fix(contracts)!: 읽기 operation은 SAFE·IDEMPOTENT일 때만 조립한다

문제
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
This commit is contained in:
DongHyeonka
2026-11-04 20:21:04 +09:00
parent a94006b9da
commit e4caafda30
3 changed files with 45 additions and 0 deletions
+1
View File
@@ -102,6 +102,7 @@ context는 URL 앞부분 하나(라우트 루트)를 가진다. 그 아래 기
**틀리면**
- 읽기(GET·HEAD)에 `KEYED`나 `NEVER`를 적으면 계약 조립이 `<method> 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`로 거부한다.
- 서버 보장과 다른 의미를 고른 것은 검사가 잡지 못한다.