@kontourai/flow-agents 3.12.0 → 4.0.0

package/src/cli/sidecar-pure-helpers.test.mjs

@@ -8,53 +8,93 @@
 // Run: `npm run test:unit` (builds first). Requires `npm run build` output under build/.
 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 {
-  buildClaimExplanation as buildClaimExplanationReexport,
   deriveGateCalibration,
   gateAdvisoryFix,
   buildGateInquiryRecords,
+  isNarrativeNamespacePath,
+  isNarrativeArtifactContent,
   validateEvidenceRef,
   normalizeEvidenceRefs,
   normalizeCheck,
+  normalizeFinding,
+  normalizeLearning,
   reduceCaptureLogByCommand,
 } from "../../build/src/cli/workflow-sidecar.js";
-import { buildClaimExplanation } from "../../build/src/cli/sidecar-claim-explain.js";
 
-// ── buildClaimExplanation (extracted pure projection) ────────────────────────
+// ── explainClaim (#171: consumed from @kontourai/surface >=2.10) ─────────────
+// The local buildClaimExplanation prototype was lifted into Surface (surface#151)
+// with the drilldown composition folded inside; these tests pin the consumed
+// function's behavior through the SAME expectations the prototype carried, so a
+// Surface regression (or an accidental un-lift) fails here.
+import { explainClaim, buildTrustReport, TrustBundleBuilder } from "@kontourai/surface";
 
