문제: 응답 DTO를 `.strict()`로 바꾸고 FE-REG-SCHEMA 행의 `unknownFieldPolicy`를 STRIP_UNKNOWN에서 REJECT_UNKNOWN으로 같이 고치면 check:registries가 behavior-change로 통과한다(리뷰 배치 07-R1). 1103/07-03 수정은 행과 검증기를 묶었지만 등급은 그대로였다. 그 뒤 백엔드가 응답에 필드 하나를 더하면 그 API는 SCHEMA_MISMATCH로 실패한다. 같은 경계에서 FE-REG-API는 acceptedStatuses 축소를 breaking으로 본다. 고른 방법: 분류기에 규칙 하나를 더한다. `direction: "RESPONSE"` 행의 `unknownFieldPolicy`가 REJECT_UNKNOWN이 아니던 값에서 REJECT_UNKNOWN으로 바뀌면 kind `response-reader-narrowed`, breaking이다. 반대 방향 (REJECT→STRIP, 읽는 쪽을 넓힘)과 REQUEST 행(프론트가 스스로 채우는 값)은 그대로 behavior-change다. 버린 대안: governance의 FE-REG-SCHEMA breakingFields에 `unknownFieldPolicy`를 넣는 것(리뷰 안 B). 넓히는 변경까지 증거를 요구하게 되고, governance 계약이 바뀌어 템플릿과 다운스트림 모두 기준선을 다시 승인해야 한다. 이 규칙은 기준선과 governance를 바꾸지 않는다. 리뷰 안 (1)의 fieldTypes 선언도 같은 이유로 하지 않았다. 위험·한계: 규칙은 칸 이름(`unknownFieldPolicy`)과 값 어휘 (src/contracts/schema-registry.ts)에 묶여 있다. 어휘를 바꾸면 이 함수도 고친다. route-params·route-search(REQUEST 방향, URL을 읽는 쪽)를 REJECT_UNKNOWN으로 좁히는 변경은 여전히 behavior-change다. 지금 템플릿 스냅샷은 기준선과 같아 결과는 none 그대로다. 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/unit/registry-compatibility.test.ts 리뷰 07-R1 패치(응답 DTO `.strict()` + 응답 행 두 개 REJECT_UNKNOWN)를 다시 적용하면 check:registries가 `breaking change missing evidence: FE-REG-SCHEMA:ReferenceResource(List)Payload:unknownFieldPolicy: response-reader-narrowed`로 실패해야 한다. Refs: 1105/07-02
5.3 KiB
Contract compatibility and rollback rules
The blocking tuple is (buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId). Versions are parsed numerically.
- a change is additive only when it adds an optional field that every reader of the previous version tolerates; see the boundary table below
- breaking changes require a major version bump or a reader-first deployment
- persisted cache is discarded unless an explicit tested migration exists
- an incompatible config or API contract blocks product mount
- 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 | runtimeConfigV2ArtifactSchema in src/contracts/release-artifacts.ts |
CAPABILITY_OVERRIDES |
strict; unknown capability rejected | breaking | capabilityOverrideArtifactSchema in src/contracts/release-artifacts.ts |
FEATURE_OVERRIDES |
record; unknown feature id ignored | additive | featureOverrideArtifactSchema in src/contracts/release-artifacts.ts |
| Release manifest V2 | strict object | breaking | releaseManifestV2ArtifactSchema in src/contracts/release-artifacts.ts |
HTTP success/failure envelope (V3 with responseEnvelope: "ENVELOPE_V1") |
strict object (meta strips) |
breaking | successEnvelopeSchema, failureEnvelopeSchema in src/adapters/http/backend-envelope.ts |
| HTTP V3 response DTO (reference feature) | .strip() drops unknown fields |
additive | referenceResourceDtoSchema in the reference sample's contracts/reference-schemas.ts |
| Realtime envelope | exact key set; unknown eventType is MALFORMED_EVENT |
breaking | decodeUnsafe in src/adapters/realtime/event-codec.ts |
| Browser RPC transport error code | closed vocabulary; unknown code is a protocol violation | breaking | decodeTransportFailure in src/adapters/browser-rpc/browser-rpc-runtime.ts |
| Persisted client storage | versioned key; incompatible value discarded | use a new key version | defineStorageKey in src/contracts/storage-keys.ts |
Turning a response DTO strict changes its row in this table. check:registries
grades it as breaking (response-reader-narrowed) when the FE-REG-SCHEMA row
of a RESPONSE schema goes from STRIP_UNKNOWN to REJECT_UNKNOWN, so the
change needs registry evidence (1105/07-02).
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) 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:
- Classifies the hand-written cases in
config/compatibility/fixtures.jsonand fails if any result differs fromexpected. - Compares the committed baseline
config/compatibility/runtime-config.schema.baseline.jsonwith the current runtime config schema, which is the samez.toJSONSchemaoutput the build writes todist/runtime-config.schema.json(scripts/generate-build-manifest.ts). Abreakingresult 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,
protobuf source/descriptors/codegen profiles, Connect/gRPC-Web provider profiles,
ProtoJSON/HttpRule/generated OpenAPI/gateway artifacts, runtime schema/mapper
registries, and server-state policy digests as defined in
API contract, Schema, Mapper, and Server State.
Browser Protobuf and REST Gateway compatibility is further split in
Protobuf browser transport and REST Gateway;
binary/JSON/HTTP-route compatibility gates are not interchangeable.