Files
clean-architecture-frontend…/docs/contracts/compatibility.md
T
DongHyeonka 11530b1adf docs: runbook·보안·스타일·접근성·계약·테스트 문서와 모듈 README를 한국어로 옮긴다
문제: 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이 비었다.
2026-11-08 21:57:47 +09:00

6.1 KiB

계약 호환성과 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/<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를 실행한다. 이 스크립트는 두 가지를 한다.

  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에 정의된 대로 다음을 묶는다: 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는 서로 바꿔 쓸 수 없다.