문제
V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서
12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감,
retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에
없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도
check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이
breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고
(X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도
behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에
204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다.
고른 방법
- projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다:
acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기
칸 이름: input·output·problem), requestByteLimit, responseByteLimit,
totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery.
- commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지
(classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite
목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로
읽고, 없으면 행에도 없다.
- governance: problemSchema와 unvalidated를 breakingFields에 넣는다.
status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이
빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에
넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지
증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다.
- 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지,
descriptor 함수는 행에 없다는 것을 적었다.
버린 대안
- descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지
기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다.
- V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다.
- 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감
조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다.
위험·한계
- governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어
기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다.
- FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사
대상이 아니다. breaking 칸으로만 잠근다.
- classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다.
검증
- 기준선 재승인 뒤 실험 재실행(check:registries):
X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락),
X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건),
X5 GET 출력 검증기 생략 실패(unvalidated:field-changed),
X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다.
- tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite
있음·없음, governance JSON으로 분류한 8가지 변경.
- run-vitest related(api-operations.ts, governance) 21파일 156건,
registry 테스트 4파일 63건, check:registries:compatibility-fixtures,
check:types, eslint, verify:documentation 통과.
BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의
check:registries가 FE-REG-API:$contract:* contract-field-changed로
실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을
주고 update:registry-baseline을 한 번 돌린다.
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절