@dogfood-lab/ingest 1.4.0 → 1.6.0

package/run.js

@@ -22,14 +22,44 @@ import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 
 import { verify } from '@dogfood-lab/verify';
-import { stubProvenance, githubProvenance } from '@dogfood-lab/verify/validators/provenance.js';
+import { stubProvenance, provenanceForProvider } from '@dogfood-lab/verify/validators/provenance.js';
 import { logStage as sharedLogStage } from '@dogfood-lab/dogfood-swarm/lib/log-stage.js';
 import { loadGlobalPolicy, loadRepoPolicy, loadScenarios } from './load-context.js';
 import { isDuplicate, writeRecord, computeRecordPath } from './persist.js';
 import { rebuildIndexes } from './rebuild-indexes.js';
+import { verifyChain, formatChainResult } from './verify-chain.js';
+import { handleAnchorCompute, handleAnchorPost, handleAnchorVerify } from './anchor/cli.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Resolve the REAL provenance adapter for a submission, routed by
+ * `submission.source.provider` (github | gitlab), sourcing the provider's token
+ * from the environment. Returns `{ provenance }` on success or `{ err }` (a
+ * structured, operator-legible Error the caller surfaces via emitCliErrorEvent
+ * + exit 2). The adapter registry (`provenanceForProvider`) is the single
+ * provider-keyed seam; a provider in the schema enum without a registered
+ * adapter fails here loudly rather than silently skipping verification.
+ *
+ * @param {object} submission
+ * @returns {{ provenance: object } | { err: Error }}
+ */
+function resolveProviderProvenance(submission) {
+  const provider = (submission && submission.source && submission.source.provider) || 'github';
+  const factory = provenanceForProvider(provider);
+  if (!factory) {
+    return { err: new Error(`unknown provenance provider '${provider}' — no adapter registered (supported: github, gitlab).`) };
+  }
+  const token = provider === 'gitlab'
+    ? (process.env.GITLAB_TOKEN || process.env.CI_JOB_TOKEN)
+    : (process.env.GITHUB_TOKEN || process.env.GH_TOKEN);
+  if (!token) {
+    const need = provider === 'gitlab' ? 'GITLAB_TOKEN or CI_JOB_TOKEN' : 'GITHUB_TOKEN or GH_TOKEN';
+    return { err: new Error(`real provenance for provider '${provider}' requires ${need} in the environment.`) };
+  }
+  return { provenance: factory(token) };
+}
+
 /**
  * SEED-1 (d3-ingest-003) — posixify a path-shaped value at the operator/log
  * SERIALIZATION boundary. `computeRecordPath`/`writeRecord` return OS-native
@@ -513,6 +543,25 @@ if (isMain) {
   let submissionJson;
   let provenanceMode = null;
   let verifyOnlyFlag = false;
+  let verifyChainFlag = false;
+  // --verify-chain modifiers (only meaningful alongside it):
+  //   --reconcile → collectOrphans (INGEST-PROACT-001): also flag on-disk records
+  //     absent from the ledger (a torn persist). Makes the audit fail on orphans.
+  //   --all → collectAllBreaks (INGEST-PROACT-004): continue past the first
+  //     per-record-independent break and report every break in one pass.
+  let reconcileFlag = false;
+  let allBreaksFlag = false;
+  // Anchor verbs (optional, off-by-default, operator-run). --anchor-compute and
+  // --anchor-verify are fully offline (never import xrpl); --anchor-post lazily
+  // loads the optional xrpl package and needs XRPL_SEED.
+  let anchorComputeFlag = false;
+  let anchorPostFlag = false;
+  let anchorVerifyFlag = false;
+  let anchorMode = 'since-last';
+  let anchorAlgo = null;
+  let anchorNetwork = null;
+  let anchorTxFile = null;
+  let anchorTrustedAccounts = [];
   const positionalArgs = [];
 
   for (let i = 0; i < args.length; i++) {
@@ -532,7 +581,13 @@ if (isMain) {
         arg = arg.slice(0, eq);
       }
     }
-    const hasValue = inlineValue !== null || args[i + 1] !== undefined;
+    // A space-form value is the NEXT token only when it is not itself a flag —
+    // otherwise `--flag --next` would swallow `--next` as `--flag`'s value and
+    // silently drop it. A `--`-prefixed next token means this flag has no value,
+    // so it falls through to its "requires a value" path (for `--provenance`,
+    // the downstream "--provenance flag is required" error).
+    const nextIsValue = args[i + 1] !== undefined && !args[i + 1].startsWith('--');
+    const hasValue = inlineValue !== null || nextIsValue;
     const takeValue = () => (inlineValue !== null ? inlineValue : args[++i]);
 
     if (arg === '--provenance' && hasValue) {
@@ -563,11 +618,131 @@ if (isMain) {
       // F-252714-058: dry-run the pipeline without writing or rebuilding
       // indexes. CI / operators preview what WOULD have been persisted.
       verifyOnlyFlag = true;
+    } else if (arg === '--verify-chain') {
+      // Integrity chain v1: verify the append-only tamper-evident ledger at
+      // indexes/integrity/chain.jsonl, fully offline. No submission, no stdin,
+      // no provenance — a standalone audit command.
+      verifyChainFlag = true;
+    } else if (arg === '--reconcile') {
+      // Modifier for --verify-chain: also reconcile on-disk records against the
+      // ledger and fail on any orphan (INGEST-PROACT-001).
+      reconcileFlag = true;
+    } else if (arg === '--all') {
+      // Modifier for --verify-chain: report every per-record-independent break
+      // instead of stopping at the first (INGEST-PROACT-004).
+      allBreaksFlag = true;
+    } else if (arg === '--anchor-compute') {
+      // Optional XRPL anchor: compute + write the next anchor manifest. Offline.
+      anchorComputeFlag = true;
+    } else if (arg === '--anchor-post') {
+      // Optional XRPL anchor: compute if needed + post to XRPL. Needs the
+      // optional xrpl package (lazily loaded) and XRPL_SEED.
+      anchorPostFlag = true;
+    } else if (arg === '--anchor-verify') {
+      // Optional XRPL anchor: verify local manifests + run the truncation check.
+      // Offline reports honest NOT-verified for the on-chain leg.
+      anchorVerifyFlag = true;
+    } else if (arg === '--anchor-all') {
+      // Genesis snapshot mode for compute/post (covers the whole chain).
+      anchorMode = 'all';
+    } else if (arg === '--anchor-algo' && hasValue) {
+      anchorAlgo = takeValue();
+    } else if (arg === '--anchor-network' && hasValue) {
+      anchorNetwork = takeValue();
+    } else if (arg === '--anchor-tx' && hasValue) {
+      // Path to a JSON file containing a fetched XRPL tx (with Memos) for the
+      // on-chain leg of --anchor-verify. Offline-honest: omit it to run the
+      // truncation check only.
+      anchorTxFile = takeValue();
+    } else if (arg === '--anchor-trusted' && hasValue) {
+      // Comma-separated trusted anchor accounts (UNIONed with the bundled list).
+      anchorTrustedAccounts = takeValue().split(',').map((s) => s.trim()).filter(Boolean);
     } else {
       positionalArgs.push(args[i]);
     }
   }
 
+  // --verify-chain is a standalone, side-effect-free audit: it reads only the
+  // ledger + the record files it references, takes no submission, reads no
+  // stdin, and needs no provenance adapter. Handle it BEFORE the stdin read and
+  // provenance resolution so `node run.js --verify-chain` does not block on
+  // stdin or demand a --provenance flag. Exit 0 when the chain verifies, 1 on
+  // the first break (operator-legible output, no raw stack traces).
+  if (verifyChainFlag) {
+    const result = verifyChain(repoRoot, {
+      collectOrphans: reconcileFlag,
+      collectAllBreaks: allBreaksFlag,
+    });
+    logStage(result.ok ? 'verify_chain_complete' : 'error', {
+      correlation_id: synthCorrelationId(),
+      ...(result.ok ? {} : { failed_stage: 'verify_chain' }),
+      verified: result.count,
+      head_digest: result.head_digest,
+      chain_ok: result.ok,
+      ...(result.break ? { break_seq: result.break.seq, break_reason: result.break.reason } : {}),
+      // INGEST-PROACT-004 / -001: surface the full corruption scope when the
+      // operator asked for it, so a grep of the NDJSON shows how many breaks and
+      // orphans were found, not just the first break.
+      ...(Array.isArray(result.breaks) ? { break_count: result.breaks.length } : {}),
+      ...(Array.isArray(result.orphans) ? { orphan_count: result.orphans.length } : {})
+    });
+    const lines = formatChainResult(result);
+    if (result.ok) {
+      for (const line of lines) console.log(line);
+    } else {
+      for (const line of lines) console.error(line);
+    }
+    process.exit(result.ok ? 0 : 1);
+  }
+
+  // Optional XRPL anchor verbs — operator-run, off by default, NOT in the normal
+  // ingest/CI path. Like --verify-chain these are standalone audit/operations:
+  // no submission, no stdin, no provenance adapter. --anchor-compute and
+  // --anchor-verify are fully offline (never import xrpl); --anchor-post lazily
+  // loads the optional xrpl package and needs XRPL_SEED. Each handler returns
+  // { ok, exitCode, lines, event } and run.js owns the console + logStage + exit.
+  if (anchorComputeFlag || anchorPostFlag || anchorVerifyFlag) {
+    const correlation_id = synthCorrelationId();
+    let result;
+    if (anchorComputeFlag) {
+      result = handleAnchorCompute(repoRoot, {
+        mode: anchorMode,
+        ...(anchorAlgo ? { algo: anchorAlgo } : {}),
+        ...(anchorNetwork ? { network: anchorNetwork } : {}),
+      });
+    } else if (anchorPostFlag) {
+      result = await handleAnchorPost(repoRoot, {
+        mode: anchorMode,
+        ...(anchorNetwork ? { network: anchorNetwork } : {}),
+      });
+    } else {
+      // --anchor-verify: optionally load a fetched tx JSON for the on-chain leg.
+      let tx;
+      if (anchorTxFile) {
+        const { readFileSync } = await import('node:fs');
+        try {
+          tx = JSON.parse(readFileSync(resolve(anchorTxFile), 'utf-8'));
+        } catch (err) {
+          emitCliErrorEvent({
+            failedStage: 'anchor_verify_read_tx',
+            correlationId: correlation_id,
+            err,
+            humanPrefix: 'could not read --anchor-tx file'
+          });
+          process.exit(2);
+        }
+      }
+      result = handleAnchorVerify(repoRoot, { tx, trustedAnchorAccounts: anchorTrustedAccounts });
+    }
+
+    // logStage strips any inner `stage:` field (the positional name wins), so
+    // spreading result.event — which carries its own `stage` — is safe.
+    logStage(result.event.stage, { correlation_id, ...result.event });
+    const sink = result.exitCode === 0 ? console.log : console.error;
+    for (const line of result.lines) sink(line);
+    process.exit(result.exitCode);
+  }
+
   if (!submissionJson) {
     // Read from stdin
     const chunks = [];
@@ -629,32 +804,36 @@ if (isMain) {
     console.error('WARNING: Using stub provenance (test/dev only). Records will NOT have real provenance verification.');
     provenance = stubProvenance;
   } else if (provenanceMode === 'github') {
-    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
-    if (!token) {
+    // --provenance=github selects REAL provenance; the actual provider is taken
+    // from submission.source.provider, so a GitLab submission is confirmed via
+    // gitlabProvenance end-to-end (the adapter registry keys on the provider).
+    const resolved = resolveProviderProvenance(submission);
+    if (resolved.err) {
       emitCliErrorEvent({
         failedStage: 'cli_provenance_resolve',
         correlationId: cliCorrelationId,
         submissionId: submission && submission.run_id ? submission.run_id : null,
-        err: new Error('--provenance=github requires GITHUB_TOKEN or GH_TOKEN environment variable.'),
+        err: resolved.err,
         humanPrefix: 'provenance precondition unmet'
       });
       process.exit(2);
     }
-    provenance = githubProvenance(token);
+    provenance = resolved.provenance;
   } else if (process.env.CI === 'true' || process.env.GITHUB_ACTIONS === 'true') {
-    // In CI without explicit flag: default to github provenance, fail if no token
-    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
-    if (!token) {
+    // In CI without an explicit flag: default to real provenance, routed by the
+    // submission's source.provider (github | gitlab).
+    const resolved = resolveProviderProvenance(submission);
+    if (resolved.err) {
       emitCliErrorEvent({
         failedStage: 'cli_provenance_resolve',
         correlationId: cliCorrelationId,
         submissionId: submission && submission.run_id ? submission.run_id : null,
-        err: new Error('Running in CI without --provenance flag and no GITHUB_TOKEN. Cannot verify provenance.'),
+        err: resolved.err,
         humanPrefix: 'provenance precondition unmet'
       });
       process.exit(2);
     }
-    provenance = githubProvenance(token);
+    provenance = resolved.provenance;
   } else {
     emitCliErrorEvent({
       failedStage: 'cli_provenance_resolve',

package/verify-chain.js

@@ -0,0 +1,316 @@
+/**
+ * Chain verifier — the offline tamper-evidence gate.
+ *
+ * `verifyChain(repoRoot)` reads the append-only ledger at
+ * `indexes/integrity/chain.jsonl` and, FULLY OFFLINE (no network, no GitHub
+ * API), proves the chain is internally consistent:
+ *
+ *   1. For each entry, load the record file at `entry.path` and recompute its
+ *      digest with the SAME `submissionDigest` helper persist used. Assert it
+ *      equals BOTH `entry.submission_digest` (the ledger's claim) AND
+ *      `record.integrity.submission_digest` (the record's self-claim). All three
+ *      must agree — a tamper that touches the record but not the ledger, or the
+ *      ledger but not the record, breaks one of these equalities.
+ *   2. Assert `entry.prev_digest` equals the PREVIOUS entry's
+ *      `submission_digest` (GENESIS_DIGEST for seq 0) — the chain link.
+ *   3. Assert `seq` is 0,1,2,… strictly monotonic from 0.
+ *
+ * On the FIRST break it stops and reports `{ seq, run_id, reason }`; the caller
+ * (`--verify-chain` in run.js, or any consumer) exits non-zero. On success it
+ * returns the record count and head digest.
+ *
+ * Honesty (threat model): this is tamper-EVIDENT, not tamper-PROOF. An actor
+ * with the ingest write credential can rewrite a record, recompute its digest,
+ * and rewrite the matching ledger line — that re-verifies clean. The verifier
+ * catches any mutation to a record or ledger entry that is NOT consistently
+ * reflected in BOTH (an out-of-band edit, disk corruption, a partial restore, a
+ * push that touched a record but not the chain), and it catches middle-deletion,
+ * reorder, and forged-insertion (they break the seq run or the prev-link).
+ *
+ * KNOWN LIMITATION — tail truncation. Removing the most-recent entries (and
+ * their record files) leaves a SHORTER but internally-consistent chain, which
+ * verifies OK: the offline verifier has no external record of the expected head
+ * or leaf-count, so it can prove what remains is consistent but NOT that the
+ * chain is COMPLETE. Detecting truncation requires an external anchor of the
+ * head/count outside the writer's control — exactly what the optional XRPL
+ * anchor provides (its on-chain Merkle root + leaf count make any truncation
+ * BELOW an anchored point detectable). The offline chain alone is a completeness
+ * floor for in-place tampering, not a defense against tail truncation.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+import { submissionDigest, GENESIS_DIGEST } from './lib/integrity.js';
+import { readChainManifest } from './lib/chain-manifest.js';
+import { findJsonFiles } from './rebuild-indexes.js';
+
+/**
+ * @typedef {object} ChainBreak
+ * @property {number} seq - The seq at which verification failed.
+ * @property {string|null} run_id - The run_id of the failing entry, if known.
+ * @property {string} reason - Operator-legible description of what failed.
+ */
+
+/**
+ * @typedef {object} ChainOrphan
+ * @property {string|null} run_id - The orphan record's run_id (from its
+ *   integrity block or its body), if known.
+ * @property {number|null} seq - The orphan record's self-claimed integrity.seq.
+ * @property {string} path - Repo-relative, forward-slashed path to the orphan file.
+ * @property {string} reason - Operator-legible description of why it is an orphan.
+ */
+
+/**
+ * @typedef {object} ChainVerifyResult
+ * @property {boolean} ok - True when the whole chain verifies (and, when
+ *   collectOrphans is set, no orphan records exist).
+ * @property {number} count - Number of entries verified (0 for an empty chain).
+ * @property {string} head_digest - submission_digest of the last entry, or
+ *   GENESIS_DIGEST for an empty chain.
+ * @property {ChainBreak|null} break - First break, or null when ok.
+ * @property {ChainBreak[]} [breaks] - All independent breaks (only present when
+ *   `collectAllBreaks` is set). The first element equals `break`.
+ * @property {ChainOrphan[]} [orphans] - Records on disk but absent from the
+ *   ledger (only present when `collectOrphans` is set).
+ */
+
+/**
+ * Verify the integrity chain at `<repoRoot>/indexes/integrity/chain.jsonl`.
+ *
+ * @param {string} repoRoot - Absolute path to the testing-os repo root.
+ * @param {object} [opts]
+ * @param {boolean} [opts.collectAllBreaks=false] - INGEST-PROACT-004: continue
+ *   past the FIRST break and return a `breaks[]` array of every
+ *   per-record-independent break (digest-mismatch, missing-file). The default
+ *   (false) stops at the first break — the fail-fast CI gate semantics. A
+ *   structural break (non-monotonic seq, broken prev-link) still stops the
+ *   walk even under this flag, because everything after it is unverifiable
+ *   relative to a now-untrustworthy chain order.
+ * @param {boolean} [opts.collectOrphans=false] - INGEST-PROACT-001: after the
+ *   chain walk, reconcile the on-disk records against the ledger and return an
+ *   `orphans[]` array of any record file whose seq/run_id is absent from the
+ *   ledger (a torn write between record-write and ledger-append). An orphan
+ *   makes the result `ok: false` — the audit DETECTS the orphan instead of
+ *   silently passing while a real record lives outside the tamper-evident chain.
+ * @returns {ChainVerifyResult}
+ */
+export function verifyChain(repoRoot, opts = {}) {
+  const collectAllBreaks = opts.collectAllBreaks === true;
+  const collectOrphans = opts.collectOrphans === true;
+
+  let entries;
+  try {
+    entries = readChainManifest(repoRoot);
+  } catch (err) {
+    // A corrupt (non-JSON) manifest line is itself a tamper signal. We cannot
+    // trust the ledger at all here, so orphan reconciliation is not meaningful.
+    const brk = { seq: -1, run_id: null, reason: err.message };
+    return {
+      ok: false,
+      count: 0,
+      head_digest: GENESIS_DIGEST,
+      break: brk,
+      ...(collectAllBreaks ? { breaks: [brk] } : {}),
+      ...(collectOrphans ? { orphans: [] } : {}),
+    };
+  }
+
+  const headDigest = entries.length === 0
+    ? GENESIS_DIGEST
+    : (entries[entries.length - 1].submission_digest ?? GENESIS_DIGEST);
+
+  const breaks = [];
+  let prevDigest = GENESIS_DIGEST;
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const seq = entry.seq;
+    const runId = entry.run_id ?? null;
+    const record = (reason) => breaks.push({ seq, run_id: runId, reason });
+
+    // (3) Monotonic seq and (2) chain-link are STRUCTURAL: a break here means
+    // the chain order itself is untrustworthy, so everything downstream is
+    // unverifiable relative to it. Record the break and stop — even under
+    // collectAllBreaks — rather than emitting a cascade of meaningless
+    // downstream prev-link errors.
+    if (seq !== i) {
+      record(`seq is not monotonic: expected ${i}, found ${seq}`);
+      break;
+    }
+    if (entry.prev_digest !== prevDigest) {
+      record(`broken prev_digest link: expected ${prevDigest}, found ${entry.prev_digest}`);
+      break;
+    }
+
+    // (1) Per-record-INDEPENDENT checks: missing-file and digest-mismatch.
+    // Each is judged on this record alone, so under collectAllBreaks we record
+    // the break and CONTINUE to surface the full corruption scope. Under the
+    // default we record the first and stop.
+    const recordPath = join(repoRoot, entry.path);
+    if (!existsSync(recordPath)) {
+      record(`record file missing at ${entry.path} (could not read to recompute digest)`);
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(readFileSync(recordPath, 'utf-8'));
+    } catch (err) {
+      record(`record file at ${entry.path} is not valid JSON: ${err.message}`);
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
+    }
+
+    const recomputed = submissionDigest(parsed);
+    if (recomputed !== entry.submission_digest) {
+      record(
+        `digest mismatch: recomputed ${recomputed} but manifest claims ${entry.submission_digest} ` +
+        `— record at ${entry.path} was modified after persist`
+      );
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
+    }
+
+    const selfDigest = parsed.integrity?.submission_digest;
+    if (selfDigest !== recomputed) {
+      record(
+        `record self-digest mismatch: record.integrity.submission_digest is ` +
+        `${selfDigest ?? '(absent)'} but recomputed ${recomputed} — record at ${entry.path} ` +
+        `was modified after persist`
+      );
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
+    }
+
+    prevDigest = entry.submission_digest;
+  }
+
+  const orphans = collectOrphans ? collectOrphanRecords(repoRoot, entries) : null;
+
+  const ok = breaks.length === 0 && (orphans === null || orphans.length === 0);
+  return {
+    ok,
+    count: entries.length,
+    head_digest: headDigest,
+    break: breaks.length > 0 ? breaks[0] : null,
+    ...(collectAllBreaks ? { breaks } : {}),
+    ...(collectOrphans ? { orphans } : {}),
+  };
+}
+
+/**
+ * INGEST-PROACT-001 — reconcile on-disk records against the ledger.
+ *
+ * Walks every `*.json` under `records/` (accepted AND `_rejected/`) and flags
+ * any record file whose `(run_id, seq)` identity is absent from the ledger.
+ * Such a file is an ORPHAN: persist wrote the record but the ledger append did
+ * not happen (a crash in the torn window between the two steps), so the record
+ * exists OUTSIDE the tamper-evident chain and the plain chain-walk is blind to
+ * it. The chain-manifest's own ledger lines are NOT under `records/`, so they
+ * are never mistaken for orphans.
+ *
+ * @param {string} repoRoot
+ * @param {Array<object>} entries - The ledger entries (already read).
+ * @returns {ChainOrphan[]}
+ */
+function collectOrphanRecords(repoRoot, entries) {
+  // Index the ledger by run_id and by repo-relative path so a record matches if
+  // EITHER identity is present — a record is ledgered as long as its line exists.
+  const ledgerRunIds = new Set();
+  const ledgerPaths = new Set();
+  for (const e of entries) {
+    if (e.run_id) ledgerRunIds.add(e.run_id);
+    if (e.path) ledgerPaths.add(e.path);
+  }
+
+  const orphans = [];
+  const recordsDir = join(repoRoot, 'records');
+  for (const absPath of findJsonFiles(recordsDir)) {
+    const relPath = relative(repoRoot, absPath).split(sep).join('/');
+    if (ledgerPaths.has(relPath)) continue;
+
+    let record;
+    try {
+      record = JSON.parse(readFileSync(absPath, 'utf-8'));
+    } catch {
+      // A record file we cannot even parse, that is also absent from the ledger,
+      // is still an orphan — report it with what little identity we have.
+      orphans.push({
+        run_id: null,
+        seq: null,
+        path: relPath,
+        reason: `record file present on disk but absent from the ledger, and not valid JSON`,
+      });
+      continue;
+    }
+
+    const runId = record.run_id ?? null;
+    if (runId && ledgerRunIds.has(runId)) continue;
+
+    orphans.push({
+      run_id: runId,
+      seq: record.integrity?.seq ?? null,
+      path: relPath,
+      reason:
+        `record present on disk but absent from the ledger — a torn persist ` +
+        `(record written, ledger append missed). Re-run ingest for this record ` +
+        `or rebuild the chain to admit it into the tamper-evident ledger.`,
+    });
+  }
+
+  return orphans;
+}
+
+/**
+ * Render a verifyChain result as operator-legible lines (no raw stack traces).
+ * Returned as an array so callers can choose the sink (console.log/console.error).
+ *
+ * @param {ChainVerifyResult} result
+ * @returns {string[]}
+ */
+export function formatChainResult(result) {
+  if (result.ok) {
+    const lines = [
+      `integrity chain OK: ${result.count} record(s) verified`,
+      `head digest: ${result.head_digest}`,
+    ];
+    if (Array.isArray(result.orphans)) {
+      lines.push(`reconciliation: 0 orphan record(s) on disk`);
+    }
+    return lines;
+  }
+
+  const lines = [];
+
+  // INGEST-PROACT-004: when collectAllBreaks populated breaks[], list every
+  // independent break so the operator sees the full corruption scope in one
+  // pass. Otherwise report the single first break (the CI-gate default).
+  const allBreaks = Array.isArray(result.breaks) ? result.breaks : (result.break ? [result.break] : []);
+  if (allBreaks.length > 1) {
+    lines.push(`integrity chain BROKEN: ${allBreaks.length} break(s) found`);
+    for (const b of allBreaks) {
+      lines.push(`  - seq ${b.seq}${b.run_id ? ` (run_id: ${b.run_id})` : ''}: ${b.reason}`);
+    }
+  } else if (allBreaks.length === 1) {
+    const b = allBreaks[0];
+    lines.push(`integrity chain BROKEN at seq ${b.seq}${b.run_id ? ` (run_id: ${b.run_id})` : ''}`);
+    lines.push(`reason: ${b.reason}`);
+  }
+
+  // INGEST-PROACT-001: an orphan makes the result not-ok even with zero chain
+  // breaks — name each orphan file + run_id and the recovery action.
+  if (Array.isArray(result.orphans) && result.orphans.length > 0) {
+    lines.push(`reconciliation: ${result.orphans.length} orphan record(s) on disk but absent from the ledger`);
+    for (const o of result.orphans) {
+      lines.push(`  - ${o.path}${o.run_id ? ` (run_id: ${o.run_id})` : ''}: ${o.reason}`);
+    }
+  }
+
+  return lines;
+}