agentdb 3.0.0-alpha.9 → 3.1.0

package/dist/src/db-fallback.js

@@ -1,68 +1,270 @@
 /**
- * Database System using sql.js (WASM SQLite)
- * Pure JavaScript implementation with NO build dependencies
+ * Database System backed by SQLite.
+ *
+ * Resolution order (ruflo #2235 A):
+ *   1. **better-sqlite3** if the optional peer is loadable — native, faster,
+ *      what most callers actually want when they install the native module.
+ *   2. **sql.js** (WASM) — pure-JS fallback, requires no build tools.
+ *
+ * Both implementations expose the same `db.prepare(sql).run/get/all(...)`
+ * interface (the sql.js wrapper below was designed to mimic better-sqlite3),
+ * so callers don't care which one served them.
  *
  * SECURITY: Fixed SQL injection vulnerabilities:
  * - PRAGMA commands validated against whitelist
  * - Removed eval() usage (replaced with async import)
  */
 import { validatePragmaCommand, ValidationError } from './security/input-validation.js';
+import { createHash, randomUUID } from 'node:crypto';
 import * as fs from 'fs';
 import * as path from 'path';
-let sqlJsWrapper = null;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- cached impl (better-sqlite3 class or sql.js wrapper class)
+let cachedImpl = null;
+let cachedImplKind = null;
+export class SqlJsConcurrentModificationError extends Error {
+    code = 'AGENTDB_SQLJS_CONCURRENT_MODIFICATION';
+    constructor(filename) {
+        super(`Refusing to overwrite "${filename}" because it changed after this sql.js instance opened. ` +
+            'Another process may have written to the database; reopen it before retrying.');
+        this.name = 'SqlJsConcurrentModificationError';
+    }
+}
+function fingerprintFile(filename) {
+    let fd;
+    try {
+        fd = fs.openSync(filename, 'r');
+        const before = fs.fstatSync(fd);
+        const data = fs.readFileSync(fd);
+        const after = fs.fstatSync(fd);
+        if (before.dev !== after.dev ||
+            before.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeMs !== after.mtimeMs ||
+            before.ctimeMs !== after.ctimeMs) {
+            throw new SqlJsConcurrentModificationError(filename);
+        }
+        return {
+            exists: true,
+            device: after.dev,
+            inode: after.ino,
+            mode: after.mode,
+            size: after.size,
+            mtimeMs: after.mtimeMs,
+            ctimeMs: after.ctimeMs,
+            sha256: createHash('sha256').update(data).digest('hex'),
+        };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { exists: false };
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+export function captureDatabaseFileState(filename) {
+    return {
+        database: fingerprintFile(filename),
+        wal: fingerprintFile(`${filename}-wal`),
+        shm: fingerprintFile(`${filename}-shm`),
+        journal: fingerprintFile(`${filename}-journal`),
+    };
+}
+export function loadSqlJsDatabaseFile(filename) {
+    const state = captureDatabaseFileState(filename);
+    if ((state.wal.exists && state.wal.size > 0) ||
+        (state.journal.exists && state.journal.size > 0)) {
+        throw new Error(`Refusing to open "${filename}" with sql.js while an active SQLite WAL or journal exists. ` +
+            'Checkpoint/close the other SQLite writer first.');
+    }
+    if (!state.database.exists)
+        return { data: null, state };
+    // fingerprintFile hashes the exact bytes read from a stable descriptor.
+    // Read once more and verify the digest so the returned bytes and baseline
+    // are guaranteed to describe the same database generation.
+    const data = fs.readFileSync(filename);
+    const digest = createHash('sha256').update(data).digest('hex');
+    if (digest !== state.database.sha256) {
+        throw new SqlJsConcurrentModificationError(filename);
+    }
+    if (data.length < 16 ||
+        data.subarray(0, 16).toString('utf8') !== 'SQLite format 3\u0000') {
+        throw new Error(`Refusing to open invalid SQLite database file "${filename}"`);
+    }
+    return { data: new Uint8Array(data), state };
+}
+function sameDatabaseFileState(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function fsyncDirectory(directory) {
+    let fd;
+    try {
+        fd = fs.openSync(directory, 'r');
+        fs.fsyncSync(fd);
+    }
+    catch (error) {
+        // Some platforms/filesystems do not permit opening or syncing directories.
+        const code = error.code;
+        if (code !== 'EINVAL' && code !== 'EPERM' && code !== 'EISDIR')
+            throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+export function persistSqlJsDatabase(filename, data, expectedState) {
+    const directory = path.dirname(filename);
+    fs.mkdirSync(directory, { recursive: true });
+    if (fs.existsSync(filename) && fs.lstatSync(filename).isSymbolicLink()) {
+        throw new Error(`Refusing to replace symbolic-link database path "${filename}"`);
+    }
+    const lockPath = `${filename}.agentdb.lock`;
+    let lockFd;
+    let tempPath;
+    try {
+        try {
+            lockFd = fs.openSync(lockPath, 'wx', 0o600);
+            fs.writeSync(lockFd, `${process.pid}\n`);
+            fs.fsyncSync(lockFd);
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                throw new SqlJsConcurrentModificationError(filename);
+            }
+            throw error;
+        }
+        if (!sameDatabaseFileState(captureDatabaseFileState(filename), expectedState)) {
+            throw new SqlJsConcurrentModificationError(filename);
+        }
+        tempPath = path.join(directory, `.${path.basename(filename)}.${process.pid}.${randomUUID()}.tmp`);
+        const tempFd = fs.openSync(tempPath, 'wx', 0o600);
+        try {
+            fs.writeFileSync(tempFd, Buffer.from(data));
+            if (expectedState.database.exists && expectedState.database.mode !== undefined) {
+                fs.fchmodSync(tempFd, expectedState.database.mode);
+            }
+            fs.fsyncSync(tempFd);
+        }
+        finally {
+            fs.closeSync(tempFd);
+        }
+        // Recheck after export/write so a non-cooperating SQLite writer cannot be
+        // silently overwritten merely because it raced with the temporary write.
+        if (!sameDatabaseFileState(captureDatabaseFileState(filename), expectedState)) {
+            throw new SqlJsConcurrentModificationError(filename);
+        }
+        fs.renameSync(tempPath, filename);
+        tempPath = undefined;
+        fsyncDirectory(directory);
+        return captureDatabaseFileState(filename);
+    }
+    finally {
+        if (tempPath) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* best-effort cleanup */ }
+        }
+        if (lockFd !== undefined) {
+            fs.closeSync(lockFd);
+            try {
+                fs.unlinkSync(lockPath);
+            }
+            catch { /* preserve the original error */ }
+        }
+    }
+}
 /**
- * Get sql.js database implementation (ONLY sql.js, no better-sqlite3)
+ * Get the SQLite database implementation. Prefers native `better-sqlite3`
+ * when loadable; falls back to WASM `sql.js` (no build tools required).
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- returns dynamically constructed class
 export async function getDatabaseImplementation() {
-    // Return cached wrapper
-    if (sqlJsWrapper) {
-        return sqlJsWrapper;
+    if (cachedImpl)
+        return cachedImpl;
+    // 1. Try native better-sqlite3 (optional peer; same prepare/run API).
+    if (!process.env.AGENTDB_FORCE_SQLJS) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- dynamic optional import
+            const mod = await import('better-sqlite3');
+            const BetterSqlite3 = mod.default ?? mod;
+            if (typeof BetterSqlite3 === 'function') {
+                // Importing the JS wrapper can succeed even when its native binding is
+                // missing or incompatible with the current Node ABI. Probe an actual
+                // in-memory connection before selecting it.
+                const probe = new BetterSqlite3(':memory:');
+                probe.close();
+                cachedImpl = BetterSqlite3;
+                cachedImplKind = 'better-sqlite3';
+                console.error('✅ Using native better-sqlite3');
+                return cachedImpl;
+            }
+        }
+        catch {
+            // Not installed or failed to load → fall through to sql.js.
+        }
     }
+    // 2. Fall back to sql.js (WASM, no build tools).
     try {
-        console.log('✅ Using sql.js (WASM SQLite, no build tools required)');
+        console.error('✅ Using sql.js (WASM SQLite, no build tools required)');
         // sql.js requires async initialization
         const mod = await import('sql.js');
         const SQL = await mod.default();
-        // Create database wrapper
-        sqlJsWrapper = createSqlJsWrapper(SQL);
-        return sqlJsWrapper;
+        cachedImpl = createSqlJsWrapper(SQL);
+        cachedImplKind = 'sql.js';
+        return cachedImpl;
     }
     catch (error) {
         console.error('❌ Failed to initialize sql.js:', error.message);
-        throw new Error('Failed to initialize SQLite. Please ensure sql.js is installed:\n' +
-            'npm install sql.js');
+        throw new Error('Failed to initialize SQLite. Install one of:\n' +
+            '  npm install better-sqlite3  # native, faster (recommended)\n' +
+            '  npm install sql.js          # pure-JS fallback, no build tools');
     }
 }
+/** Reset the cached implementation (intended for tests). */
+export function _resetDatabaseImplementationForTests() {
+    cachedImpl = null;
+    cachedImplKind = null;
+}
 /**
  * Create a better-sqlite3 compatible wrapper around sql.js
  * This allows AgentDB to work (with reduced performance) without native compilation
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js SQL factory type
 function createSqlJsWrapper(SQL) {
     return class SqlJsDatabase {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js Database instance
         db;
         filename;
+        fileState;
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js Statement instances
         activeStatements = new Map();
+        // Cache wrappers by SQL text so repeated db.prepare(sameSql) returns the
+        // same underlying sql.js Statement and doesn't add a new entry to
+        // activeStatements. Without this, callers using the
+        // db.prepare(sql).run(...)-and-discard pattern (idiomatic in
+        // better-sqlite3, where V8 GCs the handle) leak forever under sql.js.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- prepared-statement wrapper objects
+        statementCache = new Map();
         statementCounter = 0;
         intervalId = null;
-        constructor(filename, options) {
+        constructor(filename, _options) {
             this.filename = filename;
+            const loaded = filename === ':memory:' ? null : loadSqlJsDatabaseFile(filename);
+            this.fileState = loaded?.state ?? null;
             // In-memory database
             if (filename === ':memory:') {
                 this.db = new SQL.Database();
             }
             else {
                 // File-based database - use safe fs module (no eval)
-                try {
-                    if (fs.existsSync(filename)) {
-                        const buffer = fs.readFileSync(filename);
-                        this.db = new SQL.Database(buffer);
-                    }
-                    else {
-                        this.db = new SQL.Database();
-                    }
+                if (loaded.data) {
+                    this.db = new SQL.Database(loaded.data);
                 }
-                catch (error) {
-                    console.warn('⚠️  Could not read database file:', error.message);
+                else {
                     this.db = new SQL.Database();
                 }
             }
@@ -72,19 +274,54 @@ function createSqlJsWrapper(SQL) {
                     console.warn(`⚠️  Detected ${this.activeStatements.size} active SQL statements - possible memory leak`);
                 }
             }, 10000);
+            // Diagnostic only: must not keep a process alive that never calls close()
+            this.intervalId.unref?.();
         }
         prepare(sql) {
-            const stmt = this.db.prepare(sql);
+            // Reuse the cached wrapper for an identical SQL string. The cache owns
+            // the underlying stmt's lifetime; finalize() is a no-op on a cached
+            // wrapper so concurrent callers that all called prepare(sql) keep
+            // working. close() drops everything.
+            const cached = this.statementCache.get(sql);
+            if (cached)
+                return cached;
+            let stmt = this.db.prepare(sql);
             let isFinalized = false;
             const stmtId = ++this.statementCounter;
+            const self = this;
+            // sql.js frees every prepared statement on export() (save(), or another
+            // wrapper of the same database), after which bind() throws the string
+            // "Statement closed". Re-prepare once instead of failing the call.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
+            const bindLive = (params) => {
+                try {
+                    stmt.bind(params);
+                }
+                catch (error) {
+                    if (error !== SQLJS_STATEMENT_CLOSED)
+                        throw error;
+                    stmt = self.db.prepare(sql);
+                    self.activeStatements.set(stmtId, stmt);
+                    stmt.bind(params);
+                }
+            };
             // Track active statement
             this.activeStatements.set(stmtId, stmt);
-            return {
+            const evictOnError = () => {
+                if (!isFinalized) {
+                    stmt.free();
+                    isFinalized = true;
+                    self.activeStatements.delete(stmtId);
+                    self.statementCache.delete(sql);
+                }
+            };
+            const wrapper = {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
                 run: (...params) => {
                     if (isFinalized)
                         throw new Error('Statement already finalized');
                     try {
-                        stmt.bind(params);
+                        bindLive(params);
                         stmt.step();
                         stmt.reset();
                         return {
@@ -93,20 +330,16 @@ function createSqlJsWrapper(SQL) {
                         };
                     }
                     catch (error) {
-                        // Auto-free on error to prevent memory leak
-                        if (!isFinalized) {
-                            stmt.free();
-                            isFinalized = true;
-                            this.activeStatements.delete(stmtId);
-                        }
+                        evictOnError();
                         throw error;
                     }
                 },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
                 get: (...params) => {
                     if (isFinalized)
                         throw new Error('Statement already finalized');
                     try {
-                        stmt.bind(params);
+                        bindLive(params);
                         const hasRow = stmt.step();
                         if (!hasRow) {
                             stmt.reset();
@@ -122,51 +355,45 @@ function createSqlJsWrapper(SQL) {
                         return result;
                     }
                     catch (error) {
-                        // Auto-free on error to prevent memory leak
-                        if (!isFinalized) {
-                            stmt.free();
-                            isFinalized = true;
-                            this.activeStatements.delete(stmtId);
-                        }
+                        evictOnError();
                         throw error;
                     }
                 },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
                 all: (...params) => {
                     if (isFinalized)
                         throw new Error('Statement already finalized');
                     try {
-                        stmt.bind(params);
+                        bindLive(params);
                         const results = [];
+                        // Column names are fixed for one execution; read them once, not per row
+                        let columns = null;
                         while (stmt.step()) {
-                            const columns = stmt.getColumnNames();
+                            if (!columns)
+                                columns = stmt.getColumnNames();
                             const values = stmt.get();
                             const result = {};
-                            columns.forEach((col, idx) => {
-                                result[col] = values[idx];
-                            });
+                            for (let idx = 0; idx < columns.length; idx++) {
+                                result[columns[idx]] = values[idx];
+                            }
                             results.push(result);
                         }
                         stmt.reset();
                         return results;
                     }
                     catch (error) {
-                        // Auto-free on error to prevent memory leak
-                        if (!isFinalized) {
-                            stmt.free();
-                            isFinalized = true;
-                            this.activeStatements.delete(stmtId);
-                        }
+                        evictOnError();
                         throw error;
                     }
                 },
                 finalize: () => {
-                    if (!isFinalized) {
-                        stmt.free();
-                        isFinalized = true;
-                        this.activeStatements.delete(stmtId);
-                    }
+                    // No-op while cached: the wrapper is shared and finalize() must not
+                    // tear out a stmt another caller is about to use. close() handles
+                    // the real teardown.
                 }
             };
+            this.statementCache.set(sql, wrapper);
+            return wrapper;
         }
         exec(sql) {
             return this.db.exec(sql);
@@ -175,13 +402,8 @@ function createSqlJsWrapper(SQL) {
             // Save to file if needed
             if (this.filename !== ':memory:') {
                 try {
-                    // Create parent directories if they don't exist
-                    const dir = path.dirname(this.filename);
-                    if (!fs.existsSync(dir)) {
-                        fs.mkdirSync(dir, { recursive: true });
-                    }
                     const data = this.db.export();
-                    fs.writeFileSync(this.filename, Buffer.from(data));
+                    this.fileState = persistSqlJsDatabase(this.filename, data, this.fileState);
                 }
                 catch (error) {
                     console.error('❌ Could not save database to file:', error.message);
@@ -190,32 +412,38 @@ function createSqlJsWrapper(SQL) {
             }
         }
         close() {
+            let saveError;
+            try {
+                this.save();
+            }
+            catch (error) {
+                saveError = error;
+            }
             // Clear interval timer
             if (this.intervalId) {
                 clearInterval(this.intervalId);
                 this.intervalId = null;
             }
             // Free all active statements to prevent memory leaks
-            for (const [stmtId, stmt] of this.activeStatements.entries()) {
+            for (const [, stmt] of this.activeStatements.entries()) {
                 try {
                     stmt.free();
                 }
-                catch (e) {
+                catch {
                     // Statement may already be freed
                 }
             }
             this.activeStatements.clear();
-            // Save to file before closing
-            this.save();
+            this.statementCache.clear();
             this.db.close();
+            if (saveError)
+                throw saveError;
         }
-        pragma(pragma, options) {
+        pragma(pragma, _options) {
             try {
                 // SECURITY: Validate PRAGMA command against whitelist to prevent SQL injection
                 const validatedPragma = validatePragmaCommand(pragma);
-                // Execute validated PRAGMA
-                const result = this.db.exec(`PRAGMA ${validatedPragma}`);
-                return result[0]?.values[0]?.[0];
+                return runPragma(this.db, validatedPragma);
             }
             catch (error) {
                 if (error instanceof ValidationError) {
@@ -243,22 +471,244 @@ function createSqlJsWrapper(SQL) {
         }
     };
 }
+/** What sql.js throws (a string, not an Error) when using a freed statement */
+export const SQLJS_STATEMENT_CLOSED = 'Statement closed';
+/**
+ * Run one validated PRAGMA as a single prepared statement (exec() would run
+ * any stacked statements). table_info(...) returns its rows, like
+ * better-sqlite3; other pragmas return the first value.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js raw database
+function runPragma(rawDb, validatedPragma) {
+    const stmt = rawDb.prepare(`PRAGMA ${validatedPragma}`);
+    try {
+        if (/^table_info\(/i.test(validatedPragma)) {
+            const rows = [];
+            while (stmt.step())
+                rows.push(stmt.getAsObject());
+            return rows;
+        }
+        return stmt.step() ? stmt.get()[0] : undefined;
+    }
+    finally {
+        stmt.free();
+    }
+}
 /**
  * Create a database instance using sql.js
  */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- returns dynamically constructed SqlJsDatabase
 export async function createDatabase(filename, options) {
     const DatabaseImpl = await getDatabaseImplementation();
     return new DatabaseImpl(filename, options);
 }
+/**
+ * Wrap an EXISTING sql.js raw database with the better-sqlite3-compatible API.
+ * Used by AgentDB unified mode to share one sql.js Database instance for both
+ * vector (rvf) and relational tables in a single .rvf file.
+ *
+ * Unlike createDatabase(), this does NOT create a new SQL.Database — it wraps
+ * the one already held by SqlJsRvfBackend.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js raw database and returned wrapper
+export function wrapExistingSqlJsDatabase(rawDb, filename = ':memory:') {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js Statement instances
+    const activeStatements = new Map();
+    // SQL-text cache; see SqlJsDatabase.statementCache for rationale.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- prepared-statement wrapper objects
+    const statementCache = new Map();
+    let statementCounter = 0;
+    const loaded = filename === ':memory:' ? null : loadSqlJsDatabaseFile(filename);
+    let fileState = loaded?.state ?? null;
+    if (loaded?.data) {
+        const rawDigest = createHash('sha256').update(rawDb.export()).digest('hex');
+        if (rawDigest !== fileState.database.sha256) {
+            throw new SqlJsConcurrentModificationError(filename);
+        }
+    }
+    return {
+        prepare(sql) {
+            const cached = statementCache.get(sql);
+            if (cached)
+                return cached;
+            let stmt = rawDb.prepare(sql);
+            let isFinalized = false;
+            const stmtId = ++statementCounter;
+            activeStatements.set(stmtId, stmt);
+            // See SqlJsDatabase.prepare: re-prepare after sql.js freed the statement
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
+            const bindLive = (params) => {
+                try {
+                    stmt.bind(params);
+                }
+                catch (error) {
+                    if (error !== SQLJS_STATEMENT_CLOSED)
+                        throw error;
+                    stmt = rawDb.prepare(sql);
+                    activeStatements.set(stmtId, stmt);
+                    stmt.bind(params);
+                }
+            };
+            const evictOnError = () => {
+                if (!isFinalized) {
+                    stmt.free();
+                    isFinalized = true;
+                    activeStatements.delete(stmtId);
+                    statementCache.delete(sql);
+                }
+            };
+            const wrapper = {
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
+                run(...params) {
+                    if (isFinalized)
+                        throw new Error('Statement already finalized');
+                    try {
+                        bindLive(params);
+                        stmt.step();
+                        stmt.reset();
+                        return {
+                            changes: rawDb.getRowsModified(),
+                            lastInsertRowid: rawDb.exec('SELECT last_insert_rowid()')[0]?.values[0]?.[0] || 0,
+                        };
+                    }
+                    catch (error) {
+                        evictOnError();
+                        throw error;
+                    }
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
+                get(...params) {
+                    if (isFinalized)
+                        throw new Error('Statement already finalized');
+                    try {
+                        bindLive(params);
+                        const hasRow = stmt.step();
+                        if (!hasRow) {
+                            stmt.reset();
+                            return undefined;
+                        }
+                        const columns = stmt.getColumnNames();
+                        const values = stmt.get();
+                        stmt.reset();
+                        const result = {};
+                        columns.forEach((col, idx) => { result[col] = values[idx]; });
+                        return result;
+                    }
+                    catch (error) {
+                        evictOnError();
+                        throw error;
+                    }
+                },
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any -- sql.js bind accepts heterogeneous params
+                all(...params) {
+                    if (isFinalized)
+                        throw new Error('Statement already finalized');
+                    try {
+                        bindLive(params);
+                        const results = [];
+                        // Column names are fixed for one execution; read them once, not per row
+                        let columns = null;
+                        while (stmt.step()) {
+                            if (!columns)
+                                columns = stmt.getColumnNames();
+                            const values = stmt.get();
+                            const result = {};
+                            for (let idx = 0; idx < columns.length; idx++)
+                                result[columns[idx]] = values[idx];
+                            results.push(result);
+                        }
+                        stmt.reset();
+                        return results;
+                    }
+                    catch (error) {
+                        evictOnError();
+                        throw error;
+                    }
+                },
+                finalize() {
+                    // No-op while cached; close() handles teardown.
+                },
+            };
+            statementCache.set(sql, wrapper);
+            return wrapper;
+        },
+        exec(sql) {
+            return rawDb.exec(sql);
+        },
+        save() {
+            if (filename !== ':memory:') {
+                const data = rawDb.export();
+                fileState = persistSqlJsDatabase(filename, data, fileState);
+            }
+        },
+        close() {
+            let saveError;
+            try {
+                this.save();
+            }
+            catch (error) {
+                saveError = error;
+            }
+            for (const [, stmt] of activeStatements.entries()) {
+                try {
+                    stmt.free();
+                }
+                catch { /* already freed */ }
+            }
+            activeStatements.clear();
+            statementCache.clear();
+            rawDb.close();
+            if (saveError)
+                throw saveError;
+        },
+        pragma(pragma, _options) {
+            try {
+                const validatedPragma = validatePragmaCommand(pragma);
+                return runPragma(rawDb, validatedPragma);
+            }
+            catch (error) {
+                if (error instanceof ValidationError) {
+                    console.error(`Invalid PRAGMA command: ${error.message}`);
+                    throw error;
+                }
+                throw error;
+            }
+        },
+        transaction(fn) {
+            return () => {
+                try {
+                    rawDb.exec('BEGIN TRANSACTION');
+                    const result = fn();
+                    rawDb.exec('COMMIT');
+                    return result;
+                }
+                catch (error) {
+                    rawDb.exec('ROLLBACK');
+                    throw error;
+                }
+            };
+        },
+    };
+}
 /**
  * Get information about current database implementation
  */
 export function getDatabaseInfo() {
+    // Reports the currently-loaded backend; falls back to the sql.js description
+    // before getDatabaseImplementation() has run.
+    if (cachedImplKind === 'better-sqlite3') {
+        return {
+            implementation: 'better-sqlite3 (native)',
+            isNative: true,
+            performance: 'high',
+            requiresBuildTools: true,
+        };
+    }
     return {
         implementation: 'sql.js (WASM)',
         isNative: false,
         performance: 'medium',
-        requiresBuildTools: false
+        requiresBuildTools: false,
     };
 }
 //# sourceMappingURL=db-fallback.js.map