From 17d617ab7a5d34bb4d74985e5838e683729b95d8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:04:25 +0900 Subject: [PATCH 1/9] 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", From c9360638fd2ba16b51b6029f633b0ef4c74d80f9 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:09:11 +0900 Subject: [PATCH 2/9] test(contracts): require installed V2 operation rows to match their V3 descriptors (07-03) FE-REG-API governs the V2 rows but the V3 descriptors execute, so a V3 path or limit change passed every check. The test compares method, path, success statuses, response limit, auth profile and replay policy per operationId. Co-Authored-By: Claude Opus 5.5 --- .../unit/http-operation-v2-v3-parity.test.ts | 56 +++++++++++++++++++ 1 file changed, 56 insertions(+) create mode 100644 tests/unit/http-operation-v2-v3-parity.test.ts diff --git a/tests/unit/http-operation-v2-v3-parity.test.ts b/tests/unit/http-operation-v2-v3-parity.test.ts new file mode 100644 index 00000000..bb6fe398 --- /dev/null +++ b/tests/unit/http-operation-v2-v3-parity.test.ts @@ -0,0 +1,56 @@ +import { describe, expect, it } from "vitest"; + +import type { + ApiOperation, + RestOperationV2, +} from "../../src/contracts/api-operations.ts"; +import { INSTALLED_CONTRACT_CONTRIBUTIONS } from "../../src/features/installed-contract-contributions.ts"; +import { API_OPERATIONS } from "../../src/features/installed-feature-contracts.ts"; + +// 07-03 (D-7). FE-REG-API governs the V2 rows while the V3 descriptors are +// what executes. Until V2 is generated from V3, both copies must agree. +const RETRY_SEMANTICS_FOR_REPLAY_POLICY = Object.freeze({ + SAFE: "SAFE", + IDEMPOTENT: "IDEMPOTENT", + KEYED_COMMAND: "KEYED", + NON_REPLAYABLE: "NEVER", +} as const); + +const v3ByOperationId = new Map( + INSTALLED_CONTRACT_CONTRIBUTIONS.flatMap((contribution) => + contribution.http.map( + (descriptor) => [descriptor.contract.operationId, descriptor] as const, + ), + ), +); +const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter( + (operation): operation is RestOperationV2 => operation.contractVersion === 2, +); + +describe("HTTP operation V2 rows and V3 descriptors", () => { + it("declare the same method, path, statuses, limit, auth profile and replay policy", () => { + for (const row of v2Rows) { + const descriptor = v3ByOperationId.get(row.operationId); + expect(descriptor, `${row.operationId} has no V3 descriptor`).toBeDefined(); + if (!descriptor) continue; + expect( + { + method: descriptor.contract.method, + path: descriptor.contract.pathTemplate, + successStatuses: [...descriptor.contract.acceptedStatuses], + maxResponseBytes: descriptor.frontend.responseByteLimit, + authProfileId: descriptor.frontend.authProfileId, + retrySemantics: descriptor.contract.retrySemantics, + }, + row.operationId, + ).toEqual({ + method: row.method, + path: row.path, + successStatuses: [...row.successStatuses], + maxResponseBytes: row.maxResponseBytes, + authProfileId: row.authProfileId, + retrySemantics: RETRY_SEMANTICS_FOR_REPLAY_POLICY[row.replayPolicy], + }); + } + }); +}); From aff5f43652bb7f59201cb341171c428d1e5e980f Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:16:55 +0900 Subject: [PATCH 3/9] fix(contracts): drop unread error registry fields and pin the createFailure effect rule (07-04) Nothing read severity, telemetryEvent or redaction, yet FE-REG-ERROR guarded them as policy. They are removed and the registry baseline is re-approved. A new test fails if createFailure stops clearing retryable for MAYBE_APPLIED (M1). Co-Authored-By: Claude Opus 5.5 --- .../contracts/registry-baseline.approval.json | 6 +- config/contracts/registry-baseline.json | 529 ++---------------- config/contracts/registry-governance.json | 13 +- src/contracts/errors.ts | 203 ++----- tests/unit/error-classification.test.ts | 49 +- 5 files changed, 124 insertions(+), 676 deletions(-) diff --git a/config/contracts/registry-baseline.approval.json b/config/contracts/registry-baseline.approval.json index a061482f..1c30ebaa 100644 --- a/config/contracts/registry-baseline.approval.json +++ b/config/contracts/registry-baseline.approval.json @@ -1,7 +1,7 @@ { "schemaVersion": 1, - "snapshotDigest": "96b95ef1d50cce36e9fca8a98776a9e2e9e3a5dca24a6288ad83bf29c94aebd8", + "snapshotDigest": "83d11f848b8b2f67bcb657403f112d4baaf05481ab6bcee94ebc6851c32e2159", "owner": "frontend-platform", - "reason": "Baseline canonical invalidation graph and topic-version contracts after FE-REG-QUERY retirement", - "approvedAt": "2026-08-01T15:15:45.537Z" + "reason": "07-04: FE-REG-ERROR drops severity, telemetryEvent and redaction, which nothing read", + "approvedAt": "2026-09-25T15:11:58.763Z" } diff --git a/config/contracts/registry-baseline.json b/config/contracts/registry-baseline.json index 5f21fa6e..46dc3ebb 100644 --- a/config/contracts/registry-baseline.json +++ b/config/contracts/registry-baseline.json @@ -640,7 +640,7 @@ "registryId": "FE-REG-ENV", "owner": "feature-frontend-env-runtime-config-contract", "source": "src/contracts/env.ts", - "rowCount": 14, + "rowCount": 16, "contract": { "requiredFields": [ "phase", @@ -706,6 +706,12 @@ "phase": "runtime", "required": true }, + "FEATURE_OVERRIDES": { + "classification": "public", + "defaultValue": null, + "phase": "runtime", + "required": false + }, "MAX_RETRY_ATTEMPTS": { "classification": "public", "defaultValue": 2, @@ -748,6 +754,12 @@ "phase": "build", "required": false }, + "VITE_PRODUCT_FEATURES": { + "classification": "compile-time", + "defaultValue": null, + "phase": "build", + "required": false + }, "VITE_ROUTER_BASE_PATH": { "classification": "compile-time", "defaultValue": "/", @@ -766,7 +778,7 @@ "registryId": "FE-REG-STORAGE", "owner": "feature-frontend-storage-registry-contract", "source": "src/contracts/storage-keys.ts", - "rowCount": 4, + "rowCount": 7, "contract": { "requiredFields": [ "logicalName", @@ -847,6 +859,19 @@ "ttl": null, "valueCodec": "none" }, + "CACHE_INVALIDATION_PULSE": { + "backend": "localStorage", + "classification": "opaque-cache", + "logicalName": "CACHE_INVALIDATION_PULSE", + "migration": "discard", + "name": "pulse", + "physicalKey": "ca-frontend:cache-invalidation:v1:pulse", + "quotaFallback": "no-persist", + "schemaVersion": 1, + "scope": "cache-invalidation", + "ttl": null, + "valueCodec": "opaque-string-v1" + }, "CHUNK_RELOAD_GUARD": { "backend": "sessionStorage", "classification": "opaque-cache", @@ -873,6 +898,19 @@ "ttl": null, "valueCodec": "color-scheme-v1" }, + "LOCALE": { + "backend": "localStorage", + "classification": "public-preference", + "logicalName": "LOCALE", + "migration": "discard", + "name": "locale", + "physicalKey": "ca-frontend:preference:v1:locale", + "quotaFallback": "memory", + "schemaVersion": 1, + "scope": "preference", + "ttl": null, + "valueCodec": "opaque-string-v1" + }, "QUERY_PERSISTENCE": { "backend": "disabled", "classification": "sensitive-forbidden", @@ -885,6 +923,19 @@ "scope": "cache", "ttl": null, "valueCodec": "none" + }, + "RELEASE_MISMATCH_RECOVERY": { + "backend": "sessionStorage", + "classification": "opaque-cache", + "logicalName": "RELEASE_MISMATCH_RECOVERY", + "migration": "discard", + "name": "boot-mismatch-recovery", + "physicalKey": "ca-frontend:release:v1:boot-mismatch-recovery", + "quotaFallback": "no-persist", + "schemaVersion": 1, + "scope": "release", + "ttl": "session", + "valueCodec": "opaque-string-v1" } } }, @@ -897,30 +948,19 @@ "requiredFields": [ "kind", "defaultRetryable", - "severity", "userMessageKey", - "action", - "telemetryEvent", - "redaction" + "action" ], "fieldTypes": { "kind": "string", "defaultRetryable": "boolean", - "severity": "string", "userMessageKey": "string", - "action": "string", - "telemetryEvent": "string", - "redaction": "array" + "action": "string" }, "uniqueFields": [ "kind" ], "allowedValues": { - "severity": [ - "info", - "warning", - "error" - ], "action": [ "retry", "reauth", @@ -935,8 +975,7 @@ "breakingFields": [ "kind", "userMessageKey", - "action", - "telemetryEvent" + "action" ] }, "rows": { @@ -944,684 +983,228 @@ "action": "contact-support", "defaultRetryable": false, "kind": "API_CONTRACT_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "app.boot.failed", "userMessageKey": "error.api_contract_mismatch" }, "ASSET_MISMATCH": { "action": "reload-once", "defaultRetryable": false, "kind": "ASSET_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "release.mismatch.detected", "userMessageKey": "error.asset_mismatch" }, "AUTH_INTEGRATION_FAILURE": { "action": "contact-support", "defaultRetryable": false, "kind": "AUTH_INTEGRATION_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.auth_integration_failure" }, "AUTH_REQUIRED": { "action": "reauth", "defaultRetryable": false, "kind": "AUTH_REQUIRED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.auth_required" }, "BOOT_CONFIG_FAILURE": { "action": "contact-support", "defaultRetryable": false, "kind": "BOOT_CONFIG_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "app.boot.failed", "userMessageKey": "error.boot_config_failure" }, "BUILD_MISMATCH": { "action": "reload-once", "defaultRetryable": false, "kind": "BUILD_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "release.mismatch.detected", "userMessageKey": "error.build_mismatch" }, "CHUNK_LOAD_FAILURE": { "action": "reload-once", "defaultRetryable": false, "kind": "CHUNK_LOAD_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "release.mismatch.detected", "userMessageKey": "error.chunk_load_failure" }, "CONFIG_MISMATCH": { "action": "contact-support", "defaultRetryable": false, "kind": "CONFIG_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "app.boot.failed", "userMessageKey": "error.config_mismatch" }, "CONFLICT": { "action": "retry", "defaultRetryable": false, "kind": "CONFLICT", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.conflict" }, "CONTENT_TYPE_MISMATCH": { "action": "contact-support", "defaultRetryable": false, "kind": "CONTENT_TYPE_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.content_type_mismatch" }, "DEPLOY_MISMATCH": { "action": "reload-once", "defaultRetryable": false, "kind": "DEPLOY_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "release.mismatch.detected", "userMessageKey": "error.deploy_mismatch" }, "DUPLICATE_IN_FLIGHT": { "action": "none", "defaultRetryable": false, "kind": "DUPLICATE_IN_FLIGHT", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.duplicate_in_flight" }, "ENVELOPE_MISMATCH": { "action": "contact-support", "defaultRetryable": false, "kind": "ENVELOPE_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.envelope_mismatch" }, "FORBIDDEN": { "action": "navigate", "defaultRetryable": false, "kind": "FORBIDDEN", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.forbidden" }, "IDENTITY_INTERN_LIMIT_EXCEEDED": { "action": "retry", "defaultRetryable": false, "kind": "IDENTITY_INTERN_LIMIT_EXCEEDED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.identity_intern_limit_exceeded" }, "MALFORMED_JSON": { "action": "contact-support", "defaultRetryable": false, "kind": "MALFORMED_JSON", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.malformed_json" }, "MAPPING_CONTRACT_VIOLATION": { "action": "contact-support", "defaultRetryable": false, "kind": "MAPPING_CONTRACT_VIOLATION", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.mapping_contract_violation" }, "NETWORK_UNREACHABLE": { "action": "retry", "defaultRetryable": true, "kind": "NETWORK_UNREACHABLE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.network_unreachable" }, "NOT_FOUND": { "action": "navigate", "defaultRetryable": false, "kind": "NOT_FOUND", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.not_found" }, "PAGINATION_CONTRACT_VIOLATION": { "action": "contact-support", "defaultRetryable": false, "kind": "PAGINATION_CONTRACT_VIOLATION", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.pagination_contract_violation" }, "QUERY_CACHE_FAILURE": { "action": "retry", "defaultRetryable": false, "kind": "QUERY_CACHE_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "query.cache.failed", "userMessageKey": "error.query_cache_failure" }, "RATE_LIMITED": { "action": "retry", "defaultRetryable": true, "kind": "RATE_LIMITED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.rate_limited" }, "RELEASE_MANIFEST_FAILURE": { "action": "contact-support", "defaultRetryable": false, "kind": "RELEASE_MANIFEST_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "app.boot.failed", "userMessageKey": "error.release_manifest_failure" }, "RELEASE_MISMATCH": { "action": "reload-once", "defaultRetryable": false, "kind": "RELEASE_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "release.mismatch.detected", "userMessageKey": "error.release_mismatch" }, "RENDER_FAILURE": { "action": "reload-once", "defaultRetryable": false, "kind": "RENDER_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "ui.render.failed", "userMessageKey": "error.render_failure" }, "REQUEST_ABORTED": { "action": "none", "defaultRetryable": false, "kind": "REQUEST_ABORTED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.request_aborted" }, "REQUEST_TIMEOUT": { "action": "retry", "defaultRetryable": true, "kind": "REQUEST_TIMEOUT", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.request_timeout" }, "RESPONSE_BODY_LIMIT": { "action": "contact-support", "defaultRetryable": false, "kind": "RESPONSE_BODY_LIMIT", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.response_body_limit" }, "RESULT_LIMIT_EXCEEDED": { "action": "contact-support", "defaultRetryable": false, "kind": "RESULT_LIMIT_EXCEEDED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.result_limit_exceeded" }, "SCHEMA_MISMATCH": { "action": "contact-support", "defaultRetryable": false, "kind": "SCHEMA_MISMATCH", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.schema_mismatch" }, "SCOPE_GENERATION_CHANGED": { "action": "none", "defaultRetryable": false, "kind": "SCOPE_GENERATION_CHANGED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.scope_generation_changed" }, "SERVER_FAILURE": { "action": "retry", "defaultRetryable": true, "kind": "SERVER_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.server_failure" }, "STORAGE_QUOTA_EXCEEDED": { "action": "none", "defaultRetryable": false, "kind": "STORAGE_QUOTA_EXCEEDED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "storage.operation.failed", "userMessageKey": "error.storage_quota_exceeded" }, "STORAGE_UNAVAILABLE": { "action": "none", "defaultRetryable": false, "kind": "STORAGE_UNAVAILABLE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "storage.operation.failed", "userMessageKey": "error.storage_unavailable" }, "TELEMETRY_FAILURE": { "action": "none", "defaultRetryable": false, "kind": "TELEMETRY_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "telemetry.delivery.dropped", "userMessageKey": "error.telemetry_failure" }, "UNKNOWN_CLIENT_FAILURE": { "action": "contact-support", "defaultRetryable": false, "kind": "UNKNOWN_CLIENT_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "warning", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.unknown_client_failure" }, "UNKNOWN_FAILURE": { "action": "contact-support", "defaultRetryable": false, "kind": "UNKNOWN_FAILURE", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "error", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.unknown_failure" }, "VALIDATION_REJECTED": { "action": "none", "defaultRetryable": false, "kind": "VALIDATION_REJECTED", - "redaction": [ - "authorization", - "body", - "cause", - "headers", - "query", - "stack", - "storageValue", - "url" - ], - "severity": "info", - "telemetryEvent": "api.request.failed", "userMessageKey": "error.validation_rejected" } } diff --git a/config/contracts/registry-governance.json b/config/contracts/registry-governance.json index 6de373e2..11eaa591 100644 --- a/config/contracts/registry-governance.json +++ b/config/contracts/registry-governance.json @@ -344,24 +344,17 @@ "requiredFields": [ "kind", "defaultRetryable", - "severity", "userMessageKey", - "action", - "telemetryEvent", - "redaction" + "action" ], "fieldTypes": { "kind": "string", "defaultRetryable": "boolean", - "severity": "string", "userMessageKey": "string", - "action": "string", - "telemetryEvent": "string", - "redaction": "array" + "action": "string" }, "uniqueFields": ["kind"], "allowedValues": { - "severity": ["info", "warning", "error"], "action": [ "retry", "reauth", @@ -377,7 +370,7 @@ "token": "failure(" } ], - "breakingFields": ["kind", "userMessageKey", "action", "telemetryEvent"] + "breakingFields": ["kind", "userMessageKey", "action"] }, { "registryId": "FE-REG-QUERY-INVALIDATION", diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index 86873b98..ed0a1f6d 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -1,5 +1,3 @@ -import type { DiagnosticEventId } from "./diagnostics.ts"; -import type { TelemetryEventName } from "./telemetry.ts"; import { projectValidationIssues, type ValidationIssue, @@ -7,17 +5,6 @@ import { export type { ValidationIssue } from "./validation-issues.ts"; -const DROP_SENSITIVE = Object.freeze([ - "cause", - "body", - "headers", - "authorization", - "url", - "query", - "stack", - "storageValue", -] as const); - export type ErrorAction = | "retry" | "reauth" @@ -26,208 +13,94 @@ export type ErrorAction = | "contact-support" | "none"; -export type ErrorObservationEvent = DiagnosticEventId | TelemetryEventName; - +/** + * 07-04. Every field has a reader: `createFailure` copies `defaultRetryable`, + * `userMessageKey` and `action`. Severity, telemetry event and redaction + * fields were removed because nothing read them — telemetry names its own + * events and `createFailure` drops sensitive details by copying an allowlist. + */ export type ErrorDefinition = Readonly<{ kind: Kind; defaultRetryable: boolean; - severity: string; userMessageKey: string; action: ErrorAction; - telemetryEvent: ErrorObservationEvent; - redaction: readonly string[]; }>; const row = ( kind: Kind, defaultRetryable: boolean, - severity: string, action: ErrorAction, - telemetryEvent: ErrorObservationEvent = "api.request.failed", ): ErrorDefinition => Object.freeze({ kind, defaultRetryable, - severity, userMessageKey: `error.${kind.toLowerCase()}`, action, - telemetryEvent, - redaction: DROP_SENSITIVE, }); export const ERROR_REGISTRY = Object.freeze({ - NETWORK_UNREACHABLE: row("NETWORK_UNREACHABLE", true, "warning", "retry"), - REQUEST_TIMEOUT: row("REQUEST_TIMEOUT", true, "warning", "retry"), - REQUEST_ABORTED: row("REQUEST_ABORTED", false, "info", "none"), - CONTENT_TYPE_MISMATCH: row( - "CONTENT_TYPE_MISMATCH", - false, - "error", - "contact-support", - ), - MALFORMED_JSON: row("MALFORMED_JSON", false, "error", "contact-support"), - RESPONSE_BODY_LIMIT: row( - "RESPONSE_BODY_LIMIT", - false, - "error", - "contact-support", - ), - ENVELOPE_MISMATCH: row("ENVELOPE_MISMATCH", false, "error", "contact-support"), - SCHEMA_MISMATCH: row("SCHEMA_MISMATCH", false, "error", "contact-support"), + NETWORK_UNREACHABLE: row("NETWORK_UNREACHABLE", true, "retry"), + REQUEST_TIMEOUT: row("REQUEST_TIMEOUT", true, "retry"), + REQUEST_ABORTED: row("REQUEST_ABORTED", false, "none"), + CONTENT_TYPE_MISMATCH: row("CONTENT_TYPE_MISMATCH", false, "contact-support"), + MALFORMED_JSON: row("MALFORMED_JSON", false, "contact-support"), + RESPONSE_BODY_LIMIT: row("RESPONSE_BODY_LIMIT", false, "contact-support"), + ENVELOPE_MISMATCH: row("ENVELOPE_MISMATCH", false, "contact-support"), + SCHEMA_MISMATCH: row("SCHEMA_MISMATCH", false, "contact-support"), MAPPING_CONTRACT_VIOLATION: row( "MAPPING_CONTRACT_VIOLATION", false, - "error", "contact-support", ), - RESULT_LIMIT_EXCEEDED: row( - "RESULT_LIMIT_EXCEEDED", - false, - "error", - "contact-support", - ), - SCOPE_GENERATION_CHANGED: row( - "SCOPE_GENERATION_CHANGED", - false, - "info", - "none", - ), + RESULT_LIMIT_EXCEEDED: row("RESULT_LIMIT_EXCEEDED", false, "contact-support"), + SCOPE_GENERATION_CHANGED: row("SCOPE_GENERATION_CHANGED", false, "none"), IDENTITY_INTERN_LIMIT_EXCEEDED: row( "IDENTITY_INTERN_LIMIT_EXCEEDED", false, - "warning", "retry", ), - DUPLICATE_IN_FLIGHT: row( - "DUPLICATE_IN_FLIGHT", - false, - "info", - "none", - ), + DUPLICATE_IN_FLIGHT: row("DUPLICATE_IN_FLIGHT", false, "none"), PAGINATION_CONTRACT_VIOLATION: row( "PAGINATION_CONTRACT_VIOLATION", false, - "error", "contact-support", ), - AUTH_REQUIRED: row("AUTH_REQUIRED", false, "info", "reauth"), + AUTH_REQUIRED: row("AUTH_REQUIRED", false, "reauth"), AUTH_INTEGRATION_FAILURE: row( "AUTH_INTEGRATION_FAILURE", false, - "error", "contact-support", ), - FORBIDDEN: row("FORBIDDEN", false, "warning", "navigate"), - NOT_FOUND: row("NOT_FOUND", false, "info", "navigate"), - CONFLICT: row("CONFLICT", false, "warning", "retry"), - VALIDATION_REJECTED: row("VALIDATION_REJECTED", false, "info", "none"), + FORBIDDEN: row("FORBIDDEN", false, "navigate"), + NOT_FOUND: row("NOT_FOUND", false, "navigate"), + CONFLICT: row("CONFLICT", false, "retry"), + VALIDATION_REJECTED: row("VALIDATION_REJECTED", false, "none"), UNKNOWN_CLIENT_FAILURE: row( "UNKNOWN_CLIENT_FAILURE", false, - "warning", "contact-support", ), - RATE_LIMITED: row("RATE_LIMITED", true, "warning", "retry"), - SERVER_FAILURE: row("SERVER_FAILURE", true, "error", "retry"), - CHUNK_LOAD_FAILURE: row( - "CHUNK_LOAD_FAILURE", - false, - "error", - "reload-once", - "release.mismatch.detected", - ), - BOOT_CONFIG_FAILURE: row( - "BOOT_CONFIG_FAILURE", - false, - "error", - "contact-support", - "app.boot.failed", - ), + RATE_LIMITED: row("RATE_LIMITED", true, "retry"), + SERVER_FAILURE: row("SERVER_FAILURE", true, "retry"), + CHUNK_LOAD_FAILURE: row("CHUNK_LOAD_FAILURE", false, "reload-once"), + BOOT_CONFIG_FAILURE: row("BOOT_CONFIG_FAILURE", false, "contact-support"), RELEASE_MANIFEST_FAILURE: row( "RELEASE_MANIFEST_FAILURE", false, - "error", "contact-support", - "app.boot.failed", ), - DEPLOY_MISMATCH: row( - "DEPLOY_MISMATCH", - false, - "error", - "reload-once", - "release.mismatch.detected", - ), - BUILD_MISMATCH: row( - "BUILD_MISMATCH", - false, - "error", - "reload-once", - "release.mismatch.detected", - ), - CONFIG_MISMATCH: row( - "CONFIG_MISMATCH", - false, - "error", - "contact-support", - "app.boot.failed", - ), - API_CONTRACT_MISMATCH: row( - "API_CONTRACT_MISMATCH", - false, - "error", - "contact-support", - "app.boot.failed", - ), - RELEASE_MISMATCH: row( - "RELEASE_MISMATCH", - false, - "error", - "reload-once", - "release.mismatch.detected", - ), - ASSET_MISMATCH: row( - "ASSET_MISMATCH", - false, - "error", - "reload-once", - "release.mismatch.detected", - ), - STORAGE_UNAVAILABLE: row( - "STORAGE_UNAVAILABLE", - false, - "warning", - "none", - "storage.operation.failed", - ), - STORAGE_QUOTA_EXCEEDED: row( - "STORAGE_QUOTA_EXCEEDED", - false, - "warning", - "none", - "storage.operation.failed", - ), - RENDER_FAILURE: row( - "RENDER_FAILURE", - false, - "error", - "reload-once", - "ui.render.failed", - ), - TELEMETRY_FAILURE: row( - "TELEMETRY_FAILURE", - false, - "info", - "none", - "telemetry.delivery.dropped", - ), - QUERY_CACHE_FAILURE: row( - "QUERY_CACHE_FAILURE", - false, - "error", - "retry", - "cache.operation.failed", - ), - UNKNOWN_FAILURE: row("UNKNOWN_FAILURE", false, "error", "contact-support"), + DEPLOY_MISMATCH: row("DEPLOY_MISMATCH", false, "reload-once"), + BUILD_MISMATCH: row("BUILD_MISMATCH", false, "reload-once"), + CONFIG_MISMATCH: row("CONFIG_MISMATCH", false, "contact-support"), + API_CONTRACT_MISMATCH: row("API_CONTRACT_MISMATCH", false, "contact-support"), + RELEASE_MISMATCH: row("RELEASE_MISMATCH", false, "reload-once"), + ASSET_MISMATCH: row("ASSET_MISMATCH", false, "reload-once"), + STORAGE_UNAVAILABLE: row("STORAGE_UNAVAILABLE", false, "none"), + STORAGE_QUOTA_EXCEEDED: row("STORAGE_QUOTA_EXCEEDED", false, "none"), + RENDER_FAILURE: row("RENDER_FAILURE", false, "reload-once"), + TELEMETRY_FAILURE: row("TELEMETRY_FAILURE", false, "none"), + QUERY_CACHE_FAILURE: row("QUERY_CACHE_FAILURE", false, "retry"), + UNKNOWN_FAILURE: row("UNKNOWN_FAILURE", false, "contact-support"), }); /** diff --git a/tests/unit/error-classification.test.ts b/tests/unit/error-classification.test.ts index 90ad93f0..389becc5 100644 --- a/tests/unit/error-classification.test.ts +++ b/tests/unit/error-classification.test.ts @@ -7,35 +7,17 @@ import { normalizeUnknownFailure, withFailureEffect, } from "../../src/contracts/errors.ts"; -import { DIAGNOSTIC_EVENT_REGISTRY } from "../../src/contracts/diagnostics.ts"; -import { TELEMETRY_REGISTRY } from "../../src/contracts/telemetry.ts"; describe("frontend failure classification", () => { - it("defines all stable error kinds with the seven contract fields", () => { + it("defines all stable error kinds with the four contract fields", () => { expect(Object.keys(ERROR_REGISTRY)).toHaveLength(38); for (const definition of Object.values(ERROR_REGISTRY)) { - expect(definition).toEqual( - expect.objectContaining({ - kind: expect.any(String), - defaultRetryable: expect.any(Boolean), - severity: expect.any(String), - userMessageKey: expect.any(String), - action: expect.any(String), - telemetryEvent: expect.any(String), - redaction: expect.any(Array), - }), - ); - } - }); - - it("references only registered observability events", () => { - const registeredEvents = new Set([ - ...Object.keys(DIAGNOSTIC_EVENT_REGISTRY), - ...Object.keys(TELEMETRY_REGISTRY), - ]); - - for (const definition of Object.values(ERROR_REGISTRY)) { - expect(registeredEvents.has(definition.telemetryEvent)).toBe(true); + expect(Object.keys(definition).sort()).toEqual([ + "action", + "defaultRetryable", + "kind", + "userMessageKey", + ]); } }); @@ -65,6 +47,23 @@ describe("frontend failure classification", () => { ).toMatchObject({ action: "contact-support" }); }); + it("never marks a failure retryable once the write may or did take effect (07-04)", () => { + expect(ERROR_REGISTRY.SERVER_FAILURE.defaultRetryable).toBe(true); + expect(createFailure("SERVER_FAILURE", "CREATE", 0).retryable).toBe(true); + expect( + createFailure("SERVER_FAILURE", "CREATE", 0, { effect: "MAYBE_APPLIED" }), + ).toMatchObject({ retryable: false, action: "contact-support" }); + expect( + createFailure("SERVER_FAILURE", "CREATE", 0, { + effect: "APPLIED_CONFIRMED", + }), + ).toMatchObject({ retryable: false, action: "none" }); + expect( + createFailure("SERVER_FAILURE", "CREATE", 0, { effect: "NOT_APPLIED" }) + .retryable, + ).toBe(true); + }); + it("projects only allowlisted safe fields", () => { const untrustedDetails = { code: "TEMPORARY", From 710436bc2ea29e9ffb3dfaeed60215ff9a537c75 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:22:08 +0900 Subject: [PATCH 4/9] fix(ci): pin each diagnostics fixture violation with its own ts-expect-error (07-05) The gate only matched one diagnostic string, so widening the telemetry event name or the diagnostic level still counted as the expected failure. Each violation now has its own directive and the fixture must compile cleanly. Co-Authored-By: Claude Opus 5.5 --- config/ci/gates.json | 4 +--- tests/fixtures/typecheck/invalid-diagnostics-port.ts | 9 +++++++++ tests/unit/ci-workflow-generation.test.ts | 2 +- 3 files changed, 11 insertions(+), 4 deletions(-) diff --git a/config/ci/gates.json b/config/ci/gates.json index 3778db53..b4ea16ec 100644 --- a/config/ci/gates.json +++ b/config/ci/gates.json @@ -177,9 +177,7 @@ { "id": "check-types-fixture-diagnostics", "script": "check:types:fixture:diagnostics", - "expect": "fail", - "expectedExitCode": 1, - "expectedDiagnosticId": "UNKNOWN_DIAGNOSTIC_EVENT" + "expect": "pass" }, { "id": "check-types-fixture-image-resolve-signal", diff --git a/tests/fixtures/typecheck/invalid-diagnostics-port.ts b/tests/fixtures/typecheck/invalid-diagnostics-port.ts index abe7fcdc..68861186 100644 --- a/tests/fixtures/typecheck/invalid-diagnostics-port.ts +++ b/tests/fixtures/typecheck/invalid-diagnostics-port.ts @@ -4,8 +4,17 @@ import type { TelemetryPort } from "../../../src/application/ports/telemetry-por declare const diagnostics: DiagnosticsPort; declare const telemetry: TelemetryPort; +// 07-05. One violation per directive: if a port type widens, its directive +// becomes unused (TS2578) and this fixture stops compiling. diagnostics.record({ + // @ts-expect-error "fatal" is not a diagnostic level. level: "fatal", + eventId: "route.changed", +}); +diagnostics.record({ + level: "info", + // @ts-expect-error the diagnostic event id is not registered. eventId: "UNKNOWN_DIAGNOSTIC_EVENT", }); +// @ts-expect-error the telemetry event name is not registered. telemetry.emit("unknown.telemetry.event", {}); diff --git a/tests/unit/ci-workflow-generation.test.ts b/tests/unit/ci-workflow-generation.test.ts index e237df08..0866cc38 100644 --- a/tests/unit/ci-workflow-generation.test.ts +++ b/tests/unit/ci-workflow-generation.test.ts @@ -196,7 +196,7 @@ describe("CI gate contract", () => { expect(contract.jobs).toHaveLength(9); expect(contract.commands).toHaveLength(95); expect(contract.gates.reduce((total, gate) => total + gate.commandIds.length, 0)).toBe(105); - expect(contract.commands.filter(({ expect }) => expect === "fail")).toHaveLength(31); + expect(contract.commands.filter(({ expect }) => expect === "fail")).toHaveLength(30); expect(contract.gates.reduce((total, gate) => total + gate.evidenceArtifactIds.length, 0)).toBe(87); expect(contract.artifacts).toHaveLength(109); expect(contract.stages).toHaveLength(5); From 0bcee348c59b13b10b3b254c74c45afda3496018 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:26:10 +0900 Subject: [PATCH 5/9] fix(contracts): report malformed validator results as THROWN instead of throwing (07-06) invokeValidator spread result.issues outside its try and treated any truthy success as valid, so a hand-written validator could throw past the executor or pass unchecked data. The result is now read inside the try and checked. Co-Authored-By: Claude Opus 5.5 --- src/contracts/external-contract-runtime.ts | 31 +++++++++++------- tests/unit/external-contract-runtime.test.ts | 33 ++++++++++++++++++++ 2 files changed, 52 insertions(+), 12 deletions(-) diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index ca930d11..31e1333f 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -72,22 +72,29 @@ export function invokeValidator( validator: RuntimeValidator, value: unknown, ): ValidatorInvocation { - let result: RuntimeValidationResult; + // 07-06. Reading the result stays inside the try: a hand-written validator + // may return any shape, including throwing getters. try { - result = validator.safeParse(value); + const result: unknown = validator.safeParse(value); + if (!result || typeof result !== "object") throw new TypeError(); + const candidate = result as Readonly>; + if (candidate.success === true) { + return Object.freeze({ + outcome: "VALID" as const, + value: candidate.data as T, + }); + } + const issues = candidate.issues; + if (candidate.success !== false || !Array.isArray(issues)) { + throw new TypeError(); + } + return Object.freeze({ + outcome: "INVALID" as const, + issues: Object.freeze([...(issues as RuntimeValidationIssue[])]), + }); } catch { return Object.freeze({ outcome: "THROWN" as const }); } - if (!result || typeof result !== "object" || !("success" in result)) { - return Object.freeze({ outcome: "THROWN" as const }); - } - if (result.success) { - return Object.freeze({ outcome: "VALID" as const, value: result.data }); - } - return Object.freeze({ - outcome: "INVALID" as const, - issues: Object.freeze([...(result.issues ?? [])]), - }); } export type MappingResult = diff --git a/tests/unit/external-contract-runtime.test.ts b/tests/unit/external-contract-runtime.test.ts index 24a26110..421dfe87 100644 --- a/tests/unit/external-contract-runtime.test.ts +++ b/tests/unit/external-contract-runtime.test.ts @@ -3,7 +3,9 @@ import { describe, expect, it } from "vitest"; import { ContractContributionError, composeContractContributions, + invokeValidator, type InstalledContractContribution, + type RuntimeValidator, } from "../../src/contracts/external-contract-runtime.ts"; import { TEST_CONTRACT_CONTRIBUTION } from "../helpers/external-contract-fixture.ts"; @@ -83,3 +85,34 @@ describe("external contract contribution composition", () => { expect(error.reason).toContain("method"); }); }); + +describe("validator invocation (07-06)", () => { + const returning = (result: unknown): RuntimeValidator => ({ + schemaId: "Malformed", + safeParse: () => result as never, + }); + + it.each([ + ["non-array issues", { success: false, issues: 5 }], + ["object issues", { success: false, issues: {} }], + ["non-boolean success", { success: "no", data: "unchecked" }], + ["throwing issues getter", { + success: false, + get issues(): never { + throw new Error("hostile"); + }, + }], + ])("reports THROWN for a result with %s", (_label, result) => { + expect(invokeValidator(returning(result), {})).toEqual({ outcome: "THROWN" }); + }); + + it("keeps well-formed results", () => { + expect(invokeValidator(returning({ success: true, data: 1 }), {})).toEqual({ + outcome: "VALID", + value: 1, + }); + expect( + invokeValidator(returning({ success: false, issues: [{ path: [], code: "X" }] }), {}), + ).toEqual({ outcome: "INVALID", issues: [{ path: [], code: "X" }] }); + }); +}); From 9e616d3a06337ed5ad872a41b00ac4e0bda65715 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:28:27 +0900 Subject: [PATCH 6/9] docs(contracts): mark compatibility aliases and V1 readers deprecated with removal conditions (07-07) The aliases and V1 config/manifest readers had no @deprecated tag, replacement or removal condition in code, so they could only become permanent. Co-Authored-By: Claude Opus 5.5 --- src/contracts/boundary-mapper.ts | 8 +++++++- src/contracts/errors.ts | 5 +++-- src/contracts/read-only-registry.ts | 6 +++++- src/contracts/release-artifacts.ts | 14 ++++++++++++++ 4 files changed, 29 insertions(+), 4 deletions(-) diff --git a/src/contracts/boundary-mapper.ts b/src/contracts/boundary-mapper.ts index 5b21f7b3..1116d927 100644 --- a/src/contracts/boundary-mapper.ts +++ b/src/contracts/boundary-mapper.ts @@ -14,7 +14,13 @@ export type BoundaryMappingResult = | Readonly<{ ok: true; value: Value }> | Readonly<{ ok: false; code: MappingFailureCode }>; -/** Compatible alias kept for existing importers; see `BoundaryMappingResult`. */ +/** + * Compatible alias kept for existing importers. + * + * @deprecated Use `BoundaryMappingResult`. Remove in the next minor release + * once no module imports `MappingResult` from this file (owner: + * frontend-platform). + */ export type MappingResult = BoundaryMappingResult; /** Adapts a boundary mapper result to the canonical contract mapping result. */ diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index ed0a1f6d..a434a261 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -135,9 +135,10 @@ export type AppFailure = Readonly<{ }>; /** - * Backward-compatible transport-facing name. New application and presentation - * code should prefer AppFailure. + * Backward-compatible transport-facing name. * + * @deprecated Use `AppFailure`. Remove in the next minor release once + * `grep -rw ApiFailure src` finds only this line (owner: frontend-platform). */ export type ApiFailure = AppFailure; diff --git a/src/contracts/read-only-registry.ts b/src/contracts/read-only-registry.ts index a9ecfe3b..1fc16bb3 100644 --- a/src/contracts/read-only-registry.ts +++ b/src/contracts/read-only-registry.ts @@ -61,5 +61,9 @@ export function createReadOnlyMap( return readOnlyFacade(entries); } -/** Kept here for existing importers; the implementation lives in `exact-snapshot.ts`. */ +/** + * @deprecated Import `exactOwnDataSnapshot` from `./exact-snapshot.ts`. Kept for + * downstream importers; remove in the next minor release (owner: + * frontend-platform). + */ export { exactOwnDataSnapshot } from "./exact-snapshot.ts"; diff --git a/src/contracts/release-artifacts.ts b/src/contracts/release-artifacts.ts index 6dcd23aa..e3449fd5 100644 --- a/src/contracts/release-artifacts.ts +++ b/src/contracts/release-artifacts.ts @@ -151,6 +151,13 @@ const runtimeConfigArtifactFields = { BUILD_ID: z.string().min(1).optional(), } as const; +/** + * @deprecated V1 reader kept for one release after the V2-only writer + * (change evidence `FE-REG-ENV:API_CONTRACT_VERSION:*:removed`, 2026-09-24). + * Remove it and its re-export in `src/bootstrap/runtime-config-schema.ts` + * once no deployed `/config.json` still carries `CONFIG_SCHEMA_VERSION: "1"` + * (owner: frontend-platform). + */ export const runtimeConfigV1ArtifactSchema = z .object({ ...runtimeConfigArtifactFields, @@ -188,6 +195,13 @@ const releaseManifestArtifactFields = { routeChunks: z.record(z.string().min(1), z.string().min(1)), } as const; +/** + * @deprecated V1 reader kept for one release after the V2-only writer + * (change evidence `FE-REG-ENV:API_CONTRACT_VERSION:*:removed`, 2026-09-24). + * Remove it and its re-export in `src/bootstrap/load-release-manifest.ts` + * once no deployed `/release-manifest.json` still carries `schemaVersion: 1` + * (owner: frontend-platform). + */ export const releaseManifestV1ArtifactSchema = z .object({ schemaVersion: z.literal(1), From 063375ed0478f342c62dc942f5876e47676fbcb4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 00:32:54 +0900 Subject: [PATCH 7/9] fix(contracts): fail public builds without VITE_BUILD_ID and record the local default (F-6, 13-15) ENV_REGISTRY called VITE_BUILD_ID required with no default while every reader fell back to local-build. Staging and production builds now fail without it; local builds keep the placeholder, and the registry records that default. Co-Authored-By: Claude Opus 5.5 --- .../contracts/registry-change-evidence.json | 8 ++++++ scripts/generate-runtime-config.ts | 8 +++++- src/contracts/deployment-admission.ts | 2 +- src/contracts/env.ts | 5 +++- tests/unit/deployment-admission.test.ts | 27 +++++++++++++++++++ 5 files changed, 47 insertions(+), 3 deletions(-) diff --git a/config/contracts/registry-change-evidence.json b/config/contracts/registry-change-evidence.json index 0329c0a2..5aa12b9c 100644 --- a/config/contracts/registry-change-evidence.json +++ b/config/contracts/registry-change-evidence.json @@ -104,6 +104,14 @@ "compatibilityWindow": "No wire, storage or runtime-config format changes: the old id was never emitted by any producer, so no consumer could observe it.", "rollback": "Restore the previous telemetryEvent string on QUERY_CACHE_FAILURE in src/contracts/errors.ts and widen ErrorObservationEvent back to string.", "owner": "frontend-platform" + }, + { + "changeId": "FE-REG-ENV:VITE_BUILD_ID:defaultValue:field-type-changed", + "versionBump": "F-6 (13-15): the registry now records the local-build fallback that getBuildConfig and the build scripts already applied; the value itself did not change.", + "migration": "None for local builds. A staging or production build without VITE_BUILD_ID now fails in scripts/generate-runtime-config.ts instead of shipping the placeholder that admission refused.", + "compatibilityWindow": "No runtime document or wire format changes: BUILD_ID was already local-build whenever VITE_BUILD_ID was unset.", + "rollback": "Restore defaultValue null on VITE_BUILD_ID in src/contracts/env.ts and drop the public-target check in scripts/generate-runtime-config.ts.", + "owner": "frontend-platform" } ] } diff --git a/scripts/generate-runtime-config.ts b/scripts/generate-runtime-config.ts index 1ae9e288..5de3e330 100644 --- a/scripts/generate-runtime-config.ts +++ b/scripts/generate-runtime-config.ts @@ -5,6 +5,7 @@ import process from "node:process"; import { DEPLOYMENT_TARGETS, isDeploymentTarget, + PUBLIC_TARGETS, type DeploymentTarget, } from "../src/contracts/deployment-admission.ts"; import { runtimeConfigV2ArtifactSchema } from "../src/contracts/release-artifacts.ts"; @@ -64,7 +65,12 @@ export async function generateRuntimeConfig( ) { draft["RELEASE_MANIFEST_URL"] = `${basePath}${manifestUrl.slice(1)}`; } - const buildId = environment["VITE_BUILD_ID"] ?? "local-build"; + // F-6. A public build without its own identity would ship the local + // placeholder; fail here instead of at admission. + if (PUBLIC_TARGETS.has(target) && !environment["VITE_BUILD_ID"]) { + throw new Error(`${profilePath}: a ${target} build requires VITE_BUILD_ID`); + } + const buildId = environment["VITE_BUILD_ID"] || "local-build"; const releaseId = environment["RELEASE_ID"] ?? "local-release"; draft["BUILD_ID"] = buildId; draft["RELEASE_ID"] = releaseId; diff --git a/src/contracts/deployment-admission.ts b/src/contracts/deployment-admission.ts index 09fd3ae3..718b88e9 100644 --- a/src/contracts/deployment-admission.ts +++ b/src/contracts/deployment-admission.ts @@ -31,7 +31,7 @@ export type DeploymentTarget = (typeof DEPLOYMENT_TARGETS)[number]; * rule set; `local` and `development` only have to be honest about what they * are. */ -const PUBLIC_TARGETS: ReadonlySet = new Set([ +export const PUBLIC_TARGETS: ReadonlySet = new Set([ "staging", "production", ]); diff --git a/src/contracts/env.ts b/src/contracts/env.ts index b9905a3b..56c63159 100644 --- a/src/contracts/env.ts +++ b/src/contracts/env.ts @@ -40,7 +40,10 @@ export type EnvironmentDefinition = Readonly<{ }>; export const ENV_REGISTRY = Object.freeze({ - VITE_BUILD_ID: build("public-metadata", true, null), + // F-6. Required: a staging or production build fails without it + // (scripts/generate-runtime-config.ts). Local and development builds fall + // back to the placeholder, which admission refuses for public targets. + VITE_BUILD_ID: build("public-metadata", true, "local-build"), VITE_COMMIT_SHA: build("public-metadata", false, "local"), VITE_ROUTER_BASE_PATH: build("compile-time", true, "/"), VITE_RUNTIME_CONFIG_URL: build("compile-time", true, "/config.json"), diff --git a/tests/unit/deployment-admission.test.ts b/tests/unit/deployment-admission.test.ts index 2d3c57cb..6bf40263 100644 --- a/tests/unit/deployment-admission.test.ts +++ b/tests/unit/deployment-admission.test.ts @@ -11,6 +11,7 @@ import { isDeploymentTarget, type AdmissionInput, } from "../../src/contracts/deployment-admission.ts"; +import { ENV_REGISTRY, getBuildConfig } from "../../src/contracts/env.ts"; import { runtimeConfigV2ArtifactSchema } from "../../src/contracts/release-artifacts.ts"; import { generateRuntimeConfig } from "../../scripts/generate-runtime-config.ts"; @@ -195,6 +196,32 @@ describe("runtime config profiles", () => { ).rejects.toThrow(/runtime config is invalid/u); }); + it("refuses a staging or production build without VITE_BUILD_ID (F-6)", async () => { + for (const target of ["staging", "production"] as const) { + await expect( + generateRuntimeConfig(target, { RELEASE_ID: "r-1" }), + ).rejects.toThrow(/VITE_BUILD_ID/u); + await expect( + generateRuntimeConfig(target, { VITE_BUILD_ID: "", RELEASE_ID: "r-1" }), + ).rejects.toThrow(/VITE_BUILD_ID/u); + } + }); + + it("declares the build defaults that getBuildConfig applies (F-6)", () => { + const applied = getBuildConfig({}); + expect({ + VITE_BUILD_ID: ENV_REGISTRY.VITE_BUILD_ID.defaultValue, + VITE_COMMIT_SHA: ENV_REGISTRY.VITE_COMMIT_SHA.defaultValue, + VITE_ROUTER_BASE_PATH: ENV_REGISTRY.VITE_ROUTER_BASE_PATH.defaultValue, + VITE_RUNTIME_CONFIG_URL: ENV_REGISTRY.VITE_RUNTIME_CONFIG_URL.defaultValue, + }).toEqual({ + VITE_BUILD_ID: applied.buildId, + VITE_COMMIT_SHA: applied.commitSha, + VITE_ROUTER_BASE_PATH: applied.routerBasePath, + VITE_RUNTIME_CONFIG_URL: applied.runtimeConfigUrl, + }); + }); + it("keeps a developer build from carrying a released identity by default", async () => { const config = await generateRuntimeConfig("local", {}); expect(config["BUILD_ID"]).toBe("local-build"); From 606c191941323188b55a3be66fdfab2e98f9b6d4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 26 Sep 2026 01:01:48 +0900 Subject: [PATCH 8/9] test(registries): prove a second feature with an API operation passes check-registries unaided (F-3, 09-07) Writes a feature that owns one REST operation, plus its own context, into a copy of the repository and runs the generator and check-registries there. Reverting the consumer-directory globs makes the test fail. Co-Authored-By: Claude Opus 5.5 --- .../second-api-feature-registries.test.ts | 183 ++++++++++++++++++ 1 file changed, 183 insertions(+) create mode 100644 tests/unit/second-api-feature-registries.test.ts diff --git a/tests/unit/second-api-feature-registries.test.ts b/tests/unit/second-api-feature-registries.test.ts new file mode 100644 index 00000000..e2a8ba94 --- /dev/null +++ b/tests/unit/second-api-feature-registries.test.ts @@ -0,0 +1,183 @@ +import { spawnSync } from "node:child_process"; +import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import path from "node:path"; + +import { afterAll, describe, expect, it } from "vitest"; + +import { linkFixtureNodeModules } from "../../scripts/lib/fixture-node-modules.ts"; + +/** + * F-3 (09-07). Adding a feature that owns an API operation must not require + * edits outside its own directory: governance, composers and the registry + * baseline stay as they are. This writes one such feature (plus the bounded + * context it declares, so the check survives the sample's removal) into a copy + * of the repository and runs the production generator and `check-registries`. + */ +const FEATURE_ID = "second-api-feature"; +const CONTEXT_ID = "second-api-context"; + +const FEATURE_CONTRACT = `import { defineRestOperation } from "../../../contracts/api-operations.ts"; +import type { InstalledBoundaryMapper } from "../../../contracts/boundary-mapper.ts"; +import { mappingFailure, mappingSuccess } from "../../../contracts/boundary-mapper.ts"; +import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; + +const OWNER = "feature-frontend-second-api-feature"; + +const schema = (schemaId: string, boundary: string, direction: string) => + Object.freeze({ schemaId, boundary, owner: OWNER, runtime: "zod", schemaVersion: 1, direction }); + +const codec = (schemaId: string) => + runtimeSchemaCodecFromValidator({ + schemaId, + safeParse: (value: unknown) => Object.freeze({ success: true as const, data: value }), + }); + +export const SECOND_API_CONTRACT = Object.freeze({ + featureId: "${FEATURE_ID}", + routes: {}, + routeRuntimeContracts: {}, + apiOperations: Object.freeze({ + GET_SECOND_ITEM: defineRestOperation({ + method: "GET", + path: "/api/second-items/{itemId}", + operationId: "GET_SECOND_ITEM", + auth: "none", + timeoutMs: null, + idempotency: "safe", + retry: "runtime", + requestSource: "none", + requestSchema: "SecondItemRequest", + responseSchema: "SecondItemPayload", + owner: OWNER, + contractVersion: 2, + protocol: "REST", + semantics: "QUERY", + replayPolicy: "SAFE", + idempotencyKeyPolicy: "NONE", + mapperId: "SecondItemMapper", + successStatuses: [200], + responseMediaTypes: ["application/json"], + maxResponseBytes: 16_384, + providerId: "PRIMARY_API", + authProfileId: "ANONYMOUS", + csrfProfileId: "NO_CSRF_BEARER", + pathSchema: "SecondItemParams", + pathParameterNames: ["itemId"], + maxEncodedSearchBytes: 0, + }), + }), + invalidation: { topics: Object.freeze([]), namespaces: Object.freeze([]), edges: Object.freeze([]) }, + topicVersions: Object.freeze([]), + schemas: Object.freeze({ + SecondItemParams: schema("SecondItemParams", "api-request", "REQUEST"), + SecondItemRequest: schema("SecondItemRequest", "api-request", "REQUEST"), + SecondItemPayload: schema("SecondItemPayload", "api-response", "RESPONSE"), + }), + runtimeSchemas: Object.freeze({ + SecondItemParams: codec("SecondItemParams"), + SecondItemRequest: codec("SecondItemRequest"), + SecondItemPayload: codec("SecondItemPayload"), + }), + mappers: Object.freeze({ + SecondItemMapper: Object.freeze({ + mapperId: "SecondItemMapper", + mapperVersion: 1, + inputSchemaId: "SecondItemPayload", + outputContractId: "SecondItem", + owner: OWNER, + maxOutputItems: 1, + map: (value: unknown) => + value && typeof value === "object" ? mappingSuccess(value) : mappingFailure("MAPPING_INVARIANT_REJECTED"), + } satisfies InstalledBoundaryMapper), + }), +} as const); +`; + +const FEATURE_MODULE = `import { defineFeatureModule } from "../feature-module.ts"; +import { SECOND_API_CONTRACT } from "./contracts/second-api-contract.ts"; + +export const FEATURE_MODULE_ID = "${FEATURE_ID}"; +export const FEATURE_CONTEXT_ID = "${CONTEXT_ID}"; + +export const FEATURE_MODULE = defineFeatureModule({ + id: FEATURE_MODULE_ID, + contracts: SECOND_API_CONTRACT, + routes: {}, + adapters: [], + runtimes: [], + messages: {}, + contractContributions: [], +} as const); +`; + +const FEATURE_GATEWAY = `// The executable consumer of GET_SECOND_ITEM. +export const SECOND_ITEM_OPERATION = "GET_SECOND_ITEM"; +`; + +const CONTEXT_ROUTES = `import type { RouteObject } from "react-router-dom"; + +export const FEATURE_CONTEXT_ROUTES: readonly RouteObject[] = Object.freeze([]); +`; + +const CONTEXT_MODULE = `export const CONTEXT_MODULE_ID = "${CONTEXT_ID}"; +export const CONTEXT_APP_ID = "template-app"; +export const CONTEXT_ROUTE_PATH = "second-api/*"; +export const CONTEXT_MAX_FEATURES = 1; +`; + +const roots: string[] = []; + +afterAll(async () => { + await Promise.all(roots.map((root) => rm(root, { recursive: true, force: true }))); +}); + +describe("adding a feature with an API operation (F-3, 09-07)", () => { + it("passes check-registries without edits outside the feature and its context", async () => { + const root = await mkdtemp(path.join(tmpdir(), "second-api-feature-")); + roots.push(root); + // scripts/check-diagnostics.ts is a FE-REG-TELEMETRY consumer path. + for (const entry of [ + "src", + "config/contracts", + "schemas/artifacts", + "scripts/check-diagnostics.ts", + ]) { + await cp(path.resolve(entry), path.join(root, entry), { recursive: true }); + } + await linkFixtureNodeModules(root); + const files: Readonly> = { + [`src/contexts/${CONTEXT_ID}/context-module.ts`]: CONTEXT_MODULE, + [`src/features/${FEATURE_ID}/feature-module.ts`]: FEATURE_MODULE, + [`src/features/${FEATURE_ID}/context-routes.ts`]: CONTEXT_ROUTES, + [`src/features/${FEATURE_ID}/contracts/second-api-contract.ts`]: FEATURE_CONTRACT, + [`src/features/${FEATURE_ID}/adapters/second-api-gateway.ts`]: FEATURE_GATEWAY, + }; + for (const [file, content] of Object.entries(files)) { + await mkdir(path.dirname(path.join(root, file)), { recursive: true }); + await writeFile(path.join(root, file), content); + } + + const generated = spawnSync( + process.execPath, + [path.resolve("scripts/generate-product-feature-index.ts"), `--root=${root}`], + { encoding: "utf8" }, + ); + expect(generated.stderr).toBe(""); + expect(generated.status).toBe(0); + + const checked = spawnSync( + process.execPath, + [path.resolve("scripts/check-registries.ts")], + { cwd: root, encoding: "utf8" }, + ); + expect(checked.stderr).toBe(""); + expect(checked.stdout).toMatch(/11 registries PASS/u); + expect(checked.status).toBe(0); + const report = JSON.parse( + await readFile(path.join(root, "artifacts/quality/registries.json"), "utf8"), + ) as { registries: { registryId: string; rows: Record }[] }; + const api = report.registries.find(({ registryId }) => registryId === "FE-REG-API"); + expect(Object.keys(api?.rows ?? {})).toContain("GET_SECOND_ITEM"); + }, 60_000); +}); From 9dc95ca0665b4a0de68a95a7c48998b52fdec072 Mon Sep 17 00:00:00 2001 From: donghyeon-ka Date: Sun, 27 Sep 2026 12:58:57 +0900 Subject: [PATCH 9/9] fix(contracts): set zod jitless before any schema is built so the production csp sees no eval (F-7, 13-08) zod probed Function("") on its first object schema, which the production CSP (no unsafe-eval) reported on every boot. Schema code now imports z from src/contracts/zod.ts, enforced by a dependency-cruiser rule, and the CSP smoke drops its init-script workaround. Co-Authored-By: Claude Opus 5.5 --- .dependency-cruiser.json | 12 ++++++++++++ docs/security/browser-boundary.md | 15 +++++++-------- scripts/check-architecture.ts | 16 ++++++++++++++++ src/adapters/http/schema-registry.ts | 2 +- src/contracts/contract-set.ts | 2 +- src/contracts/release-artifacts.ts | 2 +- src/contracts/zod.ts | 15 +++++++++++++++ .../reference-feature-contract-contribution.ts | 2 +- .../contracts/reference-schemas.ts | 2 +- .../presentation/reference-resource-form.ts | 2 +- src/presentation/forms/use-app-form.ts | 2 +- .../routes/platform-route-codecs.ts | 2 +- tests/e2e/production-csp.spec.ts | 18 ++---------------- .../import-boundaries/contracts/zod.ts | 6 ++++++ .../presentation/pages/direct-zod.ts | 5 +++++ .../presentation/pages/wrapped-zod.ts | 3 +++ 16 files changed, 74 insertions(+), 32 deletions(-) create mode 100644 src/contracts/zod.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/contracts/zod.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-zod.ts create mode 100644 tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/wrapped-zod.ts diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index 4f46c87a..7ab151ca 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -56,6 +56,18 @@ "path": "^lucide-react$" } }, + { + "name": "zod-is-reached-through-contracts-zod", + "comment": "F-7 (13-08). src/contracts/zod.ts sets zod jitless before any schema is built, so the production CSP never sees zod's Function probe. Schema code imports z from there.", + "severity": "error", + "from": { + "path": "^src", + "pathNot": "^src/contracts/zod\\.ts$" + }, + "to": { + "path": "^zod$" + } + }, { "name": "design-system-is-reached-through-its-index", "comment": "VD-05, 12-08. Code outside src/presentation/design-system imports its public index.ts only, so the primitives can change behind it. Named facades: src/presentation/components/ui/*.ts re-export the canonical primitives under their pre-VD-05 paths (VD-05 Rollback). Exception: src/presentation/templates/page-templates.tsx reads PaginationLandmarkContext, which index.ts does not export. Owner: frontend-platform. Revisit: export it from index.ts or move the page templates into the design system.", diff --git a/docs/security/browser-boundary.md b/docs/security/browser-boundary.md index b8fa092d..807612a3 100644 --- a/docs/security/browser-boundary.md +++ b/docs/security/browser-boundary.md @@ -9,14 +9,13 @@ verification compares that declaration with live responses. CSP deliberately omits `unsafe-inline` and `unsafe-eval`; production code and built assets must remain compatible with that baseline. `tests/e2e/production-csp.spec.ts` (part of `test:e2e`, FE-GATE-008) serves the build with these headers and fails on a -`securitypolicyviolation` event or console error (review 13-08). One -violation is known: zod probes `Function("")` on its first object schema and -the policy refuses it. Parsing still works, but the default build reports the -violation on every boot until zod is configured `jitless` before the first -schema is built. `z.config` in the entry module is too late, because the -bundler evaluates the shared chunks that build schemas first. The smoke sets -zod's global config before page scripts run so it can catch every other -violation; the spec comment names when to remove that. Features that are off by +`securitypolicyviolation` event or console error (review 13-08). zod probes +`Function("")` on its first object schema, which the policy would report on +every boot. `src/contracts/zod.ts` sets `jitless` to skip that probe, and every +module that builds a schema imports `z` from there, so the setting is applied +before the first schema whatever order the bundler evaluates chunks in. +`z.config` in the entry module would be too late. Import `z` from +`src/contracts/zod.ts`, not from `zod`, in new schema code. Features that are off by default need CSP additions when a project selects them; see step 9 in [optional adapter recipes](../architecture/optional-adapter-recipes.md). `connect-src 'self' https:` lets script reach any HTTPS origin. Narrowing it to diff --git a/scripts/check-architecture.ts b/scripts/check-architecture.ts index bcaad88c..2413162c 100644 --- a/scripts/check-architecture.ts +++ b/scripts/check-architecture.ts @@ -921,6 +921,22 @@ async function runGraphFixtureChecks(): Promise { target === "lucide-react", ), }, + // F-7 (13-08): zod must be configured jitless before any schema is built. + { + name: "direct zod import outside src/contracts/zod.ts is rejected", + passed: blockingViolations(importBoundaryGraph).some( + ({ rule, source, target }) => + rule === "zod-is-reached-through-contracts-zod" && + source === "src/presentation/pages/direct-zod.ts" && + target === "zod", + ), + }, + { + name: "zod through src/contracts/zod.ts is accepted", + passed: !blockingViolations(importBoundaryGraph).some(({ source }) => + ["src/contracts/zod.ts", "src/presentation/pages/wrapped-zod.ts"].includes(source), + ), + }, { name: "unselected realtime runtime composition is rejected", passed: blockingViolations(importBoundaryGraph).some( diff --git a/src/adapters/http/schema-registry.ts b/src/adapters/http/schema-registry.ts index 1edb48c8..ffe12b80 100644 --- a/src/adapters/http/schema-registry.ts +++ b/src/adapters/http/schema-registry.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "../../contracts/zod.ts"; import { projectValidationIssues } from "../../contracts/validation-issues.ts"; const metaSchema = z diff --git a/src/contracts/contract-set.ts b/src/contracts/contract-set.ts index 5f36455c..1ffd8ca3 100644 --- a/src/contracts/contract-set.ts +++ b/src/contracts/contract-set.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "./zod.ts"; import { CONTRACT_SET_ALGORITHM, diff --git a/src/contracts/release-artifacts.ts b/src/contracts/release-artifacts.ts index e3449fd5..f662b422 100644 --- a/src/contracts/release-artifacts.ts +++ b/src/contracts/release-artifacts.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "./zod.ts"; import { contractSetSchema } from "./contract-set.ts"; diff --git a/src/contracts/zod.ts b/src/contracts/zod.ts new file mode 100644 index 00000000..d7c5060e --- /dev/null +++ b/src/contracts/zod.ts @@ -0,0 +1,15 @@ +import { z } from "zod"; + +/** + * F-7 (13-08). zod probes `new Function("")` when it builds its first object + * schema, to decide whether it may compile parsers. The production CSP has no + * 'unsafe-eval', so the browser reports that probe on every boot even though + * zod catches the refusal. `jitless` skips the probe; it only helps if it runs + * before any schema is built, and a bundler may evaluate a shared chunk before + * the entry module body. So every module that builds a schema imports `z` + * from here: the dependency, not import order in main.tsx, puts this first. + */ +z.config({ jitless: true }); + +export { z }; +export type { ZodIssue, ZodType } from "zod"; diff --git a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts index 0f38d803..589c20cc 100644 --- a/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts +++ b/src/features/reference-feature/contracts/reference-feature-contract-contribution.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "../../../contracts/zod.ts"; import type { CommandEffectDescriptor, diff --git a/src/features/reference-feature/contracts/reference-schemas.ts b/src/features/reference-feature/contracts/reference-schemas.ts index 0d24d33d..276cee25 100644 --- a/src/features/reference-feature/contracts/reference-schemas.ts +++ b/src/features/reference-feature/contracts/reference-schemas.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "../../../contracts/zod.ts"; import type { RuntimeValidator } from "../../../contracts/external-contract-runtime.ts"; import { runtimeSchemaCodecFromValidator } from "../../../contracts/schema-registry.ts"; diff --git a/src/features/reference-feature/presentation/reference-resource-form.ts b/src/features/reference-feature/presentation/reference-resource-form.ts index 059c596b..27af8f7b 100644 --- a/src/features/reference-feature/presentation/reference-resource-form.ts +++ b/src/features/reference-feature/presentation/reference-resource-form.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "../../../contracts/zod.ts"; export const referenceResourceFormSchema = z .object({ diff --git a/src/presentation/forms/use-app-form.ts b/src/presentation/forms/use-app-form.ts index 5a4e00a8..80556329 100644 --- a/src/presentation/forms/use-app-form.ts +++ b/src/presentation/forms/use-app-form.ts @@ -8,7 +8,7 @@ import { type FormEvent, } from "react"; import { flushSync } from "react-dom"; -import type { ZodType, ZodIssue } from "zod"; +import type { ZodIssue, ZodType } from "../../contracts/zod.ts"; import type { AppFailure } from "../../contracts/errors.ts"; import { useLocale, diff --git a/src/presentation/routes/platform-route-codecs.ts b/src/presentation/routes/platform-route-codecs.ts index 103b3302..b20509a5 100644 --- a/src/presentation/routes/platform-route-codecs.ts +++ b/src/presentation/routes/platform-route-codecs.ts @@ -1,4 +1,4 @@ -import { z } from "zod"; +import { z } from "../../contracts/zod.ts"; export const PLATFORM_ROUTE_CODECS = { // D-16: a route without input ignores unknown keys (`?utm_source=`, OAuth diff --git a/tests/e2e/production-csp.spec.ts b/tests/e2e/production-csp.spec.ts index 7ae22e49..954eafd4 100644 --- a/tests/e2e/production-csp.spec.ts +++ b/tests/e2e/production-csp.spec.ts @@ -22,19 +22,8 @@ const securityHeaders = { .join("; "), }; -/** - * Known violation, not accepted behavior. Zod probes `Function("")` when it - * builds its first object schema, to decide whether it may compile parsers. - * The policy has no 'unsafe-eval', so the probe is refused (zod catches it and - * parses without compiling) and reported on every boot of the default build. - * `z.config({ jitless: true })` removes the probe, but it must run before the - * first schema is built, and the bundler evaluates the shared chunks that - * build schemas before the entry module body. Until the app does that, this - * smoke sets zod's shared global config (`globalThis.__zod_globalConfig`, read - * by zod/v4/core when it loads) before any page script runs, so - * every other violation is still caught. Owner: frontend-platform. Remove the - * init script below when the app configures zod itself. - */ +// F-7. No zod setup here: the app sets `jitless` in src/contracts/zod.ts before +// any schema is built, so zod's `Function("")` probe never reaches the policy. test.beforeEach(async ({ page, baseURL }) => { const origin = new URL(baseURL ?? "http://127.0.0.1:4173").origin; await page.route( @@ -47,9 +36,6 @@ test.beforeEach(async ({ page, baseURL }) => { }); }, ); - await page.addInitScript(() => { - (globalThis as { __zod_globalConfig?: object }).__zod_globalConfig = { jitless: true }; - }); await page.addInitScript(() => { const violations: string[] = []; Object.defineProperty(window, "__cspViolations", { value: violations }); diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/contracts/zod.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/contracts/zod.ts new file mode 100644 index 00000000..4cc0a37c --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/contracts/zod.ts @@ -0,0 +1,6 @@ +// F-7 (13-08): the one module that imports zod itself. +import { z } from "zod"; + +z.config({ jitless: true }); + +export { z }; diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-zod.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-zod.ts new file mode 100644 index 00000000..245d03fb --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/direct-zod.ts @@ -0,0 +1,5 @@ +// F-7 (13-08): schema code imports z from src/contracts/zod.ts, which sets +// jitless before any schema is built. +import { z } from "zod"; + +export const directSchema = z.string(); diff --git a/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/wrapped-zod.ts b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/wrapped-zod.ts new file mode 100644 index 00000000..feb836ca --- /dev/null +++ b/tests/fixtures/architecture/dependency-graph/import-boundaries/presentation/pages/wrapped-zod.ts @@ -0,0 +1,3 @@ +import { z } from "../../contracts/zod.ts"; + +export const wrappedSchema = z.string();