akm-cli 0.9.0-rc.1 → 0.9.0-rc.3

package/dist/cli/config-migrate.js

@@ -1,150 +1,571 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { stripJsonComments } from "../core/config/config.js";
-import { unifiedDiff, withConfigLock, writeConfigAtomic } from "../core/config/config-io.js";
-import { migrateConfigShape } from "../core/config/config-migration.js";
-import { getCacheDir, getConfigPath } from "../core/paths.js";
-import { warn } from "../core/warn.js";
-export { migrateConfigShape } from "../core/config/config-migration.js";
-const PROJECT_CONFIG_RELATIVE_PATH = path.join(".akm", "config.json");
-function backupConfigFile(configPath) {
-    if (!fs.existsSync(configPath))
-        return;
-    const backupDir = path.join(getCacheDir(), "config-backups");
-    // 08-F4: lock the backup dir owner-only (0700) — see config-io.ts.
-    fs.mkdirSync(backupDir, { recursive: true, mode: 0o700 });
-    fs.chmodSync(backupDir, 0o700);
-    const timestamp = new Date().toISOString().replace(/[.:]/g, "-");
-    const backupPath = path.join(backupDir, `config-${timestamp}.json`);
-    fs.copyFileSync(configPath, backupPath);
-    const latestPath = path.join(backupDir, "config.latest.json");
-    fs.copyFileSync(configPath, latestPath);
-    // 08-F4: config backups can carry secrets (endpoints/tokens) — keep them
-    // owner-only rather than inheriting the source file's (often 0644) mode.
-    fs.chmodSync(backupPath, 0o600);
-    fs.chmodSync(latestPath, 0o600);
-}
-function acquireMigrateLock(lockPath, noWait) {
-    const lockDir = path.dirname(lockPath);
-    fs.mkdirSync(lockDir, { recursive: true });
-    const maxAttempts = noWait ? 1 : 20;
-    const delayMs = 200;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        try {
-            fs.writeFileSync(lockPath, String(process.pid), { flag: "wx" });
-            return () => {
-                try {
-                    fs.unlinkSync(lockPath);
-                }
-                catch {
-                    // ignore
-                }
-            };
+import { MAX_CONFIG_FILE_BYTES, MAX_LOCAL_METADATA_BYTES, readTextFileWithLimit, writeFileAtomic, } from "../core/common.js";
+import { parseAndValidateConfigText, resetConfigCache, sanitizeConfigForWrite, } from "../core/config/config.js";
+import { backupExistingConfig, withConfigLock, writeConfigAtomic } from "../core/config/config-io.js";
+import { ConfigError } from "../core/errors.js";
+import { withMaintenanceStartBarrier } from "../core/maintenance-barrier.js";
+import { assertNoArtifactReplacementBlockers, ensureMigrationBackupWithConfigLockHeld, fingerprintMigrationGeneration, getMigrationApplyJournalPath, getMigrationBackupDir, getMigrationBackupRoot, getMigrationRestoreJournalPath, inspectMigrationState, MIGRATION_BACKUP_VERSION, recoverInterruptedRestoreWithLocksHeld, restoreMigrationBackupWithLocksHeld, sameMigrationGeneration, verifyMigrationBackup, } from "../core/migration-backup.js";
+import { getConfigPath, getStateDbPathInDataDir, getWorkflowDbPath } from "../core/paths.js";
+import { runMigrations as runStateMigrations } from "../core/state/migrations.js";
+import { openDatabase } from "../storage/database.js";
+import { runMigrations as runWorkflowMigrations } from "../workflows/db.js";
+import { EXIT_CODES } from "./shared.js";
+const MANUAL_GUIDANCE = "Provide a complete operator-prepared 0.9 config with --config. AKM does not guess profile-to-engine mappings.";
+function isFileFingerprint(value) {
+    if (value === null)
+        return true;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const candidate = value;
+    return (Object.keys(candidate).sort().join(",") === "byteSize,sha256" &&
+        Number.isSafeInteger(candidate.byteSize) &&
+        candidate.byteSize >= 0 &&
+        typeof candidate.sha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(candidate.sha256));
+}
+function isGenerationFingerprint(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const generation = value;
+    if (Object.keys(generation).sort().join(",") !== "config,state,workflow")
+        return false;
+    for (const [name, expectedNullSidecars] of [
+        ["config", true],
+        ["state", false],
+        ["workflow", false],
+    ]) {
+        const artifact = generation[name];
+        if (typeof artifact !== "object" || artifact === null || Array.isArray(artifact))
+            return false;
+        const files = artifact;
+        if (Object.keys(files).sort().join(",") !== "main,shm,wal")
+            return false;
+        if (!isFileFingerprint(files.main) || !isFileFingerprint(files.wal) || !isFileFingerprint(files.shm))
+            return false;
+        if (expectedNullSidecars && (files.wal !== null || files.shm !== null))
+            return false;
+    }
+    return true;
+}
+function sameArtifactFingerprint(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function hasGenerationMarker(dbPath, operationId, phase) {
+    if (!fs.existsSync(dbPath))
+        return false;
+    const db = openDatabase(dbPath, { readonly: true });
+    try {
+        if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='akm_migration_generation'").get()) {
+            return false;
         }
-        catch {
-            if (noWait) {
-                return null;
-            }
-            // Simple busy-wait — synchronous since this is a one-shot CLI action
-            const deadline = Date.now() + delayMs;
-            while (Date.now() < deadline) {
-                // spin
-            }
+        const rows = db
+            .prepare("SELECT operation_id, phase FROM akm_migration_generation WHERE singleton=1 LIMIT 2")
+            .all();
+        return rows.length === 1 && rows[0].operation_id === operationId && rows[0].phase === phase;
+    }
+    finally {
+        db.close();
+    }
+}
+function generationFromBackup(manifest) {
+    const fingerprint = (name) => {
+        const artifact = manifest.artifacts[name];
+        return artifact.present ? { byteSize: artifact.byteSize, sha256: artifact.sha256 } : null;
+    };
+    return {
+        config: { main: fingerprint("config.json"), wal: null, shm: null },
+        state: { main: fingerprint("state.db"), wal: null, shm: null },
+        workflow: { main: fingerprint("workflow.db"), wal: null, shm: null },
+    };
+}
+function detectAdjacentGeneration(journal, manifest) {
+    if (journal.phase === "rollback-prepared") {
+        return {
+            rollbackCompleted: sameMigrationGeneration(fingerprintMigrationGeneration(), generationFromBackup(manifest)),
+        };
+    }
+    const live = inspectMigrationState();
+    const markerPresent = journal.phase === "prepared"
+        ? hasGenerationMarker(getStateDbPathInDataDir(), journal.operationId, "state-applied")
+        : journal.phase === "state-applied"
+            ? hasGenerationMarker(getWorkflowDbPath(), journal.operationId, "workflow-applied")
+            : false;
+    const current = fingerprintMigrationGeneration();
+    const unchanged = (...names) => names.every((name) => sameArtifactFingerprint(journal.generation[name], current[name]));
+    if (journal.phase === "prepared" && unchanged("config", "workflow") && markerPresent) {
+        return {
+            adjacent: {
+                phase: "state-applied",
+                complete: live.state.status === "current" || live.state.status === "missing",
+                generation: current,
+            },
+        };
+    }
+    if (journal.phase === "state-applied" && unchanged("config", "state") && markerPresent) {
+        return {
+            adjacent: {
+                phase: "workflow-applied",
+                complete: live.workflow.status === "current" || live.workflow.status === "missing",
+                generation: current,
+            },
+        };
+    }
+    const expectedTarget = `${JSON.stringify(journal.targetConfig, null, 2)}\n`;
+    if (journal.phase === "workflow-applied" &&
+        unchanged("state", "workflow") &&
+        fs.existsSync(getConfigPath()) &&
+        readTextFileWithLimit(getConfigPath(), MAX_CONFIG_FILE_BYTES, "Config file") === expectedTarget) {
+        return {
+            adjacent: { phase: "config-applied", complete: true, generation: current },
+        };
+    }
+    return {};
+}
+function assertRollbackTransitionAllowed(journal, current) {
+    const unchanged = journal.phase === "prepared"
+        ? ["config", "workflow"]
+        : journal.phase === "state-applied"
+            ? ["config", "state"]
+            : journal.phase === "workflow-applied"
+                ? ["state", "workflow"]
+                : ["config", "state", "workflow"];
+    for (const name of unchanged) {
+        if (!sameArtifactFingerprint(journal.generation[name], current[name])) {
+            throw new ConfigError(`Refusing migration rollback because ${name} changed outside the journaled ${journal.phase} transition.`, "INVALID_CONFIG_FILE");
         }
     }
-    return null;
 }
-export async function migrateConfigFile(filePath, opts) {
-    if (!fs.existsSync(filePath)) {
-        return { changed: false, result: {} };
+function sameArtifactState(actual, expected) {
+    return (actual.status === expected.status &&
+        JSON.stringify(actual.migrationIds ?? []) === JSON.stringify(expected.migrationIds ?? []) &&
+        JSON.stringify(actual.migrationChecksums ?? []) === JSON.stringify(expected.migrationChecksums ?? []));
+}
+function configMatchesBytes(expectedSize, expectedHash) {
+    const configPath = getConfigPath();
+    if (!fs.existsSync(configPath) || expectedHash === null)
+        return false;
+    const text = readTextFileWithLimit(configPath, MAX_CONFIG_FILE_BYTES, "Config file");
+    return (fs.statSync(configPath).size === expectedSize &&
+        createHash("sha256").update(Buffer.from(text)).digest("hex") === expectedHash);
+}
+function validateApplyPhase(journal, manifest) {
+    const live = inspectMigrationState();
+    const stateOriginal = sameArtifactState(live.state, manifest.artifacts["state.db"]);
+    const workflowOriginal = sameArtifactState(live.workflow, manifest.artifacts["workflow.db"]);
+    const configOriginal = manifest.artifacts["config.json"].present
+        ? configMatchesBytes(manifest.artifacts["config.json"].byteSize, manifest.artifacts["config.json"].sha256)
+        : live.config.status === "missing";
+    const stateApplied = manifest.artifacts["state.db"].present
+        ? live.state.status === "current"
+        : live.state.status === "missing";
+    const workflowApplied = manifest.artifacts["workflow.db"].present
+        ? live.workflow.status === "current"
+        : live.workflow.status === "missing";
+    const expectedTarget = `${JSON.stringify(journal.targetConfig, null, 2)}\n`;
+    const configApplied = live.config.status === "current" &&
+        fs.existsSync(getConfigPath()) &&
+        readTextFileWithLimit(getConfigPath(), MAX_CONFIG_FILE_BYTES, "Config file") === expectedTarget;
+    const reachable = journal.phase === "rollback-prepared"
+        ? true
+        : journal.phase === "prepared"
+            ? configOriginal && workflowOriginal && (stateOriginal || stateApplied)
+            : journal.phase === "state-applied"
+                ? stateApplied && configOriginal && (workflowOriginal || workflowApplied)
+                : journal.phase === "workflow-applied"
+                    ? stateApplied && workflowApplied && (configOriginal || configApplied)
+                    : stateApplied && workflowApplied && configApplied;
+    if (!reachable) {
+        throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match a reachable config/state/workflow artifact state.`, "INVALID_CONFIG_FILE");
     }
-    const text = fs.readFileSync(filePath, "utf8");
-    let raw;
+}
+function readApplyJournal() {
+    const journalPath = getMigrationApplyJournalPath();
+    if (!fs.existsSync(journalPath))
+        return {};
+    let journal;
     try {
-        const stripped = stripJsonComments(text);
-        const parsed = JSON.parse(stripped);
-        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-            warn(`[akm] config-migrate: ${filePath} is not a valid JSON object, skipping.`);
-            return { changed: false, result: {} };
+        const value = JSON.parse(readTextFileWithLimit(journalPath, MAX_LOCAL_METADATA_BYTES, "Migration apply journal"));
+        const phases = [
+            "prepared",
+            "state-applied",
+            "workflow-applied",
+            "config-applied",
+            "rollback-prepared",
+            "committed",
+        ];
+        if (typeof value !== "object" ||
+            value === null ||
+            Array.isArray(value) ||
+            Object.keys(value).sort().join(",") !==
+                [
+                    "backupPath",
+                    "backupRunId",
+                    "formatVersion",
+                    "generation",
+                    "installationId",
+                    "operationId",
+                    "phase",
+                    "targetConfig",
+                    "version",
+                ]
+                    .sort()
+                    .join(",")) {
+            return { error: `Invalid migration apply journal at ${journalPath}.` };
+        }
+        const candidate = value;
+        if (candidate.formatVersion !== 2 ||
+            candidate.version !== MIGRATION_BACKUP_VERSION ||
+            typeof candidate.operationId !== "string" ||
+            !/^[A-Za-z0-9._-]+$/.test(candidate.operationId) ||
+            candidate.installationId !== path.basename(getMigrationBackupRoot()) ||
+            !isGenerationFingerprint(candidate.generation) ||
+            typeof candidate.backupRunId !== "string" ||
+            !/^[A-Za-z0-9._-]+$/.test(candidate.backupRunId) ||
+            candidate.backupPath !== getMigrationBackupDir(candidate.backupRunId) ||
+            !candidate.targetConfig ||
+            typeof candidate.targetConfig !== "object" ||
+            Array.isArray(candidate.targetConfig) ||
+            !phases.includes(candidate.phase)) {
+            return { error: `Invalid or foreign migration apply journal at ${journalPath}.` };
+        }
+        journal = candidate;
+    }
+    catch (error) {
+        return {
+            error: `Unreadable migration apply journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    try {
+        const backupStat = fs.lstatSync(journal.backupPath);
+        if (backupStat.isSymbolicLink() ||
+            !backupStat.isDirectory() ||
+            fs.realpathSync(path.dirname(journal.backupPath)) !== fs.realpathSync(getMigrationBackupRoot())) {
+            throw new ConfigError(`Migration apply journal backup is not a canonical installation run directory.`, "INVALID_CONFIG_FILE");
+        }
+        const config = parseAndValidateConfigText(JSON.stringify(journal.targetConfig), journalPath);
+        const manifest = verifyMigrationBackup(journal.backupPath);
+        if (manifest.runId !== journal.backupRunId || manifest.installationId !== journal.installationId) {
+            throw new ConfigError(`Migration apply journal backup provenance does not match its manifest.`, "INVALID_CONFIG_FILE");
+        }
+        validateApplyPhase(journal, manifest);
+        if (!sameMigrationGeneration(fingerprintMigrationGeneration(), journal.generation)) {
+            const adjacent = detectAdjacentGeneration(journal, manifest);
+            if (adjacent.adjacent || adjacent.rollbackCompleted)
+                return { journal, config, ...adjacent };
+            throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+        }
+        return { journal, config };
+    }
+    catch (error) {
+        return {
+            journal,
+            error: `Unreadable migration apply journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function writeApplyJournal(journal) {
+    fs.mkdirSync(path.dirname(getMigrationApplyJournalPath()), { recursive: true, mode: 0o700 });
+    const serialized = `${JSON.stringify(journal, null, 2)}\n`;
+    const byteLength = Buffer.byteLength(serialized, "utf8");
+    if (byteLength > MAX_LOCAL_METADATA_BYTES) {
+        throw new ConfigError(`Migration apply journal would exceed the ${MAX_LOCAL_METADATA_BYTES}-byte metadata limit (${byteLength} bytes).`, "INVALID_CONFIG_FILE");
+    }
+    writeFileAtomic(getMigrationApplyJournalPath(), serialized, 0o600);
+}
+function advanceApplyJournal(journal, phase) {
+    const order = ["prepared", "state-applied", "workflow-applied", "config-applied", "committed"];
+    if (order.indexOf(phase) > order.indexOf(journal.phase))
+        journal.phase = phase;
+    journal.generation = fingerprintMigrationGeneration();
+    writeApplyJournal(journal);
+}
+function clearApplyJournal() {
+    fs.rmSync(getMigrationApplyJournalPath(), { force: true });
+    try {
+        const fd = fs.openSync(path.dirname(getMigrationApplyJournalPath()), "r");
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
         }
-        raw = parsed;
     }
     catch {
-        warn(`[akm] config-migrate: failed to parse ${filePath}, skipping.`);
-        return { changed: false, result: {} };
-    }
-    const { changed, result } = migrateConfigShape(raw);
-    if (!changed) {
-        return { changed: false, result };
-    }
-    const migratedText = `${JSON.stringify(result, null, 2)}\n`;
-    // WS-2: compute a diff when requested (always computed for --print-diff;
-    // never requires a write so safe in --dry-run).
-    const diff = opts.printDiff ? unifiedDiff(text, migratedText, filePath) : undefined;
-    if (opts.dryRun) {
-        return { changed: true, result, diff };
-    }
-    // WS-3: acquire config write lock + use atomic write (tmp → rename).
-    withConfigLock(() => {
-        backupConfigFile(filePath);
-        writeConfigAtomic(filePath, result);
-    });
-    return { changed: true, result, diff };
-}
-function discoverProjectConfigPaths(startDir) {
-    const paths = [];
-    let currentDir = path.resolve(startDir);
-    while (true) {
-        const configPath = path.join(currentDir, PROJECT_CONFIG_RELATIVE_PATH);
-        if (fs.existsSync(configPath) && fs.statSync(configPath).isFile()) {
-            paths.unshift(configPath);
+        // Directory fsync is not available on every supported filesystem.
+    }
+}
+function crashAfterForTests(phase) {
+    if (process.env.AKM_TEST_MIGRATION_CRASH_AFTER === phase)
+        process.kill(process.pid, "SIGKILL");
+}
+function crashInMutationGapForTests(phase) {
+    if (process.env.AKM_TEST_MIGRATION_CRASH_GAP === phase)
+        process.kill(process.pid, "SIGKILL");
+}
+function unsafeArtifact(name, state) {
+    if (!["newer", "inconsistent", "corrupt"].includes(state.status))
+        return undefined;
+    return `${name} is ${state.status}${state.detail ? `: ${state.detail}` : ""}`;
+}
+function loadTargetConfig(preparedConfigPath, artifacts) {
+    const targetPath = preparedConfigPath ?? (artifacts.config.status === "current" ? getConfigPath() : undefined);
+    if (!targetPath) {
+        return {
+            state: { status: "missing", source: "none", detail: MANUAL_GUIDANCE },
+        };
+    }
+    let text;
+    try {
+        text = readTextFileWithLimit(targetPath, MAX_CONFIG_FILE_BYTES, "Prepared migration config");
+    }
+    catch (error) {
+        return {
+            state: {
+                status: "corrupt",
+                source: preparedConfigPath ? "prepared" : "active",
+                path: targetPath,
+                detail: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+    try {
+        return {
+            state: {
+                status: "current",
+                source: preparedConfigPath ? "prepared" : "active",
+                path: targetPath,
+            },
+            config: parseAndValidateConfigText(text, targetPath),
+        };
+    }
+    catch (error) {
+        return {
+            state: {
+                status: "corrupt",
+                source: preparedConfigPath ? "prepared" : "active",
+                path: targetPath,
+                detail: error instanceof Error ? error.message : String(error),
+            },
+        };
+    }
+}
+function buildMigrationPlan(preparedConfigPath, activeApply) {
+    const artifacts = inspectMigrationState();
+    const restorePending = fs.existsSync(getMigrationRestoreJournalPath());
+    const target = activeApply.journal
+        ? {
+            state: {
+                status: activeApply.config ? "current" : "corrupt",
+                source: "prepared",
+                path: getMigrationApplyJournalPath(),
+                ...(!activeApply.config && activeApply.error ? { detail: activeApply.error } : {}),
+            },
+            config: activeApply.config,
         }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir)
-            break;
-        currentDir = parentDir;
-    }
-    return paths;
-}
-export async function runConfigMigrate(opts) {
-    const userConfigPath = getConfigPath();
-    const projectPaths = discoverProjectConfigPaths(process.cwd());
-    const allPaths = [userConfigPath, ...projectPaths].filter((p, i, arr) => arr.indexOf(p) === i && fs.existsSync(p));
-    if (allPaths.length === 0) {
-        console.log("No config files found to migrate.");
-        return;
+        : loadTargetConfig(preparedConfigPath, artifacts);
+    const blockers = [
+        unsafeArtifact("config.json", artifacts.config),
+        unsafeArtifact("state.db", artifacts.state),
+        unsafeArtifact("workflow.db", artifacts.workflow),
+    ].filter((blocker) => blocker !== undefined);
+    if (target.state.status !== "current")
+        blockers.push(target.state.detail ?? "A current target config is required.");
+    if (activeApply.error && !activeApply.journal)
+        blockers.push(activeApply.error);
+    if (restorePending)
+        blockers.push(`Restore recovery is pending at ${getMigrationRestoreJournalPath()}.`);
+    const needsApply = !!activeApply.journal ||
+        artifacts.config.status !== "current" ||
+        artifacts.state.status === "old" ||
+        artifacts.workflow.status === "old";
+    return {
+        status: blockers.length > 0 ? "blocked" : needsApply ? "ready" : "current",
+        artifacts,
+        targetConfig: target.state,
+        blockers,
+        ...(restorePending
+            ? {
+                activeOperation: {
+                    kind: "restore",
+                    phase: "pending",
+                    journalPath: getMigrationRestoreJournalPath(),
+                },
+            }
+            : activeApply.journal
+                ? {
+                    activeOperation: {
+                        kind: "apply",
+                        phase: activeApply.journal.phase,
+                        journalPath: getMigrationApplyJournalPath(),
+                    },
+                }
+                : {}),
+    };
+}
+export function inspectMigrationPlan(preparedConfigPath) {
+    return buildMigrationPlan(preparedConfigPath, readApplyJournal());
+}
+function printPlan(plan) {
+    console.log(JSON.stringify(plan));
+    if (plan.status === "blocked")
+        process.exitCode = EXIT_CODES.GENERAL;
+}
+export async function runMigrationStatus(options = {}) {
+    printPlan(inspectMigrationPlan(options.preparedConfigPath));
+}
+function requireEligiblePlan(preparedConfigPath, active = readApplyJournal()) {
+    const plan = buildMigrationPlan(preparedConfigPath, active);
+    const loaded = active.journal ? { config: active.config } : loadTargetConfig(preparedConfigPath, plan.artifacts);
+    if (plan.status === "blocked" || !loaded.config) {
+        throw new ConfigError(`Migration is blocked: ${plan.blockers.join("; ")}`, "INVALID_CONFIG_FILE");
     }
-    const lockPath = path.join(getCacheDir(), "config-migrate.lock");
-    const releaseLock = acquireMigrateLock(lockPath, opts.noWait ?? false);
-    if (!releaseLock) {
-        warn("[akm] config-migrate: another migration is already in progress, skipping.");
+    return { plan, target: loaded.config };
+}
+export async function runMigrationApply(options = {}) {
+    if (options.dryRun) {
+        printPlan(inspectMigrationPlan(options.preparedConfigPath));
         return;
     }
-    try {
-        let anyChanged = false;
-        for (const filePath of allPaths) {
-            const { changed, diff } = await migrateConfigFile(filePath, { dryRun: opts.dryRun, printDiff: opts.printDiff });
-            if (changed) {
-                const action = opts.dryRun ? "would migrate" : "migrated";
-                console.log(`[akm] ${action}: ${filePath}`);
-                // WS-2: print the unified diff to stdout when --print-diff is set.
-                if (diff) {
-                    console.log(diff);
+    const result = withConfigLock(() => withMaintenanceStartBarrier(() => {
+        assertNoArtifactReplacementBlockers();
+        recoverInterruptedRestoreWithLocksHeld();
+        const active = readApplyJournal();
+        if (active.error)
+            throw new ConfigError(active.error, "INVALID_CONFIG_FILE");
+        if (active.rollbackCompleted && active.journal) {
+            clearApplyJournal();
+            resetConfigCache();
+            throw new ConfigError("Interrupted migration rollback was already committed; cleaned its apply journal. Rerun migrate apply with the prepared config.", "INVALID_CONFIG_FILE");
+        }
+        if (active.journal?.phase === "rollback-prepared") {
+            restoreMigrationBackupWithLocksHeld(active.journal.backupPath);
+            crashInMutationGapForTests("rollback");
+            clearApplyJournal();
+            resetConfigCache();
+            throw new ConfigError("Interrupted migration rollback completed from its exact journaled generation; rerun migrate apply with the prepared config.", "INVALID_CONFIG_FILE");
+        }
+        if (active.adjacent && active.journal) {
+            active.journal.generation = active.adjacent.generation;
+            if (active.adjacent.complete)
+                active.journal.phase = active.adjacent.phase;
+            writeApplyJournal(active.journal);
+        }
+        const { plan, target } = requireEligiblePlan(options.preparedConfigPath, active);
+        if (plan.status === "current")
+            return { plan };
+        const backup = active.journal
+            ? { path: active.journal.backupPath, manifest: verifyMigrationBackup(active.journal.backupPath) }
+            : ensureMigrationBackupWithConfigLockHeld();
+        const journal = active.journal ?? {
+            formatVersion: 2,
+            version: MIGRATION_BACKUP_VERSION,
+            operationId: `${process.pid}-${randomUUID()}`,
+            installationId: backup.manifest.installationId,
+            backupRunId: backup.manifest.runId,
+            phase: "prepared",
+            backupPath: backup.path,
+            targetConfig: sanitizeConfigForWrite(target),
+            generation: fingerprintMigrationGeneration(),
+        };
+        if (!active.journal)
+            writeApplyJournal(journal);
+        try {
+            const beforeState = inspectMigrationState();
+            if (beforeState.state.status === "old") {
+                const db = openDatabase(getStateDbPathInDataDir());
+                try {
+                    runStateMigrations(db, {
+                        generationMarker: { operationId: journal.operationId, phase: "state-applied" },
+                    });
+                }
+                finally {
+                    db.close();
+                }
+            }
+            else if (beforeState.state.status !== "current" && beforeState.state.status !== "missing") {
+                throw new ConfigError(`Cannot resume state.db from ${beforeState.state.status} state.`, "INVALID_CONFIG_FILE");
+            }
+            crashInMutationGapForTests("state");
+            advanceApplyJournal(journal, "state-applied");
+            crashAfterForTests("state");
+            const beforeWorkflow = inspectMigrationState();
+            if (beforeWorkflow.workflow.status === "old") {
+                const db = openDatabase(getWorkflowDbPath());
+                try {
+                    runWorkflowMigrations(db, {
+                        generationMarker: { operationId: journal.operationId, phase: "workflow-applied" },
+                    });
+                }
+                finally {
+                    db.close();
                 }
-                anyChanged = true;
             }
-            else {
-                console.log(`[akm] already up to date: ${filePath}`);
+            else if (beforeWorkflow.workflow.status !== "current" && beforeWorkflow.workflow.status !== "missing") {
+                throw new ConfigError(`Cannot resume workflow.db from ${beforeWorkflow.workflow.status} state.`, "INVALID_CONFIG_FILE");
             }
+            crashInMutationGapForTests("workflow");
+            advanceApplyJournal(journal, "workflow-applied");
+            crashAfterForTests("workflow");
+            const migrated = inspectMigrationState();
+            for (const [name, state] of [
+                ["state.db", migrated.state],
+                ["workflow.db", migrated.workflow],
+            ]) {
+                if (state.status !== "current" && state.status !== "missing") {
+                    throw new ConfigError(`Migration left ${name} in ${state.status} state.`, "INVALID_CONFIG_FILE");
+                }
+            }
+            backupExistingConfig(getConfigPath());
+            writeConfigAtomic(getConfigPath(), sanitizeConfigForWrite(target));
+            resetConfigCache();
+            crashInMutationGapForTests("config");
+            advanceApplyJournal(journal, "config-applied");
+            crashAfterForTests("config");
+            const completedArtifacts = inspectMigrationState();
+            if (completedArtifacts.config.status !== "current" ||
+                ![completedArtifacts.state.status, completedArtifacts.workflow.status].every((status) => status === "current" || status === "missing")) {
+                throw new ConfigError("Migration verification did not reach one current cross-artifact generation.", "INVALID_CONFIG_FILE");
+            }
+            advanceApplyJournal(journal, "committed");
+            clearApplyJournal();
+            const completed = inspectMigrationPlan();
+            return { plan: completed, backup };
         }
-        if (!anyChanged) {
-            console.log("All config files are already at the current version.");
+        catch (error) {
+            try {
+                const rollbackGeneration = fingerprintMigrationGeneration();
+                assertRollbackTransitionAllowed(journal, rollbackGeneration);
+                journal.phase = "rollback-prepared";
+                journal.generation = rollbackGeneration;
+                writeApplyJournal(journal);
+                if (!sameMigrationGeneration(fingerprintMigrationGeneration(), journal.generation)) {
+                    throw new ConfigError(`Refusing migration rollback because live artifacts no longer match journal phase ${journal.phase}.`, "INVALID_CONFIG_FILE");
+                }
+                restoreMigrationBackupWithLocksHeld(backup.path);
+                crashInMutationGapForTests("rollback");
+                clearApplyJournal();
+                resetConfigCache();
+            }
+            catch (rollbackError) {
+                throw new ConfigError(`Migration apply failed and rollback could not complete. Keep the current binary and recover from ${backup.path}. Apply error: ${error instanceof Error ? error.message : String(error)}. Rollback error: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`, "INVALID_CONFIG_FILE");
+            }
+            throw new ConfigError(`Migration apply failed; config and databases were restored from ${backup.path}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
         }
-    }
-    finally {
-        releaseLock();
-    }
+    }));
+    console.log(JSON.stringify({
+        ...result.plan,
+        status: result.plan.status === "blocked" ? "blocked" : "current",
+        ...(result.backup ? { backupPath: result.backup.path, backupRunId: result.backup.manifest.runId } : {}),
+    }));
+}
+/** Backward-compatible config subcommand routed through the canonical coordinator. */
+export async function runConfigMigrate(options = {}) {
+    if (options.dryRun || !options.preparedConfigPath)
+        return runMigrationStatus(options);
+    return runMigrationApply(options);
 }