create-agdf 0.20.2 → 0.31.0

package/runtime/core/lib/control-state/legacy-projection-reader.js

@@ -1,38 +0,0 @@
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "../control-read/fs.js";
-import { join, relative, resolve } from "node:path";
-import { normalizeLineEndings } from "./run-state-parser.js";
-import { discoverRuns, runPath } from "./run-state-reader.js";
-
-function sha256(content) {
-  return createHash("sha256").update(content).digest("hex");
-}
-
-export function verifyLegacyProjection(root) {
-  const path = join(root, ".agdf", "control", "AGDF_RUN.md");
-  if (!existsSync(path)) return { status: "absent" };
-  const projection = normalizeLineEndings(readFileSync(path, "utf8"));
-  const source = projection.match(/canonical_source:\s*(.*?)\s*-->/)?.[1];
-  const runId = projection.match(/<!-- run_id:\s*(.*?)\s*-->/)?.[1];
-  const digest = projection.match(/sha256:\s*([0-9a-f]{64})/)?.[1];
-  const projectedStart = projection.indexOf("# AGDF Run State");
-  const projected = projectedStart >= 0 ? projection.slice(projectedStart) : undefined;
-  if (!source || !runId || !digest || projected === undefined) {
-    return { status: discoverRuns(root).length ? "mixed_authority" : "legacy" };
-  }
-  const target = resolve(root, source.replaceAll("\\", "/"));
-  const targetRelative = relative(resolve(root), target);
-  const expected = relative(resolve(root), resolve(runPath(root, runId)));
-  if (targetRelative.startsWith("..") || !targetRelative || targetRelative !== expected || !existsSync(target)) {
-    return { status: "projection_source_invalid" };
-  }
-  const canonical = normalizeLineEndings(readFileSync(target, "utf8"));
-  // Git checkouts may convert line endings (core.autocrlf), and projections rendered from a CRLF
-  // checkout carry a CRLF digest, so the digest identifies the content independent of line endings.
-  const digestMatches = [canonical, canonical.replaceAll("\n", "\r\n")].some((text) => sha256(text) === digest);
-  return {
-    status: digestMatches && projected === canonical
-      ? "valid"
-      : "legacy_projection_drift",
-  };
-}

package/runtime/core/lib/control-state/run-backlog-writer.js

