Keep transaction boundaries visible

Write the boundary explicitly

List the reads and writes belonging to one transaction. Then list effects outside it, such as HTTP requests or messages already delivered. Avoid describing the whole agent task as atomic when only its database writes share a commit.

Isolation matters

PostgreSQL isolation levels differ in what concurrent changes a transaction can observe. Choose the isolation and locking strategy for the invariant, not merely the ORM default. A retry after a serialization failure must rebuild the whole transaction's decision from a fresh start.

Example invariant

For a stock reservation, checking availability and reducing the same stock must follow a concurrency-safe design. A separate read followed later by an unconditional update can race with another reservation. Test two clients competing for the last unit and assert that at most one reservation succeeds.

External effects and limits

Do not send an irreversible external effect inside a retried transaction without a compatible idempotency protocol: the database may roll back after the effect occurred. Consider recording an outbox intent with the state change, then delivering it separately with duplicate protection. This is a design review method, not a complete reservation implementation; document isolation, retry bounds and failure states for the actual database version.