@ultimat3/core 20.2.1 → 21.0.0

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'] },
+  },
+});

package/src/record-envelope.ts

@@ -0,0 +1,98 @@
+/**
+ * The records envelope: an action's or a query's answer plus the entity rows it touched, so the
+ * page's one store adopts them on the way past. Used ONLY behind `RECORDS_HEADER`, which is what
+ * keeps an output with no entity rows byte-identical on the wire. Pure and schema-free — the rows
+ * are validated by whoever owns the sink, never here.
+ */
+
+import type { Row } from './conflict-policy';
+import { UltimateError } from './errors';
+import { isJsonObject } from './json-object';
+
+/** Set to `1` on a response whose body is a `RecordEnvelope` rather than the bare output. */
+export const RECORDS_HEADER = 'x-ultimate-records';
+
+/** One record type's rows, keyed by record key — the browser cannot derive a key without the entity. */
+export type RecordRows = Readonly<Record<string, Row>>;
+
+export interface RecordEnvelope<T = unknown> {
+  readonly data: T;
+  /** Rows to adopt: record type -> record key -> row. */
+  readonly records?: Readonly<Record<string, RecordRows>>;
+  /** Record keys to drop, keyed by the entity's record type. */
+  readonly removed?: Readonly<Record<string, readonly string[]>>;
+}
+
+/** The server half. An empty `removed` is omitted, so the envelope never claims a deletion. */
+export function encodeRecordEnvelope<T>(
+  data: T,
+  records: Readonly<Record<string, RecordRows>>,
+  removed?: Readonly<Record<string, readonly string[]>>,
+): RecordEnvelope<T> {
+  const hasRemoved = removed !== undefined && Object.keys(removed).length > 0;
+  return hasRemoved ? { data, records, removed } : { data, records };
+}
+
+/**
+ * The client half: a parsed body, checked for shape and copied onto null-prototype maps — a
+ * record type and a record key are server data, and `JSON.parse` mints `__proto__` as a real own
+ * key, which assigned onto a plain object would replace its prototype.
+ */
+export function decodeRecordEnvelope(body: unknown): RecordEnvelope {
+  if (!isJsonObject(body) || !Object.hasOwn(body, 'data')) {
+    throw envelopeInvalid('the body', 'is not an object with an own "data" member');
+  }
+  const records = byType(body['records'], 'records', (rows, at) => {
+    if (!isJsonObject(rows)) throw envelopeInvalid(at, 'is not an object of rows by key');
+    return nullProto(
+      Object.entries(rows).map(([key, row], index): [string, Row] => {
+        if (!isJsonObject(row)) throw envelopeInvalid(`${at} row #${index}`, 'is not an object');
+        return [key, row];
+      }),
+    );
+  });
+  const removed = byType(body['removed'], 'removed', (keys, at) => {
+    if (!Array.isArray(keys)) throw envelopeInvalid(at, 'is not an array');
+    const list: unknown[] = keys;
+    const bad = list.findIndex((key) => typeof key !== 'string');
+    if (bad !== -1) throw envelopeInvalid(`${at} key #${bad}`, 'is not a string');
+    return list as string[];
+  });
+  return {
+    data: body['data'],
+    ...(records === undefined ? {} : { records }),
+    ...(removed === undefined ? {} : { removed }),
+  };
+}
+
+function byType<T>(
+  value: unknown,
+  member: string,
+  read: (group: unknown, at: string) => T,
+): Readonly<Record<string, T>> | undefined {
+  if (value === undefined) return undefined;
+  if (!isJsonObject(value)) throw envelopeInvalid(`"${member}"`, 'is not an object');
+  return nullProto(
+    Object.entries(value).map(([type, group], index): [string, T] => [
+      type,
+      read(group, `"${member}" entry #${index}`),
+    ]),
+  );
+}
+
+function nullProto<T>(entries: readonly (readonly [string, T])[]): Record<string, T> {
+  const out = Object.create(null) as Record<string, T>;
+  for (const [key, value] of entries) {
+    Object.defineProperty(out, key, { value, enumerable: true });
+  }
+  return out;
+}
+
+/** Positions only, never the value: the body is whatever answered, and may carry anything. */
+function envelopeInvalid(where: string, what: string): UltimateError {
+  return new UltimateError({
+    code: 'X_CLIENT_RECORD_ENVELOPE_INVALID',
+    cause: `a response marked ${RECORDS_HEADER}: 1 carried a body where ${where} ${what}`,
+    fix: 'build the body with encodeRecordEnvelope() from @ultimat3/core in the handler that set the header, or stop setting the header',
+  });
+}

