@abloatai/ablo 0.3.0

package/dist/client/identity.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Participant identity + scope resolution for `Ablo()`.
+ *
+ * Three branches, mirroring the three auth paths the SDK supports:
+ *
+ *   1. **Hosted-cloud** — caller passed `apiKey`. SDK exchanges it
+ *      server-side for a capability token + scope blob, then sets
+ *      up a refresh scheduler that re-mints transparently before
+ *      expiry.
+ *   2. **Self-derived** — caller passed an authToken / capability
+ *      token but the SDK doesn't yet know the identity. Calls
+ *      `resolveIdentity` against the bootstrap endpoint to recover
+ *      `participantId` + scope from the token.
+ *   3. **Legacy explicit** — self-hosted callers that pass
+ *      `organizationId` + `user.id` (or `agentId`) directly. No
+ *      server round-trip; SDK trusts the caller.
+ *
+ * Extracted from `Ablo.ts` so each branch is testable in isolation
+ * and the constructor body reads as a single named call rather than
+ * a 100+-line if/elif/else with three different side-effect chains.
+ */
+import { type RefreshScheduler } from '../auth/index.js';
+import type { BootstrapHelper } from '../sync/BootstrapHelper.js';
+import type { SyncLogger } from '../interfaces/index.js';
+import type { ApiKeySetter } from './auth.js';
+export interface IdentityResolveInput {
+    readonly options: {
+        readonly capabilityToken?: string;
+        readonly bootstrapBaseUrl?: string;
+        readonly user?: {
+            id: string;
+            teamIds?: string[];
+        };
+        readonly agentId?: string;
+        readonly syncGroups?: string[];
+    };
+    readonly internalOptions: {
+        readonly organizationId?: string;
+    };
+    readonly url: string;
+    readonly kind: 'user' | 'agent' | 'system';
+    readonly configuredApiKey: string | ApiKeySetter | null;
+    readonly configuredAuthToken: string | null;
+    readonly bootstrapHelper: BootstrapHelper;
+    readonly logger: SyncLogger;
+    /**
+     * Called when the hosted-cloud refresh scheduler rotates the
+     * capability token — caller forwards the new token to the live
+     * WebSocket via `ws.setCapabilityToken(...)`.
+     */
+    readonly applyRotatedToken: (token: string) => void;
+}
+export interface ResolvedIdentity {
+    readonly userId: string;
+    readonly accountScope: string;
+    readonly teamIds: string[] | undefined;
+    readonly capabilityToken: string | undefined;
+    readonly syncGroups: readonly string[] | undefined;
+    readonly participantKind: 'user' | 'agent' | 'system';
+    /** Non-null on the hosted-cloud path; caller stores it for shutdown. */
+    readonly refreshScheduler: RefreshScheduler | null;
+}
+export declare function resolveParticipantIdentity(input: IdentityResolveInput): Promise<ResolvedIdentity>;

package/dist/client/identity.js

