@kontourai/flow-agents 3.12.0 → 4.0.0

package/src/cli/narrative-projection.test.mjs

@@ -0,0 +1,236 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  NarrativeProjectionError,
+  parseSourceId,
+  projectRuntimeNarrative,
+  snapshotNarrative,
+  stableStringify,
+  validateNarrativeRuntimeProjection,
+} from "../../build/src/index.js";
+
+const NOW = "2026-07-14T15:00:00.000Z";
+const PROJECTED_AT = "2026-07-14T16:00:00.000Z";
+const compiler = { name: "projection-test", version: "1", policy_hash: "policy" };
+const captureCompleteness = {
+  channels: { full: "active" },
+  known_gaps: [{ class: "mcp_non_native_tools", ref: "flow-agents#492", note: "MCP payload capture is incomplete." }],
+};
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const sha8 = (bytes) => sha256(bytes).slice(0, 8);
+
+function writeJsonLines(file, records) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const lines = records.map((record) => JSON.stringify(record));
+  fs.writeFileSync(file, `${lines.join("\n")}\n`);
+  return lines;
+}
+
+function constructedNarrative({ includeTrust = false, fileOnly = false, timeoutWithoutDuration = false, spacedFileName = false } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-projection-"));
+  const narrativeDir = path.join(root, "artifacts", "narrative", "runtime-test");
+  const telemetryDir = path.join(root, "telemetry");
+  const sessionDir = path.join(root, "runtime-session");
+  const flowRoot = path.join(root, "flow");
+  const repoRoot = path.join(root, "repo");
+  fs.mkdirSync(repoRoot, { recursive: true });
+
+  const requests = [];
+  if (!fileOnly) {
+    const timeoutTool = timeoutWithoutDuration
+      ? { name: "execute_bash", command: "npm test" }
+      : { name: "execute_bash", command: "npm test", timeout_ms: 5000 };
+    const telemetry = [
+      { session_id: "runtime-session", event_id: "turn-explicit", event_type: "turn.user", hook: { turn_id: "turn-1" } },
+      { session_id: "runtime-session", event_id: "tool-timeout", event_type: "tool.result", hook: { turn_id: "turn-1" }, tool: timeoutTool, timed_out: true },
+      { session_id: "runtime-session", event_id: "turn-derived", event_type: "turn.user" },
+      { session_id: "runtime-session", event_id: "session-end", event_type: "session.end" },
+    ];
+    const telemetryLines = writeJsonLines(path.join(telemetryDir, "full.jsonl"), telemetry);
+    const telemetryIds = telemetry.map((record, index) => `fa1:telemetry:full/runtime-session:${record.event_id}/${sha8(Buffer.from(telemetryLines[index]))}`);
+
+    const flowState = { run_id: "run-test", session_id: "runtime-session", status: "active", step: "execute", gate: "tests-evidence", transitions: [] };
+    const flowBytes = Buffer.from(JSON.stringify(flowState));
+    fs.mkdirSync(path.join(flowRoot, "runs", "run-test"), { recursive: true });
+    fs.writeFileSync(path.join(flowRoot, "runs", "run-test", "state.json"), flowBytes);
+
+    const commandRecords = [
+      { command: "npm test", result: "fail", exitCode: 1 },
+      { command: "npm test", result: "pass", exitCode: 0 },
+    ];
+    const commandLines = writeJsonLines(path.join(sessionDir, "command-log.jsonl"), commandRecords);
+
+    const delegation = { kind: "delegation", target: "leaf-worker", task: "nested fixture" };
+    const [delegationLine] = writeJsonLines(path.join(sessionDir, "agents", "nested-worker", "events.jsonl"), [delegation]);
+
+    requests.push(
+      { source: parseSourceId(telemetryIds[0]), roots: { telemetryDir } },
+      { source: parseSourceId(telemetryIds[1]), roots: { telemetryDir } },
+      { source: parseSourceId(`fa1:flow-state:run-test:state/${sha8(flowBytes)}`), roots: { flowRoot } },
+      { source: parseSourceId(`fa1:delegation:runtime-session/nested-worker:0/${sha8(Buffer.from(delegationLine))}`), roots: { sessionDir } },
+      { source: parseSourceId(telemetryIds[2]), roots: { telemetryDir } },
+      { source: parseSourceId(telemetryIds[3]), roots: { telemetryDir } },
+      { source: parseSourceId(`fa1:cmdlog:runtime-session:line-1/${sha8(Buffer.from(commandLines[0]))}`), roots: { sessionDir } },
+      { source: parseSourceId(`fa1:cmdlog:runtime-session:line-2/${sha8(Buffer.from(commandLines[1]))}`), roots: { sessionDir } },
+    );
+  }
+
+  const createdName = spacedFileName ? "created file.txt" : "created.txt";
+  const created = Buffer.from(JSON.stringify({ kind: "created-file", path: createdName }));
+  fs.writeFileSync(path.join(repoRoot, createdName), created);
+  requests.push(
+    { source: parseSourceId(`fa1:file:${encodeURIComponent(createdName)}:${sha256(created)}`), roots: { repoRoot } },
+    { source: parseSourceId(`fa1:file:missing.txt:${"a".repeat(64)}`), roots: { repoRoot } },
+  );
+
+  if (includeTrust) {
+    const trust = Buffer.from(JSON.stringify({ schema_version: "1.0", claims: [{ id: "uninterpreted", status: "accepted", summary: "coverage probe" }], evidence: [] }));
+    fs.writeFileSync(path.join(sessionDir, "trust.bundle"), trust);
+    requests.push({
+      source: parseSourceId(`fa1:trust-claim:runtime-session/${sha8(trust)}:uninterpreted`),
+      roots: { sessionDir },
+    });
+  }
+
+  const result = snapshotNarrative({
+    narrativeDir,
+    narrativeId: "runtime-test",
+    requests,
+    redactionFields: [],
+    compiler,
+    captureCompleteness,
+  }, { now: () => NOW });
+  return { root, narrativeDir, manifest: result.manifest };
+}
+
+test("constructed snapshot projects the complete runtime account deterministically", () => {
+  const { narrativeDir } = constructedNarrative();
+  const first = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const second = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const bytes = stableStringify(first);
+  assert.equal(bytes, stableStringify(second));
+  assert.deepEqual(validateNarrativeRuntimeProjection(first), []);
+  assert.equal(first.coverage.sources, 10);
+  assert.equal(first.coverage.cited, 10);
+  assert.equal(first.coverage.unavailable, 1);
+  assert.ok(first.turns.some((turn) => turn.turnId === "turn-1"));
+  assert.ok(first.turns.some((turn) => !("turnId" in turn)));
+  assert.ok(first.turns.some((turn) => turn.purpose?.step === "execute" && turn.purpose?.gate === "tests-evidence"));
+  assert.ok(first.turns.every((turn) => turn.known_gap_refs.includes("flow-agents#492")));
+  const statements = [...first.turns.flatMap((turn) => turn.statements), ...first.document_statements];
+  assert.ok(statements.some((statement) => statement.proposition.includes("was retried across 2 attempts")));
+  assert.ok(statements.some((statement) => statement.proposition.includes("5000 ms timeout")));
+  assert.ok(statements.some((statement) => statement.proposition.includes("classified as a no-op")));
+  assert.ok(statements.some((statement) => statement.actor === "unattributed" && statement.proposition.includes("delegated")));
+  assert.ok(statements.some((statement) => statement.proposition.includes("`created.txt`")));
+  assert.ok(statements.some((statement) => statement.proposition.includes("unavailable because not_captured")));
+});
+
+test("project CLI validates and emits stable JSON through --json", () => {
+  const { narrativeDir } = constructedNarrative();
+  const run = spawnSync(process.execPath, [
+    path.resolve("build/src/cli.js"), "narrative-sources", "project",
+    "--narrative-dir", narrativeDir, "--json", "--projected-at", PROJECTED_AT,
+  ], { encoding: "utf8" });
+  assert.equal(run.status, 0, run.stderr);
+  const projected = JSON.parse(run.stdout);
+  assert.deepEqual(validateNarrativeRuntimeProjection(projected), []);
+  assert.equal(run.stdout, `${stableStringify(projected)}\n`);
+});
+
+test("projection schema enforces the observed/derived rule iff", () => {
+  const { narrativeDir } = constructedNarrative();
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const observed = structuredClone(projection);
+  const observedStatement = [...observed.turns.flatMap((turn) => turn.statements), ...observed.document_statements]
+    .find((statement) => statement.class === "observed");
+  observedStatement.rule = { id: "forbidden", version: "v1", inputs: observedStatement.source_refs };
+  assert.ok(validateNarrativeRuntimeProjection(observed).some((issue) => issue.message.includes("exactly one")));
+
+  const derived = structuredClone(projection);
+  const derivedStatement = [...derived.turns.flatMap((turn) => turn.statements), ...derived.document_statements]
+    .find((statement) => statement.class === "deterministic_derived");
+  delete derivedStatement.rule;
+  assert.ok(validateNarrativeRuntimeProjection(derived).some((issue) => issue.message.includes("exactly one")));
+});
+
+test("resolved source without an interpreter fails the typed coverage check", () => {
+  const { narrativeDir } = constructedNarrative({ includeTrust: true });
+  assert.throws(
+    () => projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT }),
+    (error) => error instanceof NarrativeProjectionError && error.code === "coverage_gap",
+  );
+});
+
+test("malformed JSON inside an integrity-valid snapshot fails with a typed error", () => {
+  const { narrativeDir, manifest } = constructedNarrative({ fileOnly: true });
+  const entry = manifest.sources.find((source) => source.status === "snapshotted");
+  assert.ok(entry);
+  const malformed = Buffer.from("{");
+  const malformedSha = sha256(malformed);
+  fs.rmSync(path.join(narrativeDir, "sources", entry.sha256));
+  fs.writeFileSync(path.join(narrativeDir, "sources", malformedSha), malformed);
+  const manifestPath = path.join(narrativeDir, "source-manifest.json");
+  const stored = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+  const storedEntry = stored.sources.find((source) => source.source_id === entry.source_id);
+  storedEntry.sha256 = malformedSha;
+  storedEntry.bytes = malformed.length;
+  fs.writeFileSync(manifestPath, `${JSON.stringify(stored, null, 2)}\n`);
+  assert.throws(
+    () => projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT }),
+    (error) => error instanceof NarrativeProjectionError && error.code === "malformed_snapshot",
+  );
+});
+
+test("M2: stableStringify emits lexically sorted keys at every level (JSON.stringify would fail this)", () => {
+  const { narrativeDir } = constructedNarrative();
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const walk = (value, where) => {
+    if (Array.isArray(value)) { value.forEach((item, i) => walk(item, `${where}[${i}]`)); return; }
+    if (value && typeof value === "object") {
+      const keys = Object.keys(value);
+      assert.deepEqual(keys, [...keys].sort(), `unsorted keys at ${where}`);
+      keys.forEach((key) => walk(value[key], `${where}.${key}`));
+    }
+  };
+  walk(JSON.parse(stableStringify(projection)), "$");
+});
+
+test("H2b: no-op classification never coexists with commands, delegations, or created files in the same turn", () => {
+  const { narrativeDir } = constructedNarrative();
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const activityRules = (turn) => turn.statements.filter((s) =>
+    s.proposition.startsWith("Command `") || s.proposition.includes("delegated work") || s.proposition.includes("was observed to be created"));
+  for (const turn of projection.turns) {
+    const noOp = turn.statements.some((s) => s.rule?.id === "no-op-turn");
+    if (noOp) assert.deepEqual(activityRules(turn).map((s) => s.proposition), [],
+      `turn ${turn.ordinal} is no-op yet carries activity statements`);
+  }
+  // A turn consisting solely of tool events (read-only) IS no-op-classified.
+  const readOnly = projection.turns.filter((turn) =>
+    turn.statements.length > 0 && activityRules(turn).length === 0 && turn.ordinal !== -1);
+  assert.ok(readOnly.some((turn) => turn.statements.some((s) => s.rule?.id === "no-op-turn")),
+    "expected a read-only turn to be no-op-classified");
+});
+
+test("H3 regression: space-bearing file paths are quoted free text, not rejected identifiers", () => {
+  const { narrativeDir } = constructedNarrative({ spacedFileName: true });
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const all = [...projection.turns.flatMap((turn) => turn.statements), ...projection.document_statements];
+  assert.ok(all.some((s) => s.proposition.includes("`created file.txt`")), "spaced path must project quoted");
+});
+
+test("H2a: a timeout signal without a duration still yields the material timeout statement", () => {
+  const { narrativeDir } = constructedNarrative({ timeoutWithoutDuration: true });
+  const projection = projectRuntimeNarrative(narrativeDir, { projectedAt: PROJECTED_AT });
+  const all = [...projection.turns.flatMap((turn) => turn.statements), ...projection.document_statements];
+  assert.ok(all.some((s) => s.rule?.id === "timeout-detection" && s.proposition.includes("duration unknown")),
+    "material timeout fact missing despite timeout signal");
+});

