@ultimat3/jobs 24.0.0 → 25.0.0

package/src/index.ts

@@ -7,23 +7,10 @@
 // bypasses `defineApi`'s own result — the ambiguity axiom 1 exists to refuse.
 import './register';
 
-// The wire format, RE-EXPORTED from `@ultimat3/core` and never re-declared: it is one module at
-// the tier both halves can reach, because this package signs a delivery, `@ultimat3/http` verifies
-// one, and neither may import the other. Re-exported here so a `job` file needs one import rather
-// than two — the same reason `t` is re-exported above.
-export type { PgExecutor, WebhookMacInput, WebhookSigningInput } from '@ultimat3/core';
-export {
-  isCanonicalWebhookField,
-  WEBHOOK_FIELD_MAX,
-  WEBHOOK_ID_HEADER,
-  WEBHOOK_SIGNATURE_HEADER,
-  WEBHOOK_SIGNATURE_VERSION,
-  WEBHOOK_TOPIC_HEADER,
-  webhookHeaders,
-  webhookMac,
-  webhookSignature,
-  webhookSigningString,
-} from '@ultimat3/core';
+// The webhook wire format (`WEBHOOK_*`, `webhookSignature`, `webhookMac`, …) is `@ultimat3/core`'s
+// and imported from there: one module at the tier this package (the signer) and `@ultimat3/http`
+// (the verifier) both reach, with one import path — never re-exported here (`X_HELPER_COPY`).
+export type { PgExecutor } from '@ultimat3/core';
 /** Re-exported so a `job`/`task` file needs one import, not two. Same object as schema's. */
 export type { Infer } from '@ultimat3/schema';
 export { t } from '@ultimat3/schema';
