@owlmeans/queue 0.1.18-rc.2 → 0.1.18-rc.20

package/README.md

@@ -1,20 +1,249 @@
 # @owlmeans/queue
 
-Reserved namespace for queue management. Currently a stub with no exports.
+Job queues as resources, plus the route protocol that makes a queued call look like any other call.
+Use it when work must outlive the request. Three cases qualify: the user would otherwise wait more
+than about five seconds, accepted work must survive a process restart, or the work is retried
+against a third party (payment capture, provider sync, bulk mail, report generation, model
+pipelines). A request that finishes in under about two seconds and makes no external call should
+not queue: do it inline. Check for a smaller fix first, such as an index, a batch write or a cached
+aggregate. The framework has no scheduler, so recurring work is triggered by a platform cron that
+calls an entrypoint or enqueues a job.
 
-## Overview
-
-This package is a placeholder for future queue/task processing functionality within the OwlMeans framework.
+This package is contracts only and carries no broker code. A driver implements them
+(`@owlmeans/redis-queue` does, over BullMQ). Depend on this package from a shared contract package,
+and on the driver only where the application wires itself up.
 
 ## Installation
 
 ```bash
-bun add @owlmeans/queue
+bun add @owlmeans/queue@^0.1.18-rc.19
+```
+
+## Concepts
+
+- **Queue declaration**: `declareQueue(cfg, name, jobs, opts?)` in the shared backend config. It
+  names a queue, the job names it accepts, and its worker and default job options. It is an
+  address, not a deployment.
+- **Listen**: `listenQueues(cfg, ...names)` in one process's own config says which queues *that
+  process* consumes. A process that listens to nothing is a producer only.
+- **Queued protocol**: an immutable entrypoint protocol whose route uses `job()` instead of
+  `backend()` (`RouteProtocols.QUEUE`). Callers use `ctx.entrypoint(protocol).call(...)` unchanged,
+  and the QUEUE transport carries the call through the broker.
+- **Job record**: `ctx.jobs(queue)` returns a `QueueResource`, the ordinary `Resource<JobRecord>`
+  contract plus `wait`, `flow`, `counts` and `close`. `create` enqueues, `list` inspects and `take`
+  cancels.
+- **Processor**: a function registered with `QueueWorkerService.process(queue, name, fn)` that gets
+  a `JobContext`. It must be safe to run twice and must `touch()` in long loops.
+- **Single-flight id**: a `JobOptions.id` derived from what the job is about (`develop:<storyId>`).
+  A duplicate enqueue then returns the existing job instead of a second one.
+
+## Usage
+
+### Declare queues in the shared backend config
+
+```ts
+import { declareQueue } from '@owlmeans/queue'
+
+// Split lanes by how long work takes, not by topic: a one-second read queued behind
+// a thirty-minute job is a UI that looks broken.
+declareQueue(cfg, APP_OPS, [appProtocols.files.get.alias, appProtocols.report.build.alias], {
+  worker: { concurrency: 16, lockDuration: 30_000 }
+})
+
+declareQueue(cfg, APP_BILLING, [appProtocols.invoice.capture.alias], {
+  worker: { concurrency: 4, lockDuration: 30_000 },
+  defaults: { attempts: 3, backoff: { type: 'exponential', delay: 250 } }
+})
+```
+
+The worker process names what it consumes, in its own config:
+
+```ts
+import { listenQueues } from '@owlmeans/queue'
+
+listenQueues(cfg, APP_OPS, APP_BILLING)   // the api process omits this and only produces
+```
+
+Both processes build their context through the same backend factory, which wires the driver once:
+
+```ts
+import { appendRedisQueue } from '@owlmeans/redis-queue'
+
+appendRedis<C, T>(context)
+appendRedisQueue(context, { hooks: billingQueueHooks(context) })
+```
+
+### Declare a queued entrypoint
+
+```ts
+import { contract, protocol, typed } from '@owlmeans/entrypoint'
+import { backend, job, route } from '@owlmeans/route'
+
+const aliases = { base: 'app:report', build: 'app:report:build' } as const
+const reportBase = protocol(route(aliases.base, '/reports', backend({ service: APP_WORKER })), contract())
+
+export const appProtocols = {
+  report: {
+    base: reportBase,
+    build: protocol(
+      route(aliases.build, '/:id/build',
+        job({ parent: reportBase, service: APP_WORKER, queue: APP_OPS, timeout: 30_000 })),
+      contract.request({ params: typed<ReportParams>(ReportParamsSchema) }, typed<ReportResult>()),
+    ),
+  },
+} as const
+```
+
+The worker process serves it like any backend entrypoint; the HTTP server skips QUEUE routes. A
+producer calls it with no knowledge of the broker:
+
+```ts
+const result = await context.entrypoint(appProtocols.report.build).call({ params: { id } })
+```
+
+Add `reply: false` to the `job()` options to resolve `Accepted` with `{ id, queue }` as soon as the
+broker has taken the job.
+
+### Enqueue with broker options and wait
+
+When a producer needs a job id, a delay or retries, pass the same protocol object to the typed
+helpers. Never pass its alias.
+
+```ts
+import { enqueueProtocol, waitForProtocol } from '@owlmeans/queue'
+
+const queued = await enqueueProtocol(context, appProtocols.invoice.capture, {
+  body: { invoiceId },
+}, {
+  id: `capture:${invoiceId}:${attemptSequence}`,   // derived from what the job is about
+  delay: 250, attempts: 3, backoff: { type: 'exponential', delay: 250 },
+})
+
+const receipt = await waitForProtocol(context, appProtocols.invoice.capture, queued, { timeout: 120_000 })
+```
+
+`queueJobOf(req)` gives a protocol handler `{ id, name, queue, attempt, touch }` when it must compare
+the broker job with a claim it persisted.
+
+### Processors, hooks and job graphs
+
+```ts
+import { DEFAULT_ALIAS } from '@owlmeans/queue'
+import type { QueueWorkerService } from '@owlmeans/queue'
+
+const worker = context.service<QueueWorkerService>(DEFAULT_ALIAS)
+
+worker.process(APP_OPS, 'app:import:rows', async job => {
+  for (const chunk of chunks(job.data.fileId)) {
+    await job.touch()                     // renew the lock on every iteration
+    await importChunk(chunk)              // idempotent: skips rows already imported
+  }
+  return { ok: true }
+})
+
+worker.hooks({
+  onJobDead: async (record, reason) => {  // retries exhausted: compensate
+    await imports.patch({ id: record.data.importId, status: 'failed', error: reason })
+  }
+})
+
+// children complete before the parent; siblings run in parallel
+await context.jobs(APP_OPS).flow({
+  name: 'app:import:finalize', data: ref, children: [
+    { name: 'app:import:validate', data: ref, children: [{ name: 'app:import:rows', data: ref }] }
+  ]
+})
 ```
 
