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 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 23:25:24 +09:00
co-authored by Claude Opus 5.5
parent 69e40f106f
commit b685b616e4
8 changed files with 176 additions and 1 deletions
+1 -1
View File
@@ -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",
+1
View File
@@ -47,6 +47,7 @@ const diagnosticProducerFiles: Readonly<Record<string, string>> = {
"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) {
+15
View File
@@ -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<void> {
}
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<void> {
releaseId: config.RELEASE_ID ?? null,
status: violations.length === 0 ? "ADMITTED" : "REFUSED",
violations,
warnings,
},
null,
2,
+5
View File
@@ -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();
+11
View File
@@ -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;
+5
View File
@@ -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<Record<DiagnosticContextKey, DiagnosticCardinalityClass>>);
export type DiagnosticContext = Readonly<
+15
View File
@@ -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[],
@@ -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<typeof createRuntimeAdapters>[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<Record<string, "DISABLED">>): 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<typeof createRuntimeAdapters>[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 });
}
});
});