@ultimat3/core 20.2.1 → 21.0.0

package/src/client-transport.ts

@@ -0,0 +1,86 @@
+/**
+ * The ONE browser HTTP function. Every client surface — `rpc()`, `queryClient()`, a signed upload,
+ * the store's refetch — sends through here, so credentials, headers, the error decode, the records
+ * envelope and the principal fence are decided once. A GET is a read: abortable on `rescope()`,
+ * deduped when a `ClientFlight` is supplied. Anything else is a write: never deduped, never
+ * aborted by the fence, and its records never adopted across one.
+ *
+ * `createClientFlight` is NOT imported here at value level — a caller passes one, and only then
+ * does its graph enter the bundle. Neither is `traceHeaders()`: the trace and budget headers come
+ * from an outbound slot that `runWithContext`/`startSpan` fill SERVER-side (`outbound-headers.ts`),
+ * so a browser, which never has either, carries zero bytes of telemetry, context or logger.
+ *
+ * Measured `bun build --target=browser --minify` through the barrel, As of 2026-09-22 (before →
+ * after the outbound slot): `rpc` 23,164 → 18,119 B; `queryClient` 24,100 → 22,897 B (the rest is
+ * `@ultimat3/query`'s anchored `registry.ts`); `clientTransport` 13,571 B; `pageClient` 8,139 B;
+ * `UltimateError` 7,679 B. ~7.6 kB of every barrel import is the error-code registry that the
+ * anchored `schema-error-codes.ts` registers into — `pageClient` straight from its module is 332 B.
+ */
+
+import type { Answer, TransportRequest } from './client-dispatch';
+import { dispatch } from './client-dispatch';
+import { transportFailed } from './client-problem';
+import { scopeChanged } from './client-scope-error';
+import type { RecordEnvelope } from './record-envelope';
+import { decodeRecordEnvelope } from './record-envelope';
+import { pageClient, recordSink } from './record-sink';
+
+const ONCE = { attempts: 1 } as const;
+
+export async function clientTransport<T = unknown>(req: TransportRequest): Promise<T> {
+  const read = req.method === 'GET';
+  const issued = pageClient().scope.epoch;
+  const flight = req.flight;
+  const answer: Answer =
+    flight === undefined
+      ? await dispatch(req, read, issued, undefined)
+      : await flight.run({
+          // A mutation never joins another mutation, idempotency key or not: the key is for the
+          // server's replay, and sharing one dispatch would hide the second intent from it.
+          key: read ? flight.keyFor(req.url, { signal: req.signal, fresh: req.fresh }) : undefined,
+          abortable: read,
+          // A stream is read once, so a second attempt re-sends a body that is already spent —
+          // and fails as the network would, until the attempts run out. One attempt, always.
+          retry: req.rawBody instanceof ReadableStream ? ONCE : req.retry,
+          run: (signal) => dispatch(req, read, issued, signal),
+          // `dispatch` makes every wire failure `X_CLIENT_TRANSPORT_FAILED`; a bare throw that
+          // reaches the flight is a caller hook's, never the network's.
+          classified: true,
+        });
+  const current = pageClient().scope.epoch;
+  // A read that raced the abort still belongs to the previous principal.
+  if (read && current !== issued) throw scopeChanged(req.url, issued, current);
+  if (req.rawBody !== undefined) return undefined as T;
+  const envelope = unwrap(answer, req.url, read);
+  // A write that crossed a rescope HAS landed, so its caller is told — but its rows are the
+  // previous principal's, and the new scope's store never sees them.
+  if (current === issued) {
+    adopt(envelope);
+    if (answer.enveloped) req.onEnvelope?.(envelope);
+  }
+  return envelope.data as T;
+}
+
+function unwrap(answer: Answer, url: string, read: boolean): RecordEnvelope {
+  let body: unknown;
+  try {
+    body = answer.text === '' ? undefined : (JSON.parse(answer.text) as unknown);
+  } catch (error) {
+    throw transportFailed(
+      'body',
+      `${url} answered 2xx with a body that is not JSON — a proxy answered instead of the app`,
+      read ? 'retryable' : undefined,
+      { url },
+      error,
+    );
+  }
+  return answer.enveloped ? decodeRecordEnvelope(body) : { data: body };
+}
+
+/** Adopt, then remove: a key in both is gone, never resurrected by the same answer. */
+function adopt(envelope: RecordEnvelope): void {
+  const sink = recordSink();
+  if (sink === undefined) return;
+  for (const [type, rows] of Object.entries(envelope.records ?? {})) sink.adopt(type, rows);
+  for (const [type, keys] of Object.entries(envelope.removed ?? {})) sink.remove(type, keys);
+}

