@abloatai/ablo 0.35.0 → 0.37.0

package/dist/InstanceCache.js

@@ -1,1164 +0,0 @@
-/**
- * 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 './transaction/errors.js';
-import { ModelScope } from './transaction/types/index.js';
-import { ViewRegistry } from './core/ViewRegistry.js';
-import { QueryView } from './core/QueryView.js';
-// Re-exported so `import { ModelScope } from './InstanceCache.js'` resolves
-export { ModelScope };
-/**
- * The in-memory cache of model instances, keyed by id and deduplicated so each
- * entity resolves to a single instance.
- */
-export class InstanceCache {
-    // Single source of truth for all models (observable for reactivity)
-    entries = observable.map();
-    typeIndex = observable.map();
-    // Non-observable access time tracking — kept outside observable.map so that
-    // updating timestamps in get() during React render does NOT trigger MobX
-    // reactions (which would cause infinite re-render loops).
-    accessTimes = new Map();
-    // Deduplication tracking
-    recentAdditions = new Map(); // "modelType:modelId" -> timestamp
-    deltaHistory = new Map();
-    // 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 Block models where sectionId = X"
-    // instead of scanning all models of a type and filtering.
-    foreignKeyIndexes = new Map();
-    // Registry of which fields to index: Map<modelName, fieldName[]>
-    foreignKeyConfig = new Map();
-    // Performance tracking
-    metrics = {
-        hits: 0,
-        misses: 0,
-        evictions: 0,
-        additions: 0,
-        duplicatesSkipped: 0,
-    };
-    // Configuration
-    config;
-    gcTimer;
-    // ModelRegistry instance — single source of truth for model metadata
-    registry;
-    // ViewRegistry — tracks active QueryViews for incremental view maintenance
-    viewRegistry = new ViewRegistry();
-    // Subscription registry
-    subscriptions = new Map();
-    /**
-     * Subscribe to updates for a specific model type.
-     */
-    subscribe(modelClass, callback) {
-        const modelName = this.registry.getModelNameFromConstructor(modelClass);
-        if (!modelName) {
-            throw new AbloValidationError(`Model class not registered: ${modelClass.name}`, {
-                code: 'pool_subscribe_unregistered',
-            });
-        }
-        let subs = this.subscriptions.get(modelName);
-        if (!subs) {
-            subs = new Set();
-            this.subscriptions.set(modelName, subs);
-        }
-        const erased = callback;
-        subs.add(erased);
-        return () => subs.delete(erased);
-    }
-    notifySubscribers(model) {
-        const modelName = model.getModelName();
-        const subs = this.subscriptions.get(modelName);
-        if (subs) {
-            for (const callback of subs) {
-                callback(model);
-            }
-        }
-    }
-    constructor(config = {}, modelRegistry) {
-        this.config = {
-            maxSize: config.maxSize ?? 10000,
-            // Idle-eviction disabled by default. The 5-minute default used to
-            // live here, but with schema-driven dynamic classes not
-            // registering `LazyReferenceCollection`s, the
-            // `hasObservedCollections()` guard in gc() didn't fire for most
-            // actively-rendered models — and they'd evict out from under a
-            // user whose tab sat for 10 minutes. Memory pressure relief is
-            // handled by the `maxSize` LRU cap (see `evictOldest`), which is
-            // the bound that actually matches usage: "keep the most recent N
-            // entities, not the entities touched in the last N minutes."
-            //
-            // Callers who genuinely want time-based eviction can pass an
-            // explicit `maxAge`. Leaving the default at Infinity keeps
-            // correctness as the default and makes aggressive GC an opt-in.
-            maxAge: config.maxAge ?? Number.POSITIVE_INFINITY,
-            gcInterval: config.gcInterval ?? 60000, // 1 minute
-            useWeakRefs: config.useWeakRefs ?? true,
-        };
-        // Store the model registry reference
-        if (!modelRegistry) {
-            throw new AbloValidationError('InstanceCache requires ModelRegistry for production-safe model name lookup', { code: 'pool_registry_missing' });
-        }
-        this.registry = modelRegistry;
-        // 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,
-            addBatch: action,
-            upsertBatch: action,
-            removeBatch: action,
-            addToArchive: action,
-            remove: action,
-            removeFromArchive: action,
-            clear: action,
-            updateScope: action,
-            size: computed,
-        });
-        this.startGC();
-    }
-    // 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;
-        if (entry.weakRef) {
-            const model = entry.weakRef.deref();
-            if (model) {
-                entry.model = model;
-                if (id)
-                    this.accessTimes.set(id, Date.now());
-                return model;
-            }
-        }
-        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) {
-            runInAction(() => {
-                this.metrics.misses++;
-            });
-            return undefined;
-        }
-        let model = entry.model;
-        if (!model && entry.weakRef) {
-            const restoredModel = entry.weakRef.deref();
-            if (!restoredModel) {
-                runInAction(() => {
-                    this.entries.delete(id);
-                    this.removeFromTypeIndex(id, entry.model?.getModelName());
-                    this.metrics.misses++;
-                });
-                return undefined;
-            }
-            model = restoredModel;
-            runInAction(() => {
-                entry.model = restoredModel;
-            });
-        }
-        // Never return disposed models — they are logically removed and may have
-        // torn-down internal state. Callers (e.g. flushPendingDeltas) must not
-        // receive a disposed reference that will throw on updateFromData().
-        if (model?.disposed) {
-            return undefined;
-        }
-        // Update access time in non-observable map — prevents MobX reactions during render
-        this.accessTimes.set(id, Date.now());
-        this.metrics.hits++;
-        return model ?? undefined;
-    }
-    /**
-     * Look a row up **within one model**.
-     *
-     * The pool is a single id space: `get(id)` returns whatever row carries that
-     * id, whatever model it belongs to. That is the correct storage shape — ids
-     * are globally unique, the same premise as Relay's Global Object
-     * Identification — but it means an *untyped* lookup cannot stand in for a
-     * typed one. Apollo and EmberData avoid the question by keying their identity
-     * maps on `Type:id`; with unique ids the equivalent guarantee comes from
-     * stating the expected model at the lookup instead.
-     *
-     * Returns `undefined` for a row belonging to another model: from the asking
-     * model's perspective that id is simply absent. Callers that must tell "not
-     * here" apart from "here, but another model's" should compare against
-     * {@link get}.
-     *
-     * Prefer this over `get()` anywhere the caller knows which model it wants —
-     * `get()` returning another model's row has caused three product bugs, most
-     * recently a resize gesture that reverted after every commit.
-     */
-    // `T` appears only in the return position, which is normally a caller-chosen
-    // cast in disguise. It is sound here precisely because `modelName` is checked
-    // at runtime below before the row is handed back, so the caller's expected
-    // type and the row's registered identity cannot disagree.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-    getOfType(id, modelName) {
-        const model = this.get(id);
-        if (!model)
-            return undefined;
-        // Checked, so the assertion below is sound: `typeIndex` and
-        // `getModelName()` are the same registered-name identity.
-        return model.getModelName() === modelName ? model : undefined;
-    }
-    /**
-     * Add model with deduplication support
-     */
-    add(model, scope = ModelScope.live, deltaInfo) {
-        const id = model.id;
-        const modelType = model.getModelName();
-        const addKey = `${modelType}:${id}`;
-        // Ensure type index exists for this model type
-        if (!this.typeIndex.has(modelType)) {
-            this.typeIndex.set(modelType, observable.set());
-        }
-        // Check if model already exists to prevent duplicates
-        const existingEntry = this.entries.get(id);
-        if (existingEntry?.model && !existingEntry.model.disposed) {
-            // Model already exists and is valid, update its scope if needed
-            if (existingEntry.scope !== scope) {
-                runInAction(() => {
-                    this.entries.set(id, { ...existingEntry, scope });
-                });
-                this.accessTimes.set(id, Date.now());
-            }
-            this.metrics.duplicatesSkipped++;
-            return;
-        }
-        // Check rapid additions (within 50ms) for better deduplication
-        const lastAdded = this.recentAdditions.get(addKey);
-        if (lastAdded && Date.now() - lastAdded < 50) {
-            this.metrics.duplicatesSkipped++;
-            return;
-        }
-        // Check delta history for duplicate processing
-        if (deltaInfo?.syncId) {
-            const history = this.deltaHistory.get(addKey);
-            if (history) {
-                // Skip if we've already processed a newer or equal sync ID
-                if (history.lastSyncId >= deltaInfo.syncId) {
-                    this.metrics.duplicatesSkipped++;
-                    return;
-                }
-                // Warn about suspicious patterns
-                if (deltaInfo.action === 'I' &&
-                    (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(`InstanceCache.add() SUSPICIOUS: INSERT after ${history.lastAction}`, { modelType, id, syncId: deltaInfo.syncId });
-                }
-            }
-            // Update delta history
-            this.deltaHistory.set(addKey, {
-                lastAction: deltaInfo.action ?? 'U',
-                lastSyncId: deltaInfo.syncId,
-                timestamp: Date.now(),
-            });
-        }
-        // Track this addition
-        this.recentAdditions.set(addKey, Date.now());
-        // Clean old tracking entries periodically
-        if (this.recentAdditions.size > 100) {
-            this.cleanupTracking();
-        }
-        // Note: existingEntry check is now done earlier for better deduplication
-        if (this.entries.size >= this.config.maxSize) {
-            this.evictOldest();
-        }
-        const entry = {
-            model,
-            scope,
-        };
-        if (this.config.useWeakRefs && this.isLargeModel(model)) {
-            entry.weakRef = new WeakRef(model);
-        }
-        this.accessTimes.set(id, Date.now());
-        runInAction(() => {
-            this.entries.set(id, entry);
-            this.addToTypeIndex(id, model.getModelName());
-            this.metrics.additions++;
-        });
-        // No cache to invalidate — typeIndex + entries are directly observable
-        // Notify views of the addition
-        this.notifySubscribers(model);
-        this.viewRegistry.notifyAdded(modelType, model);
-    }
-    /**
-     * Upsert a model - INSERT if new, UPDATE if exists
-     */
-    upsert(model, scope = ModelScope.live) {
-        const id = model.id;
-        const existingEntry = this.entries.get(id);
-        if (existingEntry?.model && !existingEntry.model.disposed) {
-            // Model exists - update it in-place
-            const existingModel = existingEntry.model;
-            // Skip updateFromData if same instance - preserves _local changes for client mutations
-            if (model !== existingModel) {
-                existingModel.updateFromData(model.toJSON());
-            }
-            // Update scope if different
-            if (existingEntry.scope !== scope) {
-                runInAction(() => {
-                    this.entries.set(id, { ...existingEntry, scope });
-                });
-                this.accessTimes.set(id, Date.now());
-            }
-            this.notifySubscribers(existingModel);
-            // Notify views of the update
-            this.viewRegistry.notifyUpdated(existingModel.getModelName(), existingModel);
-        }
-        else {
-            // Model doesn't exist - add it (add() already notifies views)
-            this.add(model, scope);
-        }
-    }
-    /**
-     * Batch add models - optimized for hydration
-     * All models are added in a single MobX action to minimize reactivity overhead
-     */
-    addBatch(models, scope = ModelScope.live) {
-        if (models.length === 0)
-            return 0;
-        let addedCount = 0;
-        const now = Date.now();
-        // Process all models in a single action to avoid per-item reaction cycles
-        for (const model of models) {
-            const id = model.id;
-            const modelType = model.getModelName();
-            // Ensure type index exists
-            if (!this.typeIndex.has(modelType)) {
-                this.typeIndex.set(modelType, observable.set());
-            }
-            // Skip if model already exists and is valid
-            const existingEntry = this.entries.get(id);
-            if (existingEntry?.model && !existingEntry.model.disposed) {
-                if (existingEntry.scope !== scope) {
-                    this.entries.set(id, { ...existingEntry, scope });
-                    this.accessTimes.set(id, now);
-                }
-                this.metrics.duplicatesSkipped++;
-                continue;
-            }
-            // Evict if at capacity
-            if (this.entries.size >= this.config.maxSize) {
-                this.evictOldest();
-            }
-            const entry = {
-                model,
-                scope,
-            };
-            this.accessTimes.set(id, now);
-            if (this.config.useWeakRefs && this.isLargeModel(model)) {
-                entry.weakRef = new WeakRef(model);
-            }
-            this.entries.set(id, entry);
-            this.addToTypeIndex(id, modelType);
-            // Populate the foreign-key indexes. The single-item `add()` path
-            // does this; `addBatch()` used to skip it, which meant every
-            // block / ledger cell / message that came in through a bulk
-            // loader (`ensureReportBlocks`, `prefetchSectionBlocks`, bootstrap
-            // hydration) was in the pool but invisible to `hasMany` lookups
-            // — `section.blocks` returned `[]` until the user clicked a block
-            // and something else ran a non-batch `add` that happened to
-            // populate the FK index as a side effect. The UX symptom was
-            // "sections show empty until you click on one." Adding this one
-            // line closes the gap.
-            this.addToForeignKeyIndex(id, model, modelType);
-            this.metrics.additions++;
-            addedCount++;
-            this.notifySubscribers(model);
-            // Notify views of the addition
-            this.viewRegistry.notifyAdded(modelType, model);
-        }
-        // No cache to invalidate — typeIndex + entries are directly observable
-        return addedCount;
-    }
-    /**
-     * Batch upsert models - optimized for delta processing.
-     * All upserts happen in a single MobX action to minimize reactivity overhead.
-     */
-    upsertBatch(models, scope = ModelScope.live) {
-        if (models.length === 0)
-            return;
-        for (const model of models) {
-            const id = model.id;
-            const existingEntry = this.entries.get(id);
-            if (existingEntry?.model && !existingEntry.model.disposed) {
-                if (model !== existingEntry.model) {
-                    existingEntry.model.updateFromData(model.toJSON());
-                }
-                if (existingEntry.scope !== scope) {
-                    this.entries.set(id, { ...existingEntry, scope });
-                    this.accessTimes.set(id, Date.now());
-                }
-                this.notifySubscribers(existingEntry.model);
-                // Notify views of the update
-                this.viewRegistry.notifyUpdated(existingEntry.model.getModelName(), existingEntry.model);
-            }
-            else {
-                // Delegate to inline add logic (same as addBatch internals)
-                const modelType = model.getModelName();
-                if (!this.typeIndex.has(modelType)) {
-                    this.typeIndex.set(modelType, observable.set());
-                }
-                if (this.entries.size >= this.config.maxSize) {
-                    this.evictOldest();
-                }
-                const entry = { model, scope };
-                this.accessTimes.set(id, Date.now());
-                if (this.config.useWeakRefs && this.isLargeModel(model)) {
-                    entry.weakRef = new WeakRef(model);
-                }
-                this.entries.set(id, entry);
-                this.addToTypeIndex(id, modelType);
-                this.metrics.additions++;
-                this.notifySubscribers(model);
-                // Notify views of the addition
-                this.viewRegistry.notifyAdded(modelType, model);
-            }
-        }
-        // No cache to invalidate — typeIndex + entries are directly observable
-    }
-    /**
-     * Batch remove models by ID - optimized for delta processing.
-     * All removals happen in a single MobX action to minimize reactivity overhead.
-     * Returns the number of models actually removed.
-     */
-    removeBatch(ids) {
-        if (ids.length === 0)
-            return 0;
-        let removedCount = 0;
-        for (const id of ids) {
-            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()`
-            // for the full explanation. Same bug, same fix.
-            this.removeFromTypeIndex(id, modelName);
-            this.entries.delete(id);
-            // Notify views of the removal before disposing
-            if (modelName) {
-                this.viewRegistry.notifyRemoved(modelName, id);
-            }
-            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);
-            this.accessTimes.delete(id);
-            removedCount++;
-        }
-        // No cache to invalidate — typeIndex + entries are directly observable
-        return removedCount;
-    }
-    /**
-     * Read-only accessor for entity IDs by model type.
-     * Used by applyBootstrapToPool() and rehydrateFromDatabase() for ghost detection.
-     */
-    getIdsByModelType(modelType) {
-        return this.typeIndex.get(modelType);
-    }
-    addToArchive(model) {
-        this.add(model, ModelScope.archived);
-    }
-    remove(id) {
-        const entry = this.entries.get(id);
-        if (!entry)
-            return false;
-        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
-        // FK cleanup silently no-ops — leaving ghost ids in the FK index.
-        // That causes `getByForeignKey(..., parentId)` to report
-        // `matched > returned` (dropped-no-entry) and, on the UI, keeps the
-        // stale block visible until the next reload rebuilds the index
-        // from fresh data. Do the FK/type cleanup first, then delete the
-        // entry.
-        runInAction(() => {
-            this.removeFromTypeIndex(id, modelName);
-            this.entries.delete(id);
-        });
-        // No cache to invalidate — typeIndex + entries are directly observable
-        // Notify views of the removal before disposing
-        if (modelName) {
-            this.viewRegistry.notifyRemoved(modelName, id);
-        }
-        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);
-        this.deltaHistory.delete(addKey);
-        this.accessTimes.delete(id);
-        return true;
-    }
-    removeFromArchive(id) {
-        const entry = this.entries.get(id);
-        if (entry?.scope !== ModelScope.archived) {
-            return false;
-        }
-        return this.remove(id);
-    }
-    getByType(modelClass, scope = ModelScope.all) {
-        // 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);
-            if (!actualModelName) {
-                try {
-                    const ConcreteClass = modelClass;
-                    const tempInstance = new ConcreteClass({});
-                    actualModelName = tempInstance.getModelName();
-                    // Fallback resolved — hand-coded class not in registry but name matches.
-                    // This is expected during migration from hand-coded → dynamic models.
-                }
-                catch (e) {
-                    getContext().observability.breadcrumb(`Failed to create fallback instance for ${modelClass.name}`, 'sync.database', 'error', {
-                        error: e instanceof Error ? e.message : String(e),
-                    });
-                    return [];
-                }
-            }
-        }
-        // Read from typeIndex (observable) to get IDs for this model type
-        const ids = this.typeIndex.get(actualModelName || '');
-        if (!ids || ids.size === 0) {
-            return [];
-        }
-        // Resolve each ID from entries (observable) with scope filtering.
-        // 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.
-        const result = [];
-        for (const id of ids) {
-            const entry = this.entries.get(id);
-            if (!entry)
-                continue;
-            if (!this.matchesScope(entry.scope, scope))
-                continue;
-            const model = this.resolveModel(entry, id);
-            if (model && !model.disposed) {
-                result.push(model);
-            }
-        }
-        return result;
-    }
-    /**
-     * Get all models of a given type by string name.
-     * Used for custom entity types where multiple entity type names share
-     * the same CustomEntityModel constructor (getByType can't disambiguate).
-     * Reads from the same typeIndex as getByType — MobX tracks the dependency.
-     */
-    getByTypeName(modelName, scope = ModelScope.all) {
-        const ids = this.typeIndex.get(modelName);
-        if (!ids || ids.size === 0) {
-            return [];
-        }
-        const result = [];
-        for (const id of ids) {
-            const entry = this.entries.get(id);
-            if (!entry)
-                continue;
-            if (!this.matchesScope(entry.scope, scope))
-                continue;
-            const model = this.resolveModel(entry, id);
-            if (model && !model.disposed) {
-                result.push(model);
-            }
-        }
-        return result;
-    }
-    *iterateByType(modelClass, scope = ModelScope.all) {
-        const actualModelName = this.registry.getModelNameFromConstructor(modelClass);
-        if (!actualModelName) {
-            throw new AbloValidationError(`Model class ${modelClass.name} not registered in ModelRegistry`, { code: 'pool_model_class_not_registered' });
-        }
-        const ids = this.typeIndex.get(actualModelName);
-        if (!ids)
-            return;
-        for (const id of ids) {
-            const entry = this.entries.get(id);
-            if (!entry)
-                continue;
-            if (!this.matchesScope(entry.scope, scope))
-                continue;
-            const model = this.get(id);
-            if (model && model instanceof modelClass) {
-                yield model;
-            }
-        }
-    }
-    updateScope(id, scope) {
-        const entry = this.entries.get(id);
-        if (entry && entry.scope !== scope) {
-            // Re-set the entry so ObservableMap notifies observers of the change.
-            // Mutating entry.scope in-place wouldn't trigger MobX (plain object property).
-            runInAction(() => {
-                this.entries.set(id, { ...entry, scope });
-            });
-            this.accessTimes.set(id, Date.now());
-        }
-    }
-    /**
-     * Create (or update) a model instance locally, given a typename and raw
-     * data. Cleaner than `createFromData({ __typename, ...data })` — the
-     * typename lives in the arg list, not hidden inside the data object.
-     *
-     * Used for optimistic local writes: `pool.create('Section', { id, reportId, ... })`.
-     * For hydration from server deltas (where `__typename` already rides on
-     * the payload), use `createFromData(data)` directly — that path is kept
-     * because the wire format attaches the discriminator to the data itself.
-     */
-    create(typename, data) {
-        return this.createFromData({ ...data, __typename: typename });
-    }
-    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);
-        if (!Constructor) {
-            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('InstanceCache.createFromData: No model identifier found', { data });
-                getContext().modelDebugLogger?.logError('Unknown', 'CREATE', 'No model identifier found', data);
-                return null;
-            }
-            if (opts?.strict) {
-                const known = this.registry.getRegisteredModelNames();
-                throw new AbloValidationError(`Model "${modelName}" is not registered on this client` +
-                    (known.length ? ` (known: ${known.join(', ')})` : '') +
-                    `. The schema pushed to this org may differ from your local ` +
-                    `schema — run \`ablo status\` to compare.`, { code: 'model_not_registered' });
-            }
-            // Genuinely actionable and NOT self-healing: a model the server is sending
-            // 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(`InstanceCache.createFromData: No constructor found for model "${modelName}"`, { data });
-            getContext().modelDebugLogger?.logError(modelName, 'CREATE', `No constructor found for model "${modelName}"`, data);
-            return null;
-        }
-        // 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?.getModelName() === modelName) {
-                // Same ID and same type - update existing model with new data and return it
-                existing.updateFromData(data);
-                return existing;
-            }
-            // Different type with same ID - this is a shared PK scenario (e.g., two models sharing one row id)
-            // Don't return existing, create new model (will use composite key for storage)
-        }
-        // Log model creation attempt
-        getContext().modelDebugLogger?.logCreation(modelName, data, Constructor);
-        try {
-            // Pass data directly to constructor for Prisma-first models
-            const model = new Constructor(data);
-            return model;
-        }
-        catch (error) {
-            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(`[InstanceCache.createFromData] FAILED ${modelName}`, { errorMessage, stack: error instanceof Error ? error.stack : undefined });
-            getContext().observability.captureMutationFailure({
-                context: 'createFromData',
-                modelName,
-                modelId: data.id,
-                error: errorMessage,
-            });
-            getContext().modelDebugLogger?.logError(modelName, 'CREATE', errorMessage, {
-                data,
-                constructor: Constructor.name,
-            });
-            return null;
-        }
-    }
-    /**
-     * Clear the object pool
-     * @param options.preserveObserved - If true, keep models that are being observed by React
-     *                                   This prevents React components from holding stale references
-     *                                   after bootstrap/rehydration
-     */
-    clear(options = {}) {
-        const preserveObserved = options.preserveObserved ?? false;
-        const preservedIds = [];
-        const preservedEntries = [];
-        for (const [id, entry] of this.entries) {
-            const model = entry.model ?? entry.weakRef?.deref();
-            // Check if this model should be preserved (has active React observers)
-            if (preserveObserved &&
-                model &&
-                typeof model.hasObservedCollections === 'function' &&
-                model.hasObservedCollections()) {
-                // Keep this model alive - React is still using it
-                preservedIds.push(id);
-                preservedEntries.push([id, entry]);
-                continue;
-            }
-            // `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();
-        for (const [id] of preservedEntries) {
-            const time = this.accessTimes.get(id);
-            if (time)
-                preservedAccessTimes.set(id, time);
-        }
-        runInAction(() => {
-            this.entries.clear();
-            this.typeIndex.clear();
-            // Clear foreign key index data (preserves config/structure, just empties the value maps)
-            for (const index of this.foreignKeyIndexes.values()) {
-                index.clear();
-            }
-            this.recentAdditions.clear();
-            this.deltaHistory.clear();
-            this.metrics = {
-                hits: 0,
-                misses: 0,
-                evictions: 0,
-                additions: 0,
-                duplicatesSkipped: 0,
-            };
-            // 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();
-                if (model) {
-                    this.addToTypeIndex(id, model.getModelName());
-                }
-            }
-        });
-        // Restore access times: clear then re-add preserved
-        this.accessTimes.clear();
-        for (const [id, time] of preservedAccessTimes) {
-            this.accessTimes.set(id, time);
-        }
-        // No cache to invalidate — typeIndex + entries are directly observable
-    }
-    has(id) {
-        return this.entries.has(id);
-    }
-    /**
-     * Touch a model to update its access time (prevents premature GC)
-     * Used by LazyReferenceCollection to keep parent models alive during active usage
-     */
-    touch(id) {
-        const entry = this.entries.get(id);
-        if (!entry) {
-            return false;
-        }
-        this.accessTimes.set(id, Date.now());
-        return true;
-    }
-    getAllIds() {
-        return Array.from(this.entries.keys());
-    }
-    getAllModels() {
-        const results = [];
-        for (const [id] of this.entries) {
-            const model = this.get(id);
-            if (model) {
-                results.push(model);
-            }
-        }
-        return results;
-    }
-    get size() {
-        return this.entries.size;
-    }
-    get hitRate() {
-        const total = this.metrics.hits + this.metrics.misses;
-        return total > 0 ? (this.metrics.hits / total) * 100 : 0;
-    }
-    getStats() {
-        const scopeCounts = { live: 0, archived: 0 };
-        const typeCounts = new Map();
-        for (const [, entry] of this.entries) {
-            if (entry.scope === ModelScope.live)
-                scopeCounts.live++;
-            else if (entry.scope === ModelScope.archived)
-                scopeCounts.archived++;
-            const modelName = entry.model?.getModelName() ?? entry.weakRef?.deref()?.getModelName();
-            if (modelName) {
-                typeCounts.set(modelName, (typeCounts.get(modelName) ?? 0) + 1);
-            }
-        }
-        return {
-            size: this.size,
-            hitRate: this.hitRate,
-            metrics: { ...this.metrics },
-            scopeCounts,
-            typeCounts: Object.fromEntries(typeCounts),
-            deltaHistorySize: this.deltaHistory.size,
-            recentAdditionsSize: this.recentAdditions.size,
-            config: { ...this.config },
-        };
-    }
-    clearDeltaHistory(olderThanMs = 3600000) {
-        const now = Date.now();
-        const toDelete = [];
-        for (const [key, history] of this.deltaHistory) {
-            if (now - history.timestamp > olderThanMs) {
-                toDelete.push(key);
-            }
-        }
-        toDelete.forEach((key) => this.deltaHistory.delete(key));
-        // Delta history entries cleared silently
-    }
-    cleanupTracking() {
-        const now = Date.now();
-        for (const [key, time] of this.recentAdditions) {
-            if (now - time > 1000) {
-                this.recentAdditions.delete(key);
-            }
-        }
-    }
-    gc() {
-        return runInAction(() => {
-            const now = Date.now();
-            const toRemove = [];
-            let evicted = 0;
-            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;
-                if (now - lastAccessed > this.config.maxAge) {
-                    // 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();
-                    if (model &&
-                        typeof model.hasObservedCollections === 'function' &&
-                        model.hasObservedCollections()) {
-                        // Model has active React observers - refresh access time and skip GC
-                        this.accessTimes.set(id, now);
-                        skippedObserved++;
-                        continue;
-                    }
-                    toRemove.push(id);
-                    continue;
-                }
-                // Strong-to-weak-ref demotion at `maxAge / 2` used to live here,
-                // in service of memory-pressure relief: idle entries would lose
-                // their strong reference, V8 would collect them, and the next
-                // access would re-hydrate from IDB/network. In practice it
-                // caused silent data loss — any model actively being rendered
-                // through a schema-driven dynamic class (i.e., most of them)
-                // would be demoted, collected, and the next render's
-                // `weakRef.deref()` returned undefined, so blocks / cells /
-                // messages "disappeared" after ~10 min of idle.
-                //
-                // The `hasObservedCollections()` guard used by the eviction
-                // branch above only protects models that explicitly register a
-                // LazyReferenceCollection; plain observer() components reading
-                // properties don't register, so for typical UI usage the guard
-                // didn't apply. Rather than try to make React-observation
-                // globally visible to the pool, we drop the demotion phase
-                // entirely — hard eviction at `maxAge` (with its own guard) is
-                // the only automated removal now. If memory-pressure relief is
-                // needed later, gate it on an explicit policy (e.g.,
-                // `documenthidden` + `performance.memory.usedJSHeapSize`) rather
-                // than a time-based tick.
-            }
-            for (const id of toRemove) {
-                if (this.remove(id)) {
-                    evicted++;
-                    this.metrics.evictions++;
-                }
-            }
-            if (skippedObserved > 0) {
-                getContext().logger.debug(`[InstanceCache GC] Skipped ${skippedObserved} models with active React observers`);
-            }
-            // Also clean up old tracking data
-            this.clearDeltaHistory();
-            this.cleanupTracking();
-            return evicted;
-        });
-    }
-    startGC() {
-        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) {
-            clearInterval(this.gcTimer);
-            this.gcTimer = undefined;
-        }
-    }
-    evictOldest() {
-        runInAction(() => {
-            let oldest;
-            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();
-                if (model &&
-                    typeof model.hasObservedCollections === 'function' &&
-                    model.hasObservedCollections()) {
-                    continue;
-                }
-                const entryAccessTime = this.accessTimes.get(id) ?? 0;
-                if (entryAccessTime < oldestTime) {
-                    oldest = [id, entry];
-                    oldestTime = entryAccessTime;
-                }
-            }
-            if (oldest) {
-                this.remove(oldest[0]);
-                this.metrics.evictions++;
-            }
-        });
-    }
-    isLargeModel(model) {
-        try {
-            const size = JSON.stringify(model).length;
-            return size > 10240;
-        }
-        catch {
-            return false;
-        }
-    }
-    // ========== FOREIGN KEY INDEX ==========
-    /**
-     * Register a foreign key field for indexing on a model type.
-     * Call once during app initialization (e.g., after model registration).
-     *
-     * Example: registerForeignKey('Block', 'sectionId')
-     * This enables getByForeignKey('Block', 'sectionId', someSectionId) → O(1) lookup
-     */
-    registerForeignKey(modelName, fieldName) {
-        const fields = this.foreignKeyConfig.get(modelName) ?? [];
-        if (!fields.includes(fieldName)) {
-            fields.push(fieldName);
-            this.foreignKeyConfig.set(modelName, fields);
-        }
-        // Initialize the index map
-        const indexKey = `${modelName}:${fieldName}`;
-        if (!this.foreignKeyIndexes.has(indexKey)) {
-            this.foreignKeyIndexes.set(indexKey, observable.map());
-        }
-    }
-    /**
-     * Check whether a foreign key index exists for a given typename + field.
-     * Used by QueryView to decide whether to use FK-index for initial scan.
-     */
-    hasForeignKeyIndex(typename, fieldName) {
-        const indexKey = `${typename}:${fieldName}`;
-        return this.foreignKeyIndexes.has(indexKey);
-    }
-    /**
-     * Create a QueryView — an incrementally maintained materialized view.
-     * The view registers itself with the ViewRegistry and receives
-     * incremental updates when models of the given typename change.
-     */
-    createView(typename, options) {
-        return new QueryView(typename, this, this.viewRegistry, options);
-    }
-    /**
-     * O(1) lookup of models by foreign key value.
-     * Returns model instances, filtered to live scope by default.
-     */
-    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:
-        // 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
-        // call, which turned into hundreds of log lines per second during
-        // cursor hover / rapid re-renders on a busy page. If a caller
-        // needs visibility into "why is this empty," wire an opt-in
-        // `logger.debug` at the specific call site rather than re-adding
-        // a blanket warn here.
-        if (!index)
-            return [];
-        const ids = index.get(fieldValue);
-        if (!ids || ids.size === 0)
-            return [];
-        const result = [];
-        let droppedNoEntry = 0;
-        let droppedScope = 0;
-        let droppedDisposed = 0;
-        for (const id of ids) {
-            const entry = this.entries.get(id);
-            if (!entry) {
-                droppedNoEntry++;
-                continue;
-            }
-            if (!this.matchesScope(entry.scope, ModelScope.live)) {
-                droppedScope++;
-                continue;
-            }
-            const model = this.resolveModel(entry, id);
-            if (model && !model.disposed) {
-                result.push(model);
-            }
-            else if (model?.disposed) {
-                droppedDisposed++;
-            }
-        }
-        if (droppedNoEntry || droppedScope || droppedDisposed) {
-            // Debug-level: happens on every render when a foreign-key index
-            // has dangling refs (legacy orphan deltas, pending CREATE
-            // transactions, etc.). Noisy at warn level, useful during
-            // investigation.
-            getContext().logger.debug('[InstanceCache.getByForeignKey] ROWS DROPPED', {
-                modelName,
-                fieldName,
-                fieldValue,
-                matched: ids.size,
-                returned: result.length,
-                droppedNoEntry,
-                droppedScope,
-                droppedDisposed,
-            });
-        }
-        return result;
-    }
-    /**
-     * Add a model to foreign key indexes (called from addToTypeIndex path)
-     */
-    addToForeignKeyIndex(id, model, modelName) {
-        // Silent no-ops for "no config / non-string value / missing index"
-        // — all three are legitimate states (non-indexed model, optional
-        // nullable FK, index not yet registered because the batch ran
-        // before schema registration completed). Diagnostic warns that
-        // used to live here spammed the console on every hot-path load.
-        const fields = this.foreignKeyConfig.get(modelName);
-        if (!fields)
-            return;
-        for (const fieldName of fields) {
-            const fieldValue = model.getField(fieldName);
-            if (typeof fieldValue !== 'string')
-                continue;
-            const indexKey = `${modelName}:${fieldName}`;
-            const index = this.foreignKeyIndexes.get(indexKey);
-            if (!index)
-                continue;
-            let ids = index.get(fieldValue);
-            if (!ids) {
-                ids = observable.set();
-                index.set(fieldValue, ids);
-            }
-            ids.add(id);
-        }
-    }
-    /**
-     * Remove a model from foreign key indexes (called from removeFromTypeIndex path)
-     */
-    removeFromForeignKeyIndex(id, modelName) {
-        if (!modelName)
-            return;
-        const fields = this.foreignKeyConfig.get(modelName);
-        if (!fields)
-            return;
-        // We need the model to read the foreign key value
-        const entry = this.entries.get(id);
-        const model = entry?.model ?? entry?.weakRef?.deref();
-        if (!model)
-            return;
-        for (const fieldName of fields) {
-            const fieldValue = model.getField(fieldName);
-            if (typeof fieldValue !== 'string')
-                continue;
-            const indexKey = `${modelName}:${fieldName}`;
-            const index = this.foreignKeyIndexes.get(indexKey);
-            if (!index)
-                continue;
-            const ids = index.get(fieldValue);
-            if (ids) {
-                ids.delete(id);
-                if (ids.size === 0) {
-                    index.delete(fieldValue);
-                }
-            }
-        }
-    }
-    addToTypeIndex(id, modelName) {
-        if (!modelName)
-            return;
-        let ids = this.typeIndex.get(modelName);
-        if (!ids) {
-            ids = observable.set();
-            this.typeIndex.set(modelName, ids);
-        }
-        ids.add(id);
-        // Update foreign key indexes. If we can't reach the model object,
-        // the FK index will be (re)populated on the first lookup that
-        // resolves the entry — no need to warn here.
-        const entry = this.entries.get(id);
-        const model = entry?.model ?? entry?.weakRef?.deref();
-        if (model) {
-            this.addToForeignKeyIndex(id, model, modelName);
-        }
-    }
-    removeFromTypeIndex(id, modelName) {
-        if (!modelName)
-            return;
-        // Remove from foreign key indexes BEFORE removing from entries
-        this.removeFromForeignKeyIndex(id, modelName);
-        const ids = this.typeIndex.get(modelName);
-        if (ids) {
-            ids.delete(id);
-            if (ids.size === 0) {
-                this.typeIndex.delete(modelName);
-            }
-        }
-    }
-    matchesScope(entryScope, queryScope) {
-        switch (queryScope) {
-            case ModelScope.all:
-                return true;
-            case ModelScope.live:
-                return entryScope === ModelScope.live;
-            case ModelScope.archived:
-                return entryScope === ModelScope.archived;
-            default:
-                return entryScope === queryScope;
-        }
-    }
-}