@abloatai/ablo 0.26.0 → 0.28.0

package/dist/core/DatabaseManager.js

@@ -1,11 +1,9 @@
 /**
- * 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.
+ * 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 { getContext } from '../context.js';
 import { openIDBWithTimeout, deleteIDBWithTimeout, IDBOpenTimeoutError, } from './openIDBWithTimeout.js';
@@ -90,7 +88,7 @@ export class DatabaseManager {
         else if (existingInfo) {
             schemaVersion = existingInfo.schemaVersion || 1;
         }
-        // DEBUG: Log all existing databases for this user to detect duplicates
+        // Record the existing databases for this user so duplicates can be detected.
         const allUserDatabases = await this.getDatabasesForUser(userId);
         const allIndexedDBs = (await indexedDB.databases?.()) || [];
         const abloDatabases = allIndexedDBs.filter((db) => db.name?.startsWith('ablo_'));
@@ -117,7 +115,7 @@ export class DatabaseManager {
     generateDatabaseName(userId, workspaceId, userVersion = 1) {
         // Combine userId, workspaceId, and userVersion for unique database
         const combined = `${userId}:${workspaceId}:${userVersion}`;
-        // Generate hash similar to Linear's approach
+        // Hash the combined key into a compact, deterministic identifier.
         let hash = 0;
         for (let i = 0; i < combined.length; i++) {
             hash = (hash << 5) - hash + combined.charCodeAt(i);
@@ -185,13 +183,12 @@ export class DatabaseManager {
                 onUpgrade: (request, event) => {
                     const db = request.result;
                     const tx = event.target.transaction;
-                    // Per jakearchibald/idb's "Transaction Lifetime Management":
-                    // only IDB-request awaits keep an upgrade transaction alive; any
-                    // non-IDB await (fetch, timer, etc.) commits it prematurely and
-                    // later ops throw `TransactionInactiveError`. StoreManager.createStores
-                    // (src/core/StoreManager.ts:93) is only synchronous createObjectStore
-                    // / createIndex calls wrapped in an `async` keyword, so firing it
-                    // without awaiting is safe and matches the VCS-slot semantics.
+                    // 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) => {
@@ -238,9 +235,8 @@ export class DatabaseManager {
                     updatedAt: data.updatedAt ? new Date(data.updatedAt) : new Date(),
                     schemaHash: data.schemaHash,
                     syncGroups: data.syncGroups,
-                    // NOTE: old persisted records may still carry a `versions` key
-                    // (the removed per-entity version vector) — tolerated by simply
-                    // not picking it here.
+                    // 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);
             };

package/dist/core/QueryProcessor.d.ts

@@ -1,15 +1,13 @@
 /**
- * QueryProcessor - Centralized query processing for the sync engine
- *
- * Responsibilities:
- * - Complex filtering, sorting, and pagination logic
- * - Query optimization and caching strategies
- * - Predicate evaluation and result processing
- *
- * This extracts query processing logic from SyncedStore for proper separation of concerns
+ * Runs in-memory queries over a set of models — filtering by predicate,
+ * sorting, paginating, and caching the results. A caller hands
+ * {@link QueryProcessor} the candidate models and the query options, and it
+ * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
+ * plain queries, and a structural-identity cache for predicate queries, whose
+ * closures cannot be turned into a stable string key.
  */
 import type { Model } from '../Model.js';