package/src/conflict-policy.ts

@@ -0,0 +1,48 @@
+/**
+ * The ONE conflict vocabulary: which row survives when an optimistic local write and the server's
+ * answer disagree. Row-shaped because the client store is — a merge over a mutator's OUTPUT had
+ * nowhere to land, and realtime's rebase silently dropped it. Tier 0 so `action` and `realtime`
+ * (both tier 3) name the same type.
+ */
+
+/** One record as the client store holds it: a JSON object, keyed by field name. */
+export type Row = Readonly<Record<string, unknown>>;
+
+export type ConflictPolicy =
+  | 'server-wins'
+  | 'last-write-wins'
+  | { readonly kind: 'custom'; readonly merge: (local: Row, server: Row) => Row };
+
+export interface ResolveConflictOptions {
+  /**
+   * The field `last-write-wins` compares — a finite number (epoch ms) the SERVER wrote. Default
+   * `updatedAt`, the name realtime's rebase has always read.
+   */
+  readonly clockField?: string | undefined;
+}
+
+/**
+ * The surviving row. `last-write-wins` keeps the local row only when its clock is provably newer
+ * by the server's own field; a missing or non-numeric clock on either side is no proof, so the
+ * server's row stands — the store must never keep a guess over an answer.
+ */
+export function resolveConflict(
+  policy: ConflictPolicy,
+  local: Row,
+  server: Row,
+  options: ResolveConflictOptions = {},
+): Row {
+  if (typeof policy !== 'string') return policy.merge(local, server);
+  if (policy === 'server-wins') return server;
+  const field = options.clockField ?? 'updatedAt';
+  const localAt = clockOf(local, field);
+  const serverAt = clockOf(server, field);
+  return localAt !== undefined && serverAt !== undefined && localAt > serverAt ? local : server;
+}
+
+function clockOf(row: Row, field: string): number | undefined {
+  // Own keys only: a field named `constructor` must not read `Object.prototype`'s.
+  if (!Object.hasOwn(row, field)) return undefined;
+  const value = row[field];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}

package/src/context.ts

@@ -37,6 +37,7 @@ import { UltimateError } from './errors';
 import { finiteOption } from './finite-option';
 import { traceId as newTraceId, uuid } from './ids';
 import { type Logger, logger as rootLogger, setLoggerContextFields } from './logger';
+import { installTraceHeaders } from './outbound-headers';
 import { type Role, resolveRole } from './roles';
 import { installedServices, isManagedService } from './service';
 
