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

package/dist/generic/providerBase.d.ts

@@ -1,6 +1,6 @@
 import { BaseEntity, BaseEntityEvent } from "./baseEntity.js";
 import { EntityDependency, EntityDocumentTypeInfo, EntityInfo, RecordDependency, RecordMergeRequest, RecordMergeResult } from "./entityInfo.js";
-import { IMetadataProvider, MetadataSweepResult, ProviderConfigDataBase, MetadataInfo, ILocalStorageProvider, IFileSystemProvider, DatasetResultType, DatasetStatusResultType, DatasetItemFilterType, EntityRecordNameInput, EntityRecordNameResult, ProviderType, PotentialDuplicateRequest, PotentialDuplicateResponse, EntityMergeOptions, AllMetadata, IRunViewProvider, RunViewResult, IRunQueryProvider, RunQueryResult, RunViewWithCacheCheckParams, FullTextSearchParams, FullTextSearchResult, SearchEntityParams, EntitySearchResult, IRemoteOperationProvider, RemoteOpInvokeOptions, RemoteOpResult } from "./interfaces.js";
+import { IMetadataProvider, MetadataSweepResult, ProviderConfigDataBase, MetadataInfo, ILocalStorageProvider, IFileSystemProvider, DatasetResultType, DatasetStatusResultType, DatasetItemFilterType, EntityRecordNameInput, EntityRecordNameResult, ProviderType, PotentialDuplicateRequest, PotentialDuplicateResponse, EntityMergeOptions, GetRecordDependenciesOptions, AllMetadata, IRunViewProvider, RunViewResult, IRunQueryProvider, RunQueryResult, RunViewWithCacheCheckParams, FullTextSearchParams, FullTextSearchResult, SearchEntityParams, EntitySearchResult, IRemoteOperationProvider, RemoteOpInvokeOptions, RemoteOpResult } from "./interfaces.js";
 import { ScoredCandidate } from "./scoring/ReciprocalRankFusion.js";
 import { RunQueryParams } from "./runQuery.js";
 import { CachedRunViewResult } from "./localCacheManager.js";
@@ -15,6 +15,7 @@ import { CompositeKey } from "./compositeKey.js";
 import { ExplorerNavigationItem } from "./explorerNavigationItem.js";
 import { RunViewParams } from "../views/runView.js";
 import { DatabasePlatform, PlatformSQL } from "./platformSQL.js";
+import { ContextToken } from "./contextTokens.js";
 /**
  * Creates a new instance of AllMetadata from a simple object.
  * Handles deserialization and proper instantiation of all metadata classes.
@@ -51,6 +52,12 @@ export interface QueryCacheAuthorization {
     categoryPath?: string;
     /** Resolved query name — for log messages when the request was by ID only. */
     queryName?: string;
+    /**
+     * The context tokens the resolved query's template reads, with every query it composes
+     * (`FindQueryContextTokens`). Their values join the fingerprint, so a result that depends on
+     * the user or the date is never served to another user or on another day.
+     */
+    contextTokens?: ContextToken[];
     /**
      * Resolved query ID. With `queryName`, the identity the RunQuery fingerprint is built from, so
      * a request by ID, by name, or by both reaches the same slot.
@@ -62,6 +69,12 @@ export interface QueryCacheAuthorization {
      * provider cannot compute one (a client, whose slots the server validates instead).
      */
     definition?: QueryDefinitionSignature;
