@owlmeans/queue 0.1.18-rc.4 → 0.1.18-rc.40

package/README.md

@@ -1,20 +1,297 @@
 # @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. Recurring work is a declared schedule: the broker produces a job on an interval or a
+cron pattern and a registered processor runs it.
 
-## 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.40
+```
+
+## 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 backend entrypoint protocol whose route uses `job()` from this
+  package (`QUEUE_PROTOCOL`). 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.
+- **Schedule**: `declareSchedule(cfg, { id, queue, name, every | pattern, … })` in the shared config.
+  Every process that listens to the queue reconciles the broker with the declared schedules when its
+  worker starts; each run is an ordinary job, and `JobContext.scheduled` names the schedule.
+
+## 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 { job } from '@owlmeans/queue'
+import { backend, 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 }] }
+  ]
+})
+```
+
+### Recurring jobs
+
+```ts
+import { declareQueue, declareSchedule } from '@owlmeans/queue'
+
+// Shared config: the queue first, then its schedules.
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile', 'app:maintenance:purge'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+declareSchedule(cfg, {
+  id: 'app-purge', queue: APP_MAINTENANCE, name: 'app:maintenance:purge', every: 15 * 60_000,
+})
+```
+
+The process that `listenQueues(cfg, APP_MAINTENANCE)` registers the processors; nothing else is
+wired. A scheduled run carries no caller and no credentials, so it goes to a processor, never to a
+guarded entrypoint:
+
+```ts
+worker.process(APP_MAINTENANCE, 'app:maintenance:reconcile', async job => {
+  for await (const page of organizations()) {
+    await job.touch()
+    await reconcile(page)              // safe to run twice: a restart re-runs the whole sweep
+  }
+  return { scheduled: job.scheduled }  // 'app-nightly-reconcile'
+})
 ```
 
-## Related Packages
+Renaming a schedule id removes the old scheduler and creates a new one; deleting a declaration
+removes its scheduler at the next worker start.
+
+### 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` |
+| `declareSchedule(cfg, schedule)` | function | Declare a recurring job after checking it; re-declaring an id replaces |
+| `schedulesOf(cfg, queue?)` | function | The declared schedules, of one queue when named |
+| `assertSchedule(cfg, schedule)`, `assertSchedules(cfg)` | function | Check one schedule, or every declared one plus duplicate ids |
+| `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`, `ScheduleDeclaration` | 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 (`scheduled` names the schedule of a scheduled run); 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`, `ScheduleMisdeclared` | 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.** Declare a schedule. `delay` defers a single job once.
+- **A schedule on a queue nothing consumes.** Only a listening worker creates the scheduler, and the
+  broker produces each next run when the previous one starts.
+- **Loading different schedule lists in two processes that listen to one queue.** Each start removes
+  the schedules its own list does not name.
+- **Declaring a schedule before its queue.** `declareSchedule` checks the queue and the job name and
+  throws `UnknownQueue` / `UnknownJobName`.
+- **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): transport-neutral route declarations used by the queue-owned `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 +301,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.48
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,10 +1,17 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/queue",
-  "version": "0.1.18-rc.0",
-  "generatedAt": "2026-08-16T22:20:50.517Z",
+  "version": "0.1.18-rc.40",
+  "generatedAt": "2026-10-05T08:32:19.092Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
+    {
+      "kind": "skill",
+      "name": "scheduled-jobs",
+      "category": "multi-package",
+      "file": "skills/scheduled-jobs/SKILL.md",
+      "canonicalPath": ".agents/skills/scheduled-jobs/SKILL.md"
+    },
     {
       "kind": "skill",
       "name": "queue",

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, recurring schedules, lifecycle hooks, and processor rules. Auto-invoked when importing queue types, declaring a job protocol, or declaring a schedule.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,24 +8,253 @@ user-invocable: false
 # @owlmeans/queue
 
 **Layer:** Infra
-**Install:** `"@owlmeans/queue": "^0.1.18-rc.0"` in `dependencies`
+**Install:** `"@owlmeans/queue": "^0.1.18-rc.40"` in `dependencies`
 
-## Key Exports
+Backend transport contracts only. It carries no broker code — a driver package
+(`@owlmeans/redis-queue`) implements them. Depend on this one from a shared backend package;
+generic common and frontend packages must not import it. 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 `QUEUE_PROTOCOL`.
+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()),
+)
+```
+
+Import `job`, `QUEUE_PROTOCOL`, `isQueueRoute` and `queueRouteOptions` from `@owlmeans/queue`.
+The generic route package deliberately knows none of the queue option shape.
+
+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).
+
+## 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.
 
-## Usage
+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.
+
+## Recurring jobs
+
+A recurring sweep is a SCHEDULE on a queue, run by a registered processor:
+
+```typescript
+declareQueue(cfg, APP_MAINTENANCE, ['app:maintenance:reconcile'], {
+  worker: { concurrency: 1, lockDuration: 60_000 }
+})
+declareSchedule(cfg, {
+  id: 'app-nightly-reconcile', queue: APP_MAINTENANCE, name: 'app:maintenance:reconcile',
+  pattern: '17 3 * * *', tz: 'UTC', data: {},
+})
+```
+
+- **Declare it in the shared package, after its queue.** `declareSchedule` runs `assertSchedule`
+  first: the queue must be declared (`UnknownQueue`) and must accept the job name
+  (`UnknownJobName`), exactly one of `every` (a positive integer of milliseconds) and `pattern`
+  (cron), `tz` and `immediately` only with a pattern, never `immediately` with `startDate`, and
+  `opts.id` / `opts.delay` refused — the broker names and places every run
+  (`ScheduleMisdeclared`, message `<id>:<reason>`). Re-declaring an id replaces it.
+- **The id is the identity.** Changing any other field updates the schedule in place; renaming the
+  id is one schedule removed and another created.
+- **Every process that listens to the queue reconciles it at worker start** — the driver creates
+  and updates what is declared and removes the schedules it owns that are not. Two listeners of one
+  queue must therefore load the same schedule list, which is why it lives in the shared package.
+  A producer creates nothing.
+- **A scheduled run is a processor job, never a guarded entrypoint.** Nobody's credentials travel
+  with it. `job.scheduled` carries the schedule id; it is absent on a job enqueued any other way.
+- **It needs a consumer.** The broker produces the next run when the previous one starts
+  processing, so a schedule on a queue nothing consumes stops producing.
+- **The processor obeys every rule above** — `touch()` through the sweep, and safe to run twice,
+  because a restart mid-sweep re-runs it from the start.
+
+`schedulesOf(cfg, queue?)` reads the declarations back; `assertSchedules(cfg)` checks all of them,
+including one written into `cfg.queue.schedules` directly, and refuses a duplicate id.
+Which recurring work belongs on a schedule at all is `scheduled-jobs`.
+
+## 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 |
+| `declareSchedule` / `schedulesOf` / `assertSchedule` / `assertSchedules` | Recurring jobs — declare, read back, check |
+| `queueOf` / `queueOfJob` / `isListening` | Reading it back; `queueOf` throws `UnknownQueue` |
+| `QueueConfig` / `QueueDeclaration` / `QueueWorkerOptions` / `JobOptions` / `ScheduleDeclaration` | 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`, `scheduled?`, `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`, `ScheduleMisdeclared` |
+| 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` — the generic declaration model that `QUEUE_PROTOCOL` and `job()` extend
+- `@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; how schedules are reconciled; integration tests live there
+- `scheduled-jobs` — when recurring work is a schedule, and how to write the sweep it runs
+- `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