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

package/dist/generic/localCacheManager.js

@@ -1,9 +1,10 @@
 import { BaseSingleton, MJGlobal, MJEventType } from "@memberjunction/global";
 import { IsMaterializedDataSource } from "../views/runView.js";
-import { LogError, LogStatusEx } from "./logging.js";
+import { LogError, LogStatusEx, LogWarning } from "./logging.js";
 import { BaseEntity } from "./baseEntity.js";
 import { Metadata } from "./metadata.js";
 import { CompositeKey, KeyValuePair } from "./compositeKey.js";
+import { EntityEventBatchSet } from "./entityEventBatch.js";
 /** Verbose-only status logging — hidden unless verbose logging is enabled */
 function LogStatusVerbose(message) {
     LogStatusEx({ message, verboseOnly: true });
@@ -55,13 +56,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,
 };
@@ -118,6 +141,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;
@@ -139,6 +167,20 @@ export class LocalCacheManager extends BaseSingleton {
          * (e.g., TransactionGroup batch deletes).
          */
         this._fingerprintLocks = new Map();
+        /** Logged once when a local TTL is configured against a shared store. See {@link runEvictionSweep}. */
+        this._sharedTTLWarned = false;
+        /** Open entity-event batches. See {@link BeginEntityEventBatch}. */
+        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
@@ -146,6 +188,7 @@ export class LocalCacheManager extends BaseSingleton {
          * event fires so we can update all relevant cached results.
          */
         this._entityFingerprintIndex = new Map();
+        this._initializedListeners = [];
         // ========================================================================
         // CROSS-SERVER CACHE CHANGE CALLBACKS
         // ========================================================================
@@ -168,22 +211,29 @@ export class LocalCacheManager extends BaseSingleton {
      * Initialize the cache manager with a storage provider.
      * This should be called during app startup after the storage provider is available.
      *
-     * This method is safe to call multiple times - subsequent calls will return the same
-     * promise as the first caller, ensuring initialization only happens once.
+     * Safe to call repeatedly: the cache is initialized once, but **a `config` passed by a later
+     * caller is still applied**. That matters because a database provider initializes this manager
+     * from inside its own `Config()` — before the host has a chance to pass anything — so a host
+     * that hands its settings to `StartupManager` would otherwise have them silently dropped, and
+     * every `cacheSettings` knob would be inert. The host's explicit settings win
+     * over the provider's implicit initialization, whichever runs first.
      *
      * @param storageProvider - The local storage provider to use for persistence
-     * @param config - Optional configuration overrides
+     * @param config - Optional configuration overrides, applied even when already initialized
      * @returns A promise that resolves when initialization is complete
      */
     Initialize(storageProvider, config) {
-        // If already initialized, return immediately
         if (this._initialized) {
+            if (config) {
+                this.UpdateConfig(config);
+            }
             return Promise.resolve();
         }
-        // If initialization is in progress, return the existing promise
-        // so all callers await the same initialization
+        // Initialization in flight: share it, then apply this caller's settings on top.
         if (this._initializePromise) {
-            return this._initializePromise;
+            return config
+                ? this._initializePromise.then(() => { this.UpdateConfig(config); })
+                : this._initializePromise;
         }
         // First caller - start initialization and store the promise
         this._initializePromise = this.doInitialize(storageProvider, config);
@@ -254,6 +304,36 @@ export class LocalCacheManager extends BaseSingleton {
         // Subscribe to BaseEntity events for universal cache invalidation.
         // When any entity is saved/deleted, update all cached RunView results for that entity.
         this.subscribeToBaseEntityEvents();
+        this.notifyInitialized();
+    }
+    /**
+     * Runs `listener` once the cache manager is initialized — immediately if it already is.
+     * Lets code that ran too early (an engine loaded before startup initialized the cache) finish
+     * its cache wiring later instead of never.
+     *
+     * @param listener - Called once; errors are logged and do not affect other listeners
+     */
+    WhenInitialized(listener) {
+        if (this._initialized) {
+            this.runInitializedListener(listener);
+            return;
+        }
+        this._initializedListeners.push(listener);
+    }
+    runInitializedListener(listener) {
+        try {
+            listener();
+        }
+        catch (e) {
+            LogError(`LocalCacheManager.WhenInitialized listener failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    notifyInitialized() {
+        const listeners = this._initializedListeners;
+        this._initializedListeners = [];
+        for (const listener of listeners) {
+            this.runInitializedListener(listener);
+        }
     }
     /**
      * Returns whether the cache manager has been initialized
@@ -268,10 +348,24 @@ export class LocalCacheManager extends BaseSingleton {
         return { ...this._config };
     }
     /**
-     * Updates the configuration at runtime
+     * Updates the configuration at runtime, and re-arms the eviction sweep so a changed interval
+     * (or a disabled cache) takes effect immediately instead of at the next restart.
      */
     UpdateConfig(config) {
+        const previousInterval = this._config.evictionSweepIntervalMs;
+        const wasEnabled = this._config.enabled;
         this._config = { ...this._config, ...config };
+        if (!this._initialized) {
+            return; // doInitialize starts the sweep with the merged config
+        }
+        if (this._config.evictionSweepIntervalMs !== previousInterval || this._config.enabled !== wasEnabled) {
+            if (this._config.enabled) {
+                this.startEvictionSweep();
+            }
+            else {
+                this.stopEvictionSweep();
+            }
+        }
     }
     /**
      * Checks whether caching is enabled for a given entity. Returns the entity's
@@ -294,9 +388,15 @@ export class LocalCacheManager extends BaseSingleton {
      * @param newProvider - The new storage provider to use
      */
     async SetStorageProvider(newProvider) {
+        if (newProvider === this._storageProvider) {
+            // Already in use (a host that installed its shared store before startup): migrating
+            // every entry onto itself would rewrite — and republish — all of them.
+            return;
+        }
         // The freeze decision belongs to the ACTIVE provider, not to whichever one happened to be
-        // installed at Initialize. MJAPI initializes on the in-memory provider during engine
-        // loading and swaps to Redis afterward, so these two have OPPOSITE reference semantics on
+        // installed at Initialize. A host may still swap stores after initialization (and MJAPI did,
+        // before it began installing Redis ahead of metadata), and the two have OPPOSITE reference
+        // semantics on
         // every Redis deployment — carrying the old answer forward means freezing rows Redis has
         // already isolated (all of the hazard, none of the protection), or, on the reverse swap,
         // silently dropping the protection.
@@ -321,7 +421,7 @@ export class LocalCacheManager extends BaseSingleton {
                 const category = this.getCategoryForType(entry.type);
                 const data = await oldProvider?.GetItem(entry.key, category);
                 if (data) {
-                    await newProvider.SetItem(entry.key, data, category);
+                    await newProvider.SetItem(entry.key, data, category, this.writeOptionsForEntry(entry));
                     migratedCount++;
                 }
             }
@@ -381,6 +481,23 @@ export class LocalCacheManager extends BaseSingleton {
      * in-place mutation (`canUseImmediateMutation`); this closes the same gap in the raw
      * provider cache. (B42)
      *
+     * Maintaining the order in place was built and then withdrawn, so the payoff is on record rather
+     * than left to be rediscovered. It is possible for a narrow subset — plain column terms over
+     * numeric/date/boolean fields with no NULLs present, where JavaScript and SQL provably agree —
+     * but the subset is where the value dies, not the implementation. Of 918 RunView param literals
+     * in this repo, 289 carry an ORDER BY, 112 are also unfiltered and uncapped (the only ones a slot
+     * could maintain), and roughly 26 fall in that type subset, several of which order on a
+     * uniqueidentifier and are refused anyway. The survivors are about a dozen configuration and
+     * admin lists — API keys, credentials, view types, schema info — saved rarely, so the saving is a
+     * handful of small indexed reads per day. High-write entities gain nothing: every ordered read of
+     * MJ: AI Agent Runs, MJ: Conversation Details and MJ: AI Prompt Runs is FILTERED, so their slots
+     * land in the invalidate branch regardless. Against that, the cost is a comparator that must keep
+     * agreeing with SQL collation and NULL placement across dialects forever, whose failure mode is a
+     * silently reordered list in a slot other readers treat as authoritative. Widening it to strings —
+     * by far the largest bucket, `Name` — means owning collation per dialect and per column.
+     *
+     * If you are about to attempt this, the measurement above is the argument not to.
+     *
      * @param parts - the fingerprint already split on '|'
      */
     hasOrderBy(parts) {
@@ -540,30 +657,227 @@ 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) {
-            LogStatusEx({
-                message: `[CACHE-SCHEMA-STALE] Entity "${entityName}" schema changed (cached=${data.schemaHash}, current=${currentHash})`,
-                verboseOnly: false
+        }
+        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
+     * `undefined` when the rows carry no such column (so the caller can fall back to its own stamp).
+     * Mirrors how the RunView fill path stamps a slot.
+     */
+    static MaxUpdatedAtOfRows(rows) {
+        let max = Number.NEGATIVE_INFINITY;
+        let sawColumn = false;
+        for (const row of rows) {
+            if (!row || typeof row !== 'object') {
+                continue;
+            }
+            // `UpdatedAt` is the fallback an entity whose view predates the `__mj_` prefix carries.
+            // Both cache-write funnels must agree on the stamp they compute, or the same rows get
+            // different slot timestamps depending on which path wrote them and every currency check
+            // between them misfires.
+            const record = row;
+            const raw = record['__mj_UpdatedAt'] !== undefined ? record['__mj_UpdatedAt'] : record['UpdatedAt'];
+            if (raw === undefined) {
+                continue;
+            }
+            sawColumn = true;
+            if (raw === null) {
+                continue; // new Date(null) is the epoch, not "no timestamp"
+            }
+            const ms = raw instanceof Date ? raw.getTime() : new Date(raw).getTime();
+            if (!Number.isNaN(ms) && ms > max) {
+                max = ms;
+            }
+        }
+        if (rows.length === 0) {
+            return '';
+        }
+        if (!sawColumn) {
+            return undefined;
+        }
+        return max === Number.NEGATIVE_INFINITY ? '' : new Date(max).toISOString();
+    }
+    /**
+     * Storage write options for a RunView slot: the entity name as index group, so a shared
+     * provider can find the slot from any process, and the time left before the slot's own expiry
+     * (external-data-source entities), so a rewrite does not extend it.
+     *
+     * @param fingerprint - The slot key
+     * @param expiresAt - Absolute expiry (ms since epoch), when the slot has one
+     */
+    runViewWriteOptions(fingerprint, expiresAt) {
+        const options = {};
+        const entity = this.extractEntityFromFingerprint(fingerprint);
+        if (entity) {
+            options.IndexGroup = entity;
+        }
+        if (expiresAt) {
+            options.TTLSeconds = Math.max(1, Math.ceil((expiresAt - Date.now()) / 1000));
+        }
+        return options;
+    }
+    /** Storage write options for any registry entry; only RunView slots are indexed. */
+    writeOptionsForEntry(entry) {
+        if (entry.type === 'runview') {
+            return this.runViewWriteOptions(entry.key, entry.expiresAt);
+        }
+        return entry.expiresAt ? { TTLSeconds: Math.max(1, Math.ceil((entry.expiresAt - Date.now()) / 1000)) } : undefined;
     }
     /**
      * Adds a fingerprint to the entity→fingerprint reverse index.
@@ -602,13 +916,31 @@ export class LocalCacheManager extends BaseSingleton {
         return this._entityFingerprintIndex.get(entityName) ?? new Set();
     }
     /**
-     * Resolves cached fingerprints for an entity, checking the local in-memory
-     * index first and falling back to the shared storage provider (e.g., Redis)
-     * when the local index is empty. This handles cross-server scenarios where
-     * Server A cached RunView results and Server B saves a record — Server B's
-     * local index is empty but Redis still has the stale cached entries.
+     * Resolves cached fingerprints for an entity: this process's own index, plus — on a storage
+     * provider shared between processes — the slots other processes wrote.
+     *
+     * A save on server A has to reach slots server B wrote after A booted, because nothing else
+     * will: B only hears about A's save through the slots A rewrites. A shared provider therefore
+     * answers from its per-entity index ({@link ILocalStorageProvider.GetIndexGroupKeys}) on every
+     * call. A provider without that index is process-local or cannot enumerate cheaply, and keeps
+     * the older behaviour: the category is listed only when the local index knows nothing.
      */
     async resolveFingerprintsForEntity(entityName) {
+        if (this._storageProvider?.GetIndexGroupKeys) {
+            const shared = await this._storageProvider.GetIndexGroupKeys(CacheCategory.RunViewCache, entityName);
+            // The local index is deliberately NOT pruned against the shared group here. A slot this
+            // process wrote that the group no longer lists is one that expired or was cleared
+            // elsewhere — and peers may still be holding its rows in memory. Keeping it means the
+            // next save invalidates it, which is what publishes the `removed` those peers reload
+            // on (pinned by localCacheManager.sharedIndex.test.ts). The invalidation then
+            // drops it from the index, so that costs one notice per slot, once — not per save.
+            // Reviewed as and rejected on that evidence
+            for (const fp of shared) {
+                this.addToEntityIndex(fp);
+            }
+            const merged = this._entityFingerprintIndex.get(entityName);
+            return merged && merged.size > 0 ? merged : undefined;
+        }
         const local = this._entityFingerprintIndex.get(entityName);
         if (local && local.size > 0)
             return local;
@@ -656,6 +988,9 @@ export class LocalCacheManager extends BaseSingleton {
             // Only react to completed save and delete events
             if (entityEvent.type !== 'save' && entityEvent.type !== 'delete')
                 return;
+            // Inside an open batch the change is recorded now and applied when the batch closes.
+            if (this.bufferIfBatching(entityEvent))
+                return;
             // Fire-and-forget to avoid blocking the save/delete operation
             this.HandleBaseEntityEvent(entityEvent).catch((err) => {
                 LogError(`LocalCacheManager.HandleBaseEntityEvent error: ${err.message}`);
@@ -721,6 +1056,306 @@ export class LocalCacheManager extends BaseSingleton {
             }));
         }
     }
+    // ========================================================================
+    // ENTITY-EVENT BATCHES
+    // ========================================================================
+    /**
+     * Opens a batch for `owner` (normally a provider), or enters the one already open. Until the
+     * matching {@link EndEntityEventBatch}, saves and deletes raised by entities that use `owner`
+     * as their provider are recorded instead of applied; closing the batch rewrites each affected
+     * slot once. `DatabaseProviderBase.BeginEntityTransaction` opens one for every transaction, so
+     * callers rarely need this directly — {@link RunInEntityEventBatch} is the wrapper for bulk
+     * writers that do not use a transaction.
+     *
+     * Every call must be paired with exactly one {@link EndEntityEventBatch}.
+     */
+    BeginEntityEventBatch(owner) {
+        this._entityEventBatches.Open(owner);
+    }
+    /**
+     * Replaces a RunView slot wholesale while holding the cross-process lock for it.
+     *
+     * The event-driven path already reads-modifies-writes under that lock; a writer that replaces
+     * the same slot outside it can land between a peer's read and its write, and whichever `SET`
+     * lands second wins — the engine sweep's fresh rows lost, or the peer's delta lost, and either
+     * way the losing state is published to the fleet.
+     */
+    async ReplaceRunViewResultLocked(fingerprint, params, results, maxUpdatedAt, totalRowCount, provider) {
+        if (!this._storageProvider || !this._config.enabled) {
+            return false;
+        }
+        // Carry the slot's existing expiry across the replace. An external-data-source slot has one,
+        // and a rewrite that dropped it would turn a bounded cache entry into a permanent one
+        //.
+        const ttlMs = this.remainingTTLForSlot(fingerprint);
+        return this.maintainSlotLocked(fingerprint, async () => {
+            await this.SetRunViewResult(fingerprint, params, results, maxUpdatedAt, undefined, totalRowCount, provider, ttlMs);
+            return true;
+        });
+    }
+    /** Milliseconds left on a slot's expiry, or undefined when it has none. @internal */
+    remainingTTLForSlot(fingerprint) {
+        const expiresAt = this._registry.get(fingerprint)?.expiresAt;
+        if (!expiresAt) {
+            return undefined;
+        }
+        return Math.max(1, expiresAt - Date.now());
+    }
+    /**
+     * Abandons `owner`'s batch at any depth and invalidates every slot it touched.
+     *
+     * For an owner that cannot settle its batch normally: an independent provider instance being
+     * released with a transaction still open, or a transaction handle reset after a failure. The
+     * buffered rows may or may not have reached the database, so the affected slots are invalidated
+     * rather than written, and the entities stop counting as pending — a batch left open makes
+     * every cached read of its entities miss, for the life of the process.
+     *
+     * Never throws. Safe when no batch is open.
+     */
+    async AbandonEntityEventBatch(owner) {
+        const batch = this._entityEventBatches.Abandon(owner);
+        if (!batch) {
+            return;
+        }
+        LogWarning(`LocalCacheManager: an entity-event batch was abandoned with ${batch.Changes.length} buffered change(s) across ${batch.TouchedEntities.size} entit${batch.TouchedEntities.size === 1 ? 'y' : 'ies'} — invalidating them, because whether those rows reached the database is unknown`, 'Cache');
+        try {
+            await this.invalidateBatchEntities(batch);
+        }
+        catch (e) {
+            LogError(`LocalCacheManager.AbandonEntityEventBatch failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Leaves one level of `owner`'s batch. Closing the outermost level applies the batch: with
+     * every level successful, each affected slot is rewritten once with all its changes; if any
+     * level failed (a rollback), the affected slots are invalidated instead, so every server reloads
+     * them from the database. Never throws.
+     *
+     * @param owner - The object passed to {@link BeginEntityEventBatch}
+     * @param succeeded - False when the work this level covered was rolled back or failed
+     */
+    async EndEntityEventBatch(owner, succeeded) {
+        const batch = this._entityEventBatches.Close(owner, succeeded);
+        if (!batch) {
+            return;
+        }
+        try {
+            await this.applyEntityEventBatch(batch);
+        }
+        catch (e) {
+            LogError(`LocalCacheManager: applying an entity-event batch failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    /**
+     * Claims a named lease on the storage provider for `ttlMs`: on a shared store only one process
+     * gets it per period; on a private store the caller always does. A lease that cannot be
+     * checked is reported as not claimed.
+     */
+    async TryAcquireSharedLease(name, ttlMs) {
+        return (await this.claimLease(name, ttlMs)) === 'claimed';
+    }
+    /** One lease attempt: claimed, held by another process, or the store could not be asked. */
+    async claimLease(name, ttlMs) {
+        const provider = this._storageProvider;
+        if (!provider?.TryAcquireLease) {
+            return 'claimed';
+        }
+        try {
+            return (await provider.TryAcquireLease(name, ttlMs)) ? 'claimed' : 'held';
+        }
+        catch (e) {
+            LogWarning(`LocalCacheManager: could not claim lease "${name}" (${e instanceof Error ? e.message : String(e)})`, 'Cache');
+            return 'error';
+        }
+    }
+    /**
+     * Extends a lease this process already holds, so long-running work keeps its turn. Falls back
+     * to re-claiming when the store has no dedicated renewal, which is a no-op for anyone else's
+     * lease because the claim is `SET NX`. Never throws.
+     *
+     * @returns true when the lease is still (or again) held by this process.
+     */
+    async RenewSharedLease(name, ttlMs) {
+        const provider = this._storageProvider;
+        if (!provider?.TryAcquireLease) {
+            return true; // no shared store: this process is the only one, and holds it by default
+        }
+        try {
+            const renew = provider.RenewLease;
+            if (renew) {
+                return await renew.call(provider, name, ttlMs);
+            }
+            return await provider.TryAcquireLease(name, ttlMs);
+        }
+        catch (e) {
+            LogWarning(`LocalCacheManager: could not renew lease "${name}" (${e instanceof Error ? e.message : String(e)})`, 'Cache');
+            return false;
+        }
+    }
+    /** Ends a lease claimed with {@link TryAcquireSharedLease}. Never throws. */
+    async ReleaseSharedLease(name) {
+        try {
+            await this._storageProvider?.ReleaseLease?.(name);
+        }
+        catch (e) {
+            LogWarning(`LocalCacheManager: could not release lease "${name}" (${e instanceof Error ? e.message : String(e)})`, 'Cache');
+        }
+    }
+    /**
+     * Waits until this process claims the lease, polling every `pollMs`, for at most `maxWaitMs`.
+     * @returns Whether the lease was claimed, and how long the wait took.
+     */
+    async WaitForSharedLease(name, ttlMs, maxWaitMs, pollMs = 100) {
+        const started = Date.now();
+        for (;;) {
+            const outcome = await this.claimLease(name, ttlMs);
+            if (outcome !== 'held') {
+                // An unreachable store coordinates nothing, so waiting on it would only delay the caller.
+                return { Acquired: outcome === 'claimed', WaitedMs: Date.now() - started };
+            }
+            if (Date.now() - started >= maxWaitMs) {
+                return { Acquired: false, WaitedMs: Date.now() - started };
+            }
+            await new Promise(resolve => setTimeout(resolve, pollMs));
+        }
+    }
+    /** True while a batch is open for `owner`. */
+    IsBatchingEntityEvents(owner) {
+        return this._entityEventBatches.Find(owner) !== undefined;
+    }
+    /**
+     * True when a batch took `entityEvent` as it was raised, so closing that batch maintains every
+     * slot indexed for the entity. A listener that reaches its cache write only after an `await`
+     * asks this instead of {@link IsBatchingEntityEvents}: by then the batch may have closed, and
+     * a write of its own would rewrite the slot once per event.
+     */
+    WasTakenByEntityEventBatch(entityEvent) {
+        return this._eventsTakenByBatch.has(entityEvent);
+    }
+    /**
+     * Runs `work` inside an entity-event batch for `owner` and applies the batch when it finishes
+     * (as a failure when `work` throws). Use for bulk writes that do not already run in a
+     * transaction.
+     */
+    async RunInEntityEventBatch(owner, work) {
+        this.BeginEntityEventBatch(owner);
+        let succeeded = false;
+        try {
+            const result = await work();
+            succeeded = true;
+            return result;
+        }
+        finally {
+            await this.EndEntityEventBatch(owner, succeeded);
+        }
+    }
+    /**
+     * Records a save/delete in the batch open for the entity's provider.
+     * @returns True when the event was taken by a batch (or needs no cache work at all).
+     */
+    bufferIfBatching(entityEvent) {
+        const owner = entityEvent.baseEntity?.ProviderToUse;
+        if (!this._entityEventBatches.Find(owner)) {
+            return false;
+        }
+        const taken = this._entityEventBatches.Record(owner, this.captureEntityChange(entityEvent));
+        if (taken) {
+            this._eventsTakenByBatch.add(entityEvent);
+        }
+        return taken;
+    }
+    /**
+     * True when `fingerprint`'s entity has changes waiting in an open batch. Such a slot is behind
+     * what the unit of work has written, so reads treat it as a miss (the database answers,
+     * including the uncommitted rows for a reader inside the transaction) and fills are not stored.
+     */
+    isPendingInBatch(fingerprint) {
+        const entityName = this.extractEntityFromFingerprint(fingerprint);
+        return entityName !== null && this._entityEventBatches.HasPendingChanges(entityName);
+    }
+    /**
+     * The change a save/delete event describes, captured now — the entity object can change (or,
+     * after a delete, be reset) before a batch closes. Null when the event needs no cache work.
+     */
+    captureEntityChange(entityEvent) {
+        const entityInfo = entityEvent.baseEntity?.EntityInfo;
+        if (!entityInfo?.Name || !this.IsCachingEnabledForEntity(entityInfo) || !entityInfo.PrimaryKeys?.length) {
+            return null;
+        }
+        if (entityEvent.type !== 'save' && entityEvent.type !== 'delete') {
+            return null;
+        }
+        // A delete resets the entity right after raising the event; its payload keeps the old values.
+        const payload = entityEvent.payload;
+        const record = (entityEvent.type === 'delete' && payload?.OldValues)
+            ? payload.OldValues
+            : entityEvent.baseEntity.GetAll();
+        const key = new CompositeKey();
+        key.LoadFromEntityInfoAndRecord(entityInfo, record);
+        if (key.KeyValuePairs.length === 0 || key.KeyValuePairs.some(kv => kv.Value == null)) {
+            return null;
+        }
+        return { EntityInfo: entityInfo, Type: entityEvent.type, Key: key, Record: record };
+    }
+    /** Applies a closed batch; see {@link EndEntityEventBatch}. */
+    async applyEntityEventBatch(batch) {
+        if (!batch.CanApplyRows) {
+            await this.invalidateBatchEntities(batch);
+            return;
+        }
+        const byEntity = new Map();
+        for (const change of batch.Changes) {
+            const list = byEntity.get(change.EntityInfo.Name) ?? [];
+            list.push(change);
+            byEntity.set(change.EntityInfo.Name, list);
+        }
+        for (const [entityName, changes] of byEntity) {
+            await this.applyEntityChanges(entityName, changes);
+        }
+    }
+    /** Invalidates every entity a batch touched — for a batch that failed or was abandoned. */
+    async invalidateBatchEntities(batch) {
+        for (const entityName of batch.TouchedEntities.keys()) {
+            await this.InvalidateEntityCaches(entityName);
+        }
+    }
+    /** Applies one entity's buffered changes to every slot indexed for it, each slot once. */
+    async applyEntityChanges(entityName, changes) {
+        const fingerprints = await this.resolveFingerprintsForEntity(entityName);
+        if (!fingerprints || fingerprints.size === 0) {
+            return;
+        }
+        const snapshot = [...fingerprints];
+        const nowISO = new Date().toISOString();
+        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);
+                }
+                catch (err) {
+                    LogError(`LocalCacheManager: failed to apply batched changes to "${fingerprint}": ${err.message}`);
+                }
+            }));
+        }
+    }
+    /**
+     * One slot, several changes: the same decisions {@link processEntityEventForFingerprint} makes
+     * per event, made once for the whole list.
+     */
+    async applyEntityChangesToSlot(fingerprint, changes, nowISO) {
+        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.
+        if (this.isSubsetFingerprint(fingerprint) || this.hasAggregates(fingerprint.split('|'))
+            || (hasSave && this.isFilteredFingerprint(fingerprint))) {
+            await this.InvalidateRunViewResult(fingerprint);
+            return;
+        }
+        const rowChanges = changes.map(c => ({ Key: c.Key, Row: c.Type === 'save' ? c.Record : null }));
+        const maintained = await this.ApplyRowChanges(fingerprint, rowChanges, nowISO);
+        await this.invalidateIfNotMaintained(fingerprint, maintained);
+    }
     /**
      * Handles remote-invalidate events that include recordData (the saved entity as JSON).
      * Updates all cached RunView results for the entity without a server round-trip.
@@ -928,13 +1563,15 @@ export class LocalCacheManager extends BaseSingleton {
         }
         else if (eventType === 'delete') {
             LogStatusVerbose(`LocalCacheManager: Removing entity ${keyStr} from cache "${fingerprint.substring(0, 60)}"`);
-            await this.RemoveSingleEntity(fingerprint, key, nowISO);
+            const maintained = await this.RemoveSingleEntity(fingerprint, key, nowISO);
+            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)}"`);
             const entityData = baseEntity.GetAll();
-            await this.UpsertSingleEntity(fingerprint, entityData, key, nowISO);
+            const maintained = await this.UpsertSingleEntity(fingerprint, entityData, key, nowISO);
+            await this.invalidateIfNotMaintained(fingerprint, maintained);
         }
         else {
             // Filtered cache: conservatively invalidate (can't verify filter match)
@@ -942,6 +1579,26 @@ export class LocalCacheManager extends BaseSingleton {
             await this.InvalidateRunViewResult(fingerprint);
         }
     }
+    /**
+     * 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.
+     *
+     * Rewriting the slot is how peer servers hear about the change: their engines hold the rows in
+     * memory and never read the slot again, so a slot that expired while they were running leaves
+     * nothing to rewrite and the change would never reach them. Invalidating instead publishes a
+     * `removed` event on a shared provider, which makes every peer engine tracking the slot reload
+     * it from the database. It also drops the dead fingerprint from this process's index.
+     *
+     * @param fingerprint - The slot the event was applied to
+     * @param maintained - What the in-place upsert/remove reported
+     */
+    async invalidateIfNotMaintained(fingerprint, maintained) {
+        if (maintained) {
+            return;
+        }
+        LogStatusVerbose(`LocalCacheManager: slot "${fingerprint.substring(0, 60)}" could not be maintained in place — invalidating so peers reload`);
+        await this.InvalidateRunViewResult(fingerprint);
+    }
     /**
      * Registers a callback that fires when a specific cache fingerprint is updated
      * by another server instance. Returns an unsubscribe function to remove the callback.
@@ -988,9 +1645,8 @@ export class LocalCacheManager extends BaseSingleton {
      * fingerprint. Called by infrastructure code (e.g., {@link RedisLocalStorageProvider})
      * when another server modifies a cached entry.
      *
-     * For `category_cleared` events, dispatches to ALL registered callbacks whose
-     * fingerprints belong to the cleared category (matched by the event's CacheKey
-     * which contains the category name).
+     * For `category_cleared` events on the RunView category, dispatches to ALL registered
+     * callbacks (they all watch RunView slots); a clear of any other category reaches none.
      *
      * Errors in individual callbacks are caught and logged via {@link LogError}
      * to prevent one bad callback from blocking others.
@@ -1001,9 +1657,13 @@ export class LocalCacheManager extends BaseSingleton {
         const sourceShort = event.SourceServerId ? event.SourceServerId.substring(0, 8) : 'unknown';
         LogStatusVerbose(`LocalCacheManager: DispatchCacheChange received — action="${event.Action}", key="${event.CacheKey}", source="${sourceShort}"`);
         if (event.Action === 'category_cleared') {
-            // For category-level clearing, notify ALL registered callbacks
-            // since we can't know which fingerprints belong to which category
-            // without parsing them. This is a rare operation so the overhead is acceptable.
+            // Every registered callback watches a RunView slot (engine configs and RunView
+            // OnDataChanged both key on RunView fingerprints), so only clearing that category
+            // affects them. Notifying them for a Metadata or Dataset clear as well would make a
+            // tool that clears several categories reload every engine once per category.
+            if (event.Category !== CacheCategory.RunViewCache) {
+                return;
+            }
             for (const [, callbacks] of this._changeCallbacks) {
                 for (const cb of callbacks) {
                     try {
@@ -1053,9 +1713,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
@@ -1455,6 +2116,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);
@@ -1463,12 +2132,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
@@ -1557,6 +2241,12 @@ export class LocalCacheManager extends BaseSingleton {
             LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for keyset (AfterKey) query on "${params.EntityName}"`, verboseOnly: true });
             return;
         }
+        // Rows read while a unit of work has unapplied changes for this entity may include its
+        // uncommitted writes (or miss them); either way they must not become the shared slot.
+        if (this.isPendingInBatch(fingerprint)) {
+            LogStatusEx({ message: `[CACHE-WRITE-GATE] Skipping cache write for "${params.EntityName}" — an open batch has changes for it`, verboseOnly: true });
+            return;
+        }
         // Short-circuit: if the entity has AllowCaching = false, do not write to the cache.
         // The invalidation path (HandleBaseEntityEvent line 552) already short-circuits for
         // these entities, so any entry we write here would never be invalidated and would
@@ -1618,26 +2308,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)) {
-            LogStatusEx({ message: `[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)` });
+            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`
@@ -1655,7 +2352,8 @@ export class LocalCacheManager extends BaseSingleton {
         await this.evictIfNeeded(sizeBytes);
         try {
             // Native object storage — IDB structured-clones, localStorage / Redis serialize internally.
-            await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache);
+            const expiresAt = ttlMs ? Date.now() + ttlMs : undefined;
+            await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache, this.runViewWriteOptions(fingerprint, expiresAt));
             this.registerEntry({
                 key: fingerprint,
                 type: 'runview',
@@ -1675,7 +2373,7 @@ export class LocalCacheManager extends BaseSingleton {
                 sizeBytes,
                 maxUpdatedAt,
                 rowCount: results.length, // Registry still tracks this for display/stats, derived from actual results
-                expiresAt: ttlMs ? Date.now() + ttlMs : undefined // time-based expiry (external entities); undefined => event-invalidated (MJ-DB entities)
+                expiresAt // time-based expiry (external entities); undefined => event-invalidated (MJ-DB entities)
             });
             // Maintain entity→fingerprint reverse index for universal cache invalidation
             this.addToEntityIndex(fingerprint);
@@ -1694,12 +2392,20 @@ export class LocalCacheManager extends BaseSingleton {
      * @returns The cached results, maxUpdatedAt, rowCount (derived), and aggregateResults, or null if not found
      */
     async GetRunViewResult(fingerprint) {
+        if (this.isPendingInBatch(fingerprint)) {
+            this._stats.misses++;
+            return null;
+        }
+        return this.readRunViewSlot(fingerprint, 'serve');
+    }
+    /** {@link GetRunViewResult} without the open-batch check; slot maintenance reads through this. */
+    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}`);
@@ -1739,7 +2445,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.materializeCachedRunViewResult(fp, parsed));
+                out.set(fp, this.isPendingInBatch(fp) ? null : this.materializeCachedRunViewResult(fp, parsed, 'serve'));
             }
             return out;
         }
@@ -1759,10 +2465,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;
@@ -1776,12 +2483,14 @@ 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;
         }
         this.recordAccess(fingerprint);
+        this.indexSlotThisProcessDidNotWrite(fingerprint);
         this._stats.hits++;
         const results = parsed.results || [];
         const result = {
@@ -1791,6 +2500,7 @@ 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,
         };
@@ -1799,6 +2509,34 @@ export class LocalCacheManager extends BaseSingleton {
         }
         return result;
     }
+    /**
+     * Records a slot this process READ, so a later save can still find it once it has expired.
+     *
+     * An engine loads its rows once and never reads its slot again — that is the design, not a
+     * defect: the slot is a boot shortcut and a propagation channel, and correctness comes from
+     * events. Giving slots a finite expiry opened a window those events could not cross. When a
+     * slot expires under running replicas, a save finds nothing to rewrite and publishes nothing,
+     * so every peer engine keeps serving what it loaded.
+     *
+     * The fix — invalidate a slot that cannot be maintained, which publishes `removed` — only
+     * fires if the saving process still holds the fingerprint, and only the process that WROTE the
+     * slot did. A server that booted warm read it instead, and a read indexed nothing; behind a
+     * load balancer, which server takes the save is arbitrary. A warm read is the only trace such a
+     * process has of that slot, so it is indexed too.
+     *
+     * Gated on the provider exposing a shared per-entity index, which is exactly the case
+     * {@link resolveFingerprintsForEntity} answers from that index — with no category-scan
+     * fallback. On a process-local store there is nothing to gain (no peers to notify, and every
+     * slot in it was written by this process, so it is already indexed) and something to lose: a
+     * non-empty index SUPPRESSES that fallback scan, which is what finds persisted slots the index
+     * does not know about.
+     * @internal
+     */
+    indexSlotThisProcessDidNotWrite(fingerprint) {
+        if (this._storageProvider?.GetIndexGroupKeys) {
+            this.addToEntityIndex(fingerprint);
+        }
+    }
     /**
      * Invalidates a cached RunView result.
      *
@@ -1948,16 +2686,33 @@ export class LocalCacheManager extends BaseSingleton {
         }
     }
     /**
-     * Upserts a single entity in a cached RunView result.
-     * Used by BaseEngine for immediate cache sync when an entity is saved.
-     * If the entity exists (by primary key), it is replaced; otherwise it is added.
-     *
-     * Serializes async operations on the same cache fingerprint to prevent
-     * lost-update races. When multiple entity events fire simultaneously
-     * (e.g., 3 deletes from a TransactionGroup), each read-modify-write cycle
-     * must complete before the next one starts for the same fingerprint.
-     * Different fingerprints run concurrently with no contention.
+     * Runs an in-place slot rewrite under {@link withFingerprintLock}. When the lock itself fails
+     * (a shared lock another server held too long), reports the rewrite as not done rather than
+     * throwing, so the caller's fallback — invalidate the slot, making every server reload —
+     * applies.
      */
+    async maintainSlotLocked(fingerprint, fn) {
+        try {
+            return await this.withFingerprintLock(fingerprint, fn);
+        }
+        catch (e) {
+            // Distinguish "another process holds this slot" (expected contention — the caller
+            // invalidates instead of writing) from a fault inside the work itself, which is a bug
+            // and must be reported as one rather than filed under lock contention. The
+            // storage provider owns those error types, and it depends on this package, so they are
+            // recognised by name rather than imported.
+            const name = e instanceof Error ? e.name : '';
+            const isLockProblem = name === 'KeyLockTimeoutError' || name === 'KeyLockLostError';
+            const detail = e instanceof Error ? e.message : String(e);
+            if (isLockProblem) {
+                LogWarning(`LocalCacheManager: could not hold the lock on "${fingerprint.substring(0, 60)}" for an in-place update (${detail}) — invalidating instead`, 'Cache');
+            }
+            else {
+                LogError(`LocalCacheManager: the in-place update of "${fingerprint.substring(0, 60)}" failed (${detail}) — invalidating instead`);
+            }
+            return false;
+        }
+    }
     async withFingerprintLock(fingerprint, fn) {
         const existing = this._fingerprintLocks.get(fingerprint) ?? Promise.resolve();
         let releaseLock;
@@ -1965,6 +2720,13 @@ export class LocalCacheManager extends BaseSingleton {
         this._fingerprintLocks.set(fingerprint, lockPromise);
         try {
             await existing; // Wait for any previous operation on this fingerprint
+            // Another server may be rewriting the same shared entry right now; its write and ours
+            // would each start from the same old array, and the later SET would drop the other's
+            // row. A shared provider serializes the whole read-modify-write across processes.
+            const provider = this._storageProvider;
+            if (provider?.WithKeyLock) {
+                return await provider.WithKeyLock(fingerprint, CacheCategory.RunViewCache, fn);
+            }
             return await fn();
         }
         finally {
@@ -1976,46 +2738,24 @@ export class LocalCacheManager extends BaseSingleton {
         }
     }
     /**
+     * Upserts a single entity in a cached RunView result.
+     * Used by BaseEngine for immediate cache sync when an entity is saved.
+     * If the entity exists (by primary key), it is replaced; otherwise it is added.
+     *
+     * Serializes async operations on the same cache fingerprint to prevent
+     * lost-update races. When multiple entity events fire simultaneously
+     * (e.g., 3 deletes from a TransactionGroup), each read-modify-write cycle
+     * must complete before the next one starts for the same fingerprint.
+     * Different fingerprints run concurrently with no contention.
+     *
      * @param fingerprint - The cache fingerprint to update
      * @param entityData - The entity data as a plain object (use entity.GetAll())
-     * @param primaryKeyFieldName - Name of the primary key field
+     * @param key - The record's primary key
      * @param newMaxUpdatedAt - New maxUpdatedAt timestamp (from entity's __mj_UpdatedAt)
      * @returns true if cache was updated, false if cache not found or update failed
      */
     async UpsertSingleEntity(fingerprint, entityData, key, newMaxUpdatedAt) {
-        if (!this._storageProvider || !this._config.enabled)
-            return false;
-        return this.withFingerprintLock(fingerprint, async () => {
-            try {
-                const cached = await this.GetRunViewResult(fingerprint);
-                if (!cached) {
-                    LogStatusVerbose(`LocalCacheManager.UpsertSingleEntity: No cached data found for fingerprint "${fingerprint.substring(0, 60)}" — skipping (cache will be populated on next RunView)`);
-                    return false;
-                }
-                LogStatusVerbose(`LocalCacheManager.UpsertSingleEntity: Found cached data with ${cached.results.length} rows, updating...`);
-                const pkFieldNames = key.KeyValuePairs.map(kv => kv.FieldName);
-                const keyStr = this.cheapKeyFromCompositeKey(key);
-                // Build a map of existing records by composite key string. Uses a cheap
-                // delimiter-joined PK string (no per-row CompositeKey/KeyValuePair allocation);
-                // matching is consistent because keyStr above uses the same format.
-                const resultMap = new Map();
-                for (const row of cached.results) {
-                    const rowObj = row;
-                    if (pkFieldNames.some(fn => rowObj[fn] == null))
-                        continue; // Skip rows with missing PK fields
-                    resultMap.set(this.cheapRowKey(rowObj, pkFieldNames), row);
-                }
-                // Upsert the entity (add or replace)
-                resultMap.set(keyStr, entityData);
-                const updatedResults = Array.from(resultMap.values());
-                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash,
-                    providerInternalScaffolding: cached.providerInternalScaffolding });
-            }
-            catch (e) {
-                LogError(`LocalCacheManager.UpsertSingleEntity failed: ${e}`);
-                return false;
-            }
-        });
+        return this.ApplyRowChanges(fingerprint, [{ Key: key, Row: entityData }], newMaxUpdatedAt);
     }
     /**
      * Removes a single entity from a cached RunView result.
@@ -2027,39 +2767,70 @@ export class LocalCacheManager extends BaseSingleton {
      * @returns true if cache was updated, false if cache not found or update failed
      */
     async RemoveSingleEntity(fingerprint, key, newMaxUpdatedAt) {
-        if (!this._storageProvider || !this._config.enabled)
+        return this.ApplyRowChanges(fingerprint, [{ Key: key, Row: null }], newMaxUpdatedAt);
+    }
+    /**
+     * Applies several row changes to one cached RunView result in a single read-modify-write:
+     * each change with a `Row` adds or replaces that row, each with `Row: null` removes it, in
+     * order. The slot is written once, and not at all when only removals of absent rows were asked.
+     * All keys must name the same primary-key fields.
+     *
+     * @returns true if the slot now reflects the changes, false if it was not cached or the update failed
+     */
+    async ApplyRowChanges(fingerprint, changes, newMaxUpdatedAt) {
+        if (!this._storageProvider || !this._config.enabled || changes.length === 0)
             return false;
-        return this.withFingerprintLock(fingerprint, async () => {
+        return this.maintainSlotLocked(fingerprint, async () => {
             try {
-                const cached = await this.GetRunViewResult(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;
                 }
-                const pkFieldNames = key.KeyValuePairs.map(kv => kv.FieldName);
-                const keyStr = this.cheapKeyFromCompositeKey(key);
-                // Build a map of existing records by composite key string (cheap PK keying;
-                // see UpsertSingleEntity for the rationale — no per-row CompositeKey allocation).
-                const resultMap = new Map();
-                for (const row of cached.results) {
-                    const rowObj = row;
-                    if (pkFieldNames.some(fn => rowObj[fn] == null))
-                        continue; // Skip rows with missing PK fields
-                    resultMap.set(this.cheapRowKey(rowObj, pkFieldNames), row);
+                const pkFieldNames = changes[0].Key.KeyValuePairs.map(kv => kv.FieldName);
+                const resultMap = this.indexRowsByKey(cached.results, pkFieldNames);
+                if (!this.applyChangesToRowMap(resultMap, changes)) {
+                    return true; // only removals of rows the slot does not hold
                 }
-                if (!resultMap.has(keyStr)) {
-                    return true; // Not in cache, no-op
-                }
-                resultMap.delete(keyStr);
-                const updatedResults = Array.from(resultMap.values());
-                return await this.storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, { totalRowCount: cached.totalRowCount, rowCount: cached.results.length, schemaHash: cached.schemaHash,
-                    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 });
             }
             catch (e) {
-                LogError(`LocalCacheManager.RemoveSingleEntity failed: ${e}`);
+                LogError(`LocalCacheManager.ApplyRowChanges failed: ${e}`);
                 return false;
             }
         });
     }
+    /**
+     * Rows keyed by a cheap delimiter-joined PK string (no per-row CompositeKey/KeyValuePair
+     * allocation); matching is consistent because {@link cheapKeyFromCompositeKey} uses the same
+     * format. Rows missing a PK value are dropped.
+     */
+    indexRowsByKey(rows, pkFieldNames) {
+        const resultMap = new Map();
+        for (const row of rows) {
+            const rowObj = row;
+            if (pkFieldNames.some(fn => rowObj[fn] == null))
+                continue;
+            resultMap.set(this.cheapRowKey(rowObj, pkFieldNames), row);
+        }
+        return resultMap;
+    }
+    /** Applies `changes` to `rows` in order. @returns True when anything changed. */
+    applyChangesToRowMap(rows, changes) {
+        let changed = false;
+        for (const change of changes) {
+            const keyStr = this.cheapKeyFromCompositeKey(change.Key);
+            if (change.Row) {
+                rows.set(keyStr, change.Row);
+                changed = true;
+            }
+            else if (rows.delete(keyStr)) {
+                changed = true;
+            }
+        }
+        return changed;
+    }
     /**
      * Stores updated results array back to the cache and updates the registry.
      * Shared by UpsertSingleEntity and RemoveSingleEntity to avoid duplication.
@@ -2075,9 +2846,14 @@ export class LocalCacheManager extends BaseSingleton {
      * correct total.
      */
     async storeCachedResults(fingerprint, updatedResults, newMaxUpdatedAt, prior) {
+        // 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 data = {
             results: updatedResults,
-            maxUpdatedAt: newMaxUpdatedAt
+            maxUpdatedAt
         };
         // Carry the schemaHash FORWARD — never recompute it here (B38).
         //
@@ -2093,6 +2869,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).
@@ -2116,10 +2895,10 @@ export class LocalCacheManager extends BaseSingleton {
         if (!prior?.providerInternalScaffolding) {
             this.freezeRowDataIfProviderSharesReferences(data);
         }
-        await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache);
         const existingEntry = this._registry.get(fingerprint);
+        await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunViewCache, this.runViewWriteOptions(fingerprint, existingEntry?.expiresAt));
         if (existingEntry) {
-            existingEntry.maxUpdatedAt = newMaxUpdatedAt;
+            existingEntry.maxUpdatedAt = maxUpdatedAt;
             existingEntry.rowCount = updatedResults.length;
             existingEntry.sizeBytes = sizeBytes;
             existingEntry.lastAccessedAt = Date.now();
@@ -2198,8 +2977,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;
@@ -2209,17 +2994,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)) {
-            LogStatusEx({ message: `[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)` });
+            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.
@@ -2227,10 +3022,17 @@ export class LocalCacheManager extends BaseSingleton {
         // Check if we need to evict entries. Evicts OTHER entries only — cannot cancel this write.
         await this.evictIfNeeded(sizeBytes);
         const now = Date.now();
-        const expiresAt = ttlMs ? now + ttlMs : undefined;
+        // Keep the expiry a rewrite found, exactly as the RunView path does: recomputing it from
+        // `now` on every write pushes a bounded entry's expiry forward for as long as anything keeps
+        // rewriting it, so it never expires at all.
+        const existingExpiry = this._registry.get(fingerprint)?.expiresAt;
+        const expiresAt = existingExpiry ?? (ttlMs ? now + ttlMs : undefined);
         try {
-            // Native object storage — no JSON.stringify on the hot path.
-            await this._storageProvider.SetItem(fingerprint, data, CacheCategory.RunQueryCache);
+            // The expiry must reach the STORE, not just this process's registry: another server
+            // 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, LocalCacheManager.runQueryWriteOptions(expiresAt, now, definition?.QueryID ?? queryId));
             this.registerEntry({
                 key: fingerprint,
                 type: 'runquery',
@@ -2249,13 +3051,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
@@ -2270,6 +3092,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
@@ -2283,7 +3113,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
                 };
             }
         }
@@ -2293,6 +3126,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.
      *
@@ -2313,7 +3162,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)
@@ -2336,12 +3190,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);
@@ -2349,7 +3257,8 @@ export class LocalCacheManager extends BaseSingleton {
             return null;
         return {
             maxUpdatedAt: cached.maxUpdatedAt,
-            rowCount: cached.rowCount
+            rowCount: cached.rowCount,
+            definitionHash: cached.definitionHash
         };
     }
     // ========================================================================
@@ -2379,17 +3288,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
         };
@@ -2515,11 +3431,21 @@ export class LocalCacheManager extends BaseSingleton {
             // Don't persist on every access - too expensive
         }
     }
+    /**
+     * True when the registry must stay in this process: the storage is shared with other
+     * processes, so a persisted registry would be one key every server overwrites with its own
+     * view (and publishes to every peer on each write), and a booting server would adopt another
+     * server's accounting. Entries written by other processes are found through the provider's
+     * per-entity index instead ({@link resolveFingerprintsForEntity}).
+     */
+    registryIsProcessLocalOnly() {
+        return this._storageProvider?.SharedAcrossProcesses === true;
+    }
     /**
      * Loads the registry from storage.
      */
     async loadRegistry() {
-        if (!this._storageProvider)
+        if (!this._storageProvider || this.registryIsProcessLocalOnly())
             return;
         try {
             // Native object read — registry is a plain CacheEntryInfo[] array.
@@ -2554,7 +3480,7 @@ export class LocalCacheManager extends BaseSingleton {
      * Persists the registry to storage.
      */
     async persistRegistry() {
-        if (!this._storageProvider)
+        if (!this._storageProvider || this.registryIsProcessLocalOnly())
             return;
         try {
             // Native object storage — store the entries array directly.
@@ -2599,7 +3525,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;
@@ -2621,32 +3547,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);
     }
     /**
@@ -2788,8 +3771,26 @@ export class LocalCacheManager extends BaseSingleton {
         if (!this._storageProvider || !this._config.enabled)
             return;
         const now = Date.now();
-        const ttlMs = this._config.defaultTTLMs;
+        // On a shared store this process must not age out entries by its OWN clock: every server
+        // would delete the same keys on its own schedule and publish a `removed` for each, and the
+        // peers would reload every affected engine — a fleet-wide deletion and reload storm for
+        // entries the store already expires itself (the Redis provider sets a per-key TTL). The
+        // local TTL stays in force for process-private stores, where nothing else can expire them.
+        const sharedStore = this._storageProvider.SharedAcrossProcesses === true;
+        const ttlMs = sharedStore ? 0 : this._config.defaultTTLMs;
+        if (sharedStore && this._config.defaultTTLMs > 0 && !this._sharedTTLWarned) {
+            this._sharedTTLWarned = true;
+            LogWarning(`LocalCacheManager: defaultTTLSeconds is set but the cache store is shared across processes — expiry is left to the store itself (set the store's own TTL, e.g. REDIS_TTL_SECONDS / cacheSettings.sharedCacheTTLSeconds)`, 'Cache');
+        }
         const toDelete = [];
+        // Entries to drop from this process's bookkeeping WITHOUT touching the store. An entry that
+        // carries its own `expiresAt` always handed the store the matching TTL when it was written,
+        // so a shared store expires the key itself. Deleting it here as well means every server
+        // removes the same key on its own clock and publishes a `removed` for it, and every peer
+        // reloads the affected engine — the storm the TTL branch above already avoids, in miniature.
+        // Forgetting it locally still matters: otherwise this registry records slots the store no
+        // longer has.
+        const toForget = [];
         for (const [key, entry] of this._registry) {
             // TTL expiry check
             if (ttlMs > 0 && entry.cachedAt + ttlMs < now) {
@@ -2798,29 +3799,38 @@ export class LocalCacheManager extends BaseSingleton {
             }
             // expiresAt check (if set individually)
             if (entry.expiresAt && entry.expiresAt < now) {
-                toDelete.push(key);
+                (sharedStore ? toForget : toDelete).push(key);
             }
         }
-        if (toDelete.length > 0) {
+        if (toDelete.length > 0 || toForget.length > 0) {
             if (this._config.verboseLogging) {
-                LogStatusEx({ message: `    🗑️ [Cache SWEEP] Evicting ${toDelete.length} TTL-expired entries`, verboseOnly: true });
+                LogStatusEx({ message: `    🗑️ [Cache SWEEP] Evicting ${toDelete.length} TTL-expired entries` +
+                        (toForget.length > 0 ? `, forgetting ${toForget.length} the shared store expires itself` : ''), verboseOnly: true });
             }
             for (const key of toDelete) {
                 try {
                     const entry = this._registry.get(key);
                     const category = this.getCategoryForType(entry?.type);
                     await this._storageProvider.Remove(key, category);
-                    if (entry?.fingerprint) {
-                        this.removeFromEntityIndex(entry.fingerprint);
-                    }
-                    this._registry.delete(key);
+                    this.forgetRegistryEntry(key);
                 }
                 catch {
                     // Continue
                 }
             }
+            for (const key of toForget) {
+                this.forgetRegistryEntry(key);
+            }
             await this.persistRegistry();
         }
     }
+    /** Drops one entry from the registry and the fingerprint index, leaving the store alone. @internal */
+    forgetRegistryEntry(key) {
+        const entry = this._registry.get(key);
+        if (entry?.fingerprint) {
+            this.removeFromEntityIndex(entry.fingerprint);
+        }
+        this._registry.delete(key);
+    }
 }
 //# sourceMappingURL=localCacheManager.js.map