@rindle/optimistic 0.2.0 → 0.4.2

package/dist/backend.d.ts

@@ -1,7 +1,22 @@
-import type { Ast, Backend, ChangeEvent, ColsMap, Mutation, OptimisticSource, QueryId, RemoteQuery, ResultType, Schema, WireValue } from "@rindle/client";
-/** 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>;
+import type { Ast, Backend, BackendDevObserver, ChangeEvent, ColsMap, IsoTx, KeyedRow, Mutation, MutationGen, MutatorCtx, OptimisticSource, QueryId, RemoteQuery, ResultType, Schema, WireValue } from "@rindle/client";
+/** 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).
  *
@@ -18,16 +33,30 @@ 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[];
     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;
+/** 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. */
 export type ClientRegistry = Record<string, ClientMutator>;
@@ -63,6 +92,11 @@ export interface FoldHandle {
 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
@@ -115,6 +149,8 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
     private readonly source;
     private readonly registry;
     private readonly clientID;
+    /** The acting principal provider for a shared mutator's `ctx.user` (§ shared mutators). */
+    private readonly user;
     private readonly bufferCap;
     /** Column order + pk indices per table, for the keyed `MutationTx` methods. */
     private readonly specs;
@@ -147,6 +183,12 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  pending delta `displayed = server_base ⊕ local_pending_delta` is applied from. */
     private readonly overlay;
     private handler;
+    /** 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;
+    private readonly devObservers;
     private pendingMutations;
     private nextMid;
     /** The live fold entries, by fold key `${name}\0${identityJSON}` — at most one per key
@@ -204,6 +246,23 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  non-reentrant (A5), so a local write can never interleave with an open server cycle. */
     writeLocal(mutations: Mutation[]): void;
     onEvent(handler: (qid: QueryId, ev: ChangeEvent) => void): void;
+    onCommitBoundary(handler: (phase: "begin" | "end") => void): void;
+    /** 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;
+    /** 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;
     /** 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`. */
@@ -240,6 +299,7 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  A pending local mutation no longer moves it — see {@link pending}. */
     resultType(qid: QueryId): ResultType;
     onResultType(handler: (qid: QueryId, rt: ResultType) => void): void;
+    __attachDevtoolsServerDeltas(observer: BackendDevObserver): () => void;
     /** 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`. */
@@ -258,6 +318,8 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  (remove) — exactly where `:359`/`:468` used to flip ResultType (§7.3). */
     private refreshPending;
     private onNormalized;
+    private emitServerDelta;
+    private localQidsForSource;
     private onProgress;
     /** 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. */

package/dist/backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../src/backend.ts"],"names":[],"mappings":"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"}

package/dist/backend.js

@@ -37,7 +37,7 @@
 //
 // `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 { aggTableSchemas, NormalizedSync, rewriteAggregates } from "@rindle/normalized";
 import { WasmBackend } from "@rindle/wasm";
 import { AggOverlay, collectAggDefs } from "./agg-overlay.js";
@@ -62,6 +62,8 @@ export class OptimisticBackend {
     source;
     registry;
     clientID;
+    /** The acting principal provider for a shared mutator's `ctx.user` (§ shared mutators). */
+    user;
     bufferCap;
     /** Column order + pk indices per table, for the keyed `MutationTx` methods. */
     specs;
@@ -94,6 +96,12 @@ export class OptimisticBackend {
      *  pending delta `displayed = server_base ⊕ local_pending_delta` is applied from. */
     overlay = new AggOverlay();
     handler = () => { };
+    /** 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. */
+    boundaryHandler = () => { };
+    devObservers = new Set();
     pendingMutations = [];
     nextMid = 1;
     /** The live fold entries, by fold key `${name}\0${identityJSON}` — at most one per key
@@ -127,6 +135,9 @@ export class OptimisticBackend {
     constructor(schema, source, registry, opts) {
         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);
@@ -135,6 +146,7 @@ export class OptimisticBackend {
         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
@@ -314,7 +326,45 @@ export class OptimisticBackend {
     onEvent(handler) {
         this.handler = handler;
     }
+    onCommitBoundary(handler) {
+        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. */
+    inOneCommit(apply) {
+        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). */
+    runMutator(mutator, tx, args) {
+        if (isGeneratorMutator(mutator)) {
+            const gen = mutator(isoTx, args, { user: this.user() });
+            driveMutationSync(gen, {
+                apply: (op) => applyOpToTx(tx, op),
+                read: (table, pk) => tx.row(table, pk),
+            });
+        }
+        else {
+            mutator(tx, args);
+        }
+    }
     /** 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`. */
@@ -322,32 +372,36 @@ export class OptimisticBackend {
         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();
-        const ops = [];
-        this.local.writeWith((tx) => {
-            mutator(trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), args);
+        // 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();
+            const ops = [];
+            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
      *  (like `invoke`), but collapse a run of same-key invokes into ONE pending entry whose `args`
@@ -358,65 +412,69 @@ export class OptimisticBackend {
         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();
-        const ops = [];
-        try {
-            this.local.writeWith((tx) => {
-                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)`);
+        // 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();
+            const ops = [];
+            try {
+                this.local.writeWith((tx) => {
+                    this.runMutator(mutator, trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops), true), args);
+                });
             }
-            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 = { mid: null, name, args, touched };
-            this.pendingMutations.push(entry);
-            let resolveMid;
-            const midPromise = new Promise((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 = { flush: () => this.flushFold(foldKey), mid: f.midPromise };
-        return handle;
+            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 = { mid: null, name, args, touched };
+                this.pendingMutations.push(entry);
+                let resolveMid;
+                const midPromise = new Promise((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 = { 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
@@ -500,6 +558,12 @@ export class OptimisticBackend {
     onResultType(handler) {
         this.resultTypeHandler = handler;
     }
+    __attachDevtoolsServerDeltas(observer) {
+        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
      *  pending here?" (FOLDED-MUTATIONS-DESIGN §7.2). Orthogonal to {@link resultType}; this is the
@@ -573,6 +637,8 @@ export class OptimisticBackend {
     }
     // --- the downstream stream (§8.5: buffer, then release coherently) ---------------
     onNormalized(qid, ev) {
+        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
@@ -613,6 +679,22 @@ export class OptimisticBackend {
         if (this.buffer.length > this.bufferCap)
             this.overflow();
     }
+    emitServerDelta(sourceQid, ev) {
+        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 });
+        }
+    }
+    localQidsForSource(sourceQid) {
+        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];
+    }
     onProgress(frame) {
         // (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
@@ -714,7 +796,7 @@ export class OptimisticBackend {
                 const ops = [];
                 try {
                     this.local.writeWith((tx) => {
-                        this.registry[p.name](trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), p.args);
+                        this.runMutator(this.registry[p.name], trackingTx(tx, touched, this.specs, this.localTables, this.opCollector(ops)), p.args);
                     });
                 }
                 catch {
@@ -931,6 +1013,23 @@ function colIndexFromSchema(schema) {
  *  — 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, op) {
+    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, touched, specs, localTables, onOp, trapReads = false) {
     const spec = (table) => {
         const s = specs[table];
@@ -999,8 +1098,20 @@ function trackingTx(tx, touched, specs, localTables, onOp, trapReads = false) {
     const trapped = () => {
         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) => {
+        const ast = q.ast();
+        for (const t of collectTables(ast))
+            assertNotLocal(t, "read");
+        return tx.query(ast);
+    };
     return {
         get: trapReads ? trapped : rawGet,
+        query: trapReads ? trapped : runQuery,
         add,
         remove,
         edit,
@@ -1032,6 +1143,11 @@ function trackingTx(tx, touched, specs, localTables, onOp, trapReads = false) {
             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));