From 3b62ccd5dbe501d3eabb0ecd9f7f2963df685496 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 22:10:05 +0900 Subject: [PATCH] =?UTF-8?q?fix(registry):=20=EC=9D=91=EB=8B=B5=20=EC=8A=A4?= =?UTF-8?q?=ED=82=A4=EB=A7=88=20=ED=96=89=EC=9D=84=20REJECT=5FUNKNOWN?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EC=A2=81=ED=9E=88=EB=A9=B4=20breaking?= =?UTF-8?q?=EC=9C=BC=EB=A1=9C=20=EB=B3=B8=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의 `unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면 check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03 수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에 필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서 FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다. 고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로 바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향 (REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은 그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지 증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두 기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다. 리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다. 위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘 (src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도 고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를 REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿 스냅샷은 기준선과 같아 결과는 none 그대로다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts 리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를 다시 적용하면 check:registries가 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy: response-reader-narrowed`로 실패해야 한다. Refs: 1105/07-02 --- docs/contracts/compatibility.md | 5 ++ docs/manual/01-add-a-feature.md | 1 + scripts/lib/registry-compatibility.ts | 25 ++++++++++ tests/unit/registry-compatibility.test.ts | 60 +++++++++++++++++++++++ 4 files changed, 91 insertions(+) diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 5d1337b2..ce4d99c5 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -30,6 +30,11 @@ reader that accepts it must ship before any writer sends it. | Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `decodeTransportFailure` in `src/adapters/browser-rpc/browser-rpc-runtime.ts` | | Persisted client storage | versioned key; incompatible value discarded | use a new key version | `defineStorageKey` in `src/contracts/storage-keys.ts` | +Turning a response DTO strict changes its row in this table. `check:registries` +grades it as breaking (`response-reader-narrowed`) when the FE-REG-SCHEMA row +of a `RESPONSE` schema goes from `STRIP_UNKNOWN` to `REJECT_UNKNOWN`, so the +change needs registry evidence (1105/07-02). + `CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids vary per build because each downstream project installs its own features, and one shared config document may cover several builds. The capability set is diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md index 6128b020..442978a1 100644 --- a/docs/manual/01-add-a-feature.md +++ b/docs/manual/01-add-a-feature.md @@ -539,6 +539,7 @@ projectRequest: (input) => Object.freeze({ - 행을 **빼거나** breaking 칸을 **바꾸면** breaking 변경이다. breaking 칸은 `config/contracts/registry-governance.json`의 `breakingFields`다. 배열 칸에서 값을 빼는 것도 breaking이다. - FE-REG-API 예: 생성 API의 `acceptedStatuses`를 `[200, 201]`에서 `[201]`로 줄이거나, `problemSchema`를 바꾸거나, 검증기를 `unvalidatedPayload`로 바꾸면(`unvalidated` 칸) breaking이다. - status를 더하는 것, 바이트 상한·마감·`retryBudget`·`traffic`·`commandEffect`·`commandRecovery`를 바꾸는 것은 behavior-change다. 통과하지만 스냅샷 diff(`artifacts/quality/registries.json`의 `compatibility.changes`)에 남는다. PR에서 본다. + - FE-REG-SCHEMA 예: 응답 DTO를 `.strict()`로 바꾸고 스키마 메타 행을 `REJECT_UNKNOWN`으로 고치면(`direction: "RESPONSE"`) `response-reader-narrowed` breaking이다. 백엔드가 응답에 필드를 하나 더하면 그 API가 `SCHEMA_MISMATCH`로 실패하기 때문이다. 반대(`REJECT_UNKNOWN`→`STRIP_UNKNOWN`)와 요청 행은 behavior-change다. - breaking 변경이면 둘 중 하나를 한다. - `REGISTRY_BASELINE_OWNER`, `REGISTRY_BASELINE_REASON`을 주고 `corepack pnpm update:registry-baseline`을 돌린다. - 또는 `config/contracts/registry-change-evidence.json`에 항목을 더한다. 칸 설명은 `docs/operations/ci-quality-gates.md`에 있다. diff --git a/scripts/lib/registry-compatibility.ts b/scripts/lib/registry-compatibility.ts index c69fb510..5d20de5a 100644 --- a/scripts/lib/registry-compatibility.ts +++ b/scripts/lib/registry-compatibility.ts @@ -138,6 +138,28 @@ function onlyExtendsAllowedValues(before: unknown, after: unknown): boolean { }); } +/** + * 1105/07-02. A response schema row that starts rejecting unknown keys + * narrows what the frontend accepts, as removing an accepted status does in + * FE-REG-API: every response the backend extends with a field then fails with + * SCHEMA_MISMATCH. That one direction is breaking. REJECT -> STRIP widens the + * reader, and a REQUEST row's policy is checked against what the frontend + * itself sends; both stay behavior-change, as does any other policy change. + */ +function narrowsResponseReader( + field: string, + before: unknown, + after: unknown, + row: Readonly>, +): boolean { + return ( + field === "unknownFieldPolicy" && + before !== "REJECT_UNKNOWN" && + after === "REJECT_UNKNOWN" && + row.direction === "RESPONSE" + ); +} + function changeId( registryId: string, rowName: string, @@ -343,6 +365,9 @@ export function diffRegistrySnapshots( } else if (keyedSetFields.has(field) && Array.isArray(afterValue)) { kind = "set-items-added"; changeImpact = "additive"; + } else if (narrowsResponseReader(field, beforeValue, afterValue, afterRow)) { + kind = "response-reader-narrowed"; + changeImpact = "breaking"; } else { kind = "field-changed"; changeImpact = breakingFields.has(field) diff --git a/tests/unit/registry-compatibility.test.ts b/tests/unit/registry-compatibility.test.ts index 04236396..b18768c8 100644 --- a/tests/unit/registry-compatibility.test.ts +++ b/tests/unit/registry-compatibility.test.ts @@ -123,6 +123,66 @@ describe("registry compatibility evidence", () => { }); }); + // 1105/07-02. A response schema that starts rejecting unknown keys fails + // every response the backend extends with a field, so it is graded like + // removing an accepted status. Widening, and a request row the frontend + // fills itself, stay behavior-change. The rows are FE-REG-SCHEMA's shape + // (src/contracts/schema-registry.ts), not the committed baseline, which + // loses the reference rows when the sample is removed. + describe("a schema row's unknown-key policy", () => { + const contract = { breakingFields: ["schemaId", "boundary", "runtime"] }; + function schemas(direction: "REQUEST" | "RESPONSE", unknownFieldPolicy: string) { + return { + schemaVersion: 2, + registries: [ + { + registryId: "FE-REG-SCHEMA", + contract, + rows: { + Payload: { + schemaId: "Payload", + boundary: direction === "RESPONSE" ? "api-response" : "api-request", + direction, + owner: "fixture", + runtime: "zod", + schemaVersion: 1, + unknownFieldPolicy, + }, + }, + }, + ], + }; + } + + it.each([ + ["a response narrowed to REJECT_UNKNOWN", "RESPONSE", "STRIP_UNKNOWN", "REJECT_UNKNOWN", "response-reader-narrowed", "breaking"], + ["a response widened to STRIP_UNKNOWN", "RESPONSE", "REJECT_UNKNOWN", "STRIP_UNKNOWN", "field-changed", "behavior-change"], + ["a request narrowed to REJECT_UNKNOWN", "REQUEST", "STRIP_UNKNOWN", "REJECT_UNKNOWN", "field-changed", "behavior-change"], + ["a request widened to STRIP_UNKNOWN", "REQUEST", "REJECT_UNKNOWN", "STRIP_UNKNOWN", "field-changed", "behavior-change"], + ] as const)("grades %s", (_label, direction, before, after, kind, impact) => { + const diff = diffRegistrySnapshots( + schemas(direction, before), + schemas(direction, after), + ); + expect(diff.changes.map((change) => [change.changeId, change.impact])).toEqual([ + [`FE-REG-SCHEMA:Payload:unknownFieldPolicy:${kind}`, impact], + ]); + expect(diff.impact).toBe(impact); + }); + + it("asks for evidence when a response row is narrowed", () => { + const diff = diffRegistrySnapshots( + schemas("RESPONSE", "STRIP_UNKNOWN"), + schemas("RESPONSE", "REJECT_UNKNOWN"), + ); + expect( + validateBreakingEvidence(diff, { schemaVersion: 1, changes: [] }).failures, + ).toEqual([ + "breaking change missing evidence: FE-REG-SCHEMA:Payload:unknownFieldPolicy:response-reader-narrowed", + ]); + }); + }); + // 1101/16-01 (decision 1). Every feature with server state adds a topic, so // adding one must not need a new baseline. The committed baseline is used // as it stands: after the sample's removal its graph may be empty.