@rindle/room 0.5.0

package/pkg/rindle_room_bg.wasm.d.ts

@@ -0,0 +1,45 @@
+/* tslint:disable */
+/* eslint-disable */
+export const memory: WebAssembly.Memory;
+export const __rindle_room_wasm_start: () => void;
+export const __wbg_wasmroom_free: (a: number, b: number) => void;
+export const wasmroom_ack: (a: number, b: number, c: number) => [number, number, number, number];
+export const wasmroom_ackedLmid: (a: number, b: number, c: number) => number;
+export const wasmroom_appliedMid: (a: number, b: number, c: number) => number;
+export const wasmroom_apply: (a: number, b: number, c: number) => [number, number, number, number];
+export const wasmroom_beginFlush: (a: number) => [number, number, number, number];
+export const wasmroom_beginMutation: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+export const wasmroom_commitAll: (a: number) => [number, number];
+export const wasmroom_commitMutation: (a: number) => [number, number, number, number];
+export const wasmroom_cv: (a: number) => [number, number];
+export const wasmroom_dirtyLen: (a: number) => number;
+export const wasmroom_durableLmid: (a: number, b: number, c: number) => number;
+export const wasmroom_enableWrites: (a: number, b: number, c: number) => [number, number];
+export const wasmroom_enableWritesV2: (a: number, b: number, c: number) => [number, number];
+export const wasmroom_epoch: (a: number) => number;
+export const wasmroom_flushConflict: (a: number, b: number, c: number) => [number, number, number, number];
+export const wasmroom_flushInFlight: (a: number) => number;
+export const wasmroom_flushOk: (a: number) => [number, number, number, number];
+export const wasmroom_headCv: (a: number) => number;
+export const wasmroom_isLive: (a: number) => number;
+export const wasmroom_isPoisoned: (a: number) => number;
+export const wasmroom_lmidSubscribe: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
+export const wasmroom_materializationCount: (a: number) => number;
+export const wasmroom_open: (a: number, b: number, c: number) => [number, number, number];
+export const wasmroom_pendingLen: (a: number) => number;
+export const wasmroom_rejectMutation: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmroom_seedDurable: (a: number, b: number, c: number) => [number, number, number, number];
+export const wasmroom_subscribe: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => [number, number, number, number];
+export const wasmroom_subscriberCount: (a: number) => number;
+export const wasmroom_sweep: (a: number, b: number) => [number, number, number];
+export const wasmroom_txAdd: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmroom_txEdit: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmroom_txGet: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+export const wasmroom_txRemove: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+export const wasmroom_unsubscribe: (a: number, b: number, c: number, d: number) => [number, number, number];
+export const __wbindgen_free: (a: number, b: number, c: number) => void;
+export const __wbindgen_malloc: (a: number, b: number) => number;
+export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+export const __wbindgen_externrefs: WebAssembly.Table;
+export const __externref_table_dealloc: (a: number) => void;
+export const __wbindgen_start: () => void;

package/src/authority.ts

