@rindle/narrator 0.4.3

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,102 @@
+# @rindle/narrator
+
+Turn a Rindle query's flat-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
+
+```ts
+import { createNarrator, attachCausalTap, type NarratorRegistry, type QueryBinding } 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",
+    root: {
+      add: ({ sub, context }) => `${sub("guest")?.name ?? "Someone"} is unseated for ${context.subject}.`,
+      remove: ({ context }) => `A guest got a seat for ${context.subject}.`,
+    },
+  },
+};
+
+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" })));
+});
+
+// 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.

package/dist/causal.d.ts

@@ -0,0 +1,80 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,115 @@
+// 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

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

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +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`).
+export { createNarrator, SALIENCE_MARK, salienceRank, } from "./narrator.js";
+export { attachCausalTap, createCausalTap, narrateCommit, } from "./causal.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/narrator.d.ts

@@ -0,0 +1,55 @@
+import { type FlatChange, type NamedRow, type ResolvedChange, type WireSchema } from "@rindle/client";
+export type { NamedRow, ResolvedChange };
+export type Salience = "alert" | "info" | "ambient";
+/** Context a template may interpolate — e.g. a human label for the subscription's subject. */
+export interface NarrateContext {
+    /** A human name for what the query is scoped to ("the Smith wedding"). */
+    subject?: string;
+    [k: string]: unknown;
+}
+export interface TemplateCtx {
+    row: NamedRow;
+    old?: NamedRow;
+    /** The parent row, for an aggregate/nested change (e.g. the `ticket_type` behind a `sold` count). */
+    parent?: NamedRow;
+    /** Resolve a named sub-row of the change (only populated on `add`). */
+    sub: (alias: string) => NamedRow | null;
+    aggregate?: ResolvedChange["aggregate"];
+    context: NarrateContext;
+}
+export type Template = (ctx: TemplateCtx) => string | null;
+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 an aggregate slot (`countAs`), keyed by the count's alias. */
+    counts?: Record<string, Template>;
+}
+/** A registry of {@link QueryNarrator}s, keyed by `defineQuery` name. Supplied by the app. */
+export type NarratorRegistry = Record<string, QueryNarrator>;
+/** One rendered semantic event. `text === null` was suppressed by its template (too ambient). */
+export interface SemanticEvent {
+    query: string;
+    phase: "snapshot" | "batch";
+    salience: Salience;
+    resolved: ResolvedChange;
+    text: string | null;
+}
+export interface Narrator {
+    /** Resolve + render a `FlatChange[]` for a named query into semantic events. `schema` is the
+     *  query's `WireSchema`, captured from its `hello` frame (or read off `view.schema`) — the
+     *  position→name source. */
+    narrate(query: string, schema: WireSchema, changes: FlatChange[], phase: "snapshot" | "batch", ctx?: NarrateContext): SemanticEvent[];
+    /** 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). */
+export declare const SALIENCE_MARK: Record<Salience, string>;
+/** Order salience high→low (shared with the causal digest). */
+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
+ *  state of its own. */
+export declare function createNarrator(narrators: NarratorRegistry): Narrator;
+//# sourceMappingURL=narrator.d.ts.map

package/dist/narrator.d.ts.map

@@ -0,0 +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"}

package/dist/narrator.js

@@ -0,0 +1,57 @@
+// The narration framework: per-query templates that render a resolved flat-change into prose.
+//
+// The position→name resolution (`resolveChange` / `subRow`) lives in @rindle/client — it is the
+// pure inverse of the wire encoder and broadly useful. This module is the layer ON TOP: a small
+// registry of hand-written, per-query templates keyed by `defineQuery` name + op (+ count alias),
+// salience tagging (alert / info / ambient), and a `digest()` that folds a batch of rendered events
+// into a salience-ranked block for an agent prompt. The templates are the only domain-specific part
+// — 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). */
+export const SALIENCE_MARK = { alert: "⚠️", info: "•", ambient: "·" };
+/** Order salience high→low (shared with the causal digest). */
+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
+ *  state of its own. */
+export function createNarrator(narrators) {
+    return {
+        narrate(query, schema, changes, phase, ctx = {}) {
+            const spec = narrators[query];
+            const out = [];
+            for (const change of changes) {
+                const resolved = resolveChange(schema, change);
+                if (!resolved)
+                    continue;
+                let text = null;
+                if (spec) {
+                    const tctx = {
+                        row: resolved.row,
+                        old: resolved.old,
+                        parent: resolved.parent,
+                        sub: (alias) => subRow(resolved, alias),
+                        aggregate: resolved.aggregate,
+                        context: ctx,
+                    };
+                    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
+                    text = tmpl ? tmpl(tctx) : null;
+                }
+                out.push({ query, phase, salience: spec?.salience ?? "info", resolved, text });
+            }
+            return out;
+        },
+        digest(events) {
+            return events
+                .filter((e) => e.text)
+                .sort((a, b) => salienceRank(b.salience) - salienceRank(a.salience))
+                .map((e) => `${SALIENCE_MARK[e.salience]} ${e.text}`)
+                .join("\n");
+        },
+    };
+}
+//# sourceMappingURL=narrator.js.map

package/dist/narrator.js.map

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rindle/narrator",
+  "version": "0.4.3",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rindle-sh/rindle.git",
+    "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).",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "@rindle/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@rindle/client": "0.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "tsc --noEmit && node --conditions=@rindle/source --test test/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/causal.ts

@@ -0,0 +1,216 @@
+// 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 };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+// @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`).
+
+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";

package/src/narrator.ts

@@ -0,0 +1,113 @@
+// The narration framework: per-query templates that render a resolved flat-change into prose.
+//
+// The position→name resolution (`resolveChange` / `subRow`) lives in @rindle/client — it is the
+// pure inverse of the wire encoder and broadly useful. This module is the layer ON TOP: a small
+// registry of hand-written, per-query templates keyed by `defineQuery` name + op (+ count alias),
+// salience tagging (alert / info / ambient), and a `digest()` that folds a batch of rendered events
+// into a salience-ranked block for an agent prompt. The templates are the only domain-specific part
+// — small, because the query and relationship NAMES already carry the meaning; the app supplies the
+// registry to {@link createNarrator}.
+
+import { resolveChange, subRow, type FlatChange, type NamedRow, type ResolvedChange, type WireSchema } from "@rindle/client";
+
+export type { NamedRow, ResolvedChange };
+
+export type Salience = "alert" | "info" | "ambient";
+
+/** Context a template may interpolate — e.g. a human label for the subscription's subject. */
+export interface NarrateContext {
+  /** A human name for what the query is scoped to ("the Smith wedding"). */
+  subject?: string;
+  [k: string]: unknown;
+}
+
+export interface TemplateCtx {
+  row: NamedRow;
+  old?: NamedRow;
+  /** The parent row, for an aggregate/nested change (e.g. the `ticket_type` behind a `sold` count). */
+  parent?: NamedRow;
+  /** Resolve a named sub-row of the change (only populated on `add`). */
+  sub: (alias: string) => NamedRow | null;
+  aggregate?: ResolvedChange["aggregate"];
+  context: NarrateContext;
+}
+
+export type Template = (ctx: TemplateCtx) => string | null;
+
+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 an aggregate slot (`countAs`), keyed by the count's alias. */
+  counts?: Record<string, Template>;
+}
+
+/** A registry of {@link QueryNarrator}s, keyed by `defineQuery` name. Supplied by the app. */
+export type NarratorRegistry = Record<string, QueryNarrator>;
+
+/** One rendered semantic event. `text === null` was suppressed by its template (too ambient). */
+export interface SemanticEvent {
+  query: string;
+  phase: "snapshot" | "batch";
+  salience: Salience;
+  resolved: ResolvedChange;
+  text: string | null;
+}
+
+export interface Narrator {
+  /** Resolve + render a `FlatChange[]` for a named query into semantic events. `schema` is the
+   *  query's `WireSchema`, captured from its `hello` frame (or read off `view.schema`) — the
+   *  position→name source. */
+  narrate(query: string, schema: WireSchema, changes: FlatChange[], phase: "snapshot" | "batch", ctx?: NarrateContext): SemanticEvent[];
+  /** 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). */
+export const SALIENCE_MARK: Record<Salience, string> = { alert: "⚠️", info: "•", ambient: "·" };
+
+/** Order salience high→low (shared with the causal digest). */
+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
+ *  the per-query `WireSchema` passed to {@link Narrator.narrate}, so the narrator holds no schema
+ *  state of its own. */
+export function createNarrator(narrators: NarratorRegistry): Narrator {
+  return {
+    narrate(query, schema, changes, phase, ctx = {}) {
+      const spec = narrators[query];
+      const out: SemanticEvent[] = [];
+      for (const change of changes) {
+        const resolved = resolveChange(schema, change);
+        if (!resolved) continue;
+        let text: string | null = null;
+        if (spec) {
+          const tctx: TemplateCtx = {
+            row: resolved.row,
+            old: resolved.old,
+            parent: resolved.parent,
+            sub: (alias) => subRow(resolved, alias),
+            aggregate: resolved.aggregate,
+            context: ctx,
+          };
+          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
+          text = tmpl ? tmpl(tctx) : null;
+        }
+        out.push({ query, phase, salience: spec?.salience ?? "info", resolved, text });
+      }
+      return out;
+    },
+    digest(events) {
+      return events
+        .filter((e) => e.text)
+        .sort((a, b) => salienceRank(b.salience) - salienceRank(a.salience))
+        .map((e) => `${SALIENCE_MARK[e.salience]} ${e.text}`)
+        .join("\n");
+    },
+  };
+}