From b685b616e4d347092cf12502ac7f8d80e53125fa Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 25 Sep 2026 23:25:24 +0900 Subject: [PATCH] fix(bootstrap): report FEATURE_OVERRIDES keys the build does not declare (09-09) A misspelt kill-switch key was ignored without a trace, so the feature kept running. Boot now records feature.override.unknown once per such key, and release admission lists them as warnings in its record without refusing the artifact (a shared document may still name another build's features). Co-Authored-By: Claude Opus 5.5 --- package.json | 2 +- scripts/check-diagnostics.ts | 1 + scripts/check-release-admission.ts | 15 +++ scripts/contracts/release-artifacts.ts | 5 + src/bootstrap/runtime-adapters.ts | 11 ++ src/contracts/diagnostics.ts | 5 + src/contracts/product-features.ts | 15 +++ .../unit/feature-override-diagnostics.test.ts | 123 ++++++++++++++++++ 8 files changed, 176 insertions(+), 1 deletion(-) create mode 100644 tests/unit/feature-override-diagnostics.test.ts diff --git a/package.json b/package.json index 2558dad7..505cd341 100644 --- a/package.json +++ b/package.json @@ -22,7 +22,7 @@ "check:i18n:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-i18n.ts --fixture", "check:adapter-inventory": "node scripts/check-adapter-inventory.ts", "check:remediation-ledger": "node scripts/check-remediation-ledger.ts", - "check:release-admission": "node scripts/check-release-admission.ts", + "check:release-admission": "node scripts/generate-product-feature-index.ts && node scripts/check-release-admission.ts", "check:diagnostics": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts", "check:diagnostics:fixture": "node scripts/generate-product-feature-index.ts && node scripts/check-diagnostics.ts --fixture", "check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test && corepack pnpm check:types:recipes && corepack pnpm check:types:web-worker && corepack pnpm check:types:service-worker", diff --git a/scripts/check-diagnostics.ts b/scripts/check-diagnostics.ts index 7823f6b5..62a1ac29 100644 --- a/scripts/check-diagnostics.ts +++ b/scripts/check-diagnostics.ts @@ -47,6 +47,7 @@ const diagnosticProducerFiles: Readonly> = { "ui.render.failed": "src/application/create-application.ts", "release.mismatch.detected": "src/application/create-application.ts", "telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.ts", + "feature.override.unknown": "src/bootstrap/runtime-adapters.ts", }; for (const key of DIAGNOSTIC_CONTEXT_ALLOWLIST) { diff --git a/scripts/check-release-admission.ts b/scripts/check-release-admission.ts index be06a6d6..15e0299b 100644 --- a/scripts/check-release-admission.ts +++ b/scripts/check-release-admission.ts @@ -7,7 +7,9 @@ import { isDeploymentTarget, type AdmissionInput, } from "../src/contracts/deployment-admission.ts"; +import { unknownProductFeatureOverrides } from "../src/contracts/product-features.ts"; import { parseRuntimeConfigArtifact } from "../src/contracts/release-artifacts.ts"; +import { COMPILED_PRODUCT_FEATURE_IDS } from "../src/features/installed-product-manifest.ts"; /** * ยง6.4 / FE-GATE-027. Refuses to admit an artifact to an environment it was not @@ -79,6 +81,18 @@ async function main(): Promise { } const violations = findAdmissionViolations(declared, config); + // 09-09. Inert by design (a shared document may name another build's + // features), so this warns instead of refusing. + const warnings = unknownProductFeatureOverrides( + COMPILED_PRODUCT_FEATURE_IDS, + "FEATURE_OVERRIDES" in config ? config.FEATURE_OVERRIDES : undefined, + ).map((featureId) => ({ + field: `FEATURE_OVERRIDES.${featureId}`, + reason: `names no feature this build declares (${COMPILED_PRODUCT_FEATURE_IDS.join(", ") || "none"}); the override does nothing`, + })); + for (const warning of warnings) { + process.stderr.write(`release admission warning: ${warning.field} ${warning.reason}\n`); + } await mkdir("artifacts/release", { recursive: true }); await writeFile( RECORD_PATH, @@ -93,6 +107,7 @@ async function main(): Promise { releaseId: config.RELEASE_ID ?? null, status: violations.length === 0 ? "ADMITTED" : "REFUSED", violations, + warnings, }, null, 2, diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index f459f995..1f1b2270 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -688,6 +688,11 @@ export const deploymentAdmissionArtifactSchema = z violations: z.array( z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(), ), + // 09-09. Findings that do not refuse the artifact, e.g. an override key + // naming a feature this build does not declare. + warnings: z.array( + z.object({ field: nonEmptyString, reason: nonEmptyString }).strict(), + ), }) .strict(); diff --git a/src/bootstrap/runtime-adapters.ts b/src/bootstrap/runtime-adapters.ts index 1a32eacd..27d3d4b8 100644 --- a/src/bootstrap/runtime-adapters.ts +++ b/src/bootstrap/runtime-adapters.ts @@ -56,6 +56,7 @@ import { import { activeProductFeatureIds, resolveProductFeatures, + unknownProductFeatureOverrides, } from "../contracts/product-features.ts"; import { describeRuntimeCapabilities } from "../contracts/runtime-capabilities.ts"; import { @@ -442,6 +443,16 @@ export async function createRuntimeAdapters( const activeFeatureIds = new Set( activeProductFeatureIds(productFeatureStatuses), ); + for (const key of unknownProductFeatureOverrides( + COMPILED_PRODUCT_FEATURE_IDS, + config.FEATURE_OVERRIDES, + )) { + diagnostics.record({ + level: "warn", + eventId: "feature.override.unknown", + context: { feature_override_key: key }, + }); + } const productFeatures = Object.freeze({ getSnapshot() { return productFeatureStatuses; diff --git a/src/contracts/diagnostics.ts b/src/contracts/diagnostics.ts index 9d348645..8bd9a9af 100644 --- a/src/contracts/diagnostics.ts +++ b/src/contracts/diagnostics.ts @@ -18,6 +18,7 @@ export const DIAGNOSTIC_EVENT_REGISTRY = Object.freeze({ "ui.render.failed": Object.freeze({ level: "error" }), "release.mismatch.detected": Object.freeze({ level: "warn" }), "telemetry.delivery.dropped": Object.freeze({ level: "warn" }), + "feature.override.unknown": Object.freeze({ level: "warn" }), }); export type DiagnosticEventId = keyof typeof DIAGNOSTIC_EVENT_REGISTRY; @@ -41,6 +42,7 @@ export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([ "operation", "reason", "queue_size_bucket", + "feature_override_key", ] as const); export type DiagnosticContextKey = (typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number]; @@ -82,6 +84,9 @@ export const DIAGNOSTIC_CONTEXT_CARDINALITY = Object.freeze({ operation: "topology", reason: "taxonomy", queue_size_bucket: "bounded", + // 09-09. A key from the deployed runtime document; it changes with a config + // deployment, not with traffic. + feature_override_key: "deployment", } satisfies Readonly>); export type DiagnosticContext = Readonly< diff --git a/src/contracts/product-features.ts b/src/contracts/product-features.ts index bb0d069b..78a762dd 100644 --- a/src/contracts/product-features.ts +++ b/src/contracts/product-features.ts @@ -128,6 +128,21 @@ export function resolveProductFeatures( ); } +/** + * 09-09. Override keys naming no feature this build declares. They stay inert, + * since one runtime document may serve builds with different features, but a + * misspelt kill switch has to be reported rather than silently ignored. + */ +export function unknownProductFeatureOverrides( + compiledIds: readonly string[], + overrides: ProductFeatureOverrideMap = {}, +): readonly string[] { + const declared = new Set(compiledIds); + return Object.freeze( + Object.keys(overrides).filter((featureId) => !declared.has(featureId)).sort(), + ); +} + /** The feature ids serving traffic right now. */ export function activeProductFeatureIds( statuses: readonly ProductFeatureStatus[], diff --git a/tests/unit/feature-override-diagnostics.test.ts b/tests/unit/feature-override-diagnostics.test.ts new file mode 100644 index 00000000..91446b0d --- /dev/null +++ b/tests/unit/feature-override-diagnostics.test.ts @@ -0,0 +1,123 @@ +import { spawnSync } from "node:child_process"; +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"; + +import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.ts"; +import { COMPILED_PRODUCT_FEATURE_IDS } from "../../src/features/installed-product-manifest.ts"; +import { generateRuntimeConfig } from "../../scripts/generate-runtime-config.ts"; + +type Runtime = Parameters[0]["runtime"]; + +// 09-09. An override key this build does not declare stays inert (one runtime +// document may serve several builds), but a misspelt kill switch used to leave +// the feature running without a trace. +const MISSPELT = "reference-featrue"; + +function runtimeWith(overrides: Readonly>): Runtime { + return { + config: { + APP_ENV: "local", + API_BASE_URL: "http://localhost:8080", + TELEMETRY_ENABLED: false, + AUTH_MODE: "demo", + REQUEST_TIMEOUT_MS: 1000, + MAX_RETRY_ATTEMPTS: 0, + RELEASE_MANIFEST_URL: "/release-manifest.json", + CONFIG_SCHEMA_VERSION: "2.0", + CAPABILITY_OVERRIDES: { + REALTIME: "DEFAULT", + WEB_WORKER: "DEFAULT", + SERVICE_WORKER: "DEFAULT", + OFFLINE_COMMANDS: "DEFAULT", + }, + FEATURE_OVERRIDES: overrides, + }, + configSchema: "V2", + build: { + buildId: "build-a", + commitSha: "abc123", + routerBasePath: "/", + runtimeConfigUrl: "/config.json", + }, + validationDurationMs: 0, + }; +} + +const release = { + schemaVersion: 2, + appVersion: "0.1.0", + buildId: "build-a", + commitSha: "abc123", + configSchemaVersion: "2.0", + contractSet: { + setAlgorithm: "CA_CONTRACT_SET_V1", + setDigest: `sha256:${"0".repeat(64)}`, + packages: [], + }, + assetManifestHash: "hash-a", + releaseId: "release-a", + builtAt: "2026-07-25T00:00:00Z", + routeChunks: {}, +} as Parameters[0]["release"]; + +describe("unknown feature override keys (09-09)", () => { + it("records one diagnostic per key the build does not declare", async () => { + const declared = COMPILED_PRODUCT_FEATURE_IDS[0]; + const adapters = await createRuntimeAdapters({ + runtime: runtimeWith({ + [MISSPELT]: "DISABLED", + ...(declared === undefined ? {} : { [declared]: "DISABLED" }), + }), + release, + host: {}, + }); + try { + const unknown = adapters.outputPorts.diagnostics + .entries() + .filter((entry) => entry.eventId === "feature.override.unknown"); + expect(unknown).toEqual([ + expect.objectContaining({ + level: "warn", + context: { feature_override_key: MISSPELT }, + }), + ]); + } finally { + adapters.infrastructure.dispose(); + } + }); + + it("warns in the admission record without refusing the artifact", async () => { + const root = await mkdtemp(path.join(tmpdir(), "admission-override-")); + try { + const config = await generateRuntimeConfig("local", {}); + await mkdir(path.join(root, "dist"), { recursive: true }); + await writeFile( + path.join(root, "dist/config.json"), + JSON.stringify({ ...config, FEATURE_OVERRIDES: { [MISSPELT]: "DISABLED" } }), + ); + const result = spawnSync( + process.execPath, + [path.resolve("scripts/check-release-admission.ts")], + { + cwd: root, + encoding: "utf8", + env: { ...process.env, APP_PROFILE: "local", RELEASE_TARGET: "local" }, + }, + ); + expect(result.status, result.stderr).toBe(0); + expect(result.stderr).toContain(MISSPELT); + const record = JSON.parse( + await readFile(path.join(root, "artifacts/release/deployment-admission.json"), "utf8"), + ) as { status: string; warnings: { field: string; reason: string }[] }; + expect(record.status).toBe("ADMITTED"); + expect(record.warnings).toEqual([ + expect.objectContaining({ field: `FEATURE_OVERRIDES.${MISSPELT}` }), + ]); + } finally { + await rm(root, { recursive: true, force: true }); + } + }); +});