@@ -0,0 +1,156 @@
+/**
+ * Participant identity + scope resolution for `Ablo()`.
+ *
+ * Three branches, mirroring the three auth paths the SDK supports:
+ *
+ *   1. **Hosted-cloud** — caller passed `apiKey`. SDK exchanges it
+ *      server-side for a capability token + scope blob, then sets
+ *      up a refresh scheduler that re-mints transparently before
+ *      expiry.
+ *   2. **Self-derived** — caller passed an authToken / capability
+ *      token but the SDK doesn't yet know the identity. Calls
+ *      `resolveIdentity` against the bootstrap endpoint to recover
+ *      `participantId` + scope from the token.
+ *   3. **Legacy explicit** — self-hosted callers that pass
+ *      `organizationId` + `user.id` (or `agentId`) directly. No
+ *      server round-trip; SDK trusts the caller.
+ *
+ * Extracted from `Ablo.ts` so each branch is testable in isolation
+ * and the constructor body reads as a single named call rather than
+ * a 100+-line if/elif/else with three different side-effect chains.
+ */
+import { AbloAuthenticationError } from '../errors.js';
+import { exchangeApiKey } from '../auth/index.js';
+import { resolveIdentity } from '../auth/index.js';
+import { createRefreshScheduler, } from '../auth/index.js';
+import { resolveApiKeyValue } from './auth.js';
+export async function resolveParticipantIdentity(input) {
+    const { options, internalOptions, url, kind, configuredApiKey, configuredAuthToken, bootstrapHelper, logger, applyRotatedToken, } = input;
+    const apiKeyValue = await resolveApiKeyValue(configuredApiKey);
+    const initialCapToken = options.capabilityToken ?? configuredAuthToken ?? undefined;
+    // Branch 1: hosted-cloud (apiKey only, no caller-supplied capability token)
+    if (apiKeyValue && !options.capabilityToken) {
+        return resolveHosted({
+            apiKeyValue,
+            configuredApiKey,
+            url,
+            kind,
+            options,
+            bootstrapHelper,
+            logger,
+            applyRotatedToken,
+        });
+    }
+    // Branch 2: self-derived (capability token present, identity unknown)
+    if (!internalOptions.organizationId ||
+        (kind === 'agent' ? !options.agentId : !options.user?.id)) {
+        const baseUrl = options.bootstrapBaseUrl ?? `${url.replace(/^ws/, 'http')}/api`;
+        const identity = await resolveIdentity({
+            baseUrl,
+            authToken: initialCapToken,
+        });
+        // Merge caller-passed syncGroups with server-resolved ones rather
+        // than letting the server's response silently overwrite. Browser
+        // consumers (apps/web's SyncEngineProvider) compose
+        // `['default', 'org:${orgId}', 'user:${userId}', ...team:]` from
+        // the resolved session and pass it via `<AbloProvider syncGroups>`;
+        // before this merge, Branch 2 dropped that set on the floor in
+        // favor of `/auth/identity`'s response, which is empty for
+        // cookie-auth users today (apps/sync-server/src/routes/auth.ts only
+        // populates from `effectiveSyncGroups`, the cap-narrowed list).
+        // Empty syncGroups → server bootstrap falls back to `['default']`
+        // → no deltas fan out → live updates appear only on hard reload.
+        const callerGroups = options.syncGroups ?? [];
+        const mergedSyncGroups = callerGroups.length > 0
+            ? [...new Set([...callerGroups, ...identity.syncGroups])]
+            : identity.syncGroups;
+        bootstrapHelper.setCacheScope(identity.accountScope);
+        bootstrapHelper.setSyncGroups(mergedSyncGroups);
+        bootstrapHelper.setAuthToken(initialCapToken);
+        return {
+            userId: identity.participantId,
+            accountScope: identity.accountScope,
+            teamIds: undefined,
+            capabilityToken: initialCapToken,
+            syncGroups: mergedSyncGroups,
+            participantKind: identity.participantKind,
+            refreshScheduler: null,
+        };
+    }
+    // Branch 3: legacy explicit (self-hosted, pre-Phase-3 — caller knows
+    // its own organizationId + user/agentId).
+    const userId = kind === 'agent' ? options.agentId : options.user.id;
+    const accountScope = internalOptions.organizationId;
+    bootstrapHelper.setCacheScope(accountScope);
+    bootstrapHelper.setSyncGroups(options.syncGroups);
+    bootstrapHelper.setAuthToken(initialCapToken);
+    return {
+        userId,
+        accountScope,
+        teamIds: kind === 'user' ? options.user?.teamIds : undefined,
+        capabilityToken: initialCapToken,
+        syncGroups: options.syncGroups,
+        participantKind: kind,
+        refreshScheduler: null,
+    };
+}
+async function resolveHosted(input) {
+    // Pure managed-cloud shape: `Ablo({schema, apiKey})`. Server returns
+    // scope + userMeta; SDK populates internals.
+    const baseUrl = input.options.bootstrapBaseUrl ??
+        `${input.url.replace(/^ws/, 'http')}/api`;
+    const exchangeArgs = {
+        baseUrl,
+        participantKind: (input.kind === 'agent' ? 'agent' : 'system'),
+        participantId: input.options.agentId ?? input.options.user?.id,
+        wideScope: true,
+        ttlSeconds: 3600,
+    };
+    const exchange = await exchangeApiKey({
+        ...exchangeArgs,
+        apiKey: input.apiKeyValue,
+    });
+    input.bootstrapHelper.setCacheScope(exchange.scope.organizationId);
+    input.bootstrapHelper.setSyncGroups(exchange.scope.syncGroups);
+    input.bootstrapHelper.setAuthToken(exchange.token);
+    // Cap tokens have a server-set TTL (3600s by default). Without
+    // proactive refresh the WS would either get force-closed at expiry
+    // or fail its next reconnect with 401. The scheduler re-mints
+    // transparently before that fires; the consumer never sees the
+    // rotation. Rationale + tradeoffs in
+    //   `packages/sync-engine/src/auth/refreshScheduler.ts`
+    const refreshScheduler = createRefreshScheduler({
+        initialExpiresAtMs: Date.parse(exchange.expiresAt),
+        refresh: async () => {
+            // Read the apiKey fresh each time — supports the ApiKeySetter
+            // (rotating credentials) shape.
+            const freshApiKey = await resolveApiKeyValue(input.configuredApiKey);
+            if (!freshApiKey) {
+                throw new AbloAuthenticationError('apiKey unavailable during refresh', { code: 'apikey_missing' });
+            }
+            const next = await exchangeApiKey({
+                ...exchangeArgs,
+                apiKey: freshApiKey,
+            });
+            input.bootstrapHelper.setAuthToken(next.token);
+            input.applyRotatedToken(next.token);
+            return { expiresAtMs: Date.parse(next.expiresAt) };
+        },
+        onError: (err) => {
+            input.logger.warn('cap token refresh failed; will retry', {
+                error: err.message,
+            });
+        },
+    });
+    return {
+        userId: exchange.scope.participantId,
+        accountScope: exchange.scope.organizationId,
+        // teamIds isn't needed because the server already encoded
+        // team-level access into scope.syncGroups.
+        teamIds: undefined,
+        capabilityToken: exchange.token,
+        syncGroups: exchange.scope.syncGroups,
+        participantKind: input.kind,
+        refreshScheduler,
+    };
+}

