문제
V2 클라이언트는 짝 백엔드의 422 IDEMPOTENT_REQUEST_MISMATCH와 400
IDEMPOTENCY_KEY_INVALID를 진단(http.request.completed)의 reason으로
남긴다(93782b0). V3 실행기의 진단에는 백엔드 code가 없다(리뷰 README
14.4). Problem 타입이 계약 패키지 소유라 실행기가 code를 몰랐기 때문이다.
7db32e1 뒤로 responseEnvelope: "ENVELOPE_V1" operation의 실행기는
Envelope error.code를 읽는다.
고른 방법
- Envelope operation의 실패에서 backend-envelope.ts의
idempotencyRefusalReason(code, status)를 불러 V2와 같은 두 값을
HttpDiagnosticReason으로 싣는다. projector(runtime-adapters.ts)는 이미
diagnosticReason을 reason으로 옮기므로 bootstrap은 바꾸지 않았다.
- 표의 reason 타입을 IdempotencyRefusalReason으로 좁혀 두 값이 닫힌
목록임을 타입으로 둔다.
버린 대안
- 백엔드 code를 reason에 그대로 넣기: reason은 이 repo가 소유한 닫힌
목록(taxonomy)이고, 서버 code를 그대로 넣지 않는다는 93782b0 결정과
어긋난다. V2도 넣지 않는다.
- 새 진단 키(problem_code) 추가: src/contracts/diagnostics.ts 허용 목록과
bootstrap projector를 함께 바꿔야 하고 cardinality 등급을 새로 정해야
한다. 이 변경 범위를 넘는다.
위험·한계
- 그 밖의 백엔드 code는 진단에 없다. 실패의 AppFailure.code에만 있다.
- DTO 모드 operation(참조 기능)의 진단에는 여전히 code가 없다.
- classifyProblem이 던져 CLASSIFIER_FAILED가 되는 경우는 Envelope 판정이
있으면 분류기를 부르지 않으므로 둘이 겹치지 않는다.
검증
- RED: tests/integration/http-execution-v3-envelope.test.ts의 "V3 Envelope
diagnostics name what V2 names" 4행 중 2행 실패(422·400에서 V3 reason
undefined). 409 두 행은 처음부터 통과(reason 없음 고정).
- GREEN: 같은 파일 29건 통과. 같은 응답의 V2 진단 기록과 V3 진단 기록의
reason을 비교한다.
- check:types, lint, check:architecture, check:diagnostics 통과.
test:unit 2,604, test:integration 204, test:component 244,
tests/features·tests/contract 124건 통과.
- check:bundle 통과(203,352 / 204,800 B, 7db32e1 대비 +31 B).
Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6