fix(contracts): FE-REG-ENV 런타임 행의 필수 여부·기본값을 스키마와 맞춘다
문제
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
This commit is contained in:
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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
|
||||
},
|
||||
|
||||
@@ -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"],
|
||||
|
||||
+16
-5
@@ -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.
|
||||
|
||||
@@ -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<Record<string, EnvironmentDefinition>> = ENV_REGISTRY;
|
||||
const shape = runtimeConfigV2ArtifactSchema.shape as Readonly<
|
||||
Record<string, { safeParse(value: unknown): { success: boolean; data?: unknown } }>
|
||||
>;
|
||||
|
||||
/**
|
||||
* 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([]);
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user