Documentation

Whether this deployment runs a mirror runtime at all: with zero mirroring mounts there is no queue to build and no worker to start (NoMirroring), and the queue configuration is not even consulted, so a serve-only deployment boots with no queue variables under the shipped sqs default. With at least one mirroring mount, exactly today's queue selection applies (MirrorWith).

The one decision the composition root branches the mirror runtime on: derive whether anything mirrors from the resolved mounts, and only then consult the queue configuration (planMirrorQueue), so a serve-only deployment can never fail boot over queue variables it does not need.

Which mirror-queue backend the composition root will build, resolved from config: the durable AWS sqs backend (with its SqsConfig), or the bounded best-effort in-memory backend. The pure decision planMirrorQueue yields; the composition root pattern-matches it to make the one constructor call, and mirrorQueuePlanWarning tells it whether a boot warning is due. Selection needs no sizes: the in-memory backend's depth cap is a memory-plan tenant allocated after this choice (only the memory backend spends heap on queued jobs), so it parametrises the build (buildMirrorQueue), never the plan.

Select the mirror-queue backend from the queue URL's shape and the ambient SDK environment, yielding the MirrorQueuePlan the composition root builds the queue from, or the aggregated boot errors that block it.

This is the pure half of the queue's backend choice -- the single place that knows which backends this binary can build. There is no backend selector: the operator points ECLUSE_QUEUE__URL at a destination and the backend is derived from its shape (Ecluse.Config.QueueTarget, the queue's counterpart of the mirror-credential derivation), so a backend/URL disagreement is unrepresentable. A real SQS queue URL resolves to a SqsBackend carrying its SqsConfig, with the region parsed from the URL's own host (AWS_REGION is not consulted for it); the composition root passes that to Ecluse.Runtime.Queue.Sqs.newSqsQueue. A Pub/Sub topic resource names the GCP backend, which is recognised but not built, so it is a fail-loud QueueProviderUnavailable rather than a silent fall-through, and any other shape is a fail-loud QueueUrlUnrecognised naming the accepted forms. An absent ECLUSE_QUEUE__URL rolls over to the bounded in-memory MemoryBackend (its depth cap is allocated by the memory plan after this selection, and parametrises only the build): mirroring is demand-driven and self-healing (a job lost to a restart re-enqueues on the next demand), so the rollover degrades durability, never safety, and the composition root emits the memoryQueueBootWarning so it is never a silent surprise.

When an endpoint override is set (AWS_ENDPOINT_URL_SQS, the AWS-SDK-standard service-specific variable), it forces the SQS interpretation of the queue URL regardless of shape -- an emulator (ministack) or VPC endpoint URL matches no public shape by design -- and the ambient AWS_REGION must scope it (a missing one is the QueueRegionMissing boot error, this override being the only path that still raises it). The override is parsed into the backend's SqsEndpoint; a malformed one is a fail-loud QueueEndpointMalformed, aggregated with the region failure so one boot reports both. The generic AWS_ENDPOINT_URL is deliberately not consulted here: it is the S3 advisory client's override, and honouring it for the queue would let an S3-only override silently redirect the queue's traffic. With no override, the SQS backend uses AWS's default endpoint and credential resolution.

The loud boot warning a MirrorQueuePlan warrants before its queue is built, or Nothing for a durable backend that needs none. The composition root logs the Just at WarningS on selection, so an operator who chose the in-memory backend is told plainly that the mirror is non-durable -- never a silent surprise.

The boot warning emitted when mirroring rolls over to the in-memory queue (no ECLUSE_QUEUE__URL): it states plainly that the mirror is in-memory, non-durable, and best-effort, and that a lost job is re-mirrored on the next demand (so there is no data loss, only deferred mirroring), so the rollover is never mistaken for a durable cloud backend.

The cap-overflow drop warning for the in-memory backend, carrying the running total of dropped jobs (this report is rate-limited at the queue, so it does not fire per dropped job). A note on a one-line follow-up: a drop metric (ecluse.mirror.*, S26 PR2) hooks in alongside this log once that catalogue lands.