+    /**
+     * The user's field-security profile (`FieldSecuritySQLGate.CatalogDenialProfileKey`) when the
+     * run drops denied columns from its rows; it joins the fingerprint, so users with different
+     * denials never share a slot. Undefined when the rows are the same for every authorized user.
+     */
+    fieldSecurityKey?: string;
 }
 export declare const AllMetadataArrays: ({
     key: string;
@@ -123,6 +136,7 @@ export type EntityMetadataRow = BaseMetadataRow & {
     EntityRelationships?: unknown[];
     EntitySettings?: unknown[];
     EntityOrganicKeys?: unknown[];
+    EntityAlternateBaseViews?: unknown[];
 };
 export type EntityFieldMetadataRow = BaseMetadataRow & {
     ID: string;
@@ -401,10 +415,11 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      */
     private _metadataReadsJoinTransaction;
     /**
-     * The MJ_Metadata dataset items (code + entity name) as of the last full load. The remote
+     * The MJ_Metadata dataset items (code + entity name + row count) as of the last load. The remote
      * timestamps ({@link GetLatestMetadataUpdates}) are keyed by entity name while a dataset
      * read is scoped by item code, so this is the bridge that lets a staleness check be turned
-     * into a scoped reload (see {@link PartialRefreshItemCodes}).
+     * into a scoped reload (see {@link PartialRefreshItemCodes}) and lets {@link adoptServerMetadata}
+     * verify that the received dataset items' row counts match `_latestRemoteMetadataTimestamps`.
      */
     private _metadataDatasetItems;
     /**
@@ -812,11 +827,41 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @returns Array of view results (shallow-copied Results per caller)
      */
     RunViews<T = any>(params: RunViewParams[], contextUser?: UserInfo): Promise<RunViewResult<T>[]>;
+    /**
+     * Stashes resolved RunViews results on `_inflightViews` for `DedupLingerMs` and schedules
+     * cleanup via an isolated static `WeakRef` timer helper so the timer closure's V8 lexical
+     * context never retains `this`, `promise`, or `results` on short-lived per-request providers.
+     */
+    private stashInflightLingerResult;
+    private static scheduleInflightLingerExpiry;
     /**
      * The original RunViews execution pipeline (pre-processing, cache,
      * internal execution, post-processing).
      */
     private executeRunViewsPipeline;
+    /**
+     * Puts each refused view's result back at its own index of the caller's batch, with the
+     * admitted views' results filling the remaining indexes in order.
+     */
+    private static interleaveRefusedResults;
+    /**
+     * Keeps the `TotalRowCount` contract on every way out of the pipeline: a caller that passed
+     * `SkipTotalRowCount` gets `undefined`, never a number. Cache hits, the smart-cache check and
+     * the GraphQL wire each rebuild a result and each have a reason to fill in a row count, so the
+     * contract is applied once here rather than at each of those sites.
+     */
+    private static clearSkippedTotalRowCount;
+    /**
+     * Runs a RunViews batch of the views the field-security predicate gate admitted, and applies
+     * the `TotalRowCount` contract to whichever stage produced each result.
+     */
+    private runAdmittedViews;
+    /**
+     * The cache, database and post-processing stages of a RunViews batch, for the views the
+     * field-security predicate gate admitted. `params` and every index map in `preResult`
+     * describe the same admitted views.
+     */
+    private runAdmittedViewStages;
     /**
      * Enqueues a RunViews call for coalescing. Multiple calls arriving within
      * CoalesceWindowMs are merged into a single mega-batch, executed once, and
@@ -890,6 +935,34 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * - entities where server caching is disallowed
      */
     protected runViewCacheEligible(param: RunViewParams): boolean;
+    /**
+     * True when the caller explicitly requested a non-empty `Fields` projection on a plain-object
+     * (`ResultType !== 'entity_object'`) read.
+     */
+    protected hasNarrowFieldsOverride(param: RunViewParams): boolean;
+    /**
+     * True when a cache-miss read should widen `Fields` to the full entity superset AND populate
+     * `LocalCacheManager` with that superset.
+     *
+     * On the server (`TrustLocalCacheCompletely === true`), cache-allowed entities (`AllowCaching === true`)
+     * widen on miss by default so the Fields-agnostic superset slot serves any future `Fields` subset
+     * (`server-cache` S1 -> S2 -> S3), UNLESS the caller explicitly opts out via `CacheLocal: false` or
+     * `BypassCache: true` (in which case narrow SQL `SELECT` pushdown is preserved end-to-end without
+     * polluting the cache). On the client (`TrustLocalCacheCompletely === false`), only `CacheLocal: true`
+     * widens and caches.
+     */
+    protected shouldWidenAndPopulateCache(param: RunViewParams): boolean;
+    /**
+     * True when the request targets an `AlternateBaseView` (explicitly on `param.AlternateBaseView`
+     * or pinned on `param.ViewEntity`) whose `CachePolicy` (or an ancestor's `CachePolicy` in its
+     * `ParentID` chain) is `'Bypass'` (`IsBypassCache === true`), when the requested alternate
+     * base view does not resolve to a usable view on the entity, or when a saved User View is
+     * referenced only by `ViewID`/`ViewName` without a loaded `ViewEntity` (fail-closed: we cannot
+     * synchronously inspect `DisplayState.alternateBaseView` until the view is loaded).
+     */
+    protected isAlternateBaseViewCacheBypassed(param: RunViewParams): boolean;
+    /** True when a run carries view properties (even an empty map): the browser sends it to the server as it is. */
+    private static carriesViewProperties;
     /** True when the entity is a CodeGen materialized-query wrapper (materialized_vw*) whose snapshot is
      * refreshed out-of-band — the same one IsServerCacheAllowedForEntity excludes from the server cache. */
     protected isMaterializedWrapperEntity(param: RunViewParams): boolean;
@@ -1120,6 +1193,13 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * the miss path also checked entity read permissions).
      */
     protected ResolveQueryCacheAuthorization(params: RunQueryParams, user?: UserInfo): QueryCacheAuthorization;
+    /**
+     * The fingerprint segment for what the server sets on a run: `ServerParameters`, and the
+     * `Context.*` values the query reads, worked out for this user, zone and day. Empty when the
+     * run has neither, so the fingerprint is exactly what it was before either existed.
+     * @returns null when the query reads `Context.Now`: such a result is never reused
+     */
+    private queryCacheServerSegment;
     RunQuery(params: RunQueryParams, contextUser?: UserInfo): Promise<RunQueryResult>;
     /**
      * Executes a query from a `QueryExecutionSpec` — the lower-layer interface-based entry point.
@@ -1151,6 +1231,12 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @param callerName
      */
     protected EntityStatusCheck(params: RunViewParams, callerName: string, contextUser?: UserInfo): Promise<void>;
+    /**
+     * Emits a `[Deprecated]` warning when a cache-hit RunView served rows for a deprecated
+     * `AlternateBaseView` (or an alternate view whose ancestor in `ParentID` is deprecated).
+     * Cache misses log deprecation once inside `ResolveAlternateBaseView` during execution.
+     */
+    protected logDeprecatedAlternateBaseViewIfAny(params: RunViewParams, callerName: string): void;
     /**
      * Result from PreRunView hook containing cache status and optional cached result
      */
@@ -1166,6 +1252,11 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
          * to project cache-miss DB results back down to the requested shape.
          */
         callerRequestedFields?: string[] | null;
+        /**
+         * True when PreRunView determined that a cache-miss result holds a full superset
+         * projection eligible to populate the Fields-agnostic cache slot in PostRunView.
+         */
+        populateCache?: boolean;
     };
     /**
      * Result from PreRunViews hook containing cache status for batch operations
@@ -1196,12 +1287,25 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
          * fingerprint string for every batch item.
          */
         fingerprintMap?: Map<number, string>;
+        /**
+         * Param indexes whose cache-miss result holds a full superset projection eligible to
+         * populate the Fields-agnostic cache slot in PostRunViews.
+         */
+        populateCacheSet?: Set<number>;
         /**
          * Pre-resolved local cache entries keyed by client cache fingerprint, populated
          * during prepareSmartCacheCheckParams so executeSmartCacheCheck can reuse the
          * already-parsed results for 'current' items without a second IndexedDB read.
          */
         preResolvedCache?: Map<string, CachedRunViewResult | null>;
+        /**
+         * Views the field-security predicate gate refused, keyed by their index in the caller's
+         * batch, each with its `Success: false` result. Present only when at least one view was
+         * refused. Every other field of this result — the index maps, `cachedResults`,
+         * `uncachedParams`, `smartCacheCheckParams` — then describes the ADMITTED views only,
+         * indexed by their position among them.
+         */
+        refusedResults?: Map<number, RunViewResult>;
     };
     /**
      * Result from PreRunQuery hook containing cache status and optional cached result
@@ -1263,7 +1367,7 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      */
     protected ComputeRunViewRLSWhereClause(params: RunViewParams, contextUser?: UserInfo): string;
     /**
-     * The CLIENT's field-security cache key: a canonical list of the fields this user MAY read.
+     * The field-security cache key for one entity: a canonical list of the fields the user MAY read.
      *
      * Keyed on the ALLOWED set rather than the denied set for two reasons. Once metadata ships
      * to browsers filtered to what a user may see ([#3485](https://github.com/MemberJunction/MJ/issues/3485)),
@@ -1275,36 +1379,90 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * Returns '' when the entity has field security off or the user is denied nothing, so
      * unrestricted users keep byte-identical fingerprints and shared slots.
      *
-     * Only takes effect once the client's metadata refreshes. A client on stale metadata
-     * computes a stale key; the backstop is that the server strips denied columns from every
-     * fresh fetch regardless.
+     * Reads the denied set through {@link ResolveRequestDeniedReadFields}, so the key and the
+     * SELECT list a database provider builds for the same request describe the same columns.
+     *
+     * @param params - The request; also the memo the denied set is shared through
+     * @param contextUser - The request's user; defaults to {@link CurrentUser}
+     */
+    protected ComputeClientFLSAllowedKey(params: RunViewParams, contextUser?: UserInfo): string;
+    /**
+     * The field-security segment for a {@link LocalCacheManager} RunView fingerprint, on both
+     * tiers: the slot a request reads and fills belongs to the user's permission class.
+     *
+     * - **The entity's allowed columns** ({@link ComputeClientFLSAllowedKey}). A database
+     *   provider selects only the columns the reader may see, so a restricted reader's fill is
+     *   narrower than an unrestricted one's, and the two must never share a slot. A browser
+     *   stores rows exactly as the server returned them and never projects on read, so its
+     *   slots need the same identity. It also keeps user searches apart: which rows match a
+     *   search depends on which columns the reader may search.
+     * - **For a saved view, the user's denials on every entity.** A view's stored clause can
+     *   reach other entities (nested view filters), and those clauses are only screened when the
+     *   database runs them, on a miss. Keying the slot on the whole denial profile means a hit
+     *   is only ever served from a fill by a user whose clauses screen identically.
+     *
+     * Empty for a user denied nothing, so unrestricted users keep byte-identical fingerprints
+     * and share slots. Read-time projection ({@link ApplyFieldSecurityProjection}) still runs on
+     * every hit and miss, as a backstop.
+     *
+     * @param params - The request
+     * @param contextUser - The request's user; defaults to {@link CurrentUser}. On a server
+     *   this must be the request's user, never the process user.
+     */
+    protected ComputeRunViewFLSFingerprintKey(params: RunViewParams, contextUser?: UserInfo): string;
+    /**
+     * Every field `user` may not read, across all entities: one `entityID:field,field` entry per
+     * entity on which the user is denied something, sorted. '' for a user denied nothing.
+     *
+     * @param user - The user whose denials to describe
+     */
+    protected ComputeFieldSecurityProfileKey(user: UserInfo): string;
+    /**
+     * The fingerprint of the server-cache slot a RunView reads and fills for `contextUser`:
+     * the request, this provider's connection, the user's row-level-security clause and the
+     * user's field-security key. Every server path that reads or writes a RunView slot builds
+     * its fingerprint here, so none of them can leave a segment out — a path that omitted the
+     * user's segments would read or fill another permission class's slot.
+     *
+     * @param params - The request
+     * @param contextUser - The request's user; defaults to {@link CurrentUser}
      */
