agent-skillboard 0.2.18 → 0.3.1

package/src/migration/v2-files.mjs

@@ -0,0 +1,211 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, open, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+
+export async function createBackup(configPath, configBytes, inventoryPath, inventoryBytes, label = "v1") {
+  const stamp = new Date().toISOString().split(":").join("-");
+  const unique = randomUUID().slice(0, 8);
+  const configBackupPath = `${configPath}.${label}-${stamp}-${unique}.bak`;
+  const inventoryBackupPath = inventoryBytes === null ? null : `${configBackupPath}.inventory`;
+  const manifestPath = `${configBackupPath}.manifest.json`;
+  const configMode = await fileMode(configPath);
+  const inventoryMode = inventoryBytes === null ? null : await fileMode(inventoryPath);
+  await durableCreate(configBackupPath, configBytes);
+  try {
+    if (inventoryBytes !== null) await durableCreate(inventoryBackupPath, inventoryBytes);
+    const manifest = {
+      format_version: 1,
+      source_version: 1,
+      target_version: 2,
+      policy_projection_version: 2,
+      invalidates: ["v1-action-id", "v1-guard-hook", "v1-lock-projection"],
+      target_config: basename(configPath),
+      target_inventory: relativeInventoryPath(configPath, inventoryPath),
+      config_backup: basename(configBackupPath),
+      inventory_backup: inventoryBackupPath === null ? null : basename(inventoryBackupPath),
+      inventory_existed: inventoryBytes !== null,
+      config_mode: configMode,
+      inventory_mode: inventoryMode,
+      input_sha256: sha256(configBytes),
+      inventory_input_sha256: inventoryBytes === null ? null : sha256(inventoryBytes)
+    };
+    await durableCreate(manifestPath, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    return {
+      configBackupPath,
+      inventoryBackupPath,
+      inventoryExisted: inventoryBytes !== null,
+      configMode,
+      inventoryMode,
+      manifestPath
+    };
+  } catch (error) {
+    await rm(configBackupPath, { force: true });
+    if (inventoryBackupPath !== null) await rm(inventoryBackupPath, { force: true });
+    await rm(manifestPath, { force: true });
+    throw error;
+  }
+}
+
+export async function restoreSnapshot(configPath, inventoryPath, snapshot, hooks = {}) {
+  await atomicWrite(configPath, await readFile(snapshot.configBackupPath), snapshot.configMode);
+  await hooks.afterConfigRename?.();
+  if (snapshot.inventoryExisted) {
+    await atomicWrite(inventoryPath, await readFile(snapshot.inventoryBackupPath), snapshot.inventoryMode);
+  } else {
+    await rm(inventoryPath, { force: true });
+    await syncDirectory(dirname(inventoryPath));
+  }
+  await hooks.afterInventoryRename?.();
+}
+
+export async function removeBackupSet(backup) {
+  await rm(backup.configBackupPath, { force: true });
+  if (backup.inventoryBackupPath !== null) await rm(backup.inventoryBackupPath, { force: true });
+  await rm(backup.manifestPath, { force: true });
+}
+
+export async function atomicWrite(path, bytes, mode = 0o600) {
+  await mkdir(dirname(path), { recursive: true });
+  const tempPath = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+  try {
+    await durableCreate(tempPath, bytes, mode);
+    await rename(tempPath, path);
+    await syncDirectory(dirname(path));
+  } finally {
+    await rm(tempPath, { force: true });
+  }
+}
+
+export async function optionalRead(path) {
+  try {
+    return await readFile(path);
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function removeDurably(path) {
+  await rm(path, { force: true });
+  await syncDirectory(dirname(path));
+}
+
+export async function withConfigLock(configPath, operation) {
+  const canonicalPath = await realpath(resolve(configPath));
+  const lockPath = `${canonicalPath}.migrate.lock`;
+  let handle;
+  try {
+    handle = await open(lockPath, "wx", 0o600);
+  } catch (error) {
+    if (error?.code === "EEXIST") {
+      throw new Error("Another migration is already using this config. Remove a stale .migrate.lock only after confirming no migration is running.");
+    }
+    throw error;
+  }
+  try {
+    await handle.writeFile(`${process.pid}\n`);
+    await handle.sync();
+    return await operation();
+  } finally {
+    await handle.close();
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function canonicalMigrationPaths(requestedConfigPath, requestedInventoryPath) {
+  const requested = resolve(requestedConfigPath);
+  const stats = await lstat(requested);
+  if (stats.isSymbolicLink()) {
+    throw new Error("Migration config path must not be a symbolic link; use its real path explicitly.");
+  }
+  if (!stats.isFile()) throw new Error("Migration config path must be a regular file.");
+  const configPath = await realpath(requested);
+  const root = dirname(configPath);
+  const requestedInventory = resolve(requestedInventoryPath ?? join(root, ".skillboard", "inventory.json"));
+  const inventoryStats = await lstat(requestedInventory).catch(missingOnly);
+  if (inventoryStats?.isSymbolicLink()) {
+    throw new Error("Migration inventory target must not be a symbolic link.");
+  }
+  const inventoryDirectory = dirname(requestedInventory);
+  const directoryStats = await lstat(inventoryDirectory).catch(missingOnly);
+  if (directoryStats?.isSymbolicLink()) {
+    throw new Error("Migration inventory directory must not be a symbolic link.");
+  }
+  const existingParent = await nearestExistingDirectory(inventoryDirectory);
+  const realParent = await realpath(existingParent);
+  const inventoryPath = resolve(realParent, relative(existingParent, requestedInventory));
+  if (!isPathInside(root, realParent)) {
+    throw new Error("Migration inventory target resolves outside the config directory.");
+  }
+  if (!isPathInside(root, inventoryPath)) {
+    throw new Error("Migration inventory target must remain inside the config directory.");
+  }
+  return { configPath, inventoryPath };
+}
+
+export function sha256(bytes) {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+export async function durableCreate(path, bytes, mode = 0o600) {
+  await mkdir(dirname(path), { recursive: true });
+  const handle = await open(path, "wx", mode);
+  try {
+    await handle.writeFile(bytes);
+    await chmod(path, mode);
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export async function syncDirectory(path) {
+  if (process.platform === "win32") return;
+  let handle;
+  try {
+    handle = await open(path, "r");
+  } catch (error) {
+    if (error?.code === "ENOENT") return;
+    throw error;
+  }
+  try {
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
+
+export function relativeInventoryPath(configPath, inventoryPath) {
+  const prefix = `${dirname(configPath)}/`;
+  return inventoryPath.startsWith(prefix) ? inventoryPath.slice(prefix.length) : basename(inventoryPath);
+}
+
+async function fileMode(path) {
+  return (await stat(path)).mode & 0o777;
+}
+
+async function nearestExistingDirectory(start) {
+  let candidate = start;
+  while (true) {
+    const stats = await lstat(candidate).catch(missingOnly);
+    if (stats !== undefined) {
+      if (!stats.isDirectory() && !stats.isSymbolicLink()) {
+        throw new Error("Migration inventory parent must be a directory.");
+      }
+      return candidate;
+    }
+    const parent = dirname(candidate);
+    if (parent === candidate) throw new Error("Migration inventory parent does not exist.");
+    candidate = parent;
+  }
+}
+
+function missingOnly(error) {
+  if (error?.code === "ENOENT") return undefined;
+  throw error;
+}
+
+function isPathInside(root, candidate) {
+  const rel = relative(root, candidate);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/src/migration/v2-journal.mjs

@@ -0,0 +1,169 @@
+import { readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import {
+  atomicWrite,
+  optionalRead,
+  relativeInventoryPath,
+  removeBackupSet,
+  removeDurably,
+  restoreSnapshot,
+  sha256
+} from "./v2-files.mjs";
+
+const JOURNAL_FORMAT_VERSION = 1;
+
+export async function beginMigrationTransaction(configPath, inventoryPath, backup) {
+  const journalPath = journalPathFor(configPath);
+  const journal = {
+    format_version: JOURNAL_FORMAT_VERSION,
+    pid: process.pid,
+    phase: "prepared",
+    target_config: basename(configPath),
+    target_inventory: relativeInventoryPath(configPath, inventoryPath),
+    config_backup: basename(backup.configBackupPath),
+    inventory_backup: backup.inventoryBackupPath === null ? null : basename(backup.inventoryBackupPath),
+    inventory_existed: backup.inventoryExisted,
+    config_mode: backup.configMode,
+    inventory_mode: backup.inventoryMode,
+    input_sha256: sha256(await readFile(backup.configBackupPath)),
+    inventory_input_sha256: backup.inventoryBackupPath === null
+      ? null
+      : sha256(await readFile(backup.inventoryBackupPath))
+  };
+  await atomicWrite(journalPath, Buffer.from(`${JSON.stringify(journal, null, 2)}\n`), 0o600);
+  return journalPath;
+}
+
+export async function commitMigrationTransaction(journalPath) {
+  const journal = parseJournal(await readFile(journalPath, "utf8"));
+  await atomicWrite(
+    journalPath,
+    Buffer.from(`${JSON.stringify({ ...journal, phase: "committed" }, null, 2)}\n`),
+    0o600
+  );
+}
+
+export async function finishMigrationTransaction(journalPath) {
+  await removeDurably(journalPath);
+}
+
+export async function completeMigrationRecovery(journalPath, backup) {
+  const journal = parseJournal(await readFile(journalPath, "utf8"));
+  await writePhase(journalPath, journal, "recovered");
+  await removeBackupSet(backup);
+  await removeDurably(journalPath);
+}
+
+export async function recoverInterruptedMigration(configPath, inventoryPath, failpoint) {
+  const journalPath = journalPathFor(configPath);
+  const bytes = await optionalRead(journalPath);
+  if (bytes === null) return false;
+  const journal = parseJournal(bytes.toString("utf8"));
+  validateTargets(journal, configPath, inventoryPath);
+  if (processIsAlive(journal.pid)) {
+    throw new Error("Another migration is already using this config.");
+  }
+  const backup = backupFromJournal(journal, configPath);
+  if (journal.phase === "prepared") {
+    await validateBackupHashes(backup, journal);
+    await restoreSnapshot(configPath, inventoryPath, backup, {
+      afterConfigRename: () => terminateRecoveryAt(failpoint, "after-config-rename"),
+      afterInventoryRename: () => terminateRecoveryAt(failpoint, "after-inventory-rename")
+    });
+    await completeMigrationRecovery(journalPath, backup);
+  } else if (journal.phase === "recovered") {
+    await removeBackupSet(backup);
+    await removeDurably(journalPath);
+  } else {
+    await removeDurably(journalPath);
+  }
+  await removeDurably(`${configPath}.migrate.lock`);
+  return true;
+}
+
+export function journalPathFor(configPath) {
+  return `${configPath}.migrate.transaction.json`;
+}
+
+function parseJournal(text) {
+  const value = JSON.parse(text);
+  if (value?.format_version !== JOURNAL_FORMAT_VERSION
+    || !Number.isInteger(value.pid)
+    || value.pid <= 0
+    || !["prepared", "committed", "recovered"].includes(value.phase)) {
+    throw new Error("Invalid migration transaction journal; recovery was not attempted.");
+  }
+  return value;
+}
+
+async function writePhase(journalPath, journal, phase) {
+  await atomicWrite(
+    journalPath,
+    Buffer.from(`${JSON.stringify({ ...journal, phase }, null, 2)}\n`),
+    0o600
+  );
+}
+
+function terminateRecoveryAt(failpoint, point) {
+  if (failpoint === `terminate-recovery-${point}`) process.exit(87);
+}
+
+function validateTargets(journal, configPath, inventoryPath) {
+  if (journal.target_config !== basename(configPath)
+    || journal.target_inventory !== relativeInventoryPath(configPath, inventoryPath)) {
+    throw new Error("Migration transaction target mismatch; recovery was not attempted.");
+  }
+  if (typeof journal.config_backup !== "string"
+    || basename(journal.config_backup) !== journal.config_backup
+    || !journal.config_backup.startsWith(`${basename(configPath)}.`)) {
+    throw new Error("Invalid migration transaction backup reference; recovery was not attempted.");
+  }
+  const validInventoryBackup = journal.inventory_existed === false && journal.inventory_backup === null
+    || journal.inventory_existed === true
+      && typeof journal.inventory_backup === "string"
+      && basename(journal.inventory_backup) === journal.inventory_backup;
+  const validModes = Number.isInteger(journal.config_mode)
+    && journal.config_mode >= 0
+    && journal.config_mode <= 0o777
+    && (journal.inventory_existed === false
+      ? journal.inventory_mode === null
+      : Number.isInteger(journal.inventory_mode)
+        && journal.inventory_mode >= 0
+        && journal.inventory_mode <= 0o777);
+  if (!validInventoryBackup || !validModes) {
+    throw new Error("Invalid migration transaction backup metadata; recovery was not attempted.");
+  }
+}
+
+function backupFromJournal(journal, configPath) {
+  const directory = dirname(configPath);
+  return {
+    configBackupPath: join(directory, journal.config_backup),
+    inventoryBackupPath: journal.inventory_backup === null ? null : join(directory, journal.inventory_backup),
+    inventoryExisted: journal.inventory_existed,
+    configMode: journal.config_mode,
+    inventoryMode: journal.inventory_mode,
+    manifestPath: `${join(directory, journal.config_backup)}.manifest.json`
+  };
+}
+
+async function validateBackupHashes(backup, journal) {
+  if (sha256(await readFile(backup.configBackupPath)) !== journal.input_sha256) {
+    throw new Error("Migration transaction backup hash mismatch; recovery was not attempted.");
+  }
+  if (backup.inventoryExisted
+    && sha256(await readFile(backup.inventoryBackupPath)) !== journal.inventory_input_sha256) {
+    throw new Error("Migration transaction inventory hash mismatch; recovery was not attempted.");
+  }
+}
+
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if (error?.code === "ESRCH") return false;
+    if (error?.code === "EPERM") return true;
+    throw error;
+  }
+}

package/src/migration/v2-projection.mjs

@@ -0,0 +1,108 @@
+import YAML from "yaml";
+import { sha256 } from "./v2-files.mjs";
+
+const TARGET_VERSION = 2;
+const INVENTORY_FORMAT_VERSION = 1;
+
+export function parseMigrationConfig(text) {
+  const document = YAML.parseDocument(text);
+  if (document.errors.length > 0) {
+    throw new Error(`Invalid YAML config: ${document.errors.map((error) => error.message).join("; ")}`);
+  }
+  const parsed = document.toJS();
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("Config root must be an object mapping");
+  }
+  return { document, parsed };
+}
+
+export function renderMigratedPolicy(policy, sourceText, document) {
+  document.set("version", TARGET_VERSION);
+  document.delete("workflows");
+  let skills = document.get("skills", true);
+  if (!YAML.isMap(skills)) {
+    skills = document.createNode({});
+    document.set("skills", skills);
+  }
+  const retainedIds = new Set(Object.keys(policy.skills));
+  for (const item of [...skills.items]) {
+    const id = String(item.key?.value ?? item.key);
+    if (!retainedIds.has(id)) skills.delete(id);
+  }
+  for (const [id, entry] of Object.entries(policy.skills)) {
+    skills.set(id, document.createNode(entry));
+  }
+  for (const key of ["defaults", "capabilities", "harnesses", "install_units"]) {
+    document.delete(key);
+  }
+  const text = String(document);
+  return sourceText.includes("\r\n") ? text.replace(/(?<!\r)\n/g, "\r\n") : text;
+}
+
+export function migrationInventory(mapped, sourceBytes, losses) {
+  return {
+    format_version: INVENTORY_FORMAT_VERSION,
+    generated: true,
+    authoritative_for_availability: false,
+    skills: mapped.skills,
+    install_units: mapped.install_units,
+    migration: {
+      source_version: 1,
+      target_version: TARGET_VERSION,
+      policy_projection_version: TARGET_VERSION,
+      invalidates: ["v1-action-id", "v1-guard-hook", "v1-lock-projection"],
+      input_sha256: sha256(sourceBytes),
+      losses
+    }
+  };
+}
+
+export function migrationReport(before, mapped, inputBytes, configBytes, inventoryBytes) {
+  const skillEntries = Object.entries(before.skills ?? {}).sort(([left], [right]) => left.localeCompare(right));
+  return {
+    target_version: TARGET_VERSION,
+    input_sha256: sha256(inputBytes),
+    config_sha256: sha256(configBytes),
+    inventory_sha256: sha256(inventoryBytes),
+    counts: {
+      skills: skillEntries.length,
+      enabled: Object.values(mapped.policy.skills).filter((skill) => skill.enabled).length,
+      disabled: Object.values(mapped.policy.skills).filter((skill) => !skill.enabled).length,
+      warnings: mapped.warnings.length,
+      losses: mapped.losses.length
+    },
+    skills: skillEntries.map(([id, skill]) => ({
+      id,
+      before: { status: skill.status, invocation: skill.invocation, exposure: skill.exposure },
+      after: mapped.policy.skills[id]
+    })),
+    warnings: [...mapped.warnings],
+    losses: mapped.losses.map(({ path, disposition }) => ({ path, disposition })),
+    ambiguities: mapped.ambiguities,
+    grouped_decision: mapped.ambiguities.length === 0 ? null : {
+      action: "apply_v2_migration",
+      confirmation_option: "--yes",
+      ambiguity_count: mapped.ambiguities.length,
+      skill_count: mapped.ambiguities.reduce((count, ambiguity) => count + ambiguity.skill_ids.length, 0)
+    }
+  };
+}
+
+export function unchangedMigrationResult(inputBytes) {
+  return {
+    mode: "apply",
+    changed: false,
+    target_version: TARGET_VERSION,
+    input_sha256: sha256(inputBytes),
+    config_sha256: sha256(inputBytes),
+    inventory_sha256: null,
+    counts: { skills: 0, enabled: 0, disabled: 0, warnings: 0, losses: 0 },
+    skills: [],
+    warnings: [],
+    losses: [],
+    ambiguities: [],
+    grouped_decision: null,
+    backup: null,
+    manifest: null
+  };
+}

package/src/migration/v2-transaction.mjs

@@ -0,0 +1,205 @@
+import { readFile, realpath } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { loadWorkspace } from "../workspace.mjs";
+import { mapV1ConfigToV2 } from "./v1-to-v2.mjs";
+import {
+  atomicWrite,
+  canonicalMigrationPaths,
+  createBackup,
+  optionalRead,
+  relativeInventoryPath,
+  restoreSnapshot,
+  sha256,
+  withConfigLock
+} from "./v2-files.mjs";
+import {
+  beginMigrationTransaction,
+  commitMigrationTransaction,
+  completeMigrationRecovery,
+  finishMigrationTransaction,
+  recoverInterruptedMigration
+} from "./v2-journal.mjs";
+import {
+  migrationInventory,
+  migrationReport,
+  parseMigrationConfig,
+  renderMigratedPolicy,
+  unchangedMigrationResult
+} from "./v2-projection.mjs";
+
+const TARGET_VERSION = 2;
+
+export async function migrateV2(options) {
+  const { configPath, inventoryPath } = await canonicalMigrationPaths(options.configPath, options.inventoryPath);
+  await recoverInterruptedMigration(configPath, inventoryPath, options.failpoint);
+  return await withConfigLock(configPath, async () => {
+    if (options.rollbackPath !== undefined) {
+      const requestedRollbackPath = isAbsolute(options.rollbackPath)
+        ? resolve(options.rollbackPath)
+        : resolve(dirname(configPath), options.rollbackPath);
+      const rollbackPath = await realpath(requestedRollbackPath);
+      return await rollbackMigration(configPath, inventoryPath, rollbackPath, options);
+    }
+    return await migrateForward(configPath, inventoryPath, options);
+  });
+}
+
+async function migrateForward(configPath, inventoryPath, options) {
+  const inputBytes = await readFile(configPath);
+  const inputText = inputBytes.toString("utf8");
+  const { document, parsed } = parseMigrationConfig(inputText);
+  const version = parsed.version ?? 1;
+  if (version === TARGET_VERSION) {
+    await validateCurrentV2(configPath, inventoryPath, options.skillsRoot);
+    return unchangedMigrationResult(inputBytes);
+  }
+  if (version !== 1) {
+    throw new Error(`Unsupported config version: ${String(version)}. No files were changed.`);
+  }
+
+  const mapped = mapV1ConfigToV2(parsed);
+  const configBytes = Buffer.from(renderMigratedPolicy(mapped.policy, inputText, document));
+  const inventory = migrationInventory(mapped.inventory, inputBytes, mapped.losses);
+  const inventoryBytes = Buffer.from(`${JSON.stringify(inventory, null, 2)}\n`);
+  const report = migrationReport(parsed, mapped, inputBytes, configBytes, inventoryBytes);
+  if (options.apply !== true) {
+    return { mode: "preview", changed: true, backup: null, ...report };
+  }
+
+  const previousInventory = await optionalRead(inventoryPath);
+  const backup = await createBackup(configPath, inputBytes, inventoryPath, previousInventory);
+  const journalPath = await beginMigrationTransaction(configPath, inventoryPath, backup);
+  try {
+    await atomicWrite(configPath, configBytes, backup.configMode);
+    failAt(options, "after-config-rename");
+    failAt(options, "after-config-write");
+    await atomicWrite(inventoryPath, inventoryBytes, backup.inventoryMode ?? 0o600);
+    failAt(options, "after-inventory-rename");
+    failAt(options, "before-validation");
+    await validateCurrentV2(configPath, inventoryPath, options.skillsRoot);
+    await commitMigrationTransaction(journalPath);
+    failAt(options, "after-commit-journal");
+    await finishMigrationTransaction(journalPath);
+    return {
+      mode: "apply",
+      changed: true,
+      backup: basename(backup.configBackupPath),
+      manifest: basename(backup.manifestPath),
+      ...report
+    };
+  } catch (error) {
+    await restoreSnapshot(configPath, inventoryPath, backup);
+    await completeMigrationRecovery(journalPath, backup);
+    throw error;
+  }
+}
+
+async function rollbackMigration(configPath, inventoryPath, configBackupPath, options) {
+  assertAdjacentBackup(configPath, configBackupPath);
+  const manifestPath = `${configBackupPath}.manifest.json`;
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateManifest(manifest, configPath, inventoryPath, configBackupPath);
+  const currentConfig = await readFile(configPath);
+  const currentInventory = await optionalRead(inventoryPath);
+  const snapshot = {
+    configBackupPath,
+    manifestPath,
+    inventoryBackupPath: manifest.inventory_backup === null
+      ? null
+      : join(dirname(configBackupPath), manifest.inventory_backup),
+    inventoryExisted: manifest.inventory_existed,
+    configMode: manifest.config_mode,
+    inventoryMode: manifest.inventory_mode
+  };
+  const backupBytes = await readFile(configBackupPath);
+  if (sha256(backupBytes) !== manifest.input_sha256) {
+    throw new Error("Migration backup hash mismatch; rollback was not attempted.");
+  }
+  if (snapshot.inventoryExisted) {
+    const inventoryBytes = await readFile(snapshot.inventoryBackupPath);
+    if (sha256(inventoryBytes) !== manifest.inventory_input_sha256) {
+      throw new Error("Migration inventory backup hash mismatch; rollback was not attempted.");
+    }
+  }
+
+  const safety = await createBackup(configPath, currentConfig, inventoryPath, currentInventory, "rollback-safety");
+  const journalPath = await beginMigrationTransaction(configPath, inventoryPath, safety);
+  try {
+    await restoreSnapshot(configPath, inventoryPath, snapshot, {
+      afterConfigRename: () => failAt(options, "after-config-rename"),
+      afterInventoryRename: () => failAt(options, "after-inventory-rename")
+    });
+    await commitMigrationTransaction(journalPath);
+    failAt(options, "after-commit-journal");
+    await finishMigrationTransaction(journalPath);
+    return {
+      mode: "rollback",
+      changed: true,
+      target_version: manifest.source_version,
+      input_sha256: sha256(currentConfig),
+      config_sha256: sha256(await readFile(configPath)),
+      inventory_sha256: (await optionalRead(inventoryPath)) === null
+        ? null
+        : sha256(await readFile(inventoryPath)),
+      backup: basename(configBackupPath),
+      safety_backup: basename(safety.configBackupPath)
+    };
+  } catch (error) {
+    await restoreSnapshot(configPath, inventoryPath, safety);
+    await completeMigrationRecovery(journalPath, safety);
+    throw error;
+  }
+}
+
+async function validateCurrentV2(configPath, inventoryPath, skillsRoot) {
+  const workspace = await loadWorkspace({ configPath, inventoryPath, skillsRoot });
+  if (workspace.version !== TARGET_VERSION) {
+    throw new Error("Post-write validation did not load version 2 policy.");
+  }
+  if (workspace.inventory?.integrityErrors?.length > 0) {
+    throw new Error("Post-write inventory validation failed.");
+  }
+  const policyIds = workspace.skills.map(({ id }) => id).sort((left, right) => left.localeCompare(right));
+  const inventoryIds = [...(workspace.inventory?.skillIds ?? [])].sort((left, right) => left.localeCompare(right));
+  if (policyIds.length !== inventoryIds.length
+    || policyIds.some((id, index) => id !== inventoryIds[index])) {
+    throw new Error("Post-write policy and inventory skill-set agreement failed.");
+  }
+}
+
+function validateManifest(manifest, configPath, inventoryPath, backupPath) {
+  if (manifest?.format_version !== 1 || manifest.config_backup !== basename(backupPath)) {
+    throw new Error("Invalid migration backup manifest; rollback was not attempted.");
+  }
+  if (manifest.target_config !== basename(configPath)) {
+    throw new Error("Migration backup belongs to a different config; rollback was not attempted.");
+  }
+  const requestedInventory = relativeInventoryPath(configPath, inventoryPath);
+  if (manifest.target_inventory !== requestedInventory) {
+    throw new Error("Requested inventory target does not match the migration manifest; rollback was not attempted.");
+  }
+  if (!Number.isInteger(manifest.config_mode) || manifest.config_mode < 0 || manifest.config_mode > 0o777
+    || (manifest.inventory_existed === true
+      && (!Number.isInteger(manifest.inventory_mode) || manifest.inventory_mode < 0 || manifest.inventory_mode > 0o777))) {
+    throw new Error("Invalid migration backup mode metadata; rollback was not attempted.");
+  }
+  if (manifest.inventory_existed === true) {
+    const expected = `${basename(backupPath)}.inventory`;
+    if (manifest.inventory_backup !== expected || basename(manifest.inventory_backup) !== manifest.inventory_backup) {
+      throw new Error("Invalid migration inventory backup reference; rollback was not attempted.");
+    }
+  } else if (manifest.inventory_existed !== false || manifest.inventory_backup !== null) {
+    throw new Error("Invalid migration inventory backup state; rollback was not attempted.");
+  }
+}
+
+function assertAdjacentBackup(configPath, backupPath) {
+  if (dirname(configPath) !== dirname(backupPath) || !basename(backupPath).startsWith(`${basename(configPath)}.`)) {
+    throw new Error("Migration rollback backup must be adjacent to the selected config.");
+  }
+}
+
+function failAt(options, point) {
+  if (options.failpoint === `terminate-${point}`) process.exit(86);
+  if (options.failpoint === point) throw new Error(`Injected migration failure at ${point}.`);
+}