문제: 2026-11-01 성숙도 리뷰에서 High 21건·P1 25건이 나왔다. 결과를 모르는 일을 "확실함"으로 기록했다(발송 중 죽은 알림 재발송, 커밋 중 끊긴 쓰기를 재시도 가능으로 응답, 재시도 가능한 거부를 DEAD로). 중복을 DB가 아니라 코드 순서로 막았다(정산 job, 포스터 제목). 짝 프론트와 wire 계약이 달랐고(처리 중 409, Envelope null), JWT audience 검증이 기본으로 꺼져 있었고, 트레이스가 나가지 않았고, CI가 strict lane 14개를 한 번도 돌리지 않았다. 방법: 발견마다 실패하는 테스트를 먼저 쓰고 고쳤다. 주요 선택: - 알림 attempt는 처음부터 "시작 여부 모름"으로 쓴다(호출 직전 갱신은 쓰기가 하나 늘어 버림). - 정산 job claim은 lease·fence를 갱신하는 UPDATE 한 문장(처리 전체를 트랜잭션으로 감싸는 안은 외부 호출 동안 잠금을 잡아 버림). - 커밋 단계 연결 끊김은 DB_COMPLETION_UNKNOWN(재시도 불가). - 처리 중 409는 retryable=true + Retry-After: 2, Envelope null 필드는 web Jackson mixin으로 생략(shared-contract는 stdlib only). - 트레이싱은 자체 Tracer를 지우고 Boot 4 tracing·OTLP로. - strict lane을 단계에 연결하고 verifyStrictLaneStages가 고아를 막는다. 발견별 RED·GREEN·버린 대안은 리뷰 README 13절 표에 있다. 위험·한계: JWT 모드는 APP_SECURITY_JWT_AUDIENCE가 없으면 기동하지 않는다. 짝 프론트는 409 retryable과 Envelope 키 규칙을 맞춰야 한다. 이 커밋 시점에는 MinIO 공식 이미지가 사라져 MinIO 2 lane이 실패한다 (다음 커밋에서 대체 이미지로 해결). 검증: ci 통과. mainCheck·integrationCheck는 MinIO 2 lane만 실패(이미지 pull 거부). -p optional-platforms ci integrationCheck, performanceCheck, releaseCheck(-PgitRevision) 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 2·13절 BREAKING CHANGE: JWT 모드에서 APP_SECURITY_JWT_AUDIENCE가 필수가 되고 role은 audience client와 realm 것만 읽는다. IDEMPOTENT_IN_FLIGHT가 retryable=true, Retry-After: 2로 바뀌고 Envelope는 null 필드를 보내지 않는다.
3.0 KiB
ADR-JPA-003 — Completion unknown is never retried
- Status: Accepted; amended 2026-09-25 —
TransactionCompletionResolver,CommitFailureClassifierand the retry engine were removed. The invariant holds becauseSpringTransactionPort, 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
Production path: SpringTransaction records when the action has returned in a write transaction it
began; a failure after that point goes through
PersistenceExceptionTranslator#translateCommitFailure, which builds this exception for 08*,
40003, a vendor termination state (SqlStateErrorMapping#commitOutcomeUnknownStates, PostgreSQL
57P01/57P02) or a transport break. Hibernate's flush inside the commit is not separated from the
COMMIT itself, so a connection lost during that flush is also reported as unknown — the safe side.
Until review 04-01 (2026-11-01) nothing constructed the exception and a commit-phase 08* reached
callers as the retryable DB_UNAVAILABLE.
JpaFailureContextTest; SpringTransactionTest; PersistenceExceptionTranslatorTest;
PostgreSqlTransactionIntegrationTest#connectionLossDuringCommitSurfacesAsCompletionUnknownAndIsNeverRetried
(asserts DB_COMPLETION_UNKNOWN; also the jpa-failure lane, i.e. release gate
completion-unknown-no-retry).