@abloatai/ablo 0.3.0

package/dist/core/StoreManager.js

@@ -0,0 +1,334 @@
+/**
+ * Linear Sync Engine - Store Manager
+ *
+ * Manages all ObjectStore instances for registered models.
+ * Creates appropriate store types based on model load strategies.
+ * Follows Linear's architecture with 80+ ObjectStore instances.
+ */
+import { ObjectStore } from '../stores/ObjectStore.js';
+import { SyncActionStore } from '../stores/SyncActionStore.js';
+import { LoadStrategy } from '../types/index.js';
+import { AbloValidationError } from '../errors.js';
+/**
+ * StoreManager - Central manager for all ObjectStore instances
+ *
+ * Key responsibilities:
+ * - Creates ObjectStore instances for each registered model
+ * - Manages store lifecycle and readiness
+ * - Provides unified interface for database operations
+ * - Handles store-specific optimizations based on load strategies
+ */
+export class StoreManager {
+    stores = new Map();
+    syncactionStore = null;
+    db = null;
+    isInitialized = false;
+    modelRegistry;
+    constructor(modelRegistry) {
+        this.modelRegistry = modelRegistry;
+    }
+    /**
+     * Initialize all stores for registered models
+     */
+    async initializeStores(db) {
+        this.db = db;
+        if (this.isInitialized) {
+            getContext().logger.warn('StoreManager already initialized');
+            return;
+        }
+        getContext().logger.info('Initializing ObjectStore instances for all models');
+        const startTime = performance.now();
+        // Get all registered models
+        const allModels = this.modelRegistry.getRegisteredModelNames();
+        for (const modelName of allModels) {
+            await this.createStoreForModel(modelName);
+        }
+        // Initialize SyncactionStore
+        this.syncactionStore = new SyncActionStore(this.db);
+        await this.syncactionStore.initialize();
+        this.isInitialized = true;
+        const duration = performance.now() - startTime;
+        getContext().logger.info('Initialized ObjectStores and SyncactionStore', {
+            count: this.stores.size,
+            ms: duration.toFixed(2),
+        });
+        // Log store distribution
+        const storeTypes = this.getStoreTypeDistribution();
+        getContext().logger.debug('Store distribution', storeTypes);
+    }
+    /**
+     * Create ObjectStore for a specific model
+     */
+    async createStoreForModel(modelName) {
+        const metadata = this.modelRegistry.getMetadata(modelName);
+        if (!metadata) {
+            throw new AbloValidationError(`No metadata found for model: ${modelName}`, {
+                code: 'store_manager_unknown_model',
+            });
+        }
+        // Use model name directly as store name
+        const storeName = modelName;
+        // Create ObjectStore (MVP: simplified - use single store type for all strategies)
+        const store = new ObjectStore(this.db, modelName, storeName, metadata);
+        this.stores.set(modelName, store);
+    }
+    /**
+     * Create stores (tables) in IndexedDB
+     */
+    async createStores(db, transaction) {
+        getContext().logger.info('Creating tables for all registered models');
+        for (const modelName of this.modelRegistry.getRegisteredModelNames()) {
+            const storeName = modelName;
+            const metadata = this.modelRegistry.getMetadata(modelName);
+            // Skip if store already exists
+            if (db.objectStoreNames.contains(storeName)) {
+                continue;
+            }
+            getContext().logger.debug('Creating table', { storeName, modelName });
+            // Create object store with id as keyPath
+            const store = db.createObjectStore(storeName, { keyPath: 'id' });
+            // Create indexes for indexed properties
+            const indexedProperties = this.modelRegistry.getIndexedProperties(modelName);
+            for (const propName of indexedProperties) {
+                try {
+                    store.createIndex(propName, propName, { unique: false });
+                    getContext().logger.debug('Created index', { store: storeName, prop: propName });
+                }
+                catch (error) {
+                    getContext().logger.warn('Failed to create index', { store: storeName, prop: propName, error });
+                }
+            }
+            // For partial load strategy models, we'll create additional partial index database later
+            if (metadata?.loadStrategy === LoadStrategy.partial) {
+                getContext().logger.debug('Model will have additional partial index database', { modelName });
+            }
+        }
+        // Create special tables
+        this.createSpecialTables(db);
+    }
+    /**
+     * Create special tables (sync_action_table, model_table, model_table_partial, __meta, __transactions)
+     */
+    createSpecialTables(db) {
+        // Create sync_action_table for sync actions (delta packets)
+        if (!db.objectStoreNames.contains('sync_action_table')) {
+            const syncActionStore = db.createObjectStore('sync_action_table', { keyPath: 'id' });
+            syncActionStore.createIndex('syncId', 'id');
+            getContext().logger.debug('Created sync_action_table');
+        }
+        // Create __meta table for model persistence state and database metadata
+        if (!db.objectStoreNames.contains('__meta')) {
+            const metaStore = db.createObjectStore('__meta');
+            getContext().logger.debug('Created __meta table');
+        }
+        // Create __transactions table for unsent transactions
+        if (!db.objectStoreNames.contains('__transactions')) {
+            const transactionStore = db.createObjectStore('__transactions', {
+                keyPath: 'id',
+                autoIncrement: false,
+            });
+            // Create indexes for transaction queries
+            transactionStore.createIndex('timestamp', 'timestamp');
+            transactionStore.createIndex('status', 'status');
+            getContext().logger.debug('Created __transactions table');
+        }
+    }
+    /**
+     * Get ObjectStore for a model
+     */
+    getStore(modelName) {
+        return this.stores.get(modelName);
+    }
+    /**
+     * Get SyncactionStore instance
+     */
+    getSyncactionStore() {
+        return this.syncactionStore;
+    }
+    /**
+     * Get all stores
+     */
+    getAllStores() {
+        return new Map(this.stores);
+    }
+    /**
+     * Check readiness of all stores
+     */
+    async checkReadinessOfStores() {
+        const readyStores = [];
+        const notReadyStores = [];
+        for (const [modelName, store] of Array.from(this.stores)) {
+            const isReady = await store.checkIsReady();
+            if (isReady) {
+                readyStores.push(modelName);
+            }
+            else {
+                notReadyStores.push(modelName);
+            }
+        }
+        const allReady = notReadyStores.length === 0;
+        getContext().logger.debug('Store readiness', {
+            ready: readyStores.length,
+            total: this.stores.size,
+            notReady: notReadyStores,
+        });
+        return {
+            ready: allReady,
+            readyStores,
+            notReadyStores,
+            totalStores: this.stores.size,
+        };
+    }
+    /**
+     * Check if ANY data store has at least one record.
+     *
+     * This is the Zero-style cache-validity check: if the stores are empty,
+     * the sync cursor (lastSyncId) is invalid regardless of what the metadata
+     * says. The cursor and the data must be co-located — no data means no
+     * cursor, which means full bootstrap.
+     *
+     * Samples up to 3 stores to avoid a full scan. If any store has records,
+     * returns true (we have cached data worth preserving).
+     */
+    async hasAnyData() {
+        const storeEntries = Array.from(this.stores);
+        // Sample a few stores — don't check all 30+ if the first one has data
+        const samplesToCheck = Math.min(storeEntries.length, 3);
+        for (let i = 0; i < samplesToCheck; i++) {
+            const [, store] = storeEntries[i];
+            try {
+                const count = await store.count();
+                if (count > 0)
+                    return true;
+            }
+            catch {
+                // Store not accessible — treat as empty
+            }
+        }
+        return false;
+    }
+    /**
+     * Get store type distribution for debugging
+     */
+    getStoreTypeDistribution() {
+        let full = 0;
+        let partial = 0;
+        for (const [modelName] of Array.from(this.stores)) {
+            const metadata = this.modelRegistry.getMetadata(modelName);
+            if (metadata?.loadStrategy === LoadStrategy.partial) {
+                partial++;
+            }
+            else {
+                full++;
+            }
+        }
+        return { full, partial };
+    }
+    /**
+     * Get stores by load strategy
+     */
+    getStoresByStrategy(strategy) {
+        const stores = [];
+        for (const [modelName, store] of Array.from(this.stores)) {
+            const metadata = this.modelRegistry.getMetadata(modelName);
+            if (metadata?.loadStrategy === strategy) {
+                stores.push(store);
+            }
+        }
+        return stores;
+    }
+    /**
+     * Get models to load for bootstrapping
+     */
+    getModelsToLoad() {
+        const instant = [];
+        const lazy = [];
+        const partial = [];
+        for (const [modelName] of Array.from(this.stores)) {
+            const metadata = this.modelRegistry.getMetadata(modelName);
+            switch (metadata?.loadStrategy) {
+                case LoadStrategy.instant:
+                    instant.push(modelName);
+                    break;
+                case LoadStrategy.lazy:
+                    lazy.push(modelName);
+                    break;
+                case LoadStrategy.partial:
+                    partial.push(modelName);
+                    break;
+                // Skip explicitlyRequested and local
+            }
+        }
+        return { instant, lazy, partial };
+    }
+    /**
+     * Perform maintenance on all stores
+     */
+    async performMaintenance() {
+        getContext().logger.info('Performing maintenance on all stores');
+        const promises = Array.from(this.stores.values()).map((store) => store.performMaintenance());
+        await Promise.all(promises);
+        getContext().logger.info('Store maintenance completed');
+    }
+    /**
+     * Clear all stores
+     */
+    async clearAllStores() {
+        getContext().logger.warn('Clearing all stores');
+        const promises = Array.from(this.stores.values()).map((store) => store.clear());
+        await Promise.all(promises);
+        getContext().logger.info('All stores cleared');
+    }
+    /**
+     * Mark all stores as closing to prevent new operations
+     * Called before database connection is closed
+     */
+    markAllStoresAsClosing() {
+        getContext().logger.debug('Marking all stores as closing');
+        for (const store of this.stores.values()) {
+            store.markAsClosing();
+        }
+        // SyncActionStore is a standalone store (does NOT extend ObjectStore)
+        // and has no markAsClosing equivalent. The previous `(syncactionStore
+        // as any).markAsClosing?.()` was a silent no-op disguised as a real
+        // call — the optional chain swallowed the missing method. If
+        // closing-state coordination is needed for sync actions, add it
+        // explicitly to SyncActionStore rather than reintroducing the cast.
+        getContext().logger.debug('All stores marked as closing');
+    }
+    /**
+     * Get comprehensive statistics
+     */
+    async getComprehensiveStats() {
+        const storeDetails = [];
+        let totalRecords = 0;
+        let readyCount = 0;
+        for (const [modelName, store] of Array.from(this.stores)) {
+            const metadata = this.modelRegistry.getMetadata(modelName);
+            const storeName = modelName;
+            const ready = await store.checkIsReady();
+            const count = await store.count();
+            if (ready)
+                readyCount++;
+            totalRecords += count;
+            storeDetails.push({
+                modelName,
+                storeName,
+                strategy: metadata.loadStrategy,
+                ready,
+                count,
+            });
+        }
+        return {
+            totalStores: this.stores.size,
+            storeTypes: this.getStoreTypeDistribution(),
+            readiness: {
+                ready: readyCount,
+                notReady: this.stores.size - readyCount,
+            },
+            totalRecords,
+            storeDetails,
+        };
+    }
+}
+import { getContext } from '../context.js';

