Documentation

The runtime backends the mirror worker is closed over: exactly the effectful capabilities the consume loop needs to poll, fetch, verify, publish, and record. A record of concrete handles and abstract ports (the Handle pattern), assembled by the composition root (workerRuntimeOf) and read by the loop through the WorkerM reader.

The mirror queue is the demand-driven hand-off the loop consumes; the untrusted data-plane manager fetches the artifact bytes (the validating TLS manager, over an https-only dist.tarball); the heartbeat is the loop's liveness surface. The mirror write is not a runtime slot: it rides each ecosystem's bundle (wpPublish), so every job publishes through its own ecosystem's married capability. The metric and tracing ports are the abstract recording interfaces (Ecluse.Core.Telemetry.Record, Ecluse.Core.Telemetry.Span); the application supplies their OpenTelemetry-backed implementations, so the loop records without naming a telemetry backend. There is no log field: the loop logs through the ambient katip context the entry point establishes.

The per-ecosystem bundle the worker dispatches every job through: a resolver that fetches and projects the single version's metadata, the prepared rule set, the integrity floor, the tarball-host gate, the artifact request formation, the married mirror-write capability, and the wall-clock the age rules read.

The resolver is the shared single-version fetch-and-project (fetchVersionDetails over the guarded public origin, wired by the composition root); the rules are the same prepared rules the serve path gates with; the floor and host gate are the mount's own configured policy values; and the request formation is the mount ecosystem's own (pdBuildArtifactRequestByUrl) -- so the worker's ingest decision and the serve-time decision run one codepath (admitArtifact) over one policy, and any per-source breaker state is shared, never forked. The publish capability is likewise the mount's own, so the presence probe and the mirror write speak the job ecosystem's protocol at that ecosystem's declared mirror target, never a neighbour's.

The worker's per-ecosystem re-evaluation bundles, keyed by the ecosystem a job's package belongs to (pkgEcosystem). Built once at boot and shared with the serve mounts; a job whose ecosystem is absent here is fail-closed (dropped), never mirrored unvetted.

The mirror worker's monad: a reader over the WorkerRuntime layered on katip's logging context.

A newtype over ReaderT WorkerRuntime (KatipContextT IO) so its instances are this module's to control and call sites name one concrete monad. The derived instances give reader access to the runtime (MonadReader WorkerRuntime), arbitrary effects (MonadIO), the unlift capability (MonadUnliftIO) the loop's tryAny and the per-job span bracket need, and the katip classes (Katip, KatipContext) so a structured log call composes through the ambient context the entry point establishes.

The katip base is a reader, never a StateT, so the logging context behaves correctly across the loop (see docs/architecture/technology-stack.md → "Key Decisions").

Run a WorkerM against the WorkerRuntime and the katip logging environment and initial context the entry point supplies, yielding the underlying IO action. This is the boundary where the worker's WorkerM code is discharged to IO.

The LogEnv (the structured-log scribes) and the initial context payload are passed in rather than read from the runtime, so the application owns the log stream and the trace-correlation dd enrichment: it resolves the dd identity and hands it here as the initial context, so every line the loop emits carries dd. The loop narrows the namespace with katip's combinators on top as it logs.

Advance the worker heartbeat to the current instant, recording a unit of demonstrated progress. The consume loop (workerLoop) calls it after every successful poll (an empty long-poll is a healthy idle) and processBatch calls it after every completed job, so the /livez staleness bound (workerHeartbeatStaleAfter) covers a single job's worst case rather than a whole sequential batch of them. This is the one place the beat is taken, so the two call sites cannot drift.