ArchPilotExecutable architecture guardrails

Search docs

Docs search

Validation rule

Back to Rule Catalog
AP-TXN-003Transaction Boundaries

Nested transaction risk

Flags workflows where transactions may be nested or composed unsafely.

warningviolationNo auto-fix

How to fix

  1. Pass a transaction client/context through nested work.
  2. Ensure only the top-level workflow opens the transaction.
  3. Document transaction ownership in service APIs.

What it means

A transaction-bearing function appears to call another function that can also start a transaction.

Why it matters

Nested transaction behavior varies by ORM/database and can create surprising rollback semantics.

Common causes

  • A helper starts its own transaction.
  • Two service workflows were composed without a transaction contract.
  • Repository methods hide transaction creation.

Example bad pattern

inviteUsersInTransaction(...) calls createMembership(...), which starts another transaction.

Example good pattern

The outer service opens one transaction and passes the transaction client to all writes.

Related files/config

  • apps/api/src
  • apps/web
  • packages

Related CLI commands

  • archpilot validate
  • archpilot validate --ci

Related docs

Rule CatalogTransaction Boundaries
AP-TXN-003 - Nested transaction risk | ArchPilot Docs