-## Related Packages
+### Jobs are records
+
+```ts
+import { JobState } from '@owlmeans/queue'
+
+const jobs = context.jobs<ImportInput, ImportResult>(APP_OPS)
+
+const failed = await jobs.list({ state: JobState.Failed }, { size: 20 })
+const counts = await jobs.counts()
+await jobs.take(jobId)                    // cancel and return
+```
+
+## Processor rules
+
+- **`touch()` in every long loop.** The broker judges liveness by the lock. Silence longer than
+  `lockDuration` looks like a dead worker, so the job is re-run elsewhere while this one is still
+  going.
+- **Children report, parents decide.** A child returns `{ ok: false, error }` for a domain failure.
+  Throwing means "infrastructure broke, retry me". Parents read `children()` / `failedChildren()`.
+- **Retries default to one attempt** (`DEFAULT_ATTEMPTS`), because a blind retry of model work
+  re-spends the tokens that just failed. Raise `attempts` per queue for cheap idempotent work.
+- **`job.signal` is not an interrupt.** An orderly stop closes workers first and waits for jobs in
+  flight to return.
+
+## Guards and errors
+
+`handleJob` rebuilds the request from the envelope and runs the entrypoint's guards the way the
+HTTP boundary does, attaching the entity. A guarded queued entrypoint therefore needs the
+producer's credentials in the envelope `headers`. `cfg.queue.envelopeTtl` (seconds) bounds how long
+after `enqueuedAt` an envelope is still accepted; past it, the job answers `EnvelopeExpired`.
+
+A refusal the caller must recognise is carried in the reply and rebuilt on the producing side as its
+own class, so `instanceof` keeps working across the broker. `QueueTimeout` means the WAIT ended,
+not the job, so read the job back to learn what became of it.
+
+## API
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `declareQueue(cfg, name, jobs, opts?)` | function | Declare a queue and the job names it accepts; re-declaring replaces |
+| `listenQueues(cfg, ...names)` | function | Name the queues this process consumes |
+| `queueOf(cfg, name)`, `queueOfJob(cfg, job)`, `isListening(cfg, name)` | function | Read declarations back; `queueOf` throws `UnknownQueue` |
+| `enqueueProtocol(ctx, protocol, request, options?)` | function | Enqueue a QUEUE protocol with `JobOptions`, typed by the protocol |
+| `waitForProtocol(ctx, protocol, job, { timeout }?)` | function | Wait for that job and unwrap the typed reply |
+| `queueJobOf(request)` | function | `QueueJobMeta` of the broker job behind a handler's request, or `null` |
+| `appendQueueTransport(ctx, alias?)`, `makeQueueTransport(alias?)` | function | Register the QUEUE transport so `call()` routes through the broker |
+| `queueWorkerMiddleware(alias?)` | function | Start the worker at the Ready stage, only in a process that listens |
+| `handleJob(ctx, job)`, `entrypointProcessor(ctx)`, `servedJobs(ctx)` | function | The bridge a driver dispatches entrypoint jobs through |
+| `requestOf(envelope)`, `assertFresh(envelope, ttl?)` | function | Rebuild a request from an envelope; enforce `envelopeTtl` |
+| `QueueConfig`, `QueueDeclaration`, `QueueWorkerOptions`, `JobOptions` | type | Configuration shapes |
+| `QueueResource<D, R>` | type | A queue as a resource, plus `queue`, `wait`, `flow`, `counts`, `close` |
+| `JobRecord<D, R>`, `JobEvent<R>`, `FlowSpec<D>` | type | A job as a record, a lifecycle event, a graph node |
+| `QueueWorkerService` | type | `process`, `start`, `stop`, `listening`, `hooks` |
+| `JobContext<D>`, `JobProcessor<D, R>` | type | What a processor receives; the processor signature |
+| `QueueHooks` | type | `wrapHandler`, `onJobResult`, `onJobStalled`, `onJobDead` |
+| `QueueJobMeta`, `JobEnvelope`, `JobReply<T>` | type | Broker identity for a handler, the call envelope, the reply shape |
+| `QueueAppend`, `QueueDriver` | type | The `ctx.jobs(queue?)` mixin a driver installs; what a driver supplies |
+| `Config`, `Context`, `QueueTransportRequest`, `QueueTransportResponse` | type | Context, config and transport types |
+| `JobState`, `JobEventType` | enum | Job lifecycle states and event types |
+| `isSettled(state?)` | function | Whether a state is final |
+| `DEFAULT_ALIAS`, `DEFAULT_JOB_TIMEOUT`, `DEFAULT_ATTEMPTS` | const | `'queue'`, `60_000` ms, `1` |
+| `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired` | class | Error family |
+
+## Common pitfalls
+
+- **Queueing work the request could finish.** It adds a second process to deploy and a place to fail.
+- **Passing alias strings to `enqueueProtocol`/`waitForProtocol`.** They take the protocol object and
+  reject strings and non-QUEUE declarations.
+- **Enqueueing a job name the queue did not declare.** It throws `UnknownJobName` rather than
+  parking a job nothing can process.
+- **Registering a processor in a process that does not `listen`.** It throws `QueueNotListening`.
+- **Putting `listen` in the shared declaration.** Every deployment of that binary would then
+  consume everything.
+- **Random job ids on an admission step.** Derive the id from the subject, or a retried request
+  enqueues twice.
+- **Long loops without `touch()`**, or processors that are not safe to run twice.
+- **Throwing from a child for a domain failure.** Return `{ ok: false, error }` instead.
+- **Equal child ids across queues in one flow.** `children()` is keyed by bare id and collapses them.
+- **A self-re-enqueueing job as a cron.** Use a platform `CronJob`. `delay` defers a single job once.
+- **Calling `ctx.jobs()` with no name once a second queue exists.** It throws `UnknownQueue`.
+
+## Related packages
 
