create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/landing/merge-delta.js

@@ -0,0 +1,380 @@
+'use strict';
+// WP-3a (docs/landing-queue-gate-once-merge-delta-2026-10-29.html §5 D-3/D-3c, §6.5, §8 WP-3a,
+// §9 S-9, §10 T-4/T-6): merge-delta selection, in SHADOW mode.
+//
+// For a merge train T = commit-tree(tree, [B, P]) the CAV'14 two-sided rule (§3 P-1, Theorem 1) says
+// a test that neither side of the merge changes keeps the result it already had on that side, so the
+// safe Node test set is S = sel(B→T) ∩ sel(P→T). This module COMPUTES S and records it on the job's
+// `gate.intersection` telemetry — nothing else. The gate keeps running today's selection
+// (`--plan-base B`); WP-3b is the work package that would ENFORCE S, and it is gated on OQ-2, which
+// this shadow record is the instrument for (§5 Open questions OQ-2).
+//
+// Every precondition of §5 D-3 is a FALLBACK here, never a failure: a missing proof for tree(B), a
+// broken proof chain, a broad plan on either side, a planner that cannot run, or LAND_MERGE_DELTA=0
+// all return `{ mode: 'fallback', reason, detail }`, and the train gates exactly as it did before
+// this module existed. Nothing here can change a gate argv, a verdict or a landing outcome.
+//
+// `planner` is injectable and defaults to the real spawn (`node <trainDir>/bin/test-plan.js`), so
+// the unit tests never start a child process (tests/ is a no-spawn tier: bin/tier-placement-lint.js
+// rejects a spawning test in tests/). The default resolves the planner FROM THE TRAIN WORKTREE,
+// which is what bin/test-gate.sh already does ($SCRIPT_ROOT/bin/test-plan.js, test-gate.sh:1282):
+// the planner belongs to the repository whose tests are being planned, and the train worktree is a
+// checked-out copy of exactly that repository.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { spawn } = require('child_process');
+
+const proof = require('./proof');
+const queue = require('./queue');
+const state = require('./state');
+const { childEnv, revParse } = require('./git');
+
+// The planner is a `test-plan.js` on a repo that is already loaded (it parses the whole impact graph
+// in the worst case); 5 minutes is a safety net against a wedged child, not a budget.
+const PLANNER_TIMEOUT_MS = 5 * 60 * 1000;
+
+// bin/test-plan.js's disposition for "this file must run in this gate" (its `dispositions[]` rows).
+// A broad plan marks every file `scheduled-broad-lane` instead, which is exactly why the caller
+// refuses to intersect two plans that are not both narrow (§5 D-3(c)).
+const RUN_DISPOSITION = 'run';
+
+// The runners' own failure summary, verbatim (bin/test-runner-adapter.js:921-941):
+//
+//   [test-suite] FAILED (2 file(s)):
+//     - tests/foo.test.js: <reasons joined by '; '>
+//     - tests/bar.test.js: killed after 300000ms (possible synchronous spin)
+//
+// `test-suite` is the CTM/`coding-task-manager` label and `run-hermetic` the root/wall-e one
+// (test-runner-adapter.js:850), so the label is matched generically. The `  - <file>: …` rows are
+// the run's failing test files, relative to the repository the runner ran in.
+const FAILED_BLOCK_RE = /^\s*\[[^\]]+\] FAILED \(\d+ file\(s\)\):\s*$/;
+const FAILED_ROW_RE = /^\s{2}-\s+(\S+?):\s*(.*)$/;
+
+// The three reads §5 D-3(a)/(b) need, in one object so the unit tests never spawn git (tests/ is a
+// no-spawn tier). Production is `realProofs`:
+//   treeOf       — `git rev-parse <base>^{tree}`; THROWS on an unresolvable revision, which the
+//                  caller records as `plan_error` rather than guessing at a tree.
+//   treeHasProof — §5 D-3(a): has tree(B) ever passed a gate under this gates hash?
+//   proofChain   — §5 D-3c: is every commit of mb..P proved?
+const realProofs = {
+  treeOf: (cwd, rev) => revParse(cwd, `${rev}^{tree}`),
+  treeHasProof: (root, query) => proof.treeHasProof(root, query),
+  proofChain: (cwd, root, query) => proof.proofChain(cwd, root, query),
+};
+
+// --- the planner (§6.5) -------------------------------------------------------------------------
+
+function plannerArgs(trainDir, base) {
+  return [
+    path.join(trainDir, 'bin', 'test-plan.js'),
+    '--root', trainDir,
+    '--mode', 'snapshot',
+    '--base', base,
+    '--json',
+  ];
+}
+
+function firstLine(text) {
+  return String(text === undefined || text === null ? '' : text)
+    .split('\n').map((line) => line.trim()).filter(Boolean)[0] || null;
+}
+
+// The default planner: one `node <trainDir>/bin/test-plan.js --mode snapshot --base <base> --json`
+// child, resolved from the train worktree. It NEVER throws and never rejects — a failure is
+// `{ ok: false, detail }`, which the caller turns into the `plan_error` fallback — and it reports its
+// own wall time in milliseconds so two runs can be summed (`plannerMs`, AC-3c) without a second clock
+// outside this module.
+//
+// Returns `{ ok: true, plan: <parsed JSON>, ms }` | `{ ok: false, detail: <first stderr line>, ms }`.
+function runPlanner({ trainDir, base }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const done = (result) => resolve({ ...result, ms: Date.now() - started });
+    let child;
+    try {
+      child = spawn(process.execPath, plannerArgs(trainDir, base), {
+        cwd: trainDir,
+        env: childEnv(),
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (error) {
+      done({ ok: false, detail: error && error.message ? error.message : String(error) });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      done(result);
+    };
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch (error) {
+        /* expected: the planner exited between the deadline firing and this kill */
+      }
+      finish({ ok: false, detail: `test-plan.js did not finish within ${PLANNER_TIMEOUT_MS}ms` });
+    }, PLANNER_TIMEOUT_MS);
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => { stdout += chunk; });
+    child.stderr.on('data', (chunk) => { stderr += chunk; });
+    child.on('error', (error) => finish({ ok: false, detail: error && error.message ? error.message : String(error) }));
+    child.on('close', (status) => {
+      if (status !== 0) {
+        finish({ ok: false, detail: firstLine(stderr) || `test-plan.js exited ${status}` });
+        return;
+      }
+      try {
+        finish({ ok: true, plan: JSON.parse(stdout) });
+      } catch (error) {
+        finish({ ok: false, detail: `unparseable plan JSON: ${error && error.message ? error.message : String(error)}` });
+      }
+    });
+  });
+}
+
+// sel(X→T) for one plan: the repo-relative files a narrow plan says must run. A plan that is not an
+// object, or that carries no `dispositions[]`, yields the empty set — the caller has already refused
+// a broad plan, so "no run rows" is a real (empty) selection, never a reason to fall back.
+function runFiles(plan) {
+  const rows = plan && Array.isArray(plan.dispositions) ? plan.dispositions : [];
+  const files = new Set();
+  for (const row of rows) {
+    if (row && row.disposition === RUN_DISPOSITION && typeof row.file === 'string' && row.file) files.add(row.file);
+  }
+  return files;
+}
+
+// --- the selection (§5 D-3, §6.5) ----------------------------------------------------------------
+
+// §5 D-3: S = sel(B→T) ∩ sel(P→T), computed in the train worktree T and recorded — never enforced.
+//
+// Returns `{ mode: 'merge-delta', files, sizes: { fromBase, fromTip, intersection }, plannerMs }`
+// on success, or `{ mode: 'fallback', reason, detail }` for every §5 D-3 precondition miss:
+//
+//   disabled      — LAND_MERGE_DELTA === '0' (the D-3 kill switch; §6 "No env flag except the D-3
+//                   kill-switch"). Checked first: the switch is a cheap short-circuit, and it must
+//                   hold even when the proofs below are missing.
+//   no_base_proof — (a) no PASS proof exists for tree(B) under this gates hash, so the base side of
+//                   the merge was never tested and Theorem 1's induction has no first step.
+//   chain_broken  — (b) some commit on `rev-list --first-parent mb..P` has no proof for
+//                   (tree(c), planBaseTree(c)) (§5 D-3c).
+//   broad_plan    — (c) either plan is a fallback to the broad lane, whose "run" set is the whole
+//                   inventory and whose intersection would be a full run wearing a narrow plan's name.
+//   plan_error    — (c) the planner could not run or did not print JSON (detail = its first stderr
+//                   line), or a git read behind (a)/(b) failed.
+//
+// `base`/`tip` are revisions (commit oids in the runner's call), `trainDir` is the train worktree,
+// `root` the landing state directory. `planner` and `proofs` are injected by the unit tests;
+// production uses `runPlanner` and `realProofs`.
+async function mergeDeltaSelection({
+  trainDir, root, base, tip, gatesHash, env = process.env, planner = runPlanner, proofs = realProofs,
+} = {}) {
+  if (env && env.LAND_MERGE_DELTA === '0') return { mode: 'fallback', reason: 'disabled', detail: null };
+
+  const baseTree = proofs.treeOf(trainDir, base);
+  if (!proofs.treeHasProof(root, { tree: baseTree, gatesHash })) {
+    return { mode: 'fallback', reason: 'no_base_proof', detail: `no PASS proof for tree ${baseTree} (base ${base})` };
+  }
+
+  const chain = proofs.proofChain(trainDir, root, { base, tip, gatesHash });
+  if (!chain.ok) {
+    return {
+      mode: 'fallback',
+      reason: 'chain_broken',
+      detail: `${chain.missing.length} commit(s) of ${chain.checked} unproven: ${chain.missing.join(', ')}`,
+    };
+  }
+
+  const plans = [];
+  let plannerMs = 0;
+  for (const side of [base, tip]) {
+    // The two passes are sequential on the ONE host this queue owns (§11 "Host contention remains"):
+    // they are cheap next to a gate, but there is no reason to add load to a machine whose median
+    // load is already 19.9 on 16 cores.
+    // eslint-disable-next-line no-await-in-loop
+    const result = await planner({ trainDir, root, base: side, env });
+    plannerMs += result && Number.isFinite(result.ms) ? result.ms : 0;
+    if (!result || !result.ok) {
+      return { mode: 'fallback', reason: 'plan_error', detail: (result && result.detail) || 'planner returned no result' };
+    }
+    plans.push(result.plan);
+  }
+  const broadSide = plans.findIndex((plan) => plan && plan.fallback === true);
+  if (broadSide !== -1) {
+    return {
+      mode: 'fallback',
+      reason: 'broad_plan',
+      detail: `plan(${broadSide === 0 ? 'B' : 'P'}) fell back to the broad lane`,
+      plannerMs,
+    };
+  }
+
+  const fromBase = runFiles(plans[0]);
+  const fromTip = runFiles(plans[1]);
+  const files = [...fromBase].filter((file) => fromTip.has(file)).sort();
+  return {
+    mode: 'merge-delta',
+    files,
+    sizes: { fromBase: fromBase.size, fromTip: fromTip.size, intersection: files.length },
+    plannerMs,
+  };
+}
+
+// --- the shadow record (§6.6, §8 WP-3a) ----------------------------------------------------------
+
+// The gate telemetry shape `gateSelectionTelemetry` builds (bin/land.js), with every field
+// "unknown". A shadow record only exists AFTER a gate ran, so a gate that wrote no `--selection-out`
+// (a repository whose `gates[].run` is a plain script, or this repository's own queue fixtures) still
+// gets a telemetry object — one that says "the gate ran and said nothing", which is the truth.
+const UNKNOWN_TELEMETRY = Object.freeze({
+  mode: null, planBase: null, selected: null, executed: null, cached: null,
+  missReasons: null, fallbackReason: null,
+});
+
+// `gate.intersection` is written on the 3.9 kB job record, so it carries the SHAPE of the measurement
+// and not the measurement: |S| can be hundreds of files, and every job file and every metrics row
+// would pay for the list forever. The full S goes to `<root>/logs/<jobId>.merge-delta.json` and the
+// job keeps `sHash = sha256(S.join('\n'))` — enough to compare two jobs' selections, or to re-read the
+// list from the log directory.
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+function readLogText(file) {
+  if (!file) return null;
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    /* expected: the log is written by the runner; if it is gone there is simply no evidence to parse */
+    return null;
+  }
+}
+
+// The Node test files a runner reported as FAIL, or null when the log carries no runner failure block
+// at all. NULL IS NOT "NONE": an empty array means "a block was found and every failing file is in
+// S", which is the OQ-2 answer this WP exists to collect; null means "the log cannot say" (the gate
+// failed in a lint phase, or the file was pruned).
+function failingFiles(logText) {
+  // One parser for the runner's failure block: train.failedFilesFromLog (landing-throughput WP-2)
+  // reads the same `[<label>] FAILED (N file(s)):` block and `  - <file>: …` rows; `raw` is the
+  // files exactly as printed (S is compared in the log's own terms), `sawBlock` the null/[] split.
+  const parsed = require('./train').failedFilesFromLog(logText);
+  return parsed.sawBlock ? [...parsed.raw].sort() : null;
+}
+
+// §8 WP-3a: after a FAIL, the failing Node test files that are NOT in S. `[]` is a real, encouraging
+// answer (every file the gate failed is one S said to run); null means the log could not be read.
+function outsideFailing(failing, files) {
+  if (!failing) return null;
+  const selected = new Set(files || []);
+  return failing.filter((file) => !selected.has(file)).sort();
+}
+
+// Attach the shadow record to this run's `gate` telemetry (§6.6). Returns the telemetry object the
+// job record and the terminal metrics row carry. `shadow` is the value `runGate`'s `onTrainReady`
+// returned; `telemetry` is `gateSelectionTelemetry(result.selection)` (possibly null).
+function recordIntersection(telemetry, shadow, { root, jobId, trainId = null, verdict, logFile } = {}) {
+  const files = shadow && shadow.mode === 'merge-delta' && Array.isArray(shadow.files) ? shadow.files : null;
+  if (files) {
+    queue.ensureLogsDir(root);
+    // WP-1 §9 S-4: keyed by the TRAIN id (the batch id for a batch, the job id for a singleton), so a
+    // batch has one shadow record the whole train shares.
+    state.writeJsonAtomic(path.join(root, 'logs', `${trainId || jobId}.merge-delta.json`), {
+      contract: state.CONTRACT,
+      jobId,
+      trainId,
+      mode: shadow.mode,
+      sizes: shadow.sizes || null,
+      plannerMs: Number.isFinite(shadow.plannerMs) ? shadow.plannerMs : null,
+      files,
+    });
+  }
+  const intersection = {
+    shadow: true,
+    mode: shadow && shadow.mode ? shadow.mode : null,
+    reason: shadow && shadow.reason ? shadow.reason : null,
+    sizes: shadow && shadow.sizes ? shadow.sizes : null,
+    plannerMs: shadow && Number.isFinite(shadow.plannerMs) ? shadow.plannerMs : null,
+    sHash: files ? sha256(files.join('\n')) : null,
+    // Only a FAIL can have a failing file: a PASS ran S inside a green gate, and a stopped gate ran no
+    // verdict at all.
+    outsideFailing: verdict === 'FAIL' ? outsideFailing(failingFiles(readLogText(logFile)), files) : null,
+  };
+  return { ...(telemetry || UNKNOWN_TELEMETRY), intersection };
+}
+
+// --- the report (§8 AC-3b, §5 OQ-2) --------------------------------------------------------------
+
+// Every job whose `gate.intersection` this module wrote — i.e. every merge train gated since WP-3a.
+function shadowRows(root) {
+  return queue.listJobs(root)
+    .map((job) => job && job.gate && job.gate.intersection)
+    .filter((row) => row && typeof row === 'object');
+}
+
+// AC-3b/the OQ-2 data: n trains, n per mode (and per fallback reason), the median |S| as a percentage
+// of |sel(B→T)|, the median planner time, and the count of FAILED trains with a failing file OUTSIDE
+// S. The last number is the one that decides WP-3b: §5 OQ-2 enforces only when no failing test outside
+// S was found across the sample AND the median |S|/|sel(B→T)| is ≤ 0.5.
+function mergeDeltaReport(root) {
+  const rows = shadowRows(root);
+  const modes = {};
+  const ratios = [];
+  const plannerMs = [];
+  let outsideFailingTrains = 0;
+  for (const row of rows) {
+    const key = row.mode === 'merge-delta' ? 'merge-delta' : `fallback:${row.reason || 'unknown'}`;
+    modes[key] = (modes[key] || 0) + 1;
+    if (row.sizes && Number.isFinite(row.sizes.fromBase) && row.sizes.fromBase > 0 && Number.isFinite(row.sizes.intersection)) {
+      ratios.push((row.sizes.intersection / row.sizes.fromBase) * 100);
+    }
+    if (Number.isFinite(row.plannerMs)) plannerMs.push(row.plannerMs);
+    if (Array.isArray(row.outsideFailing) && row.outsideFailing.length > 0) outsideFailingTrains += 1;
+  }
+  const percent = queue.median(ratios);
+  return {
+    shadow: true,
+    trains: rows.length,
+    modes,
+    // §5 OQ-2's decision inputs, spelled the same way the decision rule reads them.
+    medianPercentOfBase: percent === null ? null : Number(percent.toFixed(1)),
+    medianPlannerMs: queue.median(plannerMs),
+    outsideFailingTrains,
+  };
+}
+
+function reportLines(report) {
+  const modes = Object.entries(report.modes).sort(([a], [b]) => a.localeCompare(b));
+  const percent = report.medianPercentOfBase === null ? '?' : `${report.medianPercentOfBase}%`;
+  const planner = report.medianPlannerMs === null ? '?' : `${report.medianPlannerMs}ms`;
+  return [
+    `merge-delta shadow: ${report.trains} train(s)`,
+    ...(modes.length ? modes.map(([mode, count]) => `  ${mode}: ${count}`) : ['  (no merge train has been gated with shadow telemetry yet)']),
+    `median |S| / |sel(B→T)|: ${percent}`,
+    `median plannerMs: ${planner}`,
+    `failed trains with a failing file outside S: ${report.outsideFailingTrains}`,
+  ];
+}
+
+module.exports = {
+  FAILED_BLOCK_RE,
+  FAILED_ROW_RE,
+  realProofs,
+  plannerArgs,
+  runPlanner,
+  runFiles,
+  mergeDeltaSelection,
+  recordIntersection,
+  failingFiles,
+  outsideFailing,
+  shadowRows,
+  mergeDeltaReport,
+  reportLines,
+};

