kiokuko-dsh 0.1.0

package/dist/db/capabilities.js

@@ -0,0 +1,57 @@
+import { DatabaseSync } from 'node:sqlite';
+import { KiokukoError } from '../errors.js';
+import { SQLITE_VEC_BACKEND_ID } from '../embedding/sqlite-vec-backend.js';
+import { SQLITE_VEC_EXTENSION_VERSION } from '../embedding/sqlite-vec-loader.js';
+function invalidCapability(capability) {
+    throw new KiokukoError('INTEGRITY_ERROR', 'SQLite capability probe returned an invalid or unsupported result', { capability });
+}
+/** Probe the optional extension without changing the core SQLite contract. */
+export function detectSqliteVecCapability(database) {
+    try {
+        const version = database.prepare('SELECT vec_version() AS version').get()?.version;
+        if (version !== SQLITE_VEC_EXTENSION_VERSION)
+            return { id: SQLITE_VEC_BACKEND_ID, available: false, version: null };
+        return { id: SQLITE_VEC_BACKEND_ID, available: true, version };
+    }
+    catch {
+        return { id: SQLITE_VEC_BACKEND_ID, available: false, version: null };
+    }
+}
+export function detectCapabilities(database) {
+    // Migrations require FTS5. An unavailable module or any unexpected probe
+    // failure is fatal rather than a false capability report.
+    database.exec('CREATE VIRTUAL TABLE temp.kiokuko_capability_fts USING fts5(content); DROP TABLE temp.kiokuko_capability_fts;');
+    const sqliteVersion = database.prepare('SELECT sqlite_version() AS version').get()?.version;
+    if (typeof sqliteVersion !== 'string' || !/^\d+\.\d+\.\d+$/u.test(sqliteVersion)) {
+        invalidCapability('sqliteVersion');
+    }
+    const foreignKeys = database.prepare('PRAGMA foreign_keys').get()?.foreign_keys;
+    if (foreignKeys !== 1)
+        invalidCapability('foreignKeys');
+    const journalMode = database.prepare('PRAGMA journal_mode').get()?.journal_mode;
+    if (journalMode !== 'wal')
+        invalidCapability('journalMode');
+    const synchronous = database.prepare('PRAGMA synchronous').get()?.synchronous;
+    if (synchronous !== 1)
+        invalidCapability('synchronous');
+    const busyTimeout = database.prepare('PRAGMA busy_timeout').get()?.timeout;
+    if (busyTimeout !== 5000)
+        invalidCapability('busyTimeout');
+    const nativePrototype = DatabaseSync.prototype;
+    const serializationDatabase = database;
+    if (typeof nativePrototype.serialize !== 'function'
+        || typeof serializationDatabase.serializeDatabase !== 'function') {
+        invalidCapability('backup');
+    }
+    return {
+        driver: 'node:sqlite',
+        sqliteVersion,
+        fts5: true,
+        foreignKeys: true,
+        journalMode,
+        synchronous: String(synchronous),
+        busyTimeout,
+        backup: true,
+    };
+}
+//# sourceMappingURL=capabilities.js.map

package/dist/db/capabilities.js.map

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

package/dist/db/connection.d.ts

@@ -0,0 +1,21 @@
+import { NodeSqliteAdapter } from './adapter.js';
+import { KiokukoError } from '../errors.js';
+import { type SqliteVecLoader } from '../embedding/sqlite-vec-loader.js';
+export interface DatabaseFileIdentity {
+    readonly device: bigint;
+    readonly inode: bigint;
+}
+export interface ConnectionOptions {
+    readonly readOnly?: boolean;
+    readonly expectedFileIdentity?: DatabaseFileIdentity;
+    readonly sqliteVecLoader?: SqliteVecLoader;
+}
+/** Internal discriminator for failures caused specifically by sqlite-vec loading. */
+export declare class SqliteVecLoadError extends KiokukoError {
+    constructor(message: string, cause?: unknown);
+}
+export declare function databaseFileIdentity(filePath: string): DatabaseFileIdentity;
+export declare function sameDatabaseFileIdentity(left: DatabaseFileIdentity, right: DatabaseFileIdentity): boolean;
+export declare function requireDatabaseFileIdentity(filePath: string, expected: DatabaseFileIdentity): void;
+export declare function openConnection(filePath: string, options?: ConnectionOptions): NodeSqliteAdapter;
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/db/connection.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAC;IACrD,QAAQ,CAAC,eAAe,CAAC,EAAE,eAAe,CAAC;CAC5C;AAED,qFAAqF;AACrF,qBAAa,kBAAmB,SAAQ,YAAY;gBACtC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAK7C;AAyCD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,oBAAoB,CAM3E;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAEzG;AAED,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,oBAAoB,GAAG,IAAI,CAkBlG;AAMD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,iBAAiB,CAyCnG"}