-- [`@owlmeans/redis-resource`](../redis-resource) — Redis Streams provide queue-like semantics today
+- [`@owlmeans/redis-queue`](../redis-queue): the BullMQ driver, and where queue integration tests live
+- [`@owlmeans/route`](../route): `RouteProtocols.QUEUE` and the `job()` builder
+- [`@owlmeans/entrypoint`](../entrypoint): protocol declarations and the transport seam
+- [`@owlmeans/resource`](../resource): the `Resource` contract jobs are read through
+- [`@owlmeans/server-job`](../server-job) / [`@owlmeans/client-job`](../client-job): listing,
+  cancelling and following jobs from an application's UI
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -24,7 +253,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills
+npx @owlmeans/agent-skills@^0.1.18-rc.23
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/queue",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.517Z",
+  "version": "0.1.18-rc.20",
+  "generatedAt": "2026-09-15T12:50:32.652Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/queue/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: queue
-description: How to use @owlmeans/queue — abstract job-queue interface (currently a stub) to be implemented by transport-specific queue services. Auto-invoked when importing queue types.
+description: How to use @owlmeans/queue — protocol-object enqueue/wait, job queues as resources, QUEUE declarations, producer/consumer split, single-flight job ids, lifecycle hooks, and processor rules. Auto-invoked when importing queue types or declaring a job protocol.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,24 +8,210 @@ user-invocable: false
 # @owlmeans/queue
 
 **Layer:** Infra
