@ultimat3/jobs 22.14.0 → 23.0.0

package/src/driver.ts

@@ -11,6 +11,7 @@
 import { finiteCount, finiteOption } from '@ultimat3/core';
 import type { BackfillLedger } from './backfill-ledger';
 import { ClaimQueuesEmptyError } from './errors';
+import type { JobIntrospection, JobProgress } from './introspection';
 import type { LeaseStore } from './leases';
 import type { StepStore } from './steps';
 
@@ -66,7 +67,13 @@ export interface JobRecord {
   /** Actor's orgId, for per-tenant limits. */
   readonly tenantId?: string;
   readonly lastError?: string;
+  /** The thrown value's stack for `lastError`, bounded (`MAX_ERROR_STACK_LENGTH`). */
+  readonly lastErrorStack?: string;
+  /** What the body last reported through `progress()` — see `introspection.ts`. */
+  readonly progress?: JobProgress;
   readonly claimedBy?: string;
+  /** How many times this row has been claimed. Absent until the first claim. */
+  readonly claim?: number;
   readonly visibleAt?: number;
   /**
    * W3C `traceparent` of the request that queued this job. The job's span is opened as a CHILD of
@@ -81,6 +88,13 @@ export interface JobRecord {
 export type ConflictPolicy = 'dedupe' | 'error';
 
 export interface EnqueueRequest {
+  /**
+   * The row's id, when the caller already allocated one. The outbox does, at STAGE time, so the
+   * enqueue that staged it can name the job before it exists — and so a row published twice
+   * meets the job its first publish made (`deduped: true`), live or finished, instead of
+   * inserting a second one. Omit it everywhere else: the driver mints one.
+   */
+  readonly id?: string;
   readonly name: string;
   readonly queue: string;
   readonly input: unknown;
@@ -89,7 +103,10 @@ export interface EnqueueRequest {
   /** Epoch ms. Omit for "now". */
   readonly runAt?: number;
   readonly tenantId?: string;
-  /** Reuse an existing run id when resuming, so step history is preserved. */
+  /**
+   * The run's id — the key its steps, its events and its prompts hang off. Allocated by the
+   * outbox at stage time or named by the caller (`EnqueueOptions.runId`); minted here otherwise.
+   */
   readonly runId?: string;
   readonly onConflict?: ConflictPolicy;
   /** W3C `traceparent` of the enqueuing request. The facade stamps it; callers rarely set it. */
@@ -132,12 +149,57 @@ export interface ClaimOptions {
 export interface ClaimedJob extends JobRecord {
   readonly claimedAt: number;
   readonly visibleAt: number;
+  /** The worker this claim was made for. */
+  readonly claimedBy: string;
+  /**
+   * THIS claim, as the row's claim ordinal: 1 for the first, one more for each after it, never
+   * reset. With `claimedBy` it is the identity every settle, renewal and progress write of this
+   * claim is fenced on — `claimOf(claimed)` is how a caller carries the pair.
+   */
+  readonly claim: number;
+}
+
+/**
+ * WHICH claim is acting. `workerId` alone was the fence, and it names a worker, not a claim: a
+ * worker that takes back its own lapsed job is the same worker, so the body still unwinding from
+ * the first claim settled the second. The ordinal is what tells the two apart.
+ */
+export interface ClaimIdentity {
+  readonly workerId: string;
+  readonly claim: number;
+}
+
+export const claimOf = (claimed: Pick<ClaimedJob, 'claimedBy' | 'claim'>): ClaimIdentity => ({
+  workerId: claimed.claimedBy,
+  claim: claimed.claim,
+});
+
+/**
+ * Who settles a claim, and how long the attempt ran. The identity is the FENCE: a settle from a
+ * claim the row no longer carries matches nothing. The lease lapses, the row is claimed again —
+ * by another worker or by this one — and the first body unwinds: its ack would mark the second
+ * run `done`, its nack would hand a running job to a third. `durationMs` feeds the per-minute
+ * counters the same statement writes.
+ */
+export interface SettleBy extends ClaimIdentity {
+  readonly durationMs?: number;
+}
+
+export interface AckOptions extends SettleBy {
+  /**
+   * False when the row is finished WITHOUT its body having run here — `x jobs drain` moving it to
+   * another driver. It is settled `done` and adds nothing to the job's counters: a job that was
+   * moved is not a job that completed.
+   */
+  readonly counted?: boolean;
 }
 
-export interface NackOptions {
+export interface NackOptions extends SettleBy {
   /** Delay before the job becomes claimable again. */
   readonly delayMs: number;
   readonly error?: string;
+  /** The thrown value's stack, kept beside `error` for `x jobs show`. */
+  readonly stack?: string;
   /**
    * The ATTEMPT COUNTER, and nothing else. False for a suspension and for a shed alike: neither is
    * a failure, and a 3-day sleep that burned an attempt would dead-letter the job.
@@ -157,14 +219,37 @@ export interface NackOptions {
    */
   readonly park?: boolean;
   readonly deadLetter?: boolean;
+  /**
+   * Terminal WITHOUT the dead-letter queue: the row settles `failed` — finished, never claimed
+   * again, requeueable by `x jobs retry`, and absent from `queue_dead_jobs`. For an ending that is
+   * an answer rather than a fault: `whenBusy: 'fail'` over a busy concurrency key
+   * (`X_JOB_KEY_BUSY`). `deadLetter` wins when both are set, and `park` loses to both.
+   */
+  readonly fail?: boolean;
 }
 
+/**
+ * The state a nack leaves its row in — ONE reading, for every driver. It was a three-way written
+ * out in each, which is two places for a fourth branch to land in one and not the other; a
+ * `fail` the pg driver filed as `ready` would re-claim a refused run forever.
+ */
+export const nackState = (options: NackOptions): JobState =>
+  options.deadLetter === true
+    ? 'dead'
+    : options.fail === true
+      ? 'failed'
+      : options.park === true
+        ? 'suspended'
+        : 'ready';
+
 export interface QueueStats {
   readonly queue: string;
   readonly ready: number;
   readonly delayed: number;
   readonly running: number;
   readonly suspended: number;
+  /** Rows that ended `failed` — refused by a busy key, or exhausted with `deadLetter: false`. */
+  readonly failed: number;
   readonly dead: number;
   /**
    * Age in ms of the oldest job that is READY and due — the number that decides autoscaling.
@@ -174,40 +259,12 @@ export interface QueueStats {
   readonly oldestReadyMs: number;
 }
 
-export interface JobFilter {
-  readonly queue?: string;
-  readonly name?: string;
-  readonly state?: JobState;
-  readonly limit?: number;
-}
-
-/** Optional: powers `/_x` and the MCP tools. A minimal driver may omit it. */
-export interface JobIntrospection {
-  job(jobId: string): Promise<JobRecord | undefined>;
-  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.
-   */
-  requeue(jobId: string, options?: { readonly fromStep?: string }): Promise<JobRecord>;
-  /**
-   * Stop a job from outside. The only answer to a runaway pass that was otherwise "scale the
-   * worker to zero" (which stops every job) or a hand-written `UPDATE` (which the running
-   * worker's next ack overwrote). 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.
-   *
-   * Optional on the interface for the reason `requeue` is not: a driver may have no way to
-   * address a single row. Answers `undefined` for a job id it does not hold.
-   */
-  cancel?(jobId: string, reason?: string): Promise<JobRecord | undefined>;
-}
-
 export interface HeartbeatOptions {
   readonly visibilityTimeoutMs: number;
   /** Renew only if this worker is still the claimant. Omit and any claimant matches. */
   readonly workerId?: string;
+  /** Renew only if the row still carries THIS claim (`ClaimedJob.claim`). Omit and any does. */
+  readonly claim?: number;
 }
 
 export interface JobDriver {
@@ -216,8 +273,13 @@ export interface JobDriver {
   readonly steps: StepStore;
   enqueue(request: EnqueueRequest): Promise<EnqueueResult>;
   claim(options: ClaimOptions): Promise<readonly ClaimedJob[]>;
-  ack(jobId: string): Promise<void>;
-  nack(jobId: string, options: NackOptions): Promise<void>;
+  /**
+   * Both settles are fenced on `state = 'running'` AND on the claimer, and both answer whether
+   * they LANDED. `false` is a settle from a worker that no longer owns the row — logged by the
+   * caller, never thrown: the row is somebody else's now and theirs is the verdict.
+   */
+  ack(jobId: string, by: AckOptions): Promise<boolean>;
+  nack(jobId: string, options: NackOptions): Promise<boolean>;
   /**
    * Extends the lease of a long-running job so it is not double-claimed.
    *

package/src/enqueue-signal.ts

@@ -0,0 +1,50 @@
+// "Work just arrived." A worker or relay that has backed off (`idle-backoff.ts`) is woken by it at
+// once, so the backoff is never the latency of a job. Two signals, because they wake two loops: a
+// job on the queue wakes workers, a row staged in the outbox wakes the relay. Raised in-process by
+// whatever queued the work here, and by `queue-wake.ts` for work ANOTHER process committed — it
+// holds the `LISTEN` this file knows nothing about.
+
+function channel<A extends readonly unknown[]>(): {
+  on(listener: (...args: A) => void): () => void;
+  signal(...args: A): void;
+} {
+  const listeners = new Set<(...args: A) => void>();
+  return {
+    on(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    signal(...args) {
+      for (const listener of listeners) listener(...args);
+    },
+  };
+}
+
+const enqueued = channel<[queue?: string]>();
+const staged = channel<[committed?: boolean]>();
+
+/** A job landed on `queue` — on any queue, when none is named. Returns the unsubscribe. */
+export const onEnqueued = enqueued.on;
+export const signalEnqueued = enqueued.signal;
+/**
+ * A row was staged in the outbox. `committed` is what tells the relay whether a pass NOW can find
+ * it: a stage signalled by this process is still inside its transaction, one announced by
+ * Postgres has committed.
+ */
+export const onStaged = staged.on;
+export const signalStaged = staged.signal;
+
+let live = false;
+
+/**
+ * Whether work committed by ANOTHER process reaches the two signals above — a `LISTEN` is held
+ * and a notification has crossed it (`queue-wake.ts`). The idle loops read it to choose their
+ * ceiling: with no wake, the poll is the only thing bounding a job's start.
+ */
+export const wakeIsLive = (): boolean => live;
+
+export function setWakeLive(value: boolean): void {
+  live = value;
+}

package/src/errors-concurrency.ts

@@ -0,0 +1,91 @@
+// Single responsibility: the refusals `job.concurrency` earns — a cap mis-declared, a key that
+// cannot name a lease, a key already holding its limit, and a driver that cannot hold the cap.
+// Its own module because `errors.ts` sits at the size ceiling; the CODES are registered there,
+// beside every other jobs code.
+
+import { isFixShellSafe, renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
+
+/**
+ * `concurrency: { key, limit, whenBusy }` declared with a member no worker can honour. The shipped
+ * `X_JOB_DECLARATION_INVALID` and not a code of its own: it is the same statement — this `job()`
+ * call cannot be seated as written — and the same repair, an edit to the declaration.
+ *
+ * `declared` is rendered by core's total reader, never interpolated: it arrives from generated
+ * code and JS callers, which is the only way a value the type forbids reaches here at all.
+ */
+export class JobConcurrencyInvalidError extends UltimateError {
+  constructor(input: { job: string; field: string; declared: unknown; why: string; edit: string }) {
+    super({
+      code: 'X_JOB_DECLARATION_INVALID',
+      cause: `job "${input.job}" declares ${input.field} ${renderCauseValue(input.declared)}, ${input.why}`,
+      fix: `${input.edit} on job('${input.job}')`,
+      meta: { job: input.job, field: input.field },
+    });
+  }
+}
+
+/** Why a key cannot name a lease. `unreadable` is a key function that answered a non-string. */
+export type ConcurrencyKeyDefect = 'empty' | 'unreadable' | 'too-long';
+
+const KEY_DEFECT_CAUSE = Object.freeze<Record<ConcurrencyKeyDefect, string>>({
+  empty:
+    'answered an empty string for this input — an empty key is one lock shared by every run, which nobody declared',
+  unreadable: 'answered something that is not a string, and a lease is keyed by text',
+  'too-long': 'answered a key longer than a lease row can be keyed by',
+});
+
+/**
+ * `concurrency.key(input)` answered a value that cannot key a lease — refused where the run is
+ * ENQUEUED, because that is the first moment an input exists to ask the function about.
+ *
+ * The key itself never reaches the cause or the meta: it is computed from an input, so it is app
+ * data, and this error is logged by whatever caught the enqueue.
+ */
+export class JobConcurrencyKeyInvalidError extends UltimateError {
+  constructor(input: { job: string; defect: ConcurrencyKeyDefect; maxLength: number }) {
+    super({
+      code: 'X_JOB_DECLARATION_INVALID',
+      cause: `job "${input.job}" concurrency.key ${KEY_DEFECT_CAUSE[input.defect]}`,
+      fix: `return a non-empty string of at most ${input.maxLength} characters from concurrency.key on job('${input.job}') — key: (input) => input.accountId — or declare concurrency: 1 for one cap across every run`,
+      meta: { job: input.job, defect: input.defect },
+    });
+  }
+}
+
+/**
+ * A run claimed under `whenBusy: 'fail'` while its key already held `limit` runs. The run settles
+ * `failed` with this as its `lastError`, its body never runs and nothing retries it — the declared
+ * answer to "a second run of this key", which is why it is neither a dead letter nor a fault.
+ */
+export class JobKeyBusyError extends UltimateError {
+  constructor(input: { job: string; key: string; limit: number }) {
+    super({
+      code: 'X_JOB_KEY_BUSY',
+      cause: `job "${input.job}" key ${renderCauseValue(input.key)} already holds ${input.limit} run(s)`,
+      // A name the shell would not read verbatim drops the filter rather than travelling as a
+      // placeholder: `--name <job>` is a redirection, and a fix that fails is no fix. The splice
+      // still goes through `renderFixShellArg` — the screen `bun run error-render` looks for —
+      // whose placeholder the guard above makes unreachable.
+      fix: isFixShellSafe(input.job)
+        ? `x jobs ls --name ${renderFixShellArg(input.job, 'job')} --state running --json`
+        : 'x jobs ls --state running --json',
+      meta: { job: input.job, key: input.key, limit: input.limit },
+    });
+  }
+}
+
+/**
+ * `job.concurrency` is declared and this driver has no `leases`, so the cap is per PROCESS and the
+ * fleet runs `concurrency x replicas`. Thrown at worker start rather than logged, because a
+ * documented guarantee that silently does nothing is exactly what axiom 3 exists to refuse — the
+ * worker refuses to start instead of running with the wrong number.
+ */
+export class ConcurrencyUnenforceableError extends UltimateError {
+  constructor(input: { driver: string; jobs: readonly string[] }) {
+    super({
+      code: 'X_JOB_CONCURRENCY_UNENFORCEABLE',
+      cause: `${input.jobs.join(', ')} declare concurrency and the "${input.driver}" jobs driver has no lease store, so the cap would hold per process and the fleet would run concurrency x replicas`,
+      fix: `remove concurrency from job("${input.jobs[0] ?? 'the job'}"), or call setJobDriver(createPgDriver()) at boot — the pg driver is the one with a lease store`,
+    });
+  }
+}

package/src/errors-operator.ts

@@ -0,0 +1,94 @@
+// Single responsibility: the refusals the operator surface gives — a job that cannot be removed
+// or promoted, a page it cannot answer — and the one failure it only ever reports, a settled
+// run's `onSettled` hook. Its own
+// module because `errors.ts` sits at the size ceiling; the codes are registered there.
+
+import { isFixShellSafe, renderFixShellArg, renderThrowable, UltimateError } from '@ultimat3/core';
+
+/** A command over one job id, or the listing when the id would not survive a shell verbatim. */
+const jobCommand = (verb: string, jobId: string): string =>
+  isFixShellSafe(jobId)
+    ? `x jobs ${verb} ${renderFixShellArg(jobId, 'id')} --json`
+    : 'x jobs ls --state running --json';
+
+/** `remove()` / `removeMany()` reached a job a worker holds. Cancel stops the body; then remove. */
+export class JobNotRemovableError extends UltimateError {
+  constructor(input: { jobId?: string }) {
+    super({
+      code: 'X_JOB_NOT_REMOVABLE',
+      cause:
+        input.jobId === undefined
+          ? 'a bulk remove named the running state, and a row a worker holds cannot be deleted under its body'
+          : `job ${input.jobId} is running, and deleting the row under its body would not stop the body`,
+      fix:
+        input.jobId === undefined
+          ? 'x jobs ls --state running --json'
+          : jobCommand('cancel', input.jobId),
+      meta: { ...(input.jobId === undefined ? {} : { jobId: input.jobId }) },
+    });
+  }
+}
+
+/** `promote()` reached a job that is not waiting on its `runAt`. */
+export class JobNotPromotableError extends UltimateError {
+  constructor(input: { jobId: string; state: string }) {
+    super({
+      code: 'X_JOB_NOT_PROMOTABLE',
+      cause:
+        input.state === 'missing'
+          ? `no job ${input.jobId} exists in this queue`
+          : `job ${input.jobId} is ${input.state} and is not waiting on its run time — only a delayed job, or one backing off before a retry, can be promoted`,
+      fix: jobCommand('show', input.jobId),
+      meta: { jobId: input.jobId, state: input.state },
+    });
+  }
+}
+
+/**
+ * Built to be LOGGED and reported, never thrown at a caller: the run is already settled, the hook
+ * is the app's reaction to that, and a reaction that fails is not a reason to settle it again.
+ */
+export class JobOnSettledFailedError extends UltimateError {
+  constructor(input: {
+    job: string;
+    jobId: string;
+    outcome: string;
+    attempts: number;
+    error: unknown;
+  }) {
+    super({
+      code: 'X_JOB_ON_SETTLED_FAILED',
+      cause: `onSettled for job "${input.job}" (${input.jobId}, ${input.outcome}) failed ${input.attempts} time(s): ${renderThrowable(input.error)}`,
+      fix: jobCommand('show', input.jobId),
+      meta: {
+        job: input.job,
+        jobId: input.jobId,
+        outcome: input.outcome,
+        attempts: input.attempts,
+      },
+    });
+  }
+}
+
+/**
+ * `list()` was asked for a page it does not answer: more rows than one page holds, or a cursor no
+ * page produced. Its own code, never the bare invariant it was: the reader is a dashboard author
+ * with a `limit` in a query string, and what they need is the bound by name and the call that
+ * walks past it. `MAX_JOB_PAGE` is passed in — `introspection.ts` owns it and imports this file.
+ */
+export class JobPageInvalidError extends UltimateError {
+  constructor(input: { subject: string; maxPage: number; limit?: number }) {
+    super({
+      code: 'X_JOB_PAGE_INVALID',
+      cause:
+        input.limit === undefined
+          ? `${input.subject} was handed an after cursor that no previous page produced`
+          : `${input.subject} limit is ${input.limit}, over MAX_JOB_PAGE (${input.maxPage}) — the rows one page may answer`,
+      fix: `list({ limit: ${input.maxPage}, after: jobCursor(lastRow) })   # lastRow is the last row of the page before; omit after for the first page, and stop at a page shorter than its limit`,
+      meta: {
+        maxPage: input.maxPage,
+        ...(input.limit === undefined ? {} : { limit: input.limit }),
+      },
+    });
+  }
+}

package/src/errors.ts

@@ -38,6 +38,11 @@ export const JOB_OWNED_ERROR_CODES = [
   'X_EXPORT_PART_TOO_LARGE',
   'X_JOB_DECLARATION_INVALID',
   'X_JOB_NOT_REQUEUEABLE',
+  'X_JOB_KEY_BUSY',
+  'X_JOB_NOT_REMOVABLE',
+  'X_JOB_NOT_PROMOTABLE',
+  'X_JOB_PAGE_INVALID',
+  'X_JOB_ON_SETTLED_FAILED',
 ] as const;
 
 /**
@@ -88,8 +93,13 @@ export const JOB_ERROR_TITLES: Readonly<Record<JobOwnedErrorCode, string>> = {
   X_WEBHOOK_DELIVERY_REJECTED: 'the endpoint refused the delivery in a way a retry cannot change',
   X_EXPORT_ROW_INVALID: 'row() answered something the declared columns do not carry',
   X_EXPORT_PART_TOO_LARGE: 'one page encoded to more bytes than a part may hold',
-  X_JOB_DECLARATION_INVALID: 'the job declaration is missing a required field',
+  X_JOB_DECLARATION_INVALID: 'the job declaration is missing or mis-declares a field',
   X_JOB_NOT_REQUEUEABLE: 'the job is still live and cannot be requeued',
+  X_JOB_KEY_BUSY: 'the concurrency key already holds its limit of runs',
+  X_JOB_NOT_REMOVABLE: 'the job is running and cannot be removed',
+  X_JOB_NOT_PROMOTABLE: 'the job is not waiting on its run time',
+  X_JOB_PAGE_INVALID: 'a job list page was asked for outside its bounds',
+  X_JOB_ON_SETTLED_FAILED: 'the onSettled hook failed after the run was settled',
 };
 
 // One unconditional call, so a second package claiming one of jobs' codes throws
@@ -141,6 +151,8 @@ registerErrorRetry({
   // the whole retry policy proving it.
   X_EXPORT_ROW_INVALID: 'terminal',
   X_EXPORT_PART_TOO_LARGE: 'terminal',
+  // The worker settles a busy key itself; listed so a body that RETHROWS one it was handed stops.
+  X_JOB_KEY_BUSY: 'terminal',
 });
 
 // No `docs:` on any class below, here or in `backfill-errors.ts`. `UltimateError` fills it from
@@ -431,22 +443,6 @@ export class CancelUnsupportedError extends UltimateError {
   }
 }
 
-/**
- * `job.concurrency` is declared and this driver has no `leases`, so the cap is per PROCESS and the
- * fleet runs `concurrency x replicas`. Thrown at worker start rather than logged, because a
- * documented guarantee that silently does nothing is exactly what axiom 3 exists to refuse — the
- * worker refuses to start instead of running with the wrong number.
- */
-export class ConcurrencyUnenforceableError extends UltimateError {
-  constructor(input: { driver: string; jobs: readonly string[] }) {
-    super({
-      code: 'X_JOB_CONCURRENCY_UNENFORCEABLE',
-      cause: `${input.jobs.join(', ')} declare concurrency and the "${input.driver}" jobs driver has no lease store, so the cap would hold per process and the fleet would run concurrency x replicas`,
-      fix: `remove concurrency from job("${input.jobs[0] ?? 'the job'}"), or call setJobDriver(createPgDriver()) at boot — the pg driver is the one with a lease store`,
-    });
-  }
-}
-
 /** An outbox enqueue happened with no ambient transaction to join. */
 export class OutboxNoTxError extends UltimateError {
   constructor(input: { job: string }) {

package/src/events-pg.ts

@@ -6,18 +6,18 @@
 // 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 type { Clock } from '@ultimat3/core';
-import { finiteOption, logger, renderThrowable, systemClock, uuid } from '@ultimat3/core';
+import { finiteOption, logger, renderThrowable, uuid } from '@ultimat3/core';
 import type { DurationInput } from './clock';
-import { finiteDurationMs, nowMs } 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,
 } from './driver-pg-sql';
-import type { EventBus, JobEvent } from './events';
+import type { EventBus } from './events';
 
 interface EventRow {
   readonly id: string;
@@ -29,8 +29,11 @@ interface EventRow {
 }
 
 export interface PgEventBusOptions {
+  /**
+   * 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.
+   */
   readonly executor: PgExecutor;
-  readonly clock?: Clock;
   /** How long an event stays matchable. Default 7d — longer than any sane wait. */
   readonly defaultTtl?: DurationInput;
   /** Rows returned by `list()`. Diagnostics only; `find()` is what a step uses. */
@@ -45,7 +48,6 @@ export interface PgEventBusOptions {
  * plus `expires_at > now()` in `find` means an unpurged row costs a filter, never a wrong answer.
  */
 export function createPgEventBus(options: PgEventBusOptions): EventBus {
-  const clock = options.clock ?? systemClock;
   // 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.
@@ -68,35 +70,43 @@ export function createPgEventBus(options: PgEventBusOptions): EventBus {
   };
 
   return {
+    stored: true,
+    async now() {
+      const rows = await exec.query<{ now: number | string }>(SQL_EVENT_NOW, []);
+      return Number(rows[0]?.now);
+    },
+
     async publish(name, payload, publishOptions = {}) {
-      const at = nowMs(clock);
-      const event: JobEvent = {
-        id: uuid(),
+      const id = uuid();
+      const ttlMs =
+        publishOptions.ttl === undefined
+          ? defaultTtlMs
+          : finiteDurationMs(publishOptions.ttl, 'the pg event bus', 'ttl');
+      const rows = await exec.query<{
+        published_at: number | string;
+        expires_at: number | string;
+      }>(SQL_EVENT_PUBLISH, [
+        id,
         name,
-        payload,
-        publishedAt: at,
-        expiresAt:
-          at +
-          (publishOptions.ttl === undefined
-            ? defaultTtlMs
-            : finiteDurationMs(publishOptions.ttl, 'the pg event bus', 'ttl')),
-        ...(publishOptions.correlationKey === undefined
-          ? {}
-          : { correlationKey: publishOptions.correlationKey }),
-      };
-      await exec.query(SQL_EVENT_PUBLISH, [
-        event.id,
-        event.name,
-        JSON.stringify(event.payload ?? null),
-        event.correlationKey ?? null,
-        event.publishedAt,
-        event.expiresAt,
+        JSON.stringify(payload ?? null),
+        publishOptions.correlationKey ?? null,
+        ttlMs,
       ]);
       logger.debug('jobs.event.published', {
         event: name,
         correlationKey: publishOptions.correlationKey ?? null,
       });
-      return event;
+      // The stamps the statement wrote, read back: what a consumer will compare against.
+      return {
+        id,
+        name,
+        payload,
+        publishedAt: Number(rows[0]?.published_at),
+        expiresAt: Number(rows[0]?.expires_at),
+        ...(publishOptions.correlationKey === undefined
+          ? {}
+          : { correlationKey: publishOptions.correlationKey }),
+      };
     },
 
     /** Earliest match at or after `afterMs`, so a resumed step consumes events in order. */

package/src/events.ts

@@ -25,6 +25,19 @@ export interface PublishOptions {
 }
 
 export interface EventBus extends EventLookup {
+  /**
+   * Whether an event published by ONE process is found by another. `true` for a bus over a table,
+   * `false` for the in-memory one — which is the whole question a wait across the web / worker
+   * 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;
@@ -65,6 +78,8 @@ export function createMemoryEventBus(options: MemoryEventBusOptions = {}): Event
   };
 
   return {
+    stored: false,
+    now: () => Promise.resolve(nowMs(clock)),
     publish(name, payload, publishOptions = {}) {
       purgeExpired();
       const at = nowMs(clock);
@@ -143,6 +158,16 @@ export function eventBus(): EventBus {
   return ambientBus;
 }
 
+/**
+ * Test seam, the counterpart of `resetJobDriver()` and `resetJobsFacade()`: back to a FRESH
+ * in-process bus, the state a process boots in. An event is matchable until it expires, so on a
+ * bus shared by a whole `bun test` process an answer one test published resumes the next test's
+ * wait before that test has asked anything — call this between tests.
+ */
+export function resetEventBus(): void {
+  ambientBus = createMemoryEventBus();
+}
+
 /** The one function app code calls to unblock a waiting step. */
 export function publishEvent(
   name: string,