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

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";
@@ -237,6 +238,21 @@ export class ProviderBase {
          */
         this._inflightViews = new Map();
         this._lingerInvalidationWired = false;
+        /**
+         * Per-entity monotonic mutation counter incremented whenever an entity receives a
+         * BaseEntity save/delete/remote-invalidate or an explicit {@link InvalidateRunViewDedupCache}
+         * call. Used by dataset reads (`GetDatasetByName`) to detect that an entity was mutated while
+         * SQL execution or post-processing was in flight and avoid writing stale pre-mutation rows
+         * back into `LocalCacheManager`.
+         */
+        this._entityMutationVersions = new Map();
+        /**
+         * Monotonic counter incremented whenever any metadata-member entity is mutated against this
+         * provider's backend. Checked by `GetAllMetadata()` before caching `MJ_Metadata` into
+         * `DatasetCache` so an in-flight background reload does not overwrite `DatasetCache` with a
+         * pre-mutation snapshot after a save/delete has already landed.
+         */
+        this._metadataMemberMutationSeq = 0;
         /**
          * 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
@@ -272,6 +288,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;
     }
@@ -418,6 +442,23 @@ export class ProviderBase {
             if (!entityName) {
                 return;
             }
+            const cascadeRelatedEntities = [];
+            const isaRelatedEntities = [];
+            const entityInfo = entityEvent.baseEntity?.EntityInfo;
+            if (entityEvent.type === 'delete' && entityInfo?.CascadeDeletes && Array.isArray(entityInfo.RelatedEntities)) {
+                for (const rel of entityInfo.RelatedEntities) {
+                    const relName = rel?.RelatedEntity?.trim().toLowerCase();
+                    const relType = (rel?.Type ?? 'One To Many').trim().toUpperCase();
+                    if (relName && relName !== entityName && relType === 'ONE TO MANY' && !cascadeRelatedEntities.includes(relName)) {
+                        cascadeRelatedEntities.push(relName);
+                    }
+                }
+            }
+            if ((entityEvent.type === 'save' || entityEvent.type === 'delete') && entityInfo) {
+                for (const isaLower of ProviderBase.collectISAHierarchyEntityNamesLower(entityInfo, entityName)) {
+                    isaRelatedEntities.push(isaLower);
+                }
+            }
             for (const ref of ProviderBase._invalidationTargets) {
                 const instance = ref.deref();
                 if (!instance) {
@@ -428,9 +469,50 @@ export class ProviderBase {
                 }
                 instance.invalidateInflightViewsForEntity(entityName);
                 instance.handleMetadataMemberEntityEvent(entityName, entityEvent);
+                for (const relLower of cascadeRelatedEntities) {
+                    instance.invalidateInflightViewsForEntity(relLower);
+                    instance.handleMetadataMemberEntityEvent(relLower, entityEvent);
+                }
+                for (const isaLower of isaRelatedEntities) {
+                    instance.invalidateInflightViewsForEntity(isaLower);
+                    instance.handleMetadataMemberEntityEvent(isaLower, entityEvent);
+                }
             }
         });
     }
+    /**
+     * Collects all lowercased entity names in the same IS-A hierarchy (`ParentEntityInfo` ancestors
+     * and `ChildEntities` descendants) as `entityInfo`, excluding `excludeLower`.
+     */
+    static collectISAHierarchyEntityNamesLower(entityInfo, excludeLower) {
+        if (!entityInfo.IsChildType && !entityInfo.IsParentType) {
+            return [];
+        }
+        let root = entityInfo;
+        const seenAncestors = new Set();
+        while (root.ParentEntityInfo && !seenAncestors.has(root.ParentEntityInfo)) {
+            seenAncestors.add(root);
+            root = root.ParentEntityInfo;
+        }
+        const results = [];
+        const visited = new Set();
+        const queue = [root];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            const lower = current?.Name?.trim().toLowerCase();
+            if (!lower || visited.has(lower)) {
+                continue;
+            }
+            visited.add(lower);
+            if (lower !== excludeLower) {
+                results.push(lower);
+            }
+            if (Array.isArray(current.ChildEntities) && current.ChildEntities.length > 0) {
+                queue.push(...current.ChildEntities);
+            }
+        }
+        return results;
+    }
     /**
      * 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
@@ -451,6 +533,17 @@ export class ProviderBase {
         this._lingerInvalidationWired = true;
         ProviderBase._invalidationTargets.add(new WeakRef(this));
     }
+    /**
+     * Returns the current monotonic mutation version for `entityName` (case-insensitive).
+     */
+    GetEntityMutationVersion(entityName) {
+        this.ensureInflightViewInvalidation();
+        const lower = entityName?.trim().toLowerCase();
+        if (!lower) {
+            return 0;
+        }
+        return this._entityMutationVersions.get(lower) ?? 0;
+    }
     /**
      * Drops this provider's in-flight/lingered RunView dedup entries so the next identical
      * RunView goes to the server instead of replaying a result from the last
@@ -473,6 +566,9 @@ export class ProviderBase {
         const names = (entityNames ?? []).map(n => n?.trim().toLowerCase()).filter((n) => !!n);
         if (names.length === 0) {
             this._inflightViews.clear();
+            for (const [k, v] of this._entityMutationVersions) {
+                this._entityMutationVersions.set(k, v + 1);
+            }
             return;
         }
         for (const n of names) {
@@ -484,6 +580,7 @@ export class ProviderBase {
      * entity (lowercased name). Called on BaseEntity save/delete/remote-invalidate.
      */
     invalidateInflightViewsForEntity(lowerEntityName) {
+        this._entityMutationVersions.set(lowerEntityName, (this._entityMutationVersions.get(lowerEntityName) ?? 0) + 1);
         for (const [key, entry] of this._inflightViews) {
             if (entry.entityNames?.has(lowerEntityName)) {
                 this._inflightViews.delete(key);
@@ -663,6 +760,7 @@ export class ProviderBase {
         if (!this.eventTargetsThisProviderBackend(entityEvent)) {
             return;
         }
+        this._metadataMemberMutationSeq++;
         this.scheduleMetadataMemberRefresh();
     }
     /**
@@ -881,6 +979,14 @@ export class ProviderBase {
             return true;
         }
         this._metadataMemberRefreshWaits = 0;
+        if (this._metadataReloadInFlight) {
+            // A metadata reload is already in flight. Do not call RefreshRemoteMetadataTimestamps()
+            // concurrently here, because that mutates _latestRemoteMetadataTimestamps out from under
+            // the in-flight pass before it runs adoptServerMetadata(). Instead, delegate directly to
+            // ReloadMetadata, which sets _metadataReloadQueued = true and re-reads authoritative
+            // remote timestamps at the start of the queued follow-up pass.
+            return this.ReloadMetadata(true, undefined, true);
+        }
         // The writer holds positive evidence, so the timestamps are re-read from the authoritative
         // status query. When they attribute the change entirely to the saved-query family (see
         // PartialRefreshMetadataItemCodes) only that family is reloaded, cache layers bypassed as a
@@ -1087,6 +1193,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 +1202,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 +1275,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 +1292,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 +1352,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);
@@ -1258,6 +1396,7 @@ export class ProviderBase {
             // allCached ⇒ every param produced a hit and was pushed in order (PreRunViews only
             // pushes a null placeholder on the path that clears allCached), so index i of
             // cachedResults corresponds to params[i].
+            await this.TransformBatchRunViewResults(params, preResult.cachedResults, undefined, preResult.callerFieldsMap, contextUser);
             for (let i = 0; i < preResult.cachedResults.length; i++) {
                 await this.ApplyPostRunViewHooksToCacheHit(params[i], preResult.cachedResults[i], contextUser);
             }
@@ -1509,22 +1648,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 +1708,7 @@ export class ProviderBase {
             return false;
         }
         return !param.BypassCache &&
+            param.CacheLocal !== false &&
             !param.AfterKey &&
             !IsMaterializedDataSource(param.DataSource) &&
             !this.isAlternateBaseViewCacheBypassed(param) &&
@@ -1593,6 +1718,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 +2130,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 +2239,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 +2260,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 +2414,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(
@@ -2280,22 +2432,24 @@ export class ProviderBase {
             queryDefinition = queryAuth.definition;
             // TTL-enforced, and a miss when the slot was written under another query definition.
             const cached = queryFingerprint ? await LocalCacheManager.Instance.GetRunQueryResult(queryFingerprint, queryDefinition) : null;
-            if (cached && queryFingerprint) {
-                const serveFromSlot = () => ({
-                    QueryID: cached.queryId ?? params.QueryID ?? '',
-                    QueryName: params.QueryName ?? '',
-                    Success: true,
-                    // Transport boundary: `cached.results` is readonly (shared, deep-frozen cache
-                    // rows) while the outbound Results is mutable — the runtime freeze is the
-                    // enforcement. Same cast as the RunView hit paths above.
-                    Results: cached.results,
-                    RowCount: cached.results.length,
-                    TotalRowCount: cached.rowCount ?? cached.results.length,
-                    ExecutionTime: 0,
-                    ErrorMessage: '',
-                    CacheHit: true,
-                    CacheKey: queryFingerprint
-                });
+            if (queryFingerprint) {
+                const serveFromSlot = cached
+                    ? () => ({
+                        QueryID: cached.queryId ?? params.QueryID ?? '',
+                        QueryName: params.QueryName ?? '',
+                        Success: true,
+                        // Transport boundary: `cached.results` is readonly (shared, deep-frozen cache
+                        // rows) while the outbound Results is mutable — the runtime freeze is the
+                        // enforcement. Same cast as the RunView hit paths above.
+                        Results: cached.results,
+                        RowCount: cached.results.length,
+                        TotalRowCount: cached.rowCount ?? cached.results.length,
+                        ExecutionTime: 0,
+                        ErrorMessage: '',
+                        CacheHit: true,
+                        CacheKey: queryFingerprint
+                    })
+                    : undefined;
                 const checker = this.RunQueriesWithCacheCheck?.bind(this);
                 if (!checker || this.TrustLocalCacheCompletely) {
                     // TTL mode (server providers / no validation transport).
@@ -2312,69 +2466,71 @@ export class ProviderBase {
                     // authorizes with the proper error message. Query metadata missing from the
                     // provider cache ⇒ ALSO fall through (never serve rows we cannot authorize);
                     // that costs one query run, not correctness.
-                    if (contextUser) {
-                        if (queryAuth.resolvable) {
-                            // Metadata can answer — enforce it. `authorized` comes from the
-                            // provider's STRONGEST available check (B45): the base enforces
-                            // roles-only QueryInfo.UserCanRun; GenericDatabaseProvider's
-                            // override enforces the full MJQueryEntityExtended.UserCanRun
-                            // (roles + entity CanRead + recursive composition) — the identical
-                            // check ValidateQueryForExecution applies on the miss path, so a
-                            // hit is never easier to read than a miss.
-                            if (queryAuth.authorized) {
+                    if (cached && serveFromSlot) {
+                        if (contextUser) {
+                            if (queryAuth.resolvable) {
+                                // Metadata can answer — enforce it. `authorized` comes from the
+                                // provider's STRONGEST available check (B45): the base enforces
+                                // roles-only QueryInfo.UserCanRun; GenericDatabaseProvider's
+                                // override enforces the full MJQueryEntityExtended.UserCanRun
+                                // (roles + entity CanRead + recursive composition) — the identical
+                                // check ValidateQueryForExecution applies on the miss path, so a
+                                // hit is never easier to read than a miss.
+                                if (queryAuth.authorized) {
+                                    return serveFromSlot();
+                                }
+                                LogStatusEx({ message: `RunQuery cache: user '${contextUser.Email}' lacks run permission on '${queryAuth.queryName ?? params.QueryName ?? params.QueryID}' — falling through to authorized execution.`, verboseOnly: true });
+                            }
+                            else if (cached.warmedForUserID && UUIDsEqual(cached.warmedForUserID, contextUser.ID)) {
+                                // Metadata CANNOT answer — runtime-created queries never appear in the
+                                // provider's Queries cache (it does not refresh in-process; verified:
+                                // a saved Query stays invisible, 21 -> 21). But a slot only exists
+                                // because its WARMER executed the fully-authorized miss path — so the
+                                // warmer's own permission is already proven. Serve the warmer;
+                                // anyone ELSE falls through and pays one authorized execution.
+                                //
+                                // The first version of this gate failed closed on unresolvable
+                                // metadata, which silently disabled TTL caching for every
+                                // runtime-created query — caught by Q2/Q5/Q10 going red.
                                 return serveFromSlot();
                             }
-                            LogStatusEx({ message: `RunQuery cache: user '${contextUser.Email}' lacks run permission on '${queryAuth.queryName ?? params.QueryName ?? params.QueryID}' — falling through to authorized execution.`, verboseOnly: true });
-                        }
-                        else if (cached.warmedForUserID && UUIDsEqual(cached.warmedForUserID, contextUser.ID)) {
-                            // Metadata CANNOT answer — runtime-created queries never appear in the
-                            // provider's Queries cache (it does not refresh in-process; verified:
-                            // a saved Query stays invisible, 21 -> 21). But a slot only exists
-                            // because its WARMER executed the fully-authorized miss path — so the
-                            // warmer's own permission is already proven. Serve the warmer;
-                            // anyone ELSE falls through and pays one authorized execution.
-                            //
-                            // The first version of this gate failed closed on unresolvable
-                            // metadata, which silently disabled TTL caching for every
-                            // runtime-created query — caught by Q2/Q5/Q10 going red.
-                            return serveFromSlot();
+                            else {
+                                LogStatusEx({ message: `RunQuery cache: '${params.QueryID ?? params.QueryName}' not in cached metadata and requester is not the slot's warmer — falling through to authorized execution.`, verboseOnly: true });
+                            }
                         }
                         else {
-                            LogStatusEx({ message: `RunQuery cache: '${params.QueryID ?? params.QueryName}' not in cached metadata and requester is not the slot's warmer — falling through to authorized execution.`, verboseOnly: true });
+                            return serveFromSlot();
                         }
                     }
-                    else {
-                        return serveFromSlot();
-                    }
-                }
-                // Client smart validation round trip.
-                //
-                // Guarded on `checker` (R4-2): the block above is entered when `!checker ||
-                // TrustLocalCacheCompletely`. If we got here via `!checker` AND the B43 permission
-                // gate DECLINED to serve (denied user / non-warmer), execution used to fall
-                // straight into `await checker(...)` = `await undefined(...)` — a TypeError instead
-                // of the promised "fall through to authorized execution". Every in-tree provider
-                // implements the optional `RunQueriesWithCacheCheck`, so this was latent, but the
-                // pre-B43 code handled `!checker` and this must too: skip the round trip and let
-                // the normal PreRunQuery/InternalRunQuery path below authorize and execute.
-                if (!checker) {
-                    // fall through to normal execution below
                 }
                 else {
+                    // Client smart validation round trip (both cold first-fetch and warm revalidation).
+                    // Routing cold CacheLocal requests through RunQueriesWithCacheCheck with no cacheStatus
+                    // engages the server's firstFetchWithValidation path so the initial client slot is
+                    // stamped with maxUpdatedAt, rowCount, and definitionHash — allowing the very first
+                    // subsequent refresh (F5) to validate as 'current' instead of missing.
                     const response = await checker([{
                             params,
-                            // '' for a slot written without a hash: the server answers `stale` and returns
-                            // its hash, so the rewrite below stamps the slot.
-                            cacheStatus: { maxUpdatedAt: cached.maxUpdatedAt, rowCount: cached.rowCount, definitionHash: cached.definitionHash ?? '' }
+                            ...(cached
+                                ? {
+                                    // '' for a slot written without a hash: the server answers `stale` and returns
+                                    // its hash, so the rewrite below stamps the slot.
+                                    cacheStatus: {
+                                        maxUpdatedAt: cached.maxUpdatedAt,
+                                        rowCount: cached.rowCount,
+                                        definitionHash: cached.definitionHash ?? ''
+                                    }
+                                }
+                                : {})
                         }], contextUser);
                     const check = response.results?.[0];
                     if (response.success && check) {
-                        if (check.status === 'current') {
+                        if (check.status === 'current' && serveFromSlot) {
                             return serveFromSlot();
                         }
                         if ((check.status === 'stale' || check.status === 'no_validation') && check.results) {
                             const freshRows = check.results;
-                            // Fire-and-forget slot rewrite — same pattern as the RunView client path
+                            // Fire-and-forget slot write/rewrite — same pattern as the RunView client path
                             LocalCacheManager.Instance.SetRunQueryResult(queryFingerprint, params.QueryName ?? '', freshRows, check.maxUpdatedAt ?? '', check.rowCount, check.queryId, params.CacheLocalTTL, contextUser?.ID, check.definitionHash ? { QueryID: check.queryId, Hash: check.definitionHash } : undefined).catch(e => LogError(`RunQuery cache rewrite failed: ${e}`));
                             return {
                                 QueryID: check.queryId ?? params.QueryID ?? '',
@@ -2384,12 +2540,25 @@ export class ProviderBase {
                                 RowCount: freshRows.length,
                                 TotalRowCount: check.rowCount ?? freshRows.length,
                                 ExecutionTime: 0,
-                                ErrorMessage: ''
+                                ErrorMessage: '',
+                                CacheKey: queryFingerprint
+                            };
+                        }
+                        if (check.status === 'error') {
+                            return {
+                                QueryID: check.queryId ?? params.QueryID ?? '',
+                                QueryName: params.QueryName ?? '',
+                                Success: false,
+                                Results: [],
+                                RowCount: 0,
+                                TotalRowCount: 0,
+                                ExecutionTime: 0,
+                                ErrorMessage: check.errorMessage ?? response.errorMessage ?? 'Query execution failed'
                             };
                         }
                     }
+                    // validation transport failed — fall through to a normal execution
                 }
-                // validation transport failed — fall through to a normal execution
             }
         }
         // Pre-processing: telemetry, cache check
@@ -3056,41 +3225,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 +3263,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 +3307,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 +3326,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 +3451,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 +3459,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 +3484,16 @@ 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);
+                        callerFieldsMap.set(i, projectedCallerFields);
                     }
                     // Field-level security on the batch cache-hit path — same reasoning as the
                     // single-view path in PreRunView: this result is returned without
@@ -3351,8 +3512,9 @@ export class ProviderBase {
                         // different Aggregates[] order — remap to THIS caller's requested order.
                         AggregateResults: LocalCacheManager.Instance.ReorderAggregateResultsToRequest(cached.aggregateResults, param.Aggregates)
                     };
-                    // if needed this will transform each result into an entity object
-                    await this.TransformSimpleObjectToEntityObject(param, cachedViewResult, contextUser);
+                    // Entity transformation (`ResultType: 'entity_object'`) is deferred to
+                    // TransformBatchRunViewResults in runAdmittedViewStages / PostRunViews so
+                    // cache hits and DB misses participate together in two-phase sibling IS-A hydration.
                     this.logDeprecatedAlternateBaseViewIfAny(param, 'PreRunViews');
                     if (!param.CacheLocal && this.TrustLocalCacheCompletely) {
                         LogStatusEx({ message: `    ✅ [Server Cache HIT] RunViews "${param.EntityName || param.ViewName || 'unknown'}" — ${cached.results.length} rows served from server cache (no DB query)`, verboseOnly: true });
@@ -3368,6 +3530,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 +3553,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,
         };
     }
     /**
@@ -3518,6 +3690,14 @@ export class ProviderBase {
         // pre-resolved map instead of issuing their own GetRunViewResult calls.
         const processingPromises = params.map((param, i) => this.processSingleSmartCacheResult(param, i, serverResultsByViewIndex.get(i), preResolvedCache, contextUser));
         const processedResults = await Promise.all(processingPromises);
+        const batchResults = processedResults.map(r => r.result);
+        const alreadyTransformedIndices = new Set();
+        for (let i = 0; i < processedResults.length; i++) {
+            if (processedResults[i].alreadyTransformed) {
+                alreadyTransformedIndices.add(i);
+            }
+        }
+        await this.TransformBatchRunViewResults(params, batchResults, alreadyTransformedIndices, undefined, contextUser);
         // Aggregate telemetry stats
         let cacheHits = 0;
         let cacheMisses = 0;
@@ -3535,7 +3715,7 @@ export class ProviderBase {
             cacheMisses,
             batchSize: params.length
         });
-        return processedResults.map(r => r.result);
+        return batchResults;
     }
     /**
      * Processes a single smart cache check result.
@@ -3581,8 +3761,6 @@ export class ProviderBase {
                     // different Aggregates[] order — remap to THIS caller's requested order.
                     AggregateResults: LocalCacheManager.Instance.ReorderAggregateResultsToRequest(cached.aggregateResults, param.Aggregates)
                 };
-                // Transform to entity objects if needed
-                await this.TransformSimpleObjectToEntityObject(param, cachedResult, contextUser);
                 return { result: cachedResult, cacheHit: true, cacheMiss: false };
             }
             else {
@@ -3633,8 +3811,6 @@ export class ProviderBase {
                         // Include aggregate results - either fresh from server or from merged cache
                         AggregateResults: checkResult.aggregateResults || merged.aggregateResults
                     };
-                    // Transform to entity objects if needed
-                    await this.TransformSimpleObjectToEntityObject(param, mergedResult, contextUser);
                     return { result: mergedResult, cacheHit: true, cacheMiss: false };
                 }
             }
@@ -3649,14 +3825,23 @@ export class ProviderBase {
             //     `r.result` straight to the caller, so null became the caller's RESULT.
             //
             // The only correct remedy is what a cache miss does anyway: fetch in full. The
-            // declined slot was already invalidated by ApplyDifferentialUpdate, so the refetch
-            // repopulates it. CacheLocal is stripped and BypassCache set so this single call
-            // takes the plain path — it cannot re-enter the smart-cache transport, which is what
-            // makes the recursion impossible rather than merely unlikely.
+            // declined slot was already invalidated by ApplyDifferentialUpdate, and because
+            // fallbackParam sets CacheLocal:false + BypassCache:true (so the refetch takes the
+            // plain path and cannot re-enter the smart-cache transport), PostRunViews does not
+            // write to LocalCacheManager — so we repopulate the slot explicitly here.
             LogStatusEx({ message: `Differential merge declined for '${param.EntityName}' — refetching in full.`, verboseOnly: true });
             const fallbackParam = { ...param, CacheLocal: false, BypassCache: true };
             const freshFetch = await this.RunView(fallbackParam, contextUser);
-            return { result: freshFetch, cacheHit: false, cacheMiss: true };
+            if (this.runViewCacheEligibleForWrite(param) && freshFetch.Success && LocalCacheManager.Instance.IsInitialized) {
+                const plainRows = (freshFetch.Results || []).map(row => row && typeof row.GetAll === 'function'
+                    ? row.GetAll()
+                    : row);
+                const maxUpdatedAt = checkResult.maxUpdatedAt || this.extractMaxUpdatedAt(plainRows) || '';
+                if (maxUpdatedAt) {
+                    LocalCacheManager.Instance.SetRunViewResult(fingerprint, param, plainRows, maxUpdatedAt, freshFetch.AggregateResults ?? checkResult.aggregateResults, freshFetch.TotalRowCount ?? checkResult.rowCount, this).catch(e => LogError(`Failed to update cache after differential fallback: ${e}`));
+                }
+            }
+            return { result: freshFetch, cacheHit: false, cacheMiss: true, alreadyTransformed: true };
         }
         else if (checkResult.status === 'stale') {
             // Cache is stale - use fresh data and update cache (entity doesn't support differential)
@@ -3681,8 +3866,6 @@ export class ProviderBase {
                 LocalCacheManager.Instance.SetRunViewResult(fingerprint, param, checkResult.results || [], checkResult.maxUpdatedAt, checkResult.aggregateResults, // Include aggregate results in cache
                 checkResult.rowCount, this).catch(e => LogError(`Failed to update cache: ${e}`));
             }
-            // Transform to entity objects if needed
-            await this.TransformSimpleObjectToEntityObject(param, freshResult, contextUser);
             return { result: freshResult, cacheHit: false, cacheMiss: true };
         }
         else {
@@ -3762,18 +3945,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 +3985,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 +4061,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
@@ -3907,17 +4114,8 @@ export class ProviderBase {
             results[i].Results = this.ApplyFieldSecurityProjection(results[i].Results, params[i], contextUser);
             results[i].Results = this.ApplyRecordChangeFieldSecurityProjection(results[i].Results, params[i], contextUser);
         }
-        // Transform results to entity objects AFTER caching plain objects.
-        // Skip results that came from cache hits — they're already entity objects.
-        const transformPromises = [];
-        for (let i = 0; i < results.length; i++) {
-            const cacheInfo = preResult.cacheStatusMap?.get(i);
-            if (cacheInfo?.status === 'hit') {
-                continue;
-            }
-            transformPromises.push(this.TransformSimpleObjectToEntityObject(params[i], results[i], contextUser));
-        }
-        await Promise.all(transformPromises);
+        // Transform results (both cache hits and DB misses) to entity objects AFTER caching plain objects.
+        await this.TransformBatchRunViewResults(params, results, undefined, preResult.callerFieldsMap, contextUser);
         // Run registered PostRunView hooks on each result in the batch
         for (let i = 0; i < results.length; i++) {
             results[i] = await this.RunPostRunViewHooks(params[i], results[i], contextUser);
@@ -4138,6 +4336,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)
@@ -4336,12 +4536,7 @@ export class ProviderBase {
      */
     async PostProcessRunViews(results, params, contextUser) {
         if (params && params.length > 0) {
-            const promises = [];
-            for (let i = 0; i < results.length; i++) {
-                promises.push(this.TransformSimpleObjectToEntityObject(params[i], results[i], contextUser));
-            }
-            // await the promises for all transformations
-            await Promise.all(promises);
+            await this.TransformBatchRunViewResults(params, results, undefined, undefined, contextUser);
             // End telemetry tracking for batch operation
             const eventId = params[0]._telemetryBatchEventId;
             if (eventId) {
@@ -4350,18 +4545,113 @@ export class ProviderBase {
             }
         }
     }
+    /**
+     * Two-phase batch entity transformation for `RunViews`:
+     * 1. Transforms all non-IS-A-parent views in parallel first so lookup tables (`SubtypeSelector`)
+     *    and IS-A child tables in the same batch are hydrated before parent views run.
+     * 2. Registers all unfiltered full-entity views from this batch on `BaseEntity` for the duration
+     *    of Phase 2, then transforms IS-A parent views so they can resolve child records and
+     *    `SubtypeSelector` targets directly from memory with 0 extra queries.
+     */
+    async TransformBatchRunViewResults(params, results, skipTransformIndices, callerFieldsMap, contextUser) {
+        if (!params || params.length === 0) {
+            return;
+        }
+        const nonParentIndices = [];
+        const isaParentIndices = [];
+        for (let i = 0; i < results.length; i++) {
+            if (skipTransformIndices?.has(i)) {
+                continue;
+            }
+            const firstRow = results[i]?.Results?.[0];
+            if (firstRow instanceof BaseEntity) {
+                continue;
+            }
+            const param = params[i];
+            if (!param) {
+                continue;
+            }
+            const entity = param.EntityName ? this.EntityByName(param.EntityName) : undefined;
+            if (param.ResultType === 'entity_object' && entity?.IsParentType && entity.ChildEntities.length > 0) {
+                isaParentIndices.push(i);
+            }
+            else {
+                nonParentIndices.push(i);
+            }
+        }
+        if (nonParentIndices.length > 0) {
+            await Promise.all(nonParentIndices.map(i => this.TransformSimpleObjectToEntityObject(params[i], results[i], contextUser)));
+        }
+        if (isaParentIndices.length === 0) {
+            return;
+        }
+        const batchUnfilteredCache = new Map();
+        for (let i = 0; i < results.length; i++) {
+            const param = params[i];
+            if (param && this.isUnfilteredFullEntityBatchView(param, results[i], callerFieldsMap, i)) {
+                const key = param.EntityName.trim().toLowerCase();
+                if (!batchUnfilteredCache.has(key)) {
+                    batchUnfilteredCache.set(key, results[i].Results);
+                }
+            }
+        }
+        const batchCache = batchUnfilteredCache.size > 0 ? batchUnfilteredCache : undefined;
+        await Promise.all(isaParentIndices.map(i => this.TransformSimpleObjectToEntityObject(params[i], results[i], contextUser, batchCache)));
+    }
+    isUnfilteredFullEntityBatchView(param, result, callerFieldsMap, viewIndex) {
+        if (!param.EntityName || !result?.Success || !Array.isArray(result.Results)) {
+            return false;
+        }
+        if (param.ResultType === 'count_only') {
+            return false;
+        }
+        const filter = typeof param.ExtraFilter === 'string' ? param.ExtraFilter.trim() : '';
+        const search = typeof param.UserSearchString === 'string' ? param.UserSearchString.trim() : '';
+        if (filter.length > 0 || search.length > 0) {
+            return false;
+        }
+        if (param.ViewID || param.ViewName || param.ViewEntity) {
+            return false;
+        }
+        const alternateBaseView = param.AlternateBaseView;
+        if (alternateBaseView && alternateBaseView.trim().length > 0) {
+            return false;
+        }
+        if (param.MaxRows || param.StartRow || param.AfterKey) {
+            return false;
+        }
+        if (typeof result.TotalRowCount === 'number' &&
+            result.TotalRowCount > result.Results.length) {
+            return false;
+        }
+        if (param.IgnoreMaxRows !== true) {
+            const entity = this.EntityByName(param.EntityName);
+            const maxRowsCap = entity?.UserViewMaxRows ?? 0;
+            if (maxRowsCap > 0 && result.Results.length >= maxRowsCap) {
+                return false;
+            }
+        }
+        if (viewIndex !== undefined && callerFieldsMap?.has(viewIndex)) {
+            return false;
+        }
+        if (param.Fields && param.Fields.length > 0 && !this.isFullCoverageFieldList(param)) {
+            return false;
+        }
+        return true;
+    }
     /**
      * Transforms the result set from simple objects to entity objects if needed.
      * @param param - The RunViewParams used for the request
      * @param result - The RunViewResult returned from the request
      * @param contextUser - The user context for permissions
+     * @param batchUnfilteredCache - Optional map of unfiltered full-entity sibling views from the same RunViews call
      */
-    async TransformSimpleObjectToEntityObject(param, result, contextUser) {
+    async TransformSimpleObjectToEntityObject(param, result, contextUser, batchUnfilteredCache) {
         // Mutually exclusive with the entity branch below: entity objects get real types from
         // BaseEntity's Get/Set conversion, so normalization applies only to non-entity results.
         this.NormalizeSimpleRowTypes(param, result);
         if (param.ResultType === 'entity_object' && result && result.Success && result.Results?.length > 0) {
-            result.Results = await TransformSimpleObjectToEntityObject(this, param.EntityName, result.Results, contextUser);
+            result.Results = await TransformSimpleObjectToEntityObject(this, param.EntityName, result.Results, contextUser, batchUnfilteredCache);
             // Opt-in batched child loading: ONE query per named collection across the whole result
             // set, not one per row. Companion eager loading is deliberately kept out of
             // LoadFromData() (which is the per-row path above) precisely so that populating children
@@ -4453,6 +4743,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);
@@ -4786,6 +5079,9 @@ export class ProviderBase {
                 LogWarning(`[Metadata Cache] Row count mismatch when adopting server metadata for "${remoteEntry.Type}": ` +
                     `received ${receivedRowCount} rows but remote status reported ${remoteEntry.RowCount} rows. ` +
                     `Not advancing local timestamp for "${remoteEntry.Type}" so the next check self-heals.`, 'Metadata');
+                if (LocalCacheManager.Instance.IsInitialized && remoteEntry.Type) {
+                    LocalCacheManager.Instance.InvalidateEntityCaches(remoteEntry.Type).catch(() => { });
+                }
                 const priorEntry = prevLocal.find(m => norm(m.Type) === norm(remoteEntry.Type));
                 if (priorEntry) {
                     reconciled.push({
@@ -4813,6 +5109,7 @@ export class ProviderBase {
         if (!hasMismatch) {
             return remote;
         }
+        this.ClearDatasetCache(ProviderBase._mjMetadataDatasetName).catch(() => { });
         const remoteRollup = remote.find(r => norm(r.Type) === rollup);
         if (remoteRollup) {
             const priorRollup = prevLocal.find(m => norm(m.Type) === rollup);
@@ -5155,6 +5452,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.
@@ -5191,6 +5495,40 @@ export class ProviderBase {
         return f;
     }
     static { this._mjMetadataDatasetName = 'MJ_Metadata'; }
+    /**
+     * Checks whether any item in a freshly fetched `MJ_Metadata` dataset has a row count that
+     * disagrees with `_latestRemoteMetadataTimestamps` (when remote timestamps are populated).
+     * Used to prevent `GetAllMetadata()` from caching a dataset snapshot into `DatasetCache`
+     * whose row counts are already stale relative to remote status.
+     */
+    hasDatasetRemoteRowCountMismatch(dataset) {
+        const remote = this._latestRemoteMetadataTimestamps;
+        if (!remote || remote.length === 0 || !Array.isArray(dataset?.Results)) {
+            return false;
+        }
+        const norm = (v) => (v ?? '').trim().toLowerCase();
+        const rollup = norm(ProviderBase._allMetadataTypeName);
+        const nonRollupRemote = remote.filter(r => norm(r.Type) !== rollup);
+        const remoteByID = IndexByUUID(nonRollupRemote.filter(r => Boolean(r.ID)), r => r.ID);
+        const remoteByType = new Map();
+        for (const r of nonRollupRemote) {
+            if (r.Type) {
+                remoteByType.set(norm(r.Type), r);
+            }
+        }
+        for (const item of dataset.Results) {
+            if (!Array.isArray(item.Results)) {
+                continue;
+            }
+            const remoteEntry = (item.EntityID ? remoteByID.Get(item.EntityID) : undefined)
+                ?? remoteByType.get(norm(item.EntityName))
+                ?? remoteByType.get(norm(item.Code));
+            if (remoteEntry && remoteEntry.RowCount !== undefined && item.Results.length !== remoteEntry.RowCount) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Retrieves all metadata from the server and constructs typed instances.
      * Uses the MJ_Metadata dataset for efficient bulk loading.
@@ -5201,6 +5539,7 @@ export class ProviderBase {
             // we are now using datasets instead of the custom metadata to GraphQL to simplify GraphQL's work as it was very slow preivously
             // NOTE: Schema filters (IncludeSchemas/ExcludeSchemas) are for CodeGen only, not for runtime
             // metadata loading. We always load all schemas — there are no sys/staging entities in metadata anyway.
+            const mutationSeqAtStart = this._metadataMemberMutationSeq;
             // Get the dataset and cache it for anyone else who wants to use it
             // When forceRefresh is true (from a hard Refresh() call), bypass LocalCacheManager
             const d = await this.GetDatasetByName(ProviderBase._mjMetadataDatasetName, null, this.CurrentUser, providerToUse, forceRefresh);
@@ -5215,12 +5554,24 @@ export class ProviderBase {
                 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
-                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);
+                // Only cache the dataset in DatasetCache when no metadata-member mutation occurred
+                // while GetDatasetByName was in flight, no follow-up reload is already queued, and
+                // item row counts match _latestRemoteMetadataTimestamps. Otherwise a slow background
+                // GetAllMetadata() that started before a delete can overwrite DatasetCache with
+                // pre-delete rows right after the delete has already completed.
+                const mutatedDuringLoad = this._metadataReloadQueued ||
+                    this._metadataMemberMutationSeq !== mutationSeqAtStart ||
+                    this.hasDatasetRemoteRowCountMismatch(d);
+                if (!mutatedDuringLoad) {
+                    await this.CacheDataset(ProviderBase._mjMetadataDatasetName, null, d);
+                }
+                else {
+                    await this.ClearDatasetCache(ProviderBase._mjMetadataDatasetName);
+                }
                 // got the results, let's build our response in the format we need
                 const simpleMetadata = {};
                 for (let r of d.Results) {
@@ -5584,6 +5935,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 +5994,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 +6208,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 +6240,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 +6275,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 +6300,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 +6369,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 +6382,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 +6489,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 +6571,7 @@ export class ProviderBase {
             });
             return ret;
         }
+        return undefined;
     }
     /**
      * Refreshes the remote metadata timestamps from the server.
@@ -6086,9 +6579,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