@ultimat3/jobs 23.0.0 → 24.0.0

package/src/inspect-operator.ts

@@ -3,15 +3,15 @@
 // 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`,
+    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',
     });
   }

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,8 +112,8 @@ 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`,
+    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',
     });
   }

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';
@@ -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/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';
@@ -261,16 +271,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-pg.ts

@@ -9,11 +9,10 @@
 // `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 type { Clock, PgExecutor } from '@ultimat3/core';
 import { uuid } 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,

package/src/outbox.ts

@@ -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,
+  uuid,
+} from '@ultimat3/core';
 import type { Tx } from '@ultimat3/entity';
 import { nowMs } from './clock';
 import type { EnqueueResult, JobDriver } from './driver';
@@ -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: uuid() } to enqueue(), with import { uuid } 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(),
+    runId: runId ?? uuid(),
     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 {
@@ -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 }),

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/scheduler-pg.ts

@@ -3,11 +3,10 @@
 // both failures are silent — a redeployed pod arms to tomorrow and never reports the 03:00 run the
 // pod it replaced dropped, and two pods in a rolling update both dispatch every task.
 
-import type { Clock } from '@ultimat3/core';
+import type { Clock, PgExecutor } from '@ultimat3/core';
 import { finiteOption, uuid } from '@ultimat3/core';
 import { nowMs } from './clock';
 import { DEFAULT_QUEUE } from './driver';
-import type { PgExecutor } from './driver-pg';
 import { SQL_SCHEDULER_FIRE } from './driver-pg-operator-sql';
 import {
   SQL_LEADER_ACQUIRE,
@@ -62,6 +61,8 @@ export function pgSchedulerState(executor: PgExecutor): SchedulerState {
             max_attempts: request.maxAttempts,
           })),
         ),
