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

package/dist/generic/providerBase.js

@@ -5,7 +5,7 @@ import { ComputeRRF } from "./scoring/ReciprocalRankFusion.js";
 import { LocalCacheManager } from "./localCacheManager.js";
 import { ApplicationInfo } from "../generic/applicationInfo.js";
 import { AuditLogTypeInfo, AuthorizationInfo, AuthorizationRoleInfo, RoleInfo, RowLevelSecurityFilterInfo, UserInfo } from "./securityInfo.js";
-import { MJGlobal, MJEventType, NormalizeUUID, UUIDsEqual, MJLruCache } from "@memberjunction/global";
+import { MJGlobal, MJEventType, NormalizeUUID, UUIDsEqual, MJLruCache, EscapeSQLString, ordinalCompare } from "@memberjunction/global";
 import { TelemetryManager } from "./telemetryManager.js";
 import { LogError, LogStatus, LogStatusEx } from "./logging.js";
 import { QueryCategoryInfo, QueryFieldInfo, QueryInfo, QueryPermissionInfo, QueryEntityInfo, QueryParameterInfo, QueryDependencyInfo, SQLDialectInfo, QuerySQLInfo } from "./queryInfo.js";
@@ -189,6 +189,10 @@ export class ProviderBase {
         // it can't be reset on metadata refresh; it needs its own eviction policy.
         this._entityRecordNameCache = new MJLruCache({ maxSize: 10000, ttlMs: 60 * 60 * 1000 });
         this._refresh = false;
+        /** Single-flight guard for the full metadata reload in {@link Config} — see the comment there. */
+        this._metadataReloadInFlight = null;
+        /** Set when a refresh request arrives while a reload is in flight; the reload loop reruns once. */
+        this._metadataReloadQueued = false;
         this._lastRefreshCheckAt = 0;
         /**
          * Pending coalesced requests waiting to be flushed.
@@ -213,6 +217,16 @@ export class ProviderBase {
          */
         this._inflightViews = new Map();
         this._lingerInvalidationWired = false;
+        /**
+         * Lowercased names of the entities whose rows COMPOSE this provider's metadata — the
+         * MJ_Metadata dataset's item entities, recorded each time the dataset is loaded (and restored
+         * from local storage on warm boot). Membership is DATA: adding a `DatasetItem` row to
+         * MJ_Metadata extends refresh coverage with no code change, which is why no entity names are
+         * hardcoded anywhere in this mechanism.
+         */
+        this._metadataDatasetEntityNames = null;
+        /** Debounce timer for {@link scheduleMetadataMemberRefresh}. */
+        this._metadataMemberRefreshTimer = null;
         this._clientFingerprintMemo = new WeakMap();
         this._cachedVisibleExplorerNavigationItems = null;
     }
@@ -355,6 +369,7 @@ export class ProviderBase {
                     continue;
                 }
                 instance.invalidateInflightViewsForEntity(entityName);
+                instance.handleMetadataMemberEntityEvent(entityName, entityEvent);
             }
         });
     }
@@ -405,6 +420,155 @@ export class ProviderBase {
         }
         return names;
     }