-**Install:** `"@owlmeans/queue": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/queue": "^0.1.18-rc.20"` in `dependencies`
 
-## Key Exports
+Contracts only. It carries no broker code — a driver package (`@owlmeans/redis-queue`) implements
+them. Depend on this one from a shared contract package; depend on the driver only where the
+application wires itself up.
 
-This package is currently a stub that defines the queue interface. Concrete implementations (Redis BullMQ, RabbitMQ, etc.) will register a service that satisfies this interface.
+## The one idea
 
-| Export | Description |
-|--------|-------------|
-| Queue types (placeholder) | Abstract queue interface |
+A queued call is an immutable entrypoint protocol whose route names `RouteProtocols.QUEUE`.
+Ordinary calls use `ctx.entrypoint(protocol).call(request)`. Code that needs broker options or a
+job handle uses `enqueueProtocol(ctx, protocol, request, options)` and
+`waitForProtocol(ctx, protocol, job)`. Both derive queue and job name from the protocol object and
+preserve its exact request/reply pair; raw strings and non-QUEUE declarations are rejected.
+
+That is what makes it worth having: moving a service-to-service call onto the broker is a change
+to a declaration, not to the places that call it, and the broker holds the work across a restart of
+either side — which an in-process call cannot.
+
+## Declaring
+
+Queues and the jobs they accept live in the SHARED backend package, so producers and consumers
+read one list:
+
+```typescript
+declareQueue(cfg, AGENT_WORK, [story.develop.alias], {
+  worker: { concurrency: 3, lockDuration: 60_000 }
+})
+```
+
+The job list is enforced, not documentation: enqueueing a name the queue does not declare throws
+`UnknownJobName` instead of parking a job nothing can ever process. Re-declaring a name replaces,
+so a helper that runs once per composed app is safe to call twice.
+
+Which queues a process CONSUMES is separate, and lives in that process's own config:
+
+```typescript
+listenQueues(cfg, AGENT_WORK, AGENT_OPS)   // absent ⇒ producer only
+```
+
+Keep them apart. A declaration is an address; `listen` is a deployment fact. If a worker bound
+whatever it could serve, every deployment of the same binary would consume everything it imports.
+
+A queued entrypoint is an immutable protocol with `job()` in place of `backend()`:
+
+```typescript
+protocol(
+  route(agent.story.develop, '/:id/develop',
+    job({ parent: agent.story.base, service: AGENT, queue: AGENT_WORK, timeout: 30_000 })),
+  contract.request({ params: typed<StoryParams>(StoryParamsSchema) }, typed()),
+)
+```
+
+The alias appears in `declareQueue(...jobs)` only because the broker is a string-keyed adapter.
+Application producers and handlers keep the protocol object.
+
+When an admission record owns single flight, select the job id atomically first, then enqueue it:
+
+```typescript
+const queued = await enqueueProtocol(context, tokenBalance.reconcile, {
+  body: { projectionId },
+}, { id: claimId, delay: 250, attempts: 3, backoff: { type: 'exponential', delay: 250 } })
+const result = await waitForProtocol(context, tokenBalance.reconcile, queued)
+```
+
+Per-call `id`, delay, attempts, backoff and retention belong here; putting them into an alias-based
+helper forfeits protocol inference. `queueJobOf(request)` exposes `{ id, name, queue, attempt }` to
+the rare protocol handler that must compare a broker job with its persisted claim.
+
+`reply: false` makes it fire-and-forget: the call resolves `Accepted` with `{ id, queue }` as soon
+as the BROKER has accepted the enqueue — before any worker has picked the job up, so the resolution
+says the job exists and nothing about it having started. That is what a long pipeline wants; watch
+the job by its id for anything further. The default is to wait for the value, for
+`req.timeout ?? route.timeout ?? DEFAULT_JOB_TIMEOUT` (60 s).
 
