Files
clean-architecture-frontend…/docs/contracts/compatibility.md
T
DongHyeonka e98a980dff fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.

고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).

버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
  newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.

위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.

검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
  "expected { ok: true, value: undefined } to match object { ok: false }"
  로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
  to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
  contract-registry-lookup, browser-security, runtime-adapters,
  release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
  eslint 통과, check-registries PASS, verify-documentation-readiness
  PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00

4.7 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 src/contracts/release-artifacts.ts:163-171
CAPABILITY_OVERRIDES strict; unknown capability rejected breaking src/contracts/release-artifacts.ts:50-63
FEATURE_OVERRIDES record; unknown feature id ignored additive src/contracts/release-artifacts.ts:65-80
Release manifest V2 strict object breaking src/contracts/release-artifacts.ts:200-208
HTTP V2 success/failure envelope strict object (meta strips) breaking src/adapters/http/schema-registry.ts:12-34
HTTP V3 response DTO (reference feature) .strip() drops unknown fields additive src/features/reference-feature/contracts/reference-schemas.ts:29-35
Realtime envelope exact key set; unknown eventType is MALFORMED_EVENT breaking src/adapters/realtime/event-codec.ts:126,149
Browser RPC transport error code closed vocabulary; unknown code is a protocol violation breaking src/adapters/browser-rpc/browser-rpc-runtime.ts:1473
Persisted client storage versioned key; incompatible value discarded use a new key version src/contracts/storage-keys.ts:148-150

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:110) 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.