@cleocode/core 2026.9.26 → 2026.10.2

package/dist/store/migration-runner.d.ts

@@ -0,0 +1,158 @@
+/**
+ * The bracketed migration runner (journal spec §2.3a rules 1–3; T12774,
+ * T12781, T12785, T12786, T12795, T12796, T12797, T12809).
+ *
+ * Drizzle's `migrateSync` runs every pending migration in ONE transaction of
+ * its own, with `PRAGMA foreign_keys` left ON (the PRAGMA is a no-op inside a
+ * transaction). A table rebuild's `DROP TABLE` therefore cascade-deletes
+ * child rows, and nothing can run inside its transaction. This runner keeps
+ * drizzle's journal byte-for-byte and replaces the transaction discipline:
+ *
+ * - **Journal-identical (R5-3).** Pending migrations are selected by NAME
+ *   (drizzle's `getMigrationsToRun`), each row is written with the RAW file's
+ *   sha256, `created_at = folderMillis`, `name` and `applied_at`, exactly as
+ *   `migrateSync` writes it. `reconcileJournal` and drizzle's own
+ *   `upgradeSyncIfNeeded` run inside the leading bracket, in today's order.
+ *   Statements run one per `prepare()`, as drizzle's session does.
+ * - **One bracket per migration FILE (R6-6).** Each file gets its own
+ *   `BEGIN IMMEDIATE … COMMIT` and its own journal row.
+ * - **FK discipline (A, NEW-1, R5-2, R5-4, NEW-6).** `foreign_keys` is turned
+ *   OFF before `BEGIN` only for a file that rebuilds a table. For such a file
+ *   the runner snapshots the FK violations of its scope (rebuilt and
+ *   DML-touched tables plus their FK children) as a rowid-free multiset,
+ *   re-checks after the statements, and rolls back on any NEW violation.
+ *   Pre-existing orphans never block a migration. `finally` restores
+ *   `foreign_keys`, reads it back and asserts no transaction is open.
+ * - **Recovery kept.** A duplicate-column or table-exists error re-runs
+ *   `reconcileJournal` once and retries, as `migrateWithRetry` does; a BUSY
+ *   error retries the whole bracket with backoff, never mid-bracket.
+ * - **Hooks (D4, NEW-8).** `beforeMigrations` runs before the first bracket
+ *   (the sealer's pending work and the repair diff for suspect tables, S3);
+ *   `suspendCapture` / `reinstallCapture` run inside each bracket around the
+ *   statements (the capture triggers, S2); `afterMigration` runs after each
+ *   commit (the `chash` re-baseline, S3). All are optional.
+ *
+ * Drizzle is pinned to {@link PINNED_DRIZZLE_VERSION}; a test fails when the
+ * installed version differs, so an upgrade must re-run the parity suite.
+ *
+ * @task T12796
+ * @task T12809
+ * @module store/migration-runner
+ */
+import type { DatabaseSync } from 'node:sqlite';
+import type { NodeSQLiteDatabase } from 'drizzle-orm/node-sqlite';
+/** The drizzle-orm version the runner's journal parity was proven against. */
+export declare const PINNED_DRIZZLE_VERSION = "1.0.0-rc.4";
+/** The journal table drizzle uses by default. */
+export declare const MIGRATIONS_TABLE = "__drizzle_migrations";
+/** Optional work around the brackets (D4 ordering). */
+export interface MigrationBracketHooks {
+    /** Before the first bracket: seal pending captures, repair suspect tables (S3). */
+    beforeMigrations?(db: DatabaseSync): void;
+    /** Inside each bracket, before the statements: drop the capture triggers (S2). */
+    suspendCapture?(db: DatabaseSync): void;
+    /** Inside each bracket, after the statements: reinstall the capture triggers (S2). */
+    reinstallCapture?(db: DatabaseSync): void;
+    /** After each committed bracket: re-baseline `chash` for the file's tables (S3). */
+    afterMigration?(db: DatabaseSync, migration: {
+        name: string;
+        hash: string;
+    }): void;
+}
+/** One migration lineage sharing the store's journal. */
+export interface MigrationLineage {
+    readonly folder: string;
+    /** Run `reconcileJournal` for this lineage first (as the callers do today). */
+    readonly reconcile?: {
+        readonly existenceTable: string;
+        readonly logSubsystem: string;
+        readonly siblings?: readonly string[];
+    };
+}
+/**
+ * Legacy lineages the runner refuses by folder name (cleo-dev ruling on the
+ * S2 runner scope, 2026-09-30). They keep `migrateWithRetry` in their own
+ * binders (`sqlite.ts`, `memory-sqlite.ts`, `nexus-sqlite.ts`,
+ * `conduit-sqlite.ts`, …); only the consolidated `cleo.db` lineages run
+ * bracketed.
+ */
+export declare const LEGACY_LINEAGES: ReadonlySet<string>;
+/** A legacy lineage was handed to the runner. */
+export declare class LegacyLineageRefusedError extends Error {
+    readonly lineage: string;
+    readonly code = "E_MIGRATION_RUNNER_LEGACY_LINEAGE";
+    constructor(lineage: string);
+}
+/** What {@link runBracketedMigrations} did. */
+export interface MigrationRunReport {
+    /** Names of the migrations applied, in order. */
+    readonly applied: string[];
+    /** Names of the files that ran with `foreign_keys = OFF` (rebuilds). */
+    readonly rebuilds: string[];
+}
+/** A migration file that introduced a foreign-key violation (rolled back). */
+export declare class MigrationForeignKeyError extends Error {
+    readonly migration: string;
+    readonly violations: readonly string[];
+    readonly code = "E_MIGRATION_FK_VIOLATION";
+    constructor(migration: string, violations: readonly string[]);
+}
+/** `foreign_keys` could not be restored on a handle after a bracket. */
+export declare class ForeignKeysNotRestoredError extends Error {
+    readonly code = "E_STORE_FK_OFF";
+    constructor(expected: number, actual: number);
+}
+/**
+ * The tables a migration file rebuilds or drops: `CREATE TABLE __new_x`
+ * (→ `x`), `DROP TABLE x`, `ALTER TABLE x RENAME TO y` (→ `x`, `y`).
+ * Empty for a file that rebuilds nothing.
+ */
+export declare function rebuiltTables(statements: readonly string[]): string[];
+/**
+ * Where each table a migration file renames ends up: every `ALTER TABLE a RENAME TO b`, in statement
+ * order and composed, so `a → b` then `b → c` gives `a → c` (T13027). Unrenamed tables are absent.
+ */
+export declare function renamedTables(statements: readonly string[]): Map<string, string>;
+/** The tables a migration's DML writes (INSERT / UPDATE / DELETE / REPLACE). */
+export declare function dmlTables(statements: readonly string[]): string[];
+/**
+ * The FK scope of a rebuild file: the given tables plus every table with a
+ * foreign key to one of them (children), restricted to tables that exist.
+ */
+export declare function foreignKeyScope(db: DatabaseSync, tables: readonly string[]): string[];
+/**
+ * The foreign-key violations of `tables`, as a multiset keyed by rowid-free
+ * identity (R5-2): (table, the child's primary-key values normalized by
+ * column affinity — or the whole row for a table without a declared PK,
+ * parent table, the child's FK values). Duplicates count.
+ *
+ * FK column NAMES are not part of the key: a rebuild may rename an FK column
+ * while the violation stays the same row and value (T13027). Two orphaned
+ * FKs of one row with equal values are still counted twice.
+ */
+export declare function foreignKeyViolations(db: DatabaseSync, tables: readonly string[]): Map<string, number>;
+/**
+ * A before-snapshot re-keyed to the names its tables have after a file's
+ * renames (T13027): child and parent tables move through `renames` when the
+ * new name exists afterwards. A table renamed away and dropped (`x → __old_x`
+ * in a rebuild) keeps its name, since its rows now live under the old name.
+ */
+export declare function renameViolations(before: Map<string, number>, renames: ReadonlyMap<string, string>, exists: (table: string) => boolean): Map<string, number>;
+/** Keys whose count in `after` exceeds their count in `before`. */
+export declare function newViolations(before: Map<string, number>, after: Map<string, number>): string[];
+/**
+ * Apply every pending migration of each lineage, in order, with the journal
+ * `migrateSync` would leave, one bracket per file.
+ *
+ * @param nativeDb - The store handle.
+ * @param db - The drizzle wrapper of `nativeDb` (for drizzle's journal upgrade).
+ * @param lineages - The lineages sharing the journal, in apply order.
+ * @param hooks - Optional D4 hooks.
+ */
+export declare function runBracketedMigrations(nativeDb: DatabaseSync, db: NodeSQLiteDatabase<any>, lineages: readonly MigrationLineage[], hooks?: MigrationBracketHooks): MigrationRunReport;
+/**
+ * Same as {@link runBracketedMigrations} for one lineage, in the shape the
+ * callers of `reconcileJournal` + `migrateWithRetry` use today.
+ */
+export declare function migrateBracketed(db: NodeSQLiteDatabase<any>, nativeDb: DatabaseSync, migrationsFolder: string, existenceTable: string, logSubsystem: string, siblings?: readonly string[], hooks?: MigrationBracketHooks): MigrationRunReport;
+//# sourceMappingURL=migration-runner.d.ts.map

