설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2.7 KiB
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. SpringTransactionPort is the only implementation: one pre-built TransactionTemplate per
mode over Spring's PlatformTransactionManager, every mode pinned to READ_COMMITTED.
| 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:
maximumPoolSize >= (concurrent_threads x (1 + max_requires_new_depth)) + 1
Nothing is retried by the port
SpringTransactionPort runs the action once. A failure rolls back and propagates, translated to
the shared persistence error codes where the SQLSTATE is known. 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#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried).
Recovery is reconciliation, not retry:
check the idempotency record -> check the business row -> check the outbox
-> still undetermined? escalate