Commit Graph
357 Commits
Author SHA1 Message Date
DongHyeonka 6fc77bb71f fix(design-system): h2·h3·h4에 제목 단계 크기와 굵기를 준다 (08-04)
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로
되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두
h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다
제목 크기를 따로 만들게 된다.

고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem)
·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰
(--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤
base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면
h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰
값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로
골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에
흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이
바로 실패하고, 결과는 아래 e2e가 지킨다.

위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은
오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게
보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다.

검증:
- RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패
  (h2 16px, h3 16px: "Expected: > 16, Received: 16").
- GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n·
  ui-gallery·app-shell·responsive·theme·design-system-interactions·
  compact-smoke + typography chromium/chromium-compact 32/32 통과(별도
  playwright 설정, vite preview, pnpm 없이 빌드).
- check-design-system PASS(48 tokens). 시각 회귀는 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:31 +09:00
DongHyeonka d0f3993b60 fix(presentation): 검색값만 바뀌면 포커스·스크롤·진단을 건드리지 않는다 (08-02)
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로
썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로
튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다.
이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈)
navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고
권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2).

고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1
(B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만
하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지
번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다.
버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런
라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에
더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라
React 19의 useEffectEvent보다 의도가 덜 드러난다.

위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가
준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적
확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다.

검증:
- RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가
  <main id="main-content">에 있었고 route.changed가 필터 테스트 1→3,
  링크 테스트 1→2로 늘었다.
- GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과.
  tsc(app, test) 통과, eslint(바꾼 파일) 통과,
  verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02
2026-11-01 23:20:31 +09:00
DongHyeonka 37e5f9d682 test(e2e): SW spec이 이미 켠 worker와 생성된 사전 캐시 목록을 쓴다 (0929/11-03)
SW e2e는 템플릿의 `= null;` 줄만 바꿔 worker를 켰다. 제품이 이미 ACTIVE로
켠 트리에서는 2건이 실패하고 4건이 실행되지 않았다. 사전 캐시 목록도
템플릿 기준으로 고정돼 있어 해시 파일을 더하면 2건이 실패했다.

선택을 지금 값과 상관없이 고치되, 이미 ACTIVE면 제품의 handler를 그대로
두는 `turnOnServiceWorker` 하나로 모았다. 빌드가 만든 사전 캐시 목록을
`precached`로 돌려주고 spec이 그 목록과 비교한다. 같은 문제를 고친
0929/06-04(`96a4f68`)의 `selectActiveServiceWorker`는 ACTIVE 선택을
템플릿 값으로 덮어써 제품 handler가 빠지므로 이 함수로 바꿨고, 실패한
준비 단계에서 임시 복사본을 지우는 처리는 유지했다(두 브랜치 병합 때
오케스트레이터가 충돌을 풀었다).

위험: 테스트 도우미만 바뀐다. 0929/06-04 단위 테스트의 기대값이 "ACTIVE
선택도 템플릿 값으로 덮어쓴다"에서 "ACTIVE 선택은 그대로 둔다"로 바뀐다.
검증: ACTIVE 선택과 해시 파일 추가 트리 모두 6 passed(에이전트).
병합 뒤 service-worker-build-output 단위 테스트 5/5, SW e2e chromium·webkit
12/12, tsc(test), eslint 통과.
2026-11-01 23:20:28 +09:00
DongHyeonka 41e79627d0 test(scale): 기능 규모 기준선에 측정한 커밋을 남기고 다시 잰다 (0929/11-05)
문제: config/scale/feature-shape-growth.json에 측정 시각만 있고 어느
코드를 쟀는지가 없다. 기준선이 지금 코드와 맞는지, 다음 측정과 비교할 수
있는지 알 수 없다. 실제로 기준선은 2026-09-27 측정이고, 그 뒤 15-01이
초기 청크 구조를 바꿨다(ceilings.json도 "baseline predates 15-01"이라고
적고 있었다). 기준선 0개 초기 JS 200,001 B, 기능당 2,907 B는 지금 코드와
다르다.

고른 방법:
- 측정 스크립트가 시작할 때 `git rev-parse HEAD`와 추적 파일 변경 목록
  (`git status --porcelain --untracked-files=no`)을 읽어 결과의
  `source: { commit, modifiedPaths }`에 싣는다. 변경 목록이 비면 커밋만으로
  재현된다는 뜻이다. 측정 중 트리가 바뀔 수 있어 시작할 때 읽는다.
- 기준선을 현재 코드로 다시 잰다(--sizes=0,25,100 --repeats=2 --write).
- ceilings.json의 수치를 새 기준선에 맞춘다. 초기 JS 여유는 리뷰 개선안대로
  "예산 − 기준선 ÷ 기능당 증가"로 적는다(2,291 B ÷ 약 610 B ≈ 3개).
- 단위 테스트가 기준선에 40자 commit과 modifiedPaths 배열이 있는지 본다.

버린 대안:
- 기준선 커밋이 현재 이력의 조상인지 테스트로 확인: 이력 없이 3-way로
  이식하는 다운스트림(tech-log)에서는 템플릿 커밋이 없어 항상 실패한다.
- dirty 트리면 --write를 거절: 이 커밋처럼 측정 스크립트와 기준선을 한
  커밋에 넣을 수 없게 된다. 대신 변경 경로를 그대로 기록한다.

위험·한계:
- 기록된 커밋은 2be973a(이 브랜치의 직전 커밋)이고 modifiedPaths는 측정
  스크립트와 그 테스트 2개다. 측정 대상(src, vite 설정)은 그 커밋과 같다.
  이 브랜치를 rebase하면 기록된 SHA가 이력에서 사라진다. 그때는 다시 재야
  한다.
- 시간 값은 호스트 부하(loadavg 27~29)에 따라 흔들린다. 바이트와
  instantiation 수만 비교 대상이다.
- 15-01 커밋 본문의 202,361 B와 이번 0개 측정 202,509 B는 148 B 다르다.
  원인은 확인하지 않았다. ceilings.json은 기준선 수치 하나로 통일했다.

검증:
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  -t 'commits a baseline' — "expected undefined to deeply equal { commit:
  StringMatching…" 실패.
- 측정(flock): 0개 202,509 B·720,060 inst, 25개 218,010 B, 100개
  263,119 B·12,399,171 inst, 반복 2회 바이트·inst 동일. 기능당 초기 JS
  약 610 B, lazy 약 8.3 KB·8파일, inst 약 117k, tsc 메모리 약 36 MB,
  route 4개.
- 재현: 같은 트리에서 --sizes=0,25 --repeats=1을 다시 돌려 0개 202,509 B,
  25개 218,010 B로 같음.
- GREEN: feature-shape-growth.test.ts 5 passed(빌드 측정 테스트 포함).
- tsc(node·test), eslint(바꾼 2파일), verify-documentation-readiness
  PASS_SCOPED.

Refs: docs/reviews/2026-09-29-maturity-review/11-tests-browser-release-scale.md 11-05
2026-11-01 23:18:45 +09:00
DongHyeonka ba98048b29 test(design-system): Popover 포커스 반환 테스트가 전제를 먼저 만든다 (10-02)
문제: "Escape 뒤 포커스가 trigger로 돌아온다" 단언은 trigger를 클릭한
채로 Escape를 누른다. Popover는 열 때 포커스를 내용으로 옮기지 않으므로
포커스는 처음부터 끝까지 trigger에 있다. overlays.tsx의 Escape 처리에서
`triggerRef.current?.focus()`를 지워도(M15) 관련 테스트가 모두 통과한다.
내용 안의 버튼으로 Tab한 뒤 Escape를 누르는 키보드 사용자는 포커스를
잃어도 아무 테스트가 모른다(WCAG 2.4.3).

고른 방법: 열고 나서 Tab으로 내용 안의 "내부 작업" 버튼에 포커스를
옮기고, 그 버튼에 포커스가 있는지 먼저 단언한다. 그 뒤 Escape와 trigger
포커스 단언은 그대로 둔다. 리뷰 최소 개선안 그대로다.

위험·한계: 바깥 클릭으로 닫을 때의 포커스 반환(closeOutside)은 이
테스트가 보지 않는다. 이번 발견 범위 밖이다.

검증:
- RED(M15 적용): 변경 전 테스트 파일은 통과, 새 테스트는
  "expect(element).toHaveFocus()" 실패(design-system-platform.test.tsx
  trigger 단언).
- GREEN: 원본 overlays.tsx로 되돌리고 related overlays.tsx --run —
  23파일 152 passed.
- eslint(바꾼 파일), tsc -p tsconfig.test.json 통과.

Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-02
2026-11-01 23:18:45 +09:00
DongHyeonka 5ce3db98ef test(visual): 시각 회귀 허용치를 절대 픽셀 50으로 바꾼다 (11-03)
문제: 시각 회귀 허용치가 maxDiffPixelRatio 0.002(이미지의 0.2%)라서
긴 화면일수록 허용 픽셀이 커진다. 넓은 셸 1440×900은 2,592 px를
허용한다. 그래서 UI-04 수정을 되돌린 회귀(선택 상자 값 잘림, 1,145 px)가
통과한다. 골든이 코드와 조금씩 달라져도 실패하지 않아 어느 골든이 낡았는지
알 수 없다. VD-08 8항은 작은 rasterization 차이만 허용한다고 적는다.

고른 방법: maxDiffPixels 50. 11-02로 글꼴과 래스터 설정을 고정한 뒤
같은 호스트에서 깨끗한 빌드를 다시 찍으면 0 px 차이다(아래 검증). 50은
흩어진 anti-aliasing만 덮고, 지금까지 잰 가장 작은 실제 변화(낡은
compact 골든 175 px)보다 작다. tests/unit/visual-regression-tolerance.test.ts가
비율 허용치가 다시 들어오거나 절대값이 175 이상이 되면 실패한다.

버린 대안:
- 0 px: 이 호스트에서는 흔들리지 않았지만 다른 Linux 러너의 래스터는
  재 보지 못했다(U-1). 50은 실제 회귀를 놓치지 않는 범위의 여유다.
- 위험 영역만 따로 찍어 비율의 분모를 줄이기: 골든이 늘어난다.
- 현상 유지: 회귀를 놓친다.

위험·한계:
- 커밋된 골든 2장이 새 허용치에서 실패한다. 깨끗한 빌드 기준으로 넓은
  셸 614 px, compact 6,955 px 다르다. compact는 이 변경 전 0.2%에서도
  이미 실패한다(08-01의 서랍 변경). 골든은 다시 찍지 않았다. 오케스트레이터가
  마지막에 한 번 찍는다. 나머지 3장은 0 px로 통과한다.
- 다른 호스트의 래스터 차이는 재 보지 못했다. 수십 px 넘게 나오면 그
  측정값으로 허용치를 정한다(리뷰 재검토 조건).

검증 (pnpm을 부르지 않으려고 build-frontend.ts로 빌드하고 webServer만
vite preview로 바꾼 로컬 설정 사본으로 실행, flock, 비교 대상은 깨끗한
빌드로 새로 찍은 scratch 골든. 저장소 골든은 건드리지 않았다):
- 깨끗한 빌드 vs scratch 골든, 허용치 0, --repeat-each=3: 16 passed.
- RED: UI-04 변이(f1b9d3c의 shell.css 변경을 git apply -R)를 넣은 빌드,
  0.2% 비율: 6 passed. 허용치 0: 넓은 셸만 "1145 pixels are different".
- GREEN: 같은 변이, maxDiffPixels 50: 넓은 셸 실패(1,145 px), 나머지 통과.
  변이를 되돌리고 다시 빌드, --repeat-each=2: 11 passed.
- 새 단위 테스트는 수정 전 "expected 0.002 to be undefined"로 실패,
  수정 뒤 2 passed. supply-chain·deletable-history-documents·
  test-evidence-source-rules와 함께 37 passed.
- tsc(node·test), eslint, check-test-evidence --source-only PASS,
  verify-documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md 11-03
2026-11-01 23:18:45 +09:00
DongHyeonka 95e7d1107c test(vitest): skip·todo·only가 남은 실행을 실패시킨다 (10-04)
문제: Vitest는 skip·todo 테스트를 통과로 센다. `it.skip`이나
`it.todo`가 든 파일은 CI=true에서도 종료 코드 0으로 끝난다.
`context.skip()`도 같다. `.only`는 Vitest 기본값 때문에 CI에서만 막히고,
로컬에서는 같은 파일의 나머지 테스트를 조용히 건너뛴다.
check:test-evidence의 소스 검사가 quarantine 주석 없는 `.skip(`·`.only(`
글자를 잡지만, `it.todo`, `context.skip()`, `skipIf`는 보지 못한다.

고른 방법:
- vitest.config.ts에 allowOnly: false를 둬 `.only`를 어디서나 막는다.
- scripts/lib/no-skipped-tests-reporter.ts reporter가 실행 끝에
  state가 skipped인 테스트를 찾으면 이름을 출력하고 exitCode를 1로 둔다.
  -t, 태그 필터, file:line처럼 호출자가 일부러 좁힌 실행은 예외다.
  게이트는 실행을 좁히지 않는다.
- reporter는 scripts/run-vitest.ts가 붙인다. CLI --reporter는 config의
  reporters를 대체하므로 config에 두면 package script에서 빠진다.
  run-vitest.ts는 package script와 scale tier가 모두 거치는 입구다.
  호출자가 reporter를 하나도 주지 않으면 default를 함께 붙인다.

버린 대안:
- 리뷰 최소 개선안의 junit `skipped > 0` 검사: Vitest junit은 mode가
  skip·todo인 테스트만 <skipped/>로 적고 `context.skip()`은 통과처럼
  적는다. junit을 쓰지 않는 실행(scale tier, http-scenario-catalog,
  로컬 단일 파일)은 아예 보지 못한다.
- tests/setup.ts의 afterAll 검사: 모든 테스트가 skip인 파일은 hook이
  돌지 않아 잡지 못한다.
- eslint-plugin-vitest no-disabled-tests: 새 의존성이 생기고
  `context.skip()`을 못 잡는다.

위험·한계:
- run-vitest.ts를 거치지 않는 직접 `vitest` 실행에는 reporter가 붙지
  않는다. allowOnly는 config라서 그때도 적용된다.
- 호출자가 reporter를 주지 않으면 default reporter를 고정해서 붙인다.
  Vitest가 AI 에이전트 환경에서 고르는 agent reporter 대신 default가
  나온다.
- 본문 없는 `describe.todo`처럼 테스트가 없는 묶음은 세지 않는다.
- check:test-evidence는 quarantine 주석이 있는 `.skip(`을 허용하지만
  이 reporter는 Vitest에서 그것도 실패시킨다. 지금 quarantine은
  Playwright spec에만 있어 충돌하는 테스트는 없다. 전략 문서 16.5절에
  "quarantine은 Vitest 테스트를 통과시키지 않는다"고 적었다. Vitest에도
  quarantine이 필요해지면 허용 목록을 따로 둬야 한다.
- 지금 저장소의 Vitest 테스트에는 skip·todo·only가 없다.

검증:
- RED(P-B 재현, run-vitest.ts로 skip+todo, only, context.skip() 파일을
  CI 없음/CI=true로): 수정 전 6경우 중 5경우 exit 0("1 passed | 1
  skipped | 1 todo"). only+CI=true만 exit 1.
- 새 tests/unit/no-skipped-tests-reporter.test.ts는 수정 전 "Cannot find
  module ../../scripts/lib/no-skipped-tests-reporter.ts"로 실패.
- GREEN: 같은 6경우 모두 exit 1. skip·todo·context.skip()은 "N test(s)
  did not run" 목록, only는 "Unexpected .only modifier". junit reporter를
  준 실행도 exit 1. -t로 좁힌 실행과 file:line 실행은 exit 0. 새 테스트
  11 passed.
- 빠른 계층 전체(unit·component·integration·contract·runtime-schema·
  platform·architecture·features·release·scripts·recipes, pnpm 설치를
  하는 fixture-node-modules.test.ts 제외, maxWorkers 4): 3,228 passed,
  1 failed. 실패는 provider-guardian-transaction의 fs.watch ENOSPC(호스트
  inotify 한도)이고 reporter 없이 vitest를 직접 돌려도 같다. skip 목록
  출력은 없었다.
- tsc -p tsconfig.node.json, tsconfig.test.json, eslint(바꾼 4파일),
  check-ci-contract, generate-ci-workflow --check,
  verify-documentation-readiness(PASS_SCOPED) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-04
2026-11-01 23:18:45 +09:00
DongHyeonka dddf6353e0 test(contracts): 이벤트 계약 검증을 실제 이벤트 행으로 고정한다 (10-01)
문제: "정확하지 않은 이벤트 계약을 거부한다" 테스트는 공용 fixture의
events가 빈 배열이라 첫 줄 `if (events.length === 0) return;`에서 끝난다.
단언이 하나도 실행되지 않는다. 그래서 composeContractContributions의
이벤트 snapshot(M17)이나 assertEventContract 호출(M18)을 빼도 관련
테스트가 모두 통과한다. 템플릿 안에는 이벤트를 기여하는 계약이 없어서
이 경로를 지키는 테스트가 따로 없다.

고른 방법:
- tests/helpers/external-contract-fixture.ts에 TEST_EVENT_CONTRACT를
  추가한다. 공용 TEST_CONTRACT_CONTRIBUTION의 events는 그대로 비워 둔다.
  이 fixture를 쓰는 다른 테스트 20여 파일의 전제를 바꾸지 않기 위해서다.
- 빈 배열이면 return하던 테스트를 지우고 "event contracts" 묶음을 둔다.
  정상 행이 snapshot으로 설치되는지(같은 내용, 다른 객체, frozen) 먼저
  확인해서 아래 거부 경우가 다른 이유로 throw하는 것이 아님을 보인다.
  거부 경우는 HTTP 쪽 hostileRows처럼 모양(추가 필드, 다른 prototype,
  accessor)과 내용(빈 eventType, 공백, C1 제어문자, 160바이트 초과,
  validator 없음, 빈 schemaId), 중복 eventType이다.
  ContractContributionError로 던지는지까지 본다.

버린 대안: tests/setup.ts에 전역 expect.hasAssertions()를 두는 방법.
같은 종류의 빈 테스트를 모두 막지만 모든 vitest 프로젝트의 테스트 계약을
바꾸고, 리뷰는 빠른 계층 8개 폴더에서만 확인했다. 이 발견의 범위를
넘는다.

위험·한계: 템플릿 안에서 eventByType을 읽는 코드는 여전히 없다. 이
테스트는 composition 단계의 검증만 고정한다.

검증:
- RED(변경 전 테스트 파일과 새 파일을 함께, 변이 적용):
  M17(snapshotEventContract가 입력을 그대로 반환) — 옛 파일 16개 통과,
  새 파일 4개 실패("installs a well-formed event contract as its own
  snapshot", extra own field, custom prototype, accessor eventType).
  M18(assertEventContract 호출 제거) — 옛 파일 16개 통과, 새 파일 6개
  실패(빈·공백·제어문자·160바이트 초과 eventType, validator 2종).
- GREEN: node scripts/run-vitest.ts run
  tests/unit/contract-registry-immutability.test.ts — 26 passed.
- related tests/helpers/external-contract-fixture.ts
  src/contracts/external-contract-runtime.ts — 97파일 796 passed.
- tsc -p tsconfig.test.json, eslint(바꾼 2파일) 통과.

Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md 10-01
2026-11-01 23:18:45 +09:00
DongHyeonka 9142390422 fix(browser-transfer): upload 실패 번역이 code도 보고 행동을 고른다 (0929/01-01)
문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고
적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표
밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고
retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른
행동을 가리킨다.
- ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true.
  표대로면 RESELECT다.
- ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE.
  다시 부르면 성공한다.
- ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새
  session으로 성공한다.
- ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다.
- ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY):
  RESUME. 서버가 같은 값을 다시 준다.

고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에
둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의
NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE.
나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나
REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는
번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다.
포트 표 주석과 설계 문서 표에 이 규칙을 적었다.

버린 대안:
- 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE
  경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금
  STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다.
- 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기
  실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못
  보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다.
- 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난
  리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다.

위험·한계:
- ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object
  store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로
  고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다.
  리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건
  ("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime
  호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다.
  그래서 이 발견은 부분 충족이다.
- 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나
  (resumable-upload-runtime-contract.test.ts "rejects a part capability
  that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다.
  다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이
  필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지
  않았다.
- 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류
  값을 주입했다.
- file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산
  56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다.

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패.
  ① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대
  RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대
  NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다.
- GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면
  retryable:false" 단언을 더했고 통과한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
  image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼
  파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
  check-architecture(exec 전용 shim) 통과. check-optional-recipes
  (source) file-transfer 56031/56100.

Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:48 +09:00
DongHyeonka aedd32841f fix(cache-storage): 정책 변경과 손상 뒤에도 다음 배포가 pointer를 덮어쓴다 (0929/02-01)
문제: active pointer를 읽을 때 rollback 목록 길이를 현재
retainedPreviousReleaseCount와 비교한다. 3에서 1로 줄이는 정상 설정
변경이나 pointer JSON 손상 뒤에는 읽기가 CORRUPT_DATA가 되고, 조회·
활성화·정리·inspect가 모두 여기서 멈춘다. control cache를 지우는 API가
없어 사용자가 사이트 데이터를 지우기 전까지 오프라인 캐시가 꺼진 채로
남고, cleanup이 막혀 배포마다 release cache가 쌓인다. 이번 라운드에도
Node와 실제 Cache API 3엔진에서 재현됐다.

고른 방법(지난 리뷰 4.1절의 (나)+(다)):
- (다) isActivePointer는 목록 길이를 현재 값이 아니라 정책이 허용하는
  최댓값(5, MAX_RETAINED_PREVIOUS_RELEASE_COUNT)과만 비교한다. 정책
  검증과 같은 상수를 쓴다. 다음 activation이 이미 하던 slice로 목록을
  현재 값으로 자른다.
- (나) activateRelease는 이전 pointer 읽기가 CORRUPT_DATA면 없는
  것으로 보고, 전체 재검증을 통과한 후보로 rollback 목록 없이
  덮어쓴다. 일시 오류(UNAVAILABLE 등)는 지금처럼 활성화를 멈춘다.

버린 대안:
- 현상 유지 + "사이트 데이터 삭제" 안내. 운영자가 원인을 알 수 없고
  캐시가 계속 쌓인다.
- control을 지우는 admin API. 포트가 늘고 호출자가 언제 불러야 하는지
  알아야 한다.
- (다)만 적용. 정책 변경은 풀리지만 JSON 손상은 풀리지 않는다.

위험·한계:
- 지키던 성질은 그대로다. 검증한 후보만 활성화하고(재검증은 pointer
  읽기 전에 끝난다), 조회는 manifest digest가 맞는 바이트만 돌려준다.
  읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다.
  손상 pointer 상태의 조회와 cleanup은 다음 activation까지 여전히
  CORRUPT_DATA다.
- 덮어쓰면 손상 pointer의 rollback 목록을 잃는다. 원래 읽을 수 없던
  값이다. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다.
  그 탭의 조회는 네트워크로 떨어진다. Service Worker drain(VD-15)을
  구현하면 이 규칙을 다시 본다(지난 리뷰 4.1절 7).
- 리뷰가 "가능하면"으로 적은 3엔진 browser spec(E-2)은 추가하지
  않았다. 단위 테스트(MemoryCacheStorage)로만 확인했다.
- service-worker-pwa 레시피 번들 9,665 → 9,716 / 10,000 gzip bytes.

검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 2건 실패.
  retained 3 → 1 뒤 조회가 { ok: false }(기대 ok:true), 잘린 pointer
  뒤 다음 배포의 activate가 { ok: false }.
- GREEN: 같은 파일 8건 통과. 일시 오류 가드 테스트 1건을 함께 넣었다.
  activate가 모든 pointer 실패를 무시하도록 바꾼 변이를 이 테스트가
  잡는다(1건 실패 확인 뒤 되돌림).
- 회귀: public-response-cache 단위 3파일 40건 통과. tsc app·test·
  service-worker·recipes 통과. 바꾼 파일 eslint 통과.
  verify-documentation-readiness PASS_SCOPED. check-optional-recipes
  (source) PASS.

Refs: docs/reviews/2026-09-29-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:48 +09:00
DongHyeonka 8ad11c0b64 fix(browser-files): preview와 download의 dispose가 자기 lease만 푼다 (02-01)
문제: runtime은 object URL lease registry 하나를 preview와 download에
같이 넘긴다. 두 쪽의 dispose()가 모두 registry 전체의 dispose()를
불러, 누가 만든 lease인지 구분하지 않고 전부 revoke한다.
runtime.previews.dispose()를 부르면 30초 grace 중인 download blob
URL까지 바로 revoke된다(E-9). 브라우저가 아직 blob을 읽기 전이면 그
download가 실패할 수 있다. 반대로 download의 dispose()는 다른 화면의
preview URL을 끊는다. registry 주석은 이 dispose를 "route teardown"
에서 쓰라고 읽혔다.

고른 방법(리뷰 5.2절의 (나)): 한도는 같이 쓰고 해제 권한만 나눈다.
registry에 scope()를 두어 소비자마다 자기가 만든 lease 집합을
들고, scope의 dispose()는 그것만 release한다. preview와 download
adapter는 각자 scope로 lease를 만든다. registry 전체 dispose()는
runtime.dispose()만 부른다. 포트 시그니처는 그대로이고,
TransientPreviewPort.dispose()에 효과 범위를 주석으로 적었다. 설계
문서 3.5절에 해제 권한과 route 정리 방법을 적고, 바뀐 줄 번호를
맞췄다.

버린 대안:
- 포트 주석만 고친다(가). 함정이 코드에 그대로 남는다.
- 소비자마다 registry를 나눈다(다). 해제 범위는 맞지만 탭 전체의
  합계 바이트 상한이 두 곳으로 갈라진다.
- TransientPreviewPort에서 dispose()를 뺀다(라). 공개 포트 변경이라
  이번 범위(포트는 추가만)를 넘는다. (나)와 함께 할 수 있어 남겨 둔다.

위험·한계:
- previews.dispose() 뒤 그 runtime의 preview가 계속 UNAVAILABLE인
  것(영향 ②)과, previews.dispose()가 다른 화면의 preview lease까지
  푸는 것(영향 ①, 같은 소비자 안)은 그대로다. 문서에 route 정리는
  lease마다 release()로 하라고 적었다. 완전히 막으려면 (라)가 필요하다.
- scope가 들고 있는 release 함수 집합만큼 메모리가 조금 는다. lease
  release 때 집합에서 빠지므로 lease 수 상한(기본 16)을 넘지 않는다.
- file-transfer 레시피 번들이 55,856 → 55,937 gzip bytes가 되어 예산
  55,900을 넘었다. 다음 백 단위 규칙대로 56,000으로 올렸다.

검증:
- RED(수정 전): browser-file-runtime.test.ts 새 1건 "expected
  [ 'blob:runtime-download' ] to deeply equal []"(previews.dispose()가
  download URL을 revoke). browser-file-download.test.ts 새 1건
  "expected [ 'blob:shared-1', 'blob:shared-2' ] to deeply equal
  [ 'blob:shared-2' ]"(download dispose()가 다른 소비자의 lease를
  revoke).
- GREEN: browser-file 단위 5파일 64건 통과. runtime dispose가 모든
  lease를 즉시 revoke하는 기존 테스트도 통과.
- 회귀: browser-file·presigned·json-schema 단위 10파일 168건 통과.
  tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
  (exec 전용 shim) 통과, check-adapter-inventory 통과,
  verify-documentation-readiness PASS_SCOPED,
  check-optional-recipes(source) file-transfer 55937/56000.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 5b96529c53 fix(cross-context-invalidation): publish 실패 원인을 관측 reason에 싣는다 (02-05)
문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이
INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random
실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그
함수가 reason을 고정한다. bootstrap은 이 reason을 그대로
cache.operation.failed 진단에 싣는다. 난수 실패나 topic version
불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다.

고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는
이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사
실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason
값은 만들지 않는다. 호출자에게 돌려주는 결과
{ok:false, reason:"INVALID_EVENT"}는 그대로다.

위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는
대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가
없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는
수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해
이 worktree에서 돌리지 않았다.

검증:
- RED(수정 전): cross-tab-invalidation.test.ts 새 1건이
  "expected [ 'INVALID_ENVELOPE' ] to deeply equal
  [ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패.
- GREEN: 같은 파일 통과.
- 회귀: cross-tab-invalidation·tanstack-cache-coordinator·
  runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 3bb1829cda fix(cache-storage): stage 재검증 실패를 CACHE_STAGE로 기록한다 (02-03)
문제: 이미 stage된 release를 다시 stage하면 후보를 재검증한다.
재검증 함수 verifyReleaseCandidate는 활성화와 같이 쓰는 함수라 실패
Result의 operation을 CACHE_ACTIVATE로 만든다. 활성화 경로는
rebaseFailure로 바꾸지만 stage의 재사용 경로는 그대로 돌려준다.
Cache API가 재검증 중 일시 오류를 내면 stage 결과와 관측이 모두
CACHE_ACTIVATE가 된다. 운영자는 "활성화 실패"로 읽고, error.operation
으로 분기하는 호출자는 잘못된 경로를 탄다.

고른 방법: stage 재사용 경로도 활성화 경로처럼
rebaseFailure(..., "CACHE_STAGE")로 돌려준다. 한 줄이다.

버린 대안: verifyReleaseCandidate가 operation을 인자로 받게 하는 안.
호출부 세 곳(stage, activate, inspect)을 모두 바꾸고, inspect는 실패를
밖으로 내지 않아 이득이 없다. 리뷰가 함께 적은
readAndValidateResponse의 CACHE_STAGE 고정은 두 소비 경로가 이미
rebase하거나 결과를 내보내지 않아 겉으로 드러나는 결함이 없으므로
건드리지 않았다.

위험·한계: 동작(실패를 성공으로 바꾸지 않음, 후보를 지우지 않음)은
그대로다. 바뀌는 것은 실패의 operation 값뿐이다. service-worker-pwa
레시피 번들 9,662 → 9,665 / 10,000 gzip bytes.

검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 1건이
  operation "CACHE_ACTIVATE"(기대 "CACHE_STAGE")로 실패.
- GREEN: public-response-cache 단위 3파일 37건 통과.
- 회귀: tsc app·test·service-worker 통과. 바꾼 파일 eslint 통과.
  check-optional-recipes(source) PASS.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 6b7b53fe01 perf(image-cdn): 같은 이미지를 동시에 resolve하면 probe를 한 번만 돌린다 (01-04)
문제: resolve()는 통과한 probe 기록(passedProbes)을 slot을 기다리기
전에만 본다. 같은 asset·preset을 동시에 5번 resolve하면 probe가 5번
돈다. probe마다 preset의 encoded 예산까지 no-store로 내려받고
decode하며, 같은 이미지가 probe slot을 차지해 다른 이미지의 probe가
밀린다.

고른 방법: asset·preset별로 "진행 중인 probe 단계"(slot 대기, probe,
통과 기록)를 promise 하나로 둔다. 뒤에 온 호출은 그 단계가 끝나기를
자기 signal로 기다린 뒤 기록된 통과를 재사용한다. probe 자체를
공유하지 않으므로 호출마다 abort가 독립이다. 앞선 probe가 실패하면
기다린 호출이 직접 probe한다(실패는 재사용하지 않는다는 기존 규칙).
X5(동시 5회, maxConcurrentProbes 2)에서 probe가 1회다.

버린 대안:
- 리뷰가 제안한 slot 획득 뒤 재확인. 넣어 보니 X5에서 probe가 3회로
  완료 기준(2회 이하)을 못 맞춘다. slot은 원시 probe가 끝날 때
  넘겨지는데(TR-RR-07), 통과 기록은 그보다 몇 microtask 뒤에 남는다.
  다음 대기자가 기록 전에 깨어난다.
- 진행 중 probe의 결과를 공유(single-flight). 호출자마다 signal이
  달라 참조 수를 세야 한다.
- slot 해제를 통과 기록 뒤로 미룬다. 해제 지점이 원시 probe 정착과
  wrapper 종료 두 곳으로 갈라진다.

위험·한계:
- 대기 뒤 재사용할 때 만료를 따로 다시 보지 않는다. 통과를 기록한
  호출이 기록 직전에 만료를 봤고, 대기자는 같은 task 안에서 이어서
  실행된다. 시작할 때의 만료 검사(기존)는 그대로다.
- 앞선 probe가 실패하면 기다리던 호출들이 각자 probe한다(slot 수로
  묶임). 실패가 반복되는 이미지는 지금과 같은 수의 probe가 돈다.
- probe 블록을 try/finally로 감싸면서 들여쓰기가 바뀌었다. 로직
  변경은 `git show -w`로 보면 짧다.
- file-transfer 레시피 번들이 55,725 → 55,856 gzip bytes가 되어 예산
  55,800을 넘었다. 다음 백 단위로 올리는 기존 규칙대로 55,900으로
  올렸다.

검증:
- RED(수정 전 코드에 새 테스트): "probes once and lets the other calls
  reuse the pass"가 "expected vi.fn() to be called 1 times, but got 5
  times"로 실패. 재확인 안(버린 대안)에서는 2회 기대에 3회로 실패.
  나머지 새 테스트 2건(앞선 probe 실패 시 대기자가 직접 probe, 대기
  중 abort가 진행 중 probe를 끊지 않음)은 새 분기를 고정한다.
- GREEN: image-cdn 단위 3파일 37건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·json-schema
  단위 20파일 323건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint
  통과. check-optional-recipes(source) file-transfer 55856/55900.

Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:47 +09:00
DongHyeonka 95e4445243 fix(browser-transfer): part 발급과 PUT이 서버의 Retry-After를 기다린다 (01-01)
문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.

고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.

버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
  증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
  클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
  둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
  실패를 다시 만들어 이 값을 읽지 않는다.

위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
  Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
  쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
  retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
  차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
  타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
  55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
  (4b0e44a9)대로 55,800으로 올렸다.
- 포트 반환 타입이 넓어졌으므로 CHANGELOG [계약] 한 줄이 필요하다.
  이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다.

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 4건 실패.
  발급·PUT이 `429 Retry-After: 5`일 때 "expected 0 to be greater than
  or equal to 5000"(첫 sleep 0ms). maxRetryAfterMs 1000을 넘을 때
  재시도해서 ok:true. resumable-upload-http-control-plane.test.ts 새
  1건 실패: 브리지 결과에 retryAfterMs 5000이 없다.
- GREEN: 두 파일 33건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·
  upload-cancellation·json-schema 단위 21파일 322건 통과. tsc app·
  test·node·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
  (exec 전용 shim, pnpm 미사용) 통과, check-adapter-inventory 통과,
  check-optional-recipes(source) PASS file-transfer 55725/55800.

Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:47 +09:00
DongHyeonka 48a4074e3a fix(bootstrap): 시작할 런타임이 없는 선택 capability를 조립 때 거절한다 (09-07)
문제: 선택 파일은 "Adding an entry here is what installs a capability"라고
적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다.
realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지
않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그
선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다.

고른 방법:
- `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime,
  webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아
  throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지
  않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다.
- 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는
  composition에 런타임을 먼저 연결해야 한다"로 고쳤다.

버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은
여전히 아무 신호도 받지 못한다.

위험·한계:
- 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야
  한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다.
- health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만,
  런타임을 연결할 때 쓸 자리라 남겼다.
- 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다.
- 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B).

검증:
- RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별
  하나)이 "expected [Function] to throw an error"로 실패.
- GREEN: 같은 파일 9건 통과.
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{component,platform,
  architecture,features,contract} 570건 통과. 그중
  app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고,
  heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka abf3ce521d fix(contracts): REST 보안 프로필 오류가 operation·프로필·깨진 조건을 말한다 (16-03)
문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱
조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다.
참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로
레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서
rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다.

고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와
함께 한 오류로 던진다. 예: "REST security profiles are incoherent for
CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER."
operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부
두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를
넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는
테스트·로그 검색은 계속 맞는다.

버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상
깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시
봐야 한다.

위험·한계:
- 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을
  별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리
  기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와
  사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은
  사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그
  작업에 남는다.
- 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가
  초기 청크에 있어 오류 문장이 그대로 실린다.

검증:
- RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가
  "expected [Function] to throw error matching /incoherent.*
  CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are
  incoherent.'"로 실패.
- GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우).
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{contract,features,
  runtime-schema,component,architecture,platform} 626건 통과. tsc app·test
  통과. 바꾼 파일 eslint 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka de48db25d9 fix(router): context·feature 경계와 라우트 모듈 실패를 진단에 남긴다 (09-09)
문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는
`onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는
buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중
throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이
없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의
route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자
신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다.

고른 방법:
- `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에
  넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존
  ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작).
- incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두
  경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다).
- gateway가 두 경계에 `reportRenderFailure` 호출과
  `<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는
  `component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에
  context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다.
- 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를
  탄다. route id는 URL의 등록 라우트, 없으면 context id다.

버린 대안:
- 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계
  두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시
  (`data-boundary`, testid)가 바뀐다.
- gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기:
  두 경계가 같은 id를 공유해 사건 구분이 흐려진다.
- `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과
  레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다.

위험·한계:
- `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로
  buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식
  (useRouteError + 마운트 시 보고)이 필요해 남겼다.
- 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다
  한 번 보고한다.
- 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의
  지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다.
- 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B).

검증:
- RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context
  경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이
  모두 `Unable to find an element with the text: /^지원 참조:
  build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다.
- GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한
  incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
  95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
  1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.
  check-architecture(shim), check-adapter-inventory, check-diagnostics,
  check-registries 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka 7139c7c61e fix(apps): 소유 context 루트가 닿지 않는 기능 라우트를 조립 때 막는다 (09-06)
문제: 라우터는 context마다 gateway 하나를 그 루트 경로에 붙이고 기능
라우트를 그 안에서만 렌더한다. 레지스트리와 탐색 메뉴는 경로와 상관없이
모든 기능 라우트를 싣는다. 그래서 루트 `shop/*` context의 `/catalog`
라우트는 메뉴 링크로 나오고 그 URL은 NOT_FOUND가 된다. 같은 루트를 쓰는
context가 둘이면 id가 늦은 쪽 전체가 닿지 않는다. 어떤 게이트도 경로와
루트를 비교하지 않았다.

고른 방법: `defineDeployableAppModule`이 context별 기능 계약 라우트를
React Router `matchRoutes`로 전체 context 루트에 맞춰 보고, 그 라우트를
받는 context가 소유 context가 아니면 라우트 id·경로·기능 id·context
id·루트를 담아 throw한다. 앱 모듈은 부트 정적 그래프에서 평가되므로
부트 실패 화면과 라우터를 거치는 모든 테스트에서 드러난다. 라우터와 같은
매칭 규칙을 쓰므로 루트 밖 경로, `/`, 루트 없는 context, 같은 루트, 더
구체적인 다른 루트에 먹히는 경로를 한 검사로 잡는다. 중첩 루트 자체는
허용한다(`tests/component/context-route-gateway.test.tsx`가 쓰는 모양).
starter-experience.md 기능 추가 4단계에 규칙을 적었다.

버린 대안:
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다.
- `defineBoundedContextModule`에서 검사: 다른 context의 루트를 모른다.
  같은 루트·중첩 루트를 앱 단위에서 따로 또 봐야 해서 검사가 두 곳이 된다.
- 루트 문자열 접두어 비교: `:param`·splat 규칙을 다시 구현하게 된다.

위험·한계:
- 리뷰 09-06의 (3) "context 라우트 핸들의 route id가 레지스트리에 있는가"는
  넣지 않았다. 핸들은 `context-routes.ts`를 읽어야 보이는데 이 파일은 늦게
  읽어야 한다. 헬퍼 제공과 적재 시 검사 중 고르는 설계 선택이라 남긴다.
  그 실패의 진단 누락은 09-09에서 다룬다.
- 플랫폼 라우트와 기능 라우트의 경로 충돌은 검사하지 않는다.
- 초기 JS +239 B gzip(202,509 → 202,748 B, 여유 2,291 → 2,052 B).
  같은 worktree에서 `vite build` 두 번으로 쟀다.

검증:
- RED: tests/architecture/context-route-roots.test.ts 7건 중 거절 5건이
  "expected [Function] to throw an error"로 실패(수정 전, 298201f 기준).
- GREEN: 같은 파일 7건 통과.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
  94 files / 588 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
  1,929 tests 통과. tsc app·test·node 통과. 바꾼 파일 eslint 통과.
  check-architecture.ts(pnpm exec를 node_modules/.bin으로 넘기는 shim)
  통과.
2026-11-01 22:56:29 +09:00
DongHyeonka 96a4f68016 test(service-worker): SW 픽스처가 현재 선택과 무관하게 워커를 켠다 (0929/06-04)
문제: SW e2e 도우미(prepareServiceWorkerBuilds)는 사본의
`const SERVICE_WORKER: InstalledServiceWorkerSelection | null = null;`
줄을 글자 그대로 찾아 ACTIVE로 바꿨다. 이미 SW를 켠 제품 트리에는 이
줄이 없어서 beforeAll이 throw하고 update·recovery spec이 모두 멈춘다.
이 spec이 실제로 필요한 곳이 바로 SW를 켠 제품이다. setup이 실패하면
spec이 root를 받지 못해 /tmp/ca-sw-builds-* 사본도 남았다.
service-worker-build-output.test.ts도 같은 치환을 했다.

고른 방법: selectActiveServiceWorker(root)를 도우미에 두고, SERVICE_WORKER
선언 전체를 값과 무관하게(정규식, 정확히 1개) ACTIVE_SELECTION으로
바꾼다. 두 픽스처가 이 함수를 쓴다. recovery spec이 ACTIVE_SELECTION을
다시 찾는 방식은 그대로 동작한다. setup 실패 때는 fixture-builds.ts처럼
사본을 지우고 다시 throw한다.

버린 대안: 리뷰가 함께 적은 "install spec 기대값을 dist/assets 전체 대신
생성된 service-worker-assets.ts 목록과 비교". ACTIVE 트리에서도 두 값이
같아 이번 결함과 무관하다. 제품이 사전 캐시 대상을 바꿀 때(0929/06-03)
다시 본다.

위험·한계:
- 선택 선언의 값에 `;`가 들어가면 정규식이 짧게 끊겨 "정확히 1개"
  검사나 이후 타입 검사에서 실패한다(조용히 틀리지는 않는다).
- e2e는 chromium만 돌렸다. webkit·firefox는 미실행.

검증:
- RED: 작업 트리 선택을 ACTIVE로 바꾸고 SW e2e 2 spec(chromium,
  webServer 없는 임시 설정)을 돌림 -> `Expected exactly one "const
  SERVICE_WORKER: ... = null;"`로 2 failed, 4 did not run, 사본 2개
  잔류.
- GREEN: 같은 ACTIVE 트리에서 6 passed. 선택을 null로 되돌린 템플릿
  트리에서도 6 passed. 잔류 사본 0.
- 새 단위 테스트(null·ACTIVE·REMOVE_REGISTRATION 선택 -> ACTIVE) 포함
  `node scripts/run-vitest.ts run
  tests/unit/service-worker-build-output.test.ts` -> 5 passed(ACTIVE
  트리와 null 트리 모두).
- `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 파일 2개> --max-warnings=0` -> 통과.

Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-04, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
2026-11-01 22:49:38 +09:00
DongHyeonka 85d55e0cd3 fix(service-worker): 사전 캐시와 설정 URL이 router base path를 따른다 (0929/06-02)
문제: SW 자산 생성기(scripts/generate-service-worker-assets.ts)가 사전
캐시 URL을 `/${relative}`로 만들어 VITE_ROUTER_BASE_PATH를 무시했다.
워커는 root-relative URL을 scope 기준으로 풀지만 base가 사라지므로
/app/ 배포에서 install이 /assets/...를 요청해 404를 받고, 워커가
설치되지 않았다. 같은 빌드의 SW 설정도 runtime config URL 기본값을
"/config.json"으로 고정해, 페이지가 쓰는 /app/config.json을 워커가
network-only로 알아보지 못했다. 앱 빌드·runtime config·06-08
fallback은 이미 base를 따르는데 이 두 곳만 빠져 있었다.

고른 방법: 리뷰가 적은 최소 방향. collectStaticAssets에 basePath
인자(기본 "/")를 더하고, 생성기 main과 SW Vite 설정이 페이지와 같은
getBuildConfig(src/contracts/env.ts)로 base와 runtime config URL을
계산한다. 결과 URL은 그대로 root-relative라 isCanonicalStaticAssetUrl
검사를 통과한다. base가 "/"이면 manifest와 digest가 전과 같다.

버린 대안: 워커가 manifest URL을 scope 상대로 풀게 바꾸기. 계약 차이는
없지만 워커 코드와 manifest 계약(root-relative)을 함께 바꿔야 해서
생성기 수정보다 크다.

위험·한계:
- base마다 manifest digest가 달라진다(의도된 결과).
- VITE_RUNTIME_CONFIG_URL이 빈 문자열이면 이제 base 기본값을 쓴다.
  페이지(getBuildConfig)와 같은 규칙이다.
- 리뷰 완료 기준의 "e2e 도우미를 base 옵션으로 돌린 첫 설치가
  RELOAD_TO_ENABLE"은 하지 않았다. e2e 도우미에 base 옵션과 /app/
  서빙이 필요하고, 실제 브라우저 install은 이번에 확인하지 않았다.

검증:
- RED: collectStaticAssets 단위 테스트(basePath "/app/")가 수정 전
  `/assets/index-abcdefgh.js`를 받아 실패(1 failed | 9 passed).
  service-worker-build-output.test.ts의 새 테스트(SW ACTIVE·
  production·/app/ 실제 빌드)가 생성기만 되돌리면 URL 목록에서,
  SW 설정만 되돌리면 `Received: "/config.json"`으로 각각 실패.
- GREEN: 두 테스트 통과. `node scripts/run-vitest.ts run
  tests/unit/service-worker tests/unit/sub-path-deployment.test.ts
  tests/unit/hosting-probe.test.ts tests/unit/web-push` -> 12파일
  171건 통과(빌드 테스트는 flock 안에서).
- `npx tsc` node·test·app·service-worker -> 오류 0.
- `npx eslint <바꾼 파일 4개> --max-warnings=0` -> 통과.
- `node scripts/check-adapter-inventory.ts` -> PASS.
- 미실행: SW e2e(Playwright).

Refs: docs/reviews/2026-09-29-maturity-review/06-adapters-service-worker-push.md 06-02, docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 2.1절
2026-11-01 22:49:38 +09:00
DongHyeonka c67edd2557 fix(web-push): 정상 알림 클릭이 router base path 아래 경로를 연다 (06-01)
문제: Web Push 정상 클릭은 registry path를 origin 기준으로 풀었다
(`new URL(path, origin)`). 거절된 클릭은 이미 앱 루트(=
registration.scope = router base path)를 쓴다(06-09). 그래서
VITE_ROUTER_BASE_PATH=/app/ 배포에서 열린 창이 없으면 정상 클릭이
https://host/inbox, 즉 앱 밖을 열었다. registry에 /app/inbox를 넣으면
openWindow는 맞지만 같은 값이 handoff path로 페이지에 가서 router
basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수
없었다.

고른 방법: registry path를 "base path를 뺀 앱 기준 경로"로 정하고,
클릭 어댑터가 앱 루트의 pathname(끝 / 제외)을 앞에 붙여 openWindow
대상을 만든다. handoff path는 registry 값 그대로 둔다. same-origin·
userinfo·hash 검사(safeTarget)는 그대로 거친다. 규칙은
WebPushNotificationDefinition.path 주석, appRootUrl 주석, 설계 8.5절에
적었다. 앱 루트가 origin 루트(기본값)면 결과가 전과 같다.

버린 대안: 리뷰가 적은 `new URL(path.slice(1), appRootUrl)`. 앱 루트가
/로 끝나지 않으면(`https://host/app`) 마지막 segment가 사라지고,
`/a:b` 같은 경로는 `a:b`가 scheme으로 읽혀 거절된다. pathname을 앞에
붙이면 두 경우 모두 의도대로 된다.

위험·한계:
- realtime 레시피 번들(web-push 포함) 40,879 -> 40,897 / 40,900 gzip
  B(+18 B, 여유 3 B). 예산은 그대로다. 다음 realtime·web-push 변경은
  예산 인상과 함께 와야 한다.
- 페이지가 handoff path를 basename 기준으로 쓰는지는 제품 코드 몫이라
  확인하지 않았다(템플릿에는 handoff 소비자가 없다).
- 실제 브라우저·푸시 서비스에서는 실행하지 않았다.

검증:
- RED: 새 테스트 "opens an accepted click's route under the base
  path"가 수정 전 openWindow 인자 `https://app.example.test/inbox`
  (기대 `https://app.example.test/app/inbox`)로 실패(1 failed | 19
  passed).
- GREEN: 같은 테스트가 통과하고, 열린 창에는 handoff path `/inbox`가
  간다. `node scripts/run-vitest.ts run tests/unit/web-push
  tests/unit/sub-path-deployment.test.ts
  tests/unit/service-worker-web-push-remediation.test.ts` -> 8파일
  82건 통과(web-push-worker-runtime 20건 포함).
- `npx tsc` app·test·service-worker -> 오류 0.
- `npx eslint <바꾼 ts 3개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
  `node scripts/check-optional-recipes.ts` -> PASS(realtime
  40897/40900), `node scripts/verify-documentation-readiness.ts` ->
  PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-01
2026-11-01 22:49:38 +09:00
DongHyeonka 3fe28dec2e fix(realtime): 배럴에서 결과 생성 함수를 내보내고 동결 규칙을 적는다 (04-01)
문제: reconnect coordinator, live/poll handoff, SSE onOpen·onEvent,
WS onSubscribed·onEvent는 받은 RealtimeResult를 2단계로 동결된
객체만 받는다. 타입은 Readonly일 뿐이라 같은 모양의 평범한 객체도
컴파일된다. 그런데 동결된 결과를 만드는 realtimeSuccess /
realtimeFailure는 result.ts에만 있고 배럴에 없다. 조합 코드는 배럴만
import할 수 있으므로 결과를 손으로 만들게 되고, 그러면 첫 실패나 첫
종료에서 PROTOCOL_MISMATCH·MAPPING_CONTRACT_VIOLATION으로 재시도
없이 끝난다. 이 규칙은 주석에도 없었고, reconnect 경계의 동결 검사
3곳을 지워도(MU4) 테스트가 모두 통과했다.

고른 방법: 리뷰 6.2절의 (b). 배럴 src/adapters/realtime/index.ts에서
두 함수를 export하고(추가만, 기존 시그니처 변화 없음), 엄격한 경계의
타입 주석(RealtimeReconnectOutcome, RealtimeReconnectSession,
confirmTransportBarrier, handoff apply·establishAuthoritativeCheckpoint,
SSE onOpen·onEvent, WS onEvent·onSubscribed)과 생성 함수 주석에 규칙을
적었다. 동결 규칙 자체와 DEFAULT_RETRYABLE 기본값은 그대로다.

버린 대안:
- (c) 엄격한 경계도 stream coordinator처럼 한 번 복사하기. 규칙이
  하나가 되지만 "검증한 실패 객체를 그대로 돌려준다"(toBe) 계약을
  깬다.
- (d) 생성 함수를 application port(shared.ts)에 두기. feature 코드도
  쓸 수 있게 되지만 application 계층에 런타임 헬퍼가 는다. handoff
  apply를 feature가 구현한다고 정해지면 그때 옮긴다.
- 런타임 오류 이름을 따로 두기(예: RESULT_NOT_FROZEN). failure kind
  어휘가 바뀌는 계약 변경이라 이번 범위 밖이다.

위험·한계:
- 동결하지 않은 결과는 여전히 컴파일된다. 타입으로 막으려면 brand가
  필요하고, 그건 공개 타입을 깨는 변경이다. 주석과 테스트로만 알린다.
- realtime 레시피 번들 40,863 -> 40,879 / 40,900 gzip B(+16 B, 여유
  21 B). 예산은 그대로다.

검증:
- RED: 새 테스트 "retries a failure built with the barrel's
  realtimeFailure"가 수정 전 `TypeError: realtimeFailure is not a
  function`으로 실패(1 failed | 43 passed).
- 새 테스트 4건(시도의 평범한 실패, 동결된 실패 안의 평범한 error,
  classifyClosed의 평범한 성공 -> PROTOCOL_MISMATCH, 재시도 없음)과
  handoff apply의 평범한 성공 -> MAPPING_CONTRACT_VIOLATION 1건.
- MU4(reconnect 동결 검사 3곳 제거)를 다시 넣으면 새 테스트 3건이
  실패한다(수정 전에는 생존).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/` ->
  14파일 230건 통과.
- `npx tsc --project tsconfig.app.json --noEmit`,
  `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 파일 8개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
  `node scripts/check-adapter-inventory.ts` -> PASS,
  `node scripts/check-optional-recipes.ts` -> PASS(realtime 40879/40900).

Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-01, 6.2절
2026-11-01 22:49:38 +09:00
DongHyeonka e0c2a91d47 test(setup): npx vitest가 npm scope 환경변수 없이 시작한다 (1101/15-05)
문제
`npx vitest run tests/unit/ci-workflow-generation.test.ts`는 79건이
"CI runner npm scope environment invalid"로 실패한다(415건 중). npx와
npm을 거친 IDE 실행기는 npm_config_prefix·_userconfig·_globalconfig를
넣는다. CI 게이트 preflight(withCiGatePreflight)는 실제 runner에서 이
변수들을 거절하는데(옳은 동작), 테스트가 그 preflight를 프로세스 안에서
부르거나 자식으로 띄우면서 실행기의 process.env를 그대로 물려받는다.
scripts/run-vitest.ts만 그중 일부를 지워서 pnpm 경로만 통과한다. 원인은
timeout이 아니라 이 환경변수다.

고른 방법
- vitest.config.ts가 NODE_ENV를 고정하는 자리에서 npm scope 변수를 지운다.
  config는 worker를 띄우기 전에 메인 프로세스에서 평가되므로 worker와 그
  자식 프로세스 모두 깨끗한 환경으로 시작한다. 어느 실행기로 돌리든,
  어느 테스트 파일이든 한 곳에서 막는다.
- 지울 이름은 preflight가 쓰는 것과 같은 판정
  (package-script-graph.ts의 isNpmScopeEnvironmentName, 기존 private 함수를
  export)으로 고른다. 목록이 둘로 갈라지지 않는다.
- ci-workflow-generation.test.ts에 "테스트 프로세스에 npm scope 변수가
  없다"는 테스트를 더했다.

버린 대안
- 해당 테스트 파일의 beforeEach/afterEach에서 지우고 되돌리기(리뷰의 최소
  방향 1): 같은 preflight를 띄우는 다른 파일이 생기면 다시 깨진다.
- 실행 함수가 환경을 인자로 받게 하기: 자식 프로세스는 여전히 process.env를
  물려받아 실패한다.
- run-vitest.ts의 하드코딩 목록 정리: 이번 수정으로 필요 없어지지만, product
  index 생성 자식에도 쓰이고 동작이 같아 건드리지 않았다.

위험·한계
- 실제 게이트 실행기의 npm scope 거절은 그대로다. 테스트 안에서 일부러 변수를
  넣는 기존 테스트 3건도 그대로 통과한다.
- tests/unit 밖(component, integration 등)은 npx로 돌려 보지 않았다.

검증
- RED: npx vitest run tests/unit/ci-workflow-generation.test.ts -t
  "npm-launched runner" 실패 "expected [ 'npm_config_userconfig', …(2) ] to
  deeply equal []". 수정 전 같은 파일 79 failed / 336 passed
- GREEN: npx vitest run tests/unit/ci-workflow-generation.test.ts
  416 passed
- npx vitest run tests/unit: 171파일 2,401 passed
- tsc(node, test), eslint 바뀐 파일 통과

Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-05
2026-11-01 22:49:13 +09:00
DongHyeonka f13ed7bea7 fix(docs): verify:documentation이 실패한 검사와 고칠 파일을 적는다 (1101/14-06)
문제
verify-documentation-readiness.ts는 실패 원인과 상관없이 마지막에
"FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"를
적는다. stderr에 따로 적는 것은 README 빌드 변수 누락뿐이다. 기능을
더해 route가 늘었는데 README나 접근성 체크리스트에 route ID를 안 적으면,
개발자는 diagram 리뷰 기록을 먼저 의심하고 산출물 JSON을 열어야 원인을
안다.

고른 방법
- 검사 네 개(route scope, runtime variables, review report digest,
  diagram reviews)의 실패를 failedChecks로 모으고 passed는 그것이 비었는지로
  정한다. 판정 조건은 그대로다.
- 실패하면 검사마다 고칠 곳을 stderr에 적는다. route scope는 문서별로
  빠진 route ID, diagram review는 어느 diagram이 증거 문서에 PASS로 없는지.
- 마지막 줄은 "FAIL_UNVERIFIED (failed: <검사 이름들>)"이다. 판정 토큰은
  그대로 둬서 이 줄을 읽는 쪽이 바뀌지 않는다.

버린 대안
- route ID 누락만 따로 적기(리뷰의 최소 방향): 다음에 다른 검사가 실패해도
  같은 엉뚱한 문구가 나온다. 검사 네 개 모두 같은 방식으로 적어도 몇 줄이다.

위험·한계
- diagram review 실패는 어느 하위 조건(경로·digest·점수)인지까지는 적지
  않는다. 산출물 JSON의 results에 그대로 있다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/documentation-readiness.test.ts
  2 failed. README에서 `EXAMPLES_PLATFORM`을 지운 사본에서 stderr가
  "Documentation readiness: FAIL_UNVERIF…"뿐이라 "README.md does not name
  route IDs: EXAMPLES_PLATFORM"이 없다. 두 검사 실패 때도 실패 이름이 없다
- GREEN: 같은 파일 3 passed(원본 사본 PASS, route 하나 누락,
  route+변수 누락)
- 실제 repo에서 verify-documentation-readiness PASS_SCOPED
- eslint, tsc(node, test), check-ci-contract PASS

Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-06
2026-11-01 22:49:13 +09:00
DongHyeonka 003832b694 docs(changelog): 리뷰 발견 ID에 라운드를 붙인다 (1101/14-02)
문제
리뷰 라운드마다 발견 ID를 `NN-MM`으로 새로 매긴다. CHANGELOG의
`(14-02)`는 0925 라운드의 "CI 계약 고정"인데, 0929 라운드의 14-02는
"README 업데이트 절차"이고 이번 라운드에도 14-02가 있다. CHANGELOG는
복사한 프로젝트가 변경 근거를 찾는 유일한 링크라 ID가 어느 라운드인지
모르면 다른 결함을 읽게 된다. 리뷰 가이드에 ID 네임스페이스 규칙이 없다.

고른 방법
- CHANGELOG 0.2.0 절의 ID 98개에 `0925/`를 붙였다(`F-N`은 0925
  FOLLOW-UP의 ID라 같이 붙였다). 기계적 치환이다: 괄호 안의
  `NN-MM`·`F-N`만, 범위(`01-01~01-11`)는 앞에만, 날짜는 건드리지 않는다.
  0.1.0 절의 `R-x.y`는 다른 체계라 그대로 둔다.
- CHANGELOG 머리말에 `MMDD/NN-MM` 규칙과 F-N의 뜻을 적었다.
- 리뷰 가이드 36.3 "ID·제목"에 같은 규칙을 넣었다. 라운드 안에서는
  `NN-MM`, 밖에서 가리킬 때는 `MMDD/NN-MM`. 기존 코드 주석 약 339곳은
  고치지 않고 새로 쓰는 것부터 붙인다(리뷰의 최소 개선 방향 ③).
- tests/unit/changelog-review-ids.test.ts가 CHANGELOG 괄호 안의 라운드
  없는 ID를 막는다. 리뷰가 적은 grep 검증을 test:unit 게이트로 옮긴 것이다.

버린 대안
- CHANGELOG 표에 라운드 열 추가: "그 밖의 수정" 목록에는 표가 없어 규칙이
  둘이 된다. ID 자체에 붙이는 쪽이 코드 주석·커밋 제목과 같은 형식이다.
- 접두어를 `YYYYMMDD/`로: 이미 브랜치의 커밋과 리뷰 README가
  `0929/03-01` 형식을 쓴다. 해가 바뀌어 월일이 겹치면 그때 연도를 붙인다.

위험·한계
- 기존 주석과 0.2.0 커밋 제목은 라운드 없는 ID로 남는다(혼재 기간).
- 테스트는 괄호 안 쉼표 구분 토큰만 본다. 괄호 밖 본문에 쓴 ID는 잡지
  않는다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts
  실패 "expected [ '03-03', '03-01', '08-03', …(95) ] to deeply equal []"
- GREEN: 같은 테스트 통과. 리뷰의 검증 명령
  `grep -cE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md` → 0
- eslint, tsc(test), verify-documentation-readiness PASS_SCOPED,
  check-ci-contract PASS(새 테스트 파일이 test:unit 게이트에 들어감)

Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-02
2026-11-01 22:49:13 +09:00
DongHyeonka b3af26fc0e fix(release): 배포된 config.json 사본을 바꾸기 전에 검사한다 (1101/13-05)
문제
.env.example과 운영 문서는 runtime config를 재빌드 없이 바꿀 수 있다고
적는다(SERVICE_WORKER DISABLED, FEATURE_OVERRIDES). 그런데 고친 문서를
검사할 명령이 없다. check:release-admission은 dist/config.json만 읽고,
build:profile은 BUILD_ID를 덮어 다시 만든다. 브라우저는 부팅 때 문서를
스키마로 검사하고 BUILD_ID를 HTML과 맞춰 보므로, 오타 하나나 BUILD_ID
변경 하나가 모든 사용자의 BOOT_CONFIG_FAILURE가 된다. FE-RB-001은 세
줄이고 고치는 방법이 없다.

고른 방법
- check-release-admission.ts가 `--config <고친 사본> --original <배포된
  원본>`을 받는다. 사본에 기존 검사(스키마, 대상 규칙)를 그대로 돌리고,
  원본과 비교해 CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 밖의 필드가 하나라도
  바뀌면 거절한다. BUILD_ID·RELEASE_ID 유지는 이 규칙에 들어 있다.
  `--original` 없이 `--config`만 주면 거절한다(비교 대상 없이 통과시키지
  않는다).
- 사본 검사는 artifacts/release/deployment-admission.json을 쓰지 않는다.
  그 파일은 빌드의 승인 증거(CI artifact)이고 운영자의 사본은 빌드가 아니다.
- FE-RB-001에 네 단계(사본 두 개 받기·고치기 → 검사 → 같은 파일시스템에서
  rename으로 교체, 되돌리기도 같은 방법 → 깨끗한 세션 부팅 확인)를 적고,
  release-cache-rollback.md와 browser-file-storage-recovery.md의 스위치
  설명이 그 절차를 가리킨다. .env.example 문장을 "비상 스위치만 재빌드
  없이 바꾼다"로 좁혔다.
- pnpm이 `--`를 넘겨도 되도록 맨 앞 `--`를 버린다.

버린 대안
- `--build-id <id>`로 BUILD_ID만 대조: API_BASE_URL·RELEASE_MANIFEST_URL처럼
  빌드가 정한 다른 필드를 바꿔도 통과한다. 원본 전체 비교가 같은 비용으로
  더 좁다.
- release-manifest.json에서 build id를 읽기: 운영자가 받을 파일이 하나 더
  늘고, 여전히 BUILD_ID만 본다.
- 비상 스위치도 빌드로만 바꾸기: 장애 대응 시간이 빌드·승격 시간만큼 늘어
  스위치의 목적이 사라진다(리뷰 대안 비교).

위험·한계
- 원본과 사본의 중첩 객체 비교는 JSON.stringify라 키 순서만 달라도
  "바뀜"으로 거절한다(닫힌 쪽으로 실패).
- 실제 서버에서 사본을 바꿔 부팅해 보지 않았다. 바뀐 문서가 release
  기록(checksums.txt, 승격 archive)과 달라지는 점은 런북에 적기만 했다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
  새 6건 실패. 모두 "release admission refused: dist/config.json is
  unreadable"(--config를 무시하고 dist를 읽음)
- GREEN: 같은 파일 22 passed. 스위치만 바꾼 사본 ADMITTED·기록 없음,
  SERVICE_WORKER "DISABLE" 오타·BUILD_ID/RELEASE_ID/API_BASE_URL 변경·
  --original 누락은 exit 1
- runbook-contract, runbook-drill, feature-override-diagnostics 포함 35 passed
- 실제 local 빌드에서 인자 없는 기존 경로 ADMITTED(기록 작성),
  `-- --config dist/config.json --original public/config.json` ADMITTED
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
  PASS_SCOPED

Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-05
2026-11-01 22:49:13 +09:00
DongHyeonka 629c8f045e fix(hosting): 호스팅 검사가 SPA fallback과 SW 스크립트 헤더를 본다 (1101/13-04)
문제
라우터는 browser history를 쓴다. 호스트가 앱 경로에 index.html을 주지
않으면 `/`는 열리고 새로고침·북마크·공유 링크만 404가 된다. 호스팅 계약
(config/hosting/cache-policy.json)에 앱 경로 표면이 없고, live probe는
`/`, config, manifest, entry script만 요청해서 FE-GATE-019가 그대로
PASS한다. 운영 문서가 no-cache로 서빙하라는 service-worker.js도 선언과
검사에 없다. e2e는 fallback을 기본으로 하는 vite preview라 드러나지 않는다.

고른 방법
- cache-policy.json에 표면 두 개를 더한다.
  - appRoute: 빌드에 파일이 없는 경로 `/__probe/deep-link`. index와 같은
    Cache-Control, content-type, 보안 헤더를 요구한다.
  - serviceWorker: `/service-worker.js`, no-cache, JS MIME.
    `requiredWhen: "service-worker-shipped"`로 워커를 싣는 빌드
    (ACTIVE, REMOVE_REGISTRATION)에서만 요구한다. 이 판정은
    checkPublicServiceWorkers와 같은 함수(shipsServiceWorker)를 쓴다.
- live probe를 scripts/lib/hosting-probe.ts의 probeLiveRelease로 옮겨
  fetcher를 주입해 단위 테스트한다. 요청 경로는 정책의 path에서 읽는다.
  appRoute는 200이어야 하고, 응답이 index.html과 같은 entry script를
  가리켜야 한다. 그래서 404와, 200으로 답하는 다른 페이지(soft 404)를
  모두 FAIL로 잡는다.
- release-cache-rollback.md에 fallback 규칙과 desktop 서버용 nginx 예시를
  적는다. 예시는 손으로 썼고, 빠진 hashed asset은 index.html이 아니라
  404여야 한다는 점(구 탭 재적재, FE-RB-002)과 add_header 상속 함정을
  적었다.

버린 대안
- createHashRouter로 바꿔 fallback 자체를 없애기: URL과 기존 경로 계약·
  테스트가 모두 바뀐다(리뷰 대안 비교에서 기각).
- 정책 이름(serviceWorker)으로 스크립트가 조건을 아는 방식: 정책 파일만
  읽는 운영자가 항상 필요한 표면으로 오해한다. 조건을 JSON에 적었다.
- 리다이렉트 뒤 최종 경로까지 비교: 이번 완료 기준(404 FAIL) 밖이라 넣지
  않았다.

위험·한계
- nginx 예시는 이 머신에 nginx가 없어 실행하지 않았다. CI도 돌리지 않는다.
  호스트가 실제로 무엇을 주는지는 live probe가 확인한다.
- 이미 배포한 호스트에 fallback이나 SW 헤더가 없으면 FE-GATE-019가 새로
  실패한다(의도).
- 앱 base path가 `/`가 아닌 배포는 기존 probe와 같이 다루지 않는다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
  5 failed. "expected undefined to match object { cacheControl:
  'no-cache', …}"(정책에 appRoute·serviceWorker 없음),
  "probeLiveRelease is not a function"
- GREEN: 같은 파일 22 passed. fallback 없는 호스트에서
  ["appRoute http-status", "appRoute entry-script"]가 실패로 나온다
- node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
  tests/platform/release tests/release tests/unit/ci-workflow-generation.test.ts:
  483 passed
- build-frontend.ts 뒤 verify-hosting-headers.ts(fixture): UNVERIFIED rc=3,
  결과 36건(appRoute 8건 포함), SW null이라 serviceWorker 헤더 검사는 건너뜀
- tsc(node, test), eslint 바뀐 파일, verify-documentation-readiness
  PASS_SCOPED, check-ci-contract PASS

Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-04
2026-11-01 22:49:13 +09:00
DongHyeonka ffb6782b0c fix(query): 무효화 topic이 닿지 않는 조회 namespace를 진단으로 알린다 (03-01)
문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.

고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
  이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
  읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
  cache.operation.failed(operation: unregistered-query-namespace) 진단을
  남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
  있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
  더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
  QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
  상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
  coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
  청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
  QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
  객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.

버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
  깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
  포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
  추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
  못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
  알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
  채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
  넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.

위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
  namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
  런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
  BoundQuery.invalidation, 상수 1개).

검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
  bound query whose namespace no registered topic reaches (03-01)" 실패.
  "expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
  89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
  넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
  tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
  12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
  provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
  다른 실행 때문)로 이 변경과 무관하다.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
  gzipSync로 쟀다. 298201f 202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적
  202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다.
- 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은
  0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts,
  presentation -> contracts뿐이다.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
DongHyeonka 4da046683f fix(http): 전송 전 거절의 원인을 진단에 남기고 연결 실수를 구분한다 (03-02)
문제
전송 전 실패가 네 곳에서 원인 없는 위반 FINAL_REQUEST_INVARIANT_FAILED
하나로 바뀐다. 입력 검증 실패, 요청 조립 실패 10종(PATH_PLACEHOLDER_MISSING
등), 최종 불변식 실패 12종, 미설치 계약이다. 바인딩은 이 위반과
MISSING_IDEMPOTENCY_KEY·UNEXPECTED_IDEMPOTENCY_KEY를 모두 VALIDATION_REJECTED로
바꿔 "서버가 입력값을 받아들이지 않았습니다"를 띄운다. 그래서 경로
placeholder 오타나 mutation 정책과 계약의 불일치 같은 개발자 연결 실수가
사용자 입력 문제처럼 보이고, 진단에는 원인이 없다. 미설치 계약은 실행기를
거치지 않아 진단이 0건이다. 또 마감이 시도별 budget 읽기와 최종 불변식
검사 사이에 끝나면 DEADLINE_EXPIRED도 같은 위반이 되어, 시간 초과가 "입력
거절"로 보인다(P-03-05).

고른 방법
- HttpContractViolation에 선택 필드 reason(닫힌 집합
  HttpRequestRejectionReason)을 더한다. 실행기의 세 거절 지점이
  refusedRequest(reason)로 위반을 만들고, finish()가 그 reason을 관측의
  diagnosticReason으로 옮긴다. projector는 03-05에서 만든 경로대로
  diagnostics에만 reason을 싣는다. telemetry는 error_kind 그대로다.
- 최종 불변식의 DEADLINE_EXPIRED는 budget 읽기 분기와 똑같이
  TRANSPORT_FAILURE/TIMEOUT으로 끝낸다(P-03-05).
- 바인딩은 사용자가 입력을 바꿔 고칠 수 있는 거절(INPUT_INVALID,
  PATH_VALUE_INVALID, QUERY_TOO_LARGE, URL_TOO_LARGE, REQUEST_BODY_TOO_LARGE)과
  reason 없는 거절만 VALIDATION_REJECTED로 둔다. 나머지 reason과 멱등 키
  위반은 UNKNOWN_CLIENT_FAILURE(문의 행동, "요청을 처리할 수 없습니다.")로
  낸다. V2 client가 미등록 operation을 같은 종류로 내는 것과 맞췄다.
- 미설치 계약 분기는 같은 projector로 관측 1건(reason
  CONTRACT_NOT_INSTALLED)을 직접 남긴다.

버린 대안
- 새 FailureKind 추가: 오류 레지스트리·i18n 카탈로그·화면 분기를 다 바꿔야
  한다. 이미 있는 UNKNOWN_CLIENT_FAILURE가 "클라이언트 결함, 문의"라는 같은
  뜻이고 V2에서 같은 상황에 쓰고 있다.
- 리뷰 예시대로 MAPPING_CONTRACT_VIOLATION으로 내기: 문구가 "서버 응답을 화면
  데이터로 바꾸지 못했습니다"라 응답이 없는 전송 전 실패와 맞지 않는다.
- 사용자 입력 쪽을 reason별 Record로 망라하기: 컴파일 시 분류를 강제하지만
  20여 줄이 는다. 새 reason은 기본으로 클라이언트 결함이 되는 쪽이 안전하므로
  입력 쪽 5개만 Set으로 적었다.
- terminalReason에 원인을 싣기(리뷰 문구): 03-05와 같은 이유로 버렸다.

위험·한계
- 동작 변경: 멱등 키 위반과 연결 실수가 VALIDATION_REJECTED에서
  UNKNOWN_CLIENT_FAILURE로 바뀐다. 폼은 필드 오류 대신 "unavailable" 상태
  안내를 띄운다. 기존 계약 테스트의 기대값을 이에 맞게 바꿨다.
- 입력 검증 실패(INPUT_INVALID)는 리뷰 문구("입력 크기 초과만")와 달리
  VALIDATION_REJECTED로 남겼다. 입력 validator의 거절은 사용자 입력 문제다.
- reason 없는 FINAL_REQUEST_INVARIANT_FAILED(다른 실행기 구현)는 기존대로
  VALIDATION_REJECTED다.
- AppFailure.code는 지금처럼 위반 종류다. 원인 코드는 진단에만 있다.
- 공개 타입은 추가만 했다(위반 선택 필드 1개, 진단 reason 집합 확장).
- validator가 throw하는 경우(VALIDATOR_RUNTIME_FAILURE → SCHEMA_MISMATCH,
  "서버 응답 데이터가…" 문구)는 이번 범위가 아니라 그대로다.
- 미설치 계약 거절도 다른 CONTRACT_VIOLATION처럼 api.request.failed
  telemetry 1건을 낸다(VD-07 규칙 5).
- 화면: 정상 상태는 그대로이고 위 실패에서만 문구가 바뀐다. 시각 골든은
  다시 찍지 않았다.

검증
- RED(수정 전):
  - http-execution-v3-observability "names a refused request's assembly
    cause in diagnostics only (03-02)": violation.reason 없음.
  - 같은 파일 "ends a deadline that expires at the final invariant check as
    a timeout (P-03-05)": TRANSPORT_FAILURE 기대, 실제 CONTRACT_VIOLATION.
  - feature-http-binding 계약 테스트 5건: PATH_PLACEHOLDER_MISSING,
    CONTRACT_NOT_INSTALLED, HEADER_NOT_ALLOWED, MISSING_IDEMPOTENCY_KEY,
    UNEXPECTED_IDEMPOTENCY_KEY가 VALIDATION_REJECTED로 나옴.
  - runtime-adapters-auth-profile "is refused without a fetch and leaves one
    diagnostic naming the cause": reason 없음, 진단 0건.
- GREEN: 세 파일 38/38 통과.
- 회귀: run-vitest tests/unit tests/integration tests/component
  tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
  13개 제외) 227 files 중 226 통과, 2354/2355. 실패 1건은
  provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
  다른 실행 때문)로 HTTP와 무관하다. 제외했던 http-scenario-evidence는
  pnpm을 띄우지 않아 따로 돌렸고 14/14 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 스크립트 필요), 번들 크기 측정.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
DongHyeonka f8a492a6ad fix(http): 문제 응답 분류기 실패를 진단 reason으로 남긴다 (03-05)
문제
기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면
classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를
돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract
runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를
버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고
답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을
NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다.

고른 방법
- HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은
  닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다.
  문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고,
  finish()가 관측 기록에 싣는다.
- 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다
  (reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다.
- 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지
  않았다.

버린 대안
- 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기:
  terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제
  응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단
  조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중
  차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌
  타입 필드가 의도가 더 잘 보인다.
- 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이
  분류기 결함 때문인지 구분할 수단이 계속 없다.

위험·한계
- classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만
  내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서
  뺐다.
- 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개).
- VD-07 5-1에 reason 전달 규칙을 적었다.

검증
- RED(수정 전): tests/integration/http-execution-v3-observability.test.ts
  "keeps MAYBE_APPLIED and records a failed problem classifier in
  diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제
  undefined.
- GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면
  이 테스트가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/integration tests/features/reference-feature
  tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 스크립트 필요).

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
DongHyeonka 5e6be9a92f fix(registry): breaking 증거를 그 증거가 설명하는 값에 묶는다 (0929/07-01)
문제
breaking 증거 조회 키는 registryId:row:field:kind뿐이고, 증거 검사는
5필드가 비었는지만 본다. 값은 diff에 있지만 증거와 비교하지 않는다. 그래서
한 번 증거를 쓴 row·field는 다음 변경도 새 증거 없이 통과한다. 실험 X3:
REFERENCE_RESOURCE_DETAIL.path를 08-13 증거가 설명하는
/examples/reference-resources/items/:resourceId가 아닌
.../entries/:resourceId로 바꿔도 check-registries가 "11 registries
PASS"였다. 공개 URL·API 경로·저장 키 같은 breaking 변경이 이행·롤백
계획 없이 지나간다.

고른 방법 (리뷰 최소 개선 (1))
- 값이 있는 breaking 변경(change.after가 있음)은 증거 행에 after가 있어야
  하고, canonical JSON이 diff의 after와 같아야 한다. 없으면 "evidence
  needs after", 다르면 "evidence explains after=..., the change is
  after=..."로 실패한다. 키 순서·원시값 배열 순서는 기존 canonical 규칙
  그대로라 차이로 보지 않는다.
- 삭제(row·registry·field 삭제)는 설명할 값이 없어 after를 요구하지 않는다.
- 현재 diff와 맞는 템플릿 증거 1건(REFERENCE_RESOURCE_DETAIL.path)에
  after를 더했다. ci-quality-gates.md의 증거 안내에 after를 적었다.
- 완전한 증거를 만드는 테스트 두 곳(registry-compatibility,
  registry-governance tamper 사례)에 after를 넣었다.

버린 대안
- after를 선택 필드로 두기: 없는 행은 지금처럼 모든 다음 변경을 통과시켜
  X3이 그대로 남는다.
- 증거 키에 값 해시를 넣기(changeId 형식 변경): 기존 changeId 문법과
  출력이 바뀌고 사람이 읽을 수 없다.
- 리뷰 (2) 현재 diff와 맞지 않는 증거 행 실패 또는 목록 출력, (3)
  update:registry-baseline의 증거 정리: 실패로 할지 출력으로 할지, 오래된
  14건을 지울지 이력 파일로 옮길지가 감사 기록을 다루는 결정이라 이번에
  하지 않았다.

위험·한계
- 증거 파일 형식이 바뀐다. 다운스트림이 이 검사를 동기화하면 아직 diff에
  남은 breaking 변경의 증거 행마다 after를 넣어야 게이트가 통과한다.
  다음 릴리스 CHANGELOG [계약] 행이 필요하다(미출시 절이 없어 적지
  않았다).
- 오래된 증거 행(현재 diff와 무관한 14건, 0929/07-02 수정으로 쓰이지 않게
  된 VITE_BUILD_ID 포함)은 그대로 남는다. 위 (2)·(3)이 남은 일이다.
- 값이 큰 contract 필드(allowedValues 전체 등)의 증거는 그 값을 통째로
  적어야 한다.

검증
- RED(수정 전): registry-compatibility.test.ts 새 사례 2건 실패
  ("rejects evidence written for another value", "requires the explained
  value": expected [] to deeply equal [...]). X3 변이로 check-registries
  "11 registries PASS".
- GREEN: 같은 X3 변이에서 check-registries 실패("evidence explains
  after=\"/examples/reference-resources/items/:resourceId\", the change is
  after=\"/examples/reference-resources/entries/:resourceId\""), 변이 없이
  "11 registries PASS". registry-compatibility·registry-governance·
  release-artifacts·second-api-feature-registries 53/53 통과.
  compatibility fixtures 11 PASS. verify-documentation-readiness
  PASS_SCOPED.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm), test:sample-removal(pnpm).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka 82c9e594ff fix(registry): 선언된 null 전환과 허용값 추가를 breaking으로 막지 않는다 (0929/07-02)
문제
레지스트리 호환성 분류기(scripts/lib/registry-compatibility.ts)는 값의 JS
타입이 다르면 breakingFields를 보기 전에 field-type-changed(breaking)로
판정한다. null과 문자열은 타입이 달라서, governance가 string|null로
선언하고 breaking 필드에서 뺀 필드(navigationLabel, navigationOrder, API
timeoutMs, 저장 ttl, ENV defaultValue)를 null <-> 값으로 바꾸기만 해도
breaking 증거를 요구한다. contract의 allowedValues에 값을 더하는 것도
어떤 변경이든 breaking이다. 그래서 증거 5필드에 쓸 내용이 없는 변경에
"마이그레이션·롤백"을 지어 쓰게 된다. 템플릿 자신도 VITE_BUILD_ID
defaultValue null -> "local-build"에 "the value itself did not change"라고
적은 breaking 증거를 남겼다.

고른 방법 (리뷰 최소 개선 B)
- 행 필드: 한쪽이 null이고 두 값이 모두 그 필드의 선언 타입
  (contract.fieldTypes, 예 string|null)에 맞으면 타입 변경이 아니라
  field-changed로 보고 breakingFields로 등급을 정한다. 선언이 없거나
  선언 밖 값이면 지금처럼 field-type-changed(breaking)다.
- contract allowedValues: 필드 집합이 같고 필드마다 이전 허용값을 모두
  포함하면 allowed-values-extended(additive)다. 값 하나라도 빠지거나,
  새 필드를 제한하거나, 제한을 없애면 지금처럼 breaking이다. 나머지
  contract 변경도 그대로 breaking이다.
- 선언 타입 판정은 check-registries.ts에 있던 runtimeType·
  matchesDeclaredType을 lib로 옮겨 검사기와 분류기가 같은 함수를 쓴다.
- semantic-diff.json fixture에 nullable-field-cleared(behavior-change),
  registry-contract-extension(additive)을 더하고 artifact id 목록에도
  넣었다.

버린 대안
- 현 상태 + "이런 변경은 재승인하라"는 문서: 재승인이 증거를 대신하는
  길을 더 넓힌다(0929/07-04).
- nullable 필드 판단 전체를 breakingFields로 옮기기(리뷰 C): 다른
  레지스트리 영향을 다시 봐야 하는 넓은 변경이다.
- 제한 해제(allowedValues에서 필드 키 삭제)를 additive로 보기: 리뷰
  기준("이전 값을 모두 포함")에 맞지 않고 판단이 하나 더 필요해 보수적으로
  breaking에 남겼다.

위험·한계
- fail-closed 범위가 줄어든다. 선언 타입 안의 null 전환이 의미("기능
  꺼짐")를 갖는 필드는 breakingFields에 넣어야 breaking으로 남는다.
  paramsSchema·searchSchema는 이미 breakingFields라 그대로 breaking이다.
- 현재 기준선 diff에서 VITE_BUILD_ID defaultValue가 breaking에서
  behavior-change로 바뀐다. registry-change-evidence.json의 해당 증거 행
  (field-type-changed)은 이제 어떤 변경과도 맞지 않는다. 오래된 증거 정리는
  0929/07-01 범위라 이번에는 지우지 않았다.
- 다운스트림의 같은 종류 증거 행도 쓰이지 않게 된다. 게이트 판정이
  바뀌는 변경이라 다음 릴리스 CHANGELOG에 [계약] 행이 필요하다(이번
  라운드는 CHANGELOG 미출시 절이 없어 적지 않았다).
- fieldTypes 키가 점 경로(a.b)인 필드는 행의 최상위 필드 이름과 맞지 않아
  계속 breaking으로 남는다.

검증
- RED(분류기 수정 전): registry-compatibility.test.ts 새 사례 5건 실패
  (null 전환 3건이 breaking/field-type-changed, nullable breaking 필드의
  kind, allowlist 확장 breaking). check-registry-compatibility-fixtures:
  nullable-field-cleared actual breaking, registry-contract-extension
  actual breaking.
- GREEN: registry-compatibility·registry-governance·release-artifacts·
  second-api-feature-registries 49/49 통과. compatibility fixtures 11 PASS.
  check-registries "11 registries PASS"(남은 breaking은
  REFERENCE_RESOURCE_DETAIL.path 하나, 증거 있음).
  ci-artifact-contract "semantic validator" 사례 통과.
- 회귀: tsc node/test rc=0, 바꾼 파일 eslint rc=0.
- 미실행: check:architecture(pnpm). tests/system 나머지(provider guardian
  exit=126 환경 문제로 이 변경과 무관하게 실패).

Refs: docs/reviews/2026-09-29-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka fc303d89bc refactor(contracts): 폐기 별칭 import를 새 이름으로 옮기고 lint로 막는다 (07-01)
문제
MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의
MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고
부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는
{ ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름
MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을
요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper,
참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거
조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수
없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다.
eslint 설정에 폐기 검사가 없다.

고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로)
- boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry,
  mappingSuccess, mappingFailure와 바인딩 mapSuccess가
  BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도
  옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서
  런타임과 공개 시그니처는 바뀌지 않는다.
- D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은
  BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가
  필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는
  같은 type의 alias" 문장도 고쳤다.
- 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어
  @typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core
  no-restricted-imports의 patterns.importNames로 boundary-mapper의
  MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다.
  층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로
  restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은
  그 앞에 둔 공통 블록이 받는다.

버린 대안
- 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2)
  후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상
  공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0,
  lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다.
- typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint
  설정(속도·설정 범위)이 필요하다.
- 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유
  문자열로 넓어져 계약이 약해진다.

위험·한계
- 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭).
  리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야
  충족된다. 제거 시점은 릴리스 결정으로 남긴다.
- 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint
  오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데,
  반환 타입은 같은 모양이라 영향 없음).
- adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다.
  같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다.

검증
- RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors
  ("'MappingResult' import from '../../contracts/boundary-mapper.ts' is
  restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure
  같은 꼴).
- GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일)
  --max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep).
- 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit
  tests/features tests/platform tests/component tests/contract
  tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외)
  273 files / 3136 tests 중 3135 통과. 실패 1건은
  provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이
  변경과 무관한 scripts/lib 프로세스 테스트).
  check-registries PASS, verify-documentation-readiness PASS_SCOPED,
  check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로
  사실상 미검증.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +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 3c31576940 test(contracts): V2 행과 V3 descriptor를 양방향과 스키마 id까지 맞춰 본다 (07-02)
문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.

고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
  V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
  commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
  요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
  (V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
  응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
  대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
  정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
  게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.

버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
  V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
  변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
  defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
  생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
  이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
  비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
  fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
  parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.

위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
  않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
  주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
  zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
  파일을 돌려야 걸린다.

검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
  L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
  ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
  ("responseSchema": "ReferenceResourcePayload" vs "...V2").
  L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
  "cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
  함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).

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
DongHyeonka 68e88b081d fix(opfs): 객체를 못 지운 purge가 완료와 chunk sweep을 보고하지 않는다 (0929/05-02)
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.

고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.

버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
  그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
  번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.

위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
  예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
  페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
  지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
  방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
  확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.

검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
  as unfinished"가 `- "moreObjectsAvailable": true`
  `+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
  chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
  chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
  indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
  recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
  check-optional-recipes PASS.

Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka 49f7cde50e fix(platform): lifecycle 리스너 주인 규칙을 실제에 맞추고 테스트를 둔다 (05-03)
문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한
주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus·
pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다.
optional-runtime-host.ts도 같은 말을 한다. 실제로는
- telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다
  (telemetry-collector.ts onPageExit).
- 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를
  단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외).
- lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는
  없다.
또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache
복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가
살아남았다.

고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에
구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다.
tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation,
visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt,
dispose 뒤 0개를 확인한다.

버린 대안:
- (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을
  만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야
  해 이번 범위를 넘는다.
- (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에
  비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다.

위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다).
src 동작은 바뀌지 않는다.

검증:
- RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide,
  browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인.
- RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를
  모두 잡는다. K3(generation += 1 제거) → "expected {...} to match
  object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) →
  "expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0",
  dirty 검사 제거 → preventDefault "to not be called".
- 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters
  3파일 30/30 통과. tsc app·test 통과, eslint 통과,
  check-adapter-inventory PASS.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka 12c23feba9 fix(storage): 저장소 진단 이벤트에 실패 원인을 싣는다 (05-02)
문제: Web Storage 어댑터의 실패 원인은 QUOTA_EXCEEDED,
SIZE_LIMIT_EXCEEDED, UNAVAILABLE, VALUE_REJECTED 넷이다. 진단 이벤트
storage.operation.failed는 error_kind에 quota면 STORAGE_QUOTA_EXCEEDED,
나머지는 모두 STORAGE_UNAVAILABLE을 넣고 원인을 버린다. 그래서 운영자는
"브라우저 저장소를 못 쓴다"와 "저장된 값이 깨져서 버렸다"를 같은
이벤트로 본다. 호출자에게 주는 실패 code에는 원인이 이미 들어 있다.

고른 방법: recordStorageFailure의 context에 reason: cause를 더한다.
reason은 진단 계약의 허용 칸(taxonomy)이고 원인 값은 어댑터의 닫힌
유니온이라 cardinality가 늘지 않는다. projectDiagnosticRecord에 넣어
칸이 그대로 남는 것을 확인했다.

버린 대안: error_kind를 원인별로 나누는 것. error_kind는 createFailure의
error kind taxonomy와 맞춰져 있어, 값을 늘리면 그 taxonomy를 바꿔야
한다. 이미 있는 reason 칸에 싣는 쪽이 추가만으로 끝난다.

위험·한계: 진단 이벤트에 칸이 하나 는다(추가만). 수집기가 reason을
바깥으로 내보내는지는 영역 03 소관이라 보지 않았다.

검증:
- RED: storage-registry의 quota, discard 3종(malformed, invalid
  envelope, oversized), oversize write 테스트 5개가 실패.
  예: "expected vi.fn() to be called with arguments" 차이
  `- "reason": "VALUE_REJECTED"`.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, runtime-adapters, diagnostics,
  release-mismatch-recovery 4파일 68/68 통과. tsc app·test 통과,
  eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka e98a980dff fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.

고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).

버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
  newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.

위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.

검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
  "expected { ok: true, value: undefined } to match object { ok: false }"
  로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
  to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
  contract-registry-lookup, browser-security, runtime-adapters,
  release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
  eslint 통과, check-registries PASS, verify-documentation-readiness
  PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka 98b9682241 chore(scripts): 쓰지 않는 npm script 4개를 지우고 scan:도 게이트 검사한다 (12-05)
문제
package.json에 어디서도 부르지 않는 script 4개가 있다.
- scan:security:fixture: FE-GATE-013은 이것 대신 check:security:fixtures를
  돈다. supply-chain.test.ts는 "게이트에 없어야 한다"고 단언하는데 script는
  남아 있다. 게이트 밖 script 검사는 check|verify|test|drill|review만 봐서
  scan:을 놓쳤다.
- build:profile: 이름과 달리 generate-runtime-config.ts만 돈다.
- generate:contract-set: 참조 0건.
- build:app-only: vite build와 매니페스트만 만든다. build-frontend.ts의
  계약 세트·런타임 설정·Service Worker 단계가 빠진 dist가 나온다. 참조는
  product-index-entrypoints 테스트의 진입점 목록 하나다.
참조 확인(새 기준 298201f, docs/reviews 제외): package.json 정의와 위 두
테스트 말고는 config/ci/gates.json, 생성 workflow, scripts, docs 어디에도
없다. 아래 세 script가 부르던 파일(generate-runtime-config.ts,
generate-contract-set.ts, generate-build-manifest.ts)은 build-frontend.ts가
그대로 부른다.

고른 방법
- 네 script를 지우고 진입점 목록에서 build:app-only를 뺀다.
- VERIFICATION_SCRIPT에 scan을 더한다. 게이트가 닿지 않는 scan:* script는
  ungated-scripts.json 항목 없이는 check:ci에서 실패한다. 지금 남은
  scan:security는 build:release-candidate를 거쳐 게이트가 닿는다.
- docs/operations/ci-quality-gates.md의 접두어 목록에 scan:*을 더한다.
버린 대안
- build:app-only를 build:vite-only로 이름만 바꾸기: 남길 사용처를 찾지
  못했다.
- 접두어 대신 "게이트 밖 모든 script는 예외 목록에": dev·storybook·
  update:*까지 목록에 올라가 목록이 커진다(리뷰 대안 비교와 같다).
- check:feature-index 정리(리뷰 개선 (4)): 지우기와 이유 문구 고치기 중
  하나를 고르는 일이라 이번에 하지 않았다.

위험·한계
- 개인 습관으로 이 script를 쓰던 사람은 build-frontend.ts나 node
  scripts/...를 직접 불러야 한다.
- 게이트 명령은 바뀌지 않아 CI 계약 기준선은 그대로다.

검증
- RED: 새 테스트 "rejects a scan script that no gate reaches"가 실패
  (expected [ …(2) ] to deep equally contain '…: scan:orphan'). 정규식만
  넓히면 저장소 검사 "reaches every verification script …"가
  scan:security:fixture 한 건으로 실패.
- GREEN: ungated-scripts·product-index-entrypoints·supply-chain·
  ci-workflow-generation 4파일 457/457 통과. check:ci의 세 단계를 pnpm
  없이 직접 실행: generate-artifact-schemas --check PASS,
  check-ci-contract.ts PASS(27 gates), generate-ci-workflow --check PASS.
  tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-05
2026-11-01 22:16:26 +09:00
DongHyeonka e714c0d770 fix(design-system): 디자인 검사가 deg 색상각과 시스템 글꼴 이름을 받는다 (12-04)
문제
디자인 규칙이 올바른 CSS를 거부한다. 포커스 대비 규칙의 parseOklch는
색상각 단위 deg와 음수 색상각을 읽지 못해 oklch(52% 0.15 230deg)를 실패로
센다(B13). 첫 글꼴 규칙은 -apple-system, BlinkMacSystemFont로 시작하는
시스템 글꼴 스택을 실패로 센다(B6). color-mix()·알파 표면(B10, B11)은
"--color-focus or X is not a plain oklch() value"로 실패해서 어느 토큰이
무슨 값인지, 무엇이면 되는지 알 수 없다. 네 규칙의 설명은 코드 주석에만
있다.

고른 방법
- parseOklch가 색상각에 deg와 음수를 받는다. 알파는 계속 받지 않는다.
- oklch-contrast.ts에 resolveValue(var() 사슬 끝 값)를 두고 resolveColor가
  그것을 쓴다. 포커스 규칙은 계산할 수 없는 토큰마다 "<테마> <토큰> is
  <값>; contrast needs an opaque oklch(L C H), hue in degrees with or
  without deg"를 낸다. 포커스 색 자체를 못 읽으면 표면 8개 대신 한 줄이다.
- 첫 글꼴 허용 목록에 -apple-system, BlinkMacSystemFont를 더한다.
- docs/styling/design-system-platform.md 4.1절에 규칙 4개, 지원 형식,
  검사 위치를 표 하나로 적는다.
버린 대안
- color-mix()·알파 표면을 배경 위에 섞어 계산: 무엇이 아래에 그려지는지
  규칙이 모른다. 추측하지 않고 실패하는 기존 원칙을 유지하고 메시지로
  해결 형식을 알린다(리뷰 대안 비교와 같다).
- 리뷰 개선 (4) token-contract.ts에 "제품이 싣는 글꼴" 목록: 공개 계약에
  새 이름을 넣는 설계 선택이고 완료 기준에 없다. 문서 표에 "아직 선언할
  곳이 없어 실패한다"로 적었다.
- rad·grad·turn 단위: 쓰는 곳이 없다. 넣지 않은 단위는 메시지가 알려 준다.

위험·한계
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은 이 테스트 파일뿐이다.
- 패키지·<link>로 싣는 글꼴, 12-03의 검사 위치 밖 CSS는 그대로다.
- 화면 변화 없음. CSS를 바꾸지 않았다.

검증
- RED(수정 전): design-system-rules·oklch-contrast 테스트 19개 중 4개
  실패. "reads a hue written with deg" expected [ …(8) ] to deeply equal [],
  "names the value it cannot compute …" 메시지 불일치, "-apple-system"
  expected [ Array(1) ] to deeply equal [], parseOklch("…230deg") expected
  null.
- GREEN: 같은 두 파일과 design-system-contract 21/21 통과. 실제 스크립트
  probe: 포커스를 oklch(52% 0.15 230deg)로 → PASS(B13). surface-muted를
  oklch(0.97 0 0 / 0.9)로 → "light --color-surface-muted is oklch(0.97 0 0
  / 0.9); contrast needs …"로 실패(B11). 저장소 CSS는 PASS.
