@ultimat3/core 20.2.1 → 22.0.0

package/README.md

@@ -8,7 +8,6 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | `UltimateError`, the 3-line rendering, `--json` shape | `errors.ts` |
 | rendering an app's value into a `cause` / `fix` without throwing | `error-render.ts` |
 | code → `{ title, docs }` registry, `registerErrorCodes()` | `error-codes.ts` |
-| `Result<T, E>` for boundaries where throwing is wrong | `result.ts` |
 | the one lazy `AsyncLocalStorage`, every ambient scope in the framework | `async-context.ts` |
 | request context on that seam | `context.ts` |
 | `Actor` (`user \| service \| agent \| anonymous`) | `actor.ts` |
@@ -22,14 +21,23 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | whether an answer still applies — `X_SUPERSEDED` | `generation-fence.ts` |
 | the five composed into one typed-client call — dedup, fence, retry, deadline, ceiling | `client-flight.ts` |
 | what a typed client puts on the wire and reads back off it | `client-wire.ts` |
+| the ONE browser HTTP function — credentials, JSON, the error decode, records, the fence | `client-transport.ts` + `client-dispatch.ts` + `client-problem.ts` |
+| the ONE URL rule for actions and queries | `client-paths.ts` |
+| the records envelope an answer carries behind `x-ultimate-records: 1` | `record-envelope.ts` |
+| the per-tab page handle (`globalThis[Symbol.for('ultimate.client')]`) records land in | `record-sink.ts` |
+| which principal the page acts for, and the epoch that moves when it changes | `client-scope.ts` |
+| which row survives a conflict — `server-wins`, `last-write-wins`, `custom` | `conflict-policy.ts` |
+| the four shapes an async region can be in | `async-state.ts` |
 | is this `unknown` a keyed record? | `json-object.ts` |
 | typed env validated at boot | `env.ts` |
 | `.env.example` rendered from that schema, and its drift check | `env-example.ts` |
 | named environments + `ULTIMATE_ENV` resolution | `environment.ts` |
+| the boot refusal of a shipped dev signing secret outside development/test — `X_CURSOR_SECRET_DEV` | `dev-secrets.ts` |
 | a value that cannot be printed by accident | `secret.ts` |
 | the committed encrypted secrets envelope, AES-256-GCM | `secrets.ts` |
 | the two secrets files, and decrypted values → `defineEnv` | `secrets-store.ts` |
 | `defineConfig()` for `app.config.ts` | `config.ts` |
+| how overlays layer onto it — per section, key by key | `config-merge.ts` |
 | the `pwa` block — what an install needs, and the boot refusal when it is not there | `config-pwa.ts` |
 | the closed route vocabulary every renderer names | `route-vocabulary.ts` |
 | runtime roles + `ROLE` resolution | `roles.ts` |
@@ -47,6 +55,9 @@ Zero dependencies, zero `@ultimat3/*` imports.
 | the `/metrics` scrape body | `metrics-text.ts` |
 | the series every process emits, incl. what the chart scales on | `runtime-metrics.ts` |
 | graceful drain, `/healthz`, `/readyz` | `lifecycle.ts` |
+| the readiness grace between `/readyz` → 503 and the listener closing (`drain.readinessGraceMs`) | `lifecycle-grace.ts` |
+| SIGTERM/SIGINT → the one drain | `lifecycle-signals.ts` |
+| which network an IP literal belongs to — `classifyAddress`, for SSRF screens | `address-class.ts` |
 | the sockets this process opened, so a self-request is not egress | `listeners.ts` |
 | `defineService('orgs', …)` → `ctx.orgs`, rebuilt per actor | `service.ts` |
 | the registrar table one same-tier package reaches another through | `registrar.ts` |
@@ -157,6 +168,40 @@ Enforced, not documented: `x verify`'s `errors` step fails with `X_ERROR_RENDER_
 parameter typed `unknown` reaches a `cause:` or `fix:` through `JSON.stringify`, `String()` or a
 bare interpolation (`scripts/error-render.ts`).
 
