@opensaas/stack-core 0.37.0 → 0.39.0

package/src/context/transaction-boundary.ts

@@ -9,53 +9,36 @@ import {
   type TransactionOutcome,
 } from '../hooks/index.js'
 import type { WriteOperation } from './write-pipeline.js'
+import type {
+  TransactionRegistry,
+  TransactionSettleOutcome,
+} from '../access/transaction-registry.js'
 
 /**
- * Transaction-boundary hooks (#590 / ADR-0010).
- *
- * `beforeTransaction`/`afterTransaction` run OUTSIDE the write's `$transaction`
- * — `beforeTransaction` before it opens, `afterTransaction` after it settles —
- * for non-transactional side effects (e.g. external API calls) that must not
- * hold a DB transaction open and cannot be rolled back. The pair forms a
- * compensation bracket around the atomic write described by ADR-0010.
- *
- * This module:
- *  1. Enumerates the lists involved in a write up front, BY WALKING THE INPUT
- *     TREE only (no DB reads), so the bracket can run per involved list before
- *     the transaction opens (mirroring how in-transaction before/afterOperation
- *     fire per record, but at list granularity).
- *  2. Runs all `beforeTransaction` hooks, tracking exactly which involved lists'
- *     `beforeTransaction` ran, then — after the caller settles the transaction —
- *     runs `afterTransaction` ONLY for those lists (the symmetric-bracket
- *     "always-run" rule), surfacing any hook errors afterward.
+ * Transaction-boundary hooks (#590 / ADR-0010): `beforeTransaction`/`afterTransaction`
+ * bracket a write's `$transaction` from the outside, for non-transactional side
+ * effects. See ADR-0010 for the bracket's design and ADR-0028 for how a joined
+ * write's `afterTransaction` defers to the transaction owner.
  */
 
 /**
- * One list involved in a write, with the data the transaction-boundary hooks
- * receive. Enumerated purely from the input tree (no DB reads).
- *
- * The persisted/pre-write rows (`item`/`originalItem`) are surfaced to
- * `afterTransaction` ONLY for the TOP-LEVEL record (`isTopLevel`). For nested
- * lists the per-record persisted row is not reliably recoverable outside the
- * transaction, so they are passed as `undefined` rather than mis-handing the
- * top-level row as if it were the nested row. `originalItem` here is therefore
- * populated only for the top-level update/delete target (the pipeline resolves
- * it before the transaction opens).
+ * One list involved in a write, enumerated purely from the input tree (no DB
+ * reads). `item`/`originalItem` are populated only for the top-level record
+ * (`isTopLevel`) — a nested list's persisted row isn't reliably recoverable
+ * outside the transaction, so handing it the top-level row instead would be
+ * silently wrong.
  */
 export interface InvolvedList {
   listKey: string
   // eslint-disable-next-line @typescript-eslint/no-explicit-any -- ListConfig must accept any TypeInfo
   listConfig: ListConfig<any>
   operation: WriteOperation
-  /** Whether this is the top-level write target (the only list with a reliable persisted row). */
   isTopLevel: boolean
-  /** The input payload for this involvement (create/update); `undefined` for delete. */
+  /** `undefined` for delete, which has no input payload. */
   inputData: Record<string, unknown> | undefined
-  /** The existing row for the TOP-LEVEL update/delete target; `undefined` otherwise. */
   originalItem: Record<string, unknown> | undefined
 }
 
