@rindle/client 0.4.2 → 0.4.4

package/src/store.ts

@@ -10,9 +10,9 @@
 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 { ColsMap, InsertOf, RowOf, Schema } from "./schema.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";
+import { type ArrayView, type ChangePhase, FlatArrayView, type SingularArrayView, SingularView, type ViewChangeListener, type ViewTypes } from "./view.ts";
 
 /** One query's SSR snapshot, keyed by its `viewKey` ({@link stableKey} of the AST): the
  *  pre-projected first-paint `rows` plus the `cvMin` watermark they reflect (SSR-DESIGN.md §6.2).
@@ -36,9 +36,13 @@ export interface AssembledNode {
 }
 
 /** The write transaction handed to `store.write(tx => …)`. Rows are objects keyed by column;
- *  the Store positionalizes them (and stringifies json columns) before the backend sees them. */
+ *  the Store positionalizes them (and stringifies json columns) before the backend sees them.
+ *
+ *  `add` takes an {@link InsertOf} row — a nullable column may be omitted (it is filled with `null`,
+ *  design 206 §7). `remove`/`edit` take a full {@link RowOf} row: they identify an EXISTING row, so
+ *  every column (nullable ones as their actual `T | null` value) must be present. */
 export interface WriteTx<S extends ColsMap> {
-  add<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
+  add<N extends keyof S & string>(table: N, row: InsertOf<S[N]>): void;
   remove<N extends keyof S & string>(table: N, row: RowOf<S[N]>): void;
   edit<N extends keyof S & string>(table: N, oldRow: RowOf<S[N]>, newRow: RowOf<S[N]>): void;
 }