-    protected ComputeClientFLSAllowedKey(params: RunViewParams): string;
+    ComputeRunViewCacheFingerprint(params: RunViewParams, contextUser?: UserInfo): string;
     /**
-     * The field-security segment for a {@link LocalCacheManager} RunView fingerprint — the one
-     * place the client/server asymmetry is decided, so the two tiers cannot drift.
+     * The field-security key a browser sends with a cached slot's status, and the one a server
+     * compares it with: a hash of {@link ComputeRunViewFLSFingerprintKey}, or '' for a user
+     * denied nothing.
      *
-     * **SERVER → no segment.** Its slots are full-width and shared by every user; per-request
-     * narrowing happens at read time in {@link ApplyFieldSecurityProjection}, which runs on
-     * every hit and every miss. A segment here would fragment one shared slot into one per
-     * permission class and protect nothing the projection does not already handle.
+     * The currency check otherwise compares only `maxUpdatedAt` and `rowCount`, and neither
+     * changes when a user loses a column. A browser whose metadata has not refreshed yet keeps
+     * its old slot (same fingerprint) and would be told "current" while still showing the
+     * column; with this key the server sees the mismatch and answers "stale" with fresh rows.
      *
-     * **CLIENT → the allowed-list key.** Its slots are stored exactly as the server returned
-     * them (already narrowed on the wire) and are not projected on read, so slot identity has to
-     * carry the field set. Without it, a user whose access is tightened keeps being served their
-     * persisted IndexedDB slot: the currency check compares `maxUpdatedAt` and `rowCount` only,
-     * neither of which notices a column, so the server answers "current" and the browser keeps
-     * showing a column that was just taken away.
+     * @param params - The request
+     * @param contextUser - The request's user; defaults to {@link CurrentUser}
+     */
+    protected ComputeFieldSecurityCacheStatusKey(params: RunViewParams, contextUser?: UserInfo): string;
+    /**
+     * The fields `user` may not read on `entity` for this one request, resolved once and reused by
+     * everything that asks again for the same request (`params` object), user object and entity.
+     *
+     * The cache key and the SELECT list are built at different moments of a request. Read
+     * independently, a metadata refresh landing between the two would key a slot for one
+     * permission class and fill it with another's columns. Sharing one answer per request rules
+     * that out. Empty when field security does not apply.
      *
-     * Empty/undefined for unrestricted users on both tiers, so their fingerprints stay
-     * byte-identical and keep sharing slots.
+     * @param params - The request; the memo is keyed on this object
+     * @param entity - The entity being read
+     * @param user - The request's user
      */
