@ultimat3/core 29.4.0 → 30.0.0

package/src/record-envelope.ts

@@ -21,16 +21,36 @@ export interface RecordEnvelope<T = unknown> {
   readonly records?: Readonly<Record<string, RecordRows>>;
   /** Record keys to drop, keyed by the entity's record type. */
   readonly removed?: Readonly<Record<string, readonly string[]>>;
+  /**
+   * A type's record keys in ANSWER order, sent only for a type whose `records` key order differs:
+   * every JS object — `JSON.parse`'s included — enumerates an integer-like key ascending, so an
+   * `integer()` key's order cannot ride `records` itself. Absent, `records` key order IS the order.
+   */
+  readonly order?: Readonly<Record<string, readonly string[]>>;
 }
 
-/** The server half. An empty `removed` is omitted, so the envelope never claims a deletion. */
+/**
+ * The server half. An empty `removed` is omitted, so the envelope never claims a deletion. `order`
+ * is each type's keys first-seen; only a type whose order an object would lose is sent, so an
+ * answer keyed by uuids stays byte-identical on the wire.
+ */
 export function encodeRecordEnvelope<T>(
   data: T,
   records: Readonly<Record<string, RecordRows>>,
   removed?: Readonly<Record<string, readonly string[]>>,
+  order?: Readonly<Record<string, readonly string[]>>,
 ): RecordEnvelope<T> {
   const hasRemoved = removed !== undefined && Object.keys(removed).length > 0;
-  return hasRemoved ? { data, records, removed } : { data, records };
+  const lost = Object.entries(order ?? {}).filter(([type, keys]) => {
+    const held = Object.keys(records[type] ?? {});
+    return keys.length !== held.length || keys.some((key, index) => key !== held[index]);
+  });
+  return {
+    data,
+    records,
+    ...(hasRemoved ? { removed } : {}),
+    ...(lost.length > 0 ? { order: nullProto(lost) } : {}),
+  };
 }
 
 /**
@@ -51,20 +71,24 @@ export function decodeRecordEnvelope(body: unknown): RecordEnvelope {
       }),
     );
   });
-  const removed = byType(body['removed'], 'removed', (keys, at) => {
-    if (!Array.isArray(keys)) throw envelopeInvalid(at, 'is not an array');
-    const list: unknown[] = keys;
-    const bad = list.findIndex((key) => typeof key !== 'string');
-    if (bad !== -1) throw envelopeInvalid(`${at} key #${bad}`, 'is not a string');
-    return list as string[];
-  });
+  const removed = byType(body['removed'], 'removed', keysOf);
+  const order = byType(body['order'], 'order', keysOf);
   return {
     data: body['data'],
     ...(records === undefined ? {} : { records }),
     ...(removed === undefined ? {} : { removed }),
+    ...(order === undefined ? {} : { order }),
   };
 }
 
+function keysOf(keys: unknown, at: string): string[] {
+  if (!Array.isArray(keys)) throw envelopeInvalid(at, 'is not an array');
+  const list: unknown[] = keys;
+  const bad = list.findIndex((key) => typeof key !== 'string');
+  if (bad !== -1) throw envelopeInvalid(`${at} key #${bad}`, 'is not a string');
+  return list as string[];
+}
+
 function byType<T>(
   value: unknown,
   member: string,

package/src/record-sink.ts

@@ -40,11 +40,18 @@ export interface ScopeCell {
   readonly listeners: Set<(next: ClientScope, prev: ClientScope) => void>;
 }
 
+/** Whether this page's session is lost (`session-lost.ts`). On the handle, so every copy agrees. */
+export interface SessionLostCell {
+  lost: boolean;
+  readonly listeners: Set<() => void>;
+}
+
 /** Headers every outbound request carries, or nothing. See `outbound-headers.ts`. */
 export type OutboundHeaders = () => Readonly<Record<string, string>>;
 
 interface PageClientHandle extends PageClient {
   readonly scopeCell: ScopeCell;
+  readonly sessionLost: SessionLostCell;
   /** The early-records buffer, or `undefined` where there is no page to install a store on. */
   readonly pending: PendingRecords | undefined;
   outboundHeaders: OutboundHeaders | undefined;
@@ -64,6 +71,11 @@ export function scopeCell(): ScopeCell {
   return handle().scopeCell;
 }
 
+/** The session-loss cell. Internal: `session-lost.ts` and `rescope()` are its callers. */
+export function sessionLostCell(): SessionLostCell {
+  return handle().sessionLost;
+}
+
 /**
  * Where decoded records go RIGHT NOW: the installed store, else the browser's pending buffer, else
  * nowhere. Internal: `client-transport.ts` is its one caller.
@@ -109,6 +121,7 @@ function handle(): PageClientHandle {
   const created: PageClientHandle = {
     socket: undefined,
     scopeCell: cell,
+    sessionLost: { lost: false, listeners: new Set() },
     pending,
     outboundHeaders: undefined,
     get store(): RecordSink | undefined {

package/src/redis-client.ts

@@ -0,0 +1,78 @@
+// Single responsibility: the framework's one Redis client — `@ultimat3/core/redis`, never the
+// barrel (core is in every bundle graph and this reads `Bun.RedisClient`). `Bun.redis`'s defaults
+// turn an outage into a hang and a restart into a dead tier; each option below is why it is not.
+// Measured 2026-11-02 on Redis 7, Bun 1.4.4 (plan 101, `29-data-redis-outage.md`).
+
+import type { RedisClient, RedisOptions } from 'bun';
+
+/** The local server Bun itself falls back to, so an unset environment dials the same place. */
+const LOCAL_REDIS_URL = 'redis://localhost:6379';
+
+export const REDIS_CLIENT_OPTIONS: Readonly<
+  Required<Pick<RedisOptions, 'enableOfflineQueue' | 'maxRetries' | 'connectionTimeout'>>
+> = Object.freeze({
+  /**
+   * why: with the offline queue on, a command issued while disconnected WAITS for a connection —
+   * the first read against a stopped server took 30,916 ms. Off, it refuses at once, and a refused
+   * cache read is a miss.
+   */
+  enableOfflineQueue: false,
+  /**
+   * why: the default 20 attempts are spent in ~31 s, then the client stays closed — a server
+   * back 37 s later still answered `ERR_REDIS_CONNECTION_CLOSED` on every pod until it restarted.
+   * The largest 32-bit count is "never give up"; with it the same restart recovered within 4 s.
+   */
+  maxRetries: 2_147_483_647,
+  /** why: the default 10 s connect is 10 s every reconnect attempt sits on an unanswering host. */
+  connectionTimeout: 1_000,
+});
+
+/** One client per process per URL: a second one is a second socket and a second reconnect loop. */
+const clients = new Map<string, RedisClient>();
+
+type RedisEnv = Readonly<Record<string, string | undefined>>;
+
+/** The variable that supplied a Redis URL, and the URL. */
+export interface RedisUrlSource {
+  readonly key: 'REDIS_URL' | 'VALKEY_URL';
+  readonly url: string;
+}
+
+/**
+ * `REDIS_URL`, the variable the CLI's tier selection reads; then `VALKEY_URL`, which `Bun.redis`
+ * also honours. An empty or blank value is unset; `undefined` when neither is set — the one
+ * precedence, for a caller that must tell an unset Redis from the local default.
+ */
+export function redisUrlSource(
+  env: RedisEnv = process.env as Record<string, string | undefined>,
+): RedisUrlSource | undefined {
+  for (const key of ['REDIS_URL', 'VALKEY_URL'] as const) {
+    const url = env[key]?.trim();
+    if (url !== undefined && url !== '') return { key, url };
+  }
+  return undefined;
+}
+
+/** `redisUrlSource`'s URL, else the local default. */
+export function redisUrl(
+  env: RedisEnv = process.env as Record<string, string | undefined>,
+): string {
+  return redisUrlSource(env)?.url ?? LOCAL_REDIS_URL;
+}
+
+/**
+ * The client for `url` (default `redisUrl()`), built once and connecting in the background: the
+ * caller never waits on a connect, and a command before the first connect is refused like any
+ * other command while down. `close()` on it closes it for every holder.
+ */
+export function redisClient(url: string = redisUrl()): RedisClient {
+  const held = clients.get(url);
+  if (held !== undefined) return held;
+  const client = new Bun.RedisClient(url, { ...REDIS_CLIENT_OPTIONS });
+  clients.set(url, client);
+  // why: the rejection is not lost — every command while unconnected is refused with
+  // `ERR_REDIS_CONNECTION_CLOSED`, which is where a caller learns of it. Unhandled, it would kill
+  // the process on a cold start against a server that is still coming up.
+  client.connect().catch(() => undefined);
+  return client;
+}

package/src/registrar.ts

@@ -81,13 +81,24 @@ export const PRIMITIVE_FACTORIES = Object.freeze<readonly PrimitiveFactory[]>(
       { factory: 'hive', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'llm', pkg: '@ultimat3/ai', kind: 'action' },
       { factory: 'backfill', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'consumer', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'exportRows', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'importRows', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'purge', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'refreshView', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'rollup', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'subjectErase', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'subjectExport', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'webhook', pkg: '@ultimat3/jobs', kind: 'job' },
+      { factory: 'webhookReceiver', pkg: '@ultimat3/jobs', kind: 'job' },
       { factory: 'mcpConfirmations', pkg: '@ultimat3/mcp', kind: 'action' },
       { factory: 'notifier', pkg: '@ultimat3/notify', kind: 'job' },
+      { factory: 'pushRegister', pkg: '@ultimat3/notify', kind: 'action' },
+      { factory: 'pushUnregister', pkg: '@ultimat3/notify', kind: 'action' },
       { factory: 'pushSubscribe', pkg: '@ultimat3/pwa', kind: 'action' },
       { factory: 'pushUnsubscribe', pkg: '@ultimat3/pwa', kind: 'action' },
+      // A route: the value IS a websocket mount the web role serves (`path`, `fetch`, `websocket`).
+      { factory: 'deviceSocket', pkg: '@ultimat3/realtime', kind: 'route' },
       { factory: 'scrape', pkg: '@ultimat3/scraping', kind: 'job' },
     ] satisfies readonly PrimitiveFactory[]
   ).map((entry) => Object.freeze(entry)),

