feature-factory 0.7.0

package/observe/index.js

@@ -0,0 +1,366 @@
+// Observe, don't trust. A subagent's report is a claim, so independently re-derive
+// the diff and re-run its named tests before work-reviewer judges observed evidence.
+// `factory observe` mechanizes that rule because an autonomous run has no human to
+// check whether the orchestrator actually observed anything.
+import { spawnSync } from "node:child_process";
+import { existsSync, lstatSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { CONTROL_PLANE } from "../state/schema.js";
+
+export const DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS = 900000;
+export const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 900000;
+
+export const EVIDENCE_KEYS = Object.freeze([
+  "subject", "run_id", "attempt", "branch", "base_ref", "worktree", "status", "blocked_reason",
+  "worktree_clean",
+  "files_changed", "diff_stat", "diff_observed", "commands", "tests", "commit",
+  "observed_by", "review_ready", "claim_reconciliation",
+]);
+
+export function git(cwd, args, { runner = spawnSync } = {}) {
+  const result = runner("git", args, { cwd, encoding: "utf8", shell: false, env: { ...process.env, LC_ALL: "C" } });
+  const status = Number.isInteger(result?.status) ? result.status : null;
+  return {
+    ok: status === 0,
+    status,
+    stdout: String(result?.stdout ?? ""),
+    stderr: String(result?.stderr ?? ""),
+    argv: ["git", ...args],
+  };
+}
+
+// Every fact below is re-derived from the repository. A caller-supplied value is
+// never substituted for an observation; if git cannot answer, the field is null
+// and `diff_observed` is false, which blocks review_ready.
+// `options.ref` names what to observe, defaulting to HEAD. A caller that knows the
+// subject's branch should pass it: binding to whatever happens to be checked out
+// makes the observation depend on the orchestrator's current directory state, and a
+// merge legitimately checks out the integration branch in the same worktree.
+export function observeWorktree(worktree, baseRef, options = {}) {
+  const ref = options.ref ?? "HEAD";
+  const commands = [];
+  const record = (result) => {
+    commands.push({ cmd: result.argv.join(" "), exit: result.status, summary: summarize(result) });
+    return result;
+  };
+
+  const head = record(git(worktree, ["rev-parse", ref], options));
+  const names = record(git(worktree, ["--literal-pathspecs", "diff", "--name-only", "-z", `${baseRef}...${ref}`], options));
+  const stat = record(git(worktree, ["diff", "--stat", `${baseRef}...${ref}`], options));
+
+  const observed = head.ok && names.ok && stat.ok;
+  return {
+    commit: head.ok ? head.stdout.trim() : null,
+    // NUL-separated and untrimmed: ownership is decided on these paths, so a name with a
+    // trailing space must stay a distinct path rather than collapsing onto another.
+    files_changed: names.ok ? names.stdout.split("\0").filter((path) => path !== "") : [],
+    diff_stat: stat.ok ? stat.stdout.trim() : null,
+    diff_observed: observed,
+    commands,
+  };
+}
+
+// Attack 7: a caller may present any head it likes. Ancestry is asked of git, and
+// git's exit codes are read precisely: 0 is "is an ancestor", 1 is "proven not",
+// anything else is a failed probe that must not be read as either.
+// Finding 3: observeWorktree derives the commit and diff from a git ref, but runTests
+// executes in the mutable working directory. So tests could pass on uncommitted bytes
+// while the evidence claimed the HEAD commit - and the same tests then failed on the
+// clean merged tree. This is not an adversarial case: a builder leaving uncommitted
+// changes is the ordinary state of an agent-driven worktree.
+//
+// Observation of a dirty tree is meaningless, so it is refused rather than recorded.
+export function observeCleanliness(worktree, options = {}) {
+  const probe = git(worktree, ["status", "--porcelain", "--untracked-files=normal"], options);
+  if (!probe.ok) return { clean: false, reason: "worktree state could not be observed", entries: [] };
+  const entries = probe.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+  return { clean: entries.length === 0, reason: entries.length === 0 ? null : "worktree has uncommitted changes", entries };
+}
+
+export function runBootstrap(worktree, command, timeoutMs = DEFAULT_BOOTSTRAP_TIMEOUT_MS, { runner = spawnSync } = {}) {
+  try {
+    const result = runner(command, [], {
+      cwd: worktree, shell: true, env: process.env, timeout: timeoutMs, stdio: ["inherit", process.stderr, process.stderr],
+    });
+    return Number.isSafeInteger(result?.status) && result.status >= 0 ? result.status : null;
+  } catch { return null; }
+}
+
+export function observeTrackedCleanliness(worktree, options = {}) {
+  try {
+    const top = git(worktree, ["rev-parse", "--show-toplevel"], options);
+    const probes = [
+      git(worktree, ["--literal-pathspecs", "diff", "--name-only", "-z"], options),
+      git(worktree, ["--literal-pathspecs", "diff", "--cached", "--name-only", "-z"], options),
+    ];
+    if (!top.ok || realpathSync(resolve(worktree, top.stdout.trim())) !== realpathSync(worktree)
+      || probes.some((probe) => !probe.ok)) return { observed: false, entries: [] };
+    return { observed: true, entries: [...new Set(probes.flatMap((probe) => probe.stdout.split("\0").filter(Boolean)))].sort() };
+  } catch { return { observed: false, entries: [] }; }
+}
+
+export function observeAncestry(worktree, ancestor, descendant, options = {}) {
+  const probe = git(worktree, ["merge-base", "--is-ancestor", ancestor, descendant], options);
+  if (probe.ok) return "ancestor";
+  if (probe.status === 1) return "not-ancestor";
+  return "indeterminate";
+}
+
+// Attack 1: the test command is run here, by us, and its exit code is recorded
+// from the process rather than from anybody's report. `observed: false` means we
+// could not run it, which is not the same as a pass.
+export function runTests(worktree, command, { runner = spawnSync, skipReason = null, shellCommand = false, timeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS } = {}) {
+  if (!command) {
+    // Finding 1: defaulting a skip reason let omission manufacture review readiness.
+    // Tests must be observed green or explicitly skipped with a caller-declared reason;
+    // omission alone is neither.
+    return { cmd: null, exit: null, observed: false, skipped_reason: skipReason };
+  }
+  const result = shellCommand
+    ? runner(command, [], { cwd: worktree, shell: true, stdio: "inherit", env: process.env, timeout: timeoutMs })
+    : runner(command[0], command.slice(1), { cwd: worktree, encoding: "utf8", shell: false });
+  const exit = Number.isInteger(result?.status) ? result.status : null;
+  return { cmd: shellCommand ? command : command.join(" "), exit, observed: exit !== null, skipped_reason: null };
+}
+
+// Readiness requires completed, clean, changed, observed-diff evidence and tests
+// observed passing or ratified as explicitly skipped with a reason.
+export function deriveReviewReady(evidence) {
+  if (evidence.status !== "completed") return false;
+  // A tree with uncommitted changes cannot produce evidence about the commit it
+  // claims, whatever the tests said.
+  if (evidence.worktree_clean !== true) return false;
+  if (!Array.isArray(evidence.files_changed) || evidence.files_changed.length === 0) return false;
+  if (evidence.diff_observed !== true) return false;
+  const tests = evidence.tests ?? {};
+  if (tests.observed === true) return tests.exit === 0;
+  // A skip is only acceptable when a reason was recorded. Absent tests with no
+  // reason is the shape a fabricated pass would take.
+  return typeof tests.skipped_reason === "string" && tests.skipped_reason.trim().length > 0;
+}
+
+// A claim that disagrees with observation is a finding, not the truth. The
+// disagreement is recorded rather than resolved: the reviewer judges it.
+export function reconcileClaim(claim, observation) {
+  if (claim === null || claim === undefined) return { claimed: false, mismatches: [] };
+  const mismatches = [];
+  const compare = (field, claimed, observed) => {
+    if (claimed === undefined || claimed === null) return;
+    if (Array.isArray(claimed) && Array.isArray(observed)) {
+      const claimedSet = [...claimed].sort().join("\n");
+      const observedSet = [...observed].sort().join("\n");
+      if (claimedSet !== observedSet) mismatches.push({ field, claimed, observed });
+      return;
+    }
+    if (claimed !== observed) mismatches.push({ field, claimed, observed });
+  };
+  compare("commit", claim.commit, observation.commit);
+  compare("files_changed", claim.files_changed, observation.files_changed);
+  compare("status", claim.status, observation.status);
+  // The important one: a claimed passing test against an observed failure or an
+  // unobserved run.
+  if (claim.tests?.exit !== undefined && claim.tests.exit !== null) {
+    compare("tests.exit", claim.tests.exit, observation.tests?.exit ?? null);
+  }
+  return { claimed: true, mismatches };
+}
+
+// Attack 5: a slice may only change paths it declared. Ownership is decided on the
+// observed file list, never on the builder's report of what it touched.
+export function unownedPaths(filesChanged, declaredPaths) {
+  if (!Array.isArray(declaredPaths) || declaredPaths.length === 0) return [...filesChanged];
+  return filesChanged.filter((file) => !declaredPaths.some((declared) => coversPath(declared, file)));
+}
+
+function coversPath(declared, file) {
+  const normalizedDeclared = declared.replace(/\/+$/u, "");
+  if (file === normalizedDeclared) return true;
+  // A directory declaration covers its subtree; a prefix that is not a path
+  // boundary does not, so "src/app" must not cover "src/application/x".
+  return file.startsWith(`${normalizedDeclared}/`);
+}
+
+// .gitignore can conceal files from cleanliness and observed-diff checks, so it is
+// refused with control-plane prefixes regardless of ownership. Ecosystem manifests
+// are authorized through ratified seeded ownership instead.
+const PRIVILEGED_PREFIXES = Object.freeze([CONTROL_PLANE, ".git"]);
+// `.factory.json` is the repository's declaration of how to resolve, verify, publish and publish-as.
+// It is committed rather than ignored, so ownership cannot come from gitignore the way the run
+// directory's does; it comes from here. A run that could edit it could redefine what it is allowed to
+// run, which is the one thing configuration must not be able to do.
+const PRIVILEGED_EXACT = Object.freeze([".gitignore", ".factory.json"]);
+
+export function privilegedPaths(filesChanged) {
+  return filesChanged.filter((file) => PRIVILEGED_PREFIXES.some((prefix) => file === prefix || file.startsWith(`${prefix}/`))
+    || PRIVILEGED_EXACT.includes(file));
+}
+
+export function buildEvidence({ subject, runId, attempt, branch, baseRef, worktree, status, blockedReason = null, claim = null, testCommand = null, skipReason = null, shellCommand = false, testTimeoutMs = DEFAULT_REPOSITORY_VERIFY_TIMEOUT_MS, options = {} }) {
+  // Cleanliness is established before anything else is observed, because every later
+  // fact - the diff, the commit, and above all the test result - is only about the
+  // recorded commit if the tree has nothing uncommitted in it.
+  const cleanliness = observeCleanliness(worktree, options);
+  const observation = observeWorktree(worktree, baseRef, options);
+  // Tests are not run at all against a dirty tree: running them would produce a
+  // result about bytes that are not going to merge.
+  const tests = cleanliness.clean
+    ? runTests(worktree, testCommand, { ...options, skipReason, shellCommand, timeoutMs: testTimeoutMs })
+    : { cmd: testCommand ? (shellCommand ? testCommand : testCommand.join(" ")) : null, exit: null, observed: false, skipped_reason: null };
+
+  // Third round, finding 1: cleanliness was a pre-test snapshot, so a test that wrote
+  // tracked files left the tree dirty while the evidence still claimed a clean HEAD -
+  // and the same test then failed on the merged tree. The tree and the commit are
+  // re-observed after the run, and both must be unchanged for the result to describe
+  // the recorded commit.
+  //
+  // This does NOT close the case where another process mutates the worktree during the
+  // run and restores it before the end: both observations are clean and the commit
+  // matches, so no before/after comparison can see it. Closing that needs tests run from
+  // an isolated checkout. Left open deliberately - its precondition is a second writer
+  // in this slice's worktree, meaning a builder that has not actually finished or two
+  // slices sharing a worktree, which is an orchestration error rather than one of the
+  // twelve attacks.
+  const afterTests = observeCleanliness(worktree, options);
+  const headAfter = git(worktree, ["rev-parse", options.ref ?? "HEAD"], options);
+  const stableUnderTest = cleanliness.clean
+    && afterTests.clean
+    && headAfter.ok
+    && headAfter.stdout.trim() === observation.commit;
+  const evidence = {
+    subject,
+    // Finding 2: evidence carried no run identity, so a record from another run with a
+    // matching subject was accepted and merged.
+    run_id: runId ?? null,
+    attempt,
+    branch,
+    base_ref: baseRef,
+    worktree,
+    status,
+    blocked_reason: blockedReason ?? cleanliness.reason ?? (stableUnderTest ? null : "worktree changed while the tests ran"),
+    // Named for what it asserts: clean before the run, still clean after, and HEAD did
+    // not move. A pre-test snapshot alone was not enough.
+    worktree_clean: stableUnderTest,
+    files_changed: observation.files_changed,
+    diff_stat: observation.diff_stat,
+    diff_observed: observation.diff_observed,
+    commands: observation.commands,
+    tests,
+    commit: observation.commit,
+    observed_by: "orchestrator",
+    review_ready: false,
+    claim_reconciliation: { claimed: false, mismatches: [] },
+  };
+  evidence.review_ready = deriveReviewReady(evidence);
+  evidence.claim_reconciliation = reconcileClaim(claim, evidence);
+  // A claim that disagrees with what we observed cannot be review-ready: the
+  // disagreement is itself the finding.
+  if (evidence.claim_reconciliation.mismatches.length > 0) evidence.review_ready = false;
+  return evidence;
+}
+
+export function resolveWorktree(repo, worktree) {
+  const absolute = resolve(repo, worktree);
+  const rel = relative(resolve(repo), absolute);
+  if (rel.startsWith("..") || rel.startsWith(sep) || !existsSync(absolute)) return null;
+  return absolute;
+}
+
+export function proveInitContainment({ operatorRoot, sandboxPath, runId, worktree }) {
+  const container = join(operatorRoot, ".factory-sandboxes");
+  if (sandboxPath !== join(container, runId)) throw new Error("sandbox is not the exact derived run path");
+  exactDirectory(operatorRoot);
+  exactDirectory(container);
+  exactDirectory(sandboxPath);
+  if (dirname(sandboxPath) !== container || realpathSync(dirname(sandboxPath)) !== container) throw new Error("sandbox parent is not the canonical container");
+
+  const gitDirectory = join(sandboxPath, ".git");
+  if (gitPath(sandboxPath, ["rev-parse", "--show-toplevel"]) !== sandboxPath) throw new Error("sandbox Git top level escapes the sandbox");
+  exactDirectory(gitDirectory);
+  if (gitPath(sandboxPath, ["rev-parse", "--absolute-git-dir"]) !== gitDirectory) throw new Error("sandbox Git directory is not S/.git");
+  if (gitPath(sandboxPath, ["rev-parse", "--git-common-dir"]) !== gitDirectory) throw new Error("sandbox Git common directory is not S/.git");
+
+  const configuredWorktree = resolve(sandboxPath, worktree);
+  if (!within(configuredWorktree, sandboxPath)) throw new Error("configured worktree escapes the sandbox");
+  inspectComponents(sandboxPath, configuredWorktree);
+  exactDirectory(configuredWorktree);
+  const worktreeTop = gitPath(configuredWorktree, ["rev-parse", "--show-toplevel"]);
+  if (worktreeTop !== sandboxPath && worktreeTop !== configuredWorktree) throw new Error("configured worktree Git top level escapes the sandbox");
+  const worktreeGitDirectory = gitPath(configuredWorktree, ["rev-parse", "--absolute-git-dir"]);
+  if (!within(worktreeGitDirectory, gitDirectory)) throw new Error("configured worktree Git directory escapes S/.git");
+  assertWorktreeRelationship(sandboxPath, configuredWorktree, gitDirectory, worktreeTop, worktreeGitDirectory);
+  if (gitPath(configuredWorktree, ["rev-parse", "--git-common-dir"]) !== gitDirectory) throw new Error("configured worktree Git common directory is not S/.git");
+
+  const factory = ensureDirectory(join(sandboxPath, CONTROL_PLANE), sandboxPath);
+  const runDir = ensureDirectory(join(factory, runId), factory);
+  const directories = [
+    ...["plan", "artifacts", "evidence", "reviews"].map((name) => ensureDirectory(join(runDir, name), runDir)),
+    ensureDirectory(join(factory, "worktrees"), factory),
+  ];
+  directories.push(ensureDirectory(join(directories.at(-1), runId), directories.at(-1)));
+
+  for (const path of [operatorRoot, container, sandboxPath, gitDirectory, configuredWorktree, factory, runDir, ...directories]) exactDirectory(path);
+  const finalTop = gitPath(configuredWorktree, ["rev-parse", "--show-toplevel"]);
+  const finalGitDirectory = gitPath(configuredWorktree, ["rev-parse", "--absolute-git-dir"]);
+  if (gitPath(sandboxPath, ["rev-parse", "--show-toplevel"]) !== sandboxPath
+    || gitPath(sandboxPath, ["rev-parse", "--absolute-git-dir"]) !== gitDirectory
+    || gitPath(sandboxPath, ["rev-parse", "--git-common-dir"]) !== gitDirectory
+    || gitPath(configuredWorktree, ["rev-parse", "--git-common-dir"]) !== gitDirectory) {
+    throw new Error("final Git containment proof failed");
+  }
+  assertWorktreeRelationship(sandboxPath, configuredWorktree, gitDirectory, finalTop, finalGitDirectory);
+  return { sandboxPath, configuredWorktree };
+}
+
+function exactDirectory(path) {
+  const stats = lstatSync(path);
+  if (stats.isSymbolicLink() || !stats.isDirectory() || realpathSync(path) !== path) throw new Error(`unsafe directory '${path}'`);
+  return path;
+}
+
+function ensureDirectory(path, parent) {
+  exactDirectory(parent);
+  try {
+    exactDirectory(path);
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    mkdirSync(path);
+    exactDirectory(path);
+  }
+  if (dirname(path) !== parent || realpathSync(dirname(path)) !== parent || !within(realpathSync(path), parent, true)) throw new Error(`directory escapes its parent '${path}'`);
+  return path;
+}
+
+function inspectComponents(root, target) {
+  const path = relative(root, target);
+  let cursor = root;
+  for (const part of path.split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    const stats = lstatSync(cursor);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) throw new Error(`unsafe configured worktree component '${cursor}'`);
+  }
+}
+
+function gitPath(cwd, args) {
+  const result = git(cwd, args);
+  if (!result.ok || !result.stdout.trim()) throw new Error(`Git observation failed: git ${args.join(" ")}`);
+  return realpathSync(resolve(cwd, result.stdout.trim()));
+}
+
+function assertWorktreeRelationship(sandbox, worktree, gitDirectory, top, observedGitDirectory) {
+  if (top === sandbox && observedGitDirectory === gitDirectory) return;
+  if (worktree !== sandbox && top === worktree && within(observedGitDirectory, gitDirectory, true)) return;
+  throw new Error("configured worktree Git relationship is not contained");
+}
+
+function within(child, parent, strict = false) {
+  const path = relative(parent, child);
+  return (!strict && path === "") || (path !== "" && path !== ".." && !path.startsWith(`..${sep}`) && !path.startsWith(sep));
+}
+
+function summarize(result) {
+  const text = (result.ok ? result.stdout : result.stderr).trim().split("\n")[0] ?? "";
+  return text.length > 200 ? `${text.slice(0, 197)}...` : text;
+}
+
+export const EVIDENCE_DIR = "evidence";
+export const evidenceRef = (subject) => join(EVIDENCE_DIR, `${subject}.json`);

