From 17d617ab7a5d34bb4d74985e5838e683729b95d8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:04:25 +0900 Subject: [PATCH] fix(contracts): classify unknown schema changes as breaking and gate the runtime config schema against a baseline (07-02, 13-10) The classifier called type, enum and nullable changes "none" and treated new keys under strict readers as additive; FE-GATE-014 only checked hand-written fixtures. It now fails closed and compares the committed baseline with the schema the build emits. The doc lists per-boundary reader rules. Co-Authored-By: Claude Opus 5.5 --- config/compatibility/fixtures.json | 110 +++++++------- .../runtime-config.schema.baseline.json | 140 ++++++++++++++++++ docs/contracts/compatibility.md | 57 ++++++- scripts/check-compatibility.ts | 81 ++++++---- scripts/contracts/release-artifacts.ts | 23 ++- src/contracts/compatibility.ts | 63 ++++++-- tests/unit/compatibility.test.ts | 77 ++++++++++ 7 files changed, 450 insertions(+), 101 deletions(-) create mode 100644 config/compatibility/runtime-config.schema.baseline.json diff --git a/config/compatibility/fixtures.json b/config/compatibility/fixtures.json index fbe5d0c3..37487e4f 100644 --- a/config/compatibility/fixtures.json +++ b/config/compatibility/fixtures.json @@ -1,63 +1,67 @@ { - "schemaVersion": 1, - "families": { - "api": { - "additive": { - "before": { "required": ["id"], "properties": { "id": {} } }, - "after": { - "required": ["id"], - "properties": { "id": {}, "displayName": {} } - } - }, - "breaking": { - "before": { "required": ["id"], "properties": { "id": {} } }, - "after": { - "required": ["id", "name"], - "properties": { "id": {}, "name": {} } - } + "schemaVersion": 2, + "cases": [ + { + "id": "tolerant-reader-optional-field", + "expected": "additive", + "before": { "required": ["id"], "properties": { "id": {} } }, + "after": { + "required": ["id"], + "properties": { "id": {}, "displayName": {} } } }, - "config": { - "additive": { - "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } }, - "after": { - "required": ["APP_ENV"], - "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} } - } + { + "id": "strict-reader-optional-field", + "expected": "breaking", + "before": { + "required": ["APP_ENV"], + "properties": { "APP_ENV": {} }, + "additionalProperties": false }, - "breaking": { - "before": { "required": ["APP_ENV"], "properties": { "APP_ENV": {} } }, - "after": { - "required": ["APP_ENV", "NEW_REQUIRED"], - "properties": { "APP_ENV": {}, "NEW_REQUIRED": {} } - } + "after": { + "required": ["APP_ENV"], + "properties": { "APP_ENV": {}, "OPTIONAL_FLAG": {} }, + "additionalProperties": false } }, - "storage": { - "additive": { - "before": { "properties": { "theme": {} } }, - "after": { "properties": { "theme": {}, "contrast": {} } } - }, - "breaking": { - "before": { "properties": { "theme": {} } }, - "after": { "properties": {} } + { + "id": "required-field-added", + "expected": "breaking", + "before": { "required": ["buildId"], "properties": { "buildId": {} } }, + "after": { + "required": ["buildId", "assetManifestHash"], + "properties": { "buildId": {}, "assetManifestHash": {} } } }, - "release": { - "additive": { - "before": { "required": ["buildId"], "properties": { "buildId": {} } }, - "after": { - "required": ["buildId"], - "properties": { "buildId": {}, "builtAt": {} } - } - }, - "breaking": { - "before": { "required": ["buildId"], "properties": { "buildId": {} } }, - "after": { - "required": ["buildId", "assetManifestHash"], - "properties": { "buildId": {}, "assetManifestHash": {} } - } - } + { + "id": "field-removed", + "expected": "breaking", + "before": { "properties": { "theme": {} } }, + "after": { "properties": {} } + }, + { + "id": "type-changed", + "expected": "breaking", + "before": { "properties": { "id": { "type": "string" } } }, + "after": { "properties": { "id": { "type": "number" } } } + }, + { + "id": "enum-narrowed", + "expected": "breaking", + "before": { "properties": { "state": { "enum": ["A", "B"] } } }, + "after": { "properties": { "state": { "enum": ["A"] } } } + }, + { + "id": "nullable-added", + "expected": "breaking", + "before": { "properties": { "note": { "type": "string" } } }, + "after": { "properties": { "note": { "type": ["string", "null"] } } } + }, + { + "id": "unchanged", + "expected": "none", + "before": { "required": ["id"], "properties": { "id": { "type": "string" } } }, + "after": { "properties": { "id": { "type": "string" } }, "required": ["id"] } } - } + ] } diff --git a/config/compatibility/runtime-config.schema.baseline.json b/config/compatibility/runtime-config.schema.baseline.json new file mode 100644 index 00000000..046379ef --- /dev/null +++ b/config/compatibility/runtime-config.schema.baseline.json @@ -0,0 +1,140 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "APP_ENV": { + "type": "string", + "enum": [ + "local", + "development", + "staging", + "production" + ] + }, + "API_BASE_URL": { + "type": "string", + "format": "uri" + }, + "REQUEST_TIMEOUT_MS": { + "default": 10000, + "type": "integer", + "minimum": 100, + "maximum": 60000 + }, + "MAX_RETRY_ATTEMPTS": { + "default": 2, + "type": "integer", + "minimum": 0, + "maximum": 2 + }, + "TELEMETRY_ENABLED": { + "type": "boolean" + }, + "TELEMETRY_ENDPOINT": { + "type": "string", + "format": "uri" + }, + "AUTH_MODE": { + "type": "string", + "enum": [ + "external", + "demo" + ] + }, + "RELEASE_MANIFEST_URL": { + "default": "/release-manifest.json", + "type": "string", + "minLength": 1 + }, + "RELEASE_ID": { + "type": "string", + "minLength": 1 + }, + "BUILD_ID": { + "type": "string", + "minLength": 1 + }, + "CONFIG_SCHEMA_VERSION": { + "type": "string", + "const": "2.0" + }, + "CAPABILITY_OVERRIDES": { + "default": { + "REALTIME": "DEFAULT", + "WEB_WORKER": "DEFAULT", + "SERVICE_WORKER": "DEFAULT", + "OFFLINE_COMMANDS": "DEFAULT" + }, + "type": "object", + "properties": { + "REALTIME": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "WEB_WORKER": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "SERVICE_WORKER": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + }, + "OFFLINE_COMMANDS": { + "default": "DEFAULT", + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + } + }, + "required": [ + "REALTIME", + "WEB_WORKER", + "SERVICE_WORKER", + "OFFLINE_COMMANDS" + ], + "additionalProperties": false + }, + "FEATURE_OVERRIDES": { + "default": {}, + "type": "object", + "propertyNames": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]{0,63}$" + }, + "additionalProperties": { + "type": "string", + "enum": [ + "DEFAULT", + "DISABLED" + ] + } + } + }, + "required": [ + "APP_ENV", + "API_BASE_URL", + "REQUEST_TIMEOUT_MS", + "MAX_RETRY_ATTEMPTS", + "TELEMETRY_ENABLED", + "AUTH_MODE", + "RELEASE_MANIFEST_URL", + "CONFIG_SCHEMA_VERSION", + "CAPABILITY_OVERRIDES", + "FEATURE_OVERRIDES" + ], + "additionalProperties": false +} diff --git a/docs/contracts/compatibility.md b/docs/contracts/compatibility.md index 1e3dbf56..46ec1b18 100644 --- a/docs/contracts/compatibility.md +++ b/docs/contracts/compatibility.md @@ -3,13 +3,66 @@ The blocking tuple is `(buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId)`. Versions are parsed numerically. -1. additive changes preserve current required fields -2. breaking changes require a major version bump +1. a change is additive only when it adds an optional field that every + reader of the previous version tolerates; see the boundary table below +2. breaking changes require a major version bump or a reader-first deployment 3. persisted cache is discarded unless an explicit tested migration exists 4. an incompatible config or API contract blocks product mount 5. rollback restores HTML, assets, runtime config, API compatibility, and release manifest as one coherent set +## Per-boundary rules + +Whether "add a field" is safe depends on the reader, not on the writer. Old +readers stay alive: several tabs, cached app shells and rollbacks are all +supported. At a `REJECT_UNKNOWN` boundary an added field is breaking, so the +reader that accepts it must ship before any writer sends it. + +| Boundary | Reader policy | Adding a field or value | Code | +|---|---|---|---| +| Runtime config V2 (`/config.json`) | strict object; `CONFIG_SCHEMA_VERSION` is the literal `"2.0"` | breaking | `src/contracts/release-artifacts.ts:163-171` | +| `CAPABILITY_OVERRIDES` | strict; unknown capability rejected | breaking | `src/contracts/release-artifacts.ts:50-63` | +| `FEATURE_OVERRIDES` | record; unknown feature id ignored | additive | `src/contracts/release-artifacts.ts:65-80` | +| Release manifest V2 | strict object | breaking | `src/contracts/release-artifacts.ts:200-208` | +| HTTP V2 success/failure envelope | strict object (`meta` strips) | breaking | `src/adapters/http/schema-registry.ts:12-34` | +| HTTP V3 response DTO (reference feature) | `.strip()` drops unknown fields | additive | `src/features/reference-feature/contracts/reference-schemas.ts:29-35` | +| Realtime envelope | exact key set; unknown `eventType` is `MALFORMED_EVENT` | breaking | `src/adapters/realtime/event-codec.ts:126,149` | +| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | `src/adapters/browser-rpc/browser-rpc-runtime.ts:1473` | +| Persisted client storage | versioned key; incompatible value discarded | use a new key version | `src/contracts/storage-keys.ts:138-140` | + +`CAPABILITY_OVERRIDES` and `FEATURE_OVERRIDES` differ on purpose. Feature ids +vary per build because each downstream project installs its own features, and +one shared config document may cover several builds. The capability set is +fixed by the platform version, so an unknown capability means the config was +written for a newer platform; it is treated like any other strict config +addition. + +## Schema change classifier and FE-GATE-014 + +`classifyObjectSchemaChange` (`src/contracts/compatibility.ts:110`) answers +for a reader built against `before`. It is fail-closed: only a new property +under a reader without `additionalProperties: false` is `additive`. A removed +or changed property (type, enum, nullable, format, ...), a different required +set, or any other changed keyword is `breaking`. Nothing differs: `none`. + +FE-GATE-014 (`config-compatibility`, `corepack pnpm verify:compatibility`) +runs `scripts/check-compatibility.ts`. It does two things: + +1. Classifies the hand-written cases in `config/compatibility/fixtures.json` + and fails if any result differs from `expected`. +2. Compares the committed baseline + `config/compatibility/runtime-config.schema.baseline.json` with the current + runtime config schema, which is the same `z.toJSONSchema` output the build + writes to `dist/runtime-config.schema.json` + (`scripts/generate-build-manifest.ts`). A `breaking` result fails the gate. + +The baseline stands for the schema that readers of the previous release +accept. When a breaking config change is intended, deploy the reader first (or +bump the config major version), then run +`corepack pnpm verify:compatibility --update-baseline` and commit the new +baseline with the change. The result is recorded in +`artifacts/release/compatibility.json`. + The current `apiContractVersion` check proves release/config coherence, not provider conformance by itself. The target multi-protocol contract set binds REST/OpenAPI artifacts, GraphQL schema and persisted-operation manifests, diff --git a/scripts/check-compatibility.ts b/scripts/check-compatibility.ts index 32f3a9ba..686a03aa 100644 --- a/scripts/check-compatibility.ts +++ b/scripts/check-compatibility.ts @@ -1,53 +1,72 @@ -import { mkdir, readFile } from "node:fs/promises"; +import { mkdir, readFile, writeFile } from "node:fs/promises"; -import { classifyObjectSchemaChange } from "../src/contracts/compatibility.ts"; +import { z } from "zod"; + +import { + classifyObjectSchemaChange, + type ObjectSchemaShape, + type SchemaChangeClassification, +} from "../src/contracts/compatibility.ts"; +import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts"; import { compatibilityFixturesArtifactSchema } from "./contracts/release-artifacts.ts"; import { writeValidatedJsonArtifact } from "./lib/validated-json-artifact.ts"; -type CompatibilitySchema = Readonly<{ - required?: readonly string[]; - properties?: Readonly>; -}>; - -type CompatibilityFixture = Readonly<{ - before: CompatibilitySchema; - after: CompatibilitySchema; -}>; +// FE-GATE-014 (07-02, 13-10). The committed baseline stands in for the schema +// the previous release's reader accepts; the current schema is exactly what +// the build writes to dist/runtime-config.schema.json. +const BASELINE_PATH = "config/compatibility/runtime-config.schema.baseline.json"; type CompatibilityFixtures = Readonly<{ - families: Readonly< - Record>> - >; + cases: readonly Readonly<{ + id: string; + expected: SchemaChangeClassification; + before: ObjectSchemaShape; + after: ObjectSchemaShape; + }>[]; }>; +const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema); +if (process.argv.includes("--update-baseline")) { + await writeFile(BASELINE_PATH, `${JSON.stringify(current, null, 2)}\n`); + process.stdout.write(`Updated ${BASELINE_PATH}\n`); + process.exit(0); +} + const fixtures = JSON.parse( await readFile("config/compatibility/fixtures.json", "utf8"), ) as CompatibilityFixtures; -const results = []; +const results = fixtures.cases.map(({ id, expected, before, after }) => { + const actual = classifyObjectSchemaChange(before, after); + return { id, expected, actual, passed: actual === expected }; +}); -for (const [family, cases] of Object.entries(fixtures.families)) { - for (const expected of ["additive", "breaking"] as const) { - const fixture = cases[expected]; - const actual = classifyObjectSchemaChange(fixture.before, fixture.after); - results.push({ family, expected, actual, passed: actual === expected }); - } -} +const baselineClassification = classifyObjectSchemaChange( + JSON.parse(await readFile(BASELINE_PATH, "utf8")) as ObjectSchemaShape, + current as ObjectSchemaShape, +); +const baseline = { + path: BASELINE_PATH, + classification: baselineClassification, + passed: baselineClassification !== "breaking", +}; await mkdir("artifacts/release", { recursive: true }); await writeValidatedJsonArtifact({ path: "artifacts/release/compatibility.json", schema: compatibilityFixturesArtifactSchema, value: { - schemaVersion: 1, + schemaVersion: 2, generatedAt: new Date().toISOString(), rules: [ - "additive changes preserve required fields", - "breaking changes require version bump and migration, discard, fallback, or rollback", + "a change is additive only when it adds a property under a reader that tolerates unknown keys", + "type, enum, nullable, required-set and unmodelled changes are breaking (fail-closed)", + "adding a field at a strict (REJECT_UNKNOWN) boundary is breaking: deploy the reader first", "config and API major versions must match", "incompatible persisted cache is discarded by default", "rollback uses a coherent compatibility tuple", ], results, + baseline, }, }); @@ -55,4 +74,14 @@ if (results.some((result) => !result.passed)) { process.stderr.write("Compatibility fixture classification failed.\n"); process.exit(1); } -process.stdout.write("Compatibility fixtures: PASS\n"); +if (!baseline.passed) { + process.stderr.write( + `Runtime config schema change is breaking for readers of ${BASELINE_PATH}.\n` + + "Follow docs/contracts/compatibility.md (deploy readers first), then run\n" + + "`corepack pnpm verify:compatibility --update-baseline` and commit the baseline.\n", + ); + process.exit(1); +} +process.stdout.write( + `Compatibility fixtures: PASS; runtime config schema vs baseline: ${baseline.classification}\n`, +); diff --git a/scripts/contracts/release-artifacts.ts b/scripts/contracts/release-artifacts.ts index 51774877..b4fd743f 100644 --- a/scripts/contracts/release-artifacts.ts +++ b/scripts/contracts/release-artifacts.ts @@ -1338,32 +1338,41 @@ export const supplyChainProviderFixturesArtifactSchema = z } }); -const compatibilityClassificationSchema = z.enum(["additive", "breaking"]); +const compatibilityClassificationSchema = z.enum(["additive", "breaking", "none"]); export const compatibilityFixturesArtifactSchema = z .object({ - schemaVersion: z.literal(1), + schemaVersion: z.literal(2), generatedAt: timestamp, - rules: z.array(nonEmptyString).length(5), + rules: z.array(nonEmptyString).min(1), results: z.array( z .object({ - family: z.enum(["api", "config", "storage", "release"]), + id: nonEmptyString, expected: compatibilityClassificationSchema, actual: compatibilityClassificationSchema, passed: z.boolean(), }) .strict(), - ).length(8), + ).min(1), + baseline: z + .object({ + path: nonEmptyString, + classification: compatibilityClassificationSchema, + passed: z.boolean(), + }) + .strict(), }) .strict() .superRefine((artifact, context) => { - const keys = artifact.results.map(({ family, expected }) => `${family}\0${expected}`); - addUniqueStringIssues(keys, ["results"], context); + addUniqueStringIssues(artifact.results.map(({ id }) => id), ["results"], context); artifact.results.forEach((result, index) => { if (result.passed !== (result.actual === result.expected)) { context.addIssue({ code: "custom", path: ["results", index, "passed"], message: "must agree with expected and actual" }); } }); + if (artifact.baseline.passed !== (artifact.baseline.classification !== "breaking")) { + context.addIssue({ code: "custom", path: ["baseline", "passed"], message: "must fail exactly when the baseline change is breaking" }); + } }); export const documentationReviewArtifactSchema = z diff --git a/src/contracts/compatibility.ts b/src/contracts/compatibility.ts index 486a9548..4d0b42de 100644 --- a/src/contracts/compatibility.ts +++ b/src/contracts/compatibility.ts @@ -82,26 +82,63 @@ export function verifyCompatibilityTuple(input: Readonly<{ export type ObjectSchemaShape = Readonly<{ required?: readonly string[]; properties?: Readonly>; + additionalProperties?: unknown; }>; export type SchemaChangeClassification = "breaking" | "additive" | "none"; +function canonicalJson(value: unknown): string { + return JSON.stringify(value, (_key, item: unknown) => + item && typeof item === "object" && !Array.isArray(item) + ? Object.fromEntries( + Object.entries(item).sort(([left], [right]) => + left < right ? -1 : left > right ? 1 : 0, + ), + ) + : item, + ); +} + +/** + * Classifies an object schema change as seen by a reader built against + * `before` (07-02, 13-10). Fail-closed: the only "additive" change is a new + * property under a reader that tolerates unknown keys. Anything else that + * differs — removed or changed properties (type, enum, nullable, ...), a + * different required set, a new property under `additionalProperties: false`, + * or any other keyword — is "breaking". + */ export function classifyObjectSchemaChange( before: ObjectSchemaShape, after: ObjectSchemaShape, ): SchemaChangeClassification { - const beforeRequired = new Set(before.required ?? []); - const afterRequired = new Set(after.required ?? []); - const removedProperties = Object.keys(before.properties ?? {}).filter( - (key) => !(key in (after.properties ?? {})), + const { + properties: beforeProperties = {}, + required: beforeRequired = [], + ...beforeRest + } = before; + const { + properties: afterProperties = {}, + required: afterRequired = [], + ...afterRest + } = after; + if ( + canonicalJson(beforeRest) !== canonicalJson(afterRest) || + canonicalJson([...beforeRequired].sort()) !== + canonicalJson([...afterRequired].sort()) + ) { + return "breaking"; + } + for (const [key, schema] of Object.entries(beforeProperties)) { + if ( + !Object.hasOwn(afterProperties, key) || + canonicalJson(schema) !== canonicalJson(afterProperties[key]) + ) { + return "breaking"; + } + } + const added = Object.keys(afterProperties).filter( + (key) => !Object.hasOwn(beforeProperties, key), ); - const addedRequired = [...afterRequired].filter( - (key) => !beforeRequired.has(key), - ); - if (removedProperties.length > 0 || addedRequired.length > 0) return "breaking"; - - const addedProperties = Object.keys(after.properties ?? {}).filter( - (key) => !(key in (before.properties ?? {})), - ); - return addedProperties.length > 0 ? "additive" : "none"; + if (added.length === 0) return "none"; + return before.additionalProperties === false ? "breaking" : "additive"; } diff --git a/tests/unit/compatibility.test.ts b/tests/unit/compatibility.test.ts index bc0654e7..2666d5e0 100644 --- a/tests/unit/compatibility.test.ts +++ b/tests/unit/compatibility.test.ts @@ -1,4 +1,7 @@ +import { readFileSync } from "node:fs"; + import { describe, expect, it } from "vitest"; +import { z } from "zod"; import { classifyObjectSchemaChange, @@ -6,6 +9,7 @@ import { parseNumericVersion, verifyCompatibilityTuple, } from "../../src/contracts/compatibility.ts"; +import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts"; describe("contract compatibility", () => { it("uses numeric version parsing rather than lexical comparison", () => { @@ -15,6 +19,11 @@ describe("contract compatibility", () => { expect(isVersionCompatible("next", "1.0")).toBe(false); }); + it("rejects a runtime whose minor version is lower than the supported one", () => { + expect(isVersionCompatible("2.1", "2.0")).toBe(false); + expect(isVersionCompatible("2.1", "2.1")).toBe(true); + }); + it("distinguishes additive and breaking object changes", () => { const base = { required: ["id"], properties: { id: {} } }; expect( @@ -31,6 +40,74 @@ describe("contract compatibility", () => { ).toBe("breaking"); }); + it("classifies changes it cannot prove compatible as breaking", () => { + const base = { + required: ["id"], + properties: { + id: { type: "string" }, + state: { type: "string", enum: ["A", "B"] }, + note: { type: "string" }, + }, + }; + const withProperty = (key: string, schema: unknown) => ({ + ...base, + properties: { ...base.properties, [key]: schema }, + }); + expect(classifyObjectSchemaChange(base, base)).toBe("none"); + expect( + classifyObjectSchemaChange(base, withProperty("id", { type: "number" })), + ).toBe("breaking"); + expect( + classifyObjectSchemaChange( + base, + withProperty("state", { type: "string", enum: ["A"] }), + ), + ).toBe("breaking"); + expect( + classifyObjectSchemaChange( + base, + withProperty("note", { type: ["string", "null"] }), + ), + ).toBe("breaking"); + expect(classifyObjectSchemaChange(base, { ...base, required: [] })).toBe( + "breaking", + ); + expect( + classifyObjectSchemaChange(base, { ...base, additionalProperties: false }), + ).toBe("breaking"); + }); + + it("treats a property added under a reader that rejects unknown keys as breaking", () => { + const strict = { + required: ["id"], + properties: { id: {} }, + additionalProperties: false, + }; + expect( + classifyObjectSchemaChange(strict, { + ...strict, + properties: { id: {}, displayName: {} }, + }), + ).toBe("breaking"); + }); + + it("classifies an optional runtime config key as breaking against the committed baseline", () => { + const baseline = JSON.parse( + readFileSync("config/compatibility/runtime-config.schema.baseline.json", "utf8"), + ) as Record; + const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema) as Record< + string, + unknown + > & { properties: Record }; + expect(classifyObjectSchemaChange(baseline, current)).toBe("none"); + expect( + classifyObjectSchemaChange(baseline, { + ...current, + properties: { ...current.properties, NEW_OPTIONAL_KEY: { type: "string" } }, + }), + ).toBe("breaking"); + }); + it("treats release ID mismatch as a warning when the blocking tuple is coherent", () => { const frontend = { buildId: "build-a",