ai-delivery-workflow 0.2.2 → 0.4.0

package/lib/project-migration.mjs

@@ -0,0 +1,1193 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { atomicWrite, filesUnder, resolveContainedRelativePath } from "./fs-utils.mjs";
+import { readVerifiedHistoryAnchor } from "./history-anchor.mjs";
+import {
+  applyPrototypeMigration,
+  planPrototypeMigration,
+  rollbackPrototypeMigration,
+} from "./prototype-migration.mjs";
+
+const CLOSED_TASK_STATUSES = new Set(["completed", "failed", "abandoned"]);
+const TASK_CONTRACT_FIELDS = [
+  "iteration_id",
+  "node",
+  "skill",
+  "goal",
+  "scope",
+  "responsibility",
+  "depends_on",
+  "acceptance",
+  "planned_outputs",
+  "actual_outputs",
+  "branch",
+  "worktree",
+  "code_repository_id",
+];
+const MIGRATION_FORMAL_STREAMS = new Map([
+  ["workflow-state", { snapshotFile: "workflow-state.yaml", normalize: (value) => value }],
+  ["artifact-registry", { snapshotFile: "artifact-registry.yaml", normalize: (value) => value }],
+]);
+
+function toPosix(value) {
+  return value.replaceAll("\\", "/");
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function treeDigest(root) {
+  const hash = crypto.createHash("sha256");
+  for (const file of filesUnder(root)) {
+    hash.update(toPosix(path.relative(root, file)));
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function readStructured(file, label) {
+  try {
+    const text = fs.readFileSync(file, "utf8");
+    const value = path.extname(file).toLowerCase() === ".json" ? JSON.parse(text) : parseYaml(text);
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      throw new Error("expected a mapping");
+    }
+    return value;
+  } catch (error) {
+    throw new Error(`Cannot read ${label} (${toPosix(file)}): ${error.message}`);
+  }
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function uniqueSorted(values) {
+  return [...new Set((Array.isArray(values) ? values : []).map(String))].sort();
+}
+
+function taskContract(task) {
+  return {
+    iteration_id: task.iteration_id || null,
+    node: task.node || null,
+    skill: task.skill || null,
+    goal: task.goal || null,
+    scope: uniqueSorted(task.scope),
+    responsibility: task.responsibility || task.skill || null,
+    depends_on: uniqueSorted(task.depends_on),
+    acceptance: uniqueSorted(task.acceptance),
+    planned_outputs: uniqueSorted(task.planned_outputs),
+    actual_outputs: uniqueSorted(task.actual_outputs),
+    branch: task.branch || null,
+    worktree: task.worktree || null,
+    code_repository_id: task.code_repository_id || task.repo_id || null,
+  };
+}
+
+function taskRelationships(task, knownIds) {
+  return ["derived_from", "supersedes"]
+    .map((type) => ({ type, task_id: task[type] || null }))
+    .filter((item) => item.task_id && knownIds.has(item.task_id));
+}
+
+function taskFamily(taskId) {
+  let family = String(taskId || "");
+  let previous;
+  do {
+    previous = family;
+    family = family.replace(/[-_.](?:F|R|T|P)\d+$/i, "").replace(/[-_.]v\d+$/i, "");
+  } while (family !== previous);
+  return family || String(taskId || "");
+}
+
+function readTasks(project, workflowRoot) {
+  const sources = [
+    path.join(project, workflowRoot, "control", "tasks"),
+    path.join(project, workflowRoot, "delivery", "runtime", "tasks"),
+  ];
+  const byId = new Map();
+  for (const directory of sources) {
+    for (const file of filesUnder(directory)) {
+      if (!/\.(json|ya?ml)$/i.test(file)) continue;
+      const task = readStructured(file, "migration task");
+      if (!task.task_id) continue;
+      const relative = toPosix(path.relative(project, file));
+      const existing = byId.get(task.task_id);
+      if (!existing || relative.includes("/control/tasks/")) {
+        byId.set(task.task_id, { ...task, source_path: relative });
+      }
+    }
+  }
+  return [...byId.values()].sort((left, right) => String(left.task_id).localeCompare(String(right.task_id)));
+}
+
+function taskGrouping(tasks) {
+  const exact = new Map();
+  const families = new Map();
+  const knownIds = new Set(tasks.map((task) => task.task_id));
+  for (const task of tasks) {
+    const contract = taskContract(task);
+    const signature = sha256(stableJson(contract));
+    if (!exact.has(signature)) exact.set(signature, []);
+    exact.get(signature).push(task);
+    const family = taskFamily(task.task_id);
+    if (!families.has(family)) families.set(family, []);
+    families.get(family).push({ task, contract, signature });
+  }
+  const groups = [...exact.entries()]
+    .filter(([, members]) => members.length > 1)
+    .map(([signature, members]) => ({
+      group_id: `LOGICAL-${signature.slice(0, 16).toUpperCase()}`,
+      confidence: "exact-semantic-contract",
+      source_task_ids: members.map((task) => task.task_id).sort(),
+      status_policy: "preserve-source-facts",
+      contract_checksum: signature,
+      relationship_edges: members.flatMap((task) => taskRelationships(task, knownIds)
+        .map((relationship) => ({
+          source_task_id: task.task_id,
+          ...relationship,
+        }))),
+    }))
+    .sort((left, right) => left.group_id.localeCompare(right.group_id));
+  const ambiguities = [];
+  for (const [family, members] of families) {
+    if (members.length < 2 || new Set(members.map((item) => item.signature)).size < 2) continue;
+    const differingFields = TASK_CONTRACT_FIELDS.filter((field) =>
+      new Set(members.map((item) => stableJson(item.contract[field]))).size > 1);
+    ambiguities.push({
+      family,
+      source_task_ids: members.map((item) => item.task.task_id).sort(),
+      differing_fields: differingFields,
+      relationship_edges: members.flatMap((item) => taskRelationships(item.task, knownIds)
+        .map((relationship) => ({
+          source_task_id: item.task.task_id,
+          ...relationship,
+        }))),
+      decision_required: true,
+      suffixes_are_semantic: false,
+    });
+  }
+  ambiguities.sort((left, right) => left.family.localeCompare(right.family));
+  return {
+    strategy: "semantic-contract-v1",
+    source_task_count: tasks.length,
+    proposed_logical_task_count: tasks.length - groups.reduce((total, group) =>
+      total + group.source_task_ids.length - 1, 0),
+    groups,
+    ambiguities,
+    unresolved_ambiguities: ambiguities,
+    decisions: [],
+  };
+}
+
+function groupingDecisionTemplate(sourceChecksum, ambiguities) {
+  return {
+    schema_version: 1,
+    source_checksum: sourceChecksum,
+    actor: "human:<identity>",
+    decisions: ambiguities.map((ambiguity) => ({
+      family: ambiguity.family,
+      action: "keep-separate",
+      source_task_ids: ambiguity.source_task_ids,
+      rationale: "<why these source tasks are separate or one logical task>",
+    })),
+  };
+}
+
+function applyGroupingDecisions(grouping, tasks, decisionsFile, sourceChecksum) {
+  const result = {
+    ...grouping,
+    groups: grouping.groups.map((group) => ({ ...group })),
+    ambiguities: grouping.ambiguities.map((ambiguity) => ({ ...ambiguity })),
+    unresolved_ambiguities: grouping.ambiguities.map((ambiguity) => ({ ...ambiguity })),
+    decisions: [],
+    decision_template: groupingDecisionTemplate(sourceChecksum, grouping.ambiguities),
+  };
+  if (!decisionsFile) return result;
+  const absolute = path.resolve(decisionsFile);
+  const document = readStructured(absolute, "migration grouping decisions");
+  if (document.schema_version !== 1 || document.source_checksum !== sourceChecksum) {
+    throw new Error("Migration grouping decisions do not match the current source checksum.");
+  }
+  const actor = String(document.actor || "").trim();
+  if (!actor.startsWith("human:")) {
+    throw new Error("Migration grouping decisions require actor human:<identity>.");
+  }
+  if (!Array.isArray(document.decisions)) {
+    throw new Error("Migration grouping decisions must contain a decisions list.");
+  }
+  const decisionByFamily = new Map();
+  for (const decision of document.decisions) {
+    const family = String(decision?.family || "");
+    if (!family || decisionByFamily.has(family)) {
+      throw new Error(`Migration grouping decision family is missing or duplicated: ${family || "missing"}.`);
+    }
+    decisionByFamily.set(family, decision);
+  }
+  const tasksById = new Map(tasks.map((task) => [task.task_id, task]));
+  for (const ambiguity of grouping.ambiguities) {
+    const decision = decisionByFamily.get(ambiguity.family);
+    if (!decision) continue;
+    const sourceTaskIds = uniqueSorted(decision.source_task_ids);
+    if (stableJson(sourceTaskIds) !== stableJson(ambiguity.source_task_ids)) {
+      throw new Error(`Migration grouping decision source tasks changed for ${ambiguity.family}.`);
+    }
+    const action = String(decision.action || "");
+    if (!new Set(["keep-separate", "group"]).has(action)) {
+      throw new Error(`Migration grouping decision action is invalid for ${ambiguity.family}.`);
+    }
+    const rationale = String(decision.rationale || "").trim();
+    if (!rationale) throw new Error(`Migration grouping decision requires rationale for ${ambiguity.family}.`);
+    const normalized = { family: ambiguity.family, action, source_task_ids: sourceTaskIds, actor, rationale };
+    if (action === "group") {
+      const canonicalSourceTaskId = String(decision.canonical_source_task_id || "");
+      if (!sourceTaskIds.includes(canonicalSourceTaskId)) {
+        throw new Error(`Grouped family ${ambiguity.family} requires canonical_source_task_id from source_task_ids.`);
+      }
+      const logicalTaskId = String(decision.logical_task_id || ambiguity.family);
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(logicalTaskId)) {
+        throw new Error(`Grouped family ${ambiguity.family} has an invalid logical_task_id.`);
+      }
+      result.groups = result.groups.filter((group) =>
+        !group.source_task_ids.some((taskId) => sourceTaskIds.includes(taskId)));
+      result.groups.push({
+        group_id: logicalTaskId,
+        confidence: "human-confirmed",
+        source_task_ids: sourceTaskIds,
+        canonical_source_task_id: canonicalSourceTaskId,
+        status_policy: "preserve-source-facts",
+        contract_checksum: sha256(stableJson(taskContract(tasksById.get(canonicalSourceTaskId)))),
+        relationship_edges: ambiguity.relationship_edges,
+      });
+      normalized.logical_task_id = logicalTaskId;
+      normalized.canonical_source_task_id = canonicalSourceTaskId;
+    }
+    result.decisions.push(normalized);
+    result.ambiguities = result.ambiguities.map((item) => item.family === ambiguity.family
+      ? { ...item, decision_required: false, resolution: normalized }
+      : item);
+  }
+  for (const family of decisionByFamily.keys()) {
+    if (!grouping.ambiguities.some((ambiguity) => ambiguity.family === family)) {
+      throw new Error(`Migration grouping decision does not match an ambiguity: ${family}.`);
+    }
+  }
+  result.groups.sort((left, right) => left.group_id.localeCompare(right.group_id));
+  result.decisions.sort((left, right) => left.family.localeCompare(right.family));
+  const resolved = new Set(result.decisions.map((decision) => decision.family));
+  result.unresolved_ambiguities = grouping.ambiguities.filter((ambiguity) => !resolved.has(ambiguity.family));
+  result.decision_source = {
+    path: toPosix(absolute),
+    sha256: sha256(fs.readFileSync(absolute)),
+  };
+  return result;
+}
+
+function yamlEventFormat(bytes) {
+  const text = bytes.toString("utf8");
+  const schemaVersion = text.match(/^schema_version:[ \t]*([^\r\n#]+)/m)?.[1]?.trim();
+  const afterValue = text.match(/^after_value:[ \t]*([^\r\n#]*)/m)?.[1]?.trim();
+  const operations = text.match(/^operations:[ \t]*([^\r\n#]*)/m)?.[1]?.trim();
+  return {
+    legacySnapshot: afterValue !== undefined
+      && !new Set(["null", "~", "false", "0", "''", '\"\"']).has(afterValue),
+    delta: schemaVersion === "2"
+      && operations !== undefined
+      && (operations === "" || operations.startsWith("[")),
+  };
+}
+
+function eventFormat(file, bytes) {
+  if (path.extname(file).toLowerCase() !== ".json") return yamlEventFormat(bytes);
+  const record = JSON.parse(bytes.toString("utf8"));
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    throw new Error(`Cannot read formal event (${toPosix(file)}): expected a mapping`);
+  }
+  return {
+    legacySnapshot: Boolean(record.after_value),
+    delta: record.schema_version === 2 && Array.isArray(record.operations),
+  };
+}
+
+function fileSha256(file, checksumCache) {
+  const cached = checksumCache?.get(path.resolve(file));
+  if (cached) return cached;
+  const checksum = sha256(fs.readFileSync(file));
+  checksumCache?.set(path.resolve(file), checksum);
+  return checksum;
+}
+
+function eventFormats(project, workflowRoot, checksumCache = null) {
+  const eventRoot = path.join(project, workflowRoot, "control", "events");
+  let legacySnapshots = 0;
+  let deltas = 0;
+  const deltaHash = crypto.createHash("sha256");
+  const treeHash = crypto.createHash("sha256");
+  for (const file of filesUnder(eventRoot)) {
+    const bytes = fs.readFileSync(file);
+    const relative = toPosix(path.relative(eventRoot, file));
+    checksumCache?.set(path.resolve(file), sha256(bytes));
+    treeHash.update(relative);
+    treeHash.update("\0");
+    treeHash.update(bytes);
+    treeHash.update("\0");
+    if (!/\.(json|ya?ml)$/i.test(file)) continue;
+    const format = eventFormat(file, bytes);
+    if (format.legacySnapshot) legacySnapshots += 1;
+    if (format.delta) {
+      deltas += 1;
+      deltaHash.update(relative);
+      deltaHash.update("\0");
+      deltaHash.update(bytes);
+      deltaHash.update("\0");
+    }
+  }
+  return {
+    legacySnapshots,
+    deltas,
+    fingerprint: treeHash.digest("hex"),
+    deltaFingerprint: deltaHash.digest("hex"),
+  };
+}
+
+function trustedAnchors(project, workflowRoot) {
+  const verified = readVerifiedHistoryAnchor({
+    historySnapshots: path.join(
+      project, workflowRoot, "control", "snapshots", "formal-state",
+    ),
+    events: path.join(project, workflowRoot, "delivery", "state-events.jsonl"),
+    streams: MIGRATION_FORMAL_STREAMS,
+    readStructured,
+    stringify: (value) => stringifyYaml(value, { lineWidth: 0 }),
+  });
+  if (!verified) return [];
+  const { anchor, anchorFile, pointer, pointerFile, snapshotFiles } = verified;
+  return [{
+    anchor_id: anchor.anchor_id,
+    anchor_checksum: pointer.anchor_checksum,
+    pointer_path: toPosix(path.relative(project, pointerFile)),
+    anchor_path: toPosix(path.relative(project, anchorFile)),
+    snapshots: [...MIGRATION_FORMAL_STREAMS.keys()].map((stream) => ({
+      stream,
+      path: toPosix(path.relative(project, snapshotFiles[stream])),
+      revision: anchor.streams[stream].revision,
+      sha256: anchor.streams[stream].view_checksum,
+    })),
+    verified: true,
+  }];
+}
+
+function archiveConflicts(project, workflowRoot, tasks) {
+  const archiveRoot = path.join(project, workflowRoot, "control", "archives", "versions");
+  const byIteration = new Map();
+  for (const task of tasks) {
+    if (!task.iteration_id) continue;
+    if (!byIteration.has(task.iteration_id)) byIteration.set(task.iteration_id, []);
+    byIteration.get(task.iteration_id).push(task);
+  }
+  const invalidated = verifiedArchiveInvalidations(project, readRepairTransactions(project));
+  const conflicts = [];
+  const manifestFiles = fs.existsSync(archiveRoot)
+    ? fs.readdirSync(archiveRoot, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => path.join(archiveRoot, entry.name, "version-manifest.json"))
+      .filter((file) => fs.existsSync(file) && fs.statSync(file).isFile())
+      .sort((left, right) => left.localeCompare(right))
+    : [];
+  for (const file of manifestFiles) {
+    const manifest = readStructured(file, "version archive manifest");
+    if (invalidated.has(manifest.iteration_id)) continue;
+    const activeStoreTasks = byIteration.get(manifest.iteration_id) || [];
+    if (!activeStoreTasks.length) continue;
+    conflicts.push({
+      type: "archive-active-task-conflict",
+      iteration_id: manifest.iteration_id,
+      archive_path: toPosix(path.relative(project, file)),
+      archive_status: manifest.version_status || null,
+      source_task_ids: activeStoreTasks.map((task) => task.task_id).sort(),
+      retryable_task_ids: activeStoreTasks
+        .filter((task) => task.status === "failed")
+        .map((task) => task.task_id)
+        .sort(),
+      decision_required: true,
+    });
+  }
+  return conflicts.sort((left, right) => left.iteration_id.localeCompare(right.iteration_id));
+}
+
+function unsignedRepairRecord(record) {
+  const unsigned = { ...record };
+  delete unsigned.record_checksum;
+  return unsigned;
+}
+
+function readRepairTransactions(project) {
+  const directory = path.join(project, ".workflow", "control", "repairs", "transactions");
+  const records = [];
+  let previousChecksum = null;
+  for (const file of filesUnder(directory).filter((item) => item.endsWith(".json"))) {
+    const record = readStructured(file, "repair transaction");
+    if (record.schema_version !== 1
+      || !Number.isInteger(record.sequence)
+      || record.sequence !== records.length + 1
+      || record.previous_checksum !== previousChecksum
+      || record.record_checksum !== sha256(stableJson(unsignedRepairRecord(record)))) {
+      throw new Error(`Repair transaction chain is invalid: ${toPosix(path.relative(project, file))}.`);
+    }
+    records.push(record);
+    previousChecksum = record.record_checksum;
+  }
+  return records;
+}
+
+function verifiedArchiveInvalidations(project, records) {
+  const invalidated = new Set();
+  for (const record of records.filter((item) => item.transaction_type === "archive-invalidation")) {
+    const iterationId = archiveIterationId(record.target?.iteration_id);
+    const expectedArchivePath = `.workflow/control/archives/versions/${iterationId}`;
+    const expectedManifestPath = `${expectedArchivePath}/version-manifest.json`;
+    if (record.target.archive_path !== expectedArchivePath
+      || record.target.manifest_path !== expectedManifestPath
+      || !/^[a-f0-9]{64}$/.test(record.target.archive_sha256 || "")
+      || !/^[a-f0-9]{64}$/.test(record.target.manifest_sha256 || "")) {
+      throw new Error(`Archive invalidation target is invalid: ${record.transaction_id}.`);
+    }
+    const archiveDirectory = path.join(project, ...expectedArchivePath.split("/"));
+    const manifestFile = path.join(project, ...expectedManifestPath.split("/"));
+    if (!fs.existsSync(manifestFile)
+      || treeDigest(archiveDirectory) !== record.target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== record.target.manifest_sha256) {
+      throw new Error(`Invalidated archive ${iterationId} bytes changed after ${record.transaction_id}.`);
+    }
+    invalidated.add(iterationId);
+  }
+  return invalidated;
+}
+
+function repairTransactionPath(sequence, transactionId) {
+  return `.workflow/control/repairs/transactions/${String(sequence).padStart(6, "0")}-${transactionId}.json`;
+}
+
+function archiveIterationId(value) {
+  const iterationId = String(value || "");
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(iterationId)) {
+    throw new Error(`Invalid archive iteration ID: ${iterationId || "missing"}.`);
+  }
+  return iterationId;
+}
+
+function detectLayout(project) {
+  const currentState = path.join(project, ".workflow", "delivery", "workflow-state.yaml");
+  const legacyState = path.join(project, "delivery", "workflow-state.yaml");
+  const current = fs.existsSync(currentState);
+  const legacy = fs.existsSync(legacyState);
+  if (current && legacy) {
+    return {
+      root: ".workflow",
+      roots: [".workflow", "."],
+      source: "current-workflow-root",
+      conflicts: [{
+        type: "split-workflow-layout",
+        current_state_path: ".workflow/delivery/workflow-state.yaml",
+        legacy_state_path: "delivery/workflow-state.yaml",
+        decision_required: true,
+      }],
+    };
+  }
+  if (current) return { root: ".workflow", roots: [".workflow"], source: "current-workflow-root", conflicts: [] };
+  if (legacy) return { root: ".", roots: ["."], source: "legacy-project-root", conflicts: [] };
+  throw new Error("Cannot locate workflow-state.yaml in .workflow/delivery or legacy delivery layout.");
+}
+
+function migrationSourceFiles(project, workflowRoot) {
+  const workflowBase = path.join(project, workflowRoot);
+  const deliveryRoot = path.join(workflowBase, "delivery");
+  const controlRoot = path.join(workflowBase, "control");
+  const files = [
+    ...filesUnderExcluding(deliveryRoot, [path.join(deliveryRoot, "runtime")]),
+    ...filesUnder(path.join(deliveryRoot, "runtime", "tasks")),
+    ...filesUnderExcluding(controlRoot, [
+      path.join(controlRoot, "migrations"),
+      ...(workflowRoot === ".workflow" ? [path.join(controlRoot, "archives")] : []),
+    ]),
+    ...filesUnder(path.join(workflowBase, "standards")),
+  ];
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function filesUnderExcluding(root, excludedDirectories) {
+  if (!fs.existsSync(root)) return [];
+  const excluded = new Set(excludedDirectories.map((directory) => path.resolve(directory)));
+  const files = [];
+  const visit = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+      const absolute = path.join(directory, entry.name);
+      if (entry.isDirectory()) {
+        if (!excluded.has(path.resolve(absolute))) visit(absolute);
+      } else if (entry.isFile()) {
+        files.push(absolute);
+      }
+    }
+  };
+  visit(root);
+  return files.sort((left, right) => left.localeCompare(right));
+}
+
+function projectedAttemptStatus(status) {
+  return new Map([
+    ["completed", "completed"],
+    ["failed", "failed"],
+    ["abandoned", "abandoned"],
+    ["blocked", "paused"],
+    ["interrupted", "paused"],
+  ]).get(status) || "active";
+}
+
+function taskWithExplicitAttempts(task) {
+  if (Array.isArray(task.attempts)) return task;
+  const legacyNumber = Number(task.attempt || 0);
+  const attempts = legacyNumber > 0 && (task.started_at || task.status !== "queued")
+    ? [{
+      attempt_id: `${task.task_id}/A${legacyNumber}`,
+      number: legacyNumber,
+      status: projectedAttemptStatus(task.status),
+      started_at: task.started_at || task.created_at || null,
+      finished_at: CLOSED_TASK_STATUSES.has(task.status)
+        ? task.finished_at || task.updated_at || null
+        : null,
+      phases: [],
+      time_entries: [],
+      time_by_category: {},
+    }]
+    : [];
+  return { ...task, attempts };
+}
+
+function migratedTaskBytes(file) {
+  const task = readStructured(file, "legacy migration task");
+  return Buffer.from(`${JSON.stringify(taskWithExplicitAttempts(task), null, 2)}\n`, "utf8");
+}
+
+function isTaskStatePath(relative) {
+  return relative.startsWith("control/tasks/") || relative.startsWith("delivery/runtime/tasks/");
+}
+
+function plannedFileChanges(root, layout, migrationId) {
+  const copies = [];
+  const replacements = [];
+  const conflicts = [];
+  if (layout.source === "legacy-project-root") {
+    const mappings = migrationSourceFiles(root, ".").map((source) => ({
+      source,
+      source_path: toPosix(path.relative(root, source)),
+      target_path: `.workflow/${toPosix(path.relative(root, source))}`,
+    }));
+    for (const [sourcePath, targetPath] of [
+      [".ai-delivery/workspace.yaml", ".workflow/config/workspace.yaml"],
+      [".ai-delivery/install-manifest.json", ".workflow/config/install-manifest.json"],
+    ]) {
+      const source = path.join(root, ...sourcePath.split("/"));
+      if (fs.existsSync(source)) mappings.push({ source, source_path: sourcePath, target_path: targetPath });
+    }
+    for (const mapping of mappings) {
+      const sourceBytes = fs.readFileSync(mapping.source);
+      const logicalPath = mapping.source_path.replace(/^(?:\.workflow\/)?/, "");
+      const targetBytes = isTaskStatePath(logicalPath) ? migratedTaskBytes(mapping.source) : sourceBytes;
+      const target = path.join(root, ...mapping.target_path.split("/"));
+      if (fs.existsSync(target)) {
+        if (!fs.readFileSync(target).equals(targetBytes)) {
+          conflicts.push({
+            type: "migration-target-conflict",
+            source_path: mapping.source_path,
+            target_path: mapping.target_path,
+            decision_required: true,
+          });
+        }
+        continue;
+      }
+      copies.push({
+        source_path: mapping.source_path,
+        target_path: mapping.target_path,
+        source_sha256: sha256(sourceBytes),
+        target_sha256: sha256(targetBytes),
+        transformation: isTaskStatePath(logicalPath) ? "add-explicit-attempts" : "byte-for-byte",
+      });
+    }
+  } else {
+    const taskRoots = [
+      path.join(root, ".workflow", "control", "tasks"),
+      path.join(root, ".workflow", "delivery", "runtime", "tasks"),
+    ];
+    for (const file of taskRoots.flatMap(filesUnder).filter((item) => /\.(json|ya?ml)$/i.test(item))) {
+      const before = fs.readFileSync(file);
+      const after = migratedTaskBytes(file);
+      if (before.equals(after)) continue;
+      const relative = toPosix(path.relative(root, file));
+      const backupPath = `.workflow/control/migrations/${migrationId}/backups/${relative.replace(/^\.workflow\//, "")}`;
+      replacements.push({
+        path: relative,
+        backup_path: backupPath,
+        before_sha256: sha256(before),
+        after_sha256: sha256(after),
+        transformation: "add-explicit-attempts",
+      });
+    }
+  }
+  return { copies, replacements, conflicts };
+}
+
+function planMigration(project, options = {}) {
+  const root = path.resolve(project);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const layout = detectLayout(root);
+  const workflowState = readStructured(
+    path.join(root, layout.root, "delivery", "workflow-state.yaml"),
+    "workflow state",
+  );
+  const artifactRegistry = readStructured(
+    path.join(root, layout.root, "delivery", "artifact-registry.yaml"),
+    "artifact registry",
+  );
+  const tasks = readTasks(root, layout.root);
+  const initialGrouping = taskGrouping(tasks);
+  const sourceChecksums = new Map();
+  const events = eventFormats(root, layout.root, sourceChecksums);
+  const anchors = layout.roots.flatMap((workflowRoot) => trustedAnchors(root, workflowRoot));
+  const repairFingerprint = treeDigest(
+    path.join(root, layout.root, "control", "repairs", "transactions"),
+  );
+  const legacyConfigSources = layout.source === "legacy-project-root"
+    ? [".ai-delivery/workspace.yaml", ".ai-delivery/install-manifest.json"]
+      .map((relative) => path.join(root, ...relative.split("/")))
+      .filter((file) => fs.existsSync(file))
+    : [];
+  const initialPrototypeMigration = planPrototypeMigration(root);
+  const sourceFiles = [...new Set([
+    ...layout.roots.flatMap((workflowRoot) => migrationSourceFiles(root, workflowRoot)),
+    ...legacyConfigSources,
+    ...initialPrototypeMigration.preserved_sources.map((item) =>
+      path.join(root, ...item.path.split("/"))),
+  ].map((file) => path.resolve(file)))]
+    .sort((left, right) => left.localeCompare(right));
+  const conflicts = [...layout.conflicts, ...archiveConflicts(root, layout.root, tasks)];
+  const sourceDigest = sha256(stableJson({
+    layout: layout.source,
+    roots: layout.roots,
+    sources: sourceFiles.map((file) => ({
+      path: toPosix(path.relative(root, file)),
+      sha256: fileSha256(file, sourceChecksums),
+    })),
+  }));
+  const migrationId = `MIG-${sourceDigest.slice(0, 16).toUpperCase()}`;
+  const manifestPath = `.workflow/control/migrations/${migrationId}/migration-manifest.json`;
+  const grouping = applyGroupingDecisions(initialGrouping, tasks, options.decisions, sourceDigest);
+  const prototypeMigration = planPrototypeMigration(root, {
+    decisionsFile: options.decisions,
+    sourceChecksum: sourceDigest,
+  });
+  const changes = plannedFileChanges(root, layout, migrationId);
+  conflicts.push(...changes.conflicts);
+  const preservedSourcePaths = sourceFiles;
+  return {
+    command: "migrate",
+    dry_run: true,
+    applied: false,
+    migration_id: migrationId,
+    schemas: {
+      workspace_layout: {
+        source: layout.source,
+        target: "current-workflow-root",
+        action: layout.source === "current-workflow-root" ? "preserve" : "copy-preserve-source",
+      },
+      formal_state: {
+        workflow_state: workflowState.schema_version ?? null,
+        artifact_registry: artifactRegistry.schema_version ?? null,
+        legacy_snapshot_events: events.legacySnapshots,
+        delta_events: events.deltas,
+        target_event_schema: 2,
+        action: "preserve-legacy-base-and-append-deltas",
+      },
+      task_state: {
+        source: tasks.some((task) => !Array.isArray(task.attempts))
+          ? "legacy-flat-tasks"
+          : "logical-task-groups-with-attempts",
+        target: "logical-task-groups-with-attempts",
+        action: "add-explicit-attempts-and-record-semantic-grouping-without-lifecycle-mutation",
+      },
+      prototype_state: {
+        source: "legacy-prototype-set-members",
+        target: "single-prototype",
+        action: prototypeMigration.status,
+      },
+    },
+    task_grouping: grouping,
+    prototype_migration: prototypeMigration,
+    conflicts,
+    anchors: {
+      trusted: anchors,
+      proposed: {
+        kind: "migration-baseline",
+        source_checksum: sourceDigest,
+        preserves_legacy_history: true,
+      },
+    },
+    file_changes: {
+      additions: [{ path: manifestPath, kind: "migration-manifest" }],
+      copies: changes.copies,
+      replacements: changes.replacements,
+      preserved: [
+        { path: `${layout.root === "." ? "" : `${layout.root}/`}delivery/workflow-state.yaml`, reason: "business state is immutable during structural migration" },
+        { path: `${layout.root === "." ? "" : `${layout.root}/`}delivery/artifact-registry.yaml`, reason: "formal artifact semantics are preserved" },
+        { path: `${layout.root === "." ? "" : `${layout.root}/`}control/events`, reason: "legacy event history remains in place" },
+      ],
+      conflicts: changes.conflicts,
+    },
+    business_state: {
+      completion_inferred: false,
+      tasks_activated: [],
+      tasks_closed: [],
+      scope_changed: false,
+    },
+    can_apply: conflicts.length === 0 && grouping.unresolved_ambiguities.length === 0
+      && prototypeMigration.can_apply,
+    forward_state: {
+      source_workflow_root: layout.root,
+      transaction_workflow_root: ".workflow",
+      new_format_event_fingerprint: events.deltaFingerprint,
+      repair_transaction_fingerprint: repairFingerprint,
+    },
+    preserved_sources: [...new Set(preservedSourcePaths.map((file) => path.resolve(file)))]
+      .sort((left, right) => left.localeCompare(right))
+      .map((file) => ({
+        path: toPosix(path.relative(root, file)),
+        sha256: fileSha256(file, sourceChecksums),
+      })),
+  };
+}
+
+function appliedMigration(root) {
+  const directory = path.join(root, ".workflow", "control", "migrations");
+  const manifests = filesUnder(directory)
+    .filter((file) => path.basename(file) === "migration-manifest.json")
+    .sort((left, right) => left.localeCompare(right));
+  const found = [];
+  for (const file of manifests) {
+    const manifest = readStructured(file, "applied migration manifest");
+    if (!new Set([1, 2, 3]).has(manifest.schema_version) || manifest.status !== "applied"
+      || manifest.record_checksum !== sha256(stableJson(unsignedMigrationManifest(manifest)))) {
+      throw new Error(`Applied migration manifest is invalid: ${toPosix(path.relative(root, file))}.`);
+    }
+    found.push({ manifest, path: toPosix(path.relative(root, file)) });
+  }
+  found.sort((left, right) =>
+    Number(right.manifest.schema_version) - Number(left.manifest.schema_version)
+      || String(right.manifest.applied_at || "").localeCompare(String(left.manifest.applied_at || ""))
+      || right.path.localeCompare(left.path));
+  return found[0] || null;
+}
+
+function reportFromManifest(found, dryRun) {
+  const { manifest } = found;
+  return {
+    command: "migrate",
+    dry_run: Boolean(dryRun),
+    applied: false,
+    migration_id: manifest.migration_id,
+    schemas: manifest.schemas,
+    task_grouping: manifest.task_grouping,
+    prototype_migration: manifest.prototype_migration || null,
+    conflicts: manifest.conflicts,
+    anchors: manifest.anchors,
+    file_changes: manifest.file_changes || { additions: [], copies: [], replacements: [], preserved: [], conflicts: [] },
+    business_state: manifest.business_state,
+    can_apply: true,
+    forward_state: manifest.forward_state,
+    preserved_sources: manifest.preserved_sources,
+    manifest_path: found.path,
+    already_applied: true,
+  };
+}
+
+function migrationTargetForSource(sourcePath) {
+  if (sourcePath === ".ai-delivery/workspace.yaml") return ".workflow/config/workspace.yaml";
+  if (sourcePath === ".ai-delivery/install-manifest.json") {
+    return ".workflow/config/install-manifest.json";
+  }
+  if (sourcePath.startsWith("control/migrations/")) return null;
+  if (["delivery", "control", "standards"].some((prefix) =>
+    sourcePath.startsWith(`${prefix}/`))) return `.workflow/${sourcePath}`;
+  return null;
+}
+
+function validatedMigrationOperations(root, manifest, migrationId) {
+  const fileChanges = manifest.file_changes;
+  if (!fileChanges || !Array.isArray(fileChanges.copies) || !Array.isArray(fileChanges.replacements)) {
+    throw new Error(`Migration ${migrationId} file changes are invalid.`);
+  }
+  const targetPaths = new Set();
+  const copies = fileChanges.copies.map((copy) => {
+    const expectedTarget = migrationTargetForSource(String(copy.source_path || ""));
+    if (!expectedTarget || copy.target_path !== expectedTarget
+      || !new Set(["byte-for-byte", "add-explicit-attempts"]).has(copy.transformation)
+      || !/^[a-f0-9]{64}$/.test(copy.source_sha256 || "")
+      || !/^[a-f0-9]{64}$/.test(copy.target_sha256 || "")) {
+      throw new Error(`Migration copy path or checksum is invalid: ${copy.source_path || "missing"}.`);
+    }
+    const source = resolveContainedRelativePath(root, copy.source_path, [
+      "delivery", "control", "standards",
+      ".ai-delivery/workspace.yaml", ".ai-delivery/install-manifest.json",
+    ]);
+    const target = resolveContainedRelativePath(root, copy.target_path, [".workflow"]);
+    if (!fs.existsSync(source) || sha256(fs.readFileSync(source)) !== copy.source_sha256) {
+      throw new Error(`Migration preserved source changed after ${migrationId}: ${copy.source_path}.`);
+    }
+    if (targetPaths.has(copy.target_path)) {
+      throw new Error(`Migration target path is duplicated: ${copy.target_path}.`);
+    }
+    targetPaths.add(copy.target_path);
+    return { ...copy, source, target };
+  });
+  const replacements = fileChanges.replacements.map((replacement) => {
+    const replacementPath = String(replacement.path || "");
+    const expectedBackup = `.workflow/control/migrations/${migrationId}/backups/${replacementPath.replace(/^\.workflow\//, "")}`;
+    if (replacement.backup_path !== expectedBackup
+      || replacement.transformation !== "add-explicit-attempts"
+      || !/^[a-f0-9]{64}$/.test(replacement.before_sha256 || "")
+      || !/^[a-f0-9]{64}$/.test(replacement.after_sha256 || "")) {
+      throw new Error(`Migration replacement path or checksum is invalid: ${replacementPath || "missing"}.`);
+    }
+    const target = resolveContainedRelativePath(root, replacementPath, [
+      ".workflow/control/tasks", ".workflow/delivery/runtime/tasks",
+    ]);
+    const backup = resolveContainedRelativePath(root, replacement.backup_path, [
+      `.workflow/control/migrations/${migrationId}/backups`,
+    ]);
+    if (targetPaths.has(replacementPath)) {
+      throw new Error(`Migration target path is duplicated: ${replacementPath}.`);
+    }
+    targetPaths.add(replacementPath);
+    return { ...replacement, target, backup };
+  });
+  return { copies, replacements };
+}
+
+function rollbackMigration(project, migrationId) {
+  const root = path.resolve(project);
+  const id = String(migrationId || "");
+  if (!/^MIG-[A-F0-9]{16}$/.test(id)) throw new Error(`Invalid migration rollback identifier: ${id || "missing"}.`);
+  const migrationDirectory = path.join(root, ".workflow", "control", "migrations", id);
+  const manifestFile = path.join(migrationDirectory, "migration-manifest.json");
+  const manifest = readStructured(manifestFile, "migration rollback manifest");
+  if (!new Set([1, 2, 3]).has(manifest.schema_version)
+    || manifest.migration_id !== id || manifest.status !== "applied") {
+    throw new Error(`Migration ${id} is not in an applied rollback state.`);
+  }
+  if (manifest.record_checksum !== sha256(stableJson(unsignedMigrationManifest(manifest)))) {
+    throw new Error(`Migration ${id} manifest checksum is invalid.`);
+  }
+  const operations = manifest.schema_version >= 2
+    ? validatedMigrationOperations(root, manifest, id)
+    : { copies: [], replacements: [] };
+  const transactionWorkflowRoot = manifest.forward_state?.transaction_workflow_root
+    || manifest.forward_state?.source_workflow_root;
+  if (!new Set([".", ".workflow"]).has(transactionWorkflowRoot)) {
+    throw new Error(`Migration ${id} does not contain a compatible rollback boundary.`);
+  }
+  const currentEvents = eventFormats(root, transactionWorkflowRoot);
+  const currentRepairs = treeDigest(path.join(
+    root, ".workflow", "control", "repairs", "transactions",
+  ));
+  if (currentEvents.deltaFingerprint !== manifest.forward_state.new_format_event_fingerprint
+    || currentRepairs !== manifest.forward_state.repair_transaction_fingerprint) {
+    throw new Error(
+      "A new-format formal transaction was written after this migration; rollback is blocked. Use forward repair.",
+    );
+  }
+  if (manifest.schema_version >= 2) {
+    const replacements = [...operations.replacements].reverse();
+    const copies = [...operations.copies].reverse();
+    for (const replacement of replacements) {
+      if (!fs.existsSync(replacement.target)
+        || sha256(fs.readFileSync(replacement.target)) !== replacement.after_sha256
+        || !fs.existsSync(replacement.backup)
+        || sha256(fs.readFileSync(replacement.backup)) !== replacement.before_sha256) {
+        throw new Error(`Migrated task bytes changed after ${id}; rollback is blocked. Use forward repair.`);
+      }
+    }
+    for (const copy of copies) {
+      if (!fs.existsSync(copy.target) || sha256(fs.readFileSync(copy.target)) !== copy.target_sha256) {
+        throw new Error(`Migrated layout bytes changed after ${id}; rollback is blocked. Use forward repair.`);
+      }
+    }
+    for (const replacement of replacements) {
+      atomicWrite(replacement.target, fs.readFileSync(replacement.backup));
+    }
+    for (const copy of copies) {
+      fs.rmSync(copy.target, { force: true });
+    }
+  }
+  if (manifest.schema_version >= 3 && manifest.prototype_migration?.applied) {
+    rollbackPrototypeMigration(root, manifest.prototype_migration);
+  }
+  fs.rmSync(migrationDirectory, { recursive: true, force: true });
+  return {
+    command: "migrate rollback",
+    migration_id: id,
+    rolled_back: true,
+    forward_repair_required: false,
+  };
+}
+
+function unsignedMigrationManifest(manifest) {
+  const unsigned = { ...manifest };
+  delete unsigned.record_checksum;
+  return unsigned;
+}
+
+export function migrateProject(project, options = {}) {
+  if (options.rollback) return rollbackMigration(project, options.rollback);
+  const root = path.resolve(project);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const existing = appliedMigration(root);
+  const currentPrototypePlan = planPrototypeMigration(root);
+  const prototypeMigrationPending = new Set(["ready", "blocked"]).has(currentPrototypePlan.status);
+  if (existing && !prototypeMigrationPending) return reportFromManifest(existing, options.dryRun);
+  const report = planMigration(root, { decisions: options.decisions });
+  report.dry_run = Boolean(options.dryRun);
+  if (report.dry_run) return report;
+  if (!report.can_apply) {
+    const reasons = [
+      ...report.conflicts.map((item) => item.type),
+      ...report.task_grouping.unresolved_ambiguities
+        .map((item) => `ambiguous-task-family:${item.family}`),
+      ...report.prototype_migration.unresolved_conflicts
+        .map((item) => `prototype-decision:${item.conflict_id}`),
+    ];
+    throw new Error(
+      `Migration requires explicit repair, grouping, or Prototype decisions before apply: ${reasons.join(", ")}.`,
+    );
+  }
+  for (const copy of report.file_changes.copies) {
+    const source = path.join(root, ...copy.source_path.split("/"));
+    const target = path.join(root, ...copy.target_path.split("/"));
+    if (!fs.existsSync(source) || sha256(fs.readFileSync(source)) !== copy.source_sha256
+      || fs.existsSync(target)) {
+      throw new Error(`Migration source or target changed during apply: ${copy.source_path}.`);
+    }
+  }
+  for (const replacement of report.file_changes.replacements) {
+    const target = path.join(root, ...replacement.path.split("/"));
+    if (!fs.existsSync(target) || sha256(fs.readFileSync(target)) !== replacement.before_sha256) {
+      throw new Error(`Migration task source changed during apply: ${replacement.path}.`);
+    }
+  }
+  const manifestRelative = report.file_changes.additions[0].path;
+  const manifestFile = path.join(root, ...manifestRelative.split("/"));
+  const manifest = {
+    schema_version: 3,
+    migration_id: report.migration_id,
+    status: "applied",
+    applied_at: new Date().toISOString(),
+    source_checksum: report.anchors.proposed.source_checksum,
+    schemas: report.schemas,
+    task_grouping: report.task_grouping,
+    prototype_migration: report.prototype_migration,
+    conflicts: report.conflicts,
+    anchors: report.anchors,
+    business_state: report.business_state,
+    file_changes: report.file_changes,
+    preserved_sources: report.preserved_sources,
+    forward_state: report.forward_state,
+  };
+  manifest.record_checksum = sha256(stableJson(manifest));
+  const operations = validatedMigrationOperations(root, manifest, report.migration_id);
+  const copiedTargets = [];
+  const replacedTargets = [];
+  let prototypeApplied = false;
+  try {
+    for (const copy of operations.copies) {
+      const content = copy.transformation === "add-explicit-attempts"
+        ? migratedTaskBytes(copy.source)
+        : fs.readFileSync(copy.source);
+      if (sha256(content) !== copy.target_sha256) {
+        throw new Error(`Migration copy plan changed during apply: ${copy.source_path}.`);
+      }
+      atomicWrite(copy.target, content);
+      copiedTargets.push(copy.target);
+    }
+    for (const replacement of operations.replacements) {
+      const before = fs.readFileSync(replacement.target);
+      atomicWrite(replacement.backup, before);
+      const after = migratedTaskBytes(replacement.target);
+      if (sha256(after) !== replacement.after_sha256) {
+        throw new Error(`Migration task plan changed during apply: ${replacement.path}.`);
+      }
+      atomicWrite(replacement.target, after);
+      replacedTargets.push({ target: replacement.target, before });
+    }
+    applyPrototypeMigration(root, report.prototype_migration);
+    prototypeApplied = report.prototype_migration.applied;
+    manifest.prototype_migration = report.prototype_migration;
+    delete manifest.record_checksum;
+    manifest.record_checksum = sha256(stableJson(manifest));
+    atomicWrite(manifestFile, `${JSON.stringify(manifest, null, 2)}\n`);
+  } catch (error) {
+    if (prototypeApplied) rollbackPrototypeMigration(root, report.prototype_migration);
+    for (const replacement of replacedTargets.reverse()) atomicWrite(replacement.target, replacement.before);
+    for (const target of copiedTargets.reverse()) fs.rmSync(target, { force: true });
+    fs.rmSync(path.dirname(manifestFile), { recursive: true, force: true });
+    throw error;
+  }
+  report.applied = true;
+  report.manifest_path = manifestRelative;
+  report.already_applied = false;
+  return report;
+}
+
+export function repairProject(project, options = {}) {
+  const root = path.resolve(project);
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+    throw new Error(`Project directory does not exist: ${root}`);
+  }
+  const iterationId = archiveIterationId(options.invalidateArchive);
+  const reason = String(options.reason || "").trim();
+  const actor = String(options.actor || "").trim();
+  const evidence = uniqueSorted(options.evidence);
+  if (!reason) throw new Error("Archive invalidation requires --reason.");
+  if (!actor.startsWith("human:")) {
+    throw new Error("Archive invalidation requires an explicit human actor through --actor human:<identity>.");
+  }
+  if (evidence.length < 2) {
+    throw new Error("Archive invalidation requires at least two --evidence values for RCA and recovery evidence.");
+  }
+  const archiveDirectory = path.join(
+    root, ".workflow", "control", "archives", "versions", iterationId,
+  );
+  const manifestFile = path.join(archiveDirectory, "version-manifest.json");
+  if (!fs.existsSync(manifestFile)) throw new Error(`Version archive not found: ${iterationId}.`);
+  const manifest = readStructured(manifestFile, "version archive manifest");
+  if (manifest.iteration_id !== iterationId) {
+    throw new Error(`Version archive identity mismatch: expected ${iterationId}, found ${manifest.iteration_id || "missing"}.`);
+  }
+  const target = {
+    iteration_id: iterationId,
+    archive_path: toPosix(path.relative(root, archiveDirectory)),
+    manifest_path: toPosix(path.relative(root, manifestFile)),
+    manifest_sha256: sha256(fs.readFileSync(manifestFile)),
+    archive_sha256: treeDigest(archiveDirectory),
+    original_bytes_preserved: true,
+  };
+  const identity = {
+    transaction_type: "archive-invalidation",
+    target,
+    correction: { actor, reason, evidence },
+  };
+  const idempotencyKey = `archive-invalidation:${iterationId}:${sha256(stableJson(identity))}`;
+  const existingTransactions = readRepairTransactions(root);
+  verifiedArchiveInvalidations(root, existingTransactions);
+  const existing = existingTransactions.find((record) => record.idempotency_key === idempotencyKey);
+  const sequence = existing?.sequence || existingTransactions.length + 1;
+  const transactionId = existing?.transaction_id
+    || `REPAIR-${sha256(idempotencyKey).slice(0, 16).toUpperCase()}`;
+  const transactionPath = repairTransactionPath(sequence, transactionId);
+  const report = {
+    command: "repair",
+    action: "archive-invalidation",
+    dry_run: Boolean(options.dryRun),
+    applied: false,
+    forward_only: true,
+    original_bytes_preserved: true,
+    target,
+    actor,
+    reason,
+    evidence,
+    transaction: {
+      transaction_id: transactionId,
+      path: transactionPath,
+      previous_checksum: existing?.previous_checksum || existingTransactions.at(-1)?.record_checksum || null,
+    },
+    eligibility: existing ? {
+      iteration_id: iterationId,
+      current: "invalidated",
+      source_transaction_id: transactionId,
+    } : {
+      iteration_id: iterationId,
+      current: "eligible",
+      source_transaction_id: null,
+    },
+  };
+  if (report.dry_run || existing) return report;
+
+  const repairRoot = path.join(root, ".workflow", "control", "repairs");
+  const lockFile = path.join(repairRoot, ".repair.lock");
+  fs.mkdirSync(repairRoot, { recursive: true });
+  let lock;
+  try {
+    lock = fs.openSync(lockFile, "wx");
+  } catch (error) {
+    throw new Error(`Repair transaction is locked by another writer: ${error.message}`);
+  }
+  try {
+    const currentTransactions = readRepairTransactions(root);
+    const duplicate = currentTransactions.find((record) => record.idempotency_key === idempotencyKey);
+    if (duplicate) {
+      report.transaction.transaction_id = duplicate.transaction_id;
+      report.transaction.path = repairTransactionPath(duplicate.sequence, duplicate.transaction_id);
+      report.eligibility = {
+        iteration_id: iterationId,
+        current: "invalidated",
+        source_transaction_id: duplicate.transaction_id,
+      };
+      return report;
+    }
+    if (currentTransactions.length !== existingTransactions.length
+      || (currentTransactions.at(-1)?.record_checksum || null)
+        !== (existingTransactions.at(-1)?.record_checksum || null)) {
+      throw new Error("Repair transaction revision changed during apply; rerun the command.");
+    }
+    if (treeDigest(archiveDirectory) !== target.archive_sha256
+      || sha256(fs.readFileSync(manifestFile)) !== target.manifest_sha256) {
+      throw new Error(`Version archive changed during repair apply: ${iterationId}.`);
+    }
+    const transaction = {
+      schema_version: 1,
+      sequence,
+      transaction_id: transactionId,
+      transaction_type: "archive-invalidation",
+      idempotency_key: idempotencyKey,
+      occurred_at: new Date().toISOString(),
+      target,
+      correction: { actor, reason, evidence },
+      previous_checksum: existingTransactions.at(-1)?.record_checksum || null,
+    };
+    transaction.record_checksum = sha256(stableJson(transaction));
+    const transactionFile = path.join(root, ...transactionPath.split("/"));
+    atomicWrite(transactionFile, `${JSON.stringify(transaction, null, 2)}\n`);
+    report.applied = true;
+    report.transaction.previous_checksum = transaction.previous_checksum;
+    report.eligibility = {
+      iteration_id: iterationId,
+      current: "invalidated",
+      source_transaction_id: transactionId,
+    };
+    return report;
+  } finally {
+    if (lock !== undefined) fs.closeSync(lock);
+    fs.rmSync(lockFile, { force: true });
+  }
+}