@kontourai/flow-agents 3.12.1 → 4.0.0

package/src/cli/narrative-grounding-validator.test.mjs

@@ -0,0 +1,322 @@
+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 {
+  NarrativeGroundingError,
+  entailmentIndependenceHolds,
+  isAssertionProhibited,
+  validateNarrativeGrounding,
+} from "../../build/src/narrative/grounding-validator.js";
+
+const NOW = "2026-07-14T15:00:00.000Z";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const sha8 = (bytes) => sha256(bytes).slice(0, 8);
+
+function sourceId(stream, index, bytes) {
+  if (stream === "telemetry") return `fa1:telemetry:full/session:event-${index}/${sha8(bytes)}`;
+  if (stream === "file") return `fa1:file:created-${index}.json:${sha256(bytes)}`;
+  return `fa1:cmdlog:grounding:line-${index + 1}/${sha8(bytes)}`;
+}
+
+function narrativeDirFor(records = []) {
+  const narrativeDir = fs.mkdtempSync(path.join(os.tmpdir(), "grounding-validator-"));
+  const sourcesDir = path.join(narrativeDir, "sources");
+  fs.mkdirSync(sourcesDir);
+  const sources = records.map(({ stream, record }, index) => {
+    const bytes = Buffer.from(JSON.stringify(record));
+    const digest = sha256(bytes);
+    fs.writeFileSync(path.join(sourcesDir, digest), bytes);
+    return {
+      source_id: sourceId(stream, index, bytes),
+      integrity_class: stream === "telemetry" ? "rotatable" : stream === "cmdlog" ? "append_only_unhashed" : "overwritten_in_place",
+      captured_at: NOW,
+      origin: { store: stream, path_class: "fixture" },
+      status: "snapshotted",
+      sha256: digest,
+      bytes: bytes.length,
+      lineage: [{ at: NOW, event: "source_snapshotted" }],
+    };
+  });
+  fs.writeFileSync(path.join(narrativeDir, "source-manifest.json"), JSON.stringify({
+    schema_version: "1.0",
+    narrative_id: "grounding-unit",
+    captured_at: NOW,
+    compiler: { name: "grounding-unit", version: "1", policy_hash: "fixture" },
+    capture_completeness: { channels: { full: "active" }, known_gaps: [] },
+    sources,
+  }));
+  return { narrativeDir, sources };
+}
+
+function statement(overrides = {}) {
+  return {
+    id: "statement-1",
+    class: "observed",
+    proposition: "Tool read emitted event tool.result",
+    source_refs: [],
+    ...overrides,
+  };
+}
+
+function envelope(statements = []) {
+  return {
+    sections: [{
+      authority: "flow-agents",
+      kind: "runtime-projection",
+      sha256: "0".repeat(64),
+      embedded: { turns: [], document_statements: statements },
+    }],
+  };
+}
+
+function codes(verdict) {
+  assert.equal(verdict.ok, false);
+  return verdict.violations.map((violation) => violation.code);
+}
+
+test("AC1: an absent frozen source citation is rejected with resolver detail", () => {
+  const { narrativeDir } = narrativeDirFor();
+  const missing = "fa1:cmdlog:grounding:line-1/01234567";
+  const verdict = validateNarrativeGrounding(envelope([statement({ source_refs: [missing] })]), narrativeDir);
+  assert.deepEqual(codes(verdict), ["unresolved_citation"]);
+  assert.deepEqual(verdict.violations[0], {
+    code: "unresolved_citation",
+    statement_id: "statement-1",
+    source_ref: missing,
+    reason: "not_captured",
+    detail: "source id is not present in the manifest",
+  });
+  assert.equal(verdict.known_gaps[0].code, "contradiction_detection_unavailable");
+});
+
+test("manifest-declared unavailable-source disclosures are not treated as content citations", () => {
+  const { narrativeDir } = narrativeDirFor();
+  const sourceRef = "fa1:file:missing.json:" + "0".repeat(64);
+  const manifestFile = path.join(narrativeDir, "source-manifest.json");
+  const manifest = JSON.parse(fs.readFileSync(manifestFile, "utf8"));
+  manifest.sources.push({
+    source_id: sourceRef,
+    integrity_class: "overwritten_in_place",
+    captured_at: NOW,
+    origin: { store: "file", path_class: "fixture" },
+    status: "unavailable",
+    unavailable_reason: "not_captured",
+    lineage: [],
+  });
+  fs.writeFileSync(manifestFile, JSON.stringify(manifest));
+  const verdict = validateNarrativeGrounding(envelope([statement({
+    class: "deterministic_derived",
+    proposition: `Source ${sourceRef} was unavailable because not_captured`,
+    source_refs: [sourceRef],
+    rule: { id: "unavailable-source", version: "v1", inputs: [sourceRef] },
+  })]), narrativeDir);
+  assert.equal(verdict.ok, true);
+
+  const falsified = validateNarrativeGrounding(envelope([statement({
+    class: "deterministic_derived",
+    proposition: "Gate tests-evidence was accepted",
+    source_refs: [sourceRef],
+    rule: { id: "unavailable-source", version: "v1", inputs: [sourceRef] },
+  })]), narrativeDir);
+  assert.ok(codes(falsified).includes("unresolved_citation"));
+});
+
+const materialCases = [
+  {
+    name: "command_failure",
+    records: [{ stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } }],
+  },
+  {
+    // #623 (review HIGH): a command failure captured via the telemetry stream (a tool.result
+    // event carrying a command + non-zero exit) must be derived and coverage-enforced, exactly
+    // like a cmdlog failure — otherwise a telemetry-sourced failure can be omitted undetected.
+    name: "telemetry_command_failure",
+    eventKind: "command_failure",
+    records: [{ stream: "telemetry", record: { session_id: "session", event_type: "tool.result", tool: { name: "execute_bash", input: { command: "false" } }, exit_code: 1 } }],
+  },
+  {
+    name: "retry_group",
+    records: [
+      { stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } },
+      { stream: "cmdlog", record: { command: "npm test", result: "pass", exitCode: 0 } },
+    ],
+  },
+  {
+    name: "timeout",
+    records: [{ stream: "telemetry", record: { session_id: "session", event_type: "tool.result", timed_out: true, tool: { name: "shell" } } }],
+  },
+  {
+    // #623 (re-review HIGH): a timeout signalled ONLY via tool.status must be derived and
+    // coverage-enforced too — carriesTimeout must mirror projection's carriesTimeoutSignal
+    // tool.status fallback, or a tool.status-only timeout can be omitted undetected.
+    name: "tool_status_timeout",
+    eventKind: "timeout",
+    records: [{ stream: "telemetry", record: { session_id: "session", event_type: "tool.result", tool: { name: "shell", status: "timeout" } } }],
+  },
+  {
+    name: "no_op_turn",
+    records: [{ stream: "telemetry", record: { session_id: "session", event_type: "tool.result", tool: { name: "read" } } }],
+  },
+  {
+    name: "file_creation",
+    records: [{ stream: "file", record: { kind: "created-file", path: "created.json" } }],
+  },
+];
+
+for (const fixture of materialCases) {
+  test(`AC2: uncovered ${fixture.name} material event is rejected`, () => {
+    const { narrativeDir } = narrativeDirFor(fixture.records);
+    const verdict = validateNarrativeGrounding(envelope(), narrativeDir);
+    assert.equal(verdict.ok, false);
+    assert.ok(verdict.violations.some((violation) =>
+      violation.code === "uncovered_material_event" && violation.event_kind === (fixture.eventKind ?? fixture.name)));
+  });
+}
+
+test("AC2: observed material events use class/proposition matchers, never invented rules", () => {
+  const { narrativeDir, sources } = narrativeDirFor([
+    { stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } },
+    { stream: "file", record: { kind: "created-file", path: "created.json" } },
+  ]);
+  const verdict = validateNarrativeGrounding(envelope([
+    statement({ id: "failure", proposition: "Command `npm test` was observed to fail (exit 1)", source_refs: [sources[0].source_id] }),
+    statement({ id: "file", proposition: "File `created-1.json` was observed to be created", source_refs: [sources[1].source_id] }),
+  ]), narrativeDir);
+  assert.equal(verdict.ok, true);
+});
+
+test("AC3: deterministic rule inputs outside source_refs are rejected", () => {
+  const { narrativeDir } = narrativeDirFor();
+  const cited = "fa1:cmdlog:grounding:line-1/01234567";
+  const other = "fa1:cmdlog:grounding:line-2/89abcdef";
+  const verdict = validateNarrativeGrounding(envelope([statement({
+    class: "deterministic_derived",
+    source_refs: [cited],
+    rule: { id: "fixture", version: "v1", inputs: [other] },
+  })]), narrativeDir);
+  assert.ok(codes(verdict).includes("invalid_rule_binding"));
+});
+
+test("AC3: declared dormant summarizer rule rejects a synthetic observed outcome", () => {
+  const { narrativeDir } = narrativeDirFor();
+  const synthetic = statement({
+    id: "synthetic-summary",
+    class: "summarizer_inferred",
+    proposition: "Command npm test was observed to fail",
+  });
+  const verdict = validateNarrativeGrounding(envelope([synthetic]), narrativeDir);
+  assert.ok(codes(verdict).includes("prohibited_assertion"));
+  assert.equal(isAssertionProhibited("summarizer_inferred", "observed_outcome"), true);
+  assert.equal(isAssertionProhibited("observed", "observed_outcome"), false);
+});
+
+test("#622 (review HIGH R2): the prohibited-assertion scan covers the actor field, not only the proposition", () => {
+  const { narrativeDir, sources } = narrativeDirFor([{ stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } }]);
+  // An agent_stated self-report with a benign proposition but an identifier-shaped
+  // actor that smuggles a prohibited-assertion keyword ("authoritative" -> authority).
+  // The proposition-only scan would have missed it; the actor-inclusive scan must fire.
+  const smuggled = statement({
+    id: "actor-smuggle",
+    class: "agent_stated",
+    self_report: true,
+    actor: "authoritative",
+    proposition: "Agent stated the purpose of this action is to prepare the release notes",
+    source_refs: [sources[0].source_id],
+  });
+  const verdict = validateNarrativeGrounding(envelope([smuggled]), narrativeDir);
+  assert.ok(codes(verdict).includes("prohibited_assertion"), "actor-smuggled authority keyword must be rejected");
+  // Mutation-guard: the same statement with a clean identifier-shaped actor is NOT
+  // rejected for a prohibited assertion (proves the test fails if the scan reverts to
+  // proposition-only and stops seeing the actor at all).
+  const clean = validateNarrativeGrounding(envelope([{ ...smuggled, id: "actor-clean", actor: "claude-code" }]), narrativeDir);
+  assert.equal(codes(clean).includes("prohibited_assertion"), false, "a clean actor must not trip the prohibited-assertion scan");
+});
+
+test("#614 D3: a summarizer_inferred statement citing a real atomic statement's refs is accepted", () => {
+  const { narrativeDir, sources } = narrativeDirFor([{ stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } }]);
+  const atomic = statement({
+    id: "atomic-failure",
+    class: "observed",
+    proposition: "Command `npm test` was observed to fail (exit 1)",
+    source_refs: [sources[0].source_id],
+  });
+  const summary = statement({
+    id: "summary-1",
+    class: "summarizer_inferred",
+    proposition: "The test command did not succeed",
+    source_refs: [sources[0].source_id],
+  });
+  const verdict = validateNarrativeGrounding(envelope([atomic, summary]), narrativeDir);
+  assert.equal(verdict.ok, true);
+});
+
+test("#614 D3: a summarizer_inferred statement with no atomic statements present is rejected", () => {
+  const { narrativeDir, sources } = narrativeDirFor([{ stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } }]);
+  const summary = statement({
+    id: "summary-orphan",
+    class: "summarizer_inferred",
+    proposition: "The test command did not succeed",
+    source_refs: [sources[0].source_id],
+  });
+  const verdict = validateNarrativeGrounding(envelope([summary]), narrativeDir);
+  assert.ok(codes(verdict).includes("unsupported_summary"));
+  assert.deepEqual(verdict.violations.find((violation) => violation.code === "unsupported_summary").unsupported_refs, [sources[0].source_id]);
+});
+
+test("#614 D3: a summarizer_inferred statement citing a fa1 ref no atomic statement carries is rejected", () => {
+  const { narrativeDir, sources } = narrativeDirFor([
+    { stream: "cmdlog", record: { command: "npm test", result: "fail", exitCode: 1 } },
+    { stream: "file", record: { kind: "created-file", path: "created.json" } },
+  ]);
+  const atomic = statement({
+    id: "atomic-failure",
+    class: "observed",
+    proposition: "Command `npm test` was observed to fail (exit 1)",
+    source_refs: [sources[0].source_id],
+  });
+  const summary = statement({
+    id: "summary-overreach",
+    class: "summarizer_inferred",
+    proposition: "The test command did not succeed and a file appeared",
+    // Cites a REAL fa1 ref (the file source) that no atomic statement in this
+    // section actually carries -- the subset guard must catch this even
+    // though the ref itself resolves fine (citationViolations would pass it).
+    source_refs: [sources[0].source_id, sources[1].source_id],
+  });
+  const verdict = validateNarrativeGrounding(envelope([atomic, summary]), narrativeDir);
+  assert.ok(codes(verdict).includes("unsupported_summary"));
+  assert.deepEqual(verdict.violations.find((violation) => violation.code === "unsupported_summary").unsupported_refs, [sources[1].source_id]);
+});
+
+test("R3: entailment validator must differ by model or configuration", () => {
+  const generator = { provider: "provider-a", model: "model-a", config_hash: "same" };
+  assert.equal(entailmentIndependenceHolds(generator, { ...generator }), false);
+  assert.equal(entailmentIndependenceHolds(generator, { ...generator, model: "model-b" }), true);
+  assert.equal(entailmentIndependenceHolds(generator, { ...generator, config_hash: "different" }), true);
+});
+
+test("AC5 seam: validator-internal resolver exceptions propagate fail-closed", () => {
+  const { narrativeDir, sources } = narrativeDirFor([{ stream: "cmdlog", record: { command: "true", exitCode: 0 } }]);
+  assert.throws(
+    () => validateNarrativeGrounding(envelope([statement({ source_refs: [sources[0].source_id] })]), narrativeDir, {
+      resolver: () => { throw new Error("injected resolver failure"); },
+    }),
+    /injected resolver failure/,
+  );
+});
+
+test("publication error is typed and lists violation evidence", () => {
+  const violation = {
+    code: "uncovered_material_event",
+    event_kind: "timeout",
+    source_ref: "fa1:telemetry:full/session:event/01234567",
+    detail: "fixture",
+  };
+  const error = new NarrativeGroundingError([violation]);
+  assert.equal(error.code, "grounding_failed");
+  assert.match(error.message, /uncovered_material_event timeout/);
+});

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

