@abloatai/ablo 0.25.0 → 0.27.0

package/dist/{ObjectPool.js → InstanceCache.js}

@@ -1,21 +1,26 @@
 /**
- * ObjectPool - In-memory model cache with deduplication
- *
- * Pure memory management without database or registry dependencies.
- * Uses static ModelRegistry for model class lookup only.
+ * InstanceCache is the in-memory cache of live model instances, keyed by id and
+ * deduplicated so each entity has a single instance. It maintains type and
+ * foreign-key indexes for fast lookups, evicts entries under a size cap, and
+ * notifies subscribers and query views as models are added, updated, or
+ * removed. It holds a {@link ModelRegistry} to map between model names and
+ * constructor classes, but performs no persistence of its own.
  */
 import { makeObservable, observable, action, computed, runInAction } from 'mobx';
+import { Model } from './Model.js';
+import { ModelRegistry } from './ModelRegistry.js';
 import { getContext } from './context.js';
 import { AbloValidationError } from './errors.js';
 import { ModelScope } from './types/index.js';
 import { ViewRegistry } from './core/ViewRegistry.js';
 import { QueryView } from './core/QueryView.js';
-// Re-export so existing `import { ModelScope } from './ObjectPool.js'` still resolves
+// Re-exported so `import { ModelScope } from './InstanceCache.js'` resolves
 export { ModelScope };
 /**
- * ObjectPool - Pure in-memory model cache with deduplication
+ * The in-memory cache of model instances, keyed by id and deduplicated so each
+ * entity resolves to a single instance.
  */
