@memberjunction/core 6.1.0-edge.1 → 6.1.0-edge.3

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 { MJEventType, MJGlobal, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager } from '@memberjunction/global';
+import { IsMemberOverridden, MJEventType, MJGlobal, OptionalKeyedSpecialization, uuidv4, UUIDsEqual, WarningManager } from '@memberjunction/global';
 import { GetDataHooks } from './dataHooks.js';
 import { EntityFieldInfo, EntityInfo, EntityFieldTSType, EntityPermissionType, RecordChange, ValidationErrorInfo, ValidationResult } from './entityInfo.js';
 import { EntityDeleteOptions, EntitySaveOptions, ProviderType } from './interfaces.js';
@@ -18,6 +18,7 @@ import { LogDebug, LogError } from './logging.js';
 import { CompositeKey } from './compositeKey.js';
 import { RelatedRecordCollection } from './relatedRecordCollection.js';
 import { COMPANION_PAYLOAD_KEY } from './entityCompanion.js';
+import { EmbeddedRecord } from './embeddedRecord.js';
 import { EntitySavePlan, ExecuteEntitySavePlan } from './entitySavePlan.js';
 import { BaseRemotableOperation } from './baseRemotableOperation.js';
 import { SAVE_ENTITY_GRAPH_OPERATION_KEY, } from './saveEntityGraphOperation.js';
@@ -312,6 +313,20 @@ let EntityField = class EntityField {
                     }
                 }
             }
+            // Value-list validation (MJ issue #3969): a field whose ValueListType is `List` carries an
+            // EXHAUSTIVE set of legal values in metadata, and for an `IN (...)` CHECK constraint that
+            // list is the only runtime representation CodeGen produces — so without this rung an
+            // out-of-list value reached the database as a raw constraint violation attributed to no
+            // field, on every path that is not a form. Which modes and value types the rule applies
+            // to, how values are compared, and why, all live in
+            // EntityFieldInfo.ValueIsPermittedByValueList: the normalized set of legal values is
+            // derived from immutable metadata SHARED by every EntityField instance of this field, so
+            // it is built once per field rather than rebuilt on every record's validation.
+            if (!ef.ValueIsPermittedByValueList(this.Value)) {
+                result.Success = false;
+                const nullNote = ef.AllowsNull ? ' (or null)' : '';
+                result.Errors.push(new ValidationErrorInfo(ef.Name, `${ef.DisplayNameOrName} must be one of: ${ef.ValueListValuesForDisplay}${nullNote}. Current value is '${this.Value}'`, this.Value));
+            }
         }
         return result;
     }
