fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)

문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.

고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
  (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
  field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
  선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
  포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
  새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
  contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
  matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
  registry-contract-extension(additive)을 더하고 artifact id 목록에도
  넣었다.

버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
  길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
  레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
  기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
  breaking에 남겼다.

위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
  꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
  paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
  behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
  (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
  0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
  바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
  라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
  계속 breaking으로 남는다.

검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
  (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
  kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
  nullable-field-cleared actual breaking, registry-contract-extension
  actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
  second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
  check-registries "11 registries PASS"(남은 breaking은
  REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
  ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
  exit=126 환경 문제로 이 변경과 무관하게 실패).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
This commit is contained in:
DongHyeonka
2026-11-01 22:35:54 +09:00
parent fc303d89bc
commit 82c9e594ff
5 changed files with 205 additions and 23 deletions
+3 -19
View File
@@ -10,6 +10,8 @@ import { pathToFileURL } from "node:url";
import {
canonicalizeRegistryValue,
diffRegistrySnapshots,
matchesDeclaredType,
registryRuntimeType,
registrySnapshotDigest,
validateBreakingEvidence,
verifyRegistryBaselineApproval,
@@ -140,24 +142,6 @@ async function resolveRegistrySource(
return candidates[0] ?? null;
}
function runtimeType(value: unknown): string {
if (value === null) return "null";
if (Array.isArray(value)) return "array";
if (Number.isInteger(value)) return "integer";
return typeof value;
}
function matchesDeclaredType(value: unknown, declaration: string): boolean {
const actual = runtimeType(value);
return declaration
.split("|")
.some(
(candidate) =>
candidate === actual ||
(candidate === "number" && actual === "integer"),
);
}
type FieldLookup = Readonly<{
found: boolean;
value: unknown;
@@ -417,7 +401,7 @@ for (const specification of governance.registries) {
)
) {
failures.push(
`${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${runtimeType(lookupField(row, field).value)}`,
`${specification.registryId}.${rowName}.${field} expected ${declaredType}, received ${registryRuntimeType(lookupField(row, field).value)}`,
);
}
}
+2
View File
@@ -1211,6 +1211,8 @@ const REGISTRY_COMPATIBILITY_FIXTURE_IDS = [
"field-type-narrowing",
"route-path-change",
"registry-contract-narrowing",
"nullable-field-cleared",
"registry-contract-extension",
"breaking-evidence-required",
"tampered-baseline-digest",
] as const;
+79 -4
View File
@@ -80,6 +80,64 @@ function valueType(value: unknown): string {
return typeof value;
}
/** The governance `fieldTypes` vocabulary: `integer` is its own name. */
export function registryRuntimeType(value: unknown): string {
if (Number.isInteger(value)) return "integer";
return valueType(value);
}
/** `declaration` is a governance field type such as `string|null`. */
export function matchesDeclaredType(value: unknown, declaration: string): boolean {
const actual = registryRuntimeType(value);
return declaration
.split("|")
.some(
(candidate) =>
candidate === actual ||
(candidate === "number" && actual === "integer"),
);
}
/**
* 0929/07-02. A null on one side and a value on the other is a change inside
* the field's declared type when that type admits both (`string|null`), not a
* change of type: hiding a navigation label is graded like renaming it.
*/
function isDeclaredNullableChange(
before: unknown,
after: unknown,
declaration: unknown,
): boolean {
return (
typeof declaration === "string" &&
(before === null || after === null) &&
matchesDeclaredType(before, declaration) &&
matchesDeclaredType(after, declaration)
);
}
/**
* 0929/07-02. Every field keeps its restriction and every value it allowed:
* rows valid before stay valid. A new, dropped or narrowed restriction is
* still breaking.
*/
function onlyExtendsAllowedValues(before: unknown, after: unknown): boolean {
if (!before || !after || typeof before !== "object" || typeof after !== "object") {
return false;
}
const previous = before as Record<string, unknown>;
const current = after as Record<string, unknown>;
const fields = Object.keys(previous);
if (fields.length !== Object.keys(current).length) return false;
return fields.every((field) => {
const allowedBefore = previous[field];
const allowedAfter = current[field];
if (!Array.isArray(allowedBefore) || !Array.isArray(allowedAfter)) return false;
const kept = new Set(allowedAfter.map((value) => canonicalRegistryJson(value)));
return allowedBefore.every((value) => kept.has(canonicalRegistryJson(value)));
});
}
function changeId(
registryId: string,
rowName: string,
@@ -154,19 +212,29 @@ export function diffRegistrySnapshots(
) {
continue;
}
const extendsAllowedValues =
field === "allowedValues" &&
beforeHas &&
afterHas &&
onlyExtendsAllowedValues(beforeValue, afterValue);
const kind = !beforeHas
? "contract-field-added"
: !afterHas
? "contract-field-removed"
: "contract-field-changed";
impact = strongestImpact(impact, "breaking");
: extendsAllowedValues
? "allowed-values-extended"
: "contract-field-changed";
const changeImpact: CompatibilityImpact = extendsAllowedValues
? "additive"
: "breaking";
impact = strongestImpact(impact, changeImpact);
changes.push({
changeId: changeId(registryId, "$contract", field, kind),
registryId,
rowName: "$contract",
field,
kind,
impact: "breaking",
impact: changeImpact,
before: canonicalizeRegistryValue(beforeValue),
after: canonicalizeRegistryValue(afterValue),
});
@@ -175,6 +243,10 @@ export function diffRegistrySnapshots(
const breakingFields = new Set(
(currentContract.breakingFields ?? []) as string[],
);
const fieldTypes = (currentContract.fieldTypes ?? {}) as Record<
string,
unknown
>;
const beforeRows = (previous.rows ?? {}) as Record<
string,
Record<string, unknown>
@@ -234,7 +306,10 @@ export function diffRegistrySnapshots(
} else if (!afterHas) {
kind = "field-removed";
changeImpact = "breaking";
} else if (valueType(beforeValue) !== valueType(afterValue)) {
} else if (
valueType(beforeValue) !== valueType(afterValue) &&
!isDeclaredNullableChange(beforeValue, afterValue, fieldTypes[field])
) {
kind = "field-type-changed";
changeImpact = "breaking";
} else if (
@@ -186,6 +186,66 @@
}
]
}
},
{
"id": "nullable-field-cleared",
"expected": "behavior-change",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"fieldTypes": { "path": "string", "label": "string|null" }
},
"rows": { "A": { "path": "/a", "label": "Home" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"fieldTypes": { "path": "string", "label": "string|null" }
},
"rows": { "A": { "path": "/a", "label": null } }
}
]
}
},
{
"id": "registry-contract-extension",
"expected": "additive",
"before": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"allowedValues": { "kind": ["one"] }
},
"rows": { "A": { "path": "/a", "kind": "one" } }
}
]
},
"after": {
"schemaVersion": 2,
"registries": [
{
"registryId": "FE-REG-TEST",
"contract": {
"breakingFields": ["path"],
"allowedValues": { "kind": ["one", "two"] }
},
"rows": { "A": { "path": "/a", "kind": "one" } }
}
]
}
}
],
"breakingEvidence": {
+61
View File
@@ -60,6 +60,67 @@ describe("registry compatibility evidence", () => {
).toBe("breaking");
});
// 0929/07-02. Changes the governance contract already describes are graded
// by it; anything else stays fail-closed.
describe("changes the declared contract describes", () => {
function registry(
contract: Readonly<Record<string, unknown>>,
rows: Readonly<Record<string, Readonly<Record<string, unknown>>>>,
) {
return {
schemaVersion: 2,
registries: [{ registryId: "FE-REG-TEST", contract, rows }],
};
}
const nullable = {
breakingFields: ["path", "schema"],
fieldTypes: {
path: "string",
label: "string|null",
order: "integer|null",
schema: "string|null",
},
};
it.each([
["a label hidden", { label: "Home" }, { label: null }, "behavior-change", "field-changed"],
["a label shown", { label: null }, { label: "Home" }, "behavior-change", "field-changed"],
["an order set", { order: null }, { order: 2 }, "behavior-change", "field-changed"],
["a nullable breaking field set", { schema: null }, { schema: "Params" }, "breaking", "field-changed"],
["a value outside the declared type", { order: null }, { order: "2" }, "breaking", "field-type-changed"],
])("grades %s by the declared field type", (_label, before, after, impact, kind) => {
const diff = diffRegistrySnapshots(
registry(nullable, { A: { path: "/a", ...before } }),
registry(nullable, { A: { path: "/a", ...after } }),
);
expect(diff.changes.map((change) => [change.kind, change.impact])).toEqual([
[kind, impact],
]);
});
it("keeps a null transition breaking when no field type is declared", () => {
expect(
diffRegistrySnapshots(
registry({ breakingFields: ["path"] }, { A: { path: "/a", label: "Home" } }),
registry({ breakingFields: ["path"] }, { A: { path: "/a", label: null } }),
).impact,
).toBe("breaking");
});
it.each([
["one more allowed value", { kind: ["one"] }, { kind: ["one", "two"] }, "additive"],
["an allowed value removed", { kind: ["one", "two"] }, { kind: ["two", "three"] }, "breaking"],
["a newly restricted field", { kind: ["one"] }, { kind: ["one"], mode: ["a"] }, "breaking"],
["a restriction dropped", { kind: ["one"], mode: ["a"] }, { kind: ["one"] }, "breaking"],
])("grades %s in allowedValues", (_label, before, after, impact) => {
const diff = diffRegistrySnapshots(
registry({ breakingFields: ["path"], allowedValues: before }, { A: { path: "/a" } }),
registry({ breakingFields: ["path"], allowedValues: after }, { A: { path: "/a" } }),
);
expect(diff.impact).toBe(impact);
});
});
it("verifies the approved digest and complete breaking evidence", () => {
const before = snapshot({ A: { path: "/before" } });
const after = snapshot({ A: { path: "/after" } });