문제: 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
76 lines
4.7 KiB
Markdown
76 lines
4.7 KiB
Markdown
# 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](../architecture/api-contract-schema-mapper-and-server-state.md).
|
|
Browser Protobuf and REST Gateway compatibility is further split in
|
|
[Protobuf browser transport and REST Gateway](../architecture/protobuf-browser-transport-and-rest-gateway.md);
|
|
binary/JSON/HTTP-route compatibility gates are not interchangeable.
|