@@ -422,6 +437,13 @@ let EntityField = class EntityField {
     ResetOldValue() {
         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;
+    }
     /**
      * @deprecated No-op as of the active-status relocation. Active-status (deprecated/disabled)
      * assertions are now enforced at BaseEntity.Get/Set/SetMany — the entry points genuine code uses —
@@ -519,9 +541,6 @@ export class BaseEntityResult {
  */
 export class BaseEntityEvent {
 }
-/**
- * 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
@@ -614,6 +633,21 @@ export class BaseEntity {
          * authoritative source.
          */
         this._raw = null;
+        /**
+         * Per-instance memo for values `Get()` derives from `_raw` — a parsed `Date`, an rtrimmed
+         * fixed-width string. Lazily created; only converted fields ever get an entry.
+         *
+         * This deliberately does NOT write back into `_raw`. `LoadFromData`'s fast path keeps the
+         * caller's row BY REFERENCE, and that row is frequently a LocalCacheManager entry, which the
+         * cache deep-freezes on reference-sharing providers. Memoizing into the row therefore made a
+         * plain field READ throw — and gating that write on a once-sampled `Object.isFrozen` could
+         * not be made correct, because the freeze is asynchronous relative to the consumer (cache
+         * writes are not always awaited), so the sample can be stale by the first read.
+         *
+         * Keeping the memo here makes freeze timing irrelevant AND restores the optimization on
+         * frozen rows, which the isFrozen-guard version had to give up.
+         */
+        this._rawConverted = null;
         /**
          * Whether a database record has been loaded into this instance (via `Load`, `NewRecord`,
          * `LoadFromData`, etc.). Used to gate operations that require loaded state and to distinguish
@@ -913,6 +947,8 @@ export class BaseEntity {
         // We need to replace the child's auto-initialized parent with our existing instance
         this.replaceChildParentChain(childEntity);
         this._childEntity = childEntity;
+        // Capture any pending modifications on this entity or its ancestors before child InnerLoad
+        const dirtySnapshots = this.captureChainDirtyState();
         // Load the child's record using our shared PK
         const loaded = await childEntity.InnerLoad(this.PrimaryKey);
         if (!loaded) {
@@ -920,10 +956,34 @@ export class BaseEntity {
             this._childEntity = null;
             return;
         }
+        // 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();
     }
+    captureChainDirtyState() {
+        const snapshots = [];
+        let curr = this;
+        while (curr) {
+            const dirtyFields = curr.Fields.filter(f => f.Dirty).map(f => ({
+                name: f.Name,
+                value: f.Value,
+            }));
+            if (dirtyFields.length > 0) {
+                snapshots.push({ entity: curr, dirtyFields });
+            }
+            curr = curr._parentEntity;
+        }
+        return snapshots;
+    }
+    restoreChainDirtyState(snapshots) {
+        for (const snap of snapshots) {
+            for (const df of snap.dirtyFields) {
+                snap.entity.Set(df.name, df.value);
+            }
+        }
+    }
     /**
      * Replaces the child entity's auto-initialized parent chain with references
      * to our existing chain. This ensures all entities in the IS-A hierarchy
@@ -1008,7 +1068,12 @@ export class BaseEntity {
      * values are present (via {@link UpdateSavedStateFromPrimaryKeys}).
      *
      * The parent chain is handled recursively: if this entity has an IS-A parent, the
-     * parent is hydrated first (deepest ancestor first) via SetMany's built-in routing.
+     * parent is hydrated first (deepest ancestor first). Each level only receives the
+     * fields it owns — a child's view row is the union of every ancestor plus its own
+     * columns, and passing that whole row to the parent used to trip
+     * `WarningManager` ("fields were not found in entity definitions") for every
+     * child-only column. That is how loading `Accounting Company Profiles` as
+     * entity objects produced a `MJ: Companies` missing-field dump at MJAPI boot.
      *
      * @param data - A plain object whose properties map to field names on this entity
      *               (and potentially parent entities in the IS-A chain).
@@ -1025,9 +1090,23 @@ export class BaseEntity {
         // Populate this entity's fields. SetMany also routes parent field values to
         // _parentEntity via the IS-A routing block (which now includes PK fields).
         // replaceOldValues=true ensures OldValue matches Value (no false dirty flags).
-        // ignoreNonExistentFields=true because data may contain fields from other
-        // entities in the chain that don't exist on this entity.
-        this.SetMany(data, true, true, true);
+        // ignoreNonExistentFields=true remains as a safety net; ownedFieldsFrom already
+        // dropped columns that belong to another level of the IS-A chain.
+        this.SetMany(this.ownedFieldsFrom(data), true, true, true);
+    }
+    /**
+     * Columns on `data` that this entity actually defines (by field name or CodeName).
+     * Used by {@link Hydrate} so an IS-A ancestor is not asked to SetMany its child's
+     * extra view columns.
+     */
+    ownedFieldsFrom(data) {
+        const owned = {};
+        for (const key of Object.keys(data)) {
+            if (this.GetFieldByName(key) || this.GetFieldByCodeName(key)) {
+                owned[key] = data[key];
+            }
+        }
+        return owned;
     }
     // ─── Entity Companions ──────────────────────────────────────────────────────
     //
@@ -1108,21 +1187,91 @@ export class BaseEntity {
     DeclareRelatedRecords(options) {
         return this.RegisterCompanion(new RelatedRecordCollection(this, options));
     }
+    /**
+     * Declares a 1:1 embedded peer on this entity, joined by an owner-held foreign key,
+     * and registers it as a companion.
+     *
+     * Call from a field initialiser on a **shared** (client + server) subclass — or let
+     * CodeGen emit it from `EntityField.EmbeddedRecord`. The public surface is the
+     * generated `{Field}_Object` getter, not this companion.
+     *
+     * @typeParam TEmbedded - The peer entity type.
+     * @param options - The declaration.
+     * @returns The registered companion.
+     */
+    DeclareEmbeddedRecord(options) {
+        return this.RegisterCompanion(new EmbeddedRecord(this, options));
+    }
+    /**
+     * Constructs every declared embedded peer without `NewRecord` or `Load`.
+     * Called from `GetEntityObject` after {@link InitializeParentEntity}.
+     *
+     * @param visited - Entity names already being constructed (cycle guard).
+     */
+    async InitializeEmbeddedRecords(visited = new Set()) {
+        if (!this.HasCompanions) {
+            return;
+        }
+        const embeddeds = this.Companions.filter((c) => c instanceof EmbeddedRecord);
+        if (embeddeds.length === 0) {
+            return;
+        }
+        // Copy the visited set per sibling. Sharing one mutable set made two
+        // embeds targeting the same entity (BillTo + ShipTo Address) throw a
+        // false "cycle detected" while the first companion was still in flight.
+        await Promise.all(embeddeds.map(e => e.InitializeInstance(new Set(visited))));
+    }
+    /**
+     * Builds a related entity the way `GetEntityObject` does, minus `NewRecord` / `Load`.
+     * Used by {@link EmbeddedRecord} so construction can thread a cycle-detection set.
+     *
+     * @typeParam T - The entity type to construct.
+     * @param entityName - Metadata entity name.
+     * @param visited - Cycle guard, forwarded into the new instance's own embeddeds.
+     */
+    async ConstructUninitializedEntity(entityName, visited) {
+        const provider = this.ProviderToUse;
+        if (!provider) {
+            throw new Error(`BaseEntity.ConstructUninitializedEntity: no provider; cannot construct '${entityName}'.`);
+        }
+        const entityInfo = provider.EntityByName(entityName);
+        if (!entityInfo) {
+            throw new Error(`BaseEntity.ConstructUninitializedEntity: entity '${entityName}' not found in metadata.`);
+        }
+        let instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseEntity, entityName, entityInfo, provider);
+        if (!instance) {
+            instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseEntity, null, entityInfo, provider);
+        }
+        if (!instance) {
+            throw new Error(`BaseEntity.ConstructUninitializedEntity: ClassFactory could not construct '${entityName}'. ` +
+                `Ensure the entity class is registered.`);
+        }
+        await instance.Config(this.ContextCurrentUser);
+        await instance.InitializeParentEntity();
+        // Recurse so a *new* peer's own embeds are constructed (required nested
+        // FKs provision on NewRecord; Ensure on the nested peer does not throw).
+        // InitializeInstance skips when RelatedEntity is already on this path,
+        // so a self-FK / A→B→A cycle still constructs only one extra level.
+        await instance.InitializeEmbeddedRecords(visited);
+        return instance;
+    }
     /**
      * Serializes every registered companion that has something to send.
      *
      * Companions returning `null` are omitted entirely, so a header-only save on a composite entity
      * ships no companion payload at all and costs nothing extra on the wire.
      *
+     * @param mode - `'request'` omits clean saved companions. `'result'` ships
+     *               authoritative post-save state so the other tier can mark peers saved.
      * @returns The companion payloads, in declaration order.
      */
