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:
@@ -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
|
||||
|
||||
@@ -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`에 있다.
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user