@@ -1,80 +0,0 @@
-import { readFileSync } from "node:fs";
-import { join, relative, sep } from "node:path";
-import { parseRunState } from "./run-state-parser.js";
-import { runSealState } from "./run-seal.js";
-import { atomicWrite, withOwnedFileLock, writeRunLocked } from "./run-state-writer.js";
-import { commitRunStepLocked, recoverPendingRunStepLocked, readPendingRunStepJournal } from "./run-step-transaction.js";
-import { pendingRunStepIds } from "./run-step-pending.js";
-import { BACKLOG_RELATIVE_PATH, prepareRunBacklogOrSkip } from "./run-backlog.js";
-import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
-import { randomUUID } from "node:crypto";
-import { existsSync } from 'node:fs';
-import { pendingRunStepPath } from './run-step-pending.js';
-import { assertSummarySources } from "../control-evaluation/run-work-summary.js";
-
-export function withRunBacklogLock(root, path, work, options = {}) {
-  const relativePath = relative(root, path).split(sep).join("/");
-  if (hasSymlinkComponent(root, relativePath) || containedRegularFile(root, relativePath).status !== "valid") throw Error("AGDF_RUN_PATH_INVALID");
-  // The Run path check covers the shared .agdf/control ancestors, so the sibling Backlog lock is
-  // contained. An unusable Backlog file itself is reported by the planner, not by the lock.
-  return withOwnedFileLock(path, () => {
-    return withOwnedFileLock(join(root, BACKLOG_RELATIVE_PATH), () => {
-      const run = parseRunState(readFileSync(path, "utf8"));
-      if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
-      const other = pendingRunStepIds(root).find(id => id !== run.meta.run_id);
-      if (other) { const error = Error("AGDF_RUN_STEP_RECOVERY_REQUIRED"); error.pending_run_id = other; throw error; }
-      if (options.operationContext && existsSync(pendingRunStepPath(root, run.meta.run_id))) {
-        const pending = readPendingRunStepJournal(root, run.meta.run_id), expected = options.operationContext;
-        if (pending.schema_version !== 3 || pending.operation_id !== expected.operation_id || pending.kind !== expected.kind
-          || pending.target_id !== expected.target_id || pending.request_digest !== expected.request_digest) throw Error('AGDF_RUN_STEP_RECOVERY_REQUIRED');
-      }
-      recoverPendingRunStepLocked(root, run.meta.run_id);
-      return work();
-    });
-  }, options);
-}
-
-// Both locks are held by the caller. The existing journal keeps receipt, seal, revision
-// and Backlog projection recoverable at the same Run commit point.
-export function writeRunWithBacklogLocked(root, path, content, revisionId, options = {}) {
-  const old = readFileSync(path, "utf8"), run = parseRunState(old);
-  if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
-  if (run.meta.revision_id !== revisionId || options.expectedContent !== undefined && old !== options.expectedContent) throw Error("AGDF_STALE_RUN_REVISION");
-  const nextRevisionId = options.nextRevisionId ?? randomUUID();
-  const plan = prepareRunBacklogOrSkip(root, run.meta.run_id, content, path, nextRevisionId);
-  const withBacklog = state => ({ ...state, backlog: plan.status, backlog_reason: plan.reason ?? null });
-  const guard = () => { if (plan.summary) assertSummarySources(root, plan.summary); };
-  if (!plan.update && !options.operationContext) return withBacklog(writeRunLocked(path, content, revisionId, { ...options, nextRevisionId,
-    validateBeforeWrite: () => { options.validateBeforeWrite?.(); guard(); } }));
-  // Full gate/presentation evaluation still sees the original sealed Run, under both
-  // locks. The journal then rechecks its captured source digests and envelope at commit.
-  options.validateBeforeWrite?.();
-  return withBacklog(commitRunStepLocked(root, { runId: run.meta.run_id, runPath: path, content,
-    revisionId, expectedContent: old, backlog: plan.update, or: null,
-    operationContext: options.operationContext,
-    nextRevisionId,
-    writeOptions: { ...options, validateBeforeWrite: () => { options.validateDuringTransaction?.(); guard(); } }, afterWrite: options.afterWrite }));
-}
-
-export function writeRunWithBacklog(root, path, content, revisionId, options = {}) {
-  return withRunBacklogLock(root, path, () => writeRunWithBacklogLocked(root, path, content, revisionId, options));
-}
-
-// Explicit repair of a valid sealed Run's stale pointer needs only one atomic file write;
-// no fabricated Run revision, new approval or reader-side write is necessary.
-export function synchronizeRunBacklog(root, path, revisionId) {
-  return withRunBacklogLock(root, path, () => {
-    const content = readFileSync(path, "utf8"), run = parseRunState(content);
-    if (!run.valid) throw Error("AGDF_RUN_STATE_INVALID");
-    if (run.meta.revision_id !== revisionId) throw Error("AGDF_STALE_RUN_REVISION");
-    if (runSealState(root, content).status !== "valid") throw Error("AGDF_RUN_SEAL_INVALID");
-    const plan = prepareRunBacklogOrSkip(root, run.meta.run_id, content, path, revisionId);
-    if (plan.update) {
-      assertSummarySources(root, plan.summary);
-      if (readFileSync(path, "utf8") !== content || runSealState(root, content).status !== "valid"
-          || readFileSync(join(root, BACKLOG_RELATIVE_PATH), "utf8") !== plan.update.old) throw Error("AGDF_STALE_RUN_REVISION");
-      atomicWrite(join(root, BACKLOG_RELATIVE_PATH), plan.update.next);
-    }
-    return { meta: run.meta, backlog: plan.status, backlog_reason: plan.reason ?? null };
-  });
-}

package/runtime/core/lib/control-state/run-backlog.js