-    protected ComputeRunViewFLSFingerprintKey(params: RunViewParams): string | undefined;
+    protected ResolveRequestDeniedReadFields(params: RunViewParams, entity: EntityInfo, user: UserInfo | undefined): Set<string>;
+    private _requestDeniedReadFields;
     /**
      * The fetch-widening field list for a cache-eligible request: always every entity field.
-     * One slot per (entity, filter, order) serves every caller regardless of the field subset
-     * they asked for, and field security narrows per request at read time via
-     * {@link ApplyFieldSecurityProjection}.
+     * One slot per (entity, filter, order, permission class) serves every caller regardless of
+     * the field subset they asked for. Field security is not applied here: a database provider
+     * leaves the user's denied columns out of the SELECT it builds from this list, and the slot
+     * key carries the user's class ({@link ComputeRunViewFLSFingerprintKey}).
      */
     protected ComputeRunViewFetchFields(entity: EntityInfo, params?: RunViewParams): string[];
     /**
@@ -1338,28 +1496,44 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @returns Pre-processing result with cache status and optional cached result
      */
     /**
-     * Rejects a RunView whose `ExtraFilter`, `OrderBy`, or `Aggregates` expressions reference a
-     * field the user cannot read.
+     * Rejects a RunView whose caller-authored SQL reads a field the user cannot read: `ExtraFilter`,
+     * `OrderBy`, `OverrideExcludeFilter`, every `Aggregates[].expression`, and — when the request
+     * carries a loaded `ViewEntity` — that view's stored `WhereClause` and `OrderByClause`.
      *
      * Output projection alone is security theater. A user denied `Salary` can send
      * `ExtraFilter: "Salary > 200000"` or `OrderBy: "Salary DESC"` and reconstruct the values
      * from which rows come back and in what order — the column never appears in a result, so
      * every output-stripping point reports "secure." Aggregates are the same channel in a purer
      * form: `Aggregates: [{expression: 'MIN(Salary)'}]` under a narrow filter returns a denied
-     * field's exact values directly. Predicate validation is a first-class enforcement point,
-     * not a belt-and-braces afterthought. Together these cover every caller-authored expression
-     * surface (`UserSearchString` is handled by excluding denied fields from the searched set,
-     * not by rejection — see below).
+     * field's exact values directly. `UserSearchString` is handled by excluding denied fields from
+     * the searched set, not by rejection.
      *
-     * Lives at the provider layer rather than in the GraphQL resolver (where the plan first
-     * placed it) because every RunView funnels through here — the batch path, server-internal
-     * agents and actions running under a restricted `contextUser`, and the resolver alike. One
-     * gate, no path left uncovered.
+     * Lives at the provider layer because every RunView funnels through here — the batch path,
+     * server-internal agents and actions running under a restricted `contextUser`, and the
+     * resolver alike. A database provider checks the clauses it actually runs a second time, once
+     * a saved view is resolved, so a request that names only a `ViewID` is covered too.
      *
-     * The error deliberately does not say whether the field is missing or merely forbidden —
-     * see {@link ProviderBase.FieldSecurityDenialMessage}.
+     * The reading of each clause, and the error it raises, is {@link FieldSecuritySQLGate}'s.
      */
     protected AssertPredicatesRespectFieldSecurity(params: RunViewParams, contextUser?: UserInfo): void;
