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

package/dist/generic/baseEntity.js

@@ -8,7 +8,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var EntityField_1;
-import { Base64DecodedByteLength, DeserializeValidationErrors, Float32VectorToBase64, IsValidBase64, IsMemberOverridden, MJEventType, MJGlobal, NormalizeUUID, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager, ComputeContentHashAsync } from '@memberjunction/global';
+import { Base64DecodedByteLength, DeserializeValidationErrors, Float32VectorToBase64, IsValidBase64, IsMemberOverridden, MJEventType, MJGlobal, NormalizeUUID, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, UserCacheKeySegment, WarningManager, ComputeContentHashAsync } from '@memberjunction/global';
 import { GetDataHooks } from './dataHooks.js';
 import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, FieldSecurityError, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
 import { EntitySubtypeResolver } from './entitySubtypeResolver.js';
@@ -25,6 +25,7 @@ import { EmbeddedRecord } from './embeddedRecord.js';
 import { EntitySavePlan, ExecuteEntitySavePlan } from './entitySavePlan.js';
 import { JSONFieldBinding, ValidateJSONFieldValue } from './jsonFieldBinding.js';
 import { BaseRemotableOperation } from './baseRemotableOperation.js';
+import { OmitDeniedFieldKeys, OmitFieldsUnreadableByActiveUser } from './entityValueFieldSecurity.js';
 import { SAVE_ENTITY_GRAPH_OPERATION_KEY, } from './saveEntityGraphOperation.js';
 import { finalize, firstValueFrom, from, of, shareReplay, Subject, switchMap } from 'rxjs';
 /**
@@ -79,8 +80,9 @@ let EntityField = class EntityField {
      * `InnerLoad` — reusing it would conflate defaults with omissions. This flag is set only
      * by the hydration paths (via {@link MarkNotLoaded}) when a source omits the key, is
      * cleared by ANY explicit set (an intentional blind write to a read-denied field is a
-     * legitimate write-only update and must save), and is never present on new (unhydrated)
-     * entities — their fields legitimately hold metadata defaults for INSERT.
+     * legitimate write-only update and must save). On a new record it marks only the fields the
+     * record's user may not read; every other field legitimately holds its metadata default for
+     * INSERT.
      */
     get NotLoaded() {
         return this._notLoaded;
@@ -92,6 +94,18 @@ let EntityField = class EntityField {
      */
     MarkNotLoaded() {
         this._notLoaded = true;
+        this._writtenAfterNotLoaded = false;
+    }
+    /**
+     * Framework-internal, for the hydration paths: the source omitted this field, so it is
+     * not-loaded AND holds nothing. Unlike {@link MarkNotLoaded}, which only flags the field and keeps
+     * its in-memory value, this drops a default or a previous record's value that would otherwise
+     * read back through Get() as if it had been loaded.
+     */
+    ClearAsNotLoaded() {
+        this._value = null;
+        this._oldValue = null;
+        this.MarkNotLoaded();
     }
     /**
      * True when field-level security bars this user from supplying the field's value on INSERT,
@@ -171,7 +185,18 @@ let EntityField = class EntityField {
         return this._entityFieldInfo.HasDefaultValue;
     }
     /**
-     * Sets the value of the field. If the field is read only, nothing happens. If the field is not read only, the value is set and the internal representation of the dirty flag is flipped if the value is different from the old value.
+     * Sets the value of the field.
+     *
+     * - A read-only field accepts ONE set after construction or {@link ResetNeverSetFlag} (how a
+     *   load populates it); later sets are ignored.
+     * - Dirty state is not stored here: {@link Dirty} compares the value with {@link OldValue} when
+     *   it is read. A set during record setup (the first set of a never-set field) also becomes
+     *   the old value, so it is not dirty.
+     * - A set onto a {@link NotLoaded} field clears that flag and is always dirty, whatever the
+     *   value, even one equal to the field's construction state. The write therefore reaches the
+     *   save and its update-permission check.
+     * - No field-level security or active-status check happens here. Those live at
+     *   `BaseEntity.Get`/`Set` and at the save; this accessor is framework-internal.
      */
     set Value(value) {
         // No active-status assertion here — see the Value getter note. Deprecation/disabled checks
@@ -198,6 +223,9 @@ let EntityField = class EntityField {
             // this field.
             const wasNotLoaded = this._notLoaded;
             this._notLoaded = false;
+            if (wasNotLoaded) {
+                this._writtenAfterNotLoaded = true;
+            }
             // in the below, we set the OldValue, but only if (a) we have never set the value before, or (b) the value or the old value is not null - which means that we are in a record setup scenario
             if (this._neverSet && !wasNotLoaded &&
                 (value !== null || this._oldValue !== null)) {
@@ -215,6 +243,12 @@ let EntityField = class EntityField {
     ResetNeverSetFlag() {
         this._neverSet = true;
     }
+    /**
+     * True when the field has had no explicit write since construction or since {@link ResetNeverSetFlag}.
+     */
+    get NeverSet() {
+        return this._neverSet;
+    }
     /**
      * Returns true if the field is dirty, false otherwise. A field is considered dirty if the value is different from the old value. If the field is read only, it is never dirty.
      * A {@link NotLoaded} field is never dirty either — its in-memory state is a construction
@@ -223,9 +257,11 @@ let EntityField = class EntityField {
     get Dirty() {
         if (this.ReadOnly || this._notLoaded)
             return false;
+        else if (this._writtenAfterNotLoaded)
+            return true; // a write onto a value the record never loaded must reach the save, even null
         else {
             const oldNull = this._oldValue === null || this.OldValue === undefined || Number.isNaN(this.OldValue); // check for NaN because sometimes we have old values that are NaN and we need to account for that
-            const curNull = this.Value === null || this.Value === undefined || Number.isNaN(this.OldValue);
+            const curNull = this.Value === null || this.Value === undefined || Number.isNaN(this.Value);
             if (oldNull && curNull)
                 return false; // BOTH are null or undefined, not dirty
             else {
@@ -239,16 +275,16 @@ let EntityField = class EntityField {
                     // and sometimes the new values are date objects, convert to UTC timestamp for comparison
                     newCompare = this.Value.getTime();
                 }
+                const tsType = this._entityFieldInfo.TSType;
                 // Special handling for bit/Boolean types - treat truthy values as equivalent
-                if (this._entityFieldInfo.TSType === EntityFieldTSType.Boolean ||
-                    this._entityFieldInfo.Type.toLowerCase() === 'bit') {
+                if (tsType === EntityFieldTSType.Boolean) {
                     // Convert both values to boolean for comparison
                     const oldBool = this.convertToBoolean(oldCompare);
                     const newBool = this.convertToBoolean(newCompare);
                     return oldBool !== newBool;
                 }
                 // Special handling for numeric types - treat numeric strings that convert to same value as equivalent
-                if (this._entityFieldInfo.TSType === EntityFieldTSType.Number || this.isNumericType(this._entityFieldInfo.Type)) {
+                if (tsType === EntityFieldTSType.Number) {
                     const oldNum = this.convertToNumber(oldCompare);
                     const newNum = this.convertToNumber(newCompare);
                     // Handle NaN cases - if both are NaN, they're equivalent
@@ -262,7 +298,7 @@ let EntityField = class EntityField {
                     return oldNum !== newNum;
                 }
                 // for string types where the comparisons are not both strings
-                if (this._entityFieldInfo.TSType === EntityFieldTSType.String) {
+                if (tsType === EntityFieldTSType.String) {
                     if (typeof oldCompare === 'object') {
                         // need to convert the object to a string for comparison
                         oldCompare = JSON.stringify(oldCompare);
@@ -370,7 +406,7 @@ let EntityField = class EntityField {
                 }
                 else {
                     // we do have a default value, but our current value is null. If we are in an EXISTING record, this is an error, check the OldValue to determine this
-                    if (this._oldValue !== null && this._oldValue !== undefined) {
+                    if ((this._oldValue !== null && this._oldValue !== undefined) || this._writtenAfterNotLoaded) {
                         result.Success = false;
                         result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} cannot be null`, null));
                     }
@@ -465,9 +501,16 @@ let EntityField = class EntityField {
             result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} cannot be longer than ${ef.MaxByteLength} bytes. Current value is ${byteLength} bytes`, this.Value));
         }
     }
-    constructor(fieldInfo, Value) {
+    constructor(fieldInfo, Value, skipDefaultValue = false) {
         this._neverSet = true;
         this._notLoaded = false;
+        /**
+         * True once the field is explicitly set after being not-loaded: a write onto a value the record
+         * never loaded. The field is then dirty whatever it was set to — even null, which equals its
+         * cleared old value — so the write reaches the save, and Validate treats it as an existing
+         * record's value. Cleared when the old value is reset (load, save) or the field is not-loaded again.
+         */
+        this._writtenAfterNotLoaded = false;
         this._createSuppressed = false;
         // NOTE: constructing an EntityField for a deprecated/disabled field is always allowed — the
         // column is physically part of the entity and the instance must exist. Active-status is
@@ -477,102 +520,51 @@ let EntityField = class EntityField {
         if (Value) {
             this.Value = Value;
         }
-        else if (fieldInfo.DefaultValue) {
-            if (fieldInfo.TSType === EntityFieldTSType.Boolean) {
-                // special handling for booleans as we don't want a string passed into a boolean field, we want a true boolean
-                if (typeof fieldInfo.DefaultValue === "string" && fieldInfo.DefaultValue.trim() === "1" || fieldInfo.DefaultValue.trim().toLowerCase() === "true")
-                    this.Value = true;
-                else
-                    this.Value = false;
-            }
-            else if (fieldInfo.TSType === EntityFieldTSType.Number) {
-                // special handling for numbers as we don't want a string passed into a value for a numeric field
-                if (!isNaN(Number(fieldInfo.DefaultValue))) {
-                    this.Value = Number(fieldInfo.DefaultValue);
-                }
-                else if (fieldInfo.DefaultValue.trim().toLowerCase() === "null") {
-                    this.Value = null;
-                }
-            }
-            else if (fieldInfo.IsUniqueIdentifier) {
-                // special handling for GUIDs (SQL Server `uniqueidentifier` / PostgreSQL `uuid`),
-                // we don't want to populate anything here because the server always sets the value, leave blank
-                this.Value = null;
-            }
-            else if (fieldInfo.TSType === EntityFieldTSType.Date) {
-                if (fieldInfo.DefaultValue.trim().length > 0) {
-                    // special handling for dates as we don't want to use getdate() type defaults as is, we want to convert them to a JS Date object
-                    try {
-                        // attempt to convert the default value to a date
-                        const temp = new Date(fieldInfo.DefaultValue);
-                        // if we get here, that means it worked, but we could have an invalid date, so check for that
-                        if (isNaN(temp.getTime())) {
-                            // this is an invalid date, so throw an error
-                            throw new Error(); // blank error because we just end up going to the catch block anyway and in there we have logic to handle this properly
-                        }
-                        else
-                            this.Value = temp;
-                    }
-                    catch (e) {
-                        // if we get here, that means the default value is not a valid date, so we need to check to see if it's a SQL current date function
-                        if (EntityFieldInfo.IsDefaultValueSQLCurrentDateFunction(fieldInfo.DefaultValue)) {
-                            // we have a SQL current date function default, leave the field alone if its a special date field as the server (i.e. database) will handle
-                            //setting the value, otherwise set the value to the current date
-                            if (fieldInfo.IsSpecialDateField) {
-                                this.Value = null;
-                            }
-                            else {
-                                this.Value = new Date();
-                            }
-                        }
-                        else {
-                            // we have a default value that is not a valid date and not a getdate() type default, so we need to throw an error
-                            throw new Error(`Invalid default value for ${fieldInfo.Entity}.${fieldInfo.Name} of ${fieldInfo.DefaultValue}. Default values for date fields must be a valid date or a getdate() type default`);
-                        }
-                    }
-                }
+        else if (!skipDefaultValue && fieldInfo.DefaultValue) {
+            const parsed = typeof fieldInfo.GetParsedDefaultValue === 'function'
+                ? fieldInfo.GetParsedDefaultValue()
+                : EntityFieldInfo.ParseDefaultValue(fieldInfo);
+            if (parsed.isCurrentDateFunction) {
+                this.Value = new Date();
             }
-            else {
-                // For strings: strip PostgreSQL's typed-literal wrapper.
-                //
-                // PG's pg_get_expr() (used by vwSQLColumnsAndEntityFields →
-                // EntityField.DefaultValue) renders a string default like:
-                //   'Single'::character varying
-                //   'pending'::text
-                // SQL Server stores the same default as just `'Single'` or
-                // `'pending'`. If we set the field value to the raw PG form,
-                // the value is `'Single'::character varying` (27 chars), and
-                // a MaxLength=20 constraint immediately fails validation —
-                // even though the actual content is `Single` (6 chars).
-                //
-                // Unwrap a leading single-quoted string followed by a `::type`
-                // suffix. Function-call defaults (`nextval('...')`,
-                // `now() AT TIME ZONE 'UTC'`) deliberately don't match this
-                // shape and are left untouched — the database evaluates them
-                // server-side at INSERT time.
-                const dv = fieldInfo.DefaultValue.trim();
-                const pgTypedLiteral = /^'((?:[^']|'')*)'::[A-Za-z][\w "()\[\],]*$/;
-                const m = dv.match(pgTypedLiteral);
-                if (m) {
-                    // Replace the SQL-escaped doubled quotes back to a single quote.
-                    this.Value = m[1].replace(/''/g, "'");
-                }
-                else {
-                    this.Value = fieldInfo.DefaultValue;
-                }
+            else if (parsed.hasValue) {
+                this.Value = parsed.value instanceof Date ? new Date(parsed.value.getTime()) : parsed.value;
             }
             this._neverSet = true; // set this back to true because we are setting the default value and we want to be able to set this ONCE from BaseEntity when we load
         }
         else {
-            this.Value = null; // we need to set the value to null instead of being undefined as the value is defined, it is NULL
+            this._value = null; // we need to set the value to null instead of being undefined as the value is defined, it is NULL
+            this._oldValue = null;
             this._neverSet = true; // set this back to true because we are setting the value to null;
         }
     }
     /**
      * This method will set the internal Old Value which is used to track dirty state, to the current value of the field. This effectively resets the dirty state of the field to false. Use this method sparingly.
+     *
+     * It also clears the written-after-not-loaded flag: the current value becomes the field's
+     * loaded baseline. The hydration paths rely on that (a reload that supplies the field must not
+     * leave it dirty), so code outside hydration must not call this to "accept" a write onto a
+     * not-loaded field, or the write would be saved without being seen as a change.
      */
     ResetOldValue() {
         this._oldValue = this.Value;
+        this._writtenAfterNotLoaded = false;
+    }
+    /**
+     * Framework-internal, for {@link BaseEntity.Revert}: puts the field back to its last loaded or
+     * saved state. A not-loaded field has nothing to revert and stays not-loaded; a field written
+     * after being not-loaded goes back to not-loaded, so the revert neither turns an unloaded field
+     * into "loaded" data a later update would write, nor leaves the write's dirty flag behind.
+     */
+    RevertToOldValue() {
+        if (this._notLoaded) {
+            return;
+        }
+        if (this._writtenAfterNotLoaded) {
+            this.ClearAsNotLoaded();
+            return;
+        }
+        this.Value = this.OldValue;
     }
     /**
      * Restores the dirty-tracking baseline to a previously captured value.
@@ -585,7 +577,13 @@ let EntityField = class EntityField {
      * back can put them back with {@link RestoreState}.
      */
     GetState() {
-        return { Value: this._value, OldValue: this._oldValue, NotLoaded: this._notLoaded, NeverSet: this._neverSet };
+        return {
+            Value: this._value,
+            OldValue: this._oldValue,
+            NotLoaded: this._notLoaded,
+            NeverSet: this._neverSet,
+            WrittenAfterNotLoaded: this._writtenAfterNotLoaded,
+        };
     }
     /**
      * Framework-internal: puts back a state {@link GetState} captured. It writes the state as it was,
@@ -596,6 +594,7 @@ let EntityField = class EntityField {
         this._oldValue = state.OldValue;
         this._notLoaded = state.NotLoaded;
         this._neverSet = state.NeverSet;
+        this._writtenAfterNotLoaded = state.WrittenAfterNotLoaded ?? false;
     }
     /**
      * @deprecated No-op as of the active-status relocation. Active-status (deprecated/disabled)
@@ -620,7 +619,7 @@ let EntityField = class EntityField {
 };
 EntityField = EntityField_1 = __decorate([
     OptionalKeyedSpecialization(),
-    __metadata("design:paramtypes", [EntityFieldInfo, Object])
+    __metadata("design:paramtypes", [EntityFieldInfo, Object, Boolean])
 ], EntityField);
 export { EntityField };
 /**
@@ -905,6 +904,12 @@ export class BaseEntity {
          * commits atomically.
          */
         this._transactionGroup = null;
+        /**
+         * RxJS `Subject` that fires `BaseEntityEvent`s (save, delete, field-change,
+         * remote-invalidate). Exposed publicly via `Event$` so engines and UI components can react
+         * to entity lifecycle events.
+         */
+        this._eventSubject = null;
         /**
          * Bounded ring of `BaseEntityResult` objects from each Save/Delete attempt. The most
          * recent entry is exposed via `LatestResult` for error inspection after a failure.
@@ -1112,7 +1117,7 @@ export class BaseEntity {
          * however it is possible for the string in the map to be any unique key relative to the object so you could have vectors
          * that embed multiple fields if desired.
          */
-        this._vectors = new Map();
+        this._vectors = null;
         /**
          * When true, GenerateEmbedding() returns immediately without computing vectors.
          * Set this before calling Save() in batch/sync contexts where embedding computation
@@ -1120,7 +1125,6 @@ export class BaseEntity {
          * per-process is expensive and vectors can be computed later by the API server).
          */
         this._skipEmbeddings = false;
-        this._eventSubject = new Subject();
         this._entityInfo = Entity;
         EntityInfo.AssertEntityActiveStatus(Entity, 'BaseEntity::constructor');
         this._provider = Provider;
@@ -1662,7 +1666,39 @@ export class BaseEntity {
     static errorText(e) {
         return e instanceof Error ? e.message : String(e);
     }
-    static { this._subtypeLookupCache = new Map(); }
+    /**
+     * The create path's SubtypeSelector lookup memo, partitioned by the provider that ran the lookup and
+     * then by the user it ran for. A memo shared across providers would hand provider B a row loaded
+     * through provider A (another connection) or a `null` miss recorded against A's database. A memo
+     * shared across users would hand one user an entity object shaped to another: an object holds only
+     * the fields its own user may read, so a record loaded for an administrator carries values a
+     * restricted user is denied. Keyed weakly so a request-scoped provider's memo is collected with it.
+     */
+    static { this._subtypeLookupCache = new WeakMap(); }
+    /** Partition key for lookups made by an entity that has no provider at all. */
+    static { this._noProviderSubtypeKey = {}; }
+    /**
+     * The memo for one provider and user, or null when no user resolves: an entry keyed without a
+     * user would be shared by every caller, so such a lookup is not memoized at all.
+     */
+    static subtypeLookupCacheFor(provider, user) {
+        const userKey = UserCacheKeySegment(user?.ID);
+        if (userKey === null) {
+            return null;
+        }
+        const partitionKey = provider ?? BaseEntity._noProviderSubtypeKey;
+        let byUser = BaseEntity._subtypeLookupCache.get(partitionKey);
+        if (!byUser) {
+            byUser = new Map();
+            BaseEntity._subtypeLookupCache.set(partitionKey, byUser);
+        }
+        let cache = byUser.get(userKey);
+        if (!cache) {
+            cache = new Map();
+            byUser.set(userKey, cache);
+        }
+        return cache;
+    }
     /** Per entity (lowercased name): the resolver asked for load hints, decided once per registration. */
     static { this._subtypeLoadHintResolvers = new Map(); }
     /** Indexes over engine-cached arrays, keyed by the live array itself; see {@link findEngineCachedRow}. */
@@ -1674,7 +1710,7 @@ export class BaseEntity {
      * reported again.
      */
     static ClearSubtypeLookupCache() {
-        BaseEntity._subtypeLookupCache.clear();
+        BaseEntity._subtypeLookupCache = new WeakMap();
         BaseEntity._subtypeLoadHintResolvers.clear();
         BaseEntity._engineCachedRowIndexes = new WeakMap();
         BaseEntity._loggedSubtypeLoadHintMessages.clear();
@@ -1863,12 +1899,16 @@ export class BaseEntity {
             return null;
         let currentEntity = this;
         let currentEntityInfo = this.EntityInfo;
+        const actingUser = this.resolveActiveUserOrNull();
         for (let i = 0; i < segments.length - 1; i++) {
             const fieldName = segments[i];
             const fieldInfo = currentEntityInfo.Fields.find(f => f.Name.trim().toLowerCase() === fieldName.toLowerCase());
             if (!fieldInfo) {
                 throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': field '${fieldName}' was not found on entity '${currentEntityInfo.Name}'.`);
             }
+            if (!this.subtypeSelectorMayRead(currentEntity, fieldInfo.Name, actingUser)) {
+                return null; // a hop the user may not read gives no subtype, as a denied name field gives no name
+            }
             const fkValue = currentEntity.Get(fieldInfo.Name);
             if (fkValue == null || fkValue === '') {
                 return null;
@@ -1889,33 +1929,54 @@ export class BaseEntity {
         if (!terminalField) {
             throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': terminal field '${terminalSegment}' was not found on entity '${currentEntityInfo.Name}'.`);
         }
+        if (!this.subtypeSelectorMayRead(currentEntity, terminalField.Name, actingUser)) {
+            return null;
+        }
         const terminalValue = currentEntity.Get(terminalField.Name);
         if (terminalValue == null || typeof terminalValue !== 'string' || terminalValue.trim() === '') {
             return null;
         }
         return terminalValue.trim();
     }
+    /**
+     * Whether a `SubtypeSelector` hop may read `fieldName` on `record`, which is this record or
+     * one the path reached. Both the record's own user and the user resolving the subtype must be
+     * allowed: a record reached through an engine cache was loaded as the system user and holds
+     * every column, so its own answer says nothing about the acting user.
+     */
+    subtypeSelectorMayRead(record, fieldName, actingUser) {
+        if (!record.IsFieldReadableByActiveUser(fieldName)) {
+            return false;
+        }
+        return record === this || !actingUser || record.EntityInfo.IsFieldReadableByUser(fieldName, actingUser);
+    }
     async getSubtypePathTargetEntity(entityName, pkValue) {
         const cacheKey = `${entityName.trim().toLowerCase()}|${String(pkValue).trim().toLowerCase()}`;
-        if (BaseEntity._subtypeLookupCache.has(cacheKey)) {
-            return BaseEntity._subtypeLookupCache.get(cacheKey) ?? null;
+        const provider = this.ProviderToUse;
+        const lookupCache = BaseEntity.subtypeLookupCacheFor(provider, this.resolveActiveUserOrNull());
+        if (lookupCache?.has(cacheKey)) {
+            return lookupCache.get(cacheKey) ?? null;
         }
-        // 1. Check BaseEngineRegistry for loaded cached entities
+        const found = await this.findSubtypePathTarget(provider, entityName, pkValue);
+        lookupCache?.set(cacheKey, found);
+        return found;
+    }
+    /**
+     * Finds the record a create-time `SubtypeSelector` hop points at: in a loaded engine cache
+     * first, then by loading it through the provider for this record's user. Null when neither
+     * has it, or the load fails.
+     */
+    async findSubtypePathTarget(provider, entityName, pkValue) {
         const cached = BaseEntity.findSubtypePathTargetInEngineCache(entityName, pkValue);
         if (cached) {
-            BaseEntity._subtypeLookupCache.set(cacheKey, cached);
             return cached;
         }
-        // 2. Fall back to loading via provider
-        const provider = this.ProviderToUse;
         if (!provider?.GetEntityObject) {
-            BaseEntity._subtypeLookupCache.set(cacheKey, null);
             return null;
         }
         try {
             const targetObj = await provider.GetEntityObject(entityName, this._contextCurrentUser);
             if (!targetObj) {
-                BaseEntity._subtypeLookupCache.set(cacheKey, null);
                 return null;
             }
             let key;
@@ -1927,17 +1988,11 @@ export class BaseEntity {
                 const pkName = targetObj.FirstPrimaryKey.Name; // first-pk-ok: FK target — pkValue is one SubtypeSelector FK column's value
                 key.KeyValuePairs.push(new KeyValuePair(pkName, pkValue));
             }
-            const loaded = await targetObj.InnerLoad(key);
-            if (loaded) {
-                BaseEntity._subtypeLookupCache.set(cacheKey, targetObj);
-                return targetObj;
-            }
+            return (await targetObj.InnerLoad(key)) ? targetObj : null;
         }
         catch {
-            // On load failure, return null
+            return null; // on load failure, no target
         }
-        BaseEntity._subtypeLookupCache.set(cacheKey, null);
-        return null;
     }
     /**
      * Finds the record a `SubtypeSelector` hop points at among the entity objects that loaded
@@ -2142,6 +2197,8 @@ export class BaseEntity {
         // _everSaved, and recreates all EntityField instances with _NeverSet = true
         this.init();
         this.discardJSONFieldObjects();
+        // Field security: denied values never enter this object (see narrowHydrationSource).
+        data = this.narrowHydrationSource(data);
         // Recursively hydrate parent entities first (deepest ancestor resets first).
         // After init(), parent fields have fresh _NeverSet=true, so SetMany can set PKs.
         if (this._parentEntity) {
@@ -2406,7 +2463,9 @@ export class BaseEntity {
             }
             const result = await operation.Execute({
                 EntityName: this.EntityInfo.Name,
-                Fields: this.GetAll(),
+                // Without the fields this user may not read: the server refuses a restricted
+                // caller's input that names one, as the transaction-group serializer knows.
+                Fields: OmitFieldsUnreadableByActiveUser(this, this.GetAll()),
                 Companions: await this.SerializeCompanions(),
                 IsExistingRecord: this.IsSaved,
             }, { provider: this.ProviderToUse, user: this.ActiveUser });
@@ -2445,9 +2504,14 @@ export class BaseEntity {
         // 'save' event both carry it; hardcoding 'update' here made every remote graph CREATE
         // report (and notify subscribers) as an update.
         const saveSubType = this.IsSaved ? 'update' : 'create';
+        const changedFieldNames = this.dirtyFieldNames();
         // Root: rebase field values and dirty state onto what the database now holds.
         this.init();
-        this.SetMany(output.Fields, false, true, true);
+        const fields = this.narrowHydrationSource(output.Fields);
+        this.SetMany(fields, false, true, true);
+        // A hydration source like any other: a field the result omitted (the server withheld it, or
+        // this user may not hold it) is not loaded, so its construction state is never resent as data.
+        this.markFieldsOmittedBySourceAsNotLoaded(fields);
         this._recordLoaded = true;
         this._everSaved = true;
         // Children: adopt server-assigned primary keys and computed values. 'result' mode adopts the
@@ -2461,7 +2525,28 @@ export class BaseEntity {
         result.StartedAt = new Date();
         result.EndedAt = new Date();
         this.RegisterResultHistoryEntry(result);
-        this.RaiseEvent('save', null, saveSubType);
+        this.RaiseEvent('save', null, saveSubType, changedFieldNames);
+    }
+    /**
+     * The names of the fields that are dirty right now. Cheaper than walking {@link Fields}: an
+     * object still in raw mode (loaded and never written to) cannot be dirty, so it answers `[]`
+     * without building its field objects.
+     */
+    GetDirtyFieldNames() {
+        if (!this._fieldsHydrated && this._raw !== null && !this._parentEntity) {
+            return [];
+        }
+        const names = [];
+        for (const f of this.Fields) {
+            if (f.Dirty) {
+                names.push(f.Name);
+            }
+        }
+        return names;
+    }
+    /** The names of the fields that are dirty right now, for the `save` event's {@link BaseEntityEvent.ChangedFieldNames}. */
+    dirtyFieldNames() {
+        return this.GetDirtyFieldNames();
     }
     /**
      * Gives every eager companion a chance to populate itself.
@@ -3039,6 +3124,9 @@ export class BaseEntity {
      * @returns
      */
     RegisterEventHandler(callback) {
+        if (!this._eventSubject) {
+            this._eventSubject = new Subject();
+        }
         return this._eventSubject.asObservable().subscribe(callback);
     }
     /**
@@ -3060,6 +3148,9 @@ export class BaseEntity {
         this.RaiseEvent('transaction_ready', null);
     }
     static { this._baseEventCode = 'BaseEntityEvent'; }
+    static { this._globalEventTypes = new Set([
+        'save', 'delete', 'load_complete', 'save_started', 'delete_started', 'load_started'
+    ]); }
     /**
      * When a BaseEntity class raises an event with MJGlobal, the eventCode property is set to this value. This is used to identify events that are raised by BaseEntity objects.
      * Any MJGlobal event that is raised by a BaseEntity class will use a BaseEntityEvent type as the args parameter
@@ -3070,7 +3161,7 @@ export class BaseEntity {
     /**
      * Used for raising events within the BaseEntity and can be used by sub-classes to raise events that are specific to the entity.
      */
-    RaiseEvent(type, payload, saveSubType = undefined) {
+    RaiseEvent(type, payload, saveSubType = undefined, changedFieldNames) {
         // Resolve the entity's bound provider once so every consumer (local subscribers
         // AND MJGlobal listeners) receives consistent provider context. This matters in
         // multi-provider scenarios — listeners like LocalCacheManager / BaseEngine need to
@@ -3081,17 +3172,17 @@ export class BaseEntity {
         const provider = this.ProviderToUse;
         // this is the local event handler that is specific to THIS instance of the entity object
         LogDebug(`BaseEntity.RaiseEvent() - ${type === 'save' ? 'save:' + saveSubType : type} event raised for ${this.EntityInfo.Name}, about to call this._eventSubject.next()`);
-        this._eventSubject.next({ type: type, payload: payload, saveSubType: saveSubType, baseEntity: this, provider });
+        this._eventSubject?.next({ type: type, payload: payload, saveSubType: saveSubType, baseEntity: this, provider, ChangedFieldNames: changedFieldNames });
         // this next call is to MJGlobal to let everyone who cares knows that we had an event on an entity object
         // we broadcast save/delete/load events and their _started counterparts
-        const globalEventTypes = ['save', 'delete', 'load_complete', 'save_started', 'delete_started', 'load_started'];
-        if (globalEventTypes.includes(type)) {
+        if (BaseEntity._globalEventTypes.has(type)) {
             const event = new BaseEntityEvent();
             event.baseEntity = this;
             event.payload = payload;
             event.type = type;
             event.saveSubType = saveSubType;
             event.provider = provider;
+            event.ChangedFieldNames = changedFieldNames;
             LogDebug(`BaseEntity.RaiseEvent() - ${type === 'save' ? 'save:' + saveSubType : type} event raised for ${this.EntityInfo.Name}, about to call MJGlobal.RaiseEvent()`);
             MJGlobal.Instance.RaiseEvent({
                 component: this,
@@ -3232,6 +3323,7 @@ export class BaseEntity {
     get TransactionGroup() {
         return this._transactionGroup;
     }
+    /** Set `null` to detach the entity from a group, e.g. once the group has been submitted. */
     set TransactionGroup(group) {
         this._transactionGroup = group;
     }
@@ -3272,6 +3364,10 @@ export class BaseEntity {
         }
         // Lookup needs an EntityField instance to return — hydrate.
         this.hydrateFieldsIfNeeded();
+        if (this._entityInfo && typeof this._entityInfo.FieldIndexByName === 'function' && this._fields.length === this._entityInfo.Fields.length && this._fieldCache === null) {
+            const idx = this._entityInfo.FieldIndexByName(fieldName);
+            return idx >= 0 ? (this._fields[idx] ?? null) : null;
+        }
         const lcase = fieldName.trim().toLowerCase(); // do this once as we will use it multiple times
         if (this._fieldCache === null) {
             this._fieldCache = new Map();
@@ -3315,6 +3411,9 @@ export class BaseEntity {
      * ```
      */
     FieldIsDirty(fieldName, ...more) {
+        if (!this._fieldsHydrated && this._raw !== null && !this._parentEntity) {
+            return false;
+        }
         const names = more.length === 0 ? [fieldName] : [fieldName, ...more];
         for (const name of names) {
             if (this.GetFieldByName(name)?.Dirty === true) {
@@ -3334,6 +3433,10 @@ export class BaseEntity {
         }
         // Lookup needs an EntityField instance to return — hydrate.
         this.hydrateFieldsIfNeeded();
+        if (this._entityInfo && typeof this._entityInfo.FieldIndexByCodeName === 'function' && this._fields.length === this._entityInfo.Fields.length && this._codeNameCache === null) {
+            const idx = this._entityInfo.FieldIndexByCodeName(codeName);
+            return idx >= 0 ? (this._fields[idx] ?? null) : null;
+        }
         const lcase = codeName.trim().toLowerCase();
         if (this._codeNameCache === null) {
             this._codeNameCache = new Map();
@@ -3472,11 +3575,14 @@ export class BaseEntity {
      * nothing like field security.
      *
      * Framework-internal value machinery (`Dirty`, `Validate`, `GetAll`, hydration, save-SQL
-     * build) reads `EntityField.Value` directly and never routes through here — that exemption
-     * is load-bearing, not an oversight. Do not "fix" it.
+     * build) reads `EntityField.Value` directly and never routes through here. It needs no gate
+     * of its own: every hydration point leaves a denied field not-loaded and empty for a
+     * restricted user (see {@link narrowHydrationSource}), so there is no denied value for that
+     * machinery to read. This assertion is what turns asking for one into an error rather than a
+     * silent null.
      */
     assertFieldReadable(fieldName) {
-        const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+        const denied = this.deniedReadFieldsForActiveUser();
         if (denied?.has(fieldName?.trim().toLowerCase())) {
             throw new FieldSecurityError(fieldName, this.EntityInfo.Name);
         }
@@ -3488,41 +3594,47 @@ export class BaseEntity {
     setLocal(FieldName, Value) {
         const field = this.GetFieldByName(FieldName);
         if (field != null) {
-            if (field.EntityFieldInfo.TSType === EntityFieldTSType.Date && (typeof Value === 'string' || typeof Value === 'number')) {
-                field.Value = new Date(Value);
+            this.setFieldValue(field, Value);
+        }
+    }
+    setFieldValue(field, Value) {
+        const tsType = field.EntityFieldInfo.TSType;
+        if (tsType === EntityFieldTSType.Date && (typeof Value === 'string' || typeof Value === 'number')) {
+            field.Value = new Date(Value);
+        }
+        else if (tsType === EntityFieldTSType.Number && typeof Value === 'string' && Value !== null && Value !== undefined) {
+            const numericValue = Number(Value);
+            if (!isNaN(numericValue)) {
+                field.Value = numericValue;
             }
-            else if (field.EntityFieldInfo.TSType === EntityFieldTSType.Number && typeof Value === 'string' && Value !== null && Value !== undefined) {
-                const numericValue = Number(Value);
-                if (!isNaN(numericValue)) {
-                    field.Value = numericValue;
-                }
-                else {
-                    field.Value = Value;
-                }
+            else {
+                field.Value = Value;
             }
-            else if (field.EntityFieldInfo.TSType === EntityFieldTSType.Boolean && Value !== null && Value !== undefined) {
-                if (typeof Value === 'string') {
-                    if (Value.trim() === '1' || Value.trim().toLowerCase() === 'true') {
-                        field.Value = true;
-                    }
-                    else if (Value.trim() === '0' || Value.trim().toLowerCase() === 'false') {
-                        field.Value = false;
-                    }
-                    else {
-                        field.Value = Value;
-                    }
+        }
+        else if (tsType === EntityFieldTSType.Boolean && Value !== null && Value !== undefined) {
+            if (typeof Value === 'string') {
+                const trimmed = Value.trim();
+                const lower = trimmed.toLowerCase();
+                if (trimmed === '1' || lower === 'true') {
+                    field.Value = true;
                 }
-                else if (typeof Value === 'number') {
-                    field.Value = Value !== 0;
+                else if (trimmed === '0' || lower === 'false') {
+                    field.Value = false;
                 }
                 else {
                     field.Value = Value;
                 }
             }
+            else if (typeof Value === 'number') {
+                field.Value = Value !== 0;
+            }
             else {
                 field.Value = Value;
             }
         }
+        else {
+            field.Value = Value;
+        }
     }
     /**
      * Returns the value of the field with the given name. If the field is a date, and the value is a string, it will be converted to a date object.
@@ -3533,6 +3645,15 @@ export class BaseEntity {
      * @param FieldName
      * @returns
      */
+    /**
+     * A raw-mode row's value for a field: under its Name, or else its CodeName. Hydration accepts
+     * both keys (as SetMany does), so every raw-mode read must too, or a CodeName-keyed row reads
+     * back empty. `undefined` means the row omitted the field.
+     */
+    rawValueFor(raw, field) {
+        const byName = raw[field.Name];
+        return byName !== undefined || field.CodeName === field.Name ? byName : raw[field.CodeName];
+    }
     /** Records a value derived from `_raw` so later reads skip the conversion. See {@link _rawConverted}. */
     memoizeRawConversion(fieldName, value) {
         (this._rawConverted ??= new Map()).set(fieldName, value);
@@ -3559,28 +3680,31 @@ export class BaseEntity {
         // hydration. Cache data uses exact SQL column names so no case-insensitive scan needed.
         if (!this._fieldsHydrated && this._raw) {
             let value = this._raw[FieldName];
-            if (value === undefined)
-                return null;
             // Conversions mirror the hydrated path, and memoize into `_rawConverted` rather than
             // back into `_raw` — the row may be shared, frozen cache state. Fields needing no
             // conversion (the vast majority) never touch the memo at all, so the fast path stays
             // a single property read.
             const fi = this._entityInfo?.FieldByName(FieldName);
+            if (value === undefined && fi)
+                value = this.rawValueFor(this._raw, fi);
+            if (value === undefined)
+                return null;
+            const memoKey = fi ? fi.Name : FieldName;
             if (fi?.TSType === EntityFieldTSType.Date && (typeof value === 'string' || typeof value === 'number')) {
-                const memo = this._rawConverted?.get(FieldName);
+                const memo = this._rawConverted?.get(memoKey);
                 if (memo !== undefined)
                     return memo;
                 const d = new Date(value);
-                this.memoizeRawConversion(FieldName, d);
+                this.memoizeRawConversion(memoKey, d);
                 return d;
             }
             // Mirror the EntityField.Value setter: rtrim padding for fixed-width string columns.
             if (typeof value === 'string' && fi?.FixedWidthColumn) {
-                const memo = this._rawConverted?.get(FieldName);
+                const memo = this._rawConverted?.get(memoKey);
                 if (memo !== undefined)
                     return memo;
                 value = trimTrailingSpaces(value);
-                this.memoizeRawConversion(FieldName, value);
+                this.memoizeRawConversion(memoKey, value);
             }
             return value;
         }
@@ -3624,8 +3748,8 @@ export class BaseEntity {
                 if (checkStatus) {
                     EntityFieldInfo.AssertEntityFieldActiveStatus(field.EntityFieldInfo, 'BaseEntity.SetMany');
                 }
-                // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
-                this.setLocal(key, object[key]);
+                // Use setFieldValue directly so we don't repeat GetFieldByName(key)
+                this.setFieldValue(field, object[key]);
                 if (replaceOldValues) {
                     field.ResetOldValue();
                 }
@@ -3638,8 +3762,8 @@ export class BaseEntity {
                     if (checkStatus) {
                         EntityFieldInfo.AssertEntityFieldActiveStatus(field.EntityFieldInfo, 'BaseEntity.SetMany');
                     }
-                    // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
-                    this.setLocal(field.Name, object[key]);
+                    // Use setFieldValue directly so we don't repeat GetFieldByName(field.Name)
+                    this.setFieldValue(field, object[key]);
                     if (replaceOldValues) {
                         field.ResetOldValue();
                     }
@@ -3707,21 +3831,51 @@ export class BaseEntity {
      */
     GetAll(oldValues = false, onlyDirtyFields = false) {
         let obj = {};
-        for (let field of this.Fields) {
-            // NotLoaded fields are OMITTED (D-3 decision): their in-memory state is a
-            // construction artifact, and serializing it would launder a default/null into
-            // something downstream code treats as data — the exact masquerade the flag exists
-            // to prevent. Key-absence also propagates the flag naturally: hydrating another
-            // entity from this output re-marks the same fields not-loaded.
-            if (field.NotLoaded)
-                continue;
-            if (!onlyDirtyFields || (onlyDirtyFields && field.Dirty)) {
-                // Reads field.Value directly — serialization is framework-internal, so it does not
-                // (and must not) assert active status. No suppression toggle needed: the assertion no
-                // longer lives on EntityField.Value (it moved to BaseEntity.Get/Set/SetMany).
-                obj[field.Name] = oldValues ? field.OldValue : field.Value;
-                if (field.EntityFieldInfo.TSType == EntityFieldTSType.Date && obj[field.Name] && !(obj[field.Name] instanceof Date)) {
-                    obj[field.Name] = new Date(obj[field.Name]); // a timestamp, convert to JS Date Object
+        if (!this._fieldsHydrated && this._raw !== null) {
+            if (!onlyDirtyFields) {
+                for (const ef of this.EntityInfo.Fields) {
+                    const name = ef.Name;
+                    const rawVal = this.rawValueFor(this._raw, ef);
+                    // Key absence in _raw means NotLoaded (D-3 decision): omit from serialized output
+                    if (rawVal === undefined)
+                        continue;
+                    let val;
+                    const memo = this._rawConverted?.get(name);
+                    if (memo !== undefined) {
+                        val = memo;
+                    }
+                    else if (ef.TSType === EntityFieldTSType.Date && (typeof rawVal === 'string' || typeof rawVal === 'number')) {
+                        val = new Date(rawVal);
+                        this.memoizeRawConversion(name, val);
+                    }
+                    else if (typeof rawVal === 'string' && ef.FixedWidthColumn) {
+                        val = trimTrailingSpaces(rawVal);
+                        this.memoizeRawConversion(name, val);
+                    }
+                    else {
+                        val = rawVal;
+                    }
+                    obj[name] = val;
+                }
+            }
+        }
+        else {
+            for (let field of this.Fields) {
+                // NotLoaded fields are OMITTED (D-3 decision): their in-memory state is a
+                // construction artifact, and serializing it would launder a default/null into
+                // something downstream code treats as data — the exact masquerade the flag exists
+                // to prevent. Key-absence also propagates the flag naturally: hydrating another
+                // entity from this output re-marks the same fields not-loaded.
+                if (field.NotLoaded)
+                    continue;
+                if (!onlyDirtyFields || (onlyDirtyFields && field.Dirty)) {
+                    // Reads field.Value directly — serialization is framework-internal, so it does not
+                    // (and must not) assert active status. No suppression toggle needed: the assertion no
+                    // longer lives on EntityField.Value (it moved to BaseEntity.Get/Set/SetMany).
+                    obj[field.Name] = oldValues ? field.OldValue : field.Value;
+                    if (field.EntityFieldInfo.TSType == EntityFieldTSType.Date && obj[field.Name] && !(obj[field.Name] instanceof Date)) {
+                        obj[field.Name] = new Date(obj[field.Name]); // a timestamp, convert to JS Date Object
+                    }
                 }
             }
         }
@@ -3744,6 +3898,53 @@ export class BaseEntity {
         }
         return obj;
     }
+    /**
+     * Whether {@link GetAll} would carry a key for every non-binary field of this entity: the
+     * object holds a value for each one (none is not loaded, or withheld from its user), here or,
+     * for an IS-A child, on an ancestor. Answers the question
+     * `LocalCacheManager.RowHasEveryField(this.EntityInfo, this.GetAll())` answers, without
+     * building the row, and without building field objects for an object in raw mode.
+     */
+    HoldsEveryField() {
+        const infos = this.EntityInfo?.Fields;
+        if (!Array.isArray(infos) || infos.length === 0) {
+            return true;
+        }
+        if (!this._fieldsHydrated && this._raw !== null) {
+            for (const fi of infos) {
+                if (!fi.IsBinaryFieldType && this.rawValueFor(this._raw, fi) === undefined && !this.ancestorHoldsField(fi.Name)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        for (const field of this.Fields) {
+            if (!field.EntityFieldInfo.IsBinaryFieldType && field.NotLoaded && !this.ancestorHoldsField(field.Name)) {
+                return false;
+            }
+        }
+        return true;
+    }
+    /** Whether an IS-A ancestor's {@link GetAll} would carry the key `name` (an exact field name). */
+    ancestorHoldsField(name) {
+        return this._parentEntity?.holdsFieldNamed(name) ?? false;
+    }
+    /** Whether this object's {@link GetAll} would carry the key `name`, counting its own ancestors. */
+    holdsFieldNamed(name) {
+        if (!this._fieldsHydrated && this._raw !== null) {
+            const fi = this.EntityInfo?.FieldByName(name);
+            if (fi && fi.Name === name && this.rawValueFor(this._raw, fi) !== undefined) {
+                return true;
+            }
+        }
+        else {
+            const field = this.GetFieldByName(name);
+            if (field && field.Name === name && !field.NotLoaded) {
+                return true;
+            }
+        }
+        return this.ancestorHoldsField(name);
+    }
     /**
      * Returns a partial object that contains only the fields that have changed since the last time the record was saved. This is useful for scenarios where you want to send only the changes to the server or to a client.
      * It is also helpful for quickly finding the fields that are "dirty".
@@ -3921,26 +4122,33 @@ export class BaseEntity {
         this._fieldsHydrated = true;
         if (!this.EntityInfo)
             return;
-        // 1. Allocate one EntityField per column. Same construction the old `init()` used to do
-        //    up-front — we just deferred it.
-        for (const rawField of this.EntityInfo.Fields) {
-            const key = this.EntityInfo.Name + '.' + rawField.Name;
-            const newField = MJGlobal.Instance.ClassFactory.CreateInstance(EntityField, key, rawField);
-            this._fields.push(newField);
-        }
-        // 2. If we have raw data from LoadFromData, populate Fields. The first set of each Field
-        //    runs through the EntityField setter with `_NeverSet=true`, which simultaneously sets
-        //    Value AND OldValue (so the field is not marked dirty). This matches the old
-        //    SetMany(replaceOldValues=true) semantics on initial load.
+        // 1. Allocate one EntityField per column. Check once whether any custom EntityField
+        //    subclasses are registered in ClassFactory; in standard deployments none are, so we
+        //    can instantiate EntityField directly without N string concatenations + factory lookups.
+        const hasCustomEntityFieldRegistrations = MJGlobal.Instance.ClassFactory.GetAllRegistrations(EntityField).length > 0;
+        const entityFields = this.EntityInfo.Fields;
+        const skipDefaultValue = this._raw !== null;
+        if (hasCustomEntityFieldRegistrations) {
+            const prefix = this.EntityInfo.Name + '.';
+            for (let i = 0; i < entityFields.length; i++) {
+                const rawField = entityFields[i];
+                const newField = MJGlobal.Instance.ClassFactory.CreateInstance(EntityField, prefix + rawField.Name, rawField, undefined, skipDefaultValue);
+                this._fields.push(newField);
+            }
+        }
+        else {
+            for (let i = 0; i < entityFields.length; i++) {
+                this._fields.push(new EntityField(entityFields[i], undefined, skipDefaultValue));
+            }
+        }
+        // 2. If we have raw data from LoadFromData, populate Fields and mark omitted fields as
+        //    NotLoaded in a single pass.
         if (this._raw) {
-            for (const field of this._fields) {
-                const value = this._raw[field.Name];
+            const raw = this._raw;
+            for (let i = 0; i < this._fields.length; i++) {
+                const field = this._fields[i];
+                const value = this.rawValueFor(raw, field.EntityFieldInfo);
                 if (value !== undefined) {
-                    // Populating fields from the loaded row writes EntityField.Value directly, which does
-                    // not assert active status — so a deprecated column still present in the table emits
-                    // no warning on load (hydration is not user use of the field). No suppression toggle
-                    // is needed now that the assertion lives at BaseEntity.Get/Set/SetMany.
-                    // Date conversion mirrors what SetLocal / Get does for raw string/number dates.
                     if (field.EntityFieldInfo.TSType === EntityFieldTSType.Date && (typeof value === 'string' || typeof value === 'number')) {
                         field.Value = new Date(value);
                     }
@@ -3948,10 +4156,10 @@ export class BaseEntity {
                         field.Value = value;
                     }
                 }
+                else {
+                    field.MarkNotLoaded();
+                }
             }
-            // _raw IS a hydration source (LoadFromData fast path) — fields whose key it omitted
-            // are not-loaded, not defaulted. See EntityField.NotLoaded.
-            this.markFieldsOmittedBySourceAsNotLoaded(this._raw);
             // Raw data has been promoted into Fields — release the reference so we don't carry
             // duplicate state. Fields hold their own copies, so a frozen source no longer
             // constrains anything from here on.
@@ -3964,16 +4172,42 @@ export class BaseEntity {
      * Called only by the hydration entry points ({@link LoadFromData} both modes, {@link Hydrate},
      * {@link InnerLoad}) — never by plain {@link SetMany}, which is an incremental mutation API
      * where omitting a field means "leave it alone," not "this field was never loaded."
-     * Both the field Name and CodeName are checked, matching SetMany's key acceptance.
+     * Both the field Name and CodeName are checked, case-insensitively, matching SetMany's key
+     * acceptance: SetMany applies `{name: 'b'}` to a field called `Name`, so an exact-case lookup
+     * here would mark the value it just applied as not loaded, and GetAll and the save would then
+     * drop it.
      */
     markFieldsOmittedBySourceAsNotLoaded(source) {
         if (!source || typeof source !== 'object')
             return;
+        // Exact keys first: a source keyed by the field names, the usual case, never builds the
+        // case-insensitive key set. It is built once, on the first field the exact check misses.
+        let presentKeys = null;
         for (const field of this.Fields) {
-            if (source[field.Name] === undefined && source[field.CodeName] === undefined) {
-                field.MarkNotLoaded();
+            if (BaseEntity.ownValuePresent(source, field.Name) || BaseEntity.ownValuePresent(source, field.CodeName)) {
+                continue;
+            }
+            presentKeys ??= BaseEntity.normalizedPresentKeys(source);
+            if (!presentKeys.has(field.Name.trim().toLowerCase()) && !presentKeys.has(field.CodeName.trim().toLowerCase())) {
+                // Cleared, not just flagged: otherwise a default from construction, or the previous
+                // record's value on a reload, reads back through Get() as if it had been loaded.
+                field.ClearAsNotLoaded();
+            }
+        }
+    }
+    /** Whether `source` holds `key` as its own property with a value (an inherited `constructor` does not count). */
+    static ownValuePresent(source, key) {
+        return source[key] !== undefined && Object.prototype.hasOwnProperty.call(source, key);
+    }
+    /** The keys of `source` that carry a value, trimmed and lowercased. */
+    static normalizedPresentKeys(source) {
+        const keys = new Set();
+        for (const key of Object.keys(source)) {
+            if (source[key] !== undefined) {
+                keys.add(key.trim().toLowerCase());
             }
         }
+        return keys;
     }
     /**
      * This method will copy the values from the other entity object into the current one. This is useful for things like cloning a record.
@@ -3984,8 +4218,15 @@ export class BaseEntity {
      */
     CopyFrom(other, includePrimaryKeys = false, replaceOldValues = false) {
         try {
+            // Field security: a field THIS object's user may not read is skipped, not copied. The
+            // source can be full width (another user's object, or a server-internal one), and
+            // Set() refuses a denied field, which used to end the copy at the first one.
+            const denied = this.deniedReadFieldsForActiveUser();
             // iterate through all of OUR fields and set them to the value of the other object, if they exist in the other object
             for (let field of this.Fields) {
+                if (denied?.has(field.Name.trim().toLowerCase())) {
+                    continue;
+                }
                 if (!field.IsPrimaryKey || includePrimaryKeys) {
                     const otherField = other.GetFieldByName(field.Name);
                     // Skip fields the SOURCE never loaded (D-3): copying their construction
@@ -4009,9 +4250,27 @@ export class BaseEntity {
      * The ContextCurrentUser is a property used to manually set the "current" user for scenarios, primarily on the server side, where the user changes per request. For situations where there is no global CurrentUser in the Metadata.Provider,
      * you MUST set this property to the user you want to use for the current operation. If you used Metadata.GetEntityObject() to get the entity object, this property will be set automatically for you as that method has a parameter that can
      * be provided for the ContextCurrentUser.
+     *
+     * **Field security.** An object holds only what its user may read, so assigning a different
+     * user to an object that already holds a record narrows it to the new user: values the new
+     * user may not read are dropped (the fields become not loaded) from this object, its IS-A
+     * parent, its embedded records and the loaded children of its related-record collections,
+     * which are given the same user. A read-only cache collection's children are the engine's own
+     * instances and are left as they are. Nothing is widened: a field
+     * the previous user could not read stays not loaded for a user who can, because its value was
+     * never loaded. Set the user before loading wherever possible, so the record is loaded at the
+     * right width in the first place.
      */
     set ContextCurrentUser(user) {
+        if (user === this._contextCurrentUser) {
+            return;
+        }
         this._contextCurrentUser = user;
+        this.narrowHeldValuesForActiveUser(false);
+        if (this._parentEntity) {
+            this._parentEntity.ContextCurrentUser = user;
+        }
+        this.notifyCompanionsContextUserChanged(user);
     }
     get ContextCurrentUser() {
         return this._contextCurrentUser;
@@ -4078,6 +4337,11 @@ export class BaseEntity {
                 }
             }
         }
+        // Field security: a new record holds no default for a field its user may not read. The
+        // field is not loaded instead, so GetAll() and every payload built from it leave it out
+        // (the server refuses a restricted caller's input that names it), and the save omits it,
+        // so the column takes its database default.
+        this.narrowHeldValuesForActiveUser(true);
         // Apply caller-supplied values LAST so an explicit PK (or any routed
         // parent field) wins over the generated/adopted value instead of being
         // clobbered by the parent's NewRecord().
@@ -4104,6 +4368,53 @@ export class BaseEntity {
             }
         }
     }
+    /**
+     * Gives every companion this object's new user: embedded records and the loaded children of
+     * related-record collections take it. See {@link ContextCurrentUser}.
+     */
+    notifyCompanionsContextUserChanged(user) {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            companion.OnOwnerContextUserChanged(user);
+        }
+    }
+    /**
+     * Drops every value this object holds that its user may not read: the field is left not
+     * loaded and empty, or, before the fields are built, the key leaves the raw row (as a copy;
+     * the row can be shared). A no-op when field security does not apply or the user is denied
+     * nothing, which is the one boolean most entities pay.
+     *
+     * For the points where the user or the record changes WITHOUT a hydration source to narrow:
+     * a user assigned to an object that already holds a record, and a new record's defaults.
+     *
+     * @param buildFields true to build the fields first when they are not built yet, as a new
+     *        record needs: its defaults live in fields that are only created on first use.
+     */
+    narrowHeldValuesForActiveUser(buildFields) {
+        const denied = this.deniedReadFieldsForActiveUser();
+        if (!denied) {
+            return;
+        }
+        if (!this._fieldsHydrated && !buildFields) {
+            if (this._raw) {
+                this._raw = OmitDeniedFieldKeys(this._raw, denied);
+                this._rawConverted = null;
+            }
+            return;
+        }
+        let cleared = false;
+        for (const field of this.Fields) {
+            if (denied.has(field.Name.trim().toLowerCase()) && (!field.NotLoaded || field.Value !== null)) {
+                field.ClearAsNotLoaded();
+                cleared = true;
+            }
+        }
+        if (cleared) {
+            this.discardJSONFieldObjects(); // a parsed JSON object can hold a value just dropped
+        }
+    }
     /**
      * Returns the active restore context for the next save, if any.
      *
@@ -4479,7 +4790,7 @@ export class BaseEntity {
                         const data = await this.ProviderToUse.Save(this, this.ActiveUser, _options);
                         if (!this.TransactionGroup) {
                             // no transaction group, so we have our results here
-                            const result = this.finalizeSave(data, saveSubType);
+                            const result = this.finalizeSave(data, saveSubType, _options);
                             // Settle the scope this entity opened, if any (only the initiator holds
                             // one). The provider can fail by RETURNING falsy data rather than
                             // throwing — a validate-type entity action rejecting the save does
@@ -4500,7 +4811,7 @@ export class BaseEntity {
                             this.TransactionGroup.TransactionNotifications$.subscribe(({ success, results, error }) => {
                                 const transItem = success && results ? results.find(r => r.Transaction.BaseEntity === this) : undefined;
                                 if (transItem) {
-                                    this.finalizeSave(transItem.Result, saveSubType); // we get the resulting data from the transaction result, not data above as that will be blank when in a TG
+                                    this.finalizeSave(transItem.Result, saveSubType, _options); // we get the resulting data from the transaction result, not data above as that will be blank when in a TG
                                 }
                                 else {
                                     // The transaction group failed / rolled back, OR (should never happen) reported success
@@ -4602,10 +4913,43 @@ export class BaseEntity {
         // If no remaining children, safe to delete parent
         return remainingChildren.length === 0;
     }
-    finalizeSave(data, saveSubType) {
+    finalizeSave(data, saveSubType, options) {
         if (data) {
+            // The 'save' event names the fields this save wrote; init() below clears every dirty flag.
+            const changedFieldNames = this.dirtyFieldNames();
+            const effectiveReturnMode = options?.SaveReturnMode ?? this.EntityInfo.SaveReturnMode;
+            const hasGetAll = (val) => val instanceof BaseEntity || typeof val.GetAll === 'function';
+            const rawFieldData = hasGetAll(data) ? data.GetAll() : data;
+            // In 'datestamps_only' mode, the database only returned PK + __mj_CreatedAt / __mj_UpdatedAt.
+            // Merge those returned values onto the current in-memory values BEFORE init() wipes Fields,
+            // so caller-set fields remain loaded and intact without a post-save BaseView SELECT.
+            // When DatabaseProviderBase.Save already merged its pre-save snapshot (`__mj_preMerged`),
+            // reuse `rawFieldData` directly to avoid a redundant second `GetAll()` call.
+            let fieldData;
+            if (effectiveReturnMode === 'datestamps_only' && typeof rawFieldData === 'object' && !Array.isArray(rawFieldData)) {
+                if (rawFieldData.__mj_preMerged) {
+                    fieldData = rawFieldData;
+                }
+                else {
+                    const currentValues = this.GetAll();
+                    if (saveSubType === 'create' || !this.IsSaved) {
+                        for (const f of this.EntityInfo.Fields) {
+                            if (f.IsVirtual && !f.IsPrimaryKey && !(f.Name in rawFieldData) && (currentValues[f.Name] === null || currentValues[f.Name] === undefined)) {
+                                delete currentValues[f.Name];
+                            }
+                        }
+                    }
+                    fieldData = { ...currentValues, ...rawFieldData };
+                }
+            }
+            else {
+                fieldData = rawFieldData;
+            }
+            // The save returns the whole row, whoever saved it. The provider has already built the
+            // Record Changes payload from this entity's pre-save state, so narrowing the response
+            // here costs the audit nothing; it only keeps denied values out of this object.
+            fieldData = this.narrowHydrationSource(fieldData);
             this.init(); // wipe out the current data to flush out the DIRTY flags, load the ID as part of this too
-            const fieldData = (data instanceof BaseEntity || (data && typeof data.GetAll === 'function')) ? data.GetAll() : data;
             // IS-A GetAll() merges the parent, including parent virtuals this entity
             // does not own (e.g. OrderHeader on Event Order Line). Keep only columns
             // this entity defines, and ignore anything leftover.
@@ -4624,7 +4968,7 @@ export class BaseEntity {
                 result.NewValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.Value }; }); // set the latest values here
             // Cache the record name for faster lookups (updates cache with potentially new name)
             this.cacheRecordName();
-            this.RaiseEvent('save', null, saveSubType);
+            this.RaiseEvent('save', null, saveSubType, changedFieldNames);
             return true;
         }
         else {
@@ -4760,16 +5104,17 @@ export class BaseEntity {
      * entity was hydrated FROM THE DATABASE on every FLS entity. Two distinct resolver behaviours
      * carry that premise, and BOTH are load-bearing:
      *
-     * 1. `StripDeniedReadFieldsFromClientInput` removes client-sent values for fields the caller
-     *    cannot READ, which `SetMany` would otherwise make genuinely dirty with fabricated data.
-     * 2. `entityInfo.EnableFieldLevelSecurity` forces the truth-load branch, so the entity's
+     * 1. `AssertClientInputFieldSecurity` (through `AssertClientInputWritableForUser`) rejects
+     *    client input naming a field the caller cannot READ, or no field at all, which `SetMany`
+     *    would otherwise make genuinely dirty with fabricated data.
+     * 2. `entityInfo.FieldLevelSecurityApplies` forces the truth-load branch, so the entity's
      *    non-dirty baseline is the real stored row rather than the client's `OldValues___`.
      *
      * (2) is not redundant with (1). A value arriving through `LoadFromData` is recorded by the
      * EntityField setter as the field's INITIAL value, so it is not dirty — and this check would
      * never see it, while `GenerateSaveSQL` sends it anyway (it filters on `NotLoaded`, never on
      * `Dirty`). Without the forced truth-load, a caller with Read Allow + Update Deny — the
-     * canonical FLS configuration, and one that leaves (1) with nothing to strip — could write an
+     * canonical FLS configuration, and one that leaves (1) with nothing to reject — could write an
      * update-denied field just by pinning its value in `OldValues___` and never naming it in the
      * mutation. If you are considering relaxing that branch condition, this check is what breaks.
      *
@@ -4802,7 +5147,7 @@ export class BaseEntity {
                 // deliberately skips the readability assertion (hydration / resolver-apply path),
                 // so server-side code can dirty a read-denied field and land here.
                 if (deniedRead === undefined) {
-                    deniedRead = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+                    deniedRead = this.deniedReadFieldsForActiveUser();
                 }
                 throw deniedRead?.has(key)
                     ? new FieldSecurityError(field.Name, this.EntityInfo.Name)
@@ -4851,15 +5196,32 @@ export class BaseEntity {
                 `omitted field(s) ${suppressed.join(', ')}; each column takes its default`);
         }
     }
+    /**
+     * Whether this object's user may READ the named field: the question `Get()` asks before it
+     * throws a `FieldSecurityError`, answered without throwing.
+     *
+     * For code that reads a field it did not choose, such as a configured path or a display
+     * column, and must treat a denied field as having no value rather than fail. Fails open the
+     * way `Get()` does: true when field security does not apply to this entity (or any IS-A
+     * ancestor) or no user resolves.
+     *
+     * @param fieldName the field's Name, matched case-insensitively
+     */
+    IsFieldReadableByActiveUser(fieldName) {
+        if (!fieldName) {
+            return true;
+        }
+        return !this.deniedReadFieldsForActiveUser()?.has(fieldName.trim().toLowerCase());
+    }
     /**
      * The denied-field set for the acting user, or null when field security does not apply —
-     * the entity has it switched off, no user resolves, or the user is denied nothing.
+     * it is off on the entity and every IS-A ancestor, no user resolves, or the user is denied nothing.
      *
      * Returning null rather than an empty Set lets callers skip their loop entirely, and keeps
      * the three cheap short-circuits in one place instead of repeated at each gate.
      */
     deniedFieldsForActiveUser(select) {
-        if (!this.EntityInfo?.EnableFieldLevelSecurity) {
+        if (!this.EntityInfo?.FieldLevelSecurityApplies) {
             return null; // one boolean for the overwhelming majority of entities
         }
         const u = this.resolveActiveUserOrNull();
@@ -4869,6 +5231,34 @@ export class BaseEntity {
         const denied = select(u);
         return denied.size > 0 ? denied : null;
     }
+    /**
+     * The fields this object's user may not READ, lowercased by Name and CodeName, or null when
+     * field security does not apply. Every readability question this class asks, at hydration,
+     * at the typed accessors and at the save gates, goes through here.
+     */
+    deniedReadFieldsForActiveUser() {
+        return this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+    }
+    /**
+     * A hydration source reduced to what this object's user may hold: the same object when the
+     * user is denied nothing (or field security does not apply), otherwise a shallow copy without
+     * the denied keys, matched case-insensitively under Name and CodeName.
+     *
+     * Every point that fills this object from a row passes the row through here first, which is
+     * what makes the object's width a property of its user rather than of the path that built it.
+     * A key absent from a hydration source already means "not loaded" everywhere (`GetAll`, field
+     * building, the save), so omitting a denied key is all it takes for the value never to enter
+     * the object, and for every accessor and serializer to be correct without a check of its own.
+     *
+     * The caller's row is never modified, because it can be a frozen row shared through a cache,
+     * and an unrestricted user's row is returned by reference, so the raw load path stays zero-copy.
+     */
+    narrowHydrationSource(source) {
+        if (!source || typeof source !== 'object' || Array.isArray(source) || source instanceof Date) {
+            return source;
+        }
+        return OmitDeniedFieldKeys(source, this.deniedReadFieldsForActiveUser());
+    }
     /**
      * {@link ActiveUser}, but null instead of throwing when no provider is configured to resolve
      * one from.
@@ -4903,7 +5293,7 @@ export class BaseEntity {
         this.discardJSONFieldObjects(); // unconditional: an un-flushed edit through a stale reference must go too
         if (this.Dirty) {
             for (let field of this.Fields) {
-                field.Value = field.OldValue;
+                field.RevertToOldValue();
             }
             // IS-A composition: revert parent entity chain as well
             if (this._parentEntity) {
@@ -4936,7 +5326,7 @@ export class BaseEntity {
             if (!this.IsSaved) {
                 this.init(); // wipe out current data if we're loading on top of existing record
             }
-            const data = await this.readRowForLoad(CompositeKey, EntityRelationshipsToLoad);
+            let data = await this.readRowForLoad(CompositeKey, EntityRelationshipsToLoad);
             this.discardJSONFieldObjects(); // a reload replaces the record's data
             if (!data) {
                 // A subtype-hint probe asks whether this row exists, so "no" is an answer, not an error
@@ -4945,6 +5335,9 @@ export class BaseEntity {
                 }
                 return false; // no data loaded, return false
             }
+            // Field security: denied values never enter this object, even from a provider that
+            // did not narrow its SELECT (see narrowHydrationSource).
+            data = this.narrowHydrationSource(data);
             // IS-A: hydrate parent chain from loaded data before populating self.
             // Hydrate resets each parent via init() (giving fresh _NeverSet=true on PK fields)
             // then populates from data. This must happen before self's SetMany so parents
@@ -5095,6 +5488,16 @@ export class BaseEntity {
      */
     async LoadFromData(data, _replaceOldValues = false) {
         this.discardJSONFieldObjects(); // the record's data is being replaced: parsed JSON objects are stale
+        // An entity object passed as the row is read through its own GetAll(): what ITS user may
+        // read, as a plain row. Kept as the row itself, it would be read through its typed getters,
+        // which answer for the source's user and so return values this object's user is denied
+        // (narrowing below sees only an object's own keys, and an entity's values are not those).
+        if (data instanceof BaseEntity) {
+            data = data.GetAll();
+        }
+        // Field security: a restricted user's object holds a copy of the row without the keys they
+        // are denied; anyone else's keeps the caller's row by reference (see narrowHydrationSource).
+        data = this.narrowHydrationSource(data);
         // IS-A: hydrate parent chain from data before populating self.
         // Hydrate resets each parent via init() (giving fresh _NeverSet=true on PK fields)
         // then populates from data, ensuring correct PK and saved state on parents.
@@ -5108,12 +5511,26 @@ export class BaseEntity {
         // This is the dominant warm-load case (cache restore in TransformSimpleObjectToEntityObject
         // populating engine arrays of read-only data) and was previously the per-row bottleneck.
         const isPlainObject = data && typeof data === 'object' && !Array.isArray(data) && !(data instanceof Date);
+        const isFirstOrUnhydratedLoad = this._raw === null &&
+            !this._recordLoaded &&
+            !this._everSaved &&
+            ((!this._fieldsHydrated && this._fields.length === 0) || this._fields.every(f => f.NeverSet));
+        const hasCompanionPayload = this.HasCompanions &&
+            isPlainObject &&
+            Array.isArray(data[COMPANION_PAYLOAD_KEY]);
         const canTakeFastPath = isPlainObject &&
-            !this._fieldsHydrated &&
-            this._fields.length === 0 &&
+            isFirstOrUnhydratedLoad &&
             !this._parentEntity &&
-            !this.EntityInfo?.IsParentType;
+            !this.EntityInfo?.IsParentType &&
+            !hasCompanionPayload;
         if (canTakeFastPath) {
+            if (this._fieldsHydrated || this._fields.length > 0) {
+                this._fields = [];
+                this._fieldsHydrated = false;
+                this._fieldCache = null;
+                this._codeNameCache = null;
+            }
+            this._compositeKey = null;
             this._raw = data;
             // Drop any conversions memoized from a previously-loaded row — they describe the old
             // `_raw`, not this one. No isFrozen probe is needed: `Get()` never writes to `_raw`,
@@ -5124,7 +5541,7 @@ export class BaseEntity {
             const pks = this.EntityInfo?.PrimaryKeys ?? [];
             let allPksPresent = pks.length > 0;
             for (const pkInfo of pks) {
-                const v = this._raw[pkInfo.Name];
+                const v = this.rawValueFor(this._raw, pkInfo);
                 if (v === null || v === undefined) {
                     allPksPresent = false;
                     break;
@@ -5887,7 +6304,7 @@ export class BaseEntity {
         //
         // Returning null is the same answer callers already handle for "this entity has no name
         // field", and every one of them degrades to the primary key.
-        if (!this.EntityInfo.IsFieldReadableByUser(f.Name, this.ActiveUser)) {
+        if (!this.IsFieldReadableByActiveUser(f.Name)) {
             return null;
         }
         return this.Get(f.Name);
@@ -6091,13 +6508,16 @@ export class BaseEntity {
      * use this to track vectors associated with
      */
     get Vectors() {
+        if (!this._vectors) {
+            this._vectors = new Map();
+        }
         return this._vectors;
     }
     /**
      * Resets the vector embeddings for this entity to an empty state.
      */
     ResetVectors() {
-        this._vectors.clear();
+        this._vectors?.clear();
     }
     /**
      * Resolves the recursive foreign key field for this entity. If `parentFieldName` is provided,