Commit Graph
12 Commits
Author SHA1 Message Date
DongHyeonka 3f7e10c91a fix(contracts): 한 계약 기여 안에서 응답 모양이 다른 operation을 거절한다
문제
responseEnvelope는 operation마다 적는 선택 칸이다. 생성 뼈대에 operation을
손으로 더하면서 이 줄을 빠뜨려도 check:types, check:registries, 라우터를
거치는 페이지 테스트가 모두 통과한다. MSW 시나리오 핸들러가 descriptor의
선언대로 답하기 때문이다. 짝 백엔드에 붙이면 그 화면만 SCHEMA_MISMATCH로
깨진다(리뷰 E-1).

고른 방법
계약 조립이 기여 하나 안의 operation이 같은 응답 모양을 읽는지 본다. 값이
없는 것과 "NONE"은 같은 모양이다. 기여 하나는 백엔드 하나의 패키지라서
그 안의 operation은 한 모양이다. 두 백엔드를 쓰는 기능은 기여를 나눈다.
거절 reason은 두 operation과 고칠 방법을 말한다. 앱을 조립하는 모든 테스트와
check:registries가 실패한다.

버린 대안
- responseEnvelope를 필수 칸으로: tsc가 잡는 가장 강한 통제지만 descriptor
  약 25곳(참조, tests, 다운스트림 손 descriptor, 계약 패키지)을 깨는 공개 타입
  변경이다. 같은 실수(일부만 빠뜨림)를 이 규칙이 잡으므로 작은 쪽을 골랐다.
- 기여 단위 기본값: "기본값이 어디서 오나"라는 규칙이 하나 는다.

위험·한계
- 기여 안의 operation 모두에서 줄을 빼면 잡지 못한다. 생성된 gateway 테스트
  (백엔드 본문을 손으로 적음)만 잡는다. 매뉴얼에 적었다.
- 한 기여에 두 모양을 섞던 다운스트림 기여는 조립이 거부한다. 레포 안에서는
  테스트 fixture 하나(api-operation-rows)가 그랬고 고쳤다.

검증
- RED: 새 테스트 3건 중 섞인 기여 거절 1건 실패. GREEN 뒤 통과.
- tests/unit·integration·contract·component·features·runtime-schema·platform·
  architecture 297파일 3,718건: 섞인 fixture 1건만 실패 → 고친 뒤 통과.
- check:types, lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/16-structure-patterns.md 16-01
2026-11-04 22:56:52 +09:00
DongHyeonka 6088f6e533 chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 22:28:57 +09:00
DongHyeonka 1e8b3d049f feat(http): operation이 쓰기 전 업무 거절 code를 선언한다
문제
Envelope operation의 400·409·422는 백엔드 표의 세 code만 NOT_APPLIED이고
나머지는 모두 MAYBE_APPLIED다. 기능의 classifyProblem은 이를 바꿀 수 없다.
짝 백엔드 생성 기능의 create는 이름 규칙을 트랜잭션 전에 검사하고 400
<FEATURE>_INVALID를 준다. 그런데 폼은 "변경 결과를 확인할 수 없습니다"를
띄우고 저장 버튼을 끈다. 입력을 고쳐도 다시 저장할 수 없다(리뷰 실험
X-A·X-B). 401·403·429는 classifyStatus로 operation이 정할 수 있는데
400·409·422는 정할 자리가 없다.

고른 방법 (결정 D2 ①)
- CommandEffectDescriptor에 선택 칸 refusedBeforeWrite?: readonly string[].
  표 밖 400·409·422가 이 목록의 code면 NOT_APPLIED다. 함수가 아니라 code
  목록이라 리뷰할 수 있고, status 범위를 통째로 NOT_APPLIED로 만들 수 없다.
- 조립 검사(assertRefusedBeforeWrite): 목록은 Envelope operation에만,
  code는 백엔드 문법, 중복 금지. IDEMPOTENT_*·IDEMPOTENCY_*는 거절한다
  (409 IDEMPOTENT_IN_FLIGHT의 앞선 요청은 적용될 수 있다).