+    /**
+     * Throws a {@link FieldSecurityError} when any of `clauses` — SQL fragments that run against
+     * `entity`'s view — reads a field `user` cannot read, reads whole rows of an entity the user is
+     * denied fields on, or cannot be read well enough to tell. Non-string and blank entries are
+     * skipped. A no-op, with nothing scanned, for a user denied nothing on any entity.
+     *
+     * The shared entry point for every clause slot a provider runs: RunView parameters, a saved
+     * view's stored clauses, dataset item filters, user-search text spliced as SQL.
+     */
+    protected AssertClausesRespectFieldSecurityForEntity(entity: EntityInfo, clauses: Iterable<unknown>, user: UserInfo): void;
+    /**
+     * {@link AssertClausesRespectFieldSecurityForEntity} for ORDER BY fragments, which also refuses
+     * a sort by column position for a user denied a field on `entity`
+     * ({@link FieldSecuritySQLGate.FindSortViolation}).
+     */
+    protected AssertSortRespectsFieldSecurityForEntity(entity: EntityInfo, orderBys: Iterable<unknown>, user: UserInfo): void;
+    /** Throws the field-security error for the first of `fragments` that `find` refuses. */
+    private assertFragmentsAllowed;
     /**
      * The single wording for "you cannot use this field," modeled on SQL Server's posture of
      * never disclosing whether an object is missing or merely inaccessible.
@@ -1376,15 +1550,13 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     /**
      * Strips fields the user cannot read from plain-object result rows.
      *
-     * This is the primary read-time control for list results, and it runs on BOTH cache hits
-     * and cache misses — the property the rest of the cache design is arranged around. Because
-     * it reads live metadata, a permission change takes effect on the next metadata refresh
-     * with no result-cache invalidation: the cached full-width superset stays valid and only
-     * the projection changes.
-     *
-     * It composes with two per-request, never-cached narrowings that avoid pulling columns a
-     * restricted service account has no business holding: the `simple`-path SELECT-list
-     * intersection, and `Load()`'s allowed-column SELECT.
+     * The backstop behind slot segmentation: cache slots are keyed by the reader's permission
+     * class ({@link ComputeRunViewFLSFingerprintKey}) and filled with only that class's columns,
+     * and this still runs on BOTH cache hits and cache misses, checking every row. A slot can hold
+     * more than its class may read (an `entity_object` fill selects every column, and a slot keyed
+     * just before a permission change keeps its old width), and this is what keeps such a slot
+     * from reaching a reader. It reads live metadata, so a tightened permission applies here from
+     * the next metadata refresh.
      *
      * NEVER applied to `entity_object` results. Those become `BaseEntity` instances whose
      * fields round-trip through `GenerateSaveSQL`, which iterates ALL `IsSPParameter` fields
@@ -1396,13 +1568,30 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     protected ApplyFieldSecurityProjection<T>(rows: T[], params: RunViewParams, contextUser?: UserInfo): T[];
     /**
      * Row-loop half of {@link ApplyFieldSecurityProjection}, split out so the policy above reads
-     * as policy. Mirrors {@link ProjectRowsToFields}' matching semantics (trim + lowercase) and
-     * its no-op probe: when the first row carries none of the denied keys, the whole result is
-     * returned untouched rather than rebuilt row by row.
+     * as policy. Mirrors {@link ProjectRowsToFields}' matching semantics (trim + lowercase).
+     *
+     * Every row is checked on its own: rows in one result need not share a shape (a slot can mix
+     * rows written by different paths), so no row stands in for the others. A row carrying no
+     * denied key is kept as is, and when none do the input array itself is returned.
+     *
+     * The per-key work (trim, lowercase, set lookup) is done once per key SHAPE rather than once
+     * per row: rows with the same keys in the same order share one {@link RowProjectionPlan}. A
+     * result is almost always a single shape, so a restricted user's 10k-row result pays for one
+     * row's worth of key matching plus a copy per row.
      *
      * @param deniedLowercase field names to omit, already lowercased
      */
     private static omitFieldsFromRows;
+    /** One row of {@link omitFieldsFromRows}: the row itself when it carries no denied key, else a copy without them. */
+    private static omitFieldsFromRow;
+    /**
+     * The plan for a row with exactly these keys, built on first sight of the shape. The last plan
+     * used is tried first; otherwise plans are found by the joined key list. Either way the plan's
+     * own key list is compared with the row's before it is used, so two different shapes can
+     * never share a plan.
+     */
+    private static rowProjectionPlanFor;
+    private static sameKeys;
     /**
      * Strips or narrows the `MJ: Record Changes` payload columns a user may not read, using the
      * denied set of the entity each row is ABOUT rather than of Record Changes itself.
@@ -1413,6 +1602,9 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * Everything about the per-row denied set, the payload treatment, and the fail-closed decision
      * lives in {@link RecordChangeFieldSecurityProjector}; this is only the RunView wiring.
      *
+     * A request whose entity cannot be resolved without I/O (only a `ViewID` or `ViewName`) is
+     * projected too, so a saved view over Record Changes is not a way around it.
+     *
      * Runs at all four RunView projection points, matching the main projection: both cache-hit
      * paths and both cache-miss paths. The cache-hit path is not optional — it is the exact path
      * the original cross-user leak runs through, an unrestricted user warming a full-width slot
@@ -1448,11 +1640,34 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     /**
      * Pre-processing hook for RunViews (batch).
      * Handles telemetry, validation, and cache lookup for multiple views.
+     * A view the field-security predicate gate refuses is left out of every later stage and
+     * reported in `refusedResults`; the cache status describes the admitted views only.
      * @param params - Array of view parameters
      * @param contextUser - Optional user context
-     * @returns Pre-processing result with cache status for each view
+     * @returns Pre-processing result with cache status for each admitted view
      */
     protected PreRunViews(params: RunViewParams[], contextUser?: UserInfo): Promise<typeof this._preRunViewsResultType>;