+        // Where the watermark lands when that is past the occurrence (`run-once`): ONE statement.
+        fire.watermarkMs ?? null,
       ]);
       if (Number(rows[0]?.fired ?? 0) === 0) return undefined;
       const queued = new Map(

package/src/scheduler-state.ts

@@ -9,6 +9,13 @@ import type { EnqueueRequest, EnqueueResult, JobDriver } from './driver';
 export interface ScheduledFire {
   readonly task: string;
   readonly occurrenceMs: number;
+  /**
+   * Where the watermark LANDS, when that is past the occurrence: `run-once` runs the earliest
+   * missed occurrence and drops the rest, and dropping is moving the watermark past them — in the
+   * same write, or a crash between the two fires a second "one catch-up". The fence is still the
+   * occurrence. Omitted, the watermark lands on the occurrence.
+   */
+  readonly watermarkMs?: number;
   readonly jobs: readonly EnqueueRequest[];
 }
 
@@ -44,7 +51,7 @@ export async function fireThroughDriver(
   if (last !== undefined && last >= fire.occurrenceMs) return undefined;
   const results: EnqueueResult[] = [];
   for (const request of fire.jobs) results.push(await driver.enqueue(request));
-  await state.markFired(fire.task, fire.occurrenceMs);
+  await state.markFired(fire.task, fire.watermarkMs ?? fire.occurrenceMs);
   // What an operator reads as "last fired". After the watermark, so a record never names an
   // occurrence a crash would fire again.
   await driver.introspect?.recordTaskFire({ task: fire.task, occurrenceMs: fire.occurrenceMs });

package/src/scheduler.ts

@@ -144,6 +144,7 @@ export function createScheduler(options: SchedulerOptions): Scheduler {
     handle: TaskHandle,
     occurrenceMs: number,
     catchUp: boolean,
+    watermarkMs?: number,
   ): Promise<DispatchedOccurrence | undefined> => {
     // The occurrence, not `at`: a catch-up dispatch runs long after the instant it fires for,
     // and the payload has to describe the occurrence the email/report claims to be about.
@@ -166,6 +167,7 @@ export function createScheduler(options: SchedulerOptions): Scheduler {
     const results = await schedulerState.fire(options.driver, {
       task: handle.name,
       occurrenceMs,
+      ...(watermarkMs === undefined ? {} : { watermarkMs }),
       jobs: requests,
     });
     if (results === undefined) {
@@ -323,16 +325,13 @@ export function createScheduler(options: SchedulerOptions): Scheduler {
         if (handle.catchUp === 'run-once') {
           const first = due[0];
           if (first !== undefined) {
-            const ran = fired(await dispatch(handle, first, due.length > 1));
-            // `dispatch` leaves the watermark on the occurrence it RAN — the earliest missed one
-            // here — so the next round found occurrences 2..n still due and fired the second, then
-            // the third, one per tick until the backlog drained: 24 nightly digests a second apart
-            // after a day down. "One catch-up" means the rest are DROPPED, and dropping an
-            // occurrence is moving the watermark past it. `at` rather than the last element of
-            // `due`, which `maxCatchUp` truncates: every occurrence at or before `at` is missed by
-            // definition, and this policy fires none of them.
-            if (first !== at) await schedulerState.markFired(handle.name, at);
-            if (ran) remember(handle, Math.max(first, at));
+            // "One catch-up" means the rest are DROPPED, and dropping an occurrence is moving the
+            // watermark past it: left on the occurrence that RAN, the next round found 2..n still
+            // due and fired one per tick — 24 nightly digests a second apart after a day down.
+            // `at` rather than the last element of `due`, which `maxCatchUp` truncates. It rides
+            // the FIRE (`watermarkMs`): a `markFired` behind it was a second write, and a scheduler
+            // that died between the two handed its successor another catch-up.
+            if (fired(await dispatch(handle, first, due.length > 1, at))) remember(handle, at);
           }
           continue;
         }

package/src/steps-suspension.ts

@@ -0,0 +1,46 @@
+// A run that unwinds on purpose: the `StepSuspension` a `sleep` or `waitForEvent` throws, and the
+// marker a timed-out wait persists. Split from `steps.ts` at the file-size ceiling — that file is
+// the runner; this is the control flow the worker reads off what the runner threw.
+
+/**
+ * Control flow, not a failure: it must never be logged as an error or counted as an attempt.
+ * Branded by string rather than `instanceof` so two copies of this module still agree.
+ */
+export class StepSuspension extends Error {
+  static readonly brand = 'ultimate.jobs.suspension';
+  readonly brand: string = StepSuspension.brand;
+  readonly step: string;
+  readonly resumeAt: number;
+  readonly reason: 'sleep' | 'event';
+
+  constructor(input: { step: string; resumeAt: number; reason: 'sleep' | 'event' }) {
+    super(`step "${input.step}" suspended until ${new Date(input.resumeAt).toISOString()}`);
+    this.name = 'StepSuspension';
+    this.step = input.step;
+    this.resumeAt = input.resumeAt;
+    this.reason = input.reason;
+  }
+}
+
+/**
+ * What a timed-out `waitForEvent` persists, and maps back to `undefined` on replay. `undefined`
+ * itself cannot survive a store — the pg driver writes `JSON.stringify(output ?? null)` — so the
+ * timeout replayed as `null` and `evt === undefined` read as "an event arrived". A namespaced key
+ * rather than a bare `{ timedOut: true }`, so no event payload can be mistaken for the marker.
+ */
+export const WAIT_TIMED_OUT = Object.freeze<Record<string, true>>({
+  '~ultimate.waitTimedOut': true,
+});
+
+export function isWaitTimedOut(output: unknown): boolean {
+  return (
+    typeof output === 'object' &&
+    output !== null &&
+    Object.keys(output).length === 1 &&
+    (output as Record<string, unknown>)['~ultimate.waitTimedOut'] === true
+  );
+}
+
+export function isStepSuspension(error: unknown): error is StepSuspension {
+  return error instanceof Error && (error as { brand?: unknown }).brand === StepSuspension.brand;
+}

package/src/steps-timeout.ts

@@ -0,0 +1,33 @@
+// A step's own ceiling: the race between a step body and `stepTimeout`. Split from `steps.ts` at
+// the file-size ceiling — that file is the runner, and this is the one timer it arms.
+
+/**
+ * A step's own ceiling. It ABORTS before it rejects, in that order: `run()` fails the step on this
+ * rejection and the job retries, so a body still holding a socket open past the deadline would be
+ * racing the attempt that replaced it. Cancelling first is the only thing that can stop it.
+ */
+export function withStepTimeout<T>(
+  work: Promise<T> | T,
+  timeoutMs: number | undefined,
+  deadline: AbortController,
+  error: () => Error,
+): Promise<T> {
+  if (timeoutMs === undefined || timeoutMs <= 0) return Promise.resolve(work);
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      const failure = error();
+      deadline.abort(failure);
+      reject(failure);
+    }, timeoutMs);
+    Promise.resolve(work).then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (cause) => {
+        clearTimeout(timer);
+        reject(cause);
+      },
+    );
+  });
+}