create-agdf 0.20.1 → 0.30.0

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/backlog-summary.js

@@ -1,67 +0,0 @@
-import { BACKLOG_SUMMARY_FIELDS, validBacklogSummary } from './backlog-summary-shape.js';
-import { createHash } from 'node:crypto';
-import { canonicalJson, resolveControlCommandTarget } from './approval-command-contract.js';
-import { firstSection, tableCells, tableLineIndexes } from './run-state-edits.js';
-import { summaryLabel } from '../control-evaluation/backlog-vocabulary.js';
-
-export const BACKLOG_SUMMARY_LIMIT = 65536;
-const prefix = '<!-- agdf-backlog-summary-v1 ';
-const fields = BACKLOG_SUMMARY_FIELDS;
-const digest = bytes => 'sha256:' + createHash('sha256').update(bytes).digest('hex');
-const sections = ['Active Backlog', 'Planned / Parking Lot', 'Completed / Superseded Pointers'];
-export const backlogRowDigest = (section, cells) => digest(canonicalJson({ section, cells }));
-export { validBacklogSummary } from './backlog-summary-shape.js';
-
-export function decodeBacklogMarker(line) {
-  if (!line.startsWith('<!-- agdf-backlog-summary-')) return null;
-  const match = line.match(/^<!-- agdf-backlog-summary-v1 ([A-Za-z0-9+/]+={0,2}) -->$/u);
-  if (!match || match[1].length > Math.ceil(BACKLOG_SUMMARY_LIMIT / 3) * 4) return { code: 'backlog_summary_invalid', record: null };
-  try {
-    const bytes = Buffer.from(match[1], 'base64');
-    if (bytes.length > BACKLOG_SUMMARY_LIMIT || bytes.toString('base64') !== match[1]) throw Error();
-    const value = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-    const record = JSON.parse(value);
-    if (!validBacklogSummary(record) || canonicalJson(record) !== value) throw Error();
-    return { code: null, record };
-  } catch { return { code: 'backlog_summary_invalid', record: null }; }
-}
-export function savedBacklogSummary(root, section, cells, markers) {
-  const key = cells[section === sections[2] ? 0 : 1]?.replaceAll('`', '').trim();
-  const candidates = markers.filter(m => m.record?.run_id === key);
-  const fallback = code => ({ provenance_state: code ? 'invalid' : 'unverified', code, record: null,
-    label_de: null, limitation_de: code ? 'Gespeicherter Quellenbezug ungültig; aktueller Stand nicht geprüft.' : 'Gespeicherter Stand; Quellenbezug und aktueller Run nicht geprüft.', authorizes: false });
-  if (!candidates.length) return fallback(markers.some(m => m.code) ? 'backlog_summary_invalid' : null);
-  const row = candidates[0].record;
-  if (markers.some(m => m.code) || candidates.length !== 1 || row.target_id !== resolveControlCommandTarget(root).target_id
-      || row.section !== section || row.row_digest !== backlogRowDigest(section, cells)) return fallback('backlog_summary_mismatch');
-  return { provenance_state: 'recorded', code: null, record: row, label_de: summaryLabel(row.kind, 'de'),
-    limitation_de: row.limitations.length ? 'Quellenbezug eingeschränkt; aktueller Stand nicht bestätigt.'
-      : 'Gespeicherte Beobachtung; aktueller Run noch nicht verglichen.', authorizes: false };
-}
-
-// Called by existing writers under their locks. Only the addressed marker is replaced.
-export function recordBacklogSummary(root, content, runId, section, summary, revisionId) {
-  if (Buffer.byteLength(content) > 2097152) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED');
-  const bounded = next => { if (Buffer.byteLength(next) > 2097152) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED'); return next; };
-  const lines = content.split('\n'), scope = firstSection(lines, section);
-  if (!scope) throw Error('AGDF_BACKLOG_LAYOUT_UNSUPPORTED');
-  const indexes = tableLineIndexes(lines, scope), column = section === sections[2] ? 0 : 1;
-  const matches = indexes.slice(2).filter(i => tableCells(lines[i])[column]?.replaceAll('`', '').trim() === runId);
-  if (matches.length !== 1) throw Error('AGDF_BACKLOG_IDENTITY_AMBIGUOUS');
-  const row = { schema_version: 1, target_id: resolveControlCommandTarget(root).target_id, run_id: runId,
-    section, row_digest: backlogRowDigest(section, tableCells(lines[matches[0]])), revision_id: revisionId,
-    observed_at: new Date().toISOString(), ...Object.fromEntries(fields.slice(7).map(k => [k, summary[k]])) };
-  const previous = lines.map(decodeBacklogMarker).filter(m => m?.record?.run_id === runId);
-  if (previous.length === 1 && canonicalJson({ ...previous[0].record, observed_at: row.observed_at }) === canonicalJson(row)) row.observed_at = previous[0].record.observed_at;
-  const encoded = canonicalJson(row);
-  if (!validBacklogSummary(row) || Buffer.byteLength(encoded) > BACKLOG_SUMMARY_LIMIT) throw Error('AGDF_BACKLOG_SUMMARY_INVALID');
-  // An identical explicit synchronization preserves all bytes, including whitespace and time.
-  if (previous.length === 1 && canonicalJson(previous[0].record) === encoded) return content;
-  if (previous.length === 1 && previous[0].record.section === section) return bounded(lines.map(line =>
-    decodeBacklogMarker(line)?.record?.run_id === runId ? prefix + Buffer.from(encoded).toString('base64') + ' -->' : line).join('\n'));
-  const filtered = lines.filter(line => decodeBacklogMarker(line)?.record?.run_id !== runId);
-  const target = firstSection(filtered, section), table = tableLineIndexes(filtered, target);
-  const afterTable = table.at(-1) + 1;
-  filtered.splice(afterTable, 0, '', prefix + Buffer.from(encoded).toString('base64') + ' -->');
-  return bounded(filtered.join('\n'));
-}

package/generated/plugins/agdf/runtime/create-agdf/runtime/core/lib/control-state/legacy-migration.js

@@ -1,69 +0,0 @@
-import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, rmdirSync, unlinkSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import { renderRunState } from "./run-state-repository.js";
-import { runPath } from "./run-state-reader.js";
-import {
-  normalizeLineEndings,
-  parseRunState,
-  RUN_ID_PATTERN,
-  scalarFields,
-  semanticBody,
-  semanticFingerprint,
-} from "./run-state-parser.js";
-import { atomicWrite } from "./run-state-writer.js";
-export function migrateLegacy(root, requested, io = {}) {
-  const writeCanonical = io.atomicWrite ?? atomicWrite;
-  const readCanonical = io.readFile ?? readFileSync;
-  const lp = join(root, ".agdf", "control", "AGDF_RUN.md");
-  if (!existsSync(lp)) throw Error("AGDF_LEGACY_RUN_MISSING");
-  const legacy = readFileSync(lp, "utf8");
-  if (legacy.startsWith("<!-- AGDF LEGACY PROJECTION"))
-    throw Error("AGDF_LEGACY_ALREADY_PROJECTED");
-  if (!legacy.startsWith("# AGDF Run State") || !semanticBody(legacy))
-    throw Error("AGDF_LEGACY_RUN_INVALID");
-  const id = requested || scalarFields(legacy).values.get("run_id");
-  if (!RUN_ID_PATTERN.test(id ?? "")) throw Error("AGDF_RUN_ID_INVALID");
-  const legacyMeta = Object.fromEntries(scalarFields(legacy).values);
-  const dest = runPath(root, id),
-    next = renderRunState(id, semanticBody(legacy), legacyMeta);
-  if (existsSync(dest)) {
-    if (
-      semanticFingerprint(readFileSync(dest, "utf8")) ===
-      semanticFingerprint(next)
-    )
-      return { status: "already_migrated", path: dest };
-    throw Error("AGDF_RUN_COLLISION");
-  }
-  mkdirSync(dirname(dest), { recursive: true });
-  try {
-    writeCanonical(dest, next);
-    const persisted = readCanonical(dest, "utf8"),
-      parsed = parseRunState(persisted, id);
-    if (
-      !parsed.valid ||
-      semanticFingerprint(persisted) !== semanticFingerprint(next)
-    ) throw Error("AGDF_MIGRATION_VERIFICATION_FAILED");
-  } catch (error) {
-    if (existsSync(dest)) unlinkSync(dest);
-    try {
-      rmdirSync(dirname(dest));
-    } catch (cleanupError) {
-      if (!["ENOENT", "ENOTEMPTY"].includes(cleanupError.code)) throw cleanupError;
-    }
-    throw error;
-  }
-  return { status: "migrated", path: dest };
-}
-export function renderLegacyProjection(path, root = process.cwd()) {
-  const content = normalizeLineEndings(readFileSync(path, "utf8")),
-    parsed = parseRunState(content),
-    digest = createHash("sha256").update(content).digest("hex");
-  if (!parsed.valid) throw Error("AGDF_RUN_NOT_SELECTABLE");
-  const canonicalSource = relative(resolve(root), resolve(path)).replaceAll("\\", "/");
-  return `<!-- AGDF LEGACY PROJECTION: NON-AUTHORITATIVE -->\n<!-- canonical_source: ${canonicalSource} -->\n<!-- run_id: ${parsed.meta.run_id} -->\n<!-- revision_id: ${parsed.meta.revision_id} -->\n<!-- sha256: ${digest} -->\n${content}`;
-}
-export function writeLegacyProjection(path, canonical) {
-  atomicWrite(path, renderLegacyProjection(canonical, resolve(dirname(path), "../..")));
-}
-export { verifyLegacyProjection } from "./legacy-projection-reader.js";

package/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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/generated/plugins/agdf/runtime/create-agdf/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) });
-  });
-}