package/dist/core/ViewRegistry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * ViewRegistry — tracks active QueryViews per typename.
+ *
+ * When the ObjectPool mutates a model, it calls notifyAdded / notifyUpdated /
+ * notifyRemoved on the registry, which fans the event out to every active
+ * QueryView subscribed to that typename.
+ */
+import { type Model } from '../Model.js';
+import type { IncrementalView } from './query-utils.js';
+export declare class ViewRegistry {
+    private views;
+    register(typename: string, view: IncrementalView): void;
+    unregister(typename: string, view: IncrementalView): void;
+    /** Called by ObjectPool after a model is added to the pool. */
+    notifyAdded(typename: string, model: Model): void;
+    /** Called by ObjectPool after a model is updated in the pool. */
+    notifyUpdated(typename: string, model: Model): void;
+    /** Called by ObjectPool after a model is removed from the pool. */
+    notifyRemoved(typename: string, modelId: string): void;
+}

package/dist/core/ViewRegistry.js

@@ -0,0 +1,55 @@
+/**
+ * ViewRegistry — tracks active QueryViews per typename.
+ *
+ * When the ObjectPool mutates a model, it calls notifyAdded / notifyUpdated /
+ * notifyRemoved on the registry, which fans the event out to every active
+ * QueryView subscribed to that typename.
+ */
+import { modelAsRow } from '../Model.js';
+export class ViewRegistry {
+    views = new Map();
+    register(typename, view) {
+        let set = this.views.get(typename);
+        if (!set) {
+            set = new Set();
+            this.views.set(typename, set);
+        }
+        set.add(view);
+    }
+    unregister(typename, view) {
+        const set = this.views.get(typename);
+        if (!set)
+            return;
+        set.delete(view);
+        if (set.size === 0) {
+            this.views.delete(typename);
+        }
+    }
+    /** Called by ObjectPool after a model is added to the pool. */
+    notifyAdded(typename, model) {
+        const set = this.views.get(typename);
+        if (!set)
+            return;
+        for (const view of set) {
+            view.handleAdded(modelAsRow(model));
+        }
+    }
+    /** Called by ObjectPool after a model is updated in the pool. */
+    notifyUpdated(typename, model) {
+        const set = this.views.get(typename);
+        if (!set)
+            return;
+        for (const view of set) {
+            view.handleUpdated(modelAsRow(model));
+        }
+    }
+    /** Called by ObjectPool after a model is removed from the pool. */
+    notifyRemoved(typename, modelId) {
+        const set = this.views.get(typename);
+        if (!set)
+            return;
+        for (const view of set) {
+            view.handleRemoved(modelId);
+        }
+    }
+}