-## Usage
+## Jobs are records
+
+`ctx.jobs<D, R>(queue)` returns a `QueueResource<D, R>` — a `Resource<JobRecord<D, R>>` plus
+pub/sub. So inspecting a queue is the resource contract you already know: `create` enqueues,
+`get`/`load`/`list`/`count` inspect, `delete`/`take` cancel, `purge` bulk-cancels. Only what the
+base contract cannot express is added: `wait(id, { timeout })`, `flow(root)`, `counts()`, and
+`close()` for the connections a producer that waited holds.
+
+Called with no queue name it answers the SOLE declared queue and throws `UnknownQueue` once there
+are two — an application that grows a second queue is told to name one rather than quietly served
+the wrong backlog. A queue nothing declared throws the same error at the call site.
+
+Give `JobOptions.id` a value derived from what the job is ABOUT (`develop:<storyId>`) and a
+duplicate enqueue becomes a no-op returning the job already there — no `RecordExists`. That is
+what makes an admission step safe to retry.
+
+## Writing a processor
 
 ```typescript
-// Reserve the alias for your queue implementation
-import type { Queue } from '@owlmeans/queue'
-const queue = ctx.service<Queue>('queue')
+const worker = context.service<QueueWorkerService>(DEFAULT_ALIAS)
+
+worker.process(AGENT_WORK, 'agent:story:code', async job => {
+  for (const screen of screens) {
+    await job.touch()        // ← not optional
+    await develop(screen)
+  }
+  return { ok: true }
+})
 ```
 
