@memberjunction/core 5.51.2 → 5.51.4

package/dist/generic/providerBase.js

@@ -179,6 +179,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.
@@ -203,8 +207,20 @@ 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;
+        /** Guard for {@link logMetadataSnapshotDisabledOnce}. */
+        this._metadataSnapshotSkipLogged = false;
     }
     // ── Metadata Refresh Check Debounce ────────────────────────────────
     /**
@@ -257,19 +273,56 @@ export class ProviderBase {
      * instead of accumulating result arrays in memory.
      */
     static { this.MaxLingerEntries = 500; }
+    // ── Write-invalidation fan-out (process-wide, not per-instance) ────
     /**
-     * Lazily subscribes (once per provider instance) to BaseEntity events so
-     * in-flight/lingered RunView entries touching a written entity are dropped.
-     * Deleting an IN-FLIGHT entry is deliberate: late joiners must not share a
-     * query that may have read pre-commit data; the original caller still gets
-     * its own result, and the orphaned promise's stash step no-ops safely.
+     * Every live provider instance that has opted into write-invalidation, held via
+     * `WeakRef` so registering here never keeps a provider (and everything it
+     * references — connection pool, entity metadata, `_inflightViews`) reachable.
+     * Short-lived providers (one per GraphQL request, one per durable task-graph
+     * task execution — see `MJServer/context.ts` and `TaskGraphProviderFactory`)
+     * become eligible for GC as soon as the request/task finishes; dead refs are
+     * pruned lazily the next time an entity event fires.
      */
