@memberjunction/core 5.8.0 → 5.10.0

package/dist/generic/localCacheManager.js

@@ -1,5 +1,12 @@
-import { BaseSingleton } from "@memberjunction/global";
-import { LogError } from "./logging.js";
+import { BaseSingleton, MJGlobal, MJEventType } from "@memberjunction/global";
+import { LogError, LogStatusEx } from "./logging.js";
+import { BaseEntity } from "./baseEntity.js";
+import { Metadata } from "./metadata.js";
+import { CompositeKey, KeyValuePair } from "./compositeKey.js";
+/** Verbose-only status logging — hidden unless verbose logging is enabled */
+function LogStatusVerbose(message) {
+    LogStatusEx({ message, verboseOnly: true });
+}
 // ============================================================================
 // DEFAULT CONFIGURATION
 // ============================================================================
@@ -72,6 +79,21 @@ export class LocalCacheManager extends BaseSingleton {
         this._stats = { hits: 0, misses: 0 };
         this._config = { ...DEFAULT_CONFIG };
         this.REGISTRY_KEY = '__MJ_CACHE_REGISTRY__';
+        /**
+         * Reverse index from entity name to the set of RunView cache fingerprints
+         * that contain data for that entity. Enables O(1) lookup when a BaseEntity
+         * event fires so we can update all relevant cached results.
+         */
+        this._entityFingerprintIndex = new Map();
+        // ========================================================================
+        // CROSS-SERVER CACHE CHANGE CALLBACKS
+        // ========================================================================
+        /**
+         * Map from cache fingerprint (or category for category_cleared events) to
+         * registered {@link CacheChangedEvent} callbacks. Callbacks are invoked when
+         * another server instance modifies the corresponding cached entry via Redis pub/sub.
+         */
+        this._changeCallbacks = new Map();
         this._persistTimeout = null;
     }
     // ========================================================================
@@ -112,6 +134,9 @@ export class LocalCacheManager extends BaseSingleton {
         }
         await this.loadRegistry();
         this._initialized = true;
