@memberjunction/core 6.1.0-edge.2 → 6.1.0-edge.3

package/dist/generic/providerBase.js

@@ -13,7 +13,7 @@ import { LibraryInfo } from "./libraryInfo.js";
 import { CompositeKey } from "./compositeKey.js";
 import { ExplorerNavigationItem } from "./explorerNavigationItem.js";
 import { Metadata } from "./metadata.js";
-import { RunView } from "../views/runView.js";
+import { RunView, IsMaterializedDataSource } from "../views/runView.js";
 import { IsPlatformSQL } from "./platformSQL.js";
 import { GetDataHooks } from "./dataHooks.js";
 import { TransformSimpleObjectToEntityObject } from "./util.js";
@@ -996,15 +996,51 @@ export class ProviderBase {
      *   the seek key, so caching a page would poison the entity+filter slot
      * - `ResultType 'count_only'` — returns no rows; caching its empty Results under
      *   a fingerprint that excludes ResultType would poison row queries
+     * - `DataSource: 'Materialized'` — the snapshot is rebuilt OUT-OF-BAND by the scheduled refresh
+     *   (direct SQL, no BaseEntity save), so the entity's normal event-driven cache invalidation never
+     *   fires for it; a cached materialized result would be served indefinitely stale after a refresh.
+     *   Bypass caching entirely for materialized reads. (The `ds:materialized` fingerprint segment still
+     *   keeps the short-lived dedup/linger layer from cross-serving Live vs Materialized in-flight reads.)
      * - entities where server caching is disallowed
      */
     runViewCacheEligible(param) {
         return !param.BypassCache &&
             !param.AfterKey &&
+            !IsMaterializedDataSource(param.DataSource) &&
             param.ResultType !== 'count_only' &&
             (param.CacheLocal === true || this.TrustLocalCacheCompletely) &&
             this.IsServerCacheAllowedForEntity(param);
     }
+    /** True when the entity is a CodeGen materialized-query wrapper (materialized_vw*) whose snapshot is
+     * refreshed out-of-band — the same one IsServerCacheAllowedForEntity excludes from the server cache. */
+    isMaterializedWrapperEntity(param) {
+        if (!param.EntityName) {
+            return false;
+        }
+        const entity = this.EntityByName(param.EntityName);
+        return !!(entity?.VirtualEntity && entity.BaseView && entity.BaseView.toLowerCase().startsWith('materialized_vw'));
+    }
+    /**
+     * Write-side eligibility for the smart-cache-check (stamped) path. On the trusting SERVER this is
+     * exactly runViewCacheEligible — the server cache is kept fresh by BaseEntity events, so a
+     * server-cache-disallowed entity must never be slotted. On a CLIENT the slot is instead written with
+     * a maxUpdatedAt stamp and DB-revalidated per request, so the server Trust/event gate does NOT apply:
+     * a server-cache-disallowed entity (Trust=0 'MJ: Audit Logs', Record Changes, other caching-disabled)
+     * is still safely client-cacheable when stamped — folding runViewCacheEligible's server gate onto this
+     * path regressed that (integration check client-cache.C12). Materialized reads stay excluded on both
+     * (the out-of-band snapshot swap the stamp can't observe).
+     */
+    runViewCacheEligibleForWrite(param) {
+        if (this.TrustLocalCacheCompletely) {
+            return this.runViewCacheEligible(param);
+        }
+        return !param.BypassCache &&
+            !param.AfterKey &&
+            !IsMaterializedDataSource(param.DataSource) &&
+            param.ResultType !== 'count_only' &&
+            param.CacheLocal === true &&
+            !this.isMaterializedWrapperEntity(param);
+    }
     /**
      * SECURITY — decide whether the shared cache must be BYPASSED for a RunView that targets
      * a saved VIEW rather than a named entity (no `EntityName`), under a context user.
@@ -1515,6 +1551,13 @@ export class ProviderBase {
             // outer CacheLocal layer would otherwise write a SECOND, divergent slot with no/foreign
             // TTL (CacheLocalTTL) — a stale-forever hazard since external data can't be event-invalidated.
             && !this.IsExternalQuery(params)
+            // Materialized query results are excluded for the SAME reason: the snapshot IS the cache
+            // and its freshness is governed by the refresh cycle, not by BaseEntity events, so it can't
+            // be event-invalidated. Layering the outer CacheLocal TTL slot on top would serve rows older
+            // than the latest materialized refresh AND would risk a Live-vs-Materialized slot collision
+            // (the fingerprint carries no DataSource segment). Keeping materialized out of this layer
+            // means the only staleness is the refresh cadence the snapshot already advertises.
+            && !IsMaterializedDataSource(params.DataSource)
             && LocalCacheManager.Instance.IsInitialized;
         let queryFingerprint;
         if (queryCacheEngaged) {
@@ -2113,7 +2156,13 @@ export class ProviderBase {
                 // field list to `*` in the FINGERPRINT only, which cannot affect fetching.
                 param.Fields = entity.Fields.map(f => f.Name);
             }
-            if (param.CacheLocal && LocalCacheManager.Instance.IsInitialized) {
+            // Gate on runViewCacheEligible (NOT raw param.CacheLocal): the smart-cache-check path is a
+            // second, independent cache transport, and gating it on CacheLocal alone re-admits the exact
+            // params runViewCacheEligible excludes — DataSource:'Materialized' (out-of-band refreshed, no
+            // BaseEntity event), count_only, AfterKey, BypassCache, cache-disallowed entities. On a client
+            // (!TrustLocalCacheCompletely) runViewCacheEligible already implies CacheLocal===true, so this is
+            // strictly a tightening — normal cacheable slots are unaffected.
+            if (this.runViewCacheEligibleForWrite(param) && LocalCacheManager.Instance.IsInitialized) {
                 cacheable.push({ paramIndex: i, fingerprint: this.clientCacheFingerprint(param) });
             }
         }
@@ -2289,8 +2338,9 @@ export class ProviderBase {
             // Get entity info for primary key field name
             const entity = this.EntityByName(param.EntityName);
             const primaryKeyFieldName = entity?.FirstPrimaryKey?.Name || 'ID';
-            // Apply differential update to cache
-            if (param.CacheLocal && checkResult.differentialData && LocalCacheManager.Instance.IsInitialized) {
+            // Apply differential update to cache (runViewCacheEligible, not raw CacheLocal — see the
+            // cacheable-gate note in prepareSmartCacheCheckParams; keeps Materialized/count_only/etc. out).
+            if (this.runViewCacheEligibleForWrite(param) && 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)
                 this);
                 if (merged) {
@@ -2343,8 +2393,10 @@ export class ProviderBase {
                 UserViewRunID: '',
                 AggregateResults: checkResult.aggregateResults // Include fresh aggregate results
             };
-            // Update the local cache with fresh data (don't await - fire and forget for performance)
-            if (param.CacheLocal && checkResult.maxUpdatedAt && LocalCacheManager.Instance.IsInitialized) {
+            // Update the local cache with fresh data (don't await - fire and forget for performance).
+            // runViewCacheEligible, not raw CacheLocal — see the cacheable-gate note; a first-time
+            // Materialized read reaches this 'stale' branch with fresh data and would otherwise be cached.
+            if (this.runViewCacheEligibleForWrite(param) && checkResult.maxUpdatedAt && LocalCacheManager.Instance.IsInitialized) {
                 const fingerprint = this.clientCacheFingerprint(param);
                 // Note: We don't await here to avoid blocking the response
                 // Cache update happens in background
@@ -2750,6 +2802,16 @@ export class ProviderBase {
         // set to true, we still skip caching for this entity.
         if (entity.Name === 'MJ: Record Changes')
             return false;
+        // Same rationale for MATERIALIZED QUERY entities: their wrapper view (materialized_vw<CodeName>) is
+        // rebuilt OUT-OF-BAND by the scheduled materialization refresh (a direct-SQL atomic table swap),
+        // which fires no BaseEntity.Save event for this entity — so a cached read would be served the
+        // pre-refresh snapshot indefinitely. Identify them by BOTH the CodeGen wrapper-view naming convention
+        // AND the VirtualEntity flag (CodeGen mints these as virtual entities) — the conjunction avoids
+        // over-matching a real, event-invalidated entity that merely happens to be named materialized_vw*.
+        // (Base-view materializations reuse the SOURCE entity and are handled by the DataSource:'Materialized'
+        // bypass in runViewCacheEligible; this covers the query-materialization Live-read path.)
+        if (entity.VirtualEntity && entity.BaseView && entity.BaseView.toLowerCase().startsWith('materialized_vw'))
+            return false;
         return entity.TrustServerCacheCompletely !== false;
     }
     shouldAutoCache(params, result) {
@@ -3817,6 +3879,9 @@ export class ProviderBase {
                     await newObject.Config(actualContextUser);
                     // Initialize IS-A parent entity composition chain before any data operations
                     await newObject.InitializeParentEntity();
+                    // Construct declared embedded peers (no NewRecord/Load yet) so NewRecord()
+                    // can provision required FKs synchronously and Load() can fill them.
+                    await newObject.InitializeEmbeddedRecords();
                     if (actualLoadKey) {
                         // Load existing record
                         const loadResult = await newObject.InnerLoad(actualLoadKey);