- 실행기도 같은 code와 표의 code(VALIDATION_FAILED 등)를 무시한다. 조립
  없이 실행기를 부르는 경로의 fail-close다.
- 조립이 목록을 얼려 복사한다(LIVE-03). classifier는 지금처럼 참조로
  두고, 설치본이 원본을 prototype으로 물려받아 classifier의 this가 그대로다.
- 매뉴얼 02 4절과 계약 문서 6.1절에 언제 적고 언제 적지 않는지,
  <FEATURE>_INVALID 예와 거부 문구를 적었다.

버린 대안
- 표 밖 400 전체를 NOT_APPLIED: BAD_PARAMETER·MAPPING_FAILED는 쓰기 뒤에도
  나온다.
- 분류기 판정 복원: 3261208이 버린 길. 400 전체를 NOT_APPLIED로 보는
  분류기가 키 보호를 푼다.
- 결과 불명 화면에 "적용되지 않음" 버튼: 사용자가 모르고 누르면 새 키로
  중복이 생긴다.
- 백엔드 단계 신호(error.applied): 두 repo 계약 변경이다(D2 ②).

위험·한계
- 쓰기 뒤에도 나오는 code를 잘못 적으면 결과 불명 요청이 새 키로 나가
  중복이 생길 수 있다. 책임은 선언한 기능 작성자에게 간다. 매뉴얼이 백엔드
  코드에서 던지는 곳을 확인한 code만 적으라고 한다.
- 생성기(scripts/create-feature.ts)는 이 칸을 아직 쓰지 않는다. 다른 작업이
  이어 받는다.
- 결과 불명 화면이 거절 code의 문구를 보이는 것(08-01 (가))은 하지 않았다.

검증
- RED: 새 테스트 17건이 이 변경 전 소스에서 실패(조립 규칙 10, 판정 3,
  envelope 통합 3, form-foundation 1).
- GREEN: tests/unit·integration·component·features·contract·runtime-schema
  253파일 3,199건 통과. 폼: WORKLOG_INVALID를 선언하면 결과 unavailable,
  저장 켜짐, 고친 값 저장 fetch 2회, 키 key-1 → key-2. 선언하지 않으면
  effect-unknown, 저장 꺼짐, fetch 1회.
- 변이: 실행기의 멱등성·표 code 무시 제거, 조립의 멱등성 규칙 제거, 목록
  복사 제거, 실행기가 목록을 넘기지 않음 모두 검출. 보존 조건 M5·M10·M24도
  계속 검출.
- check:types, lint, check:registries, check:architecture,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-01
Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-01
2026-11-04 20:38:12 +09:00
DongHyeonka 61f70cb9b8 fix(contracts)!: 쓰기 operation의 SAFE 재시도 의미를 조립에서 거절한다
문제
설계 정본 8.3은 SAFE를 "GET/HEAD; 보낸 뒤 network 실패에도 재시도 허용"
으로 정한다. 실행기는 그 규칙대로 SAFE면 보낸 뒤 응답을 잃어도 다시
보낸다(http-retry-lifecycle.ts canRetryTransport). 그런데 조립 검사는
쓰기가 SAFE인지 보지 않는다. 생성된 뼈대 descriptor가 GET·SAFE·
retryBudget 2이고, 매뉴얼은 쓰기를 더할 때 이 파일을 고쳐 쓰라고 한다.
retrySemantics를 바꾸지 않으면 POST가 조립을 통과하고, 응답을 잃은 생성
요청이 최대 두 번 더 나간다(리뷰 실험 X-E: fetch 2회, 결과 SUCCESS).
V2에도 이 규칙은 없었다.

고른 방법
assertHttpContract의 쓰기 가지(GET·HEAD 밖)에서 retrySemantics가 SAFE면
operation·method와 고를 값(IDEMPOTENT·KEYED·NEVER), 매뉴얼 절을 담아
거절한다. 매뉴얼 02 3절 "틀리면"에 같은 문장을 더했다.

