@vibesdotdev/storage 0.0.2 → 1.0.0-rc.3

package/dist/adapters/localdb/localdb.adapter.impl.d.ts

@@ -0,0 +1,237 @@
+/**
+ * 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 { type RuntimeRef } from '@vibesdotdev/kernel';
+import type { KindContext } from '@vibesdotdev/kernel/schemas/kind';
+import type { z } from 'zod/v4';
+import type { StorageAdapterInterface, StorageAdapterCapabilities, LocalDBAdapterConfig, StorageDocumentStoreInterface, StorageKeyValueInterface, StorageRepositoryInterface, RepositoryOptions, StorageHealthStatus, StorageRecordInterface } from '@vibesdotdev/storage/interfaces';
+import type { StorageRecordDescriptor } from '@vibesdotdev/storage/schemas/record';
+import type { PathRoots } from '@vibesdotdev/paths';
+import { type SqliteConnection } from '@vibesdotdev/localdb';
+type ScopedManifestTarget = {
+    workspaceRoot: string;
+    basePath: string;
+    dbPath: string;
+    migrationKey: string;
+};
+/**
+ * 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 declare class LocalDBStorageAdapter implements StorageAdapterInterface<LocalDBAdapterConfig> {
+    readonly id = "storage.localdb";
+    readonly capabilities: StorageAdapterCapabilities;
+    private config;
+    private database;
+    private initialized;
+    /**
+     * 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.
+     */
+    private scopedDatabases;
+    /**
+     * 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.
+     */
+    private recordDatabases;
+    /**
+     * 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: LocalDBAdapterConfig): void;
+    isConfigured(): boolean;
+    /** The configuration, or the typed refusal for an adapter used before `configure()`. */
+    private requireConfig;
+    /**
+     * 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.
+     */
+    private requireRuntime;
+    /**
+     * 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.
+     */
+    private ensureDirectory;
+    /** Whether the database file at `dbPath` exists, asked of the runtime's filesystem kind. */
+    private databaseFileExists;
+    private ensureInitialized;
+    /** The adapter's default database, opened (on the configured runtime) if it is not yet. */
+    private openDefaultDatabase;
+    /** The open default database, or the typed refusal when none is open yet. */
+    private defaultConnection;
+    private getDbPath;
+    /**
+     * 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.
+     */
+    private configuredScopeInputs;
+    /**
+     * 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).
+     */
+    private resolveScopedManifestTarget;
+    private getScopedDb;
+    private getOpenedDatabasePath;
+    /**
+     * Track which custom migration keys have been applied to which databases
+     * to avoid redundant migration attempts.
+     */
+    private appliedCustomMigrations;
+    /**
+     * 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.
+     */
+    private ensureCustomMigrations;
+    private runPendingMigrations;
+    documentStore<T, Manifest = undefined>(namespace: string, schema: z.ZodType<T>, manifest?: Manifest): StorageDocumentStoreInterface<T>;
+    keyValueStore<TKey, TValue>(namespace: string, keySchema: z.ZodType<TKey>, valueSchema: z.ZodType<TValue>): StorageKeyValueInterface<TKey, TValue>;
+    /**
+     * 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<T = unknown>(descriptor: StorageRecordDescriptor, context?: KindContext): StorageRecordInterface<T>;
+    /**
+     * Create FTS virtual table for a record descriptor
+     */
+    private createFtsTables;
+    repository<T>(tableName: string, schema: z.ZodType<T>, options?: RepositoryOptions): StorageRepositoryInterface<T>;
+    ensureReady(): Promise<void>;
+    getDatabaseConnection(): SqliteConnection;
+    /**
+     * 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.
+     */
+    getScopedDatabaseConnection<Manifest>(manifest?: Manifest): Promise<SqliteConnection>;
+    /** Open a manifest's scoped connection and report the immutable target it used. */
+    getScopedDatabaseConnectionWithIdentity<Manifest>(manifest?: Manifest): Promise<{
+        connection: SqliteConnection;
+        identity: Pick<ScopedManifestTarget, 'workspaceRoot' | 'dbPath'>;
+    }>;
+    /** Resolve the same manifest target used by getScopedDatabaseConnection(). */
+    getScopedDatabaseConnectionIdentity<Manifest>(manifest?: Manifest): Promise<Pick<ScopedManifestTarget, 'workspaceRoot' | '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.
+     */
+    getRecordDatabaseConnection(config: {
+        basePath: string;
+        dbName?: string;
+        runtime: RuntimeRef;
+    }): Promise<SqliteConnection>;
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * 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.
+     */
+    healthCheck(): Promise<StorageHealthStatus>;
+}
+declare const _default: import("@vibesdotdev/kernel").RuntimeImplementationWrapper<typeof LocalDBStorageAdapter>;
+export default _default;
+/**
+ * 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 declare function createTestLocalDBAdapter(basePath: string, dbName?: string, 
+/**
+ * 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?: {
+    workspacePath: string;
+    roots: PathRoots;
+    runtime?: RuntimeRef;
+}): StorageAdapterInterface<LocalDBAdapterConfig>;
+//# sourceMappingURL=localdb.adapter.impl.d.ts.map

package/dist/adapters/localdb/localdb.adapter.impl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localdb.adapter.impl.d.ts","sourceRoot":"","sources":["../../../src/adapters/localdb/localdb.adapter.impl.ts"],"names":[],"mappings":"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"}