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.