Transaction boundary too broad

How to fix

1. Narrow the transaction to the required write set.
2. Move reads and non-database work outside the transaction.
3. Split independent workflows into separate transaction scopes.

What it means

A transaction scope includes broad orchestration or unrelated work.

Why it matters

Oversized transactions increase lock duration, retry complexity, and failure blast radius.

Common causes

• A transaction wraps an entire service method.
• Read-only work sits inside a write transaction.
• Several independent workflows were grouped together.

Example bad pattern

A checkout transaction wraps pricing lookup, email rendering, external API calls, and writes.

Example good pattern

The transaction wraps only the related database writes that must commit together.

Related files/config

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

Related CLI commands

• archpilot validate
• archpilot validate --ci