@vibesdotdev/localdb 0.0.2 → 1.0.0-rc.3

package/dist/core/database.js

@@ -5,343 +5,1077 @@
  * Provides connection pooling, migration management, and consistent configuration.
  *
  * Usage:
- *   const db = localdb.getDatabase('atlas', '.vibes/atlas/project.db');
+ *   const db = await localdb.getDatabase(runtime, 'atlas', '<workspace>/.vibes/atlas/<projectId>.db');
  *   // db is ready to use with WAL mode, busy timeout, and migrations applied
+ *
+ * Every call that opens, registers, releases or closes takes the runtime it
+ * serves: that runtime's Logging reports it (C083a), never an ambient default.
  */
-import { Database } from 'bun:sqlite';
+import { CapabilityError, CaughtFailureSchema, isCapabilityError } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient, getVibesClient, tryGetVibesClient, RuntimeClientDescriptorSchema } from '@vibesdotdev/kernel/client';
+import { runtimeClientPlugin } from '@vibesdotdev/kernel/client/plugin';
+import { releasesHolder } from "./holders.js";
 import { getLogger } from '@vibesdotdev/logging';
-import { connectionPool } from "./connection-pool.js";
-import { migrationRegistry } from "./migration-registry.js";
-import { toErrorContext } from './error-context.js';
-import { isLocaldbServerRuntime } from "./runtime.js";
-const logger = getLogger('localdb:database');
-let mkdir;
-let copyFile;
-let unlink;
-let readdir;
-let dirname;
-let basename;
+import { assertOpenedConnectionLive, openConfiguredDatabase } from "./open-connection.js";
+import { ensureDefaultPool, poolOf, tryPoolOf } from "./connection-pool.js";
+import { assertRuntimeLive } from "./live-runtime.js";
+import { migrationRegistry, MigrationRegistry } from "./migration-registry.js";
+import { attempt, settle } from "./outcome.js";
+import { applyLocalDatabasePragmas, checkpointWal } from "./wal-policy.js";
+import { fileSystemOf, sqliteDriverOf } from "./host-kinds.js";
+/** The manager's Logging on the runtime one call serves (C083a). */
+function databaseLogger(runtime) {
+    return getLogger('localdb:database', runtime);
+}
 const BACKUP_RETENTION_COUNT = 12;
