Files
clean-architecture-backend-…/docs/adr/ADR-JPA-003-completion-unknown.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: 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>
2026-09-25 12:49:07 +09:00

2.2 KiB

ADR-JPA-003 — Completion unknown is never retried

  • Status: Accepted; amended 2026-09-25 — TransactionCompletionResolver, CommitFailureClassifier and the retry engine were removed. The invariant holds because SpringTransactionPort, the only transaction engine, retries nothing; enforcement below is updated accordingly.
  • Date: 2026-08-11
  • Design: §17

Context

A connection can break while a commit is in flight. The server may have committed; the acknowledgement may simply have been lost. The driver cannot tell the two apart.

Decision

TransactionCompletionUnknownException is never retried, automatically or otherwise. It is produced only by a failure observed while the transaction phase is COMMITTING, and only for SQLSTATE 40003, a connection-class (08*) state, or a transport break. Recovery is domain-specific reconciliation.

Consequences

Retrying a possibly-committed write is the most damaging thing this platform could do: a duplicate payment, a duplicate order, a double decrement. There is no budget or backoff that makes it safe, because the failure is epistemic rather than transient.

The invariant is enforced at the type level rather than by policy alone. JpaFailureContext refuses to construct a retryable completion-unknown context, and the exception rebuilds its context through the safe factory whatever it is handed. A future policy bug therefore cannot produce an unsafe retry — the value it would need does not exist.

The rule is deliberately narrow in the other direction too. Classifying every connection failure as completion-unknown would push ordinary pool exhaustion and server restarts into the reconciliation queue, which trains operators to clear that queue without reading it — and then the one entry that mattered gets cleared with the rest.

The cost is that the domain must supply the resolver. The platform cannot: only the domain knows which idempotency record, business row, or outbox entry proves the write happened.

Enforcement

JpaFailureContextTest; PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsAFailureAndIsNeverRetried (also the jpa-failure lane, i.e. release gate completion-unknown-no-retry).