-    async SerializeCompanions() {
+    async SerializeCompanions(mode = 'request') {
         if (!this.HasCompanions) {
             return [];
         }
         const payloads = [];
         for (const companion of this.Companions) {
-            const data = await companion.Serialize();
+            const data = await companion.Serialize(mode);
             if (data !== null && data !== undefined) {
                 payloads.push({ Name: companion.Name, Data: data });
             }
@@ -1310,13 +1459,29 @@ export class BaseEntity {
             }
         });
     }
+    /**
+     * Seeds the embed-load cycle set for a nested `InnerLoad`. Called by
+     * {@link EmbeddedRecord.LoadEager} so inherit walks share one `entityName:PK`
+     * path and a self-parented row fails cleanly instead of recursing forever.
+     */
+    SetEmbeddedLoadVisited(visited) {
+        this._embedLoadVisited = visited;
+    }
+    seedEmbedLoadVisited() {
+        const seeded = new Set();
+        const name = this.EntityInfo?.Name;
+        const pk = this.FirstPrimaryKey?.Value;
+        if (name && pk !== null && pk !== undefined && pk !== '') {
+            seeded.add(`${name}:${String(pk)}`);
+        }
+        return seeded;
+    }
     async loadEagerCompanions() {
         if (!this.HasCompanions) {
             return;
         }
-        for (const companion of this.Companions) {
-            await companion.LoadEager();
-        }
+        const visited = this._embedLoadVisited ?? this.seedEmbedLoadVisited();
+        await Promise.all(this.Companions.map(c => c.LoadEager(visited)));
     }
     /**
      * Tells every companion that the unit of work committed, so they can clear pending removals and
@@ -1400,6 +1565,9 @@ export class BaseEntity {
             Label: this.EntityInfo?.Name ?? 'root',
             SelfOnly: true,
         });
+        for (const companion of this.Companions) {
+            companion.ContributePostDeleteWork(plan);
+        }
         return plan;
     }
     /**
@@ -1475,6 +1643,10 @@ 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);
         // 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.
@@ -1486,13 +1658,14 @@ export class BaseEntity {
                     : null;
             const result = await ExecuteEntitySavePlan(plan, {
                 SaveOptions: childSaveOptions,
-                RootSaveOptions: this.buildRootSaveOptions(saveOptions),
                 DeleteOptions: childDeleteOptions,
-                RootDeleteOptions: this.buildRootDeleteOptions(deleteOptions),
                 Visited: visited,
+                SaveSelfOnly: (entity, opts) => entity.saveAsGraphNode(opts),
+                DeleteSelfOnly: (entity, opts) => entity.deleteAsGraphNode(opts),
             });
             if (!result.Success) {
                 await scope?.Rollback();
+                this.revertGraphParticipants(participants);
                 this.registerGraphFailure(result.ErrorMessage, operation);
                 this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: result.ErrorMessage });
                 return false;
@@ -1513,6 +1686,7 @@ 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);
             const detail = e instanceof Error ? e.message : String(e);
             LogError(`BaseEntity.executeGraphLocal failed for ${this.EntityInfo?.Name}: ${detail}`);
             this.registerGraphFailure(detail, operation);
@@ -1521,31 +1695,54 @@ export class BaseEntity {
         }
     }
     /**
-     * Builds the save options for the graph's **root** node.
-     *
-     * Copies the caller's options onto a real `EntitySaveOptions` instance and stamps
-     * `IsGraphNodeSave`, which is what stops the root re-entering graph planning and lets it bypass
-     * its own in-flight save debounce.
-     *
-     * @param source - The caller's options, if any.
-     * @returns Options for the root node.
+     * Persist this record as one already-planned graph node. Private: the public
+     * `Save()` contract must not expose a "skip companions" switch. The executor
+     * binds this via {@link ExecuteEntitySavePlan}'s `SaveSelfOnly` callback.
      */
