Files
clean-architecture-frontend…/docs/contracts/compatibility.md
T
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로
템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다.

참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록
7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트
참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은
비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을
하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다.
기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로
옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플
경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다.
레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약
기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능
539B, context 4B)을 다시 받았다.

위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은
수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에
공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는
플랫폼 코드에 남았다.

검증(desktop): check:types, lint, check:architecture, check:registries,
check:ci, verify:documentation, test:unit, test:component,
test:contract, test:integration, test:recipes, test:coverage(Risk
coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual,
test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76
checks), test:sample-removal SKIP, build, check:bundle.
2026-11-08 14:07:58 +09:00

5.3 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 (V3 with responseEnvelope: "ENVELOPE_V1") strict object (meta strips) breaking successEnvelopeSchema, failureEnvelopeSchema in src/adapters/http/backend-envelope.ts
HTTP V3 response DTO (a feature's) .strip() drops unknown fields additive <camel>ItemDtoSchema in contracts/<base>-schemas.ts of a feature create:feature writes
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

Turning a response DTO strict changes its row in this table. check:registries grades it as breaking (response-reader-narrowed) when the FE-REG-SCHEMA row of a RESPONSE schema goes from STRIP_UNKNOWN to REJECT_UNKNOWN, so the change needs registry evidence (1105/07-02).

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.