@ultimat3/core 24.0.0 → 25.0.0

package/src/audit.ts

@@ -0,0 +1,144 @@
+/**
+ * The audit seam every primitive shares: the record an audited attempt produces, the sink it goes
+ * to, and the one installed-sink slot. Here at tier 0 so `@ultimat3/action` and `@ultimat3/query`
+ * — siblings that cannot import each other — write one contract into one sink. What the ROW says
+ * (retention, hash chain, subject index, "who" under impersonation) is the app's; none of it is here.
+ */
+
+import type { Ctx } from './context';
+
+/**
+ * The three things that can happen to an attempt. Deliberately the same three words
+ * `@ultimat3/admin`'s `AuditEntry` uses — that package is tier 5, so the vocabulary is shared by
+ * name and not by import. `denied` is an authz refusal, `failed` is everything else that threw,
+ * including an input that never parsed.
+ */
+export type AuditOutcome = 'allowed' | 'denied' | 'failed';
+
+/** Which primitive acted — the value of the `ultimate.primitive` span attribute, too. */
+export type AuditPrimitive = 'action' | 'query';
+
+/**
+ * Which projection ran the attempt: a price change over `http` and one over `mcp` are not the same
+ * event. The union of the action surfaces (`server`, `http`, `mcp`, `job`) and the read surfaces
+ * (`server`, `http`, `mcp`, `live`) — one sink receives both.
+ */
+export type AuditSurface = 'server' | 'http' | 'mcp' | 'job' | 'live';
+
+/** Why a non-`allowed` attempt ended. The framework classifies; it never renders. */
+export interface AuditFailure {
+  /** The `X_*` code when an `UltimateError` ended it; `null` for anything else that threw. */
+  readonly code: string | null;
+  /** The thrown value, verbatim — its stack is the thing worth reading. */
+  readonly error: unknown;
+}
+
+/**
+ * One attempt, as the framework observed it. Every field is something the primitive's one path
+ * already holds; nothing on it is a guess about the business.
+ *
+ * A result is deliberately absent — an action's return value and a read's rows alike. Shipping it
+ * would be the framework deciding the row carries an after-image (for a read: a copy of every row
+ * an auditor's table then has to protect as carefully as the source). `input` is present for the
+ * opposite reason: on a `denied` record nothing ran, so nothing in app code can recover what was
+ * attempted, and that is the record an auditor actually wants.
+ */
+export interface AuditRecord {
+  /**
+   * When the attempt began, from `ctx.now()` — never `new Date()`. An instant, not a rendering:
+   * serialising it is the app's decision, and it is the app that knows the zone it is shown in.
+   */
+  readonly at: Date;
+  /**
+   * The registered export name of the primitive that acted. A mutator carries its action half's.
+   * Required since 25.0.0, which also dropped the `action` alias this field replaced: one name,
+   * one spelling (plan 101, M9). `@ultimat3/action`'s durable sink still files it in the
+   * `x_audit.action` column — a column rename is a data migration, and the value is the same.
+   */
+  readonly name: string;
+  /** `'action'` (a mutator included — see `mutator`) or `'query'`. A read and a write are not one event. */
+  readonly primitive: AuditPrimitive;
+  /** True when `mutator()` built it. Always false for a query. */
+  readonly mutator: boolean;
+  readonly surface: AuditSurface;
+  /**
+   * The context the attempt ran in — actor, `requestId`, `traceId`, locale, and the service bag a
+   * sink needs to write a row at all. Carried whole, because choosing WHICH context facts a row
+   * keeps is precisely the convention four apps modelled four ways.
+   *
+   * **A sink that PERSISTS must project it** (`@ultimat3/action`'s `postgresAuditSink` is the
+   * shipped allow-list): `ctxOf` spreads every installed service onto this object and an
+   * HTTP surface's value carries the caller's `Authorization` and `Cookie`.
+   */
+  readonly ctx: Ctx;
+  /**
+   * The PARSED input, or `undefined` when the parse is what failed. Never the raw payload: an
+   * unvalidated body is attacker-shaped. Unredacted — a persisting sink redacts through
+   * `auditableInput`, the walk core's `isRedactedKey` table and `Secret` decide.
+   */
+  readonly input: unknown;
+  /** The namespaced key an `idempotent` action was retried under, or `null`. Always `null` for a read. */
+  readonly idempotencyKey: string | null;
+  /**
+   * True when the answer came from an earlier settled execution rather than this call's own: an
+   * idempotent action's stored response, or a read served by the request memo or a cache tier.
+   * A call, not a write — and, for a read, still a sighting.
+   */
+  readonly replayed: boolean;
+  readonly outcome: AuditOutcome;
+  /** Present exactly when `outcome !== 'allowed'`. */
+  readonly failure: AuditFailure | null;
+}
+
+/**
+ * Every field of `AuditRecord`, as data — the pin both primitives' tests hold their records to, so
+ * a field one of them forgets to write is a red test in that package and not a hole in a table.
+ * Spelled as a `Record` over `keyof AuditRecord` so a field missing here, or one that is not on the
+ * record, is a typecheck error in this file.
+ */
+const FIELDS: Readonly<Record<keyof AuditRecord, true>> = {
+  at: true,
+  name: true,
+  primitive: true,
+  mutator: true,
+  surface: true,
+  ctx: true,
+  input: true,
+  idempotencyKey: true,
+  replayed: true,
+  outcome: true,
+  failure: true,
+};
+
+export const AUDIT_RECORD_FIELDS: readonly (keyof AuditRecord)[] = Object.freeze(
+  Object.keys(FIELDS) as (keyof AuditRecord)[],
+);
+
+/**
+ * Where a record goes: a table, an append-only hash chain, an OTel log, a queue — the app's.
+ * `@ultimat3/admin`'s `AuditSink` is the same noun one tier up over its own fixed entry type.
+ * A sink that throws is never swallowed; each primitive's audit gate says which failure wins.
+ */
+export interface AuditSink {
+  write(record: AuditRecord): Promise<void> | void;
+}
+
+/**
+ * No default. A logger-backed default would satisfy `audit: true` with a line nobody stores, which
+ * is the silent pass this seam exists to remove: an audited primitive with no sink installed is
+ * refused before it reads its input (`X_AUDIT_SINK_MISSING`, `X_QUERY_AUDIT_SINK_MISSING`).
+ */
+let installed: AuditSink | null = null;
+
+export function setAuditSink(sink: AuditSink): void {
+  installed = sink;
+}
+
+export function getAuditSink(): AuditSink | null {
+  return installed;
+}
+
+/** Test seam: back to "nothing installed", which restoring a literal cannot express. */
+export function resetAuditSink(): void {
+  installed = null;
+}

