@ultimat3/jobs 15.0.0 → 17.0.0

package/CLAUDE.md

@@ -107,6 +107,48 @@ Tier 3. The `job` + `task` primitives, durable steps, transactional outbox, queu
   `createWorker().start()` THROW `X_JOB_CONCURRENCY_UNENFORCEABLE` when a registered job declares
   `concurrency`: a documented guarantee that silently does nothing is the worst of the three
   options, and refusing is what axiom 3 asks for.
+- **`WorkerOptions.concurrency` is read by OWN key, because a queue NAME is deployment data**
+  (`worker.ts`, `As of 2026-08-26`). `options.concurrency?.[queue]` answered
+  `Object.prototype.constructor` for a queue called `constructor`, so
+  `Math.max(0, <function> - inFlight)` was `NaN`, the `free === 0` guard did not catch it, and the
+  pass issued `driver.claim({ limit: NaN })`. `bun run proto-index` cannot reach this one — the
+  table is a **parameter**, not an object literal in the file — so `worker-slots.test.ts` is the
+  enforcement, over `constructor`, `__proto__` and `toString` at once.
+- **Every numeric knob is refused when it is not a FINITE number** — `@ultimat3/core`'s
+  `finiteOption()` (a bound) and `finiteCount()` (a whole number of things, with the caller's
+  minimum) are the two refusals, and this package declares none of its own. `worker-options.ts` is
+  the one place `createWorker` reads them (`As of 2026-08-26`), and `createOutboxRelay` refuses its
+  own two.
+  Measured: `visibilityTimeoutMs: NaN` makes `visibleAt` `NaN`, the reclaim scan asks
+  `visibleAt <= now`, and a job whose worker DIED is never claimable again — at-least-once becomes
+  never, on a row `x jobs ls` still prints as `running`. `concurrency: NaN` slices `(0, NaN)`, so
+  the worker claims nothing and reports healthy; `pollIntervalMs: NaN` is `setTimeout(fn, 0)`, so
+  the claim loop spins on the database. `??` guards only nullish and `Math.max`/`Math.floor`
+  propagate `NaN`: `Number(process.env.X)` on an unset variable arrives intact. Same refusal
+  `createLimiter`'s `maxTenants` and `backfill()`'s `batch` already made.
+
+  **`bun run finite-bounds` is a floor, never the answer, and a pin of zero is not proof**
+  (`As of 2026-08-26`). It matches `x.y ?? CONST`, so it never saw `createLimiter`'s four
+  ceilings — read as `config.global !== undefined && global >= config.global`, a shape with no
+  `??` in it — and this package read as clean at **zero** while every one of them was off.
+  Measured: `createLimiter({ global: Number(process.env.WORKER_GLOBAL_CONCURRENCY) })` with the
+  variable unset granted **1000 of 1000** acquires where `global: 2` grants 2, and
+  `snapshot().config` still reported the ceiling to `/_x`. All five numbers (`perTenant`,
+  `perQueue`, `global`, `ratePerTenant.limit`, `ratePerTenant.windowMs` — the window is half the
+  same ceiling, since `stamp > at - NaN` empties it on every call) are screened at construction
+  beside `maxTenants`, `finiteCount` with **min 0**: zero is a HARD STOP here and one this repo's
+  own suite configures, never "unlimited", which is what omitting the option means.
+
+  **A row count is `finiteCount`, and the reason is driver parity** (`As of 2026-08-26`).
+  `finiteOption` accepts `-1` and `2.5`, and both diverge: `introspect.list({ limit: -1 })` sliced
+  every row BUT the newest on `driver-memory.ts` and Postgres answers `ERROR: LIMIT must not be
+  negative` (probed on pg18), while `2.5` keeps 2 rows here and **3** there with no error on either
+  side. `list`, `deadLetters`, the backfill ledger's `list` and `assertClaimBounds` (both drivers'
+  `claim`) take the count screen with **min 0** — `limit: 0` is zero rows on both — and
+  `claim`'s `visibilityTimeoutMs` takes `finiteOption`, because a lease window is a duration.
+  The memory driver's `list`/`deadLetters` are `async` for the reason `claim` is: a refusal must
+  REJECT on both, and a synchronous throw out of a method typed `Promise<…>` is itself the
+  divergence.
 - **`enqueuedBy` is ATTRIBUTION, never authority — decided 2026-08, do not re-litigate.** Both
   answers were defensible. Impersonating the enqueuer at claim time gives correct authz and is
   rejected because a job that sleeps three days, or dead-letters and is retried next quarter, then