버린 대안
실행기에서 쓰기의 SAFE를 NEVER처럼 다루기: 잘못 적은 계약이 조용히
다른 뜻으로 돈다. 조립 때 알리는 쪽이 고칠 곳을 바로 보여 준다.

위험·한계
쓰기를 SAFE로 적은 다운스트림은 부팅에서 실패한다. 의도한 실패다.
실행기를 조립 없이 직접 부르는 테스트 경로는 이 검사를 거치지 않는다.

검증
- RED: tests/unit/external-contract-runtime.test.ts의 POST·PUT·PATCH·DELETE
  × SAFE 4건 실패(조립 통과).
- GREEN: 같은 파일 23건 통과. GET·SAFE와 PUT·IDEMPOTENT는 그대로 조립된다.
- tests/unit·integration·contract·features·runtime-schema 214파일 2,904건
  통과. check:types:app·test, eslint, verify:documentation 통과.

BREAKING CHANGE: POST·PUT·PATCH·DELETE operation에 retrySemantics "SAFE"를
쓰면 composeContractContributions가 거절한다. 서버 보장에 맞춰 IDEMPOTENT,
KEYED(commandRecovery 필요) 또는 NEVER(retryBudget 0)로 바꾼다.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-03
2026-11-04 20:25:54 +09:00
DongHyeonka e4caafda30 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
2026-11-04 20:21:04 +09:00
DongHyeonka 8b7c6ebf6c perf(contracts): 검증 생략 목록을 부팅 경로 밖에서 만든다 (1101/07-03)
문제
- 93180f6(합친 커밋 d3ddc89)이 초기 JS를 늘렸다. 기능 모양 측정
  (scripts/scale/measure-feature-shape-growth.ts) 기준으로 기능 0개가
  202,376 → 202,526 B(+150)로, 기능 1개 추가분이 960 → 1,029 B로 늘었다.
  tests/unit/feature-shape-growth.test.ts의 1 KiB 상한을 넘는다.
- 원인은 두 가지다.
  - 부팅 때 도는 composeContractContributions가 검증기마다 생략 표시를
    읽고 목록을 만들었다(feature-platform 청크 +164 B). 이 목록을 쓰는
    곳은 플랫폼 개요 화면(lazy 라우트)뿐이다.
  - 공유 zod-validator.ts가 기능이 두 개가 되면 lazy 청크 하나로 따로
    나왔다. 모든 context-routes·feature-runtime import의 preload 목록에
    파일 이름이 하나 늘어 boot·feature-declarations 청크가 각각 약 25 B
    커졌다.

고른 방법
- 목록 계산을 src/contracts/unvalidated-payload.ts의
  listUnvalidatedPayloads(composed)로 옮긴다. 플랫폼 개요 화면만 이것을
  import한다. 결정의 뜻(생략한 operation이 조립 결과에서 목록으로
  나온다)은 그대로다. 계산 시점만 화면이 열릴 때로 미룬다.
  ComposedContractContributions.unvalidatedPayloads 필드는 뺀다.
- unvalidatedPayload 팩토리도 같은 모듈로 옮긴다.
- 조립기의 표시 검사도 뺀다. 이유가 빈 생략은 unvalidatedPayload가 만들
  때 거부한다(TypeError). 손으로 붙인 표시는 값이 "NONE"이 아니거나 이유가
  없어도 목록에 나온다(화면에는 "이유 없음"). 그래서 생략이 숨지 않는다.
  external-contract-runtime.ts에는 RuntimeValidator의 선택 타입 필드
  2개만 남는다.
- vite.config.ts에서 zod-validator.ts를 schema-registry.ts와 같은 lazy
  청크로 묶는다. 어댑터를 import하는 곳은 이미 schema-registry 청크를
  preload한다. includeDependenciesRecursively: false라서 다른 모듈은
  끌려오지 않고, 두 모듈 모두 부팅 그래프 밖이다.

버린 대안
- 조립기에 "NONE + 이유" 검사만 남기기: feature-platform 청크 +57 B gzip.
  검사를 팩토리와 목록으로 옮기면 0 B다. 손으로 붙인 잘못된 표시를
  부팅 때 거부하지 못하지만, 목록에는 나온다.