-const isServerRuntime = isLocaldbServerRuntime();
-if (isServerRuntime) {
-    ({ mkdir, copyFile, unlink, readdir } = await import('node:fs/promises'));
-    ({ dirname, basename } = await import('node:path'));
+const DATABASE_SIDECARS = ['-wal', '-shm'];
+/**
+ * The backup name for `filename` archived at `now`: `<file>.bak-<ms>`, moved
+ * one millisecond later past any set that already holds that name, so an
+ * archive never replaces an earlier backup set.
+ */
+export function nextBackupName(filename, existing, now) {
+    let stamp = now;
+    while (existing.has(`${filename}.bak-${stamp}`))
+        stamp += 1;
+    return `${filename}.bak-${stamp}`;
+}
+/**
+ * Prune `<db>.bak-*` backup SETS (main + -wal + -shm sharing one timestamp) down
+ * to {@link BACKUP_RETENTION_COUNT}, newest first. Grouping by timestamp ensures a
+ * retained WAL is never stranded without its main file. The single owned home for
+ * local-db backup retention — consumers must not hand-roll their own.
+ *
+ * Pruning never fails the recovery that triggered it: a backup file that cannot
+ * be removed is reported with its cause, and the next prune tries it again.
+ */
+/** The entry names in `directory`, through the runtime's filesystem. */
+async function entryNames(files, directory) {
+    return (await files.list(directory)).map((entry) => entry.name);
+}
+async function pruneDatabaseBackups(runtime, files, directory, filename) {
+    const backupPrefix = `${filename}.bak-`;
+    const groups = new Map();
+    for (const entry of await entryNames(files, directory)) {
+        if (!entry.startsWith(backupPrefix))
+            continue;
+        const timestamp = entry.slice(backupPrefix.length).match(/^(\d+)/)?.[1];
+        if (!timestamp)
+            continue;
+        const group = groups.get(timestamp) ?? [];
+        group.push(entry);
+        groups.set(timestamp, group);
+    }
+    const ordered = [...groups.entries()].sort((a, b) => Number(b[0]) - Number(a[0]));
+    const failures = [];
+    for (const [, entries] of ordered.slice(BACKUP_RETENTION_COUNT)) {
+        for (const entry of entries) {
+            const removed = await settle(files.remove(files.join(directory, entry)));
+            if (removed.failed)
+                failures.push(removed.cause);
+        }
+    }
+    if (failures.length > 0) {
+        databaseLogger(runtime).warn('[LocalDB] Failed to prune old backup files; the next prune retries them', {
+            reason: 'localdb-backup-prune-failed',
+            directory,
+            error: new AggregateError(failures, `Failed to remove ${failures.length} backup file(s)`)
+        });
+    }
+}
+/**
+ * Move a database file and its WAL/SHM sidecars aside as ONE timestamped backup
+ * set (via rename — preserves un-checkpointed WAL rows, removes the originals),
+ * then prune old backups. The single owned primitive for archiving a broken local
+ * DB; both migration recovery and {@link LocalDBManager.resetDatabase} use it so
+ * nobody reimplements it (e.g. a copyFile-based, WAL-dropping, unbounded variant).
+ *
+ * The directory listing is the fact it acts on: no database file means nothing
+ * to archive, and a sidecar moves only when it is present. A rename that fails
+ * for any other reason throws, because a database that cannot be moved aside
+ * cannot be recovered.
+ */
+async function archiveDatabaseFiles(runtime, dbPath) {
+    const logger = databaseLogger(runtime);
+    const files = await fileSystemOf(runtime);
+    const directory = files.dirname(dbPath);
+    const filename = files.basename(dbPath);
+    await files.mkdir(directory, { recursive: true });
+    const entries = new Set(await entryNames(files, directory));
+    if (!entries.has(filename)) {
+        logger.debug('[LocalDB] No database file to archive; opening a fresh one', { dbPath });
+        return;
+    }
+    const backupPath = files.join(directory, nextBackupName(filename, entries, Date.now()));
+    await files.rename(dbPath, backupPath);
+    for (const sidecar of DATABASE_SIDECARS) {
+        if (!entries.has(`${filename}${sidecar}`))
+            continue;
+        const moved = await settle(files.rename(`${dbPath}${sidecar}`, `${backupPath}${sidecar}`));
+        // A sidecar SQLite removed after the listing (its last connection closed) is
+        // confirmed absent by listing again; anything else is a failed move.
+        if (moved.failed && (await entryNames(files, directory)).includes(`${filename}${sidecar}`))
+            throw moved.cause;
+    }
+    logger.info(`[LocalDB] Moved database (with WAL/SHM) to: ${backupPath}`);
+    await pruneDatabaseBackups(runtime, files, directory, filename);
 }
-function isFileMissingError(error) {
-    if (!error || typeof error !== 'object')
-        return false;
-    return error.code === 'ENOENT';
+/**
+ * Thrown when a database's tracked schema version is NEWER than what this
+ * build knows — i.e. the running code is older than the data. Destroying the
+ * database here would let any stale binary wipe a newer store (this happened:
+ * a Feb-era compiled CLI trapdoored the presence inner-world DB). Namespaces
+ * that hold only derived, rebuildable data may opt into auto-reset via
+ * `registerMigrations(runtime, ns, migrations, { autoReset: true })`.
+ */
+export class IncompatibleDatabaseError extends CapabilityError {
+    namespace;
+    dbPath;
+    trackedVersion;
+    currentVersion;
+    constructor(namespace, dbPath, trackedVersion, currentVersion) {
+        super(`Database '${dbPath}' tracks schema version ${trackedVersion} for namespace '${namespace}', ` +
+            `newer than this build's max version ${currentVersion}. Refusing destructive recovery — ` +
+            `this process is likely running outdated code; upgrade or rebuild the binary. ` +
+            `(Derived-cache namespaces can opt into auto-reset via registerMigrations options.)`, 'CONFLICT', {
+            reason: 'localdb-incompatible-database',
+            retryable: false,
+            recoveryHint: 'Upgrade or rebuild the binary that opens this database.',
+            details: { namespace, dbPath, trackedVersion, currentVersion }
+        });
+        this.namespace = namespace;
+        this.dbPath = dbPath;
+        this.trackedVersion = trackedVersion;
+        this.currentVersion = currentVersion;
+        this.name = 'IncompatibleDatabaseError';
+    }
+}
+/**
+ * `UNAVAILABLE localdb-database-closed`: the handle was never initialized, or
+ * it closed (every runtime holding it released it, or ended and a disposal closed it).
+ */
+function notInitialized(dbPath) {
+    return new CapabilityError('The LocalDB database is not open: initialize it, or open it again.', 'UNAVAILABLE', {
+        reason: 'localdb-database-closed',
+        retryable: false,
+        details: { dbPath },
+        recoveryHint: 'Open the database again with localdb.getDatabase() on a live runtime.'
+    });
+}
+/**
+ * `UNAVAILABLE localdb-pool-unavailable`: a pooled call before any pool was
+ * handed over — neither the constructor's pool nor a runtime resolution.
+ */
+function missingPool() {
+    return new CapabilityError('The LocalDB connection pool is not available on this runtime yet.', 'UNAVAILABLE', {
+        reason: 'localdb-pool-unavailable',
+        retryable: false,
+        recoveryHint: 'Open the database through a runtime whose composition registered a pool (the LocalDB plugin does).'
+    });
 }
 export class LocalDatabase {
+    runtime;
+    migrations;
     db;
     options;
     initialized = false;
-    constructor(options) {
+    /** Whether this instance holds a connection: a pooled reference or an open direct handle. */
+    connected = false;
+    /** The explicitly shared physical pool, once resolved from the opening runtime. */
+    physicalPool;
+    /**
+     * @param runtime the opening caller's runtime: it reports the open,
+     *   migrations and any recovery, and a pooled connection it opens is
+     *   maintained on its lifecycle when it is persistent.
+     * @param pool the explicitly shared physical pool; when omitted it is
+     *   resolved from the opening runtime on `initialize()`.
+     */
+    constructor(runtime, options, migrations = migrationRegistry, pool) {
+        this.runtime = runtime;
+        this.migrations = migrations;
         this.options = {
             consumer: 'unknown',
             skipMigrations: false,
             usePool: true,
             ...options
         };
+        this.physicalPool = pool;
+    }
+    /**
+     * The explicitly shared physical pool: the constructor's pool, else the
+     * runtime's pool once an async call resolved it. A synchronous use before
+     * any resolution refuses typed instead of opening a second connection.
+     */
+    requirePool() {
+        const resolved = this.physicalPool ?? tryPoolOf(this.runtime);
+        if (!resolved)
+            throw missingPool();
+        return (this.physicalPool = resolved);
     }
     /**
      * Initialize the database connection
      * - Creates directory if needed
      * - Gets/creates pooled connection
      * - Runs pending migrations
+     *
+     * Ownership decides, not the `initialized` flag: a database that acquired
+     * a connection and then failed to initialize keeps that connection, so its
+     * cleanup stays reachable through `close()`. Retrying `initialize()` on
+     * such a handle refuses `CONFLICT localdb-database-open` naming the
+     * pending cleanup instead of silently replacing the physical connection;
+     * close it (or release the failure) first.
+     *
+     * A database that fails to initialize keeps no connection when its
+     * cleanup succeeds: the pooled reference is released (a direct connection
+     * closed) before the failure propagates, and this handle may initialize
+     * again.
      */
     async initialize() {
         if (this.initialized)
             return;
-        // Ensure directory exists
-        if (!isServerRuntime) {
-            throw new Error('LocalDatabase is not available in browser builds');
-        }
-        await mkdir(dirname(this.options.dbPath), { recursive: true });
-        // Get connection (pooled or direct)
-        this.establishConnection();
-        // Run migrations if needed
+        if (this.connected)
+            throw pendingCleanup();
+        this.physicalPool ??= await poolOf(this.runtime);
+        const files = await fileSystemOf(this.runtime);
+        await files.mkdir(files.dirname(this.options.dbPath), { recursive: true });
+        await this.establishConnection();
         if (!this.options.skipMigrations) {
-            try {
-                // Check for incompatible database from old migration system
-                if (migrationRegistry.isIncompatibleDatabase(this.db, this.options.namespace)) {
-                    logger.error(`[LocalDB] Detected incompatible database for ${this.options.namespace} (from legacy migration system). Initiating recovery...`);
-                    await this.performRecovery();
-                }
-                else if (migrationRegistry.needsMigration(this.db, this.options.namespace)) {
-                    await migrationRegistry.runMigrations(this.db, this.options.namespace);
-                }
-            }
-            catch (error) {
-                logger.error(`[LocalDB] Migration failed for ${this.options.namespace}. Initiating automatic recovery/trapdoor...`, toErrorContext(error));
-                await this.performRecovery();
+            const prepared = await settle(this.prepareSchema());
+            if (prepared.failed) {
+                this.releaseConnection(this.runtime);
+                throw prepared.cause;
             }
         }
         this.initialized = true;
     }
+    /**
+     * Bring the namespace's schema up to date. A failure fails closed (data
+     * preserved) unless the namespace opted into `autoReset`; then the
+     * database is archived and rebuilt from version 0.
+     */
+    async prepareSchema() {
+        const { namespace } = this.options;
+        const logger = databaseLogger(this.runtime);
+        const autoReset = this.migrations.allowsAutoReset(this.runtime, namespace);
+        const migrated = await settle(this.migrateInPlace(autoReset));
+        if (!migrated.failed) {
+            if (migrated.value.state === 'migrated')
+                return;
+            const { versions } = migrated.value;
+            logger.error(`[LocalDB] Incompatible database for ${namespace} (tracked v${versions.tracked} > known v${versions.current}); namespace allows auto-reset. Initiating recovery...`);
+            await this.performRecovery();
+            return;
+        }
+        if (migrated.cause instanceof IncompatibleDatabaseError)
+            throw migrated.cause;
+        if (!autoReset) {
+            logger.error(`[LocalDB] Migration failed for ${namespace}; auto-reset is disabled for this namespace, failing closed (data preserved).`, { reason: 'localdb-migration-failed', dbPath: this.options.dbPath, error: migrated.cause });
+            throw migrated.cause;
+        }
+        logger.error(`[LocalDB] Migration failed for ${namespace}. Initiating automatic recovery/trapdoor...`, {
+            reason: 'localdb-migration-failed',
+            dbPath: this.options.dbPath,
+            error: migrated.cause
+        });
+        await this.performRecovery();
+    }
+    /** Migrate in place; a newer database is refused, or reported for a reset when the namespace allows one. */
+    async migrateInPlace(autoReset) {
+        const { namespace, dbPath } = this.options;
+        // Database tracks a NEWER schema version than this build knows.
+        if (this.migrations.isIncompatibleDatabase(this.runtime, this.db, namespace)) {
+            const versions = this.migrations.describeVersions(this.runtime, this.db, namespace);
+            if (!autoReset)
+                throw new IncompatibleDatabaseError(namespace, dbPath, versions.tracked, versions.current);
+            return { state: 'incompatible', versions };
+        }
+        if (this.migrations.needsMigration(this.runtime, this.db, namespace)) {
+            await this.migrations.runMigrations(this.runtime, this.db, namespace);
+        }
+        return { state: 'migrated' };
+    }
     /**
      * Establish initial connection
      */
-    establishConnection() {
+    async establishConnection() {
+        if (this.options.usePool) {
+            this.db = await this.requirePool().getConnection(this.runtime, this.options.dbPath, this.options.consumer);
+        }
+        else {
+            // Direct connection (for special cases), through the same host driver.
+            const lifecycle = this.runtime.lifecycle;
+            const driver = await sqliteDriverOf(this.runtime);
+            const opened = await openConfiguredDatabase(this.runtime, () => driver.open(this.options.dbPath), applyLocalDatabasePragmas, lifecycle);
+            assertOpenedConnectionLive(this.runtime, opened, lifecycle);
+            this.db = opened;
+        }
+        this.connected = true;
+    }
+    /** Give the connection back, reported on `runtime`: release the pooled reference, or checkpoint and close a direct one. */
+    releaseConnection(runtime) {
+        if (!this.connected)
+            return;
         if (this.options.usePool) {
-            this.db = connectionPool.getConnection(this.options.dbPath, this.options.consumer);
+            this.requirePool().releaseConnection(runtime, this.options.dbPath);
         }
         else {
-            // Direct connection (for special cases)
-            this.db = new Database(this.options.dbPath);
-            this.configureDatabase(this.db);
+            this.checkpointBeforeDirectClose(runtime);
+            this.db.close();
         }
+        this.connected = false;
     }
     /**
      * Perform recovery from migration failure
      * 1. Close connection
-     * 2. Backup corrupted DB
-     * 3. Delete corrupted DB
-     * 4. Re-initialize fresh DB
-     * 5. Re-run migrations
+     * 2. Move the broken DB + WAL/SHM sidecars into a complete backup set
+     * 3. Re-initialize fresh DB
+     * 4. Re-run migrations
+     *
+     * The backup MUST include the WAL: un-checkpointed rows live only there,
+     * and a main-file-only copy silently drops them (the presence inner-world
+     * incident lost a multi-day WAL window exactly this way). A connection that
+     * cannot be closed stops the recovery before any file moves.
      */
     async performRecovery() {
+        assertRuntimeLive(this.runtime, 'database recovery');
+        this.assertCanReplace(this.runtime);
         // 1. Close the broken database
+        const logger = databaseLogger(this.runtime);
         if (this.options.usePool) {
-            connectionPool.closeConnection(this.options.dbPath, true);
+            this.requirePool().closeConnection(this.runtime, this.options.dbPath, true);
         }
         else {
             this.db.close();
         }
-        // 2. Backup the broken file
-        const backupPath = `${this.options.dbPath}.bak-${Date.now()}`;
-        try {
-            await copyFile(this.options.dbPath, backupPath);
-            logger.info(`[LocalDB] Backed up corrupted database to: ${backupPath}`);
-            await this.pruneBackupFiles();
-        }
-        catch (backupError) {
-            logger.error('[LocalDB] Failed to backup corrupted database:', toErrorContext(backupError));
-        }
-        // 3. Delete the broken file and WAL artifacts
-        try {
-            await unlink(this.options.dbPath);
-            await unlink(`${this.options.dbPath}-wal`).catch(() => { });
-            await unlink(`${this.options.dbPath}-shm`).catch(() => { });
-            logger.info('[LocalDB] Deleted corrupted database file.');
-        }
-        catch (deleteError) {
-            if (isFileMissingError(deleteError)) {
-                logger.info('[LocalDB] Corrupted database file already removed during recovery. Continuing...');
-            }
-            else {
-                logger.error('[LocalDB] Failed to delete corrupted database:', toErrorContext(deleteError));
-                throw deleteError; // If we can't delete, we can't recover.
-            }
-        }
-        // 4. Re-establish connection (creates new DB file)
+        this.connected = false;
+        // 2. Move the broken file AND its WAL/SHM sidecars aside as one backup set
+        // (owned primitive — preserves the WAL, prunes old backups).
+        await archiveDatabaseFiles(this.runtime, this.options.dbPath);
+        // 3. Re-establish connection (creates new DB file)
         logger.info('[LocalDB] Re-initializing fresh database...');
-        this.establishConnection();
-        // 5. Re-run migrations on fresh DB
-        try {
-            if (migrationRegistry.needsMigration(this.db, this.options.namespace)) {
-                await migrationRegistry.runMigrations(this.db, this.options.namespace);
-            }
-            logger.info('[LocalDB] Recovery successful. Database reset.');
-        }
-        catch (retryError) {
-            logger.error('[LocalDB] Recovery failed. Fresh database migration failed:', toErrorContext(retryError));
-            throw retryError;
-        }
-    }
-    async pruneBackupFiles() {
-        const directory = dirname(this.options.dbPath);
-        const filename = basename(this.options.dbPath);
-        const backupPrefix = `${filename}.bak-`;
-        const files = await readdir(directory).catch(() => []);
-        const backups = files
-            .filter((entry) => entry.startsWith(backupPrefix))
-            .map((entry) => ({ entry, timestamp: Number(entry.slice(backupPrefix.length)) }))
-            .sort((a, b) => {
-            if (Number.isNaN(a.timestamp) || Number.isNaN(b.timestamp)) {
-                return b.entry.localeCompare(a.entry);
-            }
-            return b.timestamp - a.timestamp;
-        });
-        for (const backup of backups.slice(BACKUP_RETENTION_COUNT)) {
-            await unlink(`${directory}/${backup.entry}`).catch(() => { });
+        await this.establishConnection();
+        // 4. Re-run migrations on fresh DB
+        const remigrated = await settle(this.runPendingMigrations());
+        if (remigrated.failed) {
+            logger.error('[LocalDB] Recovery failed. Fresh database migration failed', {
+                reason: 'localdb-recovery-failed',
+                dbPath: this.options.dbPath,
+                error: remigrated.cause
+            });
+            throw remigrated.cause;
+        }
+        logger.info('[LocalDB] Recovery successful. Database reset.');
+    }
+    async runPendingMigrations() {
+        if (this.migrations.needsMigration(this.runtime, this.db, this.options.namespace)) {
+            await this.migrations.runMigrations(this.runtime, this.db, this.options.namespace);
         }
     }
     /**
-     * Configure database with optimal settings (for non-pooled connections)
+     * Observed checkpoint before a direct (non-pooled) connection closes,
+     * reported on `runtime`. Busy outcomes are logged at warn; a SQLite failure
+     * is logged at error and never blocks the close.
      */
-    configureDatabase(db) {
-        db.exec('PRAGMA journal_mode = WAL;');
-        db.exec('PRAGMA busy_timeout = 5000;');
-        db.exec('PRAGMA foreign_keys = ON;');
-        db.exec('PRAGMA synchronous = NORMAL;');
-        db.exec('PRAGMA temp_store = MEMORY;');
+    checkpointBeforeDirectClose(runtime) {
+        if (this.db.inTransaction)
+            return;
+        const logger = databaseLogger(runtime);
+        const attempted = attempt(() => checkpointWal(this.db));
+        if (attempted.failed) {
+            logger.error('[LocalDB] WAL checkpoint failed', {
+                reason: 'wal-checkpoint-failed',
+                trigger: 'close',
+                dbPath: this.options.dbPath,
+                consumer: this.options.consumer,
+                error: attempted.cause
+            });
+            return;
+        }
+        const { status, ...outcome } = attempted.value;
+        const fields = { dbPath: this.options.dbPath, consumer: this.options.consumer, ...outcome };
+        if (status === 'busy') {
+            logger.warn('[LocalDB] WAL checkpoint busy', { reason: 'wal-checkpoint-busy', trigger: 'close', ...fields });
+        }
+        else {
+            logger.debug('[LocalDB] WAL checkpoint', { status, trigger: 'close', ...fields });
+        }
     }
     /**
      * Get the underlying Database instance
      */
     getDatabase() {
-        if (!this.initialized) {
-            throw new Error('Database not initialized. Call initialize() first.');
+        if (!this.initialized || (this.options.usePool && !this.requirePool().ownsConnection(this.options.dbPath, this.db))) {
+            throw notInitialized(this.options.dbPath);
         }
         return this.db;
     }
+    /** Preserve every other physical borrower before this instance is reset or recovered. */
+    assertCanReplace(runtime) {
+        this.requirePool().assertCanReplaceDatabase(runtime, this.options.dbPath, this.connected && this.options.usePool ? this.db : undefined);
+    }
     /**
-     * Close the database connection
+     * Close the database connection, reported on the releasing runtime (which
+     * may differ from the runtime that opened it: the manager shares one
+     * instance per `namespace:path`).
+     *
+     * Cleanup runs whenever this handle owns a connection, including a handle
+     * whose initialization failed: its acquired connection stays reachable for
+     * cleanup instead of being abandoned (close before `initialized` became
+     * true was previously a no-op).
      */
-    close() {
-        if (!this.initialized)
-            return;
-        if (this.options.usePool) {
-            // Release back to pool
-            connectionPool.releaseConnection(this.options.dbPath);
-        }
-        else {
-            // Direct close
-            this.db.close();
-        }
+    close(runtime) {
+        this.releaseConnection(runtime);
         this.initialized = false;
     }
     /**
-     * Check if database is healthy
+     * Check if database is healthy. A health probe answers false, with the
+     * reason logged on the probing runtime.
      */
-    healthCheck() {
+    healthCheck(runtime) {
         if (!this.initialized)
             return false;
-        try {
-            const result = this.db.query('SELECT 1').get();
-            return result !== null;
-        }
-        catch {
+        const probe = attempt(() => this.db.prepare('SELECT 1 AS ok').get());
+        if (probe.failed) {
+            databaseLogger(runtime).warn('[LocalDB] Health check query failed', {
+                reason: 'localdb-health-check-failed',
+                dbPath: this.options.dbPath,
+                error: probe.cause
+            });
             return false;
         }
+        return probe.value !== null;
     }
     /**
      * Get migration status for this database
      */
     getMigrationStatus() {
-        if (!this.initialized) {
-            throw new Error('Database not initialized');
+        if (!this.initialized || (this.options.usePool && !this.requirePool().ownsConnection(this.options.dbPath, this.db))) {
+            throw notInitialized(this.options.dbPath);
         }
-        return migrationRegistry.getDatabaseStatus(this.db, this.options.namespace);
+        return this.migrations.getDatabaseStatus(this.runtime, this.db, this.options.namespace);
     }
 }
+/** Whether `holder` is `runtime` or reads its lifecycle (a view of it). */
+function sameHolder(holder, runtime) {
+    return releasesHolder(holder, runtime);
+}
+/** A runtime that ended holds nothing: drop it, as the pool drops ended holders. */
+function dropEnded(holders) {
+    for (const holder of holders.keys()) {
+        if (holder.lifecycle.signal.aborted)
+            holders.delete(holder);
+    }
+}
+/** Record one more reference for `runtime` (dropping runtimes that ended); returns `holders`. */
+function hold(holders, runtime) {
+    dropEnded(holders);
+    holders.set(runtime, (holders.get(runtime) ?? 0) + 1);
+    return holders;
+}
+/**
+ * Give back one of `runtime`'s references: its own, or one taken by a view of
+ * it (any runtime object reading the same lifecycle). A fork or reload
+ * generation of the same root has its own lifecycle and never releases the
+ * root's reference; a runtime that holds nothing releases nothing.
+ */
+function release(holders, runtime) {
+    dropEnded(holders);
+    const holder = [...holders.keys()].find((candidate) => sameHolder(candidate, runtime));
+    if (holder === undefined)
+        return;
+    const count = holders.get(holder) ?? 0;
+    if (count > 1)
+        holders.set(holder, count - 1);
+    else
+        holders.delete(holder);
+}
+/** Give back every reference `runtime` releases ({@link releasesHolder}), and drop runtimes that ended. */
+function releaseAll(holders, runtime) {
+    for (const holder of holders.keys()) {
+        if (releasesHolder(holder, runtime))
+            holders.delete(holder);
+    }
+    dropEnded(holders);
+}
+/** Whether `value` is a kernel `runtime/client` descriptor (rather than a registry). */
+function isClientDescriptor(value) {
+    return RuntimeClientDescriptorSchema.safeParse(value).success;
+}
+/**
+ * `CONFLICT localdb-database-open`: the handle still owns a connection from a
+ * failed initialization, so reinitializing would abandon it. Close the handle
+ * (or release the failure) first.
+ */
+function pendingCleanup() {
+    return new CapabilityError('The LocalDB database still holds a connection from a failed initialization; close it before initializing again.', 'CONFLICT', {
+        reason: 'localdb-database-open',
+        retryable: false,
+        recoveryHint: 'Call close(runtime) on this handle first, or retry close until the driver accepts it.'
+    });
+}
+/** The typed refusal when LocalDB is asked to act without the runtime that owns the call. */
+function missingRuntime() {
+    return new CapabilityError('A runtime is required for LocalDB access', 'INVALID_INPUT', {
+        reason: 'localdb-runtime-required',
+        retryable: false,
+        recoveryHint: 'Resolve dev/localdb on the runtime making this call.'
+    });
+}
 /**
  * LocalDB Manager
- * Main entry point for accessing local databases
+ *
+ * The runtime-owned logical owner of LocalDB access: one instance per
+ * runtime, resolved through the kernel as the `localdb` `runtime/client`
+ * (see `src/localdb.client.descriptor.ts`) via `getVibesClient` (async) or
+ * `tryGetVibesClient` (synchronously, once activation warmed the cache).
+ * The `dev/localdb` context resolves to this same instance. Physical
+ * connections stay shared per path in the runtime's pool — an explicitly
+ * shared pool when the composition root registered one, else the plugin's
+ * runtime-owned default; each client only tracks its own runtime's logical
+ * holdings, so one runtime's release or disposal never closes a database
+ * another live runtime holds.
  */
-class LocalDBManager {
-    databases = new Map();
-    dbPathLocks = new Map();
-    async withDbPathLock(dbPath, task) {
-        const prior = this.dbPathLocks.get(dbPath) ?? Promise.resolve();
-        let release;
-        const current = new Promise((resolve) => {
-            release = resolve;
-        });
-        const queued = prior.then(() => current);
-        this.dbPathLocks.set(dbPath, queued);
-        await prior;
+export class LocalDBManager extends BaseRuntimeClient {
+    poolResolution;
+    migrations;
+    owner;
+    /**
+     * The runtime's physical pool, once resolved: an explicitly shared pool
+     * when the composition root registered one, else the runtime-owned
+     * default. Cached because disposal paths must reach it without
+     * re-resolving through a runtime whose lifecycle already ended.
+     */
+    physicalPool;
+    constructor(descriptorOrMigrations = migrationRegistry, contextOrOwner, runtime) {
+        if (isClientDescriptor(descriptorOrMigrations)) {
+            // SAFETY: a runtime/client descriptor selects the kernel constructor overload, whose second argument is KindContext.
+            super(descriptorOrMigrations, contextOrOwner, runtime);
+            this.migrations = migrationRegistry;
+            this.owner = this.runtime;
+            // Full lifecycle integration belongs to runtimes that composed the
+            // plugin: a root runtime releases in inverse plugin dependency order via
+            // localdb.plugin.ts onDispose (so dependent plugins like browser-automation
+            // finish their disposal writes first); reload-generation forks whose
+            // borrowed plugin lifetimes finalize once on the root release via
+            // releaseAtDisposal. Runtimes reached only through the compatibility
+            // fallback below keep the legacy behavior — their disposal closes nothing.
+            this.ensureBorrowedDisposal(this.runtime);
+        }
+        else {
+            // SAFETY: the legacy registry overload accepts its explicit RuntimeRef owner as the second argument.
+            const owner = contextOrOwner;
+            if (!owner)
+                throw missingRuntime();
+            super({ id: 'localdb', kind: 'runtime/client', description: 'Runtime-owned logical LocalDB access' }, undefined, owner);
+            this.migrations = descriptorOrMigrations;
+            this.owner = owner;
+        }
+    }
+    ensureBorrowedDisposal(runtime) {
+        if (runtime.hasPlugin('localdb') && !hasDirectPluginDisposal(runtime)) {
+            releaseAtDisposal(runtime, this);
+        }
+    }
+    requireOwner() {
+        return this.owner;
+    }
+    /** A kernel-owned API serves its runtime, a view of that same lifecycle, or a reload generation sharing this retained client. */
+    assertOwner(runtime) {
+        if (this.owner &&
+            this.owner.lifecycle.signal !== runtime.lifecycle.signal &&
+            cachedPoolClient(runtime) !== this) {
+            throw new CapabilityError('The LocalDB API belongs to another runtime.', 'CONFLICT', {
+                reason: 'localdb-runtime-mismatch', retryable: false,
+                recoveryHint: 'Resolve dev/localdb on the runtime making this call.'
+            });
+        }
+    }
+    /**
+     * Resolve the owning runtime's physical pool through the kernel and cache
+     * it. Always resolved from the owner — never from the calling view — so
+     * lifecycle views of the owner share the owner's pool. The first resolved
+     * physical owner stays captured for this client, including disposal, which must
+     * reach the pool without re-resolving through a runtime whose lifecycle
+     * already ended.
+     */
+    async ensurePool() {
+        if (this.physicalPool)
+            return this.physicalPool;
+        this.poolResolution ??= poolOf(this.requireOwner());
         try {
-            return await task();
+            this.physicalPool ??= await this.poolResolution;
+            return this.physicalPool;
         }
         finally {
-            release?.();
-            if (this.dbPathLocks.get(dbPath) === queued) {
-                this.dbPathLocks.delete(dbPath);
-            }
+            this.poolResolution = undefined;
         }
     }
+    /** Physical owner shared by managed access and the public pool facade. */
+    getConnectionPool() {
+        return this.requirePool();
+    }
+    /**
+     * The cached pool, else the runtime's already-resolved pool. A use before
+     * any resolution refuses typed instead of opening a second connection.
+     */
+    requirePool() {
+        const resolved = this.physicalPool ?? tryPoolOf(this.requireOwner());
+        if (!resolved)
+            throw missingPool();
+        return (this.physicalPool = resolved);
+    }
+    /**
+     * Managed databases per `namespace:path` within this manager. The kernel's
+     * context instance owns a manager and its registrations. `holders` counts open references, so
+     * one runtime's release or disposal (a root, or a reload generation forked
+     * from it) never closes a database another live runtime holds.
+     */
+    databases = new Map();
+    /** In-flight `closeAll` per runtime: concurrent calls for one runtime share it; two runtimes never do. */
+    closeAllPromises = new Map();
+    /**
+     * Register migrations for a namespace, reported on the registering runtime.
+     * Must be called before getDatabase() for that namespace.
+     */
+    registerMigrations(runtime, namespace, migrations, options) {
+        this.assertOwner(runtime);
+        this.migrations.register(runtime, namespace, migrations, options);
+    }
     /**
-     * Register migrations for a namespace
-     * Must be called before getDatabase() for that namespace
+     * Guarded repair for a namespace whose registered migration set is known to
+     * be incomplete. The caller must provide the exact ids it observed.
      */
-    registerMigrations(namespace, migrations) {
-        migrationRegistry.register(namespace, migrations);
+    replaceMigrations(runtime, namespace, migrations, options) {
+        this.assertOwner(runtime);
+        return this.migrations.replaceMigrations(runtime, namespace, migrations, options);
     }
     /**
      * Get or create a database instance
      *
+     * @param runtime The calling runtime: it reports the open, and a persistent
+     *   one can carry the connection's maintenance
      * @param namespace Migration namespace (e.g., 'atlas', 'session')
      * @param dbPath Path to database file
      * @param consumer Consumer identifier for debugging
-     * @returns Initialized database instance
+     * @returns Initialized database instance; a runtime whose disposal began
+     *   (checked once the path's lock is held) is refused `CANCELLED`
+     *   `runtime-disposed` and holds nothing
      */
-    getDatabase(namespace, dbPath, consumer) {
+    async getDatabase(runtime, namespace, dbPath, consumer) {
         const key = `${namespace}:${dbPath}`;
-        return this.withDbPathLock(dbPath, async () => {
+        const pool = await this.ensurePool();
+        return pool.withDatabasePathLock(dbPath, async () => {
+            this.assertOwner(runtime);
+            assertRuntimeLive(runtime, 'database open');
+            this.ensureBorrowedDisposal(runtime);
             const existing = this.databases.get(key);
             if (existing) {
-                existing.references += 1;
+                hold(existing.holders, runtime);
+                // Another runtime may have opened it: this caller holds it now too.
+                pool.retain(runtime, dbPath);
                 return existing.database;
             }
-            if (!this.databases.has(key)) {
-                const db = new LocalDatabase({
-                    namespace,
-                    dbPath,
-                    consumer
-                });
-                await db.initialize();
-                this.databases.set(key, {
-                    database: db,
-                    references: 1
-                });
-            }
-            return this.databases.get(key).database;
+            const database = new LocalDatabase(runtime, {
+                namespace,
+                dbPath,
+                consumer
+            }, this.migrations, pool);
+            await database.initialize();
+            this.databases.set(key, { database, dbPath, holders: hold(new Map(), runtime) });
+            return database;
         });
     }
     /**
      * Get a raw Database instance (auto-configured with WAL, etc.)
      * For when you don't need migration management
      */
-    getRawDatabase(dbPath, consumer = 'raw') {
-        return connectionPool.getConnection(dbPath, consumer);
+    async getRawDatabase(runtime, dbPath, consumer = 'raw') {
+        const pool = await this.ensurePool();
+        return pool.withDatabasePathLock(dbPath, async () => {
+            this.assertOwner(runtime);
+            this.ensureBorrowedDisposal(runtime);
+            return pool.getConnection(runtime, dbPath, consumer);
+        });
     }
     /**
-     * Release a database instance
+     * Release a database instance, reported on the releasing runtime
      */
-    async releaseDatabase(namespace, dbPath) {
+    async releaseDatabase(runtime, namespace, dbPath) {
+        this.assertOwner(runtime);
         const key = `${namespace}:${dbPath}`;
-        await this.withDbPathLock(dbPath, async () => {
+        const pool = await this.ensurePool();
+        await pool.withDatabasePathLock(dbPath, async () => {
             const entry = this.databases.get(key);
-            if (!entry)
+            if (!entry) {
+                // Another runtime's client may have been the only owner and
+                // ended since: give back one reference no live runtime holds
+                // so a dead holder's pooled reference cannot leak.
+                pool.releaseOrphanedConnection(dbPath);
                 return;
-            entry.references = Math.max(0, entry.references - 1);
-            if (entry.references === 0) {
-                await entry.database.close();
+            }
+            release(entry.holders, runtime);
+            if (entry.holders.size === 0) {
+                entry.database.close(runtime);
+                this.databases.delete(key);
+            }
+        });
+    }
+    /**
+     * Reset a database: force-close any open handle, archive the existing file and
+     * its WAL/SHM sidecars aside as one pruned backup set, then re-open a fresh DB
+     * (re-running the namespace's migrations). This is the owned recovery path for
+     * consumers that detect app-level corruption the migration layer can't see
+     * (e.g. a missing core table) — they delegate here instead of hand-rolling
+     * copy/remove of the file, which drops the WAL and never prunes.
+     * Another live lifecycle or raw reference refuses before any handle closes
+     * or file moves. A handle that cannot be closed also stops the reset.
+     *
+     * @returns the freshly re-initialized database instance (references = 1). A
+     *   runtime whose disposal began is refused before anything closes or moves.
+     */
+    async resetDatabase(runtime, namespace, dbPath, consumer) {
+        const key = `${namespace}:${dbPath}`;
+        const pool = await this.ensurePool();
+        return pool.withDatabasePathLock(dbPath, async () => {
+            this.assertOwner(runtime);
+            assertRuntimeLive(runtime, 'database reset');
+            this.ensureBorrowedDisposal(runtime);
+            const existing = this.databases.get(key);
+            if (existing)
+                existing.database.assertCanReplace(runtime);
+            else
+                pool.assertCanReplaceDatabase(runtime, dbPath);
+            if (existing) {
+                existing.database.close(runtime);
                 this.databases.delete(key);
             }
+            // Force-evict any pooled connection for this path: close() only RELEASES a
+            // pooled connection, which would leave a live handle on the file we are
+            // about to rename aside and let getDatabase() re-use it (pool is keyed by
+            // path). performRecovery() force-closes for the same reason.
+            pool.closeConnection(runtime, dbPath, true);
+            await archiveDatabaseFiles(runtime, dbPath);
+            const db = new LocalDatabase(runtime, { namespace, dbPath, consumer }, this.migrations, pool);
+            await db.initialize();
+            this.databases.set(key, { database: db, dbPath, holders: hold(new Map(), runtime) });
+            return db;
         });
     }
     /**
-     * Get connection pool statistics
+     * Get connection pool statistics for the calling runtime's pool.
      */
-    getPoolStats() {
-        return connectionPool.getStats();
+    getPoolStats(runtime = this.requireOwner()) {
+        this.assertOwner(runtime);
+        return this.requirePool().getStats();
     }
     /**
      * Get migration registry status
      */
-    getMigrationStatus() {
-        return migrationRegistry.getStatus();
+    getMigrationStatus(runtime = this.requireOwner()) {
+        this.assertOwner(runtime);
+        return this.migrations.getStatus(runtime);
     }
     /**
      * List all registered migration namespaces
      */
-    listNamespaces() {
-        return migrationRegistry.listNamespaces();
+    listNamespaces(runtime = this.requireOwner()) {
+        this.assertOwner(runtime);
+        return this.migrations.listNamespaces(runtime);
+    }
+    /**
+     * Resolve the owner-declared database location for a namespace (see
+     * `RegisterMigrationsOptions.location`). Undefined when undeclared;
+     * propagates resolver throws.
+     */
+    getNamespaceLocation(namespace, runtime = this.requireOwner()) {
+        this.assertOwner(runtime);
+        return this.migrations.getNamespaceLocation(runtime, namespace);
     }
     /**
-     * Close all database connections
+     * Give back every database and connection the closing runtime holds,
+     * reported on that runtime, and close those no live runtime holds. Ones
+     * another live runtime holds (another root, or a root and its reload
+     * generations) stay open for it.
+     *
+     * Concurrent calls for one runtime share one operation; calls for two
+     * runtimes never do. Successful entries are
+     * removed as they close; failed entries remain registered so a later call can
+     * retry them.
+     */
+    closeAll(runtime) {
+        this.assertOwner(runtime);
+        const inFlight = this.closeAllPromises.get(runtime.lifecycle.signal);
+        if (inFlight)
+            return inFlight;
+        const closing = this.closeEverything(runtime).finally(() => {
+            this.closeAllPromises.delete(runtime.lifecycle.signal);
+        });
+        this.closeAllPromises.set(runtime.lifecycle.signal, closing);
+        return closing;
+    }
+    /**
+     * Give back every reference `runtime` holds and drop runtimes that ended,
+     * then close each database no live runtime holds, under its path's lock.
+     * The pool then does the same for its connections.
      */
-    async closeAll() {
-        for (const entry of this.databases.values()) {
-            await entry.database.close();
+    async closeEverything(runtime) {
+        // Release what this runtime holds, drop runtimes that ended, then close every
+        // database no live runtime holds — including one orphaned by a runtime that
+        // ended without disposing LocalDB, so no later caller reuses a closed handle.
+        for (const entry of this.databases.values())
+            releaseAll(entry.holders, runtime);
+        const pool = this.physicalPool ?? tryPoolOf(this.requireOwner());
+        if (!pool && this.databases.size === 0)
+            return;
+        const activePool = pool ?? this.requirePool();
+        const settled = await Promise.all([...this.databases.entries()]
+            .filter(([, entry]) => entry.holders.size === 0)
+            .map(([key, entry]) => 
+        // Under the path's lock, as every open is: an open that took a holding meanwhile keeps the entry.
+        activePool.withDatabasePathLock(entry.dbPath, async () => {
+            if (this.databases.get(key) !== entry || entry.holders.size > 0)
+                return undefined;
+            const closed = await settle(Promise.resolve().then(() => entry.database.close(runtime)));
+            if (!closed.failed)
+                this.databases.delete(key);
+            return { key, dbPath: entry.dbPath, closed };
+        })));
+        const results = settled.filter((result) => result !== undefined);
+        const failures = [];
+        const retainedPaths = new Set();
+        for (const { key, dbPath, closed } of results) {
+            if (closed.failed) {
+                retainedPaths.add(dbPath);
+                failures.push(new Error(`Failed to release LocalDB database '${key}'`, { cause: closed.cause }));
+            }
+        }
+        const closed = attempt(() => activePool.closeAll(runtime, retainedPaths));
+        if (closed.failed) {
+            failures.push(new Error('Failed to close the LocalDB connection pool', { cause: closed.cause }));
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures, `LocalDB disposal failed for ${failures.length} resource${failures.length === 1 ? '' : 's'}`);
+        }
+    }
+}
+/**
+ * Register the `localdb` client owner on runtimes that never composed the
+ * plugin (storage-adapter-style callers), so async entrypoints still resolve
+ * exactly one kernel-cached client per runtime instead of guessing an owner.
+ * The check and the registration are synchronous once the `runtime/client`
+ * kind exists, so concurrent first calls cannot register twice.
+ */
+async function ensureClientOwner(runtime) {
+    if (!runtime.hasKind('runtime/client'))
+        await runtime.registerPlugin(runtimeClientPlugin);
+    // Storage-adapter-style callers never composed the plugin: they still get
+    // the runtime-owned default pool, so their opens share one connection per
+    // path exactly like plugin-composed runtimes.
+    ensureDefaultPool(runtime);
+    if (runtime.query('runtime/client').withId('localdb').descriptors().length > 0)
+        return;
+    runtime.registerDescriptor('runtime/client', {
+        kind: 'runtime/client',
+        id: 'localdb',
+        description: 'Runtime-owned logical LocalDB access'
+    });
+    runtime.registerLoader('runtime/client', 'localdb', async () => ({ impl: LocalDBManager }));
+}
+/** Per-lifecycle LocalDBManager for reload-generation forks whose retained kernel client belongs to their root. */
+const forkClientCache = new WeakMap();
+/** Resolve (registering the owner first when needed) the calling runtime's owned LocalDB client. */
+export async function resolveLocaldbClient(runtime) {
+    await ensureClientOwner(runtime);
+    const client = await getVibesClient('localdb', runtime);
+    if (client.runtime.lifecycle.signal === runtime.lifecycle.signal)
+        return client;
+    let forkClient = forkClientCache.get(runtime.lifecycle.signal);
+    if (!forkClient) {
+        forkClient = new LocalDBManager({ id: 'localdb', kind: 'runtime/client', description: 'Runtime-owned logical LocalDB access' }, undefined, runtime);
+        forkClientCache.set(runtime.lifecycle.signal, forkClient);
+    }
+    return forkClient;
+}
+const loadedClient = resolveLocaldbClient;
+/** The captured client remains reachable through the kernel while disposal finalizes. */
+function cachedPoolClient(runtime) {
+    const forked = forkClientCache.get(runtime.lifecycle.signal);
+    if (forked)
+        return forked;
+    if (runtime.lifecycle.signal.aborted && runtime.hasKind('runtime/client')) {
+        const peeked = runtime.query('runtime/client').withId('localdb').peek?.();
+        return peeked?.runtime.lifecycle.signal === runtime.lifecycle.signal ? peeked : undefined;
+    }
+    const resolved = tryGetVibesClient('localdb', runtime);
+    return resolved?.runtime.lifecycle.signal === runtime.lifecycle.signal ? resolved : undefined;
+}
+/** Resolve the facade through the same semantic owner as managed databases. */
+export async function ownedPoolOf(runtime) {
+    const cached = cachedPoolClient(runtime);
+    if (cached)
+        return cached.ensurePool();
+    // Preserve pool registration, loader and validation refusals before adding
+    // the compatibility client for hosts that composed only the pool kind.
+    await poolOf(runtime);
+    return (await loadedClient(runtime)).ensurePool();
+}
+/** Synchronous facade access never reselects a captured physical owner. */
+export function tryOwnedPoolOf(runtime) {
+    return cachedPoolClient(runtime)?.getConnectionPool();
+}
+/**
+ * Stateless runtime-backed compatibility access to the calling runtime's
+ * owned LocalDB client. Every method takes the runtime it serves first and
+ * delegates to that runtime's `localdb` client — no ambient manager, no
+ * ambient runtime, no per-runtime cache beside the kernel's own. Synchronous
+ * methods query the runtime's migration descriptors directly; async methods
+ * resolve the kernel-owned client (registering its owner when needed) on demand.
+ * Runtime-optional migration reads refuse `INVALID_INPUT localdb-runtime-required`
+ * when no runtime is supplied; they never choose an owner.
+ */
+export const localdb = {
+    registerMigrations(runtime, namespace, migrations, options) {
+        migrationRegistry.register(runtime, namespace, migrations, options);
+    },
+    getNamespaceLocation(namespace, runtime) {
+        if (!runtime)
+            throw missingRuntime();
+        return migrationRegistry.getNamespaceLocation(runtime, namespace);
+    },
+    replaceMigrations(runtime, namespace, migrations, options) {
+        return migrationRegistry.replaceMigrations(runtime, namespace, migrations, options);
+    },
+    async getDatabase(runtime, namespace, dbPath, consumer) {
+        // Refuse before kernel client resolution, whose own disposed-runtime
+        // refusal would otherwise surface a different code for this condition.
+        assertRuntimeLive(runtime, 'database open');
+        const client = await loadedClient(runtime);
+        return client.getDatabase(runtime, namespace, dbPath, consumer);
+    },
+    async getRawDatabase(runtime, dbPath, consumer) {
+        assertRuntimeLive(runtime, 'connection');
+        const client = await loadedClient(runtime);
+        return client.getRawDatabase(runtime, dbPath, consumer);
+    },
+    async releaseDatabase(runtime, namespace, dbPath) {
+        const cached = cachedPoolClient(runtime);
+        if (cached)
+            return cached.releaseDatabase(runtime, namespace, dbPath);
+        if (runtime.lifecycle.signal.aborted) {
+            const pool = abortedPool(runtime);
+            if (!pool)
+                return;
+            return pool.withDatabasePathLock(dbPath, async () => {
+                pool.releaseOrphanedConnection(dbPath);
+            });
+        }
+        return (await loadedClient(runtime)).releaseDatabase(runtime, namespace, dbPath);
+    },
+    async resetDatabase(runtime, namespace, dbPath, consumer) {
+        assertRuntimeLive(runtime, 'database reset');
+        const client = await loadedClient(runtime);
+        return client.resetDatabase(runtime, namespace, dbPath, consumer);
+    },
+    getPoolStats(runtime) {
+        const client = runtime ? cachedPoolClient(runtime) : undefined;
+        if (!client)
+            throw runtime ? missingPool() : missingRuntime();
+        return client.getPoolStats(runtime);
+    },
+    getMigrationStatus(runtime) {
+        if (!runtime)
+            throw missingRuntime();
+        return migrationRegistry.getStatus(runtime);
+    },
+    listNamespaces(runtime) {
+        if (!runtime)
+            throw missingRuntime();
+        return migrationRegistry.listNamespaces(runtime);
+    },
+    closeAll(runtime) {
+        if (!runtime.lifecycle.signal.aborted) {
+            const cached = cachedPoolClient(runtime);
+            if (cached)
+                return cached.closeAll(runtime);
+            return loadedClient(runtime).then(client => client.closeAll(runtime));
         }
-        this.databases.clear();
-        connectionPool.closeAll();
+        return Promise.resolve().then(() => {
+            const cached = cachedPoolClient(runtime);
+            if (cached)
+                return cached.closeAll(runtime);
+            abortedPool(runtime)?.closeAll(runtime);
+        });
     }
+};
+/**
+ * The runtime's pool on a lifecycle that already ended: the kernel cache when
+ * it is still reachable, else `undefined` (disposal already gave back what
+ * that runtime held, so there is nothing left to release).
+ */
+function abortedPool(runtime) {
+    return tryOwnedPoolOf(runtime);
+}
+/** Runtimes whose own LocalDB plugin registration still owns `onDispose` at plugin finalization time. */
+const directPluginDisposalSignals = new WeakSet();
+const releaseAtDisposalSignals = new WeakSet();
+export function markDirectPluginDisposal(runtime) {
+    directPluginDisposalSignals.add(runtime.lifecycle.signal);
+}
+export function clearDirectPluginDisposal(runtime) {
+    directPluginDisposalSignals.delete(runtime.lifecycle.signal);
+}
+function hasDirectPluginDisposal(runtime) {
+    return directPluginDisposalSignals.has(runtime.lifecycle.signal);
+}
+/** The longest a deferred release waits for its runtime's disposal: the largest delay a host timer honours. */
+const RELEASE_AT_DISPOSAL_WAIT_MS = 2_147_483_647;
+/**
+ * Give back what `runtime` holds when its lifecycle ends, as work that
+ * lifecycle owns and joins at its disposal. The LocalDB plugin is disposed on a
+ * live lifecycle when a reload retires it from a runtime that lives on (the
+ * kernel then never disposes it again): the runtime's holdings are released
+ * when that runtime itself is disposed, reported on it.
+ */
+export function releaseAtDisposal(runtime, api = localdb) {
+    const { signal } = runtime.lifecycle;
+    if (releaseAtDisposalSignals.has(signal))
+        return;
+    releaseAtDisposalSignals.add(signal);
+    const ended = new Promise((resolve) => {
+        signal.addEventListener('abort', () => resolve(), { once: true });
+    });
+    const waiting = runtime.lifecycle.wait(async () => {
+        await ended;
+        const released = await settle(api.closeAll(runtime));
+        if (released.failed) {
+            databaseLogger(runtime).error('[LocalDB] Failed to release databases at disposal', {
+                reason: 'localdb-release-at-disposal-failed',
+                error: released.cause
+            });
+        }
+    }, { timeoutMs: RELEASE_AT_DISPOSAL_WAIT_MS, reason: 'localdb-release-at-disposal' });
+    // The wait ends (cancelled) when disposal begins; the work then runs and disposal joins it.
+    void observeReleaseWait(runtime, waiting);
+}
+/** A cancelled wait is the expected end (disposal began); any other end of the wait is reported. */
+async function observeReleaseWait(runtime, waiting) {
+    const waited = await settle(waiting);
+    if (!waited.failed)
+        return;
+    const caught = CaughtFailureSchema.parse(waited.cause);
+    if (isCapabilityError(caught) && caught.code === 'CANCELLED')
+        return;
+    databaseLogger(runtime).warn('[LocalDB] The release at disposal stopped waiting', {
+        reason: 'localdb-release-at-disposal-unwaited',
+        error: caught
+    });
+}
+/**
+ * Release every managed and raw LocalDB connection without assuming ownership
+ * of the process, reported on `runtime`. Runtime plugins and executable hosts
+ * call this from their lifecycle owner.
+ */
+export function disposeLocalDatabaseConnections(runtime) {
+    return localdb.closeAll(runtime);
 }
-// Singleton instance
-export const localdb = new LocalDBManager();
 //# sourceMappingURL=database.js.map