package/src/render-node.ts

@@ -0,0 +1,13 @@
+// The render node brands, the one literal of each in the framework. A leaf with no import,
+// published at `@ultimat3/core/render-node` so `@ultimat3/render` stamps them and
+// `@ultimat3/core/render-nodes` reads them without either joining the barrel. Registered on the
+// GLOBAL symbol registry: two copies of a module must agree on a node.
+
+/** An element or a component call: `{ [JSX_NODE]: true, type, props }`. */
+export const JSX_NODE: unique symbol = Symbol.for('ultimate.render.jsx') as never;
+
+/** An island: a branded ARRAY whose `props.children` is the server shell. */
+export const ISLAND_NODE: unique symbol = Symbol.for('ultimate.render.island') as never;
+
+/** A stream hole: a branded ARRAY whose first flush is `props.fallback` and `props.error`. */
+export const HOLE_NODE: unique symbol = Symbol.for('ultimate.render.hole') as never;

package/src/render-nodes.ts

@@ -0,0 +1,137 @@
+// A component's node tree, walked so a test can assert on the props an element carries (the
+// `aria-live`, the `onKeyDown`, the `ref`) rather than on markup it was serialised into. Reads the
+// render factory's branded node and a hand-built `{ inert: true }` one; needs nothing from
+// `@ultimat3/render`, so it sits at tier 0 behind `@ultimat3/core/render-nodes`, off the barrel.
+
+import { assert } from './assert';
+import { HOLE_NODE, ISLAND_NODE, JSX_NODE } from './render-node';
+
+export type RenderComponent = (props: Record<string, unknown>) => unknown;
+
+export interface RenderNode {
+  /** A lowercase string is an element; a function is a component. */
+  readonly type: string | RenderComponent;
+  readonly props: Record<string, unknown>;
+}
+
+/**
+ * What a walk does at a component node. `expand` calls it and keeps only host nodes; `keep` calls
+ * it and keeps the component node too, so a test can read the props a view handed a design-system
+ * component; `stop` keeps the node, never calls it, and walks the children it was handed.
+ */
+export type ComponentMode = 'expand' | 'keep' | 'stop';
+
+export interface NodesOfOptions {
+  readonly components?: ComponentMode | undefined;
+}
+
+export function isRenderNode(value: unknown): value is RenderNode {
+  if (typeof value !== 'object' || value === null) return false;
+  return 'inert' in value || JSX_NODE in value;
+}
+
+/**
+ * Every node in the tree, depth first. Thunks are called: a component that reads a prop inside one
+ * renders nothing until something asks. A value no factory built contributes nothing.
+ */
+export function nodesOf(value: unknown, options: NodesOfOptions = {}): RenderNode[] {
+  return walk(value, options.components ?? 'expand');
+}
+
+type BrandedProps = { readonly props?: Record<string, unknown> };
+
+/**
+ * An island or a hole is an ARRAY to the type system, so each is tested before the array branch,
+ * which would walk nothing. An island's subtree is its server shell, `props.children`. A hole's
+ * first flush is `fallback` and `error`; its `children` are deferred work, never called here.
+ */
+const isIsland = (value: unknown): value is BrandedProps =>
+  typeof value === 'object' && value !== null && ISLAND_NODE in value;
+const isHole = (value: unknown): value is BrandedProps =>
+  typeof value === 'object' && value !== null && HOLE_NODE in value;
+
+function walk(value: unknown, mode: ComponentMode): RenderNode[] {
+  if (isIsland(value)) return walk(value.props?.['children'], mode);
+  if (isHole(value)) return walk([value.props?.['fallback'], value.props?.['error']], mode);
+  if (Array.isArray(value)) return value.flatMap((item) => walk(item, mode));
+  if (isRenderNode(value)) {
+    const { type, props } = value;
+    if (typeof type !== 'function' || mode === 'stop')
+      return [value, ...walk(props['children'], mode)];
+    const output = walk(type(props), mode);
+    return mode === 'keep' ? [value, ...output] : output;
+  }
+  if (typeof value === 'function') return walk((value as () => unknown)(), mode);
+  return [];
+}
+
+/** Render a component to its nodes. `props` is the component's own, untyped on purpose. */
+export function renderNodes(
+  component: unknown,
+  props: Record<string, unknown> = {},
+  options: NodesOfOptions = {},
+): RenderNode[] {
+  assert(
+    typeof component === 'function',
+    'renderNodes() was handed a value that is not a component function',
+    'renderNodes(Button, { label: "Save" }) — the component function itself, never <Button /> or its output',
+  );
+  return nodesOf((component as RenderComponent)(props), options);
+}
+
+export function byTag(nodes: readonly RenderNode[], tag: string): RenderNode[] {
+  return nodes.filter((node) => node.type === tag);
+}
+
+/** Nodes rendered by the named component, read off its function name: `byComponent(n, 'Money')`. */
+export function byComponent(nodes: readonly RenderNode[], name: string): RenderNode[] {
+  return nodes.filter((node) => typeof node.type === 'function' && node.type.name === name);
+}
+
+/** Nodes whose attribute equals `value`; `undefined` matches "carries the attribute at all". */
+export function withAttr(
+  nodes: readonly RenderNode[],
+  name: string,
+  value?: unknown,
+): RenderNode[] {
+  return nodes.filter((node) =>
+    value === undefined ? node.props[name] !== undefined : node.props[name] === value,
+  );
+}
+
+/** The one node a test means, or `X_INVARIANT` naming what it sought — never a silent `undefined`. */
+export function one(nodes: readonly RenderNode[], what: string): RenderNode {
+  const node = nodes[0];
+  assert(
+    node !== undefined && nodes.length === 1,
+    `expected exactly one ${what}, found ${nodes.length}`,
+    'one(withAttr(byTag(nodes, "button"), "aria-label", "Save"), "the save button") — narrow until one node matches',
+  );
+  return node;
+}
+
+/** `<button>` for an element, `<Money>` for a component: never a function's source text. */
+const label = (node: RenderNode): string =>
+  `<${typeof node.type === 'function' ? node.type.name : node.type}>`;
+
+/** Call an element's `ref` prop with the element a test built for it. */
+export function attachRef(node: RenderNode, element: unknown): void {
+  const ref = node.props['ref'];
+  assert(
+    typeof ref === 'function',
+    `node ${label(node)} carries no ref`,
+    'attachRef(one(withAttr(nodes, "ref"), "the node holding a ref"), element) — pick the node that declares ref={…}',
+  );
+  (ref as (el: unknown) => void)(element);
+}
+
+/** Call an element's event handler prop, e.g. `fire(menu, 'onKeyDown', keydown('ArrowDown'))`. */
+export function fire(node: RenderNode, handler: string, event: unknown): void {
+  const fn = node.props[handler];
+  assert(
+    typeof fn === 'function',
+    `node ${label(node)} carries no ${handler}`,
+    `fire(one(withAttr(nodes, "${handler}"), "the node holding ${handler}"), "${handler}", event) — pick the node that declares it`,
+  );
+  (fn as (e: unknown) => void)(event);
+}

