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

package/dist/generic/localCacheManager.d.ts

@@ -3,6 +3,14 @@ import { AggregateResult, DatasetItemFilterType, DatasetResultType, IMetadataPro
 import { AggregateExpression, RunViewParams } from "../views/runView.js";
 import { BaseEntityEvent } from "./baseEntity.js";
 import { CompositeKey } from "./compositeKey.js";
+/**
+ * One change for {@link LocalCacheManager.ApplyRowChanges}: `Row` adds or replaces the row with
+ * `Key`; `Row: null` removes it.
+ */
+export interface CachedRowChange {
+    Key: CompositeKey;
+    Row: Record<string, unknown> | null;
+}
 /**
  * The type of cache entry: dataset, runview, or runquery
  */
@@ -90,6 +98,14 @@ export interface CachedRunViewData {
      * Backward-compatible: entries without this field are served normally (no regression).
      */
     schemaHash?: string;
+    /**
+     * The newest `__mj_UpdatedAt` (ISO string) across the entity's metadata row and its field rows,
+     * written alongside {@link schemaHash}. When two processes sharing a cache disagree on the hash,
+     * this says which of them holds the newer metadata, so the older one stops treating the newer
+     * one's slots as stale. Absent on entries from writers that predate it or whose metadata
+     * carries no timestamps.
+     */
+    schemaStamp?: string;
     /**
      * Set when the slot was written with {@link CacheWriteOptions.ProviderInternalScaffolding}.
      * Persisted so that in-place slot maintenance (`storeCachedResults`, driven by BaseEntity
@@ -124,12 +140,50 @@ export interface CachedRunViewResult {
      * permanently disabling post-migration drift detection for that slot.
      */
     schemaHash?: string;
+    /** Surfaced for the same carry-forward reason as {@link schemaHash}. See {@link CachedRunViewData.schemaStamp}. */
+    schemaStamp?: string;
     /**
      * Surfaced from the stored payload so in-place maintenance can carry the freeze exemption
      * forward. See {@link CachedRunViewData.providerInternalScaffolding}.
      */
     providerInternalScaffolding?: boolean;
 }
+/** A cached RunQuery result, as {@link LocalCacheManager.GetRunQueryResult} returns it. */
+export interface CachedRunQuerySlot {
+    /**
+     * The cached result rows — shared and deep-frozen under a reference-sharing storage
+     * provider, exactly like {@link CachedRunViewData.results}. Do not mutate.
+     */
+    results: unknown[];
+    maxUpdatedAt: string;
+    rowCount: number;
+    queryId?: string;
+    /** User who executed the authorized miss that produced this slot (B43 tie-breaker). */
+    warmedForUserID?: string;
+    /** The definition hash the slot was written under; undefined for slots written without one. */
+    definitionHash?: string;
+}
+/**
+ * What a saved query's cached results were computed from. A RunQuery slot stores the hash and the
+ * stamp it was written under; a read that expects a different hash is a miss. Computed by the
+ * database provider from the query metadata it executes (`QueryEngine`), so every process that
+ * runs the query agrees on it once it holds the same definition.
+ */
+export interface QueryDefinitionSignature {
+    /** The query the signature describes. Its RunQuery slots are indexed and held by this ID. */
+    QueryID: string;
+    /**
+     * Hash of everything that changes the query's results: its SQL for the platform, the columns
+     * that change how that SQL executes, its parameter definitions, and the hashes of the queries
+     * it composes.
+     */
+    Hash: string;
+    /**
+     * The newest `__mj_UpdatedAt` (ISO string) across the rows the hash covers. When two processes
+     * sharing a cache disagree on the hash, this says which of them holds the newer definition.
+     */
+    Stamp?: string;
+}
 /**
  * Per-write options for the cache write methods.
  */
@@ -174,16 +228,29 @@ export interface LocalCacheManagerConfig {
      */
     maxPercentOfCachePerEntity: number;
     /**
-     * Maximum size of any single cache entry, expressed as a percentage of
-     * maxSizeBytes. An entry estimated larger than this cap is not cached at
-     * all — the write is skipped (logged, data still returned to the caller
-     * uncached). Without this cap, storing an oversized entry is strictly worse
-     * than not caching it: evictIfNeeded frees max(incoming, 10% of budget), so
-     * an entry larger than the whole budget evicts EVERY other entry and still
-     * cannot be retained within budget — a full cache wipe on every store.
-     * Applies to RunView and RunQuery entries. Default: 25. Set to 0 to disable.
-     */
-    maxEntryPercentOfCache: number;
+     * Ceiling on the size of any ONE cache entry. An entry estimated larger than the
+     * ceiling is not cached at all — the write is skipped (logged, data still returned
+     * to the caller uncached). Applies to RunView and RunQuery entries.
+     *
+     * The ceiling exists because an entry that cannot be RETAINED within the budget is
+     * worse than no entry: it evicts other entries to make room and is itself evicted on
+     * the next store, so the cache churns and nothing is ever served from it.
+     *
+     * Three modes:
+     * - `'auto'` (default): the ceiling is DERIVED from the budget — everything except a
+     *   reserve of {@link SINGLE_ENTRY_RESERVE_PERCENT} held back for the rest of the
+     *   cache. This is deliberately not a small fixed fraction: a fixed fraction sized for
+     *   a small tenant makes the one entity worth caching (the biggest one) permanently
+     *   uncacheable, which is the failure this mode exists to avoid. The only entries
+     *   `'auto'` declines are entries that genuinely cannot be retained — and the decline
+     *   message says which `maxMemoryMB` would admit them.
+     * - a positive number: an explicit percentage of `maxSizeBytes`, for an operator who
+     *   wants a stricter ceiling than `'auto'`. Clamped to
+     *   {@link HARD_MAX_ENTRY_PERCENT} — no configuration may admit an entry that leaves
+     *   the cache less free space than one eviction cycle needs.
+     * - `0`: no ceiling at all (the original, unguarded behaviour — not recommended).
+     */
+    maxEntryPercentOfCache: number | 'auto';
     /**
      * Interval in milliseconds for the periodic eviction sweep.
      * Catches entries that should have been evicted (TTL expired) but weren't
@@ -329,6 +396,25 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * (e.g., TransactionGroup batch deletes).
      */
     private _fingerprintLocks;
+    /** Logged once when a local TTL is configured against a shared store. See {@link runEvictionSweep}. */
+    private _sharedTTLWarned;
+    /** Open entity-event batches. See {@link BeginEntityEventBatch}. */
+    private _entityEventBatches;
+    /** Save/delete events a batch took when they were raised. See {@link WasTakenByEntityEventBatch}. */
+    private _eventsTakenByBatch;
+    /**
+     * 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}.
+     */
+    private _schemaWriteHolds;
+    /**
+     * 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 readonly SCHEMA_MISMATCH_WRITE_INTERVAL_MS = 60000;
+    /** Schema mismatches already reported, so each entity/hash pair is logged once per process. */
+    private _reportedSchemaMismatches;
     private readonly REGISTRY_KEY;
     /**
      * Reverse index from entity name to the set of RunView cache fingerprints
@@ -341,11 +427,15 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * 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: ILocalStorageProvider, config?: Partial<LocalCacheManagerConfig>): Promise<void>;
@@ -370,6 +460,17 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * Internal initialization logic - only called once by the first caller
      */
     private doInitialize;
+    private _initializedListeners;
+    /**
+     * 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: () => void): void;
+    private runInitializedListener;
+    private notifyInitialized;
     /**
      * Returns whether the cache manager has been initialized
      */
@@ -379,7 +480,8 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      */
     get Config(): LocalCacheManagerConfig;
     /**
-     * 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: Partial<LocalCacheManagerConfig>): void;
     /**
@@ -438,6 +540,23 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * 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 '|'
      */
     protected hasOrderBy(parts: string[]): boolean;
@@ -547,14 +666,82 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      */
     protected isSubsetFingerprint(fingerprint: string): boolean;
     /**
-     * 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
-     */
-    private isSchemaStaleCacheEntry;
+     * @returns The mismatch, or null when the entry may be served
+     */
+    private findSchemaMismatch;
+    /** The mismatch subject for an entity's RunView slots. */
+    private static runViewSubject;
+    /** The mismatch subject for a query's RunQuery slots. */
+    private static runQuerySubject;
+    /**
+     * 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.
+     */
+    private static isNewerSchemaStamp;
+    /**
+     * 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.
+     */
+    private handleSchemaMismatch;
+    /** The log text for a mismatch that left the slot in place and took a write hold. */
+    private static describeHeldMismatch;
+    /** The key of a subject's write hold. RunView and RunQuery holds share one map. */
+    private static holdKey;
+    /** Records or extends the write hold for a mismatch seen on a shared store. */
+    private holdSchemaWrites;
+    /** Logs a mismatch once per subject and hash pair per process. */
+    private reportSchemaMismatch;
+    /**
+     * 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.
+     */
+    private mayWriteUnderSchemaHold;
+    /**
+     * 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: ReadonlyArray<unknown>): string | undefined;
+    /**
+     * 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
+     */
+    private runViewWriteOptions;
+    /** Storage write options for any registry entry; only RunView slots are indexed. */
+    private writeOptionsForEntry;
     /**
      * Adds a fingerprint to the entity→fingerprint reverse index.
      * Called when a RunView result is cached.
@@ -571,11 +758,14 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      */
     GetFingerprintsForEntity(entityName: string): ReadonlySet<string>;
     /**
-     * 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.
      */
     private resolveFingerprintsForEntity;
     /**
@@ -593,6 +783,118 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @param entityEvent - The BaseEntity event payload
      */
     protected HandleBaseEntityEvent(entityEvent: BaseEntityEvent): Promise<void>;
+    /**
+     * 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: object): void;
+    /**
+     * 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.
+     */
+    ReplaceRunViewResultLocked(fingerprint: string, params: RunViewParams, results: unknown[], maxUpdatedAt: string, totalRowCount: number, provider?: IMetadataProvider): Promise<boolean>;
+    /** Milliseconds left on a slot's expiry, or undefined when it has none. @internal */
+    private remainingTTLForSlot;
+    /**
+     * 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.
+     */
+    AbandonEntityEventBatch(owner: object): Promise<void>;
+    /**
+     * 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
+     */
+    EndEntityEventBatch(owner: object, succeeded: boolean): Promise<void>;
+    /**
+     * 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.
+     */
+    TryAcquireSharedLease(name: string, ttlMs: number): Promise<boolean>;
+    /** One lease attempt: claimed, held by another process, or the store could not be asked. */
+    private claimLease;
+    /**
+     * 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.
+     */
+    RenewSharedLease(name: string, ttlMs: number): Promise<boolean>;
+    /** Ends a lease claimed with {@link TryAcquireSharedLease}. Never throws. */
+    ReleaseSharedLease(name: string): Promise<void>;
+    /**
+     * 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.
+     */
+    WaitForSharedLease(name: string, ttlMs: number, maxWaitMs: number, pollMs?: number): Promise<{
+        Acquired: boolean;
+        WaitedMs: number;
+    }>;
+    /** True while a batch is open for `owner`. */
+    IsBatchingEntityEvents(owner: object | null | undefined): boolean;
+    /**
+     * 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: BaseEntityEvent): boolean;
+    /**
+     * 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.
+     */
+    RunInEntityEventBatch<T>(owner: object, work: () => Promise<T>): Promise<T>;
+    /**
+     * 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).
+     */
+    private bufferIfBatching;
+    /**
+     * 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.
+     */
+    private isPendingInBatch;
+    /**
+     * 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.
+     */
+    private captureEntityChange;
+    /** Applies a closed batch; see {@link EndEntityEventBatch}. */
+    private applyEntityEventBatch;
+    /** Invalidates every entity a batch touched — for a batch that failed or was abandoned. */
+    private invalidateBatchEntities;
+    /** Applies one entity's buffered changes to every slot indexed for it, each slot once. */
+    private applyEntityChanges;
+    /**
+     * One slot, several changes: the same decisions {@link processEntityEventForFingerprint} makes
+     * per event, made once for the whole list.
+     */
+    private applyEntityChangesToSlot;
     /**
      * 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.
@@ -637,6 +939,20 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * Decomposed from HandleBaseEntityEvent for clarity and testability.
      */
     private processEntityEventForFingerprint;
+    /**
+     * 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
+     */
+    private invalidateIfNotMaintained;
     /**
      * Map from cache fingerprint (or category for category_cleared events) to
      * registered {@link CacheChangedEvent} callbacks. Callbacks are invoked when
@@ -675,9 +991,8 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * 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.
@@ -827,6 +1142,14 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @returns The schema hash string, or undefined if the entity can't be resolved
      */
     ComputeSchemaHash(provider: IMetadataProvider | undefined, entityName: string): string | undefined;
+    /**
+     * 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.
+     */
+    private computeSchemaSignature;
+    /** Milliseconds since the epoch for a metadata timestamp (a Date or a string), or 0 when unreadable. */
+    private static timestampMs;
     /**
      * Deep-freezes an about-to-be-stored cache payload when — and only when — the active
      * storage provider hands out live object references
@@ -892,6 +1215,8 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @returns The cached results, maxUpdatedAt, rowCount (derived), and aggregateResults, or null if not found
      */
     GetRunViewResult(fingerprint: string): Promise<CachedRunViewResult | null>;
+    /** {@link GetRunViewResult} without the open-batch check; slot maintenance reads through this. */
+    private readRunViewSlot;
     /**
      * Batched retrieval for many cached RunView results in a single underlying
      * IndexedDB transaction (or Redis MGET, or one in-memory pass — depends on
@@ -920,10 +1245,35 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * 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}).
      */
     private materializeCachedRunViewResult;
+    /**
+     * 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
+     */
+    private indexSlotThisProcessDidNotWrite;
     /**
      * Invalidates a cached RunView result.
      *
@@ -959,6 +1309,14 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @returns The merged results after applying the differential update, or null if cache not found
      */
     ApplyDifferentialUpdate(fingerprint: string, params: RunViewParams, updatedRows: unknown[], deletedRecordIDs: string[], primaryKeyFieldNames: string | string[], newMaxUpdatedAt: string, serverRowCount?: number, aggregateResults?: AggregateResult[], provider?: IMetadataProvider): Promise<CachedRunViewResult | null>;
+    /**
+     * 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.
+     */
+    private maintainSlotLocked;
+    private withFingerprintLock;
     /**
      * Upserts a single entity in a cached RunView result.
      * Used by BaseEngine for immediate cache sync when an entity is saved.
@@ -969,12 +1327,10 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * (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.
-     */
-    private withFingerprintLock;
-    /**
+     *
      * @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
      */
@@ -989,6 +1345,23 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @returns true if cache was updated, false if cache not found or update failed
      */
     RemoveSingleEntity(fingerprint: string, key: CompositeKey, newMaxUpdatedAt: string): Promise<boolean>;
+    /**
+     * 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
+     */
+    ApplyRowChanges(fingerprint: string, changes: ReadonlyArray<CachedRowChange>, newMaxUpdatedAt: string): Promise<boolean>;
+    /**
+     * 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.
+     */
+    private indexRowsByKey;
+    /** Applies `changes` to `rows` in order. @returns True when anything changed. */
+    private applyChangesToRowMap;
     /**
      * Stores updated results array back to the cache and updates the registry.
      * Shared by UpsertSingleEntity and RemoveSingleEntity to avoid duplication.
@@ -1034,26 +1407,38 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * @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)
+     * @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`).
      */
-    SetRunQueryResult(fingerprint: string, queryName: string, results: unknown[], maxUpdatedAt: string, rowCount?: number, queryId?: string, ttlMs?: number, warmedForUserID?: string): Promise<void>;
+    SetRunQueryResult(fingerprint: string, queryName: string, results: unknown[], maxUpdatedAt: string, rowCount?: number, queryId?: string, ttlMs?: number, warmedForUserID?: string, definition?: QueryDefinitionSignature): Promise<void>;
+    /**
+     * 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.
+     */
+    private static runQueryWriteOptions;
     /**
      * Retrieves a cached RunQuery result.
      *
      * @param fingerprint - The cache fingerprint
-     * @returns The cached results, maxUpdatedAt, rowCount, and queryId, or null if not found
-     */
-    GetRunQueryResult(fingerprint: string): Promise<{
-        /**
-         * The cached result rows — shared and deep-frozen under a reference-sharing storage
-         * provider, exactly like {@link CachedRunViewData.results}. Do not mutate.
-         */
-        results: unknown[];
-        maxUpdatedAt: string;
-        rowCount: number;
-        queryId?: string;
-        /** User who executed the authorized miss that produced this slot (B43 tie-breaker). */
-        warmedForUserID?: string;
-    } | null>;
+     * @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
+     */
+    GetRunQueryResult(fingerprint: string, expectedDefinition?: QueryDefinitionSignature): Promise<CachedRunQuerySlot | 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.
+     */
+    private static findDefinitionMismatch;
     /**
      * Invalidates a cached RunQuery result.
      *
@@ -1064,19 +1449,39 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * 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.
      */
     InvalidateQueryCaches(queryName: string): Promise<void>;
+    /**
+     * 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
+     */
+    InvalidateRunQueryResultsForQuery(queryId: string): Promise<number>;
+    /** The keys of one query's RunQuery slots: this process's registry, plus the shared index. */
+    private findRunQueryKeysForQuery;
     /**
      * 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
      */
     GetRunQueryCacheStatus(fingerprint: string): Promise<{
         maxUpdatedAt: string;
         rowCount: number;
+        definitionHash?: string;
     } | null>;
     /**
      * Returns all cache entries for dashboard display.
@@ -1133,6 +1538,14 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * Records an access to a cache entry (updates lastAccessedAt and accessCount).
      */
     private recordAccess;
+    /**
+     * 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}).
+     */
+    private registryIsProcessLocalOnly;
     /**
      * Loads the registry from storage.
      */
@@ -1164,16 +1577,50 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      */
     private estimateResultsSize;
     /**
-     * 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.
+     */
+    get MaxEntrySizeBytes(): number;
+    /**
+     * The per-entry ceiling as a percentage of the budget, with `'auto'` resolved and an
+     * explicit configuration clamped. 0 or below means "no ceiling".
+     */
+    private get effectiveMaxEntryPercent();
+    /**
+     * 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.
      */
     private exceedsMaxEntrySize;
+    /**
+     * 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.
+     */
+    private describeOversizedEntry;
     /**
      * 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.
      */
     private evictIfNeeded;
     /**
@@ -1211,5 +1658,7 @@ export declare class LocalCacheManager extends BaseSingleton<LocalCacheManager>
      * or entries for entities that are over their per-entity cap.
      */
     private runEvictionSweep;
+    /** Drops one entry from the registry and the fingerprint index, leaving the store alone. @internal */
+    private forgetRegistryEntry;
 }
 //# sourceMappingURL=localCacheManager.d.ts.map