brane 0.1.1 → 0.3.1

package/dist/test/diagram-self-loop-labels.test.js

@@ -0,0 +1,303 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { parseDiagram } from "../diagram/parse.js";
+import { renderDiagram } from "../diagram/index.js";
+import { layoutDiagram } from "../diagram/layout.js";
+import { measureEdgeLabel } from "../diagram/metrics.js";
+// A self-loop's label was parsed, carried through the IR, and dropped at the
+// last step: layout synthesises loops itself (dagre never sees them) and left
+// `labelPos` undefined, which the renderer reads as "no label". Nothing
+// warned — the diagram drew — so a Rule 30 state graph came back with all 24
+// arrows and none of the three loop labels that distinguish the vacuum from
+// the two stripe phases (claude-1vugmmfw:5, :7, :9). Every test here reads the
+// *output*: a label in the IR proves nothing, which is the trap the `classDef`
+// test fell into before it.
+const ok = (src) => {
+    const r = parseDiagram(src);
+    assert.equal(r.ok, true, `expected a parse, got ${r.ok ? "" : r.refusal.message}`);
+    return r.ok ? r.ir : undefined;
+};
+/** The chip `svg.ts` draws for a label, as a rect — the thing that has to fit. */
+function chipRect(e) {
+    assert.ok(e.label && e.labelPos, `${e.from}→${e.to} has a placed label`);
+    const { width, height } = measureEdgeLabel(e.label);
+    return {
+        left: e.labelPos.x - width / 2, right: e.labelPos.x + width / 2,
+        top: e.labelPos.y - height / 2, bottom: e.labelPos.y + height / 2,
+    };
+}
+const intersects = (a, b) => a.left < b.right && b.left < a.right && a.top < b.bottom && b.top < a.bottom;
+function assertInside(placed, r, what) {
+    assert.ok(r.left >= 0 && r.top >= 0 && r.right <= placed.width && r.bottom <= placed.height, `${what} chip ${JSON.stringify(r)} is not inside ${placed.width}x${placed.height}`);
+}
+/** The diagram self-loop labels were built for: eight states, 24 arrows, three
+ *  loops (claude-1vugmmfw:5). */
+const RULE30 = `flowchart TD
+  s000(["000"])
+  s001(["001"])
+  s010(["010"])
+  s011(["011"])
+  s100(["100"])
+  s101(["101"])
+  s110(["110"])
+  s111(["111"])
+  s000 -->|"00000"| s000
+  s000 -->|"00001"| s001
+  s000 -->|"10000"| s100
+  s000 -->|"10001"| s101
+  s001 -->|"00010/00011"| s011
+  s001 -->|"10010/10011"| s111
+  s010 -->|"10101"| s010
+  s010 -->|"10100"| s011
+  s010 -->|"00101"| s110
+  s010 -->|"00100"| s111
+  s011 -->|"10110/10111"| s010
+  s011 -->|"00110/00111"| s110
+  s100 -->|"11000"| s010
+  s100 -->|"11001"| s011
+  s100 -->|"01000"| s110
+  s100 -->|"01001"| s111
+  s101 -->|"11010/11011"| s001
+  s101 -->|"01010/01011"| s101
+  s110 -->|"11101"| s000
+  s110 -->|"11100"| s001
+  s110 -->|"01101"| s100
+  s110 -->|"01100"| s101
+  s111 -->|"11110/11111"| s000
+  s111 -->|"01110/01111"| s100`;
+const loopOf = (placed, id) => placed.edges.find((e) => e.selfLoop && e.from === id);
+describe("a self-loop's label is drawn", () => {
+    const DIRS = ["TD", "BT", "LR", "RL"];
+    it("reaches the SVG in every direction", () => {
+        for (const dir of DIRS) {
+            const r = renderDiagram(`flowchart ${dir}\n A -->|"vacuum"| A\n A --> B`);
+            assert.ok(r && r.svg.includes(">vacuum<"), `${dir}: the loop label is in the output`);
+        }
+    });
+    it("fits inside the viewBox, by its chip's four corners, on a top-rank node", () => {
+        // The union that sizes the canvas covered only the curve's points, and a
+        // chip is wider than the point it hangs on. "The text is in the SVG"
+        // would pass a chip drawn at negative y and never seen.
+        for (const dir of DIRS) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"a long loop label"| A\n A --> B`));
+            assertInside(placed, chipRect(loopOf(placed, "A")), `${dir} A`);
+        }
+    });
+    it("fits on the far side too, where only the maximum would have noticed", () => {
+        // A right-hand node in LR bows past `graph.width`; a bottom node in BT
+        // bows below `graph.height`. Both grow the canvas rather than clipping.
+        for (const src of [
+            `flowchart LR\n A --> B\n B -->|"a long loop label"| B`,
+            `flowchart TD\n A --> B\n B -->|"a long loop label"| B`,
+        ]) {
+            const placed = layoutDiagram(ok(src));
+            assertInside(placed, chipRect(loopOf(placed, "B")), src);
+        }
+    });
+    it("sits outside the node, off a cross-axis face — one no rank edge uses", () => {
+        for (const dir of ["TD", "BT"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"x"| A`));
+            const a = placed.nodes[0];
+            assert.ok(chipRect(loopOf(placed, "A")).left > a.x + a.width / 2, `${dir}: right of the right face`);
+        }
+        for (const dir of ["LR", "RL"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"x"| A`));
+            const a = placed.nodes[0];
+            assert.ok(chipRect(loopOf(placed, "A")).top > a.y + a.height / 2, `${dir}: below the bottom face`);
+        }
+    });
+});
+describe("the loop's space is reserved from dagre", () => {
+    // Dagre routes around what it was told about, and it was told nothing about
+    // the bow. On the Rule 30 graph it parked `01100` (110→101) exactly where
+    // 101's loop bows, and with the loop's own label missing, a reader took it
+    // for the loop's. Placing the label alone would have turned one wrong chip
+    // into two overlapping ones.
+    it("keeps another edge's chip out of the loop's chip", () => {
+        for (const dir of ["TD", "LR"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n B -->|"from B to A"| A\n A -->|"loop on A"| A`));
+            const loop = chipRect(loopOf(placed, "A"));
+            const other = chipRect(placed.edges.find((e) => !e.selfLoop));
+            assert.ok(!intersects(loop, other), `${dir}: ${JSON.stringify(loop)} overlaps ${JSON.stringify(other)}`);
+        }
+    });
+    it("but the node itself is drawn at its measured size, and edges attach to it", () => {
+        // Only dagre's box grows. If the drawn node grew with it, or attachments
+        // used the inflated extents, every other edge on a loop-bearing node
+        // would end in the air above its face.
+        const placed = layoutDiagram(ok(`flowchart TD\n B -->|"in"| A\n A -->|"loop"| A`));
+        const plain = layoutDiagram(ok(`flowchart TD\n B -->|"in"| A`));
+        const a = placed.nodes.find((n) => n.id === "A");
+        const a0 = plain.nodes.find((n) => n.id === "A");
+        assert.deepEqual([a.width, a.height], [a0.width, a0.height]);
+        const into = placed.edges.find((e) => !e.selfLoop);
+        const end = into.points[into.points.length - 1];
+        assert.equal(end.y, a.y - a.height / 2, "the incoming edge ends on A's top face");
+    });
+    it("does not grow a node that has no loop", () => {
+        const withLoop = layoutDiagram(ok(`flowchart TD\n A --> B\n B -->|"loop"| B`));
+        const without = layoutDiagram(ok(`flowchart TD\n A --> B`));
+        const a = withLoop.nodes.find((n) => n.id === "A");
+        const a0 = without.nodes.find((n) => n.id === "A");
+        assert.deepEqual([a.width, a.height, a.y], [a0.width, a0.height, a0.y], "A keeps its size and its rank");
+    });
+    it("grows the cross axis, not the rank axis", () => {
+        // A TD diagram's height is the chat bubble's height. #504 reserved the
+        // loop's room along the rank axis — +50% on a two-node graph — and on
+        // the side every rank edge arrives from.
+        const withLoop = layoutDiagram(ok(`flowchart TD\n B -->|"in"| A\n A -->|"loop"| A`));
+        const without = layoutDiagram(ok(`flowchart TD\n B -->|"in"| A`));
+        assert.ok(withLoop.height <= without.height + 8, `${withLoop.height} vs ${without.height}`);
+    });
+});
+describe("two loops on one node", () => {
+    // They used to draw the same bow twice — and would have stacked their
+    // chips on top of each other. The second bows outside the first's chip.
+    it("draw as two bows with two legible chips", () => {
+        for (const dir of ["TD", "LR"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"first"| A\n A -->|"second"| A\n A --> B`));
+            const loops = placed.edges.filter((e) => e.selfLoop);
+            assert.equal(loops.length, 2);
+            assert.notDeepEqual(loops[0].points, loops[1].points, `${dir}: distinct bows`);
+            const [c0, c1] = loops.map(chipRect);
+            assert.ok(!intersects(c0, c1), `${dir}: chips ${JSON.stringify(c0)} / ${JSON.stringify(c1)}`);
+            assertInside(placed, c0, `${dir} first`);
+            assertInside(placed, c1, `${dir} second`);
+        }
+    });
+});
+describe("the Rule 30 state graph", () => {
+    // The diagram this was found on: eight states, 24 arrows, three loops.
+    const src = RULE30;
+    it("renders all three loop labels, inside the canvas, clear of every other chip", () => {
+        const r = renderDiagram(src);
+        assert.ok(r);
+        for (const l of ["00000", "10101", "01010/01011"]) {
+            assert.ok(r.svg.includes(`>${l}<`), `${l} is drawn`);
+        }
+        const placed = layoutDiagram(ok(src));
+        const loops = placed.edges.filter((e) => e.selfLoop);
+        assert.equal(loops.length, 3);
+        const others = placed.edges.filter((e) => !e.selfLoop && e.labelPos).map(chipRect);
+        for (const loop of loops) {
+            const chip = chipRect(loop);
+            assertInside(placed, chip, loop.from);
+            for (const o of others) {
+                assert.ok(!intersects(chip, o), `${loop.from}'s chip overlaps another label`);
+            }
+        }
+    });
+});
+// The finding that moved the loops (claude-djdja7g6:13): the checks above hold a
+// loop's chip against other *chips*, and the Rule 30 test passed while three
+// edges ran straight through 101's label. A chip an edge passes through reads
+// as that edge's label, so what has to hold is chip against *path*.
+describe("no edge runs through a loop's label", () => {
+    /** Points along an edge as drawn — `curveBasis`, sampled. */
+    function along(points) {
+        if (points.length < 3)
+            return points;
+        // B-spline, uniform, clamped the way d3's curveBasis is: sample densely.
+        const p = [points[0], points[0], ...points, points[points.length - 1], points[points.length - 1]];
+        const out = [];
+        for (let i = 0; i + 3 < p.length; i++) {
+            for (let s = 0; s <= 20; s++) {
+                const t = s / 20, t2 = t * t, t3 = t2 * t;
+                const b0 = (1 - 3 * t + 3 * t2 - t3) / 6, b1 = (4 - 6 * t2 + 3 * t3) / 6;
+                const b2 = (1 + 3 * t + 3 * t2 - 3 * t3) / 6, b3 = t3 / 6;
+                out.push({
+                    x: b0 * p[i].x + b1 * p[i + 1].x + b2 * p[i + 2].x + b3 * p[i + 3].x,
+                    y: b0 * p[i].y + b1 * p[i + 1].y + b2 * p[i + 2].y + b3 * p[i + 3].y,
+                });
+            }
+        }
+        return out;
+    }
+    const inside = (q, r) => q.x > r.left && q.x < r.right && q.y > r.top && q.y < r.bottom;
+    function crossings(src) {
+        const placed = layoutDiagram(ok(src));
+        const out = [];
+        for (const loop of placed.edges.filter((e) => e.selfLoop && e.label)) {
+            const chip = chipRect(loop);
+            for (const o of placed.edges) {
+                if (o === loop)
+                    continue;
+                if (along(o.points).some((q) => inside(q, chip)))
+                    out.push(`${o.from}→${o.to} crosses ${loop.from}'s loop label`);
+            }
+            for (const n of placed.nodes) {
+                const r = { left: n.x - n.width / 2, right: n.x + n.width / 2, top: n.y - n.height / 2, bottom: n.y + n.height / 2 };
+                if (intersects(chip, r))
+                    out.push(`${loop.from}'s loop label covers node ${n.id}`);
+            }
+        }
+        return out;
+    }
+    it("the smallest case: an edge into a node with a labelled loop", () => {
+        for (const dir of ["TD", "BT", "LR", "RL"]) {
+            assert.deepEqual(crossings(`flowchart ${dir}\n B --> A\n A -->|"loop"| A`), [], dir);
+            assert.deepEqual(crossings(`flowchart ${dir}\n A -->|"loop"| A\n A --> C\n B --> A`), [], `${dir}, in and out`);
+        }
+    });
+    it("two loop-bearing nodes side by side, with labels wider than the nodes", () => {
+        for (const dir of ["TD", "LR"]) {
+            assert.deepEqual(crossings(`flowchart ${dir}\n R --> A\n R --> B\n A -->|"a rather long loop label"| A\n B -->|"another long loop label"| B`), [], dir);
+        }
+    });
+    it("stacked loops with labels of different widths, in every direction", () => {
+        // #504 stacked chips by height in every direction, so beside the node a
+        // wider first label ran into the second: "a lon[second]abel".
+        for (const dir of ["TD", "BT", "LR", "RL"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"a longer first label"| A\n A -->|"second"| A\n A -->|"3"| A\n B --> A`));
+            const chips = placed.edges.filter((e) => e.selfLoop).map(chipRect);
+            for (let i = 0; i < chips.length; i++) {
+                assertInside(placed, chips[i], `${dir} loop ${i}`);
+                for (let j = i + 1; j < chips.length; j++) {
+                    assert.ok(!intersects(chips[i], chips[j]), `${dir}: loop chips ${i} and ${j} overlap`);
+                }
+            }
+            assert.deepEqual(crossings(`flowchart ${dir}\n A -->|"a longer first label"| A\n A -->|"second"| A\n A -->|"3"| A\n B --> A`), [], dir);
+        }
+    });
+    it("a loop without a label draws, reserves its bow, and places nothing", () => {
+        const placed = layoutDiagram(ok(`flowchart TD\n B --> A\n A --> A`));
+        const loop = loopOf(placed, "A");
+        assert.equal(loop.labelPos, undefined);
+        const a = placed.nodes.find((n) => n.id === "A");
+        assert.ok(loop.points.every((q) => q.x >= a.x + a.width / 2 - 1e-9), "the bow is off the right face");
+        assert.ok(Math.max(...loop.points.map((q) => q.x)) <= placed.width, "and inside the canvas");
+    });
+    it("an edge fanning into a wide-labelled loop node, in every direction", () => {
+        // Dagre ends each edge on the node's inflated box; pulled back onto the
+        // drawn face, the last leg of a steep edge used to cut the corner of a
+        // chip wider than its node (LR/RL: claude-w6c1k8h4:7).
+        for (const dir of ["TD", "BT", "LR", "RL"]) {
+            assert.deepEqual(crossings(`flowchart ${dir}\n A --> X\n B --> X\n C --> X\n X -->|"a rather long loop label"| X`), [], `${dir}, fan-in`);
+            assert.deepEqual(crossings(`flowchart ${dir}\n X -->|"a rather long loop label"| X\n X --> A\n X --> B\n X --> C`), [], `${dir}, fan-out`);
+        }
+    });
+    it("each label sits just outside its own arc, stacked or not", () => {
+        // The apex is 23/24 of the control depth, not 5/6: with the wrong ratio an
+        // outer arc of a stack ran through its own label.
+        for (const dir of ["TD", "BT", "LR", "RL"]) {
+            const placed = layoutDiagram(ok(`flowchart ${dir}\n A -->|"one"| A\n A -->|"a middling label"| A\n A -->|"3"| A\n B --> A`));
+            const a = placed.nodes.find((n) => n.id === "A");
+            const vertical = dir === "LR" || dir === "RL"; // loops hang below
+            for (const loop of placed.edges.filter((e) => e.selfLoop)) {
+                const chip = chipRect(loop);
+                const arc = along(loop.points);
+                assert.ok(!arc.some((q) => inside(q, chip)), `${dir}: "${loop.label}" is crossed by its own arc`);
+                const apex = vertical
+                    ? Math.max(...arc.map((q) => q.y)) - (a.y + a.height / 2)
+                    : Math.max(...arc.map((q) => q.x)) - (a.x + a.width / 2);
+                const near = vertical ? chip.top - (a.y + a.height / 2) : chip.left - (a.x + a.width / 2);
+                assert.ok(near - apex >= 1 && near - apex <= 6, `${dir}: "${loop.label}" sits ${(near - apex).toFixed(1)}px past its apex`);
+            }
+        }
+    });
+    it("the Rule 30 board", () => {
+        const src = RULE30;
+        assert.deepEqual(crossings(src), []);
+    });
+});
+//# sourceMappingURL=diagram-self-loop-labels.test.js.map

package/dist/test/embedder.test.js

@@ -0,0 +1,84 @@
+import { after, describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { createEmbedder, l2Normalize, meanPool, VECTOR_DIM, } from "../memory/embedder.js";
+import { EMBEDDING_GOLDEN } from "./fixtures/embedding-golden.js";
+/** Cosine of two unit-ish vectors. */
+function cosine(a, b) {
+    let dot = 0;
+    for (let i = 0; i < a.length; i++)
+        dot += a[i] * b[i];
+    return dot;
+}
+describe("pooling math", () => {
+    it("mean-pools only the unmasked positions", () => {
+        // Two positions of a 2-dim hidden state; the second is padding.
+        const hidden = Float32Array.from([1, 2, 100, 200]);
+        const pooled = meanPool(hidden, 0, 2, 2, [1, 0]);
+        assert.deepEqual(Array.from(pooled), [1, 2]);
+    });
+    it("averages rather than sums, so sequence length doesn't scale the vector", () => {
+        const hidden = Float32Array.from([1, 1, 3, 3]);
+        assert.deepEqual(Array.from(meanPool(hidden, 0, 2, 2, [1, 1])), [2, 2]);
+    });
+    it("reads the right sequence out of a batch via its base offset", () => {
+        // [batch=2, seq=1, dim=2]
+        const hidden = Float32Array.from([1, 2, 30, 40]);
+        assert.deepEqual(Array.from(meanPool(hidden, 2, 1, 2, [1])), [30, 40]);
+    });
+    it("normalizes to unit length", () => {
+        const v = Float32Array.from([3, 4]);
+        l2Normalize(v);
+        assert.ok(Math.abs(Math.hypot(v[0], v[1]) - 1) < 1e-6);
+        assert.ok(Math.abs(v[0] - 0.6) < 1e-6);
+    });
+});
+const modelPath = join(process.env.BRANE_MODEL_CACHE || join(homedir(), ".brane", "models"), "Xenova", "bge-small-en-v1.5", "onnx", "model.onnx");
+const haveModel = existsSync(modelPath);
+describe("embedder", { skip: haveModel ? false : `no model at ${modelPath}` }, () => {
+    let embedder = null;
+    const get = async () => (embedder ??= await createEmbedder());
+    after(async () => {
+        await embedder?.dispose();
+    });
+    it("reproduces the vectors transformers.js produced", async () => {
+        // The reason this file exists. `memory_vec` already holds vectors from the
+        // old pipeline, so drift here silently degrades search rather than failing.
+        const e = await get();
+        const vectors = await e.embed(EMBEDDING_GOLDEN.map((g) => g.text));
+        for (let i = 0; i < EMBEDDING_GOLDEN.length; i++) {
+            const sim = cosine(vectors[i], EMBEDDING_GOLDEN[i].vector);
+            assert.ok(sim > 0.99999, `cosine ${sim} for ${JSON.stringify(EMBEDDING_GOLDEN[i].text.slice(0, 40))}`);
+        }
+    });
+    it("returns normalized vectors of the schema's width", async () => {
+        const [v] = await (await get()).embed(["a sentence"]);
+        assert.equal(v.length, VECTOR_DIM);
+        let norm = 0;
+        for (const x of v)
+            norm += x * x;
+        assert.ok(Math.abs(Math.sqrt(norm) - 1) < 1e-5);
+    });
+    it("embeds a text identically whether batched or alone", async () => {
+        // Padding leaks into the vector if the attention mask is ignored, and the
+        // symptom is subtle: results that shift depending on batch composition.
+        const e = await get();
+        const [alone] = await e.embed(["short"]);
+        const batched = await e.embed(["short", "a considerably longer neighbour sentence"]);
+        assert.ok(cosine(alone, batched[0]) > 0.99999);
+    });
+    it("places related text nearer than unrelated text", async () => {
+        const [a, b, c] = await (await get()).embed([
+            "the daemon streams terminal output over a websocket",
+            "tmux panes are mirrored to the browser in real time",
+            "sourdough needs a long cold fermentation",
+        ]);
+        assert.ok(cosine(a, b) > cosine(a, c));
+    });
+    it("returns nothing for an empty batch without loading anything", async () => {
+        assert.deepEqual(await (await get()).embed([]), []);
+    });
+});
+//# sourceMappingURL=embedder.test.js.map

package/dist/test/events.test.js

@@ -0,0 +1,123 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { createTestDb } from "./helpers.js";
+import { appendEvent, readEventsSince, getMaxSeq } from "../db/events.js";
+describe("events", () => {
+    it("appends events with auto-incrementing seq", () => {
+        const db = createTestDb();
+        const e1 = appendEvent(db, "test-narrative", "narration", { content: "hello" });
+        const e2 = appendEvent(db, "test-narrative", "narration", { content: "world" });
+        assert.equal(e1.seq, 1);
+        assert.equal(e2.seq, 2);
+        assert.equal(e1.content, "hello");
+        assert.equal(e2.content, "world");
+    });
+    it("sequences are per-narrative", () => {
+        const db = createTestDb();
+        appendEvent(db, "narrative-a", "narration", { content: "a1" });
+        appendEvent(db, "narrative-a", "narration", { content: "a2" });
+        const b1 = appendEvent(db, "narrative-b", "narration", { content: "b1" });
+        assert.equal(b1.seq, 1); // starts at 1, not 3
+    });
+    it("readEventsSince returns events after cursor", () => {
+        const db = createTestDb();
+        appendEvent(db, "n1", "narration", { content: "one" });
+        appendEvent(db, "n1", "narration", { content: "two" });
+        appendEvent(db, "n1", "narration", { content: "three" });
+        const events = readEventsSince(db, "n1", 1);
+        assert.equal(events.length, 2);
+        assert.equal(events[0].content, "two");
+        assert.equal(events[1].content, "three");
+    });
+    it("readEventsSince with cursor 0 returns all events", () => {
+        const db = createTestDb();
+        appendEvent(db, "n1", "narration", { content: "one" });
+        appendEvent(db, "n1", "narration", { content: "two" });
+        const events = readEventsSince(db, "n1", 0);
+        assert.equal(events.length, 2);
+    });
+    it("readEventsSince respects limit", () => {
+        const db = createTestDb();
+        for (let i = 0; i < 10; i++) {
+            appendEvent(db, "n1", "narration", { content: `msg-${i}` });
+        }
+        const events = readEventsSince(db, "n1", 0, 3);
+        assert.equal(events.length, 3);
+        assert.equal(events[0].content, "msg-0");
+        assert.equal(events[2].content, "msg-2");
+    });
+    it("readEventsSince returns empty for unknown narrative", () => {
+        const db = createTestDb();
+        const events = readEventsSince(db, "nonexistent", 0);
+        assert.equal(events.length, 0);
+    });
+    it("getMaxSeq returns 0 for empty narrative", () => {
+        const db = createTestDb();
+        assert.equal(getMaxSeq(db, "nonexistent"), 0);
+    });
+    it("getMaxSeq returns highest seq", () => {
+        const db = createTestDb();
+        appendEvent(db, "n1", "narration", { content: "one" });
+        appendEvent(db, "n1", "narration", { content: "two" });
+        appendEvent(db, "n1", "narration", { content: "three" });
+        assert.equal(getMaxSeq(db, "n1"), 3);
+    });
+    it("stores and retrieves back-references as parsed arrays", () => {
+        const db = createTestDb();
+        const e = appendEvent(db, "n1", "narration", {
+            content: "reply",
+            re: [1, "other-narrative:5"],
+        });
+        assert.deepEqual(e.re, [1, "other-narrative:5"]);
+        const events = readEventsSince(db, "n1", 0);
+        assert.deepEqual(events[0].re, [1, "other-narrative:5"]);
+    });
+    it("source field works for all event types", () => {
+        const db = createTestDb();
+        const opSignal = appendEvent(db, "n1", "human_signal", {
+            content: "incoming",
+            source: "mobile",
+        });
+        assert.equal(opSignal.source, "mobile");
+        assert.equal(opSignal.type, "human_signal");
+        const agentMsg = appendEvent(db, "n1", "agent_signal", {
+            content: "delegation result",
+            source: "claude-abc",
+        });
+        assert.equal(agentMsg.source, "claude-abc");
+        assert.equal(agentMsg.type, "agent_signal");
+        const narration = appendEvent(db, "n1", "narration", {
+            content: "thinking",
+            source: "claude-xyz",
+        });
+        assert.equal(narration.source, "claude-xyz");
+        assert.equal(narration.type, "narration");
+    });
+    it("stores payloads as parsed arrays", () => {
+        const db = createTestDb();
+        const e = appendEvent(db, "n1", "narration", {
+            content: "with files",
+            payloads: ["path/to/file.png", "path/to/doc.md"],
+        });
+        assert.deepEqual(e.payloads, ["path/to/file.png", "path/to/doc.md"]);
+    });
+    it("omits undefined optional fields", () => {
+        const db = createTestDb();
+        const e = appendEvent(db, "n1", "narration", { content: "minimal" });
+        assert.equal(e.seq, 1);
+        assert.equal(typeof e.time, "number");
+        assert.equal(e.type, "narration");
+        assert.equal(e.content, "minimal");
+        assert.equal(e.content_type, undefined);
+        assert.equal(e.source, undefined);
+        assert.equal(e.re, undefined);
+        assert.equal(e.payloads, undefined);
+        assert.equal("narrative_id" in e, false);
+        assert.equal("event_type" in e, false);
+        assert.equal("timestamp_ms" in e, false);
+        assert.equal("sender" in e, false);
+        assert.equal("speaker" in e, false);
+        assert.equal("intensity" in e, false);
+    });
+});
+//# sourceMappingURL=events.test.js.map

package/dist/test/export-selection.test.js

@@ -0,0 +1,102 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { formatSeqModeParam, formatSeqParam, parseSeqModeParam, parseSeqParam, exportFileName, seqDigest, } from "../shared/export-selection.js";
+describe("formatSeqParam", () => {
+    it("writes ascending, deduped decimal seqs", () => {
+        assert.equal(formatSeqParam([19, 12, 14, 12]), "12,14,19");
+    });
+    it("is null when there is nothing to send", () => {
+        assert.equal(formatSeqParam([]), null);
+        assert.equal(formatSeqParam(null), null);
+        assert.equal(formatSeqParam(undefined), null);
+    });
+    it("drops values that are not seqs", () => {
+        // seq numbering starts at 1, so 0 and negatives name nothing.
+        assert.equal(formatSeqParam([0, -3, 1.5, 7]), "7");
+        assert.equal(formatSeqParam([0]), null);
+    });
+    it("takes a Set, which is the shape the chat keeps its selection in", () => {
+        assert.equal(formatSeqParam(new Set([3, 1, 2])), "1,2,3");
+    });
+});
+describe("parseSeqParam", () => {
+    it("reads what formatSeqParam writes", () => {
+        const seqs = [4, 17, 23];
+        assert.deepEqual(parseSeqParam(formatSeqParam(seqs)), seqs);
+    });
+    it("is empty for an absent or blank parameter", () => {
+        assert.deepEqual(parseSeqParam(null), []);
+        assert.deepEqual(parseSeqParam(undefined), []);
+        assert.deepEqual(parseSeqParam(""), []);
+        assert.deepEqual(parseSeqParam(",,"), []);
+    });
+    it("ignores junk rather than refusing the export", () => {
+        assert.deepEqual(parseSeqParam("3,abc,5"), [3, 5]);
+        assert.deepEqual(parseSeqParam("12abc"), [], "a partial number is not a seq");
+        assert.deepEqual(parseSeqParam("-1,0,2.5,2"), [2]);
+        assert.deepEqual(parseSeqParam("nonsense"), [], "unreadable means no selection, which means a full export");
+    });
+    it("sorts and dedupes whatever order it arrives in", () => {
+        assert.deepEqual(parseSeqParam("9, 2 ,9,2,5"), [2, 5, 9]);
+    });
+    it("reads plain decimal digits only — `Number` accepts more than a seq", () => {
+        // Each of these is a number to `Number()` and a message nobody picked.
+        assert.deepEqual(parseSeqParam("1e2"), []);
+        assert.deepEqual(parseSeqParam("0x10"), []);
+        assert.deepEqual(parseSeqParam("+4"), []);
+        assert.deepEqual(parseSeqParam("5.0"), []);
+        assert.deepEqual(parseSeqParam("0b11,0o7"), []);
+        assert.deepEqual(parseSeqParam("9007199254740993"), [], "past MAX_SAFE_INTEGER, Number() rounds to a different seq");
+        assert.deepEqual(parseSeqParam("007"), [7], "leading zeros are still decimal");
+        assert.deepEqual(parseSeqParam("9007199254740991"), [9007199254740991], "MAX_SAFE_INTEGER itself is a seq");
+        assert.deepEqual(parseSeqParam("1e2,3"), [3], "a rejected part drops alone; the rest of the list stands");
+    });
+});
+describe("exportFileName", () => {
+    it("a full export keeps the name sibling exports link to", () => {
+        assert.equal(exportFileName("claude-aaaaaaaa"), "claude-aaaaaaaa.html");
+        assert.equal(exportFileName("claude-aaaaaaaa", null), "claude-aaaaaaaa.html");
+    });
+    it("an excerpt carries its count and a digest of its seqs", () => {
+        assert.match(exportFileName("claude-aaaaaaaa", { seqs: [2, 5, 9], total: 47 }), /^claude-aaaaaaaa\.3-of-47\.[0-9a-f]{6}\.html$/);
+    });
+    it("two excerpts of the same size are two names — `only` and `except` of a half-selection included", () => {
+        // seqs [1,4] of four messages: `only` exports 1,4 and `except` exports 2,3.
+        // Both are 2-of-4; the count alone gave them one name.
+        const only = exportFileName("claude-aaaaaaaa", { seqs: [1, 4], total: 4 });
+        const except = exportFileName("claude-aaaaaaaa", { seqs: [2, 3], total: 4 });
+        assert.notEqual(only, except);
+    });
+    it("the digest depends on the set, not the order it was tapped in", () => {
+        assert.equal(seqDigest([9, 2, 5]), seqDigest([2, 5, 9]));
+        assert.notEqual(seqDigest([1, 23]), seqDigest([12, 3]), "the separator keeps 1,23 and 12,3 apart");
+    });
+});
+describe("the selection's mode", () => {
+    it("reads what it writes", () => {
+        assert.equal(parseSeqModeParam(formatSeqModeParam("except")), "except");
+        assert.equal(parseSeqModeParam(formatSeqModeParam("only")), "only");
+    });
+    it("leaves the default off the URL", () => {
+        // An ordinary excerpt's link stays the one brane built before a complement
+        // was possible — the parameter appears only when it changes something.
+        assert.equal(formatSeqModeParam("only"), null);
+        assert.equal(formatSeqModeParam(null), null);
+        assert.equal(formatSeqModeParam(undefined), null);
+        assert.equal(formatSeqModeParam("except"), "except");
+    });
+    it("inverts an export only on the exact word", () => {
+        // The tolerance runs one way on purpose: a garbled parameter must never
+        // hand the operator the complement of the document they asked for.
+        assert.equal(parseSeqModeParam("except"), "except");
+        assert.equal(parseSeqModeParam(" except "), "except");
+        for (const junk of ["Except", "EXCEPT", "exclude", "excluded", "!", "1", "true", "", " "]) {
+            assert.equal(parseSeqModeParam(junk), "only", `${JSON.stringify(junk)} is not "except"`);
+        }
+    });
+    it("is `only` when absent, which is what every export was", () => {
+        assert.equal(parseSeqModeParam(null), "only");
+        assert.equal(parseSeqModeParam(undefined), "only");
+    });
+});
+//# sourceMappingURL=export-selection.test.js.map