@ultimat3/jobs 23.0.0 → 25.0.0

package/src/events-pg.ts

@@ -6,16 +6,16 @@
 // Stored and not broadcast, exactly as the memory bus is: a step that suspends at 12:00 and
 // resumes at 12:00:30 must still see an event published at 12:00:10.
 
-import { finiteOption, logger, renderThrowable, uuid } from '@ultimat3/core';
+import type { PgExecutor } from '@ultimat3/core';
+import { finiteOption, logger, uuidV7 } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { finiteDurationMs } from './clock';
-import type { PgExecutor } from './driver-pg';
 import {
   SQL_EVENT_FIND,
   SQL_EVENT_LIST,
   SQL_EVENT_NOW,
   SQL_EVENT_PUBLISH,
-  SQL_EVENT_PURGE,
+  SQL_EVENT_PURGE_COUNTED,
 } from './driver-pg-sql';
 import type { EventBus } from './events';
 
@@ -28,7 +28,7 @@ interface EventRow {
   readonly expires_at: number | string;
 }
 
-export interface PgEventBusOptions {
+export interface PostgresEventBusOptions {
   /**
    * The only thing this bus is built from. There is no `clock`: every instant it writes or
    * compares is the database's (`SQL_EVENT_PUBLISH`), and a process clock here was the defect.
@@ -40,14 +40,7 @@ export interface PgEventBusOptions {
   readonly listLimit?: number;
 }
 
-/**
- * `purgeExpired()` is SYNCHRONOUS in `EventBus` because the memory bus can be — it walks a Map.
- * Over SQL the delete is a round trip, so this fires it and answers 0: the count is a diagnostic
- * the memory bus offers and this one cannot, and blocking a step's resume on a housekeeping
- * DELETE would be a far worse trade than an unanswered number. The index on `(name, published_at)`
- * plus `expires_at > now()` in `find` means an unpurged row costs a filter, never a wrong answer.
- */
-export function createPgEventBus(options: PgEventBusOptions): EventBus {
+export function postgresEventBus(options: PostgresEventBusOptions): EventBus {
   // 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.
@@ -59,14 +52,11 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
   const listLimit = finiteOption('the pg event bus', 'listLimit', options.listLimit ?? 1_000);
   const exec = options.executor;
 
-  const purgeExpired = (): number => {
-    void exec.query(SQL_EVENT_PURGE, []).catch((error: unknown) => {
-      // Housekeeping never costs a publish: an unpurged row is filtered out of every read.
-      logger.warn('jobs.event.purge-failed', {
-        error: renderThrowable(error),
-      });
-    });
-    return 0;
+  // Awaited and never fired-and-forgotten: it was `void`ed with nothing calling it, so the table
+  // only grew. A failure REJECTS — the caller is the retention sweep's step, which retries.
+  const purgeExpired = async (): Promise<number> => {
+    const rows = await exec.query<{ removed: number | string }>(SQL_EVENT_PURGE_COUNTED, []);
+    return Number(rows[0]?.removed ?? 0);
   };
 
   return {
@@ -77,7 +67,7 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
     },
 
     async publish(name, payload, publishOptions = {}) {
-      const id = uuid();
+      const id = uuidV7();
       const ttlMs =
         publishOptions.ttl === undefined
           ? defaultTtlMs

package/src/events.ts

@@ -3,9 +3,10 @@
 // 12:00:10, so a fire-and-forget emitter would silently strand every waiting run.
 
 import type { Clock } from '@ultimat3/core';
-import { finiteOption, logger, systemClock, uuid } from '@ultimat3/core';
+import { finiteOption, logger, systemClock, uuidV7 } from '@ultimat3/core';
 import type { DurationInput } from './clock';
 import { finiteDurationMs, nowMs } from './clock';
+import type { PurgeTarget } from './purge';
 import type { EventLookup } from './steps';
 
 export interface JobEvent {
@@ -31,16 +32,14 @@ export interface EventBus extends EventLookup {
    * split asks, and the reason `eventPrompt()` refuses the in-memory bus outside development.
    */
   readonly stored: boolean;
-  /**
-   * The bus's OWN clock, in epoch ms: what a publish issued now would be stamped with. A consumer
-   * that wants "published after I asked" takes its "asked at" from here and never from its own
-   * process — `publishedAt` is this clock's, and two clocks compared is a skew between pods
-   * deciding which answers count.
-   */
-  now(): Promise<number>;
   publish(name: string, payload: unknown, options?: PublishOptions): Promise<JobEvent>;
   list(name?: string): Promise<readonly JobEvent[]>;
-  purgeExpired(): number;
+  /**
+   * Delete every event past its expiry and answer how many went. Measured on the bus's own clock,
+   * like every other instant it holds. The memory bus also sweeps on each publish; the stored one
+   * has no caller but the retention sweep (`eventsPurgeTarget`).
+   */
+  purgeExpired(): Promise<number>;
   size(): number;
 }
 
@@ -50,7 +49,7 @@ export interface MemoryEventBusOptions {
   readonly maxEvents?: number;
 }
 
-export function createMemoryEventBus(options: MemoryEventBusOptions = {}): EventBus {
+export function memoryEventBus(options: MemoryEventBusOptions = {}): EventBus {
   const clock = options.clock ?? systemClock;
   // 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`
@@ -84,7 +83,7 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
       purgeExpired();
       const at = nowMs(clock);
       const event: JobEvent = {
-        id: uuid(),
+        id: uuidV7(),
         name,
         payload,
         publishedAt: at,
@@ -136,15 +135,27 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
       return Promise.resolve(all);
     },
 
-    purgeExpired,
+    purgeExpired: () => Promise.resolve(purgeExpired()),
     size: () => events.size,
   };
 }
 
-let ambientBus: EventBus = createMemoryEventBus();
+/** The table the stored bus keeps — the sweep's durable step key, log field and report name. */
+export const EVENTS_PURGE_TARGET = 'x_job_events';
+
+/**
+ * The bus as one table of the retention sweep (`purge()`). `x_job_events` takes a row per publish
+ * and an expired one is only FILTERED by `find`, so with no sweep the table grows for the life of
+ * the deployment. The sweep's `nowMs` is not passed on: a bus holds its own clock.
+ */
+export function eventsPurgeTarget(bus: EventBus): PurgeTarget {
+  return { name: EVENTS_PURGE_TARGET, purgeExpired: () => bus.purgeExpired() };
+}
+
+let ambientBus: EventBus = memoryEventBus();
 
 /**
- * **Install `createPgEventBus({ executor })` here in any deployment with more than one process.**
+ * **Install `postgresEventBus({ executor })` here in any deployment with more than one process.**
  * The default above is one process's heap: the pod that publishes and the pod that resumes are
  * never the same one, so a webhook landing on web-3 strands a run on worker-7 until its 24h
  * timeout dead-letters it, with nothing logged before then. This line used to promise a
@@ -165,7 +176,7 @@ export function eventBus(): EventBus {
  * wait before that test has asked anything — call this between tests.
  */
 export function resetEventBus(): void {
-  ambientBus = createMemoryEventBus();
+  ambientBus = memoryEventBus();
 }
 
 /** The one function app code calls to unblock a waiting step. */

package/src/execute.ts

@@ -26,12 +26,17 @@ import type { AnyJobHandle } from './job';
 import { createProgressReporter } from './progress';
 import { isFinalAttempt } from './retry';
 import type { JobStopReason } from './retry-classification';
-import { failureForRow, nextRetryForError, recordedFailure } from './retry-classification';
+import {
+  failureForRow,
+  nextRetryForError,
+  rateLimitDeferralMs,
+  recordedFailure,
+} from './retry-classification';
 import { raceTimeout } from './run-deadline';
 import { createRunSignal } from './run-signal';
 import { announceSettled, settledCode } from './settled';
 import type { EventLookup, StepRecord } from './steps';
-import { createStepRunner, isStepSuspension } from './steps';
+import { isStepSuspension, stepRunner } from './steps';
 import { jobRunActor } from './tenant';
 
 /**
@@ -57,7 +62,7 @@ export type JobOutcome =
 const NEVER_ABORTED = new AbortController().signal;
 
 /**
- * `Ctx.signal` is non-optional in the type and `createContext` always sets it — but a context can
+ * `Ctx.signal` is non-optional in the type and `ctxOf` always sets it — but a context can
  * still arrive across a cast (`@ultimat3/http`'s `asCtx`, a test's `{} as Ctx`) without one, and
  * a job that crashed on a missing field would be a far worse answer than a job with no caller to
  * follow. Read it, do not assume it.
@@ -68,7 +73,7 @@ function callerSignal(ctx: Ctx): AbortSignal {
 
 /**
  * The same defensive read, for the same reason: `Ctx.actor` is non-optional in the type and
- * `createContext` always sets it, but `WorkerOptions.context()` is the app's own function and a
+ * `ctxOf` always sets it, but `WorkerOptions.context()` is the app's own function and a
  * cast context (`{} as Ctx`) reaches here without one. Anonymous is the honest stand-in — it
  * carries no org, so the job's declared tenant is the only thing that can put one on the run.
  */
@@ -147,11 +152,15 @@ export async function executeJob(options: ExecuteJobOptions): Promise<JobExecuti
     signal,
     services: callerServices(options.ctx),
   });
-  const runner = createStepRunner({
+  const runner = stepRunner({
     runId: claimed.runId,
     jobName: handle.name,
     store: driver.steps,
+    fence: { job: handle.name, jobId: claimed.id, ...claimOf(claimed) },
     signal,
+    // This attempt's OWN end — the deadline, the `finally` below — apart from the run's signal,
+    // whose first reason may be the drain's: a drained step still records, an ended attempt never.
+    ended: cancel.signal,
     // The DECLARED per-step ceiling and event poll. Passed here or nowhere: this is the only
     // production construction of a runner, so a `StepRunnerOptions` field it omits is a feature
     // no `job()` can reach — which both of these were until 2026-08.
@@ -309,6 +318,39 @@ export async function executeJob(options: ExecuteJobOptions): Promise<JobExecuti
         replayed: [],
       });
     }
+    // A rate-limit refusal is "not yet": rescheduled for its Retry-After with the attempt
+    // UNCOUNTED, like a suspension — but left in the ready bucket (no park): it is a job still
+    // waiting, and it belongs in `queue_depth`. Counted, a backlog of rate-limited `llm()` jobs was
+    // dead-lettered for having waited on a bucket that was only ever going to refill.
+    const deferMs = rateLimitDeferralMs(handle.retry, claimed.attempt, error);
+    if (deferMs !== undefined) {
+      landed(
+        await driver.nack(claimed.id, {
+          ...by(),
+          delayMs: deferMs,
+          error: failureForRow(error),
+          countsAsAttempt: false,
+        }),
+        'retried',
+      );
+      logger.info('jobs.attempt.rate_limited', {
+        job: handle.name,
+        jobId: claimed.id,
+        attempt: claimed.attempt,
+        delayMs: deferMs,
+      });
+      return settle({
+        outcome: 'retried',
+        jobId: claimed.id,
+        job: handle.name,
+        attempt: claimed.attempt,
+        durationMs: nowMs(options.clock) - startedAt,
+        error: message,
+        resumeAt: nowMs(options.clock) + deferMs,
+        steps: [],
+        replayed: [],
+      });
+    }
     // The ERROR decides too, not only the attempt count. A `terminal` code — a rotated password,
     // a schema mismatch, a permission denial — fails identically on every remaining attempt, so
     // spending them is a queue slot, a provider bill and, at a site that locks an account after

package/src/export.ts

@@ -20,7 +20,7 @@ import { assert, systemClock } from '@ultimat3/core';
 import type { ReadBuilder } from '@ultimat3/entity';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { Pacer } from './backfill-rate';
-import { createPacer } from './backfill-rate';
+import { backfillPacer } from './backfill-rate';
 import type { DurationInput } from './clock';
 import { nowMs } from './clock';
 import type { ExportFormat, ExportRecord } from './export-format';
@@ -177,7 +177,7 @@ export function exportRows<Row, I>(definition: ExportDefinition<Row, I>): JobHan
   const pace =
     definition.rate === undefined
       ? undefined
-      : createPacer({ rate: definition.rate, job: definition.name, clock });
+      : backfillPacer({ rate: definition.rate, job: definition.name, clock });
 
   // Resolved per write, never here: this line runs at the app's import, before its storage exists.
   const planned: PlannedExport<Row, I> = {

package/src/heartbeat.ts

@@ -98,6 +98,11 @@ export function startLeaseHeartbeat(options: LeaseHeartbeatOptions): LeaseHeartb
     // request per tick onto the connection that is already the thing failing.
     if (renewing) return;
     renewing = true;
+    // Stamped BEFORE the call: the driver writes the new lease at the statement, so the window it
+    // bought starts no later than this. Stamped at the reply instead, a slow answer would stretch
+    // this process's view of the lease past the server's by the reply's latency — and a second
+    // worker re-claims the row while this one still believes it holds it.
+    const sentAt = now();
     try {
       const held = await options.driver.heartbeat(claimed.id, {
         visibilityTimeoutMs,
@@ -121,14 +126,14 @@ export function startLeaseHeartbeat(options: LeaseHeartbeatOptions): LeaseHeartb
       }
       // Asked again AFTER the call, because a renewal that SUCCEEDS late is still late: an
       // event-loop stall or a driver that answered at the end of a connect timeout can land this
-      // past the window it was renewing, and `renewedAt = now()` there would restart the clock on
+      // past the window it was renewing, and renewing there would restart the clock on
       // a lease the queue has already re-delivered — the loss hidden by the very call meant to
       // prevent it.
       if (lapsed()) {
         reportLost();
         return;
       }
-      renewedAt = now();
+      renewedAt = sentAt;
     } catch (error) {
       // One failed renewal is not a lost lease: there is a whole visibility window left to land
       // the next one, and the default interval gives three tries inside it. Say it at warn and

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 { 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.
@@ -84,6 +71,8 @@ export {
   isBackfill,
   registeredBackfills,
 } from './backfill-registry';
+export type { AnnounceExhaustedOptions, ExhaustedCounts } from './claim-exhausted';
+export { announceExhausted } from './claim-exhausted';
 export type { JobConcurrency, KeyedConcurrency, WhenBusy } from './concurrency';
 export { MAX_CONCURRENCY_KEY_LENGTH, WHEN_BUSY } from './concurrency';
 export type { JobConcurrencyDescriptor, JobDescriptor } from './describe';
@@ -112,66 +101,20 @@ export {
   isJobState,
   JOB_STATES,
   jobDriver,
+  LEASE_LAPSED_FINAL_ATTEMPT,
+  LIVE_STATES,
   nackState,
   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, PgExecutor } 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 {
@@ -190,7 +133,6 @@ export {
   JobNotCancellableError,
   JobRowStatusUnknownError,
   JobSlotLostError,
-  JobsNotImplementedError,
   JobTenantRequiredError,
   JobTimeoutError,
   LeaseLostError,
@@ -210,17 +152,19 @@ export {
   JobOnSettledFailedError,
   JobPageInvalidError,
 } from './errors-operator';
-export { JobNotRequeueableError } from './errors-requeue';
+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';
@@ -291,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,
@@ -301,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,
@@ -311,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,
@@ -347,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,
@@ -356,27 +300,28 @@ 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 {
   EventLookup,
   StepApi,
+  StepFence,
   StepRecord,
   StepRunner,
   StepRunnerOptions,
@@ -385,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,
@@ -415,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,
@@ -432,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

@@ -3,16 +3,16 @@
 // know whether the job is gone or was never theirs to remove. Apart from `inspect.ts`, which is
 // the read side.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { JobDriver, JobRecord } from './driver';
-import { JobsNotImplementedError } from './errors';
 import { JobNotPromotableError } from './errors-operator';
 import type { JobIntrospection, PausedName } from './introspection';
 
 function operatorOf(driver: JobDriver): JobIntrospection {
   if (driver.introspect === undefined) {
-    throw new JobsNotImplementedError({
-      feature: `the operator surface of the "${driver.name}" jobs driver`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — the pg driver implements introspect — then: x jobs ls --json',
+    throw new NotImplementedError({
+      cause: `the operator surface of the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — the pg driver implements introspect — then: x jobs ls --json',
     });
   }
   return driver.introspect;

package/src/inspect.ts

@@ -2,11 +2,12 @@
 // object so `x jobs ... --json` and the MCP tool share one shape — an agent debugging a stuck
 // queue reads exactly what the dashboard renders.
 
+import { NotImplementedError } from '@ultimat3/core';
 import type { BackfillProgress } from './backfill-inspect';
 import { backfillForRun } from './backfill-inspect';
 import type { WhenBusy } from './concurrency';
 import type { JobDriver, JobRecord, QueueStats } from './driver';
-import { CancelUnsupportedError, JobNotCancellableError, JobsNotImplementedError } from './errors';
+import { CancelUnsupportedError, JobNotCancellableError } from './errors';
 import type { JobFilter, JobProgress } from './introspection';
 import type { AnyJobHandle } from './job';
 import { registeredJobs } from './job';
@@ -111,9 +112,9 @@ const iso = (ms: number | undefined): string | null =>
 
 function requireIntrospection(driver: JobDriver): NonNullable<JobDriver['introspect']> {
   if (driver.introspect === undefined) {
-    throw new JobsNotImplementedError({
-      feature: `introspection for the "${driver.name}" jobs driver`,
-      fix: 'call setJobDriver(createPgDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
+    throw new NotImplementedError({
+      cause: `introspection for the "${driver.name}" jobs driver is not implemented: the driver has no introspect`,
+      fix: 'call setJobDriver(postgresJobDriver()) at boot — only the pg driver implements introspect — then: x jobs ls --json',
     });
   }
   return driver.introspect;