-    buildRootSaveOptions(source) {
-        const options = Object.assign(new EntitySaveOptions(), source ?? {});
-        options.IsGraphNodeSave = true;
-        return options;
+    saveAsGraphNode(options) {
+        return this._InnerSave(options);
     }
     /**
-     * Builds the delete options for the graph's **root** node. Delete-path counterpart of
-     * {@link buildRootSaveOptions}.
-     *
-     * @param source - The caller's options, if any.
-     * @returns Options for the root node.
+     * Delete-path counterpart of {@link saveAsGraphNode}.
+     */
+    deleteAsGraphNode(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.
      */
-    buildRootDeleteOptions(source) {
-        const options = Object.assign(new EntityDeleteOptions(), source ?? {});
-        options.IsGraphNodeDelete = true;
-        return options;
+    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 })),
+        }));
+    }
+    /**
+     * Restores in-memory saved/dirty state after the database rolled the graph back.
+     */
+    revertGraphParticipants(snapshots) {
+        for (const snap of snapshots) {
+            snap.entity.revertUncommittedGraphSave(snap);
+        }
+    }
+    /**
+     * 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.
+     */
+    revertUncommittedGraphSave(snap) {
+        if (!snap.wasSaved) {
+            this._everSaved = false;
+            this._recordLoaded = false;
+        }
+        for (const captured of snap.oldValues) {
+            const field = this.GetFieldByName(captured.name);
+            if (field) {
+                field.RestoreOldValue(captured.old);
+            }
+        }
     }
     /**
      * Records a graph-level failure on this entity's result history.
@@ -2050,6 +2247,10 @@ export class BaseEntity {
      * @param FieldName
      * @returns
      */
