@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/migration-backup.js

@@ -0,0 +1,1060 @@
+"use strict";
+
+const crypto = require("crypto");
+const fs = require("fs");
+const path = require("path");
+
+const MIGRATION_ID = "provider-parity-v1.1";
+const FORMAT_VERSION = 1;
+const REQUIRED_ACTIVATION_COMPONENTS = Object.freeze(["state", "sessions", "jobs"]);
+const MANIFEST_FILE = "manifest.json";
+const MANIFEST_HASH_FILE = "manifest.sha256";
+const JOURNAL_FILE = "journal.json";
+const LOCK_FILE = ".lock";
+const COMPONENT_SCHEMA_VERSIONS = Object.freeze({
+  state: 3,
+  sessions: 3,
+  jobs: 2,
+});
+
+function migrationError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "MigrationBackupError";
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function migrationRoot(configDir) {
+  if (!configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  return path.join(path.resolve(configDir), "migration-backups", MIGRATION_ID);
+}
+
+function journalPath(configDir) {
+  return path.join(migrationRoot(configDir), JOURNAL_FILE);
+}
+
+function ensureDirectory(directory, mode = 0o700) {
+  fs.mkdirSync(directory, { recursive: true, mode });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw migrationError("UNSAFE_MIGRATION_DIRECTORY", "migration directory must be a real directory");
+  }
+  try { fs.chmodSync(directory, mode); } catch (_) {}
+}
+
+function ensureTargetParent(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw migrationError("UNSAFE_ROLLBACK_TARGET", "rollback parent must be a real directory");
+  }
+}
+
+function fsyncDirectory(directory) {
+  let fd;
+  try {
+    fd = fs.openSync(directory, "r");
+    fs.fsyncSync(fd);
+  } catch (_) {
+    // Some platforms/filesystems cannot fsync directories. File fsync and
+    // atomic sibling rename still protect the contents there.
+  } finally {
+    if (fd !== undefined) try { fs.closeSync(fd); } catch (_) {}
+  }
+}
+
+function writeSecureFile(filePath, data, { exclusive = false, privateParent = true } = {}) {
+  if (privateParent) ensureDirectory(path.dirname(filePath));
+  else ensureTargetParent(path.dirname(filePath));
+  const flags = exclusive ? "wx" : "w";
+  const fd = fs.openSync(filePath, flags, 0o600);
+  try {
+    fs.writeFileSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try { fs.chmodSync(filePath, 0o600); } catch (_) {}
+}
+
+function atomicWriteSecure(filePath, data) {
+  ensureDirectory(path.dirname(filePath));
+  const temp = `${filePath}.${process.pid}.${Date.now()}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  try {
+    writeSecureFile(temp, data, { exclusive: true });
+    fs.renameSync(temp, filePath);
+    try { fs.chmodSync(filePath, 0o600); } catch (_) {}
+    fsyncDirectory(path.dirname(filePath));
+  } finally {
+    try { if (fs.existsSync(temp)) fs.unlinkSync(temp); } catch (_) {}
+  }
+}
+
+function stableJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function assertRegularFile(filePath, code, label) {
+  const stat = fs.lstatSync(filePath);
+  if (!stat.isFile() || stat.isSymbolicLink()) {
+    throw migrationError(code, `${label} must be a regular file`);
+  }
+  return stat;
+}
+
+function assertPrivateMode(stat, expectedMask, code, label) {
+  if (process.platform !== "win32" && (stat.mode & 0o777) !== expectedMask) {
+    throw migrationError(code, `${label} has unsafe permissions`);
+  }
+}
+
+function normalizeLogicalPath(value) {
+  if (typeof value !== "string" || !value || value.includes("\\") || value.includes("\0")) {
+    throw migrationError("UNSAFE_MANIFEST_PATH", "migration path is invalid");
+  }
+  const normalized = path.posix.normalize(value);
+  if (normalized !== value || normalized === "." || normalized.startsWith("../") || path.posix.isAbsolute(normalized)) {
+    throw migrationError("UNSAFE_MANIFEST_PATH", `unsafe migration path: ${value}`);
+  }
+  return normalized;
+}
+
+function sourceRecord(logicalPath, sourcePath, kind) {
+  return {
+    path: normalizeLogicalPath(logicalPath),
+    sourcePath: path.resolve(sourcePath),
+    kind,
+  };
+}
+
+function defaultMigrationSources(options = {}) {
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const stateFile = path.resolve(options.stateFile || path.join(configDir, "state.json"));
+  const sessionsFile = path.resolve(options.sessionsFile || path.join(configDir, "sessions.json"));
+  const jobsFile = path.resolve(options.jobsFile || path.join(configDir, "jobs.json"));
+  const cronsFile = path.resolve(options.cronsFile || path.join(configDir, "crons.json"));
+  return normalizeSources([
+    sourceRecord("state.json", stateFile, "state"),
+    sourceRecord("state.json.bak", `${stateFile}.bak`, "state"),
+    sourceRecord("sessions.json", sessionsFile, "sessions"),
+    sourceRecord("sessions.json.bak", `${sessionsFile}.bak`, "sessions"),
+    sourceRecord("jobs.json", jobsFile, "jobs"),
+    sourceRecord("jobs.json.bak", `${jobsFile}.bak`, "jobs"),
+    sourceRecord("crons.json", cronsFile, "crons"),
+    sourceRecord("crons.json.migrated", `${cronsFile}.migrated`, "crons"),
+  ]);
+}
+
+function normalizeSources(sources) {
+  if (!Array.isArray(sources) || sources.length === 0) {
+    throw migrationError("INVALID_MIGRATION_CONFIG", "at least one migration source is required");
+  }
+  const logical = new Set();
+  const physical = new Map();
+  const normalized = sources.map((entry) => {
+    const record = sourceRecord(entry.path, entry.sourcePath, entry.kind || "unknown");
+    if (logical.has(record.path)) throw migrationError("MIGRATION_PATH_COLLISION", `duplicate migration path: ${record.path}`);
+    logical.add(record.path);
+    const previous = physical.get(record.sourcePath);
+    if (previous && previous !== record.path) {
+      throw migrationError("MIGRATION_SOURCE_COLLISION", `one source is mapped to both ${previous} and ${record.path}`);
+    }
+    physical.set(record.sourcePath, record.path);
+    return record;
+  });
+  return normalized.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function stateValues(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return [];
+  if (value.users && typeof value.users === "object" && !Array.isArray(value.users)) return Object.values(value.users);
+  return [value];
+}
+
+function schemaGuess(buffer, source) {
+  if (buffer === null) return { schemaGuess: "missing", resolution: "missing" };
+  let value;
+  try { value = JSON.parse(buffer.toString("utf8")); }
+  catch (_) { return { schemaGuess: "malformed-json", resolution: "unresolved" }; }
+
+  const suffix = source.path.endsWith(".bak") ? "-fallback" : "";
+  if (source.kind === "state") {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+      return { schemaGuess: `unknown-state${suffix}`, resolution: "unresolved" };
+    }
+    const values = stateValues(value);
+    const multi = !!(value && typeof value === "object" && value.users && typeof value.users === "object");
+    const cursor = values.some((entry) => (
+      entry?.settings?.backend === "cursor"
+      || !!entry?.cursorSessionId
+      || !!entry?.providerSettings?.cursor
+      || Object.values(entry?.activeSessions || {}).some((providers) => !!providers?.cursor)
+    ));
+    const dual = values.some((entry) => !!entry?.lastSessionId && !!entry?.codexSessionId);
+    const codex = values.some((entry) => entry?.settings?.backend === "codex" || !!entry?.codexSessionId);
+    const claude = values.some((entry) => entry?.settings?.backend === "claude" || !!entry?.lastSessionId);
+    const missingProject = values.some((entry) => !entry?.currentSession && (!!entry?.lastSessionId || !!entry?.codexSessionId || !!entry?.cursorSessionId));
+    if (cursor) return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-cursor${suffix}`, resolution: "unresolved" };
+    if (missingProject) return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-missing-project${suffix}`, resolution: "unresolved" };
+    if (dual || (multi && codex && claude)) return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-claude-codex${suffix}`, resolution: "archived" };
+    if (codex) return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-codex${suffix}`, resolution: "archived" };
+    if (claude) return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-claude${suffix}`, resolution: "archived" };
+    return { schemaGuess: `${multi ? "multi-user-" : "legacy-"}state-unknown${suffix}`, resolution: "unresolved" };
+  }
+  if (source.kind === "sessions") {
+    const records = [];
+    const walk = (node) => {
+      if (Array.isArray(node)) records.push(...node.filter((entry) => entry && typeof entry === "object"));
+      else if (node && typeof node === "object") Object.values(node).forEach(walk);
+    };
+    walk(value);
+    const cursor = records.some((entry) => entry?.provider === "cursor" || entry?.archivedProvider === "cursor");
+    const providerAware = records.length > 0 && records.every((entry) => typeof entry.provider === "string" && entry.provider);
+    return {
+      schemaGuess: `${cursor ? "provider-session-history-cursor" : (providerAware ? "provider-session-history" : "legacy-provider-blind-sessions")}${suffix}`,
+      resolution: cursor || !providerAware ? "unresolved" : "archived",
+    };
+  }
+  if (source.kind === "jobs") {
+    if (!Array.isArray(value)) return { schemaGuess: `unknown-jobs${suffix}`, resolution: "unresolved" };
+    const cursor = value.some((entry) => entry?.provider === "cursor" || entry?.sessionKey === "cursorSessionId");
+    const missingProject = value.some((entry) => entry?.sessionId && !entry?.project);
+    const ambiguous = value.some((entry) => entry?.sessionId && !entry?.provider && !entry?.sessionKey);
+    return {
+      schemaGuess: `${cursor ? "legacy-jobs-cursor" : "legacy-jobs"}${suffix}`,
+      resolution: cursor || missingProject || ambiguous ? "unresolved" : "archived",
+    };
+  }
+  if (source.kind === "crons") {
+    return { schemaGuess: `legacy-provider-blind-crons${suffix}`, resolution: "unresolved" };
+  }
+  return { schemaGuess: `unknown-json${suffix}`, resolution: "unresolved" };
+}
+
+function fault(options, point, context = {}) {
+  if (typeof options.faultInjector === "function") options.faultInjector(point, context);
+}
+
+function acquireLock(root) {
+  ensureDirectory(root);
+  const filePath = path.join(root, LOCK_FILE);
+  let fd;
+  const open = () => fs.openSync(filePath, "wx", 0o600);
+  try { fd = open(); }
+  catch (error) {
+    if (error.code === "EEXIST") {
+      let stale = false;
+      try {
+        const stat = assertRegularFile(filePath, "MIGRATION_LOCKED", "migration lock");
+        const pid = Number(fs.readFileSync(filePath, "utf8").trim());
+        if (Number.isSafeInteger(pid) && pid > 0 && Date.now() - stat.mtimeMs > 1000) {
+          try { process.kill(pid, 0); }
+          catch (probeError) { stale = probeError.code === "ESRCH"; }
+        }
+      } catch (_) {}
+      if (stale) {
+        try { fs.unlinkSync(filePath); } catch (_) {}
+        try { fd = open(); }
+        catch (_) { throw migrationError("MIGRATION_LOCKED", "provider migration snapshot is already locked"); }
+      } else {
+        throw migrationError("MIGRATION_LOCKED", "provider migration snapshot is already locked");
+      }
+    } else {
+      throw error;
+    }
+  }
+  fs.writeFileSync(fd, `${process.pid}\n`);
+  fs.fsyncSync(fd);
+  return () => {
+    try { fs.closeSync(fd); } catch (_) {}
+    try { fs.unlinkSync(filePath); } catch (_) {}
+  };
+}
+
+function snapshotPathFromJournal(root, journal) {
+  if (!journal?.snapshot) throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal has no snapshot pointer");
+  const resolved = path.resolve(root, journal.snapshot);
+  const prefix = `${path.resolve(root)}${path.sep}`;
+  if (!resolved.startsWith(prefix)) throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal snapshot path is unsafe");
+  return resolved;
+}
+
+function readJsonFile(filePath, code, label) {
+  assertRegularFile(filePath, code, label);
+  try { return JSON.parse(fs.readFileSync(filePath, "utf8")); }
+  catch (_) { throw migrationError(code, `${label} is invalid JSON`); }
+}
+
+function readMigrationJournal(configDir) {
+  const filePath = journalPath(configDir);
+  if (!fs.existsSync(filePath)) return null;
+  const journal = readJsonFile(filePath, "INVALID_MIGRATION_JOURNAL", "migration journal");
+  if (journal.migrationId !== MIGRATION_ID || journal.formatVersion !== FORMAT_VERSION) {
+    throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal identity is invalid");
+  }
+  if (!new Set(["prepared", "validated", "activated"]).has(journal.stage)
+      || typeof journal.snapshot !== "string"
+      || !/^[a-f0-9]{64}$/.test(journal.manifestSha256 || "")
+      || !journal.stages?.prepared) {
+    throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal stage metadata is invalid");
+  }
+  if (journal.stage !== "prepared" && !journal.stages.validated) {
+    throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal is missing validation metadata");
+  }
+  if (journal.stage === "activated" && (
+    !journal.stages.activated
+    || !REQUIRED_ACTIVATION_COMPONENTS.every((component) => !!journal.components?.[component])
+  )) {
+    throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal activation is incomplete");
+  }
+  if (journal.pendingComponents !== undefined && (
+    !journal.pendingComponents
+    || typeof journal.pendingComponents !== "object"
+    || Array.isArray(journal.pendingComponents)
+    || Object.keys(journal.pendingComponents).some((component) => !REQUIRED_ACTIVATION_COMPONENTS.includes(component))
+  )) {
+    throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal pending-component metadata is invalid");
+  }
+  return journal;
+}
+
+function writeJournal(configDir, journal) {
+  atomicWriteSecure(journalPath(configDir), stableJson(journal));
+  return journal;
+}
+
+function sourceMap(sources) {
+  return new Map(normalizeSources(sources).map((entry) => [entry.path, entry]));
+}
+
+function readSource(source) {
+  if (!fs.existsSync(source.sourcePath)) return null;
+  let stat;
+  try { stat = assertRegularFile(source.sourcePath, "UNSAFE_MIGRATION_SOURCE", `migration source ${source.path}`); }
+  catch (error) {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  }
+  const data = fs.readFileSync(source.sourcePath);
+  const after = fs.lstatSync(source.sourcePath);
+  if (!after.isFile() || after.isSymbolicLink() || stat.dev !== after.dev || stat.ino !== after.ino || stat.size !== after.size || stat.mtimeMs !== after.mtimeMs) {
+    throw migrationError("MIGRATION_SOURCE_CHANGED", `migration source changed while reading: ${source.path}`);
+  }
+  return data;
+}
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function componentNotMigrated(component, reason, details = {}) {
+  return migrationError(
+    "MIGRATION_COMPONENT_NOT_MIGRATED",
+    `${component} migration output is not provider-aware: ${reason}`,
+    { component, ...details },
+  );
+}
+
+function parseMigratedComponent(component, raw) {
+  if (raw === null) throw componentNotMigrated(component, `${component}.json is missing`);
+  let document;
+  try { document = JSON.parse(raw.toString("utf8")); }
+  catch (_) { throw componentNotMigrated(component, `${component}.json is invalid JSON`); }
+  const expectedSchema = COMPONENT_SCHEMA_VERSIONS[component];
+  if (!isRecord(document) || document.schemaVersion !== expectedSchema) {
+    throw componentNotMigrated(component, `expected schema version ${expectedSchema}`);
+  }
+
+  if (component === "state") {
+    if (!isRecord(document.users)) throw componentNotMigrated(component, "users must be an object");
+    for (const user of Object.values(document.users)) {
+      if (!isRecord(user)) throw componentNotMigrated(component, "every user state must be an object");
+      const backend = user.settings?.backend;
+      if (backend !== undefined && backend !== null && !["claude", "codex"].includes(backend)) {
+        throw componentNotMigrated(component, `unsupported active provider ${String(backend)}`);
+      }
+      if (Object.prototype.hasOwnProperty.call(user, "cursorSessionId")) {
+        throw componentNotMigrated(component, "removed-provider session pointer is still active");
+      }
+      if (isRecord(user.providerSettings) && Object.prototype.hasOwnProperty.call(user.providerSettings, "cursor")) {
+        throw componentNotMigrated(component, "removed-provider settings are still active");
+      }
+      for (const providers of Object.values(isRecord(user.activeSessions) ? user.activeSessions : {})) {
+        if (!isRecord(providers)) throw componentNotMigrated(component, "active session buckets must be objects");
+        if (Object.prototype.hasOwnProperty.call(providers, "cursor")) {
+          throw componentNotMigrated(component, "removed-provider session is still selectable");
+        }
+      }
+    }
+  } else if (component === "sessions") {
+    if (!isRecord(document.users)) throw componentNotMigrated(component, "users must be an object");
+    for (const projects of Object.values(document.users)) {
+      if (!isRecord(projects)) throw componentNotMigrated(component, "project histories must be objects");
+      for (const records of Object.values(projects)) {
+        if (!Array.isArray(records)) throw componentNotMigrated(component, "session histories must be arrays");
+        for (const record of records) {
+          if (!isRecord(record) || typeof record.provider !== "string" || !record.provider) {
+            throw componentNotMigrated(component, "session records must declare a provider");
+          }
+          if (record.provider === "cursor") {
+            throw componentNotMigrated(component, "removed-provider history is still selectable");
+          }
+          if (record.archivedProvider === "cursor" && (record.provider !== "legacy" || record.selectable !== false)) {
+            throw componentNotMigrated(component, "removed-provider history is not a disabled legacy record");
+          }
+        }
+      }
+    }
+  } else if (component === "jobs") {
+    if (!Array.isArray(document.jobs) || !Array.isArray(document.archived)) {
+      throw componentNotMigrated(component, "jobs and archived must be arrays");
+    }
+    for (const job of document.jobs) {
+      if (!isRecord(job) || !["claude", "codex"].includes(job.provider)) {
+        throw componentNotMigrated(component, "runnable jobs must use a supported provider");
+      }
+      if (job.sessionKey === "cursorSessionId") {
+        throw componentNotMigrated(component, "removed-provider session pointer is still runnable");
+      }
+    }
+    for (const job of document.archived) {
+      if (!isRecord(job) || job.disabled !== true || job.status !== "archived") {
+        throw componentNotMigrated(component, "archived jobs must be disabled archives");
+      }
+      if (job.sessionKey === "cursorSessionId") {
+        throw componentNotMigrated(component, "removed-provider session pointer was not archived");
+      }
+    }
+    const cron = document.legacyCronMigration;
+    if (!isRecord(cron)
+        || cron.path !== "crons.json"
+        || typeof cron.present !== "boolean"
+        || !new Set(["missing", "archived", "malformed-archived"]).has(cron.status)
+        || !Number.isSafeInteger(cron.recordCount)
+        || cron.recordCount < 0
+        || !Array.isArray(cron.recordHashes)
+        || cron.recordHashes.length !== cron.recordCount) {
+      throw componentNotMigrated(component, "legacy cron migration evidence is missing or invalid");
+    }
+    if (cron.present) {
+      if (!Number.isSafeInteger(cron.size) || cron.size < 0 || !/^[a-f0-9]{64}$/.test(cron.sha256 || "")) {
+        throw componentNotMigrated(component, "legacy cron source evidence is invalid");
+      }
+    } else if (cron.size !== null || cron.sha256 !== null || cron.status !== "missing") {
+      throw componentNotMigrated(component, "missing legacy cron source evidence is invalid");
+    }
+    const archivedCronHashes = new Set(document.archived.map((job) => job.legacyCronHash).filter(Boolean));
+    if (cron.recordHashes.some((hash) => !/^[a-f0-9]{64}$/.test(hash) || !archivedCronHashes.has(hash))) {
+      throw componentNotMigrated(component, "a legacy cron record was not archived");
+    }
+    if (cron.status === "malformed-archived"
+        && !document.archived.some((job) => job.id === cron.archiveId && job.legacyCronSourceHash === cron.sha256)) {
+      throw componentNotMigrated(component, "malformed legacy cron source was not archived");
+    }
+  }
+  return document;
+}
+
+function migratedComponentProof(sources, component) {
+  const source = normalizeSources(sources).find((entry) => entry.path === `${component}.json` && entry.kind === component);
+  if (!source) {
+    throw migrationError("INVALID_MIGRATION_CONFIG", `migration source is missing: ${component}.json`);
+  }
+  const raw = readSource(source);
+  const document = parseMigratedComponent(component, raw);
+  if (component === "jobs") {
+    const cronSource = normalizeSources(sources).find((entry) => entry.path === "crons.json" && entry.kind === "crons");
+    if (!cronSource) throw migrationError("INVALID_MIGRATION_CONFIG", "migration source is missing: crons.json");
+    const cronRaw = readSource(cronSource);
+    const cron = document.legacyCronMigration;
+    const matches = cron.path === cronSource.path
+      && cron.present === (cronRaw !== null)
+      && cron.size === (cronRaw === null ? null : cronRaw.length)
+      && cron.sha256 === (cronRaw === null ? null : sha256(cronRaw));
+    if (!matches) throw componentNotMigrated(component, "legacy cron certification is stale");
+  }
+  return {
+    path: source.path,
+    size: raw.length,
+    sha256: sha256(raw),
+    schemaVersion: document.schemaVersion,
+  };
+}
+
+function proofMatches(record, proof) {
+  return isRecord(record)
+    && record.path === proof.path
+    && record.size === proof.size
+    && record.sha256 === proof.sha256
+    && record.schemaVersion === proof.schemaVersion;
+}
+
+function backupPath(snapshotDir, logicalPath) {
+  const safe = normalizeLogicalPath(logicalPath);
+  const root = path.resolve(snapshotDir, "originals");
+  const resolved = path.resolve(root, ...safe.split("/"));
+  if (resolved !== root && !resolved.startsWith(`${root}${path.sep}`)) {
+    throw migrationError("UNSAFE_MANIFEST_PATH", `unsafe backup path: ${logicalPath}`);
+  }
+  return resolved;
+}
+
+function compareSources(manifest, sources) {
+  const byPath = sourceMap(sources);
+  const manifestPaths = new Set(manifest.files.map((entry) => entry.path));
+  if (byPath.size !== manifestPaths.size) return { ok: false, path: "source-set" };
+  for (const logicalPath of byPath.keys()) {
+    if (!manifestPaths.has(logicalPath)) return { ok: false, path: logicalPath };
+  }
+  for (const entry of manifest.files) {
+    const source = byPath.get(entry.path);
+    if (!source) return { ok: false, path: entry.path };
+    const raw = readSource(source);
+    if (!entry.present) {
+      if (raw !== null) return { ok: false, path: entry.path };
+      continue;
+    }
+    if (raw === null || raw.length !== entry.size || sha256(raw) !== entry.sha256) return { ok: false, path: entry.path };
+  }
+  return { ok: true };
+}
+
+function activationComponentForKind(kind) {
+  if (kind === "crons") return "jobs";
+  return REQUIRED_ACTIVATION_COMPONENTS.includes(kind) ? kind : null;
+}
+
+function compareComponentSources(manifest, sources, component) {
+  if (!REQUIRED_ACTIVATION_COMPONENTS.includes(component)) {
+    throw migrationError("INVALID_MIGRATION_COMPONENT", `unknown migration component: ${component}`);
+  }
+  const byPath = sourceMap(sources);
+  for (const entry of manifest.files) {
+    const source = byPath.get(entry.path);
+    if (!source || activationComponentForKind(source.kind) !== component) continue;
+    const raw = readSource(source);
+    if (!entry.present) {
+      if (raw !== null) return { ok: false, path: entry.path };
+      continue;
+    }
+    if (raw === null || raw.length !== entry.size || sha256(raw) !== entry.sha256) {
+      return { ok: false, path: entry.path };
+    }
+  }
+  return { ok: true };
+}
+
+function assertMigrationComponentSourcesMatch(manifest, sources, component) {
+  const comparison = compareComponentSources(manifest, sources, component);
+  if (!comparison.ok) {
+    throw migrationError(
+      "MIGRATION_SOURCE_CHANGED",
+      `${component} migration source changed after snapshot: ${comparison.path}`,
+    );
+  }
+}
+
+function assertSourcesMatch(manifest, sources) {
+  const comparison = compareSources(manifest, sources);
+  if (!comparison.ok) {
+    throw migrationError("MIGRATION_SOURCE_CHANGED", `migration source changed after snapshot: ${comparison.path}`);
+  }
+}
+
+function validateManifestShape(manifest) {
+  if (!manifest || manifest.formatVersion !== FORMAT_VERSION || manifest.migrationId !== MIGRATION_ID || !Array.isArray(manifest.files)) {
+    throw migrationError("INVALID_MIGRATION_MANIFEST", "migration manifest identity is invalid");
+  }
+  const paths = manifest.files.map((entry) => normalizeLogicalPath(entry.path));
+  if (new Set(paths).size !== paths.length) throw migrationError("INVALID_MIGRATION_MANIFEST", "migration manifest contains duplicate paths");
+  if (paths.some((value, index) => index > 0 && paths[index - 1].localeCompare(value) > 0)) {
+    throw migrationError("INVALID_MIGRATION_MANIFEST", "migration manifest paths are not sorted");
+  }
+  for (const entry of manifest.files) {
+    if (typeof entry.present !== "boolean" || typeof entry.schemaGuess !== "string") {
+      throw migrationError("INVALID_MIGRATION_MANIFEST", `migration manifest entry is invalid: ${entry.path}`);
+    }
+    if (entry.present) {
+      if (!Number.isSafeInteger(entry.size) || entry.size < 0 || !/^[a-f0-9]{64}$/.test(entry.sha256 || "") || !Number.isSafeInteger(entry.mode)) {
+        throw migrationError("INVALID_MIGRATION_MANIFEST", `migration manifest checksum is invalid: ${entry.path}`);
+      }
+    } else if (entry.size !== null || entry.sha256 !== null || entry.mode !== null) {
+      throw migrationError("INVALID_MIGRATION_MANIFEST", `missing migration entry has data metadata: ${entry.path}`);
+    }
+  }
+}
+
+function validateMigrationSnapshot(snapshotDir, options = {}) {
+  const resolvedSnapshot = path.resolve(snapshotDir);
+  const snapshotStat = fs.lstatSync(resolvedSnapshot);
+  if (!snapshotStat.isDirectory() || snapshotStat.isSymbolicLink()) {
+    throw migrationError("INVALID_MIGRATION_SNAPSHOT", "migration snapshot must be a real directory");
+  }
+  assertPrivateMode(snapshotStat, 0o700, "INVALID_MIGRATION_SNAPSHOT", "migration snapshot");
+  const originalsStat = fs.lstatSync(path.join(resolvedSnapshot, "originals"));
+  if (!originalsStat.isDirectory() || originalsStat.isSymbolicLink()) {
+    throw migrationError("INVALID_MIGRATION_SNAPSHOT", "migration originals directory is invalid");
+  }
+  assertPrivateMode(originalsStat, 0o700, "INVALID_MIGRATION_SNAPSHOT", "migration originals directory");
+  const manifestPath = path.join(resolvedSnapshot, MANIFEST_FILE);
+  const hashPath = path.join(resolvedSnapshot, MANIFEST_HASH_FILE);
+  const manifestStat = assertRegularFile(manifestPath, "INVALID_MIGRATION_MANIFEST", "migration manifest");
+  const manifestHashStat = assertRegularFile(hashPath, "INVALID_MIGRATION_MANIFEST", "migration manifest checksum");
+  assertPrivateMode(manifestStat, 0o600, "INVALID_MIGRATION_MANIFEST", "migration manifest");
+  assertPrivateMode(manifestHashStat, 0o600, "INVALID_MIGRATION_MANIFEST", "migration manifest checksum");
+  const manifestBytes = fs.readFileSync(manifestPath);
+  const expectedManifestHash = fs.readFileSync(hashPath, "utf8").trim();
+  if (!/^[a-f0-9]{64}$/.test(expectedManifestHash) || sha256(manifestBytes) !== expectedManifestHash) {
+    throw migrationError("MANIFEST_CHECKSUM_MISMATCH", "migration manifest checksum verification failed");
+  }
+  let manifest;
+  try { manifest = JSON.parse(manifestBytes.toString("utf8")); }
+  catch (_) { throw migrationError("INVALID_MIGRATION_MANIFEST", "migration manifest is invalid JSON"); }
+  validateManifestShape(manifest);
+  for (const entry of manifest.files) {
+    const filePath = backupPath(resolvedSnapshot, entry.path);
+    if (!entry.present) {
+      if (fs.existsSync(filePath)) throw migrationError("BACKUP_CHECKSUM_MISMATCH", `unexpected backup data exists for ${entry.path}`);
+      continue;
+    }
+    if (!fs.existsSync(filePath)) throw migrationError("BACKUP_CHECKSUM_MISMATCH", `backup file is missing: ${entry.path}`);
+    const stat = assertRegularFile(filePath, "BACKUP_CHECKSUM_MISMATCH", `backup file ${entry.path}`);
+    assertPrivateMode(stat, 0o600, "BACKUP_CHECKSUM_MISMATCH", `backup file ${entry.path}`);
+    const bytes = fs.readFileSync(filePath);
+    if (stat.size !== entry.size || bytes.length !== entry.size || sha256(bytes) !== entry.sha256) {
+      throw migrationError("BACKUP_CHECKSUM_MISMATCH", `backup checksum verification failed: ${entry.path}`);
+    }
+  }
+  if (options.verifySources) assertSourcesMatch(manifest, options.sources || []);
+  return { ok: true, manifest, manifestSha256: expectedManifestHash, snapshotDir: resolvedSnapshot };
+}
+
+function uniqueSnapshotDir(root, now, idFactory) {
+  const stamp = now.toISOString().replace(/[:.]/g, "-");
+  const snapshotsRoot = path.join(root, "snapshots");
+  ensureDirectory(snapshotsRoot);
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const suffix = String(idFactory()).replace(/[^A-Za-z0-9_-]/g, "-").slice(0, 48) || crypto.randomBytes(6).toString("hex");
+    const snapshotDir = path.join(snapshotsRoot, `${stamp}-${suffix}`);
+    try {
+      fs.mkdirSync(snapshotDir, { mode: 0o700 });
+      fs.chmodSync(snapshotDir, 0o700);
+      ensureDirectory(path.join(snapshotDir, "originals"));
+      return snapshotDir;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+    }
+  }
+  throw migrationError("MIGRATION_SNAPSHOT_COLLISION", "could not allocate a unique migration snapshot directory");
+}
+
+function initialJournal(snapshotDir, root, manifestHash, createdAt, previous) {
+  const components = Object.fromEntries(REQUIRED_ACTIVATION_COMPONENTS.map((component) => [component, null]));
+  const prior = Array.isArray(previous?.previousSnapshots) ? [...previous.previousSnapshots] : [];
+  if (previous?.snapshot) prior.push(previous.snapshot);
+  return {
+    formatVersion: FORMAT_VERSION,
+    migrationId: MIGRATION_ID,
+    snapshot: path.relative(root, snapshotDir).split(path.sep).join("/"),
+    manifestSha256: manifestHash,
+    stage: "prepared",
+    stages: {
+      prepared: { at: createdAt },
+      validated: null,
+      activated: null,
+    },
+    components,
+    pendingComponents: {},
+    previousSnapshots: [...new Set(prior)],
+    rollbacks: [],
+  };
+}
+
+function createSnapshot(configDir, sources, options, previousJournal) {
+  const root = migrationRoot(configDir);
+  const nowValue = options.now ? options.now() : new Date();
+  const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+  if (!Number.isFinite(now.getTime())) throw migrationError("INVALID_MIGRATION_CONFIG", "migration clock returned an invalid date");
+  const idFactory = options.idFactory || (() => crypto.randomBytes(6).toString("hex"));
+  const snapshotDir = uniqueSnapshotDir(root, now, idFactory);
+  const files = [];
+  for (const source of sources) {
+    const raw = readSource(source);
+    const guess = schemaGuess(raw, source);
+    const entry = {
+      path: source.path,
+      present: raw !== null,
+      size: raw === null ? null : raw.length,
+      sha256: raw === null ? null : sha256(raw),
+      mode: raw === null ? null : (fs.lstatSync(source.sourcePath).mode & 0o777),
+      schemaGuess: guess.schemaGuess,
+      resolution: guess.resolution,
+    };
+    if (raw !== null) {
+      const destination = backupPath(snapshotDir, source.path);
+      writeSecureFile(destination, raw, { exclusive: true });
+      fault(options, `before-copy-verify:${source.path}`, { backupPath: destination, path: source.path });
+      const copied = fs.readFileSync(destination);
+      if (copied.length !== entry.size || sha256(copied) !== entry.sha256) {
+        throw migrationError("BACKUP_VERIFICATION_FAILED", `backup copy verification failed: ${source.path}`);
+      }
+      const current = readSource(source);
+      if (current === null || current.length !== entry.size || sha256(current) !== entry.sha256) {
+        throw migrationError("MIGRATION_SOURCE_CHANGED", `migration source changed while copying: ${source.path}`);
+      }
+    }
+    files.push(entry);
+    fault(options, `after-copy:${source.path}`, { path: source.path });
+  }
+
+  const manifest = {
+    formatVersion: FORMAT_VERSION,
+    migrationId: MIGRATION_ID,
+    snapshotId: path.basename(snapshotDir),
+    createdAt: now.toISOString(),
+    creation: {
+      tool: "open-claudia-provider-migration",
+      purpose: "pre-provider-schema byte snapshot",
+      hashAlgorithm: "sha256",
+      sourceSet: "state-sessions-jobs-and-legacy-crons-v1",
+      fileCount: files.filter((entry) => entry.present).length,
+    },
+    files,
+  };
+  const manifestBytes = Buffer.from(stableJson(manifest));
+  const manifestHash = sha256(manifestBytes);
+  writeSecureFile(path.join(snapshotDir, MANIFEST_FILE), manifestBytes, { exclusive: true });
+  writeSecureFile(path.join(snapshotDir, MANIFEST_HASH_FILE), `${manifestHash}\n`, { exclusive: true });
+  fsyncDirectory(snapshotDir);
+  fault(options, "after-manifest", { snapshotDir });
+
+  let journal = initialJournal(snapshotDir, root, manifestHash, now.toISOString(), previousJournal);
+  writeJournal(configDir, journal);
+  fault(options, "after-prepared", { snapshotDir });
+  fault(options, "before-source-validation", { snapshotDir });
+  assertSourcesMatch(manifest, sources);
+  validateMigrationSnapshot(snapshotDir);
+  journal = {
+    ...journal,
+    stage: "validated",
+    stages: { ...journal.stages, validated: { at: now.toISOString() } },
+  };
+  writeJournal(configDir, journal);
+  fault(options, "after-validated", { snapshotDir });
+  return { snapshotDir, manifest, journal, reused: false };
+}
+
+function ensureMigrationSnapshot(options = {}) {
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const sources = normalizeSources(options.sources || defaultMigrationSources({ configDir }));
+  const root = migrationRoot(configDir);
+  ensureDirectory(root);
+  const release = acquireLock(root);
+  try {
+    fault(options, "after-lock", {});
+    const current = readMigrationJournal(configDir);
+    if (current) {
+      const currentSnapshot = snapshotPathFromJournal(root, current);
+      const validated = validateMigrationSnapshot(currentSnapshot);
+      if (current.manifestSha256 !== validated.manifestSha256) {
+        throw migrationError("MANIFEST_CHECKSUM_MISMATCH", "migration journal and manifest checksums differ");
+      }
+      const comparison = compareSources(validated.manifest, sources);
+      if (comparison.ok) {
+        let journal = current;
+        if (journal.stage === "prepared") {
+          const nowValue = options.now ? options.now() : new Date();
+          const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+          journal = {
+            ...journal,
+            stage: "validated",
+            stages: { ...journal.stages, validated: { at: now.toISOString() } },
+          };
+          writeJournal(configDir, journal);
+          fault(options, "after-validated", { snapshotDir: currentSnapshot });
+        }
+        return { snapshotDir: currentSnapshot, manifest: validated.manifest, journal, reused: true };
+      }
+      if (current.stage === "activated") {
+        return { snapshotDir: currentSnapshot, manifest: validated.manifest, journal: current, reused: true, sourceChangedAfterActivation: true };
+      }
+      const changingComponents = REQUIRED_ACTIVATION_COMPONENTS.filter((component) => (
+        !!current.components?.[component] || !!current.pendingComponents?.[component]
+      ));
+      if (changingComponents.length > 0) {
+        // A component migration intentionally changes its live source. Keep the
+        // one pre-migration rollback point across restarts, while still
+        // refusing any unexpected change to a component that has not migrated.
+        for (const component of REQUIRED_ACTIVATION_COMPONENTS) {
+          if (!current.components?.[component] && !current.pendingComponents?.[component]) {
+            assertMigrationComponentSourcesMatch(validated.manifest, sources, component);
+          }
+        }
+        return {
+          snapshotDir: currentSnapshot,
+          manifest: validated.manifest,
+          journal: current,
+          reused: true,
+          sourceChangedAfterPartialActivation: true,
+        };
+      }
+    }
+    return createSnapshot(configDir, sources, options, current);
+  } finally {
+    release();
+  }
+}
+
+function markMigrationComponentPrepared(snapshotDir, component, options = {}) {
+  if (!REQUIRED_ACTIVATION_COMPONENTS.includes(component)) {
+    throw migrationError("INVALID_MIGRATION_COMPONENT", `unknown migration component: ${component}`);
+  }
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const sources = normalizeSources(options.sources || defaultMigrationSources({ configDir }));
+  const root = migrationRoot(configDir);
+  const release = acquireLock(root);
+  try {
+    const validated = validateMigrationSnapshot(snapshotDir);
+    const journal = readMigrationJournal(configDir);
+    if (!journal) throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal is missing");
+    assertSnapshotMatchesJournal(snapshotDir, configDir, journal, validated);
+    if (!journal.stages?.validated) throw migrationError("MIGRATION_NOT_VALIDATED", "migration snapshot has not been validated");
+    if (journal.components?.[component] || journal.pendingComponents?.[component]) return journal;
+    if (options.requireSourceMatch !== false) {
+      assertMigrationComponentSourcesMatch(validated.manifest, sources, component);
+    }
+    const nowValue = options.now ? options.now() : new Date();
+    const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+    const next = {
+      ...journal,
+      pendingComponents: {
+        ...(journal.pendingComponents || {}),
+        [component]: { at: now.toISOString() },
+      },
+    };
+    writeJournal(configDir, next);
+    fault(options, `after-prepare:${component}`, { component });
+    return next;
+  } finally {
+    release();
+  }
+}
+
+function requireMigrationSnapshotForComponent(component, options = {}) {
+  if (!REQUIRED_ACTIVATION_COMPONENTS.includes(component)) {
+    throw migrationError("INVALID_MIGRATION_COMPONENT", `unknown migration component: ${component}`);
+  }
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const sources = normalizeSources(options.sources || defaultMigrationSources({ configDir }));
+  const existing = readMigrationJournal(configDir);
+  if (!existing) return ensureMigrationSnapshot({ ...options, configDir, sources });
+
+  const snapshotDir = snapshotPathFromJournal(migrationRoot(configDir), existing);
+  const validated = validateMigrationSnapshot(snapshotDir);
+  if (existing.manifestSha256 !== validated.manifestSha256 || !existing.stages?.validated) {
+    throw migrationError("MIGRATION_NOT_VALIDATED", "migration snapshot has not been validated");
+  }
+  if (!existing.components?.[component] && !options.allowSourceMismatch) {
+    assertMigrationComponentSourcesMatch(validated.manifest, sources, component);
+  }
+  return {
+    snapshotDir,
+    manifest: validated.manifest,
+    journal: existing,
+    reused: true,
+    componentAlreadyActivated: !!existing.components?.[component],
+  };
+}
+
+function assertSnapshotMatchesJournal(snapshotDir, configDir, journal, validated) {
+  const root = migrationRoot(configDir);
+  const expected = snapshotPathFromJournal(root, journal);
+  if (path.resolve(snapshotDir) !== expected || journal.manifestSha256 !== validated.manifestSha256) {
+    throw migrationError("MIGRATION_SNAPSHOT_MISMATCH", "migration snapshot does not match the active journal");
+  }
+}
+
+function markMigrationComponentActivated(snapshotDir, component, options = {}) {
+  if (!REQUIRED_ACTIVATION_COMPONENTS.includes(component)) {
+    throw migrationError("INVALID_MIGRATION_COMPONENT", `unknown migration component: ${component}`);
+  }
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const sources = normalizeSources(options.sources || defaultMigrationSources({ configDir }));
+  const root = migrationRoot(configDir);
+  const release = acquireLock(root);
+  try {
+    const validated = validateMigrationSnapshot(snapshotDir);
+    const journal = readMigrationJournal(configDir);
+    if (!journal) throw migrationError("INVALID_MIGRATION_JOURNAL", "migration journal is missing");
+    assertSnapshotMatchesJournal(snapshotDir, configDir, journal, validated);
+    if (!journal.stages?.validated) throw migrationError("MIGRATION_NOT_VALIDATED", "migration snapshot has not been validated");
+    if (options.requireSourceMatch) assertSourcesMatch(validated.manifest, sources);
+    const proof = migratedComponentProof(sources, component);
+    const previous = journal.components?.[component];
+    if (proofMatches(previous, proof)) return journal;
+    if (!previous && !journal.pendingComponents?.[component]) {
+      throw migrationError("MIGRATION_COMPONENT_NOT_PREPARED", `${component} migration has not been prepared`);
+    }
+    const nowValue = options.now ? options.now() : new Date();
+    const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+    const components = {
+      ...(journal.components || {}),
+      [component]: { at: previous?.at || now.toISOString(), ...proof },
+    };
+    const pendingComponents = { ...(journal.pendingComponents || {}) };
+    delete pendingComponents[component];
+    const allActivated = REQUIRED_ACTIVATION_COMPONENTS.every((name) => !!components[name]);
+    const next = {
+      ...journal,
+      stage: allActivated ? "activated" : "validated",
+      components,
+      pendingComponents,
+      stages: {
+        ...journal.stages,
+        activated: allActivated ? (journal.stages.activated || { at: now.toISOString() }) : null,
+      },
+    };
+    writeJournal(configDir, next);
+    fault(options, `after-activation:${component}`, { component });
+    return next;
+  } finally {
+    release();
+  }
+}
+
+function requireProviderRemovalReady(options = {}) {
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const sources = normalizeSources(options.sources || defaultMigrationSources({ configDir }));
+  const journal = readMigrationJournal(configDir);
+  if (!journal) throw migrationError("PROVIDER_REMOVAL_NOT_READY", "provider removal requires a validated migration journal");
+  const snapshotDir = snapshotPathFromJournal(migrationRoot(configDir), journal);
+  const validated = validateMigrationSnapshot(snapshotDir);
+  if (!journal.stages?.validated || journal.manifestSha256 !== validated.manifestSha256) {
+    throw migrationError("PROVIDER_REMOVAL_NOT_READY", "provider removal requires a valid migration snapshot");
+  }
+  const missing = REQUIRED_ACTIVATION_COMPONENTS.filter((component) => !journal.components?.[component]);
+  if (journal.stage !== "activated" || missing.length) {
+    throw migrationError(
+      "PROVIDER_REMOVAL_NOT_READY",
+      `provider removal requires completed state, sessions, and jobs migrations${missing.length ? `; pending: ${missing.join(", ")}` : ""}`,
+      { missing },
+    );
+  }
+  for (const component of REQUIRED_ACTIVATION_COMPONENTS) {
+    let proof;
+    try { proof = migratedComponentProof(sources, component); }
+    catch (error) {
+      throw migrationError(
+        "PROVIDER_REMOVAL_NOT_READY",
+        `provider removal requires valid ${component} migration output`,
+        { component, cause: error.code || error.name },
+      );
+    }
+    if (!proofMatches(journal.components[component], proof)) {
+      throw migrationError(
+        "PROVIDER_REMOVAL_NOT_READY",
+        `provider removal certification is stale for ${component}`,
+        { component },
+      );
+    }
+  }
+  return { snapshotDir, manifest: validated.manifest, journal };
+}
+
+function targetMapForManifest(manifest, sources) {
+  const byPath = sourceMap(sources);
+  for (const entry of manifest.files) {
+    if (!byPath.has(entry.path)) throw migrationError("INVALID_MIGRATION_CONFIG", `rollback target is missing: ${entry.path}`);
+  }
+  return byPath;
+}
+
+function rollbackMigrationSnapshot(snapshotDir, options = {}) {
+  const configDir = path.resolve(options.configDir || "");
+  if (!options.configDir) throw migrationError("INVALID_MIGRATION_CONFIG", "configDir is required");
+  const root = migrationRoot(configDir);
+  const release = acquireLock(root);
+  const staged = [];
+  try {
+    // Full snapshot verification deliberately precedes every target mutation.
+    const validated = validateMigrationSnapshot(snapshotDir);
+    const targets = targetMapForManifest(validated.manifest, options.sources || []);
+    const journal = readMigrationJournal(configDir);
+    if (journal) assertSnapshotMatchesJournal(snapshotDir, configDir, journal, validated);
+    fault(options, "before-rollback", {});
+
+    for (const entry of validated.manifest.files) {
+      const target = targets.get(entry.path).sourcePath;
+      if (fs.existsSync(target)) assertRegularFile(target, "UNSAFE_ROLLBACK_TARGET", `rollback target ${entry.path}`);
+      if (!entry.present) {
+        staged.push({ entry, target, temp: null });
+        continue;
+      }
+      ensureDirectory(path.dirname(target));
+      const temp = `${target}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.rollback.tmp`;
+      writeSecureFile(temp, fs.readFileSync(backupPath(snapshotDir, entry.path)), { exclusive: true, privateParent: false });
+      staged.push({ entry, target, temp });
+      fault(options, `after-rollback-stage:${entry.path}`, { path: entry.path });
+    }
+
+    for (const item of staged) {
+      if (item.entry.present) {
+        fs.renameSync(item.temp, item.target);
+        item.temp = null;
+        try { fs.chmodSync(item.target, item.entry.mode); } catch (_) {}
+      } else if (fs.existsSync(item.target)) {
+        fs.unlinkSync(item.target);
+      }
+      fsyncDirectory(path.dirname(item.target));
+      fault(options, `after-rollback:${item.entry.path}`, { path: item.entry.path });
+    }
+
+    assertSourcesMatch(validated.manifest, options.sources || []);
+    if (journal) {
+      const nowValue = options.now ? options.now() : new Date();
+      const now = nowValue instanceof Date ? nowValue : new Date(nowValue);
+      writeJournal(configDir, {
+        ...journal,
+        rollbacks: [...(journal.rollbacks || []), { at: now.toISOString(), verified: true }],
+      });
+    }
+    return { ok: true, restored: validated.manifest.files.length, snapshotDir: path.resolve(snapshotDir) };
+  } finally {
+    for (const item of staged) {
+      try { if (item.temp && fs.existsSync(item.temp)) fs.unlinkSync(item.temp); } catch (_) {}
+    }
+    release();
+  }
+}
+
+module.exports = {
+  FORMAT_VERSION,
+  MIGRATION_ID,
+  REQUIRED_ACTIVATION_COMPONENTS,
+  assertMigrationComponentSourcesMatch,
+  assertSourcesMatch,
+  defaultMigrationSources,
+  ensureMigrationSnapshot,
+  markMigrationComponentActivated,
+  markMigrationComponentPrepared,
+  migrationRoot,
+  normalizeLogicalPath,
+  normalizeSources,
+  readMigrationJournal,
+  requireProviderRemovalReady,
+  requireMigrationSnapshotForComponent,
+  rollbackMigrationSnapshot,
+  sha256,
+  validateMigrationSnapshot,
+};