@@ -1,90 +0,0 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { firstSection, tableCells, tableLine, tableLineIndexes } from "./run-state-edits.js";
-import { containedRegularFile, hasSymlinkComponent } from "./contained-file.js";
-import { policyForRunContent } from "../control-evaluation/run-step-policy.js";
-import { runWorkSummary } from "../control-evaluation/run-work-summary.js";
-import { recordBacklogSummary } from "./backlog-summary.js";
-import { parseRunState } from "./run-state-parser.js";
-
-export const BACKLOG_RELATIVE_PATH = ".agdf/control/MASTER_BACKLOG.md";
-const compactHeaders = ["priority", "key", "work item", "status", "artefacts", "current spec", "next step"];
-const legacyHeaders = ["prio", "key", "title", "status", "ur", "brownfield review", "prd", "sd", "tp", "qa", "or", "current spec", "notes"];
-const clean = value => value.replaceAll("`", "").trim();
-export const backlogTableLayout = headers => {
-  const normalized = headers.map(value => clean(value).toLowerCase()).join("\0");
-  return normalized === compactHeaders.join("\0") ? "compact" : normalized === legacyHeaders.join("\0") ? "legacy" : null;
-};
-const SKIPPABLE_BACKLOG_ERRORS = new Map([
-  ["AGDF_BACKLOG_PATH_INVALID", "backlog_path_invalid"],
-  ["AGDF_BACKLOG_LAYOUT_UNSUPPORTED", "backlog_layout_unsupported"],
-  ["AGDF_BACKLOG_IDENTITY_AMBIGUOUS", "backlog_identity_ambiguous"],
-]);
-
-// A saved projection of the same policy used by the Run writer, never UR metadata or a
-// reader-side claim of current readiness. Completion still belongs to explicit closeout.
-export function backlogStatusForPolicy(after) {
-  if (after.status === "blocked") return "Blocked";
-  if (after.current_gate === "UR") return "Needs UR";
-  if (after.current_gate === "Brownfield Review") return "Awaiting Brownfield Review";
-  if (["PRD", "SD", "TP"].includes(after.current_gate)) return `Awaiting ${after.current_gate}`;
-  if (["QA", "UAT"].includes(after.current_gate) && after.missing_approval === `Approval: ${after.current_gate}`) return `Awaiting ${after.current_gate}`;
-  if (after.current_gate === "OR") return "Awaiting OR";
-  if (["Brownfield Analysis", "CD+Tests", "CR", "Quick Task Execution", "Verified Change Execution", "Mode/Slice Decision"].includes(after.current_gate)) return `${after.current_gate} work pending`;
-  return "In Progress";
-}
-export const backlogStatusForSummary = (summary, after) =>
-  ["work_pending", "approval_pending", "closeout_pending"].includes(summary.kind)
-    ? backlogStatusForPolicy(after) : summary.status_label;
-
-export function assertBacklogPath(root) {
-  if (hasSymlinkComponent(root, BACKLOG_RELATIVE_PATH)
-      || existsSync(join(root, BACKLOG_RELATIVE_PATH)) && containedRegularFile(root, BACKLOG_RELATIVE_PATH).status !== "valid") {
-    throw Error("AGDF_BACKLOG_PATH_INVALID");
-  }
-}
-
-// Change only the addressed existing Active row. Keep title, links, order, other rows and
-// archive/planning placement intact. Unsupported layouts and ambiguous identities fail closed.
-export function prepareRunBacklog(root, runId, content, runPath, revisionId = parseRunState(content).meta.revision_id) {
-  assertBacklogPath(root);
-  const path = join(root, BACKLOG_RELATIVE_PATH);
-  if (!existsSync(path)) return { status: "missing", update: null };
-  const old = readFileSync(path, "utf8"), lines = old.split("\n");
-  if (Buffer.byteLength(old) > 2097152) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
-  const section = firstSection(lines, "Active Backlog");
-  if (!section) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
-  const indexes = tableLineIndexes(lines, section), layout = backlogTableLayout(tableCells(lines[indexes[0]] ?? ""));
-  const width = layout === "compact" ? compactHeaders.length : layout === "legacy" ? legacyHeaders.length : undefined;
-  if (!width || indexes.length < 2 || tableCells(lines[indexes[1]]).length !== width
-      || tableCells(lines[indexes[1]]).some(value => !/^:?-{3,}:?$/u.test(value))) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
-  const matches = indexes.slice(2).filter(index => clean(tableCells(lines[index])[1] ?? "") === runId);
-  if (matches.length > 1) throw Error("AGDF_BACKLOG_IDENTITY_AMBIGUOUS");
-  if (!matches.length) return { status: "unlinked", update: null };
-  for (const [heading, column] of [["Planned / Parking Lot", 1], ["Completed / Superseded Pointers", 0]]) {
-    const other = firstSection(lines, heading);
-    if (other && tableLineIndexes(lines, other).slice(2).some(index => clean(tableCells(lines[index])[column] ?? "") === runId)) throw Error("AGDF_BACKLOG_IDENTITY_AMBIGUOUS");
-  }
-  const index = matches[0], cells = tableCells(lines[index]);
-  if (cells.length !== width) throw Error("AGDF_BACKLOG_LAYOUT_UNSUPPORTED");
-  const after = policyForRunContent(root, content, runPath);
-  const summary = runWorkSummary(root, content, runPath, after);
-  const status = backlogStatusForSummary(summary, after);
-  const next = summary.display_action;
-  cells[3] = status; cells[width - 1] = next;
-  lines[index] = tableLine(cells);
-  const updated = recordBacklogSummary(root, lines.join("\n"), runId, "Active Backlog", summary, revisionId);
-  return { status: old === updated ? "unchanged" : "updated", summary, update: old === updated ? null : { old, next: updated } };
-}
-
-// Approvals and run-update stay valid when the saved pointer cannot be synchronized. The
-// pointer is left untouched and the result names why; the doctor reports the backlog itself.
-export function prepareRunBacklogOrSkip(root, runId, content, runPath, revisionId) {
-  try { return prepareRunBacklog(root, runId, content, runPath, revisionId); }
-  catch (error) {
-    const reason = SKIPPABLE_BACKLOG_ERRORS.get(error?.message);
-    if (!reason) throw error;
-    return { status: "skipped", reason, update: null };
-  }
-}
-export const backlogSkip = plan => plan?.reason ? { backlog: plan.status, backlog_reason: plan.reason } : {};

package/runtime/core/lib/control-state/run-recovery.js

@@ -1,296 +0,0 @@
-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/runtime/core/lib/control-state/run-relationship-correction.js

@@ -1,74 +0,0 @@
-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;
-}