+    /** Records a value derived from `_raw` so later reads skip the conversion. See {@link _rawConverted}. */
+    memoizeRawConversion(fieldName, value) {
+        (this._rawConverted ??= new Map()).set(fieldName, value);
+    }
     Get(FieldName) {
         // IS-A routing: return the authoritative value from the parent entity
         if (this._parentEntity && this._parentEntityFieldNames?.has(FieldName)) {
@@ -2070,20 +2271,26 @@ export class BaseEntity {
             let value = this._raw[FieldName];
             if (value === undefined)
                 return null;
-            // Date conversion mirrors the hydrated path. Mutating _raw to cache the converted
-            // Date avoids reparsing on every read.
+            // Conversions mirror the hydrated path, and memoize into `_rawConverted` rather than
+            // back into `_raw` — the row may be shared, frozen cache state. Fields needing no
+            // conversion (the vast majority) never touch the memo at all, so the fast path stays
+            // a single property read.
             const fi = this._EntityInfo?.FieldByName(FieldName);
             if (fi?.TSType === EntityFieldTSType.Date && (typeof value === 'string' || typeof value === 'number')) {
+                const memo = this._rawConverted?.get(FieldName);
+                if (memo !== undefined)
+                    return memo;
                 const d = new Date(value);
-                this._raw[FieldName] = d;
+                this.memoizeRawConversion(FieldName, d);
                 return d;
             }
-            // Mirror the EntityField.Value setter: rtrim padding for fixed-
-            // width string columns. Memoize back into _raw so we don't
-            // re-trim on every read.
+            // Mirror the EntityField.Value setter: rtrim padding for fixed-width string columns.
             if (typeof value === 'string' && fi?.FixedWidthColumn) {
+                const memo = this._rawConverted?.get(FieldName);
+                if (memo !== undefined)
+                    return memo;
                 value = value.replace(/ +$/, '');
-                this._raw[FieldName] = value;
+                this.memoizeRawConversion(FieldName, value);
             }
             return value;
         }
@@ -2346,6 +2553,7 @@ export class BaseEntity {
         this._Fields = [];
         this._fieldsHydrated = false;
         this._raw = null;
+        this._rawConverted = null;
         this._fieldCache = null;
         this._codeNameCache = null;
         // Field construction is deferred to hydrateFieldsIfNeeded(). Constructor / init() stays
@@ -2402,8 +2610,10 @@ export class BaseEntity {
                 }
             }
             // Raw data has been promoted into Fields — release the reference so we don't carry
-            // duplicate state.
+            // duplicate state. Fields hold their own copies, so a frozen source no longer
+            // constrains anything from here on.
             this._raw = null;
+            this._rawConverted = null;
         }
     }
     /**
@@ -2512,9 +2722,24 @@ export class BaseEntity {
                 this.Set(kv.FieldName, kv.Value);
             });
         }
+        this.notifyEmbeddedNewRecord();
         this.RaiseEvent('new_record', null);
         return true;
     }
+    /**
+     * Required embeddeds are provisioned here so `{Field}_Object` is usable immediately
+     * after `GetEntityObject` / `NewRecord`. Nullable embeddeds stay unexposed.
+     */
+    notifyEmbeddedNewRecord() {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            if (companion instanceof EmbeddedRecord) {
+                companion.OnOwnerNewRecord();
+            }
+        }
+    }
     /**
      * Returns the active restore context for the next save, if any.
      *
@@ -2613,11 +2838,6 @@ export class BaseEntity {
         if (options?.IsParentEntitySave) {
             return this._InnerSave(options);
         }
-        // Executing our own node inside a graph we already planned. Bypass both the debounce and
-        // graph routing — see EntitySaveOptions.IsGraphNodeSave for why each matters.
-        if (options?.IsGraphNodeSave) {
-            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
         // (double-click, autosave racing a manual save) must share the in-flight unit of work.
@@ -2649,8 +2869,7 @@ export class BaseEntity {
                 }
                 // Run the graph through the same pending-save pipeline as a single-row save, so
                 // concurrent callers share one execution and one result. The graph's own root node
-                // re-enters Save() with IsGraphNodeSave, which bypasses this pipeline above — no
-                // self-deadlock.
+                // runs via the private saveAsGraphNode path — no re-entry into this pipeline.
                 this._pendingSave$ = of(options).pipe(switchMap(opts => from(this.saveGraph(plan, opts))), finalize(() => { this._pendingSave$ = null; }), shareReplay(1));
                 return firstValueFrom(this._pendingSave$);
             }
@@ -2766,11 +2985,29 @@ export class BaseEntity {
                     else {
                         // First run synchronous validation
                         valResult = this.Validate();
-                        // Determine if we should run async validation:
-                        // 1. Explicitly set in options, OR
-                        // 2. Use the subclass's default if not specified in options
-                        const skipAsyncValidation = _options.SkipAsyncValidation !== undefined ?
-                            _options.SkipAsyncValidation : this.DefaultSkipAsyncValidation;
+                        // Determine if we should run async validation, in order of authority:
+                        //   1. An explicit SkipAsyncValidation in the options.
+                        //   2. An explicit DefaultSkipAsyncValidation override on the subclass.
+                        //   3. Neither: run it if — and only if — a subclass wrote a ValidateAsync
+                        //      to run. Overriding the method IS the request to run it.
+                        //
+                        // Case 3 is the fix for a silent no-op. The default is `true`, and the base
+                        // ValidateAsync just returns success, so skipping costs a subclass that did
+                        // not override it precisely nothing. The flag's only reachable effect was
+                        // therefore to disable the async rules of subclasses that WROTE async rules
+                        // and never learned a second, separate getter had to be overridden too —
+                        // which the ValidateAsync docstring did not mention while promising the
+                        // method was "automatically called by Save()".
+                        //
+                        // That is how OrderEntityServer.ValidateAsync — holding both the "cannot
+                        // confirm an order with no lines" guard and an entire per-line validation
+                        // loop — was dead on every save in production, and it is the same reasoning
+                        // that already exempts companions below.
+                        const skipAsyncValidation = _options.SkipAsyncValidation !== undefined
+                            ? _options.SkipAsyncValidation
+                            : IsMemberOverridden(this, 'DefaultSkipAsyncValidation', BaseEntity)
+                                ? this.DefaultSkipAsyncValidation
+                                : !IsMemberOverridden(this, 'ValidateAsync', BaseEntity);
                         // If not skipping async validation, run it - even if sync validation failed
                         // This ensures all validation errors (sync and async) are collected
                         if (!skipAsyncValidation) {
@@ -2937,7 +3174,11 @@ export class BaseEntity {
     finalizeSave(data, saveSubType) {
         if (data) {
             this.init(); // wipe out the current data to flush out the DIRTY flags, load the ID as part of this too
-            this.SetMany(data, false, true, true); // set the new values from the data returned from the save, this will also reset the old values
+            const fieldData = (data instanceof BaseEntity || (data && typeof data.GetAll === 'function')) ? data.GetAll() : data;
+            // IS-A GetAll() merges the parent, including parent virtuals this entity
+            // does not own (e.g. OrderHeader on Event Order Line). Keep only columns
+            // this entity defines, and ignore anything leftover.
+            this.SetMany(this.ownedFieldsFrom(fieldData), true, true, true);
             this._everSaved = true; // Mark as saved after successful save
             const result = this.LatestResult;
             if (result)
@@ -2975,7 +3216,9 @@ export class BaseEntity {
         }
         // Cache it via this entity's provider so the cache lives on the right connection.
         const md = this.ProviderToUse;
-        md.SetCachedRecordName(this.EntityInfo.Name, this.PrimaryKey, recordName);
+        if (typeof md?.SetCachedRecordName === 'function') {
+            md.SetCachedRecordName(this.EntityInfo.Name, this.PrimaryKey, recordName);
+        }
     }
     /**
      * Utility method that returns true if the given permission being checked is enabled for the current user, and false if not.
@@ -3249,6 +3492,10 @@ export class BaseEntity {
             !this.EntityInfo?.IsParentType;
         if (canTakeFastPath) {
             this._raw = data;
+            // Drop any conversions memoized from a previously-loaded row — they describe the old
+            // `_raw`, not this one. No isFrozen probe is needed: `Get()` never writes to `_raw`,
+            // so whether the row is frozen (now, or at any point later) does not affect reads.
+            this._rawConverted = null;
             // Mirror the "are PKs present?" check that the hydrated path does, but read straight
             // from the raw data so we don't trigger hydration.
             const pks = this.EntityInfo?.PrimaryKeys ?? [];
@@ -3395,11 +3642,19 @@ export class BaseEntity {
     }
     /**
      * Default value for whether async validation should be skipped.
-     * Subclasses can override this property to enable async validation by default.
-     * When the options object is passed to Save(), and it includes a value for the
-     * SkipAsyncValidation property, that value will take precedence over this default.
+     *
+     * @remarks
+     * Override this to state a policy explicitly; an explicit override always wins over the
+     * inference described below. When the options object passed to `Save()` includes
+     * `SkipAsyncValidation`, that value takes precedence over both.
+     *
+     * **If no subclass overrides this getter**, the answer is inferred instead: async validation
+     * runs when a subclass has overridden {@link ValidateAsync}, and is skipped when none has.
+     * Reading the literal `true` below as "async validation is off unless you find this getter"
+     * made every hand-written `ValidateAsync` a silent no-op — see the note on that method.
      *
      * @see {@link Save}
+     * @see {@link ValidateAsync}
      *
      * @protected
      */