package/dist/core/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @ablo/sync-engine-internal/core — Framework extension
+ *
+ * Only imported by SyncedStore.ts and ApplicationStore.ts —
+ * the 2-3 files that extend or orchestrate the sync engine.
+ * Regular model files and components should NOT import from here.
+ */
+export { BaseSyncedStore, type SyncStatus, type UserContext, type SyncedStoreConfig, type QueryResult, type SmartSyncOptions, type ModelConstructor, type ConcreteModelConstructor, BOOTSTRAP_CONFIG, } from '../BaseSyncedStore.js';
+export { SyncClient, type RehydrationStats } from '../SyncClient.js';
+export { Database, type BootstrapResult, type BootstrapRequirements } from '../Database.js';
+export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { Model } from '../Model.js';
+export { LazyReferenceCollection, type LazyCollectionOptions } from '../LazyReferenceCollection.js';
+export { postQuery, type PostQueryOptions } from '../query/client.js';
+export { probeNetwork, type ProbeResult } from '../sync/NetworkProbe.js';
+export { ConnectionManager, type ConnectionState, type ConnectionEvent, type ConnectionCallbacks, type ConnectionManagerOptions, } from '../sync/ConnectionManager.js';
+export { ModelRegistry, getActiveRegistry, type ExtendedReferenceMetadata, type BackReferenceMetadata } from '../ModelRegistry.js';
+export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
+export { TransactionQueue } from '../transactions/TransactionQueue.js';
+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';
+export { QueryProcessor } from './QueryProcessor.js';
+export { QueryView, type QueryViewOptions } from './QueryView.js';
+export { ViewRegistry } from './ViewRegistry.js';
+export { ObjectStore } from '../stores/ObjectStore.js';
+export { NetworkMonitor } from '../NetworkMonitor.js';
+export { SyncWebSocket, type SyncDelta, type VersionVector, type BootstrapHint, type SyncGroupChangePayload, type BootstrapDataEvent, type PresenceUpdateEvent, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
+export { BootstrapHelper, type BootstrapData, type BootstrapOptions, type BootstrapFetchResult } from '../sync/BootstrapHelper.js';
+export { OfflineTransactionStore, offlineTxStore, Priority } from '../sync/OfflineTransactionStore.js';
+export { PropertyType, LoadStrategy, MutationOperationType } from '../types/index.js';
+export type { PropertyMetadata, ReferenceMetadata, ModelMetadata, SyncAction, DeltaPacket, BootstrapMetadata, DatabaseMetadata, } from '../types/index.js';
+export type { ModelData } from '../BaseSyncedStore.js';

package/dist/core/index.js

@@ -0,0 +1,59 @@
+/**
+ * @ablo/sync-engine-internal/core — Framework extension
+ *
+ * Only imported by SyncedStore.ts and ApplicationStore.ts —
+ * the 2-3 files that extend or orchestrate the sync engine.
+ * Regular model files and components should NOT import from here.
+ */
+// Base store class
+export { BaseSyncedStore, BOOTSTRAP_CONFIG, } from '../BaseSyncedStore.js';
+// Core infrastructure
+export { SyncClient } from '../SyncClient.js';
+export { Database } from '../Database.js';
+export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { Model } from '../Model.js';
+export { LazyReferenceCollection } from '../LazyReferenceCollection.js';
+// Undo runtime — `useUndoScope` hook from `@ablo/sync-engine/react` is
+// the canonical access path. Type counterparts (`Ablo.Mutator.UndoScope`,
+// `Ablo.Mutator.UndoEntry`, `Ablo.Mutator.InverseOp`) live on the main `Ablo`
+// namespace. Direct class access (tests, non-React hosts) imports via
+// the package's internal subpath.
+// Lower-level network primitives — exposed here for the per-app demand
+// loaders. The main barrel hides these so consumer code converges on
+// `ablo.<model>.fetch(...)` for hydration. Loaders that haven't been
+// migrated yet can keep importing from `/core`.
+export { postQuery } from '../query/client.js';
+export { probeNetwork } from '../sync/NetworkProbe.js';
+export { ConnectionManager, } from '../sync/ConnectionManager.js';
+export { ModelRegistry, getActiveRegistry } from '../ModelRegistry.js';
+// FK-cycle / dependency-order helper — used by schema-aware test
+// fixtures and scaffolding tools to compute commit ordering. Lives
+// here because it traverses model relations and isn't part of the
+// consumer-facing API.
+export { computeFKDepthPriority } from '../client/Ablo.js';
+export { TransactionQueue } from '../transactions/TransactionQueue.js';
+// ── Provider-facing DI types (was the deleted `/config` subpath) ──
+// Adapters that the consumer wires into `<AbloProvider>` props
+// (logger, observability, mutation executor, session-error
+// detector, etc.) implement these interfaces. Lives on `/core`
+// because most consumers don't need them; only apps that wrap the
+// provider with custom adapters reach for them.
+export { initSyncEngine, resetSyncEngine, isSyncEngineInitialized } from '../context.js';
+export { noopLogger, noopObservability, noopAnalytics, browserOnlineStatus, defaultSessionErrorDetector, emptyConfig, } from '../SyncEngineContext.js';
+export { SyncSessionError } from '../errors.js';
+export { QueryProcessor } from './QueryProcessor.js';
+export { QueryView } from './QueryView.js';
+export { ViewRegistry } from './ViewRegistry.js';
+export { ObjectStore } from '../stores/ObjectStore.js';
+export { NetworkMonitor } from '../NetworkMonitor.js';
+// Sync layer
+export { SyncWebSocket, } from '../sync/SyncWebSocket.js';
+export { BootstrapHelper } from '../sync/BootstrapHelper.js';
+// Offline transaction queue — moved out of the main barrel in the headless
+// audit cleanup (see docs/headless-audit.md §4.1 Task 23). The class
+// touches indexedDB + crypto.subtle and therefore cannot live on the main
+// headless-clean import path. Framework-level consumers (the few files
+// that orchestrate sync) import from /core explicitly.
+export { OfflineTransactionStore, offlineTxStore, Priority } from '../sync/OfflineTransactionStore.js';
+// Types used by framework-level code
+export { PropertyType, LoadStrategy, MutationOperationType } from '../types/index.js';

package/dist/core/openIDBWithTimeout.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
+ * request can never silently hang the app.
+ *
+ * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
+ * holding an older schema version, the request fires `onblocked` and then
+ * waits forever for that tab to close the DB. Neither `onsuccess` nor
+ * `onerror` fires — the promise wrapping it never settles and every caller
+ * above sits indefinitely.
+ *
+ * This helper converts that into a real error after a bounded wait, which
+ * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
+ * the error skeleton with a retry button. A visible error is strictly better
+ * than a forever-spinner the user can only escape by closing the tab.
+ */
+export declare class IDBOpenTimeoutError extends Error {
+    readonly dbName: string;
+    readonly reason: 'blocked' | 'timeout';
+    constructor(dbName: string, reason: 'blocked' | 'timeout', message: string);
+}
+export interface OpenIDBOptions {
+    /** Called inside `onupgradeneeded` — mirrors `IDBOpenDBRequest.onupgradeneeded`. */
+    onUpgrade?: (request: IDBOpenDBRequest, event: IDBVersionChangeEvent) => void;
+    /** Max milliseconds to wait for the open request to resolve. Default 10_000. */
+    timeoutMs?: number;
+}
+export declare function openIDBWithTimeout(name: string, version: number | undefined, options?: OpenIDBOptions): Promise<IDBDatabase>;

package/dist/core/openIDBWithTimeout.js

@@ -0,0 +1,63 @@
+/**
+ * Wrap `indexedDB.open()` with a timeout + loud `onblocked` surfacing so the
+ * request can never silently hang the app.
+ *
+ * The native `IDBOpenDBRequest` has a nasty failure mode: if another tab is
+ * holding an older schema version, the request fires `onblocked` and then
+ * waits forever for that tab to close the DB. Neither `onsuccess` nor
+ * `onerror` fires — the promise wrapping it never settles and every caller
+ * above sits indefinitely.
+ *
+ * This helper converts that into a real error after a bounded wait, which
+ * flows up through `engine.ready()` → `SyncEngineProvider.handleError()` →
+ * the error skeleton with a retry button. A visible error is strictly better
+ * than a forever-spinner the user can only escape by closing the tab.
+ */
+export class IDBOpenTimeoutError extends Error {
+    dbName;
+    reason;
+    constructor(dbName, reason, message) {
+        super(message);
+        this.dbName = dbName;
+        this.reason = reason;
+        this.name = 'IDBOpenTimeoutError';
+    }
+}
+export function openIDBWithTimeout(name, version, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    return new Promise((resolve, reject) => {
+        const request = version === undefined
+            ? indexedDB.open(name)
+            : indexedDB.open(name, version);
+        let settled = false;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn();
+        };
+        if (options.onUpgrade) {
+            request.onupgradeneeded = (event) => {
+                options.onUpgrade(request, event);
+            };
+        }
+        request.onsuccess = () => settle(() => resolve(request.result));
+        request.onerror = () => settle(() => reject(request.error));
+        // The critical handler: another tab is blocking us. Native API leaves
+        // the request pending indefinitely; we fail fast with a clear error so
+        // the UI can tell the user to close other tabs.
+        request.onblocked = () => {
+            settle(() => reject(new IDBOpenTimeoutError(name, 'blocked', `IndexedDB \"${name}\" open blocked — another tab is holding an ` +
+                `older version. Close other Ablo tabs and reload.`)));
+        };
+        // Catch-all timeout: even without `onblocked`, some browsers in some
+        // storage states hang without firing any event. Bounded wait →
+        // deterministic error.
+        const timer = setTimeout(() => {
+            settle(() => reject(new IDBOpenTimeoutError(name, 'timeout', `IndexedDB \"${name}\" open did not resolve within ${timeoutMs}ms. ` +
+                `Storage may be in a bad state — clearing site data and reloading ` +
+                `usually fixes this.`)));
+        }, timeoutMs);
+    });
+}

