noormme 1.2.6 → 1.2.7

package/dist/cjs/agentic/Cortex.js

@@ -133,18 +133,22 @@ class Cortex {
         this.executionLock = true;
         console.log('[Cortex] Initiating Autonomous Soul-Searching Loop v2 (Deep Hardening Pass)...');
         try {
+            // Phase 1: System Health & Diagnostic (Strict Transaction)
             await this.db.transaction().execute(async (trx) => {
-                // 1. Audit health & Run self-tests
                 await this.#runIsolated('Audit', () => this.governor.performAudit(trx));
                 await this.#runIsolated('Self-Tests', () => this.tests.runAllProbes(trx));
-                // 2. Run background rituals (optimization, compression)
-                await this.#runIsolated('Rituals', () => this.rituals.runPendingRituals(trx));
-                // 3. Learn from actions & Prune dead data
+            });
+            // Phase 2: Autonomous Rituals (Individual Transactional Isolation)
+            // We run these outside the main transaction to prevent long-running ritual locks
+            // from blocking the entire database.
+            await this.#runIsolated('Rituals', () => this.rituals.runPendingRituals());
+            // Phase 3: Background Maintenance (Unified Maintenance Transaction)
+            await this.db.transaction().execute(async (trx) => {
                 await this.#runIsolated('Action Refinement', () => this.refiner.refineActions(trx));
                 await this.#runIsolated('Zombie Pruning', () => this.ablation.pruneZombies(30, trx));
                 await this.#runIsolated('Ablation Monitoring', () => this.ablation.monitorAblationPerformance(trx));
             });
-            // These are often long-running or have their own internal transaction boundaries
+            // Phase 4: Long-Running Evolutionary Cycles (Internal transaction boundaries)
             await this.#runIsolated('Strategy Mutation', () => this.strategy.mutateStrategy());
             await this.#runIsolated('Evolution Pulse', () => this.evolutionRitual.execute());
             await this.#runIsolated('Knowledge Broadcast', () => this.hive.broadcastKnowledge());

package/dist/cjs/agentic/improvement/RitualOrchestrator.d.ts

@@ -16,7 +16,8 @@ export declare class RitualOrchestrator {
      */
     scheduleRitual(name: string, type: AgentRitual['type'], frequency: AgentRitual['frequency'], definition?: string, metadata?: Record<string, any>): Promise<AgentRitual>;
     /**
-     * Run all pending rituals that are due
+     * Run all pending rituals that are due.
+     * PRODUCTION HARDENING: Separate Discovery/Locking from Execution to minimize lock duration.
      */
     runPendingRituals(trxOrDb?: any): Promise<number>;
     /**

package/dist/cjs/agentic/improvement/RitualOrchestrator.js

@@ -37,7 +37,8 @@ class RitualOrchestrator {
         return this.parseRitual(ritual);
     }
     /**
-     * Run all pending rituals that are due
+     * Run all pending rituals that are due.
+     * PRODUCTION HARDENING: Separate Discovery/Locking from Execution to minimize lock duration.
      */
     async runPendingRituals(trxOrDb = this.db) {
         const now = new Date();
@@ -56,7 +57,7 @@ class RitualOrchestrator {
             if (due.length === 0)
                 return [];
             for (const ritual of due) {
-                // Production Hardening: Distributed Lock
+                // Distributed Lock to prevent other nodes/instances from picking this up
                 await trx
                     .updateTable(this.ritualsTable)
                     .set({ locked_until: lockTimeout })
@@ -65,15 +66,18 @@ class RitualOrchestrator {
             }
             return due;
         };
+        // DISCOVERY PHASE: Short transaction to find and lock pending work
         const pending = (trxOrDb !== this.db)
             ? await runner(trxOrDb)
             : await this.db.transaction().execute(runner);
         if (pending.length === 0)
             return 0;
-        console.log(`[RitualOrchestrator] Found ${pending.length} pending rituals due. Locking for execution...`);
+        console.log(`[RitualOrchestrator] Found ${pending.length} pending rituals due. Executing in isolation...`);
+        // EXECUTION PHASE: Run rituals outside the discovery transaction.
+        // Each ritual will handle its own internal DB calls / transactions.
         for (const ritual of pending) {
-            // Execute with the same trxOrDb context
-            await this.executeRitual(ritual, trxOrDb);
+            // Use this.db directly to ensure we don't hold the parent transaction lock
+            await this.executeRitual(ritual, this.db);
         }
         return pending.length;
     }

package/dist/cjs/dialect/sqlite/sqlite-auto-optimizer.d.ts

@@ -1,16 +1,17 @@
 import type { Kysely } from '../../kysely.js';
 import { Logger } from '../../logging/logger.js';
 export interface SQLiteOptimizationConfig {
-    enableAutoPragma: boolean;
-    enableAutoIndexing: boolean;
-    enablePerformanceTuning: boolean;
-    enableBackupRecommendations: boolean;
-    slowQueryThreshold: number;
-    autoVacuumMode: 'NONE' | 'FULL' | 'INCREMENTAL';
-    journalMode: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
-    synchronous: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
-    cacheSize: number;
-    tempStore: 'DEFAULT' | 'FILE' | 'MEMORY';
+    enableAutoPragma?: boolean;
+    enableAutoIndexing?: boolean;
+    enablePerformanceTuning?: boolean;
+    enableBackupRecommendations?: boolean;
+    slowQueryThreshold?: number;
+    autoVacuumMode?: 'NONE' | 'FULL' | 'INCREMENTAL';
+    journalMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+    busyTimeout?: number;
+    cacheSize?: number;
+    tempStore?: 'DEFAULT' | 'FILE' | 'MEMORY';
 }
 export interface SQLiteOptimizationResult {
     appliedOptimizations: string[];
@@ -46,7 +47,7 @@ export declare class SQLiteAutoOptimizer {
     /**
      * Get default optimization configuration
      */
-    getDefaultConfig(): SQLiteOptimizationConfig;
+    getDefaultConfig(): Required<SQLiteOptimizationConfig>;
     /**
      * Analyze current SQLite configuration and performance
      */

package/dist/cjs/dialect/sqlite/sqlite-auto-optimizer.js

@@ -32,6 +32,7 @@ class SQLiteAutoOptimizer {
             autoVacuumMode: 'INCREMENTAL',
             journalMode: 'WAL',
             synchronous: 'NORMAL',
+            busyTimeout: 5000,
             cacheSize: -64000, // 64MB cache
             tempStore: 'MEMORY',
         };
@@ -83,7 +84,7 @@ class SQLiteAutoOptimizer {
     /**
      * Apply automatic optimizations based on configuration
      */
-    async optimizeDatabase(db, config = this.getDefaultConfig()) {
+    async optimizeDatabase(db, config) {
         const result = {
             appliedOptimizations: [],
             recommendations: [],
@@ -91,15 +92,17 @@ class SQLiteAutoOptimizer {
             warnings: [],
         };
         try {
+            // Merge provided config with defaults
+            const finalConfig = { ...this.getDefaultConfig(), ...config };
             // Analyze current state
             const metrics = await this.analyzeDatabase(db);
             // Apply pragma optimizations
-            if (config.enableAutoPragma) {
-                await this.applyPragmaOptimizations(db, config, metrics, result);
+            if (finalConfig.enableAutoPragma) {
+                await this.applyPragmaOptimizations(db, finalConfig, metrics, result);
             }
             // Apply performance tuning
-            if (config.enablePerformanceTuning) {
-                await this.applyPerformanceTuning(db, config, metrics, result);
+            if (finalConfig.enablePerformanceTuning) {
+                await this.applyPerformanceTuning(db, finalConfig, metrics, result);
             }
             // Generate recommendations
             await this.generateRecommendations(db, metrics, result);
@@ -179,6 +182,17 @@ class SQLiteAutoOptimizer {
                 result.warnings.push('Failed to set temp store');
             }
         }
+        // Set busy timeout
+        if (config.busyTimeout) {
+            try {
+                await (0, sql_js_1.sql) `PRAGMA busy_timeout = ${sql_js_1.sql.lit(config.busyTimeout)}`.execute(db);
+                optimizations.push(`Set busy timeout to ${config.busyTimeout}ms`);
+                result.performanceImpact = 'low';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set busy timeout');
+            }
+        }
         result.appliedOptimizations.push(...optimizations);
     }
     /**

package/dist/cjs/dialect/sqlite/sqlite-dialect-config.d.ts

@@ -11,6 +11,12 @@ export interface SqliteDialectConfig {
      * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
      */
     database: SqliteDatabase | (() => Promise<SqliteDatabase>);
+    /**
+     * Maximum number of concurrent connections to the database.
+     * Requires `database` to be a factory function `() => Promise<SqliteDatabase>`.
+     * Defaults to 1.
+     */
+    poolSize?: number;
     /**
      * Called once when the first query is executed.
      *

package/dist/cjs/dialect/sqlite/sqlite-driver.d.ts

@@ -34,7 +34,7 @@ export declare class SqliteDriver implements Driver {
     /**
      * Releases a connection back to the pool.
      */
-    releaseConnection(): Promise<void>;
+    releaseConnection(connection: DatabaseConnection): Promise<void>;
     /**
      * Destroys the driver and releases all resources.
      */

package/dist/cjs/dialect/sqlite/sqlite-driver.js

@@ -5,40 +5,103 @@ const savepoint_parser_js_1 = require("../../parser/savepoint-parser.js");
 const compiled_query_js_1 = require("../../query-compiler/compiled-query.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
 const query_id_js_1 = require("../../util/query-id.js");
+// Global WriteMutex registry.
+// This serializes all writes to a specific SQLite file across multiple connections
+// in the SAME Node.js process, preventing synchronous C-level event loop blocking.
+const globalWriteMutexRegistry = new Map();
 class SqliteDriver {
     #config;
-    #connectionMutex = new ConnectionMutex();
-    #db;
-    #connection;
+    #writeMutex;
+    #dbPath;
+    #connections = [];
+    #freeConnections = [];
+    #waiters = [];
+    #initialized = false;
     constructor(config) {
         this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     async init() {
-        this.#db = (0, object_utils_js_1.isFunction)(this.#config.database)
+        const poolSize = this.#config.poolSize || 1;
+        // Retrieve database name/path (fallback to memory if not accessible)
+        // We instantiate the first DB to get the path before building the pool
+        const firstDb = (0, object_utils_js_1.isFunction)(this.#config.database)
             ? await this.#config.database()
             : this.#config.database;
-        this.#connection = new SqliteConnection(this.#db);
+        this.#dbPath = firstDb.name || ':memory:';
+        // Assign global write mutex keyed by path, with reference counting
+        const entry = globalWriteMutexRegistry.get(this.#dbPath);
+        if (entry) {
+            entry.refCount++;
+            this.#writeMutex = entry.mutex;
+        }
+        else {
+            const mutex = new ConnectionMutex();
+            globalWriteMutexRegistry.set(this.#dbPath, { mutex, refCount: 1 });
+            this.#writeMutex = mutex;
+        }
+        // Build the connection pool
+        const conn1 = new SqliteConnection(firstDb, this.#writeMutex);
+        this.#connections.push(conn1);
+        this.#freeConnections.push(conn1);
+        await this.#setupConnection(conn1);
+        // If using a factory function, we can create a real pool.
+        if (poolSize > 1 && (0, object_utils_js_1.isFunction)(this.#config.database)) {
+            for (let i = 1; i < poolSize; i++) {
+                const db = await this.#config.database();
+                const conn = new SqliteConnection(db, this.#writeMutex);
+                this.#connections.push(conn);
+                this.#freeConnections.push(conn);
+                await this.#setupConnection(conn);
+            }
+        }
+        this.#initialized = true;
+    }
+    async #setupConnection(conn) {
+        // Set baseline PRAGMAs for concurrency and performance
+        await conn.executeQuery(compiled_query_js_1.CompiledQuery.raw('pragma busy_timeout = 5000'));
+        await conn.executeQuery(compiled_query_js_1.CompiledQuery.raw('pragma journal_mode = WAL'));
+        await conn.executeQuery(compiled_query_js_1.CompiledQuery.raw('pragma synchronous = NORMAL'));
+        await conn.executeQuery(compiled_query_js_1.CompiledQuery.raw('pragma journal_size_limit = 67108864'));
+        await conn.executeQuery(compiled_query_js_1.CompiledQuery.raw('pragma temp_store = MEMORY'));
         if (this.#config.onCreateConnection) {
-            await this.#config.onCreateConnection(this.#connection);
+            await this.#config.onCreateConnection(conn);
         }
     }
     async acquireConnection() {
-        if (!this.#connection) {
-            throw new Error('driver has already been destroyed');
+        if (!this.#initialized) {
+            throw new Error('driver has not been initialized or has already been destroyed');
+        }
+        if (this.#freeConnections.length > 0) {
+            return this.#freeConnections.pop();
         }
-        // SQLite only has one single connection. We use a mutex here to wait
-        // until the single connection has been released.
-        await this.#connectionMutex.lock();
-        return this.#connection;
+        // Wait for a connection to become available
+        return new Promise((resolve) => {
+            this.#waiters.push(resolve);
+        });
     }
     async beginTransaction(connection) {
-        await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('begin'));
+        const sqliteConn = connection;
+        // Acquire the JS-level WriteMutex before executing BEGIN IMMEDIATE.
+        // This serializes all explicit transactions at the JS level.
+        await this.#writeMutex.lock();
+        sqliteConn.hasWriteMutex = true;
+        await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('begin immediate'));
     }
     async commitTransaction(connection) {
         await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('commit'));
+        const sqliteConn = connection;
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
     }
     async rollbackTransaction(connection) {
         await connection.executeQuery(compiled_query_js_1.CompiledQuery.raw('rollback'));
+        const sqliteConn = connection;
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
     }
     async savepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery((0, savepoint_parser_js_1.parseSavepointCommand)('savepoint', savepointName), (0, query_id_js_1.createQueryId)()));
@@ -49,24 +112,52 @@ class SqliteDriver {
     async releaseSavepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery((0, savepoint_parser_js_1.parseSavepointCommand)('release', savepointName), (0, query_id_js_1.createQueryId)()));
     }
-    async releaseConnection() {
-        this.#connectionMutex.unlock();
+    async releaseConnection(connection) {
+        const sqliteConn = connection;
+        // Safety check: ensure mutex is unlocked if connection is released abruptly
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
+        if (this.#waiters.length > 0) {
+            const resolve = this.#waiters.shift();
+            resolve(sqliteConn);
+        }
+        else {
+            this.#freeConnections.push(sqliteConn);
+        }
     }
     async destroy() {
-        if (this.#db) {
-            this.#db.close();
-            this.#db = undefined;
-            this.#connection = undefined;
+        this.#initialized = false;
+        for (const conn of this.#connections) {
+            conn.close();
+        }
+        this.#connections = [];
+        this.#freeConnections = [];
+        this.#waiters = [];
+        // Update reference counting and clean up global registry
+        const entry = globalWriteMutexRegistry.get(this.#dbPath);
+        if (entry) {
+            entry.refCount--;
+            if (entry.refCount <= 0) {
+                globalWriteMutexRegistry.delete(this.#dbPath);
+            }
         }
     }
 }
 exports.SqliteDriver = SqliteDriver;
 class SqliteConnection {
-    #db;
-    constructor(db) {
-        this.#db = db;
+    db;
+    writeMutex;
+    hasWriteMutex = false;
+    constructor(db, writeMutex) {
+        this.db = db;
+        this.writeMutex = writeMutex;
     }
-    executeQuery(compiledQuery) {
+    close() {
+        this.db.close();
+    }
+    async executeQuery(compiledQuery) {
         const { sql, parameters } = compiledQuery;
         // Convert parameters to SQLite-compatible types
         const sqliteParameters = parameters.map((param) => {
@@ -84,20 +175,40 @@ class SqliteConnection {
             }
             return param;
         });
-        const stmt = this.#db.prepare(sql);
+        const stmt = this.db.prepare(sql);
+        // If it's a read query, execute immediately concurrently
         if (stmt.reader) {
-            return Promise.resolve({
+            return {
                 rows: stmt.all(sqliteParameters),
-            });
-        }
-        const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
-        return Promise.resolve({
-            numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
-            insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
-                ? BigInt(lastInsertRowid)
-                : undefined,
-            rows: [],
-        });
+            };
+        }
+        // It's a write query!
+        if (!this.hasWriteMutex) {
+            // Not in an explicit transaction, so we must acquire the WriteMutex temporarily
+            await this.writeMutex.lock();
+            try {
+                const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
+                return {
+                    numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
+                    insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
+                        ? BigInt(lastInsertRowid) : undefined,
+                    rows: [],
+                };
+            }
+            finally {
+                this.writeMutex.unlock();
+            }
+        }
+        else {
+            // Already holding the WriteMutex via explicit transaction
+            const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
+            return {
+                numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
+                insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
+                    ? BigInt(lastInsertRowid) : undefined,
+                rows: [],
+            };
+        }
     }
     async *streamQuery(compiledQuery, _chunkSize) {
         const { sql, parameters, query } = compiledQuery;
@@ -117,7 +228,7 @@ class SqliteConnection {
             }
             return param;
         });
-        const stmt = this.#db.prepare(sql);
+        const stmt = this.db.prepare(sql);
         if (stmt.reader) {
             const iter = stmt.iterate(sqliteParameters);
             for (const row of iter) {

package/dist/cjs/noormme.js

@@ -679,7 +679,7 @@ class NOORMME {
         switch (dialect) {
             case 'sqlite':
                 return new sqlite_dialect_js_1.SqliteDialect({
-                    database: new better_sqlite3_1.default(connection.database),
+                    database: new better_sqlite3_1.default(connection.database, { timeout: 5000 }),
                 });
             case 'postgresql':
                 return new postgresql_dialect_js_1.PostgresDialect({

package/dist/esm/agentic/Cortex.js

@@ -131,18 +131,22 @@ export class Cortex {
         this.executionLock = true;
         console.log('[Cortex] Initiating Autonomous Soul-Searching Loop v2 (Deep Hardening Pass)...');
         try {
+            // Phase 1: System Health & Diagnostic (Strict Transaction)
             await this.db.transaction().execute(async (trx) => {
-                // 1. Audit health & Run self-tests
                 await this.#runIsolated('Audit', () => this.governor.performAudit(trx));
                 await this.#runIsolated('Self-Tests', () => this.tests.runAllProbes(trx));
-                // 2. Run background rituals (optimization, compression)
-                await this.#runIsolated('Rituals', () => this.rituals.runPendingRituals(trx));
-                // 3. Learn from actions & Prune dead data
+            });
+            // Phase 2: Autonomous Rituals (Individual Transactional Isolation)
+            // We run these outside the main transaction to prevent long-running ritual locks
+            // from blocking the entire database.
+            await this.#runIsolated('Rituals', () => this.rituals.runPendingRituals());
+            // Phase 3: Background Maintenance (Unified Maintenance Transaction)
+            await this.db.transaction().execute(async (trx) => {
                 await this.#runIsolated('Action Refinement', () => this.refiner.refineActions(trx));
                 await this.#runIsolated('Zombie Pruning', () => this.ablation.pruneZombies(30, trx));
                 await this.#runIsolated('Ablation Monitoring', () => this.ablation.monitorAblationPerformance(trx));
             });
-            // These are often long-running or have their own internal transaction boundaries
+            // Phase 4: Long-Running Evolutionary Cycles (Internal transaction boundaries)
             await this.#runIsolated('Strategy Mutation', () => this.strategy.mutateStrategy());
             await this.#runIsolated('Evolution Pulse', () => this.evolutionRitual.execute());
             await this.#runIsolated('Knowledge Broadcast', () => this.hive.broadcastKnowledge());

package/dist/esm/agentic/improvement/RitualOrchestrator.d.ts

@@ -16,7 +16,8 @@ export declare class RitualOrchestrator {
      */
     scheduleRitual(name: string, type: AgentRitual['type'], frequency: AgentRitual['frequency'], definition?: string, metadata?: Record<string, any>): Promise<AgentRitual>;
     /**
-     * Run all pending rituals that are due
+     * Run all pending rituals that are due.
+     * PRODUCTION HARDENING: Separate Discovery/Locking from Execution to minimize lock duration.
      */
     runPendingRituals(trxOrDb?: any): Promise<number>;
     /**

package/dist/esm/agentic/improvement/RitualOrchestrator.js

@@ -35,7 +35,8 @@ export class RitualOrchestrator {
         return this.parseRitual(ritual);
     }
     /**
-     * Run all pending rituals that are due
+     * Run all pending rituals that are due.
+     * PRODUCTION HARDENING: Separate Discovery/Locking from Execution to minimize lock duration.
      */
     async runPendingRituals(trxOrDb = this.db) {
         const now = new Date();
@@ -54,7 +55,7 @@ export class RitualOrchestrator {
             if (due.length === 0)
                 return [];
             for (const ritual of due) {
-                // Production Hardening: Distributed Lock
+                // Distributed Lock to prevent other nodes/instances from picking this up
                 await trx
                     .updateTable(this.ritualsTable)
                     .set({ locked_until: lockTimeout })
@@ -63,15 +64,18 @@ export class RitualOrchestrator {
             }
             return due;
         };
+        // DISCOVERY PHASE: Short transaction to find and lock pending work
         const pending = (trxOrDb !== this.db)
             ? await runner(trxOrDb)
             : await this.db.transaction().execute(runner);
         if (pending.length === 0)
             return 0;
-        console.log(`[RitualOrchestrator] Found ${pending.length} pending rituals due. Locking for execution...`);
+        console.log(`[RitualOrchestrator] Found ${pending.length} pending rituals due. Executing in isolation...`);
+        // EXECUTION PHASE: Run rituals outside the discovery transaction.
+        // Each ritual will handle its own internal DB calls / transactions.
         for (const ritual of pending) {
-            // Execute with the same trxOrDb context
-            await this.executeRitual(ritual, trxOrDb);
+            // Use this.db directly to ensure we don't hold the parent transaction lock
+            await this.executeRitual(ritual, this.db);
         }
         return pending.length;
     }

package/dist/esm/dialect/sqlite/sqlite-auto-optimizer.d.ts

@@ -1,16 +1,17 @@
 import type { Kysely } from '../../kysely.js';
 import { Logger } from '../../logging/logger.js';
 export interface SQLiteOptimizationConfig {
-    enableAutoPragma: boolean;
-    enableAutoIndexing: boolean;
-    enablePerformanceTuning: boolean;
-    enableBackupRecommendations: boolean;
-    slowQueryThreshold: number;
-    autoVacuumMode: 'NONE' | 'FULL' | 'INCREMENTAL';
-    journalMode: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
-    synchronous: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
-    cacheSize: number;
-    tempStore: 'DEFAULT' | 'FILE' | 'MEMORY';
+    enableAutoPragma?: boolean;
+    enableAutoIndexing?: boolean;
+    enablePerformanceTuning?: boolean;
+    enableBackupRecommendations?: boolean;
+    slowQueryThreshold?: number;
+    autoVacuumMode?: 'NONE' | 'FULL' | 'INCREMENTAL';
+    journalMode?: 'DELETE' | 'TRUNCATE' | 'PERSIST' | 'MEMORY' | 'WAL' | 'OFF';
+    synchronous?: 'OFF' | 'NORMAL' | 'FULL' | 'EXTRA';
+    busyTimeout?: number;
+    cacheSize?: number;
+    tempStore?: 'DEFAULT' | 'FILE' | 'MEMORY';
 }
 export interface SQLiteOptimizationResult {
     appliedOptimizations: string[];
@@ -46,7 +47,7 @@ export declare class SQLiteAutoOptimizer {
     /**
      * Get default optimization configuration
      */
-    getDefaultConfig(): SQLiteOptimizationConfig;
+    getDefaultConfig(): Required<SQLiteOptimizationConfig>;
     /**
      * Analyze current SQLite configuration and performance
      */

package/dist/esm/dialect/sqlite/sqlite-auto-optimizer.js

@@ -30,6 +30,7 @@ export class SQLiteAutoOptimizer {
             autoVacuumMode: 'INCREMENTAL',
             journalMode: 'WAL',
             synchronous: 'NORMAL',
+            busyTimeout: 5000,
             cacheSize: -64000, // 64MB cache
             tempStore: 'MEMORY',
         };
@@ -81,7 +82,7 @@ export class SQLiteAutoOptimizer {
     /**
      * Apply automatic optimizations based on configuration
      */
-    async optimizeDatabase(db, config = this.getDefaultConfig()) {
+    async optimizeDatabase(db, config) {
         const result = {
             appliedOptimizations: [],
             recommendations: [],
@@ -89,15 +90,17 @@ export class SQLiteAutoOptimizer {
             warnings: [],
         };
         try {
+            // Merge provided config with defaults
+            const finalConfig = { ...this.getDefaultConfig(), ...config };
             // Analyze current state
             const metrics = await this.analyzeDatabase(db);
             // Apply pragma optimizations
-            if (config.enableAutoPragma) {
-                await this.applyPragmaOptimizations(db, config, metrics, result);
+            if (finalConfig.enableAutoPragma) {
+                await this.applyPragmaOptimizations(db, finalConfig, metrics, result);
             }
             // Apply performance tuning
-            if (config.enablePerformanceTuning) {
-                await this.applyPerformanceTuning(db, config, metrics, result);
+            if (finalConfig.enablePerformanceTuning) {
+                await this.applyPerformanceTuning(db, finalConfig, metrics, result);
             }
             // Generate recommendations
             await this.generateRecommendations(db, metrics, result);
@@ -177,6 +180,17 @@ export class SQLiteAutoOptimizer {
                 result.warnings.push('Failed to set temp store');
             }
         }
+        // Set busy timeout
+        if (config.busyTimeout) {
+            try {
+                await sql `PRAGMA busy_timeout = ${sql.lit(config.busyTimeout)}`.execute(db);
+                optimizations.push(`Set busy timeout to ${config.busyTimeout}ms`);
+                result.performanceImpact = 'low';
+            }
+            catch (error) {
+                result.warnings.push('Failed to set busy timeout');
+            }
+        }
         result.appliedOptimizations.push(...optimizations);
     }
     /**

package/dist/esm/dialect/sqlite/sqlite-dialect-config.d.ts

@@ -11,6 +11,12 @@ export interface SqliteDialectConfig {
      * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
      */
     database: SqliteDatabase | (() => Promise<SqliteDatabase>);
+    /**
+     * Maximum number of concurrent connections to the database.
+     * Requires `database` to be a factory function `() => Promise<SqliteDatabase>`.
+     * Defaults to 1.
+     */
+    poolSize?: number;
     /**
      * Called once when the first query is executed.
      *

package/dist/esm/dialect/sqlite/sqlite-driver.d.ts

@@ -34,7 +34,7 @@ export declare class SqliteDriver implements Driver {
     /**
      * Releases a connection back to the pool.
      */
-    releaseConnection(): Promise<void>;
+    releaseConnection(connection: DatabaseConnection): Promise<void>;
     /**
      * Destroys the driver and releases all resources.
      */

package/dist/esm/dialect/sqlite/sqlite-driver.js

@@ -3,40 +3,103 @@ import { parseSavepointCommand } from '../../parser/savepoint-parser.js';
 import { CompiledQuery } from '../../query-compiler/compiled-query.js';
 import { freeze, isFunction } from '../../util/object-utils.js';
 import { createQueryId } from '../../util/query-id.js';
+// Global WriteMutex registry.
+// This serializes all writes to a specific SQLite file across multiple connections
+// in the SAME Node.js process, preventing synchronous C-level event loop blocking.
+const globalWriteMutexRegistry = new Map();
 export class SqliteDriver {
     #config;
-    #connectionMutex = new ConnectionMutex();
-    #db;
-    #connection;
+    #writeMutex;
+    #dbPath;
+    #connections = [];
+    #freeConnections = [];
+    #waiters = [];
+    #initialized = false;
     constructor(config) {
         this.#config = freeze({ ...config });
     }
     async init() {
-        this.#db = isFunction(this.#config.database)
+        const poolSize = this.#config.poolSize || 1;
+        // Retrieve database name/path (fallback to memory if not accessible)
+        // We instantiate the first DB to get the path before building the pool
+        const firstDb = isFunction(this.#config.database)
             ? await this.#config.database()
             : this.#config.database;
-        this.#connection = new SqliteConnection(this.#db);
+        this.#dbPath = firstDb.name || ':memory:';
+        // Assign global write mutex keyed by path, with reference counting
+        const entry = globalWriteMutexRegistry.get(this.#dbPath);
+        if (entry) {
+            entry.refCount++;
+            this.#writeMutex = entry.mutex;
+        }
+        else {
+            const mutex = new ConnectionMutex();
+            globalWriteMutexRegistry.set(this.#dbPath, { mutex, refCount: 1 });
+            this.#writeMutex = mutex;
+        }
+        // Build the connection pool
+        const conn1 = new SqliteConnection(firstDb, this.#writeMutex);
+        this.#connections.push(conn1);
+        this.#freeConnections.push(conn1);
+        await this.#setupConnection(conn1);
+        // If using a factory function, we can create a real pool.
+        if (poolSize > 1 && isFunction(this.#config.database)) {
+            for (let i = 1; i < poolSize; i++) {
+                const db = await this.#config.database();
+                const conn = new SqliteConnection(db, this.#writeMutex);
+                this.#connections.push(conn);
+                this.#freeConnections.push(conn);
+                await this.#setupConnection(conn);
+            }
+        }
+        this.#initialized = true;
+    }
+    async #setupConnection(conn) {
+        // Set baseline PRAGMAs for concurrency and performance
+        await conn.executeQuery(CompiledQuery.raw('pragma busy_timeout = 5000'));
+        await conn.executeQuery(CompiledQuery.raw('pragma journal_mode = WAL'));
+        await conn.executeQuery(CompiledQuery.raw('pragma synchronous = NORMAL'));
+        await conn.executeQuery(CompiledQuery.raw('pragma journal_size_limit = 67108864'));
+        await conn.executeQuery(CompiledQuery.raw('pragma temp_store = MEMORY'));
         if (this.#config.onCreateConnection) {
-            await this.#config.onCreateConnection(this.#connection);
+            await this.#config.onCreateConnection(conn);
         }
     }
     async acquireConnection() {
-        if (!this.#connection) {
-            throw new Error('driver has already been destroyed');
+        if (!this.#initialized) {
+            throw new Error('driver has not been initialized or has already been destroyed');
+        }
+        if (this.#freeConnections.length > 0) {
+            return this.#freeConnections.pop();
         }
-        // SQLite only has one single connection. We use a mutex here to wait
-        // until the single connection has been released.
-        await this.#connectionMutex.lock();
-        return this.#connection;
+        // Wait for a connection to become available
+        return new Promise((resolve) => {
+            this.#waiters.push(resolve);
+        });
     }
     async beginTransaction(connection) {
-        await connection.executeQuery(CompiledQuery.raw('begin'));
+        const sqliteConn = connection;
+        // Acquire the JS-level WriteMutex before executing BEGIN IMMEDIATE.
+        // This serializes all explicit transactions at the JS level.
+        await this.#writeMutex.lock();
+        sqliteConn.hasWriteMutex = true;
+        await connection.executeQuery(CompiledQuery.raw('begin immediate'));
     }
     async commitTransaction(connection) {
         await connection.executeQuery(CompiledQuery.raw('commit'));
+        const sqliteConn = connection;
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
     }
     async rollbackTransaction(connection) {
         await connection.executeQuery(CompiledQuery.raw('rollback'));
+        const sqliteConn = connection;
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
     }
     async savepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery(parseSavepointCommand('savepoint', savepointName), createQueryId()));
@@ -47,23 +110,51 @@ export class SqliteDriver {
     async releaseSavepoint(connection, savepointName, compileQuery) {
         await connection.executeQuery(compileQuery(parseSavepointCommand('release', savepointName), createQueryId()));
     }
-    async releaseConnection() {
-        this.#connectionMutex.unlock();
+    async releaseConnection(connection) {
+        const sqliteConn = connection;
+        // Safety check: ensure mutex is unlocked if connection is released abruptly
+        if (sqliteConn.hasWriteMutex) {
+            sqliteConn.hasWriteMutex = false;
+            this.#writeMutex.unlock();
+        }
+        if (this.#waiters.length > 0) {
+            const resolve = this.#waiters.shift();
+            resolve(sqliteConn);
+        }
+        else {
+            this.#freeConnections.push(sqliteConn);
+        }
     }
     async destroy() {
-        if (this.#db) {
-            this.#db.close();
-            this.#db = undefined;
-            this.#connection = undefined;
+        this.#initialized = false;
+        for (const conn of this.#connections) {
+            conn.close();
+        }
+        this.#connections = [];
+        this.#freeConnections = [];
+        this.#waiters = [];
+        // Update reference counting and clean up global registry
+        const entry = globalWriteMutexRegistry.get(this.#dbPath);
+        if (entry) {
+            entry.refCount--;
+            if (entry.refCount <= 0) {
+                globalWriteMutexRegistry.delete(this.#dbPath);
+            }
         }
     }
 }
 class SqliteConnection {
-    #db;
-    constructor(db) {
-        this.#db = db;
+    db;
+    writeMutex;
+    hasWriteMutex = false;
+    constructor(db, writeMutex) {
+        this.db = db;
+        this.writeMutex = writeMutex;
     }
-    executeQuery(compiledQuery) {
+    close() {
+        this.db.close();
+    }
+    async executeQuery(compiledQuery) {
         const { sql, parameters } = compiledQuery;
         // Convert parameters to SQLite-compatible types
         const sqliteParameters = parameters.map((param) => {
@@ -81,20 +172,40 @@ class SqliteConnection {
             }
             return param;
         });
-        const stmt = this.#db.prepare(sql);
+        const stmt = this.db.prepare(sql);
+        // If it's a read query, execute immediately concurrently
         if (stmt.reader) {
-            return Promise.resolve({
+            return {
                 rows: stmt.all(sqliteParameters),
-            });
-        }
-        const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
-        return Promise.resolve({
-            numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
-            insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
-                ? BigInt(lastInsertRowid)
-                : undefined,
-            rows: [],
-        });
+            };
+        }
+        // It's a write query!
+        if (!this.hasWriteMutex) {
+            // Not in an explicit transaction, so we must acquire the WriteMutex temporarily
+            await this.writeMutex.lock();
+            try {
+                const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
+                return {
+                    numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
+                    insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
+                        ? BigInt(lastInsertRowid) : undefined,
+                    rows: [],
+                };
+            }
+            finally {
+                this.writeMutex.unlock();
+            }
+        }
+        else {
+            // Already holding the WriteMutex via explicit transaction
+            const { changes, lastInsertRowid } = stmt.run(sqliteParameters);
+            return {
+                numAffectedRows: changes !== undefined && changes !== null ? BigInt(changes) : undefined,
+                insertId: lastInsertRowid !== undefined && lastInsertRowid !== null
+                    ? BigInt(lastInsertRowid) : undefined,
+                rows: [],
+            };
+        }
     }
     async *streamQuery(compiledQuery, _chunkSize) {
         const { sql, parameters, query } = compiledQuery;
@@ -114,7 +225,7 @@ class SqliteConnection {
             }
             return param;
         });
-        const stmt = this.#db.prepare(sql);
+        const stmt = this.db.prepare(sql);
         if (stmt.reader) {
             const iter = stmt.iterate(sqliteParameters);
             for (const row of iter) {

package/dist/esm/noormme.js

@@ -674,7 +674,7 @@ export class NOORMME {
         switch (dialect) {
             case 'sqlite':
                 return new SqliteDialect({
-                    database: new Database(connection.database),
+                    database: new Database(connection.database, { timeout: 5000 }),
                 });
             case 'postgresql':
                 return new PostgresDialect({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "noormme",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "NOORMME - The Agentic Data Engine. High-fidelity persistence and cognitive governance for Autonomous AI Agents.",
   "repository": {
     "type": "git",