create-agdf 0.20.2 → 0.31.0

package/runtime/core/lib/control-inspect/cockpit-backlog.js

@@ -1,135 +0,0 @@
-import { join } from 'node:path';
-import { createHash } from 'node:crypto';
-import { existsSync, readFileSync } from '../control-read/fs.js';
-import { markdownSection, parseBacklogSection, tableRows, cleanStatusCell, markdownLink, resolvedBacklogLinkTarget } from '../control-evaluation/shared.js';
-import { isSafeControlRelativePath } from '../control-state/contained-file.js';
-import { READ_LIMITS, fail } from '../control-read/snapshot.js';
-import { COCKPIT_BACKLOG_SECTIONS } from './cockpit-list.js';
-import { decodeBacklogMarker, savedBacklogSummary } from '../control-state/backlog-summary.js';
-
-const SOURCE = '.agdf/control/MASTER_BACKLOG.md';
-const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
-const headings = COCKPIT_BACKLOG_SECTIONS;
-const completedHeader = ['key', 'work item', 'status', 'record', 'outcome'];
-const canonicalCompletedHeader = ['key', 'work item', 'final status', 'historical record', 'outcome'];
-
-// A stored pointer projection. It never resolves Runs, evaluates gates or follows links.
-export function projectCockpitBacklog(root) {
-  const path = join(root, SOURCE);
-  if (!existsSync(path)) return { state: 'missing', code: 'backlog_missing', data: null };
-  const bytes = readFileSync(path);
-  if (bytes.length > READ_LIMITS.preview) fail('resource_limit');
-  let source;
-  try { source = decoder.decode(bytes); if (source.includes('\0')) throw Error(); }
-  catch { return { state: 'unsupported', code: 'backlog_unsupported', data: null }; }
-  const entries = [], diagnostics = [], counts = {};
-  const markers = source.split('\n').map(decodeBacklogMarker).filter(Boolean);
-  const diagnostic = (code, section, key = null) => diagnostics.push({ code, path: SOURCE, section, key });
-  for (const section of headings) {
-    const content = markdownSection(source, section), rows = tableRows(content);
-    if (!new RegExp(`^## ${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm').test(source)) {
-      diagnostic('backlog_section_missing', section); counts[section] = 0; continue;
-    }
-    if (!rows.length) { diagnostic('backlog_layout_missing', section); counts[section] = 0; continue; }
-    const completed = section === headings[2];
-    const normalized = rows[0].map(cell => cell.toLowerCase().trim());
-    let pointers = [];
-    if (completed) {
-      if (![completedHeader.join('|'), canonicalCompletedHeader.join('|')].includes(normalized.join('|'))) {
-        diagnostic('backlog_layout_unsupported', section); counts[section] = 0; continue;
-      }
-    } else {
-      const findings = [];
-      pointers = parseBacklogSection(content, findings, SOURCE);
-      diagnostics.push(...findings.map(row => ({ ...row, section })));
-      if (findings.some(row => row.code === 'AGDF_BACKLOG_LAYOUT_UNKNOWN')) { counts[section] = 0; continue; }
-    }
-    const width = rows[0].length;
-    let pointerIndex = 0;
-    for (const cells of rows.slice(1).filter(row => row.some(Boolean))) {
-      const pointer = completed ? null : pointers[pointerIndex++];
-      const compact = width === 7;
-      const key = cleanStatusCell(cells[completed ? 0 : 1] ?? '');
-      const malformed = cells.length !== width || !key || !(cells[completed ? 1 : 2] ?? '').trim();
-      if (malformed) diagnostic('backlog_row_malformed', section, key);
-      const saved_summary = savedBacklogSummary(root, section, cells, markers);
-      if (saved_summary.code) diagnostic(saved_summary.code, section, key);
-      entries.push({ section, key, original_key: cells[completed ? 0 : 1] ?? '',
-        title: cells[completed ? 1 : 2] ?? '', stored_status: cells[completed ? 2 : 3] ?? '',
-        scope: pointer?.scope ?? '', priority: completed ? null : cells[0] ?? '',
-        stored_next_step: completed ? cells[4] ?? '' : cells[compact ? 6 : 12] ?? '',
-        source_links: completed ? cells[3] ?? '' : compact ? cells[4] ?? '' : cells.slice(4, 11).join(' · '),
-        current_spec: completed ? null : cells[compact ? 5 : 11] ?? '',
-        normalized_pointer: pointer, saved_summary,
-        selectable: !malformed && /^[A-Za-z0-9_-]{1,128}$/.test(key) });
-    }
-    counts[section] = entries.filter(row => row.section === section).length;
-  }
-  const seen = new Map();
-  for (const entry of entries) {
-    if (seen.has(entry.key)) {
-      diagnostic('backlog_key_duplicate', entry.section, entry.key);
-      entry.selectable = false; seen.get(entry.key).selectable = false;
-    } else seen.set(entry.key, entry);
-  }
-  return { state: diagnostics.length ? 'partial' : entries.length ? 'available' : 'empty',
-    code: diagnostics.length ? 'backlog_partial' : null,
-    data: { kind: 'backlog', entries, diagnostics, source_path: SOURCE,
-      content_digest: createHash('sha256').update(bytes).digest('hex'), counts } };
-}
-
-export function backlogUrSource(row) {
-  const paths = new Set();
-  for (const match of `${row.source_links} · ${row.current_spec ?? ''}`.matchAll(/\[UR\]\([^)]+\)/gi)) {
-    const link = markdownLink(match[0]);
-    const path = link && resolvedBacklogLinkTarget(link.target);
-    if (!path || /[%#?\0]/.test(link.target) || !isSafeControlRelativePath(path)
-      || !path.startsWith('.agdf/control/artefacts/') || !/\.md$/i.test(path)) return { path: null, code: 'resource_denied' };
-    paths.add(path);
-  }
-  return paths.size === 1 ? { path: [...paths][0], code: null }
-    : { path: null, code: paths.size ? 'ur_link_ambiguous' : 'ur_link_missing' };
-}
-
-// Passive Markdown heading extraction for list presentation only. No evaluator changes.
-export function backlogUrHeading(content) {
-  let fence = null, comment = false, front = false, previous = '';
-  const lines = content.replace(/^\uFEFF/, '').split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    let line = lines[i];
-    if (i === 0 && line.trim() === '---') { front = true; continue; }
-    if (front) { if (/^(---|\.\.\.)\s*$/.test(line)) front = false; continue; }
-    if (comment) { const end = line.indexOf('-->'); if (end < 0) continue; line = line.slice(end + 3); comment = false; }
-    const block = line.match(/^ {0,3}(`{3,}|~{3,})/);
-    if (fence) { if (new RegExp(`^ {0,3}${fence[0]}{${fence.length},}\\s*$`).test(line)) fence = null; continue; }
-    if (block) { fence = block[1]; previous = ''; continue; }
-    while (line.includes('<!--')) {
-      const start = line.indexOf('<!--'), end = line.indexOf('-->', start + 4);
-      if (end < 0) { line = line.slice(0, start); comment = true; previous = ''; break; }
-      line = line.slice(0, start) + line.slice(end + 3);
-    }
-    const atx = line.match(/^ {0,3}#(?:[ \t]+(.*)|$)/);
-    if (atx) return (atx[1] ?? '').replace(/[ \t]+#+[ \t]*$/, '').trim();
-    if (previous && /^ {0,3}=+\s*$/.test(line)) return previous;
-    const paragraph = line.trim() && !/^(?:\s{4}|\t)|^ {0,3}(?:[#>|]|[-+*]\s|\d+[.)]\s|[-*_]{3,}\s*$)/.test(line);
-    previous = paragraph ? (previous ? previous + '\n' : '') + line.trim() : '';
-  }
-  return '';
-}
-
-export function projectBacklogUrTitle(root, view, row, backlogDigest) {
-  const source = backlogUrSource(row);
-  const observation = { state: 'unavailable', code: source.code, path: source.path, heading: null, title: null,
-    content_digest: null, observed_as_of: view.observed_as_of, backlog_digest: backlogDigest };
-  if (!source.path) return observation;
-  const read = view.readOptionalFileSync(join(root, source.path), READ_LIMITS.preview);
-  if (read.code) return { ...observation, code: read.code };
-  let content;
-  try { content = decoder.decode(read.bytes); if (content.includes('\0')) throw Error(); }
-  catch { return { ...observation, code: 'document_unsupported' }; }
-  const heading = backlogUrHeading(content), title = heading.replace(/^UR:\s*/i, '').trim();
-  if (!title) return { ...observation, code: 'ur_heading_missing' };
-  if ([...heading].length > 512 || Buffer.byteLength(heading, 'utf8') > 2048) return { ...observation, code: 'resource_limit' };
-  return { ...observation, state: 'available', code: null, heading, title,
-    content_digest: createHash('sha256').update(read.bytes).digest('hex') };
-}

package/runtime/core/lib/control-maintenance/interaction.js

@@ -1,57 +0,0 @@
-import { interactionLocales } from "../resources/context.js";
-import { localePack } from "../interaction-presentation.js";
-import { renderMaintenanceOffer, renderControlMigrationDecision, renderControlRepairOffer, renderControlRepairPlan } from "./presentation.js";
-
-export async function selectControlMaintenance(control, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_MAINTENANCE_INTERACTION_REQUIRED");
-  const copy = localePack(registry, language).repositoryMaintenance;
-  write(renderMaintenanceOffer(control, { registry, language }));
-  while (true) {
-    let raw;
-    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
-    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (["1", "start"].includes(choice)) return "start";
-    if (["3", "d", "details"].includes(choice)) write(renderMaintenanceOffer(control, { registry, language, details: true }));
-    else write(copy.invalid);
-  }
-}
-
-export async function selectControlMigration(plan, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_MIGRATION_READER_REQUIRED");
-  const copy = localePack(registry, language).installSetup.controlMigration;
-  write(renderControlMigrationDecision(plan, { registry, language }));
-  while (true) {
-    let value;
-    try { value = await readChoice({ prompt: copy.batchPrompt, default: null }); } catch { return "skip"; }
-    const choice = typeof value === "string" ? value.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (["1", "migrate"].includes(choice)) return "migrate";
-    if (["3", "d", "details"].includes(choice)) write(renderControlMigrationDecision(plan, { registry, language, details: true }));
-    else write(copy.invalidChoice);
-  }
-}
-
-export async function selectControlRepair(value, {
-  readChoice, write = () => {}, registry = interactionLocales, language = "en", phase = "offer",
-} = {}) {
-  if (typeof readChoice !== "function") throw new Error("AGDF_CONTROL_REPAIR_READER_REQUIRED");
-  if (!["offer", "plan"].includes(phase)) throw new Error("AGDF_CONTROL_REPAIR_PHASE_INVALID");
-  const copy = localePack(registry, language).installSetup.controlRepair;
-  const render = phase === "offer" ? renderControlRepairOffer : renderControlRepairPlan;
-  write(render(value, { registry, language }));
-  while (true) {
-    let raw;
-    try { raw = await readChoice({ prompt: copy.prompt, default: null }); } catch { return "skip"; }
-    const choice = typeof raw === "string" ? raw.trim().toLowerCase() : "";
-    if (!choice || ["2", "skip", "later"].includes(choice)) return "skip";
-    if (choice === "1" && (phase === "offer" || value.items.some((item) => item.available))) return phase === "offer" ? "start" : "repair";
-    if (["3", "d", "details"].includes(choice)) write(render(value, { registry, language, details: true }));
-    else write(copy.invalidChoice);
-  }
-}
-

package/runtime/core/lib/control-maintenance/migration.js

@@ -1,85 +0,0 @@
-import { join } from "node:path";
-import { regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { applyRunRecovery, inspectRunRecovery, previewRunRecovery } from "../control-state/run-recovery.js";
-import { inspectControlMigration, safeApprovalReset } from "./compatibility.js";
-
-export async function migrateInstallationControl(root, { mode = "inspect", confirmMigration } = {}) {
-  if (!["inspect", "safe"].includes(mode)) throw new Error("AGDF_CONTROL_MIGRATION_MODE_INVALID");
-  const before = inspectControlMigration(root);
-  if (mode === "inspect" || !root) return before;
-  const changes = [];
-  const errors = [];
-  // A structural inventory failure never authorizes a partial migration of an incomplete inventory.
-  if (before.diagnostics.some((finding) => finding.code !== "AGDF_LEGACY_MIGRATION_REQUIRED")) return before;
-  const candidates = before.runs.filter((entry) => entry.status === "migration_required" || entry.pending_recoveries?.length);
-  // Bind the single decision to read-only snapshots. Declining must not even create journals.
-  // The canonical recovery writer still checks each selected revision under its own lock.
-  let selected;
-  if (typeof confirmMigration === "function" && candidates.length) {
-    selected = new Map();
-    for (const run of candidates) {
-      try {
-        if (run.pending_recoveries?.length > 1) throw new Error("AGDF_RECOVERY_JOURNAL_CONFLICT");
-        const pending = run.pending_recoveries?.[0];
-        const journalContent = pending ? regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") : null;
-        const journal = pending ? JSON.parse(journalContent) : null;
-        const inspection = pending ? null : inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-        selected.set(run.run_id, {
-          run_id: run.run_id, pending, journalContent,
-          source_revision_id: journal?.source_revision_id ?? inspection.revision_id,
-          source_content_digest: journal?.source_content_digest ?? inspection.content_digest,
-          source_artefacts: journal?.source_artefacts ?? inspection.artefacts,
-          prior_approvals: journal?.prior_approvals ?? inspection.approvals,
-          next_gate: journal?.next_gate ?? inspection.next_gate_if_recovered,
-        });
-      } catch (error) { errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) }); }
-    }
-    if (selected.size) {
-      const plan = { target: root, control: before, runs: [...selected.values()], diagnostics: errors,
-        approval_reset_count: [...selected.values()].filter((run) => !safeApprovalReset(run.prior_approvals)).length,
-        authorizes: false };
-      if (await confirmMigration(structuredClone(plan)) !== "migrate") return before;
-    }
-  }
-  for (const run of candidates) {
-    if (selected && !selected.has(run.run_id)) continue;
-    if (run.pending_recoveries?.length > 1) { errors.push({ run_id: run.run_id, code: "AGDF_RECOVERY_JOURNAL_CONFLICT" }); continue; }
-    if (run.pending_recoveries?.length) run.safe_to_migrate = safeApprovalReset(run.pending_recoveries[0].prior_approvals ?? []);
-    if (!selected && !run.safe_to_migrate) continue;
-    try {
-      const snapshot = selected?.get(run.run_id);
-      const pending = run.pending_recoveries?.[0];
-      if (snapshot) {
-        if (pending) {
-          if (regularFileSnapshot(join(root, pending.journal)).content.toString("utf8") !== snapshot.journalContent) {
-            throw new Error("AGDF_STALE_RUN_REVISION");
-          }
-        } else {
-          const current = inspectRunRecovery(root, run.run_id, { inspectHistory: false });
-          if (current.revision_id !== snapshot.source_revision_id || current.content_digest !== snapshot.source_content_digest
-              || JSON.stringify(current.artefacts) !== JSON.stringify(snapshot.source_artefacts)) throw new Error("AGDF_STALE_RUN_REVISION");
-        }
-      }
-      const preview = pending ?? previewRunRecovery(root, run.run_id);
-      if (snapshot && !pending && (preview.source_content_digest !== snapshot.source_content_digest
-          || JSON.stringify(preview.source_artefacts) !== JSON.stringify(snapshot.source_artefacts))) throw new Error("AGDF_STALE_RUN_REVISION");
-      // A concurrent approval change must never turn a safe migration into approval invalidation.
-      const journal = JSON.parse(regularFileSnapshot(join(root, preview.journal)).content.toString("utf8"));
-      const safe = safeApprovalReset(journal.prior_approvals);
-      const confirmation = selected || safe ? preview.confirmation : null;
-      if (confirmation !== preview.confirmation) continue;
-      const applied = applyRunRecovery(root, { runId: run.run_id, previewId: preview.preview_id, confirmation });
-      if (applied.seal_status !== "valid" && applied.outcome !== "already_recovered") throw new Error("AGDF_CONTROL_MIGRATION_VERIFICATION_FAILED");
-      changes.push({ run_id: run.run_id, outcome: applied.outcome, revision_id: applied.revision_id,
-        backup: preview.journal, next_gate: preview.next_gate });
-    } catch (error) {
-      errors.push({ run_id: run.run_id, code: String(error.code ?? error.message) });
-    }
-  }
-  const after = inspectControlMigration(root);
-  after.changes = changes;
-  after.diagnostics.push(...errors);
-  if (errors.length) after.status = "repair_required";
-  return after;
-}
-

package/runtime/core/lib/control-maintenance/repair.js

@@ -1,226 +0,0 @@
-import { createHash, randomUUID } from "node:crypto";
-import { lstatSync, mkdirSync, unlinkSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { isSafeControlRelativePath } from "../control-state/contained-file.js";
-import { directoryIdentity, regularFileSnapshot } from "../control-state/run-store-inspection.js";
-import { parseRunState } from "../control-state/run-state-parser.js";
-import { approvalSeal, artefactFileDigest, canonicalRunText, listedArtefactPaths, runSealState } from "../control-state/run-seal.js";
-import { inspectSelfReferenceRecovery } from "../control-state/run-recovery.js";
-import { atomicWrite, unapproveRecoveryApprovals, withRunLock, writeRunLocked, writeRunRecoveryLocked } from "../control-state/run-state-writer.js";
-import { inspectControlMigration } from "./compatibility.js";
-
-const digest = (content) => `sha256:${createHash("sha256").update(content).digest("hex")}`;
-const textDigest = (content) => digest(canonicalRunText(content));
-const pathError = (path) => Object.assign(new Error("AGDF_REPAIR_PATH_INVALID"), { code: "AGDF_REPAIR_PATH_INVALID", path });
-
-function checkedPath(root, relative, { createParents = false } = {}) {
-  if (!isSafeControlRelativePath(relative)) throw pathError(relative);
-  try { directoryIdentity(root); } catch { throw pathError(relative); }
-  let cursor = root;
-  const segments = relative.split("/");
-  for (const segment of segments.slice(0, -1)) {
-    cursor = join(cursor, segment);
-    try { directoryIdentity(cursor); } catch (error) {
-      if (error.code !== "ENOENT") throw pathError(relative);
-      if (!createParents) return null;
-      mkdirSync(cursor, { mode: 0o700 });
-      directoryIdentity(cursor);
-    }
-  }
-  const path = join(root, relative);
-  try {
-    const stat = lstatSync(path);
-    if (stat.isSymbolicLink() || !stat.isFile()) throw pathError(relative);
-  } catch (error) { if (error.code !== "ENOENT") throw error; }
-  return path;
-}
-
-function gitOriginals(root, path, readGitOriginals) {
-  if (!isSafeControlRelativePath(path) || typeof readGitOriginals !== "function") return [];
-  try {
-    const entries = readGitOriginals(root, path);
-    if (!Array.isArray(entries) || entries.length > 9) return [];
-    return entries.filter(entry => entry?.path === path && isSafeControlRelativePath(entry.git_path)
-      && entry.source === "git" && /^[0-9a-f]{40,64}$/u.test(entry.commit)
-      && typeof entry.bytes === "string" && entry.bytes.length <= 3 * 1024 * 1024
-      && entry.digest === textDigest(Buffer.from(entry.bytes, "base64").toString("utf8")));
-  } catch { return []; }
-}
-
-function proposal(root, item, fields) {
-  const proposed = { ...item, ...fields };
-  proposed.artefacts = [...new Set([...item.artefacts.map((artifact) => artifact.path), ...listedArtefactPaths(proposed.candidate_content)])]
-    .map((path) => { checkedPath(root, path); return { path, digest: artefactFileDigest(root, path) }; });
-  return proposed;
-}
-
-function inspectRunRepair(root, run, readGitOriginals) {
-  const relative = `.agdf/control/runs/${run.run_id}/RUN_STATE.md`;
-  const path = checkedPath(root, relative);
-  const content = regularFileSnapshot(path).content.toString("utf8");
-  const parsed = parseRunState(content, run.run_id);
-  const item = { run_id: run.run_id, kind: "manual", available: false, required: [], sources: [],
-    source_content: content, source_digest: digest(content), source_revision_id: parsed.meta.revision_id,
-    candidate_content: null, files: [], artefacts: listedArtefactPaths(content).map((path) => {
-      checkedPath(root, path);
-      return { path, digest: artefactFileDigest(root, path) };
-    }) };
-  if (!parsed.valid || parsed.meta.lifecycle !== "active" || run.pending_recoveries?.length) {
-    item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
-    return item;
-  }
-  const seal = runSealState(root, content);
-  const checkpoint = inspectSelfReferenceRecovery(root, run.run_id);
-  if (checkpoint) {
-    return proposal(root, item, { kind: "self_reference", available: true, candidate_content: checkpoint.content,
-      sources: [{ path: relative, source: "recovery_journal", journal: checkpoint.source }] });
-  }
-  if (seal.status === "content_changed") {
-    const original = gitOriginals(root, relative, readGitOriginals).find((candidate) => {
-      const text = Buffer.from(candidate.bytes, "base64").toString("utf8");
-      const state = parseRunState(text, run.run_id);
-      return state.valid && state.meta.lifecycle === "active" && state.meta.revision_id === parsed.meta.revision_id
-        && runSealState(root, text).status === "valid" && runSealState(root, text).recorded.content_seal === seal.recorded.content_seal && approvalSeal(text) === seal.recorded.approval_seal
-        && listedArtefactPaths(text).every((path) => artefactFileDigest(root, path).startsWith("sha256:"));
-    });
-    if (original) return proposal(root, item, { kind: "run_snapshot", available: true,
-      candidate_content: Buffer.from(original.bytes, "base64").toString("utf8"), sources: [original] });
-  }
-  if (seal.status === "unsealed") {
-    for (const artifact of listedArtefactPaths(content)) {
-      const target = checkedPath(root, artifact);
-      const status = artefactFileDigest(root, artifact);
-      if (!["missing", "unresolved"].includes(status)) continue;
-      // A descriptive placeholder is not a filename; repair never invents paths or evidence.
-      if (!artifact.startsWith(`.agdf/control/artefacts/${run.run_id}/`) || !isSafeControlRelativePath(artifact)) {
-        item.required.push({ code: "AGDF_REPAIR_REFERENCE_REQUIRED", path: artifact });
-        continue;
-      }
-      if (target) {
-        try { lstatSync(target); item.required.push({ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: artifact }); continue; }
-        catch (error) { if (error.code !== "ENOENT") throw error; }
-      }
-      const original = gitOriginals(root, artifact, readGitOriginals)[0];
-      if (original) { item.files.push(original); item.sources.push(original); }
-      else item.required.push({ code: "AGDF_REPAIR_ORIGINAL_REQUIRED", path: artifact });
-    }
-    if (item.files.length && !item.required.length) {
-      item.kind = "missing_artefacts";
-      item.available = true;
-      item.candidate_content = unapproveRecoveryApprovals(content);
-      item.approval_reset = true;
-      return proposal(root, item, {});
-    }
-  }
-  if (!item.required.length) item.required = run.diagnostics.length ? run.diagnostics : [{ code: "AGDF_REPAIR_MANUAL_REQUIRED", path: relative }];
-  return item;
-}
-
-export function inspectControlRepair(root, { readGitOriginals } = {}) {
-  const control = inspectControlMigration(root);
-  const items = [];
-  const diagnostics = [...control.diagnostics];
-  // An incomplete inventory or unsafe scaffold cannot authorize repair writes.
-  if (!diagnostics.length) for (const run of control.runs.filter((entry) => entry.status === "repair_required")) {
-    try { items.push(inspectRunRepair(root, run, readGitOriginals)); } catch (error) {
-      items.push({ run_id: run.run_id, kind: "manual", available: false, files: [], sources: [],
-        required: [{ code: String(error.code ?? error.message), ...(error.path ? { path: error.path } : {}) }] });
-    }
-  }
-  return { target: root, control, items, diagnostics, authorizes: false };
-}
-
-function publicRepair(plan, status) {
-  return { status, target: plan.target, authorizes: false, diagnostics: plan.diagnostics,
-    items: plan.items.map(({ run_id, kind, available, required, sources, outcome, backup }) => ({
-      run_id, kind, available, required,
-      sources: sources.map(({ bytes, ...source }) => source), ...(outcome ? { outcome, backup } : {}),
-    })) };
-}
-
-function applyRunRepair(root, item, hooks = {}, readGitOriginals) {
-  const relative = `.agdf/control/runs/${item.run_id}/RUN_STATE.md`;
-  const path = checkedPath(root, relative);
-  return withRunLock(path, () => {
-    if (regularFileSnapshot(path).content.toString("utf8") !== item.source_content) throw new Error("AGDF_STALE_RUN_REVISION");
-    // Re-read the selected source under the lock; callback mutation and source changes cannot
-    // replace the displayed restoration with another snapshot or a newly found original.
-    const run = inspectControlMigration(root).runs.find((entry) => entry.run_id === item.run_id);
-    if (!run || run.status !== "repair_required") throw new Error("AGDF_STALE_RUN_REVISION");
-    const current = inspectRunRepair(root, run, readGitOriginals);
-    if (JSON.stringify(current) !== JSON.stringify(item)) throw new Error("AGDF_STALE_RUN_REVISION");
-    const directory = join(dirname(path), "repair-previews");
-    try { mkdirSync(directory, { mode: 0o700 }); } catch (error) { if (error.code !== "EEXIST") throw error; }
-    directoryIdentity(directory);
-    if (process.platform !== "win32" && (lstatSync(directory).mode & 0o077)) throw new Error("AGDF_RECOVERY_JOURNAL_PERMISSIONS_INVALID");
-    const id = randomUUID();
-    const journalPath = join(directory, `${id}.json`);
-    const updatedAt = new Date().toISOString();
-    const nextRevisionId = randomUUID();
-    const journal = { schema_version: 1, phase: "prepared", created_at: updatedAt, run_id: item.run_id,
-      source_content: item.source_content, source_digest: item.source_digest, sources: item.sources,
-      files: item.files, candidate_content: item.candidate_content, next_revision_id: nextRevisionId };
-    atomicWrite(journalPath, `${JSON.stringify(journal, null, 2)}\n`);
-    const restored = [];
-    try {
-      for (const file of item.files) {
-        const target = checkedPath(root, file.path, { createParents: true });
-        try { lstatSync(target); throw new Error("AGDF_STALE_RUN_REVISION"); }
-        catch (error) { if (error.code !== "ENOENT") throw error; }
-        atomicWrite(target, Buffer.from(file.bytes, "base64"));
-        restored.push({ ...file, snapshot: regularFileSnapshot(target) });
-      }
-      hooks.beforeRunWrite?.();
-      const options = { expectedContent: item.source_content, expectedRevisionId: item.source_revision_id,
-        nextRevisionId, updatedAt, validateBeforeWrite: () => {
-          checkedPath(root, relative);
-          for (const artifact of item.artefacts) {
-            checkedPath(root, artifact.path);
-            const expected = item.files.find((file) => file.path === artifact.path)?.digest ?? artifact.digest;
-            if (artefactFileDigest(root, artifact.path) !== expected) throw new Error("AGDF_STALE_RUN_REVISION");
-          }
-        } };
-      if (item.kind === "missing_artefacts") writeRunRecoveryLocked(path, item.candidate_content, options);
-      else writeRunLocked(path, item.candidate_content, item.source_revision_id, { ...options, allowContentChange: true });
-      hooks.afterRunWrite?.();
-      const result = regularFileSnapshot(path).content.toString("utf8");
-      if (runSealState(root, result).status !== "valid") throw new Error("AGDF_CONTROL_REPAIR_VERIFICATION_FAILED");
-      atomicWrite(journalPath, `${JSON.stringify({ ...journal, phase: "committed", result_digest: digest(result) }, null, 2)}\n`);
-      return { outcome: "repaired", backup: journalPath.slice(root.length + 1) };
-    } catch (error) {
-      // Roll back only files we created and still own, only while the run was not replaced.
-      // A post-rename interruption retains the complete original snapshot and avoids a second write.
-      if (regularFileSnapshot(path).content.toString("utf8") === item.source_content) for (const file of restored) {
-        const target = checkedPath(root, file.path);
-        if (target) {
-          const current = regularFileSnapshot(target);
-          if (current.dev === file.snapshot.dev && current.ino === file.snapshot.ino
-              && current.content.equals(file.snapshot.content)) unlinkSync(target);
-        }
-      }
-      throw error;
-    }
-  });
-}
-
-export async function repairInstallationControl(control, { chooseRepair, confirmRepair, hooks, readGitOriginals } = {}) {
-  if (control.status !== "repair_required" || typeof chooseRepair !== "function") return control;
-  if (await chooseRepair(structuredClone(control)) !== "start") return control;
-  const plan = inspectControlRepair(control.target, { readGitOriginals });
-  const candidates = plan.items.filter((item) => item.available);
-  let decision = "skip";
-  if (typeof confirmRepair === "function") decision = await confirmRepair(structuredClone(plan));
-  if (decision === "repair") for (const item of candidates) {
-    try { Object.assign(item, applyRunRepair(control.target, item, hooks, readGitOriginals)); }
-    catch (error) { plan.diagnostics.push({ run_id: item.run_id, code: String(error.code ?? error.message) }); }
-  }
-  const after = inspectControlMigration(control.target);
-  after.changes = control.changes;
-  after.repair = publicRepair(plan, !candidates.length ? "needs_input" : decision !== "repair" ? "deferred"
-    : plan.diagnostics.length || after.status !== "current" ? "partial" : "applied");
-  if (plan.diagnostics.length) {
-    after.diagnostics.push(...plan.diagnostics);
-    after.status = "repair_required";
-  }
-  return after;
-}

package/runtime/core/lib/control-state/backlog-summary-shape.d.ts

@@ -1,4 +0,0 @@
-export const BACKLOG_SUMMARY_FIELDS: readonly string[];
-export function validBacklogSummary(value: unknown): boolean;
-
-export function validWorkSummary(value: unknown, runId: string): boolean;

package/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/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";