@@ -3414,6 +3669,15 @@ export class BaseEntity {
      * 1. This should NEVER be called INSTEAD of the synchronous Validate() method
      * 2. This is meant to be overridden by subclasses that need to perform async validations
      * 3. The base implementation just returns success - no actual validation is performed
+     * 4. Overriding this method is what turns it on. You do NOT also have to override
+     *    {@link DefaultSkipAsyncValidation} — that getter is for stating a policy explicitly, and
+     *    an explicit override of it (either value) still wins. To suppress async validation for one
+     *    call, pass `SkipAsyncValidation: true` in the save options.
+     *
+     * Point 4 used to be the opposite, and it was not discoverable: `DefaultSkipAsyncValidation`
+     * defaults to `true`, so an override written against this docstring alone never ran. It reads
+     * as enforced, reviews as enforced, and was not — the failure mode that let an order confirm
+     * with no lines in production.
      *
      * Subclasses should override this to add complex validations that require database queries
      * or other async operations that cannot be performed in the synchronous Validate() method.
@@ -3436,11 +3700,6 @@ export class BaseEntity {
      * @returns Promise<boolean>
      */
     async Delete(options) {
-        // Executing our own node inside a delete graph we already planned. Bypass both the debounce
-        // and graph routing — see EntityDeleteOptions.IsGraphNodeDelete.
-        if (options?.IsGraphNodeDelete) {
-            return this._InnerDelete(options);
-        }
         // Composite routing: companions that own their children (OnRemove:'delete') contribute
         // child deletions that must run before this row disappears. A single-node plan falls
         // through to the ordinary path, so nothing changes for entities without companions.
@@ -4044,5 +4303,115 @@ export class BaseEntity {
     ResetVectors() {
         this._vectors.clear();
     }
+    /**
+     * Resolves the recursive foreign key field for this entity. If `parentFieldName` is provided,
+     * finds that specific field. Otherwise defaults to 'ParentID' if present, or the first
+     * self-referencing foreign key field found on the entity.
+     */
+    getRecursiveForeignKeyField(parentFieldName) {
+        if (!this.EntityInfo)
+            return null;
+        if (this.PrimaryKeys.length !== 1) {
+            LogError(`BaseEntity hierarchy methods: Entity '${this.EntityInfo.Name}' has ${this.PrimaryKeys.length} primary key fields. MemberJunction hierarchy traversal requires a single-column primary key.`);
+            return null;
+        }
+        const fields = this.EntityInfo.Fields ?? [];
+        if (parentFieldName) {
+            const match = fields.find(f => f.Name.toLowerCase() === parentFieldName.toLowerCase() || f.CodeName.toLowerCase() === parentFieldName.toLowerCase());
+            return match ?? null;
+        }
+        // Check for field explicitly configured with IsHierarchy = true first
+        const explicitHierarchyField = fields.find(f => f.IsHierarchy && (UUIDsEqual(f.RelatedEntityID, this.EntityInfo?.ID) || f.RelatedEntity === this.EntityInfo?.Name));
+        if (explicitHierarchyField)
+            return explicitHierarchyField;
+        // Check for 'ParentID' self-referencing foreign key next
+        const parentIdField = fields.find(f => f.Name.toLowerCase() === 'parentid' && (UUIDsEqual(f.RelatedEntityID, this.EntityInfo?.ID) || f.RelatedEntity === this.EntityInfo?.Name));
+        if (parentIdField)
+            return parentIdField;
+        // Fall back to first recursive foreign key field
+        return fields.find(f => f.RelatedEntityID && (UUIDsEqual(f.RelatedEntityID, this.EntityInfo?.ID) || f.RelatedEntity === this.EntityInfo?.Name)) ?? null;
+    }
+    /**
+     * Retrieves all descendant records in the hierarchy under this record using a single RunView query.
+     * @param optionsOrMaxDepth Optional maximum relative depth to retrieve, or an options object.
+     * @returns Array of descendant entity instances ordered by hierarchy depth.
+     */
+    async GetDescendants(options) {
+        const maxDepth = typeof options === 'number' ? options : options?.maxDepth;
+        const parentFieldName = typeof options === 'object' ? options?.parentFieldName : undefined;
+        const fkField = this.getRecursiveForeignKeyField(parentFieldName);
+        if (!fkField) {
+            LogError(`BaseEntity.GetDescendants(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
+            return [];
+        }
+        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const rootId = this.Get(pkName);
+        if (!rootId)
+            return [];
+        const rootFieldName = `Root${fkField.Name}`;
+        const depthFieldName = `${fkField.Name}Depth`;
+        const filter = maxDepth != null
+            ? `${rootFieldName} = '${rootId}' AND ${depthFieldName} <= ${maxDepth}`
+            : `${rootFieldName} = '${rootId}'`;
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: this.EntityInfo.Name,
+            ExtraFilter: filter,
+            OrderBy: `${depthFieldName} ASC`,
+        }, this._contextCurrentUser);
+        return result.Success ? (result.Results ?? []) : [];
+    }
+    /**
+     * Retrieves all ancestor records in the hierarchy from the top-level root down to this record using a single RunView query.
+     * @param parentFieldName Optional recursive foreign key field name (defaults to 'ParentID' or the first recursive FK found).
+     * @returns Array of ancestor entity instances ordered from root down to parent.
+     */
+    async GetAncestors(parentFieldName) {
+        const fkField = this.getRecursiveForeignKeyField(parentFieldName);
+        if (!fkField) {
+            LogError(`BaseEntity.GetAncestors(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
+            return [];
+        }
+        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const currentId = this.Get(pkName);
+        const pathFieldName = `${fkField.Name}Path`;
+        const depthFieldName = `${fkField.Name}Depth`;
+        const path = this.Get(pathFieldName);
+        if (!path)
+            return [];
+        const rawIds = path.split('/').filter(id => id.length > 0 && id !== currentId);
+        if (rawIds.length === 0)
+            return [];
+        const rv = new RunView();
+        const idList = rawIds.map(id => `'${id}'`).join(',');
+        const result = await rv.RunView({
+            EntityName: this.EntityInfo.Name,
+            ExtraFilter: `${pkName} IN (${idList})`,
+            OrderBy: `${depthFieldName} ASC`,
+        }, this._contextCurrentUser);
+        return result.Success ? (result.Results ?? []) : [];
+    }
+    /**
+     * Retrieves all direct child records of this record using a single RunView query.
+     * @param parentFieldName Optional recursive foreign key field name (defaults to 'ParentID' or the first recursive FK found).
+     * @returns Array of direct child entity instances.
+     */
+    async GetChildren(parentFieldName) {
+        const fkField = this.getRecursiveForeignKeyField(parentFieldName);
+        if (!fkField) {
+            LogError(`BaseEntity.GetChildren(): No recursive foreign key field found on entity ${this.EntityInfo?.Name}`);
+            return [];
+        }
+        const pkName = this.FirstPrimaryKey?.Name ?? 'ID';
+        const currentId = this.Get(pkName);
+        if (!currentId)
+            return [];
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: this.EntityInfo.Name,
+            ExtraFilter: `${fkField.Name} = '${currentId}'`,
+        }, this._contextCurrentUser);
+        return result.Success ? (result.Results ?? []) : [];
+    }
 }
 //# sourceMappingURL=baseEntity.js.map