package/dist/core/query-utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * query-utils — Pure query helpers shared between QueryView (MobX) and
+ * AgentQueryView (headless). One source of truth for sort, filter, and
+ * binary insertion logic.
+ *
+ * No MobX, no ObjectPool, no Model — just arrays and values.
+ */
+/**
+ * The incremental-update contract that both QueryView and
+ * AgentQueryView satisfy. Their respective registries (ViewRegistry,
+ * AgentViewRegistry) store views as this base type so they can
+ * dispatch to many views with different `T` parameters from one Set
+ * — `View<T>` is invariant in T, so without this shared base the
+ * registries would have to widen via `unknown as View<Record<...>>`
+ * at every register/unregister/notify call.
+ */
+export interface IncrementalView {
+    handleAdded(entity: Record<string, unknown>): void;
+    handleUpdated(entity: Record<string, unknown>): void;
+    handleRemoved(id: string): void;
+}
+/** Compare two values for sorting, null-safe. Returns -1 | 0 | 1. */
+export declare function compareValues(a: unknown, b: unknown, dir: 1 | -1): number;
+/**
+ * Binary search for the correct insertion index in a sorted array.
+ * Returns the index at which `item` should be inserted.
+ */
+export declare function binaryInsertionIndex<T>(arr: ArrayLike<T>, item: T, sortKey: string, dir: 1 | -1): number;
+/**
+ * Check whether an entity matches a declarative `where` clause.
+ * Every key in `where` must exactly match the entity's value.
+ */
+export declare function matchesWhere<T extends Record<string, unknown>>(entity: T, where: Partial<T>): boolean;
+/**
+ * Find the index of an entity by id in an array. Returns -1 if not found.
+ */
+export declare function findIndexById<T extends Record<string, unknown>>(arr: ArrayLike<T>, id: string): number;