# Transaction Guide Design §15-§20. What owns a transaction, what may be retried, and what must never be. ## The application service owns the boundary Repository adapters do not open transactions. The use case does, through `TransactionPort`, because the unit of work is a business decision and only the use case knows where it starts and ends. `SpringTransaction` is the only implementation: one pre-built `TransactionTemplate` per mode over Spring's `PlatformTransactionManager`, every mode running at `READ_COMMITTED` and bounded in time. - **Isolation** is pinned on the pool, not per transaction: the module defaults set `spring.datasource.hikari.transaction-isolation: TRANSACTION_READ_COMMITTED` and `HikariPoolConstraintValidator` refuses any other level. A template that names the level makes pgjdbc ask the server for it (`SHOW TRANSACTION ISOLATION LEVEL`) at every begin. - **Time bound**: `app.persistence-jpa.transaction.write-timeout` (`inWrite`, `inRootWrite`) and `read-timeout` (`inRead`), 30 s each by default; `inNew` is fixed at 30 s. Spring hands the remaining time to each statement, so the server cancels a slow statement or lock wait (`DB_QUERY_CANCELED`) and the connection returns to the pool. A unit of work that needs longer is usually a batch job that should be split, not a reason to raise the bound. | Call | Propagation | When | |---|---|---| | `inWrite` | `REQUIRED`, read-write | command default | | `inRootWrite` | `REQUIRED`, read-write, rejects an ambient transaction before running | orchestration that must prove a physical commit | | `inRead` | `REQUIRED`, read-only | query default | | `inNew` | `REQUIRES_NEW`, read-write | outbox / audit / compensation that must commit on its own | Open Session In View is off in every runtime profile. It is on by default in Spring Boot, which is why `JpaDangerousConfigurationGuard` fails startup rather than trusting configuration review. `REQUIRES_NEW` acquires a second physical connection while pinning the first, so the pool must satisfy: ```text maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1 ``` ## Nothing is retried by the port `SpringTransaction` runs the action once. A failure rolls back and propagates, translated to the shared persistence error codes where the SQLSTATE is known; a lost `@Version` race has no SQLSTATE and is reported as `DB_OPTIMISTIC_CONFLICT` (409). A caller that decides to retry must re-run the whole use case in a new transaction — never re-issue one statement — because an optimistic conflict or a serialization failure means the state the attempt computed against is no longer the committed state. A second engine with named policies, deadline budgets, transaction-local timeouts and automatic full-transaction retry (`SpringJpaTransactionExecutor`, `FullTransactionRetryCoordinator`, `PolicyTransactionPort`) existed next to this one and was removed on 2026-09-25. Its last commit is recorded in `docs/capability-status.md`. ## Completion unknown A connection can break while a commit is in flight; the server may have committed and only the acknowledgement was lost. `TransactionCompletionUnknownException` is never retried, and the type system enforces it: `JpaFailureContext` refuses to represent a retryable completion-unknown failure. The port itself retries nothing, so such a commit surfaces to the caller as a failure exactly once (`PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried`). Recovery is reconciliation, not retry: ```text check the idempotency record -> check the business row -> check the outbox -> still undetermined? escalate ```