@@ -850,7 +892,7 @@ picture from the other side.
 | `events-pg.ts` | `createPgEventBus` — `step.waitForEvent` across processes |
 | `driver.ts` | `JobDriver` contract + wire records |
 | `driver-pg.ts` | default driver, real SQL constants, and `createPgLeader` — the advisory-lock election that is **not** what a scheduler uses; `scheduler-pg.ts` above owns the lease-row one boot wires |
-| `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` + `SQL_OUTBOX_TABLE` — the schema the driver installs. Whichever file holds the DDL is the one whose comments may carry no `;` and no `'` |
+| `driver-pg-ddl.ts` | `SQL_JOBS_TABLE` — the schema the driver installs, and the ONE install point: every durable table this package owns, `x_outbox` included, is declared in it. Whichever file holds the DDL is the one whose comments may carry no `;` and no `'` |
 | `driver-pg-jobs-sql.ts` | every statement returning a whole `x_jobs` row, and the `JOB_ROW_COLUMNS` projection they share. Split off at `driver-pg-sql.ts`'s size ceiling and re-exported from it |
 | `driver-pg-rows.ts` | a Postgres row → a wire record: `JobRow`/`StepRow`/`BackfillRow` and their mappings |
 | `driver-memory.ts` | `x dev` / tests |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/jobs",
-  "version": "15.0.0",
+  "version": "17.0.0",
   "description": "Durable background work: steps, transactional outbox, cron tasks, one driver interface",
   "license": "MIT",
   "type": "module",
@@ -32,9 +32,9 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "15.0.0",
-    "@ultimat3/entity": "15.0.0",
-    "@ultimat3/schema": "15.0.0",
-    "@ultimat3/time": "15.0.0"
+    "@ultimat3/core": "17.0.0",
+    "@ultimat3/entity": "17.0.0",
+    "@ultimat3/schema": "17.0.0",
+    "@ultimat3/time": "17.0.0"
   }
 }

package/src/backfill-ledger.ts

@@ -10,7 +10,7 @@
 // become — the checkpoints are transactional with the work, and this row is not.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock } from '@ultimat3/core';