@@ -57,9 +44,9 @@ export type {
 export {
   BACKFILL_STATUSES,
   backfillChecksum,
-  createMemoryBackfillLedger,
   decideBackfill,
   isBackfillStatus,
+  memoryBackfillLedger,
 } from './backfill-ledger';
 export type {
   BackfillPendingReport,
@@ -73,7 +60,7 @@ export {
   pendingBackfills,
 } from './backfill-pending';
 export type { Pacer, PacerOptions } from './backfill-rate';
-export { createPacer, DEFAULT_BACKFILL_RATE } from './backfill-rate';
+export { backfillPacer, DEFAULT_BACKFILL_RATE } from './backfill-rate';
 export type { BackfillCount, BackfillDeclaration, BackfillOrigin } from './backfill-registry';
 // `stampBackfill` is deliberately absent, for the reason `registerJob` is: a second way to make a
 // handle claim it is a backfill would let a plain `job()` inherit the pending diff and the gate.
@@ -120,62 +107,14 @@ export {
   resetJobDriver,
   setJobDriver,
 } from './driver';
-export type { MemoryDriverOptions, MemoryJobDriver } from './driver-memory';
-export { createMemoryDriver } from './driver-memory';
-export type { NatsDriverOptions } from './driver-nats';
-export { createNatsDriver } from './driver-nats';
-export type { PgDriverOptions } from './driver-pg';
-export { createPgDriver, createPgLeader } from './driver-pg';
-export {
-  SQL_COUNTER_DROP,
-  SQL_COUNTER_FOLD,
-  SQL_COUNTER_TOTALS,
-  SQL_COUNTERS,
-  SQL_JOB_PROGRESS,
-  SQL_JOB_PROMOTE,
-  SQL_JOB_REMOVE,
-  SQL_JOB_REMOVE_MANY,
-  SQL_JOB_REQUEUE_MANY,
-  SQL_PAUSE,
-  SQL_PAUSED,
-  SQL_RESUME,
-  SQL_SCHEDULER_FIRE,
-  SQL_WORKER_ANNOUNCE,
-  SQL_WORKER_FORGET,
-  SQL_WORKERS,
-} from './driver-pg-operator-sql';
-export {
-  SQL_ACK,
-  SQL_ADVISORY_UNLOCK,
-  SQL_BACKFILL_FINISH,
-  SQL_BACKFILL_LIST,
-  SQL_BACKFILL_PROGRESS,
-  SQL_BACKFILL_START,
-  SQL_CANCEL,
-  SQL_CLAIM,
-  SQL_ENQUEUE,
-  SQL_HEARTBEAT,
-  SQL_JOBS_TABLE,
-  SQL_LEADER_ACQUIRE,
-  SQL_LEADER_RELEASE,
-  SQL_LEASE_ACQUIRE,
-  SQL_LEASE_HOLDERS,
-  SQL_LEASE_RELEASE,
-  SQL_LEASE_RENEW,
-  SQL_NACK,
-  SQL_OUTBOX_CLAIM,
-  SQL_OUTBOX_MARK_PUBLISHED,
-  SQL_OUTBOX_RELEASE,
-  SQL_OUTBOX_STAGE,
-  SQL_SCHEDULER_STATE_GET,
-  SQL_SCHEDULER_STATE_MARK,
-  SQL_STATS,
-  SQL_STEP_GET,
-  SQL_STEP_PUT,
-  SQL_TRY_ADVISORY_LOCK,
-} from './driver-pg-sql';
-export type { RedisDriverOptions } from './driver-redis';
-export { createRedisDriver } from './driver-redis';
+export type { MemoryJobDriver, MemoryJobDriverOptions } from './driver-memory';
+export { memoryJobDriver } from './driver-memory';
+export type { PostgresJobDriverOptions } from './driver-pg';
+export { postgresJobDriver, postgresLeader } from './driver-pg';
+// Only the statement another workspace runs: the install (`cli/src/framework-schema.ts`, action,
+// notify). The rest are this package's internals, read where they are defined, and tested there
+// too — the array-parameter proofs are `driver-pg-array.live.test.ts` (25.0.0).
+export { SQL_JOBS_TABLE } from './driver-pg-sql';
 export { signalEnqueued, signalStaged } from './enqueue-signal';
 export type { JobErrorCode } from './errors';
 export {
@@ -216,16 +155,16 @@ export {
 export { JobNotFoundError, JobNotRequeueableError } from './errors-requeue';
 export type { EventBus, JobEvent, MemoryEventBusOptions, PublishOptions } from './events';
 export {
-  createMemoryEventBus,
   EVENTS_PURGE_TARGET,
   eventBus,
   eventsPurgeTarget,
+  memoryEventBus,
   publishEvent,
   resetEventBus,
   setEventBus,
 } from './events';
-export type { PgEventBusOptions } from './events-pg';
-export { createPgEventBus } from './events-pg';
+export type { PostgresEventBusOptions } from './events-pg';
+export { postgresEventBus } from './events-pg';
 export type { ExecuteJobOptions, JobExecution, JobOutcome } from './execute';
 export { executeJob } from './execute';
 export type { ExportDefinition, ExportReport } from './export';
@@ -296,7 +235,7 @@ export type {
 } from './job';
 export { describeJobs, getJob, isJobHandle, job, registeredJobs, resetJobs } from './job';
 export type { HeldLease, LeaseStore, MemoryLeaseStore, MemoryLeaseStoreOptions } from './leases';
-export { createMemoryLeaseStore, jobLeaseKey } from './leases';
+export { jobLeaseKey, memoryLeaseStore } from './leases';
 export type {
   Lease,
   LimitConfig,
@@ -306,7 +245,7 @@ export type {
   LimitSnapshot,
   RateLimit,
 } from './limits';
-export { createLimiter, NO_TENANT, tenantKeyFrom } from './limits';
+export { concurrencyLimiter, NO_TENANT, tenantKeyFrom } from './limits';
 export {
   queueDeadJobs,
   queueOldestReady,
@@ -316,27 +255,27 @@ export {
 export type {
   EnqueueOptions,
   JobsFacade,
-  MemoryOutboxOptions,
   MemoryOutboxStore,
+  MemoryOutboxStoreOptions,
   OutboxDeps,
   OutboxRecord,
   OutboxStore,
 } from './outbox';
 export {
-  createJobsFacade,
-  createMemoryOutboxStore,
   enqueueInTx,
   jobsFacade,
+  memoryOutboxStore,
+  outboxJobsFacade,
   resetJobsFacade,
   setJobsFacade,
 } from './outbox';
 // One definition of the lease, consumed by both stores — a memory default and a pg default that
 // could drift are two answers to "how long is a claim mine for", and the shorter one duplicates.
 export { DEFAULT_OUTBOX_CLAIM_LEASE_MS } from './outbox-lease';
-export type { PgOutboxOptions } from './outbox-pg';
-export { createPgOutboxStore } from './outbox-pg';
+export type { PostgresOutboxStoreOptions } from './outbox-pg';
+export { postgresOutboxStore } from './outbox-pg';
 export type { OutboxRelay, RelayOptions } from './outbox-relay';
-export { createOutboxRelay } from './outbox-relay';
+export { outboxRelay } from './outbox-relay';
 export type { ProgressFn } from './progress';
 export type {
   PurgeDefinition,
@@ -352,7 +291,7 @@ export type { IntervalScheduler } from './renewal-timer';
 export type { BackoffStrategy, Random, RetryDecision, RetryPolicy } from './retry';
 export { backoffDelayMs, DEFAULT_RETRY, isFinalAttempt, nextRetry, retrySchedule } from './retry';
 export type { JobRetryDecision, JobStopReason } from './retry-classification';
-export { classifyThrown, failureForRow, nextRetryForError } from './retry-classification';
+export { failureForRow, nextRetryForError } from './retry-classification';
 export type {
   CronResolver,
   DispatchedOccurrence,
@@ -361,22 +300,22 @@ export type {
 } from './scheduler';
 export {
   COUNTER_ROLLUP_INTERVAL_MS,
-  createScheduler,
+  jobScheduler,
   PAUSE_RECHECK_MS,
 } from './scheduler';
 export type { LeaderElection } from './scheduler-leader';
 export { soleLeader } from './scheduler-leader';
 export { nextTaskRun } from './scheduler-occurrences';
-export type { PgLeaseLeaderOptions } from './scheduler-pg';
+export type { PostgresLeaseLeaderOptions } from './scheduler-pg';
 export {
-  createPgLeaseLeader,
   currentLeader,
   DEFAULT_LEADER_TTL_MS,
   LEASE_RENEWALS_PER_TTL,
-  pgSchedulerState,
+  postgresLeaseLeader,
+  postgresSchedulerState,
 } from './scheduler-pg';
 export type { ScheduledFire, SchedulerState } from './scheduler-state';
-export { createMemorySchedulerState, fireThroughDriver } from './scheduler-state';
+export { fireThroughDriver, memorySchedulerState } from './scheduler-state';
 export type { JobCompleted, JobFailed, JobSettled } from './settled';
 export { ON_SETTLED_ATTEMPTS } from './settled';
 export type {
@@ -391,14 +330,14 @@ export type {
   WaitForEventOptions,
 } from './steps';
 export {
-  createStepRunner,
   isStepStatus,
   isStepSuspension,
   MAX_TRACE_NAMES,
   STEP_STATUSES,
   StepSuspension,
+  stepRunner,
 } from './steps';
-export { createMemoryStepStore } from './steps-memory';
+export { memoryStepStore } from './steps-memory';
 export type {
   CatchUpPolicy,
   TaskDefinition,
@@ -421,10 +360,11 @@ export type {
   WebhookDeliveryInput,
   WebhookEndpoint,
   WebhookEvent,
-  WebhookFetch,
   WebhookReport,
 } from './webhook';
-export { DEFAULT_WEBHOOK_DISABLE_AFTER, WEBHOOK_CONTENT_TYPE, webhook } from './webhook';
+export { DEFAULT_WEBHOOK_DISABLE_AFTER, webhook } from './webhook';
+export type { WebhookFetch } from './webhook-attempt';
+export { WEBHOOK_CONTENT_TYPE } from './webhook-attempt';
 export {
   WebhookDeliveryFailedError,
   WebhookDeliveryRejectedError,
@@ -438,4 +378,4 @@ export {
 export type { MemoryWebhookLedger, WebhookAttempt, WebhookLedger } from './webhook-ledger';
 export { DEFAULT_MAX_WEBHOOK_ATTEMPTS, memoryWebhookLedger } from './webhook-ledger';
 export type { Worker, WorkerOptions, WorkerStats } from './worker';
-export { createWorker } from './worker';
+export { jobWorker } from './worker';

package/src/inspect-operator.ts

@@ -12,7 +12,7 @@ function operatorOf(driver: JobDriver): JobIntrospection {
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — the pg driver implements introspect — then: x jobs ls --json',
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg driver implements introspect — then: x jobs ls --json',
     });
   }
   return driver.introspect;

package/src/inspect.ts

@@ -114,7 +114,7 @@ function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introsp
   if (driver.introspect === undefined) {
     throw new NotImplementedError({
       cause: `introspection for the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
     });
   }
   return driver.introspect;

package/src/job.ts

@@ -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.
    */

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

@@ -119,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));
@@ -141,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
@@ -153,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
@@ -196,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);

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,13 +4,13 @@
 // 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, PgExecutor } from '@ultimat3/core';
-import { uuid } from '@ultimat3/core';
+import { uuidV7 } from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import {
@@ -39,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.
@@ -87,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.
@@ -96,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
@@ -29,7 +29,7 @@ import {
   describeValue,
   traceparent,
   UltimateError,
-  uuid,
+  uuidV7,
 } from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
@@ -104,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;
 }
@@ -123,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`. */
@@ -260,7 +260,7 @@ function namedRunId(job: string, runId: unknown): string | undefined {
     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: uuid() } to enqueue(), with import { uuid } from '@ultimat3/core'",
+    fix: "pass { runId: uuidV7() } to enqueue(), with import { uuidV7 } from '@ultimat3/core'",
     meta: { job, option: 'runId' },
   });
 }
@@ -285,8 +285,8 @@ export async function enqueueInTx<I>(
   const at = nowMs(deps.clock);
   const trace = options.traceparent ?? ambientTraceparent();
   const record: OutboxRecord = {
-    id: uuid(),
-    runId: runId ?? uuid(),
+    id: uuidV7(),
+    runId: runId ?? uuidV7(),
     job: handle.name,
     queue: options.queue ?? handle.queue ?? DEFAULT_QUEUE,
     input,
@@ -314,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>,
@@ -379,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.
@@ -389,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/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);
 }
 
 /**