@ultimat3/core 20.2.1 → 22.0.0

package/src/lifecycle.ts

@@ -7,6 +7,7 @@ import { UltimateError } from './errors';
 import { finiteCount } from './finite-option';
 import { settleWithin } from './lifecycle-deadline';
 import { lifecycleDrained } from './lifecycle-errors';
+import { defaultReadinessGraceMs, readinessGraceIssue } from './lifecycle-grace';
 import { type LogFields, type Logger, logger as rootLogger } from './logger';
 
 export type HealthState = 'starting' | 'ready' | 'draining' | 'stopped';
@@ -54,6 +55,15 @@ export interface LifecycleOptions {
    * Screened where it is assigned: a whole number of milliseconds, 0 or more. `0` is "drain now".
    */
   readonly deadlineMs?: number | undefined;
+  /**
+   * How long `/readyz` answers 503 BEFORE the `accept` phase closes the listener — the time the
+   * endpoints controller and the ingress need to stop routing here. Closing on the flip itself left
+   * endpoints pointing at a closed socket, and a POST in that window got a 502. Added to
+   * `deadlineMs`, never taken from it. Unset: `defaultReadinessGraceMs()` of the process env at
+   * drain time — 0 in development/test, 5000 everywhere else, including a process naming no env.
+   * A whole number from 0 to 60000; 0 is no grace.
+   */
+  readonly readinessGraceMs?: number | undefined;
   readonly clock?: Clock | undefined;
   readonly logger?: Logger | undefined;
 }