package/src/retry-loop.ts

@@ -0,0 +1,197 @@
+// Single responsibility: the retry loop itself and the pure decision behind it, with every source of
+// non-determinism and the caller's lifetime handed in. Split from `retry.ts` so `client-flight.ts`
+// reaches the loop without `context.ts`: a page's bundle must not pay for the ambient request.
+
+import {
+  type BackoffCurve,
+  backoffDelay,
+  type JitterMode,
+  jitterStatedDelay,
+  type Random,
+} from './backoff';
+import { systemClock } from './clock';
+import { classifyThrown, type ErrorRetry, statedDelayMs } from './error-retry';
+import { finiteCount, finiteOption } from './finite-option';
+
+export interface RetryPolicy {
+  /** Total attempts INCLUDING the first. `attempts: 1` means no retry. */
+  readonly attempts: number;
+  /** The first delay, in ms. */
+  readonly base: number;
+  /**
+   * Ceiling for any single delay, in ms. A `retry-after` the responder named is clamped to it
+   * too, and then gets its spread on top — at most half again, so a burst told one delay does
+   * not wake together (`jitterStatedDelay`).
+   */
+  readonly max: number;
+  /**
+   * Required, unlike `backoffDelay`'s, and that is the point: a retry loop with no jitter is the
+   * thundering herd itself, so the mode is a decision each caller makes rather than one it can
+   * inherit without noticing.
+   */
+  readonly jitter: JitterMode;
+  readonly curve?: BackoffCurve | undefined;
+  readonly factor?: number | undefined;
+  /**
+   * Wall-clock budget for the WHOLE loop, waits included. A wait that would end past it is never
+   * started — the caller's own deadline outranks the attempts it was allowed.
+   */
+  readonly timeBudgetMs?: number | undefined;
+}
+
+/** Why the loop stopped. Absent while it is still retrying. */
+export type RetryStopReason = 'terminal' | 'attempts-exhausted' | 'budget-exhausted';
+
+export interface RetryDecision {
+  readonly retry: boolean;
+  readonly delayMs: number;
+  readonly attempt: number;
+  readonly nextAttempt: number;
+  /** The classification consulted, or `undefined` when nobody classified the thrown code. */
+  readonly classification: ErrorRetry | undefined;
+  readonly stoppedBy: RetryStopReason | undefined;
+}
+
+/**
+ * Retry, stop, and when — pure, so a caller can print the schedule and a test can pin it without a
+ * loop. `terminal` stops on the attempt that failed: the same code run again is the same answer,
+ * and the attempts left are a queue slot, a provider bill, or three more wrong passwords at a site
+ * that locks the account after three. Everything else keeps the attempt count in charge, and
+ * `retry-after` replaces only the DELAY, never the ceiling.
+ */
+export function retryDecision(
+  policy: RetryPolicy,
+  attempt: number,
+  error: unknown,
+  random?: Random,
+): RetryDecision {
+  // Screened HERE and not only in `retry()`: this function is exported so a caller can write its
+  // own loop, and `attempt >= NaN` is false for every attempt — the loop that asks it never ends.
+  const attempts = finiteCount('a retry policy', 'attempts', policy.attempts);
+  const classification = classifyThrown(error);
+  const stop = (stoppedBy: RetryStopReason): RetryDecision => ({
+    retry: false,
+    delayMs: 0,
+    attempt,
+    nextAttempt: attempt,
+    classification,
+    stoppedBy,
+  });
+
+  if (classification === 'terminal') return stop('terminal');
+  if (attempt >= attempts) return stop('attempts-exhausted');
+
+  const computed = backoffDelay({
+    attempt,
+    base: policy.base,
+    max: policy.max,
+    factor: policy.factor,
+    curve: policy.curve,
+    jitter: policy.jitter,
+    random,
+  });
+  const stated = classification === 'retry-after' ? statedDelayMs(error) : undefined;
+  return {
+    retry: true,
+    // The stated delay is a FLOOR plus a spread (`jitterStatedDelay`), never the bare number: a
+    // shedding server tells a whole burst `Retry-After: 1`, and waiting exactly that replays the
+    // burst in lockstep every second. The floor is clamped by the policy's own ceiling, which is
+    // what `max` is for — a responder naming a day is still a responder this deployment has not
+    // agreed to wait a day for — and the spread on top is at most half of it.
+    // `jitter: 'none'` is honoured here too — the caller's one decision, for a test or a printable
+    // schedule — and only that mode gets the bare floor.
+    delayMs:
+      stated === undefined
+        ? computed
+        : policy.jitter === 'none'
+          ? Math.min(stated, policy.max)
+          : jitterStatedDelay(Math.min(stated, policy.max), policy.max, random),
+    attempt,
+    nextAttempt: attempt + 1,
+    classification,
+    stoppedBy: undefined,
+  };
+}
+
+export interface RetryLoopDeps {
+  /** Handed the signal too, so a timer can let itself go on the abort that ended its wait. */
+  sleep(ms: number, signal: AbortSignal | undefined): Promise<void>;
+  /** Monotonic ms, read only when `timeBudgetMs` is set. Defaults to the system clock. */
+  now?: (() => number) | undefined;
+  random?: Random | undefined;
+  /** The caller's lifetime. Nothing is tried, and nothing is waited for, once it has aborted. */
+  signal?: AbortSignal | undefined;
+}
+
+/** The wait, ended at once by an abort whatever `sleep` was injected. A rejected sleep propagates. */
+function waitOut(deps: RetryLoopDeps, ms: number): Promise<void> {
+  const { signal } = deps;
+  if (signal === undefined) return deps.sleep(ms, undefined);
+  if (signal.aborted) return Promise.resolve();
+  return new Promise<void>((resolve, reject) => {
+    const aborted = (): void => {
+      resolve();
+    };
+    signal.addEventListener('abort', aborted, { once: true });
+    deps.sleep(ms, signal).then(
+      () => {
+        signal.removeEventListener('abort', aborted);
+        resolve();
+      },
+      (error: unknown) => {
+        signal.removeEventListener('abort', aborted);
+        reject(error);
+      },
+    );
+  });
+}
+
+/**
+ * Run `work` until it succeeds, the policy runs out, the classification says stop, the time budget
+ * does, or the signal aborts. `work` is handed the 1-based attempt number.
+ *
+ * The LAST error reaches the caller unchanged — never wrapped. An `UltimateError` carries a code, a
+ * cause and a runnable `fix:`, and a wrapper would replace all three with the fact that something
+ * was retried, which no reader can act on. An abort before any attempt has no such error, so it
+ * answers the signal's own reason.
+ */
+export async function retryLoop<T>(
+  work: (attempt: number) => Promise<T>,
+  policy: RetryPolicy,
+  deps: RetryLoopDeps,
+): Promise<T> {
+  // Both bounds are refused BEFORE the first try: a policy that cannot stop the loop is a defect in
+  // the call, and running the work once first would report it as the work's own failure.
+  // `finiteOption` for the budget, not `finiteCount`: it is a duration a caller computes from a
+  // monotonic clock, so a fraction is real and a spent (negative) one means "do not wait at all".
+  // Zero stays legal and means what it always did — one try, no retry (`retry.test.ts` pins it).
+  finiteCount('a retry policy', 'attempts', policy.attempts);
+  const budget =
+    policy.timeBudgetMs === undefined
+      ? undefined
+      : finiteOption('a retry policy', 'timeBudgetMs', policy.timeBudgetMs);
+  const now = deps.now ?? ((): number => systemClock.monotonic());
+  // Read once even when no budget is set: a clock call per attempt would be a cost the common case
+  // does not owe. `startedAt` is only compared against when `timeBudgetMs` is present.
+  const startedAt = now();
+  let failed: { readonly error: unknown } | undefined;
+
+  for (let attempt = 1; ; attempt += 1) {
+    // The classification cannot say this: `X_ABORTED` is unclassified by design, or a job body's
+    // would dead-letter on attempt 1, so a loop that asks only it goes on sending for a dead caller.
+    if (deps.signal?.aborted === true) {
+      throw failed === undefined ? deps.signal.reason : failed.error;
+    }
+    try {
+      return await work(attempt);
+    } catch (error) {
+      const decision = retryDecision(policy, attempt, error, deps.random);
+      if (!decision.retry) throw error;
+      // Decided BEFORE the wait, never after: a loop that sleeps and then discovers it is out of
+      // budget has already spent the caller's deadline on a wait nobody could use.
+      if (budget !== undefined && now() - startedAt + decision.delayMs > budget) throw error;
+      failed = { error };
+      await waitOut(deps, decision.delayMs);
+    }
+  }
+}