@abloatai/humans 0.37.0

package/dist/local/stores/DatabaseManager.js

@@ -0,0 +1,400 @@
+/**
+ * Manages the client-side IndexedDB databases the sync engine keeps in the
+ * browser. There are two tiers. A single registry database, `ablo_databases`,
+ * records metadata about every workspace database. Each user-and-workspace pair
+ * then gets its own data database, named `ablo_<hash>`, that holds the synced
+ * rows. {@link DatabaseManager} creates, versions, and deletes both tiers.
+ */
+import { globalRuntime } from '../context.js';
+import { openIDBWithTimeout, deleteIDBWithTimeout, IDBOpenTimeoutError, } from './openIDBWithTimeout.js';
+import { AbloConnectionError } from '@abloatai/transaction/errors';
+import { getActiveRegistry, hasActiveRegistry } from '../ModelRegistry.js';
+import { PERSISTENCE_NAMESPACE_VERSION, persistenceDatabaseName, persistenceIdentityMatches, } from './persistenceIdentity.js';
+function indexedDbError(error, operation) {
+    return error ?? new Error(`IndexedDB ${operation} failed`);
+}
+/**
+ * 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 class DatabaseManager {
+    runtime;
+    metaDb = null;
+    metaDbName = 'ablo_databases';
+    constructor(runtime = globalRuntime) {
+        this.runtime = runtime;
+    }
+    /**
+     * Initialize the meta database (ablo_databases)
+     */
+    async initializeMetaDatabase() {
+        const open = () => openIDBWithTimeout(this.metaDbName, 1, {
+            onUpgrade: (request) => {
+                const db = request.result;
+                if (!db.objectStoreNames.contains('databases')) {
+                    const store = db.createObjectStore('databases', { keyPath: 'name' });
+                    store.createIndex('userId', 'userId');
+                    store.createIndex('workspaceId', 'workspaceId');
+                    store.createIndex('schemaHash', 'schemaHash');
+                    store.createIndex('updatedAt', 'updatedAt');
+                }
+            },
+        });
+        try {
+            this.metaDb = await open();
+        }
+        catch (error) {
+            // Self-heal a wedged meta DB. When `ablo_databases`'s backing store gets
+            // stuck (a corrupted store, or a leaked connection from a prior
+            // timed-out open), every open of that name hangs with no event and the
+            // app is permanently bricked until the user manually clears site data —
+            // the "open did not resolve within 10000ms" dead end. The registry this
+            // DB holds is rebuildable from the server on the next bootstrap, so it is
+            // safe to delete and re-create. Try exactly once: delete, then re-open.
+            if (!(error instanceof IDBOpenTimeoutError))
+                throw error;
+            this.runtime.logger.debug('[sync-engine] meta DB open timed out — attempting self-heal (delete + retry)', { db: this.metaDbName, reason: error.reason });
+            this.runtime.observability.captureBootstrapFailure(error, {
+                type: 'meta-db-open-timeout',
+            });
+            const deleted = await deleteIDBWithTimeout(this.metaDbName);
+            if (!deleted) {
+                // The delete itself was blocked/stuck — a live connection in another
+                // window or a deadlocked backing store. We cannot recover in-page;
+                // rethrow so the provider surfaces the real (now actionable) error.
+                throw error;
+            }
+            // Fresh store — this open creates `ablo_databases` from scratch.
+            this.metaDb = await open();
+            this.runtime.logger.info('[sync-engine] meta DB self-heal succeeded');
+        }
+    }
+    /**
+     * Calculate database info for a user/workspace combination
+     */
+    async calculateDatabaseInfo(identity, userVersion = 1) {
+        // Get schema hash from the active ModelRegistry
+        const schemaHash = hasActiveRegistry()
+            ? getActiveRegistry().getSchemaHash()
+            : 'no-registry-hash';
+        // Generate database name from userId, workspaceId, and versions
+        const dbName = await persistenceDatabaseName(identity, userVersion);
+        // Check if we need to increment schema version
+        const existingInfo = await this.getDatabaseInfo(dbName);
+        if (existingInfo && !persistenceIdentityMatches(existingInfo, identity)) {
+            throw new AbloConnectionError('Local database identity mismatch. Refusing to open persisted data ' +
+                'owned by a different authenticated plane.', { code: 'db_identity_mismatch' });
+        }
+        let schemaVersion = 1;
+        if (existingInfo && existingInfo.schemaHash !== schemaHash) {
+            schemaVersion = (existingInfo.schemaVersion || 1) + 1;
+        }
+        else if (existingInfo) {
+            schemaVersion = existingInfo.schemaVersion || 1;
+        }
+        // Record the existing databases for this user so duplicates can be detected.
+        const allUserDatabases = await this.getDatabasesForUser(identity.participantId);
+        const allIndexedDBs = (await indexedDB.databases?.()) || [];
+        const abloDatabases = allIndexedDBs.filter((db) => db.name?.startsWith('ablo_'));
+        this.runtime.observability.breadcrumb('Database info calculated', 'sync.database', 'info', {
+            dbName,
+            schemaVersion,
+            existingDbCount: allUserDatabases.length,
+            abloDbCount: abloDatabases.length,
+        });
+        return {
+            name: dbName,
+            namespaceVersion: PERSISTENCE_NAMESPACE_VERSION,
+            userId: identity.participantId,
+            workspaceId: identity.organizationId,
+            participantKind: identity.participantKind,
+            projectId: identity.projectId,
+            environment: identity.environment,
+            sandboxId: identity.sandboxId,
+            schemaHash,
+            schemaVersion,
+            userVersion,
+            createdAt: existingInfo?.createdAt ?? new Date(),
+            updatedAt: new Date(),
+        };
+    }
+    /**
+     * Register database info in ablo_databases
+     */
+    async registerDatabase(info) {
+        const metaDb = this.metaDb;
+        if (!metaDb) {
+            throw new AbloConnectionError('Meta database not initialized', {
+                code: 'meta_db_not_initialized',
+            });
+        }
+        return new Promise((resolve, reject) => {
+            const tx = metaDb.transaction(['databases'], 'readwrite');
+            const store = tx.objectStore('databases');
+            const request = store.put(info);
+            tx.oncomplete = () => {
+                resolve();
+            };
+            tx.onerror = () => { reject(indexedDbError(tx.error, 'registry transaction')); };
+            request.onerror = () => { reject(indexedDbError(request.error, 'registry write')); };
+        });
+    }
+    /**
+     * Get database info by name
+     */
+    async getDatabaseInfo(name) {
+        const metaDb = this.metaDb;
+        if (!metaDb)
+            return null;
+        return new Promise((resolve, reject) => {
+            const tx = metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const request = store.get(name);
+            request.onsuccess = () => { resolve(request.result ?? null); };
+            request.onerror = () => { reject(indexedDbError(request.error, 'registry read')); };
+        });
+    }
+    /** Remove only the named ownership records; the shared registry stays live. */
+    async unregisterDatabases(names) {
+        const metaDb = this.metaDb;
+        if (!metaDb || names.length === 0)
+            return;
+        return new Promise((resolve, reject) => {
+            const tx = metaDb.transaction(['databases'], 'readwrite');
+            const store = tx.objectStore('databases');
+            for (const name of new Set(names))
+                store.delete(name);
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(indexedDbError(tx.error, 'registry cleanup')); };
+            tx.onabort = () => { reject(indexedDbError(tx.error, 'registry cleanup')); };
+        });
+    }
+    /**
+     * Get all databases for a user
+     */
+    async getDatabasesForUser(userId) {
+        const metaDb = this.metaDb;
+        if (!metaDb)
+            return [];
+        return new Promise((resolve, reject) => {
+            const tx = metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const index = store.index('userId');
+            const request = index.getAll(userId);
+            request.onsuccess = () => { resolve(request.result || []); };
+            request.onerror = () => { reject(indexedDbError(request.error, 'user database lookup')); };
+        });
+    }
+    /**
+     * Open workspace-specific database
+     */
+    async openWorkspaceDatabase(dbInfo, createStoresFn) {
+        try {
+            return await openIDBWithTimeout(dbInfo.name, dbInfo.schemaVersion, {
+                onUpgrade: (request, event) => {
+                    const db = request.result;
+                    const tx = event.target.transaction;
+                    // IndexedDB rule: only awaits on IndexedDB requests keep an upgrade
+                    // transaction alive. Any other await — a fetch, a timer — commits the
+                    // transaction early, and later operations then throw
+                    // `TransactionInactiveError`. StoreManager.createStores runs only
+                    // synchronous createObjectStore / createIndex calls under an `async`
+                    // keyword, so calling it without awaiting is safe here.
+                    if (createStoresFn && tx) {
+                        try {
+                            void createStoresFn(db, tx).catch((err) => {
+                                this.runtime.observability.captureBootstrapFailure(err, {
+                                    type: 'store-creation',
+                                });
+                            });
+                        }
+                        catch (err) {
+                            this.runtime.observability.captureBootstrapFailure(err, {
+                                type: 'store-creation',
+                            });
+                        }
+                    }
+                },
+            });
+        }
+        catch (error) {
+            this.runtime.observability.captureBootstrapFailure(error, {
+                type: 'database-open',
+            });
+            throw error;
+        }
+    }
+    /**
+     * Read workspace metadata from __meta table
+     */
+    async getWorkspaceMetadata(db) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get('metadata');
+            request.onsuccess = () => {
+                const data = request.result;
+                if (!data) {
+                    resolve(null);
+                    return;
+                }
+                const meta = {
+                    lastSyncId: data.lastSyncId ?? 0,
+                    firstSyncId: data.firstSyncId ?? 0,
+                    backendDatabaseVersion: data.backendDatabaseVersion ?? 1,
+                    subscribedSyncGroups: data.subscribedSyncGroups ?? [],
+                    updatedAt: data.updatedAt ? new Date(data.updatedAt) : new Date(),
+                    schemaHash: data.schemaHash,
+                    syncGroups: data.syncGroups,
+                    // Older persisted records may still carry an extra `versions` key
+                    // that is no longer used; it is tolerated by simply not reading it here.
+                };
+                resolve(meta);
+            };
+            request.onerror = () => { reject(indexedDbError(request.error, 'workspace metadata read')); };
+        });
+    }
+    /**
+     * Write workspace metadata to __meta table
+     */
+    async setWorkspaceMetadata(db, metadata) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const request = store.put(metadata, 'metadata');
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(indexedDbError(tx.error, 'workspace metadata transaction')); };
+            request.onerror = () => { reject(indexedDbError(request.error, 'workspace metadata write')); };
+        });
+    }
+    /**
+     * Check if a model is persisted (all instances loaded)
+     */
+    async isModelPersisted(db, modelName) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.get(modelName);
+            request.onsuccess = () => {
+                const data = request.result;
+                resolve(data?.persisted === true);
+            };
+            request.onerror = () => { reject(indexedDbError(request.error, 'model persistence read')); };
+        });
+    }
+    /**
+     * Mark a model as persisted
+     */
+    async setModelPersisted(db, modelName, persisted) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readwrite');
+            const store = tx.objectStore('__meta');
+            const persistenceData = {
+                persisted,
+                modelName,
+                timestamp: Date.now(),
+                updatedAt: new Date().toISOString(),
+            };
+            const request = store.put(persistenceData, modelName);
+            tx.oncomplete = () => { resolve(); };
+            tx.onerror = () => { reject(indexedDbError(tx.error, 'model persistence transaction')); };
+            request.onerror = () => { reject(indexedDbError(request.error, 'model persistence write')); };
+        });
+    }
+    /**
+     * Get all model persistence states
+     */
+    async getAllModelPersistenceStates(db) {
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(['__meta'], 'readonly');
+            const store = tx.objectStore('__meta');
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const states = {};
+                for (const item of request.result) {
+                    // Skip metadata entry
+                    if (item.key === 'metadata')
+                        continue;
+                    if (item.modelName) {
+                        states[item.modelName] = item.persisted === true;
+                    }
+                }
+                resolve(states);
+            };
+            request.onerror = () => { reject(indexedDbError(request.error, 'model persistence scan')); };
+        });
+    }
+    /**
+     * Delete a workspace database
+     */
+    async deleteWorkspaceDatabase(dbInfo) {
+        const deleted = await deleteIDBWithTimeout(dbInfo.name);
+        if (!deleted) {
+            this.runtime.observability.breadcrumb(`Database deletion failed or was blocked: ${dbInfo.name}`, 'sync.database', 'error');
+            return false;
+        }
+        if (this.metaDb) {
+            const metaDb = this.metaDb;
+            await new Promise((resolve, reject) => {
+                const tx = metaDb.transaction(['databases'], 'readwrite');
+                tx.objectStore('databases').delete(dbInfo.name);
+                tx.oncomplete = () => { resolve(); };
+                tx.onerror = () => { reject(indexedDbError(tx.error, 'registry delete')); };
+                tx.onabort = () => { reject(indexedDbError(tx.error, 'registry delete')); };
+            });
+        }
+        return true;
+    }
+    /**
+     * Get comprehensive database statistics
+     */
+    async getDatabaseStatistics() {
+        const metaDb = this.metaDb;
+        if (!metaDb) {
+            return {
+                metaDatabaseSize: 0,
+                totalWorkspaceDatabases: 0,
+                databasesByUser: {},
+                schemaVersions: {},
+            };
+        }
+        return new Promise((resolve, reject) => {
+            const tx = metaDb.transaction(['databases'], 'readonly');
+            const store = tx.objectStore('databases');
+            const request = store.getAll();
+            request.onsuccess = () => {
+                const databases = request.result;
+                const databasesByUser = {};
+                const schemaVersions = {};
+                for (const db of databases) {
+                    // Count by user
+                    databasesByUser[db.userId] = (databasesByUser[db.userId] ?? 0) + 1;
+                    // Count schema versions
+                    const versionKey = `v${db.schemaVersion}`;
+                    schemaVersions[versionKey] = (schemaVersions[versionKey] ?? 0) + 1;
+                }
+                resolve({
+                    metaDatabaseSize: databases.length,
+                    totalWorkspaceDatabases: databases.length,
+                    databasesByUser,
+                    schemaVersions,
+                });
+            };
+            request.onerror = () => { reject(indexedDbError(request.error, 'registry statistics read')); };
+        });
+    }
+    /**
+     * Close all database connections
+     */
+    async close() {
+        if (this.metaDb) {
+            this.metaDb.close();
+            this.metaDb = null;
+        }
+    }
+}

