@memberjunction/core 5.51.0 → 6.1.0-edge.1

package/dist/generic/entitySavePlan.d.ts

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview `EntitySavePlan` — the ordered unit of work produced by an entity and its
+ * companions, and the local executor that runs it inside a single provider transaction.
+ *
+ * ## Why a plan rather than direct recursion
+ *
+ * Making the work explicit before executing any of it buys three things that matter:
+ *
+ * 1. **Validation can see the whole graph.** Cross-child invariants ("debits must equal credits")
+ *    have to be checked against the complete set — including pending removals — *before* the first
+ *    row is written. A plan is the natural place to assert that.
+ * 2. **One transaction decision.** The plan is built, then executed. The executor opens exactly one
+ *    scope for the whole graph instead of each level guessing whether it should start one.
+ * 3. **The remote path becomes trivial.** A plan is data. The client serializes the graph, the
+ *    server rebuilds it and runs the *same* executor. There is one cascade implementation, placed
+ *    in one of two locations — never two implementations to keep in sync.
+ *
+ * ## Platform guarantees are preserved by construction
+ *
+ * Every node is persisted by calling that record's own `BaseEntity.Save()` / `.Delete()`. Nothing
+ * is written with direct SQL. Record Changes, entity actions, field validation, subclass `Save`
+ * overrides, `PreSave` data hooks, `save_started` / `save` / `delete` events and cache invalidation
+ * therefore all fire per node exactly as they do for a standalone save — with no graph-specific
+ * plumbing and no risk of the graph path quietly skipping a guarantee the single-record path has.
+ *
+ * @module @memberjunction/core
+ */
+import type { BaseEntity } from './baseEntity.js';
+import type { EntitySaveOptions, EntityDeleteOptions } from './interfaces.js';
+/**
+ * What a plan node does to its record.
+ */
+export type EntitySavePlanOperation = 'Save' | 'Delete';
+/**
+ * A single unit of work within an {@link EntitySavePlan}.
+ */
+export type EntitySavePlanNode = {
+    /** The record to operate on. */
+    Entity: BaseEntity;
+    /** Whether this node saves or deletes its record. */
+    Operation: EntitySavePlanOperation;
+    /**
+     * Human-readable origin of this node, used in error messages so a failure names the collection
+     * it came from rather than just an entity name (e.g. `Lines[3]`).
+     */
+    Label: string;
+    /**
+     * Applied to the record immediately before the node executes.
+     *
+     * This is how a child collection stamps the parent's freshly-assigned primary key onto each
+     * child's foreign key: the parent node runs first, so by the time this callback fires the key
+     * exists. Deferring it to execution time — rather than setting it when the plan is built — is
+     * what makes creating a parent and its children in one call work.
+     */
+    Prepare?: () => void;
+    /**
+     * When true, this node executes the record's **own** save/delete only, without letting that
+     * record build and run a graph of its own.
+     *
+     * Set on the root node — the record whose `Save()` produced this plan. Without it the root
+     * would re-enter graph planning from inside its own graph execution, recursing forever, and
+     * would deadlock on its own in-flight save debounce.
+     *
+     * Deliberately **not** set on child nodes: a child that declares companions of its own must
+     * build and run its own sub-graph, which is what makes nesting (payment → line → allocation)
+     * work.
+     */
+    SelfOnly?: boolean;
+};
+/**
+ * The outcome of executing one plan node.
+ */
+export type EntitySavePlanNodeResult = {
+    /** The node that ran. */
+    Node: EntitySavePlanNode;
+    /** Whether the record's own Save()/Delete() reported success. */
+    Success: boolean;
+    /** The failure detail, when `Success` is false. */
+    ErrorMessage?: string;
+};
+/**
+ * The outcome of executing a whole plan.
+ */
+export type EntitySavePlanResult = {
+    /** True only when every node succeeded and the transaction committed. */
+    Success: boolean;
+    /** Per-node outcomes, in execution order. */
+    NodeResults: EntitySavePlanNodeResult[];
+    /** The first failure's message, hoisted for convenience. */
+    ErrorMessage?: string;
+};
+/**
+ * An ordered set of record operations that must succeed or fail together.
+ *
+ * Built by `BaseEntity.BuildSavePlan()` / `BuildDeletePlan()`, which seed the root node and then let
+ * each companion contribute via `EntityCompanion.ContributeSaveWork()` /
+ * `ContributeDeleteWork()`.
+ *
+ * @remarks
+ * Ordering is explicit and positional — nodes execute in the order they were added. Companions that
+ * need their work to run before the parent (deletions of children, for instance) add it before the
+ * parent node exists, which is why `ContributeDeleteWork` is called first on the delete path and
+ * `ContributeSaveWork` last on the save path.
+ */
+export declare class EntitySavePlan {
+    private nodes;
+    /**
+     * The record the plan is rooted at — the entity whose `Save()` / `Delete()` was called.
+     */
+    readonly Root: BaseEntity;
+    /**
+     * @param root - The record this plan is rooted at.
+     */
+    constructor(root: BaseEntity);
+    /**
+     * The nodes in execution order.
+     */
+    get Nodes(): readonly EntitySavePlanNode[];
+    /**
+     * How many operations this plan will perform.
+     *
+     * A count of 1 means the plan is just the root record, and `BaseEntity` takes its ordinary
+     * single-record path — no plan execution, no transaction scope, byte-for-byte the behavior
+     * that existed before companions. This is what keeps the overwhelmingly common case free of
+     * any new cost or risk.
+     */
+    get NodeCount(): number;
+    /**
+     * Appends a node to the plan.
+     *
+     * @param node - The unit of work to append.
+     * @returns This plan, for chaining.
+     */
+    Add(node: EntitySavePlanNode): EntitySavePlan;
+    /**
+     * Convenience wrapper over {@link Add} for a save node.
+     *
+     * @param entity - The record to save.
+     * @param label - Origin label used in error messages.
+     * @param prepare - Optional callback applied immediately before the node executes.
+     * @returns This plan, for chaining.
+     */
+    AddSave(entity: BaseEntity, label: string, prepare?: () => void, selfOnly?: boolean): EntitySavePlan;
+    /**
+     * Convenience wrapper over {@link Add} for a delete node.
+     *
+     * @param entity - The record to delete.
+     * @param label - Origin label used in error messages.
+     * @returns This plan, for chaining.
+     */
+    AddDelete(entity: BaseEntity, label: string): EntitySavePlan;
+}
+/**
+ * Per-node option sets used when executing a plan.
+ *
+ * The root node needs its own variants carrying the `IsGraphNodeSave` / `IsGraphNodeDelete` flag,
+ * which prevents it from re-entering graph planning and bypasses its in-flight save debounce.
+ * `BaseEntity` constructs all four, because it already holds the option classes as values —
+ * building them here would force a runtime import of `interfaces.ts` and close an import cycle for
+ * no benefit.
+ */
+export type EntitySavePlanExecuteOptions = {
+    /** Options for non-root save nodes. */
+    SaveOptions?: EntitySaveOptions;
+    /** Options for the root save node — must carry `IsGraphNodeSave: true`. */
+    RootSaveOptions?: EntitySaveOptions;
+    /** Options for non-root delete nodes. */
+    DeleteOptions?: EntityDeleteOptions;
+    /** Options for the root delete node — must carry `IsGraphNodeDelete: true`. */
+    RootDeleteOptions?: EntityDeleteOptions;
+    /**
+     * Keys of the records already being persisted higher up in this unit of work — the cycle guard.
+     *
+     * A child node runs the child's own `Save()`, which builds and executes the child's own plan.
+     * That is what makes nesting work (a payment's line's allocations all land in one transaction),
+     * but on a **self-referential** collection it is also what makes a cycle fatal: declare
+     * `SubAgents` on `MJ: AI Agents` via `ParentID`, then wire `a.SubAgents.Add(b)` and
+     * `b.SubAgents.Add(a)`, and the recursion only ends when the call stack does.
+     *
+     * The set is threaded through the options rather than held in a module-scoped variable
+     * deliberately. A process-global would be shared by every concurrent save in the process, so
+     * two unrelated requests saving the *same* record at the same time would report a cycle that
+     * does not exist. Carried on the options, its lifetime is exactly one unit of work.
+     */
+    Visited?: Set<string>;
+};
+/**
+ * Executes a plan's nodes in order, stopping at the first failure.
+ *
+ * This function does **not** manage the transaction — the caller owns that, because the caller is
+ * the only one that knows whether the graph is the outermost unit of work or nested inside a larger
+ * one. See `BaseEntity.executeGraphLocal`.
+ *
+ * @param plan - The plan to execute.
+ * @param options - Per-node option sets.
+ * @returns The per-node outcomes and an overall success flag.
+ */
+export declare function ExecuteEntitySavePlan(plan: EntitySavePlan, options?: EntitySavePlanExecuteOptions): Promise<EntitySavePlanResult>;
+//# sourceMappingURL=entitySavePlan.d.ts.map

