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

package/dist/generic/baseEntity.js

@@ -11,11 +11,14 @@ var EntityField_1;
 import { 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 { 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';
@@ -327,6 +330,35 @@ 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;
     }
@@ -505,6 +537,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 +596,26 @@ 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
+        // 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 until a producer-side fix removes it at the source.
         if (this.Errors && this.Errors.length > 0) {
             // 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 +901,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 +928,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 +954,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
@@ -874,6 +1012,106 @@ export class BaseEntity {
         // Cache the parent field names for O(1) routing lookups
         this._parentEntityFieldNames = this.EntityInfo.ParentEntityFieldNames;
     }
+    /**
+     * IS-A PROMOTION (#3825): binds this NEW child record to an EXISTING parent row, so saving it
+     * ADDS a subtype to a person/org/product that already exists instead of trying to create a
+     * duplicate parent.
+     *
+     * Before this existed the operation was impossible: `NewRecord()` always starts a fresh parent
+     * chain, so "this existing Person is now also an Applicant" INSERTed a second Person and
+     * collided with the existing primary key (or, with parent fields unset, failed the parent's
+     * NOT NULL validation as if it were brand new). Discovery ran the other way only — a loaded
+     * parent finds its existing child — and promotion is the normal case in a multi-app install,
+     * where a shared entity like Person accumulates subtypes owned by different applications.
+     *
+     * What it does, in the existing machinery rather than beside it:
+     *  1. LOADS the parent chain by the supplied key (`InnerLoad`, which also hydrates any
+     *     grandparents from the same row). A loaded parent saves as an UPDATE, which is the whole
+     *     trick — the chain save that already runs parent-first now updates the existing row and
+     *     INSERTs only this child.
+     *  2. Mirrors the shared primary key into this child's local fields, restoring `_NeverSet`
+     *     exactly as `NewRecord()`'s adoption path does, so the ReadOnly mirror stays writable for
+     *     the rest of the lifecycle.
+     *
+     * Everything else is deliberately UNTOUCHED: field routing still sends parent-held values to
+     * the (now loaded) parent, permissions and validation run at every level, and
+     * `EnforceDisjointSubtype` still refuses a second subtype where the parent forbids overlap.
+     * If loading the parent discovers an existing child of ANOTHER subtype, the chain save is
+     * unaffected — parent saves run with `IsParentEntitySave`, which bypasses leaf delegation.
+     *
+     * Call AFTER `NewRecord()` and BEFORE `Save()`:
+     * ```typescript
+     * const applicant = await md.GetEntityObject<ApplicantEntity>('Applicants', contextUser);
+     * applicant.NewRecord();
+     * if (!await applicant.AttachToParent(CompositeKey.FromID(personId))) {
+     *     // no such parent row — decide whether to create a fresh chain instead
+     * }
+     * applicant.Set('CompanyID', companyId);   // child-held fields as usual
+     * await applicant.Save();                  // Person UPDATEd, Applicant INSERTed, one transaction
+     * ```
+     *
+     * @param parentKey Primary key of the EXISTING parent row to promote.
+     * @returns `true` when the parent loaded and this record is now bound to it; `false` when no
+     *   parent row exists under that key (this record is left exactly as it was — still a fresh
+     *   chain — so the caller can choose to save it as one).
+     * @throws When this entity is not an IS-A child type, or has already been saved — promotion
+     *   is a decision about what a NEW record IS, not an edit to an existing one.
+     */
+    async AttachToParent(parentKey) {
+        if (!this.EntityInfo.IsChildType || !this._parentEntity) {
+            throw new Error(`AttachToParent: '${this.EntityInfo.Name}' is not an IS-A child type — there is no parent to attach to.`);
+        }
+        if (this.IsSaved) {
+            throw new Error(`AttachToParent: '${this.EntityInfo.Name}' record is already saved. Promotion binds a NEW record to an existing parent; it cannot re-parent a saved one.`);
+        }
+        // The PARENT's primary keys drive everything here, not the child's. The shared-PK mirror
+        // is a same-name convention, and a child EntityInfo is not obliged to re-declare the key as
+        // its own PrimaryKey — iterating the child's list silently does nothing on such a schema,
+        // which is exactly the empty-loop bug the first draft of this method had.
+        const parentPks = this._parentEntity.EntityInfo.PrimaryKeys;
+        // Captured BEFORE the load: InnerLoad wipes the parent chain's state before it reads, so a
+        // MISSING parent row would otherwise leave the fresh chain gutted — root PK nulled, record
+        // unsaveable — when the contract is "left exactly as it was, so the caller can still save
+        // it as a fresh chain".
+        const freshPkValues = parentPks.map(pk => ({
+            name: pk.Name,
+            value: this._parentEntity.Get(pk.Name),
+        }));
+        const loaded = await this._parentEntity.InnerLoad(parentKey);
+        if (!loaded) {
+            // Restore the fresh chain the failed load destroyed: re-seed the parent chain, then put
+            // the ORIGINAL minted key back (Set routes to the root), so the record the caller holds
+            // is bit-for-bit the fresh record they built.
+            this._parentEntity.NewRecord();
+            for (const pk of freshPkValues) {
+                if (pk.value != null) {
+                    this._parentEntity.Set(pk.name, pk.value);
+                    this.mirrorSharedKey(pk.name, pk.value);
+                }
+            }
+            return false;
+        }
+        for (const pk of parentPks) {
+            const parentValue = this._parentEntity.Get(pk.Name);
+            if (parentValue != null) {
+                this.mirrorSharedKey(pk.Name, parentValue);
+            }
+        }
+        return true;
+    }
+    /**
+     * Writes one shared-key value onto this child's LOCAL mirror, when a same-named field exists —
+     * a schema that leaves the shared key entirely to routing has no mirror to maintain, and that
+     * is fine. Restores `_NeverSet` exactly as `NewRecord()`'s adoption path does, so the ReadOnly
+     * mirror stays writable for the rest of the lifecycle.
+     */
+    mirrorSharedKey(name, value) {
+        if (!this.GetFieldByName(name)) {
+            return;
+        }
+        this.SetLocal(name, value);
+        this.GetFieldByName(name)?.ResetNeverSetFlag();
+    }
     /**
      * Discovers and initializes the IS-A child entity for a loaded record.
      *
@@ -962,6 +1200,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;
@@ -1002,6 +1483,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) {
@@ -1246,6 +1731,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
@@ -1441,7 +1928,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,
@@ -1470,7 +1957,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)}`);
         }
@@ -2064,6 +2551,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
@@ -2088,26 +2615,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.
@@ -2142,7 +2668,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.
@@ -2535,7 +3061,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 {
@@ -2700,7 +3226,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)) {
@@ -3571,40 +4097,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.
@@ -3920,11 +4451,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({
@@ -3983,21 +4515,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({
@@ -4009,7 +4541,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
@@ -4042,16 +4574,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);
@@ -4344,7 +4879,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 [];
@@ -4353,7 +4888,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,
@@ -4372,7 +4907,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`;
@@ -4382,7 +4917,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,
@@ -4402,11 +4937,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}'`,