+    // ── Metadata-Dataset Membership Refresh ────────────────────────────
+    /**
+     * Coalescing window, in milliseconds, for metadata refreshes triggered by writes to the
+     * entities that compose this provider's metadata. A single administrative action produces a
+     * burst (enabling field security writes one permission row per field/role pair, each raising
+     * its own event) — one refresh per burst, not one per row. The window also gives an enclosing
+     * entity transaction time to COMMIT before the re-read: every event in the burst re-arms the
+     * timer, so the refresh runs no earlier than this long after the LAST write.
+     */
+    static { this.MetadataDatasetRefreshDebounceMs = 500; }
+    /**
+     * Records which entities compose this provider's metadata, from the loaded MJ_Metadata
+     * dataset result, and registers this instance with the static event fan-out so writes to any
+     * of them schedule a debounced metadata refresh. Called from {@link GetAllMetadata} on every
+     * successful load, so the set tracks the dataset definition as it changes.
+     */
+    registerMetadataDatasetMembership(dataset) {
+        const names = new Set();
+        for (const item of dataset.Results ?? []) {
+            const n = item.EntityName?.trim().toLowerCase();
+            if (n) {
+                names.add(n);
+            }
+        }
+        if (names.size === 0) {
+            return; // a failed/empty load must not erase a previously recorded set
+        }
+        this._metadataDatasetEntityNames = names;
+        this.ensureInflightViewInvalidation();
+    }
+    /**
+     * Static fan-out callback: a BaseEntity save/delete (or a remote-invalidate from another
+     * server) touched `lowerEntityName`. If that entity is one of the entities this provider's
+     * metadata is BUILT FROM, the metadata this provider is serving — and, on the server, the
+     * metadata every per-request provider adopts from it — is now stale, so schedule a debounced
+     * refresh. Permission metadata is the load-bearing case: field-level security is enforced
+     * FROM metadata at every enforcement point, so a rule an administrator just tightened is
+     * simply not enforced until this re-read happens.
+     */
+    handleMetadataMemberEntityEvent(lowerEntityName, entityEvent) {
+        if (!this._metadataDatasetEntityNames?.has(lowerEntityName)) {
+            return; // the overwhelming majority of writes
+        }
+        if (!this.eventTargetsThisProviderBackend(entityEvent)) {
+            return;
+        }
+        this.scheduleMetadataMemberRefresh();
+    }
+    /**
+     * Whether the write described by `entityEvent` happened against the backend THIS provider's
+     * metadata comes from. In a multi-provider process (a client connected to several MJ servers,
+     * a server connected to several databases) a write on one backend must not refresh another's
+     * metadata. Deliberately fails OPEN — when the event does not identify its provider, or a
+     * connection string is unavailable, the answer is "yes": a spurious refresh is a bounded
+     * cost, a suppressed one is a stale-permissions window.
+     */
+    eventTargetsThisProviderBackend(entityEvent) {
+        try {
+            if (entityEvent.type === 'remote-invalidate') {
+                // The transport that received the message attaches itself; other providers in the
+                // same process are connected to other servers.
+                return !entityEvent.provider || entityEvent.provider === this;
+            }
+            const self = this;
+            const saveProvider = entityEvent.baseEntity?.ProviderToUse;
+            if (saveProvider instanceof ProviderBase && saveProvider !== self) {
+                const theirs = saveProvider.InstanceConnectionString;
+                const mine = this.InstanceConnectionString;
+                if (theirs && mine && theirs !== mine) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        catch {
+            return true; // a connection-string getter with no live pool must not veto the refresh
+        }
+    }
+    /**
+     * How long a member-entity write waits before this provider's refresh runs. The base value
+     * is the short debounce window — right for the server, where the writer is the refresher and
+     * the delay only exists to coalesce a burst and let the enclosing transaction commit.
+     * Transport providers override this with a much longer, RANDOMIZED window: every browser
+     * receives every write broadcast, so the delay is what turns "N clients each re-pull the
+     * metadata graph within the same half-second of any member write" into "each client pays at
+     * most one staleness check per window, at a moment no other client shares".
+     */
+    get MetadataMemberRefreshDelayMs() {
+        return ProviderBase.MetadataDatasetRefreshDebounceMs;
+    }
+    /**
+     * Whether a member-entity write arriving while the refresh timer is already armed RESTARTS
+     * the timer (debounce) or joins the pending window (coalesce/throttle).
+     *
+     * The base is a true debounce (`true`): the server's refresh must run AFTER the last write
+     * of the unit of work, so every event pushes the timer out — a burst costs one refresh, run
+     * once the burst ends. Transport providers return `false`: with a long window, re-arming
+     * would let steady org-wide write activity postpone the refresh indefinitely (starvation);
+     * joining the armed window guarantees at most one refresh per window regardless of write
+     * rate, which is the whole point of the window.
+     */
+    get MetadataMemberRefreshRearmsOnNewEvents() {
+        return true;
+    }
+    /**
+     * Schedules this provider's metadata refresh after a write to a metadata member entity.
+     * Delay and re-arm semantics come from {@link MetadataMemberRefreshDelayMs} and
+     * {@link MetadataMemberRefreshRearmsOnNewEvents} — debounce on the server, long jittered
+     * coalescing window on clients. The refresh targets THIS instance — the provider that loaded
+     * the dataset owns the metadata built from it; short-lived per-request providers never load
+     * the dataset (they adopt the global's metadata as a shared shell), so on the server only
+     * the process-global provider ever gets here.
+     */
+    scheduleMetadataMemberRefresh() {
+        if (this._metadataMemberRefreshTimer) {
+            if (!this.MetadataMemberRefreshRearmsOnNewEvents) {
+                return; // coalesce: this write joins the already-armed window
+            }
+            clearTimeout(this._metadataMemberRefreshTimer);
+        }
+        this._metadataMemberRefreshTimer = setTimeout(() => {
+            this._metadataMemberRefreshTimer = null;
+            this.RefreshAfterMetadataMemberChange().catch((e) => {
+                LogError(`Metadata refresh after a member-entity change failed: ${e instanceof Error ? e.message : String(e)}`);
+            });
+        }, this.MetadataMemberRefreshDelayMs);
+    }
+    /**
+     * How this provider refreshes after a metadata member entity changed. The base behavior is a
+     * hard {@link Refresh} — correct for database providers, where the process that PERFORMED the
+     * write is the one refreshing, so re-checking staleness first is wasted work and the re-read
+     * must bypass every cache layer. Transport providers (GraphQL) override this with a staleness
+     * check so a browser doesn't re-pull the full metadata graph for a change the server-side
+     * timestamp comparison can disconfirm.
+     */
+    async RefreshAfterMetadataMemberChange() {
+        return this.Refresh();
+    }
+    /**
+     * Cancels any pending debounced metadata refresh. Call during teardown (logout, provider
+     * disposal) so a timer armed just before teardown doesn't fire a refresh against a
+     * connection that no longer has a valid session.
+     */
+    CancelPendingMetadataMemberRefresh() {
+        if (this._metadataMemberRefreshTimer) {
+            clearTimeout(this._metadataMemberRefreshTimer);
+            this._metadataMemberRefreshTimer = null;
+        }
+    }
     /******** ABSTRACT SECTION ****************************************************************** */
     /**
      * When true, cached RunView/RunQuery results are returned immediately on a
@@ -932,7 +1096,10 @@ export class ProviderBase {
                     const record = result.Results[j];
                     allResults.push({
                         EntityName: entity.Name,
-                        RecordID: String(record[entity.FirstPrimaryKey?.Name ?? 'ID'] ?? ''),
+                        // Compact CompositeKey segment: the bare value for a single-column key (any
+                        // column name), "F1|v1||F2|v2" for a composite key — what
+                        // CompositeKey.FromURLSegment(entity, RecordID) reads back.
+                        RecordID: CompositeKey.FromEntityRecord(entity, record).ToCompactURLSegment(),
                         Title: String(record[titleField] ?? 'Untitled'),
                         Snippet: String(record[snippetField] ?? '').substring(0, 200),
                         Score: 1.0 / (j + 1) // Rank-based scoring for RRF compatibility
@@ -987,7 +1154,7 @@ export class ProviderBase {
         }
         // Fallback to first text field
         const textField = entity.Fields.find(f => f.Type.toLowerCase().includes('varchar') || f.Type.toLowerCase().includes('text'));
-        return textField?.Name ?? entity.FirstPrimaryKey?.Name ?? 'ID';
+        return textField?.Name ?? entity.FirstPrimaryKey.Name; // first-pk-ok: display-column fallback for FTS results, not a key construction
     }
     async RunViewsUncoalesced(params, contextUser) {
         const key = this.GenerateDedupKey(params, contextUser);
@@ -1456,7 +1623,9 @@ export class ProviderBase {
         const nameField = entity.NameField?.Name ?? entity.Fields.find(f => f.IsNameField)?.Name ?? null;
         const out = [];
         for (const row of (r.Results ?? [])) {
-            const id = String(row['ID'] ?? '');
+            // The entity is arbitrary: read the key off its primary-key metadata, not a hardcoded
+            // `ID` column. Compact segment so single-column keys stay the raw value.
+            const id = CompositeKey.FromEntityRecord(entity, row).ToCompactURLSegment();
             if (!id)
                 continue;
             const nameVal = nameField ? String(row[nameField] ?? '').toLowerCase() : '';
@@ -1495,17 +1664,23 @@ export class ProviderBase {
     async searchEntitiesFilterByPermission(entity, ids, contextUser) {
         if (ids.length === 0)
             return new Set();
-        const escaped = ids.map(id => `'${id.replace(/'/g, "''")}'`).join(',');
+        // `ids` are compact CompositeKey segments (see searchEntitiesLexicalPass): a single-column
+        // key — whatever the column is called — uses one IN(); a composite key needs one
+        // (F1=.. AND F2=..) term per record. Hardcoding `ID` here returned nothing for every entity
+        // whose key isn't named ID, so SearchEntity silently produced zero results for them.
+        const filter = entity.PrimaryKeys.length === 1
+            ? `${entity.FirstPrimaryKey.Name} IN (${ids.map(id => `'${EscapeSQLString(id)}'`).join(',')})` // first-pk-ok: guarded by PrimaryKeys.length === 1
+            : ids.map(id => `(${CompositeKey.FromURLSegment(entity, id).ToWhereClause()})`).join(' OR ');
         const r = await this.RunView({
             EntityName: entity.Name,
-            ExtraFilter: `ID IN (${escaped})`,
-            Fields: ['ID'],
+            ExtraFilter: filter,
+            Fields: entity.PrimaryKeys.map(pk => pk.Name),
             ResultType: 'simple',
             MaxRows: ids.length,
         }, contextUser);
         if (!r.Success)
             return new Set();
-        return new Set((r.Results ?? []).map(row => row.ID));
+        return new Set((r.Results ?? []).map(row => CompositeKey.FromEntityRecord(entity, row).ToCompactURLSegment()));
     }
     /**
      * Returns true if any param in the batch has SaveViewResults set,
@@ -2402,13 +2577,21 @@ export class ProviderBase {
         else if (checkResult.status === 'differential') {
             // Cache is stale but we have differential data - merge with cached data
             const fingerprint = this.clientCacheFingerprint(param);
-            // Get entity info for primary key field name
+            // Every primary key column, in order. The server's `deletedRecordIDs` are the full
+            // RecordChanges.RecordID segments (`F1|v1||F2|v2` for a composite key), and the merge
+            // keys cached and updated rows the same way — so keying on the first column alone made
+            // composite-key deletes never match and collapsed rows sharing that column. An entity the
+            // server described but this provider cannot resolve is not merged: fall through to the
+            // full refetch below rather than inventing an `ID` key.
             const entity = this.EntityByName(param.EntityName);
-            const primaryKeyFieldName = entity?.FirstPrimaryKey?.Name || 'ID';
+            const primaryKeyFieldNames = entity?.PrimaryKeys.map(pk => pk.Name) ?? [];
+            if (primaryKeyFieldNames.length === 0) {
+                LogError(`ProviderBase: server returned differential data for '${param.EntityName}' but the entity is not in this provider's metadata — refetching in full.`);
+            }
             // Apply differential update to cache (runViewCacheEligible, not raw CacheLocal — see the
             // cacheable-gate note in prepareSmartCacheCheckParams; keeps Materialized/count_only/etc. out).
-            if (this.runViewCacheEligibleForWrite(param) && checkResult.differentialData && LocalCacheManager.Instance.IsInitialized) {
-                const merged = await LocalCacheManager.Instance.ApplyDifferentialUpdate(fingerprint, param, checkResult.differentialData.updatedRows, checkResult.differentialData.deletedRecordIDs, primaryKeyFieldName, checkResult.maxUpdatedAt || new Date().toISOString(), checkResult.rowCount || 0, checkResult.aggregateResults, // Pass fresh aggregate results (can't be differentially computed)
+            if (primaryKeyFieldNames.length > 0 && this.runViewCacheEligibleForWrite(param) && checkResult.differentialData && LocalCacheManager.Instance.IsInitialized) {
+                const merged = await LocalCacheManager.Instance.ApplyDifferentialUpdate(fingerprint, param, checkResult.differentialData.updatedRows, checkResult.differentialData.deletedRecordIDs, primaryKeyFieldNames, checkResult.maxUpdatedAt || new Date().toISOString(), checkResult.rowCount || 0, checkResult.aggregateResults, // Pass fresh aggregate results (can't be differentially computed)
                 this);
                 if (merged) {
                     const mergedResult = {
@@ -3357,24 +3540,62 @@ export class ProviderBase {
             // first, make sure we reset the flag to false so that if another call to this function happens
             // while we are waiting for the async call to finish, we dont do it again
             this._refresh = false;
-            // Fetch new metadata without clearing current metadata
-            // This ensures readers always see valid data (old until new is ready)
-            const start = new Date().getTime();
-            const res = await this.GetAllMetadata(providerToUse, hardRefresh);
-            const end = new Date().getTime();
-            LogStatusEx({ message: `GetAllMetadata() took ${end - start} ms`, verboseOnly: true });
-            if (res) {
-                // Atomic swap via UpdateLocalMetadata: single property assignment is atomic in JavaScript
-                // Readers now see new metadata instead of old
-                // Uses UpdateLocalMetadata() to maintain consistency with LoadLocalMetadataFromStorage()
-                // and allow potential subclass overrides for extensibility
-                this.UpdateLocalMetadata(res);
-                this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps; // update this since we just used server to get all the stuff
-                await this.SaveLocalMetadataToStorage();
+            // SINGLE-FLIGHT: at most one full metadata reload runs at a time. Without this, a
+            // second refresh request arriving while a reload is still awaiting its queries starts
+            // a CONCURRENT reload, and whichever finishes LAST wins the atomic swap — an older
+            // snapshot can overwrite a newer one. A joiner must not simply await and return,
+            // either: the in-flight reload's queries may predate the write that prompted the
+            // joiner, so it flags ONE follow-up; the loop below reruns after the current pass,
+            // guaranteeing the final swap comes from a read that started after the last request.
+            if (this._metadataReloadInFlight) {
+                this._metadataReloadQueued = true;
+                await this._metadataReloadInFlight;
+                return true;
             }
-            else {
-                // GetAllMetadata failed - log error but keep existing metadata
-                LogError('GetAllMetadata() returned undefined - metadata not updated');
+            this._metadataReloadInFlight = (async () => {
+                let effectiveHardRefresh = hardRefresh;
+                do {
+                    this._metadataReloadQueued = false;
+                    // The local timestamps must describe the snapshot about to be loaded. On the
+                    // hard-refresh path the staleness check was SKIPPED, so the cached remote
+                    // timestamps predate this pass — copying them as-is would make the next
+                    // periodic check see a mismatch and reload once more for nothing. Re-read
+                    // them (one cheap status query, authoritative) BEFORE the load, not after:
+                    // a write landing DURING the load then leaves the stamped timestamps looking
+                    // stale and the next tick reloads — the safe direction. Reading after could
+                    // stamp the snapshot as containing a write it does not.
+                    if (effectiveHardRefresh) {
+                        await this.RefreshRemoteMetadataTimestamps(providerToUse);
+                    }
+                    // Fetch new metadata without clearing current metadata
+                    // This ensures readers always see valid data (old until new is ready)
+                    const start = new Date().getTime();
+                    const res = await this.GetAllMetadata(providerToUse, effectiveHardRefresh);
+                    const end = new Date().getTime();
+                    LogStatusEx({ message: `GetAllMetadata() took ${end - start} ms`, verboseOnly: true });
+                    if (res) {
+                        // Atomic swap via UpdateLocalMetadata: single property assignment is atomic in JavaScript
+                        // Readers now see new metadata instead of old
+                        // Uses UpdateLocalMetadata() to maintain consistency with LoadLocalMetadataFromStorage()
+                        // and allow potential subclass overrides for extensibility
+                        this.UpdateLocalMetadata(res);
+                        this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps; // update this since we just used server to get all the stuff
+                        await this.SaveLocalMetadataToStorage();
+                    }
+                    else {
+                        // GetAllMetadata failed - log error but keep existing metadata
+                        LogError('GetAllMetadata() returned undefined - metadata not updated');
+                    }
+                    // A queued follow-up exists only because another refresh request arrived
+                    // mid-reload; rerun hard so the re-read cannot be served by any cache layer.
+                    effectiveHardRefresh = true;
+                } while (this._metadataReloadQueued);
+            })();
+            try {
+                await this._metadataReloadInFlight;
+            }
+            finally {
+                this._metadataReloadInFlight = null;
             }
         }
         return true;
@@ -3594,6 +3815,10 @@ export class ProviderBase {
             if (d && d.Success) {
                 // cache the dataset for anyone who wants to use it
                 await this.CacheDataset(ProviderBase._mjMetadataDatasetName, null, d);
+                // Record which entities this metadata is built from, so a write to any of them
+                // schedules a debounced refresh of this provider's metadata (see
+                // registerMetadataDatasetMembership — membership is the dataset definition, not a list).
+                this.registerMetadataDatasetMembership(d);
                 // got the results, let's build our response in the format we need
                 const simpleMetadata = {};
                 for (let r of d.Results) {
@@ -3656,7 +3881,7 @@ export class ProviderBase {
         const result = [];
         // Sort entities alphabetically by name to ensure deterministic ordering
         // This prevents non-deterministic output in CodeGen and other metadata consumers
-        const sortedEntities = entities.sort((a, b) => a.Name.localeCompare(b.Name));
+        const sortedEntities = entities.sort((a, b) => ordinalCompare(a.Name, b.Name) || ordinalCompare(a.ID, b.ID));
         if (fieldValues && fieldValues.length > 0) {
             const fieldValuesByFieldId = this.groupByNormalizedUUID(fieldValues, fv => fv.EntityFieldID);
             for (const f of fields) {
@@ -3680,7 +3905,7 @@ export class ProviderBase {
         for (const e of sortedEntities) {
             const entityIdKey = NormalizeUUID(e.ID);
             const entityFields = fieldsByEntityId.get(entityIdKey) || [];
-            e.EntityFields = entityFields.sort((a, b) => a.Sequence - b.Sequence);
+            e.EntityFields = entityFields.sort((a, b) => (a.Sequence - b.Sequence) || ordinalCompare(a.Name, b.Name) || ordinalCompare(a.ID, b.ID));
             e.EntityPermissions = permissionsByEntityId.get(entityIdKey) || [];
             e.EntityRelationships = relationshipsByEntityId.get(entityIdKey) || [];
             e.EntitySettings = settingsByEntityId.get(entityIdKey) || [];
@@ -3867,13 +4092,18 @@ export class ProviderBase {
     /**
      * Checks if local metadata is out of date and needs refreshing.
      * Compares local timestamps with server timestamps.
+     * @param bypassMinCheckInterval - When true, skips the {@link MinRefreshCheckIntervalMs}
+     * throttle. Event-driven callers pass true: they hold positive evidence that a metadata
+     * member entity was just written, and the throttle otherwise answers "fresh" for any check
+     * arriving within the window of the previous one — which would silently drop the second of
+     * two permission changes made less than the window apart.
      * @returns True if refresh is needed, false otherwise
      */
-    async CheckToSeeIfRefreshNeeded(providerToUse) {
+    async CheckToSeeIfRefreshNeeded(providerToUse, bypassMinCheckInterval) {
         if (!this.AllowRefresh)
             return false;
         const now = Date.now();
-        if ((now - this._lastRefreshCheckAt) < ProviderBase.MinRefreshCheckIntervalMs) {
+        if (!bypassMinCheckInterval && (now - this._lastRefreshCheckAt) < ProviderBase.MinRefreshCheckIntervalMs) {
             LogStatusEx({
                 message: `[RefreshCheck] Skipped — last check was ${now - this._lastRefreshCheckAt}ms ago (min interval ${ProviderBase.MinRefreshCheckIntervalMs}ms)`,
                 verboseOnly: true
@@ -3888,10 +4118,13 @@ export class ProviderBase {
     /**
      * Refreshes metadata only if needed based on timestamp comparison.
      * Combines check and refresh into a single operation.
+     * @param bypassMinCheckInterval - Passed through to {@link CheckToSeeIfRefreshNeeded};
+     * event-driven callers set true so the throttle cannot eat a check they have positive
+     * evidence for.
      * @returns True if refresh was successful or not needed
      */
-    async RefreshIfNeeded(providerToUse) {
-        if (await this.CheckToSeeIfRefreshNeeded(providerToUse))
+    async RefreshIfNeeded(providerToUse, bypassMinCheckInterval) {
+        if (await this.CheckToSeeIfRefreshNeeded(providerToUse, bypassMinCheckInterval))
             return this.Refresh(providerToUse);
         else
             return true;
@@ -3943,6 +4176,11 @@ export class ProviderBase {
                         // to a downstream `.constructor`/`.LoadFromData` crash.
                         throw new Error(`Entity '${entityName}' could not be instantiated — MJGlobal ClassFactory returned null. Ensure LoadGeneratedEntities()/LoadCoreEntities() has run so the entity's class is registered.`);
                     }
+                    // Always rebind. ClassFactory passes `(Entity, this)` into the constructor,
+                    // but a 1-arg subclass (`constructor(Entity) { super(Entity); }`) silently
+                    // drops the provider. Without this, ProviderToUse falls back to the global
+                    // host and a nested save on an independent instance deadlocks on FKs.
+                    newObject.BindProvider(this);
                     await newObject.Config(actualContextUser);
                     // Initialize IS-A parent entity composition chain before any data operations
                     await newObject.InitializeParentEntity();
@@ -4361,13 +4599,31 @@ export class ProviderBase {
             const tsKey = this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey;
             const fmtKey = this.LocalStoragePrefix + ProviderBase.localStorageFormatKey;
             const dataKey = this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey;
+            const membershipKey = this.LocalStoragePrefix + ProviderBase.localStorageDatasetMembershipKey;
             const readStart = Date.now();
-            const all = await ls.GetItems([tsKey, fmtKey, dataKey]);
+            const all = await ls.GetItems([tsKey, fmtKey, dataKey, membershipKey]);
             const readMs = Date.now() - readStart;
             const tsRaw = all.get(tsKey) ?? null;
             const format = all.get(fmtKey) ?? null;
             const raw = all.get(dataKey) ?? null;
+            const membershipRaw = all.get(membershipKey) ?? null;
             this._latestLocalMetadataTimestamps = tsRaw ? JSON.parse(tsRaw) : null;
+            // Restore the metadata-member entity set so the event-driven refresh works on a warm
+            // boot that never calls GetAllMetadata (the stale-while-revalidate fast start). The
+            // set is only stored after a successful dataset load, so restoring it is exactly as
+            // trustworthy as restoring the metadata itself.
+            if (membershipRaw) {
+                try {
+                    const names = JSON.parse(membershipRaw);
+                    if (Array.isArray(names) && names.length > 0) {
+                        this._metadataDatasetEntityNames = new Set(names);
+                        this.ensureInflightViewInvalidation();
+                    }
+                }
+                catch (membershipErr) {
+                    LogError(`[Metadata Cache] Failed to restore dataset membership: ${membershipErr instanceof Error ? membershipErr.message : String(membershipErr)}`);
+                }
+            }
             if (!raw)
                 return;
             // Decompress if stored in compressed format, otherwise parse directly
@@ -4413,10 +4669,12 @@ export class ProviderBase {
     static { this.localStorageTimestampsKey = this.localStorageRootKey + '_Timestamps'; }
     static { this.localStorageAllMetadataKey = this.localStorageRootKey + '_AllMetadata'; }
     static { this.localStorageFormatKey = this.localStorageRootKey + '_Format'; }
+    static { this.localStorageDatasetMembershipKey = this.localStorageRootKey + '_DatasetMembership'; }
     static { this.localStorageKeys = [
         ProviderBase.localStorageTimestampsKey,
         ProviderBase.localStorageAllMetadataKey,
         ProviderBase.localStorageFormatKey,
+        ProviderBase.localStorageDatasetMembershipKey,
     ]; }
     /**
      * Converts a base64-encoded string to an ArrayBuffer.
@@ -4460,46 +4718,74 @@ export class ProviderBase {
             if (!ls)
                 return;
             const start = Date.now();
-            // Save timestamps as a JSON string. The metadata snapshot path intentionally uses
-            // string storage so the compressed (gzip+base64) format below can round-trip cleanly
-            // through providers that don't support binary natively.
-            await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey, JSON.stringify(this._latestLocalMetadataTimestamps));
-            // Serialize the AllMetadata object
+            // Serialize the AllMetadata object FIRST. If this throws (or the payload write below
+            // fails), nothing else has been written yet, so the previously stored timestamps still
+            // describe the previously stored payload and LocalMetadataObsolete() will report
+            // obsolete on the next boot — which is what makes the save retry. Writing timestamps
+            // before the payload left the cache claiming freshness with no payload behind it, and
+            // that state was never retried.
             const jsonString = JSON.stringify(this._localMetadata);
-            // Attempt compressed storage using native CompressionStream (available in modern browsers and Node 18+)
-            if (typeof CompressionStream !== 'undefined') {
-                try {
-                    const blob = new Blob([jsonString]);
-                    const cs = new CompressionStream('gzip');
-                    const compressedStream = blob.stream().pipeThrough(cs);
-                    const compressedBuffer = await new Response(compressedStream).arrayBuffer();
-                    const base64 = ProviderBase.arrayBufferToBase64(compressedBuffer);
-                    await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey, base64);
-                    await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageFormatKey, 'gzip');
-                    const elapsed = Date.now() - start;
-                    const ratio = jsonString.length > 0 ? (base64.length / jsonString.length * 100).toFixed(1) : '?';
-                    LogStatusEx({
-                        message: `[Metadata Cache] Save complete: ${elapsed}ms, raw=${(jsonString.length / 1024 / 1024).toFixed(1)}MB, compressed=${(base64.length / 1024 / 1024).toFixed(1)}MB (${ratio}%)`,
-                        verboseOnly: true
-                    });
-                    return;
-                }
-                catch (compressErr) {
-                    // Compression failed — fall through to uncompressed save
-                    LogError(`[Metadata Cache] Compression failed, falling back to uncompressed: ${compressErr instanceof Error ? compressErr.message : String(compressErr)}`);
-                }
+            const snapshot = await this.writeMetadataSnapshot(ls, jsonString);
+            // Persist the metadata-member entity set beside the snapshot it belongs to, so the
+            // event-driven refresh survives a warm boot (see LoadLocalMetadataFromStorage).
+            if (this._metadataDatasetEntityNames?.size) {
+                await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageDatasetMembershipKey, JSON.stringify([...this._metadataDatasetEntityNames]));
+            }
+            // Timestamps LAST: they are the freshness claim for everything written above, so they
+            // must be the final thing to land.
+            await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey, JSON.stringify(this._latestLocalMetadataTimestamps));
+            this.logMetadataSaveComplete(Date.now() - start, jsonString.length, snapshot);
+        }
+        catch (e) {
+            LogError(`[Metadata Cache] SaveLocalMetadataToStorage failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Writes the serialized metadata payload and its format marker. Compressed (gzip+base64) when
+     * CompressionStream is available, otherwise plain JSON. The snapshot path intentionally uses
+     * string storage so the compressed form round-trips cleanly through providers that don't
+     * support binary natively. A compression failure falls back to the uncompressed write; a
+     * failure of the write itself propagates to the caller so nothing after it is stored.
+     */
+    async writeMetadataSnapshot(ls, jsonString) {
+        const dataKey = this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey;
+        const formatKey = this.LocalStoragePrefix + ProviderBase.localStorageFormatKey;
+        // Attempt compressed storage using native CompressionStream (available in modern browsers and Node 18+)
+        if (typeof CompressionStream !== 'undefined') {
+            try {
+                const blob = new Blob([jsonString]);
+                const cs = new CompressionStream('gzip');
+                const compressedStream = blob.stream().pipeThrough(cs);
+                const compressedBuffer = await new Response(compressedStream).arrayBuffer();
+                const base64 = ProviderBase.arrayBufferToBase64(compressedBuffer);
+                await ls.SetItem(dataKey, base64);
+                await ls.SetItem(formatKey, 'gzip');
+                return { compressed: true, storedLength: base64.length };
+            }
+            catch (compressErr) {
+                // Compression failed — fall through to uncompressed save
+                LogError(`[Metadata Cache] Compression failed, falling back to uncompressed: ${compressErr instanceof Error ? compressErr.message : String(compressErr)}`);
             }
-            // Fallback: uncompressed save (older environments without CompressionStream)
-            await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey, jsonString);
-            await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageFormatKey, 'json');
-            const elapsed = Date.now() - start;
+        }
+        // Fallback: uncompressed save (older environments without CompressionStream)
+        await ls.SetItem(dataKey, jsonString);
+        await ls.SetItem(formatKey, 'json');
+        return { compressed: false, storedLength: jsonString.length };
+    }
+    logMetadataSaveComplete(elapsedMs, rawLength, snapshot) {
+        const mb = (n) => (n / 1024 / 1024).toFixed(1);
+        if (snapshot.compressed) {
+            const ratio = rawLength > 0 ? (snapshot.storedLength / rawLength * 100).toFixed(1) : '?';
             LogStatusEx({
-                message: `[Metadata Cache] Save complete (uncompressed): ${elapsed}ms, size=${(jsonString.length / 1024 / 1024).toFixed(1)}MB`,
+                message: `[Metadata Cache] Save complete: ${elapsedMs}ms, raw=${mb(rawLength)}MB, compressed=${mb(snapshot.storedLength)}MB (${ratio}%)`,
                 verboseOnly: true
             });
         }
-        catch (e) {
-            LogError(`[Metadata Cache] SaveLocalMetadataToStorage failed: ${e instanceof Error ? e.message : String(e)}`);
+        else {
+            LogStatusEx({
+                message: `[Metadata Cache] Save complete (uncompressed): ${elapsedMs}ms, size=${mb(rawLength)}MB`,
+                verboseOnly: true
+            });
         }
     }
     /**