@memberjunction/core 6.2.0-edge.6 → 6.2.0-edge.7

package/dist/generic/baseEngine.js

@@ -14,7 +14,7 @@ import { BaseEngineRegistry } from "./baseEngineRegistry.js";
 import { LocalCacheManager } from "./localCacheManager.js";
 import { ProviderBase } from "./providerBase.js";
 import { DatabaseProviderBase } from "./databaseProviderBase.js";
-import { TransformSimpleObjectToEntityObject } from "./util.js";
+import { TransformSimpleObjectToEntityObject, CanonicalPrimaryKeyValue } from "./util.js";
 import { WellKnownUserSource } from "./wellKnownUserSource.js";
 /**
  * Property configuration for the BaseEngine class to automatically load/set properties on the class.
@@ -127,6 +127,21 @@ export class BaseEngine extends BaseSingleton {
         });
         return this._derivedStateRebuild;
     }
+    /**
+     * The least time, in milliseconds, between the end of one reload from
+     * {@link reloadAfterExternalChange} and the start of the next for the same property. A change
+     * that arrives after this long since the last reload reloads at once; one that arrives sooner
+     * (including while a reload is running) waits out the rest of it, and every change that arrives
+     * meanwhile shares that one reload.
+     *
+     * Without it, a steady stream of changes (a server writing rows of one entity a few times a
+     * second) keeps a property reloading back to back. Each full reload costs time proportional to
+     * the table, so the process spends most of its time reloading and the cost of the stream grows
+     * with the square of its length. With it, a property reloads at most once per this delay plus
+     * one reload's duration, and its data is never more than that far behind the last change.
+     * 0 restores back-to-back reloads.
+     */
+    static { this.ExternalChangeFollowUpDelayMs = 1000; }
     /**
      * Returns an Observable for a specific engine array property. Subscribers receive the
      * current array immediately (BehaviorSubject semantics), then re-receive the same array
@@ -199,11 +214,25 @@ export class BaseEngine extends BaseSingleton {
          */
         this._configRefreshGeneration = new Map();
         /**
-         * Reloads started by {@link OnExternalCacheChange}, keyed by config PropertyName. While one is
-         * running, further events for that property set `Again` instead of starting another, so a
-         * burst of peer events costs at most two reloads per property. See {@link reloadAfterExternalChange}.
+         * Reloads started by {@link OnExternalCacheChange} and by the no-row fallback of
+         * {@link HandleRemoteInvalidateEvent}, keyed by config PropertyName. While one is running,
+         * further events for that property set `Again` instead of starting another, so a burst of
+         * events costs at most two reloads per property. See {@link reloadAfterExternalChange}.
          */
         this._externalChangeReloads = new Map();
+        /**
+         * Per-property count of in-flight full refreshes (`LoadSingleEntityConfig` or full `'set'`
+         * cache payload materialization). When positive, incoming `row_delta` events defer to a
+         * coalesced full reload rather than racing an in-progress snapshot replacement.
+         */
+        this._inFlightFullRefreshCount = new Map();
+        /**
+         * Per-property promise chain serializing `row_delta` applications so back-to-back row deltas
+         * for distinct rows apply in arrival order without dropping earlier mutations.
+         */
+        this._rowDeltaQueues = new Map();
+        /** When the last reload from {@link reloadAfterExternalChange} ended, per config PropertyName (epoch ms). */
+        this._externalChangeReloadEndedAt = new Map();
         this._entityEventDebounceTime = 1500; // Default debounce time in milliseconds (1.5 seconds)
         this._eventRefreshRetryTimers = new Map();
         /**
@@ -769,9 +798,7 @@ export class BaseEngine extends BaseSingleton {
             if (!entityName) {
                 return true; // No entity name, nothing to do
             }
-            const matchingConfigs = this._metadataConfigs.filter((config) => {
-                return config.AutoRefresh && config.EntityName && config.EntityName.trim().toLowerCase() === entityName;
-            });
+            const matchingConfigs = this.AutoRefreshConfigsForEntity(entityName);
             if (matchingConfigs.length === 0) {
                 return true;
             }
@@ -794,22 +821,9 @@ export class BaseEngine extends BaseSingleton {
                 }
                 // Fall through to server fetch if direct delete failed
             }
-            // Fallback: re-fetch from server (missing data or apply failure). Bypass the cache
-            // for the same reason as the local-event path: this fetch runs BECAUSE a
-            // (cross-server) write signaled the cache stale, so reading back through it would
-            // re-sync the pre-write snapshot.
-            let refreshCount = 0;
+            // Fallback: re-fetch from the server (no row, or it could not be applied).
             for (const config of matchingConfigs) {
-                await this.LoadSingleConfig(config, this._contextUser, /*bypassCache*/ true);
-                if (!this.configLoadedSuccessfully(config.PropertyName)) {
-                    // Same one-shot hazard as the debounced path: the invalidation event is
-                    // consumed, so a transient failure here needs a bounded retry too.
-                    this.scheduleEventRefreshRetry(config, 1);
-                }
-                refreshCount++;
-            }
-            if (refreshCount > 0) {
-                await this.AdditionalLoading(this._contextUser);
+                await this.reloadAfterRemoteInvalidate(config);
             }
             return true;
         }