-test("buildClaimExplanation: re-export from workflow-sidecar === the extracted module", () => {
-  assert.equal(buildClaimExplanationReexport, buildClaimExplanation);
-});
-
-test("buildClaimExplanation: unknown claim id returns found:false sentinel", () => {
-  const out = buildClaimExplanation({ claims: [] }, { claims: [] }, "missing");
+test("explainClaim (Surface): unknown claim id returns found:false sentinel", () => {
+  const report = buildTrustReport(new TrustBundleBuilder({ source: "unit:171" }).build());
+  const out = explainClaim(report, "missing");
   assert.equal(out.found, false);
   assert.equal(out.status, "unknown");
   assert.deepEqual(out.evidence, []);
   assert.equal(out.policy, null);
 });
 
-test("buildClaimExplanation: projects status, policy, and evidence for a found claim", () => {
-  const report = {
-    claims: [{ id: "c1", status: "verified", value: "pass", claimType: "workflow.check" }],
-    transparencyGaps: [{ claimId: "c1", reason: "x" }, { claimId: "other" }],
-    changeRecords: [],
-  };
-  const bundle = {
-    claims: [{ id: "c1", verificationPolicyId: "p1", value: "pass", claimType: "workflow.check" }],
-    policies: [{ id: "p1", requiredEvidence: ["test"], acceptanceCriteria: ["AC1"], reviewAuthority: "owner" }],
-    evidence: [{ claimId: "c1", evidenceType: "command", execution: { runner: "npm test", label: "npm test", exitCode: 0 } }],
-  };
-  const out = buildClaimExplanation(report, bundle, "c1");
+test("explainClaim (Surface): projects status, policy, evidence, and filtered gaps for a found claim", () => {
+  const builder = new TrustBundleBuilder({ source: "unit:171" });
+  builder.addClaim({
+    id: "c1", subjectType: "repo", subjectId: "flow-agents", claimType: "workflow.check",
+    fieldOrBehavior: "unit-tests", value: "pass", verificationPolicyId: "p1",
+    createdAt: "2026-07-14T00:00:00.000Z", updatedAt: "2026-07-14T00:00:00.000Z",
+  });
+  builder.addPolicy({
+    id: "p1", claimType: "workflow.check", requiredEvidence: ["test_output"], requiredMethods: ["validation"],
+    acceptanceCriteria: ["AC1"], reviewAuthority: "owner", validityRule: { kind: "manual" },
+    stalenessTriggers: [], conflictRules: [], impactLevel: "high",
+  });
+  builder.addEvidence({
+    id: "e1", claimId: "c1", evidenceType: "test_output", method: "validation",
+    sourceRef: "run:e1", excerptOrSummary: "npm test", observedAt: "2026-07-14T00:00:00.000Z",
+    collectedBy: "ci", execution: { runner: "bash", label: "npm test", exitCode: 0 },
+  });
+  const out = explainClaim(buildTrustReport(builder.build()), "c1");
   assert.equal(out.found, true);
-  assert.equal(out.status, "verified");
+  assert.equal(out.status, "proposed");               // derived by the report (no verifying event), projected verbatim
+  assert.equal(out.value, "pass");                    // String coercion of the claim value
+  assert.equal(out.claimType, "workflow.check");
   assert.equal(out.policy.id, "p1");
-  assert.deepEqual(out.policy.requiredEvidence, ["test"]);
+  assert.deepEqual(out.policy.requiredEvidence, ["test_output"]);
   assert.equal(out.evidence.length, 1);
   assert.equal(out.evidence[0].passing, true);        // exitCode 0 → not error → passing
   assert.equal(out.evidence[0].execution.exitCode, 0);
-  assert.equal(out.why.transparencyGaps.length, 1);   // only the c1 gap, not "other"
+  // Gap filtering: only THIS claim's transparency gaps appear (none seeded for c1,
+  // and a report-level gap for another claim must not leak in).
+  assert.deepEqual(out.why.transparencyGaps.filter((gap) => gap.claimId !== "c1"), []);
+});
+
+test("explainClaim (Surface): legacy evidence label/summary fallback tolerance survives the lift", () => {
+  // Pre-lift bundles could carry top-level label/summary on evidence; the consumed
+  // function keeps the prototype's fallback chains (label ?? excerptOrSummary ?? ...).
+  const builder = new TrustBundleBuilder({ source: "unit:171-legacy" });
+  builder.addClaim({
+    id: "c2", subjectType: "repo", subjectId: "flow-agents", claimType: "workflow.check",
+    fieldOrBehavior: "legacy", value: "pass",
+    createdAt: "2026-07-14T00:00:00.000Z", updatedAt: "2026-07-14T00:00:00.000Z",
+  });
+  builder.addEvidence({
+    id: "e2", claimId: "c2", evidenceType: "attestation", method: "attestation",
+    sourceRef: "run:e2", excerptOrSummary: "excerpt-wins-for-summary", observedAt: "2026-07-14T00:00:00.000Z",
+    collectedBy: "ci",
+  });
+  const out = explainClaim(buildTrustReport(builder.build()), "c2");
+  assert.equal(out.found, true);
+  assert.equal(out.evidence.length, 1);
+  assert.equal(out.evidence[0].label, "excerpt-wins-for-summary");   // label falls back to excerptOrSummary
+  assert.equal(out.evidence[0].summary, "excerpt-wins-for-summary"); // summary prefers excerptOrSummary
+  assert.equal(out.evidence[0].execution, null);
+  assert.equal(out.evidence[0].passing, true);                       // no execution, not disputed → passing
 });
 
 // ── deriveGateCalibration (pure mapping) ─────────────────────────────────────
@@ -93,6 +133,99 @@ test("validateEvidenceRef: rejects bad kind, unsupported field, and incomplete s
   assert.throws(() => validateEvidenceRef({ kind: "source", file: "a.ts" }, "refs"), /source refs require/);
 });
 
+test("narrative namespace paths and free-form references are rejected with the typed #619 diagnostic", () => {
+  const root = "/tmp/project";
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/.kontourai/narrative/run/n1/envelope.json"), true);
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/.kontourai/flow-agents/run/narrative/legacy.md"), true);
+  assert.equal(isNarrativeNamespacePath(root, "/tmp/project/docs/narrative/design.md"), false);
+  for (const ref of [
+    { kind: "source", file: "src/file.ts", line_start: 1, line_end: 1, excerpt: "see .kontourai/narrative/run/n1/envelope.json" },
+    { kind: "artifact", file: ".kontourai/narrative/run/n1/envelope.json", summary: "rendered narrative" },
+    { kind: "command", excerpt: "cat .kontourai/flow-agents/run/narrative/envelope.md" },
+    { kind: "provider", url: "file:///.kontourai/narrative/run/n1/envelope.json" },
+    { kind: "external", url: "https://example.invalid/.kontourai/narrative/run/n1/envelope.json" },
+  ]) {
+    assert.throws(() => validateEvidenceRef(ref, "refs"), /narrative trust isolation \(#619\)/);
+  }
+});
+
+test("narrative isolation canonicalizes aliases and rejects narrative content independent of location", { concurrency: false }, () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "narrative-isolation-unit-"));
+  const narrativeDir = path.join(root, ".kontourai", "narrative", "run", "n1");
+  const envelope = path.join(narrativeDir, "envelope.json");
+  const relocated = path.join(root, "evidence", "relocated.json");
+  const hardlink = path.join(root, "evidence", "hardlink.json");
+  const symlink = path.join(root, "evidence", "symlink.json");
+  const commandSymlink = path.join(root, "evidence", "narrative-symlink.sh");
+  const source = path.join(root, "src", "narrative", "composer.ts");
+  fs.mkdirSync(narrativeDir, { recursive: true });
+  fs.mkdirSync(path.dirname(relocated), { recursive: true });
+  fs.mkdirSync(path.dirname(source), { recursive: true });
+  const bytes = Buffer.from('{"schema_version":"grounded-execution-narrative/v1","narrative_id":"n1"}');
+  fs.writeFileSync(envelope, bytes);
+  fs.copyFileSync(envelope, relocated);
+  fs.linkSync(envelope, hardlink);
+  fs.symlinkSync(envelope, symlink);
+  fs.symlinkSync(envelope, commandSymlink);
+  fs.writeFileSync(source, 'export const narrativeSource = true;\n');
+  try {
+    assert.equal(isNarrativeNamespacePath(root, path.join(root, ".KONTOURAI", "NARRATIVE", "run", "n1", "envelope.json")), true);
+    assert.equal(isNarrativeArtifactContent(bytes), true);
+    for (const file of [envelope, relocated, hardlink, symlink]) {
+      assert.throws(
+        () => validateEvidenceRef({ kind: "artifact", file, summary: "must reject" }, "refs", root),
+        /narrative trust isolation \(#619\)/,
+      );
+    }
+    assert.throws(
+      () => validateEvidenceRef({ kind: "provider", url: "file%3A%2F%2F%2F.KONTOURAI%2FNARRATIVE%2Frun%2Fn1%2Fenvelope.json" }, "refs", root),
+      /narrative trust isolation \(#619\)/,
+    );
+    assert.doesNotThrow(() => validateEvidenceRef({ kind: "source", file: source, line_start: 1, line_end: 1, excerpt: "source code" }, "refs", root));
+    for (const command of [
+      "test -f .kontourai/narrative/run/n1/envelope.json",
+      "test -f .KONTOURAI/NARRATIVE/run/n1/envelope.json",
+      "test -f .kontourai%2Fnarrative%2Frun%2Fn1%2Fenvelope.json",
+      "bash evidence/narrative-symlink.sh",
+      "cd .kontourai && test -f narrative/run/n1/envelope.json",
+    ]) {
+      assert.throws(() => normalizeCheck({ id: "n", kind: "command", status: "pass", summary: "n", command }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    }
+    assert.doesNotThrow(() => normalizeCheck({
+      id: "variable-composition", kind: "command", status: "pass", summary: "static scanner residual",
+      command: 'base=.kontourai; test -f "$base/narrative/run/n1/envelope.json"',
+    }, false, undefined, root));
+    assert.throws(() => normalizeCheck({
+      id: "standard-ref", kind: "test", status: "pass", summary: "must reject",
+      standard_refs: [{ standard: "junit", ref: ".kontourai/narrative/run/n1/envelope.json" }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "surface-ref", kind: "policy", status: "pass", summary: "must reject",
+      surface_trust_refs: [{
+        artifact_kind: "trust.bundle", artifact_ref: ".kontourai/narrative/run/n1/envelope.json",
+        claim_status: "accepted", freshness: { status: "fresh" }, authority: { producer: "surface-local" },
+        integrity: { status: "matched" }, status: "pass", summary: "accepted",
+      }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "standard-content", kind: "test", status: "pass", summary: "must reject",
+      standard_refs: [{ standard: "junit", ref: hardlink }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeCheck({
+      id: "surface-content", kind: "policy", status: "pass", summary: "must reject",
+      surface_trust_refs: [{
+        artifact_kind: "trust.bundle", artifact_ref: relocated, claim_status: "accepted",
+        freshness: { status: "fresh" }, authority: { producer: "surface-local" },
+        integrity: { status: "matched" }, status: "pass", summary: "accepted",
+      }],
+    }, false, undefined, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeFinding({ file_refs: [hardlink] }, root), /narrative trust isolation \(#619\)/);
+    assert.throws(() => normalizeLearning({ source_refs: [relocated], facts: [], routing: [], outcome: "unknown", correction: { needed: false, evidence: "none" } }, "2026-07-14T00:00:00.000Z", root), /narrative trust isolation \(#619\)/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("normalizeEvidenceRefs: rejects non-arrays and legacy string refs; passes valid arrays", () => {
   assert.throws(() => normalizeEvidenceRefs("nope", "refs"), /must be an array/);
   assert.throws(() => normalizeEvidenceRefs(["legacy"], "refs"), /legacy string refs are not supported/);
@@ -230,3 +363,62 @@ test("buildGateInquiryRecords: emits a single missed_block record for an empty b
   assert.equal(records.length, 1);
   assert.equal(records[0].answer.value.calibration, "missed_block");
 });
+
+// ── #634: writer-observed execution entries in the capture fold ─────────────
+test("writer-observed pass lifts an otherwise ambiguous command to pass", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm run test:unit", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+    { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+  ]);
+  assert.equal(fold.get("npm run test:unit").observedResult, "pass");
+});
+
+test("a hook-observed fail is never buried by a writer-observed pass, in either order", () => {
+  for (const entries of [
+    [
+      { command: "npm run test:unit", observedResult: "fail", exitCode: 1, source: "postToolUse-capture" },
+      { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+    ],
+    [
+      { command: "npm run test:unit", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+      { command: "npm run test:unit", observedResult: "fail", exitCode: 1, source: "postToolUse-capture" },
+    ],
+  ]) {
+    const fold = reduceCaptureLogByCommand(entries);
+    assert.equal(fold.get("npm run test:unit").observedResult, "fail");
+    // Review finding (#634): fail/0 would be contradictory evidence (isError:true, exitCode:0) —
+    // the exit code must travel with the winning status, never a losing entry's.
+    assert.equal(fold.get("npm run test:unit").exitCode, 1);
+  }
+});
+
+test("when both entries carry the winning status the newer non-null exit code wins", () => {
+  const sticky = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "fail", exitCode: 2, source: "postToolUse-capture" },
+    { command: "npm test", observedResult: "fail", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(sticky.get("npm test").exitCode, 2);
+  const newer = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "fail", exitCode: 2, source: "postToolUse-capture" },
+    { command: "npm test", observedResult: "fail", exitCode: 3, source: "canonical-writer-execution" },
+  ]);
+  assert.equal(newer.get("npm test").exitCode, 3);
+});
+
+test("an ambiguous entry's null exit code never displaces the winning pass's code", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm test", observedResult: "pass", exitCode: 0, source: "canonical-writer-execution" },
+    { command: "npm test", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(fold.get("npm test").observedResult, "pass");
+  assert.equal(fold.get("npm test").exitCode, 0);
+});
+
+test("a writer-observed fail is sticky like any other observed fail", () => {
+  const fold = reduceCaptureLogByCommand([
+    { command: "npm run test:unit", observedResult: "fail", exitCode: 2, source: "canonical-writer-execution" },
+    { command: "npm run test:unit", observedResult: "ambiguous", exitCode: null, source: "postToolUse-capture" },
+  ]);
+  assert.equal(fold.get("npm run test:unit").observedResult, "fail");
+  assert.equal(fold.get("npm run test:unit").exitCode, 2);
+});

package/src/cli/trust-bundle-policy-order.test.mjs

@@ -12,8 +12,11 @@
 // Run: `npm run test:unit`. Requires @kontourai/surface (the bundle producer's dependency).
 import test from "node:test";
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
 
-import { buildTrustBundle } from "../../build/src/cli/workflow-sidecar.js";
+import { WORKFLOW_ACCEPTANCE_STATUSES } from "../../build/src/cli/public-contracts.js";
+import { buildTrustBundle, validateTrustBundle } from "../../build/src/cli/workflow-sidecar.js";
 
 const TS = "2026-07-02T00:00:00Z";
 
@@ -85,3 +88,133 @@ test("buildTrustBundle: same-kind checks with different command-presence get DIS
   assert.equal(statuses[cmdClaim.id], "verified");
   assert.equal(statuses[noCmdClaim.id], "verified");
 });
+
+test("workflow acceptance status contract stays aligned with the artifact schema", () => {
+  const schema = JSON.parse(fs.readFileSync(path.join(process.cwd(), "schemas", "workflow-acceptance.schema.json"), "utf8"));
+  assert.deepEqual(schema.properties.criteria.items.properties.status.enum, [...WORKFLOW_ACCEPTANCE_STATUSES]);
+});
+
+test("buildTrustBundle: malformed acceptance statuses remain pending and keep invariant identity at the plan step", async () => {
+  const flowAgentsDir = path.join(process.cwd(), ".kontourai", "flow-agents");
+  const malformedStatuses = [undefined, null, "", "PASS", " pass ", true, false, 0, 1, {}, [], "verified", "unknown"];
+  for (const [index, status] of malformedStatuses.entries()) {
+    const criterion = { id: `ac-malformed-${index}`, description: "The implementation satisfies the requested behavior" };
+    if (status !== undefined) criterion.status = status;
+    const bundle = await buildTrustBundle(
+      "acceptance-integrity",
+      TS,
+      [],
+      [criterion],
+      [],
+      undefined,
+      flowAgentsDir,
+      undefined,
+      { flowId: "builder.build", stepId: "plan" },
+    );
+    assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+
+    const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+    assert.ok(claim, "expected an acceptance criterion claim");
+    assert.equal(claim.claimType, "workflow.acceptance.criterion");
+    assert.equal(claim.subjectType, "flow-step");
+    assert.equal(claim.value, "pending");
+    assert.equal(claim.status, "proposed");
+    assert.equal(claim.metadata.criterion.status, "pending");
+    assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+    assert.deepEqual(await validateTrustBundle(bundle), { valid: true, errors: [], available: true });
+  }
+});
+
+test("buildTrustBundle: evidence-free acceptance pass cannot manufacture verified trust", async () => {
+  const bundle = await buildTrustBundle(
+    "acceptance-no-evidence",
+    TS,
+    [],
+    [{ id: "ac-no-evidence", description: "The behavior is complete", status: "pass", evidence_refs: [] }],
+    [],
+  );
+  assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+  const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+  assert.ok(claim, "expected an acceptance criterion claim");
+  assert.equal(claim.value, "pending");
+  assert.equal(claim.status, "proposed");
+  assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+});
+
+test("buildTrustBundle: pass metadata without observed execution remains pending", async () => {
+  const bundle = await buildTrustBundle(
+    "acceptance-forged-provenance",
+    TS,
+    [],
+    [{
+      id: "ac-forged",
+      description: "The behavior is complete",
+      status: "pass",
+      evidence_refs: [{ kind: "command", excerpt: "npm test", summary: "Claimed test command." }],
+      identity_version: 2,
+      verified_at: TS,
+      _observed_commands: [{
+        command: "npm test",
+        exit_code: 0,
+        output_sha256: "0".repeat(64),
+        test_count: 1,
+        execution_proof: { kind: "local-process-exit", runner: "npm", static_test_units: 1 },
+      }],
+    }],
+    [],
+  );
+  assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+  const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+  assert.ok(claim, "expected an acceptance criterion claim");
+  assert.equal(claim.value, "pending");
+  assert.equal(claim.status, "proposed");
+  assert.equal(bundle.evidence.filter((evidence) => evidence.claimId === claim.id).length, 0);
+  assert.equal(bundle.events.filter((event) => event.claimId === claim.id).length, 0);
+});
+
+test("buildTrustBundle: direct observed-command metadata cannot manufacture verified trust", async () => {
+  const flowAgentsDir = path.join(process.cwd(), ".kontourai", "flow-agents");
+  const criterion = {
+    id: "ac-stable",
+    description: "The accepted behavior remains independently verified",
+    status: "pass",
+    evidence_refs: [{ kind: "command", excerpt: "npm test", summary: "The observed test command passed." }],
+    identity_version: 2,
+    verified_at: TS,
+    _observed_commands: [{
+      command: "npm test",
+      exit_code: 0,
+      output_sha256: "0".repeat(64),
+      test_count: 1,
+      execution_proof: { kind: "local-process-exit", runner: "npm", static_test_units: 1 },
+    }],
+  };
+  const bundles = await Promise.all(["plan", "verify"].map((stepId) => buildTrustBundle(
+    "acceptance-stability",
+    TS,
+    [],
+    [criterion],
+    [],
+    undefined,
+    flowAgentsDir,
+    undefined,
+    { flowId: "builder.build", stepId },
+  )));
+
+  const claimIds = [];
+  for (const bundle of bundles) {
+    assert.ok(bundle, "buildTrustBundle returned null (is @kontourai/surface installed?)");
+    const claim = bundle.claims.find((candidate) => candidate.metadata?.origin === "acceptance");
+    assert.ok(claim, "expected an acceptance criterion claim");
+    assert.equal(claim.claimType, "workflow.acceptance.criterion");
+    assert.equal(claim.subjectType, "flow-step");
+    assert.equal(claim.value, "pending");
+    assert.equal(claim.status, "proposed");
+    const evidence = bundle.evidence.filter((candidate) => candidate.claimId === claim.id);
+    assert.equal(evidence.length, 0);
+    const event = bundle.events.find((candidate) => candidate.claimId === claim.id);
+    assert.equal(event, undefined);
+    claimIds.push(claim.id);
+  }
+  assert.equal(new Set(claimIds).size, 1, "acceptance claim identity changed across Builder gates");
+});