Files
clean-architecture-frontend…/docs/contracts/compatibility.md
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

83 lines
6.1 KiB
Markdown

# 계약 호환성과 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](../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는 서로 바꿔 쓸 수 없다.