@rindle/client 0.2.0 → 0.4.2

package/src/store.ts

@@ -11,7 +11,7 @@ import type { Ast } from "./ast.ts";
 import { stableKey } from "./key.ts";
 import { queries, type Query, type QueryRoot } from "./query.ts";
 import type { ColsMap, RowOf, Schema } from "./schema.ts";
-import type { Backend, ChangeEvent, ColType, Mutation, QueryId, RemoteQuery, ResultType, WireSchema, WireValue } from "./types.ts";
+import type { Backend, ChangeEvent, ColType, FlatChange, Mutation, QueryId, RemoteQuery, ResultType, WireSchema, WireValue } from "./types.ts";
 import { type ArrayView, FlatArrayView, type SingularArrayView, SingularView, type ViewTypes } from "./view.ts";
 
 /** One query's SSR snapshot, keyed by its `viewKey` ({@link stableKey} of the AST): the
@@ -85,18 +85,6 @@ export interface StoreInspect {
   queries: QueryInspect[];
 }
 
-/** A dev-only passive tap over the Store's per-query streams (DEBUG-TOOLS-BROWSER-DESIGN §6.2).
- *  Registered via {@link Store.__attachDevtools}; it ADDS a listener and never displaces the
- *  single `backend.onEvent`/`onResultType` handlers the Store already owns, so attaching devtools
- *  cannot perturb the app. Both hooks are optional. */
-export interface StoreDevObserver {
-  /** The raw per-query {@link ChangeEvent} (hello / snapshot / batch) the Store just routed to its
-   *  view — the source of the devtools delta stream (§4.3). Fired AFTER the view has folded it. */
-  onDelta?(qid: QueryId, ev: ChangeEvent): void;
-  /** A per-query {@link ResultType} transition the Store just applied to its view (§4.2). */
-  onResultType?(qid: QueryId, rt: ResultType): void;
-}
-
 export class Store<S extends ColsMap> {
   /** Type-safe query entry: `store.query.issue.where.closed(false).materialize()`. */
   readonly query: QueryRoot<S>;
@@ -111,15 +99,49 @@ export class Store<S extends ColsMap> {
   // seeded for first paint; a seed is consumed (dropped) the moment its query's first live
   // `hello` lands, so later mounts don't flash stale SSR data.
   private readonly seeds = new Map<string, DehydratedQuery>();
-  // Dev-only devtools taps (DEBUG-TOOLS-BROWSER-DESIGN §6.2). `undefined` until the first
-  // `__attachDevtools`, so a production app that never attaches a pane pays one undefined-check per
-  // routed event and nothing else — there is no global singleton and no hot-path instrumentation.
-  private devObservers?: Set<StoreDevObserver>;
+  // Public per-query change subscribers ({@link subscribeChanges}). `undefined` until the first
+  // subscription, so an app that never narrates (nor attaches devtools) pays one undefined-check per
+  // routed event and nothing else — no global singleton, no hot-path instrumentation. Each listener
+  // also receives the post-fold view for the qid (always the plural {@link ArrayView}, even for a
+  // `.one()` query — the Store retains the list-shaped view, not the SingularView wrapper).
+  private changeListeners?: Set<(qid: QueryId, ev: ChangeEvent, view?: ArrayView<unknown>) => void>;
+  // How many active change subscribers asked for removed subtrees ({@link subscribeChanges} opts).
+  // `> 0` ⇒ the view reconstructs each evicted subtree onto its `remove` op before fan-out. A plain
+  // counter: the cost is paid only while at least one consumer wants it, and only on real evictions.
+  private removedSubtreeWanted = 0;
+  // Public per-query {@link ResultType} subscribers ({@link subscribeResultType}). `undefined` until
+  // the first subscription. Devtools and any status-driven layer ride this instead of a private tap.
+  private resultTypeListeners?: Set<(qid: QueryId, rt: ResultType) => void>;
+  // Cross-view-atomic notification (the `Backend.onCommitBoundary` contract): while the backend is
+  // delivering one commit's coherent multi-query batch, fold every affected view but DEFER each
+  // view's subscriber notification, collecting the changed views here; at the commit's `end` flush
+  // them all. So when any view's subscriber runs, every sibling view touched by the same commit has
+  // already folded — a callback that re-reads another view sees post-commit data. `> 0` ⇒ inside a
+  // commit (defer); `0` ⇒ notify inline (the prior behavior, and what a backend with no commit
+  // boundary always gets). A depth counter (not a bool) is robust to any future nesting.
+  private commitDepth = 0;
+  private readonly pendingFlush = new Set<FlatArrayView>();
+  // The raw change-stream frames ({@link subscribeChanges}) buffered during a commit, delivered
+  // together at the boundary alongside the view flush — so a change listener (narrator/devtools)
+  // that re-reads ANY view also sees post-commit state, the same cross-view-atomic guarantee view
+  // subscribers get. Only filled while a commit is open AND a change listener exists; otherwise it
+  // stays empty and untouched (the no-narrator hot path is one undefined-check, as before).
+  private readonly pendingChanges: Array<[QueryId, ChangeEvent]> = [];
 
   constructor(schema: Schema<S>, backend: Backend) {
     this.schema = schema;
     this.backend = backend;
     this.backend.onEvent((qid, ev) => this.onEvent(qid, ev));
+    // The in-process engine brackets each commit's multi-query delivery so every affected view
+    // folds before any subscriber is notified (see `commitDepth`/`pendingFlush`). A backend with no
+    // such boundary never enters deferred mode, so its views notify inline exactly as before.
+    this.backend.onCommitBoundary?.((phase) => {
+      if (phase === "begin") {
+        this.commitDepth++;
+      } else if (this.commitDepth > 0 && --this.commitDepth === 0) {
+        this.flushCommit();
+      }
+    });
     // Route the backend's per-query lifecycle onto its view (`view.resultType`). Backends without a
     // lifecycle omit `onResultType`, leaving every view `complete`. A devtools tap mirrors the
     // transition (it never displaces this single handler).
@@ -131,7 +153,7 @@ export class Store<S extends ColsMap> {
         if (rt === "complete" && sync.seedKey !== undefined) this.seeds.delete(sync.seedKey);
         for (const listener of sync.listeners) listener();
       }
-      if (this.devObservers) for (const o of this.devObservers) o.onResultType?.(qid, rt);
+      if (this.resultTypeListeners) for (const l of this.resultTypeListeners) l(qid, rt);
     });
     // `store.query` is the LOCAL builder (201-LOCAL-ONLY-TABLES-DESIGN.md §5): it scopes over
     // synced AND local-only tables, so a local query can join the two. Server/named queries use
@@ -341,8 +363,10 @@ export class Store<S extends ColsMap> {
     this.asts.set(qid, ast);
     // Pre-create the view (PENDING) so `materialize` is synchronous for ANY backend — a remote
     // backend's `hello` arrives async (the view reads as `[]` until then). A synchronous backend
-    // (wasm/replica) resets it during `registerQuery` below, so it returns already-hydrated.
-    const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView()).get(qid)!;
+    // (wasm/replica) resets it during `registerQuery` below, so it returns already-hydrated. The
+    // view carries its `qid` (exposed as `view.qid`) so a consumer can correlate it with the raw
+    // change stream straight off `materialize(query).qid`.
+    const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView(undefined, undefined, qid)).get(qid)!;
     // Wire teardown: `destroy()` must unregister the query from the backend and drop our routing
     // entry. Otherwise the engine keeps emitting events for the destroyed query and the Store
     // routes them to the now-empty view — which throws on the next Child/remove ("parent not
