@vibesdotdev/localdb 0.0.2 → 1.0.0-rc.2

package/dist/core/connection-pool.js

@@ -7,140 +7,534 @@
  * Features:
  * - Singleton pattern per database path
  * - Automatic WAL mode and busy timeout configuration
+ * - A bounded WAL (D-WAL, see `wal-policy.ts`): `journal_size_limit`; one
+ *   non-blocking checkpoint attempt per idle window (TRUNCATE, falling back to
+ *   RESTART after a busy attempt) with busy attempts backing off by whole
+ *   windows; an attempt on release to zero references and at close; observed
+ *   `(busy, log, checkpointed)` results with busy outcomes logged; and a bound
+ *   on how long a transaction may stay open
  * - Connection reuse across consumers
- * - Safe cleanup on process exit
+ * - Slow-statement reporting: a statement at or over `SLOW_STATEMENT_MS` on any
+ *   pooled connection is recorded with its operation and table, and the tick
+ *   reports it (see `slow-statement.ts`) — value-free, and never from the
+ *   statement's own path
+ * - Explicit, host-owned cleanup
  * - Connection statistics and monitoring
+ *
+ * The pool never deletes a raw `-wal` or `-shm` file.
+ *
+ * Hosts sharing one pool have at most one connection per path: two connections to one
+ * file on the same thread can wait on each other inside SQLite's synchronous
+ * busy handler. A composition root that boots several runtimes in one process
+ * creates the pool explicitly (`createConnectionPool`) and hands it to every
+ * runtime it boots (`shareConnectionPool`), so those runtimes — including
+ * reload-generation forks, which inherit the registration — share the one
+ * connection per path. A process that boots a single runtime uses the
+ * runtime-owned default the LocalDB plugin registers instead. Each call
+ * reports on the runtime it was handed (C083a), never on an ambient default.
+ *
+ * Maintenance is owned by a runtime lifecycle (RC07). A connection records the
+ * runtimes that acquired it and runs its maintenance tick on the lifecycle of
+ * one of them that is live and persistent; when that lifecycle ends, the tick
+ * ends with it and moves to the next live persistent holder. The reload
+ * generation dispatcher reads whichever generation serves: it stays a holder
+ * while it serves a live one, so its tick follows it from a retiring
+ * generation to the next. A connection no persistent runtime
+ * holds gets no tick: it checkpoints on release to zero references and on
+ * close/shutdown instead, until a persistent runtime acquires it again.
  */
-import { Database } from 'bun:sqlite';
+import { CapabilityError, createRuntimeKind } from '@vibesdotdev/kernel';
 import { getLogger } from '@vibesdotdev/logging';