package/dist/db/connection.js

@@ -0,0 +1,129 @@
+import { DatabaseSync } from 'node:sqlite';
+import { dirname } from 'node:path';
+import { chmodSync, lstatSync, mkdirSync } from 'node:fs';
+import { NodeSqliteAdapter } from './adapter.js';
+import { withSqliteLockRetry } from './sqlite-retry.js';
+import { KiokukoError } from '../errors.js';
+import { isSqliteVecLoader, } from '../embedding/sqlite-vec-loader.js';
+/** Internal discriminator for failures caused specifically by sqlite-vec loading. */
+export class SqliteVecLoadError extends KiokukoError {
+    constructor(message, cause) {
+        super('SERVICE_UNAVAILABLE', message);
+        this.name = 'SqliteVecLoadError';
+        if (cause !== undefined)
+            Object.defineProperty(this, 'cause', { value: cause });
+    }
+}
+function requireSqliteVecLoader(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isSqliteVecLoader(value)) {
+        throw new KiokukoError('VALIDATION_ERROR', 'The SQLite extension loader is not the known sqlite-vec loader');
+    }
+    return value;
+}
+function loadSqliteVec(database, loader) {
+    let failure;
+    let failed = false;
+    let loadingDisabled = false;
+    try {
+        loader.load(database);
+        database.enableLoadExtension(false);
+        loadingDisabled = true;
+        const version = database.prepare('SELECT vec_version() AS version').get()?.version;
+        if (version !== loader.extensionVersion) {
+            throw new SqliteVecLoadError('The loaded sqlite-vec version is unsupported');
+        }
+    }
+    catch (error) {
+        failure = error;
+        failed = true;
+    }
+    if (!loadingDisabled) {
+        try {
+            database.enableLoadExtension(false);
+        }
+        catch (disableError) {
+            failure = failed
+                ? new AggregateError([failure, disableError], 'sqlite-vec loading failed and disabling extension loading also failed')
+                : disableError;
+            failed = true;
+        }
+    }
+    if (!failed)
+        return;
+    if (failure instanceof SqliteVecLoadError)
+        throw failure;
+    throw new SqliteVecLoadError('The sqlite-vec extension could not be loaded', failure);
+}
+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 });
+}
+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 = {}) {
+    const sqliteVecLoader = requireSqliteVecLoader(options.sqliteVecLoader);
+    if (filePath !== ':memory:') {
+        mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    }
+    const database = new DatabaseSync(filePath, {
+        enableForeignKeyConstraints: true,
+        timeout: 5000,
+        ...(sqliteVecLoader === undefined ? {} : { allowExtension: true }),
+        ...(options.readOnly === undefined ? {} : { readOnly: options.readOnly }),
+    });
+    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;');
+        }
+        if (sqliteVecLoader !== undefined)
+            loadSqliteVec(database, sqliteVecLoader);
+        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;
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/db/connection.js.map

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

package/dist/db/migrate.d.ts

@@ -0,0 +1,40 @@
+import type { SqliteDatabase } from './adapter.js';
+export interface MigrationResult {
+    applied: number[];
+    currentVersion: number;
+    recoveredEntries: number;
+}
+export interface MigrationPlan {
+    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;
+    /** Allows setup to remove unreadable memory while preserving the pre-upgrade backup. */
+    readonly recoverInvalidStoredMemory?: boolean;
+}
+export declare function defaultMigrationsDirectory(): string;
+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

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/db/migrate.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAa,MAAM,cAAc,CAAC;AAG9D,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;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;IAC9F,wFAAwF;IACxF,QAAQ,CAAC,0BAA0B,CAAC,EAAE,OAAO,CAAC;CAC/C;AA6BD,wBAAgB,0BAA0B,IAAI,MAAM,CAEnD;AAED,wBAAgB,qBAAqB,CAAC,SAAS,SAA+B,GAAG,iBAAiB,CA4EjG;AAiGD,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,aAAa,CAE7G;AA8DD,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

