ultra-builder-pro-cli 0.20.0 → 0.21.1

package/ultra-tools/commands/migrate.cjs

@@ -2,14 +2,20 @@
 
 const fs = require('node:fs');
 const path = require('node:path');
+const { createHash } = require('node:crypto');
+const Database = require('better-sqlite3');
 
 const {
   EXPECTED_VERSION, initStateDb, openStateDb, closeStateDb, MIGRATED_GAPS,
 } = require('../../mcp-server/lib/state-db.cjs');
 const ops = require('../../mcp-server/lib/state-ops.cjs');
 const projector = require('../../mcp-server/lib/projector.cjs');
+const runtimePaths = require('../../mcp-server/lib/runtime-paths.cjs');
+const contextPaths = require('../../mcp-server/lib/context-paths.cjs');
 
 const DEFAULT_FROM = '4.4';
+const BACKUP_MANIFEST = 'backup-manifest.json';
+const BACKUP_MANIFEST_KIND = 'ultra-projection-backup';
 const SUPPORTED_TRANSITIONS = Object.freeze({
   '4.4': '4.5',
   '4.5': EXPECTED_VERSION,
@@ -64,23 +70,148 @@ function readJsonOptional(p) {
   return JSON.parse(fs.readFileSync(p, 'utf8'));
 }
 
-function findContexts(rootDir) {
-  const dir = path.join(rootDir, '.ultra', 'tasks', 'contexts');
+function findContexts(rootDir, ultraDir = path.join(rootDir, '.ultra')) {
+  const dir = path.join(ultraDir, 'tasks', 'contexts');
   if (!fs.existsSync(dir)) return [];
   return fs.readdirSync(dir)
     .filter((f) => f.endsWith('.md'))
     .map((f) => path.join(dir, f));
 }
 
-function copyDirSync(src, dst) {
+function lstatOrNull(candidate) {
+  try {
+    return fs.lstatSync(candidate);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+function assertRealDirectory(candidate, label) {
+  const stat = lstatOrNull(candidate);
+  if (!stat || stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new Error(`migrate: ${label} must be a real directory: ${candidate}`);
+  }
+  return stat;
+}
+
+function assertRegularTree(root, label) {
+  assertRealDirectory(root, label);
+  const pending = fs.readdirSync(root).map((entry) => path.join(root, entry));
+  while (pending.length > 0) {
+    const candidate = pending.pop();
+    const stat = fs.lstatSync(candidate);
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+      throw new Error(
+        `migrate: ${label} contains a symlink or non-regular entry: ${candidate}`,
+      );
+    }
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(candidate)) {
+        pending.push(path.join(candidate, entry));
+      }
+    }
+  }
+}
+
+function copyDirSync(src, dst, {
+  copyFileSync = fs.copyFileSync,
+  excludeAuthorityRoot = true,
+} = {}) {
+  assertRealDirectory(src, 'copy source');
   fs.mkdirSync(dst, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const s = path.join(src, entry.name);
     const d = path.join(dst, entry.name);
-    if (entry.name === 'state.db' || entry.name === 'state.db-wal' || entry.name === 'state.db-shm') continue;
-    if (/^backup-v[^/]+-/.test(entry.name)) continue;
-    if (entry.isDirectory()) copyDirSync(s, d);
-    else fs.copyFileSync(s, d);
+    if (excludeAuthorityRoot && entry.name === '.runtime') continue;
+    if (excludeAuthorityRoot
+        && ['state.db', 'state.db-wal', 'state.db-shm'].includes(entry.name)) continue;
+    if (excludeAuthorityRoot && /^backup-v[^/]+-/.test(entry.name)) continue;
+    if (entry.isDirectory()) {
+      copyDirSync(s, d, { copyFileSync, excludeAuthorityRoot: false });
+    }
+    else if (entry.isFile()) copyFileSync(s, d);
+    else {
+      throw new Error(
+        `migrate: copy source contains a symlink or non-regular entry: ${s}`,
+      );
+    }
+  }
+}
+
+function fileDigest(candidate) {
+  return createHash('sha256').update(fs.readFileSync(candidate)).digest('hex');
+}
+
+function regularTreeInventory(root, { excludeRootEntries = [] } = {}) {
+  assertRegularTree(root, 'inventory tree');
+  const inventory = [];
+  const excluded = new Set(excludeRootEntries);
+  const pending = fs.readdirSync(root)
+    .filter((entry) => !excluded.has(entry))
+    .map((entry) => path.join(root, entry));
+  while (pending.length > 0) {
+    const candidate = pending.pop();
+    const stat = fs.lstatSync(candidate);
+    const relative = path.relative(root, candidate).split(path.sep).join('/');
+    if (stat.isDirectory()) {
+      inventory.push({ path: `${relative}/`, kind: 'directory' });
+      for (const entry of fs.readdirSync(candidate)) pending.push(path.join(candidate, entry));
+    } else {
+      inventory.push({
+        path: relative,
+        kind: 'file',
+        size: stat.size,
+        sha256: fileDigest(candidate),
+      });
+    }
+  }
+  return inventory.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function jsonDigest(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+function backupInventory(root) {
+  return regularTreeInventory(root, { excludeRootEntries: [BACKUP_MANIFEST] });
+}
+
+function backupManifest(inventory, fromVersion, createdAt) {
+  return {
+    version: 1,
+    kind: BACKUP_MANIFEST_KIND,
+    source_version: String(fromVersion),
+    created_at: createdAt,
+    inventory,
+    inventory_sha256: jsonDigest(inventory),
+  };
+}
+
+function validateBackupManifestDocument(manifest, fromVersion, label) {
+  if (!manifest
+      || manifest.version !== 1
+      || manifest.kind !== BACKUP_MANIFEST_KIND
+      || manifest.source_version !== String(fromVersion)
+      || !Array.isArray(manifest.inventory)
+      || !/^[a-f0-9]{64}$/.test(manifest.inventory_sha256 || '')
+      || manifest.inventory_sha256 !== jsonDigest(manifest.inventory)) {
+    throw new Error(`migrate: ${label} has an invalid backup manifest`);
+  }
+  return {
+    manifest,
+    manifestDigest: jsonDigest(manifest),
+    inventoryDigest: manifest.inventory_sha256,
+  };
+}
+
+function projectionInventory(root) {
+  const stage = fs.mkdtempSync(path.join(path.dirname(root), '.inventory-stage-'));
+  try {
+    copyDirSync(root, stage);
+    return regularTreeInventory(stage);
+  } finally {
+    fs.rmSync(stage, { recursive: true, force: true });
   }
 }
 
@@ -95,17 +226,14 @@ function isoTimestamp(value, fallback) {
 
 function projectRelativeContextPath(sourceDir, value) {
   if (!value) return null;
-  const normalized = String(value).replaceAll('\\', '/');
-  if (normalized.startsWith('.ultra/')) return normalized;
-  if (normalized.startsWith('contexts/')) return `.ultra/tasks/${normalized}`;
-  if (path.isAbsolute(value)) {
-    const relative = path.relative(sourceDir, value).replaceAll(path.sep, '/');
-    if (relative.startsWith('../') || relative === '..') {
-      throw new Error(`migrate: context_file escapes project root: ${value}`);
-    }
-    return relative;
+  try {
+    return contextPaths.resolveContextPath(sourceDir, value, {
+      allowLegacyAliases: true,
+    }).relative;
+  } catch (error) {
+    if (error.code !== 'CONTEXT_PATH_INVALID') throw error;
+    throw new Error(`migrate: context_file rejected: ${error.message}`, { cause: error });
   }
-  return `.ultra/tasks/contexts/${path.basename(normalized)}`;
 }
 
 function sanitizeLegacyContextTemplate(sourceDir) {
@@ -153,8 +281,10 @@ function normalizeLegacyTask(task, tasksJson, contextHeaders, sourceDir) {
   };
 }
 
-function planForward(sourceDir, expectedFrom = DEFAULT_FROM) {
-  const tasksPath = path.join(sourceDir, '.ultra', 'tasks', 'tasks.json');
+function planForward(sourceDir, expectedFrom = DEFAULT_FROM, {
+  ultraDir = path.join(sourceDir, '.ultra'),
+} = {}) {
+  const tasksPath = path.join(ultraDir, 'tasks', 'tasks.json');
   const tasksJson = readJsonOptional(tasksPath);
   if (!tasksJson || !Array.isArray(tasksJson.tasks)) {
     throw new Error(`migrate: tasks.json missing or malformed at ${tasksPath}`);
@@ -165,9 +295,18 @@ function planForward(sourceDir, expectedFrom = DEFAULT_FROM) {
   }
 
   const contextHeaders = {};
-  for (const file of findContexts(sourceDir)) {
+  for (const file of findContexts(sourceDir, ultraDir)) {
     const fm = parseFrontmatter(fs.readFileSync(file, 'utf8'));
-    if (fm && fm.task_id) contextHeaders[fm.task_id] = { ...fm, _file: file };
+    if (fm && fm.task_id) {
+      contextHeaders[fm.task_id] = {
+        ...fm,
+        _file: path.join(
+          sourceDir,
+          '.ultra',
+          path.relative(ultraDir, file),
+        ),
+      };
+    }
   }
 
   const warnings = [];
@@ -183,7 +322,7 @@ function planForward(sourceDir, expectedFrom = DEFAULT_FROM) {
     }
   }
 
-  const eventsPath = path.join(sourceDir, '.ultra', 'activity-log.json');
+  const eventsPath = path.join(ultraDir, 'activity-log.json');
   const events = readJsonOptional(eventsPath);
   const eventList = Array.isArray(events) ? events : [];
   const tasks = tasksJson.tasks.map((task) => (
@@ -249,26 +388,800 @@ function recordMigration(db, { from, to, direction, status, notes }) {
 
 function ensureBackupName(sourceDir, fromVersion = DEFAULT_FROM) {
   const ts = new Date().toISOString().replace(/[:.]/g, '-');
-  return path.join(sourceDir, '.ultra', `backup-v${fromVersion}-${ts}`);
+  const parent = runtimePaths.pathsFor(sourceDir).backupsDir;
+  const prefix = `projection-v${fromVersion}-${ts}`;
+  let candidate = path.join(parent, prefix);
+  let attempt = 0;
+  while (lstatOrNull(candidate)) {
+    attempt += 1;
+    candidate = path.join(parent, `${prefix}-${attempt}`);
+  }
+  return candidate;
+}
+
+function createProjectionBackup(sourceDir, fromVersion, {
+  copyFileSync = fs.copyFileSync,
+  renameSync = fs.renameSync,
+} = {}) {
+  const paths = runtimePaths.pathsFor(sourceDir);
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const stage = path.join(sourceDir, `.ultra-migrate-stage-${token}`);
+  const finalPath = ensureBackupName(sourceDir, fromVersion);
+  try {
+    copyDirSync(paths.ultraDir, stage, { copyFileSync });
+    const expected = projectionInventory(paths.ultraDir);
+    const actual = regularTreeInventory(stage);
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+      throw new Error('migrate: staged projection backup inventory does not match source');
+    }
+    writeJsonAtomic(
+      path.join(stage, BACKUP_MANIFEST),
+      backupManifest(actual, fromVersion, new Date().toISOString()),
+    );
+    assertRollbackBackup(sourceDir, stage, fromVersion, { staged: true });
+    fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+    renameSync(stage, finalPath);
+    return finalPath;
+  } catch (error) {
+    try { fs.rmSync(stage, { recursive: true, force: true }); } catch { /* recovery path remains */ }
+    throw error;
+  }
+}
+
+function prepareForwardSnapshot(sourceDir, fromVersion, {
+  afterBackup = null,
+  ...backupOptions
+} = {}) {
+  const backupDir = createProjectionBackup(sourceDir, fromVersion, backupOptions);
+  if (afterBackup) afterBackup({ sourceDir, backupDir });
+  const bound = assertRollbackBackup(sourceDir, backupDir, fromVersion);
+  const current = projectionInventory(runtimePaths.pathsFor(sourceDir).ultraDir);
+  if (JSON.stringify(current) !== JSON.stringify(bound.manifest.inventory)) {
+    throw new Error(
+      'migrate: semantic source changed after the immutable backup snapshot; replan required',
+    );
+  }
+  const plan = planForward(sourceDir, fromVersion, { ultraDir: backupDir });
+  return { backupDir, plan, manifest: bound.manifest };
+}
+
+function backupTimestampFromName(candidate) {
+  const match = path.basename(candidate).match(
+    /(\d{4}-\d{2}-\d{2}T\d{2})-(\d{2})-(\d{2})-(\d{3})Z(?:-\d+)?$/,
+  );
+  if (!match) return null;
+  const value = `${match[1]}:${match[2]}:${match[3]}.${match[4]}Z`;
+  const timestamp = Date.parse(value);
+  return Number.isFinite(timestamp) ? timestamp : null;
+}
+
+function backupTimestampFromMetadata(candidate) {
+  for (const name of ['.backup-metadata.json', 'backup-metadata.json']) {
+    const metadataPath = path.join(candidate, name);
+    const stat = lstatOrNull(metadataPath);
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || !stat.isFile()) return null;
+    try {
+      const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      const timestamp = Date.parse(metadata.created_at || metadata.createdAt || '');
+      if (Number.isFinite(timestamp)) return timestamp;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function backupSortKey(candidate) {
+  const stat = fs.lstatSync(candidate);
+  return [
+    backupTimestampFromMetadata(candidate)
+      ?? backupTimestampFromName(candidate)
+      ?? stat.mtimeMs,
+    stat.mtimeMs,
+    candidate,
+  ];
 }
 
 function findLatestBackup(sourceDir, fromVersion = DEFAULT_FROM) {
-  const ultra = path.join(sourceDir, '.ultra');
-  if (!fs.existsSync(ultra)) return null;
-  const prefix = `backup-v${fromVersion}-`;
-  const candidates = fs.readdirSync(ultra)
-    .filter((n) => n.startsWith(prefix))
-    .sort();
-  return candidates.length === 0 ? null : path.join(ultra, candidates[candidates.length - 1]);
+  runtimePaths.validateProjectLayout(sourceDir, {
+    env: {},
+    validateRuntimeTree: true,
+  });
+  const roots = [
+    {
+      dir: runtimePaths.pathsFor(sourceDir).backupsDir,
+      prefix: `projection-v${fromVersion}-`,
+    },
+    {
+      dir: path.join(sourceDir, '.ultra'),
+      prefix: `backup-v${fromVersion}-`,
+    },
+  ];
+  const candidates = roots.flatMap(({ dir, prefix }) => (
+    fs.existsSync(dir)
+      ? fs.readdirSync(dir)
+        .filter((name) => name.startsWith(prefix))
+        .map((name) => path.join(dir, name))
+      : []
+  ));
+  const valid = [];
+  const invalid = [];
+  for (const candidate of candidates) {
+    try {
+      assertRollbackBackup(sourceDir, candidate, fromVersion);
+      valid.push(candidate);
+    } catch (error) {
+      invalid.push(error);
+    }
+  }
+  if (valid.length === 0) {
+    if (invalid.length > 0) throw invalid[0];
+    return null;
+  }
+  valid.sort((left, right) => {
+    const a = backupSortKey(left);
+    const b = backupSortKey(right);
+    return a[0] - b[0] || a[1] - b[1] || a[2].localeCompare(b[2]);
+  });
+  return valid.at(-1);
+}
+
+function assertRollbackBackup(sourceDir, backupDir, fromVersion, { staged = false } = {}) {
+  const paths = runtimePaths.validateProjectLayout(sourceDir, { env: {} });
+  if (!staged) {
+    const allowedParents = [
+      paths.backupsDir,
+      paths.ultraDir,
+    ];
+    const parent = path.dirname(path.resolve(backupDir));
+    if (!allowedParents.includes(parent)) {
+      throw new Error(`migrate: rollback backup is outside a managed backup root: ${backupDir}`);
+    }
+    if (parent === paths.backupsDir) {
+      assertRealDirectory(paths.backupsDir, 'runtime backup root');
+    }
+  }
+  assertRegularTree(backupDir, 'rollback backup');
+  for (const entry of fs.readdirSync(backupDir, { withFileTypes: true })) {
+    const candidate = path.join(backupDir, entry.name);
+    if (entry.name === '.runtime'
+        || entry.name === 'state.db'
+        || entry.name === 'state.db-wal'
+        || entry.name === 'state.db-shm') {
+      throw new Error(`migrate: rollback backup contains a runtime authority entry: ${candidate}`);
+    }
+  }
+  // Traversing the source with the same copier used for staging proves every
+  // nested entry is a real directory or regular file before current state moves.
+  const tasksPath = path.join(backupDir, 'tasks', 'tasks.json');
+  const tasksStat = lstatOrNull(tasksPath);
+  if (!tasksStat || tasksStat.isSymbolicLink() || !tasksStat.isFile()) {
+    throw new Error(`migrate: rollback backup has no regular tasks/tasks.json: ${tasksPath}`);
+  }
+  const tasks = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+  const version = String(tasks.version || tasks.schema_version || '');
+  if (version !== String(fromVersion) || !Array.isArray(tasks.tasks)) {
+    throw new Error(
+      `migrate: rollback backup is not a valid v${fromVersion} projection snapshot`,
+    );
+  }
+  const inventory = backupInventory(backupDir);
+  const manifestPath = path.join(backupDir, BACKUP_MANIFEST);
+  const manifestStat = lstatOrNull(manifestPath);
+  const requiresManifest = path.basename(backupDir).startsWith(`projection-v${fromVersion}-`);
+  let manifest;
+  if (manifestStat) {
+    if (manifestStat.isSymbolicLink() || !manifestStat.isFile()) {
+      throw new Error(`migrate: rollback backup manifest is unsafe: ${manifestPath}`);
+    }
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    } catch (error) {
+      throw new Error(`migrate: rollback backup manifest is malformed: ${manifestPath}`, {
+        cause: error,
+      });
+    }
+  } else if (requiresManifest) {
+    throw new Error(`migrate: projection backup manifest is missing: ${manifestPath}`);
+  } else {
+    // Legacy backup-v snapshots predate cryptographic manifests. Adopt their
+    // complete current image once, before mutation, and bind that inventory to
+    // the new durable recovery journal.
+    manifest = backupManifest(
+      inventory,
+      fromVersion,
+      new Date(fs.lstatSync(backupDir).mtimeMs).toISOString(),
+    );
+  }
+  const admitted = validateBackupManifestDocument(
+    manifest,
+    fromVersion,
+    'rollback backup',
+  );
+  if (JSON.stringify(inventory) !== JSON.stringify(manifest.inventory)) {
+    throw new Error(
+      `migrate: rollback backup inventory does not match its manifest: ${backupDir}`,
+    );
+  }
+  return {
+    paths,
+    manifest: admitted.manifest,
+    manifestDigest: admitted.manifestDigest,
+    inventoryDigest: admitted.inventoryDigest,
+    manifestPath: manifestStat ? manifestPath : null,
+  };
+}
+
+function assertCurrentSemanticTree(ultraDir) {
+  assertRealDirectory(ultraDir, '.ultra');
+  const pending = fs.readdirSync(ultraDir, { withFileTypes: true })
+    .filter((entry) => entry.name !== '.runtime'
+      && entry.name !== 'state.db'
+      && entry.name !== 'state.db-wal'
+      && entry.name !== 'state.db-shm')
+    .map((entry) => path.join(ultraDir, entry.name));
+  while (pending.length > 0) {
+    const candidate = pending.pop();
+    const stat = fs.lstatSync(candidate);
+    if (stat.isSymbolicLink() || (!stat.isDirectory() && !stat.isFile())) {
+      throw new Error(
+        `migrate: current semantic tree contains a symlink or non-regular entry: ${candidate}`,
+      );
+    }
+    if (stat.isDirectory()) {
+      for (const entry of fs.readdirSync(candidate)) {
+        pending.push(path.join(candidate, entry));
+      }
+    }
+  }
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    try { fs.rmSync(tmp, { force: true }); } catch { /* best effort */ }
+    throw error;
+  }
+}
+
+function updateRollbackJournal(journalPath, patch) {
+  const current = JSON.parse(fs.readFileSync(journalPath, 'utf8'));
+  const next = {
+    ...current,
+    ...patch,
+    updated_at: new Date().toISOString(),
+  };
+  writeJsonAtomic(journalPath, next);
+  return next;
+}
+
+function rollbackRecoveryBase(paths) {
+  return path.join(paths.runtimeDir, 'recovery', 'migrate-rollback');
+}
+
+function assertRollbackRecoveryJournal(sourceDir, paths, recoveryDir, journal) {
+  const resolvedRecovery = path.resolve(recoveryDir);
+  const recoveryBase = path.resolve(rollbackRecoveryBase(paths));
+  if (path.dirname(resolvedRecovery) !== recoveryBase) {
+    throw new Error(`migrate: rollback recovery is outside its managed root: ${recoveryDir}`);
+  }
+  if (!journal || journal.version !== 1
+      || path.resolve(journal.source_dir || '') !== path.resolve(sourceDir)
+      || path.resolve(journal.recovery_dir || '') !== resolvedRecovery
+      || path.dirname(path.resolve(journal.stage_dir || '')) !== path.resolve(paths.runtimeDir)
+      || !path.basename(journal.stage_dir || '').startsWith('.rollback-stage-')
+      || path.resolve(journal.backup_manifest_path || '')
+        !== path.resolve(recoveryDir, BACKUP_MANIFEST)
+      || !/^[a-f0-9]{64}$/.test(journal.backup_manifest_sha256 || '')
+      || !/^[a-f0-9]{64}$/.test(journal.backup_inventory_sha256 || '')
+      || ![
+        'prepared',
+        'installed',
+        'cleanup_pending',
+        'complete',
+        'rolled_back',
+        'recovery_failed',
+      ].includes(journal.phase)) {
+    throw new Error(`migrate: invalid rollback recovery journal: ${recoveryDir}`);
+  }
+  const hasStateInventory = journal.previous_state_inventory !== undefined
+    || journal.previous_state_inventory_sha256 !== undefined;
+  if (hasStateInventory) {
+    if (!Array.isArray(journal.previous_state_inventory)
+        || !/^[a-f0-9]{64}$/.test(journal.previous_state_inventory_sha256 || '')
+        || jsonDigest(journal.previous_state_inventory)
+          !== journal.previous_state_inventory_sha256) {
+      throw new Error(`migrate: invalid rollback state inventory: ${recoveryDir}`);
+    }
+    const actual = regularTreeInventory(path.join(recoveryDir, 'previous-state'));
+    if (JSON.stringify(actual) !== JSON.stringify(journal.previous_state_inventory)) {
+      throw new Error(`migrate: rollback state snapshot changed after publication: ${recoveryDir}`);
+    }
+  }
+  return journal;
+}
+
+function boundRecoveryManifest(recoveryDir, journal) {
+  const manifestPath = path.join(recoveryDir, BACKUP_MANIFEST);
+  const stat = lstatOrNull(manifestPath);
+  if (!stat || stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`migrate: bound recovery manifest is missing or unsafe: ${manifestPath}`);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`migrate: bound recovery manifest is malformed: ${manifestPath}`, {
+      cause: error,
+    });
+  }
+  const admitted = validateBackupManifestDocument(
+    manifest,
+    journal.from_version,
+    'bound recovery',
+  );
+  if (admitted.manifestDigest !== journal.backup_manifest_sha256
+      || admitted.inventoryDigest !== journal.backup_inventory_sha256) {
+    throw new Error('migrate: recovery manifest digest does not match its journal binding');
+  }
+  return admitted;
+}
+
+function assertInstalledRollback(sourceDir, paths, journal) {
+  const bound = boundRecoveryManifest(journal.recovery_dir, journal);
+  assertCurrentSemanticTree(paths.ultraDir);
+  const installedInventory = projectionInventory(paths.ultraDir);
+  if (JSON.stringify(installedInventory) !== JSON.stringify(bound.manifest.inventory)) {
+    throw new Error('migrate: installed rollback inventory does not match its bound manifest');
+  }
+  const tasksPath = path.join(paths.ultraDir, 'tasks', 'tasks.json');
+  const tasks = JSON.parse(fs.readFileSync(tasksPath, 'utf8'));
+  const version = String(tasks.version || tasks.schema_version || '');
+  if (version !== String(journal.from_version)) {
+    throw new Error(
+      `migrate: installed rollback does not match v${journal.from_version}: ${tasksPath}`,
+    );
+  }
+  for (const candidate of [
+    paths.stateDbPath,
+    `${paths.stateDbPath}-wal`,
+    `${paths.stateDbPath}-shm`,
+    paths.legacyStateDbPath,
+    `${paths.legacyStateDbPath}-wal`,
+    `${paths.legacyStateDbPath}-shm`,
+  ]) {
+    if (lstatOrNull(candidate)) {
+      throw new Error(`migrate: installed rollback still exposes state authority: ${candidate}`);
+    }
+  }
+  return sourceDir;
+}
+
+function resumeRollbackRecovery(sourceDir, io = {}) {
+  const rmSync = io.rmSync || fs.rmSync;
+  const paths = runtimePaths.validateProjectLayout(sourceDir, {
+    env: {},
+    validateRuntimeTree: true,
+  });
+  const base = rollbackRecoveryBase(paths);
+  const stat = lstatOrNull(base);
+  if (!stat) return { resumed: 0, pending: 0, recoveries: [] };
+  assertRealDirectory(base, 'rollback recovery root');
+  const recoveries = [];
+  let pending = 0;
+  for (const name of fs.readdirSync(base).sort()) {
+    const recoveryDir = path.join(base, name);
+    assertRealDirectory(recoveryDir, 'rollback recovery');
+    const journalPath = path.join(recoveryDir, 'journal.json');
+    const journalStat = lstatOrNull(journalPath);
+    if (!journalStat || journalStat.isSymbolicLink() || !journalStat.isFile()) {
+      throw new Error(`migrate: rollback recovery journal is missing or unsafe: ${journalPath}`);
+    }
+    const journal = assertRollbackRecoveryJournal(
+      sourceDir,
+      paths,
+      recoveryDir,
+      JSON.parse(fs.readFileSync(journalPath, 'utf8')),
+    );
+    if (journal.phase === 'complete' || journal.phase === 'rolled_back') continue;
+    if (!['installed', 'cleanup_pending'].includes(journal.phase)) {
+      pending += 1;
+      recoveries.push({
+        recovery_dir: recoveryDir,
+        phase: journal.phase,
+        resumed: false,
+      });
+      continue;
+    }
+    assertInstalledRollback(sourceDir, paths, journal);
+    if (lstatOrNull(journal.stage_dir)) {
+      rmSync(journal.stage_dir, { recursive: true, force: true });
+    }
+    updateRollbackJournal(journalPath, {
+      phase: 'complete',
+      cleanup_error: null,
+      completed_at: new Date().toISOString(),
+    });
+    recoveries.push({
+      recovery_dir: recoveryDir,
+      phase: 'complete',
+      resumed: true,
+    });
+  }
+  return {
+    resumed: recoveries.filter((entry) => entry.resumed).length,
+    pending,
+    recoveries,
+  };
+}
+
+function sqliteFile(candidate) {
+  const stat = lstatOrNull(candidate);
+  if (!stat || stat.isSymbolicLink() || !stat.isFile()) return false;
+  const descriptor = fs.openSync(candidate, 'r');
+  try {
+    const header = Buffer.alloc(16);
+    return fs.readSync(descriptor, header, 0, header.length, 0) === header.length
+      && header.equals(Buffer.from('SQLite format 3\0'));
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
+function quoteSqlString(value) {
+  return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function immutableStateSnapshot(resolvedDb, previousState, {
+  onSnapshot = () => {},
+  afterVacuumBeforeFence = () => {},
+  maxAttempts = 5,
+} = {}) {
+  const copied = [];
+  const main = lstatOrNull(resolvedDb);
+  if (!main) {
+    onSnapshot([], { source_data_version: null, snapshot_attempts: 0 });
+    return copied;
+  }
+  if (main.isSymbolicLink() || !main.isFile()) {
+    throw new Error(`migrate: current state entry is unsafe: ${resolvedDb}`);
+  }
+  let liveDb = null;
+  let exclusive = false;
+  let sourceDataVersion = null;
+  let snapshotAttempts = 0;
+  try {
+    const snapshot = path.join(previousState, 'state.db');
+    if (sqliteFile(resolvedDb)) {
+      liveDb = new Database(resolvedDb, { fileMustExist: true });
+      liveDb.pragma('busy_timeout = 0');
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        snapshotAttempts = attempt;
+        const before = Number(liveDb.pragma('data_version', { simple: true }));
+        fs.rmSync(snapshot, { force: true });
+        // VACUUM cannot run inside the exclusive transaction. Bind its read
+        // image to the later writer fence with data_version: if any other
+        // connection commits in this gap, discard the candidate and retry.
+        liveDb.exec(`VACUUM INTO ${quoteSqlString(snapshot)}`);
+        afterVacuumBeforeFence({ attempt, source_data_version: before });
+        liveDb.exec('BEGIN EXCLUSIVE');
+        exclusive = true;
+        const fenced = Number(liveDb.pragma('data_version', { simple: true }));
+        if (fenced === before) {
+          sourceDataVersion = fenced;
+          break;
+        }
+        liveDb.exec('ROLLBACK');
+        exclusive = false;
+        fs.rmSync(snapshot, { force: true });
+      }
+      if (!exclusive) {
+        throw new Error(
+          `migrate: current state changed during ${maxAttempts} snapshot attempts`,
+        );
+      }
+    } else {
+      throw new Error(`migrate: current state is not a SQLite database: ${resolvedDb}`);
+    }
+    const verification = new Database(snapshot, { readonly: true, fileMustExist: true });
+    try {
+      const integrity = verification.pragma('integrity_check');
+      if (integrity.length !== 1 || integrity[0].integrity_check !== 'ok') {
+        throw new Error('migrate: current state recovery snapshot failed integrity_check');
+      }
+    } finally {
+      verification.close();
+    }
+    fs.chmodSync(snapshot, 0o444);
+    copied.push({ current: resolvedDb, prior: snapshot, kind: 'sqlite' });
+    const inventory = regularTreeInventory(previousState);
+    onSnapshot(inventory, {
+      source_data_version: sourceDataVersion,
+      snapshot_attempts: snapshotAttempts,
+    });
+    for (const suffix of ['-wal', '-shm', '']) {
+      fs.rmSync(`${resolvedDb}${suffix}`, { force: true });
+    }
+    if (exclusive) {
+      try { liveDb.exec('ROLLBACK'); } catch { /* the unlinked inode is already fenced */ }
+      exclusive = false;
+    }
+  } finally {
+    if (liveDb) {
+      if (exclusive) {
+        try { liveDb.exec('ROLLBACK'); } catch { /* best effort */ }
+      }
+      liveDb.close();
+    }
+  }
+  return copied;
+}
+
+function rollbackFromBackupLocked({
+  sourceDir,
+  dbPath,
+  backupDir,
+  fromVersion,
+  toVersion,
+}, io = {}) {
+  const copyFileSync = io.copyFileSync || fs.copyFileSync;
+  const renameSync = io.renameSync || fs.renameSync;
+  const rmSync = io.rmSync || fs.rmSync;
+  const afterPublish = io.afterPublish || (() => {});
+  const backupAdmission = assertRollbackBackup(sourceDir, backupDir, fromVersion);
+  const paths = backupAdmission.paths;
+  const resolvedDb = path.resolve(dbPath);
+  if (![paths.stateDbPath, paths.legacyStateDbPath].includes(resolvedDb)) {
+    throw new Error(
+      `migrate: rollback state.db must be project-owned: ${resolvedDb}`,
+    );
+  }
+  assertCurrentSemanticTree(paths.ultraDir);
+
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  const stageRoot = path.join(paths.runtimeDir, `.rollback-stage-${token}`);
+  const restoreRoot = path.join(stageRoot, 'restore');
+  const recoveryDir = path.join(rollbackRecoveryBase(paths), token);
+  const previousSemantic = path.join(recoveryDir, 'previous-semantic');
+  const previousState = path.join(recoveryDir, 'previous-state');
+  const journalPath = path.join(recoveryDir, 'journal.json');
+  const movedCurrent = [];
+  const installed = [];
+  const movedState = [];
+  const cleanupStage = () => {
+    rmSync(stageRoot, { recursive: true, force: true });
+  };
+  let published = false;
+  try {
+    if (!lstatOrNull(paths.runtimeDir)) {
+      fs.mkdirSync(paths.runtimeDir);
+    }
+    fs.mkdirSync(stageRoot, { recursive: false });
+
+    // Complete and validate the restore image before moving any current file.
+    copyDirSync(backupDir, restoreRoot, { copyFileSync });
+    if (!lstatOrNull(path.join(restoreRoot, BACKUP_MANIFEST))) {
+      writeJsonAtomic(path.join(restoreRoot, BACKUP_MANIFEST), backupAdmission.manifest);
+    }
+    const stagedAdmission = assertRollbackBackup(
+      sourceDir,
+      restoreRoot,
+      fromVersion,
+      { staged: true },
+    );
+    if (stagedAdmission.manifestDigest !== backupAdmission.manifestDigest
+        || stagedAdmission.inventoryDigest !== backupAdmission.inventoryDigest) {
+      throw new Error('migrate: staged rollback image does not match the admitted backup manifest');
+    }
+    fs.mkdirSync(recoveryDir, { recursive: true });
+    fs.mkdirSync(previousSemantic);
+    fs.mkdirSync(previousState);
+    const recoveryManifestPath = path.join(recoveryDir, BACKUP_MANIFEST);
+    writeJsonAtomic(recoveryManifestPath, stagedAdmission.manifest);
+    const now = new Date().toISOString();
+    let preparedJournal = {
+      version: 1,
+      source_dir: path.resolve(sourceDir),
+      from_version: fromVersion,
+      to_version: toVersion,
+      backup_dir: path.resolve(backupDir),
+      backup_manifest_path: recoveryManifestPath,
+      backup_manifest_sha256: stagedAdmission.manifestDigest,
+      backup_inventory_sha256: stagedAdmission.inventoryDigest,
+      stage_dir: stageRoot,
+      recovery_dir: recoveryDir,
+      phase: 'prepared',
+      cleanup_error: null,
+      created_at: now,
+      updated_at: now,
+    };
+    writeJsonAtomic(journalPath, preparedJournal);
+
+    if (runtimePaths.isManagedLegacyStateTombstone?.(paths.legacyStateDbPath)) {
+      const prior = path.join(previousState, 'legacy-state-tombstone');
+      copyFileSync(paths.legacyStateDbPath, prior);
+      fs.chmodSync(prior, 0o444);
+      fs.rmSync(paths.legacyStateDbPath);
+      movedState.push({
+        current: paths.legacyStateDbPath,
+        prior,
+        kind: 'tombstone',
+      });
+    }
+
+    movedState.push(...immutableStateSnapshot(resolvedDb, previousState, {
+      afterVacuumBeforeFence: io.afterStateSnapshotBeforeFence,
+      onSnapshot(inventory, snapshotEvidence) {
+        preparedJournal = updateRollbackJournal(journalPath, {
+          previous_state_inventory: inventory,
+          previous_state_inventory_sha256: jsonDigest(inventory),
+          previous_state_data_version: snapshotEvidence.source_data_version,
+          previous_state_snapshot_attempts: snapshotEvidence.snapshot_attempts,
+        });
+      },
+    }));
+
+    for (const entry of fs.readdirSync(paths.ultraDir, { withFileTypes: true })) {
+      if (entry.name === '.runtime'
+          || entry.name === 'state.db'
+          || entry.name === 'state.db-wal'
+          || entry.name === 'state.db-shm'
+          || path.resolve(paths.ultraDir, entry.name) === path.resolve(backupDir)) {
+        continue;
+      }
+      const current = path.join(paths.ultraDir, entry.name);
+      const prior = path.join(previousSemantic, entry.name);
+      renameSync(current, prior);
+      movedCurrent.push({ current, prior });
+    }
+
+    for (const entry of fs.readdirSync(restoreRoot)) {
+      if (entry === BACKUP_MANIFEST) continue;
+      const staged = path.join(restoreRoot, entry);
+      const target = path.join(paths.ultraDir, entry);
+      renameSync(staged, target);
+      installed.push({ staged, target });
+    }
+
+    assertInstalledRollback(sourceDir, paths, preparedJournal);
+    updateRollbackJournal(journalPath, {
+      phase: 'installed',
+      installed_at: new Date().toISOString(),
+    });
+    published = true;
+    // This seam also models a process interruption after the rollback is
+    // authoritative but before disposable staging cleanup begins. Recovery
+    // must trust the installed tree plus the independent journal, never the
+    // potentially partial staging directory.
+    afterPublish();
+  } catch (error) {
+    if (published) throw error;
+    const rollbackErrors = [];
+    for (const item of [...installed].reverse()) {
+      try {
+        fs.mkdirSync(path.dirname(item.staged), { recursive: true });
+        renameSync(item.target, item.staged);
+      } catch (rollbackError) {
+        rollbackErrors.push(`${item.target}: ${rollbackError.message}`);
+      }
+    }
+    for (const item of [...movedCurrent].reverse()) {
+      try {
+        fs.mkdirSync(path.dirname(item.current), { recursive: true });
+        renameSync(item.prior, item.current);
+      } catch (rollbackError) {
+        rollbackErrors.push(`${item.prior}: ${rollbackError.message}`);
+      }
+    }
+    for (const item of [...movedState].reverse()) {
+      try {
+        fs.mkdirSync(path.dirname(item.current), { recursive: true });
+        copyFileSync(item.prior, item.current);
+        fs.chmodSync(item.current, item.kind === 'tombstone' ? 0o444 : 0o600);
+      } catch (rollbackError) {
+        rollbackErrors.push(`${item.prior}: ${rollbackError.message}`);
+      }
+    }
+    if (rollbackErrors.length === 0) {
+      try { cleanupStage(); }
+      catch (cleanupError) {
+        rollbackErrors.push(`${stageRoot}: ${cleanupError.message}`);
+      }
+    }
+    if (rollbackErrors.length > 0) {
+      if (lstatOrNull(journalPath)) {
+        try {
+          updateRollbackJournal(journalPath, {
+            phase: 'recovery_failed',
+            rollback_error: rollbackErrors.join('; '),
+          });
+        } catch { /* preserve original rollback evidence */ }
+      }
+      throw new Error(
+        `${error.message}; rollback restore failed: ${rollbackErrors.join('; ')}`,
+        { cause: error },
+      );
+    }
+    if (lstatOrNull(journalPath)) {
+      updateRollbackJournal(journalPath, {
+        phase: 'rolled_back',
+        rollback_error: null,
+      });
+    }
+    throw error;
+  }
+
+  let cleanupError = null;
+  try {
+    cleanupStage();
+  } catch (error) {
+    cleanupError = error;
+    updateRollbackJournal(journalPath, {
+      phase: 'cleanup_pending',
+      cleanup_error: error.message,
+    });
+  }
+  if (!cleanupError) {
+    updateRollbackJournal(journalPath, {
+      phase: 'complete',
+      cleanup_error: null,
+      completed_at: new Date().toISOString(),
+    });
+  }
+  return {
+    mode: 'rollback',
+    from: toVersion,
+    to: fromVersion,
+    backup_dir: backupDir,
+    source_dir: sourceDir,
+    recovery_dir: recoveryDir,
+    journal_path: journalPath,
+    stage_dir: stageRoot,
+    cleanup_pending: Boolean(cleanupError),
+    ...(cleanupError ? { cleanup_error: cleanupError.message } : {}),
+  };
+}
+
+function rollbackFromBackup(input, io = {}) {
+  const paths = runtimePaths.validateProjectLayout(input.sourceDir, {
+    env: {},
+    forMutation: true,
+    validateRuntimeTree: true,
+  });
+  fs.mkdirSync(paths.runtimeDir, { recursive: true });
+  const releaseGate = runtimePaths._internal.acquireStateMigrationGate(paths);
+  try {
+    return rollbackFromBackupLocked(input, io);
+  } finally {
+    releaseGate();
+  }
 }
 
 function cmdForward(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
-  const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
   const fromVersion = flags.from || DEFAULT_FROM;
   const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
   let plan;
+  let dbPath;
   try {
+    const paths = runtimePaths.validateProjectLayout(sourceDir, {
+      env: {},
+      validateRuntimeTree: true,
+    });
+    dbPath = flags.dbPath ? path.resolve(flags.dbPath) : paths.stateDbPath;
+    if (dbPath !== paths.stateDbPath) {
+      throw new Error(
+        `migrate: state.db destination must be the project canonical authority: ${paths.stateDbPath}`,
+      );
+    }
+    assertCurrentSemanticTree(paths.ultraDir);
+    // Validate the live source before creating any backup. Apply mode discards
+    // this provisional plan and rebuilds it from the immutable backup image.
     plan = planForward(sourceDir, fromVersion);
   } catch (err) {
     emit({ ok: false, error: { code: 'MIGRATE_FAILED', message: err.message, retriable: false } });
@@ -292,13 +1205,15 @@ function cmdForward(flags) {
     return 0;
   }
 
-  // Real run: backup the entire .ultra subtree first.
-  const backupDir = ensureBackupName(sourceDir, fromVersion);
-  const ultraSource = path.join(sourceDir, '.ultra');
-  copyDirSync(ultraSource, backupDir);
-
   let db;
+  let backupDir;
   try {
+    // Validate and publish the complete projection snapshot before authority
+    // migration can relocate any legacy DB or mutable runtime artifact.
+    const prepared = prepareForwardSnapshot(sourceDir, fromVersion);
+    backupDir = prepared.backupDir;
+    plan = prepared.plan;
+    dbPath = runtimePaths.ensureRuntimeState(sourceDir).stateDbPath;
     db = initStateDb(dbPath).db;
     const counts = ops.tx(db, () => {
       const existing = db.prepare('SELECT COUNT(*) AS count FROM tasks').get().count;
@@ -363,58 +1278,54 @@ function cmdForward(flags) {
 
 function cmdRollback(flags) {
   const sourceDir = path.resolve(flags.sourceDir || '.');
-  const dbPath = path.resolve(flags.dbPath || path.join(sourceDir, '.ultra', 'state.db'));
   const fromVersion = flags.from || DEFAULT_FROM;
   const toVersion = flags.to || SUPPORTED_TRANSITIONS[fromVersion];
-  const backupDir = findLatestBackup(sourceDir, fromVersion);
-  if (!backupDir) {
-    emit({ ok: false, error: { code: 'NO_BACKUP', message: `no backup-v${fromVersion}-* directory found` } });
-    return 2;
-  }
-
-  // Record rollback BEFORE removing the db; if the file is gone we still want an audit row.
-  let db;
   try {
-    if (fs.existsSync(dbPath)) {
-      db = openStateDb(dbPath);
-      recordMigration(db, {
-        from: toVersion,
-        to: fromVersion,
-        direction: 'rollback',
-        status: 'success',
-        notes: `restored from ${backupDir}`,
+    const resumed = resumeRollbackRecovery(sourceDir);
+    if (resumed.pending > 0) {
+      throw new Error(
+        `migrate: ${resumed.pending} rollback recovery transaction(s) require manual recovery`,
+      );
+    }
+    if (resumed.resumed > 0) {
+      emit({
+        ok: true,
+        data: {
+          mode: 'rollback-resumed',
+          from: toVersion,
+          to: fromVersion,
+          source_dir: sourceDir,
+          ...resumed,
+        },
       });
-      closeStateDb(db);
-      db = null;
-      fs.unlinkSync(dbPath);
-      const wal = `${dbPath}-wal`;
-      const shm = `${dbPath}-shm`;
-      if (fs.existsSync(wal)) fs.unlinkSync(wal);
-      if (fs.existsSync(shm)) fs.unlinkSync(shm);
+      return 0;
     }
-
-    // Restore .ultra contents from backup, leaving the backup itself in place.
-    const ultraDir = path.join(sourceDir, '.ultra');
-    for (const entry of fs.readdirSync(ultraDir, { withFileTypes: true })) {
-      if (/^backup-v[^/]+-/.test(entry.name)) continue;
-      const target = path.join(ultraDir, entry.name);
-      fs.rmSync(target, { recursive: true, force: true });
+    const dbPath = flags.dbPath
+      ? path.resolve(flags.dbPath)
+      : runtimePaths.locateStateDb(sourceDir, { env: {} });
+    const backupDir = findLatestBackup(sourceDir, fromVersion);
+    if (!backupDir) {
+      emit({
+        ok: false,
+        error: {
+          code: 'NO_BACKUP',
+          message: `no projection-v${fromVersion}-* or backup-v${fromVersion}-* directory found`,
+        },
+      });
+      return 2;
     }
-    copyDirSync(backupDir, ultraDir);
-
     emit({
       ok: true,
-      data: {
-        mode: 'rollback',
-        from: toVersion,
-        to: fromVersion,
-        backup_dir: backupDir,
-        source_dir: sourceDir,
-      },
+      data: rollbackFromBackup({
+        sourceDir,
+        dbPath,
+        backupDir,
+        fromVersion,
+        toVersion,
+      }),
     });
     return 0;
   } catch (err) {
-    if (db) closeStateDb(db);
     emit({ ok: false, error: { code: 'ROLLBACK_FAILED', message: err.message, retriable: false } });
     return 2;
   }
@@ -447,15 +1358,16 @@ Supported transitions:
 
 Flags:
   --source-dir <dir>   project root containing .ultra/ (default: .)
-  --db-path <path>     state.db destination (default: <source-dir>/.ultra/state.db)
+  --db-path <path>     state.db destination (default: <source-dir>/.ultra/.runtime/state.db)
   --dry                print the migration plan without writing
   --rollback           restore the most recent matching backup-v<from>-* and drop state.db
 
 The forward flow: backup .ultra/ → init state.db → insert tasks from
 tasks.json → merge context md status (tasks.json wins on conflict, warnings
 recorded) → insert activity-log events → record migration_history.
-Rollback restores from the latest matching backup-v<from>-* directory and writes a
-matching migration_history rollback row before dropping state.db.
+Rollback restores from the latest matching backup-v<from>-* directory through a
+prevalidated staged image, then removes the newer state.db only as part of the
+rollback transaction.
 `;
 
 module.exports = {
@@ -463,6 +1375,9 @@ module.exports = {
   USAGE,
   parseFlags,
   planForward,
+  prepareForwardSnapshot,
   parseFrontmatter,
   sanitizeLegacyContextTemplate,
+  rollbackFromBackup,
+  resumeRollbackRecovery,
 };