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

package/dist/generic/localCacheManager.js

@@ -1,5 +1,7 @@
-import { BaseSingleton, MJGlobal, MJEventType } from "@memberjunction/global";
-import { IsMaterializedDataSource } from "../views/runView.js";
+import { BaseSingleton, MJGlobal, MJEventType, IsValueEncrypted, ENCRYPTED_SENTINEL } from "@memberjunction/global";
+import { IsMaterializedDataSource, NormalizeAlternateBaseViewName } from "../views/runView.js";
+import { GetEffectiveAlternateBaseViewName } from "./alternateBaseViews.js";
+import { ViewPropertyValuesKey } from "../views/viewProperties.js";
 import { LogError, LogStatusEx, LogWarning } from "./logging.js";
 import { BaseEntity } from "./baseEntity.js";
 import { Metadata } from "./metadata.js";
@@ -156,6 +158,7 @@ export class LocalCacheManager extends BaseSingleton {
          */
         this._sharesReferences = false;
         this._registry = new Map();
+        this._lastVerifiedAt = new Map();
         this._initialized = false;
         this._initializePromise = null;
         this._stats = { hits: 0, misses: 0 };
@@ -464,6 +467,17 @@ export class LocalCacheManager extends BaseSingleton {
             || this.hasNarrowingSegment(parts)
             || this.hasAggregates(parts);
     }
+    /**
+     * Returns true when a cached `RunView` slot identified by `fingerprint` is eligible for
+     * in-place maintenance across entity saves (unfiltered, unordered, uncapped, no aggregates
+     * or narrowing segments).
+     */
+    IsRunViewFingerprintMaintainableOnSave(fingerprint) {
+        if (!fingerprint || !fingerprint.includes('|')) {
+            return false;
+        }
+        return !this.isSubsetFingerprint(fingerprint) && !this.isFilteredFingerprint(fingerprint);
+    }
     /**
      * Returns true if the slot was cached under an ORDER BY (fingerprint segment [2]).
      *
@@ -567,6 +581,9 @@ export class LocalCacheManager extends BaseSingleton {
      *                  segment is built. Same misclassification, worse consequence: a save by
      *                  user A was upserted into user B's RLS-scoped slot, injecting a row B's
      *                  predicate excludes. That is an RLS bypass.
+     *   - `fls:<h>`  — the slot holds only the columns one permission class may read. Upserting a
+     *                  saver's row would put columns into it that its readers may not see (or
+     *                  take away ones they may), so it is invalidated like the two above.
      *
      * ## Why it is written as a DENY-by-default allowlist
      * Enumerating the narrowing segments would repeat the original mistake: the next segment
@@ -590,6 +607,9 @@ export class LocalCacheManager extends BaseSingleton {
             if (!seg) {
                 continue;
             }
+            if (seg.startsWith('abv:')) {
+                return true; // alternate base view applies a canonical WHERE/JOIN — never maintain in place on save
+            }
             if (seg.startsWith('imr:')) {
                 continue; // widens the set — safe to maintain
             }
@@ -861,7 +881,7 @@ export class LocalCacheManager extends BaseSingleton {
      * @param fingerprint - The slot key
      * @param expiresAt - Absolute expiry (ms since epoch), when the slot has one
      */
-    runViewWriteOptions(fingerprint, expiresAt) {
+    runViewWriteOptions(fingerprint, expiresAt, pubSubOverride) {
         const options = {};
         const entity = this.extractEntityFromFingerprint(fingerprint);
         if (entity) {
@@ -870,6 +890,10 @@ export class LocalCacheManager extends BaseSingleton {
         if (expiresAt) {
             options.TTLSeconds = Math.max(1, Math.ceil((expiresAt - Date.now()) / 1000));
         }
+        if (pubSubOverride) {
+            options.pubSubAction = pubSubOverride.pubSubAction;
+            options.pubSubData = pubSubOverride.pubSubData;
+        }
         return options;
     }
     /** Storage write options for any registry entry; only RunView slots are indexed. */
@@ -1327,11 +1351,12 @@ export class LocalCacheManager extends BaseSingleton {
         }
         const snapshot = [...fingerprints];
         const nowISO = new Date().toISOString();
+        const savesComplete = LocalCacheManager.everySavedRowComplete(changes); // per change, not per slot
         const BATCH_SIZE = 8;
         for (let i = 0; i < snapshot.length; i += BATCH_SIZE) {
             await Promise.all(snapshot.slice(i, i + BATCH_SIZE).map(async (fingerprint) => {
                 try {
-                    await this.applyEntityChangesToSlot(fingerprint, changes, nowISO);
+                    await this.applyEntityChangesToSlot(fingerprint, changes, nowISO, savesComplete);
                 }
                 catch (err) {
                     LogError(`LocalCacheManager: failed to apply batched changes to "${fingerprint}": ${err.message}`);
@@ -1343,12 +1368,14 @@ export class LocalCacheManager extends BaseSingleton {
      * One slot, several changes: the same decisions {@link processEntityEventForFingerprint} makes
      * per event, made once for the whole list.
      */
-    async applyEntityChangesToSlot(fingerprint, changes, nowISO) {
+    async applyEntityChangesToSlot(fingerprint, changes, nowISO, savesComplete = LocalCacheManager.everySavedRowComplete(changes)) {
         const hasSave = changes.some(c => c.Type === 'save');
         // Subset and aggregate slots cannot be maintained in place; filtered slots cannot take an
         // upsert (the new row may not match the filter) but can drop deleted rows.
+        // A saved row missing columns cannot replace a full-width row either (see RowHasEveryField).
         if (this.isSubsetFingerprint(fingerprint) || this.hasAggregates(fingerprint.split('|'))
-            || (hasSave && this.isFilteredFingerprint(fingerprint))) {
+            || (hasSave && this.isFilteredFingerprint(fingerprint))
+            || !savesComplete) {
             await this.InvalidateRunViewResult(fingerprint);
             return;
         }
@@ -1445,11 +1472,13 @@ export class LocalCacheManager extends BaseSingleton {
                 if (key.KeyValuePairs.some(kv => kv.Value == null))
                     return;
                 LogStatusVerbose(`LocalCacheManager: remote-invalidate (save) for "${entityName}" PK=${key.ToConcatenatedString()}, updating ${fingerprints.size} cached fingerprint(s)`);
+                const rowComplete = LocalCacheManager.RowHasEveryField(entityInfo, recordData)
+                    && !LocalCacheManager.RowContainsPlaintextEncryptedField(entityInfo, recordData); // per row, not per slot
                 for (const fingerprint of fingerprintSnapshot) {
                     try {
                         // Subset slot (MaxRows/StartRow): upserting would grow the slot past the
                         // caller's own row limit. Invalidate, same as a filtered slot.
-                        if (!this.isFilteredFingerprint(fingerprint) && !this.isSubsetFingerprint(fingerprint)) {
+                        if (rowComplete && !this.isFilteredFingerprint(fingerprint) && !this.isSubsetFingerprint(fingerprint)) {
                             await this.UpsertSingleEntity(fingerprint, recordData, key, nowISO);
                         }
                         else {
@@ -1567,9 +1596,17 @@ export class LocalCacheManager extends BaseSingleton {
             await this.invalidateIfNotMaintained(fingerprint, maintained);
         }
         else if (!this.isFilteredFingerprint(fingerprint)) {
-            // Unfiltered cache: update the record in place
-            LogStatusVerbose(`LocalCacheManager: Upserting entity ${keyStr} in unfiltered cache "${fingerprint.substring(0, 60)}"`);
+            // Unfiltered cache: update the record in place, unless the saved row is missing columns
+            // or carries decrypted plaintext on an Encrypt=true field (BaseEntity.GetAll() holds
+            // in-memory plaintext after Save(), which must never be persisted to shared cache/Redis).
             const entityData = baseEntity.GetAll();
+            if (!LocalCacheManager.RowHasEveryField(baseEntity.EntityInfo, entityData) ||
+                LocalCacheManager.RowContainsPlaintextEncryptedField(baseEntity.EntityInfo, entityData)) {
+                LogStatusVerbose(`LocalCacheManager: Invalidating "${fingerprint.substring(0, 60)}" — the saved row is missing columns or holds decrypted plaintext`);
+                await this.InvalidateRunViewResult(fingerprint);
+                return;
+            }
+            LogStatusVerbose(`LocalCacheManager: Upserting entity ${keyStr} in unfiltered cache "${fingerprint.substring(0, 60)}"`);
             const maintained = await this.UpsertSingleEntity(fingerprint, entityData, key, nowISO);
             await this.invalidateIfNotMaintained(fingerprint, maintained);
         }
@@ -1579,6 +1616,93 @@ export class LocalCacheManager extends BaseSingleton {
             await this.InvalidateRunViewResult(fingerprint);
         }
     }
+    /**
+     * True when `row` has a key for every non-binary field of `entity`, so it may replace the
+     * cached copy of its record in place.
+     *
+     * A save event carries the saver's own values (`GetAll()`), and an object leaves out every
+     * field it does not hold: one its user may not read, or one that was never loaded. Upserting
+     * such a row into a full-width slot would replace a complete cached row with a partial one,
+     * and every later reader of that slot, including users entitled to the missing columns, would
+     * be served the row without them. A partial row therefore clears the slot instead, and the
+     * next read refills it from the database. Binary fields are not required, because slots
+     * leave them out unless asked for.
+     *
+     * A row is judged against the entity's field list, so without one (no entity metadata on
+     * the event, which a real entity always carries) there is nothing to compare and the row is
+     * accepted, as before this check existed.
+     *
+     * @param entity - The saved record's entity
+     * @param row - The values the event carries
+     */
+    static RowHasEveryField(entity, row) {
+        if (!row || typeof row !== 'object') {
+            return false;
+        }
+        const fields = entity?.Fields;
+        if (!Array.isArray(fields) || fields.length === 0) {
+            return true;
+        }
+        for (const field of fields) {
+            if (!field.IsBinaryFieldType && !Object.prototype.hasOwnProperty.call(row, field.Name)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /**
+     * Returns `true` when `entity` declares one or more encrypted fields (`Encrypt && EncryptionKeyID`)
+     * and `row` contains a non-empty string value for any such field that is neither ciphertext
+     * (`$ENC$...`) nor `ENCRYPTED_SENTINEL`.
+     *
+     * Used as a defense-in-depth gate so decrypted in-memory entity values (e.g. from
+     * `BaseEntity.GetAll()` during `save` events) are never written in plaintext to local or
+     * distributed Redis caches.
+     */
+    static RowContainsPlaintextEncryptedField(entity, row) {
+        if (!entity || !row || typeof row !== 'object') {
+            return false;
+        }
+        const encryptedFields = Array.isArray(entity.EncryptedFields)
+            ? entity.EncryptedFields
+            : Array.isArray(entity.Fields)
+                ? entity.Fields.filter(f => f.Encrypt && Boolean(f.EncryptionKeyID))
+                : [];
+        if (encryptedFields.length === 0) {
+            return false;
+        }
+        const rowMap = row;
+        for (const field of encryptedFields) {
+            if (!field.EncryptionKeyID)
+                continue;
+            const val = rowMap[field.Name];
+            if (typeof val === 'string' && val.length > 0 && val !== ENCRYPTED_SENTINEL && !IsValueEncrypted(val)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Whether every saved row among `changes` carries every column ({@link RowHasEveryField}) and no plaintext encrypted values. */
+    static everySavedRowComplete(changes) {
+        return changes.every(c => c.Type !== 'save' ||
+            (LocalCacheManager.RowHasEveryField(c.EntityInfo, c.Record) &&
+                !LocalCacheManager.RowContainsPlaintextEncryptedField(c.EntityInfo, c.Record)));
+    }
+    /**
+     * True when a saved row may be written into `fingerprint`'s slot in place: the slot is neither
+     * filtered (including row-security and field-security segments) nor a subset, and the row
+     * carries every column ({@link RowHasEveryField}) with no plaintext secrets. Otherwise the slot must be invalidated.
+     *
+     * @param fingerprint - The slot to maintain
+     * @param entity - The saved record's entity
+     * @param row - The values the save carries
+     */
+    CanUpsertRowIntoSlot(fingerprint, entity, row) {
+        return !this.isFilteredFingerprint(fingerprint)
+            && !this.isSubsetFingerprint(fingerprint)
+            && LocalCacheManager.RowHasEveryField(entity, row)
+            && !LocalCacheManager.RowContainsPlaintextEncryptedField(entity, row);
+    }
     /**
      * Handles a save/delete that could not be applied to a slot this process indexed — in practice
      * because the slot expired or was removed by someone else.
@@ -1676,7 +1800,25 @@ export class LocalCacheManager extends BaseSingleton {
             }
         }
         else {
-            // For set/removed, dispatch only to callbacks for the specific fingerprint
+            this._lastVerifiedAt.delete(event.CacheKey);
+            if (event.Action === 'row_delta' && event.Data) {
+                const existingEntry = this._registry.get(event.CacheKey);
+                if (existingEntry) {
+                    try {
+                        const parsedDelta = JSON.parse(event.Data);
+                        if (typeof parsedDelta.rowCount === 'number') {
+                            existingEntry.rowCount = parsedDelta.rowCount;
+                        }
+                        if (typeof parsedDelta.maxUpdatedAt === 'string') {
+                            existingEntry.maxUpdatedAt = parsedDelta.maxUpdatedAt;
+                        }
+                    }
+                    catch {
+                        // Best-effort local registry metadata update; callbacks handle invalid payloads safely.
+                    }
+                }
+            }
+            // For set/row_delta/removed, dispatch only to callbacks for the specific fingerprint
             const callbacks = this._changeCallbacks.get(event.CacheKey);
             if (callbacks) {
                 for (const cb of callbacks) {
@@ -1867,16 +2009,12 @@ export class LocalCacheManager extends BaseSingleton {
      *   what goes in it, and `ProviderBase.ComputeRunViewFLSFingerprintKey` is the single place
      *   that decision lives so the two tiers cannot drift.
      *
-     *   **CLIENT-ONLY in practice.** The client passes its ALLOWED set
-     *   (`ProviderBase.ComputeClientFLSAllowedKey`); the SERVER passes nothing. Server slots are
-     *   full-width and shared by every user, with narrowing applied at read time by
-     *   `ApplyFieldSecurityProjection` on both the hit and miss paths — a segment there would
-     *   fragment one shared slot into one per permission class and protect nothing. Client slots
-     *   are stored exactly as the server returned them (already narrowed on the wire) and are
-     *   never projected on read, so the field set has to be part of slot identity: without it a
-     *   user whose access is tightened keeps being served their persisted IndexedDB slot, because
-     *   the currency check compares only `maxUpdatedAt` and `rowCount` and neither notices a
-     *   column.
+     *   **Both tiers pass it.** Each slot holds the rows of one permission class: the provider
+     *   fetches only the columns the reading user may see, so the field set has to be part of slot
+     *   identity on the server exactly as it is in the browser, where rows are stored as the server
+     *   returned them and never projected on read. Users with the same allowed set share a slot;
+     *   users with different sets never do. That also keeps a user search's row set apart, since
+     *   which rows match depends on which columns the reader may search.
      *
      *   Keyed on the ALLOWED set rather than the denied one deliberately: once client metadata is
      *   filtered for restricted users ([#3485](https://github.com/MemberJunction/MJ/issues/3485))
@@ -1887,7 +2025,7 @@ export class LocalCacheManager extends BaseSingleton {
      *   Empty for unrestricted users and non-FLS entities, which appends no segment at all — so
      *   their fingerprints stay byte-identical and keep sharing slots (the `rls:` rule). A
      *   permission change produces a new hash → fresh slot; slots keyed to the old hash strand
-     *   until eviction (memory cost, not a leak).
+     *   until eviction (memory cost, not a leak). Hashed with {@link HashSecuritySegment}.
      * @param datasetSegment - Namespace for dataset-item slots (see the `ds:` append below): keeps
      *   `GetDatasetByName` item caching from colliding with a plain unfiltered read of the same
      *   entity. Appended only when supplied, so ordinary reads keep their pre-existing key.
@@ -1952,6 +2090,14 @@ export class LocalCacheManager extends BaseSingleton {
         if (params.IncludeBinaryFields === true) {
             parts.push('bin:1');
         }
+        // SkipTotalRowCount segment. A call that skips the fallback COUNT stores a result whose
+        // TotalRowCount was never counted, so it must not share a slot with the otherwise
+        // identical counted call (each would be served the other's TotalRowCount). Appended only
+        // when true, so every existing fingerprint stays byte-for-byte identical. Not allowlisted
+        // in hasNarrowingSegment, so such a slot is invalidated on save rather than maintained.
+        if (params.SkipTotalRowCount === true) {
+            parts.push('strc:1');
+        }
         // DataSource segment. RunViewParams.DataSource:'Materialized' routes the read to the entity's
         // materialized snapshot view (GetEffectiveBaseView), a DIFFERENT physical source than the default
         // live base view — so a Live read and a Materialized read of the same entity/filter/orderBy MUST
@@ -1961,6 +2107,15 @@ export class LocalCacheManager extends BaseSingleton {
         if (IsMaterializedDataSource(params.DataSource)) {
             parts.push('ds:materialized');
         }
+        // AlternateBaseView segment. Routing a read through an alternate base view (explicitly via
+        // params.AlternateBaseView or pinned inside a loaded params.ViewEntity's DisplayState JSON)
+        // targets a different physical SQL view with its own canonical WHERE/JOIN, so it MUST NOT
+        // share a cache slot with the entity's canonical BaseView or another alternate view.
+        // Appended only when non-empty so canonical reads keep their exact pre-existing fingerprint.
+        const effectiveAbv = NormalizeAlternateBaseViewName(GetEffectiveAlternateBaseViewName(params));
+        if (effectiveAbv.length > 0) {
+            parts.push(`abv:${effectiveAbv}`);
+        }
         // Keyset (AfterKey) seek cursor MUST be part of the fingerprint. Each keyset page
         // sends a different AfterKey but otherwise-identical params; without this, sequential
         // pages collide on the same fingerprint and the dedup/linger layer hands page N+1 the
@@ -1978,25 +2133,24 @@ export class LocalCacheManager extends BaseSingleton {
         // substitutions) hash differently and therefore never collide.
         const rls = (rlsWhereClause ?? '').trim();
         if (rls.length > 0) {
-            parts.push(`rls:${this.simpleHash(rls)}`);
+            parts.push(`rls:${this.HashSecuritySegment(rls)}`);
         }
-        // Field-Level-Security segment — the column counterpart of `rls:`, and CLIENT-ONLY.
+        // Field-Level-Security segment — the column counterpart of `rls:`.
         //
-        // A browser stores rows exactly as the server returned them (already narrowed to the
-        // user's allowed columns) and never projects on read, so the field set has to be part
-        // of slot identity. Without it, a user whose access is tightened keeps being served
-        // their persisted IndexedDB slot: the currency check compares maxUpdatedAt and rowCount
-        // only, neither of which notices a column.
-        //
-        // The server passes nothing here — its slots are full-width and shared, with narrowing
-        // applied at read time by ApplyFieldSecurityProjection.
-        // ProviderBase.ComputeRunViewFLSFingerprintKey is where that split is decided.
+        // A slot holds the columns one permission class may read, on both tiers: the server
+        // fetches only the reader's allowed columns, and a browser stores rows exactly as the
+        // server returned them. So the field set is part of slot identity, and a user is only
+        // ever served a slot filled for the same allowed set. Without it, a user whose access is
+        // tightened keeps being served a slot with the column in it (the currency check compares
+        // maxUpdatedAt and rowCount only, neither of which notices a column), and a restricted
+        // reader's narrow rows would be served to an unrestricted one.
+        // ProviderBase.ComputeRunViewFLSFingerprintKey decides what the key contains.
         //
         // Appended ONLY when non-empty, so unrestricted users and non-FLS entities keep
         // byte-identical fingerprints and shared slots (the rls: rule).
         const fls = (flsFieldsKey ?? '').trim();
         if (fls.length > 0) {
-            parts.push(`fls:${this.simpleHash(fls)}`);
+            parts.push(`fls:${this.HashSecuritySegment(fls)}`);
         }
         // Stored-view identity. A saved view's WhereClause/OrderBy live on the view, not in
         // params.ExtraFilter, so a view run and a plain entity read (or a different view) can
@@ -2009,6 +2163,17 @@ export class LocalCacheManager extends BaseSingleton {
         if (viewKey.length > 0) {
             parts.push(`vw:${viewKey}`);
         }
+        // View-property segment. A stored view's property values (RunViewParams.Properties and
+        // ServerProperties) each add a predicate the provider builds, so one chapter's run must
+        // never be served another chapter's slot. On the server the provider has already replaced
+        // both with the resolved values (token defaults included) before this runs. The values go
+        // in as canonical JSON rather than a hash: a 32-bit hash of values a client partly chooses
+        // could be steered onto another run's slot. Appended ONLY when a value is present, so every
+        // run without properties keeps its exact fingerprint.
+        const propertyKey = ViewPropertyValuesKey(params.Properties, params.ServerProperties);
+        if (propertyKey.length > 0) {
+            parts.push(`vp:${propertyKey}`);
+        }
         // Dataset namespace. `GetDatasetByName` caches each dataset ITEM's rows through this same
         // builder, supplying only entity + the item's WhereClause — and every shipped item has a
         // NULL WhereClause, so without this segment a dataset item emits the identical fingerprint
@@ -2091,6 +2256,39 @@ export class LocalCacheManager extends BaseSingleton {
         }
         return reordered;
     }
+    /**
+     * A 128-bit hash, as 32 hex characters, of a security key that becomes part of a slot's
+     * identity: the `rls:` and `fls:` fingerprint segments, and the field-security key a browser
+     * sends with its cache status.
+     *
+     * These keys decide which users may share a slot, so two different keys must not land on the
+     * same value. The 32-bit {@link simpleHash} used for the other segments is too short for that:
+     * at a few tens of thousands of distinct row filters a collision becomes likely, and a
+     * collision here serves one user's rows to another. Four independent 32-bit multiply-xor lanes
+     * keep it synchronous, deterministic and identical in Node and the browser.
+     *
+     * @param str - The security key
+     * @returns 32 lowercase hex characters
+     */
+    HashSecuritySegment(str) {
+        let h1 = 1779033703, h2 = 3144134277, h3 = 1013904242, h4 = 2773480762;
+        for (let i = 0; i < str.length; i++) {
+            const k = str.charCodeAt(i);
+            h1 = h2 ^ Math.imul(h1 ^ k, 597399067);
+            h2 = h3 ^ Math.imul(h2 ^ k, 2869860233);
+            h3 = h4 ^ Math.imul(h3 ^ k, 951274213);
+            h4 = h1 ^ Math.imul(h4 ^ k, 2716044179);
+        }
+        h1 = Math.imul(h3 ^ (h1 >>> 18), 597399067);
+        h2 = Math.imul(h4 ^ (h2 >>> 22), 2869860233);
+        h3 = Math.imul(h1 ^ (h3 >>> 17), 951274213);
+        h4 = Math.imul(h2 ^ (h4 >>> 19), 2716044179);
+        h1 ^= (h2 ^ h3 ^ h4);
+        h2 ^= h1;
+        h3 ^= h1;
+        h4 ^= h1;
+        return [h1, h2, h3, h4].map(h => (h >>> 0).toString(16).padStart(8, '0')).join('');
+    }
     /**
      * Simple hash function for creating short fingerprints from strings.
      * Not cryptographic, just for deduplication/fingerprinting purposes.
@@ -2282,6 +2480,17 @@ export class LocalCacheManager extends BaseSingleton {
                     LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for external entity "${params.EntityName}" — no TTL provided (would never invalidate)`, verboseOnly: true });
                     return;
                 }
+                // Defense-in-depth on server caches (TrustLocalCacheCompletely === true):
+                // never persist decrypted plaintext values for Encrypt=true columns into shared/Redis cache.
+                const cacheProvider = provider;
+                if (entity &&
+                    cacheProvider?.TrustLocalCacheCompletely === true &&
+                    !options?.ProviderInternalScaffolding &&
+                    Array.isArray(results) &&
+                    results.some(r => typeof r === 'object' && r !== null && LocalCacheManager.RowContainsPlaintextEncryptedField(entity, r))) {
+                    LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping server cache write for "${params.EntityName}" — rows contain decrypted plaintext for an encrypted field`, verboseOnly: true });
+                    return;
+                }
             }
             catch (err) {
                 // fall through and write — fail-open is safer than fail-closed here
@@ -2295,7 +2504,8 @@ export class LocalCacheManager extends BaseSingleton {
             maxUpdatedAt = coerced;
         }
         // Persist results, maxUpdatedAt, aggregateResults, totalRowCount, and schemaHash
-        const data = { results, maxUpdatedAt };
+        const initialNow = Date.now();
+        const data = { results, maxUpdatedAt, cachedAt: initialNow, lastVerifiedAt: initialNow };
         if (options?.ProviderInternalScaffolding) {
             // Persisted so event-driven in-place maintenance carries the exemption forward.
             data.providerInternalScaffolding = true;
@@ -2352,8 +2562,10 @@ export class LocalCacheManager extends BaseSingleton {
         await this.evictIfNeeded(sizeBytes);
         try {
             // Native object storage — IDB structured-clones, localStorage / Redis serialize internally.
-            const expiresAt = ttlMs ? Date.now() + ttlMs : undefined;
+            const writeNow = Date.now();
+            const expiresAt = ttlMs ? writeNow + ttlMs : undefined;
             await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache, this.runViewWriteOptions(fingerprint, expiresAt));
+            this._lastVerifiedAt.set(fingerprint, writeNow);
             this.registerEntry({
                 key: fingerprint,
                 type: 'runview',
@@ -2367,8 +2579,9 @@ export class LocalCacheManager extends BaseSingleton {
                     MaxRows: params.MaxRows,
                     HasAggregates: (params.Aggregates?.length ?? 0) > 0
                 },
-                cachedAt: Date.now(),
-                lastAccessedAt: Date.now(),
+                cachedAt: writeNow,
+                lastAccessedAt: writeNow,
+                lastVerifiedAt: writeNow,
                 accessCount: 1,
                 sizeBytes,
                 maxUpdatedAt,
@@ -2493,6 +2706,11 @@ export class LocalCacheManager extends BaseSingleton {
         this.indexSlotThisProcessDidNotWrite(fingerprint);
         this._stats.hits++;
         const results = parsed.results || [];
+        const cachedAt = registryEntry?.cachedAt ?? parsed.cachedAt;
+        const lastVerifiedAt = this._lastVerifiedAt.get(fingerprint)
+            ?? registryEntry?.lastVerifiedAt
+            ?? parsed.lastVerifiedAt
+            ?? cachedAt;
         const result = {
             results,
             maxUpdatedAt: parsed.maxUpdatedAt,
@@ -2503,12 +2721,31 @@ export class LocalCacheManager extends BaseSingleton {
             schemaStamp: parsed.schemaStamp,
             // Same carry-forward rationale: a maintained scaffolding slot must stay exempt.
             providerInternalScaffolding: parsed.providerInternalScaffolding,
+            cachedAt,
+            lastVerifiedAt,
         };
         if (parsed.aggregateResults) {
             result.aggregateResults = parsed.aggregateResults;
         }
         return result;
     }
+    /**
+     * Updates the `lastVerifiedAt` timestamp for a cached RunView slot in O(1) time
+     * without re-cloning, re-freezing, or rewriting its stored row array.
+     *
+     * Used by server-side smart-cache verification after a lightweight SQL status probe
+     * (`MAX(__mj_UpdatedAt)`, `COUNT(*)`) confirms that a cached slot is still current.
+     *
+     * @param fingerprint - The cache fingerprint to touch
+     * @param timestamp - Verification timestamp in epoch ms (defaults to `Date.now()`)
+     */
+    TouchRunViewResultVerifiedAt(fingerprint, timestamp = Date.now()) {
+        this._lastVerifiedAt.set(fingerprint, timestamp);
+        const entry = this._registry.get(fingerprint);
+        if (entry) {
+            entry.lastVerifiedAt = timestamp;
+        }
+    }
     /**
      * Records a slot this process READ, so a later save can still find it once it has expired.
      *
@@ -2669,11 +2906,16 @@ export class LocalCacheManager extends BaseSingleton {
             // Note: If aggregateResults not provided, cached aggregates are cleared (they'd be stale)
             await this.SetRunViewResult(fingerprint, params, mergedResults, newMaxUpdatedAt, aggregateResults, mergedTotalRowCount, provider);
             // Return with rowCount derived from merged results and aggregates if provided
+            const verifiedNow = this._lastVerifiedAt.get(fingerprint) ?? Date.now();
+            this._lastVerifiedAt.set(fingerprint, verifiedNow);
+            const registryEntry = this._registry.get(fingerprint);
             const result = {
                 results: mergedResults,
                 maxUpdatedAt: newMaxUpdatedAt,
                 rowCount: mergedResults.length,
-                totalRowCount: mergedTotalRowCount
+                totalRowCount: mergedTotalRowCount,
+                cachedAt: registryEntry?.cachedAt ?? verifiedNow,
+                lastVerifiedAt: verifiedNow
             };
             if (aggregateResults) {
                 result.aggregateResults = aggregateResults;
@@ -2789,11 +3031,23 @@ export class LocalCacheManager extends BaseSingleton {
                 }
                 const pkFieldNames = changes[0].Key.KeyValuePairs.map(kv => kv.FieldName);
                 const resultMap = this.indexRowsByKey(cached.results, pkFieldNames);
-                if (!this.applyChangesToRowMap(resultMap, changes)) {
+                const deltaChanges = this.applyChangesToRowMap(resultMap, changes);
+                if (!deltaChanges.changed) {
                     return true; // only removals of rows the slot does not hold
                 }
-                return await this.storeCachedResults(fingerprint, Array.from(resultMap.values()), newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash,
-                    schemaStamp: cached.schemaStamp, providerInternalScaffolding: cached.providerInternalScaffolding });
+                return await this.storeCachedResults(fingerprint, Array.from(resultMap.values()), newMaxUpdatedAt, {
+                    totalRowCount: cached.totalRowCount,
+                    rowCount: cached.results.length,
+                    schemaHash: cached.schemaHash,
+                    schemaStamp: cached.schemaStamp,
+                    providerInternalScaffolding: cached.providerInternalScaffolding,
+                }, cached.providerInternalScaffolding
+                    ? undefined
+                    : {
+                        upsertedRows: deltaChanges.upsertedRows,
+                        deletedPrimaryKeys: deltaChanges.deletedPrimaryKeys,
+                        primaryKeyFields: pkFieldNames,
+                    });
             }
             catch (e) {
                 LogError(`LocalCacheManager.ApplyRowChanges failed: ${e}`);
@@ -2816,20 +3070,38 @@ export class LocalCacheManager extends BaseSingleton {
         }
         return resultMap;
     }
-    /** Applies `changes` to `rows` in order. @returns True when anything changed. */
+    /** Applies `changes` to `rows` in order and collects the collapsed net row delta for pub/sub. */
     applyChangesToRowMap(rows, changes) {
         let changed = false;
+        const upsertsByKey = new Map();
+        const deletesByKey = new Map();
         for (const change of changes) {
             const keyStr = this.cheapKeyFromCompositeKey(change.Key);
             if (change.Row) {
                 rows.set(keyStr, change.Row);
+                deletesByKey.delete(keyStr);
+                upsertsByKey.set(keyStr, change.Row);
                 changed = true;
             }
             else if (rows.delete(keyStr)) {
+                upsertsByKey.delete(keyStr);
+                const pkRecord = {};
+                for (const kv of change.Key.KeyValuePairs) {
+                    const v = kv.Value;
+                    pkRecord[kv.FieldName] =
+                        typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean' || v === null
+                            ? v
+                            : String(v);
+                }
+                deletesByKey.set(keyStr, pkRecord);
                 changed = true;
             }
         }
-        return changed;
+        return {
+            changed,
+            upsertedRows: Array.from(upsertsByKey.values()),
+            deletedPrimaryKeys: Array.from(deletesByKey.values()),
+        };
     }
     /**
      * Stores updated results array back to the cache and updates the registry.
@@ -2845,15 +3117,19 @@ export class LocalCacheManager extends BaseSingleton {
      * full-dataset slot is unchanged (prior total == prior length) while a subset slot keeps a
      * correct total.
      */
-    async storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, prior) {
+    async storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, prior, rowDelta) {
         // Stamp the slot the way the fill path does — the newest row's __mj_UpdatedAt — so the
         // stamp means the same thing whichever funnel wrote the slot and matches what the database
         // reports for the same rows (the client smart-cache check compares the two). The caller's
         // value (the event time) is used only when the rows carry no timestamp column.
         const maxUpdatedAt = LocalCacheManager.MaxUpdatedAtOfRows(updatedResults) ?? newMaxUpdatedAt;
+        const now = Date.now();
+        const existingEntry = this._registry.get(fingerprint);
         const data = {
             results: updatedResults,
-            maxUpdatedAt
+            maxUpdatedAt,
+            cachedAt: existingEntry?.cachedAt ?? now,
+            lastVerifiedAt: now
         };
         // Carry the schemaHash FORWARD — never recompute it here (B38).
         //
@@ -2895,13 +3171,30 @@ export class LocalCacheManager extends BaseSingleton {
         if (!prior?.providerInternalScaffolding) {
             this.freezeRowDataIfProviderSharesReferences(data);
         }
-        const existingEntry = this._registry.get(fingerprint);
-        await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache, this.runViewWriteOptions(fingerprint, existingEntry?.expiresAt));
+        let pubSubOverride;
+        if (rowDelta) {
+            const deltaPayload = {
+                upsertedRows: rowDelta.upsertedRows,
+                deletedPrimaryKeys: rowDelta.deletedPrimaryKeys,
+                primaryKeyFields: rowDelta.primaryKeyFields,
+                maxUpdatedAt,
+                rowCount: updatedResults.length,
+                totalRowCount: data.totalRowCount ?? updatedResults.length,
+                schemaHash: data.schemaHash,
+            };
+            pubSubOverride = {
+                pubSubAction: 'row_delta',
+                pubSubData: JSON.stringify(deltaPayload),
+            };
+        }
+        await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache, this.runViewWriteOptions(fingerprint, existingEntry?.expiresAt, pubSubOverride));
+        this._lastVerifiedAt.set(fingerprint, now);
         if (existingEntry) {
             existingEntry.maxUpdatedAt = maxUpdatedAt;
             existingEntry.rowCount = updatedResults.length;
             existingEntry.sizeBytes = sizeBytes;
-            existingEntry.lastAccessedAt = Date.now();
+            existingEntry.lastAccessedAt = now;
+            existingEntry.lastVerifiedAt = now;
             this.debouncedPersistRegistry();
         }
         return true;
@@ -2924,6 +3217,7 @@ export class LocalCacheManager extends BaseSingleton {
             try {
                 await this._storageProvider.Remove(key, CacheCategory.RunViewCache);
                 this._registry.delete(key);
+                this._lastVerifiedAt.delete(key);
                 this.removeFromEntityIndex(key);
             }
             catch (e) {
@@ -3338,6 +3632,7 @@ export class LocalCacheManager extends BaseSingleton {
                     await this._storageProvider.Remove(entry.key + '_date', category);
                 }
                 this._registry.delete(entry.key);
+                this._lastVerifiedAt.delete(entry.key);
             }
             catch (e) {
                 LogError(`LocalCacheManager.ClearByType failed for key ${entry.key}: ${e}`);
@@ -3368,6 +3663,7 @@ export class LocalCacheManager extends BaseSingleton {
             }
         }
         this._registry.clear();
+        this._lastVerifiedAt.clear();
         this._stats = { hits: 0, misses: 0 };
         await this.persistRegistry();
         return count;
@@ -3418,6 +3714,7 @@ export class LocalCacheManager extends BaseSingleton {
      */
     unregisterEntry(key) {
         this._registry.delete(key);
+        this._lastVerifiedAt.delete(key);
         this.debouncedPersistRegistry();
     }
     /**
@@ -3675,6 +3972,7 @@ export class LocalCacheManager extends BaseSingleton {
                     this.removeFromEntityIndex(entry.fingerprint);
                 }
                 this._registry.delete(key);
+                this._lastVerifiedAt.delete(key);
             }
             catch (e) {
                 // Continue evicting other entries
@@ -3727,6 +4025,7 @@ export class LocalCacheManager extends BaseSingleton {
                 this.removeFromEntityIndex(entry.key);
                 bytesToFree -= entry.sizeBytes;
                 this._registry.delete(entry.key);
+                this._lastVerifiedAt.delete(entry.key);
             }
             catch {
                 // Continue evicting
@@ -3831,6 +4130,7 @@ export class LocalCacheManager extends BaseSingleton {
             this.removeFromEntityIndex(entry.fingerprint);
         }
         this._registry.delete(key);
+        this._lastVerifiedAt.delete(key);
     }
 }
 //# sourceMappingURL=localCacheManager.js.map