@@ -397,31 +421,130 @@ export class Store<S extends ColsMap> {
       const types = ast ? this.viewTypes(ev.schema, ast) : undefined;
       // Reset the (pre-created or existing) view IN PLACE — first hello OR a re-hydrate (new
       // epoch) — so the materialized reference the caller holds survives a re-subscribe.
-      const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView()).get(qid)!;
+      const view = this.views.get(qid) ?? this.views.set(qid, new FlatArrayView(undefined, undefined, qid)).get(qid)!;
       view.reset(ev.schema, types);
     } else if (ev.type === "snapshot") {
-      this.views.get(qid)?.applyChanges(ev.adds);
+      this.applyAndTrack(qid, ev.adds);
     } else {
-      this.views.get(qid)?.applyChanges(ev.events);
+      this.applyAndTrack(qid, ev.events);
+    }
+    // Fan the same post-fold frame out to subscribers (narration, devtools, …). Inside a commit
+    // bracket the frames are BUFFERED and delivered together at the boundary (after every view has
+    // folded), so a listener re-reading ANY view sees post-commit state — the same cross-view-atomic
+    // guarantee view subscribers get; outside one they go inline (still after this view's own fold,
+    // so the post-fold view passed here — and any re-read of it — reflects the post-apply state, and
+    // an opted-in removed subtree the view just attached rides along on the `remove` op).
+    // No-op (one undefined-check) when nothing is subscribed.
+    if (this.changeListeners) {
+      if (this.commitDepth > 0) this.pendingChanges.push([qid, ev]);
+      else {
+        const view = this.views.get(qid);
+        for (const l of this.changeListeners) l(qid, ev, view);
+      }
     }
