@memberjunction/core 6.2.0-edge.0 → 6.2.0-edge.2

package/dist/generic/providerBase.js

@@ -195,7 +195,20 @@ export class ProviderBase {
         this._metadataReloadInFlight = null;
         /** Set when a refresh request arrives while a reload is in flight; the reload loop reruns once. */
         this._metadataReloadQueued = false;
+        /** When the last SUCCESSFUL refresh check's status request completed; 0 = never. */
         this._lastRefreshCheckAt = 0;
+        /**
+         * The check currently running in {@link CheckToSeeIfRefreshNeeded}; null when none is. While
+         * set, a non-bypassing caller is answered `false` without a request — the owner of this check
+         * acts on its answer. Held as the promise (not a flag) so only its owner clears it.
+         */
+        this._refreshCheckInFlight = null;
+        /**
+         * Set when Config() adopts a snapshot it loaded from the server (which fetched the current user
+         * with it); consumed by the next {@link preValidateAndRefresh}, which then has nothing to check.
+         */
+        this._configLoadedFromServer = false;
+        this._lastMetadataLoadError = null;
         /**
          * Pending coalesced requests waiting to be flushed.
          * Each entry tracks the original params, contextUser, and a resolver
@@ -227,6 +240,12 @@ export class ProviderBase {
          * hardcoded anywhere in this mechanism.
          */
         this._metadataDatasetEntityNames = null;
+        /**
+         * True only while {@link RefreshWithinTransaction} is reloading. The metadata dataset is
+         * normally read on the pool (#4514); this window joins those reads to the caller's transaction
+         * so a push can see the metadata rows it has not committed yet (MJ#4836).
+         */
+        this._metadataReadsJoinTransaction = false;
         /** Debounce timer for {@link scheduleMetadataMemberRefresh}. */
         this._metadataMemberRefreshTimer = null;
         this._metadataMemberRefreshWaits = 0;
@@ -253,9 +272,22 @@ export class ProviderBase {
      * Minimum interval (ms) between metadata refresh checks to prevent
      * redundant network calls when Config()/RefreshIfNeeded() fire in
      * quick succession (e.g., multiple engines during startup).
+     * The throttle is armed only by a check whose status request succeeded — a check
+     * that threw or got no timestamps proved nothing, so the next caller checks again.
+     * A caller arriving while a check is in flight is told no refresh is needed, as the
+     * in-flight owner acts on the answer (see {@link CheckToSeeIfRefreshNeeded}).
      * Does NOT affect forced Refresh() calls. Default: 30 000 ms.
      */
     static { this.MinRefreshCheckIntervalMs = 30000; }
+    /**
+     * Why the most recent metadata download ({@link GetAllMetadata}) failed; null when it succeeded
+     * or none has run. GetAllMetadata logs and returns undefined on failure so a background refresh
+     * keeps the last good graph; a boot that ends with no metadata reads this to report the cause
+     * (e.g. a user with no roles cannot read `MJ: User Roles`) instead of a generic "nothing loaded".
+     */
+    get LastMetadataLoadError() {
+        return this._lastMetadataLoadError;
+    }
     // ── Server-Side Auto-Cache ────────────────────────────────────────
     /**
      * Maximum row count for auto-caching on the server side. When
@@ -453,6 +485,26 @@ export class ProviderBase {
         this._metadataDatasetEntityNames = names;
         this.ensureInflightViewInvalidation();
     }
+    /**
+     * Whether `entityName` is one of the entities this provider's metadata is built from.
+     * False when the membership set has not been loaded yet — a caller must not treat "unknown"
+     * as "reload". Names are compared case-insensitively, matching the set recorded by
+     * {@link registerMetadataDatasetMembership}.
+     */
+    IsMetadataDatasetMember(entityName) {
+        const name = entityName?.trim().toLowerCase();
+        if (!name || !this._metadataDatasetEntityNames) {
+            return false;
+        }
+        return this._metadataDatasetEntityNames.has(name);
+    }
+    /**
+     * True while {@link RefreshWithinTransaction} is running, so metadata-dataset reads join the
+     * ambient transaction instead of the pool.
+     */
+    get MetadataReadsJoinTransaction() {
+        return this._metadataReadsJoinTransaction;
+    }
     /**
      * 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
@@ -876,8 +928,8 @@ export class ProviderBase {
         // CALLER's objects — reusing params across calls must be safe.
         params = params.map(p => ({ ...p }));
         // Bypass dedup for side-effect calls (SaveViewResults creates DB records)
-        if (this.ShouldBypassDedup(params)) {
-            return this.ExecuteRunViewsPipeline(params, contextUser);
+        if (this.shouldBypassDedup(params)) {
+            return this.executeRunViewsPipeline(params, contextUser);
         }
         // ── Coalescing: merge concurrent RunViews into one mega-batch ──
         if (ProviderBase.CoalesceWindowMs > 0 && !this.TrustLocalCacheCompletely) {
@@ -885,7 +937,7 @@ export class ProviderBase {
             // Server-side trusts its cache (no network calls), so coalescing adds no benefit.
             return this.enqueueCoalescedRunViews(params, contextUser);
         }
-        const key = this.GenerateDedupKey(params, contextUser);
+        const key = this.generateDedupKey(params, contextUser);
         const existing = this._inflightViews.get(key);
         // ── Linger hit: resolved result still within the linger window ──
         if (existing?.resolvedResults && existing.resolvedAt) {
@@ -896,7 +948,7 @@ export class ProviderBase {
                     message: `[Dedup] Linger hit for [${entities}] — returning cached result (age ${age}ms, window ${ProviderBase.DedupLingerMs}ms)`,
                     verboseOnly: true
                 });
-                return existing.resolvedResults.map(r => this.ShallowCopyResult(r));
+                return existing.resolvedResults.map(r => this.shallowCopyResult(r));
             }
             // Linger expired — fall through to fresh execution
             this._inflightViews.delete(key);
@@ -909,10 +961,10 @@ export class ProviderBase {
                 verboseOnly: true
             });
             const results = await existing.promise;
-            return results.map(r => this.ShallowCopyResult(r));
+            return results.map(r => this.shallowCopyResult(r));
         }
         // ── Fresh execution ──
-        const promise = this.ExecuteRunViewsPipeline(params, contextUser)
+        const promise = this.executeRunViewsPipeline(params, contextUser)
             .then(results => {
             // Stash resolved results for the linger window. Safety cap: under
             // extreme churn (hundreds of distinct keys resolving within one linger
@@ -948,14 +1000,14 @@ export class ProviderBase {
         this.ensureInflightViewInvalidation();
         this._inflightViews.set(key, { promise, entityNames: this.collectParamEntityNames(params) });
         const results = await promise;
-        return results.map(r => this.ShallowCopyResult(r));
+        return results.map(r => this.shallowCopyResult(r));
     }
     // ── Dedup helpers ──────────────────────────────────────────────────
     /**
      * The original RunViews execution pipeline (pre-processing, cache,
      * internal execution, post-processing).
      */
-    async ExecuteRunViewsPipeline(params, contextUser) {
+    async executeRunViewsPipeline(params, contextUser) {
         // Pre-processing for batch
         const preResult = await this.PreRunViews(params, contextUser);
         // Check for smart cache check mode
@@ -1027,7 +1079,7 @@ export class ProviderBase {
         if (queue.length === 1) {
             const entry = queue[0];
             try {
-                const results = await this.RunViewsUncoalesced(entry.params, entry.contextUser);
+                const results = await this.runViewsUncoalesced(entry.params, entry.contextUser);
                 entry.resolve(results);
             }
             catch (err) {
@@ -1047,7 +1099,7 @@ export class ProviderBase {
         for (const entry of queue) {
             const entryIndices = [];
             for (const param of entry.params) {
-                const key = this.GenerateDedupKey([param], contextUser);
+                const key = this.generateDedupKey([param], contextUser);
                 let idx = uniqueKeys.get(key);
                 if (idx === undefined) {
                     idx = uniqueParams.length;
@@ -1076,12 +1128,12 @@ export class ProviderBase {
         });
         try {
             // Execute the deduplicated mega-batch as a single pipeline call
-            const uniqueResults = await this.RunViewsUncoalesced(uniqueParams, contextUser);
+            const uniqueResults = await this.runViewsUncoalesced(uniqueParams, contextUser);
             // Route deduped results back to each original caller, preserving order.
             // ShallowCopyResult gives each caller an independent Results array (rows
             // are still shared refs; callers should not mutate rows in place).
             for (let i = 0; i < queue.length; i++) {
-                const callerResults = callerIndexMaps[i].map(idx => this.ShallowCopyResult(uniqueResults[idx]));
+                const callerResults = callerIndexMaps[i].map(idx => this.shallowCopyResult(uniqueResults[idx]));
                 queue[i].resolve(callerResults);
             }
             TelemetryManager.Instance.EndEvent(eventId);
@@ -1208,24 +1260,24 @@ export class ProviderBase {
         const textField = entity.Fields.find(f => f.Type.toLowerCase().includes('varchar') || f.Type.toLowerCase().includes('text'));
         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);
+    async runViewsUncoalesced(params, contextUser) {
+        const key = this.generateDedupKey(params, contextUser);
         const existing = this._inflightViews.get(key);
         // ── Linger hit ──
         if (existing?.resolvedResults && existing.resolvedAt) {
             const age = Date.now() - existing.resolvedAt;
             if (age < ProviderBase.DedupLingerMs) {
-                return existing.resolvedResults.map(r => this.ShallowCopyResult(r));
+                return existing.resolvedResults.map(r => this.shallowCopyResult(r));
             }
             this._inflightViews.delete(key);
         }
         // ── In-flight hit ──
         if (existing && !existing.resolvedResults) {
             const results = await existing.promise;
-            return results.map(r => this.ShallowCopyResult(r));
+            return results.map(r => this.shallowCopyResult(r));
         }
         // ── Fresh execution ──
-        const promise = this.ExecuteRunViewsPipeline(params, contextUser)
+        const promise = this.executeRunViewsPipeline(params, contextUser)
             .then(results => {
             const entry = this._inflightViews.get(key);
             if (entry && entry.promise === promise) {
@@ -1252,7 +1304,7 @@ export class ProviderBase {
         this.ensureInflightViewInvalidation();
         this._inflightViews.set(key, { promise, entityNames: this.collectParamEntityNames(params) });
         const results = await promise;
-        return results.map(r => this.ShallowCopyResult(r));
+        return results.map(r => this.shallowCopyResult(r));
     }
     /**
      * Generates a deterministic dedup key for a batch of RunViewParams.
@@ -1384,11 +1436,11 @@ export class ProviderBase {
         }
         return result;
     }
-    GenerateDedupKey(params, contextUser) {
+    generateDedupKey(params, contextUser) {
         const parts = params.map(p => {
             const base = LocalCacheManager.Instance.GenerateRunViewFingerprint(p, this.InstanceConnectionString);
             const extras = [
-                ProviderBase.NormalizeFieldsKey(p.Fields),
+                ProviderBase.normalizeFieldsKey(p.Fields),
                 p.ResultType ?? 'simple',
                 p.UserSearchString ?? '',
                 p.ViewID ?? '',
@@ -1406,7 +1458,7 @@ export class ProviderBase {
      * semantically identical requests collapse to the same key. Used by both the
      * request-dedup key and the client-side cache fingerprint.
      */
-    static NormalizeFieldsKey(fields) {
+    static normalizeFieldsKey(fields) {
         return fields && fields.length > 0
             ? fields.map(f => f.trim().toLowerCase()).sort().join(',')
             : '*';
@@ -1460,7 +1512,7 @@ export class ProviderBase {
         // This touches ONLY how the slot is keyed. param.Fields is left untouched, so what the
         // provider FETCHES is unchanged — an earlier attempt cleared param.Fields instead and was
         // reverted precisely because fetch behavior could not be verified.
-        const fieldsKey = this.isFullCoverageFieldList(param) ? '*' : ProviderBase.NormalizeFieldsKey(param.Fields);
+        const fieldsKey = this.isFullCoverageFieldList(param) ? '*' : ProviderBase.normalizeFieldsKey(param.Fields);
         const fingerprint = `${base}|f:${fieldsKey}`;
         this._clientFingerprintMemo.set(param, fingerprint);
         return fingerprint;
@@ -1747,7 +1799,7 @@ export class ProviderBase {
      * which means the call has a side effect (creating UserViewRun records)
      * and must not be deduplicated.
      */
-    ShouldBypassDedup(params) {
+    shouldBypassDedup(params) {
         // BypassCache:true MUST bypass the dedup-linger cache as well —
         // otherwise the "skip the cache to see DB truth" contract leaks: a
         // recent identical RunView (within DedupLingerMs) would return its
@@ -1764,7 +1816,7 @@ export class ProviderBase {
      * new array instance (protecting against push/sort/splice by other
      * callers) but the individual row objects inside are shared references.
      */
-    ShallowCopyResult(result) {
+    shallowCopyResult(result) {
         return {
             ...result,
             Results: [...result.Results]
@@ -2330,7 +2382,7 @@ export class ProviderBase {
         if (denied.size === 0) {
             return rows;
         }
-        return ProviderBase.OmitFieldsFromRows(rows, denied);
+        return ProviderBase.omitFieldsFromRows(rows, denied);
     }
     /**
      * Row-loop half of {@link ApplyFieldSecurityProjection}, split out so the policy above reads
@@ -2340,7 +2392,7 @@ export class ProviderBase {
      *
      * @param deniedLowercase field names to omit, already lowercased
      */
-    static OmitFieldsFromRows(rows, deniedLowercase) {
+    static omitFieldsFromRows(rows, deniedLowercase) {
         const probe = rows[0];
         if (!probe || typeof probe !== 'object') {
             return rows;
@@ -3879,6 +3931,9 @@ export class ProviderBase {
      */
     async Config(data, providerToUse) {
         this._ConfigData = data;
+        // Describes THIS Config only: a flag left by an earlier Refresh() must not make the
+        // pre-validation that follows a Config which loaded nothing skip its check.
+        this._configLoadedFromServer = false;
         // Initialize LocalCacheManager early so dataset loading can use the cache.
         // Initialize() is idempotent — subsequent calls (e.g. from StartupManager) are no-ops.
         if (!LocalCacheManager.Instance.IsInitialized) {
@@ -3924,7 +3979,12 @@ export class ProviderBase {
                 return true; // App can proceed immediately with cached metadata
             }
         }
-        if (hardRefresh || await this.CheckToSeeIfRefreshNeeded(providerToUse)) {
+        // An empty graph has nothing to throttle: the throttle exists to stop redundant checks of a
+        // snapshot we already hold. After a status check succeeded but the download that followed
+        // failed, the throttle is armed and a non-bypassing retry would read "current" and load
+        // nothing for the whole window (#4887).
+        const graphIsEmpty = !this._localMetadata?.AllEntities?.length;
+        if (hardRefresh || await this.CheckToSeeIfRefreshNeeded(providerToUse, graphIsEmpty)) {
             // either a hard refresh flag was set within Refresh(), or LocalMetadata is Obsolete
             // 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
@@ -3963,13 +4023,8 @@ export class ProviderBase {
                     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();
+                        await this.adoptServerMetadata(res);
+                        this._configLoadedFromServer = true;
                     }
                     else {
                         // GetAllMetadata failed - log error but keep existing metadata
@@ -3989,6 +4044,19 @@ export class ProviderBase {
         }
         return true;
     }
+    /**
+     * Adopts a metadata snapshot just loaded from the server: swaps it in, records that the
+     * local copy now matches the server's timestamps, and persists it to local storage.
+     *
+     * The swap goes through UpdateLocalMetadata — a single property assignment, atomic in
+     * JavaScript, so readers see the old snapshot until the new one is complete — which keeps
+     * it consistent with LoadLocalMetadataFromStorage() and lets subclasses override it.
+     */
+    async adoptServerMetadata(res) {
+        this.UpdateLocalMetadata(res);
+        this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps; // we just used the server to get all the stuff
+        await this.SaveLocalMetadataToStorage();
+    }
     /**
      * Background validation for the stale-while-revalidate fast-start pattern.
      * Checks if local metadata is still current; if stale, fetches fresh metadata
@@ -4004,9 +4072,7 @@ export class ProviderBase {
                 const res = await this.GetAllMetadata(providerToUse, false);
                 const elapsed = Date.now() - start;
                 if (res) {
-                    this.UpdateLocalMetadata(res);
-                    this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps;
-                    await this.SaveLocalMetadataToStorage();
+                    await this.adoptServerMetadata(res);
                     LogStatusEx({ message: `⚡ [Metadata Cache] Background refresh complete (${elapsed}ms) — metadata updated in place`, verboseOnly: false });
                 }
             }
@@ -4037,9 +4103,22 @@ export class ProviderBase {
      * on RTT). On the warm-stale path we additionally pay the full metadata fetch but
      * avoid serving stale data to the UI in the first place.
      *
+     * On a cold boot, where Config() just loaded the graph (and the current user) from the
+     * server, the first call after that load returns immediately — no check, no current-user
+     * re-fetch. Later calls, and calls after a background refresh, check as usual.
+     *
      * Caller contract: invoke this before `StartupManager.Startup()`.
      */
     async preValidateAndRefresh(providerToUse) {
+        // The snapshot Config just loaded from the server (a cold boot) is current by construction,
+        // and GetAllMetadata fetched CurrentUser with it. Checking again would hit the refresh
+        // throttle, read "current", and re-fetch the same user serially (#4887). One-shot: only the
+        // first pre-validation after that load skips.
+        if (this._configLoadedFromServer) {
+            this._configLoadedFromServer = false;
+            LogStatusEx({ message: `⚡ [Metadata Cache] Pre-validation: metadata was just loaded from the server — skipping`, verboseOnly: true });
+            return;
+        }
         try {
             const needsRefresh = await this.CheckToSeeIfRefreshNeeded(providerToUse);
             if (needsRefresh) {
@@ -4048,9 +4127,7 @@ export class ProviderBase {
                 const res = await this.GetAllMetadata(providerToUse, false);
                 const elapsed = Date.now() - start;
                 if (res) {
-                    this.UpdateLocalMetadata(res);
-                    this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps;
-                    await this.SaveLocalMetadataToStorage();
+                    await this.adoptServerMetadata(res);
                     LogStatusEx({ message: `⚡ [Metadata Cache] Pre-validation refresh complete (${elapsed}ms)`, verboseOnly: false });
                 }
             }
@@ -4213,7 +4290,7 @@ export class ProviderBase {
             const entitiesItem = d?.Success ? d.Results?.find(r => r.Code === 'Entities') : undefined;
             const hasEntities = Array.isArray(entitiesItem?.Results) && entitiesItem.Results.length > 0;
             if (d && d.Success && !hasEntities) {
-                LogError(`GetAllMetadata() - the ${ProviderBase._mjMetadataDatasetName} dataset returned no entities; keeping the metadata already loaded`);
+                this.recordMetadataLoadFailure(new Error(`GetAllMetadata() - the ${ProviderBase._mjMetadataDatasetName} dataset returned no entities; keeping the metadata already loaded`));
             }
             else if (d && d.Success) {
                 // cache the dataset for anyone who wants to use it
@@ -4241,16 +4318,23 @@ export class ProviderBase {
                 // build the base return type
                 const returnMetadata = MetadataFromSimpleObjectWithoutUser(simpleMetadata, this);
                 returnMetadata.CurrentUser = await this.GetCurrentUser();
+                this._lastMetadataLoadError = null;
                 return returnMetadata;
             }
             else {
-                LogError('GetAllMetadata() - Error getting metadata from server' + (d ? ': ' + d.Status : ''));
+                this.recordMetadataLoadFailure(new Error('GetAllMetadata() - Error getting metadata from server' + (d ? ': ' + d.Status : '')));
             }
         }
         catch (e) {
             LogError(e);
+            this._lastMetadataLoadError = e instanceof Error ? e : new Error(String(e));
         }
     }
+    /** Logs a failed metadata download and keeps it for {@link LastMetadataLoadError}. */
+    recordMetadataLoadFailure(error) {
+        LogError(error.message);
+        this._lastMetadataLoadError = error;
+    }
     /**
      * Refreshes the CurrentUser from the server and updates local metadata in place.
      * Useful on warm boot or when user roles/permissions change dynamically without
@@ -4524,6 +4608,24 @@ export class ProviderBase {
         else
             return true; // subclass is telling us not to do any refresh ops right now
     }
+    /**
+     * The same hard reload as {@link Refresh}, but the metadata dataset's reads join the ambient
+     * transaction for the duration of the call (MJ#4836).
+     *
+     * A timer-driven refresh must stay on the pool so it cannot land beside COMMIT (#4514).
+     * The caller that owns the transaction — `mj sync push`, between its own writes — is the
+     * one case that has to see its uncommitted metadata rows, and it waits for this call, so
+     * the read cannot race the commit.
+     */
+    async RefreshWithinTransaction(providerToUse) {
+        this._metadataReadsJoinTransaction = true;
+        try {
+            return await this.Refresh(providerToUse);
+        }
+        finally {
+            this._metadataReadsJoinTransaction = false;
+        }
+    }
     /**
      * Checks if local metadata is out of date and needs refreshing.
      * Compares local timestamps with server timestamps.
@@ -4531,12 +4633,28 @@ export class ProviderBase {
      * 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.
+     * two permission changes made less than the window apart. For the same reason a bypassing
+     * caller always runs its own check, even while another is in flight: that check may have
+     * started before the write.
+     *
+     * The throttle is armed only when the status request succeeded (returned timestamps). A
+     * check that throws or returns no timestamps leaves it unarmed, so a retried boot inside
+     * the window really checks instead of reading "current" and loading nothing (#4887).
+     * A non-bypassing caller arriving while a check is in flight is told no refresh is needed,
+     * as the in-flight owner acts on the answer; that keeps N engines starting together down to
+     * one request. It must not share the owner's answer: a shared `true` would send every caller
+     * into its own full metadata reload (preValidateAndRefresh / backgroundValidateAndRefresh /
+     * RefreshIfNeeded load outside Config's reload single-flight). For the same reason it gets
+     * `false`, not the owner's rejection, when the owner's check throws.
      * @returns True if refresh is needed, false otherwise
      */
     async CheckToSeeIfRefreshNeeded(providerToUse, bypassMinCheckInterval) {
         if (!this.AllowRefresh)
             return false;
+        if (!bypassMinCheckInterval && this._refreshCheckInFlight) {
+            LogStatusEx({ message: `[RefreshCheck] Skipped — a check is already in flight; its caller acts on the answer`, verboseOnly: true });
+            return false;
+        }
         const now = Date.now();
         if (!bypassMinCheckInterval && (now - this._lastRefreshCheckAt) < ProviderBase.MinRefreshCheckIntervalMs) {
             LogStatusEx({
@@ -4545,8 +4663,25 @@ export class ProviderBase {
             });
             return false;
         }
-        this._lastRefreshCheckAt = now;
-        await this.RefreshRemoteMetadataTimestamps(providerToUse);
+        const check = this.runRefreshCheck(providerToUse);
+        this._refreshCheckInFlight = check;
+        try {
+            return await check;
+        }
+        finally {
+            // A bypassing caller may have replaced the slot with its own newer check while this
+            // one ran; only the check that still owns the slot clears it.
+            if (this._refreshCheckInFlight === check) {
+                this._refreshCheckInFlight = null;
+            }
+        }
+    }
+    /** One refresh check: fetch remote timestamps, arm the throttle only on success, compare. */
+    async runRefreshCheck(providerToUse) {
+        const gotTimestamps = await this.RefreshRemoteMetadataTimestamps(providerToUse);
+        if (gotTimestamps) {
+            this._lastRefreshCheckAt = Date.now();
+        }
         await this.LoadLocalMetadataFromStorage();
         return this.LocalMetadataObsolete();
     }