Merge lane/G: contracts (07-02~07-07, 13-10, F-3, F-6, F-7)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -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.",
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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"] }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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
|
||||
}
|
||||
@@ -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"
|
||||
}
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -921,6 +921,22 @@ async function runGraphFixtureChecks(): Promise<GraphFixtureResult> {
|
||||
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(
|
||||
|
||||
@@ -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<Record<string, unknown>>;
|
||||
}>;
|
||||
|
||||
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<string, Readonly<Record<"additive" | "breaking", CompatibilityFixture>>>
|
||||
>;
|
||||
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`,
|
||||
);
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { z } from "zod";
|
||||
import { z } from "../../contracts/zod.ts";
|
||||
import { projectValidationIssues } from "../../contracts/validation-issues.ts";
|
||||
|
||||
const metaSchema = z
|
||||
|
||||
@@ -14,7 +14,13 @@ export type BoundaryMappingResult<Value> =
|
||||
| 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<Value> = BoundaryMappingResult<Value>;
|
||||
|
||||
/** Adapts a boundary mapper result to the canonical contract mapping result. */
|
||||
|
||||
@@ -82,26 +82,63 @@ export function verifyCompatibilityTuple(input: Readonly<{
|
||||
export type ObjectSchemaShape = Readonly<{
|
||||
required?: readonly string[];
|
||||
properties?: Readonly<Record<string, unknown>>;
|
||||
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";
|
||||
}
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { z } from "zod";
|
||||
import { z } from "./zod.ts";
|
||||
|
||||
import {
|
||||
CONTRACT_SET_ALGORITHM,
|
||||
|
||||
@@ -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<DeploymentTarget> = new Set([
|
||||
export const PUBLIC_TARGETS: ReadonlySet<DeploymentTarget> = new Set([
|
||||
"staging",
|
||||
"production",
|
||||
]);
|
||||
|
||||
@@ -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"),
|
||||
|
||||
+41
-167
@@ -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<Kind extends string> = Readonly<{
|
||||
kind: Kind;
|
||||
defaultRetryable: boolean;
|
||||
severity: string;
|
||||
userMessageKey: string;
|
||||
action: ErrorAction;
|
||||
telemetryEvent: ErrorObservationEvent;
|
||||
redaction: readonly string[];
|
||||
}>;
|
||||
|
||||
const row = <Kind extends string>(
|
||||
kind: Kind,
|
||||
defaultRetryable: boolean,
|
||||
severity: string,
|
||||
action: ErrorAction,
|
||||
telemetryEvent: ErrorObservationEvent = "api.request.failed",
|
||||
): ErrorDefinition<Kind> =>
|
||||
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"),
|
||||
});
|
||||
|
||||
/**
|
||||
@@ -262,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;
|
||||
|
||||
|
||||
@@ -72,22 +72,29 @@ export function invokeValidator<T>(
|
||||
validator: RuntimeValidator<T>,
|
||||
value: unknown,
|
||||
): ValidatorInvocation<T> {
|
||||
let result: RuntimeValidationResult<T>;
|
||||
// 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<Record<string, unknown>>;
|
||||
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<T> =
|
||||
|
||||
@@ -61,5 +61,9 @@ export function createReadOnlyMap<Key, Value>(
|
||||
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";
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { z } from "zod";
|
||||
import { z } from "./zod.ts";
|
||||
|
||||
import { contractSetSchema } from "./contract-set.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),
|
||||
|
||||
@@ -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";
|
||||
@@ -1,4 +1,4 @@
|
||||
import { z } from "zod";
|
||||
import { z } from "../../../contracts/zod.ts";
|
||||
|
||||
import type {
|
||||
CommandEffectDescriptor,
|
||||
|
||||
@@ -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";
|
||||
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
import { z } from "zod";
|
||||
import { z } from "../../../contracts/zod.ts";
|
||||
|
||||
export const referenceResourceFormSchema = z
|
||||
.object({
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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 });
|
||||
|
||||
+6
@@ -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 };
|
||||
Vendored
+5
@@ -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();
|
||||
Vendored
+3
@@ -0,0 +1,3 @@
|
||||
import { z } from "../../contracts/zod.ts";
|
||||
|
||||
export const wrappedSchema = z.string();
|
||||
@@ -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", {});
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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<string, unknown>;
|
||||
const current = z.toJSONSchema(runtimeConfigV2ArtifactSchema) as Record<
|
||||
string,
|
||||
unknown
|
||||
> & { properties: Record<string, unknown> };
|
||||
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",
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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<unknown> => ({
|
||||
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" }] });
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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],
|
||||
});
|
||||
}
|
||||
});
|
||||
});
|
||||
@@ -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<Record<string, string>> = {
|
||||
[`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<string, unknown> }[] };
|
||||
const api = report.registries.find(({ registryId }) => registryId === "FE-REG-API");
|
||||
expect(Object.keys(api?.rows ?? {})).toContain("GET_SECOND_ITEM");
|
||||
}, 60_000);
|
||||
});
|
||||
Reference in New Issue
Block a user