akm-cli 0.9.17-alpha.2 → 0.9.17-alpha.4

package/dist/core/state-db.js

@@ -4,93 +4,70 @@
 /**
  * state.db — Durable SQLite database for non-regenerable akm state.
  *
- * This module OWNS the state database's shared infrastructure: path resolution,
- * the managed-db open/loan wrappers, the `BEGIN IMMEDIATE` transaction helper,
- * and schema introspection. The table-specific query helpers live by domain in
+ * This module OWNS the state database's shared infrastructure: path
+ * resolution, the open/loan wrappers and schema introspection. The
+ * table-specific query helpers live by domain in
  * `src/storage/repositories/*-repository.ts` (events, proposals, task-history,
- * improve-runs, extract-sessions, consolidation, embeddings, canaries);
- * importers reference those modules directly. The migration engine
- * lives in `./state/migrations`.
- *
- * The state DB stores non-regenerable events, proposals, task history, workflow
- * runs, and improve-pipeline ledgers.
+ * improve-runs, improve-ledger, extract-sessions, embeddings); the
+ * migration registry lives in `./state/migrations` and the runner in
+ * `storage/sqlite-migrations`. The `BEGIN IMMEDIATE` helpers are
+ * re-exported from `storage/sqlite-transaction`.
  *
  * ## Why a separate database from index.db
  *
  * index.db is a derived cache built by an idempotent baseline schema; it is fully
  * regenerable from the stash on disk, so a corrupt index is recovered by deleting
- * it and re-running `akm index` (no destructive version-bump rebuild). Events,
- * proposals, and task history are NON-REGENERABLE — losing them is data loss. They
- * live in a database whose released migration ledger is immutable and whose
- * application policy is explicit.
- *
- * ## Migration-safety contract
- *
- * The `schema_migrations` table records every applied migration by a stable string
- * ID. New installs run all migrations in order. Existing exact-prefix ledgers
- * automatically apply additive migrations and the verified data-preserving 002
- * table rebuild. Released migration 018 contains destructive cleanup DDL and is
- * never applied by an ordinary managed open. The successful `akm upgrade` path
- * must first create and verify a sibling `VACUUM INTO` snapshot, then supplies
- * the narrow explicit intent that admits 018. A pre-existing file with no
- * applied migration IDs (whether the ledger table is absent or empty) is also
- * rejected without writes; explicit upgrade snapshots its exact inode before
- * creating the ledger or applying migration 001, then retains the same writer
- * lock through migration 002's rebuild. Unknown and divergent ledgers fail
- * closed.
- *
- * Normal automatic schema evolution uses:
- *   - ALTER TABLE … ADD COLUMN <name> <type> DEFAULT <value>
- *   - CREATE INDEX IF NOT EXISTS …
- *   - CREATE TABLE IF NOT EXISTS … (additive new tables)
+ * it and re-running `akm index`. Events, proposals, task history, workflow runs
+ * and improve-pipeline ledgers are NON-REGENERABLE — losing them is data loss.
+ * They live in a database whose released migration ledger is append-only.
+ *
+ * ## Open sequence
+ *
+ * {@link openStateDatabase} opens ONE connection: mkdir the parent, open, apply
+ * the standard pragmas (`busy_timeout` 30 s first, `journal_mode` WAL with the
+ * network-filesystem fallback, `foreign_keys` ON — `storage/sqlite-pragmas`),
+ * read the `schema_migrations` ledger on that connection, and run every
+ * migration not yet applied inside one `BEGIN IMMEDIATE` transaction. A
+ * missing, empty or table-less file is simply a fresh database and gets the
+ * whole registry. A ledger carrying ids this akm does not know was written by
+ * a newer akm: the open continues with the schema this version knows and warns
+ * once ({@link warnNewerStateLedger}). Before a released migration that drops
+ * schema (`018-drop-dead-lane-schema`, `028-improve-ledger`; see
+ * `STATE_MIGRATION_SAFETY_BY_ID`) runs against an existing database, the
+ * database is copied beside itself to `state.db.pre-<id of the first such
+ * pending migration>.bak` with `VACUUM INTO` — a plain sibling copy the
+ * operator can open, nothing more. A database this open created from scratch is
+ * compacted once after its migrations, since the registry creates tables that
+ * later migrations drop. Only a ledger that DIVERGES from this akm's registry
+ * is refused (`assertMigrationLedger`).
  *
  * ## Schema design: indexed columns vs. metadata_json
  *
  * Each table holds only the columns needed for indexed queries as first-class
- * columns. All other fields live in a `metadata_json TEXT` column (a JSON object).
- * New fields can be appended to the JSON blob at any time without touching the
- * DDL. This is the same pattern used by `usage_events.metadata` in index.db and
- * by the original events.jsonl format (the `metadata` field was always free-form
- * JSON).
+ * columns. All other fields live in a `metadata_json TEXT` column (a JSON
+ * object), so new fields can be appended without touching the DDL.
  *
- * ## WAL mode
+ * ## WAL mode and writer contention
  *
- * SQLite WAL mode allows concurrent readers while a writer is active and makes
- * crashes safe (the WAL is replayed on next open). The O_APPEND multi-writer model
- * of events.jsonl is replaced by WAL-mode serialised writes — acceptable because
- * CLI commands are almost always single-writer.
- *
- * ## Writer contention (#948)
- *
- * Every open already carries a 30s `busy_timeout` (`sqlite-pragmas.ts`), so a
- * single blocked statement waits before failing. `withImmediateTransaction`
- * additionally retries `BEGIN IMMEDIATE` itself
- * ({@link WITH_IMMEDIATE_TX_MAX_ATTEMPTS} attempts) for the rarer case of two
- * writers racing the BEGIN statement back-to-back. If every attempt is still
- * contention-shaped ({@link isSqliteContentionError} — SQLITE_BUSY/LOCKED, the
- * matching message text, or the phantom-BEGIN marker), the exhaustion throw is
- * reclassified into `TransientError("STATE_DB_CONTENDED")` (exit 75, #948
- * addendum) instead of surfacing the raw driver text: another akm process (an
- * unrelated `improve`, `workflow run`, or task run — not necessarily
- * contending for the same row) is writing state.db right now. A genuinely
- * unrelated error (real corruption, a body-thrown failure) is never
- * reclassified and rethrows exactly as raised.
+ * WAL lets readers proceed while a writer is active and replays after a crash;
+ * CLI commands are almost always single-writer. Writer contention that
+ * outlasts every `BEGIN IMMEDIATE` retry surfaces as
+ * `TransientError("STATE_DB_CONTENDED")`, exit 75 (#948) — the one place that
+ * mapping lives is `storage/sqlite-transaction`.
  *
  * @module state-db
  */