@@ -0,0 +1,127 @@
+// The room's **write-authority seam** (RINDLE-REALTIME-DESIGN.md §5.3.1): the three
+// calls a flushing room makes against the app's authority — claim a placement epoch at
+// boot (§2.5), probe the durable lmids before journal replay (§3.3, T2's
+// committed-before-crash row), and apply one journaled batch. In every deployment shape
+// the counterpart is the API server's `/apply-row-change-txn` host ([`httpAuthority`]);
+// the P3 gate drives the same interface against an in-process mock, which is what keeps
+// the contract host-independent.
+//
+// The apply takes the **exact composed body string** the shell journaled — never a
+// re-serialized object. One flush id names one immutable byte body forever (§5.3
+// step 4): a retry, a crash-replay resubmission, and the first send all put identical
+// bytes on the wire, which is what makes the authority's `batch_hash` identity check
+// (§8.3, T6) meaningful.
+
+/** One CAS rejection in the authority's `409 conflict` body: the row's authoritative
+ *  current image (`null` = absent), keyed by table + pk cells. */
+export interface AuthorityConflict {
+  table: string;
+  pk: unknown[];
+  current: unknown[] | null;
+}
+
+/** The apply outcome. Anything else — network failure, a 5xx — is a **throw**: plain
+ *  errors retry (same body, same id; dedup absorbs a landed retry), errors marked
+ *  `fatal: true` (an identity mismatch — same id, different body — or a malformed
+ *  refusal) kill the incarnation loudly instead. */
+export type AuthorityApplyResult =
+  | { kind: "ok"; applied: boolean; cv?: number }
+  | { kind: "conflict"; conflicts: AuthorityConflict[] }
+  | { kind: "fenced"; currentEpoch?: number };
+
+export interface RoomAuthority {
+  /** Claim the placement epoch for `doc` (§2.5) — once per shell process, at boot,
+   *  AFTER resubmitting the previous incarnation's unconfirmed batches (their recorded
+   *  epochs must still be current to land). */
+  claimEpoch(doc: string): Promise<number>;
+  /** The authority's ledger lmid per client (0 = none) — the boot probe that lets
+   *  journal replay absorb already-durable mutations as dedup. */
+  lmids(doc: string, clients: string[]): Promise<Record<string, number>>;
+  /** Apply one batch: `body` is the exact journaled `/apply-row-change-txn` body
+   *  string, sent verbatim. */
+  applyRowChangeTxn(body: string): Promise<AuthorityApplyResult>;
+}
+
+/** An apply error the shell must NOT retry (retrying cannot help; something is wrong
+ *  with the batch or the room, not the network). */
+export interface FatalAuthorityError extends Error {
+  fatal: true;
+}
+
+export function fatalAuthorityError(message: string): FatalAuthorityError {
+  const e = new Error(message) as FatalAuthorityError;
+  e.fatal = true;
+  return e;
+}
+
+export interface HttpAuthorityOptions {
+  /** The API server's apply endpoint (e.g. `http://…/api/rindle/apply-row-change-txn`). */
+  applyUrl: string;
+  /** The epoch-claim endpoint (e.g. `http://…/api/rindle/claim-room-epoch`). */
+  claimUrl: string;
+  /** The lmid-probe endpoint (e.g. `http://…/api/rindle/room-lmids`). */
+  lmidsUrl: string;
+  /** Extra headers on every call — the epoch-bound flush credential rides here. */
+  headers?: Record<string, string>;
+  fetch?: typeof fetch;
+}
+
+/** The HTTP [`RoomAuthority`]: the API-server host as the room's sole counterpart
+ *  (§5.3.1). Maps `409 {error:"fenced"}` / `409 {error:"conflict"}` to their results,
+ *  a `500` mentioning a batch-identity mismatch to a fatal error, and anything else
+ *  non-OK to a retryable throw. */
+export function httpAuthority(opts: HttpAuthorityOptions): RoomAuthority {
+  const doFetch = opts.fetch ?? fetch;
+  const headers = { "content-type": "application/json", ...(opts.headers ?? {}) };
+  const post = async (url: string, body: string): Promise<Response> =>
+    doFetch(url, { method: "POST", headers, body });
+  return {
+    async claimEpoch(doc) {
+      const res = await post(opts.claimUrl, JSON.stringify({ doc }));
+      if (!res.ok) {
+        throw new Error(`claim-room-epoch failed: ${res.status} ${await res.text()}`);
+      }
+      const out = (await res.json()) as { epoch?: number };
+      if (typeof out.epoch !== "number") {
+        throw fatalAuthorityError("claim-room-epoch returned no epoch");
+      }
+      return out.epoch;
+    },
+    async lmids(doc, clients) {
+      const res = await post(opts.lmidsUrl, JSON.stringify({ doc, clients }));
+      if (!res.ok) {
+        throw new Error(`room-lmids failed: ${res.status} ${await res.text()}`);
+      }
+      const out = (await res.json()) as { lmids?: Record<string, number> };
+      return out.lmids ?? {};
+    },
+    async applyRowChangeTxn(body) {
+      const res = await post(opts.applyUrl, body);
+      if (res.status === 409) {
+        const out = (await res.json()) as {
+          error?: string;
+          currentEpoch?: number;
+          conflicts?: AuthorityConflict[];
+        };
+        if (out.error === "fenced") {
+          return { kind: "fenced", currentEpoch: out.currentEpoch };
+        }
+        if (out.error === "conflict") {
+          return { kind: "conflict", conflicts: out.conflicts ?? [] };
+        }
+        throw new Error(`apply-row-change-txn 409: ${JSON.stringify(out)}`);
+      }
+      if (!res.ok) {
+        const text = await res.text();
+        // The §8.3 identity check: same flush id, different body — OUR bug, loud,
+        // never retried (a retry re-sends the same mismatched bytes forever).
+        if (res.status === 500 && text.includes("batch identity")) {
+          throw fatalAuthorityError(`apply-row-change-txn: ${text}`);
+        }
+        throw new Error(`apply-row-change-txn failed: ${res.status} ${text}`);
+      }
+      const out = (await res.json()) as { applied?: boolean; cv?: number };
+      return { kind: "ok", applied: out.applied === true, cv: out.cv };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+// @rindle/room — the Rindle Realtime room (P0 read-only follower + P1 lease-gated
+// downstream + P2 shared optimistic writes).
+//
+// Four layers, deliberately separable:
+// - `initRoomWasm` / `WasmRoom` (src/wasm.ts): the wasm room core — rindle-room-wasm
+//   compiled to `pkg/`, host-neutral (the Durable Object shell runs the SAME artifact).
+// - `mintRoomToken` / `verifyRoomToken` (src/token.ts): the §10.1 self-authorizing
+//   signed lease token — minted by the API server (the authority), verified by any
+//   shell via WebCrypto (Node and Workers alike).
+// - `MutationTx` / `RoomJournal` (src/mutation-tx.ts, src/journal.ts): the §5.1 write
+//   plane's two seams — the §4.2 mutator interface (a shared app registry drops in
+//   verbatim) and the pluggable durable sidecar an ack means (§8.1).
+// - `createRoomShell` (src/shell.ts): the Node test shell — upstream ws subscriber of a
+//   live rindled, downstream ws server speaking the `@rindle/remote` protocol verbatim,
+//   gated by the tokens, with lease-TTL enforcement, the `/revoke` control plane, and
+//   the journaled write path.
+
+export { initRoomWasm, WasmRoom } from "./wasm.ts";
+export { createRoomShell } from "./shell.ts";
+export type {
+  DownstreamOptions,
+  RoomScopeSpec,
+  RoomShell,
+  RoomShellOptions,
+  UpstreamOptions,
+  WritesOptions,
+} from "./shell.ts";
+export { journalEntryOutcome, memoryJournal } from "./journal.ts";
+export type { RoomFlushRecord, RoomJournal, RoomJournalEntry } from "./journal.ts";
+export { fatalAuthorityError, httpAuthority } from "./authority.ts";
+export type {
+  AuthorityApplyResult,
+  AuthorityConflict,
+  HttpAuthorityOptions,
+  RoomAuthority,
+} from "./authority.ts";
+export type {
+  KeyedRow,
+  MutationTx,
+  RoomMutator,
+  RoomMutatorCtx,
+  WireValue,
+} from "./mutation-tx.ts";
+export { mintRoomToken, verifyRoomToken, RoomTokenError, scopeSpecsHash } from "./token.ts";
+export type {
+  MintRoomTokenOptions,
+  RoomTokenPayload,
+  VerifyRoomTokenOptions,
+} from "./token.ts";

package/src/journal.ts

@@ -0,0 +1,110 @@
+// The room's pluggable journal (RINDLE-REALTIME-DESIGN.md §2.2, §5.1, §8.1): the
+// durable sidecar an **ack** means. The shell appends mutation ENVELOPES under a group
+// commit and advances the author's lmid row only after `append` resolves — so `acked`
+// survives a room-process crash by construction, replayed by re-invoking the mutators
+// against the freshly re-subscribed base (§3.3; recovery is re-invocation, never effect
+// replay). Each host brings its own durability: the Durable Object shell backs this
+// with per-object transactional storage (P4); the Node test shell defaults to
+// `memoryJournal`, whose durability class is exactly "the shell process" — which is
+// what makes T2's crash matrix a plain test: hand ONE journal to a second shell and
+// the restart-with-journal failure class runs in-process.
+//
+// With P3's write-behind the journal ALSO holds the built flush batches (§5.3 step 4):
+// the exact body bytes are appended BEFORE the first send and dropped once the
+// authority confirms, so a crash-replay resubmits the same immutable body — one flush
+// id names one byte body forever (the §8.3/T6 identity property). Mutation entries
+// still grow without bound here; bounded retention (truncate ≤ the durable watermark)
+// is a host-journal concern (P4's storage journal).
+
+/** One journaled mutation: the wire envelope plus its recorded outcome. Replay applies
+ *  the OUTCOME — a non-applied (`rejected`/`deopt`) entry consumes its mid without
+ *  running the mutator. */
+export interface RoomJournalEntry {
+  clientID: string;
+  mid: number;
+  name: string;
+  args: unknown;
+  /** The connection's authenticated subject at push time (the lease token's `sub`,
+   *  shell-stamped — managed-writes §3.3): recovery is re-invocation, so identity is
+   *  an input that must survive the crash. `""` = an entry journaled before the
+   *  identity plane existed (mutators see it as unauthenticated). */
+  sub: string;
+  /** The recorded verdict (H-iv-b): `"applied"` replays by RE-INVOKING the mutator
+   *  (§3.3 — and against a moved base the re-invocation may legitimately reject or
+   *  DEOPT; the journal record is never rewritten, the shell's recorded-outcome map
+   *  reflects what the replaying incarnation produced); `"rejected"` (final — authz /
+   *  validation / unknown mutator) and `"deopt"` (the §3.3 commit gate refused; the
+   *  client was told to re-route the mutation) both replay as a consumed-mid-no-effect
+   *  WITHOUT running anything — re-judging a deopt could invent effects the client
+   *  already re-routed elsewhere. Absent = a legacy pre-H-iv-b entry: read through
+   *  {@link journalEntryOutcome}. */
+  outcome?: "applied" | "rejected" | "deopt";
+  /** Legacy pre-H-iv-b flag, superseded by {@link outcome} but still WRITTEN (`true`)
+   *  alongside BOTH non-applied outcomes: a legacy reader replays either kind as a
+   *  consumed-mid-no-effect, which is exactly right. */
+  rejected?: boolean;
+}
+
+/** The ONE reading rule for an entry's verdict across journal generations: `outcome`
+ *  when present, else the legacy `rejected` flag, else applied. */
+export function journalEntryOutcome(entry: RoomJournalEntry): "applied" | "rejected" | "deopt" {
+  return entry.outcome ?? (entry.rejected === true ? "rejected" : "applied");
+}
+
+/** One journaled flush batch: the room's flush-stream position, the placement epoch it
+ *  was built under, and the EXACT `/apply-row-change-txn` body string — resubmitted
+ *  verbatim, never rebuilt (§5.3 step 4). */
+export interface RoomFlushRecord {
+  seq: number;
+  epoch: number;
+  body: string;
+}
+
+export interface RoomJournal {
+  /** Append `entries` durably, in order. Resolving is the ack gate (§8.1): the shell
+   *  advances lmid rows only after this resolves. A rejection is fatal to the
+   *  incarnation — an ack that might not survive must never be sent. */
+  append(entries: RoomJournalEntry[]): Promise<void>;
+  /** Every entry ever appended, in append order — the boot-time replay source. */
+  replay(): Promise<RoomJournalEntry[]>;
+  /** Journal one built flush batch, BEFORE its first send. Same durability contract
+   *  as `append`: a rejection is fatal (an unjournaled batch must never reach the
+   *  wire — a retry could otherwise rebuild different bytes under the same id). */
+  appendFlush(record: RoomFlushRecord): Promise<void>;
+  /** The authority settled flush `seq` (committed, deduped, or dead) — drop it. */
+  confirmFlush(seq: number): Promise<void>;
+  /** Unconfirmed flush records in seq order, plus the highest seq ever appended
+   *  (0 = none) — the boot-time resubmission source and the seq seed. */
+  replayFlushes(): Promise<{ records: RoomFlushRecord[]; maxSeq: number }>;
+}
+
+/** An in-process journal: survives incarnations within one shell process (and, handed
+ *  to a second shell, a simulated process crash — the T2 harness). Not durable beyond
+ *  the process, by definition. */
+export function memoryJournal(): RoomJournal {
+  const log: RoomJournalEntry[] = [];
+  const flushes = new Map<number, RoomFlushRecord>();
+  let maxSeq = 0;
+  return {
+    append(entries) {
+      log.push(...entries);
+      return Promise.resolve();
+    },
+    replay() {
+      return Promise.resolve([...log]);
+    },
+    appendFlush(record) {
+      flushes.set(record.seq, record);
+      maxSeq = Math.max(maxSeq, record.seq);
+      return Promise.resolve();
+    },
+    confirmFlush(seq) {
+      flushes.delete(seq);
+      return Promise.resolve();
+    },
+    replayFlushes() {
+      const records = [...flushes.values()].sort((a, b) => a.seq - b.seq);
+      return Promise.resolve({ records, maxSeq });
+    },
+  };
+}

package/src/mutation-tx.ts

@@ -0,0 +1,275 @@
+// The room-side MutationTx (RINDLE-REALTIME-DESIGN.md §5.1; OPTIMISTIC-WRITES-DESIGN.md
+// §4.2): the write handle a room mutator runs against, structurally identical to
+// `@rindle/optimistic`'s client MutationTx — the whole point of §4.2's "two registries,
+// one interface" is that an app can register its client mutators in the room VERBATIM
+// (`mutators` from a shared app-def typechecks against `RoomMutator` as-is). Declared
+// locally rather than imported so @rindle/room does not depend on the browser client
+// stack; TS structural typing keeps the two in lockstep at the app's call site.
+//
+// Backing: the wasm room's staged transaction (txGet/txAdd/txEdit/txRemove). Only
+// concrete cells cross the JSON boundary — `undefined` ("leave unchanged") in the
+// positional `edit` and the partial keyed `update` is resolved HERE against the
+// effective row (`txGet`: live head under this tx's own staged writes), the same merge
+// the browser WriteTxn does at its staging boundary. Reads are read-your-writes by
+// construction. Every refusal below (unknown column, width, presence) throws — the
+// shell catches a mutator throw and turns the whole mutation into a reject.
+
+import type { WasmRoom } from "./wasm.ts";
+
+/** A bare wire cell (the client stack's `WireValue`). */
+export type WireValue = number | string | boolean | null;
+/** A row keyed by column name. */
+export type KeyedRow = Record<string, WireValue>;
+
+/** The §4.2 write handle. Keyed methods are schema-checked; positional methods are the
+ *  raw wire shape (cells in schema column order, pk cells in `primaryKey` order).
+ *  `query` is not available in room mutators yet (it throws) — typed so a client
+ *  registry that uses it still registers, and fails loudly at run time. */
+export interface MutationTx {
+  /** Read one row by primary key (e.g. `tx.row("issue", { id: 1 })`). */
+  row(table: string, pk: KeyedRow): KeyedRow | undefined;
+  /** Insert a FULL row (every column named; missing or unknown columns throw). */
+  insert(table: string, row: KeyedRow): void;
+  /** Update the row identified by the pk columns; only the named non-pk columns
+   *  change. A missing row is a NO-OP (rebase-friendly). */
+  update(table: string, row: KeyedRow): void;
+  /** Insert, or fully replace when the pk already exists (a FULL row, like insert). */
+  upsert(table: string, row: KeyedRow): void;
+  /** Delete the row identified by the pk columns. A missing row is a NO-OP. */
+  delete(table: string, pk: KeyedRow): void;
+  /** NOT SUPPORTED in room mutators yet — throws. (Typed to accept the client
+   *  builder's queries so shared registries typecheck.) */
+  query(query: { ast(): unknown }): never;
+  // --- positional (the wire shape) ---
+  get(table: string, pk: WireValue[]): WireValue[] | undefined;
+  add(table: string, row: WireValue[]): void;
+  remove(table: string, row: WireValue[]): void;
+  edit(table: string, oldRow: WireValue[], newRow: (WireValue | undefined)[]): void;
+}
+
+/** The ambient authorization context a room mutator runs under (managed-writes design
+ *  §3.2). Shell-stamped from the connection's DO-verified lease token — NEVER
+ *  client-supplied — so per-row/per-field rules checked against it are trustworthy.
+ *  The shape deliberately matches the shared-generator drivers' `ctx.user`, so one
+ *  registry body runs identically in all three homes (client / api-server / room). */
+export interface RoomMutatorCtx {
+  /** The authenticated subject (the lease token's `sub`). `""` on replay of an entry
+   *  journaled before the identity plane — treat as unauthenticated. */
+  user: string;
+}
+
+/** A room mutator: deterministic, replayable — re-invoked on journal replay against
+ *  the freshly re-subscribed base (§3.3), so the same purity rules as a client
+ *  mutator apply (no clock, no randomness, a pure function of `(base, args, ctx)`).
+ *  An auth check against `ctx` re-runs on replay against the freshly rebuilt base —
+ *  a mutation that passed before a crash can replay as rejected if the permission
+ *  row changed in between; that is §3.3's intended rebase behavior. */
+export type RoomMutator = (tx: MutationTx, args: never, ctx: RoomMutatorCtx) => void;
+
+/**
+ * Tag an error as an ENVIRONMENT shortfall (H-iv-b): the room lacks a capability the
+ * mutation needs (today: `tx.query`), which is a verdict about the ROOM, not the
+ * mutation — the shell classifies it as a DEOPT (the client re-routes the mutation to
+ * the daemon stream, where the capability exists) instead of a FINAL rejection (which
+ * would drop the mutation). Contrast a validation/authz throw: re-routing can't help
+ * those, so they stay `rejected`.
+ */
+export function environmentShortfall(message: string): Error {
+  const e = new Error(message);
+  (e as { roomEnvironmentShortfall?: boolean }).roomEnvironmentShortfall = true;
+  return e;
+}
+
+/** Whether `e` was tagged by {@link environmentShortfall}. */
+export function isEnvironmentShortfall(e: unknown): boolean {
+  return (
+    (e as { roomEnvironmentShortfall?: boolean } | null)?.roomEnvironmentShortfall === true
+  );
+}
+
+/**
+ * Guard against the two mutator shapes that would corrupt silently instead of failing loudly.
+ * A `shared(...)` GENERATOR registered verbatim returns an un-iterated generator — zero writes,
+ * acked as applied (data loss); an ASYNC mutator runs synchronously only to its first `await`,
+ * so later writes land OUTSIDE the committed transaction. Both shells call this on the
+ * mutator's return value inside their try/reject path, so either shape becomes an explicit
+ * rejection with a pointed message. (An adapter that DRIVES a shared generator registry against
+ * the room tx is future work — managed-writes design §8.)
+ */
+export function assertSyncMutatorReturn(returned: unknown, name: string): void {
+  if (returned === undefined || returned === null) return;
+  const r = returned as { next?: unknown; then?: unknown };
+  if (typeof r.then === "function") {
+    throw new Error(
+      `mutator \`${name}\` returned a promise — room mutators must be synchronous ` +
+        `(writes after an \`await\` would land outside the transaction)`,
+    );
+  }
+  if (typeof r.next === "function") {
+    throw new Error(
+      `mutator \`${name}\` returned a generator — a shared(...) registry cannot register ` +
+        `verbatim as room mutators (nothing would drive it; zero writes would be acked). ` +
+        `Write plain synchronous (tx, args, ctx) mutators for the room bundle.`,
+    );
+  }
+}
+
+/** One table's positional shape, parsed from the upstream hello. */
+export interface TableShape {
+  columns: string[];
+  /** Indices into `columns`. */
+  primaryKey: number[];
+}
+
+function shapeOf(shapes: Map<string, TableShape>, table: string): TableShape {
+  const s = shapes.get(table);
+  if (!s) throw new Error(`unknown table \`${table}\``);
+  return s;
+}
+
+/** pk cells (primaryKey order) from a keyed probe — every pk column must be named. */
+function keyedPk(shape: TableShape, table: string, pk: KeyedRow): WireValue[] {
+  return shape.primaryKey.map((c) => {
+    const name = shape.columns[c];
+    const v = pk[name];
+    if (v === undefined) {
+      throw new Error(`missing primary-key column \`${name}\` for \`${table}\``);
+    }
+    return v;
+  });
+}
+
+function assertKnownColumns(shape: TableShape, table: string, row: KeyedRow): void {
+  for (const name of Object.keys(row)) {
+    if (!shape.columns.includes(name)) {
+      throw new Error(`unknown column \`${name}\` for \`${table}\``);
+    }
+  }
+}
+
+/** Build the MutationTx for one open wasm transaction. Valid only while that
+ *  transaction is open — the shell creates one per mutation and never retains it. */
+export function mutationTx(room: WasmRoom, shapes: Map<string, TableShape>): MutationTx {
+  const getRow = (table: string, pkCells: WireValue[]): WireValue[] | undefined => {
+    const text = room.txGet(table, JSON.stringify(pkCells));
+    return text === undefined ? undefined : (JSON.parse(text) as WireValue[]);
+  };
+  /** Resolve `undefined` cells ("leave unchanged") against the effective row; the
+   *  row must exist. Only concrete cells may cross the JSON boundary — a stringified
+   *  `undefined` would silently become `null`. */
+  const resolveCells = (
+    table: string,
+    shape: TableShape,
+    cells: (WireValue | undefined)[],
+  ): WireValue[] | undefined => {
+    if (cells.length !== shape.columns.length) {
+      throw new Error(`row width does not match the schema of \`${table}\``);
+    }
+    const pkCells = shape.primaryKey.map((c) => {
+      const v = cells[c];
+      if (v === undefined) {
+        throw new Error(`primary-key cells must be concrete (\`${table}\`)`);
+      }
+      return v;
+    });
+    const current = getRow(table, pkCells);
+    if (cells.every((v) => v !== undefined)) return cells as WireValue[];
+    if (current === undefined) return undefined;
+    return cells.map((v, i) => (v === undefined ? current[i] : v)) as WireValue[];
+  };
+
+  return {
+    row(table, pk) {
+      const shape = shapeOf(shapes, table);
+      const cells = getRow(table, keyedPk(shape, table, pk));
+      if (cells === undefined) return undefined;
+      const out: KeyedRow = {};
+      shape.columns.forEach((name, i) => (out[name] = cells[i]));
+      return out;
+    },
+    insert(table, row) {
+      const shape = shapeOf(shapes, table);
+      assertKnownColumns(shape, table, row);
+      const cells = shape.columns.map((name) => {
+        const v = row[name];
+        if (v === undefined) {
+          throw new Error(`insert of \`${table}\` is missing column \`${name}\``);
+        }
+        return v;
+      });
+      room.txAdd(table, JSON.stringify(cells));
+    },
+    update(table, row) {
+      const shape = shapeOf(shapes, table);
+      assertKnownColumns(shape, table, row);
+      const pkCells = keyedPk(shape, table, row);
+      const current = getRow(table, pkCells);
+      if (current === undefined) return; // rebase-friendly no-op
+      const cells = shape.columns.map((name, i) => {
+        const v = row[name];
+        return v === undefined ? current[i] : v;
+      });
+      room.txEdit(table, JSON.stringify(cells));
+    },
+    upsert(table, row) {
+      const shape = shapeOf(shapes, table);
+      assertKnownColumns(shape, table, row);
+      const cells = shape.columns.map((name) => {
+        const v = row[name];
+        if (v === undefined) {
+          throw new Error(`upsert of \`${table}\` is missing column \`${name}\``);
+        }
+        return v;
+      });
+      const pkCells = keyedPk(shape, table, row);
+      if (getRow(table, pkCells) === undefined) {
+        room.txAdd(table, JSON.stringify(cells));
+      } else {
+        room.txEdit(table, JSON.stringify(cells));
+      }
+    },
+    delete(table, pk) {
+      const shape = shapeOf(shapes, table);
+      const pkCells = keyedPk(shape, table, pk);
+      if (getRow(table, pkCells) === undefined) return; // rebase-friendly no-op
+      room.txRemove(table, JSON.stringify(pkCells));
+    },
+    query() {
+      // An environment shortfall, not a mutation verdict: the shell classifies this
+      // throw as a DEOPT so the client re-routes to the daemon stream (H-iv-b).
+      throw environmentShortfall("tx.query is not supported in room mutators yet");
+    },
+    get(table, pk) {
+      shapeOf(shapes, table);
+      return getRow(table, pk);
+    },
+    add(table, row) {
+      const shape = shapeOf(shapes, table);
+      if (row.some((v) => v === undefined)) {
+        throw new Error(`add of \`${table}\`: cells must be concrete`);
+      }
+      if (row.length !== shape.columns.length) {
+        throw new Error(`row width does not match the schema of \`${table}\``);
+      }
+      room.txAdd(table, JSON.stringify(row));
+    },
+    remove(table, row) {
+      const shape = shapeOf(shapes, table);
+      if (row.length !== shape.columns.length) {
+        throw new Error(`row width does not match the schema of \`${table}\``);
+      }
+      room.txRemove(table, JSON.stringify(shape.primaryKey.map((c) => row[c])));
+    },
+    edit(table, _oldRow, newRow) {
+      // The authority composes `old` from its own effective read (the wasm side);
+      // the caller's oldRow is its *prediction* of old — unused here, kept in the
+      // signature for client-registry compatibility.
+      const shape = shapeOf(shapes, table);
+      const resolved = resolveCells(table, shape, newRow);
+      if (resolved === undefined) {
+        throw new Error(`no row with that primary key in \`${table}\``);
+      }
+      room.txEdit(table, JSON.stringify(resolved));
+    },
+  };
+}