+    /**
+     * Runs each view's PreRunView hooks, replacing `params[i]` with the hooked params, then the
+     * field-security predicate gate — the same contract as the single-view path, except that a
+     * refusal fails only its own view: it becomes that view's `Success: false` result, carrying
+     * the refusal's ambiguous message, so the views batched with it still run. A batch is often
+     * several independent reads (a dashboard's panels), and one unreadable column in one of them
+     * must not blank the rest; the refusal is still reported, at the refused view's index. Any
+     * other error from the gate is thrown and fails the batch.
+     * @returns The refused views' results keyed by batch index, or `undefined` when none was refused.
+     */
+    private runBatchHooksAndPredicateGate;
+    /** `error` as a failed view result when it is a field-security refusal; otherwise rethrows it. */
+    protected static fieldSecurityRefusalAsResult<T = unknown>(error: unknown): RunViewResult<T>;
+    /**
+     * The cache stage of PreRunViews for the views the predicate gate admitted. An empty batch
+     * (every view refused) is reported as fully cached, so the pipeline returns without a
+     * database call and still ends the batch's telemetry event.
+     */
+    private lookUpAdmittedViews;
+    /** The server's trusted-cache lookup for a batch: serves hits, and lists the misses to run. */
+    private lookUpBatchCache;
     /**
      * Prepares smart cache check parameters for RunViews when CacheLocal is enabled.
      * Instead of returning cached data immediately, this builds params to send to the server
@@ -1502,6 +1717,22 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @param preResult - The pre-processing result
      * @param contextUser - Optional user context
      */
+    /**
+     * Hook allowing server database providers to substitute pre-decryption (ciphertext-preserving)
+     * rows before storing view results in {@link LocalCacheManager} / Redis, ensuring decrypted
+     * plaintext secrets are never persisted in local or shared caches.
+     *
+     * Client-side providers inherit this default identity implementation.
+     */
+    protected PrepareRowsForCacheStorage(rows: unknown[], _entityInfo?: EntityInfo): unknown[];
+    /**
+     * Hook allowing server database providers to decrypt ciphertext-at-rest rows retrieved from
+     * {@link LocalCacheManager} for in-process callers (or selectively preserve restricted
+     * ciphertext when `preserveRestrictedApiCiphertext` is `true`).
+     *
+     * Client-side providers inherit this default identity implementation.
+     */
+    protected MaterializeCachedRowsForCaller(rows: Record<string, unknown>[], _entityInfo?: EntityInfo, _contextUser?: UserInfo, _preserveRestrictedApiCiphertext?: boolean): Promise<Record<string, unknown>[]>;
     protected PostRunView(result: RunViewResult, params: RunViewParams, preResult: typeof this._preRunViewResultType, contextUser?: UserInfo): Promise<void>;
     /**
      * Post-processing hook for RunViews (batch).
@@ -1512,6 +1743,16 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @param contextUser - Optional user context
      */
     protected PostRunViews(results: RunViewResult[], params: RunViewParams[], preResult: typeof this._preRunViewsResultType, contextUser?: UserInfo): Promise<void>;
+    /**
+     * Works out a stored view's property values ({@link RunViewParams.Properties},
+     * {@link RunViewParams.ServerProperties}, and each property's default) before the run's cache
+     * lookup, so the result-cache fingerprint keys on the values the run will actually use. Called
+     * on the run's own params copy, after the PreRunView hooks. Must never throw: a run whose
+     * properties would be refused is left for the provider's run path to refuse with its message.
+     *
+     * Does nothing here. A database provider, which resolves token defaults on the server, overrides it.
+     */
+    protected PrepareRunViewProperties(_params: RunViewParams, _contextUser?: UserInfo): Promise<void>;
     /**
      * Runs all registered PreRunView hooks against a single RunViewParams,
      * returning the (possibly mutated) params.
@@ -1711,6 +1952,7 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * Resolves the {@link EntityInfo} normalization should read field types from, using only
      * synchronously available information on the params.
      */
+    protected resolveEntityForRunViewParams(param: RunViewParams): EntityInfo | undefined;
     private resolveEntityForNormalization;
     /**
      * The row keys each field of the given TSType can appear under, one entry per field.
@@ -1753,13 +1995,23 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     protected ReloadMetadata(hardRefresh: boolean, providerToUse?: IMetadataProvider, scopedFirst?: boolean): Promise<boolean>;
     /**
      * Adopts a metadata snapshot just loaded from the server: swaps it in, records that the
-     * local copy now matches the server's timestamps, and persists it to local storage.
+     * local copy now matches the server's timestamps (verified per item against the received
+     * dataset row counts), and persists it to local storage.
      *
      * The swap goes through UpdateLocalMetadata — a single property assignment, atomic in
      * JavaScript, so readers see the old snapshot until the new one is complete — which keeps
      * it consistent with LoadLocalMetadataFromStorage() and lets subclasses override it.
      */
     private adoptServerMetadata;
+    /**
+     * Verifies that each item in `_latestRemoteMetadataTimestamps` matches the row count actually
+     * received in the loaded `MJ_Metadata` dataset (or `AllMetadata` collections) before advancing
+     * `_latestLocalMetadataTimestamps`. If any item has a mismatched row count (e.g., because a
+     * server cache slot returned stale rows while the SQL status probe reported newer counts),
+     * logs a warning and preserves the unadvanced local timestamp for that item so the next
+     * staleness check (`LocalMetadataObsolete`) detects the discrepancy and self-heals.
+     */
+    private reconcileAdoptedMetadataTimestamps;
     /**
      * Decides whether the current staleness can be served by a scoped reload of the saved-query
      * family. Compares local and remote timestamps item by item (the same test as
@@ -1865,14 +2117,30 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * customized adoption through CloneAllMetadata. Remove the CloneAllMetadata
      * override to activate a CreateSharedMetadataShell override.
      */
