@ultimat3/core 20.2.1 → 21.0.0

package/CLAUDE.md

@@ -13,12 +13,12 @@ is a change to every package.
 | Rendering the 3-line format | nothing to remember — `UltimateError`'s CONSTRUCTOR escapes `code`, `title`, `cause`, `fix` and `docs` with `singleLine()`. Call it yourself only when you render a shape this class never built, e.g. a `Finding` |
 | A value a CALLER supplied | `describeValue()` — shape, never content. `renderCauseValue` is safe against throwing, not against leaking |
 | Reading a caught value | `renderThrowable()` / `isThrownError()` / `stringField()`; never `error.message`, `error instanceof Error` or `typeof error.code === 'string'` directly — the probe throws before the renderer runs |
-| New code | add to `CORE_CODE_TITLES` in `error-codes.ts`, else the title is auto-humanised |
+| New code | add to `CORE_CODE_TITLES` in `core-error-codes.ts` — a side-effect anchor the barrel bare-imports, so `UltimateError` alone (2,353 B, from 5,265 B) never carries the table; an untitled code renders humanised |
 | Where an error points | `ERROR_DOCS_URL` — one constant, never a per-code URL. `docs:` is omitted at every construction site and resolved from the registry |
 | Time | take a `Clock`; `Date.now()` / `new Date()` only inside `clock.ts` |
 | Context | never thread `ctx` as a parameter — `useContext()` |
 | A value ambient across an `await` | `asyncContext<T>(subject)` from `async-context.ts`, in **every** package — never `new AsyncLocalStorage` |
-| Exports | add to `src/index.ts` explicitly; no `export *`. Three subjects that each span a dozen modules arrive through `src/exports/` — every name is still written out in `index.ts`, so the public surface is one file to read |
+| Exports | add to `src/index.ts` explicitly; no `export *`. ONE subpath, `@ultimat3/core/page` (`src/page.ts`): the page handle, the principal fence and the page's shared names, re-exported by the barrel too — a browser module imports them there because any barrel import retains the error registry (~7.6 kB) through the anchored `schema-error-codes.ts`. `page-bundle.test.ts` pins the retained module set and the 1.5 kB ceiling; nothing that constructs an error may join it. Three subjects that each span a dozen modules arrive through `src/exports/` — every name is still written out in `index.ts`, so the public surface is one file to read |
 | Files | < 200 LOC, 500 hard ceiling, one responsibility, `kebab-case.ts`, test beside source |
 | Type claims | `type-pins.ts`, never a `.test.ts` — `tsconfig.json` excludes tests, so `tsc` never reads one |
 
@@ -136,6 +136,10 @@ shape against a locally declared sample interface for exactly that reason.
 | which HTTP statuses are worth repeating | `retryable-status.ts` | `>= 500` plus 408, 409, 425, 429 — the two byte-identical copies' set |
 | how long this request has left | `request-budget.ts` (`Ctx.deadlineAt`, `REQUEST_TIMEOUT_HEADER`) | `@ultimat3/http`'s `startDeadline` is the one production writer of the instant; `traceHeaders()` is the one writer of the header. It lives here because the READER is tier 2 and the WRITER is a typed client in tier 0, and a second literal for the header name is a propagation that stops working the day either string is edited. A spent budget sends nothing rather than `0` — the far side ignores anything under 1ms and falls back to its own, which is the failure the header exists to prevent, one hop later |
 | the five above, composed into one typed-client call | `client-flight.ts` + `client-wire.ts` | `@ultimat3/action` and `@ultimat3/query` both project a typed client and are both tier 3, so neither could import the other: it shipped as a byte-identical 288-line + 85-line copy in each, policed by a `client-twin.test.ts` in both. Both packages re-export these names, so their public surface is unchanged. Declares NO code of its own — `X_SUPERSEDED`, `X_TIMEOUT` and `X_FLIGHT_GATE_OVERLOADED` are already here |
