From e4caafda3070da4d55802fc6ca8fcccfd672dbe6 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:21:04 +0900 Subject: [PATCH] =?UTF-8?q?fix(contracts)!:=20=EC=9D=BD=EA=B8=B0=20operati?= =?UTF-8?q?on=EC=9D=80=20SAFE=C2=B7IDEMPOTENT=EC=9D=BC=20=EB=95=8C?= =?UTF-8?q?=EB=A7=8C=20=EC=A1=B0=EB=A6=BD=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 GET에 `retrySemantics: "KEYED"`(commandRecovery 없음)나 `"NEVER"`를 적어도 계약 조립이 통과하고 FE-REG-API 행에 그 값이 남는다. KEYED 복구 descriptor 검사가 쓰기 분기 안에만 있기 때문이다. 실행기는 이 GET을 쓰기로 보지 않아 재시도 없는 읽기로 돌린다. 매뉴얼은 "읽기(GET)는 늘 SAFE"라 적는다. V2 `defineRestOperation`은 조회에 SAFE·IDEMPOTENT만 허용했는데 V2 삭제 때 이 규칙이 V3로 옮겨지지 않았다(실험 R1). 고른 방법 assertHttpContract의 읽기 분기에서 GET·HEAD의 retrySemantics가 SAFE나 IDEMPOTENT가 아니면 method와 값을 담아 거절한다. realtime snapshot 바인딩이 요구하는 짝(GET + SAFE·IDEMPOTENT)과 같은 어휘다. 매뉴얼 02 3절 "틀리면"에 거절 문구를 더했다. 버린 대안 - 레지스트리 governance의 allowedValues로 막기: method별 허용값을 표현할 칸이 없고, 조립(부팅 경로)이 아니라 check:registries에서만 걸린다. 위험·한계 - GET·HEAD를 KEYED나 NEVER로 적은 다운스트림 descriptor는 부팅에서 계약 조립 실패가 된다. 템플릿 안에는 그런 descriptor가 없다(grep). - 쓰기의 SAFE 금지(03-03)는 이 커밋 범위가 아니다. 검증 - RED: tests/unit/external-contract-runtime.test.ts의 GET·HEAD × KEYED·NEVER 4건이 실패(조립 통과)했다. - GREEN: `run-vitest related src/contracts/external-contract-runtime.ts` 105파일 950건 통과. check:types, eslint, check:registries, verify:documentation 통과. BREAKING CHANGE: GET·HEAD operation의 retrySemantics가 KEYED나 NEVER이면 계약 조립이 CONTRACT_CONTRIBUTION_INVALID로 실패한다. SAFE(재시도 허용)나 IDEMPOTENT로 바꾼다. 재시도를 막으려면 frontend.retryBudget을 0으로 둔다. Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01 --- docs/manual/02-decision-tables.md | 1 + src/contracts/external-contract-runtime.ts | 11 +++++++ tests/unit/external-contract-runtime.test.ts | 33 ++++++++++++++++++++ 3 files changed, 45 insertions(+) diff --git a/docs/manual/02-decision-tables.md b/docs/manual/02-decision-tables.md index 96fe6213..4972f5cf 100644 --- a/docs/manual/02-decision-tables.md +++ b/docs/manual/02-decision-tables.md @@ -102,6 +102,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기 **틀리면** +- 읽기(GET·HEAD)에 `KEYED`나 `NEVER`를 적으면 계약 조립이 ` is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>`으로 거부한다. - `NEVER`에 `retryBudget`을 0보다 크게 주면 계약 조립이 `retry budget contradicts NEVER retry semantics`로 거부한다. - `KEYED`에 `commandRecovery`가 없으면 `KEYED commands require a recovery descriptor`로 거부한다. - 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다. diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 4ac7ffec..2250fb90 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -508,6 +508,17 @@ function assertHttpContract( if (contract.requestBody !== "NONE") { fail(`${label}: read operations carry no request body`); } + // 1103/07-01 (c). The executor runs a read as a read whatever it is + // declared; KEYED or NEVER here only looks like a decision the executor + // never makes. A realtime snapshot binding reads the same pair. + if ( + contract.retrySemantics !== "SAFE" && + contract.retrySemantics !== "IDEMPOTENT" + ) { + fail( + `${label}: ${contract.method} is a read; its retrySemantics is SAFE or IDEMPOTENT, not ${contract.retrySemantics}`, + ); + } } else { if (!contract.commandEffect) { fail(`${label}: command operations require a command effect descriptor`); diff --git a/tests/unit/external-contract-runtime.test.ts b/tests/unit/external-contract-runtime.test.ts index ba47667a..3e9f8943 100644 --- a/tests/unit/external-contract-runtime.test.ts +++ b/tests/unit/external-contract-runtime.test.ts @@ -124,6 +124,39 @@ describe("write operation rules", () => { ).toBe("test-feature/TEST_LIST_ENTITIES: read operations carry no command descriptors"); }); + // 1103/07-01 (c). The KEYED recovery check sits in the write branch, so a + // GET written as KEYED or NEVER used to compose and run as a read with no + // retry. A read is SAFE or IDEMPOTENT (docs/manual/02-decision-tables.md 3절). + it.each([ + ["GET", "KEYED"], + ["GET", "NEVER"], + ["HEAD", "KEYED"], + ["HEAD", "NEVER"], + ] as const)("rejects a %s declared %s", (method, retrySemantics) => { + expect( + reasonFor({ + ...listRow, + contract: { ...listRow.contract, method, retrySemantics }, + frontend: { ...listRow.frontend, retryBudget: 0 }, + }), + ).toBe( + `test-feature/TEST_LIST_ENTITIES: ${method} is a read; its retrySemantics is SAFE or IDEMPOTENT, not ${retrySemantics}`, + ); + }); + + it.each(["SAFE", "IDEMPOTENT"] as const)("composes a GET declared %s", (retrySemantics) => { + expect( + composeContractContributions([ + contribution("read-rule", [ + { + ...listRow, + contract: { ...listRow.contract, retrySemantics }, + } as InstalledContractContribution["http"][number], + ]), + ]).httpByOperationId.size, + ).toBe(1); + }); + it("requires a recovery descriptor on a KEYED command", () => { expect( reasonFor({