package/dist/local/stores/ObjectStore.d.ts

@@ -0,0 +1,115 @@
+/**
+ * The IndexedDB-backed object store: durable, per-model record storage for
+ * the browser. See {@link ObjectStore}.
+ */
+import type { ModelMetadata } from '@abloatai/transaction/types';
+import type { ObjectStoreContract } from './ObjectStoreContract.js';
+/**
+ * IDB transaction options type (TypeScript's lib.dom.d.ts may be outdated)
+ * durability: 'relaxed' provides ~16x write performance improvement
+ * by not requiring fsync on each transaction commit.
+ * Safe for optimistic sync engines that can recover from server state.
+ */
+interface IDBTransactionOptionsWithDurability {
+    durability?: 'default' | 'relaxed' | 'strict';
+}
+/**
+ * An IndexedDB-backed store holding the records of a single model.
+ *
+ * It implements {@link ObjectStoreContract}, the shared surface that
+ * {@link InMemoryObjectStore} also satisfies, so callers can hold either
+ * implementation behind one type. Because both are checked against the same
+ * interface, any drift between them surfaces as a typecheck error rather
+ * than a runtime surprise.
+ *
+ * The store talks to the native IndexedDB API directly and uses relaxed
+ * transaction durability on writes.
+ */
+export declare class ObjectStore implements ObjectStoreContract {
+    protected db: IDBDatabase;
+    protected modelName: string;
+    protected storeName: string;
+    protected metadata: ModelMetadata;
+    private readonly writeDurability;
+    private isClosing;
+    constructor(db: IDBDatabase, modelName: string, storeName: string, metadata: ModelMetadata, writeDurability?: NonNullable<IDBTransactionOptionsWithDurability['durability']>);
+    /** Insert without replacing an existing key (used by the commit outbox). */
+    add(data: Record<string, unknown>): Promise<void>;
+    /**
+     * Mark this store as closing to prevent new operations
+     */
+    markAsClosing(): void;
+    /**
+     * Check if database is available for operations
+     */
+    private checkDatabaseAvailable;
+    /**
+     * Store a model in IndexedDB.
+     * Matches the {@link InMemoryObjectStore.put} signature so both
+     * stores satisfy the same caller-visible contract.
+     */
+    put(data: Record<string, unknown>): Promise<void>;
+    /**
+     * Get a model by ID
+     */
+    get(id: string): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Batch get multiple models by IDs in a single IDB transaction.
+     * Much faster than N sequential get() calls (1 transaction vs N).
+     */
+    getMany(ids: string[]): Promise<Map<string, Record<string, unknown>>>;
+    /**
+     * Get all models
+     */
+    getAll(): Promise<Record<string, unknown>[]>;
+    /**
+     * Delete a model by ID
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Check if store is ready (has data)
+     */
+    checkIsReady(): Promise<boolean>;
+    /**
+     * Clear all data in store
+     */
+    clear(): Promise<void>;
+    /**
+     * Get count of models in store
+     */
+    count(): Promise<number>;
+    /**
+     * Get models by indexed property
+     */
+    getAllFromIndex(indexName: string, value: IDBValidKey): Promise<Record<string, unknown>[]>;
+    /**
+     * Get models by indexed key (supports compound keys)
+     */
+    getAllForIndexedKey(indexedKey: string, keyValue: IDBValidKey): Promise<Record<string, unknown>[]>;
+    /**
+     * Get first model matching index
+     */
+    getFromIndex(indexName: string, value: IDBValidKey): Promise<Record<string, unknown> | undefined>;
+    /**
+     * Get count from index
+     */
+    countFromIndex(indexName: string, value: IDBValidKey): Promise<number>;
+    /**
+     * Check if any models exist for index value
+     */
+    hasModelsForIndex(indexName: string, value: IDBValidKey): Promise<boolean>;
+    /**
+     * Get store statistics
+     */
+    getStats(): Promise<{
+        count: number;
+        ready: boolean;
+        loadStrategy: string;
+        indexes: string[];
+    }>;
+    /**
+     * Perform maintenance (override in subclasses for specific needs)
+     */
+    performMaintenance(): Promise<void>;
+}
+export {};