fix(registry): 맞는 변경이 없는 breaking 증거 행을 실패로 막는다 (0929/07-01)
문제
check:registries는 증거 행이 지금 diff의 어느 breaking 변경을 설명하는지
보지 않는다. 증거 파일 17건 중 14건이 지금 diff의 어떤 changeId와도 맞지
않았다(예: FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed,
그 필드는 07-04 이후 없다). update:registry-baseline은 기준선을 새로 찍어도
증거 행을 그대로 두므로 오래된 행이 계속 쌓인다. 5e6be9a가 리뷰 개선
(1)(증거를 값에 묶기)만 했고 (2)·(3)이 남았다.
고른 방법 (2026-11-03 결정)
- (2) validateBreakingEvidence가 지금 diff의 breaking 변경과 changeId가
맞지 않는 증거 행마다 "stale breaking evidence <changeId>: ..."로
실패한다. 메시지에 지울 행과 update:registry-baseline이 지운다는 사실을
적는다. breaking이 아닌 변경(behavior-change 등)과 맞는 행도 오래된
행으로 본다. 증거는 breaking 변경에만 쓰기 때문이다.
- (3) update:registry-baseline이 승인 파일을 쓴 뒤 증거 행을 모두 지우고,
지운 changeId를 출력한다. 새 기준선은 지금 스냅샷이라 증거가 설명하던
변경을 모두 흡수한다. 남은 행은 어떤 변경과도 맞지 않아 (2)에서
실패한다. 이력 파일로 옮기지 않는다. git 이력이 이력이다.
증거 파일은 쓰기 전에 읽어서, 파일이 없으면 아무것도 바꾸지 않고 멈춘다.
- 이번 검사에 걸리는 오래된 14건을 지웠다. 지금 diff와 맞는 3건
(REFERENCE_RESOURCE_DETAIL.path, CACHE_INVALIDATION_PULSE backend·
valueCodec)은 남겼다.
- docs/operations/ci-quality-gates.md 증거 안내에 두 동작을 적었다.
이유: 목록을 출력만 하면 아무도 보지 않는다. 정리가 자동이라 실패해도
고치는 비용이 작다.
버린 대안
- 오래된 행을 목록으로 출력만 하기: 위 이유.
- 지운 행을 이력 파일로 옮기기: 파일이 하나 늘고, git 이력과 같은 사실의
사본이 된다.
위험·한계
- 다운스트림이 이 검사를 동기화하면 자기 증거 파일의 오래된 행 때문에
게이트가 실패한다. 실패 메시지가 행을 나열하므로 지우거나
update:registry-baseline을 한 번 돌리면 된다. CHANGELOG [계약] 행이
필요하다.
- 같은 changeId가 증거 파일에 두 번 있으면 지금처럼 뒤의 행만 쓰고,
앞의 행은 오래된 행으로 걸리지 않는다. 이번 범위 밖이다.
검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 "fails on evidence
rows that explain no breaking change of the current diff"가
"expected [] to deeply equal [ …(2) ]"로 실패. registry-governance.test.ts
새 사례 "deletes the evidence rows the new baseline explains"가
"expected { schemaVersion: 1, changes: [ …(1) ] } to deeply equal
{ schemaVersion: 1, changes: [] }"로 실패.
- GREEN: 두 파일 25/25 통과. 오래된 행을 지우기 전 check-registries가
"stale breaking evidence ..." 14줄로 실패(rc=1), 지운 뒤 "11 registries
PASS"(rc=0).
- 회귀: registry-compatibility·registry-governance·second-api-feature-
registries·release-artifacts 55/55 통과. compatibility fixtures 11 PASS.
verify-documentation-readiness PASS_SCOPED. tsc node·test rc=0, 바꾼
파일 eslint rc=0.
- 미실행: check:architecture, test:sample-removal(pnpm 필요). 제거 드릴은
update:registry-baseline 뒤 check:registries를 돌리므로 (3)이 있어야
통과한다.
Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
This commit is contained in:
@@ -1,118 +1,6 @@
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"changes": [
|
||||
{
|
||||
"changeId": "FE-REG-ENV:API_CONTRACT_VERSION:*:removed",
|
||||
"versionBump": "Runtime Config V2 (CONFIG_SCHEMA_VERSION 2.0) removes the scalar API contract version.",
|
||||
"migration": "Release Manifest V2 contractSet replaces the scalar: the compiled external contract package set is canonicalized and digested, and boot compares it against the manifest.",
|
||||
"compatibilityWindow": "The V1 config and V1 manifest readers stay in place for one release. A V1 document may still carry the scalar; a V2 document is rejected if it does.",
|
||||
"rollback": "Restore the V1 writer in scripts/generate-build-manifest.ts and the scalar key in public/config.json; the V1 reader is still present.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:*:*:removed",
|
||||
"versionBump": "Query invalidation composition moves from the legacy flat query registry to the bounded many-to-many invalidation graph.",
|
||||
"migration": "Installed feature contracts now contribute topics, namespace identities, edges, and separate wire versions; bootstrap validates and indexes those contributions before constructing coordinators.",
|
||||
"compatibilityWindow": "Cross-context envelopes remain opaque topic/version pairs and release cache epochs isolate mixed releases; no query keys or cached values cross contexts.",
|
||||
"rollback": "Restore the flat QUERY_REGISTRY composition and its coordinator adapter together with the prior governance entry.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:$contract:allowedValues:contract-field-changed",
|
||||
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
|
||||
"migration": "Every installed query row declares invalidate-only; older tabs remain local-only.",
|
||||
"compatibilityWindow": "Mixed releases are isolated by release cacheEpoch and never exchange query keys or values.",
|
||||
"rollback": "Remove the coordinator composition and the two query registry fields.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:$contract:breakingFields:contract-field-changed",
|
||||
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
|
||||
"migration": "Every installed query row declares its opaque topic and transport policy.",
|
||||
"compatibilityWindow": "A release cacheEpoch rejects messages from a different deployed contract.",
|
||||
"rollback": "Remove the coordinator composition and restore the prior query registry contract.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:$contract:fieldTypes:contract-field-changed",
|
||||
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
|
||||
"migration": "The installed reference query row and all consumers were updated atomically.",
|
||||
"compatibilityWindow": "Old clients do not consume the new fields; new clients validate them before boot.",
|
||||
"rollback": "Restore the previous query registry field types and local-only invalidation.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:$contract:requiredFields:contract-field-changed",
|
||||
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
|
||||
"migration": "Missing topics now fail registry validation instead of silently degrading at runtime.",
|
||||
"compatibilityWindow": "Only a fully built release consumes its own installed registry snapshot.",
|
||||
"rollback": "Remove the newly required fields and cross-context composition together.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-QUERY:$contract:uniqueFields:contract-field-changed",
|
||||
"versionBump": "Cross-context invalidation wire protocol starts at version 1.",
|
||||
"migration": "Existing query namespaces received unique registry-issued opaque topics.",
|
||||
"compatibilityWindow": "Topics are scoped by release cacheEpoch, so mixed releases cannot collide.",
|
||||
"rollback": "Drop invalidationTopic uniqueness after removing the transport consumer.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-RELEASE:apiContractVersion:compatibilityRole:field-changed",
|
||||
"versionBump": "The release token registry adds contractSetDigest and demotes apiContractVersion to a legacy V1 scalar.",
|
||||
"migration": "compareReleaseToRuntime no longer sources the scalar from Runtime Config; when neither side declares it there is nothing to compare and contractSet verification owns contract coherence.",
|
||||
"compatibilityWindow": "A V1 manifest still supplies apiContractVersion and is still compared against a V1 config that declares one.",
|
||||
"rollback": "Restore the previous compatibilityRole text and remove the contractSetDigest token together with the V2 manifest writer.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-STORAGE:$contract:allowedValues:contract-field-changed",
|
||||
"versionBump": "Web Storage value codec contracts start at version 1.",
|
||||
"migration": "Existing keys retain their physical schema version; values outside the selected codec are discarded.",
|
||||
"compatibilityWindow": "Valid existing color-scheme and opaque-string records remain readable.",
|
||||
"rollback": "Restore the previous registry contract; no physical key deletion is required.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-STORAGE:$contract:breakingFields:contract-field-changed",
|
||||
"versionBump": "Web Storage value codec contracts start at version 1.",
|
||||
"migration": "Each existing row received an explicit codec; executable migration was never consumed and is now forbidden.",
|
||||
"compatibilityWindow": "Schema-versioned physical keys and the envelope shape remain unchanged.",
|
||||
"rollback": "Remove valueCodec enforcement and restore the prior metadata declaration.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-STORAGE:$contract:fieldTypes:contract-field-changed",
|
||||
"versionBump": "Web Storage value codec contracts start at version 1.",
|
||||
"migration": "The dead function migration union was narrowed to the only implemented discard policy.",
|
||||
"compatibilityWindow": "All installed definitions already used discard before this contract change.",
|
||||
"rollback": "Restore the former type metadata without rewriting persisted records.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-STORAGE:$contract:requiredFields:contract-field-changed",
|
||||
"versionBump": "Web Storage value codec contracts start at version 1.",
|
||||
"migration": "All installed storage rows now declare their closed value codec.",
|
||||
"compatibilityWindow": "Existing valid envelopes continue to decode; invalid values fail closed.",
|
||||
"rollback": "Remove the required codec field and runtime codec dispatch together.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-ERROR:QUERY_CACHE_FAILURE:telemetryEvent:field-changed",
|
||||
"versionBump": "Error taxonomy observability references became the closed union of registered diagnostic and telemetry event ids (extreme-scale Phase 4 ledger, 2026-09-23).",
|
||||
"migration": "QUERY_CACHE_FAILURE pointed at the unregistered event id query.cache.failed; it now references the registered cache.operation.failed diagnostic event that the query cache adapter actually emits.",
|
||||
"compatibilityWindow": "No wire, storage or runtime-config format changes: the old id was never emitted by any producer, so no consumer could observe it.",
|
||||
"rollback": "Restore the previous telemetryEvent string on QUERY_CACHE_FAILURE in src/contracts/errors.ts and widen ErrorObservationEvent back to string.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed",
|
||||
"versionBump": "F-6 (13-15): the registry now records the local-build fallback that getBuildConfig and the build scripts already applied; the value itself did not change.",
|
||||
"migration": "None for local builds. A staging or production build without VITE_BUILD_ID now fails in scripts/generate-runtime-config.ts instead of shipping the placeholder that admission refused.",
|
||||
"compatibilityWindow": "No runtime document or wire format changes: BUILD_ID was already local-build whenever VITE_BUILD_ID was unset.",
|
||||
"rollback": "Restore defaultValue null on VITE_BUILD_ID in src/contracts/env.ts and drop the public-target check in scripts/generate-runtime-config.ts.",
|
||||
"owner": "frontend-platform"
|
||||
},
|
||||
{
|
||||
"changeId": "FE-REG-ROUTE:REFERENCE_RESOURCE_DETAIL:path:field-changed",
|
||||
"after": "/examples/reference-resources/items/:resourceId",
|
||||
|
||||
@@ -64,7 +64,7 @@ package script 그래프로 닿거나, 게이트가 이미 돌리는 Vitest 경
|
||||
| 기준선 | 파일 | 갱신 방법 | 검사 위치 |
|
||||
|---|---|---|---|
|
||||
| CI 계약 크기·게이트 모양 | `config/ci/contract-baseline.json` | `update:ci-contract-baseline` (`CI_CONTRACT_BASELINE_OWNER`·`_REASON` 필수) | `scripts/contracts/ci-gates.ts` `assertCiContractBaseline` |
|
||||
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다 | `scripts/check-registries.ts`의 baseline 비교 |
|
||||
| registry 스냅샷과 승인 | `config/contracts/registry-baseline.json`, `registry-baseline.approval.json` | `update:registry-baseline` (`REGISTRY_BASELINE_OWNER`·`_REASON` 필수). 기준선을 새로 찍지 않고 breaking 변경을 유지하려면 `config/contracts/registry-change-evidence.json`에 항목을 추가(`changeId`, 그 변경 뒤 값 `after`(삭제는 생략, 값은 JSON 그대로이고 키·원시값 배열 순서는 상관없다), `versionBump`·`migration`·`compatibilityWindow`·`rollback`·`owner`). 같은 칸을 다시 바꾸면 `after`가 달라 새 항목이 필요하다. 지금 diff의 breaking 변경과 changeId가 맞지 않는 항목이 있으면 게이트가 그 항목을 나열하며 실패한다. `update:registry-baseline`은 새 기준선이 설명하는 항목을 모두 지운다(지운 항목은 git 이력에 남는다) | `scripts/check-registries.ts`의 baseline 비교 |
|
||||
| 커버리지 모듈 수 하한 | `config/testing/risk-coverage.json`의 `repositoryBaseline` | 직접 수정. 지운 production 모듈 수만큼 줄인다(`scripts/test-sample-removal.ts`가 같은 계산을 한다) | `scripts/lib/risk-coverage.ts` "repository module baseline" |
|
||||
| 기능 끄기 설정 | `config/runtime/<profile>.json`의 `FEATURE_OVERRIDES` | 직접 수정. 지운 기능의 키를 뺀다(`scripts/test-sample-removal.ts`가 같은 일을 한다) | 없음. 남은 키는 조용히 무시된다(리뷰 09-09) |
|
||||
| 의존성 목록 | `config/security/dependency-baseline.json`, `dependency-baseline.approval.json` | `update:dependency-baseline` (`DEPENDENCY_BASELINE_OWNER`·`_REASON` 필수) | `scripts/generate-supply-chain.ts` |
|
||||
|
||||
@@ -381,9 +381,10 @@ export function validateBreakingEvidence(
|
||||
entries.map((entry) => [String(entry.changeId), entry]),
|
||||
);
|
||||
const failures: string[] = [];
|
||||
for (const change of diff.changes.filter(
|
||||
const breakingChanges = diff.changes.filter(
|
||||
(entry) => entry.impact === "breaking",
|
||||
)) {
|
||||
);
|
||||
for (const change of breakingChanges) {
|
||||
const entry = evidence.get(change.changeId);
|
||||
if (!entry) {
|
||||
failures.push(`breaking change missing evidence: ${change.changeId}`);
|
||||
@@ -420,6 +421,18 @@ export function validateBreakingEvidence(
|
||||
}
|
||||
}
|
||||
}
|
||||
// 0929/07-01 (2). A row that explains no breaking change of this diff was
|
||||
// absorbed by an earlier baseline or describes a change that is gone. It
|
||||
// fails rather than being listed, because a printed list is not read, and
|
||||
// the fix is cheap: update:registry-baseline deletes absorbed rows.
|
||||
const explained = new Set(breakingChanges.map((change) => change.changeId));
|
||||
for (const entry of entries) {
|
||||
if (!explained.has(String(entry.changeId))) {
|
||||
failures.push(
|
||||
`stale breaking evidence ${String(entry.changeId)}: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)`,
|
||||
);
|
||||
}
|
||||
}
|
||||
return Object.freeze({
|
||||
passed: failures.length === 0,
|
||||
failures: Object.freeze(failures),
|
||||
|
||||
@@ -7,6 +7,7 @@ const inputPath =
|
||||
process.argv[2] ?? "artifacts/quality/registry-current-snapshot.json";
|
||||
const outputPath =
|
||||
process.argv[3] ?? "config/contracts/registry-baseline.json";
|
||||
const evidencePath = "config/contracts/registry-change-evidence.json";
|
||||
const owner = process.env.REGISTRY_BASELINE_OWNER;
|
||||
const reason = process.env.REGISTRY_BASELINE_REASON;
|
||||
|
||||
@@ -18,6 +19,8 @@ if (!owner || !reason) {
|
||||
}
|
||||
|
||||
const input = JSON.parse(await readFile(inputPath, "utf8"));
|
||||
// Read before anything is written, so a missing file changes nothing.
|
||||
const evidence = JSON.parse(await readFile(evidencePath, "utf8"));
|
||||
const snapshot = input.registries
|
||||
? { schemaVersion: 2, registries: input.registries }
|
||||
: input;
|
||||
@@ -38,4 +41,19 @@ await writeFile(
|
||||
2,
|
||||
)}\n`,
|
||||
);
|
||||
// 0929/07-01 (3). The new baseline is the current snapshot, so it explains
|
||||
// every change an evidence row described. A row left behind would match no
|
||||
// change and fail check:registries. Git history keeps the deleted rows.
|
||||
const deleted = (evidence.changes ?? []).map(
|
||||
(entry: { changeId?: unknown }) => String(entry.changeId),
|
||||
);
|
||||
await writeFile(
|
||||
evidencePath,
|
||||
`${JSON.stringify({ ...evidence, changes: [] }, null, 2)}\n`,
|
||||
);
|
||||
process.stdout.write(`Registry baseline updated: ${digest}\n`);
|
||||
if (deleted.length > 0) {
|
||||
process.stdout.write(
|
||||
`Deleted evidence the new baseline explains:\n${deleted.join("\n")}\n`,
|
||||
);
|
||||
}
|
||||
|
||||
@@ -205,6 +205,31 @@ describe("registry compatibility evidence", () => {
|
||||
).toBe(true);
|
||||
});
|
||||
|
||||
// 0929/07-01 (2). A row that explains no breaking change of the current
|
||||
// diff fails the gate, and the message names every such row.
|
||||
it("fails on evidence rows that explain no breaking change of the current diff", () => {
|
||||
const diff = diffRegistrySnapshots(
|
||||
snapshot({ A: { path: "/a", owner: "one" } }),
|
||||
snapshot({ A: { path: "/entries", owner: "two" } }),
|
||||
);
|
||||
const row = (changeId: string, after?: string) => ({
|
||||
...evidence(after === undefined ? {} : { after }).changes[0],
|
||||
changeId,
|
||||
});
|
||||
expect(
|
||||
validateBreakingEvidence(diff, {
|
||||
changes: [
|
||||
row("FE-REG-TEST:A:path:field-changed", "/entries"),
|
||||
row("FE-REG-TEST:B:*:removed"),
|
||||
row("FE-REG-TEST:A:owner:field-changed", "two"),
|
||||
],
|
||||
}).failures,
|
||||
).toEqual([
|
||||
"stale breaking evidence FE-REG-TEST:B:*:removed: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)",
|
||||
"stale breaking evidence FE-REG-TEST:A:owner:field-changed: no breaking change in the current diff has this changeId. Delete the row (update:registry-baseline deletes the rows a new baseline explains)",
|
||||
]);
|
||||
});
|
||||
|
||||
it("needs no value for a removal", () => {
|
||||
const removed = diffRegistrySnapshots(
|
||||
snapshot({ A: { path: "/a" } }),
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { spawnSync } from "node:child_process";
|
||||
import { mkdtemp, readFile, rm } from "node:fs/promises";
|
||||
import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import path from "node:path";
|
||||
import { describe, expect, it } from "vitest";
|
||||
@@ -343,6 +343,63 @@ describe("registry governance manifest", () => {
|
||||
});
|
||||
});
|
||||
|
||||
// 0929/07-01 (3). Re-approval makes the current snapshot the baseline, so it
|
||||
// explains every change the evidence described. Git history keeps the rows.
|
||||
it("deletes the evidence rows the new baseline explains when it re-approves", async () => {
|
||||
const directory = await mkdtemp(
|
||||
path.join(tmpdir(), "registry-baseline-update-"),
|
||||
);
|
||||
const evidencePath = path.join(
|
||||
directory,
|
||||
"config/contracts/registry-change-evidence.json",
|
||||
);
|
||||
try {
|
||||
await mkdir(path.dirname(evidencePath), { recursive: true });
|
||||
await writeFile(
|
||||
path.join(directory, "snapshot.json"),
|
||||
JSON.stringify({ registries: [] }),
|
||||
);
|
||||
await writeFile(
|
||||
evidencePath,
|
||||
JSON.stringify({
|
||||
schemaVersion: 1,
|
||||
changes: [
|
||||
{
|
||||
changeId: "FE-REG-TEST:A:*:removed",
|
||||
versionBump: "2",
|
||||
migration: "none",
|
||||
compatibilityWindow: "none",
|
||||
rollback: "restore A",
|
||||
owner: "fixture-owner",
|
||||
},
|
||||
],
|
||||
}),
|
||||
);
|
||||
const result = spawnSync(
|
||||
process.execPath,
|
||||
[path.resolve("scripts/update-registry-baseline.ts"), "snapshot.json"],
|
||||
{
|
||||
cwd: directory,
|
||||
encoding: "utf8",
|
||||
env: {
|
||||
...process.env,
|
||||
REGISTRY_BASELINE_OWNER: "fixture-owner",
|
||||
REGISTRY_BASELINE_REASON: "fixture re-approval",
|
||||
},
|
||||
},
|
||||
);
|
||||
|
||||
expect(result.status, result.stderr).toBe(0);
|
||||
expect(JSON.parse(await readFile(evidencePath, "utf8"))).toEqual({
|
||||
schemaVersion: 1,
|
||||
changes: [],
|
||||
});
|
||||
expect(result.stdout).toContain("FE-REG-TEST:A:*:removed");
|
||||
} finally {
|
||||
await rm(directory, { recursive: true, force: true });
|
||||
}
|
||||
});
|
||||
|
||||
it("rejects duplicate composite invalidation edges after projection", async () => {
|
||||
const directory = await mkdtemp(
|
||||
path.join(tmpdir(), "registry-governance-duplicate-"),
|
||||
|
||||
Reference in New Issue
Block a user