The classifier called type, enum and nullable changes "none" and treated new keys under strict readers as additive; FE-GATE-014 only checked hand-written fixtures. It now fails closed and compares the committed baseline with the schema the build emits. The doc lists per-boundary reader rules. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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:138-140` |
|
|
|
|
`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.
|