create-agdf 0.20.1 → 0.30.0

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

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 };
-  });
-}