@@ -111,6 +121,8 @@ interface Registration {
 const DEFAULT_DEADLINE_MS = 25_000;
 
 let deadlineMs = DEFAULT_DEADLINE_MS;
+/** `undefined` means "the environment's default", read when a drain starts, not at import. */
+let graceMs: number | undefined;
 let clock: Clock = systemClock;
 let log: Logger = rootLogger;
 let state: HealthState = 'starting';
@@ -131,6 +143,18 @@ export function configureLifecycle(options: LifecycleOptions): void {
   if (options.deadlineMs !== undefined) {
     deadlineMs = finiteCount('configureLifecycle', 'deadlineMs', options.deadlineMs, 0);
   }
+  if (options.readinessGraceMs !== undefined) {
+    const issue = readinessGraceIssue(options.readinessGraceMs);
+    if (issue !== undefined) {
+      throw new UltimateError({
+        code: 'X_CONFIG_INVALID',
+        cause: issue,
+        fix: 'pass configureLifecycle({ readinessGraceMs: 5_000 }) — or set drain: { readinessGraceMs: 5_000 } in app.config.ts',
+        meta: { key: 'drain.readinessGraceMs' },
+      });
+    }
+    graceMs = options.readinessGraceMs;
+  }
   if (options.clock !== undefined) {
     clock = options.clock;
     startedAtMono = clock.monotonic();
@@ -316,6 +340,11 @@ export function drainDeadlineMs(): number {
   return deadlineMs;
 }
 
+/** The grace the next drain will wait out — configured, else the environment's default. */
+export function readinessGraceMs(): number {
+  return graceMs ?? defaultReadinessGraceMs();
+}
+
 /**
  * What is left of that budget. Read per hook, not per phase: the deadline bounds the WHOLE drain,
  * so a hook that spent it leaves nothing for the ones behind it — which is what
@@ -354,10 +383,20 @@ async function runPhase(phase: ShutdownPhase, reason: ShutdownReason): Promise<v
   }
 }
 
-/** The three phases, in order, under one budget. Never rejects — `drain()` depends on that. */
-async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
+/**
+ * The three phases, in order, under one budget. Never rejects — `drain()` depends on that.
+ *
+ * The readiness grace runs FIRST and OUTSIDE the budget: `state` is already `draining`, so
+ * `/readyz` answers 503 while the listener still accepts what was routed here before the flip.
+ * The deadline starts after it, so a chart's `terminationGracePeriodSeconds` must exceed
+ * `readinessGraceMs + deadlineMs`.
+ */
+async function runDrain(signal: string): Promise<void> {
   try {
-    report('info', 'draining', { signal, deadlineMs, inflight });
+    const grace = readinessGraceMs();
+    report('info', 'draining', { signal, deadlineMs, readinessGraceMs: grace, inflight });
+    if (grace > 0) await Bun.sleep(grace);
+    const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
     await runPhase('accept', reason);
 
     // Real monotonic, like `deadlineAt` itself: `waitForIdle` sleeps on a real `setTimeout`, and
@@ -401,7 +440,6 @@ async function runDrain(signal: string, reason: ShutdownReason): Promise<void> {
 export function drain(signal = 'manual'): Promise<void> {
   if (drainPromise !== undefined) return drainPromise;
   state = 'draining';
-  const reason: ShutdownReason = { signal, deadlineAt: systemClock.monotonic() + deadlineMs };
   let published!: () => void;
   drainPromise = new Promise<void>((resolve) => {
     published = resolve;
@@ -409,41 +447,10 @@ export function drain(signal = 'manual'): Promise<void> {
   // Both settle paths, for the reason `installSignalHandlers` gives below: `runDrain` cannot
   // reject today — that is its `try/finally`, not luck — and a rejected memo would re-reject for
   // every later caller and end the process the drain was trying to end cleanly.
-  void runDrain(signal, reason).then(published, published);
+  void runDrain(signal).then(published, published);
   return drainPromise;
 }
 
-export interface SignalHandlerOptions {
-  readonly signals?: readonly ProcessSignal[] | undefined;
-  /** Call `process.exit()` once drained. Off in tests. */
-  readonly exit?: boolean | undefined;
-}
-
-/** Install SIGTERM/SIGINT handling. Returns an uninstall function. */
-export function installSignalHandlers(options?: SignalHandlerOptions): () => void {
-  const signals: readonly ProcessSignal[] = options?.signals ?? ['SIGTERM', 'SIGINT'];
-  const handlers = new Map<ProcessSignal, () => void>();
-
-  for (const signal of signals) {
-    const handler = (): void => {
-      // Attached on BOTH settle paths, for the reason `settleWithin` gives: an unhandled rejection
-      // ends the process before the drain does, and the exit is what the kubelet is waiting for.
-      // `drain()` cannot reject today — that is the `try/finally` above, not luck — and this is
-      // the one line that keeps it true when someone changes the body.
-      const done = (): void => {
-        if (options?.exit === true) process.exit(0);
-      };
-      void drain(signal).then(done, done);
-    };
-    handlers.set(signal, handler);
-    process.on(signal, handler);
-  }
-
-  return () => {
-    for (const [signal, handler] of handlers) process.off(signal, handler);
-  };
-}
-
 export function healthReport(): HealthReport {
   const checks = readinessChecks();
   return {
@@ -479,6 +486,7 @@ export function readyzPayload(): HealthPayload {
 /** Test-only: forget all hooks and return to `starting`. */
 export function resetLifecycle(): void {
   deadlineMs = DEFAULT_DEADLINE_MS;
+  graceMs = undefined;
   clock = systemClock;
   log = rootLogger;
   state = 'starting';

package/src/logger.ts

@@ -304,6 +304,22 @@ function resolveLevel(declared: LogLevel): LogLevel {
   return declared;
 }
 
+/** The keys a line owns. A caller field spelled like one is renamed, never allowed to replace it. */
+const RESERVED_KEYS: ReadonlySet<string> = new Set(['ts', 'level', 'msg']);
+
+/**
+ * The caller's fields with any reserved key moved to `field.<key>`. Spread after `level`, a field
+ * `{ level: 'debug' }` turned an `error` line into a `debug` one, so a level-filtered alert never
+ * saw it. Renamed rather than dropped: the value is still evidence.
+ */
+function unreserved(fields: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(fields)) {
+    out[RESERVED_KEYS.has(key) ? `field.${key}` : key] = value;
+  }
+  return out;
+}
+
 export function createLogger(options?: LoggerOptions): Logger {
   const level = options?.level === undefined ? envLevel() : resolveLevel(options.level);
   const bound = options?.fields ?? {};
@@ -313,13 +329,16 @@ export function createLogger(options?: LoggerOptions): Logger {
 
   function emit(lineLevel: LogLevel, message: string, fields?: LogFields): void {
     if (LEVEL_WEIGHT[lineLevel] < threshold) return;
+    const caller = {
+      ...redactFields(bound),
+      ...redactFields(contextFields() ?? {}),
+      ...redactFields(fields ?? {}),
+    };
     const line = {
       ts: timestamp(clock),
       level: lineLevel,
       msg: message,
-      ...redactFields(bound),
-      ...redactFields(contextFields() ?? {}),
-      ...redactFields(fields ?? {}),
+      ...unreserved(caller),
     };
     writer(renderLine(line, lineLevel, message, line.ts), lineLevel);
   }

package/src/measurement-actor.ts

@@ -0,0 +1,52 @@
+// The actor a route is rendered AS when the render exists only to be weighed — `x build`'s budget
+// measurement, whose document is discarded. The default holds every permission and no app facts;
+// a page that reads the app's own facts (`useActor()` over `actorFact`) failed `X_ACTOR_UNRESOLVED`
+// under it, so the app declares its own here, from `app.config.ts`, with no import of the CLI.
+
+import type { Actor } from './actor';
+import { serviceActor } from './actor';
+import { assert } from './assert';
+
+/** The id every trace and log line under a default measurement render carries. */
+export const MEASUREMENT_ACTOR_ID = 'x-build-measure';
+
+/** What an app declares: the actor its authed pages render as while they are weighed. */
+export type MeasurementActorFactory = () => Actor | Promise<Actor>;
+
+let declared: MeasurementActorFactory | undefined;
+
+/**
+ * Declare the measurement actor. Called at module scope in `app.config.ts`, the one file every
+ * build imports. The LAST declaration wins, because `x dev` re-imports that file on a save and a
+ * refusal there would be a reload that fails over a line nobody changed.
+ *
+ * Only a render that is WEIGHED AND DISCARDED uses it — never a published `site/` artifact, whose
+ * `load` must keep failing the build rather than render this actor's rows into a file for everyone.
+ */
+export function defineMeasurementActor(factory: MeasurementActorFactory): void {
+  declared = factory;
+}
+
+/**
+ * `kind: 'service'` and `'*'`: weighing bytes needs no data authority, and an app's own
+ * `requireMember()` has nothing to resolve for a service actor, which is the honest answer.
+ */
+const defaultMeasurementActor = (): Actor =>
+  serviceActor({ id: MEASUREMENT_ACTOR_ID, permissions: ['*'] });
+
+/** The declared actor, or the framework's default. The build's ONE reader. */
+export async function measurementActor(): Promise<Actor> {
+  if (declared === undefined) return defaultMeasurementActor();
+  const actor: Actor | undefined = await declared();
+  assert(
+    typeof actor === 'object' && actor !== null && typeof actor.id === 'string',
+    'the factory handed to defineMeasurementActor() answered no actor',
+    'return one from it in app.config.ts: defineMeasurementActor(() => userActor({ id: "measure", roles: ["member"] }))',
+  );
+  return actor;
+}
+
+/** Back to the default. For a test, and for nothing else. */
+export function resetMeasurementActor(): void {
+  declared = undefined;
+}

package/src/metrics-text.ts

@@ -9,7 +9,15 @@ export const METRICS_PATH = '/metrics';
 
 export const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';
 
-/** The exposition format escapes exactly these three, and nothing else. */
+/**
+ * HELP's two escapes, and only those: the exposition format defines `\\` and `\n` for a docstring.
+ * `\"` is a label-value escape — in HELP a parser keeps it as a literal backslash before the quote.
+ */
+function escapeHelp(value: string): string {
+  return value.replaceAll('\\', '\\\\').replaceAll('\n', '\\n');
+}
+
+/** A label VALUE escapes exactly these three, and nothing else. */
 function escapeLabel(value: string): string {
   return value.replaceAll('\\', '\\\\').replaceAll('"', '\\"').replaceAll('\n', '\\n');
 }
@@ -60,7 +68,7 @@ function histogramLines(name: string, point: HistogramPoint): readonly string[]
 function metricLines(metric: ReadableMetric): readonly string[] {
   const { name, kind, description, unit } = metric.descriptor;
   const help = unit === '1' || unit === '' ? description : `${description} (${unit})`;
-  const lines = [`# HELP ${name} ${escapeLabel(help)}`, `# TYPE ${name} ${kind}`];
+  const lines = [`# HELP ${name} ${escapeHelp(help)}`, `# TYPE ${name} ${kind}`];
   for (const point of metric.points) {
     if (kind === 'histogram' && isHistogramPoint(point)) {
       lines.push(...histogramLines(name, point));

package/src/otlp-metric-exporter.ts

@@ -122,7 +122,33 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
   const timeoutMs = assertFiniteOtlpBound('timeoutMs', options.timeoutMs ?? 10_000);
   const send = options.fetch ?? globalThis.fetch;
   let startedAtMs = options.startedAtMs;
-  let inflight: Promise<void> = Promise.resolve();
+  /** The ONE POST in flight, and the one body waiting behind it — never a chain. */
+  let sending: Promise<void> | undefined;
+  let waiting: string | undefined;
+
+  /**
+   * One snapshot in flight and at most one waiting. Each export used to chain a POST behind the
+   * last, so a stalled collector held every snapshot taken while it stalled. Snapshots are
+   * CUMULATIVE, so the newest supersedes every older one still waiting — dropping those loses no
+   * count — and sending strictly one at a time keeps a counter from arriving out of order and
+   * reading as a reset. `postOtlp` never rejects; the `then` pair keeps that true for this loop.
+   */
+  const pump = (): Promise<void> => {
+    if (sending !== undefined) return sending;
+    const body = waiting;
+    waiting = undefined;
+    if (body === undefined) return Promise.resolve();
+    sending = postOtlp({ url, headers, body, timeoutMs, fetch: send })
+      .then(
+        () => undefined,
+        () => undefined,
+      )
+      .then(() => {
+        sending = undefined;
+        if (waiting !== undefined) void pump();
+      });
+    return sending;
+  };
 
   return {
     export(collection: MetricCollection): void {
@@ -143,18 +169,19 @@ export function otlpMetricExporter(options: OtlpMetricExporterOptions = {}): Otl
         });
         return;
       }
-      // Chained, so a slow collector cannot make two snapshots arrive out of order and turn a
-      // cumulative counter into an apparent reset. Chained on a SETTLED shadow, for the reason
-      // `otlp-span-exporter.ts` spells out: a chain that carries a rejection forward stops calling
-      // `postOtlp` for the life of the process, in silence.
-      const settled = inflight.then(
-        () => undefined,
-        () => undefined,
-      );
-      inflight = settled.then(() => postOtlp({ url, headers, body, timeoutMs, fetch: send }));
+      waiting = body;
+      void pump();
     },
-    flush(): Promise<void> {
-      return inflight;
+    async flush(): Promise<void> {
+      // The one in flight, then the one that was waiting behind it — which that settle started.
+      // Bounded, so a timer exporting while this waits cannot keep a shutdown here forever.
+      for (
+        let round = 0;
+        round < 3 && (sending !== undefined || waiting !== undefined);
+        round += 1
+      ) {
+        await pump();
+      }
     },
   };
 }

package/src/otlp-span-exporter.ts

@@ -136,14 +136,15 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
   );
   const send = options.fetch ?? globalThis.fetch;
   const queue: ReadableSpan[] = [];
-  let inflight: Promise<void> = Promise.resolve();
+  /** The ONE batch in flight, or `undefined`. Never a chain: see `pump`. */
+  let sending: Promise<void> | undefined;
 
   const post = (batch: readonly ReadableSpan[]): Promise<void> => {
     const first = batch[0];
     if (first === undefined) return Promise.resolve();
     let body: string;
     try {
-      // The one synchronous throw on this path, and the only way `inflight` can reject at all:
+      // The one synchronous throw on this path, and the only way a send could reject at all:
       // `AttributeValue` is a compile-time claim, so an attribute the app spelled as an object, a
       // bigint or a cycle reaches `anyValue`'s `value.map(...)` as a TypeError. Dropped with a
       // line, the same degradation `postOtlp` already applies to a collector that is down —
@@ -160,25 +161,47 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
     return postOtlp({ url, headers, body, timeoutMs, fetch: send });
   };
 
-  const drainQueue = (): Promise<void> => {
-    const batch = queue.splice(0, queue.length);
-    // Chained, not concurrent: a collector reordering batches from one process turns a parent's
-    // span arriving after its child into a broken trace on the read side. Chained on a SETTLED
-    // shadow, because a chain that carries a rejection forward is poisoned for the life of the
-    // process: `post` is never called again while the queue keeps emptying, so every later span is
-    // dropped in silence and every timer tick mints a fresh unhandled rejection — which Bun ends
-    // the process on. Same shape as `offline-queue.ts`'s drain chain.
-    const settled = inflight.then(
+  /**
+   * At most ONE batch in flight, and at most `maxBatchSize` spans in it. The queue used to be
+   * moved wholesale into a promise chain behind the previous POST, so a stalled collector held
+   * every span ever exported — 100k with `maxQueueSize: 2048` — and the bound was a bound on the
+   * queue, not on memory. Now spans WAIT IN the queue while a POST is unsettled, where drop-oldest
+   * applies, and what is held is `maxQueueSize` plus one batch. One at a time also keeps batches
+   * in order, so a parent span never arrives after its child. A POST cannot reject (`postOtlp`
+   * degrades to a log line) and `post` catches its own serialisation throw, so nothing here can
+   * poison the next send.
+   */
+  const pump = (): Promise<void> => {
+    if (sending !== undefined) return sending;
+    const batch = queue.splice(0, maxBatchSize);
+    if (batch.length === 0) return Promise.resolve();
+    const current = post(batch).then(
       () => undefined,
       () => undefined,
     );
-    inflight = settled.then(() => post(batch));
-    return inflight;
+    sending = current.then(() => {
+      sending = undefined;
+      // A full batch waiting behind a slow POST goes next without waiting for the timer.
+      if (queue.length >= maxBatchSize) void pump();
+    });
+    return sending;
+  };
+
+  /** Everything queued NOW, batch by batch. Bounded, so a busy exporter cannot keep it looping. */
+  const drainQueue = async (): Promise<void> => {
+    let rounds = Math.ceil(queue.length / maxBatchSize) + 1;
+    while (rounds > 0) {
+      rounds -= 1;
+      await pump();
+      if (queue.length === 0 && sending === undefined) return;
+    }
   };
 
   // Unref'd, so a pending flush never holds a draining process open — `shutdown()` is what
   // decides the last batch leaves, exactly as `startMetricExport` defers to the drain hook.
-  const timer = setInterval(() => void drainQueue(), flushIntervalMs);
+  // `pump`, never `drainQueue`: while a POST is stalled `pump` answers the send already in flight
+  // and allocates nothing, where a drain per tick would park one more waiter per interval.
+  const timer = setInterval(() => void pump(), flushIntervalMs);
   timer.unref();
 
   return {
@@ -187,7 +210,7 @@ export function otlpSpanExporter(options: OtlpSpanExporterOptions = {}): OtlpSpa
       // the spans an operator wants during an incident are the ones happening now.
       if (queue.length >= maxQueueSize) queue.shift();
       queue.push(span);
-      if (queue.length >= maxBatchSize) void drainQueue();
+      if (queue.length >= maxBatchSize) void pump();
     },
     flush(): Promise<void> {
       return drainQueue();

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';

package/src/pending-records.ts

@@ -0,0 +1,58 @@
+/**
+ * Records answered before the page's store exists. The store is installed by the first realtime
+ * hook, and an action or query can answer earlier than that — so in a BROWSER page the handle
+ * holds the latest row per `type:key` (and the keys removed since) here, and hands them to the
+ * store once, when it is installed. Bounded by the keys themselves: a row seen twice is one entry.
+ */
+
+import type { Row } from './conflict-policy';
+import type { RecordRows } from './record-envelope';
+import type { RecordSink } from './record-sink';
+
+export interface PendingRecords extends RecordSink {
+  /** Adopts everything held into `sink`, then forgets it — a second drain adopts nothing. */
+  drainInto(sink: RecordSink): void;
+  /** Forgets everything held: the principal changed, and these rows were the previous one's. */
+  clear(): void;
+}
+
+export function pendingRecords(): PendingRecords {
+  const rows = new Map<string, Map<string, Row>>();
+  const removed = new Map<string, Set<string>>();
+  const group = <T>(table: Map<string, T>, type: string, make: () => T): T => {
+    const found = table.get(type);
+    if (found !== undefined) return found;
+    const created = make();
+    table.set(type, created);
+    return created;
+  };
+  return {
+    adopt(type: string, incoming: RecordRows): void {
+      const held = group(rows, type, () => new Map<string, Row>());
+      for (const [key, row] of Object.entries(incoming)) {
+        held.set(key, row);
+        removed.get(type)?.delete(key);
+      }
+    },
+    remove(type: string, keys: readonly string[]): void {
+      const gone = group(removed, type, () => new Set<string>());
+      for (const key of keys) {
+        rows.get(type)?.delete(key);
+        gone.add(key);
+      }
+    },
+    drainInto(sink: RecordSink): void {
+      for (const [type, held] of rows) {
+        if (held.size > 0) sink.adopt(type, Object.fromEntries(held));
+      }
+      for (const [type, gone] of removed) {
+        if (gone.size > 0) sink.remove(type, [...gone]);
+      }
+      this.clear();
+    },
+    clear(): void {
+      rows.clear();
+      removed.clear();
+    },
+  };
+}

package/src/record-envelope-openapi.ts

@@ -0,0 +1,41 @@
+/**
+ * The ONE OpenAPI description of the records envelope, for every operation that answers one —
+ * `@ultimat3/action`'s and `@ultimat3/query`'s projections both build their 200 from it. The rule
+ * it serves: an operation decides ONCE, from its schema, whether it answers `{ data, records }`,
+ * so each operation has exactly one body shape and one header, never a `oneOf` over "sometimes".
+ */
+
+import { RECORDS_HEADER } from './record-envelope';
+
+/** The 200 body: the operation's own answer under `data`, the rows it carried beside it. */
+export function recordEnvelopeSchema(
+  data: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  return {
+    type: 'object',
+    required: ['data', 'records'],
+    properties: {
+      data,
+      records: {
+        type: 'object',
+        description:
+          'Entity rows in `data`, keyed by record type and then by record key, for the client record store. May be empty.',
+        additionalProperties: { type: 'object', additionalProperties: { type: 'object' } },
+      },
+      removed: {
+        type: 'object',
+        description: 'Record keys the client store must drop, keyed by record type.',
+        additionalProperties: { type: 'array', items: { type: 'string' } },
+      },
+    },
+  };
+}
+
+/** The header beside that body. Always `1` on an operation that answers the envelope at all. */
+export const RECORDS_OPENAPI_HEADER: Readonly<Record<string, unknown>> = Object.freeze({
+  [RECORDS_HEADER]: {
+    description: 'Always `1`: the body is a record envelope and the operation answer is `data`.',
+    required: true,
+    schema: { type: 'string', enum: ['1'] },
+  },
+});