-    ensureInflightViewInvalidation() {
-        if (this._lingerInvalidationWired) {
+    static { this._invalidationTargets = new Set(); }
+    /**
+     * The exact event-bus Observable the fan-out is currently subscribed to — identity, not a
+     * boolean "already wired" flag. `MJGlobal.GetEventListener(false)` returns `MJGlobal._events$`,
+     * and BOTH `MJGlobal.Reset()` and `resetMJSingletons()` (which drops the singleton out of the
+     * global object store entirely) replace that field with a fresh `Subject`. A boolean cannot
+     * tell that the bus underneath it changed, so it would leave the fan-out attached to the
+     * orphaned Subject for the rest of the process — no error, just linger entries that silently
+     * stop being invalidated. Comparing the reference detects the swap exactly.
+     */
+    static { this._wiredBus = null; }
+    /**
+     * The live fan-out subscription, retained so a bus swap can unsubscribe the stale one.
+     * Without this, every swap strands a subscriber on the dead Subject — a small instance of
+     * the very leak this fan-out exists to prevent.
+     */
+    static { this._busSubscription = null; }
+    /**
+     * Subscribes exactly ONCE PER EVENT BUS (not once per provider instance) to BaseEntity
+     * events and fans each one out to every still-live registered provider. This is what keeps
+     * the number of `MJGlobal` event-bus subscribers constant regardless of how many short-lived
+     * provider instances get created — subscribing per-instance (the original implementation)
+     * permanently pinned one subscription per instance on the process-wide `Subject`, which never
+     * releases subscribers on its own, so a fresh provider minted on every GraphQL request (or
+     * every durable task-graph task) leaked its entire object graph forever.
+     *
+     * Keyed on the bus's identity rather than a one-shot boolean, because the bus is a
+     * replaceable slot and not a process constant. See {@link _wiredBus}.
+     */
+    static ensureStaticInvalidationSubscription() {
+        const bus = MJGlobal.Instance.GetEventListener(false);
+        if (ProviderBase._wiredBus === bus) {
             return;
         }
-        this._lingerInvalidationWired = true;
-        MJGlobal.Instance.GetEventListener(false).subscribe((event) => {
+        // The bus was replaced (MJGlobal.Reset / singleton clear). Drop the subscriber stranded on
+        // the dead Subject, then attach to the live one. Assign _wiredBus BEFORE subscribing so a
+        // re-entrant call cannot double-wire.
+        ProviderBase._busSubscription?.unsubscribe();
+        ProviderBase._wiredBus = bus;
+        ProviderBase._busSubscription = bus.subscribe((event) => {
             if (event.event !== MJEventType.ComponentEvent || event.eventCode !== BaseEntity.BaseEventCode) {
                 return;
             }
@@ -281,11 +334,42 @@ export class ProviderBase {
                 return;
             }
             const entityName = (entityEvent.baseEntity?.EntityInfo?.Name ?? entityEvent.entityName)?.trim().toLowerCase();
-            if (entityName) {
-                this.invalidateInflightViewsForEntity(entityName);
+            if (!entityName) {
+                return;
+            }
+            for (const ref of ProviderBase._invalidationTargets) {
+                const instance = ref.deref();
+                if (!instance) {
+                    // Provider was GC'd since it registered — prune the dead ref instead of
+                    // letting the registry grow forever with entries that resolve to nothing.
+                    ProviderBase._invalidationTargets.delete(ref);
+                    continue;
+                }
+                instance.invalidateInflightViewsForEntity(entityName);
+                instance.handleMetadataMemberEntityEvent(entityName, entityEvent);
             }
         });
     }
+    /**
+     * Lazily registers this instance (once per provider instance) for write-invalidation
+     * of in-flight/lingered RunView entries touching a written entity. Deleting an IN-FLIGHT
+     * entry is deliberate: late joiners must not share a query that may have read pre-commit
+     * data; the original caller still gets its own result, and the orphaned promise's stash
+     * step no-ops safely.
+     */
+    ensureInflightViewInvalidation() {
+        // Deliberately ABOVE the per-instance guard: the static wiring is re-checked on every call,
+        // not just the first. A long-lived provider (Explorer's client provider, MJServer's system
+        // provider) that registered before a bus swap would otherwise stay wired to the dead Subject
+        // for the rest of the process — short-lived server providers self-heal via the next
+        // request's fresh instance, long-lived ones never would.
+        ProviderBase.ensureStaticInvalidationSubscription();
+        if (this._lingerInvalidationWired) {
+            return;
+        }
+        this._lingerInvalidationWired = true;
+        ProviderBase._invalidationTargets.add(new WeakRef(this));
+    }
     /**
      * Drops every in-flight/lingered RunView entry whose params touch the given
      * entity (lowercased name). Called on BaseEntity save/delete/remote-invalidate.
@@ -313,6 +397,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 wires this instance's write-invalidation event subscription 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();
+    }
+    /**
+     * Write-invalidation 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
@@ -2934,24 +3167,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;
@@ -3171,6 +3442,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) {
@@ -3444,13 +3719,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
@@ -3465,10 +3745,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;
@@ -3927,6 +4210,12 @@ export class ProviderBase {
             const ls = this.LocalStorageProvider;
             if (!ls)
                 return;
+            // Symmetrical with the save: an in-process store can only hand back a copy of the
+            // metadata this heap already holds, at the cost of rebuilding every metadata object.
+            if (!this.MetadataSnapshotPersistenceEnabled) {
+                this.logMetadataSnapshotDisabledOnce();
+                return;
+            }
             const overallStart = Date.now();
             // The metadata snapshot uses three keys (timestamps, format, AllMetadata).
             // Pull them in a single batched read — saves two IDB transaction round-trips
@@ -3935,13 +4224,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
@@ -3987,16 +4294,30 @@ 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.
      * Used for compressed metadata storage/retrieval.
      */
     static base64ToArrayBuffer(base64) {
+        // Node decodes natively; the atob path below allocates an intermediate string and fills the
+        // array a byte at a time.
+        if (typeof Buffer !== 'undefined') {
+            const buf = Buffer.from(base64, 'base64');
+            // Copy into an exact-size buffer: `buf.buffer` is a view into a shared pool, usually
+            // larger than the payload, so returning it directly would carry unrelated bytes and a
+            // wrong byteLength. It is also typed ArrayBufferLike and will not assign to the
+            // declared return type.
+            const exact = new ArrayBuffer(buf.byteLength);
+            new Uint8Array(exact).set(buf);
+            return exact;
+        }
         const binaryString = atob(base64);
         const bytes = new Uint8Array(binaryString.length);
         for (let i = 0; i < binaryString.length; i++) {
@@ -4009,6 +4330,11 @@ export class ProviderBase {
      * Used for compressed metadata storage/retrieval.
      */
     static arrayBufferToBase64(buffer) {
+        // Node encodes natively. The loop below concatenates one character per byte, building a rope
+        // the size of the payload that then has to be flattened.
+        if (typeof Buffer !== 'undefined') {
+            return Buffer.from(buffer).toString('base64');
+        }
         const bytes = new Uint8Array(buffer);
         let binary = '';
         for (let i = 0; i < bytes.byteLength; i++) {
@@ -4024,6 +4350,42 @@ export class ProviderBase {
     get LocalStoragePrefix() {
         return "";
     }
+    /**
+     * Whether anything could read the metadata snapshot back, and therefore whether saving it is
+     * worth the cost.
+     *
+     * The snapshot lets a cold process start from a cached copy of the metadata instead of querying
+     * for it, which only works if the store outlives the writer. Where it does not, both halves of
+     * the round trip are pure cost: the save serializes, gzips and base64-encodes the entire
+     * metadata graph, and the load parses it and rebuilds every `EntityInfo` and `EntityFieldInfo`
+     * from a copy of objects the heap already holds. On a large tenant that is expensive enough to
+     * exhaust the heap.
+     *
+     * A provider that does not declare {@link ILocalStorageProvider.SupportsCrossProcessPersistence}
+     * is treated as persistent, which fails in the safer direction.
+     */
+    get MetadataSnapshotPersistenceEnabled() {
+        const ls = this.LocalStorageProvider;
+        if (!ls) {
+            return false;
+        }
+        return ls.SupportsCrossProcessPersistence !== false;
+    }
+    /**
+     * Explains the skip once per process. The refresh path runs every 30 seconds on a busy server,
+     * so logging per call would bury the one line that matters.
+     */
+    logMetadataSnapshotDisabledOnce() {
+        if (this._metadataSnapshotSkipLogged) {
+            return;
+        }
+        this._metadataSnapshotSkipLogged = true;
+        const name = this.LocalStorageProvider?.constructor?.name ?? 'the local storage provider';
+        LogStatusEx({
+            message: `[Metadata Cache] Snapshot persistence disabled: ${name} is in-process only, so a saved snapshot could never be read back. Skipping the metadata snapshot save and load.`,
+            verboseOnly: false
+        });
+    }
     /**
      * Saves current metadata to local storage for caching.
      * Serializes both timestamps and full metadata collections.
@@ -4033,11 +4395,22 @@ export class ProviderBase {
             const ls = this.LocalStorageProvider;
             if (!ls)
                 return;
+            // Nothing could ever read this snapshot back, so the entire serialize/compress/encode
+            // pass buys nothing. See MetadataSnapshotPersistenceEnabled.
+            if (!this.MetadataSnapshotPersistenceEnabled) {
+                this.logMetadataSnapshotDisabledOnce();
+                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));
+            // 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]));
+            }
             // Serialize the AllMetadata object
             const jsonString = JSON.stringify(this._localMetadata);
             // Attempt compressed storage using native CompressionStream (available in modern browsers and Node 18+)