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

package/dist/generic/baseEntity.js

@@ -8,14 +8,17 @@ 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 { IsMemberOverridden, MJEventType, MJGlobal, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager } from '@memberjunction/global';
+import { DeserializeValidationErrors, IsMemberOverridden, MJEventType, MJGlobal, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager } from '@memberjunction/global';
 import { GetDataHooks } from './dataHooks.js';
-import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
+import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, FieldSecurityError, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
+import { EntitySubtypeResolver } from './entitySubtypeResolver.js';
+import { BaseEngineRegistry } from './baseEngineRegistry.js';
+import { IsPermittedImageFieldValue, IsValidCssColor, TryParseJsonText } from './extendedTypeValue.js';
 import { EntityDeleteOptions, EntitySaveOptions, ProviderType } from './interfaces.js';
 import { Metadata } from './metadata.js';
 import { RunView } from '../views/runView.js';
 import { LogDebug, LogError } from './logging.js';
-import { CompositeKey } from './compositeKey.js';
+import { CompositeKey, KeyValuePair } from './compositeKey.js';
 import { RelatedRecordCollection } from './relatedRecordCollection.js';
 import { COMPANION_PAYLOAD_KEY } from './entityCompanion.js';
 import { EmbeddedRecord } from './embeddedRecord.js';
@@ -49,6 +52,57 @@ let EntityField = class EntityField {
         "real": { min: -3.402823466e+38, max: 3.402823466e+38 },
         "money": { min: -922337203685477.5808, max: 922337203685477.5807 },
     }; }
+    /**
+     * True when the source this entity was hydrated from OMITTED this field's key — most
+     * commonly because field-level security stripped it before the payload reached us, but
+     * equally for any partial hydration. The field's in-memory state (its metadata default,
+     * else null) is a construction artifact, not data: the save path skips not-loaded fields
+     * entirely (the generated procs' `ISNULL(@p, [Col])` merge then preserves the stored
+     * value), {@link Dirty} always reports false for them, and {@link Validate} exempts them
+     * from the required/null check.
+     *
+     * Deliberately DISTINCT from `_NeverSet`, which means "no set since construction," exists
+     * to permit the one-time write to ReadOnly fields on load, and is re-armed wholesale by
+     * `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.
+     */
+    get NotLoaded() {
+        return this._NotLoaded;
+    }
+    /**
+     * Framework-internal: hydration paths call this for each field whose key the hydration
+     * source omitted. Application code should never need it — an explicit {@link Value} set
+     * clears the flag.
+     */
+    MarkNotLoaded() {
+        this._NotLoaded = true;
+    }
+    /**
+     * True when field-level security bars this user from supplying the field's value on INSERT,
+     * so the save path must omit it and let the column take its database default.
+     *
+     * Deliberately DISTINCT from {@link NotLoaded}, even though both end in "leave this
+     * parameter out of the SP call". `NotLoaded` means "the hydration source omitted this key"
+     * and carries consequences this must not: it suppresses the `_Clear` companion, exempts the
+     * field from required/null validation, and forces {@link Dirty} to false. A create-suppressed
+     * field, by contrast, holds a perfectly real value the user typed — it is simply not one they
+     * are permitted to supply. Conflating them would silently disarm validation on fields a user
+     * IS allowed to create.
+     *
+     * Set per-save by the create-path gate and cleared at the start of every save, because the
+     * answer depends on the acting user and the same entity object can be saved by different
+     * users over its lifetime.
+     */
+    get CreateSuppressed() {
+        return this._CreateSuppressed;
+    }
+    /** Framework-internal: set by the save path's field-security create gate. */
+    SetCreateSuppressed(suppressed) {
+        this._CreateSuppressed = suppressed;
+    }
     get Name() {
         return this._entityFieldInfo.Name;
     }
@@ -123,8 +177,16 @@ let EntityField = class EntityField {
                 value = value.replace(/ +$/, '');
             }
             this._Value = value;
+            // Any explicit set means the field now holds REAL data — including a blind write to
+            // a read-denied field (the write-only case), which must flow to the save. Captured
+            // BEFORE clearing so the OldValue branch below can see it: a set onto a not-loaded
+            // field is an EDIT (must become dirty and reach the save), never the "initial value
+            // set" of record setup — the record's setup moment was the hydration that omitted
+            // this field.
+            const wasNotLoaded = this._NotLoaded;
+            this._NotLoaded = false;
             // 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 &&
