Commit Graph
9 Commits
Author SHA1 Message Date
DongHyeonka 7db32e1343 fix(http): V3 실행기가 짝 백엔드 Envelope를 operation 단위로 읽는다
문제
create:feature가 만든 기능과 참조 기능이 쓰는 V3 실행기
(http-execution-v3.ts, feature-http-binding.ts)는 성공 본문을 DTO로,
실패 본문을 problem details(최상위 code)로 바로 검증한다. 짝 백엔드는
모든 JSON 응답을 Envelope {success, data|error, meta}로 보내고 null 필드는
키째 뺀다(백엔드 docs/web/http-contract.md 1절). 그래서 생성한 기능은 짝
백엔드의 성공을 SCHEMA_MISMATCH로, 실패를 PROBLEM_SCHEMA_INVALID(쓰기는
결과 불명)로 읽는다. 백엔드 맞추기(969979d~64e98ee)는 V2 클라이언트에만
들어갔다.

고른 방법: (가) V3 실행기에 operation 단위 Envelope 읽기
- V3 descriptor에 선택 필드 responseEnvelope("NONE" | "ENVELOPE_V1")를
  둔다. 조립은 이 키를 허용하고 모르는 값을 거부한다. 값이 없으면 지금과
  같다.
- ENVELOPE_V1이면 실행기가 바이트 상한·구조 예산을 Envelope 전체에 건 뒤
  프레임을 확인한다. outputValidator는 data(키가 없으면 null),
  problemValidator는 error를 받는다. 성공 status에 Envelope가 아닌 본문은
  새 위반 ENVELOPE_MISMATCH다. 실패 Envelope의 바이트 상한은
  min(64 KiB, responseByteLimit)이다.
- V2 client.ts의 멱등성 거절 표·필드 검증 판정·gateway status 규칙을
  backend-envelope.ts로 옮기고 V2, V3 실행기, feature binding이 함께
  읽는다. 실행기는 그 표의 판정(422·400 거절, 필드 목록 400은 적용 안 됨,
  409 IDEMPOTENT_IN_FLIGHT·503 IDEMPOTENCY_UNAVAILABLE은 결과 불명)을
  classifyProblem보다 먼저 쓴다. binding은 mapProblem이 답하지 않으면 V2와
  같은 kind·code·validationIssues로 읽는다. V2 출력은 바뀌지 않았다.
- create:feature 뼈대: contribution이 ENVELOPE_V1을 선언하고 problem
  스키마가 Envelope error(code 필수)다. 백엔드 본문을 그대로 적은
  <base>-http-gateway.test.ts를 생성한다.
- MSW createHttpScenarioHandler는 descriptor가 ENVELOPE_V1이면 Envelope로
  답한다.

버린 대안
- provider 단위(실행기 전체): V3 실행기는 baseUrl 하나라 앱 전체가 바뀐다.
  참조 기능·테스트 계약의 problem details fixture가 모두 깨지고 한 앱이 두
  모양의 API를 쓸 수 없다.
- (나) 백엔드 problem+json·DTO 모드: 백엔드 소유자 결정 2(JSON은 모두
  Envelope)와 반대이고 백엔드가 두 모양을 계속 유지해야 한다.
- (다) 기능 스키마가 Envelope를 감쌈: 기능마다 null 생략·success 판별·
  멱등성 판정을 다시 쓰고, V2 행(data 스키마)과 V3 스키마 ID가 갈라진다.

위험·한계
- HttpContractViolationKind에 ENVELOPE_MISMATCH가 더해졌다. default 없는
  exhaustive switch는 분기를 더해야 한다.
- 실행기가 ENVELOPE_V1 operation의 위 판정을 classifyProblem보다 먼저
  정한다. 패키지가 409 IDEMPOTENT_IN_FLIGHT를 적용 안 됨이라 해도 결과
  불명이다.
- V2와 남은 차이: 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸
  KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 같다). 구조
  예산은 V3에만 있다.
- 참조 기능은 그대로 DTO·problem details다. tests/e2e/accessibility.spec.ts는
  모든 API에 []로 답하므로 생성한 기능 라우트는 오류 화면이 검사된다(e2e는
  돌리지 않았다).
