@dogfood-lab/ingest 1.3.2 → 1.5.0

package/run.js

@@ -17,19 +17,70 @@
  * - regenerate indexes
  */
 
-import { resolve, dirname } from 'node:path';
+import { resolve, dirname, sep } from 'node:path';
 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
+ * paths (backslash-separated, absolute, on win32) because those values are
+ * also used for real filesystem operations. But the moment a path crosses into
+ * CLI JSON output, NDJSON log lines, or a downstream report
+ * (dogfood-swarm persist.js records `report.dogfood.path`), it must be
+ * forward-slash so operators and log pivots see one canonical shape across
+ * OSes — and so a copy-paste into a raw.githubusercontent URL is not a broken
+ * link. We posixify ONLY here, at the emit sites, leaving the returned fs paths
+ * OS-native for the filesystem layer. Mirrors the boundary-normalize doctrine
+ * already used in rebuild-indexes.js and parse-regression-pins.js. NEVER a
+ * win32-skip.
+ *
+ * @param {string|null} p
+ * @returns {string|null}
+ */
+function posixifyPath(p) {
+  return typeof p === 'string' ? p.split(sep).join('/') : p;
+}
+
 /**
  * Emit a single structured stage-transition log line via the shared helper.
  *
@@ -238,7 +289,10 @@ export async function ingest(submission, options) {
   logStage('persist_complete', {
     submission_id: submissionId,
     correlation_id,
-    path,
+    // d3-ingest-003: posixify at the log boundary — `path` is OS-native from
+    // writeRecord (used for the fs write); the NDJSON log surface gets forward
+    // slashes so log pivots are byte-identical across OSes.
+    path: posixifyPath(path),
     written,
     duplicate: !written,
     duration_ms: Date.now() - persistStart
@@ -281,11 +335,12 @@ export async function ingest(submission, options) {
         failed_stage: 'rebuild_indexes',
         message: err.message,
         stack: truncatedStack,
-        record_persisted_at: path,
+        // d3-ingest-003: operator-facing path → posixify at the log boundary.
+        record_persisted_at: posixifyPath(path),
         recovery: 'next ingest will trigger a full rebuild of indexes/'
       });
       console.error(
-        `WARNING: record persisted at ${path}, but index rebuild failed: ${err.message}\n` +
+        `WARNING: record persisted at ${posixifyPath(path)}, but index rebuild failed: ${err.message}\n` +
         `         indexes/ may be stale until next ingest. To force rebuild now, re-run any test ingest.\n` +
         `         stack: ${stackPreview}`
       );
@@ -429,7 +484,10 @@ export async function verifyOnly(submission, options) {
     submission_id: submissionId,
     correlation_id,
     status: record.verification?.status ?? null,
-    would_persist_to
+    // d3-ingest-003: posixify at the log boundary. The returned
+    // `would_persist_to` below stays OS-native so callers that resolve it
+    // against the filesystem keep a real fs path.
+    would_persist_to: posixifyPath(would_persist_to)
   });
 
   return { record, would_persist_to, verify_only: true };
@@ -467,18 +525,61 @@ const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(__dirname
 
 if (isMain) {
   const args = process.argv.slice(2);
-  const repoRoot = resolve(__dirname, '../..');
+  // SEED-2 (d3-ingest-002) — make the CLI's repoRoot overridable so callers
+  // (notably dogfood-swarm's commands/persist.js execSync, and any test
+  // harness) can redirect every record write + index rebuild into a sandbox
+  // instead of the REAL working tree. Without this the only way to sandbox was
+  // a brittle source-copy of this file (the setupTempRunJs run.js-copy in
+  // d1b-001-cli-toplevel-error-event.test.js) that rewrote __dirname's `../..`
+  // walk. A production caller passes the real root explicitly; a test passes a
+  // temp dir; the default preserves the historical behavior when the env var
+  // is unset. resolve() makes a relative override absolute so the downstream
+  // join()s stay anchored.
+  const repoRoot = process.env.INGEST_REPO_ROOT
+    ? resolve(process.env.INGEST_REPO_ROOT)
+    : resolve(__dirname, '../..');
 
   // Parse CLI flags
   let submissionJson;
   let provenanceMode = null;
   let verifyOnlyFlag = false;
+  let verifyChainFlag = 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++) {
-    if (args[i] === '--provenance' && args[i + 1]) {
-      provenanceMode = args[++i];
-    } else if (args[i] === '--file' && args[i + 1]) {
+    // Accept BOTH the space form (`--flag value`) and the equals form
+    // (`--flag=value`). The prior parser matched only the space form, so a
+    // caller passing `--provenance=stub --file=...` (the shape dogfood-swarm's
+    // commands/persist.js builds for its execSync invocation) fell through to
+    // positionalArgs — `--provenance` then read as missing and the CLI exited 2
+    // ("--provenance flag is required"), silently breaking `swarm persist
+    // --ingest` on every platform. (dogfood-swarm self-audit follow-up.)
+    let arg = args[i];
+    let inlineValue = null;
+    if (arg.startsWith('--')) {
+      const eq = arg.indexOf('=');
+      if (eq !== -1) {
+        inlineValue = arg.slice(eq + 1);
+        arg = arg.slice(0, eq);
+      }
+    }
+    const hasValue = inlineValue !== null || args[i + 1] !== undefined;
+    const takeValue = () => (inlineValue !== null ? inlineValue : args[++i]);
+
+    if (arg === '--provenance' && hasValue) {
+      provenanceMode = takeValue();
+    } else if (arg === '--file' && hasValue) {
       const { readFileSync } = await import('node:fs');
       // D1B-001 family (operator-legibility): a --file read failure
       // (ENOENT/EACCES) routes through the structured error event and exits 2
@@ -488,7 +589,7 @@ if (isMain) {
       // correlation id here (the same pivot the JSON.parse catch uses when
       // there is no submission to derive a run_id from yet).
       try {
-        submissionJson = readFileSync(resolve(args[++i]), 'utf-8');
+        submissionJson = readFileSync(resolve(takeValue()), 'utf-8');
       } catch (err) {
         emitCliErrorEvent({
           failedStage: 'cli_read_file',
@@ -498,17 +599,121 @@ if (isMain) {
         });
         process.exit(2);
       }
-    } else if (args[i] === '--payload' && args[i + 1]) {
-      submissionJson = args[++i];
-    } else if (args[i] === '--verify-only') {
+    } else if (arg === '--payload' && hasValue) {
+      submissionJson = takeValue();
+    } else if (arg === '--verify-only') {
       // 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 === '--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);
+    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 } : {})
+    });
+    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 = [];
@@ -570,32 +775,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',
@@ -625,7 +834,10 @@ if (isMain) {
         status: result.record.verification.status,
         run_id: result.record.run_id ?? null,
         verdict: result.record.overall_verdict?.verified ?? null,
-        would_persist_to: result.would_persist_to,
+        // d3-ingest-003: posixify path-shaped CLI output so the operator
+        // contract is identical across OSes (a Windows backslash here breaks
+        // any downstream URL-build/string-match).
+        would_persist_to: posixifyPath(result.would_persist_to),
         verify_only: true,
         rejection_reasons: result.record.verification.rejection_reasons ?? []
       }));
@@ -648,7 +860,9 @@ if (isMain) {
       status: result.record.verification.status,
       run_id: result.record.run_id ?? null,
       verdict: result.record.overall_verdict?.verified ?? null,
-      path: result.path,
+      // d3-ingest-003: posixify path-shaped CLI output (same family as
+      // would_persist_to above). dogfood-swarm's persist.js pivots on this.
+      path: posixifyPath(result.path),
       written: result.written,
       rejection_reasons: result.record.verification.rejection_reasons ?? []
     }));

package/verify-chain.js

@@ -0,0 +1,178 @@
+/**
+ * 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 } from 'node:path';
+
+import { submissionDigest, GENESIS_DIGEST } from './lib/integrity.js';
+import { readChainManifest } from './lib/chain-manifest.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} ChainVerifyResult
+ * @property {boolean} ok - True when the whole chain verifies.
+ * @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.
+ */
+
+/**
+ * Verify the integrity chain at `<repoRoot>/indexes/integrity/chain.jsonl`.
+ *
+ * @param {string} repoRoot - Absolute path to the testing-os repo root.
+ * @returns {ChainVerifyResult}
+ */
+export function verifyChain(repoRoot) {
+  let entries;
+  try {
+    entries = readChainManifest(repoRoot);
+  } catch (err) {
+    // A corrupt (non-JSON) manifest line is itself a tamper signal.
+    return {
+      ok: false,
+      count: 0,
+      head_digest: GENESIS_DIGEST,
+      break: { seq: -1, run_id: null, reason: err.message },
+    };
+  }
+
+  if (entries.length === 0) {
+    // An empty chain is trivially valid: genesis with no entries.
+    return { ok: true, count: 0, head_digest: GENESIS_DIGEST, break: null };
+  }
+
+  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 fail = (reason) => ({
+      ok: false,
+      count: entries.length,
+      head_digest: entries[entries.length - 1].submission_digest ?? GENESIS_DIGEST,
+      break: { seq, run_id: runId, reason },
+    });
+
+    // (3) Monotonic seq: 0,1,2,…
+    if (seq !== i) {
+      return fail(`seq is not monotonic: expected ${i}, found ${seq}`);
+    }
+
+    // (2) Chain link: this entry's prev_digest must equal the previous entry's
+    // submission_digest (GENESIS for the first entry).
+    if (entry.prev_digest !== prevDigest) {
+      return fail(
+        `broken prev_digest link: expected ${prevDigest}, found ${entry.prev_digest}`
+      );
+    }
+
+    // (1) Load the record and recompute its digest.
+    const recordPath = join(repoRoot, entry.path);
+    if (!existsSync(recordPath)) {
+      return fail(`record file missing at ${entry.path} (could not read to recompute digest)`);
+    }
+
+    let record;
+    try {
+      record = JSON.parse(readFileSync(recordPath, 'utf-8'));
+    } catch (err) {
+      return fail(`record file at ${entry.path} is not valid JSON: ${err.message}`);
+    }
+
+    const recomputed = submissionDigest(record);
+
+    // The recomputed digest must equal the ledger's claim.
+    if (recomputed !== entry.submission_digest) {
+      return fail(
+        `digest mismatch: recomputed ${recomputed} but manifest claims ${entry.submission_digest} ` +
+        `— record at ${entry.path} was modified after persist`
+      );
+    }
+
+    // …AND the record's own self-certified digest.
+    const selfDigest = record.integrity?.submission_digest;
+    if (selfDigest !== recomputed) {
+      return fail(
+        `record self-digest mismatch: record.integrity.submission_digest is ` +
+        `${selfDigest ?? '(absent)'} but recomputed ${recomputed} — record at ${entry.path} ` +
+        `was modified after persist`
+      );
+    }
+
+    prevDigest = entry.submission_digest;
+  }
+
+  return {
+    ok: true,
+    count: entries.length,
+    head_digest: entries[entries.length - 1].submission_digest,
+    break: null,
+  };
+}
+
+/**
+ * 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) {
+    return [
+      `integrity chain OK: ${result.count} record(s) verified`,
+      `head digest: ${result.head_digest}`,
+    ];
+  }
+  const b = result.break;
+  return [
+    `integrity chain BROKEN at seq ${b.seq}${b.run_id ? ` (run_id: ${b.run_id})` : ''}`,
+    `reason: ${b.reason}`,
+  ];
+}