-    // Mirror the raw delta to any devtools tap, AFTER the view has folded it (so a pane re-reading
-    // `__inspect` sees the post-apply state). No-op (one undefined-check) when no pane is attached.
-    if (this.devObservers) for (const o of this.devObservers) o.onDelta?.(qid, ev);
   }
 
-  // --- dev-only introspection (DEBUG-TOOLS-BROWSER-DESIGN §2/§6.2) --------------
-  // A single read-only accessor + a passive tap per the design's "surface, not instrument" rule.
-  // Only ever called by `@rindle/devtools` (imported in dev); inert otherwise.
+  /** Fold a batch into its view, then notify now or — inside a commit bracket — defer the view's
+   *  notification to the commit boundary, so all sibling views fold first (cross-view-atomic
+   *  notification; see `commitDepth`). */
+  private applyAndTrack(qid: QueryId, events: FlatChange[]): void {
+    const view = this.views.get(qid);
+    if (!view) return;
+    const deferring = this.commitDepth > 0;
+    if (view.applyChanges(events, this.removedSubtreeWanted > 0, deferring) && deferring) {
+      this.pendingFlush.add(view);
+    }
+  }
+
+  /** Deliver everything deferred during the just-ended commit, after every affected view has folded
+   *  (cross-view-atomic notification): view subscribers first, then the raw change stream
+   *  (narrators/devtools), each frame in arrival order. A throwing listener does not stop the others
+   *  — the first error is re-raised only once the whole flush completes (mirroring the backend's
+   *  per-query isolation). View subscribers run before change listeners, preserving the per-event
+   *  order that held before coalescing (a view's subscribers fired before its change frame). */
+  private flushCommit(): void {
+    const views = this.pendingFlush.size > 0 ? [...this.pendingFlush] : [];
+    if (views.length) this.pendingFlush.clear();
+    const changes = this.pendingChanges.length > 0 ? this.pendingChanges.splice(0) : [];
+    if (views.length === 0 && changes.length === 0) return;
+    let firstError: unknown;
+    let hasError = false;
+    const note = (e: unknown): void => {
+      if (!hasError) {
+        hasError = true;
+        firstError = e;
+      }
+    };
+    for (const view of views) {
+      try {
+        view.flush();
+      } catch (e) {
+        note(e);
+      }
+    }
+    if (this.changeListeners) {
+      for (const [qid, ev] of changes) {
+        const view = this.views.get(qid);
+        for (const l of this.changeListeners) {
+          try {
+            l(qid, ev, view);
+          } catch (e) {
+            note(e);
+          }
+        }
+      }
+    }
+    if (hasError) throw firstError;
+  }
 
