Commit Graph
4 Commits
Author SHA1 Message Date
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.

고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
  resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
  스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
  parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
  parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
  지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
  legacy-http-credential-authority, bounded-json-compatibility,
  request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
  지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
  boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
  계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
  422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
  비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
  보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
  1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
  risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
  경로를 V3 파일로 바꿨다.

버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
  곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.

위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
  CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
  자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
  재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
  커밋에서 지우지 않았다. 다음 커밋이 지운다.

검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
  check:adapter-inventory(140 files), check:diagnostics, check:registries,
  check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).

BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
2026-11-03 21:12:34 +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
DongHyeonkaandClaude Opus 5.5 56de543d49 refactor(contracts): make the external-contract-runtime shapes canonical (Q-6.7-8)
D-15. `RuntimeValidator` and `MappingResult` in
external-contract-runtime.ts are the canonical validator protocol and
mapping result. The other shapes stay as public names over them:

- schema-registry.ts: `RuntimeSchemaCodec` is documented as the
  registry adapter and gains `runtimeSchemaCodecFromValidator`.
- boundary-mapper.ts: the flat `{ ok: false, code }` result is named
  `BoundaryMappingResult`; `MappingResult` stays as an alias, and
  `toContractMappingResult` converts to the canonical shape.

The reference feature wrapped each zod schema twice (a RuntimeValidator
in the contract contribution and a separate `project`/`codec` in
reference-schemas.ts). It now has one `zodValidator`; the registry
codecs are a one-liner over it, and validateReferencePayload/Request
look up the codec with Object.hasOwn.

Verified: characterization test
tests/features/reference-feature/reference-validator-protocol.test.ts
passed before and after (array paths, dotted paths, codec ids,
SCHEMA_NOT_REGISTERED); adapter case added to boundary-mapper.test.ts;
gates green except the known removal-fixture test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:45:37 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00