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

package/dist/generic/entityInfo.js

@@ -1,9 +1,10 @@
 import { BaseInfo } from "./baseInfo.js";
 import { Metadata } from "./metadata.js";
+import { MetadataProviderFor } from "./infoProviderResolution.js";
 import { TypeScriptTypeFromSQLType, SQLFullType, SQLMaxLength, SQLMaxByteLength, FormatValue, CodeNameFromString } from "./util.js";
 import { IsFixedWidthStringSQLType } from "@memberjunction/sql-dialect";
 import { LogError } from "./logging.js";
-import { WarningManager, SafeJSONParse, UUIDsEqual, ordinalCompare, GeneratePluralName } from "@memberjunction/global";
+import { WarningManager, SafeJSONParse, UUIDsEqual, NormalizeUUID, ordinalCompare, GeneratePluralName } from "@memberjunction/global";
 import { ReadRelationshipJoinFields, } from "./entityConfiguration.js";
 /**
  * Runtime domain for {@link EntityFieldInfo.ExtendedType}. This array is the single source of
@@ -305,6 +306,186 @@ export class EntityOrganicKeyRelatedEntityInfo extends BaseInfo {
         }
     }
 }
+/**
+ * Metadata describing a governed alternate SQL view on an entity that maintains 100% column
+ * parity with the entity's canonical `BaseView` while applying a curated canonical filter
+ * or join (for example, `Active` members or `Open` orders).
+ *
+ * Alternate base views can form a same-entity derivation hierarchy via {@link ParentID}
+ * (for example, `ActiveAutoRenew` selecting from `vwActiveMembers`).
+ *
+ * Maps to the `MJ: Entity Alternate Base Views` metadata entity.
+ */
+export class EntityAlternateBaseViewInfo extends BaseInfo {
+    /**
+     * The parent alternate base view on the same entity when {@link ParentID} is set,
+     * or `undefined` for a top-level alternate base view.
+     */
+    get ParentView() {
+        return this._resolvedParentViewRef;
+    }
+    /**
+     * Direct child alternate base views on the same entity that derive from this view via {@link ParentID}.
+     */
+    get ChildViews() {
+        return this._resolvedChildViewsList;
+    }
+    /**
+     * Effective database schema name for this alternate base view: uses {@link SchemaName}
+     * when explicitly populated, falling back to the parent entity's `SchemaName`.
+     */
+    get EffectiveSchemaName() {
+        const explicit = this.SchemaName?.trim();
+        if (explicit && explicit.length > 0) {
+            return explicit;
+        }
+        return this._entitySchemaName ?? '';
+    }
+    /**
+     * Human-friendly label for UI surfaces: returns {@link DisplayName} when set,
+     * falling back to {@link Name}.
+     */
+    get EffectiveDisplayName() {
+        const display = this.DisplayName?.trim();
+        if (display && display.length > 0) {
+            return display;
+        }
+        return this.Name;
+    }
+    /**
+     * True when this alternate base view (and every ancestor in its {@link ParentView} chain)
+     * has `Status` equal to `'Active'` or `'Deprecated'`. Disabled views (or views derived
+     * from a disabled or missing ancestor) return `false`.
+     */
+    get IsUsable() {
+        return this.checkIsUsable(new Set());
+    }
+    checkIsUsable(visited) {
+        if (this.Status !== 'Active' && this.Status !== 'Deprecated') {
+            return false;
+        }
+        if (!this.ParentID) {
+            return true;
+        }
+        if (!this._resolvedParentViewRef) {
+            return false; // ParentID is set but parent view was not found on the entity
+        }
+        const key = NormalizeUUID(this.ID);
+        if (key && visited.has(key)) {
+            return false; // Defensive cycle guard
+        }
+        if (key) {
+            visited.add(key);
+        }
+        return this._resolvedParentViewRef.checkIsUsable(visited);
+    }
+    /**
+     * True when this view (or any ancestor in its {@link ParentView} chain) has
+     * `Status === 'Deprecated'`. Deprecated alternate base views remain usable at runtime
+     * so existing views and queries do not break, but emit a deprecation warning.
+     */
+    get IsDeprecated() {
+        return this.checkIsDeprecated(new Set());
+    }
+    checkIsDeprecated(visited) {
+        if (this.Status === 'Deprecated') {
+            return true;
+        }
+        if (!this._resolvedParentViewRef) {
+            return false;
+        }
+        const key = NormalizeUUID(this.ID);
+        if (key && visited.has(key)) {
+            return false;
+        }
+        if (key) {
+            visited.add(key);
+        }
+        return this._resolvedParentViewRef.checkIsDeprecated(visited);
+    }
+    /**
+     * True when `CachePolicy === 'Bypass'` on this view or any ancestor in its {@link ParentView}
+     * chain, instructing `ProviderBase` to skip local/server result caching for reads through
+     * this alternate base view (used when the view reads the clock or joins other tables whose
+     * updates do not fire `BaseEntity` events on this entity).
+     */
+    get IsBypassCache() {
+        return this.checkIsBypassCache(new Set());
+    }
+    checkIsBypassCache(visited) {
+        if (this.CachePolicy === 'Bypass') {
+            return true;
+        }
+        if (!this._resolvedParentViewRef) {
+            return false;
+        }
+        const key = NormalizeUUID(this.ID);
+        if (key && visited.has(key)) {
+            return false;
+        }
+        if (key) {
+            visited.add(key);
+        }
+        return this._resolvedParentViewRef.checkIsBypassCache(visited);
+    }
+    /**
+     * Links `ParentView` and `ChildViews` references across the alternate base views belonging
+     * to a single entity and stamps the owning entity's `SchemaName` fallback.
+     */
+    static LinkHierarchy(views, entitySchemaName) {
+        const byId = new Map();
+        for (const v of views) {
+            if (entitySchemaName !== undefined) {
+                v._entitySchemaName = entitySchemaName;
+            }
+            v._resolvedParentViewRef = undefined;
+            v._resolvedChildViewsList = [];
+            if (v.ID) {
+                byId.set(NormalizeUUID(v.ID), v);
+            }
+        }
+        for (const v of views) {
+            if (v.ParentID && !UUIDsEqual(v.ParentID, v.ID)) {
+                const parent = byId.get(NormalizeUUID(v.ParentID));
+                if (parent) {
+                    v._resolvedParentViewRef = parent;
+                    parent._resolvedChildViewsList.push(v);
+                }
+            }
+        }
+    }
+    constructor(initData = null, entitySchemaName) {
+        super();
+        this.ID = null;
+        this.EntityID = null;
+        this.ParentID = null;
+        this.Name = null;
+        this.DisplayName = null;
+        this.Description = null;
+        this.SchemaName = null;
+        this.ViewName = null;
+        this.CachePolicy = 'Default';
+        this.Status = 'Active';
+        this.Sequence = 0;
+        this.__mj_CreatedAt = null;
+        this.__mj_UpdatedAt = null;
+        // Virtual fields from vwEntityAlternateBaseViews
+        this.Entity = null;
+        this.Parent = null;
+        this.RootParentID = null;
+        this._entitySchemaName = null;
+        // Named without matching `ParentView` / `ChildViews` getter names so `BaseInfo.toJSON()`
+        // does not serialize parent<->child object references into a circular JSON graph.
+        this._resolvedParentViewRef = undefined;
+        this._resolvedChildViewsList = [];
+        if (entitySchemaName !== undefined) {
+            this._entitySchemaName = entitySchemaName;
+        }
+        if (initData) {
+            this.copyInitData(initData);
+        }
+    }
+}
 export const EntityPermissionType = {
     Read: 'Read',
     Create: 'Create',
@@ -369,9 +550,13 @@ export class EntityPermissionInfo extends BaseInfo {
                 break;
         }
         if (fID && fID.length > 0)
-            return Metadata.Provider.RowLevelSecurityFilters.find(f => UUIDsEqual(f.ID, fID)); // global-provider-ok: stateless info class — proxies to global metadata
+            return MetadataProviderFor(this)?.RowLevelSecurityFilters?.find(f => UUIDsEqual(f.ID, fID));
     }