+### Error classes
+
+Every error class `src/index.ts` exports, for `instanceof` inside one process. Across a wire or
+a job boundary the class is gone and the `code` is what survives — match on that.
+
+| Class | Code | Declared in |
+|---|---|---|
+| `ConfigInvalidError` | `X_CONFIG_INVALID` | `src/errors.ts` |
+| `CursorInvalidError` | `X_CURSOR_INVALID` | `src/cursor.ts` |
+| `CursorSecretDevError` | `X_CURSOR_SECRET_DEV` | `src/dev-secrets.ts` |
+| `EnvExampleDriftError` | `X_ENV_EXAMPLE_DRIFT` | `src/env-example.ts` |
+| `EnvironmentInvalidError` | `X_ENVIRONMENT_INVALID` | `src/environment.ts` |
+| `EnvMissingError` | `X_ENV_MISSING` | `src/errors.ts` |
+| `ErrorReporterDsnInvalidError` | `X_ERROR_REPORTER_DSN_INVALID` | `src/error-reporter-sentry.ts` |
+| `ImageDecodeFailedError` | `X_IMAGE_DECODE_FAILED` | `src/image/errors.ts` |
+| `ImageTooLargeError` | `X_IMAGE_TOO_LARGE` | `src/image/errors.ts` |
+| `ImageUnsupportedError` | `X_IMAGE_UNSUPPORTED` | `src/image/errors.ts` |
+| `InternalError` | `X_INTERNAL` | `src/errors.ts` |
+| `MetricCardinalityError` | `X_METRIC_CARDINALITY` | `src/metrics.ts` |
+| `MetricNameInvalidError` | `X_METRIC_NAME_INVALID` | `src/metric-names.ts` |
+| `MetricValueInvalidError` | `X_METRIC_VALUE_INVALID` | `src/metrics.ts` |
+| `NotImplementedError` | `X_NOT_IMPLEMENTED` | `src/errors.ts` |
+| `OtlpEndpointInvalidError` | `X_OTLP_ENDPOINT_INVALID` | `src/otlp.ts` |
+| `OtlpHeadersInvalidError` | `X_OTLP_HEADERS_INVALID` | `src/otlp.ts` |
+| `OtlpProtocolUnsupportedError` | `X_OTLP_PROTOCOL_UNSUPPORTED` | `src/otlp.ts` |
+| `SecretsFileInvalidError` | `X_SECRETS_FILE_INVALID` | `src/secrets-errors.ts` |
+| `SecretsFileMissingError` | `X_SECRETS_FILE_MISSING` | `src/secrets-errors.ts` |
+| `SecretsKeyInvalidError` | `X_SECRETS_KEY_INVALID` | `src/secrets-errors.ts` |
+| `SecretsKeyMismatchError` | `X_SECRETS_KEY_MISMATCH` | `src/secrets-errors.ts` |
+| `SecretsKeyMissingError` | `X_SECRETS_KEY_MISSING` | `src/secrets-errors.ts` |
+| `SecretsPlaintextInvalidError` | `X_SECRETS_PLAINTEXT_INVALID` | `src/secrets-errors.ts` |
+| `SecretsTamperedError` | `X_SECRETS_TAMPERED` | `src/secrets-errors.ts` |
+| `UltimateError` | any registered code — every class in the framework extends it | `src/errors.ts` |
+
 ## Context
 
 ```ts
@@ -562,6 +607,22 @@ cause and a runnable `fix:` with the fact that something was retried, which no r
 `classifyThrown` and `statedDelayMs` live in `error-retry.ts`, one import away from the table they
 read; `@ultimat3/jobs` re-exports both rather than keeping a second pair.
 
+## One browser seam — transport, records, page handle, principal fence
+
+| Export | The one answer | The question it settles |
+|---|---|---|
+| `clientTransport({ method, url, body?, rawBody?, headers?, signal?, idempotencyKey?, flight?, fresh?, retry?, onResponse?, decodeError?, onEnvelope?, fetchImpl? })` | every browser request | `credentials: 'same-origin'`, JSON in and out, the `idempotency-key` header, a non-2xx `problem+json` back into the server's code (`meta.origin: 'remote'`) unless `decodeError` answers first, a network `TypeError` into `X_CLIENT_TRANSPORT_FAILED`. A GET is abortable on `rescope()` and deduped only when a `flight` is passed (`fresh` refuses to join); any other method is never deduped and never aborted by the fence. `rawBody` goes out verbatim with no default header and resolves `undefined`. `onResponse` sees headers before the body is read. `onEnvelope` sees the decoded records envelope after adoption — the one way to learn the order of `records[type]`. `fetchImpl` defaults to `globalThis.fetch`, read at call time |
+| `actionPath(name)`, `actionRoute(name)`, `queryPath(name)`, `QUERY_PATH_PREFIX`, `splitWords`, `pluralize` | the one URL rule | `publishPost` → `/api/posts/publish`, `liveFeed` → `/_x/query/live-feed`. Tier 0 so `action`, `query` and `realtime` derive one URL with no sideways import |
+| `RECORDS_HEADER`, `encodeRecordEnvelope`, `decodeRecordEnvelope`, `RecordRows` | `{ data, records?: { [type]: { [key]: Row } }, removed?: { [type]: key[] } }`, only behind `x-ultimate-records: 1` | how an answer carries entity rows without changing the wire of an answer that has none. A malformed envelope is `X_CLIENT_RECORD_ENVELOPE_INVALID` |
+| `pageClient()` → `{ store, socket, scope }`, `RecordSink` | one handle per TAB, not per module copy | every island bundle carries its own core; the handle lives on `globalThis` under one `Symbol.for` key so all of them resolve the same store. No store installed = records dropped |
+| `rescope(principal)`, `onRescope(fn)`, `isSuperseded(error)` | the principal fence | a principal change bumps the epoch and notifies synchronously; reads in flight reject `X_CLIENT_SCOPE_CHANGED`, writes complete but their records are not adopted. `isSuperseded` answers true for it and for `X_SUPERSEDED` |
+| `resolveConflict(policy, local, server, { clockField? })`, `ConflictPolicy`, `Row` | one conflict vocabulary, over ROWS | `last-write-wins` keeps the local row only when its numeric clock field (default `updatedAt`) is newer; no provable clock = the server's row |
+| `AsyncState<T>` | `pending \| refreshing \| ready \| failed` | the type `realtime` produces and `ui` renders; tier 0 because neither may import the other |
+
+`clientTransport` does not value-import `createClientFlight` or `traceHeaders()` — measured sizes
+are in its file header. A server-side caller that propagates a trace passes `traceHeaders()` in
+`headers` itself.
+
 ## One image pipeline, everywhere
 
 ```ts

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@ultimat3/core",
-  "version": "20.2.1",
+  "version": "22.0.0",
   "description": "Ultimate's foundation: errors, context, env, config, clock, ids, logging, telemetry, lifecycle",
   "license": "MIT",
   "type": "module",
   "sideEffects": [
     "./src/context.ts",
+    "./src/core-error-codes.ts",
     "./src/lifecycle-errors.ts",
     "./src/schema-error-codes.ts",
     "./src/secrets-errors.ts"
@@ -20,11 +21,13 @@
     "provenance": true
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./page": "./src/page.ts"
   },
   "files": [
     "src",
     "!src/**/*.test.ts",
+    "!src/**/*-fixture.ts",
     "CLAUDE.md",
     "README.md",
     "LICENSE"
@@ -37,6 +40,6 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/schema": "20.2.1"
+    "@ultimat3/schema": "22.0.0"
   }
 }

