@memberjunction/core 6.1.4 → 6.2.0-edge.1

package/dist/generic/baseEntity.js

@@ -8,7 +8,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 var EntityField_1;
-import { DeserializeValidationErrors, IsMemberOverridden, MJEventType, MJGlobal, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager } from '@memberjunction/global';
+import { DeserializeValidationErrors, IsMemberOverridden, MJEventType, MJGlobal, NormalizeUUID, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager, ComputeContentHashAsync } from '@memberjunction/global';
 import { GetDataHooks } from './dataHooks.js';
 import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, FieldSecurityError, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
 import { EntitySubtypeResolver } from './entitySubtypeResolver.js';
@@ -17,7 +17,7 @@ import { IsPermittedImageFieldValue, IsValidCssColor, TryParseJsonText } from '.
 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 { LogDebug, LogError, LogStatusEx } from './logging.js';
 import { CompositeKey, KeyValuePair } from './compositeKey.js';
 import { RelatedRecordCollection } from './relatedRecordCollection.js';
 import { COMPANION_PAYLOAD_KEY } from './entityCompanion.js';
@@ -26,6 +26,18 @@ import { EntitySavePlan, ExecuteEntitySavePlan } from './entitySavePlan.js';
 import { BaseRemotableOperation } from './baseRemotableOperation.js';
 import { SAVE_ENTITY_GRAPH_OPERATION_KEY, } from './saveEntityGraphOperation.js';
 import { finalize, firstValueFrom, from, of, shareReplay, Subject, switchMap } from 'rxjs';