package/dist/client/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @ablo/sync-engine/client — Consumer API
+ *
+ * The one-liner entry point for external consumers.
+ *
+ * `Ablo({ apiKey })` is the stateless HTTP API client. Add `schema`
+ * when you want the realtime sync engine with typed model proxies.
+ *
+ * ```ts
+ * import { Ablo } from '@ablo/sync-engine/client';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({
+ *   schema,
+ *   apiKey: process.env.ABLO_API_KEY,
+ * });
+ *
+ * const tasks = ablo.tasks.list({ where: { status: 'todo' } });
+ * await ablo.tasks.create({ title: 'New task' });
+ * ```
+ *
+ * For headless agents (workers, bots), pass `kind: 'agent'` plus a
+ * Biscuit `capabilityToken`:
+ *
+ * ```ts
+ * const bot = Ablo({
+ *   schema,
+ *   apiKey: process.env.ABLO_API_KEY,
+ *   kind: 'agent',
+ * });
+ * ```
+ */
+export { Ablo, computeFKDepthPriority, type AbloOptions, type InternalAbloOptions, type BusyOptions, type BusyPolicy, type IntentWaitOptions, type ModelCountOptions, type ModelListOptions, type ModelListScope, type ModelLoadOptions, type ModelOperations, type ResourceReadOptions, } from './Ablo.js';
+export type { AbloPersistence } from './persistence.js';
+export type { AbloApi, AbloApiClientOptions, AbloApiIntents, Agent, AgentIntentInput, AgentIntentOptions, AgentOptions, AgentResourceClient, AgentResourceReadOptions, AgentResourceMutationOptions, AgentRunContext, AgentRunDone, AgentRunFailed, AgentRunCancelled, AgentRunOptions, AgentRunResult, AgentRunStatus, Capability, CapabilityCreateOptions, CapabilityParticipantKind, CapabilityRecord, CapabilityResource, CapabilityRevocation, CapabilityScope, Task, TaskCloseOptions, TaskCloseResult, TaskCreateOptions, TaskResource, } from './ApiClient.js';
+export type { EngineParticipant, JoinedParticipant, ParticipantJoinOptions, ParticipantManager, ParticipantScope, ParticipantStatus, ScopedIntents, ScopedPresence, } from '../sync/participants.js';

package/dist/client/index.js