+| the browser's one HTTP function, its records envelope, the per-tab handle and the principal fence | `client-transport.ts`, `client-dispatch.ts`, `client-problem.ts`, `client-paths.ts`, `record-envelope.ts`, `record-sink.ts`, `client-scope.ts` | plan 101, 21.0.0. `pageClient()` is the ONE `globalThis` write (`Symbol.for('ultimate.client')`) — a module-scope singleton would be one store per island bundle, which `record-sink.test.ts` reproduces by importing the module twice. The scope's listeners live ON the handle for the same reason. `clientTransport` must never value-import `createClientFlight` or `traceHeaders()` (sizes in its header). `isSuperseded` answers both `X_SUPERSEDED` and `X_CLIENT_SCOPE_CHANGED` — one reader, never a second predicate. The fence does NOT `bump()` a caller's flight: a flight's fence refuses writes too, and a write across a rescope must resolve. A write never dedupes, idempotency key or not; a read dedupes only with a caller's `flight` — there is no default flight, decided 2026-09-22. Trace and budget headers reach the transport through an OUTBOUND SLOT on the page handle that `runWithContext` and `startSpan` fill (`outbound-headers.ts`) — never a `traceHeaders()` call in a client: that put 12.9 kB of telemetry/context/logger into every island for a header a browser never has. Measured browser-minified through the barrel, As of 2026-09-22, before → after the slot: `clientTransport` 13,328 → 13,571 B, `pageClient` 7,964 → 8,139 B; re-measured As of 2026-09-23 (one entry importing `packages/core/src/index.ts` by path): 14,405 B and 8,853 B. `rpc`'s figures live in ONE table, [`packages/action/CLAUDE.md`](../action/CLAUDE.md) (the `ClientFlight` bullet), and `queryClient`'s in [`packages/query/CLAUDE.md`](../query/CLAUDE.md) — never restated here. The floor under all of them is the error-code registry (~7.6 kB) the anchored `schema-error-codes.ts` pulls into ANY barrel import; `pageClient` from its own module is 332 B. `pageClient()` reads its initial principal from `<meta name="ultimate-scope">` (`CLIENT_SCOPE_META`, which `@ultimat3/render` imports) once, at creation — THREE states: content = that principal, empty = `null` (anonymous), no tag or no `document` = `undefined` (UNSCOPED: a page rendered for nobody; nothing is persisted under it) |
+| a write's public name | `write-digest.ts` (`writeDigest`, `isWriteDigest`, on `./page` too) + `write-origin.ts` (`withWriteOrigin`, `currentWriteOrigin`, `WRITE_ORIGIN_WAL_PREFIX`, server-only) | the SHA-256 of an idempotency key, 32 hex. `@ultimat3/action`'s HTTP projection opens the scope, `@ultimat3/entity` carries it onto a row change and into the WAL, `@ultimat3/realtime` stamps it on a `records` frame and the page matches its own. Tier 0 because all four read it and none may import another. A malformed value runs the work unnamed: the scope is a label, never a gate |
+| which row survives a conflict | `conflict-policy.ts` (`ConflictPolicy`, `resolveConflict`, `Row`) | the one vocabulary `action`'s mutator and `realtime`'s rebase both read |
+| the four shapes of an async region | `async-state.ts` (`AsyncState`) | moved from `@ultimat3/ui`; tier 0 so `realtime` can return it and `ui` can render it |
 | is this `unknown` a keyed record? | `json-object.ts` | `isJsonObject`, which was the same three terms in both those packages' `stable.ts`. A `Date` and a class instance PASS: it narrows a shape, it does not certify provenance |
 | a value that must not be printed | `secret.ts` | redacted by VALUE; `revealSecret()` is the one way out, on purpose greppable |
 | an `Intl` formatter cache, and the screen in front of it | `intl-cache.ts` (`cachedFormatter`, `canonicalLocale`, `assertLocale`, `MAX_CACHED_FORMATTERS`, `MAX_LOCALE_EXCERPT`) | a locale and a zone arrive from a request header, so the tag must be REFUSED when it is not a tag (`X_LOCALE_INVALID`), the key must be canonical AND the cache bounded — never a second copy of any of the three. The refusal is bounded too: the `cause` quotes back at most `MAX_LOCALE_EXCERPT` (35, RFC 5646 §4.4.1) code points and says so when it cut, and the whole tag rides in `meta.locale` — a `cause` reaches the 400 body and the log line, where a value with no key has nothing a redactor can address |

