From 3c3157694095c46c99531ec53f22492feb311d2d Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:09:27 +0900 Subject: [PATCH] =?UTF-8?q?test(contracts):=20V2=20=ED=96=89=EA=B3=BC=20V3?= =?UTF-8?q?=20descriptor=EB=A5=BC=20=EC=96=91=EB=B0=A9=ED=96=A5=EA=B3=BC?= =?UTF-8?q?=20=EC=8A=A4=ED=82=A4=EB=A7=88=20id=EA=B9=8C=EC=A7=80=20?= =?UTF-8?q?=EB=A7=9E=EC=B6=B0=20=EB=B3=B8=EB=8B=A4=20(07-02)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 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 --- docs/architecture/starter-experience.md | 4 ++ src/contracts/api-operations.ts | 9 ++++ .../unit/http-operation-v2-v3-parity.test.ts | 43 +++++++++++++++++-- 3 files changed, 53 insertions(+), 3 deletions(-) diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index 99d56352..cfa84ace 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -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. diff --git a/src/contracts/api-operations.ts b/src/contracts/api-operations.ts index 692021e6..c333f26b 100644 --- a/src/contracts/api-operations.ts +++ b/src/contracts/api-operations.ts @@ -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; diff --git a/tests/unit/http-operation-v2-v3-parity.test.ts b/tests/unit/http-operation-v2-v3-parity.test.ts index 340c0372..287a747f 100644 --- a/tests/unit/http-operation-v2-v3-parity.test.ts +++ b/tests/unit/http-operation-v2-v3-parity.test.ts @@ -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, }); } });