@@ -130,6 +131,13 @@ export interface CtxInit {
   /** Epoch ms. `@ultimat3/http`'s `startDeadline` is the one production writer. */
   readonly deadlineAt?: number | undefined;
   readonly services?: ServiceBag | undefined;
+  /**
+   * `false` installs no `defineService` factory — only `services` — and leaves the registered
+   * ones to the caller. `@ultimat3/http` is that caller: its context exists before the `auth`
+   * stage names the actor, and a service built here would act as anonymous for the whole request.
+   * Default `true`.
+   */
+  readonly installServices?: boolean | undefined;
 }
 
 /**
@@ -184,7 +192,8 @@ export function createContext(init: CtxInit = {}): Ctx {
   // wins over an auto-installed one of the same name — a test's hand-built mock overrides the
   // real thing on purpose.
   const preview: CtxFacts = Object.freeze({ ...explicit, ...fields, services: explicit });
-  const services: ServiceBag = Object.freeze({ ...installedServices(preview), ...explicit });
+  const installed = init.installServices === false ? {} : installedServices(preview);
+  const services: ServiceBag = Object.freeze({ ...installed, ...explicit });
   const ctx = {
     // Services ride ON the context, not only under `ctx.services`: `CtxServices` exists to be
     // augmented, so `ctx.posts` has to BE the service. Spread first, so a service that collides
@@ -208,6 +217,8 @@ export function createContext(init: CtxInit = {}): Ctx {
 }
 
 export function runWithContext<T>(ctx: Ctx, fn: () => T): T {
+  // A request scope is what gives an outbound typed call a budget to forward; see the module.
+  installTraceHeaders();
   return requestContext.run(ctx, fn);
 }
 

package/src/core-error-codes.ts

@@ -0,0 +1,77 @@
+// Single responsibility: core's OWN error-code titles, registered at import. A side-effect
+// anchor, bare-imported by the barrel — the same shape as `schema-error-codes.ts` — so the table
+// rides every barrel import and none of the light paths: `UltimateError` alone no longer carries
+// 40 titles into a browser island that throws one code. Listed in `SIDE_EFFECTS_ANCHORS`.
+
+import type { ErrorCodeDescriptor } from './error-codes';
+import { descriptor, registerCoreErrorCodes } from './error-codes';
+
+/** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
+const CORE_CODE_TITLES = {
+  X_ABORTED: 'operation aborted',
+  X_ASYNC_CONTEXT_UNAVAILABLE: 'async context unavailable',
+  // The browser seam's three (`client-transport.ts`, `record-envelope.ts`, `client-scope.ts`).
+  X_CLIENT_RECORD_ENVELOPE_INVALID: 'a response marked as a records envelope has the wrong shape',
+  X_CLIENT_SCOPE_CHANGED: 'the page changed principal while this request was in flight',
+  X_CLIENT_TRANSPORT_FAILED: 'a browser request got no answer from the app',
+  X_CONFIG_INVALID: 'app.config.ts is invalid',
+  X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
+  X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
+  X_DRAINING: 'process is draining and refuses new work',
+  X_ENV_EXAMPLE_DRIFT: '.env.example does not declare every variable the schema requires',
+  X_ENV_MISSING: 'required environment variables are missing or invalid',
+  X_ENVIRONMENT_INVALID: 'ULTIMATE_ENV is not a known environment',
+  X_ERROR_CODE_DUPLICATE: 'error code registered twice',
+  X_ERROR_REPORTER_DSN_INVALID: 'the error monitor DSN is malformed',
+  X_ERROR_RETRY_INVALID: 'error retry classification is unknown or already claimed',
+  // Core's own, and deliberately NOT `@ultimat3/http`'s `X_OVERLOADED`: that code is owned by a
+  // tier-2 package, and a tier-0 gate borrowing it upward is an import core may not make. The two
+  // read alike to an operator and the fix lines say which ceiling to widen.
+  X_FLIGHT_GATE_OVERLOADED: 'a concurrency gate is at its ceiling and its queue is full',
+  X_ID_INVALID: 'value is not a valid id',
+  X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
+  X_IMAGE_TOO_LARGE: 'image exceeds the pipeline pixel ceiling',
+  X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
+  X_INTERNAL: 'unexpected internal framework error',
+  X_INVARIANT: 'invariant violated',
+  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
+  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
+  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
+  X_METRIC_CARDINALITY:
+    'a metric exceeded its series ceiling and is folding into one overflow series',
+  X_METRIC_NAME_INVALID:
+    'metric name is malformed, or redeclared with a different kind, bounds or observer',
+  X_METRIC_VALUE_INVALID: 'metric value is not recordable',
+  X_NO_CONTEXT: 'no request context is active',
+  X_NOT_IMPLEMENTED: 'this driver does not implement the requested feature',
+  X_OTLP_ENDPOINT_INVALID: 'the OTLP collector endpoint is missing or malformed',
+  // Its own code rather than the endpoint's, because a title is what an agent reads first:
+  // `x errors explain X_OTLP_ENDPOINT_INVALID` would send it to inspect a variable that is fine.
+  X_OTLP_HEADERS_INVALID: 'OTEL_EXPORTER_OTLP_HEADERS is malformed',
+  X_OTLP_PROTOCOL_UNSUPPORTED: 'the OTLP protocol requested is not OTLP/HTTP JSON',
+  X_READINESS_CHECK_DUPLICATE: 'a readiness check name is registered twice',
+  X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',
+  X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
+  X_ROLE_INVALID: 'ROLE is not a known runtime role',
+  X_SERVICE_DUPLICATE: 'a service name is registered twice',
+  X_SERVICE_MISSING: 'service is not registered on the request context',
+  X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',
+  X_SUPERSEDED: 'a later generation superseded this work',
+  X_TELEMETRY_SAMPLER_ARG_INVALID: 'the trace sampling ratio is not a number between 0 and 1',
+  // Core's, though core does not throw it — the twin of `X_ABORTED`, and `@ultimat3/http` already
+  // calls it "borrowed (core's concept)" in `HTTP_BORROWED_ERROR_CODES`. A deadline that expired
+  // and a caller that went away are one pair of facts, so they are titled and classified in one
+  // place rather than by whichever package happened to raise one first.
+  X_TIMEOUT: 'operation exceeded its deadline',
+  X_UNREACHABLE: 'unreachable branch was reached',
+} as const;
+
+export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
+
+export const CORE_ERROR_CODES: Readonly<Record<CoreErrorCode, ErrorCodeDescriptor>> = Object.freeze(
+  Object.fromEntries(
+    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor({ title })]),
+  ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
+);
+
+registerCoreErrorCodes(CORE_ERROR_CODES);

package/src/error-codes.ts

@@ -28,75 +28,26 @@ export interface ErrorCodeEntry extends ErrorCodeDescriptor {
  */
 export const ERROR_DOCS_URL = 'https://github.com/developerz-ai/ultimate/wiki/Error-Codes';
 