package/dist/generic/entitySavePlan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitySavePlan.d.ts","sourceRoot":"","sources":["../../src/generic/entitySavePlan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAG3E;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAExD;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,gCAAgC;IAChC,MAAM,EAAE,UAAU,CAAC;IACnB,qDAAqD;IACrD,SAAS,EAAE,uBAAuB,CAAC;IACnC;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACnC,yBAAyB;IACzB,IAAI,EAAE,kBAAkB,CAAC;IACzB,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC;IACjB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAC/B,yEAAyE;IACzE,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,WAAW,EAAE,wBAAwB,EAAE,CAAC;IACxC,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,KAAK,CAA4B;IAEzC;;OAEG;IACH,SAAgB,IAAI,EAAE,UAAU,CAAC;IAEjC;;OAEG;gBACS,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,IAAW,KAAK,IAAI,SAAS,kBAAkB,EAAE,CAEhD;IAED;;;;;;;OAOG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IAED;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,kBAAkB,GAAG,cAAc;IAKpD;;;;;;;OAOG;IACI,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,EAAE,QAAQ,UAAQ,GAAG,cAAc;IAIzG;;;;;;OAMG;IACI,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc;CAGtE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,4BAA4B,GAAG;IACvC,uCAAuC;IACvC,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,2EAA2E;IAC3E,eAAe,CAAC,EAAE,iBAAiB,CAAC;IACpC,yCAAyC;IACzC,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC,+EAA+E;IAC/E,iBAAiB,CAAC,EAAE,mBAAmB,CAAC;IACxC;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACzB,CAAC;AAkBF;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACvC,IAAI,EAAE,cAAc,EACpB,OAAO,GAAE,4BAAiC,GAC3C,OAAO,CAAC,oBAAoB,CAAC,CAsD/B"}