+    /**
+     * Builds this instance's AllMetadata as a zero-copy prototype-delegated shell over
+     * another provider's already-loaded metadata (`Object.create(shared)`), keeping
+     * `CurrentUser` as an own property on the shell instance.
+     *
+     * Why zero-copy prototype delegation is safe: the metadata graph (`AllMetadata` and its
+     * arrays) is treated as immutable after `Config`. Refreshes swap the entire `AllMetadata`
+     * reference via `UpdateLocalMetadata` rather than mutating the previous `AllMetadata`
+     * instance in place, so in-flight shells continue reading a consistent snapshot while
+     * avoiding 19 array shallow-copies on every per-request provider creation.
+     */
     protected CreateSharedMetadataShell(shared: AllMetadata): AllMetadata;
     /**
      * Adopts the global provider's metadata for this instance without reloading it
      * from the server: shares the (immutable post-Config) metadata arrays by
-     * reference via {@link CreateSharedMetadataShell} and builds this instance's
+     * reference via {@link CreateSharedMetadataShell} and shares or builds this instance's
      * entity lookup maps.
      */
     protected CopyMetadataFromGlobalProvider(): boolean;
+    /**
+     * Re-adopts the immutable read-only metadata catalog shell and lookup maps from
+     * `Metadata.Provider` after the global provider completes a metadata refresh.
+     */
+    SyncMetadataFromGlobalProvider(): boolean;
     /**
      * Builds dataset filters based on the provider configuration.
      * Ensures MJ Core schema is always included and never excluded.
@@ -1917,7 +2185,7 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * metadata post-processing, replacing repeated O(N*M) filter scans.
      */
     private groupByNormalizedUUID;
-    protected PostProcessEntityMetadata(entities: EntityMetadataRow[], fields: EntityFieldMetadataRow[], fieldValues: EntityFieldValueMetadataRow[], permissions: EntityChildMetadataRow[], relationships: EntityChildMetadataRow[], settings: EntityChildMetadataRow[], organicKeys?: OrganicKeyMetadataRow[], organicKeyRelatedEntities?: OrganicKeyRelatedEntityMetadataRow[], fieldPermissions?: EntityFieldPermissionMetadataRow[]): EntityInfo[];
+    protected PostProcessEntityMetadata(entities: EntityMetadataRow[], fields: EntityFieldMetadataRow[], fieldValues: EntityFieldValueMetadataRow[], permissions: EntityChildMetadataRow[], relationships: EntityChildMetadataRow[], settings: EntityChildMetadataRow[], organicKeys?: OrganicKeyMetadataRow[], organicKeyRelatedEntities?: OrganicKeyRelatedEntityMetadataRow[], fieldPermissions?: EntityFieldPermissionMetadataRow[], alternateBaseViews?: EntityChildMetadataRow[]): EntityInfo[];
     /**
      * Gets the configuration data that was provided to the provider.
      * @returns The provider configuration including schema filters
@@ -2040,6 +2308,27 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * RefreshIfNeeded load outside Config's reload single-flight). For the same reason it gets
      * `false`, not the owner's rejection, when the owner's check throws.
      * @returns True if refresh is needed, false otherwise
+     *
+     * @remarks
+     * This is a **freshness question, not a load**, so it never throws on an unreachable
+     * server. {@link ReadRemoteMetadataTimestamps} reports whether the server was reached at
+     * all, and when it was NOT the honest answer here depends on whether we hold anything to
+     * serve:
+     *
+     * - **We hold local metadata** → answer `false` ("do not tear this down"). The cached
+     *   snapshot may be a few seconds stale; a rejected status query is no reason to throw
+     *   it away, and every caller of this method treats `false` as "carry on with what you
+     *   have".
+     * - **We hold nothing** → answer `true`, so the caller attempts a real load against the
+     *   actual metadata fetch. That load logs its own failure and leaves the graph empty;
+     *   `SetupGraphQLClient` turns an empty graph into an error carrying it, while a caller
+     *   that only checks {@link Config}'s return value sees `true`.
+     *
+     * Before this, an unreachable status query propagated an exception out of
+     * {@link Config} and the Explorer's single boot catch turned it into a non-retryable
+     * "System Error" — the whole app dead over a freshness check it did not need an answer
+     * to. The two warm callers ({@link backgroundValidateAndRefresh},
+     * {@link preValidateAndRefresh}) already caught it; {@link Config} did not.
      */
     CheckToSeeIfRefreshNeeded(providerToUse?: IMetadataProvider, bypassMinCheckInterval?: boolean): Promise<boolean>;
     /**
@@ -2097,9 +2386,11 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * is within the EntityField table and specifically the RelatedEntity and RelatedEntityField columns. In turn, this method uses that metadata and queries the database to determine the dependencies. To get the list of entity dependencies
      * you can use the utility method GetEntityDependencies(), which doesn't check for dependencies on a specific record, but rather gets the metadata in one shot that can be used for dependency checking.
      * @param entityName the name of the entity to check
-     * @param KeyValuePairs the values of the primary key of the record to check
+     * @param CompositeKey the values of the primary key of the record to check
+     * @param contextUser optional user context (or options when called with 3 arguments)
+     * @param options optional filtering options for dependency discovery
      */