+/**
+ * Strips the trailing spaces SQL Server and PostgreSQL pad fixed-width string columns with. Only
+ * spaces: tabs and other whitespace are data. A loop rather than `/ +$/`, which backtracks
+ * quadratically on a long run of spaces that doesn't end the string.
+ */
+function trimTrailingSpaces(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 32) {
+        end--;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
 /**
  * Represents a field in an instance of the BaseEntity class. This class is used to store the value of the field, dirty state, as well as other run-time information about the field. The class encapsulates the underlying field metadata and exposes some of the more commonly
  * used properties from the entity field metadata.
@@ -70,7 +82,7 @@ let EntityField = class EntityField {
      * entities — their fields legitimately hold metadata defaults for INSERT.
      */
     get NotLoaded() {
-        return this._NotLoaded;
+        return this._notLoaded;
     }
     /**
      * Framework-internal: hydration paths call this for each field whose key the hydration
@@ -78,7 +90,7 @@ let EntityField = class EntityField {
      * clears the flag.
      */
     MarkNotLoaded() {
-        this._NotLoaded = true;
+        this._notLoaded = true;
     }
     /**
      * True when field-level security bars this user from supplying the field's value on INSERT,
@@ -97,11 +109,11 @@ let EntityField = class EntityField {
      * users over its lifetime.
      */
     get CreateSuppressed() {
-        return this._CreateSuppressed;
+        return this._createSuppressed;
     }
     /** Framework-internal: set by the save path's field-security create gate. */
     SetCreateSuppressed(suppressed) {
-        this._CreateSuppressed = suppressed;
+        this._createSuppressed = suppressed;
     }
     get Name() {
         return this._entityFieldInfo.Name;
@@ -137,7 +149,7 @@ let EntityField = class EntityField {
      * serialization, hydration, SQL build) reads this directly and must stay assertion-free.
      */
     get Value() {
-        return this._Value;
+        return this._value;
     }
     get ReadOnly() {
         return this._entityFieldInfo.ReadOnly;
@@ -164,7 +176,7 @@ let EntityField = class EntityField {
         // No active-status assertion here — see the Value getter note. Deprecation/disabled checks
         // are enforced at BaseEntity.Get/Set/SetMany, not at this low-level accessor.
         if (!this.ReadOnly ||
-            this._NeverSet /* Allow one time set of any field because BaseEntity Object passes in ReadOnly fields when we load,
+            this._neverSet /* Allow one time set of any field because BaseEntity Object passes in ReadOnly fields when we load,
                            after that load for a given INSTANCE of an EntityField object we never set a ReadOnly Field*/) {
             // Strip trailing space-padding on fixed-width string columns
             // (`nchar`/`char`/`bpchar`). SQL Server / PG right-pad these
@@ -174,24 +186,24 @@ let EntityField = class EntityField {
             // value is the logical (un-padded) form. See
             // `EntityFieldInfo.FixedWidthColumn` for the source of truth.
             if (typeof value === 'string' && this._entityFieldInfo.FixedWidthColumn) {
-                value = value.replace(/ +$/, '');
+                value = trimTrailingSpaces(value);
             }
-            this._Value = value;
+            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;
+            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 && !wasNotLoaded &&
-                (value !== null || this._OldValue !== null)) {
+            if (this._neverSet && !wasNotLoaded &&
+                (value !== null || this._oldValue !== null)) {
                 // initial value set
-                this._OldValue = value;
+                this._oldValue = value;
             }
-            this._NeverSet = false;
+            this._neverSet = false;
         }
     }
     /**
@@ -200,7 +212,7 @@ let EntityField = class EntityField {
      * after the object is created, but only once. This is typically used in the BaseEntity class when loading an entity from an array of values or the DB and reusing an existing object.
      */
     ResetNeverSetFlag() {
-        this._NeverSet = true;
+        this._neverSet = true;
     }
     /**
      * 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.
@@ -208,19 +220,19 @@ let EntityField = class EntityField {
      * artifact, not data, and nothing that was never loaded can have been changed.
      */
     get Dirty() {
-        if (this.ReadOnly || this._NotLoaded)
+        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
+            const oldNull = this._oldValue === null || this.OldValue === undefined || Number.isNaN(this.OldValue); // check for NaN because sometimes we have old values that are NaN and we need to account for that
             const curNull = this.Value === null || this.Value === undefined || Number.isNaN(this.OldValue);
             if (oldNull && curNull)
                 return false; // BOTH are null or undefined, not dirty
             else {
-                let oldCompare = this._OldValue;
+                let oldCompare = this._oldValue;
                 let newCompare = this.Value;
-                if (this._OldValue instanceof Date) {
+                if (this._oldValue instanceof Date) {
                     // sometimes we have old values that are date objects, convert to UTC timestamp for comparison
-                    oldCompare = this._OldValue.getTime();
+                    oldCompare = this._oldValue.getTime();
                 }
                 if (this.Value instanceof Date) {
                     // and sometimes the new values are date objects, convert to UTC timestamp for comparison
@@ -348,7 +360,7 @@ let EntityField = class EntityField {
             // 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)) {
+            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
@@ -357,7 +369,7 @@ let EntityField = class EntityField {
                 }
                 else {
                     // we do have a default value, but our current value is null. If we are in an EXISTING record, this is an error, check the OldValue to determine this
-                    if (this._OldValue !== null && this._OldValue !== undefined) {
+                    if (this._oldValue !== null && this._oldValue !== undefined) {
                         result.Success = false;
                         result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} cannot be null`, null));
                     }
@@ -430,9 +442,9 @@ let EntityField = class EntityField {
         return result;
     }
     constructor(fieldInfo, Value) {
-        this._NeverSet = true;
-        this._NotLoaded = false;
-        this._CreateSuppressed = false;
+        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
@@ -525,25 +537,25 @@ let EntityField = class EntityField {
                     this.Value = fieldInfo.DefaultValue;
                 }
             }
-            this._NeverSet = true; // set this back to true because we are setting the default value and we want to be able to set this ONCE from BaseEntity when we load
+            this._neverSet = true; // set this back to true because we are setting the default value and we want to be able to set this ONCE from BaseEntity when we load
         }
         else {
             this.Value = null; // we need to set the value to null instead of being undefined as the value is defined, it is NULL
-            this._NeverSet = true; // set this back to true because we are setting the value to null;
+            this._neverSet = true; // set this back to true because we are setting the value to null;
         }
     }
     /**
      * This method will set the internal Old Value which is used to track dirty state, to the current value of the field. This effectively resets the dirty state of the field to false. Use this method sparingly.
      */
     ResetOldValue() {
-        this._OldValue = this.Value;
+        this._oldValue = this.Value;
     }
     /**
      * Restores the dirty-tracking baseline to a previously captured value.
      * Used by graph rollback so a retried save still sees the pre-attempt dirty set.
      */
     RestoreOldValue(value) {
-        this._OldValue = value;
+        this._oldValue = value;
     }
     /**
      * @deprecated No-op as of the active-status relocation. Active-status (deprecated/disabled)
@@ -563,7 +575,7 @@ let EntityField = class EntityField {
      * Returns the old value of the field. This is the value that was set when the field was last loaded from the database.
      */
     get OldValue() {
-        return this._OldValue;
+        return this._oldValue;
     }
 };
 EntityField = EntityField_1 = __decorate([
@@ -714,6 +726,10 @@ export class BaseEntityResult {
  */
 export class BaseEntityEvent {
 }
+/** Entity names compare the way metadata lookups do: trimmed and case-insensitive. */
+function sameEntityName(a, b) {
+    return a.trim().toLowerCase() === b.trim().toLowerCase();
+}
 export class BaseEntity {
     /**
      * Maximum number of `BaseEntityResult` entries retained in `_resultHistory` per entity
@@ -791,7 +807,7 @@ export class BaseEntity {
          * `BaseEntity` are reserved for paths that have already triggered hydration or paths that
          * deliberately want to inspect hydration state (e.g., `Dirty` getter).
          */
-        this._Fields = [];
+        this._fields = [];
         /**
          * Tracks whether `_Fields` has been populated. `false` while in "raw mode" (data accessible
          * via `_raw` but no EntityField instances built yet); flips to `true` after the first call to
@@ -956,6 +972,17 @@ export class BaseEntity {
          * loaded record. Reset to false on NewRecord() and init().
          */
         this._childEntityDiscoveryDone = false;
+        /**
+         * Set only while this record's parent loads it because the parent's subtype rule named it
+         * (see {@link tryLinkHintedChildEntity}); read by {@link InnerLoad}.
+         */
+        this._subtypeHintProbe = null;
+        /**
+         * Set only while {@link AttachToParent} loads this record as the parent it promotes. Child
+         * discovery then doesn't ask the subtype rule: the child row being added doesn't exist yet, so
+         * a hint would name it and miss.
+         */
+        this._skipSubtypeLoadHint = false;
         /**
          * For **overlapping** subtype parents (AllowMultipleSubtypes = true), stores
          * the list of child entity type names that have records for this PK.
@@ -1037,7 +1064,7 @@ export class BaseEntity {
          */
         this._skipEmbeddings = false;
         this._eventSubject = new Subject();
-        this._EntityInfo = Entity;
+        this._entityInfo = Entity;
         EntityInfo.AssertEntityActiveStatus(Entity, 'BaseEntity::constructor');
         this._provider = Provider;
         this.init();
@@ -1165,7 +1192,16 @@ export class BaseEntity {
             name: pk.Name,
             value: this._parentEntity.Get(pk.Name),
         }));
-        const loaded = await this._parentEntity.InnerLoad(parentKey);
+        // The parent's subtype rule isn't asked for a load hint here: it would name the child this
+        // promotion is adding, whose row doesn't exist yet, and the miss would cost a round trip.
+        this._parentEntity._skipSubtypeLoadHint = true;
+        let loaded;
+        try {
+            loaded = await this._parentEntity.InnerLoad(parentKey);
+        }
+        finally {
+            this._parentEntity._skipSubtypeLoadHint = false;
+        }
         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
@@ -1197,7 +1233,7 @@ export class BaseEntity {
         if (!this.GetFieldByName(name)) {
             return;
         }
-        this.SetLocal(name, value);
+        this.setLocal(name, value);
         this.GetFieldByName(name)?.ResetNeverSetFlag();
     }
     /**
@@ -1211,6 +1247,10 @@ export class BaseEntity {
      * This ensures that Save/Delete operations always delegate to the leaf entity,
      * running the full validation and event chain at every level.
      *
+     * For a disjoint parent, the entity's subtype rule is asked first (see
+     * {@link resolveSubtypeLoadHint}); when it names a child, that child's load, which
+     * happens anyway, checks the answer, and the discovery query runs only on a miss.
+     *
      * Must be called AFTER a record is loaded (PK must be available).
      * Skipped for entities that are not parent types or have already been discovered.
      */
@@ -1225,12 +1265,48 @@ export class BaseEntity {
             await this.discoverOverlappingChildren();
         }
         else {
-            // Disjoint: discover single child, auto-chain (current behavior)
-            const childEntityName = await this.discoverChildEntityName();
-            if (!childEntityName)
+            // Disjoint: discover the single child and auto-chain it
+            await this.initializeDisjointChildEntity();
+        }
+    }
+    /**
+     * Finds and links the one child of a loaded disjoint parent.
+     *
+     * Without a hint this is one discovery query plus the child's load. With a hint from the
+     * entity's subtype rule, the child's load checks the hint, and the discovery query runs
+     * only when that load comes back empty or wasn't tried.
+     *
+     * For well-formed data the outcome is the one the discovery query alone would give: a hint
+     * changes the number of round trips, not which child is linked or whether the load succeeds.
+     * Three benign exceptions:
+     * - a failure reading the hinted child's row falls back to the discovery query, so a transient
+     *   failure now recovers (a lasting one reads the row twice, then fails as before);
+     * - when the data breaks the disjoint rule with two child rows, the discovery query's
+     *   unordered `UNION ALL` links either one, where a hint links the one the rule names;
+     * - a provider without `FindISAChildEntity` links nothing without a hint, and the hinted child
+     *   with one.
+     */
+    async initializeDisjointChildEntity() {
+        const hintedName = await this.resolveSubtypeLoadHint();
+        const hintOutcome = hintedName
+            ? await this.tryLinkHintedChildEntity(hintedName)
+            : 'NotTried';
+        if (hintOutcome === 'Linked')
+            return;
+        const childEntityName = await this.discoverChildEntityName();
+        if (hintedName && hintOutcome === 'NotFound') {
+            if (childEntityName && sameEntityName(childEntityName, hintedName)) {
+                // The row exists but its load came back empty (for example, a row filter hides it).
+                // Loading it again would too, and the discovery-only path unlinks it the same way,
+                // after logging the empty load that the hinted attempt kept quiet.
+                BaseEntity.logLoadFoundNoRow(hintedName, this.PrimaryKey);
                 return;
-            await this.createAndLinkChildEntity(childEntityName);
+            }
+            this.reportSubtypeLoadHintMiss(hintedName, childEntityName);
         }
+        if (!childEntityName)
+            return;
+        await this.createAndLinkChildEntity(childEntityName);
     }
     /**
      * Uses the provider's FindISAChildEntity method (single UNION ALL query) to
@@ -1263,12 +1339,29 @@ export class BaseEntity {
      * Creates the child entity instance, wires up the shared instance chain
      * (child._parentEntity = this, this._childEntity = child), loads the
      * child's data, and recursively discovers further children.
+     *
+     * @returns true when the child's row loaded and the child is linked; false when the load
+     *   came back empty, in which case the link is undone.
      */
     async createAndLinkChildEntity(childEntityName) {
-        // Create child via this entity's provider so the child shares the same connection
-        // (correct in multi-provider scenarios — never the global default).
+        const childEntity = await this.createChildEntityObject(childEntityName);
+        return this.linkAndLoadChildEntity(childEntity);
+    }
+    /**
+     * Creates an unlinked child entity instance through this entity's provider, so the child
+     * shares the same connection (correct in multi-provider scenarios — never the global default).
+     */
+    async createChildEntityObject(childEntityName) {
         const childProvider = this.ProviderToUse;
-        const childEntity = await childProvider.GetEntityObject(childEntityName, this._contextCurrentUser);
+        return childProvider.GetEntityObject(childEntityName, this._contextCurrentUser);
+    }
+    /**
+     * Links `childEntity` into this entity's chain and loads its row under the shared key.
+     *
+     * @returns true when the row loaded and the child is linked; false when the load came back
+     *   empty, in which case the link is undone.
+     */
+    async linkAndLoadChildEntity(childEntity) {
         // Wire up the shared instance chain: child's parent IS this entity (same object)
         // We need to replace the child's auto-initialized parent with our existing instance
         this.replaceChildParentChain(childEntity);
@@ -1280,20 +1373,245 @@ export class BaseEntity {
         if (!loaded) {
             // Load failed — clean up the link
             this._childEntity = null;
-            return;
+            return false;
         }
         // Re-apply any pending modifications so child hydration does not overwrite unsaved in-memory edits
         this.restoreChainDirtyState(dirtySnapshots);
         // Recursively discover grandchildren (child may also be a parent type)
         // InitializeChildEntity is idempotent via _childEntityDiscoveryDone flag
         await childEntity.InitializeChildEntity();
+        return true;
+    }
+    /**
+     * Tries to link the child that the subtype rule named, by loading its row directly. That
+     * load is the check on the hint.
+     *
+     * The hint isn't tried when the child object can't be created or the user can't read that
+     * entity: the discovery-only path decides those cases, so a hint can neither expose a child
+     * nor fail a load that works without it. A failure READING the hinted row is logged and
+     * treated the same way: the discovery path runs, and reads the row again only if the discovery
+     * query finds it. A failure after the row was read (the child's hydration, its eager
+     * companions, its own child discovery) propagates, as it does on the discovery-only path.
+     *
+     * @returns `'Linked'` when the hinted child loaded and is linked, `'NotFound'` when its load
+     *   came back empty, and `'NotTried'` when it wasn't loaded or reading its row failed.
+     */
+    async tryLinkHintedChildEntity(hintedName) {
+        const childEntity = await this.createReadableHintedChild(hintedName);
+        if (!childEntity) {
+            return 'NotTried';
+        }
+        const probe = { RowReadFailed: false };
+        childEntity._subtypeHintProbe = probe;
+        try {
+            return (await this.linkAndLoadChildEntity(childEntity)) ? 'Linked' : 'NotFound';
+        }
+        catch (e) {
+            if (!probe.RowReadFailed) {
+                throw e;
+            }
+            // Nothing after the row read ran, so the parent chain and its unsaved edits are untouched.
+            this._childEntity = null;
+            LogError(`IS-A load hint: reading the '${hintedName}' row for '${this.EntityInfo.Name}' record ${this.PrimaryKey.ToString()} failed (${BaseEntity.errorText(e)}); finding the subtype with the discovery query instead.`);
+            return 'NotTried';
+        }
+        finally {
+            childEntity._subtypeHintProbe = null;
+        }
+    }
+    /**
+     * Creates the child object the subtype rule named, or returns null when the user can't read
+     * that entity. A failure to create it is logged and returns null too, so the discovery-only
+     * path decides.
+     */
+    async createReadableHintedChild(hintedName) {
+        try {
+            const childEntity = await this.createChildEntityObject(hintedName);
+            return childEntity.CheckPermissions(EntityPermissionType.Read, false) ? childEntity : null;
+        }
+        catch (e) {
+            LogError(`IS-A load hint: creating a '${hintedName}' object for '${this.EntityInfo.Name}' record ${this.PrimaryKey.ToString()} failed (${BaseEntity.errorText(e)}); finding the subtype with the discovery query instead.`);
+            return null;
+        }
+    }
+    /**
+     * Asks the entity's subtype rule which child a LOADED record has, without running a query.
+     *
+     * - A registered {@link EntitySubtypeResolver} owns the rule. It gives a hint only when its
+     *   class overrides {@link EntitySubtypeResolver.ResolveLoadHint}. A resolver that doesn't
+     *   gives none, and the `SubtypeSelector` isn't consulted in its place: at create time the
+     *   resolver overrides the selector, so the selector may not describe the same rule.
+     * - Otherwise a `SubtypeSelector` that sets `UseForLoadedRecords` is walked through rows that
+     *   loaded `BaseEngine` caches already hold. A hop that isn't cached gives no hint, not a query.
+     * - An entity with no rule gets no hint. The single-child fallback of
+     *   {@link ResolveSubtypeEntityName} is a default for new records, not a rule about existing ones.
+     * - While {@link AttachToParent} loads this record, no rule is asked: the child row being added
+     *   doesn't exist yet.
+     *
+     * An answer of "no subtype" also gives no hint: only the discovery query can tell whether an
+     * older record still has a child row.
+     *
+     * @returns A declared IsA child's entity name, or null when there is no usable hint. Never throws.
+     */
+    async resolveSubtypeLoadHint() {
+        if (this._skipSubtypeLoadHint) {
+            return null;
+        }
+        const registration = MJGlobal.Instance.ClassFactory.GetRegistration(EntitySubtypeResolver, this.EntityInfo.Name);
+        if (registration) {
+            const resolver = BaseEntity.loadHintResolverFor(this.EntityInfo.Name, registration);
+            return resolver ? this.askResolverForLoadHint(resolver) : null;
+        }
+        const selector = this.EntityInfo.SubtypeSelectorConfig;
+        const selectorPath = selector?.UseForLoadedRecords ? selector.Path?.trim() : null;
+        return selectorPath ? this.evaluateSelectorForLoadHint(selectorPath) : null;
+    }
+    /**
+     * The resolver to ask for load hints for an entity, decided once per registration and cached:
+     * null when the registered class doesn't override {@link EntitySubtypeResolver.ResolveLoadHint},
+     * which is read from the class without constructing it, or when constructing it failed.
+     */
+    static loadHintResolverFor(entityName, registration) {
+        const key = entityName.trim().toLowerCase();
+        const cached = BaseEntity._subtypeLoadHintResolvers.get(key);
+        if (cached?.Registration === registration) {
+            return cached.Resolver;
+        }
+        const resolver = BaseEntity.overridesResolveLoadHint(registration)
+            ? BaseEntity.constructLoadHintResolver(entityName)
+            : null;
+        BaseEntity._subtypeLoadHintResolvers.set(key, { Registration: registration, Resolver: resolver });
+        return resolver;
+    }
+    /** Whether a registered resolver class overrides `ResolveLoadHint`, read from its prototype. */
+    static overridesResolveLoadHint(registration) {
+        const prototype = registration.SubClass?.prototype;
+        const resolveLoadHint = prototype?.ResolveLoadHint;
+        return typeof resolveLoadHint === 'function' && resolveLoadHint !== EntitySubtypeResolver.prototype.ResolveLoadHint;
+    }
+    /**
+     * Constructs the registered resolver once, to ask it for load hints. A failure is logged and
+     * gives null; since the answer is cached, that is once per entity.
+     */
+    static constructLoadHintResolver(entityName) {
+        try {
+            const resolution = MJGlobal.Instance.ClassFactory.TryCreateInstance(EntitySubtypeResolver, entityName);
+            if (resolution.Resolved && resolution.Instance) {
+                return resolution.Instance;
+            }
+            LogError(`IS-A load hint: the EntitySubtypeResolver registered for '${entityName}' did not resolve (${resolution.Reason ?? 'no reason given'}); loading its records without a hint.`);
+        }
+        catch (e) {
+            LogError(`IS-A load hint: constructing the EntitySubtypeResolver registered for '${entityName}' failed (${BaseEntity.errorText(e)}); loading its records without a hint.`);
+        }
+        return null;
+    }
+    /**
+     * Asks the resolver for a load hint. A resolver that throws or rejects gives no hint for that
+     * record, and is logged once per entity rather than per record.
+     */
+    async askResolverForLoadHint(resolver) {
+        try {
+            // A synchronous answer is used as-is, with no extra microtask per record.
+            const raw = resolver.ResolveLoadHint(this);
+            const candidate = raw instanceof Promise ? await raw : raw;
+            return this.declaredChildForLoadHint(candidate, `EntitySubtypeResolver.ResolveLoadHint for '${this.EntityInfo.Name}'`);
+        }
+        catch (e) {
+            BaseEntity.logSubtypeLoadHintOnce(`${this.EntityInfo.Name}|resolver-failed`, () => LogError(`IS-A load hint: EntitySubtypeResolver.ResolveLoadHint for '${this.EntityInfo.Name}' failed on record ${this.PrimaryKey.ToString()} (${BaseEntity.errorText(e)}). A record it fails on loads without a hint; this is reported once per entity.`));
+            return null;
+        }
+    }
+    /**
+     * Walks the `SubtypeSelector` path through engine caches only. A path that isn't valid for
+     * this entity's metadata is logged once and gives no hint; the create path throws on it instead.
+     */
+    async evaluateSelectorForLoadHint(path) {
+        try {
+            const pathResult = await this.evaluateSubtypeSelectorPath(path, (entityName, pkValue) => BaseEntity.findSubtypePathTargetInEngineCache(entityName, pkValue));
+            return this.declaredChildForLoadHint(pathResult, `SubtypeSelector path '${path}' on '${this.EntityInfo.Name}'`);
+        }
+        catch (e) {
+            BaseEntity.logSubtypeLoadHintOnce(`${this.EntityInfo.Name}|path|${path}`, () => LogError(`IS-A load hint: ${BaseEntity.errorText(e)} Loading '${this.EntityInfo.Name}' records without a hint.`));
+            return null;
+        }
+    }
+    /**
+     * Turns a rule's answer into a declared child's canonical entity name. Empty means no subtype,
+     * which gives no hint. A name that isn't a declared IsA child is logged once and gives no hint.
+     */
+    declaredChildForLoadHint(candidate, source) {
+        const trimmed = candidate?.trim();
+        if (!trimmed) {
+            return null;
+        }
+        const match = this.findDeclaredChild(trimmed);
+        if (!match) {
+            BaseEntity.logSubtypeLoadHintOnce(`${this.EntityInfo.Name}|undeclared|${trimmed}`, () => LogError(`IS-A load hint: ${source} named '${trimmed}', which is not a declared IsA child entity of '${this.EntityInfo.Name}'. Loading the record without a hint.`));
+            return null;
+        }
+        return match.Name;
+    }
+    /**
+     * Reports a hint the data didn't bear out: the hinted child's row wasn't there.
+     *
+     * When the discovery query finds no child either, that is a normal state, not an error: core
+     * never creates a subtype row on save, so a typed record can exist without one (saved through
+     * a generic form or an import, or older than its type's subtype). It logs one verbose line per
+     * entity and hinted child. When the discovery query finds a DIFFERENT child, the rule and the
+     * data disagree, and each such load costs an extra round trip until one of them is fixed; that
+     * is logged as an error, once per entity, hinted child and child found.
+     */
+    reportSubtypeLoadHintMiss(hintedName, discoveredName) {
+        const entityName = this.EntityInfo.Name;
+        if (!discoveredName) {
+            BaseEntity.logSubtypeLoadHintOnce(`${entityName}|no-row|${hintedName}`, () => LogStatusEx({
+                message: `IS-A load hint: a '${entityName}' record whose subtype rule names '${hintedName}' has no subtype row, so its load also ran the discovery query. Normal for a record saved before its subtype row; reported once.`,
+                verboseOnly: true,
+            }));
+            return;
+        }
+        BaseEntity.logSubtypeLoadHintOnce(`${entityName}|disagree|${hintedName}|${discoveredName}`, () => LogError(`IS-A load hint: the subtype rule for '${entityName}' record ${this.PrimaryKey.ToString()} names '${hintedName}', but its subtype row is in '${discoveredName}'. The rule and the data disagree, and each such load costs an extra round trip until one of them is fixed. Reported once for this pair of subtypes.`));
+    }
+    /** Keys of load-hint messages already logged, so each is reported once rather than per record. */
+    static { this._loggedSubtypeLoadHintMessages = new Set(); }
+    /** Runs `log` the first time `key` is seen (case-insensitively), and not again until the caches are cleared. */
+    static logSubtypeLoadHintOnce(key, log) {
+        const normalizedKey = key.toLowerCase();
+        if (BaseEntity._loggedSubtypeLoadHintMessages.has(normalizedKey)) {
+            return;
+        }
+        BaseEntity._loggedSubtypeLoadHintMessages.add(normalizedKey);
+        log();
+    }
+    static errorText(e) {
+        return e instanceof Error ? e.message : String(e);
     }
     static { this._subtypeLookupCache = new Map(); }
+    /** Per entity (lowercased name): the resolver asked for load hints, decided once per registration. */
+    static { this._subtypeLoadHintResolvers = new Map(); }
+    /** Indexes over engine-cached arrays, keyed by the live array itself; see {@link findEngineCachedRow}. */
+    static { this._engineCachedRowIndexes = new WeakMap(); }
     /**
-     * Clears the static memoization cache used by SubtypeSelector path evaluation.
+     * Clears the static caches IsA subtype resolution keeps: the create path's SubtypeSelector
+     * lookup memo, the per-entity decision about which resolver gives load hints, the indexes over
+     * engine-cached rows, and the record of load-hint messages already logged, so each can be
+     * reported again.
      */
     static ClearSubtypeLookupCache() {
         BaseEntity._subtypeLookupCache.clear();
+        BaseEntity._subtypeLoadHintResolvers.clear();
+        BaseEntity._engineCachedRowIndexes = new WeakMap();
+        BaseEntity._loggedSubtypeLoadHintMessages.clear();
+    }
+    /**
+     * The declared IsA child entity named `name`, matched the way metadata lookups match names
+     * (trimmed, case-insensitive), or undefined when this entity declares no such child. The one
+     * lookup behind {@link ResolveSubtypeEntityName}, {@link EnsureISAChild} and load hints: the
+     * create path throws on a miss, the load path logs it.
+     */
+    findDeclaredChild(name) {
+        return this.EntityInfo.ChildEntities?.find(c => sameEntityName(c.Name, name));
     }
     /**
      * Prospective counterpart to FindISAChildEntity.
@@ -1303,6 +1621,12 @@ export class BaseEntity {
      * 3. Unconditional single-child IsA fallback (ChildEntities.length === 1)
      * 4. Otherwise null (no subtype)
      *
+     * This is the create-time ladder, and steps 1 and 2 may query. When a record is loaded,
+     * BaseEntity asks a narrower, query-free version of it for a hint instead: the resolver's
+     * `ResolveLoadHint` (not `Resolve`) when its class overrides it, the selector only when it sets
+     * `UseForLoadedRecords` and only through rows that loaded `BaseEngine` caches hold, and never
+     * step 3.
+     *
      * @see plans/sync-composition-axes.md
      */
     async ResolveSubtypeEntityName() {
@@ -1317,8 +1641,7 @@ export class BaseEntity {
                 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());
+                    const match = this.findDeclaredChild(candidate);
                     if (!match) {
                         throw new Error(`EntitySubtypeResolver for '${this.EntityInfo.Name}' returned '${candidate}', which is not a declared IsA child entity of '${this.EntityInfo.Name}'.`);
                     }
@@ -1330,10 +1653,9 @@ export class BaseEntity {
         // 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());
+            const pathResult = await this.evaluateSubtypeSelectorPath(selectorConfig.Path.trim(), (entityName, pkValue) => this.getSubtypePathTargetEntity(entityName, pkValue));
             if (pathResult != null && pathResult.trim() !== '') {
-                const trimmed = pathResult.trim();
-                const match = this.EntityInfo.ChildEntities.find(c => c.Name.trim().toLowerCase() === trimmed.toLowerCase());
+                const match = this.findDeclaredChild(pathResult);
                 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}'.`);
                 }
@@ -1364,7 +1686,7 @@ export class BaseEntity {
         if (!entityName) {
             return null;
         }
-        const matchedChild = this.EntityInfo.ChildEntities?.find(c => c.Name.trim().toLowerCase() === entityName.trim().toLowerCase());
+        const matchedChild = this.findDeclaredChild(entityName);
         if (!matchedChild) {
             throw new Error(`'${entityName}' is not a declared IsA child entity of '${this.EntityInfo.Name}'.`);
         }
@@ -1438,7 +1760,19 @@ export class BaseEntity {
             }
         }
     }
-    async evaluateSubtypeSelectorPath(path) {
+    /**
+     * Walks a `SubtypeSelector` path from this record to the column holding the subtype's entity
+     * name, and returns that column's value, or null when a hop's foreign key is empty, a target
+     * isn't found, or the terminal value is empty.
+     *
+     * @param path The dotted path, e.g. `ProductTypeID.ProductExtensionEntity`.
+     * @param findTarget Finds the record a foreign key points at. Create time passes a finder that
+     *   may query; load time passes one that reads engine caches only, so a hop missing from them
+     *   ends the walk with null instead of a query.
+     * @throws When the path doesn't fit this entity's metadata (a field isn't found, or a hop isn't
+     *   a foreign key).
+     */
+    async evaluateSubtypeSelectorPath(path, findTarget) {
         const segments = path.split('.').map(s => s.trim()).filter(Boolean);
         if (segments.length === 0)
             return null;
@@ -1458,7 +1792,7 @@ export class BaseEntity {
             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);
+            const targetEntity = await findTarget(relatedEntityName, fkValue);
             if (!targetEntity) {
                 return null;
             }
@@ -1482,21 +1816,10 @@ export class BaseEntity {
             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;
-                }
-            }
+        const cached = BaseEntity.findSubtypePathTargetInEngineCache(entityName, pkValue);
+        if (cached) {
+            BaseEntity._subtypeLookupCache.set(cacheKey, cached);
+            return cached;
         }
         // 2. Fall back to loading via provider
         const provider = this.ProviderToUse;
@@ -1531,6 +1854,84 @@ export class BaseEntity {
         BaseEntity._subtypeLookupCache.set(cacheKey, null);
         return null;
     }
+    /**
+     * Finds the record a `SubtypeSelector` hop points at among the entity objects that loaded
+     * `BaseEngine` caches already hold. Never queries, and never reads the create path's memo, whose
+     * entries can outlive a change to the row: engine caches are kept current by entity events.
+     *
+     * `pkValue` is one foreign-key column's value, matched against the first primary key of the
+     * cached rows' entity the way UUIDs compare (trimmed, case-insensitive).
+     *
+     * @returns The cached record, or null when no loaded engine holds it as an entity object.
+     */
+    static findSubtypePathTargetInEngineCache(entityName, pkValue) {
+        const key = NormalizeUUID(String(pkValue));
+        for (const match of BaseEngineRegistry.Instance.FindCachedEntity(entityName)) {
+            const found = BaseEntity.findEngineCachedRow(match.records, key);
+            if (found) {
+                return found;
+            }
+        }
+        return null;
+    }
+    /**
+     * Finds the row whose key is `key` in an engine's live cached array through an index over the
+     * array, not a scan per lookup. Keys are read with `Get()`, which leaves the rows an engine holds
+     * in raw mode unhydrated.
+     *
+     * The array is the engine's own and changes under the index: a refresh replaces it, and a save,
+     * delete or remote invalidation pushes a row, splices one out, or swaps one for a copy with the
+     * same key. So the index is keyed by the array itself, and rebuilt when the array's length or
+     * last element differs from when it was built, which every added or removed row changes. A hit
+     * is checked against the row now at that position, and a row that moved makes the index rebuild
+     * before the answer is trusted. A key that isn't indexed is a miss, which gives no hint on load
+     * and falls back to a query at create time, as for a row no engine caches.
+     */
+    static findEngineCachedRow(records, key) {
+        let index = BaseEntity.currentEngineCachedRowIndex(records);
+        let position = index.Positions.get(key);
+        if (position !== undefined && BaseEntity.engineCachedRowKey(records[position], index.KeyField) !== key) {
+            index = BaseEntity.buildEngineCachedRowIndex(records);
+            position = index.Positions.get(key);
+        }
+        return position === undefined ? null : records[position];
+    }
+    /** The index over `records`, rebuilt when the array's length or last element changed since it was built. */
+    static currentEngineCachedRowIndex(records) {
+        const index = BaseEntity._engineCachedRowIndexes.get(records);
+        if (index && index.Length === records.length && index.LastRow === records[records.length - 1]) {
+            return index;
+        }
+        return BaseEntity.buildEngineCachedRowIndex(records);
+    }
+    /** Indexes `records` by key. Anything that isn't an entity object (a `'simple'` cache holds plain rows) is skipped. */
+    static buildEngineCachedRowIndex(records) {
+        const firstEntityRow = records.find(r => typeof r?.Get === 'function');
+        const keyField = firstEntityRow?.EntityInfo?.FirstPrimaryKey?.Name ?? null; // first-pk-ok: FK target — a SubtypeSelector hop's foreign key holds one key value
+        const positions = new Map();
+        for (let i = 0; i < records.length; i++) {
+            const rowKey = BaseEntity.engineCachedRowKey(records[i], keyField);
+            if (rowKey !== null && !positions.has(rowKey)) {
+                positions.set(rowKey, i);
+            }
+        }
+        const index = {
+            Length: records.length,
+            LastRow: records[records.length - 1],
+            KeyField: keyField,
+            Positions: positions,
+        };
+        BaseEntity._engineCachedRowIndexes.set(records, index);
+        return index;
+    }
+    /** A cached row's key, normalized with `NormalizeUUID`; null for a row that isn't an entity object or has no key value. */
+    static engineCachedRowKey(row, keyField) {
+        if (!keyField || typeof row?.Get !== 'function') {
+            return null;
+        }
+        const value = row.Get(keyField);
+        return value == null ? null : NormalizeUUID(String(value));
+    }
     captureChainDirtyState() {
         const snapshots = [];
         let curr = this;
@@ -2280,13 +2681,13 @@ export class BaseEntity {
      * binds this via {@link ExecuteEntitySavePlan}'s `SaveSelfOnly` callback.
      */
     saveAsGraphNode(options) {
-        return this._InnerSave(options);
+        return this._innerSave(options);
     }
     /**
      * Delete-path counterpart of {@link saveAsGraphNode}.
      */
     deleteAsGraphNode(options) {
-        return this._InnerDelete(options);
+        return this._innerDelete(options);
     }
     /**
      * Captures saved/dirty baselines for every plan participant so a rolled-back
@@ -2620,12 +3021,12 @@ export class BaseEntity {
      * Access to the underlying metadata for the entity object.
      */
     get EntityInfo() {
-        return this._EntityInfo;
+        return this._entityInfo;
     }
     get Fields() {
         // Caller wants to walk Fields — promote raw data into real EntityField instances now.
         this.hydrateFieldsIfNeeded();
-        return this._Fields;
+        return this._fields;
     }
     /**
      * Convenience method to access a field by name. This method is case-insensitive and will return null if the field is not found. You can do the same thing with more fine tune controlled by accessing the Fields property directly.
@@ -2641,7 +3042,7 @@ export class BaseEntity {
         const lcase = fieldName.trim().toLowerCase(); // do this once as we will use it multiple times
         if (this._fieldCache === null) {
             this._fieldCache = new Map();
-            for (const f of this._Fields) {
+            for (const f of this._fields) {
                 if (!this._fieldCache.has(f.Name.trim().toLowerCase())) {
                     this._fieldCache.set(f.Name.trim().toLowerCase(), f);
                 }
@@ -2704,7 +3105,7 @@ export class BaseEntity {
         if (this._codeNameCache === null) {
             this._codeNameCache = new Map();
             // First-write-wins on duplicate code names — matches prior Array.find() behavior
-            for (const f of this._Fields) {
+            for (const f of this._fields) {
                 const codeKey = f.CodeName.trim().toLowerCase();
                 if (!this._codeNameCache.has(codeKey)) {
                     this._codeNameCache.set(codeKey, f);
@@ -2726,7 +3127,7 @@ export class BaseEntity {
             // dirty. Avoid hydrating just to check.
             if (!this._fieldsHydrated)
                 return this._parentEntity?.Dirty ?? false;
-            return this._Fields.some(f => f.Dirty) ||
+            return this._fields.some(f => f.Dirty) ||
                 (this._parentEntity?.Dirty ?? false);
         }
         finally {
@@ -2791,17 +3192,17 @@ export class BaseEntity {
         if (this._parentEntity && this._parentEntityFieldNames?.has(FieldName)) {
             this._parentEntity.Set(FieldName, Value); // recursive for N-level chains (parent asserts its own field)
             // Also mirror the value on our own virtual EntityField for UI compatibility
-            this.SetLocal(FieldName, Value);
+            this.setLocal(FieldName, Value);
         }
         else {
             // Active-status enforcement choke point for own-field writes. Fast-path gated on the
             // memoized EntityInfo.HasInactiveFields so all-Active entities (the overwhelming majority)
             // pay only a single cached boolean check.
             if (this.EntityInfo?.HasInactiveFields) {
-                this.AssertFieldActiveStatus(FieldName, 'BaseEntity.Set');
+                this.assertFieldActiveStatus(FieldName, 'BaseEntity.Set');
             }
-            this.AssertFieldReadable(FieldName);
-            this.SetLocal(FieldName, Value);
+            this.assertFieldReadable(FieldName);
+            this.setLocal(FieldName, Value);
         }
     }
     /**
@@ -2814,7 +3215,7 @@ export class BaseEntity {
      * Callers should gate this behind `EntityInfo.HasInactiveFields` so the common all-Active entity
      * skips the field lookup entirely.
      */
-    AssertFieldActiveStatus(fieldName, caller) {
+    assertFieldActiveStatus(fieldName, caller) {
         const fi = this.EntityInfo?.FieldByName(fieldName);
         if (fi) {
             EntityFieldInfo.AssertEntityFieldActiveStatus(fi, caller);
@@ -2841,7 +3242,7 @@ export class BaseEntity {
      * build) reads `EntityField.Value` directly and never routes through here — that exemption
      * is load-bearing, not an oversight. Do not "fix" it.
      */
-    AssertFieldReadable(fieldName) {
+    assertFieldReadable(fieldName) {
         const denied = this.deniedFieldsForActiveUser(u => this.EntityInfo.GetDeniedReadFields(u));
         if (denied?.has(fieldName?.trim().toLowerCase())) {
             throw new FieldSecurityError(fieldName, this.EntityInfo.Name);
@@ -2851,7 +3252,7 @@ export class BaseEntity {
      * 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.
      */
-    SetLocal(FieldName, Value) {
+    setLocal(FieldName, Value) {
         const field = this.GetFieldByName(FieldName);
         if (field != null) {
             if (field.EntityFieldInfo.TSType === EntityFieldTSType.Date && (typeof Value === 'string' || typeof Value === 'number')) {
@@ -2912,12 +3313,12 @@ export class BaseEntity {
         // EntityInfo.HasInactiveFields so all-Active entities pay only a single cached boolean check
         // before the hot read paths below.
         if (this.EntityInfo?.HasInactiveFields) {
-            this.AssertFieldActiveStatus(FieldName, 'BaseEntity.Get');
+            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);
+        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
@@ -2931,7 +3332,7 @@ export class BaseEntity {
             // back into `_raw` — the row may be shared, frozen cache state. Fields needing no
             // conversion (the vast majority) never touch the memo at all, so the fast path stays
             // a single property read.
-            const fi = this._EntityInfo?.FieldByName(FieldName);
+            const fi = this._entityInfo?.FieldByName(FieldName);
             if (fi?.TSType === EntityFieldTSType.Date && (typeof value === 'string' || typeof value === 'number')) {
                 const memo = this._rawConverted?.get(FieldName);
                 if (memo !== undefined)
@@ -2945,7 +3346,7 @@ export class BaseEntity {
                 const memo = this._rawConverted?.get(FieldName);
                 if (memo !== undefined)
                     return memo;
-                value = value.replace(/ +$/, '');
+                value = trimTrailingSpaces(value);
                 this.memoizeRawConversion(FieldName, value);
             }
             return value;
@@ -2991,7 +3392,7 @@ export class BaseEntity {
                     EntityFieldInfo.AssertEntityFieldActiveStatus(field.EntityFieldInfo, 'BaseEntity.SetMany');
                 }
                 // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
-                this.SetLocal(key, object[key]);
+                this.setLocal(key, object[key]);
                 if (replaceOldValues) {
                     field.ResetOldValue();
                 }
@@ -3005,7 +3406,7 @@ export class BaseEntity {
                         EntityFieldInfo.AssertEntityFieldActiveStatus(field.EntityFieldInfo, 'BaseEntity.SetMany');
                     }
                     // Use SetLocal here so we set on OUR fields (mirrors for parent fields)
-                    this.SetLocal(field.Name, object[key]);
+                    this.setLocal(field.Name, object[key]);
                     if (replaceOldValues) {
                         field.ResetOldValue();
                     }
@@ -3045,7 +3446,7 @@ export class BaseEntity {
         // load — without this, the parent would think it's a new record and attempt CREATE
         // instead of UPDATE on save.
         if (replaceOldValues) {
-            this.UpdateSavedStateFromPrimaryKeys();
+            this.updateSavedStateFromPrimaryKeys();
         }
     }
     /**
@@ -3053,7 +3454,7 @@ export class BaseEntity {
      * a saved/loaded record. This enables entities populated via SetMany (e.g., IS-A parent
      * entities) to correctly recognize themselves as existing records.
      */
-    UpdateSavedStateFromPrimaryKeys() {
+    updateSavedStateFromPrimaryKeys() {
         if (!this.PrimaryKeys || this.PrimaryKeys.length === 0)
             return;
         const allPKsSet = this.PrimaryKeys.every(pk => pk.Value !== null && pk.Value !== undefined);
@@ -3118,6 +3519,49 @@ export class BaseEntity {
     GetChangesSinceLastSave() {
         return this.GetAll(false, true);
     }
+    /**
+     * Computes a deterministic SHA-256 content hash of the entity's field values using
+     * the canonicalizer and Web Crypto API from `@memberjunction/global`.
+     *
+     * By default, hashes all loaded non-system fields (excluding `__mj_*` columns).
+     * The result is byte-for-byte identical across client and server tiers.
+     *
+     * @param options Optional configuration specifying subset of fields and/or whether to exclude system fields.
+     */
+    async ComputeContentHash(options) {
+        const excludeSystem = options?.ExcludeSystemFields ?? true;
+        const allData = this.GetAll(false, false);
+        // If specific fields are requested, validate each exists (case-insensitively) and resolve canonical name
+        let targetFieldNames;
+        if (options?.Fields && options.Fields.length > 0) {
+            targetFieldNames = options.Fields.map((req) => {
+                const fieldInfo = this.GetFieldByName(req);
+                if (!fieldInfo) {
+                    throw new Error(`ComputeContentHash: field '${req}' does not exist on entity '${this.EntityInfo.Name}'`);
+                }
+                return fieldInfo.Name;
+            });
+        }
+        else {
+            targetFieldNames = Object.keys(allData);
+        }
+        const excludeSet = new Set((options?.ExcludeFields ?? []).map((f) => f.trim().toLowerCase()));
+        const data = {};
+        for (const name of targetFieldNames) {
+            if (excludeSystem && name.startsWith('__mj_'))
+                continue;
+            if (excludeSet.has(name.toLowerCase()))
+                continue;
+            const val = allData[name];
+            if (val !== undefined) {
+                data[name] = val;
+            }
+        }
+        if (Object.keys(data).length === 0) {
+            throw new Error(`ComputeContentHash: cannot compute content hash on empty basis for entity '${this.EntityInfo.Name}'`);
+        }
+        return ComputeContentHashAsync(data);
+    }
     /**
      * This utility method calls GetDataObject() internally and formats the result as a JSON string. If you want to get the data as an object instead of a string, call GetDataObject() directly.
      * @param params
@@ -3154,8 +3598,8 @@ export class BaseEntity {
         }
         if (params.includeRelatedEntityData) {
             // now, get the related entity data
-            for (let i = 0; i < this._EntityInfo.RelatedEntities.length; i++) {
-                const re = this._EntityInfo.RelatedEntities[i];
+            for (let i = 0; i < this._entityInfo.RelatedEntities.length; i++) {
+                const re = this._entityInfo.RelatedEntities[i];
                 const pre = params.relatedEntityList ? params.relatedEntityList.find(r => r.relatedEntityName === re.RelatedEntity) : null;
                 if (pre) {
                     // pre now has the param that matches the related entity (re) that we are looking at
@@ -3213,7 +3657,7 @@ export class BaseEntity {
         this._compositeKey = null;
         this._resultHistory = [];
         this._recordLoaded = false;
-        this._Fields = [];
+        this._fields = [];
         this._fieldsHydrated = false;
         this._raw = null;
         this._rawConverted = null;
@@ -3249,14 +3693,14 @@ export class BaseEntity {
         for (const rawField of this.EntityInfo.Fields) {
             const key = this.EntityInfo.Name + '.' + rawField.Name;
             const newField = MJGlobal.Instance.ClassFactory.CreateInstance(EntityField, key, rawField);
-            this._Fields.push(newField);
+            this._fields.push(newField);
         }
         // 2. If we have raw data from LoadFromData, populate Fields. The first set of each Field
         //    runs through the EntityField setter with `_NeverSet=true`, which simultaneously sets
         //    Value AND OldValue (so the field is not marked dirty). This matches the old
         //    SetMany(replaceOldValues=true) semantics on initial load.
         if (this._raw) {
-            for (const field of this._Fields) {
+            for (const field of this._fields) {
                 const value = this._raw[field.Name];
                 if (value !== undefined) {
                     // Populating fields from the loaded row writes EntityField.Value directly, which does
@@ -3368,7 +3812,7 @@ export class BaseEntity {
             for (const pk of this.EntityInfo.PrimaryKeys) {
                 const parentValue = this._parentEntity.Get(pk.Name);
                 if (parentValue != null) {
-                    this.SetLocal(pk.Name, parentValue);
+                    this.setLocal(pk.Name, parentValue);
                     // The shared PK is ReadOnly, so SetLocal above consumed its
                     // one-time write (_NeverSet -> false). Restore _NeverSet so the
                     // child's OWN mirror can be re-written if the shared key is set
@@ -3520,7 +3964,7 @@ export class BaseEntity {
         // Root.Save() would wait on the first _pendingSave$ (which is itself waiting
         // for the leaf chain), creating a circular wait that hangs forever.
         if (options?.IsParentEntitySave) {
-            return this._InnerSave(options);
+            return this._innerSave(options);
         }
         // If a save is already in progress, return its promise. This check MUST run before graph
         // routing: a composite save is still a save, and two concurrent Save() calls on one record
@@ -3561,7 +4005,7 @@ export class BaseEntity {
         // Create a new observable that debounces duplicative calls, and executes the save.
         this._pendingSave$ = of(options).pipe(
         // Execute the actual save logic.
-        switchMap(opts => from(this._InnerSave(opts))), 
+        switchMap(opts => from(this._innerSave(opts))), 
         // When the save completes (whether successfully or not), clear the pending save observable.
         finalize(() => { this._pendingSave$ = null; }), 
         // Ensure that all subscribers get the same result.
@@ -3574,7 +4018,7 @@ export class BaseEntity {
      * @param options
      * @returns
      */
-    async _InnerSave(options) {
+    async _innerSave(options) {
         const currentResultCount = this.ResultHistory.length;
         const newResult = new BaseEntityResult();
         newResult.StartedAt = new Date();
@@ -3722,7 +4166,7 @@ export class BaseEntity {
                     }
                     if (valResult.Success) {
                         // Run registered PreSave hooks (e.g., tenant validation)
-                        await this.RunPreSaveHooks();
+                        await this.runPreSaveHooks();
                         // Optimistic-UI hook: every pre-flight check (Validate, ValidateAsync,
                         // PreSave hooks) has passed and the DB write is imminent. Fire the optional
                         // OnValidated callback so a UI can render the now-known-valid change before
@@ -3824,7 +4268,7 @@ export class BaseEntity {
      * Runs all registered PreSave hooks. If any hook returns false or a string
      * (error message), the save is rejected by throwing an Error.
      */
-    async RunPreSaveHooks() {
+    async runPreSaveHooks() {
         const preSaveHooks = GetDataHooks('PreSave');
         for (const hook of preSaveHooks) {
             const hookResult = await hook(this, this.ActiveUser);
@@ -3881,7 +4325,7 @@ export class BaseEntity {
             if (result)
                 result.NewValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.Value }; }); // set the latest values here
             // Cache the record name for faster lookups (updates cache with potentially new name)
-            this.CacheRecordName();
+            this.cacheRecordName();
             this.RaiseEvent('save', null, saveSubType);
             return true;
         }
@@ -3901,7 +4345,7 @@ export class BaseEntity {
      * Caches the entity record name in the provider's EntityRecordNameCache for faster lookups.
      * Called automatically after successful Load(), LoadFromData(), and Save() operations.
      */
-    CacheRecordName() {
+    cacheRecordName() {
         // Only cache if we have a valid primary key
         if (!this.PrimaryKey || !this.PrimaryKey.HasValue) {
             return;
@@ -4192,9 +4636,12 @@ export class BaseEntity {
             if (!this.IsSaved) {
                 this.init(); // wipe out current data if we're loading on top of existing record
             }
-            const data = await this.ProviderToUse.Load(this, CompositeKey, EntityRelationshipsToLoad, this.ActiveUser);
+            const data = await this.readRowForLoad(CompositeKey, EntityRelationshipsToLoad);
             if (!data) {
-                LogError(`Error in BaseEntity.Load(${this.EntityInfo.Name}, Key: ${CompositeKey.ToString()}`);
+                // A subtype-hint probe asks whether this row exists, so "no" is an answer, not an error
+                if (!this._subtypeHintProbe) {
+                    BaseEntity.logLoadFoundNoRow(this.EntityInfo.Name, CompositeKey);
+                }
                 return false; // no data loaded, return false
             }
             // IS-A: hydrate parent chain from loaded data before populating self.
@@ -4230,7 +4677,7 @@ export class BaseEntity {
             this._everSaved = true; // Mark as saved since we loaded from database
             this._compositeKey = CompositeKey; // set the composite key to the one we just loaded
             // Cache the record name for faster lookups
-            this.CacheRecordName();
+            this.cacheRecordName();
             // IS-A: discover child entity records after load completes.
             // This populates _childEntity so Save/Delete can delegate to the leaf.
             // Only runs for parent-type entities; idempotent via _childEntityDiscoveryDone.
@@ -4253,6 +4700,27 @@ export class BaseEntity {
             this._isLoading = false;
         }
     }
+    /**
+     * The provider's read of the row {@link InnerLoad} loads. While this record is a subtype-hint
+     * probe, a throw from the read is recorded on the probe before it propagates, so the parent
+     * that asked can tell it apart from a failure after the row loaded.
+     */
+    async readRowForLoad(key, relationshipsToLoad) {
+        const user = this.ActiveUser;
+        try {
+            return await this.ProviderToUse.Load(this, key, relationshipsToLoad, user);
+        }
+        catch (e) {
+            if (this._subtypeHintProbe) {
+                this._subtypeHintProbe.RowReadFailed = true;
+            }
+            throw e;
+        }
+    }
+    /** The error {@link InnerLoad} logs when the provider finds no row for the key. */
+    static logLoadFoundNoRow(entityName, key) {
+        LogError(`Error in BaseEntity.Load(${entityName}, Key: ${key.ToString()}`);
+    }
     /**
      * Re-fetches the current record from the database using its existing primary key, replacing all in-memory field values
      * with the latest data from the database. This is useful when you know (or suspect) the record has been modified externally
@@ -4340,7 +4808,7 @@ export class BaseEntity {
         const isPlainObject = data && typeof data === 'object' && !Array.isArray(data) && !(data instanceof Date);
         const canTakeFastPath = isPlainObject &&
             !this._fieldsHydrated &&
-            this._Fields.length === 0 &&
+            this._fields.length === 0 &&
             !this._parentEntity &&
             !this.EntityInfo?.IsParentType;
         if (canTakeFastPath) {
@@ -4396,7 +4864,7 @@ export class BaseEntity {
             }
             // Cache the record name for faster lookups if successfully loaded
             if (this._recordLoaded) {
-                this.CacheRecordName();
+                this.cacheRecordName();
                 // IS-A: discover child entity records after data load completes.
                 await this.InitializeChildEntity();
             }
@@ -4578,7 +5046,7 @@ export class BaseEntity {
         // Create a new observable that debounces duplicative calls, and executes the delete.
         this._pendingDelete$ = of(options).pipe(
         // Execute the actual delete logic.
-        switchMap(opts => from(this._InnerDelete(opts))), 
+        switchMap(opts => from(this._innerDelete(opts))), 
         // When the delete completes (whether successfully or not), clear the pending delete observable.
         finalize(() => { this._pendingDelete$ = null; }), 
         // Ensure that all subscribers get the same result.
@@ -4591,7 +5059,7 @@ export class BaseEntity {
      * @param options
      * @returns
      */
-    async _InnerDelete(options) {
+    async _innerDelete(options) {
         const currentResultCount = this.ResultHistory.length;
         const newResult = new BaseEntityResult();
         newResult.StartedAt = new Date();
@@ -4849,13 +5317,13 @@ export class BaseEntity {
         if (!entityInfo) {
             return { LeafEntityName: entityName, IsLeaf: true };
         }
-        return BaseEntity.ResolveLeafEntityRecursive(entityInfo, primaryKey, contextUser, md);
+        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, provider) {
+    static async resolveLeafEntityRecursive(entityInfo, primaryKey, contextUser, provider) {
         const childEntities = entityInfo.ChildEntities;
         if (childEntities.length === 0) {
             return { LeafEntityName: entityInfo.Name, IsLeaf: true };
@@ -4875,7 +5343,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, provider);
+                return BaseEntity.resolveLeafEntityRecursive(child, primaryKey, contextUser, provider);
             }
         }
         // No child found — this entity IS the leaf