+Registering against a queue this process does not `listen` to throws `QueueNotListening` — the
+question is a deployment one, so it is answered at wiring time rather than when a job arrives.
+
+Three rules, each of which has a failure mode attached:
+
+- **`touch()` in every long loop.** The broker judges liveness by the lock. Silence for longer
+  than `lockDuration` is indistinguishable from a dead worker, so the job is handed to someone
+  else while this one is still working — you get two runs, not one. `progress(value)` reports
+  without renewing, and the value must be JSON-carryable.
+- **Children report, parents decide.** A child returns `{ ok: false, error }` for a DOMAIN
+  failure; it does not throw. Throwing means "infrastructure broke, retry me". A child that
+  exhausts its attempts does not fail its parent: the parent runs and reads `children()` /
+  `failedChildren()` — both keyed by bare job id — and decides. Give the children of a flow that
+  spans queues distinct ids, because that re-keying collapses two ids that are equal across queues.
+- **Retries default to one attempt** (`DEFAULT_ATTEMPTS`). These jobs mostly talk to a model, and
+  a blind retry re-spends the tokens that just failed. Raise `attempts` per queue only where jobs
+  are cheap and idempotent.
+
+`job.signal` is the queue's abort signal, and it is NOT an interrupt. The driver stops by closing
+every worker first — which waits for the jobs in flight to return — and aborts only afterwards, so
+a processor cannot bail out on it and does not need to. An orderly stop drains; an outright kill is
+covered by the rule below.
+
+## Being restartable
+
+A worker can die mid-job; the lock expires and the step re-runs. So a processor has to be safe to
+run twice — skip work already recorded, delete the rows a previous attempt created, or accept
+regenerating over a baseline. Decide this per job and say so in a comment; there is no way to make
+it automatic.
+
+## A queued call is still a guarded call
+
+`handleJob` rebuilds the request from the envelope and runs the entrypoint as the HTTP boundary
+would: the declared guards are tried in order, the first that matches authorizes, the entity is
+attached, and only then does the handler run. A queued entrypoint with guards therefore needs the
+producer's credentials on the envelope's `headers`, and an unauthorized job answers
+`AuthorizationError`. An alias this process does not serve answers `JobNotServed` — the job was
+taken by a worker that has no handler for it.
+
+Set `cfg.queue.envelopeTtl` (seconds) to bound how long a job envelope stays acceptable. The age is
+measured from the envelope's `enqueuedAt` — when the PRODUCER enqueued it, not when a worker picked
+it up — so a captured envelope stops being replayable, and so does a job that sat behind a backlog
+longer than the window: it answers `EnvelopeExpired` at pickup rather than running late. Size the
+window against the longest backlog you are willing to let run, and leave `envelopeTtl` unset — the
+default — for a queue whose jobs may legitimately wait.
+
+## Errors cross the hop as classes
+
+A refusal the caller must recognise — `ContentRefused`, `AgentLocked` — is marshalled into the
+reply and rebuilt on the producer side as its own class, so `catch (e) { if (e instanceof ...) }`
+keeps working across the broker. Only broker- and connection-level faults propagate as throws,
+because those are the only ones a retry can fix.
+
+## What runs where
+
+`queueWorkerMiddleware()` starts the worker at the **Ready** stage — processors register while the
+application wires up, and binding earlier would take jobs the process cannot yet run. A process
+that listens to nothing registers no worker and pays nothing.
+
+`canServeModule` in `@owlmeans/server-api/utils` excludes QUEUE routes, the same way it excludes
+sockets: the worker takes those jobs off the broker, and mounting them on the HTTP server too would
+answer every call twice. `servedJobs` is the mirror image — the entrypoints this process both serves and
+listens to, grouped by queue, which is what a driver binds.
+
+## Key exports
+
+| Export | Description |
+|--------|-------------|
+| `enqueueProtocol` / `waitForProtocol` | Typed protocol-object enqueue and result wait; validates protocol kind and queue configuration. |
+| `queueJobOf(request)` / `QueueJobMeta` | Explicit broker identity boundary for a protocol handler, including `touch()` for long work. |
+| `declareQueue` / `listenQueues` | Configuration — what exists, and what this process consumes |
+| `queueOf` / `queueOfJob` / `isListening` | Reading it back; `queueOf` throws `UnknownQueue` |
+| `QueueConfig` / `QueueDeclaration` / `QueueWorkerOptions` / `JobOptions` | The configuration shapes |
+| `QueueResource<D, R>` | A queue addressed as a resource, plus `wait` / `flow` / `counts` / `close` |
+| `JobRecord<D, R>` / `JobState` / `isSettled` / `JobEvent` / `JobEventType` | The record shape and lifecycle |
+| `FlowSpec<D>` | A graph node — `name`, optional `queue`, `data`, `opts`, `children` |
+| `QueueWorkerService` | `process(queue, name, fn)`, `start`, `stop`, `listening`, `hooks` |
+| `JobContext<D>` | What a processor gets: `id`, `name`, `queue`, `attempt`, `data`, `signal`, `touch`, `progress`, `children`, `failedChildren` |
+| `QueueHooks` | `wrapHandler`, `onJobResult`, `onJobStalled`, `onJobDead` — the compensation seam |
+| `QueueAppend` | The `ctx.jobs(queue?)` mixin a driver installs; `QueueDriver` is what a driver supplies |
+| `appendQueueTransport` / `makeQueueTransport` | Binds the QUEUE protocol so `call()` routes through the broker |
+| `queueWorkerMiddleware` | Starts the worker at Ready stage |
+| `handleJob` / `servedJobs` / `entrypointProcessor` | The bridge a driver dispatches through |
+| `requestOf` / `assertFresh` / `JobEnvelope` / `JobReply` | The envelope, and rebuilding a request from it |
+| Errors | `QueueError`, `QueueTimeout`, `UnknownJob`, `UnknownJobName`, `UnknownQueue`, `QueueNotListening`, `JobNotServed`, `EnvelopeExpired` |
+| Constants | `DEFAULT_ALIAS` (`queue`), `DEFAULT_JOB_TIMEOUT` (60 000 ms), `DEFAULT_ATTEMPTS` (1) |
+
 ## Depends On
 