@@ -97,7 +101,9 @@ export class Store<S extends ColsMap> {
   private readonly syncLeases = new Map<QueryId, SyncLeaseState>();
   // SSR seeds (SSR-DESIGN.md §6), keyed by `viewKey`: a view materialized for one of these is
   // 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.
+  // SNAPSHOT lands — NOT its `hello` — so the seed bridges the `hello`→snapshot gap (the live
+  // data arrives on the snapshot, a round-trip after the hello) and later mounts of a now-live
+  // query don't re-seed stale SSR data.
   private readonly seeds = new Map<string, DehydratedQuery>();
   // 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
@@ -162,10 +168,18 @@ export class Store<S extends ColsMap> {
   }
 
   /** Materialize any fluent query object. Named queries subscribe remotely by `(name,args)`;
-   *  ad-hoc builder queries are local-only for local-first backends. */
-  materialize<Q extends Query<any, any, any>>(query: Q): ReturnType<Q["materialize"]> {
+   *  ad-hoc builder queries are local-only for local-first backends.
+   *
+   *  `opts.onChanges` binds a narrator to this view's DIFF stream ({@link ArrayView.onChanges}) — the
+   *  per-view seam that replaces filtering the store-global {@link subscribeChanges} by `qid`. It is
+   *  wired BEFORE the backend registers the query, so a synchronous backend's first `snapshot` (fired
+   *  inside `registerQuery`, before this returns) is delivered too. */
+  materialize<Q extends Query<any, any, any>>(
+    query: Q,
+    opts?: { onChanges?: ViewChangeListener },
+  ): ReturnType<Q["materialize"]> {
     const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
-    return this.registerMaterialized(query.ast(), remote).view as ReturnType<Q["materialize"]>;
+    return this.registerMaterialized(query.ast(), remote, opts?.onChanges).view as ReturnType<Q["materialize"]>;
   }
 
   /** True when the backend can retain a remote named query independently from the local
@@ -358,6 +372,7 @@ export class Store<S extends ColsMap> {
   private registerMaterialized(
     ast: Ast,
     remote?: RemoteQuery,
+    onChanges?: ViewChangeListener,
   ): { qid: QueryId; view: ArrayView<unknown> | SingularArrayView<unknown> } {
     const qid: QueryId = this.nextId++;
     this.asts.set(qid, ast);
@@ -380,6 +395,9 @@ export class Store<S extends ColsMap> {
       }
       baseDestroy();
     };
+    // Bind the narrator BEFORE `registerQuery` fires (a synchronous backend dispatches this query's
+    // first `hello`+`snapshot` inside it) so the initial snapshot reaches the change listener too.
+    if (onChanges) view.onChanges(onChanges);
     // If the backend rejects the registration (E3: a remote query naming a local-only table), roll
     // back the per-qid state we just created — otherwise the view + ast entry leak (the caller never
     // gets a handle to `destroy()` them, since the throw aborts before we return).
@@ -415,18 +433,27 @@ export class Store<S extends ColsMap> {
   private onEvent(qid: QueryId, ev: ChangeEvent): void {
     if (ev.type === "hello") {
       const ast = this.asts.get(qid);
-      // First live hello for this view ⇒ retire its SSR seed: the maintained tree now owns the
-      // result, so no future mount of the same query should flash the stale first-paint rows.
-      if (ast) this.seeds.delete(stableKey(ast));
       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.
+      // epoch) — so the materialized reference the caller holds survives a re-subscribe. The SSR
+      // seed is KEPT across the reset and retired on the first `snapshot` below (the live data
+      // lands then, not on the hello), so a seeded query bridges the gap instead of flashing empty.
       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.applyAndTrack(qid, ev.adds);
+      // The first live snapshot IS the query's hydration point (even an empty one — 0 rows is an
+      // authoritative answer): retire the SSR seed now, from the view (so `data` switches to the
+      // maintained tree) AND from the seeds map (so no later mount re-seeds a now-live query),
+      // BEFORE folding so the fold's notify already reflects the live tree with no empty gap.
+      const ast = this.asts.get(qid);
+      if (ast) this.seeds.delete(stableKey(ast));
+      this.views.get(qid)?.retireSeed();
+      this.applyAndTrack(qid, ev.adds, "snapshot");
     } else {
-      this.applyAndTrack(qid, ev.events);
+      // A `catchUp` batch is a query's initial hydration delivered as a delta (the optimistic
+      // backend hydrates through its reconcile cycle), so phase it as a `snapshot` — a narrator's
+      // "what CHANGED" default then ignores the initial rows instead of narrating each as an add.
+      this.applyAndTrack(qid, ev.events, ev.catchUp ? "snapshot" : "batch");
     }
     // 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
@@ -447,11 +474,11 @@ export class Store<S extends ColsMap> {
   /** 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 {
+  private applyAndTrack(qid: QueryId, events: FlatChange[], phase: ChangePhase): void {
     const view = this.views.get(qid);
     if (!view) return;
     const deferring = this.commitDepth > 0;
-    if (view.applyChanges(events, this.removedSubtreeWanted > 0, deferring) && deferring) {
+    if (view.applyChanges(events, this.removedSubtreeWanted > 0, deferring, phase) && deferring) {
       this.pendingFlush.add(view);
     }
   }

package/src/types.ts

@@ -75,7 +75,12 @@ export interface FlatChange {
 export type ChangeEvent =
   | { type: "hello"; schema: WireSchema; comparatorVersion: number }
   | { type: "snapshot"; adds: FlatChange[]; last: boolean }
-  | { type: "batch"; events: FlatChange[] };
+  // `catchUp` marks a batch that is really a query's INITIAL hydration delivered as a delta — the
+  // optimistic backend hydrates a fresh query through its reconcile cycle (a `serverBatchEnd`), so
+  // the whole first result set arrives as a `batch`, not a `snapshot`. The Store maps a catch-up
+  // batch to the `snapshot` change-phase so a narrator's "what CHANGED" default ignores the initial
+  // rows instead of narrating every one as a fresh add. A normal incremental batch omits it.
+  | { type: "batch"; events: FlatChange[]; catchUp?: boolean };
 
 export type Mutation =
   | { op: "add"; table: string; row: WireValue[] }
@@ -173,8 +178,13 @@ export interface Backend {
   /** Optional DIRECT-COMMIT path for LOCAL-only tables (`201-LOCAL-ONLY-TABLES-DESIGN.md` §6):
    *  applies the writes straight to the engine, OUTSIDE the optimistic pending stack (a local
    *  table is untracked, so it never rebases). The backend rejects any synced/tracked table (M2).
-   *  Backends with no local-table support (a plain remote sync backend) omit it. */
-  writeLocal?(mutations: Mutation[]): void;
+   *  Backends with no local-table support (a plain remote sync backend) omit it.
+   *
+   *  `onCommitted` (207 §5.1) runs after the engine commit is applied but BEFORE subscriber
+   *  delivery: a subscriber throwing during delivery re-raises out of this call, and a caller
+   *  that must stay coherent with the engine (the persistence tap) cannot tell that throw from
+   *  a pre-commit rejection — the callback can, because it fires exactly when the commit is in. */
+  writeLocal?(mutations: Mutation[], onCommitted?: () => void): void;
   onEvent(handler: (queryId: QueryId, event: ChangeEvent) => void): void;
   /** Optional: the backend pushes per-query {@link ResultType} changes here and the core routes
    *  each to the matching view (so `view.resultType` tracks it). Backends with no lifecycle (the

package/src/view.ts

@@ -18,6 +18,17 @@ export interface ViewTypes {
   rels: Record<number, ViewTypes>;
 }
 
+/** The phase of an {@link ArrayView.onChanges} delivery: the initial hydrate `snapshot` vs a later
+ *  incremental `batch` — the same distinction a narrator draws (`ChangeEvent` `snapshot`/`batch`). */
+export type ChangePhase = "snapshot" | "batch";
+
+/** A per-view change listener ({@link ArrayView.onChanges}): the net `FlatChange[]` this view folded,
+ *  the {@link ChangePhase} it arrived on, and the view's `WireSchema` (the position→name source for
+ *  `resolveChange`). This is the DIFF the data channel ({@link ArrayView.subscribe}) discards — the
+ *  seam a narrator drives off. The `schema` is passed (not closed over) because the first `snapshot`
+ *  fires synchronously inside `materialize`, before the caller holds the view handle. */
+export type ViewChangeListener = (changes: FlatChange[], phase: ChangePhase, schema: WireSchema) => void;
+
 /** The public ArrayView contract `materialize()` returns. */
 export interface ArrayView<R> {
   /** The current materialized result (reference-stable where data is unchanged). */
@@ -39,6 +50,14 @@ export interface ArrayView<R> {
   /** Subscribe; fires immediately with the current data, then after each applied batch (and after
    *  a {@link resultType} change — re-read `resultType` in the listener). */
   subscribe(listener: (data: readonly R[]) => void): () => void;
+  /** Subscribe to this view's folded CHANGE stream — the `FlatChange[]` it applies, NET of no-op
+   *  cycles (a rebase's balanced `remove`+`add` / edit round-trip cancels, so a correctly predicted
+   *  optimistic write delivers nothing here). Carries the diff {@link subscribe} throws away; the
+   *  per-view seam a narrator rides. Does NOT replay on subscribe — attach via
+   *  `store.materialize(query, { onChanges })` to catch a synchronous backend's first snapshot.
+   *  A view with any change listener also enriches its own `remove` ops with the evicted subtree
+   *  (per-view, no global opt-in). Returns a detach function. */
+  onChanges(listener: ViewChangeListener): () => void;
   /** Tear down + stop receiving updates. */
   destroy(): void;
 }
@@ -58,6 +77,10 @@ export interface SingularArrayView<R> {
   /** Subscribe; fires immediately with the current row, then after each applied batch (and after
    *  a {@link resultType} change). */
   subscribe(listener: (data: R | null) => void): () => void;
+  /** Subscribe to the view's folded CHANGE stream — see {@link ArrayView.onChanges}. The changes
+   *  are the same positional `FlatChange`s as the plural view (a `.one()` is just the list capped to
+   *  one), so a narrator resolves them identically. */
+  onChanges(listener: ViewChangeListener): () => void;
   /** Tear down + stop receiving updates. */
   destroy(): void;
 }
@@ -91,6 +114,10 @@ export class SingularView<R> implements SingularArrayView<R> {
     return this.inner.subscribe((d) => listener(d[0] ?? null));
   }
 
+  onChanges(listener: ViewChangeListener): () => void {
+    return this.inner.onChanges(listener);
+  }
+
   destroy(): void {
     this.inner.destroy();
   }
@@ -161,8 +188,159 @@ function toWireNode(node: Node, schema: WireSchema): WireNode {
   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]));
