fix(registry): 응답 스키마 행을 REJECT_UNKNOWN으로 좁히면 breaking으로 본다

문제: 응답 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
This commit is contained in:
DongHyeonka
2026-11-05 22:10:05 +09:00
parent 2e1acb1f21
commit 3b62ccd5db
4 changed files with 91 additions and 0 deletions
+25
View File
@@ -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<Record<string, unknown>>,
): 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)