@ultimat3/jobs 23.0.0 → 25.0.0

package/src/introspection.ts

@@ -68,7 +68,12 @@ export interface JobFilter {
   readonly tenantId?: string;
 }
 
-const CURSOR = /^(\d{1,16}):([0-9A-Za-z-]{1,64})$/;
+/**
+ * `<createdAt ms>:<job id>`, and the id is a UUID in its one canonical shape. The group accepted
+ * any 1-64 letters, digits and hyphens, which the memory driver compared as text and the pg
+ * statement CAST: `123:not-a-uuid` was an empty page here and a raw `22P02` there.
+ */
+const CURSOR = /^(\d{1,16}):([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
 
 /** The cursor a page's LAST row yields. A page shorter than its limit is the last page. */
 export function jobCursor(record: Pick<JobRecord, 'createdAt' | 'id'>): string {
@@ -76,11 +81,12 @@ export function jobCursor(record: Pick<JobRecord, 'createdAt' | 'id'>): string {
 }
 
 export function parseJobCursor(
-  after: string,
+  raw: string,
   subject = 'the job list',
+  cursor: 'after' | 'before' = 'after',
 ): { readonly createdAt: number; readonly id: string } {
-  const match = CURSOR.exec(after);
-  if (match === null) throw new JobPageInvalidError({ subject, maxPage: MAX_JOB_PAGE });
+  const match = CURSOR.exec(raw);
+  if (match === null) throw new JobPageInvalidError({ subject, maxPage: MAX_JOB_PAGE, cursor });
   return { createdAt: Number(match[1]), id: match[2] ?? '' };
 }
 
@@ -108,7 +114,11 @@ export const PROMOTABLE_STATES: ReadonlySet<JobState> = new Set<JobState>(['read
 export interface BulkResult {
   /** Rows this call changed — at most `MAX_BULK_ROWS`. */
   readonly affected: number;
-  /** Rows still matching the filter afterwards. Call again until it is zero. */
+  /**
+   * Rows the SAME call would still act on afterwards — so "call again until it is zero" ends. A
+   * row the verb leaves where it is (a requeue whose key a live job holds, a promote of a row
+   * already due) is not counted: it will be skipped on every later call too.
+   */
   readonly remaining: number;
 }
 
@@ -183,16 +193,17 @@ export interface JobIntrospection {
   list(filter?: JobFilter): Promise<readonly JobRecord[]>;
   deadLetters(limit?: number): Promise<readonly JobRecord[]>;
   /**
-   * Re-queue a finished job (`REQUEUEABLE_STATES`); a live one is `X_JOB_NOT_REQUEUEABLE`, and a
-   * key a live job holds is `X_JOB_DUPLICATE`. `fromStep` drops that step and every step that
-   * started after it.
+   * Re-queue a finished job (`REQUEUEABLE_STATES`); a live one is `X_JOB_NOT_REQUEUEABLE`, a key a
+   * live job holds is `X_JOB_DUPLICATE`, and an id nobody queued is `X_JOB_NOT_FOUND`. `fromStep`
+   * drops that step and every step that started after it, with the row's own move.
    */
   requeue(jobId: string, options?: { readonly fromStep?: string }): Promise<JobRecord>;
   /**
    * Stop a job from outside. Terminal for a queued row immediately; a RUNNING one stops at its
    * next heartbeat, which no longer matches its own row and cancels the attempt. Answers
-   * `undefined` for a job id it does not hold or one that already finished. Optional, as it
-   * shipped: a driver may have no way to address a single running row.
+   * `undefined` for a job id it does not hold or one that is not LIVE (`LIVE_STATES`) — a done,
+   * failed, dead or already cancelled row is left exactly as it ended. Optional, as it shipped: a
+   * driver may have no way to address a single running row.
    */
   cancel?(jobId: string, reason?: string): Promise<JobRecord | undefined>;
   /**
@@ -203,7 +214,8 @@ export interface JobIntrospection {
   remove(jobId: string): Promise<JobRecord | undefined>;
   /**
    * Re-queue up to `MAX_BULK_ROWS` finished jobs. `filter.state` must be a requeueable state. A
-   * row whose key a live job holds is left where it is and counted in `remaining`.
+   * row whose key a live job holds is left where it is and is NOT counted in `remaining`; of
+   * several finished rows sharing one key, the oldest is the one requeued.
    */
   requeueMany(filter: BulkFilter): Promise<BulkResult>;
   /** Delete up to `MAX_BULK_ROWS` jobs. `filter.state` may be any state but `running`. */

package/src/job.ts

@@ -8,7 +8,7 @@
 // deletes that class of bug: there is no way to define a job that cannot be deduped.
 
 import type { Ctx } from '@ultimat3/core';
-import { assert } from '@ultimat3/core';
+import { assert, finiteCount } from '@ultimat3/core';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { parse } from '@ultimat3/schema';
 import type { DurationInput } from './clock';
@@ -101,7 +101,7 @@ export interface JobDefinition<I, R = unknown> {
    *
    * Enforced by `JobDriver.leases` — a row every replica can see — and NOT by `limits.ts`, which
    * counts one process's heap. A driver with no lease store cannot hold this cap, so
-   * `createWorker().start()` refuses to boot rather than let it pass silently
+   * `jobWorker().start()` refuses to boot rather than let it pass silently
    * (`X_JOB_CONCURRENCY_UNENFORCEABLE`): this field was declared, documented and in the manifest
    * while nothing read it, which is exactly what axiom 3 exists to prevent.
    */
@@ -266,11 +266,10 @@ export function job<I, R = unknown>(definition: JobDefinition<I, R>): JobHandle<
     throw new JobDeclarationInvalidError({ job: name, missing });
   }
   assertJobTenant(name, definition.tenant);
-  assert(
-    definition.retry.attempts >= 1,
-    `job "${name}" needs retry.attempts >= 1, got ${String(definition.retry.attempts)}`,
-    `set retry: { attempts: 1 } or higher on job("${name}") — 0 attempts means the job is never executed at all, not that it never retries`,
-  );
+  // A COUNT, so whole and finite as well as at least 1: `>= 1` alone admitted `Infinity` and
+  // `1.5`, which the memory driver ran and Postgres refused at the first enqueue (`$7::int`).
+  // Zero is not "never retries" — that is `attempts: 1` — it is a job that never executes at all.
+  finiteCount(`job "${name}"`, 'retry.attempts', definition.retry.attempts, 1);
   // `concurrency: 0` is not "no cap" — it is a fleet slot table that grants nothing, and the job
   // is permanently unrunnable with no log line. Refused where it is written, plain or keyed.
   const concurrency = resolveConcurrency(name, definition.concurrency);

package/src/leases.ts

@@ -57,7 +57,7 @@ export interface MemoryLeaseStore extends LeaseStore {
  * memory driver enforces `concurrency` with the same code path the pg driver does, and so the
  * "a second worker is refused" test is a real test rather than a pg-only one.
  */
-export function createMemoryLeaseStore(options: MemoryLeaseStoreOptions = {}): MemoryLeaseStore {
+export function memoryLeaseStore(options: MemoryLeaseStoreOptions = {}): MemoryLeaseStore {
   const clock = options.clock ?? systemClock;
   type Slots = Map<number, { holder: string; expiresAt: number }>;
   const slots = new Map<string, Slots>();

package/src/limits.ts

@@ -44,11 +44,21 @@ export interface LimitKey {
   readonly tenantId?: string;
 }
 
-/** Returned on success; `release()` is idempotent so a double-release cannot leak slots. */
+/**
+ * Returned on success. Handed back exactly once, by whichever of the two is called first — the
+ * other, and any repeat, is a no-op, so a double hand-back cannot leak a slot or pop two stamps.
+ */
 export interface Lease {
   readonly queue: string;
   readonly tenantId: string;
+  /** The run ENDED: the slot is free, and the start stays counted against `ratePerTenant`. */
   release(): void;
+  /**
+   * The run never STARTED — shed over a fleet cap, refused by its key: the slot is free and the
+   * rate stamp `tryAcquire` wrote goes with it. `ratePerTenant` is starts per window, and a job
+   * handed back unrun every poll interval otherwise spent its tenant's whole window on sheds.
+   */
+  abandon(): void;
 }
 
 export type LimitReason = 'per-tenant' | 'per-queue' | 'global' | 'rate';
@@ -109,20 +119,20 @@ export function tenantKeyFrom(actor: { readonly orgId?: string } | undefined): s
   return actor?.orgId ?? NO_TENANT;
 }
 
-export function createLimiter(
+export function concurrencyLimiter(
   config: LimitConfig,
   clock: Clock = systemClock,
   options: { readonly maxTenants?: number | undefined } = {},
 ): Limiter {
   const requested = options.maxTenants ?? DEFAULT_MAX_LIMIT_TENANTS;
-  // Refused where it was written, for the reason `createPacer` refuses `rate: 0`: `Math.floor(NaN)`
+  // Refused where it was written, for the reason `backfillPacer` refuses `rate: 0`: `Math.floor(NaN)`
   // is `NaN` and `Math.floor(Infinity)` is `Infinity`, so BOTH cap comparisons below read false and
   // the option silently means "no cap at all" — the one setting this bound exists to make
   // unreachable. `Number(process.env.X)` is how a deployment writes the first of those.
   assert(
     Number.isFinite(requested),
     `job limiter maxTenants is ${String(requested)}, which caps nothing — the per-tenant maps would grow without a bound`,
-    `pass a finite maxTenants to createLimiter(...), or omit it for the default ${String(DEFAULT_MAX_LIMIT_TENANTS)}`,
+    `pass a finite maxTenants to concurrencyLimiter(...), or omit it for the default ${String(DEFAULT_MAX_LIMIT_TENANTS)}`,
   );
   const maxTenants = Math.max(1, Math.floor(requested));
   const evictTo = Math.max(1, Math.floor(maxTenants * 0.9));
@@ -131,7 +141,7 @@ export function createLimiter(
   // `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
+  // a configured ceiling. `ratePerTenant.windowMs` is screened too 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
@@ -143,10 +153,16 @@ export function createLimiter(
     ['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);
+    if (value !== undefined) finiteCount('concurrencyLimiter', option, value);
   }
+  // Out of the loop because it is also READ, by `sweep`: the screened value is the one it reads.
+  // An absent rate window is 0, which `sweep` treats as "every stamp is spent".
+  const rateWindowMs = finiteCount(
+    'concurrencyLimiter',
+    'ratePerTenant.windowMs',
+    config.ratePerTenant?.windowMs ?? 0,
+  );
   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
@@ -186,9 +202,8 @@ export function createLimiter(
    */
   const sweep = (at: number): void => {
     lastSweepMs = at;
-    const windowMs = config.ratePerTenant?.windowMs ?? 0;
     for (const [tenant, stamps] of starts) {
-      if (stamps.length === 0 || (stamps.at(-1) ?? 0) <= at - windowMs) starts.delete(tenant);
+      if (stamps.length === 0 || (stamps.at(-1) ?? 0) <= at - rateWindowMs) starts.delete(tenant);
     }
     for (const [key, refusal] of refusals) {
       if (refusal.atMs <= at - REFUSAL_TTL_MS) refusals.delete(key);
@@ -261,16 +276,32 @@ export function createLimiter(
       maybeSweep(at);
 
       let released = false;
+      /** `false` when this lease was already handed back. */
+      const free = (): boolean => {
+        if (released) return false;
+        released = true;
+        global = Math.max(0, global - 1);
+        bump(byQueue, key.queue, -1);
+        bump(byTenant, tenant, -1);
+        bump(byQueueTenant, refusalKey, -1);
+        return true;
+      };
       return {
         queue: key.queue,
         tenantId: tenant,
         release() {
-          if (released) return;
-          released = true;
-          global = Math.max(0, global - 1);
-          bump(byQueue, key.queue, -1);
-          bump(byTenant, tenant, -1);
-          bump(byQueueTenant, refusalKey, -1);
+          free();
+        },
+        abandon() {
+          if (!free() || config.ratePerTenant === undefined) return;
+          // ONE stamp of this lease's own instant: two leases taken in the same millisecond wrote
+          // equal stamps, and either is this one. Absent when a sweep already dropped the window.
+          const stamps = starts.get(tenant);
+          const index = stamps?.lastIndexOf(at) ?? -1;
+          if (stamps === undefined || index === -1) return;
+          const rest = stamps.filter((_stamp, position) => position !== index);
+          if (rest.length === 0) starts.delete(tenant);
+          else starts.set(tenant, rest);
         },
       };
     },

package/src/outbox-lease.ts

@@ -23,7 +23,7 @@ export function resolveClaimLeaseMs(value: number | undefined): number {
   assert(
     Number.isInteger(value) && value > 0,
     `outbox claimLeaseMs is ${String(value)}, which is not a positive whole number of milliseconds`,
-    'pass a positive whole claimLeaseMs: 30_000 — createPgOutboxStore({ executor, txExecutor, claimLeaseMs: 30_000 }) — or omit the field for the 30s default',
+    'pass a positive whole claimLeaseMs: 30_000 — postgresOutboxStore({ executor, txExecutor, claimLeaseMs: 30_000 }) — or omit the field for the 30s default',
   );
   return value;
 }

package/src/outbox-pg.ts

@@ -4,16 +4,15 @@
 // memory store hangs rows off the `Tx` object and is correct only inside one process; this is
 // what a deployment installs.
 //
-// `txExecutor` is injected rather than resolved here for the reason `createPgDriver` takes a
+// `txExecutor` is injected rather than resolved here for the reason `postgresJobDriver` takes a
 // `PgExecutor`: this package holds no `@ultimat3/db` dependency, and "which connection is this
 // `Tx` on" is a question only boot can answer. Boot has `currentTx()` — a `DbTx` IS a client on
 // the transaction's connection — so the wiring is one line there and no tier crossing here.
 
-import type { Clock } from '@ultimat3/core';
-import { uuid } from '@ultimat3/core';
+import type { Clock, PgExecutor } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
-import type { PgExecutor } from './driver-pg';
 import {
   SQL_OUTBOX_CLAIM,
   SQL_OUTBOX_MARK_PUBLISHED,
@@ -40,7 +39,7 @@ interface OutboxRow {
   readonly claimed_by?: string | null;
 }
 
-export interface PgOutboxOptions {
+export interface PostgresOutboxStoreOptions {
   /**
    * The pooled executor the RELAY uses: `claim`, `markPublished` and `pendingCount` all run after
    * the caller's transaction is gone, so they must not be bound to it.
@@ -88,7 +87,7 @@ function toRecord(row: OutboxRow): OutboxRecord {
   };
 }
 
-export function createPgOutboxStore(options: PgOutboxOptions): OutboxStore {
+export function postgresOutboxStore(options: PostgresOutboxStoreOptions): OutboxStore {
   // What each open transaction has staged, for `commit()`'s return value only. Never the source
   // of truth — that is the row, and the row's fate is the transaction's. A WeakMap so a `Tx` that
   // is neither committed nor rolled back (a process killed mid-request) leaves nothing behind.
@@ -97,7 +96,7 @@ export function createPgOutboxStore(options: PgOutboxOptions): OutboxStore {
   // One id per store, minted here rather than per claim: `claimed_by` is read by an operator
   // asking which relay is sitting on a batch, and a value that changed every tick answers nobody.
   // Per-store is also the granularity the fence needs — two relays are two processes, two stores.
-  const relayId = options.relayId ?? `relay-${uuid()}`;
+  const relayId = options.relayId ?? `relay-${uuidV7()}`;
   // Resolved once, at construction, so a lease this store could never honour fails where it was
   // written instead of inside a relay tick whose only trace is a log line nobody reads.
   const claimLeaseMs = resolveClaimLeaseMs(options.claimLeaseMs);

package/src/outbox-relay.ts

@@ -52,23 +52,23 @@ export interface OutboxRelay {
  * At-least-once by construction: publish, THEN mark published. A crash between the two
  * re-publishes, which the idempotency key collapses — the opposite order would lose jobs.
  */
-export function createOutboxRelay(options: RelayOptions): OutboxRelay {
+export function outboxRelay(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',
+    `outboxRelay batchSize is ${String(batchSize)} — a batch is a whole number of staged rows, at least one`,
+    'pass a finite batchSize to outboxRelay(...), or omit it for the default 100',
   );
   assert(
     Number.isFinite(intervalMs) && intervalMs >= 0,
-    `createOutboxRelay intervalMs is ${String(intervalMs)}, which a timer reads as 0 — the relay would spin, not poll`,
-    'pass a finite intervalMs to createOutboxRelay(...), or omit it for the default 200',
+    `outboxRelay intervalMs is ${String(intervalMs)}, which a timer reads as 0 — the relay would spin, not poll`,
+    'pass a finite intervalMs to outboxRelay(...), or omit it for the default 200',
   );
   const backoff = createIdleBackoff({
-    subject: 'createOutboxRelay',
+    subject: 'outboxRelay',
     floorMs: intervalMs,
     ...(options.idlePollMaxMs === undefined ? {} : { ceilingMs: options.idlePollMaxMs }),
   });

package/src/outbox.ts

@@ -14,9 +14,9 @@
 // `jobsFacade()` is what happens when they are not:
 //
 //   1. `x_outbox` exists — it ships in `SQL_JOBS_TABLE` now, so applying the queue DDL is enough.
-//   2. `setJobsFacade(createJobsFacade({ store, driver }, currentTx))` ran at boot, with a store
-//      from `createPgOutboxStore` and a REAL `currentTx` accessor.
-//   3. `createOutboxRelay({ store, driver }).start()` is running somewhere.
+//   2. `setJobsFacade(outboxJobsFacade({ store, driver }, currentTx))` ran at boot, with a store
+//      from `postgresOutboxStore` and a REAL `currentTx` accessor.
+//   3. `outboxRelay({ store, driver }).start()` is running somewhere.
 //
 // With none of them, `jobsFacade()` answers the fallback below, whose `currentTx` is
 // `() => undefined`: every enqueue publishes straight to the driver, outside the caller's
@@ -24,7 +24,13 @@
 // 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, traceparent, uuid } from '@ultimat3/core';
+import {
+  currentSpanContext,
+  describeValue,
+  traceparent,
+  UltimateError,
+  uuidV7,
+} from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import type { EnqueueResult, JobDriver } from './driver';
@@ -98,7 +104,7 @@ function byClaimOrder(a: OutboxRecord, b: OutboxRecord): number {
   return a.id < b.id ? -1 : 1;
 }
 
-export interface MemoryOutboxOptions {
+export interface MemoryOutboxStoreOptions {
   readonly clock?: Clock;
   readonly claimLeaseMs?: number;
 }
@@ -117,7 +123,7 @@ export interface MemoryOutboxStore extends OutboxStore {
  * transaction" guarantee needs no cooperation from the DB layer and rollback is a delete.
  * The pg store swaps this for a real `x_outbox` table written by the same connection.
  */
-export function createMemoryOutboxStore(options: MemoryOutboxOptions = {}): MemoryOutboxStore {
+export function memoryOutboxStore(options: MemoryOutboxStoreOptions = {}): MemoryOutboxStore {
   const staged = new WeakMap<object, OutboxRecord[]>();
   const committed = new Map<string, OutboxRecord>();
   /** Each claimed row's lease: when it was taken and by whom. Absent is `claimed_at is null`. */
@@ -238,6 +244,27 @@ function ambientTraceparent(): string | undefined {
   return traceparent(context);
 }
 
+/** What Postgres prints for a `uuid`, and so the only spelling both drivers store identically. */
+const RUN_ID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * `EnqueueOptions.runId`, refused HERE when it is not a uuid — the one screen both enqueue paths
+ * read. `run_id` is a `uuid` column: the memory driver took any string, Postgres raised a raw
+ * `22P02`, and on the staged path that was the caller's whole transaction failing at the outbox
+ * insert. Any version, lowercase: an uppercase one would come back from Postgres re-spelled.
+ */
+function namedRunId(job: string, runId: unknown): string | undefined {
+  if (runId === undefined) return undefined;
+  if (typeof runId === 'string' && RUN_ID_SHAPE.test(runId)) return runId;
+  throw new UltimateError({
+    code: 'X_ID_INVALID',
+    // `describeValue`, never the value: what arrives here wrong is as often a key as a typo.
+    cause: `enqueue of job "${job}" was given runId ${describeValue(runId)}, and a run id is a lowercase uuid (8-4-4-4-12 hex) — the queue stores it in a uuid column`,
+    fix: "pass { runId: uuidV7() } to enqueue(), with import { uuidV7 } from '@ultimat3/core'",
+    meta: { job, option: 'runId' },
+  });
+}
+
 export interface OutboxDeps {
   readonly store: OutboxStore;
   readonly driver: JobDriver;
@@ -247,18 +274,19 @@ export interface OutboxDeps {
 }
 
 /** Stage a job inside `tx`. Returns the row that the relay will publish after commit. */
-export function enqueueInTx<I>(
+export async function enqueueInTx<I>(
   deps: OutboxDeps,
   tx: Tx,
   handle: JobHandle<I>,
   input: I,
   options: EnqueueOptions = {},
 ): Promise<OutboxRecord> {
+  const runId = namedRunId(handle.name, options.runId);
   const at = nowMs(deps.clock);
   const trace = options.traceparent ?? ambientTraceparent();
   const record: OutboxRecord = {
-    id: uuid(),
-    runId: options.runId ?? uuid(),
+    id: uuidV7(),
+    runId: runId ?? uuidV7(),
     job: handle.name,
     queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
     input,
@@ -272,11 +300,10 @@ export function enqueueInTx<I>(
     ...(trace === undefined ? {} : { traceparent: trace }),
     ...(options.enqueuedBy === undefined ? {} : { enqueuedBy: options.enqueuedBy }),
   };
-  return deps.store.stage(tx, record).then(() => {
-    // Wakes a relay in THIS process that has backed off; a relay elsewhere polls on its own.
-    signalStaged();
-    return record;
-  });
+  await deps.store.stage(tx, record);
+  // Wakes a relay in THIS process that has backed off; a relay elsewhere polls on its own.
+  signalStaged();
+  return record;
 }
 
 export interface JobsFacade {
@@ -287,7 +314,7 @@ export interface JobsFacade {
   enqueue<I>(handle: JobHandle<I>, input: I, options?: EnqueueOptions): Promise<EnqueueResult>;
 }
 
-export function createJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefined): JobsFacade {
+export function outboxJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefined): JobsFacade {
   return {
     async enqueue<I>(
       handle: JobHandle<I>,
@@ -304,6 +331,7 @@ export function createJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefin
         if (deps.mode === 'required' && options.outbox !== false) {
           throw new OutboxNoTxError({ job: handle.name });
         }
+        const runId = namedRunId(handle.name, options.runId);
         const trace = options.traceparent ?? ambientTraceparent();
         const result = await deps.driver.enqueue({
           name: handle.name,
@@ -312,7 +340,7 @@ export function createJobsFacade(deps: OutboxDeps, currentTx: () => Tx | undefin
           idempotencyKey: handle.idempotencyKeyFor(input),
           maxAttempts: handle.retry.attempts,
           runAt: options.runAt ?? nowMs(deps.clock),
-          ...(options.runId === undefined ? {} : { runId: options.runId }),
+          ...(runId === undefined ? {} : { runId }),
           ...(options.tenantId === undefined ? {} : { tenantId: options.tenantId }),
           ...(trace === undefined ? {} : { traceparent: trace }),
           ...(options.enqueuedBy === undefined ? {} : { enqueuedBy: options.enqueuedBy }),
@@ -351,7 +379,7 @@ export function setJobsFacade(facade: JobsFacade | null): void {
  */
 export function jobsFacade(): JobsFacade {
   if (ambient !== undefined) return ambient;
-  fallback ??= createJobsFacade(
+  fallback ??= outboxJobsFacade(
     {
       // A getter, not a snapshot: `setJobDriver()` after the first enqueue is honoured, and a
       // missing driver is an error at the call rather than at import time.
@@ -361,14 +389,14 @@ export function jobsFacade(): JobsFacade {
           throw new DriverUnavailableError({
             driver: 'none',
             cause: 'no queue driver is installed in this process',
-            fix: 'call setJobDriver(createMemoryDriver()) before enqueuing, or setJobDriver(createPgDriver()) for a real queue',
+            fix: 'call setJobDriver(memoryJobDriver()) before enqueuing, or setJobDriver(postgresJobDriver()) for a real queue',
           });
         }
         return installed;
       },
       // Unreachable while `currentTx` is `() => undefined`; present because `OutboxDeps`
       // requires a store, and a real one is cheaper than an assertion that cannot fire.
-      store: createMemoryOutboxStore(),
+      store: memoryOutboxStore(),
     },
     () => undefined,
   );

package/src/purge.ts

@@ -33,7 +33,7 @@ export interface PurgeTarget {
   /**
    * What this sweep is called in its durable step, its log line and its report. A table name is
    * the natural spelling (`x_rate_limit`); a target that clears a SET of tables names their common
-   * prefix (`x_auth`, for `x_auth_failures` and `x_auth_lockouts`). Unique within one definition —
+   * prefix (`x_auth`, for `x_auth_lockouts`). Unique within one definition —
    * the name is the step key, and two steps under one name is `X_STEP_DUPLICATE` mid-run.
    */
   readonly name: string;

package/src/queue-wake.ts

@@ -5,9 +5,8 @@
 // the poll keeps running underneath, and this file's other job is to say whether the wake is
 // PROVEN: the loops raise their idle ceiling only while it is.
 
-import type { Random } from '@ultimat3/core';
+import type { PgExecutor, Random } from '@ultimat3/core';
 import { backoffDelay, finiteOption, logger, renderThrowable } from '@ultimat3/core';
-import type { PgExecutor } from './driver-pg';
 import { JOBS_WAKE_CHANNEL, OUTBOX_WAKE_CHANNEL, SQL_WAKE } from './driver-pg-wake-sql';
 import { setWakeLive, signalEnqueued, signalStaged } from './enqueue-signal';
 

package/src/renewal-timer.ts

@@ -20,7 +20,7 @@ export interface RenewalTimer {
 
 /**
  * Calls `tick` every `intervalMs` until the canceller it returns runs. The seam a lease, a fleet
- * slot and a registry row renew through: `createWorker({ schedule })` hands one in, and the
+ * slot and a registry row renew through: `jobWorker({ schedule })` hands one in, and the
  * `runJobs` fixture's is driven by the frozen clock, so a test renews when time passes and never
  * on the wall clock.
  */

package/src/retry-classification.ts

@@ -3,10 +3,16 @@
 // The backoff arithmetic stays in ./retry — nothing here recomputes a delay `nextRetry` owns.
 
 import type { ErrorRetry } from '@ultimat3/core';
-import { classifyThrown, isUltimateError, renderThrowable, statedDelayMs } from '@ultimat3/core';
+import {
+  classifyThrown,
+  isUltimateError,
+  jitterStatedDelay,
+  renderThrowable,
+  statedDelayMs,
+} from '@ultimat3/core';
 import { finiteDurationMs } from './clock';
 import type { Random, RetryDecision, RetryPolicy } from './retry';
-import { DEFAULT_RETRY, nextRetry } from './retry';
+import { backoffDelayMs, DEFAULT_RETRY, nextRetry } from './retry';
 
 /** Why this attempt was the last one. Absent while the job is still being retried. */
 export type JobStopReason = 'terminal' | 'attempts-exhausted';
@@ -17,16 +23,10 @@ export interface JobRetryDecision extends RetryDecision {
   readonly classification: ErrorRetry | undefined;
 }
 
-/**
- * Core's, re-exported rather than copied — they are the readers of core's classification table and
- * every executor in the framework has to answer them the same way. Both were declared here first
- * and moved down a tier VERBATIM, the subtle rule included: an UNCLASSIFIED code carrying an
- * instance `retry: 'terminal'` reads as unclassified, because a per-instance `terminal` is
- * indistinguishable from the fail-closed default and honouring it would dead-letter the first
- * attempt of every job in every app whose codes nobody has classified. `retry-classification.test.ts`
- * pins that they are the same FUNCTION, not merely two functions that agree today.
- */
-export { classifyThrown, statedDelayMs };
+// `classifyThrown` and `statedDelayMs` are core's, imported — the readers of core's classification
+// table, which every executor answers the same way. An UNCLASSIFIED code carrying an instance
+// `retry: 'terminal'` reads as unclassified (a per-instance `terminal` is indistinguishable from
+// the fail-closed default); `retry-classification.test.ts` holds that rule against core's function.
 
 /**
  * Retry, dead-letter, and when. `terminal` stops here on the attempt that failed — the same code
@@ -65,10 +65,47 @@ export function nextRetryForError(
 
   const stated = statedDelayMs(error);
   if (stated === undefined) return { ...decision, stoppedBy: undefined, classification };
-  // Clamped by the policy's own ceiling, which is what `maxDelay` is for: a responder naming a
-  // day is still a responder this deployment has not agreed to wait a day for.
+  // The floor is clamped by the policy's own ceiling, which is what `maxDelay` is for: a responder
+  // naming a day is still a responder this deployment has not agreed to wait a day for. The spread
+  // on top is core's `jitterStatedDelay` — the one rule for a named delay — because an HTTP-date
+  // hands every delivery to one receiver the SAME instant, and waking them together is the herd.
+  const cap = finiteDurationMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay, 'retry', 'maxDelay');
+  // `jitter: false` is the policy's own decision and is honoured: the bare floor.
+  const floor = Math.min(stated, cap);
+  const jittered = (policy.jitter ?? DEFAULT_RETRY.jitter) === true;
+  const delayMs = jittered ? jitterStatedDelay(floor, cap, random) : floor;
+  return { ...decision, delayMs, stoppedBy: undefined, classification };
+}
+
+/**
+ * `@ultimat3/http`'s `rateLimited()` — the refusal a declared `rateLimit:` answers on every
+ * surface, a job's `.job()`/`llm()` run included. Named, not classified: `retry-after` also covers
+ * `X_OVERLOADED`, a shed that should still spend the policy's attempts.
+ */
+const RATE_LIMITED = 'X_RATE_LIMITED';
+
+/**
+ * How long to wait out a rate-limit refusal, or `undefined` when `error` is not one. A refusal is
+ * "not yet", never "failed": the bucket refills, so the run is rescheduled with its attempt
+ * UNCOUNTED — counted, a backlog of rate-limited jobs spent every attempt waiting and was
+ * dead-lettered for it.
+ *
+ * The stated `Retry-After` is the FLOOR, never clamped: a run woken before the refill is refused
+ * again, so clamping a 3600 s refusal to `maxDelay` re-ran the backlog every minute for an hour.
+ * With none stated, the policy's own backoff. On top, a spread in `[0, min(wait / 2, maxDelay))`:
+ * a backlog refused together and woken at one instant is refused together again, a claim storm
+ * that repeats forever. `maxDelay` bounds only that spread.
+ */
+export function rateLimitDeferralMs(
+  policy: RetryPolicy,
+  attempt: number,
+  error: unknown,
+  random: Random = Math.random,
+): number | undefined {
+  if (!isUltimateError(error) || error.code !== RATE_LIMITED) return undefined;
   const cap = finiteDurationMs(policy.maxDelay ?? DEFAULT_RETRY.maxDelay, 'retry', 'maxDelay');
-  return { ...decision, delayMs: Math.min(stated, cap), stoppedBy: undefined, classification };
+  const wait = statedDelayMs(error) ?? Math.min(backoffDelayMs(policy, attempt), cap);
+  return jitterStatedDelay(wait, cap, random);
 }
 
 /**

package/src/scheduler-leader.ts

@@ -15,8 +15,8 @@ export interface LeaderElection {
   readonly renewEveryMs: number;
 }
 
-/** Single-node default: always the leader. Multi-node uses `createPgLeaseLeader()` — never
- * `createPgLeader()`, whose advisory lock is owned by a pooled session this process cannot name. */
+/** Single-node default: always the leader. Multi-node uses `postgresLeaseLeader()` — never
+ * `postgresLeader()`, whose advisory lock is owned by a pooled session this process cannot name. */
 export function soleLeader(): LeaderElection {
   return {
     acquire: () => Promise.resolve(true),