package/dist/store/migration-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migration-runner.d.ts","sourceRoot":"","sources":["../../src/store/migration-runner.ts"],"names":[],"mappings":"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"}

package/dist/store/migration-runner.js

@@ -0,0 +1,493 @@
+/**
+ * The bracketed migration runner (journal spec §2.3a rules 1–3; T12774,
+ * T12781, T12785, T12786, T12795, T12796, T12797, T12809).
+ *
+ * Drizzle's `migrateSync` runs every pending migration in ONE transaction of
+ * its own, with `PRAGMA foreign_keys` left ON (the PRAGMA is a no-op inside a
+ * transaction). A table rebuild's `DROP TABLE` therefore cascade-deletes
+ * child rows, and nothing can run inside its transaction. This runner keeps
+ * drizzle's journal byte-for-byte and replaces the transaction discipline:
+ *
+ * - **Journal-identical (R5-3).** Pending migrations are selected by NAME
+ *   (drizzle's `getMigrationsToRun`), each row is written with the RAW file's
+ *   sha256, `created_at = folderMillis`, `name` and `applied_at`, exactly as
+ *   `migrateSync` writes it. `reconcileJournal` and drizzle's own
+ *   `upgradeSyncIfNeeded` run inside the leading bracket, in today's order.
+ *   Statements run one per `prepare()`, as drizzle's session does.
+ * - **One bracket per migration FILE (R6-6).** Each file gets its own
+ *   `BEGIN IMMEDIATE … COMMIT` and its own journal row.
+ * - **FK discipline (A, NEW-1, R5-2, R5-4, NEW-6).** `foreign_keys` is turned
+ *   OFF before `BEGIN` only for a file that rebuilds a table. For such a file
+ *   the runner snapshots the FK violations of its scope (rebuilt and
+ *   DML-touched tables plus their FK children) as a rowid-free multiset,
+ *   re-checks after the statements, and rolls back on any NEW violation.
+ *   Pre-existing orphans never block a migration. `finally` restores
+ *   `foreign_keys`, reads it back and asserts no transaction is open.
+ * - **Recovery kept.** A duplicate-column or table-exists error re-runs
+ *   `reconcileJournal` once and retries, as `migrateWithRetry` does; a BUSY
+ *   error retries the whole bracket with backoff, never mid-bracket.
+ * - **Hooks (D4, NEW-8).** `beforeMigrations` runs before the first bracket
+ *   (the sealer's pending work and the repair diff for suspect tables, S3);
+ *   `suspendCapture` / `reinstallCapture` run inside each bracket around the
+ *   statements (the capture triggers, S2); `afterMigration` runs after each
+ *   commit (the `chash` re-baseline, S3). All are optional.
+ *
+ * Drizzle is pinned to {@link PINNED_DRIZZLE_VERSION}; a test fails when the
+ * installed version differs, so an upgrade must re-run the parity suite.
+ *
+ * @task T12796
+ * @task T12809
+ * @module store/migration-runner
+ */
+import { basename } from 'node:path';
+import { readMigrationFiles } from 'drizzle-orm/migrator';
+import { getMigrationsToRun } from 'drizzle-orm/migrator.utils';
+import { sql } from 'drizzle-orm/sql';
+import { upgradeSyncIfNeeded } from 'drizzle-orm/up-migrations/sqlite';
+import { getLogger } from '../logger.js';
+import { isDuplicateColumnError, isTableAlreadyExistsError, reconcileJournal, sanitizeMigrationStatements, } from './migration-manager.js';
+import { isSqliteBusy } from './with-retry.js';
+import { assertNoPendingMigrationsForWorktreeBuild } from './worktree-build-guard.js';
+/** The drizzle-orm version the runner's journal parity was proven against. */
+export const PINNED_DRIZZLE_VERSION = '1.0.0-rc.4';
+/** The journal table drizzle uses by default. */
+export const MIGRATIONS_TABLE = '__drizzle_migrations';
+const MAX_BUSY_RETRIES = 5;
+const BUSY_BASE_DELAY_MS = 100;
+const BUSY_MAX_DELAY_MS = 2000;
+/**
+ * Legacy lineages the runner refuses by folder name (cleo-dev ruling on the
+ * S2 runner scope, 2026-09-30). They keep `migrateWithRetry` in their own
+ * binders (`sqlite.ts`, `memory-sqlite.ts`, `nexus-sqlite.ts`,
+ * `conduit-sqlite.ts`, …); only the consolidated `cleo.db` lineages run
+ * bracketed.
+ */
+export const LEGACY_LINEAGES = new Set([
+    'drizzle-tasks',
+    'drizzle-brain',
+    'drizzle-nexus',
+    'drizzle-conduit',
+    'drizzle-agent-registry',
+    'drizzle-skills',
+    'drizzle-telemetry',
+    'drizzle-signaldock',
+]);
+/** A legacy lineage was handed to the runner. */
+export class LegacyLineageRefusedError extends Error {
+    lineage;
+    code = 'E_MIGRATION_RUNNER_LEGACY_LINEAGE';
+    constructor(lineage) {
+        super(`The bracketed migration runner runs only the consolidated cleo.db lineages; refusing legacy lineage ${lineage}`);
+        this.lineage = lineage;
+        this.name = 'LegacyLineageRefusedError';
+    }
+}
+/** A migration file that introduced a foreign-key violation (rolled back). */
+export class MigrationForeignKeyError extends Error {
+    migration;
+    violations;
+    code = 'E_MIGRATION_FK_VIOLATION';
+    constructor(migration, violations) {
+        super(`Migration ${migration} would leave ${violations.length} new foreign-key violation(s); ` +
+            `rolled back. First: ${violations.slice(0, 3).join('; ')}`);
+        this.migration = migration;
+        this.violations = violations;
+        this.name = 'MigrationForeignKeyError';
+    }
+}
+/** `foreign_keys` could not be restored on a handle after a bracket. */
+export class ForeignKeysNotRestoredError extends Error {
+    code = 'E_STORE_FK_OFF';
+    constructor(expected, actual) {
+        super(`PRAGMA foreign_keys is ${actual} after a migration bracket; expected ${expected}`);
+        this.name = 'ForeignKeysNotRestoredError';
+    }
+}
+const IDENT = String.raw `[\`"[]?(\w+)[\`"\]]?`;
+/** Strip `--` comments so prose never looks like DDL. */
+function code(stmt) {
+    return stmt.replace(/--[^\n]*/g, '');
+}
+/**
+ * The tables a migration file rebuilds or drops: `CREATE TABLE __new_x`
+ * (→ `x`), `DROP TABLE x`, `ALTER TABLE x RENAME TO y` (→ `x`, `y`).
+ * Empty for a file that rebuilds nothing.
+ */
+export function rebuiltTables(statements) {
+    const out = new Set();
+    const final = (t) => t.replace(/^__new_/, '');
+    for (const s of statements.map(code)) {
+        for (const m of s.matchAll(new RegExp(String.raw `\bCREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?${IDENT}`, 'gi'))) {
+            if (m[1].startsWith('__new_'))
+                out.add(final(m[1]));
+        }
+        for (const m of s.matchAll(new RegExp(String.raw `\bDROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?${IDENT}`, 'gi'))) {
+            out.add(final(m[1]));
+        }
+        for (const m of s.matchAll(new RegExp(String.raw `\bALTER\s+TABLE\s+${IDENT}\s+RENAME\s+TO\s+${IDENT}`, 'gi'))) {
+            out.add(final(m[1]));
+            out.add(final(m[2]));
+        }
+    }
+    return [...out].sort();
+}
+/**
+ * Where each table a migration file renames ends up: every `ALTER TABLE a RENAME TO b`, in statement
+ * order and composed, so `a → b` then `b → c` gives `a → c` (T13027). Unrenamed tables are absent.
+ */
+export function renamedTables(statements) {
+    const out = new Map();
+    // Anchored: only a statement that IS the rename counts, never text inside a
+    // string literal or another statement's body.
+    const rename = new RegExp(String.raw `^\s*ALTER\s+TABLE\s+${IDENT}\s+RENAME\s+TO\s+${IDENT}\s*;?\s*$`, 'i');
+    for (const s of statements.map(code)) {
+        const m = rename.exec(s);
+        if (!m)
+            continue;
+        const from = m[1];
+        const to = m[2];
+        const original = [...out.entries()].find(([, now]) => now === from)?.[0] ?? from;
+        out.set(original, to);
+    }
+    return out;
+}
+/** The tables a migration's DML writes (INSERT / UPDATE / DELETE / REPLACE). */
+export function dmlTables(statements) {
+    const out = new Set();
+    for (const s of statements.map(code)) {
+        for (const m of s.matchAll(new RegExp(String.raw `\b(?:INSERT(?:\s+OR\s+\w+)?\s+INTO|REPLACE\s+INTO|UPDATE(?:\s+OR\s+\w+)?|DELETE\s+FROM)\s+${IDENT}`, 'gi'))) {
+            out.add(m[1].replace(/^__new_/, ''));
+        }
+    }
+    return [...out].sort();
+}
+function listTables(db) {
+    return db
+        .prepare("SELECT name FROM main.sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name")
+        .all().map((r) => r.name);
+}
+function foreignKeys(db, table) {
+    return db.prepare(`PRAGMA main.foreign_key_list("${table}")`).all();
+}
+/**
+ * The FK scope of a rebuild file: the given tables plus every table with a
+ * foreign key to one of them (children), restricted to tables that exist.
+ */
+export function foreignKeyScope(db, tables) {
+    const all = listTables(db);
+    const existing = new Set(all);
+    const scope = new Set(tables.filter((t) => existing.has(t)));
+    const parents = new Set(tables);
+    for (const t of all) {
+        if (foreignKeys(db, t).some((fk) => parents.has(fk.table)))
+            scope.add(t);
+    }
+    return [...scope].sort();
+}
+/** SQLite's affinity for a declared column type (§3.1 of the datatype doc). */
+function affinity(declared) {
+    const t = declared.toUpperCase();
+    if (t.includes('INT'))
+        return 'INTEGER';
+    if (/CHAR|CLOB|TEXT/.test(t))
+        return 'TEXT';
+    if (t === '' || t.includes('BLOB'))
+        return 'BLOB';
+    if (/REAL|FLOA|DOUB/.test(t))
+        return 'REAL';
+    return 'NUMERIC';
+}
+/**
+ * The foreign-key violations of `tables`, as a multiset keyed by rowid-free
+ * identity (R5-2): (table, the child's primary-key values normalized by
+ * column affinity — or the whole row for a table without a declared PK,
+ * parent table, the child's FK values). Duplicates count.
+ *
+ * FK column NAMES are not part of the key: a rebuild may rename an FK column
+ * while the violation stays the same row and value (T13027). Two orphaned
+ * FKs of one row with equal values are still counted twice.
+ */
+export function foreignKeyViolations(db, tables) {
+    const out = new Map();
+    for (const table of tables) {
+        const rows = db.prepare(`PRAGMA main.foreign_key_check("${table}")`).all();
+        if (rows.length === 0)
+            continue;
+        const cols = db.prepare(`PRAGMA main.table_info("${table}")`).all();
+        const pkCols = cols.filter((c) => c.pk > 0).sort((a, b) => a.pk - b.pk);
+        const keyCols = pkCols.length > 0 ? pkCols : cols;
+        const fks = foreignKeys(db, table);
+        const seenNoRowid = new Set();
+        const enc = (c, alias) => {
+            const a = affinity(c.type);
+            const ref = `${alias}"${c.name}"`;
+            return a === 'BLOB' ? `quote(${ref})` : `quote(CAST(${ref} AS ${a}))`;
+        };
+        const keySql = (alias) => `json_array(${keyCols.map((c) => enc(c, alias)).join(', ')})`;
+        for (const v of rows) {
+            const fkCols = fks.filter((f) => f.id === v.fkid).sort((a, b) => a.seq - b.seq);
+            const fkSql = (alias) => `json_array(${fkCols.map((f) => `quote(${alias}"${f.from}")`).join(', ')})`;
+            let identities;
+            if (v.rowid !== null && v.rowid !== undefined) {
+                identities = db
+                    .prepare(`SELECT ${keySql('')} AS k, ${fkSql('')} AS f FROM main."${table}" WHERE rowid = ?`)
+                    .all(v.rowid);
+            }
+            else {
+                // WITHOUT ROWID: no rowid to point at; list this FK's violating rows.
+                const parentPk = db.prepare(`PRAGMA main.table_info("${v.parent}")`).all()
+                    .filter((c) => c.pk > 0)
+                    .sort((a, b) => a.pk - b.pk)
+                    .map((c) => c.name);
+                const match = fkCols
+                    .map((f, i) => `p."${f.to ?? parentPk[i] ?? f.from}" = c."${f.from}"`)
+                    .join(' AND ');
+                identities = db
+                    .prepare(`SELECT ${keySql('c.')} AS k, ${fkSql('c.')} AS f FROM main."${table}" c ` +
+                    `WHERE ${fkCols.map((f) => `c."${f.from}" IS NOT NULL`).join(' AND ')} ` +
+                    `AND NOT EXISTS (SELECT 1 FROM main."${v.parent}" p WHERE ${match})`)
+                    .all();
+                // foreign_key_check lists one row per violation; this query lists them
+                // all at once, so take it for the first report of this FK only.
+                if (seenNoRowid.has(v.fkid))
+                    identities = [];
+                seenNoRowid.add(v.fkid);
+            }
+            for (const id of identities) {
+                const key = JSON.stringify([table, id.k, v.parent, id.f]);
+                out.set(key, (out.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * A before-snapshot re-keyed to the names its tables have after a file's
+ * renames (T13027): child and parent tables move through `renames` when the
+ * new name exists afterwards. A table renamed away and dropped (`x → __old_x`
+ * in a rebuild) keeps its name, since its rows now live under the old name.
+ */
+export function renameViolations(before, renames, exists) {
+    if (renames.size === 0)
+        return before;
+    const to = (t) => {
+        const r = renames.get(t);
+        return r !== undefined && exists(r) ? r : t;
+    };
+    const out = new Map();
+    for (const [k, n] of before) {
+        const [table, pk, parent, values] = JSON.parse(k);
+        const key = JSON.stringify([to(table), pk, to(parent), values]);
+        out.set(key, (out.get(key) ?? 0) + n);
+    }
+    return out;
+}
+/** Keys whose count in `after` exceeds their count in `before`. */
+export function newViolations(before, after) {
+    const out = [];
+    for (const [k, n] of after) {
+        const extra = n - (before.get(k) ?? 0);
+        for (let i = 0; i < extra; i++)
+            out.push(k);
+    }
+    return out;
+}
+function sleepMs(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.round(ms));
+}
+/** Run `fn`, retrying the whole thing on SQLITE_BUSY with backoff. */
+function withBusyRetry(fn) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return fn();
+        }
+        catch (err) {
+            if (!isSqliteBusy(err) || attempt >= MAX_BUSY_RETRIES)
+                throw err;
+            sleepMs(Math.min(BUSY_BASE_DELAY_MS * 2 ** (attempt - 1) * (1 + Math.random() * 0.5), BUSY_MAX_DELAY_MS));
+        }
+    }
+}
+function readForeignKeys(db) {
+    return Number(db.prepare('PRAGMA foreign_keys').get().foreign_keys);
+}
+/**
+ * The leading bracket of a lineage: reconcile (when configured), then
+ * drizzle's journal-format upgrade, then create the journal table on a new
+ * store. Returns the names already journaled.
+ */
+function leadingBracket(nativeDb, 
+// biome-ignore lint/suspicious/noExplicitAny: drizzle's session type is generic over the schema
+db, lineage, migrations) {
+    withBusyRetry(() => {
+        nativeDb.exec('BEGIN IMMEDIATE');
+        try {
+            if (lineage.reconcile) {
+                reconcileJournal(nativeDb, lineage.folder, lineage.reconcile.existenceTable, lineage.reconcile.logSubsystem, lineage.reconcile.siblings ?? []);
+            }
+            // Drizzle's own upgrade, with its inner transaction folded into ours.
+            const session = db._.session;
+            const inBracket = new Proxy(session, {
+                get(target, prop, receiver) {
+                    if (prop === 'transaction')
+                        return (fn) => fn(receiver);
+                    return Reflect.get(target, prop, receiver);
+                },
+            });
+            const { newDb } = upgradeSyncIfNeeded(MIGRATIONS_TABLE, inBracket, migrations);
+            if (newDb) {
+                session.run(sql `
+			CREATE TABLE IF NOT EXISTS ${sql.identifier(MIGRATIONS_TABLE)} (
+				id INTEGER PRIMARY KEY,
+				hash text NOT NULL,
+				created_at numeric,
+				name text,
+				applied_at TEXT
+			)`);
+            }
+            nativeDb.exec('COMMIT');
+        }
+        catch (err) {
+            if (nativeDb.isTransaction)
+                nativeDb.exec('ROLLBACK');
+            throw err;
+        }
+    });
+}
+function journalRows(nativeDb) {
+    return nativeDb
+        .prepare(`SELECT id, hash, created_at, name FROM main."${MIGRATIONS_TABLE}"`)
+        .all();
+}
+/**
+ * Apply one migration file in its own bracket. Returns whether it ran with
+ * foreign keys off.
+ */
+function migrationBracket(nativeDb, migration, hooks) {
+    const statements = migration.sql;
+    const rebuilt = rebuiltTables(statements);
+    const rebuild = rebuilt.length > 0;
+    const prev = readForeignKeys(nativeDb);
+    let failure;
+    let committed = false;
+    try {
+        if (rebuild)
+            nativeDb.exec('PRAGMA foreign_keys = OFF');
+        nativeDb.exec('BEGIN IMMEDIATE');
+        const scopeTables = [...rebuilt, ...dmlTables(statements)];
+        const before = rebuild
+            ? foreignKeyViolations(nativeDb, foreignKeyScope(nativeDb, scopeTables))
+            : new Map();
+        hooks.suspendCapture?.(nativeDb);
+        for (const stmt of statements)
+            nativeDb.prepare(stmt).run();
+        nativeDb
+            .prepare(`INSERT INTO main."${MIGRATIONS_TABLE}" ("hash", "created_at", "name", "applied_at") values(?, ?, ?, ?)`)
+            .run(migration.hash, migration.folderMillis, migration.name ?? null, new Date().toISOString());
+        if (rebuild) {
+            // Re-scope after the statements: the rebuild may have created tables.
+            const after = foreignKeyViolations(nativeDb, foreignKeyScope(nativeDb, scopeTables));
+            // A renamed table keeps its pre-existing orphans: compare under the new names (T13027).
+            const live = new Set(listTables(nativeDb));
+            const renamed = renameViolations(before, renamedTables(statements), (t) => live.has(t));
+            const added = newViolations(renamed, after);
+            // @sync-invariant none:local-only a migration that adds FK violations is refused locally before commit; schema, not synced rows
+            if (added.length > 0)
+                throw new MigrationForeignKeyError(migration.name ?? '', added);
+        }
+        hooks.reinstallCapture?.(nativeDb);
+        nativeDb.exec('COMMIT');
+        committed = true;
+    }
+    catch (err) {
+        failure = err;
+    }
+    // NEW-6: never leave a pooled handle inside a transaction or with FK off.
+    if (nativeDb.isTransaction)
+        nativeDb.exec('ROLLBACK');
+    nativeDb.exec(`PRAGMA foreign_keys = ${prev}`);
+    const now = readForeignKeys(nativeDb);
+    if (now !== prev || nativeDb.isTransaction) {
+        // @sync-invariant none:local-only the migration runner restores this handle's FK mode; local schema pass
+        throw Object.assign(new ForeignKeysNotRestoredError(prev, now), { cause: failure });
+    }
+    if (!committed)
+        throw failure;
+    return rebuild;
+}
+/**
+ * Apply every pending migration of each lineage, in order, with the journal
+ * `migrateSync` would leave, one bracket per file.
+ *
+ * @param nativeDb - The store handle.
+ * @param db - The drizzle wrapper of `nativeDb` (for drizzle's journal upgrade).
+ * @param lineages - The lineages sharing the journal, in apply order.
+ * @param hooks - Optional D4 hooks.
+ */
+export function runBracketedMigrations(nativeDb, 
+// biome-ignore lint/suspicious/noExplicitAny: drizzle's session type is generic over the schema
+db, lineages, hooks = {}) {
+    const applied = [];
+    const rebuilds = [];
+    let hooked = false;
+    for (const lineage of lineages) {
+        const name = basename(lineage.folder.replace(/[\\/]+$/, ''));
+        // @sync-invariant none:local-only refuses a retired migration lineage on this store; local schema pass
+        if (LEGACY_LINEAGES.has(name))
+            throw new LegacyLineageRefusedError(name);
+    }
+    for (const lineage of lineages) {
+        const raw = readMigrationFiles({ migrationsFolder: lineage.folder });
+        // T12687: a worktree build never applies its migrations to a foreign store.
+        assertNoPendingMigrationsForWorktreeBuild(nativeDb, raw);
+        const migrations = sanitizeMigrationStatements(raw);
+        let reconciledDuplicate = false;
+        let reconciledExists = false;
+        leadingBracket(nativeDb, db, lineage, migrations);
+        for (;;) {
+            const pending = getMigrationsToRun({
+                localMigrations: migrations,
+                dbMigrations: journalRows(nativeDb),
+            });
+            if (pending.length === 0)
+                break;
+            if (!hooked) {
+                hooks.beforeMigrations?.(nativeDb);
+                hooked = true;
+            }
+            const next = pending[0];
+            try {
+                const rebuild = withBusyRetry(() => migrationBracket(nativeDb, next, hooks));
+                applied.push(next.name ?? '');
+                if (rebuild)
+                    rebuilds.push(next.name ?? '');
+                hooks.afterMigration?.(nativeDb, { name: next.name ?? '', hash: next.hash });
+            }
+            catch (err) {
+                const dup = isDuplicateColumnError(err) && !reconciledDuplicate;
+                const exists = isTableAlreadyExistsError(err) && !reconciledExists;
+                if (lineage.reconcile && (dup || exists)) {
+                    if (dup)
+                        reconciledDuplicate = true;
+                    if (exists)
+                        reconciledExists = true;
+                    getLogger(lineage.reconcile.logSubsystem).warn({ migration: next.name, message: err.message }, 'Migration hit an already-applied DDL target; reconciling the journal and retrying');
+                    leadingBracket(nativeDb, db, lineage, migrations);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    return { applied, rebuilds };
+}
+/**
+ * Same as {@link runBracketedMigrations} for one lineage, in the shape the
+ * callers of `reconcileJournal` + `migrateWithRetry` use today.
+ */
+export function migrateBracketed(
+// biome-ignore lint/suspicious/noExplicitAny: drizzle's session type is generic over the schema
+db, nativeDb, migrationsFolder, existenceTable, logSubsystem, siblings = [], hooks = {}) {
+    return runBracketedMigrations(nativeDb, db, [{ folder: migrationsFolder, reconcile: { existenceTable, logSubsystem, siblings } }], hooks);
+}
+//# sourceMappingURL=migration-runner.js.map