package/template/coding-task-manager/lib/landing/proof.js

@@ -0,0 +1,223 @@
+'use strict';
+// WP-2 (docs/landing-queue-gate-once-merge-delta-2026-10-29.html §5 D-1/D-3c/D-4, §6.3, §6.4,
+// §8 WP-2, §9 S-5..S-8): the proof store.
+//
+// D-1: a gate PASS is a PROOF, and it is keyed by the PAIR (tree, planBaseTree) plus the gates
+// hash — not by the tree alone. The commit's own gate proves the delta against its parent (`bin/
+// pre-commit-hook.sh` passes that parent as `--plan-base`), so a proof the author's commit gate
+// produced is exactly as good as one the landing runner produced, and the queue can land the tip
+// without re-running the identical gate (S-5: today the hook's PASS is checked and thrown away).
+//
+// The legacy tree-keyed store `verdicts/<tree>.json` (lib/landing/gate.js) stays readable and is
+// still written by the runner; this file is the second, narrower key and never writes that one.
+//
+// Only PASS is ever written (§5 D-1: "INCONCLUSIVE, FAIL and a PASS that contains a FLAKY line are
+// never recorded as proofs"), and a proof is refused outright when the diff against its plan base
+// touches a dependency manifest: the train gate symlinks the MAIN checkout's node_modules in
+// (gate.js `linkCachePaths`), so a tree whose dependencies differ from the author's was tested
+// against something the author never installed.
+//
+// Keyed entries live at `verdicts/<tree>.<planBaseTree>.json` under the landing state root — the
+// same `<common-dir>/landing` directory `lib/landing/state.js` owns. Nothing here throws for a
+// state file that is merely absent or torn: a missing proof is a cache miss, never a failure.
+
+const fs = require('fs');
+const path = require('path');
+
+const state = require('./state');
+const { landingError, runGitRaw, isAncestor } = require('./git');
+
+// Git object names, both 40-hex (sha1) and 64-hex (sha256) repositories. The name is used as a
+// path component, so it is validated rather than interpolated blindly.
+const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+// The one terminal line `bin/test-gate.sh` prints on a green run (bin/lib-test-gate-summary.sh
+// `print_gate_verdict`); the pre-commit hook greps it with `grep -Fqx`, so it is matched as a whole
+// line here too.
+const PASS_LINE = '[test-gate] VERDICT: PASS';
+
+// The FLAKY evidence lines the runners actually print, verbatim, case-sensitively:
+//   bin/test-runner-adapter.js:869        `[test-suite] FLAKY (passed on isolated rerun): …`
+//                                         `[run-hermetic] FLAKY (passed on isolated rerun): …`
+//   bin/test-browser-selection-rerun.js:260 `[browser-selection] FLAKY (rerun passed alone): …`
+//   bin/test-browser-selection.js:793     `[browser-selection] VERDICT: PASS (with N FLAKY file(s), …)`
+// A bare `FLAKY` substring would also fire on a TAP line that merely NAMES a flaky-related file
+// (`flaky-report`, `flaky-ledger`), and a rerun-pass is a real flake — the proof must not claim it.
+const FLAKY_RE = /FLAKY \(passed on isolated rerun\)|FLAKY \(rerun passed alone\)|\d+ FLAKY file\(s\)/;
+
+// §5 D-1: "Dependency installs differ between the author's worktree and the train's symlinked
+// node_modules". Manifest and lock files, at the repository root or in a package subdirectory.
+const DEPENDENCY_RE = /(^|\/)(?:package(?:-lock)?|npm-shrinkwrap)\.json$/;
+
+function isOid(value) {
+  return typeof value === 'string' && OID_RE.test(value);
+}
+
+// §6.3: the proof file for the exact pair. Both names must be object ids — they are path
+// components, so a caller that hands over a revision like `main` or `../../etc/passwd` is a bug,
+// never a path traversal.
+function proofFile(root, tree, planBaseTree) {
+  if (!isOid(tree) || !isOid(planBaseTree)) {
+    throw landingError('proof_invalid', `a proof is keyed by two object ids, got tree=${JSON.stringify(tree)} planBaseTree=${JSON.stringify(planBaseTree)}`, { tree, planBaseTree, root });
+  }
+  return path.join(root, 'verdicts', `${tree}.${planBaseTree}.json`);
+}
+
+// The recorded proof for exactly this (tree, planBaseTree, gatesHash), or null. Null covers every
+// "not a proof" case on purpose: absent file, unreadable/torn JSON, a different tree or base, a
+// different gates hash (§6.2: changing `gates` invalidates every proof), and a non-PASS record.
+function readProof(root, { tree, planBaseTree, gatesHash } = {}) {
+  if (!isOid(tree) || !isOid(planBaseTree) || typeof gatesHash !== 'string' || !gatesHash) return null;
+  const raw = state.readJsonSafe(proofFile(root, tree, planBaseTree));
+  if (!raw || raw.tree !== tree || raw.planBaseTree !== planBaseTree) return null;
+  if (raw.gatesHash !== gatesHash) return null;
+  if (raw.verdict !== 'PASS') return null;
+  return raw;
+}
+
+// §6.3 entry: { contract, tree, planBaseTree, gatesHash, verdict: 'PASS', source: 'commit'|'train',
+// commit, seconds, at, logPath, selection }. Written tmp+rename (state.writeJsonAtomic), so a
+// reader never sees a half-written proof. Only PASS is a proof; anything else throws.
+function recordProof(root, entry) {
+  const record = entry || {};
+  if (record.verdict !== 'PASS') {
+    throw landingError('proof_not_pass', `refusing to record a ${JSON.stringify(record.verdict === undefined ? null : record.verdict)} proof (only PASS is a proof)`, {
+      tree: record.tree === undefined ? null : record.tree,
+      planBaseTree: record.planBaseTree === undefined ? null : record.planBaseTree,
+    });
+  }
+  const file = proofFile(root, record.tree, record.planBaseTree);
+  state.writeJsonAtomic(file, { contract: state.CONTRACT, ...record });
+  return file;
+}
+
+// Every proof file name in the store, sorted (readdir order is filesystem-dependent, so a reader
+// that picks the first match must sort first to be deterministic). A store that does not exist yet is
+// an empty store: `verdicts/` is created lazily by the first write.
+function proofNames(root) {
+  try {
+    return fs.readdirSync(path.join(root, 'verdicts')).sort();
+  } catch (error) {
+    /* expected: nothing has ever been proved in this repository — an empty store, not an error */
+    return [];
+  }
+}
+
+// §5 D-3(a), §6.3: is there ANY proof for this tree, against any plan base? The base side of a merge
+// (tree(B)) is not proved against `P` — it is proved against whatever its own commit gate used — so
+// the D-3(a) question is "has this tree ever passed a gate under these gates", not "is this exact
+// pair recorded". Both layouts count: the legacy tree-keyed `verdicts/<tree>.json` (§6.3 "stays
+// readable, never written") and the pair-keyed `verdicts/<tree>.<planBaseTree>.json`. The gates hash
+// must still match (§6.2: changing `gates` invalidates every proof) and only PASS is a proof (D-1).
+function treeHasProof(root, { tree, gatesHash } = {}) {
+  if (!isOid(tree) || typeof gatesHash !== 'string' || !gatesHash) return null;
+  for (const name of proofNames(root)) {
+    if (name !== `${tree}.json` && !name.startsWith(`${tree}.`)) continue;
+    const raw = state.readJsonSafe(path.join(root, 'verdicts', name));
+    if (!raw || raw.tree !== tree) continue;
+    if (raw.gatesHash !== gatesHash) continue;
+    if (raw.verdict !== 'PASS') continue;
+    return raw;
+  }
+  return null;
+}
+
+// --- the chain (§5 D-3c, §5 D-4) -----------------------------------------------------------------
+
+// `git rev-list --first-parent <base>..<tip>` — the commits a fast-forward of `base` to `tip`
+// would add, oldest-history-last (order is irrelevant here: each commit is decided on its own).
+function firstParentRange(cwd, base, tip) {
+  const args = ['rev-list', '--first-parent', `${base}..${tip}`];
+  const res = runGitRaw(cwd, args);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git ${args.join(' ')} exited ${res.status}: ${String(res.stderr || '').trim()}`, { cwd, args, status: res.status });
+  }
+  return res.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function treeOf(cwd, commit) {
+  const res = runGitRaw(cwd, ['rev-parse', '--verify', '--quiet', `${commit}^{tree}`]);
+  if (res.status !== 0) return null;
+  const value = res.stdout.trim();
+  return isOid(value) ? value : null;
+}
+
+// The parent oids of ONE commit, first parent first (`git rev-list --parents -n 1 <c>` prints
+// `<c> <p1> <p2> …`).
+function parentsOf(cwd, commit) {
+  const args = ['rev-list', '--parents', '-n', '1', commit];
+  const res = runGitRaw(cwd, args);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git ${args.join(' ')} exited ${res.status}: ${String(res.stderr || '').trim()}`, { cwd, args, status: res.status });
+  }
+  const tokens = res.stdout.split('\n')[0].trim().split(/\s+/).filter(Boolean);
+  return tokens.slice(1);
+}
+
+// One commit's link in the chain: it holds iff some parent `p` has a proof for (tree(c), tree(p)).
+// `p` qualifies when it is c's FIRST parent — which, walking first-parents, is either the next
+// commit on the chain or (for the oldest one) an ancestor of `base` — or when it is an ancestor of
+// `base` itself. That second case is what makes an author's merge-of-main commit provable: its
+// second parent IS the target, so the proof the hook recorded for it is accepted (D-2).
+function commitProven(cwd, root, commit, base, gatesHash) {
+  const tree = treeOf(cwd, commit);
+  if (!tree) return false;
+  const parents = parentsOf(cwd, commit);
+  for (let index = 0; index < parents.length; index += 1) {
+    const parent = parents[index];
+    if (index > 0 && !isAncestor(cwd, parent, base)) continue;
+    if (readProof(root, { tree, planBaseTree: treeOf(cwd, parent), gatesHash })) return true;
+  }
+  return false;
+}
+
+// §5 D-4, generalized to the per-commit induction §5 D-3c describes. `base` is the target commit
+// the fast-forward starts from, `tip` the commit being landed. The chain holds iff EVERY commit
+// `base..tip` (first-parent order) has a proof against a qualifying parent; `missing` lists the
+// commits that do not. An empty range is trivially proven — nothing is being added.
+//
+// `checked` is the number of commits walked (0 for an empty range): the D-4 one-commit case and the
+// runner's own progress line both need it, and recomputing the range outside would be a second git
+// call for a number this walk already knows.
+function proofChain(cwd, root, { base, tip, gatesHash } = {}) {
+  if (!base || !tip) return { ok: false, missing: [], checked: 0 };
+  const commits = firstParentRange(cwd, base, tip);
+  const missing = commits.filter((commit) => !commitProven(cwd, root, commit, base, gatesHash));
+  return { ok: missing.length === 0, missing, checked: commits.length };
+}
+
+// --- the refusal (§5 D-1, §6.4) ------------------------------------------------------------------
+
+// Why a gate log is NOT a proof, in the order that decides it. `null` means "recordable".
+//   'no_pass'           — no line exactly `[test-gate] VERDICT: PASS`
+//   'flaky'             — the log carries a runner's FLAKY evidence line (FLAKY_RE)
+//   'dependency_change' — `git diff --name-only <planBase> <tree>` touches a dependency manifest
+// The dependency check is skipped when either side is unreadable: a caller that cannot name both
+// sides has nothing to diff, and the ledger check must never be the thing that fabricates a refusal.
+function proofRefusal(cwd, { planBase, tree, logText } = {}) {
+  const text = String(logText === undefined || logText === null ? '' : logText);
+  const green = text.split('\n').map((line) => line.replace(/\r$/, '')).some((line) => line === PASS_LINE);
+  if (!green) return 'no_pass';
+  if (FLAKY_RE.test(text)) return 'flaky';
+  if (!planBase || !tree) return null;
+  const args = ['diff', '--name-only', planBase, tree];
+  const res = runGitRaw(cwd, args);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git ${args.join(' ')} exited ${res.status}: ${String(res.stderr || '').trim()}`, { cwd, args, status: res.status });
+  }
+  const touched = res.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (touched.some((file) => DEPENDENCY_RE.test(file))) return 'dependency_change';
+  return null;
+}
+
+module.exports = {
+  PASS_LINE,
+  FLAKY_RE,
+  DEPENDENCY_RE,
+  proofFile,
+  readProof,
+  recordProof,
+  treeHasProof,
+  proofChain,
+  proofRefusal,
+};