- 초기 JS 202,770 → 203,321 B(+551 B, 예산 204,800 B).

검증
- RED: tests/integration/http-execution-v3-envelope.test.ts 19건 중 17건
  실패(성공 → SCHEMA_MISMATCH, 실패 → PROBLEM_SCHEMA_INVALID·MAYBE_APPLIED,
  조립 → unexpected key: responseEnvelope). 크기 2건은 처음부터 통과(동작
  고정).
- GREEN: 같은 파일 25건 통과. 같은 응답을 V2와 V3에 보내 kind·code·
  httpStatus·effect·retryAfterMs·validationIssues가 같음을 7가지 응답으로
  비교한다.
- check:types, lint, check:architecture, check:adapter-inventory,
  check:registries, check:diagnostics, check:i18n, check:ci 통과.
  test:unit 2,604, test:component 244, test:integration 200 통과.
  tests/features·tests/contract 124건 통과.
  test:feature-scaffold 16개 검사 통과(생성한 gateway 테스트 5건,
  Envelope로 답하는 목록 화면 테스트 3건 포함).
  test:sample-removal 23개 검사 통과.
  check:bundle 통과(203,321 / 204,800 B).

Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.3, 14.6
2026-11-03 20:10:51 +09:00
DongHyeonka 5d064b8ace test(features): 기능을 더해도 기능 밖 테스트와 시나리오 하네스가 깨지지 않게 한다 (16-02)
문제: 기능 하나를 더하면(리뷰 16 실험 E) 기능 밖 테스트 3개가 깨진다.
① installed-context-routing은 context 목록이 정확히
["reference-context"]이고 첫 context가 참조 context라고 단정한다.
② product-feature-switch는 정렬 첫 기능(INSTALLED_PRODUCT_FEATURE_IDS[0])을
끄고 참조 라우트를 본다. 새 기능이 앞에 정렬되면 깨진다.
③ release-manifest fixture가 contractSet.packages: []로 고정이다.
EXTERNAL_PACKAGE를 쓰는 첫 기능에서 반드시 깨진다.
또 시나리오 하네스의 operation ID 타입이 테스트 계약 3개 리터럴이고
시나리오 응답 함수가 /api/test-entities 핸들러 안에 묶여 있다. 새 기능
테스트가 자기 operation에 실패 시나리오를 쓰려면 카탈로그를 고쳐야 한다
(안 고치면 TS2345, 실행하면 catalog.ts:469 TypeError).

방법: 리뷰의 (b) 최소 개선.
① "목록에 reference-context가 있다"로 바꾸고, 라우트 검사는 id로 찾은
  context에서 한다.
② REFERENCE_FEATURE_ID를 쓴다.
③ fixture의 packages와 setDigest를 EXPECTED_CONTRACT_SET_PACKAGES에서
  만든다.
하네스: HttpScenarioOperationId를 string으로 넓혔다. 시나리오 사실(명령
여부, 응답 상한, 성공 status)은 httpScenarioOperationFacts가 설치된 V3
descriptor에서 읽는다. 시나리오 응답은 tests/mocks/handlers/
http-scenarios.ts의 createHttpScenarioHandler로 옮겼다. 경로와 method도
descriptor에서 만든다. test-entities 핸들러는 이 함수를 쓰고 카탈로그
확인(assertOperationScenario)을 그대로 거친다. 카탈로그 기대값 57개는
계속 테스트 계약 3개에만 있고, 그 타입도 3개로 둔다. 카탈로그에 없는
operation을 assertOperationScenario에 넘기면 TypeError 대신 그 사실을
말하는 오류가 난다. test-entities 핸들러는 요청의 이름·id를 되돌려 주던
응답을 카탈로그 payload로 고정했다(기대값과 같은 값이다).
새 기능 테스트의 MSW 시나리오: server.use(createHttpScenarioHandler(
<자기 설치 계약>, { scenario: "server-terminal-503", payload }))
버린 대안: (a) 현상 유지는 기능마다 4곳을 고친다. (c) 하네스를 기능별로
나누면 변경이 크고 test-evidence.json의 증거 경로가 바뀐다. 기능
operation을 카탈로그에 더하는 방식은 기능 추가를 공유 파일 수정으로
만든다.
test-evidence.json은 바꾸지 않았다(sourceContracts 토큰이 test-entities.ts에
그대로 있다). 제거 드릴의 플랫폼 보존 목록에 http-scenarios.ts를 더했고,
테스트 전략 문서 11절에 사용법을 적었다.

