@lwelliott/cortex-cli 1.0.3

package/dist/db/locks.d.ts

@@ -0,0 +1,106 @@
+import type Database from 'better-sqlite3';
+/** Options for lock acquisition */
+export interface LockOptions {
+    /** Lock name (e.g., "kanban:sprint-2026050301") */
+    name: string;
+    /** Unique identifier for the lock holder (e.g., PID + timestamp) */
+    owner: string;
+    /** Max wait time in ms (default: 5000) */
+    timeoutMs?: number;
+    /** Lock considered stale after this many ms (default: 60000) */
+    staleMs?: number;
+    /** Retry interval in ms (default: 50) */
+    retryIntervalMs?: number;
+}
+/** Handle returned after successful lock acquisition */
+export interface LockHandle {
+    /** The lock name */
+    name: string;
+    /** The owner identifier */
+    owner: string;
+    /** Release the lock */
+    release: () => void;
+}
+/**
+ * Generate a unique owner string using PID and timestamp.
+ */
+export declare function generateLockOwner(): string;
+/**
+ * Clear stale locks for a given lock name.
+ * A lock is stale if COALESCE(last_heartbeat, acquired_at) is older than now - staleMs.
+ * Per FS-SS-003-0004 VR-003.
+ *
+ * @returns Number of stale locks cleared
+ */
+export declare function clearStaleLocks(db: Database.Database, name: string, staleMs?: number): number;
+/**
+ * Attempt to acquire a lock (single attempt, no retry).
+ * Uses TEXT (ISO 8601) for acquired_at per FS-SS-003-0003 Data Model.
+ *
+ * @returns true if acquired, false if lock is held by another owner
+ */
+export declare function tryAcquireLock(db: Database.Database, name: string, owner: string): boolean;
+/**
+ * Refresh/heartbeat a lock — update last_heartbeat timestamp.
+ * Per FS-SS-003-0004 VR-005: operations exceeding the stale threshold
+ * must explicitly extend their lock.
+ *
+ * @returns true if the lock was refreshed, false if not found or wrong owner
+ */
+export declare function refreshLock(db: Database.Database, name: string, owner: string): boolean;
+/**
+ * Get information about a lock (if held).
+ */
+export declare function getLockInfo(db: Database.Database, name: string): {
+    owner: string;
+    acquiredAt: string;
+    lastHeartbeat: string | null;
+} | null;
+/**
+ * Acquire an advisory lock with timeout and stale detection.
+ * Implements the retry loop with configurable timeout.
+ *
+ * Per FS-SS-003-0003 VR-008: re-evaluates lock staleness at intervals no
+ * greater than the advisory lock acquisition timeout. The default retry
+ * interval (50ms) is well below the default timeout (5000ms), so each
+ * retry iteration satisfies this bound.
+ *
+ * @throws LockTimeoutError if the lock cannot be acquired within timeoutMs (ERR-LOCK-002)
+ */
+export declare function acquireLock(db: Database.Database, opts: LockOptions): LockHandle;
+/**
+ * Acquire multiple advisory locks in alphabetical order.
+ * Per FS-SS-003-0003 VR-006/VR-007: locks must be acquired in alphabetical
+ * order by lock name to prevent deadlocks.
+ *
+ * On partial failure (some locks acquired but a later one times out),
+ * all acquired locks are released before the error is thrown.
+ *
+ * @throws LockTimeoutError if any lock cannot be acquired
+ */
+export declare function acquireLocks(db: Database.Database, lockNames: string[], owner: string, opts?: Omit<LockOptions, 'name' | 'owner'>): LockHandle[];
+/**
+ * Release an advisory lock.
+ * Only the owner can release their own lock.
+ *
+ * @returns true if the lock was released, false if not found or wrong owner
+ */
+export declare function releaseLock(db: Database.Database, name: string, owner: string): boolean;
+/**
+ * Force-release a lock regardless of owner.
+ * Use with caution — only for administrative purposes.
+ */
+export declare function forceReleaseLock(db: Database.Database, name: string): boolean;
+/**
+ * Execute a function within a lock context, guaranteeing release in finally.
+ * Per FS-SS-003-0003 VR-003: locks must be released upon operation completion
+ * (success, failure, or exception).
+ *
+ * @param db - Database connection
+ * @param opts - Lock acquisition options
+ * @param fn - Function to execute while holding the lock
+ * @returns The return value of fn
+ * @throws LockTimeoutError if the lock cannot be acquired
+ */
+export declare function withLock<T>(db: Database.Database, opts: LockOptions, fn: () => T): T;
+//# sourceMappingURL=locks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"locks.d.ts","sourceRoot":"","sources":["../../src/db/locks.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wDAAwD;AACxD,MAAM,WAAW,UAAU;IACzB,oBAAoB;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,2BAA2B;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AASD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB,GAAG,MAAM,CAQ/G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAY1F;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKvF;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,CAY3I;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,GAAG,UAAU,CA4ChF;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,UAAU,EAAE,CAkBhJ;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAKvF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK7E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAOpF"}

