@memberjunction/core 6.2.0-edge.5 → 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,13 +214,33 @@ 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();
+        /**
+         * Maps normalized entity names (`entityName.trim().toLowerCase()`) to dataset item properties
+         * loaded via `DatasetResultHandling === 'single_property'`, allowing in-place auto-refresh of
+         * dataset-backed engines (such as `TemplateEngineBase`) on entity save/delete events.
+         */
+        this._datasetItemMappings = new Map();
         /** Configs waiting for the cache manager to initialize before their callbacks can register. */
         this._deferredCacheCallbackConfigs = null;
     }
@@ -676,11 +711,16 @@ export class BaseEngine extends BaseSingleton {
                 const matchingConfigs = this._metadataConfigs.filter((config) => {
                     return config.AutoRefresh && config.EntityName && config.EntityName.trim().toLowerCase() === eName;
                 });
-                if (matchingConfigs.length === 0) {
+                const matchingDatasetItems = (this._datasetItemMappings.get(eName) ?? []).filter(m => m.config.AutoRefresh !== false);
+                if (matchingConfigs.length === 0 && matchingDatasetItems.length === 0) {
                     return true;
                 }
-                // Check if ALL matching configs can use immediate mutation
-                const allCanUseImmediate = matchingConfigs.every(config => this.canUseImmediateMutation(config));
+                // Check if ALL matching entity configs can use immediate mutation. A saved object
+                // that lacks columns (its saver could not read them) would put a narrowed row into
+                // an engine every user reads, so that save takes the full-refresh path instead,
+                // which reloads the row as this engine's own user.
+                const allCanUseImmediate = matchingConfigs.every(config => this.canUseImmediateMutation(config))
+                    && this.savedRowIsComplete(event);
                 if (allCanUseImmediate) {
                     const applyAll = async () => {
                         // mutation requires await because the entity must be cloned (with its
@@ -688,6 +728,9 @@ export class BaseEngine extends BaseSingleton {
                         for (const config of matchingConfigs) {
                             await this.applyImmediateMutation(config, event);
                         }
+                        if (matchingDatasetItems.length > 0) {
+                            await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                        }
                     };
                     // The entity raises save/delete as soon as its own write returns, while an
                     // enclosing transaction may still be open. Mutating the cache now would keep a
@@ -714,6 +757,21 @@ export class BaseEngine extends BaseSingleton {
                     return true;
                 }
                 else {
+                    if (matchingDatasetItems.length > 0) {
+                        const provider = event.baseEntity.ProviderToUse;
+                        if (provider instanceof DatabaseProviderBase && provider.TransactionDepth > 0) {
+                            const token = provider.CapturePostCommitToken();
+                            const savedKey = event.type === 'save' ? event.baseEntity.PrimaryKey.ToString() : null;
+                            provider.RunAfterCommit(async () => {
+                                if (savedKey !== null && event.baseEntity.PrimaryKey.ToString() !== savedKey)
+                                    return;
+                                await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                            }, `BaseEngine dataset cache mutation for ${eName}`, token);
+                        }
+                        else {
+                            await this.applyDatasetItemMutations(matchingDatasetItems, event);
+                        }
+                    }
                     // At least one config requires full refresh, use debouncing
                     return this.DebounceIndividualBaseEntityEvent(event);
                 }
@@ -740,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;
             }
@@ -765,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;
         }
@@ -789,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
@@ -967,7 +1042,9 @@ export class BaseEngine extends BaseSingleton {
                     const needingWork = classified.filter(c => c.disposition.action === 'refresh');
                     if (needingWork.length > 0) {
                         // Check if we can use immediate array mutation instead of running a view
-                        if (this.canUseImmediateMutation(config)) {
+                        // A save carrying a row with missing columns can't replace an engine row
+                        // in place (see savedRowIsComplete), so the whole window refreshes instead.
+                        if (this.canUseImmediateMutation(config) && needingWork.every(c => this.savedRowIsComplete(c.event))) {
                             // Apply, in order, every event the array hasn't seen yet
                             for (const c of needingWork) {
                                 await this.applyImmediateMutation(config, c.event);
@@ -1032,7 +1109,11 @@ export class BaseEngine extends BaseSingleton {
     classifyEventForConfig(config, event) {
         if (event.type === 'save') {
             if (event.saveSubType === 'update' || event.saveSubType === 'create') {
-                if (this.isEntityAlreadyInArray(config, event.baseEntity)) {
+                // When AlternateBaseView is set on the config, the SQL view applies a canonical
+                // WHERE/JOIN predicate — an in-memory update can cause the record to fall out of
+                // the alternate view (e.g. Status changed from 'Active' to 'Inactive'), so we
+                // must refresh from the database rather than only notifying in place.
+                if (!config.AlternateBaseView && this.isEntityAlreadyInArray(config, event.baseEntity)) {
                     return { action: 'notify', changeType: event.saveSubType === 'create' ? 'add' : 'update' };
                 }
             }
@@ -1217,6 +1298,11 @@ export class BaseEngine extends BaseSingleton {
         if (config.Filter) {
             return false;
         }
+        // An AlternateBaseView applies a canonical SQL WHERE/JOIN in the database view;
+        // immediate in-memory mutations cannot evaluate that SQL predicate.
+        if (config.AlternateBaseView) {
+            return false;
+        }
         // If there's an OrderBy, we can't safely do immediate mutations because:
         // - For creates: we'd need to insert at the correct position
         // - For updates: the entity might need to move to a different position
@@ -1255,6 +1341,21 @@ export class BaseEngine extends BaseSingleton {
         // it means the subclass has overridden it
         return instanceProto.AdditionalLoading !== baseProto.AdditionalLoading;
     }
+    /**
+     * Whether a save event's entity carries every column, so it can replace an engine row in
+     * place. Deletes and non-save events always qualify.
+     */
+    savedRowIsComplete(event) {
+        if (event.type !== 'save' || !event.baseEntity) {
+            return true;
+        }
+        const entity = event.baseEntity;
+        // Asked of the object directly, so no throwaway GetAll() row is built per event. An object
+        // that is not a BaseEntity (a test double) is judged on its row, as before.
+        return typeof entity.HoldsEveryField === 'function'
+            ? entity.HoldsEveryField()
+            : LocalCacheManager.RowHasEveryField(entity.EntityInfo, entity.GetAll());
+    }
     /**
      * Applies an immediate array mutation based on the entity event type.
      * This is faster than running a full view refresh for simple add/update/delete operations.
@@ -1404,16 +1505,9 @@ export class BaseEngine extends BaseSingleton {
         if (cache.IsBatchingEntityEvents(entity?.ProviderToUse) || cache.WasTakenByEntityEventBatch(event)) {
             return;
         }
-        // Get the connection string from the provider for fingerprint generation
-        // The provider is needed because fingerprints include connection prefix
-        const provider = this.ProviderToUse;
-        let connectionString;
-        if (provider && 'InstanceConnectionString' in provider) {
-            connectionString = provider.InstanceConnectionString;
-        }
-        // Use the shared builder so the fingerprint matches what LoadSingleEntityConfig
-        // and RegisterCacheChangeCallbacks produce — prevents silent cache-slot mismatches
-        const fingerprint = LocalCacheManager.Instance.GenerateRunViewFingerprint(this.BuildRunViewParamsForConfig(config), connectionString);
+        // The same builder as LoadSingleEntityConfig and RegisterCacheChangeCallbacks, so the
+        // slot maintained here is the one this engine reads and listens on.
+        const fingerprint = this.configFingerprint(config);
         // Build CompositeKey from the entity's primary key fields
         const key = entity.PrimaryKey;
         if (!key || key.KeyValuePairs.length === 0 || key.KeyValuePairs.some(kv => kv.Value == null)) {
@@ -1435,6 +1529,12 @@ export class BaseEngine extends BaseSingleton {
         }
         else {
             const entityData = entity.GetAll();
+            // A row-filtered or field-secured slot, or a saved row missing columns, cannot take the
+            // saver's values in place: clear it and let the next read refill it.
+            if (!LocalCacheManager.Instance.CanUpsertRowIntoSlot(fingerprint, entity.EntityInfo, entityData)) {
+                await LocalCacheManager.Instance.InvalidateRunViewResult(fingerprint);
+                return;
+            }
             await LocalCacheManager.Instance.UpsertSingleEntity(fingerprint, entityData, key, updatedAt);
         }
     }
@@ -1495,19 +1595,48 @@ 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');
-        // 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)),
+        this.WarnAboutFieldSecuredEntities(entityConfigs);
+        // 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);
     }
+    /** Engine-class and entity pairs already warned about by {@link WarnAboutFieldSecuredEntities}. */
+    static { this._fieldSecurityWarned = new Set(); }
+    /**
+     * On a server, says once per engine class and entity when an entity this engine caches has
+     * field-level security (its own, or an IS-A ancestor's). Changes nothing about the load.
+     *
+     * A server-side engine loads as the system user (see {@link ResolveContextUser}), so its
+     * cache holds every column, including ones some users are denied. That is correct for a
+     * process-wide cache, and it makes every path that hands engine data to a person responsible
+     * for projecting it to that person first.
+     */
+    WarnAboutFieldSecuredEntities(entityConfigs) {
+        const provider = this.ProviderToUse;
+        if (provider?.ProviderType !== ProviderType.Database) {
+            return;
+        }
+        for (const config of entityConfigs) {
+            const entityInfo = config.EntityName ? provider.EntityByName(config.EntityName) : undefined;
+            if (!entityInfo?.FieldLevelSecurityApplies) {
+                continue;
+            }
+            const key = `${this.constructor.name}|${entityInfo.Name}`.toLowerCase();
+            if (BaseEngine._fieldSecurityWarned.has(key)) {
+                continue;
+            }
+            BaseEngine._fieldSecurityWarned.add(key);
+            LogStatus(`${this.constructor.name}: '${entityInfo.Name}' has field-level security. Engine data is loaded as the system user and holds every column; project it for the acting user before it reaches a person.`);
+        }
+    }
     /**
      * All-or-nothing permission gate: checks `CanRead` on every entity config. If ANY
      * entity is denied, ALL configs are skipped — the engine is marked permission-constrained
@@ -1529,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,
                 });
@@ -1552,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,
@@ -1570,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`)
@@ -1586,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;
@@ -1599,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;
@@ -1659,14 +1816,8 @@ export class BaseEngine extends BaseSingleton {
      * IgnoreMaxRows, IncludeBinaryFields) are always consistent — preventing cache key mismatches that break
      * cross-server invalidation via Redis pub/sub and local cache upsert/remove operations.
      *
-     * **Row-level security is not part of the fingerprints built from these params.** The engine
-     * builds them with `GenerateRunViewFingerprint(params, connection)`, without the RLS clause the
-     * provider adds for the reading user. On a server that is correct: engines load as the system
-     * user, whose RLS clause is empty, so the provider's fingerprint for the same read matches. An
-     * engine loaded by an RLS-scoped user (possible on a client) would compute an unscoped
-     * fingerprint for a slot the provider stored under a scoped one, so its cache callbacks and
-     * `syncLocalCacheForConfig` would target a different slot. Pass the RLS clause here if such an
-     * engine is ever needed.
+     * The slot fingerprint for these params also carries the engine user's row-level-security
+     * and field-security segments; see {@link configFingerprint}.
      */
     BuildRunViewParamsForConfig(config, bypassCache = false) {
         return {
@@ -1674,6 +1825,7 @@ export class BaseEngine extends BaseSingleton {
             ResultType: config.ResultType || this.EngineDefaultResultType,
             ExtraFilter: config.Filter,
             OrderBy: config.OrderBy,
+            ...(config.AlternateBaseView ? { AlternateBaseView: config.AlternateBaseView } : {}),
             IgnoreMaxRows: true, // Engines always need ALL data — bypass entity-level UserViewMaxRows caps
             _fromEngine: true, // Mark as engine-initiated to avoid false positive telemetry warnings
             CacheLocal: config.CacheLocal,
@@ -1698,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
@@ -1805,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
@@ -1813,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) {
@@ -1834,6 +2042,58 @@ export class BaseEngine extends BaseSingleton {
             }
         }
     }
+    /**
+     * Applies an immediate in-place mutation to dataset item arrays when a constituent entity is saved or deleted,
+     * then invokes {@link AdditionalLoading} so derived associations (e.g. Template Content / Params) stay current.
+     */
+    async applyDatasetItemMutations(mappings, event) {
+        const entity = event.baseEntity;
+        let mutated = false;
+        const notifiedProperties = new Set();
+        for (const mapping of mappings) {
+            const container = this[mapping.config.PropertyName];
+            const currentData = container?.[mapping.itemCode];
+            if (!Array.isArray(currentData)) {
+                continue;
+            }
+            if (event.type === 'save') {
+                const provider = this.ProviderToUse;
+                if (!provider)
+                    continue;
+                const cached = await provider.GetEntityObject(mapping.entityName, this._contextUser);
+                if (!cached)
+                    continue;
+                await cached.LoadFromData(entity.GetAll());
+                const existsByRef = currentData.indexOf(entity) >= 0;
+                if (!existsByRef) {
+                    const index = this.findEntityIndexByPrimaryKeys(currentData, entity);
+                    if (index >= 0) {
+                        currentData[index] = cached;
+                    }
+                    else {
+                        currentData.push(cached);
+                    }
+                }
+                mutated = true;
+                notifiedProperties.add(mapping.config.PropertyName);
+            }
+            else if (event.type === 'delete') {
+                const oldValues = event.payload?.OldValues;
+                const index = this.indexOfEntityByRefOrKey(currentData, entity, oldValues);
+                if (index >= 0) {
+                    currentData.splice(index, 1);
+                    mutated = true;
+                    notifiedProperties.add(mapping.config.PropertyName);
+                }
+            }
+        }
+        if (mutated) {
+            await this.AdditionalLoading(this._contextUser);
+            for (const propName of notifiedProperties) {
+                this.emitPropertyChange(propName);
+            }
+        }
+    }
     /**
      * Handles the process of loading a single config of type 'dataset'.
      * @param config
@@ -1850,10 +2110,12 @@ 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);
+            result = await p.GetAndCacheDatasetByName(config.DatasetName, config.DatasetItemFilters, contextUser);
         }
         if (!result) {
             const errorMsg = `GetAndCacheDatasetByName("${config.DatasetName}") returned undefined/null — provider: ${p?.constructor?.name}`;
@@ -1867,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, {
@@ -1880,18 +2147,31 @@ export class BaseEngine extends BaseSingleton {
         if (result.Success) {
             if (config.AddToObject !== false) {
                 if (config.DatasetResultHandling === 'single_property') {
+                    // Clear previous dataset item mappings for this property before re-indexing
+                    for (const [key, list] of this._datasetItemMappings.entries()) {
+                        const filtered = list.filter(m => m.config.PropertyName !== config.PropertyName);
+                        if (filtered.length === 0) {
+                            this._datasetItemMappings.delete(key);
+                        }
+                        else if (filtered.length !== list.length) {
+                            this._datasetItemMappings.set(key, filtered);
+                        }
+                    }
                     const singleObject = {};
-                    for (const item of result.Results) {
-                        //convert the results to entity objects before
-                        //adding them to the singleObject
-                        const entities = [];
-                        for (const entityData of item.Results) {
+                    await Promise.all(result.Results.map(async (item) => {
+                        const entities = await Promise.all(item.Results.map(async (entityData) => {
                             const entity = await p.GetEntityObject(item.EntityName, contextUser);
                             await entity.LoadFromData(entityData);
-                            entities.push(entity);
-                        }
+                            return entity;
+                        }));
                         singleObject[item.Code] = entities;
-                    }
+                        if (item.EntityName && item.Code) {
+                            const normName = item.EntityName.trim().toLowerCase();
+                            const existing = this._datasetItemMappings.get(normName) ?? [];
+                            existing.push({ config, itemCode: item.Code, entityName: item.EntityName });
+                            this._datasetItemMappings.set(normName, existing);
+                        }
+                    }));
                     this[config.PropertyName] = singleObject;
                 }
                 else {
@@ -1995,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
                     }
@@ -2042,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
@@ -2057,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.
@@ -2337,11 +2927,26 @@ export class BaseEngine extends BaseSingleton {
         // read-modify-write of this slot, and an unlocked replace would clobber it.
         await cache.ReplaceRunViewResultLocked(this.configFingerprint(config), params, plainRows, maxUpdatedAt, plainRows.length, this.ProviderToUse);
     }
-    /** The cache fingerprint of a config's slot, as {@link RegisterCacheChangeCallbacks} computes it. */
+    /**
+     * The cache fingerprint of a config's slot: the one {@link RegisterCacheChangeCallbacks} listens
+     * on, {@link syncLocalCacheForConfig} maintains and {@link storeConfigRows} writes.
+     *
+     * Built by the provider for this engine's user, with that user's row-level-security and
+     * field-security segments, so it names the same slot the provider's own RunView read used. An
+     * engine running as a restricted user holds only what that user may see; without the segments
+     * its rows would be written into, and its callbacks registered on, the slot unrestricted
+     * readers share.
+     */
     configFingerprint(config) {
+        const params = this.BuildRunViewParamsForConfig(config);
         const provider = this.RunViewProviderToUse;
-        const connectionPrefix = provider instanceof ProviderBase ? provider.InstanceConnectionString : undefined;
-        return LocalCacheManager.Instance.GenerateRunViewFingerprint(this.BuildRunViewParamsForConfig(config), connectionPrefix);
+        if (provider instanceof ProviderBase) {
+            return provider.ComputeRunViewCacheFingerprint(params, this._contextUser);
+        }
+        const connection = provider && 'InstanceConnectionString' in provider
+            ? provider.InstanceConnectionString
+            : undefined;
+        return LocalCacheManager.Instance.GenerateRunViewFingerprint(params, connection);
     }
     /**
      * Snapshot of what this engine holds: per property, the row count, newest `__mj_UpdatedAt`,