package/dist/generic/entitySavePlan.js

@@ -0,0 +1,213 @@
+/**
+ * @fileoverview `EntitySavePlan` — the ordered unit of work produced by an entity and its
+ * companions, and the local executor that runs it inside a single provider transaction.
+ *
+ * ## Why a plan rather than direct recursion
+ *
+ * Making the work explicit before executing any of it buys three things that matter:
+ *
+ * 1. **Validation can see the whole graph.** Cross-child invariants ("debits must equal credits")
+ *    have to be checked against the complete set — including pending removals — *before* the first
+ *    row is written. A plan is the natural place to assert that.
+ * 2. **One transaction decision.** The plan is built, then executed. The executor opens exactly one
+ *    scope for the whole graph instead of each level guessing whether it should start one.
+ * 3. **The remote path becomes trivial.** A plan is data. The client serializes the graph, the
+ *    server rebuilds it and runs the *same* executor. There is one cascade implementation, placed
+ *    in one of two locations — never two implementations to keep in sync.
+ *
+ * ## Platform guarantees are preserved by construction
+ *
+ * Every node is persisted by calling that record's own `BaseEntity.Save()` / `.Delete()`. Nothing
+ * is written with direct SQL. Record Changes, entity actions, field validation, subclass `Save`
+ * overrides, `PreSave` data hooks, `save_started` / `save` / `delete` events and cache invalidation
+ * therefore all fire per node exactly as they do for a standalone save — with no graph-specific
+ * plumbing and no risk of the graph path quietly skipping a guarantee the single-record path has.
+ *
+ * @module @memberjunction/core
+ */
+import { LogError } from './logging.js';
+/**
+ * An ordered set of record operations that must succeed or fail together.
+ *
+ * Built by `BaseEntity.BuildSavePlan()` / `BuildDeletePlan()`, which seed the root node and then let
+ * each companion contribute via `EntityCompanion.ContributeSaveWork()` /
+ * `ContributeDeleteWork()`.
+ *
+ * @remarks
+ * Ordering is explicit and positional — nodes execute in the order they were added. Companions that
+ * need their work to run before the parent (deletions of children, for instance) add it before the
+ * parent node exists, which is why `ContributeDeleteWork` is called first on the delete path and
+ * `ContributeSaveWork` last on the save path.
+ */
+export class EntitySavePlan {
+    /**
+     * @param root - The record this plan is rooted at.
+     */
+    constructor(root) {
+        this.nodes = [];
+        this.Root = root;
+    }
+    /**
+     * The nodes in execution order.
+     */
+    get Nodes() {
+        return this.nodes;
+    }
+    /**
+     * How many operations this plan will perform.
+     *
+     * A count of 1 means the plan is just the root record, and `BaseEntity` takes its ordinary
+     * single-record path — no plan execution, no transaction scope, byte-for-byte the behavior
+     * that existed before companions. This is what keeps the overwhelmingly common case free of
+     * any new cost or risk.
+     */
+    get NodeCount() {
+        return this.nodes.length;
+    }
+    /**
+     * Appends a node to the plan.
+     *
+     * @param node - The unit of work to append.
+     * @returns This plan, for chaining.
+     */
+    Add(node) {
+        this.nodes.push(node);
+        return this;
+    }
+    /**
+     * Convenience wrapper over {@link Add} for a save node.
+     *
+     * @param entity - The record to save.
+     * @param label - Origin label used in error messages.
+     * @param prepare - Optional callback applied immediately before the node executes.
+     * @returns This plan, for chaining.
+     */
+    AddSave(entity, label, prepare, selfOnly = false) {
+        return this.Add({ Entity: entity, Operation: 'Save', Label: label, Prepare: prepare, SelfOnly: selfOnly });
+    }
+    /**
+     * Convenience wrapper over {@link Add} for a delete node.
+     *
+     * @param entity - The record to delete.
+     * @param label - Origin label used in error messages.
+     * @returns This plan, for chaining.
+     */
+    AddDelete(entity, label) {
+        return this.Add({ Entity: entity, Operation: 'Delete', Label: label });
+    }
+}
+/**
+ * Stable identity for cycle detection: the entity plus its primary key.
+ *
+ * Object identity is not enough — the same row can be represented by two different `BaseEntity`
+ * instances within one graph, which is precisely the shape a cycle takes after a round trip.
+ *
+ * @param entity - The record to key.
+ * @returns The key, or `null` for a record with no primary-key value yet (a brand-new record cannot
+ *          be its own ancestor, so it needs no guard).
+ */
+function GraphNodeKey(entity) {
+    const entityName = entity.EntityInfo?.Name;
+    const key = entity.PrimaryKey?.ToString();
+    return entityName && key ? `${entityName}|${key}` : null;
+}
+/**
+ * Executes a plan's nodes in order, stopping at the first failure.
+ *
+ * This function does **not** manage the transaction — the caller owns that, because the caller is
+ * the only one that knows whether the graph is the outermost unit of work or nested inside a larger
+ * one. See `BaseEntity.executeGraphLocal`.
+ *
+ * @param plan - The plan to execute.
+ * @param options - Per-node option sets.
+ * @returns The per-node outcomes and an overall success flag.
+ */
+export async function ExecuteEntitySavePlan(plan, options = {}) {
+    const nodeResults = [];
+    const visited = options.Visited ?? new Set();
+    // The root is an ancestor of everything this plan will run, so it goes in before the loop.
+    // Its own node is `SelfOnly` and therefore exempt from the check below — it cannot recurse.
+    const rootKey = GraphNodeKey(plan.Root);
+    const rootWasAlreadyVisited = rootKey !== null && visited.has(rootKey);
+    if (rootKey && !rootWasAlreadyVisited) {
+        visited.add(rootKey);
+    }
+    try {
+        for (const node of plan.Nodes) {
+            // A child node re-entering a record already in progress above it is a cycle. Detect it
+            // here rather than letting the recursion run until the stack overflows, which surfaces
+            // as an unattributable crash rather than a fixable message.
+            if (!node.SelfOnly) {
+                const key = GraphNodeKey(node.Entity);
+                if (key && visited.has(key)) {
+                    const message = `Cycle detected in the entity graph at ${node.Label} (${key}): this record is already ` +
+                        `being saved higher up in the same unit of work. A self-referential related-record ` +
+                        `collection cannot contain one of its own ancestors.`;
+                    LogError(message);
+                    return { Success: false, NodeResults: nodeResults, ErrorMessage: message };
+                }
+            }
+            // Late-bind anything that depends on values produced by earlier nodes — most importantly
+            // a child's foreign key, which cannot exist until the parent row has been inserted.
+            if (node.Prepare) {
+                node.Prepare();
+            }
+            const outcome = await executePlanNode(node, { ...options, Visited: visited });
+            nodeResults.push(outcome);
+            if (!outcome.Success) {
+                // Stop immediately. The caller rolls the transaction back, so continuing would only
+                // pile up work that is about to be undone — and would let a later, more confusing
+                // failure mask the real one.
+                return { Success: false, NodeResults: nodeResults, ErrorMessage: outcome.ErrorMessage };
+            }
+        }
+        return { Success: true, NodeResults: nodeResults };
+    }
+    finally {
+        // Leave the set exactly as it was found, so sibling branches of the same graph are not
+        // poisoned by an ancestor this branch happened to add.
+        if (rootKey && !rootWasAlreadyVisited) {
+            visited.delete(rootKey);
+        }
+    }
+}
+/**
+ * Runs a single plan node and normalizes its outcome.
+ *
+ * `BaseEntity.Save()` / `.Delete()` signal logical failure by returning `false` rather than
+ * throwing, so both shapes have to be handled: a `false` return and a genuine exception.
+ *
+ * @param node - The node to run.
+ * @param saveOptions - Options for a save node.
+ * @param deleteOptions - Options for a delete node.
+ * @returns The node outcome.
+ */
+async function executePlanNode(node, options) {
+    try {
+        // The root node runs "self only": it must not re-enter graph planning from inside the graph
+        // it is already executing, and it must bypass its own in-flight save debounce. Child nodes
+        // get the ordinary options, so a child with companions of its own runs its own sub-graph.
+        const ok = node.Operation === 'Save'
+            ? await node.Entity.Save(node.SelfOnly ? options.RootSaveOptions : options.SaveOptions)
+            : await node.Entity.Delete(node.SelfOnly ? options.RootDeleteOptions : options.DeleteOptions);
+        if (ok) {
+            return { Node: node, Success: true };
+        }
+        const detail = node.Entity.LatestResult?.CompleteMessage ?? 'unknown error';
+        return {
+            Node: node,
+            Success: false,
+            ErrorMessage: `${node.Operation} failed for ${node.Label} (${node.Entity.EntityInfo?.Name}): ${detail}`,
+        };
+    }
+    catch (e) {
+        const detail = e instanceof Error ? e.message : String(e);
+        LogError(`EntitySavePlan node threw for ${node.Label}: ${detail}`);
+        return {
+            Node: node,
+            Success: false,
+            ErrorMessage: `${node.Operation} threw for ${node.Label} (${node.Entity.EntityInfo?.Name}): ${detail}`,
+        };
+    }
+}
+//# sourceMappingURL=entitySavePlan.js.map