package/src/actor.ts

@@ -105,6 +105,14 @@ export interface Actor {
    * one the customer issued. Every surface that renders an actor renders this with it.
    */
   readonly onBehalfOf?: ActorOrigin | undefined;
+  /**
+   * The actor's SAVED language and IANA zone — the `user` rung of `@ultimat3/i18n`'s
+   * `resolveLocale` and `@ultimat3/time`'s `resolveTimeZone`. Whoever authenticates sets them from
+   * the user record; `@ultimat3/http` re-resolves `ctx.locale` / `ctx.tz` with them once the actor
+   * is known, so a cookie the reader chose still wins exactly where those owners say it does.
+   */
+  readonly locale?: string | undefined;
+  readonly tz?: string | undefined;
 }
 
 export interface ActorInit {
@@ -117,6 +125,9 @@ export interface ActorInit {
   readonly facts?: ActorFactMap | undefined;
   /** For a session that already recorded an impersonation; `impersonate()` sets it otherwise. */
   readonly onBehalfOf?: ActorOrigin | undefined;
+  /** Saved preferences — see `Actor.locale`. */
+  readonly locale?: string | undefined;
+  readonly tz?: string | undefined;
 }
 
 const NO_FACTS: ActorFactMap = Object.freeze({});
@@ -143,6 +154,9 @@ function build(kind: ActorKind, init: ActorInit): Actor {
     permissions: Object.freeze([...(init.permissions ?? [])]),
     facts: Object.freeze({ ...init.facts }),
     onBehalfOf: init.onBehalfOf === undefined ? undefined : Object.freeze({ ...init.onBehalfOf }),
+    // Absent keys, not `undefined` ones: an actor is compared and serialised in tests and logs.
+    ...(init.locale === undefined ? {} : { locale: init.locale }),
+    ...(init.tz === undefined ? {} : { tz: init.tz }),
   });
 }
 

