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

package/dist/generic/entityInfo.js

@@ -1,5 +1,6 @@
 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";
@@ -369,9 +370,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 +406,7 @@ export class EntityPermissionInfo extends BaseInfo {
         this.CreateRLSFilter = null;
         this.UpdateRLSFilter = null;
         this.DeleteRLSFilter = null;
+        this.SetOwningProvider(md);
         this.copyInitData(initData);
     }
 }
@@ -927,14 +933,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 +979,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 +1472,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 +1502,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 +1519,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 +1652,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 +2040,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 +2048,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 +2136,99 @@ 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();
+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.
  */
@@ -2139,6 +2271,11 @@ export class EntitySettingInfo extends BaseInfo {
  * Catalog of all entities across all schemas.
  * Contains comprehensive metadata about each entity including its database mappings, security settings, and UI preferences.
  */
+/** Backing list for {@link EntityInfo.ConfigurableAtCreationAttributes}. */
+const ENTITY_CONFIGURABLE_AT_CREATION_ATTRIBUTES = [
+    'IncludeInAPI', 'AllowUserSearchAPI', 'AllowCaching', 'TrackRecordChanges', 'AuditRecordAccess',
+    'AuditViewRuns', 'AllowAllRowsAPI', 'AllowCreateAPI', 'AllowUpdateAPI', 'AllowDeleteAPI', 'UserViewMaxRows',
+];
 export class EntityInfo extends BaseInfo {
     /**
      * The view CodeGen actually WRITES for this entity.
@@ -2322,6 +2459,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.
      */
@@ -2389,7 +2550,7 @@ export class EntityInfo extends BaseInfo {
      * `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
@@ -2458,7 +2619,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
@@ -2468,7 +2629,49 @@ 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);
+    }
+    getCachedDeniedFields(user, verb, isDenied) {
+        if (!this.EnableFieldLevelSecurity) {
+            return new Set();
+        }
+        if (!user || typeof user !== 'object') {
+            return this.getDeniedFields(user, isDenied);
+        }
+        let totalPerms = 0;
+        for (let i = 0; i < this._fields.length; i++) {
+            totalPerms += this._fields[i].FieldPermissions.length;
+        }
+        const rolesRef = user.UserRoles;
+        const rolesLen = rolesRef?.length ?? 0;
+        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.fieldsLen !== this._fields.length ||
+            entry.totalPerms !== totalPerms ||
+            entry.rolesRef !== rolesRef ||
+            entry.rolesLen !== rolesLen) {
+            entry = {
+                fieldsRef: this._fields,
+                fieldsLen: this._fields.length,
+                totalPerms,
+                rolesRef,
+                rolesLen,
+            };
+            byUser.set(user, entry);
+        }
+        const existing = entry[verb];
+        if (existing !== undefined) {
+            return existing;
+        }
+        const computed = this.getDeniedFields(user, isDenied);
+        entry[verb] = computed;
+        return computed;
     }
     /**
      * Shared walk behind {@link GetDeniedReadFields} / {@link GetDeniedUpdateFields} /
@@ -2523,8 +2726,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);
             }
@@ -2532,6 +2736,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.
@@ -2731,6 +2991,14 @@ export class EntityInfo extends BaseInfo {
     static get DeletedAtFieldName() {
         return EntityInfo.__deletedAtFieldName;
     }
+    /**
+     * Entity flags that a per-table entry in CodeGen's additionalSchemaInfo config may set when CodeGen first
+     * creates the entity, overriding the global `newEntityDefaults`. Typed against `EntityInfo`, so a name that
+     * stops being an entity property fails to compile.
+     */
+    static get ConfigurableAtCreationAttributes() {
+        return ENTITY_CONFIGURABLE_AT_CREATION_ATTRIBUTES;
+    }
     /**
      * This static factory method is used to check to see if the entity in question is active or not
      * If it is not active, it will throw an exception or log a warning depending on the status of the entity being
@@ -2846,7 +3114,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;
         }
@@ -2862,7 +3130,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
@@ -3035,23 +3319,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
@@ -3086,13 +3368,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)
@@ -3133,14 +3419,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:
@@ -3256,7 +3546,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)';
@@ -3428,7 +3718,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) {
@@ -3552,7 +3842,20 @@ 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',
+    ]); }
+    /**
+     * @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
@@ -3677,11 +3980,21 @@ export class EntityInfo extends BaseInfo {
          */
         this.AuditViewRuns = null;
         /**
-         * When true (default), the server-side RunView cache will store and return cached results
-         * for this entity, trusting that all mutations flow through BaseEntity.Save() which fires
-         * cache invalidation events. Set to false for entities whose rows are created as side-effects
-         * of other operations via raw SQL (e.g., Record Changes created by spCreateRecordChange_Internal),
-         * since those inserts bypass BaseEntity and never trigger cache invalidation.
+         * Whether every change to this entity's rows fires a `BaseEntity` event. True (the default)
+         * declares that all mutations flow through `BaseEntity.Save()`/`Delete()`, so a cached copy
+         * kept current by those events can be trusted. False declares that rows can change without an
+         * event: raw SQL, a stored procedure (e.g. Record Changes created by
+         * `spCreateRecordChange_Internal`), or another application writing the same table.
+         *
+         * Each cache layer responds to `false` in the way that suits it:
+         * - **Server RunView cache:** does not cache the entity, since re-validating would cost as
+         *   much as running the query.
+         * - **Client RunView cache:** caches as before; every read is validated against the database.
+         * - **Engine caches (`BaseEngine`):** keep the rows, and the engine sweep re-checks them on its
+         *   interval. The user cache and the metadata sweep do the same for their entities.
+         *
+         * To keep an entity out of caching altogether, set {@link AllowCaching} to false instead.
+         * Setting any `AllowDirectSQL*` flag requires this to be false (a database CHECK enforces it).
          */
         this.TrustServerCacheCompletely = true;
         /**
@@ -4022,8 +4335,9 @@ export class EntityInfo extends BaseInfo {
         this._parentChainCache = null;
         // Cache for ParentEntityFieldNames
         this._parentEntityFieldNamesCache = null;
+        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 = [];
@@ -4054,7 +4368,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
@@ -4062,7 +4378,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