문제: docs/runbooks, docs/security, docs/styling/design-tokens.md, docs/accessibility, docs/contracts, docs/testing/taxonomy.md와 src/adapters/browser-transfer/image-cdn/README.md는 본문이 영어다. PRODUCT.md는 「~합니다」 체라 한 문서 안 문체 규칙(「~한다」)과 다르다. 고른 방법: 뜻을 바꾸지 않고 옮긴다. runbook 제목의 ID와 오류 code, 기록 양식의 영어 키(`Status:`, `M1 Keyboard:` 등, 코드 블록 안)는 그대로 둔다. PRODUCT.md는 디자인 도구가 읽는 제목(`## Users` 등)을 두고 문장 끝만 바꾼다. 위험: 이 커밋으로 문서 검사의 예외 목록이 빈다. 앞으로 영어 문서나 높임 문체를 더하면 verify:documentation이 실패한다. 검증: 백틱 span·링크 대상·코드 블록을 옮기기 전과 python으로 비교해 같다. 문서 검사 여섯이 모두 0건이고 예외 목록과 FROZEN이 비었다.
6.1 KiB
계약 호환성과 rollback 규칙
차단 기준이 되는 tuple은 (buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId)이다. version은 숫자로 파싱한다.
- 변경이 추가(additive)로 인정되는 것은 이전 version의 모든 reader가 받아들이는 선택 필드를 더할 때뿐이다. 아래 경계별 표를 본다
- 깨지는(breaking) 변경은 major version을 올리거나 reader를 먼저 배포해야 한다
- 저장된 cache는 테스트된 명시적 migration이 없으면 버린다
- 호환되지 않는 config나 API 계약은 제품 mount를 막는다
- 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/<base>-schemas.ts에 있는 <camel>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를 실행한다. 이 스크립트는 두 가지를 한다.
config/compatibility/fixtures.json에 손으로 쓴 사례를 분류하고, 결과가 하나라도expected와 다르면 실패한다.- 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에
정의된 대로 다음을 묶는다: 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에서
더 나눈다. binary·JSON·HTTP route 호환성 gate는 서로 바꿔 쓸 수 없다.