@memberjunction/core 5.51.0 → 6.1.0-edge.1

package/dist/generic/baseEntity.js

@@ -16,6 +16,11 @@ import { Metadata } from './metadata.js';
 import { RunView } from '../views/runView.js';
 import { LogDebug, LogError } from './logging.js';
 import { CompositeKey } from './compositeKey.js';
+import { RelatedRecordCollection } from './relatedRecordCollection.js';
+import { COMPANION_PAYLOAD_KEY } from './entityCompanion.js';
+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';
 /**
  * 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
@@ -537,15 +542,6 @@ export class BaseEntity {
             this._resultHistory.splice(0, overflow);
         }
     }
-    /**
-     * Gets the provider transaction handle for IS-A chain orchestration.
-     */
-    get ProviderTransaction() { return this._providerTransaction; }
-    /**
-     * Sets the provider transaction handle. Used during IS-A save/delete to share
-     * a single database transaction across the entire parent chain.
-     */
-    set ProviderTransaction(value) { this._providerTransaction = value; }
     /**
      * Returns the parent entity in the IS-A composition chain, or null if this
      * entity is not an IS-A child type.
@@ -771,12 +767,21 @@ export class BaseEntity {
          */
         this._childEntities = null;
         /**
-         * Opaque provider-level transaction handle. Used by IS-A save/delete orchestration
-         * to share a single SQL transaction across the parent chain.
-         * On client (GraphQLDataProvider), this remains null.
-         * On server (SQLServerDataProvider), this holds a sql.Transaction.
+         * The active transaction scope owned by this entity, when it is the participant that opened (or
+         * joined) one for a multi-record unit of work — an IS-A parent chain or a composite save graph.
+         *
+         * Only the *initiator* holds a scope; other participants in the same unit of work simply write
+         * into the provider's ambient transaction without knowing it exists. That is the whole point of
+         * routing through the provider: participants stay ignorant of one another.
+         */
+        this._entityTransactionScope = null;
+        /**
+         * Companions registered on this entity, keyed by {@link EntityCompanion.Name}.
+         *
+         * Lazily created so that the overwhelming majority of entities — which declare no companions —
+         * pay nothing for the feature, not even an empty Map per instance.
          */
-        this._providerTransaction = null;
+        this._companions = null;
         this._compositeKey = null;
         // ────────────────────────────────────────────────────────────────────
         // Restore context — populated by callers immediately before Save() to
@@ -1024,15 +1029,572 @@ export class BaseEntity {
         // entities in the chain that don't exist on this entity.
         this.SetMany(data, true, true, true);
     }
+    // ─── Entity Companions ──────────────────────────────────────────────────────
+    //
+    // Companions are named, serialisable side-channels attached to a record — most commonly
+    // related-record collections. See entityCompanion.ts for the full rationale and lifecycle.
     /**
-     * Propagates the ProviderTransaction handle down the IS-A parent chain so all
-     * entities in the chain execute on the same database transaction.
+     * The companions registered on this entity, in declaration order.
+     *
+     * Empty for the vast majority of entities. Nothing in the save, load or validation paths does
+     * any companion work when this is empty, so the feature costs nothing where it is unused.
      */