package/observe/repair-record.js

@@ -0,0 +1,300 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { git, privilegedPaths } from "./index.js";
+import { parseRepositoryConfig } from "./repository-config.js";
+import { repositoryRelativePath, validateRun } from "../state/schema.js";
+
+export const REPAIR_JOURNAL_REF = "artifacts/post-merge-repairs.md";
+export const REPAIR_EVIDENCE_PREFIX = "repair-reverification.";
+
+const SHA = /^[0-9a-f]{40}$/u;
+const DIGEST = /^sha256:[0-9a-f]{64}$/u;
+const RECORD_ID = /^repair-([0-9a-f]{40})-([1-9][0-9]*)$/u;
+const JOURNAL_KEYS = ["version", "records"];
+const RECORD_KEYS = ["record_id", "introducing_merge", "attempt", "starting_head", "trigger", "trigger_result", "test_paths", "cause", "property_outcome", "repair_commit", "post_repair_result", "status"];
+const MARKER_KEYS = ["version", "run_id", "record_id", "attempt", "run_sha256", "journal_sha256", "record_sha256", "introducing_merge", "repair_commit", "trigger", "started_at"];
+const RESULT_KEYS = ["version", "run_id", "record_id", "attempt", "marker_sha256", "run_sha256", "journal_sha256", "record_sha256", "introducing_merge", "repair_commit", "trigger", "result", "observed_at", "observed_by"];
+const STATUSES = ["planned", "committed", "verified", "failed", "exhausted", "needs-human"];
+
+const fail = (message) => { throw new Error(`repair state is invalid: ${message}`); };
+const sameKeys = (value, keys) => value && typeof value === "object" && !Array.isArray(value)
+  && JSON.stringify(Object.keys(value)) === JSON.stringify(keys);
+const nonblank = (value) => typeof value === "string" && Boolean(value.trim());
+const positive = (value) => Number.isSafeInteger(value) && value > 0;
+const digest = (value) => `sha256:${createHash("sha256").update(JSON.stringify(value), "utf8").digest("hex")}`;
+const equal = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function canonicalFile(path, label, { optional = false } = {}) {
+  let stats;
+  let bytes;
+  try {
+    stats = lstatSync(path);
+    if (!stats.isFile() || stats.isSymbolicLink()) fail(`${label} is not a regular non-symlink file`);
+    bytes = readFileSync(path);
+  } catch (error) {
+    if (optional && error?.code === "ENOENT") return null;
+    if (String(error.message).startsWith("repair state is invalid:")) throw error;
+    fail(`${label} could not be read: ${error.message}`);
+  }
+  let text;
+  let value;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    value = JSON.parse(text);
+  } catch {
+    fail(`${label} is not canonical UTF-8 JSON`);
+  }
+  if (!bytes.equals(Buffer.from(`${JSON.stringify(value, null, 2)}\n`, "utf8"))) fail(`${label} bytes are not canonical`);
+  return { bytes, value };
+}
+
+function validResult(value) {
+  return sameKeys(value, ["observed", "exit"])
+    && typeof value.observed === "boolean"
+    && ((value.observed && Number.isSafeInteger(value.exit) && value.exit >= 0)
+      || (!value.observed && value.exit === null));
+}
+
+function validateRecord(row, index, run) {
+  const label = `journal record ${index + 1}`;
+  if (!sameKeys(row, RECORD_KEYS)) fail(`${label} has the wrong key order or shape`);
+  const match = RECORD_ID.exec(row.record_id);
+  if (!match || !positive(row.attempt) || Number(match[2]) !== row.attempt || !Number.isSafeInteger(Number(match[2]))
+    || match[1] !== row.introducing_merge) fail(`${label} has an invalid record binding`);
+  if (!SHA.test(row.starting_head) || !STATUSES.includes(row.status)) fail(`${label} has an invalid head or status`);
+  if (!sameKeys(row.trigger, ["command", "timeout_ms"]) || !nonblank(row.trigger.command) || !positive(row.trigger.timeout_ms)) {
+    fail(`${label} has an invalid trigger`);
+  }
+  if (!validResult(row.trigger_result) || !row.trigger_result.observed || row.trigger_result.exit === 0) {
+    fail(`${label} does not record an observed failing trigger`);
+  }
+  if (!Array.isArray(row.test_paths) || row.test_paths.length === 0
+    || row.test_paths.some((path) => !repositoryRelativePath(path))
+    || new Set(row.test_paths).size !== row.test_paths.length
+    || !equal(row.test_paths, [...row.test_paths].sort()) || privilegedPaths(row.test_paths).length > 0) {
+    fail(`${label} has invalid canonical test paths`);
+  }
+  if (!nonblank(row.cause) || row.attempt > run.max_retries) fail(`${label} has an invalid cause or exceeds max_retries`);
+  const property = nonblank(row.property_outcome);
+  const commit = SHA.test(String(row.repair_commit));
+  const result = validResult(row.post_repair_result);
+  const pass = result && row.post_repair_result.observed && row.post_repair_result.exit === 0;
+  const observedFailure = result && row.post_repair_result.observed && row.post_repair_result.exit > 0;
+  const unobserved = result && !row.post_repair_result.observed;
+  const validShape = (row.status === "planned" && row.property_outcome === null && row.repair_commit === null && row.post_repair_result === null)
+    || (row.status === "committed" && property && commit && row.post_repair_result === null)
+    || (row.status === "verified" && property && commit && pass)
+    || (row.status === "failed" && property && commit && observedFailure)
+    || (row.status === "exhausted" && property && commit && observedFailure && row.attempt === run.max_retries)
+    || (row.status === "needs-human" && ((row.property_outcome === null && row.repair_commit === null && row.post_repair_result === null)
+      || (property && commit && (observedFailure || unobserved))));
+  if (!validShape) fail(`${label} has a status-conditioned shape mismatch`);
+  return row;
+}
+
+function gitValue(repo, args, label) {
+  const observed = git(repo, args);
+  if (!observed.ok) fail(`${label} could not be observed`);
+  return observed.stdout;
+}
+
+function validateBindings(repo, row, run) {
+  const slices = run.slices.filter((slice) => slice.status === "merged" && slice.merge_commit === row.introducing_merge);
+  if (slices.length !== 1) fail(`record '${row.record_id}' introducing merge does not identify exactly one merged slice`);
+  if (!git(repo, ["merge-base", "--is-ancestor", row.introducing_merge, row.starting_head]).ok) {
+    fail(`record '${row.record_id}' starting head does not descend from its introducing merge`);
+  }
+  if (row.repair_commit === null) return;
+  if (row.repair_commit === row.introducing_merge) fail(`record '${row.record_id}' repair commit equals its introducing merge`);
+  const parents = gitValue(repo, ["rev-list", "--parents", "-n", "1", row.repair_commit], `record '${row.record_id}' repair commit`)
+    .trim().split(/\s+/u).slice(1);
+  if (parents.length !== 1 || parents[0] !== row.starting_head) fail(`record '${row.record_id}' repair commit has the wrong parent`);
+  const paths = gitValue(repo, ["--literal-pathspecs", "diff", "--name-only", "--no-renames", "-z", row.starting_head, row.repair_commit], `record '${row.record_id}' repair diff`)
+    .split("\0").filter(Boolean).sort();
+  if (paths.length === 0 || !equal(paths, row.test_paths)) fail(`record '${row.record_id}' repair diff does not equal test_paths`);
+  let config;
+  try {
+    config = parseRepositoryConfig(gitValue(repo, ["show", `${row.repair_commit}:.factory.json`], `record '${row.record_id}' committed config`));
+  } catch (error) {
+    fail(`record '${row.record_id}' committed config is invalid: ${error.message}`);
+  }
+  if (config.command !== row.trigger.command || config.timeoutMs !== row.trigger.timeout_ms) {
+    fail(`record '${row.record_id}' trigger does not match its committed config`);
+  }
+}
+
+function validateJournal(value, run, repo) {
+  if (!sameKeys(value, JOURNAL_KEYS) || value.version !== 1 || !Array.isArray(value.records) || value.records.length === 0) {
+    fail("journal has the wrong version, key order, or shape");
+  }
+  const records = value.records.map((row, index) => validateRecord(row, index, run));
+  const ids = new Set();
+  const chains = new Map();
+  let active = 0;
+  for (const row of records) {
+    if (ids.has(row.record_id)) fail(`duplicate record '${row.record_id}'`);
+    ids.add(row.record_id);
+    if (["planned", "committed"].includes(row.status)) active += 1;
+    const chain = chains.get(row.introducing_merge) ?? [];
+    const prior = chain.at(-1);
+    if (row.attempt !== chain.length + 1) fail(`record '${row.record_id}' is not the next contiguous attempt`);
+    if (prior && (prior.status !== "failed" || row.starting_head !== prior.repair_commit)) {
+      fail(`record '${row.record_id}' does not validly follow the prior repair attempt`);
+    }
+    chain.push(row);
+    chains.set(row.introducing_merge, chain);
+    validateBindings(repo, row, run);
+  }
+  if (active > 1) fail("more than one repair record is active");
+  return { records, chains };
+}
+
+function canonicalTimestamp(value) {
+  const parsed = typeof value === "string" ? Date.parse(value) : NaN;
+  return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
+function validateMarker(value, row, runId, attempt, label) {
+  if (!sameKeys(value, MARKER_KEYS) || value.version !== 1 || value.run_id !== runId
+    || value.record_id !== row.record_id || value.attempt !== attempt
+    || !DIGEST.test(value.run_sha256) || !DIGEST.test(value.journal_sha256)
+    || value.record_sha256 !== digest(row) || value.introducing_merge !== row.introducing_merge
+    || value.repair_commit !== row.repair_commit || !equal(value.trigger, row.trigger)
+    || !sameKeys(value.trigger, ["command", "timeout_ms"]) || !canonicalTimestamp(value.started_at)) {
+    fail(`${label} has an invalid marker binding or schema`);
+  }
+}
+
+function validateExecutionResult(value) {
+  return sameKeys(value, ["observed", "exit", "commit", "worktree_clean"])
+    && typeof value.observed === "boolean"
+    && ((value.observed && Number.isSafeInteger(value.exit) && value.exit >= 0) || (!value.observed && value.exit === null))
+    && (value.commit === null || SHA.test(value.commit)) && typeof value.worktree_clean === "boolean";
+}
+
+function validateResult(value, marker, row, runId, attempt, label) {
+  if (!sameKeys(value, RESULT_KEYS) || value.version !== 1 || value.run_id !== runId
+    || value.record_id !== row.record_id || value.attempt !== attempt || value.marker_sha256 !== digest(marker)
+    || value.run_sha256 !== marker.run_sha256 || value.journal_sha256 !== marker.journal_sha256
+    || value.record_sha256 !== marker.record_sha256 || value.introducing_merge !== marker.introducing_merge
+    || value.repair_commit !== marker.repair_commit || !equal(value.trigger, marker.trigger)
+    || !sameKeys(value.trigger, ["command", "timeout_ms"]) || !validateExecutionResult(value.result)
+    || !canonicalTimestamp(value.observed_at) || value.observed_at !== marker.started_at || value.observed_by !== "factory") {
+    fail(`${label} has an invalid result binding or schema`);
+  }
+}
+
+function evidenceEntries(runDir) {
+  const dir = join(runDir, "evidence");
+  let stats;
+  try {
+    stats = lstatSync(dir);
+  } catch (error) {
+    if (error?.code === "ENOENT") return [];
+    fail(`evidence directory could not be inspected: ${error.message}`);
+  }
+  if (!stats.isDirectory() || stats.isSymbolicLink()) fail("evidence path is not a regular directory");
+  try {
+    return readdirSync(dir).filter((name) => name.toLowerCase().startsWith(REPAIR_EVIDENCE_PREFIX)).sort();
+  } catch (error) {
+    fail(`evidence directory could not be read: ${error.message}`);
+  }
+}
+
+function validateInventory(runDir, runId, records) {
+  const rows = new Map(records.map((row) => [row.record_id, row]));
+  const histories = new Map();
+  const filename = /^repair-reverification\.(repair-[0-9a-f]{40}-[1-9][0-9]*)\.([1-9][0-9]*)(\.started)?\.json$/u;
+  for (const name of evidenceEntries(runDir)) {
+    const match = filename.exec(name);
+    if (!match) fail(`evidence entry '${name}' has a malformed repair re-verification name`);
+    const row = rows.get(match[1]);
+    const attempt = Number(match[2]);
+    if (!row || !positive(attempt) || !(row.status === "needs-human" && row.repair_commit !== null)) {
+      fail(`evidence entry '${name}' does not identify an eligible repair record`);
+    }
+    const history = histories.get(row.record_id) ?? { markers: new Map(), results: new Map(), names: [] };
+    const kind = match[3] ? "markers" : "results";
+    const parsed = canonicalFile(join(runDir, "evidence", name), `evidence '${name}'`).value;
+    if (history[kind].has(attempt)) fail(`evidence entry '${name}' duplicates an attempt`);
+    history[kind].set(attempt, parsed);
+    history.names.push(name);
+    histories.set(row.record_id, history);
+  }
+  for (const [recordId, history] of histories) {
+    const row = rows.get(recordId);
+    const attempts = [...history.markers.keys()].sort((a, b) => a - b);
+    if (attempts.some((attempt, index) => attempt !== index + 1)) fail(`evidence for '${recordId}' has a marker gap`);
+    if ([...history.results.keys()].some((attempt) => !history.markers.has(attempt))) fail(`evidence for '${recordId}' has a result without its marker`);
+    let pass = null;
+    for (const attempt of attempts) {
+      const marker = history.markers.get(attempt);
+      validateMarker(marker, row, runId, attempt, `evidence marker for '${recordId}' attempt ${attempt}`);
+      const result = history.results.get(attempt);
+      if (result) {
+        validateResult(result, marker, row, runId, attempt, `evidence result for '${recordId}' attempt ${attempt}`);
+        const qualifies = result.result.observed && result.result.exit === 0
+          && result.result.commit === row.repair_commit && result.result.worktree_clean;
+        if (qualifies) {
+          if (pass !== null) fail(`evidence for '${recordId}' contains a second pass`);
+          pass = attempt;
+        }
+      } else if (attempt !== attempts.at(-1)) fail(`evidence for '${recordId}' has a non-final marker-only attempt`);
+    }
+    if (pass !== null && (pass !== attempts.at(-1) || !history.results.has(pass))) fail(`evidence for '${recordId}' continues after its first pass`);
+    history.attempts = attempts.length;
+    history.tail = attempts.length > 0 && !history.results.has(attempts.at(-1));
+    history.pass = pass;
+    history.names.sort();
+  }
+  return histories;
+}
+
+export function readRepairState({ runDir, state = null, runId, repo, recordId = null } = {}) {
+  let runBytes;
+  let rawRun;
+  try {
+    runBytes = readFileSync(join(runDir, "run.json"));
+    rawRun = validateRun(JSON.parse(runBytes.toString("utf8")));
+  } catch (error) {
+    fail(`run.json could not be validated: ${error.message}`);
+  }
+  const run = validateRun(state ?? rawRun);
+  if (run.run_id !== runId || rawRun.run_id !== runId) fail(`run ID does not equal loaded run_id '${rawRun.run_id}'`);
+  const journalPath = join(runDir, REPAIR_JOURNAL_REF);
+  const journalFile = canonicalFile(journalPath, REPAIR_JOURNAL_REF, { optional: true });
+  if (!journalFile) {
+    const inventory = validateInventory(runDir, runId, []);
+    if (recordId !== null) fail(`repair journal is absent; record '${recordId}' does not exist`);
+    return { run, runBytes, journal: null, journalBytes: null, records: [], chains: new Map(), inventory, selected: null };
+  }
+  if (!repo) fail("repository is required to validate the repair journal");
+  const { records, chains } = validateJournal(journalFile.value, run, repo);
+  const inventory = validateInventory(runDir, runId, records);
+  let selected = null;
+  if (recordId !== null) {
+    const matches = records.filter((row) => row.record_id === recordId);
+    if (matches.length !== 1) fail(`record '${recordId}' does not identify exactly one journal row`);
+    selected = matches[0];
+    if (chains.get(selected.introducing_merge)?.at(-1) !== selected
+      || selected.status !== "needs-human" || selected.repair_commit === null) {
+      fail(`record '${recordId}' is not the latest eligible post-commit needs-human row`);
+    }
+  }
+  return { run, runBytes, journal: journalFile.value, journalBytes: journalFile.bytes,
+    records, chains, inventory, selected, selectedHistory: selected ? inventory.get(recordId) ?? { markers: new Map(), results: new Map(), names: [], attempts: 0, tail: false, pass: null } : null };
+}
+
+export function assertRepairPublicationReady(options) {
+  const observed = readRepairState(options);
+  let tested = null;
+  for (const chain of observed.chains.values()) {
+    const row = chain.at(-1);
+    const history = observed.inventory.get(row.record_id);
+    const effective = row.status === "verified" || (row.status === "needs-human" && history?.pass !== null && history?.pass !== undefined);
+    if (!effective) throw new Error(`repair record '${row.record_id}' remains ${row.status} and blocks publication`);
+    if (row.status === "needs-human" && history?.pass && row.repair_commit === options.head) tested = row.repair_commit;
+  }
+  return { tested, observed };
+}