위험·한계:
- 앱 전체를 렌더하는 테스트에서 response-too-large는 끝나지 않는다.
  실행기가 MSW가 넘긴 본문을 cancel하는 promise가 끝나지 않는 기존
  제약이다. 카탈로그 통합 테스트는 프록시 fetcher로 우회한다.
- 같은 실험에서 기능 밖 테스트가 더 깨진다. 이 발견 범위 밖이라 두었다.
  http-operation-v2-v3-parity는 스키마 ID "NoRequest"를 센티널로 고정한다.
  스키마 ID는 전역이라 두 번째 기능은 다른 이름을 써야 하고, 그러면 이
  테스트가 깨진다. manual-a11y-evidence·documentation-readiness(라우트별
  a11y 기록, 16-01)와 second-api-feature-registries(무효화 그래프 추가가
  breaking, 16-01)도 깨진다.
- test:sample-removal, test:http-scenario-evidence는 pnpm이 필요해 돌리지
  않았다.

검증:
RED: 참조 기능을 토큰 경계로 order로 바꾼 복사본(order-context,
EXTERNAL_PACKAGE 출처 포함, 커밋 안 함)을 넣고 tests/features
tests/component tests/runtime-schema를 돌렸다. 5파일 8개 실패. 기능 밖은
① 2개(["order-context","reference-context"]), ② 2개(order-feature를 꺼서
참조 링크가 남음), ③ 1개(ReleaseManifestError)다. 나머지 3개는 복사한
테스트다. 하네스 probe는 TS2345 2건, 실행 시 TypeError(catalog.ts:469).
새 통합 테스트는 기준 하네스에서 모듈 없음으로 실패하고, 기준
assertOperationScenario는 미등록 operation에 TypeError를 낸다.
GREEN: 같은 복사본으로 같은 폴더와 카탈로그 통합 테스트를 돌렸다. 78파일
중 실패는 출처를 바꾼 복사본 provenance 1파일뿐이고 ①~③은 통과한다.
order 테스트가 createHttpScenarioHandler(LIST_ORDER_RESOURCES_CONTRACT)로
content-type-mismatch·schema-mismatch·server-terminal-503을 화면에서
확인했다(카탈로그 수정 없음).
복사본을 지운 뒤: tests/features·component·runtime-schema·unit·
integration(security-followup-archive 제외)·contract 250파일 3111개 통과,
카탈로그 57/57, check-test-evidence --scenario-only·--source-only PASS,
tsc app·test·node 통과, verify-documentation-readiness PASS_SCOPED,
check-ci-contract PASS, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-02
2026-11-03 01:49:11 +09:00
DongHyeonka 498ae87554 test(evidence): HTTP 시나리오와 타입 음성 fixture를 테스트 계약으로 옮긴다 (0929/10-02)
문제: 샘플 제거 절차(scripts/test-sample-removal.ts)의 SAMPLE_EXTRAS가
플랫폼 검사도 함께 지운다. HTTP 실패 시나리오 카탈로그(57개)와 tests/mocks,
test:http-scenario-evidence(FE-GATE-007), 기능 API 타입 음성 fixture 8개와
check:types:fixture:* 8개(FE-GATE-003)가 참조 기능 계약을 import해서
샘플 소유로 묶여 있었다. 드릴은 플랫폼 경로 4개만 확인하므로 통과하고,
제품은 가드레일이 줄었다는 것을 모른다.

