문제 매뉴얼 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
76 lines
5.1 KiB
Markdown
76 lines
5.1 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 | `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](../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.
|