package/src/aws-sigv4.ts

@@ -0,0 +1,275 @@
+// Single responsibility: AWS Signature Version 4 over one HTTP request — the framework's ONE SigV4
+// implementation, shared by `@ultimat3/storage`'s s3 disk and `@ultimat3/mail`'s SES driver, which
+// sit at tiers that cannot import each other. Web Crypto only (HMAC-SHA256, SHA-256), no SDK, and
+// the instant is an injected `Clock`, so a test signs against AWS's own known answers.
+
+import { assert } from './assert';
+import { type Clock, systemClock } from './clock';
+import { describeValue } from './error-render';
+
+export interface AwsCredentials {
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  /** STS / instance-role credentials: sent and signed as `x-amz-security-token`. */
+  readonly sessionToken?: string | undefined;
+}
+
+/** The literal S3 accepts in place of a body hash — a stream, or bytes too large to hash twice. */
+export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
+
+/**
+ * What the signature says about the body. Absent is the EMPTY body. `{ body }` is hashed here;
+ * `{ sha256Hex }` is a hash the caller already took (a stream it hashed while buffering);
+ * `UNSIGNED_PAYLOAD` signs no body at all, which S3 accepts over TLS.
+ */
+export type AwsPayload =
+  | { readonly body: Uint8Array | string }
+  | { readonly sha256Hex: string }
+  | typeof UNSIGNED_PAYLOAD;
+
+export interface SignAwsRequestInput {
+  readonly method: string;
+  /** Absolute. The path and query are re-encoded strictly; the URL returned is the one signed. */
+  readonly url: string | URL;
+  /** Every header here is signed. `host` defaults to the URL's; `authorization`/`x-amz-date` are the signer's. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly payload?: AwsPayload | undefined;
+  readonly credentials: AwsCredentials;
+  /** `us-east-1`, or `auto` for R2. */
+  readonly region: string;
+  /** `s3`, `ses`, `email`, … — the scope's service segment. */
+  readonly service: string;
+  /** Default `systemClock`. The signature is only valid within ~15 minutes of this instant. */
+  readonly clock?: Clock | undefined;
+  /**
+   * Encode each path segment twice. Default `service !== 's3'`: every AWS service but S3 signs the
+   * already-encoded path again; S3 signs the key encoded once.
+   */
+  readonly doubleEncodePath?: boolean | undefined;
+  /** Send and sign `x-amz-content-sha256`. Default `service === 's3'`, which requires it. */
+  readonly contentSha256Header?: boolean | undefined;
+}
+
+export interface SignedAwsRequest {
+  readonly method: string;
+  /** The URL to send: the input's, with the path and query in the encoding that was signed. */
+  readonly url: string;
+  /** Every header to send — lower-case names, `authorization` included. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** The two intermediate strings, exposed so a provider's `SignatureDoesNotMatch` can be diffed. */
+  readonly canonicalRequest: string;
+  readonly stringToSign: string;
+  readonly signature: string;
+}
+
+const ALGORITHM = 'AWS4-HMAC-SHA256';
+const SCOPE_SEGMENT = /^[a-z0-9-]{1,64}$/;
+const METHOD = /^[A-Z]{1,16}$/;
+/** Headers the signer writes itself; a caller's copy would sign a value the request does not carry. */
+const SIGNER_OWNED: ReadonlySet<string> = new Set([
+  'authorization',
+  'x-amz-date',
+  'x-amz-security-token',
+  'x-amz-content-sha256',
+]);
+
+const encoder = new TextEncoder();
+
+const toHex = (bytes: ArrayBuffer | Uint8Array): string =>
+  Array.from(new Uint8Array(bytes), (byte) => byte.toString(16).padStart(2, '0')).join('');
+
+/** Web Crypto takes an ArrayBuffer-backed view; only a view over shared memory is copied. */
+const ownedBytes = (bytes: Uint8Array): Uint8Array<ArrayBuffer> =>
+  bytes.buffer instanceof ArrayBuffer
+    ? new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+    : new Uint8Array(bytes);
+
+async function sha256Hex(data: Uint8Array | string): Promise<string> {
+  const bytes = typeof data === 'string' ? encoder.encode(data) : ownedBytes(data);
+  return toHex(await crypto.subtle.digest('SHA-256', bytes));
+}
+
+async function hmac(key: Uint8Array<ArrayBuffer>, data: string): Promise<Uint8Array<ArrayBuffer>> {
+  const imported = await crypto.subtle.importKey(
+    'raw',
+    key,
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['sign'],
+  );
+  return new Uint8Array(await crypto.subtle.sign('HMAC', imported, encoder.encode(data)));
+}
+
+/** RFC 3986 unreserved bytes stay; everything else is `%XX`, upper-case — SigV4's `UriEncode`. */
+function uriEncode(value: string): string {
+  let encoded: string;
+  try {
+    encoded = encodeURIComponent(value);
+  } catch {
+    // A lone surrogate: there are no UTF-8 bytes to sign.
+    assert(
+      false,
+      'an AWS request URL holds a lone UTF-16 surrogate, which has no UTF-8 encoding',
+      'build the key from well-formed text: value.toWellFormed()',
+    );
+  }
+  return encoded.replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function uriDecode(value: string, where: string): string {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    assert(
+      false,
+      `an AWS request ${where} holds a malformed percent-escape (${describeValue(value)}), so no canonical form exists to sign`,
+      'encode each segment with encodeURIComponent() before building the URL — a literal % is %25',
+    );
+  }
+}
+
+function canonicalPath(pathname: string, doubleEncode: boolean): string {
+  if (pathname === '') return '/';
+  return pathname
+    .split('/')
+    .map((segment) => {
+      const once = uriEncode(uriDecode(segment, 'path'));
+      return doubleEncode ? uriEncode(once) : once;
+    })
+    .join('/');
+}
+
+/** Pairs decoded then strictly re-encoded, sorted by key then value; a bare `key` is `key=`. */
+function canonicalQuery(search: string): string {
+  const pairs: [string, string][] = [];
+  for (const part of search.replace(/^\?/, '').split('&')) {
+    if (part === '') continue;
+    const at = part.indexOf('=');
+    const key = at === -1 ? part : part.slice(0, at);
+    const value = at === -1 ? '' : part.slice(at + 1);
+    pairs.push([uriEncode(uriDecode(key, 'query')), uriEncode(uriDecode(value, 'query'))]);
+  }
+  pairs.sort(([ak, av], [bk, bv]) => (ak === bk ? (av < bv ? -1 : 1) : ak < bk ? -1 : 1));
+  return pairs.map(([key, value]) => `${key}=${value}`).join('&');
+}
+
+/** Lower-case names, trimmed values with inner whitespace runs collapsed, duplicates comma-joined. */
+function canonicalHeaders(headers: Readonly<Record<string, string>>): Map<string, string> {
+  const merged = new Map<string, string>();
+  for (const [name, raw] of Object.entries(headers)) {
+    const key = name.trim().toLowerCase();
+    const value = raw.trim().replace(/\s+/g, ' ');
+    const prior = merged.get(key);
+    merged.set(key, prior === undefined ? value : `${prior},${value}`);
+  }
+  return new Map([...merged].sort(([a], [b]) => (a < b ? -1 : 1)));
+}
+
+function parseUrl(url: string | URL): URL {
+  if (url instanceof URL) return url;
+  assert(
+    URL.canParse(url),
+    `signAwsRequest was handed a url that is not absolute (${describeValue(url)})`,
+    "pass the whole endpoint URL: signAwsRequest({ url: 'https://<host>/<path>', … })",
+  );
+  return new URL(url);
+}
+
+function assertInput(input: SignAwsRequestInput): void {
+  const { accessKeyId, secretAccessKey } = input.credentials;
+  assert(
+    accessKeyId !== '' && secretAccessKey !== '',
+    'signAwsRequest was handed an empty access key id or secret, so nothing can be signed',
+    'set the access key id and secret (S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY, or the driver’s own env names), then re-run',
+  );
+  for (const [name, value] of [
+    ['region', input.region],
+    ['service', input.service],
+  ] as const) {
+    assert(
+      SCOPE_SEGMENT.test(value),
+      `signAwsRequest was handed a ${name} that cannot be a credential-scope segment (${describeValue(value)})`,
+      `pass a lower-case ${name} of letters, digits and hyphens — region: 'us-east-1', service: 's3'`,
+    );
+  }
+  assert(
+    METHOD.test(input.method),
+    `signAwsRequest was handed an HTTP method that is not upper-case letters (${describeValue(input.method)})`,
+    "pass the method as sent on the wire: method: 'PUT'",
+  );
+}
+
+async function payloadHash(payload: AwsPayload | undefined): Promise<string> {
+  if (payload === undefined) return sha256Hex('');
+  if (payload === UNSIGNED_PAYLOAD) return UNSIGNED_PAYLOAD;
+  if ('sha256Hex' in payload) return payload.sha256Hex;
+  return sha256Hex(payload.body);
+}
+
+/** `20150830T123600Z` — the ISO instant with its separators and fraction removed. Always UTC. */
+const amzDate = (clock: Clock): string =>
+  clock
+    .now()
+    .toISOString()
+    .replace(/\.\d{3}Z$/, 'Z')
+    .replace(/[-:]/g, '');
+
+/**
+ * Sign one request with SigV4 in the `Authorization` header. Returns everything to send — the
+ * re-encoded URL and every header — plus the canonical request and string-to-sign for debugging.
+ * A malformed input (an empty credential, a scope segment with a `/`, a broken escape) is a coded
+ * `X_INVARIANT` refusal before anything is hashed.
+ */
+export async function signAwsRequest(input: SignAwsRequestInput): Promise<SignedAwsRequest> {
+  assertInput(input);
+  const url = parseUrl(input.url);
+  const service = input.service;
+  const path = canonicalPath(url.pathname, input.doubleEncodePath ?? service !== 's3');
+  const query = canonicalQuery(url.search);
+  const date = amzDate(input.clock ?? systemClock);
+  const hash = await payloadHash(input.payload);
+
+  const caller: Record<string, string> = {};
+  for (const [name, value] of Object.entries(input.headers ?? {})) {
+    if (!SIGNER_OWNED.has(name.trim().toLowerCase())) caller[name] = value;
+  }
+  const hasHost = Object.keys(caller).some((name) => name.trim().toLowerCase() === 'host');
+  const token = input.credentials.sessionToken;
+  const headers = canonicalHeaders({
+    ...caller,
+    ...(hasHost ? {} : { host: url.host }),
+    'x-amz-date': date,
+    ...(token === undefined || token === '' ? {} : { 'x-amz-security-token': token }),
+    ...((input.contentSha256Header ?? service === 's3') ? { 'x-amz-content-sha256': hash } : {}),
+  });
+  const signedHeaders = [...headers.keys()].join(';');
+  const canonicalRequest = [
+    input.method,
+    path,
+    query,
+    ...[...headers].map(([name, value]) => `${name}:${value}`),
+    '',
+    signedHeaders,
+    hash,
+  ].join('\n');
+
+  const day = date.slice(0, 8);
+  const scope = `${day}/${input.region}/${service}/aws4_request`;
+  const stringToSign = [ALGORITHM, date, scope, await sha256Hex(canonicalRequest)].join('\n');
+  let key = encoder.encode(`AWS4${input.credentials.secretAccessKey}`);
+  for (const part of [day, input.region, service, 'aws4_request']) key = await hmac(key, part);
+  const signature = toHex(await hmac(key, stringToSign));
+
+  const sent = Object.fromEntries(headers);
+  sent['authorization'] =
+    `${ALGORITHM} Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  const singlePath = canonicalPath(url.pathname, false);
+  return {
+    method: input.method,
+    url: `${url.origin}${singlePath}${query === '' ? '' : `?${query}`}`,
+    headers: sent,
+    canonicalRequest,
+    stringToSign,
+    signature,
+  };
+}

package/src/backoff.ts

@@ -70,3 +70,19 @@ export function backoffDelay(options: BackoffOptions): number {
   if (options.jitter === 'equal') return Math.round(capped / 2 + (capped / 2) * roll());
   return Math.round(capped);
 }
+
+/**
+ * The wait after a responder STATED one: the stated delay as a FLOOR, plus a spread in
+ * `[0, min(wait / 2, cap))`. The ONE rule for a named delay — `retryDecision`'s `retry-after`
+ * path and `@ultimat3/jobs`' rate-limit deferral and webhook throttle all take it. A floor because
+ * waking before the responder said is refused again; a spread because a shedding server tells a
+ * whole burst `Retry-After: 1`, and a burst that waits exactly that replays in lockstep every
+ * second, as does every delivery handed one HTTP-date. `cap` bounds only the spread.
+ */
+export function jitterStatedDelay(
+  waitMs: number,
+  capMs: number,
+  random: Random = Math.random,
+): number {
+  return waitMs + Math.floor(random() * Math.min(waitMs / 2, capMs));
+}

package/src/bunfs.ts

@@ -0,0 +1,17 @@
+// Whether a directory is inside a `bun build --compile` executable's virtual filesystem. One answer
+// for every platform, because Bun spells its root two ways: `/$bunfs/` on POSIX and `B:\~BUN\`
+// (public form `B:/~BUN/`) on Windows — `BASE_PATH` / `BASE_PUBLIC_PATH` in Bun's
+// `StandaloneModuleGraph`, as of Bun 1.4.2. An entry that tested only the first resolved its app root
+// INSIDE the bundle on Windows, where no source exists, and every registry booted empty.
+
+/** Each prefix is followed by a separator or nothing, so `/$bunfsx` or `B:\~BUNDLE` never match. */
+const COMPILED_ROOT = /^(?:\/\$bunfs|[Bb]:[\\/]~BUN)(?:[\\/]|$)/;
+
+/**
+ * `true` when `dir` — normally `import.meta.dir` — is a path inside a compiled executable. Such a
+ * path holds the entry's bundled imports and nothing else, so an app reads its root from the
+ * directory it is started in instead.
+ */
+export function isCompiledBundle(dir: string): boolean {
+  return COMPILED_ROOT.test(dir);
+}

package/src/client-dispatch.ts

@@ -6,9 +6,11 @@
 
 import type { ClientFlight, ClientRetry } from './client-flight';
 import { problemError, transportFailed } from './client-problem';
+import { retryAfterSecondsOf } from './client-retry-after';
 import { onRescope } from './client-scope';
 import { scopeChanged } from './client-scope-error';
 import type { UltimateError } from './errors';
+import { CLIENT_BUILD_META } from './page-meta';
 import type { RecordEnvelope } from './record-envelope';
 import { RECORDS_HEADER } from './record-envelope';
 import { outboundSlot, pageClient } from './record-sink';
@@ -18,6 +20,14 @@ export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
 /** The header `@ultimat3/action`'s server reads to replay rather than re-run a write. */
 export const IDEMPOTENCY_HEADER = 'idempotency-key';
 
+/**
+ * The build a client was served, on the request, and the build that answered, on the response.
+ * `@ultimat3/http` reads it into `ctx.clientBuildId` and stamps it back; `@ultimat3/action`'s typed
+ * client and `@ultimat3/pwa`'s service worker send it; `@ultimat3/render` writes it. The document
+ * meta's spelling by construction, so a script reading either reads one name. Not configurable.
+ */
+export const BUILD_ID_HEADER: typeof CLIENT_BUILD_META = CLIENT_BUILD_META;
+
 export interface TransportRequest {
   readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   readonly url: string;
@@ -46,8 +56,14 @@ export interface TransportRequest {
   readonly onEnvelope?: ((envelope: RecordEnvelope) => void) | undefined;
   /** Sees every response before its body is read — a header check may throw its own refusal. */
   readonly onResponse?: ((response: Response) => void | Promise<void>) | undefined;
-  /** A non-2xx answer as the caller's own error; `undefined` falls back to the shared decode. */
-  readonly decodeError?: ((status: number, text: string) => UltimateError | undefined) | undefined;
+  /**
+   * A non-2xx answer as the caller's own error; `undefined` falls back to the shared decode.
+   * `retryAfterSeconds` is the delay the answer's `Retry-After` named (`retryAfterSecondsOf`),
+   * for a decoder to classify with `retryForStatus` and carry as `meta.retryAfterSeconds`.
+   */
+  readonly decodeError?:
+    | ((status: number, text: string, retryAfterSeconds?: number) => UltimateError | undefined)
+    | undefined;
   /** Default `globalThis.fetch`, read at call time — never captured at module scope. */
   readonly fetchImpl?: FetchLike | undefined;
 }
@@ -79,8 +95,13 @@ export async function dispatch(
     // Read as TEXT once: a body is a single-use stream, and the failure path wants it too.
     const text = response.status === 204 ? '' : await onTheWire(req, read, () => response.text());
     if (!response.ok) {
+      const stated = retryAfterSecondsOf(
+        response.headers.get('retry-after'),
+        response.headers.get('date'),
+      );
       throw (
-        req.decodeError?.(response.status, text) ?? problemError(response.status, text, req.url)
+        req.decodeError?.(response.status, text, stated) ??
+        problemError(response.status, text, req.url, stated)
       );
     }
     return { text, enveloped: response.headers.get(RECORDS_HEADER) === '1' };

package/src/client-flight.ts

@@ -9,7 +9,7 @@
  * each; both re-export this one, so their public surface is unchanged and there is one file.
  *
  * Nothing here is imported by either package's `client.ts` at VALUE level. A caller that wants a
- * plain typed fetch never mentions `createClientFlight`, so this module and every module it
+ * plain typed fetch never mentions `clientFlight`, so this module and every module it
  * imports are shaken out of that caller's bundle — the 36 kB island problem is the reason it is
  * built this way, and `packages/{action,query}/src/client.ts` must keep naming `ClientFlight` as
  * an `import type`.
@@ -19,12 +19,12 @@ import type { Random } from './backoff';
 import { classifyThrown } from './error-retry';
 import { UltimateError } from './errors';
 import type { FlightGate, FlightGateLimits } from './flight-gate';
-import { createFlightGate } from './flight-gate';
-import { createFence } from './generation-fence';
+import { flightGate } from './flight-gate';
+import { generationFence } from './generation-fence';
 import type { RetryPolicy } from './retry';
 import { retry } from './retry';
 import type { Scheduler } from './single-flight';
-import { createSingleFlight } from './single-flight';
+import { singleFlight } from './single-flight';
 
 /** Overrides for the shipped policy. `attempts: 1` — the default — means one dispatch, no retry. */
 export type ClientRetry = Partial<RetryPolicy>;
@@ -93,6 +93,11 @@ export interface FlightPlan<T> {
   readonly abortable: boolean;
   /** One attempt. `signal` is the flight's own — a caller's signal never reaches here. */
   run(signal: AbortSignal | undefined, attempt: number): Promise<T>;
+  /**
+   * The CALLER's signal, read for one thing: an abort during the wait between attempts settles the
+   * call at once, a write's included. `run` gets the flight's own signal as before.
+   */
+  readonly signal?: AbortSignal | undefined;
   /** Overrides the flight's policy for this one call. */
   readonly retry?: ClientRetry | undefined;
   /**
@@ -153,9 +158,9 @@ const defaultSchedule: Scheduler = (fn, ms) => {
   };
 };
 
-export function createClientFlight(options: ClientFlightOptions = {}): ClientFlight {
+export function clientFlight(options: ClientFlightOptions = {}): ClientFlight {
   const subject = options.subject ?? 'a typed client call';
-  const fence = createFence(subject);
+  const fence = generationFence(subject);
   const schedule = options.schedule ?? defaultSchedule;
   const sleep =
     options.sleep ??
@@ -167,11 +172,60 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
   const transientFor = (plan: FlightPlan<unknown>): ((error: unknown) => boolean) =>
     plan.classified === true && options.transient === undefined ? isDeclaredTransient : transient;
   const deadlineMs = options.deadlineMs;
-  const flights = createSingleFlight({ deadlineMs, schedule });
+  const flights = singleFlight({ deadlineMs, schedule });
   const gate: FlightGate | undefined =
-    options.limit === undefined ? undefined : createFlightGate(options.limit, { subject });
+    options.limit === undefined ? undefined : flightGate(options.limit, { subject });
   const live = new Set<AbortController>();
 
+  /**
+   * The wait between attempts, raced against the flight's signal (`bump()`, the deadline) and the
+   * caller's. Uncancellable, a bump at 50 ms settled `X_SUPERSEDED` only when a one-second wait
+   * ran out; now it settles at once, with the abort's own reason, and the timer is let go.
+   */
+  const waitFor = (ms: number, signals: readonly (AbortSignal | undefined)[]): Promise<void> => {
+    const live = signals.filter((one): one is AbortSignal => one !== undefined);
+    const fired = live.find((one) => one.aborted);
+    if (fired !== undefined) return Promise.reject(fired.reason);
+    if (live.length === 0) return sleep(ms);
+    return new Promise<void>((resolve, reject) => {
+      let cancel: (() => void) | undefined;
+      const stop = (): void => {
+        for (const one of live) one.removeEventListener('abort', onAbort);
+      };
+      const onAbort = (event: Event): void => {
+        stop();
+        cancel?.();
+        reject((event.target as AbortSignal).reason);
+      };
+      const done = (): void => {
+        stop();
+        resolve();
+      };
+      for (const one of live) one.addEventListener('abort', onAbort, { once: true });
+      // The flight's own scheduler is cancellable, so an abandoned wait leaves no timer behind; an
+      // injected `sleep` is a test's, raced and simply never awaited again.
+      if (options.sleep === undefined) cancel = schedule(done, ms);
+      else
+        options.sleep(ms).then(done, (error: unknown) => {
+          stop();
+          reject(error);
+        });
+    });
+  };
+
+  /**
+   * One attempt holds a gate slot; the WAIT between attempts does not. Held across the sleep, a
+   * call backing off from a 503 kept the ceiling's only slot and a second call was refused
+   * `X_FLIGHT_GATE_OVERLOADED` for work nobody was doing. Re-acquired for the next attempt.
+   */
+  const once = <T>(plan: FlightPlan<T>, signal: AbortSignal | undefined, count: number) => {
+    if (gate === undefined) return plan.run(signal, count);
+    // The queued wait for a slot ends on the same two signals the wait between attempts does.
+    const signals = [signal, plan.signal].filter((one): one is AbortSignal => one !== undefined);
+    const cancel = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    return gate.run(() => plan.run(signal, count), cancel);
+  };
+
   const attempt = async <T>(plan: FlightPlan<T>, signal: AbortSignal | undefined): Promise<T> => {
     const policy: RetryPolicy = {
       ...DEFAULT_CLIENT_RETRY,
@@ -188,7 +242,7 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
     const answer = await retry<T | typeof STOPPED>(
       async (count) => {
         try {
-          return await plan.run(signal, count);
+          return await once(plan, signal, count);
         } catch (error) {
           if (sendAgain(error)) throw error;
           stopped = { error };
@@ -197,7 +251,7 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
       },
       policy,
       {
-        sleep,
+        sleep: (ms) => waitFor(ms, [signal, plan.signal]),
         ...(options.random === undefined ? {} : { random: options.random }),
         ...(options.now === undefined ? {} : { now: options.now }),
       },
@@ -272,8 +326,9 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
 
     run<T>(plan: FlightPlan<T>): Promise<T> {
       const issued = fence.generation();
-      const work = (): Promise<T> =>
-        gate === undefined ? dispatch(plan) : gate.run(() => dispatch(plan));
+      // The gate is taken per ATTEMPT, inside `dispatch` (`once`), so a wait between attempts holds
+      // no slot.
+      const work = (): Promise<T> => dispatch(plan);
       // The single flight sits OUTSIDE the gate: a joiner takes no slot, so dedup relieves the
       // ceiling instead of queueing behind it. Keyed by GENERATION too: `bump()` aborts the old
       // flights, but each holds its key until its rejection settles, and a same-key read issued
@@ -304,7 +359,7 @@ function deadlineExpired(subject: string, deadlineMs: number): UltimateError {
   return new UltimateError({
     code: 'X_TIMEOUT',
     cause: `${subject} was aborted after its client deadline of ${deadlineMs}ms`,
-    fix: 'raise deadlineMs at the createClientFlight({ deadlineMs }) call site, or find what is answering that slowly with x doctor --json',
+    fix: 'raise deadlineMs at the clientFlight({ deadlineMs }) call site, or find what is answering that slowly with x doctor --json',
     meta: { subject, deadlineMs },
   });
 }