@vibesdotdev/storage 0.0.1 → 1.0.0-rc.3

package/dist/adapters/localdb/localdb.adapter.impl.js

@@ -0,0 +1,1370 @@
+/**
+ * LocalDB Storage Adapter Implementation
+ *
+ * SQLite-based persistent storage for consumer hardware.
+ * Implements StorageAdapterInterface with document, key-value, and repository support.
+ *
+ * SERVER-ONLY: opens SQLite through LocalDB's host driver and reaches the
+ * filesystem through the runtime's `filesystem/adapter` kind. Do not import in
+ * browser bundles.
+ */
+import { CapabilityError, createRuntimeImplementation, valueFreeFailure } from '@vibesdotdev/kernel';
+import { DocumentRevisionMetadataSchema, DocumentRevisionSchema } from "../../schemas/document-revision.js";
+import { StorageRecord } from '@vibesdotdev/storage/record';
+import { resolveGlobalStorageBasePath, resolveScopePathTemplate } from '@vibesdotdev/storage/paths';
+import { fileSystemOf, localdb, LocalDatabase, migrationRegistry } from '@vibesdotdev/localdb';
+import { sqliteFailureCondition } from '@vibesdotdev/localdb/sqlite-driver';
+import { getLogger } from '@vibesdotdev/logging';
+import { isAppliedMigrationFailure } from "./migration-failure.js";
+import { attempt, settle } from "./outcome.js";
+import { DbRowsSchema, IdentifiedItemSchema, isAbsoluteHostPath, KeyTextSchema, LocalDBConfigFieldsSchema, LocalDBManifestHintsSchema, LocalDBScopeInputsSchema, RowsLayerSchema, SQL_IDENTIFIER } from "./localdb.inputs.js";
+import { matchesRepositoryQuery, repositoryFieldsOf, RepositoryFieldsSchema, RepositoryKeySchema, sortRepositoryRows } from "./repository-query.js";
+import { parseAdapterInput } from "../parse-adapter-input.js";
+import { readStoredLayer, validateForPersist } from "../validate-for-persist.js";
+/** The database file a configuration names when it names none. */
+const DEFAULT_DB_NAME = 'vibes-storage.db';
+/** How many times an atomic document update re-reads and retries before it reports contention. */
+const DOCUMENT_UPDATE_ATTEMPTS = 64;
+/**
+ * Escape a `LIKE` pattern's metacharacters (`%`, `_`, and the escape char)
+ * with the pattern's declared escape, so a literal namespace prefix with `%`
+ * or `_` (URL-encoded partition ids may contain neither, but be explicit)
+ * cannot widen the `SELECT DISTINCT namespace` discovery scan.
+ */
+function escapeSqlLike(literal) {
+    return literal.replaceAll('\\', '\\\\').replaceAll('%', '\\%').replaceAll('_', '\\_');
+}
+const STORAGE_MIGRATIONS = [
+    {
+        version: 1,
+        name: 'Create storage tables',
+        up: (db) => {
+            // Document store
+            db.exec(`
+				CREATE TABLE IF NOT EXISTS vibes_documents (
+					namespace TEXT PRIMARY KEY,
+					data TEXT NOT NULL,
+					updated_at TEXT DEFAULT CURRENT_TIMESTAMP
+				)
+			`);
+            // Key-value store
+            db.exec(`
+				CREATE TABLE IF NOT EXISTS vibes_kv (
+					namespace TEXT NOT NULL,
+					key TEXT NOT NULL,
+					value TEXT NOT NULL,
+					expires_at INTEGER,
+					PRIMARY KEY (namespace, key)
+				)
+			`);
+            db.exec(`CREATE INDEX IF NOT EXISTS vibes_kv_expires ON vibes_kv(expires_at) WHERE expires_at IS NOT NULL`);
+            // Repository store
+            db.exec(`
+				CREATE TABLE IF NOT EXISTS vibes_repository (
+					tablename TEXT NOT NULL,
+					id TEXT NOT NULL,
+					data TEXT NOT NULL,
+					created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+					updated_at TEXT DEFAULT CURRENT_TIMESTAMP,
+					PRIMARY KEY (tablename, id)
+				)
+			`);
+            db.exec(`CREATE INDEX IF NOT EXISTS vibes_repository_tablename ON vibes_repository(tablename)`);
+        },
+        down: (db) => {
+            db.exec(`DROP TABLE IF EXISTS vibes_documents`);
+            db.exec(`DROP TABLE IF EXISTS vibes_kv`);
+            db.exec(`DROP TABLE IF EXISTS vibes_repository`);
+        }
+    },
+    {
+        version: 2,
+        name: 'Persist document revisions',
+        up: (db) => {
+            db.exec(`ALTER TABLE vibes_documents ADD COLUMN __vibes_revision TEXT NOT NULL DEFAULT ''`);
+            db.exec(`UPDATE vibes_documents SET __vibes_revision = lower(hex(randomblob(16)))`);
+            db.exec(`CREATE TRIGGER storage_document_revision_insert AFTER INSERT ON vibes_documents
+			 BEGIN UPDATE vibes_documents SET __vibes_revision = lower(hex(randomblob(16))) WHERE namespace = NEW.namespace; END`);
+            db.exec(`CREATE TRIGGER storage_document_revision_update AFTER UPDATE OF data ON vibes_documents
+			 BEGIN UPDATE vibes_documents SET __vibes_revision = lower(hex(randomblob(16))) WHERE namespace = NEW.namespace; END`);
+        },
+        down: (db) => {
+            db.exec('DROP TRIGGER IF EXISTS storage_document_revision_insert');
+            db.exec('DROP TRIGGER IF EXISTS storage_document_revision_update');
+            db.exec('ALTER TABLE vibes_documents DROP COLUMN __vibes_revision');
+        }
+    }
+];
+// Migration registration: once per process, on the first opening call's
+// runtime. The registry is one per process, so it is asked first.
+function ensureMigrationsRegistered(runtime) {
+    if (localdb.listNamespaces(runtime).includes('storage.localdb'))
+        return;
+    localdb.registerMigrations(runtime, 'storage.localdb', STORAGE_MIGRATIONS);
+}
+/** A configuration refusal: `INVALID_INPUT` with its specific reason, value-free. */
+function invalidConfiguration(message, reason) {
+    return new CapabilityError(message, 'INVALID_INPUT', { reason, retryable: false });
+}
+/** The manifest descriptor's LocalDB hints, read once through the adapters' guard. */
+function readManifestHints(manifest) {
+    return parseAdapterInput(LocalDBManifestHintsSchema, manifest, {
+        message: 'storage.localdb could not read the manifest descriptor it was handed.',
+        code: 'INVALID_INPUT',
+        reason: 'storage-localdb-manifest-invalid'
+    });
+}
+// LocalDB Adapter Implementation
+/**
+ * The `storage.localdb` adapter. A class: the `storage/adapter` kind constructs
+ * one per runtime (`new LocalDBStorageAdapter(descriptor, context)`), so one
+ * runtime's `configure()` never re-points another runtime's adapter. Database
+ * handles come from LocalDB's process pool, which dedupes by namespace and
+ * path and counts each runtime's references, so two instances holding one file
+ * share one connection and neither's release closes the other's.
+ */
+export class LocalDBStorageAdapter {
+    id = 'storage.localdb';
+    capabilities = {
+        protocols: ['document', 'keyvalue', 'repository'],
+        requiresPairSchema: false,
+        supportsTransactions: true,
+        supportsTTL: true,
+        supportsFTS: true,
+        persistent: true,
+        supportsSubscription: false,
+        supportsHierarchy: true,
+        supportsComputedFields: true,
+        supportsSideEffects: true,
+        supportsRawQueries: true
+    };
+    config = null;
+    database = null;
+    initialized = false;
+    /**
+     * Cache of scope-resolved databases keyed by dbPath.
+     * When a manifest has a different scope (e.g., 'global') than the adapter's
+     * configured basePath, we resolve a separate database from the localdb pool.
+     */
+    scopedDatabases = new Map();
+    /**
+     * Cache of `storage/record` databases keyed by dbPath.
+     *
+     * Distinct from `scopedDatabases` above: that pool resolves a MANIFEST's
+     * (`storage/manifest`, document-store) own scope→path mapping, which is a
+     * different formula than a `StorageRecord`'s scope→path mapping
+     * (`StorageRecord.getBasePath()`) — e.g. manifest global-scope resolves
+     * via `resolveGlobalStorageBasePath()` (`{home}/.vibes[-dev]/storage[/profile/x]`)
+     * while a record's global scope resolves to the canonical Vibes home
+     * (`VIBES_HOME` or `{home}/.vibes[-dev]`, with no `/storage` nesting or
+     * profile split). Pooling records through the manifest formula would
+     * silently retarget every existing local record
+     * store to a different, empty file. This pool is keyed off the CALLER's
+     * already-resolved `{ basePath, dbName }` (see `getRecordDatabaseConnection`)
+     * instead of re-deriving scope here, so it preserves the exact path
+     * `StorageRecord` has always used while still being race-free.
+     */
+    recordDatabases = new Map();
+    /**
+     * Check and apply a manifest's or record's configuration. Synchronous: the
+     * manifest and record bases call it on every access. Each refusal is
+     * `INVALID_INPUT` with its own reason and a value-free message. Whether the
+     * base path is writable is not decided here (configuration is not a write,
+     * and existing stores stay readable in read-only processes): the first open
+     * creates the directory and refuses `UNAVAILABLE`
+     * `storage-localdb-base-path-unwritable` when it cannot.
+     */
+    configure(config) {
+        const fields = parseAdapterInput(LocalDBConfigFieldsSchema, config, {
+            message: 'storage.localdb could not read its configuration.',
+            code: 'INVALID_INPUT',
+            reason: 'storage-localdb-config-invalid'
+        });
+        const basePath = fields.basePath;
+        if (basePath === undefined || basePath.trim() === '') {
+            throw invalidConfiguration('storage.localdb requires a non-empty basePath.', 'storage-localdb-base-path-required');
+        }
+        if (!isAbsoluteHostPath(basePath)) {
+            throw invalidConfiguration('storage.localdb requires an absolute basePath.', 'storage-localdb-base-path-relative');
+        }
+        if (fields.dbName !== undefined && (fields.dbName.includes('/') || fields.dbName.includes('\\'))) {
+            throw invalidConfiguration('storage.localdb dbName must be a filename, not a path.', 'storage-localdb-db-name-invalid');
+        }
+        if (fields.customTables === true && !fields.migrationKey) {
+            throw invalidConfiguration('storage.localdb customTables requires a migrationKey.', 'storage-localdb-migration-key-required');
+        }
+        if (fields.migrationKey !== undefined && fields.migrationKey.trim() === '') {
+            throw invalidConfiguration('storage.localdb migrationKey must be a non-empty string.', 'storage-localdb-migration-key-empty');
+        }
+        if (fields.tableName && !SQL_IDENTIFIER.test(fields.tableName)) {
+            throw invalidConfiguration('storage.localdb tableName must be a valid SQL identifier.', 'storage-localdb-table-name-invalid');
+        }
+        // If the default (non-scoped) database path changes — e.g. the active
+        // VIBES_PROFILE switched between two reads in the same process, which
+        // moves the global-scope storage path under {base}/profile/<name>/storage —
+        // drop the cached default handle so the next access re-opens the correct
+        // database. Without this, ensureInitialized() would return the stale
+        // previously-initialized handle (only a health-check, no path comparison)
+        // and reads would resolve against the wrong profile's data. The old handle
+        // stays in the localdb pool (keyed by path) and is reused if that path
+        // returns, so this only re-points the adapter, it does not leak.
+        const priorDbPath = this.config ? `${this.config.basePath}/${this.config.dbName ?? DEFAULT_DB_NAME}` : null;
+        const nextDbPath = `${basePath}/${fields.dbName ?? DEFAULT_DB_NAME}`;
+        if (priorDbPath !== null && priorDbPath !== nextDbPath) {
+            this.database = null;
+            this.initialized = false;
+        }
+        this.config = config;
+    }
+    isConfigured() {
+        return this.config !== null && !!this.config.basePath;
+    }
+    /** The configuration, or the typed refusal for an adapter used before `configure()`. */
+    requireConfig() {
+        if (!this.config) {
+            throw new CapabilityError('storage.localdb was used before it was configured.', 'INTERNAL', {
+                reason: 'storage-adapter-unconfigured',
+                retryable: false
+            });
+        }
+        return this.config;
+    }
+    /**
+     * The runtime the adapter's current call serves: the configuring manifest's
+     * or record's. LocalDB opens, releases and probes on it and reports there
+     * (C083a); an adapter configured without one is refused, typed.
+     */
+    requireRuntime() {
+        const runtime = this.config?.runtime;
+        if (!runtime) {
+            throw new CapabilityError('storage.localdb was configured without the runtime its databases open and report on.', 'INTERNAL', { reason: 'storage-adapter-unconfigured' });
+        }
+        return runtime;
+    }
+    /**
+     * Create `path` (recursively) through the runtime's filesystem kind. A
+     * directory that cannot be created refuses `UNAVAILABLE`
+     * `storage-localdb-base-path-unwritable`, the filesystem's failure as cause.
+     */
+    async ensureDirectory(runtime, path) {
+        const files = await fileSystemOf(runtime);
+        const created = await settle(files.mkdir(path, { recursive: true }));
+        if (created.failed) {
+            throw new CapabilityError('storage.localdb could not create its database directory; the base path is not writable.', 'UNAVAILABLE', { reason: 'storage-localdb-base-path-unwritable', retryable: false, cause: created.cause });
+        }
+    }
+    /** Whether the database file at `dbPath` exists, asked of the runtime's filesystem kind. */
+    async databaseFileExists(runtime, dbPath) {
+        const files = await fileSystemOf(runtime);
+        return files.exists(dbPath);
+    }
+    async ensureInitialized() {
+        const runtime = this.requireRuntime();
+        assertStorageRuntimeLive(runtime, 'database work');
+        if (this.initialized && this.database) {
+            const healthy = this.database.healthCheck(runtime);
+            if (healthy)
+                return;
+            // Stale/closed handle (e.g. after shared recovery): release and recreate.
+            const dbPath = this.getDbPath();
+            // Recovery proceeds with a fresh handle; the release failure is reported, not lost.
+            await localdb.releaseDatabase(runtime, 'storage.localdb', dbPath).catch(logReleaseFailure(runtime, dbPath, 'stale'));
+            this.database = null;
+            this.initialized = false;
+        }
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        // Now initialize the database on first access
+        if (!this.database) {
+            await this.ensureDirectory(runtime, this.requireConfig().basePath);
+            // Always use the generic storage.localdb namespace for the adapter's
+            // own database. Custom-table migrations (e.g. 'ai') are per-manifest
+            // and applied lazily via ensureCustomMigrations() in getScopedDb().
+            ensureMigrationsRegistered(runtime);
+            this.database = await localdb.getDatabase(runtime, 'storage.localdb', this.getDbPath(), 'storage-adapter');
+        }
+    }
+    /** The adapter's default database, opened (on the configured runtime) if it is not yet. */
+    async openDefaultDatabase() {
+        await this.ensureInitialized();
+        return this.defaultConnection();
+    }
+    /** The open default database, or the typed refusal when none is open yet. */
+    defaultConnection() {
+        if (!this.database) {
+            throw new CapabilityError('storage.localdb has no open default database; call ensureReady() first.', 'INTERNAL', {
+                reason: 'storage-localdb-not-ready',
+                retryable: false
+            });
+        }
+        return this.database.getDatabase();
+    }
+    getDbPath() {
+        const config = this.requireConfig();
+        return `${config.basePath}/${config.dbName ?? DEFAULT_DB_NAME}`;
+    }
+    /**
+     * The workspace root and path roots the configuring manifest handed over.
+     * A filesystem manifest always sets both; their absence is a configuration
+     * defect, reported as such rather than answered from ambient state.
+     */
+    configuredScopeInputs() {
+        return parseAdapterInput(LocalDBScopeInputsSchema, { workspacePath: this.config?.workspacePath, roots: this.config?.roots }, {
+            message: 'storage.localdb was configured without a workspace path and path roots.',
+            code: 'INTERNAL',
+            reason: 'storage-adapter-unconfigured'
+        });
+    }
+    /**
+     * Resolve the correct SQLite database for a manifest's scope.
+     *
+     * Manifests sharing this runtime's adapter may have different scopes
+     * (e.g., 'global' vs 'project') that map to different database files.
+     * This method resolves the correct database from the localdb pool based on
+     * the manifest descriptor's scope, falling back to the adapter's configured
+     * default when no scope override is needed.
+     *
+     * For manifests with customTables=true, the migrationKey determines which
+     * migrations run against the database (e.g., 'ai' runs AI table migrations).
+     */
+    resolveScopedManifestTarget(hints) {
+        const config = this.requireConfig();
+        let basePath = config.basePath;
+        // The configuring manifest or record resolved the workspace and roots on
+        // its own runtime (`getAdapterConfig`); nothing here is ambient.
+        const { workspacePath: workspaceRoot, roots } = this.configuredScopeInputs();
+        if (hints?.scope && hints.scope !== 'auto') {
+            const scopePath = hints.scopePaths?.[hints.scope];
+            if (scopePath) {
+                basePath = scopePath.includes('{')
+                    ? resolveScopePathTemplate(scopePath, workspaceRoot, roots)
+                    : scopePath;
+            }
+            else {
+                switch (hints.scope) {
+                    case 'global':
+                        basePath = resolveGlobalStorageBasePath(roots);
+                        break;
+                    case 'project':
+                    case 'local':
+                        basePath = `${workspaceRoot}/.vibes/storage`;
+                        break;
+                }
+            }
+        }
+        const migrationKey = hints?.customTables && hints.migrationKey ? hints.migrationKey : 'storage.localdb';
+        // The manifest's own adapterConfig dbName is the contract (e.g. work.items
+        // declares work.db). Falling through to the adapter INSTANCE's dbName made
+        // the scoped file depend on host bootstrap config — the compiled CLI and
+        // the from-source CLI resolved different files for the same manifest
+        // (workspace.db vs work.db), splitting the store.
+        const dbName = hints?.adapterConfig?.['storage.localdb']?.dbName ?? config.dbName ?? DEFAULT_DB_NAME;
+        return { workspaceRoot, basePath, dbPath: `${basePath}/${dbName}`, migrationKey };
+    }
+    async getScopedDb(target) {
+        const { basePath, dbPath, migrationKey } = target;
+        // The runtime that configured the target above, read at the same moment.
+        const runtime = this.requireRuntime();
+        assertStorageRuntimeLive(runtime, 'scoped database work');
+        // Always resolve through the `dbPath`-keyed `scopedDatabases` pool below —
+        // never shortcut to the adapter's mutable `this.database`/`this.config` via
+        // `this.getDbPath()`. Manifests that share this runtime's adapter call
+        // `configure()` on it on every access; when two manifests with DIFFERENT
+        // scopes resolve concurrently (e.g. the `auth` config manifest and a
+        // project-scoped workspace catalog during plugin activation), a sibling's
+        // `configure()` could land between this function's `await` points and a
+        // later re-read, handing THIS manifest a handle open on a DIFFERENT
+        // manifest's file. That was a production bug: `vibes auth status` got a
+        // connection to an unrelated project-scoped db and reported "Not
+        // authenticated" while the credential row sat in the global-scope file.
+        //
+        // `dbPath` is a plain local value resolved once by the caller, never
+        // re-derived from shared mutable state, so keying everything off it here
+        // is race free. `localdb.getDatabase()` already dedupes by
+        // `${namespace}:${dbPath}`, so this doesn't open a redundant connection
+        // when `dbPath` coincides with the adapter's default.
+        const existingScoped = this.scopedDatabases.get(dbPath);
+        if (existingScoped) {
+            const healthy = existingScoped.healthCheck(runtime);
+            if (!healthy) {
+                await localdb.releaseDatabase(runtime, 'storage.localdb', dbPath).catch(logReleaseFailure(runtime, dbPath, 'unhealthy'));
+                this.scopedDatabases.delete(dbPath);
+            }
+        }
+        let scoped = this.scopedDatabases.get(dbPath);
+        if (!scoped) {
+            await this.ensureDirectory(runtime, basePath);
+            ensureMigrationsRegistered(runtime);
+            scoped = await localdb.getDatabase(runtime, 'storage.localdb', dbPath, 'storage-adapter-scoped');
+            this.scopedDatabases.set(dbPath, scoped);
+        }
+        // For custom tables, ensure custom migrations have run on the scoped db
+        if (migrationKey !== 'storage.localdb') {
+            await this.ensureCustomMigrations(runtime, migrationKey, scoped.getDatabase());
+        }
+        return scoped.getDatabase();
+    }
+    getOpenedDatabasePath(connection, fallbackPath) {
+        const databases = connection.prepare('PRAGMA database_list').all();
+        return databases.find((database) => database.name === 'main')?.file || fallbackPath;
+    }
+    /**
+     * Track which custom migration keys have been applied to which databases
+     * to avoid redundant migration attempts.
+     */
+    appliedCustomMigrations = new Set();
+    /**
+     * Ensure custom table migrations have been applied to a specific database.
+     * Runs any pending migrations of `migrationKey` against the target
+     * connection. A failure that means the migrations are already applied
+     * (another registrar, or a statement finding what it creates) counts as
+     * applied; any other refuses `INTERNAL` `storage-localdb-migration-failed`,
+     * the failure as cause and the key (a manifest-declared identifier) in details.
+     */
+    async ensureCustomMigrations(runtime, migrationKey, db) {
+        const cacheKey = `${migrationKey}:${db.path}`;
+        if (this.appliedCustomMigrations.has(cacheKey))
+            return;
+        // Run pending migrations directly against the current connection.
+        // Avoiding localdb.getDatabase(namespace, dbPath) prevents cross-namespace
+        // recovery from invalidating shared handles for this dbPath.
+        const migrated = await settle(this.runPendingMigrations(runtime, migrationKey, db));
+        if (migrated.failed && !isAppliedMigrationFailure(migrated.cause, migrationKey)) {
+            throw new CapabilityError("storage.localdb could not apply a manifest's custom migrations.", 'INTERNAL', {
+                reason: 'storage-localdb-migration-failed',
+                retryable: false,
+                details: { migrationKey },
+                cause: migrated.cause
+            });
+        }
+        this.appliedCustomMigrations.add(cacheKey);
+    }
+    async runPendingMigrations(runtime, migrationKey, db) {
+        if (migrationRegistry.needsMigration(runtime, db, migrationKey)) {
+            await migrationRegistry.runMigrations(runtime, db, migrationKey);
+        }
+    }
+    // Document Store
+    documentStore(namespace, schema, manifest) {
+        const hints = readManifestHints(manifest);
+        const target = () => this.resolveScopedManifestTarget(hints);
+        const scopedDb = () => this.getScopedDb(target());
+        const defaultDbPath = () => this.getDbPath();
+        // Determine if this manifest uses a dedicated table
+        if (hints?.customTables === true) {
+            const tableConfig = hints.adapterConfig?.['storage.localdb'];
+            const tableName = tableConfig?.tableName;
+            if (!tableName) {
+                throw new CapabilityError("A storage manifest with customTables needs a tableName in adapterConfig['storage.localdb'].", 'INVALID_INPUT', { reason: 'storage-localdb-table-name-required', retryable: false, details: { namespace } });
+            }
+            if (!SQL_IDENTIFIER.test(tableName)) {
+                throw new CapabilityError("A storage manifest's dedicated tableName must be a valid SQL identifier.", 'INVALID_INPUT', { reason: 'storage-localdb-table-name-invalid', retryable: false, details: { namespace } });
+            }
+            return dedicatedTableStore(schema, tableName, tableConfig?.transforms, scopedDb, defaultDbPath);
+        }
+        // Default path: generic vibes_documents blob store
+        /**
+         * The stored JSON text of this namespace's document, or `null` when there
+         * is none. A read probe must not materialize the database file: a missing
+         * store answers null from the resolved path alone (pinned by
+         * localdb.adapter.impl.test.ts "does not create a database ...").
+         */
+        const readDocumentText = async () => {
+            const runtime = this.requireRuntime();
+            assertStorageRuntimeLive(runtime, 'document reads');
+            const resolved = target();
+            if (!(await this.databaseFileExists(runtime, resolved.dbPath)))
+                return null;
+            const db = await this.getScopedDb(resolved);
+            const row = db
+                .prepare('SELECT data FROM vibes_documents WHERE namespace = ?')
+                .get(namespace);
+            return row ? row.data : null;
+        };
+        /**
+         * Immediate child namespaces, without reading their documents. The
+         * document store is namespace-addressed (`vibes_documents` keyed by
+         * `namespace`), so a `SELECT DISTINCT` restricted to exact children of
+         * `namespace/` is the full discovery contract. Grandchildren and other
+         * families are excluded by the escaped `LIKE` pair, and a missing
+         * store answers `[]` like the read probe above.
+         */
+        const discoverChildNamespaces = async () => {
+            const runtime = this.requireRuntime();
+            assertStorageRuntimeLive(runtime, 'namespace discovery');
+            const resolved = target();
+            if (!(await this.databaseFileExists(runtime, resolved.dbPath)))
+                return [];
+            const db = await this.getScopedDb(resolved);
+            const prefix = `${namespace}/`;
+            // SAFETY: The query selects only the TEXT namespace column; LIKE excludes null values.
+            const rows = db
+                .prepare(`SELECT DISTINCT namespace FROM vibes_documents
+					 WHERE namespace LIKE ? ESCAPE '\\'
+					   AND namespace NOT LIKE ? ESCAPE '\\'`)
+                .all(`${escapeSqlLike(prefix)}%`, `${escapeSqlLike(prefix)}%/%`);
+            const children = rows
+                .map((row) => row.namespace)
+                .filter((child) => child.length > prefix.length)
+                .sort();
+            return [...new Set(children)];
+        };
+        const revisionDatabase = async () => {
+            const runtime = this.requireRuntime();
+            assertStorageRuntimeLive(runtime, 'document revision reads');
+            const resolved = target();
+            if (!(await this.databaseFileExists(runtime, resolved.dbPath)))
+                return null;
+            return this.getScopedDb(resolved);
+        };
+        const revisionMetadata = async () => {
+            const db = await revisionDatabase();
+            if (!db)
+                return null;
+            const row = db.prepare('SELECT __vibes_revision AS revision FROM vibes_documents WHERE namespace = ?').get(namespace);
+            return row ? DocumentRevisionMetadataSchema.parse(row) : null;
+        };
+        return {
+            revisions: {
+                metadata: revisionMetadata,
+                readAtRevision: async (expected, options) => {
+                    const revision = DocumentRevisionSchema.parse(expected);
+                    if (options?.signal?.aborted)
+                        throw new CapabilityError('The document read was cancelled.', 'CANCELLED', { reason: 'storage-load-cancelled' });
+                    const db = await revisionDatabase();
+                    if (options?.signal?.aborted)
+                        throw new CapabilityError('The document read was cancelled.', 'CANCELLED', { reason: 'storage-load-cancelled' });
+                    if (!db)
+                        return { status: 'not-found' };
+                    const row = db.prepare('SELECT data FROM vibes_documents WHERE namespace = ? AND __vibes_revision = ?').get(namespace, revision);
+                    if (row)
+                        return { status: 'read', revision, value: schema.parse(JSON.parse(row.data)) };
+                    const current = await revisionMetadata();
+                    return current ? { status: 'changed', revision: current.revision } : { status: 'not-found' };
+                }
+            },
+            async load() {
+                const text = await readDocumentText();
+                return text === null ? null : schema.parse(JSON.parse(text));
+            },
+            async loadStored() {
+                const text = await readDocumentText();
+                return text === null ? null : readStoredLayer(schema, JSON.parse(text));
+            },
+            async save(data) {
+                // Persist the caller's validated input, never the parse output (defaults are read-time only).
+                const validated = validateForPersist(schema, data);
+                const db = await scopedDb();
+                db.prepare(`INSERT INTO vibes_documents (namespace, data, updated_at)
+					 VALUES (?, ?, datetime('now'))
+					 ON CONFLICT(namespace) DO UPDATE SET data = excluded.data, updated_at = datetime('now')`).run(namespace, JSON.stringify(validated));
+            },
+            /**
+             * Optimistic read-transform-write. A write that loses to a concurrent
+             * writer re-reads and retries; after DOCUMENT_UPDATE_ATTEMPTS lost
+             * rounds it refuses `CONFLICT` `localdb-document-contention`
+             * (retryable: the caller may try again once the contention passes).
+             */
+            async update(transform) {
+                const db = await scopedDb();
+                for (let round = 0; round < DOCUMENT_UPDATE_ATTEMPTS; round++) {
+                    const row = db
+                        .prepare('SELECT data FROM vibes_documents WHERE namespace = ?')
+                        .get(namespace);
+                    const current = row ? schema.parse(JSON.parse(row.data)) : null;
+                    // Persist the transform's validated result; hand the caller the parsed value.
+                    const next = validateForPersist(schema, await transform(current));
+                    const updated = schema.parse(next);
+                    const serialized = JSON.stringify(next);
+                    const result = row
+                        ? db
+                            .prepare(`UPDATE vibes_documents
+									 SET data = ?, updated_at = datetime('now')
+									 WHERE namespace = ? AND data = ?`)
+                            .run(serialized, namespace, row.data)
+                        : db
+                            .prepare(`INSERT INTO vibes_documents (namespace, data, updated_at)
+									 VALUES (?, ?, datetime('now'))
+									 ON CONFLICT(namespace) DO NOTHING`)
+                            .run(namespace, serialized);
+                    if (result.changes > 0)
+                        return updated;
+                }
+                throw new CapabilityError('An atomic document update lost to concurrent writers on every retry.', 'CONFLICT', {
+                    reason: 'localdb-document-contention',
+                    retryable: true,
+                    details: { namespace, attempts: DOCUMENT_UPDATE_ATTEMPTS },
+                    recoveryHint: 'Retry the update once the concurrent writes settle.'
+                });
+            },
+            async exists() {
+                return (await readDocumentText()) !== null;
+            },
+            async delete() {
+                const db = await scopedDb();
+                db.prepare('DELETE FROM vibes_documents WHERE namespace = ?').run(namespace);
+            },
+            listChildNamespaces: discoverChildNamespaces,
+            getPath() {
+                return `localdb://${defaultDbPath()}/${namespace}`;
+            }
+        };
+    }
+    // Key-Value Store
+    keyValueStore(namespace, keySchema, valueSchema) {
+        const open = () => this.openDefaultDatabase();
+        const reportingRuntime = () => this.requireRuntime();
+        const serializeKey = (key) => {
+            const validated = keySchema.parse(key);
+            const asText = KeyTextSchema.safeParse(validated);
+            return asText.success ? asText.data : JSON.stringify(validated);
+        };
+        /**
+         * The key a stored row names, or `undefined` for a row that does not
+         * satisfy the key schema (skipped, as before). A string key is stored as
+         * its own text; any other key as JSON (`serializeKey`). A row whose text
+         * fits neither is malformed against the declared contract: it is skipped
+         * and reported once on the runtime the call serves.
+         */
+        const decodeKey = (stored) => {
+            const asText = keySchema.safeParse(stored);
+            if (asText.success)
+                return asText.data;
+            const decoded = attempt(() => JSON.parse(stored));
+            if (decoded.failed) {
+                const logger = getLogger('storage:localdb-adapter', reportingRuntime());
+                logger.warn('storage.localdb: skipped a key-value row whose key is neither text nor JSON', {
+                    namespace,
+                    error: valueFreeFailure(decoded.cause)
+                });
+                return undefined;
+            }
+            const asJson = keySchema.safeParse(decoded.value);
+            return asJson.success ? asJson.data : undefined;
+        };
+        const cleanExpired = (db) => {
+            db.prepare(`DELETE FROM vibes_kv WHERE namespace = ? AND expires_at IS NOT NULL AND expires_at < ?`).run(namespace, Date.now());
+        };
+        const get = async (key) => {
+            const db = await open();
+            cleanExpired(db);
+            const row = db
+                .prepare(`SELECT value FROM vibes_kv WHERE namespace = ? AND key = ?`)
+                .get(namespace, serializeKey(key));
+            if (!row)
+                return null;
+            return valueSchema.parse(JSON.parse(row.value));
+        };
+        const set = async (key, value, options) => {
+            const db = await open();
+            const k = serializeKey(key);
+            // Handle nx/xx options
+            if (options?.nx || options?.xx) {
+                const exists = db
+                    .prepare(`SELECT COUNT(*) as count FROM vibes_kv WHERE namespace = ? AND key = ? AND (expires_at IS NULL OR expires_at > ?)`)
+                    .get(namespace, k, Date.now())?.count ?? 0;
+                if (options.nx && exists > 0)
+                    return;
+                if (options.xx && exists === 0)
+                    return;
+            }
+            const validated = valueSchema.parse(value);
+            const expiresAt = options?.ttl ? Date.now() + options.ttl : null;
+            db.prepare(`INSERT INTO vibes_kv (namespace, key, value, expires_at)
+				 VALUES (?, ?, ?, ?)
+				 ON CONFLICT(namespace, key) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`).run(namespace, k, JSON.stringify(validated), expiresAt);
+        };
+        const remove = async (key) => {
+            const db = await open();
+            const result = db
+                .prepare('DELETE FROM vibes_kv WHERE namespace = ? AND key = ?')
+                .run(namespace, serializeKey(key));
+            return result.changes > 0;
+        };
+        return {
+            get,
+            set,
+            delete: remove,
+            async has(key) {
+                const db = await open();
+                cleanExpired(db);
+                const row = db
+                    .prepare(`SELECT COUNT(*) as count FROM vibes_kv WHERE namespace = ? AND key = ? AND (expires_at IS NULL OR expires_at > ?)`)
+                    .get(namespace, serializeKey(key), Date.now());
+                return (row?.count ?? 0) > 0;
+            },
+            async getMany(keys) {
+                const result = new Map();
+                for (const key of keys) {
+                    const value = await get(key);
+                    if (value !== null) {
+                        result.set(key, value);
+                    }
+                }
+                return result;
+            },
+            async setMany(entries) {
+                for (const [key, value] of entries) {
+                    await set(key, value);
+                }
+            },
+            async deleteMany(keys) {
+                let count = 0;
+                for (const key of keys) {
+                    if (await remove(key))
+                        count++;
+                }
+                return count;
+            },
+            async *keys(pattern) {
+                const db = await open();
+                cleanExpired(db);
+                const query = pattern
+                    ? `SELECT key FROM vibes_kv WHERE namespace = ? AND key LIKE ? AND (expires_at IS NULL OR expires_at > ?)`
+                    : `SELECT key FROM vibes_kv WHERE namespace = ? AND (expires_at IS NULL OR expires_at > ?)`;
+                const rows = pattern
+                    ? db.prepare(query).all(namespace, `%${pattern}%`, Date.now())
+                    : db.prepare(query).all(namespace, Date.now());
+                for (const row of rows) {
+                    const key = decodeKey(row.key);
+                    if (key !== undefined)
+                        yield key;
+                }
+            },
+            async *entries(pattern) {
+                const db = await open();
+                cleanExpired(db);
+                const query = pattern
+                    ? `SELECT key, value FROM vibes_kv WHERE namespace = ? AND key LIKE ? AND (expires_at IS NULL OR expires_at > ?)`
+                    : `SELECT key, value FROM vibes_kv WHERE namespace = ? AND (expires_at IS NULL OR expires_at > ?)`;
+                const rows = pattern
+                    ? db.prepare(query).all(namespace, `%${pattern}%`, Date.now())
+                    : db.prepare(query).all(namespace, Date.now());
+                for (const row of rows) {
+                    const key = decodeKey(row.key);
+                    if (key === undefined)
+                        continue;
+                    const valueResult = valueSchema.safeParse(JSON.parse(row.value));
+                    if (!valueResult.success)
+                        continue;
+                    yield [key, valueResult.data];
+                }
+            },
+            async count(pattern) {
+                const db = await open();
+                cleanExpired(db);
+                const query = pattern
+                    ? `SELECT COUNT(*) as count FROM vibes_kv WHERE namespace = ? AND key LIKE ? AND (expires_at IS NULL OR expires_at > ?)`
+                    : `SELECT COUNT(*) as count FROM vibes_kv WHERE namespace = ? AND (expires_at IS NULL OR expires_at > ?)`;
+                const row = pattern
+                    ? db.prepare(query).get(namespace, `%${pattern}%`, Date.now())
+                    : db.prepare(query).get(namespace, Date.now());
+                return row?.count ?? 0;
+            },
+            async clear() {
+                const db = await open();
+                db.prepare('DELETE FROM vibes_kv WHERE namespace = ?').run(namespace);
+            }
+        };
+    }
+    // Record (New Pattern)
+    /**
+     * Get a storage record interface for CRUD operations on a single table.
+     *
+     * This is the new pattern for storage that properly integrates with the runtime system.
+     * Use this for modules that need structured storage with relations and queries.
+     *
+     * @param descriptor - Storage record descriptor
+     * @returns Storage record interface with CRUD operations
+     *
+     * @example
+     * ```typescript
+     * const todos = adapter.record(todoDescriptor);
+     * await todos.create({ sessionId: '...', title: '...' });
+     * const allTodos = await todos.list({ where: { sessionId: '...' }});
+     * ```
+     */
+    record(descriptor, context) {
+        // A record this adapter hands out is bound to the runtime its caller
+        // names: that runtime's roots place the record's files and its HookBus
+        // carries its events.
+        if (!context?.runtime) {
+            throw new CapabilityError('A storage.localdb record needs the runtime context it will read and write through.', 'INVALID_INPUT', { reason: 'storage-record-context-required', retryable: false, details: { recordId: descriptor.id } });
+        }
+        return new StorageRecord(descriptor, context);
+    }
+    /**
+     * Create FTS virtual table for a record descriptor
+     */
+    createFtsTables(descriptor, db) {
+        if (!descriptor.fts)
+            return;
+        const ftsConfig = descriptor.fts;
+        const ftsTable = ftsConfig.tableName || `${descriptor.tableName}_fts`;
+        const fields = ftsConfig.fields;
+        const tokenizer = ftsConfig.tokenizer || 'unicode61';
+        db.exec(`
+			CREATE VIRTUAL TABLE IF NOT EXISTS ${ftsTable} USING fts5(
+				${fields.join(', ')},
+				content='${descriptor.tableName}',
+				tokenize='${tokenizer}'
+			)
+		`);
+        db.exec(`
+			CREATE TRIGGER IF NOT EXISTS ${descriptor.tableName}_ai AFTER INSERT ON ${descriptor.tableName} BEGIN
+				INSERT INTO ${ftsTable}(rowid, ${fields.join(', ')})
+				VALUES (NEW.rowid, ${fields.map((f) => `NEW.${f}`).join(', ')});
+			END
+		`);
+        db.exec(`
+			CREATE TRIGGER IF NOT EXISTS ${descriptor.tableName}_ad AFTER DELETE ON ${descriptor.tableName} BEGIN
+				INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${fields.join(', ')})
+				VALUES('delete', OLD.rowid, ${fields.map((f) => `OLD.${f}`).join(', ')});
+			END
+		`);
+        db.exec(`
+			CREATE TRIGGER IF NOT EXISTS ${descriptor.tableName}_au AFTER UPDATE ON ${descriptor.tableName} BEGIN
+				INSERT INTO ${ftsTable}(${ftsTable}, rowid, ${fields.join(', ')})
+				VALUES('delete', OLD.rowid, ${fields.map((f) => `OLD.${f}`).join(', ')});
+				INSERT INTO ${ftsTable}(rowid, ${fields.join(', ')})
+				VALUES (NEW.rowid, ${fields.map((f) => `NEW.${f}`).join(', ')});
+			END
+		`);
+    }
+    // Repository (Legacy Pattern)
+    repository(tableName, schema, options) {
+        const open = () => this.openDefaultDatabase();
+        const primaryKey = options?.primaryKey ?? 'id';
+        const autoId = options?.autoId ?? true;
+        const autoTimestamps = options?.autoTimestamps ?? true;
+        const generateId = () => `${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        /** A caller's create or update input, read once through the adapters' guard. */
+        const readInput = (data) => parseAdapterInput(RepositoryFieldsSchema, data, {
+            message: 'storage.localdb repository input must be an object of fields.',
+            code: 'INVALID_INPUT',
+            reason: 'storage-localdb-repository-input-invalid',
+            details: { tableName }
+        });
+        const stamp = (fields, isNew) => {
+            if (!autoTimestamps)
+                return fields;
+            const now = new Date().toISOString();
+            return isNew ? { ...fields, createdAt: now, updatedAt: now } : { ...fields, updatedAt: now };
+        };
+        /** The primary-key value a row or input names, as the id column stores it. */
+        const keyOf = (fields, field = primaryKey) => {
+            const key = RepositoryKeySchema.safeParse(fields[field]);
+            return key.success ? String(key.data) : undefined;
+        };
+        const readAll = async () => {
+            const db = await open();
+            const rows = db
+                .prepare('SELECT data FROM vibes_repository WHERE tablename = ?')
+                .all(tableName);
+            return rows.map((row) => schema.parse(JSON.parse(row.data)));
+        };
+        return {
+            // Create
+            async create(data) {
+                const db = await open();
+                const fields = readInput(data);
+                const id = keyOf(fields) ?? (autoId ? generateId() : undefined);
+                if (id === undefined) {
+                    throw new CapabilityError('A storage.localdb repository record names no primary key value.', 'INVALID_INPUT', {
+                        reason: 'storage-localdb-primary-key-missing',
+                        retryable: false,
+                        details: { tableName, primaryKey }
+                    });
+                }
+                const validated = schema.parse(stamp({ ...fields, [primaryKey]: id }, true));
+                db.prepare(`INSERT INTO vibes_repository (tablename, id, data, created_at, updated_at)
+					 VALUES (?, ?, ?, datetime('now'), datetime('now'))`).run(tableName, id, JSON.stringify(validated));
+                return validated;
+            },
+            createMany(data) {
+                return Promise.all(data.map((d) => this.create(d)));
+            },
+            // Read
+            async get(id) {
+                const db = await open();
+                const row = db
+                    .prepare('SELECT data FROM vibes_repository WHERE tablename = ? AND id = ?')
+                    .get(tableName, id);
+                if (!row)
+                    return null;
+                return schema.parse(JSON.parse(row.data));
+            },
+            async getOrThrow(id) {
+                const data = await this.get(id);
+                if (!data) {
+                    throw new CapabilityError('No storage.localdb repository record has that id.', 'NOT_FOUND', {
+                        reason: 'record-absent',
+                        retryable: false,
+                        details: { tableName, id }
+                    });
+                }
+                return data;
+            },
+            async getMany(ids) {
+                const result = new Map();
+                for (const id of ids) {
+                    const data = await this.get(id);
+                    if (data)
+                        result.set(id, data);
+                }
+                return result;
+            },
+            async list(opts) {
+                const all = await readAll();
+                const offset = opts?.offset ?? 0;
+                const limit = opts?.limit ?? 100;
+                if (opts?.orderBy)
+                    sortRepositoryRows(all, opts.orderBy);
+                return {
+                    data: all.slice(offset, offset + limit),
+                    total: all.length,
+                    hasMore: offset + limit < all.length
+                };
+            },
+            async find(query, opts) {
+                let filtered = (await readAll()).filter((row) => matchesRepositoryQuery(row, query));
+                if (opts?.orderBy)
+                    sortRepositoryRows(filtered, opts.orderBy);
+                // Pagination
+                if (opts?.offset || opts?.limit) {
+                    const offset = opts.offset ?? 0;
+                    const limit = opts.limit ?? 100;
+                    filtered = filtered.slice(offset, offset + limit);
+                }
+                return filtered;
+            },
+            async findOne(query) {
+                const results = await this.find(query, { limit: 1 });
+                return results[0] ?? null;
+            },
+            async count(query) {
+                if (!query) {
+                    const db = await open();
+                    const row = db
+                        .prepare('SELECT COUNT(*) as count FROM vibes_repository WHERE tablename = ?')
+                        .get(tableName);
+                    return row?.count ?? 0;
+                }
+                return (await readAll()).filter((row) => matchesRepositoryQuery(row, query)).length;
+            },
+            async exists(id) {
+                const db = await open();
+                const row = db
+                    .prepare('SELECT COUNT(*) as count FROM vibes_repository WHERE tablename = ? AND id = ?')
+                    .get(tableName, id);
+                return (row?.count ?? 0) > 0;
+            },
+            async existsWhere(query) {
+                return (await this.count(query)) > 0;
+            },
+            // Update
+            async update(id, data) {
+                const db = await open();
+                const changes = readInput(data);
+                const existing = await this.get(id);
+                if (!existing)
+                    return null;
+                const validated = schema.parse(stamp({ ...repositoryFieldsOf(existing), ...changes }, false));
+                db.prepare(`UPDATE vibes_repository SET data = ?, updated_at = datetime('now') WHERE tablename = ? AND id = ?`).run(JSON.stringify(validated), tableName, id);
+                return validated;
+            },
+            async updateOrThrow(id, data) {
+                const result = await this.update(id, data);
+                if (!result) {
+                    throw new CapabilityError('No storage.localdb repository record has that id.', 'NOT_FOUND', {
+                        reason: 'record-absent',
+                        retryable: false,
+                        details: { tableName, id }
+                    });
+                }
+                return result;
+            },
+            async updateMany(query, data) {
+                const matching = await this.find(query);
+                let count = 0;
+                for (const record of matching) {
+                    const id = keyOf(repositoryFieldsOf(record));
+                    if (id === undefined)
+                        continue;
+                    await this.update(id, data);
+                    count++;
+                }
+                return count;
+            },
+            async upsert(data, uniqueKey) {
+                const keyField = uniqueKey === undefined ? primaryKey : String(uniqueKey);
+                const id = keyOf(readInput(data), keyField);
+                if (id !== undefined && (await this.exists(id))) {
+                    const updated = await this.update(id, data);
+                    if (updated)
+                        return updated;
+                }
+                return this.create(data);
+            },
+            // Delete
+            async delete(id) {
+                const db = await open();
+                const result = db
+                    .prepare('DELETE FROM vibes_repository WHERE tablename = ? AND id = ?')
+                    .run(tableName, id);
+                return result.changes > 0;
+            },
+            async deleteMany(ids) {
+                let count = 0;
+                for (const id of ids) {
+                    if (await this.delete(id))
+                        count++;
+                }
+                return count;
+            },
+            async deleteWhere(query) {
+                const matching = await this.find(query);
+                let count = 0;
+                for (const record of matching) {
+                    const id = keyOf(repositoryFieldsOf(record));
+                    if (id !== undefined && (await this.delete(id)))
+                        count++;
+                }
+                return count;
+            },
+            // Meta
+            meta() {
+                return {
+                    tableName,
+                    schema,
+                    primaryKey,
+                    autoFields: {
+                        id: autoId,
+                        createdAt: autoTimestamps,
+                        updatedAt: autoTimestamps
+                    }
+                };
+            }
+        };
+    }
+    // Database Access (public API for StorageRecord)
+    async ensureReady() {
+        await this.ensureInitialized();
+    }
+    getDatabaseConnection() {
+        return this.defaultConnection();
+    }
+    /**
+     * Get the scoped database connection for a specific manifest.
+     *
+     * Custom-table manifests (e.g. work.items, knowledge bases) live in
+     * dedicated SQLite files under scope-specific paths. This method
+     * resolves the right file, registers the manifest's custom
+     * migrations, and returns the open connection. The plain
+     * `getDatabaseConnection()` always returns the adapter's default
+     * database, which is the wrong target for scoped manifests.
+     */
+    async getScopedDatabaseConnection(manifest) {
+        return this.getScopedDb(this.resolveScopedManifestTarget(readManifestHints(manifest)));
+    }
+    /** Open a manifest's scoped connection and report the immutable target it used. */
+    async getScopedDatabaseConnectionWithIdentity(manifest) {
+        const target = this.resolveScopedManifestTarget(readManifestHints(manifest));
+        const connection = await this.getScopedDb(target);
+        const { workspaceRoot } = target;
+        const dbPath = this.getOpenedDatabasePath(connection, target.dbPath);
+        return { connection, identity: { workspaceRoot, dbPath } };
+    }
+    /** Resolve the same manifest target used by getScopedDatabaseConnection(). */
+    async getScopedDatabaseConnectionIdentity(manifest) {
+        const target = this.resolveScopedManifestTarget(readManifestHints(manifest));
+        const connection = await this.getScopedDb(target);
+        return {
+            workspaceRoot: target.workspaceRoot,
+            dbPath: this.getOpenedDatabasePath(connection, target.dbPath)
+        };
+    }
+    /**
+     * Get the database connection for a `storage/record`'s already-resolved
+     * `{ basePath, dbName }` target — the `StorageRecord`/base.ts analogue of
+     * `getScopedDatabaseConnection` above.
+     *
+     * Every `StorageRecord` on this runtime that resolves `storage.localdb`
+     * shares this adapter, and `configure()` re-points its `this.config` on
+     * every call. Two records with different descriptors (different
+     * `scope`/`dbName`) resolved concurrently — e.g. during runtime plugin
+     * activation — could otherwise race: `getDatabaseConnection()` reads
+     * whichever `this.database` is installed at the moment it's called, which
+     * may belong to a SIBLING record's dbName. Live forensics of that failure
+     * mode: stray `brain_state`/`session_state` tables inside `awareness.db`,
+     * frozen partial `awareness_*` tables inside `sessions.db`.
+     *
+     * `basePath`/`dbName` are the CALLER's already-resolved values (computed
+     * from the record's own immutable descriptor/context, never from this
+     * adapter's mutable fields), and `dbPath` is deterministic from them
+     * alone — so pooling by `dbPath` here (mirroring `scopedDatabases` above)
+     * is race-free regardless of what any other record's concurrent
+     * `configure()` call does to `this.config` in between.
+     *
+     * Deliberately NOT the same pool/formula as `getScopedDb` (used by
+     * `getScopedDatabaseConnection`): that method re-derives basePath from a
+     * MANIFEST's scope, which is a different mapping than a record's own
+     * `StorageRecord.getBasePath()` — reusing it here would silently retarget
+     * every existing local record store (e.g. `~/.vibes/awareness.db`) at a
+     * different, empty file.
+     */
+    async getRecordDatabaseConnection(config) {
+        assertStorageRuntimeLive(config.runtime, 'record database work');
+        const dbPath = `${config.basePath}/${config.dbName ?? DEFAULT_DB_NAME}`;
+        const existing = this.recordDatabases.get(dbPath);
+        if (existing) {
+            const healthy = existing.healthCheck(config.runtime);
+            if (healthy)
+                return existing.getDatabase();
+            await localdb.releaseDatabase(config.runtime, 'storage.localdb', dbPath).catch(logReleaseFailure(config.runtime, dbPath, 'unhealthy'));
+            this.recordDatabases.delete(dbPath);
+        }
+        await this.ensureDirectory(config.runtime, config.basePath);
+        ensureMigrationsRegistered(config.runtime);
+        const localDatabase = await localdb.getDatabase(config.runtime, 'storage.localdb', dbPath, 'storage-record');
+        this.recordDatabases.set(dbPath, localDatabase);
+        return localDatabase.getDatabase();
+    }
+    // Lifecycle
+    async initialize() {
+        if (this.initialized)
+            return;
+        // Configured or refused, typed; the database itself opens on first access.
+        this.requireConfig();
+        this.initialized = true;
+    }
+    async close() {
+        // Release scoped databases
+        for (const [dbPath] of this.scopedDatabases) {
+            await localdb.releaseDatabase(this.requireRuntime(), 'storage.localdb', dbPath);
+        }
+        this.scopedDatabases.clear();
+        this.appliedCustomMigrations.clear();
+        // Release record databases
+        for (const [dbPath] of this.recordDatabases) {
+            await localdb.releaseDatabase(this.requireRuntime(), 'storage.localdb', dbPath);
+        }
+        this.recordDatabases.clear();
+        if (!this.initialized || !this.database)
+            return;
+        // Release from localdb cache (this also closes the database)
+        await localdb.releaseDatabase(this.requireRuntime(), 'storage.localdb', this.getDbPath());
+        this.database = null;
+        this.initialized = false;
+    }
+    /**
+     * Probe real connectivity (opening the default database if needed). A
+     * failed probe answers unhealthy with a fixed, value-free `error` and the
+     * failure's value-free facts in `details.failure`; the failure's own text
+     * (which may carry a path) never leaves.
+     */
+    async healthCheck() {
+        const start = Date.now();
+        const probed = await settle(this.openDefaultDatabase());
+        if (probed.failed) {
+            return {
+                healthy: false,
+                latencyMs: Date.now() - start,
+                error: 'storage.localdb health check failed',
+                details: { failure: valueFreeFailure(probed.cause) }
+            };
+        }
+        const healthy = this.database ? this.database.healthCheck(this.requireRuntime()) : false;
+        return {
+            healthy,
+            latencyMs: Date.now() - start,
+            details: {
+                dbPath: this.getDbPath()
+            }
+        };
+    }
+}
+/**
+ * A dedicated-table manifest's document store: per-row reads and writes on its
+ * own SQLite table (`tableName`, a checked SQL identifier).
+ */
+function dedicatedTableStore(schema, tableName, transforms, scopedDb, defaultDbPath) {
+    /**
+     * Run one statement on the table. A table that does not exist yet (LocalDB's
+     * driver condition `missing-table`) is confirmed absence and answers
+     * `absent`; every other failure rethrows.
+     */
+    const onTable = (run, absent) => {
+        const ran = attempt(run);
+        if (!ran.failed)
+            return ran.value;
+        if (sqliteFailureCondition(ran.cause) === 'missing-table')
+            return absent;
+        throw ran.cause;
+    };
+    /**
+     * The rows as the stored layer, handed to `read`: the array the schema
+     * accepts (most schemas use z.array()), else the record keyed by id
+     * (z.record()). Nothing is defaulted here; `null` when the table is absent
+     * or empty.
+     */
+    const readRows = async (read) => {
+        const db = await scopedDb();
+        const rows = onTable(() => db.prepare(`SELECT * FROM ${tableName}`).all(), null);
+        if (rows === null || rows.length === 0)
+            return null;
+        // Transform rows from snake_case DB format to camelCase
+        const transformed = transforms?.fromDb ? transforms.fromDb.parse(rows) : rows;
+        const items = Array.isArray(transformed) ? transformed : [transformed];
+        if (schema.safeParse(items).success)
+            return read(items);
+        // Schema expects Record<string, T> — reconstruct from rows
+        const keyed = new Map();
+        for (const item of items) {
+            const identified = IdentifiedItemSchema.safeParse(item);
+            if (identified.success)
+                keyed.set(String(identified.data.id), item);
+        }
+        return read(Object.fromEntries(keyed));
+    };
+    return {
+        async load() {
+            return readRows((stored) => schema.parse(stored));
+        },
+        async loadStored() {
+            return readRows((stored) => readStoredLayer(schema, stored));
+        },
+        async save(data) {
+            // Persist the caller's validated input, never the parse output (defaults are read-time only).
+            const validated = validateForPersist(schema, data);
+            const db = await scopedDb();
+            // Normalize to array of items (handles both array and record formats)
+            const layer = RowsLayerSchema.safeParse(validated);
+            const items = !layer.success ? [] : Array.isArray(layer.data) ? layer.data : Object.values(layer.data);
+            // Transform items to snake_case DB format, then bind each cell.
+            const rows = parseAdapterInput(DbRowsSchema, transforms?.toDb ? transforms.toDb.parse(items) : items, {
+                message: 'storage.localdb could not bind the rows of a dedicated-table document.',
+                code: 'INVALID_INPUT',
+                reason: 'storage-localdb-rows-invalid'
+            });
+            if (rows.length === 0) {
+                // Empty data — delete all rows
+                db.prepare(`DELETE FROM ${tableName}`).run();
+                return;
+            }
+            // Use a transaction for atomicity
+            db.exec('BEGIN TRANSACTION');
+            try {
+                const incomingIds = new Set();
+                for (const row of rows) {
+                    const id = row.id;
+                    if (id)
+                        incomingIds.add(id);
+                    // Build column list from row keys, excluding undefined values
+                    const columns = [];
+                    const values = [];
+                    for (const [column, value] of Object.entries(row)) {
+                        if (value === undefined)
+                            continue;
+                        columns.push(column);
+                        values.push(value);
+                    }
+                    const placeholders = columns.map(() => '?');
+                    // Upsert: INSERT OR REPLACE
+                    db.prepare(`INSERT OR REPLACE INTO ${tableName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`).run(...values);
+                }
+                // Delete rows not in the incoming set
+                if (incomingIds.size > 0) {
+                    const existingRows = db.prepare(`SELECT id FROM ${tableName}`).all();
+                    for (const existing of existingRows) {
+                        if (!incomingIds.has(existing.id)) {
+                            db.prepare(`DELETE FROM ${tableName} WHERE id = ?`).run(existing.id);
+                        }
+                    }
+                }
+                db.exec('COMMIT');
+            }
+            catch (error) {
+                db.exec('ROLLBACK');
+                throw error;
+            }
+        },
+        async exists() {
+            const db = await scopedDb();
+            const row = onTable(() => db.prepare(`SELECT COUNT(*) as count FROM ${tableName}`).get(), null);
+            return (row?.count ?? 0) > 0;
+        },
+        async delete() {
+            const db = await scopedDb();
+            onTable(() => db.prepare(`DELETE FROM ${tableName}`).run(), null);
+        },
+        getPath() {
+            return `localdb://${defaultDbPath()}/${tableName}`;
+        }
+    };
+}
+/**
+ * Recovery continues with a fresh handle; a failed release of the stale or
+ * unhealthy one is reported once, value-free, on the runtime this call serves.
+ */
+function logReleaseFailure(runtime, dbPath, handle) {
+    return (error) => {
+        const logger = getLogger('storage:localdb-adapter', runtime);
+        logger.warn('storage.localdb: releasing a database handle failed', {
+            dbPath,
+            handle,
+            error: valueFreeFailure(error)
+        });
+    };
+}
+/**
+ * The adapter begins database work only on a live runtime (RC07). Its opens,
+ * migrations and queries report on the runtime the call serves (C083a); a
+ * runtime whose disposal began (`finalizing` or `disposed`) is closing its
+ * Logging and LocalDB connections, so work started there is refused before it
+ * begins, typed as a cancellation (`CANCELLED` `runtime-disposed`): its
+ * runtime ended, which the caller treats as a confirmed end. Releasing
+ * handles stays available; that is how the runtime gives them back.
+ */
+function assertStorageRuntimeLive(runtime, operation) {
+    const { phase } = runtime.lifecycle;
+    if (phase === 'live')
+        return;
+    throw new CapabilityError(`storage.localdb starts no ${operation} on a runtime whose disposal began.`, 'CANCELLED', {
+        reason: 'runtime-disposed',
+        retryable: false,
+        cause: runtime.lifecycle.signal.reason,
+        details: { operation, phase },
+        recoveryHint: 'Use the live runtime handed to this call.'
+    });
+}
+// Implementation Export
+export default createRuntimeImplementation({
+    id: 'storage.localdb',
+    kind: 'storage/adapter',
+    constraint: {
+        hardware: ['consumer'] // Only works on consumer hardware with local filesystem
+    },
+    // A class: the storage/adapter kind constructs one per runtime, so one
+    // runtime's configure() never re-points another runtime's adapter.
+    implementation: LocalDBStorageAdapter
+});
+// Testing Utilities
+/**
+ * Create a fresh LocalDB adapter instance (for testing)
+ * @param basePath - Base directory for the database file
+ * @param dbName - Optional database filename (default: unique timestamp-based name)
+ */
+export function createTestLocalDBAdapter(basePath, dbName, 
+/**
+ * The workspace, roots and runtime a manifest would hand over, for a test
+ * that reads the adapter directly; without a runtime, opening a database
+ * refuses (`storage-adapter-unconfigured`) until a manifest configures one.
+ */
+scope) {
+    const adapter = new LocalDBStorageAdapter();
+    adapter.configure({ basePath, dbName: dbName ?? `test-${Date.now()}.db`, ...scope });
+    return adapter;
+}
+//# sourceMappingURL=localdb.adapter.impl.js.map