- zodValidator를 schema-registry.ts 안에 정의: 빌드 설정 없이 같은 결과가
  나오지만 결정한 위치(src/contracts/zod-validator.ts)와 다르고, 다음 단계의
  기능 생성 명령이 그 경로를 쓴다.
- 어댑터를 zod.ts에 두기: zod 입구는 초기 청크라 기능 0개 초기 JS가 는다.

위험·한계
- 조립 결과 타입에서 unvalidatedPayloads 필드가 빠진다. 93180f6 뒤 이
  필드를 쓴 코드는 listUnvalidatedPayloads로 바꿔야 한다. repo 안에서는
  화면과 테스트만 썼다.
- 손으로 만든 잘못된 표시(예: validation: "PARTIAL")는 더 이상 조립에서
  거부되지 않는다. 목록에만 나온다. 테스트 2건을 이 동작으로 바꿨다.
- 청크 묶음은 빌드 설정에 두 파일 경로를 적는다. 파일 이름을 바꾸면
  정규식도 함께 바꿔야 한다. 놓치면 바이트만 늘고 동작은 같다.
- 플랫폼 개요 화면을 열면 schema-registry 청크에 어댑터(351 B raw)가 같이
  온다.

검증
- 기능 모양 측정(0개 / 1개 추가분, gzip B):
  - ee81c44(07-03 전): 202,376 / 960
  - d3ddc89(07-03 합친 뒤): 202,526 / 1,029
  - 목록만 부팅 밖으로: 202,407 / 1,035
  - 청크 묶음 추가: 202,424 / 983
  - 조립기 검사 제거(이 커밋): 202,371 / 958
- feature-shape-growth.test.ts 6건 통과.
- 07-03 테스트 3파일 33건 통과(zod-validator, external-contract-runtime,
  starter-platform-overview-page).
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  270파일 3,203건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
- tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. 아키텍처 그래프 검사(pnpm 대신 exec stub) 413 모듈 PASS.
  check-registries PASS(compatibility=none).
- 본 빌드 초기 JS gzip 202,371 B(26파일). raw 644,782 B로 ee81c44 측정과
  같다.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03
2026-11-03 01:58:38 +09:00
DongHyeonka d3ddc8957f feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제
- zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의
  reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은
  복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을
  structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다.
- RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도
  검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이
  타입·이름·조립 결과 어디에도 남지 않는다.

고른 방법 (C: 공유 어댑터 + 생략 표시)
- zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과
  tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은
  참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code
  문자열). tests/helpers도 이제 성공 값을 복사한다.
- unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에
  둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다.
  zod가 필요 없어서 검증기 프로토콜 옆에 뒀다.
- composeContractContributions가 이 표시가 붙은 검증기를
  unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로
  내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두
  본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다.
- 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약"
  표를 둔다. 목록이 비면 그리지 않는다.