package/src/record-sink.ts

@@ -0,0 +1,129 @@
+/**
+ * The ONE per-tab client handle, and the seam records flow through into it. Every island bundle
+ * carries its own copy of `@ultimat3/core`, so a module-scope singleton here would be one store
+ * PER ISLAND; the handle lives on `globalThis` under one `Symbol.for` key instead — the pattern
+ * `ultimate.error` already uses — and every copy resolves the same object.
+ */
+
+import type { ClientScope } from './client-scope';
+import { CLIENT_SCOPE_META } from './page-meta';
+import type { PendingRecords } from './pending-records';
+import { pendingRecords } from './pending-records';
+import type { RecordRows } from './record-envelope';
+
+/**
+ * Where decoded records land. `@ultimat3/realtime` installs the store. `adopt` MUST be idempotent
+ * per `recordType + key`: a deduped read hands one answer to several callers and each adopts it.
+ */
+export interface RecordSink {
+  /** `rows` is record key -> row: the key is the server's, the browser cannot derive it. */
+  adopt(recordType: string, rows: RecordRows): void;
+  remove(recordType: string, keys: readonly string[]): void;
+}
+
+export interface PageClient {
+  /**
+   * The record store — `undefined` until realtime installs one. ASSIGNING it is the one install
+   * path: records answered before then are held (browser pages only) and adopted into the new
+   * store once, on assignment. With no `document` (SSR, a test, a server) they are dropped.
+   */
+  store: RecordSink | undefined;
+  /** The page's one socket — typed by `@ultimat3/realtime`, which fills it. */
+  socket: unknown;
+  /** Who the page is acting for right now. Read-only here: `rescope()` is the one writer. */
+  readonly scope: ClientScope;
+}
+
+/** The mutable half `client-scope.ts` owns. On the handle, so every module copy shares it. */
+export interface ScopeCell {
+  current: ClientScope;
+  readonly listeners: Set<(next: ClientScope, prev: ClientScope) => void>;
+}
+
+/** Headers every outbound request carries, or nothing. See `outbound-headers.ts`. */
+export type OutboundHeaders = () => Readonly<Record<string, string>>;
+
+interface PageClientHandle extends PageClient {
+  readonly scopeCell: ScopeCell;
+  /** The early-records buffer, or `undefined` where there is no page to install a store on. */
+  readonly pending: PendingRecords | undefined;
+  outboundHeaders: OutboundHeaders | undefined;
+}
+
+const HANDLE_KEY: unique symbol = Symbol.for('ultimate.client');
+
+type HandleHost = { [HANDLE_KEY]?: PageClientHandle };
+
+/** Get-or-create. The only `globalThis` write in the client seam, and it happens on first call. */
+export function pageClient(): PageClient {
+  return handle();
+}
+
+/** The scope cell behind `pageClient().scope`. Internal: `client-scope.ts` is its one caller. */
+export function scopeCell(): ScopeCell {
+  return handle().scopeCell;
+}
+
+/**
+ * Where decoded records go RIGHT NOW: the installed store, else the browser's pending buffer, else
+ * nowhere. Internal: `client-transport.ts` is its one caller.
+ */
+export function recordSink(): RecordSink | undefined {
+  const client = handle();
+  return client.store ?? client.pending;
+}
+
+/** The early-records buffer, for `rescope()` to clear. Internal. */
+export function heldRecords(): PendingRecords | undefined {
+  return handle().pending;
+}
+
+/** The outbound-header slot. Internal: `outbound-headers.ts` writes it, the dispatch reads it. */
+export function outboundSlot(): { outboundHeaders: OutboundHeaders | undefined } {
+  return handle();
+}
+
+/**
+ * The principal the server rendered into the page, read ONCE, when the handle is created. Three
+ * answers: the tag's content, `null` for an empty tag (anonymous), `undefined` for no tag or no
+ * `document` at all (unscoped — nobody's page). A later change is `rescope()`'s, never a re-read.
+ */
+function renderedPrincipal(): string | null | undefined {
+  const doc: { querySelector?: (selector: string) => { content?: unknown } | null } | undefined =
+    Reflect.get(globalThis, 'document');
+  const tag = doc?.querySelector?.(`meta[name="${CLIENT_SCOPE_META}"]`);
+  if (tag === undefined || tag === null) return undefined;
+  return typeof tag.content === 'string' && tag.content !== '' ? tag.content : null;
+}
+
+function handle(): PageClientHandle {
+  const host = globalThis as HandleHost;
+  const existing = host[HANDLE_KEY];
+  if (existing !== undefined) return existing;
+  const cell: ScopeCell = {
+    current: { principal: renderedPrincipal(), epoch: 0 },
+    listeners: new Set(),
+  };
+  const pending = Reflect.has(globalThis, 'document') ? pendingRecords() : undefined;
+  let store: RecordSink | undefined;
+  const created: PageClientHandle = {
+    socket: undefined,
+    scopeCell: cell,
+    pending,
+    outboundHeaders: undefined,
+    get store(): RecordSink | undefined {
+      return store;
+    },
+    set store(next: RecordSink | undefined) {
+      store = next;
+      if (next !== undefined) pending?.drainInto(next);
+    },
+    get scope(): ClientScope {
+      return cell.current;
+    },
+  };
+  // Non-enumerable, so a test harness or a devtools dump walking `globalThis` never serialises
+  // the store through it.
+  Object.defineProperty(host, HANDLE_KEY, { value: created, configurable: true });
+  return created;
+}