-  /** Register a devtools {@link StoreDevObserver}; returns a detach function. Multiple panes may
-   *  attach. The observer is ADDITIVE — it does not touch the backend's single handler slots. */
-  __attachDevtools(observer: StoreDevObserver): () => void {
-    (this.devObservers ??= new Set()).add(observer);
+  /** Subscribe to the raw per-query {@link ChangeEvent} stream (hello / snapshot / batch) the Store
+   *  routes to its views, tagged by `qid`. Fired AFTER the event is folded — and, for a commit that
+   *  fans out to several queries (the in-process engine's `onCommitBoundary`), after EVERY view in
+   *  that commit has folded — so a listener that re-reads ANY view (its own or a sibling) sees
+   *  post-commit state, never a torn mid-commit one. Frames keep their arrival (engine-dispatch)
+   *  order, one per affected query. This is the supported way to drive change-derived layers
+   *  (e.g. {@link resolveChange} → @rindle/narrator, or a devtools pane) off a live store — attach
+   *  BEFORE `materialize` to catch a synchronous backend's first `hello`+`snapshot`.
+   *  The per-query view `WireSchema` rides the `hello` frame (also readable via `view.schema`).
+   *
+   *  The third listener arg is the post-fold {@link ArrayView} for this `qid` (so a template wanting
+   *  list context — current `data`, `schema`, `resultType` — needn't look it up). It is ALWAYS the
+   *  plural view, even for a top-level `.one()` query: the Store retains the list-shaped view, not the
+   *  SingularView wrapper handed back from `materialize`. `undefined` only if the view is mid-teardown.
+   *
+   *  `opts.removedSubtree` enriches every `remove` op on this stream with the full removed subtree
+   *  ({@link FlatOp.node}), so a consumer can resolve a removed row's nested subs exactly as on an
+   *  `add` (a bare remove carries only the leaving row). It is reconstructed client-side from the
+   *  view — no wire/engine cost — and paid only on real evictions while at least one subscriber asks.
+   *
+   *  Returns a detach function; multiple listeners may attach. */
+  subscribeChanges(
+    listener: (qid: QueryId, ev: ChangeEvent, view?: ArrayView<unknown>) => void,
+    opts?: { removedSubtree?: boolean },
+  ): () => void {
+    (this.changeListeners ??= new Set()).add(listener);
+    if (opts?.removedSubtree) this.removedSubtreeWanted++;
     return () => {
-      this.devObservers?.delete(observer);
+      if (this.changeListeners?.delete(listener) && opts?.removedSubtree) this.removedSubtreeWanted--;
     };
   }
 
+  /** Subscribe to per-query {@link ResultType} transitions (the server-channel lifecycle the backend
+   *  pushes — `unknown` → `complete`, etc.), tagged by `qid`. Fired only on a CHANGE (never replayed
+   *  on attach; read `view.resultType` for the current value). The supported seam for a status-driven
+   *  layer (a devtools pane). Returns a detach function; multiple listeners may attach. */
+  subscribeResultType(listener: (qid: QueryId, rt: ResultType) => void): () => void {
+    (this.resultTypeListeners ??= new Set()).add(listener);
+    return () => {
+      this.resultTypeListeners?.delete(listener);
+    };
+  }
+
+  // --- dev-only introspection (DEBUG-TOOLS-BROWSER-DESIGN §2/§6.2) --------------
+  // A single read-only accessor per the design's "surface, not instrument" rule. Only ever called
+  // by `@rindle/devtools` (imported in dev); inert otherwise. The delta + resultType taps devtools
+  // also needs are the SUPPORTED `subscribeChanges` / `subscribeResultType` seams above.
+
   /** A read-only snapshot of every live materialized view (DEBUG-TOOLS-BROWSER-DESIGN §4.2): its
    *  qid, AST, {@link ResultType}, row count, and a capped row sample. Built fresh on each call from
    *  the live `views`/`asts` maps — never cached, never mutating. `sampleRows` caps the per-query

package/src/types.ts

@@ -52,9 +52,14 @@ export interface PathSeg {
   parentRow: WireValue[];
 }
 
+/** A positional change at one level of the view tree. A `remove` ships only the leaving `row`
+ *  (the receiver already holds the subtree and locates it by key) — `node` is NEVER on the wire;
+ *  it is an OPTIONAL client-side enrichment carrying the full removed subtree, attached by the
+ *  ArrayView when a change consumer opts in (`Store.subscribeChanges(_, { removedSubtree: true })`),
+ *  so a narrator can resolve a removed row's nested subs just as it can on an `add`. */
 export type FlatOp =
   | { tag: "add"; node: WireNode }
-  | { tag: "remove"; row: WireValue[] }
+  | { tag: "remove"; row: WireValue[]; node?: WireNode }
   | { tag: "edit"; old: WireValue[]; new: WireValue[] };
 
 export interface FlatChange {
@@ -113,6 +118,20 @@ export type NormalizedEvent =
 
 export type QueryId = number;
 
+/** A dev-only authoritative server delta exposed by backends that can distinguish the upstream
+ *  server stream from their local view/IVM stream. Flat remote backends surface clean
+ *  {@link ChangeEvent}s; local-first normalized/optimistic backends surface the path-free
+ *  {@link NormalizedEvent}s before they are folded into the local engine. */
+export type BackendServerDelta =
+  | { format: "flat"; event: ChangeEvent }
+  | { format: "normalized"; event: NormalizedEvent };
+
+/** Dev-only passive tap over a backend's authoritative server stream. Optional because in-process
+ *  backends have no server stream, and older/custom backends may only expose the Store tap. */
+export interface BackendDevObserver {
+  onServerDelta?(qid: QueryId, ev: BackendServerDelta): void;
+}
+
 /** A query's SERVER-CHANNEL state, surfaced on its {@link ArrayView} (FOLDED-MUTATIONS-DESIGN §7 —
  *  formerly conflated with pending-ness, OPTIMISTIC-WRITES-DESIGN.md §6):
  *   - `unknown`  — not hydrated: the server has not produced a first result for this query yet;
@@ -161,6 +180,21 @@ export interface Backend {
    *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the
    *  in-process engine) omit it and every view stays `complete`. */
   onResultType?(handler: (queryId: QueryId, resultType: ResultType) => void): void;
+  /** Optional: brackets one commit's coherent multi-query delivery so the Store can fold every
+   *  affected view BEFORE notifying any subscriber — cross-view-atomic notification. The
+   *  in-process engine derives the whole commit's per-query deltas against one consistent post-
+   *  commit snapshot, then dispatches them one query at a time; without a barrier a subscriber on
+   *  the first-dispatched view, re-reading a sibling view in its callback, would observe that
+   *  sibling's PRE-commit state (it has not folded yet). The backend calls the handler with
+   *  `"begin"` before delivering a commit's per-query `batch` events (via {@link onEvent}) and
+   *  `"end"` after the last one; between them the Store folds each view but DEFERS its
+   *  notification, firing every affected view's subscribers together at `"end"`. Backends with no
+   *  synchronous multi-query commit boundary (a plain remote backend, where each query's frame
+   *  arrives in its own message) omit it — the Store then notifies per event, exactly as before. */
+  onCommitBoundary?(handler: (phase: "begin" | "end") => void): void;
+  /** Optional dev-only authoritative server stream tap. It is additive, like
+   *  `Store.subscribeChanges`, and must not displace the backend's normal event handler. */
+  __attachDevtoolsServerDeltas?(observer: BackendDevObserver): () => void;
 }
 
 /**

package/src/view.ts

@@ -9,7 +9,7 @@
 // and untouched subtrees keep their object identity (React/Solid memoize on it).
 
 import { compareRows } from "./compare.ts";
-import type { ColType, FlatChange, FlatOp, ResultType, WireNode, WireSchema, WireValue } from "./types.ts";
+import type { ColType, FlatChange, FlatOp, QueryId, ResultType, WireNode, WireSchema, WireValue } from "./types.ts";
 
 /** Per-level column types (parallel to the WireSchema), used to JSON.parse json columns on
  *  projection. Built by the Store from the typed schema; absent ⇒ no parsing (bare values). */
@@ -22,6 +22,15 @@ export interface ViewTypes {
 export interface ArrayView<R> {
   /** The current materialized result (reference-stable where data is unchanged). */
   readonly data: readonly R[];
+  /** The engine query id the Store assigned this view (1:1 with the view). The same `qid` the raw
+   *  change stream ({@link Store.subscribeChanges}) tags each frame with, so a consumer can
+   *  correlate this query with its `ChangeEvent`s (e.g. to bind a narrator) straight off
+   *  `materialize(query).qid` — no separate handle needed. */
+  readonly qid: QueryId;
+  /** The query's view `WireSchema` (the position→name source for {@link resolveChange}), captured
+   *  from its `hello` frame. `null` while PENDING — a remote backend's `hello` arrives async; an
+   *  in-process backend (wasm/replica) populates it synchronously during `materialize`. */
+  readonly schema: WireSchema | null;
   /** The query's SERVER-CHANNEL state (`unknown` while loading, `complete` once server-authoritative;
    *  the `error` variant is reserved and currently unproduced). A pending optimistic mutation no
    *  longer moves this — it is a separate axis (FOLDED-MUTATIONS-DESIGN §7). `complete` for backends
@@ -40,6 +49,10 @@ export interface ArrayView<R> {
 export interface SingularArrayView<R> {
   /** The single current row, or `null` when the query matches nothing. */
   readonly data: R | null;
+  /** The engine query id — see {@link ArrayView.qid}. */
+  readonly qid: QueryId;
+  /** The query's view `WireSchema` — see {@link ArrayView.schema}. */
+  readonly schema: WireSchema | null;
   /** The query's lifecycle state — see {@link ArrayView.resultType}. */
   readonly resultType: ResultType;
   /** Subscribe; fires immediately with the current row, then after each applied batch (and after
@@ -62,6 +75,14 @@ export class SingularView<R> implements SingularArrayView<R> {
     return this.inner.data[0] ?? null;
   }
 
+  get qid(): QueryId {
+    return this.inner.qid;
+  }
+
+  get schema(): WireSchema | null {
+    return this.inner.schema;
+  }
+
   get resultType(): ResultType {
     return this.inner.resultType;
   }
@@ -124,6 +145,22 @@ function cloneNode(n: Node): Node {
   return { row: n.row.slice(), rc: n.rc, rels: n.rels.map((r) => r.map(cloneNode)), out: null };
 }
 
+/** Reconstruct a positional {@link WireNode} (row + its populated child slots) from a maintained
+ *  {@link Node} — the inverse of {@link buildNode}. Used to attach a removed subtree to a `remove`
+ *  op so a change consumer (a narrator) can resolve its nested subs, which a bare positional remove
+ *  (just the leaving row) cannot carry. Only in-view (`child !== null`), non-empty slots are emitted,
+ *  matching how an `add` node ships only populated relationships. */
+function toWireNode(node: Node, schema: WireSchema): WireNode {
+  const rels: { rel: number; children: WireNode[] }[] = [];
+  for (const rel of schema.relationships) {
+    if (rel.child === null) continue;
+    const childList = node.rels[rel.slot] ?? [];
+    if (childList.length === 0) continue;
+    rels.push({ rel: rel.slot, children: childList.map((c) => toWireNode(c, rel.child as WireSchema)) });
+  }
+  return { row: node.row, rels };
+}
+
 function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
   return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
 }
@@ -131,9 +168,13 @@ function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
 const EMPTY: readonly never[] = Object.freeze([]);
 
 export class FlatArrayView<R = unknown> implements ArrayView<R> {
+  // The engine query id (Store-assigned, 1:1 with this view), exposed read-only via {@link qid}.
+  // `0` ⇒ unbound (a bare view never registered with a Store); the Store passes it at construction.
+  private readonly _qid: QueryId;
   // `null` ⇒ PENDING (no schema yet): a remote backend's `hello` arrives async, so the view
   // exists (and reads as `[]`) before its schema lands. Set by `reset` (first hello / re-hydrate).
-  private schema: WireSchema | null;
+  // Exposed read-only via the {@link schema} getter (the position→name source for `resolveChange`).
+  private _schema: WireSchema | null;
   private types?: ViewTypes;
   // SSR first-paint seed (SSR-DESIGN.md §6): pre-projected rows installed by `seed`, returned by
   // `data` WHILE pending (no live schema yet). Cleared on `reset` — the first live `hello` —
@@ -148,9 +189,18 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   private rt: ResultType = "complete";
   private readonly listeners = new Set<(data: readonly R[]) => void>();
 
-  constructor(schema?: WireSchema, types?: ViewTypes) {
-    this.schema = schema ?? null;
+  constructor(schema?: WireSchema, types?: ViewTypes, qid: QueryId = 0) {
+    this._schema = schema ?? null;
     this.types = types;
+    this._qid = qid;
+  }
+
+  get qid(): QueryId {
+    return this._qid;
+  }
+
+  get schema(): WireSchema | null {
+    return this._schema;
   }
 
   get resultType(): ResultType {
@@ -171,7 +221,7 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  the caller's view reference and its subscribers survive a re-subscribe. Does NOT notify —
    *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker. */
   reset(schema: WireSchema, types?: ViewTypes): void {
-    this.schema = schema;
+    this._schema = schema;
     this.types = types;
     this.seeded = null; // live data takes over; the seed was first-paint only
     this.top = [];
@@ -190,20 +240,41 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
 
   /** Apply a batch (the hydrate snapshot or one transaction's events) in order, then
    *  notify subscribers once. Order is significant (FLAT-CHANGES-DESIGN.md §5.4). A no-op
-   *  while pending (changes never precede the `hello` that resets the schema). */
-  applyChanges(events: FlatChange[]): void {
-    if (this.schema === null) return;
+   *  while pending (changes never precede the `hello` that resets the schema).
+   *
+   *  `enrichRemoves` ⇒ before a removed node is dropped, reconstruct its full subtree and attach it
+   *  to the `remove` op's `node` (in place, so the same event object the Store fans out to its
+   *  change subscribers carries it). Off by default — paid only when a consumer asked for it, and
+   *  only on a real eviction (an rc-decrement that keeps the row leaves `node` absent).
+   *
+   *  `deferNotify` ⇒ fold but do NOT notify; the caller is responsible for calling {@link flush}
+   *  later. The Store uses this to fold every view in one commit before notifying any subscriber
+   *  (cross-view-atomic notification — `Store.onCommitBoundary`); standalone use leaves it off, so
+   *  a bare view still fires its subscribers after each applied batch.
+   *
+   *  Returns whether the batch changed the view (so a deferring caller knows it must be flushed). */
+  applyChanges(events: FlatChange[], enrichRemoves = false, deferNotify = false): boolean {
+    if (this._schema === null) return false;
     let changed = false;
-    for (const e of events) changed = this.applyAt(this.top, this.schema, e.path, e.op, 0) || changed;
-    if (!changed) return;
+    for (const e of events) changed = this.applyAt(this.top, this._schema, e.path, e.op, 0, enrichRemoves) || changed;
+    if (!changed) return false;
     this.dirty = true;
+    if (!deferNotify) this.notify();
+    return true;
+  }
+
+  /** Notify subscribers with the current data. The deferred half of {@link applyChanges} (when
+   *  `deferNotify` was set): the Store calls this at the commit-notify barrier — after every view
+   *  touched by the same commit has folded — so a subscriber that re-reads a sibling view inside
+   *  its callback observes post-commit data, never a torn mid-commit state. */
+  flush(): void {
     this.notify();
   }
 
   get data(): readonly R[] {
-    if (this.schema === null) return this.seeded ?? (EMPTY as readonly R[]);
+    if (this._schema === null) return this.seeded ?? (EMPTY as readonly R[]);
     if (!this.dirty && this.cached !== null) return this.cached;
-    this.cached = this.top.map((n) => this.project(n, this.schema as WireSchema, this.types)) as R[];
+    this.cached = this.top.map((n) => this.project(n, this._schema as WireSchema, this.types)) as R[];
     this.dirty = false;
     return this.cached;
   }
@@ -223,9 +294,9 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
 
   // --- apply -------------------------------------------------------------------
 
-  private applyAt(list: Node[], schema: WireSchema, path: FlatChange["path"], op: FlatOp, depth: number): boolean {
+  private applyAt(list: Node[], schema: WireSchema, path: FlatChange["path"], op: FlatOp, depth: number, enrichRemoves: boolean): boolean {
     if (depth === path.length) {
-      return this.applyOp(list, schema, op);
+      return this.applyOp(list, schema, op, enrichRemoves);
     }
     const seg = path[depth];
     const child = schema.relationships[seg.rel]?.child;
@@ -233,14 +304,20 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     const { found, index } = binarySearch(list, seg.parentRow, schema.sort);
     if (!found) throw new Error("flat ArrayView: parent not found at path hop (inconsistent stream)");
     const node = list[index];
-    const changed = this.applyAt(node.rels[seg.rel], child, path, op, depth + 1);
+    const changed = this.applyAt(node.rels[seg.rel], child, path, op, depth + 1, enrichRemoves);
     if (changed) node.out = null; // a descendant changed → this node must re-project its rel array
     return changed;
   }
 
-  private applyOp(list: Node[], schema: WireSchema, op: FlatOp): boolean {
+  private applyOp(list: Node[], schema: WireSchema, op: FlatOp, enrichRemoves: boolean): boolean {
     if (op.tag === "add") return this.applyAdd(list, schema, op.node);
-    if (op.tag === "remove") return this.applyRemove(list, schema, op.row);
+    if (op.tag === "remove") {
+      const removed = this.applyRemove(list, schema, op.row);
+      // Attach the full removed subtree (in place) for an opted-in consumer; absent when the row
+      // only lost a reference (rc > 1) and so did not actually leave the result.
+      if (removed && enrichRemoves) op.node = toWireNode(removed, schema);
+      return removed !== null;
+    }
     return this.applyEdit(list, schema, op.old, op.new);
   }
 
@@ -254,15 +331,19 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     return true;
   }
 
-  private applyRemove(list: Node[], schema: WireSchema, row: WireValue[]): boolean {
+  /** Drop one path to `row`. Returns the evicted {@link Node} (its full subtree intact) when the
+   *  last path went away — `null` when another path still holds it (rc decremented, nothing left
+   *  the result). */
+  private applyRemove(list: Node[], schema: WireSchema, row: WireValue[]): Node | null {
     const at = binarySearch(list, row, schema.sort);
     if (!at.found) throw new Error("flat ArrayView: remove of a non-existent node");
-    if (list[at.index].rc === 1) {
+    const node = list[at.index];
+    if (node.rc === 1) {
       list.splice(at.index, 1);
-      return true;
+      return node;
     }
-    list[at.index].rc -= 1;
-    return false;
+    node.rc -= 1;
+    return null;
   }
 
   private applyEdit(list: Node[], schema: WireSchema, oldRow: WireValue[], newRow: WireValue[]): boolean {