full-reverse 0.0.0-stage → 1.0.0

package/skills/full-reverse/scripts/lib/validate.mjs

@@ -0,0 +1,1133 @@
+// Deterministic workspace validation. Checks report verified | failed | unverified.
+// This proves structure, integrity and reference resolution, never that evidence
+// semantically supports a statement (that is the verify specialist's review).
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { DEFAULT_MAX_PARSE_BYTES, inspectFile } from "./rea.mjs";
+import { validateSchema, loadValidators, PINNED_AJV } from "./schemas.mjs";
+import { scopeDigest } from "./scope.mjs";
+import { ExternalFacts, PointerStore, judgeExternal, judgePointer } from "./selectors.mjs";
+import { EVIDENCE_DIRS, INDEX_PATH, kindDir, matchBuild, semanticDigest, walkFiles } from "./workspace.mjs";
+import { hashFile, normalizeRelPath, openWorkspace, resolveInWorkspace, sha256Buffer } from "./util.mjs";
+
+const RANK = { observed: 3, derived: 2, inferred: 1, unknown: 0, unavailable: 0 };
+const ASSERTING = new Set(["observed", "derived", "inferred"]);
+const CANONICAL_KINDS = new Set(["canonical-record", "canonical-bundle", "derived-view"]);
+const MAX_DOC_BYTES = 256 * 1024 * 1024;
+const MAX_LISTED_CHECKS = 400;
+
+class Report {
+  constructor(mode) {
+    this.mode = mode;
+    this.checks = [];
+    this.counts = {};
+    this.totals = { verified: 0, failed: 0, unverified: 0 };
+    this.errorFailed = 0;
+    this.errorUnverified = 0;
+    this.resumeBlockers = [];
+    this.omitted = 0;
+    this.verbose = false;
+  }
+
+  add(rule, status, subject, message, { reason, severity = "error", modes, details } = {}) {
+    // modes: modes in which this check is severity "error"; elsewhere it is a warning.
+    const effective = modes && !modes.includes(this.mode) ? "warning" : severity;
+    this.totals[status] += 1;
+    const bucket = (this.counts[rule] ??= { verified: 0, failed: 0, unverified: 0 });
+    bucket[status] += 1;
+    if (effective === "error") {
+      if (status === "failed") this.errorFailed += 1;
+      if (status === "unverified") this.errorUnverified += 1;
+    }
+    if (modes?.includes("resume") && status !== "verified" && effective === "error") this.resumeBlockers.push(`${rule}:${subject}`);
+    if (status === "verified" && !this.verbose) return;
+    if (this.checks.length >= MAX_LISTED_CHECKS && !this.verbose) {
+      this.omitted += 1;
+      return;
+    }
+    this.checks.push({ id: `${rule}:${subject}`, rule, status, severity: effective, subject, message, ...(reason ? { reason } : {}), ...(details ? { details } : {}) });
+  }
+
+  ok(rule, subject, message, opts) {
+    this.add(rule, "verified", subject, message, opts);
+  }
+
+  fail(rule, subject, message, opts) {
+    this.add(rule, "failed", subject, message, opts);
+  }
+
+  unv(rule, subject, message, opts) {
+    this.add(rule, "unverified", subject, message, opts);
+  }
+}
+
+const CLOSURE = ["closure"];
+const NARRATIVE_HEADING = "Narrative (non-factual)";
+
+/**
+ * Line classifier for fenced code blocks (``` or ~~~, closed by the same character with at
+ * least the opening length). Returns true for fence delimiters and lines inside a fence, so
+ * a longer outer fence may contain shorter example fences.
+ */
+function makeFenceTracker() {
+  let open = null;
+  return (line) => {
+    const m = /^\s*(`{3,}|~{3,})(.*)$/.exec(line);
+    if (open) {
+      if (m && m[1][0] === open.char && m[1].length >= open.length && m[2].trim() === "") open = null;
+      return true;
+    }
+    if (m && !(m[1][0] === "`" && m[2].includes("`"))) {
+      open = { char: m[1][0], length: m[1].length };
+      return true;
+    }
+    return false;
+  };
+}
+
+/** Inline markdown link targets outside code fences and inline code spans (images excluded). */
+function markdownLinkTargets(body) {
+  const inFenceLine = makeFenceTracker();
+  const targets = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (inFenceLine(line)) continue;
+    const stripped = line.replace(/`+[^`]*`+/g, "");
+    for (const m of stripped.matchAll(/(!?)\[[^\]]*\]\(\s*(?:<([^>]*)>|([^)\s]*))(?:\s+(?:"[^"]*"|'[^']*'))?\s*\)/g)) {
+      if (m[1]) continue;
+      targets.push(m[2] ?? m[3] ?? "");
+    }
+  }
+  return targets;
+}
+
+function forEachRef(node, fn) {
+  if (Array.isArray(node)) {
+    for (const item of node) forEachRef(item, fn);
+  } else if (node && typeof node === "object") {
+    if ((node.kind === "canonical" || node.kind === "external") && typeof node.file === "string" && typeof node.sha256 === "string") fn(node);
+    for (const value of Object.values(node)) if (value && typeof value === "object") forEachRef(value, fn);
+  }
+}
+
+const refKey = (ref) => `${ref.kind}|${ref.file}|${ref.sha256}|${ref.evidence_id ?? ref.ext_id}`;
+const describeErrors = (errors) => errors.slice(0, 5).map((e) => `${e.path} ${e.message}`).join("; ");
+
+export async function validateWorkspace({ workspace, mode = "progress", maxParseBytes = DEFAULT_MAX_PARSE_BYTES, verbose = false, checkTargets = false }) {
+  const ws = await openWorkspace(workspace);
+  const r = new Report(mode);
+  r.verbose = verbose;
+  const { ajvVersion } = await loadValidators();
+  const closure = mode === "closure";
+  const targets = checkTargets || mode === "resume";
+
+  // ---- load documents -------------------------------------------------------------
+  const docs = {};
+  const loadDoc = async (rel, schema, { required }) => {
+    const resolved = await resolveInWorkspace(ws.abs, rel).catch((error) => ({ error }));
+    if (resolved.error) {
+      r.fail("workspace.path", rel, resolved.error.message);
+      return { exists: false, valid: false };
+    }
+    if (!resolved.exists) {
+      if (required) r.fail("workspace.file_missing", rel, `${rel} is missing`);
+      return { exists: false, valid: false };
+    }
+    if (!resolved.stat.isFile()) {
+      r.fail("workspace.path", rel, `${rel} is not a regular file`);
+      return { exists: true, valid: false };
+    }
+    if (resolved.stat.size > MAX_DOC_BYTES) {
+      r.unv(`schema.${schema}`, rel, `${rel} is ${resolved.stat.size} bytes; exceeds the ${MAX_DOC_BYTES} byte document limit`, { reason: "document_size_limit" });
+      return { exists: true, valid: false };
+    }
+    const buffer = await fsp.readFile(resolved.abs);
+    const sha256 = sha256Buffer(buffer);
+    let doc;
+    try {
+      doc = JSON.parse(buffer.toString("utf8"));
+    } catch (error) {
+      r.fail(`schema.${schema}`, rel, `${rel} is not valid JSON: ${error.message}`, { reason: "json_parse_failed" });
+      return { exists: true, valid: false, sha256 };
+    }
+    const result = await validateSchema(schema, doc);
+    if (!result.valid) {
+      r.fail(`schema.${schema}`, rel, `${rel} violates schema ${schema}: ${describeErrors(result.errors)}`, { details: result.errors });
+      return { exists: true, valid: false, sha256, doc };
+    }
+    r.ok(`schema.${schema}`, rel, "schema valid");
+    return { exists: true, valid: true, sha256, bytes: buffer.length, doc };
+  };
+
+  const D = {
+    investigation: await loadDoc("investigation.json", "investigation", { required: true }),
+    index: await loadDoc(INDEX_PATH, "evidence-index", { required: true }),
+    inventory: await loadDoc("inventory.json", "inventory", { required: false }),
+    claims: await loadDoc("claims.json", "claims", { required: false }),
+    review: await loadDoc("review.json", "review", { required: false }),
+  };
+  const inv = D.investigation.valid ? D.investigation.doc : null;
+  const idx = D.index.valid ? D.index.doc : null;
+  const inventory = D.inventory.valid ? D.inventory.doc : null;
+  const claimsDoc = D.claims.valid ? D.claims.doc : null;
+  const review = D.review.valid ? D.review.doc : null;
+
+  const base = {
+    tool: { name: "full-reverse-validator", ajv: ajvVersion, ajv_pinned: PINNED_AJV, node: process.versions.node },
+    command: "validate",
+    mode,
+    workspace: ws.abs,
+    max_parse_bytes: maxParseBytes,
+  };
+  if (!inv || !idx) {
+    r.fail("validation.prerequisites", "workspace", "investigation.json and evidence/index.json must both be valid before dependent checks can run");
+    return finish(r, base, D, { steps: [] });
+  }
+
+  // ---- identity across documents -------------------------------------------------
+  for (const [name, doc] of [["evidence/index.json", idx], ["inventory.json", inventory], ["claims.json", claimsDoc], ["review.json", review]]) {
+    if (doc && doc.investigation_id !== inv.investigation_id) {
+      r.fail("workspace.investigation_id", name, `${name} belongs to ${doc.investigation_id}, expected ${inv.investigation_id}`);
+    }
+  }
+
+  // ---- builds ----------------------------------------------------------------------
+  const builds = new Map();
+  for (const build of inv.builds) {
+    if (builds.has(build.build_id)) r.fail("build.unique", build.build_id, "duplicate build_id");
+    builds.set(build.build_id, build);
+  }
+  const digestOwners = new Map();
+  for (const build of inv.builds) {
+    const owners = digestOwners.get(build.identity.sha256) ?? [];
+    owners.push(build.build_id);
+    digestOwners.set(build.identity.sha256, owners);
+    if (build.parent_build_id !== null && !builds.has(build.parent_build_id)) r.fail("build.parent", build.build_id, `unknown parent ${build.parent_build_id}`);
+    if (build.kind === "member" && build.parent_build_id === null) r.fail("build.parent", build.build_id, "member builds need parent_build_id (member identity is kept separate from the archive)");
+    if (build.identity.method === "archive-member" && build.parent_build_id === null) r.fail("build.parent", build.build_id, "archive-member identity needs parent_build_id");
+    if (build.identity.method === "file-sha256" && build.identity.coverage !== "complete") r.fail("build.identity", build.build_id, "file-sha256 identity must have complete coverage");
+    if (build.identity.method === "file-sha256" && build.identity.bytes === null) r.unv("build.identity", build.build_id, "file-sha256 identity lacks byte size", { severity: "warning" });
+    if (build.identity.method === "rea-subject-digest" && build.identity.coverage !== "complete") {
+      r.ok("build.identity", build.build_id, `REA subject digest with ${build.identity.coverage} coverage; not a whole-directory fingerprint`);
+    }
+  }
+  for (const [digest, owners] of digestOwners) {
+    if (owners.length > 1) r.add("build.unique_digest", "unverified", digest.slice(0, 12), `builds ${owners.join(", ")} share one identity digest; evidence cannot distinguish them`, { severity: "warning" });
+  }
+  for (const build of inv.builds) {
+    const seen = new Set();
+    for (let cursor = build; cursor?.parent_build_id; cursor = builds.get(cursor.parent_build_id)) {
+      if (seen.has(cursor.build_id)) {
+        r.fail("build.parent", build.build_id, "parent chain is cyclic");
+        break;
+      }
+      seen.add(cursor.build_id);
+    }
+  }
+
+  // ---- planned/running work decides which resume blockers are real ------------------------
+  // Superseded, disposed or finished history never blocks a resume; only what the next planned or
+  // running step still depends on does. An explicit --check-targets keeps every build blocking.
+  const supersededIds = new Set(inv.steps.map((s) => s.supersedes_step_id).filter((id) => id !== null));
+  const openSteps = inv.steps.filter((s) => s.status === "planned" || s.status === "running");
+  const neededGrants = new Set(openSteps.map((s) => s.authorization_grant_id).filter((id) => id !== null));
+  const neededBuilds = new Set();
+  for (const step of openSteps) {
+    const seen = new Set();
+    for (let id = step.build_id; id && !seen.has(id); id = builds.get(id)?.parent_build_id ?? null) {
+      seen.add(id);
+      neededBuilds.add(id);
+    }
+  }
+
+  // ---- target identity re-check (resume) ------------------------------------------
+  if (targets) {
+    for (const build of inv.builds) {
+      const subject = build.build_id;
+      const blocking = { modes: checkTargets || neededBuilds.has(subject) ? ["resume", "closure"] : [] };
+      if (build.identity.method !== "file-sha256") {
+        r.unv("build.identity_current", subject, `identity method ${build.identity.method} cannot be recomputed by this helper; re-run the REA identity operation and compare the subject digest`, { ...blocking, reason: "requires_rea_reidentification" });
+        continue;
+      }
+      if (!build.local_path) {
+        r.unv("build.identity_current", subject, "no local_path recorded; cannot re-check identity", { ...blocking, reason: "no_local_path" });
+        continue;
+      }
+      const stat = await fsp.stat(build.local_path).catch(() => null);
+      if (!stat?.isFile()) {
+        r.unv("build.identity_current", subject, `target file is unavailable at ${build.local_path}; earlier evidence stays under ${subject} but is not current`, { ...blocking, reason: "target_unavailable" });
+        continue;
+      }
+      const live = await hashFile(build.local_path);
+      if (live.sha256 === build.identity.sha256) r.ok("build.identity_current", subject, "target still matches the recorded identity");
+      else r.fail("build.identity_current", subject, "target bytes changed since identification; new reads need a new build and earlier evidence is not current");
+    }
+  }
+
+  // ---- questions ---------------------------------------------------------------------
+  const questions = new Map();
+  for (const q of inv.questions) {
+    if (questions.has(q.question_id)) r.fail("question.unique", q.question_id, "duplicate question_id");
+    questions.set(q.question_id, q);
+    for (const b of q.build_ids ?? []) if (!builds.has(b)) r.fail("question.build", q.question_id, `unknown build ${b}`);
+    if (q.status === "pending") r.fail("question.final_disposition", q.question_id, "question is still pending", { modes: CLOSURE });
+    else if ((q.status === "partial" || q.status === "unresolved") && !q.reason) r.fail("question.reason", q.question_id, `${q.status} questions need a reason`);
+    else if (q.status !== "pending") r.ok("question.final_disposition", q.question_id, q.status);
+  }
+  if (closure && inv.questions.length === 0) r.fail("question.none", "investigation", "closure needs at least one scoped question", { modes: CLOSURE });
+
+  // ---- authorization and steps ---------------------------------------------------------
+  // A failed or interrupted attempt is disposed once it is finished, annotated, and every question it served is reasoned partial/unresolved.
+  const isDisposed = (step) =>
+    step.finished_at !== null &&
+    step.note.trim() !== "" &&
+    step.question_ids.length > 0 &&
+    step.question_ids.every((id) => {
+      const question = questions.get(id);
+      return question && ["partial", "unresolved"].includes(question.status) && question.reason?.trim();
+    });
+  const grants = new Map(inv.authorizations.map((g) => [g.grant_id, g]));
+  const stepIds = new Map();
+  const stepReport = [];
+  const liveHash = new Map();
+  const hashCached = async (rel) => {
+    if (liveHash.has(rel)) return liveHash.get(rel);
+    const resolved = await resolveInWorkspace(ws.abs, rel).catch(() => null);
+    const value = resolved?.exists && resolved.stat.isFile() ? await hashFile(resolved.abs) : null;
+    liveHash.set(rel, value);
+    return value;
+  };
+  for (const step of inv.steps) {
+    if (stepIds.has(step.step_id)) r.fail("step.unique", step.step_id, "duplicate step_id");
+    stepIds.set(step.step_id, step);
+  }
+  for (const step of inv.steps) {
+    const reasons = [];
+    for (const qid of step.question_ids) if (!questions.has(qid)) r.fail("step.question", step.step_id, `unknown question ${qid}`);
+    if (step.build_id !== null && !builds.has(step.build_id)) r.fail("step.build", step.step_id, `unknown build ${step.build_id}`);
+    if (step.supersedes_step_id !== null) {
+      const prior = stepIds.get(step.supersedes_step_id);
+      if (!prior) r.fail("step.attempt_chain", step.step_id, `supersedes unknown step ${step.supersedes_step_id}`);
+      else {
+        if (step.attempt <= prior.attempt) r.fail("step.attempt_chain", step.step_id, "attempt number must exceed the superseded attempt");
+        else r.ok("step.attempt_chain", step.step_id, "linked retry");
+        if (!["superseded", "interrupted", "failed"].includes(prior.status)) r.unv("step.attempt_chain", step.step_id, `superseded step ${prior.step_id} is ${prior.status}, not superseded/interrupted/failed`, { severity: "warning" });
+      }
+    }
+    if (step.effects.length > 0) {
+      const grant = step.authorization_grant_id ? grants.get(step.authorization_grant_id) : null;
+      if (!grant) r.fail("authorization.step", step.step_id, "step with effects needs an existing authorization_grant_id");
+      else if (grant.build_id !== step.build_id) r.fail("authorization.step", step.step_id, `grant ${grant.grant_id} is bound to ${grant.build_id}, step targets ${step.build_id}`);
+      else if (step.effects.some((effect) => !grant.permitted_effects.includes(effect))) r.fail("authorization.step", step.step_id, `effects exceed grant ${grant.grant_id}: ${step.effects.filter((e) => !grant.permitted_effects.includes(e)).join(",")}`);
+      else r.ok("authorization.step", step.step_id, "effects within grant");
+    }
+    if (step.effects.length > 0 && step.status !== "planned" && step.authorization_grant_id && grants.has(step.authorization_grant_id)) {
+      // Steps that began before the latest resume are history and are never invalidated retroactively.
+      const grant = grants.get(step.authorization_grant_id);
+      const started = Date.parse(step.started_at ?? "");
+      const resumedAt = inv.lifecycle.last_resumed_at ? Date.parse(inv.lifecycle.last_resumed_at) : null;
+      const recordedAt = Date.parse(grant.recorded_at);
+      const reconfirmedInWindow = grant.reconfirmed_at && resumedAt !== null && Date.parse(grant.reconfirmed_at) >= resumedAt && Date.parse(grant.reconfirmed_at) <= started;
+      const grantedThisSession = resumedAt !== null && recordedAt >= resumedAt; // recorded <= started is enforced above
+      if (Number.isFinite(started) && started < recordedAt) r.fail("authorization.fresh", step.step_id, `step started before grant ${grant.grant_id} was recorded`);
+      else if (Number.isFinite(started) && resumedAt !== null && started >= resumedAt && grant.persistence !== "persistent" && !grantedThisSession && !reconfirmedInWindow) r.fail("authorization.fresh", step.step_id, `session grant ${grant.grant_id} was recorded before the last resume and not reconfirmed between the resume and this step`);
+      else if (Number.isFinite(started)) r.ok("authorization.fresh", step.step_id, "grant was recorded and current when the step started");
+      else r.fail("authorization.fresh", step.step_id, "step with effects needs started_at");
+    }
+    if (step.status === "running" || step.status === "interrupted") reasons.push(`step_${step.status}`);
+    if (step.status === "running" || step.status === "interrupted") {
+      if (step.status === "interrupted" && (supersededIds.has(step.step_id) || isDisposed(step))) r.ok("step.state", step.step_id, "interrupted attempt is superseded or disposed; history only");
+      else r.unv("step.state", step.step_id, `step is ${step.status}; its outputs are incomplete and must not be reused`, { modes: ["resume"], reason: `step_${step.status}` });
+    }
+    if (step.status === "running" || step.status === "planned") r.fail("step.closure", step.step_id, `step is ${step.status}; finish, interrupt or remove it before closure`, { modes: ["closure"] });
+    if ((step.status === "interrupted" || step.status === "failed") && !supersededIds.has(step.step_id) && !isDisposed(step)) {
+      r.fail("step.closure", step.step_id, `step is ${step.status} without a superseding attempt or reasoned partial/unresolved question disposition`, { modes: ["closure"] });
+    }
+    if (step.status === "completed") {
+      for (const output of step.outputs) {
+        const live = await hashCached(output.path);
+        if (!live) {
+          r.fail("step.output", `${step.step_id}:${output.path}`, "published output is missing");
+          reasons.push(`output_missing:${output.path}`);
+        } else if (live.sha256 !== output.sha256) {
+          // Mutable outputs may legitimately be republished by a later step; immutable evidence may not change.
+          const immutable = EVIDENCE_DIRS.some((d) => output.path.startsWith(`${d}/`));
+          r.add("step.output", "failed", `${step.step_id}:${output.path}`, immutable ? "immutable evidence output changed" : "output changed after this step completed", { severity: immutable ? "error" : "warning" });
+          reasons.push(`output_changed:${output.path}`);
+        }
+      }
+      for (const input of step.inputs) {
+        const live = await hashCached(input.path);
+        if (!live || live.sha256 !== input.sha256) {
+          reasons.push(`input_changed:${input.path}`);
+          r.add("step.input", "failed", `${step.step_id}:${input.path}`, "input changed or missing since the step completed; do not reuse it as current", { severity: "warning" });
+        }
+      }
+    }
+    stepReport.push({ step_id: step.step_id, status: step.status, attempt: step.attempt, reusable: step.status === "completed" && reasons.length === 0, reasons });
+  }
+  if (mode === "resume") {
+    for (const grant of inv.authorizations) {
+      if (grant.permitted_effects.length === 0) continue;
+      const resumedAt = inv.lifecycle.last_resumed_at;
+      const current = resumedAt && ((grant.reconfirmed_at && Date.parse(grant.reconfirmed_at) >= Date.parse(resumedAt)) || Date.parse(grant.recorded_at) >= Date.parse(resumedAt));
+      if (grant.persistence === "persistent") r.ok("authorization.resume", grant.grant_id, "user-granted persistence; target/effect scope must still match");
+      else if (current) r.ok("authorization.resume", grant.grant_id, "recorded or reconfirmed since resume");
+      else if (neededGrants.has(grant.grant_id)) r.unv("authorization.resume", grant.grant_id, "session-scoped grant must be reconfirmed by the user after this resume before any effect", { modes: ["resume"], reason: "grant_not_reconfirmed" });
+      else r.unv("authorization.resume", grant.grant_id, "session-scoped grant predates this resume; no planned or running step uses it, but it must be reconfirmed before any new effect", { severity: "warning", reason: "grant_not_reconfirmed" });
+    }
+  }
+
+  // ---- evidence index --------------------------------------------------------------------
+  const entryByFile = new Map();
+  const entryById = new Map();
+  const info = new Map(); // file -> { entry, abs, live, trusted }
+  for (const entry of idx.entries) {
+    if (entryById.has(entry.entry_id)) r.fail("evidence.unique", entry.entry_id, "duplicate entry_id");
+    entryById.set(entry.entry_id, entry);
+    if (entryByFile.has(entry.file)) r.fail("evidence.unique", entry.file, "file indexed twice");
+    entryByFile.set(entry.file, entry);
+  }
+  for (const entry of idx.entries) {
+    const subject = entry.entry_id;
+    const state = { entry, abs: null, live: null, trusted: false };
+    info.set(entry.file, state);
+    const normalized = normalizeRelPath(entry.file);
+    const dir = kindDir(entry.kind);
+    if (!normalized || !normalized.startsWith(`${dir}/`)) {
+      r.fail("evidence.path", subject, `${entry.file} must be a safe path under ${dir}/ for kind ${entry.kind}`);
+      continue;
+    }
+    const resolved = await resolveInWorkspace(ws.abs, entry.file).catch((error) => ({ error }));
+    if (resolved.error) {
+      r.fail("evidence.path", subject, resolved.error.message);
+      continue;
+    }
+    if (!resolved.exists || !resolved.stat.isFile()) {
+      r.fail("evidence.file_exists", subject, `indexed file is missing: ${entry.file}`);
+      continue;
+    }
+    state.abs = resolved.abs;
+    const canonicalKind = CANONICAL_KINDS.has(entry.kind);
+    const live = await inspectFile(resolved.abs, { maxParseBytes, shallow: !canonicalKind });
+    state.live = live;
+    if (live.sha256 !== entry.sha256 || live.bytes !== entry.bytes) {
+      r.fail("evidence.file_hash", subject, `${entry.file} content differs from the indexed SHA-256/size`);
+      continue;
+    }
+    r.ok("evidence.file_hash", subject, "streamed SHA-256 and size match");
+    const digest = semanticDigest(entry);
+    const idPrefix = digest.slice(0, 16);
+    if (entry.entry_id !== `ei_${idPrefix}` || !path.posix.basename(entry.file).startsWith(`${idPrefix}-`)) {
+      r.fail("evidence.entry_identity", subject, `entry_id and file name do not derive from the entry's semantic content (expected ei_${idPrefix} and a ${idPrefix}- file prefix); the index entry was edited or mislabeled`);
+      continue;
+    }
+    r.ok("evidence.entry_identity", subject, "entry_id and file prefix derive from the semantic publication digest");
+    if (entry.kind === "external") {
+      const ext = entry.external;
+      if (!ext || ext.ext_id !== `ext_${live.sha256}` || ext.file.sha256 !== live.sha256 || ext.file.path !== entry.file || ext.file.bytes !== live.bytes) {
+        r.fail("evidence.external_identity", subject, "ext_id/file digest does not derive from the saved file bytes");
+        continue;
+      }
+      r.ok("evidence.external_identity", subject, "ext_id derives from file SHA-256");
+      state.trusted = true;
+      const assoc = ext.target_association;
+      if (assoc.status === "declared" && !builds.has(assoc.build_id)) r.fail("evidence.target_binding", subject, `external evidence declares unknown build ${assoc.build_id}`);
+      if (ext.acquisition.provenance_status !== "known") r.unv("evidence.provenance", subject, `external provenance is ${ext.acquisition.provenance_status}; supported claim strength is limited`, { severity: "warning" });
+      continue;
+    }
+    if (!canonicalKind) {
+      state.trusted = true; // diagnostics are preserved but never support assertions
+      continue;
+    }
+    // Canonical evidence: recompute classification, identities and bindings from the saved bytes.
+    if (live.kind_hint !== entry.kind) {
+      r.fail("evidence.kind", subject, `index labels ${entry.file} as ${entry.kind} but its saved content classifies as ${live.kind_hint ?? live.content_type}${live.reasons.length ? ` (${live.reasons.join(", ")})` : ""}`);
+      continue;
+    }
+    r.ok("evidence.kind", subject, "label matches saved content");
+    if (live.id_authentication.status === "failed") {
+      r.fail("evidence.record_id", subject, `evidence_id does not match record content: ${live.id_authentication.reason}`);
+      continue;
+    }
+    if (live.id_authentication.status === "unverified") {
+      r.unv("evidence.record_id", subject, `evidence_id authentication skipped: ${live.id_authentication.reason}${live.parse === "header-only" ? `; raise --max-parse-bytes above ${live.bytes} (and Node heap) or cite smaller views` : ""}`, { reason: live.id_authentication.reason });
+    } else r.ok("evidence.record_id", subject, "semantic evidence_id recomputed for every record");
+    const sameRecords =
+      !live.records_truncated &&
+      live.records.length === entry.records.length &&
+      live.records.every((rec, i) => {
+        const other = entry.records[i];
+        return other && rec.evidence_id === other.evidence_id && rec.pointer === other.pointer && rec.operation === other.operation && rec.confidence === other.confidence && rec.authority === other.authority && JSON.stringify(rec.binding_digests) === JSON.stringify(other.binding_digests) && rec.parent_evidence_id === other.parent_evidence_id;
+      });
+    if (!live.records_truncated && !sameRecords) {
+      r.fail("evidence.records", subject, "index record summaries differ from the saved records (labels are not identity)");
+      continue;
+    }
+    if (live.records_truncated) r.unv("evidence.records", subject, "bundle exceeds the indexed record limit; only a prefix is verifiable", { severity: "warning" });
+    const liveDigests = [...live.binding.digests].sort();
+    const indexDigests = [...entry.target.binding_digests].sort();
+    if (JSON.stringify(liveDigests) !== JSON.stringify(indexDigests) || live.binding.source !== entry.target.binding_source) {
+      r.fail("evidence.target_binding", subject, "index target digests differ from the saved record's intrinsic target digests");
+      continue;
+    }
+    if (liveDigests.length > 0) {
+      const match = matchBuild(inv.builds, liveDigests);
+      const expected = match ? match.build_id : null;
+      if ((entry.target.build_id !== null && entry.target.build_id !== expected) || (entry.target.association === "intrinsic" && expected === null)) {
+        r.fail("evidence.build_label", subject, `index binds this record to ${entry.target.build_id ?? "no build"} but its own target digest identifies ${expected ?? "no investigation build"}`);
+        continue;
+      }
+      if (expected) r.ok("evidence.target_binding", subject, `record's own target digest equals ${expected}`);
+      else r.unv("evidence.target_binding", subject, "record's target digest matches no investigation build yet", { severity: "warning", reason: "no_matching_build" });
+    } else if (entry.target.association === "declared" && entry.target.build_id && builds.has(entry.target.build_id)) {
+      r.unv("evidence.target_binding", subject, `record carries no target digest; bound to ${entry.target.build_id} only by analyst declaration`, { severity: "warning", reason: "declared_binding_only" });
+    } else {
+      r.unv("evidence.target_binding", subject, "record carries no target digest and no valid declared build", { severity: "warning", reason: "unbound_record" });
+    }
+    if (live.binding.identity_state === "unknown") r.unv("evidence.identity_state", subject, "producer reports executable identity state unknown", { severity: "warning" });
+    state.trusted = true;
+  }
+
+  // orphans and staged files
+  for (const dir of EVIDENCE_DIRS) {
+    for (const file of await walkFiles(ws.abs, dir)) {
+      if (file.symlink) r.fail("evidence.path", file.rel, "symbolic link inside evidence");
+      else if (!entryByFile.has(file.rel)) r.unv("evidence.orphan", file.rel, "published file has no index entry and is not citable", { severity: "warning" });
+    }
+  }
+  for (const file of await walkFiles(ws.abs, "evidence/.staging")) {
+    r.unv("evidence.staged", file.rel, "unpublished staged output present (possible interrupted run)", { severity: "warning" });
+  }
+  for (const entry of idx.entries) {
+    if (entry.invocation.stderr_file) {
+      const target = entryByFile.get(entry.invocation.stderr_file);
+      if (!target || target.sha256 !== entry.invocation.stderr_sha256) r.fail("evidence.stderr", entry.entry_id, "stderr companion is not an indexed file with the recorded digest");
+    }
+  }
+
+  // ---- reference machinery ------------------------------------------------------------------
+  const pointerRequests = new Map();
+  const collect = (doc) => {
+    forEachRef(doc, (ref) => {
+      if (ref.kind !== "canonical") return;
+      const st = info.get(ref.file);
+      if (!st?.abs || !st.live || !st.trusted || !st.live.records) return;
+      const rec = st.live.records.find((x) => x.evidence_id === ref.evidence_id);
+      if (!rec) return;
+      const request = pointerRequests.get(st.abs) ?? { bytes: st.entry.bytes, pointers: new Set() };
+      for (const selector of ref.selectors ?? []) request.pointers.add(`${rec.pointer}${selector.pointer}`);
+      pointerRequests.set(st.abs, request);
+    });
+  };
+  collect(inventory);
+  collect(claimsDoc);
+  const store = new PointerStore({ maxParseBytes });
+  await store.prepare(pointerRequests);
+  const externalFacts = new ExternalFacts({ maxParseBytes });
+
+  /** Evaluate one evidence reference. allowedBuilds: Set of build ids, or null to skip binding. */
+  const evalRef = async (ref, subject, { allowedBuilds, assertion }) => {
+    const out = { usable: false, rank: 0, authority: null, external: null, selectors: [], kind: ref.kind, summary: null, entry: null, provider: null };
+    const st = info.get(ref.file);
+    const entry = st?.entry;
+    if (!entry) {
+      r.fail("ref.resolve", subject, `${ref.file} is not in the evidence index`);
+      return out;
+    }
+    out.entry = entry;
+    if (entry.sha256 !== ref.sha256) {
+      r.fail("ref.digest", subject, `reference digest ${ref.sha256.slice(0, 12)}… differs from the indexed file ${entry.sha256.slice(0, 12)}…`);
+      return out;
+    }
+    if (!st.trusted) {
+      r.fail("ref.entry_untrusted", subject, `${ref.file} failed integrity checks; it cannot be cited`);
+      return out;
+    }
+    if (ref.kind === "canonical") {
+      if (!CANONICAL_KINDS.has(entry.kind)) {
+        if (assertion) r.fail("ref.entry_kind", subject, `${entry.kind} evidence cannot support observed/derived/inferred claims`);
+        else r.ok("ref.entry_kind", subject, `${entry.kind} cited as limitation/unavailability record`);
+        return out;
+      }
+      const rec = st.live.records.find((x) => x.evidence_id === ref.evidence_id);
+      if (!rec) {
+        if (st.live.records_truncated) {
+          out.unverified = true;
+          r.unv("ref.resolve", subject, `${ref.evidence_id.slice(0, 15)}… is outside the indexed record prefix of ${ref.file}; the unindexed suffix cannot be checked`, { reason: "record_beyond_index_limit" });
+        } else r.fail("ref.resolve", subject, `${ref.evidence_id.slice(0, 15)}… is not a record in ${ref.file}`);
+        return out;
+      }
+      out.summary = rec;
+      const providerLookup = await store.lookup(st.abs, entry.bytes, `${rec.pointer}/provider`);
+      if (providerLookup.kind === "found") out.provider = providerLookup.value;
+      out.rank = RANK[rec.confidence] ?? 0;
+      out.authority = rec.authority;
+      out.usable = true;
+      if (allowedBuilds) {
+        const digests = rec.binding_digests;
+        if (digests.length > 0) {
+          const match = matchBuild(inv.builds, digests);
+          if (match && allowedBuilds.has(match.build_id)) r.ok("ref.target", subject, `record target equals ${match.build_id}`);
+          else {
+            r.fail("ref.cross_target", subject, `record's own target digest ${digests[0].slice(0, 12)}… ${match ? `belongs to ${match.build_id}` : "matches no investigation build"}; allowed: ${[...allowedBuilds].join(", ")}`);
+            out.usable = false;
+            return out;
+          }
+        } else if (entry.target.association === "declared" && allowedBuilds.has(entry.target.build_id)) {
+          r.unv("ref.target", subject, `record has no intrinsic target digest; bound to ${entry.target.build_id} by declaration only`, { severity: "warning", reason: "declared_binding_only" });
+        } else {
+          r.fail("ref.cross_target", subject, `record has no intrinsic target digest and no declared binding to ${[...allowedBuilds].join(", ")}`);
+          out.usable = false;
+          return out;
+        }
+      }
+      for (const [i, selector] of (ref.selectors ?? []).entries()) {
+        const sid = `${subject}/selector[${i}]`;
+        const lookup = await store.lookup(st.abs, entry.bytes, `${rec.pointer}${selector.pointer}`);
+        const result = judgePointer(selector, lookup);
+        r.add("ref.selector", result.status, sid, `${selector.role} ${selector.pointer || "(root)"}: ${result.detail ?? result.reason ?? ""}`.trim(), { reason: result.reason });
+        out.selectors.push({ selector, result });
+      }
+      return out;
+    }
+    // external
+    if (entry.kind !== "external" || entry.external?.ext_id !== ref.ext_id) {
+      r.fail("ref.resolve", subject, `${ref.ext_id.slice(0, 16)}… is not the external evidence in ${ref.file}`);
+      return out;
+    }
+    const ext = entry.external;
+    out.external = ext;
+    out.usable = true;
+    out.rank = ext.acquisition.provenance_status === "known" ? 3 : ext.acquisition.provenance_status === "partial" ? 2 : 1;
+    if (allowedBuilds) {
+      const a = ext.target_association;
+      if (a.status === "declared" && !allowedBuilds.has(a.build_id)) {
+        r.fail("ref.cross_target", subject, `external evidence is declared for ${a.build_id}; allowed: ${[...allowedBuilds].join(", ")}`);
+        out.usable = false;
+        return out;
+      }
+      if (a.status !== "declared") r.unv("ref.target", subject, `external evidence target association is ${a.status}`, { severity: "warning", reason: "external_target_unbound" });
+      else r.unv("ref.target", subject, `external evidence bound to ${a.build_id} by declaration only`, { severity: "warning", reason: "declared_binding_only" });
+    }
+    for (const [i, selector] of (ref.selectors ?? []).entries()) {
+      const sid = `${subject}/selector[${i}]`;
+      const result = await judgeExternal(selector, st.abs, entry, externalFacts);
+      r.add("ref.selector", result.status, sid, `${selector.type}: ${result.detail ?? result.reason ?? ""}`.trim(), { reason: result.reason });
+      out.selectors.push({ selector, result });
+    }
+    return out;
+  };
+
+  // ---- inventory ---------------------------------------------------------------------------------
+  if (inventory) {
+    const seenBuilds = new Set();
+    for (const artifact of inventory.artifacts) {
+      const subject = `inventory:${artifact.build_id}`;
+      if (!builds.has(artifact.build_id)) r.fail("inventory.build", subject, `unknown build ${artifact.build_id}`);
+      if (seenBuilds.has(artifact.build_id)) r.fail("inventory.build", subject, "build inventoried twice");
+      seenBuilds.add(artifact.build_id);
+      const allowed = new Set([artifact.build_id]);
+      const refs = [
+        ...artifact.evidence.map((ref, i) => [ref, `${subject}/evidence[${i}]`]),
+        ...artifact.components.flatMap((c, ci) => c.evidence.map((ref, i) => [ref, `${subject}/component[${ci}]/evidence[${i}]`])),
+        ...artifact.capabilities.flatMap((c, ci) => c.evidence.map((ref, i) => [ref, `${subject}/capability[${ci}]/evidence[${i}]`])),
+      ];
+      for (const [ref, sub] of refs) await evalRef(ref, sub, { allowedBuilds: allowed, assertion: true });
+      for (const component of artifact.components) {
+        if (component.sha256 === null && component.path === null) r.unv("inventory.component", `${subject}:${component.component_id}`, "component has neither path nor digest", { severity: "warning" });
+      }
+    }
+    if (closure && inv.builds.some((b) => !seenBuilds.has(b.build_id))) {
+      r.fail("inventory.coverage", "inventory", `builds not inventoried: ${inv.builds.filter((b) => !seenBuilds.has(b.build_id)).map((b) => b.build_id).join(", ")}`, { modes: CLOSURE });
+    }
+    if (D.index.sha256 && inventory.inputs.evidence_index && inventory.inputs.evidence_index.sha256 !== D.index.sha256) {
+      r.unv("inventory.inputs", "inventory", "inventory was derived from an older evidence index; its references are still validated against the current index", { severity: "warning", reason: "inputs_stale" });
+    }
+  } else if (closure) r.fail("inventory.missing", "inventory.json", "closure needs inventory.json", { modes: CLOSURE });
+
+  // ---- claims --------------------------------------------------------------------------------------------
+  const claimMap = new Map();
+  if (claimsDoc) {
+    for (const claim of claimsDoc.claims) {
+      if (claimMap.has(claim.claim_id)) r.fail("claim.unique", claim.claim_id, "duplicate claim_id");
+      claimMap.set(claim.claim_id, claim);
+    }
+    if (claimsDoc.inputs.evidence_index.sha256 !== D.index.sha256) r.unv("claims.inputs", "claims", "claims were written against an older evidence index; references are validated against the current index", { severity: "warning", reason: "inputs_stale" });
+    if (claimsDoc.inputs.inventory && D.inventory.sha256 && claimsDoc.inputs.inventory.sha256 !== D.inventory.sha256) r.unv("claims.inputs", "claims", "claims were written against an older inventory", { severity: "warning", reason: "inputs_stale" });
+    for (const claim of claimsDoc.claims) await checkClaim(claim);
+    // derivation graph: cycles and weaker inputs
+    const visiting = new Set();
+    const done = new Set();
+    const visit = (id) => {
+      if (done.has(id)) return false;
+      if (visiting.has(id)) return true;
+      visiting.add(id);
+      const claim = claimMap.get(id);
+      let cyclic = false;
+      for (const input of claim?.derivation?.input_claim_ids ?? []) if (claimMap.has(input) && visit(input)) cyclic = true;
+      visiting.delete(id);
+      done.add(id);
+      return cyclic;
+    };
+    for (const id of claimMap.keys()) if (visit(id)) r.fail("claim.derivation_cycle", id, "derivation inputs form a cycle");
+    // question <-> claim links
+    for (const q of inv.questions) {
+      for (const cid of q.claim_ids) {
+        const claim = claimMap.get(cid);
+        if (!claim) r.fail("question.claim_links", q.question_id, `unknown claim ${cid}`);
+        else if (!claim.question_ids.includes(q.question_id)) r.fail("question.claim_links", q.question_id, `claim ${cid} does not list this question`);
+      }
+      if ((q.status === "answered" || q.status === "partial") && !q.claim_ids.some((id) => claimMap.has(id))) r.fail("question.claim_links", q.question_id, `${q.status} question has no supporting claim`);
+      if (q.status === "answered" && !q.claim_ids.some((id) => ["observed", "derived"].includes(claimMap.get(id)?.state))) r.fail("question.claim_links", q.question_id, "answered question needs at least one observed or derived claim; inferred-only support is partial");
+    }
+  } else if (closure && inv.questions.some((q) => q.status === "answered" || q.status === "partial")) {
+    r.fail("claims.missing", "claims.json", "closure needs claims.json for answered/partial questions", { modes: CLOSURE });
+  }
+
+  async function checkClaim(claim) {
+    const subject = claim.claim_id;
+    const asserting = ASSERTING.has(claim.state);
+    const allowed = new Set([claim.build_id, ...claim.comparison_build_ids]);
+    for (const b of allowed) if (!builds.has(b)) r.fail("claim.build", subject, `unknown build ${b}`);
+    for (const q of claim.question_ids) if (!questions.has(q)) r.fail("claim.question", subject, `unknown question ${q}`);
+    for (const other of claim.contradicts) if (!claimMap.has(other)) r.fail("claim.contradicts", subject, `contradicts unknown claim ${other}`);
+
+    // state-specific structure
+    const structure = [];
+    if ((claim.state === "derived") !== (claim.derivation !== null)) structure.push("derivation must be present exactly for derived claims");
+    if ((claim.state === "inferred") !== (claim.inference !== null)) structure.push("inference must be present exactly for inferred claims");
+    if ((claim.state === "unavailable") !== (claim.unavailable_reason !== null && claim.unavailable_reason !== "")) structure.push("unavailable_reason must be present exactly for unavailable claims");
+    if ((claim.basis === "user-statement") !== (claim.user_statement !== null)) structure.push("user_statement must be present exactly for user-statement basis");
+    if (claim.basis === "user-statement" && claim.state === "observed") structure.push("a user statement is not an observation of the target");
+    if (claim.state === "derived" && claim.derivation && claim.derivation.input_claim_ids.length + claim.derivation.input_evidence.length === 0) structure.push("derived claims need explicit inputs");
+    if (claim.state === "unknown" && claim.coverage.status === "complete") structure.push("an unknown claim cannot have complete coverage");
+    if (claim.state === "unavailable" && !["unavailable", "unknown"].includes(claim.coverage.status)) structure.push("unavailable claims need coverage unavailable or unknown");
+    if (asserting && claim.evidence.length === 0 && claim.basis !== "user-statement") structure.push("asserted claims need evidence references");
+    if (structure.length) for (const s of structure) r.fail("claim.structure", subject, s);
+    else r.ok("claim.structure", subject, "state/basis fields consistent");
+
+    // evidence references
+    const evaluated = [];
+    for (const [i, ref] of claim.evidence.entries()) evaluated.push(await evalRef(ref, `${subject}/evidence[${i}]`, { allowedBuilds: allowed, assertion: asserting }));
+    const usable = evaluated.filter((e) => e.usable);
+
+    // locations
+    for (const [li, location] of claim.locations.entries()) await checkLocation(claim, location, `${subject}/location[${li}]`, allowed, asserting);
+
+    // coverage
+    const coverageEvaluated = [];
+    for (const [i, ref] of claim.coverage.evidence.entries()) coverageEvaluated.push(await evalRef(ref, `${subject}/coverage[${i}]`, { allowedBuilds: allowed, assertion: asserting }));
+    const coverageSelectors = coverageEvaluated.flatMap((e) => e.selectors).filter((s) => s.selector.role === "coverage" && s.selector.expect && ("equals" in s.selector.expect || "sha256" in s.selector.expect));
+    const absence = claim.polarity === "absence" && asserting;
+    if (absence || (asserting && claim.coverage.status === "complete")) {
+      const problems = [];
+      if (claim.coverage.status !== "complete") problems.push(`absence needs complete coverage, found ${claim.coverage.status}; record the outcome as an unknown claim instead`);
+      if (!claim.coverage.scope.trim()) problems.push("coverage scope is empty");
+      if (coverageSelectors.length === 0) problems.push("no coverage-role selector asserts the saved completeness value (expect.equals or expect.sha256; expect.exists only proves the pointer resolves)");
+      else if (!coverageSelectors.some((s) => s.result.status === "verified")) {
+        const unverifiedOnly = coverageSelectors.every((s) => s.result.status === "unverified");
+        if (unverifiedOnly) r.unv("claim.absence_coverage", subject, "coverage selectors could not be verified", { reason: coverageSelectors[0].result.reason });
+        else problems.push("coverage selectors do not verify against saved evidence");
+      }
+      if (problems.length) for (const p of problems) r.fail("claim.absence_coverage", subject, p);
+      else if (coverageSelectors.some((s) => s.result.status === "verified")) r.ok("claim.absence_coverage", subject, "coverage selectors verified");
+    }
+    if (claim.polarity === "absence" && !asserting && claim.state === "inferred") r.fail("claim.absence_coverage", subject, "inferred absence is not allowed without complete coverage");
+
+    if (!asserting) return;
+    // derivation inputs set the ceiling of a derived claim; unrelated stronger evidence cannot promote it
+    let derivationCeiling = null;
+    if (claim.derivation) {
+      const cited = new Set(claim.evidence.map(refKey));
+      const ranks = [];
+      let unverifiedInput = false;
+      for (const input of claim.derivation.input_claim_ids) {
+        const source = claimMap.get(input);
+        if (!source) r.fail("claim.derivation", subject, `derivation input ${input} does not exist`);
+        else if (!ASSERTING.has(source.state)) r.fail("claim.derivation", subject, `derivation input ${input} is ${source.state}`);
+        else ranks.push(RANK[source.state]);
+      }
+      for (const [i, ref] of claim.derivation.input_evidence.entries()) {
+        const input = await evalRef(ref, `${subject}/derivation[${i}]`, { allowedBuilds: allowed, assertion: true });
+        ranks.push(input.usable ? input.rank : 0);
+        unverifiedInput ||= input.unverified === true;
+        if (!cited.has(refKey(ref))) r.fail("claim.derivation", subject, `derivation input_evidence[${i}] must also be listed in claim.evidence`);
+      }
+      derivationCeiling = ranks.length ? Math.min(...ranks) : 0;
+      if (unverifiedInput && derivationCeiling === 0) r.unv("claim.derivation", subject, "an input outside the indexed record prefix cannot establish the derivation ceiling", { reason: "record_beyond_index_limit" });
+      else if (RANK[claim.state] > derivationCeiling) r.fail("claim.derivation", subject, `derived claim is stronger than its weakest input (rank ${derivationCeiling}); inputs and cited evidence must support the state`);
+      else r.ok("claim.derivation", subject, "inputs support the claim state");
+    }
+    // strength: never strengthen producer inference or weak provenance
+    if (claim.basis !== "user-statement" && derivationCeiling === null) {
+      const best = Math.max(0, ...usable.map((e) => e.rank));
+      if (usable.length > 0 && RANK[claim.state] > best) r.fail("claim.state_exceeds_evidence", subject, `claim state ${claim.state} is stronger than the strongest cited evidence (rank ${best}: ${best === 3 ? "observed" : best === 2 ? "derived" : "inferred"}); downgrade the state or cite stronger evidence`);
+      else if (usable.length > 0) r.ok("claim.state_exceeds_evidence", subject, "state not stronger than evidence");
+    }
+    // basis consistency
+    const canonicalUsable = usable.filter((e) => e.kind === "canonical");
+    const externalUsable = usable.filter((e) => e.kind === "external");
+    let basisProblem = null;
+    switch (claim.basis) {
+      case "static":
+        if (!canonicalUsable.some((e) => e.authority === "shipped-artifact")) basisProblem = "static basis needs a cited canonical record with authority shipped-artifact";
+        break;
+      case "runtime":
+        if (!canonicalUsable.some((e) => e.authority === "controlled-replay") && !externalUsable.some((e) => e.external.acquisition.scenario_id)) basisProblem = "runtime basis needs a controlled-replay record or external evidence tied to a scenario_id";
+        break;
+      case "recorded":
+        if (!canonicalUsable.some((e) => ["historical-reference", "external-service"].includes(e.authority)) && externalUsable.length === 0) basisProblem = "recorded basis needs a recording-derived record (historical-reference/external-service) or external original";
+        break;
+      case "external":
+        if (claim.evidence.length === 0 || claim.evidence.some((ref) => ref.kind !== "external")) basisProblem = "external basis needs evidence made only of ext_ references";
+        break;
+      default:
+        break;
+    }
+    if (basisProblem) {
+      if (["static", "runtime", "recorded"].includes(claim.basis) && evaluated.some((e) => e.kind === "canonical" && e.unverified)) {
+        r.unv("claim.basis", subject, `${basisProblem}; a canonical reference outside the indexed record prefix remains unchecked`, { reason: "record_beyond_index_limit" });
+      } else r.fail("claim.basis", subject, basisProblem);
+    } else if (claim.basis !== "user-statement") r.ok("claim.basis", subject, `${claim.basis} basis consistent`);
+    // external provenance ceiling
+    for (const e of externalUsable) {
+      const cap = e.external.acquisition.provenance_status === "known" ? 3 : e.external.acquisition.provenance_status === "partial" ? 2 : 1;
+      if (usable.every((u) => u.kind === "external") && RANK[claim.state] > cap) r.fail("claim.provenance_ceiling", subject, `external provenance is ${e.external.acquisition.provenance_status}; claim state cannot exceed ${cap === 2 ? "derived" : "inferred"}`);
+    }
+    // derivation: self-reference only; ranks and inputs were evaluated above
+    if (claim.derivation && claim.derivation.input_claim_ids.includes(claim.claim_id)) r.fail("claim.derivation", subject, "claim derives from itself");
+  }
+
+  async function checkLocation(claim, location, subject, allowed, asserting) {
+    const evaluated = [];
+    for (const [i, ref] of location.evidence.entries()) evaluated.push(await evalRef(ref, `${subject}/evidence[${i}]`, { allowedBuilds: allowed, assertion: asserting }));
+    let claimed;
+    switch (location.kind) {
+      case "artifact-member": claimed = location.member_path; break;
+      case "source-range": claimed = location.path; break;
+      case "native-procedure": claimed = location.address; break;
+      case "resource-node": claimed = location.node_id; break;
+      default: claimed = location.event_id;
+    }
+    if (location.kind === "source-range" && location.end_line < location.start_line) r.fail("location.range", subject, "end_line precedes start_line");
+    if (location.kind === "native-procedure") {
+      const digests = evaluated.filter((e) => e.summary).flatMap((e) => e.summary.binding_digests);
+      if (digests.length > 0 && digests.some((d) => d !== location.target_sha256)) r.fail("location.target", subject, "location target_sha256 differs from the cited record's own target digest");
+      else if (digests.length > 0) r.ok("location.target", subject, "target digest matches cited evidence");
+      else r.unv("location.target", subject, "cited evidence carries no target digest to compare with target_sha256", { severity: "warning" });
+      const owner = matchBuild(inv.builds, [location.target_sha256]);
+      if (!owner || !allowed.has(owner.build_id)) r.fail("location.target", subject, "location target_sha256 is not an allowed build identity for this claim");
+      if (location.file_offset !== undefined && !location.mapping) r.fail("location.mapping", subject, "file offsets need an observed mapping");
+    }
+    let tied = false;
+    let mismatch = null;
+    for (const e of evaluated) {
+      for (const { selector, result } of e.selectors) {
+        if (result.status !== "verified") continue;
+        if (selector.type === "json-pointer" && selector.expect && "equals" in selector.expect) {
+          if (JSON.stringify(selector.expect.equals) === JSON.stringify(claimed)) tied = true;
+          else mismatch = selector.expect.equals;
+        }
+        if (selector.type === "event-ordinal" && location.kind === "runtime-event" && selector.ordinal === claimed) tied = true;
+        if (selector.type === "line-range" && location.kind === "source-range" && selector.start === location.start_line && selector.end === location.end_line) tied = true;
+      }
+    }
+    if (tied) r.ok("location.tie", subject, "claimed location value equals a verified selector value");
+    else if (evaluated.every((e) => !e.usable)) r.unv("location.tie", subject, "location evidence is not usable", { reason: "evidence_unusable" });
+    else r.unv("location.tie", subject, mismatch !== null ? "verified selectors assert a different value than the claimed location" : "no verified selector with expect.equals ties the claimed location value to saved evidence", { reason: "selector_missing_or_untied" });
+    if (location.kind === "source-range") {
+      let bounded = false;
+      for (const e of evaluated) {
+        for (const { selector, result } of e.selectors) {
+          if (result.status !== "verified") continue;
+          if (selector.type === "line-range" && selector.start === location.start_line && selector.end === location.end_line) bounded = true;
+          if (selector.type === "json-pointer" && selector.role === "line-count" && selector.expect && Number.isInteger(selector.expect.equals) && selector.expect.equals >= location.end_line) bounded = true;
+        }
+      }
+      if (bounded) r.ok("location.range", subject, "line range is bounded by a verified line-range selector or line-count");
+      else if (evaluated.every((e) => !e.usable)) r.unv("location.range", subject, "location evidence is not usable", { reason: "evidence_unusable" });
+      else r.unv("location.range", subject, "no verified line-range selector or role=line-count selector bounds end_line against the saved source", { reason: "range_not_bounded_by_evidence" });
+    }
+    if (location.kind === "native-procedure") {
+      for (const e of evaluated.filter((x) => x.entry)) {
+        const provider = e.provider;
+        if (!provider) r.unv("location.provider", subject, "cited evidence does not report a single provider to compare with location.provider", { reason: "provider_not_reported" });
+        else if (provider.id === location.provider.id && (provider.version ?? null) === (location.provider.version ?? null)) r.ok("location.provider", subject, "provider id/version match the saved record");
+        else r.fail("location.provider", subject, `location provider ${location.provider.id}@${location.provider.version ?? "null"} differs from saved record ${provider.id}@${provider.version ?? "null"}`);
+      }
+      if (location.address_space === "provider-reported") r.ok("location.address_space", subject, "address is stated as provider-reported; no mapping is claimed");
+      else {
+        const asserted = evaluated.some((e) => e.selectors.some(({ selector, result }) => result.status === "verified" && selector.role === "identity" && selector.expect && selector.expect.equals === location.address_space));
+        if (asserted) r.ok("location.address_space", subject, "address space equals a verified identity selector");
+        else r.unv("location.address_space", subject, `address_space ${location.address_space} is not reported by saved evidence; use provider-reported or cite a role=identity selector that exposes it`, { reason: "address_space_not_in_evidence" });
+      }
+      if (location.file_offset !== undefined) {
+        const selectors = evaluated.flatMap((e) => e.selectors).filter((s) => s.result.status === "verified" && s.selector.type === "json-pointer" && s.selector.expect);
+        const offsetFound = selectors.some((s) => s.selector.expect.equals === location.file_offset);
+        const mappingFound = selectors.some((s) => s.selector.role === "identity" && s.selector.expect.equals === location.mapping);
+        if (offsetFound && mappingFound) r.ok("location.mapping", subject, "file offset and mapping are explicitly tied to saved values; semantic correspondence still requires review");
+        else r.unv("location.mapping", subject, "file offset and mapping need verified value/identity selectors; a mapping description alone is not evidence", { reason: "mapping_not_in_evidence" });
+      }
+    }
+  }
+
+  // ---- specs ------------------------------------------------------------------------------------------------
+  const specFiles = (await walkFiles(ws.abs, "specs")).filter((f) => f.rel.endsWith(".md") || f.symlink);
+  const liveSpecs = [];
+  for (const file of specFiles) {
+    if (file.symlink) {
+      r.fail("spec.path", file.rel, "symbolic link inside specs");
+      continue;
+    }
+    liveSpecs.push(file.rel);
+  }
+  const specDigests = new Map();
+  let indexText = null;
+  for (const rel of liveSpecs) {
+    const resolved = await resolveInWorkspace(ws.abs, rel);
+    const buffer = await fsp.readFile(resolved.abs);
+    specDigests.set(rel, sha256Buffer(buffer));
+    if (rel === "specs/index.md") indexText = buffer.toString("utf8");
+    const isFeatureFile = /^specs\/[^/]+\/(requirements|reference-design)\.md$/.test(rel);
+    if (isFeatureFile) checkSpec(rel, buffer.toString("utf8"));
+  }
+  const features = new Set(liveSpecs.map((rel) => rel.split("/")[1]).filter((name) => name && name !== "index.md" && liveSpecs.some((x) => x.startsWith(`specs/${name}/`))));
+  if (closure && features.size > 0) {
+    if (!liveSpecs.includes("specs/index.md")) r.fail("spec.layout", "specs/index.md", "specs/index.md is required", { modes: CLOSURE });
+    for (const feature of features) {
+      for (const required of ["requirements.md", "reference-design.md"]) {
+        if (!liveSpecs.includes(`specs/${feature}/${required}`)) r.fail("spec.layout", `specs/${feature}/${required}`, "required spec file is missing", { modes: CLOSURE });
+      }
+    }
+  }
+  if (indexText !== null && features.size > 0) {
+    // Warning-only: resolve inline links against specs/ and expect each feature's requirements and
+    // reference design (a link to the feature directory covers both). Fenced examples are ignored.
+    const reachable = new Set();
+    const directories = new Set();
+    for (const target of markdownLinkTargets(parseFrontMatter(indexText).body)) {
+      if (target === "" || target.startsWith("#") || target.startsWith("//") || /^[a-z][a-z0-9+.-]*:/i.test(target)) continue;
+      let decoded = target.replace(/[?#].*$/, "");
+      try {
+        decoded = decodeURIComponent(decoded);
+      } catch {
+        /* keep the raw target; it will fail to resolve below */
+      }
+      const normalized = path.posix.normalize(path.posix.join("specs", decoded));
+      if (normalized !== "specs" && !normalized.startsWith("specs/")) continue;
+      const trimmed = normalized.replace(/\/+$/, "");
+      const resolved = await resolveInWorkspace(ws.abs, trimmed).catch(() => null);
+      if (!resolved?.exists) {
+        r.unv("spec.index_links", `specs/index.md:${target}`, `index link ${target} does not resolve to a file or directory under specs/`, { severity: "warning", reason: "index_link_broken" });
+        continue;
+      }
+      if (resolved.stat.isDirectory()) directories.add(trimmed);
+      else reachable.add(trimmed);
+    }
+    for (const feature of features) {
+      for (const required of ["requirements.md", "reference-design.md"]) {
+        const file = `specs/${feature}/${required}`;
+        if (!liveSpecs.includes(file)) continue;
+        if (reachable.has(file) || directories.has(`specs/${feature}`)) r.ok("spec.index_links", file, "index links to this spec");
+        else r.unv("spec.index_links", file, `specs/index.md has no link to ${file} (link the file or its feature directory)`, { severity: "warning", reason: "index_link_missing" });
+      }
+    }
+  }
+
+  function parseFrontMatter(text) {
+    if (!text.startsWith("---\n") && !text.startsWith("---\r\n")) return { data: null, body: text };
+    const end = text.search(/\n---\s*(\r?\n|$)/);
+    if (end === -1) return { data: null, body: text };
+    const block = text.slice(4, end);
+    const body = text.slice(text.indexOf("\n", end + 1) + 1);
+    const data = {};
+    let currentKey = null;
+    for (const line of block.split(/\r?\n/)) {
+      let m = /^([A-Za-z_][A-Za-z0-9_]*):\s*(.*)$/.exec(line);
+      if (m) {
+        currentKey = m[1];
+        const value = m[2].trim();
+        if (value === "") data[currentKey] = [];
+        else if (value.startsWith("[") && value.endsWith("]")) data[currentKey] = value.slice(1, -1).split(",").map((s) => s.trim().replace(/^["']|["']$/g, "")).filter(Boolean);
+        else data[currentKey] = value.replace(/^["']|["']$/g, "");
+        continue;
+      }
+      m = /^\s+-\s+(.*)$/.exec(line);
+      if (m && currentKey && Array.isArray(data[currentKey])) data[currentKey].push(m[1].trim().replace(/^["']|["']$/g, ""));
+    }
+    return { data, body };
+  }
+
+  function checkSpec(rel, text) {
+    const { data, body } = parseFrontMatter(text);
+    if (!data) {
+      r.fail("spec.front_matter", rel, "missing YAML front matter");
+    } else {
+      for (const key of ["investigation_id", "feature", "reference_build_ids", "claims_digest"]) if (data[key] === undefined || data[key] === "") r.fail("spec.front_matter", rel, `front matter key ${key} is missing`);
+      if (data.investigation_id && data.investigation_id !== inv.investigation_id) r.fail("spec.front_matter", rel, `investigation_id ${data.investigation_id} does not match`);
+      if (data.feature && data.feature !== rel.split("/")[1]) r.fail("spec.front_matter", rel, `feature ${data.feature} does not match directory ${rel.split("/")[1]}`);
+      const refBuilds = Array.isArray(data.reference_build_ids) ? data.reference_build_ids : [];
+      for (const b of refBuilds) if (!builds.has(b)) r.fail("spec.front_matter", rel, `unknown reference build ${b}`);
+      if (data.claims_digest) {
+        const digest = String(data.claims_digest).replace(/^sha256:/, "");
+        if (D.claims.sha256 && digest !== D.claims.sha256) r.fail("spec.claims_digest", rel, "claims_digest differs from the current claims.json", { modes: CLOSURE, reason: "spec_stale" });
+        else if (D.claims.sha256) r.ok("spec.claims_digest", rel, "claims_digest current");
+      }
+      data.__builds = new Set(refBuilds);
+    }
+    const lines = body.split(/\r?\n/);
+    const inFenceLine = makeFenceTracker();
+    let inNarrative = false;
+    let linked = 0;
+    for (let n = 0; n < lines.length; n += 1) {
+      const line = lines[n];
+      const subject = `${rel}:${n + 1 + (text.length - body.length > 0 ? text.slice(0, text.length - body.length).split("\n").length - 1 : 0)}`;
+      if (inFenceLine(line)) continue;
+      const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+      if (heading) {
+        // Only the template's exact level-2 section is exempt, and it ends at the next heading of any level.
+        inNarrative = heading[1].length === 2 && heading[2].replace(/\s+#+\s*$/, "").trim() === NARRATIVE_HEADING;
+        continue;
+      }
+      if (inNarrative) continue;
+      let content = null;
+      const list = /^\s*(?:[-*+]|\d+[.)])\s+(.*)$/.exec(line);
+      if (list) content = list[1];
+      else if (/^\s*\|.*\|\s*$/.test(line)) {
+        if (/^\s*\|[\s:|-]+\|\s*$/.test(line)) {
+          continue;
+        }
+        const next = lines[n + 1] ?? "";
+        if (/^\s*\|[\s:|-]+\|\s*$/.test(next)) {
+          continue;
+        }
+        content = line;
+      }
+      if (content === null || content.trim() === "") continue;
+      const claimTokens = [...content.matchAll(/\[claims:\s*([^\]]*)\]/g)].flatMap((m) => m[1].split(",").map((s) => s.trim()).filter(Boolean));
+      const questionTokens = [...content.matchAll(/\[questions:\s*([^\]]*)\]/g)].flatMap((m) => m[1].split(",").map((s) => s.trim()).filter(Boolean));
+      if (claimTokens.length === 0 && questionTokens.length === 0) {
+        r.fail("spec.statement_link", subject, "statement has no [claims: …] or [questions: …] token");
+        continue;
+      }
+      let bad = false;
+      for (const id of claimTokens) if (!claimMap.has(id)) { r.fail("spec.claim_link", subject, `unknown claim ${id}`); bad = true; }
+      for (const id of questionTokens) if (!questions.has(id)) { r.fail("spec.question_link", subject, `unknown question ${id}`); bad = true; }
+      if (bad) continue;
+      linked += 1;
+      const plain = content.replace(/^(\*\*|__)/, "");
+      const prefix = /^(Inferred|Unknown):/.exec(plain)?.[1] ?? null;
+      const states = claimTokens.map((id) => claimMap.get(id).state);
+      let problem = null;
+      if (prefix === "Inferred") {
+        if (claimTokens.length === 0 || states.some((s) => s !== "inferred")) problem = "Inferred: statements must cite only inferred claims";
+      } else if (prefix === "Unknown") {
+        if (states.some((s) => s !== "unknown" && s !== "unavailable")) problem = "Unknown: statements may cite only unknown/unavailable claims or questions";
+      } else if (claimTokens.length === 0) problem = "unprefixed statements must cite claims";
+      else if (states.some((s) => s !== "observed" && s !== "derived")) problem = "unprefixed statements may cite only observed/derived claims; prefix inferred ones with Inferred: and unknown ones with Unknown:";
+      if (problem) r.fail("spec.state_prefix", subject, problem);
+      if (data?.__builds) {
+        for (const id of claimTokens) {
+          const claim = claimMap.get(id);
+          const claimBuilds = [claim.build_id, ...claim.comparison_build_ids];
+          if (claimBuilds.some((b) => !data.__builds.has(b))) r.fail("spec.build_scope", subject, `claim ${id} concerns build(s) outside reference_build_ids`);
+        }
+      }
+      if (!problem) r.ok("spec.state_prefix", subject, "statement linked");
+    }
+    if (linked === 0) r.fail("spec.statements", rel, "spec contains no linked statements (a statement is a list item or table body row outside code fences and the exact `## Narrative (non-factual)` section)", { modes: CLOSURE, reason: "no_linked_statements" });
+  }
+
+  // ---- review and closure ------------------------------------------------------------------------------------
+  if (review) {
+    const staleReasons = [];
+    const expectEq = (label, entry, rel, sha) => {
+      if (!entry) {
+        if (sha) staleReasons.push(`${label} exists but the review recorded none`);
+        return;
+      }
+      if (entry.path !== rel) staleReasons.push(`${label} path ${entry.path} != ${rel}`);
+      if (!sha) staleReasons.push(`${label} no longer exists`);
+      else if (entry.sha256 !== sha) staleReasons.push(`${label} changed since review`);
+    };
+    const reviewedScope = review.reviewed_inputs.scope?.sha256 ?? null;
+    const currentScope = scopeDigest(inv);
+    if (reviewedScope !== currentScope) staleReasons.push("investigation scope (objective, non-goals, question text/feature/build scope or build identities) changed since review");
+    expectEq("inventory", review.reviewed_inputs.inventory, "inventory.json", D.inventory.sha256);
+    expectEq("evidence_index", review.reviewed_inputs.evidence_index, INDEX_PATH, D.index.sha256);
+    expectEq("claims", review.reviewed_inputs.claims, "claims.json", D.claims.sha256);
+    const reviewedSpecs = new Map(review.reviewed_inputs.specs.map((s) => [s.path, s.sha256]));
+    for (const rel of liveSpecs) {
+      if (!reviewedSpecs.has(rel)) staleReasons.push(`spec ${rel} was not part of the review`);
+      else if (reviewedSpecs.get(rel) !== specDigests.get(rel)) staleReasons.push(`spec ${rel} changed since review`);
+    }
+    for (const rel of reviewedSpecs.keys()) if (!specDigests.has(rel)) staleReasons.push(`reviewed spec ${rel} no longer exists`);
+    if (staleReasons.length) r.fail("review.inputs_current", "review.json", `review is stale: ${staleReasons.slice(0, 6).join("; ")}`, { modes: CLOSURE, reason: "review_stale", details: staleReasons });
+    else r.ok("review.inputs_current", "review.json", "review digests equal current inputs");
+    const dispositions = new Map();
+    for (const d of review.dispositions) {
+      if (dispositions.has(d.question_id)) r.fail("review.dispositions", d.question_id, "duplicate disposition", { modes: CLOSURE });
+      dispositions.set(d.question_id, d);
+    }
+    for (const q of inv.questions) {
+      const d = dispositions.get(q.question_id);
+      if (!d) r.fail("review.dispositions", q.question_id, "review has no disposition for this question", { modes: CLOSURE });
+      else if (d.disposition !== q.status) r.fail("review.dispositions", q.question_id, `review disposition ${d.disposition} differs from investigation status ${q.status}`, { modes: CLOSURE });
+      else {
+        const unknownClaims = d.claim_ids.filter((cid) => !claimMap.has(cid));
+        for (const cid of unknownClaims) r.fail("review.dispositions", q.question_id, `review cites unknown claim ${cid}`, { modes: CLOSURE });
+        const same = d.claim_ids.length === q.claim_ids.length && new Set(d.claim_ids).size === d.claim_ids.length && q.claim_ids.every((cid) => d.claim_ids.includes(cid));
+        if (!same) r.fail("review.dispositions", q.question_id, "review claim_ids differ from the question's claim_ids", { modes: CLOSURE });
+        if (!d.reason || !d.reason.trim()) r.fail("review.dispositions", q.question_id, "review disposition needs a reason", { modes: CLOSURE });
+        else if (q.reason && d.reason !== q.reason) r.fail("review.dispositions", q.question_id, "review reason differs from the question's recorded reason", { modes: CLOSURE });
+        if (unknownClaims.length === 0 && same && d.reason && d.reason.trim() && (!q.reason || d.reason === q.reason)) r.ok("review.dispositions", q.question_id, d.disposition);
+      }
+    }
+    for (const id of dispositions.keys()) if (!questions.has(id)) r.fail("review.dispositions", id, "disposition for unknown question", { modes: CLOSURE });
+    for (const f of review.findings) {
+      if (f.claim_id && !claimMap.has(f.claim_id)) r.fail("review.findings", f.finding_id, `unknown claim ${f.claim_id}`);
+      if (f.status === "open" && (f.severity === "blocking" || f.severity === "major")) r.fail("review.findings", f.finding_id, `open ${f.severity} finding${f.route_to ? ` (route to ${f.route_to})` : ""}: ${f.text.slice(0, 120)}`, { modes: CLOSURE });
+      else if (f.status === "open") r.unv("review.findings", f.finding_id, `open ${f.severity} finding`, { severity: "warning" });
+    }
+    if (!["approved", "approved-with-limits"].includes(review.verdict)) r.fail("review.verdict", "review.json", `verdict ${review.verdict} does not allow closure`, { modes: CLOSURE });
+    else r.ok("review.verdict", "review.json", review.verdict);
+    if (inv.lifecycle.review_sha256 !== D.review.sha256) r.fail("review.checkpoint_binding", "investigation.json", "lifecycle.review_sha256 does not equal the current review.json digest", { modes: CLOSURE, reason: "checkpoint_unbound" });
+    else r.ok("review.checkpoint_binding", "investigation.json", "lifecycle binds the current review");
+  } else if (closure) r.fail("review.missing", "review.json", "closure needs a current review.json", { modes: CLOSURE });
+  if (closure && !["verify", "complete"].includes(inv.phase)) r.fail("investigation.phase", "investigation.json", `phase ${inv.phase} cannot close; use verify or complete`, { modes: CLOSURE });
+
+  return finish(r, base, D, { steps: stepReport });
+}
+
+function finish(r, base, D, extra) {
+  const mode = base.mode;
+  let outcome = "pass";
+  if (r.errorFailed > 0) outcome = "fail";
+  else if (mode === "closure" && r.errorUnverified > 0) outcome = "blocked";
+  else if (mode === "resume" && r.resumeBlockers.length > 0) outcome = "blocked";
+  return {
+    ...base,
+    outcome,
+    summary: {
+      verified: r.totals.verified,
+      failed: r.totals.failed,
+      unverified: r.totals.unverified,
+      error_failed: r.errorFailed,
+      error_unverified: r.errorUnverified,
+      listed_checks: r.checks.length,
+      omitted_checks: r.omitted,
+      note: "Structural validation only; it does not establish that cited evidence supports a statement.",
+    },
+    by_rule: r.counts,
+    digests: {
+      investigation: D.investigation.sha256 ?? null,
+      evidence_index: D.index.sha256 ?? null,
+      inventory: D.inventory.sha256 ?? null,
+      claims: D.claims.sha256 ?? null,
+      review: D.review.sha256 ?? null,
+    },
+    resume_blockers: r.resumeBlockers,
+    checks: r.checks,
+    ...extra,
+  };
+}