package/src/cli/narrative-readers.test.mjs

@@ -0,0 +1,196 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+
+import {
+  NarrativeReaderError,
+  readAgentEventCandidate,
+  readCommandLogCandidate,
+  readFileCandidate,
+  readFlowStateCandidate,
+  readFlowTransitionCandidate,
+  readTelemetryCandidates,
+  readTranscriptCandidate,
+  readTrustCandidate,
+} from "../../build/src/narrative/readers.js";
+
+const require = createRequire(import.meta.url);
+const { CHAIN_GENESIS, computeChainHash } = require("../../scripts/lib/command-log-chain.js");
+
+function tempDir(t) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-readers-"));
+  t.after(() => fs.rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+function sha8(bytes) {
+  return sha256(bytes).slice(0, 8);
+}
+
+test("telemetry duplicate event ids are selected by content pin plus deterministic file-order ordinal", (t) => {
+  const dir = tempDir(t);
+  const currentLine = JSON.stringify({ session_id: "s1", event_id: "duplicate", value: "current" });
+  const otherSession = JSON.stringify({ session_id: "other", event_id: "duplicate", value: "ignore" });
+  const rotatedLine = JSON.stringify({ session_id: "s1", event_id: "duplicate", value: "rotated" });
+  fs.writeFileSync(path.join(dir, "full.jsonl"), `${currentLine}\n${otherSession}\n${currentLine}\n`);
+  fs.writeFileSync(path.join(dir, "full.1.jsonl"), `${rotatedLine}\n`);
+  const currentPin = sha8(Buffer.from(currentLine));
+
+  const pinned = readTelemetryCandidates({ telemetryDir: dir, channel: "full", sessionId: "s1", eventId: "duplicate", sha8: currentPin });
+  assert.deepEqual(pinned.map((candidate) => candidate.record.value), ["current", "current"]);
+  const second = readTelemetryCandidates({ telemetryDir: dir, channel: "full", sessionId: "s1", eventId: "duplicate", sha8: currentPin, ordinal: 1 });
+  assert.equal(second[0].record.value, "current");
+  const rotated = readTelemetryCandidates({ telemetryDir: dir, channel: "full", sessionId: "s1", eventId: "duplicate", sha8: sha8(Buffer.from(rotatedLine)), ordinal: 0 });
+  assert.equal(rotated[0].record.value, "rotated");
+});
+
+test("telemetry content pin rejects rebinding when records with the same event id are reordered or replaced", (t) => {
+  const dir = tempDir(t);
+  const recordA = JSON.stringify({ session_id: "s1", event_id: "duplicate", value: "A" });
+  const recordB = JSON.stringify({ session_id: "s1", event_id: "duplicate", value: "B" });
+  fs.writeFileSync(path.join(dir, "full.jsonl"), `${recordA}\n${recordB}\n`);
+  const pinA = sha8(Buffer.from(recordA));
+
+  // Reorder: the pin still selects record A regardless of position.
+  fs.writeFileSync(path.join(dir, "full.jsonl"), `${recordB}\n${recordA}\n`);
+  const selected = readTelemetryCandidates({ telemetryDir: dir, channel: "full", sessionId: "s1", eventId: "duplicate", sha8: pinA, ordinal: 0 });
+  assert.equal(selected[0].record.value, "A");
+
+  // Replace: same event id, different content — the pin refuses to rebind.
+  fs.writeFileSync(path.join(dir, "full.jsonl"), `${recordB}\n`);
+  assert.throws(
+    () => readTelemetryCandidates({ telemetryDir: dir, channel: "full", sessionId: "s1", eventId: "duplicate", sha8: pinA }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt",
+  );
+});
+
+test("command-log reader rejects a non-capture fork sibling the canonical verifier marks broken", (t) => {
+  const sessionDir = tempDir(t);
+  const first = { command: "npm test", source: "postToolUse-capture" };
+  const firstHash = computeChainHash(CHAIN_GENESIS, first);
+  const firstLinked = { ...first, _chain: { seq: 0, prevHash: CHAIN_GENESIS, hash: firstHash } };
+  const capture = { command: "npm run build", source: "postToolUse-capture" };
+  const captureLinked = { ...capture, _chain: { seq: 1, prevHash: firstHash, hash: computeChainHash(firstHash, capture) } };
+  const forged = { command: "echo forged", source: "manual-injection" };
+  const forgedLinked = { ...forged, _chain: { seq: 1, prevHash: firstHash, hash: computeChainHash(firstHash, forged) } };
+  fs.writeFileSync(path.join(sessionDir, "command-log.jsonl"), `${JSON.stringify(firstLinked)}\n${JSON.stringify(captureLinked)}\n${JSON.stringify(forgedLinked)}\n`);
+
+  assert.throws(
+    () => readCommandLogCandidate({ sessionDir, locator: { kind: "chained", seq: 0, hash8: firstHash.slice(0, 8) } }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt" && error.message.includes("fork sibling"),
+  );
+});
+
+test("command-log reader tolerates an all-capture fork (two captures racing on one tip)", (t) => {
+  const sessionDir = tempDir(t);
+  const first = { command: "npm test", source: "postToolUse-capture" };
+  const firstHash = computeChainHash(CHAIN_GENESIS, first);
+  const firstLinked = { ...first, _chain: { seq: 0, prevHash: CHAIN_GENESIS, hash: firstHash } };
+  const raceA = { command: "npm run build", source: "postToolUse-capture" };
+  const raceALinked = { ...raceA, _chain: { seq: 1, prevHash: firstHash, hash: computeChainHash(firstHash, raceA) } };
+  const raceB = { command: "npm run lint", source: "postToolUse-capture" };
+  const raceBLinked = { ...raceB, _chain: { seq: 1, prevHash: firstHash, hash: computeChainHash(firstHash, raceB) } };
+  fs.writeFileSync(path.join(sessionDir, "command-log.jsonl"), `${JSON.stringify(firstLinked)}\n${JSON.stringify(raceALinked)}\n${JSON.stringify(raceBLinked)}\n`);
+
+  const found = readCommandLogCandidate({ sessionDir, locator: { kind: "chained", seq: 0, hash8: firstHash.slice(0, 8) } });
+  assert.equal(found.record.command, "npm test");
+});
+
+test("command-log reader verifies links with the normative command-log-chain module", (t) => {
+  const sessionDir = tempDir(t);
+  const first = { command: "npm test", source: "postToolUse-capture" };
+  const firstHash = computeChainHash(CHAIN_GENESIS, first);
+  const firstLinked = { ...first, _chain: { seq: 0, prevHash: CHAIN_GENESIS, hash: firstHash } };
+  const second = { command: "npm run build", source: "postToolUse-capture" };
+  const secondHash = computeChainHash(firstHash, second);
+  const secondLinked = { ...second, _chain: { seq: 1, prevHash: firstHash, hash: secondHash } };
+  const file = path.join(sessionDir, "command-log.jsonl");
+  fs.writeFileSync(file, `${JSON.stringify(firstLinked)}\n${JSON.stringify(secondLinked)}\n`);
+
+  const found = readCommandLogCandidate({ sessionDir, locator: { kind: "chained", seq: 1, hash8: secondHash.slice(0, 8) } });
+  assert.equal(found.record.command, "npm run build");
+
+  secondLinked.command = "tampered";
+  fs.writeFileSync(file, `${JSON.stringify(firstLinked)}\n${JSON.stringify(secondLinked)}\n`);
+  assert.throws(
+    () => readCommandLogCandidate({ sessionDir, locator: { kind: "chained", seq: 1, hash8: secondHash.slice(0, 8) } }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt",
+  );
+});
+
+test("legacy command-log and agent-event readers enforce raw line pins", (t) => {
+  const sessionDir = tempDir(t);
+  const legacy = Buffer.from(JSON.stringify({ command: "legacy" }));
+  fs.writeFileSync(path.join(sessionDir, "command-log.jsonl"), Buffer.concat([legacy, Buffer.from("\n")]));
+  assert.equal(readCommandLogCandidate({ sessionDir, locator: { kind: "legacy", line: 1, sha8: sha8(legacy) } }).record.command, "legacy");
+
+  const agentDir = path.join(sessionDir, "agents", "agent-1");
+  fs.mkdirSync(agentDir, { recursive: true });
+  const event = Buffer.from(JSON.stringify({ kind: "delegation", summary: "work" }));
+  fs.writeFileSync(path.join(agentDir, "events.jsonl"), Buffer.concat([event, Buffer.from("\n")]));
+  assert.equal(readAgentEventCandidate({ sessionDir, agentId: "agent-1", lineIndex: 0, sha8: sha8(event), delegation: true }).record.summary, "work");
+  assert.throws(
+    () => readAgentEventCandidate({ sessionDir, agentId: "agent-1", lineIndex: 0, sha8: "00000000" }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt",
+  );
+});
+
+test("trust, Flow state, transitions, transcripts, and repository files return pinned bytes", (t) => {
+  const root = tempDir(t);
+  const sessionDir = path.join(root, "session");
+  fs.mkdirSync(sessionDir);
+  const bundle = Buffer.from(JSON.stringify({ claims: [{ id: "c1", value: "pass" }], evidence: [{ id: "e1", passing: true }] }));
+  fs.writeFileSync(path.join(sessionDir, "trust.bundle"), bundle);
+  assert.equal(readTrustCandidate({ sessionDir, bundleSha8: sha8(bundle), id: "e1", kind: "evidence" }).record.passing, true);
+
+  const flowRoot = path.join(root, "flow");
+  const runDir = path.join(flowRoot, "runs", "run-1");
+  fs.mkdirSync(runDir, { recursive: true });
+  const transition = { from_step: "a", to_step: "b" };
+  const state = Buffer.from(JSON.stringify({ run_id: "run-1", transitions: [transition] }));
+  fs.writeFileSync(path.join(runDir, "state.json"), state);
+  assert.equal(readFlowStateCandidate({ flowRoot, runId: "run-1", sha8: sha8(state) }).record.run_id, "run-1");
+  assert.equal(readFlowTransitionCandidate({ flowRoot, runId: "run-1", index: 0, sha8: sha8(Buffer.from(JSON.stringify(transition))) }).record.to_step, "b");
+
+  const transcript = path.join(root, "transcript.jsonl");
+  fs.writeFileSync(transcript, "0123456789");
+  assert.equal(readTranscriptCandidate({ absolutePath: transcript, byteStart: 2, byteEnd: 6 }).toString(), "2345");
+
+  const repoFile = path.join(root, "source.txt");
+  const fileBytes = Buffer.from("source bytes\n");
+  fs.writeFileSync(repoFile, fileBytes);
+  assert.deepEqual(readFileCandidate({ repoRoot: root, repoRelativePath: "source.txt", hash: sha256(fileBytes) }).raw, fileBytes);
+  const gitHash = createHash("sha1").update(`blob ${fileBytes.length}\0`).update(fileBytes).digest("hex");
+  assert.deepEqual(readFileCandidate({ repoRoot: root, repoRelativePath: "source.txt", hash: gitHash }).raw, fileBytes);
+});
+
+test("all file-opening readers reject final-component symlinks", (t) => {
+  const root = tempDir(t);
+  const outside = path.join(root, "outside.jsonl");
+  fs.writeFileSync(outside, JSON.stringify({ session_id: "s", event_id: "e" }) + "\n");
+  const telemetry = path.join(root, "telemetry");
+  fs.mkdirSync(telemetry);
+  fs.symlinkSync(outside, path.join(telemetry, "full.jsonl"));
+  assert.throws(
+    () => readTelemetryCandidates({ telemetryDir: telemetry, channel: "full", sessionId: "s", eventId: "e", sha8: "00000000" }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt",
+  );
+
+  const realDir = path.join(root, "real-dir");
+  fs.mkdirSync(realDir);
+  const bytes = Buffer.from("pinned\n");
+  fs.writeFileSync(path.join(realDir, "source.txt"), bytes);
+  fs.symlinkSync(realDir, path.join(root, "linked-dir"));
+  assert.throws(
+    () => readFileCandidate({ repoRoot: root, repoRelativePath: "linked-dir/source.txt", hash: sha256(bytes) }),
+    (error) => error instanceof NarrativeReaderError && error.reason === "corrupt",
+  );
+});

package/src/cli/narrative-render.test.mjs

@@ -0,0 +1,221 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+
+const root = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../..");
+const api = await import(pathToFileURL(path.join(root, "build/src/index.js")));
+
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const sha8 = (bytes) => sha256(bytes).slice(0, 8);
+const CAPTURED_AT = "2026-07-14T15:00:00.000Z";
+const COMPILED_AT = "2026-07-14T16:00:00.000Z";
+
+function buildNarrativeDir(tmp) {
+  const sessionDir = path.join(tmp, "session");
+  fs.mkdirSync(sessionDir, { recursive: true });
+  const commandLine = JSON.stringify({ command: "npm test", result: "fail", exitCode: 1 });
+  fs.writeFileSync(path.join(sessionDir, "command-log.jsonl"), `${commandLine}\n`);
+  const narrativeDir = path.join(tmp, "narrative");
+  api.snapshotNarrative({
+    narrativeDir,
+    narrativeId: "prose-render-unit",
+    redactionFields: [],
+    compiler: { name: "prose-render-unit", version: "1", policy_hash: "fixture" },
+    captureCompleteness: { channels: { full: "active" }, known_gaps: [] },
+    requests: [{
+      source: api.parseSourceId(`fa1:cmdlog:session:line-1/${sha8(Buffer.from(commandLine))}`),
+      roots: { sessionDir },
+    }],
+  }, { now: () => CAPTURED_AT });
+  return narrativeDir;
+}
+
+function neverResolvingGenerator() {
+  return { identity: { model: "never", provider: "test", config_hash: "x" }, generate: () => new Promise(() => {}) };
+}
+
+function throwingGenerator(message = "generator boom") {
+  return {
+    identity: { model: "throws", provider: "test", config_hash: "x" },
+    async generate() { throw new Error(message); },
+  };
+}
+
+function unsupportedGenerator() {
+  return {
+    identity: { model: "unsupported", provider: "test", config_hash: "x" },
+    async generate() {
+      return {
+        sentences: [{ text: "The run silently succeeded despite issues", statement_refs: ["fa1:flow-state:absent:state/00000000"] }],
+        usage: { input_tokens: 10, output_tokens: 5 },
+      };
+    },
+  };
+}
+
+function readEconomics(narrativeDir) {
+  const file = path.join(narrativeDir, api.PROSE_ECONOMICS_FILE);
+  return fs.readFileSync(file, "utf8").trim().split("\n").filter(Boolean).map((line) => JSON.parse(line));
+}
+
+test("#614 success: stub generator publishes prose alongside the deterministic narrative", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-render-success-"));
+  try {
+    const narrativeDir = buildNarrativeDir(tmp);
+    const outDir = path.join(tmp, "out");
+    const result = await api.renderProse(narrativeDir, { compiledAt: COMPILED_AT, outDir, generator: api.stubGenerator });
+    assert.equal(result.outcome, "prose_published");
+    assert.ok(result.prose);
+    assert.ok(fs.existsSync(result.written.envelopePath), "deterministic envelope must exist");
+    assert.ok(fs.existsSync(result.written.renderPath), "deterministic markdown must exist");
+    assert.ok(fs.existsSync(result.prose.path), "prose artifact must exist");
+
+    const proseDoc = JSON.parse(fs.readFileSync(result.prose.path, "utf8"));
+    assert.ok(proseDoc.statements.length > 0, "at least one summary statement was published");
+    for (const statement of proseDoc.statements) assert.equal(statement.class, "summarizer_inferred");
+
+    // LB2: original atomic statements in the (unaugmented) written envelope keep their class.
+    const runtime = result.envelope.sections.find((section) => section.authority === "flow-agents");
+    const atomicClasses = new Set(
+      [...runtime.embedded.turns.flatMap((turn) => turn.statements), ...runtime.embedded.document_statements].map((statement) => statement.class),
+    );
+    assert.ok([...atomicClasses].every((cls) => cls === "observed" || cls === "deterministic_derived"));
+
+    const economics = readEconomics(narrativeDir);
+    assert.equal(economics.length, 1);
+    assert.equal(economics[0].outcome, "accepted");
+    assert.equal(typeof economics[0].source_hash, "string");
+    assert.equal(typeof economics[0].output_hash, "string");
+    assert.ok(economics[0].input_tokens > 0);
+    assert.ok(economics[0].output_tokens > 0);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("#614 fail-closed: generator timeout writes zero prose artifacts and records economics", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-render-timeout-"));
+  try {
+    const narrativeDir = buildNarrativeDir(tmp);
+    const outDir = path.join(tmp, "out");
+    const result = await api.renderProse(narrativeDir, {
+      compiledAt: COMPILED_AT, outDir, generator: neverResolvingGenerator(), timeoutMs: 25,
+    });
+    assert.equal(result.outcome, "deterministic_only");
+    assert.ok(fs.existsSync(result.written.envelopePath), "deterministic envelope must still exist");
+    const proseFiles = fs.readdirSync(outDir).filter((name) => name.endsWith(".prose.json"));
+    assert.deepEqual(proseFiles, [], "zero prose artifacts on timeout");
+
+    const economics = readEconomics(narrativeDir);
+    assert.equal(economics.length, 1);
+    assert.equal(economics[0].outcome, "generator_timeout");
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("#614 fail-closed: generator error writes zero prose artifacts and records economics", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-render-error-"));
+  try {
+    const narrativeDir = buildNarrativeDir(tmp);
+    const outDir = path.join(tmp, "out");
+    const result = await api.renderProse(narrativeDir, { compiledAt: COMPILED_AT, outDir, generator: throwingGenerator("boom-614") });
+    assert.equal(result.outcome, "deterministic_only");
+    assert.match(result.reason, /boom-614/);
+    const proseFiles = fs.readdirSync(outDir).filter((name) => name.endsWith(".prose.json"));
+    assert.deepEqual(proseFiles, [], "zero prose artifacts on generator error");
+
+    const economics = readEconomics(narrativeDir);
+    assert.equal(economics.length, 1);
+    assert.equal(economics[0].outcome, "generator_error");
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("#614 fail-closed: an unsupported/unresolved summary is rejected and writes zero prose artifacts", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-render-reject-"));
+  try {
+    const narrativeDir = buildNarrativeDir(tmp);
+    const outDir = path.join(tmp, "out");
+    const result = await api.renderProse(narrativeDir, { compiledAt: COMPILED_AT, outDir, generator: unsupportedGenerator() });
+    assert.equal(result.outcome, "deterministic_only");
+    assert.match(result.reason, /unresolved_citation|unsupported_summary/);
+    const proseFiles = fs.readdirSync(outDir).filter((name) => name.endsWith(".prose.json"));
+    assert.deepEqual(proseFiles, [], "zero prose artifacts on validator reject");
+    // The forbidden claim never reaches disk anywhere under outDir or the narrative dir sink.
+    const combined = [
+      ...fs.readdirSync(outDir).map((name) => fs.readFileSync(path.join(outDir, name), "utf8")),
+      fs.readFileSync(path.join(narrativeDir, api.PROSE_ECONOMICS_FILE), "utf8"),
+    ].join("\n");
+    assert.doesNotMatch(combined, /silently succeeded/);
+
+    const economics = readEconomics(narrativeDir);
+    assert.equal(economics.length, 1);
+    assert.equal(economics[0].outcome, "validator_reject");
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test("#614 economics-always: every attempted outcome kind appends exactly one provenance record", async () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-render-economics-"));
+  try {
+    const narrativeDir = buildNarrativeDir(tmp);
+    await api.renderProse(narrativeDir, { compiledAt: COMPILED_AT, outDir: path.join(tmp, "out-1"), generator: api.stubGenerator });
+    await api.renderProse(narrativeDir, { compiledAt: COMPILED_AT, outDir: path.join(tmp, "out-2"), generator: throwingGenerator() });
+    const economics = readEconomics(narrativeDir);
+    assert.equal(economics.length, 2);
+    assert.deepEqual(economics.map((record) => record.outcome).sort(), ["accepted", "generator_error"]);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ── Provider gate (D5/R6/AC8) ────────────────────────────────────────────────
+
+test("#614 provider gate: a local endpoint is allowed with no opt-in", () => {
+  assert.equal(api.providerAllowed({}, "http://127.0.0.1:11434/api/generate"), true);
+  assert.equal(api.providerAllowed({}, "http://localhost:11434/api/generate"), true);
+});
+
+test("#614 provider gate: a non-local endpoint is refused without opt-in, and opt-in requires all three fields", () => {
+  const endpoint = "https://model-provider.example/v1/generate";
+  assert.equal(api.providerAllowed({}, endpoint), false);
+  assert.equal(api.providerAllowed({ optIn: { tenant: "acme" } }, endpoint), false, "partial opt-in must still be refused");
+  assert.equal(api.providerAllowed({ optIn: { tenant: "acme", data_residency: "us", payload_policy: "redacted-only" } }, endpoint), true);
+});
+
+test("#614 provider gate: hosted generator is inert without opt-in and never attempts a socket", async () => {
+  // A non-routable TEST-NET-1 address (RFC 5737): any real connection attempt would hang
+  // until a TCP-level timeout (seconds). A providerAllowed()-gated rejection instead
+  // resolves in milliseconds, proving the check runs BEFORE any dial is attempted.
+  const generator = api.hostedModelGenerator({ model: "hosted-test", provider: "hosted", endpoint: "https://192.0.2.1/generate", timeoutMs: 5000 });
+  const startedAt = Date.now();
+  await assert.rejects(
+    generator.generate({ statements: [], sourceViews: [] }),
+    (error) => error instanceof api.ProviderNotAllowedError,
+  );
+  assert.ok(Date.now() - startedAt < 2000, "hosted generator must reject before any network dial, not after a connection timeout");
+});
+
+test("#614 provider gate: hosted generator proceeds to dial only once fully opted in (still fails fast against an unroutable test address)", async () => {
+  const generator = api.hostedModelGenerator({
+    model: "hosted-test",
+    provider: "hosted",
+    endpoint: "http://127.0.0.1:1", // local, allowed unconditionally; nothing listens there.
+    timeoutMs: 500,
+  });
+  await assert.rejects(generator.generate({ statements: [], sourceViews: [] }));
+});
+
+// ── Display-only isolation (D9/LB8) ──────────────────────────────────────────
+
+test("#614 D9: narrative-render.ts imports no continuation-* module", () => {
+  const source = fs.readFileSync(path.join(root, "src/cli/narrative-render.ts"), "utf8");
+  assert.doesNotMatch(source, /(?:from|import|require)\s*\(?\s*["'`][^"'`]*continuation-[^"'`]*["'`]/);
+});