-    abstract GetRecordDependencies(entityName: string, CompositeKey: CompositeKey, contextUser?: UserInfo): Promise<RecordDependency[]>;
+    abstract GetRecordDependencies(entityName: string, CompositeKey: CompositeKey, contextUser?: UserInfo | GetRecordDependenciesOptions, options?: GetRecordDependenciesOptions): Promise<RecordDependency[]>;
     /**
      * Returns a list of record IDs that are possible duplicates of the specified record.
      *
@@ -2164,6 +2455,11 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
      * @returns
      */
     IsDatasetCacheUpToDate(datasetName: string, itemFilters?: DatasetItemFilterType[]): Promise<boolean>;
+    /**
+     * Normalizes a dataset `LatestUpdateDate` to a valid `Date`, or `null` when absent or invalid
+     * (for example, when a dataset or dataset-status call fails and returns `LatestUpdateDate: null`).
+     */
+    private validDatasetDate;
     /**
      * Compares the per-entity row counts of a cached dataset against the server's status.
      *
@@ -2288,15 +2584,68 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     get LatestLocalMetadata(): MetadataInfo[];
     /**
      * Retrieves the latest metadata update timestamps from the server.
-     * @returns Array of metadata update information
+     * @returns Array of metadata update information, or `undefined` when the server could not
+     * be asked (transport failure, timeout, gateway error) or answered unsuccessfully.
+     *
+     * @remarks
+     * This is the ONE network call behind every staleness check, and it is a question about
+     * freshness — never the metadata itself. A rejected status query therefore returns
+     * `undefined` (an absent answer) rather than propagating: its callers already treat a
+     * falsy result as "could not tell", while an exception out of here travelled unguarded
+     * through {@link RefreshRemoteMetadataTimestamps} → {@link CheckToSeeIfRefreshNeeded} →
+     * {@link Config} and killed the caller's whole bootstrap.
+     *
+     * The failure is logged at error level, not swallowed quietly: "we are running on a
+     * cached snapshot because the server did not answer" is something an operator needs to
+     * see in the console.
      */
     protected GetLatestMetadataUpdates(providerToUse?: IMetadataProvider): Promise<MetadataInfo[]>;
+    /**
+     * The metadata-status read, with **why** it failed preserved.
+     *
+     * Two failures look the same to {@link GetLatestMetadataUpdates} — both give `undefined` —
+     * but they call for opposite responses, so callers that can act on the difference read it
+     * here instead:
+     *
+     * - `Reached: false` — the request never got an answer (transport failure, timeout, 504).
+     *   Transient. Nothing can be concluded about freshness, and a full metadata load would hit
+     *   the same wall, so the right move is to keep serving what we have.
+     * - `Reached: true` with no `Timestamps` — the server answered `Success: false`. A
+     *   *permanent* condition (the dataset is missing or misconfigured), not a network blip.
+     *   Degrading here would serve a stale cache forever; the historical behaviour of treating
+     *   it as "obsolete" and attempting the real load is correct, because `GetDatasetByName`
+     *   may well still work.
+     * - A rejection that is NOT a transport failure — an authorization denial ("this API key
+     *   requires the dataset:read scope"), a validation rejection, a programming error — is
+     *   the server (or our own code) answering, not the wire failing. It propagates exactly
+     *   as it did before this method existed. {@link IsTransportError} draws the line. The
+     *   integration tier's FLS fixture depends on this: it builds a reader whose scope rule
+     *   has not propagated yet and retries `Config()` until the denial stops — a denial
+     *   swallowed into `Reached: false` left that reader with an empty snapshot for good.
+     *
+     * Conflating these is how a broken status endpoint — or a refused identity — would become
+     * permanently invisible.
+     */
+    protected ReadRemoteMetadataTimestamps(providerToUse?: IMetadataProvider): Promise<{
+        Reached: boolean;
+        Timestamps: MetadataInfo[] | undefined;
+    }>;
+    /** Shape a dataset-status answer into the timestamp list, or `undefined` if it failed. */
+    private mapDatasetStatusToTimestamps;
     /**
      * Refreshes the remote metadata timestamps from the server.
      * Updates the internal cache of remote timestamps.
      * @returns True if timestamps were successfully refreshed
      */
     RefreshRemoteMetadataTimestamps(providerToUse?: IMetadataProvider): Promise<boolean>;
+    /**
+     * Whether the most recent {@link RefreshRemoteMetadataTimestamps} actually REACHED the
+     * server, regardless of whether it came back with usable timestamps.
+     *
+     * Starts `true` so that nothing reads "unreachable" before a read has been attempted.
+     * See {@link ReadRemoteMetadataTimestamps} for why the distinction exists.
+     */
+    private _lastRemoteTimestampReadReached;
     /**
      * Checks if local metadata is obsolete compared to remote metadata.
      * Compares timestamps and row counts to detect changes.
@@ -2311,6 +2660,8 @@ export declare abstract class ProviderBase implements IMetadataProvider, IRunVie
     protected UpdateLocalMetadata(res: AllMetadata): void;
     /**
      * Rebuilds the O(1) entity lookup Maps from the current AllEntities array.
+     * Allocates fresh Map instances so any per-request provider sharing a previous
+     * snapshot's maps is unaffected by a subsequent refresh.
      * Called automatically from UpdateLocalMetadata().
      */
     protected RebuildEntityMaps(): void;