@dogfood-lab/ingest 1.5.0 → 1.6.0

package/README.md

@@ -59,6 +59,12 @@ Flags:
 - `--provenance=stub` — accept the claimed provenance without an API call. **Test/dev only — refused in CI.**
 - `--verify-only` — verify and report, write nothing.
 
+Standalone audit verb (no submission, no stdin, no `--provenance` — fully offline):
+
+- `--verify-chain` — verify the append-only tamper-evident ledger at `indexes/integrity/chain.jsonl`: every record's recomputed digest matches both the ledger's claim and the record's self-claim, the `prev_digest` links are intact, and `seq` is monotonic. Exits `0` when the chain verifies, `1` on the first break (operator-legible output, no raw stack traces).
+  - `--reconcile` — also walk `records/` and flag any record file whose `run_id`/`seq` is absent from the ledger (a torn persist that wrote the record but missed the ledger append). An orphan makes the audit exit `1` even with zero chain breaks.
+  - `--all` — continue past the first per-record-independent break (digest-mismatch, missing-file) and report every break in one pass. A structural break (non-monotonic `seq`, broken `prev_digest`) still stops the walk. The default stops at the first break — the fail-fast CI gate.
+
 Exit codes:
 
 - `0` — the record was accepted (and, without `--verify-only`, persisted).

package/anchor/cli.js

@@ -109,6 +109,36 @@ export async function handleAnchorPost(repoRoot, opts = {}) {
         event: { stage: 'error', failed_stage: 'anchor_post', engine_result: receipt.engine_result },
       };
     }