package/dist/db/locks.js

@@ -0,0 +1,211 @@
+"use strict";
+// Advisory lock implementation
+// Implements AD-0006: Advisory Locks for Multi-Step Operations
+// + FS-SS-003-0003 (lock management), FS-SS-003-0004 (stale detection),
+//   FS-SS-003-0007 (error reporting)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateLockOwner = generateLockOwner;
+exports.clearStaleLocks = clearStaleLocks;
+exports.tryAcquireLock = tryAcquireLock;
+exports.refreshLock = refreshLock;
+exports.getLockInfo = getLockInfo;
+exports.acquireLock = acquireLock;
+exports.acquireLocks = acquireLocks;
+exports.releaseLock = releaseLock;
+exports.forceReleaseLock = forceReleaseLock;
+exports.withLock = withLock;
+const errors_1 = require("../utils/errors");
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_STALE_MS = 60000; // FS-SS-003-0004 VR-001: default 60 seconds
+const DEFAULT_RETRY_INTERVAL_MS = 50;
+/**
+ * Generate a unique owner string using PID and timestamp.
+ */
+function generateLockOwner() {
+    return `${process.pid}:${Date.now()}`;
+}
+/**
+ * Get the current ISO 8601 timestamp.
+ */
+function isoNow() {
+    return new Date().toISOString();
+}
+/**
+ * Clear stale locks for a given lock name.
+ * A lock is stale if COALESCE(last_heartbeat, acquired_at) is older than now - staleMs.
+ * Per FS-SS-003-0004 VR-003.
+ *
+ * @returns Number of stale locks cleared
+ */
+function clearStaleLocks(db, name, staleMs = DEFAULT_STALE_MS) {
+    const cutoff = new Date(Date.now() - staleMs).toISOString();
+    const result = db
+        .prepare('DELETE FROM locks WHERE name = ? AND COALESCE(last_heartbeat, acquired_at) < ?')
+        .run(name, cutoff);
+    return result.changes;
+}
+/**
+ * Attempt to acquire a lock (single attempt, no retry).
+ * Uses TEXT (ISO 8601) for acquired_at per FS-SS-003-0003 Data Model.
+ *
+ * @returns true if acquired, false if lock is held by another owner
+ */
+function tryAcquireLock(db, name, owner) {
+    try {
+        db.prepare('INSERT INTO locks (name, owner, acquired_at) VALUES (?, ?, ?)')
+            .run(name, owner, isoNow());
+        return true;
+    }
+    catch (err) {
+        // UNIQUE constraint violation means lock is already held
+        if (err instanceof Error && err.message.includes('UNIQUE constraint failed')) {
+            return false;
+        }
+        throw err;
+    }
+}
+/**
+ * Refresh/heartbeat a lock — update last_heartbeat timestamp.
+ * Per FS-SS-003-0004 VR-005: operations exceeding the stale threshold
+ * must explicitly extend their lock.
+ *
+ * @returns true if the lock was refreshed, false if not found or wrong owner
+ */
+function refreshLock(db, name, owner) {
+    const result = db
+        .prepare('UPDATE locks SET last_heartbeat = ? WHERE name = ? AND owner = ?')
+        .run(isoNow(), name, owner);
+    return result.changes > 0;
+}
+/**
+ * Get information about a lock (if held).
+ */
+function getLockInfo(db, name) {
+    const row = db
+        .prepare('SELECT owner, acquired_at, last_heartbeat FROM locks WHERE name = ?')
+        .get(name);
+    if (!row)
+        return null;
+    return {
+        owner: row.owner,
+        acquiredAt: row.acquired_at,
+        lastHeartbeat: row.last_heartbeat,
+    };
+}
+/**
+ * Acquire an advisory lock with timeout and stale detection.
+ * Implements the retry loop with configurable timeout.
+ *
+ * Per FS-SS-003-0003 VR-008: re-evaluates lock staleness at intervals no
+ * greater than the advisory lock acquisition timeout. The default retry
+ * interval (50ms) is well below the default timeout (5000ms), so each
+ * retry iteration satisfies this bound.
+ *
+ * @throws LockTimeoutError if the lock cannot be acquired within timeoutMs (ERR-LOCK-002)
+ */
+function acquireLock(db, opts) {
+    const { name, owner, timeoutMs = DEFAULT_TIMEOUT_MS, staleMs = DEFAULT_STALE_MS, retryIntervalMs = DEFAULT_RETRY_INTERVAL_MS, } = opts;
+    const startTime = Date.now();
+    const deadline = startTime + timeoutMs;
+    while (true) {
+        // Clear stale locks before each attempt (FS-SS-003-0004 VR-002)
+        clearStaleLocks(db, name, staleMs);
+        // Try to acquire
+        if (tryAcquireLock(db, name, owner)) {
+            return {
+                name,
+                owner,
+                release: () => releaseLock(db, name, owner),
+            };
+        }
+        // Check timeout
+        const elapsed = Date.now() - startTime;
+        if (Date.now() >= deadline) {
+            // Query current lock owner for error reporting (FS-SS-003-0007 VR-002)
+            const info = getLockInfo(db, name);
+            const currentOwner = info?.owner ?? 'unknown';
+            throw new errors_1.LockTimeoutError(name, currentOwner, elapsed);
+        }
+        // Wait before retry
+        const sleepMs = Math.min(retryIntervalMs, deadline - Date.now());
+        if (sleepMs > 0) {
+            // Synchronous busy-wait (Node.js main-thread compatible)
+            const end = Date.now() + sleepMs;
+            while (Date.now() < end) {
+                // busy-wait
+            }
+        }
+    }
+}
+/**
+ * Acquire multiple advisory locks in alphabetical order.
+ * Per FS-SS-003-0003 VR-006/VR-007: locks must be acquired in alphabetical
+ * order by lock name to prevent deadlocks.
+ *
+ * On partial failure (some locks acquired but a later one times out),
+ * all acquired locks are released before the error is thrown.
+ *
+ * @throws LockTimeoutError if any lock cannot be acquired
+ */
+function acquireLocks(db, lockNames, owner, opts) {
+    // Sort alphabetically to prevent deadlocks (VR-006)
+    const sorted = [...lockNames].sort();
+    const acquired = [];
+    try {
+        for (const name of sorted) {
+            const handle = acquireLock(db, { name, owner, ...opts });
+            acquired.push(handle);
+        }
+        return acquired;
+    }
+    catch (err) {
+        // Rollback: release all acquired locks on partial failure
+        for (const handle of acquired) {
+            handle.release();
+        }
+        throw err;
+    }
+}
+/**
+ * Release an advisory lock.
+ * Only the owner can release their own lock.
+ *
+ * @returns true if the lock was released, false if not found or wrong owner
+ */
+function releaseLock(db, name, owner) {
+    const result = db
+        .prepare('DELETE FROM locks WHERE name = ? AND owner = ?')
+        .run(name, owner);
+    return result.changes > 0;
+}
+/**
+ * Force-release a lock regardless of owner.
+ * Use with caution — only for administrative purposes.
+ */
+function forceReleaseLock(db, name) {
+    const result = db
+        .prepare('DELETE FROM locks WHERE name = ?')
+        .run(name);
+    return result.changes > 0;
+}
+/**
+ * Execute a function within a lock context, guaranteeing release in finally.
+ * Per FS-SS-003-0003 VR-003: locks must be released upon operation completion
+ * (success, failure, or exception).
+ *
+ * @param db - Database connection
+ * @param opts - Lock acquisition options
+ * @param fn - Function to execute while holding the lock
+ * @returns The return value of fn
+ * @throws LockTimeoutError if the lock cannot be acquired
+ */
+function withLock(db, opts, fn) {
+    const handle = acquireLock(db, opts);
+    try {
+        return fn();
+    }
+    finally {
+        handle.release();
+    }
+}
+//# sourceMappingURL=locks.js.map

