# 계약 호환성과 rollback 규칙 차단 기준이 되는 tuple은 `(buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId)`이다. version은 숫자로 파싱한다. 1. 변경이 추가(additive)로 인정되는 것은 이전 version의 모든 reader가 받아들이는 선택 필드를 더할 때뿐이다. 아래 경계별 표를 본다 2. 깨지는(breaking) 변경은 major version을 올리거나 reader를 먼저 배포해야 한다 3. 저장된 cache는 테스트된 명시적 migration이 없으면 버린다 4. 호환되지 않는 config나 API 계약은 제품 mount를 막는다 5. rollback은 HTML, asset, runtime config, API 호환성, release manifest를 하나의 일관된 묶음으로 되돌린다 ## 경계별 규칙 "필드 추가"가 안전한지는 쓰는 쪽(writer)이 아니라 읽는 쪽(reader)에 달려 있다. 옛 reader는 계속 살아 있다. 여러 탭, cache된 앱 셸, rollback을 모두 지원하기 때문이다. `REJECT_UNKNOWN` 경계에서는 필드를 더하면 깨진다. 그래서 그 필드를 받아들이는 reader를 먼저 배포해야 한다. 어떤 writer든 그 뒤에야 그 필드를 보낼 수 있다. | 경계 | reader 정책 | 필드나 값 추가 | 코드 | |---|---|---|---| | Runtime config V2 (`/config.json`) | 엄격한(strict) object. `CONFIG_SCHEMA_VERSION`은 리터럴 `"2.0"` | 깨짐 | `src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema` | | `CAPABILITY_OVERRIDES` | 엄격함. 모르는 capability는 거부 | 깨짐 | `src/contracts/release-artifacts.ts`의 `capabilityOverrideArtifactSchema` | | `FEATURE_OVERRIDES` | record. 모르는 feature id는 무시 | 추가로 인정 | `src/contracts/release-artifacts.ts`의 `featureOverrideArtifactSchema` | | Release manifest V2 | 엄격한 object | 깨짐 | `src/contracts/release-artifacts.ts`의 `releaseManifestV2ArtifactSchema` | | HTTP 성공·실패 envelope (V3에서 `responseEnvelope: "ENVELOPE_V1"`) | 엄격한 object(`meta`는 걸러 냄) | 깨짐 | `src/adapters/http/backend-envelope.ts`의 `successEnvelopeSchema`, `failureEnvelopeSchema` | | HTTP V3 응답 DTO (feature의 것) | `.strip()`이 모르는 필드를 버림 | 추가로 인정 | `create:feature`가 만드는 feature의 `contracts/-schemas.ts`에 있는 `ItemDtoSchema` | | Realtime envelope | 정확한 key 집합. 모르는 `eventType`은 `MALFORMED_EVENT` | 깨짐 | `src/adapters/realtime/event-codec.ts`의 `decodeUnsafe` | | Browser RPC 전송 오류 code | 닫힌 어휘. 모르는 code는 protocol 위반 | 깨짐 | `src/adapters/browser-rpc/browser-rpc-runtime.ts`의 `decodeTransportFailure` | | 저장된 클라이언트 storage | version이 붙은 key. 호환되지 않는 값은 버림 | 새 key version을 쓴다 | `src/contracts/storage-keys.ts`의 `defineStorageKey` | 응답 DTO를 엄격하게 바꾸면 이 표에서 그 행이 바뀐다. `RESPONSE` schema의 FE-REG-SCHEMA 행이 `STRIP_UNKNOWN`에서 `REJECT_UNKNOWN`으로 바뀌면 `check:registries`가 이를 깨지는 변경(`response-reader-narrowed`)으로 판정한다. 그래서 그 변경에는 registry 증거가 필요하다(1105/07-02). `CAPABILITY_OVERRIDES`와 `FEATURE_OVERRIDES`는 일부러 다르게 둔다. feature id는 빌드마다 다르다. 다운스트림 프로젝트마다 자기 feature를 설치하기 때문이다. 그리고 공유 config 문서 하나가 여러 빌드를 덮을 수 있다. capability 집합은 platform version이 정한다. 그래서 모르는 capability가 있다는 것은 그 config가 더 새 platform을 위해 쓰였다는 뜻이다. 이것은 다른 엄격한 config 추가와 똑같이 다룬다. ## Schema 변경 분류기와 FE-GATE-014 `classifyObjectSchemaChange`(`src/contracts/compatibility.ts`)는 `before`를 기준으로 만든 reader 입장에서 답한다. fail closed로 동작한다: `additionalProperties: false`가 없는 reader 아래에 새 property를 더한 경우만 `additive`다. property를 지우거나 바꾸는 것(type, enum, nullable, format 등), required 집합이 달라지는 것, 그 밖의 keyword가 바뀌는 것은 모두 `breaking`이다. 아무것도 다르지 않으면 `none`이다. FE-GATE-014(`config-compatibility`, `corepack pnpm verify:compatibility`)는 `scripts/check-compatibility.ts`를 실행한다. 이 스크립트는 두 가지를 한다. 1. `config/compatibility/fixtures.json`에 손으로 쓴 사례를 분류하고, 결과가 하나라도 `expected`와 다르면 실패한다. 2. commit된 기준선 `config/compatibility/runtime-config.schema.baseline.json`을 지금 runtime config schema와 비교한다. 지금 schema는 빌드가 `dist/runtime-config.schema.json`에 쓰는 것과 같은 `z.toJSONSchema` 출력이다(`scripts/generate-build-manifest.ts`). 결과가 `breaking`이면 gate가 실패한다. 기준선은 이전 release의 reader가 받아들이는 schema를 나타낸다. 깨지는 config 변경을 의도했다면 reader를 먼저 배포한다(또는 config major version을 올린다). 그다음 `corepack pnpm verify:compatibility --update-baseline`을 실행하고, 새 기준선을 변경과 함께 commit한다. 결과는 `artifacts/release/compatibility.json`에 기록된다. 지금의 `apiContractVersion` 검사는 release와 config가 서로 맞는다는 것을 증명한다. 그것만으로 provider가 계약을 지킨다는 것까지 증명하지는 않는다. 목표로 하는 다중 protocol 계약 묶음은 [API contract, Schema, Mapper와 Server State](../design/2026-07-28-api-contract-schema-mapper-and-server-state-design.md)에 정의된 대로 다음을 묶는다: REST/OpenAPI artifact, GraphQL schema와 persisted-operation manifest, protobuf source·descriptor·codegen profile, Connect/gRPC-Web provider profile, ProtoJSON·HttpRule·생성된 OpenAPI·gateway artifact, runtime schema·mapper registry, server-state 정책 digest. 브라우저 Protobuf와 REST Gateway 호환성은 [Protobuf browser transport와 REST Gateway](../design/2026-07-28-protobuf-browser-transport-and-rest-gateway-design.md)에서 더 나눈다. binary·JSON·HTTP route 호환성 gate는 서로 바꿔 쓸 수 없다.