버린 대안
- (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다.
- (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의
  자체 검증기까지 막아 §4 설계와 충돌한다.

위험·한계
- 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을
  통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을
  만들어 그 길로 생략한 것만 드러낸다.
- 공개 계약 추가: RuntimeValidator에 선택 필드 2개,
  ComposedContractContributions에 필드 1개, 새 export zodValidator·
  unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다.
  ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야
  한다(repo 안에는 없다).
- 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다.
  플랫폼 개요 청크 4,625 → 4,750 B.
- 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는
  돌리지 않았다.
- tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는
  그대로 둔다(16-01이 그 파일을 넓힌다).

검증
- RED(수정 전): zod-validator.test.ts "Cannot find module
  '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와
  starter-platform-overview-page.test.tsx "unvalidatedPayload is not a
  function". 3파일 모두 실패.
- GREEN: 같은 3파일 33건 통과.
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
  tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. check-registries PASS(compatibility=none), verify-documentation
  PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신
  exec stub) 383 모듈 PASS.
- 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능
  폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용.
  src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립·
  플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3
2026-11-03 01:34:32 +09:00
DongHyeonka 32da8a40e9 test(contracts): 조립기·선언 검증의 쓰기 API 규칙 5개를 고정한다 (07-06)
문제
조립기와 선언 검증의 쓰기 API 규칙 5개는 지워도 관련 테스트가 모두
통과한다(리뷰 변이 MX1·MX2·MX5·MX6·MX9).
- MX1 읽기 operation의 command descriptor 금지
  (external-contract-runtime.ts). 실행기는 쓰기 여부를 메서드가 아니라
  commandEffect !== null로 정하므로 GET이 쓰기로 처리되는 것을 막는
  유일한 경계다.
- MX9 KEYED 쓰기의 복구 descriptor 필수
- MX6 NEVER 재시도와 재시도 예산 1 이상의 모순 거부
- MX5 V2 KEYED_COMMAND의 idempotencyKeyPolicy REQUIRED 정합
  (api-operations.ts)
- MX2 mapper 레지스트리 키 = mapperId (boundary-mapper.ts)
조립기는 여러 번 다시 쓰인 파일이라 규칙 줄이 빠져도 CI가 모른다.

고른 방법
규칙마다 그 규칙만 어긴 행 하나로 실패 사례를 둔다. 오류 메시지는 기능
작성자가 쓰기 API 규칙을 배우는 통로라 reason 문자열을 그대로 단언한다.
정상 대조군은 기존 사례(TEST_CONTRACT_CONTRIBUTION 조립, command()
정의, 키가 맞는 mapper 등록)를 쓰거나 같은 테스트 안에 둔다. 코드 변경은
없다.

버린 대안
- 메시지 대신 ContractContributionError 종류만 단언: 다른 규칙이 먼저
  실패해도 통과해서 변이를 놓칠 수 있다.

위험·한계
- 메시지 문구를 바꾸면 테스트도 바꿔야 한다. 의도한 결합이다.
- MX6은 실행기(http-retry-lifecycle)가 한 번 더 막는다. 이 테스트는
  조립 단계의 안내 메시지를 지킨다.

검증
- RED: 변이 5개를 하나씩 넣고 바꾼 3파일을 돌렸다. 이 커밋 전 테스트로는
  5개 모두 살아남음(26/26 통과). 새 테스트로는 5개 모두 죽음, 각 변이마다
  해당 사례 1건만 실패(30/31).
- GREEN: 변이 없이 31/31 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka c06338956e fix(contracts): 참조 기능 밖의 TEMPLATE_FIXTURE 기여를 거부한다 (07-04)
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.

고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
  ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
  쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
  기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
  있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
  (REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
  이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
  EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
  featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
  테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
  바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
  단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
  읽었는지 아닌지를 구분하지 못했다.

버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
  test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
  /REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
  잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
  남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
  필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
  depcruise로 볼 수 없다.

위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
  (라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
  스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
  복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
  거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
  측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
  꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
  참조 기능 id 하나로만 풀린다.

검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
  external-contract-runtime "rejects a fixture copied into a product
  feature" -> "Expected contract composition to fail."
  reference-fixture-provenance "rejects a second fixture contribution"
  -> "expected undefined to be 'reference-feature: only one
  TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features
  tests/platform tests/component tests/contract tests/runtime-schema
  tests/integration (pnpm·corepack을 띄우는 fixture-node-modules,
  security-followup-archive, deployment-admission, lab-performance 제외)
  267 files / 3107 tests 중 3106 통과. 실패 1건은
  provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로
  scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0.
- 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep).
- 미실행: test:sample-removal, check:architecture(pnpm 필요).

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonkaandClaude Opus 5.5 0bcee348c5 fix(contracts): report malformed validator results as THROWN instead of throwing (07-06)
invokeValidator spread result.issues outside its try and treated any truthy
success as valid, so a hand-written validator could throw past the executor
or pass unchecked data. The result is now read inside the try and checked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:10 +09:00
DongHyeonka 0eb23875cb fix: harden invalidation registry governance 2026-08-01 23:59:11 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00