package/dist/db/locks.js.map

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

package/dist/db/migration.d.ts

@@ -0,0 +1,65 @@
+import type Database from 'better-sqlite3';
+/**
+ * Compute SHA-256 checksum of migration SQL content.
+ */
+export declare function computeChecksum(sql: string): string;
+/**
+ * Get the current migration version from the database.
+ * Returns 0 if no migrations have been applied.
+ */
+export declare function getCurrentVersion(db: Database.Database): number;
+/**
+ * Verify schema integrity: all expected tables and indexes exist.
+ * Returns an array of missing table/index names, or empty if all present.
+ */
+export declare function verifySchemaIntegrity(db: Database.Database): string[];
+/**
+ * Verify migration checksums.
+ * By default (verifyAll=false), only checks the latest migration.
+ * With verifyAll=true, checks all applied migrations.
+ *
+ * @throws MigrationChecksumMismatchError on mismatch (ERR-MIG-003)
+ */
+export declare function verifyChecksums(db: Database.Database, verifyAll?: boolean): void;
+/**
+ * Run all pending migrations on the database.
+ * Each migration is applied in a transaction.
+ * After all migrations, a schema integrity check is performed.
+ * Idempotent: if all migrations are already applied, no action is taken.
+ *
+ * @param db - Database connection
+ * @param targetVersion - Optional target version (defaults to latest)
+ * @throws MigrationError if a migration fails (ERR-MIG-001)
+ * @throws MigrationIntegrityError if integrity check fails (ERR-MIG-002)
+ */
+export declare function runMigrations(db: Database.Database, targetVersion?: number): void;
+/**
+ * Initialize the builtin graph schema (relation types + graph_schema metadata).
+ *
+ * Implements AD-0048: Two-pass FK-safe insertion strategy.
+ *
+ * Pass 1: Insert all relation types WITHOUT inverse_of (avoids FK violations
+ * when the referenced inverse type row does not yet exist).
+ * Pass 2: UPDATE each type's inverse_of to its final value.
+ *
+ * Both passes run within a single transaction with FK enforcement active.
+ *
+ * @requires PRAGMA foreign_keys = ON — caller must ensure FK enforcement is enabled
+ *   before invoking this function.
+ */
+export declare function initializeBuiltinSchema(db: Database.Database): void;
+/**
+ * Initialize a fresh database with the full schema.
+ * Also verifies the latest migration checksum on open (VR-006).
+ * Builtin schema is initialized after migrations (FS-SS-008-0007-A).
+ */
+export declare function initializeSchema(db: Database.Database, verifyAll?: boolean, skipBuiltinSchema?: boolean): void;
+/**
+ * Check if the database schema is up to date.
+ */
+export declare function isSchemaUpToDate(db: Database.Database): boolean;
+/**
+ * Get list of pending migration versions.
+ */
+export declare function getPendingMigrations(db: Database.Database): number[];
+//# sourceMappingURL=migration.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/db/migration.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAO3C;;GAEG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,CAY/D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,EAAE,CAyBrE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAE,OAAe,GAAG,IAAI,CAqBvF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CA+DjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAiDnE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAE,OAAe,EAAE,iBAAiB,GAAE,OAAe,GAAG,IAAI,CAY5H;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,OAAO,CAE/D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,GAAG,MAAM,EAAE,CAGpE"}

