@memberjunction/core 6.1.5 → 6.1.6

package/dist/generic/localCacheManager.js

@@ -118,6 +118,11 @@ export class LocalCacheManager extends BaseSingleton {
     static get Instance() {
         return super.getInstance();
     }
+    /**
+     * How often, at most, a process writes an entity's shared slots while it keeps finding that
+     * entity's slots under a schema different from its own. See {@link handleSchemaMismatch}.
+     */
+    static { this.SCHEMA_MISMATCH_WRITE_INTERVAL_MS = 60_000; }
     constructor() {
         super();
         this._storageProvider = null;
@@ -139,6 +144,14 @@ export class LocalCacheManager extends BaseSingleton {
          * (e.g., TransactionGroup batch deletes).
          */
         this._fingerprintLocks = new Map();
+        /**
+         * Write holds on entities whose shared slots were found under a different schema, keyed by
+         * lowercased entity name. While a hold applies, {@link SetRunViewResult} skips or rate-limits
+         * writes of that entity's slots. See {@link handleSchemaMismatch} and {@link mayWriteUnderSchemaHold}.
+         */
+        this._schemaWriteHolds = new Map();
+        /** Schema mismatches already reported, so each entity/hash pair is logged once per process. */
+        this._reportedSchemaMismatches = new Set();
         this.REGISTRY_KEY = '__MJ_CACHE_REGISTRY__';
         /**
          * Reverse index from entity name to the set of RunView cache fingerprints
@@ -540,30 +553,134 @@ export class LocalCacheManager extends BaseSingleton {
         return Number.isFinite(startRow) && startRow > 0;
     }
     /**
-     * Checks whether a cached RunView entry is structurally stale due to a schema change
-     * (e.g., new columns added via migration + CodeGen). Compares the stored schema hash
-     * against the current entity field list. If they differ, the entry is invalidated.
+     * Compares a cached RunView entry's schema hash against this process's current field list for
+     * the entity (a mismatch follows a migration + CodeGen that added, removed or reordered
+     * columns). Entries without a hash, and entities this process cannot resolve, never mismatch.
      * @param fingerprint - The cache fingerprint
      * @param data - The cached data to validate
-     * @returns true if the entry is stale and should not be served
+     * @returns The mismatch, or null when the entry may be served
      */
-    isSchemaStaleCacheEntry(fingerprint, data) {
+    findSchemaMismatch(fingerprint, data) {
         if (!data.schemaHash)
-            return false;
+            return null;
         const entityName = this.extractEntityFromFingerprint(fingerprint);
         if (!entityName)
+            return null;
+        const current = this.computeSchemaSignature(undefined, entityName);
+        if (!current || current.Hash === data.schemaHash)
+            return null;
+        return {
+            EntityName: entityName,
+            CachedHash: data.schemaHash,
+            Current: current,
+            EntryIsNewer: LocalCacheManager.isNewerSchemaStamp(data.schemaStamp, current.Stamp),
+        };
+    }
+    /**
+     * True only when both stamps are present and the cached entry's is strictly newer than this
+     * process's. Equal or missing stamps leave the order unknown, which counts as not newer.
+     */
+    static isNewerSchemaStamp(entryStamp, currentStamp) {
+        if (!entryStamp || !currentStamp) {
             return false;
-        const currentHash = this.ComputeSchemaHash(undefined, entityName);
-        if (!currentHash)
-            return false;
-        if (currentHash !== data.schemaHash) {
-            LogStatusEx({
-                message: `[CACHE-SCHEMA-STALE] Entity "${entityName}" schema changed (cached=${data.schemaHash}, current=${currentHash})`,
-                verboseOnly: false
+        }
+        return LocalCacheManager.timestampMs(entryStamp) > LocalCacheManager.timestampMs(currentStamp);
+    }
+    /**
+     * Decides what a schema mismatch does to the slot. The entry is never served; the question is
+     * whether the slot is deleted, which on a shared store also tells every peer to reload.
+     *
+     * - Process-local store, or a slot-maintenance read: delete it. No other process reads a local
+     *   store. A maintenance read happens because a row changed, and a slot that cannot take the
+     *   change in place must go, whichever process wrote it.
+     * - Shared store, serving read: leave it, and hold back this process's writes of the entity.
+     *   Deleting publishes `removed`, every peer engine holding the slot reloads and rewrites it
+     *   under its own hash, and processes on either side of a migration keep doing that to each
+     *   other. The caller reads the database instead.
+     *   - When the slot is known to come from newer metadata, this process is the one out of date.
+     *     It stops writing the entity's slots until its own metadata changes.
+     *   - Otherwise it writes the entity's slots at most once per
+     *     {@link SCHEMA_MISMATCH_WRITE_INTERVAL_MS} while mismatches keep appearing. That still
+     *     replaces a slot left by older metadata, but a peer running code that deletes mismatched
+     *     slots (any release before this check stopped deleting them) gets one slot to delete per
+     *     interval instead of one per read. The hold lapses after an interval with no mismatch.
+     */
+    handleSchemaMismatch(fingerprint, mismatch, purpose) {
+        const shared = this._storageProvider?.SharedAcrossProcesses === true;
+        if (!shared || purpose === 'maintain') {
+            this.reportSchemaMismatch(mismatch, 'dropping the slot');
+            this.InvalidateRunViewResult(fingerprint).catch(() => { });
+            return;
+        }
+        this.holdSchemaWrites(mismatch);
+        if (mismatch.EntryIsNewer) {
+            this.reportSchemaMismatch(mismatch, 'another process wrote the slot under newer metadata. This process reads the entity from the database ' +
+                'and stops writing its cache slots until its metadata changes. If it started before a migration, restart it.');
+        }
+        else {
+            this.reportSchemaMismatch(mismatch, `reading from the database. While slots under other metadata keep appearing, this process writes the entity's ` +
+                `slots at most once every ${LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS / 1000}s.`);
+        }
+    }
+    /** Records or extends the write hold for a mismatch seen on a shared store. */
+    holdSchemaWrites(mismatch) {
+        const key = mismatch.EntityName.trim().toLowerCase();
+        const now = Date.now();
+        const existing = this._schemaWriteHolds.get(key);
+        if (mismatch.EntryIsNewer) {
+            this._schemaWriteHolds.set(key, { OwnHash: mismatch.Current.Hash, NextWriteAt: Number.POSITIVE_INFINITY, LastMismatchAt: now });
+        }
+        else if (existing && existing.OwnHash === mismatch.Current.Hash) {
+            existing.LastMismatchAt = now;
+        }
+        else {
+            this._schemaWriteHolds.set(key, {
+                OwnHash: mismatch.Current.Hash,
+                NextWriteAt: now + LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS,
+                LastMismatchAt: now,
             });
+        }
+    }
+    /** Logs a schema mismatch once per entity and hash pair per process. */
+    reportSchemaMismatch(mismatch, outcome) {
+        const key = `${mismatch.EntityName.trim().toLowerCase()}|${mismatch.CachedHash}|${mismatch.Current.Hash}`;
+        if (this._reportedSchemaMismatches.has(key)) {
+            return;
+        }
+        this._reportedSchemaMismatches.add(key);
+        LogStatusEx({
+            message: `[CACHE-SCHEMA-STALE] Entity "${mismatch.EntityName}" schema differs from a cached slot ` +
+                `(cached=${mismatch.CachedHash}, current=${mismatch.Current.Hash}) — ${outcome}`,
+            verboseOnly: false
+        });
+    }
+    /**
+     * Whether a slot of `entityName` may be written now, given the entity's write hold (see
+     * {@link handleSchemaMismatch}). A permitted write under a rate-limiting hold uses up the
+     * interval. The hold is dropped once this process's schema hash changes (a metadata refresh)
+     * or, for a rate-limiting hold, once an interval passes with no mismatch.
+     */
+    mayWriteUnderSchemaHold(entityName, currentHash) {
+        if (this._storageProvider?.SharedAcrossProcesses !== true) {
             return true;
         }
-        return false;
+        const key = entityName.trim().toLowerCase();
+        const hold = this._schemaWriteHolds.get(key);
+        if (!hold) {
+            return true;
+        }
+        const now = Date.now();
+        const interval = LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS;
+        const lapsed = hold.NextWriteAt !== Number.POSITIVE_INFINITY && now - hold.LastMismatchAt > interval;
+        if (hold.OwnHash !== currentHash || lapsed) {
+            this._schemaWriteHolds.delete(key);
+            return true;
+        }
+        if (now < hold.NextWriteAt) {
+            return false;
+        }
+        hold.NextWriteAt = now + interval;
+        return true;
     }
     /**
      * Adds a fingerprint to the entity→fingerprint reverse index.
@@ -602,21 +719,26 @@ export class LocalCacheManager extends BaseSingleton {
         return this._entityFingerprintIndex.get(entityName) ?? new Set();
     }
     /**
-     * Resolves cached fingerprints for an entity, checking the local in-memory
-     * index first and falling back to the shared storage provider (e.g., Redis)
-     * when the local index is empty. This handles cross-server scenarios where
-     * Server A cached RunView results and Server B saves a record — Server B's
-     * local index is empty but Redis still has the stale cached entries.
+     * Resolves cached fingerprints for an entity: this process's own index, plus the slots the
+     * storage provider lists for the entity.
+     *
+     * On a provider shared between processes (e.g. Redis) the provider is listed on every call
+     * and merged into the local index. The local index only knows slots this process wrote, so
+     * answering from it alone would miss slots other processes wrote — including a slot this
+     * process only read warm at boot — and a save here would never reach the engines that load
+     * from those slots on its peers.
+     *
+     * On a process-local provider (e.g. IndexedDB) the category is listed only when the local
+     * index knows nothing for the entity, which picks up slots persisted by an earlier session.
      */
     async resolveFingerprintsForEntity(entityName) {
+        if (this._storageProvider?.SharedAcrossProcesses === true && this._storageProvider.GetCategoryKeys) {
+            return this.resolveFingerprintsFromSharedStore(entityName);
+        }
         const local = this._entityFingerprintIndex.get(entityName);
         if (local && local.size > 0)
             return local;
-        if (!this._storageProvider?.GetCategoryKeys)
-            return undefined;
-        const allKeys = await this._storageProvider.GetCategoryKeys(CacheCategory.RunViewCache);
-        const entityPrefix = entityName + '|';
-        const remoteFingerprints = allKeys.filter(k => k.startsWith(entityPrefix));
+        const remoteFingerprints = await this.listStoredFingerprintsForEntity(entityName);
         if (remoteFingerprints.length > 0) {
             LogStatusVerbose(`LocalCacheManager: found ${remoteFingerprints.length} remote cached fingerprint(s) for "${entityName}" via storage provider`);
             const result = new Set(remoteFingerprints);
@@ -628,6 +750,26 @@ export class LocalCacheManager extends BaseSingleton {
         }
         return undefined;
     }
+    /**
+     * Merges the slots a shared store lists for the entity into the local index and returns the
+     * union. Local entries the store does not list are left in place; invalidation removes them
+     * from the index the same way it does for any other slot.
+     */
+    async resolveFingerprintsFromSharedStore(entityName) {
+        for (const fp of await this.listStoredFingerprintsForEntity(entityName)) {
+            this.addToEntityIndex(fp);
+        }
+        const merged = this._entityFingerprintIndex.get(entityName);
+        return merged && merged.size > 0 ? merged : undefined;
+    }
+    /** Lists the RunView slots the storage provider holds for an entity; empty when it cannot list keys. */
+    async listStoredFingerprintsForEntity(entityName) {
+        if (!this._storageProvider?.GetCategoryKeys)
+            return [];
+        const allKeys = await this._storageProvider.GetCategoryKeys(CacheCategory.RunViewCache);
+        const entityPrefix = entityName + '|';
+        return allKeys.filter(k => k.startsWith(entityPrefix));
+    }
     // ========================================================================
     // UNIVERSAL CACHE INVALIDATION (BaseEntity Events)
     // ========================================================================
@@ -1446,6 +1588,14 @@ export class LocalCacheManager extends BaseSingleton {
      * @returns The schema hash string, or undefined if the entity can't be resolved
      */
     ComputeSchemaHash(provider, entityName) {
+        return this.computeSchemaSignature(provider, entityName)?.Hash;
+    }
+    /**
+     * The entity's schema hash (see {@link ComputeSchemaHash}) together with its schema stamp: the
+     * newest `__mj_UpdatedAt` across the entity row and its field rows, as an ISO string, or
+     * undefined when the metadata carries no timestamps.
+     */
+    computeSchemaSignature(provider, entityName) {
         try {
             const md = provider ?? new Metadata();
             const entity = md.EntityByName(entityName);
@@ -1454,12 +1604,27 @@ export class LocalCacheManager extends BaseSingleton {
             // Use natural sequence order (EntityInfo.Fields is sorted by Sequence).
             // This detects field additions, removals, AND reorderings.
             const fieldNames = entity.Fields.map(f => f.Name).join('|');
-            return this.simpleHash(fieldNames);
+            let newest = LocalCacheManager.timestampMs(entity.__mj_UpdatedAt);
+            for (const field of entity.Fields) {
+                newest = Math.max(newest, LocalCacheManager.timestampMs(field.__mj_UpdatedAt));
+            }
+            return {
+                Hash: this.simpleHash(fieldNames),
+                Stamp: newest > 0 ? new Date(newest).toISOString() : undefined,
+            };
         }
         catch {
             return undefined;
         }
     }
+    /** Milliseconds since the epoch for a metadata timestamp (a Date or a string), or 0 when unreadable. */
+    static timestampMs(value) {
+        if (value == null) {
+            return 0;
+        }
+        const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+        return Number.isNaN(ms) ? 0 : ms;
+    }
     /**
      * Deep-freezes an about-to-be-stored cache payload when — and only when — the active
      * storage provider hands out live object references
@@ -1609,9 +1774,16 @@ export class LocalCacheManager extends BaseSingleton {
         }
         // Compute and store schema hash for upgrade detection
         if (params.EntityName) {
-            const schemaHash = this.ComputeSchemaHash(provider, params.EntityName);
-            if (schemaHash) {
-                data.schemaHash = schemaHash;
+            const signature = this.computeSchemaSignature(provider, params.EntityName);
+            if (signature) {
+                if (!this.mayWriteUnderSchemaHold(params.EntityName, signature.Hash)) {
+                    LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for "${params.EntityName}" — its shared slots were found under different metadata`, verboseOnly: true });
+                    return;
+                }
+                data.schemaHash = signature.Hash;
+                if (signature.Stamp) {
+                    data.schemaStamp = signature.Stamp;
+                }
             }
         }
         // Estimate size by sampling rows (eviction accounting only); the actual stored
@@ -1626,9 +1798,9 @@ export class LocalCacheManager extends BaseSingleton {
             LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for "${params.EntityName || fingerprint.substring(0, 60)}" — estimated entry size ${sizeBytes} bytes exceeds per-entry cap (${this._config.maxEntryPercentOfCache}% of ${this._config.maxSizeBytes} byte budget)` });
             return;
         }
-        // The oversized gate above is the ONLY step that can decline this write, and it is
-        // synchronous — so by here the row set is definitely becoming shared state, and it is
-        // frozen with no intervening yield point. That ordering is load-bearing: the eviction
+        // The schema gate and the oversized gate above are the ONLY steps that can decline this
+        // write, and they are synchronous — so by here the row set is definitely becoming shared
+        // state, and it is frozen with no intervening yield point. That ordering is load-bearing: the eviction
         // steps below are awaited, and callers hold this very array while they run (the
         // smart-cache stale leg does not await this method at all). Freezing after them leaves
         // a window in which shared rows are handed out still mutable — and `BaseEntity`
@@ -1685,12 +1857,16 @@ export class LocalCacheManager extends BaseSingleton {
      * @returns The cached results, maxUpdatedAt, rowCount (derived), and aggregateResults, or null if not found
      */
     async GetRunViewResult(fingerprint) {
+        return this.readRunViewSlot(fingerprint, 'serve');
+    }
+    /** {@link GetRunViewResult} for a given purpose; in-place slot maintenance reads with `'maintain'`. */
+    async readRunViewSlot(fingerprint, purpose) {
         if (!this._storageProvider || !this._config.enabled)
             return null;
         try {
             // Native object read — IDB structured-clones the result back, no JSON.parse needed.
             const parsed = await this._storageProvider.GetItem(fingerprint, CacheCategory.RunViewCache);
-            return this.materializeCachedRunViewResult(fingerprint, parsed);
+            return this.materializeCachedRunViewResult(fingerprint, parsed, purpose);
         }
         catch (e) {
             LogError(`LocalCacheManager.GetRunViewResult failed: ${e}`);
@@ -1730,7 +1906,7 @@ export class LocalCacheManager extends BaseSingleton {
         try {
             const raw = await this._storageProvider.GetItems(fingerprints, CacheCategory.RunViewCache);
             for (const [fp, parsed] of raw) {
-                out.set(fp, this.materializeCachedRunViewResult(fp, parsed));
+                out.set(fp, this.materializeCachedRunViewResult(fp, parsed, 'serve'));
             }
             return out;
         }
@@ -1753,7 +1929,7 @@ export class LocalCacheManager extends BaseSingleton {
      * cache entries after schema migrations. If the entity's field list changed
      * since the entry was cached, the entry is invalidated and null is returned.
      */
-    materializeCachedRunViewResult(fingerprint, parsed) {
+    materializeCachedRunViewResult(fingerprint, parsed, purpose) {
         if (!parsed) {
             this._stats.misses++;
             return null;
@@ -1767,8 +1943,9 @@ export class LocalCacheManager extends BaseSingleton {
             this._stats.misses++;
             return null;
         }
-        if (this.isSchemaStaleCacheEntry(fingerprint, parsed)) {
-            this.InvalidateRunViewResult(fingerprint).catch(() => { });
+        const schemaMismatch = this.findSchemaMismatch(fingerprint, parsed);
+        if (schemaMismatch) {
+            this.handleSchemaMismatch(fingerprint, schemaMismatch, purpose);
             this._stats.misses++;
             return null;
         }
@@ -1782,6 +1959,7 @@ export class LocalCacheManager extends BaseSingleton {
             totalRowCount: parsed.totalRowCount,
             // Surfaced so in-place maintenance can carry it forward on rewrite (B38).
             schemaHash: parsed.schemaHash,
+            schemaStamp: parsed.schemaStamp,
             // Same carry-forward rationale: a maintained scaffolding slot must stay exempt.
             providerInternalScaffolding: parsed.providerInternalScaffolding,
         };
@@ -1978,7 +2156,7 @@ export class LocalCacheManager extends BaseSingleton {
             return false;
         return this.withFingerprintLock(fingerprint, async () => {
             try {
-                const cached = await this.GetRunViewResult(fingerprint);
+                const cached = await this.readRunViewSlot(fingerprint, 'maintain');
                 if (!cached) {
                     LogStatusVerbose(`LocalCacheManager.UpsertSingleEntity: No cached data found for fingerprint "${fingerprint.substring(0, 60)}" — skipping (cache will be populated on next RunView)`);
                     return false;
@@ -1999,7 +2177,7 @@ export class LocalCacheManager extends BaseSingleton {
                 // Upsert the entity (add or replace)
                 resultMap.set(keyStr, entityData);
                 const updatedResults = Array.from(resultMap.values());
-                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash,
+                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash, schemaStamp: cached.schemaStamp,
                     providerInternalScaffolding: cached.providerInternalScaffolding });
             }
             catch (e) {
@@ -2022,7 +2200,7 @@ export class LocalCacheManager extends BaseSingleton {
             return false;
         return this.withFingerprintLock(fingerprint, async () => {
             try {
-                const cached = await this.GetRunViewResult(fingerprint);
+                const cached = await this.readRunViewSlot(fingerprint, 'maintain');
                 if (!cached) {
                     return false;
                 }
@@ -2042,7 +2220,7 @@ export class LocalCacheManager extends BaseSingleton {
                 }
                 resultMap.delete(keyStr);
                 const updatedResults = Array.from(resultMap.values());
-                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash,
+                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash, schemaStamp: cached.schemaStamp,
                     providerInternalScaffolding: cached.providerInternalScaffolding });
             }
             catch (e) {
@@ -2084,6 +2262,9 @@ export class LocalCacheManager extends BaseSingleton {
         if (prior?.schemaHash) {
             data.schemaHash = prior.schemaHash;
         }
+        if (prior?.schemaStamp) {
+            data.schemaStamp = prior.schemaStamp;
+        }
         // Carry the freeze exemption forward too — a scaffolding slot that gets maintained in
         // place must not silently become frozen, or the owner that mutates those rows breaks on
         // the next read (for the metadata dataset that means booting with no metadata).