@rindle/client 0.1.6 → 0.3.1

package/src/resolve.ts

@@ -0,0 +1,136 @@
+// Positional → named change resolution: the inverse of the wire encoder.
+//
+// A backend ships per-query `FlatChange`s (types.ts): `{ path: PathSeg[], op: add|remove|edit }`,
+// where `path` indexes into the view's relationship tree and rows are POSITIONAL cells. The view
+// (view.ts) folds those into the materialized tree positionally; this module instead LIFTS one
+// change out of positional/indexed wire form into NAMED rows, resolving it against the query's OWN
+// `WireSchema` (the per-subscription view schema the engine ships once on its `hello` frame): per
+// level the column NAMES in wire order, and the relationships in SLOT order (a gating exists/notExists
+// slot is `child: null`; a `countAs` slot carries a `project` annotation). So `path[i].rel` indexes
+// `schema.relationships[i]` directly, and a positional `row` names against `schema.columns` — both
+// authoritative, straight from the engine.
+//
+// Resolving against the hello schema (rather than re-deriving positions from the query `Ast`) means
+// we assume NOTHING about slot ordering and NOTHING about column order: it stays correct under
+// `.select()` projections and any future slot layout. The result — named rows + an aggregate's exact
+// new value — is what a higher layer (e.g. @rindle/narrator) renders into prose, but it is broadly
+// useful to anything consuming a `FlatChange` (logging, devtools, change-driven overlays).
+//
+// NOTE on aggregates (`countAs`): the slot's `project.col` names the EXACT count cell in the child
+// row, so a count change reports the exact new value (and previous, on an edit) — not a best-effort
+// guess. A remove of the aggregate row means the count fell to its identity (`project.identity`).
+
+import type { FlatChange, PathSeg, WireNode, WireRel, WireSchema, WireValue } from "./types.ts";
+
+/** A row named against its level's wire columns. */
+export type NamedRow = Record<string, WireValue>;
+
+/** One resolved change: a `FlatChange` lifted out of positional/indexed wire form into names,
+ *  using the query's `WireSchema` (from `hello`) as the sole position→name source. */
+export interface ResolvedChange {
+  /** Relationship-alias chain from the query root to the changed level (`[]` ⇒ the root rows). */
+  aliasChain: string[];
+  /** The alias of the changed level (`""` ⇒ root), i.e. the last of `aliasChain`. */
+  alias: string;
+  op: "add" | "remove" | "edit";
+  /** The affected row, named. For `edit` this is the NEW row; see `old` for the prior one. */
+  row: NamedRow;
+  /** The prior row, named (present only for `edit`). */
+  old?: NamedRow;
+  /** The PARENT row (named), for a nested/aggregate change — e.g. the `ticket_type` whose `sold`
+   *  count moved. Taken from the path's last `parentRow`; absent for a root-level change. */
+  parent?: NamedRow;
+  /** Set when the changed level is a `countAs`/aggregate slot. The value is EXACT — read from the
+   *  slot's projected count column (`WireRel.project.col`). */
+  aggregate?: { alias: string; value: WireValue; previous?: WireValue };
+  /** The raw node whose children a consumer can dig a named sub-row out of (via {@link subRow}). On
+   *  an `add` the engine always ships it; on a `remove` it is present only when the consumer opted
+   *  into the removed subtree (see the `op` mapping below). */
+  node?: WireNode;
+  /** The changed level's `WireSchema` — used by {@link subRow} to resolve a named sub of `node`. */
+  levelSchema: WireSchema;
+}
+
+/** Name positional `cells` against a level's wire `columns` (insertion = wire order). */
+function nameRow(cells: WireValue[] | undefined, cols: string[]): NamedRow {
+  const out: NamedRow = {};
+  if (!cells) return out;
+  for (let i = 0; i < cols.length; i++) out[cols[i]] = cells[i] ?? null;
+  return out;
+}
+
+/** Walk a `path` from the root `WireSchema` down the relationship tree. Returns the reached level,
+ *  the alias chain, and the LAST relationship traversed (its `project` marks an aggregate slot).
+ *  `null` if a hop addresses an unknown or gating (`child: null`) slot. */
+function descend(
+  root: WireSchema,
+  path: PathSeg[],
+): { level: WireSchema; lastRel: WireRel | null; aliasChain: string[] } | null {
+  let level = root;
+  let lastRel: WireRel | null = null;
+  const aliasChain: string[] = [];
+  for (const seg of path) {
+    const rel = level.relationships[seg.rel];
+    if (!rel || !rel.child) return null; // unknown / gating slot — not a materialized level
+    lastRel = rel;
+    level = rel.child;
+    aliasChain.push(rel.name);
+  }
+  return { level, lastRel, aliasChain };
+}
+
+/** Lift one `FlatChange` into a {@link ResolvedChange} against the query's `WireSchema`, or `null`
+ *  if its path doesn't resolve to a materialized level. */
+export function resolveChange(schema: WireSchema, change: FlatChange): ResolvedChange | null {
+  const here = descend(schema, change.path);
+  if (!here) return null;
+  const { level, lastRel, aliasChain } = here;
+  const cols = level.columns;
+  const alias = aliasChain.length ? aliasChain[aliasChain.length - 1] : "";
+  const base: Omit<ResolvedChange, "op" | "row"> = { aliasChain, alias, levelSchema: level };
+  // The parent row (for a nested/aggregate change) sits in the last path seg, named against the
+  // level one hop up.
+  if (change.path.length) {
+    const up = descend(schema, change.path.slice(0, -1));
+    const parentCells = change.path[change.path.length - 1].parentRow;
+    if (up) base.parent = nameRow(parentCells, up.level.columns);
+  }
+
+  // A `countAs` slot carries a scalar `project` annotation on the relationship we descended through:
+  // `project.col` is the exact count cell, `project.identity` the empty value (0 for count).
+  const proj = lastRel?.project ?? null;
+  const agg = (cells: WireValue[] | undefined): WireValue => (proj && cells ? (cells[proj.col] ?? null) : null);
+
+  const op = change.op;
+  if (op.tag === "add") {
+    const r: ResolvedChange = { ...base, op: "add", row: nameRow(op.node.row, cols), node: op.node };
+    if (proj) r.aggregate = { alias, value: agg(op.node.row) };
+    return r;
+  }
+  if (op.tag === "remove") {
+    const r: ResolvedChange = { ...base, op: "remove", row: nameRow(op.row, cols) };
+    // The removed subtree rides along only when the consumer opted into it (the ArrayView attaches
+    // it client-side — `Store.subscribeChanges(_, { removedSubtree: true })`). When present, `subRow`
+    // resolves a removed row's nested subs exactly as on an `add`; absent, a remove is row-only.
+    if (op.node) r.node = op.node;
+    if (proj) r.aggregate = { alias, value: proj.identity };
+    return r;
+  }
+  // edit
+  const r: ResolvedChange = { ...base, op: "edit", row: nameRow(op.new, cols), old: nameRow(op.old, cols) };
+  if (proj) r.aggregate = { alias, value: agg(op.new), previous: agg(op.old) };
+  return r;
+}
+
+/** Read a named sub-row off a change's `node` by relationship alias (e.g. the `guest` under an
+ *  `rsvp`) — the `add` node, or a `remove`'s subtree when the consumer opted into it. The alias →
+ *  wire slot mapping comes from the changed level's `WireSchema`. `null` when no node rode along. */
+export function subRow(rc: ResolvedChange, alias: string): NamedRow | null {
+  if (!rc.node) return null;
+  const rel = rc.levelSchema.relationships.find((r) => r.name === alias);
+  if (!rel || !rel.child) return null;
+  const slot = rc.node.rels.find((s) => s.rel === rel.slot);
+  const child = slot?.children[0];
+  if (!child) return null;
+  return nameRow(child.row, rel.child.columns);
+}

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
@@ -51,6 +51,19 @@ export interface CachedQueryView<Q extends Query<any, any, any>> {
   destroy(): void;
 }
 