-    PropagateTransactionToParents() {
-        let current = this._parentEntity;
-        while (current) {
-            current.ProviderTransaction = this._providerTransaction;
-            current = current._parentEntity;
+    get Companions() {
+        return this._companions ? Array.from(this._companions.values()) : [];
+    }
+    /**
+     * Whether this entity has any registered companions.
+     *
+     * Used as the fast guard on the hot paths — a single boolean check keeps single-record saves on
+     * exactly the code path they took before companions existed.
+     */
+    get HasCompanions() {
+        return this._companions !== null && this._companions.size > 0;
+    }
+    /**
+     * Registers a companion on this entity. Called from a subclass constructor or field
+     * initialiser, normally via {@link DeclareRelatedRecords}.
+     *
+     * @typeParam TCompanion - The companion type.
+     * @param companion - The companion to register.
+     * @returns The same companion, so it can be assigned to a readonly field in one expression.
+     * @throws When a companion with the same name is already registered — a duplicate name would
+     *         make the wire payload ambiguous and silently drop one of the two.
+     */
+    RegisterCompanion(companion) {
+        if (!this._companions) {
+            this._companions = new Map();
+        }
+        if (this._companions.has(companion.Name)) {
+            throw new Error(`BaseEntity.RegisterCompanion: '${companion.Name}' is already registered on ` +
+                `${this.EntityInfo?.Name ?? this.constructor.name}. Companion names must be unique per entity.`);
+        }
+        this._companions.set(companion.Name, companion);
+        return companion;
+    }
+    /**
+     * Looks up a registered companion by name.
+     *
+     * @typeParam TCompanion - The expected companion type.
+     * @param name - The companion's {@link EntityCompanion.Name}.
+     * @returns The companion, or `undefined` when none is registered under that name.
+     */
+    GetCompanion(name) {
+        return this._companions?.get(name);
+    }
+    /**
+     * Declares a typed child collection on this entity and registers it as a companion.
+     *
+     * This is the entry point for composite entities. Call it from a field initialiser on a
+     * **shared** (client + server) subclass so both tiers see the collection — a declaration that
+     * exists only in a server-side class makes the collection invisible to the browser, which is
+     * exactly the limitation this feature removes.
+     *
+     * @typeParam TChild - The child entity type.
+     * @param options - The collection declaration.
+     * @returns The registered collection.
+     *
+     * @example
+     * ```typescript
+     * public readonly Lines = this.DeclareRelatedRecords<OrderLineEntity>({
+     *     Name: 'Lines',
+     *     ChildEntity: 'MJ_BizApps_Orders: Order Lines',
+     *     ForeignKey: 'OrderHeaderID',
+     *     OrderBy: 'LineNumber ASC',
+     *     Sequence: { Field: 'LineNumber', From: 1 },
+     * });
+     * ```
+     */
+    DeclareRelatedRecords(options) {
+        return this.RegisterCompanion(new RelatedRecordCollection(this, options));
+    }
+    /**
+     * 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.
+     *
+     * @returns The companion payloads, in declaration order.
+     */
+    async SerializeCompanions() {
+        if (!this.HasCompanions) {
+            return [];
+        }
+        const payloads = [];
+        for (const companion of this.Companions) {
+            const data = await companion.Serialize();
+            if (data !== null && data !== undefined) {
+                payloads.push({ Name: companion.Name, Data: data });
+            }
+        }
+        return payloads;
+    }
+    /**
+     * Restores companion state from payloads produced by {@link SerializeCompanions} on the other
+     * tier.
+     *
+     * Payloads naming a companion this entity does not declare are **ignored rather than rejected**.
+     * That is deliberate: during a rolling deploy the two tiers can disagree about which companions
+     * exist, and a hard failure would turn a harmless version skew into an outage. The mismatch is
+     * logged so it is still visible.
+     *
+     * @param payloads - Companion payloads received from the other tier.
+     * @param mode - Whether these payloads are an inbound request (the default) or authoritative
+     *               post-save results. See {@link EntityCompanionDeserializeMode}.
+     */
+    async DeserializeCompanions(payloads, mode = 'request') {
+        if (!payloads || payloads.length === 0) {
+            return;
+        }
+        for (const payload of payloads) {
+            const companion = this.GetCompanion(payload.Name);
+            if (!companion) {
+                LogDebug(`BaseEntity.DeserializeCompanions: no companion named '${payload.Name}' on ` +
+                    `${this.EntityInfo?.Name}; ignoring (tier version skew is expected during rolling deploys).`);
+                continue;
+            }
+            await companion.Deserialize(payload.Data, mode);
+        }
+    }
+    /**
+     * Executes a multi-node plan by handing the entire unit of work to the server.
+     *
+     * Used when the provider cannot open a local transaction — i.e. from the browser. The client
+     * does not orchestrate the cascade; it ships intent, and the server runs the *same*
+     * `executeGraphLocal` path inside a real transaction. One cascade implementation, two possible
+     * locations.
+     *
+     * @param plan - The planned unit of work. Used for its node count in events and diagnostics;
+     *               the server rebuilds its own plan from the payload.
+     * @param _options - Save options. Not forwarded over the wire: they describe local execution
+     *                   preferences, and the server applies its own.
+     * @returns True when the server reports the graph committed.
+     */
+    async executeGraphRemote(plan, _options) {
+        try {
+            const operation = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRemotableOperation, SAVE_ENTITY_GRAPH_OPERATION_KEY);
+            if (!operation) {
+                throw new Error(`Composite save requires the '${SAVE_ENTITY_GRAPH_OPERATION_KEY}' remote operation, which is ` +
+                    `not registered in this process.`);
+            }
+            const result = await operation.Execute({
+                EntityName: this.EntityInfo.Name,
+                Fields: this.GetAll(),
+                Companions: await this.SerializeCompanions(),
+                IsExistingRecord: this.IsSaved,
+            }, { provider: this.ProviderToUse, user: this.ActiveUser });
+            if (!result.Success || !result.Output?.Success) {
+                const detail = result.ErrorMessage ?? result.Output?.ErrorMessage ?? 'unknown error';
+                this.registerGraphFailure(detail);
+                this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: detail });
+                return false;
+            }
+            await this.applyGraphResult(result.Output);
+            this.RaiseEvent('graph_save', { Success: true, NodeCount: plan.NodeCount });
+            return true;
+        }
+        catch (e) {
+            const detail = e instanceof Error ? e.message : String(e);
+            LogError(`BaseEntity.executeGraphRemote failed for ${this.EntityInfo?.Name}: ${detail}`);
+            this.registerGraphFailure(detail);
+            this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: detail });
+            return false;
+        }
+    }
+    /**
+     * Adopts the post-save state the server returned for the whole graph.
+     *
+     * Both halves matter. Refreshing only the header would leave the client holding children that
+     * still look unsaved — they would be re-inserted on the next save, silently duplicating rows.
+     *
+     * @param output - The server's result graph.
+     */
+    async applyGraphResult(output) {
+        // Captured at entry — the last moment the create-vs-update distinction exists on this
+        // object, since `_everSaved` is stamped true a few lines down. The result history and the
+        // 'save' event both carry it; hardcoding 'update' here made every remote graph CREATE
+        // report (and notify subscribers) as an update.
+        const saveSubType = this.IsSaved ? 'update' : 'create';
+        // Root: rebase field values and dirty state onto what the database now holds.
+        this.init();
+        this.SetMany(output.Fields, false, true, true);
+        this._recordLoaded = true;
+        this._everSaved = true;
+        // Children: adopt server-assigned primary keys and computed values. 'result' mode adopts the
+        // returned state verbatim — these rows were just persisted by the sender, so re-loading them
+        // would be one wasted round trip per record for data we already hold.
+        await this.DeserializeCompanions(output.Companions ?? [], 'result');
+        this.acceptCompanionChanges();
+        const result = new BaseEntityResult();
+        result.Success = true;
+        result.Type = saveSubType;
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        this.RegisterResultHistoryEntry(result);
+        this.RaiseEvent('save', null, saveSubType);
+    }
+    /**
+     * Gives every eager companion a chance to populate itself.
+     *
+     * Called from {@link InnerLoad} only — deliberately **not** from {@link LoadFromData}. See
+     * {@link RelatedRecordLoadMode} for why that distinction is load-bearing.
+     */
+    /**
+     * Populates this record's declared related-record collections and resolves once they are all
+     * ready — the one call to `await` when you want a fully-hydrated record.
+     *
+     * The point is batching. Cache-sourced collections resolve synchronously against
+     * `BaseEngineRegistry` and cost nothing; every database-sourced collection is gathered into a
+     * **single `RunViews` call** rather than one `RunView` each. So a record with four declared
+     * collections costs one round trip, or zero when they all read from engine caches — instead of
+     * the four sequential queries a naive `for (…) await c.Load()` would issue.
+     *
+     * Collections declared `'never'` are skipped: that mode means write-only staging buffer.
+     *
+     * @param names - Collection names to load. Omit to load every declared collection.
+     *
+     * @example
+     * ```typescript
+     * await action.LoadRelatedRecords();              // Params, ResultCodes and Libraries, one trip
+     * await agent.LoadRelatedRecords('Prompts');      // just the one
+     * ```
+     */
+    async LoadRelatedRecords(...names) {
+        const wanted = names.length > 0 ? new Set(names.map(n => n.trim().toLowerCase())) : null;
+        const collections = this.Companions.filter((c) => c instanceof RelatedRecordCollection &&
+            c.LoadMode !== 'never' &&
+            (!wanted || wanted.has(c.Name.trim().toLowerCase())));
+        if (collections.length === 0) {
+            return;
+        }
+        // Cache-backed ones first — synchronous, zero queries. Whatever misses falls through to the
+        // batched database load below, so a donor engine that is not loaded yet costs correctness
+        // nothing. Database-backed collections carry the same guards Load() itself has: a
+        // collection that is already loaded, or that holds staged work (new/edited children,
+        // pending removals), is left alone — without those guards this call re-queried an
+        // already-loaded collection and, worse, WIPED staged children on a new parent, because the
+        // parent's pre-generated UUID matches zero rows and SetLoadedItems([]) discards everything.
+        const needsDatabase = [];
+        for (const collection of collections) {
+            if (await collection.TryLoadFromCache()) {
+                continue;
+            }
+            if (collection.IsLoaded || collection.Dirty) {
+                continue;
+            }
+            needsDatabase.push(collection);
+        }
+        // An unsaved parent owns no persisted related records — mirror Load()'s own guard rather
+        // than issuing queries guaranteed to return nothing (and destroy staged state adopting it).
+        if (needsDatabase.length === 0 || !this.IsSaved) {
+            return;
+        }
+        // One `RunViews` for all remaining collections — N declared collections cost one round trip,
+        // not N. Params are built per collection so each keeps its own filter and ordering. The key
+        // is escaped exactly as RelatedRecordCollection.Load() and the batch loader escape it.
+        const parentKeyLiteral = String(this.FirstPrimaryKey?.Value).replace(/'/g, "''");
+        const rv = new RunView(this.ProviderToUse);
+        const results = await rv.RunViews(needsDatabase.map(c => ({
+            EntityName: c.RelatedEntityName,
+            ExtraFilter: `${c.RelatedEntityJoinField} = '${parentKeyLiteral}'`,
+            OrderBy: c.OrderByClause,
+            ResultType: 'entity_object',
+        })), this.ContextCurrentUser);
+        needsDatabase.forEach((collection, i) => {
+            const result = results?.[i];
+            if (result?.Success) {
+                collection.SetLoadedItems(result.Results ?? []);
+            }
+            else {
+                LogError(`BaseEntity.LoadRelatedRecords: '${collection.Name}' failed — ${result?.ErrorMessage ?? 'no result'}`);
+            }
+        });
+    }
+    async loadEagerCompanions() {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            await companion.LoadEager();
+        }
+    }
+    /**
+     * Tells every companion that the unit of work committed, so they can clear pending removals and
+     * rebase their dirty state.
+     */
+    acceptCompanionChanges() {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            companion.AcceptChanges();
+        }
+    }
+    /**
+     * Opens a transaction scope for a multi-record unit of work rooted at this entity, when this
+     * entity is the initiator and is not already inside a `TransactionGroup`.
+     *
+     * Participants never ask whether a transaction is already open — the provider arbitrates and
+     * either starts one or joins the one in flight. See {@link EntityTransactionScope}.
+     *
+     * @param isInitiator - Whether this entity is the one orchestrating the unit of work. Non-
+     *                      initiators never open a scope; they write into the ambient transaction.
+     * @returns True if a scope was opened (or joined) and is now held by this entity.
+     */
+    async beginEntityTransactionScope(isInitiator) {
+        // A TransactionGroup manages its own atomicity and defers every save until Submit(); opening
+        // a provider transaction underneath it would wrap statements that have not run yet.
+        if (!isInitiator || this.TransactionGroup) {
+            return false;
+        }
+        const provider = this.ProviderToUse;
+        if (provider?.SupportsEntityTransactions !== true || !provider.BeginEntityTransaction) {
+            return false; // client-side provider — no local transaction to open
+        }
+        this._entityTransactionScope = await provider.BeginEntityTransaction();
+        return true;
+    }
+    /**
+     * Builds the ordered unit of work for saving this record and everything its companions
+     * contribute.
+     *
+     * The root node comes first — children need the parent's primary key, and on a create it does
+     * not exist until the parent row is inserted.
+     *
+     * @param includeRoot - Whether to include this record's own save. False when the caller has
+     *                      already persisted the root by other means.
+     * @param saveOptions - The caller's save options, forwarded to each companion so it can honor
+     *                      flags that change what counts as work (`IgnoreDirtyState`, most
+     *                      importantly — a companion that skips clean children must not skip them
+     *                      when the caller demanded a full write-out).
+     * @returns The plan. A `NodeCount` of 1 means there is no graph and the caller should take the
+     *          ordinary single-record path.
+     */
+    BuildSavePlan(includeRoot = true, saveOptions) {
+        const plan = new EntitySavePlan(this);
+        if (includeRoot) {
+            plan.AddSave(this, this.EntityInfo?.Name ?? 'root', undefined, /* selfOnly */ true);
+        }
+        for (const companion of this.Companions) {
+            companion.ContributeSaveWork(plan, saveOptions);
+        }
+        return plan;
+    }
+    /**
+     * Builds the ordered unit of work for deleting this record and everything its companions
+     * contribute.
+     *
+     * Companions contribute **first**: children hold foreign keys pointing at the row that is about
+     * to disappear, so they must be removed before it.
+     *
+     * @returns The plan.
+     */
+    BuildDeletePlan() {
+        const plan = new EntitySavePlan(this);
+        for (const companion of this.Companions) {
+            companion.ContributeDeleteWork(plan);
+        }
+        plan.Add({
+            Entity: this,
+            Operation: 'Delete',
+            Label: this.EntityInfo?.Name ?? 'root',
+            SelfOnly: true,
+        });
+        return plan;
+    }
+    /**
+     * Runs a multi-record save as one unit of work, choosing where it executes based on what the
+     * provider can do.
+     *
+     * This is the single decision point for the whole feature:
+     *
+     * - **Provider supports entity transactions** (server): execute locally inside one transaction.
+     * - **It does not** (client): serialize the graph and hand the entire unit of work to the
+     *   server via the `MJ.SaveEntityGraph` remote operation, which rebuilds the records — as their
+     *   *server-side* registered subclasses — and runs this very same local executor there.
+     *
+     * There is exactly one cascade implementation. The remote path relocates it; it never
+     * reimplements it. That is what keeps client and server behavior from drifting.
+     *
+     * Validation is not performed here: the root node's own `_InnerSave` runs `Validate()` (which
+     * fans out to every companion, over the complete child set including pending removals) before
+     * it writes anything, and the root node executes first. So the whole graph is validated before
+     * the first row lands, which is the guarantee cross-child invariants need.
+     *
+     * @param plan - The planned unit of work.
+     * @param options - Save options forwarded to every node.
+     * @returns True when the whole graph committed.
+     */
+    async saveGraph(plan, options) {
+        this.RaiseEvent('graph_save_started', { NodeCount: plan.NodeCount });
+        if (this.ProviderToUse?.SupportsEntityTransactions === true) {
+            return this.executeGraphLocal(plan, options);
+        }
+        return this.executeGraphRemote(plan, options);
+    }
+    /**
+     * Runs a multi-record delete as one unit of work.
+     *
+     * Unlike the save path there is no remote counterpart: a delete graph carries no state that
+     * needs rebuilding server-side, so on a client provider the nodes execute in order over
+     * ordinary mutations. That is **not atomic** — a failure partway leaves earlier deletions
+     * committed. Callers needing an atomic multi-record delete from the browser should expose a
+     * dedicated remote operation, which is also what MJ's own cascade-delete tooling does.
+     *
+     * @param plan - The planned unit of work, children first.
+     * @param options - Delete options forwarded to every node.
+     * @returns True when the whole graph completed.
+     */
+    async deleteGraph(plan, options) {
+        this.RaiseEvent('graph_save_started', { NodeCount: plan.NodeCount, Operation: 'Delete' });
+        return this.executeGraphLocal(plan, undefined, options, 'delete');
+    }
+    /**
+     * Executes a multi-node plan locally, inside a single provider transaction.
+     *
+     * Used when the provider reports {@link IMetadataProvider.SupportsEntityTransactions} — i.e.
+     * server-side. The transaction is provider-arbitrated, so this composes correctly whether it is
+     * the outermost unit of work or nested inside an application cascade that already opened one.
+     *
+     * @param plan - The plan to run.
+     * @param saveOptions - Options forwarded to save nodes.
+     * @param deleteOptions - Options forwarded to delete nodes.
+     * @returns True when every node succeeded and the transaction committed.
+     */
+    async executeGraphLocal(plan, saveOptions, deleteOptions, operationKind = 'save') {
+        const provider = this.ProviderToUse;
+        // Passed explicitly rather than inferred from which options object is set: `Delete()` is
+        // routinely called with no arguments, so an inference would mislabel every such failure.
+        const operation = operationKind;
+        // One cycle-guard set per unit of work: inherited when this graph is nested inside another
+        // (so a child sees its ancestors), created fresh when this graph is the outermost one.
+        // Child nodes must carry it on their own options, because a child node runs the child's
+        // `Save()`, which builds and executes a plan of its own.
+        const visited = saveOptions?.GraphVisited ?? deleteOptions?.GraphVisited ?? new Set();
+        const childSaveOptions = Object.assign(new EntitySaveOptions(), saveOptions ?? {});
+        childSaveOptions.GraphVisited = visited;
+        const childDeleteOptions = Object.assign(new EntityDeleteOptions(), deleteOptions ?? {});
+        childDeleteOptions.GraphVisited = visited;
+        // 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.
+        let scope = null;
+        try {
+            scope =
+                provider?.SupportsEntityTransactions === true && provider.BeginEntityTransaction
+                    ? await provider.BeginEntityTransaction()
+                    : null;
+            const result = await ExecuteEntitySavePlan(plan, {
+                SaveOptions: childSaveOptions,
+                RootSaveOptions: this.buildRootSaveOptions(saveOptions),
+                DeleteOptions: childDeleteOptions,
+                RootDeleteOptions: this.buildRootDeleteOptions(deleteOptions),
+                Visited: visited,
+            });
+            if (!result.Success) {
+                await scope?.Rollback();
+                this.registerGraphFailure(result.ErrorMessage, operation);
+                this.RaiseEvent('graph_save', { Success: false, NodeCount: plan.NodeCount, Error: result.ErrorMessage });
+                return false;
+            }
+            await scope?.Commit();
+            this.acceptCompanionChanges();
+            this.RaiseEvent('graph_save', { Success: true, NodeCount: plan.NodeCount });
+            return true;
+        }
+        catch (e) {
+            // Rollback failures are logged and swallowed: this is already the failure path, and a
+            // secondary throw (a doomed transaction refusing a savepoint rollback, a dropped
+            // connection) would both replace the real error and escape the no-throw contract.
+            try {
+                await scope?.Rollback();
+            }
+            catch (rollbackError) {
+                LogError(`BaseEntity.executeGraphLocal: rollback failed after graph error for ` +
+                    `${this.EntityInfo?.Name}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+            }
+            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;
+        }
+    }
+    /**
+     * 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.
+     */
+    buildRootSaveOptions(source) {
+        const options = Object.assign(new EntitySaveOptions(), source ?? {});
+        options.IsGraphNodeSave = true;
+        return 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.
+     */
+    buildRootDeleteOptions(source) {
+        const options = Object.assign(new EntityDeleteOptions(), source ?? {});
+        options.IsGraphNodeDelete = true;
+        return options;
+    }
+    /**
+     * Records a graph-level failure on this entity's result history.
+     *
+     * Without this the caller gets a bare `false` while `LatestResult` still holds the *root's*
+     * successful save — so a child failure reads as "it just didn't work". Mirrors the parent-chain
+     * failure handling in `_InnerSave`.
+     *
+     * @param message - The failure detail.
+     */
+    registerGraphFailure(message, operation = 'save') {
+        const result = new BaseEntityResult();
+        result.Success = false;
+        result.Type = operation === 'delete' ? 'delete' : this.IsSaved ? 'update' : 'create';
+        result.Message = message ?? 'Entity graph operation failed';
+        result.StartedAt = new Date();
+        result.EndedAt = new Date();
+        result.OriginalValues = this.Fields.map(f => ({ FieldName: f.CodeName, Value: f.OldValue }));
+        this.RegisterResultHistoryEntry(result);
+    }
+    /**
+     * Commits the transaction scope held by this entity, if any. Safe to call unconditionally — a
+     * no-op when this entity holds no scope.
+     */
+    async commitEntityTransactionScope() {
+        const scope = this._entityTransactionScope;
+        if (!scope) {
+            return;
+        }
+        this._entityTransactionScope = null;
+        await scope.Commit();
+    }
+    /**
+     * Rolls back the transaction scope held by this entity, if any. Safe to call unconditionally.
+     *
+     * Rollback failures are logged and swallowed: this runs on the failure path, and throwing here
+     * would replace the caller's real error with a secondary one that explains less.
+     */
+    async rollbackEntityTransactionScope() {
+        const scope = this._entityTransactionScope;
+        if (!scope) {
+            return;
+        }
+        this._entityTransactionScope = null;
+        try {
+            await scope.Rollback();
+        }
+        catch (rollbackError) {
+            LogError(`Error rolling back entity transaction scope for ${this.EntityInfo?.Name}: ${rollbackError}`);
         }
     }
     /**
@@ -1053,12 +1615,6 @@ export class BaseEntity {
     get RunQueryProviderToUse() {
         return this.ProviderToUse;
     }
-    /**
-     * Returns the RunReportProvider to be used for a given instance of a BaseEntity derived subclass.
-     */
-    get RunReportProviderToUse() {
-        return this.ProviderToUse;
-    }
     /**
      * This method can be used to register a callback for events that will be raised by the instance of the BaseEntity object. The callback will be called with a
      * BaseEntityEvent object that contains the type of event and any payload that is associated with the event. Subclasses of the BaseEntity can define their
@@ -1337,10 +1893,18 @@ export class BaseEntity {
     }
     /**
      * Returns true if the object is Dirty, meaning something has changed since it was last saved to the database, and false otherwise. For new records, this will always return true.
+     *
+     * @remarks
+     * Dirtiness rolls up **companions** as well as fields. Without that rollup, a clean parent with
+     * three brand-new children reports `Dirty === false`, `_InnerSave` takes its not-dirty early
+     * return, and the children are silently never persisted — the save reports success and writes
+     * nothing. See {@link EntityCompanion.Dirty}.
      */
     get Dirty() {
         if (!this.IsSaved)
             return true;
+        if (this.companionsDirty)
+            return true;
         // Raw mode means LoadFromData populated us but no mutation has happened — nothing can be
         // dirty. Avoid hydrating just to check.
         if (!this._fieldsHydrated)
@@ -1348,6 +1912,17 @@ export class BaseEntity {
         return this._Fields.some(f => f.Dirty) ||
             (this._parentEntity?.Dirty ?? false);
     }
+    /**
+     * Whether any registered companion holds unsaved work.
+     *
+     * Guarded on {@link HasCompanions} so entities without companions — nearly all of them — do no
+     * extra work on this hot path.
+     */
+    get companionsDirty() {
+        if (!this.HasCompanions)
+            return false;
+        return this.Companions.some(c => c.Dirty);
+    }
     /**
      * Returns an array of all primary key fields for the entity. If the entity has a composite primary key, this method will return an array of all primary key fields.
      * If the entity has a single primary key, this method will return an array with a single field in it.
@@ -1734,6 +2309,16 @@ export class BaseEntity {
                 }
             }
         }
+        // Companion payloads ride along under a reserved key, following the convention already set
+        // by OldValues___ and RestoreContext___. This is what lets a composite cross the wire on any
+        // path that serializes via GetDataObject — including the TransactionGroup envelope, which
+        // carries whole records as EntityObjectJSON — with no change to the transport itself.
+        if (this.HasCompanions) {
+            const companions = await this.SerializeCompanions();
+            if (companions.length > 0) {
+                obj[COMPANION_PAYLOAD_KEY] = companions;
+            }
+        }
         return obj;
     }
     async GetRelatedEntityData(re, filter = null, maxRecords = null) {
@@ -2028,10 +2613,48 @@ export class BaseEntity {
         if (options?.IsParentEntitySave) {
             return this._InnerSave(options);
         }
-        // If a save is already in progress, return its promise.
+        // 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.
+        // Routing first meant each call built and executed its own full graph — a double insert of
+        // root and children — while single-row entities kept the debounce protection.
         if (this._pendingSave$) {
             return firstValueFrom(this._pendingSave$);
         }
+        // Composite routing: when companions contribute work, this save is a multi-record unit of
+        // work rather than a single row. Building the plan is cheap and, crucially, a plan with one
+        // node falls straight through to the ordinary path below — so entities without companions,
+        // and composites whose collections happen to be empty, behave exactly as they did before.
+        if (this.HasCompanions) {
+            const plan = this.BuildSavePlan(true, options);
+            if (plan.NodeCount > 1) {
+                // A TransactionGroup defers this record's own write until Submit(), while a graph
+                // executes its child nodes immediately (or ships the whole graph to the server) —
+                // children would insert rows pointing at a parent whose write is still queued, and
+                // the remote path would commit everything before the group ever submits. The
+                // combination cannot be made coherent, so refuse it loudly rather than silently
+                // tearing the group's atomicity. (Same conclusion as the guide: a TransactionGroup
+                // is not a composite-save engine — see guides/TRANSACTIONS_AND_BATCHING_GUIDE.md.)
+                if (this.TransactionGroup) {
+                    throw new Error(`${this.EntityInfo?.Name}: cannot save related-record collections while enrolled in a ` +
+                        `TransactionGroup. The group defers the parent's write until Submit(), so the graph's ` +
+                        `child records would persist against a parent row that does not exist yet. Save the ` +
+                        `composite record on its own — entity.Save() is already atomic for its collections — ` +
+                        `or detach it from the TransactionGroup first.`);
+                }
+                // 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.
+                this._pendingSave$ = of(options).pipe(switchMap(opts => from(this.saveGraph(plan, opts))), finalize(() => { this._pendingSave$ = null; }), shareReplay(1));
+                return firstValueFrom(this._pendingSave$);
+            }
+        }
         // Create a new observable that debounces duplicative calls, and executes the save.
         this._pendingSave$ = of(options).pipe(
         // Execute the actual save logic.
@@ -2064,15 +2687,12 @@ export class BaseEntity {
             }
             // IS-A orchestration: determine if this is the initiating save in a parent chain
             const isISAInitiator = (!!this._parentEntity) && !_options.IsParentEntitySave;
-            // Begin provider transaction if IS-A initiator and NOT in a TransactionGroup
-            // TransactionGroup manages its own atomicity; IS-A just orchestrates save order within it
-            if (isISAInitiator && !this.TransactionGroup) {
-                const txn = await this.ProviderToUse?.BeginISATransaction?.();
-                if (txn) {
-                    this.ProviderTransaction = txn;
-                    this.PropagateTransactionToParents();
-                }
-            }
+            // Open (or join) a transaction scope for the parent chain. The provider arbitrates:
+            // if a transaction is already in flight — an application cascade, an enclosing graph
+            // 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);
             // Save parent chain first (root → branch → immediate parent)
             // Parent calls Save() recursively which handles its own parents, permissions, validation
             if (this._parentEntity) {
@@ -2088,7 +2708,7 @@ export class BaseEntity {
                 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.RollbackISATransaction(isISAInitiator);
+                    await this.rollbackEntityTransactionScope();
                     // 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
@@ -2163,6 +2783,16 @@ export class BaseEntity {
                                 valResult.Errors.push(error);
                             });
                         }
+                        // Companion async validation runs REGARDLESS of skipAsyncValidation.
+                        //
+                        // That flag exists so an entity can opt out of its OWN expensive async
+                        // rules; applying it to companions silently disables cross-child invariants.
+                        // That is not hypothetical — it is exactly how OrderEntityServer's
+                        // ValidateAsync, holding both the "cannot confirm an order with no lines"
+                        // guard and the entire per-line validation loop, became dead code on every
+                        // save in production: the class never overrode DefaultSkipAsyncValidation
+                        // (which defaults to true) and no caller ever passed SkipAsyncValidation:false.
+                        await this.validateCompanionsAsync(valResult);
                     }
                     if (valResult.Success) {
                         // Run registered PreSave hooks (e.g., tenant validation)
@@ -2186,10 +2816,17 @@ export class BaseEntity {
                         if (!this.TransactionGroup) {
                             // no transaction group, so we have our results here
                             const result = this.finalizeSave(data, saveSubType);
-                            // IS-A: commit transaction after successful save (only the initiator commits)
-                            if (isISAInitiator && this.ProviderTransaction) {
-                                await this.ProviderToUse.CommitISATransaction?.(this.ProviderTransaction);
-                                this.ProviderTransaction = null;
+                            // Settle the scope this entity opened, if any (only the initiator holds
+                            // one). The provider can fail by RETURNING falsy data rather than
+                            // throwing — a validate-type entity action rejecting the save does
+                            // exactly that — and committing on that path would persist the parent
+                            // chain around a leaf that reported failure: precisely the torn write
+                            // this scope exists to prevent.
+                            if (result) {
+                                await this.commitEntityTransactionScope();
+                            }
+                            else {
+                                await this.rollbackEntityTransactionScope();
                             }
                             return result;
                         }
@@ -2230,13 +2867,19 @@ export class BaseEntity {
                     }
                 }
             }
-            else
+            else {
+                // Nothing to save — but the scope opened above (an IS-A initiator whose whole chain
+                // is clean) must still be settled. Returning with it open leaked the provider's
+                // ambient transaction: every subsequent write joined a transaction nobody would ever
+                // commit, so later "successful" saves were silently non-durable. Committing an
+                // empty scope writes nothing; it only releases the transaction.
+                await this.commitEntityTransactionScope();
                 return true; // nothing to save since we're not dirty
+            }
         }
         catch (e) {
-            // IS-A: rollback transaction on failure (only the initiator rolls back)
-            const isISAInitiator = this._parentEntity != null && !options?.IsParentEntitySave;
-            await this.RollbackISATransaction(isISAInitiator);
+            // 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
@@ -2291,21 +2934,6 @@ export class BaseEntity {
         // If no remaining children, safe to delete parent
         return remainingChildren.length === 0;
     }
-    /**
-     * Helper to rollback an IS-A provider transaction if one is active.
-     * Only called by the IS-A initiator (the leaf entity that started the chain).
-     */
-    async RollbackISATransaction(isInitiator) {
-        if (isInitiator && this.ProviderTransaction) {
-            try {
-                await this.ProviderToUse?.RollbackISATransaction?.(this.ProviderTransaction);
-            }
-            catch (rollbackError) {
-                LogError(`Error rolling back IS-A transaction: ${rollbackError}`);
-            }
-            this.ProviderTransaction = null;
-        }
-    }
     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
@@ -2511,6 +3139,15 @@ export class BaseEntity {
             // This populates _childEntity so Save/Delete can delegate to the leaf.
             // Only runs for parent-type entities; idempotent via _childEntityDiscoveryDone.
             await this.InitializeChildEntity();
+            // Companions declared Load:'immediate' populate here — and ONLY here.
+            //
+            // Deliberately not in LoadFromData(): that is the per-row materialization path for
+            // RunView(ResultType:'entity_object'), so an eager child query there becomes one query
+            // per row of every view. That is a live N+1 in production accounting code today
+            // (JournalEntryEntityServer.LoadFromData → LoadLines), and excluding it here is the
+            // structural fix. Set-oriented eager loading is served by RunView's batched child
+            // loading, which issues one WHERE fk IN (...) for the whole result set.
+            await this.loadEagerCompanions();
             // Raise load completion event
             this.RaiseEvent('load_complete', { CompositeKey });
             return true;
@@ -2666,8 +3303,27 @@ export class BaseEntity {
             this._recordLoaded = false;
             this._everSaved = false; // Mark as NOT saved since we loaded from data without primary keys
         }
+        // Absorb any companion payload that travelled with this record. This is the receiving half
+        // of the reserved-key convention applied in GetDataObject(). Note this restores state the
+        // sender already had — it never issues a query, so it cannot reintroduce the N+1 that
+        // eager companion loading is kept out of this method to avoid.
+        await this.deserializeCompanionsFromData(data);
         return true;
     }
+    /**
+     * Extracts and applies a companion payload carried inside a plain data object, if present.
+     *
+     * @param data - The plain object passed to {@link LoadFromData}.
+     */
+    async deserializeCompanionsFromData(data) {
+        if (!this.HasCompanions || !data || typeof data !== 'object') {
+            return;
+        }
+        const payloads = data[COMPANION_PAYLOAD_KEY];
+        if (Array.isArray(payloads)) {
+            await this.DeserializeCompanions(payloads);
+        }
+    }
     /**
      * This method is used automatically within Save() and is used to determine if the state of the object is valid relative to the validation rules that are defined in metadata. In addition, sub-classes can
      * override or wrap this base class method to add other logic for validation.
@@ -2696,8 +3352,47 @@ export class BaseEntity {
             });
             result.Success = result.Success && err.Success; // if any field fails, we fail, but keep going to get all of the validation messages
         }
+        // Companions validate LAST but still BEFORE any write, over their complete state including
+        // pending removals. That ordering is what lets a cross-child invariant — "debits must equal
+        // credits", "a confirmed order must have lines" — be enforced against the whole graph rather
+        // than discovered halfway through persisting it.
+        this.validateCompanions(result);
         return result;
     }
+    /**
+     * Fans synchronous validation out to every registered companion.
+     *
+     * @param result - The accumulating result companions contribute to.
+     */
+    validateCompanions(result) {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            companion.Validate(result);
+        }
+    }
+    /**
+     * Fans asynchronous validation out to every registered companion.
+     *
+     * @remarks
+     * Called from `_InnerSave` **independently of `DefaultSkipAsyncValidation`**. That flag lets an
+     * entity opt out of its *own* expensive async rules; extending it to companions silently
+     * disabled cross-child invariants, which is precisely how `OrderEntityServer.ValidateAsync` —
+     * containing both the "cannot confirm an order with no lines" guard and the entire per-line
+     * validation loop — became dead code on every save in production. Companion async validation
+     * runs whenever companions are present.
+     *
+     * @param result - The accumulating result companions contribute to.
+     */
+    async validateCompanionsAsync(result) {
+        if (!this.HasCompanions) {
+            return;
+        }
+        for (const companion of this.Companions) {
+            await companion.ValidateAsync(result);
+        }
+    }
     /**
      * Default value for whether async validation should be skipped.
      * Subclasses can override this property to enable async validation by default.
@@ -2741,6 +3436,20 @@ 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.
+        if (this.HasCompanions) {
+            const plan = this.BuildDeletePlan();
+            if (plan.NodeCount > 1) {
+                return this.deleteGraph(plan, options);
+            }
+        }
         // If a delete is already in progress, return its promise.
         if (this._pendingDelete$) {
             return firstValueFrom(this._pendingDelete$);
@@ -2808,14 +3517,10 @@ export class BaseEntity {
                         }
                     }
                 }
-                // Begin provider transaction if IS-A initiator and NOT in a TransactionGroup
-                if (isISAInitiator && !this.TransactionGroup) {
-                    const txn = await this.ProviderToUse?.BeginISATransaction?.();
-                    if (txn) {
-                        this.ProviderTransaction = txn;
-                        this.PropagateTransactionToParents();
-                    }
-                }
+                // 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);
                 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);
@@ -2844,7 +3549,7 @@ export class BaseEntity {
                             const parentResult = await this._parentEntity.Delete(parentDeleteOptions);
                             if (!parentResult) {
                                 // Parent delete failed — rollback if we started the transaction
-                                await this.RollbackISATransaction(isISAInitiator);
+                                await this.rollbackEntityTransactionScope();
                                 // 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
@@ -2874,11 +3579,8 @@ export class BaseEntity {
                             }
                         }
                     }
-                    // IS-A: commit transaction after successful chain delete
-                    if (isISAInitiator && this.ProviderTransaction) {
-                        await this.ProviderToUse.CommitISATransaction?.(this.ProviderTransaction);
-                        this.ProviderTransaction = null;
-                    }
+                    // Commit the scope this entity opened, if any (only the initiator holds one).
+                    await this.commitEntityTransactionScope();
                     if (!this.TransactionGroup) {
                         // NOT part of a transaction - raise event immediately
                         // record deleted correctly
@@ -2919,14 +3621,21 @@ export class BaseEntity {
                     }
                     return true;
                 }
-                else // record didn't delete, return false, but also don't wipe out the entity like we do if the Delete() worked
+                else {
+                    // Record didn't delete. This path is ordinary, not exotic: the provider reports
+                    // essentially every delete failure — RLS denial, FK violation, zero rows
+                    // affected — by RETURNING false rather than throwing. The scope opened above
+                    // must be settled here or the provider's ambient transaction leaks open and
+                    // 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();
                     return false;
+                }
             }
         }
         catch (e) {
-            // IS-A: rollback transaction on failure (only the initiator rolls back)
-            const isISAInitiator = this._parentEntity != null && !options?.IsParentEntityDelete;
-            await this.RollbackISATransaction(isISAInitiator);
+            // 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