@@ -818,6 +832,38 @@ export class BaseEngine extends BaseSingleton {
             return false;
         }
     }
+    /**
+     * Reloads one config because a remote-invalidate event said it changed but carried no row to
+     * apply. A burst of such events shares reloads (see {@link reloadAfterExternalChange}), so a
+     * server that saves many rows of one entity costs this engine at most two reloads per burst
+     * instead of one per row, and the reload that runs last began after the last event arrived.
+     *
+     * The reload reads past the cache: it runs because a write elsewhere made the cached copy
+     * stale, and reading back through the cache would restore the pre-write snapshot. A transient
+     * failure gets the bounded retry, since the event that asked for this reload is consumed.
+     */
+    async reloadAfterRemoteInvalidate(config) {
+        let succeeded;
+        try {
+            await this.reloadAfterExternalChange(config, /*bypassCache*/ true);
+            succeeded = this.configLoadedSuccessfully(config.PropertyName);
+        }
+        catch (e) {
+            LogError(e);
+            succeeded = false;
+        }
+        if (!succeeded) {
+            this.scheduleEventRefreshRetry(config, 1);
+        }
+    }
+    /**
+     * The entity configs that refresh automatically when a record of `entityName` changes.
+     * Matching ignores case and surrounding whitespace.
+     */
+    AutoRefreshConfigsForEntity(entityName) {
+        const name = entityName.trim().toLowerCase();
+        return this._metadataConfigs.filter((config) => config.AutoRefresh && config.EntityName && config.EntityName.trim().toLowerCase() === name);
+    }
     /**
      * Applies record data from a remote-invalidate event directly to the engine's in-memory arrays.
      * Creates a BaseEntity instance, loads the JSON data into it, then updates the matching
@@ -1549,16 +1595,15 @@ export class BaseEngine extends BaseSingleton {
      */
     async LoadConfigs(configs, contextUser, bypassCache = false) {
         this._metadataConfigs = configs.map(c => this.UpgradeObjectToConfig(c));
-        // now, break up the configs into two chunks, datasets and views of entities so we can load all the views in a single network call via RunViews()
         const entityConfigs = this._metadataConfigs.filter(c => c.Type === 'entity');
-        const datasetConfigs = this._metadataConfigs.filter(c => c.Type === 'dataset');
         this.WarnAboutFieldSecuredEntities(entityConfigs);
-        // All-or-nothing permission check: if the user lacks read access on ANY
-        // entity config, skip ALL entity configs for this engine. Returns the
-        // original array unchanged when permissions pass, or an empty array when
-        // any entity is denied (marking the engine as permission-constrained).
-        const entityConfigsToLoad = this.CheckPermissionsOrSkipAll(entityConfigs, contextUser);
-        await Promise.all([...datasetConfigs.map(c => this.LoadSingleDatasetConfig(c, contextUser, bypassCache)),
+        // All-or-nothing permission check across all configs (both entity configs and
+        // dataset configs that declare their constituent Entities). If the user lacks
+        // read access on ANY configured entity, skip ALL configs for this engine.
+        const configsToLoad = this.CheckPermissionsOrSkipAll(this._metadataConfigs, contextUser);
+        const entityConfigsToLoad = configsToLoad.filter(c => c.Type === 'entity');
+        const datasetConfigsToLoad = configsToLoad.filter(c => c.Type === 'dataset');
+        await Promise.all([...datasetConfigsToLoad.map(c => this.LoadSingleDatasetConfig(c, contextUser, bypassCache)),
             this.LoadMultipleEntityConfigs(entityConfigsToLoad, contextUser, bypassCache)]);
         // Register cross-server cache change callbacks for entity configs
         this.RegisterCacheChangeCallbacks(entityConfigs);
@@ -1613,16 +1658,14 @@ export class BaseEngine extends BaseSingleton {
         const missingEntities = this.findMissingEntities(configs);
         if (missingEntities.length > 0) {
             LogStatusEx({
-                message: `${this.constructor.name}: Skipping ${configs.length} entity config(s) — entity metadata not installed for: ${missingEntities.join(', ')}`,
+                message: `${this.constructor.name}: Skipping ${configs.length} config(s) — entity metadata not installed for: ${missingEntities.join(', ')}`,
                 verboseOnly: true,
                 category: 'Cache',
             });
             for (const config of configs) {
-                if (config.AddToObject !== false) {
-                    this[config.PropertyName] = [];
-                }
+                this.initializeSkippedConfigProperty(config);
                 this._dataMap.set(config.PropertyName, {
-                    entityName: config.EntityName,
+                    ...(config.Type === 'dataset' ? { datasetName: config.DatasetName } : { entityName: config.EntityName }),
                     data: [],
                     loadedSuccessfully: true,
                 });
@@ -1636,17 +1679,15 @@ export class BaseEngine extends BaseSingleton {
             return configs; // Can't check without a user — proceed with normal loading
         const deniedEntities = this.findUnreadableEntities(configs, user);
         if (deniedEntities.length > 0) {
-            LogWarning(`${this.constructor.name}: Skipping ${configs.length} entity config(s) — user ${user.Email} lacks read permission on: ${deniedEntities.join(', ')}`, 'Cache');
-            // Mark all entity configs as successfully loaded with empty data.
+            LogWarning(`${this.constructor.name}: Skipping ${configs.length} config(s) — user ${user.Email} lacks read permission on: ${deniedEntities.join(', ')}`, 'Cache');
+            // Mark all configs as successfully loaded with empty data.
             // This is not a failure — it's expected behavior for limited-permission users.
             // Marking as successful allows the engine to set _loaded = true and avoid
             // endless retry loops from EnsureLoaded().
             for (const config of configs) {
-                if (config.AddToObject !== false) {
-                    this[config.PropertyName] = [];
-                }
+                this.initializeSkippedConfigProperty(config);
                 this._dataMap.set(config.PropertyName, {
-                    entityName: config.EntityName,
+                    ...(config.Type === 'dataset' ? { datasetName: config.DatasetName } : { entityName: config.EntityName }),
                     data: [],
                     loadedSuccessfully: true,
                     permissionDenied: true,
@@ -1654,10 +1695,42 @@ export class BaseEngine extends BaseSingleton {
             }
             this._isPermissionConstrained = true;
             this._deniedEntityNames = deniedEntities;
-            return []; // Return empty — don't attempt any RunView calls
+            return []; // Return empty — don't attempt any RunView or dataset calls
         }
         return configs;
     }
+    /**
+     * Initializes the target property on `this` when a config is skipped before loading.
+     * Entity configs receive `[]`; `single_property` dataset configs receive `{}` only when
+     * the subclass has not already initialized the property to a default container.
+     */
+    initializeSkippedConfigProperty(config) {
+        if (config.AddToObject === false) {
+            return;
+        }
+        if (config.Type === 'dataset') {
+            if (config.DatasetResultHandling === 'single_property' &&
+                this[config.PropertyName] == null) {
+                this[config.PropertyName] = {};
+            }
+        }
+        else {
+            this[config.PropertyName] = [];
+        }
+    }
+    /**
+     * Returns the entity name(s) governed by `config`: `Entities` (or `EntityName`) for
+     * dataset configs, and `EntityName` for entity configs.
+     */
+    configEntityNames(config) {
+        if (config.Type === 'dataset') {
+            if (config.Entities && config.Entities.length > 0) {
+                return config.Entities;
+            }
+            return config.EntityName ? [config.EntityName] : [];
+        }
+        return config.EntityName ? [config.EntityName] : [];
+    }
     /**
      * Returns entity names among `configs` that do not exist in the loaded metadata provider.
      * Only checks when the metadata provider actually has entities loaded (`md.Entities.length > 0`)
@@ -1670,10 +1743,10 @@ export class BaseEngine extends BaseSingleton {
         }
         const missing = [];
         for (const config of configs) {
-            if (!config.EntityName)
-                continue;
-            if (!md.EntityByName(config.EntityName)) {
-                missing.push(config.EntityName);
+            for (const entityName of this.configEntityNames(config)) {
+                if (!md.EntityByName(entityName) && !missing.includes(entityName)) {
+                    missing.push(entityName);
+                }
             }
         }
         return missing;
@@ -1683,14 +1756,14 @@ export class BaseEngine extends BaseSingleton {
         const md = this.ProviderToUse;
         const denied = [];
         for (const config of configs) {
-            if (!config.EntityName)
-                continue;
-            const entityInfo = md.EntityByName(config.EntityName);
-            if (!entityInfo)
-                continue; // Entity not in metadata — let RunView handle it
-            const perms = entityInfo.GetUserPermisions(user);
-            if (!perms || !perms.CanRead) {
-                denied.push(config.EntityName);
+            for (const entityName of this.configEntityNames(config)) {
+                const entityInfo = md.EntityByName(entityName);
+                if (!entityInfo)
+                    continue; // Entity not in metadata — let RunView/dataset handle it
+                const perms = entityInfo.GetUserPermisions(user);
+                if ((!perms || !perms.CanRead) && !denied.includes(entityName)) {
+                    denied.push(entityName);
+                }
             }
         }
         return denied;
@@ -1777,9 +1850,16 @@ export class BaseEngine extends BaseSingleton {
         // UserInfoEngine's per-user '_UserApplications') apply out of initiation-order and the
         // cache ends up "one operation behind". See _configRefreshGeneration.
         const generation = this.beginConfigRefresh(config.PropertyName);
-        const p = this.RunViewProviderToUse;
-        const rv = new RunView(p);
-        const result = await rv.RunView(this.BuildRunViewParamsForConfig(config, bypassCache), contextUser);
+        this.incrementInFlightFullRefresh(config.PropertyName);
+        let result;
+        try {
+            const p = this.RunViewProviderToUse;
+            const rv = new RunView(p);
+            result = await rv.RunView(this.BuildRunViewParamsForConfig(config, bypassCache), contextUser);
+        }
+        finally {
+            this.decrementInFlightFullRefresh(config.PropertyName);
+        }
         // A newer full refresh superseded us while we awaited — drop this (staler) snapshot
         // rather than clobber the newer one. The newer refresh owns the assignment, the
         // observer notification, and (on failure) the retry, so bailing here leaves no
@@ -1884,6 +1964,35 @@ export class BaseEngine extends BaseSingleton {
         this._dataMap.set(config.PropertyName, { entityName: config.EntityName, data: [], loadedSuccessfully: true, readDenied: true });
         this.NotifyDataChange(config, []);
     }
+    /**
+     * Returns true when a failed dataset load was caused by the current user lacking Read
+     * permission on one of the dataset's constituent entities — either per local metadata
+     * (`config.Entities` / `config.EntityName`) or per the server's dataset status message
+     * (`does not have read permissions on ...`).
+     */
+    IsDatasetReadDenied(config, result, contextUser) {
+        for (const entityName of this.configEntityNames(config)) {
+            if (!this.ContextUserCanReadConfigEntity(entityName, contextUser)) {
+                return true;
+            }
+        }
+        return typeof result.Status === 'string' && /does not have read permissions? on/i.test(result.Status);
+    }
+    /**
+     * Records a dataset config as successfully loaded in an empty state after a permanent
+     * permission denial, so `BaseEngine.Load` marks the engine loaded and does not loop on
+     * `EnsureLoaded()` / `Config()`.
+     */
+    MarkDatasetConfigEmptyLoaded(config) {
+        this.initializeSkippedConfigProperty(config);
+        this._dataMap.set(config.PropertyName, {
+            datasetName: config.DatasetName,
+            data: [],
+            loadedSuccessfully: true,
+            readDenied: true,
+        });
+        this.NotifyDataChange(config, []);
+    }
     /**
      * Handles the process of loading multiple entity configs in a single network call via RunViews()
      * @param configs
@@ -1892,13 +2001,33 @@ export class BaseEngine extends BaseSingleton {
      */
     async LoadMultipleEntityConfigs(configs, contextUser, bypassCache = false) {
         if (configs && configs.length > 0) {
-            const p = this.RunViewProviderToUse;
-            const rv = new RunView(p);
-            const viewConfigs = configs.map(c => this.BuildRunViewParamsForConfig(c, bypassCache));
-            const results = await rv.RunViews(viewConfigs, contextUser);
+            // Same protocol as LoadSingleEntityConfig, per property: claim a refresh generation and
+            // mark a full refresh in flight BEFORE the awaited RunViews. Without it a `row_delta`
+            // that arrives mid-flight is applied to the held array and then overwritten by this
+            // (pre-delta) snapshot when the batch lands; with it the delta path defers to a
+            // coalesced reload instead, and a newer per-property refresh supersedes our slot.
+            const generations = configs.map(c => this.beginConfigRefresh(c.PropertyName));
+            for (const c of configs) {
+                this.incrementInFlightFullRefresh(c.PropertyName);
+            }
+            let results;
+            try {
+                const p = this.RunViewProviderToUse;
+                const rv = new RunView(p);
+                const viewConfigs = configs.map(c => this.BuildRunViewParamsForConfig(c, bypassCache));
+                results = await rv.RunViews(viewConfigs, contextUser);
+            }
+            finally {
+                for (const c of configs) {
+                    this.decrementInFlightFullRefresh(c.PropertyName);
+                }
+            }
             // Process results and record entity loads for redundancy detection
             const entityNames = [];
             for (let i = 0; i < configs.length; i++) {
+                if (!this.isLatestConfigRefresh(configs[i].PropertyName, generations[i])) {
+                    continue; // a newer refresh of this property owns the assignment
+                }
                 this.HandleSingleViewResult(configs[i], results[i], contextUser);
                 this.emitPropertyChange(configs[i].PropertyName);
                 if (configs[i].EntityName) {
@@ -1981,7 +2110,9 @@ export class BaseEngine extends BaseSingleton {
         let result;
         if (bypassCache) {
             result = await p.GetDatasetByName(config.DatasetName, config.DatasetItemFilters, contextUser, undefined, true);
-            await p.CacheDataset(config.DatasetName, config.DatasetItemFilters, result);
+            if (result?.Success) {
+                await p.CacheDataset(config.DatasetName, config.DatasetItemFilters, result);
+            }
         }
         else {
             result = await p.GetAndCacheDatasetByName(config.DatasetName, config.DatasetItemFilters, contextUser);
@@ -1998,6 +2129,11 @@ export class BaseEngine extends BaseSingleton {
             return;
         }
         if (!result.Success) {
+            if (this.IsDatasetReadDenied(config, result, contextUser)) {
+                this.MarkDatasetConfigEmptyLoaded(config);
+                LogWarning(`BaseEngine: Dataset ${config.DatasetName} not readable by current role — loaded empty (restricted-role degradation).`, 'Cache');
+                return;
+            }
             const errorMsg = result.Status || `Dataset "${config.DatasetName}" load returned Success=false`;
             LogError(`BaseEngine: Failed to load dataset ${config.DatasetName} into ${config.PropertyName}: ${errorMsg}`);
             this._dataMap.set(config.PropertyName, {
@@ -2139,14 +2275,21 @@ export class BaseEngine extends BaseSingleton {
                     // overlapping cache events (or an event racing a full reload) can resolve out
                     // of order and the stale result would be the one that assigns last.
                     const generation = this.beginConfigRefresh(config.PropertyName);
-                    // A burst of payloads for one slot usually arrives together. Let the rest of the
-                    // burst claim its generations first, so only the newest payload is materialized
-                    // instead of every one of them (receive side).
-                    await yieldToEventLoop();
-                    if (!this.isLatestConfigRefresh(config.PropertyName, generation)) {
-                        return;
+                    this.incrementInFlightFullRefresh(config.PropertyName);
+                    let rows = null;
+                    try {
+                        // A burst of payloads for one slot usually arrives together. Let the rest of the
+                        // burst claim its generations first, so only the newest payload is materialized
+                        // instead of every one of them (receive side).
+                        await yieldToEventLoop();
+                        if (!this.isLatestConfigRefresh(config.PropertyName, generation)) {
+                            return;
+                        }
+                        rows = await this.materializeCacheEventRows(config, parsed.results);
+                    }
+                    finally {
+                        this.decrementInFlightFullRefresh(config.PropertyName);
                     }
-                    const rows = await this.materializeCacheEventRows(config, parsed.results);
                     if (!this.isLatestConfigRefresh(config.PropertyName, generation)) {
                         return; // superseded while materializing — the newer refresh owns the property
                     }
@@ -2186,8 +2329,270 @@ export class BaseEngine extends BaseSingleton {
                 LogWarning(`BaseEngine.OnExternalCacheChange: payload for '${config.PropertyName}' could not be applied (${e instanceof Error ? e.message : String(e)}) — falling back to full reload`, 'Cache');
             }
         }
+        else if (event.Data && event.Action === 'row_delta') {
+            const outcome = await this.applyExternalRowDelta(config, event.Data);
+            if (outcome === 'applied' || outcome === 'superseded') {
+                return;
+            }
+        }
         await this.reloadAfterExternalChange(config);
     }
+    incrementInFlightFullRefresh(propertyName) {
+        this._inFlightFullRefreshCount.set(propertyName, (this._inFlightFullRefreshCount.get(propertyName) ?? 0) + 1);
+    }
+    decrementInFlightFullRefresh(propertyName) {
+        const next = (this._inFlightFullRefreshCount.get(propertyName) ?? 1) - 1;
+        if (next <= 0) {
+            this._inFlightFullRefreshCount.delete(propertyName);
+        }
+        else {
+            this._inFlightFullRefreshCount.set(propertyName, next);
+        }
+    }
+    /**
+     * Applies a compact `row_delta` pub/sub event in $O(\Delta)$ without re-materializing
+     * untouched sibling rows. Falls back to `'reload'` whenever schema hash, ordering, or
+     * row-count invariants indicate the engine cannot prove local delta equivalence.
+     */
+    async applyExternalRowDelta(config, rawDeltaJson) {
+        let delta;
+        try {
+            delta = JSON.parse(rawDeltaJson);
+        }
+        catch (e) {
+            LogWarning(`BaseEngine.OnExternalCacheChange: row_delta payload for '${config.PropertyName}' could not be parsed (${e instanceof Error ? e.message : String(e)}) — falling back to reload`, 'Cache');
+            return 'reload';
+        }
+        if (!delta ||
+            !Array.isArray(delta.upsertedRows) ||
+            !Array.isArray(delta.deletedPrimaryKeys) ||
+            !Array.isArray(delta.primaryKeyFields) ||
+            delta.primaryKeyFields.length === 0 ||
+            typeof delta.rowCount !== 'number') {
+            return 'reload';
+        }
+        if (this.payloadSchemaDiffers(config, delta.schemaHash)) {
+            LogStatusEx({ message: `BaseEngine.OnExternalCacheChange: row_delta for '${config.PropertyName}' was written under a different schema — reloading instead`, verboseOnly: true });
+            return 'reload';
+        }
+        // Ordered configs rely on database collation ordering; reload from the warm Redis slot (0 SQL).
+        if (config.OrderBy && delta.upsertedRows.length > 0) {
+            return 'reload';
+        }
+        let stepOutcome = 'reload';
+        const priorQueue = this._rowDeltaQueues.get(config.PropertyName) ?? Promise.resolve();
+        const currentStep = priorQueue.then(async () => {
+            try {
+                stepOutcome = await this.applyExternalRowDeltaSerialized(config, delta);
+            }
+            catch (e) {
+                LogWarning(`BaseEngine.OnExternalCacheChange: row_delta application for '${config.PropertyName}' failed (${e instanceof Error ? e.message : String(e)}) — falling back to reload`, 'Cache');
+                stepOutcome = 'reload';
+            }
+        });
+        const settled = currentStep.catch(() => undefined);
+        this._rowDeltaQueues.set(config.PropertyName, settled);
+        await currentStep;
+        if (this._rowDeltaQueues.get(config.PropertyName) === settled) {
+            this._rowDeltaQueues.delete(config.PropertyName);
+        }
+        return stepOutcome;
+    }
+    async applyExternalRowDeltaSerialized(config, delta) {
+        if ((this._inFlightFullRefreshCount.get(config.PropertyName) ?? 0) > 0) {
+            return 'reload';
+        }
+        const heldRows = this.getHeldRowsForDelta(config);
+        if (!heldRows) {
+            return 'reload';
+        }
+        const entityInfo = config.EntityName ? this.ProviderToUse?.EntityByName?.(config.EntityName) : undefined;
+        const pkFields = delta.primaryKeyFields;
+        const isUuidPk = pkFields.map(fieldName => Boolean(entityInfo?.FieldByName(fieldName)?.IsUniqueIdentifier));
+        const heldIndexByKey = this.indexHeldRowsForDelta(heldRows, pkFields, isUuidPk);
+        if (!heldIndexByKey) {
+            return 'reload';
+        }
+        const keyPlan = this.planRowDeltaKeys(delta, heldRows.length, heldIndexByKey, pkFields, isUuidPk);
+        if (!keyPlan) {
+            return 'reload';
+        }
+        // Echo / duplicate delta suppression: when no rows are added or removed and every
+        // upserted row's __mj_UpdatedAt matches the held row, skip materialization & emit churn.
+        if (keyPlan.matchedDeleteKeys.size === 0 &&
+            keyPlan.netNewInserts === 0 &&
+            this.upsertsMatchHeldTimestamps(heldRows, heldIndexByKey, delta.upsertedRows, keyPlan.upsertKeys, entityInfo)) {
+            LogStatusEx({ message: `BaseEngine.OnExternalCacheChange: '${config.PropertyName}' already holds row_delta versions — skipped`, verboseOnly: true });
+            return 'applied';
+        }
+        const generationBefore = this._configRefreshGeneration.get(config.PropertyName) ?? 0;
+        const materializedUpserts = delta.upsertedRows.length > 0
+            ? await this.materializeCacheEventRows(config, delta.upsertedRows)
+            : [];
+        if (materializedUpserts === null) {
+            return 'reload';
+        }
+        if ((this._configRefreshGeneration.get(config.PropertyName) ?? 0) !== generationBefore ||
+            (this._inFlightFullRefreshCount.get(config.PropertyName) ?? 0) > 0) {
+            return 'superseded';
+        }
+        const nextRows = this.mergeMaterializedDeltaRows(heldRows, pkFields, isUuidPk, keyPlan.matchedDeleteKeys, keyPlan.upsertKeys, materializedUpserts);
+        this.HandleSingleViewResult(config, {
+            Success: true,
+            Results: nextRows,
+            RowCount: nextRows.length,
+            TotalRowCount: delta.totalRowCount ?? nextRows.length,
+            ExecutionTime: 0,
+            ErrorMessage: '',
+            UserViewRunID: '',
+        });
+        await this.RebuildDerivedState(this._contextUser);
+        this.emitPropertyChange(config.PropertyName);
+        return 'applied';
+    }
+    indexHeldRowsForDelta(heldRows, pkFields, isUuidPk) {
+        const heldIndexByKey = new Map();
+        for (let i = 0; i < heldRows.length; i++) {
+            const key = this.canonicalHeldRowPkKey(heldRows[i], pkFields, isUuidPk);
+            if (key === null) {
+                return null;
+            }
+            heldIndexByKey.set(key, i);
+        }
+        return heldIndexByKey.size === heldRows.length ? heldIndexByKey : null;
+    }
+    planRowDeltaKeys(delta, heldRowCount, heldIndexByKey, pkFields, isUuidPk) {
+        const matchedDeleteKeys = new Set();
+        for (const delPk of delta.deletedPrimaryKeys) {
+            const key = this.canonicalPlainRecordPkKey(delPk, pkFields, isUuidPk);
+            if (key === null) {
+                return null;
+            }
+            if (heldIndexByKey.has(key)) {
+                matchedDeleteKeys.add(key);
+            }
+        }
+        const upsertKeys = [];
+        const seenUpsertKeys = new Set();
+        let netNewInserts = 0;
+        for (const upRow of delta.upsertedRows) {
+            const key = this.canonicalPlainRecordPkKey(upRow, pkFields, isUuidPk);
+            if (key === null || seenUpsertKeys.has(key)) {
+                return null;
+            }
+            seenUpsertKeys.add(key);
+            upsertKeys.push(key);
+            if (!heldIndexByKey.has(key) || matchedDeleteKeys.has(key)) {
+                netNewInserts++;
+            }
+        }
+        // Strict cardinality verification: detects uninitialized state, missed pub/sub messages,
+        // or filtered-slot membership divergence and falls back to reading the warm cache slot.
+        const expectedNextLength = heldRowCount - matchedDeleteKeys.size + netNewInserts;
+        if (expectedNextLength !== delta.rowCount) {
+            return null;
+        }
+        return { matchedDeleteKeys, upsertKeys, netNewInserts };
+    }
+    mergeMaterializedDeltaRows(heldRows, pkFields, isUuidPk, matchedDeleteKeys, upsertKeys, materializedUpserts) {
+        const upsertByKey = new Map();
+        for (let i = 0; i < upsertKeys.length; i++) {
+            upsertByKey.set(upsertKeys[i], materializedUpserts[i]);
+        }
+        const consumedUpsertKeys = new Set();
+        const nextRows = [];
+        for (let i = 0; i < heldRows.length; i++) {
+            const existingRow = heldRows[i];
+            const key = this.canonicalHeldRowPkKey(existingRow, pkFields, isUuidPk);
+            if (upsertByKey.has(key)) {
+                nextRows.push(upsertByKey.get(key));
+                consumedUpsertKeys.add(key);
+            }
+            else if (!matchedDeleteKeys.has(key)) {
+                nextRows.push(existingRow);
+            }
+        }
+        for (let i = 0; i < upsertKeys.length; i++) {
+            const key = upsertKeys[i];
+            if (!consumedUpsertKeys.has(key)) {
+                nextRows.push(upsertByKey.get(key));
+            }
+        }
+        return nextRows;
+    }
+    getHeldRowsForDelta(config) {
+        const entry = this._dataMap.get(config.PropertyName);
+        if (entry && entry.loadedSuccessfully === false) {
+            return null;
+        }
+        if (entry?.loadedSuccessfully && Array.isArray(entry.data)) {
+            return entry.data;
+        }
+        const propVal = Reflect.get(this, config.PropertyName);
+        if (Array.isArray(propVal) && (propVal.length > 0 || Boolean(entry))) {
+            return propVal;
+        }
+        return null;
+    }
+    readHeldRowField(row, fieldName) {
+        if (row instanceof BaseEntity) {
+            return row.Get(fieldName);
+        }
+        if (fieldName in row) {
+            return row[fieldName];
+        }
+        const nestedData = row['data'];
+        if (typeof nestedData === 'object' && nestedData !== null && fieldName in nestedData) {
+            return nestedData[fieldName];
+        }
+        return undefined;
+    }
+    canonicalHeldRowPkKey(row, pkFields, isUuidPk) {
+        const parts = [];
+        for (let i = 0; i < pkFields.length; i++) {
+            const val = this.readHeldRowField(row, pkFields[i]);
+            if (val === null || val === undefined) {
+                return null;
+            }
+            const str = String(val);
+            parts.push(CanonicalPrimaryKeyValue(str, isUuidPk[i]));
+        }
+        return parts.join('\u001f');
+    }
+    canonicalPlainRecordPkKey(record, pkFields, isUuidPk) {
+        const parts = [];
+        for (let i = 0; i < pkFields.length; i++) {
+            const val = record[pkFields[i]];
+            if (val === null || val === undefined) {
+                return null;
+            }
+            const str = String(val);
+            parts.push(CanonicalPrimaryKeyValue(str, isUuidPk[i]));
+        }
+        return parts.join('\u001f');
+    }
+    upsertsMatchHeldTimestamps(heldRows, heldIndexByKey, upsertedRows, upsertKeys, entityInfo) {
+        if (!entityInfo || !entityInfo.Fields.some(f => f.IsUpdatedAtField)) {
+            return false;
+        }
+        for (let i = 0; i < upsertedRows.length; i++) {
+            const heldIdx = heldIndexByKey.get(upsertKeys[i]);
+            if (heldIdx === undefined) {
+                return false;
+            }
+            const heldRaw = this.readHeldRowField(heldRows[heldIdx], EntityInfo.UpdatedAtFieldName);
+            const incomingRaw = upsertedRows[i][EntityInfo.UpdatedAtFieldName];
+            if (heldRaw == null || incomingRaw == null) {
+                return false;
+            }
+            const heldMs = heldRaw instanceof Date ? heldRaw.getTime() : new Date(String(heldRaw)).getTime();
+            const incomingMs = incomingRaw instanceof Date ? incomingRaw.getTime() : new Date(String(incomingRaw)).getTime();
+            if (Number.isNaN(heldMs) || Number.isNaN(incomingMs) || heldMs !== incomingMs) {
+                return false;
+            }
+        }
+        return true;
+    }
     /**
      * True when a cache-change payload carries a schema hash and it differs from this engine's
      * hash for the config's entity. A payload without a hash, or an entity this process cannot
@@ -2201,40 +2606,81 @@ export class BaseEngine extends BaseSingleton {
         return ownHash !== undefined && ownHash !== payloadSchemaHash;
     }
     /**
-     * Reloads a config after a peer's cache change, coalescing overlapping requests: an event that
-     * arrives while a reload for the same property is running asks for one more reload after it
-     * instead of starting its own. Every caller's promise settles only after a reload that began
+     * Reloads a config after a change made elsewhere, coalescing overlapping requests: an event
+     * that arrives while a reload for the same property is running asks for one more reload after
+     * it instead of starting its own. Every caller's promise settles only after a reload that began
      * after its event, so no change is missed, but N events in a burst cost at most two reloads.
+     * Successive reloads of one property are at least {@link ExternalChangeFollowUpDelayMs} apart.
+     * Requests for different properties never share a reload.
+     *
+     * @param bypassCache - Read past the cache. When any request folded into a reload asks for
+     *   it, that reload bypasses the cache.
      */
-    reloadAfterExternalChange(config) {
+    reloadAfterExternalChange(config, bypassCache = false) {
         const running = this._externalChangeReloads.get(config.PropertyName);
         if (running) {
             running.Again = true;
+            running.BypassCache = running.BypassCache || bypassCache;
             return running.Done;
         }
-        const reload = { Again: false, Done: Promise.resolve() };
+        const reload = { Again: false, BypassCache: bypassCache, Done: Promise.resolve() };
         this._externalChangeReloads.set(config.PropertyName, reload);
         reload.Done = this.runExternalChangeReloads(config, reload);
         return reload.Done;
     }
-    /** Runs reloads for {@link reloadAfterExternalChange} until no further event asked for one. */
+    /**
+     * Runs reloads for {@link reloadAfterExternalChange} until no further event asked for one.
+     * A reload that throws does not end the loop while another is pending, so an event that
+     * arrived during a failed reload is still served; the error surfaces only when the last
+     * reload is the one that threw.
+     */
     async runExternalChangeReloads(config, reload) {
         try {
+            let lastError = null;
             do {
+                const wait = this.reloadSpacingRemainingMs(config.PropertyName);
+                if (wait > 0) {
+                    // Requests that arrive during the wait join the reload that follows it.
+                    await new Promise(resolve => setTimeout(resolve, wait));
+                }
+                const bypassCache = reload.BypassCache;
                 reload.Again = false;
-                // The reload replaces the property, so the derived state has to be rebuilt too —
-                // and the reload must NOT emit on its own, or a subscriber wakes between the new
-                // rows and the rebuild and reads derived state still pointing at the instances
-                // this reload discarded.
-                await this.LoadSingleConfig(config, this._contextUser, /*bypassCache*/ false, /*suppressEmit*/ true);
-                await this.RebuildDerivedState(this._contextUser);
-                this.emitPropertyChange(config.PropertyName);
+                reload.BypassCache = false;
+                lastError = await this.runOneExternalChangeReload(config, bypassCache);
+                this._externalChangeReloadEndedAt.set(config.PropertyName, Date.now());
+                if (lastError && reload.Again) {
+                    LogError(lastError);
+                }
             } while (reload.Again);
+            if (lastError) {
+                throw lastError;
+            }
         }
         finally {
             this._externalChangeReloads.delete(config.PropertyName);
         }
     }
+    /** How long the next reload of the property must still wait for {@link ExternalChangeFollowUpDelayMs}; 0 when it may start now. */
+    reloadSpacingRemainingMs(propertyName) {
+        const endedAt = this._externalChangeReloadEndedAt.get(propertyName);
+        return endedAt === undefined ? 0 : Math.max(0, endedAt + BaseEngine.ExternalChangeFollowUpDelayMs - Date.now());
+    }
+    /** One reload for {@link runExternalChangeReloads}. Returns the error it threw, or null. */
+    async runOneExternalChangeReload(config, bypassCache) {
+        try {
+            // The reload replaces the property, so the derived state has to be rebuilt too —
+            // and the reload must NOT emit on its own, or a subscriber wakes between the new
+            // rows and the rebuild and reads derived state still pointing at the instances
+            // this reload discarded.
+            await this.LoadSingleConfig(config, this._contextUser, bypassCache, /*suppressEmit*/ true);
+            await this.RebuildDerivedState(this._contextUser);
+            this.emitPropertyChange(config.PropertyName);
+            return null;
+        }
+        catch (e) {
+            return e instanceof Error ? e : new Error(String(e));
+        }
+    }
     /**
      * True when `payloadRows` are the same row versions this config currently holds: the same
      * number of rows, and the same multiset of (primary key, `__mj_UpdatedAt`) pairs.