@ultimat3/jobs 23.0.0 → 25.0.0

package/CLAUDE.md

@@ -8,7 +8,8 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   `expectedQueryLoop` ONLY: `steps.ts` declares the per-step write one-per-step to the N+1
   detector there, and no client is ever taken from it. Never `http`, `render`, `ui`.
 - Consumers: `action` (`<job>.enqueue`, via the ambient jobs facade), `cli`, `mcp`, `admin`.
-- External deps: none. Postgres access goes through the injected `PgExecutor`.
+- External deps: none. Postgres access goes through the injected `PgExecutor` (`@ultimat3/core`'s,
+  re-exported from `index.ts`).
 
 ## Rules — registration and declarations
 
@@ -29,7 +30,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **JOBS DECLARE THEIR TENANT, and `executeJob` INSTALLS the context — do not re-litigate.**
   `tenant` is REQUIRED (`(input) => input.orgId` or `'none'`; `X_JOB_TENANT_REQUIRED` backstop).
   `executeJob` puts the derived org on the ctx's actor (`jobRunActor`, org only) and runs the body in
-  `runWithContext`; `'none'` STRIPS the org (fail-closed). A boot-supplied service actor was rejected.
+  `runWithContext`; `'none'` STRIPS the org (fail-closed).
   `tenantFor` is a METHOD on `JobHandle` (variance). The queue row's `tenantId` stays the ENQUEUER's
   (the limiter's bucket). `tenancy-cross-surface.test.ts` asserts HTTP and job verdicts are EQUAL.
 - **`enqueuedBy` is ATTRIBUTION, never authority** — do not re-litigate. A job acting FOR a user takes
@@ -43,39 +44,37 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 
 ## Rules — the driver and SQL
 
-- **`SQL_JOBS_TABLE` is the ONE install point** for every durable table (`x_jobs`, `x_job_steps`,
-  `x_backfills`, `x_outbox`, `x_scheduler_state`, `x_scheduler_leader`, `x_job_leases`,
-  `x_job_events`, `x_job_pauses`, `x_job_workers`, `x_job_counters`). A NEW table is also a name in
+- **`SQL_JOBS_TABLE` is the ONE install point** for every durable table (`x_jobs`, `x_job_*`, `x_backfills`,
+  `x_outbox`, `x_scheduler_*`). A NEW table is also a name in
   `packages/cli/src/framework-schema.ts`. A shipped table grows by `alter table ... add column if
-  not exists`. Its comments carry NO apostrophes and NO semicolons (`dev-queue.ts` splits on `;`; `driver-pg-sql.test.ts` checks
+  not exists`. Its comments carry NO apostrophes and NO semicolons (it splits on `;`; `driver-pg-sql.test.ts` checks
   quote parity).
 - **`claim({ queues: [] })` is REFUSED by every driver** (`assertClaimQueues`,
-  `X_JOB_CLAIM_QUEUES_EMPTY`); the memory driver's `claim`/`list`/`deadLetters` are `async` so a
-  refusal rejects on both.
+  `X_JOB_CLAIM_QUEUES_EMPTY`); the memory driver's reads are `async` so a refusal rejects on both.
 - **`ack`, `nack`, `heartbeat` and `recordProgress` are FENCED on `state = 'running'` AND the
   CLAIM** — `{ workerId, claim }`, `claimOf(claimed)`; `x_jobs.claims` is moved by the claim and
-  never reset. A worker id alone let a worker's own earlier body settle its re-claim. `heartbeat`
-  answers a boolean, read as `held === false` (never `!held`).
-- **A driver's semantics are pinned in ONE test beside the pg statement** (`driver-parity.test.ts`):
-  list order, the `attempt` floor, `SQL_LEASE_RENEW` fencing on `expires_at > now()` and `holder`,
-  `SQL_STATS` one bucket per row.
+  never reset. `heartbeat` answers a boolean, read as `held === false` (never `!held`).
+- **A driver's semantics are pinned beside the pg statement** (`driver-parity*.test.ts`);
+  `driver-*-fixture.ts` scenarios run on memory AND Postgres.
+- **The claim BURIES a lease that lapsed on the final attempt** (`attempt >= max_attempts`): `dead`
+  in `SQL_CLAIM` — `failed` for a name in `ClaimOptions.dropExhausted` (`retry.deadLetter: false`)
+  — counted, never returned; the worker's round hears `onExhausted` and calls `announceExhausted`.
+- **`cancel` is fenced on `LIVE_STATES`.** **`requeue`** refuses (`X_JOB_NOT_FOUND`, not requeueable,
+  duplicate), then ONE statement. **`enqueue` inserts twice at most.** **`BulkResult.remaining` is
+  what a second call would move.**
 - **No read returns a WHOLE row** — `driver-pg-sql.test.ts` scans every production file here
   (discovered, comments stripped) for `select *`/`returning *`.
 - Drivers implement the six `JobDriver` methods plus optional `introspect`, `backfills`, `leases`. New
   capabilities go behind the interface. `inspect.ts` returns plain JSON for CLI, `/_x` and MCP.
-- Step results are persisted BEFORE the step returns. All time is epoch ms from an injected `Clock`
-  (`nowMs()` in `clock.ts`).
-- **`createPgLeader` is correct only on a DEDICATED connection**; boot uses `createPgLeaseLeader`.
-- `driver-redis.ts` / `driver-nats.ts` are honest `X_NOT_IMPLEMENTED` stubs.
+- Step results are persisted BEFORE the step returns. All time is epoch ms (`nowMs()`, `clock.ts`).
+- **`postgresLeader` is correct only on a DEDICATED connection**; boot uses `postgresLeaseLeader`.
 
 ## Rules — numbers and limits
 
 - **Every numeric knob is refused when not FINITE** — core's `finiteOption()` (a bound) and
-  `finiteCount()` (a count, caller's minimum); `worker-options.ts` is where `createWorker` reads them.
-  **`bun run finite-bounds` is a floor, never proof**: `createLimiter`'s five numbers (`perTenant`,
-  `perQueue`, `global`, `ratePerTenant.limit` / `.windowMs`) are screened with min 0 (zero is a HARD
-  STOP). **A row count is `finiteCount` (min 0)** for driver parity (`list`, `deadLetters`, the
-  backfill ledger's `list`, `assertClaimBounds`).
+  `finiteCount()` (a count, caller's minimum); `worker-options.ts` is where `jobWorker` reads them.
+  **`bun run finite-bounds` is a floor, never proof**: `concurrencyLimiter`'s five numbers are screened
+  with min 0 (zero is a HARD STOP). **A row count is `finiteCount` (min 0)**; `retry.attempts` is one with min 1.
 - **`WorkerOptions.concurrency` is read by OWN key** — a queue named `constructor`
   (`worker-slots.test.ts`).
 - **`job.concurrency` is enforced by `JobDriver.leases`** (one row per held slot in `x_job_leases`);
@@ -99,24 +98,21 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - The scheduler's key is occurrence-scoped (`task:occurrenceMs:jobKey`); `task.enqueue()` uses the
   job's plain key.
 - **TWO shutdown hooks per worker, one per PHASE**: `accept` is `stopAccepting()` (flip state, clear
-  the poll timer, abort held runs); `close` is the teardown. `stop()` hands both back in a `finally`;
+  the poll timer, arm the drain cut-off — it aborts nothing); `close` is the teardown. `stop()` hands both back in a `finally`;
   `start()` refuses while draining.
-- **A claimed job is counted with core's `beginWork()`**, so the drain's in-flight phase does the
-  waiting. **The teardown's wait is bounded on SIGTERM** (`settleAllBy` in `drain-wait.ts`,
-  `jobs.worker.drain-abandoned`) and unbounded on a manual `stop()`. A worker always reaches `'stopped'`;
-  `state` is set in the `finally`. **One teardown, joined.**
-- **SIGTERM reaches the job**: the worker's one `AbortController` (`drainSignal`) is composed into every
-  run (`worker-run.ts`); `stopAccepting(reason)` aborts it with `JobDrainedError` (`X_DRAINING`). A
-  drained attempt settles as **`interrupted`** (`nack`, `countsAsAttempt: false`, no park, no dead
-  letter), read off the SIGNAL. `WorkerStats.interrupted`; `worker-drain-signal.test.ts`.
+- **A claimed job is counted with core's `beginWork()`**: the drain's in-flight phase waits. The
+  teardown's wait is bounded on SIGTERM (`drain-wait.ts`), unbounded on `stop()`; one teardown, joined.
+- **A deploy lets a running job FINISH**: SIGTERM only stops claiming. `drainSignal` aborts
+  (`X_DRAINING`) at `deadlineAt − margin` (`worker-drain-cutoff.ts`), then held claims go back
+  uncounted (`worker-held.ts`). Settles **`interrupted`**; `docs/history/jobs.md`, "Drain, 2026-10".
+- **`X_RATE_LIMITED` defers uncounted** (`rateLimitDeferralMs`).
 - **The drain waits out the claim round it races** — `tick()` registers its round in `rounds`
   synchronously with its guard.
-- **A fleet slot is taken INSIDE a `try`, released AWAITED, and a renewal answering `false` CANCELS the
-  run** (`X_JOB_SLOT_LOST`, read as `renewed !== false`).
+- **A fleet slot is taken INSIDE a `try`, released AWAITED, and HELD, not owned**: `false`, or a TTL
+  with no renewal landing, CANCELS the run (`X_JOB_SLOT_LOST`); held per job id as a LIST.
 - **The run's signal is a controller this worker owns** (`run-signal.ts`), never `AbortSignal.any`.
-- **A lease is HELD, not owned** (`heartbeat.ts`): one failed renewal is `jobs.heartbeat.failed`; a
-  whole window without one landing is `jobs.lease.lost` + `recordLeaseLost(queue)`, measured on this
-  process's clock, asked both sides of the call.
+- **A lease is HELD, not owned** (`heartbeat.ts`): one failed renewal warns; a whole window without
+  one landing is `jobs.lease.lost`, on this process's clock, asked both sides of the call.
 - **A renewal is decided against `stopped()`** (`renewal-timer.ts`, re-read after every await); the
   interval is `unref`ed; every renewal is armed through `WorkerOptions.schedule`.
 - **Settlement is not part of the retry decision**: `driver.ack` sits after the `try`.
@@ -125,21 +121,26 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **The claim loop re-arms on the PASS, never the jobs**; `tick()` resolves with that pass's executions.
 - **A deadline CANCELS, then fails the attempt**, never the reverse (`raceTimeout`, `withStepTimeout`);
   the attempt is cancelled in `executeJob`'s `finally`.
-- **A cancelled runner writes NOTHING** — `put()` in `steps.ts` is the one fence (`X_ABORTED`);
-  `jobs.timeout.abandoned` names an uncooperative body. `executeJob` reads `ctx.signal` defensively.
+- **A cancelled runner writes NOTHING** — `put()` in `steps.ts` (`X_ABORTED`) — save a fenced
+  `X_DRAINING` on a live attempt: a step done in the drain is recorded once. The STORE fences
+  the claim (`StepFence`, `SQL_STEP_PUT` as `SQL_ACK`: `X_JOB_LEASE_LOST`). `executeJob` passes it.
 - **`traceparent` is stamped at ENQUEUE time, in `outbox.ts`**, and an empty `spanId` sends none.
 - **The scheduler runs one dispatch round at a time**; every other `tick()` joins it; `stop()` waits it
   out before `leader.release()`. Same two-hook rule; an ABANDONED round does not release
   (`jobs.scheduler.drain-abandoned`). `stillLeading()` is asked every round and before every task,
   and answers from memory inside `renewEveryMs`.
-- **`run-once` fires ONE catch-up** (marks `at`); `skip` fires the true latest missed occurrence
-  (`latestOccurrenceBy`, bisection).
+- **`run-once` fires ONE catch-up**: the watermark rides the fire (`ScheduledFire.watermarkMs`,
+  `SQL_SCHEDULER_FIRE` `$4`), never a `markFired` behind it; `skip` fires the true latest missed
+  occurrence (`latestOccurrenceBy`, bisection).
+- **A lease for a run that never STARTED is `abandon()`ed, never `release()`d** — the rate stamp
+  goes with it (`worker-admit.ts`). **A failed pass re-arms at the floor** (`worker-loop.ts`
+  catch); `timers` is the test seam.
 - **Every timer body catches before it finalises** (`void work().catch(log).finally(...)`).
 - **Suspension is control flow, and a SHED is not a suspension**: `StepSuspension` →
   `nack({ countsAsAttempt: false, park: true })`; a shed is `countsAsAttempt: false` without `park`,
   stays `ready`, logs `jobs.worker.shed` (no `last_error`). `driver-parity.test.ts`.
-- **A run's acquisitions are handed back even when the wiring throws** (`worker-run.ts`: `context()`
-  above the heartbeat; `createRunSignal` and `fleetSlots.startRenewal` inside the `try`).
+- **A wiring throw hands back the run's holdings, and its ROW until `executeJob` starts**
+  (`worker-run.ts`), as a failed shed does its job (`worker-admit.ts`).
 - **`step.run` hydrates the run's steps from ONE `store.list(runId)`**; `sleep` and `waitForEvent`
   record replays through `trace()`. **`claimName` reads a Set**; `usedNames()` keeps
   `MAX_TRACE_NAMES` (200).
@@ -153,9 +154,8 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   suite (memory + real pg).
 - **A settle answers whether it landed**; a miss is `jobs.settle.unowned`, not a throw.
 - **The counter moves in the SETTLING statement** (`driver-pg-settle-sql.ts`): one-minute bucket per
-  job name; `nackOutcome()` decides what a nack adds (a shed, a suspension, a drain: nothing), and
-  `ack({ counted: false })` — `x jobs drain` — adds nothing. The scheduler leader folds tiers
-  (`rollupCounters`), at most once a bucket.
+  job name; `nackOutcome()` decides what a nack adds (a shed, a suspension, a drain: nothing).
+  The scheduler leader folds tiers (`rollupCounters`), at most once a bucket.
 - **`list()` is KEYSET** (`after: jobCursor(lastRow)`, newest first by `(created_at, id)`); the pg
   seek reads the cursor row's own `created_at` — the cursor's ms is rounded. A page past
   `MAX_JOB_PAGE` or a foreign cursor is `X_JOB_PAGE_INVALID`, never a bare invariant.
@@ -166,10 +166,9 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **An occurrence fires in ONE statement** (`SchedulerState.fire`, `SQL_SCHEDULER_FIRE`): the
   watermark is the fence, jobs insert only `where exists (select 1 from moved)`.
 - **`progress()` is throttled in `progress.ts`** and flushed before every settle. **`onSettled`
-  (`settled.ts`) is the ONE ending hook** — `completed` (with `result`), `dead-lettered`,
-  `dropped`, `refused` — AFTER a settle that LANDED, in the body's tenant scope,
-  `ON_SETTLED_ATTEMPTS` tries, never rethrown (`X_JOB_ON_SETTLED_FAILED`), at most once across a
-  crash. Never for a cancel, a retry or a suspension; no second hook beside it.
+  (`settled.ts`) is the ONE ending hook** — `completed`, `dead-lettered`, `dropped`, `refused` —
+  AFTER a settle that LANDED, in the body's tenant scope, `ON_SETTLED_ATTEMPTS` tries, never
+  rethrown, at most once across a crash. Never for a cancel, a retry or a suspension.
 - **Failed for good + `deadLetter: false` is DROPPED**: `nack({ fail })`, outcome `dropped`.
 - **Worker registry rows expire** (`worker-registry.ts`, TTL = visibility timeout); `stop()` forgets.
 
@@ -196,7 +195,9 @@ Long form: `docs/history/jobs.md`, "the cross-process wake".
 - **`idle-cost.test.ts` / `queue-wake.test.ts` count statements per idle minute** — scheduler 6,
   worker and relay 30 with no wake, 12 with. Raising one is a regression.
 - **The memory driver stores a payload's JSON form**, as pg binds it (`driver-settle-parity.test.ts`).
-- **The event bus has ONE clock**: `createPgEventBus` takes no `clock`; `bus.now()` is "asked at".
+- **The event bus has ONE clock**: `postgresEventBus` takes no `clock`; `EventLookup.now()` is
+  REQUIRED, stamps a NEW wait, and calls the TIMEOUT (asked once the runner thinks time is up).
+  `purgeExpired()` is awaited and counted; `eventsPurgeTarget(bus)` is its `PurgeTarget`.
 
 ## Rules — the outbox
 
@@ -225,8 +226,8 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 - **`purge()`** is the one caller of every `purgeExpired()`: one table per `step.run`, one clock
   reading per pass, duplicate names refused.
 - **`exportRows()`**: one object per PAGE, named by page index; NO cross-tenant escape.
-- **`webhook()`** delivers ONE event to ONE endpoint; no steps; every attempt recorded before the
-  throw. **The wire format is core's**, re-exported.
+- **`webhook()`**: ONE event to ONE endpoint, no steps; each attempt but a CANCELLED one recorded
+  before the throw; `ledger.isDisabled` gates the socket. **The wire format is core's.**
 - A `-fixture.ts` file does not ship; `backfill-pass-fixture.ts` raises a plain `Error` subclass on
   purpose (it stands in for app code).
 
@@ -238,7 +239,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `tenant.ts` | what tenant a run acts under: `JobTenant`, the declaration's backstop, the actor `executeJob` installs |
 | `backfill.ts` | `backfill()` — a factory over `job()`: the declaration, its checksum and its input |
 | `backfill-pass.ts` | one pass: the batched iteration, its cursor checkpoints and its ledger row |
-| `backfill-scope.ts` | which sweeps run across tenants — `tenant: 'none'` only, on the pass's own actor, for the pass's own life |
+| `backfill-scope.ts` | which sweeps run across tenants (`tenant: 'none'` only) |
 | `backfill-ledger.ts` | `x_backfills` — the contract, `BACKFILL_STATUSES`, the checksum, the verdict, the memory ledger |
 | `backfill-registry.ts` | what was DECLARED: the `origin` stamp, `isBackfill`, `registeredBackfills` |
 | `backfill-gate.ts` | may this sweep run here and now — environment, `requires`, already-applied |
@@ -249,38 +250,39 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `register.ts` | `registerJobs`/`registerTasks` over a module namespace + the registrar announcements; an `action-job` projection is `X_ACTION_JOB_UNBRIDGED` |
 | `describe.ts` | the JSON projection one handle emits; `describeJobs()` is a map over it |
 | `steps.ts` | `StepStore`, `StepApi`, memoized-replay executor, `StepSuspension` |
+| `steps-timeout.ts` / `steps-suspension.ts` | a step's ceiling; `StepSuspension` and the timed-out marker |
 | `outbox.ts` | staging in a `Tx`, the store seam, the ambient `JobsFacade` slot |
 | `outbox-relay.ts` | the relay: the poll timer, one pass, and its TWO shutdown hooks |
-| `outbox-pg.ts` | `createPgOutboxStore` — `stage()` on the caller's OWN connection, claim on the pool |
+| `outbox-pg.ts` | `postgresOutboxStore` — `stage()` on the caller's OWN connection, claim on the pool |
 | `outbox-lease.ts` | the claim lease's one definition and its one normalisation, for both stores |
-| `leases.ts` | `LeaseStore` — fleet-wide slots, the memory one (drops a key with its last slot), `jobLeaseKey` |
+| `leases.ts` | `LeaseStore` — fleet-wide slots, the memory one, `jobLeaseKey` |
 | `concurrency.ts` | `job.concurrency` as declared, resolved once: `KeyedConcurrency`, `WhenBusy`, the declaration and key refusals |
-| `errors-concurrency.ts` | every concurrency refusal's class — declaration, key, `X_JOB_KEY_BUSY`, the boot refusal. Codes stay declared in `errors.ts` |
+| `errors-concurrency.ts` | every concurrency refusal's class; codes stay in `errors.ts` |
 | `worker-key-busy.ts` | one run refused by its key: settled `failed`, body never run |
 | `metrics.ts` | `queue_oldest_ready_seconds` and `queue_dead_jobs`, the two alertable gauges |
-| `scheduler-pg.ts` | `pgSchedulerState` (the durable watermark, the atomic fire) + `createPgLeaseLeader` |
-| `events-pg.ts` | `createPgEventBus` — `step.waitForEvent` across processes |
+| `scheduler-pg.ts` | `postgresSchedulerState` (the durable watermark, the atomic fire) + `postgresLeaseLeader` |
+| `events-pg.ts` | `postgresEventBus` — `step.waitForEvent` across processes |
 | `driver.ts` | `JobDriver` contract + wire records |
-| `driver-pg.ts` | default driver, and `createPgLeader` — the advisory-lock election a scheduler does NOT use |
+| `driver-pg.ts` | default driver, and `postgresLeader` |
 | `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` — the ONE install point. Its comments carry no `;` and no `'` |
 | `driver-pg-jobs-sql.ts` | every statement returning a whole `x_jobs` row, and `JOB_ROW_COLUMNS`; re-exported from `driver-pg-sql.ts` |
 | `driver-pg-rows.ts` | a Postgres row → a wire record: `JobRow`/`StepRow`/`BackfillRow` and their mappings |
-| `driver-memory.ts` | `x dev` / tests |
-| `driver-redis.ts`, `driver-nats.ts` | honest `X_NOT_IMPLEMENTED` stubs |
+| `driver-memory.ts` / `claim-exhausted.ts` | `x dev` / tests; a buried row's log line and `onSettled` |
 | `retry.ts` | the dead-letter decision, and this package's option names over core's `backoffDelay` — no curve of its own |
-| `retry-classification.ts` | the OTHER half of that decision: what the thrown error says, and the stop reason the row and the log carry |
+| `retry-classification.ts` | the other half: what the thrown error says, and the stop reason |
 | `execute.ts` / `run-deadline.ts` | `executeJob` — one claimed job run and settled; the run's deadline: cancel, then fail |
 | `heartbeat.ts` | one claimed job's lease: the renewal interval and the loss it reports |
-| `renewal-timer.ts` | the interval a renewal runs on, and the `stopped()` latch every branch after an await re-reads |
-| `worker.ts` | `worker` role, claim loop, drain — and the one `AbortController` SIGTERM reaches every held run through |
+| `renewal-timer.ts` | the renewal interval and its `stopped()` latch |
+| `worker.ts` | `worker` role, claim round, drain |
+| `worker-drain-cutoff.ts` / `worker-held.ts` / `worker-tally.ts` | drain cut-off · held claims · counters |
 | `worker-admit.ts` | may this claimed job start: the limiter, the fleet slot, and the shed / refusal |
 | `worker-registry.ts` | one worker's registry row: announce, heartbeat, forget |
 | `worker-types.ts` | the worker's public contract: `WorkerOptions`, `WorkerStats`, `Worker` |
-| `drain-wait.ts` | the drain's wait, shared by both roles: settled, or abandoned at the `close` hook's budget |
-| `worker-run.ts` | one claimed job, wired: heartbeat, slot renewal, run signal, span — handed back in one `finally` |
-| `run-signal.ts` | the signal ONE run is cancelled by — composition that can be handed back, and that the worker can abort itself |
+| `drain-wait.ts` | the drain's wait, shared by both roles |
+| `worker-run.ts` | one claimed job, wired: heartbeat, slot renewal, run signal, span |
+| `run-signal.ts` | the signal ONE run is cancelled by |
 | `worker-fleet-slots.ts` | the fleet slot an in-flight job holds — take, renew, hand back — and the boot refusal |
-| `purge.ts` | `purge()` — a factory over `job()`: the retention sweep, its structural target seam and the hourly cron a host schedules it on |
+| `purge.ts` | `purge()` — a factory over `job()`: the retention sweep and its target seam |
 | `task.ts` | the `task()` primitive + registry + the handle's surface + `registerTask` |
 | `scheduler.ts` | `scheduler` role: the dispatch round, catch-up, leader election, the drain |
 | `limits.ts` | per-tenant / per-queue / global concurrency + rate |
@@ -298,16 +300,11 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `queue-wake.ts` / `driver-pg-wake-sql.ts` | the `LISTEN` session and its proof; which statement notifies |
 | `worker-loop.ts` | the claim loop's timer: wake, `again`, the kicks |
 | `driver-pg-outbox-sql.ts` | the `x_outbox` statements |
-| `errors-operator.ts` | `X_JOB_NOT_REMOVABLE`, `X_JOB_NOT_PROMOTABLE`, `X_JOB_ON_SETTLED_FAILED` classes |
+| `errors-operator.ts` / `errors-requeue.ts` | the operator verbs' refusals; `requeue`'s |
 
 Which `-fixture.ts` harness each suite shares, and what each `.job.` suite proves:
 `docs/history/jobs.md`, "Moved 2026-10-01 — test harnesses".
 
-## Commands
-
-```
-bun test packages/jobs
-bun run --filter @ultimat3/jobs typecheck
-```
+Commands: `bun test packages/jobs` · `bun run --filter @ultimat3/jobs typecheck`.
 
 Why each rule above is shaped the way it is: [`docs/history/jobs.md`](../../docs/history/jobs.md).

package/README.md

@@ -192,11 +192,17 @@ input. The tenant is a fact about the work, so the job declares it.
 expires, so on a bus shared by one `bun test` process an answer one test published resumes the
 next test's wait — call it between tests.
 
-The event bus has ONE clock. `createPgEventBus({ executor })` stamps `publishedAt` and the expiry
+The event bus has ONE clock. `postgresEventBus({ executor })` stamps `publishedAt` and the expiry
 with the database's `now()` — it takes no `clock` — and `bus.now()` answers that same clock. A
 consumer that wants "published after I asked" (`@ultimat3/scraping`'s `eventPrompt`) reads its
 "asked at" from `bus.now()`, never from its own process: a skew between two pods must not decide
-which answers count.
+which answers count. `step.waitForEvent` stamps a new wait from the same clock
+(`EventLookup.now()`), so a worker running ahead of the database still matches an event published
+after it asked.
+`step.waitForEvent` stamps a new wait from that clock (`EventLookup.now()`, required) and asks it
+again before declaring a timeout, so a worker running ahead of the database still matches an event
+published after it asked and does not give up early. `eventsPurgeTarget(bus)` is the bus as a
+`purge()` target: `purgeExpired()` is awaited and answers the rows it removed.
 
 Step names are the replay key, so they must be deterministic and unique in a run — a
 duplicate is `X_STEP_DUPLICATE`, not a silent overwrite. Suspension is control flow
@@ -405,6 +411,11 @@ export const hourly = task({
 | at least once is safe here | a replayed delete removes rows that are already gone, and a row a purge deleted answers exactly as one that was never there |
 | two targets under one name | `X_INVARIANT`, before the first delete — `step.run` would raise `X_STEP_DUPLICATE` after one table was already empty |
 
+The stored event bus is a target too: `eventsPurgeTarget(bus)` answers
+`{ name: EVENTS_PURGE_TARGET, purgeExpired }` over `bus.purgeExpired()`, which is awaited and
+answers the rows it removed — `x_job_events` only grew while nothing called it. Add it to
+`targets`: `targets: () => [eventsPurgeTarget(eventBus())]`.
+
 `@ultimat3/cli`'s boot declares both halves over the three tables it owns, so an app gets the sweep
 without writing any of the above. It needs a `worker` to run it and a `scheduler` to fire it: a
 deployment with neither has no background work at all, and this is one more thing it does not do.
@@ -526,9 +537,11 @@ x-ultimate-webhook-signature: t=1700000000,v1=<hex hmac-sha256>
 
 The receiving half is `verifyWebhookSignature(request, { secret })` in `@ultimat3/http`. The format
 itself — the canonical string, the mac and the header names — is **one module in `@ultimat3/core`**
-(`webhook-signature.ts`), re-exported by both packages and re-declared by neither: this package
-signs, `http` verifies, and neither may import the other, so the one copy lives at the tier both
-can reach. Same argument `timing-safe-equal.ts` makes for itself.
+(`webhook-signature.ts`), imported from `@ultimat3/core` by both packages and re-declared by
+neither: this package signs, `http` verifies, and neither may import the other, so the one copy
+lives at the tier both can reach. A receiver or a test imports `WEBHOOK_SIGNATURE_HEADER`,
+`webhookSignature` and the rest from `@ultimat3/core` — 25.0.0 dropped this package's
+re-exports (`X_HELPER_COPY`). Same argument `timing-safe-equal.ts` makes for itself.
 
 | Rule | Why |
 |---|---|
@@ -539,10 +552,21 @@ can reach. Same argument `timing-safe-equal.ts` makes for itself.
 | `redirect: 'manual'` | following a 3xx would re-POST a body signed for one host to whatever the receiver named |
 | the endpoint is never checkpointed | a `step.run` output lands in `x_job_steps`, and the endpoint carries the secret |
 | every attempt is recorded **before** the throw | a failure the ledger cannot see is a failure the consecutive count cannot see, which is an endpoint that never gets disabled |
-| a `Retry-After` the receiver names is honoured | `X_WEBHOOK_DELIVERY_THROTTLED` carries `meta.retryAfterSeconds`, which the nack waits out (clamped by `retry.maxDelay`) rather than guessing a curve against an answer it already has |
+| a `Retry-After` the receiver names is honoured | `X_WEBHOOK_DELIVERY_THROTTLED` carries `meta.retryAfterSeconds`, which the nack waits out — read by core's `retryAfterSecondsOf` (delta-seconds, or an HTTP-date against the response's own `Date`; `0` or a past date is unstated), clamped by `retry.maxDelay`, plus core's `jitterStatedDelay` spread so deliveries handed one instant do not wake together |
+| `WebhookLedger.isDisabled(endpointId)` is asked before every socket, beside the row's own `disabled` | `disableAfter` writes only the ledger: a verdict nobody asks for again is an endpoint that keeps receiving POSTs. Answer it from the column your `disable` sets |
+| the deadline and a lost lease abort `fetch`; a failure that abort caused writes no ledger row | the nack behind them hands the job to another worker at once, so a request left open is a duplicate delivery, and an abandoned attempt's failure would count toward `disableAfter` |
+| the DRAIN never aborts a POST already on the wire; it stops one not yet sent | torn down, the job goes to the next pod, which re-POSTs the same event on every deploy. Finished, it is recorded like any other outcome — a real failure during the drain included |
 | re-enabling is always yours | an endpoint the framework un-disabled on its own is a retry loop with no end |
 | `WebhookLedger` is a seam, not a table | retention is seven years for one business and thirty days for the next, so shipping a schema would ship one of those answers |
 
+**Set `timeout` below the drain budget.** A webhook has no timeout unless you declare one, and a
+POST on the wire when SIGTERM lands runs until the receiver answers. With a `timeout`, a drained
+request is still torn down at the attempt's deadline — where `executeJob` hands the job on — and
+writes no ledger row. Without one, the only bound is `configureLifecycle({ deadlineMs })`, 25 s by
+default: past it the worker logs `jobs.worker.drain-abandoned` and exits, and the row comes back
+only when its lease lapses, as a COUNTED attempt the receiver may already have processed.
+`timeout: '10s'` against the default budget ends every drained delivery inside it.
+
 ## The deadline cancels
 
 A job's `timeout` aborts `ctx.signal` **before** it fails the attempt, because the nack that
@@ -659,15 +683,15 @@ things have to be true in a process:
 | Step | Call |
 |---|---|
 | the table exists | ships in `SQL_JOBS_TABLE` — applying the queue DDL is enough |
-| the facade is installed | `setJobsFacade(createJobsFacade({ store, driver }, currentTx))` |
-| the relay is running | `createOutboxRelay({ store, driver }).start()` |
+| the facade is installed | `setJobsFacade(outboxJobsFacade({ store, driver }, currentTx))` |
+| the relay is running | `outboxRelay({ store, driver }).start()` |
 
-`start()` registers the same two shutdown hooks `createWorker` does — `accept` stops polling
+`start()` registers the same two shutdown hooks `jobWorker` does — `accept` stops polling
 (the worker's also aborts every held job's `ctx.signal`), `close` waits out the pass in flight
 under the drain's deadline — and `stop()` hands both back.
 `drainOnShutdown: false` opts out, for a caller that drives its own teardown.
 
-with `store = createPgOutboxStore({ executor, txExecutor })`. `txExecutor` is what makes it
+with `store = postgresOutboxStore({ executor, txExecutor })`. `txExecutor` is what makes it
 transactional: `stage()` runs on the CALLER'S connection, never the pool. With nothing installed,
 `jobsFacade()` answers a fallback whose `currentTx` is `() => undefined` and every enqueue
 publishes straight to the driver — deliberate, so a script and a test enqueue with no wiring, but
@@ -702,7 +726,7 @@ What the lease buys, precisely:
 | a relay that died mid-batch stranding its rows forever | anything a **non-idempotent** handler does on its second run |
 | — | a lapsed visibility lease re-delivering a job that is still running |
 
-The memory store (`createMemoryOutboxStore`, `x dev` and tests) **drops** a published row —
+The memory store (`memoryOutboxStore`, `x dev` and tests) **drops** a published row —
 `retained()` is the relay's backlog, not a running total; the pg store keeps `published_at` as
 the audit trail this map is not. A relay pass that throws is logged as `jobs.outbox.tick-failed`
 and the loop re-arms: an unobserved rejection would end the process with rows still staged.
@@ -719,17 +743,35 @@ One interface: `enqueue`, `claim` (visibility timeout), `ack(jobId, { workerId,
 `backfills` and `leases`. Both settles are fenced on the CLAIM — `claimOf(claimed)` is the
 `{ workerId, claim }` a `ClaimedJob` carries — and answer whether they landed. Zero job-code change
 between them — swapping is `setJobDriver(other)`, and there is **no `jobs.driver` config line**:
-`JobsConfig.driver` has no reader and boot always builds `createPgDriver`.
+`JobsConfig.driver` has no reader and boot always builds `postgresJobDriver`.
 
 | Driver | Status | Backing | Use |
 |---|---|---|---|
 | `pg` | **default** | `SELECT ... FOR UPDATE SKIP LOCKED`, a partial unique index on `(name, coalesce(tenant_id, ''), idempotency_key)` over live rows (`x_jobs_name_tenant_idempotency_live_idx`), lease-based leader, `x_job_leases` | zero-infra start, most apps |
 | `memory` | complete | in-process maps | `x dev`, tests |
-| `redis` | interface-complete, `X_NOT_IMPLEMENTED` | Streams + consumer groups | planned |
-| `nats` | interface-complete, `X_NOT_IMPLEMENTED` | JetStream work queue | planned |
 
-The pg SQL is exported verbatim (`SQL_CLAIM`, `SQL_ENQUEUE`, `SQL_NACK`, …) so an agent
-debugging a stuck queue can read and run the exact statement.
+There is **no NATS or Redis jobs driver**: `createNatsDriver` and `createRedisDriver`, all-throw
+stubs, were deleted in 25.0.0. A real `redisJobDriver()` would arrive as a minor.
+
+The pg SQL lives verbatim in `src/driver-pg-*sql.ts` (`SQL_CLAIM`, `SQL_ENQUEUE`, `SQL_NACK`, …)
+so an agent debugging a stuck queue can read and run the exact statement. The barrel exports
+only the statement another package runs: `SQL_JOBS_TABLE` (the install) — 25.0.0 took the rest
+off, `SQL_CLAIM` and `SQL_OUTBOX_RELEASE` included (their array-parameter proofs are this package's
+`driver-pg-array.live.test.ts`).
+
+**A lease that lapses on a row's final attempt is buried by the claim.** `claim` re-takes a
+`running` row whose lease lapsed — the worker died — but one already at `attempt >= maxAttempts`
+is settled `dead` in the claim statement itself (`SQL_CLAIM`'s second arm; `isFinalAttempt` on the
+memory driver), with `lastError` set to `LEASE_LAPSED_FINAL_ATTEMPT`, counted `dead`, and never
+handed out: a job that kills its worker reaches the dead-letter queue after `retry.attempts`
+claims instead of taking a worker per visibility timeout, forever. The pass is told through
+`ClaimOptions.onExhausted(rows)` — at most once per pass, once per row — and `announceExhausted`
+(`claim-exhausted.ts`) is what a claim round does with them: `jobs.claim.exhausted` at `error`, and
+the job's `onSettled`, and the worker's claim round does exactly that. The row carries
+`maxAttempts` and not the policy, so the CALLER names the jobs declaring `retry.deadLetter: false`
+(`ClaimOptions.dropExhausted` — the worker reads them off its registry): those rows are buried
+`failed` and announced `dropped`, every other one `dead` / `dead-lettered`. A caller that names
+none buries every such row `dead`.
 
 A driver you write reads a nack's target state through `nackState(options)` — `dead`
 (`deadLetter`), `failed` (`fail`, terminal and out of the dead-letter queue), `suspended` (`park`)
@@ -740,8 +782,8 @@ or `ready` — so a new branch cannot land in one driver and not another. Its le
 
 | Role | Entry | Behaviour |
 |---|---|---|
-| `worker` | `createWorker({ driver, context, queues, concurrency })` | per-queue pools, lease heartbeat, SIGTERM drain: stop claiming → finish in-flight → close |
-| `scheduler` | `createScheduler({ driver, leader, state })` | one dispatch round at a time, catch-up policy, SIGTERM drain: stop dispatching → finish the round → release the lock |
+| `worker` | `jobWorker({ driver, context, queues, concurrency })` | per-queue pools, lease heartbeat, SIGTERM drain: stop claiming → finish in-flight → close. `concurrency` is a number for every queue or a table per queue; a queue it does not name gets core's `JOBS_CONCURRENCY_DEFAULT` (8 — this package's own default was 5 before 25.0.0) |
+| `scheduler` | `jobScheduler({ driver, leader, state })` | one dispatch round at a time, catch-up policy, SIGTERM drain: stop dispatching → finish the round → release the lock |
 
 Both roles register the same **pair** of hooks and bound the `close` half the same way. The
 scheduler's abandoned case differs in one respect: a round still enqueueing keeps the lease rather
@@ -773,24 +815,24 @@ update runs two leaders.
 
 ```ts
 import {
-  createPgLeaseLeader,
-  createScheduler,
+  postgresLeaseLeader,
+  jobScheduler,
   type JobDriver,
   type PgExecutor,
-  pgSchedulerState,
+  postgresSchedulerState,
 } from '@ultimat3/jobs';
 
 declare const driver: JobDriver;
 declare const executor: PgExecutor;   // see "A `PgExecutor`" below
 
-createScheduler({
+jobScheduler({
   driver,
-  state: pgSchedulerState(executor),
-  leader: createPgLeaseLeader({ executor }),
+  state: postgresSchedulerState(executor),
+  leader: postgresLeaseLeader({ executor }),
 });
 ```
 
-`createPgLeaseLeader` and not `createPgLeader`: `pg_try_advisory_lock` is scoped to a Postgres
+`postgresLeaseLeader` and not `postgresLeader`: `pg_try_advisory_lock` is scoped to a Postgres
 *session*, and the executor this package is handed is a **pool** — the lock is released the moment
 that connection goes back to it, so every node reads itself as leader. The lease is a row with an
 expiry and needs no connection affinity. `acquire()` is also the renewal, called every round, which
@@ -830,10 +872,10 @@ hourly task fire 24 catch-ups a second apart.
 client, which already speaks `(text, values)` and decodes `jsonb`:
 
 ```ts
-import { createPostgresClient } from '@ultimat3/db';
+import { postgresClient } from '@ultimat3/db';
 import type { PgExecutor } from '@ultimat3/jobs';
 
-const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const client = postgresClient({ url: 'postgres://localhost:5432/app_test' });
 export const executor: PgExecutor = {
   query: <R>(text: string, values: readonly unknown[]) => client.query<R>({ text, values }),
 };
@@ -861,11 +903,11 @@ A queue with nothing to do costs almost nothing, and a job starts when it is com
 `startQueueWake({ listener, executor })` holds ONE `LISTEN` session per worker pod and turns "another process committed" into the signal the idle loops already hear. The boot starts it for the `worker` role.
 
 ```ts
-import { createPostgresClient } from '@ultimat3/db';
+import { postgresClient } from '@ultimat3/db';
 import type { PgExecutor } from '@ultimat3/jobs';
 import { startQueueWake } from '@ultimat3/jobs';
 
-const client = createPostgresClient({ url: 'postgres://localhost:5432/app_test' });
+const client = postgresClient({ url: 'postgres://localhost:5432/app_test' });
 const executor: PgExecutor = {
   query: <R>(text: string, values: readonly unknown[]) => client.query<R>({ text, values }),
 };
@@ -934,7 +976,7 @@ exactly as it had before.
 | Thrown | What the queue does |
 |---|---|
 | a `terminal` code (`X_SCRAPE_AUTH_FAILED`, a validation fault, a permission denial) | dead-lettered on the attempt it happened, `attempt` recorded, remaining attempts unspent — a rotated password retried five times is five more wrong passwords at a site that locks the account after three |
-| a `retry-after` code (`X_RATE_LIMITED`, `X_OVERLOADED`) | retried at the time the responder NAMED — `meta.retryAfterSeconds`, clamped by the policy's `maxDelay` — instead of the backoff. Still an attempt, still under the ceiling |
+| a `retry-after` code (`X_RATE_LIMITED`, `X_OVERLOADED`) | retried at the time the responder NAMED — `meta.retryAfterSeconds`, clamped by the policy's `maxDelay`, plus core's `jitterStatedDelay` spread unless `jitter: false` — instead of the backoff. Still an attempt, still under the ceiling |
 | a `retryable` code (`X_TIMEOUT`, `X_DRAINING`) | the backoff schedule above, unchanged |
 | an **unclassified** code, or anything that is not an `UltimateError` | the backoff schedule above, unchanged. Most codes are unclassified and `retryFor` answers `terminal` for all of them, so reading that would have stopped every transient retry in every app |
 
@@ -965,7 +1007,7 @@ contractual rate.
 `job.concurrency` is the one that is fleet-wide, and it is enforced by a row every replica can
 see — one per held slot, keyed `job:<name>`, renewed by the same heartbeat that renews the
 visibility lease and reclaimed by TTL when a worker is SIGKILLed. A driver with no lease store
-cannot hold the cap, so `createWorker().start()` **refuses to boot**
+cannot hold the cap, so `jobWorker().start()` **refuses to boot**
 (`X_JOB_CONCURRENCY_UNENFORCEABLE`) rather than let a documented guarantee do nothing.
 
 Over any cap the claim is handed straight back without burning an attempt — one org's 50k-row
@@ -1003,7 +1045,7 @@ export const syncAccount = job({
 |---|---|---|
 | a cap of `0`, negative, fractional, `NaN` or `Infinity` — `concurrency: 0` and `limit: 0` alike; a `key` that is not a function; a `whenBusy` outside the two | where the job is declared | `X_JOB_DECLARATION_INVALID` |
 | `key(input)` answering `''`, a non-string, or more than 200 characters | at that **enqueue** — the facade and the scheduler both ask | `X_JOB_DECLARATION_INVALID` |
-| a driver with no lease store, for any `concurrency` | `createWorker().start()` | `X_JOB_CONCURRENCY_UNENFORCEABLE` |
+| a driver with no lease store, for any `concurrency` | `jobWorker().start()` | `X_JOB_CONCURRENCY_UNENFORCEABLE` |
 | a `LeaseStore` with no `holders(key)` | the build — the member is required | `TS2741` |
 
 What `'fail'` decides, exactly:
@@ -1071,7 +1113,9 @@ the pg and the memory driver alike. `x jobs`, `/_x` and a dashboard read nothing
 |---|---|---|
 | `list(filter)` | one page, newest first; `filter.after = jobCursor(lastRow)` for the next, `filter.before = jobCursor(firstRow)` for the previous (the rows nearest the cursor, still newest first; never both). Filters: `queue`, `name`, `state`, `tenantId`, `idPrefix`, `createdFrom`, `createdTo` | `MAX_JOB_PAGE` = 200 rows; `DEFAULT_JOB_PAGE` = 100. A page shorter than its limit is the last. A larger `limit`, or a cursor no page produced, is `X_JOB_PAGE_INVALID` |
 | `remove(id)` | delete one job and its steps. A running one is `X_JOB_NOT_REMOVABLE` | — |
-| `requeueMany({ state, queue?, name?, tenantId? })` | re-queue finished rows; a row whose key a live job holds stays | `MAX_BULK_ROWS` = 1,000 per call; answers `{ affected, remaining }` |
+| `requeue(id, { fromStep? })` | re-queue ONE finished job (`REQUEUEABLE_STATES`). A live one is `X_JOB_NOT_REQUEUEABLE`, a key a live job holds `X_JOB_DUPLICATE`, an id nobody queued `X_JOB_NOT_FOUND` — on both drivers. `fromStep` drops that step and every later one in the statement that moves the row | — |
+| `cancel(id, reason?)` | stop a LIVE job (`LIVE_STATES`: ready, delayed, running, suspended). A done, failed, dead or cancelled row is left exactly as it ended and answers `undefined` — `cancelJob` turns that into `X_JOB_NOT_CANCELLABLE` | — |
+| `requeueMany({ state, queue?, name?, tenantId? })` | re-queue finished rows; a row whose key a live job holds stays, and of several finished rows sharing one key the oldest is requeued | `MAX_BULK_ROWS` = 1,000 per call, spent only on rows it can move; answers `{ affected, remaining }`, where `remaining` is what a second call could still move — a held row is not counted, so "call until zero" ends |
 | `removeMany({ state, queue?, name?, tenantId? })` | delete rows in any state but `running` | the same |
 | `promoteMany({ state, queue?, name?, tenantId? })` | `promote` over a set: every row still waiting on its `runAt` is due now. `state` is `delayed` or `ready` (`PROMOTABLE_STATES`) | the same; `remaining` is the rows still waiting |
 | `promote(id)` | a job waiting on its `runAt` — delayed, or backing off — is due now | — |
@@ -1089,7 +1133,6 @@ the pg and the memory driver alike. `x jobs`, `/_x` and a dashboard read nothing
 | the counter moves in the statement that settles the row | a count that can disagree with the rows is worse than none — and no second round trip per job |
 | a shed, a suspension and a drained attempt add nothing | they are handed back uncounted; counted, every `step.sleep` would read as a failure |
 | `ack` / `nack` / `heartbeat` / `recordProgress` are fenced on the CLAIM | `{ workerId, claim }`: a body whose lease lapsed must not settle, renew or report on the run that replaced it — claimed by another worker, or by the SAME one, whose id did not change. A miss answers `false` and logs `jobs.settle.unowned` |
-| `ack(id, { …, counted: false })` adds nothing to the counters | `x jobs drain` settles the row it moved: `done` here, and not a completed run |
 | a pause is a row the claim reads | never a column on every queued row: pausing a million-row queue takes effect within one poll |
 | an occurrence fires in one statement | the watermark and its jobs move together (`SchedulerState.fire`), so a crash between them cannot fire it twice |
 
@@ -1133,6 +1176,7 @@ export const syncAccountWatched = job({
 |---|---|---|---|
 | the body returned and the ack landed | `completed` | `input`, `result` — what `run` returned, typed from it | `done` |
 | failed for good, parked in the dead-letter queue | `dead-lettered` | `input` (or `undefined`: the stored payload no longer parses), `error`, `code` | `dead` |
+| its lease lapsed on the final attempt and the claim buried it — every worker that took it died | `dead-lettered` | `input`, `error` (`LEASE_LAPSED_FINAL_ATTEMPT`), `code: undefined` — nothing was thrown | `dead` |
 | failed for good on `retry.deadLetter: false` | `dropped` | the same | `failed` |
 | `whenBusy: 'fail'` over a busy key — the body never ran | `refused` | the same, `code: 'X_JOB_KEY_BUSY'` | `failed` |
 
@@ -1198,15 +1242,16 @@ FOR a user takes that user's id in its input and re-authorises it in the body.
 | `X_ABORTED` | a cancelled attempt tried to write a step — core's code, not a second name for it |
 | `X_JOB_LEASE_LOST` | the job was cancelled, or its lease lapsed and the queue re-delivered it, while this worker was still running it |
 | `X_JOB_SLOT_LOST` | the fleet `concurrency` slot this run held was taken by another worker — a different row on a different clock from the lease above |
-| `X_JOB_NOT_CANCELLABLE` | `cancelJob` reached a job that already finished, or a driver with no `cancel` |
+| `X_JOB_NOT_CANCELLABLE` | `cancelJob` reached a job that is not live — done, failed, dead or already cancelled — an id no queue holds, or a driver with no `cancel` |
+| `X_JOB_NOT_FOUND` | `requeue` was asked for an id the queue does not hold — one answer on both drivers. Fix: `x jobs ls --json` |
 | `X_JOB_CONCURRENCY_UNENFORCEABLE` | a registered job declares `concurrency`, plain or keyed, and the driver has no lease store |
 | `X_JOB_KEY_BUSY` | a run claimed under `whenBusy: 'fail'` while its key already held `limit` runs. Classified `terminal`. Fix: `x jobs ls --name <job> --state running --json` |
 | `X_JOB_DECLARATION_INVALID` | `job()` is missing a required field, declares a `concurrency` no worker can honour (plain or keyed), or its `concurrency.key` answered an empty, non-string or over-long key at enqueue |
 | `X_JOB_NOT_REMOVABLE` | `remove` / `removeMany` reached a running job. Fix: `x jobs cancel <id> --json` |
 | `X_JOB_NOT_PROMOTABLE` | `promote` reached a job not waiting on its run time |
-| `X_JOB_PAGE_INVALID` | `list()` was asked for more than `MAX_JOB_PAGE` rows, or handed a cursor no page produced. Fix: `list({ limit: 200, after: jobCursor(lastRow) })` |
+| `X_JOB_PAGE_INVALID` | `list()` was asked for more than `MAX_JOB_PAGE` rows, or handed a cursor no page produced. The cause names which cursor (`after` / `before`). Fix: `x jobs ls --limit 200 --json` |
 | `X_JOB_ON_SETTLED_FAILED` | a declared `onSettled` threw on every one of its tries; logged and reported, never thrown |
-| `X_NOT_IMPLEMENTED` | redis / nats driver |
+| `X_NOT_IMPLEMENTED` | introspection or the operator surface on a driver with no `introspect` (a hand-rolled one) |
 
 ### Error classes
 
@@ -1240,6 +1285,7 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `JobMaxAttemptsError` | `X_JOB_MAX_ATTEMPTS` | `src/errors.ts` |
 | `JobNameTakenError` | `X_JOB_DUPLICATE` | `src/errors.ts` |
 | `JobNotCancellableError` | `X_JOB_NOT_CANCELLABLE` | `src/errors.ts` |
+| `JobNotFoundError` | `X_JOB_NOT_FOUND` | `src/errors-requeue.ts` |
 | `JobNotPromotableError` | `X_JOB_NOT_PROMOTABLE` | `src/errors-operator.ts` |
 | `JobNotRemovableError` | `X_JOB_NOT_REMOVABLE` | `src/errors-operator.ts` |
 | `JobNotRequeueableError` | `X_JOB_NOT_REQUEUEABLE` | `src/errors-requeue.ts` |
@@ -1247,7 +1293,6 @@ a job boundary the class is gone and the `code` is what survives — match on th
 | `JobPageInvalidError` | `X_JOB_PAGE_INVALID` | `src/errors-operator.ts` |
 | `JobRowStatusUnknownError` | `X_JOB_ROW_STATUS_UNKNOWN` | `src/errors.ts` |
 | `JobSlotLostError` | `X_JOB_SLOT_LOST` | `src/errors.ts` |
-| `JobsNotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
 | `JobTenantRequiredError` | `X_JOB_TENANT_REQUIRED` | `src/errors.ts` |
 | `JobTimeoutError` | `X_JOB_TIMEOUT` | `src/errors.ts` |
 | `LeaseLostError` | `X_JOB_LEASE_LOST` | `src/errors.ts` |