-/** Nested-op kinds whose payloads imply an involved list + operation. */
 const NESTED_OP_OPERATIONS: ReadonlyArray<{ kind: string; operation: WriteOperation }> = [
   { kind: 'create', operation: 'create' },
   { kind: 'update', operation: 'update' },
@@ -64,7 +47,6 @@ const NESTED_OP_OPERATIONS: ReadonlyArray<{ kind: string; operation: WriteOperat
   { kind: 'connectOrCreate', operation: 'create' },
 ]
 
-/** Distinct dedupe-key operations `NESTED_OP_OPERATIONS` can produce (create/update/delete). */
 const DISTINCT_OPERATION_COUNT = new Set(NESTED_OP_OPERATIONS.map((o) => o.operation)).size
 
 function isRelationshipField(fieldConfig: FieldConfig | undefined): boolean {
@@ -72,17 +54,12 @@ function isRelationshipField(fieldConfig: FieldConfig | undefined): boolean {
 }
 
 /**
- * The number of distinct (listKey, operation) involvement pairs the walk
- * could ever record starting from `startListName` — computed from the
- * CONFIG's relationship graph (not the payload), so it bounds the walk by
- * what the schema can reach rather than by an arbitrary depth.
- *
- * Used as the saturation bound: once `walkNested` has recorded this many
- * pairs, no further pair can be new, so it stops descending. This replaces
- * the old depth cap as the cost bound (#835) — a payload nesting the config's
- * lists more deeply than any previous cap no longer loses their
- * transaction-boundary hooks, while a payload that repeats the same few
- * lists still terminates promptly instead of walking every entry.
+ * Distinct (listKey, operation) pairs reachable from `startListName` via the
+ * CONFIG's relationship graph (not the payload) — the saturation bound
+ * `walkNested` stops at once it has recorded this many. Bounding by reachable
+ * pairs rather than a depth cap (#835) avoids losing hooks for payloads
+ * nested deeper than any fixed cap, while still terminating promptly on
+ * payloads that repeat the same few lists.
  */
 function countReachableInvolvementPairs(
   startListName: string,
@@ -114,15 +91,7 @@ function asRecordArray(value: unknown): Array<Record<string, unknown>> {
   return []
 }
 
-/**
- * Extract the create/update payload from a nested-op entry so nested
- * `beforeTransaction` receives meaningful `inputData`.
- *
- *  - `create`: the entry itself is the create data.
- *  - `update`: the entry's `data`.
- *  - `connectOrCreate`: the entry's `create`.
- *  - `delete`: no input payload.
- */
+/** Extract a nested-op entry's create/update payload so its `beforeTransaction` receives meaningful `inputData`. */
 function nestedInputData(
   kind: string,
   entry: Record<string, unknown>,
@@ -142,10 +111,10 @@ function nestedInputData(
 
 /**
  * Recursively walk a write payload's relationship fields, appending one
- * {@link InvolvedList} per nested create/update/delete involvement. De-dups by
- * (listKey, operation) so a list with many nested records of the same operation
- * fires its transaction-boundary bracket once (these hooks are a per-LIST
- * compensation bracket, not per-record).
+ * {@link InvolvedList} per nested create/update/delete involvement. De-dups
+ * by (listKey, operation): these hooks are a per-LIST compensation bracket,
+ * not per-record, so a list with many nested records of the same operation
+ * fires its bracket once.
  */
 function walkNested(
   data: Record<string, unknown> | undefined,
@@ -155,8 +124,7 @@ function walkNested(
   seen: Set<string>,
   maxPairs: number,
 ): void {
-  // Every reachable pair is already recorded — no further recursion can add
-  // anything new, so stop instead of re-walking the rest of the payload.
+  // Saturated: no further pair can be new (see countReachableInvolvementPairs).
   if (!data || seen.size >= maxPairs) return
 
   for (const [fieldName, value] of Object.entries(data)) {
@@ -174,7 +142,6 @@ function walkNested(
       if (opValue === undefined) continue
 
       const entries = asRecordArray(opValue)
-      // Record the involvement once per (list, operation).
       const dedupeKey = `${relatedListName}:${operation}`
       if (!seen.has(dedupeKey)) {
         seen.add(dedupeKey)
@@ -190,7 +157,6 @@ function walkNested(
 
       if (seen.size >= maxPairs) return
 
-      // Recurse into each nested entry's own relationship payload.
       for (const entry of entries) {
         const childData = nestedInputData(kind, entry)
         walkNested(childData, relatedListConfig.fields, config, out, seen, maxPairs)
@@ -201,8 +167,8 @@ function walkNested(
 
 /**
  * Enumerate the lists involved in a write — the top-level list plus every
- * nested create/update/delete target reachable from the input tree — WITHOUT
- * any DB reads. The top-level list is always first.
+ * nested create/update/delete target — without DB reads. The top-level list
+ * is always first.
  */
 export function enumerateInvolvedLists(args: {
   listName: string
@@ -229,16 +195,12 @@ export function enumerateInvolvedLists(args: {
   const seen = new Set<string>([`${listName}:${operation}`])
   const maxPairs = countReachableInvolvementPairs(listName, listConfig, config)
 
-  // Delete has no nested payload to walk (inputData is undefined).
   walkNested(inputData, listConfig.fields, config, out, seen, maxPairs)
 
   return out
 }
 
-/**
- * Run the list- and field-level `beforeTransaction` hooks for one involved list.
- * A throw propagates to the caller (which aborts the write).
- */
+/** Runs one involved list's `beforeTransaction` hooks. A throw propagates to the caller (which aborts the write). */
 async function runBeforeTransactionForList<TPrisma extends PrismaClientLike>(
   involved: InvolvedList,
   context: AccessContext<TPrisma>,
@@ -280,11 +242,13 @@ async function runBeforeTransactionForList<TPrisma extends PrismaClientLike>(
 }
 
 /**
- * Run the list- and field-level `afterTransaction` hooks for one involved list
- * with the settled {@link TransactionOutcome}. Collects (does not throw) any
- * errors so the caller can keep running the remaining lists' compensators.
+ * Runs one involved list's `afterTransaction` hooks against the settled
+ * {@link TransactionOutcome}, collecting rather than throwing errors so the
+ * caller can keep running the remaining lists' compensators. Exported for
+ * {@link TransactionRegistry} to reuse when draining a deferred, joined
+ * write's bracket (ADR-0028).
  */
-async function runAfterTransactionForList<TPrisma extends PrismaClientLike>(
+export async function runAfterTransactionForList<TPrisma extends PrismaClientLike>(
   involved: InvolvedList,
   outcome: TransactionOutcome,
   context: AccessContext<TPrisma>,
@@ -292,15 +256,13 @@ async function runAfterTransactionForList<TPrisma extends PrismaClientLike>(
 ): Promise<void> {
   const { listKey, listConfig, operation, isTopLevel, inputData, originalItem } = involved
 
-  // On commit, the persisted row (`outcome.item`) is the TOP-LEVEL row. We only
-  // surface `item`/`originalItem` for the top-level list — handing the top-level
-  // row to a nested list's hook (whose type is the nested list's own item) would
-  // be unsound, since the hook would silently read the wrong record. For nested
-  // lists we pass `undefined`; per-record nested compensation must use the
-  // in-transaction `afterOperation`, which already receives the correct nested row.
+  // The persisted row (`outcome.item`) is the TOP-LEVEL row only. Handing it to
+  // a nested list's hook would silently mis-type as that list's own item — for
+  // nested lists `item`/`originalItem` stay `undefined`; per-record nested
+  // compensation belongs in the in-transaction `afterOperation`, which gets the
+  // correct row.
   try {
     if (outcome.status === 'committed') {
-      // The persisted row is surfaced only for the top-level list (see above).
       const committedItem = isTopLevel ? outcome.item : undefined
       if (operation === 'create') {
         await executeAfterTransaction(listConfig.hooks, {
@@ -331,7 +293,6 @@ async function runAfterTransactionForList<TPrisma extends PrismaClientLike>(
         })
       }
     } else {
-      // rolled-back: no persisted item.
       if (operation === 'create') {
         await executeAfterTransaction(listConfig.hooks, {
           listKey,
@@ -401,34 +362,47 @@ export class AfterTransactionError extends Error {
 }
 
 /**
- * Bracket a write's transaction with the transaction-boundary hooks (#590).
- *
- * Sequence:
- *  1. Run every involved list's `beforeTransaction` in order, tracking which
- *     ran. A throw aborts: the transaction is NEVER opened; `afterTransaction`
- *     fires (status `rolled-back`, with the throw as `error`) ONLY for the lists
- *     whose `beforeTransaction` already ran (symmetric bracket), and the throw
- *     is then re-surfaced.
- *  2. Otherwise open the transaction via `runTransaction` (the existing #569
- *     machinery). On settle (commit or rollback) run `afterTransaction` for
- *     EVERY involved list (all of their `beforeTransaction` ran) with the
- *     outcome.
- *  3. If any `afterTransaction` throws, the rest still run; the collected
- *     errors are surfaced afterward as an {@link AfterTransactionError}.
+ * Resolves a joined write's final outcome once the owner's settle is known
+ * (ADR-0028): the write's own error always wins; otherwise committed iff the
+ * owner's transaction also committed.
+ */
+function resolveDeferredOutcome(
+  writeOutcome: TransactionOutcome,
+  settle: TransactionSettleOutcome,
+): TransactionOutcome {
+  if (writeOutcome.status === 'rolled-back') return writeOutcome
+  if (settle.status === 'committed') return writeOutcome
+  return { status: 'rolled-back', error: settle.error }
+}
+
+/**
+ * Brackets a write's transaction with the transaction-boundary hooks (#590,
+ * ADR-0028 / #899): runs every involved list's `beforeTransaction` eagerly —
+ * a throw here aborts before `runTransaction` (#569) ever opens the write's
+ * transaction — then routes `afterTransaction` by ownership: deferred onto
+ * `args.joinedOwner`'s {@link TransactionRegistry} for a joined write, run
+ * eagerly (draining `args.ownedRegistry`) for the write that opened the
+ * transaction, or run eagerly with neither set. See ADR-0028 for why. A
+ * joined write's `afterTransaction` errors therefore surface as an
+ * {@link AfterTransactionError} from the OWNER's promise, not this write's.
  *
- * Sudo does not affect these hooks — they always run; sudo only bypasses access.
+ * Sudo bypasses access control only — never these hooks.
  */
 export async function runWithTransactionBoundary<TPrisma extends PrismaClientLike>(args: {
   involvedLists: InvolvedList[]
   context: AccessContext<TPrisma>
+  /** Set when this write is nested in a transaction it did not open (ADR-0028). */
+  joinedOwner?: TransactionRegistry
+  /** Set when this write just opened the transaction joined writes below it share. */
+  ownedRegistry?: TransactionRegistry
   runTransaction: () => Promise<Record<string, unknown> | null>
 }): Promise<Record<string, unknown> | null> {
-  const { involvedLists, context, runTransaction } = args
+  const { involvedLists, context, joinedOwner, ownedRegistry, runTransaction } = args
 
-  // Lists whose beforeTransaction ran (in order), for the symmetric bracket. A
-  // list is marked as "ran" the moment its beforeTransaction BEGINS, so even a
-  // list whose beforeTransaction throws gets its afterTransaction (it may have
-  // taken a partial external action that needs compensating).
+  // A list counts as "ran" the moment its beforeTransaction BEGINS (pushed
+  // before the try below), not on success — so a list whose beforeTransaction
+  // itself throws still gets its afterTransaction, in case it took a partial
+  // external action that needs compensating.
   const ran: InvolvedList[] = []
 
   let beforeError: unknown
@@ -442,18 +416,29 @@ export async function runWithTransactionBoundary<TPrisma extends PrismaClientLik
     }
   }
 
-  // beforeTransaction threw → abort: never open the transaction, compensate the
-  // lists whose beforeTransaction ran, then surface the original error.
+  // Abort path: never open the transaction; compensate the lists that ran,
+  // then rethrow the original error.
   if (beforeError !== undefined) {
     const outcome: TransactionOutcome = { status: 'rolled-back', error: beforeError }
-    const afterErrors: unknown[] = []
-    for (const involved of ran) {
-      await runAfterTransactionForList(involved, outcome, context, afterErrors)
+    if (joinedOwner) {
+      // Discards any afterTransaction errors on this path — only beforeError
+      // propagates, matching the eager branch below.
+      joinedOwner.enqueue(async (_settle, _errors) => {
+        const discarded: unknown[] = []
+        for (const involved of ran) {
+          await runAfterTransactionForList(involved, outcome, context, discarded)
+        }
+      })
+    } else {
+      const afterErrors: unknown[] = []
+      for (const involved of ran) {
+        await runAfterTransactionForList(involved, outcome, context, afterErrors)
+      }
     }
     throw beforeError
   }
 
-  // Open the transaction and capture the settle outcome.
+  // Open (or join) the transaction and capture this write's own settle outcome.
   let outcome: TransactionOutcome
   let result: Record<string, unknown> | null = null
   let txError: unknown
@@ -465,15 +450,34 @@ export async function runWithTransactionBoundary<TPrisma extends PrismaClientLik
     outcome = { status: 'rolled-back', error: err }
   }
 
-  // afterTransaction always runs for every list whose beforeTransaction ran
-  // (here: all involved lists). All compensators run even if one throws.
+  if (joinedOwner) {
+    // Deferred (ADR-0028) — only afterTransaction waits; this write's own
+    // result/throw is returned/thrown normally below.
+    joinedOwner.enqueue(async (settle, errors) => {
+      const finalOutcome = resolveDeferredOutcome(outcome, settle)
+      for (const involved of ran) {
+        await runAfterTransactionForList(involved, finalOutcome, context, errors)
+      }
+    })
+    if (txError !== undefined) throw txError
+    return result
+  }
+
+  // All compensators run even if one throws.
   const afterErrors: unknown[] = []
   for (const involved of ran) {
     await runAfterTransactionForList(involved, outcome, context, afterErrors)
   }
 
-  // Surface errors: the transaction's own error takes precedence (the write
-  // failed); otherwise any afterTransaction errors.
+  // Owner: drain joined writes' deferred brackets with this write's own settle
+  // outcome (ADR-0028).
+  if (ownedRegistry) {
+    const settle: TransactionSettleOutcome =
+      txError !== undefined ? { status: 'rolled-back', error: txError } : { status: 'committed' }
+    await ownedRegistry.drain(settle, afterErrors)
+  }
+
+  // Transaction error takes precedence over afterTransaction errors (ADR-0028).
   if (txError !== undefined) throw txError
   if (afterErrors.length > 0) throw new AfterTransactionError(afterErrors)