akm-cli 0.9.0-rc.4 → 0.9.0-rc.6

package/dist/cli/config-migrate.js

@@ -3,19 +3,43 @@
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 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 { backupExistingConfig, parseConfigText, readConfigText, 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 { getConfigPath, getDbPath, getStateDbPathInDataDir } 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 { mergeLockEntriesSync } from "../integrations/lockfile.js";
+import { migrateConfigSourcesToBundles, migratedLockEntries } from "../migrate/legacy/config-source-migration.js";
+import { runContentMigration } from "../migrate/legacy/content-migration.js";
+import { getLegacyWorkflowDbPath } from "../migrate/legacy/legacy-paths.js";
+import { importLegacyProposalsIntoState } from "../migrate/legacy/proposal-fs-import.js";
+import { applyTaskTargetRefMigration, planTaskTargetRefMigration } from "../migrate/legacy/task-target-ref-migration.js";
+import { buildCutoverRefMap, cutoverMergeCommitted, deleteWorkflowDb, loadCutoverRefMap, migratePilotTreatmentFiles, quarantineIndexDb, runThreeDbCutover, } from "../migrate/legacy/three-db-cutover.js";
+import { FROZEN_WORKFLOW_MIGRATIONS } from "../migrate/legacy/workflow-migrations-bodies.js";
+import { requestGc } from "../runtime.js";
+import { openDatabaseFinalizing } from "../storage/database.js";
+import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.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.";
+const APPLY_PHASE_ORDER = [
+    "prepared",
+    "state-converting",
+    "state-collapsing",
+    "state-applied",
+    "workflow-applied",
+    "cutover-applied",
+    "config-applied",
+    "tasks-prepared",
+    "tasks-applied",
+    "pilot-prepared",
+    "pilot-applied",
+    "committed",
+];
 function isFileFingerprint(value) {
     if (value === null)
         return true;
@@ -55,10 +79,57 @@ function isGenerationFingerprint(value) {
 function sameArtifactFingerprint(left, right) {
     return JSON.stringify(left) === JSON.stringify(right);
 }
+/**
+ * Collapse state.db to a SINGLE FILE (DELETE journal) for the rest of the
+ * apply. A WAL-mode state.db carries `-wal`/`-shm` sidecars that the migration
+ * generation fingerprint tracks; a later read-only inspect (or a rolled-back
+ * cutover transaction) mutates them, which would trip the "state changed
+ * outside the journaled transition" rollback guard and REFUSE the fail-closed
+ * restore. In single-file mode a rolled-back transaction leaves state.db
+ * byte-identical, so the cutover's fail-closed rollback works. The runtime
+ * restores WAL on its next openStateDatabase.
+ *
+ * The resulting journal_mode is AUTHORITATIVE, not best-effort (issue #720):
+ * if state.db could not leave WAL mode — another PROCESS holds it open
+ * (same-process zombie closes are prevented by openDatabaseFinalizing's
+ * finalize-on-close guard) — the later cutover's rolled-back transaction
+ * would mutate `-wal` and the restore would be silently refused. Fail EARLY
+ * instead: journal.phase is still "state-converting" at the call site, so the
+ * outer catch restores config+state+workflow from the backup with a clear
+ * retry message.
+ */
+function collapseStateDbToSingleFile(db) {
+    const attempt = () => {
+        try {
+            const checkpoint = db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+            if (checkpoint?.busy === 0)
+                crashInMutationGapForTests("state-checkpoint");
+            db.exec("PRAGMA journal_mode = DELETE");
+        }
+        catch {
+            // Already single-file / nothing to checkpoint, or blocked — the
+            // read-back below is the authoritative signal either way.
+        }
+        return String(db.prepare("PRAGMA journal_mode").get()?.journal_mode ?? "").toLowerCase();
+    };
+    let journalMode = attempt();
+    if (journalMode === "wal") {
+        // A zombie-closed sibling connection ANYWHERE in this process (a close()
+        // with unfinalized prepare() statements outside the openDatabaseFinalizing
+        // set) also blocks the switch until GC finalizes it. Force a collection
+        // and retry once before concluding another PROCESS holds the database.
+        requestGc();
+        journalMode = attempt();
+    }
+    if (journalMode === "wal") {
+        throw new ConfigError("Cannot convert state.db out of WAL mode for migration — another akm process is holding it open. " +
+            "Close other akm processes and re-run `akm migrate apply`.", "INVALID_CONFIG_FILE");
+    }
+}
 function hasGenerationMarker(dbPath, operationId, phase) {
     if (!fs.existsSync(dbPath))
         return false;
-    const db = openDatabase(dbPath, { readonly: true });
+    const db = openDatabaseFinalizing(dbPath, { readonly: true });
     try {
         if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='akm_migration_generation'").get()) {
             return false;
@@ -66,12 +137,495 @@ function hasGenerationMarker(dbPath, operationId, phase) {
         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;
+        return rows.length === 1 && rows[0]?.operation_id === operationId && rows[0]?.phase === phase;
+    }
+    finally {
+        db.close();
+    }
+}
+function hasGenerationMarkerFromSnapshot(dbPath, operationId, phase) {
+    if (!fs.existsSync(dbPath))
+        return false;
+    const snapshot = createSqliteReadSnapshot(dbPath, "akm-migration-marker-");
+    try {
+        return hasGenerationMarker(snapshot.databasePath, operationId, phase);
+    }
+    finally {
+        snapshot.cleanup();
+    }
+}
+const STATE_SNAPSHOT_BUFFER_BYTES = 1024 * 1024;
+class MigrationSnapshotChangedError extends ConfigError {
+}
+let migrationSnapshotHookForTests;
+export function _setMigrationSnapshotHookForTests(hook) {
+    migrationSnapshotHookForTests = hook;
+}
+function updateCanonicalValue(hash, type, value) {
+    hash.update(`${Buffer.byteLength(type)}:`);
+    hash.update(type);
+    if (value === null) {
+        hash.update("-1:");
+        return;
+    }
+    const byteLength = typeof value === "string" ? Buffer.byteLength(value) : value.byteLength;
+    hash.update(`${byteLength}:`);
+    hash.update(value);
+}
+export function canonicalStateGenerationSha256(db) {
+    const quoteIdentifier = (value) => `"${value.replaceAll('"', '""')}"`;
+    const hash = createHash("sha256");
+    for (const [name, query] of [
+        ["application_id", "SELECT CAST(application_id AS TEXT) AS value FROM pragma_application_id"],
+        ["encoding", "SELECT encoding AS value FROM pragma_encoding"],
+        ["user_version", "SELECT CAST(user_version AS TEXT) AS value FROM pragma_user_version"],
+    ]) {
+        const row = db.prepare(query).get();
+        if (!row)
+            throw new ConfigError(`Cannot fingerprint SQLite PRAGMA ${name}.`, "INVALID_CONFIG_FILE");
+        updateCanonicalValue(hash, "pragma-name", name);
+        updateCanonicalValue(hash, "pragma-value", row.value);
+    }
+    const schemaRows = db
+        .prepare("SELECT type, name, tbl_name, sql FROM sqlite_schema WHERE name <> 'akm_migration_generation' AND tbl_name <> 'akm_migration_generation' ORDER BY type COLLATE BINARY, name COLLATE BINARY, tbl_name COLLATE BINARY, sql COLLATE BINARY")
+        .iterate();
+    for (const row of schemaRows) {
+        updateCanonicalValue(hash, "schema-type", row.type);
+        updateCanonicalValue(hash, "schema-name", row.name);
+        updateCanonicalValue(hash, "schema-table", row.tbl_name);
+        updateCanonicalValue(hash, "schema-sql", row.sql);
+    }
+    const firstTable = db.prepare("SELECT name FROM sqlite_schema WHERE type='table' AND name <> 'akm_migration_generation' AND tbl_name <> 'akm_migration_generation' ORDER BY name COLLATE BINARY LIMIT 1");
+    const nextTable = db.prepare("SELECT name FROM sqlite_schema WHERE type='table' AND name <> 'akm_migration_generation' AND tbl_name <> 'akm_migration_generation' AND name COLLATE BINARY > ? ORDER BY name COLLATE BINARY LIMIT 1");
+    let tableRow = firstTable.get();
+    while (tableRow) {
+        const table = tableRow.name;
+        updateCanonicalValue(hash, "table", table);
+        const columns = [];
+        const columnRows = db
+            .prepare('SELECT CAST(cid AS TEXT) AS cid, name, type, CAST("notnull" AS TEXT) AS not_null, dflt_value, CAST(pk AS TEXT) AS pk, CAST(hidden AS TEXT) AS hidden FROM pragma_table_xinfo(?) ORDER BY cid')
+            .iterate(table);
+        for (const column of columnRows) {
+            columns.push(column.name);
+            updateCanonicalValue(hash, "column-cid", column.cid);
+            updateCanonicalValue(hash, "column-name", column.name);
+            updateCanonicalValue(hash, "column-type", column.type);
+            updateCanonicalValue(hash, "column-notnull", column.not_null);
+            updateCanonicalValue(hash, "column-default", column.dflt_value);
+            updateCanonicalValue(hash, "column-pk", column.pk);
+            updateCanonicalValue(hash, "column-hidden", column.hidden);
+        }
+        const projections = [];
+        const ordering = [];
+        const tableFlags = db
+            .prepare("SELECT CAST(wr AS TEXT) AS without_rowid FROM pragma_table_list WHERE schema='main' AND name=?")
+            .get(table);
+        if (!tableFlags) {
+            throw new ConfigError(`Cannot determine whether SQLite table ${JSON.stringify(table)} has a rowid.`, "INVALID_CONFIG_FILE");
+        }
+        const hasImplicitRowid = tableFlags.without_rowid === "0";
+        const declaredNames = new Set(columns.map((column) => column.toLowerCase()));
+        const rowidAlias = hasImplicitRowid
+            ? ["rowid", "_rowid_", "oid"].find((alias) => !declaredNames.has(alias))
+            : undefined;
+        if (hasImplicitRowid && !rowidAlias) {
+            throw new ConfigError(`Cannot fingerprint SQLite table ${JSON.stringify(table)} because all implicit rowid aliases are shadowed.`, "INVALID_CONFIG_FILE");
+        }
+        if (rowidAlias) {
+            const rowidTypeAlias = quoteIdentifier("__akm_implicit_rowid_type");
+            const rowidValueAlias = quoteIdentifier("__akm_implicit_rowid_value");
+            projections.push(`'integer' AS ${rowidTypeAlias}`, `CAST(${quoteIdentifier(rowidAlias)} AS TEXT) AS ${rowidValueAlias}`);
+            ordering.push(`${rowidTypeAlias} COLLATE BINARY`, `${rowidValueAlias} COLLATE BINARY`);
+        }
+        for (const [index, column] of columns.entries()) {
+            const quotedColumn = quoteIdentifier(column);
+            const typeAlias = quoteIdentifier(`__akm_type_${index}`);
+            const valueAlias = quoteIdentifier(`__akm_value_${index}`);
+            projections.push(`typeof(${quotedColumn}) AS ${typeAlias}`, `CASE typeof(${quotedColumn}) WHEN 'integer' THEN CAST(${quotedColumn} AS TEXT) WHEN 'real' THEN printf('%!.17g', ${quotedColumn}) WHEN 'text' THEN CAST(${quotedColumn} AS BLOB) WHEN 'blob' THEN ${quotedColumn} ELSE NULL END AS ${valueAlias}`);
+            ordering.push(`${typeAlias} COLLATE BINARY`, `${valueAlias} COLLATE BINARY`);
+        }
+        const rowStatement = db.prepare(`SELECT ${projections.join(", ")} FROM ${quoteIdentifier(table)} ORDER BY ${ordering.join(", ")}`);
+        for (const row of rowStatement.iterate()) {
+            updateCanonicalValue(hash, "row", "");
+            if (rowidAlias) {
+                const rowidType = row.__akm_implicit_rowid_type;
+                const rowidValue = row.__akm_implicit_rowid_value;
+                if (rowidType !== "integer" || typeof rowidValue !== "string") {
+                    throw new ConfigError("Cannot fingerprint an exact SQLite implicit rowid.", "INVALID_CONFIG_FILE");
+                }
+                updateCanonicalValue(hash, rowidType, rowidValue);
+            }
+            for (const [index] of columns.entries()) {
+                const type = row[`__akm_type_${index}`];
+                const value = row[`__akm_value_${index}`];
+                if (typeof type !== "string" ||
+                    (value !== null && typeof value !== "string" && !(value instanceof Uint8Array))) {
+                    throw new ConfigError("Cannot fingerprint an unsupported SQLite value.", "INVALID_CONFIG_FILE");
+                }
+                updateCanonicalValue(hash, type, value);
+            }
+        }
+        tableRow = nextTable.get(table);
+    }
+    return hash.digest("hex");
+}
+function migrationSnapshotChangedError() {
+    return new MigrationSnapshotChangedError("A SQLite migration artifact changed while creating a private status snapshot; retry when writes are idle.", "INVALID_CONFIG_FILE");
+}
+function isSnapshotPathRaceError(error) {
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP" || code === "EISDIR";
+}
+function sameOpenStateSnapshotStat(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.size === right.size &&
+        left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs);
+}
+function assertOpenStateSnapshotIdentity(source) {
+    let stat;
+    try {
+        stat = fs.lstatSync(source.path, { bigint: true });
+    }
+    catch (error) {
+        if (isSnapshotPathRaceError(error))
+            throw migrationSnapshotChangedError();
+        throw error;
+    }
+    if (!stat.isFile() || stat.dev !== source.dev || stat.ino !== source.ino)
+        throw migrationSnapshotChangedError();
+}
+function assertStateSnapshotPathAbsent(filePath) {
+    try {
+        fs.lstatSync(filePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw migrationSnapshotChangedError();
+}
+function openStateSnapshotSource(filePath, optional = false) {
+    let pathStat;
+    try {
+        pathStat = fs.lstatSync(filePath, { bigint: true });
+    }
+    catch (error) {
+        if (optional && error.code === "ENOENT")
+            return undefined;
+        if (isSnapshotPathRaceError(error))
+            throw migrationSnapshotChangedError();
+        throw error;
+    }
+    if (!pathStat.isFile()) {
+        throw new ConfigError(`Migration snapshot source is not a regular file: ${filePath}`, "INVALID_CONFIG_FILE");
+    }
+    let fd;
+    try {
+        fd = fs.openSync(filePath, "r");
+    }
+    catch (error) {
+        if (isSnapshotPathRaceError(error))
+            throw migrationSnapshotChangedError();
+        throw error;
+    }
+    try {
+        const fdStat = fs.fstatSync(fd, { bigint: true });
+        if (!fdStat.isFile() || fdStat.dev !== pathStat.dev || fdStat.ino !== pathStat.ino) {
+            throw migrationSnapshotChangedError();
+        }
+        return { path: filePath, fd, dev: fdStat.dev, ino: fdStat.ino };
+    }
+    catch (error) {
+        fs.closeSync(fd);
+        throw error;
+    }
+}
+function readStateSnapshotSource(source, destinationFd) {
+    assertOpenStateSnapshotIdentity(source);
+    const before = fs.fstatSync(source.fd, { bigint: true });
+    const hash = createHash("sha256");
+    const buffer = Buffer.allocUnsafe(STATE_SNAPSHOT_BUFFER_BYTES);
+    let position = 0;
+    while (true) {
+        const bytesRead = fs.readSync(source.fd, buffer, 0, buffer.length, position);
+        if (bytesRead === 0)
+            break;
+        hash.update(buffer.subarray(0, bytesRead));
+        if (destinationFd !== undefined) {
+            let written = 0;
+            while (written < bytesRead) {
+                written += fs.writeSync(destinationFd, buffer, written, bytesRead - written);
+            }
+        }
+        position += bytesRead;
+    }
+    const after = fs.fstatSync(source.fd, { bigint: true });
+    assertOpenStateSnapshotIdentity(source);
+    if (!sameOpenStateSnapshotStat(before, after) || BigInt(position) !== after.size) {
+        throw migrationSnapshotChangedError();
+    }
+    return { bytes: position, sha256: hash.digest("hex") };
+}
+function fingerprintStateSnapshotSources(main, wal, walPath) {
+    const mainFingerprint = readStateSnapshotSource(main);
+    const walFingerprint = wal ? readStateSnapshotSource(wal) : null;
+    if (!wal)
+        assertStateSnapshotPathAbsent(walPath);
+    return { main: mainFingerprint, wal: walFingerprint };
+}
+function copyStateSnapshotSource(source, destination) {
+    const destinationFd = fs.openSync(destination, "wx", 0o600);
+    try {
+        const fingerprint = readStateSnapshotSource(source, destinationFd);
+        fs.fsyncSync(destinationFd);
+        return fingerprint;
+    }
+    finally {
+        fs.closeSync(destinationFd);
+    }
+}
+function copyStateSnapshotSources(main, wal, walPath, databasePath) {
+    const mainFingerprint = copyStateSnapshotSource(main, databasePath);
+    const walFingerprint = wal ? copyStateSnapshotSource(wal, `${databasePath}-wal`) : null;
+    if (!wal)
+        assertStateSnapshotPathAbsent(walPath);
+    return { main: mainFingerprint, wal: walFingerprint };
+}
+function sameStateSnapshotFingerprint(left, right) {
+    return left === null || right === null ? left === right : left.bytes === right.bytes && left.sha256 === right.sha256;
+}
+function sameStateSnapshotGeneration(left, right) {
+    return sameStateSnapshotFingerprint(left.main, right.main) && sameStateSnapshotFingerprint(left.wal, right.wal);
+}
+function createSqliteReadSnapshot(sourcePath, tempPrefix, applyPhase) {
+    const walPath = `${sourcePath}-wal`;
+    const main = openStateSnapshotSource(sourcePath);
+    if (!main)
+        throw new ConfigError(`SQLite database not found: ${sourcePath}`, "INVALID_CONFIG_FILE");
+    let wal;
+    let snapshotDir;
+    let mainOpen = true;
+    let walOpen = false;
+    try {
+        wal = openStateSnapshotSource(walPath, true);
+        walOpen = wal !== undefined;
+        snapshotDir = fs.mkdtempSync(path.join(os.tmpdir(), tempPrefix));
+        fs.chmodSync(snapshotDir, 0o700);
+        const databasePath = path.join(snapshotDir, "state.db");
+        const before = fingerprintStateSnapshotSources(main, wal, walPath);
+        migrationSnapshotHookForTests?.({ sourcePath, ...(applyPhase ? { applyPhase } : {}) });
+        const copied = copyStateSnapshotSources(main, wal, walPath, databasePath);
+        const after = fingerprintStateSnapshotSources(main, wal, walPath);
+        if (!sameStateSnapshotGeneration(before, copied) || !sameStateSnapshotGeneration(before, after)) {
+            throw migrationSnapshotChangedError();
+        }
+        const completedDir = snapshotDir;
+        fs.closeSync(main.fd);
+        mainOpen = false;
+        if (wal) {
+            fs.closeSync(wal.fd);
+            walOpen = false;
+        }
+        snapshotDir = undefined;
+        return {
+            databasePath,
+            cleanup: () => fs.rmSync(completedDir, { recursive: true, force: true }),
+        };
+    }
+    finally {
+        if (mainOpen) {
+            try {
+                fs.closeSync(main.fd);
+            }
+            catch {
+                // The original snapshot failure remains authoritative.
+            }
+        }
+        if (walOpen && wal) {
+            try {
+                fs.closeSync(wal.fd);
+            }
+            catch {
+                // The original snapshot failure remains authoritative.
+            }
+        }
+        if (snapshotDir)
+            fs.rmSync(snapshotDir, { recursive: true, force: true });
+    }
+}
+function bindStateConvertingMarker(db, operationId) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS akm_migration_generation (
+      singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
+      operation_id TEXT NOT NULL,
+      phase TEXT NOT NULL,
+      generation_sha256 TEXT
+    )
+  `);
+    const columns = new Set(db.prepare("PRAGMA table_info(akm_migration_generation)").all().map((column) => column.name));
+    if (!columns.has("generation_sha256")) {
+        db.exec("ALTER TABLE akm_migration_generation ADD COLUMN generation_sha256 TEXT");
+    }
+    const generationSha256 = canonicalStateGenerationSha256(db);
+    db.prepare("INSERT INTO akm_migration_generation(singleton, operation_id, phase, generation_sha256) VALUES (1, ?, 'state-converting', ?) ON CONFLICT(singleton) DO UPDATE SET operation_id=excluded.operation_id, phase=excluded.phase, generation_sha256=excluded.generation_sha256").run(operationId, generationSha256);
+}
+function readBoundStateGenerationMarker(db, operationId) {
+    if (!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='akm_migration_generation'").get()) {
+        return undefined;
+    }
+    const columns = new Set(db.prepare("PRAGMA table_info(akm_migration_generation)").all().map((column) => column.name));
+    if (!columns.has("generation_sha256"))
+        return undefined;
+    const marker = db
+        .prepare("SELECT operation_id, phase, generation_sha256 FROM akm_migration_generation WHERE singleton=1")
+        .get();
+    const generationSha256 = marker?.generation_sha256;
+    if (!marker || marker.operation_id !== operationId || !generationSha256 || !/^[a-f0-9]{64}$/.test(generationSha256)) {
+        return undefined;
+    }
+    if (marker.phase !== "state-converting" && marker.phase !== "state-applied")
+        return undefined;
+    if (canonicalStateGenerationSha256(db) !== generationSha256) {
+        throw new ConfigError("state.db no longer matches the exact logical generation bound to its state-converting marker.", "INVALID_CONFIG_FILE");
+    }
+    return { phase: marker.phase, generationSha256 };
+}
+function readBoundStateGenerationMarkerAtPath(statePath, operationId) {
+    if (!fs.existsSync(statePath))
+        return undefined;
+    const db = openDatabaseFinalizing(statePath, { readonly: true, create: false });
+    try {
+        return readBoundStateGenerationMarker(db, operationId);
     }
     finally {
         db.close();
     }
 }
+function readBoundStateGenerationMarkerFromDisk(operationId) {
+    const statePath = getStateDbPathInDataDir();
+    if (!fs.existsSync(statePath))
+        return undefined;
+    const snapshot = createSqliteReadSnapshot(statePath, "akm-migration-state-");
+    try {
+        return readBoundStateGenerationMarkerAtPath(snapshot.databasePath, operationId);
+    }
+    finally {
+        snapshot.cleanup();
+    }
+}
+function cutoverMergeCommittedFromSnapshot(operationId) {
+    const statePath = getStateDbPathInDataDir();
+    if (!fs.existsSync(statePath))
+        return false;
+    const snapshot = createSqliteReadSnapshot(statePath, "akm-migration-state-");
+    try {
+        return cutoverMergeCommitted(snapshot.databasePath, operationId);
+    }
+    finally {
+        snapshot.cleanup();
+    }
+}
+function createMigrationInspectionSnapshots(applyPhase) {
+    const missingRoot = fs.mkdtempSync(path.join(os.tmpdir(), "akm-migration-inspect-"));
+    fs.chmodSync(missingRoot, 0o700);
+    const snapshots = [];
+    const capture = (sourcePath, prefix, name) => {
+        if (!fs.existsSync(sourcePath))
+            return path.join(missingRoot, name);
+        const snapshot = createSqliteReadSnapshot(sourcePath, prefix, applyPhase);
+        snapshots.push(snapshot);
+        return snapshot.databasePath;
+    };
+    try {
+        const paths = {
+            stateDbPath: capture(getStateDbPathInDataDir(), "akm-migration-state-", "state.db"),
+            workflowDbPath: capture(getLegacyWorkflowDbPath(), "akm-migration-workflow-", "workflow.db"),
+            indexDbPath: capture(getDbPath(), "akm-migration-index-", "index.db"),
+        };
+        return {
+            paths,
+            cleanup: () => {
+                for (const snapshot of snapshots)
+                    snapshot.cleanup();
+                fs.rmSync(missingRoot, { recursive: true, force: true });
+            },
+        };
+    }
+    catch (error) {
+        for (const snapshot of snapshots)
+            snapshot.cleanup();
+        fs.rmSync(missingRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
+function captureMigrationInspection(applyPhase) {
+    const before = fingerprintMigrationGeneration();
+    const snapshots = createMigrationInspectionSnapshots(applyPhase);
+    try {
+        const after = fingerprintMigrationGeneration();
+        if (!sameMigrationGeneration(before, after))
+            throw migrationSnapshotChangedError();
+        return {
+            paths: snapshots.paths,
+            artifacts: inspectMigrationState(snapshots.paths),
+            generation: after,
+            cleanup: snapshots.cleanup,
+        };
+    }
+    catch (error) {
+        snapshots.cleanup();
+        throw error;
+    }
+}
+function inspectMigrationStateFromSnapshots() {
+    const capture = captureMigrationInspection();
+    try {
+        return capture.artifacts;
+    }
+    finally {
+        capture.cleanup();
+    }
+}
+class MigrationPreflightGenerationError extends ConfigError {
+}
+let applyPreflightHookForTests;
+export function _setApplyPreflightHookForTests(hook) {
+    applyPreflightHookForTests = hook;
+}
+function inspectExactApplyJournalGeneration(journal) {
+    if (journal.phase !== "state-applied" && journal.phase !== "workflow-applied") {
+        throw new ConfigError(`Cannot preflight migration journal phase ${journal.phase}.`, "INVALID_CONFIG_FILE");
+    }
+    applyPreflightHookForTests?.(journal.phase);
+    const capture = captureMigrationInspection(journal.phase);
+    try {
+        if (!sameMigrationGeneration(capture.generation, journal.generation)) {
+            throw new MigrationPreflightGenerationError(`Migration apply journal phase ${journal.phase} changed before its next mutation; the external generation was preserved.`, "INVALID_CONFIG_FILE");
+        }
+        return capture.artifacts;
+    }
+    finally {
+        capture.cleanup();
+    }
+}
+function readSingleFileBoundStateMarker(journal, stateSnapshotPath) {
+    const statePath = stateSnapshotPath ?? getStateDbPathInDataDir();
+    if (!fs.existsSync(statePath) || stateDatabaseHeaderUsesWal(statePath))
+        return undefined;
+    return stateSnapshotPath
+        ? readBoundStateGenerationMarkerAtPath(statePath, journal.operationId)
+        : readBoundStateGenerationMarkerFromDisk(journal.operationId);
+}
+function advanceBoundStateMarker(db, operationId) {
+    const marker = readBoundStateGenerationMarker(db, operationId);
+    if (!marker) {
+        throw new ConfigError("state.db lacks its exact marker-bound conversion generation.", "INVALID_CONFIG_FILE");
+    }
+    db.prepare("UPDATE akm_migration_generation SET phase='state-applied' WHERE singleton=1 AND operation_id=?").run(operationId);
+}
 function generationFromBackup(manifest) {
     const fingerprint = (name) => {
         const artifact = manifest.artifacts[name];
@@ -83,30 +637,16 @@ function generationFromBackup(manifest) {
         workflow: { main: fingerprint("workflow.db"), wal: null, shm: null },
     };
 }
-function detectAdjacentGeneration(journal, manifest) {
+function detectAdjacentGeneration(journal, manifest, live, current, workflowDbPath) {
     if (journal.phase === "rollback-prepared") {
         return {
-            rollbackCompleted: sameMigrationGeneration(fingerprintMigrationGeneration(), generationFromBackup(manifest)),
+            rollbackCompleted: sameMigrationGeneration(current, 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) {
+    if (journal.phase === "state-applied" &&
+        unchanged("config", "state") &&
+        hasGenerationMarker(workflowDbPath, journal.operationId, "workflow-applied")) {
         return {
             adjacent: {
                 phase: "workflow-applied",
@@ -116,7 +656,11 @@ function detectAdjacentGeneration(journal, manifest) {
         };
     }
     const expectedTarget = `${JSON.stringify(journal.targetConfig, null, 2)}\n`;
-    if (journal.phase === "workflow-applied" &&
+    // Chunk 8, WI-8.2: config is written in the phase AFTER the cutover, so a crash
+    // in the config mutation gap leaves the journal at `cutover-applied` with the
+    // config already on disk. state (merged) + workflow (deleted) are unchanged
+    // since the cutover-applied advance — detect the config-applied adjacent.
+    if ((journal.phase === "workflow-applied" || journal.phase === "cutover-applied") &&
         unchanged("state", "workflow") &&
         fs.existsSync(getConfigPath()) &&
         readTextFileWithLimit(getConfigPath(), MAX_CONFIG_FILE_BYTES, "Config file") === expectedTarget) {
@@ -129,11 +673,16 @@ function detectAdjacentGeneration(journal, manifest) {
 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"];
+        : journal.phase === "state-converting"
+            ? ["config", "workflow"]
+            : journal.phase === "state-applied"
+                ? ["config", "state"]
+                : journal.phase === "workflow-applied" || journal.phase === "cutover-applied"
+                    ? // config is applied in the phase after the cutover, so a rollback from
+                        // either only needs state + workflow unchanged (workflow=deleted is
+                        // recorded in the journal's own generation and compares equal).
+                        ["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");
@@ -153,8 +702,8 @@ function configMatchesBytes(expectedSize, expectedHash) {
     return (fs.statSync(configPath).size === expectedSize &&
         createHash("sha256").update(Buffer.from(text)).digest("hex") === expectedHash);
 }
-function validateApplyPhase(journal, manifest) {
-    const live = inspectMigrationState();
+function validateApplyPhase(journal, manifest, inspectionPaths, inspectedState) {
+    const live = inspectedState ?? inspectMigrationState(inspectionPaths);
     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
@@ -166,6 +715,11 @@ function validateApplyPhase(journal, manifest) {
     const workflowApplied = manifest.artifacts["workflow.db"].present
         ? live.workflow.status === "current"
         : live.workflow.status === "missing";
+    // Chunk 8, WI-8.2: at/after the cutover, workflow.db is DELETED (its rows are
+    // merged into state.db). A backed-up-present workflow.db that is now missing is
+    // the intended post-cutover terminal state, not a failure.
+    const workflowDeleted = manifest.artifacts["workflow.db"].present && live.workflow.status === "missing";
+    const workflowFinal = workflowApplied || workflowDeleted;
     const expectedTarget = `${JSON.stringify(journal.targetConfig, null, 2)}\n`;
     const configApplied = live.config.status === "current" &&
         fs.existsSync(getConfigPath()) &&
@@ -174,16 +728,29 @@ function validateApplyPhase(journal, manifest) {
         ? 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;
+            : journal.phase === "state-converting" || journal.phase === "state-collapsing"
+                ? configOriginal && workflowOriginal && (stateOriginal || stateApplied)
+                : journal.phase === "state-applied"
+                    ? stateApplied && configOriginal && (workflowOriginal || workflowApplied)
+                    : journal.phase === "workflow-applied"
+                        ? stateApplied && workflowApplied && (configOriginal || configApplied)
+                        : journal.phase === "cutover-applied"
+                            ? stateApplied && workflowFinal && (configOriginal || configApplied)
+                            : // config-applied / tasks-* / pilot-* / committed
+                                stateApplied && workflowFinal && 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");
     }
+    return live;
 }
-function readApplyJournal() {
+function postCutoverArtifacts(journal, manifest, current, paths, artifacts) {
+    assertPostCutoverWorkflowAuthenticated(journal, current);
+    if (!cutoverMergeCommitted(paths.stateDbPath, journal.operationId)) {
+        throw new ConfigError(`Migration apply journal phase ${journal.phase} lacks its operation-bound cutover marker.`, "INVALID_CONFIG_FILE");
+    }
+    return validateApplyPhase(journal, manifest, paths, artifacts);
+}
+function readApplyJournalMetadata() {
     const journalPath = getMigrationApplyJournalPath();
     if (!fs.existsSync(journalPath))
         return {};
@@ -192,9 +759,16 @@ function readApplyJournal() {
         const value = JSON.parse(readTextFileWithLimit(journalPath, MAX_LOCAL_METADATA_BYTES, "Migration apply journal"));
         const phases = [
             "prepared",
+            "state-converting",
+            "state-collapsing",
             "state-applied",
             "workflow-applied",
+            "cutover-applied",
             "config-applied",
+            "tasks-prepared",
+            "tasks-applied",
+            "pilot-prepared",
+            "pilot-applied",
             "rollback-prepared",
             "committed",
         ];
@@ -252,21 +826,293 @@ function readApplyJournal() {
         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 };
+        return { journal, config, manifest };
+    }
+    catch (error) {
+        return {
+            journal,
+            error: `Unreadable migration apply journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function journalArtifactState(artifact, status = artifact.status) {
+    return {
+        status,
+        ...(artifact.migrationIds ? { migrationIds: artifact.migrationIds } : {}),
+        ...(artifact.migrationChecksums ? { migrationChecksums: artifact.migrationChecksums } : {}),
+    };
+}
+function stateBeforeCompatibilityConversion(journal, manifest) {
+    const workflowBackup = manifest.artifacts["workflow.db"];
+    const indexBackup = manifest.artifacts["index.db"];
+    return {
+        config: journalArtifactState(manifest.artifacts["config.json"]),
+        state: { status: manifest.artifacts["state.db"].present ? "current" : "missing" },
+        workflow: journal.phase === "workflow-applied" && workflowBackup.present
+            ? { status: "current" }
+            : journalArtifactState(workflowBackup),
+        index: indexBackup ? journalArtifactState(indexBackup) : { status: "missing" },
+    };
+}
+function isPreConversionCompatiblePhase(phase) {
+    return phase === "state-applied" || phase === "workflow-applied";
+}
+function isPostCutoverPhase(phase) {
+    return [
+        "cutover-applied",
+        "config-applied",
+        "tasks-prepared",
+        "tasks-applied",
+        "pilot-prepared",
+        "pilot-applied",
+        "committed",
+    ].includes(phase);
+}
+function isAuthenticatedWorkflowAdjacent(journal, current, workflowSnapshotPath) {
+    if (journal.phase !== "state-applied")
+        return false;
+    const markerPresent = workflowSnapshotPath
+        ? hasGenerationMarker(workflowSnapshotPath, journal.operationId, "workflow-applied")
+        : hasGenerationMarkerFromSnapshot(getLegacyWorkflowDbPath(), journal.operationId, "workflow-applied");
+    return (sameArtifactFingerprint(journal.generation.config, current.config) &&
+        sameArtifactFingerprint(journal.generation.state, current.state) &&
+        markerPresent);
+}
+function isAuthenticatedCutoverAdjacent(journal, current, stateSnapshotPath) {
+    return (journal.phase === "workflow-applied" &&
+        sameArtifactFingerprint(journal.generation.config, current.config) &&
+        workflowArtifactIsDeletionSubset(journal.generation, current) &&
+        (stateSnapshotPath
+            ? cutoverMergeCommitted(stateSnapshotPath, journal.operationId)
+            : cutoverMergeCommittedFromSnapshot(journal.operationId)));
+}
+function workflowArtifactIsDeletionSubset(expected, current) {
+    return ["main", "wal", "shm"].every((component) => {
+        const actual = current.workflow[component];
+        return actual === null || JSON.stringify(actual) === JSON.stringify(expected.workflow[component]);
+    });
+}
+function assertPostCutoverWorkflowAuthenticated(journal, current) {
+    if (workflowArtifactIsDeletionSubset(journal.generation, current))
+        return;
+    throw new ConfigError(`Migration apply journal phase ${journal.phase} does not authorize the live workflow.db generation.`, "INVALID_CONFIG_FILE");
+}
+function readApplyJournal() {
+    const metadata = readApplyJournalMetadata();
+    if (metadata.error || !metadata.journal || !metadata.config || !metadata.manifest)
+        return metadata;
+    const { journal, config, manifest } = metadata;
+    let capture;
+    try {
+        capture = captureMigrationInspection();
+    }
+    catch (error) {
+        return {
+            journal,
+            config,
+            error: `Unreadable migration apply journal at ${getMigrationApplyJournalPath()}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const rawGeneration = capture.generation;
+    const inspectedArtifacts = capture.artifacts;
+    try {
+        if (isPostCutoverPhase(journal.phase)) {
+            if (isTaskOnlyRepair(manifest)) {
+                const artifacts = validateApplyPhase(journal, manifest, capture.paths, inspectedArtifacts);
+                if (!sameMigrationGeneration(rawGeneration, journal.generation)) {
+                    throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+                }
+                return { journal, config, artifacts };
+            }
+            return {
+                journal,
+                config,
+                artifacts: postCutoverArtifacts(journal, manifest, rawGeneration, capture.paths, inspectedArtifacts),
+            };
+        }
+        if (!sameMigrationGeneration(rawGeneration, journal.generation) &&
+            isAuthenticatedCutoverAdjacent(journal, rawGeneration, capture.paths.stateDbPath)) {
+            const artifacts = postCutoverArtifacts({ ...journal, phase: "cutover-applied" }, manifest, rawGeneration, capture.paths, inspectedArtifacts);
+            return {
+                journal,
+                config,
+                artifacts,
+                adjacent: {
+                    phase: "cutover-applied",
+                    complete: true,
+                    generation: rawGeneration,
+                },
+            };
+        }
+        if (isPreConversionCompatiblePhase(journal.phase)) {
+            const stateMarker = readSingleFileBoundStateMarker(journal, capture.paths.stateDbPath);
+            if (stateMarker?.phase === "state-applied") {
+                if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+                    return { journal, config, artifacts: inspectedArtifacts };
+                }
+                if (isAuthenticatedWorkflowAdjacent(journal, rawGeneration, capture.paths.workflowDbPath)) {
+                    return {
+                        journal,
+                        config,
+                        artifacts: inspectedArtifacts,
+                        adjacent: {
+                            phase: "workflow-applied",
+                            complete: true,
+                            generation: rawGeneration,
+                        },
+                    };
+                }
+                throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+            }
+        }
+        if (isPreConversionCompatiblePhase(journal.phase)) {
+            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                };
+            }
+            if (isAuthenticatedWorkflowAdjacent(journal, rawGeneration, capture.paths.workflowDbPath)) {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion({ ...journal, phase: "workflow-applied" }, manifest),
+                    requiresStateConversion: true,
+                    adjacent: {
+                        phase: "workflow-applied",
+                        complete: true,
+                        generation: rawGeneration,
+                    },
+                };
+            }
             throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
         }
-        return { journal, config };
+        if (journal.phase === "state-converting") {
+            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                };
+            }
+            const marker = readBoundStateGenerationMarkerAtPath(capture.paths.stateDbPath, journal.operationId);
+            if (marker?.phase === "state-converting") {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                    adjacent: {
+                        phase: "state-collapsing",
+                        complete: true,
+                        generation: rawGeneration,
+                    },
+                };
+            }
+            throw new ConfigError("Migration apply journal phase state-converting does not match its exact marker-bound generation.", "INVALID_CONFIG_FILE");
+        }
+        if (journal.phase === "state-collapsing") {
+            if (sameMigrationGeneration(rawGeneration, journal.generation)) {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                };
+            }
+            const marker = readBoundStateGenerationMarkerAtPath(capture.paths.stateDbPath, journal.operationId);
+            if (marker) {
+                return {
+                    journal,
+                    config,
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                    adjacent: {
+                        phase: marker.phase === "state-applied" ? "state-applied" : "state-collapsing",
+                        complete: marker.phase === "state-applied",
+                        generation: rawGeneration,
+                    },
+                };
+            }
+            throw new ConfigError("Migration apply journal phase state-collapsing does not match its exact marker-bound generation.", "INVALID_CONFIG_FILE");
+        }
+        validateApplyPhase(journal, manifest, capture.paths, inspectedArtifacts);
+        if (!sameMigrationGeneration(rawGeneration, journal.generation)) {
+            const adjacent = detectAdjacentGeneration(journal, manifest, inspectedArtifacts, rawGeneration, capture.paths.workflowDbPath);
+            if (adjacent.adjacent || adjacent.rollbackCompleted) {
+                return { journal, config, artifacts: inspectedArtifacts, ...adjacent };
+            }
+            throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+        }
+        return { journal, config, artifacts: inspectedArtifacts };
     }
     catch (error) {
         return {
             journal,
-            error: `Unreadable migration apply journal at ${journalPath}: ${error instanceof Error ? error.message : String(error)}`,
+            config,
+            ...(isPreConversionCompatiblePhase(journal.phase) ||
+                journal.phase === "state-converting" ||
+                journal.phase === "state-collapsing"
+                ? {
+                    artifacts: stateBeforeCompatibilityConversion(journal, manifest),
+                    requiresStateConversion: true,
+                }
+                : { artifacts: inspectedArtifacts }),
+            error: `Unreadable migration apply journal at ${getMigrationApplyJournalPath()}: ${error instanceof Error ? error.message : String(error)}`,
         };
     }
+    finally {
+        capture.cleanup();
+    }
+}
+function authenticatePreConversionJournalForApply() {
+    const metadata = readApplyJournalMetadata();
+    if (metadata.error)
+        throw new ConfigError(metadata.error, "INVALID_CONFIG_FILE");
+    const journal = metadata.journal;
+    if (!journal || !isPreConversionCompatiblePhase(journal.phase))
+        return;
+    const current = fingerprintMigrationGeneration();
+    if (isAuthenticatedCutoverAdjacent(journal, current))
+        return;
+    if (readSingleFileBoundStateMarker(journal)?.phase === "state-applied") {
+        if (sameMigrationGeneration(current, journal.generation) ||
+            isAuthenticatedWorkflowAdjacent(journal, current) ||
+            isAuthenticatedCutoverAdjacent(journal, current)) {
+            return;
+        }
+        throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+    }
+    if (!sameMigrationGeneration(current, journal.generation) &&
+        !isAuthenticatedWorkflowAdjacent(journal, current) &&
+        !isAuthenticatedCutoverAdjacent(journal, current)) {
+        throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+    }
+}
+function preparePreConversionJournalForApply() {
+    const metadata = readApplyJournalMetadata();
+    if (metadata.error)
+        throw new ConfigError(metadata.error, "INVALID_CONFIG_FILE");
+    const journal = metadata.journal;
+    if (!journal || !isPreConversionCompatiblePhase(journal.phase))
+        return;
+    let current = fingerprintMigrationGeneration();
+    if (isAuthenticatedCutoverAdjacent(journal, current))
+        return;
+    if (readSingleFileBoundStateMarker(journal)?.phase === "state-applied")
+        return;
+    if (!sameMigrationGeneration(current, journal.generation)) {
+        if (!isAuthenticatedWorkflowAdjacent(journal, current)) {
+            throw new ConfigError(`Migration apply journal phase ${journal.phase} does not match the exact live artifact generation.`, "INVALID_CONFIG_FILE");
+        }
+        current = fingerprintMigrationGeneration();
+    }
+    journal.phase = "state-converting";
+    journal.generation = current;
+    writeApplyJournal(journal);
 }
 function writeApplyJournal(journal) {
     fs.mkdirSync(path.dirname(getMigrationApplyJournalPath()), { recursive: true, mode: 0o700 });
@@ -278,8 +1124,7 @@ function writeApplyJournal(journal) {
     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))
+    if (APPLY_PHASE_ORDER.indexOf(phase) > APPLY_PHASE_ORDER.indexOf(journal.phase))
         journal.phase = phase;
     journal.generation = fingerprintMigrationGeneration();
     writeApplyJournal(journal);
@@ -307,11 +1152,344 @@ function crashInMutationGapForTests(phase) {
     if (process.env.AKM_TEST_MIGRATION_CRASH_GAP === phase)
         process.kill(process.pid, "SIGKILL");
 }
+function isForwardRecoveryPhase(phase) {
+    return [
+        "state-collapsing",
+        "cutover-applied",
+        "config-applied",
+        "tasks-prepared",
+        "tasks-applied",
+        "pilot-prepared",
+        "pilot-applied",
+        "committed",
+    ].includes(phase);
+}
+/** Publish a preflighted task-target batch inside the journal's forward-only region. */
+function runTaskTargetMigrationStep(journal, plan) {
+    applyTaskTargetRefMigration(plan);
+    crashInMutationGapForTests("tasks");
+    advanceApplyJournal(journal, "tasks-applied");
+    crashAfterForTests("tasks");
+}
+function isTaskOnlyRepair(manifest) {
+    return (manifest.artifacts["config.json"].status === "current" &&
+        ["current", "missing"].includes(manifest.artifacts["state.db"].status) &&
+        manifest.artifacts["workflow.db"].status === "missing");
+}
+function runTaskOnlyRepair(journal, plan) {
+    advanceApplyJournal(journal, "tasks-prepared");
+    if (journal.phase === "tasks-prepared")
+        runTaskTargetMigrationStep(journal, plan);
+    advanceApplyJournal(journal, "committed");
+    clearApplyJournal();
+}
+function runStateMigrationStep(journal) {
+    if (journal.phase === "prepared") {
+        advanceApplyJournal(journal, "state-converting");
+        crashAfterForTests("state-converting");
+    }
+    if (journal.phase === "state-converting") {
+        const db = openDatabaseFinalizing(getStateDbPathInDataDir());
+        try {
+            const marker = readBoundStateGenerationMarker(db, journal.operationId);
+            if (marker?.phase === "state-applied") {
+                throw new ConfigError("state.db is ahead of its state-converting journal.", "INVALID_CONFIG_FILE");
+            }
+            if (!marker) {
+                db.transaction(() => {
+                    runStateMigrations(db);
+                    bindStateConvertingMarker(db, journal.operationId);
+                })();
+            }
+            else {
+                runStateMigrations(db, { applyPending: false });
+            }
+        }
+        finally {
+            db.close();
+        }
+        crashInMutationGapForTests("state-marker");
+        advanceApplyJournal(journal, "state-collapsing");
+        crashAfterForTests("state-marker");
+    }
+    if (journal.phase === "state-collapsing") {
+        if (!sameMigrationGeneration(fingerprintMigrationGeneration(), journal.generation)) {
+            const marker = readBoundStateGenerationMarkerFromDisk(journal.operationId);
+            if (!marker) {
+                throw new ConfigError("state.db does not match the exact marker-bound generation recorded before conversion.", "INVALID_CONFIG_FILE");
+            }
+            journal.phase = marker.phase === "state-applied" ? "state-applied" : "state-collapsing";
+            journal.generation = fingerprintMigrationGeneration();
+            writeApplyJournal(journal);
+            if (journal.phase === "state-applied")
+                return;
+        }
+        const db = openDatabaseFinalizing(getStateDbPathInDataDir());
+        try {
+            if (!readBoundStateGenerationMarker(db, journal.operationId)) {
+                throw new ConfigError("state.db lacks its exact marker-bound conversion generation.", "INVALID_CONFIG_FILE");
+            }
+            collapseStateDbToSingleFile(db);
+            crashInMutationGapForTests("state-converting");
+            advanceBoundStateMarker(db, journal.operationId);
+        }
+        finally {
+            db.close();
+        }
+        crashInMutationGapForTests("state");
+        advanceApplyJournal(journal, "state-applied");
+        crashAfterForTests("state");
+    }
+}
+function stateDatabaseHeaderUsesWal(filePath) {
+    const fd = fs.openSync(filePath, "r");
+    try {
+        const header = Buffer.alloc(20);
+        if (fs.readSync(fd, header, 0, header.byteLength, 0) !== header.byteLength) {
+            throw new ConfigError(`Cannot verify the SQLite header for ${filePath}.`, "INVALID_CONFIG_FILE");
+        }
+        if (!header.subarray(0, 16).equals(Buffer.from("SQLite format 3\0"))) {
+            throw new ConfigError(`Cannot verify a non-SQLite state database at ${filePath}.`, "INVALID_CONFIG_FILE");
+        }
+        return header[18] === 2 || header[19] === 2;
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function assertStateReadyForCutover(journal) {
+    const statePath = getStateDbPathInDataDir();
+    if (!fs.existsSync(statePath)) {
+        throw new ConfigError("Cannot run cutover without state.db.", "INVALID_CONFIG_FILE");
+    }
+    if (stateDatabaseHeaderUsesWal(statePath)) {
+        throw new ConfigError("Refusing cutover because state.db still uses WAL; resume through the state-converting phase first.", "INVALID_CONFIG_FILE");
+    }
+    const db = openDatabaseFinalizing(statePath, { readonly: true });
+    try {
+        const journalMode = String(db.prepare("PRAGMA journal_mode").get()?.journal_mode ?? "").toLowerCase();
+        const hasMarkerTable = db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='akm_migration_generation'")
+            .get();
+        const marker = hasMarkerTable
+            ? db
+                .prepare("SELECT operation_id, phase FROM akm_migration_generation WHERE singleton=1 LIMIT 2")
+                .all()
+            : [];
+        if (journalMode !== "delete" ||
+            marker.length !== 1 ||
+            marker[0]?.operation_id !== journal.operationId ||
+            marker[0]?.phase !== "state-applied") {
+            throw new ConfigError("Refusing cutover because state.db lacks the operation-bound state-converting/single-file proof.", "INVALID_CONFIG_FILE");
+        }
+    }
+    finally {
+        db.close();
+    }
+}
+function assertMigrationArtifactsComplete() {
+    const completed = inspectMigrationState();
+    if (completed.config.status !== "current" ||
+        ![completed.state.status, completed.workflow.status].every((status) => status === "current" || status === "missing")) {
+        throw new ConfigError("Migration verification did not reach one current cross-artifact generation.", "INVALID_CONFIG_FILE");
+    }
+}
+/** Expand a leading `~` against the home directory (config stashDir/source paths may use it). */
+function expandTilde(p) {
+    if (p === "~")
+        return os.homedir();
+    if (p.startsWith("~/") || p.startsWith("~\\"))
+        return path.join(os.homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Stash roots for the cutover ref map's origin aliases, the
+ * source-(b) legacy walk, AND the WI-8.5d content migration's `.stash.json`
+ * fold + D-R6 rename walk. Derived from the TARGET config, which by this point in
+ * the apply has already been normalized to the 0.9 `bundles` shape by
+ * {@link parseMigrationTargetConfig}: each path-bearing bundle is a root, the
+ * `defaultBundle` is the primary, and a bundle's `registryId` (or its key)
+ * supplies the origin alias. The pre-cutover `stashDir`/`sources` shape is still
+ * honored as a fallback for a transitional config that reaches here un-migrated.
+ * Source (a) (the index `item_ref` join) is authoritative, so an unresolved root
+ * only costs a few origin aliases.
+ */
+function cutoverStashRootsFromConfig(config) {
+    const roots = [];
+    const bundles = config.bundles;
+    if (bundles && typeof bundles === "object") {
+        for (const [id, entry] of Object.entries(bundles)) {
+            const bundlePath = entry.path;
+            if (typeof bundlePath !== "string" || bundlePath.length === 0)
+                continue; // only filesystem bundles
+            const registryId = entry.registryId ?? id;
+            roots.push({
+                path: path.resolve(expandTilde(bundlePath)),
+                registryId,
+                primary: config.defaultBundle === id,
+            });
+        }
+    }
+    return roots;
+}
+/**
+ * Roll a pre-cutover workflow.db forward to its final ledger (010) using the
+ * FROZEN migration bodies (`src/migrate/legacy/workflow-migrations-bodies.ts`)
+ * through the shared engine — never the live `WORKFLOW_MIGRATIONS` array
+ * (`src/workflows/db.ts` is deleted in WI-8.3). The roll materialises every
+ * migration-added column + DEFAULT so the subsequent state.db merge carries
+ * faithful data.
+ *
+ * Pre-versioning (0.7-era) workflow.dbs — rows present but NO `schema_migrations`
+ * ledger — are OUT of the migrator FROM-state (the rc-train fixtures pin a
+ * versioned ledger). We FAIL CLOSED with a clear message rather than
+ * bootstrapping (the old `bootstrapPreVersioningDb` back-fill is retired).
+ */
+function runFrozenWorkflowRoll(operationId) {
+    const workflowPath = getLegacyWorkflowDbPath();
+    const db = openDatabaseFinalizing(workflowPath);
+    try {
+        const hasRuns = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='workflow_runs'").get();
+        const hasLedger = !!db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='schema_migrations'").get();
+        if (hasRuns && !hasLedger) {
+            throw new ConfigError(`Refusing to migrate a pre-versioning workflow.db at ${workflowPath} (no schema_migrations ledger). ` +
+                "Pre-0.8 workflow databases are not a supported migrator source; upgrade through a 0.8.x release first.", "INVALID_CONFIG_FILE");
+        }
+        // Roll the pending frozen migrations ONLY — never the base-schema DDL. Any
+        // real pre-cutover workflow.db already carries the base schema (its runtime
+        // opener created it); running the baseline CREATE INDEX here would fail on a
+        // pre-existing-but-narrower table. Matches the WI-8.2 workflow-applied path
+        // (openDatabase + runSqliteMigrations, no pragmas/base-schema), preserving
+        // the crash-recovery generation-fingerprint invariants that flow pins.
+        runSqliteMigrations(db, FROZEN_WORKFLOW_MIGRATIONS, {
+            generationMarker: { operationId, phase: "workflow-applied" },
+        });
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * The `cutover-applied` phase (Chunk 8, WI-8.2). Builds + persists the
+ * old-ref → item_ref map, runs the fail-closed three-DB merge/re-key
+ * transaction, then the idempotent index-quarantine / workflow.db-unlink
+ * boundary ops. A committed merge marker (from an interrupted-then-resumed
+ * apply) short-circuits the merge so it runs exactly once.
+ */
+function runCutoverStep(journal, target) {
+    const statePath = getStateDbPathInDataDir();
+    const workflowPath = getLegacyWorkflowDbPath();
+    const indexPath = getDbPath();
+    const stashRoots = cutoverStashRootsFromConfig(target);
+    if (!cutoverMergeCommitted(statePath, journal.operationId)) {
+        const refMap = buildCutoverRefMap({
+            oldIndexDbPath: indexPath,
+            stashRoots,
+            mapOutputPath: cutoverRefMapPath(journal),
+        });
+        // Fail-closed: an integrity failure (unparseable ref / row-count mismatch)
+        // throws a CutoverIntegrityError, which the outer catch converts to a
+        // restore-from-backup. The state txn is atomic — a throw rolls it back, so
+        // state.db + workflow.db are unchanged going into the rollback.
+        runThreeDbCutover({ refMap, operationId: journal.operationId, statePath, workflowPath, oldIndexPath: indexPath });
+        crashInMutationGapForTests("cutover-commit");
+    }
+    else {
+        assertPostCutoverWorkflowAuthenticated(journal, fingerprintMigrationGeneration());
+    }
+    // Boundary ops run AFTER the committed state txn, OUTSIDE the fail-closed gate
+    // (cutover-design.md §2 step 5/6). Idempotent + best-effort — they log and
+    // return, never throw, so a rename/unlink hiccup never rolls back the merge.
+    quarantineIndexDb(journal.operationId, indexPath);
+    deleteWorkflowDb(workflowPath);
+    // WI-8.5d: the content migration (`.stash.json` fold + delete, D-R6 reserved-
+    // filename conformance) is an ADDITIVE filesystem step of the same phase. It
+    // also runs AFTER the committed state txn, is best-effort (a throw is swallowed
+    // + logged, never aborting a committed cutover), and idempotent (a resumed
+    // apply finds no sidecars and no mis-named concepts, so it re-runs to a no-op).
+    runContentMigrationStep(journal, target);
+}
+function cutoverRefMapPath(journal) {
+    return path.join(path.dirname(getMigrationApplyJournalPath()), `cutover-refmap-${journal.operationId}.json`);
+}
+/** Required forward-only filesystem step after the core config/database cutover verifies. */
+function runPilotTreatmentStep(journal, target) {
+    const refMap = loadCutoverRefMap(cutoverRefMapPath(journal));
+    migratePilotTreatmentFiles(cutoverStashRootsFromConfig(target), refMap);
+}
+/**
+ * Persist location for the content-migration report — next to the ApplyJournal
+ * (alongside the cutover ref map). Survives `clearApplyJournal` (which removes
+ * only the journal file), so the operator + the WI-8.5d test can read the D-R6
+ * rename list after a committed apply.
+ */
+function contentMigrationReportPath() {
+    return path.join(path.dirname(getMigrationApplyJournalPath()), "content-migration-report.json");
+}
+/** Best-effort content migration + report persistence (see {@link runCutoverStep}). */
+function runContentMigrationStep(journal, target) {
+    try {
+        const roots = cutoverStashRootsFromConfig(target).map((r) => r.path);
+        const report = runContentMigration(roots);
+        // Fold the one-time pre-0.9 filesystem-proposal import into this same
+        // additive step (it used to run on every proposal operation via
+        // `withProposalsDb`). state.db has been merged + collapsed to single-file
+        // DELETE mode by this point, so we open it raw and INSERT OR IGNORE each
+        // legacy `proposal.json` on its UUID — idempotent, no ledger needed.
+        //
+        // rc-window edge: a user who already ran `akm migrate apply` on an EARLIER
+        // rc binary (before this fold existed) AND never ran a proposal command
+        // afterward would have their pre-0.9 fs proposals un-imported — the old
+        // live-path import that once covered that gap is gone. Re-running this
+        // idempotent `migrate apply` recovers them (the legacy files are left in
+        // place on import, so they are still there to re-walk). Acceptable for an rc.
+        report.legacyProposalsImported = importLegacyProposalsIntoState(getStateDbPathInDataDir(), roots);
+        persistContentMigrationReport(report);
+        if (report.sidecarsFolded > 0 || report.reservedRenames.length > 0 || report.legacyProposalsImported > 0) {
+            console.log(JSON.stringify({
+                event: "content-migration",
+                operationId: journal.operationId,
+                ...report,
+            }));
+        }
+    }
+    catch (error) {
+        console.error(`[akm] content migration skipped (${error instanceof Error ? error.message : String(error)}); the committed cutover is unaffected.`);
+    }
+}
+function persistContentMigrationReport(report) {
+    try {
+        const reportPath = contentMigrationReportPath();
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true, mode: 0o700 });
+        writeFileAtomic(reportPath, `${JSON.stringify(report, null, 2)}\n`, 0o600);
+    }
+    catch {
+        // The report is auditing-only; a persistence failure never affects the cutover.
+    }
+}
 function unsafeArtifact(name, state) {
     if (!["newer", "inconsistent", "corrupt"].includes(state.status))
         return undefined;
     return `${name} is ${state.status}${state.detail ? `: ${state.detail}` : ""}`;
 }
+/**
+ * Parse + validate a migration TARGET config, applying the Chunk-8 config-shape
+ * migration (`stashDir`/`sources[]`/`installed[]` → `bundles`/`defaultBundle`)
+ * as a pre-validation transform. This is why a target still carrying the
+ * pre-cutover source shape loads (and reports "current" in `migrate status`)
+ * even though the runtime loader now rejects that shape once `bundles` exists:
+ * the migrator normalizes it FIRST, then the strict schema gates the result.
+ *
+ * The transform is idempotent, so an already-migrated prepared config, or the
+ * new-shape config re-parsed from the apply journal, passes through untouched.
+ */
+function parseMigrationTargetConfig(text, sourcePath) {
+    const raw = parseConfigText(text, sourcePath);
+    const migrated = migrateConfigSourcesToBundles(raw);
+    // Re-serialize the normalized object through the canonical validator so the
+    // version check, schema validation, and defaults merge stay in one place.
+    return parseAndValidateConfigText(JSON.stringify(migrated), sourcePath);
+}
 function loadTargetConfig(preparedConfigPath, artifacts) {
     const targetPath = preparedConfigPath ?? (artifacts.config.status === "current" ? getConfigPath() : undefined);
     if (!targetPath) {
@@ -340,7 +1518,7 @@ function loadTargetConfig(preparedConfigPath, artifacts) {
                 source: preparedConfigPath ? "prepared" : "active",
                 path: targetPath,
             },
-            config: parseAndValidateConfigText(text, targetPath),
+            config: parseMigrationTargetConfig(text, targetPath),
         };
     }
     catch (error) {
@@ -355,7 +1533,7 @@ function loadTargetConfig(preparedConfigPath, artifacts) {
     }
 }
 function buildMigrationPlan(preparedConfigPath, activeApply) {
-    const artifacts = inspectMigrationState();
+    const artifacts = activeApply.artifacts ?? inspectMigrationStateFromSnapshots();
     const restorePending = fs.existsSync(getMigrationRestoreJournalPath());
     const target = activeApply.journal
         ? {
@@ -375,14 +1553,25 @@ function buildMigrationPlan(preparedConfigPath, activeApply) {
     ].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)
+    if (activeApply.error && (!activeApply.journal || target.state.status === "current"))
         blockers.push(activeApply.error);
     if (restorePending)
         blockers.push(`Restore recovery is pending at ${getMigrationRestoreJournalPath()}.`);
+    let taskRewrites = 0;
+    if (blockers.length === 0 && target.config) {
+        try {
+            taskRewrites = planTaskTargetRefMigration(target.config).rewrites.length;
+        }
+        catch (error) {
+            blockers.push(error instanceof Error ? error.message : String(error));
+        }
+    }
     const needsApply = !!activeApply.journal ||
         artifacts.config.status !== "current" ||
         artifacts.state.status === "old" ||
-        artifacts.workflow.status === "old";
+        artifacts.workflow.status === "old" ||
+        artifacts.workflow.status === "current" ||
+        taskRewrites > 0;
     return {
         status: blockers.length > 0 ? "blocked" : needsApply ? "ready" : "current",
         artifacts,
@@ -432,8 +1621,12 @@ export async function runMigrationApply(options = {}) {
         return;
     }
     const result = withConfigLock(() => withMaintenanceStartBarrier(() => {
-        assertNoArtifactReplacementBlockers();
         recoverInterruptedRestoreWithLocksHeld();
+        authenticatePreConversionJournalForApply();
+        assertNoArtifactReplacementBlockers(undefined, {
+            skipWorkflowClaims: fs.existsSync(getMigrationApplyJournalPath()),
+        });
+        preparePreConversionJournalForApply();
         const active = readApplyJournal();
         if (active.error)
             throw new ConfigError(active.error, "INVALID_CONFIG_FILE");
@@ -474,69 +1667,103 @@ export async function runMigrationApply(options = {}) {
         };
         if (!active.journal)
             writeApplyJournal(journal);
+        const taskOnlyRepair = isTaskOnlyRepair(backup.manifest);
+        let forwardRecoveryRequired = isForwardRecoveryPhase(journal.phase);
         try {
-            const beforeState = inspectMigrationState();
-            if (beforeState.state.status === "old") {
-                const db = openDatabase(getStateDbPathInDataDir());
-                try {
-                    runStateMigrations(db, {
-                        generationMarker: { operationId: journal.operationId, phase: "state-applied" },
-                    });
+            const taskTargetPlan = planTaskTargetRefMigration(target);
+            if (taskOnlyRepair) {
+                forwardRecoveryRequired = true;
+                runTaskOnlyRepair(journal, taskTargetPlan);
+                return { plan: inspectMigrationPlan(), backup };
+            }
+            runStateMigrationStep(journal);
+            forwardRecoveryRequired = isForwardRecoveryPhase(journal.phase);
+            if (isPostCutoverPhase(journal.phase))
+                runCutoverStep(journal, target);
+            if (journal.phase === "state-applied") {
+                // Roll the pre-cutover workflow.db through the frozen migration bodies
+                // only while the journal is still before the committed cutover.
+                const beforeWorkflow = inspectExactApplyJournalGeneration(journal);
+                if (beforeWorkflow.workflow.status === "old") {
+                    runFrozenWorkflowRoll(journal.operationId);
                 }
-                finally {
-                    db.close();
+                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");
             }
-            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");
+            if (journal.phase === "workflow-applied") {
+                const migrated = inspectExactApplyJournalGeneration(journal);
+                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");
+                    }
+                }
+                assertStateReadyForCutover(journal);
+                runCutoverStep(journal, target);
+                forwardRecoveryRequired = true;
+                crashInMutationGapForTests("cutover");
+                advanceApplyJournal(journal, "cutover-applied");
+                crashAfterForTests("cutover");
             }
-            crashInMutationGapForTests("state");
-            advanceApplyJournal(journal, "state-applied");
-            crashAfterForTests("state");
-            const beforeWorkflow = inspectMigrationState();
-            if (beforeWorkflow.workflow.status === "old") {
-                const db = openDatabase(getWorkflowDbPath());
+            if (journal.phase === "cutover-applied") {
+                // The cutover is committed, so all remaining work is forward-only.
                 try {
-                    runWorkflowMigrations(db, {
-                        generationMarker: { operationId: journal.operationId, phase: "workflow-applied" },
-                    });
+                    const preCutoverText = readConfigText(getConfigPath());
+                    if (preCutoverText !== undefined) {
+                        mergeLockEntriesSync(migratedLockEntries(parseConfigText(preCutoverText, getConfigPath())));
+                    }
                 }
-                finally {
-                    db.close();
+                catch {
+                    // Advisory lock re-key only; the committed cutover is unaffected.
                 }
+                backupExistingConfig(getConfigPath());
+                writeConfigAtomic(getConfigPath(), sanitizeConfigForWrite(target));
+                resetConfigCache();
+                crashInMutationGapForTests("config");
+                advanceApplyJournal(journal, "config-applied");
+                crashAfterForTests("config");
             }
-            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");
-                }
+            if (journal.phase === "config-applied") {
+                assertMigrationArtifactsComplete();
+                advanceApplyJournal(journal, "tasks-prepared");
             }
-            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");
+            if (journal.phase === "tasks-prepared") {
+                forwardRecoveryRequired = true;
+                runTaskTargetMigrationStep(journal, taskTargetPlan);
+            }
+            if (journal.phase === "tasks-applied")
+                advanceApplyJournal(journal, "pilot-prepared");
+            if (journal.phase === "pilot-prepared") {
+                forwardRecoveryRequired = true;
+                runPilotTreatmentStep(journal, target);
+                crashInMutationGapForTests("pilot");
+                advanceApplyJournal(journal, "pilot-applied");
+                crashAfterForTests("pilot");
+            }
+            if (journal.phase === "pilot-applied")
+                advanceApplyJournal(journal, "committed");
             clearApplyJournal();
             const completed = inspectMigrationPlan();
             return { plan: completed, backup };
         }
         catch (error) {
+            if (error instanceof MigrationPreflightGenerationError || error instanceof MigrationSnapshotChangedError) {
+                forwardRecoveryRequired = true;
+            }
+            if (isForwardRecoveryPhase(journal.phase))
+                forwardRecoveryRequired = true;
+            if (!forwardRecoveryRequired && cutoverMergeCommitted(getStateDbPathInDataDir(), journal.operationId)) {
+                forwardRecoveryRequired = true;
+            }
+            if (forwardRecoveryRequired) {
+                throw new ConfigError(`Migration apply requires forward recovery from ${getMigrationApplyJournalPath()}: ${error instanceof Error ? error.message : String(error)}`, "INVALID_CONFIG_FILE");
+            }
             try {
                 const rollbackGeneration = fingerprintMigrationGeneration();
                 assertRollbackTransitionAllowed(journal, rollbackGeneration);