+import { finiteCount, systemClock } from '@ultimat3/core';
 import { nowMs } from './clock';
 
 /**
@@ -167,7 +167,8 @@ export function createMemoryBackfillLedger(clock: Clock = systemClock): Backfill
       });
       return Promise.resolve();
     },
-    list(filter = {}) {
+    // `async`, so a refused limit REJECTS here as it does on the pg ledger — see `driver-memory.ts`.
+    async list(filter = {}) {
       // Reversed BEFORE the sort: the test clock is frozen, so two rows share a `startedAt` and a
       // stable sort would hand back the oldest of them first under a "newest first" contract.
       const rows = [...runs.values()]
@@ -176,8 +177,8 @@ export function createMemoryBackfillLedger(clock: Clock = systemClock): Backfill
         .filter((run) => filter.name === undefined || run.name === filter.name)
         .filter((run) => filter.status === undefined || run.status === filter.status)
         .filter((run) => filter.runId === undefined || run.runId === filter.runId)
-        .slice(0, filter.limit ?? 100);
-      return Promise.resolve(rows);
+        .slice(0, finiteCount('the backfill ledger list', 'limit', filter.limit ?? 100));
+      return rows;
     },
   };
 }

package/src/driver-memory.ts

@@ -3,7 +3,7 @@
 // real claim/ack/nack paths rather than a mock that always succeeds.
 
 import type { Clock } from '@ultimat3/core';
-import { assert, systemClock, uuid } from '@ultimat3/core';
+import { assert, finiteCount, systemClock, uuid } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';
 import { createMemoryBackfillLedger } from './backfill-ledger';
 import { nowMs } from './clock';
@@ -20,7 +20,7 @@ import type {
   NackOptions,
   QueueStats,
 } from './driver';
-import { assertClaimQueues, DEFAULT_QUEUE } from './driver';
+import { assertClaimBounds, assertClaimQueues, DEFAULT_QUEUE } from './driver';
 import { JobDuplicateError } from './errors';
 import type { LeaseStore } from './leases';
 import { createMemoryLeaseStore } from './leases';
@@ -103,7 +103,10 @@ export function createMemoryDriver(options: MemoryDriverOptions = {}): MemoryJob
     job(jobId) {
       return Promise.resolve(jobs.get(jobId));
     },
-    list(filter: JobFilter = {}) {
+    // `async` for the reason `claim` is: a refused bound must REJECT here exactly as it does on the
+    // pg driver, and a synchronous throw out of a method typed `Promise<…>` is a second answer to
+    // one question.
+    async list(filter: JobFilter = {}) {
       const rows = [...jobs.values()]
         .filter((record) => filter.queue === undefined || record.queue === filter.queue)
         .filter((record) => filter.name === undefined || record.name === filter.name)
@@ -112,15 +115,15 @@ export function createMemoryDriver(options: MemoryDriverOptions = {}): MemoryJob
         // `x jobs ls` answered one thing against `x dev` and the opposite in production — and,
         // because the limit is applied after the sort, a default page of the hundred OLDEST rows.
         .sort((a, b) => b.createdAt - a.createdAt)
-        .slice(0, filter.limit ?? 100);
-      return Promise.resolve(rows);
+        .slice(0, finiteCount('the memory driver list', 'limit', filter.limit ?? 100));
+      return rows;
     },
-    deadLetters(limit = 100) {
+    async deadLetters(limit = 100) {
       const rows = [...jobs.values()]
         .filter((record) => record.state === 'dead')
         .sort((a, b) => b.updatedAt - a.updatedAt)
-        .slice(0, limit);
-      return Promise.resolve(rows);
+        .slice(0, finiteCount('the memory driver dead letters', 'limit', limit));
+      return rows;
     },
     async requeue(jobId, requeueOptions) {
       const existing = jobs.get(jobId);
@@ -199,6 +202,7 @@ export function createMemoryDriver(options: MemoryDriverOptions = {}): MemoryJob
     // question, which is the class of divergence this pair is checked for.
     async claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
       assertClaimQueues('memory', claimOptions);
+      assertClaimBounds('memory', claimOptions);
       const at = nowMs(clock);
       const wanted = new Set(claimOptions.queues);
       const claimable = [...jobs.values()]

package/src/driver-pg-ddl.ts

@@ -177,29 +177,3 @@ create table if not exists x_job_events (
 create index if not exists x_job_events_lookup_idx
   on x_job_events (name, published_at);
 `.trim();
-
-/**
- * Kept as its own constant because it is a public export and `x_outbox` is a table an operator
- * may need to create alone. It is ALSO inside `SQL_JOBS_TABLE`, which is the one boot applies —
- * two install points for one table is how the outbox came to be documented and never created.
- */
-export const SQL_OUTBOX_TABLE = `
-create table if not exists x_outbox (
-  id              uuid primary key,
-  job             text        not null,
-  queue           text        not null default 'default',
-  input           jsonb       not null,
-  idempotency_key text        not null,
-  max_attempts    int         not null default 3,
-  run_at          timestamptz not null default now(),
-  staged_at       timestamptz not null default now(),
-  tenant_id       text,
-  traceparent     text,
-  enqueued_by     text,
-  published_at    timestamptz
-);
-create index if not exists x_outbox_unpublished_idx
-  on x_outbox (staged_at) where published_at is null;
-alter table x_outbox add column if not exists claimed_at timestamptz;
-alter table x_outbox add column if not exists claimed_by text;
-`.trim();

package/src/driver-pg-sql.ts

@@ -7,7 +7,7 @@
 // it is applied once at boot and never by a driver method. Re-exported from here so the install
 // point keeps the ONE import path every caller already uses.
 
-export { SQL_JOBS_TABLE, SQL_OUTBOX_TABLE } from './driver-pg-ddl';
+export { SQL_JOBS_TABLE } from './driver-pg-ddl';
 // The whole-`x_jobs`-row reads, split off at this file's size ceiling and re-exported for the
 // same reason the DDL is. `JOB_ROW_COLUMNS` is imported as a value because `SQL_CANCEL` also
 // returns a whole row and must project it identically — two spellings of one row shape is how

package/src/driver-pg.ts

@@ -5,7 +5,7 @@
 // they run against in `driver-pg-ddl.ts`, and the row-to-record decoding in `driver-pg-rows.ts`.
 
 import type { Clock } from '@ultimat3/core';
-import { systemClock, uuid } from '@ultimat3/core';
+import { finiteCount, systemClock, uuid } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';
 import { nowMs } from './clock';
 import type {
@@ -20,7 +20,7 @@ import type {
   NackOptions,
   QueueStats,
 } from './driver';
-import { assertClaimQueues, DEFAULT_QUEUE } from './driver';
+import { assertClaimBounds, assertClaimQueues, DEFAULT_QUEUE } from './driver';
 import type { BackfillRow, JobRow, StepRow } from './driver-pg-rows';
 import { num, toBackfillRun, toJobRecord, toStepRecord } from './driver-pg-rows';
 import {
@@ -135,7 +135,7 @@ function pgBackfillLedger(exec: () => PgExecutor): BackfillLedger {
         filter.name ?? null,
         filter.status ?? null,
         filter.runId ?? null,
-        filter.limit ?? 100,
+        finiteCount('the pg driver list', 'limit', filter.limit ?? 100),
       ]);
       return rows.map(toBackfillRun);
     },
