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 the rule validates

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.

Typical violation example

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

Typical compliant example

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

Related rules

AP-TXN-001 - Transaction boundary too broadAP-TXN-002 - Transaction started in controller/API layerAP-TXN-004 - Long-running workflow inside transaction

Adjacent categories

Transaction Boundaries

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