@ultimat3/core 29.3.2 → 30.0.0

package/package.json

@@ -1,7 +1,18 @@
 {
   "name": "@ultimat3/core",
-  "version": "29.3.2",
+  "version": "30.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
+  "keywords": [
+    "ultimate",
+    "bun",
+    "framework",
+    "errors",
+    "env",
+    "config",
+    "telemetry",
+    "retry"
+  ],
+  "homepage": "https://github.com/developerz-ai/ultimate/wiki/Configuration",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
@@ -19,7 +30,12 @@
   },
   "exports": {
     ".": "./src/index.ts",
-    "./page": "./src/page.ts"
+    "./page": "./src/page.ts",
+    "./internal/error-status": "./src/error-status-declared.ts",
+    "./outbound": "./src/outbound-subpath.ts",
+    "./redis": "./src/redis-client.ts",
+    "./render-node": "./src/render-node.ts",
+    "./render-nodes": "./src/render-nodes.ts"
   },
   "files": [
     "src",
@@ -37,6 +53,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "29.3.2"
+    "@ultimat3/schema": "30.0.0"
   }
 }

package/src/address-class.ts

@@ -29,6 +29,7 @@ const V4_RULES: readonly (readonly [number, number, AddressClass])[] = [
   [0x64400000, 10, 'cgnat'],
   [0xc0000000, 24, 'reserved'], // 192.0.0.0/24, IETF protocol assignments
   [0xc0000200, 24, 'reserved'], // 192.0.2.0/24, TEST-NET-1
+  [0xc0586300, 24, 'reserved'], // 192.88.99.0/24, the deprecated 6to4 relay anycast
   [0xc6120000, 15, 'reserved'], // 198.18.0.0/15, benchmarking
   [0xc6336400, 24, 'reserved'], // 198.51.100.0/24, TEST-NET-2
   [0xcb007100, 24, 'reserved'], // 203.0.113.0/24, TEST-NET-3
@@ -97,24 +98,48 @@ function parseV6(text: string): readonly number[] | undefined {
 
 const embeddedV4 = (g: readonly number[]): number => (g[6] ?? 0) * 0x10000 + (g[7] ?? 0);
 
-function classifyV6(g: readonly number[]): AddressClass {
-  const zeroUpTo = (n: number): boolean => g.slice(0, n).every((group) => group === 0);
-  if (zeroUpTo(8)) return 'unspecified';
-  if (zeroUpTo(7) && g[7] === 1) return 'loopback';
-  // IPv4-mapped `::ffff:a.b.c.d`, IPv4-compatible `::a.b.c.d` and NAT64 `64:ff9b::/96`: each is
-  // routed to the IPv4 address it carries, so that address is what gets classified.
-  if (zeroUpTo(5) && g[5] === 0xffff) return classifyV4(embeddedV4(g));
-  if (zeroUpTo(6)) return classifyV4(embeddedV4(g));
+const zeroUpTo = (g: readonly number[], n: number): boolean =>
+  g.slice(0, n).every((group) => group === 0);
+
+/** `::ffff:a.b.c.d`: how a dual-stack socket spells an IPv4 peer, so that peer really is the IPv4. */
+const isMappedV4 = (g: readonly number[]): boolean => zeroUpTo(g, 5) && g[5] === 0xffff;
+
+/**
+ * The IPv4 a TRANSIT form carries: IPv4-translated `::ffff:0:a.b.c.d`, IPv4-compatible `::a.b.c.d`,
+ * NAT64 `64:ff9b::/96` and 6to4 `2002::/16`, which alone holds it in bits 16-47, not the last 32.
+ * Each is routed to that address, but the address on the packet is not that host's.
+ */
+function transitV4(g: readonly number[]): number | undefined {
+  if (zeroUpTo(g, 4) && g[4] === 0xffff && g[5] === 0) return embeddedV4(g);
+  const isLoopbackOrUnspecified = zeroUpTo(g, 7) && (g[7] ?? 0) <= 1;
+  if (zeroUpTo(g, 6) && !isLoopbackOrUnspecified) return embeddedV4(g);
   if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((group) => group === 0)) {
-    return classifyV4(embeddedV4(g));
+    return embeddedV4(g);
   }
+  if (g[0] === 0x2002) return (g[1] ?? 0) * 0x10000 + (g[2] ?? 0);
+  return undefined;
+}
+
+function classifyV6(g: readonly number[]): AddressClass {
+  if (zeroUpTo(g, 8)) return 'unspecified';
+  if (zeroUpTo(g, 7) && g[7] === 1) return 'loopback';
+  // Each of these is routed to the IPv4 address it carries, so that is what gets classified.
+  if (isMappedV4(g)) return classifyV4(embeddedV4(g));
+  const carried = transitV4(g);
+  if (carried !== undefined) return classifyV4(carried);
   const first = g[0] ?? 0;
+  const second = g[1] ?? 0;
   if ((first & 0xffc0) === 0xfe80) return 'link-local';
   if ((first & 0xffc0) === 0xfec0) return 'private'; // deprecated site-local
   if ((first & 0xfe00) === 0xfc00) return 'ula';
-  if ((first & 0xff00) === 0xff00) return 'reserved'; // multicast
-  if (first === 0x2001 && g[1] === 0x0db8) return 'reserved'; // documentation
-  if (first === 0x0100 && g.slice(1, 4).every((group) => group === 0)) return 'reserved'; // 100::/64
+  // Only `2000::/3` is global unicast. The rest — multicast, `100::/64`, local-use NAT64, SRv6, the
+  // unassigned space — is named rather than left to read as public, which is what fails closed.
+  if ((first & 0xe000) !== 0x2000) return 'reserved';
+  // Teredo. Its client address is obfuscated, so unwrapping it would classify a mask, not a host.
+  if (first === 0x2001 && second === 0) return 'private';
+  if (first === 0x2001 && second < 0x0200) return 'reserved'; // 2001::/23, IETF protocol assignments
+  if (first === 0x2001 && second === 0x0db8) return 'reserved'; // documentation
+  if (first === 0x3fff && second < 0x1000) return 'reserved'; // 3fff::/20, documentation
 
   return 'public';
 }
@@ -143,6 +168,22 @@ export function classifyAddress(address: string): AddressClass | undefined {
   return v4 === undefined ? undefined : classifyV4(v4);
 }
 
+/**
+ * The class of an address as a CALLER or a local name, for a check that grants something on it —
+ * `classifyAddress` answers where a DIAL would land, a different question over the same bits. A
+ * transit form spelling an inward IPv4 (`64:ff9b::7f00:1`, `2002:7f00:1::`) is a stranger across
+ * the network, so it answers `reserved`, never the class it spells; `::ffff:127.0.0.1` stays
+ * `loopback`, being only how a dual-stack socket writes 127.0.0.1. `undefined` as there.
+ */
+export function peerAddressClass(address: string): AddressClass | undefined {
+  const kind = classifyAddress(address);
+  if (kind === undefined || kind === 'public') return kind;
+  const text = literalOf(address);
+  if (!text.includes(':')) return kind;
+  const groups = parseV6(text);
+  return groups !== undefined && transitV4(groups) !== undefined ? 'reserved' : kind;
+}
+
 /** Fails CLOSED: anything but a literal classified `public` — a hostname included — is `false`. */
 export function isPublicAddress(address: string): boolean {
   return classifyAddress(address) === 'public';

package/src/aws-sigv4.ts

@@ -6,6 +6,7 @@
 import { assert } from './assert';
 import { type Clock, systemClock } from './clock';
 import { describeValue } from './error-render';
+import { finiteCount } from './finite-option';
 
 export interface AwsCredentials {
   readonly accessKeyId: string;
@@ -62,7 +63,32 @@ export interface SignedAwsRequest {
   readonly signature: string;
 }
 
+/**
+ * A URL whose query carries the signature: a credential-less holder sends it from a browser. What
+ * `headers` names is inside the signature, so the request must carry exactly those values.
+ */
+export interface PresignAwsUrlInput
+  extends Pick<
+    SignAwsRequestInput,
+    'method' | 'url' | 'credentials' | 'region' | 'service' | 'clock' | 'doubleEncodePath'
+  > {
+  /** 1 … 604 800, S3's own limit. */
+  readonly expiresInSeconds: number;
+  /** Signed, and sent by whoever holds the URL. `host` is always signed. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+}
+
+export interface PresignedAwsUrl {
+  readonly url: 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';
+/** SigV4's own ceiling on `X-Amz-Expires`: seven days. A presigner beside this one refuses past it too. */
+export const MAX_AWS_PRESIGN_SECONDS = 604_800;
 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. */
@@ -175,7 +201,9 @@ function parseUrl(url: string | URL): URL {
   return new URL(url);
 }
 
-function assertInput(input: SignAwsRequestInput): void {
+function assertInput(
+  input: Pick<SignAwsRequestInput, 'credentials' | 'region' | 'service' | 'method'>,
+): void {
   const { accessKeyId, secretAccessKey } = input.credentials;
   assert(
     accessKeyId !== '' && secretAccessKey !== '',
@@ -214,6 +242,25 @@ const amzDate = (clock: Clock): string =>
     .replace(/\.\d{3}Z$/, 'Z')
     .replace(/[-:]/g, '');
 
+/** The scope, the string to sign and the signature over it: one derivation for both forms. */
+async function signatureOver(
+  input: Pick<SignAwsRequestInput, 'credentials' | 'region' | 'service'>,
+  date: string,
+  canonicalRequest: string,
+): Promise<{ readonly stringToSign: string; readonly signature: string }> {
+  const day = date.slice(0, 8);
+  const scope = scopeOf(input, day);
+  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, input.service, 'aws4_request']) {
+    key = await hmac(key, part);
+  }
+  return { stringToSign, signature: toHex(await hmac(key, stringToSign)) };
+}
+
+const scopeOf = (input: Pick<SignAwsRequestInput, 'region' | 'service'>, day: string): string =>
+  `${day}/${input.region}/${input.service}/aws4_request`;
+
 /**
  * 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.
@@ -253,13 +300,8 @@ export async function signAwsRequest(input: SignAwsRequestInput): Promise<Signed
     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 { stringToSign, signature } = await signatureOver(input, date, canonicalRequest);
+  const scope = scopeOf(input, date.slice(0, 8));
   const sent = Object.fromEntries(headers);
   sent['authorization'] =
     `${ALGORITHM} Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
@@ -273,3 +315,57 @@ export async function signAwsRequest(input: SignAwsRequestInput): Promise<Signed
     signature,
   };
 }
+
+/**
+ * Sign one request with SigV4 in its query, for a holder with no credentials. The payload is
+ * `UNSIGNED-PAYLOAD`, because the holder's body is not this process's to hash; a signed
+ * `content-length` is what bounds it instead, since the provider recomputes the signature from the
+ * header the request really carries.
+ */
+export async function presignAwsUrl(input: PresignAwsUrlInput): Promise<PresignedAwsUrl> {
+  assertInput(input);
+  const expires = finiteCount('presignAwsUrl', 'expiresInSeconds', input.expiresInSeconds, 1);
+  assert(
+    expires <= MAX_AWS_PRESIGN_SECONDS,
+    `presignAwsUrl was handed expiresInSeconds ${expires}, past SigV4's limit of ${MAX_AWS_PRESIGN_SECONDS}`,
+    `expiresInSeconds: ${MAX_AWS_PRESIGN_SECONDS}   # seven days, the longest a presigned URL can live`,
+  );
+  const url = parseUrl(input.url);
+  const date = amzDate(input.clock ?? systemClock);
+  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 headers = canonicalHeaders({ ...caller, ...(hasHost ? {} : { host: url.host }) });
+  const signedHeaders = [...headers.keys()].join(';');
+  const token = input.credentials.sessionToken;
+  const params = new URLSearchParams(url.search);
+  params.set('X-Amz-Algorithm', ALGORITHM);
+  params.set(
+    'X-Amz-Credential',
+    `${input.credentials.accessKeyId}/${scopeOf(input, date.slice(0, 8))}`,
+  );
+  params.set('X-Amz-Date', date);
+  params.set('X-Amz-Expires', String(expires));
+  params.set('X-Amz-SignedHeaders', signedHeaders);
+  if (token !== undefined && token !== '') params.set('X-Amz-Security-Token', token);
+  const query = canonicalQuery(params.toString().replaceAll('+', '%20'));
+  const doubleEncode = input.doubleEncodePath ?? input.service !== 's3';
+  const canonicalRequest = [
+    input.method,
+    canonicalPath(url.pathname, doubleEncode),
+    query,
+    ...[...headers].map(([name, value]) => `${name}:${value}`),
+    '',
+    signedHeaders,
+    UNSIGNED_PAYLOAD,
+  ].join('\n');
+  const { stringToSign, signature } = await signatureOver(input, date, canonicalRequest);
+  return {
+    url: `${url.origin}${canonicalPath(url.pathname, false)}?${query}&X-Amz-Signature=${signature}`,
+    canonicalRequest,
+    stringToSign,
+    signature,
+  };
+}

package/src/breaker.ts

@@ -0,0 +1,177 @@
+// Single responsibility: the circuit breaker's state machine, and nothing about what counts as a
+// failure — the TRIGGER is the caller's (`classify`, or `failed()` called by hand). Four apps wrote
+// this machine and disagreed only on the trigger; `@ultimat3/db`'s replica router held a private
+// copy. Per process, by design: a shared row would make the breaker depend on the slow thing.
+
+import type { Clock } from './clock';
+import { systemClock } from './clock';
+import { declaredErrorRetry, registerErrorRetry } from './error-retry';
+import { isUltimateError, UltimateError } from './errors';
+import { finiteCount } from './finite-option';
+import { recordBreakerTransition } from './runtime-metrics';
+
+// Here, not in `error-retry.ts`'s core table, which rides every browser page: a breaker is server
+// work. Open names the time left in `retryAfterSeconds`, the flight gate's spelling.
+registerErrorRetry({ X_BREAKER_OPEN: 'retry-after' });
+
+export type BreakerState = 'closed' | 'open' | 'half-open';
+
+/** What one settled call says about the dependency. `ignore` says nothing: a caller's abort. */
+export type BreakerVerdict = 'failure' | 'success' | 'ignore';
+
+export interface BreakerOptions {
+  /** A bounded label chosen in code (`'resend'`, `'replica'`) — never a tenant or a URL. */
+  readonly name: string;
+  /** Consecutive failures that open it. */
+  readonly failures: number;
+  /** How long it stays open before one probe is let through, in ms. */
+  readonly cooldownMs: number;
+  /** The trigger. Default: `defaultBreakerClassify`. */
+  readonly classify?: ((error: unknown) => BreakerVerdict) | undefined;
+  /** Monotonic time only: a wall-clock step must not close a breaker. */
+  readonly clock?: Pick<Clock, 'monotonic'> | undefined;
+}
+
+/**
+ * One admission. The breaker settles the half-open probe only through ITS ticket, so a call
+ * admitted before the trip — aborting, failing or answering late — never frees or closes it.
+ */
+export interface BreakerTicket {
+  /** Whether this admission is the half-open probe. */
+  readonly probe: boolean;
+}
+
+export interface Breaker {
+  readonly name: string;
+  /** May a call go out now: its ticket, or `undefined`. In `half-open` the one ticket IS the probe. */
+  admit(): BreakerTicket | undefined;
+  /** The dependency answered. In `half-open` only the probe's ticket closes it; `open` ignores it. */
+  succeeded(ticket?: BreakerTicket): void;
+  failed(ticket?: BreakerTicket): void;
+  /** The call ended for a reason that says nothing: the probe's ticket gives the probe back. */
+  released(ticket?: BreakerTicket): void;
+  /** Read-only: never consumes a probe. `half-open` once the cooldown has passed. */
+  state(): BreakerState;
+  /** The current run of consecutive failures. */
+  failures(): number;
+  /** This breaker's `classify`, the default applied when none was given. */
+  judge(error: unknown): BreakerVerdict;
+  /** `X_BREAKER_OPEN` with the time left, for a caller that refuses without `run`. */
+  refusal(): UltimateError;
+  run<T>(fn: () => Promise<T>): Promise<T>;
+}
+
+/**
+ * Retryable means the dependency did not answer: a failure. A caller going away is no statement
+ * about the dependency (`X_ABORTED`, `X_DRAINING`, checked first: the second is retryable). Any
+ * other outcome is an answer, refusals included — a 400 is a vendor that is up.
+ */
+export function defaultBreakerClassify(error: unknown): BreakerVerdict {
+  if (!isUltimateError(error)) return 'success';
+  if (error.code === 'X_ABORTED' || error.code === 'X_DRAINING') return 'ignore';
+  const retry = declaredErrorRetry(error.code);
+  return retry === 'retryable' || retry === 'retry-after' ? 'failure' : 'success';
+}
+
+export function breakerOpen(name: string, retryAfterSeconds: number): UltimateError {
+  return new UltimateError({
+    code: 'X_BREAKER_OPEN',
+    cause: `the breaker "${name}" is open after consecutive failures, so this call was not sent`,
+    fix: `breaker({ name: '${name}', failures, cooldownMs })   # raise failures if this outage is not one; else wait ${String(retryAfterSeconds)} s and check the dependency "${name}" names`,
+    meta: { name, retryAfterSeconds },
+  });
+}
+
+export function breaker(options: BreakerOptions): Breaker {
+  const limit = finiteCount('breaker()', 'failures', options.failures, 1);
+  const cooldownMs = finiteCount('breaker()', 'cooldownMs', options.cooldownMs, 1);
+  const clock = options.clock ?? systemClock;
+  const classify = options.classify ?? defaultBreakerClassify;
+  let current: BreakerState = 'closed';
+  let count = 0;
+  /** When it opened (`open`) or when the probe went out (`half-open`). */
+  let since = 0;
+
+  const move = (to: BreakerState): void => {
+    if (current === to) return;
+    current = to;
+    recordBreakerTransition(options.name, to);
+  };
+  const lapsed = (): boolean => clock.monotonic() - since >= cooldownMs;
+
+  const CLOSED_TICKET: BreakerTicket = Object.freeze({ probe: false });
+  /** The outstanding probe's ticket, compared by identity. */
+  let probe: BreakerTicket | undefined;
+  const isProbe = (ticket: BreakerTicket | undefined): boolean =>
+    ticket !== undefined && ticket === probe;
+
+  const self: Breaker = {
+    name: options.name,
+    admit() {
+      if (current === 'closed') return CLOSED_TICKET;
+      if (current === 'open' && !lapsed()) return undefined;
+      // Past an open cooldown, or a probe that never settled: its holder may be dead.
+      if (current === 'half-open' && probe !== undefined && !lapsed()) return undefined;
+      move('half-open');
+      probe = { probe: true };
+      since = clock.monotonic();
+      return probe;
+    },
+    succeeded(ticket) {
+      // A late answer from a call admitted BEFORE the trip proves nothing about now: only a
+      // closed breaker or the half-open probe's own ticket may close it.
+      if (current === 'open' || (current === 'half-open' && !isProbe(ticket))) return;
+      count = 0;
+      probe = undefined;
+      move('closed');
+    },
+    failed(ticket) {
+      count += 1;
+      if (current === 'half-open' && isProbe(ticket)) {
+        probe = undefined;
+        since = clock.monotonic();
+        move('open');
+      } else if (current === 'closed' && count >= limit) {
+        since = clock.monotonic();
+        move('open');
+      }
+    },
+    released(ticket) {
+      if (isProbe(ticket)) probe = undefined;
+    },
+    state() {
+      return current === 'open' && lapsed() ? 'half-open' : current;
+    },
+    failures: () => count,
+    judge: (error) => classify(error),
+    refusal() {
+      const leftMs = Math.max(0, cooldownMs - (clock.monotonic() - since));
+      return breakerOpen(options.name, Math.max(1, Math.ceil(leftMs / 1_000)));
+    },
+    async run<T>(fn: () => Promise<T>): Promise<T> {
+      const ticket = self.admit();
+      if (ticket === undefined) throw self.refusal();
+      let value: T;
+      try {
+        value = await fn();
+      } catch (error) {
+        settleWith(self, self.judge(error), ticket);
+        throw error;
+      }
+      self.succeeded(ticket);
+      return value;
+    },
+  };
+  return self;
+}
+
+/** Record one verdict. Exported for a caller that classifies itself (`outbound()`). */
+export function settleWith(
+  gate: Breaker,
+  verdict: BreakerVerdict,
+  ticket: BreakerTicket | undefined,
+): void {
+  if (verdict === 'failure') gate.failed(ticket);
+  else if (verdict === 'success') gate.succeeded(ticket);
+  else gate.released(ticket);
+}

package/src/client-dispatch.ts

@@ -1,7 +1,7 @@
 /**
- * One dispatch of a `clientTransport` request: the `RequestInit`, the fence's abort for a read,
- * the network fault's code, and the ok/error split — nothing about how many times it happens
- * (the flight's) or what the answer means (the transport's).
+ * One dispatch of a `clientTransport` request — or of `clientStream`'s, whose body is handed back
+ * unread: the `RequestInit`, the fence's abort for a read, the network fault's code, and the
+ * ok/error split — nothing about how many times it happens (the flight's) or what it means.
  */
 
 import type { ClientFlight, ClientRetry } from './client-flight';
@@ -14,6 +14,7 @@ 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';
+import { noteRefusal } from './session-lost';
 import { DATES_HEADER } from './wire-dates';
 
 export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
@@ -21,6 +22,9 @@ 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';
 
+/** On a keyed answer: `1` when it was replayed from the first response, `0` when this call ran. */
+export const REPLAYED_HEADER = 'x-ultimate-replayed';
+
 /**
  * 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
@@ -105,22 +109,15 @@ export async function dispatch(
   const fence = read ? abortable([req.signal, flightSignal]) : undefined;
   const signal = fence === undefined ? req.signal : fence.signal;
   try {
-    const response = await onTheWire(req, read, () =>
+    const retryable = read || req.idempotencyKey !== undefined;
+    const response = await onTheWire(req, retryable, () =>
       (req.fetchImpl ?? browserFetch)(req.url, initOf(req, signal)),
     );
     await req.onResponse?.(response);
     // 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, stated) ??
-        problemError(response.status, text, req.url, stated)
-      );
-    }
+    const text =
+      response.status === 204 ? '' : await onTheWire(req, retryable, () => response.text());
+    if (!response.ok) throw refusalOf(req, response, text, issued);
     return {
       text,
       enveloped: response.headers.get(RECORDS_HEADER) === '1',
@@ -135,6 +132,68 @@ export async function dispatch(
   }
 }
 
+/** What `clientStream` sends: a write's request, never a raw body, a flight or a retry. */
+export type StreamDispatch = Pick<
+  TransportRequest,
+  | 'url'
+  | 'body'
+  | 'headers'
+  | 'signal'
+  | 'idempotencyKey'
+  | 'decodeError'
+  | 'onResponse'
+  | 'fetchImpl'
+>;
+
+/**
+ * A streamed answer's dispatch: the same `POST` init, credentials, outbound headers and refusal
+ * fence as `dispatch`, bounded by the caller's signal, and the 2xx `Response` handed back with
+ * its body UNREAD for the caller to consume frame by frame. A write, so no read fence, and never
+ * retryable — even keyed: a stream is not an idempotent replay.
+ */
+export async function dispatchStream(req: StreamDispatch): Promise<Response> {
+  const post: TransportRequest = {
+    ...req,
+    method: 'POST',
+    headers: { accept: 'text/event-stream', ...req.headers },
+  };
+  const issued = pageClient().scope.epoch;
+  const response = await onTheWire(post, false, () =>
+    (req.fetchImpl ?? browserFetch)(req.url, initOf(post, req.signal)),
+  );
+  await req.onResponse?.(response);
+  if (!response.ok) {
+    throw refusalOf(post, response, await onTheWire(post, false, () => response.text()), issued);
+  }
+  return response;
+}
+
+/**
+ * A non-2xx answer as the caller's refusal, noted against the session it was issued for: only
+ * that principal can have lost it. The answer's own URL, so a same-origin call redirected
+ * elsewhere is judged by where it was refused.
+ */
+function refusalOf(
+  req: TransportRequest,
+  response: Response,
+  text: string,
+  issued: number,
+): UltimateError {
+  const stated = retryAfterSecondsOf(
+    response.headers.get('retry-after'),
+    response.headers.get('date'),
+  );
+  const refusal =
+    req.decodeError?.(response.status, text, stated) ??
+    problemError(response.status, text, req.url, stated);
+  const scope = pageClient().scope;
+  if (scope.epoch === issued) {
+    const url = response.url === '' ? req.url : response.url;
+    noteRefusal({ status: response.status, url, code: refusal.code }, scope.principal);
+  }
+  return refusal;
+}
+
 /**
  * The network's half of a dispatch, and only that half. `fetch` — and a body read cut mid-stream —
  * rejects with a bare `TypeError` when no response arrived; that is `failure: 'network'`. A caller's
@@ -144,7 +203,7 @@ export async function dispatch(
  */
 async function onTheWire<T>(
   req: TransportRequest,
-  read: boolean,
+  retryable: boolean,
   work: () => Promise<T>,
 ): Promise<T> {
   try {
@@ -154,7 +213,7 @@ async function onTheWire<T>(
     throw transportFailed(
       'network',
       `${req.method} ${req.url} produced no response — the network refused or dropped it`,
-      read || req.idempotencyKey !== undefined ? 'retryable' : undefined,
+      retryable ? 'retryable' : undefined,
       { url: req.url, method: req.method },
       error,
     );

package/src/client-flight.ts

@@ -21,8 +21,8 @@ import { UltimateError } from './errors';
 import type { FlightGate, FlightGateLimits } from './flight-gate';
 import { flightGate } from './flight-gate';
 import { generationFence } from './generation-fence';
-import type { RetryPolicy } from './retry';
-import { retry } from './retry';
+import type { RetryPolicy } from './retry-loop';
+import { retryLoop } from './retry-loop';
 import type { Scheduler } from './single-flight';
 import { singleFlight } from './single-flight';
 
@@ -49,7 +49,7 @@ export const DEFAULT_CLIENT_RETRY: RetryPolicy = {
  * no response at all.
  *
  * The default is the OPPOSITE of `retryDecision`'s, one file over, and that is the point.
- * `retry.ts` sends a throw nobody classified again until the attempts run out — which for a
+ * `retry-loop.ts` sends a throw nobody classified again until the attempts run out — which for a
  * client means a caller's own `AbortError` and a `TypeError` out of a mapper both get retried.
  * `@ultimat3/ai` and `@ultimat3/db` each refused that executor outright over it; this predicate
  * keeps the executor and inverts the default instead, and is a parameter (`transient`) so an app
@@ -239,7 +239,7 @@ export function clientFlight(options: ClientFlightOptions = {}): ClientFlight {
     // it would replace a code, a cause and a runnable `fix:` with the fact that something retried.
     let stopped: { readonly error: unknown } | undefined;
     const sendAgain = transientFor(plan);
-    const answer = await retry<T | typeof STOPPED>(
+    const answer = await retryLoop<T | typeof STOPPED>(
       async (count) => {
         try {
           return await once(plan, signal, count);