+
+    // INGEST-PROACT-002: the anchor LANDED on-chain (receipt.ok) but writing the
+    // receipt back into the local manifest failed. This is NOT a failure of the
+    // anchor — the on-chain fact is final. Surface a loud WARNING and exit 0 so
+    // the operator does not re-post (which would double-spend the fee). The event
+    // still carries tx_hash so the on-chain fact survives a log grep, and the
+    // recovery path (re-run --anchor-post to repair the manifest idempotently) is
+    // named in the message.
+    if (receipt.record_failed) {
+      return {
+        ok: true,
+        exitCode: 0,
+        lines: [
+          `anchor-post: anchor LANDED on-chain (tx ${receipt.tx_hash}) on ${receipt.network}`,
+          `  ledger_index: ${receipt.ledger_index ?? '(unavailable)'}`,
+          `  WARNING: recording the receipt locally FAILED: ${receipt.record_failed.error}`,
+          `  The on-chain anchor is final — do NOT re-post (it would spend another fee).`,
+          `  Recover: re-run --anchor-post to repair the manifest idempotently, or re-fetch`,
+          `  tx ${receipt.tx_hash} and run --anchor-verify --anchor-tx <file>.`,
+        ],
+        event: {
+          stage: 'anchor_post_record_failed',
+          anchor_seq: receipt.anchor_seq,
+          tx_hash: receipt.tx_hash,
+          ledger_index: receipt.ledger_index,
+          record_error: receipt.record_failed.error,
+        },
+      };
+    }
+
     return {
       ok: true,
       exitCode: 0,

package/anchor/post-anchor.js

@@ -222,10 +222,22 @@ export async function postAnchor(repoRoot, opts = {}) {
   // (1) Ensure there is a manifest to post. Re-running compute is idempotent
   //     (append-only). If nothing new is pending, post the LAST anchor manifest
   //     so a re-post after a transient network failure still binds the same root.
-  const computed = computeAnchor(repoRoot, { mode, network });
+  //
+  //     Thread the LAST anchor's algo into the recompute. compute defaults to the
+  //     v2 algo, so a chain previously anchored with the v1 (historical-
+  //     reproduction) algo would otherwise be recomputed as v2 — re-posting that
+  //     anchor would either bind a divergent v2 root or collide append-only with
+  //     the stored v1 manifest. Reproducing the SAME algo keeps a re-post
+  //     idempotent and binds the root the operator actually anchored.
+  const lastAnchor = readLastAnchor(repoRoot);
+  const computed = computeAnchor(repoRoot, {
+    mode,
+    network,
+    ...(lastAnchor?.algo ? { algo: lastAnchor.algo } : {}),
+  });
   let manifest;
   if (computed.empty) {
-    manifest = readLastAnchor(repoRoot);
+    manifest = lastAnchor;
     if (!manifest) {
       const e = new Error(`nothing to anchor: ${computed.reason}`);
       e.code = 'ANCHOR_NOTHING_TO_POST';
@@ -285,14 +297,31 @@ export async function postAnchor(repoRoot, opts = {}) {
 
   // (4) Record the on-chain facts back into the anchor manifest. Injected in
   //     tests; in production it patches the manifest file in place.
+  //
+  //     INGEST-PROACT-002: the anchor has ALREADY LANDED on-chain at this point
+  //     (receipt.ok) — an irreversible, fee-paid, citable fact. If recordPost
+  //     throws (disk full, EPERM, the manifest deleted between compute and post),
+  //     the on-chain landing MUST NOT be reported as a failure: a false failure
+  //     invites a re-post that double-spends the fee against a divergent state.
+  //     We keep receipt.ok true and attach a distinct `record_failed` outcome so
+  //     the caller surfaces a loud WARNING (exit 0, not exit 2) naming the
+  //     tx_hash and the idempotent recovery path. The on-chain fact survives on
+  //     the receipt regardless of whether the local manifest patch succeeded.
   if (receipt.ok && typeof opts.deps?.recordPost === 'function') {
-    opts.deps.recordPost(manifest.anchor_seq, {
-      tx_hash: receipt.tx_hash,
-      ledger_index: receipt.ledger_index,
-      close_time_iso: receipt.close_time_iso,
-      wallet_address: receipt.wallet_address,
-      network,
-    });
+    try {
+      opts.deps.recordPost(manifest.anchor_seq, {
+        tx_hash: receipt.tx_hash,
+        ledger_index: receipt.ledger_index,
+        close_time_iso: receipt.close_time_iso,
+        wallet_address: receipt.wallet_address,
+        network,
+      });
+    } catch (err) {
+      receipt.record_failed = {
+        error: err && err.message ? err.message : String(err),
+        code: err && err.code ? err.code : null,
+      };
+    }
   }
 
   return receipt;

package/load-context.js

@@ -201,6 +201,25 @@ export function localScenarioFetcher(repoRoot) {
  */
 export const GITHUB_SCENARIO_FETCH_TIMEOUT_MS = 30000;
 
+/**
+ * Default number of fetch attempts (INGEST-PROACT-003). A transient GitHub-API
+ * fault (5xx, 429, network blip) should not turn a loadable scenario into a hard
+ * rejection; a small bounded retry rides out the hiccup. Kept small — three
+ * attempts is enough to clear a momentary throttle without amplifying a real
+ * outage into a multi-minute stall (the AbortController timeout still bounds each
+ * attempt, and a 404/invalid-id is never retried).
+ */
+export const GITHUB_SCENARIO_FETCH_ATTEMPTS = 3;
+
+/** Initial backoff before the first retry (ms); doubles per attempt, capped. */
+const RETRY_BASE_MS = 250;
+const RETRY_MAX_MS = 2000;
+
+/** Default async backoff. Injectable (`opts.sleepImpl`) so tests run instantly. */
+function defaultSleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
 /**
  * GitHub scenario fetcher. Loads scenario definitions from a source repo
  * via the GitHub API at a specific commit SHA.
@@ -219,28 +238,45 @@ export const GITHUB_SCENARIO_FETCH_TIMEOUT_MS = 30000;
  * Both surfaces honour the per-request AbortController timeout
  * (`GITHUB_SCENARIO_FETCH_TIMEOUT_MS`, overridable via `opts.timeoutMs`).
  *
+ * INGEST-PROACT-003: each call makes up to `opts.attempts`
+ * (`GITHUB_SCENARIO_FETCH_ATTEMPTS`) tries with exponential backoff, retrying
+ * ONLY the transient classes — request timeout, HTTP 5xx, HTTP 429, and network
+ * rejects. A 404 (`not_found`), an `invalid_id`, and a `parse_error` are
+ * DEFINITIVE answers and are returned immediately without a retry (mirrors the
+ * EPERM/EBUSY-only discipline in `lib/rename-with-retry.js`). The backoff sleep
+ * is injectable (`opts.sleepImpl`) so tests do not actually wait.
+ *
  * @param {string} token - GitHub PAT
  * @param {string} repoSlug - e.g. "mcp-tool-shop-org/shipcheck"
  * @param {string} commitSha - Commit to fetch scenarios from
- * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch }} [opts]
+ * @param {{ timeoutMs?: number, fetchImpl?: typeof fetch, attempts?: number, sleepImpl?: (ms: number) => Promise<void> }} [opts]
  * @returns {{ fetch(scenarioId: string): Promise<object|null>, fetchWithReason(scenarioId: string): Promise<{ scenario: object|null, reason?: string }> }}
  */
 export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
   const timeoutMs = opts.timeoutMs ?? GITHUB_SCENARIO_FETCH_TIMEOUT_MS;
   const fetchImpl = opts.fetchImpl ?? ((url, init) => globalThis.fetch(url, init));
+  const attempts = opts.attempts ?? GITHUB_SCENARIO_FETCH_ATTEMPTS;
+  const sleep = opts.sleepImpl ?? defaultSleep;
 
   const [org, repo] = repoSlug.split('/');
-  if (!org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo)) {
+  // commitSha is interpolated into the authenticated (Bearer-token) GitHub API
+  // URL's `?ref=` — a shape guard (lowercase-hex, 7–40 chars) refuses anything
+  // that could re-target the ref or inject query params, matching how org/repo
+  // and scenarioId are guarded below. encodeURIComponent alone would NOT reject
+  // a re-targeted ref (e.g. a branch name), so the shape guard is the floor.
+  if (
+    !org || !repo || isUnsafeSegment(org) || isUnsafeSegment(repo) ||
+    typeof commitSha !== 'string' || !/^[0-9a-f]{7,40}$/.test(commitSha)
+  ) {
     return {
       async fetch() { return null; },
       async fetchWithReason() { return { scenario: null, reason: 'invalid_id' }; }
     };
   }
 
-  async function fetchWithReason(scenarioId) {
-    if (!/^[\w-]+$/.test(scenarioId)) {
-      return { scenario: null, reason: 'invalid_id' };
-    }
+  // One bounded attempt. Returns `{ scenario, reason, retryable }`; the loop
+  // below decides whether to retry on `retryable`.
+  async function attemptOnce(scenarioId) {
     const path = `dogfood/scenarios/${scenarioId}.yaml`;
     const url = `https://api.github.com/repos/${repoSlug}/contents/${path}?ref=${commitSha}`;
 
@@ -262,16 +298,20 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
         signal: controller.signal
       });
       if (!resp.ok) {
-        return { scenario: null, reason: 'not_found' };
+        // A 5xx server error or a 429 rate-limit is transient — retry. Any
+        // other non-ok (notably 404) is a definitive answer; do not retry.
+        const retryable = resp.status >= 500 || resp.status === 429;
+        return { scenario: null, reason: 'not_found', retryable };
       }
       text = await resp.text();
     } catch (err) {
       if (err && (err.name === 'AbortError' || err.code === 'ABORT_ERR')) {
-        return { scenario: null, reason: 'timeout' };
+        // A timed-out request may succeed on a retry.
+        return { scenario: null, reason: 'timeout', retryable: true };
       }
-      // Network reject, DNS failure, etc. — surface as not_found for
-      // back-compat with the legacy null contract.
-      return { scenario: null, reason: 'not_found' };
+      // Network reject, DNS failure, etc. — transient; surface as not_found
+      // for back-compat with the legacy null contract, but allow a retry.
+      return { scenario: null, reason: 'not_found', retryable: true };
     } finally {
       clearTimeout(timer);
     }
@@ -279,12 +319,28 @@ export function githubScenarioFetcher(token, repoSlug, commitSha, opts = {}) {
     try {
       const scenario = yaml.load(text);
       if (!scenario || typeof scenario !== 'object') {
-        return { scenario: null, reason: 'parse_error' };
+        return { scenario: null, reason: 'parse_error', retryable: false };
       }
       return { scenario };
     } catch {
-      return { scenario: null, reason: 'parse_error' };
+      return { scenario: null, reason: 'parse_error', retryable: false };
+    }
+  }
+
+  async function fetchWithReason(scenarioId) {
+    if (!/^[\w-]+$/.test(scenarioId)) {
+      return { scenario: null, reason: 'invalid_id' };
+    }
+
+    let last;
+    for (let i = 0; i < attempts; i++) {
+      last = await attemptOnce(scenarioId);
+      if (last.scenario || !last.retryable || i === attempts - 1) break;
+      await sleep(Math.min(RETRY_BASE_MS * (1 << i), RETRY_MAX_MS));
     }
+    // Strip the internal `retryable` flag from the public contract.
+    const { retryable: _drop, ...result } = last;
+    return result;
   }
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dogfood-lab/ingest",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "type": "module",
   "description": "Ingestion pipeline for testing-os. Thin glue: dispatch → verifier → persist → indexes.",
   "main": "run.js",

package/run.js

@@ -544,6 +544,13 @@ if (isMain) {
   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.
@@ -574,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) {
@@ -610,6 +623,14 @@ if (isMain) {
       // 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;
@@ -648,14 +669,22 @@ if (isMain) {
   // 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);
+    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 } : {})
+      ...(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) {

package/verify-chain.js

@@ -39,10 +39,11 @@
  */
 
 import { existsSync, readFileSync } from 'node:fs';
-import { join } from 'node:path';
+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
@@ -51,111 +52,221 @@ import { readChainManifest } from './lib/chain-manifest.js';
  * @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.
+ * @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) {
+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.
+    // 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: { seq: -1, run_id: null, reason: err.message },
+      break: brk,
+      ...(collectAllBreaks ? { breaks: [brk] } : {}),
+      ...(collectOrphans ? { orphans: [] } : {}),
     };
   }
 
-  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 };
-  }
+  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 });
 
-    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,…
+    // (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) {
-      return fail(`seq is not monotonic: expected ${i}, found ${seq}`);
+      record(`seq is not monotonic: expected ${i}, found ${seq}`);
+      break;
     }
