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 }); + } + }); +});