-    constructor(initData) {
+    /**
+     * @param initData - the raw permission row
+     * @param md - the provider that owns this metadata; RLS filters resolve through it (see {@link BaseInfo.OwningProvider})
+     */
+    constructor(initData, md) {
         super();
         this.ID = null;
         this.EntityID = null;
@@ -401,6 +586,7 @@ export class EntityPermissionInfo extends BaseInfo {
         this.CreateRLSFilter = null;
         this.UpdateRLSFilter = null;
         this.DeleteRLSFilter = null;
+        this.SetOwningProvider(md);
         this.copyInitData(initData);
     }
 }
@@ -457,9 +643,16 @@ export const ReadableFieldsTransportKey = 'ReadableFields___';
  * set and aggregate it — see {@link EntityFieldInfo.AggregateFieldRulesForUser}.
  */
 export function IsRestrictingFieldRule(rule) {
-    return (rule?.ReadAccess === FieldPermissionAccess.Deny ||
-        rule?.UpdateAccess === FieldPermissionAccess.Deny ||
-        rule?.CreateAccess === FieldPermissionAccess.Deny);
+    return isDenyAccess(rule?.ReadAccess) || isDenyAccess(rule?.UpdateAccess) || isDenyAccess(rule?.CreateAccess);
+}
+/**
+ * Whether one Access value means `Deny`, compared the way the aggregation compares: ignoring case
+ * and surrounding whitespace. The column's CHECK constraint runs under a case-insensitive
+ * collation, so `'deny'` stores, and the aggregation enforces it as a Deny; a strict `===` here
+ * would call that same rule harmless.
+ */
+function isDenyAccess(access) {
+    return (access ?? '').trim().toLowerCase() === 'deny';
 }
 /**
  * The single wording for "you cannot use this field", modelled on SQL Server's posture of never
@@ -927,14 +1120,16 @@ export class EntityFieldInfo extends BaseInfo {
     static AggregateFieldRulesForUser(rules, user) {
         const allow = { CanRead: false, CanUpdate: false, CanCreate: false };
         const deny = { CanRead: false, CanUpdate: false, CanCreate: false };
-        for (const fp of rules) {
-            const roleMatch = user?.UserRoles?.find((r) => UUIDsEqual(r.RoleID, fp.RoleID));
-            if (!roleMatch) {
-                continue; // user does not hold this role
+        const userRoleIds = getUserRoleIdSet(user);
+        if (userRoleIds.size > 0) {
+            for (const fp of rules) {
+                if (!fp.RoleID || !userRoleIds.has(fp.RoleID.trim().toLowerCase())) {
+                    continue; // user does not hold this role
+                }
+                EntityFieldInfo.applyAccessToBuckets(fp.ReadAccess, allow, deny, 'CanRead');
+                EntityFieldInfo.applyAccessToBuckets(fp.UpdateAccess, allow, deny, 'CanUpdate');
+                EntityFieldInfo.applyAccessToBuckets(fp.CreateAccess, allow, deny, 'CanCreate');
             }
-            EntityFieldInfo.applyAccessToBuckets(fp.ReadAccess, allow, deny, 'CanRead');
-            EntityFieldInfo.applyAccessToBuckets(fp.UpdateAccess, allow, deny, 'CanUpdate');
-            EntityFieldInfo.applyAccessToBuckets(fp.CreateAccess, allow, deny, 'CanCreate');
         }
         const effective = {
             CanRead: allow.CanRead && !deny.CanRead,
@@ -971,17 +1166,23 @@ export class EntityFieldInfo extends BaseInfo {
      * Returns the ValueListType using the EntityFieldValueListType enum.
      */
     get ValueListTypeEnum() {
-        if (this.ValueListType == null)
-            return EntityFieldValueListType.None;
-        else {
-            // iterate through list of possibilities from enum and compare lcase
-            for (let enumMember in EntityFieldValueListType) {
-                if (typeof EntityFieldValueListType[enumMember] === 'string' &&
-                    enumMember.toLowerCase().trim() === this.ValueListType.toLowerCase().trim()) {
-                    return EntityFieldValueListType[enumMember];
-                }
+        if (this._valueListTypeEnumCache !== undefined) {
+            return this._valueListTypeEnumCache;
+        }
+        if (this.ValueListType == null) {
+            this._valueListTypeEnumCache = EntityFieldValueListType.None;
+            return this._valueListTypeEnumCache;
+        }
+        const target = this.ValueListType.toLowerCase().trim();
+        for (const enumMember in EntityFieldValueListType) {
+            if (typeof EntityFieldValueListType[enumMember] === 'string' &&
+                enumMember.toLowerCase().trim() === target) {
+                this._valueListTypeEnumCache = EntityFieldValueListType[enumMember];
+                return this._valueListTypeEnumCache;
             }
         }
+        this._valueListTypeEnumCache = EntityFieldValueListType.None;
+        return this._valueListTypeEnumCache;
     }
     /**
      * Upper bound on how many legal values a validation message enumerates before it truncates.
@@ -1458,19 +1659,28 @@ export class EntityFieldInfo extends BaseInfo {
      * Returns true if the field is the CreatedAt field, a special field that is used to track the creation date of a record. This is only used when the entity has TrackRecordChanges=1
      */
     get IsCreatedAtField() {
-        return this.Name.trim().toLowerCase() === EntityInfo.CreatedAtFieldName.trim().toLowerCase();
+        if (this._isCreatedAtFieldCache !== undefined)
+            return this._isCreatedAtFieldCache;
+        this._isCreatedAtFieldCache = this.Name.trim().toLowerCase() === EntityInfo.CreatedAtFieldName.trim().toLowerCase();
+        return this._isCreatedAtFieldCache;
     }
     /**
      * Returns true if the field is the UpdatedAt field, a special field that is used to track the last update date of a record. This is only used when the entity has TrackRecordChanges=1
      */
     get IsUpdatedAtField() {
-        return this.Name.trim().toLowerCase() === EntityInfo.UpdatedAtFieldName.trim().toLowerCase();
+        if (this._isUpdatedAtFieldCache !== undefined)
+            return this._isUpdatedAtFieldCache;
+        this._isUpdatedAtFieldCache = this.Name.trim().toLowerCase() === EntityInfo.UpdatedAtFieldName.trim().toLowerCase();
+        return this._isUpdatedAtFieldCache;
     }
     /**
      * Returns true if the field is the DeletedAt field, a special field that is used to track the deletion date of a record. This is only used when the entity has DeleteType=Soft
      */
     get IsDeletedAtField() {
-        return this.Name.trim().toLowerCase() === EntityInfo.DeletedAtFieldName.trim().toLowerCase();
+        if (this._isDeletedAtFieldCache !== undefined)
+            return this._isDeletedAtFieldCache;
+        this._isDeletedAtFieldCache = this.Name.trim().toLowerCase() === EntityInfo.DeletedAtFieldName.trim().toLowerCase();
+        return this._isDeletedAtFieldCache;
     }
     /**
      * Returns true if the field is a GUID/UUID column in the database.
@@ -1479,8 +1689,11 @@ export class EntityFieldInfo extends BaseInfo {
      * `uuid`, so a `uniqueidentifier`-only check would miss every UUID column.
      */
     get IsUniqueIdentifier() {
+        if (this._isUniqueIdentifierCache !== undefined)
+            return this._isUniqueIdentifierCache;
         const t = this.Type.trim().toLowerCase();
-        return t === 'uniqueidentifier' || t === 'uuid';
+        this._isUniqueIdentifierCache = t === 'uniqueidentifier' || t === 'uuid';
+        return this._isUniqueIdentifierCache;
     }
     /**
      * Returns true if the field's SQL type is **fixed-width / space-padded**
@@ -1493,7 +1706,10 @@ export class EntityFieldInfo extends BaseInfo {
      * (un-padded) form of the value.
      */
     get FixedWidthColumn() {
-        return IsFixedWidthStringSQLType(this.Type);
+        if (this._fixedWidthColumnCache !== undefined)
+            return this._fixedWidthColumnCache;
+        this._fixedWidthColumnCache = IsFixedWidthStringSQLType(this.Type);
+        return this._fixedWidthColumnCache;
     }
     /**
      * Returns true if the field has a default value set
@@ -1623,6 +1839,10 @@ export class EntityFieldInfo extends BaseInfo {
     FormatValue(value, decimals = 2, currency = 'USD', maxLength = 0, trailingChars = "...") {
         return FormatValue(this.Type, value, decimals, currency, maxLength, trailingChars);
     }
+    static { this.CHILD_INIT_KEYS = new Set([
+        'EntityFieldValues', '_EntityFieldValues',
+        'EntityFieldPermissions', '_FieldPermissions', 'FieldPermissions',
+    ]); }
     constructor(initData = null) {
         super();
         this.ID = null;
@@ -2007,6 +2227,7 @@ export class EntityFieldInfo extends BaseInfo {
          */
         this._relatedEntityJoinFieldsFailedParsing = false;
         this._fieldPermissions = [];
+        this._valueListTypeEnumCache = undefined;
         /** Memoized {@link TSType} — `Type` is immutable after metadata load, so the classification never changes. */
         this._tsType = undefined;
         /**
@@ -2014,8 +2235,14 @@ export class EntityFieldInfo extends BaseInfo {
          * This property returns a consistent CodeName you can use everywhere to refer to the field when generated variable names
          */
         this._codeName = null;
+        this._isCreatedAtFieldCache = undefined;
+        this._isUpdatedAtFieldCache = undefined;
+        this._isDeletedAtFieldCache = undefined;
+        this._isUniqueIdentifierCache = undefined;
+        this._fixedWidthColumnCache = undefined;
+        this._parsedDefaultValueCache = undefined;
         if (initData) {
-            this.copyInitData(initData);
+            this.copyInitData(initData, EntityFieldInfo.CHILD_INIT_KEYS);
             // Lazy-construct EntityFieldValueInfo objects — stash raw data now,
             // construct typed instances on first access via the getter.
             // This eliminates ~36,000 object constructions during startup deserialization.
@@ -2096,7 +2323,157 @@ export class EntityFieldInfo extends BaseInfo {
         // Using includes() because the value might be wrapped in parentheses like (getdate())
         return EntityFieldInfo.SQL_CURRENT_DATE_FUNCTIONS.some(func => normalizedValue.includes(func));
     }
+    static { this.PG_TYPED_LITERAL_REGEX = /^'((?:[^']|'')*)'::[A-Za-z][\w "()\[\],]*$/; }
+    /**
+     * Parses a field's SQL DefaultValue into its runtime JS representation.
+     * Exposed as a static helper so unit tests passing plain-object mocks for EntityFieldInfo
+     * work identically to real EntityFieldInfo instances.
+     */
+    static ParseDefaultValue(field) {
+        const rawDefault = field.DefaultValue;
+        if (!rawDefault) {
+            return { source: rawDefault, hasValue: true, value: null, isCurrentDateFunction: false };
+        }
+        if (field.TSType === EntityFieldTSType.Boolean) {
+            const val = typeof rawDefault === 'string' &&
+                (rawDefault.trim() === '1' || rawDefault.trim().toLowerCase() === 'true');
+            return { source: rawDefault, hasValue: true, value: val, isCurrentDateFunction: false };
+        }
+        if (field.TSType === EntityFieldTSType.Number) {
+            const num = Number(rawDefault);
+            if (!isNaN(num)) {
+                return { source: rawDefault, hasValue: true, value: num, isCurrentDateFunction: false };
+            }
+            if (typeof rawDefault === 'string' && rawDefault.trim().toLowerCase() === 'null') {
+                return { source: rawDefault, hasValue: true, value: null, isCurrentDateFunction: false };
+            }
+            return { source: rawDefault, hasValue: false, value: undefined, isCurrentDateFunction: false };
+        }
+        const isUniqueId = field.IsUniqueIdentifier !== undefined
+            ? field.IsUniqueIdentifier
+            : (typeof field.Type === 'string' && (field.Type.trim().toLowerCase() === 'uniqueidentifier' || field.Type.trim().toLowerCase() === 'uuid'));
+        if (isUniqueId) {
+            return { source: rawDefault, hasValue: true, value: null, isCurrentDateFunction: false };
+        }
+        if (field.TSType === EntityFieldTSType.Date) {
+            if (typeof rawDefault === 'string' && rawDefault.trim().length > 0) {
+                const temp = new Date(rawDefault);
+                if (!isNaN(temp.getTime())) {
+                    return { source: rawDefault, hasValue: true, value: temp, isCurrentDateFunction: false };
+                }
+                if (EntityFieldInfo.IsDefaultValueSQLCurrentDateFunction(rawDefault)) {
+                    if (field.IsSpecialDateField) {
+                        return { source: rawDefault, hasValue: true, value: null, isCurrentDateFunction: false };
+                    }
+                    return { source: rawDefault, hasValue: true, value: null, isCurrentDateFunction: true };
+                }
+                throw new Error(`Invalid default value for ${field.Entity}.${field.Name} of ${rawDefault}. Default values for date fields must be a valid date or a getdate() type default`);
+            }
+            return { source: rawDefault, hasValue: false, value: undefined, isCurrentDateFunction: false };
+        }
+        const dv = typeof rawDefault === 'string' ? rawDefault.trim() : String(rawDefault);
+        const m = dv.match(EntityFieldInfo.PG_TYPED_LITERAL_REGEX);
+        const strVal = m ? m[1].replace(/''/g, "'") : rawDefault;
+        return { source: rawDefault, hasValue: true, value: strVal, isCurrentDateFunction: false };
+    }
+    /**
+     * Parses and memoizes the SQL DefaultValue into its runtime JS representation once per
+     * EntityFieldInfo instead of re-parsing (trimming, regex matching, Number/Date parsing)
+     * on every EntityField instantiation.
+     */
+    GetParsedDefaultValue() {
+        const rawDefault = this.DefaultValue;
+        if (this._parsedDefaultValueCache !== undefined && this._parsedDefaultValueCache.source === rawDefault) {
+            return this._parsedDefaultValueCache;
+        }
+        this._parsedDefaultValueCache = EntityFieldInfo.ParseDefaultValue(this);
+        return this._parsedDefaultValueCache;
+    }
+}
+const _emptyStringSet = new Set();
+const _userRoleIdSetCache = new WeakMap();
+function getUserRoleIdSet(user) {
+    if (!user?.UserRoles || user.UserRoles.length === 0) {
+        return _emptyStringSet;
+    }
+    const roles = user.UserRoles;
+    const len = roles.length;
+    const firstId = roles[0]?.RoleID;
+    const cached = _userRoleIdSetCache.get(user);
+    if (cached && cached.rolesRef === roles && cached.rolesLen === len && cached.firstRoleId === firstId) {
+        return cached.roleIds;
+    }
+    const roleIds = new Set();
+    for (let i = 0; i < len; i++) {
+        const rid = roles[i]?.RoleID;
+        if (rid) {
+            roleIds.add(rid.trim().toLowerCase());
+        }
+    }
+    _userRoleIdSetCache.set(user, { rolesRef: roles, rolesLen: len, firstRoleId: firstId, roleIds });
+    return roleIds;
+}
+const _entityFieldIndexCache = new WeakMap();
+const _entityDeniedFieldsCache = new WeakMap();
+/**
+ * The field-security generation: one process-wide number that moves whenever an answer derived
+ * from field-security configuration may have changed. It moves when an `EntityInfo` is built (a
+ * metadata refresh rebuilds every entity), when an entity's {@link EntityInfo.EnableFieldLevelSecurity}
+ * flag is assigned, and when {@link EntityInfo.InvalidateFieldSecurityCache} is called. Every memo
+ * of a field-security answer records the number it was filled under and is discarded once the
+ * number has moved, so a memo is never served across any of those changes. Numbers only grow.
+ */
+let _fieldSecurityGeneration = 0;
+/** Marks every memoized field-security answer stale (see {@link CurrentFieldSecurityGeneration}). */
+function advanceFieldSecurityGeneration() {
+    _fieldSecurityGeneration++;
 }
+/**
+ * The current field-security generation. A memo of anything derived from field-security
+ * configuration (denied sets, whether field security applies, a user's denial profile across a
+ * catalog) is valid only while this returns the number the memo was filled under. It moves when an
+ * `EntityInfo` is built, when an entity's `EnableFieldLevelSecurity` flag is assigned, and when
+ * `EntityInfo.InvalidateFieldSecurityCache()` is called.
+ */
+export function CurrentFieldSecurityGeneration() {
+    return _fieldSecurityGeneration;
+}
+const NO_ANCESTORS = Object.freeze([]);
+/** Whether two ancestor lists hold the same entities, by identity, in the same order. */
+function sameAncestors(a, b) {
+    if (a === b) {
+        return true;
+    }
+    if (a.length !== b.length) {
+        return false;
+    }
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The role IDs a user holds, in order, as one string: changes whenever a role is added, removed
+ * or swapped. Field-level security reads nothing else about a user, so this, with
+ * {@link CurrentFieldSecurityGeneration}, keys any memo of a user's field-security answers.
+ */
+export function FieldSecurityUserRolesKey(user) {
+    return userRolesKey(user);
+}
+function userRolesKey(user) {
+    const roles = user.UserRoles;
+    if (!roles || roles.length === 0) {
+        return '';
+    }
+    let key = '';
+    for (let i = 0; i < roles.length; i++) {
+        key += `${roles[i]?.RoleID ?? ''}|`;
+    }
+    return key;
+}
+const _entityChildEntitiesCache = new WeakMap();
 /**
  * Entity Document Type Info object has information about the document types that exist across all entities. When Entity Documents are created they are associated with a document type.
  */
@@ -2222,6 +2599,28 @@ export class EntityInfo extends BaseInfo {
         LogError(`EntityInfo '${this.Name}': SubtypeSelector 'UseForLoadedRecords' must be true or false, but is ${JSON.stringify(value)}. Loads of this entity won't use the selector.`);
         return false;
     }
+    /**
+     * Whether field-level (column-level) security is enforced for this entity.
+     *
+     * This is the single gate every field-security enforcement point checks first, and it is
+     * explicit — never inferred from whether permission rows happen to exist. It is `false` for
+     * nearly every entity in nearly every deployment, so enforcement collapses to one boolean
+     * test: no field iteration, no aggregation, no allocation.
+     *
+     * Turning it on snapshots the entity's existing entity-level permissions into per-field
+     * rows, so enabling changes no behavior until an administrator tightens a field. Turning it
+     * off leaves the rows in place, inactive, so re-enabling does not lose the configuration.
+     *
+     * Assigning it moves the field-security generation ({@link CurrentFieldSecurityGeneration}),
+     * so every memoized field-security answer that read the old value is recomputed.
+     */
+    get EnableFieldLevelSecurity() {
+        return this._enableFieldLevelSecurity;
+    }
+    set EnableFieldLevelSecurity(value) {
+        this._enableFieldLevelSecurity = value;
+        advanceFieldSecurityGeneration();
+    }
     /**
      * True when at least one field is a writable Geo* source (street and/or native lat/lng).
      * Person/Org PrimaryAddress* are virtual display fields and do **not** count.
@@ -2327,6 +2726,30 @@ export class EntityInfo extends BaseInfo {
     get CloneConfig() {
         return this.ConfigurationObject?.Clone ?? null;
     }
+    /**
+     * Controls which columns a save operation (`spCreate` / `spUpdate`) returns from the database
+     * for this entity. Defaults to `'full'` when `Configuration.SaveReturnMode` is omitted or not
+     * `'datestamps_only'`.
+     */
+    get SaveReturnMode() {
+        return this.ConfigurationObject?.SaveReturnMode === 'datestamps_only' ? 'datestamps_only' : 'full';
+    }
+    /**
+     * Returns the ordered list of base-table fields returned by a `'datestamps_only'` save:
+     * the entity's primary key field(s), followed by `__mj_CreatedAt` and `__mj_UpdatedAt`
+     * when those columns exist on the entity's base table.
+     */
+    get DatestampReturnFields() {
+        const result = [...this.PrimaryKeys];
+        const pkNames = new Set(result.map(k => k.Name.trim().toLowerCase()));
+        const createdAt = this.Fields.find(f => !f.IsVirtual && f.IsCreatedAtField && !pkNames.has(f.Name.trim().toLowerCase()));
+        if (createdAt)
+            result.push(createdAt);
+        const updatedAt = this.Fields.find(f => !f.IsVirtual && f.IsUpdatedAtField && !pkNames.has(f.Name.trim().toLowerCase()));
+        if (updatedAt)
+            result.push(updatedAt);
+        return result;
+    }
     /**
      * Returns true if cloning is explicitly enabled for this entity as a ROOT record.
      */
@@ -2379,6 +2802,87 @@ export class EntityInfo extends BaseInfo {
     set _floatCount(value) {
         this.FloatCount = value;
     }
+    /**
+     * Whether field-level security decides anything on this entity: its own
+     * {@link EnableFieldLevelSecurity} flag is on, or an IS-A ancestor's is.
+     *
+     * **Enforcement points gate on this, never on the raw flag.** An IS-A child carries each
+     * ancestor's fields as mirror fields of its own, read from the same row. Gating on the child's
+     * own flag — off on nearly every child, because nobody turns it on there — let a role denied
+     * `Phone` on the parent read it through the child's RunView, load and `GetAll()`. The denied
+     * sets ({@link GetDeniedReadFields} and siblings) carry the ancestor's denials for those mirror
+     * fields; this is the matching gate, so a caller that skips work when it is false never skips
+     * an ancestor's rules.
+     *
+     * The raw flag stays the right question for CONFIGURATION — which entities reconciliation,
+     * CodeGen and the system-user sweeps cover — because the rules themselves live on the entity
+     * that owns the field.
+     */
+    get FieldLevelSecurityApplies() {
+        if (this.EnableFieldLevelSecurity) {
+            return true; // checked first: one boolean for every entity that has it on
+        }
+        if (!this.ParentID) {
+            return false; // one boolean for every entity outside an IS-A chain
+        }
+        // The ancestors are memoized; their flags are read live, so an in-place flip is seen at once.
+        const ancestors = this.liveAncestors();
+        for (let i = 0; i < ancestors.length; i++) {
+            if (ancestors[i].EnableFieldLevelSecurity) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * This entity's IS-A ancestors, nearest first, as {@link ParentEntityInfo} resolves them NOW
+     * rather than the cached {@link ParentChain}. The denied walk ({@link addFieldsDeniedOnParent})
+     * follows the live parent, so the gate and the memo key must too: read from a chain cached
+     * before a metadata refresh replaced an ancestor, the gate could answer "no" while the
+     * ancestor now in place has rules, and every enforcement point would skip them.
+     *
+     * The walk is memoized, valid while the field-security generation (which moves whenever any
+     * `EntityInfo` is built, so a rebuilt ancestor is noticed), the provider this entity resolves
+     * its parent through (its owning provider, else the global one), that provider's entity array
+     * and this entity's `ParentID` are unchanged. Ancestors resolve their own parents through
+     * their own providers; a chain whose entities came from one provider, the only way providers
+     * build them, is covered by that provider's array. A walk cut
+     * short because a `ParentID` did not resolve (asked before the provider held its entities) is
+     * returned but not kept, so it cannot pin an incomplete answer.
+     */
+    liveAncestors() {
+        if (!this.ParentID) {
+            return NO_ANCESTORS;
+        }
+        const provider = MetadataProviderFor(this); // the provider ParentEntityInfo resolves through
+        const entities = provider?.Entities;
+        const memo = this._liveAncestorsMemo;
+        if (memo !== null && memo.generation === _fieldSecurityGeneration && memo.provider === provider
+            && memo.entities === entities && memo.parentID === this.ParentID) {
+            return memo.ancestors;
+        }
+        const generation = _fieldSecurityGeneration;
+        const { ancestors, complete } = this.walkLiveAncestors();
+        if (complete) {
+            this._liveAncestorsMemo = { generation, provider, entities, parentID: this.ParentID, ancestors };
+        }
+        return ancestors;
+    }
+    /** The uncached walk behind {@link liveAncestors}; stops at the root or at a cycle. */
+    walkLiveAncestors() {
+        const ancestors = [];
+        const visited = new Set([this]);
+        let current = this;
+        let ancestor = this.ParentEntityInfo;
+        while (ancestor && !visited.has(ancestor)) {
+            visited.add(ancestor);
+            ancestors.push(ancestor);
+            current = ancestor;
+            ancestor = ancestor.ParentID ? ancestor.ParentEntityInfo : null;
+        }
+        const complete = !current.ParentID || ancestor !== null;
+        return { ancestors: Object.freeze(ancestors), complete };
+    }
     /**
      * The set of field names this user may NOT READ on this entity — the per-request primitive
      * every field-security enforcement point is built on.
@@ -2389,12 +2893,13 @@ export class EntityInfo extends BaseInfo {
      * re-scans `user.UserRoles` and allocates. A Set lookup costs neither.
      *
      * Names are lowercased so callers can match case-insensitively, consistent with
-     * {@link ProjectRowsToFields}. Returns an EMPTY set — never null — both when the entity has
-     * field security switched off and when the user is denied nothing, so callers can treat
+     * {@link ProjectRowsToFields}. Returns an EMPTY set — never null — both when field security
+     * does not apply (see {@link FieldLevelSecurityApplies}) and when the user is denied nothing,
+     * so callers can treat
      * `size === 0` as the single "nothing to do" condition.
      */
     GetDeniedReadFields(user) {
-        return this.getDeniedFields(user, (p) => !p.CanRead);
+        return this.getCachedDeniedFields(user, 'read', (p) => !p.CanRead);
     }
     /**
      * Whether this user may READ the named field — the single-field question, answered the same
@@ -2410,10 +2915,10 @@ export class EntityInfo extends BaseInfo {
      * The caller still decides what to render in place of the value, which is the part that
      * differs per surface and should not be hidden inside a getter.
      *
-     * **Fails open** on a missing user, a missing field name, or an entity with field security
-     * switched off — matching `BaseEntity`'s own gate and `MjFormFieldComponent`. The server is
-     * the real boundary; a UI that blanked out fields because no user had resolved yet would be
-     * worse than one that shows them.
+     * **Fails open** on a missing user, a missing field name, or an entity where field security
+     * does not apply ({@link FieldLevelSecurityApplies}) — matching `BaseEntity`'s own gate and
+     * `MjFormFieldComponent`. The server is the real boundary; a UI that blanked out fields
+     * because no user had resolved yet would be worse than one that shows them.
      *
      * PERFORMANCE: this delegates to {@link GetDeniedReadFields}, which walks every field on the
      * entity. Fine for the handful of chrome reads it exists for; do NOT call it per row in a
@@ -2423,7 +2928,7 @@ export class EntityInfo extends BaseInfo {
      * @param user the acting user
      */
     IsFieldReadableByUser(fieldName, user) {
-        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+        if (!this.FieldLevelSecurityApplies || !fieldName || !user) {
             return true;
         }
         return !this.GetDeniedReadFields(user).has(fieldName.trim().toLowerCase());
@@ -2435,7 +2940,7 @@ export class EntityInfo extends BaseInfo {
      * three conditions.
      */
     IsFieldUpdatableByUser(fieldName, user) {
-        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+        if (!this.FieldLevelSecurityApplies || !fieldName || !user) {
             return true;
         }
         return !this.GetDeniedUpdateFields(user).has(fieldName.trim().toLowerCase());
@@ -2449,7 +2954,7 @@ export class EntityInfo extends BaseInfo {
      * the user typed, which is the case this exists to prevent.
      */
     IsFieldCreatableByUser(fieldName, user) {
-        if (!this.EnableFieldLevelSecurity || !fieldName || !user) {
+        if (!this.FieldLevelSecurityApplies || !fieldName || !user) {
             return true;
         }
         return !this.GetDeniedCreateFields(user).has(fieldName.trim().toLowerCase());
@@ -2463,7 +2968,7 @@ export class EntityInfo extends BaseInfo {
      * actually need rather than relying on that.
      */
     GetDeniedUpdateFields(user) {
-        return this.getDeniedFields(user, (p) => !p.CanUpdate);
+        return this.getCachedDeniedFields(user, 'update', (p) => !p.CanUpdate);
     }
     /**
      * The set of field names this user may NOT supply a value for when CREATING a record. Same
@@ -2473,11 +2978,69 @@ export class EntityInfo extends BaseInfo {
      * create-denied field is dropped and the column takes its default.
      */
     GetDeniedCreateFields(user) {
-        return this.getDeniedFields(user, (p) => !p.CanCreate);
+        return this.getCachedDeniedFields(user, 'create', (p) => !p.CanCreate);
+    }
+    /**
+     * Discards the memoized field-security answers: this entity's denied-field sets, those of
+     * every IS-A descendant, and every other memo keyed on the field-security generation
+     * ({@link CurrentFieldSecurityGeneration}), such as a user's denial profile across a catalog.
+     * Invalidation is process-wide because a rule on one entity can change answers about others.
+     *
+     * A metadata refresh needs no call: it builds new `EntityInfo` objects, which start with
+     * empty memos. Call this only after changing field rules IN PLACE on an existing
+     * `EntityInfo`, for example editing an {@link EntityFieldPermissionInfo}'s access values.
+     */
+    InvalidateFieldSecurityCache() {
+        advanceFieldSecurityGeneration();
+    }
+    /**
+     * Memoized front for {@link getDeniedFields}, per (entity, user, verb).
+     *
+     * An entry is reused while four things are unchanged: the field-security generation (see
+     * {@link CurrentFieldSecurityGeneration}; it moves on every rebuild, flag assignment and
+     * {@link InvalidateFieldSecurityCache}), the IS-A ancestors as they resolve now, the field
+     * array itself, and the role IDs the user holds. Counting fields or rules is not enough:
+     * editing a rule from `Allow` to `Deny` changes neither count.
+     */
+    getCachedDeniedFields(user, verb, isDenied) {
+        if (!this.FieldLevelSecurityApplies) {
+            return new Set(); // gate on inheritance too: an ancestor's rules still apply
+        }
+        if (!user || typeof user !== 'object') {
+            return this.getDeniedFields(user, verb, isDenied);
+        }
+        const entry = this.deniedFieldsMemoEntryFor(user);
+        const existing = entry[verb];
+        if (existing !== undefined) {
+            return existing;
+        }
+        const computed = this.getDeniedFields(user, verb, isDenied);
+        entry[verb] = computed;
+        return computed;
+    }
+    /** The current memo entry for `user`, replaced with an empty one when any part of its key moved. */
+    deniedFieldsMemoEntryFor(user) {
+        const generation = _fieldSecurityGeneration;
+        const ancestors = this.liveAncestors();
+        const rolesKey = userRolesKey(user);
+        let byUser = _entityDeniedFieldsCache.get(this);
+        if (!byUser) {
+            byUser = new WeakMap();
+            _entityDeniedFieldsCache.set(this, byUser);
+        }
+        let entry = byUser.get(user);
+        if (!entry || entry.fieldsRef !== this._fields || entry.generation !== generation
+            || !sameAncestors(entry.ancestors, ancestors) || entry.rolesKey !== rolesKey) {
+            entry = { fieldsRef: this._fields, generation, ancestors, rolesKey };
+            byUser.set(user, entry);
+        }
+        return entry;
     }
     /**
      * Shared walk behind {@link GetDeniedReadFields} / {@link GetDeniedUpdateFields} /
-     * {@link GetDeniedCreateFields}, short-circuiting on {@link EnableFieldLevelSecurity}.
+     * {@link GetDeniedCreateFields}. Walks this entity's own fields when its
+     * {@link EnableFieldLevelSecurity} is on, then adds the fields an IS-A parent denies (see
+     * {@link addFieldsDeniedOnParent}).
      *
      * Every field is aggregated, including those carrying no permission records — on an enabled
      * entity those are denied. Unrestrictable fields (primary keys, `__mj_` columns) come back
@@ -2500,18 +3063,54 @@ export class EntityInfo extends BaseInfo {
      * that collide on `CodeName` already collide on their generated property, which is not a
      * schema CodeGen can emit.
      */
-    getDeniedFields(user, isDenied) {
+    getDeniedFields(user, verb, isDenied) {
         const denied = new Set();
-        if (!this.EnableFieldLevelSecurity) {
-            return denied;
+        if (this.EnableFieldLevelSecurity) {
+            for (const field of this._fields) {
+                if (isDenied(field.GetUserFieldPermissions(user, true))) {
+                    this.addDeniedField(denied, field);
+                }
+            }
+        }
+        this.addFieldsDeniedOnParent(denied, user, verb, isDenied);
+        return denied;
+    }
+    /**
+     * IS-A inheritance for the denied sets: a field the immediate parent denies is denied on this
+     * entity's mirror of it, whatever this entity's own flag says. The parent's set already
+     * includes ITS parent's denials (this method runs there too), so one hop covers any depth.
+     *
+     * A mirror is a field of this entity whose `Name` is the `Name` of one of the parent's own
+     * fields: an IS-A child's view exposes each parent column under the parent's column name, and
+     * a child cannot declare a column of its own with that name. Matching goes through the
+     * parent's field list rather than straight into the parent's denied set, because that set also
+     * holds each denied field's `CodeName`: a parent field `Base Salary` puts `base_salary` in it,
+     * and a child's OWN field named `Base_Salary` must not be denied for that.
+     *
+     * Additive only. When this entity ALSO has field security on, a mirror with no rows of its own
+     * is already denied by the walk above (no rows on an enabled entity means denied); the parent's
+     * rules cannot re-open it.
+     */
+    addFieldsDeniedOnParent(denied, user, verb, isDenied) {
+        const parent = this.ParentEntityInfo;
+        if (!parent?.FieldLevelSecurityApplies) {
+            return;
+        }
+        const parentDenied = parent.getCachedDeniedFields(user, verb, isDenied);
+        if (parentDenied.size === 0) {
+            return;
         }
         for (const field of this._fields) {
-            if (isDenied(field.GetUserFieldPermissions(user, true))) {
-                denied.add(field.Name.trim().toLowerCase());
-                denied.add(field.CodeName.trim().toLowerCase());
+            const parentField = parent.FieldByName(field.Name);
+            if (parentField && parentDenied.has(parentField.Name.trim().toLowerCase())) {
+                this.addDeniedField(denied, field);
             }
         }
-        return denied;
+    }
+    /** Adds a field under BOTH key spaces — see {@link getDeniedFields} for why. */
+    addDeniedField(denied, field) {
+        denied.add(field.Name.trim().toLowerCase());
+        denied.add(field.CodeName.trim().toLowerCase());
     }
     /**
      * O(1) case-insensitive field lookup by name. Use this instead of `Fields.find(f => f.Name === name)`
@@ -2528,8 +3127,9 @@ export class EntityInfo extends BaseInfo {
         if (name == null)
             return undefined;
         if (this._fieldByNameMap === null) {
+            const fields = this._fields ?? this.Fields ?? [];
             const map = new Map();
-            for (const f of this._fields) {
+            for (const f of fields) {
                 if (f.Name != null)
                     map.set(f.Name.trim().toLowerCase(), f);
             }
@@ -2537,6 +3137,62 @@ export class EntityInfo extends BaseInfo {
         }
         return this._fieldByNameMap.get(name.trim().toLowerCase());
     }
+    ensureFieldIndexEntry() {
+        const fields = this._fields ?? this.Fields ?? [];
+        let entry = _entityFieldIndexCache.get(this);
+        if (!entry || entry.fieldsRef !== fields || entry.fieldsLen !== fields.length) {
+            const byName = new Map();
+            const byCodeName = new Map();
+            for (let i = 0; i < fields.length; i++) {
+                const f = fields[i];
+                if (f.Name != null) {
+                    const nameKey = f.Name.trim().toLowerCase();
+                    if (!byName.has(nameKey)) {
+                        byName.set(nameKey, i);
+                    }
+                    const rawCodeName = f.CodeName ?? f.Name;
+                    const codeKey = rawCodeName.trim().toLowerCase();
+                    if (!byCodeName.has(codeKey)) {
+                        byCodeName.set(codeKey, i);
+                    }
+                }
+            }
+            entry = { fieldsRef: fields, fieldsLen: fields.length, byName, byCodeName };
+            _entityFieldIndexCache.set(this, entry);
+        }
+        return entry;
+    }
+    /**
+     * O(1) case-insensitive lookup of a field's positional index in `Fields` by `Name`.
+     * Shared across all `BaseEntity` instances of this `EntityInfo` so individual entity
+     * instances do not need to allocate their own `Map<string, EntityField>` on hydration.
+     */
+    FieldIndexByName(name) {
+        if (!name)
+            return -1;
+        return this.ensureFieldIndexEntry().byName.get(name.trim().toLowerCase()) ?? -1;
+    }
+    /**
+     * O(1) case-insensitive lookup of a field's positional index in `Fields` by `CodeName`.
+     */
+    FieldIndexByCodeName(codeName) {
+        if (!codeName)
+            return -1;
+        return this.ensureFieldIndexEntry().byCodeName.get(codeName.trim().toLowerCase()) ?? -1;
+    }
+    /**
+     * O(1) case-insensitive field lookup by `CodeName`. Uses the shared `_entityFieldIndexCache`
+     * index so GraphQL resolvers and mutation handlers can resolve client `CodeName` keys without
+     * linear `Fields.find(...)` scans.
+     *
+     * @param codeName field CodeName (matched case-insensitively, whitespace-trimmed)
+     * @returns the matching EntityFieldInfo, or undefined if not found
+     */
+    FieldByCodeName(codeName) {
+        const idx = this.FieldIndexByCodeName(codeName);
+        const fields = this._fields ?? this.Fields;
+        return idx >= 0 && fields ? fields[idx] : undefined;
+    }
     /**
      * Returns the primary key field for the entity. For entities with a composite primary key, use the PrimaryKeys property which returns all.
      * In the case of a composite primary key, the PrimaryKey property will return the first field in the sequence of the primary key fields.
@@ -2715,6 +3371,53 @@ export class EntityInfo extends BaseInfo {
     get OrganicKeys() {
         return this._organicKeys;
     }
+    /**
+     * Gets all registered alternate base views for this entity, sorted by `Sequence`, `Name`, and `ID`.
+     * Alternate base views maintain 100% column parity with {@link BaseView} while applying a
+     * curated canonical filter or join.
+     * @returns {EntityAlternateBaseViewInfo[]} Array of alternate base view metadata definitions
+     */
+    get AlternateBaseViews() {
+        return this._alternateBaseViews;
+    }
+    /**
+     * Finds a registered alternate base view on this entity by its semantic `Name`
+     * (case-insensitive, whitespace-trimmed).
+     *
+     * @param name Semantic name of the alternate base view (for example, `'Active'`).
+     * @returns The matching {@link EntityAlternateBaseViewInfo}, or `undefined` if not found.
+     */
+    GetAlternateBaseView(name) {
+        const trimmed = name?.trim().toLowerCase();
+        if (!trimmed) {
+            return undefined;
+        }
+        return this._alternateBaseViews.find(v => v.Name?.trim().toLowerCase() === trimmed);
+    }
+    /**
+     * Finds a registered alternate base view on this entity by its physical SQL `ViewName`
+     * (and optional `schemaName`), matched case-insensitively and whitespace-trimmed.
+     *
+     * @param viewName Physical SQL view name (for example, `'vwActiveMembers'`).
+     * @param schemaName Optional schema name; when supplied, must match `EffectiveSchemaName` case-insensitively.
+     * @returns The matching {@link EntityAlternateBaseViewInfo}, or `undefined` if not found.
+     */
+    GetAlternateBaseViewByViewName(viewName, schemaName) {
+        const trimmedView = viewName?.trim().toLowerCase();
+        if (!trimmedView) {
+            return undefined;
+        }
+        const trimmedSchema = schemaName?.trim().toLowerCase();
+        return this._alternateBaseViews.find(v => {
+            if (v.ViewName?.trim().toLowerCase() !== trimmedView) {
+                return false;
+            }
+            if (trimmedSchema && trimmedSchema.length > 0) {
+                return v.EffectiveSchemaName.trim().toLowerCase() === trimmedSchema;
+            }
+            return true;
+        });
+    }
     static { this.__createdAtFieldName = '__mj_CreatedAt'; }
     static { this.__updatedAtFieldName = '__mj_UpdatedAt'; }
     static { this.__deletedAtFieldName = '__mj_DeletedAt'; }
@@ -2859,7 +3562,7 @@ export class EntityInfo extends BaseInfo {
     get ParentEntityInfo() {
         if (!this.ParentID)
             return null;
-        const p = Metadata.Provider; // global-provider-ok: stateless info class — proxies to global metadata
+        const p = MetadataProviderFor(this);
         if (p?.EntityByID) {
             return p.EntityByID(this.ParentID) ?? null;
         }
@@ -2875,7 +3578,23 @@ export class EntityInfo extends BaseInfo {
      * only one child type is allowed per parent record (disjoint subtypes).
      */
     get ChildEntities() {
-        return Metadata.Provider?.Entities?.filter(e => UUIDsEqual(e.ParentID, this.ID)) ?? []; // global-provider-ok: stateless info class — proxies to global metadata
+        const provider = MetadataProviderFor(this);
+        const entities = provider?.Entities;
+        if (!entities || entities.length === 0) {
+            return [];
+        }
+        const cached = _entityChildEntitiesCache.get(this);
+        if (cached && cached.provider === provider && cached.entitiesRef === entities && cached.entitiesLen === entities.length) {
+            return cached.children;
+        }
+        const children = entities.filter(e => UUIDsEqual(e.ParentID, this.ID));
+        _entityChildEntitiesCache.set(this, {
+            provider,
+            entitiesRef: entities,
+            entitiesLen: entities.length,
+            children,
+        });
+        return children;
     }
     /**
      * Convenience alias: returns true when this entity is a parent type that allows
@@ -2889,22 +3608,33 @@ export class EntityInfo extends BaseInfo {
      * Walks the IS-A chain upward from this entity to the root, returning all parent entities.
      * Does NOT include this entity itself.
      * Example: For Webinars (IS-A Meetings IS-A Products), returns [Meetings, Products].
-     * Results are cached after first computation for performance.
+     * Results are cached after first computation for performance — but only a COMPLETE chain:
+     * one that ends at an entity with no parent, or at a cycle. A walk cut short because a
+     * `ParentID` did not resolve (asked before the provider had its entities) is returned but not
+     * kept, so it cannot pin an incomplete answer; field security reads this chain to decide
+     * whether an ancestor's rules apply.
      */
     get ParentChain() {
         if (this._parentChainCache !== null)
             return this._parentChainCache;
         const chain = [];
         let current = this.ParentEntityInfo;
+        let complete = !this.ParentID || current !== null;
         const visited = new Set(); // circular reference protection
         while (current) {
             if (visited.has(current.ID))
                 break; // prevent infinite loop
             visited.add(current.ID);
             chain.push(current);
-            current = current.ParentEntityInfo;
+            const next = current.ParentEntityInfo;
+            if (current.ParentID && !next) {
+                complete = false;
+            }
+            current = next;
+        }
+        if (complete) {
+            this._parentChainCache = chain;
         }
-        this._parentChainCache = chain;
         return chain;
     }
     /**
@@ -3048,23 +3778,21 @@ export class EntityInfo extends BaseInfo {
      */
     GetUserPermisions(user) {
         try {
-            const permissionList = [];
-            for (let j = 0; j < this.Permissions.length; j++) {
-                const ep = this.Permissions[j];
-                const roleMatch = user.UserRoles?.find((r) => UUIDsEqual(r.RoleID, ep.RoleID));
-                if (roleMatch) // user has this role
-                    permissionList.push(ep);
-            }
-            // Aggregate Allow and Deny separately, then subtract Deny from Allow per action.
+            const _ = user.UserRoles; // preserve throw-on-null behavior
+            const userRoleIds = getUserRoleIdSet(user);
             const allow = { CanCreate: false, CanRead: false, CanUpdate: false, CanDelete: false };
             const deny = { CanCreate: false, CanRead: false, CanUpdate: false, CanDelete: false };
-            for (const ep of permissionList) {
-                const isDeny = ep.IsDeny;
-                const bucket = isDeny ? deny : allow;
-                bucket.CanCreate = bucket.CanCreate || !!ep.CanCreate;
-                bucket.CanRead = bucket.CanRead || !!ep.CanRead;
-                bucket.CanUpdate = bucket.CanUpdate || !!ep.CanUpdate;
-                bucket.CanDelete = bucket.CanDelete || !!ep.CanDelete;
+            if (userRoleIds.size > 0) {
+                for (let j = 0; j < this.Permissions.length; j++) {
+                    const ep = this.Permissions[j];
+                    if (ep.RoleID && userRoleIds.has(ep.RoleID.trim().toLowerCase())) {
+                        const bucket = ep.IsDeny ? deny : allow;
+                        bucket.CanCreate = bucket.CanCreate || !!ep.CanCreate;
+                        bucket.CanRead = bucket.CanRead || !!ep.CanRead;
+                        bucket.CanUpdate = bucket.CanUpdate || !!ep.CanUpdate;
+                        bucket.CanDelete = bucket.CanDelete || !!ep.CanDelete;
+                    }
+                }
             }
             // An API-driven action also requires that the entity ALLOWS that action at all
             // (`Allow*API`). No role grant can create/update/delete records of an entity whose
@@ -3084,6 +3812,45 @@ export class EntityInfo extends BaseInfo {
             return null;
         }
     }
+    /**
+     * Checks whether the specified user has the requested permission (`Read`, `Create`, `Update`, or `Delete`)
+     * on this entity. When `this.Permissions` is empty/uninitialized (e.g., in lightweight unit-test fixtures),
+     * returns `true` so unconfigured fixtures are not blocked.
+     */
+    CheckPermissions(user, type, throwError = false) {
+        if (!user || !this.Permissions || this.Permissions.length === 0) {
+            return true;
+        }
+        const perms = this.GetUserPermisions(user);
+        if (!perms) {
+            if (throwError) {
+                throw new Error(`Permission check failed for user on entity ${this.Name}`);
+            }
+            return false;
+        }
+        let allowed = false;
+        switch (type) {
+            case EntityPermissionType.Read:
+                allowed = perms.CanRead;
+                break;
+            case EntityPermissionType.Create:
+                allowed = perms.CanCreate;
+                break;
+            case EntityPermissionType.Update:
+                allowed = perms.CanUpdate;
+                break;
+            case EntityPermissionType.Delete:
+                allowed = perms.CanDelete;
+                break;
+            default:
+                allowed = false;
+                break;
+        }
+        if (!allowed && throwError) {
+            throw new Error(`User does not have ${type} permission on ${this.Name}`);
+        }
+        return allowed;
+    }
     /**
      * Determines if a given user, for a given permission type, is exempt from RowLevelSecurity or not.
      *
@@ -3099,13 +3866,17 @@ export class EntityInfo extends BaseInfo {
      * @returns
      */
     UserExemptFromRowLevelSecurity(user, type) {
+        const _ = user.UserRoles; // preserve throw-on-null behavior if user is null/undefined
+        const userRoleIds = getUserRoleIdSet(user);
+        if (userRoleIds.size === 0) {
+            return false;
+        }
         for (let j = 0; j < this.Permissions.length; j++) {
             const ep = this.Permissions[j];
             if (ep.IsDeny) {
                 continue; // a Deny row's Can* flags are denials, never grants — it cannot exempt anyone
             }
-            const roleMatch = user.UserRoles?.find((r) => UUIDsEqual(r.RoleID, ep.RoleID));
-            if (roleMatch) { // user has this role 
+            if (ep.RoleID && userRoleIds.has(ep.RoleID.trim().toLowerCase())) { // user has this role 
                 switch (type) {
                     case EntityPermissionType.Create:
                         if (ep.CanCreate && !ep.CreateRLSFilterID)
@@ -3146,14 +3917,18 @@ export class EntityInfo extends BaseInfo {
      * @returns
      */
     GetUserRowLevelSecurityInfo(user, type) {
+        const _ = user.UserRoles; // preserve throw-on-null behavior if user is null/undefined
         const rlsList = [];
+        const userRoleIds = getUserRoleIdSet(user);
+        if (userRoleIds.size === 0) {
+            return rlsList;
+        }
         for (let j = 0; j < this.Permissions.length; j++) {
             const ep = this.Permissions[j];
             if (ep.IsDeny) {
                 continue; // never a grant — see the doc comment
             }
-            const roleMatch = user.UserRoles?.find((r) => UUIDsEqual(r.RoleID, ep.RoleID));
-            if (roleMatch) { // user has this role
+            if (ep.RoleID && userRoleIds.has(ep.RoleID.trim().toLowerCase())) { // user has this role
                 let matchObject = null;
                 switch (type) {
                     case EntityPermissionType.Create:
@@ -3269,7 +4044,7 @@ export class EntityInfo extends BaseInfo {
         const clauses = [...mine]
             .sort((a, b) => a.FilterID.localeCompare(b.FilterID)) // deterministic order for the cache fingerprint (INV-2)
             .map(b => {
-            const filter = Metadata.Provider.RowLevelSecurityFilters.find(f => UUIDsEqual(f.ID, b.FilterID)); // global-provider-ok: same resolution path as RLSFilter() above — stateless info class proxying to global metadata
+            const filter = MetadataProviderFor(this)?.RowLevelSecurityFilters?.find(f => UUIDsEqual(f.ID, b.FilterID));
             if (!filter) {
                 LogError(`API-key row filter ${b.FilterID} for entity ${this.Name} not found in metadata — resolving to (1=0)`);
                 return '(1=0)';
@@ -3441,7 +4216,7 @@ export class EntityInfo extends BaseInfo {
         const conditions = [];
         // Resolve the spoke entity's own organic key (matching by Name) to pull its
         // per-column normalization. Falls back to the hub's expression if not found.
-        const spokeOrganicKey = EntityInfo.resolveSpokeOrganicKey(relatedEntity, organicKey);
+        const spokeOrganicKey = EntityInfo.resolveSpokeOrganicKey(relatedEntity, organicKey, record.EntityInfo?.OwningProvider);
         for (let i = 0; i < matchFields.length; i++) {
             const value = record.Get(matchFields[i]);
             if (value == null) {
@@ -3565,7 +4340,21 @@ export class EntityInfo extends BaseInfo {
             default: return `'${escapedValue}'`;
         }
     }
-    constructor(initData = null) {
+    static { this.CHILD_INIT_KEYS = new Set([
+        'EntityFields', '_Fields', 'Fields',
+        'EntityPermissions', '_Permissions', 'Permissions',
+        'EntitySettings', '_Settings', 'Settings',
+        'EntityRelationships', '_RelatedEntities', 'RelatedEntities',
+        'EntityOrganicKeys', '_OrganicKeys', 'OrganicKeys',
+        'EntityAlternateBaseViews', '_AlternateBaseViews', 'AlternateBaseViews',
+    ]); }
+    /**
+     * @param initData - the raw entity row (or another EntityInfo being re-instantiated)
+     * @param md - the provider that owns this metadata. Sibling lookups ({@link ParentEntityInfo},
+     *   {@link ChildEntities}, RLS filters) resolve through it rather than the global provider, so
+     *   they stay correct in a multi-provider process. Optional for backward compatibility.
+     */
+    constructor(initData = null, md) {
         super();
         /**
          * Unique identifier for the entity
@@ -3715,19 +4504,7 @@ export class EntityInfo extends BaseInfo {
          * client-side IndexedDB cache. Zero overhead on hot save/query paths.
          */
         this.AllowCaching = false;
-        /**
-         * Whether field-level (column-level) security is enforced for this entity.
-         *
-         * This is the single gate every field-security enforcement point checks first, and it is
-         * explicit — never inferred from whether permission rows happen to exist. It is `false` for
-         * nearly every entity in nearly every deployment, so enforcement collapses to one boolean
-         * test: no field iteration, no aggregation, no allocation.
-         *
-         * Turning it on snapshots the entity's existing entity-level permissions into per-field
-         * rows, so enabling changes no behavior until an administrator tightens a field. Turning it
-         * off leaves the rows in place, inactive, so re-enabling does not lose the configuration.
-         */
-        this.EnableFieldLevelSecurity = false;
+        this._enableFieldLevelSecurity = false;
         /**
          * Whether this entity is available through the GraphQL API
          */
@@ -4019,6 +4796,7 @@ export class EntityInfo extends BaseInfo {
         this.ParentBaseView = null;
         this._fieldCategories = null;
         this._organicKeys = [];
+        this._alternateBaseViews = [];
         this.HasIdField = false;
         this.VirtualCount = 0;
         this.ManyToManyCount = 0;
@@ -4039,14 +4817,20 @@ export class EntityInfo extends BaseInfo {
         this._nameFieldCache = undefined;
         /** Memoized computed plural, keyed by the display name it was derived from (see `DisplayNamePlural`). */
         this._displayNamePluralCache = undefined;
+        /** See {@link liveAncestors}. A `_` field with no matching getter, so `toJSON()` leaves it out. */
+        this._liveAncestorsMemo = null;
         this._hasInactiveFields = undefined;
         this._hasSearchFields = undefined;
         // Cache for ParentChain to avoid repeated walks
         this._parentChainCache = null;
         // Cache for ParentEntityFieldNames
         this._parentEntityFieldNamesCache = null;
+        // A new entity can replace one that memoized field-security answers point at (a metadata
+        // refresh, an IS-A ancestor rebuilt), so building one moves the generation.
+        advanceFieldSecurityGeneration();
+        this.SetOwningProvider(md);
         if (initData) {
-            this.copyInitData(initData);
+            this.copyInitData(initData, EntityInfo.CHILD_INIT_KEYS);
             // do some special handling to create class instances instead of just data objects
             // copy the Entity Fields (accept EntityFields, _Fields, or Fields as input names)
             this._fields = [];
@@ -4077,7 +4861,9 @@ export class EntityInfo extends BaseInfo {
             const ef = initData.EntityFields || initData._Fields || initData.Fields;
             if (ef) {
                 for (let j = 0; j < ef.length; j++) {
-                    this._fields.push(new EntityFieldInfo(ef[j]));
+                    const field = new EntityFieldInfo(ef[j]);
+                    field.SetOwningProvider(md);
+                    this._fields.push(field);
                 }
             }
             // copy the Entity Permissions
@@ -4085,7 +4871,7 @@ export class EntityInfo extends BaseInfo {
             const ep = initData.EntityPermissions || initData._Permissions || initData.Permissions;
             if (ep) {
                 for (let j = 0; j < ep.length; j++) {
-                    this._permissions.push(new EntityPermissionInfo(ep[j]));
+                    this._permissions.push(new EntityPermissionInfo(ep[j], md));
                 }
             }
             // copy the Entity settings
@@ -4131,6 +4917,22 @@ export class EntityInfo extends BaseInfo {
                     this._organicKeys.push(new EntityOrganicKeyInfo(item));
                 }
             }
+            // copy the Alternate Base Views (sorted by Sequence, Name, ID, then linked via ParentID)
+            this._alternateBaseViews = [];
+            const abv = initData.EntityAlternateBaseViews || initData._AlternateBaseViews || initData.AlternateBaseViews;
+            if (abv && Array.isArray(abv)) {
+                for (const item of abv) {
+                    const viewInfo = new EntityAlternateBaseViewInfo(item, this.SchemaName);
+                    viewInfo.SetOwningProvider(md);
+                    this._alternateBaseViews.push(viewInfo);
+                }
+                this._alternateBaseViews.sort((a, b) => {
+                    const aSeq = a.Sequence !== null && a.Sequence !== undefined ? a.Sequence : 0;
+                    const bSeq = b.Sequence !== null && b.Sequence !== undefined ? b.Sequence : 0;
+                    return (aSeq - bSeq) || ordinalCompare(a.Name, b.Name) || ordinalCompare(a.ID, b.ID);
+                });
+                EntityAlternateBaseViewInfo.LinkHierarchy(this._alternateBaseViews, this.SchemaName);
+            }
             this.prepareSpecialFields();
         }
     }