package/src/address-class.ts

@@ -0,0 +1,143 @@
+// Single responsibility: which kind of network an IP address literal belongs to. Tier 0 because the
+// SSRF screens that need it sit in packages that may not import each other — `@ultimat3/jobs`'
+// webhook delivery (tier 3) and `@ultimat3/scraping` (tier 5) — and a copy per screen is how one
+// of them comes to miss `::ffff:127.0.0.1`.
+
+/**
+ * `reserved` is every range that is neither a host network nor public: multicast, broadcast,
+ * `240.0.0.0/4`, the documentation and benchmarking nets. A screen allowing only `public` refuses
+ * all of them, which is the point of naming them rather than calling them public.
+ */
+export type AddressClass =
+  | 'loopback'
+  | 'private'
+  | 'link-local'
+  | 'ula'
+  | 'cgnat'
+  | 'unspecified'
+  | 'reserved'
+  | 'public';
+
+/** `[network, prefixBits]` over the 32-bit value; ordered, first match wins. */
+const V4_RULES: readonly (readonly [number, number, AddressClass])[] = [
+  [0x00000000, 8, 'unspecified'],
+  [0x7f000000, 8, 'loopback'],
+  [0x0a000000, 8, 'private'],
+  [0xac100000, 12, 'private'],
+  [0xc0a80000, 16, 'private'],
+  [0xa9fe0000, 16, 'link-local'],
+  [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
+  [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
+  [0xe0000000, 4, 'reserved'], // multicast
+  [0xf0000000, 4, 'reserved'], // 240.0.0.0/4 and the broadcast address inside it
+];
+
+/**
+ * Strict dotted quad: four decimal octets, no leading zero. `010.0.0.1` is octal to some parsers
+ * and decimal to others, so it is not an address this module will vouch for — a screen that
+ * refuses what it cannot classify is the only safe reader of it.
+ */
+function parseV4(text: string): number | undefined {
+  const parts = text.split('.');
+  if (parts.length !== 4) return undefined;
+  let value = 0;
+  for (const part of parts) {
+    if (!/^(?:0|[1-9]\d{0,2})$/.test(part)) return undefined;
+    const octet = Number(part);
+    if (octet > 255) return undefined;
+    value = value * 256 + octet;
+  }
+  return value;
+}
+
+function classifyV4(value: number): AddressClass {
+  for (const [network, bits, kind] of V4_RULES) {
+    const size = 2 ** (32 - bits);
+    if (value >= network && value < network + size) return kind;
+  }
+  return 'public';
+}
+
+/** Eight 16-bit groups, or `undefined`. A trailing dotted quad fills the last two. */
+function parseV6(text: string): readonly number[] | undefined {
+  let body = text;
+  let tail: number[] = [];
+  const lastColon = body.lastIndexOf(':');
+  if (body.includes('.', lastColon)) {
+    const v4 = parseV4(body.slice(lastColon + 1));
+    if (v4 === undefined) return undefined;
+    tail = [Math.floor(v4 / 0x10000), v4 % 0x10000];
+    // `::ffff:1.2.3.4` keeps `::ffff`; `::1.2.3.4` keeps its `::`, the one colon that is syntax.
+    const head = body.slice(0, lastColon + 1);
+    body = head.endsWith('::') ? head : head.slice(0, -1);
+  }
+  const halves = body.split('::');
+  if (halves.length > 2) return undefined;
+  const groups = (half: string): number[] | undefined => {
+    if (half === '') return [];
+    const out: number[] = [];
+    for (const group of half.split(':')) {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return undefined;
+      out.push(Number.parseInt(group, 16));
+    }
+    return out;
+  };
+  const head = groups(halves[0] ?? '');
+  const rest = halves.length === 2 ? groups(halves[1] ?? '') : [];
+  if (head === undefined || rest === undefined) return undefined;
+  const width = head.length + rest.length + tail.length;
+  if (halves.length === 1) return width === 8 ? [...head, ...tail] : undefined;
+  if (width > 7) return undefined;
+  return [...head, ...new Array<number>(8 - width).fill(0), ...rest, ...tail];
+}
+
+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));
+  if (g[0] === 0x64 && g[1] === 0xff9b && g.slice(2, 6).every((group) => group === 0)) {
+    return classifyV4(embeddedV4(g));
+  }
+  const first = g[0] ?? 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
+
+  return 'public';
+}
+
+/**
+ * The class of an IP address LITERAL — IPv4, IPv6, bracketed `[::1]`, a zone id `fe80::1%eth0`,
+ * and every IPv6 form carrying an IPv4 address. `undefined` means "not an address literal": a
+ * hostname must be resolved first and each resolved address classified, never this string.
+ */
+export function classifyAddress(address: string): AddressClass | undefined {
+  let text = address.trim();
+  if (text.startsWith('[') && text.endsWith(']')) text = text.slice(1, -1);
+  const zone = text.indexOf('%');
+  if (zone !== -1 && text.includes(':')) text = text.slice(0, zone);
+  if (text.includes(':')) {
+    const groups = parseV6(text);
+    return groups === undefined ? undefined : classifyV6(groups);
+  }
+  const v4 = parseV4(text);
+  return v4 === undefined ? undefined : classifyV4(v4);
+}
+
+/** 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/async-state.ts

@@ -0,0 +1,19 @@
+/**
+ * The four shapes an async region can be in — pending, refreshing, ready, failed. Tier 0 because
+ * every client layer produces or consumes one: `@ultimat3/realtime`'s `useQuery` returns it (tier 3)
+ * and `@ultimat3/ui`'s `asyncBranch` renders it (tier 4), and neither may import the other's way.
+ */
+
+/**
+ * A STATE, never a query: a live-query accessor, a `createResource` and a plain signal all arrive
+ * at a region as the same four shapes.
+ *
+ * `refreshing` is the one that makes search feel fast — it CARRIES the previous data, so a refetch
+ * re-renders what is already on screen instead of tearing it down to a skeleton. `pending` holds
+ * no data, which is what makes "no results" before the first answer unconstructible.
+ */
+export type AsyncState<T> =
+  | { readonly status: 'pending' }
+  | { readonly status: 'refreshing'; readonly data: T }
+  | { readonly status: 'ready'; readonly data: T }
+  | { readonly status: 'failed'; readonly error: unknown };

