Expose outer interactive transaction outcome to afterTransaction hooks

[borisno2]

Problem

A list write executed through the transaction context passed to context.transaction(async (tx) => ...) runs its afterTransaction hook as soon as that individual write pipeline returns. The outer transaction callback can still perform later writes or throw, so an external side effect launched by that hook can escape even though the surrounding interactive transaction ultimately rolls back.

The transaction-scoped Prisma client has no $transaction method, so applications can currently detect this shape and defer dispatch manually until context.transaction() resolves, but that is an undocumented and fragile workaround.

Requested API/behavior

Please either:

• defer nested list afterTransaction hooks until the owning context.transaction() settles, supplying its committed/rolled-back outcome; or
• expose an explicit supported signal that the list write is nested in an outer interactive transaction so applications can safely coordinate after-commit effects.

Context

Found while fixing application issue borisno2/emily-calder-performing-arts#2992. Direct writes can use the existing committed afterTransaction pattern, while trial conversion and rollover currently require explicit post-transaction() dispatch to guarantee rollback safety.

[borisno2]

This was generated by AI during triage.

Agent Brief

Category: bug
Summary: afterTransaction reports the settle of a transaction the write did not open, so an external side effect dispatched on 'committed' can escape a rollback

Design is settled — read docs/adr/0028-a-transaction-boundary-hook-reports-the-outermost-transaction.md before starting. It is the contract for this work; this brief is its acceptance surface. The glossary terms it uses (joined write, transaction owner, unowned join) are in CONTEXT.md.

Current behavior

A write that runs inside a transaction it did not open — a joined write — has its transaction-boundary bracket settled by its own write returning, not by the transaction settling. The bracket records 'committed' and runs afterTransaction immediately, while the enclosing transaction is still open and can still roll back.

Two independent paths produce a joined write, both confirmed by reproduction during triage:

1. Inside context.transaction(). A Prisma transaction client exposes no $transaction, so the Write Pipeline's "join, don't nest" fallback runs the write against the active client. Repro: create inside the callback, then throw. The row is rolled back and afterTransaction has already fired with status: 'committed'.
2. From a hook, with no interactive transaction anywhere. The hook-facing context's db is rebound to the transaction client (ADR-0010), so a hook's own context.db write is also a joined write. Repro: a beforeOperation writing a second list, then a throwing afterOperation — zero rows persisted, and that second list's afterTransaction fired 'committed'.

Existing coverage does not catch either, because the transaction-boundary tests use a mock whose transaction client still exposes $transaction (so nested writes open their own transaction rather than joining), while the interactive-transaction tests use a faithful mock but assert nothing about boundary hooks. Both repros are reproduced with the faithful mock — the one whose transaction client omits $transaction.

Desired behavior

afterTransaction fires when the outermost transaction the write participates in settles, and reports that transaction's outcome.

• A joined write's afterTransaction is deferred until the transaction owner — context.transaction(), or the Write Pipeline when it actually opened the transaction — observes the settle, then flushed with the real outcome.
• Status is a conjunction: 'committed' if and only if the write succeeded and the transaction committed; otherwise 'rolled-back'. The write's own error takes precedence over the transaction's. Nothing fires early — a write that failed on its own is still flushed at settle, because settling it early is only correct on some providers.
• item on a deferred commit is the row as that write persisted it, captured at write time. It is not re-read at flush, and may be stale if a later write in the same transaction touched the record.
• Both halves of the bracket receive a context bound to the base client, never the transaction client. This is already true for top-level writes; it must become true for joined writes. A deferred hook otherwise holds a closed transaction client, and compensation must not be written through a transaction that rolled back.
• beforeTransaction stays eager, running before its write as it does today.
• One bracket per write, flushed in write order (FIFO). Brackets from separate writes never merge — each already ran its own beforeTransaction, so collapsing them would strand compensators. The existing dedupe within one write, by (listKey, operation) across the involved-list walk, is unchanged.
• Error precedence at flush is unchanged: every compensator runs even if one throws; the transaction's own error wins if it rolled back; otherwise the collected hook errors surface as AfterTransactionError. Transaction-error precedence is load-bearing — a serialization failure must reach the caller unwrapped or the documented P2034 retry loop stops retrying.
• An unowned join fires optimistically at write time, exactly as today. When the stack did not open the enclosing transaction there is no owner to flush and no settle signal, so deferring would mean never firing. This covers both an application-managed prisma.$transaction and a plain test double. Do not add a warning: the two are indistinguishable at runtime and a warning would fire on every correct mock-based test.
• A context.transaction() nested inside another joins the outer owner's queue rather than creating a second one.

