@ultimat3/jobs 29.4.0 → 30.0.0

package/CLAUDE.md

@@ -5,8 +5,11 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 ## Boundary
 
 - May import: `core`, `schema`, `entity`, `policy`, `cache`, `time` — and `db`, for
-  `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`.
+  `expectedQueryLoop` (`steps.ts` declares the per-step write one-per-step to the N+1 detector),
+  `outsideTransaction` (`execute.ts`), `refuseAbandoned` (`outbox.ts`) and `withTransaction`
+  (`consumer-loop.ts`: a batch and its cursor commit together) — the ONE place a client is taken
+  from it, the ambient `db()`. Never `render`, `ui`. `http` only from `webhook-receiver*.ts`, for the route
+  (`Route`/`Bucket` types, `DEFAULT_WEBHOOK_BODY_LIMIT`, `HttpError`, `jsonResponse`).
 - Consumers: `action` (`<job>.enqueue`, via the ambient jobs facade), `cli`, `mcp`, `admin`.
 - External deps: none. Postgres access goes through the injected `PgExecutor` (`@ultimat3/core`'s,
   re-exported from `index.ts`).
@@ -27,12 +30,7 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   idempotency_key)`** — the index, the conflict target (spelling the index EXPRESSION exactly) and the
   live-row lookup agree, pinned by a test; `driver-memory.ts` mirrors it. The DDL drops both
   superseded indexes.
-- **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).
-  `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.
+- **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). Full rule: `docs/history/jobs.md`.
 - **`enqueuedBy` is ATTRIBUTION, never authority** — do not re-litigate. A job acting FOR a user takes
   the user's id in its input and re-authorises it in the body.
 - `tz` is NON-OPTIONAL in `TaskDefinition`, validated by `@ultimat3/time`'s `isValidTimeZone`. A task
