@relayflows/sdk 2.0.42 → 2.0.43

package/src/journal-client.ts

@@ -7,26 +7,36 @@
 // AGENTS.md rule 4). The kernel binary (`kernel/relayflowd serve`) speaks
 // this transport, including out-of-band leases, watches, events, and durable
 // stream plumbing. The client's framing and failure behavior is covered by a
-// loopback double in tests.
-
-import { EventEmitter } from 'node:events';
+// loopback double in tests. Framing and the socket lifecycle live in
+// journal-connection.ts; budgeted reads in journal-budgeted-reads.ts.
+
+import { READ_ONLY_VERBS } from './journal-read-policy.js';
+import { JournalConnection, JournalProtocolError } from './journal-connection.js';
+export { JournalFrameError, JournalProtocolError } from './journal-connection.js';
+import { BudgetedReads } from './journal-budgeted-reads.js';
+export { JournalReadInterruptedError, JournalRequestTimeoutError } from './journal-read-policy.js';
 export { walkJournal, JournalReadError, type JournalEvent, type JournalReadFailure } from './journal-reader.js';
-import { randomUUID } from 'node:crypto';
-import { createConnection, type Socket } from 'node:net';
 import type { VerbContract, EventEmitParams, EventSubmitParams, ReportedCost } from './protocol.js';
 import {
   PROTOCOL_VERSION,
   type CompletionReason,
   type EffectRef,
   type Pins,
-  type Request,
-  type Response,
-  type ServerEvent,
   type StepUsage,
 } from './protocol.js';
 import type { KernelRunSpec, StepType } from './spec.js';
 
 export interface JournalClientOptions {
+  /** Opt-in total budget for read-only requests; interactive clients stay single-shot. */
+  readBudgetMs?: number;
+  /** Cancels every budgeted read, so a run's lifecycle abort never waits out the budget. */
+  readSignal?: AbortSignal;
+  /**
+   * Retry this session's own `hello` within the read budget. Only for sessions
+   * opened after a run is admitted (an authored child, its verifier); a
+   * top-level command's handshake stays a single-shot compatibility check.
+   */
+  budgetHandshake?: boolean;
   /** Override the timeout for bounded protocol requests (ms). Default 30000. */
   requestTimeoutMs?: number;
   /**
@@ -42,42 +52,21 @@ export interface JournalClientOptions {
   connectTimeoutMs?: number;
 }
 
-interface Pending {
-  resolve: (value: unknown) => void;
-  reject: (err: Error) => void;
-  timer?: ReturnType<typeof setTimeout>;
-}
-
-/** A structured rejection returned by relayflowd over the journal protocol. */
-export class JournalProtocolError extends Error {
-  readonly code: string;
-  verb?: string;
+export class JournalClient extends JournalConnection {
+  private readonly budgeted: BudgetedReads | undefined;
+  private readonly budgetHandshake: boolean;
+  /** Additive request capabilities the daemon advertised at `hello`; none until then. */
+  private features: ReadonlySet<string> = new Set();
 
-  constructor(code: string, message: string) {
-    super(`${code}: ${message}`);
-    this.name = 'JournalProtocolError';
-    this.code = code;
+  constructor(socketPath: string, options: JournalClientOptions = {}) {
+    super(socketPath, options.requestTimeoutMs ?? 30_000, options.connectTimeoutMs ?? 2_000);
+    this.budgetHandshake = options.budgetHandshake === true;
+    this.budgeted = options.readBudgetMs === undefined ? undefined
+      : new BudgetedReads(this, options.readBudgetMs, options.readSignal);
   }
-}
 
-export class JournalClient extends EventEmitter {
-  /** Additive request capabilities the daemon advertised at `hello`; none until then. */
-  private features: ReadonlySet<string> = new Set();
-  private socket: Socket | null = null;
-  /** Why the connection ended, so a later "not connected" names its cause rather than hiding it. */
-  private disconnectCause: Error | undefined;
-  private buffer = '';
-  private readonly pending = new Map<string, Pending>();
-  private readonly requestTimeoutMs: number;
-  private readonly connectTimeoutMs: number;
-
-  constructor(
-    readonly socketPath: string,
-    options: JournalClientOptions = {},
-  ) {
-    super();
-    this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
-    this.connectTimeoutMs = options.connectTimeoutMs ?? 2_000;
+  protected override connectionClosed(cause: unknown, unexpected: boolean): void {
+    this.budgeted?.close(cause, unexpected);
   }
 
   /** Independent session for an SDK helper worker; preserves the caller's registration. */
@@ -87,139 +76,41 @@ export class JournalClient extends EventEmitter {
     });
   }
 
-  /** Open the unix socket connection. Rejects on connect failure (fail-closed). */
-  connect(): Promise<void> {
-    return new Promise((resolve, reject) => {
-      if (this.socket) return resolve();
-      const socket = createConnection({ path: this.socketPath });
-      const timer = setTimeout(() => {
-        socket.removeAllListeners();
-        socket.destroy();
-        this.failAll(new Error(`journal client: connect timed out after ${this.connectTimeoutMs}ms`));
-        reject(new Error(`journal client: connect timed out after ${this.connectTimeoutMs}ms`));
-      }, this.connectTimeoutMs);
-      const onError = (err: Error): void => {
-        clearTimeout(timer);
-        socket.removeAllListeners();
-        this.failAll(err);
-        reject(new Error(`journal client: connect failed: ${err.message}`));
-      };
-      socket.once('error', onError);
-      socket.once('connect', () => {
-        clearTimeout(timer);
-        socket.removeListener('error', onError);
-        socket.on('error', (err) => { this.disconnectCause ??= err; this.failAll(err); });
-        socket.on('data', (chunk) => this.onData(chunk));
-        socket.on('close', () => {
-          const closed = new Error('journal client: connection closed');
-          this.disconnectCause ??= closed;
-          this.failAll(closed);
-        });
-        this.disconnectCause = undefined;
-        this.socket = socket;
-        resolve();
-      });
-    });
+  private request<V extends keyof VerbContract>(verb: V, params: VerbContract[V]['params'],
+    timeoutMs: number | null = this.requestTimeoutMs, signal?: AbortSignal): Promise<VerbContract[V]['result']> {
+    // Every allowlisted read takes the policy, even after the primary dropped: its
+    // closed state then answers with the typed interruption recorded at the drop.
+    if (this.budgeted !== undefined && timeoutMs !== null && READ_ONLY_VERBS.has(verb)) {
+      return this.budgeted.read(verb, params, timeoutMs, signal);
+    }
+    return this.requestOnce(verb, params, timeoutMs, signal);
   }
 
   /**
-   * Close the connection and reject any pending requests. A `cause` (for
-   * example the worker failure that forced the close) is carried into every
-   * later "not connected" rejection.
+   * Cancel budgeted reads also when `signal` aborts — a root attempt's lease —
+   * until the returned release is called. A no-op without a read budget.
    */
-  close(cause?: unknown): void {
-    const closed = cause === undefined
-      ? new Error('journal client: closed by caller')
-      : new Error(`journal client: closed after ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
-    this.disconnectCause ??= closed;
-    this.failAll(closed);
-    this.socket?.destroy();
-    this.socket = null;
-    this.buffer = '';
-  }
-
-  private onData(chunk: Buffer): void {
-    this.buffer += chunk.toString('utf8');
-    let nl: number;
-    while ((nl = this.buffer.indexOf('\n')) !== -1) {
-      const line = this.buffer.slice(0, nl);
-      this.buffer = this.buffer.slice(nl + 1);
-      if (line.length > 0) this.onLine(line);
-    }
+  scopeReads(signal: AbortSignal): () => void {
+    return this.budgeted?.scope(signal) ?? (() => {});
   }
 
-  private onLine(line: string): void {
-    let msg: Response | ServerEvent;
-    try {
-      msg = JSON.parse(line) as Response | ServerEvent;
-    } catch {
-      // A malformed frame is a protocol violation; fail closed.
-      this.failAll(new Error('journal client: malformed frame from server'));
-      return;
-    }
-
-    if (typeof (msg as Response).id === 'string' && 'ok' in (msg as Response)) {
-      const res = msg as Response;
-      const pending = this.pending.get(res.id);
-      if (!pending) return; // reply for an already-timed-out request
-      this.pending.delete(res.id);
-      if (pending.timer !== undefined) clearTimeout(pending.timer);
-      if (res.ok) pending.resolve(res.result);
-      else pending.reject(new JournalProtocolError(res.error.code, res.error.message));
-    } else {
-      const ev = msg as ServerEvent;
-      this.emit(ev.event, ev.data);
-      this.emit('event', ev);
-    }
-  }
-
-  private failAll(err: Error): void {
-    for (const [, p] of this.pending) {
-      if (p.timer !== undefined) clearTimeout(p.timer);
-      p.reject(err);
-    }
-    this.pending.clear();
-  }
-
-  private request<V extends keyof VerbContract>(
-    verb: V,
-    params: VerbContract[V]['params'],
-    timeoutMs: number | null = this.requestTimeoutMs,
-  ): Promise<VerbContract[V]['result']> {
-    return new Promise((resolve, reject) => {
-      if (!this.socket || this.socket.destroyed) {
-        const cause = this.disconnectCause;
-        reject(new Error(
-          `journal client: not connected (${verb})${cause === undefined ? '' : `: ${cause.message}`}`,
-          cause === undefined ? undefined : { cause },
-        ));
-        return;
-      }
-      const id = randomUUID();
-      const frame: Request = { id, verb: verb as string, params };
-      const timer = timeoutMs === null ? undefined : setTimeout(() => {
-        this.pending.delete(id);
-        reject(new Error(`journal client: ${verb} timed out after ${timeoutMs}ms`));
-      }, timeoutMs);
-      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
-      this.socket.write(JSON.stringify(frame) + '\n', (err) => {
-        if (err) {
-          const p = this.pending.get(id);
-          if (p) {
-            if (p.timer !== undefined) clearTimeout(p.timer);
-            this.pending.delete(id);
-            p.reject(new Error(`journal client: ${verb} write failed: ${err.message}`));
-          }
-        }
-      });
-    });
+  /**
+   * End every budgeted read now and refuse later ones; the session itself stays
+   * open. The reads end as read interruptions, so a worker hands its attempt
+   * back to the kernel rather than completing it as a failure.
+   */
+  cancelReads(): void {
+    this.budgeted?.close(new Error('journal client: reads canceled'), true);
   }
 
   // --- Typed verb methods (gate 1 minimal set, kernel DESIGN.md §5) --------
 
   /** Handshake; version mismatch is a hard error. Records the daemon's additive features. */
   async hello(client: string): Promise<VerbContract['hello']['result']> {
-    const result = await this.request('hello', { protocol: PROTOCOL_VERSION, client });
+    const params = { protocol: PROTOCOL_VERSION, client };
+    // A flow client's handshake meets the same CPU load as its reads.
+    const result = this.budgeted === undefined || !this.budgetHandshake ? await this.request('hello', params)
+      : await this.budgeted.handshake(params, this.requestTimeoutMs);
     this.features = new Set(Array.isArray(result.features) ? result.features.filter(f => typeof f === 'string') : []);
     return result;
   }
@@ -255,13 +146,15 @@ export class JournalClient extends EventEmitter {
   }
 
   /** Snapshot for legibility. */
-  runGet(runId: string): Promise<VerbContract['run.get']['result']> {
-    return this.request('run.get', { run_id: runId });
+  runGet(runId: string, options: { signal?: AbortSignal } = {}): Promise<VerbContract['run.get']['result']> {
+    return this.request('run.get', { run_id: runId }, this.requestTimeoutMs, options.signal);
   }
 
   /**
-   * Open a push stream of every appended entry. Resolves once subscribed;
-   * entries arrive as `'entry'` events: `client.on('entry', (entry) => …)`.
+   * Open a push stream of every appended entry. The daemon writes the run's
+   * existing entries before this resolves (server.rs `watch_with_replay`), so
+   * the replay is fully delivered first; later entries arrive as they are
+   * appended. Entries arrive as `'entry'` events: `client.on('entry', (entry) => …)`.
    */
   runWatch(runId: string): Promise<VerbContract['run.watch']['result']> {
     return this.request('run.watch', { run_id: runId });

package/src/journal-connection.ts

@@ -0,0 +1,222 @@
+// Journal-protocol v0 client (kernel DESIGN.md §5).
+//
+// A real client implementation of the wire protocol — newline-delimited JSON
+// over a unix socket. It correlates requests by `id`, demultiplexes
+// server-pushed events, and is fail-closed: a connection drop or write error
+// rejects every pending request (a journal write that fails fails the step;
+// AGENTS.md rule 4). The kernel binary (`kernel/relayflowd serve`) speaks
+// this transport, including out-of-band leases, watches, events, and durable
+// stream plumbing. The client's framing and failure behavior is covered by a
+// loopback double in tests.
+
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { createConnection, type Socket } from 'node:net';
+import { JournalRequestTimeoutError } from './journal-read-policy.js';
+import type { Request, Response, ServerEvent, VerbContract } from './protocol.js';
+
+interface Pending {
+  resolve: (value: unknown) => void;
+  reject: (err: Error) => void;
+  timer?: ReturnType<typeof setTimeout>;
+}
+
+/** A structured rejection returned by relayflowd over the journal protocol. */
+export class JournalProtocolError extends Error {
+  readonly code: string;
+  verb?: string;
+
+  constructor(code: string, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'JournalProtocolError';
+    this.code = code;
+  }
+}
+
+/** The daemon sent a frame this client cannot parse: a protocol violation, never retried. */
+export class JournalFrameError extends Error {
+  constructor(message = 'journal client: malformed frame from server') {
+    super(message);
+    this.name = 'JournalFrameError';
+  }
+}
+
+/** Framing, socket lifecycle and request correlation; the typed verbs live on JournalClient. */
+export class JournalConnection extends EventEmitter {
+  protected socket: Socket | null = null;
+  private connectingSocket: Socket | undefined;
+  /** Why the connection ended, so a later "not connected" names its cause rather than hiding it. */
+  protected disconnectCause: Error | undefined;
+  private buffer = '';
+  private readonly pending = new Map<string, Pending>();
+
+  constructor(
+    readonly socketPath: string,
+    protected readonly requestTimeoutMs: number,
+    protected readonly connectTimeoutMs: number,
+  ) {
+    super();
+  }
+
+  /** Hook for sessions layered on this one: `unexpected` is a drop the caller did not ask for. */
+  protected connectionClosed(_cause: unknown, _unexpected: boolean): void {}
+
+  /** Open the unix socket connection. Rejects on connect failure (fail-closed). */
+  connect(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.socket) return resolve();
+      const socket = createConnection({ path: this.socketPath });
+      this.connectingSocket = socket;
+      const timer = setTimeout(() => {
+        socket.removeAllListeners();
+        socket.destroy();
+        this.failAll(new Error(`journal client: connect timed out after ${this.connectTimeoutMs}ms`));
+        reject(new Error(`journal client: connect timed out after ${this.connectTimeoutMs}ms`));
+      }, this.connectTimeoutMs);
+      const onError = (err: Error): void => {
+        clearTimeout(timer);
+        socket.removeAllListeners();
+        this.failAll(err);
+        reject(new Error(`journal client: connect failed: ${err.message}`));
+      };
+      socket.once('error', onError);
+      socket.once('connect', () => {
+        clearTimeout(timer);
+        socket.removeListener('error', onError);
+        socket.on('error', (err) => { this.disconnectCause ??= err; this.failAll(err); });
+        socket.on('data', (chunk) => this.onData(chunk));
+        socket.on('close', () => {
+          const closed = new Error('journal client: connection closed');
+          this.connectionClosed(closed, this.socket === socket);
+          this.disconnectCause ??= closed;
+          this.failAll(closed);
+          // Only a drop the caller did not ask for; close() clears this.socket first.
+          // Sessions with nothing pending (a registered watch) must hear it too.
+          if (this.socket === socket) this.emit('disconnected', closed);
+        });
+        this.disconnectCause = undefined;
+        this.connectingSocket = undefined;
+        this.socket = socket;
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * Close the connection and reject any pending requests. A `cause` (for
+   * example the worker failure that forced the close) is carried into every
+   * later "not connected" rejection.
+   */
+  close(cause?: unknown): void {
+    const closed = cause === undefined
+      ? new Error('journal client: closed by caller')
+      : new Error(`journal client: closed after ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    this.connectionClosed(cause, false);
+    this.connectingSocket?.destroy(closed);
+    this.disconnectCause ??= closed;
+    this.failAll(closed);
+    this.socket?.destroy();
+    this.socket = null;
+    this.buffer = '';
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffer += chunk.toString('utf8');
+    let nl: number;
+    while ((nl = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, nl);
+      this.buffer = this.buffer.slice(nl + 1);
+      if (line.length > 0) this.onLine(line);
+    }
+  }
+
+  private onLine(line: string): void {
+    let msg: Response | ServerEvent;
+    try {
+      msg = JSON.parse(line) as Response | ServerEvent;
+    } catch {
+      // A malformed frame is a protocol violation; fail closed.
+      const error = new JournalFrameError();
+      this.failAll(error);
+      // Sessions with nothing pending (a registered watch) must hear it too.
+      this.emit('protocol_error', error);
+      return;
+    }
+
+    if (typeof (msg as Response).id === 'string' && 'ok' in (msg as Response)) {
+      const res = msg as Response;
+      const pending = this.pending.get(res.id);
+      if (!pending) return; // reply for an already-timed-out request
+      this.pending.delete(res.id);
+      if (pending.timer !== undefined) clearTimeout(pending.timer);
+      if (res.ok) pending.resolve(res.result);
+      else pending.reject(new JournalProtocolError(res.error.code, res.error.message));
+    } else {
+      const ev = msg as ServerEvent;
+      this.emit(ev.event, ev.data);
+      this.emit('event', ev);
+    }
+  }
+
+  private failAll(err: Error): void {
+    for (const [, p] of this.pending) {
+      if (p.timer !== undefined) clearTimeout(p.timer);
+      p.reject(err);
+    }
+    this.pending.clear();
+  }
+
+  /** @internal One unretried request on this session; flow reads go through `request`. */
+  requestOnce<V extends keyof VerbContract>(
+    verb: V,
+    params: VerbContract[V]['params'],
+    timeoutMs: number | null = this.requestTimeoutMs,
+    signal?: AbortSignal,
+  ): Promise<VerbContract[V]['result']> {
+    return new Promise((resolve, reject) => {
+      if (signal?.aborted) {
+        reject(signal.reason);
+        return;
+      }
+      if (!this.socket || this.socket.destroyed) {
+        const cause = this.disconnectCause;
+        reject(new Error(
+          `journal client: not connected (${verb})${cause === undefined ? '' : `: ${cause.message}`}`,
+          cause === undefined ? undefined : { cause },
+        ));
+        return;
+      }
+      const id = randomUUID();
+      const started = performance.now();
+      const frame: Request = { id, verb: verb as string, params };
+      // Cancellation forgets the request; a late reply is ignored like a timed-out one.
+      const onAbort = () => {
+        const p = this.pending.get(id);
+        if (p === undefined) return;
+        if (p.timer !== undefined) clearTimeout(p.timer);
+        this.pending.delete(id);
+        p.reject(signal!.reason);
+      };
+      const settle = <A>(fn: (arg: A) => void) => (arg: A) => {
+        signal?.removeEventListener('abort', onAbort);
+        fn(arg);
+      };
+      const timer = timeoutMs === null ? undefined : setTimeout(() => {
+        this.pending.delete(id);
+        settle(reject)(new JournalRequestTimeoutError(verb, timeoutMs, 1, performance.now() - started));
+      }, timeoutMs);
+      this.pending.set(id, { resolve: settle(resolve as (v: unknown) => void), reject: settle(reject), timer });
+      signal?.addEventListener('abort', onAbort, { once: true });
+      this.socket.write(JSON.stringify(frame) + '\n', (err) => {
+        if (err) {
+          const p = this.pending.get(id);
+          if (p) {
+            if (p.timer !== undefined) clearTimeout(p.timer);
+            this.pending.delete(id);
+            p.reject(new Error(`journal client: ${verb} write failed: ${err.message}`));
+          }
+        }
+      });
+    });
+  }
+}

package/src/journal-read-policy.ts

@@ -0,0 +1,123 @@
+import { setMaxListeners } from 'node:events';
+import { setTimeout as sleep } from 'node:timers/promises';
+
+export const READ_ONLY_VERBS = new Set(['run.get', 'journal.read', 'stream.read', 'subscription.inspect']);
+export const FLOW_READ_BUDGET_MS = 300_000;
+
+export class JournalRequestTimeoutError extends Error {
+  constructor(
+    readonly verb: string,
+    readonly timeoutMs: number,
+    readonly attempts = 1,
+    readonly elapsedMs = timeoutMs,
+    readonly readBudgetMs?: number,
+  ) {
+    super(readBudgetMs === undefined
+      ? `journal client: ${verb} timed out after ${timeoutMs}ms`
+      : `journal client: ${verb} timed out after ${attempts} attempts in ${Math.round(elapsedMs)}ms (read budget ${readBudgetMs}ms); relayflowd may be delayed by CPU load`);
+    this.name = 'JournalRequestTimeoutError';
+  }
+}
+
+/**
+ * The dedicated read session lost its transport (closed, reset, not connected)
+ * while the primary session may still be healthy. Like a timeout, this says
+ * nothing about the run itself: retry within the budget, then leave the run
+ * resumable. Protocol refusals and write failures are never this error.
+ */
+export class JournalReadInterruptedError extends Error {
+  constructor(
+    readonly verb: string,
+    readonly attempts = 1,
+    readonly elapsedMs = 0,
+    readonly readBudgetMs?: number,
+    options?: ErrorOptions & { retryable?: boolean },
+  ) {
+    const cause = options?.cause instanceof Error ? `: ${options.cause.message}` : '';
+    super(readBudgetMs === undefined
+      ? `journal client: ${verb} read session was interrupted${cause}`
+      : `journal client: ${verb} read session was interrupted after ${attempts} attempts in ${Math.round(elapsedMs)}ms (read budget ${readBudgetMs}ms)${cause}`,
+    options);
+    this.name = 'JournalReadInterruptedError';
+    this.retryable = options?.retryable !== false;
+  }
+
+  /** False when the session it ran on is gone, so retrying it cannot help. */
+  readonly retryable: boolean;
+}
+
+/** A read that could not be answered — by timeout or lost read transport — not a run failure. */
+export function isReadInterruptionError(error: unknown): error is JournalRequestTimeoutError | JournalReadInterruptedError {
+  return (error instanceof JournalRequestTimeoutError
+    && (READ_ONLY_VERBS.has(error.verb) || error.verb === 'run.watch' || error.verb === 'hello'))
+    || error instanceof JournalReadInterruptedError;
+}
+
+/** Serial admission bounds read amplification, including retries, per body client. */
+export class JournalReadPolicy {
+  private tail: Promise<unknown> = Promise.resolve();
+  private readonly closed = new AbortController();
+
+  constructor() {
+    // Concurrent children share this cancellation signal; each waiter removes its listener.
+    setMaxListeners(0, this.closed.signal);
+  }
+
+  close(reason: unknown = new Error('journal client: closed by caller')): void { this.closed.abort(reason); }
+
+  async read<T>(verb: string, timeoutMs: number, budgetMs: number,
+    request: (timeoutMs: number, signal: AbortSignal) => Promise<T>, caller?: AbortSignal): Promise<T> {
+    const started = performance.now();
+    const deadline = started + budgetMs;
+    let attempts = 0;
+    let last: unknown;
+    const exhausted = () => last instanceof JournalReadInterruptedError
+      ? new JournalReadInterruptedError(verb, attempts, performance.now() - started, budgetMs, { cause: last.cause })
+      : new JournalRequestTimeoutError(verb, timeoutMs, attempts, performance.now() - started, budgetMs);
+    // A caller's cancellation settles this read and drains its queued attempt.
+    const signal = caller === undefined ? this.closed.signal : AbortSignal.any([this.closed.signal, caller]);
+    // Budget exhaustion also aborts the queued work, so a stalled setup or
+    // request does not hold the serialized queue after its caller gave up.
+    const budget = new AbortController();
+    const attemptSignal = AbortSignal.any([signal, budget.signal]);
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let onClose: () => void = () => {};
+    let deliver: (value: T) => void = () => {};
+    let fail: (error: unknown) => void = () => {};
+    const response = new Promise<T>((resolve, reject) => {
+      deliver = resolve;
+      fail = reject;
+      timer = setTimeout(() => { const error = exhausted(); budget.abort(error); reject(error); }, budgetMs);
+      onClose = () => reject(signal.reason);
+      signal.addEventListener('abort', onClose, { once: true });
+      if (signal.aborted) onClose();
+    });
+    const job = this.tail.then(async () => {
+      while (true) {
+        attemptSignal.throwIfAborted();
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) throw exhausted();
+        attempts += 1;
+        try {
+          return await request(Math.min(remaining, timeoutMs * 2 ** Math.max(0, attempts - 2)), attemptSignal);
+        } catch (error) {
+          attemptSignal.throwIfAborted();
+          if (!(error instanceof JournalRequestTimeoutError
+            || (error instanceof JournalReadInterruptedError && error.retryable))) throw error;
+          last = error;
+          const left = deadline - performance.now();
+          if (left <= 0) throw exhausted();
+          // Jitter plus escalating bounds keep a slow daemon from collecting a retry storm.
+          await sleep(Math.min(left, Math.min(1000, timeoutMs / 4) * (0.5 + Math.random())), undefined, { signal: attemptSignal });
+        }
+      }
+    });
+    this.tail = job.catch(() => {});
+    void job.then(deliver, fail);
+    try { return await response; }
+    finally {
+      clearTimeout(timer);
+      signal.removeEventListener('abort', onClose);
+    }
+  }
+}

package/src/named-gate-lowering.ts

@@ -1,17 +1,13 @@
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { deflateRawSync } from 'node:zlib';
+import { RE2JS_DEFLATED_BASE64 } from './re2js-embedded.js';
 import { bindingDependencies } from './input-binding.js';
 import { isNamedGate, regexFlags } from './named-gates.js';
 import type { NamedDataGate, StepSpec, VerificationSpec } from './spec.js';
 
 const quote = (text: string): string => `'${text.replaceAll("'", "'\\''")}'`;
-let re2Source: string | undefined;
 
 /** Embed the pinned engine in the command: execution does not resolve npm or SDK paths. */
 function embeddedRE2(): string {
-  re2Source ??= deflateRawSync(readFileSync(createRequire(import.meta.url).resolve('re2js'))).toString('base64');
-  return `const re2={};new Function('exports',require('node:zlib').inflateRawSync(Buffer.from(${JSON.stringify(re2Source)},'base64')).toString())(re2);`;
+  return `const re2={};new Function('exports',require('node:zlib').inflateRawSync(Buffer.from(${JSON.stringify(RE2JS_DEFLATED_BASE64)},'base64')).toString())(re2);`;
 }
 
 /**