package/src/schema-error-codes.ts

@@ -23,7 +23,7 @@ export const SCHEMA_ERROR_CODE_TITLES: Readonly<Record<string, string>> = Object
   ),
 );
 
-// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
+// Registered here rather than in `core-error-codes.ts`'s `CORE_CODE_TITLES` because core does not own
 // these codes — `@ultimat3/schema` does — and `registerErrorCodes` is the one mechanism that
 // raises `X_ERROR_CODE_DUPLICATE` if a package that DOES own one of them ever tries to register it
 // too, which pins ownership even though the registration happens here.

package/src/secrets-errors.ts

@@ -30,7 +30,7 @@ const SECRETS_ERROR_TITLES: Readonly<Record<SecretsErrorCode, string>> = {
   X_SECRETS_PLAINTEXT_INVALID: 'the decrypted secrets are not a flat map of env values',
 };
 
-// Registered here rather than in `error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
+// Registered here rather than in `core-error-codes.ts`'s `CORE_CODE_TITLES` because these codes and the
 // module that throws them ship together: `registerErrorCodes` is the documented way a set of codes
 // joins the registry, and it raises `X_ERROR_CODE_DUPLICATE` if anything else ever claims one.
 registerErrorCodes(

package/src/service.ts

@@ -64,3 +64,12 @@ export function installedServices(ctx: CtxFacts): ServiceBag {
 export function resetServices(): void {
   factories.clear();
 }
+
+/**
+ * The names `installedServices` would build, without building them. `@ultimat3/http` binds each as
+ * a lazy member of a request context, because the actor a request's services must close over is
+ * only known once its `auth` stage has run — after the context exists.
+ */
+export function registeredServiceNames(): readonly string[] {
+  return [...factories.keys()];
+}

package/src/telemetry.ts

@@ -8,6 +8,7 @@ import { tryUseContext } from './context';
 import { renderThrowable } from './error-render';
 import { isUltimateError } from './errors';
 import { isSpanId, isTraceId, spanId as newSpanId, traceId as newTraceId } from './ids';
+import { installTraceHeaders } from './outbound-headers';
 import { defaultSampler, resetDefaultSampler, type Sampler } from './sampler';
 
 export type SpanKind = 'internal' | 'server' | 'client' | 'producer' | 'consumer';
@@ -194,6 +195,8 @@ function inboundParent(parent: SpanContext | undefined): SpanContext | undefined
 }
 
 export function startSpan(name: string, options?: StartSpanOptions): Span {
+  // A live span is what gives an outbound typed call a trace to continue; see the module.
+  installTraceHeaders();
   const parent = options?.parent ?? currentSpanContext();
   const inbound = inboundParent(parent);
   const attributes: Record<string, AttributeValue> = { ...(options?.attributes ?? {}) };

package/src/write-digest.ts

@@ -0,0 +1,29 @@
+// A write's public name: the digest of the idempotency key the page sent it under. The server
+// stamps it on every `records` frame the write produced; the page computes the same digest from
+// its own key, so it can tell its own echo from somebody else's change. A digest, never the key:
+// a frame fans out to every member of the channel, and the key is only the writer's to show.
+
+/** Hex characters kept from the SHA-256: 128 bits, no collision between two writes in flight. */
+export const WRITE_DIGEST_LENGTH = 32;
+
+const WRITE_DIGEST_SHAPE = /^[0-9a-f]{32}$/;
+
+/** Whether `value` is a write digest as this module mints one — what a decoder admits. */
+export function isWriteDigest(value: unknown): value is string {
+  return typeof value === 'string' && WRITE_DIGEST_SHAPE.test(value);
+}
+
+/**
+ * SHA-256 of the key, hex, first `WRITE_DIGEST_LENGTH` characters. `undefined` where the runtime
+ * has no `crypto.subtle` — a browser page served over plain HTTP from a host that is not
+ * `localhost`. The page then names none of its writes and every frame is a plain merge, which is
+ * the behaviour before frames named their write: a flicker at worst, never a wrong row.
+ */
+export async function writeDigest(key: string): Promise<string | undefined> {
+  const subtle: SubtleCrypto | undefined = globalThis.crypto?.subtle;
+  if (subtle === undefined) return undefined;
+  const bytes = new Uint8Array(await subtle.digest('SHA-256', new TextEncoder().encode(key)));
+  let hex = '';
+  for (const byte of bytes) hex += byte.toString(16).padStart(2, '0');
+  return hex.slice(0, WRITE_DIGEST_LENGTH);
+}

package/src/write-origin.ts

@@ -0,0 +1,31 @@
+// The write in flight on the server: the digest of the idempotency key the request that is
+// running arrived with. `@ultimat3/action`'s HTTP projection opens the scope; the layers that turn
+// a committed row into a `records` frame read it — entity's row observer in-process, and the
+// Postgres driver, which writes it into the WAL for the replicator to find. Server-only: it rides
+// core's one `AsyncLocalStorage` seam, which a browser bundle does not have.
+
+import { asyncContext } from './async-context';
+import { isWriteDigest } from './write-digest';
+
+const origin = asyncContext<string>('the write origin');
+
+/**
+ * The `pg_logical_emit_message` prefix a keyed write's transaction opens with, its content the
+ * digest. `@ultimat3/entity`'s Postgres driver writes it; `@ultimat3/realtime`'s replication stream
+ * reads it and names every change of that transaction. One constant, so the two cannot drift.
+ */
+export const WRITE_ORIGIN_WAL_PREFIX = 'ultimate.write';
+
+/**
+ * Run `fn` as the write named `digest` (`writeDigest(key)`). Anything but a digest runs `fn`
+ * unnamed — the scope is a label on frames, never a gate, so a malformed one costs the page its
+ * echo match and nothing else.
+ */
+export function withWriteOrigin<T>(digest: string | undefined, fn: () => T): T {
+  return isWriteDigest(digest) ? origin.run(digest, fn) : fn();
+}
+
+/** The digest of the write this code runs inside, or `undefined` outside every keyed write. */
+export function currentWriteOrigin(): string | undefined {
+  return origin.get();
+}