문제
계약 문서 6.1절(ed0e4b1, 백엔드 5786126c 코드 기준)은 400·409·422 code마다
쓰기 전 거절인지를 정했다. 쓰기 전이라 적용 안 됨인 것은 400
VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID,
422 IDEMPOTENT_REQUEST_MISMATCH뿐이고, 표에 없는 400·409·422는 쓰기 뒤에도
나올 수 있어 결과 불명이다. 지금 판정은 이 표와 세 곳이 다르다.
- V2: 필드 목록 없는 400 VALIDATION_FAILED({cause}, details 없음,
{field, code})에 effect가 없다. 결과 불명으로 붙들려 다시 저장할 수 없다.
- V2: 422는 code와 상관없이 적용 안 됨이다. fileserver의 422
INTEGRITY_MISMATCH·MALWARE_DETECTED는 레코드를 쓴 뒤 던진다.
- V3 Envelope operation(7db32e1): 위 V2 규칙을 같이 쓰고, 표 밖 400·409·422는
classifyProblem에 맡긴다. 400·422를 모두 적용 안 됨으로 보는 분류기면
BAD_PARAMETER·도메인 400이 틀린다.
고른 방법
- backend-envelope.ts에 표 REFUSED_BEFORE_WRITE(code → status, 진단
reason)를 하나 두고 V2 client.ts, V3 실행기가 envelopeFailureEffect로
같이 읽는다. 표에 있으면 NOT_APPLIED, 그 밖의 400·409·422와 503
IDEMPOTENCY_UNAVAILABLE은 MAYBE_APPLIED, 나머지 status는 undefined
(V2는 effect 없음, V3는 classifyProblem)다. 진단 reason도 같은 표에서
읽는다.
- kind와 validationIssues 판정(isFieldValidationFailure)은 그대로 둔다.
필드 목록 없는 400 VALIDATION_FAILED는 UNKNOWN_CLIENT_FAILURE, 422는
VALIDATION_REJECTED다. 적용 여부만 바뀐다.
- V3 Envelope operation에서는 400·409·422를 표가 정하고 classifyProblem이
바꾸지 못한다.
버린 대안
- V2와 V3에 표를 따로 두기: 7db32e1 전처럼 두 벌이 갈라진다.
- 표 밖 400·409·422를 classifyProblem에 맡기기: 6.1절이 표 밖은
MAYBE_APPLIED로 정했고, 적용 안 됨을 잘못 내면 다음 저장이 새 키를 써
같은 작업이 두 번 적용된다. 잘못된 MAYBE_APPLIED는 결과 불명 화면만 남긴다.
- 422 전부를 필드 검증(적용 안 됨)으로 남기기: 짝 백엔드는 필드 검증을
400으로 보내고, fileserver 422는 쓴 뒤 던진다.
- V3 참조 기능 분류기 고치기: 참조 기능은 Envelope operation이 아니고
fixture가 problem details라 이 표의 대상이 아니다. 고치지 않았다.
위험·한계
- 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에
폼에서 다시 저장할 수 없다(결과 불명). 프론트 계약 문서 4.2절의 "422
field validation" 행과 어긋난다. 그 문서는 이 커밋에서 고치지 않았다.
- 표는 백엔드 5786126c 기준이다. 백엔드가 쓰기 전 거절 code를 새로 만들면
6.1절과 이 표를 함께 고쳐야 한다. 두 repo를 비교하는 검사는 없다.
- 6.1절의 남은 위험: 백엔드가 use case 안에서 VALIDATION_FAILED를 내게 되면
적용 안 됨 판정이 틀린다.
검증
- RED: 바뀐 행 8건 실패. tests/integration/http-client.test.ts 필드 목록
없는 400 VALIDATION_FAILED 3모양의 effect, http-diagnostics.test.ts의
"unrelated 422"(effect NOT_APPLIED), http-execution-v3-envelope.test.ts의
고정 판정 2건(VALIDATION_FAILED 3모양 NOT_APPLIED, BAD_PARAMETER·도메인
409·fileserver 422 MAYBE_APPLIED), form-foundation.test.tsx 2건({cause}
실패 뒤 다시 저장, 422 뒤 저장 버튼 꺼짐).
- GREEN: 위 4개 파일 128건 통과. V2와 V3에 같은 응답 11가지를 보내 판정을
비교하는 행이 모두 같다.
- check:types, lint, check:architecture, check:diagnostics, check:ci,
check:registries, check:adapter-inventory 통과. test:unit 2,604,
test:integration 209, test:component 245, tests/features·tests/contract
124건 통과. check:bundle 203,354 / 204,800 B.
Refs: docs/architecture/backend-api-and-server-state-contract.md 6.1 (ed0e4b1),
docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6
문제
V2 클라이언트(client.ts)는 필드 검증 거절(422, 짝 백엔드의 400
VALIDATION_FAILED + 필드 목록)에 effect를 붙이지 않는다. mutation
코디네이터(application-query.ts mutationFailureWithEffect)는 effect가 없으면
MAYBE_APPLIED로 보고 admission을 UNKNOWN으로 붙든다. 폼은 VALIDATION_
REJECTED를 필드 오류로 보여 주지만, 참조 폼 페이지는 코디네이터가 결과 불명을
들고 있으면 저장 버튼을 끈다(reference-resource-form-page.tsx
mutationBlocked). 사용자가 필드를 고쳐도 다시 저장할 수 없다. use-app-form
자체는 VALIDATION_REJECTED에서 unknownSubmissionRef를 비우므로 막지 않는다.
막는 것은 코디네이터 상태다.
V3 참조 기능은 재현되지 않는다. 생성 분류기가 400·422를 NOT_APPLIED로
본다(reference-feature-contract-contribution.ts classifyProblem).
고른 방법
V2에서 필드 검증 거절(fieldValidation: 422, 또는 400 VALIDATION_FAILED +
배열 details)에 effect NOT_APPLIED를 붙인다. 멱등성 거절(IDEMPOTENCY_
REFUSALS)과 같은 자리에서 붙이고, 진단 reason은 멱등성 거절에만 남긴다.
근거(백엔드 계약)
- docs/web/http-contract.md 4절과 web adapter README 예외 표가 VALIDATION_
FAILED의 출처를 적는다: 요청 본문 바인딩(MethodArgumentNotValid
Exception), 컨트롤러 파라미터 제약(HandlerMethodValidationException),
Bean Validation(ConstraintViolationException), 페이지 파라미터, 읽을 수
없는 본문. 모두 요청을 묶는 단계에서 컨트롤러·use case보다 먼저 거절한다.
- 4절에 "상태를 바꾸지 않는다"는 문장은 없다. 이 판정은 위 출처에서
끌어낸 것이다.
버린 대안
- 코디네이터가 effect 없는 VALIDATION_REJECTED를 모두 NOT_APPLIED로 보기:
거절을 판정하는 곳은 응답을 읽는 클라이언트다. 코디네이터의 "모르면
MAYBE_APPLIED" 규칙은 그대로 둔다.
- 폼 페이지가 VALIDATION_REJECTED 뒤 결과 불명을 무시하기: 키가 붙은 채
남아 같은 입력을 다시 저장하면 같은 키가 나간다.
위험·한계
- application 층에서 쓰기 뒤에 VALIDATION_FAILED를 던지는 백엔드 코드가
있다면 이 판정은 틀린다. 짝 백엔드 IdempotencyExecutor는 실행 중 예외를
EFFECT_UNKNOWN_ABANDONED로 기록한다. 이 경우 같은 키 재전송은 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받는다. NOT_APPLIED면 다음 저장이 새 키를
쓰므로 그 경로를 타지 않는다.
- 필드 목록 없는 400 VALIDATION_FAILED({cause}, 본문 파싱 실패)와 그 밖의
400·409는 effect 없이 둔다(결과 불명으로 붙듦). 이번 범위 밖이다.
- 422 IDEMPOTENT_REQUEST_MISMATCH는 원래 NOT_APPLIED였고 그대로다.
검증
- RED: tests/component/form-foundation.test.tsx "saves the corrected value
after a $status field error" 2행(422, 400 VALIDATION_FAILED) 실패. 필드
오류 뒤 저장 버튼이 disabled다.
- V3: tests/features/reference-feature/reference-production-vertical.test.tsx
"saves the corrected value after a server 422 field error"는 수정 전에도
통과한다(재현 안 됨, 동작 고정).
- GREEN: 위 행 통과. tests/integration/http-diagnostics.test.ts의 "unrelated
422" 행은 effect가 없다고 기대하던 것을 NOT_APPLIED로 바꾸고, 409 행을
더해 다른 거절은 effect가 없음을 고정했다. tests/integration/http-client.
test.ts에 400 VALIDATION_FAILED effect 단언을 더했다.
tests/unit·contract·runtime-schema·integration·component·features·platform
3398 tests 통과, 1개 실패(tests/unit/second-api-feature-registries.test.ts,
기준 3b7d73a에서도 같은 메시지로 실패). tsc app·test, 바꾼 파일 eslint
통과.
Refs: clean-architecture-backend-template docs/web/http-contract.md 4절, src/adapter/inbound/web/README.md 예외 표
문제
짝 백엔드는 KEYED 요청을 실행하기 전에 두 가지를 거절한다(백엔드
docs/web/http-contract.md §2).
- 422 IDEMPOTENT_REQUEST_MISMATCH: 같은 키에 다른 본문. 클라이언트 버그.
- 400 IDEMPOTENCY_KEY_INVALID(details.reason MISSING·MALFORMED): 키 누락·
형식 오류.
둘 다 이 요청은 적용되지 않았고, 그대로 다시 보내면 같은 답이 온다.
- V2(client.ts)는 이 실패에 effect를 붙이지 않는다. mutation 코디네이터는
effect가 없으면 MAYBE_APPLIED로 보고(application-query.ts
mutationFailureWithEffect) 키를 붙든다. 400은 결과 불명 화면으로 가고,
같은 입력을 다시 저장하면 같은 키로 같은 400·422를 계속 받는다. 진단
이벤트(http.request.completed)에는 원인이 없다.
- V3 참조 기능은 분류기가 400·422를 이미 NOT_APPLIED로 본다. 다만
mapProblem이 400을 다루지 않아 code가 CONTRACT_PROBLEM으로 바뀌고
서버의 IDEMPOTENCY_KEY_INVALID가 사라진다.
고른 방법
- V2: 문서에 적힌 status와 code가 둘 다 맞을 때만 effect NOT_APPLIED를
붙인다(IDEMPOTENCY_REFUSALS 표). 같은 표가 진단 reason을 준다.
- 422 → reason IDEMPOTENT_REQUEST_MISMATCH
- 400 → reason IDEMPOTENCY_KEY_RULE_MISMATCH. 프론트는 보내기 전에
isValidIdempotencyKey로 키를 검사한다. 서버의 400은 두 키 규칙이
어긋났다는 뜻이라 그 이름으로 남긴다. 보내기 전 거절(VALIDATION_
REJECTED, httpStatus 없음)은 표에 걸리지 않는다.
reason은 diagnostics에만 넣는다. telemetry 속성은 그대로다(VD-07).
- V3 참조 mapProblem: 400 + IDEMPOTENCY_KEY_INVALID만 UNKNOWN_CLIENT_
FAILURE와 서버 code로 둔다. 다른 400은 기존 fallback 그대로다.
- kind는 바꾸지 않았다(422 VALIDATION_REJECTED, 400 UNKNOWN_CLIENT_
FAILURE). 둘 다 retryable:false이고 V2 재시도 대상이 아니다.
- 키 문법은 백엔드 IdempotencyKeyHeader([\x21-\x7E]{1,256}, trim 없음)와
같다. 1자 키를 받는 행을 더해 경계를 고정했다.
버린 대안
- code만 보고 판정: 다른 status에 같은 code가 오면 NOT_APPLIED를 잘못
붙인다. NOT_APPLIED는 다음 저장이 새 키를 쓰게 하는 판정이라 문서의
짝(status+code)만 믿는다.
- 422 mismatch를 UNKNOWN_CLIENT_FAILURE로 바꾸기: 화면 문구가 바뀐다.
요구는 재전송 금지·결과 불명 화면 금지·원인 code 보존이라 kind는 두었다.
- 서버 code를 진단 reason에 그대로 넣기: 서버 code는 무제한이라 진단
cardinality 규칙(taxonomy)을 깬다. 표에 있는 두 값만 넣는다.
위험·한계
- 422 mismatch를 NOT_APPLIED로 보면 다음 저장이 새 키를 쓴다. 같은 키의
앞선 요청이 적용됐을 수 있지만, 프론트는 canonical 입력이 같을 때만 키를
재사용하므로 mismatch는 지문 규칙이 어긋난 버그다. 결정(15절)대로 이번
요청은 적용되지 않았다고 본다.
- 422 화면 문구는 "입력값을 다시 확인해 주세요."다. 사용자가 고칠 입력이
아니지만 다시 저장하면 새 키로 나간다.
- V3 실행기의 진단은 problem code를 모른다(Problem 타입은 계약 패키지
소유). V3에서 원인은 AppFailure.code·httpStatus로만 보인다.
검증
- RED: tests/integration/http-diagnostics.test.ts 새 2행 실패(effect
undefined, reason 없음). tests/features/reference-feature/reference-http-
problem-mapping.test.ts 400 IDEMPOTENCY_KEY_INVALID 행 실패(code
CONTRACT_PROBLEM). 422 mismatch 매핑, 분류기 2행, 1자 키 행은 처음부터
통과(이미 맞는 동작을 고정).
- GREEN: 위 파일과 tests/features/reference-feature, tests/integration/
http-client·http-execution-contract·auth-recovery·legacy-http-credential-
authority, tests/contract/reusable-capability/feature-http-binding 24 files
207 tests 통과. tests/unit/legacy-and-optional-network-remediation 6/6.
tsc app·test 통과, 바꾼 파일 eslint 통과.
Refs: clean-architecture-backend-template docs/reviews/2026-11-01-maturity-review/README.md 14.3, 15