Key interfaces

• TransactionOutcome — the shape afterTransaction reports. Unchanged in its variants; what changes is when and by whom it is computed.
• The transaction-boundary bracket — currently computes its outcome from its own runTransaction() returning. It needs to distinguish "I opened this transaction" from "I joined one", and in the joined case hand the invocation to the owner instead of running it.
• The deferral registry — internal plumbing, no public surface. Thread it through the same context-rebind path ADR-0010/0012 already use for plugins. It must not appear on the public context type; if it needs a home on the internal access-context shape, keep it @internal.
• context.transaction() — becomes a transaction owner: installs a registry, and after its underlying transaction settles, flushes with the outcome before its promise resolves or rejects.
• The Write Pipeline's transaction runner — becomes a transaction owner in the case where it actually opens a transaction, and a joiner in the case where it does not.
• No change to the public beforeTransaction/afterTransaction argument types.

Acceptance criteria

• A write inside context.transaction() whose callback later throws fires afterTransaction exactly once with status: 'rolled-back' and the callback's error, after the transaction settles
• A write inside context.transaction() whose transaction commits fires afterTransaction with status: 'committed' and the row that write persisted
• A hook-issued context.db write inside a plain top-level write, where the enclosing write later rolls back, fires that list's afterTransaction with status: 'rolled-back' — no interactive transaction involved
• A write that itself throws inside a transaction that later commits reports 'rolled-back' with the write's own error, not the transaction's outcome
• Three writes to the same list in one transaction produce three beforeTransaction and three afterTransaction invocations, flushed in write order
• beforeTransaction still runs before its write, eagerly, in all cases
• Deferred hooks receive a context whose db/prisma target the base client; a compensator issuing a context.db write from a deferred afterTransaction succeeds after the transaction settled, and its write survives a rolled-back transaction
• A P2034 thrown inside a transaction still propagates unwrapped to the caller, with compensators having run — the retry loop in packages/core/CLAUDE.md still works verbatim
• A transaction that commits with a throwing deferred hook rejects with AfterTransactionError, and every other compensator still ran
• A write against a client that cannot open a transaction and has no owner (bare mock) fires afterTransaction at write time with 'committed', and emits no warning — existing mock-based tests keep passing unchanged
• Existing transaction-boundary tests still pass; the ones asserting immediate firing for a joined write are updated to the new contract rather than deleted
• packages/core/CLAUDE.md and the hooks concept doc state the outermost-transaction rule, the stale-item caveat, the "rejection no longer implies rollback" caveat, and the hazard that beforeTransaction inside an interactive transaction runs with that transaction open (keep it fast; don't touch rows the transaction is writing)
• A minor changeset for @opensaas/stack-core (use the pr-changeset skill) covering the three behaviour changes: hooks fire at the outermost settle and can now report 'rolled-back'; transaction() can reject after a successful commit; boundary hooks on joined writes now receive a base-client context
• pnpm lint, pnpm manypkg fix, pnpm format clean

Out of scope

• Any "you are nested in a transaction" flag on the hook arguments. Deferral was chosen precisely so hooks don't need one; adding it as well re-introduces the contract this fixes.
• Re-reading the persisted row at flush time so a committed hook sees final state — rejected in ADR-0028; the captured row is the contract.
• Fixing the unowned-join case. It is a documented limitation, not a bug to solve here.
• Changing the flush direction to LIFO. FIFO matches how the single-write path already compensates; changing it would mean changing that path too.
• Any change to beforeOperation/afterOperation, to access control, or to the ADR-0010 nested-write decomposition.
• A built-in retry helper for serialization failures — still caller-owned, per ADR-0012.

Verification notes

The bug is invisible under a mock whose transaction client still exposes $transaction. Any test for this must use a transaction client that omits it, mirroring real Prisma — the interactive-transaction tests already have that mock, and it is the shape both triage repros used.

---

Generated by Claude Code