-- `@owlmeans/context` — service registration
+- `@owlmeans/context` — service registration and the middleware stage
+- `@owlmeans/entrypoint` — the transport seam and the served-entrypoint dispatch
+- `@owlmeans/route` — `RouteProtocols.QUEUE` and the `job()` builder
+- `@owlmeans/resource` — the `Resource` contract jobs are read through
+- `@owlmeans/auth` / `@owlmeans/auth-common` — guarding a queued call and attaching its entity
+- `@owlmeans/error` — marshalling a refusal across the hop
+
+## Related
+
+- `redis-queue` — the BullMQ driver; integration tests for queue behaviour live there
+- `server-job` / `client-job` — exposing a queue's jobs to an application's UI (list, cancel,
+  progress over a socket), without touching the contracts here
+- `entrypoint` — protocol declarations, bindings, and the transport lookup
+- `resource` — the criteria and paging semantics `list` follows

package/build/bridge.d.ts

@@ -0,0 +1,30 @@
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { BasicContext } from '@owlmeans/context';
+import type { Config, Context, JobContext, JobEnvelope, JobReply, QueueJobMeta } from './types.js';
+/**
+ * Rebuild the request the producer described. A queued call is still a call: the same guards, the
+ * same filter, the same handler run against it — only the wire is different.
+ */
+export declare const requestOf: (envelope: JobEnvelope, path: string, context?: BasicContext<any>, job?: QueueJobMeta) => AbstractRequest;
+/** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
+export declare const queueJobOf: (request: unknown) => QueueJobMeta | null;
+/**
+ * Freshness is judged from when the job was ENQUEUED, not from now.
+ *
+ * A signed envelope proves who produced it, and a replay window keeps a captured one from being
+ * useful forever. But a job can legitimately sit behind a long backlog, and judging it on pickup
+ * would reject exactly the work that a busy queue delayed — so the producer's timestamp is what
+ * the window applies to.
+ *
+ * @throws {EnvelopeExpired}
+ */
+export declare const assertFresh: (envelope: JobEnvelope, ttl?: number) => void;
+/**
+ * Run one queued entrypoint call and describe the outcome.
+ *
+ * It never throws for a DOMAIN failure — the error is marshalled into the returned reply so the
+ * producer can rebuild it as its own class, and so the broker does not count a legitimate refusal
+ * as a job to retry. Infrastructure failures are left to propagate: those are what retries are for.
+ */
+export declare const handleJob: <C extends Config, T extends Context<C>>(context: T, job: JobContext<JobEnvelope>) => Promise<JobReply>;
+//# sourceMappingURL=bridge.d.ts.map

package/build/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAkC,MAAM,sBAAsB,CAAA;AAC3F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAMrD,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAGlG;;;GAGG;AACH,eAAO,MAAM,SAAS,aACV,WAAW,QAAQ,MAAM,YAAY,YAAY,CAAC,GAAG,CAAC,QAAQ,YAAY,KACnF,eAWD,CAAA;AAEF,oGAAoG;AACpG,eAAO,MAAM,UAAU,YAAa,OAAO,KAAG,YAAY,GAAG,IAK5D,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,aAAc,WAAW,QAAQ,MAAM,KAAG,IAQjE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,WAC3D,CAAC,OAAO,UAAU,CAAC,WAAW,CAAC,KACvC,OAAO,CAAC,QAAQ,CA2DlB,CAAA"}

package/build/bridge.js

