diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index 9999c135..f7e2ab0c 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -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", diff --git a/docs/operations/ci-quality-gates.md b/docs/operations/ci-quality-gates.md index 5ddce76f..19803142 100644 --- a/docs/operations/ci-quality-gates.md +++ b/docs/operations/ci-quality-gates.md @@ -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/.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` | diff --git a/scripts/lib/registry-compatibility.ts b/scripts/lib/registry-compatibility.ts index 9dbcdf25..ee0a700d 100644 --- a/scripts/lib/registry-compatibility.ts +++ b/scripts/lib/registry-compatibility.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), diff --git a/scripts/update-registry-baseline.ts b/scripts/update-registry-baseline.ts index 8e2236b9..baef0bc6 100644 --- a/scripts/update-registry-baseline.ts +++ b/scripts/update-registry-baseline.ts @@ -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`, + ); +} diff --git a/tests/unit/registry-compatibility.test.ts b/tests/unit/registry-compatibility.test.ts index 197eacfa..e9c3e98a 100644 --- a/tests/unit/registry-compatibility.test.ts +++ b/tests/unit/registry-compatibility.test.ts @@ -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" } }), diff --git a/tests/unit/registry-governance.test.ts b/tests/unit/registry-governance.test.ts index e188da79..f5fbf295 100644 --- a/tests/unit/registry-governance.test.ts +++ b/tests/unit/registry-governance.test.ts @@ -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-"),