From fbd93ac9a80ad139a8963a7b1f1a9fb7fda4a272 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Tue, 3 Nov 2026 20:34:23 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B1=B0=EC=A0=88=20=EC=A0=81=EC=9A=A9?= =?UTF-8?q?=20=EC=97=AC=EB=B6=80=EB=A5=BC=20=EB=B0=B1=EC=97=94=EB=93=9C=20?= =?UTF-8?q?=EA=B8=B0=EC=A4=80=20=ED=91=9C=EB=A1=9C=20=EB=B0=94=EA=BE=BC=20?= =?UTF-8?q?=EA=B2=83=EC=9D=84=20=EB=A7=A4=EB=89=B4=EC=96=BC=EA=B3=BC=20?= =?UTF-8?q?=EA=B8=B0=EB=A1=9D=EC=97=90=20=EC=A0=81=EB=8A=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 3261208이 V2·V3의 거절 판정을 계약 문서 6.1절 표로 바꿨다. 매뉴얼 02 4절은 아직 "422 전부와 필드 목록 400은 적용 안 됨, 그 밖은 classifyProblem"으로 적고, 리뷰 README 14.6 판정 표, 14.4의 검증 거절 줄, CHANGELOG의 7db32e1 행도 같은 옛 규칙을 적는다. 고른 방법 - 매뉴얼 02 4절: 표의 세 code(적용 안 됨)와 그 밖의 400·409·422(결과 불명), 근거가 계약 문서 6.1절이라는 것, 쓰기 전 거절 code를 새로 만들 때 두 곳을 함께 고친다는 것. - 매뉴얼 01 3단계: 실행기가 정하는 status 범위를 400·409·422와 503으로 적었다. - 리뷰 README 14.6: 판정 표를 새 표로 바꾸고 처음 규칙을 한 줄로 남겼다. "6.1 표 반영" 단락에 바뀐 것, 버린 대안, 위험, RED·GREEN, 게이트를 적었다. 14.4 줄에 바뀐 판정을 덧붙였다. - CHANGELOG: [계약] 행 하나를 더하고 02e35d2·7db32e1 행이 그 행을 가리키게 했다. 위험·한계 - 계약 문서 6.1절은 오케스트레이터 브랜치(ed0e4b1)에만 있다. 이 브랜치의 매뉴얼은 그 절을 가리키지만, 합치기 전에는 그 절이 없다. - 프론트 계약 문서 4.2절 "422 field validation" 행은 고치지 않았다. 검증 - verify:documentation PASS_SCOPED. - tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.4, 14.6 --- CHANGELOG.md | 5 +-- docs/manual/01-add-a-feature.md | 2 +- docs/manual/02-decision-tables.md | 7 ++-- .../2026-11-01-maturity-review/README.md | 33 ++++++++++++++----- 4 files changed, 33 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4a29f83c..95a8435b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -73,8 +73,9 @@ | [계약] | `CREDENTIAL_HEADER_NAMES`에 `x-xsrf-token`을 더했다. 짝 백엔드(Spring `CookieCsrfTokenRepository`)의 기본 CSRF 헤더다 (1101/09-02) | `src/contracts/rest-profiles.ts` | `183a4a3` | | [계약] | V2 Envelope에 `data` 키가 없으면 `null`로 읽는다. `meta.requestId`·`traceId`는 선택이다. 짝 백엔드는 null 필드를 생략한다 (백엔드 리뷰 1101/02-02) | `src/adapters/http/schema-registry.ts` | `969979d` | | [계약] | V2: 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`가 `effect: "NOT_APPLIED"`와 진단 reason을 싣는다. 409의 `Retry-After`는 `retryAfterMs`로 실린다(V3 PROBLEM 실패도 같다). 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다. 응답 code의 정본은 백엔드 템플릿 `docs/web/http-contract.md` §2다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/adapters/http/feature-http-binding.ts`, `src/presentation/adapters/query/application-query.ts` | `93782b0`, `47fec5c` | -| [계약] | V2 클라이언트가 짝 백엔드의 400 `VALIDATION_FAILED`(필드 목록 `details: [{field, code, message}]`)를 422와 같은 `VALIDATION_REJECTED`·`validationIssues`로 읽는다. 필드 검증 거절(422와 이 400)은 `effect: "NOT_APPLIED"`다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/contracts/errors.ts` | `02e35d2`, `64e98ee` | -| [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 멱등성 거절·처리 중 409·503 `IDEMPOTENCY_UNAVAILABLE`·필드 검증 400은 실행기가 V2와 같은 표로 먼저 판정하고, `mapProblem`이 답하지 않으면 V2와 같은 kind·code·필드 오류로 읽는다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가만, exhaustive switch는 분기를 더한다). Envelope operation의 진단은 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`에 V2와 같은 `reason`을 싣는다(`HttpDiagnosticReason`에 두 값 추가). `create:feature`가 만든 기능은 이 값을 선언하고 problem 스키마가 Envelope `error`다. 값이 없는 descriptor(참조 기능 포함)는 그대로다. 이전에 만든 기능을 짝 백엔드에 붙이려면 contribution에 `responseEnvelope: "ENVELOPE_V1" as const`를 더하고 problem 스키마를 `error` 모양(`code` 필수)으로 바꾼다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` | +| [계약] | V2 클라이언트가 짝 백엔드의 400 `VALIDATION_FAILED`(필드 목록 `details: [{field, code, message}]`)를 422와 같은 `VALIDATION_REJECTED`·`validationIssues`로 읽는다. 필드 검증 거절(422와 이 400)은 `effect: "NOT_APPLIED"`다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다. 적용 여부는 다음 행이 다시 정했다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/contracts/errors.ts` | `02e35d2`, `64e98ee` | +| [계약] | 거절의 적용 여부를 계약 문서 6.1절 표(백엔드 `5786126c` 코드 기준)로 정한다. V2와 V3 Envelope operation이 같은 표(`src/adapters/http/backend-envelope.ts`)를 쓴다. 적용 안 됨은 400 `VALIDATION_FAILED`(details 모양과 상관없음)·400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`뿐이고, 그 밖의 400·409·422는 결과 불명이다. V2에서 `IDEMPOTENT_REQUEST_MISMATCH`가 아닌 422는 이제 결과 불명이라 폼에서 값을 고쳐도 다시 저장할 수 없다. 필드 검증을 422로 보내는 백엔드를 쓰는 프로젝트는 영향을 받는다. 필드 목록 없는 400 `VALIDATION_FAILED`는 바로 다시 저장할 수 있다. V3 Envelope operation의 400·409·422는 `classifyProblem` 대신 이 표가 정한다 (1101/14.4) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/client.ts`, `src/adapters/http/http-execution-v3.ts` | `3261208` | +| [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 적용 여부는 실행기가 V2와 같은 표로 정하고(아래 6.1 표 행), `mapProblem`이 답하지 않으면 V2와 같은 kind·code·필드 오류로 읽는다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가만, exhaustive switch는 분기를 더한다). Envelope operation의 진단은 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`에 V2와 같은 `reason`을 싣는다(`HttpDiagnosticReason`에 두 값 추가). `create:feature`가 만든 기능은 이 값을 선언하고 problem 스키마가 Envelope `error`다. 값이 없는 descriptor(참조 기능 포함)는 그대로다. 이전에 만든 기능을 짝 백엔드에 붙이려면 contribution에 `responseEnvelope: "ENVELOPE_V1" as const`를 더하고 problem 스키마를 `error` 모양(`code` 필수)으로 바꾼다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` | | [계약] | V3 실행 결과에 선택 필드 `sentRequestId`가 생겼다. 서버가 `x-correlation-id`를 돌려주지 않으면 `AppFailure.requestId`는 보낸 값이다. 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (0929/03-04) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts` | `849d000` | | [계약] | `ResumableUploadPort.upload()`: part 발급(BFF)이 401/403으로 거절하면 recovery가 `RESUME` 대신 `NONE`(`retryable: false`)이다. 세션 만료·권한 회수라 재인증 전에는 다시 불러도 같다. object store PUT 403은 그대로 `RESUME`이다 (0929/01-01) | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | `c5f87aa` | | [계약] | realtime stream coordinator의 effect·recovery·close 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`/`APPLY`, `PROVIDER_UNAVAILABLE`/`RECOVER`, `PROVIDER_UNAVAILABLE`/`CLOSE`로 나온다. `RealtimeObservation.reason`도 같다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts` | `1196b86` | diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index d4253183..2a6c6858 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -202,7 +202,7 @@ corepack pnpm create:feature invoice-feature - 백엔드는 값이 null인 필드를 키째 뺀다. `data` 키가 없으면 `null`로 읽는다. DTO 안에서 null일 수 있는 필드는 스키마에서 `.optional()`로 받는다. - problem 스키마(`-schemas.ts`의 `ProblemSchema`)는 Envelope의 `error` 객체다. 분기는 `code`로 한다. `message`는 버린다. -- 백엔드가 operation과 상관없이 정한 판정(멱등성 거절, 처리 중 409, 필드 검증 400)은 실행기가 먼저 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. +- 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`가 적용됐는지는 실행기가 백엔드 기준 표로 정한다. 목록은 [02 결정표 4절](02-decision-tables.md#4-결과-불명)이다. - `mapProblem`이 없거나 `undefined`를 돌려주면 V2 클라이언트와 같은 kind·code·필드 오류로 읽는다(`src/adapters/http/backend-envelope.ts`). - 바이트 상한(`responseByteLimit`)과 구조 예산은 Envelope 전체에 걸린다. V2 `maxResponseBytes`와 같은 값이다. - MSW: `createHttpScenarioHandler`는 descriptor의 `responseEnvelope`를 보고 Envelope로 답한다(`tests/mocks/handlers/http-scenarios.ts`). 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 검사한다. diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 42e977fa..61ceb487 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -141,9 +141,10 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 - 같은 status라도 code로 나뉠 수 있다. 예: 409 중 "처리 중"은 `MAYBE_APPLIED`여야 한다. `NOT_APPLIED`로 보면 다음 저장이 새 키를 만들어 같은 작업이 두 번 적용된다. - 401·403·429는 문제 응답 본문을 읽기 전에 status로 나뉜다. 서버가 상태를 안 바꾼다고 보장하면 `classifyStatus`로 `NOT_APPLIED`를 돌려준다. 없으면 `MAYBE_APPLIED`다. - 문제 응답 본문이 기능의 problem 스키마를 통과하지 못하면 `classifyProblem`을 부르지 않는다. 쓰기는 `MAYBE_APPLIED`가 된다(`src/adapters/http/http-execution-v3.ts`). -- `responseEnvelope: "ENVELOPE_V1"`인 operation은 짝 백엔드가 operation과 상관없이 정한 판정을 실행기가 먼저 적용한다(`src/adapters/http/backend-envelope.ts`의 `envelopeFailureEffect`). `classifyProblem`은 그 밖의 응답만 받는다. - - `NOT_APPLIED`: 422, 필드 목록이 있는 400 `VALIDATION_FAILED`, 400 `IDEMPOTENCY_KEY_INVALID` - - `MAYBE_APPLIED`: 409 `IDEMPOTENT_IN_FLIGHT`, 503 `IDEMPOTENCY_UNAVAILABLE`. `classifyProblem`이 `NOT_APPLIED`라고 해도 바뀌지 않는다 +- `responseEnvelope: "ENVELOPE_V1"`인 operation은 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 판정을 실행기가 백엔드 기준 표로 정한다(`src/adapters/http/backend-envelope.ts`의 `REFUSED_BEFORE_WRITE`). 표의 근거는 [계약 문서](../architecture/backend-api-and-server-state-contract.md) 6.1절이다(백엔드 코드에서 code마다 쓰기 전·후를 읽은 결과). `classifyProblem`은 그 밖의 status만 받고, 다르게 답해도 표의 판정은 바뀌지 않는다. V2 클라이언트도 같은 표를 쓴다. + - `NOT_APPLIED`(쓰기 전 거절): 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH` + - `MAYBE_APPLIED`: 그 밖의 400·409·422. 409 `IDEMPOTENT_IN_FLIGHT`, `BAD_PARAMETER`, 도메인 code, fileserver의 422가 여기 든다. 그리고 503 `IDEMPOTENCY_UNAVAILABLE` + - 짝 백엔드가 쓰기 전에 거절하는 code를 새로 만들면 계약 문서 6.1절과 이 표를 함께 고친다. 표에 없으면 `MAYBE_APPLIED`다 **503 `IDEMPOTENCY_UNAVAILABLE`는 `NOT_APPLIED`로 분류하지 않는다.** diff --git a/docs/reviews/2026-11-01-maturity-review/README.md b/docs/reviews/2026-11-01-maturity-review/README.md index 16fb43a3..e210e4d0 100644 --- a/docs/reviews/2026-11-01-maturity-review/README.md +++ b/docs/reviews/2026-11-01-maturity-review/README.md @@ -507,7 +507,7 @@ ### 14.4 남은 문제와 위험 - 백엔드 응답 code 정본(`docs/web/http-contract.md`)이 백엔드 repo에 아직 커밋되지 않았다. 프론트 계약 문서는 SHA 대신 결정일로 기준을 적었다. -- "검증 거절은 적용 안 됨" 판정: 백엔드 application 층이 쓰기 뒤 `VALIDATION_FAILED`를 던지면 틀린다. 필드 목록 없는 400 `VALIDATION_FAILED`와 그 밖의 400·409는 여전히 결과 불명이다. +- "검증 거절은 적용 안 됨" 판정: 백엔드 application 층이 쓰기 뒤 `VALIDATION_FAILED`를 던지면 틀린다. 필드 목록 없는 400 `VALIDATION_FAILED`와 그 밖의 400·409는 여전히 결과 불명이다. (2026-11-03: 판정을 계약 문서 6.1절 표로 바꿨다. `VALIDATION_FAILED`는 details 모양과 상관없이 적용 안 됨, 그 밖의 400·409·422는 결과 불명. 14.6) - 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 기본 문구가 나온다. V3 실행기 진단에 problem code가 없다. (2026-11-03: Envelope operation은 V2와 같은 멱등성 거절 `reason`을 싣는다. 14.6) - 09-03: 레이아웃의 skip link·`
`은 실행 검사가 없다. 플랫폼 라우트와 같은 경로의 기능 라우트를 검사하지 않는다. - 09-02 이식: env.ts의 FE-REG-ENV 행과 tech-log의 부트 전 BFF owner 설치는 아직 템플릿 파일 수정이 필요하다. 다운스트림 이식은 하지 않았다. @@ -545,21 +545,38 @@ **V2와 같은 판정**: V2 `client.ts`가 갖고 있던 멱등성 거절 표, 필드 검증 판정, gateway status 규칙을 `backend-envelope.ts`로 옮겼다. V2, V3 실행기, feature binding이 이 파일 하나를 읽는다. `tests/integration/http-execution-v3-envelope.test.ts`가 같은 응답을 V2와 V3에 보내 kind·code·httpStatus·effect·retryAfterMs·validationIssues를 비교한다. -| 응답 (쓰기, `classifyProblem`은 모두 `MAYBE_APPLIED`) | kind | effect | 그 밖 | +처음(`7db32e1`)에는 422 전부와 필드 목록이 있는 400 `VALIDATION_FAILED`를 적용 안 됨으로 보고, 그 밖의 400·409·422는 `classifyProblem`에 맡겼다. 뒤의 "6.1 표 반영"에서 아래 표로 바꿨다. + +| 응답 (쓰기) | kind | effect | 그 밖 | |---|---|---|---| -| 409 `IDEMPOTENT_IN_FLIGHT`, `Retry-After: 2` | `CONFLICT` | `MAYBE_APPLIED`. `classifyProblem`이 `NOT_APPLIED`라고 해도 바뀌지 않는다 | `retryAfterMs` 2,000 | -| 422 `IDEMPOTENT_REQUEST_MISMATCH` | `VALIDATION_REJECTED` | `NOT_APPLIED` | | -| 400 `IDEMPOTENCY_KEY_INVALID` | `UNKNOWN_CLIENT_FAILURE` | `NOT_APPLIED` | | -| 503 `IDEMPOTENCY_UNAVAILABLE` | `SERVER_FAILURE` | `MAYBE_APPLIED`. 위와 같이 고정 | | | 400 `VALIDATION_FAILED` + 필드 목록 | `VALIDATION_REJECTED` | `NOT_APPLIED` | `validationIssues` | -| 400 `VALIDATION_FAILED` + `{cause}` | `UNKNOWN_CLIENT_FAILURE` | `classifyProblem` | | -| 그 밖의 실패 (예: 409 도메인 충돌) | V2와 같은 status 규칙 | `classifyProblem` | | +| 400 `VALIDATION_FAILED` + `{cause}` / details 없음 / `{field, code}` | `UNKNOWN_CLIENT_FAILURE` | `NOT_APPLIED` | | +| 400 `IDEMPOTENCY_KEY_INVALID` | `UNKNOWN_CLIENT_FAILURE` | `NOT_APPLIED` | | +| 422 `IDEMPOTENT_REQUEST_MISMATCH` | `VALIDATION_REJECTED` | `NOT_APPLIED` | | +| 409 `IDEMPOTENT_IN_FLIGHT`, `Retry-After: 2` | `CONFLICT` | `MAYBE_APPLIED` | `retryAfterMs` 2,000 | +| 그 밖의 400·409·422 (`BAD_PARAMETER`, 도메인 409, fileserver 422 `INTEGRITY_MISMATCH` 등) | V2와 같은 status 규칙 | `MAYBE_APPLIED` | | +| 503 `IDEMPOTENCY_UNAVAILABLE` | `SERVER_FAILURE` | `MAYBE_APPLIED` | | +| 그 밖의 status (예: 404) | V2와 같은 status 규칙 | V2는 effect 없음(결과 불명), V3는 `classifyProblem` | | + +Envelope operation에서는 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 effect를 이 표가 정한다. `classifyProblem`이 `NOT_APPLIED`라고 해도 바뀌지 않는다. - 바이트 상한: 성공 Envelope는 본문 전체를 `responseByteLimit`(V2 `maxResponseBytes`와 같은 값)로 센다. 실패 Envelope는 min(64 KiB, `responseByteLimit`)이다. 구조 예산도 Envelope 전체에 건다. - `mapProblem`이 없거나 `undefined`를 돌려주면 V2와 같은 kind·code·필드 오류로 읽는다. - 성공 status인데 Envelope가 아닌 본문(맨 DTO, 실패 Envelope, `error`가 붙은 성공)은 새 위반 `ENVELOPE_MISMATCH`이고 `AppFailure.kind`도 `ENVELOPE_MISMATCH`다(V2와 같다). - MSW `createHttpScenarioHandler`가 descriptor를 보고 Envelope로 답한다. 생성된 `tests/features//-http-gateway.test.ts`는 백엔드 본문을 그대로 적어 성공·null 생략·실패·필드 검증·맨 DTO 거절을 검사한다. +**6.1 표 반영** (2026-11-03, `3261208`, 오케스트레이터 요청) + +계약 문서 6.1절(오케스트레이터 브랜치 `ed0e4b1`, 백엔드 `5786126c` 코드 기준)이 code마다 쓰기 전·후를 정했다. V2와 V3가 따로 들던 규칙을 `backend-envelope.ts`의 표 `REFUSED_BEFORE_WRITE` 하나로 바꿨다. + +- V2: 필드 목록 없는 400 `VALIDATION_FAILED`(`{cause}`, details 없음, `{field, code}`)가 `NOT_APPLIED`가 됐다(kind는 `UNKNOWN_CLIENT_FAILURE` 그대로). 422는 `IDEMPOTENT_REQUEST_MISMATCH`만 `NOT_APPLIED`이고, 다른 422는 effect가 없다(결과 불명). 폼에 필드 오류는 보이지만 저장 버튼은 꺼진 채로 남는다. +- V3 Envelope: 400·409·422는 표가 정한다. 처음에는 도메인 409 같은 code를 `classifyProblem`에 맡겼는데, 6.1절은 그 code들이 쓰기 뒤에도 나온다고 적으므로 표 밖은 `MAYBE_APPLIED`로 고정했다. +- V3 참조 기능 분류기(400·422 전부 `NOT_APPLIED`)는 고치지 않았다. 참조 기능은 Envelope operation이 아니고 fixture도 problem details라 이 표를 쓰지 않는다. 짝 백엔드에 붙일 때 `classifyProblem` 대신 이 표가 적용된다. +- RED: 바뀐 행 8건 실패(V2 `{cause}`·details 없음·`{field, code}`의 effect 3건, "unrelated 422" 진단 1건, V3 고정 판정 2건, 폼 2건). GREEN: 같은 파일들 128건 통과. +- 게이트(`3261208`): `check:types`, `lint`, `check:architecture`, `check:diagnostics`, `check:ci`, `check:registries`, `check:adapter-inventory`, `verify:documentation` 통과. `test:unit` 2,604 / `test:integration` 209 / `test:component` 245 / features·contract 124건 통과. `check:bundle` 203,354 / 204,800 B. `test:feature-scaffold` 16개, `test:sample-removal` 23개 검사 통과. `f3b87b3`에서 다시 돌린 `test:feature-scaffold`는 한 번 실패했다. 실패한 것은 HTTP와 무관한 `tests/unit/task3-selective-integration.test.ts`("provider scope EOF close timed out")였고, 그때 호스트 load가 약 20이었다. 단독으로 3회 돌리면 3회 통과하고, `3261208` 실행에서도 통과했다 +- 버린 대안: (1) V2·V3에 표를 따로 두기: 두 번째 표가 다시 갈라진다. (2) 표 밖 400·409·422를 `classifyProblem`에 맡기기: 6.1절이 "표에 없는 400·409·422는 `MAYBE_APPLIED`"로 정했고, 참조 분류기처럼 400·422를 모두 `NOT_APPLIED`로 보는 패키지가 다음 저장에 새 키를 쓰게 한다. (3) 422를 필드 검증으로 남기기: 짝 백엔드는 필드 검증을 400으로 보내고, fileserver 422는 레코드를 쓴 뒤 던진다. +- 위험: 필드 검증을 422로 보내는 다른 백엔드를 V2로 쓰는 프로젝트는 422 뒤에 다시 저장할 수 없게 된다(결과 불명 화면). 프론트 계약 문서 4.2절의 "`422` field validation" 행과 어긋난다. 그 줄은 이 브랜치 범위 밖이라 고치지 않았다. + **V2와 남은 차이** (의도한 것): - 64 KiB보다 크고 `maxResponseBytes` 이하인 실패 Envelope는 V2만 읽는다. V3 problem 상한(scale-architecture.md §7.3)은 올리지 않았다. 짝 백엔드에서 이 크기가 나오는 실패는 bulk 부분 실패뿐이고, 프론트에 bulk 사용처가 없다.