문제
1103/14-04 조치는 참조 기능을 지운 사본에서 문서 검사가 통과하도록 참조
기능·참조 context 경로와 그 전용 파일·script를 백틱 없이 다시 적었다.
검사기는 백틱 안·명령 안·링크의 경로만 보므로(verify-documentation-
readiness.ts) 그 26줄은 참조 기능이 설치된 템플릿에서도 검사 밖이다. 참조
기능 파일 이름이 바뀌면 매뉴얼이 없는 경로를 가리켜도 어느 게이트도
실패하지 않는다. docs/manual/README.md의 "이 폴더 문서의 경로는 검사된다"가
예제 경로에서 거짓이다.
고른 방법
- 앞 커밋(1105/14-01)으로 검사기가 지운 템플릿 기능의 경로를 받으므로,
README, starter-experience, static-delivery, compatibility,
backend-api-and-server-state-contract, manual-checklist,
adapter-remediation-ledger, performance-evidence, 매뉴얼 01·02·patterns의
참조 기능 경로와 test:reference-feature를 다시 백틱(또는 명령 한 줄)으로
적는다. 두 줄로 끊겨 검사되지 않던 measure 명령도 한 줄로 적었다.
1105/15-02·16-01 조치가 starter-experience.md 표와 매뉴얼 03(A 표, "기능을
지울 때")에 백틱 없이 더한 config/scale/feature-shape-ceilings.json과
measure 명령 세 줄도 같은 규칙으로 고쳤다.
- patterns.md 첫머리 규칙("백틱 없이 적는다")과 README의 SAMPLE_EXTRAS
안내를 새 규칙(설치된 동안 검사, 지운 사본에서는 받음)과 목록 모듈
위치로 고쳤다.
- 테스트: template-feature-removal-documents.test.ts에 "names their paths
and scripts only where verify:documentation checks them"을 더했다. 검사기가
읽은 1절 문서 목록(documentation-review.json)을 받아, 지울 수 있는 템플릿
기능의 경로·script가 백틱 span·링크 대상·셸 블록 밖에 나오면 실패한다.
같은 우회가 다시 들어오는 것을 막는다. 지운 사본에서 통과하는 성질은 앞
커밋의 "passes in a copy without reference-feature"가 본다.
- 버린 대안: 경로 존재만 보는 단위 테스트를 따로 두기(리뷰의 차선책).
검사기와 같은 규칙을 두 곳에 두게 된다.
위험·한계
- 다음에 참조 기능 경로를 백틱 없이 적는 문서 변경은 새 테스트가 막는다.
백틱으로 적으면 참조 기능을 지운 사본에서도 통과한다.
- 언어 없는 펜스 블록은 검사기처럼 셸 블록으로 보고 넘긴다. 그 안의 명령이
아닌 줄(트리 그림 등)에 적은 경로는 검사기도 새 테스트도 보지 않는다.
검증
- desktop batch에서 확인: node scripts/run-vitest.ts run
tests/unit/template-feature-removal-documents.test.ts
tests/unit/documentation-readiness.test.ts, corepack pnpm
verify:documentation, corepack pnpm test:sample-removal
Refs: 1105/14-03
81 lines
5.3 KiB
Markdown
81 lines
5.3 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 (V3 with `responseEnvelope: "ENVELOPE_V1"`) | strict object (`meta` strips) | breaking | `successEnvelopeSchema`, `failureEnvelopeSchema` in `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` |
|
|
|
|
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](../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.
|