@rindle/narrator 0.4.3 → 0.4.4

package/README.md

@@ -1,41 +1,16 @@
 # @rindle/narrator
 
-Turn a Rindle query's flat-change stream into agent-ready prose.
+Turn a Rindle view's netted change stream into agent-ready prose.
 
-A standing query (`defineQuery`) is a live, incrementally-maintained subscription. As base-table
-writes flow in, the engine emits per-query `FlatChange` diffs (positional, indexed into the view's
-relationship tree). `@rindle/narrator` lifts those into named rows and renders them through small,
-per-query templates into **salience-tagged semantic events** — the "operational context" an agent
-reads — and groups one commit's effects under the **mutator that caused them**.
-
-```
-base writes ──▶ engine maintains the query ──▶ FlatChange[] diffs
-                                                     │
-            resolveChange (@rindle/client)  ◀────────┘   positional → named rows
-                                                     │
-            per-query templates (your registry)            named rows → prose
-                                                     │
-            SemanticEvent[]  ──▶  digest()                 salience-ranked prompt block
-```
-
-## Pipeline
-
-1. **Resolve** — `resolveChange(schema, change)` (in `@rindle/client`) is the pure inverse of the
-   wire encoder: it names positional cells against the query's `WireSchema` (shipped on its `hello`
-   frame, also readable as `view.schema`), surfaces the parent row and the exact aggregate value for
-   a `countAs` slot, and lets you read a nested sub-row off an `add` node.
-2. **Render** — `createNarrator(registry)` matches each resolved change to a template keyed by
-   `defineQuery` name + op (+ count alias) and emits a `SemanticEvent` (with `salience`:
-   `alert` / `info` / `ambient`). `digest(events)` folds a batch into a salience-ranked block.
-3. **Attribute** — `narrateCommit(...)` / `createCausalTap(...)` group a commit's per-query batches
-   under a `Cause` (the named mutator + args), rendering one append-ready block per commit.
-
-## Usage
+<<<<<<< HEAD
+Full docs — the agent loop this package powers (named diffs in, salience-ranked
+digests out, observe→act): **[rindle.sh/docs/agents](https://rindle.sh/docs/agents)** ·
+markdown mirror: [`agents.md`](https://rindle.sh/docs/agents.md) · for agents:
+[llms.txt](https://rindle.sh/llms.txt)
 
 ```ts
-import { createNarrator, attachCausalTap, type NarratorRegistry, type QueryBinding } from "@rindle/narrator";
+import { createNarrator, type NarratorRegistry } from "@rindle/narrator";
 
-// The only hand-written part: per-query templates. The names do the work, so this stays small.
 const NARRATORS: NarratorRegistry = {
   unseatedGuests: {
     salience: "alert",
@@ -47,56 +22,15 @@ const NARRATORS: NarratorRegistry = {
 };
 
 const narrator = createNarrator(NARRATORS);
-
-// Single query: the materialized view is self-describing — `qid` + `schema` + `data`.
-const view = store.materialize(unseatedGuestsQuery({ eventId }));
-const off = store.subscribeChanges((qid, ev) => {
-  if (qid !== view.qid || !view.schema) return;
-  const changes = ev.type === "snapshot" ? ev.adds : ev.type === "batch" ? ev.events : [];
-  console.log(narrator.digest(narrator.narrate("unseatedGuests", view.schema, changes, ev.type === "snapshot" ? "snapshot" : "batch", { subject: "the Smith wedding" })));
+store.materialize(unseatedGuestsQuery({ eventId }), {
+  onChanges: (changes, phase, schema) => {
+    const block = narrator.digest(narrator.narrate("unseatedGuests", schema, changes, phase, ctx));
+    if (block) agentContext.append(block);
+  },
 });
-
-// Causal: bind each live query, wrap a mutator call.
-const bindings = new Map<number, QueryBinding>([[view.qid, { query: "unseatedGuests", schema: view.schema!, ctx: { subject: "the Smith wedding" } }]]);
-const { tap } = attachCausalTap(store, narrator, bindings, { causes: { seatGuest: () => "Seated a guest" } });
-tap.begin({ mutator: "seatGuest", args });
-await store.write((tx) => /* … */ undefined);
-const block = tap.end();           // one CausalDigest for the whole commit
 ```
 
-## Why subscribe to the store, not the view?
-
-Narration drives off `store.subscribeChanges` — the raw, qid-tagged `ChangeEvent` stream — rather
-than `view.subscribe`. That looks backwards (the view is right there, self-describing), but the view
-is the wrong seam for three concrete reasons:
-
-1. **The view's `subscribe` carries the folded snapshot, not the diff.** `view.subscribe(d => …)`
-   fires with `data: readonly R[]` — the projected tree *after* the `FlatChange[]` has been applied
-   and discarded. The narrator's whole job is the diff (`resolveChange` → named rows → per-op
-   templates); the view hands you the one thing it throws away. Driving narration off the view would
-   mean adding a second, diff-bearing channel to it.
-2. **Synchronous backends emit the first frame before the view handle exists.** The in-process
-   wasm/replica backend dispatches a query's first `hello`+`snapshot` *synchronously inside*
-   `registerQuery`, i.e. before `materialize()` returns the view to its caller. `subscribeChanges` is
-   attached up front (before `materialize`) precisely so it catches those frames; a per-view
-   subscription has no handle to subscribe to yet when they fire, so it misses the initial snapshot.
-3. **A commit fans out across many queries; the causal tap is a fan-in over all of them.** One
-   mutator invocation is one engine commit that returns per-query batches for *every* affected query.
-   `createCausalTap` buffers them in a single qid-keyed map and folds them into one block under the
-   cause. That correlation is store-level by nature — per-view, you'd re-aggregate N independent
-   callbacks back into the qid buffer the store already gives you, and views churn (a changed
-   limit/filter destroys + rebuilds the view) while the store subscription rides through.
-
-The store fires each change listener *after* the fold (`onEvent` → `applyChanges` → listeners), so a
-listener that wants the post-apply snapshot can still re-read the view by `qid`. Two refinements stay
-open: making the `removedSubtree` opt-in per-qid (today one global counter enriches every view's
-removals once any consumer asks), and widening the change callback to hand the post-fold view
-alongside the diff so a template needing list context doesn't have to look the view up itself.
-
-## What lives where
-
-- **Position→name resolution** is in `@rindle/client` (`resolveChange`, `subRow`, `ResolvedChange`,
-  `NamedRow`) — it's broadly useful to anything consuming a `FlatChange`.
-- **The narration framework** (registry shape, `createNarrator`, `digest`, salience, the causal
-  digest) is here.
-- **The templates and cause headlines** are yours — co-locate them with the queries and mutators.
+In React, `useNarration(query, NARRATORS, { ctx })` wires the view lifecycle and change
+channel for you and returns a stable `Narration` handle — drain it with `take()` when you
+prompt the model. See [rindle.sh/docs/agents](https://rindle.sh/docs/agents) for the full
+walkthrough (resolution, nested `related` templates, salience, and the observe→act loop).

package/dist/index.d.ts

@@ -1,5 +1,3 @@
 export { createNarrator, SALIENCE_MARK, salienceRank, } from "./narrator.ts";
-export type { NamedRow, NarrateContext, Narrator, NarratorRegistry, QueryNarrator, ResolvedChange, Salience, SemanticEvent, Template, TemplateCtx, } from "./narrator.ts";
-export { attachCausalTap, createCausalTap, narrateCommit, } from "./causal.ts";
-export type { Cause, CausalDigest, CausalEffect, CausalTap, CauseTemplate, ChangeStream, CommitBatch, DigestOpts, QueryBinding, } from "./causal.ts";
+export type { NamedRow, NarrateContext, Narrator, NarratorRegistry, QueryNarrator, RelatedNarrator, ResolvedChange, Salience, SemanticEvent, Template, TemplateCtx, } from "./narrator.ts";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,KAAK,EACL,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,EACV,YAAY,GACb,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,QAAQ,EACR,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,cAAc,EACd,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,WAAW,GACZ,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,10 +1,9 @@
 // @rindle/narrator — turn a Rindle query's flat-change stream into agent-ready prose.
 //
-// Pipeline: a backend's per-query `FlatChange`s → `resolveChange` (@rindle/client) lifts each into
-// NAMED rows → per-query templates render salience-tagged `SemanticEvent`s → `digest()` folds a
-// batch into a prompt block. `narrateCommit` / `createCausalTap` additionally group one commit's
-// effects under the named mutator that caused them. Drive it off a live store with the supported
-// `store.subscribeChanges` seam (and read each query's `WireSchema` from `view.schema`).
+// Pipeline: a view's per-query `FlatChange`s (delivered by `view.onChanges` / `store.materialize(
+// query, { onChanges })`, net of no-op rebase cycles) → `resolveChange` (@rindle/client) lifts each
+// into NAMED rows → per-query templates render salience-tagged `SemanticEvent`s → `digest()` folds a
+// batch into a prompt block. Drive it off a live view's OWN change channel — the position→name source
+// is that view's `schema`. In React, `@rindle/react`'s `useNarration` wires this for you.
 export { createNarrator, SALIENCE_MARK, salienceRank, } from "./narrator.js";
-export { attachCausalTap, createCausalTap, narrateCommit, } from "./causal.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,mGAAmG;AACnG,gGAAgG;AAChG,iGAAiG;AACjG,iGAAiG;AACjG,yFAAyF;AAEzF,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC;AAcvB,OAAO,EACL,eAAe,EACf,eAAe,EACf,aAAa,GACd,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,EAAE;AACF,kGAAkG;AAClG,oGAAoG;AACpG,qGAAqG;AACrG,sGAAsG;AACtG,0FAA0F;AAE1F,OAAO,EACL,cAAc,EACd,aAAa,EACb,YAAY,GACb,MAAM,eAAe,CAAC"}

package/dist/narrator.d.ts

@@ -18,11 +18,29 @@ export interface TemplateCtx {
     context: NarrateContext;
 }
 export type Template = (ctx: TemplateCtx) => string | null;
+/** Handlers for changes to ONE nested relationship (keyed by its alias in {@link QueryNarrator.related}),
+ *  by op — plus an optional salience override for that relationship's events. A nested template reads
+ *  `row` (the nested row), `old`, and `parent` (its immediate container — the deck for a slide, the
+ *  slide for a component). */
+export interface RelatedNarrator {
+    /** Override the query's default salience for events on this relationship (else inherits it). */
+    salience?: Salience;
+    add?: Template;
+    remove?: Template;
+    edit?: Template;
+}
 export interface QueryNarrator {
     /** Default importance of this query's events; an op handler may override via the return tuple. */
     salience: Salience;
     /** Handlers for changes at the ROOT level, by op. */
     root?: Partial<Record<"add" | "remove" | "edit", Template>>;
+    /** Handlers for changes to a NESTED relationship, keyed by op — so ONE materialized view narrates
+     *  its whole tree: e.g. a deck's title at the root, slide edits under `slides`, component adds under
+     *  `components`. Key by the relationship's LEAF alias (`components`) for the common case, or by the
+     *  FULL dotted alias-chain from the root (`slides.components`) to disambiguate two relationships that
+     *  share a leaf alias at different tree positions (e.g. `slides.components` vs `appendix.components`).
+     *  A dotted key wins over a leaf key when both match; a bare leaf key still matches at any depth. */
+    related?: Record<string, RelatedNarrator>;
     /** Handlers for an aggregate slot (`countAs`), keyed by the count's alias. */
     counts?: Record<string, Template>;
 }
@@ -44,9 +62,9 @@ export interface Narrator {
     /** Format a batch of rendered events for an agent prompt (salience-marked, suppressions dropped). */
     digest(events: SemanticEvent[]): string;
 }
-/** Per-salience glyph for a rendered line (shared with the causal digest). */
+/** Per-salience glyph for a rendered line. */
 export declare const SALIENCE_MARK: Record<Salience, string>;
-/** Order salience high→low (shared with the causal digest). */
+/** Order salience high→low. */
 export declare const salienceRank: (s: Salience) => number;
 /** Build a narrator over an app-supplied {@link NarratorRegistry}. Resolution is driven entirely by
  *  the per-query `WireSchema` passed to {@link Narrator.narrate}, so the narrator holds no schema

package/dist/narrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"narrator.d.ts","sourceRoot":"","sources":["../src/narrator.ts"],"names":[],"mappings":"AAUA,OAAO,EAAyB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7H,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,QAAQ,CAAC;IACd,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,qGAAqG;IACrG,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,uEAAuE;IACvE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IACxC,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,IAAI,CAAC;AAE3D,MAAM,WAAW,aAAa;IAC5B,kGAAkG;IAClG,QAAQ,EAAE,QAAQ,CAAC;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC5D,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnC;AAED,8FAA8F;AAC9F,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE7D,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB;;gCAE4B;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,aAAa,EAAE,CAAC;IACtI,qGAAqG;IACrG,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC;CACzC;AAED,8EAA8E;AAC9E,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAA4C,CAAC;AAEhG,+DAA+D;AAC/D,eAAO,MAAM,YAAY,GAAI,GAAG,QAAQ,KAAG,MAAoD,CAAC;AAEhG;;wBAEwB;AACxB,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,QAAQ,CAqCpE"}
+{"version":3,"file":"narrator.d.ts","sourceRoot":"","sources":["../src/narrator.ts"],"names":[],"mappings":"AAUA,OAAO,EAAyB,KAAK,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE7H,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AAEzC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEpD,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,QAAQ,CAAC;IACd,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,qGAAqG;IACrG,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,uEAAuE;IACvE,GAAG,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,QAAQ,GAAG,IAAI,CAAC;IACxC,SAAS,CAAC,EAAE,cAAc,CAAC,WAAW,CAAC,CAAC;IACxC,OAAO,EAAE,cAAc,CAAC;CACzB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,IAAI,CAAC;AAE3D;;;8BAG8B;AAC9B,MAAM,WAAW,eAAe;IAC9B,gGAAgG;IAChG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,IAAI,CAAC,EAAE,QAAQ,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,kGAAkG;IAClG,QAAQ,EAAE,QAAQ,CAAC;IACnB,qDAAqD;IACrD,IAAI,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,QAAQ,GAAG,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC5D;;;;;yGAKqG;IACrG,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;CACnC;AAED,8FAA8F;AAC9F,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;AAE7D,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,QAAQ;IACvB;;gCAE4B;IAC5B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,EAAE,GAAG,CAAC,EAAE,cAAc,GAAG,aAAa,EAAE,CAAC;IACtI,qGAAqG;IACrG,MAAM,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,MAAM,CAAC;CACzC;AAED,8CAA8C;AAC9C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAA4C,CAAC;AAEhG,+BAA+B;AAC/B,eAAO,MAAM,YAAY,GAAI,GAAG,QAAQ,KAAG,MAAoD,CAAC;AAEhG;;wBAEwB;AACxB,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,QAAQ,CA+CpE"}

package/dist/narrator.js

@@ -8,9 +8,9 @@
 // — small, because the query and relationship NAMES already carry the meaning; the app supplies the
 // registry to {@link createNarrator}.
 import { resolveChange, subRow } from "@rindle/client";
-/** Per-salience glyph for a rendered line (shared with the causal digest). */
+/** Per-salience glyph for a rendered line. */
 export const SALIENCE_MARK = { alert: "⚠️", info: "•", ambient: "·" };
-/** Order salience high→low (shared with the causal digest). */
+/** Order salience high→low. */
 export const salienceRank = (s) => (s === "alert" ? 2 : s === "info" ? 1 : 0);
 /** Build a narrator over an app-supplied {@link NarratorRegistry}. Resolution is driven entirely by
  *  the per-query `WireSchema` passed to {@link Narrator.narrate}, so the narrator holds no schema
@@ -25,6 +25,7 @@ export function createNarrator(narrators) {
                 if (!resolved)
                     continue;
                 let text = null;
+                let salience = spec?.salience ?? "info";
                 if (spec) {
                     const tctx = {
                         row: resolved.row,
@@ -34,20 +35,29 @@ export function createNarrator(narrators) {
                         aggregate: resolved.aggregate,
                         context: ctx,
                     };
+                    // A nested relationship change (not the root, not an aggregate) matches a `related` template
+                    // keyed by its FULL dotted alias-chain (`slides.components`) if present, else its leaf alias
+                    // (`components`) — so two same-leaf relationships at different tree positions never collide,
+                    // while the common single-position case still keys by the bare alias.
+                    const relSpec = resolved.alias !== "" && !resolved.aggregate
+                        ? (spec.related?.[resolved.aliasChain.join(".")] ?? spec.related?.[resolved.alias])
+                        : undefined;
                     const tmpl = resolved.aggregate
                         ? spec.counts?.[resolved.aggregate.alias]
                         : resolved.alias === ""
                             ? spec.root?.[resolved.op]
-                            : undefined; // sub-level changes surface through the root `add` node, not on their own
+                            : relSpec?.[resolved.op];
                     text = tmpl ? tmpl(tctx) : null;
+                    if (relSpec?.salience)
+                        salience = relSpec.salience;
                 }
-                out.push({ query, phase, salience: spec?.salience ?? "info", resolved, text });
+                out.push({ query, phase, salience, resolved, text });
             }
             return out;
         },
         digest(events) {
             return events
-                .filter((e) => e.text)
+                .filter((e) => e.text !== null)
                 .sort((a, b) => salienceRank(b.salience) - salienceRank(a.salience))
                 .map((e) => `${SALIENCE_MARK[e.salience]} ${e.text}`)
                 .join("\n");

package/dist/narrator.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rindle/narrator",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -8,7 +8,7 @@
     "directory": "packages/narrator"
   },
   "type": "module",
-  "description": "Turn a Rindle query's flat-change stream into agent-ready prose: resolve each FlatChange to named rows (via @rindle/client), render per-query templates into salience-tagged SemanticEvents, and group a commit's effects under the mutator that caused them (causal digest).",
+  "description": "Turn a Rindle view's netted flat-change stream into agent-ready prose: resolve each FlatChange to named rows (via @rindle/client), render per-query templates (root + nested relationships) into salience-tagged SemanticEvents, and digest a batch into a ranked block for an agent prompt.",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "sideEffects": false,
@@ -25,7 +25,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@rindle/client": "0.4.3"
+    "@rindle/client": "0.4.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",

package/src/index.ts

@@ -1,10 +1,10 @@
 // @rindle/narrator — turn a Rindle query's flat-change stream into agent-ready prose.
 //
-// Pipeline: a backend's per-query `FlatChange`s → `resolveChange` (@rindle/client) lifts each into
-// NAMED rows → per-query templates render salience-tagged `SemanticEvent`s → `digest()` folds a
-// batch into a prompt block. `narrateCommit` / `createCausalTap` additionally group one commit's
-// effects under the named mutator that caused them. Drive it off a live store with the supported
-// `store.subscribeChanges` seam (and read each query's `WireSchema` from `view.schema`).
+// Pipeline: a view's per-query `FlatChange`s (delivered by `view.onChanges` / `store.materialize(
+// query, { onChanges })`, net of no-op rebase cycles) → `resolveChange` (@rindle/client) lifts each
+// into NAMED rows → per-query templates render salience-tagged `SemanticEvent`s → `digest()` folds a
+// batch into a prompt block. Drive it off a live view's OWN change channel — the position→name source
+// is that view's `schema`. In React, `@rindle/react`'s `useNarration` wires this for you.
 
 export {
   createNarrator,
@@ -17,26 +17,10 @@ export type {
   Narrator,
   NarratorRegistry,
   QueryNarrator,
+  RelatedNarrator,
   ResolvedChange,
   Salience,
   SemanticEvent,
   Template,
   TemplateCtx,
 } from "./narrator.ts";
-
-export {
-  attachCausalTap,
-  createCausalTap,
-  narrateCommit,
-} from "./causal.ts";
-export type {
-  Cause,
-  CausalDigest,
-  CausalEffect,
-  CausalTap,
-  CauseTemplate,
-  ChangeStream,
-  CommitBatch,
-  DigestOpts,
-  QueryBinding,
-} from "./causal.ts";

package/src/narrator.ts

@@ -34,11 +34,30 @@ export interface TemplateCtx {
 
 export type Template = (ctx: TemplateCtx) => string | null;
 
+/** Handlers for changes to ONE nested relationship (keyed by its alias in {@link QueryNarrator.related}),
+ *  by op — plus an optional salience override for that relationship's events. A nested template reads
+ *  `row` (the nested row), `old`, and `parent` (its immediate container — the deck for a slide, the
+ *  slide for a component). */
+export interface RelatedNarrator {
+  /** Override the query's default salience for events on this relationship (else inherits it). */
+  salience?: Salience;
+  add?: Template;
+  remove?: Template;
+  edit?: Template;
+}
+
 export interface QueryNarrator {
   /** Default importance of this query's events; an op handler may override via the return tuple. */
   salience: Salience;
   /** Handlers for changes at the ROOT level, by op. */
   root?: Partial<Record<"add" | "remove" | "edit", Template>>;
+  /** Handlers for changes to a NESTED relationship, keyed by op — so ONE materialized view narrates
+   *  its whole tree: e.g. a deck's title at the root, slide edits under `slides`, component adds under
+   *  `components`. Key by the relationship's LEAF alias (`components`) for the common case, or by the
+   *  FULL dotted alias-chain from the root (`slides.components`) to disambiguate two relationships that
+   *  share a leaf alias at different tree positions (e.g. `slides.components` vs `appendix.components`).
+   *  A dotted key wins over a leaf key when both match; a bare leaf key still matches at any depth. */
+  related?: Record<string, RelatedNarrator>;
   /** Handlers for an aggregate slot (`countAs`), keyed by the count's alias. */
   counts?: Record<string, Template>;
 }
@@ -64,10 +83,10 @@ export interface Narrator {
   digest(events: SemanticEvent[]): string;
 }
 
-/** Per-salience glyph for a rendered line (shared with the causal digest). */
+/** Per-salience glyph for a rendered line. */
 export const SALIENCE_MARK: Record<Salience, string> = { alert: "⚠️", info: "•", ambient: "·" };
 
-/** Order salience high→low (shared with the causal digest). */
+/** Order salience high→low. */
 export const salienceRank = (s: Salience): number => (s === "alert" ? 2 : s === "info" ? 1 : 0);
 
 /** Build a narrator over an app-supplied {@link NarratorRegistry}. Resolution is driven entirely by
@@ -82,6 +101,7 @@ export function createNarrator(narrators: NarratorRegistry): Narrator {
         const resolved = resolveChange(schema, change);
         if (!resolved) continue;
         let text: string | null = null;
+        let salience: Salience = spec?.salience ?? "info";
         if (spec) {
           const tctx: TemplateCtx = {
             row: resolved.row,
@@ -91,20 +111,29 @@ export function createNarrator(narrators: NarratorRegistry): Narrator {
             aggregate: resolved.aggregate,
             context: ctx,
           };
+          // A nested relationship change (not the root, not an aggregate) matches a `related` template
+          // keyed by its FULL dotted alias-chain (`slides.components`) if present, else its leaf alias
+          // (`components`) — so two same-leaf relationships at different tree positions never collide,
+          // while the common single-position case still keys by the bare alias.
+          const relSpec =
+            resolved.alias !== "" && !resolved.aggregate
+              ? (spec.related?.[resolved.aliasChain.join(".")] ?? spec.related?.[resolved.alias])
+              : undefined;
           const tmpl = resolved.aggregate
             ? spec.counts?.[resolved.aggregate.alias]
             : resolved.alias === ""
               ? spec.root?.[resolved.op]
-              : undefined; // sub-level changes surface through the root `add` node, not on their own
+              : relSpec?.[resolved.op];
           text = tmpl ? tmpl(tctx) : null;
+          if (relSpec?.salience) salience = relSpec.salience;
         }
-        out.push({ query, phase, salience: spec?.salience ?? "info", resolved, text });
+        out.push({ query, phase, salience, resolved, text });
       }
       return out;
     },
     digest(events) {
       return events
-        .filter((e) => e.text)
+        .filter((e) => e.text !== null)
         .sort((a, b) => salienceRank(b.salience) - salienceRank(a.salience))
         .map((e) => `${SALIENCE_MARK[e.salience]} ${e.text}`)
         .join("\n");

package/dist/causal.d.ts

@@ -1,80 +0,0 @@
-import type { ArrayView, ChangeEvent, FlatChange, QueryId, WireSchema } from "@rindle/client";
-import { type NarrateContext, type Narrator, type Salience, type SemanticEvent } from "./narrator.ts";
-/** The cause: a named mutator + its args (the same `(name, args)` the optimistic envelope carries). */
-export interface Cause {
-    mutator: string;
-    args?: unknown;
-}
-/** What a subscribed query needs to be narrated: its `defineQuery` name, its `WireSchema` (from the
- *  query's `hello` frame / `view.schema`), and ctx. (One per live `materialize()`, keyed by the
- *  engine `queryId`.) */
-export interface QueryBinding {
-    query: string;
-    schema: WireSchema;
-    ctx?: NarrateContext;
-}
-/** One commit's per-query batch — exactly the `tx.commit()` / backend-dispatch element shape. */
-export interface CommitBatch {
-    queryId: QueryId;
-    events: FlatChange[];
-}
-/** Render the cause headline from a mutator name. Co-locate these with the mutators, the way
- *  narrators are co-located with queries; absent ⇒ the generic `mutator(k=v, …)` fallback. */
-export type CauseTemplate = (args: unknown) => string;
-/** The narrated effects of the commit on ONE query (suppressed/ambient nulls already dropped). */
-export interface CausalEffect {
-    query: string;
-    events: SemanticEvent[];
-}
-export interface CausalDigest {
-    cause: Cause;
-    /** Highest salience across all effects (`ambient` when there are none). */
-    salience: Salience;
-    /** Only queries with ≥1 narratable effect, ordered by salience then name. */
-    effects: CausalEffect[];
-    /** The append-ready block (cause headline + indented effect lines); `""` when nothing narratable. */
-    text: string;
-}
-export interface DigestOpts {
-    /** Per-mutator cause headlines (keyed by mutator name). */
-    causes?: Record<string, CauseTemplate>;
-    /** Emit the cause headline even when the commit had no narratable effect (default false). */
-    includeEmpty?: boolean;
-}
-/** Group one commit's batches under its cause and render the block. */
-export declare function narrateCommit(narrator: Narrator, bindings: ReadonlyMap<QueryId, QueryBinding>, cause: Cause, batches: readonly CommitBatch[], opts?: DigestOpts): CausalDigest;
-/** One commit's correlator. Buffer a commit's per-query batches between {@link CausalTap.begin} and
- *  {@link CausalTap.end}, then fold them into a {@link CausalDigest} under the in-flight cause. */
-export interface CausalTap {
-    /** Mark the start of a mutator's commit; clears any prior buffer. */
-    begin(cause: Cause): void;
-    /** Feed one raw change frame (wire `subscribeChanges((qid, ev) => tap.capture(qid, ev))`). Only
-     *  `batch` frames within an active `begin`/`end` window are buffered; `hello`/`snapshot` ignored. */
-    capture(qid: QueryId, ev: ChangeEvent): void;
-    /** Close the window and render the digest (or `null` if no `begin` is active). */
-    end(): CausalDigest | null;
-}
-/**
- * Correlate a store's change frames with the mutator currently in flight. The local /
- * optimistic-prediction path dispatches a commit's batches synchronously inside `mutate()`, so:
- *
- *   tap.begin({ mutator: "seatGuest", args });
- *   await store.write(tx => …);   // subscribeChanges fires → tap.capture(qid, ev)
- *   const digest = tap.end();     // one CausalDigest for the whole commit
- *
- * Wire `capture` into {@link attachCausalTap} (or directly into `store.subscribeChanges`).
- */
-export declare function createCausalTap(narrator: Narrator, bindings: ReadonlyMap<QueryId, QueryBinding>, opts?: DigestOpts): CausalTap;
-/** The minimal store surface {@link attachCausalTap} needs — the supported public change stream.
- *  The listener's third arg is the post-fold {@link ArrayView} for the qid (always the plural view);
- *  the causal tap ignores it, but the seam carries it for consumers that want list context. */
-export interface ChangeStream {
-    subscribeChanges(listener: (qid: QueryId, ev: ChangeEvent, view?: ArrayView<unknown>) => void): () => void;
-}
-/** Create a {@link CausalTap} and wire its `capture` into a store's {@link ChangeStream.subscribeChanges}.
- *  Returns the tap (call `begin`/`end` around each mutator) plus a `detach` to stop listening. */
-export declare function attachCausalTap(store: ChangeStream, narrator: Narrator, bindings: ReadonlyMap<QueryId, QueryBinding>, opts?: DigestOpts): {
-    tap: CausalTap;
-    detach: () => void;
-};
-//# sourceMappingURL=causal.d.ts.map

package/dist/causal.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"causal.d.ts","sourceRoot":"","sources":["../src/causal.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE9F,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,aAAa,EAGnB,MAAM,eAAe,CAAC;AAIvB,uGAAuG;AACvG,MAAM,WAAW,KAAK;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;yBAEyB;AACzB,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,UAAU,CAAC;IACnB,GAAG,CAAC,EAAE,cAAc,CAAC;CACtB;AAED,iGAAiG;AACjG,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAED;8FAC8F;AAC9F,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,CAAC;AAItD,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,aAAa,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,KAAK,CAAC;IACb,2EAA2E;IAC3E,QAAQ,EAAE,QAAQ,CAAC;IACnB,6EAA6E;IAC7E,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,qGAAqG;IACrG,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;IACvC,6FAA6F;IAC7F,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAqBD,uEAAuE;AACvE,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,EAC5C,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,SAAS,WAAW,EAAE,EAC/B,IAAI,GAAE,UAAe,GACpB,YAAY,CAgCd;AAOD;mGACmG;AACnG,MAAM,WAAW,SAAS;IACxB,qEAAqE;IACrE,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC1B;yGACqG;IACrG,OAAO,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7C,kFAAkF;IAClF,GAAG,IAAI,YAAY,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,EAC5C,IAAI,GAAE,UAAe,GACpB,SAAS,CAuBX;AAED;;+FAE+F;AAC/F,MAAM,WAAW,YAAY;IAC3B,gBAAgB,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5G;AAED;kGACkG;AAClG,wBAAgB,eAAe,CAC7B,KAAK,EAAE,YAAY,EACnB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,EAC5C,IAAI,GAAE,UAAe,GACpB;IAAE,GAAG,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAIxC"}

package/dist/causal.js

@@ -1,115 +0,0 @@
-// Causal digest — group ONE commit's effects under the named mutator that caused them.
-//
-// In rindle a mutator invocation is one engine commit, and a commit returns per-query batches of
-// FlatChanges. So "cause → effects" is a free join: the mutator name+args is the cause, every batch
-// from that commit is an effect. We narrate each effect through the per-query templates
-// (narrator.ts) and render one block:
-//
-//   ↳ Seated a guest (seatGuest guestId=g1, tableId=t7)
-//      ⚠️ Jane Doe got a seat for the Smith wedding.
-//      • You're seated at Head Table, seat 3.
-//
-// That block is also the natural APPEND UNIT for the cache-coherent context story: one commit, one
-// immutable block appended to the trunk — never a rewrite of earlier turns.
-//
-// Two layers: `narrateCommit` is a pure (bindings + cause + batches) → CausalDigest function; the
-// live-store glue (`createCausalTap` / `attachCausalTap`) wraps a mutator call (begin → mutate →
-// end) and feeds it off the store's supported `subscribeChanges` stream.
-import { SALIENCE_MARK, salienceRank, } from "./narrator.js";
-// ----------------------------- rendering -----------------------------
-function formatArgs(args) {
-    if (args === undefined || args === null)
-        return "";
-    if (typeof args !== "object")
-        return String(args);
-    const parts = Object.entries(args).map(([k, v]) => {
-        const s = typeof v === "string" ? v : JSON.stringify(v);
-        return `${k}=${s && s.length > 24 ? s.slice(0, 23) + "…" : s}`;
-    });
-    return parts.join(", ");
-}
-function causeHeadline(cause, causes) {
-    const tmpl = causes?.[cause.mutator];
-    if (tmpl)
-        return tmpl(cause.args);
-    const a = formatArgs(cause.args);
-    return `${cause.mutator}(${a})`;
-}
-/** Group one commit's batches under its cause and render the block. */
-export function narrateCommit(narrator, bindings, cause, batches, opts = {}) {
-    const effects = [];
-    let maxRank = -1;
-    let salience = "ambient";
-    for (const batch of batches) {
-        const b = bindings.get(batch.queryId);
-        if (!b || batch.events.length === 0)
-            continue;
-        const events = narrator.narrate(b.query, b.schema, batch.events, "batch", b.ctx).filter((e) => e.text);
-        if (events.length === 0)
-            continue;
-        effects.push({ query: b.query, events });
-        for (const e of events) {
-            if (salienceRank(e.salience) > maxRank) {
-                maxRank = salienceRank(e.salience);
-                salience = e.salience;
-            }
-        }
-    }
-    // Strongest-first, then by query name; lines within a query keep engine order.
-    effects.sort((x, y) => salienceRank(top(y)) - salienceRank(top(x)) || (x.query < y.query ? -1 : 1));
-    let text = "";
-    if (effects.length > 0 || opts.includeEmpty) {
-        const lines = [`↳ ${causeHeadline(cause, opts.causes)}`];
-        for (const eff of effects) {
-            for (const e of eff.events)
-                lines.push(`   ${SALIENCE_MARK[e.salience]} ${e.text}`);
-        }
-        text = lines.join("\n");
-    }
-    return { cause, salience, effects, text };
-}
-const top = (eff) => eff.events.reduce((acc, e) => (salienceRank(e.salience) > salienceRank(acc) ? e.salience : acc), "ambient");
-/**
- * Correlate a store's change frames with the mutator currently in flight. The local /
- * optimistic-prediction path dispatches a commit's batches synchronously inside `mutate()`, so:
- *
- *   tap.begin({ mutator: "seatGuest", args });
- *   await store.write(tx => …);   // subscribeChanges fires → tap.capture(qid, ev)
- *   const digest = tap.end();     // one CausalDigest for the whole commit
- *
- * Wire `capture` into {@link attachCausalTap} (or directly into `store.subscribeChanges`).
- */
-export function createCausalTap(narrator, bindings, opts = {}) {
-    let cause = null;
-    const buf = new Map();
-    return {
-        begin(c) {
-            cause = c;
-            buf.clear();
-        },
-        capture(qid, ev) {
-            if (!cause || ev.type !== "batch")
-                return; // hello/snapshot aren't commit effects
-            const list = buf.get(qid) ?? [];
-            list.push(...ev.events);
-            buf.set(qid, list);
-        },
-        end() {
-            if (!cause)
-                return null;
-            const batches = [...buf].map(([queryId, events]) => ({ queryId, events }));
-            const digest = narrateCommit(narrator, bindings, cause, batches, opts);
-            cause = null;
-            buf.clear();
-            return digest;
-        },
-    };
-}
-/** Create a {@link CausalTap} and wire its `capture` into a store's {@link ChangeStream.subscribeChanges}.
- *  Returns the tap (call `begin`/`end` around each mutator) plus a `detach` to stop listening. */
-export function attachCausalTap(store, narrator, bindings, opts = {}) {
-    const tap = createCausalTap(narrator, bindings, opts);
-    const detach = store.subscribeChanges((qid, ev) => tap.capture(qid, ev));
-    return { tap, detach };
-}
-//# sourceMappingURL=causal.js.map

package/dist/causal.js.map

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

package/src/causal.ts

@@ -1,216 +0,0 @@
-// Causal digest — group ONE commit's effects under the named mutator that caused them.
-//
-// In rindle a mutator invocation is one engine commit, and a commit returns per-query batches of
-// FlatChanges. So "cause → effects" is a free join: the mutator name+args is the cause, every batch
-// from that commit is an effect. We narrate each effect through the per-query templates
-// (narrator.ts) and render one block:
-//
-//   ↳ Seated a guest (seatGuest guestId=g1, tableId=t7)
-//      ⚠️ Jane Doe got a seat for the Smith wedding.
-//      • You're seated at Head Table, seat 3.
-//
-// That block is also the natural APPEND UNIT for the cache-coherent context story: one commit, one
-// immutable block appended to the trunk — never a rewrite of earlier turns.
-//
-// Two layers: `narrateCommit` is a pure (bindings + cause + batches) → CausalDigest function; the
-// live-store glue (`createCausalTap` / `attachCausalTap`) wraps a mutator call (begin → mutate →
-// end) and feeds it off the store's supported `subscribeChanges` stream.
-
-import type { ArrayView, ChangeEvent, FlatChange, QueryId, WireSchema } from "@rindle/client";
-
-import {
-  type NarrateContext,
-  type Narrator,
-  type Salience,
-  type SemanticEvent,
-  SALIENCE_MARK,
-  salienceRank,
-} from "./narrator.ts";
-
-// ----------------------------- inputs -----------------------------
-
-/** The cause: a named mutator + its args (the same `(name, args)` the optimistic envelope carries). */
-export interface Cause {
-  mutator: string;
-  args?: unknown;
-}
-
-/** What a subscribed query needs to be narrated: its `defineQuery` name, its `WireSchema` (from the
- *  query's `hello` frame / `view.schema`), and ctx. (One per live `materialize()`, keyed by the
- *  engine `queryId`.) */
-export interface QueryBinding {
-  query: string;
-  schema: WireSchema;
-  ctx?: NarrateContext;
-}
-
-/** One commit's per-query batch — exactly the `tx.commit()` / backend-dispatch element shape. */
-export interface CommitBatch {
-  queryId: QueryId;
-  events: FlatChange[];
-}
-
-/** Render the cause headline from a mutator name. Co-locate these with the mutators, the way
- *  narrators are co-located with queries; absent ⇒ the generic `mutator(k=v, …)` fallback. */
-export type CauseTemplate = (args: unknown) => string;
-
-// ----------------------------- outputs -----------------------------
-
-/** The narrated effects of the commit on ONE query (suppressed/ambient nulls already dropped). */
-export interface CausalEffect {
-  query: string;
-  events: SemanticEvent[];
-}
-
-export interface CausalDigest {
-  cause: Cause;
-  /** Highest salience across all effects (`ambient` when there are none). */
-  salience: Salience;
-  /** Only queries with ≥1 narratable effect, ordered by salience then name. */
-  effects: CausalEffect[];
-  /** The append-ready block (cause headline + indented effect lines); `""` when nothing narratable. */
-  text: string;
-}
-
-export interface DigestOpts {
-  /** Per-mutator cause headlines (keyed by mutator name). */
-  causes?: Record<string, CauseTemplate>;
-  /** Emit the cause headline even when the commit had no narratable effect (default false). */
-  includeEmpty?: boolean;
-}
-
-// ----------------------------- rendering -----------------------------
-
-function formatArgs(args: unknown): string {
-  if (args === undefined || args === null) return "";
-  if (typeof args !== "object") return String(args);
-  const parts = Object.entries(args as Record<string, unknown>).map(([k, v]) => {
-    const s = typeof v === "string" ? v : JSON.stringify(v);
-    return `${k}=${s && s.length > 24 ? s.slice(0, 23) + "…" : s}`;
-  });
-  return parts.join(", ");
-}
-
-function causeHeadline(cause: Cause, causes?: Record<string, CauseTemplate>): string {
-  const tmpl = causes?.[cause.mutator];
-  if (tmpl) return tmpl(cause.args);
-  const a = formatArgs(cause.args);
-  return `${cause.mutator}(${a})`;
-}
-
-/** Group one commit's batches under its cause and render the block. */
-export function narrateCommit(
-  narrator: Narrator,
-  bindings: ReadonlyMap<QueryId, QueryBinding>,
-  cause: Cause,
-  batches: readonly CommitBatch[],
-  opts: DigestOpts = {},
-): CausalDigest {
-  const effects: CausalEffect[] = [];
-  let maxRank = -1;
-  let salience: Salience = "ambient";
-
-  for (const batch of batches) {
-    const b = bindings.get(batch.queryId);
-    if (!b || batch.events.length === 0) continue;
-    const events = narrator.narrate(b.query, b.schema, batch.events, "batch", b.ctx).filter((e) => e.text);
-    if (events.length === 0) continue;
-    effects.push({ query: b.query, events });
-    for (const e of events) {
-      if (salienceRank(e.salience) > maxRank) {
-        maxRank = salienceRank(e.salience);
-        salience = e.salience;
-      }
-    }
-  }
-
-  // Strongest-first, then by query name; lines within a query keep engine order.
-  effects.sort((x, y) => salienceRank(top(y)) - salienceRank(top(x)) || (x.query < y.query ? -1 : 1));
-
-  let text = "";
-  if (effects.length > 0 || opts.includeEmpty) {
-    const lines = [`↳ ${causeHeadline(cause, opts.causes)}`];
-    for (const eff of effects) {
-      for (const e of eff.events) lines.push(`   ${SALIENCE_MARK[e.salience]} ${e.text}`);
-    }
-    text = lines.join("\n");
-  }
-
-  return { cause, salience, effects, text };
-}
-
-const top = (eff: CausalEffect): Salience =>
-  eff.events.reduce<Salience>((acc, e) => (salienceRank(e.salience) > salienceRank(acc) ? e.salience : acc), "ambient");
-
-// ----------------------------- live-store glue -----------------------------
-
-/** One commit's correlator. Buffer a commit's per-query batches between {@link CausalTap.begin} and
- *  {@link CausalTap.end}, then fold them into a {@link CausalDigest} under the in-flight cause. */
-export interface CausalTap {
-  /** Mark the start of a mutator's commit; clears any prior buffer. */
-  begin(cause: Cause): void;
-  /** Feed one raw change frame (wire `subscribeChanges((qid, ev) => tap.capture(qid, ev))`). Only
-   *  `batch` frames within an active `begin`/`end` window are buffered; `hello`/`snapshot` ignored. */
-  capture(qid: QueryId, ev: ChangeEvent): void;
-  /** Close the window and render the digest (or `null` if no `begin` is active). */
-  end(): CausalDigest | null;
-}
-
-/**
- * Correlate a store's change frames with the mutator currently in flight. The local /
- * optimistic-prediction path dispatches a commit's batches synchronously inside `mutate()`, so:
- *
- *   tap.begin({ mutator: "seatGuest", args });
- *   await store.write(tx => …);   // subscribeChanges fires → tap.capture(qid, ev)
- *   const digest = tap.end();     // one CausalDigest for the whole commit
- *
- * Wire `capture` into {@link attachCausalTap} (or directly into `store.subscribeChanges`).
- */
-export function createCausalTap(
-  narrator: Narrator,
-  bindings: ReadonlyMap<QueryId, QueryBinding>,
-  opts: DigestOpts = {},
-): CausalTap {
-  let cause: Cause | null = null;
-  const buf = new Map<QueryId, FlatChange[]>();
-  return {
-    begin(c: Cause): void {
-      cause = c;
-      buf.clear();
-    },
-    capture(qid: QueryId, ev: ChangeEvent): void {
-      if (!cause || ev.type !== "batch") return; // hello/snapshot aren't commit effects
-      const list = buf.get(qid) ?? [];
-      list.push(...ev.events);
-      buf.set(qid, list);
-    },
-    end(): CausalDigest | null {
-      if (!cause) return null;
-      const batches: CommitBatch[] = [...buf].map(([queryId, events]) => ({ queryId, events }));
-      const digest = narrateCommit(narrator, bindings, cause, batches, opts);
-      cause = null;
-      buf.clear();
-      return digest;
-    },
-  };
-}
-
-/** The minimal store surface {@link attachCausalTap} needs — the supported public change stream.
- *  The listener's third arg is the post-fold {@link ArrayView} for the qid (always the plural view);
- *  the causal tap ignores it, but the seam carries it for consumers that want list context. */
-export interface ChangeStream {
-  subscribeChanges(listener: (qid: QueryId, ev: ChangeEvent, view?: ArrayView<unknown>) => void): () => void;
-}
-
-/** Create a {@link CausalTap} and wire its `capture` into a store's {@link ChangeStream.subscribeChanges}.
- *  Returns the tap (call `begin`/`end` around each mutator) plus a `detach` to stop listening. */
-export function attachCausalTap(
-  store: ChangeStream,
-  narrator: Narrator,
-  bindings: ReadonlyMap<QueryId, QueryBinding>,
-  opts: DigestOpts = {},
-): { tap: CausalTap; detach: () => void } {
-  const tap = createCausalTap(narrator, bindings, opts);
-  const detach = store.subscribeChanges((qid, ev) => tap.capture(qid, ev));
-  return { tap, detach };
-}