@sanning/proof 0.6.0 → 0.8.0

package/src/cli.ts

@@ -21,6 +21,8 @@ import { fileURLToPath } from "node:url";
 
 import { isAgentProofSpec, verifyAgentProofBundle } from "./agent-proof.js";
 import type { AgentProofResult } from "./agent-proof.js";
+import { CHAIN_READING_SCOPE, readChains, renderChainFinding } from "./chain.js";
+import type { ChainReading } from "./chain.js";
 import { composeExport } from "./compose.js";
 import type { ComposeExportOptions } from "./compose.js";
 import { utf8 } from "./crypto.js";
@@ -167,7 +169,12 @@ export async function runCli(argv: string[], io: Cli): Promise<number> {
     ...(content ? { content } : {}),
     ...(io.fetchImpl ? { fetchImpl: io.fetchImpl } : {}),
   });
-  const exit = reportEvidence(result, bundlePath, gateways, io);
+  // Read the chains from the SAME parsed bundle the verifier saw. Findings are
+  // evidence about the records in front of us, not a verdict: they are printed
+  // and they never move `exit`, because a chain is not a completeness proof and
+  // an exit code is exactly the kind of thing people read as one.
+  const chains = await readChains(parsed);
+  const exit = reportEvidence(result, bundlePath, gateways, io, chains);
   // Coverage is reported only once the bundle parsed far enough to have events
   // to compare against; over a MALFORMED bundle there is nothing to say.
   if (logs && result.status !== "malformed") reportLogsCoverage(logs, result, io);
@@ -664,6 +671,7 @@ function reportEvidence(
   path: string,
   gateways: string[],
   io: Cli,
+  chains: ChainReading,
 ): number {
   if (result.status === "malformed") {
     io.err(paint("MALFORMED", R) + `  ${path}`);
@@ -708,6 +716,8 @@ function reportEvidence(
     }
   }
 
+  reportChains(chains, io);
+
   if (result.export) {
     reportExport(result.export, io);
   }
@@ -725,6 +735,45 @@ function reportEvidence(
   return mapStatusToExit(result.status, result.errors);
 }
 
+/**
+ * The chain block: what following each record's pointer to the record before it
+ * showed, over the records THIS bundle presents.
+ *
+ * Three deliberate choices, all of them about not overclaiming.
+ *
+ * 1. It prints the chains it READ, not just the findings. "3 chains, nothing to
+ *    report" and silence are different statements, and a reader that quietly
+ *    matched no records at all would produce the second one while covering
+ *    nothing.
+ * 2. It prints the scope sentence whenever it read a chain, findings or not.
+ *    "Delete an event and the next pointer dangles" is true; "so the bundle is
+ *    complete" does not follow, and two customer-facing documents had already
+ *    made that leap. The limit travels with the result or it gets dropped.
+ * 3. It does not touch the exit code. Findings are evidence; the exit code is
+ *    the verdict surface, and the pinned 0/1/2/3 contract stays exactly what it
+ *    was. A dangling link is something for a person to look at, not a machine
+ *    decision this check is entitled to make.
+ */
+function reportChains(reading: ChainReading, io: Cli): void {
+  if (reading.chains.length === 0) return;
+
+  io.out("");
+  io.out(paint("  Event chains", DIM));
+  for (const c of reading.chains) {
+    const where = c.namespace === undefined ? "record" : `${c.namespace} metadata`;
+    io.out(
+      paint(
+        `    ${c.chainKey}  ${count(c.events, "record", "records")} present  (linked in ${where})`,
+        DIM,
+      ),
+    );
+  }
+  for (const f of reading.findings) {
+    io.out(paint(`    ! ${renderChainFinding(f, "this bundle")}`, Y));
+  }
+  io.out(paint(`    ${CHAIN_READING_SCOPE}`, DIM));
+}
+
 // Render the export-specific block (evidence-export.md §5): source-bundle
 // linkage, cached-vs-recomputed verdict agreement, and each embedded operator
 // attestation (RSA-PSS sig · operator-address binding · data_hash binding).