-
-    // (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}`
-      );
+      record(`broken prev_digest link: expected ${prevDigest}, found ${entry.prev_digest}`);
+      break;
     }
 
-    // (1) Load the record and recompute its digest.
+    // (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)) {
-      return fail(`record file missing at ${entry.path} (could not read to recompute digest)`);
+      record(`record file missing at ${entry.path} (could not read to recompute digest)`);
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
     }
 
-    let record;
+    let parsed;
     try {
-      record = JSON.parse(readFileSync(recordPath, 'utf-8'));
+      parsed = JSON.parse(readFileSync(recordPath, 'utf-8'));
     } catch (err) {
-      return fail(`record file at ${entry.path} is not valid JSON: ${err.message}`);
+      record(`record file at ${entry.path} is not valid JSON: ${err.message}`);
+      if (!collectAllBreaks) break;
+      prevDigest = entry.submission_digest;
+      continue;
     }
 
-    const recomputed = submissionDigest(record);
-
-    // The recomputed digest must equal the ledger's claim.
+    const recomputed = submissionDigest(parsed);
     if (recomputed !== entry.submission_digest) {
-      return fail(
+      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;
     }
 
-    // …AND the record's own self-certified digest.
-    const selfDigest = record.integrity?.submission_digest;
+    const selfDigest = parsed.integrity?.submission_digest;
     if (selfDigest !== recomputed) {
-      return fail(
+      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: true,
+    ok,
     count: entries.length,
-    head_digest: entries[entries.length - 1].submission_digest,
-    break: null,
+    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).
@@ -165,14 +276,41 @@ export function verifyChain(repoRoot) {
  */
 export function formatChainResult(result) {
   if (result.ok) {
-    return [
+    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}`);
   }
-  const b = result.break;
-  return [
-    `integrity chain BROKEN at seq ${b.seq}${b.run_id ? ` (run_id: ${b.run_id})` : ''}`,
-    `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;
 }