The mirror-queue handle -- a record of functions over a backend whose private state the closures capture. See the module header for the enqueue / don't-ack-to-retry / no-nack conventions; all fields are IO.

A mirror job: everything the worker needs to back-fill one artifact into the mirror target. The version was already gated by the rules at serve time (when the job was enqueued), so the worker does not re-run the rules; it fetches the bytes, verifies them against the serve-time-admitted integrity digest the job carries, and publishes.

The integrity digest and the artifact descriptor are captured at enqueue time (jobArtifact), not re-fetched: the worker mirrors exactly what the rules admitted, so an upstream packument mutated in the enqueue → process window cannot substitute a different artifact for the one that was gated. The descriptor also carries the filename and declared size the worker needs to assemble the publish document.

The serve-time-admitted artifact descriptor carried on a MirrorJob: exactly the fields the worker needs to verify the fetched bytes and assemble the publish document, captured when the version was gated.

maHashes is a NonEmpty because the serve path admits a public version only when it carries at least one integrity digest (the integrity-presence admission policy), so a job with no digest to verify against is unrepresentable -- the worker always has a fingerprint to check the bytes against before they reach the private upstream.

A serialised W3C trace-context carrier riding on a MirrorJob: the traceparent (and any tracestate) of the span that enqueued the job, in the standard wire encoding. It is captured at enqueue time and read back by the worker's tracing port to re-establish a span link from the per-job span to the enqueueing request, so the asynchronous mirror hand-off is navigable in a trace.

The two fields are the W3C header values verbatim; the queue carries them opaquely (it neither parses nor validates them -- an unparseable carrier simply yields no link), so this type names what is carried without coupling the queue to any tracing backend.

A received message: the MirrorJob to process together with the ReceiptHandle used to ack it (or extendVisibility on it) once processed.

An opaque handle identifying a received message for ack / extendVisibility. It carries the backend's own delivery token -- an SQS receipt handle or a Pub/Sub ackId -- as text; the constructor is hidden so neither provider's representation leaks into worker code, and a handle is only ever obtained from a QueueMessage returned by receive. Build one (in a backend) with mkReceiptHandle and read the token back with unReceiptHandle.

Wrap a backend's delivery token (an SQS receipt handle, a Pub/Sub ackId) as an opaque ReceiptHandle. For backend implementations only -- worker code obtains handles from receive, never builds them.

Recover the backend's delivery token from a ReceiptHandle, to pass back to the backend on ack / extendVisibility. For backend implementations only.

A duration in whole seconds, for extendVisibility. A 'newtype' so a raw Int of seconds is never confused with some other count.

Build a fresh STM-backed in-memory MirrorQueue.

Honours the handle's contract: enqueue appends (FIFO), receive delivers all currently-visible jobs and moves them in-flight, ack removes an in-flight job, and an in-flight job that is never acked is redelivered on the next receive ("retry is don't ack"). extendVisibility holds a job in-flight across one such redelivery pass. This is a test double -- there is no long-poll blocking; an empty receive returns [] at once.

What the bounded in-memory backend needs: its depth cap and its idle-poll window. A record (like SqsConfig) so each knob is named rather than a bare Int; build it with defaultMemoryQueueConfig for the production poll window.

A MemoryQueueConfig for a given depth cap with the idle-poll window at its production default -- 20s, mirroring the SQS long-poll cadence (defaultSqsConfig) and comfortably under the worker's 120s heartbeat-staleness budget (workerHeartbeatStaleAfter), so an idle receive returns a healthy empty poll long before /livez would flag the loop stalled. The depth cap stays the operator-tunable knob; the poll window is a fixed cadence, exposed on the record only so a test can shorten it.

Build a bounded, best-effort in-memory MirrorQueue -- the production backend behind ECLUSE_QUEUE_BACKEND=memory, a TBQueue shared between the serve path's enqueue and the worker's receive.

It is correctness-safe despite being lossy: mirroring is a demand-driven optimization over the always-available public upstream, so a job lost to the cap or to process teardown just means the package is served from public again and re-enqueued on the next pull -- a deferred performance win, never a correctness loss. That admits two deliberate departures from the cloud backends' contract:

• Bounded, drop-newest on overflow. The queue holds at most memQueueMaxDepth jobs; an enqueue that would exceed the cap is rejected (the newest job is dropped) rather than growing memory without bound -- the load-bearing constraint, since a cold-cache npm ci enqueues thousands of jobs at once. enqueue never throws (it runs on the serve hot path), and each report-worthy drop invokes the injected drop callback with the running drop count, rate-limited by memoryQueueDropReportInterval so a flood does not spam.
• No redelivery; ack / extendVisibility are no-ops. Unlike the cloud backends (and newInMemoryQueue), there is no visibility-timeout in-flight tracking: a receive removes a job for good. A job whose processing fails is therefore not redelivered -- it is simply re-enqueued on the next demand. This bounds memory hardest (nothing is retained after delivery) and is admissible precisely because a lost job is safe.

receive is a bounded long-poll: it waits up to memQueuePollWaitMicros for a job, then drains up to memoryQueueBatchSize without blocking, or returns [] when the window lapses -- the in-process analogue of the cloud long-poll. The bound is load-bearing: the worker advances its liveness heartbeat only when receive returns (an empty poll is a healthy idle), so an idle receive that blocked forever would let the heartbeat go stale and /livez flag the loop stalled. The wait is the timeout-over-atomically idiom rather than registerDelay so it works on the non-threaded RTS too; an interrupted poll aborts the STM transaction, consuming nothing.

The most jobs one receive delivers from the bounded in-memory backend. Held at the SQS batch cap so the worker -- which processes a batch sequentially and advances its liveness heartbeat once per poll -- sees the same bounded batch shape regardless of backend, rather than one poll returning a whole cold-cache burst and starving the heartbeat past its staleness window.

How many cap-overflow drops the bounded in-memory backend absorbs between warning reports. The first drop is always reported, then every multiple of this, so a sustained flood logs at most about one line per this many drops rather than one per dropped job.

Wrap a bounded producer-side hand-off buffer in front of a queue, so the serve path's enqueue is an in-process STM write (microseconds) no matter how slow the backend's own producer call is.

The motivating case is the SQS backend: its enqueue is an HTTP round trip (SendMessage), and the serve path runs the mirror enqueue after the response body has been sent but before the handler returns -- so on a keep-alive connection those milliseconds hold the connection's turn and tax the next request on it. Buffered, the handler hands the job off and returns; the returned drain loop -- which the composition root runs alongside the server -- delivers buffered jobs to the backend at the backend's own pace. The consumer fields (receive, ack, extendVisibility) pass through untouched.

Loss stays safe, so the buffer keeps the handle's best-effort producer contract (mirroring is demand-driven: a lost job is re-enqueued on the next demand for its artifact -- the same argument newBoundedInMemoryQueue makes):

• Drop-newest on overflow. A hand-off finding the buffer full drops the job and invokes onDrop with the running drop total. The callback fires on every drop (metric-grade); the caller owns any log rate-limiting.
• A backend failure inside the drain loop invokes onDeliveryFailure with the running failure total and the failure's detail, and the loop moves on to the next job; the failed job is not redelivered here.
• Cancellation loses the buffer. The drain loop never returns, so the composition root races it against the services; shutdown cancels it and any still-buffered jobs are dropped -- the same safe loss.

The wrapped enqueue never throws.