-/** Codes owned by `@ultimat3/core`. Every other package calls `registerErrorCodes()`. */
-const CORE_CODE_TITLES = {
-  X_ABORTED: 'operation aborted',
-  X_ASYNC_CONTEXT_UNAVAILABLE: 'async context unavailable',
-  X_CONFIG_INVALID: 'app.config.ts is invalid',
-  X_CURSOR_INVALID: 'pagination cursor is malformed, tampered with or from another query',
-  X_CURSOR_SECRET_DEV: 'cursors are signed with the shipped development key',
-  X_DRAINING: 'process is draining and refuses new work',
-  X_ENV_EXAMPLE_DRIFT: '.env.example does not declare every variable the schema requires',
-  X_ENV_MISSING: 'required environment variables are missing or invalid',
-  X_ENVIRONMENT_INVALID: 'ULTIMATE_ENV is not a known environment',
-  X_ERROR_CODE_DUPLICATE: 'error code registered twice',
-  X_ERROR_REPORTER_DSN_INVALID: 'the error monitor DSN is malformed',
-  X_ERROR_RETRY_INVALID: 'error retry classification is unknown or already claimed',
-  // Core's own, and deliberately NOT `@ultimat3/http`'s `X_OVERLOADED`: that code is owned by a
-  // tier-2 package, and a tier-0 gate borrowing it upward is an import core may not make. The two
-  // read alike to an operator and the fix lines say which ceiling to widen.
-  X_FLIGHT_GATE_OVERLOADED: 'a concurrency gate is at its ceiling and its queue is full',
-  X_ID_INVALID: 'value is not a valid id',
-  X_IMAGE_DECODE_FAILED: 'image bytes are malformed, truncated or internally inconsistent',
-  X_IMAGE_TOO_LARGE: 'image exceeds the pipeline pixel ceiling',
-  X_IMAGE_UNSUPPORTED: 'the built-in image pipeline cannot read or write this format',
-  X_INTERNAL: 'unexpected internal framework error',
-  X_INVARIANT: 'invariant violated',
-  // Owned here rather than by `@ultimat3/time`, which declared it until 16.x: `@ultimat3/money`
-  // needs the same screen and tier 1 may not import sideways. One code, one declaration.
-  X_LOCALE_INVALID: 'not a well-formed BCP 47 tag',
-  X_METRIC_CARDINALITY:
-    'a metric exceeded its series ceiling and is folding into one overflow series',
-  X_METRIC_NAME_INVALID:
-    'metric name is malformed, or redeclared with a different kind, bounds or observer',
-  X_METRIC_VALUE_INVALID: 'metric value is not recordable',
-  X_NO_CONTEXT: 'no request context is active',
-  X_NOT_IMPLEMENTED: 'this driver does not implement the requested feature',
-  X_OTLP_ENDPOINT_INVALID: 'the OTLP collector endpoint is missing or malformed',
-  // Its own code rather than the endpoint's, because a title is what an agent reads first:
-  // `x errors explain X_OTLP_ENDPOINT_INVALID` would send it to inspect a variable that is fine.
-  X_OTLP_HEADERS_INVALID: 'OTEL_EXPORTER_OTLP_HEADERS is malformed',
-  X_OTLP_PROTOCOL_UNSUPPORTED: 'the OTLP protocol requested is not OTLP/HTTP JSON',
-  X_READINESS_CHECK_DUPLICATE: 'a readiness check name is registered twice',
-  X_REGISTRAR_CONFLICT: 'two different registrars are loaded for one primitive kind',
-  X_REGISTRAR_MISSING: 'no registrar is loaded for a primitive kind',
-  X_ROLE_INVALID: 'ROLE is not a known runtime role',
-  X_SERVICE_DUPLICATE: 'a service name is registered twice',
-  X_SERVICE_MISSING: 'service is not registered on the request context',
-  X_SHUTDOWN_TIMEOUT: 'graceful shutdown exceeded its deadline',
-  X_SUPERSEDED: 'a later generation superseded this work',
-  X_TELEMETRY_SAMPLER_ARG_INVALID: 'the trace sampling ratio is not a number between 0 and 1',
-  // Core's, though core does not throw it — the twin of `X_ABORTED`, and `@ultimat3/http` already
-  // calls it "borrowed (core's concept)" in `HTTP_BORROWED_ERROR_CODES`. A deadline that expired
-  // and a caller that went away are one pair of facts, so they are titled and classified in one
-  // place rather than by whichever package happened to raise one first.
-  X_TIMEOUT: 'operation exceeded its deadline',
-  X_UNREACHABLE: 'unreachable branch was reached',
-} as const;
-
-export type CoreErrorCode = keyof typeof CORE_CODE_TITLES;
-
-function descriptor(declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
+export function descriptor(declaration: ErrorCodeDeclaration): ErrorCodeDescriptor {
   return Object.freeze({ title: declaration.title, docs: declaration.docs ?? ERROR_DOCS_URL });
 }
 
-export const CORE_ERROR_CODES: Readonly<Record<CoreErrorCode, ErrorCodeDescriptor>> = Object.freeze(
-  Object.fromEntries(
-    Object.entries(CORE_CODE_TITLES).map(([code, title]) => [code, descriptor({ title })]),
-  ) as Record<CoreErrorCode, ErrorCodeDescriptor>,
-);
+/**
+ * Empty at load, on purpose: core's own titles live in `core-error-codes.ts`, which the barrel
+ * bare-imports as a side-effect anchor. A browser module that constructs an `UltimateError` from a
+ * light path pays for the class and this lookup, not a 40-row table — an untitled code renders
+ * through `humanize`, the trade `@ultimat3/realtime` already made for its own titles.
+ */
+const registry = new Map<string, ErrorCodeDescriptor>();
 
-const registry = new Map<string, ErrorCodeDescriptor>(Object.entries(CORE_ERROR_CODES));
+/** What `resetErrorCodes` restores: the codes `registerCoreErrorCodes` installed. */
+const coreCodes = new Map<string, ErrorCodeDescriptor>();
+
+/** `core-error-codes.ts`'s one call. Registered like any package's, and remembered for a reset. */
+export function registerCoreErrorCodes(codes: Readonly<Record<string, ErrorCodeDescriptor>>): void {
+  registerErrorCodes(codes);
+  for (const [code, value] of Object.entries(codes)) coreCodes.set(code, value);
+}
 
 /**
  * Register a package's codes. Throws `X_ERROR_CODE_DUPLICATE` on collision so two packages
@@ -145,7 +96,7 @@ export function listErrorCodes(): readonly ErrorCodeEntry[] {
 /** Test-only: drop everything a package registered, keeping core's codes. */
 export function resetErrorCodes(): void {
   registry.clear();
-  for (const [code, value] of Object.entries(CORE_ERROR_CODES)) registry.set(code, value);
+  for (const [code, value] of coreCodes) registry.set(code, value);
 }
 
 /**

package/src/error-retry.ts

@@ -58,6 +58,9 @@ const CORE_ERROR_RETRY: ReadonlyMap<string, ErrorRetry> = new Map(
     // re-run produces the same refusal by construction, so an UNCLASSIFIED reading would spend a
     // job's whole retry policy proving that the world has still moved on.
     X_SUPERSEDED: 'terminal',
+    // The principal fence's twin of `X_SUPERSEDED`, listed for the same reason: re-sending a read
+    // from the previous principal's scope is refused identically every time.
+    X_CLIENT_SCOPE_CHANGED: 'terminal',
   } as const),
 );
 

package/src/exports/error-contract.ts

@@ -3,14 +3,14 @@
 // built with, and the retry classification a code carries. One group because a code, its title,
 // its rendering and its retry class are one contract; `index.ts` re-exports every name explicitly.
 
+export type { CoreErrorCode } from '../core-error-codes';
+export { CORE_ERROR_CODES } from '../core-error-codes';
 export type {
-  CoreErrorCode,
   ErrorCodeDeclaration,
   ErrorCodeDescriptor,
   ErrorCodeEntry,
 } from '../error-codes';
 export {
-  CORE_ERROR_CODES,
   describeErrorCode,
   ERROR_DOCS_URL,
   errorCodeSnapshot,

package/src/generation-fence.ts

@@ -51,7 +51,14 @@ function superseded(subject: string, issued: number, current: number): UltimateE
   });
 }
 
-/** Whether a caught value is this refusal. The one reader a caller needs; never `error.code`. */
+/**
+ * Whether a caught value is a supersession — this fence's refusal, or `X_CLIENT_SCOPE_CHANGED`,
+ * the principal fence's (`client-scope.ts`). One reader for both, because a caller does the same
+ * thing with either: drop the answer and render nothing. Never `error.code`.
+ */
 export function isSuperseded(error: unknown): boolean {
-  return isUltimateError(error) && error.code === 'X_SUPERSEDED';
+  return (
+    isUltimateError(error) &&
+    (error.code === 'X_SUPERSEDED' || error.code === 'X_CLIENT_SCOPE_CHANGED')
+  );
 }

package/src/index.ts

@@ -14,6 +14,7 @@
 // are declared side-effecting too and are deliberately NOT anchored: each is reached by whatever
 // uses it, and anchoring `context.ts` alone measured +3,485 B on a browser chunk for a provider a
 // browser can never fire.
+import './core-error-codes';
 import './schema-error-codes';
 
 export type {
@@ -43,10 +44,14 @@ export {
 export { APP_VERSION_KEY, appVersion, DEFAULT_APP_VERSION } from './app-version';
 export { assert, assertNever, type InvariantOptions, invariant } from './assert';
 export { type AsyncContext, asyncContext } from './async-context';
+/** The four shapes an async region can be in — produced by `realtime`, rendered by `ui`. */
+export type { AsyncState } from './async-state';
 export type { BackoffCurve, BackoffOptions, JitterMode, Random } from './backoff';
 export { backoffDelay } from './backoff';
 export { CACHE_TIERS, type CacheTierName } from './cache-vocabulary';
 export { canonicalJson, fingerprint } from './canonical-json';
+export type { FetchLike, TransportRequest } from './client-dispatch';
+export { IDEMPOTENCY_HEADER } from './client-dispatch';
 /**
  * Flight control for a typed client, and OPT-IN by construction: `@ultimat3/action`'s and
  * `@ultimat3/query`'s `client.ts` each name `ClientFlight` as a TYPE only, so a caller that never
@@ -61,6 +66,23 @@ export type {
   FlightPlan,
 } from './client-flight';
 export { createClientFlight, DEFAULT_CLIENT_RETRY, isTransientFailure } from './client-flight';
+export type { ActionRoute } from './client-paths';
+export {
+  actionPath,
+  actionRoute,
+  pluralize,
+  QUERY_PATH_PREFIX,
+  queryPath,
+  splitWords,
+} from './client-paths';
+export type { TransportFailure } from './client-problem';
+/**
+ * The browser seam (plan 101): ONE HTTP function, the records envelope it decodes, the per-tab
+ * page handle records land in, and the principal fence every client layer subscribes to.
+ */
+export type { ClientScope } from './client-scope';
+export { onRescope, rescope } from './client-scope';
+export { clientTransport } from './client-transport';
 /** What a typed client puts on the wire. `retryForStatus` is what fills a failure's `retry`. */
 export type { WireAnswer } from './client-wire';
 export { FRAMEWORK_CODE, problemOf, retryForStatus, traceHeaders } from './client-wire';
@@ -86,6 +108,8 @@ export type {
 export { defineConfig, INBOX_RETENTION_KEYS } from './config';
 export type { PwaColors, PwaConfig, PwaOfflineConfig, PwaSchemeColors } from './config-pwa';
 export { PWA_COLOR_KEYS, PWA_SCHEMES } from './config-pwa';
+export type { ConflictPolicy, ResolveConflictOptions, Row } from './conflict-policy';
+export { resolveConflict } from './conflict-policy';
 export type { Ctx, CtxFacts, CtxInit, CtxPatch, CtxServices, ServiceBag } from './context';
 export {
   createContext,
@@ -521,7 +545,24 @@ export type { Direction } from './locale-direction';
 export { directionOf, isRtl } from './locale-direction';
 export { isMcpExposed, type McpExposureDeclaration } from './mcp-exposure';
 export { nearestName } from './nearest-name';
+/** The message pwa's `sw.js` posts and realtime's outbox listens for. */
+export { OUTBOX_DRAIN_MESSAGE, type OutboxDrainMessage } from './outbox-drain';
+/** The `<meta name>`s render writes and the page client, realtime and pwa read. */
+export {
+  APP_UPDATE_MESSAGE,
+  CLIENT_BUILD_META,
+  CLIENT_PERSIST_META,
+  CLIENT_SCOPE_HEADER,
+  CLIENT_SCOPE_META,
+  CLIENT_SYNC_META,
+  CLIENT_SYNC_WORKER_META,
+} from './page-meta';
 export { type CappedBody, readWithinLimit } from './read-capped';
+export type { RecordEnvelope, RecordRows } from './record-envelope';
+export { decodeRecordEnvelope, encodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
+export { RECORDS_OPENAPI_HEADER, recordEnvelopeSchema } from './record-envelope-openapi';
+export type { PageClient, RecordSink } from './record-sink';
+export { pageClient } from './record-sink';
 export type {
   ModuleRegistrar,
   PrimitiveFactory,
@@ -551,7 +592,13 @@ export { DEFAULT_ROLE, isRole, ROLE_INFO, ROLES, resolveRole } from './roles';
 export type { HydrateStrategy, OfflineStrategy, RenderMode } from './route-vocabulary';
 export { HYDRATE_STRATEGIES, OFFLINE_STRATEGIES, RENDER_MODES } from './route-vocabulary';
 export { safeUrl, URL_ATTRIBUTES } from './safe-url';
-export { defineService, resetServices, type ServiceFactory } from './service';
+export {
+  defineService,
+  installedServices,
+  registeredServiceNames,
+  resetServices,
+  type ServiceFactory,
+} from './service';
 export type { FlightJoin, Scheduler, SingleFlight, SingleFlightOptions } from './single-flight';
 export { createSingleFlight } from './single-flight';
 export { endOfLiteral, maskLiterals, QUOTES, stripComments } from './source-mask';
@@ -584,3 +631,9 @@ export {
   webhookSignature,
   webhookSigningString,
 } from './webhook-signature';
+/**
+ * A write's public name — the digest of its idempotency key — and the server scope that carries it
+ * from `@ultimat3/action`'s HTTP projection to the layers that stamp it on a `records` frame.
+ */
+export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';
+export { currentWriteOrigin, WRITE_ORIGIN_WAL_PREFIX, withWriteOrigin } from './write-origin';

package/src/outbound-headers.ts

@@ -0,0 +1,16 @@
+/**
+ * The trace and request-budget headers a SERVER-side typed call carries onward, installed into the
+ * transport's slot by the code that makes them meaningful — `runWithContext` and `startSpan` — and
+ * never at import. A browser runs neither, so its slot stays empty and `clientTransport` carries
+ * zero bytes of telemetry, context or logger: that graph was 12.9 kB of every island that called
+ * `rpc()` or `queryClient()`, for a header a browser never has a value for.
+ */
+
+import { traceHeaders } from './client-wire';
+import { outboundSlot } from './record-sink';
+
+/** Idempotent: the first call fills the slot, every later one is a property read. */
+export function installTraceHeaders(): void {
+  const slot = outboundSlot();
+  if (slot.outboundHeaders === undefined) slot.outboundHeaders = traceHeaders;
+}

package/src/outbox-drain.ts

@@ -0,0 +1,14 @@
+/**
+ * The one message a service worker posts to its window clients when the platform says the
+ * connection is back: "drain your outbox now". Tier 0 because the SENDER is `@ultimat3/pwa`'s
+ * emitted `sw.js` (tier 4) and the LISTENER is `@ultimat3/realtime`'s outbox (tier 3) — one literal,
+ * one home, never a string each side retypes.
+ */
+
+/** `event.data.type` of the drain message. */
+export const OUTBOX_DRAIN_MESSAGE = 'x-outbox-drain';
+
+/** The whole message. It carries nothing else: the outbox lives in the page, not in the worker. */
+export interface OutboxDrainMessage {
+  readonly type: typeof OUTBOX_DRAIN_MESSAGE;
+}

package/src/page-meta.ts

@@ -0,0 +1,41 @@
+/**
+ * The `<meta name>`s a rendered document hands its page client. Tier 0 because the WRITER is
+ * `@ultimat3/render` (tier 4) and the READERS are core's `pageClient()`, `@ultimat3/realtime`'s
+ * socket host (tier 3) and `@ultimat3/pwa`'s skew check — one literal per fact, never retyped.
+ */
+
+/** The page's principal: content = that principal, empty = anonymous, absent = unscoped. */
+export const CLIENT_SCOPE_META = 'ultimate-scope';
+
+/**
+ * The same scope on the RESPONSE of a private document, so a service worker — which never parses
+ * HTML — can partition its offline pages by principal. Present only where the meta is; its value
+ * is the meta's (`''` for the anonymous visitor).
+ */
+export const CLIENT_SCOPE_HEADER = 'x-ultimate-scope';
+
+/**
+ * The build id the document was rendered by. `x-ultimate-build` — the same spelling as the header,
+ * and the one `@ultimat3/pwa` shipped as `BUILD_ID_META`, so no shipped reader changes.
+ */
+export const CLIENT_BUILD_META = 'x-ultimate-build';
+
+/**
+ * `event.data.type` of the message a service worker posts to its windows when a newer build is
+ * waiting (`{ type, to: <build id> }`). Sent by `@ultimat3/pwa`'s emitted `sw.js`, read by an app's
+ * update banner — one literal both import, beside the build id it is about.
+ */
+export const APP_UPDATE_MESSAGE = 'AppUpdateAvailable';
+
+/** Where the page's one socket dials: `/_x/sync`, or the deployment's absolute `SYNC_URL`. */
+export const CLIENT_SYNC_META = 'ultimate-sync';
+
+/** The worker script that hosts the socket; absent when the app has no realtime. */
+export const CLIENT_SYNC_WORKER_META = 'ultimate-sync-worker';
+
+/**
+ * The record types the client keeps on disk — the entities registered with `persist: true`,
+ * comma-separated (`post,comment`). The browser holds no entity declarations, so this is the one
+ * place it learns which types `@ultimat3/realtime`'s persister may write. Absent = none.
+ */
+export const CLIENT_PERSIST_META = 'ultimate-persist';

package/src/page.ts

@@ -0,0 +1,52 @@
+/**
+ * `@ultimat3/core/page` — the ONE light entry for browser code: the page handle, the principal
+ * fence, the names a document, a service worker and an island agree on, and `UltimateError` with
+ * the render helper a refusal's `fix:` needs. What it never carries is a titles TABLE: any barrel
+ * import retains the anchored `core-error-codes.ts` and `schema-error-codes.ts`, and a browser
+ * that loaded no table titles a code from its name. The barrel re-exports every name here;
+ * `page-bundle.test.ts` fails if this entry ever grows a table back.
+ */
+
+// The client seam's own functions, for the hooks a browser island calls: the one transport, the
+// URL rule, the principal-supersession reader, and the small helpers realtime's browser half uses.
+// Each reaches no titles table — `page-bundle.test.ts` builds all of them together to prove it.
+export { invariant } from './assert';
+export type { AsyncState } from './async-state';
+export type { JitterMode, Random } from './backoff';
+export { backoffDelay } from './backoff';
+export type { FetchLike, TransportRequest } from './client-dispatch';
+export { IDEMPOTENCY_HEADER } from './client-dispatch';
+export { actionPath, queryPath, splitWords } from './client-paths';
+export type { ClientScope } from './client-scope';
+export { onRescope, rescope } from './client-scope';
+export { clientTransport } from './client-transport';
+export { type Clock, systemClock } from './clock';
+export type { ConflictPolicy, Row } from './conflict-policy';
+// Registry-free: it merges two rows and throws nothing, so the page's record store settles a
+// write under a conflict policy without loading the error table.
+export { resolveConflict } from './conflict-policy';
+export { renderFixShellArg, renderThrowable, stringField } from './error-render';
+export { classifyThrown } from './error-retry';
+export type { UltimateErrorInit } from './errors';
+export { isUltimateError, UltimateError } from './errors';
+export { finiteCount, finiteOption } from './finite-option';
+export { isSuperseded } from './generation-fence';
+export { uuid } from './ids';
+export { isJsonObject } from './json-object';
+export type { OutboxDrainMessage } from './outbox-drain';
+export { OUTBOX_DRAIN_MESSAGE } from './outbox-drain';
+export {
+  APP_UPDATE_MESSAGE,
+  CLIENT_BUILD_META,
+  CLIENT_PERSIST_META,
+  CLIENT_SCOPE_HEADER,
+  CLIENT_SCOPE_META,
+  CLIENT_SYNC_META,
+  CLIENT_SYNC_WORKER_META,
+} from './page-meta';
+export type { RecordEnvelope, RecordRows } from './record-envelope';
+export { decodeRecordEnvelope, RECORDS_HEADER } from './record-envelope';
+export type { PageClient, RecordSink } from './record-sink';
+export { pageClient } from './record-sink';
+// A write's public name, so the page's store can recognise the `records` frame its own write made.
+export { isWriteDigest, WRITE_DIGEST_LENGTH, writeDigest } from './write-digest';