@memberjunction/core 6.2.0-edge.0 → 6.2.0-edge.2

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, ComputeContentHashAsync } 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,41 @@ 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;
+    }
+    /**
+     * Framework-internal: the field's value and dirty-tracking state, so a unit of work that rolls
+     * back can put them back with {@link RestoreState}.
+     */
+    GetState() {
+        return { Value: this._value, OldValue: this._oldValue, NotLoaded: this._notLoaded, NeverSet: this._neverSet };
+    }
+    /**
+     * Framework-internal: puts back a state {@link GetState} captured. It writes the state as it was,
+     * so the read-only and first-set rules of the {@link Value} setter don't apply.
+     */
+    RestoreState(state) {
+        this._value = state.Value;
+        this._oldValue = state.OldValue;
+        this._notLoaded = state.NotLoaded;
+        this._neverSet = state.NeverSet;
     }
     /**
      * @deprecated No-op as of the active-status relocation. Active-status (deprecated/disabled)
@@ -563,7 +591,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([
@@ -571,6 +599,13 @@ EntityField = EntityField_1 = __decorate([
     __metadata("design:paramtypes", [EntityFieldInfo, Object])
 ], EntityField);
 export { EntityField };
+/**
+ * The `ChangeContext` JSON a clone writes on its Record Change rows (`IRecordChangeContext`,
+ * Kind 'Clone'). The one serializer every provider path uses, so the shape can't drift.
+ */
+export function SerializeCloneChangeContext(context) {
+    return JSON.stringify({ Version: 1, Kind: 'Clone', Clone: context });
+}
 export class DataObjectRelatedEntityParam {
 }
 export class DataObjectParams {
@@ -714,6 +749,13 @@ 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();
+}
+/**
+ * Base class used for all entity objects. This class is abstract and is sub-classes for each particular entity using the CodeGen tool. This class provides the basic functionality for loading, saving, and validating entity objects.
+ */
 export class BaseEntity {
     /**
      * Maximum number of `BaseEntityResult` entries retained in `_resultHistory` per entity
@@ -791,7 +833,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 +998,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.
@@ -982,6 +1035,12 @@ export class BaseEntity {
          * routing through the provider: participants stay ignorant of one another.
          */
         this._entityTransactionScope = null;
+        /**
+         * The unit of work this record is saved or deleted in, while it runs as part of a larger one: an
+         * IS-A chain's initiator sets it on each parent for the parent's write, and a graph sets it on
+         * each of its records. See {@link UnitOfWork}.
+         */
+        this._unitOfWork = null;
         /**
          * Companions registered on this entity, keyed by {@link EntityCompanion.Name}.
          *
@@ -1014,6 +1073,7 @@ export class BaseEntity {
         // provider may capture the context now but use it later.
         // ────────────────────────────────────────────────────────────────────
         this._restoreContext = null;
+        this._cloneContext = null;
         // Holds the current pending save observable (if any)
         this._pendingSave$ = null;
         /**
@@ -1037,7 +1097,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();
@@ -1096,10 +1156,27 @@ export class BaseEntity {
         // route the parent through the same connection — not the global default.
         const parentProvider = this.ProviderToUse;
         this._parentEntity = await parentProvider.GetEntityObject(parentEntityInfo.Name, this._contextCurrentUser);
+        // A chain loaded through the parent is linked the other way too, so the parent's
+        // LeafEntity (and its save hooks) see this child (MJ#4870).
+        this.linkParentBackToThisChild();
         // Recursive: the parent's InitializeParentEntity() was called by GetEntityObject()
         // Cache the parent field names for O(1) routing lookups
         this._parentEntityFieldNames = this.EntityInfo.ParentEntityFieldNames;
     }
+    /**
+     * Points this child's disjoint parent back at this instance (`parent._childEntity = this`).
+     *
+     * Same gate as {@link InitializeParentEntity}: a parent that allows several subtypes keeps no
+     * single child. `NewRecord()` sets `_childEntity` to null, so this has to run AFTER the
+     * parent's `NewRecord()` — calling it before is wiped out.
+     */
+    linkParentBackToThisChild() {
+        const parentEntityInfo = this.EntityInfo?.ParentEntityInfo;
+        if (!this._parentEntity || !parentEntityInfo || parentEntityInfo.AllowMultipleSubtypes) {
+            return;
+        }
+        this._parentEntity._childEntity = this;
+    }
     /**
      * 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
@@ -1165,12 +1242,22 @@ 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
-            // is bit-for-bit the fresh record they built.
+            // is bit-for-bit the fresh record they built. Re-seed nulls the parent's back-link.
             this._parentEntity.NewRecord();
+            this.linkParentBackToThisChild();
             for (const pk of freshPkValues) {
                 if (pk.value != null) {
                     this._parentEntity.Set(pk.name, pk.value);
@@ -1197,7 +1284,7 @@ export class BaseEntity {
         if (!this.GetFieldByName(name)) {
             return;
         }
-        this.SetLocal(name, value);
+        this.setLocal(name, value);
         this.GetFieldByName(name)?.ResetNeverSetFlag();
     }
     /**
@@ -1211,6 +1298,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 +1316,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 +1390,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 +1424,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 +1672,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 +1692,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 +1704,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 +1737,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}'.`);
         }
@@ -1383,15 +1756,7 @@ export class BaseEntity {
             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);
-            }
+            await this.loadOrMirrorChildRow(childEntity);
             this.restoreChainDirtyState(dirtySnapshots);
             // Recursively discover grandchildren if the child is also a parent type
             if (childEntity.EntityInfo.IsParentType) {
@@ -1411,15 +1776,7 @@ export class BaseEntity {
             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);
-            }
+            await this.loadOrMirrorChildRow(childEntity);
             this.restoreChainDirtyState(dirtySnapshots);
             if (childEntity.EntityInfo.IsParentType) {
                 await childEntity.EnsureISAChild();
@@ -1427,6 +1784,32 @@ export class BaseEntity {
             return childEntity;
         }
     }
+    /**
+     * A new parent's child is new too: there is no row to read, so copy the parent's keys.
+     * A saved parent still reads (promotion's usual answer is "no row"), and that miss is not
+     * an error — the same way a subtype-hint probe treats an empty read (MJ#4859).
+     */
+    async loadOrMirrorChildRow(childEntity) {
+        if (this.IsSaved && this.PrimaryKey?.HasValue) {
+            const loaded = await this.loadChildRowQuietly(childEntity);
+            if (!loaded) {
+                this.mirrorSharedKeysToChild(childEntity);
+            }
+            return;
+        }
+        this.mirrorSharedKeysToChild(childEntity);
+    }
+    /** Loads the child by the shared key. An empty result is an answer, not a logged error. */
+    async loadChildRowQuietly(childEntity) {
+        const probe = { RowReadFailed: false };
+        childEntity._subtypeHintProbe = probe;
+        try {
+            return await childEntity.InnerLoad(this.PrimaryKey);
+        }
+        finally {
+            childEntity._subtypeHintProbe = null;
+        }
+    }
     mirrorSharedKeysToChild(childEntity) {
         const parentPks = this.EntityInfo.PrimaryKeys;
         if (!parentPks || parentPks.length === 0)
@@ -1438,7 +1821,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 +1853,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 +1877,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 +1915,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;
@@ -1762,6 +2224,20 @@ export class BaseEntity {
     DeclareRelatedRecords(options) {
         return this.RegisterCompanion(new RelatedRecordCollection(this, options));
     }
+    /**
+     * Dynamically registers a database-sourced child collection companion on this entity instance.
+     * Used by generic composite persistence engines (Record Cloning, Metadata Sync) when a relationship
+     * has no static collection companion declared on the generated entity class.
+     *
+     * Refuses duplicate names or re-registering an already existing companion.
+     *
+     * @typeParam TChild - The child entity type.
+     * @param options - The collection declaration options.
+     * @returns The registered collection companion.
+     */
+    DeclareRelatedRecordsDynamic(options) {
+        return this.DeclareRelatedRecords(options);
+    }
     /**
      * Declares a 1:1 embedded peer on this entity, joined by an owner-held foreign key,
      * and registers it as a companion.
@@ -2223,10 +2699,15 @@ export class BaseEntity {
         childSaveOptions.GraphVisited = visited;
         const childDeleteOptions = Object.assign(new EntityDeleteOptions(), deleteOptions ?? {});
         childDeleteOptions.GraphVisited = visited;
-        // Snapshot dirty/saved bookkeeping so a rolled-back graph can be retried.
-        // Node Save() finalizes each participant as saved+clean; DB rollback does
-        // not undo that, and the next Save() would skip the peer and fail the FK.
-        const participants = this.captureGraphParticipants(plan);
+        // A graph that holds a scope is a unit of work: what its records write is put back if it
+        // rolls back, and what they delete is reset only once it commits (see UnitOfWork). Nested in
+        // another unit — the companions of an IS-A parent deleted in its child's chain, say — it
+        // joins that one. Without a scope each write stands as it runs, so a failure leaves the
+        // records that already wrote as they are, which is what the database holds.
+        const enclosing = this._unitOfWork;
+        const records = plan.Nodes.map(node => node.Entity);
+        const previousUnits = records.map(record => record._unitOfWork);
+        let part = null;
         // Acquired INSIDE the try: a begin failure (pool exhausted, dead connection) is a failed
         // save, and Save()/Delete() report failure by returning false — an escaping throw here
         // would break that contract for exactly one path.
@@ -2236,6 +2717,12 @@ export class BaseEntity {
                 provider?.SupportsEntityTransactions === true && provider.BeginEntityTransaction
                     ? await provider.BeginEntityTransaction()
                     : null;
+            if (scope) {
+                part = BaseEntity.beginUnitOfWork(enclosing, BaseEntity.captureChains(records));
+                for (const record of records) {
+                    record._unitOfWork = part.unit;
+                }
+            }
             const result = await ExecuteEntitySavePlan(plan, {
                 SaveOptions: childSaveOptions,
                 DeleteOptions: childDeleteOptions,
@@ -2245,12 +2732,13 @@ export class BaseEntity {
             });
             if (!result.Success) {
                 await scope?.Rollback();
-                this.revertGraphParticipants(participants);
+                BaseEntity.settleRollback(part);
                 this.registerGraphFailure(result.ErrorMessage, operation);
                 this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: result.ErrorMessage });
                 return false;
             }
             await scope?.Commit();
+            BaseEntity.settleCommit(part);
             this.acceptCompanionChanges();
             this.RaiseEvent('graph_save', { Success: true, NodeCount: plan.NodeCount });
             return true;
@@ -2266,13 +2754,18 @@ export class BaseEntity {
                 LogError(`BaseEntity.executeGraphLocal: rollback failed after graph error for ` +
                     `${this.EntityInfo?.Name}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
             }
-            this.revertGraphParticipants(participants);
+            BaseEntity.settleRollback(part);
             const detail = e instanceof Error ? e.message : String(e);
             LogError(`BaseEntity.executeGraphLocal failed for ${this.EntityInfo?.Name}: ${detail}`);
             this.registerGraphFailure(detail, operation);
             this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: detail });
             return false;
         }
+        finally {
+            records.forEach((record, index) => {
+                record._unitOfWork = previousUnits[index];
+            });
+        }
     }
     /**
      * Persist this record as one already-planned graph node. Private: the public
@@ -2280,47 +2773,80 @@ 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
-     * graph can be retried without re-INSERTing a "saved" peer or skipping it.
+     * Captures each record's IS-A chain, from its leaf up to its root, so a unit of work that rolls
+     * back can put the chain back with {@link restoreChains}. A record in more than one chain is
+     * captured once.
      */
-    captureGraphParticipants(plan) {
-        return plan.Nodes.map(node => ({
-            entity: node.Entity,
-            wasSaved: node.Entity.IsSaved,
-            oldValues: node.Entity.Fields.map(f => ({ name: f.Name, old: f.OldValue })),
-        }));
+    static captureChains(entities) {
+        const captured = new Set();
+        const snapshots = [];
+        for (const entity of entities) {
+            for (let level = entity.LeafEntity; level && !captured.has(level); level = level._parentEntity) {
+                captured.add(level);
+                snapshots.push({
+                    entity: level,
+                    wasSaved: level._everSaved,
+                    wasLoaded: level._recordLoaded,
+                    resultHistory: [...level._resultHistory],
+                    fields: level.Fields.map(field => ({ field, state: field.GetState() })),
+                });
+            }
+        }
+        return snapshots;
     }
     /**
-     * Restores in-memory saved/dirty state after the database rolled the graph back.
+     * Puts back, after a rollback, what the unit of work changed in memory. See {@link restoreSnapshot}.
      */
-    revertGraphParticipants(snapshots) {
-        for (const snap of snapshots) {
-            snap.entity.revertUncommittedGraphSave(snap);
+    static restoreChains(snapshots) {
+        for (const snapshot of snapshots) {
+            snapshot.entity.restoreSnapshot(snapshot);
         }
     }
     /**
-     * After a graph node Save() the fields look clean and `_everSaved` is true.
-     * The DB rollback does not undo that. Restore the pre-attempt baseline so
-     * a retry still writes the peer and the owner FK still matches.
+     * Puts this record back as a snapshot captured it, after the unit of work that finalized it
+     * rolled back.
+     *
+     * A save's `finalizeSave()` rebuilds the record's fields from what its write returned, marks it
+     * saved and empties its result history. The database undid the write, so the record gets back
+     * its saved and loaded flags, its result history, and each field's value and tracking state. A
+     * field edited since then keeps the edit, and is compared with its captured baseline again, since
+     * that is what the database holds after the rollback. (A delete leaves nothing to put back: a
+     * record deleted inside a unit of work isn't reset until the unit commits.)
+     *
+     * The history matters to the caller: a save records its failure only when nothing else did,
+     * judged by the history's length when it started, which an emptied history would make wrong.
+     *
+     * A record still holding the captured field objects was never finalized, so nothing about it
+     * changed and it is left alone.
      */
-    revertUncommittedGraphSave(snap) {
-        if (!snap.wasSaved) {
-            this._everSaved = false;
-            this._recordLoaded = false;
+    restoreSnapshot(snapshot) {
+        const finalized = snapshot.fields.some(({ field }) => this.GetFieldByName(field.Name) !== field);
+        if (!finalized) {
+            return;
         }
-        for (const captured of snap.oldValues) {
-            const field = this.GetFieldByName(captured.name);
-            if (field) {
-                field.RestoreOldValue(captured.old);
+        this._everSaved = snapshot.wasSaved;
+        this._recordLoaded = snapshot.wasLoaded;
+        this._resultHistory = snapshot.resultHistory;
+        this._compositeKey = null; // cached from the finalized key; rebuilt on the next read
+        for (const { field: capturedField, state } of snapshot.fields) {
+            const field = this.GetFieldByName(capturedField.Name);
+            if (!field) {
+                continue;
+            }
+            if (field.Dirty) {
+                field.RestoreOldValue(state.OldValue);
+            }
+            else {
+                field.RestoreState(state);
             }
         }
     }
@@ -2379,6 +2905,89 @@ export class BaseEntity {
             LogError(`Error rolling back entity transaction scope for ${this.EntityInfo?.Name}: ${rollbackError}`);
         }
     }
+    /**
+     * The failure path of a save: rolls back the transaction scope this entity holds, if any, then
+     * settles this save's part in its unit of work (see {@link settleRollback}). `part` is null when
+     * this save took none (see `_innerSave`), and then only the scope is rolled back.
+     */
+    async rollbackChainSave(part) {
+        await this.rollbackEntityTransactionScope();
+        BaseEntity.settleRollback(part);
+    }
+    /**
+     * Starts a unit of work's part in a {@link UnitOfWork}: joins `enclosing` when the unit runs
+     * inside one, and owns a new one when it doesn't. `snapshots` are the unit's records as they are
+     * before it writes them. They join the unit's, so that the outermost unit can put them back.
+     */
+    static beginUnitOfWork(enclosing, snapshots) {
+        const unit = enclosing ?? { Snapshots: [], DeletedRecords: [] };
+        unit.Snapshots.push(...snapshots);
+        return { unit, owns: !enclosing, snapshots, deletedMark: unit.DeletedRecords.length };
+    }
+    /**
+     * Runs `work` on `record` as part of `unit` (see {@link UnitOfWork}), and gives the record back
+     * the unit it was in before, however `work` ends. Used for an IS-A parent's delete, which runs
+     * inside its child's chain, along with the graph of its companions if it has any.
+     */
+    static async inUnitOfWork(record, unit, work) {
+        const previous = record._unitOfWork;
+        record._unitOfWork = unit;
+        try {
+            return await work(record);
+        }
+        finally {
+            record._unitOfWork = previous;
+        }
+    }
+    /**
+     * After a unit of work rolls back: puts its records back as they were before it wrote them, and
+     * drops the deletes the rollback undid, so that nothing resets their records. The owner does this
+     * for everything the unit and the units nested in it wrote. A nested part does it for its own
+     * records only; when the owner then rolls back too, restoring them again changes nothing.
+     */
+    static settleRollback(part) {
+        if (!part) {
+            return;
+        }
+        BaseEntity.restoreChains(part.owns ? part.unit.Snapshots : part.snapshots);
+        part.unit.DeletedRecords.length = part.owns ? 0 : part.deletedMark;
+    }
+    /**
+     * After a unit of work commits: its owner resets the records it deleted. A nested part leaves
+     * them to the owner, since the enclosing unit can still roll back.
+     */
+    static settleCommit(part) {
+        if (part?.owns) {
+            BaseEntity.resetDeletedRecords(part.unit.DeletedRecords);
+        }
+    }
+    /**
+     * Resets the records a unit of work deleted, once the unit has committed, as each record's own
+     * `Delete()` does when no unit of work is involved. See {@link UnitOfWork}.
+     *
+     * Last-deleted first, skipping a record that no longer reads as saved. `NewRecord()` on a record
+     * also resets every IS-A level above it, and relinks them. A chain's initiator records its delete
+     * after its parents do, so it's reset first, and its parents with it. Resetting a parent again
+     * after that would unlink it from its child and give it a key the child doesn't share.
+     *
+     * The unit has committed, so a reset that throws is logged and the rest still run: the deletes
+     * stand whatever happens here.
+     */
+    static resetDeletedRecords(records) {
+        for (let index = records.length - 1; index >= 0; index--) {
+            const record = records[index];
+            if (!record.IsSaved) {
+                continue;
+            }
+            try {
+                record.NewRecord();
+            }
+            catch (e) {
+                LogError(`BaseEntity.resetDeletedRecords: resetting a deleted ${record.EntityInfo?.Name} record failed: ` +
+                    `${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+    }
     /**
      * Returns this provider to be used for a given instance of a BaseEntity derived subclass. If the provider is not set, the BaseEntity.Provider is returned.
      */
@@ -2620,12 +3229,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 +3250,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 +3313,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 +3335,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 +3400,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 +3423,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 +3450,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 +3460,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 +3521,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 +3540,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 +3554,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 +3600,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 +3614,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 +3654,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 +3662,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);
@@ -3197,8 +3806,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
@@ -3256,7 +3865,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;
@@ -3292,14 +3901,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
@@ -3408,10 +4017,12 @@ export class BaseEntity {
         // when setting keys.
         if (this._parentEntity) {
             this._parentEntity.NewRecord();
+            // The parent's NewRecord() just nulled its back-link. Put this child back.
+            this.linkParentBackToThisChild();
             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
@@ -3516,6 +4127,42 @@ export class BaseEntity {
     ClearRestoreContext() {
         this._restoreContext = null;
     }
+    /**
+     * Returns the active clone context for the next save, if any.
+     *
+     * Read by the data provider when generating the RecordChange SQL: when
+     * non-null, the resulting RecordChange row is written with
+     * `Source='Clone'` and `ChangeContext` populated with structured JSON provenance.
+     * Returns null for ordinary saves.
+     */
+    get CloneContext() {
+        return this._cloneContext;
+    }
+    /**
+     * Marks the next Save() as part of a record clone operation.
+     *
+     * The provider will write a new RecordChange entry with `Source='Clone'`
+     * and `ChangeContext` populated with structured JSON provenance.
+     *
+     * The context persists on the entity until either (a) overwritten by a
+     * subsequent SetCloneContext() call or (b) explicitly cleared via
+     * ClearCloneContext(). It is NOT auto-cleared inside Save() because
+     * TransactionGroup execution is deferred.
+     *
+     * @param context Structured clone context. Throws if missing required fields.
+     */
+    SetCloneContext(context) {
+        if (!context || !context.CloneLogID || !context.SourceRecordID || !context.RootEntityName) {
+            throw new Error('BaseEntity.SetCloneContext: context is required with CloneLogID, SourceRecordID, and RootEntityName');
+        }
+        this._cloneContext = context;
+    }
+    /**
+     * Clears any pending clone context. Safe to call when no context is set.
+     */
+    ClearCloneContext() {
+        this._cloneContext = null;
+    }
     /**
      * Saves the current state of the object to the database. Uses the active provider to handle the actual saving of the record.
      * If the record is new, it will be created, if it already exists, it will be updated.
@@ -3563,7 +4210,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
@@ -3604,7 +4251,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.
@@ -3617,10 +4264,14 @@ 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();
+        // The unit of work this save runs inside, if any (see UnitOfWork), and this save's own part
+        // in one, taken only when this entity starts an IS-A chain save whose writes a failure undoes.
+        const enclosing = this._unitOfWork;
+        let part = null;
         try {
             const initialDirtyState = this.Dirty; // save this because parent entity save cycle, if any, will clear their dirty flags
             const _options = options ? options : new EntitySaveOptions();
@@ -3638,7 +4289,20 @@ export class BaseEntity {
             // save — this joins it as a savepoint rather than starting a second physical
             // transaction. Before 6.2 this path called BeginISATransaction(), which was blind to
             // any existing transaction and produced torn writes; see EntityTransactionScope.
-            await this.beginEntityTransactionScope(isISAInitiator);
+            const scopeOpened = await this.beginEntityTransactionScope(isISAInitiator);
+            // Each level of the chain is finalized as saved and clean when its own write returns,
+            // before the chain commits. A failure that undoes those writes has to put the chain
+            // back in memory too, so the chain save is a unit of work, captured before the parents
+            // save. The writes are undone when this save holds a scope, and on a provider without
+            // entity transactions, which doesn't talk to a database directly: there each parent's
+            // save is recorded in memory and the leaf's one write carries the chain
+            // (GraphQLDataProvider). Anywhere else a level may really have written (in a
+            // TransactionGroup, a level outside the group does), and marking it unsaved would make
+            // the retry insert it twice.
+            if (isISAInitiator && !this.TransactionGroup &&
+                (scopeOpened || this.ProviderToUse?.SupportsEntityTransactions !== true)) {
+                part = BaseEntity.beginUnitOfWork(enclosing, BaseEntity.captureChains([this]));
+            }
             // Save parent chain first (root → branch → immediate parent)
             // Parent calls Save() recursively which handles its own parents, permissions, validation
             if (this._parentEntity) {
@@ -3653,8 +4317,9 @@ export class BaseEntity {
                 parentSaveOptions.ISAActiveChildEntityName = this.EntityInfo.Name;
                 const parentResult = await this._parentEntity.Save(parentSaveOptions); // we know parent entity exists hre
                 if (!parentResult) {
-                    // Parent save failed — rollback if we started the transaction
-                    await this.rollbackEntityTransactionScope();
+                    // Parent save failed — roll back if we started the transaction, and put back
+                    // the levels above it that had already saved
+                    await this.rollbackChainSave(part);
                     // RECORD the failure on THIS entity's ResultHistory before returning. Without
                     // this the caller gets `false` with LatestResult === null and an empty
                     // ResultHistory, because every result was written to the PARENT object — which
@@ -3765,7 +4430,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
@@ -3793,9 +4458,10 @@ export class BaseEntity {
                             // this scope exists to prevent.
                             if (result) {
                                 await this.commitEntityTransactionScope();
+                                BaseEntity.settleCommit(part);
                             }
                             else {
-                                await this.rollbackEntityTransactionScope();
+                                await this.rollbackChainSave(part);
                             }
                             return result;
                         }
@@ -3843,12 +4509,15 @@ export class BaseEntity {
                 // commit, so later "successful" saves were silently non-durable. Committing an
                 // empty scope writes nothing; it only releases the transaction.
                 await this.commitEntityTransactionScope();
+                BaseEntity.settleCommit(part);
                 return true; // nothing to save since we're not dirty
             }
         }
         catch (e) {
-            // Roll back the scope this entity opened, if any. No-op when it holds none.
-            await this.rollbackEntityTransactionScope();
+            // Roll back the scope this entity opened, if any (a no-op when it holds none), and put
+            // back what the chain's saves changed in memory, this entity included when the commit
+            // is what threw. Before the result below, which reads IsSaved and the old values.
+            await this.rollbackChainSave(part);
             if (currentResultCount === this.ResultHistory.length) {
                 // this means that NO new results were added to the history anywhere
                 // so we need to add a new result to the history here
@@ -3867,7 +4536,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);
@@ -3924,7 +4593,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;
         }
@@ -3944,7 +4613,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;
@@ -4235,9 +4904,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.
@@ -4273,7 +4945,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.
@@ -4296,6 +4968,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
@@ -4383,7 +5076,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) {
@@ -4439,7 +5132,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();
             }
@@ -4614,6 +5307,12 @@ export class BaseEntity {
                 return this.deleteGraph(plan, options);
             }
         }
+        // IS-A parent chain deletes bypass the debounce, as parent chain saves do: the leaf's
+        // call back up the chain would otherwise wait on the pending delete that handed the
+        // delete to the leaf, and Delete() would never return (MJ#4850).
+        if (options?.IsParentEntityDelete) {
+            return this._innerDelete(options);
+        }
         // If a delete is already in progress, return its promise.
         if (this._pendingDelete$) {
             return firstValueFrom(this._pendingDelete$);
@@ -4621,7 +5320,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.
@@ -4634,10 +5333,17 @@ 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();
+        // The unit of work this delete runs inside, if any (see UnitOfWork), and this delete's own
+        // part in one, taken when it opens a scope for an IS-A chain.
+        const enclosing = this._unitOfWork;
+        let part = null;
+        // Set once this record's own row is deleted. From then on its history holds the provider's
+        // entry for that delete, which doesn't report a failure later in the chain.
+        let ownRowDeleted = false;
         try {
             const _options = options ? options : new EntityDeleteOptions();
             // IS-A leaf delegation: if this entity has a child entity and we are NOT
@@ -4684,7 +5390,15 @@ export class BaseEntity {
                 // Open (or join) a transaction scope for the parent chain — see the matching
                 // comment in _InnerSave and EntityTransactionScope for why this is provider-
                 // arbitrated rather than IS-A-specific.
-                await this.beginEntityTransactionScope(isISAInitiator);
+                const scopeOpened = await this.beginEntityTransactionScope(isISAInitiator);
+                // A chain delete that holds a scope is a unit of work. Each parent is deleted inside
+                // it and isn't reset when its delete returns: the unit resets the chain once it
+                // commits, so a failure that rolls it back leaves every level as it was. Without a
+                // scope each delete stands as it runs and resets its record at once, as before.
+                if (scopeOpened) {
+                    part = BaseEntity.beginUnitOfWork(enclosing, BaseEntity.captureChains([this]));
+                }
+                const unit = part?.unit ?? enclosing;
                 this.CheckPermissions(EntityPermissionType.Delete, true); // this will throw an error and exit out if we don't have permission
                 // Raise delete_started event before the actual delete operation begins
                 this.RaiseEvent('delete_started', null);
@@ -4699,6 +5413,7 @@ export class BaseEntity {
                 });
                 // Delete OWN row first (FK constraint: child must be deleted before parent)
                 if (await this.ProviderToUse.Delete(this, _options, this.ActiveUser)) {
+                    ownRowDeleted = true;
                     // IS-A: after own delete succeeds, cascade to parent chain
                     if (hasParentChain) {
                         // For overlapping subtypes, check if other children still reference
@@ -4710,38 +5425,40 @@ export class BaseEntity {
                             parentDeleteOptions.SkipEntityActions = _options.SkipEntityActions;
                             parentDeleteOptions.ReplayOnly = _options.ReplayOnly;
                             parentDeleteOptions.IsParentEntityDelete = true;
-                            const parentResult = await this._parentEntity.Delete(parentDeleteOptions);
+                            // The parent's delete belongs to this chain's unit of work, so it doesn't
+                            // reset the parent when it returns: the unit does, once it commits.
+                            const parentResult = await BaseEntity.inUnitOfWork(this._parentEntity, unit, parent => parent.Delete(parentDeleteOptions));
                             if (!parentResult) {
                                 // Parent delete failed — rollback if we started the transaction
                                 await this.rollbackEntityTransactionScope();
+                                BaseEntity.settleRollback(part);
                                 // RECORD the failure on THIS entity's ResultHistory before returning —
-                                // symmetric with the parent-SAVE-failure path in _InnerSave. Without this
-                                // the caller gets `false` with LatestResult === null and an empty
-                                // ResultHistory, because every result was written to the PARENT object,
-                                // which callers have no reference to (`_parentEntity` is private). Note
-                                // THIS entity's own row was already deleted successfully above; it is the
-                                // parent-chain delete that failed and rolled the transaction back.
-                                if (currentResultCount === this.ResultHistory.length) {
-                                    const parentLatest = this._parentEntity.LatestResult;
-                                    const parentErrors = parentLatest?.Errors ?? [];
-                                    // A failed parent commonly reports its detail ONLY in Errors, so fall
-                                    // back to the error text rather than a message that says nothing.
-                                    const detail = parentLatest?.Message ||
-                                        parentErrors.map(e => e?.Message ?? String(e)).filter(Boolean).join('; ') ||
-                                        'no error detail was reported by the parent';
-                                    newResult.Success = false;
-                                    newResult.Type = 'delete';
-                                    newResult.Message =
-                                        `Failed to delete parent entity '${this._parentEntity.EntityInfo?.Name}': ${detail}`;
-                                    // Surface the parent's field-level errors so the caller can act on them.
-                                    newResult.Errors = parentErrors;
-                                    // When `detail` was built from `parentErrors` (no parent Message), `Message` already renders
-                                    // them — say so, or CompleteMessage repeats every one.
-                                    newResult.MessageIncludesErrors = !parentLatest?.Message && parentErrors.length > 0;
-                                    newResult.OriginalValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.OldValue }; });
-                                    newResult.EndedAt = new Date();
-                                    this.RegisterResultHistoryEntry(newResult);
-                                }
+                                // symmetric with the parent-SAVE-failure path in _InnerSave. Every result
+                                // for the parent's failure was written to the PARENT object, which callers
+                                // have no reference to (`_parentEntity` is private). THIS entity's own row
+                                // was already deleted successfully above, and the only entry its history
+                                // gained is the provider's for that delete, which the rollback just undid.
+                                // So the failure is recorded whatever that entry says: skipping it when
+                                // the history had grown left the caller holding the provider's entry.
+                                const parentLatest = this._parentEntity.LatestResult;
+                                const parentErrors = parentLatest?.Errors ?? [];
+                                // A failed parent commonly reports its detail ONLY in Errors, so fall
+                                // back to the error text rather than a message that says nothing.
+                                const detail = parentLatest?.Message ||
+                                    parentErrors.map(e => e?.Message ?? String(e)).filter(Boolean).join('; ') ||
+                                    'no error detail was reported by the parent';
+                                newResult.Success = false;
+                                newResult.Type = 'delete';
+                                newResult.Message =
+                                    `Failed to delete parent entity '${this._parentEntity.EntityInfo?.Name}': ${detail}`;
+                                // Surface the parent's field-level errors so the caller can act on them.
+                                newResult.Errors = parentErrors;
+                                // When `detail` was built from `parentErrors` (no parent Message), `Message` already renders
+                                // them — say so, or CompleteMessage repeats every one.
+                                newResult.MessageIncludesErrors = !parentLatest?.Message && parentErrors.length > 0;
+                                newResult.OriginalValues = this.Fields.map(f => { return { FieldName: f.CodeName, Value: f.OldValue }; });
+                                newResult.EndedAt = new Date();
+                                this.RegisterResultHistoryEntry(newResult);
                                 return false;
                             }
                         }
@@ -4752,8 +5469,16 @@ export class BaseEntity {
                         // NOT part of a transaction - raise event immediately
                         // record deleted correctly
                         this.RaiseEvent('delete', { OldValues: oldVals });
-                        // wipe out the current data to flush out the DIRTY flags by calling NewRecord()
-                        this.NewRecord(); // will trigger a new record event here too
+                        if (unit) {
+                            // Deleted inside a unit of work, which resets the record once it commits:
+                            // now, when this delete owns the unit and has just committed it.
+                            unit.DeletedRecords.push(this);
+                            BaseEntity.settleCommit(part);
+                        }
+                        else {
+                            // wipe out the current data to flush out the DIRTY flags by calling NewRecord()
+                            this.NewRecord(); // will trigger a new record event here too
+                        }
                     }
                     else {
                         // part of a transaction, wait for the transaction to submit successfully and then
@@ -4796,6 +5521,7 @@ export class BaseEntity {
                     // every subsequent "committed" write on this provider silently never commits.
                     // (Also: don't wipe out the entity like we do when the Delete() worked.)
                     await this.rollbackEntityTransactionScope();
+                    BaseEntity.settleRollback(part);
                     return false;
                 }
             }
@@ -4803,9 +5529,11 @@ export class BaseEntity {
         catch (e) {
             // Roll back the scope this entity opened, if any. No-op when it holds none.
             await this.rollbackEntityTransactionScope();
-            if (currentResultCount === this.ResultHistory.length) {
-                // this means that NO new results were added to the history anywhere
-                // so we need to add a new result to the history here
+            BaseEntity.settleRollback(part);
+            // Record the failure when nothing else did. Once this record's own row was deleted, its
+            // history holds the provider's entry for that delete, which doesn't report this failure
+            // (a failed commit, most often), so the failure is recorded then too.
+            if (ownRowDeleted || currentResultCount === this.ResultHistory.length) {
                 newResult.Success = false;
                 newResult.Type = 'delete';
                 newResult.Message = e.message || null;
@@ -4892,13 +5620,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 };
@@ -4918,7 +5646,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