-export class ObjectPool {
+export class InstanceCache {
     // Single source of truth for all models (observable for reactivity)
     entries = observable.map();
     typeIndex = observable.map();
@@ -26,9 +31,10 @@ export class ObjectPool {
     // Deduplication tracking
     recentAdditions = new Map(); // "modelType:modelId" -> timestamp
     deltaHistory = new Map();
-    // No intermediate cache layer — getByType() reads typeIndex + entries directly.
-    // This follows Linear's sync engine pattern: observable data structures ARE the
-    // reactivity source. No computed getters with conditional cache invalidation.
+    // No intermediate cache layer — getByType() reads typeIndex and entries
+    // directly. Both are observable, so the data structures are themselves the
+    // reactivity source; there are no computed getters with conditional cache
+    // invalidation to get wrong.
     // Foreign key indexes: Map<"ModelType:fieldName", Map<fieldValue, ObservableSet<modelId>>>
     // Enables O(1) lookups like "all SlideLayer models where slideId = X"
     // instead of scanning all models of a type and filtering.
@@ -62,10 +68,11 @@ export class ObjectPool {
                 code: 'pool_subscribe_unregistered',
             });
         }
-        if (!this.subscriptions.has(modelName)) {
-            this.subscriptions.set(modelName, new Set());
+        let subs = this.subscriptions.get(modelName);
+        if (!subs) {
+            subs = new Set();
+            this.subscriptions.set(modelName, subs);
         }
-        const subs = this.subscriptions.get(modelName);
         const erased = callback;
         subs.add(erased);
         return () => subs.delete(erased);
@@ -99,15 +106,14 @@ export class ObjectPool {
             gcInterval: config.gcInterval ?? 60000, // 1 minute
             useWeakRefs: config.useWeakRefs ?? true,
         };
-        // 🔧 PROPER FIX: Store model registry reference
+        // Store the model registry reference
         if (!modelRegistry) {
-            throw new AbloValidationError('ObjectPool requires ModelRegistry for production-safe model name lookup', { code: 'pool_registry_missing' });
+            throw new AbloValidationError('InstanceCache requires ModelRegistry for production-safe model name lookup', { code: 'pool_registry_missing' });
         }
         this.registry = modelRegistry;
-        // 🔧 PRODUCTION FIX: Defer type index initialization until first use
-        // This allows models to be registered after ObjectPool creation
-        // Type indexes will be initialized on first getByType call
-        // Linear-style: no computed cache layer. entries + typeIndex are both observable.
+        // Type indexes are initialized on first use, so models can be registered
+        // after the InstanceCache is created; the first getByType call builds them.
+        // No computed cache layer: entries and typeIndex are both observable, and
         // getByType() reads them directly, so MobX always tracks the dependency.
         makeObservable(this, {
             add: action,
@@ -123,24 +129,11 @@ export class ObjectPool {
         });
         this.startGC();
     }
-    /**
-     * 🔧 PRODUCTION FIX: Initialize type indexes for all registered models
-     * This prevents the "No type index found" error in production where constructor
-     * references are lost due to minification.
-     */
-    initializeTypeIndexes() {
-        const names = this.registry.getRegisteredModelNames();
-        for (const modelName of names) {
-            if (!this.typeIndex.has(modelName)) {
-                this.typeIndex.set(modelName, observable.set());
-            }
-        }
-    }
-    // No computed getters — getByType() reads typeIndex + entries directly.
-    // This eliminates the conditional dependency bug where MobX lost tracking
-    // because _cacheInvalid (non-observable) gated whether entries was read.
-    // _rebuildCaches and _invalidateCache removed — no cache layer to manage.
-    // typeIndex + entries are observable and read directly by getByType().
+    // No computed getters — getByType() reads typeIndex and entries directly.
+    // Both are observable, so MobX always tracks the dependency; there is no
+    // conditional cache path that could silently drop a dependency.
+    // There is no cache layer to manage: typeIndex and entries are observable
+    // and read directly by getByType().
     resolveModel(entry, id) {
         if (entry.model)
             return entry.model;
@@ -155,6 +148,10 @@ export class ObjectPool {
         }
         return undefined;
     }
+    // The type parameter appears only in the return position on purpose: this is
+    // an ergonomic typed accessor (like Map<K, V>.get) that centralizes what would
+    // otherwise be an `as T` cast at every call site.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
     get(id) {
         const entry = this.entries.get(id);
         if (!entry) {
@@ -203,7 +200,7 @@ export class ObjectPool {
         }
         // Check if model already exists to prevent duplicates
         const existingEntry = this.entries.get(id);
-        if (existingEntry && existingEntry.model && !existingEntry.model.disposed) {
+        if (existingEntry?.model && !existingEntry.model.disposed) {
             // Model already exists and is valid, update its scope if needed
             if (existingEntry.scope !== scope) {
                 runInAction(() => {
@@ -234,12 +231,12 @@ export class ObjectPool {
                     (history.lastAction === 'U' || history.lastAction === 'D')) {
                     // Internal delta-ordering anomaly that reconciles on the next
                     // catch-up — forensic, not consumer-actionable → debug.
-                    getContext().logger.debug(`ObjectPool.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
+                    getContext().logger.debug(`InstanceCache.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
                 }
             }
             // Update delta history
             this.deltaHistory.set(addKey, {
-                lastAction: deltaInfo.action || 'U',
+                lastAction: deltaInfo.action ?? 'U',
                 lastSyncId: deltaInfo.syncId,
                 timestamp: Date.now(),
             });
@@ -320,7 +317,7 @@ export class ObjectPool {
             }
             // Skip if model already exists and is valid
             const existingEntry = this.entries.get(id);
-            if (existingEntry && existingEntry.model && !existingEntry.model.disposed) {
+            if (existingEntry?.model && !existingEntry.model.disposed) {
                 if (existingEntry.scope !== scope) {
                     this.entries.set(id, { ...existingEntry, scope });
                     this.accessTimes.set(id, now);
@@ -348,7 +345,7 @@ export class ObjectPool {
             // loader (`ensureDeckLayers`, `prefetchSlideLayers`, bootstrap
             // hydration) was in the pool but invisible to `hasMany` lookups
             // — `slide.layers` returned `[]` until the user clicked a layer
-            // and SOMETHING else ran a non-batch `add` that happened to
+            // and something else ran a non-batch `add` that happened to
             // populate the FK index as a side effect. The UX symptom was
             // "slides show empty until you click on one." Adding this one
             // line closes the gap.
@@ -421,8 +418,8 @@ export class ObjectPool {
             const entry = this.entries.get(id);
             if (!entry)
                 continue;
-            const modelName = entry.model?.getModelName() || entry.weakRef?.deref()?.getModelName();
-            // FK/type cleanup must run BEFORE entries.delete — see `remove()`
+            const modelName = entry.model?.getModelName() ?? entry.weakRef?.deref()?.getModelName();
+            // FK/type cleanup must run before entries.delete — see `remove()`
             // for the full explanation. Same bug, same fix.
             this.removeFromTypeIndex(id, modelName);
             this.entries.delete(id);
@@ -430,8 +427,10 @@ export class ObjectPool {
             if (modelName) {
                 this.viewRegistry.notifyRemoved(modelName, id);
             }
-            const model = entry.model || entry.weakRef?.deref();
-            model?.dispose?.();
+            const model = entry.model ?? entry.weakRef?.deref();
+            // A non-Model object can reach the pool (see `clear`); only dispose a real one.
+            if (typeof model?.dispose === 'function')
+                model.dispose();
             const addKey = modelName ? `${modelName}:${id}` : id;
             this.recentAdditions.delete(addKey);
             this.deltaHistory.delete(addKey);
@@ -455,7 +454,7 @@ export class ObjectPool {
         const entry = this.entries.get(id);
         if (!entry)
             return false;
-        const modelName = entry.model?.getModelName() || entry.weakRef?.deref()?.getModelName();
+        const modelName = entry.model?.getModelName() ?? entry.weakRef?.deref()?.getModelName();
         // Order matters here: `removeFromTypeIndex` → `removeFromForeignKeyIndex`
         // reads the FK field values off the model via `this.entries.get(id)`.
         // If we `this.entries.delete(id)` first, the model is gone and the
@@ -463,7 +462,7 @@ export class ObjectPool {
         // That causes `getByForeignKey(..., parentId)` to report
         // `matched > returned` (dropped-no-entry) and, on the UI, keeps the
         // stale layer visible until the next reload rebuilds the index
-        // from fresh data. Do the FK/type cleanup FIRST, then delete the
+        // from fresh data. Do the FK/type cleanup first, then delete the
         // entry.
         runInAction(() => {
             this.removeFromTypeIndex(id, modelName);
@@ -474,8 +473,10 @@ export class ObjectPool {
         if (modelName) {
             this.viewRegistry.notifyRemoved(modelName, id);
         }
-        const model = entry.model || entry.weakRef?.deref();
-        model?.dispose?.();
+        const model = entry.model ?? entry.weakRef?.deref();
+        // A non-Model object can reach the pool (see `clear`); only dispose a real one.
+        if (typeof model?.dispose === 'function')
+            model.dispose();
         // Clean tracking
         const addKey = modelName ? `${modelName}:${id}` : id;
         this.recentAdditions.delete(addKey);
@@ -485,14 +486,14 @@ export class ObjectPool {
     }
     removeFromArchive(id) {
         const entry = this.entries.get(id);
-        if (!entry || entry.scope !== ModelScope.archived) {
+        if (entry?.scope !== ModelScope.archived) {
             return false;
         }
         return this.remove(id);
     }
     getByType(modelClass, scope = ModelScope.all) {
-        // Linear-style: read typeIndex + entries directly. Both are observable maps,
-        // so MobX always tracks the dependency — no conditional cache path.
+        // Read typeIndex and entries directly. Both are observable maps, so MobX
+        // always tracks the dependency — there is no conditional cache path.
         let actualModelName = this.registry.getModelNameFromConstructor(modelClass);
         if (!actualModelName) {
             actualModelName = this.registry.getModelNameFromConstructor(modelClass);
@@ -518,7 +519,7 @@ export class ObjectPool {
             return [];
         }
         // Resolve each ID from entries (observable) with scope filtering.
-        // Note: we do NOT check `instanceof modelClass` because schema-generated
+        // Note: we do not check `instanceof modelClass`, because schema-generated
         // dynamic classes and hand-coded classes are different constructors that
         // both represent the same model type. The typeIndex lookup by name is
         // authoritative — if the name matched, the model belongs to this type.
@@ -608,12 +609,12 @@ export class ObjectPool {
     createFromData(data, ModelClass, opts) {
         // Support multiple model identifier fields for backwards compatibility
         const modelName = data.__typename ?? data.__class ?? data.modelName ?? 'Unknown';
-        const Constructor = ModelClass || this.registry.getModelByName(modelName);
+        const Constructor = ModelClass ?? this.registry.getModelByName(modelName);
         if (!Constructor) {
-            if (!ModelClass && modelName === 'Unknown') {
+            if (modelName === 'Unknown') {
                 // Malformed row with no type marker — dropped, but nothing the consumer
                 // can act on (the actionable schema-drift case is handled below) → debug.
-                getContext().logger.debug('ObjectPool.createFromData: No model identifier found', { data });
+                getContext().logger.debug('InstanceCache.createFromData: No model identifier found', { data });
                 getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
                 return null;
             }
@@ -628,16 +629,16 @@ export class ObjectPool {
             // isn't in your schema, so these rows are silently skipped. Keep at warn,
             // consumer register (their model name + the `ablo status` fix); forensics ride debug.
             getContext().logger.warn(`Received data for "${modelName}", which isn't in your schema — these rows will be skipped. Run \`ablo status\` to compare your local schema with the server.`);
-            getContext().logger.debug(`ObjectPool.createFromData: No constructor found for model "${modelName}"`, { data });
+            getContext().logger.debug(`InstanceCache.createFromData: No constructor found for model "${modelName}"`, { data });
             getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
             return null;
         }
-        // Check if model already exists and UPDATE it instead of creating duplicate
-        // LINEAR PATTERN: Keep existing model instances alive, just update their data
-        // This preserves React's references and MobX observation tracking
+        // If the model already exists, update it in place instead of creating a
+        // duplicate. Keeping the existing instance alive preserves React's
+        // references and MobX's observation tracking.
         if (data.id && this.entries.has(data.id)) {
             const existing = this.get(data.id);
-            if (existing && existing.getModelName() === modelName) {
+            if (existing?.getModelName() === modelName) {
                 // Same ID and same type - update existing model with new data and return it
                 existing.updateFromData(data);
                 return existing;
@@ -656,7 +657,7 @@ export class ObjectPool {
             const errorMessage = error instanceof Error ? error.message : String(error);
             // Internal construction failure — captured via observability below and
             // re-fetched on resync; the stack is forensic → debug.
-            getContext().logger.debug(`[ObjectPool.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
+            getContext().logger.debug(`[InstanceCache.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
             getContext().observability.captureTransactionFailure({
                 context: 'createFromData',
                 modelName,
@@ -680,11 +681,8 @@ export class ObjectPool {
         const preserveObserved = options.preserveObserved ?? false;
         const preservedIds = [];
         const preservedEntries = [];
-        let disposedCount = 0;
-        let checkedCount = 0;
         for (const [id, entry] of this.entries) {
-            const model = entry.model || entry.weakRef?.deref();
-            checkedCount++;
+            const model = entry.model ?? entry.weakRef?.deref();
             // Check if this model should be preserved (has active React observers)
             if (preserveObserved &&
                 model &&
@@ -695,8 +693,12 @@ export class ObjectPool {
                 preservedEntries.push([id, entry]);
                 continue;
             }
-            model?.dispose?.();
-            disposedCount++;
+            // `rowAsModel` only casts, so a non-Model object can reach the pool (see
+            // the SyncClient no-op UPDATE guard). Guard that `dispose` is actually
+            // callable — mirroring the `hasObservedCollections` typeof-check above —
+            // rather than assume every pooled entry is a real Model.
+            if (typeof model?.dispose === 'function')
+                model.dispose();
         }
         // Save access times for preserved entries before clearing
         const preservedAccessTimes = new Map();
@@ -724,7 +726,7 @@ export class ObjectPool {
             // Re-add preserved entries (also rebuilds foreign key indexes via addToTypeIndex)
             for (const [id, entry] of preservedEntries) {
                 this.entries.set(id, entry);
-                const model = entry.model || entry.weakRef?.deref();
+                const model = entry.model ?? entry.weakRef?.deref();
                 if (model) {
                     this.addToTypeIndex(id, model.getModelName());
                 }
@@ -780,9 +782,9 @@ export class ObjectPool {
                 scopeCounts.live++;
             else if (entry.scope === ModelScope.archived)
                 scopeCounts.archived++;
-            const modelName = entry.model?.getModelName() || entry.weakRef?.deref()?.getModelName();
+            const modelName = entry.model?.getModelName() ?? entry.weakRef?.deref()?.getModelName();
             if (modelName) {
-                typeCounts.set(modelName, (typeCounts.get(modelName) || 0) + 1);
+                typeCounts.set(modelName, (typeCounts.get(modelName) ?? 0) + 1);
             }
         }
         return {
@@ -823,12 +825,12 @@ export class ObjectPool {
             let skippedObserved = 0;
             for (const [id, entry] of this.entries) {
                 // Check if model has expired based on last access time
-                const lastAccessed = this.accessTimes.get(id) || 0;
+                const lastAccessed = this.accessTimes.get(id) ?? 0;
                 if (now - lastAccessed > this.config.maxAge) {
-                    // CRITICAL: Check if model has observed collections before GC
-                    // Following MobX best practice: don't dispose models being observed by React
+                    // Do not GC a model that has observed collections — disposing one
+                    // React is still observing would break it (per MobX guidance).
                     // See: https://mobx.js.org/lazy-observables.html
-                    const model = entry.model || entry.weakRef?.deref();
+                    const model = entry.model ?? entry.weakRef?.deref();
                     if (model &&
                         typeof model.hasObservedCollections === 'function' &&
                         model.hasObservedCollections()) {
@@ -869,7 +871,7 @@ export class ObjectPool {
                 }
             }
             if (skippedObserved > 0) {
-                getContext().logger.debug(`[ObjectPool GC] Skipped ${skippedObserved} models with active React observers`);
+                getContext().logger.debug(`[InstanceCache GC] Skipped ${skippedObserved} models with active React observers`);
             }
             // Also clean up old tracking data
             this.clearDeltaHistory();
@@ -881,6 +883,12 @@ export class ObjectPool {
         if (this.gcTimer)
             return;
         this.gcTimer = setInterval(() => this.gc(), this.config.gcInterval);
+        // Don't hold a headless Node process open just for pool GC — without
+        // this, an agent that never calls disconnect() can never exit. No-op in
+        // browsers (where setInterval returns a number without `unref`), which is
+        // why the call is optional even though the Node timer type always has it.
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        this.gcTimer.unref?.();
     }
     stopGC() {
         if (this.gcTimer) {
@@ -894,13 +902,13 @@ export class ObjectPool {
             let oldestTime = Date.now();
             for (const [id, entry] of this.entries) {
                 // Skip models that are being observed by React - they must stay alive
-                const model = entry.model || entry.weakRef?.deref();
+                const model = entry.model ?? entry.weakRef?.deref();
                 if (model &&
                     typeof model.hasObservedCollections === 'function' &&
                     model.hasObservedCollections()) {
                     continue;
                 }
-                const entryAccessTime = this.accessTimes.get(id) || 0;
+                const entryAccessTime = this.accessTimes.get(id) ?? 0;
                 if (entryAccessTime < oldestTime) {
                     oldest = [id, entry];
                     oldestTime = entryAccessTime;
@@ -964,7 +972,7 @@ export class ObjectPool {
     getByForeignKey(modelName, fieldName, fieldValue) {
         const indexKey = `${modelName}:${fieldName}`;
         const index = this.foreignKeyIndexes.get(indexKey);
-        // Both empty-path early-returns below are NORMAL states, not errors:
+        // Both empty-path early-returns below are normal states, not errors:
         // a model with no FK index yet (not populated), or an index with no
         // entry for this specific parent id (entity genuinely has no
         // children). These used to `console.warn` diagnostic dumps on every
@@ -1005,7 +1013,7 @@ export class ObjectPool {
             // has dangling refs (legacy orphan deltas, pending CREATE
             // transactions, etc.). Noisy at warn level, useful during
             // investigation.
-            getContext().logger.debug('[ObjectPool.getByForeignKey] ROWS DROPPED', {
+            getContext().logger.debug('[InstanceCache.getByForeignKey] ROWS DROPPED', {
                 modelName,
                 fieldName,
                 fieldValue,
@@ -1031,7 +1039,7 @@ export class ObjectPool {
         if (!fields)
             return;
         for (const fieldName of fields) {
-            const fieldValue = Reflect.get(model, fieldName);
+            const fieldValue = model.getField(fieldName);
             if (typeof fieldValue !== 'string')
                 continue;
             const indexKey = `${modelName}:${fieldName}`;
@@ -1061,7 +1069,7 @@ export class ObjectPool {
         if (!model)
             return;
         for (const fieldName of fields) {
-            const fieldValue = Reflect.get(model, fieldName);
+            const fieldValue = model.getField(fieldName);
             if (typeof fieldValue !== 'string')
                 continue;
             const indexKey = `${modelName}:${fieldName}`;

package/dist/LazyReferenceCollection.d.ts

@@ -1,12 +1,11 @@
 /**
- * Linear Sync Engine - Lazy Reference Collection
- *
- * Efficient implementation of one-to-many relationships that loads
- * data on-demand with intelligent caching and batching.
+ * LazyReferenceCollection implements a lazy-loaded one-to-many relationship.
+ * It loads related rows on demand, caches them, and batches lookups so that
+ * reading a parent's children does not trigger a query per parent.
  */
 import type { Model } from './Model.js';
 import { Database } from './Database.js';
-import { ObjectPool } from './ObjectPool.js';
+import { InstanceCache } from './InstanceCache.js';
 /**
  * Options for LazyReferenceCollection behavior
  */
@@ -23,14 +22,11 @@ export interface LazyCollectionOptions {
     autoRefresh?: boolean;
 }
 /**
- * LazyReferenceCollection - Lazy-loaded one-to-many relationships
- *
- * Key features:
- * - Loads from IndexedDB first, then network if needed
- * - Automatic batching to prevent N+1 queries
- * - Observable for React integration
- * - Memory efficient with intelligent caching
- * - Support for filtering and sorting
+ * A lazy-loaded one-to-many relationship between a parent {@link Model} and
+ * its children. It reads from the local store first and falls back to the
+ * network, batches lookups to avoid one query per parent, and is observable so
+ * a React component re-renders when the set of children changes. Loaded items
+ * can be filtered, sorted, and limited through {@link LazyCollectionOptions}.
  */
 export declare class LazyReferenceCollection<T extends Model> {
     private modelName;
@@ -45,7 +41,7 @@ export declare class LazyReferenceCollection<T extends Model> {
      * Set global dependencies for all LazyReferenceCollection instances
      * Called once during SyncedStore initialization
      */
-    static setDependencies(database: Database, objectPool: ObjectPool): void;
+    static setDependencies(database: Database, objectPool: InstanceCache): void;
     /**
      * Clear dependencies (e.g., on logout/store disposal)
      */
@@ -82,7 +78,7 @@ export declare class LazyReferenceCollection<T extends Model> {
     /**
      * Get the collection value (triggers hydration if needed).
      *
-     * Filters out items whose id is no longer in the ObjectPool. The
+     * Filters out items whose id is no longer in the InstanceCache. The
      * local `items` array isn't auto-synced with `pool.remove()` — a
      * deleted entity would linger here until hydrate() re-runs on
      * reload. Reading `pool.has(item.id)` inside this computed getter

package/dist/LazyReferenceCollection.js

@@ -1,21 +1,19 @@
 /**
- * Linear Sync Engine - Lazy Reference Collection
- *
- * Efficient implementation of one-to-many relationships that loads
- * data on-demand with intelligent caching and batching.
+ * LazyReferenceCollection implements a lazy-loaded one-to-many relationship.
+ * It loads related rows on demand, caches them, and batches lookups so that
+ * reading a parent's children does not trigger a query per parent.
  */
 import { makeObservable, observable, action, computed, onBecomeObserved, onBecomeUnobserved, } from 'mobx';
+import { Database } from './Database.js';
+import { InstanceCache } from './InstanceCache.js';
 import { getActiveRegistry } from './ModelRegistry.js';
 import { AbloValidationError } from './errors.js';
 /**
- * LazyReferenceCollection - Lazy-loaded one-to-many relationships
- *
- * Key features:
- * - Loads from IndexedDB first, then network if needed
- * - Automatic batching to prevent N+1 queries
- * - Observable for React integration
- * - Memory efficient with intelligent caching
- * - Support for filtering and sorting
+ * A lazy-loaded one-to-many relationship between a parent {@link Model} and
+ * its children. It reads from the local store first and falls back to the
+ * network, batches lookups to avoid one query per parent, and is observable so
+ * a React component re-renders when the set of children changes. Loaded items
+ * can be filtered, sorted, and limited through {@link LazyCollectionOptions}.
  */
 export class LazyReferenceCollection {
     modelName;
@@ -130,7 +128,7 @@ export class LazyReferenceCollection {
     /**
      * Get the collection value (triggers hydration if needed).
      *
-     * Filters out items whose id is no longer in the ObjectPool. The
+     * Filters out items whose id is no longer in the InstanceCache. The
      * local `items` array isn't auto-synced with `pool.remove()` — a
      * deleted entity would linger here until hydrate() re-runs on
      * reload. Reading `pool.has(item.id)` inside this computed getter
@@ -260,7 +258,7 @@ export class LazyReferenceCollection {
                 throw new AbloValidationError(`Database dependency not provided to LazyReferenceCollection for ${this.modelName}`, { code: 'lazy_ref_db_missing' });
             }
             if (!this.objectPool) {
-                throw new AbloValidationError(`ObjectPool dependency not provided to LazyReferenceCollection for ${this.modelName}`, { code: 'lazy_ref_pool_missing' });
+                throw new AbloValidationError(`InstanceCache dependency not provided to LazyReferenceCollection for ${this.modelName}`, { code: 'lazy_ref_pool_missing' });
             }
             const store = this.database.getStore(this.modelName);
             const rawData = store ? await store.getAllFromIndex(this.foreignKey, this.parent.id) : [];
@@ -280,7 +278,7 @@ export class LazyReferenceCollection {
                 // narrow-checked here rather than assumed.
                 if (typeof id !== 'string')
                     continue;
-                // Check if already in ObjectPool
+                // Check if already in InstanceCache
                 let model = this.objectPool.get(id);
                 if (!model) {
                     // Create new model instance
@@ -289,6 +287,9 @@ export class LazyReferenceCollection {
                     this.objectPool.add(model);
                 }
                 if (model) {
+                    // The by-name registry lookup types instances as the base
+                    // `Model`; this collection's `modelName` IS `T`'s registered
+                    // name (fixed at construction), so the instance is a `T`.
                     models.push(model);
                 }
             }