package/dist/db/migration.js

@@ -0,0 +1,233 @@
+"use strict";
+// Schema migration runner
+// Implements AD-0002: Sequential Versioned Migrations
+// + FS-SS-001-0002 VR-004 (integrity check), VR-006 (checksum verification)
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeChecksum = computeChecksum;
+exports.getCurrentVersion = getCurrentVersion;
+exports.verifySchemaIntegrity = verifySchemaIntegrity;
+exports.verifyChecksums = verifyChecksums;
+exports.runMigrations = runMigrations;
+exports.initializeBuiltinSchema = initializeBuiltinSchema;
+exports.initializeSchema = initializeSchema;
+exports.isSchemaUpToDate = isSchemaUpToDate;
+exports.getPendingMigrations = getPendingMigrations;
+const crypto_1 = require("crypto");
+const schema_1 = require("./schema");
+const schema_types_1 = require("./generated/schema-types");
+const errors_1 = require("../utils/errors");
+const retry_1 = require("./retry");
+/**
+ * Compute SHA-256 checksum of migration SQL content.
+ */
+function computeChecksum(sql) {
+    return (0, crypto_1.createHash)('sha256').update(sql).digest('hex');
+}
+/**
+ * Get the current migration version from the database.
+ * Returns 0 if no migrations have been applied.
+ */
+function getCurrentVersion(db) {
+    // Check if _migrations table exists
+    const tableExists = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='_migrations'")
+        .get();
+    if (!tableExists) {
+        return 0;
+    }
+    const row = db.prepare('SELECT MAX(version) as v FROM _migrations').get();
+    return row?.v ?? 0;
+}
+/**
+ * Verify schema integrity: all expected tables and indexes exist.
+ * Returns an array of missing table/index names, or empty if all present.
+ */
+function verifySchemaIntegrity(db) {
+    const existingTables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all()
+        .map(r => r.name));
+    const existingIndexes = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type='index'").all()
+        .map(r => r.name));
+    const missing = [];
+    for (const table of schema_1.EXPECTED_TABLES) {
+        if (!existingTables.has(table)) {
+            missing.push(`table:${table}`);
+        }
+    }
+    for (const index of schema_1.EXPECTED_INDEXES) {
+        if (!existingIndexes.has(index)) {
+            missing.push(`index:${index}`);
+        }
+    }
+    return missing;
+}
+/**
+ * Verify migration checksums.
+ * By default (verifyAll=false), only checks the latest migration.
+ * With verifyAll=true, checks all applied migrations.
+ *
+ * @throws MigrationChecksumMismatchError on mismatch (ERR-MIG-003)
+ */
+function verifyChecksums(db, verifyAll = false) {
+    const currentVersion = getCurrentVersion(db);
+    if (currentVersion === 0)
+        return;
+    const rows = db
+        .prepare('SELECT version, checksum FROM _migrations ORDER BY version')
+        .all();
+    const versionsToCheck = verifyAll
+        ? rows
+        : rows.filter(r => r.version === currentVersion);
+    for (const row of versionsToCheck) {
+        const migration = schema_1.MIGRATIONS.find(m => m.version === row.version);
+        if (!migration)
+            continue; // Unknown version — can't verify
+        const expected = computeChecksum(migration.sql);
+        if (row.checksum !== expected) {
+            throw new errors_1.MigrationChecksumMismatchError(row.version, expected, row.checksum);
+        }
+    }
+}
+/**
+ * Run all pending migrations on the database.
+ * Each migration is applied in a transaction.
+ * After all migrations, a schema integrity check is performed.
+ * Idempotent: if all migrations are already applied, no action is taken.
+ *
+ * @param db - Database connection
+ * @param targetVersion - Optional target version (defaults to latest)
+ * @throws MigrationError if a migration fails (ERR-MIG-001)
+ * @throws MigrationIntegrityError if integrity check fails (ERR-MIG-002)
+ */
+function runMigrations(db, targetVersion) {
+    const target = targetVersion ?? schema_1.LATEST_VERSION;
+    const current = getCurrentVersion(db);
+    if (current > target) {
+        throw new errors_1.MigrationVersionError(current, [`Database version (${current}) is ahead of target version (${target}). This application version may be outdated.`]);
+    }
+    if (current === target) {
+        return; // Already at target version
+    }
+    const pending = schema_1.MIGRATIONS.filter(m => m.version > current && m.version <= target)
+        .sort((a, b) => a.version - b.version);
+    let lastAppliedVersion = current;
+    // Disable FK enforcement during migrations (needed for DROP COLUMN on FK-referenced columns)
+    const fkWasOn = db.pragma('foreign_keys', { simple: true });
+    if (fkWasOn)
+        db.pragma('foreign_keys = OFF');
+    for (const migration of pending) {
+        const checksum = computeChecksum(migration.sql);
+        const transaction = db.transaction(() => {
+            try {
+                db.exec(migration.sql);
+                db.prepare('INSERT INTO _migrations (version, checksum) VALUES (?, ?)')
+                    .run(migration.version, checksum);
+            }
+            catch (err) {
+                // Allow idempotent migrations: ignore "duplicate column" errors for ALTER TABLE ADD COLUMN
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes('duplicate column name') || msg.includes('no such column')) {
+                    // Column already exists (ADD) or already removed (DROP) — record migration as applied
+                    db.prepare('INSERT INTO _migrations (version, checksum) VALUES (?, ?)')
+                        .run(migration.version, checksum);
+                    return;
+                }
+                throw new errors_1.MigrationError(`Migration v${migration.version} (${migration.description}) failed: ${err instanceof Error ? err.message : String(err)}`, { version: migration.version, description: migration.description, originalError: err });
+            }
+        });
+        transaction();
+        lastAppliedVersion = migration.version;
+    }
+    // Re-enable FK enforcement if it was on
+    if (fkWasOn)
+        db.pragma('foreign_keys = ON');
+    // VR-004: Schema integrity check after all migrations (only when fully migrated)
+    if (lastAppliedVersion >= schema_1.LATEST_VERSION || target >= schema_1.LATEST_VERSION) {
+        const missing = verifySchemaIntegrity(db);
+        if (missing.length > 0) {
+            throw new errors_1.MigrationIntegrityError(lastAppliedVersion, missing);
+        }
+    }
+}
+/**
+ * Initialize the builtin graph schema (relation types + graph_schema metadata).
+ *
+ * Implements AD-0048: Two-pass FK-safe insertion strategy.
+ *
+ * Pass 1: Insert all relation types WITHOUT inverse_of (avoids FK violations
+ * when the referenced inverse type row does not yet exist).
+ * Pass 2: UPDATE each type's inverse_of to its final value.
+ *
+ * Both passes run within a single transaction with FK enforcement active.
+ *
+ * @requires PRAGMA foreign_keys = ON — caller must ensure FK enforcement is enabled
+ *   before invoking this function.
+ */
+function initializeBuiltinSchema(db) {
+    // Defensive check: FK enforcement must be ON for the two-pass strategy to be meaningful
+    const fkState = db.pragma('foreign_keys', { simple: true });
+    if (fkState === 0) {
+        throw new Error('initializeBuiltinSchema requires foreign_keys = ON');
+    }
+    const now = new Date().toISOString();
+    (0, retry_1.withTransaction)(db, () => {
+        // builtin:3.0 (Sprint 31): entity_types table dropped.
+        // Entity types are derived dynamically from documents.type.
+        // No entity type initialization is performed here.
+        // Pass 1: Insert all relation types WITHOUT inverse_of
+        // This avoids FK violations when the inverse type row does not yet exist.
+        for (const rt of schema_types_1.RELATION_TYPES) {
+            db.prepare(`
+        INSERT OR IGNORE INTO relation_types (name, from_types, to_types, cardinality, inverse_of, description, created_at, updated_at)
+        VALUES (?, ?, ?, ?, NULL, ?, ?, ?)
+      `).run(rt.name, JSON.stringify([...rt.from_types]), JSON.stringify([...rt.to_types]), rt.cardinality, rt.description, now, now);
+        }
+        // Pass 2: UPDATE inverse_of for each type that has one
+        for (const rt of schema_types_1.RELATION_TYPES) {
+            if (rt.inverse_of) {
+                db.prepare(`
+          UPDATE relation_types SET inverse_of = ?, updated_at = ?
+          WHERE name = ? AND inverse_of IS NULL
+        `).run(rt.inverse_of, now, rt.name);
+            }
+        }
+        // Record builtin schema source — only if no row exists (preserve YAML bootstrap metadata)
+        const existingMeta = db.prepare('SELECT COUNT(*) as cnt FROM graph_schema').get();
+        if (existingMeta.cnt === 0) {
+            db.prepare(`
+        INSERT INTO graph_schema (source_file, version, bootstrapped_at, checksum)
+        VALUES ('builtin:3.0', 'builtin:3.0', ?, NULL)
+    `).run(now);
+        }
+    });
+}
+/**
+ * Initialize a fresh database with the full schema.
+ * Also verifies the latest migration checksum on open (VR-006).
+ * Builtin schema is initialized after migrations (FS-SS-008-0007-A).
+ */
+function initializeSchema(db, verifyAll = false, skipBuiltinSchema = false) {
+    // Verify existing checksums before running migrations
+    const currentVersion = getCurrentVersion(db);
+    if (currentVersion > 0) {
+        verifyChecksums(db, verifyAll);
+    }
+    runMigrations(db);
+    // FS-SS-008-0007-A: Initialize builtin graph schema
+    if (!skipBuiltinSchema) {
+        initializeBuiltinSchema(db);
+    }
+}
+/**
+ * Check if the database schema is up to date.
+ */
+function isSchemaUpToDate(db) {
+    return getCurrentVersion(db) >= schema_1.LATEST_VERSION;
+}
+/**
+ * Get list of pending migration versions.
+ */
+function getPendingMigrations(db) {
+    const current = getCurrentVersion(db);
+    return schema_1.MIGRATIONS.filter(m => m.version > current).map(m => m.version);
+}
+//# sourceMappingURL=migration.js.map

