Files
clean-architecture-frontend…/docs/contracts/compatibility.md
T
DongHyeonka f3b87b3f02 docs: 생성한 기능이 짝 백엔드 Envelope를 읽는다는 결정과 결과를 적는다
문제
매뉴얼 01 3단계, CHANGELOG 미출시 절, 리뷰 README 14.3은 "생성한 기능은
짝 백엔드 응답을 그대로 읽지 못한다, 해결 방법은 정하지 않았다"를 알려진
제한으로 적는다. 7db32e1로 V3가 responseEnvelope: "ENVELOPE_V1"
operation의 Envelope를 읽게 되어 이 문장들이 틀렸다. 매뉴얼 02 4절의 503
흐름도와 계약 문서 4.1절도 "V3는 Envelope 없이 DTO를 검증"으로 적는다.

고른 방법
- 리뷰 README 14.6: 선택지 넷(V3 operation 단위 / provider 단위 / 백엔드
  problem+json 모드 / 기능 스키마가 감쌈)의 판정과 이유, V2와 같은 판정
  표, 의도한 차이 세 가지, RED→GREEN·게이트 결과, 남은 것. 14.3 행의
  처리 칸은 14.6을 가리킨다.
- 매뉴얼 01 3단계: "응답 모양"을 짝 백엔드 Envelope 기준으로 다시 쓰고,
  Envelope가 아닌 백엔드에 붙이는 순서(responseEnvelope 줄 삭제, problem
  details 스키마)를 따로 적었다. 알려진 제한 문단은 지웠다.
- 매뉴얼 02 4절: 실행기가 먼저 정하는 판정 목록과 바뀐 503 흐름.
- CHANGELOG: [계약] 행 하나, 알려진 제한을 남은 차이(참조 기능 미선언,
  V2와의 차이 셋, e2e 접근성 스펙의 [] 본문)로 바꿨다.
- 14.4와 CHANGELOG의 "V3 진단에 problem code가 없다"에 bd83b49가 싣는
  범위(멱등성 거절 reason 두 값)와 싣지 않는 것, 그 이유를 적었다.
- 계약 문서 4.1절·compatibility.md: Envelope를 읽는 곳을
  backend-envelope.ts로 고쳤다.

버린 대안
- 백엔드에 요청 문서 쓰기: (나)를 고르지 않아 요청할 것이 없다.

위험·한계
- 문서의 게이트 결과는 이 커밋 직전 트리(bd83b49, scaffold·sample-removal은
  7db32e1)에서 잰 값이다.
- 백엔드 링크는 두 repo가 나란히 있을 때만 열린다(기존과 같다).

검증
- verify:documentation PASS_SCOPED.
- 게이트 수치는 README 14.6 결과 표에 실행한 커밋과 함께 적었다.
- tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
2026-11-03 20:13:31 +09:00

5.1 KiB

Contract compatibility and rollback rules

The blocking tuple is (buildId, configSchemaVersion, apiContractVersion, assetManifestHash, releaseId). Versions are parsed numerically.

  1. a change is additive only when it adds an optional field that every reader of the previous version tolerates; see the boundary table below
  2. breaking changes require a major version bump or a reader-first deployment
  3. persisted cache is discarded unless an explicit tested migration exists
  4. an incompatible config or API contract blocks product mount
  5. 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 (V2, and V3 with responseEnvelope: "ENVELOPE_V1") strict object (meta strips) breaking successEnvelopeSchema, failureEnvelopeSchema in src/adapters/http/schema-registry.ts, read by src/adapters/http/backend-envelope.ts
HTTP V3 response DTO (reference feature) .strip() drops unknown fields additive referenceResourceDtoSchema in src/features/reference-feature/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

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:

  1. Classifies the hand-written cases in config/compatibility/fixtures.json and fails if any result differs from expected.
  2. Compares the committed baseline config/compatibility/runtime-config.schema.baseline.json with the current runtime config schema, which is the same z.toJSONSchema output the build writes to dist/runtime-config.schema.json (scripts/generate-build-manifest.ts). A breaking result 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.