+        // Subscribe to BaseEntity events for universal cache invalidation.
+        // When any entity is saved/deleted, update all cached RunView results for that entity.
+        this.subscribeToBaseEntityEvents();
     }
     /**
      * Returns whether the cache manager has been initialized
@@ -131,6 +156,407 @@ export class LocalCacheManager extends BaseSingleton {
     UpdateConfig(config) {
         this._config = { ...this._config, ...config };
     }
+    /**
+     * Replaces the storage provider after initialization. This is needed when
+     * the initial provider (e.g., in-memory) needs to be swapped for a
+     * persistent provider (e.g., Redis) that becomes available later.
+     *
+     * Migrates the in-memory registry to the new provider and rebuilds
+     * the entity→fingerprint reverse index.
+     *
+     * @param newProvider - The new storage provider to use
+     */
+    async SetStorageProvider(newProvider) {
+        if (!this._initialized) {
+            // Not yet initialized — just set the provider and return
+            this._storageProvider = newProvider;
+            return;
+        }
+        const oldProvider = this._storageProvider;
+        this._storageProvider = newProvider;
+        // Migrate existing cached data from old provider to new provider
+        const entries = this.GetAllEntries();
+        let migratedCount = 0;
+        for (const entry of entries) {
+            try {
+                const category = this.getCategoryForType(entry.type);
+                const data = await oldProvider?.GetItem(entry.key, category);
+                if (data) {
+                    await newProvider.SetItem(entry.key, data, category);
+                    migratedCount++;
+                }
+            }
+            catch (err) {
+                LogError(`LocalCacheManager.SetStorageProvider: Failed to migrate key "${entry.key}": ${err.message}`);
+            }
+        }
+        // Persist the registry to the new provider
+        await this.persistRegistry();
+        LogStatusVerbose(`LocalCacheManager.SetStorageProvider: Migrated ${migratedCount}/${entries.length} entries to new storage provider`);
+    }
+    // ========================================================================
+    // ENTITY → FINGERPRINT REVERSE INDEX
+    // ========================================================================
+    /**
+     * Extracts the entity name from a RunView fingerprint.
+     * Fingerprint format: `EntityName|Filter|OrderBy|ResultType|MaxRows|StartRow|AggHash[|Connection]`
+     * @param fingerprint - The RunView cache fingerprint
+     * @returns The entity name, or null if the fingerprint is malformed
+     */
+    extractEntityFromFingerprint(fingerprint) {
+        const pipeIndex = fingerprint.indexOf('|');
+        return pipeIndex > 0 ? fingerprint.substring(0, pipeIndex) : null;
+    }
+    /**
+     * Returns true if the fingerprint includes a non-trivial filter (not just '_' or empty).
+     * Unfiltered fingerprints can safely have records upserted in-place; filtered ones
+     * must be invalidated conservatively since the new data may not match the filter.
+     * @param fingerprint - The RunView cache fingerprint
+     */
+    isFilteredFingerprint(fingerprint) {
+        const parts = fingerprint.split('|');
+        return parts.length >= 2 && parts[1] !== '_' && parts[1] !== '';
+    }
+    /**
+     * Adds a fingerprint to the entity→fingerprint reverse index.
+     * Called when a RunView result is cached.
+     */
+    addToEntityIndex(fingerprint) {
+        const entity = this.extractEntityFromFingerprint(fingerprint);
+        if (!entity)
+            return;
+        if (!this._entityFingerprintIndex.has(entity)) {
+            this._entityFingerprintIndex.set(entity, new Set());
+        }
+        this._entityFingerprintIndex.get(entity).add(fingerprint);
+    }
+    /**
+     * Removes a fingerprint from the entity→fingerprint reverse index.
+     * Called when a RunView result is invalidated.
+     */
+    removeFromEntityIndex(fingerprint) {
+        const entity = this.extractEntityFromFingerprint(fingerprint);
+        if (!entity)
+            return;
+        const set = this._entityFingerprintIndex.get(entity);
+        if (set) {
+            set.delete(fingerprint);
+            if (set.size === 0) {
+                this._entityFingerprintIndex.delete(entity);
+            }
+        }
+    }
+    /**
+     * Returns the set of cached fingerprints for a given entity name.
+     * Useful for diagnostics and testing.
+     */
+    GetFingerprintsForEntity(entityName) {
+        return this._entityFingerprintIndex.get(entityName) ?? new Set();
+    }
+    // ========================================================================
+    // UNIVERSAL CACHE INVALIDATION (BaseEntity Events)
+    // ========================================================================
+    /**
+     * Subscribes to MJGlobal BaseEntity events to proactively update all cached
+     * RunView results when entities are saved or deleted. This ensures ALL cached
+     * data stays consistent, not just engine-managed data.
+     */
+    subscribeToBaseEntityEvents() {
+        LogStatusVerbose('LocalCacheManager: Subscribed to BaseEntity events for universal cache invalidation');
+        MJGlobal.Instance.GetEventListener(false).subscribe((mjEvent) => {
+            if (mjEvent.event !== MJEventType.ComponentEvent)
+                return;
+            if (mjEvent.eventCode !== BaseEntity.BaseEventCode)
+                return;
+            const entityEvent = mjEvent.args;
+            if (!entityEvent)
+                return;
+            // Handle remote-invalidate events with embedded record data
+            if (entityEvent.type === 'remote-invalidate') {
+                this.HandleRemoteInvalidateEvent(entityEvent).catch((err) => {
+                    LogError(`LocalCacheManager.HandleRemoteInvalidateEvent error: ${err.message}`);
+                });
+                return;
+            }
+            // Only react to completed save and delete events
+            if (entityEvent.type !== 'save' && entityEvent.type !== 'delete')
+                return;
+            // Fire-and-forget to avoid blocking the save/delete operation
+            this.HandleBaseEntityEvent(entityEvent).catch((err) => {
+                LogError(`LocalCacheManager.HandleBaseEntityEvent error: ${err.message}`);
+            });
+        });
+    }
+    /**
+     * Handles a BaseEntity event by updating all cached RunView results for the
+     * affected entity. For unfiltered caches, updates the record in-place.
+     * For filtered caches, invalidates the cache entry (conservative approach
+     * since we can't verify filter match without re-querying).
+     *
+     * @param entityEvent - The BaseEntity event payload
+     */
+    async HandleBaseEntityEvent(entityEvent) {
+        const baseEntity = entityEvent.baseEntity;
+        if (!baseEntity?.EntityInfo?.Name)
+            return;
+        const entityName = baseEntity.EntityInfo.Name;
+        const fingerprints = this._entityFingerprintIndex.get(entityName);
+        if (!fingerprints || fingerprints.size === 0)
+            return;
+        const primaryKeys = baseEntity.EntityInfo.PrimaryKeys;
+        if (!primaryKeys || primaryKeys.length === 0)
+            return;
+        // Build a CompositeKey from the entity's primary key fields
+        const key = new CompositeKey();
+        key.LoadFromEntityInfoAndRecord(baseEntity.EntityInfo, baseEntity.GetAll());
+        if (key.KeyValuePairs.length === 0 || key.KeyValuePairs.some(kv => kv.Value == null))
+            return;
+        LogStatusVerbose(`LocalCacheManager: BaseEntity ${entityEvent.type} event for "${entityName}" PK=${key.ToConcatenatedString()}, updating ${fingerprints.size} cached fingerprint(s)`);
+        const fingerprintSnapshot = [...fingerprints];
+        const nowISO = new Date().toISOString();
+        for (const fingerprint of fingerprintSnapshot) {
+            try {
+                await this.processEntityEventForFingerprint(entityEvent.type, fingerprint, baseEntity, key, nowISO);
+            }
+            catch (err) {
+                LogError(`HandleBaseEntityEvent: failed to update fingerprint "${fingerprint}": ${err.message}`);
+            }
+        }
+    }
+    /**
+     * Handles remote-invalidate events that include recordData (the saved entity as JSON).
+     * Updates all cached RunView results for the entity without a server round-trip.
+     * For delete events or events without recordData, the cache entries are invalidated
+     * so the next RunView call will fetch fresh data from the server.
+     */
+    async HandleRemoteInvalidateEvent(entityEvent) {
+        const payload = entityEvent.payload;
+        const entityName = entityEvent.entityName;
+        if (!entityName)
+            return;
+        const fingerprints = this._entityFingerprintIndex.get(entityName);
+        if (!fingerprints || fingerprints.size === 0)
+            return;
+        const action = payload?.action;
+        // Look up entity metadata for PK field names
+        const md = new Metadata();
+        const entityInfo = md.Entities.find(e => e.Name === entityName);
+        if (!entityInfo) {
+            LogStatusVerbose(`LocalCacheManager: remote-invalidate — entity "${entityName}" not found in metadata, invalidating caches`);
+            for (const fp of [...fingerprints]) {
+                await this.InvalidateRunViewResult(fp);
+            }
+            return;
+        }
+        const primaryKeys = entityInfo.PrimaryKeys;
+        if (!primaryKeys || primaryKeys.length === 0) {
+            LogStatusVerbose(`LocalCacheManager: remote-invalidate — no PKs for "${entityName}", invalidating ${fingerprints.size} cached fingerprint(s)`);
+            for (const fp of [...fingerprints]) {
+                await this.InvalidateRunViewResult(fp);
+            }
+            return;
+        }
+        const nowISO = new Date().toISOString();
+        const fingerprintSnapshot = [...fingerprints];
+        // Handle delete: remove the record from all cached results
+        if (action === 'delete') {
+            const key = this.parseCompositeKeyFromJSON(payload?.primaryKeyValues);
+            if (!key) {
+                LogStatusVerbose(`LocalCacheManager: remote-invalidate (delete) — no PK values for "${entityName}", invalidating caches`);
+                for (const fp of fingerprintSnapshot) {
+                    await this.InvalidateRunViewResult(fp);
+                }
+                return;
+            }
+            LogStatusVerbose(`LocalCacheManager: remote-invalidate (delete) for "${entityName}" PK=${key.ToConcatenatedString()}, removing from ${fingerprints.size} cached fingerprint(s)`);
+            for (const fingerprint of fingerprintSnapshot) {
+                try {
+                    await this.RemoveSingleEntity(fingerprint, key, nowISO);
+                }
+                catch (err) {
+                    LogError(`HandleRemoteInvalidateEvent: failed to remove from "${fingerprint}": ${err.message}`);
+                }
+            }
+            return;
+        }
+        // Handle save: upsert record data into cached results
+        if (action === 'save' && payload?.recordData) {
+            try {
+                const recordData = JSON.parse(payload.recordData);
+                // Build CompositeKey from record data using entity PK fields
+                const key = this.buildCompositeKeyFromRow(recordData, primaryKeys.map(pk => pk.Name));
+                if (key.KeyValuePairs.some(kv => kv.Value == null))
+                    return;
+                LogStatusVerbose(`LocalCacheManager: remote-invalidate (save) for "${entityName}" PK=${key.ToConcatenatedString()}, updating ${fingerprints.size} cached fingerprint(s)`);
+                for (const fingerprint of fingerprintSnapshot) {
+                    try {
+                        if (!this.isFilteredFingerprint(fingerprint)) {
+                            await this.UpsertSingleEntity(fingerprint, recordData, key, nowISO);
+                        }
+                        else {
+                            await this.InvalidateRunViewResult(fingerprint);
+                        }
+                    }
+                    catch (err) {
+                        LogError(`HandleRemoteInvalidateEvent: failed to update "${fingerprint}": ${err.message}`);
+                    }
+                }
+            }
+            catch (e) {
+                LogError(`HandleRemoteInvalidateEvent: failed to parse recordData for "${entityName}": ${e.message}`);
+                for (const fp of fingerprintSnapshot) {
+                    await this.InvalidateRunViewResult(fp);
+                }
+            }
+            return;
+        }
+        // Fallback: no record data or unrecognized action — invalidate
+        LogStatusVerbose(`LocalCacheManager: remote-invalidate (${action || 'unknown'}) for "${entityName}", invalidating ${fingerprints.size} cached fingerprint(s)`);
+        for (const fp of fingerprintSnapshot) {
+            await this.InvalidateRunViewResult(fp);
+        }
+    }
+    /**
+     * Parses a JSON-encoded primaryKeyValues string (array of {FieldName, Value} pairs)
+     * into a CompositeKey. Returns null if parsing fails or the string is empty.
+     */
+    parseCompositeKeyFromJSON(primaryKeyValuesJSON) {
+        if (!primaryKeyValuesJSON)
+            return null;
+        try {
+            const pairs = JSON.parse(primaryKeyValuesJSON);
+            if (!pairs || pairs.length === 0)
+                return null;
+            return CompositeKey.FromKeyValuePairs(pairs.map(p => new KeyValuePair(p.FieldName, p.Value)));
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Builds a CompositeKey from a plain row object using the specified PK field names.
+     */
+    buildCompositeKeyFromRow(row, pkFieldNames) {
+        const pairs = pkFieldNames.map(fn => new KeyValuePair(fn, row[fn]));
+        return CompositeKey.FromKeyValuePairs(pairs);
+    }
+    /**
+     * Processes a single fingerprint for a BaseEntity event.
+     * Decomposed from HandleBaseEntityEvent for clarity and testability.
+     */
+    async processEntityEventForFingerprint(eventType, fingerprint, baseEntity, key, nowISO) {
+        const keyStr = key.ToConcatenatedString();
+        if (eventType === 'delete') {
+            LogStatusVerbose(`LocalCacheManager: Removing entity ${keyStr} from cache "${fingerprint.substring(0, 60)}"`);
+            await this.RemoveSingleEntity(fingerprint, key, nowISO);
+        }
+        else if (!this.isFilteredFingerprint(fingerprint)) {
+            // Unfiltered cache: update the record in place
+            LogStatusVerbose(`LocalCacheManager: Upserting entity ${keyStr} in unfiltered cache "${fingerprint.substring(0, 60)}"`);
+            const entityData = baseEntity.GetAll();
+            await this.UpsertSingleEntity(fingerprint, entityData, key, nowISO);
+        }
+        else {
+            // Filtered cache: conservatively invalidate (can't verify filter match)
+            LogStatusVerbose(`LocalCacheManager: Invalidating filtered cache "${fingerprint.substring(0, 60)}"`);
+            await this.InvalidateRunViewResult(fingerprint);
+        }
+    }
+    /**
+     * Registers a callback that fires when a specific cache fingerprint is updated
+     * by another server instance. Returns an unsubscribe function to remove the callback.
+     *
+     * This is the mechanism that powers the `OnDataChanged` callback in {@link RunViewParams}.
+     * Engines, components, and other callers can use this to react to cross-server
+     * cache invalidation without polling.
+     *
+     * @param fingerprint - The cache key/fingerprint to watch. For RunView results,
+     *                      use {@link GenerateRunViewFingerprint} to build this.
+     * @param callback - Function invoked with the {@link CacheChangedEvent} when
+     *                   the fingerprint's cached data changes on another server.
+     * @returns A function that, when called, removes this specific callback registration.
+     *
+     * @example
+     * ```typescript
+     * const fingerprint = cache.GenerateRunViewFingerprint(params, connectionPrefix);
+     * const unsubscribe = cache.RegisterChangeCallback(fingerprint, (event) => {
+     *     console.log(`Data changed for ${event.CacheKey}`);
+     *     // Reload, re-render, etc.
+     * });
+     *
+     * // Later, on cleanup:
+     * unsubscribe();
+     * ```
+     */
+    RegisterChangeCallback(fingerprint, callback) {
+        if (!this._changeCallbacks.has(fingerprint)) {
+            this._changeCallbacks.set(fingerprint, new Set());
+        }
+        this._changeCallbacks.get(fingerprint).add(callback);
+        return () => {
+            const callbacks = this._changeCallbacks.get(fingerprint);
+            if (callbacks) {
+                callbacks.delete(callback);
+                if (callbacks.size === 0) {
+                    this._changeCallbacks.delete(fingerprint);
+                }
+            }
+        };
+    }
+    /**
+     * Dispatches a cache change event to all registered callbacks for the affected
+     * fingerprint. Called by infrastructure code (e.g., {@link RedisLocalStorageProvider})
+     * when another server modifies a cached entry.
+     *
+     * For `category_cleared` events, dispatches to ALL registered callbacks whose
+     * fingerprints belong to the cleared category (matched by the event's CacheKey
+     * which contains the category name).
+     *
+     * Errors in individual callbacks are caught and logged via {@link LogError}
+     * to prevent one bad callback from blocking others.
+     *
+     * @param event - The cache change event to dispatch
+     */
+    DispatchCacheChange(event) {
+        const sourceShort = event.SourceServerId ? event.SourceServerId.substring(0, 8) : 'unknown';
+        LogStatusVerbose(`LocalCacheManager: DispatchCacheChange received — action="${event.Action}", key="${event.CacheKey}", source="${sourceShort}"`);
+        if (event.Action === 'category_cleared') {
+            // For category-level clearing, notify ALL registered callbacks
+            // since we can't know which fingerprints belong to which category
+            // without parsing them. This is a rare operation so the overhead is acceptable.
+            for (const [, callbacks] of this._changeCallbacks) {
+                for (const cb of callbacks) {
+                    try {
+                        cb(event);
+                    }
+                    catch (err) {
+                        LogError(`OnDataChanged callback error for category_cleared "${event.CacheKey}": ${err.message}`);
+                    }
+                }
+            }
+        }
+        else {
+            // For set/removed, dispatch only to callbacks for the specific fingerprint
+            const callbacks = this._changeCallbacks.get(event.CacheKey);
+            if (callbacks) {
+                for (const cb of callbacks) {
+                    try {
+                        cb(event);
+                    }
+                    catch (err) {
+                        LogError(`OnDataChanged callback error for key "${event.CacheKey}": ${err.message}`);
+                    }
+                }
+            }
+        }
+    }
+    /**
+     * Returns the number of fingerprints that have registered change callbacks.
+     * Useful for diagnostics and testing.
+     */
+    get ChangeCallbackCount() {
+        return this._changeCallbacks.size;
+    }
     // ========================================================================
     // DATASET CACHING
     // ========================================================================
@@ -275,18 +701,19 @@ export class LocalCacheManager extends BaseSingleton {
         const filter = (typeof rawFilter === 'string' ? rawFilter : rawFilter ? JSON.stringify(rawFilter) : '').trim();
         const rawOrderBy = params.OrderBy;
         const orderBy = (typeof rawOrderBy === 'string' ? rawOrderBy : rawOrderBy ? JSON.stringify(rawOrderBy) : '').trim();
-        const resultType = params.ResultType || 'simple';
+        // ResultType is intentionally excluded from the fingerprint.
+        // The cache always stores plain JSON objects regardless of ResultType.
+        // Transformation to entity objects happens post-cache at consumption time.
         const maxRows = params.MaxRows ?? -1;
         const startRow = params.StartRow ?? 0;
         const connection = connectionPrefix || '';
         const aggHash = this.generateAggregateHash(params.Aggregates);
         // Build human-readable fingerprint with pipe separators
-        // Format: Entity|Filter|OrderBy|ResultType|MaxRows|StartRow|AggHash|Connection
+        // Format: Entity|Filter|OrderBy|MaxRows|StartRow|AggHash[|Connection]
         const parts = [
             entity,
             filter || '_', // Use underscore for empty filter
             orderBy || '_', // Use underscore for empty orderBy
-            resultType,
             maxRows.toString(),
             startRow.toString(),
             aggHash // Aggregate hash (or '_' for no aggregates)
@@ -376,6 +803,9 @@ export class LocalCacheManager extends BaseSingleton {
                 maxUpdatedAt,
                 rowCount: results.length // Registry still tracks this for display/stats, derived from actual results
             });
+            // Maintain entity→fingerprint reverse index for universal cache invalidation
+            this.addToEntityIndex(fingerprint);
+            LogStatusVerbose(`LocalCacheManager.SetRunViewResult: Cached ${results.length} rows for "${fingerprint.substring(0, 60)}" (${sizeBytes} bytes)`);
         }
         catch (e) {
             LogError(`LocalCacheManager.SetRunViewResult failed: ${e}`);
@@ -426,6 +856,9 @@ export class LocalCacheManager extends BaseSingleton {
     async InvalidateRunViewResult(fingerprint) {
         if (!this._storageProvider)
             return;
+        LogStatusEx({ message: `    🗑️ [Cache INVALIDATE] fingerprint="${fingerprint}"`, verboseOnly: true });
+        // Remove from entity→fingerprint index before removing the cache entry
+        this.removeFromEntityIndex(fingerprint);
         try {
             await this._storageProvider.Remove(fingerprint, CacheCategory.RunViewCache);
             this.unregisterEntry(fingerprint);
@@ -465,32 +898,25 @@ export class LocalCacheManager extends BaseSingleton {
                 // No existing cache - can't apply differential, caller should do full fetch
                 return null;
             }
-            // Build a map of existing records by primary key for O(1) lookups
+            // Build a map of existing records by composite key string for O(1) lookups
+            const pkFieldNames = [primaryKeyFieldName];
             const resultMap = new Map();
             for (const row of cached.results) {
                 const rowObj = row;
-                const pkValue = this.extractPrimaryKeyString(rowObj, primaryKeyFieldName);
-                if (pkValue) {
-                    resultMap.set(pkValue, row);
-                }
+                const rowKey = this.buildCompositeKeyFromRow(rowObj, pkFieldNames);
+                resultMap.set(rowKey.ToConcatenatedString(), row);
             }
             // Apply deletions - remove records that have been deleted
             for (const deletedID of deletedRecordIDs) {
-                // deletedID is in CompositeKey concatenated format: "Field1|Value1||Field2|Value2"
-                // For single-field PKs, it's just "ID|abc123"
-                // We need to extract just the value(s) to match against our map
-                const pkValue = this.extractValueFromConcatenatedKey(deletedID, primaryKeyFieldName);
-                if (pkValue) {
-                    resultMap.delete(pkValue);
-                }
+                // deletedID is already in CompositeKey concatenated format: "Field1|Value1||Field2|Value2"
+                // Use it directly as the map key since ToConcatenatedString() produces the same format
+                resultMap.delete(deletedID);
             }
             // Apply updates/inserts - add or replace records
             for (const row of updatedRows) {
                 const rowObj = row;
-                const pkValue = this.extractPrimaryKeyString(rowObj, primaryKeyFieldName);
-                if (pkValue) {
-                    resultMap.set(pkValue, row);
-                }
+                const rowKey = this.buildCompositeKeyFromRow(rowObj, pkFieldNames);
+                resultMap.set(rowKey.ToConcatenatedString(), row);
             }
             // Convert map back to array
             const mergedResults = Array.from(resultMap.values());
@@ -524,54 +950,29 @@ export class LocalCacheManager extends BaseSingleton {
      * @param newMaxUpdatedAt - New maxUpdatedAt timestamp (from entity's __mj_UpdatedAt)
      * @returns true if cache was updated, false if cache not found or update failed
      */
-    async UpsertSingleEntity(fingerprint, entityData, primaryKeyFieldName, newMaxUpdatedAt) {
+    async UpsertSingleEntity(fingerprint, entityData, key, newMaxUpdatedAt) {
         if (!this._storageProvider || !this._config.enabled)
             return false;
         try {
-            // Get existing cached data
             const cached = await this.GetRunViewResult(fingerprint);
             if (!cached) {
-                // No existing cache - nothing to update
-                // The next RunView call will populate the cache
+                LogStatusVerbose(`LocalCacheManager.UpsertSingleEntity: No cached data found for fingerprint "${fingerprint.substring(0, 60)}" — skipping (cache will be populated on next RunView)`);
                 return false;
             }
-            // Get the primary key value from the entity
-            const pkValue = this.extractPrimaryKeyString(entityData, primaryKeyFieldName);
-            if (!pkValue) {
-                LogError(`LocalCacheManager.UpsertSingleEntity: Could not extract primary key from entity data`);
-                return false;
-            }
-            // Build a map of existing records by primary key
+            LogStatusVerbose(`LocalCacheManager.UpsertSingleEntity: Found cached data with ${cached.results.length} rows, updating...`);
+            const pkFieldNames = key.KeyValuePairs.map(kv => kv.FieldName);
+            const keyStr = key.ToConcatenatedString();
+            // Build a map of existing records by composite key string
             const resultMap = new Map();
             for (const row of cached.results) {
                 const rowObj = row;
-                const rowPkValue = this.extractPrimaryKeyString(rowObj, primaryKeyFieldName);
-                if (rowPkValue) {
-                    resultMap.set(rowPkValue, row);
-                }
+                const rowKey = this.buildCompositeKeyFromRow(rowObj, pkFieldNames);
+                resultMap.set(rowKey.ToConcatenatedString(), row);
             }
             // Upsert the entity (add or replace)
-            resultMap.set(pkValue, entityData);
-            // Convert map back to array
+            resultMap.set(keyStr, entityData);
             const updatedResults = Array.from(resultMap.values());
-            // Store the updated cache - rowCount is derived from results.length
-            const data = {
-                results: updatedResults,
-                maxUpdatedAt: newMaxUpdatedAt
-            };
-            const value = JSON.stringify(data);
-            const sizeBytes = this.estimateSize(value);
-            await this._storageProvider.SetItem(fingerprint, value, CacheCategory.RunViewCache);
-            // Update registry entry with derived rowCount
-            const existingEntry = this._registry.get(fingerprint);
-            if (existingEntry) {
-                existingEntry.maxUpdatedAt = newMaxUpdatedAt;
-                existingEntry.rowCount = updatedResults.length;
-                existingEntry.sizeBytes = sizeBytes;
-                existingEntry.lastAccessedAt = Date.now();
-                this.debouncedPersistRegistry();
-            }
-            return true;
+            return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt);
         }
         catch (e) {
             LogError(`LocalCacheManager.UpsertSingleEntity failed: ${e}`);
@@ -580,60 +981,36 @@ export class LocalCacheManager extends BaseSingleton {
     }
     /**
      * Removes a single entity from a cached RunView result.
-     * Used by BaseEngine for immediate cache sync when an entity is deleted.
+     * Supports composite primary keys via CompositeKey matching.
      *
      * @param fingerprint - The cache fingerprint to update
-     * @param primaryKeyValue - The primary key value of the entity to remove
-     * @param primaryKeyFieldName - Name of the primary key field
+     * @param key - CompositeKey identifying the entity to remove
      * @param newMaxUpdatedAt - New maxUpdatedAt timestamp
      * @returns true if cache was updated, false if cache not found or update failed
      */
-    async RemoveSingleEntity(fingerprint, primaryKeyValue, primaryKeyFieldName, newMaxUpdatedAt) {
+    async RemoveSingleEntity(fingerprint, key, newMaxUpdatedAt) {
         if (!this._storageProvider || !this._config.enabled)
             return false;
         try {
-            // Get existing cached data
             const cached = await this.GetRunViewResult(fingerprint);
             if (!cached) {
-                // No existing cache - nothing to update
                 return false;
             }
-            // Build a map of existing records by primary key
+            const pkFieldNames = key.KeyValuePairs.map(kv => kv.FieldName);
+            const keyStr = key.ToConcatenatedString();
+            // Build a map of existing records by composite key string
             const resultMap = new Map();
             for (const row of cached.results) {
                 const rowObj = row;
-                const rowPkValue = this.extractPrimaryKeyString(rowObj, primaryKeyFieldName);
-                if (rowPkValue) {
-                    resultMap.set(rowPkValue, row);
-                }
+                const rowKey = this.buildCompositeKeyFromRow(rowObj, pkFieldNames);
+                resultMap.set(rowKey.ToConcatenatedString(), row);
             }
-            // Check if entity exists in cache
-            if (!resultMap.has(primaryKeyValue)) {
-                // Entity not in cache, nothing to remove
-                return true; // Not an error, just a no-op
+            if (!resultMap.has(keyStr)) {
+                return true; // Not in cache, no-op
             }
-            // Remove the entity
-            resultMap.delete(primaryKeyValue);
-            // Convert map back to array
+            resultMap.delete(keyStr);
             const updatedResults = Array.from(resultMap.values());
-            // Store the updated cache - rowCount is derived from results.length
-            const data = {
-                results: updatedResults,
-                maxUpdatedAt: newMaxUpdatedAt
-            };
-            const value = JSON.stringify(data);
-            const sizeBytes = this.estimateSize(value);
-            await this._storageProvider.SetItem(fingerprint, value, CacheCategory.RunViewCache);
-            // Update registry entry with derived rowCount
-            const existingEntry = this._registry.get(fingerprint);
-            if (existingEntry) {
-                existingEntry.maxUpdatedAt = newMaxUpdatedAt;
-                existingEntry.rowCount = updatedResults.length;
-                existingEntry.sizeBytes = sizeBytes;
-                existingEntry.lastAccessedAt = Date.now();
-                this.debouncedPersistRegistry();
-            }
-            return true;
+            return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt);
         }
         catch (e) {
             LogError(`LocalCacheManager.RemoveSingleEntity failed: ${e}`);
@@ -641,51 +1018,26 @@ export class LocalCacheManager extends BaseSingleton {
         }
     }
     /**
-     * Extracts the primary key value as a string from a row object.
-     * Handles both single-field and composite primary keys.
-     * @param row - The row object
-     * @param primaryKeyFieldName - The primary key field name (first field for composite keys)
-     * @returns The primary key value as a string, or null if not found
-     */
-    extractPrimaryKeyString(row, primaryKeyFieldName) {
-        const value = row[primaryKeyFieldName];
-        if (value === null || value === undefined) {
-            return null;
-        }
-        return String(value);
-    }
-    /**
-     * Extracts the primary key value from a CompositeKey concatenated string.
-     * Format: "Field1|Value1||Field2|Value2" for composite keys, or "ID|abc123" for single keys.
-     * @param concatenatedKey - The concatenated key string from RecordChange.RecordID
-     * @param primaryKeyFieldName - The primary key field name to extract
-     * @returns The value for the specified field, or the first value if field not found
+     * Stores updated results array back to the cache and updates the registry.
+     * Shared by UpsertSingleEntity and RemoveSingleEntity to avoid duplication.
      */
-    extractValueFromConcatenatedKey(concatenatedKey, primaryKeyFieldName) {
-        if (!concatenatedKey) {
-            return null;
-        }
-        // Split by field delimiter (||)
-        const fieldPairs = concatenatedKey.split('||');
-        for (const pair of fieldPairs) {
-            // Split by value delimiter (|)
-            const parts = pair.split('|');
-            if (parts.length >= 2) {
-                const fieldName = parts[0];
-                const value = parts.slice(1).join('|'); // Rejoin in case value contained |
-                if (fieldName === primaryKeyFieldName) {
-                    return value;
-                }
-            }
-        }
-        // If field name not found, return the first value (fallback for simple keys)
-        if (fieldPairs.length > 0) {
-            const parts = fieldPairs[0].split('|');
-            if (parts.length >= 2) {
-                return parts.slice(1).join('|');
-            }
+    async storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt) {
+        const data = {
+            results: updatedResults,
+            maxUpdatedAt: newMaxUpdatedAt
+        };
+        const value = JSON.stringify(data);
+        const sizeBytes = this.estimateSize(value);
+        await this._storageProvider.SetItem(fingerprint, value, CacheCategory.RunViewCache);
+        const existingEntry = this._registry.get(fingerprint);
+        if (existingEntry) {
+            existingEntry.maxUpdatedAt = newMaxUpdatedAt;
+            existingEntry.rowCount = updatedResults.length;
+            existingEntry.sizeBytes = sizeBytes;
+            existingEntry.lastAccessedAt = Date.now();
+            this.debouncedPersistRegistry();
         }
-        return null;
+        return true;
     }
     /**
      * Invalidates all cached RunView results for a specific entity.
@@ -703,6 +1055,9 @@ export class LocalCacheManager extends BaseSingleton {
                 toRemove.push(key);
             }
         }
+        if (toRemove.length > 0) {
+            LogStatusEx({ message: `    🗑️ [Cache INVALIDATE-ENTITY] "${entityName}" — removing ${toRemove.length} entries: ${toRemove.map(k => `"${k}"`).join(', ')}`, verboseOnly: true });
+        }
         for (const key of toRemove) {
             try {
                 await this._storageProvider.Remove(key, CacheCategory.RunViewCache);
@@ -1055,6 +1410,13 @@ export class LocalCacheManager extends BaseSingleton {
             if (stored) {
                 const parsed = JSON.parse(stored);
                 this._registry = new Map(parsed.map(e => [e.key, e]));
+                // Rebuild entity→fingerprint reverse index from persisted registry
+                // so that BaseEntity events can find cached entries after a server restart
+                for (const entry of this._registry.values()) {
+                    if (entry.fingerprint) {
+                        this.addToEntityIndex(entry.fingerprint);
+                    }
+                }
             }
         }
         catch (e) {
@@ -1138,6 +1500,9 @@ export class LocalCacheManager extends BaseSingleton {
             freedBytes += entry.sizeBytes;
             freedCount++;
         }
+        if (toDelete.length > 0) {
+            LogStatusEx({ message: `    🗑️ [Cache EVICT] Evicting ${toDelete.length} entries to free ${freedBytes} bytes: ${toDelete.map(k => `"${k}"`).join(', ')}`, verboseOnly: true });
+        }
         for (const key of toDelete) {
             try {
                 const entry = this._registry.get(key);
@@ -1146,6 +1511,10 @@ export class LocalCacheManager extends BaseSingleton {
                 if (entry?.type === 'dataset') {
                     await this._storageProvider.Remove(key + '_date', category);
                 }
+                // Clean up entity→fingerprint index for evicted entries
+                if (entry?.fingerprint) {
+                    this.removeFromEntityIndex(entry.fingerprint);
+                }
                 this._registry.delete(key);
             }
             catch (e) {