akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/migrate/legacy/three-db-cutover.js

@@ -1,841 +0,0 @@
-// This Source Code Form is subject to the terms of the Mozilla Public
-// License, v. 2.0. If a copy of the MPL was not distributed with this
-// file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * @removeIn 0.10.0
- *
- * The one-time three-DB cutover DATA step (akm 0.9.0 Chunk 8, WI-8.2;
- * plan §3.2/§3.3/§8, normative §11.4, chunk-8 cutover design). Migration
- * `020-three-db-cutover` is the pure additive
- * DDL (`CREATE TABLE IF NOT EXISTS` the merge-target tables); THIS module is the
- * code that MOVES the durable rows into place, exactly once, under the
- * migrate-apply fail-closed gate (`src/cli/config-migrate.ts` `cutover-applied`
- * phase). It never runs as a sealed SQL migration body — the ATTACH path is
- * runtime-resolved and the old-ref → item_ref map is filesystem/index-derived.
- *
- * ## Frozen-resolver rule (plan §3.3 item 2)
- *
- * Old-ref resolution NEVER runs through new-layout code. This module therefore
- * imports ONLY the frozen legacy surface (`./legacy-layout`), the stored-ref
- * grammar (`../legacy-ref-grammar`), storage-engine helpers (`openDatabase`,
- * `applyStandardPragmas`), core path/warn leaves, and Node builtins. It imports
- * NOTHING from `src/indexer/` or `src/workflows/`: the last-good-index join
- * reads the ATTACHED old index.db by raw SQL, never through indexer code, and
- * the workflow merge reads the ATTACHED old workflow.db by raw SQL.
- *
- * ## Design choices where the design is silent (documented per the WI brief)
- *
- *  - **ATTACH is read-write, safety enforced by construction.** `cutover-design`
- *    calls for read-only ATTACH; to stay driver-portable (bun:sqlite has no
- *    URI-mode guarantee) we ATTACH normally but (a) pre-check `fs.existsSync`
- *    before every ATTACH so a missing file is never silently CREATED, and (b)
- *    only ever `SELECT` from the attached schemas — the sole writes target
- *    `main` (state.db). This is behaviourally equivalent to a read-only ATTACH.
- *  - **Column-intersection copy.** The workflow / usage_events merge copies the
- *    INTERSECTION of columns present in both the source and the target table, so
- *    a source DB at any pre-cutover shape (or a partially-migrated test fixture)
- *    copies verbatim what it holds without tripping "no such column".
- *  - **Durable idempotency marker.** The merge writes a singleton row into
- *    `akm_cutover_ledger` INSIDE the same transaction as the data move, so a
- *    crash after COMMIT (but before the journal advances, or the workflow.db
- *    unlink) never re-runs the INSERT…SELECT (which would duplicate rows). The
- *    boundary ops (index quarantine, workflow.db unlink) key on that committed
- *    marker and are idempotent.
- *  - **Ref-map source (b) — the frozen legacy-layout walk — is best-effort.**
- *    It only ADDS mappings for on-disk assets the index no longer holds, using
- *    the source's `registryId` (or a local basename slug) as the bundle. The
- *    primary correctness path is source (a): the last-good index join, which
- *    reads the durable `item_ref` directly.
- */
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { warn } from "../../core/warn.js";
-import { openDatabaseFinalizing } from "../../storage/database.js";
-import { applyStandardPragmas } from "../../storage/sqlite-pragmas.js";
-import { classifyRefGrammar, parseStoredRef } from "../legacy-ref-grammar.js";
-import { deriveCanonicalAssetName, TYPE_DIRS } from "./legacy-layout.js";
-// ═══════════════════════════════════════════════════════════════════════
-// Errors + report shapes
-// ═══════════════════════════════════════════════════════════════════════
-/**
- * A re-key INTEGRITY failure (unparseable stored ref, or a post-pass row-count
- * mismatch). Distinct from an EXPECTED orphan (old ref → no live item), which is
- * quarantined and never aborts the cutover. The apply flow converts this typed
- * error into a fail-closed restore.
- */
-export class CutoverIntegrityError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "CutoverIntegrityError";
-    }
-}
-const CUTOVER_REFMAP_FORMAT = 1;
-/**
- * Compute the old-ref → new item_ref map BEFORE any re-layout, and persist it as
- * JSON (fsynced) next to the ApplyJournal. Sources, in precedence order:
- *
- *   (a) last-good index join — `entries.entry_key` / `item_ref`, generalizing
- *       the F4c `classifyLegacyRefForRekey` origin rules to a full-table pass.
- *   (b) frozen legacy-layout walk of the configured stash roots, for on-disk
- *       refs the index no longer holds (best-effort — source (a) wins).
- */
-export function buildCutoverRefMap(opts) {
-    const map = new Map();
-    // ── Source (a): the last-good index join (authoritative). ──
-    if (fs.existsSync(opts.oldIndexDbPath)) {
-        const db = openDatabaseFinalizing(opts.oldIndexDbPath, { readonly: true });
-        try {
-            const entryColumns = tableExists(db, "main", "entries") ? new Set(columnNames(db, "main", "entries")) : undefined;
-            if (["entry_key", "item_ref", "entry_type", "stash_dir"].every((column) => entryColumns?.has(column))) {
-                const rows = db
-                    .prepare("SELECT entry_key AS entryKey, item_ref AS itemRef, entry_type AS entryType, stash_dir AS stashDir " +
-                    "FROM entries WHERE item_ref IS NOT NULL AND item_ref <> ''")
-                    .all();
-                for (const row of rows)
-                    addIndexEntryMappings(map, row, opts.stashRoots);
-            }
-        }
-        finally {
-            db.close();
-        }
-    }
-    // ── Source (b): the frozen legacy-layout walk (completeness for stale-index refs). ──
-    for (const root of opts.stashRoots ?? [])
-        walkLegacyLayoutInto(map, root);
-    persistRefMapJson(opts.mapOutputPath, map);
-    return map;
-}
-/** First-wins insertion: an old spelling that already maps to a different item_ref keeps its first target. */
-function setMapping(map, oldRef, itemRef) {
-    if (!map.has(oldRef))
-        map.set(oldRef, itemRef);
-}
-function addIndexEntryMappings(map, row, stashRoots) {
-    const bareTail = row.entryKey.includes("//") ? row.entryKey.slice(row.entryKey.indexOf("//") + 2) : row.entryKey; // `type:name`
-    const bundle = row.itemRef.includes("//") ? row.itemRef.slice(0, row.itemRef.indexOf("//")) : undefined;
-    const matched = stashRoots?.find((r) => samePath(r.path, row.stashDir));
-    // No stash-root info (or an unrecognized root) → treat as the primary source,
-    // so single-source installs (and the test fixtures) always get bare keys.
-    const isPrimary = matched ? matched.primary === true || stashRoots?.[0] === matched : true;
-    if (isPrimary) {
-        setMapping(map, bareTail, row.itemRef); // bare `type:name` resolves to the default/primary
-        setMapping(map, `stash//${bareTail}`, row.itemRef);
-        setMapping(map, `local//${bareTail}`, row.itemRef);
-    }
-    if (bundle)
-        setMapping(map, `${bundle}//${bareTail}`, row.itemRef);
-    if (matched?.registryId)
-        setMapping(map, `${matched.registryId}//${bareTail}`, row.itemRef);
-    setMapping(map, row.entryKey, row.itemRef); // the literal stored key
-}
-/**
- * Best-effort source (b): walk a configured stash root's `TYPE_DIRS` with the
- * frozen resolver and add a mapping for each on-disk asset the index map does
- * not already cover. The bundle is the source's `registryId`, or a basename slug
- * for the primary (matching how the index mints the primary bundle id).
- */
-function walkLegacyLayoutInto(map, root) {
-    let bundle;
-    if (root.registryId && root.registryId.length > 0)
-        bundle = root.registryId;
-    else if (root.primary)
-        bundle = basenameSlug(root.path);
-    else
-        return; // non-primary source with no registryId — cannot form a stable bundle here
-    for (const [type, dirName] of Object.entries(TYPE_DIRS)) {
-        const typeRoot = path.join(root.path, dirName);
-        let files;
-        try {
-            files = listFilesRecursive(typeRoot);
-        }
-        catch {
-            continue; // dir absent / unreadable
-        }
-        for (const filePath of files) {
-            const name = safeDerive(type, typeRoot, filePath);
-            if (name === undefined)
-                continue;
-            const bareTail = `${type}:${name}`;
-            if (map.has(bareTail))
-                continue; // source (a) already covers it
-            const conceptId = `${dirName}/${name}`;
-            const itemRef = `${bundle}//${conceptId}`;
-            setMapping(map, bareTail, itemRef);
-            if (root.primary) {
-                setMapping(map, `stash//${bareTail}`, itemRef);
-                setMapping(map, `local//${bareTail}`, itemRef);
-            }
-            if (root.registryId)
-                setMapping(map, `${root.registryId}//${bareTail}`, itemRef);
-        }
-    }
-}
-function safeDerive(type, typeRoot, filePath) {
-    try {
-        return deriveCanonicalAssetName(type, typeRoot, filePath);
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Basename slug matching the index's `slugForPath` primary-bundle derivation (reimplemented, not imported). */
-function basenameSlug(sourcePath) {
-    const base = path
-        .basename(path.resolve(sourcePath))
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+|-+$/g, "");
-    return base.length > 0 ? base : "bundle";
-}
-function listFilesRecursive(dir) {
-    const out = [];
-    const walk = (current) => {
-        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
-            const abs = path.join(current, entry.name);
-            if (entry.isDirectory())
-                walk(abs);
-            else if (entry.isFile())
-                out.push(abs);
-        }
-    };
-    walk(dir);
-    return out;
-}
-function samePath(a, b) {
-    if (!b)
-        return false;
-    return path.resolve(a) === path.resolve(b);
-}
-function persistRefMapJson(outputPath, map) {
-    fs.mkdirSync(path.dirname(outputPath), { recursive: true, mode: 0o700 });
-    const payload = {
-        formatVersion: CUTOVER_REFMAP_FORMAT,
-        entries: Object.fromEntries([...map.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))),
-    };
-    const tmp = `${outputPath}.tmp`;
-    const fd = fs.openSync(tmp, "w", 0o600);
-    try {
-        fs.writeFileSync(fd, `${JSON.stringify(payload, null, 2)}\n`);
-        fs.fsyncSync(fd);
-    }
-    finally {
-        fs.closeSync(fd);
-    }
-    fs.renameSync(tmp, outputPath);
-    try {
-        const dirFd = fs.openSync(path.dirname(outputPath), "r");
-        try {
-            fs.fsyncSync(dirFd);
-        }
-        finally {
-            fs.closeSync(dirFd);
-        }
-    }
-    catch {
-        // Directory fsync is unavailable on some filesystems.
-    }
-}
-/** Load the persisted cutover map when a committed migration resumes at a boundary step. */
-export function loadCutoverRefMap(inputPath) {
-    if (!fs.existsSync(inputPath)) {
-        throw new CutoverIntegrityError(`persisted cutover ref map is missing: ${inputPath}`);
-    }
-    const parsed = JSON.parse(fs.readFileSync(inputPath, "utf8"));
-    if (parsed.formatVersion !== CUTOVER_REFMAP_FORMAT ||
-        !parsed.entries ||
-        typeof parsed.entries !== "object" ||
-        Array.isArray(parsed.entries)) {
-        throw new CutoverIntegrityError(`invalid persisted cutover ref map: ${inputPath}`);
-    }
-    const map = new Map();
-    for (const [oldRef, itemRef] of Object.entries(parsed.entries)) {
-        if (!oldRef || typeof itemRef !== "string" || !itemRef) {
-            throw new CutoverIntegrityError(`invalid persisted cutover ref map entry for ${oldRef}`);
-        }
-        map.set(oldRef, itemRef);
-    }
-    return map;
-}
-const PILOT_TREATMENT_FILE = path.join(".akm", "measurement", "treatment-pilot-2026-06-14.txt");
-function fsyncPilotTreatmentDirectory(directory) {
-    let fd;
-    try {
-        fd = fs.openSync(directory, "r");
-        fs.fsyncSync(fd);
-    }
-    catch (error) {
-        const code = error.code;
-        if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EISDIR" && code !== "EPERM")
-            throw error;
-    }
-    finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
-    }
-}
-/** Re-key the one pre-0.9 pilot cohort file while the frozen old-ref map is available. */
-export function migratePilotTreatmentFiles(stashRoots, refMap) {
-    let migrated = 0;
-    const seen = new Set();
-    for (const root of stashRoots) {
-        const file = path.join(root.path, PILOT_TREATMENT_FILE);
-        const resolved = path.resolve(file);
-        if (seen.has(resolved) || !fs.existsSync(file))
-            continue;
-        seen.add(resolved);
-        const original = fs.readFileSync(file, "utf8");
-        const rewritten = original
-            .split("\n")
-            .map((line) => {
-            const trimmed = line.trim();
-            if (!trimmed || trimmed.startsWith("#"))
-                return line;
-            const target = refMap.get(trimmed);
-            if (!target)
-                return line;
-            const prefix = line.slice(0, line.indexOf(trimmed));
-            const suffix = line.slice(line.indexOf(trimmed) + trimmed.length);
-            return `${prefix}${target}${suffix}`;
-        })
-            .join("\n");
-        if (rewritten === original) {
-            fsyncPilotTreatmentDirectory(path.dirname(file));
-            continue;
-        }
-        const mode = fs.statSync(file).mode & 0o777;
-        const tmp = `${file}.tmp-${process.pid}-${crypto.randomBytes(8).toString("hex")}`;
-        let ownsTmp = false;
-        try {
-            const fd = fs.openSync(tmp, "wx", mode);
-            ownsTmp = true;
-            try {
-                fs.fchmodSync(fd, mode);
-                fs.writeFileSync(fd, rewritten);
-                fs.fsyncSync(fd);
-            }
-            finally {
-                fs.closeSync(fd);
-            }
-            fs.renameSync(tmp, file);
-            ownsTmp = false;
-            fsyncPilotTreatmentDirectory(path.dirname(file));
-        }
-        catch (error) {
-            if (ownsTmp)
-                fs.rmSync(tmp, { force: true });
-            throw error;
-        }
-        migrated += 1;
-    }
-    return migrated;
-}
-// ═══════════════════════════════════════════════════════════════════════
-// The re-key engine (per-table policy, cutover-design.md §3)
-// ═══════════════════════════════════════════════════════════════════════
-/** Scalar tables (PK = ref column) — most-recently-updated wins on collision. */
-const SCALAR_REKEY_TABLES = [
-    { table: "asset_salience", keyColumn: "asset_ref", tsColumn: "updated_at" },
-    { table: "asset_outcome", keyColumn: "asset_ref", tsColumn: "updated_at" },
-];
-/** Row-carried tables — UPDATE the ref column in place, rows preserved as-is. */
-const EVENT_REKEY_TABLES = [
-    { table: "events", keyColumn: "ref" },
-    { table: "proposals", keyColumn: "ref" },
-    { table: "task_history", keyColumn: "target_ref" },
-    { table: "proposal_fingerprints", keyColumn: "ref" },
-    { table: "canary_queries", keyColumn: "anchor_ref" },
-];
-/**
- * Classify one stored ref against the map:
- *   - in the map            → re-key to its item_ref;
- *   - already new-grammar    → skip (idempotent; already canonical);
- *   - legacy + parseable     → EXPECTED orphan (no live item) → quarantine;
- *   - legacy + unparseable   → INTEGRITY failure → fail closed.
- */
-function classifyCutoverRef(ref, refMap) {
-    const target = refMap.get(ref);
-    if (target !== undefined)
-        return { kind: "rekey", target };
-    if (classifyRefGrammar(ref) === "bundle")
-        return { kind: "skip" };
-    try {
-        parseStoredRef(ref);
-    }
-    catch {
-        return { kind: "integrity", reason: `unparseable stored ref "${ref}"` };
-    }
-    return { kind: "orphan" };
-}
-function emptyReport() {
-    return { rekeyed: {}, quarantined: {}, merged: {}, skipped: [] };
-}
-function ensureLegacyStateTable(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS legacy_state (
-      surface        TEXT NOT NULL,
-      old_ref        TEXT NOT NULL,
-      row_count      INTEGER NOT NULL DEFAULT 0,
-      reason         TEXT NOT NULL,
-      quarantined_at TEXT NOT NULL DEFAULT (datetime('now')),
-      PRIMARY KEY (surface, old_ref)
-    );
-  `);
-}
-function quarantineRow(db, surface, oldRef, count, reason) {
-    db.prepare(`INSERT INTO legacy_state (surface, old_ref, row_count, reason, quarantined_at)
-     VALUES (?, ?, ?, ?, datetime('now'))
-     ON CONFLICT(surface, old_ref) DO UPDATE SET row_count = excluded.row_count, reason = excluded.reason`).run(surface, oldRef, count, reason);
-}
-function isMissingTableOrColumn(err) {
-    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    return msg.includes("no such table") || msg.includes("no such column");
-}
-/**
- * The re-key engine over the caller's OPEN handle, INSIDE the caller's
- * transaction. Exposed via {@link rekeyStateDb} (which opens + wraps a txn) so
- * the Chunk-0b property harness can drive it directly.
- */
-export function rekeyStateDbCore(db, refMap) {
-    const report = emptyReport();
-    ensureLegacyStateTable(db);
-    for (const spec of SCALAR_REKEY_TABLES)
-        rekeyScalarTable(db, spec, refMap, report);
-    for (const spec of EVENT_REKEY_TABLES)
-        rekeyEventTable(db, spec, refMap, report);
-    return report;
-}
-/**
- * Open the state.db at `dbPath`, run the full re-key inside its own
- * transaction, and close. This is the shape the Chunk-0b `RekeyFn` harness
- * drives (`(dbPath, refMap)`); the cutover itself calls {@link rekeyStateDbCore}
- * directly inside the ATTACH transaction.
- */
-export function rekeyStateDb(dbPath, refMap) {
-    const db = openDatabaseFinalizing(dbPath);
-    try {
-        applyStandardPragmas(db, { dataDir: path.dirname(dbPath) });
-        let report = emptyReport();
-        db.transaction(() => {
-            report = rekeyStateDbCore(db, refMap);
-        })();
-        return report;
-    }
-    finally {
-        db.close();
-    }
-}
-function bump(bucket, key, by = 1) {
-    bucket[key] = (bucket[key] ?? 0) + by;
-}
-function rekeyScalarTable(db, spec, refMap, report) {
-    let rows;
-    try {
-        rows = db.prepare(`SELECT rowid AS __rowid, * FROM ${spec.table}`).all();
-    }
-    catch (err) {
-        if (isMissingTableOrColumn(err)) {
-            report.skipped.push(spec.table);
-            return;
-        }
-        throw err;
-    }
-    const groups = new Map();
-    const orphans = new Map(); // oldRef → rowids
-    for (const row of rows) {
-        const key = String(row[spec.keyColumn]);
-        const resolution = classifyCutoverRef(key, refMap);
-        if (resolution.kind === "integrity")
-            throw new CutoverIntegrityError(`${spec.table}: ${resolution.reason}`);
-        if (resolution.kind === "orphan") {
-            const list = orphans.get(key) ?? [];
-            list.push(row.__rowid);
-            orphans.set(key, list);
-            continue;
-        }
-        const target = resolution.kind === "rekey" ? resolution.target : key; // skip → itself
-        const group = groups.get(target) ?? [];
-        group.push(row);
-        groups.set(target, group);
-    }
-    // Expected orphans: audit + delete.
-    for (const [oldRef, rowids] of orphans) {
-        quarantineRow(db, spec.table, oldRef, rowids.length, "orphan");
-        for (const rowid of rowids)
-            db.prepare(`DELETE FROM ${spec.table} WHERE rowid = ?`).run(rowid);
-        bump(report.quarantined, spec.table);
-    }
-    // Groups: collapse each onto its canonical key (most-recently-updated wins).
-    for (const [target, group] of groups) {
-        if (group.length === 1 && String(group[0][spec.keyColumn]) === target)
-            continue; // already canonical, nothing maps onto it
-        const winner = group.reduce((best, candidate) => (mruWins(candidate, best, spec.tsColumn) ? candidate : best));
-        for (const row of group)
-            db.prepare(`DELETE FROM ${spec.table} WHERE rowid = ?`).run(row.__rowid);
-        reinsertRow(db, spec.table, winner, spec.keyColumn, target);
-        if (group.length > 1)
-            bump(report.merged, spec.table);
-        bump(report.rekeyed, spec.table);
-    }
-}
-/** True when `candidate` should beat `best`: larger tsColumn, ties broken by larger rowid (deterministic). */
-function mruWins(candidate, best, tsColumn) {
-    const ct = Number(candidate[tsColumn] ?? 0);
-    const bt = Number(best[tsColumn] ?? 0);
-    if (ct !== bt)
-        return ct > bt;
-    return candidate.__rowid > best.__rowid;
-}
-function reinsertRow(db, table, winner, keyColumn, target) {
-    const row = {};
-    for (const [col, value] of Object.entries(winner)) {
-        if (col === "__rowid")
-            continue;
-        row[col] = col === keyColumn ? target : value;
-    }
-    const columns = Object.keys(row);
-    const placeholders = columns.map(() => "?").join(", ");
-    db.prepare(`INSERT INTO ${table} (${columns.join(", ")}) VALUES (${placeholders})`).run(...columns.map((c) => row[c]));
-}
-function rekeyEventTable(db, spec, refMap, report) {
-    let beforeCount;
-    let refs;
-    try {
-        beforeCount = countRows(db, spec.table);
-        refs = db
-            .prepare(`SELECT DISTINCT ${spec.keyColumn} AS ref FROM ${spec.table} WHERE ${spec.keyColumn} IS NOT NULL`)
-            .all();
-    }
-    catch (err) {
-        if (isMissingTableOrColumn(err)) {
-            report.skipped.push(spec.table);
-            return;
-        }
-        throw err;
-    }
-    let orphanRowsDeleted = 0;
-    for (const { ref } of refs) {
-        const resolution = classifyCutoverRef(ref, refMap);
-        if (resolution.kind === "integrity")
-            throw new CutoverIntegrityError(`${spec.table}: ${resolution.reason}`);
-        if (resolution.kind === "skip")
-            continue;
-        if (resolution.kind === "orphan") {
-            const n = db.prepare(`SELECT COUNT(*) AS n FROM ${spec.table} WHERE ${spec.keyColumn} = ?`).get(ref).n;
-            quarantineRow(db, spec.table, ref, n, "orphan");
-            db.prepare(`DELETE FROM ${spec.table} WHERE ${spec.keyColumn} = ?`).run(ref);
-            orphanRowsDeleted += n;
-            bump(report.quarantined, spec.table);
-            continue;
-        }
-        db.prepare(`UPDATE ${spec.table} SET ${spec.keyColumn} = ? WHERE ${spec.keyColumn} = ?`).run(resolution.target, ref);
-        bump(report.rekeyed, spec.table);
-    }
-    const afterCount = countRows(db, spec.table);
-    if (afterCount !== beforeCount - orphanRowsDeleted) {
-        throw new CutoverIntegrityError(`${spec.table}: row-count mismatch after re-key (before ${beforeCount}, deleted-orphans ${orphanRowsDeleted}, after ${afterCount})`);
-    }
-}
-function countRows(db, table) {
-    return db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n;
-}
-function ensureCutoverLedger(db) {
-    db.exec(`
-    CREATE TABLE IF NOT EXISTS akm_cutover_ledger (
-      singleton    INTEGER PRIMARY KEY CHECK (singleton = 1),
-      operation_id TEXT NOT NULL,
-      merged_at    TEXT NOT NULL
-    );
-  `);
-}
-/**
- * READ-ONLY check for the committed merge marker. Must NOT create the table:
- * this runs BEFORE the cutover transaction, and a `CREATE TABLE` here would be a
- * durable pre-transaction write that a later fail-closed rollback could not undo
- * (tripping the "state changed outside the journaled transition" guard). The
- * table is created inside the transaction alongside the marker INSERT.
- */
-function cutoverAlreadyMerged(db, operationId) {
-    if (!tableExists(db, "main", "akm_cutover_ledger"))
-        return false;
-    const marker = db.prepare("SELECT operation_id FROM akm_cutover_ledger WHERE singleton = 1").get();
-    if (!marker)
-        return false;
-    if (marker.operation_id !== operationId) {
-        throw new CutoverIntegrityError(`state.db cutover marker belongs to operation ${marker.operation_id}, not ${operationId}`);
-    }
-    return true;
-}
-/**
- * Whether the state.db has already recorded the committed cutover merge marker —
- * the durable key the boundary ops (index quarantine, workflow.db unlink) and
- * the apply-flow idempotency check consult.
- */
-export function cutoverMergeCommitted(statePath, operationId) {
-    if (!fs.existsSync(statePath))
-        return false;
-    const db = openDatabaseFinalizing(statePath, { readonly: true });
-    try {
-        if (!tableExists(db, "main", "akm_cutover_ledger"))
-            return false;
-        const marker = db.prepare("SELECT operation_id FROM akm_cutover_ledger WHERE singleton = 1").get();
-        return !!marker && (operationId === undefined || marker.operation_id === operationId);
-    }
-    finally {
-        db.close();
-    }
-}
-/**
- * The full three-DB data step (cutover-design.md §2 step 3). Opens state.db,
- * ATTACHes workflow.db + the old index.db read-only OUTSIDE any transaction,
- * then in ONE `BEGIN IMMEDIATE`: INSERT…SELECTs the three workflow tables, the
- * usage_events rescue (residual legacy `entry_ref` re-keyed via the map), and
- * the old index.db `legacy_state` carry, then the FULL state re-key
- * ({@link rekeyStateDbCore}), then writes the idempotency marker, COMMITs, and
- * DETACHes. Idempotent: a committed marker short-circuits the whole run.
- *
- * Throws {@link CutoverIntegrityError} on an integrity failure (the apply flow
- * converts it into a fail-closed restore). A missing workflow.db skips the merge
- * arm (never ATTACHes it — ATTACH would CREATE the file).
- */
-export function runThreeDbCutover(opts) {
-    const copied = {};
-    const db = openDatabaseFinalizing(opts.statePath);
-    try {
-        db.exec("PRAGMA busy_timeout = 30000");
-        if (cutoverAlreadyMerged(db, opts.operationId)) {
-            return { merged: false, workflowMissing: !fs.existsSync(opts.workflowPath), copied };
-        }
-        const workflowExists = fs.existsSync(opts.workflowPath);
-        const oldIndexExists = fs.existsSync(opts.oldIndexPath);
-        assertNoStaleAttachments(db);
-        if (workflowExists)
-            db.exec(`ATTACH DATABASE '${sqliteQuote(opts.workflowPath)}' AS wf`);
-        if (oldIndexExists)
-            db.exec(`ATTACH DATABASE '${sqliteQuote(opts.oldIndexPath)}' AS oldidx`);
-        let rekey = emptyReport();
-        try {
-            db.exec("BEGIN IMMEDIATE");
-            ensureLegacyStateTable(db);
-            ensureCutoverLedger(db);
-            if (workflowExists) {
-                // Parent-first for the ON DELETE CASCADE foreign keys.
-                copied.workflow_runs = copyTable(db, "wf", "workflow_runs");
-                copied.workflow_run_steps = copyTable(db, "wf", "workflow_run_steps");
-                copied.workflow_run_units = copyTable(db, "wf", "workflow_run_units");
-                // Normative §11.4: workflow target refs are a MUST-rekey durable
-                // record. The run-key is a deterministic spelling transform
-                // (`[origin//]workflow:<n>` → `[origin//]workflows/<n>`) — no index
-                // join needed, and idempotent (already-new rows don't match).
-                db.exec(`UPDATE workflow_runs SET workflow_ref =
-             CASE
-               WHEN workflow_ref LIKE 'workflow:%'
-                 THEN 'workflows/' || substr(workflow_ref, length('workflow:') + 1)
-               WHEN instr(workflow_ref, '//workflow:') > 0
-                 THEN substr(workflow_ref, 1, instr(workflow_ref, '//workflow:') + 1)
-                      || 'workflows/'
-                      || substr(workflow_ref, instr(workflow_ref, '//workflow:') + length('//workflow:'))
-               ELSE workflow_ref
-             END
-           WHERE workflow_ref LIKE 'workflow:%' OR instr(workflow_ref, '//workflow:') > 0`);
-            }
-            if (oldIndexExists) {
-                copied.usage_events = rescueUsageEvents(db, opts.refMap);
-                carryLegacyState(db, "oldidx");
-            }
-            rekey = rekeyStateDbCore(db, opts.refMap);
-            db.prepare("INSERT INTO akm_cutover_ledger (singleton, operation_id, merged_at) VALUES (1, ?, datetime('now'))").run(opts.operationId);
-            db.exec("COMMIT");
-        }
-        catch (error) {
-            if (db.inTransaction) {
-                try {
-                    db.exec("ROLLBACK");
-                }
-                catch {
-                    // Preserve the original error.
-                }
-            }
-            throw error;
-        }
-        finally {
-            // DETACH must happen OUTSIDE any transaction (an in-txn DETACH fails).
-            if (oldIndexExists)
-                safeDetach(db, "oldidx");
-            if (workflowExists)
-                safeDetach(db, "wf");
-        }
-        // Flush the WAL into the main file and truncate the sidecar to 0 bytes: the
-        // migration generation fingerprint tracks state.db + its `-wal`/`-shm`
-        // sidecars, and an uncheckpointed WAL is moved into the main file by the next
-        // read-only inspect/resume open, desyncing the fingerprint and tripping the
-        // "does not match the exact live artifact generation" guard. No-op when the
-        // DB is not in WAL mode. The journal mode is left UNCHANGED (converting it
-        // can lock a contended WAL db).
-        try {
-            db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
-        }
-        catch {
-            // Not in WAL mode / nothing to checkpoint.
-        }
-        return { merged: true, workflowMissing: !workflowExists, copied, rekey };
-    }
-    finally {
-        db.close();
-    }
-}
-function assertNoStaleAttachments(db) {
-    const attached = db.prepare("PRAGMA database_list").all().map((r) => r.name);
-    const stale = attached.filter((name) => name === "wf" || name === "oldidx");
-    if (stale.length > 0) {
-        for (const name of stale)
-            safeDetach(db, name);
-    }
-}
-function safeDetach(db, schema) {
-    try {
-        db.exec(`DETACH DATABASE ${schema}`);
-    }
-    catch {
-        // Already detached / never attached.
-    }
-}
-/** Copy the INTERSECTION of columns from an attached-schema table into the matching `main` table. */
-function copyTable(db, srcSchema, table) {
-    if (!tableExists(db, srcSchema, table))
-        return 0;
-    const srcCols = new Set(columnNames(db, srcSchema, table));
-    const common = columnNames(db, "main", table).filter((c) => srcCols.has(c));
-    if (common.length === 0)
-        return 0;
-    const colList = common.join(", ");
-    db.exec(`INSERT INTO main.${table} (${colList}) SELECT ${colList} FROM ${srcSchema}.${table}`);
-    return countRows(db, table);
-}
-/**
- * Rescue the durable index.db `usage_events` history into state.db. Copies the
- * column intersection (fresh AUTOINCREMENT ids are fine — `entry_id` is an
- * index-generation-scoped provenance column the relink pass re-derives), then
- * re-keys residual legacy `entry_ref`s via the map. Rows already in
- * `bundle//conceptId` grammar are carried as-is; unmapped legacy rows are KEPT
- * in place (append-only history) and recorded in `legacy_state`.
- */
-function rescueUsageEvents(db, refMap) {
-    if (!tableExists(db, "oldidx", "usage_events"))
-        return 0;
-    const srcCols = new Set(columnNames(db, "oldidx", "usage_events"));
-    // Never carry the source rowid/id — let state.db mint fresh AUTOINCREMENT ids.
-    const common = columnNames(db, "main", "usage_events").filter((c) => c !== "id" && srcCols.has(c));
-    if (common.length > 0) {
-        const targetColumns = [...common];
-        const selectColumns = [...common];
-        // Rows from the pre-provenance schema are historical but not necessarily
-        // interactive. Preserve them as unattributed rather than manufacturing
-        // user demand through state.db's legacy column default.
-        if (!srcCols.has("source")) {
-            targetColumns.push("source");
-            selectColumns.push("'unknown'");
-        }
-        db.exec(`INSERT INTO main.usage_events (${targetColumns.join(", ")}) ` +
-            `SELECT ${selectColumns.join(", ")} FROM oldidx.usage_events`);
-    }
-    if (!columnNames(db, "main", "usage_events").includes("entry_ref"))
-        return countRows(db, "usage_events");
-    const legacyRefs = db.prepare("SELECT DISTINCT entry_ref AS ref FROM main.usage_events WHERE entry_ref IS NOT NULL").all()
-        .map((r) => r.ref)
-        .filter((ref) => classifyRefGrammar(ref) === "legacy");
-    for (const oldRef of legacyRefs) {
-        const target = refMap.get(oldRef);
-        if (target !== undefined) {
-            db.prepare("UPDATE main.usage_events SET entry_ref = ? WHERE entry_ref = ?").run(target, oldRef);
-        }
-        else {
-            // Expected orphan — KEEP the append-only rows in place, archive for audit.
-            const n = db.prepare("SELECT COUNT(*) AS n FROM main.usage_events WHERE entry_ref = ?").get(oldRef).n;
-            quarantineRow(db, "usage_events", oldRef, n, "orphan");
-        }
-    }
-    return countRows(db, "usage_events");
-}
-/** Carry the old index.db `legacy_state` quarantine rows into state.db (durable re-home). */
-function carryLegacyState(db, srcSchema) {
-    if (!tableExists(db, srcSchema, "legacy_state"))
-        return;
-    const srcCols = new Set(columnNames(db, srcSchema, "legacy_state"));
-    const common = ["surface", "old_ref", "row_count", "reason", "quarantined_at"].filter((c) => srcCols.has(c));
-    if (!common.includes("surface") || !common.includes("old_ref"))
-        return;
-    const colList = common.join(", ");
-    db.exec(`INSERT OR IGNORE INTO main.legacy_state (${colList}) SELECT ${colList} FROM ${srcSchema}.legacy_state`);
-}
-// ═══════════════════════════════════════════════════════════════════════
-// Index/workflow boundary steps (AFTER the committed state txn)
-// ═══════════════════════════════════════════════════════════════════════
-const DB_SIDECARS = ["-wal", "-shm"];
-/**
- * Journaled rename of the old index.db (+ `-wal`/`-shm`) to
- * `index.db.pre-cutover-<runId>`. Runs AFTER the state txn commits, OUTSIDE the
- * fail-closed gate — the next index run rebuilds from scratch (a rebuild failure
- * never rolls back the committed cutover). Idempotent + best-effort: a failure
- * is logged, never thrown.
- */
-export function quarantineIndexDb(runId, indexPath) {
-    try {
-        const target = `${indexPath}.pre-cutover-${runId}`;
-        const sourceMainExists = fs.existsSync(indexPath);
-        const targetMainExists = fs.existsSync(target);
-        if (sourceMainExists && targetMainExists)
-            return { quarantined: true, target };
-        if (!sourceMainExists && !targetMainExists)
-            return { quarantined: false };
-        const remainingSidecars = DB_SIDECARS.filter((suffix) => fs.existsSync(`${indexPath}${suffix}`));
-        if (remainingSidecars.some((suffix) => fs.existsSync(`${target}${suffix}`))) {
-            warn("[akm] three-DB cutover: index.db quarantine sidecar collision; canonical sidecars were preserved.");
-            return { quarantined: targetMainExists, ...(targetMainExists ? { target } : {}) };
-        }
-        if (sourceMainExists)
-            fs.renameSync(indexPath, target);
-        for (const suffix of remainingSidecars)
-            fs.renameSync(`${indexPath}${suffix}`, `${target}${suffix}`);
-        return { quarantined: true, target };
-    }
-    catch (error) {
-        warn(`[akm] three-DB cutover: index.db quarantine rename failed (${error instanceof Error ? error.message : String(error)}); the next \`akm index\` rebuilds it — the committed state cutover is unaffected.`);
-        return { quarantined: false };
-    }
-}
-/**
- * Journaled, idempotent unlink of workflow.db + its `-wal`/`-shm` sidecars, keyed
- * on the committed cutover marker (the caller passes it only once the merge has
- * committed). Best-effort: a failure is logged, never thrown.
- */
-export function deleteWorkflowDb(workflowPath) {
-    let deleted = false;
-    try {
-        for (const suffix of ["-shm", "-wal", ""]) {
-            const target = `${workflowPath}${suffix}`;
-            if (fs.existsSync(target)) {
-                fs.rmSync(target, { force: true });
-                if (suffix === "")
-                    deleted = true;
-            }
-        }
-    }
-    catch (error) {
-        warn(`[akm] three-DB cutover: workflow.db unlink failed (${error instanceof Error ? error.message : String(error)}); it is retried on the next migrate apply.`);
-    }
-    return { deleted };
-}
-// ═══════════════════════════════════════════════════════════════════════
-// Small SQL helpers
-// ═══════════════════════════════════════════════════════════════════════
-function tableExists(db, schema, table) {
-    return !!db.prepare(`SELECT 1 FROM ${schema}.sqlite_master WHERE type = 'table' AND name = ?`).get(table);
-}
-function columnNames(db, schema, table) {
-    return db.prepare(`PRAGMA ${schema}.table_info(${table})`).all().map((r) => r.name);
-}
-/** Escape single quotes for an inline SQLite string literal (paths only — never user ref data). */
-function sqliteQuote(value) {
-    return value.replace(/'/g, "''");
-}