+            if (this._NeverSet && !wasNotLoaded &&
                 (value !== null || this._OldValue !== null)) {
                 // initial value set
                 this._OldValue = value;
@@ -142,9 +204,11 @@ let EntityField = class EntityField {
     }
     /**
      * 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
+     * artifact, not data, and nothing that was never loaded can have been changed.
      */
     get Dirty() {
-        if (this.ReadOnly)
+        if (this.ReadOnly || this._NotLoaded)
             return false;
         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
@@ -278,7 +342,13 @@ let EntityField = class EntityField {
         // no longer false-warns or throws here.
         if (!ef.ReadOnly && !ef.SkipValidation) {
             // only do validation on updatable fields and skip the special case fields defined inside the SkipValidation property (like ID/CreatedAt/UpdatedAt)
-            if (!ef.AllowsNull && (this.Value === null || this.Value === undefined)) {
+            // NotLoaded exemption: a field the hydration source omitted holds null/default by
+            // construction and is SKIPPED by the save SQL, so the stored value is untouched —
+            // failing the required check here would make every partially hydrated record
+            // unsaveable for unrelated edits (the exact NOT-NULL breakage mode the not-loaded
+            // design exists to remove). Length/type checks below still apply to whatever the
+            // constructor state is; only the required/null check is meaningless for it.
+            if (!ef.AllowsNull && !this._NotLoaded && (this.Value === null || this.Value === undefined)) {
                 // make sure this isn't a field that has a default value and we are inside a new record
                 if (ef.DefaultValue === null || ef.DefaultValue === undefined || ef.DefaultValue.trim().length === 0) {
                     // we have no default value, so this is an error
@@ -327,11 +397,42 @@ let EntityField = class EntityField {
                 const nullNote = ef.AllowsNull ? ' (or null)' : '';
                 result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} must be one of: ${ef.ValueListValuesForDisplay}${nullNote}. Current value is '${this.Value}'`, this.Value));
             }
+            // ExtendedType semantic checks (Image / Color / JSON). Empty values are handled by
+            // the AllowsNull rung above — only non-empty strings are inspected here.
+            if (ef.TSType === EntityFieldTSType.String && this.Value != null && this.Value !== '') {
+                const text = String(this.Value);
+                switch (ef.ExtendedType) {
+                    case 'JSON': {
+                        const parsed = TryParseJsonText(text);
+                        if (parsed.ok === false) {
+                            result.Success = false;
+                            result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} must be valid JSON. ${parsed.message}`, this.Value));
+                        }
+                        break;
+                    }
+                    case 'Color': {
+                        if (!IsValidCssColor(text)) {
+                            result.Success = false;
+                            result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} must be a CSS color (hex, rgb, or hsl)`, this.Value));
+                        }
+                        break;
+                    }
+                    case 'Image': {
+                        if (!IsPermittedImageFieldValue(text)) {
+                            result.Success = false;
+                            result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} must be an image URL or inline image (data URI / base64)`, this.Value));
+                        }
+                        break;
+                    }
+                }
+            }
         }
         return result;
     }
     constructor(fieldInfo, Value) {
         this._NeverSet = true;
+        this._NotLoaded = 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
         // asserted only when code accesses the field by name via BaseEntity.Get/Set/SetMany, never
@@ -489,6 +590,21 @@ export class BaseEntityAIActionParams {
  */
 export class BaseEntityResult {
     constructor(success, message, type) {
+        /**
+         * Set by a producer whose `Message` ALREADY renders every entry of `Errors`, so that
+         * {@link CompleteMessage} does not say the same thing twice.
+         *
+         * Two kinds of producer build `Message` out of `Errors`: the client-side providers, which copy
+         * the SERVER's `CompleteMessage` (= its errors, joined) into `Message` and then rehydrate the same
+         * entries into `Errors` so a form can paint the fields; and the IS-A parent-failure paths, which
+         * write "Failed to save parent entity … : <errors joined>". Without this flag every one of them
+         * read twice in `CompleteMessage`. A substring dedupe was tried and reverted (it is lossy in ways
+         * a reader cannot detect — see `CompleteMessage`); a producer stating the fact is exact.
+         *
+         * Only honoured when `Message` actually has text: a producer that set the flag and left `Message`
+         * empty is contradicting itself, and the errors are still rendered rather than lost.
+         */
+        this.MessageIncludesErrors = false;
         /**
          * A copy of the values of the entity object BEFORE the operation was performed
          */
@@ -505,6 +621,56 @@ export class BaseEntityResult {
         this.StartedAt = new Date();
         this.EndedAt = new Date();
     }
+    /**
+     * Renders ONE entry of the {@link Errors} array as human-readable text.
+     *
+     * `Errors` is typed `any[]`, and two shapes land in it from different places:
+     *
+     *  - **`ValidationErrorInfo`** — carries **`Message`** (capital M), plus `Source`, `Value` and
+     *    `Type`. This is what `_InnerSave` puts there when validation refuses a save: it throws the
+     *    `ValidationResult`, and the catch block assigns `newResult.Errors = e.Errors`.
+     *  - **`Error`** (and anything error-like) — carries lowercase **`message`**.
+     *
+     * This used to read `err.message` ONLY, so every `ValidationErrorInfo` fell through to
+     * `JSON.stringify(err)`. That is not a cosmetic difference: `CompleteMessage` is the string the
+     * server hands the client on a failed save — every write-refusal throw in `ResolverBase`
+     * (`CreateRecord`/`UpdateRecord`/`DeleteRecord`) puts it in the `GraphQLError`, and
+     * `SaveEntityGraphOperation` puts it in `ErrorMessage` — so the whole point of writing a careful,
+     * field-named refusal in a subclass's `ValidateAsync()` was defeated at the last step, and the
+     * user saw
+     * `{"Source":"ParentContractID","Message":"…","Value":null,"Type":"Failure"}` in a toast.
+     *
+     * Nothing catches this at compile time because `Errors` is `any[]`; nothing catches it at runtime
+     * because `JSON.stringify` always succeeds. It is only visible by reading the message a user got.
+     *
+     * The parameter is `unknown` rather than `any` — per `.claude/rules/typescript-style.md` — because
+     * not knowing the shape is the whole reason this helper exists, and `unknown` forces the narrowing
+     * that makes each shape's handling explicit. Callers pass `any` (the `Errors` array and the `Error`
+     * property are both legacy `any`), which is assignable, so no call site changes.
+     *
+     * `Message` is preferred over `message` because a `ValidationErrorInfo` has only the former,
+     * while an `Error` has only the latter — so the order matters solely for an object carrying both,
+     * where the MJ-native field is the better answer.
+     *
+     * @param err - One entry from the `Errors` array.
+     * @returns The entry's human-readable text, falling back to JSON for a shape with neither field.
+     */
+    static ErrorText(err) {
+        if (err === null || err === undefined) {
+            return '';
+        }
+        if (typeof err === 'string') {
+            return err;
+        }
+        if (typeof err === 'object') {
+            const shaped = err;
+            const text = shaped.Message ?? shaped.message;
+            if (typeof text === 'string' && text.trim().length > 0) {
+                return text;
+            }
+        }
+        return JSON.stringify(err);
+    }
     /**
      * Returns a complete message that includes the Message property (if present), the Error property (if present), and any Errors array items (if present).
      */
@@ -514,23 +680,30 @@ export class BaseEntityResult {
         if (this.Message && this.Message.trim().length > 0) {
             msg = this.Message;
         }
-        // now check the simple Error property
+        // now check the simple Error property. Same shape problem as the Errors array below, so the
+        // same helper answers it: a string, an Error (lowercase `message`), or an MJ
+        // ValidationErrorInfo (capital `Message`) all render as their text rather than as JSON.
         if (this.Error) {
-            msg = (msg ? msg + '\n' : '');
-            if (typeof this.Error === 'string') {
-                msg += this.Error;
-            }
-            else if (this.Error.message) {
-                msg += this.Error.message;
-            }
-            else {
-                msg += JSON.stringify(this.Error);
-            }
+            msg = (msg ? msg + '\n' : '') + BaseEntityResult.ErrorText(this.Error);
         }
-        // now check the Errors array
-        if (this.Errors && this.Errors.length > 0) {
+        // now check the Errors array.
+        //
+        // NOT de-duplicated, deliberately. Some producers set BOTH `Message` and `Errors` and build
+        // the former out of the latter — `_InnerSave`/`_InnerDelete` do on an IS-A parent failure —
+        // so their text does appear twice here. Suppressing a repeat was tried and reverted: any
+        // containment test is lossy in ways a reader cannot detect. Three fields failing with the
+        // same sentence collapse to one line; an entry whose text is a substring of another is kept
+        // or dropped depending on ARRAY ORDER; and a distinct error vanishes when its text happens to
+        // appear inside the summary. Saying something twice is ugly. Silently reporting one problem
+        // when there were three is the failure this whole class of bug is about, so the duplication
+        // stays UNLESS the producer states, via `MessageIncludesErrors`, that `Message` already
+        // renders every entry — an exact fact, not a guess, and the only producer-side fix that
+        // removes the repeat at the source.
+        const messageHasText = !!this.Message && this.Message.trim().length > 0;
+        const errorsAlreadyInMessage = this.MessageIncludesErrors && messageHasText;
+        if (this.Errors && this.Errors.length > 0 && !errorsAlreadyInMessage) {
             // append
-            msg = (msg ? msg + '\n' : '') + this.Errors.map(err => err.message || JSON.stringify(err)).join('\n');
+            msg = (msg ? msg + '\n' : '') + this.Errors.map(err => BaseEntityResult.ErrorText(err)).join('\n');
         }
         return msg;
     }
@@ -816,6 +989,16 @@ export class BaseEntity {
          * pay nothing for the feature, not even an empty Map per instance.
          */
         this._companions = null;
+        /**
+         * Returns true if the object is Dirty, meaning something has changed since it was last saved to the database, and false otherwise. For new records, this will always return true.
+         *
+         * @remarks
+         * Dirtiness rolls up **companions** as well as fields. Without that rollup, a clean parent with
+         * three brand-new children reports `Dirty === false`, `_InnerSave` takes its not-dirty early
+         * return, and the children are silently never persisted — the save reports success and writes
+         * nothing. See {@link EntityCompanion.Dirty}.
+         */
+        this._isCheckingDirty = false;
         this._compositeKey = null;
         // ────────────────────────────────────────────────────────────────────
         // Restore context — populated by callers immediately before Save() to
@@ -833,6 +1016,13 @@ export class BaseEntity {
         this._restoreContext = null;
         // Holds the current pending save observable (if any)
         this._pendingSave$ = null;
+        /**
+         * This method is used automatically within Save() and is used to determine if the state of the object is valid relative to the validation rules that are defined in metadata. In addition, sub-classes can
+         * override or wrap this base class method to add other logic for validation.
+         *
+         * @returns ValidationResult The validation result
+         */
+        this._isValidating = false;
         /**
          * private storage for vectors that might be used for this entity, typically in association with individual fields
          * however it is possible for the string in the map to be any unique key relative to the object so you could have vectors
@@ -852,6 +1042,42 @@ export class BaseEntity {
         this._provider = Provider;
         this.init();
     }
+    /**
+     * The provider actually stored on this instance, or `null` if none was bound.
+     * Unlike {@link ProviderToUse}, this does **not** fall back to the process-wide
+     * {@link BaseEntity.Provider}. Use it to detect a dropped constructor argument:
+     * `GetEntityObject(graphProvider)` must yield `BoundProvider === graphProvider`.
+     */
+    get BoundProvider() {
+        return this._provider;
+    }
+    /**
+     * Bind this instance to a provider after construction.
+     *
+     * **Rule (ORM, not just metadata-sync):** every DB read and write on this
+     * instance — Save, Load, Delete, RunView, GetEntityObject of children/embeds,
+     * lookups, RecordGeoCode — MUST use this provider. Mixing another provider
+     * (especially the process-wide host) into the same record graph is a deadlock:
+     * a child FK waits on an uncommitted parent on another connection.
+     *
+     * {@link ProviderBase.GetEntityObject} always calls this so a subclass that
+     * declares `constructor(Entity: EntityInfo)` and drops the second ClassFactory
+     * argument cannot silently run on the global host.
+     */
+    BindProvider(provider) {
+        this._provider = provider;
+        if (this._parentEntity && this._parentEntity.BoundProvider !== provider) {
+            this._parentEntity.BindProvider(provider);
+        }
+        if (this._childEntity && this._childEntity.BoundProvider !== provider) {
+            this._childEntity.BindProvider(provider);
+        }
+        if (this._companions) {
+            for (const companion of this._companions.values()) {
+                companion.BindProvider(provider);
+            }
+        }
+    }
     /**
      * Initializes the IS-A parent entity composition chain. For child type entities,
      * this creates the parent entity instance (and recursively its parent, etc.) and
@@ -1062,6 +1288,249 @@ export class BaseEntity {
         // InitializeChildEntity is idempotent via _childEntityDiscoveryDone flag
         await childEntity.InitializeChildEntity();
     }
+    static { this._subtypeLookupCache = new Map(); }
+    /**
+     * Clears the static memoization cache used by SubtypeSelector path evaluation.
+     */
+    static ClearSubtypeLookupCache() {
+        BaseEntity._subtypeLookupCache.clear();
+    }
+    /**
+     * Prospective counterpart to FindISAChildEntity.
+     * Evaluates which IsA child subtype entity this record should have based on:
+     * 1. Registered EntitySubtypeResolver (ClassFactory key = entity name)
+     * 2. Entity.SubtypeSelector declarative FK traversal path
+     * 3. Unconditional single-child IsA fallback (ChildEntities.length === 1)
+     * 4. Otherwise null (no subtype)
+     *
+     * @see plans/sync-composition-axes.md
+     */
+    async ResolveSubtypeEntityName() {
+        if (!this.EntityInfo.IsParentType || !this.EntityInfo.ChildEntities || this.EntityInfo.ChildEntities.length === 0) {
+            return null;
+        }
+        // 1. Registered resolver override
+        const reg = MJGlobal.Instance.ClassFactory.GetRegistration(EntitySubtypeResolver, this.EntityInfo.Name);
+        if (reg) {
+            const resolution = MJGlobal.Instance.ClassFactory.TryCreateInstance(EntitySubtypeResolver, this.EntityInfo.Name);
+            if (resolution.Resolved && resolution.Instance) {
+                const raw = resolution.Instance.Resolve(this);
+                const candidate = raw instanceof Promise ? await raw : raw;
+                if (candidate != null && candidate.trim() !== '') {
+                    const trimmed = candidate.trim();
+                    const match = this.EntityInfo.ChildEntities.find(c => c.Name.trim().toLowerCase() === trimmed.toLowerCase());
+                    if (!match) {
+                        throw new Error(`EntitySubtypeResolver for '${this.EntityInfo.Name}' returned '${candidate}', which is not a declared IsA child entity of '${this.EntityInfo.Name}'.`);
+                    }
+                    return match.Name;
+                }
+                return null;
+            }
+        }
+        // 2. Entity.SubtypeSelector declarative path
+        const selectorConfig = this.EntityInfo.SubtypeSelectorConfig;
+        if (selectorConfig && selectorConfig.Path && selectorConfig.Path.trim() !== '') {
+            const pathResult = await this.evaluateSubtypeSelectorPath(selectorConfig.Path.trim());
+            if (pathResult != null && pathResult.trim() !== '') {
+                const trimmed = pathResult.trim();
+                const match = this.EntityInfo.ChildEntities.find(c => c.Name.trim().toLowerCase() === trimmed.toLowerCase());
+                if (!match) {
+                    throw new Error(`SubtypeSelector path '${selectorConfig.Path}' on '${this.EntityInfo.Name}' resolved to '${pathResult}', which is not a declared IsA child entity of '${this.EntityInfo.Name}'.`);
+                }
+                return match.Name;
+            }
+            return null;
+        }
+        // 3. Exactly one child, unconditional IsA
+        if (!this.EntityInfo.AllowMultipleSubtypes && this.EntityInfo.ChildEntities.length === 1) {
+            return this.EntityInfo.ChildEntities[0].Name;
+        }
+        // 4. Otherwise null
+        return null;
+    }
+    /**
+     * Create-safe prospective counterpart to InitializeChildEntity.
+     * Unlike createAndLinkChildEntity, does NOT unlink when InnerLoad finds no row —
+     * that is the create case. Idempotent. Defaults to ResolveSubtypeEntityName()
+     * when no name is passed.
+     *
+     * @param entityName Optional explicit child entity name. If omitted, resolved via ResolveSubtypeEntityName().
+     * @returns The linked child BaseEntity, or null if no subtype applies.
+     */
+    async EnsureISAChild(entityName) {
+        if (!entityName) {
+            entityName = await this.ResolveSubtypeEntityName();
+        }
+        if (!entityName) {
+            return null;
+        }
+        const matchedChild = this.EntityInfo.ChildEntities?.find(c => c.Name.trim().toLowerCase() === entityName.trim().toLowerCase());
+        if (!matchedChild) {
+            throw new Error(`'${entityName}' is not a declared IsA child entity of '${this.EntityInfo.Name}'.`);
+        }
+        const resolvedName = matchedChild.Name;
+        if (!this.EntityInfo.AllowMultipleSubtypes) {
+            // Disjoint hierarchy
+            if (this._childEntity) {
+                if (this._childEntity.EntityInfo.Name.trim().toLowerCase() === resolvedName.trim().toLowerCase()) {
+                    return this._childEntity; // Idempotent
+                }
+                throw new Error(`Entity '${this.EntityInfo.Name}' already has an attached child entity of type '${this._childEntity.EntityInfo.Name}', cannot attach '${resolvedName}' (AllowMultipleSubtypes is false).`);
+            }
+            const childProvider = this.ProviderToUse;
+            const childEntity = await childProvider.GetEntityObject(resolvedName, this._contextCurrentUser);
+            // Wire up shared instance chain
+            this.replaceChildParentChain(childEntity);
+            this._childEntity = childEntity;
+            const dirtySnapshots = this.captureChainDirtyState();
+            if (this.PrimaryKey && this.PrimaryKey.HasValue) {
+                const loaded = await childEntity.InnerLoad(this.PrimaryKey);
+                if (!loaded) {
+                    this.mirrorSharedKeysToChild(childEntity);
+                }
+            }
+            else {
+                this.mirrorSharedKeysToChild(childEntity);
+            }
+            this.restoreChainDirtyState(dirtySnapshots);
+            // Recursively discover grandchildren if the child is also a parent type
+            if (childEntity.EntityInfo.IsParentType) {
+                await childEntity.EnsureISAChild();
+            }
+            return childEntity;
+        }
+        else {
+            // Overlapping hierarchy (AllowMultipleSubtypes = true)
+            if (!this._childEntities) {
+                this._childEntities = [];
+            }
+            if (!this._childEntities.some(c => c.entityName.trim().toLowerCase() === resolvedName.trim().toLowerCase())) {
+                this._childEntities.push({ entityName: resolvedName });
+            }
+            const childProvider = this.ProviderToUse;
+            const childEntity = await childProvider.GetEntityObject(resolvedName, this._contextCurrentUser);
+            this.replaceChildParentChain(childEntity);
+            const dirtySnapshots = this.captureChainDirtyState();
+            if (this.PrimaryKey && this.PrimaryKey.HasValue) {
+                const loaded = await childEntity.InnerLoad(this.PrimaryKey);
+                if (!loaded) {
+                    this.mirrorSharedKeysToChild(childEntity);
+                }
+            }
+            else {
+                this.mirrorSharedKeysToChild(childEntity);
+            }
+            this.restoreChainDirtyState(dirtySnapshots);
+            if (childEntity.EntityInfo.IsParentType) {
+                await childEntity.EnsureISAChild();
+            }
+            return childEntity;
+        }
+    }
+    mirrorSharedKeysToChild(childEntity) {
+        const parentPks = this.EntityInfo.PrimaryKeys;
+        if (!parentPks || parentPks.length === 0)
+            return;
+        for (const pk of parentPks) {
+            const val = this.Get(pk.Name);
+            if (val != null) {
+                childEntity.mirrorSharedKey(pk.Name, val);
+            }
+        }
+    }
+    async evaluateSubtypeSelectorPath(path) {
+        const segments = path.split('.').map(s => s.trim()).filter(Boolean);
+        if (segments.length === 0)
+            return null;
+        let currentEntity = this;
+        let currentEntityInfo = this.EntityInfo;
+        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}'.`);
+            }
+            const fkValue = currentEntity.Get(fieldInfo.Name);
+            if (fkValue == null || fkValue === '') {
+                return null;
+            }
+            const relatedEntityName = fieldInfo.RelatedEntity;
+            if (!relatedEntityName) {
+                throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': field '${fieldName}' on entity '${currentEntityInfo.Name}' is not a foreign key relationship.`);
+            }
+            const targetEntity = await this.getSubtypePathTargetEntity(relatedEntityName, fkValue);
+            if (!targetEntity) {
+                return null;
+            }
+            currentEntity = targetEntity;
+            currentEntityInfo = targetEntity.EntityInfo;
+        }
+        const terminalSegment = segments[segments.length - 1];
+        const terminalField = currentEntityInfo.Fields.find(f => f.Name.trim().toLowerCase() === terminalSegment.toLowerCase());
+        if (!terminalField) {
+            throw new Error(`Invalid SubtypeSelector path '${path}' on '${this.EntityInfo.Name}': terminal field '${terminalSegment}' was not found on entity '${currentEntityInfo.Name}'.`);
+        }
+        const terminalValue = currentEntity.Get(terminalField.Name);
+        if (terminalValue == null || typeof terminalValue !== 'string' || terminalValue.trim() === '') {
+            return null;
+        }
+        return terminalValue.trim();
+    }
+    async getSubtypePathTargetEntity(entityName, pkValue) {
+        const cacheKey = `${entityName.trim().toLowerCase()}|${String(pkValue).trim().toLowerCase()}`;
+        if (BaseEntity._subtypeLookupCache.has(cacheKey)) {
+            return BaseEntity._subtypeLookupCache.get(cacheKey) ?? null;
+        }
+        // 1. Check BaseEngineRegistry for loaded cached entities
+        const cachedMatches = BaseEngineRegistry.Instance.FindCachedEntity(entityName);
+        if (cachedMatches && cachedMatches.length > 0) {
+            for (const match of cachedMatches) {
+                const found = match.records.find(r => {
+                    const firstPK = r.FirstPrimaryKey; // first-pk-ok: FK target — pkValue is one SubtypeSelector FK column's value
+                    if (firstPK) {
+                        return String(firstPK.Value).trim().toLowerCase() === String(pkValue).trim().toLowerCase();
+                    }
+                    return false;
+                });
+                if (found) {
+                    BaseEntity._subtypeLookupCache.set(cacheKey, found);
+                    return found;
+                }
+            }
+        }
+        // 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;
+            if (pkValue instanceof CompositeKey) {
+                key = pkValue;
+            }
+            else {
+                key = new CompositeKey();
+                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;
+            }
+        }
+        catch {
+            // On load failure, return null
+        }
+        BaseEntity._subtypeLookupCache.set(cacheKey, null);
+        return null;
+    }
     captureChainDirtyState() {
         const snapshots = [];
         let curr = this;
@@ -1102,6 +1571,10 @@ export class BaseEntity {
         // Replace it with `this`, then walk upward replacing each parent.
         let childParent = childEntity._parentEntity;
         let ourInstance = this;
+        if (!childParent) {
+            childEntity._parentEntity = this;
+            return;
+        }
         while (childParent && ourInstance) {
             // Replace the child's parent reference with our shared instance
             if (childParent === childEntity._parentEntity) {
@@ -1193,6 +1666,8 @@ export class BaseEntity {
         // ignoreNonExistentFields=true remains as a safety net; ownedFieldsFrom already
         // dropped columns that belong to another level of the IS-A chain.
         this.SetMany(this.ownedFieldsFrom(data), true, true, true);
+        // Hydrate is a hydration entry point: keys the source omitted are not-loaded.
+        this.markFieldsOmittedBySourceAsNotLoaded(data);
     }
     /**
      * Columns on `data` that this entity actually defines (by field name or CodeName).
@@ -1346,6 +1821,8 @@ export class BaseEntity {
             throw new Error(`BaseEntity.ConstructUninitializedEntity: ClassFactory could not construct '${entityName}'. ` +
                 `Ensure the entity class is registered.`);
         }
+        // Same rebind as GetEntityObject — 1-arg subclasses drop the ClassFactory provider.
+        instance.BindProvider(provider);
         await instance.Config(this.ContextCurrentUser);
         await instance.InitializeParentEntity();
         // Recurse so a *new* peer's own embeds are constructed (required nested
@@ -1434,7 +1911,10 @@ export class BaseEntity {
             }, { provider: this.ProviderToUse, user: this.ActiveUser });
             if (!result.Success || !result.Output?.Success) {
                 const detail = result.ErrorMessage ?? result.Output?.ErrorMessage ?? 'unknown error';
-                this.registerGraphFailure(detail);
+                // The structured refusal rides alongside the prose so a form can paint the fields a
+                // server-side ValidateAsync named — the same thing a plain save gets from the
+                // GraphQL error's `extensions.validationErrors`.
+                this.registerGraphFailure(detail, 'save', result.Output?.ValidationErrors);
                 this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: detail });
                 return false;
             }
@@ -1541,7 +2021,7 @@ export class BaseEntity {
         // One `RunViews` for all remaining collections — N declared collections cost one round trip,
         // not N. Params are built per collection so each keeps its own filter and ordering. The key
         // is escaped exactly as RelatedRecordCollection.Load() and the batch loader escape it.
-        const parentKeyLiteral = String(this.FirstPrimaryKey?.Value).replace(/'/g, "''");
+        const parentKeyLiteral = String(this.FirstPrimaryKey?.Value).replace(/'/g, "''"); // first-pk-ok: RelatedEntityJoinField is one FK column, so the parent key it holds is single-column by design
         const rv = new RunView(this.ProviderToUse);
         const results = await rv.RunViews(needsDatabase.map(c => ({
             EntityName: c.RelatedEntityName,
@@ -1570,7 +2050,7 @@ export class BaseEntity {
     seedEmbedLoadVisited() {
         const seeded = new Set();
         const name = this.EntityInfo?.Name;
-        const pk = this.FirstPrimaryKey?.Value;
+        const pk = this.FirstPrimaryKey?.Value; // first-pk-ok: must equal EmbeddedRecord.LoadEager's `entity:fk` cycle token, and an FK holds one column
         if (name && pk !== null && pk !== undefined && pk !== '') {
             seeded.add(`${name}:${String(pk)}`);
         }
@@ -1853,11 +2333,16 @@ export class BaseEntity {
      *
      * @param message - The failure detail.
      */
-    registerGraphFailure(message, operation = 'save') {
+    registerGraphFailure(message, operation = 'save', validationErrors) {
         const result = new BaseEntityResult();
         result.Success = false;
         result.Type = operation === 'delete' ? 'delete' : this.IsSaved ? 'update' : 'create';
         result.Message = message ?? 'Entity graph operation failed';
+        // Rehydrated into real ValidationErrorInfo instances so `LatestResult.Errors` reads exactly as
+        // it does after a local `Validate()` refusal; `[]` when the server sent none.
+        result.Errors = DeserializeValidationErrors(validationErrors);
+        // `message` is the server's CompleteMessage — the same errors, already joined — so say so.
+        result.MessageIncludesErrors = result.Errors.length > 0 && !!message;
         result.StartedAt = new Date();
         result.EndedAt = new Date();
         result.OriginalValues = this.Fields.map(f => ({ FieldName: f.CodeName, Value: f.OldValue }));
@@ -2164,6 +2649,46 @@ export class BaseEntity {
         }
         return this._fieldCache.get(lcase) || null;
     }
+    /**
+     * True when any of the named fields exists on this entity and its current value
+     * differs from the last loaded or saved value.
+     *
+     * This is the boolean form of `GetFieldByName(name)?.Dirty === true`. Prefer it at
+     * call sites that only care whether a column has been edited — pricing, validation,
+     * and "did the user type this" gates — so they do not repeat the optional-chain and
+     * do not treat a missing field as a distinct third state.
+     *
+     * Semantics:
+     * - **Unknown or blank names return `false`.** They are not dirty; they are absent.
+     *   Callers that must distinguish "no such field" from "field is clean" should use
+     *   {@link GetFieldByName} and inspect the result.
+     * - **Names are case-insensitive and trimmed**, matching {@link GetFieldByName}.
+     * - **Read-only fields are never dirty**, even if their value was overwritten internally.
+     * - **Multiple names are OR'd.** `FieldIsDirty('UnitPrice', 'ProductPriceID')` is true
+     *   if either field has been edited. An empty rest list is a single-field check.
+     *
+     * @param fieldName First field to test. A missing/blank name contributes `false`.
+     * @param more Additional field names, each OR'd with the first.
+     * @returns `true` if at least one named field exists and is dirty; otherwise `false`.
+     *
+     * @example
+     * ```ts
+     * // Single field
+     * if (line.FieldIsDirty('UnitPrice')) { ... }
+     *
+     * // Either money column was edited
+     * if (line.FieldIsDirty('UnitPrice', 'ProductPriceID')) { ... }
+     * ```
+     */
+    FieldIsDirty(fieldName, ...more) {
+        const names = more.length === 0 ? [fieldName] : [fieldName, ...more];
+        for (const name of names) {
+            if (this.GetFieldByName(name)?.Dirty === true) {
+                return true;
+            }
+        }
+        return false;
+    }
     /**
      * Convenience method to access a field by code name. This method is case-insensitive and will return null if the field is not found.
      * @param codeName
@@ -2188,26 +2713,25 @@ export class BaseEntity {
         }
         return this._codeNameCache.get(lcase) || null;
     }
-    /**
-     * Returns true if the object is Dirty, meaning something has changed since it was last saved to the database, and false otherwise. For new records, this will always return true.
-     *
-     * @remarks
-     * Dirtiness rolls up **companions** as well as fields. Without that rollup, a clean parent with
-     * three brand-new children reports `Dirty === false`, `_InnerSave` takes its not-dirty early
-     * return, and the children are silently never persisted — the save reports success and writes
-     * nothing. See {@link EntityCompanion.Dirty}.
-     */
     get Dirty() {
-        if (!this.IsSaved)
-            return true;
-        if (this.companionsDirty)
-            return true;
-        // Raw mode means LoadFromData populated us but no mutation has happened — nothing can be
-        // dirty. Avoid hydrating just to check.
-        if (!this._fieldsHydrated)
-            return this._parentEntity?.Dirty ?? false;
-        return this._Fields.some(f => f.Dirty) ||
-            (this._parentEntity?.Dirty ?? false);
+        if (this._isCheckingDirty)
+            return false;
+        this._isCheckingDirty = true;
+        try {
+            if (!this.IsSaved)
+                return true;
+            if (this.companionsDirty)
+                return true;
+            // Raw mode means LoadFromData populated us but no mutation has happened — nothing can be
+            // dirty. Avoid hydrating just to check.
+            if (!this._fieldsHydrated)
+                return this._parentEntity?.Dirty ?? false;
+            return this._Fields.some(f => f.Dirty) ||
+                (this._parentEntity?.Dirty ?? false);
+        }
+        finally {
+            this._isCheckingDirty = false;
+        }
     }
     /**
      * Whether any registered companion holds unsaved work.
@@ -2242,7 +2766,7 @@ export class BaseEntity {
      * Helper method to return just the first Primary Key
      */
     get FirstPrimaryKey() {
-        return this.PrimaryKeys[0];
+        return this.PrimaryKeys[0]; // first-pk-ok: the accessor itself
     }
     /**
      * Returns true if the record has been loaded from the database, false otherwise. This is useful to check to see if the record is in a "New Record" state or not.
@@ -2276,6 +2800,7 @@ export class BaseEntity {
             if (this.EntityInfo?.HasInactiveFields) {
                 this.AssertFieldActiveStatus(FieldName, 'BaseEntity.Set');
             }
+            this.AssertFieldReadable(FieldName);
             this.SetLocal(FieldName, Value);
         }
     }
@@ -2295,6 +2820,33 @@ export class BaseEntity {
             EntityFieldInfo.AssertEntityFieldActiveStatus(fi, caller);
         }
     }
+    /**
+     * Field-level security choke point for the strongly-typed accessor path. Throws when the
+     * acting user may not READ the field.
+     *
+     * Called by `Get()` and `Set()` — every generated typed accessor
+     * (`get Salary() { return this.Get('Salary'); }`) routes through them, so these two sites
+     * cover the whole typed surface. Gated on both READ, because a field a user cannot see is
+     * one they cannot meaningfully address by name at all; update and create denials are
+     * enforced on the write path, where a rejection can name a save rather than a keystroke.
+     *
+     * **Deliberately NOT called by `SetMany`.** That is the hydration and resolver-apply path —
+     * throwing there would break loading a record that merely CONTAINS a restricted column.
+     *
+     * **Fails open when no user resolves.** `ActiveUser` is legitimately null in plenty of
+     * server paths, and a gate that threw there would break unrelated code in ways that look
+     * 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.
+     */
+    AssertFieldReadable(fieldName) {
+        const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
+        if (denied?.has(fieldName?.trim().toLowerCase())) {
+            throw new FieldSecurityError(fieldName, this.EntityInfo.Name);
+        }
+    }
     /**
      * Internal helper that sets a field value directly on THIS entity's own Fields array
      * without IS-A routing. Used by Set() for own-fields and for mirroring parent field values.
@@ -2362,6 +2914,10 @@ export class BaseEntity {
         if (this.EntityInfo?.HasInactiveFields) {
             this.AssertFieldActiveStatus(FieldName, 'BaseEntity.Get');
         }
+        // Field security sits BEFORE the raw-mode fast path below, not after: an entity whose
+        // fields are not yet hydrated would otherwise return denied values straight out of _raw
+        // without the gate ever running.
+        this.AssertFieldReadable(FieldName);
         // Raw mode fast path: read directly from the cached data without building EntityField
         // instances. This is the dominant cost in engine warm-loads — generated typed getters
         // (e.g. `get Name() { return this.Get('Name'); }`) flow through here, so a consumer that
@@ -2518,6 +3074,13 @@ 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
@@ -2635,7 +3198,7 @@ export class BaseEntity {
     async GetRelatedEntityDataExt(re, filter = null, maxRecords = null) {
         // we need to query the database to get related entity info
         const params = EntityInfo.BuildRelationshipViewParams(this, re, filter, maxRecords);
-        const rv = new RunView();
+        const rv = new RunView(this.RunViewProviderToUse);
         const result = await rv.RunView(params, this._contextCurrentUser);
         if (result && result.Success) {
             return {
@@ -2709,6 +3272,9 @@ export class BaseEntity {
                     }
                 }
             }
+            // _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.
@@ -2716,6 +3282,22 @@ export class BaseEntity {
             this._rawConverted = null;
         }
     }
+    /**
+     * Marks every field whose key the given HYDRATION SOURCE omitted as {@link EntityField.NotLoaded}.
+     * 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.
+     */
+    markFieldsOmittedBySourceAsNotLoaded(source) {
+        if (!source || typeof source !== 'object')
+            return;
+        for (const field of this.Fields) {
+            if (source[field.Name] === undefined && source[field.CodeName] === undefined) {
+                field.MarkNotLoaded();
+            }
+        }
+    }
     /**
      * This method will copy the values from the other entity object into the current one. This is useful for things like cloning a record.
      * This method will ONLY copy values for fields that exist in the current entity object. If the other object has fields that don't exist in the current object, they will be ignored.
@@ -2729,7 +3311,9 @@ export class BaseEntity {
             for (let field of this.Fields) {
                 if (!field.IsPrimaryKey || includePrimaryKeys) {
                     const otherField = other.GetFieldByName(field.Name);
-                    if (otherField) {
+                    // Skip fields the SOURCE never loaded (D-3): copying their construction
+                    // state would masquerade a default/null as real data on this entity.
+                    if (otherField && !otherField.NotLoaded) {
                         this.Set(field.Name, otherField.Value);
                         if (replaceOldValues) {
                             field.ResetOldValue();
@@ -2800,7 +3384,7 @@ export class BaseEntity {
             // Root of an IS-A chain, or a standalone (non-IS-A) entity: generate
             // a single GUID/UUID PK here (SQL Server `uniqueidentifier` /
             // PostgreSQL `uuid`).
-            const pk = this.EntityInfo.PrimaryKeys[0];
+            const pk = this.EntityInfo.FirstPrimaryKey; // first-pk-ok: guarded by PrimaryKeys.length === 1 above
             if (!pk.AutoIncrement &&
                 pk.IsUniqueIdentifier &&
                 !this.Get(pk.Name)) {
@@ -3050,6 +3634,9 @@ export class BaseEntity {
                             `Failed to save parent entity '${this._parentEntity.EntityInfo?.Name}': ${detail}`;
                         // Surface the parent's field-level errors so the caller can act on them.
                         newResult.Errors = parentErrors;
+                        // When `detail` was built from `parentErrors` (no parent Message), `Message` already renders
+                        // them — say so, or CompleteMessage repeats every one.
+                        newResult.MessageIncludesErrors = !parentLatest?.Message && parentErrors.length > 0;
                         newResult.OriginalValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.OldValue }; });
                         newResult.EndedAt = new Date();
                         this.RegisterResultHistoryEntry(newResult);
@@ -3060,6 +3647,8 @@ export class BaseEntity {
             const type = this.IsSaved ? EntityPermissionType.Update : EntityPermissionType.Create;
             const saveSubType = this.IsSaved ? 'update' : 'create';
             this.CheckPermissions(type, true); // this will throw an error and exit out if we don't have permission
+            this.CheckFieldLevelUpdatePermissions(); // field-level security — throws if a dirty field is not updatable by this user
+            this.ApplyFieldLevelCreateSuppression(); // field-level security on INSERT — omits fields, never rejects
             // IS-A disjoint subtype enforcement: on CREATE, ensure parent record
             // isn't already claimed by another child type (e.g., can't create Meeting
             // if a Publication already exists with the same Product ID).
@@ -3279,6 +3868,14 @@ export class BaseEntity {
             // does not own (e.g. OrderHeader on Event Order Line). Keep only columns
             // this entity defines, and ignore anything leftover.
             this.SetMany(this.ownedFieldsFrom(fieldData), true, true, true);
+            // finalizeSave re-hydrates from the save RESPONSE — a hydration source. Keys it
+            // omitted (e.g. fields the server stripped for field security) must be marked
+            // not-loaded, or the defaults init() just produced would masquerade as confirmed
+            // values and be resent on the NEXT save (the create/update-response corner: a
+            // trigger/system adjustment or concurrent change would be silently stomped).
+            if (typeof fieldData === 'object' && !Array.isArray(fieldData)) {
+                this.markFieldsOmittedBySourceAsNotLoaded(fieldData);
+            }
             this._everSaved = true; // Mark as saved after successful save
             const result = this.LatestResult;
             if (result)
@@ -3398,6 +3995,158 @@ export class BaseEntity {
         else
             return bAllowed;
     }
+    /**
+     * Field-level security on the write path: rejects a save that modifies a field this user
+     * has no update permission on.
+     *
+     * ENFORCEMENT LAYER — read this before treating it as the security boundary. `BaseEntity`
+     * also runs in the browser, where this guard is trivially bypassable. The AUTHORITATIVE
+     * check is the server-side execution of this same code: the MJServer mutation resolver
+     * re-instantiates the entity and re-runs Save on the server, where the client cannot reach
+     * it. The client-side occurrence is UX and defense-in-depth — fail fast with a clear
+     * message before a network round-trip — and must never be relied on alone.
+     *
+     * UPDATE rejects; CREATE does not — see {@link ApplyFieldLevelCreateSuppression}.
+     *
+     * Note this checks DIRTY fields only. CLIENT-side that is safe on its own: nothing ever
+     * nulls a restricted value in memory, so a field the user cannot see was never loaded as
+     * null, is not dirty, and an unrelated edit saves cleanly with the restricted column
+     * keeping its stored value.
+     *
+     * SERVER-side, dirty-only is safe only because `ResolverBase.UpdateRecord` guarantees the
+     * 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
+     *    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
+     * 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.
+     *
+     * The refusal names the missing permission when the caller can READ the field, and falls back
+     * to the ambiguous "does not exist or you do not have access" wording when they cannot. See
+     * {@link FieldSecurityWriteDenialMessage} for why that split discloses nothing.
+     */
+    CheckFieldLevelUpdatePermissions() {
+        if (!this.IsSaved) {
+            return; // INSERT — handled by ApplyFieldLevelCreateSuppression, which never rejects
+        }
+        const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedUpdateFields(u));
+        if (!denied) {
+            return;
+        }
+        // Resolved once, and only if we are actually going to reject: the wording depends on
+        // whether the caller can READ the field they were refused a write on.
+        let deniedRead;
+        for (const field of this.Fields) {
+            const key = field.Name.trim().toLowerCase();
+            if (field.Dirty && denied.has(key)) {
+                LogDebug(`[FieldSecurity] Rejected save on '${this.EntityInfo.Name}': ` +
+                    `field '${field.Name}' is not updatable by this user`);
+                // A field the caller can READ gets the real reason. Both facts the ambiguous
+                // wording protects — that the column exists, and that it is restricted for them —
+                // are already theirs, so withholding the reason only tells someone a field whose
+                // values they are looking at might not exist.
+                //
+                // A field they CANNOT read keeps the ambiguous wording. Not hypothetical: SetMany
+                // 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));
+                }
+                throw deniedRead?.has(key)
+                    ? new FieldSecurityError(field.Name, this.EntityInfo.Name)
+                    : FieldSecurityError.WriteDenial(field.Name, this.EntityInfo.Name);
+            }
+        }
+    }
+    /**
+     * Field-level security on the INSERT path: marks the fields this user may not supply so the
+     * save omits them and each column takes its database default.
+     *
+     * **This never rejects, and that is deliberate.** Rejecting would be inconsistent with the
+     * read path (a denied field is simply absent, not an error) and would leak information — an
+     * error naming `Salary` confirms the field exists and is restricted, which the ambiguous
+     * denial wording exists to prevent. Silently defaulting is also what an unrestricted user
+     * gets by leaving the field blank, so a restricted user creating a record ends up with the
+     * same record SHAPE rather than a failure.
+     *
+     * The cost is that a user who supplies a value for a create-denied field gets no feedback
+     * that it was dropped, which is why the drop is logged and why the admin UI should not
+     * render the field at all.
+     *
+     * Runs on every save (clearing prior marks first) because the answer depends on the acting
+     * user, and one entity object can be saved by different users over its lifetime.
+     */
+    ApplyFieldLevelCreateSuppression() {
+        for (const field of this.Fields) {
+            field.SetCreateSuppressed(false);
+        }
+        if (this.IsSaved) {
+            return; // UPDATE — CheckFieldLevelUpdatePermissions owns that path
+        }
+        const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedCreateFields(u));
+        if (!denied) {
+            return;
+        }
+        const suppressed = [];
+        for (const field of this.Fields) {
+            if (denied.has(field.Name.trim().toLowerCase())) {
+                field.SetCreateSuppressed(true);
+                suppressed.push(field.Name);
+            }
+        }
+        if (suppressed.length > 0) {
+            LogDebug(`[FieldSecurity] Create on '${this.EntityInfo.Name}': ` +
+                `omitted field(s) ${suppressed.join(', ')}; each column takes its default`);
+        }
+    }
+    /**
+     * 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.
+     *
+     * 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) {
+            return null; // one boolean for the overwhelming majority of entities
+        }
+        const u = this.resolveActiveUserOrNull();
+        if (!u) {
+            return null; // no user resolves — fail open, see AssertFieldReadable
+        }
+        const denied = select(u);
+        return denied.size > 0 ? denied : null;
+    }
+    /**
+     * {@link ActiveUser}, but null instead of throwing when no provider is configured to resolve
+     * one from.
+     *
+     * `ActiveUser` ends in `Metadata.Provider.CurrentUser`, which throws a TypeError when there
+     * is no global provider — during early boot, in tests, or in any context that never
+     * configured one. That was harmless while only the save path consulted it, but `Get()` and
+     * `Set()` now do on every access to an FLS-enabled entity, so an unresolvable provider would
+     * turn an ordinary read into a crash.
+     *
+     * "No provider to ask" is the same answer as "no user" for this purpose, and field security
+     * fails open on both.
+     */
+    resolveActiveUserOrNull() {
+        try {
+            return this.ActiveUser ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
     ThrowPermissionError(u, type, additionalInfoMessage) {
         throw new Error(`User: ${u.Name} (ID: ${u.ID}, Email: ${u.Email})
                          Does NOT have permission to ${EntityPermissionType[type]} ${this.EntityInfo.Name} records.
@@ -3465,6 +4214,10 @@ export class BaseEntity {
                 f.ResetNeverSetFlag();
             }
             this.SetMany(data, false, true, true); // don't ignore non-existent fields, but DO replace old values
+            // InnerLoad is a hydration entry point: any field the provider's row omitted (e.g.
+            // a client-side load whose server response stripped read-denied fields) is
+            // not-loaded, so its constructor state never masquerades as data on the next save.
+            this.markFieldsOmittedBySourceAsNotLoaded(data);
             if (EntityRelationshipsToLoad) {
                 for (let relationship of EntityRelationshipsToLoad) {
                     if (data[relationship]) {
@@ -3626,6 +4379,10 @@ export class BaseEntity {
         // Hits when: subsequent LoadFromData call on an already-loaded instance, IS-A entity
         // (parent or child), or non-plain-object input. Preserves original semantics exactly.
         this.SetMany(data, true, _replaceOldValues, true); // ignore non-existent fields, but DO replace old values based on the provided param
+        if (isPlainObject) {
+            // LoadFromData is a hydration entry point: keys the source omitted are not-loaded.
+            this.markFieldsOmittedBySourceAsNotLoaded(data);
+        }
         // now, check to see if we have the primary key set, if so, we should consider ourselves
         // loaded from the database and set the _recordLoaded flag to true along with the _everSaved flag
         if (this.PrimaryKeys && this.PrimaryKeys.length > 0) {
@@ -3671,40 +4428,45 @@ export class BaseEntity {
             await this.DeserializeCompanions(payloads);
         }
     }
-    /**
-     * This method is used automatically within Save() and is used to determine if the state of the object is valid relative to the validation rules that are defined in metadata. In addition, sub-classes can
-     * override or wrap this base class method to add other logic for validation.
-     *
-     * @returns ValidationResult The validation result
-     */
     Validate() {
-        const result = new ValidationResult();
-        result.Success = true; // start off with assumption of success, if any field fails, we'll set this to false
-        // IS-A composition: validate parent entity first to collect all chain errors
-        if (this._parentEntity) {
-            const parentResult = this._parentEntity.Validate();
-            if (!parentResult.Success) {
-                result.Success = false;
-                parentResult.Errors.forEach(err => result.Errors.push(err));
+        if (this._isValidating) {
+            const emptyResult = new ValidationResult();
+            emptyResult.Success = true;
+            return emptyResult;
+        }
+        this._isValidating = true;
+        try {
+            const result = new ValidationResult();
+            result.Success = true; // start off with assumption of success, if any field fails, we'll set this to false
+            // IS-A composition: validate parent entity first to collect all chain errors
+            if (this._parentEntity) {
+                const parentResult = this._parentEntity.Validate();
+                if (!parentResult.Success) {
+                    result.Success = false;
+                    parentResult.Errors.forEach(err => result.Errors.push(err));
+                }
+            }
+            // Validate own fields — for IS-A entities, skip parent field mirrors since
+            // those are validated via _parentEntity above
+            for (let field of this.Fields) {
+                if (this._parentEntityFieldNames?.has(field.Name))
+                    continue; // skip parent field mirrors — authoritative validation is on _parentEntity
+                const err = field.Validate();
+                err.Errors.forEach(element => {
+                    result.Errors.push(element);
+                });
+                result.Success = result.Success && err.Success; // if any field fails, we fail, but keep going to get all of the validation messages
             }
+            // Companions validate LAST but still BEFORE any write, over their complete state including
+            // pending removals. That ordering is what lets a cross-child invariant — "debits must equal
+            // credits", "a confirmed order must have lines" — be enforced against the whole graph rather
+            // than discovered halfway through persisting it.
+            this.validateCompanions(result);
+            return result;
         }
-        // Validate own fields — for IS-A entities, skip parent field mirrors since
-        // those are validated via _parentEntity above
-        for (let field of this.Fields) {
-            if (this._parentEntityFieldNames?.has(field.Name))
-                continue; // skip parent field mirrors — authoritative validation is on _parentEntity
-            const err = field.Validate();
-            err.Errors.forEach(element => {
-                result.Errors.push(element);
-            });
-            result.Success = result.Success && err.Success; // if any field fails, we fail, but keep going to get all of the validation messages
+        finally {
+            this._isValidating = false;
         }
-        // Companions validate LAST but still BEFORE any write, over their complete state including
-        // pending removals. That ordering is what lets a cross-child invariant — "debits must equal
-        // credits", "a confirmed order must have lines" — be enforced against the whole graph rather
-        // than discovered halfway through persisting it.
-        this.validateCompanions(result);
-        return result;
     }
     /**
      * Fans synchronous validation out to every registered companion.
@@ -3930,6 +4692,9 @@ export class BaseEntity {
                                         `Failed to delete parent entity '${this._parentEntity.EntityInfo?.Name}': ${detail}`;
                                     // Surface the parent's field-level errors so the caller can act on them.
                                     newResult.Errors = parentErrors;
+                                    // When `detail` was built from `parentErrors` (no parent Message), `Message` already renders
+                                    // them — say so, or CompleteMessage repeats every one.
+                                    newResult.MessageIncludesErrors = !parentLatest?.Message && parentErrors.length > 0;
                                     newResult.OriginalValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.OldValue }; });
                                     newResult.EndedAt = new Date();
                                     this.RegisterResultHistoryEntry(newResult);
@@ -4020,11 +4785,12 @@ export class BaseEntity {
         if (childEntities.length === 0) {
             return { HasChildren: false, ChildEntityName: '' };
         }
-        // Use RunView to check each child entity for records with our PK
-        const rv = new RunView();
+        // Use RunView on this instance's provider — a host RunView cannot see
+        // uncommitted child rows on a graph-scoped connection.
+        const rv = new RunView(this.RunViewProviderToUse);
         const pkValue = this.PrimaryKey.Values();
         for (const childEntity of childEntities) {
-            const pkField = childEntity.PrimaryKeys[0];
+            const pkField = childEntity.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
             if (!pkField)
                 continue;
             const result = await rv.RunView({
@@ -4083,21 +4849,21 @@ export class BaseEntity {
         if (!entityInfo) {
             return { LeafEntityName: entityName, IsLeaf: true };
         }
-        return BaseEntity.ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser);
+        return BaseEntity.ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser, md);
     }
     /**
      * Internal recursive helper for leaf entity resolution.
      * Walks down the child hierarchy until no more children are found.
      */
-    static async ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser) {
+    static async ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser, provider) {
         const childEntities = entityInfo.ChildEntities;
         if (childEntities.length === 0) {
             return { LeafEntityName: entityInfo.Name, IsLeaf: true };
         }
-        const rv = new RunView();
+        const rv = new RunView((provider ?? BaseEntity.Provider));
         const pkValue = primaryKey.Values();
         for (const child of childEntities) {
-            const childPK = child.PrimaryKeys[0];
+            const childPK = child.FirstPrimaryKey; // first-pk-ok: IS-A children share the parent's single key
             if (!childPK)
                 continue;
             const result = await rv.RunView({
@@ -4109,7 +4875,7 @@ export class BaseEntity {
             }, contextUser);
             if (result?.Success && result.Results?.length > 0) {
                 // Found a child — recurse to see if there's an even more specific leaf
-                return BaseEntity.ResolveLeafEntityRecursive(child, primaryKey, contextUser);
+                return BaseEntity.ResolveLeafEntityRecursive(child, primaryKey, contextUser, provider);
             }
         }
         // No child found — this entity IS the leaf
@@ -4142,16 +4908,19 @@ export class BaseEntity {
         const pkValue = this.PrimaryKey.Values();
         if (!pkValue)
             return;
-        // Build all sibling queries and execute them in a single batch
-        const rv = new RunView();
-        const validSiblings = siblingChildEntities.filter(s => s.PrimaryKeys[0]);
+        // Build all sibling queries and execute them in a single batch on
+        // this instance's provider so an uncommitted sibling on the same
+        // graph connection is visible (host RunView would miss it).
+        const rv = new RunView(this.RunViewProviderToUse);
+        // first-pk-ok: IS-A siblings share the parent's single key
+        const validSiblings = siblingChildEntities.filter(s => s.FirstPrimaryKey); // first-pk-ok: IS-A siblings share the parent's single key
         if (validSiblings.length === 0)
             return;
         const viewParams = validSiblings.map(sibling => ({
             EntityName: sibling.Name,
-            ExtraFilter: `${sibling.PrimaryKeys[0].Name} = '${pkValue}'`,
+            ExtraFilter: `${sibling.FirstPrimaryKey.Name} = '${pkValue}'`, // first-pk-ok: IS-A shared key
             ResultType: 'simple',
-            Fields: [sibling.PrimaryKeys[0].Name],
+            Fields: [sibling.FirstPrimaryKey.Name], // first-pk-ok: IS-A shared key
             MaxRows: 1
         }));
         const results = await rv.RunViews(viewParams, this._contextCurrentUser);
@@ -4218,9 +4987,20 @@ export class BaseEntity {
         if (!f) {
             return null;
         }
-        else {
-            return this.Get(f.Name);
+        // Field security: the name field is an ordinary field and can be denied like any other.
+        // `Get()` THROWS for a denied field, and this method runs AUTOMATICALLY after every
+        // Load / LoadFromData / Save via CacheRecordName — so an unguarded read here does not
+        // hide a name, it makes the record fail to load at all, with a message about the name
+        // field that reads like the record itself is broken.
+        //
+        // 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. It also keeps a denied name
+        // OUT of the provider's record-name cache, which is keyed by entity + primary key and NOT
+        // by user — caching it would leak it to the next caller.
+        if (!this.EntityInfo.IsFieldReadableByUser(f.Name, this.ActiveUser)) {
+            return null;
         }
+        return this.Get(f.Name);
     }
     /**
      * Static Utility method to get RecordChanges for a given entityName/KeyValuePair combination
@@ -4444,7 +5224,7 @@ export class BaseEntity {
             LogError(`BaseEntity.GetDescendants(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
             return [];
         }
-        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const pkName = this.FirstPrimaryKey.Name; // first-pk-ok: getRecursiveForeignKeyField already gates hierarchy traversal to single-column keys
         const rootId = this.Get(pkName);
         if (!rootId)
             return [];
@@ -4453,7 +5233,7 @@ export class BaseEntity {
         const filter = maxDepth != null
             ? `${rootFieldName} = '${rootId}' AND ${depthFieldName} <= ${maxDepth}`
             : `${rootFieldName} = '${rootId}'`;
-        const rv = new RunView();
+        const rv = new RunView(this.RunViewProviderToUse);
         const result = await rv.RunView({
             EntityName: this.EntityInfo.Name,
             ExtraFilter: filter,
@@ -4472,7 +5252,7 @@ export class BaseEntity {
             LogError(`BaseEntity.GetAncestors(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
             return [];
         }
-        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const pkName = this.FirstPrimaryKey.Name; // first-pk-ok: getRecursiveForeignKeyField already gates hierarchy traversal to single-column keys
         const currentId = this.Get(pkName);
         const pathFieldName = `${fkField.Name}Path`;
         const depthFieldName = `${fkField.Name}Depth`;
@@ -4482,7 +5262,7 @@ export class BaseEntity {
         const rawIds = path.split('/').filter(id => id.length > 0 && id !== currentId);
         if (rawIds.length === 0)
             return [];
-        const rv = new RunView();
+        const rv = new RunView(this.RunViewProviderToUse);
         const idList = rawIds.map(id => `'${id}'`).join(',');
         const result = await rv.RunView({
             EntityName: this.EntityInfo.Name,
@@ -4502,11 +5282,11 @@ export class BaseEntity {
             LogError(`BaseEntity.GetChildren(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
             return [];
         }
-        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const pkName = this.FirstPrimaryKey.Name; // first-pk-ok: getRecursiveForeignKeyField already gates hierarchy traversal to single-column keys
         const currentId = this.Get(pkName);
         if (!currentId)
             return [];
-        const rv = new RunView();
+        const rv = new RunView(this.RunViewProviderToUse);
         const result = await rv.RunView({
             EntityName: this.EntityInfo.Name,
             ExtraFilter: `${fkField.Name} = '${currentId}'`,