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

package/dist/generic/baseEngine.js

@@ -39,6 +39,14 @@ export class BaseEnginePropertyConfig extends BaseInfo {
          * environment, and the same is true for MJAPI/Server based environments. If you need network based notification, additional infrastructure will be needed to implement that.
          */
         this.AutoRefresh = true;
+        /**
+         * When set to true, the engine will use the LocalCacheManager to cache results locally.
+         * On subsequent loads (unless forceRefresh is true), cached results will be validated
+         * via smart cache check and returned from local storage if still current.
+         *
+         * @default false
+         */
+        this.CacheLocal = false;
         // now copy the values from init to this object
         if (init)
             Object.assign(this, init);
@@ -190,8 +198,20 @@ export class BaseEngine extends BaseSingleton {
          * reconciles it. Keyed by config PropertyName. See {@link beginConfigRefresh}.
          */
         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}.
+         */
+        this._externalChangeReloads = 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;
     }
@@ -659,14 +679,19 @@ export class BaseEngine extends BaseSingleton {
             }
             if (event.type === 'delete' || event.type === 'save') {
                 const eName = event.baseEntity.EntityInfo.Name.toLowerCase().trim();
-                const matchingConfigs = this.Configs.filter((config) => {
+                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
@@ -674,6 +699,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
@@ -700,6 +728,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);
                 }
@@ -726,7 +769,7 @@ export class BaseEngine extends BaseSingleton {
             if (!entityName) {
                 return true; // No entity name, nothing to do
             }
-            const matchingConfigs = this.Configs.filter((config) => {
+            const matchingConfigs = this._metadataConfigs.filter((config) => {
                 return config.AutoRefresh && config.EntityName && config.EntityName.trim().toLowerCase() === entityName;
             });
             if (matchingConfigs.length === 0) {
@@ -875,7 +918,7 @@ export class BaseEngine extends BaseSingleton {
             const entityName = event.baseEntity.EntityInfo.Name.toLowerCase().trim();
             if (!this._entityEventSubjects.has(entityName)) {
                 // Find matching config to get custom debounce time
-                const matchingConfig = this.Configs.find(c => c.EntityName?.trim().toLowerCase() === entityName);
+                const matchingConfig = this._metadataConfigs.find(c => c.EntityName?.trim().toLowerCase() === entityName);
                 // Use config-specific debounce time or fall back to default
                 const debounceTimeValue = matchingConfig?.DebounceTime ?? this.EntityEventDebounceTime;
                 const subject = new Subject();
@@ -947,13 +990,15 @@ export class BaseEngine extends BaseSingleton {
         try {
             const entityName = events[0].baseEntity.EntityInfo.Name.toLowerCase().trim();
             let refreshCount = 0;
-            for (const config of this.Configs) {
+            for (const config of this._metadataConfigs) {
                 if (config.AutoRefresh && config.Type === 'entity' && config.EntityName?.trim().toLowerCase() === entityName) {
                     const classified = events.map(e => ({ event: e, disposition: this.classifyEventForConfig(config, e) }));
                     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);
@@ -1018,7 +1063,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' };
                 }
             }
@@ -1203,6 +1252,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
@@ -1241,6 +1295,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.
@@ -1390,16 +1459,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)) {
@@ -1421,6 +1483,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);
         }
     }
@@ -1484,6 +1552,7 @@ export class BaseEngine extends BaseSingleton {
         // 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
@@ -1494,6 +1563,35 @@ export class BaseEngine extends BaseSingleton {
         // 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
@@ -1508,6 +1606,29 @@ export class BaseEngine extends BaseSingleton {
     CheckPermissionsOrSkipAll(configs, contextUser) {
         if (configs.length === 0)
             return configs;
+        // First check whether any configured entity is missing from metadata altogether
+        // (e.g., an optional OpenApp engine registered in the bundle whose database schema
+        // is not installed in the target environment). Skip cleanly instead of firing N
+        // guaranteed-to-fail RunView calls and logging N error stack traces at startup.
+        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(', ')}`,
+                verboseOnly: true,
+                category: 'Cache',
+            });
+            for (const config of configs) {
+                if (config.AddToObject !== false) {
+                    this[config.PropertyName] = [];
+                }
+                this._dataMap.set(config.PropertyName, {
+                    entityName: config.EntityName,
+                    data: [],
+                    loadedSuccessfully: true,
+                });
+            }
+            return [];
+        }
         // Determine the user to check permissions for — on the client side contextUser
         // may be undefined, so fall back to the current logged-in user from Metadata.
         const user = contextUser || this.ProviderToUse?.CurrentUser;
@@ -1537,6 +1658,26 @@ export class BaseEngine extends BaseSingleton {
         }
         return configs;
     }
+    /**
+     * 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`)
+     * so unit tests with empty mock providers are unaffected.
+     */
+    findMissingEntities(configs) {
+        const md = this.ProviderToUse;
+        if (!md?.Entities || md.Entities.length === 0) {
+            return [];
+        }
+        const missing = [];
+        for (const config of configs) {
+            if (!config.EntityName)
+                continue;
+            if (!md.EntityByName(config.EntityName)) {
+                missing.push(config.EntityName);
+            }
+        }
+        return missing;
+    }
     /** The entity names among `configs` that `user` cannot read, per current metadata. */
     findUnreadableEntities(configs, user) {
         const md = this.ProviderToUse;
@@ -1602,14 +1743,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 {
@@ -1617,6 +1752,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,
@@ -1777,6 +1913,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
@@ -1796,7 +1984,7 @@ export class BaseEngine extends BaseSingleton {
             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}`;
@@ -1823,18 +2011,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 {
@@ -1925,6 +2126,14 @@ export class BaseEngine extends BaseSingleton {
                         LogStatusEx({ message: `BaseEngine.OnExternalCacheChange: '${config.PropertyName}' already holds the payload's rows — skipped`, verboseOnly: true });
                         return;
                     }
+                    // Rows written under a different field list (a server on the other side of a
+                    // migration) lack columns this process has, or carry ones it does not. Loading
+                    // them would blank the missing columns on every row, so read the rows instead.
+                    if (this.payloadSchemaDiffers(config, parsed.schemaHash)) {
+                        LogStatusEx({ message: `BaseEngine.OnExternalCacheChange: payload for '${config.PropertyName}' was written under a different schema — reloading instead`, verboseOnly: true });
+                        await this.reloadAfterExternalChange(config);
+                        return;
+                    }
                     // Claim a refresh generation BEFORE the awaited materialization — the same
                     // protocol LoadSingleConfig uses around its awaited RunView. Without it, two
                     // overlapping cache events (or an event racing a full reload) can resolve out
@@ -1977,13 +2186,54 @@ 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');
             }
         }
-        // Fallback: reload this config from the database. This also replaces the property, so the
-        // derived state has to be rebuilt here 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);
+        await this.reloadAfterExternalChange(config);
+    }
+    /**
+     * 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
+     * resolve, does not count as differing.
+     */
+    payloadSchemaDiffers(config, payloadSchemaHash) {
+        if (typeof payloadSchemaHash !== 'string' || !payloadSchemaHash || !config.EntityName) {
+            return false;
+        }
+        const ownHash = LocalCacheManager.Instance.ComputeSchemaHash(this.ProviderToUse, config.EntityName);
+        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
+     * after its event, so no change is missed, but N events in a burst cost at most two reloads.
+     */
+    reloadAfterExternalChange(config) {
+        const running = this._externalChangeReloads.get(config.PropertyName);
+        if (running) {
+            running.Again = true;
+            return running.Done;
+        }
+        const reload = { Again: false, 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. */
+    async runExternalChangeReloads(config, reload) {
+        try {
+            do {
+                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);
+            } while (reload.Again);
+        }
+        finally {
+            this._externalChangeReloads.delete(config.PropertyName);
+        }
     }
     /**
      * True when `payloadRows` are the same row versions this config currently holds: the same
@@ -2231,11 +2481,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`,