package/README.md

@@ -22,6 +22,13 @@ 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` |
@@ -562,6 +569,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": "21.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": "21.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/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/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;
         }

package/src/client-paths.ts

@@ -0,0 +1,79 @@
+/**
+ * The ONE URL rule for the two HTTP primitives: an action's export name derives `POST
+ * /api/<resource>/<verb>`, a query's derives `GET /_x/query/<kebab>`. Tier 0 and pure string math,
+ * so `action`, `query` and `realtime` (all tier 3) derive the same URL with no sideways import and
+ * a browser bundle pays a few hundred bytes for it. Moved verbatim from both packages' `naming.ts`.
+ */
+
+/** Irregular plurals we actually hit in domain models. A `Map`: the key is a caller's word. */
+const IRREGULAR: ReadonlyMap<string, string> = new Map([
+  ['person', 'people'],
+  ['child', 'children'],
+  ['man', 'men'],
+  ['woman', 'women'],
+  ['datum', 'data'],
+  ['index', 'indexes'],
+  ['entry', 'entries'],
+]);
+
+/** Every read is served under one prefix, so a router can claim it in one rule. */
+export const QUERY_PATH_PREFIX = '/_x/query';
+
+export interface ActionRoute {
+  /** First camelCase word, kebab-cased. `publishPost` -> `publish`. */
+  readonly verb: string;
+  /** Remaining words, last one pluralized, kebab-cased. `publishPost` -> `posts`. */
+  readonly resource: string;
+  /** `/api/<resource>/<verb>`. */
+  readonly path: string;
+}
+
+/** camelCase / PascalCase / SCREAMING_SNAKE -> lowercase words. */
+export function splitWords(name: string): string[] {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .split(/[\s_-]+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.toLowerCase());
+}
+
+/**
+ * Naive-on-purpose English pluralizer. A word that already ends in `s` is left alone, so
+ * `publishPosts` and `publishPost` agree on the `posts` resource.
+ */
+export function pluralize(word: string): string {
+  const irregular = IRREGULAR.get(word);
+  if (irregular !== undefined) return irregular;
+  if (word.endsWith('s')) return word;
+  if (/(x|z|ch|sh)$/.test(word)) return `${word}es`;
+  if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+  return `${word}s`;
+}
+
+/**
+ * `publishPost` -> `/api/posts/publish`, `updateUserProfile` -> `/api/user-profiles/update`,
+ * `checkout` -> `/api/checkouts/invoke` (single-word fallback).
+ */
+export function actionRoute(name: string): ActionRoute {
+  const words = splitWords(name);
+  const head = words[0] ?? 'invoke';
+  if (words.length < 2) {
+    const resource = pluralize(head);
+    return { verb: 'invoke', resource, path: `/api/${resource}/invoke` };
+  }
+  const nouns = words.slice(1);
+  const last = nouns[nouns.length - 1] ?? head;
+  const resource = [...nouns.slice(0, -1), pluralize(last)].join('-');
+  return { verb: head, resource, path: `/api/${resource}/${head}` };
+}
+
+/** The path an action is POSTed to — `actionRoute(name).path`. */
+export function actionPath(name: string): string {
+  return actionRoute(name).path;
+}
+
+/** `liveFeed` -> `/_x/query/live-feed`, read with `GET …?orgId=…`. */
+export function queryPath(name: string): string {
+  return `${QUERY_PATH_PREFIX}/${splitWords(name).join('-')}`;
+}

package/src/client-problem.ts

@@ -0,0 +1,94 @@
+/**
+ * A browser request's failure, as the error it is: a non-2xx `problem+json` answer back into the
+ * `UltimateError` the server threw, and a dispatch that produced no usable answer into
+ * `X_CLIENT_TRANSPORT_FAILED`. The one decoder `clientTransport` owns, so every client surface
+ * reads a failure off the wire the same way.
+ */
+
+import { FRAMEWORK_CODE, problemOf, retryForStatus } from './client-wire';
+import { renderFixShellArg } from './error-render';
+import type { ErrorRetry } from './error-retry';
+import { UltimateError } from './errors';
+import { isJsonObject } from './json-object';
+
+/** An absolute HTTP(S) link, or nothing: a server's `docs` is data and may be `javascript:`. */
+const HTTP_URL = /^https?:\/\/[^\s]+$/;
+
+/**
+ * A non-2xx answer. A body naming a framework code IS the server's error, carried verbatim and
+ * marked `origin: 'remote'` — the code may be one this bundle never registered. Anything else is
+ * a proxy or a gateway answering instead of the app.
+ */
+export function problemError(status: number, text: string, url: string): UltimateError {
+  const body = problemOf(text);
+  const code = body['code'];
+  if (typeof code !== 'string' || !FRAMEWORK_CODE.test(code)) {
+    return transportFailed(
+      'status',
+      `${url} answered HTTP ${status} without a problem+json body naming a framework code`,
+      retryForStatus('X_CLIENT_TRANSPORT_FAILED', status),
+      { url, status },
+    );
+  }
+  const docs = [body['docs'], body['type']].find(
+    (value): value is string => typeof value === 'string' && HTTP_URL.test(value),
+  );
+  return new UltimateError({
+    code,
+    cause: text1(body['cause']) ?? text1(body['detail']) ?? `${url} failed with HTTP ${status}`,
+    fix: text1(body['fix']) ?? `x errors explain ${renderFixShellArg(code, '<code>')} --json`,
+    retry: retryForStatus(code, status),
+    // The server's declared keys FIRST, so the three this decoder owns win a collision.
+    meta: { ...serverMeta(body['meta'], body['issues']), origin: 'remote', status, url },
+    ...(docs === undefined ? {} : { docs }),
+  });
+}
+
+/**
+ * WHICH way no usable answer came back, on `meta.failure` — what a caller branches on, since the
+ * code is the same for all three: `network` (no response at all — the one an offline outbox
+ * queues), `status` (a non-2xx no framework code explained) and `body` (a 2xx that is not JSON).
+ */
+export type TransportFailure = 'network' | 'status' | 'body';
+
+/**
+ * No usable answer: the network refused, the body stream broke, or a 2xx body was not JSON.
+ * `retry` is the caller's to state — a read is always safe to send again, an unkeyed write never.
+ */
+export function transportFailed(
+  failure: TransportFailure,
+  cause: string,
+  retry: ErrorRetry | undefined,
+  meta: Readonly<Record<string, unknown>>,
+  sourceError?: unknown,
+): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_TRANSPORT_FAILED',
+    cause,
+    fix: 'check the network and the gateway in front of the app with x doctor --json, then retry — a write with no idempotencyKey may already have landed',
+    ...(retry === undefined ? {} : { retry }),
+    meta: { ...meta, failure },
+    ...(sourceError === undefined ? {} : { sourceError }),
+  });
+}
+
+/**
+ * The document's `meta`, copied own key by own key: `JSON.parse` mints `__proto__` as a real own
+ * key, and assigned onto a plain object it would replace the prototype. `issues` rides along
+ * unparsed for the caller whose schema can read it.
+ */
+function serverMeta(meta: unknown, issues: unknown): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (isJsonObject(meta)) {
+    for (const [key, member] of Object.entries(meta)) {
+      if (key === '__proto__') continue;
+      Object.defineProperty(out, key, { value: member, writable: true, enumerable: true });
+    }
+  }
+  if (Array.isArray(issues)) out['issues'] = issues;
+  return out;
+}
+
+function text1(value: unknown): string | undefined {
+  return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/src/client-scope-error.ts

@@ -0,0 +1,18 @@
+/**
+ * The refusal a read in flight across `rescope()` rejects with — `X_CLIENT_SCOPE_CHANGED`. Its own
+ * module, imported only by the transport: `client-scope.ts` is what `pageClient()` and every
+ * `onRescope` subscriber reach, and constructing an `UltimateError` there put core's error registry
+ * into a store-only island that never makes a request.
+ */
+
+import { UltimateError } from './errors';
+
+/** Never a UI error: `isSuperseded(error)` answers true for it, and a caller renders nothing. */
+export function scopeChanged(subject: string, issued: number, current: number): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_SCOPE_CHANGED',
+    cause: `${subject} was issued for client scope epoch ${issued} and the page is now at ${current}, so its answer belongs to the previous principal`,
+    fix: 'discard this answer and read again — test it with isSuperseded(error) from @ultimat3/core and render nothing for it',
+    meta: { subject, issued, current },
+  });
+}

package/src/client-scope.ts

@@ -0,0 +1,59 @@
+/**
+ * The principal fence: which principal the page is acting for, and an epoch that moves exactly
+ * when that changes. A response, frame or persisted row from the previous principal must never
+ * land in the next one's store, so every client layer reads this one signal.
+ *
+ * Subscriber contract (`onRescope`): called SYNCHRONOUSLY, once per real change, in registration
+ * order, before `rescope()` returns — so by the time a sign-in action's caller continues, every
+ * read was aborted, the store wiped its non-persisted records, the socket dropped its channels
+ * and the persister switched scope. A throwing subscriber does not stop the others; the first
+ * throw is re-raised after all have run. The TRIGGER is not core's: the page bootstrap calls
+ * `rescope()` with the principal the server rendered, and sign-in / sign-out call it on success.
+ */
+
+import type { ScopeCell } from './record-sink';
+import { heldRecords, scopeCell } from './record-sink';
+
+export interface ClientScope {
+  /**
+   * An opaque principal id; `null` for a page rendered for an anonymous visitor; `undefined` for
+   * an UNSCOPED page — one rendered for nobody (a shared, cacheable document carries no scope
+   * meta). Nothing is persisted while unscoped (plan 101 slice 12): there is no principal to key
+   * the rows by, and guessing one is how one visitor's cache restores into another's.
+   */
+  readonly principal: string | null | undefined;
+  /** Bumped once per principal change. Work captured at another epoch is not this scope's. */
+  readonly epoch: number;
+}
+
+/** Move the page to `principal`. Same principal = no-op: no epoch bump, no notification. */
+export function rescope(principal: string | null): void {
+  const cell: ScopeCell = scopeCell();
+  const prev = cell.current;
+  if (prev.principal === principal) return;
+  const next: ClientScope = Object.freeze({ principal, epoch: prev.epoch + 1 });
+  cell.current = next;
+  // Held early records belong to the principal that just left; they never reach the next store.
+  heldRecords()?.clear();
+  let failure: { readonly error: unknown } | undefined;
+  // A snapshot: a subscriber that unsubscribes (or subscribes) mid-notify changes the NEXT round.
+  for (const listener of [...cell.listeners]) {
+    try {
+      listener(next, prev);
+    } catch (error) {
+      failure ??= { error };
+    }
+  }
+  if (failure !== undefined) throw failure.error;
+}
+
+/** Subscribe to principal changes. Returns the unsubscribe. */
+export function onRescope(fn: (next: ClientScope, prev: ClientScope) => void): () => void {
+  const listeners = scopeCell().listeners;
+  // Wrapped, so the same function registered twice is two subscriptions with two unsubscribes.
+  const entry = (next: ClientScope, prev: ClientScope): void => fn(next, prev);
+  listeners.add(entry);
+  return (): void => {
+    listeners.delete(entry);
+  };
+}