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

package/dist/generic/providerBase.js

@@ -1,4 +1,5 @@
 import { BaseEntity } from "./baseEntity.js";
+import { IsTransportError } from './transportError.js';
 import { EntityDocumentTypeInfo, EntityFieldTSType, EntityInfo, EntityPermissionType, FieldSecurityDenialMessage, FieldSecurityError } from "./entityInfo.js";
 import { GetEffectiveAlternateBaseViewName, IsExplicitBaseViewOverride } from "./alternateBaseViews.js";
 import { ProviderType, AllMetadata } from "./interfaces.js";
@@ -272,6 +273,14 @@ export class ProviderBase {
         this._clientFingerprintMemo = new WeakMap();
         this._requestDeniedReadFields = new WeakMap();
         this._cachedVisibleExplorerNavigationItems = null;
+        /**
+         * Whether the most recent {@link RefreshRemoteMetadataTimestamps} actually REACHED the
+         * server, regardless of whether it came back with usable timestamps.
+         *
+         * Starts `true` so that nothing reads "unreachable" before a read has been attempted.
+         * See {@link ReadRemoteMetadataTimestamps} for why the distinction exists.
+         */
+        this._lastRemoteTimestampReadReached = true;
         /** Guard for {@link logMetadataSnapshotDisabledOnce}. */
         this._metadataSnapshotSkipLogged = false;
     }
@@ -1087,6 +1096,7 @@ export class ProviderBase {
                 if (params.OnDataChanged && preResult.fingerprint) {
                     preResult.cachedResult.Unsubscribe = LocalCacheManager.Instance.RegisterChangeCallback(preResult.fingerprint, params.OnDataChanged);
                 }
+                ProviderBase.clearSkippedTotalRowCount(params, preResult.cachedResult);
                 return preResult.cachedResult;
             }
             // Cache miss — execute query, then post-process (stores in cache)
@@ -1095,6 +1105,7 @@ export class ProviderBase {
             // PostRunView copies any hook-supplied replacement onto `result` in place, so this
             // reference reflects the hook chain's output.
             await this.PostRunView(result, params, preResult, contextUser);
+            ProviderBase.clearSkippedTotalRowCount(params, result);
             return result;
         }
         // Delegate to RunViews, which uses the smart cache check (lightweight maxUpdatedAt +
