@askdkc/kiokuko 0.1.17 → 0.1.19

package/dist/db/connection.js

@@ -1,25 +1,36 @@
 import { DatabaseSync } from 'node:sqlite';
 import { dirname } from 'node:path';
-import { chmodSync, mkdirSync } from 'node:fs';
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
 import { NodeSqliteAdapter } from './adapter.js';
-const JOURNAL_MODE_RETRY_LIMIT = 5;
-function isLockError(error) {
-    return error instanceof Error && /database is locked|database table is locked|busy/i.test(error.message);
+import { withSqliteLockRetry } from './sqlite-retry.js';
+import { KiokukoError } from '../errors.js';
+export function databaseFileIdentity(filePath) {
+    const status = lstatSync(filePath, { bigint: true });
+    if (!status.isFile()) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'SQLite database path is not a regular non-symbolic-link file');
+    }
+    return Object.freeze({ device: status.dev, inode: status.ino });
 }
-function configureJournalMode(database) {
-    for (let attempt = 1;; attempt += 1) {
-        try {
-            database.exec('PRAGMA journal_mode = WAL;');
-            return;
-        }
-        catch (error) {
-            if (!isLockError(error) || attempt >= JOURNAL_MODE_RETRY_LIMIT)
-                throw error;
-            const buffer = new Int32Array(new SharedArrayBuffer(4));
-            Atomics.wait(buffer, 0, 0, attempt * 25);
-        }
+export function sameDatabaseFileIdentity(left, right) {
+    return left.device === right.device && left.inode === right.inode;
+}
+export function requireDatabaseFileIdentity(filePath, expected) {
+    let actual;
+    try {
+        actual = databaseFileIdentity(filePath);
+    }
+    catch (error) {
+        const failure = new KiokukoError('CONFLICT', 'SQLite database file identity changed during initialization');
+        Object.defineProperty(failure, 'cause', { value: error });
+        throw failure;
+    }
+    if (!sameDatabaseFileIdentity(actual, expected)) {
+        throw new KiokukoError('CONFLICT', 'SQLite database file identity changed during initialization');
     }
 }
+function configureJournalMode(database) {
+    withSqliteLockRetry(() => database.exec('PRAGMA journal_mode = WAL;'));
+}
 export function openConnection(filePath, options = {}) {
     if (filePath !== ':memory:') {
         mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
@@ -29,16 +40,34 @@ export function openConnection(filePath, options = {}) {
         timeout: 5000,
         ...(options.readOnly === undefined ? {} : { readOnly: options.readOnly }),
     });
-    if (filePath !== ':memory:' && !options.readOnly)
-        chmodSync(filePath, 0o600);
-    database.exec(`
-    PRAGMA foreign_keys = ON;
-    PRAGMA busy_timeout = 5000;
-  `);
-    if (!options.readOnly) {
-        configureJournalMode(database);
-        database.exec('PRAGMA synchronous = NORMAL;');
+    try {
+        if (options.expectedFileIdentity !== undefined) {
+            if (filePath === ':memory:') {
+                throw new KiokukoError('VALIDATION_ERROR', 'An in-memory database cannot have a file identity');
+            }
+            // This check deliberately precedes chmod and every writable PRAGMA.
+            requireDatabaseFileIdentity(filePath, options.expectedFileIdentity);
+        }
+        if (filePath !== ':memory:' && !options.readOnly)
+            chmodSync(filePath, 0o600);
+        database.exec(`
+      PRAGMA foreign_keys = ON;
+      PRAGMA busy_timeout = 5000;
+    `);
+        if (!options.readOnly) {
+            configureJournalMode(database);
+            database.exec('PRAGMA synchronous = NORMAL;');
+        }
+        return new NodeSqliteAdapter(filePath, database);
+    }
+    catch (error) {
+        try {
+            database.close();
+        }
+        catch (closeError) {
+            throw new AggregateError([error, closeError], 'SQLite connection initialization failed and closing it also failed');
+        }
+        throw error;
     }
-    return new NodeSqliteAdapter(filePath, database);
 }
 //# sourceMappingURL=connection.js.map

package/dist/db/connection.js.map

@@ -1 +1 @@
-{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAMnC,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,KAAK,YAAY,KAAK,IAAI,mDAAmD,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAC3G,CAAC;AAED,SAAS,oBAAoB,CAAC,QAAsB;IAClD,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,IAAI,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,4BAA4B,CAAC,CAAC;YAC5C,OAAO;QACT,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,IAAI,OAAO,IAAI,wBAAwB;gBAAE,MAAM,KAAK,CAAC;YAC5E,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;YACxD,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,OAAO,GAAG,EAAE,CAAC,CAAC;QAC3C,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,QAAgB,EAAE,UAA6B,EAAE;IAC9E,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC5B,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,YAAY,CAAC,QAAQ,EAAE;QAC1C,2BAA2B,EAAE,IAAI;QACjC,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC,CAAC;IACH,IAAI,QAAQ,KAAK,UAAU,IAAI,CAAC,OAAO,CAAC,QAAQ;QAAE,SAAS,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC7E,QAAQ,CAAC,IAAI,CAAC;;;GAGb,CAAC,CAAC;IACH,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,oBAAoB,CAAC,QAAQ,CAAC,CAAC;QAC/B,QAAQ,CAAC,IAAI,CAAC,8BAA8B,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,IAAI,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AACnD,CAAC"}
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"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"}

package/dist/db/migrate.d.ts

@@ -4,13 +4,34 @@ export interface MigrationResult {
     currentVersion: number;
 }
 export interface MigrationPlan {
-    applied: number[];
-    pending: number[];
-    databaseVersion: number;
-    currentVersion: number;
+    readonly applied: readonly number[];
+    readonly pending: readonly number[];
+    readonly databaseVersion: number;
+    readonly currentVersion: number;
+    readonly migrations: readonly MigrationSource[];
+}
+export interface MigrationIdentity {
+    readonly version: number;
+    readonly name: string;
+}
+export interface MigrationSource extends MigrationIdentity {
+    readonly checksum: string;
+    readonly sql: string;
+}
+export interface MigrationSnapshot {
+    readonly migrations: readonly MigrationSource[];
+}
+export interface MigrationHooks {
+    /**
+     * Runs after a pending migration's SQL and before its schema marker is
+     * written. The hook is inside the same SQLite transaction as both steps.
+     */
+    readonly beforeMarkApplied?: (database: SqliteDatabase, migration: MigrationIdentity) => void;
 }
 export declare function defaultMigrationsDirectory(): string;
-export declare function inspectMigrationPlan(database: SqliteDatabase, directory?: string): MigrationPlan;
-export declare function migrateDatabase(database: SqliteDatabase, directory?: string): MigrationResult;
-export declare const migrate: typeof migrateDatabase;
+export declare function loadMigrationSnapshot(directory?: string): MigrationSnapshot;
+export declare function inspectMigrationSnapshot(database: SqliteDatabase, snapshot: MigrationSnapshot): MigrationPlan;
+/** Apply an already-loaded migration snapshot inside a transaction owned by the caller. */
+export declare function migrateDatabaseSnapshotInTransaction(database: SqliteDatabase, snapshot: MigrationSnapshot, hooks?: MigrationHooks): MigrationResult;
+export declare function migrateDatabase(database: SqliteDatabase, directory?: string, hooks?: MigrationHooks): MigrationResult;
 //# sourceMappingURL=migrate.d.ts.map

package/dist/db/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,cAAc,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACxB;AAkBD,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAgGD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,SAA+B,GAAG,aAAa,CAEtH;AAiED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,SAA+B,GAAG,eAAe,CAkBnH;AAED,eAAO,MAAM,OAAO,wBAAkB,CAAC"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,cAAc,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,eAAgB,SAAQ,iBAAiB;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/F;AAkBD,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,SAA+B,GAAG,iBAAiB,CAsEjG;AAiGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,aAAa,CAE7G;AA2DD,2FAA2F;AAC3F,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,cAAc,EACxB,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,GAAE,cAAmB,GACzB,eAAe,CAEjB;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,cAAc,EACxB,SAAS,SAA+B,EACxC,KAAK,GAAE,cAAmB,GACzB,eAAe,CASjB"}

package/dist/db/migrate.js

@@ -2,29 +2,57 @@ import { createHash } from 'node:crypto';
 import { readFileSync, readdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
+import { TextDecoder } from 'node:util';
 import { KiokukoError } from '../errors.js';
-const MIGRATION_FILE = /^(\d+)_([a-z0-9_-]+)\.sql$/i;
-const LOCK_RETRY_LIMIT = 5;
+import { canonicalizeEntryRevisionHashesInMigration } from '../memory/revisions.js';
+import { withImmediateTransaction } from './transaction.js';
+function applyBuiltInMigrationOperation(database, migration) {
+    if (migration.version === 9 && migration.name === '009_external_skill_discovery.sql') {
+        canonicalizeEntryRevisionHashesInMigration(database);
+    }
+}
+const MIGRATION_FILE = /^([0-9]{3})_([a-z0-9_-]+)\.sql$/;
+const loadedMigrationSnapshots = new WeakSet();
+const fatalUtf8Decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
 export function defaultMigrationsDirectory() {
     return fileURLToPath(new URL('../../migrations/', import.meta.url));
 }
-function listMigrations(directory) {
+export function loadMigrationSnapshot(directory = defaultMigrationsDirectory()) {
     const migrations = readdirSync(directory)
         .map((name) => {
         const match = MIGRATION_FILE.exec(name);
-        if (!match)
+        if (!match) {
+            if (/\.sql$/iu.test(name)) {
+                throw new KiokukoError('INTEGRITY_ERROR', `Migration filename is not canonical: ${name}`, { name });
+            }
             return undefined;
+        }
         const version = Number(match[1]);
-        const sql = readFileSync(path.join(directory, name), 'utf8');
+        const bytes = readFileSync(path.join(directory, name));
+        if (bytes.subarray(0, 3).equals(Buffer.from([0xEF, 0xBB, 0xBF]))) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration file ${name} has a non-canonical UTF-8 BOM`);
+        }
+        let sql;
+        try {
+            sql = fatalUtf8Decoder.decode(bytes);
+        }
+        catch (error) {
+            const failure = new KiokukoError('INTEGRITY_ERROR', `Migration file ${name} is not valid UTF-8`);
+            Object.defineProperty(failure, 'cause', { value: error });
+            throw failure;
+        }
         return {
             version,
             name,
             sql,
-            checksum: createHash('sha256').update(sql).digest('hex'),
+            checksum: createHash('sha256').update(bytes).digest('hex'),
         };
     })
         .filter((migration) => migration !== undefined)
         .sort((left, right) => left.version - right.version);
+    if (migrations.length === 0) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Migration directory contains no versioned migration files');
+    }
     const versions = new Set();
     for (const migration of migrations) {
         if (!Number.isSafeInteger(migration.version) || migration.version < 1) {
@@ -35,7 +63,23 @@ function listMigrations(directory) {
         }
         versions.add(migration.version);
     }
-    return migrations;
+    for (const [index, migration] of migrations.entries()) {
+        const expectedVersion = index + 1;
+        if (migration.version !== expectedVersion) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration files must form an exact contiguous sequence starting at version 1; expected ${expectedVersion} but found ${migration.version}`, { expectedVersion, actualVersion: migration.version, name: migration.name });
+        }
+    }
+    const snapshot = Object.freeze({
+        migrations: Object.freeze(migrations.map((migration) => Object.freeze(migration))),
+    });
+    loadedMigrationSnapshots.add(snapshot);
+    return snapshot;
+}
+function requireLoadedMigrationSnapshot(snapshot) {
+    if (!loadedMigrationSnapshots.has(snapshot)) {
+        throw new KiokukoError('INTEGRITY_ERROR', 'Migration snapshot was not produced by the validated snapshot loader');
+    }
+    return snapshot.migrations;
 }
 function hasMigrationTable(database) {
     return Boolean(database.prepare(`
@@ -53,16 +97,23 @@ function appliedMigrationRows(database) {
     ORDER BY version
   `).all();
 }
+function appliedMigrationVersion(value) {
+    if (typeof value === 'number' && Number.isSafeInteger(value) && value >= 1)
+        return value;
+    throw new KiokukoError('INTEGRITY_ERROR', 'Database migration history contains an invalid version');
+}
 function migrationPlan(database, migrations) {
     const currentVersion = migrations.at(-1)?.version ?? 0;
     const byVersion = new Map(migrations.map((migration) => [migration.version, migration]));
     const rows = appliedMigrationRows(database);
     const applied = [];
+    const seenVersions = new Set();
     for (const row of rows) {
-        const version = Number(row.version);
-        if (!Number.isSafeInteger(version) || version < 1) {
-            throw new KiokukoError('INTEGRITY_ERROR', 'Database migration history contains an invalid version');
+        const version = appliedMigrationVersion(row.version);
+        if (seenVersions.has(version)) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Database migration history contains duplicate version ${version}`, { version });
         }
+        seenVersions.add(version);
         const migration = byVersion.get(version);
         if (!migration) {
             if (version > currentVersion) {
@@ -70,89 +121,56 @@ function migrationPlan(database, migrations) {
             }
             throw new KiokukoError('INTEGRITY_ERROR', `Database migration version ${version} is not supported by this Kiokuko binary`);
         }
+        if (typeof row.name !== 'string' || typeof row.checksum !== 'string') {
+            throw new KiokukoError('INTEGRITY_ERROR', `Database migration history contains invalid metadata for version ${version}`, { version });
+        }
         if (row.name !== migration.name || row.checksum !== migration.checksum) {
             throw new KiokukoError('INTEGRITY_ERROR', `Migration checksum mismatch for ${migration.name}`, { version: migration.version, name: migration.name });
         }
         applied.push(version);
     }
-    const appliedSet = new Set(applied);
-    let foundPending = false;
-    for (const migration of migrations) {
-        if (!appliedSet.has(migration.version))
-            foundPending = true;
-        else if (foundPending) {
+    for (const [index, version] of applied.entries()) {
+        const expectedVersion = index + 1;
+        if (version !== expectedVersion) {
             throw new KiokukoError('INTEGRITY_ERROR', 'Database migration history is not a contiguous prefix');
         }
     }
+    const appliedSet = new Set(applied);
     return {
-        applied,
-        pending: migrations.filter((migration) => !appliedSet.has(migration.version)).map((migration) => migration.version),
+        applied: Object.freeze(applied),
+        pending: Object.freeze(migrations.filter((migration) => !appliedSet.has(migration.version)).map((migration) => migration.version)),
         databaseVersion: applied.at(-1) ?? 0,
         currentVersion,
+        migrations,
     };
 }
-export function inspectMigrationPlan(database, directory = defaultMigrationsDirectory()) {
-    return migrationPlan(database, listMigrations(directory));
+export function inspectMigrationSnapshot(database, snapshot) {
+    return migrationPlan(database, requireLoadedMigrationSnapshot(snapshot));
 }
-function isLockError(error) {
-    return error instanceof Error && /database is locked|database table is locked|busy/i.test(error.message);
-}
-function waitForRetry(attempt) {
-    const buffer = new Int32Array(new SharedArrayBuffer(4));
-    Atomics.wait(buffer, 0, 0, attempt * 25);
-}
-function withLockRetry(operation) {
-    for (let attempt = 1;; attempt += 1) {
-        try {
-            return operation();
-        }
-        catch (error) {
-            if (!isLockError(error) || attempt >= LOCK_RETRY_LIMIT)
-                throw error;
-            waitForRetry(attempt);
+function applyOneInTransaction(database, migration, migrations, hooks) {
+    // Revalidate while the caller's write lock is held. No other migrator can
+    // advance the history between this check, the SQL, the application hook,
+    // and the marker write.
+    migrationPlan(database, migrations);
+    const existing = database
+        .prepare('SELECT checksum FROM schema_migrations WHERE version = ?')
+        .get(migration.version);
+    if (existing) {
+        if (typeof existing.checksum !== 'string' || existing.checksum !== migration.checksum) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration checksum mismatch for ${migration.name}`, { version: migration.version, name: migration.name });
         }
+        return false;
     }
+    database.exec(migration.sql);
+    applyBuiltInMigrationOperation(database, migration);
+    hooks.beforeMarkApplied?.(database, { version: migration.version, name: migration.name });
+    database
+        .prepare('INSERT INTO schema_migrations (version, name, checksum, applied_at) VALUES (?, ?, ?, ?)')
+        .run(migration.version, migration.name, migration.checksum, new Date().toISOString());
+    return true;
 }
-function rollback(database) {
-    try {
-        database.exec('ROLLBACK');
-    }
-    catch {
-        // Preserve the original migration error.
-    }
-}
-function applyOne(database, migration, migrations) {
-    return withLockRetry(() => {
-        database.exec('BEGIN IMMEDIATE');
-        try {
-            // Revalidate under the write lock so a newer binary cannot advance the
-            // database between the read-only upgrade inspection and this write.
-            migrationPlan(database, migrations);
-            const existing = database
-                .prepare('SELECT checksum FROM schema_migrations WHERE version = ?')
-                .get(migration.version);
-            if (existing) {
-                if (existing.checksum !== migration.checksum) {
-                    throw new KiokukoError('INTEGRITY_ERROR', `Migration checksum mismatch for ${migration.name}`, { version: migration.version, name: migration.name });
-                }
-                database.exec('COMMIT');
-                return false;
-            }
-            database.exec(migration.sql);
-            database
-                .prepare('INSERT INTO schema_migrations (version, name, checksum, applied_at) VALUES (?, ?, ?, ?)')
-                .run(migration.version, migration.name, migration.checksum, new Date().toISOString());
-            database.exec('COMMIT');
-            return true;
-        }
-        catch (error) {
-            rollback(database);
-            throw error;
-        }
-    });
-}
-export function migrateDatabase(database, directory = defaultMigrationsDirectory()) {
-    const migrations = listMigrations(directory);
+function applyMigrationSetInTransaction(database, migrations, hooks) {
+    // Revalidate the database state after the writer transaction begins.
     migrationPlan(database, migrations);
     database.exec(`
     CREATE TABLE IF NOT EXISTS schema_migrations (
@@ -164,11 +182,21 @@ export function migrateDatabase(database, directory = defaultMigrationsDirectory
   `);
     const applied = [];
     for (const migration of migrations) {
-        if (applyOne(database, migration, migrations))
+        if (applyOneInTransaction(database, migration, migrations, hooks))
             applied.push(migration.version);
     }
     const currentVersion = migrations.at(-1)?.version ?? 0;
     return { applied, currentVersion };
 }
-export const migrate = migrateDatabase;
+/** Apply an already-loaded migration snapshot inside a transaction owned by the caller. */
+export function migrateDatabaseSnapshotInTransaction(database, snapshot, hooks = {}) {
+    return applyMigrationSetInTransaction(database, requireLoadedMigrationSnapshot(snapshot), hooks);
+}
+export function migrateDatabase(database, directory = defaultMigrationsDirectory(), hooks = {}) {
+    const migrations = loadMigrationSnapshot(directory).migrations;
+    // Fail on unsupported history before beginning a write transaction, then
+    // repeat the check under the lock in applyMigrationSetInTransaction.
+    migrationPlan(database, migrations);
+    return withImmediateTransaction(database, () => applyMigrationSetInTransaction(database, migrations, hooks));
+}
 //# sourceMappingURL=migrate.js.map

package/dist/db/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"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"}

package/dist/db/sqlite-retry.d.ts

@@ -0,0 +1,11 @@
+/** Match only node:sqlite errors whose SQLite primary result code is BUSY or LOCKED. */
+export declare function isSqliteLockError(error: unknown): boolean;
+/** Match only native node:sqlite operational failures discovery may safely report as bounded degradation. */
+export declare function isSqliteOperationalError(error: unknown): boolean;
+/** Match database bytes that SQLite itself reports as corrupt or not a database. */
+export declare function isSqliteCorruptionError(error: unknown): boolean;
+/** Match one exact PRIMARY KEY/UNIQUE target; trigger text cannot spoof this check. */
+export declare function isSqliteUniqueConstraintError(error: unknown, targets: readonly string[]): boolean;
+/** Retry a synchronous operation at most five total attempts, and only for SQLite BUSY/LOCKED. */
+export declare function withSqliteLockRetry<T>(operation: () => T): T;
+//# sourceMappingURL=sqlite-retry.d.ts.map

package/dist/db/sqlite-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-retry.d.ts","sourceRoot":"","sources":["../../src/db/sqlite-retry.ts"],"names":[],"mappings":"AAuBA,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED,6GAA6G;AAC7G,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGhE;AAED,oFAAoF;AACpF,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAK/D;AAED,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAIjG;AAOD,kGAAkG;AAClG,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAS5D"}

package/dist/db/sqlite-retry.js

@@ -0,0 +1,66 @@
+const LOCK_ATTEMPT_LIMIT = 5;
+const SQLITE_BUSY = 5;
+const SQLITE_LOCKED = 6;
+const SQLITE_CORRUPT = 11;
+const SQLITE_NOTADB = 26;
+const SQLITE_CONSTRAINT_PRIMARYKEY = 1555;
+const SQLITE_CONSTRAINT_UNIQUE = 2067;
+const SQLITE_OPERATIONAL_CODES = new Set([SQLITE_BUSY, SQLITE_LOCKED, 8, 10, 13, 14]);
+function sqliteErrorCode(error) {
+    if (!(error instanceof Error))
+        return undefined;
+    const sqliteError = error;
+    if (sqliteError.code !== 'ERR_SQLITE_ERROR'
+        || typeof sqliteError.errcode !== 'number'
+        || !Number.isSafeInteger(sqliteError.errcode)
+        || sqliteError.errcode < 0) {
+        return undefined;
+    }
+    return sqliteError.errcode;
+}
+/** Match only node:sqlite errors whose SQLite primary result code is BUSY or LOCKED. */
+export function isSqliteLockError(error) {
+    const code = sqliteErrorCode(error);
+    if (code === undefined)
+        return false;
+    const primaryResultCode = code & 0xff;
+    return primaryResultCode === SQLITE_BUSY || primaryResultCode === SQLITE_LOCKED;
+}
+/** Match only native node:sqlite operational failures discovery may safely report as bounded degradation. */
+export function isSqliteOperationalError(error) {
+    const code = sqliteErrorCode(error);
+    return code !== undefined && SQLITE_OPERATIONAL_CODES.has(code & 0xff);
+}
+/** Match database bytes that SQLite itself reports as corrupt or not a database. */
+export function isSqliteCorruptionError(error) {
+    const code = sqliteErrorCode(error);
+    if (code === undefined)
+        return false;
+    const primaryResultCode = code & 0xff;
+    return primaryResultCode === SQLITE_CORRUPT || primaryResultCode === SQLITE_NOTADB;
+}
+/** Match one exact PRIMARY KEY/UNIQUE target; trigger text cannot spoof this check. */
+export function isSqliteUniqueConstraintError(error, targets) {
+    const code = sqliteErrorCode(error);
+    if (code !== SQLITE_CONSTRAINT_PRIMARYKEY && code !== SQLITE_CONSTRAINT_UNIQUE)
+        return false;
+    return error instanceof Error && targets.some((target) => error.message === `UNIQUE constraint failed: ${target}`);
+}
+function waitForRetry(attempt) {
+    const buffer = new Int32Array(new SharedArrayBuffer(4));
+    Atomics.wait(buffer, 0, 0, attempt * 25);
+}
+/** Retry a synchronous operation at most five total attempts, and only for SQLite BUSY/LOCKED. */
+export function withSqliteLockRetry(operation) {
+    for (let attempt = 1;; attempt += 1) {
+        try {
+            return operation();
+        }
+        catch (error) {
+            if (!isSqliteLockError(error) || attempt >= LOCK_ATTEMPT_LIMIT)
+                throw error;
+            waitForRetry(attempt);
+        }
+    }
+}
+//# sourceMappingURL=sqlite-retry.js.map

package/dist/db/sqlite-retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite-retry.js","sourceRoot":"","sources":["../../src/db/sqlite-retry.ts"],"names":[],"mappings":"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"}

package/dist/db/transaction.d.ts

@@ -1,4 +1,17 @@
 import type { SqliteDatabase } from './adapter.js';
+/**
+ * COMMIT threw and the subsequent ROLLBACK also threw. The caller must treat
+ * the transaction as possibly committed: compensating durable side effects
+ * could otherwise turn an uncertain outcome into split-brain state.
+ */
+export declare class TransactionCommitUncertainError extends AggregateError {
+    readonly commitError: unknown;
+    readonly rollbackError: unknown;
+    constructor(commitError: unknown, rollbackError: unknown);
+}
+export declare function rollbackFailedTransaction(database: SqliteDatabase, operationError: unknown): never;
 /** Run a synchronous write transaction with bounded retry for SQLite lock errors only. */
 export declare function withImmediateTransaction<T>(database: SqliteDatabase, operation: () => T): T;
+/** Run synchronous reads against one SQLite snapshot without reserving a writer lock. */
+export declare function withDeferredReadTransaction<T>(database: SqliteDatabase, operation: () => T): T;
 //# sourceMappingURL=transaction.d.ts.map

package/dist/db/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAqBnD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAiB3F"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/db/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD;;;;GAIG;AACH,qBAAa,+BAAgC,SAAQ,cAAc;IACjE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;gBAEpB,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO;CASzD;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,cAAc,EAAE,cAAc,EAAE,OAAO,GAAG,KAAK,CAUlG;AAeD,0FAA0F;AAC1F,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAY3F;AAED,yFAAyF;AACzF,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,QAAQ,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAU9F"}