@@ -0,0 +1,33 @@
+/**
+ * @ablo/sync-engine/client — Consumer API
+ *
+ * The one-liner entry point for external consumers.
+ *
+ * `Ablo({ apiKey })` is the stateless HTTP API client. Add `schema`
+ * when you want the realtime sync engine with typed model proxies.
+ *
+ * ```ts
+ * import { Ablo } from '@ablo/sync-engine/client';
+ * import { schema } from './schema';
+ *
+ * const ablo = Ablo({
+ *   schema,
+ *   apiKey: process.env.ABLO_API_KEY,
+ * });
+ *
+ * const tasks = ablo.tasks.list({ where: { status: 'todo' } });
+ * await ablo.tasks.create({ title: 'New task' });
+ * ```
+ *
+ * For headless agents (workers, bots), pass `kind: 'agent'` plus a
+ * Biscuit `capabilityToken`:
+ *
+ * ```ts
+ * const bot = Ablo({
+ *   schema,
+ *   apiKey: process.env.ABLO_API_KEY,
+ *   kind: 'agent',
+ * });
+ * ```
+ */
+export { Ablo, computeFKDepthPriority, } from './Ablo.js';

package/dist/client/persistence.d.ts

@@ -0,0 +1,7 @@
+export type AbloPersistence = 'volatile' | 'indexeddb';
+export interface PersistenceOptions {
+    readonly persistence?: AbloPersistence | undefined;
+    readonly inMemory?: boolean | undefined;
+    readonly offline?: boolean | undefined;
+}
+export declare function shouldUseInMemoryPersistence(options: PersistenceOptions): boolean;

package/dist/client/persistence.js

@@ -0,0 +1,11 @@
+export function shouldUseInMemoryPersistence(options) {
+    if (typeof window === 'undefined')
+        return true;
+    if (options.persistence)
+        return options.persistence === 'volatile';
+    if (typeof options.inMemory === 'boolean')
+        return options.inMemory;
+    if (options.offline === true)
+        return false;
+    return true;
+}

package/dist/client/validateAbloOptions.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Up-front validation of `AbloOptions`. Returns the first error
+ * encountered or null if all checks pass — caller writes the error
+ * into `store.syncStatus` so consumers see it through the existing
+ * status surface rather than catching it at the call site.
+ *
+ * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
+ * so the validation rules are readable in isolation. The order of
+ * checks matters: missing `url` is checked before identity options
+ * because the error messages reference URLs and would mislead if a
+ * URL was actually present.
+ */
+/**
+ * Minimal subset of `AbloOptions` the validator actually inspects.
+ * Defined here as its own interface so the validator doesn't pull
+ * the whole 200+-line `AbloOptions` type — and to avoid a circular
+ * import with `Ablo.ts`. Fields are kept structurally identical to
+ * `AbloOptions` so a real options object satisfies this shape.
+ */
+export interface ValidatableAbloOptions {
+    readonly schema?: {
+        readonly models?: Record<string, unknown>;
+    } | null;
+    readonly kind?: 'user' | 'agent' | 'system';
+    readonly user?: {
+        readonly id?: string;
+    } | undefined;
+    readonly agentId?: string | undefined;
+    readonly capabilityToken?: string | undefined;
+}
+export interface ValidateAbloOptionsInput {
+    readonly options: ValidatableAbloOptions;
+    readonly url: string;
+    /**
+     * Truthy when an API key was supplied (string or callable). The
+     * validator only inspects presence, never the value, so the input
+     * shape stays loose to accept whatever the caller resolved.
+     */
+    readonly configuredApiKey: unknown;
+    readonly configuredAuthToken: unknown;
+}
+export declare function validateAbloOptions(input: ValidateAbloOptionsInput): Error | null;

package/dist/client/validateAbloOptions.js

@@ -0,0 +1,43 @@
+/**
+ * Up-front validation of `AbloOptions`. Returns the first error
+ * encountered or null if all checks pass — caller writes the error
+ * into `store.syncStatus` so consumers see it through the existing
+ * status surface rather than catching it at the call site.
+ *
+ * Extracted from `Ablo.ts` (which was ~2300 LOC of constructor wiring)
+ * so the validation rules are readable in isolation. The order of
+ * checks matters: missing `url` is checked before identity options
+ * because the error messages reference URLs and would mislead if a
+ * URL was actually present.
+ */
+export function validateAbloOptions(input) {
+    const { options, url, configuredApiKey, configuredAuthToken } = input;
+    const kind = options.kind ?? 'user';
+    if (!url) {
+        return new Error('Ablo: `url` is required. Pass the sync server URL, e.g. ' +
+            `Ablo({ baseURL: 'wss://sync.ablo.dev', schema, user })`);
+    }
+    // Schema is optional for the resource-first API:
+    //   Ablo({ apiKey }).resource('clauses').retrieve(...)
+    // Passing a schema only enables typed model sugar (`ablo.tasks.update(...)`).
+    if (!configuredApiKey &&
+        !configuredAuthToken &&
+        !options.capabilityToken &&
+        kind === 'user' &&
+        options.user &&
+        !options.user.id) {
+        return new Error('Ablo: `user.id` must be a non-empty string when `user` is provided.');
+    }
+    if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.agentId) {
+        return new Error('Ablo: provide either `apiKey` or `agentId` for `kind: "agent"`. ' +
+            'Hosted-cloud consumers pass `apiKey` and the server derives the ' +
+            'agent identity from its scope; self-hosted passes `agentId` + ' +
+            '`capabilityToken` directly.');
+    }
+    if (!configuredApiKey && !configuredAuthToken && kind === 'agent' && !options.capabilityToken) {
+        return new Error('Ablo: provide either `apiKey` (hosted cloud — SDK exchanges internally) ' +
+            'or `capabilityToken` (self-hosted — your auth layer mints + hands in). ' +
+            'See https://ablo.dev/docs/api-keys for the full pattern.');
+    }
+    return null;
+}

