From a144b575e5d6c052eba8bf12cfeb238fea1bbcbc Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:27:35 +0900 Subject: [PATCH] =?UTF-8?q?fix(contracts):=20FE-REG-ENV=20=EB=9F=B0?= =?UTF-8?q?=ED=83=80=EC=9E=84=20=ED=96=89=EC=9D=98=20=ED=95=84=EC=88=98=20?= =?UTF-8?q?=EC=97=AC=EB=B6=80=C2=B7=EA=B8=B0=EB=B3=B8=EA=B0=92=EC=9D=84=20?= =?UTF-8?q?=EC=8A=A4=ED=82=A4=EB=A7=88=EC=99=80=20=EB=A7=9E=EC=B6=98?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 FE-REG-ENV 런타임 행 13개 중 5개의 required·defaultValue가 실제 V2 runtime config 스키마(runtimeConfigV2ArtifactSchema)와 다르다. - TELEMETRY_ENABLED: 행 기본값 false / 스키마 필수, 기본값 없음 - AUTH_MODE: 행 기본값 "external" / 스키마 기본값 없음 - RELEASE_MANIFEST_URL: 행 required true / 스키마 선택(기본값 있음) - CAPABILITY_OVERRIDES: 행 기본값 null / 스키마 기본값 네 항목 DEFAULT - FEATURE_OVERRIDES: 행 기본값 null / 스키마 기본값 {} d0414c8의 테스트는 스키마 키마다 행이 있는지만 본다. 스키마에 없는 런타임 행도, 값이 다른 행도 통과한다. 이 레지스트리는 기준선 호환 검사 대상이라 틀린 값이 계약으로 굳는다. AUTH_MODE를 빼도 external이 된다고 읽으면 부팅이 스키마 오류로 멈춘다. 고른 방법 - env-registry-coverage에 두 방향을 더한다. 스키마가 읽지 않는 런타임 행은 실패한다. 각 행의 required·defaultValue는 스키마 필드에 undefined를 넣은 결과(실패 = 필수·기본값 없음, 성공 = 선택·그 값)와 같아야 한다. 차이는 키·행 값·스키마 값을 한 줄로 보인다. 제품 키(PRODUCT_*)도 같은 검사를 받는다. - 5개 행을 스키마에 맞춘다. 두 override 기본값은 객체라 governance의 defaultValue 타입에 object를 더했다. - ENV_REGISTRY 주석에 두 칸의 뜻(null = 스키마가 기본값을 주지 않음)을 적었다. 버린 대안 - 행의 required·defaultValue를 스키마에서 계산해 채우기: 손으로 맞출 일이 사라지지만 env.ts가 zod 스키마를 import해야 한다. env.ts는 부팅 경로 (getBuildConfig)에 있어 초기 청크에 zod 스키마가 끌려 들어간다. 위험·한계 - RELEASE_MANIFEST_URL required true→false는 breaking 칸 변경이고 governance fieldTypes도 바뀌어 기준선을 다시 승인했다. - 스키마 superRefine의 조건부 필수(TELEMETRY_ENABLED면 TELEMETRY_ENDPOINT)는 행에 표현하지 않는다. 검증 - RED: 새 대조 테스트가 위 5개 행을 정확히 보고하며 실패했다. - GREEN: env-registry-coverage 3건 통과. 변이: 스키마 REQUEST_TIMEOUT_MS 기본값만 20,000으로 바꾸면 실패, 스키마 필드 없는 제품 행을 더하면 실패. - check:registries(재승인 뒤 compatibility=none), run-vitest related (env.ts, governance) 18파일 154건, registry-governance·product-composition 23건, check:types, eslint 통과. Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-04 Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-05 --- .../contracts/registry-baseline.approval.json | 6 +- config/contracts/registry-baseline.json | 17 ++++-- config/contracts/registry-governance.json | 2 +- src/contracts/env.ts | 21 +++++-- tests/unit/env-registry-coverage.test.ts | 55 +++++++++++++++++-- 5 files changed, 81 insertions(+), 20 deletions(-) diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json index fad51b0f..38b05eee 100644 --- a/config/contracts/registry-baseline.approval.json +++ b/config/contracts/registry-baseline.approval.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "snapshotDigest": "96e048bf63f739ba7acb9238e77b4b36abaf9c1fc3e40ea2f2f4a4862e0127b9", + "snapshotDigest": "8f5ae6dde9c6a293144e5bccad1765367f06ac3a6b58a6229c69426703158c9c", "owner": "DongHyeonka", - "reason": "1103/07-01 FE-REG-API rows carry descriptor wire values (statuses, limits, deadline, retry budget, traffic, command data, validation skip); problemSchema and unvalidated are breaking fields", - "approvedAt": "2026-11-04T11:23:02.382Z" + "reason": "1103/13-04 FE-REG-ENV runtime rows state required and defaultValue as runtimeConfigV2ArtifactSchema reads them (TELEMETRY_ENABLED, AUTH_MODE, RELEASE_MANIFEST_URL, CAPABILITY_OVERRIDES, FEATURE_OVERRIDES); defaultValue may be an object", + "approvedAt": "2026-11-04T11:26:00.863Z" } diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json index 01e176d5..da86f4cd 100644 --- a/config/contracts/registry-baseline.json +++ b/config/contracts/registry-baseline.json @@ -656,7 +656,7 @@ "phase": "string", "classification": "string", "required": "boolean", - "defaultValue": "string|integer|boolean|null" + "defaultValue": "string|integer|boolean|object|null" }, "uniqueFields": [], "allowedValues": { @@ -694,7 +694,7 @@ }, "AUTH_MODE": { "classification": "public", - "defaultValue": "external", + "defaultValue": null, "phase": "runtime", "required": true }, @@ -706,7 +706,12 @@ }, "CAPABILITY_OVERRIDES": { "classification": "public", - "defaultValue": null, + "defaultValue": { + "OFFLINE_COMMANDS": "DEFAULT", + "REALTIME": "DEFAULT", + "SERVICE_WORKER": "DEFAULT", + "WEB_WORKER": "DEFAULT" + }, "phase": "runtime", "required": false }, @@ -718,7 +723,7 @@ }, "FEATURE_OVERRIDES": { "classification": "public", - "defaultValue": null, + "defaultValue": {}, "phase": "runtime", "required": false }, @@ -738,7 +743,7 @@ "classification": "public", "defaultValue": "/release-manifest.json", "phase": "runtime", - "required": true + "required": false }, "REQUEST_TIMEOUT_MS": { "classification": "public", @@ -748,7 +753,7 @@ }, "TELEMETRY_ENABLED": { "classification": "public", - "defaultValue": false, + "defaultValue": null, "phase": "runtime", "required": true }, diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index 71add621..dce422f5 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -291,7 +291,7 @@ "phase": "string", "classification": "string", "required": "boolean", - "defaultValue": "string|integer|boolean|null" + "defaultValue": "string|integer|boolean|object|null" }, "allowedValues": { "phase": ["build", "runtime"], diff --git a/src/contracts/env.ts b/src/contracts/env.ts index 48c874be..0fcf1a9e 100644 --- a/src/contracts/env.ts +++ b/src/contracts/env.ts @@ -41,6 +41,12 @@ export type EnvironmentDefinition = Readonly<{ defaultValue: unknown; }>; +/** + * FE-REG-ENV. A runtime row states its key as `runtimeConfigV2ArtifactSchema` + * (`release-artifacts.ts`) reads it: `required` when config.json must carry + * the key, and `defaultValue` the value the schema gives an absent key, or + * `null` when it gives none (1103/13-04, tests/unit/env-registry-coverage). + */ export const ENV_REGISTRY = Object.freeze(withProductRows({ // F-6. Required: a staging or production build fails without it // (scripts/generate-runtime-config.ts). Local and development builds fall @@ -53,20 +59,25 @@ export const ENV_REGISTRY = Object.freeze(withProductRows({ API_BASE_URL: runtime("public-sensitive", true, null), REQUEST_TIMEOUT_MS: runtime("public", false, 10_000), MAX_RETRY_ATTEMPTS: runtime("public", false, 2), - TELEMETRY_ENABLED: runtime("public", true, false), + TELEMETRY_ENABLED: runtime("public", true, null), TELEMETRY_ENDPOINT: runtime("public-sensitive", false, null), - AUTH_MODE: runtime("public", true, "external"), + AUTH_MODE: runtime("public", true, null), CONFIG_SCHEMA_VERSION: runtime("public", true, null), - RELEASE_MANIFEST_URL: runtime("public", true, "/release-manifest.json"), + RELEASE_MANIFEST_URL: runtime("public", false, "/release-manifest.json"), // F-6. The release identity the build writes into config.json. It must match // the deployed HTML and release manifest, or boot stops with // CONFIG_BUILD_MISMATCH (scripts/check-release-admission.ts). RELEASE_ID: runtime("public-metadata", false, null), BUILD_ID: runtime("public-metadata", false, null), // §3.5: overrides may only disable an installed capability, never enable one. - CAPABILITY_OVERRIDES: runtime("public", false, null), + CAPABILITY_OVERRIDES: runtime("public", false, Object.freeze({ + REALTIME: "DEFAULT", + WEB_WORKER: "DEFAULT", + SERVICE_WORKER: "DEFAULT", + OFFLINE_COMMANDS: "DEFAULT", + })), // §3.5: likewise for features — subtractive, keyed by installed feature id. - FEATURE_OVERRIDES: runtime("public", false, null), + FEATURE_OVERRIDES: runtime("public", false, Object.freeze({})), // §3.5: build-time narrowing of the product manifest, applied by // scripts/generate-product-feature-index.ts (09-02). A feature left out here // is not imported by any registry and never reaches the bundle. diff --git a/tests/unit/env-registry-coverage.test.ts b/tests/unit/env-registry-coverage.test.ts index f28118d0..e5efe327 100644 --- a/tests/unit/env-registry-coverage.test.ts +++ b/tests/unit/env-registry-coverage.test.ts @@ -1,19 +1,64 @@ +import { isDeepStrictEqual } from "node:util"; + import { describe, expect, it } from "vitest"; -import { ENV_REGISTRY } from "../../src/contracts/env.ts"; +import { + ENV_REGISTRY, + type EnvironmentDefinition, +} from "../../src/contracts/env.ts"; import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts"; +const rows: Readonly> = ENV_REGISTRY; +const shape = runtimeConfigV2ArtifactSchema.shape as Readonly< + Record +>; + +/** + * What the schema field says when the key is left out of config.json: a field + * that fails on `undefined` is required and has no default; one that passes + * has the parsed value as its default (`null` when it stays absent). + */ +function schemaDeclaration(key: string) { + const result = shape[key]!.safeParse(undefined); + return result.success + ? { required: false, defaultValue: result.data ?? null } + : { required: true, defaultValue: null }; +} + // 09-02. A key the deployed config.json may carry needs an FE-REG-ENV row, so // check:registries sees it. A product key added to // PRODUCT_RUNTIME_CONFIG_FIELDS without a PRODUCT_ENV_REGISTRY row fails here. describe("FE-REG-ENV coverage", () => { it("has a runtime row for every V2 runtime config key", () => { - const missing = Object.keys(runtimeConfigV2ArtifactSchema.shape).filter( - (key) => - !Object.hasOwn(ENV_REGISTRY, key) || - ENV_REGISTRY[key as keyof typeof ENV_REGISTRY].phase !== "runtime", + const missing = Object.keys(shape).filter( + (key) => !Object.hasOwn(rows, key) || rows[key]!.phase !== "runtime", ); expect(missing).toEqual([]); }); + + // 1103/13-04, 0929/P-07-05. The other direction: a runtime row names a key + // the schema reads, and states its required flag and default as the schema + // field does, so the governed snapshot does not describe another document. + it("has no runtime row the V2 schema does not read", () => { + const extra = Object.keys(rows).filter( + (key) => rows[key]!.phase === "runtime" && !Object.hasOwn(shape, key), + ); + + expect(extra).toEqual([]); + }); + + it("states each runtime row's required flag and default as its schema field does", () => { + const differences = Object.keys(shape).flatMap((key) => { + const row = rows[key]; + if (!row) return []; + const declared = { required: row.required, defaultValue: row.defaultValue }; + const expected = schemaDeclaration(key); + return isDeepStrictEqual(declared, expected) + ? [] + : [`${key}: row ${JSON.stringify(declared)}, schema ${JSON.stringify(expected)}`]; + }); + + expect(differences).toEqual([]); + }); });