@@ -0,0 +1,216 @@
+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';
+import { canonicalizeEntryRevisionHashesInMigration } from '../memory/revisions.js';
+import { migrateLegacyContextDeliveries } from '../context/delivery-migration.js';
+import { withImmediateTransaction } from './transaction.js';
+function applyBuiltInMigrationOperation(database, migration, hooks) {
+    if (migration.version === 9 && migration.name === '009_external_skill_discovery.sql') {
+        return canonicalizeEntryRevisionHashesInMigration(database, hooks.recoverInvalidStoredMemory === undefined
+            ? {}
+            : { recoverInvalidStoredMemory: hooks.recoverInvalidStoredMemory }).recoveredEntries;
+    }
+    if (migration.version === 12 && migration.name === '012_context_delivery_v4.sql') {
+        migrateLegacyContextDeliveries(database);
+        return 0;
+    }
+    return 0;
+}
+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));
+}
+export function loadMigrationSnapshot(directory = defaultMigrationsDirectory()) {
+    const migrations = readdirSync(directory)
+        .map((name) => {
+        const match = MIGRATION_FILE.exec(name);
+        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 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;
+        }
+        if (sql.includes('\r')) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration file ${name} has non-canonical line endings; use LF only`);
+        }
+        return {
+            version,
+            name,
+            sql,
+            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) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration version is invalid for ${migration.name}`);
+        }
+        if (versions.has(migration.version)) {
+            throw new KiokukoError('INTEGRITY_ERROR', `Migration version ${migration.version} is duplicated`);
+        }
+        versions.add(migration.version);
+    }
+    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(`
+    SELECT 1 AS present
+    FROM sqlite_master
+    WHERE type = 'table' AND name = 'schema_migrations'
+  `).get());
+}
+function appliedMigrationRows(database) {
+    if (!hasMigrationTable(database))
+        return [];
+    return database.prepare(`
+    SELECT version, name, checksum
+    FROM schema_migrations
+    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 = 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) {
+                throw new KiokukoError('INTEGRITY_ERROR', `Database schema version ${version} is newer than this Kiokuko binary supports (${currentVersion})`, { databaseVersion: version, supportedVersion: currentVersion });
+            }
+            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);
+    }
+    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: 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 inspectMigrationSnapshot(database, snapshot) {
+    return migrationPlan(database, requireLoadedMigrationSnapshot(snapshot));
+}
+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 { applied: false, recoveredEntries: 0 };
+    }
+    database.exec(migration.sql);
+    const recoveredEntries = applyBuiltInMigrationOperation(database, migration, hooks);
+    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 { applied: true, recoveredEntries };
+}
+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 (
+      version INTEGER PRIMARY KEY,
+      name TEXT NOT NULL,
+      checksum TEXT NOT NULL,
+      applied_at TEXT NOT NULL
+    );
+  `);
+    const applied = [];
+    let recoveredEntries = 0;
+    for (const migration of migrations) {
+        const result = applyOneInTransaction(database, migration, migrations, hooks);
+        if (result.applied)
+            applied.push(migration.version);
+        recoveredEntries += result.recoveredEntries;
+    }
+    const currentVersion = migrations.at(-1)?.version ?? 0;
+    return { applied, currentVersion, recoveredEntries };
+}
+/** 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

@@ -0,0 +1 @@
+{"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":"AAyBA,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,CAgB5D"}

package/dist/db/sqlite-retry.js

@@ -0,0 +1,70 @@
+import { KiokukoError } from '../errors.js';
+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))
+                throw error;
+            if (attempt >= LOCK_ATTEMPT_LIMIT) {
+                throw new KiokukoError('BACKPRESSURE', 'SQLite remained busy after bounded retry', { retryAfterSeconds: 1 });
+            }
+            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

@@ -0,0 +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

@@ -0,0 +1 @@
+{"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"}