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:
donghyeon-ka
2026-09-27 13:08:05 +09:00
co-authored by Claude Opus 5.5
42 changed files with 1026 additions and 832 deletions
+12
View File
@@ -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.",
+1 -3
View File
@@ -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",
+57 -53
View File
@@ -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"
}
+56 -473
View File
@@ -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"
}
]
}
+3 -10
View File
@@ -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",
+55 -2
View File
@@ -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,
+7 -8
View File
@@ -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
+16
View File
@@ -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(
+55 -26
View File
@@ -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`,
);
+16 -7
View File
@@ -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
+7 -1
View File
@@ -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 -1
View File
@@ -1,4 +1,4 @@
import { z } from "zod";
import { z } from "../../contracts/zod.ts";
import { projectValidationIssues } from "../../contracts/validation-issues.ts";
const metaSchema = z
+7 -1
View File
@@ -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. */
+50 -13
View File
@@ -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 -1
View File
@@ -1,4 +1,4 @@
import { z } from "zod";
import { z } from "./zod.ts";
import {
CONTRACT_SET_ALGORITHM,
+1 -1
View File
@@ -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",
]);
+4 -1
View File
@@ -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
View File
@@ -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;
+19 -12
View File
@@ -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> =
+5 -1
View File
@@ -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";
+15 -1
View File
@@ -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),
+15
View File
@@ -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({
+1 -1
View File
@@ -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
+2 -16
View File
@@ -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 });
@@ -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 };
@@ -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();
@@ -0,0 +1,3 @@
import { z } from "../../contracts/zod.ts";
export const wrappedSchema = z.string();
+9
View File
@@ -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", {});
+1 -1
View File
@@ -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);
+77
View File
@@ -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",
+27
View File
@@ -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");
+24 -25
View File
@@ -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);
});