package/dist/config/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @ablo/sync-engine/config — App initialization
+ *
+ * One-time setup at app boot. Provides DI interface types
+ * and the initSyncEngine() function to wire real implementations.
+ */
+export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
+export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, type SyncEngineContext, } from '../SyncEngineContext.js';
+export type { SyncEngineConfig, SyncLogger, SyncObservabilityProvider, SyncAnalytics, MutationExecutor, MutationDispatcher, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, BreadcrumbLevel, SyncBreadcrumbCategory, TransactionFailureDetails, BootstrapFailureDetails, WebSocketErrorDetails, RollbackDetails, SpanAttributes, } from '../interfaces/index.js';
+export { SyncSessionError } from '../errors.js';

package/dist/config/index.js

@@ -0,0 +1,12 @@
+/**
+ * @ablo/sync-engine/config — App initialization
+ *
+ * One-time setup at app boot. Provides DI interface types
+ * and the initSyncEngine() function to wire real implementations.
+ */
+// Context lifecycle
+export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
+// Context type + no-op defaults (for testing or gradual adoption)
+export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from '../SyncEngineContext.js';
+// Errors
+export { SyncSessionError } from '../errors.js';

package/dist/context.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Module-level context accessor
+ *
+ * Set once during SDK initialization via `initSyncEngine(context)`.
+ * All internal SDK files access dependencies through `getContext()`.
+ * This avoids threading context through every constructor.
+ */
+import type { SyncEngineContext } from './SyncEngineContext.js';
+/**
+ * Initialize the sync engine with application-provided dependencies.
+ * Must be called before any sync engine operations.
+ */
+export declare function initSyncEngine(context: SyncEngineContext): void;
+/**
+ * Get the current sync engine context.
+ * Returns a safe fallback with no-op implementations if not yet initialized,
+ * so SDK files can import at module load time without crashing.
+ */
+export declare function getContext(): SyncEngineContext;
+/**
+ * Check if the sync engine has been initialized.
+ */
+export declare function isSyncEngineInitialized(): boolean;
+/**
+ * Reset context (for testing or cleanup).
+ */
+export declare function resetSyncEngine(): void;

package/dist/context.js