@@ -44,11 +42,7 @@ 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_*`, `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 (it splits on `;`; `driver-pg-sql.test.ts` checks
-  quote parity).
+- **`SQL_JOBS_TABLE` is the ONE install point** for every durable table (`x_jobs`, `x_job_*`, `x_backfills`, `x_outbox`, `x_scheduler_*`). Full rule: `docs/history/jobs.md`.
 - **`claim({ queues: [] })` is REFUSED by every driver** (`assertClaimQueues`,
   `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
@@ -62,29 +56,35 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **`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.**
+- **`enqueueMany` is one statement per `ENQUEUE_CHUNK` (1,000)** (`job-enqueue-many.ts`;
+  `SQL_ENQUEUE_MANY`: `SQL_ENQUEUE`'s conflict target and id fence, one wake per queue); skipped rows
+  are answered by ONE `SQL_ENQUEUE_MANY_RESOLVE`, a row neither answers goes back through `enqueue`.
+  **`JobDriver.enqueueMany` is REQUIRED** and opens with `assertEnqueueMany` (no `onConflict:
+  'error'` in a batch, `X_INVARIANT`); Redis's `REDIS_ENQUEUE_MANY` shares `enqueue_one` with
+  `REDIS_ENQUEUE`. `OutboxStore.stageMany`/`markPublishedMany` are OPTIONAL: absent, a loop. Every
+  refusal precedes the first write; `refuseAbandoned()` before every direct chunk. `runAt` crosses
+  as `numeric` then `bigint`: a fractional ms rounds, never a `22P02`.
 - **No read returns a WHOLE row** — `driver-pg-sql.test.ts` scans every production file here
   (discovered, comments stripped) for `select *`/`returning *`.
-- Drivers: the six `JobDriver` methods plus optional `introspect`, `backfills`, `leases`; new
+- Drivers: the `JobDriver` methods plus optional `introspect`, `backfills`, `leases`; new
   capabilities go behind the interface. **`redisJobDriver`** (`@ultimat3/jobs/redis`, off the
   barrel) is one Lua script per operation: a semantic change lands in memory, pg AND the scripts.
-- Step results are persisted BEFORE the step returns. All time is epoch ms (`nowMs()`, `clock.ts`).
+  Its client is core's `redisClient()`, never `Bun.redis`; `ERR_REDIS_CONNECTION_CLOSED` is
+  `X_DRIVER_UNAVAILABLE` at once (`typedRefusals`), never a wait.
+- **`demand` is the seventh method, required**; a draining worker's `queue_demand` goes to 0.
+- **The claim SEEKS** (`SQL_CLAIM`); correct only because a claim autocommits.
+- Step results are persisted BEFORE the step returns, and it returns what it persisted: `jsonForm` (`steps-output.ts`), typed `StepOutput<T>`, one stringify + parse per EXECUTED step. Full rule: `docs/history/jobs.md`.
 - **`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 `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.
+- **Every numeric knob is refused when not FINITE** (`finiteOption()`, `finiteCount()`, read in `worker-options.ts`); `bun run finite-bounds` is a floor. Full rule: `docs/history/jobs.md`.
 - **`WorkerOptions.concurrency` is read by OWN key** (`worker-slots.test.ts`); `maxInFlight` BEFORE
   the claim, its count back with the lease, before the `kick` (history).
 - **`job.concurrency` is enforced by `JobDriver.leases`** (one row per held slot in `x_job_leases`);
   `limits.ts` is the per-process fast path. No lease store + a declared `concurrency` makes `start()`
   throw `X_JOB_CONCURRENCY_UNENFORCEABLE`.
-- **`concurrency` is resolved ONCE** (`concurrency.ts`): a number, or `{ key, limit, whenBusy }` per
-  key. The handle carries `concurrency` (the limit), `whenBusy` (set exactly when keyed) and
-  `concurrencyKeyFor()` — a METHOD. Lease key `job-key:<encoded name>:<key>`; plain `job:<name>`.
-  A bad cap is `X_JOB_DECLARATION_INVALID`.
+- **`concurrency` is resolved ONCE** (`concurrency.ts`): a number, or `{ key, limit, whenBusy }` per key. Full rule: `docs/history/jobs.md`.
 - **`whenBusy: 'fail'` refuses only on EVIDENCE another run holds the key** (`LeaseStore.holders`,
   required): a run meets its own leftover slot. The refusal is `nack({ fail, countsAsAttempt:
   false })` → `failed`, outcome `refused` (`worker-key-busy.ts`), never `executeJob`.
@@ -94,8 +94,9 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 
 ## Rules — the worker and the scheduler
 
-- **One enqueue implementation**: `jobsFacade()`; the only other `driver.enqueue` sites are the outbox
-  relay and the scheduler. `handle.as(actor, input)` QUEUES; `executeJob` is the one execution path.
+- **One enqueue implementation**: `jobsFacade()` owns `enqueue` AND `enqueueMany`, over the row
+  builders in `enqueue-record.ts`, which the relay shares; the only other `driver.enqueue` sites are
+  the outbox relay and the scheduler. `handle.as(actor, input)` QUEUES; `executeJob` is the one execution path.
 - 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
@@ -125,11 +126,9 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **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.
+- **A cancelled body's writes refuse too**, `enqueue` included (`outbox-abandon.test.ts`); a store is on the pool: a fenced `put` past `X_DRAINING` lands.
 - **`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`.
+- **The scheduler runs one dispatch round at a time**; `stop()` waits it out before `leader.release()`. Full rule: `docs/history/jobs.md`.
 - **`run-once` fires ONE catch-up**: the watermark rides the fire (`ScheduledFire.watermarkMs`),
   never a `markFired` behind it; `skip` fires the latest missed occurrence (`latestOccurrenceBy`).
 - **A lease for a run that never STARTED is `abandon()`ed, never `release()`d** — the rate stamp
@@ -147,57 +146,12 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
 - **`x jobs cancel` binds to `cancelJob(driver, id, reason?)`, which refuses** a finished job or a
   driver with no `cancel` (`X_JOB_NOT_CANCELLABLE`).
 
-## Rules — the operator surface
+## Rules — long form in `docs/history/jobs.md`
 
-- **Every operator capability is a member of `JobIntrospection`** (`introspection.ts`), implemented
-  by BOTH drivers, bounds as constants beside it; `operator-surface*-fixture.ts` is their parity
-  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).
-  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.
-- **`taskFires()` is the last occurrence that DISPATCHED**, never the watermark (arming and skipping
-  move that): `SQL_SCHEDULER_FIRE` writes it, `fireThroughDriver` calls `recordTaskFire`.
-- **A pause is a ROW the claim reads** (`x_job_pauses`, `not exists` in `SQL_CLAIM`), never a column
-  on `x_jobs`. A paused TASK keeps its watermark, so resume is its own `catchUp`.
-- **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`, `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.
-
-## Rules — idle cost and the wake
-
-Long form: `docs/history/jobs.md`, "the cross-process wake".
-
-- **An idle round touches no store.** The scheduler keeps each watermark and its next occurrence in
-  memory while it leads (`known`), trusts a lease for `LeaderElection.renewEveryMs`, reads the pause
-  table only when a task is DUE, and folds counters every `COUNTER_ROLLUP_INTERVAL_MS`. What makes
-  the trust safe is the fire statement's watermark fence, never the lease.
-- **The worker and the relay back off** (`idle-backoff.ts`): floor → doubling → the ceiling, 2 s, or
-  5 s while `wakeIsLive()`. An idle worker pass is ONE claim over every queue with a free slot.
-- **The poll is the guarantee, the wake an optimisation.** `startQueueWake` holds one `LISTEN`
-  session and raises `enqueue-signal.ts`'s two signals; it is live only once a probe has crossed
-  BOTH channels, and un-proven on every re-dial — a transaction-pooling proxy resolves a `LISTEN`
-  and delivers nothing.
-- **A statement decides whether it notifies** (`driver-pg-wake-sql.ts`): once per queue per
-  `WAKE_SLOT_MS` for an enqueue, never behind an unclaimed row for a stage. Every notifying commit
-  serialises behind ONE Postgres lock: never notify unconditionally. Payload: the queue name.
-- **A wake resets the backoff**: the floor passes after it find the row a slot silenced.
-- **The claim loop is ONE chain** (`worker-loop.ts`): a wake on a pass in flight sets `again`; a
-  freed slot and a due retry (`JobExecution.resumeAt`) `kick` one pass, no reset.
-- **`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**: `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`.
+- "Moved out 2026-11-03": operator verbs on BOTH drivers; an idle round touches no store.
+- "Moved out 2026-11-06": `demand` with no worker registry; how the claim seeks.
+- "Plan 101 wave 6c": compensate ONLY failed for good; `once` writes `started` BEFORE `fn`; a
+  waking publish is ONE statement; payload org = enqueue org (`X_JOB_TENANT_MISMATCH`).
 
 ## Rules — the outbox
 
@@ -211,25 +165,33 @@ Long form: `docs/history/jobs.md`, "Moved 2026-10-01 — the outbox".
 - **A staged row's id IS its job's id, and its `runId` is allocated at stage** (`x_outbox.run_id`),
   so a staged enqueue answers real ids. `SQL_ENQUEUE` inserts nothing under an id that names a
   row — a repeated publish is `deduped`, live or finished (`outbox-run-id.test.ts`).
+- **The relay publishes a batch in two statements** (`publishBatch`): `driver.enqueueMany`, then
+  `markPublishedMany` when the store has it; any failure drops that batch to the row loop, which
+  keeps the order. `RELAY_BATCH_SIZE` (500) is measured in its doc comment.
 
 ## Rules — factories over `job()`
 
 Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-01 — factories".
 
-- **`backfill()`**: a step persists the CURSOR and a count, never the page; step names are positional;
-  **`handle` is AT LEAST ONCE** — never invert; a REPLAYED batch writes no ledger row. `tenant: 'none'`
-  is the only cross-tenant scope (`backfill-scope.ts`). `x_backfills` is what was SWEPT, keyed by RUN;
-  only `completed` blocks. The throttle is spent INSIDE the batch's `step.run`.
+- **`backfill()`**: a step persists the CURSOR, never the page; **`handle` is AT LEAST ONCE**. Full rule: `docs/history/jobs.md`.
 - **The ledger says what RAN, the registry what EXISTS, `backfill-pending.ts` is the diff.**
   `environments` is checked in `backfillPass()` and `gateBackfill()`; `requires` in `gateBackfill()`
   only; `count` after the last batch (`X_BACKFILL_STALLED`). `inspectBackfills()` is the ONE projection.
+- **`rollup()`/`refreshView()`**: ONE `upsertAll`; `rollup.job.test.ts`.
 - **`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.
+- **`importRows()`**: one step per PAGE, checkpointed at the BYTE OFFSET, no carry between steps;
+  `pageBytes` > `maxRecordBytes` is refused at declaration. `handle` is AT LEAST ONCE per page. The
+  error report never carries the refused value. NO cross-tenant escape.
+- **`webhookReceiver()`**: a plain `Route` read under `maxBytes` (core's `readWithinLimit`, never
+  `bodyBytes()`); `verify` runs before any parse and answers `{ eventId, payload }` from verified
+  data; the id is bounded (`WEBHOOK_EVENT_ID_PATTERN`, 422); the enqueue is `outbox: false` before
+  the ack (503 otherwise); the payload is stored `.sensitive()`, never re-verified.
+  `webhookReceiverRoutes()` is what the boots mount.
 - **`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.** An org
   tenant reads `orgId` OFF THE INPUT; none, or not the run's org: TERMINAL `X_JOB_TENANT_MISMATCH`.
-- A `-fixture.ts` file does not ship; `backfill-pass-fixture.ts` raises a plain `Error` on purpose.
 
 ## Files
 
@@ -246,18 +208,23 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `backfill-pending.ts` | declared minus completed, per environment: the alarm `--pending` reads |
 | `backfill-rate.ts` | the `rate` throttle: batches/sec as an interval, and the cancellable wait |
 | `backfill-inspect.ts` | the ledger projected for `x db backfill`, `x jobs`, `/_x` and MCP |
-| `backfill-errors.ts` | the seven `X_BACKFILL_*` classes; the codes stay declared in `errors.ts` |
+| `backfill-errors.ts` | the eight `X_BACKFILL_*` classes; the codes stay declared in `error-codes.ts` |
+| `backfill-definition.ts` / `backfill-source.ts` / `backfill-reader.ts` | the declaration types; exactly one of `source`/`pages`, the `<name>:<scope>` ledger key; reading either |
+| `consumer.ts` / `consumer-loop.ts` / `consumer-types.ts` | `consumer()` — a job + `.supervisor` task; one run's turns; the shapes |
+| `consumer-registry.ts` / `consumer-guard.ts` / `consumer-errors.ts` | the `origin` stamp + `registeredConsumers`; the self-enqueue refusal; `X_CONSUMER_*` |
 | `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 |
+| `steps.ts` / `-core.ts` / `-wait.ts` / `-unwind.ts` | replay runner; shared core; `waitForEvent`; compensation |
+| `steps-timeout.ts` / `steps-suspension.ts` | a step's ceiling; `StepSuspension`, `UnwindReached`, timeout marker |
+| `steps-api.ts` / `steps-store.ts` / `steps-output.ts` | `StepApi`, `EventLookup`; `StepRecord`, `StepFence`, `StepStore`; what a step answers, `StepOutput` and `jsonForm` |
+| `type-pins.ts` | compile-time pins for `StepOutput` and `waitForEvent` |
 | `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` | `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, `jobLeaseKey` |
 | `concurrency.ts` | `job.concurrency` as declared, resolved once: `KeyedConcurrency`, `WhenBusy`, the declaration and key refusals |
-| `errors-concurrency.ts` | every concurrency refusal's class; codes stay in `errors.ts` |
+| `errors-concurrency.ts` | every concurrency refusal's class; codes stay in `error-codes.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` | `postgresSchedulerState` (the durable watermark, the atomic fire) + `postgresLeaseLeader` |
@@ -270,6 +237,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `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: what the thrown error says, and the stop reason |
+| `execute-unwind.ts` / `execute-ctx.ts` | a saga failed for good; caller ctx |
 | `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 renewal interval and its `stopped()` latch |
@@ -288,7 +256,7 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `scheduler.ts` | `scheduler` role: the dispatch round, catch-up, leader election, the drain |
 | `limits.ts` | per-tenant / per-queue / global concurrency + rate |
 | `events.ts` | stored event bus for `step.waitForEvent` |
-| `inspect.ts` | `--json` introspection |
+| `inspect.ts` | `--json` introspection. `operatorInput`: no registered handle gives `[redacted]` whole; otherwise `redactInput(maskSensitive(handle.input, …))` |
 | `inspect-operator.ts` | the verbs `x jobs` binds: remove, promote, pause, resume |
 | `introspection.ts` | `JobIntrospection`, every operator type, and the bounds |
 | `counters.ts` | bucket arithmetic, `nackOutcome`, the memory counters |
@@ -303,6 +271,17 @@ Long form: [`docs/history/jobs.md`](../../docs/history/jobs.md), "Moved 2026-10-
 | `driver-pg-outbox-sql.ts` | the `x_outbox` statements |
 | `errors-operator.ts` / `errors-requeue.ts` | the operator verbs' refusals; `requeue`'s |
 | `errors-tenant.ts` | `JobTenantMismatchError` |
+| `errors-steps.ts` / `errors-saga.ts` / `step-resolve.ts` | step, saga + `once` refusals; `resolveStep` |
+| `worker-queue-demand.ts` | the `queue_demand` gauge: `driver.demand()`, skipped when `stats()` shows no work, retracted to 0 at the drain |
+| `driver-pg-demand-sql.ts` | `QUEUE_DEMAND_ROWS` and `SQL_QUEUE_DEMAND`; the scaler fixture's `SQL_SCALER_DEMAND` reads the same predicate |
+| `driver-pg-claim-sql.ts` | `SQL_CLAIM` and why it seeks; re-exported from `driver-pg-sql.ts` |
+| `error-codes.ts` / `errors.ts` | codes, titles, their registration (`new-error-code` writes here) / the classes |
+| `job-enqueue-many.ts` / `enqueue-record.ts` / `driver-pg-enqueue-many.ts` | `enqueueMany`, `MAX_ENQUEUE_BATCH`, `ENQUEUE_CHUNK`; one enqueue's row, every path; `SQL_ENQUEUE_MANY` + resolve |
+| `import.ts` / `import-pass.ts` | `importRows()`: the declaration; one pass, its byte-offset checkpoints, the error report |
+| `import-format.ts` / `import-source.ts` / `import-errors.ts` | record boundaries on bytes; the `ImportSource` seam; the `X_IMPORT_*` classes |
+| `driver-redis-refusal.ts` | `typedRefusals`: a send refused for want of a connection → `X_DRIVER_UNAVAILABLE` |
+| `subject*.ts` | `subjectExport`/`subjectErase`; reach only via DELETED tables (README) |
+| `webhook-receiver.ts` / `-route.ts` / `-types.ts` / `-errors.ts` | `webhookReceiver()` and `webhookReceiverRoutes`; the route; `ReceivedEvent`, `WebhookInbound`; its three refusals |
 
 Commands: `bun test packages/jobs` · `bun run --filter @ultimat3/jobs typecheck`. Test harnesses:
 history, "Moved 2026-10-01 — test harnesses".