방법: 카탈로그와 handler를 tests/helpers/external-contract-fixture.ts의
테스트 계약(TEST_LIST/DETAIL, 명령)으로 옮겼다. 바이트 상한·명령 여부·성공
status는 계약에서 읽는다. 명령은 효과를 분류하는 패키지처럼
TEST_CLASSIFIED_CREATE_HTTP_CONTRACT를 더해 기존 기대값(401/403/429·422·
409 CONFLICT는 NOT_APPLIED, 409 IN_FLIGHT·404·503은 MAYBE_APPLIED)을
그대로 지킨다. TEST_CREATE_HTTP_CONTRACT의 분류기는 실행기 테스트가
"분류기 없음"을 확인하는 데 쓰므로 바꾸지 않았다. 문제 스키마에 선택
code만 더했다.
타입 fixture는 fixture tsconfig만 컴파일하는 fixture-feature-contract.ts의
테스트 기능(operation ID를 literal로 좁힌 테스트 계약, "fixture-feature"
입력 등록)을 쓴다. 등록 augmentation이 app·test 프로그램에 들어가지 않는다.
참조 기능 전용 handler(성공 응답만 쓰였다)는 tests/features/reference-feature
로 옮겼다. test-evidence.json의 owner는 platform이다. SAMPLE_EXTRAS에서
이 경로·스크립트를 빼고, 드릴의 플랫폼 보존 확인 목록에 16개 경로를 더했다.
샘플이 증거 정책을 갖지 않으므로 "등록 안 됨" 오류 검사는 지웠다.
버린 대안: README에 "함께 사라지는 검사" 목록만 적는다. 비용은 0이지만
검사는 계속 사라진다.

위험: fixture 스크립트 이름(check:types:fixture:reference-operation)과
파일 이름은 그대로라 이름이 내용(TEST_GET_ENTITY)과 다르다. CI 스크립트·
gates·워크플로 스냅샷을 함께 바꿔야 해서 미뤘다. 드릴의 제외 목록에 있는
tests/unit/http-scenario-evidence.test.ts는 그대로 뒀다.
test:sample-removal 자체는 pnpm이 필요해 돌리지 않았다.

검증: RED는 기준 복사본에 드릴의 삭제 목록을 적용했다. 카탈로그 테스트·
tests/mocks·타입 fixture 16파일이 지워지고 CI 스크립트 9개가 빠지는데 보존
확인은 4/4로 통과한다. GREEN은 같은 적용 뒤 보존 확인 16/16, 잔여 이름은
드릴이 빼는 removal-fixture.test.ts 하나, 타입 fixture 8개가 기존과 같은
진단(TS2345·2741·2353·2322·2345·2322·2322·2339) 1건씩으로 실패, 카탈로그
57/57 실행·check-test-evidence --scenario-only PASS, tests/component와
카탈로그 36파일 226개 통과, tsc -p tsconfig.test.json 통과. worktree에서는
테스트 계약 사용 파일·참조 기능·카탈로그 59파일 535개, scale session 2파일
통과, 음성 fixture의 양성 대조 컴파일 통과, tsc test·node 통과,
check-ci-contract PASS, 바꾼 파일 eslint 통과.
2026-11-03 01:18:36 +09:00
DongHyeonka 112c870fe3 fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).

고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.

버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
  NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
  같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
  APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
  틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
  변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
  목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
  응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
  요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
  만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.

위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
  contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
  적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
  고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
  백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
  (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
  템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
  Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
  참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
  referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
  code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
  (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
  이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
  "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
  확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
  run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
  두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.

검증
- RED(수정 전): reference-production-vertical "keeps the key when the
  resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
  분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
  (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
  카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
  tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
  제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
  PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
  읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
  check:ci 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 19:09:47 +09:00
DongHyeonkaandClaude Opus 5.5 2afee67150 fix(http): let the package classify command 401/403/429 and keep re-login first (03-02)
These statuses skipped the package classifier and always became
MAYBE_APPLIED, so an expired session ended in "contact support" or the
unknown-result screen. The descriptor gains optional classifyStatus, the
reference create declares NOT_APPLIED, and AUTH_REQUIRED keeps reauth.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:16:25 +09:00
DongHyeonka abdd90ad5d test: execute the HTTP scenario catalog 2026-08-02 11:17:28 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00
donghyeon-ka 98d4fd4960 feat: harden test and registry evidence 2026-07-26 17:15:26 +09:00