package/dist/db/migration.js.map

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

package/dist/db/retry.d.ts

@@ -0,0 +1,26 @@
+import type Database from 'better-sqlite3';
+export interface RetryOptions {
+    /** Maximum number of retries (default: 5) */
+    maxRetries?: number;
+    /** Base delay in ms for exponential backoff (default: 50) */
+    baseMs?: number;
+    /** Maximum delay in ms for exponential backoff (default: 1000) */
+    maxMs?: number;
+    /** Maximum total wait time in ms across all retries (default: 30000) */
+    maxTotalWaitMs?: number;
+}
+/**
+ * Execute a function with retry on SQLITE_BUSY using exponential backoff.
+ * Each retry doubles the delay, capped at maxMs.
+ * Total wait time is capped by maxTotalWaitMs per FS-SS-003-0005 VR-007.
+ *
+ * @param fn - The function to execute (typically a DB write operation)
+ * @param options - Retry configuration
+ * @throws DatabaseBusyError (ERR-LOCK-001) if all retries are exhausted
+ */
+export declare function withRetry<T>(fn: () => T, options?: RetryOptions): T;
+/**
+ * Execute a database operation within a transaction with retry on busy.
+ */
+export declare function withTransaction<T>(db: Database.Database, fn: () => T, options?: RetryOptions): T;
+//# sourceMappingURL=retry.d.ts.map