-import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
-import { sleepSync } from "../runtime.js";
 import { openDatabase } from "../storage/database.js";
-import { assertMigrationLedger } from "../storage/engines/sqlite-migrations.js";
 import { openManagedDatabase, withManagedDb } from "../storage/managed-db.js";
+import { assertMigrationLedger, runMigrations, } from "../storage/sqlite-migrations.js";
+import { applyReadonlyPragmas } from "../storage/sqlite-pragmas.js";
 import { pkgVersion } from "../version.js";
-import { TransientError } from "./errors.js";
-import { acquireMaintenanceActivitySync } from "./maintenance-barrier.js";
 import { getDataDir } from "./paths.js";
-import { runMigrations, STATE_MIGRATIONS } from "./state/migrations.js";
+import { getStateMigrationSafety, STATE_MIGRATIONS } from "./state/migrations.js";
 import { warnOnce } from "./warn.js";
+export { beginImmediateTransaction, isSqliteContentionError, withImmediateTransaction, } from "../storage/sqlite-transaction.js";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -101,294 +78,7 @@ import { warnOnce } from "./warn.js";
 export function getStateDbPath() {
     return path.join(getDataDir(), "state.db");
 }
-function safetyCopyTimestamp() {
-    return new Date().toISOString().replaceAll(/[^0-9]/g, "");
-}
-function noFollowFlag() {
-    return process.platform !== "win32" && typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
-}
-function samePhysicalFile(left, right) {
-    if (left.dev !== 0n || left.ino !== 0n || right.dev !== 0n || right.ino !== 0n) {
-        return left.dev === right.dev && left.ino === right.ino;
-    }
-    return left.birthtimeNs === right.birthtimeNs && left.rdev === right.rdev;
-}
-function assertOwnedFileReservation(reservation, label) {
-    const descriptorStat = fs.fstatSync(reservation.fd, { bigint: true });
-    let pathStat;
-    try {
-        pathStat = fs.lstatSync(reservation.path, { bigint: true });
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`${label} ownership/inode verification failed because its path disappeared: ${detail}`);
-    }
-    if (pathStat.isSymbolicLink() ||
-        !pathStat.isFile() ||
-        !descriptorStat.isFile() ||
-        !samePhysicalFile(reservation.identity, descriptorStat) ||
-        !samePhysicalFile(descriptorStat, pathStat)) {
-        throw new Error(`${label} ownership/inode verification failed: its path is a symlink or was replaced.`);
-    }
-    if (process.platform !== "win32" && typeof process.geteuid === "function") {
-        const expectedUid = BigInt(process.geteuid());
-        if (descriptorStat.uid !== expectedUid || pathStat.uid !== expectedUid) {
-            throw new Error(`${label} ownership verification failed: the reserved file is not owned by the current user.`);
-        }
-    }
-    return pathStat;
-}
-function assertStateDatabaseSource(source) {
-    const descriptorStat = fs.fstatSync(source.fd, { bigint: true });
-    let pathStat;
-    try {
-        pathStat = fs.lstatSync(source.path, { bigint: true });
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`state.db source inode verification failed because its path disappeared: ${detail}`);
-    }
-    if (pathStat.isSymbolicLink() ||
-        !pathStat.isFile() ||
-        !descriptorStat.isFile() ||
-        !samePhysicalFile(source.identity, descriptorStat) ||
-        !samePhysicalFile(descriptorStat, pathStat) ||
-        descriptorStat.uid !== source.identity.uid ||
-        pathStat.uid !== source.identity.uid) {
-        throw new Error("state.db source ownership/inode verification failed: its path is a symlink or was replaced.");
-    }
-    return descriptorStat;
-}
-function descriptorAlias(handle) {
-    const candidates = process.platform === "linux"
-        ? [`/proc/self/fd/${handle.fd}`, `/dev/fd/${handle.fd}`]
-        : process.platform === "win32"
-            ? []
-            : [`/dev/fd/${handle.fd}`];
-    for (const candidate of candidates) {
-        try {
-            const stat = fs.statSync(candidate, { bigint: true });
-            if (samePhysicalFile(handle.identity, stat))
-                return candidate;
-        }
-        catch {
-            // The caller verifies the pathname immediately around SQLite open on
-            // platforms without a SQLite-openable descriptor alias.
-        }
-    }
-    return undefined;
-}
-function sqliteBoundFilePath(handle) {
-    // A descriptor-backed alias (/proc/self/fd, /dev/fd) lets SQLite open the
-    // exact held inode even if its path gets swapped out from under it. It is
-    // an optimization, not the actual protection: every caller re-verifies the
-    // held identity (dev/ino/uid) immediately before and after every open that
-    // uses this path, so a plain path is safe whenever no alias is available —
-    // Windows never has one, and macOS's /dev/fd is a small fixed-size devfs
-    // table that a process holding higher fd numbers (as a bundled standalone
-    // binary routinely does) can miss entirely. Either way, a swap in that
-    // window is still caught by the surrounding identity checks.
-    return descriptorAlias(handle) ?? handle.path;
-}
-function closeFileIdentity(handle) {
-    try {
-        fs.closeSync(handle.fd);
-    }
-    catch {
-        // Preserve the authoritative operation failure.
-    }
-}
-function reserveFreshStateDatabase(dbPath) {
-    let fd;
-    try {
-        fd = fs.openSync(dbPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_RDWR | noFollowFlag(), 0o666);
-    }
-    catch (error) {
-        if (error?.code === "EEXIST")
-            return undefined;
-        throw error;
-    }
-    try {
-        return {
-            path: dbPath,
-            fd,
-            identity: fs.fstatSync(fd, { bigint: true }),
-        };
-    }
-    catch (error) {
-        try {
-            fs.closeSync(fd);
-        }
-        catch {
-            // Preserve the fstat failure.
-        }
-        throw error;
-    }
-}
-function openExistingStateDatabaseSource(dbPath) {
-    let fd;
-    try {
-        fd = fs.openSync(dbPath, fs.constants.O_RDONLY | noFollowFlag());
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`Could not bind the existing state.db source inode: ${detail}`);
-    }
-    try {
-        return {
-            path: dbPath,
-            fd,
-            identity: fs.fstatSync(fd, { bigint: true }),
-        };
-    }
-    catch (error) {
-        try {
-            fs.closeSync(fd);
-        }
-        catch {
-            // Preserve the fstat failure.
-        }
-        throw error;
-    }
-}
-function reserveHistoricalSafetyCopy(source, migrationId) {
-    const sourceStat = assertStateDatabaseSource(source);
-    const finalMode = Number(sourceStat.mode & 384n);
-    const prefix = `${source.path}.pre-${migrationId}.${safetyCopyTimestamp()}`;
-    for (let attempt = 0; attempt < 32; attempt += 1) {
-        const candidate = `${prefix}.${randomUUID()}.bak`;
-        let fd;
-        try {
-            fd = fs.openSync(candidate, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_RDWR | noFollowFlag(), 0o600);
-        }
-        catch (error) {
-            if (error?.code === "EEXIST")
-                continue;
-            throw error;
-        }
-        let reservation;
-        try {
-            reservation = {
-                path: candidate,
-                fd,
-                identity: fs.fstatSync(fd, { bigint: true }),
-            };
-            // Keep recovery bytes owner-only throughout creation. The source-derived
-            // (never broader) final mode is restored only after verification.
-            fs.fchmodSync(fd, 0o600);
-            assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-            return { reservation, finalMode };
-        }
-        catch (error) {
-            try {
-                fs.closeSync(fd);
-            }
-            catch {
-                // Preserve the reservation/ownership failure.
-            }
-            const detail = error instanceof Error ? error.message : String(error);
-            throw new Error(`Could not secure reserved state.db safety-copy path ${candidate}: ${detail}. ` +
-                "The reserved pathname was not removed.");
-        }
-    }
-    throw new Error("Could not reserve a unique randomized state.db safety-copy path after 32 attempts.");
-}
-function fsyncDirectory(directory) {
-    if (process.platform === "win32")
-        return;
-    const fd = fs.openSync(directory, fs.constants.O_RDONLY);
-    try {
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-}
-/**
- * Create one verified, standalone SQLite snapshot immediately before released
- * migration 018 removes its retired tables/column. `VACUUM INTO` includes
- * committed WAL content in one consistent sibling database; a raw file copy
- * would not.
- */
-function createHistoricalStateSafetyCopy(source, migrationId) {
-    const { reservation, finalMode } = reserveHistoricalSafetyCopy(source, migrationId);
-    let reader;
-    try {
-        assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        assertStateDatabaseSource(source);
-        // The migration connection already holds BEGIN IMMEDIATE. A distinct
-        // read-only connection bound to the held source inode can snapshot the
-        // committed WAL view without trying to VACUUM from inside that transaction.
-        reader = openDatabase(sqliteBoundFilePath(source), { readonly: true });
-        assertStateDatabaseSource(source);
-        reader.prepare("VACUUM INTO ?").run(sqliteBoundFilePath(reservation));
-        assertStateDatabaseSource(source);
-        reader.close();
-        reader = undefined;
-        assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        fs.fsyncSync(reservation.fd);
-        assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        const verified = openDatabase(sqliteBoundFilePath(reservation), {
-            readonly: true,
-        });
-        try {
-            const quickCheck = verified.prepare("PRAGMA quick_check").get();
-            if (!quickCheck || Object.values(quickCheck)[0] !== "ok") {
-                throw new Error("SQLite quick_check did not report ok");
-            }
-            assertMigrationLedger(verified, STATE_MIGRATIONS);
-        }
-        finally {
-            verified.close();
-        }
-        assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        fs.fchmodSync(reservation.fd, finalMode);
-        fs.fsyncSync(reservation.fd);
-        assertOwnedFileReservation(reservation, "Reserved state.db safety copy");
-        fsyncDirectory(path.dirname(reservation.path));
-        closeFileIdentity(reservation);
-        return reservation.path;
-    }
-    catch (error) {
-        try {
-            reader?.close();
-        }
-        catch {
-            // Preserve the snapshot/verification failure below.
-        }
-        closeFileIdentity(reservation);
-        const detail = error instanceof Error ? error.message : String(error);
-        throw new Error(`Could not create a verified state.db safety copy before ${migrationId}: ${detail}. ` +
-            `The reserved safety-copy pathname was not removed: ${reservation.path}`);
-    }
-}
 // ── Database open ────────────────────────────────────────────────────────────
-/**
- * Open (and initialise / migrate) the state database.
- *
- * @param dbPath - Override the database file path. Pass a tmpdir path in tests
- *   to avoid touching the real user cache. Mirrors the `filePath` test seam
- *   on `EventsContext`.
- *
- * PRAGMA rationale:
- *
- *   journal_mode = WAL
- *     Write-Ahead Logging: readers never block writers and vice-versa. Crashes
- *     are safe — the WAL is replayed on next open. Required for concurrent CLI
- *     invocations that may read while another writes.
- *
- *   foreign_keys = ON
- *     Enforces FK constraints at runtime. SQLite disables them by default for
- *     backwards compatibility; enabling them prevents orphaned rows in tables
- *     that reference each other (not used in v1 schema but guards future ones).
- *
- *   busy_timeout = 30000
- *     When another connection holds a write lock, SQLite retries for up to
- *     30 000 ms before returning SQLITE_BUSY. Without this, the default timeout
- *     is 0 ms — any concurrent writer causes an immediate error. 30 s (#589)
- *     matches the value used in openDatabase() for index.db; 5 s proved too
- *     narrow when a post-inference reindex overlapped a parallel event write.
- */
 /**
  * Tell the operator once when state.db was migrated by a newer akm than the
  * one running. The open proceeds: every migration this binary knows is already
@@ -402,193 +92,102 @@ function warnNewerStateLedger(ledger) {
     warnOnce("state-db-newer-ledger", `[state.db] This akm (v${pkgVersion}) is older than the state database: ${ledger.detail}. ` +
         "Continuing with the schema this version knows; upgrade akm if its output looks incomplete.");
 }
-function unversionedDatabaseHasNoTables(db) {
-    const tables = db
-        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name != ?")
-        .get("schema_migrations");
-    return !tables;
+/**
+ * Copy the database beside itself before the first pending migration that
+ * drops schema runs. `VACUUM INTO` writes one consistent standalone file
+ * (committed WAL content included — a raw file copy would miss it) through
+ * the same connection, into a temporary name that is renamed over the final
+ * one only once the copy is complete, so a crash never leaves a half-written
+ * `.bak` behind. Returns the copy's path, or undefined when nothing pending
+ * is destructive.
+ */
+function backupBeforeDestructiveMigration(db, dbPath, pending) {
+    const destructive = pending.find((migration) => getStateMigrationSafety(migration.id) === "historical-destructive");
+    if (!destructive)
+        return undefined;
+    const backupPath = `${dbPath}.pre-${destructive.id}.bak`;
+    const partialPath = `${backupPath}.tmp`;
+    fs.rmSync(partialPath, { force: true });
+    db.prepare("VACUUM INTO ?").run(partialPath);
+    fs.renameSync(partialPath, backupPath);
+    return backupPath;
+}
+/** Read the ledger, warn on a newer one, back up before destructive DDL, then run what is pending. */
+function migrateStateDatabase(db, dbPath) {
+    const ledger = assertMigrationLedger(db, STATE_MIGRATIONS);
+    warnNewerStateLedger(ledger);
+    const pending = STATE_MIGRATIONS.slice(ledger.migrationIds.length);
+    if (pending.length === 0)
+        return { applied: [] };
+    // A database with no applied migration holds nothing akm wrote: a fresh
+    // file, `:memory:`, or an empty file left by an interrupted first open.
+    const fresh = ledger.migrationIds.length === 0;
+    const backupPath = fresh ? undefined : backupBeforeDestructiveMigration(db, dbPath, pending);
+    const applied = runMigrations(db, STATE_MIGRATIONS);
+    // The registry creates tables that later migrations drop (018, 028), which
+    // leaves free pages behind; a database created by this open starts compact.
+    if (fresh && applied.length > 0)
+        db.exec("VACUUM");
+    return backupPath ? { applied, backupPath } : { applied };
+}
+function openAndMigrate(dbPath) {
+    let report = { applied: [] };
+    const db = openManagedDatabase({
+        path: dbPath,
+        pragmas: { dataDir: path.dirname(dbPath) },
+        init: (handle) => {
+            report = migrateStateDatabase(handle, dbPath);
+        },
+    });
+    return { db, ...report };
 }
-export function openStateDatabase(dbPath, options) {
-    const canonicalPath = getStateDbPath();
-    const resolvedPath = dbPath ?? canonicalPath;
-    // `:memory:` is a SQLite connection identity, not a filesystem pathname.
-    // Never pass it through the durable-file reservation/inode/snapshot path:
-    // doing so creates a literal `:memory:` file and makes later in-process
-    // opens look like an unversioned durable database. Each in-memory handle is
-    // fresh and cannot be path-swapped, so the ownership proof is intrinsically
-    // satisfied for this explicit test/internal seam.
-    if (resolvedPath === ":memory:") {
-        return openManagedDatabase({
-            path: resolvedPath,
-            pragmas: { dataDir: path.dirname(resolvedPath) },
-            init: (db) => runMigrations(db, { freshDatabase: true }),
-        });
-    }
-    const isCanonical = path.resolve(resolvedPath) === path.resolve(canonicalPath);
-    const releaseActivity = isCanonical ? acquireMaintenanceActivitySync("state-db") : undefined;
-    let freshReservation;
-    let existingSource;
-    let openedDb;
-    let existingUnversionedDatabase = false;
-    let treatUnversionedAsFresh = false;
-    let stateSafetyCopyCreated = false;
-    try {
-        fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
-        freshReservation = reserveFreshStateDatabase(resolvedPath);
-        if (!freshReservation) {
-            existingSource = openExistingStateDatabaseSource(resolvedPath);
-            const preflight = openDatabase(sqliteBoundFilePath(existingSource), {
-                readonly: true,
-            });
-            try {
-                preflight.exec("PRAGMA busy_timeout = 30000");
-                const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
-                warnNewerStateLedger(ledger);
-                existingUnversionedDatabase = ledger.migrationIds.length === 0;
-                if (existingUnversionedDatabase && unversionedDatabaseHasNoTables(preflight)) {
-                    existingUnversionedDatabase = false;
-                    treatUnversionedAsFresh = true;
-                }
-                if (existingUnversionedDatabase && !options?.allowHistoricalDestructiveStateUpgrade) {
-                    throw new Error("Refusing to migrate an existing unversioned state.db during an ordinary managed open. " +
-                        "Run `akm upgrade` (or `akm migrate apply`) to create a verified snapshot before migration 001 " +
-                        "and apply it deliberately.");
-                }
-            }
-            finally {
-                preflight.close();
-            }
-        }
-        const boundSource = existingSource;
-        openedDb = openManagedDatabase({
-            path: boundSource ? sqliteBoundFilePath(boundSource) : resolvedPath,
-            pragmas: { dataDir: path.dirname(resolvedPath) },
-            init: (db) => {
-                runMigrations(db, {
-                    freshDatabase: !!freshReservation || treatUnversionedAsFresh,
-                    existingUnversionedDatabase,
-                    allowHistoricalDestructiveStateUpgrade: options?.allowHistoricalDestructiveStateUpgrade,
-                    beforeExistingUnversionedStateMigration: options?.allowHistoricalDestructiveStateUpgrade
-                        ? (migration) => {
-                            if (!boundSource)
-                                throw new Error("An existing unversioned state.db has no bound source inode.");
-                            const safetyCopyPath = createHistoricalStateSafetyCopy(boundSource, migration.id);
-                            stateSafetyCopyCreated = true;
-                            options.onHistoricalStateSafetyCopy?.(safetyCopyPath);
-                        }
-                        : undefined,
-                    beforeHistoricalDestructiveMigration: options?.allowHistoricalDestructiveStateUpgrade
-                        ? (migration) => {
-                            if (stateSafetyCopyCreated)
-                                return;
-                            if (!boundSource)
-                                throw new Error("Historical state migration has no bound source inode.");
-                            const safetyCopyPath = createHistoricalStateSafetyCopy(boundSource, migration.id);
-                            stateSafetyCopyCreated = true;
-                            options.onHistoricalStateSafetyCopy?.(safetyCopyPath);
-                        }
-                        : undefined,
-                });
-            },
-        });
-        if (existingSource) {
-            closeFileIdentity(existingSource);
-            existingSource = undefined;
-        }
-        if (freshReservation) {
-            closeFileIdentity(freshReservation);
-            freshReservation = undefined;
-        }
-        const db = openedDb;
-        if (!releaseActivity)
-            return db;
-        let closed = false;
-        return {
-            prepare: db.prepare.bind(db),
-            exec: db.exec.bind(db),
-            run: db.run.bind(db),
-            transaction: db.transaction.bind(db),
-            loadExtension: db.loadExtension.bind(db),
-            get inTransaction() {
-                return db.inTransaction;
-            },
-            close() {
-                if (closed)
-                    return;
-                closed = true;
-                try {
-                    db.close();
-                }
-                finally {
-                    releaseActivity();
-                }
-            },
-        };
-    }
-    catch (error) {
-        if (openedDb) {
-            try {
-                openedDb.close();
-            }
-            catch {
-                // Preserve the open/migration ownership failure.
-            }
-        }
-        if (existingSource)
-            closeFileIdentity(existingSource);
-        if (freshReservation)
-            closeFileIdentity(freshReservation);
-        releaseActivity?.();
-        throw error;
-    }
+/**
+ * Open (and initialise / migrate) the state database on one connection — see
+ * the module header for the sequence.
+ *
+ * @param dbPath - Override the database file path. Pass a tmpdir path (or
+ *   `:memory:`) in tests to avoid touching the real user data dir.
+ */
+export function openStateDatabase(dbPath = getStateDbPath()) {
+    return openAndMigrate(dbPath).db;
+}
+/** {@link openStateDatabase}, also reporting which migrations this open applied (`akm health`). */
+export function openStateDatabaseWithReport(dbPath = getStateDbPath()) {
+    return openAndMigrate(dbPath);
 }
 /**
  * Read-only: the state migration IDs the running akm would apply to `dbPath`,
- * in ledger order. Empty when the database is missing or current. Throws on a
- * ledger this akm cannot own (newer, or not an exact ordered prefix) -- the
- * same refusal a managed open makes.
+ * in ledger order. Empty when the database is missing, current, or was
+ * migrated by a newer akm. Never applies anything. A ledger that diverges from
+ * this akm's registry throws the same refusal the open does.
  */
 export function listPendingStateMigrations(dbPath = getStateDbPath()) {
     if (!fs.existsSync(dbPath))
         return [];
-    const preflight = openDatabase(dbPath, { readonly: true });
+    const db = openDatabase(dbPath, { readonly: true, create: false });
     try {
-        preflight.exec("PRAGMA busy_timeout = 30000");
-        const ledger = assertMigrationLedger(preflight, STATE_MIGRATIONS);
+        applyReadonlyPragmas(db);
+        const ledger = assertMigrationLedger(db, STATE_MIGRATIONS);
         return STATE_MIGRATIONS.slice(ledger.migrationIds.length).map((migration) => migration.id);
     }
     finally {
-        preflight.close();
+        db.close();
     }
 }
 /**
- * Apply every pending state migration, historical-destructive ones included:
- * the one step `akm upgrade` and `akm migrate apply` share, and the only
- * caller that may admit migration 018 (an ordinary managed open refuses it by
- * design). Missing/current databases are no-ops. A pre-018 exact ledger, or an
- * unversioned database, is snapshotted beside state.db and verified before the
- * immutable released migration runs.
+ * Apply every pending state migration now and report what ran — the state
+ * step of `akm migrate apply`. Any open does exactly the same work; this one
+ * just says what happened. Missing and current databases are no-ops.
  */
 export function upgradeHistoricalStateDatabase(dbPath = getStateDbPath()) {
     const pending = listPendingStateMigrations(dbPath);
     if (pending.length === 0)
         return { upgraded: false, applied: [] };
-    let safetyCopyPath;
-    try {
-        const db = openStateDatabase(dbPath, {
-            allowHistoricalDestructiveStateUpgrade: true,
-            onHistoricalStateSafetyCopy(copyPath) {
-                safetyCopyPath = copyPath;
-            },
-        });
-        db.close();
-    }
-    catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        const recovery = safetyCopyPath ? ` Verified safety copy: ${safetyCopyPath}.` : "";
-        throw new Error(`${detail}${recovery}`);
-    }
-    return safetyCopyPath ? { upgraded: true, applied: pending, safetyCopyPath } : { upgraded: true, applied: pending };
+    const { db, backupPath } = openAndMigrate(dbPath);
+    db.close();
+    return backupPath
+        ? { upgraded: true, applied: pending, safetyCopyPath: backupPath }
+        : { upgraded: true, applied: pending };
 }
 /**
  * Run `fn` against state.db, owning the handle unless one is borrowed. The loan
@@ -601,14 +200,14 @@ export function withStateDb(fn, opts) {
     return withManagedDb(() => openStateDatabase(opts?.path), fn, opts);
 }
 /**
- * Fire-and-forget telemetry write to state.db (Chunk-8 WI-8.3: usage_events'
- * durable home). Skips entirely when state.db does not exist yet (never
- * fabricates an un-migrated DB); otherwise opens the migrated DB and lowers
- * `busy_timeout` to a short window so a contended state.db (e.g. a reindex
- * finalize holding the write lock while relinking usage_events) never stalls a
- * hot path — mirrors `withIndexDb`'s `TELEMETRY_BUSY_TIMEOUT_MS`. WAL mode lets
- * the read-only migration-preflight run concurrently with a writer, so the open
- * itself does not block. Callers wrap this in their own try/catch.
+ * Fire-and-forget telemetry write to state.db (usage_events' durable home).
+ * Skips entirely when state.db does not exist yet (never fabricates an
+ * un-migrated DB); otherwise opens it and lowers `busy_timeout` to a short
+ * window so a contended state.db (e.g. a reindex finalize holding the write
+ * lock) never stalls a hot path — mirrors `withIndexDb`'s
+ * `TELEMETRY_BUSY_TIMEOUT_MS`. On a current database the open itself only
+ * reads, so it does not wait behind a writer. Callers wrap this in their own
+ * try/catch.
  */
 export function withStateDbTelemetry(fn, busyTimeoutMs = 250) {
     if (!fs.existsSync(getStateDbPath()))
@@ -622,171 +221,6 @@ export function withStateDbTelemetry(fn, busyTimeoutMs = 250) {
         db.close();
     }
 }
-// ── Migration engine ─────────────────────────────────────────────────────────
-//
-// The MIGRATIONS registry + runMigrations live in ./state/migrations (the single
-// append-only ordered source of truth). Imported for internal use by
-// openStateDatabase.
-// ── BEGIN IMMEDIATE transaction helper ───────────────────────────────────────
-/**
- * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
- *
- * `db.transaction()` is DEFERRED by default on both Bun and better-sqlite3,
- * which means two writers can both perform stale preflight reads and only race
- * when they finally attempt the write. Proposal creation and queue mutation
- * need the write lock BEFORE those reads so concurrent processes serialize on
- * the live queue state rather than clobbering each other.
- */
-/**
- * Whether `err` is one of the SQLite conditions a concurrent-writer race can
- * throw that are transient — the statement did NOT corrupt anything, another
- * writer just holds the lock right now — and therefore safe to retry or
- * reclassify as ordinary contention rather than a genuine failure:
- *   - `SQLITE_BUSY` / `SQLITE_LOCKED` (either driver's `.code`).
- *   - "database is locked" / "database table is locked" message text.
- *   - the phantom-BEGIN marker synthesized below when `BEGIN IMMEDIATE`
- *     returns without actually opening a transaction.
- *
- * This is the single shared classifier for "is this ordinary state.db
- * contention" (#948) — `isRetryableBeginError` below delegates to it, and so
- * does {@link WorkflowRunsRepository}'s lease-contention classifier (which
- * additionally matches a couple of corruption-shaped texts specific to its
- * own narrower cross-process race and keeps its own live-lease confirmation
- * before reclassifying). Matching this set alone is never sufficient to
- * declare something DEFINITELY contention when a caller needs corroborating
- * evidence (see the lease path); for `beginImmediateTransaction`'s own
- * exhaustion case there is no such evidence available, so the five 30s
- * `busy_timeout` waits already spent stand as the evidence instead.
- */
-export function isSqliteContentionError(err) {
-    const code = err?.code;
-    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED")
-        return true;
-    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    return (msg.includes("database is locked") ||
-        msg.includes("database table is locked") ||
-        // Phantom BEGIN (see below) — synthesized when BEGIN IMMEDIATE returns
-        // without opening a transaction. Safe to retry: fn() has not run.
-        msg.includes("did not open a transaction"));
-}
-/**
- * Errors `BEGIN IMMEDIATE` can throw under concurrent-writer contention that
- * are transient (the statement did NOT start a usable transaction) and safe
- * to retry. An error thrown by `fn` is a real failure and is NEVER retried.
- *
- * "cannot start a transaction within a transaction" is deliberately NOT
- * retryable: it means a transaction is already open on this connection (a
- * re-entrant call — handled by the entry guard in withImmediateTransaction),
- * and "retrying" it with a ROLLBACK would destroy the caller's transaction
- * (issue #686).
- */
-function isRetryableBeginError(err) {
-    return isSqliteContentionError(err);
-}
-const WITH_IMMEDIATE_TX_MAX_ATTEMPTS = 5;
-/** Portable synchronous sleep (works under both Bun and Node). Delegates to the runtime boundary's `sleepSync`. */
-function sleepSyncMs(ms) {
-    if (ms <= 0)
-        return;
-    sleepSync(ms);
-}
-/**
- * Open, but deliberately do not finish, an immediate transaction.
- *
- * This is the split-phase counterpart to {@link withImmediateTransaction} for
- * the source-update coordinator: index finalization must mutate state.db in a
- * transaction that remains pending until content, lockfile, and index
- * publication have all succeeded. The caller that asked for this split phase
- * owns the matching COMMIT/ROLLBACK.
- */
-/**
- * Reclassify an exhausted-retry BEGIN failure that is still contention-shaped
- * (#948) into a `TransientError("STATE_DB_CONTENDED")`, mirroring the
- * RUN_LEASE_HELD precedent (`WorkflowRunsRepository.acquireEngineLease`): the
- * driver text is accurate but unhelpful (`{"ok":false,"error":"database is
- * locked"}`, exit 70/INTERNAL) — this instead reads as a retryable-shortly
- * signal (exit 75, sysexits EX_TEMPFAIL — #948 addendum) with the original
- * error preserved as `cause` for `--verbose`/debugging. A genuinely unrelated
- * error (not contention-shaped) is rethrown exactly as raised, never
- * reclassified.
- */
-function throwBeginFailure(err) {
-    if (isSqliteContentionError(err)) {
-        const contended = new TransientError("akm's state database is busy (another akm process is writing it); retry shortly.", "STATE_DB_CONTENDED");
-        contended.cause = err;
-        throw contended;
-    }
-    throw err;
-}
-export function beginImmediateTransaction(db) {
-    if (db.inTransaction) {
-        throw new Error("beginImmediateTransaction requires a connection with no active transaction");
-    }
-    let lastBeginErr;
-    for (let attempt = 1; attempt <= WITH_IMMEDIATE_TX_MAX_ATTEMPTS; attempt++) {
-        try {
-            db.exec("BEGIN IMMEDIATE");
-            if (!db.inTransaction) {
-                throw new Error("BEGIN IMMEDIATE did not open a transaction (phantom contention state)");
-            }
-            return;
-        }
-        catch (err) {
-            lastBeginErr = err;
-            if (isRetryableBeginError(err) && attempt < WITH_IMMEDIATE_TX_MAX_ATTEMPTS) {
-                if (db.inTransaction) {
-                    try {
-                        db.exec("ROLLBACK");
-                    }
-                    catch {
-                        // Transaction already gone — safe to retry BEGIN.
-                    }
-                }
-                sleepSyncMs(2 ** (attempt - 1));
-                continue;
-            }
-            throwBeginFailure(err);
-        }
-    }
-    throwBeginFailure(lastBeginErr);
-}
-export function withImmediateTransaction(db, fn) {
-    // Re-entrancy guard (issue #686): if a transaction is already open on this
-    // connection (e.g. a nested withImmediateTransaction call inside an outer
-    // frame's fn), join it — run fn directly with no BEGIN/COMMIT/ROLLBACK of
-    // our own. Without this, the nested BEGIN throws "cannot start a transaction
-    // within a transaction", which the old retry path answered with an
-    // unconditional ROLLBACK — destroying the OUTER transaction and leaving its
-    // COMMIT to fail with "cannot commit - no transaction is active".
-    if (db.inTransaction) {
-        return fn();
-    }
-    beginImmediateTransaction(db);
-    try {
-        const result = fn();
-        if (!db.inTransaction) {
-            // The transaction we opened vanished while fn() ran (e.g. an
-            // auto-rollback or a stray ROLLBACK inside fn). fn's writes may have
-            // escaped serialization, so retrying is unsafe — fail loudly instead of
-            // letting COMMIT throw the opaque "cannot commit - no transaction is
-            // active" SQLiteError.
-            throw new Error("withImmediateTransaction invariant violated: transaction opened by BEGIN IMMEDIATE was no longer active after the transaction body ran; refusing to COMMIT (writes may have escaped serialization)");
-        }
-        db.exec("COMMIT");
-        return result;
-    }
-    catch (err) {
-        if (db.inTransaction) {
-            try {
-                db.exec("ROLLBACK");
-            }
-            catch {
-                // Ignore rollback failures so the original error is preserved.
-            }
-        }
-        throw err;
-    }
-}
 // ── schema introspection ─────────────────────────────────────────────────────
 /**
  * Return the subset of `names` that exist as TABLEs in this database, ordered