- tsc(tsconfig.node, tsconfig.test), 바꾼 파일 eslint, verify-
  documentation-readiness PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
2026-11-01 22:16:26 +09:00
DongHyeonka c0451f9ad6 test(design-system): 검사 스크립트가 규칙 4개를 모두 부르는지 확인한다 (12-02)
문제
49d8675는 디자인 규칙 4개를 순수 함수로 옮기고 함수마다 단위 테스트를
붙였다. 규칙 함수의 판정을 깨면 규칙마다 테스트가 실패한다(이번에 다시
확인: 대비 < 0, 혼합 정규식 무력화, 토큰·글꼴 판정 무조건 통과 → 11개 중
7개 실패). 그러나 scripts/check-design-system.ts가 그 함수를 부르는
부분은 아무것도 지키지 않는다. 스크립트에서 규칙 호출을 지우고 포커스
색을 옛 값 oklch(0.72 0.16 225), 첫 글꼴을 Inter로 되돌려도
check-design-system은 PASS, 관련 단위 테스트 17개도 통과했다. 리뷰가
적은 "규칙을 모두 꺼도 모든 게이트가 통과한다"가 이 경로로 남아 있었다.

고른 방법
- 기존 규칙 테스트 파일에 테스트 하나를 더한다. 토큰 CSS와 styles/**를
  임시 폴더에 복사하고 규칙마다 위반 하나를 넣는다(옛 포커스 색, Inter
  첫 글꼴, var(--drawer-width) 제거, in oklch 혼합 probe.css). 그 폴더를
  cwd로 실제 스크립트를 돌리고, 산출물 JSON의 failures에 네 규칙의
  메시지가 모두 있고 다른 실패는 없는지 본다.
- 스크립트·게이트·산출물 스키마는 바꾸지 않는다. 스크립트가 이미 cwd
  기준 경로만 읽어서 임시 폴더로 충분하다. ci-workflow-generation 테스트가
  check-ci-contract.ts를 같은 방식으로 돌린다.
버린 대안
- 리뷰가 제안한 --root 인자와 tests/fixtures/design-system/forbidden-css:
  49d8675가 이미 버렸다. cwd 복사가 스크립트 변경 없이 같은 것을 증명한다.
- --fixture 모드가 CSS fixture도 읽게 하기: gates.json 기대값과 CI 계약
  기준선을 함께 바꿔야 한다.

위험·한계
- 실제 CSS 문자열(--color-focus 정의, --font-sans, var(--drawer-width))을
  찾아 바꾼다. 찾지 못하면 어느 문자열인지 적고 실패한다(조용히 통과하지
  않는다).
- 성공 메시지와 산출물이 어떤 규칙이 돌았는지 적지 않는 점(12-02 근거의
  산출물 부분)은 스키마 변경이라 그대로 둔다.
- 테스트 하나가 node 프로세스를 띄운다(약 0.2초).

검증
- RED: 스크립트에서 hueMixFailures 호출과 규칙 4개 failures.push를
  지우면 새 테스트가 "expected +0 to be 1"로 실패. firstFontFamilyFailures
  한 줄만 지워도 '--font-sans starts with "Inter"' 메시지가 없어 실패.
- GREEN: tests/unit/design-system-rules.test.ts 12/12, oklch-contrast·
  design-system-contract 포함 18/18 통과. node scripts/check-design-system.ts
  PASS. tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-02
2026-11-01 22:16:26 +09:00
DongHyeonka 3c175a5429 fix(provider): guardian이 실패하면 stdin을 기다리지 않고 끝난다 (G-1)
문제
guardian은 fd 0을 fs.createReadStream으로 읽는다. 이 스트림은 libuv
스레드 풀의 스레드 하나를 read(2)에 세워 둔다. process.exit()는 종료
전에 스레드 풀을 join하므로, 그 read가 돌아올 때까지(부모가 stdin을
닫을 때까지) 끝나지 않는다. 그래서 가드를 거부하거나 link가 실패하면
failClosed가 진단을 바로 쓰고도 프로세스는 남는다. 클라이언트는 stdin을
연 채 READY를 기다리므로 거부가 즉시 오지 않고 고정 5초 뒤 "READY timed
out"으로 끝난다. 같은 종류 guardian 두 개 테스트의 패자가 이 경로다.
탐침: 같은 종료 코드를 fs 스트림은 stdin을 닫은 2,008ms에, net 소켓은
228ms에 냈다(200ms 뒤 exit 호출).

고른 방법
- liveness 입력을 process.stdin으로 바꾼다. pipe면 Node가 이벤트 루프로
  읽는 net.Socket을 만든다. 스레드 풀 read가 없어 exit가 바로 끝난다.
  data/end/error 처리, removeAllListeners·destroy, closeSync(0)는 그대로다
  (libuv는 fd 0~2를 destroy에서 닫지 않는다).
- 동시 guardian 테스트에 붙였던 PROCESS_HEAVY_TIMEOUT_MS와 그 주석을
  뺀다. 패자가 link 실패 즉시 끝나 테스트가 5.14초에서 0.16~0.54초가 됐다.
버린 대안
- provider-scope-wrapper.ts처럼 new Socket({ fd: 0 }): fd 0이 pipe가
  아니면 생성자가 throw한다. guardian은 그 시점에 이미 private alias를
  묶었고 failClosed는 liveness가 있어야 돈다. process.stdin은 pipe에서는
  같은 Socket이고, 그 밖의 fd에서는 throw 대신 end/error로 기존 실패
  경로(125)를 탄다.
- 실패 때 SIGKILL로 자신을 죽이기: 종료 코드 124~126 계약이 사라진다.

위험·한계
- pipe인 fd 0에 O_NONBLOCK이 걸린다. 읽기 끝은 guardian만 가진다
  (클라이언트는 stdio "pipe"로 띄운다).
- lease 마감 경로는 원래 SIGKILL을 쓰므로 바뀌지 않는다.

검증
- RED(수정 전): 새 테스트 "exits on a rejected guard while the parent
  still holds its input open"이 "rejected-guard guardian exit timed out"
  (5,122ms)으로 실패. 다른 nonce의 가드를 보내 시계와 무관하게 거부시킨다.
- GREEN: tests/integration/provider-guardian-transaction.test.ts 22/22
  통과, 3회 반복 통과(새 테스트 65~333ms). tests/unit/task3-selective-
  integration 7/7. tsc(tsconfig.node, tsconfig.test) 통과, 바꾼 파일
  eslint 통과.
- 미실행: tests/system/ci-runner/ci-artifact-contract.test.ts의 provider
  체인 테스트. fixture가 corepack pnpm으로 빌드해서 이 worktree에서는
  돌리지 않았다.

Refs: commit c862004 위험·한계의 "따로 남는 결함"
2026-11-01 22:16:26 +09:00
DongHyeonka 298201f3ee perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.

고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
  계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
  contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
  계약, adapter contribution, contract contribution)는 feature-runtime.ts로
  옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
  route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
  모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
  화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
  모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
  적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
  registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
  (installed-contract-contributions.ts). 선언하지 않은 contract package를
  적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
  installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
  registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
  둔다. src에서 후자를 import하면 새 아키텍처 규칙
  boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
  route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
  청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
  기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
  플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
  템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
  feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
  render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
  애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).

버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
  lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
  버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
  공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
  -60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
  i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
  초기로 세어 218,303 B가 됐다.

위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
  실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
  그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
  테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
  구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
  재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
  비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
  총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
  installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
  때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
  98.8%다.

수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B

검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
  equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
  tests/integration tests/contract tests/runtime-schema tests/architecture
  tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
  109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
  boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
  check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
  55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
  pnpm 경로의 check:bundle, test:system

BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
  loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
  (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
  만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
  codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
  16-structure-patterns.md 9절
2026-11-01 21:57:53 +09:00
DongHyeonka f41e3d5e32 ci(gates): 번들 예산 검사를 merge 단계에서 돌린다 (15-01)
FE-GATE-012(build, check-bundle, check-app-build-input-bundle,
check-optional-recipes)는 release 단계에만 있어 tag push나 수동 release
실행에서만 돈다. 초기 JS를 예산보다 크게 만드는 PR도 merge 게이트를
통과하고, 몇 PR 뒤 release가 실패한다. 어느 PR이 얼마나 늘렸는지는 그때
이력을 거꾸로 따라가 찾아야 한다.

FE-GATE-012를 merge stage와 merge_gate job으로 옮긴다. release_gate는
merge_gate를 needs로 두므로 tag 실행에서도 그대로 돈다. promotion 공식
(MERGE_READY)과 CI 계약 검사의 job 소유 표를 같이 바꾸고, workflow는
생성기(node scripts/generate-ci-workflow.ts)로 다시 만든다.

버린 대안:
- check-bundle만 FE-GATE-011(build)에 붙인다(리뷰의 최소안). 같은 검사가
  두 게이트에 갈라지고, release에 남은 FE-GATE-012와 중복해서 돈다.
- FE-GATE-012를 merge와 release 둘 다에 둔다. 계약이 게이트당 job 하나를
  강제한다(multiply owned gate).
- lab 게이트(FE-GATE-026)도 merge로 옮긴다. PR마다 브라우저 설치와 5회
  측정이 붙고, 부하에 따라 판정이 뒤집힌 기록(0929/11-04)이 있다. release에
  남긴다.

위험·한계:
- merge 실행이 build 1회와 공급망 생성, 번들 계산만큼 길어진다.
- 실제 CI 러너에서는 돌려 보지 않았다(Actions 꺼짐).

검증:
- node scripts/check-ci-contract.ts: 27 gates PASS
- node scripts/generate-ci-workflow.ts --check: PASS
- node scripts/generate-artifact-schemas.ts --check: PASS
- node scripts/run-vitest.ts run tests/unit/ci-workflow-generation.test.ts
  tests/unit/promotion-readiness.test.ts: 423 통과(workflow 스냅샷 1건 갱신)

Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01
2026-11-01 21:57:53 +09:00
DongHyeonka c03bf020c9 test(setup): Testing Library 대기 기한을 전역 한 곳에서 정한다 (0929/10-01)
문제
lazy route 화면을 findBy*·waitFor 기본값(1초)으로 기다리는 테스트가 1코어
부하에서 코드와 무관하게 떨어진다. 수정 전 재현에서
runtime-application.test.tsx:65 "Unable to find role=heading name=Clean
Architecture Frontend"와 reference-production-vertical.test.tsx:103
"Unable to find role=button name=로그인 시작"이 났다. 두 DOM 모두
route-loading(aria-busy) 상태였다. 지난 리뷰는 router.test.tsx:244-250도
같은 이유로 실패했다고 적었다. React 19는 Suspense를 풀 때마다 실제 300ms
타이머(FALLBACK_THROTTLE_MS)를 기다린다. context route 표와 lazy 페이지를
거치는 화면은 렌더링 전에 1초 중 600ms를 쓴다. 이 사정을 아는 파일만
호출마다 { timeout: 5000 }을 붙이거나(7개 파일 13곳) 파일 단위로
configure를 바꿨다(reference-page). 새 테스트 작성자는 이 규칙을 알 방법이
없다.

고른 방법
tests/setup.ts에서 configure({ asyncUtilTimeout: 5_000 })를 한 번 정하고,
같은 값을 반복하던 호출·파일 단위 override를 지웠다. findBy*·waitFor는
DOM 변화가 오면 바로 끝나므로 기한은 멈춤을 알리는 용도뿐이다. 10초 테스트
제한의 절반이라 진짜 멈춤은 여전히 Testing Library의 DOM 덤프와 함께
실패한다. 기한을 늘리는 방식이라 고른 이유를 setup에 주석으로 남겼다.

버린 대안
- 가짜 시계: Testing Library는 Jest의 가짜 타이머만 알아본다
  (jestFakeTimersAreEnabled가 jest 전역을 본다). Vitest 가짜 타이머에서
  waitFor는 자기 타이머가 멈춰 끝나지 않는다. MSW와 user-event도 실제
  시계로 돈다.
- route chunk를 테스트에서 미리 import하기: chunk를 받아도 React의 300ms
  reveal 타이머와 렌더링 비용은 그대로 기한 안에 남는다. 테스트가 route
  모듈 목록을 따로 알아야 한다.
- 실패한 파일에만 timeout 붙이기: 지금 상태와 같다. 다음 lazy 화면
  테스트에서 같은 실패가 반복된다.

위험·한계
- 기다리다 실패하는 테스트는 실패까지 1초가 아니라 5초 걸린다. 부재를
  findBy·waitFor의 실패로 확인하는 테스트는 없다(grep으로 확인).
- 가짜 타이머를 쓰는 테스트의 waitFor는 이 값과 무관하다(가짜 시간).

검증
- RED(수정 전, taskset -c 0 + 같은 코어의 바쁜 이웃 1개, --maxWorkers=4,
  component·features·integration·platform/cardinality): 3회 중 1회 위 두
  테스트 실패.
- GREEN(같은 조건): 대상 6개 파일 6회, 넓은 묶음 5회 모두 통과. 바쁜
  이웃 2개로 3회 돌렸을 때도 이 커밋이 다루는 테스트는 모두 통과했다.
  넓은 묶음 한 번의 시간은 RED 91~111s(실패가 몰린 209s 회차 제외)
  -> GREEN 86~88s다.
- 기본 코어: tests/unit·component·integration 212파일 2,734개, features·
  platform·architecture·contract·runtime-schema 60파일 403개 통과.
  tsc -p tsconfig.test.json, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
2026-11-01 21:23:10 +09:00
DongHyeonka 582630062b test(scale): 극한 규모 테스트가 CPU와 무관한 비교만 단언한다 (0929/10-01)
문제
extreme-scale-registry.test.ts는 머지 게이트(FE-GATE-005 coverage, pr
scale tier)에서 돈다. 그런데 절대 시간 예산(100만 조회 1,500ms, 100k
조합·멤버십 3,000ms)을 단언한다. 1코어에서는 코드와 무관하게 떨어진다
(수정 전 9회 중 5회, 1,509~1,826ms). run-scale-profile.ts와
ungated-tests.json은 pr tier를 "CPU와 무관하다"고 설명하는데 이 파일만
어긋났다. 같은 이유로 진짜 회귀를 잡는지도 기계 속도에 달려 있었다.

고른 방법
- 조합: 이미 있던 10k -> 100k 증가 비율(30 미만)만 남긴다.
- 조회: 같은 100k 키로 만든 일반 객체 조회와 비교해 3배 미만인지 본다.
  조회 횟수는 1,000,000 -> 200,000(양쪽 합 400,000).
- 멤버십: 10k와 100k 선택·해석 비용을 repo의 assertLinearOrBetter(지수
  1.5 이하)로 본다.
- 측정: 비교하는 두 쪽을 번갈아 재고, 10k 쪽은 10번 반복해 일의 양을
  맞추고, 각자 가장 빠른 회차를 쓴다. 공유 코어에서 10ms 측정은 한
  scheduler slice 안에 끝나고 100ms 측정은 다른 프로세스 뒤에서 기다려
  성장이 실제보다 가팔라 보인다(일의 양을 맞추기 전 조합 비율 61 관측).
  가장 빠른 회차는 check:scale:baseline이 성장을 minMs로 읽는 것과 같다.
절대 시간은 기준 CPU에서만 비교하는 check:scale:baseline 몫으로 둔다.

버린 대안
- 예산을 올리기: 더 느린 러너에서 같은 문제가 다시 생긴다.
- 절대 예산을 nightly 전용 파일로 떼기: tier 설정·ungated 목록·문서를
  함께 고쳐야 하고, 머지 게이트 쪽에는 결국 이번 비교가 필요하다.
- 조회를 10k/100k 성장으로 보기: 감싸기(proxy)처럼 크기와 무관한 느려짐을
  못 잡는다. 선형 탐색은 어느 쪽이든 시간 초과로 드러난다.

위험·한계
- 비교도 실제 시계로 잰다. 바쁜 이웃 3개를 둔 1코어에서 관측한 최댓값은
  조합 비율 17(한도 30), 조회 비율 1.04(한도 3), 멤버십 지수 1.21(한도
  1.5)이다. 여유는 한도의 약 1.2~3배다.
- 크기와 무관한 작은 상수 배 느려짐(get trap이 있는 proxy 정도)은 조회
  비교가 잡지 못한다. 수정 전 절대 예산도 이 기계에서 잡지 못했다.

검증
- RED(수정 전, taskset -c 0): 대상 파일만 3회 중 1회, component·features·
  integration·platform/cardinality 3회 중 1회, 바쁜 이웃 1개를 더하면
  3회 중 3회 "expected 1509.6… to be less than 1500"
  (extreme-scale-registry.test.ts:78).
- 변이(기본 코어): 조합에 100번째마다 Object.keys -> "expected 145.5 to be
  less than 30". 조회에 20회 hasOwn get trap -> "expected 14.46 to be less
  than 3". 해석을 includes로 -> "super-linear growth: exponent 1.98".
- GREEN(taskset -c 0 + 같은 코어의 바쁜 이웃, --maxWorkers=4): 대상 6개
  파일 6회, component·features·integration·platform/cardinality 5회 모두
  통과. 이 파일만 바쁜 이웃 3개 옆에서 6회, coverage를 켜고 3회 통과.
- 실행 시간: 기본 코어에서 파일 1.76s -> 1.37s.
- 기본 코어: tests/features·platform·architecture·contract·runtime-schema
  60파일 403개 통과. tsc -p tsconfig.test.json, eslint 통과.

Refs: docs/reviews/2026-09-29-maturity-review/10-tests-fast-layers.md
2026-11-01 21:23:10 +09:00
DongHyeonka c8620042ea test(guardian): 가드를 guardian이 읽을 준비가 된 뒤에 보낸다 (0929/10-01)
문제
guardian 테스트는 자식을 띄우자마자 절대 마감(Date.now() + 350)이 든
가드를 보낸다. 그래서 lease가 프로세스 기동 시간까지 낸다. 1코어에서
기동이 350ms를 넘으면 guardian이 가드를 마감 지남으로 거부하고, 테스트는
5초 뒤 "deadline guardian READY timed out"으로 실패한다(수정 전 1코어
재현 9회 중 4회). 같은 구조가 2~3초 lease를 쓰는 테스트 5곳에 있다. near-timeout
테스트는 READY 뒤 1초를 고정으로 자서, 기동이 길면 publish·commit에 남는
시간이 줄어든다. 자식 기동을 기다리는 poll 세 개(waitForFile,
waitForNewDirectChild, waitForStoppedProcess)는 1초 마감을 쓴다. 파일
머리의 watchdog 설명("1초 요구를 넣지 않는다")과 어긋난다.

고른 방법
- spawnGuardian이 실제 guardian을 import하는 래퍼로 띄운다. import가
  끝나면(bootstrap과 stdin reader 등록까지 끝난 시점) 래퍼가 여분 pipe
  (fd 7)에 1바이트를 쓰고 닫는다. 새 sendGuard는 이 신호를 받은 뒤에
  마감을 계산해 가드를 보낸다. 가드를 보내는 6곳이 모두 sendGuard를 쓴다.
  guardian 코드와 프로토콜, 350ms·2s·3s lease 값은 그대로다.
- near-timeout 테스트는 startProviderGuardian 호출 직전 시각에서 1초 뒤에
  깬다. 클라이언트가 spawn 뒤에 마감을 찍으므로 마감은 그 시각 + 2초
  이후다. 기동이 길어도 publish·commit에 1초가 남는다.
- 1초 poll 세 개는 같은 파일의 watchdog(5초)을 쓴다. 자식 기동에는 기다릴
  이벤트가 없어 poll이 남는다.
- 같은 종류 guardian 두 개 테스트는 패자가 클라이언트의 고정 5초 READY
  제한(RESPONSE_TIMEOUT_MS)으로만 거부된다. 테스트가 줄일 수 없는 고정
  대기라 파일의 PROCESS_HEAVY_TIMEOUT_MS를 붙이고 이유를 주석에 적었다.

버린 대안
- lease를 늘리기: 기동 시간에 상한이 없어 같은 문제가 더 드물게 남는다.
  350ms 테스트는 만료를 기다리는 시간도 길어진다.
- marker 파일 + poll로 준비 신호: 파일 시스템 poll에 다시 마감이 필요하다.
  pipe는 이벤트로 끝나고 provider-evidence 목록 단언에 끼어들지 않는다.
- guardian 프로세스에 가짜 시계 주입: 자식 프로세스라 테스트용 훅을 운영
  스크립트에 넣어야 한다.

위험·한계
- spawnGuardian 경로의 guardian은 main 모듈이 아니라 래퍼가 import한
  모듈로 돈다. guardian은 argv·import.meta를 읽지 않는다. 래퍼는 신호를
  보낸 뒤 fd 7을 닫으므로 가드를 받는 시점의 상속 fd(0~6)는 운영과 같다.
  클라이언트 경로 테스트는 그대로 실제 스크립트를 직접 띄운다.
- 가드를 보내기 전 기동 대기는 watchdog 5초가 상한이다. 남은 실제 시계
  구간은 가드 처리(decode, link, fsync, READY)뿐이다.
- 따로 남는 결함(이 커밋 범위 밖): guardian은 가드를 거부하거나 link가
  실패하면 failClosed가 진단을 쓰지만, stdin 읽기가 걸려 있는 동안
  종료하지 않는다. 탐침: 만료된 가드를 받고 1,008ms에 진단을 쓴 뒤 stdin을
  닫은 4,014ms에야 126으로 끝났다. 그래서 클라이언트에서는 거부가 즉시
  오지 않고 5초 뒤 "READY timed out"이 된다(leaseMs 1과 동시 guardian 탐침
  5,018~5,053ms). 위 PROCESS_HEAVY_TIMEOUT_MS는 이 결함이 고쳐지면 뺄 수
  있다.

검증
- RED(수정 전, taskset -c 0, --maxWorkers=4): component·features·
  integration·platform/cardinality 3회 중 2회, 같은 묶음 + 바쁜 이웃 1개
  3회 중 2회 "expires an uncommitted lease … deadline guardian READY timed
  out"(5,035~5,052ms).
- GREEN(세 커밋을 합친 상태, taskset -c 0 + 같은 코어의 바쁜 이웃,
  --maxWorkers=4): 대상 6개 파일 6회, 위 넓은 묶음 5회(이웃 1개) 모두
  통과. 이웃 2개로 3회 돌렸을 때 이 파일은 모두 통과했다(실패 1건은
  http-execution-v3-live-authority, 0929/10-03).
- 기본 코어: tests/unit·component·integration 212파일 2,734개 통과
  (pnpm을 띄우는 security-followup-archive, fixture-node-modules,
  lab-performance 제외). tsc -p tsconfig.test.json, 바꾼 파일 eslint
  통과.

Refs: docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md
2026-11-01 21:23:10 +09:00