+/** Elementwise equality over positional bare-cell rows — THE row comparator for every JS-side
+ *  diff (views, aggregate heads, the persistence mirror), exported so no caller grows a drifted
+ *  private copy. Per cell: `===` keeps `-0 === 0` (the engine's key semantics treat them equal);
+ *  the `Object.is` arm makes a NaN cell equal itself (under `!==` alone, a NaN-bearing row never
+ *  matches any copy of itself, so every diff re-emits it as a spurious edit forever). */
+export function rowsEqual(a: WireValue[], b: WireValue[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i] && !Object.is(a[i], b[i])) return false;
+  }
+  return true;
+}
+
+/** JSON.stringify for keying a row, except the numbers JSON folds together — NaN/±Infinity (→ null)
+ *  and -0 (→ 0) — get a sentinel encoding, so two rows that `rowsEqual` (Object.is) distinguishes
+ *  never share a net key (a `remove [1, Infinity]` must not cancel an `add [1, null]`). */
+function keyRow(row: WireValue[]): string {
+  return JSON.stringify(row, (_k, v: unknown) =>
+    typeof v === "number" && (!Number.isFinite(v) || Object.is(v, -0)) ? [" num", Object.is(v, -0) ? "-0" : String(v)] : v,
+  );
+}
+
+/** The key a subtractive net matches an op on: the path (parent locators, one hop per level) plus the
+ *  row bytes. Two ops with the same key touch the same row at the same tree position. */
+function opRowKey(path: FlatChange["path"], row: WireValue[]): string {
+  let k = "";
+  for (const seg of path) k += seg.rel + ":" + keyRow(seg.parentRow) + "/";
+  return k + "|" + keyRow(row);
+}
+
+/** Walk `path` down `schema` to the changed level's `WireSchema` — `null` when a hop crosses a
+ *  gating (join-only) slot; such ops never fold, so they never reach the net. */
+function levelSchemaAt(schema: WireSchema, path: FlatChange["path"]): WireSchema | null {
+  let level: WireSchema = schema;
+  for (const seg of path) {
+    const child = level.relationships[seg.rel]?.child;
+    if (!child) return null;
+    level = child;
+  }
+  return level;
+}
+
+/** Deep structural equality of two canonical (maintained-order) subtrees: rows via Object.is,
+ *  per-slot children pairwise, rc included — a dup-path child only equals an equally-duplicated one. */
+function nodesEqual(a: Node, b: Node): boolean {
+  if (a.rc !== b.rc || !rowsEqual(a.row, b.row) || a.rels.length !== b.rels.length) return false;
+  for (let s = 0; s < a.rels.length; s++) {
+    const ra = a.rels[s];
+    const rb = b.rels[s];
+    if (ra.length !== rb.length) return false;
+    for (let i = 0; i < ra.length; i++) if (!nodesEqual(ra[i], rb[i])) return false;
+  }
+  return true;
+}
+
+/** Cancel no-op cycles in a folded batch SUBTRACTIVELY — the safe half of the removed engine
+ *  coalescer (OPTIMISTIC-WRITES-DESIGN §3, and `wasm/db.rs` "Step 2 of the removal"). A rebase
+ *  re-invokes a still-pending prediction, emitting a balanced `remove R`+`add R` (or `edit b→a`+
+ *  `edit a→b`) that nets to nothing; so a correctly predicted optimistic write delivers ZERO changes
+ *  to a narrator, and only genuine (mispredicted / other-client) changes survive. We ONLY drop exact
+ *  inverse pairs — byte-identical row at the same path AND a structurally identical subtree: a row
+ *  that leaves and re-enters within one batch carrying a CHANGED child set is NOT an inverse (the
+ *  child never got its own event while the row was out — the re-add is its only carrier), so that
+ *  pair survives. Survivors pass through UNMODIFIED: we never rewrite a locator, reorder, or
+ *  reconstruct a gated subtree (the reconstructive netting that shipped four correctness bugs and
+ *  was pulled from the engine). Because this feeds prose, not a locate-by-value receiver, even an
+ *  imperfect net is at worst a spurious line, never a corrupt view — and every conservative bail
+ *  here (unknown subtree, gated level) errs on the spurious-line side, never the missed-line side.
+ *  Order-preserving for survivors; returns the input array unchanged when nothing cancels. */
+function netChanges(changes: FlatChange[], schema: WireSchema): FlatChange[] {
+  if (changes.length < 2) return changes;
+  const alive = new Array<boolean>(changes.length).fill(true);
+  const removes = new Map<string, number[]>(); // key → indices of not-yet-cancelled removes
+  const adds = new Map<string, number[]>(); // key → indices of not-yet-cancelled adds
+  const edits = new Map<string, number[]>(); // pathKey+old+new → indices of not-yet-cancelled edits
+  // The subtree an add/remove carries, canonicalized to maintained (sorted, dup-folded) form so a
+  // shipped-order `add` node and a maintained-order enriched `remove` node compare structurally.
+  // Built ONLY when two ops collide on the row key — the common no-collision delivery never builds
+  // one — and memoized per op index. `null` ⇒ subtree unknown (a gated level, or a remove that was
+  // not enriched); conservative: an unknown subtree never cancels, so we err toward a spurious line.
+  const subCache = new Map<number, Node | null>();
+  const subtreeOf = (i: number): Node | null => {
+    let s = subCache.get(i);
+    if (s !== undefined) return s;
+    const { path, op } = changes[i];
+    const level = levelSchemaAt(schema, path);
+    // A remove reaching the net actually evicted its node (only applied ops are delivered) and so was
+    // enriched with its subtree on `op.node`; an add always carries `op.node`. Either is canonicalized.
+    const wnode = op.tag === "add" ? op.node : op.tag === "remove" ? op.node : undefined;
+    s = level && wnode ? buildNode(wnode, level) : null;
+    subCache.set(i, s);
+    return s;
+  };
+  // Take the LATEST pending opposite at the same key whose subtree also matches (LIFO, like the
+  // plain `take` below, so nested cycles unwind innermost-first).
+  const takeInverse = (m: Map<string, number[]>, k: string, i: number): number | undefined => {
+    const arr = m.get(k);
+    if (!arr || arr.length === 0) return undefined;
+    const mine = subtreeOf(i);
+    if (mine === null) return undefined;
+    for (let x = arr.length - 1; x >= 0; x--) {
+      const theirs = subtreeOf(arr[x]);
+      if (theirs !== null && nodesEqual(mine, theirs)) {
+        const j = arr[x];
+        arr.splice(x, 1);
+        return j;
+      }
+    }
+    return undefined;
+  };
+  const take = (m: Map<string, number[]>, k: string): number | undefined => {
+    const arr = m.get(k);
+    return arr && arr.length ? arr.pop() : undefined;
+  };
+  const put = (m: Map<string, number[]>, k: string, i: number): void => {
+    const arr = m.get(k);
+    if (arr) arr.push(i);
+    else m.set(k, [i]);
+  };
+  let cancelled = false;
+  for (let i = 0; i < changes.length; i++) {
+    const { path, op } = changes[i];
+    if (op.tag === "remove") {
+      const k = opRowKey(path, op.row);
+      const j = takeInverse(adds, k, i);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(removes, k, i);
+    } else if (op.tag === "add") {
+      const k = opRowKey(path, op.node.row);
+      const j = takeInverse(removes, k, i);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(adds, k, i);
+    } else {
+      // edit: cancel against a prior INVERSE edit (a→b then b→a) at the same path. The old/new
+      // bytes are part of the map key, so the inverse lookup is O(1) instead of a rescan.
+      const pk = opRowKey(path, []);
+      const oldS = keyRow(op.old);
+      const newS = keyRow(op.new);
+      const j = take(edits, pk + "" + newS + "" + oldS);
+      if (j !== undefined) {
+        alive[i] = alive[j] = false;
+        cancelled = true;
+      } else put(edits, pk + "" + oldS + "" + newS, i);
+    }
+  }
+  if (!cancelled) return changes;
+  const out: FlatChange[] = [];
+  for (let i = 0; i < changes.length; i++) if (alive[i]) out.push(changes[i]);
+  return out;
 }
 
 const EMPTY: readonly never[] = Object.freeze([]);
