@rindle/optimistic 0.1.0-rc.5

package/src/backend.ts

@@ -0,0 +1,1155 @@
+// OptimisticBackend — the composition that adds OPTIMISTIC WRITES to the normalized
+// local-first path (OPTIMISTIC-WRITES-DESIGN.md §8.5, §9). The richer cousin of
+// `NormalizedBackend`: the same substrate (a local `@rindle/wasm` engine + a server
+// stream + `NormalizedSync`), plus
+//
+//   - a **named client-mutator registry**: `invoke("createIssue", args)` runs the
+//     mutator against the live engine NOW (the prediction shows instantly), pushes
+//     `(mid, name, args)` — never effects — onto the pending stack, and ships the
+//     envelope upstream (§4);
+//   - **lmid-as-data**: at construction the backend subscribes its own one-row
+//     SYSTEM QUERY (`LMID_QUERY_NAME` → `_rindle_client_mutations WHERE client_id =
+//     me`). The server writes `lmid` in the SAME transaction as a mutation's
+//     effects, so the confirmation arrives as an ordinary cv-tagged data frame and
+//     is released by the same `cvMin` — confirmation can never skew from the data
+//     of its own commit (the drain race the old frame-carried lmid suffered);
+//   - **cv-buffering**: every `cv`-tagged data frame buffers; a progress frame
+//     releases all `cv ≤ cvMin` as ONE coherent step — data ops into the engine's
+//     `sync` side, lmid-table ops into `confirmedLmid` (§1.3.1/§8.5 — no torn reads
+//     across queries, no apply ahead of the release point);
+//   - the **§1.3 reconcile cycle** per release: the wasm engine rewinds
+//     (`serverBatchBegin`), every still-pending mutator is **re-invoked** against the
+//     rebased base (read-dependent mutators read current values — §4.1), and the
+//     whole cycle coalesces to one minimal delivery (`serverBatchEnd`) — a
+//     confirmed-correct prediction produces zero churn;
+//   - per-query **ResultType** is the SERVER CHANNEL's state only (FOLDED-MUTATIONS-DESIGN
+//     §7): `unknown` while not hydrated, else `complete`. A pending local mutation no longer
+//     moves it — "is a prediction pending here?" is its own reactive axis (`pending(qid)` /
+//     `onPending`), so a fold held through its debounce window doesn't pin a query loading.
+//     There is NO server rejection signal: a failed mutation is processed-as-no-op (lmid
+//     advances, effects rolled back) and the prediction snaps back on the ordinary release.
+//   - **folded mutations** (FOLDED-MUTATIONS-DESIGN): `invokeFolded` collapses a run of
+//     same-key absorbing writes to ONE pending entry whose `args` are overwritten in place,
+//     debounces the server write (a virtual `clock` seam keeps it test-deterministic), and
+//     ships only the last value. The `mid` is assigned at FLUSH (not invoke), so the gapless
+//     wire sequence is preserved under debounce (§4.1); an overlapping non-fold write drains
+//     the interacting fold first (`drainOverlapping`, §4.2 flush-on-enqueue).
+//
+// `Store`/`ArrayView` are untouched: this implements `Backend`, so
+// `new Store(schema, new OptimisticBackend(...))` reuses the whole machinery.
+
+import { CLIENT_MUTATIONS_SCHEMA, LMID_QUERY_NAME, normalizedTableSchemas, tableSpec } from "@rindle/client";
+import type {
+  Ast,
+  Backend,
+  ChangeEvent,
+  ColsMap,
+  Mutation,
+  NormalizedEvent,
+  NormalizedOp,
+  NormalizedTableSchema,
+  OptimisticSource,
+  ProgressFrame,
+  QueryId,
+  RemoteQuery,
+  ResultType,
+  Schema,
+  WireValue,
+} from "@rindle/client";
+import { aggTableSchemas, NormalizedSync, rewriteAggregates, type ColCounts, type PkCols } from "@rindle/normalized";
+import { WasmBackend, type ServerDeltaOp, type WasmWriteTxn } from "@rindle/wasm";
+
+import { AggOverlay, type ChildOp, collectAggDefs } from "./agg-overlay.ts";
+
+/** A keyed row: column name → cell. The ergonomic shape — column names are validated
+ *  against the schema at runtime, so a typo throws immediately with the valid names. */
+export type KeyedRow = Record<string, WireValue>;
+
+/** The write handle a client mutator runs against (the client `MutationTx`, §4.2):
+ *  reads see the current base + this transaction's own staged writes (§4.1).
+ *
+ *  Prefer the KEYED methods (`insert`/`update`/`upsert`/`delete`/`row`) — named columns,
+ *  schema-checked. The positional methods (`get`/`add`/`remove`/`edit`) are the raw wire
+ *  shape: bare cells in schema column order, `pk` cells in `primaryKey` order. */
+export interface MutationTx {
+  // --- keyed (schema-aware) ---
+  /** 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: the row may have vanished upstream). */
+  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;
+  // --- 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[]): void;
+}
+
+/** A client mutator: optimistic, deterministic, replayable — a pure function of
+ *  `(base, args)` (§5: no clock, no randomness; it is RE-INVOKED on every rebase). */
+export type ClientMutator = (tx: MutationTx, args: never) => void;
+
+/** The client registry (§4.2) — one of the two registries; the server's authoritative
+ *  twin shares names (and possibly code), never the wire. */
+export type ClientRegistry = Record<string, ClientMutator>;
+
+export type { ResultType };
+
+/** The reserved source-qid of the backend's own lmid system query. User/local query ids
+ *  are assigned by the `Store` starting at 1, so 0 never collides. */
+const LMID_QID: QueryId = 0;
+
+interface PendingMutation {
+  /** The wire mutation id. A FOLDED entry carries `null` until its window flushes — the `mid`
+   *  is dealt from `nextMid` in SEND order, never reserved at invoke, so the wire sequence stays
+   *  gapless under debounce (FOLDED-MUTATIONS-DESIGN §4.1). A `null` entry is never confirmable
+   *  (the confirm-drop retains it) and re-invokes AFTER every assigned mid (sorted by `mid ?? ∞`). */
+  mid: number | null;
+  name: string;
+  args: unknown;
+  /** Tables this mutator touched at its LAST invocation (drives the pending axis, §7.2). */
+  touched: Set<string>;
+}
+
+/** A virtual-clock seam for the fold debounce/maxWait timers (FOLDED-MUTATIONS-DESIGN §9): the
+ *  oracle injects a deterministic scheduler; production defaults to real timers + `Date.now`. */
+export interface FoldClock {
+  setTimeout(cb: () => void, ms: number): unknown;
+  clearTimeout(handle: unknown): void;
+  now(): number;
+}
+
+/** Options for a folded call site (FOLDED-MUTATIONS-DESIGN §3). `key` is the identity half of the
+ *  fold key (combined with the mutator name); the rest tune the debounce policy. */
+export interface FoldOptions {
+  /** The identity half of the fold key (typically the targeted primary key). Required. */
+  key: unknown;
+  /** Trailing debounce: the flush fires this long after the LAST invoke for `key`. Default 120ms. */
+  debounceMs?: number;
+  /** Hard cap so a never-idle drag still persists periodically (trailing throttle). Unbounded if
+   *  omitted — an idle gap of `debounceMs` is then the only thing that flushes. */
+  maxWaitMs?: number;
+  /** Keep deferring across overlapping non-fold writes for maximum economy, accepting the §4.2
+   *  read-dependent reorder snap. Default `false` (flush-on-enqueue — correct-and-boring). */
+  deferAcrossWrites?: boolean;
+}
+
+/** The handle a folded call site gets back (FOLDED-MUTATIONS-DESIGN §3): no `mid` is assigned yet
+ *  (§4.1), so this exposes `flush()` to force the window now and a `mid` promise that resolves with
+ *  the wire id once the window flushes — a caller that needs the server ack can await it. */
+export interface FoldHandle {
+  flush(): void;
+  readonly mid: Promise<number>;
+}
+
+/** The single live fold entry for one fold key, plus its debounce bookkeeping (§8). */
+interface FoldRecord {
+  /** The single pending entry; `entry.mid` stays `null` until `flushFold`. */
+  entry: PendingMutation;
+  /** Latest args observed for this key — the value the flush envelope ships (mirror of entry.args). */
+  args: unknown;
+  /** The live debounce timer handle (cleared on re-arm / flush). */
+  timer: unknown;
+  /** `clock.now()` at the first invoke of this window — for the `maxWaitMs` cap. */
+  firstAt: number;
+  debounceMs: number;
+  maxWaitMs?: number;
+  deferAcrossWrites: boolean;
+  /** Resolves with the assigned mid at flush (the handle's `mid` promise). */
+  midPromise: Promise<number>;
+  resolveMid: (mid: number) => void;
+}
+
+/** Thrown by the read-trap tx when a FOLDED mutator reads state (`tx.get`/`tx.row`) — the classic
+ *  non-absorbing shape, refused at the folded path (FOLDED-MUTATIONS-DESIGN §5). */
+class FoldReadError extends Error {}
+
+interface BufferedFrame {
+  cv: number;
+  qid: QueryId;
+  kind: "snapshot" | "batch";
+  ops: NormalizedOp[];
+  /** Arrival order — the tiebreak for equal-`cv` frames (release applies in order). */
+  seq: number;
+}
+
+export interface OptimisticBackendOptions {
+  /** Stable per-client identity for the upstream envelopes (§8.1). */
+  clientID: string;
+  /** Buffered-frame ceiling before the §8.5 escape (drop + re-hydrate). */
+  bufferCap?: number;
+  /** Virtual-clock seam for the fold debounce timers (FOLDED-MUTATIONS-DESIGN §9). Defaults to
+   *  real `setTimeout`/`clearTimeout`/`Date.now`; the fold oracle injects a deterministic clock. */
+  clock?: FoldClock;
+}
+
+/** Default trailing-debounce window for a folded call site (FOLDED-MUTATIONS-DESIGN §3 example). */
+const DEFAULT_FOLD_DEBOUNCE_MS = 120;
+
+/** The real-timer clock used when none is injected. */
+const REAL_CLOCK: FoldClock = {
+  setTimeout: (cb, ms) => setTimeout(cb, ms),
+  clearTimeout: (h) => clearTimeout(h as ReturnType<typeof setTimeout>),
+  now: () => Date.now(),
+};
+
+export class OptimisticBackend<S extends ColsMap> implements Backend {
+  private readonly local: WasmBackend<S>;
+  private readonly sync: NormalizedSync;
+  private readonly source: OptimisticSource;
+  private readonly registry: ClientRegistry;
+  private readonly clientID: string;
+  private readonly bufferCap: number;
+  /** Column order + pk indices per table, for the keyed `MutationTx` methods. */
+  private readonly specs: TableSpecs;
+  /** Each table's full column count (union-row width) + column-name → base ColId — to learn a
+   *  projected query's per-table projection off its `hello` and register it with the sync layer,
+   *  so it scatters that query's narrower rows into the shared union (PROJECTION-SUPPORT-DESIGN
+   *  §5.2). Without this a projected query's short rows reach the wasm `Db` un-scattered and fail
+   *  its width check. */
+  private readonly colCounts: ColCounts;
+  private readonly colIndex: Record<string, Map<string, number>>;
+  /** The client's OWN typed per-table schemas + the reserved lmid table — the fixed base
+   *  of the expected-schema set (CRIT#4 validation). Synthetic agg tables are appended as
+   *  queries arrive (`ensureSyntheticTables`). */
+  private readonly clientTablesBase: NormalizedTableSchema[];
+  /** Synthetic aggregate tables (`__agg_*`) registered so far, by name (AGGREGATE-SYNC-DESIGN
+   *  §3.3). Per aggregate DEFINITION (not per query), so two queries over the same count
+   *  share one table. */
+  private readonly synthetic = new Map<string, NormalizedTableSchema>();
+  /** Synthetic table name → how many registered LOCAL queries reference it. A table is
+   *  materialized on the `0→1` transition and reclaimed (engine source + baseline + refcount
+   *  layer + overlay def) on `1→0` — so aggregate state is not permanent (§4). */
+  private readonly syntheticRefs = new Map<string, number>();
+  /** Local qid → the synthetic tables it referenced at registration, to decrement on teardown. */
+  private readonly queryAggTables = new Map<QueryId, string[]>();
+  /** The optimistic aggregate overlay (§4–§6): the per-aggregate definitions + the per-group
+   *  pending delta `displayed = server_base ⊕ local_pending_delta` is applied from. */
+  private readonly overlay = new AggOverlay();
+  private handler: (qid: QueryId, ev: ChangeEvent) => void = () => {};
+
+  private pendingMutations: PendingMutation[] = [];
+  private nextMid = 1;
+  /** The live fold entries, by fold key `${name}\0${identityJSON}` — at most one per key
+   *  (FOLDED-MUTATIONS-DESIGN §8). Insertion order is creation order (the drain/flush tiebreak). */
+  private readonly folds = new Map<string, FoldRecord>();
+  /** The fold debounce clock (real timers by default; the oracle injects a virtual one). */
+  private readonly clock: FoldClock;
+  /** The high-water confirmed mutation id, folded from the lmid system query's
+   *  RELEASED ops (lmid-as-data) — never from a frame. */
+  private confirmedLmid = 0;
+  private buffer: BufferedFrame[] = [];
+  private nextSeq = 0;
+  private appliedCv = 0;
+
+  private readonly asts = new Map<QueryId, Ast>();
+  /** Per query: the base tables its result can draw from (from the AST tree). */
+  private readonly queryTables = new Map<QueryId, Set<string>>();
+  private readonly remoteSubs = new Map<string, RemoteSub>();
+  private readonly sourceToRemote = new Map<QueryId, string>();
+  private readonly localToRemote = new Map<QueryId, string>();
+  private readonly remoteRetainToLocal = new Map<QueryId, QueryId | undefined>();
+  private readonly resultTypes = new Map<QueryId, ResultType>();
+  /** Local view qids that are server-authoritative: a query with no remote sub (purely local) is
+   *  hydrated on registration; a remote query is hydrated when its sub's first snapshot releases.
+   *  An un-hydrated query reports `unknown` (still loading) — the basis of `resultType`. */
+  private readonly hydrated = new Set<QueryId>();
+  private resultTypeHandler: (qid: QueryId, rt: ResultType) => void = () => {};
+  /** The pending AXIS (§7.2), split off `ResultType`: per query, whether any pending mutation
+   *  touches its tables. Cached so `onPending` fires only on transitions (invoke ↔ confirm). */
+  private readonly pendingState = new Map<QueryId, boolean>();
+  private pendingHandler: (qid: QueryId, pending: boolean) => void = () => {};
+
+  constructor(
+    schema: Schema<S>,
+    source: OptimisticSource,
+    registry: ClientRegistry,
+    opts: OptimisticBackendOptions,
+  ) {
+    this.local = new WasmBackend(schema);
+    this.local.onEvent((qid, ev) => this.handler(qid, ev));
+    this.colCounts = colCountsFromSchema(schema);
+    this.colIndex = colIndexFromSchema(schema);
+    this.sync = new NormalizedSync(pkColsFromSchema(schema), this.colCounts);
+    this.specs = tableSpecsFromSchema(schema);
+    this.source = source;
+    this.registry = registry;
+    this.clientID = opts.clientID;
+    this.bufferCap = opts.bufferCap ?? 1024;
+    this.clock = opts.clock ?? REAL_CLOCK;
+    // Validate each server hello against our OWN typed schema → reject a schema skew
+    // (CRIT#4). The reserved lmid table is part of the expected set so the system
+    // query's hello passes. Synthetic agg tables join the set as queries register them.
+    this.clientTablesBase = [...normalizedTableSchemas(schema), CLIENT_MUTATIONS_SCHEMA];
+    this.source.expectClientSchema?.(this.clientTablesBase);
+    this.source.onNormalized((qid, ev) => this.onNormalized(qid, ev));
+    this.source.onProgress((frame) => this.onProgress(frame));
+    this.source.onRestart?.(() => this.resetForRestart());
+    // The lmid system query (lmid-as-data): our confirmations arrive on this stream,
+    // cv-tagged, released by the same cvMin as the data they belong to. The server
+    // derives the identity from the connection; args are advisory.
+    this.source.registerQuery(LMID_QID, { name: LMID_QUERY_NAME, args: {} });
+  }
+
+  // --- the Backend seam ---------------------------------------------------------
+
+  registerQuery(qid: QueryId, ast: Ast, remote?: RemoteQuery): void {
+    this.asts.set(qid, ast);
+    // queryTables is derived from the ORIGINAL ast — its `count(comments)` subquery names
+    // `comment`, so an optimistic comment mutation flips this query to `unknown` (§6). The
+    // local engine, by contrast, runs the REWRITTEN ast (reads the synthetic `__agg_*`).
+    this.queryTables.set(qid, collectTables(ast));
+    // A relationship `count` is DISPLAYED from a server-authoritative synthetic base table,
+    // not recomputed locally (AGGREGATE-SYNC-DESIGN.md §3.3): register that table (engine +
+    // refcount layer + hello validation), then drive the local engine off a rewritten AST
+    // whose `count` relationships read it with a plain projected join. The remote query stays
+    // un-rewritten — the server always emits the synthetic `__agg_*` rows.
+    this.ensureSyntheticTables(qid, ast);
+    // Local first (synchronous empty view), then the server stream hydrates it.
+    this.local.registerQuery(qid, rewriteAggregates(ast));
+    if (remote) {
+      // A remote query is `unknown` until its first server snapshot lands (hydration); retainRemote
+      // attaches it to the sub and sets the lifecycle against the sub's hydration state.
+      this.retainRemote(qid, remote);
+    } else {
+      // No server stream (a purely local AST view — or the local half of a split retain whose
+      // remote attaches separately via `retainRemoteQuery`): local data is synchronous, so it is
+      // `complete` with nothing to await. A later remote retain flips it back to `unknown` if it
+      // attaches an un-hydrated sub.
+      this.hydrated.add(qid);
+      this.setResultType(qid, "complete");
+    }
+  }
+
+  /** Register every synthetic aggregate table `ast` needs that we haven't seen yet: on the
+   *  local engine (which auto-tracks it for the optimistic rebase loop), on `NormalizedSync`
+   *  (so its rows refcount/GC by group key), and into the source's expected-schema set (so
+   *  the server's `hello` — which advertises the same table — passes CRIT#4 validation).
+   *  Idempotent across queries that share an aggregate definition. */
+  private ensureSyntheticTables(qid: QueryId, ast: Ast): void {
+    // Idempotent per qid: a re-register of the same query keeps the refcounts balanced.
+    if (this.queryAggTables.has(qid)) return;
+    let added = false;
+    const names: string[] = [];
+    for (const t of aggTableSchemas(ast)) {
+      names.push(t.name);
+      const prev = this.syntheticRefs.get(t.name) ?? 0;
+      this.syntheticRefs.set(t.name, prev + 1);
+      if (prev > 0) continue; // another query already materialized this table — just refcount
+      this.synthetic.set(t.name, t);
+      this.local.registerTable(t.name, { columns: t.columns, primaryKey: t.primaryKey });
+      this.sync.registerTable(t.name, t.primaryKey);
+      added = true;
+    }
+    if (names.length) this.queryAggTables.set(qid, names);
+    // The optimistic delta (§4) needs each aggregate's child table + group key + filter, which
+    // the synthetic schema alone doesn't carry — derive the definitions from the original AST.
+    this.overlay.register(collectAggDefs(ast, (t) => this.specs[t]?.columns));
+    if (added) this.source.expectClientSchema?.([...this.clientTablesBase, ...this.synthetic.values()]);
+  }
+
+  /** Decrement the refcount of every synthetic table query `qid` referenced; for each one that
+   *  reaches 0 (no live reader left), remove it from the engine, the refcount layer, and the
+   *  overlay — so aggregate state is reclaimed, not permanent (§4). Must run AFTER
+   *  `local.unregisterQuery(qid)` so the engine source has no live connection when
+   *  `unregisterTable` frees it (the engine refuses otherwise). */
+  private releaseSyntheticTables(qid: QueryId): void {
+    const names = this.queryAggTables.get(qid);
+    if (!names) return;
+    this.queryAggTables.delete(qid);
+    let removed = false;
+    for (const name of names) {
+      const next = (this.syntheticRefs.get(name) ?? 1) - 1;
+      if (next > 0) {
+        this.syntheticRefs.set(name, next);
+        continue;
+      }
+      this.syntheticRefs.delete(name);
+      this.local.unregisterTable(name);
+      this.sync.unregisterTable(name);
+      this.overlay.unregister(name);
+      this.synthetic.delete(name);
+      removed = true;
+    }
+    if (removed) this.source.expectClientSchema?.([...this.clientTablesBase, ...this.synthetic.values()]);
+  }
+
+  unregisterQuery(qid: QueryId): void {
+    const remoteQid = this.releaseRemote(qid);
+    if (remoteQid !== undefined) this.buffer = this.buffer.filter((f) => f.qid !== remoteQid);
+    // GC: rows this remote footprint SOLELY referenced fall to refcount 0 → net removes.
+    const gc = remoteQid === undefined ? [] : this.sync.dropQuery(remoteQid);
+    // Tear down the local pipeline+view first so the reconcile cycle below skips it.
+    this.local.unregisterQuery(qid);
+    // The GC removals must leave BOTH head AND the engine's `sync` baseline. A plain
+    // `local.mutate` (a HEAD-only write) leaves them in `sync`, so they look like a pending
+    // optimistic REMOVE: the next release's rewind diffs head against sync+D and RESURRECTS
+    // them, GC never frees anything, and a later query is served the stale/deleted row
+    // forever (CRIT#2). Deliver them as a coherent SERVER delta instead — the same
+    // sync-moving boundary `onProgress` uses — so head and sync both drop the rows.
+    if (gc.length) this.runReconcileCycle(gc);
+    // The local pipeline is gone (no live conn) and the remote footprint's `__agg` rows were
+    // GC'd above, so any synthetic table this was the last reader of can now be freed (§4).
+    this.releaseSyntheticTables(qid);
+    this.asts.delete(qid);
+    this.queryTables.delete(qid);
+    this.resultTypes.delete(qid);
+    this.hydrated.delete(qid);
+    this.pendingState.delete(qid); // §7.2 cache, keyed by the local materialized qid (a monotonic
+    // Store counter — re-materialize gets a fresh id, never this one again), so drop it on teardown.
+  }
+
+  retainRemoteQuery(qid: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void {
+    this.retainRemote(qid, remote, localQueryId);
+  }
+
+  releaseRemoteQuery(qid: QueryId): void {
+    const remoteQid = this.releaseRemote(qid);
+    if (remoteQid === undefined) return;
+    this.buffer = this.buffer.filter((f) => f.qid !== remoteQid);
+    const gc = this.sync.dropQuery(remoteQid);
+    if (gc.length) this.runReconcileCycle(gc);
+  }
+
+  /** Raw CRUD has no optimistic story (§9 replaces it with named mutators). Register a
+   *  mutator — even a trivial one — and `invoke` it. */
+  mutate(_mutations: Mutation[]): Promise<void> {
+    return Promise.reject(
+      new Error("optimistic backend: writes go through named mutators — use invoke(name, args)"),
+    );
+  }
+
+  onEvent(handler: (qid: QueryId, ev: ChangeEvent) => void): void {
+    this.handler = handler;
+  }
+
+  // --- the named-mutator entry (§9) ----------------------------------------------
+
+  /** Run the named client mutator optimistically: the prediction applies to the live
+   *  engine now (affected views update synchronously), `(mid, name, args)` joins the
+   *  pending stack, and the envelope ships upstream. Returns the assigned `mid`. */
+  invoke(name: string, args: unknown): number {
+    const mutator = this.registry[name];
+    if (!mutator) throw new Error(`unknown client mutator: ${name}`);
+    // Apply the prediction FIRST. If the mutator throws (client-side validation, a bad read),
+    // the staged write is discarded (the wasm txn is a clean no-op until commit) and the throw
+    // propagates with NO mid consumed — a burnt mid is a permanent server-side gap that
+    // silently refuses every later mutation from this client (#10).
+    const touched = new Set<string>();
+    const ops: ChildOp[] = [];
+    this.local.writeWith((tx) => {
+      mutator(trackingTx(tx, touched, this.specs, this.opCollector(ops)), args as never);
+    });
+    // Flush-on-enqueue (§4.2): a fold whose tables overlap this write must take its mid NOW, BEFORE
+    // this write does, so wire order == local-apply order for any pair that can observe each other
+    // (a read-dependent write reading a folded cell sees the same value optimistically and on the
+    // wire — no snap). Drained folds ship with smaller mids; this write's mid is dealt after.
+    this.drainOverlapping(touched);
+    const mid = this.nextMid++;
+    this.pendingMutations.push({ mid, name, args, touched });
+    // The prediction stuck — fold its child ops into the optimistic agg delta and push it onto
+    // the `__agg` head rows (§4). No reset here (this is the §1.3 trivial case, no rewind): the
+    // delta accumulates on top of the prior pending set, and `reconcileAggHead` recomputes each
+    // touched group's head as the absolute `server_base ⊕ delta`.
+    for (const op of ops) this.overlay.observe(op);
+    this.reconcileAggHead();
+    this.refreshPending(); // §7.2: this write now touches its queries' pending axis (NOT ResultType).
+    void this.source.pushMutation({ clientID: this.clientID, mid, name, args });
+    return mid;
+  }
+
+  /** Run a FOLDED invoke (FOLDED-MUTATIONS-DESIGN §8): apply the prediction to the live engine now
+   *  (like `invoke`), but collapse a run of same-key invokes into ONE pending entry whose `args`
+   *  are overwritten in place, debounce the server write, and ship only the last value. The `mid`
+   *  is assigned at flush, not here (§4.1) — so the return is a {@link FoldHandle}, not a mid. */
+  invokeFolded(name: string, opts: FoldOptions, args: unknown): FoldHandle {
+    const mutator = this.registry[name];
+    if (!mutator) throw new Error(`unknown client mutator: ${name}`);
+    const foldKey = `${name}\0${stableJson(opts.key)}`;
+    // Apply the prediction with the read trap armed (§5): a folded mutator that reads state to
+    // compute its write is non-absorbing and refused. A throw discards the staged write (clean
+    // no-op) and consumes no mid — exactly `invoke`'s guarantee.
+    const touched = new Set<string>();
+    const ops: ChildOp[] = [];
+    try {
+      this.local.writeWith((tx) => {
+        mutator(trackingTx(tx, touched, this.specs, this.opCollector(ops), true), args as never);
+      });
+    } catch (e) {
+      if (e instanceof FoldReadError) {
+        throw new Error(
+          `cannot fold "${name}": it reads state via tx.get/tx.row, so it is not absorbing — folded mutators must be last-writer-wins (FOLDED-MUTATIONS-DESIGN §5)`,
+        );
+      }
+      throw e;
+    }
+    for (const op of ops) this.overlay.observe(op);
+    this.reconcileAggHead();
+
+    const now = this.clock.now();
+    let f = this.folds.get(foldKey);
+    if (f) {
+      // Overwrite the single entry in place — the pending stack does NOT grow (§1 #2). The head
+      // already carries this new prediction (absorbing, last-wins on the cell); the entry holds
+      // only the LATEST args, which is what a rebase re-derives from and what the flush ships.
+      f.entry.args = args;
+      f.entry.touched = touched;
+      f.args = args;
+      this.clock.clearTimeout(f.timer);
+    } else {
+      const entry: PendingMutation = { mid: null, name, args, touched };
+      this.pendingMutations.push(entry);
+      let resolveMid!: (mid: number) => void;
+      const midPromise = new Promise<number>((res) => (resolveMid = res));
+      f = {
+        entry,
+        args,
+        timer: undefined,
+        firstAt: now,
+        debounceMs: opts.debounceMs ?? DEFAULT_FOLD_DEBOUNCE_MS,
+        maxWaitMs: opts.maxWaitMs,
+        deferAcrossWrites: opts.deferAcrossWrites ?? false,
+        midPromise,
+        resolveMid,
+      };
+      this.folds.set(foldKey, f);
+    }
+    // (Re)arm the trailing debounce — unless the maxWaitMs cap is already due (a never-idle drag
+    // still persists periodically, §3/#4), in which case flush now instead of re-arming.
+    if (f.maxWaitMs !== undefined && now - f.firstAt >= f.maxWaitMs) {
+      this.flushFold(foldKey);
+    } else {
+      f.timer = this.clock.setTimeout(() => this.flushFold(foldKey), f.debounceMs);
+    }
+    this.refreshPending();
+    const handle: FoldHandle = { flush: () => this.flushFold(foldKey), mid: f.midPromise };
+    return handle;
+  }
+
+  /** Flush-on-enqueue (§4.2): for each outstanding fold whose touched tables overlap `tables`,
+   *  assign its mid NOW and ship it — in creation (insertion) order, so the wire stays gapless. A
+   *  `deferAcrossWrites` fold opts out (it keeps deferring, accepting the read-dependent snap). The
+   *  incoming write's own fold key (if any) is skipped — it is being folded into, not flushed. */
+  private drainOverlapping(tables: Set<string>, exceptKey?: string): void {
+    // Snapshot the entries first: `flushFold` mutates `this.folds` mid-iteration.
+    for (const [key, f] of [...this.folds]) {
+      if (key === exceptKey || f.deferAcrossWrites) continue;
+      if (intersects(f.entry.touched, tables)) this.flushFold(key);
+    }
+  }
+
+  /** Flush one fold (§8): deal its `mid` from `nextMid` (SEND order — never reserved, so gapless
+   *  by construction), stamp the entry, ship the envelope with the LATEST args, resolve the handle.
+   *  The entry stays on `pendingMutations` (now with a real mid) until the lmid release confirms it. */
+  private flushFold(foldKey: string): void {
+    const f = this.folds.get(foldKey);
+    if (!f) return;
+    this.clock.clearTimeout(f.timer);
+    this.folds.delete(foldKey);
+    const mid = this.nextMid++;
+    f.entry.mid = mid;
+    void this.source.pushMutation({ clientID: this.clientID, mid, name: f.entry.name, args: f.args });
+    f.resolveMid(mid);
+  }
+
+  /** Drain every outstanding fold immediately (FOLDED-MUTATIONS-DESIGN §3): the explicit
+   *  `app.flushFolds()` and the `beforeunload`/`close` hook. Creation (insertion) order. */
+  flushFolds(): void {
+    for (const key of [...this.folds.keys()]) this.flushFold(key);
+  }
+
+  /** A `trackingTx` op collector that records only the ops over a tracked aggregate's child
+   *  table (the others can't move any count). Applied to the overlay by the caller AFTER the
+   *  mutator succeeds, so a throwing mutator (whose staged write is discarded) leaves no delta. */
+  private opCollector(ops: ChildOp[]): (op: ChildOp) => void {
+    return (op) => {
+      if (this.overlay.hasChild(op.table)) ops.push(op);
+    };
+  }
+
+  /** Push the optimistic per-group delta onto the `__agg` head rows (§4):
+   *  `target = server_base ⊕ delta`. A head-only write to the (tracked) synthetic table, so it
+   *  joins the optimistic layer and is rewound/rebuilt by the reconcile cycle like any
+   *  prediction. `server_base` is read from `NormalizedSync` (the authoritative base) — NOT
+   *  from head, which already carries the optimistic layer (a torn read). Works standalone (an
+   *  ordinary delivery) and inside an open cycle (the write buffers into it). */
+  private reconcileAggHead(): void {
+    const entries = this.overlay.entries();
+    if (entries.length === 0) return;
+    this.local.writeWith((tx) => {
+      for (const e of entries) {
+        const countCol = e.def.groupKeyCols.length; // row is [group…, count]; count is at index k
+        const serverRow = this.sync.baseRow(e.aggTable, e.cells);
+        const serverBase = serverRow ? Number(serverRow[countCol]) : 0;
+        const target = Math.max(0, serverBase + e.n); // a displayed count never goes below 0
+        const headRow = tx.get(e.aggTable, e.cells) as WireValue[] | undefined;
+        const wantRow = serverRow !== undefined || target > 0;
+        if (wantRow) {
+          const desired = [...e.cells, target];
+          if (!headRow) tx.add(e.aggTable, desired); // §6.1 optimistic birth (no server group yet)
+          else if (!rowsEqual(headRow, desired)) tx.edit(e.aggTable, headRow, desired);
+        } else if (headRow) {
+          tx.remove(e.aggTable, headRow); // delta took a not-yet-on-server group back to identity
+        }
+      }
+    });
+    this.overlay.pruneZeros();
+  }
+
+  /** The SERVER CHANNEL's state for a query (§7): `unknown` while not hydrated, else `complete`.
+   *  A pending local mutation no longer moves it — see {@link pending}. */
+  resultType(qid: QueryId): ResultType {
+    return this.resultTypes.get(qid) ?? "complete";
+  }
+
+  onResultType(handler: (qid: QueryId, rt: ResultType) => void): void {
+    this.resultTypeHandler = handler;
+  }
+
+  // --- the pending AXIS (§7.2): orthogonal to ResultType -------------------------------
+
+  /** Whether any pending mutation (folded or not) touches this query's tables — "is a prediction
+   *  pending here?" (FOLDED-MUTATIONS-DESIGN §7.2). Orthogonal to {@link resultType}; this is the
+   *  same `queryTables ∩ pending.touched` computation that used to be smuggled into `unknown`. */
+  pending(qid: QueryId): boolean {
+    const tables = this.queryTables.get(qid);
+    if (!tables) return false;
+    return this.pendingMutations.some((p) => intersects(tables, p.touched));
+  }
+
+  /** Reactive pending axis (§7.2): fires when a query's pending-ness flips (invoke ↔ confirm), so a
+   *  "saving…" affordance clears on its own when `lmid` catches up. */
+  onPending(handler: (qid: QueryId, pending: boolean) => void): void {
+    this.pendingHandler = handler;
+  }
+
+  /** The coarse, table-level pending indicator set (§7.2): every table some pending mutation touched. */
+  pendingTables(): Set<string> {
+    const out = new Set<string>();
+    for (const p of this.pendingMutations) for (const t of p.touched) out.add(t);
+    return out;
+  }
+
+  /** Recompute the pending axis for every query and fire `onPending` on transitions only. Called
+   *  from the two points that move the pending set: invoke/invokeFolded (add) and the confirm-drop
+   *  (remove) — exactly where `:359`/`:468` used to flip ResultType (§7.3). */
+  private refreshPending(): void {
+    for (const qid of this.queryTables.keys()) {
+      const now = this.pending(qid);
+      if (this.pendingState.get(qid) !== now) {
+        this.pendingState.set(qid, now);
+        this.pendingHandler(qid, now);
+      }
+    }
+  }
+
+  // --- the downstream stream (§8.5: buffer, then release coherently) ---------------
+
+  private onNormalized(qid: QueryId, ev: NormalizedEvent): void {
+    if (ev.type === "hello") {
+      // A hello is a (re)subscribe = a NEW epoch. The column map below is mutated eagerly, but
+      // data frames are cv-buffered and drained later (onProgress). So any frame still buffered
+      // for this qid is from a SUPERSEDED epoch and must NOT be scattered through this epoch's
+      // (possibly changed) map — drop it. This epoch's snapshot, which always follows the hello,
+      // re-hydrates the qid from scratch, so the dropped frames are redundant. Scoped to this
+      // qid: other queries' frames (and the lmid system query's) keep their coherent release.
+      this.buffer = this.buffer.filter((f) => f.qid !== qid);
+      this.addServerDependencyTables(qid, ev.tables.map((t) => t.name));
+      // Learn this query's per-table column map (PROJECTION-SUPPORT-DESIGN.md §5.2): map each
+      // advertised column to its base ColId BY NAME. The hello may carry FEWER columns than the
+      // client's schema (a projection) or MORE (an EXPANDED server table mid an
+      // `expand-then-contract` migration) — a column the client lacks maps to `-1`, a DROP
+      // sentinel the sync layer discards while keeping the rest Absent. Register the map so the
+      // sync layer scatters the rows into the shared union; a table whose map is an in-order,
+      // drop-free full width IS '*' (a verbatim full row) and stays unregistered (a synthetic agg
+      // table is unknown here, also '*'). Idempotent across re-hydrate epochs.
+      for (const t of ev.tables) {
+        const full = this.colCounts[t.name];
+        if (full === undefined) continue; // unknown/synthetic table → '*' (full presence)
+        const index = this.colIndex[t.name];
+        const cols = t.columns.map((name) => index?.get(name) ?? -1);
+        // Register a non-trivial map; otherwise revert to '*' — and CLEAR any stale map a prior
+        // epoch left (a server that expanded then contracted back), so the now-exact rows don't
+        // scatter through a `-1`-bearing layout (silent cell corruption).
+        if (cols.length !== full || cols.some((c, i) => c !== i)) this.sync.registerProjection(qid, t.name, cols);
+        else this.sync.unregisterProjection(qid, t.name);
+      }
+      return; // envelope validation is the source's job
+    }
+    const cv = ev.cv ?? 0;
+    if (cv <= this.appliedCv && ev.type === "batch") return; // stale redelivery
+    this.buffer.push({ cv, qid, kind: ev.type, ops: ev.ops, seq: this.nextSeq++ });
+    if (this.buffer.length > this.bufferCap) this.overflow();
+  }
+
+  private onProgress(frame: ProgressFrame): void {
+    // (1) Take every buffered frame at cv ≤ cvMin, in (cv, arrival) order, and fold it:
+    // lmid system-query frames advance `confirmedLmid`; data frames fold through the
+    // cross-query refcount into ONE net base delta — the §1.3 `D`. Confirmation and
+    // data of the same commit share a cv, so they release together by construction.
+    const ready = this.buffer
+      .filter((f) => f.cv <= frame.cvMin)
+      .sort((a, b) => a.cv - b.cv || a.seq - b.seq);
+    this.buffer = this.buffer.filter((f) => f.cv > frame.cvMin);
+    const muts: Mutation[] = [];
+    for (const f of ready) {
+      if (f.qid === LMID_QID) {
+        this.foldLmidOps(f.ops);
+        continue;
+      }
+      muts.push(
+        ...(f.kind === "snapshot" ? this.sync.rehydrate(f.qid, f.ops) : this.sync.applyBatch(f.qid, f.ops)),
+      );
+      // A query's first released snapshot is its hydration point — even an empty one (0 rows is an
+      // authoritative answer): lift every local view this sub feeds out of `unknown` (loading).
+      if (f.kind === "snapshot") this.markSubHydrated(f.qid);
+    }
+    this.appliedCv = Math.max(this.appliedCv, frame.cvMin);
+
+    // (2) Drop confirmed pending (§1.3 step 5's bookkeeping half): mid ≤ the lmid this
+    // release itself delivered. A failed mutation drops the same way — the release just
+    // carries no effects for it, so the rewind in (3) snaps the prediction back. An UNFLUSHED
+    // folded entry (`mid == null`) is never confirmable — it has not crossed the wire — so it is
+    // always retained until its own flush stamps a real mid (FOLDED-MUTATIONS-DESIGN §4.1).
+    const before = this.pendingMutations.length;
+    this.pendingMutations = this.pendingMutations.filter((p) => p.mid === null || p.mid > this.confirmedLmid);
+    const pendingChanged = this.pendingMutations.length !== before;
+
+    // (3) The reconcile cycle — only when something can have changed: a base delta to
+    // fold in, or a pending set that shrank (its optimistic layer must rewind out).
+    if (muts.length || pendingChanged) {
+      this.runReconcileCycle(muts);
+    }
+
+    // (4) ResultType is the SERVER CHANNEL's state only now (§7): `unknown` while not hydrated,
+    // else `complete` — a pending mutation no longer moves it. The pending axis moves separately.
+    for (const qid of this.queryTables.keys()) {
+      this.setResultType(qid, this.hydrated.has(qid) ? "complete" : "unknown");
+    }
+    this.refreshPending();
+  }
+
+  /** Fold the lmid system query's released ops (lmid-as-data): the one row's
+   *  `last_mutation_id` cell is this client's confirmed high-water mid. */
+  private foldLmidOps(ops: NormalizedOp[]): void {
+    for (const op of ops) {
+      const row = op.op === "add" ? op.row : op.op === "edit" ? op.new : undefined;
+      if (!row) continue; // a remove (client GC) confirms nothing
+      const lmid = Number(row[1]);
+      if (!Number.isFinite(lmid)) continue;
+      if (lmid > this.nextMid - 1) {
+        if (this.pendingMutations.length > 0) {
+          // The server confirmed a mid we never issued while we have mutations in
+          // flight — two writers on one clientID or corrupted state. Unrecoverable.
+          throw new Error(
+            `optimistic backend: confirmed lmid ${lmid} is ahead of issued mids (${this.nextMid - 1})`,
+          );
+        }
+        // A fresh session over a clientID with history: adopt the server's high-water
+        // mark so our next mid continues the sequence instead of colliding below it.
+        this.nextMid = lmid + 1;
+      }
+      this.confirmedLmid = Math.max(this.confirmedLmid, lmid);
+    }
+  }
+
+  /** One §1.3 reconcile cycle: rewind the optimistic layer and fold the coherent SERVER
+   *  delta into BOTH head AND the `sync` baseline (`serverBatchBegin`), re-invoke every
+   *  still-pending mutator to re-stage the optimistic layer (the rewind un-applied it), then
+   *  deliver the coalesced result (`serverBatchEnd`). This is the engine's only sync-moving
+   *  boundary — `onProgress` releases and `unregisterQuery`'s GC both go through here so head
+   *  and sync never diverge (the §1.2 invariant; CRIT#2). */
+  private runReconcileCycle(serverDeltas: Mutation[]): void {
+    this.local.serverBatchBegin(serverDeltas.map(toServerOp));
+    // The rewind cleared every optimistic write — incl. prior `__agg` edits — so head is now
+    // the server baseline. Rebuild the optimistic agg delta from scratch off the re-invoked
+    // (confirm-filtered) pending set, so a just-confirmed mutation's delta vanishes exactly as
+    // its server count is absorbed (§5 watermark — no double count).
+    this.overlay.reset();
+    // Re-invoke in WIRE order: assigned mids ascending, then unflushed folds (`mid == null`) last
+    // by creation order — the deterministic slot of FOLDED-MUTATIONS-DESIGN §4.1. A read-dependent
+    // mutator must replay against the same base the server computed from, which is mid order; with
+    // deferred fold mids, mid order ≠ creation order, so we sort rather than trust array order. The
+    // comparator is explicit (NOT `(mid ?? ∞) - (mid ?? ∞)`, which is `∞ - ∞ = NaN` for two unflushed
+    // folds — a NaN comparator silently corrupts V8's sort): assigned-before-unflushed, mids
+    // ascending, and STABLE for two unflushed folds so they keep creation order across cycles.
+    const order = [...this.pendingMutations].sort((a, b) => {
+      if (a.mid === null && b.mid === null) return 0; // both unflushed → stable creation order
+      if (a.mid === null) return 1; // an unflushed fold sorts after every assigned mid
+      if (b.mid === null) return -1;
+      return a.mid - b.mid;
+    });
+    const dropped = new Set<PendingMutation>();
+    try {
+      for (const p of order) {
+        const touched = new Set<string>();
+        const ops: ChildOp[] = [];
+        try {
+          this.local.writeWith((tx) => {
+            this.registry[p.name](trackingTx(tx, touched, this.specs, this.opCollector(ops)), p.args as never);
+          });
+        } catch {
+          // A re-invocation threw — e.g. a read-dependent mutator whose base row the server
+          // deleted, or one reading a row a now-rejected sibling created. Drop it from pending
+          // (its staged write was discarded); its prediction simply snaps back on this release —
+          // a throwing mutation surfaces on the mutation axis (`onRejected`), not as a query-level
+          // `error` (§7.4). The `finally` below ALWAYS closes the cycle, so one bad mutator can't
+          // wedge the engine forever (#7).
+          dropped.add(p);
+          continue;
+        }
+        // The re-invocation stuck — fold its child ops into the rebuilt optimistic agg delta.
+        for (const op of ops) this.overlay.observe(op);
+        // The pending footprint is the UNION across invocations: a re-run that no-ops (touched =
+        // {}) must NOT shrink it, else a still-pending mutation reports not-pending and its
+        // pending-axis clear fires early (§7.2).
+        for (const t of touched) p.touched.add(t);
+      }
+      // Preserve creation order in the live array (the unflushed-fold sort tiebreak depends on it).
+      if (dropped.size) this.pendingMutations = this.pendingMutations.filter((p) => !dropped.has(p));
+      // Re-apply the optimistic agg delta onto the (rewound) `__agg` head rows — INSIDE the open
+      // cycle, so the writes buffer and coalesce into the one per-query delivery `serverBatchEnd`
+      // makes (and never escape as a separate batch).
+      this.reconcileAggHead();
+    } finally {
+      this.local.serverBatchEnd(); // ALWAYS close the cycle — ONE delivery per affected query.
+    }
+  }
+
+  /** The daemon restarted (a new boot id): it lost all materialization + `cv` state and its `cv`
+   *  sequence reset, so previously-released `cv`s no longer bound the new stream. The source has
+   *  already re-subscribed every query (reconnect → resync); drop the buffer and the `cv`
+   *  watermark so the fresh, low-`cv` snapshots are RELEASED instead of dropped as stale
+   *  (`onNormalized`/`onProgress` gate on `appliedCv`). Pending optimistic mutations stay put —
+   *  they re-apply on the next reconcile, and the lmid system query's fresh snapshot restores the
+   *  confirmation watermark. */
+  private resetForRestart(): void {
+    this.buffer = [];
+    this.appliedCv = 0;
+  }
+
+  /** The §8.5 escape: the buffer outgrew its cap (a pinned `cvMin` under churn). Drop
+   *  everything buffered and re-register every query on the source — the fresh
+   *  snapshots arrive as ordinary frames and the next release re-hydrates via the
+   *  footprint diff (the §5.3 path); still-pending optimism re-applies in that cycle. */
+  private overflow(): void {
+    this.buffer = [];
+    for (const sub of this.remoteSubs.values()) {
+      this.source.unregisterQuery(sub.sourceQid);
+      this.source.registerQuery(sub.sourceQid, sub.remote);
+    }
+    // The lmid system query's buffered frames were dropped too — re-subscribe it so a
+    // fresh snapshot restores the confirmation watermark.
+    this.source.unregisterQuery(LMID_QID);
+    this.source.registerQuery(LMID_QID, { name: LMID_QUERY_NAME, args: {} });
+  }
+
+  private setResultType(qid: QueryId, rt: ResultType): void {
+    if (this.resultTypes.get(qid) === rt) return;
+    this.resultTypes.set(qid, rt);
+    this.resultTypeHandler(qid, rt);
+  }
+
+  /** Recompute a query's server-channel state from hydration alone (§7): a pending mutation no
+   *  longer affects it. Used when a remote sub attaches to or hydrates a local view. */
+  private recomputeResultType(qid: QueryId): void {
+    if (!this.queryTables.has(qid)) return;
+    this.setResultType(qid, this.hydrated.has(qid) ? "complete" : "unknown");
+  }
+
+  /** A remote sub's first snapshot landed: mark it (and every local view it feeds) hydrated, then
+   *  lift those views out of `unknown` (loading). Idempotent — a re-hydrate snapshot re-marks
+   *  harmlessly; a source qid with no sub (the lmid system query) is a no-op. */
+  private markSubHydrated(sourceQid: QueryId): void {
+    const key = this.sourceToRemote.get(sourceQid);
+    if (!key) return;
+    const sub = this.remoteSubs.get(key);
+    if (!sub || sub.hydrated) return;
+    sub.hydrated = true;
+    for (const localQid of sub.localQids.keys()) {
+      this.hydrated.add(localQid);
+      this.recomputeResultType(localQid);
+    }
+  }
+
+  private retainRemote(retainQid: QueryId, remote: RemoteQuery, localQueryId: QueryId | undefined = retainQid): void {
+    const key = remoteKey(remote);
+    let sub = this.remoteSubs.get(key);
+    let isNew = false;
+    if (!sub) {
+      sub = { sourceQid: retainQid, remote, refCount: 0, localQids: new Map(), hydrated: false };
+      this.remoteSubs.set(key, sub);
+      this.sourceToRemote.set(sub.sourceQid, key);
+      isNew = true;
+    }
+    sub.refCount++;
+    if (localQueryId !== undefined) {
+      sub.localQids.set(localQueryId, (sub.localQids.get(localQueryId) ?? 0) + 1);
+      // A late-joiner to an already-hydrated sub is immediately hydrated; otherwise this view now
+      // awaits the sub's first snapshot (so a split-path local view registered `complete` flips to
+      // `unknown` here). Then recompute its lifecycle.
+      if (sub.hydrated) this.hydrated.add(localQueryId);
+      else this.hydrated.delete(localQueryId);
+      this.recomputeResultType(localQueryId);
+    }
+    this.localToRemote.set(retainQid, key);
+    this.remoteRetainToLocal.set(retainQid, localQueryId);
+    if (isNew) this.source.registerQuery(sub.sourceQid, remote);
+  }
+
+  private releaseRemote(retainQid: QueryId): QueryId | undefined {
+    const key = this.localToRemote.get(retainQid);
+    if (!key) return undefined;
+    this.localToRemote.delete(retainQid);
+    const localQueryId = this.remoteRetainToLocal.get(retainQid);
+    this.remoteRetainToLocal.delete(retainQid);
+    const sub = this.remoteSubs.get(key);
+    if (!sub) return undefined;
+    sub.refCount--;
+    if (localQueryId !== undefined) {
+      const refs = (sub.localQids.get(localQueryId) ?? 0) - 1;
+      if (refs > 0) sub.localQids.set(localQueryId, refs);
+      else sub.localQids.delete(localQueryId);
+    }
+    if (sub.refCount > 0) return undefined;
+    this.source.unregisterQuery(sub.sourceQid);
+    this.sourceToRemote.delete(sub.sourceQid);
+    this.remoteSubs.delete(key);
+    return sub.sourceQid;
+  }
+
+  private addServerDependencyTables(sourceQid: QueryId, names: string[]): void {
+    const key = this.sourceToRemote.get(sourceQid);
+    if (!key) return;
+    const sub = this.remoteSubs.get(key);
+    if (!sub) return;
+    let grew = false;
+    for (const localQid of sub.localQids.keys()) {
+      const tables = this.queryTables.get(localQid);
+      if (!tables) continue;
+      for (const name of names) {
+        if (!tables.has(name)) grew = true;
+        tables.add(name);
+      }
+    }
+    // A newly-learned server dependency may bring a query into a pending mutation's footprint (§7.2);
+    // ResultType is unaffected (server-channel-only, §7).
+    if (grew) this.refreshPending();
+  }
+}
+
+// --- helpers -----------------------------------------------------------------------
+
+interface RemoteSub {
+  sourceQid: QueryId;
+  remote: RemoteQuery;
+  refCount: number;
+  localQids: Map<QueryId, number>;
+  /** Whether this sub's first server snapshot has been released (drives hydration of its views). */
+  hydrated: boolean;
+}
+
+function remoteKey(remote: RemoteQuery): string {
+  return stableJson([remote.name, remote.args]);
+}
+
+function stableJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  const obj = value as Record<string, unknown>;
+  return `{${Object.keys(obj)
+    .sort()
+    .map((k) => `${JSON.stringify(k)}:${stableJson(obj[k])}`)
+    .join(",")}}`;
+}
+
+function pkColsFromSchema<S extends ColsMap>(schema: Schema<S>): PkCols {
+  const out: PkCols = {};
+  for (const name of Object.keys(schema.tables)) out[name] = tableSpec(schema.tables[name]).primaryKey;
+  return out;
+}
+
+/** Per-table column order + pk indices, for the keyed `MutationTx` methods. */
+type TableSpecs = Record<string, { columns: string[]; primaryKey: number[] }>;
+
+function tableSpecsFromSchema<S extends ColsMap>(schema: Schema<S>): TableSpecs {
+  const out: TableSpecs = {};
+  for (const name of Object.keys(schema.tables)) {
+    const { columns, primaryKey } = tableSpec(schema.tables[name]);
+    out[name] = { columns, primaryKey };
+  }
+  return out;
+}
+
+/** Each table's FULL column count (the union-row width), from the typed schema. */
+function colCountsFromSchema<S extends ColsMap>(schema: Schema<S>): ColCounts {
+  const out: ColCounts = {};
+  for (const name of Object.keys(schema.tables)) out[name] = tableSpec(schema.tables[name]).columns.length;
+  return out;
+}
+
+/** Each table's column name → base ColId, from the typed schema (for mapping a projected hello's
+ *  columns back to base positions, PROJECTION-SUPPORT-DESIGN.md §5.2). */
+function colIndexFromSchema<S extends ColsMap>(schema: Schema<S>): Record<string, Map<string, number>> {
+  const out: Record<string, Map<string, number>> = {};
+  for (const name of Object.keys(schema.tables)) {
+    const cols = tableSpec(schema.tables[name]).columns;
+    out[name] = new Map(cols.map((c, i) => [c, i]));
+  }
+  return out;
+}
+
+/** Wrap the raw wasm txn as the client `MutationTx`, recording the touched tables (the client
+ *  knows its own footprint — what the pending axis derives from, §7.2). The keyed methods validate
+ *  column names eagerly: a typo'd table or column throws with the valid names listed, at the moment
+ *  the mutator runs.
+ *
+ *  With `trapReads` (the FOLDED path, §5), the PUBLIC reads `tx.get`/`tx.row` throw `FoldReadError`
+ *  — a folded mutator that reads state to compute its write is non-absorbing and refused. The keyed
+ *  writers (`update`/`upsert`/`delete`) still read internally to preserve unspecified columns; that
+ *  is column-preservation, not value-derivation, so it stays allowed. */
+function trackingTx(
+  tx: WasmWriteTxn,
+  touched: Set<string>,
+  specs: TableSpecs,
+  onOp?: (op: ChildOp) => void,
+  trapReads = false,
+): MutationTx {
+  const spec = (table: string) => {
+    const s = specs[table];
+    if (!s) throw new Error(`unknown table ${JSON.stringify(table)} — tables: ${Object.keys(specs).join(", ")}`);
+    return s;
+  };
+
+  /** Validate `obj`'s keys against the table's columns; require the pk columns; with
+   *  `full`, require EVERY column (inserts carry whole rows — there are no defaults). */
+  const checkColumns = (table: string, obj: KeyedRow, full: boolean): void => {
+    const s = spec(table);
+    const unknown = Object.keys(obj).filter((k) => !s.columns.includes(k));
+    if (unknown.length) {
+      throw new Error(
+        `unknown column${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} on ${table} — columns: ${s.columns.join(", ")}`,
+      );
+    }
+    const required = full ? s.columns : s.primaryKey.map((i) => s.columns[i]);
+    const missing = required.filter((c) => !(c in obj));
+    if (missing.length) {
+      throw new Error(`missing ${full ? "column" : "primary-key column"}${missing.length > 1 ? "s" : ""} ${missing.join(", ")} on ${table}`);
+    }
+  };
+
+  const pkCells = (table: string, obj: KeyedRow): WireValue[] =>
+    spec(table).primaryKey.map((i) => obj[spec(table).columns[i]]);
+
+  const toCells = (table: string, obj: KeyedRow): WireValue[] => spec(table).columns.map((c) => obj[c]);
+
+  const toKeyed = (table: string, cells: WireValue[]): KeyedRow => {
+    const out: KeyedRow = {};
+    spec(table).columns.forEach((c, i) => (out[c] = cells[i]));
+    return out;
+  };
+
+  // Internal read — used by the keyed writers below and the keyed `row` reader; never trapped.
+  const rawGet = (table: string, pk: WireValue[]) => tx.get(table, pk) as WireValue[] | undefined;
+  const add = (table: string, row: WireValue[]) => {
+    touched.add(table);
+    onOp?.({ table, kind: "add", row });
+    tx.add(table, row);
+  };
+  const remove = (table: string, row: WireValue[]) => {
+    touched.add(table);
+    onOp?.({ table, kind: "remove", row });
+    tx.remove(table, row);
+  };
+  const edit = (table: string, oldRow: WireValue[], newRow: WireValue[]) => {
+    touched.add(table);
+    onOp?.({ table, kind: "edit", row: newRow, old: oldRow });
+    tx.edit(table, oldRow, newRow);
+  };
+
+  // The folded read trap (§5): a mutator that reads to compute its write is refused. `() => never`
+  // is assignable to the wider read signatures (extra args ignored, `never` widens to the result).
+  const trapped = (): never => {
+    throw new FoldReadError();
+  };
+
+  return {
+    get: trapReads ? trapped : rawGet,
+    add,
+    remove,
+    edit,
+    row: trapReads
+      ? trapped
+      : (table, pk) => {
+          checkColumns(table, pk, false);
+          const cells = rawGet(table, pkCells(table, pk));
+          return cells ? toKeyed(table, cells) : undefined;
+        },
+    insert: (table, row) => {
+      checkColumns(table, row, true);
+      add(table, toCells(table, row));
+    },
+    update: (table, row) => {
+      checkColumns(table, row, false);
+      const current = rawGet(table, pkCells(table, row));
+      if (!current) return; // rebase-friendly: the row may have vanished upstream
+      const s = spec(table);
+      const next = s.columns.map((c, i) => (c in row ? row[c] : current[i]));
+      edit(table, current, next);
+    },
+    upsert: (table, row) => {
+      checkColumns(table, row, true);
+      const current = rawGet(table, pkCells(table, row));
+      if (current) edit(table, current, toCells(table, row));
+      else add(table, toCells(table, row));
+    },
+    delete: (table, pk) => {
+      checkColumns(table, pk, false);
+      const current = rawGet(table, pkCells(table, pk));
+      if (!current) return; // rebase-friendly no-op
+      remove(table, current);
+    },
+  };
+}
+
+function toServerOp(m: Mutation): ServerDeltaOp {
+  if (m.op === "add") return { table: m.table, type: "add", row: m.row };
+  if (m.op === "remove") return { table: m.table, type: "remove", row: m.row };
+  return { table: m.table, type: "edit", row: m.new, old: m.old };
+}
+
+/** Every base table a query's AST can draw rows from: the root + every related
+ *  subquery + EXISTS subqueries (a conservative deep scan for `table` fields). */
+function collectTables(ast: Ast): Set<string> {
+  const out = new Set<string>();
+  const walk = (v: unknown): void => {
+    if (Array.isArray(v)) {
+      for (const x of v) walk(x);
+    } else if (v && typeof v === "object") {
+      const o = v as Record<string, unknown>;
+      if (typeof o.table === "string") out.add(o.table);
+      for (const k of Object.keys(o)) walk(o[k]);
+    }
+  };
+  walk(ast);
+  return out;
+}
+
+function intersects(a: Set<string>, b: Set<string>): boolean {
+  for (const x of b) if (a.has(x)) return true;
+  return false;
+}
+
+/** Elementwise equality over positional bare-cell rows (the synthetic `__agg` rows are all
+ *  scalar cells — group key + count — so identity comparison suffices). */
+function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}