create-agdf 0.14.5 → 0.20.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-recovery.js

@@ -0,0 +1,296 @@
+import { assertRecoveryOperationsTrusted } from "./run-state-writer.js";
+import { createHash, randomUUID } from "node:crypto";
+import {
+  closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, writeFileSync, fsyncSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { transitionDecisionForRunState } from "../control-evaluation/gate-policy.js";
+import { prepareRunContentState, userGateOrder } from "../control-evaluation/run-state.js";
+import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
+import { duplicateArtefactRowTypes, parseControlState, parseRunState, scalarFields, sectionTableRows } from "./run-state-parser.js";
+import { applyRunSeals, artefactFileDigest, canonicalRunText, computeRunSeals, listedArtefactPaths, pendingArtefactPaths, runSealState } from "./run-seal.js";
+import { runPath } from "./run-state-reader.js";
+import { atomicWrite, recoveryRunContent, unapproveRecoveryApprovals, withRunLock, writeRunRecoveryLocked } from "./run-state-writer.js";
+
+const sha256 = (value) => `sha256:${createHash("sha256").update(value, "utf8").digest("hex")}`;
+const digestContent = (content) => sha256(canonicalRunText(content));
+function recoveryPreviewDigest(preview) {
+  const bound = {
+    schema_version: preview.schema_version, preview_id: preview.preview_id, run_id: preview.run_id,
+    source_revision_id: preview.source_revision_id, source_content_digest: preview.source_content_digest,
+    source_content: preview.source_content, source_artefacts: preview.source_artefacts,
+    git_history: preview.git_history, prior_approvals: preview.prior_approvals,
+    approval_provenance: preview.approval_provenance, approvals_to_invalidate: preview.approvals_to_invalidate,
+    next_gate: preview.next_gate, next_revision_id: preview.next_revision_id,
+    candidate_content: preview.candidate_content, candidate_digest: preview.candidate_digest,
+  };
+  // Version 1 journals did not bind the activity timestamp. Keep their stored digest readable;
+  // new previews bind the timestamp used by both the expected state and the atomic writer.
+  if (preview.preview_format_version === 2) {
+    bound.preview_format_version = 2;
+    bound.created_at = preview.created_at;
+  }
+  return sha256(JSON.stringify(bound));
+}
+
+const PREVIEW_CONFIRMATION = (runId, previewId, digest) => `RECOVER ${runId} ${previewId} ${digest}`;
+
+// Read-only proof of the former self-reference hashing defect. This does not accept arbitrary
+// changed seals: the complete current record must equal the validated journal's old writer result.
+export function inspectSelfReferenceRecovery(root, runId) {
+  const { path, runDir } = safeRunFiles(root, runId);
+  const content = readFileSync(path, "utf8");
+  const parsed = parseRunState(content, runId);
+  const selfPath = `.agdf/control/runs/${runId}/RUN_STATE.md`;
+  if (!parsed.valid || parsed.meta.lifecycle !== "active" || runSealState(root, content).status !== "content_changed"
+      || !listedArtefactPaths(content).includes(selfPath)) return null;
+  const directory = join(runDir, "recovery-previews");
+  if (!existsSync(directory)) return null;
+  const stat = lstatSync(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("AGDF_RUN_PATH_INVALID");
+  for (const name of readdirSync(directory).filter((value) => /^[0-9a-f-]{36}\.json$/iu.test(value))) {
+    try {
+      const { preview } = readPreview(root, runDir, runId, name.slice(0, -5));
+      if (preview.phase !== "committed" || preview.preview_format_version !== 2
+          || preview.result_digest !== digestContent(content) || preview.result_revision_id !== parsed.meta.revision_id
+          || preview.next_revision_id !== parsed.meta.revision_id) continue;
+      const currentArtefacts = artifactSnapshot(root, content).filter((entry) => entry.path !== selfPath);
+      if (JSON.stringify(currentArtefacts) !== JSON.stringify(preview.source_artefacts.filter((entry) => entry.path !== selfPath))) continue;
+      const source = parseRunState(preview.source_content, runId);
+      const restored = recoveryRunContent(root, preview.candidate_content, {
+        revision: source.meta.revision, nextRevisionId: preview.next_revision_id, updatedAt: preview.created_at,
+      });
+      const legacy = applyRunSeals(restored, computeRunSeals(root, restored, { selfReferenceDigest: preview.source_content_digest }));
+      if (legacy !== content || runSealState(root, restored).status !== "valid") continue;
+      return { source: `recovery-previews/${name}`, source_revision_id: parsed.meta.revision_id, content: restored };
+    } catch { /* A damaged checkpoint cannot prove an original. */ }
+  }
+  return null;
+}
+
+function gitHistoryCandidates(root, runId, readGitHistory) {
+  if (typeof readGitHistory !== "function") return { status: "unavailable", candidates: [] };
+  const relativePath = `.agdf/control/runs/${runId}/RUN_STATE.md`;
+  let entries;
+  try { entries = readGitHistory(root, relativePath); } catch { return { status: "unavailable", candidates: [] }; }
+  if (!Array.isArray(entries) || entries.length > 25) return { status: "unavailable", candidates: [] };
+  const candidates = [];
+  for (const entry of entries) {
+    if (!entry || entry.path !== relativePath || !/^[0-9a-f]{40,64}$/u.test(entry.commit) || typeof entry.content !== "string" || Buffer.byteLength(entry.content) > 1024 * 1024) continue;
+    const parsed = parseRunState(entry.content, runId);
+    if (!parsed.valid) continue;
+    const meta = scalarFields(entry.content).values;
+    const sealPattern = /^sha256:[0-9a-f]{64}$/u;
+    candidates.push({ commit: entry.commit, revision_id: parsed.meta.revision_id, content_digest: digestContent(entry.content),
+      seal_lines_present: sealPattern.test(meta.get("content_seal") ?? "") && sealPattern.test(meta.get("approval_seal") ?? ""), approval_provenance: "not_proven_by_git_revision" });
+  }
+  return { status: "available", candidates };
+}
+
+function safeRunFiles(root, runId) {
+  const path = runPath(root, runId);
+  const runDir = dirname(path);
+  let rootStat;
+  try { rootStat = lstatSync(root); } catch { throw new Error("AGDF_RUN_PATH_INVALID"); }
+  if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) throw new Error("AGDF_RUN_PATH_INVALID");
+  for (const target of [join(root, ".agdf"), join(root, ".agdf", "control"), join(root, ".agdf", "control", "runs"), runDir, path]) {
+    let stat;
+    try { stat = lstatSync(target); } catch { throw new Error("AGDF_RUN_PATH_INVALID"); }
+    if (stat.isSymbolicLink() || (target === path ? !stat.isFile() : !stat.isDirectory())) throw new Error("AGDF_RUN_PATH_INVALID");
+  }
+  return { path, runDir };
+}
+
+function artifactSnapshot(root, content) {
+  const paths = listedArtefactPaths(content);
+  const pending = new Set(pendingArtefactPaths(content));
+  const entries = paths.map((path) => {
+    const resolved = containedRegularFile(root, path);
+    const status = hasSymlinkComponent(root, path) ? "invalid" : resolved.status;
+    return { path, status, digest: status === "valid" ? artefactFileDigest(root, path) : status,
+      ...(status === "missing" && pending.has(path) ? { planned: true } : {}) };
+  });
+  return entries;
+}
+
+function approvalSnapshot(content) {
+  return ["Approvals", "Gate Checklist"].flatMap((section) => sectionTableRows(content, section)
+    .filter(([gate]) => userGateOrder.includes(gate))
+    .map(([gate, status = "", evidence = ""]) => ({ section, gate, status: status.replace(/^`|`$/gu, "").trim(), evidence: evidence.trim() })));
+}
+
+function deriveNextGate(root, content, path) {
+  const state = prepareRunContentState(root, content, path);
+  return transitionDecisionForRunState(state).current_gate;
+}
+
+export function inspectRunRecovery(root, runId, { inspectHistory = true, readGitHistory } = {}) {
+  const { path } = safeRunFiles(root, runId);
+  const content = readFileSync(path, "utf8");
+  const state = parseRunState(content, runId);
+  if (!state.valid) throw new Error("AGDF_RUN_STATE_INVALID");
+  if (state.meta.lifecycle !== "active") throw new Error("AGDF_RECOVERY_LIFECYCLE_UNSUPPORTED");
+  if (duplicateArtefactRowTypes(content).length) throw new Error("AGDF_ARTEFACT_ROW_DUPLICATE");
+  const seal = runSealState(root, content);
+  assertRecoveryOperationsTrusted(content);
+  if (!["unsealed", "invalid"].includes(seal.status)) throw new Error("AGDF_RUN_RECOVERY_NOT_REQUIRED");
+  const artefacts = artifactSnapshot(root, content);
+  const gitHistory = inspectHistory ? gitHistoryCandidates(root, runId, readGitHistory) : { status: "not_checked", candidates: [] };
+  return Object.freeze({
+    schema_version: "1", run_id: runId, revision: state.meta.revision,
+    revision_id: state.meta.revision_id, seal_status: seal.status,
+    content_digest: digestContent(content), artefacts,
+    git_history: gitHistory,
+    approvals: approvalSnapshot(content), approval_provenance: "no_independent_provenance",
+    next_gate_if_recovered: deriveNextGate(root, unapproveRecoveryApprovals(content), path),
+  });
+}
+
+function previewDirectory(runDir) {
+  const path = join(runDir, "recovery-previews");
+  try { mkdirSync(path, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; }
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) throw new Error("AGDF_RUN_PATH_INVALID");
+  if (process.platform !== "win32" && (stat.mode & 0o077) !== 0) throw new Error("AGDF_RECOVERY_JOURNAL_PERMISSIONS_INVALID");
+  return path;
+}
+
+function createJournal(path, record) {
+  let fd;
+  try {
+    fd = openSync(path, "wx", 0o600);
+    writeFileSync(fd, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+    fsyncSync(fd);
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+export function previewRunRecovery(root, runId, options = {}) {
+  const inspection = inspectRunRecovery(root, runId, options);
+  if (inspection.artefacts.some((entry) => entry.status !== "valid" && !entry.planned)) {
+    throw new Error(inspection.artefacts.some((entry) => entry.status === "invalid")
+      ? "AGDF_RECOVERY_ARTEFACT_PATH_INVALID" : "AGDF_RECOVERY_ARTEFACT_MISSING");
+  }
+  const { path, runDir } = safeRunFiles(root, runId);
+  const source = readFileSync(path, "utf8");
+  if (digestContent(source) !== inspection.content_digest) throw new Error("AGDF_STALE_RUN_REVISION");
+  if (JSON.stringify(artifactSnapshot(root, source)) !== JSON.stringify(inspection.artefacts)) throw new Error("AGDF_STALE_RUN_REVISION");
+  const previewId = randomUUID();
+  const nextRevisionId = randomUUID();
+  const candidate = unapproveRecoveryApprovals(source);
+  const preview = {
+    schema_version: "1", preview_format_version: 2, preview_id: previewId, run_id: runId,
+    created_at: new Date().toISOString(),
+    source_revision_id: inspection.revision_id, source_content_digest: inspection.content_digest,
+    source_content: source,
+    source_artefacts: inspection.artefacts, git_history: inspection.git_history,
+    prior_approvals: inspection.approvals,
+    approval_provenance: "no_independent_provenance", approvals_to_invalidate: userGateOrder,
+    next_gate: inspection.next_gate_if_recovered, next_revision_id: nextRevisionId,
+    candidate_content: candidate, candidate_digest: digestContent(candidate),
+    phase: "prepared",
+  };
+  preview.preview_digest = recoveryPreviewDigest(preview);
+  preview.confirmation = PREVIEW_CONFIRMATION(runId, previewId, preview.preview_digest);
+  const dir = previewDirectory(runDir);
+  const journalPath = join(dir, `${previewId}.json`);
+  createJournal(journalPath, preview);
+  return Object.freeze({
+    schema_version: "1", outcome: "previewed", run_id: runId, preview_id: previewId,
+    confirmation: preview.confirmation, source_content_digest: preview.source_content_digest,
+    source_artefacts: preview.source_artefacts, git_history: preview.git_history,
+    approvals_to_invalidate: preview.approvals_to_invalidate,
+    approval_provenance: preview.approval_provenance, next_gate: preview.next_gate,
+    journal: journalPath.slice(root.length + 1),
+  });
+}
+
+function readPreview(root, runDir, runId, previewId) {
+  if (!/^[0-9a-f-]{36}$/iu.test(previewId)) throw new Error("AGDF_RECOVERY_PREVIEW_INVALID");
+  const dir = join(runDir, "recovery-previews");
+  const dirStat = lstatSync(dir);
+  if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) throw new Error("AGDF_RUN_PATH_INVALID");
+  const path = join(dir, `${previewId}.json`);
+  const fileStat = lstatSync(path);
+  if (fileStat.isSymbolicLink() || !fileStat.isFile()) throw new Error("AGDF_RECOVERY_PREVIEW_INVALID");
+  const preview = JSON.parse(readFileSync(path, "utf8"));
+  if (preview.preview_format_version !== undefined && preview.preview_format_version !== 2) {
+    throw new Error("AGDF_RECOVERY_PREVIEW_VERSION_UNSUPPORTED");
+  }
+  if (preview.schema_version !== "1" || preview.preview_id !== previewId || preview.run_id !== runId
+      || preview.preview_digest !== recoveryPreviewDigest(preview)
+      || preview.confirmation !== PREVIEW_CONFIRMATION(runId, previewId, preview.preview_digest)
+      || preview.source_content_digest !== digestContent(preview.source_content)
+      || preview.candidate_digest !== digestContent(unapproveRecoveryApprovals(preview.source_content))
+      || preview.candidate_content !== unapproveRecoveryApprovals(preview.source_content)
+      || JSON.stringify(preview.prior_approvals) !== JSON.stringify(approvalSnapshot(preview.source_content))) {
+    throw new Error("AGDF_RECOVERY_PREVIEW_INVALID");
+  }
+  return { path, preview };
+}
+
+export function applyRunRecovery(root, { runId, previewId, confirmation }, hooks = {}) {
+  if (typeof confirmation !== "string") throw new Error("AGDF_RECOVERY_CONFIRMATION_REQUIRED");
+  const { path, runDir } = safeRunFiles(root, runId);
+  const { path: journalPath, preview } = readPreview(root, runDir, runId, previewId);
+  if (confirmation !== preview.confirmation) throw new Error("AGDF_RECOVERY_CONFIRMATION_REQUIRED");
+  return withRunLock(path, () => {
+    const lockedPreview = readPreview(root, runDir, runId, previewId).preview;
+    if (lockedPreview.preview_digest !== preview.preview_digest || lockedPreview.confirmation !== confirmation) {
+      throw new Error("AGDF_RECOVERY_PREVIEW_INVALID");
+    }
+    Object.assign(preview, lockedPreview);
+    const current = readFileSync(path, "utf8");
+    const currentDigest = digestContent(current);
+    if (JSON.stringify(artifactSnapshot(root, current)) !== JSON.stringify(preview.source_artefacts)) {
+      throw new Error("AGDF_STALE_RUN_REVISION");
+    }
+    if (preview.phase === "committed") {
+      const committed = parseRunState(current, runId);
+      if (currentDigest !== preview.result_digest || runSealState(root, current).status !== "valid"
+          || !committed.valid || committed.meta.revision_id !== preview.next_revision_id
+          || preview.result_revision_id !== preview.next_revision_id) throw new Error("AGDF_RECOVERY_JOURNAL_CONFLICT");
+      return Object.freeze({ schema_version: "1", outcome: "already_recovered", run_id: runId, preview_id: previewId, revision_id: preview.result_revision_id,
+        backlog: "pending", backlog_reason: "run_only_recovery",
+        backlog_next_action: `Synchronize this Run with run-update --run ${runId} --revision ${preview.result_revision_id}.` });
+    }
+    if (preview.phase !== "prepared" && preview.phase !== "applying") throw new Error("AGDF_RECOVERY_JOURNAL_PHASE_INVALID");
+    if (preview.phase === "prepared" && (currentDigest !== preview.source_content_digest
+        || current !== preview.source_content || JSON.stringify(artifactSnapshot(root, current)) !== JSON.stringify(preview.source_artefacts))) {
+      throw new Error("AGDF_STALE_RUN_REVISION");
+    }
+    const parsedSource = parseRunState(preview.source_content, runId);
+    if (!parsedSource.valid || parsedSource.meta.revision_id !== preview.source_revision_id) throw new Error("AGDF_RECOVERY_PREVIEW_INVALID");
+    const expectedResultContent = recoveryRunContent(root, preview.candidate_content, {
+      revision: parsedSource.meta.revision, nextRevisionId: preview.next_revision_id, updatedAt: preview.created_at,
+    });
+    const expectedResultDigest = digestContent(expectedResultContent);
+    let written;
+    if (preview.phase === "applying" && currentDigest === preview.result_digest
+        && currentDigest === expectedResultDigest && runSealState(root, current).status === "valid") {
+      written = parseRunState(current, runId);
+    } else {
+      if (preview.phase === "applying" && currentDigest !== preview.source_content_digest) throw new Error("AGDF_RECOVERY_JOURNAL_CONFLICT");
+      const applying = { ...preview, phase: "applying", source_content: current,
+        result_digest: expectedResultDigest, result_revision_id: preview.next_revision_id };
+      atomicWrite(journalPath, `${JSON.stringify(applying, null, 2)}\n`);
+      hooks.beforeRunWrite?.();
+      written = writeRunRecoveryLocked(path, preview.candidate_content, {
+        expectedContent: current, expectedRevisionId: preview.source_revision_id,
+        nextRevisionId: preview.next_revision_id,
+        updatedAt: preview.created_at,
+      });
+      hooks.afterRunWrite?.();
+    }
+    const resultContent = readFileSync(path, "utf8");
+    const completed = { ...preview, phase: "committed", result_digest: digestContent(resultContent), result_revision_id: written.meta.revision_id };
+    hooks.beforeJournalCommit?.();
+    atomicWrite(journalPath, `${JSON.stringify(completed, null, 2)}\n`);
+    return Object.freeze({ schema_version: "1", outcome: "recovered", run_id: runId,
+      backlog: "pending", backlog_reason: "run_only_recovery",
+      backlog_next_action: `Synchronize this Run with run-update --run ${runId} --revision ${written.meta.revision_id}.`,
+      preview_id: previewId, revision: written.meta.revision, revision_id: written.meta.revision_id,
+      seal_status: runSealState(root, resultContent).status, next_gate: deriveNextGate(root, resultContent, path) });
+  });
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-relationship-correction.js

@@ -0,0 +1,74 @@
+import { randomUUID } from "node:crypto";
+import { canonicalJson } from "./approval-command-contract.js";
+import { readArtefactBindings } from "./artefact-bindings.js";
+import { exactApprovedArtefacts, validateBindingProof } from "./artefact-binding-proof.js";
+import { APPROVAL_GATES, runSealState } from "./run-seal.js";
+import { readRun, appendTableRow, guardedWrite, rejected } from "./run-state-edits.js";
+import { prepareRunContentState } from "../control-evaluation/run-state.js";
+import { parseControlState } from "./run-state-parser.js";
+import { runPath } from "./run-state-reader.js";
+import { flushRunCommit, withRunLock, writeRunLocked } from "./run-state-writer.js";
+import { sameRelationship } from "../control-evaluation/delivery-relationships.js";
+import { transitionDecisionForRunState } from "../control-evaluation/gate-policy.js";
+
+const controlFor = (root, run) => ({ ...prepareRunContentState(root, run.content, run.path), meta: run.meta });
+
+// Mutation owner for authorized bound continuation only. Evaluators never call it.
+export function correctRunRelationship(root, { runId, revisionId }, { evaluateGateCheck, checkpoint, confirmCommit = flushRunCommit } = {}) {
+  const locked = guardedWrite(runId, () => withRunLock(runPath(root, runId), () => {
+    const run = readRun(root, runId);
+    if (run.rejection) return run.rejection;
+    if (run.meta.revision_id !== revisionId) return rejected(runId, "stale_revision");
+    if (runSealState(root, run.content).status !== "valid") return rejected(runId, "seal_invalid");
+    const report = evaluateGateCheck(root, { runId });
+    const decisive = (report.delivery_map?.findings ?? []).filter(row => ["block", "revise"].includes(row.severity));
+    const missing = (report.delivery_map?.relationships ?? []).filter(row => row.required && row.status === "missing");
+    if (missing.length === 0 && decisive.length === 0) return { schema_version: "1", outcome: "unchanged", run_id: runId, revision_id: revisionId };
+    const unrelatedDoctor = (report.doctor_report?.findings ?? []).filter(row => ["block", "revise"].includes(row.severity)
+      && row.code !== "AGDF_DELIVERY_RELATIONSHIP_MISSING");
+    if (unrelatedDoctor.length || decisive.length !== 1 || decisive[0].code !== "AGDF_DELIVERY_RELATIONSHIP_MISSING"
+        || missing.length !== 1 || report.blocking_reason !== "AGDF_DELIVERY_RELATIONSHIP_MISSING") return rejected(runId, "correction_not_eligible");
+    const control = controlFor(root, run), expected = missing[0];
+    if (control.artefact_chain.some(row => row.from === expected.from)) return rejected(runId, "correction_not_eligible");
+    const history = readArtefactBindings(run.content);
+    const eligible = history.active.filter(receipt => receipt.run_id === runId && receipt.operation.revision <= Number(run.meta.revision)
+      && sameRelationship(receipt.relationship, expected));
+    if (!history.valid || eligible.length !== 1) return rejected(runId, "binding_proof_missing_or_ambiguous");
+    const receipt = eligible[0], destinationGate = expected.from === "QA_REPORT" ? "QA" : expected.from;
+    const destination = control.artefacts.get(destinationGate), source = control.artefacts.get(expected.to);
+    if (destination?.path !== receipt.destination.path || source?.path !== receipt.source.path
+        || !validateBindingProof(root, receipt) || !exactApprovedArtefacts(root, control)) return rejected(runId, "artefact_binding_proof_invalid");
+    const before = canonicalJson(transitionDecisionForRunState(control));
+    let next = appendTableRow(run.content, "Artefact Chain", [expected.from, expected.relationship, expected.to,
+      `binding ${receipt.binding_id}; exact sealed reviewed mapping ${receipt.review.path}`]);
+    if (!next) return rejected(runId, "run_layout_unsupported");
+    const nextRevisionId = randomUUID();
+    next = appendTableRow(next, "Evidence", ["Relationship correction", receipt.review.path,
+      `binding ${receipt.binding_id}; ${expected.from} ${expected.relationship} ${expected.to}; revision ${revisionId} -> ${nextRevisionId}`, "exact sealed reviewed mapping"]);
+    if (!next || canonicalJson(transitionDecisionForRunState(controlFor(root, { ...run, content: next }))) !== before) return rejected(runId, "correction_permission_changed");
+    let written, recoveredCommit = false;
+    try { written = writeRunLocked(run.path, next, revisionId, { expectedContent: run.content, nextRevisionId, checkpoint,
+      validateBeforeWrite: () => {
+        if (!validateBindingProof(root, receipt) || !exactApprovedArtefacts(root, control)
+            || runSealState(root, run.content).status !== "valid") throw new Error("AGDF_ARTEFACT_BINDING_PROOF_INVALID");
+      } }); }
+    catch (error) {
+      const actual = readRun(root, runId);
+      if (actual.rejection || actual.meta.revision_id !== nextRevisionId || runSealState(root, actual.content).status !== "valid") throw error;
+      // Reuse the existing owner's durability confirmation; never retry into another revision.
+      try { confirmCommit(run.path); }
+      catch {
+        const unconfirmed = new Error("AGDF_CORRECTION_COMMIT_UNCONFIRMED");
+        unconfirmed.committed_revision_id = nextRevisionId;
+        throw unconfirmed;
+      }
+      written = { meta: actual.meta }; recoveredCommit = true;
+    }
+    return { schema_version: "1", outcome: "corrected", run_id: runId, binding_id: receipt.binding_id,
+      backlog: "pending", backlog_reason: "run_only_relationship_correction",
+      backlog_next_action: `Synchronize this Run with run-update --run ${runId} --revision ${written.meta.revision_id}.`,
+      relationship: receipt.relationship, previous_revision_id: revisionId, revision_id: written.meta.revision_id, revision: written.meta.revision,
+      ...(recoveredCommit ? { recovered_commit: true } : {}) };
+  }));
+  return locked.rejection ?? locked.state;
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-revision-boundary.js

@@ -0,0 +1,44 @@
+import { transitionDecisionForRunState } from "../control-evaluation/gate-policy.js";
+import { SOURCE_GATES } from "./run-source-revisions.js";
+
+// Shared by current revision preparation and historical proof validation. A history
+// cannot acquire authority from a boundary that the original Run did not satisfy.
+export function sourceRevisionBoundary(state, sourceGate, policyVersion = 1) {
+  const current = transitionDecisionForRunState(state);
+  if (policyVersion === 2) {
+    // Version selection comes from the exact proposal/receipt, never current defaults.
+    const phases = { UR: ["PRD", "SD", "TP", "CD+Tests", "QA", "UAT"],
+      PRD: ["SD", "TP", "CD+Tests", "QA", "UAT"], SD: ["TP", "CD+Tests", "QA", "UAT"], TP: ["CD+Tests", "QA", "UAT"] };
+    if (state.meta.lifecycle !== "active" || current.status !== "open"
+        || !["structured_delivery", "structured_slice"].includes(state.mode_slice_decision.decision)
+        || state.approvals.get("UAT")?.status === "approved" || state.artefacts.get("OR")?.status === "done"
+        || state.approvals.get(sourceGate)?.status !== "approved" || !phases[sourceGate]?.includes(current.current_gate)) return null;
+    const sources = SOURCE_GATES.filter(type => state.artefacts.get(type)?.path);
+    const approved = sources.filter(type => state.approvals.get(type)?.status === "approved");
+    if (!SOURCE_GATES.slice(0, SOURCE_GATES.indexOf(sourceGate) + 1).every(type => approved.includes(type))) return null;
+    return { sources, approved, bindings: sources.filter(type => type !== "UR"), initiating_phase: current.current_gate };
+  }
+  if (policyVersion !== 1) return null;
+  if (state.meta.lifecycle !== "active"
+      || !["structured_delivery", "structured_slice"].includes(state.mode_slice_decision.decision)
+      || current.status !== "open"
+      || ["QA", "UAT"].some(gate => state.approvals.get(gate)?.status === "approved")
+      || state.artefacts.get("OR")?.status === "done") return null;
+  if (current.current_gate === "CD+Tests") {
+    return { sources: SOURCE_GATES, approved: SOURCE_GATES, bindings: ["PRD", "SD", "TP"] };
+  }
+  if (sourceGate !== "UR" || current.current_gate !== "SD"
+      || !["UR", "PRD"].every(gate => state.approvals.get(gate)?.status === "approved")
+      || ["SD", "TP"].some(gate => state.approvals.get(gate)?.status === "approved")
+      || state.artefacts.get("SD")?.status !== "draft" || !state.artefacts.get("SD")?.path
+      || ["TP", "Brownfield Analysis", "CD+Tests", "CR", "Code Review", "TP Review", "Clean Review",
+        "Clean Implementation Review", "QA", "QA_REPORT", "UAT", "OR"]
+        .some(type => state.artefacts.get(type)?.path || state.artefacts.get(type)?.status === "done")) return null;
+  return { sources: ["UR", "PRD", "SD"], approved: ["UR", "PRD"], bindings: ["PRD", "SD"] };
+}
+
+// Existing early PRD-to-SD boundary, shared with its immutable history validator.
+export function earlyPrdRevisionBoundary(state) {
+  return state.meta?.lifecycle === 'active' && state.approvals.get('PRD')?.status === 'approved'
+    && state.meta.current_gate === 'SD' && !['SD', 'TP', 'QA', 'UAT'].some(gate => state.approvals.get(gate)?.status === 'approved' || state.artefacts.get(gate)?.path);
+}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/run-revision-history.js

@@ -0,0 +1,184 @@
+import { prepareRunContentState } from "../control-evaluation/run-state.js";
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "../control-read/fs.js";
+import { canonicalJson, digest, DIGEST_PATTERN, exactObject } from "./approval-command-contract.js";
+import { containedRegularFile, hasSymlinkComponent, isSafeControlRelativePath } from "./contained-file.js";
+import { APPROVAL_GATES, canonicalRunText, computeRunSeals, listedArtefactPaths, pendingArtefactPaths } from "./run-seal-compute.js";
+import { parseControlState, parseRunState } from "./run-state-parser.js";
+import { readArtefactBindings } from "./artefact-bindings.js";
+import { exactApprovedArtefacts, validateBindingProof } from "./artefact-binding-proof.js";
+import { internalStepArtefacts } from "../control-evaluation/run-state.js";
+import { readSourceRevisions, revisionHistoryPrefix, SOURCE_GATES, sourceRevisionImpact, validExpandedRevisionProof } from "./run-source-revisions.js";
+import { REVISION_PROPOSAL_FIELDS, REVISION_PROPOSAL_V2_FIELDS } from './recording-formats.js';
+import { sourceRevisionBoundary, earlyPrdRevisionBoundary } from "./run-revision-boundary.js";
+import { readRunOperations } from './run-operations.js';
+
+export const byteDigest = bytes => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+const DOCUMENT_LIMIT = 131072;
+const CONTROL_STATE_LIMIT = 1048576;
+const canonicalRunPath = path => /^\.agdf\/control\/runs\/[a-z0-9][a-z0-9._-]{0,127}\/RUN_STATE\.md$/u.test(path);
+const historyLimit = path => canonicalRunPath(path) ? CONTROL_STATE_LIMIT : DOCUMENT_LIMIT;
+// A long-lived canonical control record is not an input document. Ordinary sources,
+// proposals and manifests retain their existing bound; every read checks before allocation.
+function readBoundedHistoryBytes(root, path, limit) {
+  const file = containedRegularFile(root, path);
+  if (file.status !== "valid" || hasSymlinkComponent(root, path) || statSync(file.path).size > limit) throw Error("AGDF_REVISION_HISTORY_INVALID");
+  return readFileSync(file.path);
+}
+export function readHistoryBytes(root, path) {
+  return readBoundedHistoryBytes(root, path, historyLimit(path));
+}
+
+export function collectRevisionHistory(root, runId, operationId, paths) {
+  const prefix = revisionHistoryPrefix(runId, operationId);
+  const files = [...new Set(paths)].sort().map((path, i) => {
+    if (!isSafeControlRelativePath(path) || !path.startsWith(".agdf/control/")) throw Error("AGDF_REVISION_HISTORY_INVALID");
+    const bytes = readBoundedHistoryBytes(root, path,
+      path === `.agdf/control/runs/${runId}/RUN_STATE.md` ? CONTROL_STATE_LIMIT : DOCUMENT_LIMIT);
+    return { path, snapshot: `${prefix}files/${i}.bin`, bytes, digest: byteDigest(bytes),
+      canonical_digest: byteDigest(Buffer.from(canonicalRunText(bytes.toString("utf8")), "utf8")) };
+  });
+  const manifest = { schema_version: "1", run_id: runId, operation_id: operationId,
+    files: files.map(({ path, snapshot, bytes, digest, canonical_digest }) => ({ path, snapshot, length: bytes.length, digest, canonical_digest })) };
+  const text = canonicalJson(manifest) + "\n";
+  if (Buffer.byteLength(text) > 131072) throw Error("AGDF_REVISION_HISTORY_INVALID");
+  return { manifest, text, digest: byteDigest(Buffer.from(text)), files };
+}
+
+export function readValidatedRevisionArchive(root, receipt) {
+  try {
+    const bytes = readHistoryBytes(root, receipt.archive.path);
+    if (byteDigest(bytes) !== receipt.archive.digest) return false;
+    const manifest = JSON.parse(bytes.toString("utf8")), prefix = revisionHistoryPrefix(receipt.run_id, receipt.operation_id);
+    // target_id names the recording checkout; clones verify it via the archived proposal, not their path.
+    if (!exactObject(manifest, ["schema_version", "run_id", "operation_id", "files"]) || manifest.schema_version !== "1"
+        || manifest.run_id !== receipt.run_id || manifest.operation_id !== receipt.operation_id
+        || !Array.isArray(manifest.files) || !manifest.files.length) return false;
+    const names = new Set(), snapshots = new Set(), archived = new Map(), digests = new Map();
+    for (const row of manifest.files) {
+      if (!exactObject(row, ["path", "snapshot", "length", "digest", "canonical_digest"])
+          || !isSafeControlRelativePath(row.path) || !row.path.startsWith(".agdf/control/")
+          || !new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")}files/[0-9]+\\.bin$`, "u").test(row.snapshot)
+          || !Number.isSafeInteger(row.length) || row.length < 0
+          || row.length > (row.path === `.agdf/control/runs/${receipt.run_id}/RUN_STATE.md` ? CONTROL_STATE_LIMIT : DOCUMENT_LIMIT)
+          || !DIGEST_PATTERN.test(row.digest) || !DIGEST_PATTERN.test(row.canonical_digest)
+          || names.has(row.path) || snapshots.has(row.snapshot)) return false;
+      // Only the exact original Run record permits a larger archive snapshot.
+      // Arbitrary .bin names and other document rows cannot widen the reader.
+      const actual = readBoundedHistoryBytes(root, row.snapshot,
+        row.path === `.agdf/control/runs/${receipt.run_id}/RUN_STATE.md` ? CONTROL_STATE_LIMIT : DOCUMENT_LIMIT);
+      if (actual.length !== row.length || byteDigest(actual) !== row.digest
+          || byteDigest(Buffer.from(canonicalRunText(actual.toString("utf8")))) !== row.canonical_digest) return false;
+      names.add(row.path); snapshots.add(row.snapshot);
+      archived.set(row.path, actual); digests.set(row.path, row.canonical_digest);
+    }
+    const original = archived.get(`.agdf/control/runs/${receipt.run_id}/RUN_STATE.md`)?.toString("utf8");
+    if (!original) return false;
+    const parsed = parseRunState(original, receipt.run_id);
+    if (!parsed.valid || parsed.meta.revision_id !== receipt.previous_revision_id
+        || Number(parsed.meta.revision) + 1 !== receipt.revision) return false;
+    // Resolve original paths through the archived closure. Live canonical drafts may have
+    // changed since this receipt; they cannot repair or invalidate its historical proofs.
+    for (const path of listedArtefactPaths(original)) {
+      if (!digests.has(path)) {
+        if (!pendingArtefactPaths(original).includes(path)) return false;
+        digests.set(path, "missing");
+      }
+    }
+    const seals = computeRunSeals(root, original, { artefactDigests: digests });
+    if (seals.content_seal !== parsed.meta.content_seal || seals.approval_seal !== parsed.meta.approval_seal) return false;
+    const readers = { historical: true, fileDigest: path => digests.get(path) ?? "missing",
+      rawFileDigest: path => archived.has(path) ? byteDigest(archived.get(path)) : "missing", readJson: path => JSON.parse(archived.get(path).toString("utf8")) };
+    const control = { ...prepareRunContentState(root, original, "", { readArtefact: path => archived.get(path)?.toString("utf8") }), meta: parsed.meta };
+    return { manifest, original, parsed, archived, digests, names, readers, control };
+  } catch { return false; }
+}
+
+export function validateRevisionHistory(root, receipt) {
+  try {
+    const closure = readValidatedRevisionArchive(root, receipt);
+    if (!closure) return false;
+    const { original, parsed, archived, digests, names, readers, control } = closure;
+    const expanded = receipt.schema_version === '3';
+    const boundary = sourceRevisionBoundary(control, receipt.source_gate, expanded ? 2 : 1);
+    if (!boundary || !boundary.sources.every(type => names.has(`.agdf/control/artefacts/${receipt.run_id}/${type}.md`))) return false;
+    const bindings = readArtefactBindings(original);
+    // The receipt pins an actually archived reviewed request and its computed preview,
+    // not just unrelated valid old approvals beside caller-supplied request hashes.
+    const proposals = [...archived.values()].flatMap(bytes => {
+      try { const row = JSON.parse(bytes.toString("utf8")); return digest(canonicalJson(row)) === receipt.request_digest ? [row] : []; } catch { return []; }
+    });
+    const proposal = proposals[0];
+    if (['2', '3'].includes(receipt.schema_version)) {
+      const bytes = archived.get(receipt.proposal_reference.path);
+      if (!bytes || digest(canonicalRunText(bytes.toString('utf8'))) !== receipt.proposal_reference.digest) return false;
+    }
+    const sources = boundary.sources.map(type => ({ type, path: control.artefacts.get(type)?.path, digest: digests.get(control.artefacts.get(type)?.path) }));
+    if (proposals.length !== 1 || !exactObject(proposal, expanded ? REVISION_PROPOSAL_V2_FIELDS : REVISION_PROPOSAL_FIELDS)
+        || proposal.schema_version !== (expanded ? '2' : '1') || proposal.target_id !== receipt.target_id || proposal.run_id !== receipt.run_id
+        || proposal.expected_revision_id !== receipt.previous_revision_id || proposal.operation_id !== receipt.operation_id
+        || proposal.source_gate !== receipt.source_gate || proposal.reason !== receipt.reason || canonicalJson(proposal.sources) !== canonicalJson(sources)
+        || canonicalJson(proposal.impact_assessment?.upstream) !== canonicalJson(receipt.retained_sources)
+        || canonicalJson(proposal.impact_assessment?.analyses) !== canonicalJson(receipt.analyses)) return false;
+    const impact = sourceRevisionImpact(proposal, bindings.active);
+    if (expanded && (receipt.policy_version !== 2 || receipt.initiating_phase !== boundary.initiating_phase
+      || receipt.impact_digest !== digest(canonicalJson(impact)) || receipt.quality_digest !== digest(canonicalJson(proposal.quality_assessment))
+      || !validExpandedRevisionProof(proposal, control, path => archived.get(path)?.toString('utf8'), boundary.initiating_phase))) return false;
+    const preview = { schema_version: expanded ? '2' : "1", target_id: receipt.target_id, run_id: receipt.run_id, expected_revision_id: receipt.previous_revision_id,
+      operation_id: receipt.operation_id, request_digest: receipt.request_digest, reason: proposal.reason, intended_change: proposal.intended_change,
+      sources, impact, archive_digest: receipt.archive.digest,
+      current_run_digest: byteDigest(archived.get(`.agdf/control/runs/${receipt.run_id}/RUN_STATE.md`)) };
+    if (digest(canonicalJson(preview)) !== receipt.preview_digest) return false;
+    return boundary.approved.every(type => control.approvals.get(type)?.status === "approved")
+      && exactApprovedArtefacts(root, control, readers) && bindings.valid
+      && boundary.bindings.every(type => bindings.active.some(row => row.destination.type === type && validateBindingProof(root, row, readers)))
+      && canonicalJson(receipt.invalidated_bindings) === canonicalJson(impact.invalidated_bindings)
+      && receipt.retained_sources.every(row => digests.get(row.path) === row.digest)
+      && receipt.analyses.every(row => control.artefacts.get(row.type)?.path === row.path && digests.get(row.path) === row.digest);
+  } catch { return false; }
+}
+
+const SOURCE_TYPES = SOURCE_GATES;
+
+export function validSourceRevisionHistories(root, content) {
+  const history = readSourceRevisions(content);
+  const operations = readRunOperations(content);
+  return history.valid && history.receipts.every(receipt => validateRevisionHistory(root, receipt)) && operations.valid
+    && operations.receipts.filter(row => row.kind === 'prd_revision.reopen').every(receipt => validateEarlyPrdHistory(root, receipt));
+}
+
+export const earlyPrdHistoryReference = receipt => ({ run_id: receipt.run_id, operation_id: receipt.operation_id, archive: receipt.effect.record.archive,
+  previous_revision_id: receipt.expected_revision_id, revision: receipt.effect.revision });
+export function validateEarlyPrdHistory(root, receipt) {
+  try {
+    const closure = readValidatedRevisionArchive(root, earlyPrdHistoryReference(receipt));
+    if (!closure || !earlyPrdRevisionBoundary(closure.control)) return false;
+    return closure.control.artefacts.get('PRD')?.path === receipt.effect.record.prd.path
+      && closure.digests.get(receipt.effect.record.prd.path) === receipt.effect.record.prd.digest
+      && exactApprovedArtefacts(root, closure.control, closure.readers);
+  } catch { return false; }
+}
+
+export function validEarlyPrdEffect(before, after) {
+  const parse = content => parseControlState(content, { userGates: APPROVAL_GATES });
+  const old = parse(before), next = parse(after);
+  return earlyPrdRevisionBoundary({ ...old, meta: parseRunState(before).meta })
+    && APPROVAL_GATES.every(gate => gate === 'PRD' ? next.approvals.get(gate)?.status === 'missing' && !next.approvals.get(gate)?.evidence
+      : canonicalJson(old.approvals.get(gate)) === canonicalJson(next.approvals.get(gate)))
+    && [...old.artefacts].every(([type, row]) => type === 'PRD' ? next.artefacts.get(type)?.path === row.path && next.artefacts.get(type)?.status === 'draft'
+      : canonicalJson(next.artefacts.get(type)) === canonicalJson(row))
+    && parseRunState(after).meta.current_gate === 'PRD' && parseRunState(after).meta.lifecycle === 'active';
+}
+
+export function inspectRevisionHistory(root, receipt) {
+  if (!validateRevisionHistory(root, receipt)) throw Error("AGDF_REVISION_HISTORY_INVALID");
+  return { authority: "historical_evidence_only", receipt,
+    manifest: JSON.parse(readHistoryBytes(root, receipt.archive.path).toString("utf8")) };
+}
+
+export function archivedRunMatches(root, receipt, content) {
+  try {
+    const manifest = JSON.parse(readHistoryBytes(root, receipt.archive.path).toString("utf8"));
+    return manifest.files.find(row => row.path === `.agdf/control/runs/${receipt.run_id}/RUN_STATE.md`)?.digest === byteDigest(Buffer.from(content));
+  } catch { return false; }
+}