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

package/dist/generic/localCacheManager.js

@@ -1,5 +1,7 @@
 import { BaseSingleton, MJGlobal, MJEventType } from "@memberjunction/global";
-import { IsMaterializedDataSource } from "../views/runView.js";
+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";
@@ -56,13 +58,35 @@ function deepFreezeCacheValue(value, visited = new WeakSet()) {
 // ============================================================================
 // DEFAULT CONFIGURATION
 // ============================================================================
+/**
+ * Minimum percentage of the cache budget that eviction frees in one pass, so a run of
+ * stores near the budget does not trigger an eviction each time. Also the floor under the
+ * space any single entry must leave behind it — see {@link HARD_MAX_ENTRY_PERCENT}.
+ */
+const EVICTION_THRASH_FLOOR_PERCENT = 10;
+/**
+ * Percentage of the budget held back from any one entry when the per-entry ceiling is
+ * derived (`maxEntryPercentOfCache: 'auto'`). The reserve is what keeps the rest of the
+ * cache alive alongside one large entry: with it, a store that arrives after the large
+ * entry can be satisfied by evicting entries out of the reserve rather than the large
+ * entry itself. It MUST be at least {@link EVICTION_THRASH_FLOOR_PERCENT}, or a single
+ * eviction pass could not be satisfied without evicting the large entry that eviction
+ * was making room around.
+ */
+const SINGLE_ENTRY_RESERVE_PERCENT = 25;
+/**
+ * Hard upper bound on the per-entry ceiling, whatever the configuration says. One entry
+ * may never occupy so much of the budget that less than one eviction pass' worth of space
+ * is left — that is the state in which every store wipes everything else.
+ */
+const HARD_MAX_ENTRY_PERCENT = 100 - EVICTION_THRASH_FLOOR_PERCENT;
 const DEFAULT_CONFIG = {
     enabled: true,
     maxSizeBytes: 150 * 1024 * 1024, // 150MB
     defaultTTLMs: 0, // No TTL — event-based invalidation is the primary mechanism
     evictionPolicy: 'lru',
     maxPercentOfCachePerEntity: 50,
-    maxEntryPercentOfCache: 25,
+    maxEntryPercentOfCache: 'auto',
     evictionSweepIntervalMs: 300000, // 5 minutes
     verboseLogging: false,
 };
@@ -119,6 +143,11 @@ export class LocalCacheManager extends BaseSingleton {
     static get Instance() {
         return super.getInstance();
     }
+    /**
+     * How often, at most, a process writes an entity's shared slots while it keeps finding that
+     * entity's slots under a schema different from its own. See {@link handleSchemaMismatch}.
+     */
+    static { this.SCHEMA_MISMATCH_WRITE_INTERVAL_MS = 60_000; }
     constructor() {
         super();
         this._storageProvider = null;
@@ -129,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 };
@@ -146,6 +176,14 @@ export class LocalCacheManager extends BaseSingleton {
         this._entityEventBatches = new EntityEventBatchSet();
         /** Save/delete events a batch took when they were raised. See {@link WasTakenByEntityEventBatch}. */
         this._eventsTakenByBatch = new WeakSet();
+        /**
+         * Write holds on entities whose shared slots were found under a different schema, keyed by
+         * lowercased entity name. While a hold applies, {@link SetRunViewResult} skips or rate-limits
+         * writes of that entity's slots. See {@link handleSchemaMismatch} and {@link mayWriteUnderSchemaHold}.
+         */
+        this._schemaWriteHolds = new Map();
+        /** Schema mismatches already reported, so each entity/hash pair is logged once per process. */
+        this._reportedSchemaMismatches = new Set();
         this.REGISTRY_KEY = '__MJ_CACHE_REGISTRY__';
         /**
          * Reverse index from entity name to the set of RunView cache fingerprints
@@ -532,6 +570,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
@@ -555,6 +596,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
             }
@@ -622,27 +666,163 @@ export class LocalCacheManager extends BaseSingleton {
         return Number.isFinite(startRow) && startRow > 0;
     }
     /**
-     * Checks whether a cached RunView entry is structurally stale due to a schema change
-     * (e.g., new columns added via migration + CodeGen). Compares the stored schema hash
-     * against the current entity field list. If they differ, the entry is invalidated.
+     * Compares a cached RunView entry's schema hash against this process's current field list for
+     * the entity (a mismatch follows a migration + CodeGen that added, removed or reordered
+     * columns). Entries without a hash, and entities this process cannot resolve, never mismatch.
      * @param fingerprint - The cache fingerprint
      * @param data - The cached data to validate
-     * @returns true if the entry is stale and should not be served
+     * @returns The mismatch, or null when the entry may be served
      */
-    isSchemaStaleCacheEntry(fingerprint, data) {
+    findSchemaMismatch(fingerprint, data) {
         if (!data.schemaHash)
-            return false;
+            return null;
         const entityName = this.extractEntityFromFingerprint(fingerprint);
         if (!entityName)
+            return null;
+        const current = this.computeSchemaSignature(undefined, entityName);
+        if (!current || current.Hash === data.schemaHash)
+            return null;
+        return {
+            Subject: LocalCacheManager.runViewSubject(entityName),
+            CachedHash: data.schemaHash,
+            Current: current,
+            EntryIsNewer: LocalCacheManager.isNewerSchemaStamp(data.schemaStamp, current.Stamp),
+        };
+    }
+    /** The mismatch subject for an entity's RunView slots. */
+    static runViewSubject(entityName) {
+        return { Kind: 'runview', Name: entityName, Key: entityName.trim().toLowerCase() };
+    }
+    /** The mismatch subject for a query's RunQuery slots. */
+    static runQuerySubject(definition, queryName) {
+        return { Kind: 'runquery', Name: queryName || definition.QueryID, Key: definition.QueryID.trim().toLowerCase() };
+    }
+    /**
+     * True only when both stamps are present and the cached entry's is strictly newer than this
+     * process's. Equal or missing stamps leave the order unknown, which counts as not newer.
+     */
+    static isNewerSchemaStamp(entryStamp, currentStamp) {
+        if (!entryStamp || !currentStamp) {
             return false;
-        const currentHash = this.ComputeSchemaHash(undefined, entityName);
-        if (!currentHash)
-            return false;
-        if (currentHash !== data.schemaHash) {
-            LogWarning(`[CACHE-SCHEMA-STALE] Entity "${entityName}" schema changed (cached=${data.schemaHash}, current=${currentHash}) — dropping the slot`, 'Cache');
+        }
+        return LocalCacheManager.timestampMs(entryStamp) > LocalCacheManager.timestampMs(currentStamp);
+    }
+    /**
+     * Decides what a signature mismatch does to the slot: an entity schema mismatch on a RunView
+     * slot, or a query definition mismatch on a RunQuery slot. The entry is never served; the
+     * question is whether the slot is deleted, which on a shared store may also tell every peer to
+     * reload.
+     *
+     * - Process-local store, or a slot-maintenance read: delete it (`drop`). No other process reads a
+     *   local store. A maintenance read happens because a row changed, and a slot that cannot take
+     *   the change in place must go, whichever process wrote it.
+     * - Shared store, serving read: leave it, and hold back this process's writes of the subject's
+     *   slots. Deleting a RunView slot publishes `removed`, every peer engine holding the slot
+     *   reloads and rewrites it under its own hash, and processes on either side of a migration keep
+     *   doing that to each other. The caller reads the database instead.
+     *   - When the slot is known to come from newer metadata, this process is the one out of date.
+     *     It stops writing the subject's slots until its own hash changes.
+     *   - Otherwise it writes the subject's slots at most once per
+     *     {@link SCHEMA_MISMATCH_WRITE_INTERVAL_MS} while mismatches keep appearing. That still
+     *     replaces a slot left by older metadata, but a peer running code that deletes mismatched
+     *     slots (any release before this check stopped deleting them) gets one slot to delete per
+     *     interval instead of one per read. The hold lapses after an interval with no mismatch.
+     *     For RunView slots the first replacement waits one interval. For RunQuery slots it is
+     *     immediate: no release ever deleted a RunQuery slot over its definition and the category
+     *     is not published, so an immediate replacement cannot feed a loop, and waiting would make
+     *     every server run an edited query against the database for a full interval.
+     */
+    handleSchemaMismatch(mismatch, purpose, drop) {
+        const shared = this._storageProvider?.SharedAcrossProcesses === true;
+        if (!shared || purpose === 'maintain') {
+            this.reportSchemaMismatch(mismatch, 'dropping the slot');
+            drop().catch(() => { });
+            return;
+        }
+        this.holdSchemaWrites(mismatch);
+        this.reportSchemaMismatch(mismatch, LocalCacheManager.describeHeldMismatch(mismatch));
+    }
+    /** The log text for a mismatch that left the slot in place and took a write hold. */
+    static describeHeldMismatch(mismatch) {
+        const seconds = LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS / 1000;
+        if (mismatch.Subject.Kind === 'runquery') {
+            return mismatch.EntryIsNewer
+                ? 'another process wrote the slot under a newer query definition. This process runs the query against ' +
+                    'the database and stops writing its cache slots until its own definition catches up.'
+                : `running the query against the database. While slots under other definitions keep appearing, this ` +
+                    `process writes the query's slots at most once every ${seconds}s.`;
+        }
+        return mismatch.EntryIsNewer
+            ? 'another process wrote the slot under newer metadata. This process reads the entity from the database ' +
+                'and stops writing its cache slots until its metadata changes. If it started before a migration, restart it.'
+            : `reading from the database. While slots under other metadata keep appearing, this process writes the entity's ` +
+                `slots at most once every ${seconds}s.`;
+    }
+    /** The key of a subject's write hold. RunView and RunQuery holds share one map. */
+    static holdKey(subject) {
+        return `${subject.Kind}:${subject.Key}`;
+    }
+    /** Records or extends the write hold for a mismatch seen on a shared store. */
+    holdSchemaWrites(mismatch) {
+        const key = LocalCacheManager.holdKey(mismatch.Subject);
+        const now = Date.now();
+        const existing = this._schemaWriteHolds.get(key);
+        if (mismatch.EntryIsNewer) {
+            this._schemaWriteHolds.set(key, { OwnHash: mismatch.Current.Hash, NextWriteAt: Number.POSITIVE_INFINITY, LastMismatchAt: now });
+        }
+        else if (existing && existing.OwnHash === mismatch.Current.Hash) {
+            existing.LastMismatchAt = now;
+        }
+        else {
+            const firstWriteDelay = mismatch.Subject.Kind === 'runquery' ? 0 : LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS;
+            this._schemaWriteHolds.set(key, {
+                OwnHash: mismatch.Current.Hash,
+                NextWriteAt: now + firstWriteDelay,
+                LastMismatchAt: now,
+            });
+        }
+    }
+    /** Logs a mismatch once per subject and hash pair per process. */
+    reportSchemaMismatch(mismatch, outcome) {
+        const key = `${LocalCacheManager.holdKey(mismatch.Subject)}|${mismatch.CachedHash}|${mismatch.Current.Hash}`;
+        if (this._reportedSchemaMismatches.has(key)) {
+            return;
+        }
+        this._reportedSchemaMismatches.add(key);
+        const label = mismatch.Subject.Kind === 'runquery'
+            ? `[CACHE-QUERY-DEFINITION-STALE] Query "${mismatch.Subject.Name}" definition`
+            : `[CACHE-SCHEMA-STALE] Entity "${mismatch.Subject.Name}" schema`;
+        LogWarning(`${label} differs from a cached slot ` +
+            `(cached=${mismatch.CachedHash || '(none)'}, current=${mismatch.Current.Hash}) — ${outcome}`, 'Cache');
+    }
+    /**
+     * Whether a slot of `subject` may be written now, given its write hold (see
+     * {@link handleSchemaMismatch}). A permitted write under a rate-limiting hold uses up the
+     * interval. The hold is dropped once this process's hash changes (a metadata refresh, or a
+     * query edit reaching this process) or, for a rate-limiting hold, once an interval passes with
+     * no mismatch.
+     */
+    mayWriteUnderSchemaHold(subject, currentHash) {
+        if (this._storageProvider?.SharedAcrossProcesses !== true) {
             return true;
         }
-        return false;
+        const key = LocalCacheManager.holdKey(subject);
+        const hold = this._schemaWriteHolds.get(key);
+        if (!hold) {
+            return true;
+        }
+        const now = Date.now();
+        const interval = LocalCacheManager.SCHEMA_MISMATCH_WRITE_INTERVAL_MS;
+        const lapsed = hold.NextWriteAt !== Number.POSITIVE_INFINITY && now - hold.LastMismatchAt > interval;
+        if (hold.OwnHash !== currentHash || lapsed) {
+            this._schemaWriteHolds.delete(key);
+            return true;
+        }
+        if (now < hold.NextWriteAt) {
+            return false;
+        }
+        hold.NextWriteAt = now + interval;
+        return true;
     }
     /**
      * The newest `__mj_UpdatedAt` among `rows` as an ISO string, `''` for an empty set, or
@@ -1156,11 +1336,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}`);
@@ -1172,12 +1353,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;
         }
@@ -1274,11 +1457,12 @@ 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); // 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 {
@@ -1396,9 +1580,14 @@ 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
             const entityData = baseEntity.GetAll();
+            if (!LocalCacheManager.RowHasEveryField(baseEntity.EntityInfo, entityData)) {
+                LogStatusVerbose(`LocalCacheManager: Invalidating "${fingerprint.substring(0, 60)}" — the saved row is missing columns`);
+                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);
         }
@@ -1408,6 +1597,58 @@ 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;
+    }
+    /** Whether every saved row among `changes` carries every column ({@link RowHasEveryField}). */
+    static everySavedRowComplete(changes) {
+        return changes.every(c => c.Type !== 'save' || LocalCacheManager.RowHasEveryField(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}). 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);
+    }
     /**
      * 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.
@@ -1542,9 +1783,10 @@ export class LocalCacheManager extends BaseSingleton {
         if (!this._storageProvider || !this._config.enabled)
             return;
         const key = this.buildDatasetKey(name, itemFilters, keyPrefix);
-        // Estimate size from a string representation (used only for cache eviction
-        // accounting; the actual stored value is the native object).
-        const sizeBytes = this.estimateSize(JSON.stringify(dataset));
+        // Estimate size by sampling item result arrays instead of stringifying the entire dataset
+        const sizeBytes = Array.isArray(dataset?.Results)
+            ? dataset.Results.reduce((sum, item) => sum + this.estimateResultsSize(item.Results), 128)
+            : 128;
         // Fourth write funnel, held to the same contract as SetRunViewResult /
         // SetRunQueryResult / storeCachedResults. `GetDataset` hands this object straight back
         // out, so on a reference-sharing provider every reader shares it — the same exposure the
@@ -1695,16 +1937,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))
@@ -1715,7 +1953,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.
@@ -1780,6 +2018,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
@@ -1789,6 +2035,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
@@ -1806,25 +2061,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.
-        //
-        // 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.
+        // Field-Level-Security segment — the column counterpart of `rls:`.
         //
-        // 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
@@ -1837,6 +2091,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
@@ -1919,6 +2184,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.
@@ -1944,6 +2242,14 @@ export class LocalCacheManager extends BaseSingleton {
      * @returns The schema hash string, or undefined if the entity can't be resolved
      */
     ComputeSchemaHash(provider, entityName) {
+        return this.computeSchemaSignature(provider, entityName)?.Hash;
+    }
+    /**
+     * The entity's schema hash (see {@link ComputeSchemaHash}) together with its schema stamp: the
+     * newest `__mj_UpdatedAt` across the entity row and its field rows, as an ISO string, or
+     * undefined when the metadata carries no timestamps.
+     */
+    computeSchemaSignature(provider, entityName) {
         try {
             const md = provider ?? new Metadata();
             const entity = md.EntityByName(entityName);
@@ -1952,12 +2258,27 @@ export class LocalCacheManager extends BaseSingleton {
             // Use natural sequence order (EntityInfo.Fields is sorted by Sequence).
             // This detects field additions, removals, AND reorderings.
             const fieldNames = entity.Fields.map(f => f.Name).join('|');
-            return this.simpleHash(fieldNames);
+            let newest = LocalCacheManager.timestampMs(entity.__mj_UpdatedAt);
+            for (const field of entity.Fields) {
+                newest = Math.max(newest, LocalCacheManager.timestampMs(field.__mj_UpdatedAt));
+            }
+            return {
+                Hash: this.simpleHash(fieldNames),
+                Stamp: newest > 0 ? new Date(newest).toISOString() : undefined,
+            };
         }
         catch {
             return undefined;
         }
     }
+    /** Milliseconds since the epoch for a metadata timestamp (a Date or a string), or 0 when unreadable. */
+    static timestampMs(value) {
+        if (value == null) {
+            return 0;
+        }
+        const ms = value instanceof Date ? value.getTime() : Date.parse(value);
+        return Number.isNaN(ms) ? 0 : ms;
+    }
     /**
      * Deep-freezes an about-to-be-stored cache payload when — and only when — the active
      * storage provider hands out live object references
@@ -2100,7 +2421,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;
@@ -2113,26 +2435,33 @@ export class LocalCacheManager extends BaseSingleton {
         }
         // Compute and store schema hash for upgrade detection
         if (params.EntityName) {
-            const schemaHash = this.ComputeSchemaHash(provider, params.EntityName);
-            if (schemaHash) {
-                data.schemaHash = schemaHash;
+            const signature = this.computeSchemaSignature(provider, params.EntityName);
+            if (signature) {
+                if (!this.mayWriteUnderSchemaHold(LocalCacheManager.runViewSubject(params.EntityName), signature.Hash)) {
+                    LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for "${params.EntityName}" — its shared slots were found under different metadata`, verboseOnly: true });
+                    return;
+                }
+                data.schemaHash = signature.Hash;
+                if (signature.Stamp) {
+                    data.schemaStamp = signature.Stamp;
+                }
             }
         }
         // Estimate size by sampling rows (eviction accounting only); the actual stored
         // value is the native object — no full JSON.stringify on the hot path.
         const sizeBytes = this.estimateResultsSize(data.results);
-        // Oversized-entry gate: an entry above maxEntryPercentOfCache of the budget is
-        // never cached. Attempting to store it would trigger a full-cache eviction to
-        // make room for an entry the very next store would evict again — strictly worse
-        // than serving this one query uncached. Always logged (not verbose-gated): an
-        // oversized result is a perf smell the operator should be able to see.
+        // Oversized-entry gate: an entry too large to be RETAINED within the budget is
+        // never cached — storing it would evict other entries for something the next store
+        // evicts again. An entry that fits under MaxEntrySizeBytes is cached however large
+        // it is. Always logged (not verbose-gated): a query too big to cache is a cost the
+        // operator is paying on every call and must be able to see.
         if (this.exceedsMaxEntrySize(sizeBytes)) {
-            LogWarning(`[CACHE-WRITE-GATE] Skipping cache write for "${params.EntityName || fingerprint.substring(0, 60)}" — estimated entry size ${sizeBytes} bytes exceeds per-entry cap (${this._config.maxEntryPercentOfCache}% of ${this._config.maxSizeBytes} byte budget)`, 'Cache');
+            LogWarning(this.describeOversizedEntry(params.EntityName || fingerprint.substring(0, 60), sizeBytes), 'Cache');
             return;
         }
-        // The oversized gate above is the ONLY step that can decline this write, and it is
-        // synchronous — so by here the row set is definitely becoming shared state, and it is
-        // frozen with no intervening yield point. That ordering is load-bearing: the eviction
+        // The schema gate and the oversized gate above are the ONLY steps that can decline this
+        // write, and they are synchronous — so by here the row set is definitely becoming shared
+        // state, and it is frozen with no intervening yield point. That ordering is load-bearing: the eviction
         // steps below are awaited, and callers hold this very array while they run (the
         // smart-cache stale leg does not await this method at all). Freezing after them leaves
         // a window in which shared rows are handed out still mutable — and `BaseEntity`
@@ -2150,8 +2479,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',
@@ -2165,8 +2496,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,
@@ -2194,16 +2526,16 @@ export class LocalCacheManager extends BaseSingleton {
             this._stats.misses++;
             return null;
         }
-        return this.readRunViewSlot(fingerprint);
+        return this.readRunViewSlot(fingerprint, 'serve');
     }
     /** {@link GetRunViewResult} without the open-batch check; slot maintenance reads through this. */
-    async readRunViewSlot(fingerprint) {
+    async readRunViewSlot(fingerprint, purpose) {
         if (!this._storageProvider || !this._config.enabled)
             return null;
         try {
             // Native object read — IDB structured-clones the result back, no JSON.parse needed.
             const parsed = await this._storageProvider.GetItem(fingerprint, CacheCategory.RunViewCache);
-            return this.materializeCachedRunViewResult(fingerprint, parsed);
+            return this.materializeCachedRunViewResult(fingerprint, parsed, purpose);
         }
         catch (e) {
             LogError(`LocalCacheManager.GetRunViewResult failed: ${e}`);
@@ -2243,7 +2575,7 @@ export class LocalCacheManager extends BaseSingleton {
         try {
             const raw = await this._storageProvider.GetItems(fingerprints, CacheCategory.RunViewCache);
             for (const [fp, parsed] of raw) {
-                out.set(fp, this.isPendingInBatch(fp) ? null : this.materializeCachedRunViewResult(fp, parsed));
+                out.set(fp, this.isPendingInBatch(fp) ? null : this.materializeCachedRunViewResult(fp, parsed, 'serve'));
             }
             return out;
         }
@@ -2263,10 +2595,11 @@ export class LocalCacheManager extends BaseSingleton {
      * recording the appropriate hit/miss + access-tracking side effects.
      *
      * Also validates the schema hash (if present) to detect structurally stale
-     * cache entries after schema migrations. If the entity's field list changed
-     * since the entry was cached, the entry is invalidated and null is returned.
+     * cache entries after schema migrations. If the entity's field list differs
+     * from the one the entry was cached under, null is returned; whether the slot
+     * is also deleted depends on `purpose` (see {@link handleSchemaMismatch}).
      */
-    materializeCachedRunViewResult(fingerprint, parsed) {
+    materializeCachedRunViewResult(fingerprint, parsed, purpose) {
         if (!parsed) {
             this._stats.misses++;
             return null;
@@ -2280,8 +2613,9 @@ export class LocalCacheManager extends BaseSingleton {
             this._stats.misses++;
             return null;
         }
-        if (this.isSchemaStaleCacheEntry(fingerprint, parsed)) {
-            this.InvalidateRunViewResult(fingerprint).catch(() => { });
+        const schemaMismatch = this.findSchemaMismatch(fingerprint, parsed);
+        if (schemaMismatch) {
+            this.handleSchemaMismatch(schemaMismatch, purpose, () => this.InvalidateRunViewResult(fingerprint));
             this._stats.misses++;
             return null;
         }
@@ -2289,6 +2623,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,
@@ -2296,14 +2635,34 @@ export class LocalCacheManager extends BaseSingleton {
             totalRowCount: parsed.totalRowCount,
             // Surfaced so in-place maintenance can carry it forward on rewrite (B38).
             schemaHash: parsed.schemaHash,
+            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.
      *
@@ -2464,11 +2823,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;
@@ -2577,7 +2941,7 @@ export class LocalCacheManager extends BaseSingleton {
             return false;
         return this.maintainSlotLocked(fingerprint, async () => {
             try {
-                const cached = await this.readRunViewSlot(fingerprint);
+                const cached = await this.readRunViewSlot(fingerprint, 'maintain');
                 if (!cached) {
                     LogStatusVerbose(`LocalCacheManager.ApplyRowChanges: No cached data found for fingerprint "${fingerprint.substring(0, 60)}" — skipping (cache will be populated on next RunView)`);
                     return false;
@@ -2588,7 +2952,7 @@ export class LocalCacheManager extends BaseSingleton {
                     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,
-                    providerInternalScaffolding: cached.providerInternalScaffolding });
+                    schemaStamp: cached.schemaStamp, providerInternalScaffolding: cached.providerInternalScaffolding });
             }
             catch (e) {
                 LogError(`LocalCacheManager.ApplyRowChanges failed: ${e}`);
@@ -2646,9 +3010,13 @@ export class LocalCacheManager extends BaseSingleton {
         // 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).
         //
@@ -2664,6 +3032,9 @@ export class LocalCacheManager extends BaseSingleton {
         if (prior?.schemaHash) {
             data.schemaHash = prior.schemaHash;
         }
+        if (prior?.schemaStamp) {
+            data.schemaStamp = prior.schemaStamp;
+        }
         // Carry the freeze exemption forward too — a scaffolding slot that gets maintained in
         // place must not silently become frozen, or the owner that mutates those rows breaks on
         // the next read (for the metadata dataset that means booting with no metadata).
@@ -2687,13 +3058,14 @@ 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));
+        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;
@@ -2716,6 +3088,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) {
@@ -2769,8 +3142,14 @@ export class LocalCacheManager extends BaseSingleton {
      * @param rowCount - Optional row count (defaults to results.length if not provided)
      * @param queryId - Optional query ID for reference
      * @param ttlMs - Optional TTL in milliseconds (for cache expiry tracking)
-     */
-    async SetRunQueryResult(fingerprint, queryName, results, maxUpdatedAt, rowCount, queryId, ttlMs, warmedForUserID) {
+     * @param warmedForUserID - The user whose authorized execution produced the rows
+     * @param definition - The query definition the rows were computed under. Stored with the slot so
+     *   a read under a different definition misses (see {@link GetRunQueryResult}), and used to index
+     *   the slot by query ID (see {@link InvalidateRunQueryResultsForQuery}). On a shared store the
+     *   write is skipped while the query's slots are under a write hold (see
+     *   `handleSchemaMismatch`).
+     */
+    async SetRunQueryResult(fingerprint, queryName, results, maxUpdatedAt, rowCount, queryId, ttlMs, warmedForUserID, definition) {
         if (!this._storageProvider || !this._config.enabled)
             return;
         const actualRowCount = rowCount ?? results.length;
@@ -2780,17 +3159,27 @@ export class LocalCacheManager extends BaseSingleton {
         // does not refresh in-process): the warmer proved their permission by executing; anyone
         // ELSE falls through to an authorized execution rather than being served unchecked.
         const data = { results, maxUpdatedAt, rowCount: actualRowCount, queryId, warmedForUserID };
+        if (definition) {
+            if (!this.mayWriteUnderSchemaHold(LocalCacheManager.runQuerySubject(definition, queryName), definition.Hash)) {
+                LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for query "${queryName}" — its shared slots were found under a different definition`, verboseOnly: true });
+                return;
+            }
+            data.definitionHash = definition.Hash;
+            if (definition.Stamp) {
+                data.definitionStamp = definition.Stamp;
+            }
+        }
         // Estimate size by sampling rows (eviction accounting only).
         const sizeBytes = this.estimateResultsSize(results);
         // Oversized-entry gate — same rationale as SetRunViewResult: never wipe the
         // cache to make room for an entry that can't be retained within budget.
         if (this.exceedsMaxEntrySize(sizeBytes)) {
-            LogWarning(`[CACHE-WRITE-GATE] Skipping cache write for query "${queryName}" — estimated entry size ${sizeBytes} bytes exceeds per-entry cap (${this._config.maxEntryPercentOfCache}% of ${this._config.maxSizeBytes} byte budget)`, 'Cache');
+            LogWarning(this.describeOversizedEntry(`query ${queryName}`, sizeBytes), 'Cache');
             return;
         }
         // Same reference-sharing exposure as the RunView path (GetRunQueryResult hands
         // `results` straight back out) — closed here rather than waiting for a mutator to
-        // find it. Placed immediately after the only declining gate and BEFORE the awaited
+        // find it. Placed immediately after the only declining gates and BEFORE the awaited
         // eviction below, for the same reason as SetRunViewResult: callers of this method do
         // not always await it, so any yield point before the freeze is a window in which the
         // caller can still mutate the rows the cache is about to store.
@@ -2808,7 +3197,7 @@ export class LocalCacheManager extends BaseSingleton {
             // reading this slot has no registry entry for it, so a store-side TTL is the only thing
             // that bounds it there. Without it an external-data-source query result was served
             // forever by every server except the one that wrote it.
-            await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunQueryCache, expiresAt ? { TTLSeconds: Math.max(1, Math.ceil((expiresAt - now) / 1000)) } : undefined);
+            await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunQueryCache, LocalCacheManager.runQueryWriteOptions(expiresAt, now, definition?.QueryID ?? queryId));
             this.registerEntry({
                 key: fingerprint,
                 type: 'runquery',
@@ -2827,13 +3216,33 @@ export class LocalCacheManager extends BaseSingleton {
             LogError(`LocalCacheManager.SetRunQueryResult failed: ${e}`);
         }
     }
+    /**
+     * Store options for a RunQuery slot: its expiry, and the query ID as the index group, so a
+     * shared store can list every slot of one query whichever process wrote it.
+     */
+    static runQueryWriteOptions(expiresAt, now, queryId) {
+        const options = {};
+        if (expiresAt) {
+            options.TTLSeconds = Math.max(1, Math.ceil((expiresAt - now) / 1000));
+        }
+        if (queryId) {
+            options.IndexGroup = queryId.trim().toLowerCase();
+        }
+        return options.TTLSeconds !== undefined || options.IndexGroup !== undefined ? options : undefined;
+    }
     /**
      * Retrieves a cached RunQuery result.
      *
      * @param fingerprint - The cache fingerprint
-     * @returns The cached results, maxUpdatedAt, rowCount, and queryId, or null if not found
-     */
-    async GetRunQueryResult(fingerprint) {
+     * @param expectedDefinition - The query definition the caller would execute on a miss. When
+     *   given, a slot written under a different definition (or one that records none) is a miss.
+     *   On a process-local store the slot is also deleted; on a shared store it is left in place and
+     *   this process's writes of the query's slots are held (see `handleSchemaMismatch`). Omit it
+     *   where the caller cannot compute a definition (a client, whose slots the server validates).
+     * @returns The cached results, maxUpdatedAt, rowCount, queryId and definition hash, or null if
+     *   not found, expired, or written under another definition
+     */
+    async GetRunQueryResult(fingerprint, expectedDefinition) {
         if (!this._storageProvider || !this._config.enabled)
             return null;
         // Check if entry has expired
@@ -2848,6 +3257,14 @@ export class LocalCacheManager extends BaseSingleton {
             // Native object read — no JSON.parse needed.
             const parsed = await this._storageProvider.GetItem(fingerprint, CacheCategory.RunQueryCache);
             if (parsed) {
+                const mismatch = expectedDefinition
+                    ? LocalCacheManager.findDefinitionMismatch(parsed, expectedDefinition, entry?.name)
+                    : null;
+                if (mismatch) {
+                    this.handleSchemaMismatch(mismatch, 'serve', () => this.InvalidateRunQueryResult(fingerprint));
+                    this._stats.misses++;
+                    return null;
+                }
                 this.recordAccess(fingerprint);
                 this._stats.hits++;
                 // Handle legacy entries that may not have rowCount
@@ -2861,7 +3278,10 @@ export class LocalCacheManager extends BaseSingleton {
                     // (the B38 omission pattern, which this session exists to stamp out — and
                     // which the first version of this very fix repeated) silently disabled that
                     // tie-break and with it TTL caching for runtime-created queries.
-                    warmedForUserID: parsed.warmedForUserID
+                    warmedForUserID: parsed.warmedForUserID,
+                    // Same pass-through rule: a client sends it back to the server, which answers
+                    // `stale` when its own definition differs.
+                    definitionHash: parsed.definitionHash
                 };
             }
         }
@@ -2871,6 +3291,22 @@ export class LocalCacheManager extends BaseSingleton {
         this._stats.misses++;
         return null;
     }
+    /**
+     * Compares a RunQuery slot's definition hash with the definition the caller expects. A slot
+     * that records no hash was written before slots carried one, so nothing says which SQL produced
+     * its rows; it counts as a mismatch with an unknown order.
+     */
+    static findDefinitionMismatch(data, expected, queryName) {
+        if (data.definitionHash === expected.Hash) {
+            return null;
+        }
+        return {
+            Subject: LocalCacheManager.runQuerySubject(expected, queryName),
+            CachedHash: data.definitionHash ?? '',
+            Current: { Hash: expected.Hash, Stamp: expected.Stamp },
+            EntryIsNewer: LocalCacheManager.isNewerSchemaStamp(data.definitionStamp, expected.Stamp),
+        };
+    }
     /**
      * Invalidates a cached RunQuery result.
      *
@@ -2891,7 +3327,12 @@ export class LocalCacheManager extends BaseSingleton {
      * Invalidates all cached RunQuery results for a specific query.
      * Useful when a query's underlying data changes and all related caches should be cleared.
      *
+     * Matches this process's registry by name only, so it misses slots written by other processes
+     * on a shared store and slots written under a former name.
+     *
      * @param queryName - The query name to invalidate
+     * @deprecated Use {@link InvalidateRunQueryResultsForQuery}, which finds a query's slots by ID
+     *   in every process that shares the store.
      */
     async InvalidateQueryCaches(queryName) {
         if (!this._storageProvider)
@@ -2914,12 +3355,66 @@ export class LocalCacheManager extends BaseSingleton {
         }
         await this.persistRegistry();
     }
+    /**
+     * Deletes every cached RunQuery result of one query: the slots this process wrote, and on a
+     * shared store every slot any process wrote with the query's ID (see {@link SetRunQueryResult}).
+     * Slots keyed by the query's name alone, or written before slots were indexed, are not found;
+     * a definition check on read (see {@link GetRunQueryResult}) keeps them from being served.
+     * Never throws.
+     *
+     * @param queryId - The query whose slots to delete
+     * @returns The number of slots deleted
+     */
+    async InvalidateRunQueryResultsForQuery(queryId) {
+        if (!this._storageProvider || !queryId)
+            return 0;
+        const keys = await this.findRunQueryKeysForQuery(queryId);
+        let removed = 0;
+        for (const key of keys) {
+            try {
+                await this._storageProvider.Remove(key, CacheCategory.RunQueryCache);
+                this._registry.delete(key);
+                removed++;
+            }
+            catch (e) {
+                LogError(`LocalCacheManager.InvalidateRunQueryResultsForQuery failed for key ${key}: ${e}`);
+            }
+        }
+        if (removed > 0) {
+            await this.persistRegistry();
+        }
+        return removed;
+    }
+    /** The keys of one query's RunQuery slots: this process's registry, plus the shared index. */
+    async findRunQueryKeysForQuery(queryId) {
+        const id = queryId.trim().toLowerCase();
+        const keys = new Set();
+        for (const [key, entry] of this._registry.entries()) {
+            // A fingerprint is `Name|ID|Category|Params[|Connection]`; matching any segment keeps a
+            // name that itself contains '|' from hiding the ID.
+            if (entry.type === 'runquery' && key.toLowerCase().split('|').includes(id)) {
+                keys.add(key);
+            }
+        }
+        if (this._storageProvider?.GetIndexGroupKeys) {
+            try {
+                for (const key of await this._storageProvider.GetIndexGroupKeys(CacheCategory.RunQueryCache, id)) {
+                    keys.add(key);
+                }
+            }
+            catch (e) {
+                LogError(`LocalCacheManager: listing RunQuery slots of query ${queryId} failed: ${e}`);
+            }
+        }
+        return keys;
+    }
     /**
      * Gets the cache status (fingerprint data) for a RunQuery result.
      * Used for smart cache validation with the server.
      *
      * @param fingerprint - The cache fingerprint
-     * @returns The cache status with maxUpdatedAt and rowCount, or null if not found/expired
+     * @returns The cache status with maxUpdatedAt, rowCount and the definition hash the slot was
+     *   written under, or null if not found/expired
      */
     async GetRunQueryCacheStatus(fingerprint) {
         const cached = await this.GetRunQueryResult(fingerprint);
@@ -2927,7 +3422,8 @@ export class LocalCacheManager extends BaseSingleton {
             return null;
         return {
             maxUpdatedAt: cached.maxUpdatedAt,
-            rowCount: cached.rowCount
+            rowCount: cached.rowCount,
+            definitionHash: cached.definitionHash
         };
     }
     // ========================================================================
@@ -2957,17 +3453,24 @@ export class LocalCacheManager extends BaseSingleton {
             runview: { count: 0, sizeBytes: 0 },
             runquery: { count: 0, sizeBytes: 0 }
         };
+        let totalSizeBytes = 0;
+        let oldestEntry = Infinity;
+        let newestEntry = 0;
         for (const entry of entries) {
             byType[entry.type].count++;
             byType[entry.type].sizeBytes += entry.sizeBytes;
+            totalSizeBytes += entry.sizeBytes;
+            if (entry.cachedAt < oldestEntry)
+                oldestEntry = entry.cachedAt;
+            if (entry.cachedAt > newestEntry)
+                newestEntry = entry.cachedAt;
         }
-        const timestamps = entries.map(e => e.cachedAt);
         return {
             totalEntries: entries.length,
-            totalSizeBytes: entries.reduce((sum, e) => sum + e.sizeBytes, 0),
+            totalSizeBytes,
             byType,
-            oldestEntry: timestamps.length ? Math.min(...timestamps) : 0,
-            newestEntry: timestamps.length ? Math.max(...timestamps) : 0,
+            oldestEntry: entries.length > 0 ? oldestEntry : 0,
+            newestEntry,
             hits: this._stats.hits,
             misses: this._stats.misses
         };
@@ -3000,6 +3503,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}`);
@@ -3030,6 +3534,7 @@ export class LocalCacheManager extends BaseSingleton {
             }
         }
         this._registry.clear();
+        this._lastVerifiedAt.clear();
         this._stats = { hits: 0, misses: 0 };
         await this.persistRegistry();
         return count;
@@ -3080,6 +3585,7 @@ export class LocalCacheManager extends BaseSingleton {
      */
     unregisterEntry(key) {
         this._registry.delete(key);
+        this._lastVerifiedAt.delete(key);
         this.debouncedPersistRegistry();
     }
     /**
@@ -3187,7 +3693,7 @@ export class LocalCacheManager extends BaseSingleton {
                 return 0;
             }
         };
-        const sampleCount = Math.min(rowCount, Math.max(3, Math.ceil(rowCount * 0.10)));
+        const sampleCount = rowCount <= 3 ? rowCount : Math.min(10, Math.max(3, Math.ceil(rowCount * 0.10)));
         if (sampleCount >= rowCount) {
             // Small result set — measure every row (no point sampling).
             let total = 0;
@@ -3209,32 +3715,89 @@ export class LocalCacheManager extends BaseSingleton {
         return Math.ceil(avgLen * rowCount) * 2;
     }
     /**
-     * Returns true when a single entry of the given estimated size exceeds the
-     * per-entry cap (maxEntryPercentOfCache of maxSizeBytes) and must not be
-     * cached. See the config property's doc comment for the full rationale —
-     * in short, an entry that large can only be stored by evicting most (or
-     * all) of the cache, and it would be evicted again on the next store, so
-     * caching it is strictly worse than skipping it.
+     * The largest single entry this cache will store, in bytes, or 0 when no ceiling
+     * applies (`maxEntryPercentOfCache: 0`).
+     *
+     * `'auto'` derives it from the budget — the whole budget less
+     * {@link SINGLE_ENTRY_RESERVE_PERCENT} — so the ceiling grows with the memory the
+     * operator gave the cache instead of being a small fixed fraction that the biggest
+     * entity can never fit under. An explicit percentage is honoured as a stricter
+     * ceiling, clamped to {@link HARD_MAX_ENTRY_PERCENT} so no configuration can admit an
+     * entry that leaves the cache with less free space than one eviction pass needs.
      */
-    exceedsMaxEntrySize(sizeBytes) {
-        const pct = this._config.maxEntryPercentOfCache;
+    get MaxEntrySizeBytes() {
+        const pct = this.effectiveMaxEntryPercent;
         if (pct <= 0)
+            return 0;
+        return Math.floor(this._config.maxSizeBytes * pct / 100);
+    }
+    /**
+     * The per-entry ceiling as a percentage of the budget, with `'auto'` resolved and an
+     * explicit configuration clamped. 0 or below means "no ceiling".
+     */
+    get effectiveMaxEntryPercent() {
+        const pct = this._config.maxEntryPercentOfCache;
+        if (pct === 'auto') {
+            return 100 - Math.max(SINGLE_ENTRY_RESERVE_PERCENT, EVICTION_THRASH_FLOOR_PERCENT);
+        }
+        return Math.min(pct, HARD_MAX_ENTRY_PERCENT);
+    }
+    /**
+     * Returns true when a single entry of the given estimated size exceeds
+     * {@link MaxEntrySizeBytes} and must not be cached. See the config property's doc
+     * comment for the rationale — in short, an entry that cannot be RETAINED within the
+     * budget would be evicted again on the next store, so caching it is churn. An entry
+     * that fits is cached however large it is: the cases that most need caching are the
+     * large ones.
+     */
+    exceedsMaxEntrySize(sizeBytes) {
+        const ceiling = this.MaxEntrySizeBytes;
+        if (ceiling <= 0)
             return false;
-        return sizeBytes > Math.floor(this._config.maxSizeBytes * pct / 100);
+        return sizeBytes > ceiling;
+    }
+    /**
+     * Renders the decline of an oversized entry as something an operator can act on: what
+     * the ceiling is, and the `cacheSettings.maxMemoryMB` that would admit this entry.
+     * The old message reported raw byte counts and a percentage, which named the symptom
+     * but not the lever — and the entries it declines are exactly the expensive queries
+     * whose absence from the cache costs the most.
+     */
+    describeOversizedEntry(label, sizeBytes) {
+        const mb = (bytes) => (bytes / 1024 / 1024).toFixed(1);
+        const pct = this.effectiveMaxEntryPercent;
+        const head = `[CACHE-WRITE-GATE] Not caching "${label}" — ${mb(sizeBytes)}MB exceeds the largest single entry this cache can retain (${mb(this.MaxEntrySizeBytes)}MB of a ${mb(this._config.maxSizeBytes)}MB budget). Every read of it goes to the database.`;
+        // pct can only be <= 0 with the ceiling disabled, in which case nothing is declined
+        // and this message is never produced — but the arithmetic below must not divide by it.
+        if (pct <= 0)
+            return head;
+        const requiredBudgetMB = Math.ceil((sizeBytes * 100 / pct) / 1024 / 1024);
+        return `${head} To cache it, raise cacheSettings.maxMemoryMB to ${requiredBudgetMB} or more.`;
     }
     /**
      * Evicts entries if needed to make room for new data.
+     *
+     * Frees the DEFICIT — how far over budget the cache would be with the incoming entry —
+     * rounded up to {@link EVICTION_THRASH_FLOOR_PERCENT} of the budget so a run of stores
+     * near the budget does not evict on every one. It deliberately does not free the
+     * incoming entry's whole size: for a large entry arriving into a mostly empty cache the
+     * deficit is small, and freeing the entry's full size instead emptied the cache to make
+     * room that was already there. That over-eviction is what made a large entry look
+     * inherently destructive, and it is why the per-entry ceiling used to be set low enough
+     * to exclude every large entry.
      */
     async evictIfNeeded(neededBytes) {
         if (!this._storageProvider)
             return;
-        const stats = this.GetStats();
-        const wouldExceedSize = (stats.totalSizeBytes + neededBytes) > this._config.maxSizeBytes;
-        if (!wouldExceedSize)
+        let currentSizeBytes = 0;
+        for (const entry of this._registry.values()) {
+            currentSizeBytes += entry.sizeBytes;
+        }
+        const deficitBytes = (currentSizeBytes + neededBytes) - this._config.maxSizeBytes;
+        if (deficitBytes <= 0)
             return;
-        // Calculate how much to free — at least the incoming entry's size, but
-        // free 10% of total budget to avoid thrashing on every store.
-        const targetFreeBytes = Math.max(neededBytes, this._config.maxSizeBytes * 0.1);
+        const thrashFloorBytes = Math.floor(this._config.maxSizeBytes * EVICTION_THRASH_FLOOR_PERCENT / 100);
+        const targetFreeBytes = Math.max(deficitBytes, thrashFloorBytes);
         await this.evict(targetFreeBytes);
     }
     /**
@@ -3280,6 +3843,7 @@ export class LocalCacheManager extends BaseSingleton {
                     this.removeFromEntityIndex(entry.fingerprint);
                 }
                 this._registry.delete(key);
+                this._lastVerifiedAt.delete(key);
             }
             catch (e) {
                 // Continue evicting other entries
@@ -3332,6 +3896,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
@@ -3436,6 +4001,7 @@ export class LocalCacheManager extends BaseSingleton {
             this.removeFromEntityIndex(entry.fingerprint);
         }
         this._registry.delete(key);
+        this._lastVerifiedAt.delete(key);
     }
 }
 //# sourceMappingURL=localCacheManager.js.map