문제: 80e7f1d의 isRefusedOnEveryAttempt는 kind가 VALIDATION_REJECTED면 code를
보지 않고 참을 돌려준다. 그 kind는 기능의 mapProblem이 정한다. 생성기는
선언한 <FEATURE>_INVALID를 VALIDATION_REJECTED로 옮기고
(scripts/create-feature-write-slice.ts mapProblem), 참조 기능 gateway는 code와
상관없이 모든 422를 그렇게 옮긴다(reference-http-gateway.ts). 그래서 기능이
선언한 code나 422 IDEMPOTENT_REQUEST_MISMATCH로 끝난 같은 키 재전송이 결과
불명을 푼다. 함수 주석, CHANGELOG, 런북 6.3-4는 이것들이 결과 불명으로
남는다고 적는다. 기존 테스트는 mapProblem 없이 실패를 만들어 이 길을 타지
않았다(최종 리뷰 FR-01).
고른 방법(메인 세션 결정 "D10 보완 2"): 재전송 거절은 짝 백엔드 표의 code일
때만 결과 불명을 푼다. 지금은 400 VALIDATION_FAILED와 400
IDEMPOTENCY_KEY_INVALID다(REFUSALS_OF_EVERY_ATTEMPT, code와 status 함께). kind
줄을 지우고 kind로 입력 검증을 말하던 주석과 런북 6.3-4를 고쳤다. 기능 code는
상태 규칙일 수 있어 mapProblem이 정한 kind를 믿지 않는다. 400
VALIDATION_FAILED는 필드 목록이 있든 없든 전처럼 푼다.
테스트: 훅의 결과 불명 유지 it.each에 mapProblem 모양(VALIDATION_REJECTED +
선언 code, VALIDATION_REJECTED + 422 IDEMPOTENT_REQUEST_MISMATCH) 두 행을 더했다.
참조 페이지에서 422 재전송이 필드 오류와 다시 저장을 보인다던 테스트를, 결과
불명이 남고 확인이 보이는 테스트로 바꿨다. 리뷰가 요청한 대로 다시 마운트한 폼이
다른 값을 보이는 채 재전송해 422 IDEMPOTENT_REQUEST_MISMATCH를 받으면 결과
불명과 확인 버튼이 남는 테스트를 더했다.
버린 대안: kind 줄을 남기고 기능 선언 code만 빼기(실행기는 code가 선언인지
폼과 훅에 알리지 않는다).
위험·한계: 참조 기능처럼 problem details를 읽는 기능의 422 입력 검증은 재전송
뒤 결과 불명으로 남는다. 출구는 결과 불명 화면의 확인이다. 리뷰 실험 03-R1
X1~X3·X5는 그대로 키가 모두 key-1이어야 한다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/component/form-foundation.test.tsx tests/unit/backend-envelope.test.ts,
리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (final review FR-01)
문제: 1106/03-01(2568587)은 결과 불명 요청을 같은 키로 다시 보낸 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 이유와 상관없이 결과 불명과 키를 남긴다.
같은 요청이 매번 받는 거절(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID,
필드 목록이 있는 입력 검증)도 같다. 폼은 필드 오류를 버리고 "잠시 뒤 같은
요청으로 다시 보내 주세요"만 보인다. 저장은 꺼져 있고 다시 보내면 같은 400이
온다. 출구는 사실이 아닌 "변경됨으로 확인"이나 새로고침뿐이다. 815ea58
(1106/03-03)이 같은 길을 IDEMPOTENT 쓰기로 넓혔다(diff 리뷰 DR-01).
고른 방법(메인 세션 결정, D10 보충): 같은 키 재전송은 그 결과가 첫 요청에
무슨 일이 있었는지 보여 줄 때만 결과 불명을 푼다.
- 성공·APPLIED_CONFIRMED: 저장된 답의 재생이다. 지금처럼 푼다.
- 같은 요청이라 첫 요청도 받았을 거절: 푼다. src/contracts/errors.ts에
isRefusedOnEveryAttempt를 두었다. effect NOT_APPLIED이고, kind
VALIDATION_REJECTED(필드 목록이 있는 입력 검증)이거나 code·status가
REFUSALS_OF_EVERY_ATTEMPT(400 VALIDATION_FAILED, 400 IDEMPOTENCY_KEY_INVALID)다.
- 그 밖(429, 401, 403, 503 RATE_LIMIT_*, 422 IDEMPOTENT_REQUEST_MISMATCH(키가
이미 서버에 닿아야 나온다), 기능이 선언한 code(바뀌는 상태의 규칙일 수
있다), IDEMPOTENT 쓰기의 404·412 같은 다른 code, NOT_STARTED): 지금처럼
결과 불명과 키를 남긴다. 어느 쪽인지 모르는 code는 남긴다.
훅(resendLeavesUnknown)과 폼(resendLeftUnknown)이 같은 함수를 부른다. 폼은 푼
경우 처음 저장과 같이 보인다(필드 오류, 다시 받는 저장, 고친 값은 새 키).
남긴 경우 결과 불명 화면(확인·다시 보내기)이 그대로라 폼이 영영 막히지
않는다. 표는 backend-envelope.ts REFUSED_BEFORE_WRITE의 부분집합이어야 하고,
표의 나머지 행은 다른 쪽으로 분류된다. backend-envelope 단위 테스트가 둘을
대조해, 표에 새 행이 생기면 이 분류를 정할 때까지 실패한다. presentation은
adapters를 import할 수 없어(.dependency-cruiser.json) 판정을 contracts에 둔다.
버린 대안: 일시 거절(NOT_STARTED, retryable, RATE_LIMITED, RATE_LIMIT_*)만
남기기(diff 리뷰 안). 401·403과 422 IDEMPOTENT_REQUEST_MISMATCH, 기능 선언
code를 풀어 버린다. AppFailure에 새 칸을 더해 실행기가 표시하기(계약 타입과
실행기·바인딩을 함께 바꾼다).
위험·한계: 기능이 선언한 결정적 거절(생성 기능의 400 <FEATURE>_INVALID)은
어느 쪽인지 알 수 없어 결과 불명으로 남는다. 출구는 결과 불명 화면의
확인이다. 필드 목록이 있는 NOT_APPLIED는 기능 선언 code여도 입력 검증으로
본다. 리뷰 실험 03-R1 X1~X3·X5(503·429·NOT_STARTED)는 그대로 키가 모두
key-1이어야 한다. 런북 6.3-4를 고쳤다. CHANGELOG는 다음 커밋이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx
tests/features/reference-feature/reference-page.test.tsx
tests/unit/backend-envelope.test.ts, 리뷰 실험 03-R1 패치를 이 커밋에 적용
Refs: 1106/03-01 (diff review DR-01)
문제: 0929/03-03의 두 가드(재전송 버튼 canResend, 같은 입력 재제출 거절)가
intent의 키 유무로만 가른다. 뮤테이션 정책은 키 여부만 실어서 훅이 NEVER와
IDEMPOTENT를 가를 수 없다. 그래서 IDEMPOTENT 쓰기(손으로 쓴 PUT·DELETE)도
결과 불명 뒤 재전송 버튼이 없고 같은 입력 저장이 UNKNOWN_EFFECT_PENDING으로
거절된다. 출구는 사실을 모르는 "변경됨으로 확인"이나 새로고침뿐이다. 매뉴얼은
IDEMPOTENT를 "여러 번 적용해도 결과가 같다"로 적고, 실행기도 보낸 뒤에
다시 보낸다.
고른 방법(리뷰 03-03 대안 (a)): commandMutationIdentity가 resendSafe
(KEYED 또는 IDEMPOTENT)를 함께 준다. BoundMutation에 선택 칸 resendSafe를
더했다(추가만). 훅은 admission마다 resendable(키가 있거나 정책이
resendSafe)을 적고, 두 가드가 키 대신 그 값을 본다. 칸이 없는 손으로 쓴
정책은 지금처럼 키 유무로 간다. NEVER의 재전송 금지와 같은 입력 거절은
그대로다. 매뉴얼 01·02와 런북 6.3-4에 IDEMPOTENT 행을 적었다.
버린 대안: 문서만 고치기(회복 경로가 그대로 불편하다), IDEMPOTENT에도 키를
붙이기(백엔드가 키를 읽지 않으면 의미가 없고 실행기가
UNEXPECTED_IDEMPOTENCY_KEY로 거절한다).
위험·한계: commandMutationIdentity의 반환 객체에 칸이 하나 늘었다. 그 값을
toEqual로 비교하던 테스트는 칸을 더해야 한다(이 repo는 1곳을 고쳤다).
IDEMPOTENT로 잘못 선언한 쓰기(백엔드가 실제로는 중복을 막지 못함)는 이제
결과 불명 뒤 사용자가 다시 보낼 수 있다. 선언의 정확성은 기능 작성자
몫이다(02 결정표 3절). 템플릿 안에는 IDEMPOTENT 쓰기 소비자가 없다.
CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/unit/command-mutation-identity.test.ts
Refs: 1106/03-03
문제: KEYED 결과 불명 요청을 같은 키로 다시 보냈는데 그 시도가 쓰기 전
거절(429, 엣지 rate limiter의 503 RATE_LIMIT_*, 401)이나 보내기 전 실패
(NOT_STARTED)로 끝나면, 훅이 그 판정을 논리 요청 전체의 판정으로 써서
결과 불명과 intent를 버린다. 폼은 retry-later가 되고 다음 저장이 새 키로
나간다. 첫 요청이 적용됐으면 같은 항목이 둘 생긴다. 재전송의 NOT_APPLIED는
그 시도만 증명한다. 백엔드 http-contract.md §2와 런북 6.3-4는 결과 불명에
새 키를 금지한다(리뷰 실험 03-R1 X1~X3·X5: keys key-1, key-1, key-2).
고른 방법(결정 D10, 메인 세션, 2026-11-06: 리뷰 03-01 대안 (a)):
- 훅(application-query.ts submit): 결과 불명 intent를 다시 쓴 시도가
NOT_APPLIED·NOT_STARTED로 끝나면 새 admission을 UNKNOWN으로 되돌리고 그
intent와 키를 남긴다. 실패는 그대로 돌려준다. Retry-After는 MAYBE_APPLIED와
같이 다음 재전송의 대기 시각이 된다. 낙관적 층은 rollback 대신
markUncertain이다(첫 요청이 적용됐을 수 있다). 훅 안의 보내기 전 예외
(.catch, NOT_STARTED)도 같다. 이 경우 충돌 상태는 세우지 않는다. 화면은
결과 불명을 먼저 보여야 한다. 처음 보내는 요청의 NOT_APPLIED, 재전송의
성공·APPLIED_CONFIRMED, scope가 바뀐 경우는 지금처럼 정리한다.
- 폼은 (i)을 골랐다: use-app-form.ts resendUnknown이 그런 결과에서
unknownSubmissionRef를 지우지 않고 result를 effect-unknown으로 둔다. 문구
하나("form.resendLater": "잠시 뒤 같은 요청으로 다시 보내 주세요")를
formErrors에 싣고 feedback으로 포커스를 옮긴다. 이유: 폼은 이미 그 ref로
저장을 막는다(submitForm). 결과 불명 화면(확인·같은 키로 다시 보내기)이
그대로 남아 다음 행동이 재전송이다. (ii)는 useAppForm이 코디네이터 상태를
받는 새 옵션이 필요하다. 폼과 훅을 새로 묶는 일이라 지난 라운드 3.5 (B)로
미룬 설계 변경이다. 401은 D-2대로 다시 로그인이 먼저다.
버린 대안: 표에서 rate-limit 503을 다시 MAYBE_APPLIED로(429·401·NOT_STARTED가
남고 1105/03-02의 이득을 잃는다), 생성 페이지의 "다시 시도"만 고치기(생성
기능만 덮는다).
위험·한계: 재전송이 rate limit에 막힌 동안 결과 불명 화면이 남는다. 다시
보내기는 Retry-After(상한 5초)를 기다린다. 폼 밖에서 submit을 부른 같은
입력 재저장이 NOT_APPLIED로 끝나면 훅은 키를 지키지만 폼은 retry-later를
보인다. 그때 "다시 시도"도 같은 키로 간다. 새 문구가 초기 JS를 조금
늘린다(check:bundle). CHANGELOG 행은 문서 담당이 적는다.
검증: desktop batch에서 확인. node scripts/run-vitest.ts run
tests/component/application-mutation-admission.test.tsx
tests/component/form-foundation.test.tsx, 리뷰 실험 03-R1 패치를 이 커밋에
적용해 X1~X3 keys [key-1,key-1,key-1], X5 세 번째 요청 없음 또는 key-1.
Refs: 1106/03-01
문제
0929/03-03은 화면 버튼 쪽만 고쳐졌다. 남은 길이 둘이다.
- useApplicationMutation의 submit은 같은 canonical input의 결과 불명
admission을 찾아 그 intent를 그대로 다시 보낸다. 키 없는 intent(NEVER)면
서버가 가려낼 수 없는 두 번째 요청이다. 막는 곳은 폼(unknownSubmissionRef)과
두 페이지의 버튼·onSubmit 검사뿐이라, 폼 밖에서 submit을 부르는 화면은 같은
항목을 둘 만들 수 있다(리뷰 실험 X1: 재전송은 null인데 같은 입력 submit이
두 번째 POST를 보냈고 keys=[null,null]).
- AsyncSurface는 state.unknownEffectResendable !== false일 때 재전송 버튼을
그린다. 코디네이터 없이 손으로 만든 AsyncState(플래그 없음)는 지금도 버튼을
그린다(실험 X3).
고른 방법
- submit이 같은 입력의 결과 불명 admission을 찾았는데 그 intent에 키가 없으면
보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를
돌려준다. admission을 만들기 전이라 결과 불명 상태와 identity lease는 그대로다.
KEYED의 같은 키 재전송, 입력이 바뀐 새 요청은 바뀌지 않는다. LEGACY(테스트
하네스) 경로는 intent가 없어 replay 자체가 없으므로 영향이 없다.
- AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다.
코디네이터의 state는 늘 이 값을 싣는다(canResendUnknownEffect).
- 기존 async-surface 테스트 "renders unknown mutation effects with
confirm-applied and resend only"는 플래그 없는 상태로 버튼을 기대했다. 이
수정의 의도대로 isUnknownEffectResendable: true를 입력에 적었다. 단언은 그대로다.
- 런북 6.3-4와 매뉴얼 01에 키 없는 재제출과 손으로 만든 상태를 적었다.
버린 대안
FailureKind에 새 kind를 더한다: 닫힌 레지스트리를 넓히는 계약 변경이다.
"같은 논리 요청이 아직 끝나지 않았다"는 DUPLICATE_IN_FLIGHT(action none)로
충분하다.
위험·한계
- 다운스트림이 AsyncSurface에 손으로 만든 결과 불명 상태와 onResendUnknownEffect를
넘기던 화면은 재전송 버튼이 사라진다. 코디네이터의 state를 넘기면 그대로다.
- 결과 불명 admission은 메모리에만 있다. 새로고침 뒤 같은 입력은 막지 못한다
(런북 6.3-7의 한계 그대로).
검증
desktop batch에서 확인:
node scripts/run-vitest.ts run tests/component/application-mutation-admission.test.tsx
tests/component/async-surface.test.tsx tests/component/application-query.test.tsx
Refs: 0929/03-03
문제
resendUnknownEffect는 가장 오래된 admission이 UNKNOWN이고 intent가 있는지만
본다. 키 없는 명령(NEVER)도 intent는 있다. 그래서 응답을 잃은 NEVER 쓰기의
결과 불명 화면에서 "같은 요청으로 다시 보내기"를 누르면 키 없이 다시 나가고,
서버가 두 요청을 가려낼 수 없어 같은 항목이 두 번 생길 수 있다(리뷰 실험
X-D: fetch 2회, 키 [null, null]). 짝 백엔드 생성 기능의 create가
NOT_IDEMPOTENT이고 매뉴얼이 "모르면 NEVER"를 권하므로 이것이 짝 사용의
기본 경로다. 화면(AsyncSurface)은 콜백이 있으면 버튼을 그린다. 훅에도 화면에도
이 버튼을 숨기는 장치가 없다.
고른 방법
- application-query.ts canResend: head가 UNKNOWN이고 intent에
idempotencyKey가 있고 reconciliation 중이 아닐 때만 참. resendUnknownEffect는
거짓이면 null을 돌려준다. 컨트롤러가 canResendUnknownEffect로 같은 값을 낸다.
- AsyncState에 선택 칸 unknownEffectResendable(결과 불명일 때만)을 두고,
훅이 deriveAsyncState 신호로 채운다. AsyncSurface는 이 값이 false면
onResendUnknownEffect가 있어도 재전송 버튼을 그리지 않는다. 그래서 기존
페이지 배선(참조 폼)은 바꾸지 않아도 키 없는 명령에서 버튼이 사라진다.
- KEYED는 지금처럼 같은 키로 재전송한다.
버린 대안
- 페이지가 canResendUnknownEffect를 보고 콜백을 넘기지 않게만 하기: 기존
배선을 복사한 다운스트림 페이지에 버튼이 남는다(누르면 아무 일도 없다).
- AsyncSurface에 별도 prop: 같은 사실을 페이지가 한 번 더 옮겨야 한다.
위험·한계
- 키 없는 결과 불명 화면에는 "변경됨으로 확인"과 목록 새로고침만 남는다.
"적용 안 됨"으로 닫는 길은 없다(근거 없는 확정을 주지 않는 기존 결정).
- 같은 입력으로 submit을 다시 부르는 경로(D-1 replay)는 바꾸지 않았다. 폼은
결과 불명 동안 제출을 막는다.
- hand-built AsyncState(칸 없음)는 지금처럼 버튼을 그린다.
검증
- RED: application-mutation-admission 2건(NEVER: canResend false·resend null·
execute 1회, KEYED: canResend true), async-surface 2건 실패.
- GREEN: tests/unit·integration·component·features·contract 250파일
3,147건 통과. 변이(훅이 키를 보지 않음, 화면이 칸을 보지 않음) 모두 검출.
- check:types, lint, check:architecture, verify:documentation 통과.
Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 0929/03-03
Refs: docs/reviews/2026-11-03-maturity-review/README.md 2.1
문제
기능 하나가 같은 HTTP API를 두 번 적는다. *-api-contract.ts의 V2 행
(defineRestOperation)은 check:registries(FE-REG-API)가 검사하는 선언이고,
contract contribution의 V3 descriptor가 실제로 실행된다. 둘이 어긋나지 않게
http-operation-v2-v3-parity 테스트를 따로 둔다. 048f490으로 V2 클라이언트가
없어져 V2 행을 읽는 실행 코드는 없고, 검사만 남은 두 번째 사본이다. V2 행을
위한 기능별 runtimeSchemas·mappers 레지스트리와 V2 보안 프로필 해석
(resolveRestSecurityProfiles)도 같이 남아 있다. 사용자 지시: 최신 경로 하나만
남기고, 레지스트리 기준선 재승인을 승인했다.
고른 방법
- src/contracts/api-operations.ts를 projectApiOperationRows 하나로 바꿨다.
조립된 contribution의 descriptor마다 operationId, featureId, method, path,
authProfileId, retrySemantics, requestBody, responseBody, responseEnvelope,
request/response/problemSchema(검증기 schemaId) 행을 만든다. FE-REG-API는
같은 export(API_OPERATIONS)를 읽고, governance 정의를 이 필드로 바꿨다.
requestSchema·responseSchema는 그대로 FE-REG-SCHEMA를 참조한다.
- FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)만 받는다.
installed-feature-runtime-registries는 schemas로 스키마 레지스트리를 만들고
FE-REG-API 행을 descriptor에서 뽑는다. RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID를 지웠다.
- realtime snapshot 바인딩은 ApiOperationRow를 받고 method GET과
retrySemantics SAFE·IDEMPOTENT를 본다(V2의 contractVersion·semantics·
replayPolicy 대신).
- rest-profiles.ts에서 V2 행용 provider·CSRF 프로필 해석을 지웠다. V3는 조립
때 auth profile을 검사하고 자격증명 헤더를 프로필로 거른다.
- 참조 기능: reference-api-contract.ts를 reference-schema-metadata.ts로
바꾸고(스키마 행만), V2 runtime codec·operation mapper·레지스트리 mapper를
지웠다. V3 descriptor가 쓰지 않는 NoRequest 스키마 행도 지웠다.
- create:feature: <base>-api-contract.ts 대신 <base>-schema-metadata.ts를
만든다. codec·mapper 레지스트리 행과 그 테스트를 만들지 않는다.
- 레지스트리 기준선을 update:registry-baseline으로 다시 만들고 승인했다
(digest 16f72742…, 승인자 DongHyeonka, 이유에 사용자 승인을 적음).
- 매뉴얼 01·02·reference, starter-experience, 계약 문서의 V2 설명을 지웠다.
버린 대안
- V2 행을 남기고 V3에서 생성하기: 생성 단계와 생성물이 하나 더 생긴다. 행은
실행되지 않으므로 메모리에서 뽑아 검사하면 충분하다.
- 스키마 메타데이터(FE-REG-SCHEMA 행)도 검증기에서 뽑기: boundary·
unknownFieldPolicy·owner는 검증기에 없고, 라우트 스키마도 같은 레지스트리를
쓴다. 이 행은 V2가 아니라 스키마 레지스트리라 남겼다.
위험·한계
- BREAKING: FeatureRuntime 모양, contracts·rest-profiles·loaded-feature-runtimes
의 이름이 바뀌거나 없어졌다. memento-frontend의 memento-web이 V2 행을 쓴다.
옮기는 법은 CHANGELOG에 적는다.
- V2 보안 프로필 일관성 검사(auth "none"과 ANONYMOUS, 쿠키 프로필의 CSRF
모드)가 사라졌다. V3 descriptor에는 그 칸이 없다.
- BoundedPollOperationContract(realtime polling recipe)는 contractVersion: 2
필드를 갖지만 자체 계약이라 바꾸지 않았다.
검증
- check:types, lint, check:architecture, check:registries(11 registries PASS,
compatibility=none), check:ci, check:diagnostics, check:adapter-inventory,
verify:documentation 통과.
- test:unit 2,566(새 tests/unit/api-operation-rows.test.ts 3건 포함),
test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 99 통과.
- tests/unit/second-api-feature-registries.test.ts: V3 descriptor만 가진 두
번째 기능을 복사본에 넣으면 기준선을 고치지 않고 check:registries가 통과한다.
- check:bundle 통과. 초기 JS 201,598 → 200,911 B.
- test:feature-scaffold 16개, test:sample-removal 23개 검사 통과.
BREAKING CHANGE: FeatureRuntime이 apiContract 대신 schemas를 받는다.
defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations,
validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS,
createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles,
validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile,
loaded-feature-runtimes의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY,
REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID가 없어졌다. 기능은
operation을 contract contribution에만 적고, schemas 행을 feature-runtime에
넘긴다.
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.
고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
legacy-http-credential-authority, bounded-json-compatibility,
request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
경로를 V3 파일로 바꿨다.
버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.
위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
커밋에서 지우지 않았다. 다음 커밋이 지운다.
검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
check:adapter-inventory(140 files), check:diagnostics, check:registries,
check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).
BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로
싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고,
헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는
보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만
넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조"
줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를
싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다.
고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미
했다.
- V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드
sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를
싣는다. observation의 correlationId와 같은 값이다.
- 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다.
- 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩.
버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는
metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가
이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다.
위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을
조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안
컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로
두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은
이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼).
검증:
- RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS
200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수
없습니다."는 보이지만 "Unable to find an element with the text: 지원
참조: 29d7f444-…"로 실패.
- GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id).
tests/features·unit·integration·component 242 files 2975 tests,
tests/contract·runtime-schema·architecture 13 files 109 tests 통과.
tsc app·test, eslint(바꾼 파일), verify-documentation-readiness,
check-adapter-inventory, check-registries 통과.
Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04
The runbook still listed the auth fail-close, total deadline and bounded
decoder as not implemented and said an unauthenticated request could be
sent. Section 1 is now a status table with code locations, 5.1 and 6.0
describe V3, and 6.3 points at the same-key resend and its limits.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
V3 read the response x-correlation-id and dropped it, and untraced requests
sent no id, so a support reference could not be matched to a server log.
Each logical execution now sends one x-correlation-id; failures carry the
echoed value as requestId and diagnostics record it as correlation_id.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>