package/src/canonical-json.ts

@@ -50,6 +50,27 @@ function hashCollection(value: Map<unknown, unknown> | Set<unknown>): string {
   return `${value instanceof Map ? 'Map' : 'Set'}(${entries.sort().join(',')})`;
 }
 
+/** Lowercase hex, two digits a byte. Not `toBase64`: this module ships to browsers that lack it. */
+function hexOf(bytes: Uint8Array): string {
+  let out = '';
+  for (const byte of bytes) out += byte.toString(16).padStart(2, '0');
+  return out;
+}
+
+/**
+ * Tagged, because a typed array's indices ARE own enumerable keys: `Uint8Array([1])` rendered
+ * `{"0":1}`, one key with the plain object `{ 0: 1 }`. The view's OWN window is read, never the
+ * whole backing buffer, and any view but a `Uint8Array` carries its type name — a `Uint16Array([1])`
+ * and a `Uint8Array([1, 0])` hold the same bytes and are different payloads.
+ */
+function hashBytes(value: ArrayBuffer | ArrayBufferView): string {
+  if (value instanceof ArrayBuffer) return `ArrayBuffer(${hexOf(new Uint8Array(value))})`;
+  const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  const tag =
+    value instanceof Uint8Array ? 'Bytes' : Object.prototype.toString.call(value).slice(8, -1);
+  return `${tag}(${hexOf(bytes)})`;
+}
+
 /**
  * JSON with object keys sorted at every depth, and every value a JSON document would fold onto
  * `null` or `{}` given a token of its own. No timestamps, no insertion-order leaks.
@@ -64,7 +85,8 @@ export function canonicalJson(value: unknown): string {
     case 'boolean':
       return String(value);
     case 'bigint':
-      return JSON.stringify(`${value}n`);
+      // A bare token like `Date(…)`: quoted as `"5n"`, it was one key with the STRING `'5n'`.
+      return `BigInt(${value})`;
     case 'undefined':
     case 'function':
     case 'symbol':
@@ -77,6 +99,7 @@ export function canonicalJson(value: unknown): string {
   // every set alike.
   if (value instanceof Date) return hashDate(value);
   if (value instanceof Map || value instanceof Set) return hashCollection(value);
+  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return hashBytes(value);
   if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
   const record = value as Record<string, unknown>;
   const keys = Object.keys(record)

package/src/client-dispatch.ts

@@ -0,0 +1,163 @@
+/**
+ * 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).
+ */
+
+import type { ClientFlight, ClientRetry } from './client-flight';
+import { problemError, transportFailed } from './client-problem';
+import { onRescope } from './client-scope';
+import { scopeChanged } from './client-scope-error';
+import type { UltimateError } from './errors';
+import type { RecordEnvelope } from './record-envelope';
+import { RECORDS_HEADER } from './record-envelope';
+import { outboundSlot, pageClient } from './record-sink';
+
+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';
+
+export interface TransportRequest {
+  readonly method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  readonly url: string;
+  /** JSON-encoded, with `content-type: application/json`. */
+  readonly body?: unknown;
+  /**
+   * Sent VERBATIM instead of `body` — bytes to a signed URL. No default header is added (a signed
+   * request may cover them), and the answer is not decoded: the call resolves `undefined`.
+   */
+  readonly rawBody?: BodyInit | undefined;
+  /** Spread LAST, so an explicit value wins over every default. */
+  readonly headers?: Readonly<Record<string, string>> | undefined;
+  readonly signal?: AbortSignal | undefined;
+  readonly idempotencyKey?: string | undefined;
+  /** Dedup, retry, deadline and a concurrency ceiling — opt-in; a read dedupes only with one. */
+  readonly flight?: ClientFlight | undefined;
+  /** Refuse to join a read that left before this call did. Meaningful only with a `flight`. */
+  readonly fresh?: boolean | undefined;
+  /** This call's retry override, handed to the `flight`. */
+  readonly retry?: ClientRetry | undefined;
+  /**
+   * The decoded records envelope, after its records were adopted — only when the answer carried
+   * `x-ultimate-records: 1` and belongs to the current principal. What a caller reads to know the
+   * ORDER of `records[type]`, which the store (keyed, unordered) cannot give it back.
+   */
+  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;
+  /** Default `globalThis.fetch`, read at call time — never captured at module scope. */
+  readonly fetchImpl?: FetchLike | undefined;
+}
+
+/** One dispatch's answer: immutable TEXT, so a deduped read's joiners each parse their own. */
+export interface Answer {
+  readonly text: string;
+  readonly enveloped: boolean;
+}
+
+/** Called, never captured: a browser's `fetch` throws `Illegal invocation` when detached. */
+const browserFetch: FetchLike = (input, init) => globalThis.fetch(input, init);
+
+export async function dispatch(
+  req: TransportRequest,
+  read: boolean,
+  issued: number,
+  flightSignal: AbortSignal | undefined,
+): Promise<Answer> {
+  // A read gets its own controller so the fence can abort it; a write never does, and only its
+  // caller's own signal reaches it (a flight never hands a write one).
+  const fence = read ? abortable([req.signal, flightSignal]) : undefined;
+  const signal = fence === undefined ? req.signal : fence.signal;
+  try {
+    const response = await onTheWire(req, read, () =>
+      (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) {
+      throw (
+        req.decodeError?.(response.status, text) ?? problemError(response.status, text, req.url)
+      );
+    }
+    return { text, enveloped: response.headers.get(RECORDS_HEADER) === '1' };
+  } catch (error) {
+    const current = pageClient().scope.epoch;
+    if (read && current !== issued) throw scopeChanged(req.url, issued, current);
+    throw error;
+  } finally {
+    fence?.release();
+  }
+}
+
+/**
+ * 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
+ * `onResponse` or `decodeError` throwing a `TypeError` is a bug in the caller, and classifying it
+ * as the network made it retryable, so a flight re-sent the request for it. An abort is a decision
+ * and passes through untouched.
+ */
+async function onTheWire<T>(
+  req: TransportRequest,
+  read: boolean,
+  work: () => Promise<T>,
+): Promise<T> {
+  try {
+    return await work();
+  } catch (error) {
+    if (!(error instanceof TypeError)) throw error;
+    throw transportFailed(
+      'network',
+      `${req.method} ${req.url} produced no response — the network refused or dropped it`,
+      read || req.idempotencyKey !== undefined ? 'retryable' : undefined,
+      { url: req.url, method: req.method },
+      error,
+    );
+  }
+}
+
+function initOf(req: TransportRequest, signal: AbortSignal | undefined): RequestInit {
+  const raw = req.rawBody !== undefined;
+  const headers: Record<string, string> = raw ? {} : { accept: 'application/json' };
+  if (req.body !== undefined && !raw) headers['content-type'] = 'application/json';
+  if (req.idempotencyKey !== undefined) headers[IDEMPOTENCY_HEADER] = req.idempotencyKey;
+  const body = raw ? req.rawBody : req.body === undefined ? undefined : JSON.stringify(req.body);
+  // Server-side only: the slot is filled by `runWithContext`/`startSpan` (`outbound-headers.ts`),
+  // and a signed raw upload never carries it — an extra header can break the signature.
+  const outbound = raw ? undefined : outboundSlot().outboundHeaders?.();
+  return {
+    method: req.method,
+    credentials: 'same-origin',
+    headers: { ...headers, ...outbound, ...req.headers },
+    ...(body === undefined ? {} : { body }),
+    ...(signal === undefined ? {} : { signal }),
+  };
+}
+
+/**
+ * A read's controller: aborted by `rescope()`, by the caller's signal or by the flight's. Every
+ * listener comes off in `release`, so a long-lived caller signal does not collect one per request.
+ */
+function abortable(sources: readonly (AbortSignal | undefined)[]): {
+  readonly signal: AbortSignal;
+  release(): void;
+} {
+  const controller = new AbortController();
+  const detach: (() => void)[] = [onRescope(() => controller.abort())];
+  for (const source of sources) {
+    if (source === undefined) continue;
+    if (source.aborted) controller.abort(source.reason);
+    const forward = (): void => controller.abort(source.reason);
+    source.addEventListener('abort', forward, { once: true });
+    detach.push(() => source.removeEventListener('abort', forward));
+  }
+  return {
+    signal: controller.signal,
+    release: (): void => {
+      for (const off of detach) off();
+    },
+  };
+}

package/src/client-flight.ts

@@ -61,6 +61,12 @@ export function isTransientFailure(error: unknown): boolean {
   return isNetworkRejection(error);
 }
 
+/** Only a classification somebody declared — for work that already classified its own wire. */
+function isDeclaredTransient(error: unknown): boolean {
+  const declared = classifyThrown(error);
+  return declared !== undefined && declared !== 'terminal';
+}
+
 /**
  * A dispatch that never produced a response. `fetch` rejects with a plain `TypeError` when the
  * network is down, DNS fails or the connection drops mid-body — the one unclassified throw a
@@ -89,6 +95,13 @@ export interface FlightPlan<T> {
   run(signal: AbortSignal | undefined, attempt: number): Promise<T>;
   /** Overrides the flight's policy for this one call. */
   readonly retry?: ClientRetry | undefined;
+  /**
+   * `true` when `run` already turns every wire failure into a classified error, as
+   * `clientTransport` does. An UNclassified throw is then the caller's own — a hook's `TypeError`
+   * — and is never sent again, where the default would read it as a network rejection. A
+   * flight-wide `transient` still wins: that is the app's own answer.
+   */
+  readonly classified?: boolean | undefined;
 }
 
 export interface ClientFlightOptions {
@@ -151,6 +164,8 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
         schedule(done, ms);
       }));
   const transient = options.transient ?? isTransientFailure;
+  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 gate: FlightGate | undefined =
@@ -169,12 +184,13 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
     // and a foreign `TypeError` again. The original value is rethrown below, unwrapped — wrapping
     // 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>(
       async (count) => {
         try {
           return await plan.run(signal, count);
         } catch (error) {
-          if (transient(error)) throw error;
+          if (sendAgain(error)) throw error;
           stopped = { error };
           return STOPPED;
         }
@@ -259,8 +275,11 @@ export function createClientFlight(options: ClientFlightOptions = {}): ClientFli
       const work = (): Promise<T> =>
         gate === undefined ? dispatch(plan) : gate.run(() => dispatch(plan));
       // The single flight sits OUTSIDE the gate: a joiner takes no slot, so dedup relieves the
-      // ceiling instead of queueing behind it.
-      return settle(plan.key === undefined ? work() : flights.run(plan.key, work), issued);
+      // 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
+      // in that window joined the aborted one and was answered with its AbortError.
+      const key = plan.key === undefined ? undefined : JSON.stringify([issued, plan.key]);
+      return settle(key === undefined ? work() : flights.run(key, work), issued);
     },
 
     get inflight(): number {