@@ -1167,27 +1178,7 @@ export class ProviderBase {
         // ── Fresh execution ──
         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
-            // window) skip lingering rather than hold more result arrays in memory —
-            // the linger is a latency optimization, never a correctness requirement.
-            const entry = this._inflightViews.get(key);
-            if (entry && entry.promise === promise) {
-                if (ProviderBase.DedupLingerMs > 0 && this._inflightViews.size <= ProviderBase.MaxLingerEntries) {
-                    entry.resolvedResults = results;
-                    entry.resolvedAt = Date.now();
-                    // Schedule cleanup after linger expires
-                    setTimeout(() => {
-                        const current = this._inflightViews.get(key);
-                        if (current && current.promise === promise) {
-                            this._inflightViews.delete(key);
-                        }
-                    }, ProviderBase.DedupLingerMs);
-                }
-                else {
-                    this._inflightViews.delete(key);
-                }
-            }
+            this.stashInflightLingerResult(key, promise, results, true);
             return results;
         })
             .catch(err => {
@@ -1204,6 +1195,36 @@ export class ProviderBase {
         return results.map(r => this.shallowCopyResult(r));
     }
     // ── Dedup helpers ──────────────────────────────────────────────────
+    /**
+     * Stashes resolved RunViews results on `_inflightViews` for `DedupLingerMs` and schedules
+     * cleanup via an isolated static `WeakRef` timer helper so the timer closure's V8 lexical
+     * context never retains `this`, `promise`, or `results` on short-lived per-request providers.
+     */
+    stashInflightLingerResult(key, promise, results, enforceMaxEntries) {
+        const entry = this._inflightViews.get(key);
+        if (!entry || entry.promise !== promise) {
+            return;
+        }
+        if (ProviderBase.DedupLingerMs > 0 && (!enforceMaxEntries || this._inflightViews.size <= ProviderBase.MaxLingerEntries)) {
+            const resolvedAt = Date.now();
+            entry.resolvedResults = results;
+            entry.resolvedAt = resolvedAt;
+            ProviderBase.scheduleInflightLingerExpiry(new WeakRef(this), key, resolvedAt);
+        }
+        else {
+            this._inflightViews.delete(key);
+        }
+    }
+    static scheduleInflightLingerExpiry(selfRef, key, resolvedAt) {
+        const timer = setTimeout(() => {
+            const self = selfRef.deref();
+            const current = self?._inflightViews.get(key);
+            if (current && current.resolvedAt === resolvedAt) {
+                self?._inflightViews.delete(key);
+            }
+        }, ProviderBase.DedupLingerMs);
+        timer?.unref?.();
+    }
     /**
      * The original RunViews execution pipeline (pre-processing, cache,
      * internal execution, post-processing).
@@ -1234,12 +1255,32 @@ export class ProviderBase {
         }
         return merged;
     }
+    /**
+     * Keeps the `TotalRowCount` contract on every way out of the pipeline: a caller that passed
+     * `SkipTotalRowCount` gets `undefined`, never a number. Cache hits, the smart-cache check and
+     * the GraphQL wire each rebuild a result and each have a reason to fill in a row count, so the
+     * contract is applied once here rather than at each of those sites.
+     */
+    static clearSkippedTotalRowCount(params, result) {
+        if (result && params.SkipTotalRowCount === true && params.ResultType !== 'count_only') {
+            result.TotalRowCount = undefined;
+        }
+    }
+    /**
+     * Runs a RunViews batch of the views the field-security predicate gate admitted, and applies
+     * the `TotalRowCount` contract to whichever stage produced each result.
+     */
+    async runAdmittedViews(params, preResult, contextUser) {
+        const results = await this.runAdmittedViewStages(params, preResult, contextUser);
+        params.forEach((param, i) => ProviderBase.clearSkippedTotalRowCount(param, results[i]));
+        return results;
+    }
     /**
      * The cache, database and post-processing stages of a RunViews batch, for the views the
      * field-security predicate gate admitted. `params` and every index map in `preResult`
      * describe the same admitted views.
      */
-    async runAdmittedViews(params, preResult, contextUser) {
+    async runAdmittedViewStages(params, preResult, contextUser) {
         // Check for smart cache check mode
         if (preResult.useSmartCacheCheck && preResult.smartCacheCheckParams) {
             return this.executeSmartCacheCheck(params, preResult, contextUser);
@@ -1509,22 +1550,7 @@ export class ProviderBase {
         // ── Fresh execution ──
         const promise = this.executeRunViewsPipeline(params, contextUser)
             .then(results => {
-            const entry = this._inflightViews.get(key);
-            if (entry && entry.promise === promise) {
-                entry.resolvedResults = results;
-                entry.resolvedAt = Date.now();
-                if (ProviderBase.DedupLingerMs > 0) {
-                    setTimeout(() => {
-                        const current = this._inflightViews.get(key);
-                        if (current && current.promise === promise) {
-                            this._inflightViews.delete(key);
-                        }
-                    }, ProviderBase.DedupLingerMs);
-                }
-                else {
-                    this._inflightViews.delete(key);
-                }
-            }
+            this.stashInflightLingerResult(key, promise, results, false);
             return results;
         })
             .catch(err => {
@@ -1584,6 +1610,7 @@ export class ProviderBase {
             return false;
         }
         return !param.BypassCache &&
+            param.CacheLocal !== false &&
             !param.AfterKey &&
             !IsMaterializedDataSource(param.DataSource) &&
             !this.isAlternateBaseViewCacheBypassed(param) &&
@@ -1593,6 +1620,27 @@ export class ProviderBase {
         // Deliberately not user-dependent: field security changes which slot a request uses
         // (the fls: segment), never whether it is cacheable.
     }
+    /**
+     * True when the caller explicitly requested a non-empty `Fields` projection on a plain-object
+     * (`ResultType !== 'entity_object'`) read.
+     */
+    hasNarrowFieldsOverride(param) {
+        return Boolean(param.Fields && param.Fields.length > 0 && param.ResultType !== 'entity_object');
+    }
+    /**
+     * True when a cache-miss read should widen `Fields` to the full entity superset AND populate
+     * `LocalCacheManager` with that superset.
+     *
+     * On the server (`TrustLocalCacheCompletely === true`), cache-allowed entities (`AllowCaching === true`)
+     * widen on miss by default so the Fields-agnostic superset slot serves any future `Fields` subset
+     * (`server-cache` S1 -> S2 -> S3), UNLESS the caller explicitly opts out via `CacheLocal: false` or
+     * `BypassCache: true` (in which case narrow SQL `SELECT` pushdown is preserved end-to-end without
+     * polluting the cache). On the client (`TrustLocalCacheCompletely === false`), only `CacheLocal: true`
+     * widens and caches.
+     */
+    shouldWidenAndPopulateCache(param) {
+        return this.runViewCacheEligible(param);
+    }
     /**
      * True when the request targets an `AlternateBaseView` (explicitly on `param.AlternateBaseView`
      * or pinned on `param.ViewEntity`) whose `CachePolicy` (or an ancestor's `CachePolicy` in its
@@ -1984,6 +2032,7 @@ export class ProviderBase {
             ExtraFilter: filter,
             ResultType: 'simple',
             MaxRows: 1,
+            SkipTotalRowCount: true,
         }, contextUser);
         if (!r.Success || (r.Results?.length ?? 0) === 0)
             return null;
@@ -2092,6 +2141,7 @@ export class ProviderBase {
             Fields: entity.PrimaryKeys.map(pk => pk.Name),
             ResultType: 'simple',
             MaxRows: ids.length,
+            SkipTotalRowCount: true,
         }, contextUser);
         if (!r.Success)
             return new Set();
@@ -2112,7 +2162,10 @@ export class ProviderBase {
         // revoked grants stay visible through the linger window.
         // SaveViewResults bypasses for the original reason: it creates DB
         // records and must not be deduplicated.
-        return params.some(p => p.SaveViewResults === true || p.BypassCache === true);
+        // CacheLocal:false is the server-side opt-out from the RunView cache (read AND write). A
+        // linger hit would hand back rows that were themselves served from that cache, so the
+        // opt-out has to cover the dedup window as well.
+        return params.some(p => p.SaveViewResults === true || p.BypassCache === true || p.CacheLocal === false);
     }
     /**
      * Returns a shallow copy of a RunViewResult: the Results array is a
@@ -2263,7 +2316,8 @@ export class ProviderBase {
                 ...(params.Parameters ?? {}),
                 __maxRows: params.MaxRows ?? -1,
                 __startRow: params.StartRow ?? 0,
-                ...serverSegment
+                ...serverSegment,
+                ...(queryAuth.fieldSecurityKey ? { __fieldSecurity: queryAuth.fieldSecurityKey } : {})
             };
             if (serverSegment !== null) {
                 queryFingerprint = LocalCacheManager.Instance.GenerateRunQueryFingerprint(
@@ -3056,41 +3110,29 @@ export class ProviderBase {
         await this.EntityStatusCheck(params, 'PreRunView', contextUser);
         const entityCheckTime = performance.now() - entityCheckStart;
         // Save the caller's original Fields request for post-cache filtering.
-        // We fetch every field this user's permission class may read, so the cache entry is a
-        // superset for that class: it satisfies any later query for the same entity+filter, by
-        // any user of the same class, regardless of field subset. Slots are keyed per class (the
-        // fls: segment), so no slot is shared between classes at different widths.
+        // When widening happens (full-row read, a cache-eligible read on the server, explicit
+        // CacheLocal: true, or entity_object), we fetch every field this user's permission class
+        // may read so the cache entry is a superset for that class, and project the result back to
+        // the caller's Fields. A narrow Fields read first checks any already-warm superset slot
+        // (0-SQL hit). Only CacheLocal: false or BypassCache: true keep the caller's narrow SQL
+        // projection on a miss, and then nothing is written to the cache.
         const entityLookupStart = performance.now();
-        let callerRequestedFields = params.Fields && params.Fields.length > 0
+        const rawCallerRequestedFields = params.Fields && params.Fields.length > 0
             ? params.Fields.map(f => f.trim().toLowerCase())
             : null; // null = caller wants all fields
-        // Only override Fields to the widened fetch set when caching will actually happen
-        // for this call. For non-cached calls we respect the caller's narrow Fields
-        // end-to-end — there's no cache-coherence concern to preserve. The widened set is
-        // ALL entity fields; a database provider then leaves out the columns this user may
-        // not read, and the slot is keyed by the user's permission class (fls: segment).
         const entity = params.EntityName ? this.EntityByName(params.EntityName) : null;
-        const willCache = this.runViewCacheEligible(params);
-        // entity_object ALWAYS widens, cache-eligible or not: a BaseEntity must hydrate from
-        // every column it is entitled to, or it round-trips partial state into a save. This
-        // must happen here rather than only in the server's PreProcessRunView, which is not on
-        // the client's path — a client entity_object request without CacheLocal would otherwise
-        // ship the caller's narrow Fields over the wire and materialize partial entities. What a
-        // field-restricted user RECEIVES is still their allowed set: the server strips denied
-        // columns on the wire, and the missing keys mark those fields not-loaded.
-        const widenForEntityObject = params.ResultType === 'entity_object';
         if (entity)
             this.ResolveIncludeBinaryFields(params, entity);
-        if (entity && (willCache || widenForEntityObject)) {
-            params.Fields = this.ComputeRunViewFetchFields(entity, params);
-            // Platform contract: explicit Fields always include the primary key(s) —
-            // project back down to requested ∪ PK, matching the direct SQL path.
-            if (callerRequestedFields) {
-                callerRequestedFields = ProviderBase.UnionFieldsWithPrimaryKeys(callerRequestedFields, entity);
-            }
-        }
+        const projectedCallerFields = (rawCallerRequestedFields && entity)
+            ? ProviderBase.UnionFieldsWithPrimaryKeys(rawCallerRequestedFields, entity)
+            : rawCallerRequestedFields;
+        const canReadFromCache = this.runViewCacheEligible(params);
+        const willPopulateCache = this.shouldWidenAndPopulateCache(params) && (!this.hasNarrowFieldsOverride(params) || Boolean(entity));
+        // entity_object ALWAYS widens, cache-eligible or not: a BaseEntity must hydrate from
+        // every column it is entitled to, or it round-trips partial state into a save.
+        const widenForEntityObject = params.ResultType === 'entity_object';
         const entityLookupTime = performance.now() - entityLookupStart;
-        // Check local cache if enabled
+        // Check local cache FIRST if enabled (before any cache-miss Fields widening)
         const cacheCheckStart = performance.now();
         let cacheStatus = 'disabled';
         let cachedResult;
@@ -3106,16 +3148,17 @@ export class ProviderBase {
         // fails closed (or resolves ViewEntity synchronously) to plug that hole.
         const cacheReadDenied = (!!entity && !!contextUser && !(entity.GetUserPermisions(contextUser)?.CanRead ?? false)) ||
             this.cacheDeniedForViewOnlyRequest(params, contextUser);
-        if (willCache && !cacheReadDenied && LocalCacheManager.Instance.IsInitialized) {
+        if (canReadFromCache && !cacheReadDenied && LocalCacheManager.Instance.IsInitialized) {
             fingerprint = this.ComputeRunViewCacheFingerprint(params, contextUser);
             const cached = await LocalCacheManager.Instance.GetRunViewResult(fingerprint);
             if (cached) {
                 // These rows are the cache's shared, deep-frozen objects — the runtime freeze is
                 // what stops a consumer from corrupting the cache. Anything that needs to
                 // transform them must map onto copies.
-                let results = cached.results;
-                if (callerRequestedFields && params.ResultType !== 'entity_object') {
-                    results = ProjectRowsToFields(results, callerRequestedFields);
+                // Materialize any encrypted fields stored as ciphertext at rest before projection.
+                let results = await this.MaterializeCachedRowsForCaller(cached.results, entity, contextUser, Boolean(params.PreserveRestrictedApiCiphertext));
+                if (projectedCallerFields && params.ResultType !== 'entity_object') {
+                    results = ProjectRowsToFields(results, projectedCallerFields);
                 }
                 // Field-level security MUST be applied here, not only in PostRunView: this path
                 // RETURNS (see RunView) without ever calling PostRunView, and it is the exact
@@ -3149,6 +3192,15 @@ export class ProviderBase {
                 cacheStatus = 'miss';
             }
         }
+        // On cache MISS (or uninitialized cache), widen Fields ONLY when populating a superset
+        // cache slot or materializing full BaseEntity objects.
+        let callerRequestedFieldsForPost = null;
+        if (cacheStatus !== 'hit' && entity && (willPopulateCache || widenForEntityObject)) {
+            params.Fields = this.ComputeRunViewFetchFields(entity, params);
+            if (willPopulateCache && projectedCallerFields) {
+                callerRequestedFieldsForPost = projectedCallerFields;
+            }
+        }
         const cacheCheckTime = performance.now() - cacheCheckStart;
         const totalPreTime = performance.now() - preViewStart;
         if (totalPreTime > 50) {
@@ -3159,9 +3211,10 @@ export class ProviderBase {
             cacheStatus,
             cachedResult,
             fingerprint,
-            // Only non-null when params.Fields was actually widened above — tells
+            // Only non-null when params.Fields was actually widened for cache population — tells
             // PostRunView to project cache-miss DB results back to the caller's shape
-            callerRequestedFields: (entity && willCache) ? callerRequestedFields : null
+            callerRequestedFields: callerRequestedFieldsForPost,
+            populateCache: willPopulateCache,
         };
     }
     /**
@@ -3283,6 +3336,7 @@ export class ProviderBase {
         const cacheStatusMap = new Map();
         const callerFieldsMap = new Map();
         const fingerprintMap = new Map();
+        const populateCacheSet = new Set();
         const uncachedParams = [];
         const cachedResults = [];
         let allCached = true;
@@ -3290,31 +3344,22 @@ export class ProviderBase {
             const param = params[i];
             // Entity status check
             await this.EntityStatusCheck(param, 'PreRunViews', contextUser);
-            // Save caller's original Fields, then always fetch all fields from DB.
-            // One cache entry per entity+filter satisfies all field subsets.
-            let callerFields = param.Fields && param.Fields.length > 0
+            // Save caller's original Fields. Consult warm superset cache slots first (0-SQL hit),
+            // and on cache miss widen Fields ONLY when populating a superset cache slot or
+            // materializing BaseEntity instances.
+            const rawCallerFields = param.Fields && param.Fields.length > 0
                 ? param.Fields.map(f => f.trim().toLowerCase())
                 : null;
-            // Only override Fields to the widened fetch set when caching will actually happen
-            // for this call. For non-cached calls we respect the caller's narrow Fields
-            // end-to-end — there's no cache-coherence concern to preserve. Widened = ALL
-            // fields (see PreRunView).
             const batchEntity = param.EntityName ? this.EntityByName(param.EntityName) : null;
-            const batchWillCache = this.runViewCacheEligible(param);
-            // Same entity_object-always-widens rule as the single-view path above.
-            const batchWidenForEntityObject = param.ResultType === 'entity_object';
             if (batchEntity)
                 this.ResolveIncludeBinaryFields(param, batchEntity);
-            if (batchEntity && (batchWillCache || batchWidenForEntityObject)) {
-                param.Fields = this.ComputeRunViewFetchFields(batchEntity, param);
-                // Platform contract: explicit Fields always include the primary key(s)
-                if (callerFields) {
-                    callerFields = ProviderBase.UnionFieldsWithPrimaryKeys(callerFields, batchEntity);
-                    // Remember the caller's original shape so PostRunViews can project
-                    // cache-miss DB results back down to it
-                    callerFieldsMap.set(i, callerFields);
-                }
-            }
+            const projectedCallerFields = (rawCallerFields && batchEntity)
+                ? ProviderBase.UnionFieldsWithPrimaryKeys(rawCallerFields, batchEntity)
+                : rawCallerFields;
+            const batchCanReadCache = this.runViewCacheEligible(param);
+            const batchWillPopulateCache = this.shouldWidenAndPopulateCache(param) && (!this.hasNarrowFieldsOverride(param) || Boolean(batchEntity));
+            // Same entity_object-always-widens rule as the single-view path above.
+            const batchWidenForEntityObject = param.ResultType === 'entity_object';
             // Check local cache if enabled or if server trusts its cache completely
             // BypassCache skips cache entirely — used by maintenance actions querying for
             // records that were inserted via direct SQL (bypassing BaseEntity.Save())
@@ -3324,15 +3369,15 @@ export class ProviderBase {
             // view-only fail-closed gate for ViewID/ViewName-only requests (no resolvable entity).
             const batchCacheReadDenied = (!!batchEntity && !!contextUser && !(batchEntity.GetUserPermisions(contextUser)?.CanRead ?? false)) ||
                 this.cacheDeniedForViewOnlyRequest(param, contextUser);
-            if (batchWillCache && !batchCacheReadDenied && LocalCacheManager.Instance.IsInitialized) {
+            if (batchCanReadCache && !batchCacheReadDenied && LocalCacheManager.Instance.IsInitialized) {
                 const fingerprint = this.ComputeRunViewCacheFingerprint(param, contextUser);
                 fingerprintMap.set(i, fingerprint);
                 const cached = await LocalCacheManager.Instance.GetRunViewResult(fingerprint);
                 if (cached) {
                     // Shared, deep-frozen cache rows — same contract as the single-view hit path.
-                    let results = cached.results;
-                    if (callerFields && param.ResultType !== 'entity_object') {
-                        results = ProjectRowsToFields(results, callerFields);
+                    let results = await this.MaterializeCachedRowsForCaller(cached.results, batchEntity, contextUser, Boolean(param.PreserveRestrictedApiCiphertext));
+                    if (projectedCallerFields && param.ResultType !== 'entity_object') {
+                        results = ProjectRowsToFields(results, projectedCallerFields);
                     }
                     // Field-level security on the batch cache-hit path — same reasoning as the
                     // single-view path in PreRunView: this result is returned without
@@ -3368,6 +3413,15 @@ export class ProviderBase {
             else {
                 cacheStatusMap.set(i, { status: 'disabled' });
             }
+            if (batchWillPopulateCache) {
+                populateCacheSet.add(i);
+            }
+            if (batchEntity && (batchWillPopulateCache || batchWidenForEntityObject)) {
+                param.Fields = this.ComputeRunViewFetchFields(batchEntity, param);
+                if (batchWillPopulateCache && projectedCallerFields) {
+                    callerFieldsMap.set(i, projectedCallerFields);
+                }
+            }
             allCached = false;
             uncachedParams.push(param);
             cachedResults.push(null); // Placeholder for uncached
@@ -3382,7 +3436,8 @@ export class ProviderBase {
             uncachedParams: allCached ? undefined : uncachedParams,
             cacheStatusMap,
             callerFieldsMap: callerFieldsMap.size > 0 ? callerFieldsMap : undefined,
-            fingerprintMap: fingerprintMap.size > 0 ? fingerprintMap : undefined
+            fingerprintMap: fingerprintMap.size > 0 ? fingerprintMap : undefined,
+            populateCacheSet,
         };
     }
     /**
@@ -3762,18 +3817,39 @@ export class ProviderBase {
      * @param preResult - The pre-processing result
      * @param contextUser - Optional user context
      */
+    /**
+     * Hook allowing server database providers to substitute pre-decryption (ciphertext-preserving)
+     * rows before storing view results in {@link LocalCacheManager} / Redis, ensuring decrypted
+     * plaintext secrets are never persisted in local or shared caches.
+     *
+     * Client-side providers inherit this default identity implementation.
+     */
+    PrepareRowsForCacheStorage(rows, _entityInfo) {
+        return rows;
+    }
+    /**
+     * Hook allowing server database providers to decrypt ciphertext-at-rest rows retrieved from
+     * {@link LocalCacheManager} for in-process callers (or selectively preserve restricted
+     * ciphertext when `preserveRestrictedApiCiphertext` is `true`).
+     *
+     * Client-side providers inherit this default identity implementation.
+     */
+    async MaterializeCachedRowsForCaller(rows, _entityInfo, _contextUser, _preserveRestrictedApiCiphertext) {
+        return rows;
+    }
     async PostRunView(result, params, preResult, contextUser) {
         // Store in local cache BEFORE entity transformation — the cache needs
         // plain JSON-serializable objects. BaseEntity objects contain RxJS Subjects
         // with circular subscriber references that break JSON.stringify.
         // On cache read, TransformSimpleObjectToEntityObject is called to restore
         // entity objects when ResultType === 'entity_object'.
-        // runViewCacheEligible is the same predicate PreRunView used to decide whether to
-        // widen Fields — only widened (superset) results may be written to the cache.
-        // preResult.fingerprint doubles as a guard (only computed when eligible).
-        if (this.runViewCacheEligible(params) && result.Success && preResult.fingerprint && LocalCacheManager.Instance.IsInitialized) {
+        // preResult.populateCache records PreRunView's widening decision so narrow Fields
+        // queries (without CacheLocal: true) never poison the Fields-agnostic superset slot.
+        const resolvedEntity = this.resolveEntityForRunViewParams(params);
+        const shouldPopulateSlot = preResult.populateCache ?? this.shouldWidenAndPopulateCache(params);
+        if (shouldPopulateSlot && result.Success && preResult.fingerprint && LocalCacheManager.Instance.IsInitialized) {
             const maxUpdatedAt = this.extractMaxUpdatedAt(result.Results);
-            await LocalCacheManager.Instance.SetRunViewResult(preResult.fingerprint, params, result.Results, maxUpdatedAt, result.AggregateResults, result.TotalRowCount, this);
+            await LocalCacheManager.Instance.SetRunViewResult(preResult.fingerprint, params, this.PrepareRowsForCacheStorage(result.Results, resolvedEntity), maxUpdatedAt, result.AggregateResults, result.TotalRowCount, this);
         }
         else if (this.shouldAutoCache(params, result, contextUser)) {
             // Server-side auto-cache: small, unfiltered, unsorted results are
@@ -3781,7 +3857,7 @@ export class ProviderBase {
             // safe for in-place upsert on entity changes (no filter to evaluate).
             const fingerprint = preResult.fingerprint || this.ComputeRunViewCacheFingerprint(params, contextUser);
             const maxUpdatedAt = this.extractMaxUpdatedAt(result.Results);
-            await LocalCacheManager.Instance.SetRunViewResult(fingerprint, params, result.Results, maxUpdatedAt, result.AggregateResults, result.TotalRowCount, this);
+            await LocalCacheManager.Instance.SetRunViewResult(fingerprint, params, this.PrepareRowsForCacheStorage(result.Results, resolvedEntity), maxUpdatedAt, result.AggregateResults, result.TotalRowCount, this);
             LogStatusEx({ message: `  📦 [Auto-Cache] RunView "${params.EntityName || params.ViewName || 'unknown'}" — ${result.Results.length} rows auto-cached (small + unfiltered)`, verboseOnly: true });
         }
         // Project cache-miss DB results back down to the caller's originally requested
@@ -3857,17 +3933,20 @@ export class ProviderBase {
             // was disabled for them but auto-cache/OnDataChanged may still need it).
             const fingerprint = preResult.fingerprintMap?.get(i)
                 ?? this.ComputeRunViewCacheFingerprint(params[i], contextUser);
-            // CRITICAL: must be the SAME eligibility predicate PreRunViews used to decide
+            // CRITICAL: must reflect the SAME widening predicate PreRunViews used to decide
             // whether to widen Fields. Writing a non-widened (narrow or keyset-paged)
-            // result here poisons the Fields-agnostic superset slot — this exact gate
-            // previously omitted BypassCache/AfterKey and cached narrow BypassCache rows.
-            if (this.runViewCacheEligible(params[i]) && results[i].Success && LocalCacheManager.Instance.IsInitialized) {
+            // result here poisons the Fields-agnostic superset slot.
+            const itemEntity = this.resolveEntityForRunViewParams(params[i]);
+            const shouldPopulateBatchSlot = preResult.populateCacheSet
+                ? preResult.populateCacheSet.has(i)
+                : this.shouldWidenAndPopulateCache(params[i]);
+            if (shouldPopulateBatchSlot && results[i].Success && LocalCacheManager.Instance.IsInitialized) {
                 const maxUpdatedAt = this.extractMaxUpdatedAt(results[i].Results);
-                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], results[i].Results, maxUpdatedAt, results[i].AggregateResults, results[i].TotalRowCount, this));
+                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], this.PrepareRowsForCacheStorage(results[i].Results, itemEntity), maxUpdatedAt, results[i].AggregateResults, results[i].TotalRowCount, this));
             }
             else if (this.shouldAutoCache(params[i], results[i], contextUser)) {
                 const maxUpdatedAt = this.extractMaxUpdatedAt(results[i].Results);
-                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], results[i].Results, maxUpdatedAt, results[i].AggregateResults, results[i].TotalRowCount, this));
+                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], this.PrepareRowsForCacheStorage(results[i].Results, itemEntity), maxUpdatedAt, results[i].AggregateResults, results[i].TotalRowCount, this));
                 LogStatusEx({ message: `    📦 [Auto-Cache] RunViews "${params[i].EntityName || params[i].ViewName || 'unknown'}" — ${results[i].Results.length} rows auto-cached (small + unfiltered)`, verboseOnly: true });
             }
             // Register OnDataChanged callback if provided
@@ -4138,6 +4217,8 @@ export class ProviderBase {
         // main-path variants of those bugs.
         if (!this.runViewCacheEligible(params))
             return false;
+        if (this.hasNarrowFieldsOverride(params))
+            return false;
         if (!LocalCacheManager.Instance.IsInitialized)
             return false;
         if (!result.Success)
@@ -4453,6 +4534,9 @@ export class ProviderBase {
      * Resolves the {@link EntityInfo} normalization should read field types from, using only
      * synchronously available information on the params.
      */
+    resolveEntityForRunViewParams(param) {
+        return this.resolveEntityForNormalization(param);
+    }
     resolveEntityForNormalization(param) {
         if (param.EntityName) {
             return this.EntityByName(param.EntityName);
@@ -5155,6 +5239,13 @@ export class ProviderBase {
             return false; // if we fail to copy the metadata, we will return false
         }
     }
+    /**
+     * Re-adopts the immutable read-only metadata catalog shell and lookup maps from
+     * `Metadata.Provider` after the global provider completes a metadata refresh.
+     */
+    SyncMetadataFromGlobalProvider() {
+        return this.CopyMetadataFromGlobalProvider();
+    }
     /**
      * Builds dataset filters based on the provider configuration.
      * Ensures MJ Core schema is always included and never excluded.
@@ -5584,6 +5675,27 @@ export class ProviderBase {
      * 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
+     *
+     * @remarks
+     * This is a **freshness question, not a load**, so it never throws on an unreachable
+     * server. {@link ReadRemoteMetadataTimestamps} reports whether the server was reached at
+     * all, and when it was NOT the honest answer here depends on whether we hold anything to
+     * serve:
+     *
+     * - **We hold local metadata** → answer `false` ("do not tear this down"). The cached
+     *   snapshot may be a few seconds stale; a rejected status query is no reason to throw
+     *   it away, and every caller of this method treats `false` as "carry on with what you
+     *   have".
+     * - **We hold nothing** → answer `true`, so the caller attempts a real load against the
+     *   actual metadata fetch. That load logs its own failure and leaves the graph empty;
+     *   `SetupGraphQLClient` turns an empty graph into an error carrying it, while a caller
+     *   that only checks {@link Config}'s return value sees `true`.
+     *
+     * Before this, an unreachable status query propagated an exception out of
+     * {@link Config} and the Explorer's single boot catch turned it into a non-retryable
+     * "System Error" — the whole app dead over a freshness check it did not need an answer
+     * to. The two warm callers ({@link backgroundValidateAndRefresh},
+     * {@link preValidateAndRefresh}) already caught it; {@link Config} did not.
      */
     async CheckToSeeIfRefreshNeeded(providerToUse, bypassMinCheckInterval) {
         if (!this.AllowRefresh)
@@ -5622,10 +5734,29 @@ export class ProviderBase {
      */
     async runRefreshCheck(providerToUse) {
         const gotTimestamps = await this.RefreshRemoteMetadataTimestamps(providerToUse);
+        // Read the reachability flag in the SAME synchronous turn the await above resumed in —
+        // before the next await can let a concurrent check overwrite it.
+        const serverReached = this._lastRemoteTimestampReadReached;
         if (gotTimestamps) {
             this._lastRefreshCheckAt = Date.now();
         }
         await this.syncLocalMetadataFromStorage();
+        if (!gotTimestamps && !serverReached) {
+            // Could not ask the server. `LocalMetadataObsolete()` would answer `true` here
+            // purely because the remote timestamp list is empty — a "yes, reload everything"
+            // derived from the absence of an answer rather than from any comparison.
+            const haveLocal = (this._localMetadata?.AllEntities?.length ?? 0) > 0;
+            if (haveLocal) {
+                LogError(`[RefreshCheck] Could not read metadata timestamps from the server — serving the ` +
+                    `cached metadata snapshot (${this._localMetadata.AllEntities.length} entities) and ` +
+                    `deferring the staleness check to the next call.`);
+                return false;
+            }
+            LogError(`[RefreshCheck] Could not read metadata timestamps from the server and there is no ` +
+                `cached snapshot to fall back on — reporting a refresh as needed so the caller loads ` +
+                `metadata; that load reports its own failure.`);
+            return true;
+        }
         return this.LocalMetadataObsolete();
     }
     /**
@@ -5817,8 +5948,30 @@ export class ProviderBase {
         if (cachedDataset && cachedDateStr) {
             // We have a candidate cache entry — confirm freshness with the server.
             const localDate = new Date(cachedDateStr);
-            const status = await this.GetDatasetStatusByName(datasetName, itemFilters);
-            if (status && localDate.getTime() >= status.LatestUpdateDate.getTime()) {
+            let status;
+            try {
+                status = await this.GetDatasetStatusByName(datasetName, itemFilters);
+            }
+            catch (e) {
+                // Only the TRANSPORT failing earns the fallback. A server that answered "no"
+                // (an identity without the scope, a validation rejection) gave a definite
+                // answer that waiting will not change, and the cache would hand the caller
+                // exactly what the server just declined to — so that propagates as it always did.
+                if (!IsTransportError(e)) {
+                    throw e;
+                }
+                // We are HOLDING a complete cached dataset and only asked whether it is still
+                // current. A failed freshness question is not grounds for throwing the answer
+                // away and propagating: the line below re-fetches the whole dataset from the
+                // same unreachable server, so the alternative to serving this cache is an
+                // exception, not fresher data. Serve it and say so.
+                LogError(`GetAndCacheDatasetByName('${datasetName}'): the freshness check failed — ` +
+                    `${e instanceof Error ? e.message : String(e)}. Serving the cached dataset ` +
+                    `(cached ${cachedDateStr}), which may be stale.`);
+                return cachedDataset;
+            }
+            const serverDate = this.validDatasetDate(status?.LatestUpdateDate);
+            if (status?.Success && serverDate && localDate.getTime() >= serverDate.getTime()) {
                 // Timestamps suggest cache is fresh; verify per-entity row counts to
                 // catch deleted rows (timestamp comparison alone misses pure deletes).
                 // Shared with IsDatasetCacheUpToDate so the two cannot drift again.
@@ -5827,9 +5980,11 @@ export class ProviderBase {
                 }
             }
         }
-        // Cold path or stale: fetch from server and cache.
+        // Cold path or stale: fetch from server and cache only when the load succeeded.
         const dataset = await this.GetDatasetByName(datasetName, itemFilters, contextUser, providerToUse);
-        await this.CacheDataset(datasetName, itemFilters, dataset);
+        if (dataset?.Success) {
+            await this.CacheDataset(datasetName, itemFilters, dataset);
+        }
         return dataset;
     }
     /**
@@ -5860,8 +6015,9 @@ export class ProviderBase {
         if (localDate) {
             // we have a local cached timestamp, so compare it to the server timestamp
             const status = await this.GetDatasetStatusByName(datasetName, itemFilters);
-            if (status) {
-                const serverTimestamp = status.LatestUpdateDate.getTime();
+            const serverDate = this.validDatasetDate(status?.LatestUpdateDate);
+            if (status?.Success && serverDate) {
+                const serverTimestamp = serverDate.getTime();
                 if (localDate.getTime() >= serverTimestamp) {
                     // this situation means our local cache timestamp is >= the server timestamp, so we're most likely up to date
                     // in this situation, the last thing we check is for each entity, if the rowcount is the same as the server, if it is, we're good
@@ -5884,6 +6040,17 @@ export class ProviderBase {
             return false;
         }
     }
+    /**
+     * Normalizes a dataset `LatestUpdateDate` to a valid `Date`, or `null` when absent or invalid
+     * (for example, when a dataset or dataset-status call fails and returns `LatestUpdateDate: null`).
+     */
+    validDatasetDate(value) {
+        if (value == null) {
+            return null;
+        }
+        const date = value instanceof Date ? value : new Date(value);
+        return Number.isNaN(date.getTime()) ? null : date;
+    }
     /**
      * Compares the per-entity row counts of a cached dataset against the server's status.
      *
@@ -5942,6 +6109,12 @@ export class ProviderBase {
      * @param dataset
      */
     async CacheDataset(datasetName, itemFilters, dataset) {
+        const latestUpdateDate = this.validDatasetDate(dataset?.LatestUpdateDate);
+        if (!dataset?.Success || !latestUpdateDate) {
+            LogError(`CacheDataset("${datasetName}"): refusing to cache failed or undated dataset result ` +
+                `(Success=${dataset?.Success}, Status=${dataset?.Status ?? 'unknown'})`);
+            return;
+        }
         const ls = this.LocalStorageProvider;
         if (ls) {
             const key = this.GetDatasetCacheKey(datasetName, itemFilters);
@@ -5949,7 +6122,7 @@ export class ProviderBase {
             await ls.SetItem(key, dataset, ProviderBase.DatasetCacheCategory, { TTLSeconds: ProviderBase.DatasetCacheTTLSeconds });
             // Date is stored as ISO string for forward-compatibility across providers
             // (Redis can't natively round-trip Date; localStorage requires string).
-            await ls.SetItem(key + '_date', dataset.LatestUpdateDate.toISOString(), ProviderBase.DatasetCacheCategory, { TTLSeconds: ProviderBase.DatasetDateCacheTTLSeconds });
+            await ls.SetItem(key + '_date', latestUpdateDate.toISOString(), ProviderBase.DatasetCacheCategory, { TTLSeconds: ProviderBase.DatasetDateCacheTTLSeconds });
         }
     }
     /**
@@ -6056,11 +6229,70 @@ export class ProviderBase {
     }
     /**
      * Retrieves the latest metadata update timestamps from the server.
-     * @returns Array of metadata update information
+     * @returns Array of metadata update information, or `undefined` when the server could not
+     * be asked (transport failure, timeout, gateway error) or answered unsuccessfully.
+     *
+     * @remarks
+     * This is the ONE network call behind every staleness check, and it is a question about
+     * freshness — never the metadata itself. A rejected status query therefore returns
+     * `undefined` (an absent answer) rather than propagating: its callers already treat a
+     * falsy result as "could not tell", while an exception out of here travelled unguarded
+     * through {@link RefreshRemoteMetadataTimestamps} → {@link CheckToSeeIfRefreshNeeded} →
+     * {@link Config} and killed the caller's whole bootstrap.
+     *
+     * The failure is logged at error level, not swallowed quietly: "we are running on a
+     * cached snapshot because the server did not answer" is something an operator needs to
+     * see in the console.
      */
     async GetLatestMetadataUpdates(providerToUse) {
-        // No schema filters for metadata — see comment in GetAllMetadata
-        const d = await this.GetDatasetStatusByName(ProviderBase._mjMetadataDatasetName, null, this.CurrentUser, providerToUse);
+        return (await this.ReadRemoteMetadataTimestamps(providerToUse)).Timestamps;
+    }
+    /**
+     * The metadata-status read, with **why** it failed preserved.
+     *
+     * Two failures look the same to {@link GetLatestMetadataUpdates} — both give `undefined` —
+     * but they call for opposite responses, so callers that can act on the difference read it
+     * here instead:
+     *
+     * - `Reached: false` — the request never got an answer (transport failure, timeout, 504).
+     *   Transient. Nothing can be concluded about freshness, and a full metadata load would hit
+     *   the same wall, so the right move is to keep serving what we have.
+     * - `Reached: true` with no `Timestamps` — the server answered `Success: false`. A
+     *   *permanent* condition (the dataset is missing or misconfigured), not a network blip.
+     *   Degrading here would serve a stale cache forever; the historical behaviour of treating
+     *   it as "obsolete" and attempting the real load is correct, because `GetDatasetByName`
+     *   may well still work.
+     * - A rejection that is NOT a transport failure — an authorization denial ("this API key
+     *   requires the dataset:read scope"), a validation rejection, a programming error — is
+     *   the server (or our own code) answering, not the wire failing. It propagates exactly
+     *   as it did before this method existed. {@link IsTransportError} draws the line. The
+     *   integration tier's FLS fixture depends on this: it builds a reader whose scope rule
+     *   has not propagated yet and retries `Config()` until the denial stops — a denial
+     *   swallowed into `Reached: false` left that reader with an empty snapshot for good.
+     *
+     * Conflating these is how a broken status endpoint — or a refused identity — would become
+     * permanently invisible.
+     */
+    async ReadRemoteMetadataTimestamps(providerToUse) {
+        let d;
+        try {
+            // No schema filters for metadata — see comment in GetAllMetadata
+            d = await this.GetDatasetStatusByName(ProviderBase._mjMetadataDatasetName, null, this.CurrentUser, providerToUse);
+        }
+        catch (e) {
+            if (!IsTransportError(e)) {
+                // The server answered — with a refusal. Not ours to soften.
+                throw e;
+            }
+            LogError(`ReadRemoteMetadataTimestamps: the metadata status query failed — ` +
+                `${e instanceof Error ? e.message : String(e)}. Reporting the server as unreachable; ` +
+                `callers fall back to the cached metadata snapshot.`);
+            return { Reached: false, Timestamps: undefined };
+        }
+        return { Reached: true, Timestamps: this.mapDatasetStatusToTimestamps(d) };
+    }
+    /** Shape a dataset-status answer into the timestamp list, or `undefined` if it failed. */
+    mapDatasetStatusToTimestamps(d) {
         if (d && d.Success) {
             const ret = d.EntityUpdateDates.map(e => {
                 return {
@@ -6079,6 +6311,7 @@ export class ProviderBase {
             });
             return ret;
         }
+        return undefined;
     }
     /**
      * Refreshes the remote metadata timestamps from the server.
@@ -6086,9 +6319,14 @@ export class ProviderBase {
      * @returns True if timestamps were successfully refreshed
      */
     async RefreshRemoteMetadataTimestamps(providerToUse) {
-        const mdTimeStamps = await this.GetLatestMetadataUpdates(providerToUse);
-        if (mdTimeStamps) {
-            this._latestRemoteMetadataTimestamps = mdTimeStamps;
+        const read = await this.ReadRemoteMetadataTimestamps(providerToUse);
+        // Recorded rather than returned: this method's `boolean` contract is "did the timestamps
+        // refresh", and widening it would change a public signature that callers outside this
+        // class already consume. {@link CheckToSeeIfRefreshNeeded} reads the flag in the same
+        // synchronous turn this call resolves in, so no interleaving call can overwrite it first.
+        this._lastRemoteTimestampReadReached = read.Reached;
+        if (read.Timestamps) {
+            this._latestRemoteMetadataTimestamps = read.Timestamps;
             return true;
         }
         else