-import { toErrorContext } from './error-context.js';
-const logger = getLogger('localdb:pool');
-class SQLiteConnectionPool {
+import { PoolDescriptorSchema } from "../schemas/pool.js";
+export { PoolDescriptorSchema } from "../schemas/pool.js";
+import { sqliteDriverOf } from "./host-kinds.js";
+import { assertOpenedConnectionLive, openConfiguredDatabase } from "./open-connection.js";
+import { createSlowStatementRecorder, instrumentConnection, slowStatementFields, SLOW_STATEMENT_MS } from "./slow-statement.js";
+import { assertRuntimeLive } from "./live-runtime.js";
+import { releasesHolder } from "./holders.js";
+import { attempt } from "./outcome.js";
+import { applyLocalDatabasePragmas, checkpointBackoffWindows, checkpointWal, MAX_TRANSACTION_AGE_MS, nextCheckpointMode, WAL_BUSY_STARVATION_THRESHOLD, WAL_MAINTENANCE_INTERVAL_MS } from "./wal-policy.js";
+/** The pool's Logging on the runtime one call serves (C083a). */
+function poolLogger(runtime) {
+    return getLogger('localdb:pool', runtime);
+}
+export class SQLiteConnectionPool {
     connections = new Map();
-    cleanupInterval;
+    /** Physical path custody spans every runtime-local manager using this pool. */
+    databasePathLocks = new Map();
     STALE_THRESHOLD_MS = 30 * 60 * 1000; // 30 minutes
-    CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
-    constructor() {
-        // Periodic cleanup of stale connections
-        this.startCleanup();
-        // Ensure proper cleanup on process exit
-        this.registerExitHandlers();
+    /** Opens in flight, by path: concurrent first acquisitions share one connection. */
+    opening = new Map();
+    /** Serialize managed initialization, migration, release and reset against the same physical file. */
+    async withDatabasePathLock(dbPath, task) {
+        const prior = this.databasePathLocks.get(dbPath) ?? Promise.resolve();
+        let release;
+        const current = new Promise(resolve => { release = resolve; });
+        const queued = prior.then(() => current);
+        this.databasePathLocks.set(dbPath, queued);
+        await prior;
+        try {
+            return await task();
+        }
+        finally {
+            release?.();
+            if (this.databasePathLocks.get(dbPath) === queued)
+                this.databasePathLocks.delete(dbPath);
+        }
     }
     /**
-     * Get or create a database connection with optimal configuration
+     * Get or create a database connection with optimal configuration, opened
+     * through the SQLite driver the calling runtime's host registered. The
+     * calling runtime becomes a holder of the connection and reports the open.
+     * A runtime whose disposal began is refused before any connection opens
+     * (`CANCELLED` `runtime-disposed`), and again if it began while the open
+     * was in flight. Cancellation before publication closes the startup handle.
      */
-    getConnection(dbPath, consumer = 'unknown') {
+    async getConnection(runtime, dbPath, consumer = 'unknown') {
+        const lifecycle = runtime.lifecycle;
+        assertRuntimeLive(runtime, 'connection', lifecycle);
         let pooled = this.connections.get(dbPath);
+        let created = false;
         if (!pooled) {
-            const db = new Database(dbPath);
-            // Configure for optimal concurrent access
-            this.configureDatabase(db);
-            pooled = {
-                db,
-                refCount: 0,
-                lastUsed: Date.now(),
-                createdAt: Date.now(),
-                consumer
-            };
-            this.connections.set(dbPath, pooled);
-            logger.debug(`Created connection: ${dbPath} (${consumer})`);
+            const pending = this.opening.get(dbPath);
+            if (pending) {
+                pooled = await pending;
+            }
+            else {
+                const opening = this.open(runtime, dbPath, consumer);
+                this.opening.set(dbPath, opening);
+                try {
+                    pooled = await opening;
+                }
+                finally {
+                    this.opening.delete(dbPath);
+                }
+                created = true;
+            }
+            assertRuntimeLive(runtime, 'connection', lifecycle);
+            // Disposal may have swept an unheld open while this borrower awaited it.
+            // A live borrower acquires the current physical handle rather than a closed one.
+            if (this.connections.get(dbPath) !== pooled)
+                return this.getConnection(runtime, dbPath, consumer);
         }
+        this.hold(runtime, dbPath, pooled);
         pooled.refCount++;
         pooled.lastUsed = Date.now();
+        if (created)
+            poolLogger(runtime).debug(`Created connection: ${dbPath} (${consumer})`);
         return pooled.db;
     }
+    /** Open and pool the connection at `dbPath` with the LocalDB pragmas, through the runtime's driver. */
+    async open(runtime, dbPath, consumer) {
+        const lifecycle = runtime.lifecycle;
+        const driver = await sqliteDriverOf(runtime);
+        const opened = await openConfiguredDatabase(runtime, () => driver.open(dbPath), applyLocalDatabasePragmas, lifecycle);
+        const slowStatements = createSlowStatementRecorder();
+        // Timed here, at the one place every statement in this process reaches, so
+        // the report names the consumer that opened the connection and the table
+        // that statement touched. Reported by the tick, never from here.
+        const db = instrumentConnection(opened, slowStatements);
+        const pooled = {
+            db,
+            slowStatements,
+            refCount: 0,
+            lastUsed: Date.now(),
+            createdAt: Date.now(),
+            consumer,
+            holders: new Set(),
+            consecutiveCheckpointBusy: 0,
+            nextCheckpointMode: 'TRUNCATE',
+            nextIdleCheckpointAt: Number.NEGATIVE_INFINITY
+        };
+        // Publication is synchronous with the captured-lifecycle check. A cancelled
+        // startup closes here and can never publish an unheld physical connection.
+        assertOpenedConnectionLive(runtime, opened, lifecycle);
+        this.connections.set(dbPath, pooled);
+        return pooled;
+    }
     /**
-     * Configure database with optimal settings for concurrent access
+     * Record `runtime` as a holder of the pooled connection at `dbPath`, so its
+     * maintenance can run on (or move to) that runtime. No connection there:
+     * nothing to hold.
      */
-    configureDatabase(db) {
-        // WAL mode: Readers don't block writers, writers don't block readers
-        db.exec('PRAGMA journal_mode = WAL;');
-        // Busy timeout: Wait up to 5 seconds for locks instead of failing immediately
-        db.exec('PRAGMA busy_timeout = 5000;');
-        // Foreign keys: Enable referential integrity
-        db.exec('PRAGMA foreign_keys = ON;');
-        // Synchronous: NORMAL is safe with WAL and much faster
-        db.exec('PRAGMA synchronous = NORMAL;');
-        // Temp store: Use memory for temp tables (faster)
-        db.exec('PRAGMA temp_store = MEMORY;');
+    retain(runtime, dbPath) {
+        const pooled = this.connections.get(dbPath);
+        if (pooled)
+            this.hold(runtime, dbPath, pooled);
+    }
+    hold(runtime, dbPath, pooled) {
+        // A runtime that ended holds nothing: drop it so a long-lived connection
+        // never retains the runtimes that passed through it.
+        for (const holder of pooled.holders) {
+            if (holder.lifecycle.signal.aborted)
+                pooled.holders.delete(holder);
+        }
+        pooled.holders.add(runtime);
+        this.ensureMaintenance(dbPath, pooled);
+    }
+    /**
+     * Keep the connection's tick on a live persistent holder. A tick whose
+     * lifecycle (the one it started on) is still live, on a runtime that still
+     * holds the connection, stays where it is;
+     * otherwise the first live persistent holder takes it, and holders that
+     * ended are dropped.
+     */
+    ensureMaintenance(dbPath, pooled) {
+        const current = pooled.maintenance;
+        // A live tick stays where it is while its runtime still holds the connection.
+        if (current && !current.signal.aborted && pooled.holders.has(current.runtime))
+            return;
+        current?.stop();
+        pooled.maintenance = undefined;
+        for (const holder of pooled.holders) {
+            if (holder.lifecycle.signal.aborted) {
+                pooled.holders.delete(holder);
+                continue;
+            }
+            // A finite host starts no background work (`lifecycle.interval` refuses it).
+            if (holder.scope.lifecycle === 'finite')
+                continue;
+            pooled.maintenance = this.maintainOn(holder, dbPath, pooled);
+            return;
+        }
+    }
+    /**
+     * Run the connection's tick on the lifecycle `runtime` reads now. The tick
+     * ends when that lifecycle ends (it clears every interval). At that moment
+     * the runtime is dropped as a holder unless it now reads a live lifecycle
+     * (the reload generation dispatcher, whose `lifecycle` follows whichever
+     * generation serves), and the tick moves to the next live persistent
+     * holder, that runtime included.
+     */
+    maintainOn(runtime, dbPath, pooled) {
+        const { lifecycle } = runtime;
+        const { signal } = lifecycle;
+        const stopTick = lifecycle.interval(() => this.tick(runtime, dbPath, pooled), WAL_MAINTENANCE_INTERVAL_MS);
+        const moveOn = () => {
+            // ensureMaintenance drops the holders that ended (a runtime whose lifecycle follows
+            // another, the dispatcher, still holds while it reads a live one) and moves the tick on.
+            if (this.connections.get(dbPath) === pooled)
+                this.ensureMaintenance(dbPath, pooled);
+        };
+        signal.addEventListener('abort', moveOn, { once: true });
+        return {
+            runtime,
+            signal,
+            stop: () => {
+                stopTick();
+                signal.removeEventListener('abort', moveOn);
+            }
+        };
+    }
+    /** One maintenance tick for one connection. It never throws into the timer: a failure is logged with its cause. */
+    tick(runtime, dbPath, pooled) {
+        const pass = attempt(() => this.maintainConnection(runtime, dbPath, pooled, Date.now()));
+        if (pass.failed) {
+            poolLogger(runtime).error('[LocalDB] Pool maintenance tick failed', {
+                reason: 'localdb-maintenance-failed',
+                dbPath,
+                consumer: pooled.consumer,
+                error: pass.cause
+            });
+        }
     }
     /**
      * Release a connection (decrement reference count)
      * Connection remains in pool for reuse
      */
-    releaseConnection(dbPath) {
+    releaseConnection(runtime, dbPath) {
         const pooled = this.connections.get(dbPath);
         if (pooled) {
-            pooled.refCount = Math.max(0, pooled.refCount - 1);
-            pooled.lastUsed = Date.now();
+            const refCount = Math.max(0, pooled.refCount - 1);
+            const lastUsed = Date.now();
+            // Last reference gone: the WAL does not self-checkpoint when holders
+            // reach zero, so attempt a reset now — unless the connection is
+            // backing off after busy attempts; its next idle window will try.
+            if (refCount === 0 &&
+                !pooled.db.inTransaction &&
+                lastUsed >= pooled.nextIdleCheckpointAt) {
+                this.observeCheckpoint(runtime, dbPath, pooled, 'release', lastUsed);
+            }
+            // Commit the reference release only after its checkpoint/reporting work succeeds.
+            pooled.refCount = refCount;
+            pooled.lastUsed = lastUsed;
         }
     }
     /**
-     * Close a specific connection immediately
-     * Only closes if reference count is zero (unless forced)
+     * Run one observed, non-blocking checkpoint attempt and record its outcome,
+     * reported on `runtime`. A busy attempt is logged at warn (a run of
+     * {@link WAL_BUSY_STARVATION_THRESHOLD} at error, as starvation), switches
+     * the next attempt's mode, and backs the connection off by whole windows. A
+     * checkpoint SQLite itself rejects is logged at error with its cause and
+     * never blocks the caller's close or tick.
      */
-    closeConnection(dbPath, force = false) {
-        const pooled = this.connections.get(dbPath);
-        if (!pooled)
-            return false;
-        if (force || pooled.refCount === 0) {
-            try {
-                pooled.db.close();
-                this.connections.delete(dbPath);
-                // Use stderr to avoid breaking MCP stdio protocol
-                logger.debug(`[LocalDB] Closed connection: ${dbPath}`);
-                return true;
+    observeCheckpoint(runtime, dbPath, pooled, trigger, now) {
+        const logger = poolLogger(runtime);
+        const attempted = attempt(() => checkpointWal(pooled.db, pooled.nextCheckpointMode));
+        if (attempted.failed) {
+            logger.error('[LocalDB] WAL checkpoint failed', {
+                reason: 'wal-checkpoint-failed',
+                dbPath,
+                trigger,
+                consumer: pooled.consumer,
+                error: attempted.cause
+            });
+            return;
+        }
+        const outcome = attempted.value;
+        pooled.lastCheckpoint = { ...outcome, at: now, trigger };
+        const { busy, log, checkpointed, mode } = outcome;
+        pooled.nextCheckpointMode = nextCheckpointMode(mode, outcome.status);
+        const fields = { dbPath, trigger, consumer: pooled.consumer, mode, busy, log, checkpointed };
+        if (outcome.status === 'busy') {
+            pooled.consecutiveCheckpointBusy++;
+            const consecutive = pooled.consecutiveCheckpointBusy;
+            pooled.nextIdleCheckpointAt = now + checkpointBackoffWindows(consecutive) * WAL_MAINTENANCE_INTERVAL_MS;
+            if (consecutive >= WAL_BUSY_STARVATION_THRESHOLD) {
+                logger.error('[LocalDB] WAL checkpoint starved: another holder keeps frames pinned', {
+                    reason: 'wal-checkpoint-starved',
+                    consecutiveBusy: consecutive,
+                    ...fields
+                });
             }
-            catch (error) {
-                logger.error(`[LocalDB] Error closing ${dbPath}:`, toErrorContext(error));
-                return false;
+            else {
+                // Every frame copied back and only the truncate/restart was blocked by another
+                // process's reader: routine on a shared file. Frames left behind are worth a warning.
+                const report = checkpointed >= log ? logger.debug.bind(logger) : logger.warn.bind(logger);
+                report('[LocalDB] WAL checkpoint busy', {
+                    reason: 'wal-checkpoint-busy',
+                    consecutiveBusy: consecutive,
+                    ...fields
+                });
             }
         }
+        else {
+            pooled.consecutiveCheckpointBusy = 0;
+            pooled.nextIdleCheckpointAt = Number.NEGATIVE_INFINITY;
+            logger.debug('[LocalDB] WAL checkpoint', { status: outcome.status, ...fields });
+        }
+    }
+    /**
+     * Bound how long a pooled connection may sit inside a transaction. SQLite
+     * is synchronous, so a transaction a tick can observe spans an `await`; one
+     * older than {@link MAX_TRANSACTION_AGE_MS} pins every WAL frame written
+     * after it began, in every process. It is rolled back and reported; the
+     * owner's later COMMIT then fails loudly rather than the WAL growing silently.
+     *
+     * @returns whether the connection is still inside a transaction.
+     */
+    enforceTransactionBound(runtime, dbPath, pooled, now) {
+        if (!pooled.db.inTransaction) {
+            pooled.transactionObservedAt = undefined;
+            return false;
+        }
+        pooled.transactionObservedAt ??= now;
+        const ageMs = now - pooled.transactionObservedAt;
+        if (ageMs < MAX_TRANSACTION_AGE_MS)
+            return true;
+        const logger = poolLogger(runtime);
+        const rolledBack = attempt(() => pooled.db.exec('ROLLBACK;'));
+        if (rolledBack.failed) {
+            logger.error('[LocalDB] Failed to roll back an expired transaction', {
+                reason: 'localdb-transaction-expiry-failed',
+                dbPath,
+                consumer: pooled.consumer,
+                observedAgeMs: ageMs,
+                error: rolledBack.cause
+            });
+            return true;
+        }
+        pooled.transactionObservedAt = undefined;
+        logger.error('[LocalDB] Rolled back a transaction held open past its bound', {
+            reason: 'localdb-transaction-expired',
+            dbPath,
+            consumer: pooled.consumer,
+            observedAgeMs: ageMs,
+            maxTransactionAgeMs: MAX_TRANSACTION_AGE_MS
+        });
         return false;
     }
     /**
-     * Clean up stale connections (unused for 30+ minutes with zero references)
+     * Report the statements this window recorded as slow, on `runtime` and once
+     * per connection. Each report carries the connection's consumer and database
+     * with the statement's operation and table; a window that recorded more than
+     * it kept says so rather than reading as a complete count.
      */
-    cleanupStale() {
-        const now = Date.now();
-        for (const [dbPath, pooled] of this.connections.entries()) {
-            const age = now - pooled.lastUsed;
-            if (pooled.refCount === 0 && age > this.STALE_THRESHOLD_MS) {
-                this.closeConnection(dbPath, true);
+    reportSlowStatements(runtime, dbPath, pooled) {
+        const { reports, dropped } = pooled.slowStatements.drain();
+        if (reports.length === 0 && dropped === 0)
+            return;
+        poolLogger(runtime).warn('[LocalDB] Slow statements held the thread', {
+            reason: 'localdb-slow-statement',
+            dbPath,
+            consumer: pooled.consumer,
+            thresholdMs: SLOW_STATEMENT_MS,
+            dropped,
+            statements: reports.map(slowStatementFields)
+        });
+    }
+    /**
+     * One idle window for one connection: report what it recorded as slow, bound
+     * an open transaction, close the connection when it has been unused for 30+
+     * minutes with zero references, or make at most one observed checkpoint
+     * attempt when it is not inside a transaction and not backing off. Every step
+     * reports its own failure.
+     */
+    maintainConnection(runtime, dbPath, pooled, now) {
+        // First, so a window that returns early below still reports what it saw.
+        this.reportSlowStatements(runtime, dbPath, pooled);
+        const inTransaction = this.enforceTransactionBound(runtime, dbPath, pooled, now);
+        if (inTransaction)
+            return;
+        if (pooled.refCount === 0 && now - pooled.lastUsed > this.STALE_THRESHOLD_MS) {
+            // The close runs its own observed checkpoint.
+            const closed = attempt(() => this.closePooled(runtime, dbPath, pooled, 'close'));
+            if (closed.failed) {
+                poolLogger(runtime).error('[LocalDB] Failed to close a stale connection', {
+                    reason: 'localdb-stale-close-failed',
+                    dbPath,
+                    consumer: pooled.consumer,
+                    error: closed.cause
+                });
             }
+            return;
         }
+        if (now < pooled.nextIdleCheckpointAt)
+            return;
+        this.observeCheckpoint(runtime, dbPath, pooled, 'idle', now);
     }
     /**
-     * Start periodic cleanup
+     * One maintenance pass over every pooled connection, reported on `runtime`.
+     * Each connection's lifecycle tick runs the same window for that connection
+     * alone; hosts and tests may call this directly.
      */
-    startCleanup() {
-        this.cleanupInterval = setInterval(() => this.cleanupStale(), this.CLEANUP_INTERVAL_MS);
+    maintain(runtime, now = Date.now()) {
+        for (const [dbPath, pooled] of this.connections)
+            this.maintainConnection(runtime, dbPath, pooled, now);
     }
     /**
-     * Stop periodic cleanup
+     * Close one pooled connection and remove it from the pool, reported on
+     * `runtime`. A connection still inside a transaction is closed without a
+     * checkpoint, and SQLite discards that transaction: the discard is
+     * reported, never silent. A close SQLite refuses throws
+     * `localdb-close-failed` (the original error as `cause`) and the connection
+     * stays pooled, still maintained, for a retry.
      */
-    stopCleanup() {
-        if (this.cleanupInterval) {
-            clearInterval(this.cleanupInterval);
-            this.cleanupInterval = undefined;
+    closePooled(runtime, dbPath, pooled, trigger) {
+        const logger = poolLogger(runtime);
+        if (pooled.db.inTransaction) {
+            logger.error('[LocalDB] Closing a connection inside an open transaction discards that transaction', {
+                reason: 'localdb-transaction-discarded',
+                dbPath,
+                trigger,
+                consumer: pooled.consumer
+            });
         }
+        else {
+            // Observed and logged; a busy or failed checkpoint never blocks close.
+            this.observeCheckpoint(runtime, dbPath, pooled, trigger, Date.now());
+        }
+        const closed = attempt(() => pooled.db.close());
+        if (closed.failed) {
+            throw new CapabilityError(`Failed to close LocalDB connection '${dbPath}'`, 'INTERNAL', {
+                reason: 'localdb-close-failed',
+                retryable: true,
+                details: { dbPath, trigger },
+                cause: closed.cause
+            });
+        }
+        pooled.maintenance?.stop();
+        pooled.maintenance = undefined;
+        pooled.holders.clear();
+        this.connections.delete(dbPath);
+        logger.debug(`[LocalDB] Closed connection (${trigger}): ${dbPath}`);
+    }
+    /**
+     * Refuse destructive replacement while another lifecycle or pooled reference
+     * holds the file. Only the requesting instance's actual open connection may
+     * account for one reference; legacy/raw borrowers keep their custody too.
+     * Call under the database path lock, before releasing or closing anything.
+     */
+    assertCanReplaceDatabase(runtime, dbPath, ownedConnection) {
+        const pooled = this.connections.get(dbPath);
+        if (!pooled)
+            return;
+        const signal = runtime.lifecycle.signal;
+        const foreignHolders = [...pooled.holders].filter(holder => !holder.lifecycle.signal.aborted && holder.lifecycle.signal !== signal).length;
+        const ownedReferences = pooled.db === ownedConnection ? 1 : 0;
+        if (foreignHolders === 0 && pooled.refCount <= ownedReferences)
+            return;
+        throw new CapabilityError('LocalDB cannot replace a database with outstanding borrowers.', 'CONFLICT', {
+            reason: 'localdb-database-in-use',
+            retryable: false,
+            details: { dbPath, foreignHolders, references: pooled.refCount, ownedReferences },
+            recoveryHint: 'Release the other database borrowers before requesting reset or recovery.'
+        });
+    }
+    /**
+     * Give back one pooled reference no live runtime holds: every recorded
+     * holder ended (or none is recorded) while the reference count is still
+     * nonzero — typically a client of a runtime that ended without releasing.
+     * Returns whether a reference was given back. A connection another live
+     * runtime still holds is never touched.
+     */
+    releaseOrphanedConnection(dbPath) {
+        const pooled = this.connections.get(dbPath);
+        if (!pooled || pooled.refCount === 0)
+            return false;
+        if ([...pooled.holders].some((holder) => !holder.lifecycle.signal.aborted))
+            return false;
+        pooled.refCount = Math.max(0, pooled.refCount - 1);
+        pooled.lastUsed = Date.now();
+        return true;
     }
     /**
-     * Close all connections (typically on shutdown)
+     * Close a specific connection immediately. Only closes if the reference
+     * count is zero, unless forced. Returns whether it closed; a close SQLite
+     * refuses throws `localdb-close-failed` and leaves the connection pooled.
      */
-    closeAll() {
-        this.stopCleanup();
-        for (const [dbPath, pooled] of this.connections.entries()) {
-            try {
-                pooled.db.close();
-                // Use stderr to avoid breaking MCP stdio protocol
-                logger.debug(`[LocalDB] Closed connection on shutdown: ${dbPath}`);
+    closeConnection(runtime, dbPath, force = false) {
+        const pooled = this.connections.get(dbPath);
+        if (!pooled)
+            return false;
+        if (!force && pooled.refCount > 0)
+            return false;
+        this.closePooled(runtime, dbPath, pooled, 'close');
+        return true;
+    }
+    /**
+     * Give back every connection `runtime` holds (typically at its disposal),
+     * reported on `runtime`; runtimes that ended hold nothing. A connection
+     * another live runtime still holds (another root, or the root a disposing
+     * reload generation was forked from) stays pooled for it, its maintenance moving to that
+     * holder; every other connection closes. Every close is attempted; the ones
+     * SQLite refuses stay pooled and are reported together in one AggregateError
+     * so the runtime owner can report them and retry.
+     */
+    closeAll(runtime, retainedPaths = new Set()) {
+        const failures = [];
+        for (const [dbPath, pooled] of this.connections) {
+            if (retainedPaths.has(dbPath))
+                continue;
+            for (const holder of pooled.holders) {
+                if (releasesHolder(holder, runtime) || holder.lifecycle.signal.aborted)
+                    pooled.holders.delete(holder);
             }
-            catch (error) {
-                logger.error(`[LocalDB] Error closing ${dbPath}:`, toErrorContext(error));
+            if (pooled.holders.size > 0) {
+                this.ensureMaintenance(dbPath, pooled);
+                continue;
             }
+            const closed = attempt(() => this.closePooled(runtime, dbPath, pooled, 'shutdown'));
+            if (closed.failed)
+                failures.push(closed.cause);
         }
-        this.connections.clear();
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `Failed to close ${failures.length} LocalDB connection${failures.length === 1 ? '' : 's'}`);
+        }
+    }
+    /** Whether a managed handle still names the pooled connection at this path. */
+    ownsConnection(dbPath, db) {
+        return this.connections.get(dbPath)?.db === db;
     }
     /**
      * Get pool statistics
@@ -150,19 +544,35 @@ class SQLiteConnectionPool {
         let idle = 0;
         const connections = [];
         const now = Date.now();
-        for (const [path, pooled] of this.connections.entries()) {
+        for (const [path, pooled] of this.connections) {
             if (pooled.refCount > 0) {
                 active++;
             }
             else {
                 idle++;
             }
-            connections.push({
+            const entry = {
                 path,
                 refCount: pooled.refCount,
                 ageMs: now - pooled.createdAt,
-                consumer: pooled.consumer
-            });
+                consumer: pooled.consumer,
+                maintained: pooled.maintenance !== undefined,
+                holders: pooled.holders.size,
+                consecutiveCheckpointBusy: pooled.consecutiveCheckpointBusy
+            };
+            const last = pooled.lastCheckpoint;
+            if (last) {
+                entry.lastCheckpoint = {
+                    at: last.at,
+                    trigger: last.trigger,
+                    status: last.status,
+                    mode: last.mode,
+                    busy: last.busy,
+                    log: last.log,
+                    checkpointed: last.checkpointed
+                };
+            }
+            connections.push(entry);
         }
         return {
             total: this.connections.size,
@@ -171,21 +581,120 @@ class SQLiteConnectionPool {
             connections
         };
     }
-    /**
-     * Register process exit handlers for cleanup
-     */
-    registerExitHandlers() {
-        process.on('beforeExit', () => this.closeAll());
-        process.on('SIGINT', () => {
-            this.closeAll();
-            process.exit(0);
-        });
-        process.on('SIGTERM', () => {
-            this.closeAll();
-            process.exit(0);
+}
+/**
+ * The `localdb/pool` kind: the process's physical SQLite connections, owned
+ * through the kernel. The pool holds live host handles, so — unlike migration
+ * declarations, which each runtime owns separately — runtimes that must open
+ * the same file share one pool instance resolved from the runtime they are
+ * handed. No module-level pool instance exists: every instance is created
+ * explicitly (`createConnectionPool`, the plugin default, or a shared owner a
+ * composition root registers) and resolved through the kernel below.
+ */
+export const LOCALDB_POOL_KIND = 'localdb/pool';
+/** The runtime-owned default pool, created per root runtime by the LocalDB plugin. */
+export const DEFAULT_POOL_ID = 'pool';
+/**
+ * An explicitly shared pool, handed to each runtime by the composition root
+ * that boots them. Preferred over the default whenever it is registered.
+ */
+export const SHARED_POOL_ID = 'shared';
+/** The kind LocalDB registers; an implementation that is not a pool is refused `implementation-invalid`. */
+export const poolKind = createRuntimeKind({
+    id: LOCALDB_POOL_KIND,
+    descriptorSchema: PoolDescriptorSchema,
+    validateImplementation: (impl) => impl instanceof SQLiteConnectionPool
+});
+/**
+ * Create the physical connection pool a composition root hands to the runtimes
+ * it boots. One pool per process per database set: every runtime handed the
+ * same pool shares the one connection per path.
+ */
+export function createConnectionPool() {
+    return new SQLiteConnectionPool();
+}
+/** `UNAVAILABLE localdb-pool-unavailable`: the runtime registered no connection pool. */
+function poolUnavailable() {
+    return new CapabilityError('This runtime registered no LocalDB connection pool (localdb/pool).', 'UNAVAILABLE', {
+        reason: 'localdb-pool-unavailable',
+        retryable: false,
+        recoveryHint: 'Compose the LocalDB plugin, which registers a runtime-owned default pool.'
+    });
+}
+/**
+ * Resolve the runtime's physical connection pool through the kernel on every
+ * call, so current selection, invalidation, and implementation caching remain
+ * owned by the runtime: an explicitly shared pool when the composition root
+ * registered one, else the runtime-owned default the LocalDB plugin
+ * registered. Anything else (a refused loader, an invalid implementation)
+ * propagates unwrapped.
+ */
+export async function poolOf(runtime) {
+    if (!runtime.hasKind(LOCALDB_POOL_KIND))
+        throw poolUnavailable();
+    // SAFETY: kernel RuntimeRef.query returns AssetQuery; its minimal plugin port omits the public sortBy method.
+    const selected = await runtime.query(LOCALDB_POOL_KIND)
+        .sortBy('priority', 'desc').select();
+    if (!selected)
+        throw poolUnavailable();
+    return selected.impl;
+}
+/**
+ * The already-resolved pool, or `undefined` when no resolution warmed the
+ * kernel cache yet. Synchronous cover for call sites that hold no async
+ * context after an async call resolved the pool first.
+ */
+export function tryPoolOf(runtime) {
+    if (!runtime.hasKind(LOCALDB_POOL_KIND))
+        return undefined;
+    // SAFETY: kernel RuntimeRef.query returns AssetQuery; its minimal plugin port omits the public sortBy method.
+    return runtime.query(LOCALDB_POOL_KIND).sortBy('priority', 'desc').peek?.();
+}
+const DEFAULT_POOL_DESCRIPTION = 'Runtime-owned default LocalDB connection pool';
+const SHARED_POOL_DESCRIPTION = 'Explicitly shared LocalDB connection pool for every runtime one composition root boots';
+/**
+ * Register the runtime-owned default pool, unless one is already registered:
+ * reload-generation forks inherit their root's registrations, so they keep
+ * sharing the root's pool instead of minting a second connection per path.
+ */
+export function ensureDefaultPool(runtime) {
+    if (!runtime.hasKind(LOCALDB_POOL_KIND))
+        runtime.registerKind(poolKind);
+    if (runtime.query(LOCALDB_POOL_KIND).withId(DEFAULT_POOL_ID).descriptors().length > 0)
+        return;
+    runtime.registerDescriptor(LOCALDB_POOL_KIND, {
+        kind: LOCALDB_POOL_KIND,
+        id: DEFAULT_POOL_ID,
+        description: DEFAULT_POOL_DESCRIPTION
+    });
+    // The registration owns the instance: inherited loaders must return the
+    // same physical owner to forks, rather than construct one per client cache.
+    const pool = new SQLiteConnectionPool();
+    runtime.registerLoader(LOCALDB_POOL_KIND, DEFAULT_POOL_ID, async () => ({ impl: pool }));
+}
+/**
+ * Hand one explicitly created pool to a runtime: every runtime the
+ * composition root boots against the same database files shares the one
+ * connection per path. Fork generations inherit the registration, so they
+ * share it too.
+ */
+export function shareConnectionPool(runtime, pool) {
+    if (!runtime.hasKind(LOCALDB_POOL_KIND))
+        runtime.registerKind(poolKind);
+    const shared = runtime.query(LOCALDB_POOL_KIND).withId(SHARED_POOL_ID);
+    if (shared.peek?.() === pool)
+        return;
+    if (shared.descriptors().length > 0 || tryPoolOf(runtime)) {
+        throw new CapabilityError('The LocalDB pool owner has already been selected.', 'CONFLICT', {
+            reason: 'localdb-pool-owner-selected', retryable: false,
+            recoveryHint: 'Register the shared owner during composition, before LocalDB activation or pool resolution.'
         });
     }
+    runtime.registerDescriptor(LOCALDB_POOL_KIND, {
+        kind: LOCALDB_POOL_KIND,
+        id: SHARED_POOL_ID,
+        description: SHARED_POOL_DESCRIPTION
+    });
+    runtime.registerLoader(LOCALDB_POOL_KIND, SHARED_POOL_ID, async () => ({ impl: pool }), { priority: 100 });
 }
-// Singleton instance
-export const connectionPool = new SQLiteConnectionPool();
 //# sourceMappingURL=connection-pool.js.map