@memberjunction/core 5.30.0 → 5.31.0

package/dist/generic/providerBase.js

@@ -3,7 +3,7 @@ import { EntityDocumentTypeInfo, EntityInfo } from "./entityInfo.js";
 import { AllMetadata } from "./interfaces.js";
 import { LocalCacheManager } from "./localCacheManager.js";
 import { ApplicationInfo } from "../generic/applicationInfo.js";
-import { AuditLogTypeInfo, AuthorizationInfo, RoleInfo, RowLevelSecurityFilterInfo, UserInfo } from "./securityInfo.js";
+import { AuditLogTypeInfo, AuthorizationInfo, AuthorizationRoleInfo, RoleInfo, RowLevelSecurityFilterInfo, UserInfo } from "./securityInfo.js";
 import { MJGlobal, NormalizeUUID, UUIDsEqual } from "@memberjunction/global";
 import { TelemetryManager } from "./telemetryManager.js";
 import { LogError, LogStatus, LogStatusEx } from "./logging.js";
@@ -93,6 +93,12 @@ export const AllMetadataArrays = [
     { key: 'AllRowLevelSecurityFilters', class: RowLevelSecurityFilterInfo },
     { key: 'AllAuditLogTypes', class: AuditLogTypeInfo },
     { key: 'AllAuthorizations', class: AuthorizationInfo },
+    /**
+     * Flat join-table records linking authorizations to roles.
+     * Consumed lazily by `AuthorizationInfo.Roles` — no post-processing
+     * in `GetAllMetadata` is required.  Mirrors the QueryFields pattern.
+     */
+    { key: 'AllAuthorizationRoles', class: AuthorizationRoleInfo },
     { key: 'AllQueryCategories', class: QueryCategoryInfo },
     { key: 'AllQueries', class: QueryInfo },
     { key: 'AllQueryFields', class: QueryFieldInfo },
@@ -173,35 +179,6 @@ export class ProviderBase {
      * all engines that fire in the same tick, without adding perceptible delay.
      */
     static { this.CoalesceWindowMs = 10; }
-    // ── Fast Startup Mode ─────────────────────────────────────────────
-    /**
-     * When enabled, the first round of RunViews calls after startup will
-     * trust the local IndexedDB/localStorage cache without server validation.
-     * This eliminates the smart cache check round-trips during initial load,
-     * making warm page refreshes near-instant.
-     *
-     * After the first round of engine loads completes, FastStartupMode
-     * automatically disables itself so subsequent data access uses normal
-     * server validation.
-     *
-     * Only applies to client-side providers (TrustLocalCacheCompletely=false).
-     * Set to false to disable.
-     */
-    static { this.FastStartupMode = true; }
-    /** Tracks whether fast startup has been consumed (auto-disables after startup completes) */
-    static { this._fastStartupConsumed = false; }
-    /**
-     * Marks the fast-startup window as closed. After this call, all RunViews
-     * requests will use normal server-validated caching instead of trusting
-     * local IndexedDB unconditionally. Called by StartupManager after all
-     * engines have completed their initial load.
-     */
-    static ConsumeFastStartupMode() {
-        if (!ProviderBase._fastStartupConsumed) {
-            ProviderBase._fastStartupConsumed = true;
-            LogStatusEx({ message: '⚡ [Fast-Start] Startup complete — fast-start mode disabled, server validation re-enabled', verboseOnly: false });
-        }
-    }
     // ── Request Deduplication + Linger Window ──────────────────────────
     /**
      * How long (ms) a resolved RunViews result stays available for instant
@@ -628,10 +605,12 @@ export class ProviderBase {
     async FullTextSearch(params, contextUser) {
         const startTime = Date.now();
         try {
-            const md = new Metadata();
             const maxRows = params.MaxRowsPerEntity ?? 10;
-            // Get all FTS-enabled entities
-            const ftsEntities = this.resolveFTSEntities(md, params.EntityNames);
+            // Use this provider's metadata directly — `this` implements IMetadataProvider, so
+            // its Entities reflect the schema for the database this provider is connected to.
+            // (The previous `new Metadata()` reached for the global default provider, which is
+            // wrong in multi-provider client setups.)
+            const ftsEntities = this.resolveFTSEntities(this, params.EntityNames);
             if (ftsEntities.length === 0) {
                 return {
                     Success: true,
@@ -1075,57 +1054,15 @@ export class ProviderBase {
             Entities: params.map(p => p.EntityName || p.ViewName || p.ViewID).filter(Boolean),
             _fromEngine: fromEngine
         }, contextUser?.ID);
-        // Client-side providers use smart cache check (lightweight server validation)
-        // Server-side providers trust the cache completely and fall through to
-        // the traditional flow which returns cached data immediately on hit.
+        // Client-side providers route any CacheLocal params through smart-cache-check:
+        // a single batched GraphQL call sends fingerprints (hashes + counts) per view,
+        // the server confirms current vs stale, and only stale views return data.
+        // Server-side providers trust the cache completely and fall through to the
+        // traditional flow which returns cached data immediately on hit.
         if (!this.TrustLocalCacheCompletely) {
-            // FastStartupMode: on the first engine load after a page refresh, trust
-            // the local IndexedDB cache without server validation. This eliminates
-            // the RunViewsWithCacheCheck round-trips that dominate warm-load TTI.
-            // After the first batch of engine loads, auto-disable so subsequent
-            // requests use normal server validation for data freshness.
-            const useFastStartup = ProviderBase.FastStartupMode
-                && !ProviderBase._fastStartupConsumed
-                && LocalCacheManager.Instance.IsInitialized
-                && params.some(p => p.CacheLocal);
-            if (useFastStartup) {
-                // Check if we actually have cached data for ALL params.
-                // Use Promise.all to parallelize IndexedDB reads — sequential awaits
-                // cause ~100ms Zone.js scheduling overhead per read, which adds up to
-                // 10+ seconds across 86+ views.
-                const cacheCheckResults = await Promise.all(params.map(async (param) => {
-                    if (!param.CacheLocal)
-                        return true; // non-cached params don't block
-                    const fp = LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
-                    const cached = await LocalCacheManager.Instance.GetRunViewResult(fp);
-                    return cached != null;
-                }));
-                const allHaveCachedData = cacheCheckResults.every(Boolean);
-                if (allHaveCachedData) {
-                    // Do NOT consume the fast-start flag here — multiple engines fire
-                    // RunViews in parallel during StartupManager.Startup(), and each one
-                    // should benefit from the local cache. StartupManager.Startup() will
-                    // call ConsumeFastStartupMode() after all engines complete.
-                    const entityNames = params.map(p => p.EntityName || p.ViewName || '?').join(', ');
-                    LogStatusEx({
-                        message: `⚡ [Fast-Start] Trusting local cache for ${params.length} views [${entityNames}] — skipping server validation`,
-                        verboseOnly: false
-                    });
-                    // Fall through to the traditional flow below which will return cached data
-                }
-                else {
-                    // Not all params have cached data — use normal smart cache check
-                    const useSmartCacheCheck = params.some(p => p.CacheLocal);
-                    if (useSmartCacheCheck) {
-                        return this.prepareSmartCacheCheckParams(params, telemetryEventId, contextUser);
-                    }
-                }
-            }
-            else if (!useFastStartup) {
-                const useSmartCacheCheck = params.some(p => p.CacheLocal);
-                if (useSmartCacheCheck && LocalCacheManager.Instance.IsInitialized) {
-                    return this.prepareSmartCacheCheckParams(params, telemetryEventId, contextUser);
-                }
+            const useSmartCacheCheck = params.some(p => p.CacheLocal);
+            if (useSmartCacheCheck && LocalCacheManager.Instance.IsInitialized) {
+                return this.prepareSmartCacheCheckParams(params, telemetryEventId, contextUser);
             }
         }
         // Traditional caching flow
@@ -1229,11 +1166,13 @@ export class ProviderBase {
      * which will validate if the cache is current or return fresh data.
      */
     async prepareSmartCacheCheckParams(params, telemetryEventId, contextUser) {
-        const smartCacheCheckParams = [];
-        for (const param of params) {
-            // Entity status check
+        // Phase 1 — sync setup: entity status checks, entity_object Fields population,
+        // and fingerprint computation. None of this touches storage; do it serially
+        // so we have the full fingerprint list ready to issue ONE batched IDB read.
+        const cacheable = [];
+        for (let i = 0; i < params.length; i++) {
+            const param = params[i];
             await this.EntityStatusCheck(param, 'PreRunViews');
-            // Handle entity_object result type - need all fields
             if (param.ResultType === 'entity_object') {
                 const entity = this.EntityByName(param.EntityName);
                 if (!entity) {
@@ -1241,22 +1180,28 @@ export class ProviderBase {
                 }
                 param.Fields = entity.Fields.map(f => f.Name);
             }
-            // Build the cache check param with optional cache status
-            let cacheStatus;
             if (param.CacheLocal && LocalCacheManager.Instance.IsInitialized) {
                 const fingerprint = LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
-                const cached = await LocalCacheManager.Instance.GetRunViewResult(fingerprint);
-                if (cached) {
-                    cacheStatus = {
-                        maxUpdatedAt: cached.maxUpdatedAt,
-                        rowCount: cached.rowCount
-                    };
-                }
+                cacheable.push({ paramIndex: i, fingerprint });
+            }
+        }
+        // Phase 2 — batched read: one IDB transaction (or one Redis MGET) returns
+        // every cached entry's status (maxUpdatedAt + rowCount). Was previously N
+        // serialized GetItem calls — for the 8-engine warm-load case this drops
+        // from ~85 transactions to 1.
+        const cacheMap = cacheable.length > 0
+            ? await LocalCacheManager.Instance.GetRunViewResults(cacheable.map(c => c.fingerprint))
+            : new Map();
+        // Phase 3 — assemble per-param cache check entries from the resolved map.
+        const smartCacheCheckParams = params.map(p => ({ params: p }));
+        for (const { paramIndex, fingerprint } of cacheable) {
+            const cached = cacheMap.get(fingerprint);
+            if (cached) {
+                smartCacheCheckParams[paramIndex].cacheStatus = {
+                    maxUpdatedAt: cached.maxUpdatedAt,
+                    rowCount: cached.rowCount,
+                };
             }
-            smartCacheCheckParams.push({
-                params: param,
-                cacheStatus
-            });
         }
         return {
             telemetryEventId,
@@ -1297,8 +1242,23 @@ export class ProviderBase {
                 UserViewRunID: ''
             }));
         }
-        // Process all results in parallel
-        const processingPromises = params.map((param, i) => this.processSingleSmartCacheResult(param, i, response.results, contextUser));
+        // ── Batched cache pre-read for 'current' entries ──────────────────
+        // Each 'current' result needs its cached row data to materialize the response.
+        // Collect every fingerprint up front and issue ONE batched read instead of
+        // letting each per-param processor do its own GetRunViewResult call (~85
+        // serialized IDB transactions in the 8-engine warm-load case).
+        const currentFingerprints = [];
+        for (const sr of response.results) {
+            if (sr.status === 'current' && params[sr.viewIndex]) {
+                currentFingerprints.push(LocalCacheManager.Instance.GenerateRunViewFingerprint(params[sr.viewIndex], this.InstanceConnectionString));
+            }
+        }
+        const preResolvedCache = currentFingerprints.length > 0
+            ? await LocalCacheManager.Instance.GetRunViewResults(currentFingerprints)
+            : new Map();
+        // Process all results in parallel — 'current' entries now read from the
+        // pre-resolved map instead of issuing their own GetRunViewResult calls.
+        const processingPromises = params.map((param, i) => this.processSingleSmartCacheResult(param, i, response.results, preResolvedCache, contextUser));
         const processedResults = await Promise.all(processingPromises);
         // Aggregate telemetry stats
         let cacheHits = 0;
@@ -1322,8 +1282,13 @@ export class ProviderBase {
     /**
      * Processes a single smart cache check result.
      * Handles cache lookup for 'current' items and cache update for 'stale' items.
+     *
+     * @param preResolvedCache - Pre-resolved cache map produced by the batched
+     *   `GetRunViewResults` call in `executeSmartCacheCheck`. Lookups for
+     *   'current' items hit this map instead of issuing per-param IDB reads,
+     *   amortizing IndexedDB transaction overhead across the whole batch.
      */
-    async processSingleSmartCacheResult(param, index, serverResults, contextUser) {
+    async processSingleSmartCacheResult(param, index, serverResults, preResolvedCache, contextUser) {
         const checkResult = serverResults.find(r => r.viewIndex === index);
         if (!checkResult) {
             return {
@@ -1341,9 +1306,11 @@ export class ProviderBase {
             };
         }
         if (checkResult.status === 'current') {
-            // Cache is current - use cached data
+            // Cache is current - use the pre-resolved cache entry from the batched read
+            // (executeSmartCacheCheck reads all 'current' fingerprints in one IDB
+            // transaction up front, so we don't pay per-param transaction overhead here).
             const fingerprint = LocalCacheManager.Instance.GenerateRunViewFingerprint(param, this.InstanceConnectionString);
-            const cached = await LocalCacheManager.Instance.GetRunViewResult(fingerprint);
+            const cached = preResolvedCache.get(fingerprint) ?? null;
             if (cached) {
                 const cachedResult = {
                     Success: true,
@@ -1384,8 +1351,8 @@ export class ProviderBase {
             const primaryKeyFieldName = entity?.FirstPrimaryKey?.Name || 'ID';
             // Apply differential update to cache
             if (param.CacheLocal && checkResult.differentialData && LocalCacheManager.Instance.IsInitialized) {
-                const merged = await LocalCacheManager.Instance.ApplyDifferentialUpdate(fingerprint, param, checkResult.differentialData.updatedRows, checkResult.differentialData.deletedRecordIDs, primaryKeyFieldName, checkResult.maxUpdatedAt || new Date().toISOString(), checkResult.rowCount || 0, checkResult.aggregateResults // Pass fresh aggregate results (can't be differentially computed)
-                );
+                const merged = await LocalCacheManager.Instance.ApplyDifferentialUpdate(fingerprint, param, checkResult.differentialData.updatedRows, checkResult.differentialData.deletedRecordIDs, primaryKeyFieldName, checkResult.maxUpdatedAt || new Date().toISOString(), checkResult.rowCount || 0, checkResult.aggregateResults, // Pass fresh aggregate results (can't be differentially computed)
+                this);
                 if (merged) {
                     const mergedResult = {
                         Success: true,
@@ -1429,7 +1396,7 @@ export class ProviderBase {
                 // Note: We don't await here to avoid blocking the response
                 // Cache update happens in background
                 LocalCacheManager.Instance.SetRunViewResult(fingerprint, param, checkResult.results || [], checkResult.maxUpdatedAt, checkResult.aggregateResults, // Include aggregate results in cache
-                checkResult.rowCount).catch(e => LogError(`Failed to update cache: ${e}`));
+                checkResult.rowCount, this).catch(e => LogError(`Failed to update cache: ${e}`));
             }
             // Transform to entity objects if needed
             await this.TransformSimpleObjectToEntityObject(param, freshResult, contextUser);
@@ -1521,7 +1488,7 @@ export class ProviderBase {
         const postEntityCacheAllowed = this.IsServerCacheAllowedForEntity(params);
         if ((params.CacheLocal || this.TrustLocalCacheCompletely) && postEntityCacheAllowed && 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);
+            await LocalCacheManager.Instance.SetRunViewResult(preResult.fingerprint, params, result.Results, maxUpdatedAt, result.AggregateResults, result.TotalRowCount, this);
         }
         else if (this.shouldAutoCache(params, result)) {
             // Server-side auto-cache: small, unfiltered, unsorted results are
@@ -1529,7 +1496,7 @@ export class ProviderBase {
             // safe for in-place upsert on entity changes (no filter to evaluate).
             const fingerprint = preResult.fingerprint || LocalCacheManager.Instance.GenerateRunViewFingerprint(params, this.InstanceConnectionString);
             const maxUpdatedAt = this.extractMaxUpdatedAt(result.Results);
-            await LocalCacheManager.Instance.SetRunViewResult(fingerprint, params, result.Results, maxUpdatedAt, result.AggregateResults, result.TotalRowCount);
+            await LocalCacheManager.Instance.SetRunViewResult(fingerprint, params, result.Results, 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 });
         }
         // Transform the result set into BaseEntity-derived objects, if needed
@@ -1574,11 +1541,11 @@ export class ProviderBase {
             const batchEntityCacheAllowed = this.IsServerCacheAllowedForEntity(params[i]);
             if ((params[i].CacheLocal || this.TrustLocalCacheCompletely) && batchEntityCacheAllowed && 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));
+                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], results[i].Results, maxUpdatedAt, results[i].AggregateResults, results[i].TotalRowCount, this));
             }
             else if (this.shouldAutoCache(params[i], results[i])) {
                 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));
+                cachePromises.push(LocalCacheManager.Instance.SetRunViewResult(fingerprint, params[i], results[i].Results, 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
@@ -1963,8 +1930,18 @@ export class ProviderBase {
             await LocalCacheManager.Instance.Initialize(storageProvider);
         }
         // first, let's check to see if we have an existing Metadata.Provider registered, if so
-        // unless our data.IgnoreExistingMetadata is set to true, we will not refresh the metadata
-        if (Metadata.Provider && !data.IgnoreExistingMetadata) {
+        // unless our data.IgnoreExistingMetadata is set to true, we will not refresh the metadata.
+        //
+        // ALSO bypass this fast-path when `this._refresh` is set — that flag means the caller
+        // explicitly invoked Refresh() to force a re-fetch (e.g. CodeGen runs Refresh after
+        // manageMetadata mutates the EntityField rows in the DB). Without this guard, Refresh()
+        // calls on the *same instance that's also Metadata.Provider* (the common case after
+        // SetProvider has been called) would short-circuit here and never re-read from the
+        // server, leaving in-memory metadata permanently stale relative to subsequent DB writes.
+        // This was Bug 1 of the 3-bug chain that caused first-run CodeGen on PG to silently
+        // drop CRUD for newly-created entities like SystemEvent — its EntityField rows existed
+        // in the DB but the in-memory snapshot used by the entity-loop never picked them up.
+        if (Metadata.Provider && !data.IgnoreExistingMetadata && !this._refresh) { // global-provider-ok: bootstrap checks for an existing global registration
             // we have an existing globally registered provider AND we are not
             // requested to ignore the existing metadata, so we will not refresh it
             if (this.CopyMetadataFromGlobalProvider()) {
@@ -1983,7 +1960,7 @@ export class ProviderBase {
         if (!this.TrustLocalCacheCompletely && !hardRefresh && !this._localMetadata?.AllEntities?.length) {
             await this.LoadLocalMetadataFromStorage();
             if (this._localMetadata?.AllEntities?.length) {
-                LogStatusEx({ message: `⚡ [Fast-Start] Loaded ${this._localMetadata.AllEntities.length} entities from local cache — deferring server validation`, verboseOnly: false });
+                LogStatusEx({ message: `⚡ [Metadata Cache] Loaded ${this._localMetadata.AllEntities.length} entities from local cache — pre-validating before engine startup`, verboseOnly: false });
                 // Do NOT kick off background validation here — it writes to IndexedDB
                 // which contends with engine RunView cache reads during StartupManager.
                 // Instead, the caller (setupGraphQLClient) should call
@@ -2028,7 +2005,7 @@ export class ProviderBase {
         try {
             const needsRefresh = await this.CheckToSeeIfRefreshNeeded(providerToUse);
             if (needsRefresh) {
-                LogStatusEx({ message: `⚡ [Fast-Start] Background check: metadata is stale — refreshing...`, verboseOnly: false });
+                LogStatusEx({ message: `⚡ [Metadata Cache] Background check: metadata is stale — refreshing...`, verboseOnly: false });
                 const start = Date.now();
                 const res = await this.GetAllMetadata(providerToUse, false);
                 const elapsed = Date.now() - start;
@@ -2036,48 +2013,42 @@ export class ProviderBase {
                     this.UpdateLocalMetadata(res);
                     this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps;
                     await this.SaveLocalMetadataToStorage();
-                    LogStatusEx({ message: `⚡ [Fast-Start] Background refresh complete (${elapsed}ms) — metadata updated in place`, verboseOnly: false });
+                    LogStatusEx({ message: `⚡ [Metadata Cache] Background refresh complete (${elapsed}ms) — metadata updated in place`, verboseOnly: false });
                 }
             }
             else {
-                LogStatusEx({ message: `⚡ [Fast-Start] Background check: metadata is current — no refresh needed`, verboseOnly: false });
+                LogStatusEx({ message: `⚡ [Metadata Cache] Background check: metadata is current — no refresh needed`, verboseOnly: false });
             }
         }
         catch (e) {
-            LogError(`[Fast-Start] Background validation failed: ${e}`);
+            LogError(`[Metadata Cache] Background validation failed: ${e}`);
             // Not critical — app continues with cached metadata
         }
     }
     /**
      * Synchronous pre-validation of cached metadata before engine startup.
      *
-     * This is the deterministic counterpart to {@link backgroundValidateAndRefresh}: instead
-     * of letting engines fast-start against potentially-stale cached data and self-healing
-     * a few seconds later, we make one timestamp round-trip up front. The flow:
+     * On a warm load we serve the metadata graph from IndexedDB so the app can boot
+     * without pulling MBs of metadata from the server. Before engines run, this method
+     * makes one batched timestamp round-trip to confirm the snapshot is still current:
      *
-     *   - **Cached metadata is current** → keep `FastStartupMode` enabled. Engines trust
-     *     their local IndexedDB caches without per-view smart-cache-check round-trips,
-     *     and we have just verified at the framework metadata level that nothing has
-     *     drifted since this client last loaded.
-     *   - **Cached metadata is stale** → refresh framework metadata in place, then call
-     *     {@link ProviderBase.ConsumeFastStartupMode} to disable fast-start. Engines
-     *     proceed through the normal smart-cache-check path so each per-view cache is
-     *     re-validated against the server.
+     *   - **Cached metadata is current** → engines proceed against the cached snapshot.
+     *     Their RunViews calls go through the normal smart-cache-check path which
+     *     batches per-view fingerprints to the server — efficient and authoritative.
+     *   - **Cached metadata is stale** → refresh framework metadata in place before
+     *     engines start, then proceed normally.
      *
      * Cost on the warm-current path is one batched timestamp fetch (~50–200 ms depending
      * on RTT). On the warm-stale path we additionally pay the full metadata fetch but
      * avoid serving stale data to the UI in the first place.
      *
-     * Caller contract: invoke this before `StartupManager.Startup()` so engines see the
-     * correct fast-start state from their first `RunViews()` call. Failures here are
-     * non-fatal — the engine layer's smart-cache-check + event-based invalidation
-     * remain as a safety net.
+     * Caller contract: invoke this before `StartupManager.Startup()`.
      */
     async preValidateAndRefresh(providerToUse) {
         try {
             const needsRefresh = await this.CheckToSeeIfRefreshNeeded(providerToUse);
             if (needsRefresh) {
-                LogStatusEx({ message: `⚡ [Fast-Start] Pre-validation: metadata is stale — refreshing before engine startup and disabling fast-start`, verboseOnly: false });
+                LogStatusEx({ message: `⚡ [Metadata Cache] Pre-validation: metadata is stale — refreshing before engine startup`, verboseOnly: false });
                 const start = Date.now();
                 const res = await this.GetAllMetadata(providerToUse, false);
                 const elapsed = Date.now() - start;
@@ -2085,21 +2056,15 @@ export class ProviderBase {
                     this.UpdateLocalMetadata(res);
                     this._latestLocalMetadataTimestamps = this._latestRemoteMetadataTimestamps;
                     await this.SaveLocalMetadataToStorage();
-                    LogStatusEx({ message: `⚡ [Fast-Start] Pre-validation refresh complete (${elapsed}ms) — engines will smart-cache-check`, verboseOnly: false });
+                    LogStatusEx({ message: `⚡ [Metadata Cache] Pre-validation refresh complete (${elapsed}ms)`, verboseOnly: false });
                 }
-                // Force engines through the normal smart-cache-check path. This re-validates
-                // each per-view IndexedDB cache against the server rather than trusting it.
-                ProviderBase.ConsumeFastStartupMode();
             }
             else {
-                LogStatusEx({ message: `⚡ [Fast-Start] Pre-validation: metadata is current — fast-start engaged`, verboseOnly: false });
+                LogStatusEx({ message: `⚡ [Metadata Cache] Pre-validation: metadata is current`, verboseOnly: false });
             }
         }
         catch (e) {
-            LogError(`[Fast-Start] Pre-validation failed: ${e instanceof Error ? e.message : String(e)} — falling back to smart-cache-check`);
-            // On failure, disable fast-start so engines validate per-view rather than
-            // trusting potentially-stale cache against a known-unknown server state.
-            ProviderBase.ConsumeFastStartupMode();
+            LogError(`[Metadata Cache] Pre-validation failed: ${e instanceof Error ? e.message : String(e)} — engines will smart-cache-check`);
         }
     }
     CloneAllMetadata(toClone) {
@@ -2116,8 +2081,8 @@ export class ProviderBase {
      */
     CopyMetadataFromGlobalProvider() {
         try {
-            if (Metadata.Provider && Metadata.Provider !== this && Metadata.Provider.AllMetadata) {
-                this._localMetadata = this.CloneAllMetadata(Metadata.Provider.AllMetadata);
+            if (Metadata.Provider && Metadata.Provider !== this && Metadata.Provider.AllMetadata) { // global-provider-ok: this method literally clones FROM the global provider on bootstrap
+                this._localMetadata = this.CloneAllMetadata(Metadata.Provider.AllMetadata); // global-provider-ok: bootstrap clone path
                 return true;
             }
             return false;
@@ -2335,6 +2300,16 @@ export class ProviderBase {
     get Authorizations() {
         return this._localMetadata.AllAuthorizations;
     }
+    /**
+     * Gets the flat collection of authorization-role assignments.
+     * Consumed lazily by {@link AuthorizationInfo.Roles} — consumers should
+     * prefer accessing roles through `AuthorizationInfo.Roles` rather than
+     * filtering this array directly.
+     * @returns Array of AuthorizationRoleInfo join-table objects
+     */
+    get AuthorizationRoles() {
+        return this._localMetadata.AllAuthorizationRoles;
+    }
     /**
      * Gets all saved queries in the system.
      * @returns Array of QueryInfo objects representing stored queries
@@ -2488,7 +2463,7 @@ export class ProviderBase {
                 // First overload: entityName, contextUser
                 actualContextUser = loadKeyOrContextUser;
             }
-            const entity = this.Metadata.Entities.find(e => e.Name == entityName);
+            const entity = this.EntityByName(entityName);
             if (entity) {
                 // Use the MJGlobal Class Factory to do our object instantiation - we do NOT use metadata for this anymore, doesn't work well to have file paths with node dynamically at runtime
                 // type reference registration by any module via MJ Global is the way to go as it is reliable across all platforms.
@@ -2560,37 +2535,50 @@ export class ProviderBase {
      * @param itemFilters
      */
     async GetAndCacheDatasetByName(datasetName, itemFilters, contextUser, providerToUse) {
-        // first see if we have anything in cache at all, no reason to check server dates if we dont
-        if (await this.IsDatasetCached(datasetName, itemFilters)) {
-            // FastStartupMode: on warm loads, trust the cached dataset without server validation.
-            // Same pattern as FastStartupMode for RunViews — serve from IndexedDB immediately.
-            if (ProviderBase.FastStartupMode && !this.TrustLocalCacheCompletely) {
-                LogStatusEx({
-                    message: `⚡ [Fast-Start] Serving cached dataset "${datasetName}" from local cache — skipping server validation`,
-                    verboseOnly: false
-                });
-                return this.GetCachedDataset(datasetName, itemFilters);
-            }
-            // compare the local version, if exists to the server version dates
-            if (await this.IsDatasetCacheUpToDate(datasetName, itemFilters)) {
-                // we're up to date, all we need to do is get the local cache and return it
-                return this.GetCachedDataset(datasetName, itemFilters);
-            }
-            else {
-                // we're out of date, so get the dataset from the server
-                const dataset = await this.GetDatasetByName(datasetName, itemFilters, contextUser, providerToUse);
-                // cache it
-                await this.CacheDataset(datasetName, itemFilters, dataset);
-                return dataset;
+        const ls = this.LocalStorageProvider;
+        const key = ls ? this.GetDatasetCacheKey(datasetName, itemFilters) : null;
+        const dateKey = key ? key + '_date' : null;
+        // ── Single batched read: data + date in one IDB transaction ────────────
+        // Previously this path issued 3 sequential reads of the data key (existence
+        // check, staleness check, materialize) plus 1 read of the date key. Now we
+        // pull both keys in one transaction up front and reuse the in-memory data
+        // for staleness checking and the return value.
+        let cachedDataset = null;
+        let cachedDateStr = null;
+        if (ls && key && dateKey) {
+            const both = await ls.GetItems([key, dateKey], 'DatasetCache');
+            const rawData = both.get(key);
+            const rawDate = both.get(dateKey);
+            // Type guards — entries can be either depending on which key matched.
+            // (The cache writes data under `key` and the ISO date string under `dateKey`,
+            // so this is safe so long as the cache hasn't been corrupted.)
+            cachedDataset = (rawData && typeof rawData !== 'string') ? rawData : null;
+            cachedDateStr = (typeof rawDate === 'string') ? rawDate : null;
+        }
+        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()) {
+                // Timestamps suggest cache is fresh; verify per-entity row counts to
+                // catch deleted rows (timestamp comparison alone misses pure deletes).
+                let allCountsMatch = true;
+                for (const eu of status.EntityUpdateDates) {
+                    const localEntity = cachedDataset.Results.find(e => UUIDsEqual(e.EntityID, eu.EntityID));
+                    if (!localEntity || localEntity.Results.length !== eu.RowCount) {
+                        allCountsMatch = false;
+                        break;
+                    }
+                }
+                if (allCountsMatch) {
+                    return cachedDataset;
+                }
             }
         }
-        else {
-            // get the dataset from the server
-            const dataset = await this.GetDatasetByName(datasetName, itemFilters, contextUser, providerToUse);
-            // cache it
-            await this.CacheDataset(datasetName, itemFilters, dataset);
-            return dataset;
-        }
+        // Cold path or stale: fetch from server and cache.
+        const dataset = await this.GetDatasetByName(datasetName, itemFilters, contextUser, providerToUse);
+        await this.CacheDataset(datasetName, itemFilters, dataset);
+        return dataset;
     }
     /**
      * Returns the timestamp of the local cached version of a given datasetName or null if there is no local cache for the
@@ -2664,9 +2652,9 @@ export class ProviderBase {
         const ls = this.LocalStorageProvider;
         if (ls) {
             const key = this.GetDatasetCacheKey(datasetName, itemFilters);
-            const val = await ls.GetItem(key);
-            if (val) {
-                const dataset = JSON.parse(val);
+            // Native object read — IDB structured-clones, localStorage / Redis JSON-decode internally.
+            const dataset = await ls.GetItem(key);
+            if (dataset) {
                 return dataset;
             }
         }
@@ -2681,11 +2669,11 @@ export class ProviderBase {
         const ls = this.LocalStorageProvider;
         if (ls) {
             const key = this.GetDatasetCacheKey(datasetName, itemFilters);
-            const val = JSON.stringify(dataset);
-            await ls.SetItem(key, val);
-            const dateKey = key + '_date';
-            const dateVal = dataset.LatestUpdateDate.toISOString();
-            await ls.SetItem(dateKey, dateVal);
+            // Native object storage — no JSON.stringify on the hot path.
+            await ls.SetItem(key, dataset);
+            // 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());
         }
     }
     /**
@@ -2697,8 +2685,12 @@ export class ProviderBase {
     async IsDatasetCached(datasetName, itemFilters) {
         const ls = this.LocalStorageProvider;
         if (ls) {
+            // Probe via the tiny `_date` ISO-string key instead of pulling the
+            // full multi-MB dataset blob. The two are written together by
+            // CacheDataset, so the date's presence is a faithful proxy for the
+            // data's presence.
             const key = this.GetDatasetCacheKey(datasetName, itemFilters);
-            const val = await ls.GetItem(key);
+            const val = await ls.GetItem(key + '_date');
             return val !== null && val !== undefined;
         }
     }
@@ -2885,18 +2877,25 @@ export class ProviderBase {
             if (!ls)
                 return;
             const overallStart = Date.now();
-            // Load timestamps
-            this._latestLocalMetadataTimestamps = JSON.parse(await ls.GetItem(this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey));
-            // Read raw data from storage
+            // The metadata snapshot uses three keys (timestamps, format, AllMetadata).
+            // Pull them in a single batched read — saves two IDB transaction round-trips
+            // on warm boot. The values are still strings (string storage is intentional
+            // here so the gzip+base64 compression path round-trips cleanly).
+            const tsKey = this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey;
+            const fmtKey = this.LocalStoragePrefix + ProviderBase.localStorageFormatKey;
+            const dataKey = this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey;
             const readStart = Date.now();
-            const raw = await ls.GetItem(this.LocalStoragePrefix + ProviderBase.localStorageAllMetadataKey);
+            const all = await ls.GetItems([tsKey, fmtKey, dataKey]);
             const readMs = Date.now() - readStart;
+            const tsRaw = all.get(tsKey) ?? null;
+            const format = all.get(fmtKey) ?? null;
+            const raw = all.get(dataKey) ?? null;
+            this._latestLocalMetadataTimestamps = tsRaw ? JSON.parse(tsRaw) : null;
             if (!raw)
                 return;
             // Decompress if stored in compressed format, otherwise parse directly
             const parseStart = Date.now();
             let temp;
-            const format = await ls.GetItem(this.LocalStoragePrefix + ProviderBase.localStorageFormatKey);
             if (format === 'gzip' && typeof raw === 'string') {
                 // Compressed path: base64 → binary → gzip decompress → JSON parse
                 const binary = ProviderBase.base64ToArrayBuffer(raw);
@@ -2921,16 +2920,16 @@ export class ProviderBase {
                 this.UpdateLocalMetadata(metadata);
                 const totalMs = Date.now() - overallStart;
                 LogStatusEx({
-                    message: `[Fast-Start Cache] Load complete: read=${readMs}ms, parse=${parseMs}ms, deserialize=${deserializeMs}ms, total=${totalMs}ms, entities=${metadata.AllEntities?.length ?? 0}`,
-                    verboseOnly: false
+                    message: `[Metadata Cache] Load complete: read=${readMs}ms, parse=${parseMs}ms, deserialize=${deserializeMs}ms, total=${totalMs}ms, entities=${metadata.AllEntities?.length ?? 0}`,
+                    verboseOnly: true
                 });
             }
             else {
-                LogError('[Fast-Start Cache] MetadataFromSimpleObject returned undefined — cache deserialization failed. Check console for per-item errors above.');
+                LogError('[Metadata Cache] MetadataFromSimpleObject returned undefined — cache deserialization failed. Check console for per-item errors above.');
             }
         }
         catch (e) {
-            LogError(`[Fast-Start Cache] LoadLocalMetadataFromStorage failed: ${e instanceof Error ? e.message : String(e)}`);
+            LogError(`[Metadata Cache] LoadLocalMetadataFromStorage failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
     static { this.localStorageRootKey = '___MJCore_Metadata'; }
@@ -2984,7 +2983,9 @@ export class ProviderBase {
             if (!ls)
                 return;
             const start = Date.now();
-            // Save timestamps
+            // Save timestamps as a JSON string. The metadata snapshot path intentionally uses
+            // string storage so the compressed (gzip+base64) format below can round-trip cleanly
+            // through providers that don't support binary natively.
             await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageTimestampsKey, JSON.stringify(this._latestLocalMetadataTimestamps));
             // Serialize the AllMetadata object
             const jsonString = JSON.stringify(this._localMetadata);
@@ -3001,14 +3002,14 @@ export class ProviderBase {
                     const elapsed = Date.now() - start;
                     const ratio = jsonString.length > 0 ? (base64.length / jsonString.length * 100).toFixed(1) : '?';
                     LogStatusEx({
-                        message: `[Fast-Start Cache] Save complete: ${elapsed}ms, raw=${(jsonString.length / 1024 / 1024).toFixed(1)}MB, compressed=${(base64.length / 1024 / 1024).toFixed(1)}MB (${ratio}%)`,
-                        verboseOnly: false
+                        message: `[Metadata Cache] Save complete: ${elapsed}ms, raw=${(jsonString.length / 1024 / 1024).toFixed(1)}MB, compressed=${(base64.length / 1024 / 1024).toFixed(1)}MB (${ratio}%)`,
+                        verboseOnly: true
                     });
                     return;
                 }
                 catch (compressErr) {
                     // Compression failed — fall through to uncompressed save
-                    LogError(`[Fast-Start Cache] Compression failed, falling back to uncompressed: ${compressErr instanceof Error ? compressErr.message : String(compressErr)}`);
+                    LogError(`[Metadata Cache] Compression failed, falling back to uncompressed: ${compressErr instanceof Error ? compressErr.message : String(compressErr)}`);
                 }
             }
             // Fallback: uncompressed save (older environments without CompressionStream)
@@ -3016,12 +3017,12 @@ export class ProviderBase {
             await ls.SetItem(this.LocalStoragePrefix + ProviderBase.localStorageFormatKey, 'json');
             const elapsed = Date.now() - start;
             LogStatusEx({
-                message: `[Fast-Start Cache] Save complete (uncompressed): ${elapsed}ms, size=${(jsonString.length / 1024 / 1024).toFixed(1)}MB`,
-                verboseOnly: false
+                message: `[Metadata Cache] Save complete (uncompressed): ${elapsed}ms, size=${(jsonString.length / 1024 / 1024).toFixed(1)}MB`,
+                verboseOnly: true
             });
         }
         catch (e) {
-            LogError(`[Fast-Start Cache] SaveLocalMetadataToStorage failed: ${e instanceof Error ? e.message : String(e)}`);
+            LogError(`[Metadata Cache] SaveLocalMetadataToStorage failed: ${e instanceof Error ? e.message : String(e)}`);
         }
     }
     /**