+export interface SyncQueryLease {
+  readonly resultType: ResultType;
+  subscribe(listener: () => void): () => void;
+  release(): void;
+}
+
+interface SyncLeaseState {
+  resultType: ResultType;
+  listeners: Set<() => void>;
+  released: boolean;
+  seedKey?: string;
+}
+
 /** One live materialized view's read-only summary for a devtools pane (DEBUG-TOOLS-BROWSER-DESIGN
  *  §4.2 — "surface, not instrument"). All fields are already held by the {@link Store}; this is the
  *  single read-only accessor over the otherwise-private `views`/`asts` maps. */
@@ -72,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>;
@@ -93,25 +94,66 @@ export class Store<S extends ColsMap> {
   private nextId = 1;
   private readonly views = new Map<QueryId, FlatArrayView>();
   private readonly asts = new Map<QueryId, Ast>();
+  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.
   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).
     this.backend.onResultType?.((qid, rt) => {
       this.views.get(qid)?.setResultType(rt);
-      if (this.devObservers) for (const o of this.devObservers) o.onResultType?.(qid, rt);
+      const sync = this.syncLeases.get(qid);
+      if (sync && sync.resultType !== rt) {
+        sync.resultType = rt;
+        if (rt === "complete" && sync.seedKey !== undefined) this.seeds.delete(sync.seedKey);
+        for (const listener of sync.listeners) listener();
+      }
+      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
@@ -153,6 +195,49 @@ export class Store<S extends ColsMap> {
     };
   }
 
+  /** Retain a named remote query purely for normalized/local-first coverage. This does not
+   *  register or materialize the query AST locally, so React can keep server sync coverage alive
+   *  without subscribing to the broad coverage result tree. */
+  retainSyncQuery<Q extends Query<any, any, any>>(query: Q): SyncQueryLease {
+    if (!this.canRetainRemoteQueries()) {
+      throw new Error(
+        "store.retainSyncQuery: this backend cannot retain a remote query without a local view.",
+      );
+    }
+    const ast = query.ast();
+    const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
+    if (!remote) {
+      throw new Error("store.retainSyncQuery: sync-only coverage requires a named query.");
+    }
+    const qid = this.nextId++;
+    const state: SyncLeaseState = { resultType: "unknown", listeners: new Set(), released: false, seedKey: stableKey(ast) };
+    this.syncLeases.set(qid, state);
+    try {
+      this.backend.retainRemoteQuery?.(qid, remote, qid, ast);
+    } catch (e) {
+      this.syncLeases.delete(qid);
+      throw e;
+    }
+    return {
+      get resultType() {
+        return state.resultType;
+      },
+      subscribe: (listener: () => void) => {
+        state.listeners.add(listener);
+        listener();
+        return () => {
+          state.listeners.delete(listener);
+        };
+      },
+      release: () => {
+        if (state.released) return;
+        state.released = true;
+        this.syncLeases.delete(qid);
+        this.backend.releaseRemoteQuery?.(qid);
+      },
+    };
+  }
+
   /** Apply a batch of mutations (object rows → positional). Resolves when the backend has
    *  accepted them (local: applied; remote: sent). The resulting view updates flow back via
    *  the backend's event stream. */
@@ -234,6 +319,12 @@ export class Store<S extends ColsMap> {
     return this.seeds.get(viewKey);
   }
 
+  primaryKeyFor(table: string): readonly string[] {
+    const meta = this.schema.tables[table];
+    if (!meta) throw new Error(`unknown table: ${table}`);
+    return meta.primaryKey;
+  }
+
   /** Convert assembled (nested-by-name) rows (SSR-DESIGN.md §3.3) into the view's projected result
    *  shape: spread `cols` (parsing json columns), recurse into each relationship by its alias
    *  (plural → array, `.one()` → object/null, `countAs` → bare scalar). */
@@ -272,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
@@ -310,7 +403,7 @@ export class Store<S extends ColsMap> {
     const remote = typeof query.name === "string" ? { name: query.name, args: query.args } : undefined;
     if (!remote || !this.canRetainRemoteQueries()) return () => {};
     const qid = this.nextId++;
-    this.backend.retainRemoteQuery?.(qid, remote, localQueryId);
+    this.backend.retainRemoteQuery?.(qid, remote, localQueryId, query.ast());
     let released = false;
     return () => {
       if (released) return;
@@ -328,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

@@ -3,6 +3,8 @@
 // Cells cross the boundary BARE (the host has a typed schema, so per-column types are
 // known here, not per-cell). JSON columns cross as their raw JSON string.
 
+import type { Ast } from "./ast.ts";
+
 /** A bare wire cell. (JSON columns arrive as their raw JSON string.) */
 export type WireValue = number | string | boolean | null;
 
@@ -50,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 {
@@ -111,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;
@@ -143,8 +164,9 @@ export interface Backend {
   unregisterQuery(queryId: QueryId): void;
   /** Optional split path for local-first backends: retain/release a named remote footprint
    *  without creating another local materialized view. `localQueryId`, when provided, names
-   *  the local AST view this remote footprint feeds. */
-  retainRemoteQuery?(queryId: QueryId, remote: RemoteQuery, localQueryId?: QueryId): void;
+   *  the local AST view this remote footprint feeds. `ast`, when provided, gives the backend
+   *  the local schema context for sync-only retains that still need aggregate/table setup. */
+  retainRemoteQuery?(queryId: QueryId, remote: RemoteQuery, localQueryId?: QueryId, ast?: Ast): void;
   releaseRemoteQuery?(queryId: QueryId): void;
   /** Local: applies now (changes flow back on the stream). Remote: sends to the server. */
   mutate(mutations: Mutation[]): Promise<void>;
@@ -158,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;
 }
 
 /**