-import type { ModelScope } from '../ObjectPool.js';
+import type { ModelScope } from '../InstanceCache.js';
 export interface QueryOptions<T extends Model> {
     predicate?: (model: T) => boolean;
     /** Stable key to distinguish different predicates for the same model type.

package/dist/core/QueryProcessor.js

@@ -1,20 +1,17 @@
 /**
- * QueryProcessor - Centralized query processing for the sync engine
- *
- * Responsibilities:
- * - Complex filtering, sorting, and pagination logic
- * - Query optimization and caching strategies
- * - Predicate evaluation and result processing
- *
- * This extracts query processing logic from SyncedStore for proper separation of concerns
+ * Runs in-memory queries over a set of models — filtering by predicate,
+ * sorting, paginating, and caching the results. A caller hands
+ * {@link QueryProcessor} the candidate models and the query options, and it
+ * returns a {@link QueryResult}. It keeps two caches: a string-keyed cache for
+ * plain queries, and a structural-identity cache for predicate queries, whose
+ * closures cannot be turned into a stable string key.
  */
 /**
- * Optimized in-memory cache implementation
- *
- * 2025 Best Practice: O(1) invalidation by model type instead of O(n) regex matching
- * - Maintains a reverse index from model type to cache keys
- * - Invalidation by model type is O(k) where k = keys for that model type
- * - No regex compilation or full cache iteration needed
+ * The default in-memory cache. It keeps a reverse index from model type to the
+ * cache keys for that type, so invalidating one model type costs work
+ * proportional to that type's keys rather than a scan of the whole cache. A
+ * regex fallback still covers the rare pattern that is not a plain model-type
+ * match.
  */
 class BasicQueryCache {
     cache = new Map();
@@ -87,21 +84,19 @@ class BasicQueryCache {
      * Cache key format: "operation:ModelType:options"
      */
     extractModelType(key) {
-        // `?? null` is equivalent to the old length check: a missing second
-        // segment reads as undefined, and split never yields undefined otherwise.
+        // A missing second segment reads as undefined, so `?? null` yields null.
         return key.split(':')[1] ?? null;
     }
 }
 export class QueryProcessor {
     cache;
     enableCache;
-    // Stable-reference cache for predicate queries.
-    // String-based cache keys can't represent closures, so we use a separate
-    // identity-based cache that compares result model IDs. This follows the same
-    // principle as MobX's comparer.structural — return the previous reference
-    // when the structural content hasn't changed.
-    // Key: deterministic portion of query (modelName + serializable options)
-    // Value: previous result + its ID fingerprint
+    // Stable-reference cache for predicate queries. A string cache key cannot
+    // capture a closure, so predicate queries use a separate identity-based
+    // cache keyed on the deterministic part of the query (model name plus
+    // serializable options). Each entry stores the previous result and a
+    // fingerprint of its model ids; when the ids are unchanged, the processor
+    // returns the previous array reference so observers do not re-render.
     predicateResultCache = new Map();
     constructor(config = {}) {
         this.enableCache = config.enableCache ?? true;
@@ -137,10 +132,9 @@ export class QueryProcessor {
             hasMore: offset + limit < total,
             fromCache: false,
         };
-        // For predicate queries: use structural identity comparison
-        // Return the previous array reference if model IDs haven't changed.
-        // This is the query-layer equivalent of MobX's comparer.structural —
-        // observers won't re-render when the result is structurally identical.
+        // For predicate queries: compare by structural identity. Return the
+        // previous array reference when the model ids are unchanged, so observers
+        // don't re-render on a structurally identical result.
         if (options.predicate && this.enableCache) {
             const ids = data.map((m) => m.id).join(',');
             const cached = this.predicateResultCache.get(cacheKey);
@@ -151,7 +145,7 @@ export class QueryProcessor {
             // New result — store for future comparison
             this.predicateResultCache.set(cacheKey, { ids, result });
         }
-        // For non-predicate queries: use string-based cache as before
+        // For non-predicate queries: use the string-based cache.
         if (!options.predicate && this.enableCache) {
             this.cache.set(cacheKey, result);
         }

package/dist/core/QueryView.d.ts

@@ -12,13 +12,13 @@ import { type IObservableArray } from 'mobx';
 import { type Model } from '../Model.js';
 import { ModelScope } from '../types/index.js';
 import type { ViewRegistry } from './ViewRegistry.js';
-import type { IncrementalView } from './query-utils.js';
+import type { IncrementalView } from './queryUtils.js';
 /**
- * The slice of `ObjectPool` a QueryView reads — a minimal structural
- * interface (LogFoldContext-style) instead of the concrete class, so this
- * module never imports `../ObjectPool.js` back (ObjectPool imports QueryView
- * at runtime for `createView()`; the reverse edge was the last core-layer
- * import cycle). `ObjectPool` satisfies it structurally.
+ * The slice of the object pool that a {@link QueryView} reads. It is a minimal
+ * structural interface rather than the concrete pool class, which lets a query
+ * view avoid importing the pool and so breaks what would otherwise be an import
+ * cycle — the pool imports {@link QueryView} to construct one. The concrete
+ * pool satisfies this interface structurally.
  */
 export interface QueryViewPool {
     hasForeignKeyIndex(typename: string, fieldName: string): boolean;
@@ -32,8 +32,8 @@ export interface QueryViewOptions<T> {
     order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
-    /** Lifecycle filter — `live` (default), `archived`, or `all`. Named `state`
-     *  (GitHub's open/closed/all precedent) so it doesn't collide with the
+    /** Lifecycle filter — `live` (the default), `archived`, or `all`. It is
+     *  named `state` rather than `scope` so it does not collide with the
      *  sync-group `scope`. */
     state?: ModelScope;
 }

package/dist/core/QueryView.js

@@ -11,7 +11,7 @@
 import { observable, runInAction } from 'mobx';
 import { modelAsRow } from '../Model.js';
 import { ModelScope } from '../types/index.js';
-import { compareValues, binaryInsertionIndex, findIndexById, } from './query-utils.js';
+import { compareValues, binaryInsertionIndex, findIndexById, } from './queryUtils.js';
 // ---------------------------------------------------------------------------
 // QueryView
 // ---------------------------------------------------------------------------
@@ -168,7 +168,7 @@ export class QueryView {
     // -----------------------------------------------------------------------
     /** Check whether an entity passes both `where` and `filter`. */
     matchesFilter(entity) {
-        // Note: scope is tracked per-entry in the ObjectPool, not on the model.
+        // Note: scope is tracked per-entry in the InstanceCache, not on the model.
         // The initial scan handles scope via getByTypeName(typename, scope).
         // Incremental notifications from the pool are scope-appropriate since
         // add/upsert/remove reflect the pool's authoritative scope tracking.

package/dist/core/StoreManager.d.ts

@@ -1,9 +1,10 @@
 /**
- * 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.
+ * Manages the {@link ObjectStore} instances the sync engine keeps in the
+ * browser — one per registered model — alongside the single
+ * {@link SyncActionStore} for pending changes. It creates each store from the
+ * model's metadata, tracks readiness, and provisions the underlying IndexedDB
+ * object stores. A model's load strategy (instant, lazy, or partial) decides
+ * how and when its data is loaded.
  */
 import { ModelRegistry } from '../ModelRegistry.js';
 import { ObjectStore } from '../stores/ObjectStore.js';
@@ -20,6 +21,8 @@ import { LoadStrategy } from '../types/index.js';
  */
 export declare class StoreManager {
     private stores;
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    private transactionStore;
     private syncactionStore;
     private db;
     private isInitialized;
@@ -63,15 +66,12 @@ export declare class StoreManager {
         totalStores: number;
     }>;
     /**
-     * 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).
+     * Reports whether any data store holds at least one record. This is a
+     * cache-validity check: if the stores are empty, the sync cursor
+     * (`lastSyncId`) is meaningless no matter what the metadata says, because the
+     * cursor and the data must travel together — no data means no cursor, which
+     * forces a full bootstrap. To stay cheap it samples up to three stores rather
+     * than scanning them all, and returns true as soon as one has records.
      */
     hasAnyData(): Promise<boolean>;
     /**

package/dist/core/StoreManager.js

@@ -1,9 +1,10 @@
 /**
- * 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.
+ * Manages the {@link ObjectStore} instances the sync engine keeps in the
+ * browser — one per registered model — alongside the single
+ * {@link SyncActionStore} for pending changes. It creates each store from the
+ * model's metadata, tracks readiness, and provisions the underlying IndexedDB
+ * object stores. A model's load strategy (instant, lazy, or partial) decides
+ * how and when its data is loaded.
  */
 import { ModelRegistry } from '../ModelRegistry.js';
 import { ObjectStore } from '../stores/ObjectStore.js';
@@ -21,6 +22,8 @@ import { AbloValidationError } from '../errors.js';
  */
 export class StoreManager {
     stores = new Map();
+    /** Strict-durability wrapper for the client write journal and commit outbox. */
+    transactionStore = null;
     syncactionStore = null;
     db = null;
     isInitialized = false;
@@ -45,6 +48,12 @@ export class StoreManager {
         for (const modelName of allModels) {
             await this.createStoreForModel(modelName);
         }
+        // Special stores are created during the IDB upgrade, but unlike model
+        // stores they have no registry metadata and therefore need an explicit
+        // runtime wrapper. Outbox acknowledgement must mean disk-backed, so this
+        // store opts into strict durability rather than the cache stores' relaxed
+        // mode.
+        this.transactionStore = new ObjectStore(this.db, '__transactions', '__transactions', { loadStrategy: LoadStrategy.instant }, 'strict');
         // Initialize SyncactionStore
         this.syncactionStore = new SyncActionStore(this.db);
         await this.syncactionStore.initialize();
@@ -70,7 +79,7 @@ export class StoreManager {
         }
         // Use model name directly as store name
         const storeName = modelName;
-        // Create ObjectStore (MVP: simplified - use single store type for all strategies)
+        // Create the ObjectStore. One store type currently serves every load strategy.
         const store = new ObjectStore(this.db, modelName, storeName, metadata);
         this.stores.set(modelName, store);
     }
@@ -122,7 +131,7 @@ export class StoreManager {
         }
         // Create __meta table for model persistence state and database metadata
         if (!db.objectStoreNames.contains('__meta')) {
-            const metaStore = db.createObjectStore('__meta');
+            db.createObjectStore('__meta');
             getContext().logger.debug('Created __meta table');
         }
         // Create __transactions table for unsent transactions
@@ -141,6 +150,9 @@ export class StoreManager {
      * Get ObjectStore for a model
      */
     getStore(modelName) {
+        if (modelName === '__transactions') {
+            return this.transactionStore ?? undefined;
+        }
         return this.stores.get(modelName);
     }
     /**
@@ -184,15 +196,12 @@ export class StoreManager {
         };
     }
     /**
-     * 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).
+     * Reports whether any data store holds at least one record. This is a
+     * cache-validity check: if the stores are empty, the sync cursor
+     * (`lastSyncId`) is meaningless no matter what the metadata says, because the
+     * cursor and the data must travel together — no data means no cursor, which
+     * forces a full bootstrap. To stay cheap it samples up to three stores rather
+     * than scanning them all, and returns true as soon as one has records.
      */
     async hasAnyData() {
         const storeEntries = Array.from(this.stores);
@@ -281,8 +290,8 @@ export class StoreManager {
      * Clear all stores
      */
     async clearAllStores() {
-        // Lifecycle chatter (logout / identity switch / reset) — NOT a warning.
-        // `debug` so it's silent under the default `warn` threshold.
+        // Lifecycle chatter (logout / identity switch / reset), not a warning.
+        // Logged at `debug` so it stays silent under the default `warn` threshold.
         getContext().logger.debug('Clearing all stores');
         const promises = Array.from(this.stores.values()).map((store) => store.clear());
         await Promise.all(promises);
@@ -297,12 +306,12 @@ export class StoreManager {
         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.
+        this.transactionStore?.markAsClosing();
+        // SyncActionStore is a standalone store that does not extend ObjectStore
+        // and has no markAsClosing equivalent, so it is intentionally skipped here.
+        // If closing-state coordination is ever needed for sync actions, add it
+        // explicitly to SyncActionStore rather than casting to reach a method that
+        // may not exist.
         getContext().logger.debug('All stores marked as closing');
     }
     /**

package/dist/core/ViewRegistry.d.ts

@@ -1,20 +1,20 @@
 /**
  * ViewRegistry — tracks active QueryViews per typename.
  *
- * When the ObjectPool mutates a model, it calls notifyAdded / notifyUpdated /
+ * When the InstanceCache 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';
+import type { IncrementalView } from './queryUtils.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. */
+    /** Called by InstanceCache 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. */
+    /** Called by InstanceCache 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. */
+    /** Called by InstanceCache after a model is removed from the pool. */
     notifyRemoved(typename: string, modelId: string): void;
 }

package/dist/core/ViewRegistry.js

@@ -1,7 +1,7 @@
 /**
  * ViewRegistry — tracks active QueryViews per typename.
  *
- * When the ObjectPool mutates a model, it calls notifyAdded / notifyUpdated /
+ * When the InstanceCache mutates a model, it calls notifyAdded / notifyUpdated /
  * notifyRemoved on the registry, which fans the event out to every active
  * QueryView subscribed to that typename.
  */
@@ -25,7 +25,7 @@ export class ViewRegistry {
             this.views.delete(typename);
         }
     }
-    /** Called by ObjectPool after a model is added to the pool. */
+    /** Called by InstanceCache after a model is added to the pool. */
     notifyAdded(typename, model) {
         const set = this.views.get(typename);
         if (!set)
@@ -34,7 +34,7 @@ export class ViewRegistry {
             view.handleAdded(modelAsRow(model));
         }
     }
-    /** Called by ObjectPool after a model is updated in the pool. */
+    /** Called by InstanceCache after a model is updated in the pool. */
     notifyUpdated(typename, model) {
         const set = this.views.get(typename);
         if (!set)
@@ -43,7 +43,7 @@ export class ViewRegistry {
             view.handleUpdated(modelAsRow(model));
         }
     }
-    /** Called by ObjectPool after a model is removed from the pool. */
+    /** Called by InstanceCache after a model is removed from the pool. */
     notifyRemoved(typename, modelId) {
         const set = this.views.get(typename);
         if (!set)

package/dist/core/index.d.ts

@@ -1,20 +1,22 @@
 /**
- * @abloatai/ablo/core — Framework extension
+ * The framework-extension entry point of this package. Import from here only
+ * when you are building on top of the sync engine — wiring your own store and
+ * provider stack, writing a sync adapter, or driving a test harness. Everyday
+ * application code should use the `Ablo({ schema })` client from the package
+ * root instead; the primitives exported here are lower-level building blocks.
  *
- * Only imported by the handful of files that extend or orchestrate the
- * sync engine (the app-shell store/provider stack, sync adapters, demo
- * harnesses). Regular model files and components should NOT import from
- * here — the consumer surface is `Ablo({ schema })` on the root.
- *
- * TRIMMED to what framework-level consumers actually import (verified by
- * a monorepo-wide import scan). Everything else the engine defines stays
- * module-private: if a new framework concern genuinely needs another
- * primitive, add the export deliberately — don't re-widen the barrel.
+ * The surface is deliberately narrow: it exposes only the types and classes an
+ * extension actually needs. Anything the engine does not export here is
+ * internal and may change.
  */
 export { BaseSyncedStore, type ModelConstructor, type ConcreteModelConstructor, } from '../BaseSyncedStore.js';
 export { SyncClient } from '../SyncClient.js';
 export { Database } from '../Database.js';
-export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { InstanceCache, ModelScope } from '../InstanceCache.js';
+/** @deprecated `ObjectPool` was renamed to {@link InstanceCache} — the class is an
+ *  identity-map cache of live model instances, not a reuse pool. This alias keeps existing
+ *  imports working and will be removed in a future major version. */
+export { InstanceCache as ObjectPool } from '../InstanceCache.js';
 export { Model } from '../Model.js';
 export { LazyReferenceCollection, type LazyCollectionOptions, } from '../LazyReferenceCollection.js';
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
@@ -22,7 +24,10 @@ export { postQuery, type PostQueryOptions } from '../query/client.js';
 export { computeFKDepthPriority, type InternalAbloOptions } from '../client/Ablo.js';
 export type { SyncLogger, SyncObservabilityProvider, MutationExecutor, SessionErrorDetector, OnlineStatusProvider, CommitResult, MutationOperation, } from '../interfaces/index.js';
 export { SyncWebSocket, type SyncDelta, type SyncWebSocketOptions, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper } from '../sync/BootstrapHelper.js';
+export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
+/** @deprecated `BootstrapHelper` was renamed to {@link BootstrapFetcher}. This alias keeps
+ *  existing imports working and will be removed in a future major version. */
+export { BootstrapFetcher as BootstrapHelper } from '../sync/BootstrapFetcher.js';
 export { createClaimStream, type AttachableClaimStream, type ClaimStreamConfig, } from '../sync/createClaimStream.js';
 export { awaitClaimGrant, type GrantTransport, } from '../sync/awaitClaimGrant.js';
 export { LoadStrategy } from '../types/index.js';

package/dist/core/index.js

@@ -1,42 +1,48 @@
 /**
- * @abloatai/ablo/core — Framework extension
+ * The framework-extension entry point of this package. Import from here only
+ * when you are building on top of the sync engine — wiring your own store and
+ * provider stack, writing a sync adapter, or driving a test harness. Everyday
+ * application code should use the `Ablo({ schema })` client from the package
+ * root instead; the primitives exported here are lower-level building blocks.
  *
- * Only imported by the handful of files that extend or orchestrate the
- * sync engine (the app-shell store/provider stack, sync adapters, demo
- * harnesses). Regular model files and components should NOT import from
- * here — the consumer surface is `Ablo({ schema })` on the root.
- *
- * TRIMMED to what framework-level consumers actually import (verified by
- * a monorepo-wide import scan). Everything else the engine defines stays
- * module-private: if a new framework concern genuinely needs another
- * primitive, add the export deliberately — don't re-widen the barrel.
+ * The surface is deliberately narrow: it exposes only the types and classes an
+ * extension actually needs. Anything the engine does not export here is
+ * internal and may change.
  */
-// Base store class + the constructor shapes subclasses reference
+// The base store class, plus the constructor shapes that subclasses reference.
 export { BaseSyncedStore, } from '../BaseSyncedStore.js';
 // Core infrastructure classes
 export { SyncClient } from '../SyncClient.js';
 export { Database } from '../Database.js';
-export { ObjectPool, ModelScope } from '../ObjectPool.js';
+export { InstanceCache, ModelScope } from '../InstanceCache.js';
+/** @deprecated `ObjectPool` was renamed to {@link InstanceCache} — the class is an
+ *  identity-map cache of live model instances, not a reuse pool. This alias keeps existing
+ *  imports working and will be removed in a future major version. */
+export { InstanceCache as ObjectPool } from '../InstanceCache.js';
 export { Model } from '../Model.js';
 export { LazyReferenceCollection, } from '../LazyReferenceCollection.js';
 export { ModelRegistry, getActiveRegistry, } from '../ModelRegistry.js';
-// Lower-level network read — for per-app demand loaders that haven't
-// migrated to `ablo.<model>.list(...)` yet.
+// A lower-level network read primitive. Prefer `ablo.<model>.list(...)` for
+// ordinary reads; reach for this only when writing a custom on-demand loader.
 export { postQuery } from '../query/client.js';
-// FK-cycle / dependency-order helper — used by schema-aware test
-// fixtures and scaffolding tools to compute commit ordering.
+// Computes a dependency-safe ordering for a set of models by walking their
+// foreign-key relationships, so writes commit parents before children. Used by
+// schema-aware test fixtures and scaffolding tools.
 export { computeFKDepthPriority } from '../client/Ablo.js';
-// Sync layer — the wire socket + delta shape, for sync adapters and the
-// multi-agent demo harnesses.
+// The sync layer: the WebSocket wrapper and the delta shape it carries. Needed
+// when writing a sync adapter or a multi-participant test harness.
 export { SyncWebSocket, } from '../sync/SyncWebSocket.js';
-export { BootstrapHelper } from '../sync/BootstrapHelper.js';
-// Claim coordination primitives (the lower-level pieces behind the
-// consumer-facing `ablo.<model>.claim`). The stream factory builds the
-// announce/await machinery on a SyncWebSocket; `awaitClaimGrant` is the
-// fair-queue grant coordinator. Exposed on /core for framework-level
-// orchestration and e2e harnesses — NOT on the consumer `.` root.
+export { BootstrapFetcher } from '../sync/BootstrapFetcher.js';
+/** @deprecated `BootstrapHelper` was renamed to {@link BootstrapFetcher}. This alias keeps
+ *  existing imports working and will be removed in a future major version. */
+export { BootstrapFetcher as BootstrapHelper } from '../sync/BootstrapFetcher.js';
+// The lower-level claim-coordination primitives behind the `ablo.<model>.claim`
+// API. `createClaimStream` builds the announce-and-await machinery on top of a
+// `SyncWebSocket`; `awaitClaimGrant` coordinates fair, first-in-first-out
+// grants. These are for extension code and test harnesses; ordinary
+// application code should use `ablo.<model>.claim`.
 export { createClaimStream, } from '../sync/createClaimStream.js';
 export { awaitClaimGrant, } from '../sync/awaitClaimGrant.js';
-// Schema/model load strategy enum — referenced by model registration in
-// framework code.
+// An enum naming the strategies for loading a model's data. Referenced when
+// registering models in extension code.
 export { LoadStrategy } from '../types/index.js';