@rindle/optimistic 0.2.0 → 0.4.2

package/src/backend.ts

@@ -38,13 +38,28 @@
 // `Store`/`ArrayView` are untouched: this implements `Backend`, so
 // `new Store(schema, new OptimisticBackend(...))` reuses the whole machinery.
 
-import { CLIENT_MUTATIONS_SCHEMA, LMID_QUERY_NAME, localTableNames, normalizedTableSchemas, tableSpec } from "@rindle/client";
+import {
+  CLIENT_MUTATIONS_SCHEMA,
+  driveMutationSync,
+  isGeneratorMutator,
+  isoTx,
+  LMID_QUERY_NAME,
+  localTableNames,
+  normalizedTableSchemas,
+  tableSpec,
+} from "@rindle/client";
 import type {
   Ast,
   Backend,
+  BackendDevObserver,
   ChangeEvent,
   ColsMap,
+  IsoTx,
+  KeyedRow,
   Mutation,
+  MutationGen,
+  MutationOp,
+  MutatorCtx,
   NormalizedEvent,
   NormalizedOp,
   NormalizedTableSchema,
@@ -61,9 +76,22 @@ 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>;
+/** 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. Re-exported from
+ *  `@rindle/client` (the leaf both tiers share). */
+export type { KeyedRow };
+
+/** What `MutationTx.query` accepts: a query handle whose `.ast()` lowers to the wire
+ *  {@link Ast} — exactly what the typed query builder (`store.query.<table>…` or
+ *  `newQueryBuilder(schema).<table>…`) produces (203-MUTATOR-READS-DESIGN.md §9.1). Typed
+ *  structurally so the `MutationTx` surface need not carry the builder's heavy generics. */
+export type QueryArg = { ast(): Ast };
+
+/** A row returned by {@link MutationTx.query}: column name → cell, plus each materialized
+ *  relationship name → its nested row(s) — an array (a plural relationship), or a single row /
+ *  `null` (a `.one()` relationship). Recursive (nested rows share the shape). Presented
+ *  identically to a `view.data` row of the same query (203-MUTATOR-READS-DESIGN.md §5.2). */
+export type QueryResultRow = { [key: string]: WireValue | QueryResultRow | QueryResultRow[] };
 
 /** 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).
@@ -82,8 +110,19 @@ export interface MutationTx {
   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;
+  /** Insert a FULL row, or do nothing if the pk already exists (the isomorphic form of the classic
+   *  `if (!tx.row(pk)) tx.insert(row)` upsert-if-absent; renders `ON CONFLICT DO NOTHING` server-side). */
+  insertIgnore(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;
+  /** Run a one-shot read query (`where`/`orderBy`/`limit`/join) over the state this
+   *  mutator is mutating — it sees this transaction's own writes-so-far, the same
+   *  read-your-writes contract as `get`/`row` (§4.1; 203-MUTATOR-READS-DESIGN.md §5.2).
+   *  Synchronous; returns the matching rows in the query's order, each with its materialized
+   *  relationship children nested by name (presented identically to a `view.data` row). Pass
+   *  a query from the typed builder, e.g. `tx.query(q.issue.where("owner", "=", me))`.
+   *  Refused inside a FOLDED mutator (a reading mutator is non-absorbing, §9.1). */
+  query(query: QueryArg): QueryResultRow[];
   // --- positional (the wire shape) ---
   get(table: string, pk: WireValue[]): WireValue[] | undefined;
   add(table: string, row: WireValue[]): void;
@@ -91,9 +130,14 @@ export interface MutationTx {
   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;
+/** A client mutator: optimistic, deterministic, replayable — a pure function of `(base, args)` (§5:
+ *  no clock, no randomness; it is RE-INVOKED on every rebase). Either shape is accepted:
+ *  - a plain synchronous function `(tx, args) => void` (client-only), OR
+ *  - a shared GENERATOR `(tx, args, ctx) => MutationGen` (the isomorphic form: the SAME body the API
+ *    server runs against a live async transaction — MUTATORS-ISOMORPHIC). The driver detects which. */
+export type ClientMutator =
+  | ((tx: MutationTx, args: never) => void)
+  | ((tx: IsoTx, args: never, ctx: MutatorCtx) => MutationGen);
 
 /** The client registry (§4.2) — one of the two registries; the server's authoritative
  *  twin shares names (and possibly code), never the wire. */
@@ -182,6 +226,11 @@ interface BufferedFrame {
 export interface OptimisticBackendOptions {
   /** Stable per-client identity for the upstream envelopes (§8.1). */
   clientID: string;
+  /** The acting principal, for a shared (generator) mutator's `ctx.user` — re-read per invoke so a
+   *  mid-session login is picked up, and stable across a rebase re-invoke (replayable). Plain
+   *  client-only mutators ignore it. Defaults to the empty string (an app that registers generator
+   *  mutators must supply this). */
+  user?: () => 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
@@ -255,6 +304,8 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   private readonly source: OptimisticSource;
   private readonly registry: ClientRegistry;
   private readonly clientID: string;
+  /** The acting principal provider for a shared mutator's `ctx.user` (§ shared mutators). */
+  private readonly user: () => string;
   private readonly bufferCap: number;
   /** Column order + pk indices per table, for the keyed `MutationTx` methods. */
   private readonly specs: TableSpecs;
@@ -287,6 +338,12 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
    *  pending delta `displayed = server_base ⊕ local_pending_delta` is applied from. */
   private readonly overlay = new AggOverlay();
   private handler: (qid: QueryId, ev: ChangeEvent) => void = () => {};
+  /** The Store's commit-boundary handler ({@link Backend.onCommitBoundary}), forwarded from the
+   *  local engine's `dispatch` brackets so the Store folds every affected view before notifying any
+   *  subscriber (cross-view-atomic notification). All this backend's data deltas originate from the
+   *  local engine, so its commit brackets are this backend's commit brackets. */
+  private boundaryHandler: (phase: "begin" | "end") => void = () => {};
+  private readonly devObservers = new Set<BackendDevObserver>();
 
   private pendingMutations: PendingMutation[] = [];
   private nextMid = 1;
@@ -328,6 +385,9 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   ) {
     this.local = new WasmBackend(schema);
     this.local.onEvent((qid, ev) => this.handler(qid, ev));
+    // Forward the local engine's commit brackets up to the Store (cross-view-atomic notification):
+    // every data delta this backend emits comes from `this.local`, so its commit boundaries are ours.
+    this.local.onCommitBoundary((phase) => this.boundaryHandler(phase));
     this.colCounts = colCountsFromSchema(schema);
     this.colIndex = colIndexFromSchema(schema);
     this.sync = new NormalizedSync(pkColsFromSchema(schema), this.colCounts);
@@ -336,6 +396,7 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     this.source = source;
     this.registry = registry;
     this.clientID = opts.clientID;
+    this.user = opts.user ?? (() => "");
     this.bufferCap = opts.bufferCap ?? 1024;
     this.clock = opts.clock ?? REAL_CLOCK;
     // Validate each server hello against our OWN typed schema → reject a schema skew
@@ -518,39 +579,86 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     this.handler = handler;
   }
 
+  onCommitBoundary(handler: (phase: "begin" | "end") => void): void {
+    this.boundaryHandler = handler;
+  }
+
   // --- the named-mutator entry (§9) ----------------------------------------------
 
+  /** Bracket a multi-step optimistic apply as ONE notification commit (cross-view-atomic
+   *  notification — {@link Backend.onCommitBoundary}). `invoke`/`invokeFolded` apply the prediction
+   *  and then reconcile the `__agg` head in TWO `this.local` commits, but they are two halves of one
+   *  logical mutation: a relationship-`count` view and the data view it counts must update together.
+   *  The Store's `commitDepth` is a counter, so each inner commit's own `begin`/`end` nests under this
+   *  outer pair and the Store flushes every affected view (data AND count) once, together, at the
+   *  outer `end` — a subscriber re-reading a sibling view then sees post-commit data, never a torn
+   *  half. Balanced on throw (the prediction mutator may reject) via the `finally`, so a thrown
+   *  prediction never wedges the Store in deferred mode. */
+  private inOneCommit<T>(apply: () => T): T {
+    this.boundaryHandler("begin");
+    try {
+      return apply();
+    } finally {
+      this.boundaryHandler("end");
+    }
+  }
+
+  /** Run one client mutator against the staged `tx`, accepting BOTH forms (§ shared mutators):
+   *  a plain sync function runs as-is; a shared GENERATOR is driven synchronously — every yielded
+   *  write applies to the wasm txn now, every `tx.row` read is resolved against the same staged
+   *  state (read-your-writes), the SAME body the API server drives asynchronously. `ctx.user` is
+   *  the acting principal (re-read per invoke, stable across a rebase re-invoke). */
+  private runMutator(mutator: ClientMutator, tx: MutationTx, args: unknown): void {
+    if (isGeneratorMutator(mutator)) {
+      const gen = (mutator as (t: IsoTx, a: never, c: MutatorCtx) => MutationGen)(
+        isoTx,
+        args as never,
+        { user: this.user() },
+      );
+      driveMutationSync(gen, {
+        apply: (op) => applyOpToTx(tx, op),
+        read: (table, pk) => tx.row(table, pk),
+      });
+    } else {
+      (mutator as (t: MutationTx, a: never) => void)(tx, args as never);
+    }
+  }
+
   /** 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.localTables, this.opCollector(ops)), args as never);
+    // One commit boundary spans the prediction AND the `__agg`-head reconcile below, so their views
+    // (data + count) flush together rather than tearing across two engine commits.
+    return this.inOneCommit(() => {
+      // 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) => {
+        this.runMutator(mutator, trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), args);
+      });
+      // 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;
     });
-    // 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
@@ -561,64 +669,68 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     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.localTables, 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)`,
-        );
+    // One commit boundary spans the prediction AND the `__agg`-head reconcile (see {@link inOneCommit}),
+    // so a folded mutation's list view and count view flush together, never torn across two commits.
+    return this.inOneCommit(() => {
+      // 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) => {
+          this.runMutator(mutator, trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops), true), args);
+        });
+      } 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;
       }
-      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;
+      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`,
@@ -701,6 +813,13 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     this.resultTypeHandler = handler;
   }
 
+  __attachDevtoolsServerDeltas(observer: BackendDevObserver): () => void {
+    this.devObservers.add(observer);
+    return () => {
+      this.devObservers.delete(observer);
+    };
+  }
+
   // --- the pending AXIS (§7.2): orthogonal to ResultType -------------------------------
 
   /** Whether any pending mutation (folded or not) touches this query's tables — "is a prediction
@@ -777,6 +896,7 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
   // --- the downstream stream (§8.5: buffer, then release coherently) ---------------
 
   private onNormalized(qid: QueryId, ev: NormalizedEvent): void {
+    if (qid !== LMID_QID) this.emitServerDelta(qid, ev);
     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
@@ -813,6 +933,21 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
     if (this.buffer.length > this.bufferCap) this.overflow();
   }
 
+  private emitServerDelta(sourceQid: QueryId, ev: NormalizedEvent): void {
+    if (!this.devObservers.size) return;
+    for (const qid of this.localQidsForSource(sourceQid)) {
+      for (const o of this.devObservers) o.onServerDelta?.(qid, { format: "normalized", event: ev });
+    }
+  }
+
+  private localQidsForSource(sourceQid: QueryId): QueryId[] {
+    const key = this.sourceToRemote.get(sourceQid);
+    const sub = key ? this.remoteSubs.get(key) : undefined;
+    if (!sub) return [sourceQid];
+    const localQids = [...sub.localQids.keys()];
+    return localQids.length ? localQids : [sourceQid];
+  }
+
   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
@@ -917,7 +1052,7 @@ export class OptimisticBackend<S extends ColsMap> implements Backend {
         const ops: ChildOp[] = [];
         try {
           this.local.writeWith((tx) => {
-            this.registry[p.name](trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), p.args as never);
+            this.runMutator(this.registry[p.name], trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), p.args);
           });
         } catch {
           // A re-invocation threw — e.g. a read-dependent mutator whose base row the server
@@ -1138,6 +1273,24 @@ function colIndexFromSchema<S extends ColsMap>(schema: Schema<S>): Record<string
  *  — 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. */
+/** Apply one logical {@link MutationOp} (yielded by a shared generator mutator) onto the client's
+ *  keyed {@link MutationTx} — the same methods a plain client mutator calls directly. Column
+ *  validation, touched-table tracking, and op collection all happen inside those methods. */
+function applyOpToTx(tx: MutationTx, op: MutationOp): void {
+  switch (op.kind) {
+    case "insert":
+      return tx.insert(op.table, op.row);
+    case "upsert":
+      return tx.upsert(op.table, op.row);
+    case "insertIgnore":
+      return tx.insertIgnore(op.table, op.row);
+    case "update":
+      return tx.update(op.table, op.row);
+    case "delete":
+      return tx.delete(op.table, op.pk);
+  }
+}
+
 function trackingTx(
   tx: WasmWriteTxn,
   touched: Set<string>,
@@ -1225,8 +1378,20 @@ function trackingTx(
     throw new FoldReadError();
   };
 
+  // One-shot query (203 §5.2): lower the builder to an AST, refuse any local-only table it
+  // reads (M1 — same guard as `rawGet`), and run it over the engine's read-cache fork. The
+  // wasm engine returns the rows already keyed by column name with their materialized
+  // relationship children nested by name (`marshal::caught_node_to_js`), in the query's order —
+  // identical in shape to `view.data` — so this is a pass-through.
+  const runQuery = (q: QueryArg): QueryResultRow[] => {
+    const ast = q.ast();
+    for (const t of collectTables(ast)) assertNotLocal(t, "read");
+    return tx.query(ast) as QueryResultRow[];
+  };
+
   return {
     get: trapReads ? trapped : rawGet,
+    query: trapReads ? trapped : runQuery,
     add,
     remove,
     edit,
@@ -1255,6 +1420,10 @@ function trackingTx(
       if (current) edit(table, current, toCells(table, row));
       else add(table, toCells(table, row));
     },
+    insertIgnore: (table, row) => {
+      checkColumns(table, row, true);
+      if (!rawGet(table, pkCells(table, row))) add(table, toCells(table, row));
+    },
     delete: (table, pk) => {
       checkColumns(table, pk, false);
       const current = rawGet(table, pkCells(table, pk));

package/src/client-id.ts

@@ -39,6 +39,22 @@ export function resetTabInstanceForTests(): void {
   tabInstance = 0;
 }
 
+/** Clear the persisted client identity so the next page load starts a fresh mid/lmid stream.
+ *  Intended for dev recovery after out-of-band server state loss, not for normal operation. */
+export function resetStableClientID(): void {
+  try {
+    globalThis.localStorage?.removeItem(CLIENT_ID_KEY);
+  } catch {
+    // Storage can throw in private modes or test shims; best-effort reset.
+  }
+  try {
+    globalThis.sessionStorage?.removeItem(TAB_ID_KEY);
+  } catch {
+    // Storage can throw in private modes or test shims; best-effort reset.
+  }
+  tabInstance = 0;
+}
+
 /** The connection's stable clientID. A per-origin base (localStorage) keeps one logical identity
  *  across reloads; a per-tab suffix (sessionStorage) gives each tab its OWN mid/lmid stream; a
  *  per-load instance suffix keeps two clients constructed in ONE tab from sharing that stream. Falls

package/src/client.ts

@@ -20,7 +20,7 @@ import { initWasm } from "@rindle/wasm";
 
 import type { OptimisticBackend } from "./backend.ts";
 import type { ClientRegistry, MutationTx } from "./backend.ts";
-import { stableClientID } from "./client-id.ts";
+import { resetStableClientID, stableClientID } from "./client-id.ts";
 import { createOptimisticStore, type MutateFn } from "./index.ts";
 import type { Store } from "@rindle/client";
 
@@ -34,6 +34,10 @@ export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry
   schema: Schema<S>;
   /** The PREDICTED mutators (the API server holds the authoritative twins by name). */
   mutators: R;
+  /** The acting principal for a shared (generator) mutator's `ctx.user` — the local identity the
+   *  optimistic prediction writes under (the server injects its OWN authenticated user for the
+   *  authoritative run). Re-read per invoke. Only needed when `mutators` are shared generators. */
+  user?: () => string;
   /** The app API server: named queries resolve to leases here, mutations push here. */
   api: {
     url: string;
@@ -58,6 +62,13 @@ export interface RindleClientOptions<S extends ColsMap, R extends ClientRegistry
   /** A policy rejection's reason (the prediction's snap-back rides the lmid release). */
   onRejected?: (envelope: MutationEnvelope, reason: string) => void;
   queue?: { maxBatch?: number; retryDelayMs?: (attempt: number) => number };
+  /** Development-only recovery knobs. Keep off in production: a mutation gap means state loss
+   *  or two writers sharing a clientID, and should be investigated. */
+  dev?: {
+    /** On a mutation-gap response, clear the persisted clientID and hard reload the page. This
+     *  recovers from dev DB wipes while making the reset visible to the developer. */
+    resetOnMutationGap?: boolean;
+  };
 }
 
 export interface RindleClient<S extends ColsMap, R extends ClientRegistry> {
@@ -90,8 +101,9 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       headers: { "content-type": "application/json", ...extra },
       body: JSON.stringify(payload),
     });
-    if (!res.ok) throw new Error(`rindle api ${path} failed: ${res.status} ${await res.text()}`);
-    return res.json();
+    const text = await res.text();
+    if (!res.ok) throw new RindleApiHttpError(path, res.status, text);
+    return text ? JSON.parse(text) : undefined;
   };
 
   // Reads-leg connection: a fixed transport (tests/in-process) or a replaceable connection built
@@ -116,13 +128,23 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
       retryDelayMs: opts.queue?.retryDelayMs,
       onRejected: opts.onRejected,
       send: async (envelopes) => {
-        const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
-        return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        try {
+          const outcomes = (await post(routes.mutate, { envelopes })) as Array<{ accepted: boolean; reason?: string }>;
+          return outcomes.map((o): PushOutcome => ({ accepted: o.accepted, reason: o.reason }));
+        } catch (err) {
+          if (opts.dev?.resetOnMutationGap && reloadAfterMutationGap(err)) {
+            return new Promise<never>(() => {});
+          }
+          throw err;
+        }
       },
     }),
   });
 
-  const { store, backend, mutate } = createOptimisticStore(opts.schema, source, opts.mutators, { clientID });
+  const { store, backend, mutate } = createOptimisticStore(opts.schema, source, opts.mutators, {
+    clientID,
+    user: opts.user,
+  });
 
   // Drain folds before the tab goes away (FOLDED-MUTATIONS-DESIGN §0.1/§3): a fold deliberately
   // holds its server write through the debounce window, so an unclean navigation would otherwise
@@ -154,3 +176,41 @@ export async function createRindleClient<S extends ColsMap, R extends ClientRegi
 
 export type { ClientRegistry, MutationTx };
 export type { MutateFn } from "./index.ts";
+
+class RindleApiHttpError extends Error {
+  readonly path: string;
+  readonly status: number;
+  readonly body: string;
+
+  constructor(path: string, status: number, body: string) {
+    super(`rindle api ${path} failed: ${status}${body ? ` ${body}` : ""}`);
+    this.name = "RindleApiHttpError";
+    this.path = path;
+    this.status = status;
+    this.body = body;
+  }
+}
+
+const MUTATION_GAP_RE = /\bmutation(?: id)? gap\b/i;
+
+function reloadAfterMutationGap(err: unknown): boolean {
+  const text =
+    err instanceof RindleApiHttpError
+      ? `${err.status} ${err.body} ${err.message}`
+      : String((err as Error)?.message ?? err);
+  if (!MUTATION_GAP_RE.test(text)) return false;
+
+  resetStableClientID();
+  console.error(
+    "[rindle] mutation gap detected; cleared the dev client id and reloading so this tab starts a fresh mutation stream.",
+    err,
+  );
+  const loc = (globalThis as unknown as { location?: { reload?: () => void } }).location;
+  if (typeof loc?.reload !== "function") return false;
+  try {
+    loc.reload();
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/index.ts

@@ -34,14 +34,20 @@ export type {
   OptimisticBackendOptions,
   OptimisticInspect,
   PendingInspect,
+  QueryArg,
+  QueryResultRow,
   ResultType,
 } from "./backend.ts";
 export type { MutationEnvelope, OptimisticSource, ProgressFrame } from "@rindle/client";
+// The shared (generator) mutator seam — a registry may hold plain client mutators OR these isomorphic
+// generators (the SAME body the API server runs); re-exported here so an app registers from one import.
+export { isoTx } from "@rindle/client";
+export type { IsoTx, MutationGen, MutatorCtx, SharedMutator, YieldEffect } from "@rindle/client";
 
 // The one-call client for the daemon/serverless topology (API server + daemon ws).
 export { createRindleClient } from "./client.ts";
 export type { RindleClient, RindleClientOptions } from "./client.ts";
-export { stableClientID } from "./client-id.ts";
+export { resetStableClientID, stableClientID } from "./client-id.ts";
 
 /** A {@link Store} over an {@link OptimisticBackend}, plus the named-mutator entry
  *  (`mutate.createIssue(args)` — the §9 dream shape) and the §6 lifecycle surface. */