package/dist/generic/entitySavePlan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entitySavePlan.js","sourceRoot":"","sources":["../../src/generic/entitySavePlan.ts"],"names":[],"mappings":"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"}

package/dist/generic/entityTransactionScope.d.ts

@@ -0,0 +1,125 @@
+/**
+ * @fileoverview Provider-arbitrated transaction scopes for multi-record entity operations.
+ *
+ * ## Why this exists
+ *
+ * Before this abstraction MemberJunction had **two mutually-blind transaction mechanisms**:
+ *
+ * 1. `DatabaseProviderBase.BeginTransaction()` / `CommitTransaction()` / `RollbackTransaction()` —
+ *    a properly re-entrant ambient manager (depth counter, `SAVE TRANSACTION` savepoints at depth
+ *    ≥ 2, serialization against an in-flight outermost begin). Application composite-save code
+ *    (order headers + lines, journal entries + lines, payments + allocations) calls this directly.
+ * 2. `BeginISATransaction()` / `CommitISATransaction()` / `RollbackISATransaction()` — an
+ *    IS-A-specific trio that opened a brand-new physical transaction on the pool with **no depth
+ *    awareness at all**.
+ *
+ * Because neither knew about the other, an entity that hit both paths — an IS-A entity saved
+ * inside an application transaction, or a composite whose child is an IS-A leaf — wrote into *two
+ * independent physical transactions on the same connection pool*. Rolling one back left the other
+ * committed. A torn write, with no error raised.
+ *
+ * ## The fix: one arbiter, zero coupling between participants
+ *
+ * Every participant now asks for the same thing and never asks who else is in a transaction:
+ *
+ * ```typescript
+ * const scope = await provider.BeginEntityTransaction();
+ * try {
+ *     // ...work...
+ *     await scope.Commit();
+ * } catch (e) {
+ *     await scope.Rollback();
+ *     throw e;
+ * }
+ * ```
+ *
+ * The **provider** decides whether that is a physical `BEGIN` or a join to a transaction already in
+ * flight. This deliberately *reduces* coupling: IS-A orchestration, composite graph saves and
+ * hand-written application code each remain ignorant of one another, and correctness no longer
+ * depends on that ignorance being harmless.
+ *
+ * ## Tier behaviour
+ *
+ * - **Server** (`DatabaseProviderBase` and subclasses): `SupportsEntityTransactions === true`;
+ *   scopes map onto the depth-counted ambient transaction.
+ * - **Client** (`GraphQLDataProvider`): `SupportsEntityTransactions === false`; there is no local
+ *   transaction to join. Callers that need atomicity across several records route the whole unit of
+ *   work to the server instead — see `MJ.SaveEntityGraph` and
+ *   `guides/TRANSACTIONS_AND_BATCHING_GUIDE.md`.
+ *
+ * ## Concurrency
+ *
+ * The underlying ambient transaction is a field on the **provider instance**, not a global. MJServer
+ * builds per-request providers (`createPerRequestProviders` in `packages/MJServer/src/context.ts`),
+ * so an ambient transaction is effectively request-scoped and concurrent requests cannot interleave
+ * within one. Long-lived single-provider processes (CLI tools, workers) should not run concurrent
+ * transactional work on one provider instance — that constraint predates this abstraction and is
+ * unchanged by it.
+ *
+ * @module @memberjunction/core
+ */
+/**
+ * A handle to a unit of work that will either commit or roll back as a whole.
+ *
+ * Obtained from {@link IMetadataProvider.BeginEntityTransaction}. The scope is **settle-once**:
+ * the first call to {@link EntityTransactionScope.Commit} or
+ * {@link EntityTransactionScope.Rollback} settles it and every later call is a no-op. That makes
+ * the standard `try { work; Commit() } catch { Rollback() }` shape safe even when the work itself
+ * already rolled back on the way out.
+ *
+ * @remarks
+ * A scope does **not** necessarily correspond to a physical database transaction. When one is
+ * already in flight on the provider, the scope joins it — committing the inner scope releases a
+ * savepoint rather than committing the outer transaction. Inspect {@link IsNested} to tell the two
+ * apart; correctness never requires you to.
+ */
+export interface EntityTransactionScope {
+    /**
+     * True when this scope joined a transaction that was already in flight on the provider, rather
+     * than starting a new physical one.
+     *
+     * Informational only — for logging and diagnostics. Commit/rollback behave correctly either
+     * way, and callers must not branch on this to decide whether to settle the scope.
+     */
+    readonly IsNested: boolean;
+    /**
+     * Settles the scope successfully. On the outermost scope this commits the physical transaction;
+     * on a nested scope it releases the savepoint. No-op if the scope is already settled.
+     */
+    Commit(): Promise<void>;
+    /**
+     * Settles the scope by undoing its work. On the outermost scope this rolls the physical
+     * transaction back; on a nested scope it rolls back to the savepoint. No-op if the scope is
+     * already settled.
+     */
+    Rollback(): Promise<void>;
+}
+/**
+ * Runs `work` inside a provider-arbitrated transaction scope, committing on success and rolling
+ * back on any thrown error.
+ *
+ * This is the preferred entry point — it makes the settle-once contract impossible to get wrong and
+ * keeps the `try`/`catch` boilerplate in one place.
+ *
+ * @example
+ * ```typescript
+ * const total = await RunInEntityTransaction(this.ProviderToUse, async () => {
+ *     await header.Save();
+ *     for (const line of lines) await line.Save();
+ *     return lines.length;
+ * });
+ * ```
+ *
+ * @param provider - The provider to obtain the scope from. When it does not support entity
+ *                   transactions the work still runs, just without transactional guarantees —
+ *                   callers needing atomicity must check `SupportsEntityTransactions` first and
+ *                   route the unit of work to the server instead.
+ * @param work - The work to perform inside the scope.
+ * @returns Whatever `work` returns.
+ * @throws Re-throws whatever `work` throws, after rolling the scope back.
+ */
+export declare function RunInEntityTransaction<T>(provider: {
+    SupportsEntityTransactions?: boolean;
+    BeginEntityTransaction?(): Promise<EntityTransactionScope>;
+} | null | undefined, work: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=entityTransactionScope.d.ts.map

package/dist/generic/entityTransactionScope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityTransactionScope.d.ts","sourceRoot":"","sources":["../../src/generic/entityTransactionScope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,sBAAsB;IACnC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B;;;OAGG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;;;OAIG;IACH,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAC1C,QAAQ,EAAE;IACN,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,sBAAsB,CAAC,IAAI,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC9D,GAAG,IAAI,GAAG,SAAS,EACpB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CA6BZ"}

package/dist/generic/entityTransactionScope.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Provider-arbitrated transaction scopes for multi-record entity operations.
+ *
+ * ## Why this exists
+ *
+ * Before this abstraction MemberJunction had **two mutually-blind transaction mechanisms**:
+ *
+ * 1. `DatabaseProviderBase.BeginTransaction()` / `CommitTransaction()` / `RollbackTransaction()` —
+ *    a properly re-entrant ambient manager (depth counter, `SAVE TRANSACTION` savepoints at depth
+ *    ≥ 2, serialization against an in-flight outermost begin). Application composite-save code
+ *    (order headers + lines, journal entries + lines, payments + allocations) calls this directly.
+ * 2. `BeginISATransaction()` / `CommitISATransaction()` / `RollbackISATransaction()` — an
+ *    IS-A-specific trio that opened a brand-new physical transaction on the pool with **no depth
+ *    awareness at all**.
+ *
+ * Because neither knew about the other, an entity that hit both paths — an IS-A entity saved
+ * inside an application transaction, or a composite whose child is an IS-A leaf — wrote into *two
+ * independent physical transactions on the same connection pool*. Rolling one back left the other
+ * committed. A torn write, with no error raised.
+ *
+ * ## The fix: one arbiter, zero coupling between participants
+ *
+ * Every participant now asks for the same thing and never asks who else is in a transaction:
+ *
+ * ```typescript
+ * const scope = await provider.BeginEntityTransaction();
+ * try {
+ *     // ...work...
+ *     await scope.Commit();
+ * } catch (e) {
+ *     await scope.Rollback();
+ *     throw e;
+ * }
+ * ```
+ *
+ * The **provider** decides whether that is a physical `BEGIN` or a join to a transaction already in
+ * flight. This deliberately *reduces* coupling: IS-A orchestration, composite graph saves and
+ * hand-written application code each remain ignorant of one another, and correctness no longer
+ * depends on that ignorance being harmless.
+ *
+ * ## Tier behaviour
+ *
+ * - **Server** (`DatabaseProviderBase` and subclasses): `SupportsEntityTransactions === true`;
+ *   scopes map onto the depth-counted ambient transaction.
+ * - **Client** (`GraphQLDataProvider`): `SupportsEntityTransactions === false`; there is no local
+ *   transaction to join. Callers that need atomicity across several records route the whole unit of
+ *   work to the server instead — see `MJ.SaveEntityGraph` and
+ *   `guides/TRANSACTIONS_AND_BATCHING_GUIDE.md`.
+ *
+ * ## Concurrency
+ *
+ * The underlying ambient transaction is a field on the **provider instance**, not a global. MJServer
+ * builds per-request providers (`createPerRequestProviders` in `packages/MJServer/src/context.ts`),
+ * so an ambient transaction is effectively request-scoped and concurrent requests cannot interleave
+ * within one. Long-lived single-provider processes (CLI tools, workers) should not run concurrent
+ * transactional work on one provider instance — that constraint predates this abstraction and is
+ * unchanged by it.
+ *
+ * @module @memberjunction/core
+ */
+import { LogError } from './logging.js';
+/**
+ * Runs `work` inside a provider-arbitrated transaction scope, committing on success and rolling
+ * back on any thrown error.
+ *
+ * This is the preferred entry point — it makes the settle-once contract impossible to get wrong and
+ * keeps the `try`/`catch` boilerplate in one place.
+ *
+ * @example
+ * ```typescript
+ * const total = await RunInEntityTransaction(this.ProviderToUse, async () => {
+ *     await header.Save();
+ *     for (const line of lines) await line.Save();
+ *     return lines.length;
+ * });
+ * ```
+ *
+ * @param provider - The provider to obtain the scope from. When it does not support entity
+ *                   transactions the work still runs, just without transactional guarantees —
+ *                   callers needing atomicity must check `SupportsEntityTransactions` first and
+ *                   route the unit of work to the server instead.
+ * @param work - The work to perform inside the scope.
+ * @returns Whatever `work` returns.
+ * @throws Re-throws whatever `work` throws, after rolling the scope back.
+ */
+export async function RunInEntityTransaction(provider, work) {
+    const canTransact = provider?.SupportsEntityTransactions === true && !!provider.BeginEntityTransaction;
+    if (!canTransact) {
+        // No local transaction available (client provider, or a provider that does not implement
+        // the capability). Run the work as-is — the caller is responsible for having decided that
+        // non-atomic execution is acceptable here, or for routing elsewhere.
+        return work();
+    }
+    const scope = await provider.BeginEntityTransaction();
+    try {
+        const result = await work();
+        await scope.Commit();
+        return result;
+    }
+    catch (e) {
+        // Rollback failures are logged and swallowed so the CALLER'S error survives: this is the
+        // failure path, and a doomed transaction (savepoint rollback refused, connection gone)
+        // throwing here would replace the error that explains what actually went wrong with a
+        // secondary one that explains less. Mirrors BaseEntity's own scope helper.
+        try {
+            await scope.Rollback();
+        }
+        catch (rollbackError) {
+            LogError(`RunInEntityTransaction: rollback failed after the work threw — reporting the original error. ` +
+                `Rollback failure: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+        }
+        throw e;
+    }
+}
+//# sourceMappingURL=entityTransactionScope.js.map