test(contracts): V2 행과 V3 descriptor를 양방향과 스키마 id까지 맞춰 본다 (07-02)

문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.

고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
  V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
  commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
  요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
  (V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
  응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
  대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
  정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
  게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.

버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
  V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
  변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
  defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
  생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
  이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
  비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
  fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
  parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.

위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
  않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
  주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
  zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
  파일을 돌려야 걸린다.

검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
  L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
  ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
  ("responseSchema": "ReferenceResourcePayload" vs "...V2").
  L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
  "cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
  함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
This commit is contained in:
DongHyeonka
2026-11-01 22:35:54 +09:00
parent c06338956e
commit 3c31576940
3 changed files with 53 additions and 3 deletions
+4
View File
@@ -129,6 +129,10 @@ selected app. Every build and check script runs it first; run it yourself with
entered. Do not import it statically from anywhere: each feature would add
its whole executable code to the initial chunk again, about 3.9 KB gzip
(`tests/unit/feature-shape-growth.test.ts` bounds one feature at 1 KiB).
An HTTP API is written twice: its API contract operation (V2) is what
`check:registries` governs, and its contract contribution descriptor (V3)
is what executes. `tests/unit/http-operation-v2-v3-parity.test.ts` fails
when one exists without the other or when they disagree.
A product feature's contract contribution uses an `EXTERNAL_PACKAGE`
source. `TEMPLATE_FIXTURE` belongs to `reference-feature` only and never
joins the release contract set; the composer rejects it anywhere else.
+9
View File
@@ -27,6 +27,15 @@ export type ApiOperation = Readonly<{
maxEncodedSearchBytes?: number;
}>;
/**
* 07-02. A V2 row is the declaration `check:registries` (FE-REG-API) governs;
* it is not what executes. The executed copy of the same HTTP API is the V3
* descriptor (`InstalledHttpContract`) in the feature's contract contribution.
* A feature writes both, and `tests/unit/http-operation-v2-v3-parity.test.ts`
* checks they name the same operations, method, path, statuses, limits, auth
* profile, replay and write semantics, request body and schema ids. The
* deadline is not compared: V2 `timeoutMs` is `null` while V3 always has one.
*/
export type RestOperationV2 = ApiOperation &
Readonly<{
contractVersion: 2;
+40 -3
View File
@@ -9,8 +9,8 @@ import {
INSTALLED_CONTRACT_CONTRIBUTIONS,
} from "../../src/features/loaded-feature-runtimes.ts";
// 07-03 (D-7). FE-REG-API governs the V2 rows while the V3 descriptors are
// what executes. Until V2 is generated from V3, both copies must agree.
// 07-03 (D-7), 07-02. FE-REG-API governs the V2 rows while the V3 descriptors
// are what executes. Until V2 is generated from V3, both copies must agree.
const RETRY_SEMANTICS_FOR_REPLAY_POLICY = Object.freeze({
SAFE: "SAFE",
IDEMPOTENT: "IDEMPOTENT",
@@ -29,8 +29,35 @@ const v2Rows = (Object.values(API_OPERATIONS) as readonly ApiOperation[]).filter
(operation): operation is RestOperationV2 => operation.contractVersion === 2,
);
// V3 validates the whole canonical input with one schema; V2 splits it into a
// path schema and a request (search or body) schema, "NoRequest" when absent.
// An operation that needs both has no rule yet and fails here until one is
// written down.
const NO_REQUEST = "NoRequest";
function v2InputSchema(row: RestOperationV2): string {
const declared = [row.pathSchema, row.requestSchema].filter(
(schemaId) => schemaId !== NO_REQUEST,
);
expect(
declared.length,
`${row.operationId}: V2 declares both a path and a request schema; decide which V3 input schema matches them`,
).toBeLessThanOrEqual(1);
return declared[0] ?? NO_REQUEST;
}
describe("HTTP operation V2 rows and V3 descriptors", () => {
it("declare the same method, path, statuses, limit, auth profile and replay policy", () => {
// 07-02. Both directions: a V3-only operation executes outside the
// FE-REG-API gate, a V2-only one is governed but never executes. With the
// sample feature removed both sets are empty, which is why there is no
// "at least one row" assertion (test:sample-removal runs this file).
it("cover the same operations", () => {
expect([...v3ByOperationId.keys()].sort(), "V3 descriptors").toEqual(
v2Rows.map((row) => row.operationId).sort(),
);
});
it("declare the same method, path, statuses, limit, auth profile, replay policy, write semantics, request body and schema ids", () => {
for (const row of v2Rows) {
const descriptor = v3ByOperationId.get(row.operationId);
expect(descriptor, `${row.operationId} has no V3 descriptor`).toBeDefined();
@@ -43,6 +70,12 @@ describe("HTTP operation V2 rows and V3 descriptors", () => {
maxResponseBytes: descriptor.frontend.responseByteLimit,
authProfileId: descriptor.frontend.authProfileId,
retrySemantics: descriptor.contract.retrySemantics,
// The executor treats an operation as a write by its effect
// descriptor, not by its method.
semantics: descriptor.contract.commandEffect === null ? "QUERY" : "COMMAND",
requestBody: descriptor.contract.requestBody,
inputSchema: descriptor.contract.inputValidator.schemaId,
responseSchema: descriptor.contract.outputValidator.schemaId,
},
row.operationId,
).toEqual({
@@ -52,6 +85,10 @@ describe("HTTP operation V2 rows and V3 descriptors", () => {
maxResponseBytes: row.maxResponseBytes,
authProfileId: row.authProfileId,
retrySemantics: RETRY_SEMANTICS_FOR_REPLAY_POLICY[row.replayPolicy],
semantics: row.semantics,
requestBody: row.requestSource === "body" ? "JSON" : "NONE",
inputSchema: v2InputSchema(row),
responseSchema: row.responseSchema,
});
}
});