@@ -177,8 +355,10 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   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` —
-  // so the maintained tree takes over and the live snapshot reconciles. `null` ⇒ no seed.
+  // `data` until the maintained tree's first live SNAPSHOT lands (the Store calls `retireSeed` then).
+  // It deliberately SURVIVES `reset` (the `hello`), so a seeded view bridges the `hello`→snapshot gap
+  // instead of flashing empty in between (a `hello` sets the schema but its data arrives one round-trip
+  // later, on the snapshot). `null` ⇒ no seed.
   private seeded: readonly R[] | null = null;
   private top: Node[] = [];
   private dirty = true;
@@ -188,6 +368,16 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   // (the optimistic backend: `unknown` until hydrated, etc.).
   private rt: ResultType = "complete";
   private readonly listeners = new Set<(data: readonly R[]) => void>();
+  // The per-view CHANGE stream ({@link onChanges}) — the diff a narrator rides, distinct from the
+  // data channel above. Empty until a narrator attaches: an idle view pays one `.size` check per fold.
+  private readonly changeListeners = new Set<ViewChangeListener>();
+  // Changes folded but not yet delivered to `changeListeners` — buffered while the Store defers a
+  // commit (mirrors the deferred `notify`), then netted + flushed at the commit boundary. Segmented
+  // BY PHASE (not one last-writer-wins phase scalar): a bracket that folds both a `snapshot` and a
+  // `batch` into this view keeps them apart, each netted and delivered under its OWN phase, so a
+  // snapshot is never mislabeled `batch` (nor a batch dropped as `snapshot`). Consecutive same-phase
+  // folds coalesce into one segment so a whole commit's batch nets together.
+  private pendingSegments: { phase: ChangePhase; changes: FlatChange[] }[] = [];
 
   constructor(schema?: WireSchema, types?: ViewTypes, qid: QueryId = 0) {
     this._schema = schema ?? null;
@@ -219,25 +409,40 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
   /** (Re)bind to a schema and clear the tree IN PLACE. The first `hello` (pending → ready)
    *  and a re-hydrate (gap → new epoch — FLAT-CHANGES-DESIGN.md §2.3) both go through here, so
    *  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. */
+   *  the snapshot that follows (`applyChanges`) does, avoiding an empty-then-filled flicker.
+   *  KEEPS any SSR `seeded` rows: they are retired only when the first live snapshot lands
+   *  ({@link retireSeed}, driven by the Store), so `data` shows the seed — not an empty tree —
+   *  across the whole `hello`→first-`snapshot` gap. */
   reset(schema: WireSchema, types?: ViewTypes): void {
     this._schema = schema;
     this.types = types;
-    this.seeded = null; // live data takes over; the seed was first-paint only
     this.top = [];
     this.cached = null;
     this.dirty = true;
+    // Drop any changes buffered under the OLD epoch: a re-hydrate cuts a new schema, and
+    // `deliverChanges` resolves against the current `_schema`, so pre-epoch changes must never
+    // survive to be delivered against the new one (mirrors `destroy`). The snapshot that follows
+    // this reset re-establishes the buffer for the new epoch.
+    this.pendingSegments = [];
   }
 
   /** Install a pre-projected SSR first-paint snapshot (SSR-DESIGN.md §6). The rows are already
    *  in result shape (json columns parsed, relationships nested), so a view with no live backend
    *  (the server one-shot Store) reads them directly, and a browser view shows them until its
-   *  first live `hello` (`reset`) swaps in the maintained tree. Does NOT notify — it is set at
-   *  materialize time, before any subscriber, and the live snapshot that follows notifies. */
+   *  first live snapshot lands ({@link retireSeed}). Does NOT notify — it is set at materialize
+   *  time, before any subscriber, and the live snapshot that follows notifies. */
   seed(rows: readonly R[]): void {
     this.seeded = rows;
   }
 
+  /** Retire the SSR first-paint seed — the Store calls this as it folds the maintained tree's first
+   *  live snapshot, so `data` switches from the seed to the live tree with no empty gap between them
+   *  (the seed deliberately survived the earlier `reset`/`hello`). Idempotent; a no-op once retired.
+   *  Does NOT notify — the snapshot fold it accompanies does. */
+  retireSeed(): void {
+    this.seeded = null;
+  }
+
   /** 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).
@@ -245,21 +450,61 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  `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).
+   *  only on a real eviction (an rc-decrement that keeps the row leaves `node` absent). A view with
+   *  an attached {@link onChanges} listener ALSO enriches (per-view, no global opt-in), so a
+   *  narrator can resolve a removed row's subs whether or not the store-global counter is set.
    *
    *  `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 {
+   *  `phase` tags the {@link onChanges} delivery (`snapshot` for the hydrate, `batch` otherwise); it
+   *  does not affect the fold. Returns whether the batch changed the view (so a deferring caller
+   *  knows it must be flushed). */
+  applyChanges(events: FlatChange[], enrichRemoves = false, deferNotify = false, phase: ChangePhase = "batch"): 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, enrichRemoves) || changed;
-    if (!changed) return false;
+    // Enrich this view's removes when a narrator is attached (see the `enrichRemoves` doc above) —
+    // the per-view twin of the store's global `removedSubtree` counter.
+    const enrich = enrichRemoves || this.changeListeners.size > 0;
+    // Deliver ONLY the ops that actually changed the tree: a duplicate-path add (rc bump), an
+    // rc-decrement remove that left the row, a no-op edit, and a gated op all return false — none is
+    // a real change, so none should reach a narrator. (Enrichment already attached the subtree to a
+    // real remove during the fold, so a surviving remove carries its `node`.)
+    const applied: FlatChange[] = [];
+    for (const e of events) {
+      if (this.applyAt(this.top, this._schema, e.path, e.op, 0, enrich)) applied.push(e);
+    }
+    if (applied.length === 0) return false;
     this.dirty = true;
-    if (!deferNotify) this.notify();
+    if (deferNotify) {
+      if (this.changeListeners.size > 0) {
+        const segs = this.pendingSegments;
+        const last = segs.length > 0 ? segs[segs.length - 1] : undefined;
+        if (last && last.phase === phase) for (const e of applied) last.changes.push(e);
+        else segs.push({ phase, changes: applied.slice() });
+      }
+      return true;
+    }
+    // Inline (standalone / no commit bracket): notify data subscribers, then deliver the change
+    // stream — each isolated, first error re-raised once both have run (mirroring the Store's
+    // per-view flush isolation) so a throwing narration listener never starves the data channel,
+    // aborts the fold's return, or propagates raw into the engine's push path.
+    let firstError: unknown;
+    let hasError = false;
+    const note = (e: unknown): void => {
+      if (!hasError) {
+        hasError = true;
+        firstError = e;
+      }
+    };
+    try {
+      this.notify();
+    } catch (e) {
+      note(e);
+    }
+    this.deliverChanges(applied, phase, note);
+    if (hasError) throw firstError;
     return true;
   }
 
@@ -268,11 +513,35 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
    *  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();
+    // Take the buffer BEFORE delivery so a throwing listener can never leave changes buffered to be
+    // re-delivered — merged and cross-phase-netted — into a LATER commit's flush. Notify and every
+    // segment's delivery are isolated; the first error is re-raised after all have run, so one bad
+    // subscriber starves neither the data channel nor a sibling segment (matching `flushCommit`).
+    const segs = this.pendingSegments;
+    this.pendingSegments = [];
+    let firstError: unknown;
+    let hasError = false;
+    const note = (e: unknown): void => {
+      if (!hasError) {
+        hasError = true;
+        firstError = e;
+      }
+    };
+    try {
+      this.notify();
+    } catch (e) {
+      note(e);
+    }
+    for (const seg of segs) this.deliverChanges(seg.changes, seg.phase, note);
+    if (hasError) throw firstError;
   }
 
   get data(): readonly R[] {
-    if (this._schema === null) return this.seeded ?? (EMPTY as readonly R[]);
+    // A live SSR seed owns `data` until it is retired on the first live snapshot ({@link retireSeed}) —
+    // this spans pending (no schema) AND the post-`hello`, pre-snapshot window (schema set, tree still
+    // empty), so a seeded query never flashes empty during the handoff. `null` seed ⇒ normal behavior.
+    if (this.seeded !== null) return this.seeded;
+    if (this._schema === null) return 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.dirty = false;
@@ -287,8 +556,38 @@ export class FlatArrayView<R = unknown> implements ArrayView<R> {
     };
   }
 
+  onChanges(listener: ViewChangeListener): () => void {
+    this.changeListeners.add(listener);
+    return () => {
+      this.changeListeners.delete(listener);
+    };
+  }
+
+  /** Net the folded batch and hand the survivors to the change listeners, AFTER the data `notify`
+   *  (the order `Store.subscribeChanges` consumers already observe). A batch that nets to nothing —
+   *  a correctly predicted rebase — makes no call, so a narrator sees only real change. Each listener
+   *  is isolated: a throwing one reports to `note` (the caller re-raises the first) and the rest still
+   *  run, so one bad narration template never starves a sibling listener nor corrupts the view. */
+  private deliverChanges(events: FlatChange[], phase: ChangePhase, note: (e: unknown) => void): void {
+    if (this.changeListeners.size === 0) return;
+    // `_schema` is non-null here: `applyChanges` early-returns while pending, and `flush` runs only
+    // after a fold — so a listener always has the position→name source in hand.
+    const schema = this._schema as WireSchema;
+    const net = netChanges(events, schema);
+    if (net.length === 0) return;
+    for (const l of this.changeListeners) {
+      try {
+        l(net, phase, schema);
+      } catch (e) {
+        note(e);
+      }
+    }
+  }
+
   destroy(): void {
     this.listeners.clear();
+    this.changeListeners.clear();
+    this.pendingSegments = [];
     this.top = [];
   }