@@ -200,12 +200,14 @@ export function createPgDriver(options: PgDriverOptions = {}): JobDriver {
         filter.queue ?? null,
         filter.name ?? null,
         filter.state ?? null,
-        filter.limit ?? 100,
+        finiteCount('the pg driver list', 'limit', filter.limit ?? 100),
       ]);
       return rows.map(toJobRecord);
     },
     async deadLetters(limit = 100) {
-      const rows = await exec().query<JobRow>(SQL_JOB_DEAD_LETTERS, [limit]);
+      const rows = await exec().query<JobRow>(SQL_JOB_DEAD_LETTERS, [
+        finiteCount('the pg driver dead letters', 'limit', limit),
+      ]);
       return rows.map(toJobRecord);
     },
     async requeue(jobId, requeueOptions) {
@@ -293,6 +295,7 @@ export function createPgDriver(options: PgDriverOptions = {}): JobDriver {
 
     async claim(claimOptions: ClaimOptions): Promise<readonly ClaimedJob[]> {
       assertClaimQueues('pg', claimOptions);
+      assertClaimBounds('pg', claimOptions);
       const rows = await exec().query<JobRow>(SQL_CLAIM, [
         claimOptions.queues,
         claimOptions.limit,

package/src/driver.ts

@@ -8,6 +8,7 @@
 // `X_NOT_IMPLEMENTED` stubs. What IS true is the second half — swapping the driver is
 // `setJobDriver(other)` and ZERO job-code change — and that is what the interface buys.
 
+import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';
 import { ClaimQueuesEmptyError } from './errors';
 import type { LeaseStore } from './leases';
@@ -270,3 +271,20 @@ export function resetJobDriver(): void {
 export const assertClaimQueues = (driver: string, options: ClaimOptions): void => {
   if (options.queues.length === 0) throw new ClaimQueuesEmptyError(driver);
 };
+
+/**
+ * The two NUMBERS of a claim, screened for both drivers in one place for the reason above: a value
+ * neither of them refuses is answered two ways. `limit: -1` sliced every ready row but the newest
+ * into a lease on the memory driver, where Postgres answers `LIMIT must not be negative`; `2.5`
+ * claims 2 rows here and 3 there, with no error on either side.
+ *
+ * `limit` is a COUNT of rows and takes zero — claiming nothing is what a full worker asks for, and
+ * both drivers already answer it identically. `visibilityTimeoutMs` is a DURATION, so it is
+ * screened for finiteness alone, the same rule `worker-options.ts` applies to the same knob: it is
+ * on this list because `visibleAt = at + NaN` is never `<= now`, which turns at-least-once into
+ * never on a row `x jobs ls` still prints as `running`.
+ */
+export const assertClaimBounds = (driver: string, options: ClaimOptions): void => {
+  finiteCount(`the ${driver} driver claim`, 'limit', options.limit);
+  finiteOption(`the ${driver} driver claim`, 'visibilityTimeoutMs', options.visibilityTimeoutMs);
+};

package/src/events-pg.ts

@@ -7,7 +7,7 @@
 // resumes at 12:00:30 must still see an event published at 12:00:10.
 
 import type { Clock } from '@ultimat3/core';
-import { logger, renderThrowable, systemClock, uuid } from '@ultimat3/core';
+import { finiteOption, logger, renderThrowable, systemClock, uuid } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { nowMs, toMs } from './clock';
 import type { PgExecutor } from './driver-pg';
@@ -46,8 +46,15 @@ export interface PgEventBusOptions {
  */
 export function createPgEventBus(options: PgEventBusOptions): EventBus {
   const clock = options.clock ?? systemClock;
-  const defaultTtl = options.defaultTtl ?? 604_800_000;
-  const listLimit = options.listLimit ?? 1_000;
+  // TWO screens, for the reason `events.ts` states: `defaultTtl` is the constructor's knob and
+  // `ttl` is the publish call's, so one screen over `ttl ?? defaultTtl` names the wrong one for
+  // whichever value actually arrived.
+  const defaultTtlMs = finiteOption(
+    'the pg event bus',
+    'defaultTtl',
+    toMs(options.defaultTtl ?? 604_800_000),
+  );
+  const listLimit = finiteOption('the pg event bus', 'listLimit', options.listLimit ?? 1_000);
   const exec = options.executor;
 
   const purgeExpired = (): number => {
@@ -68,7 +75,11 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
         name,
         payload,
         publishedAt: at,
-        expiresAt: at + toMs(publishOptions.ttl ?? defaultTtl),
+        expiresAt:
+          at +
+          (publishOptions.ttl === undefined
+            ? defaultTtlMs
+            : finiteOption('the pg event bus', 'ttl', toMs(publishOptions.ttl))),
         ...(publishOptions.correlationKey === undefined
           ? {}
           : { correlationKey: publishOptions.correlationKey }),

package/src/events.ts

@@ -3,7 +3,7 @@
 // 12:00:10, so a fire-and-forget emitter would silently strand every waiting run.
 
 import type { Clock } from '@ultimat3/core';
-import { logger, systemClock, uuid } from '@ultimat3/core';
+import { finiteOption, logger, systemClock, uuid } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { nowMs, toMs } from './clock';
 import type { EventLookup } from './steps';
@@ -39,8 +39,17 @@ export interface MemoryEventBusOptions {
 
 export function createMemoryEventBus(options: MemoryEventBusOptions = {}): EventBus {
   const clock = options.clock ?? systemClock;
-  const defaultTtl = options.defaultTtl ?? 604_800_000;
-  const maxEvents = options.maxEvents ?? 10_000;
+  // TWO screens, because these are two knobs: the default is declared at construction and belongs
+  // to whoever built the bus, `ttl` rides the publish CALL. One screen over `ttl ?? defaultTtl`
+  // told a caller who wrote `{ ttl: NaN }` to "pass a finite defaultTtl" — an instruction naming an
+  // option they never set, on a constructor usually in another file. `steps.ts` names `timeout` for
+  // the same value shape.
+  const defaultTtlMs = finiteOption(
+    'the memory event bus',
+    'defaultTtl',
+    toMs(options.defaultTtl ?? 604_800_000),
+  );
+  const maxEvents = finiteOption('the memory event bus', 'maxEvents', options.maxEvents ?? 10_000);
   const events = new Map<string, JobEvent>();
 
   const purgeExpired = (): number => {
@@ -64,7 +73,11 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
         name,
         payload,
         publishedAt: at,
-        expiresAt: at + toMs(publishOptions.ttl ?? defaultTtl),
+        expiresAt:
+          at +
+          (publishOptions.ttl === undefined
+            ? defaultTtlMs
+            : finiteOption('the memory event bus', 'ttl', toMs(publishOptions.ttl))),
         ...(publishOptions.correlationKey === undefined
           ? {}
           : { correlationKey: publishOptions.correlationKey }),

package/src/index.ts

@@ -101,6 +101,7 @@ export type {
   QueueStats,
 } from './driver';
 export {
+  assertClaimBounds,
   assertClaimQueues,
   DEFAULT_QUEUE,
   DEFAULT_VISIBILITY_TIMEOUT_MS,
@@ -138,7 +139,6 @@ export {
   SQL_OUTBOX_MARK_PUBLISHED,
   SQL_OUTBOX_RELEASE,
   SQL_OUTBOX_STAGE,
-  SQL_OUTBOX_TABLE,
   SQL_SCHEDULER_STATE_GET,
   SQL_SCHEDULER_STATE_MARK,
   SQL_STATS,

package/src/limits.ts

@@ -12,7 +12,7 @@
 // what `job.concurrency` is enforced with.
 
 import type { Clock } from '@ultimat3/core';
-import { assert, systemClock } from '@ultimat3/core';
+import { assert, finiteCount, systemClock } from '@ultimat3/core';
 import { nowMs } from './clock';
 
 export interface RateLimit {
@@ -126,6 +126,27 @@ export function createLimiter(
   );
   const maxTenants = Math.max(1, Math.floor(requested));
   const evictTo = Math.max(1, Math.floor(maxTenants * 0.9));
+  // The ceilings this limiter ENFORCES, screened where they are declared — the refusal `maxTenants`
+  // above already makes, for a sharper reason: every one of them is read as
+  // `config.x !== undefined && count >= config.x`, so a `NaN` leaves the option PRESENT and the
+  // comparison false forever. Measured: `global: Number(process.env.WORKER_GLOBAL_CONCURRENCY)`
+  // with the variable unset granted 1000 of 1000 acquires while `snapshot().config` still reported
+  // a configured ceiling. `ratePerTenant.windowMs` is on the list because it is half the same
+  // ceiling: `stamp > at - NaN` is false for every stamp, so the window reads empty on every call.
+  //
+  // `min` is 0 on all five, deliberately: zero is a HARD STOP here and one this repo's own suite
+  // configures (`limits-bound.test.ts`'s `{ perTenant: 0 }`), never "unlimited" — omitting the
+  // option is what means that. A count is whole because these are SLOTS: `global: 2.5` granted 3,
+  // which is a ceiling nobody wrote.
+  for (const [option, value] of [
+    ['perTenant', config.perTenant],
+    ['perQueue', config.perQueue],
+    ['global', config.global],
+    ['ratePerTenant.limit', config.ratePerTenant?.limit],
+    ['ratePerTenant.windowMs', config.ratePerTenant?.windowMs],
+  ] as const) {
+    if (value !== undefined) finiteCount('createLimiter', option, value);
+  }
   const byQueue = new Map<string, number>();
   const byTenant = new Map<string, number>();
   // `{queue, tenantId}` is ONE key — `blockedBy` has always read it that way. Without this counter

package/src/outbox.ts

@@ -24,7 +24,14 @@
 // test and `x dev` must enqueue with nothing wired — but it is a fallback, not the guarantee.
 
 import type { Clock } from '@ultimat3/core';
-import { currentSpanContext, logger, renderThrowable, traceparent, uuid } from '@ultimat3/core';
+import {
+  assert,
+  currentSpanContext,
+  logger,
+  renderThrowable,
+  traceparent,
+  uuid,
+} from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import type { EnqueueResult, JobDriver } from './driver';
@@ -383,6 +390,18 @@ export interface OutboxRelay {
 export function createOutboxRelay(options: RelayOptions): OutboxRelay {
   const batchSize = options.batchSize ?? 100;
   const intervalMs = options.intervalMs ?? 200;
+  // Refused, never clamped — `worker-options.ts` carries the reason. `setInterval(fn, NaN)` reads
+  // the delay as 0 and `claim(NaN)` slices `(0, NaN)`: a relay that spins and publishes nothing.
+  assert(
+    Number.isSafeInteger(batchSize) && batchSize >= 1,
+    `createOutboxRelay batchSize is ${String(batchSize)} — a batch is a whole number of staged rows, at least one`,
+    'pass a finite batchSize to createOutboxRelay(...), or omit it for the default 100',
+  );
+  assert(
+    Number.isFinite(intervalMs) && intervalMs >= 0,
+    `createOutboxRelay intervalMs is ${String(intervalMs)}, which setInterval reads as 0 — the relay would spin, not poll`,
+    'pass a finite intervalMs to createOutboxRelay(...), or omit it for the default 200',
+  );
   let timer: ReturnType<typeof setInterval> | undefined;
   let running = false;
   /** The pass in flight, so `stop()` joins it instead of returning underneath it. */

package/src/scheduler-pg.ts

@@ -4,7 +4,7 @@
 // pod it replaced dropped, and two pods in a rolling update both dispatch every task.
 
 import type { Clock } from '@ultimat3/core';
-import { uuid } from '@ultimat3/core';
+import { finiteOption, uuid } from '@ultimat3/core';
 import { nowMs } from './clock';
 import type { PgExecutor } from './driver-pg';
 import {
@@ -70,7 +70,11 @@ export const DEFAULT_LEADER_TTL_MS = 30_000;
 export function createPgLeaseLeader(options: PgLeaseLeaderOptions): LeaderElection {
   const lockKey = options.lockKey ?? 'scheduler';
   const holder = options.holder ?? `scheduler-${uuid()}`;
-  const ttlMs = options.ttlMs ?? DEFAULT_LEADER_TTL_MS;
+  const ttlMs = finiteOption(
+    'the pg scheduler lease',
+    'ttlMs',
+    options.ttlMs ?? DEFAULT_LEADER_TTL_MS,
+  );
   return {
     async acquire() {
       const rows = await options.executor.query<{ holder: string }>(SQL_LEADER_ACQUIRE, [

package/src/scheduler.ts

@@ -21,7 +21,7 @@
 // over the same `lastFiredAt`.
 
 import type { Clock } from '@ultimat3/core';
-import { isUltimateError, logger, onShutdown, renderThrowable } from '@ultimat3/core';
+import { finiteOption, isUltimateError, logger, onShutdown, renderThrowable } from '@ultimat3/core';
 import { instant, nextCronOccurrence } from '@ultimat3/time';
 import { nowMs } from './clock';
 import { settleAllBy } from './drain-wait';
@@ -115,7 +115,11 @@ export interface Scheduler {
 export function createScheduler(options: SchedulerOptions): Scheduler {
   const schedulerState = options.state ?? createMemorySchedulerState();
   const resolveCron = options.cron ?? defaultCronResolver;
-  const tickIntervalMs = options.tickIntervalMs ?? 1_000;
+  const tickIntervalMs = finiteOption(
+    'createScheduler',
+    'tickIntervalMs',
+    options.tickIntervalMs ?? 1_000,
+  );
   const leader = options.leader ?? soleLeader();
   let timer: ReturnType<typeof setTimeout> | undefined;
   let isLeader = false;

package/src/steps.ts

@@ -7,7 +7,7 @@
 // catches it and re-queues the job for `resumeAt` instead of holding a process for three days.
 
 import type { Clock } from '@ultimat3/core';
-import { logger, renderThrowable } from '@ultimat3/core';
+import { finiteOption, logger, renderThrowable } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { nowMs, toMs } from './clock';
 import { JobAbortedError, JobTimeoutError, StepDuplicateError } from './errors';
@@ -199,7 +199,7 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
   const used: string[] = [];
   const replayed: string[] = [];
   const clock = options.clock;
-  const pollMs = options.eventPollMs ?? 30_000;
+  const pollMs = finiteOption('step.waitForEvent', 'eventPollMs', options.eventPollMs ?? 30_000);
   const runSignal = options.signal ?? NEVER_ABORTED;
 
   /**
@@ -387,7 +387,9 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
 
     const at = now();
     const startedAt = existing?.startedAt ?? at;
-    const deadline = startedAt + toMs(waitOptions.timeout ?? 86_400_000);
+    const deadline =
+      startedAt +
+      finiteOption('step.waitForEvent', 'timeout', toMs(waitOptions.timeout ?? 86_400_000));
     const correlationKey = waitOptions.match;
 
     const hit = await options.events?.find(event, correlationKey, startedAt);
@@ -411,7 +413,11 @@ export function createStepRunner(options: StepRunnerOptions): StepRunner {
         throw new JobTimeoutError({
           job: jobName,
           step: name,
-          timeoutMs: toMs(waitOptions.timeout ?? 86_400_000),
+          timeoutMs: finiteOption(
+            'step.waitForEvent',
+            'timeout',
+            toMs(waitOptions.timeout ?? 86_400_000),
+          ),
         });
       }
       logger.warn('jobs.step.wait-timeout', { job: jobName, step: name, event });

package/src/webhook.ts

@@ -17,6 +17,7 @@
 
 import type { Clock, Ctx } from '@ultimat3/core';
 import {
+  finiteOption,
   isCanonicalWebhookField,
   renderThrowable,
   systemClock,
@@ -169,7 +170,11 @@ const isRetryableStatus = (status: number): boolean =>
 
 export function webhook(definition: WebhookDefinition): JobHandle<WebhookDeliveryInput> {
   const clock = definition.clock ?? systemClock;
-  const disableAfter = definition.disableAfter ?? DEFAULT_WEBHOOK_DISABLE_AFTER;
+  const disableAfter = finiteOption(
+    'webhook()',
+    'disableAfter',
+    definition.disableAfter ?? DEFAULT_WEBHOOK_DISABLE_AFTER,
+  );
   const send = definition.fetch ?? ((url, init) => fetch(url, init));
 
   return job<WebhookDeliveryInput>({

package/src/worker-options.ts

@@ -0,0 +1,73 @@
+// Every numeric knob `createWorker` accepts, read and REFUSED in one place — the slot table
+// included, because a queue name is data and a slot count is a bound, and both arrive from the
+// same deployment config.
+//
+// WHY A REFUSAL AND NOT A CLAMP. `Number(process.env.JOB_VISIBILITY_MS)` on an unset variable is
+// `NaN`; `??` guards only nullish, and `Math.max`/`Math.min`/`Math.floor` PROPAGATE it. So the
+// value arrives at a lease deadline, a claim limit and a timer interval intact, and every
+// comparison against it reads FALSE — measured on `createMemoryDriver`: `visibleAt = at + NaN`,
+// the reclaim scan asks `visibleAt <= at`, and a job whose worker died is never claimable again.
+// At-least-once becomes never, with no error and a row `x jobs ls` still prints as `running`.
+// `slice(0, NaN)` is `[]`, so a `concurrency: NaN` worker claims nothing and reports healthy.
+// Same shape as `createLimiter`'s `maxTenants` and `backfill()`'s `batch`, refused the same way.
+
+import { finiteOption } from '@ultimat3/core';
+import { DEFAULT_VISIBILITY_TIMEOUT_MS } from './driver';
+
+/** Slots a queue gets when `concurrency` names no number for it. */
+const DEFAULT_SLOTS = 5;
+
+/** The subset of `WorkerOptions` this module reads. Structural, so `WorkerOptions` satisfies it. */
+export interface WorkerNumericOptions {
+  readonly concurrency?: number | Readonly<Record<string, number>> | undefined;
+  readonly visibilityTimeoutMs?: number | undefined;
+  readonly pollIntervalMs?: number | undefined;
+  readonly heartbeatIntervalMs?: number | undefined;
+}
+
+export interface WorkerTimings {
+  readonly visibilityTimeoutMs: number;
+  readonly pollIntervalMs: number;
+  readonly heartbeatIntervalMs: number;
+  /** Slots for one queue, by OWN key — see `slotsFor` below. */
+  readonly slotsFor: (queue: string) => number;
+}
+
+/**
+ * Slots for one queue. A queue NAME is deployment data, so the table is read by OWN keys:
+ * `concurrency['constructor']` answers `Object.prototype.constructor`, and
+ * `Math.max(0, <function> - inFlight)` is `NaN`, which the `free === 0` guard does not catch.
+ * `bun run proto-index` cannot see this one — the table is a parameter, not a literal in a file.
+ */
+const slotTable =
+  (declared: number | Readonly<Record<string, number>> | undefined) =>
+  (queue: string): number => {
+    if (typeof declared === 'number') return declared;
+    if (declared === undefined || !Object.hasOwn(declared, queue)) return DEFAULT_SLOTS;
+    return declared[queue] ?? DEFAULT_SLOTS;
+  };
+
+export function resolveWorkerTimings(options: WorkerNumericOptions): WorkerTimings {
+  const visibilityTimeoutMs = options.visibilityTimeoutMs ?? DEFAULT_VISIBILITY_TIMEOUT_MS;
+  finiteOption('createWorker', 'visibilityTimeoutMs', visibilityTimeoutMs);
+  const pollIntervalMs = options.pollIntervalMs ?? 250;
+  // `setTimeout(fn, NaN)` coerces the delay to 0, so the claim loop stops being a poll and becomes
+  // a spin: one round trip to Postgres per event-loop turn, from every worker replica.
+  finiteOption('createWorker', 'pollIntervalMs', pollIntervalMs);
+  const heartbeatIntervalMs = options.heartbeatIntervalMs ?? Math.floor(visibilityTimeoutMs / 3);
+  finiteOption('createWorker', 'heartbeatIntervalMs', heartbeatIntervalMs);
+  const declared = options.concurrency;
+  if (typeof declared === 'number') finiteOption('createWorker', 'concurrency', declared);
+  else if (declared !== undefined) {
+    // Per queue, by own key: an inherited member is not this table's to answer with either.
+    for (const queue of Object.keys(declared)) {
+      finiteOption('createWorker', `concurrency.${queue}`, declared[queue] ?? DEFAULT_SLOTS);
+    }
+  }
+  return {
+    visibilityTimeoutMs,
+    pollIntervalMs,
+    heartbeatIntervalMs,
+    slotsFor: slotTable(declared),
+  };
+}

package/src/worker.ts

@@ -16,7 +16,7 @@ import {
 import { nowMs } from './clock';
 import { settleAllBy } from './drain-wait';
 import type { ClaimedJob, JobDriver, QueueStats } from './driver';
-import { DEFAULT_QUEUE, DEFAULT_VISIBILITY_TIMEOUT_MS } from './driver';
+import { DEFAULT_QUEUE } from './driver';
 import { ConcurrencyUnenforceableError } from './errors';
 import type { JobExecution, JobOutcome } from './execute';
 import { getJob, registeredJobs } from './job';
@@ -25,6 +25,7 @@ import { createLimiter } from './limits';
 import { recordQueueDeadJobs, recordQueueOldestReady } from './metrics';
 import type { EventLookup } from './steps';
 import { createFleetSlots } from './worker-fleet-slots';
+import { resolveWorkerTimings } from './worker-options';
 import { runClaimedJob } from './worker-run';
 
 /**
@@ -89,13 +90,10 @@ export interface Worker {
 export function createWorker(options: WorkerOptions): Worker {
   const workerId = options.workerId ?? `worker-${uuid()}`;
   const queues = options.queues ?? [DEFAULT_QUEUE];
-  const visibilityTimeoutMs = options.visibilityTimeoutMs ?? DEFAULT_VISIBILITY_TIMEOUT_MS;
-  const pollIntervalMs = options.pollIntervalMs ?? 250;
-  const heartbeatIntervalMs = options.heartbeatIntervalMs ?? Math.floor(visibilityTimeoutMs / 3);
-  const slotsFor = (queue: string): number =>
-    typeof options.concurrency === 'number'
-      ? options.concurrency
-      : (options.concurrency?.[queue] ?? 5);
+  // Every numeric knob, read and refused in one place — `worker-options.ts` says why a non-finite
+  // one is a refusal rather than a clamp, and carries the slot table's own-key read with it.
+  const { visibilityTimeoutMs, pollIntervalMs, heartbeatIntervalMs, slotsFor } =
+    resolveWorkerTimings(options);
   const limiter = options.limiter ?? createLimiter({});
   const driverLeases = options.driver.leases;
   // `job.concurrency`, held as a row every replica sees. The TTL is the visibility timeout and the