@rindle/optimistic 0.1.6 → 0.3.1

package/dist/backend.d.ts

@@ -1,7 +1,21 @@
-import type { Ast, Backend, ChangeEvent, ColsMap, Mutation, OptimisticSource, QueryId, RemoteQuery, ResultType, Schema, WireValue } from "@rindle/client";
+import type { Ast, Backend, BackendDevObserver, 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>;
+/** 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).
  *
@@ -20,6 +34,14 @@ export interface MutationTx {
     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;
+    /** 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;
@@ -147,6 +169,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
@@ -192,7 +220,7 @@ export declare class OptimisticBackend<S extends ColsMap> implements Backend {
      *  `unregisterTable` frees it (the engine refuses otherwise). */
     private releaseSyntheticTables;
     unregisterQuery(qid: QueryId): void;
-    retainRemoteQuery(qid: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void;
+    retainRemoteQuery(qid: QueryId, remote: RemoteQuery, localQueryId?: QueryId, ast?: Ast): void;
     releaseRemoteQuery(qid: QueryId): void;
     /** Raw CRUD has no optimistic story (§9 replaces it with named mutators). Register a
      *  mutator — even a trivial one — and `invoke` it. */
@@ -204,6 +232,17 @@ 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 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 +279,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 +298,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

@@ -94,6 +94,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 +133,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);
@@ -279,11 +288,18 @@ export class OptimisticBackend {
         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, remote, localQueryId) {
+    retainRemoteQuery(qid, remote, localQueryId, ast) {
+        if (ast)
+            this.ensureSyntheticTables(qid, ast);
         this.retainRemote(qid, remote, localQueryId);
     }
     releaseRemoteQuery(qid) {
         const remoteQid = this.releaseRemote(qid);
+        this.releaseSyntheticTables(qid);
+        if (!this.queryTables.has(qid)) {
+            this.resultTypes.delete(qid);
+            this.hydrated.delete(qid);
+        }
         if (remoteQid === undefined)
             return;
         this.buffer = this.buffer.filter((f) => f.qid !== remoteQid);
@@ -307,7 +323,28 @@ 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 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`. */
@@ -315,32 +352,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) => {
+                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`
@@ -351,65 +392,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) => {
+                    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
@@ -493,6 +538,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
@@ -566,6 +617,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
@@ -606,6 +659,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
@@ -776,8 +845,6 @@ export class OptimisticBackend {
     /** 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. */
     recomputeResultType(qid) {
-        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
@@ -994,8 +1061,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,