@@ -0,0 +1,108 @@
+import { EntrypointOutcome, provideResponse } from '@owlmeans/entrypoint';
+import { AuthorizationError } from '@owlmeans/auth';
+import { attachEntity } from '@owlmeans/auth-common';
+import { ResilientError } from '@owlmeans/error';
+import { EnvelopeExpired, JobNotServed } from './errors.js';
+/**
+ * Rebuild the request the producer described. A queued call is still a call: the same guards, the
+ * same filter, the same handler run against it — only the wire is different.
+ */
+export const requestOf = (envelope, path, context, job) => ({
+    alias: envelope.alias,
+    params: (envelope.params ?? {}),
+    body: envelope.body,
+    headers: (envelope.headers ?? {}),
+    query: (envelope.query ?? {}),
+    path,
+    // Handlers reach their context through `original._ctx`, which the HTTP boundary sets on the raw
+    // Fastify request. There is no raw request here, so the shape is supplied deliberately — a
+    // handler must not have to know which transport delivered it.
+    original: context != null || job != null ? { _ctx: context, _job: job } : undefined,
+});
+/** Read broker identity only where an entrypoint truly needs to bind work to an admission claim. */
+export const queueJobOf = (request) => {
+    if (request == null || typeof request !== 'object' || !('original' in request))
+        return null;
+    const original = request.original;
+    if (original == null || typeof original !== 'object' || !('_job' in original))
+        return null;
+    return original._job ?? null;
+};
+/**
+ * Freshness is judged from when the job was ENQUEUED, not from now.
+ *
+ * A signed envelope proves who produced it, and a replay window keeps a captured one from being
+ * useful forever. But a job can legitimately sit behind a long backlog, and judging it on pickup
+ * would reject exactly the work that a busy queue delayed — so the producer's timestamp is what
+ * the window applies to.
+ *
+ * @throws {EnvelopeExpired}
+ */
+export const assertFresh = (envelope, ttl) => {
+    if (ttl == null || envelope.enqueuedAt == null) {
+        return;
+    }
+    const age = (Date.now() - new Date(envelope.enqueuedAt).getTime()) / 1000;
+    if (age > ttl) {
+        throw new EnvelopeExpired(`${envelope.alias}: ${Math.round(age)}s > ${ttl}s`);
+    }
+};
+/**
+ * Run one queued entrypoint call and describe the outcome.
+ *
+ * It never throws for a DOMAIN failure — the error is marshalled into the returned reply so the
+ * producer can rebuild it as its own class, and so the broker does not count a legitimate refusal
+ * as a job to retry. Infrastructure failures are left to propagate: those are what retries are for.
+ */
+export const handleJob = async (context, job) => {
+    const envelope = job.data;
+    try {
+        assertFresh(envelope, context.cfg.queue?.envelopeTtl);
+        const entrypoint = context.entrypoint(envelope.alias);
+        if (entrypoint.handle == null) {
+            throw new JobNotServed(envelope.alias);
+        }
+        const request = requestOf(envelope, entrypoint.path(), context, {
+            id: job.id, name: job.name, queue: job.queue, attempt: job.attempt, touch: job.touch,
+        });
+        const response = provideResponse();
+        const guards = entrypoint.getGuards();
+        if (guards.length > 0) {
+            let matched;
+            for (const alias of guards) {
+                const guard = context.service(alias);
+                if (await guard.match(request, response)) {
+                    matched = guard;
+                    break;
+                }
+            }
+            if (matched == null) {
+                throw new AuthorizationError(`queue:${envelope.alias}`);
+            }
+            const auth = provideResponse();
+            if (!await matched.handle(request, auth)) {
+                throw new AuthorizationError(`queue:${envelope.alias}:${matched.alias}`);
+            }
+            request.auth = auth.value;
+            const entity = await attachEntity(context, request);
+            if (entity != null) {
+                request.entity = entity;
+            }
+        }
+        await entrypoint.handle(request, response);
+        if (response.error != null) {
+            return { error: ResilientError.marshal(response.error).message };
+        }
+        return { value: response.value, outcome: response.outcome ?? EntrypointOutcome.Ok };
+    }
+    catch (e) {
+        // A refusal the caller must see as its own class — `ContentRefused`, `AgentLocked` — travels
+        // in the reply. Only a broker- or connection-level fault should ever reach the retry logic:
+        // retrying a refusal just spends the work again to be refused identically.
+        if (e instanceof ResilientError) {
+            return { error: ResilientError.marshal(e).message };
+        }
+        throw e;
+    }
+};
+//# sourceMappingURL=bridge.js.map

package/build/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"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"}