@@ -0,0 +1,177 @@
+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 {
+  bindIntentAnnotation,
+  captureIntent,
+  effectiveNarrativeRedactionFields,
+  isAssertionProhibited,
+  appendIntentEconomics,
+  readIntentEconomics,
+  reduceIntentEconomics,
+} from "../../build/src/index.js";
+
+const action = `fa1:file:action.json:${"a".repeat(64)}`;
+const gate = `fa1:file:gate.json:${"b".repeat(64)}`;
+const supported = { status: "supported" };
+const unsupported = { status: "unsupported", reason: "not implemented on this runtime" };
+
+// R1 (review HIGH): captureIntent co-binds the action ref to the frozen manifest.
+// The unit tests inject a resolver that resolves the action to its frozen manifest
+// ENTRY with its OWN captured_at (the annotation's captured_at derives from this, NOT
+// wall-clock). An ABSENT / fabricated ref resolves to `undefined` and is rejected.
+const ACTION_CAPTURED_AT = "2026-07-14T12:00:00.000Z";
+const resolvesAction = { resolveAction: () => ({ capturedAt: ACTION_CAPTURED_AT }) };
+const rejectsAction = { resolveAction: () => undefined };
+
+test("#622: supported + purpose captures a bounded agent_stated annotation", () => {
+  const captured = captureIntent({
+    capability: supported, actor: "codex", runtimeId: "claude-code",
+    actionRef: action, activeGateRef: gate, purpose: "prepare the release notes",
+  }, resolvesAction);
+  assert.equal(captured.mode, "agent_stated");
+  assert.equal(captured.statement.class, "agent_stated");
+  assert.equal(captured.statement.self_report, true);
+  assert.deepEqual(captured.redactions, []);
+  // captured_at derives from the resolved action entry, not a fresh clock.
+  assert.equal(captured.action_captured_at, ACTION_CAPTURED_AT);
+});
+
+test("#622 (R1): a nonexistent / unresolvable action_ref is REJECTED (no annotation)", () => {
+  // A fabricated action ref that does not resolve against the frozen manifest must
+  // throw — you cannot annotate an action that is not in the frozen manifest.
+  assert.throws(
+    () => captureIntent({
+      capability: supported, actor: "codex", runtimeId: "claude-code",
+      actionRef: `fa1:file:nonexistent.json:${"0".repeat(64)}`, activeGateRef: gate,
+      purpose: "prepare the release notes",
+    }, rejectsAction),
+    /resolvable frozen action source/,
+  );
+  // The fallback path is co-bound too: an unresolvable action is rejected even when
+  // no purpose is supplied (there is no annotation of a nonexistent action at all).
+  assert.throws(
+    () => captureIntent({
+      capability: unsupported, actor: "codex", runtimeId: "claude-code",
+      actionRef: action, activeGateRef: gate,
+    }, rejectsAction),
+    /resolvable frozen action source/,
+  );
+});
+
+test("#622 (R1): captured_at is bound to the action entry, not bind-time wall-clock", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "intent-cobind-"));
+  try {
+    const captured = captureIntent({
+      capability: supported, actor: "codex", runtimeId: "claude-code",
+      actionRef: action, activeGateRef: gate, purpose: "prepare the release notes",
+    }, resolvesAction);
+    const { annotation } = bindIntentAnnotation(dir, captured);
+    assert.equal(annotation.captured_at, ACTION_CAPTURED_AT, "annotation captured_at must equal the action entry's captured_at");
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#622: unsupported capability falls back to workflow_derived_purpose, never agent_stated", () => {
+  const captured = captureIntent({
+    capability: unsupported, actor: "codex", runtimeId: "claude-code",
+    actionRef: action, activeGateRef: gate, purpose: "prepare the release notes",
+  }, resolvesAction);
+  assert.equal(captured.mode, "workflow_derived_purpose");
+  assert.equal(captured.statement.class, "deterministic_derived");
+  assert.equal(captured.statement.rule.id, "workflow-derived-purpose");
+  assert.notEqual(captured.statement.class, "agent_stated");
+});
+
+test("#622: supported WITHOUT a purpose still falls back (no fabricated rationale)", () => {
+  const captured = captureIntent({
+    capability: supported, actor: "codex", runtimeId: "claude-code",
+    actionRef: action, activeGateRef: gate,
+  }, resolvesAction);
+  assert.equal(captured.mode, "workflow_derived_purpose");
+});
+
+test("#622: a redacted purpose field is nulled before emission (falls back)", () => {
+  const captured = captureIntent({
+    capability: supported, actor: "codex", runtimeId: "claude-code",
+    actionRef: action, activeGateRef: gate, purpose: "prepare the release notes",
+    redactionFields: effectiveNarrativeRedactionFields(["purpose"]),
+  }, resolvesAction);
+  assert.equal(captured.mode, "workflow_derived_purpose");
+  assert.ok(captured.redactions.includes("purpose"), "purpose must be recorded as redacted");
+  // The redacted purpose text never reaches an emitted agent_stated proposition.
+  assert.doesNotMatch(captured.statement.proposition, /release notes/);
+});
+
+test("#622: bindIntentAnnotation freezes write-once; a post-hoc write is EEXIST-rejected", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "intent-bind-"));
+  try {
+    const captured = captureIntent({
+      capability: supported, actor: "codex", runtimeId: "claude-code",
+      actionRef: action, activeGateRef: gate, purpose: "prepare the release notes",
+    }, resolvesAction);
+    const first = bindIntentAnnotation(dir, captured);
+    assert.equal(first.annotation.captured_at, ACTION_CAPTURED_AT);
+    assert.ok(fs.existsSync(first.path));
+    const frozenBytes = fs.readFileSync(first.path);
+    // A second/late write to the frozen channel MUST be structurally rejected.
+    assert.throws(
+      () => bindIntentAnnotation(dir, captured),
+      /already frozen/,
+    );
+    // The frozen channel bytes are unchanged by the rejected post-hoc write.
+    assert.deepEqual(fs.readFileSync(first.path), frozenBytes);
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#622: agent_stated can never assert a prohibited (gate-evidence) category", () => {
+  for (const kind of ["gate_status", "observed_outcome", "authority", "hidden_alternative"]) {
+    assert.equal(isAssertionProhibited("agent_stated", kind), true, `agent_stated must not assert ${kind}`);
+  }
+});
+
+test("#622: A/B reducer reports a mean delta WITH an uncertainty spread", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "intent-econ-"));
+  try {
+    appendIntentEconomics(dir, { mode: "annotation_off", input_tokens: 100, output_tokens: 40, wall_clock_ms: 1000, attempted_at: "2026-07-15T00:00:00.000Z" });
+    appendIntentEconomics(dir, { mode: "annotation_on", input_tokens: 130, output_tokens: 44, wall_clock_ms: 1100, attempted_at: "2026-07-15T00:00:01.000Z" });
+    appendIntentEconomics(dir, { mode: "annotation_off", input_tokens: 100, output_tokens: 40, wall_clock_ms: 1000, attempted_at: "2026-07-15T00:00:02.000Z" });
+    appendIntentEconomics(dir, { mode: "annotation_on", input_tokens: 150, output_tokens: 48, wall_clock_ms: 1200, attempted_at: "2026-07-15T00:00:03.000Z" });
+
+    const summary = reduceIntentEconomics(readIntentEconomics(dir));
+    assert.equal(summary.pairs, 2);
+    assert.equal(summary.delta_input_tokens.has_data, true);
+    assert.equal(summary.delta_input_tokens.mean, 40); // (30 + 50) / 2
+    assert.ok(summary.delta_input_tokens.sample_std > 0, "uncertainty spread must be reported");
+    assert.equal(summary.delta_input_tokens.min, 30);
+    assert.equal(summary.delta_input_tokens.max, 50);
+    assert.equal(summary.delta_output_tokens.mean, 6); // (4 + 8) / 2
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("#622 (MEDIUM): an empty / one-sided A/B window reports has_data:false, not a false-precise zero", () => {
+  // Empty window: no samples at all.
+  const empty = reduceIntentEconomics([]);
+  assert.equal(empty.pairs, 0);
+  for (const metric of ["delta_input_tokens", "delta_output_tokens", "delta_wall_clock_ms"]) {
+    assert.equal(empty[metric].has_data, false, `${metric} must not claim a measured zero`);
+    assert.equal("mean" in empty[metric], false, `${metric} must omit a false-precise mean`);
+  }
+  // One-sided window: on-only (no off samples to pair against) — still no confirmed delta.
+  const onlyOn = reduceIntentEconomics([
+    { mode: "annotation_on", input_tokens: 130, output_tokens: 44, wall_clock_ms: 1100, attempted_at: "2026-07-15T00:00:00.000Z" },
+    { mode: "annotation_on", input_tokens: 150, output_tokens: 48, wall_clock_ms: 1200, attempted_at: "2026-07-15T00:00:01.000Z" },
+  ]);
+  assert.equal(onlyOn.pairs, 0);
+  assert.equal(onlyOn.on_samples, 2);
+  assert.equal(onlyOn.off_samples, 0);
+  assert.equal(onlyOn.delta_input_tokens.has_data, false);
+});

package/src/cli/narrative-policy-filter.test.mjs

@@ -0,0 +1,66 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT,
+  TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT,
+  effectiveNarrativeRedactionFields,
+  filterNarrativeRecord,
+} from "../../build/src/index.js";
+
+function bashDefault(name) {
+  const repoRoot = path.resolve(import.meta.dirname, "../..");
+  const config = fs.readFileSync(path.join(repoRoot, "scripts/telemetry/lib/config.sh"), "utf8");
+  const match = new RegExp(`${name}="\\$\\{${name}:-([^}]*)\\}"`).exec(config);
+  assert.ok(match, `${name} default must remain parseable`);
+  return match[1].split(",");
+}
+
+test("TypeScript redaction defaults cannot drift from config.sh", () => {
+  assert.deepEqual([...TELEMETRY_CHANNEL_FULL_REDACT_DEFAULT], bashDefault("TELEMETRY_CHANNEL_FULL_REDACT"));
+  assert.deepEqual([...TELEMETRY_CHANNEL_ANALYTICS_REDACT_DEFAULT], bashDefault("TELEMETRY_CHANNEL_ANALYTICS_REDACT"));
+});
+
+test("effective narrative fields union full-channel and caller-specific policy", () => {
+  assert.deepEqual(effectiveNarrativeRedactionFields(["tool.output", "custom.secret"]), [
+    "hook.raw_input", "turn.prompt_text", "tool.input", "tool.output", "custom.secret",
+  ]);
+});
+
+test("filter nulls whole fields by dotted path on a structured clone", () => {
+  const input = { hook: { raw_input: "secret", keep: 1 }, tool: { input: { token: "secret" }, output: "secret" }, safe: true };
+  const result = filterNarrativeRecord(input, effectiveNarrativeRedactionFields());
+  assert.equal(result.kind, "filtered");
+  assert.equal(result.record.hook.raw_input, null);
+  assert.equal(result.record.tool.input, null);
+  assert.equal(result.record.tool.output, null);
+  assert.equal(result.record.safe, true);
+  assert.equal(input.hook.raw_input, "secret");
+});
+
+test("unparsable records and unresolvable policy fail closed without echoing values", () => {
+  const secret = "NEVER_ECHO_THIS_VALUE";
+  for (const result of [
+    filterNarrativeRecord(`{"tool":{"input":"${secret}"}`, ["tool.input"]),
+    filterNarrativeRecord({ tool: { input: secret } }, undefined),
+  ]) {
+    assert.equal(result.kind, "redacted");
+    assert.doesNotMatch(JSON.stringify(result), new RegExp(secret));
+  }
+});
+
+test("field-nulling failures report field names only", () => {
+  const secret = "VALUE_MUST_STAY_PRIVATE";
+  const result = filterNarrativeRecord({ tool: secret }, ["tool.input"]);
+  assert.equal(result.kind, "redacted");
+  assert.match(result.diagnostic, /tool\.input/);
+  assert.doesNotMatch(JSON.stringify(result), new RegExp(secret));
+});
+
+test("prototype-shaped policy paths fail closed", () => {
+  const result = filterNarrativeRecord({ safe: true }, ["__proto__.polluted"]);
+  assert.equal(result.kind, "redacted");
+  assert.equal({}.polluted, undefined);
+});