@@ -0,0 +1,58 @@
+/**
+ * Module-level context accessor
+ *
+ * Set once during SDK initialization via `initSyncEngine(context)`.
+ * All internal SDK files access dependencies through `getContext()`.
+ * This avoids threading context through every constructor.
+ */
+import { noopLogger, noopObservability, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from './SyncEngineContext.js';
+let _context = null;
+/**
+ * Initialize the sync engine with application-provided dependencies.
+ * Must be called before any sync engine operations.
+ */
+export function initSyncEngine(context) {
+    _context = context;
+}
+/**
+ * Get the current sync engine context.
+ * Returns a safe fallback with no-op implementations if not yet initialized,
+ * so SDK files can import at module load time without crashing.
+ */
+export function getContext() {
+    if (!_context) {
+        return _fallback;
+    }
+    return _context;
+}
+/**
+ * Check if the sync engine has been initialized.
+ */
+export function isSyncEngineInitialized() {
+    return _context !== null;
+}
+/**
+ * Reset context (for testing or cleanup).
+ */
+export function resetSyncEngine() {
+    _context = null;
+}
+/** Fallback context with no-op implementations */
+const _fallback = {
+    logger: noopLogger,
+    observability: noopObservability,
+    onlineStatus: browserOnlineStatus,
+    sessionErrorDetector: defaultSessionErrorDetector,
+    config: emptyConfig,
+    mutationExecutor: {
+        commit: () => Promise.resolve({ lastSyncId: 0 }),
+        executeCreate: () => Promise.resolve(),
+        executeUpdate: () => Promise.resolve(null),
+        executeDelete: () => Promise.resolve(),
+        executeArchive: () => Promise.resolve(),
+        executeUnarchive: () => Promise.resolve(),
+    },
+    mutationDispatcher: {
+        dispatch: () => Promise.resolve(),
+    },
+};

package/dist/core/DatabaseManager.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Ablo Sync Engine - Database Manager
+ *
+ * Manages the two-tier database architecture:
+ * 1. ablo_databases - Metadata about workspace databases
+ * 2. ablo_(hash) - Workspace-specific data storage
+ *
+ * Follows Ablo's architecture for database management.
+ */
+export interface DatabaseInfo {
+    name: string;
+    userId: string;
+    workspaceId: string;
+    schemaHash: string;
+    schemaVersion: number;
+    userVersion?: number;
+    createdAt: Date;
+    updatedAt: Date;
+}
+export interface WorkspaceMetadata {
+    lastSyncId: number;
+    firstSyncId: number;
+    backendDatabaseVersion: number;
+    subscribedSyncGroups: string[];
+    updatedAt: Date;
+    schemaHash?: string;
+    syncGroups?: string[];
+    versions?: Record<string, number>;
+}
+/**
+ * DatabaseManager - Manages Ablo's two-tier database architecture
+ *
+ * Key responsibilities:
+ * - Manages ablo_databases (database registry)
+ * - Creates workspace-specific databases (ablo_hash)
+ * - Handles database migration and versioning
+ * - Provides database info and metadata management
+ */
+export declare class DatabaseManager {
+    private metaDb;
+    private readonly metaDbName;
+    constructor();
+    /**
+     * Initialize the meta database (ablo_databases)
+     */
+    initializeMetaDatabase(): Promise<void>;
+    /**
+     * Calculate database info for a user/workspace combination
+     */
+    calculateDatabaseInfo(userId: string, workspaceId: string, userVersion?: number): Promise<DatabaseInfo>;
+    /**
+     * Generate deterministic database name
+     */
+    private generateDatabaseName;
+    /**
+     * Register database info in ablo_databases
+     */
+    registerDatabase(info: DatabaseInfo): Promise<void>;
+    /**
+     * Get database info by name
+     */
+    getDatabaseInfo(name: string): Promise<DatabaseInfo | null>;
+    /**
+     * Get all databases for a user
+     */
+    getDatabasesForUser(userId: string): Promise<DatabaseInfo[]>;
+    /**
+     * Open workspace-specific database
+     */
+    openWorkspaceDatabase(dbInfo: DatabaseInfo, createStoresFn?: (db: IDBDatabase, tx: IDBTransaction) => Promise<void>): Promise<IDBDatabase>;
+    /**
+     * Read workspace metadata from __meta table
+     */
+    getWorkspaceMetadata(db: IDBDatabase): Promise<WorkspaceMetadata | null>;
+    /**
+     * Write workspace metadata to __meta table
+     */
+    setWorkspaceMetadata(db: IDBDatabase, metadata: WorkspaceMetadata): Promise<void>;
+    /**
+     * Check if a model is persisted (all instances loaded)
+     */
+    isModelPersisted(db: IDBDatabase, modelName: string): Promise<boolean>;
+    /**
+     * Mark a model as persisted
+     */
+    setModelPersisted(db: IDBDatabase, modelName: string, persisted: boolean): Promise<void>;
+    /**
+     * Get all model persistence states
+     */
+    getAllModelPersistenceStates(db: IDBDatabase): Promise<Record<string, boolean>>;
+    /**
+     * Delete a workspace database
+     */
+    deleteWorkspaceDatabase(dbInfo: DatabaseInfo): Promise<void>;
+    /**
+     * Get comprehensive database statistics
+     */
+    getDatabaseStatistics(): Promise<{
+        metaDatabaseSize: number;
+        totalWorkspaceDatabases: number;
+        databasesByUser: Record<string, number>;
+        schemaVersions: Record<string, number>;
+    }>;
+    /**
+     * Close all database connections
+     */
+    close(): Promise<void>;
+}