diff --git a/docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md b/docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md new file mode 100644 index 00000000..108f370d --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md @@ -0,0 +1,375 @@ +# 01 browser-transfer 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 깊게 본 관점: 1, 5, 6, 12, 14, 17, 28 · 이번 라운드 추가 렌즈: 업로드·다운로드의 메모리·요청 수 비용, 재시도·중단 위험의 가시성 + +ID 표기: 이번 라운드의 새 발견은 `01-01`부터 쓴다. 지난 라운드(2026-09-29)의 발견은 `0929/01-01`처럼 앞에 날짜를 붙인다. + +## 요약 + +- 지난 리뷰 기준 `af3d8e6` 뒤로 이 영역의 코드·테스트·설계 문서는 한 줄도 바뀌지 않았다. 지난 발견 5건(`0929/01-01`~`01-05`)은 모두 **남음**이다. `0929/01-01`(Medium)과 `0929/01-02`는 이번에 새 실험으로 다시 재현했다. +- **새 결함(Medium).** part 단계(BFF capability 발급, object store PUT)는 `Retry-After`를 읽지 않는다. 문서 두 곳은 읽는다고 적는다. 서버가 `429 Retry-After: 5`로 답해도 클라이언트는 250·500·1000ms 뒤 다시 보내고 1.75초 안에 요청 8개를 쓴 뒤 실패한다(01-01). +- **새 비용 발견(Low).** ① `FILE_BYTE_SOURCE`로 재개하면 이미 수락된 part까지 다시 복사하고 해시한다(01-02). ② 메모리 상한 식의 `copyFactor`는 코드의 실제 복사 수가 아니라 정책 설정값이라 1까지 낮출 수 있다(01-03). ③ 같은 이미지를 동시에 resolve하면 probe가 호출 수만큼 돈다(01-04). +- 요청 수: 새 업로드는 HTTP `2N+4`개다(기본 최대 5GiB → 2,052개). 재시도 한 번은 발급+PUT 2개다. 메모리: part 하나가 전송 중일 때 part 크기 버퍼가 최소 4개 살아 있다(기본 copyFactor 4와 같다). +- 변이 15건 중 10건을 테스트가 잡았다. 살아남은 5건 중 3건은 "중복 작업 제거"라 리팩토링 안전성의 근거다. 2건(ABORT 키, RANGE 경로 복사)은 테스트 빈틈이다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `src/adapters/browser-transfer/` 27파일(TS 26, README 1) 12,603줄: `resumable-upload/` 13, `presigned/` 6, `image-cdn/` 7, 배럴 1. 포트 `src/application/ports/browser-transfer/` 5파일 808줄. 단위 테스트 15파일 + fixture 3파일 11,230줄 | +| 커밋·작업 상태 | `d99301b`. `git diff --stat af3d8e6 d99301b -- src/ tests/ scripts/ config/ docs/architecture/`에 이 영역 파일이 없다. 바뀐 21파일은 UI 감사(디자인 시스템, 예제 화면, `oklch` 검사)뿐이다 | +| 전제 (0.1) | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. file-transfer 레시피는 `RECIPE_AVAILABLE` / `AVAILABLE_NOT_COMPOSED`라 기본 production 번들에 조립돼 있지 않다(`config/recipes/frontend-capability-recipes.json:155-198`). 공개 경계는 배럴 `src/adapters/browser-transfer/index.ts`다. 규모·운영 목표(허용 실패율, 최저 업링크 등)는 정해져 있지 않다. 기본 정책값(`runtime-policy.ts:60-81`)을 사실상의 목표로 보고 판정했다 | +| 읽은 코드 | 전부: `resumable-upload-runtime.ts`, `upload-byte-source.ts`, `runtime-policy.ts`, `presigned-upload-part-executor.ts`, 포트 `resumable-upload.ts`. 필요한 부분: `presigned-transfer-executor.ts`(PUT·download·digest), `presigned-capability-http-provider.ts`(발급 응답 처리), `presigned-capability-vault.ts`(register·replay guard), `http-common.ts`(상태표), `fetch-json-transport.ts`(상한·`Retry-After`·본문 읽기), `http-control-plane-adapter.ts`(발급 실패 전달), `indexeddb-checkpoint-store.ts`(CAS·remove), `upload-mutation-lock.ts`, `upload-response-validation.ts`, `checkpoint-schema.ts`, `image-cdn-runtime.ts`(probe slot·재사용), `browser-image-probe.ts`(fetch·decode 예산), kernel `browser-file-storage/result.ts` 예외표 | +| 읽은 문서(주장) | `docs/architecture/presigned-transfer-and-image-cdn.md` 4.2·4.3·5절·6.3·6.4, `server-file-capability-infrastructure.md` 3.5·5.3·재시도 표(1020-1040)·1658-1668, `decisions/VD-12-presigned-transfer-and-image-cdn.md:72`, `browser-file-and-origin-storage.md:330-335`, 지난 리뷰 `2026-09-29-maturity-review/01-adapters-browser-transfer.md`와 README 9.5 | +| 게이트(오케스트레이터 실행, 로그만 읽음) | `check:architecture`·`check:types`·`lint`·`test:unit`·`check:adapter-inventory` rc=0. `test:unit` 로그에서 이 영역 15파일 249건 통과 | +| 직접 실행 | 분리 worktree(`scratchpad/wt-01`, `d99301b`, 메인 `node_modules` 링크, pnpm 미사용)에서: ① 영역 단위 테스트 `node scripts/run-vitest.ts run tests/unit/resumable-upload tests/unit/presigned-transfer tests/unit/image-cdn tests/unit/upload-cancellation` → **15파일 249건 통과, 1.59초**(직전 부하 9.2) ② 실험 X1~X6(worktree의 `tests/unit/zz-area01-*.test.ts` 3파일, 사본 `scratchpad/a01/`. worktree는 끝난 뒤 지웠다) ③ 변이 15건(`scratchpad/a01/mutate.mjs`, 결과 `scratchpad/a01/mutations.log`) ④ Node 24.14 마이크로 벤치 2개(`scratchpad/a01/copy-bench.mjs`, `sha-bench.mjs`, 직전 부하 8.4·9.4) ⑤ `flock heavy.lock node scripts/check-optional-recipes.ts`(source 모드, 직전 부하 19.75, lock 대기 포함 15분) → **PASS, file-transfer 55,623 / 55,700 gzip bytes** | +| 실험 조건 | 단위 harness와 가짜 BFF·object store다. X6은 실제 presigned provider·vault·실행기를 썼다. 오류는 실제 예외표 함수(`mapBrowserDataException`, `mapIndexedDbException`)로 만들었다. 실제 브라우저 오류, 실제 네트워크, 실제 서버는 쓰지 않았다 | +| 확인 못 한 것 | Playwright 영역 spec 3개(공유 lock 대기가 길어 이번에 돌리지 않았다), 브라우저 실제 메모리 최고점, 실제 BFF의 `429` 정책, 두 탭 경쟁, 모바일 CPU의 해시 시간, 번들 단위 제거 드릴. 9절에 정리했다 | +| 이전 리뷰와 비교 | 코드가 같으므로 지난 발견은 현재 코드 위치와 새 실행으로 다시 확인했다. 지난 라운드의 실행 결과(X1~X5, 변이 M1·M6~M17, 번들 55,623바이트)는 증거로 쓰지 않았다. 변이 번호 M9는 지난 라운드와 같은 변형이다 | + +**영역 판정 (35.8)** + +- presigned 실행기(PUT·download)와 vault: **지정 범위에서 사용 가능.** vault 반환(M28), 호출자 변경 방지 snapshot(M19), PUT·download deadline(M24·M25)이 변이로 검출된다. +- resumable upload runtime: **조건부 사용 가능.** 재개·결과 불명 complete·`ABORT_PENDING`·CAS·teardown은 검출된다(M22·M23·M29·M33·M35). 다운스트림은 ① 실패 recovery 표를 그대로 믿으면 안 되고(`0929/01-01`), ② BFF가 part 발급을 `429`로 제한하면 클라이언트가 `Retry-After`를 무시한다는 점을 알아야 한다(01-01). +- image CDN runtime: **조건부 사용 가능.** 같은 asset을 여러 곳에서 동시에 그리는 화면은 probe 다운로드가 그 수만큼 생긴다(01-04). + +## 2. 지난 발견 재확인 + +| 지난 ID | 심각도 | 상태 | 근거 | +| --- | --- | --- | --- | +| 0929/01-01 `upload()` 실패 recovery가 6개 경로에서 포트 표와 다르다 | Medium · P2 | **남음** | `toUploadAction`은 여전히 recovery 어휘만 본다(`resumable-upload-runtime.ts:1714-1726`). 포트 표는 그대로다(`resumable-upload.ts:104-121`). **X1a**(스트림이 `NotReadableError`, `result.ts:74-78` 표로 매핑): `{NOT_READABLE, UPLOAD_SESSION, retryable:true, recovery:NONE}`. **X1b**(checkpoint read가 IndexedDB `UnknownError` 1회, `result.ts:160-164`): 첫 호출 `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`, 같은 runtime 둘째 호출 성공. ③④⑥은 코드로 다시 확인했다(`http-common.ts:167-170`, `http-control-plane-adapter.ts:202-210`, `fetch-json-transport.ts:560-561`, `upload-response-validation.ts:70-74`). ⑤ 닫힌 runtime의 `RESUME`도 그대로다(`resumable-upload-runtime.ts:172-176`) | +| 0929/01-02 재조정 경로에서 checkpoint 삭제가 실패하면 resourceId를 버린다 | Low · P3 | **남음** | `reconcileActiveCheckpoint`의 `QUARANTINED` 분기는 삭제 실패를 그대로 돌려준다(`:583-589`). `completeUpload`만 무시한다(`:1149-1156`). **X2**: 첫 호출 `{UNAVAILABLE, UPLOAD_COMPLETE, retryable:true, RESUME}` → 둘째 호출(삭제 1회 실패) `{UNAVAILABLE, UPLOAD_RECONCILE, retryable:true, NONE}`, resourceId 없음 → 셋째 호출 `{QUARANTINED, resource_01, replayed:true}` | +| 0929/01-03 느린 업링크 설정이 runtime 정책과 실행기에 따로 있다 | Low · P3 | **남음**(정적 확인) | runtime `:1033-1039`, 실행기 `presigned-transfer-executor.ts:137-143, 340-345`. 문서는 여전히 정책 값만 낮추라고 적는다(`presigned-transfer-and-image-cdn.md:292-298`). 실험은 다시 하지 않았다 | +| 0929/01-04 file-transfer 어댑터만 지우면 게이트 3개가 실패한다 | Low · P3 | **남음**(정적 확인) | `scripts/check-adapter-inventory.ts:139-144`가 이 영역 파일 4개를 이름으로 고정한다. `scripts/contracts/release-artifacts.ts:1147`의 메시지도 그대로다. 제거 실험은 다시 하지 않았다 | +| 0929/01-05 `abort()` 실패 recovery에는 행동 표가 없다 | Low · P3 | **남음** | 포트 표는 `upload()`에만 있다(`resumable-upload.ts:104-121`). `abort()`는 `toUploadAction`을 거치지 않는다(`resumable-upload-runtime.ts:237-278`). 형식이 틀린 서버 응답은 여전히 `CORRUPT_DATA/RECONCILE`이다(`:1241-1253`) | + +지난 리뷰 FOLLOW-UP 성격의 항목도 모두 그대로다. + +| 항목 | 상태 | 근거 | +| --- | --- | --- | +| ABORT 멱등 키 재사용을 고정하는 테스트 없음 | 남음 | 변이 M9가 이번에도 249건 통과 | +| `0929` 01-09 바이트 상한 검사는 transport에 `maxPartCount`를 넘길 때만 동작 | 남음 | `fetch-json-transport.ts:157-166`. 조립 예도 넘기지 않는다(`resumable-upload.spec.ts:329-341`) | +| 업로드 PUT에 idle 제한 없음 | 남음(문서화된 선택) | `presigned-transfer-and-image-cdn.md:295-297` | +| 01-11 probe 재사용 테스트가 공개 이미지만 씀 | 남음 | `tests/unit/image-cdn-runtime.test.ts:1444-1578`의 3개 테스트가 `publicAsset()`만 쓴다 | +| `resumable-upload.spec.ts:7` `PAGE_ORIGIN` 포트 4174 고정 | 남음 | 설정 `playwright.capabilities.config.ts:24, 30-31`과 따로 적혀 있다 | +| 레시피 번들 예산 여유 77바이트 | 남음 | 이번 측정 55,623 / 55,700 gzip bytes(`frontend-capability-recipes.json:198`). 01-01을 고치면 헤더 파싱이 더해지므로 예산을 넘을 수 있다 | + +## 3. 대표 흐름과 비용 (체크리스트 2절, 이번 라운드 렌즈) + +### 3.1 정상 흐름 — 새 파일 업로드의 요청·해시·복사 + +```text +upload() + → 파일 전체 읽기 + part마다 SHA-256 (manifest) upload-byte-source.ts:107-183 + → checkpoint read → createSession(1) → CAS resumable-upload-runtime.ts:385, :643-710 + → getStatus(1) ← 같은 CREATE 키 재생으로 이미 part가 있는 session이 올 수 있어 필요 + → part마다: [FILE] 다시 읽기 + 복사 + SHA-256 검증 :858-887 / upload-byte-source.ts:231-258 + [RANGE] readRange + 복사 + SHA-256 검증 :775-822 / upload-byte-source.ts:185-229 + → 발급(1) → PUT(1): 실행기 snapshot 복사 + SHA-256 + fetch presigned-transfer-executor.ts:290, :347, :385 + → CAS(1) + → getStatus(1) → complete(1) → checkpoint remove +``` + +| 경우 | HTTP 요청 | IndexedDB 트랜잭션 | 근거 | +| --- | --- | --- | --- | +| 새 업로드, N part, 실패 없음 | `2N+4` (create 1, status 2, 발급 N, PUT N, complete 1) | `N+3` (read 1, CAS 1+N, remove 1) | 코드 + X3 첫 호출(create 1, status 1, 발급·PUT 각 7회 뒤 실패) | +| 기본 정책 최대 파일 5GiB(5MiB × 1,024 part) | 2,052 | 1,027 | 위 식 | +| 재개, k part 수락됨 | `2(N−k)+3` | `(N−k)+2` | X3 재개(N=8, k=6): status 2, 발급 2, PUT 2, complete 1 = 7 | +| part 하나가 계속 재시도 가능한 실패 | `2×(maxRetries+1)`, 기본 8 | 0 | X4(maxRetries 2): 발급 3, PUT 3 | + +part 하나(5MiB)에 드는 CPU (Node 24.14, 같은 V8, 부하 8.4): + +| 작업 | FILE 경로 새 업로드 횟수 | 1회 시간 | 합 | +| --- | --- | --- | --- | +| WebCrypto SHA-256 | 3 (manifest, runtime 검증, 실행기) | 8.6ms | 25.7ms | +| `Uint8Array.from` 복사 | 3 (검증 복사 `upload-byte-source.ts:245`, digest wrapper `:101` × manifest·검증) | 4.3ms | 13ms | +| `slice()` 복사 | 2 (실행기 snapshot `:290`, 실행기 digest `:1119`) | 1.5ms | 3ms | + +- 5GiB 파일이면 해시 약 26초, 복사 약 16초다. 복사는 main thread에서 돈다. 1Gbit/s 업링크의 전송 시간(약 43초)과 비슷한 크기다. 10Mbit/s면 전송이 약 70분이라 CPU 비용은 작다. +- 참고: `new Uint8Array(src)`는 0.96ms, `slice()`는 1.49ms, `Uint8Array.from(src)`는 4.32ms였다. 같은 결과에 4.5배 차이가 난다. +- 메모리 최고점(정적 계산): FILE 경로는 part가 PUT 중일 때 iterator 버퍼, 검증 복사, 실행기 snapshot, (실행기 digest 복사 또는 브라우저 fetch 본문 복사) 4개가 함께 살아 있다. RANGE 경로는 worker마다 3개 + 잠깐 쓰는 digest 복사다. 기본 정책(5MiB × 동시성 1 × copyFactor 4 = 20MiB)은 FILE 경로 최소 최고점과 같다. GC가 늦게 거두는 복사본과 스트림 chunk(≤ `maxSourceChunkBytes` 8MiB)는 식에 없다. 실제 브라우저 측정은 하지 않았다(01-03). + +### 3.2 피해가 큰 흐름 — 서버 과부하에서의 재시도 + +```text +part 발급 → BFF 429 Retry-After: 5 + → presigned provider: statusFailure(429) = UNAVAILABLE retryable, retryAfterMs 없음 http-common.ts:158-190 + → runtime: waitForRetry가 지수 backoff만 사용 (250 → 500 → 1000ms) resumable-upload-runtime.ts:1462-1475 + → 4번째 시도 실패 → { UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME } + → 포트 표: "retryable:true면 자동 재시도해도 된다" resumable-upload.ts:109-110 + → 다운스트림 자동 재시도 = 파일 전체 다시 해시 + status + 발급 4회 … +``` + +- 같은 서버가 control plane(create·status·complete·abort)에서 `429 Retry-After`를 주면 클라이언트는 기다린다(`fetch-json-transport.ts:575-588`). part 단계만 다르다(01-01). +- 한 호출 안의 재시도는 `maxRetries`로 묶인다. 호출 사이의 자동 재시도는 다운스트림 몫이고, 그때마다 파일 전체 해시가 다시 돈다. +- 전체 업로드의 시간 상한은 session 만료다. part 시도마다 만료를 확인한다(`resumable-upload-runtime.ts:952-958`). 최악의 경우 part 하나는 `4 × (30s 발급 + 110s PUT) + 1.75s ≈ 9.4분`까지 걸린다. 이 값은 모두 `runtime-policy.ts:60-81`에서 계산할 수 있다. + +### 3.3 중단 흐름 — 무엇이 남는가 + +| 중단 시점 | 남는 상태 | 다음 호출이 하는 일 | 근거 | +| --- | --- | --- | --- | +| createSession 성공, CAS 전 | 서버 session, 로컬 행 없음 | 같은 CREATE 키로 같은 session을 다시 받고 status로 맞춘다 | `:650-656`, `:705-707` 주석 | +| PUT 진행 중 | 서버에 part가 있을 수도 있음, 로컬 receipt 없음 | status가 서버 목록으로 checkpoint를 고친다 | `:604-634` | +| receipt CAS 중 | IndexedDB가 커밋됐을 수도 있음 | 다음 호출이 저장소 값을 다시 읽는다 | `:385`, CAS revision | +| complete 응답 유실 | `ACTIVE` 행, 서버는 완료 | 재호출 또는 `abort()`가 resourceId를 돌려준다(삭제 실패 시 예외 `0929/01-02`) | `:583-600`, `:1255-1263` | +| `abort()` 서버 성공, 로컬 삭제 전 | `ABORT_PENDING` 행 | `upload()`는 `RESTART`, `abort()` 재호출이 같은 ABORT 키로 끝낸다 | `:409-415`, `:1202-1209` | +| `dispose()` 중 provider가 안 끝남 | runtime `CLOSING` | 실패를 돌려주고 store를 닫지 않는다 | `:306-317`(M23 검출) | + +중단 위험은 대부분 코드 주석과 상태값으로 드러난다. 드러나지 않는 것은 `0929/01-02`(삭제 실패 시 결과 유실)와 `0929/01-05`(abort 실패 뜻) 두 가지다. + +### 3.4 다운로드 경로 비용 + +- 메모리는 chunk 하나로 묶인다. 받은 chunk를 `hardMaxChunkBytes`로 다시 잘라 복사한다(`presigned-transfer-executor.ts:744-751`). +- 무결성은 직접 구현한 JS SHA-256으로 스트리밍 검증한다. 같은 호스트에서 **156MiB/s**였다(WebCrypto 638MiB/s). 1GiB 다운로드면 main thread에서 약 6.5초다. 모바일은 측정하지 않았다. +- 실패하면 처음부터 다시 받는다. Range 재개는 `DESIGNED_NOT_IMPLEMENTED`로 문서에 있다(`presigned-transfer-and-image-cdn.md:27, 492-517`). 숨은 위험이 아니다. +- download 소비자는 검증 전 chunk를 받는다. 결과 타입의 `integrity: "VERIFIED_ON_SUCCESSFUL_EXHAUSTION"`(`:553`)이 이를 알린다. + +### 3.5 이미지 경로 비용 + +- private 이미지는 probe 다운로드(`cache: "no-store"`, `browser-image-probe.ts:131`)와 `` 다운로드로 두 번 받는다. 문서에 있다(`presigned-transfer-and-image-cdn.md:650-656`). +- 같은 asset reference를 동시에 5번 resolve하면 probe가 5번 돈다(X5). 통과한 뒤의 6번째 resolve는 재사용한다(01-04). + +## 4. 새 발견 (36.3) + +### 01-01 part 단계(발급·PUT)는 `Retry-After`를 읽지 않는다 — 문서는 읽는다고 하고, 테스트는 가짜 실행기로만 확인한다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(문서 계약과 구현 불일치) | +| 관련 관점 | 6, 5, 10, 14, 17, 23 | +| 근거 | presigned 계층의 상태표 `statusFailure(status)`는 상태 코드만 받는다(`src/adapters/browser-transfer/presigned/http-common.ts:158-190`). `429`는 `UNAVAILABLE`, `retryable:true`, `REISSUE_CAPABILITY`가 되고 `retryAfterMs`는 없다. BFF 발급 응답(`presigned-capability-http-provider.ts:261-264`)과 object store PUT 응답(`presigned-transfer-executor.ts:898`)이 모두 이 표를 쓴다. `grep -i retry-after src/adapters/browser-transfer/presigned/` 결과는 0줄이다. runtime은 `retryAfterMs`가 오면 기다릴 수 있다(`resumable-upload-runtime.ts:1462-1475`). 하지만 이 값을 만드는 곳은 control plane transport뿐이다(`fetch-json-transport.ts:575-588`). 문서는 part 전송의 "429/모든 5xx/network retry는 bounded `Retry-After`와 abortable backoff 안에서만 수행한다"고 적는다(`docs/architecture/presigned-transfer-and-image-cdn.md:286-287`). 서버 문서도 "server가 명시한 bounded `Retry-After` … 안에서만 재시도된다"(`server-file-capability-infrastructure.md:1664-1666`), "rate limit에서는 `Retry-After`를 상한 안에서 반영한다"(`:1034-1035`)고 적는다. 이를 확인하는 유일한 테스트는 `retryAfterMs: 7`을 직접 넣는 가짜 part 실행기를 쓴다(`tests/unit/resumable-upload-runtime.test.ts:530-569`). 출하되는 실행기·provider는 이 값을 만들지 않는다. **X6**(실제 provider·vault·실행기, 정책 `maxRetries 3`, `retryBaseDelayMs 250`, `maxRetryAfterMs 30000`): 발급이 `429 Retry-After: 5` → 발급 4회, sleep `[250, 500, 1000]`, 결과 `{UNAVAILABLE, UPLOAD_PART, retryable:true, RESUME}`. PUT이 `429 Retry-After: 5` → 발급 4회 + PUT 4회, sleep `[250, 500, 1000]`, 같은 결과 | +| 발생 조건 | BFF가 part 발급을 rate limit한다. 서버 문서 5.3은 "aggregate in-flight bytes와 provider connections에 hard cap"을 요구하므로(`server-file-capability-infrastructure.md:720-721`) 과부하 때 `429`가 자연스럽다. object store가 `429/503`에 `Retry-After`를 주는 경우도 같다 | +| 영향 | 과부하인 서버에 1.75초 안에 요청 8개를 보낸 뒤 포기한다. 결과가 `retryable:true`라 포트 표를 따르는 다운스트림은 자동으로 다시 부른다. 그때마다 파일 전체 해시(5GiB면 약 26초 CPU)와 status 요청이 다시 돈다. 과부하를 키우는 재시도 증폭이다. 데이터 손상과 중복 부작용은 없다 | +| 심각도·우선순위 | Medium · P2 — 피해는 지연과 서버 부하에 그친다. 하지만 두 설계 문서가 반대로 적고 있어 서버를 그 문서대로 만든 팀은 클라이언트가 기다린다고 믿는다. part 발급은 업로드당 N번 불리는, 가장 많이 불리는 control 엔드포인트다 | +| 통제·증거 | control plane M3(`429` 대기 테스트 `resumable-upload-runtime-recovery.test.ts:539`) · part 단계 M1(문서만) · E2(X6, 실제 어댑터 조합의 단위 harness) | +| 확실성과 남은 가정 | 코드와 실험으로 확정했다. 실제 BFF가 발급에 `429`를 쓰는지는 서버 구현 몫이라 미확인이다 | +| 결정의 근거 | [확인한 사실] runtime에는 `retryAfterMs` 경로와 상한 검사(`canRetry` `:1491-1504`)가 이미 있다. [리뷰어 추론] 빠진 것은 presigned 계층에서 헤더를 읽어 값을 채우는 한 단계다. 설계를 바꿀 문제가 아니다 | +| 이해 비용 | 서버 담당자는 두 문서를 믿으면 틀린다. 클라이언트 담당자는 runtime 테스트를 보면 지원된다고 믿는다. 실제 동작을 알려면 provider·실행기·`http-common.ts`를 따라가야 한다 | +| 최소 개선 방향 | `statusFailure`가 `Response`(또는 `Retry-After` 값과 현재 시각)를 받는다. `429`·`503`이면 kernel `parseRetryAfterDelay`(`src/adapters/platform/retry-after.ts`, transport가 이미 쓴다)로 `retryAfterMs`를 채운다. 실패 타입은 이미 `UploadProviderFailure`에 `retryAfterMs?`가 있다(`resumable-upload.ts:136-139`). presigned port 실패 타입에도 같은 선택 필드를 더한다 | +| 대안 비교 | (a) 위 최소 개선: 헤더 파싱 한 곳, 포트에 선택 필드 하나(추가형). (b) 문서를 "part 단계는 `Retry-After`를 읽지 않는다"로 고침: 코드 0줄, 재시도 증폭은 남는다. (c) BFF 발급 응답 본문에 대기 시간을 넣는 별도 계약: 서버·클라이언트 둘 다 바꾸고 표준 헤더를 두고 새 규약을 만든다. (b)는 위험을 문서로만 옮기므로 기각, (c)는 비용 대비 이득이 없어 기각한다 | +| 단순화의 보존 조건 | 적용 제외 — 기능 추가다. 다만 `Retry-After`가 `maxRetryAfterMs`를 넘으면 재시도하지 않는 control plane 규칙(`fetch-json-transport.ts:580-588`)과 같게 맞춘다 | +| 비용·부작용 | 수십 줄. presigned port 실패 타입에 선택 필드가 생기므로 CHANGELOG [계약] 한 줄. download 경로(`:843`)도 같은 표를 쓰므로 browser-files 전달 어댑터의 재시도도 같은 값을 받게 된다(영역 02와 확인 필요) | +| 재검토 조건 | 서버가 part 발급에 rate limit을 두지 않는다고 계약으로 정할 때 (b)로 충분하다 | +| 완료 기준 | X6의 두 경우 모두 sleep 첫 값이 5,000ms 이상이다. `Retry-After`가 `maxRetryAfterMs`를 넘으면 재시도하지 않는다 | +| 검증 방법 | X6을 `resumable-upload-runtime-recovery.test.ts`의 실제 provider harness(`presignedRuntime`)로 옮긴다. 가짜 실행기 테스트(`resumable-upload-runtime.test.ts:530`)는 runtime 단위로 남긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 01-02 `FILE_BYTE_SOURCE`로 재개하면 이미 수락된 part까지 다시 복사하고 해시한다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안(확인된 비용, 계약 위반 없음) | +| 관련 관점 | 14, 23 | +| 근거 | 스트림 경로는 part마다 `verifyUploadPartBytes`(복사 + SHA-256)를 먼저 하고, 그다음에 수락 여부를 본다(`src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts:881-888`). RANGE 경로는 빠진 part만 읽는다(`:776-778`). 재개 때 이미 수락된 part의 검증은 필요 없다. manifest 단계가 지금 파일로 모든 part를 해시하고(`upload-byte-source.ts:107-183`), status 검증이 서버 receipt를 그 manifest와 checksum까지 비교한다(`samePart`, `checkpoint-schema.ts:163-173`). 문서 4.3의 3단계("완료됐다고 주장하는 part의 local bytes를 다시 해시해 대조", `presigned-transfer-and-image-cdn.md:329-330`)는 이 두 단계로 이미 채워진다. **X3**(8 part 중 6개 수락 뒤 재개, runtime 쪽 part 해시만 셈): FILE 16회(파일 2배), RANGE 10회. **M18**(수락 확인을 검증 앞으로 옮김): 영역 249건 모두 통과 | +| 발생 조건 | `FileContentPort.openSource()`(`src/application/ports/browser-file-storage/file.ts:142-145`)의 `FileByteSource`를 그대로 넘겨 재개한다. file vault에서 바로 연결되는 쪽이 이 경로다. RANGE는 `readRange` 모양이 달라 어댑터가 필요하다 | +| 영향 | 99%에서 재개한 5GiB 파일은 쓸모없는 해시 약 1,014회(약 8.7초)와 복사 2,028회(약 8.7초)를 더 한다. 스트림이라 읽기 자체는 피할 수 없다 | +| 심각도·우선순위 | Low · P3 — CPU 비용뿐이다 | +| 통제·증거 | 해당 없음 · E2(X3, M18) | +| 확실성과 남은 가정 | 코드와 실험으로 확정했다. 시간은 Node 벤치로 환산한 값이다 | +| 결정의 근거 | 적용 제외 — 순서만 바꾸는 지역 수정이다. 기록된 의도(주석)도 없다 | +| 이해 비용 | 두 source 경로의 재개 비용이 다르다는 사실을 코드 비교로만 알 수 있다 | +| 최소 개선 방향 | `:888`의 `if (accepted.has(part.partNumber)) continue;`를 `:881` 검증 앞으로 옮긴다. manifest offset·length 대조(`:870-880`)는 모든 part에 남긴다 | +| 대안 비교 | 적용 제외 — 동작 계약이 같은 순서 변경이다 | +| 단순화의 보존 조건 | 모든 part의 offset·length가 manifest와 다르면 `INTEGRITY_FAILED/RESELECT`. 보낼 part의 내용이 바뀌면 `STALE_RESULT/RESELECT`. 진행률 값은 수락된 바이트부터 시작 | +| 비용·부작용 | 2줄 이동 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | X3 재개에서 FILE 경로 part 해시가 `N + (N−k)`회다 | +| 검증 방법 | 해시 횟수를 세는 crypto로 재개 테스트를 하나 추가한다(X3과 같은 방식) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 01-03 메모리 상한 식의 `partBufferCopyFactor`가 코드의 실제 복사 수가 아니라 정책 설정값이다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 5, 19, 13 | +| 근거 | 결정 문서는 "part memory는 `partSize × concurrency × copyFactor` hard ceiling으로 제한한다"고 적는다(`docs/architecture/decisions/VD-12-presigned-transfer-and-image-cdn.md:72`). 저장소 문서는 이 값을 "implementation copy factor"라고 부른다(`browser-file-and-origin-storage.md:333`). 하지만 코드에서 이 값은 다운스트림이 넘기는 정책 필드다(`runtime-policy.ts:12`). 기본 4, 허용 범위 1~8이다(`:49`, `:68`, `:101-103`). 검사는 조립 시점의 부등식 하나다(`:104-107`). 실제 복사는 코드 여러 곳에 흩어져 있고 이 숫자와 연결돼 있지 않다: iterator 버퍼(`upload-byte-source.ts:436, 485`), 검증 복사(`:245`), digest wrapper(`:101`), 실행기 snapshot(`presigned-transfer-executor.ts:290`), 실행기 digest(`:1119`), fetch 본문(`:389`). 3.1절 계산으로 FILE 경로의 최소 최고점은 4개다. 복사를 하나 더하거나 빼도 이 숫자를 바꾸라는 장치는 없다. 변이 M20·M26(복사 제거)은 테스트를 모두 통과했다 | +| 발생 조건 | 다운스트림이 동시성을 올리다 정책 검사에 걸리면, 가장 쉬운 손잡이인 `partBufferCopyFactor`를 낮춘다. 주석은 "raise both together"라고만 적는다(`runtime-policy.ts:64-65`). 예: `partSize 64MiB, maxConcurrency 4, copyFactor 1, maxInFlightBytes 256MiB`는 통과한다. 실제 최고점은 약 1GiB(RANGE 3개 × 4 worker × 64MiB = 768MiB + 잠깐 쓰는 복사)다 | +| 영향 | 모바일 브라우저에서 탭이 메모리 부족으로 죽을 수 있다. checkpoint가 있으므로 업로드는 재개할 수 있다. 기본값에서는 생기지 않는다 | +| 심각도·우선순위 | Low · P3 — 설정을 일부러 바꿔야 생긴다. 하지만 "hard ceiling"이라는 문서 주장은 설정 하나로 무너진다 | +| 통제·증거 | M2(조립 시점 부등식, 테스트 `resumable-upload-runtime.test.ts:104-107`, 변이 M21 검출) · 상한과 실제 복사 수의 연결은 M0 · E1(정적 계산), 브라우저 실측 없음 | +| 확실성과 남은 가정 | 정책 값과 복사 위치는 코드로 확정했다. 실제 최고 메모리는 브라우저의 fetch 본문 처리와 GC 시점에 따라 다르다 | +| 결정의 근거 | [기록된 의도] 문서는 이 값을 구현의 성질로 본다. [확인한 사실] 코드는 설정으로 받는다. [리뷰어 추론] 조립 시점 부등식이라는 구조는 싸고 충분하다. 문제는 한 항이 사용자 입력이라는 점이다(5절 D3) | +| 이해 비용 | 조립하는 사람은 이 숫자가 무엇을 세는지 알려면 6곳의 복사를 직접 찾아야 한다 | +| 최소 개선 방향 | copyFactor의 하한을 구현 상수로 둔다. 예: `PART_BUFFER_COPIES = 4`를 복사 위치 목록 주석과 함께 `runtime-policy.ts`에 두고, 그보다 작은 값을 거절한다 | +| 대안 비교 | 5절 D3. (a) 현상 유지. (b) 하한을 구현 상수로(추가형, 기존 조립 그대로 통과). (c) 정책 필드 제거(타입 변경). (d) runtime이 실제 버퍼 바이트를 세는 semaphore(실행기 안의 복사는 runtime이 볼 수 없어 정확하지도 않다). (b)를 권한다 | +| 단순화의 보존 조건 | 기본 정책이 계속 유효해야 한다(`has a valid production default policy`, M21 검출). 01-02·R2로 복사를 줄이면 상수도 같은 변경에서 낮춘다 | +| 비용·부작용 | 몇 줄. 1~3을 넘기던 조립은 실패하게 되므로 CHANGELOG [계약] 한 줄 | +| 재검토 조건 | 복사 수가 경로마다 크게 달라지거나, 실행기를 바꿔 복사 수를 runtime이 알 수 없게 될 때 (d)를 다시 본다 | +| 완료 기준 | `partBufferCopyFactor: 1`인 정책이 조립 시점에 거절된다. 상수 옆 주석이 복사 위치를 모두 가리킨다 | +| 검증 방법 | `resolveResumableUploadRuntimePolicy({ partBufferCopyFactor: 1 })` 거절 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 01-04 같은 asset·preset을 동시에 resolve하면 probe가 호출 수만큼 돈다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(중복 작업) | +| 관련 관점 | 14, 12, 13 | +| 근거 | `resolve()`는 통과 기록 `passedProbes`를 slot을 기다리기 **전에만** 본다(`src/adapters/browser-transfer/image-cdn/image-cdn-runtime.ts:586-590`). slot을 얻은 뒤(`:597-603`) 다시 보지 않는다. 기록은 probe가 끝난 뒤에 남는다(`:672-675`). 진행 중인 probe를 함께 쓰는 장치도 없다. **X5**(같은 accepted reference로 동시에 5번 resolve, `maxConcurrentProbes: 2`): probe 5회, 다섯 결과 모두 성공. 끝난 뒤 6번째 resolve는 probe 없이 재사용했다. 기존 테스트 `never runs more probes at once than maxConcurrentProbes`(`tests/unit/image-cdn-runtime.test.ts:1504-1538`)는 호출마다 새 reference를 만들어 이 경우를 보지 않는다 | +| 발생 조건 | 같은 private 이미지를 한 화면 여러 곳에 그린다(목록의 같은 아바타, 같은 썸네일). React StrictMode 개발 모드의 effect 두 번 실행도 같다 | +| 영향 | probe마다 preset의 encoded 예산까지 `no-store`로 내려받고 decode한다. 같은 이미지 20개면 다운로드·decode 20번이다. 동시 probe 4개 slot을 같은 이미지가 차지해서, 다른 이미지(예: 화면의 주 이미지) probe가 그 뒤로 밀린다 | +| 심각도·우선순위 | Low · P3 — 비용과 표시 지연뿐이다. 조립된 제품이 없다(`AVAILABLE_NOT_COMPOSED`) | +| 통제·증거 | 통과 뒤 재사용 M3(테스트 `:1464`) · 동시 호출 중복 제거 M0 · E2(X5) | +| 확실성과 남은 가정 | 코드와 실험으로 확정했다. 실제 화면에서 같은 reference를 공유하는지는 조립 코드(descriptor provider, 미구현)에 달려 있다 | +| 결정의 근거 | 적용 제외 — 이미 정한 "통과한 probe 재사용" 규칙을 대기 중인 호출에도 적용하는 문제다 | +| 이해 비용 | 문서의 "통과한 probe를 재사용"(`presigned-transfer-and-image-cdn.md:652-653`)만 읽으면 동시 호출도 싸다고 믿는다 | +| 최소 개선 방향 | slot을 얻은 직후 `passedProbes`를 한 번 더 보고, 통과했으면 slot을 돌려주고 descriptor를 반환한다. 중복이 `maxConcurrentProbes`개 이하로 준다 | +| 대안 비교 | (a) slot 뒤 재확인: 몇 줄, 첫 묶음(최대 4개)은 여전히 중복. (b) asset·preset별 진행 중 promise 공유(single-flight): 1회로 줄지만, 호출자마다 abort signal이 달라 한 호출자의 abort가 공유 probe를 끊지 않도록 참조 수를 세야 한다. 지금 조립 제품이 없으므로 (a)가 비용에 맞다 | +| 단순화의 보존 조건 | 실패한 probe는 기록하지 않는다(`:1464` 테스트). 재사용 전에 capability 만료를 다시 본다(`:547`, `:666-670`). 대기 중 abort한 호출은 slot을 차지하지 않는다(`:1540` 테스트) | +| 비용·부작용 | (a) 몇 줄 | +| 재검토 조건 | 조립 제품이 같은 이미지를 많이 반복해 그리면 (b)를 다시 본다 | +| 완료 기준 | X5에서 probe 횟수가 `maxConcurrentProbes` 이하다 | +| 검증 방법 | X5를 `image probe cost (01-11)` 묶음에 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 검토 (41절) + +### D1. part마다, 시도마다 일회용 capability를 새로 발급받는다 — 현 상태 유지 + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 브라우저가 object store에 직접 PUT한다. 서명 URL이 새거나 재생돼도 피해가 part 하나, 시도 하나로 끝나야 한다 | +| 2. 지킬 성질 | capability 하나는 한 번만 쓴다. 쓴 뒤나 실패한 뒤 vault에 남지 않는다 | +| 3. 현재 보장 | [확인한 사실] provider는 `singleUse: true`가 아닌 응답을 거절한다(`presigned-capability-http-provider.ts:509-511`). replay guard는 객체 identity로 한 번만 허용한다(`presigned-capability-vault.ts:378-397`). 실행기는 끝날 때 vault에서 뺀다(`presigned-transfer-executor.ts:113-120, 486-488`, M28 검출). 서버 문서도 발급을 "새 operation"으로 둔다(`server-file-capability-infrastructure.md:1030`). [비용] 요청이 `2N+4`, 재시도마다 2개다(3.1절) | +| 4. 대안 | (a) 현상 유지. (b) 여러 part의 capability를 한 번에 발급. (c) 시도 사이에 같은 capability 재사용. (d) BFF가 바이트를 대신 받는 proxy 업로드 | +| 5. 비교 | 발급 요청은 수백 바이트 JSON이고 PUT은 5MiB다. (b)는 요청 수를 줄이지만 capability가 vault에 오래 머물고 만료 위험이 커진다. (c)는 일회용 성질(2번)을 깬다. (d)는 서버 대역폭을 파일 크기만큼 쓴다 | +| 6. 판단 | 요청 수 비용은 바이트 비용에 비해 작다. 유지한다. 다만 발급이 가장 자주 불리는 control 요청이므로 과부하 신호(`Retry-After`)를 읽어야 한다(01-01) | +| 7. 재검토 조건 | part 크기를 1MiB 아래로 내리는 요구, BFF 발급 비용이 측정으로 병목이 될 때 (b)를 다시 본다 | + +### D2. 업로드 시작 전과 재개할 때마다 파일 전체를 해시해 fingerprint를 만든다 — 현 상태 유지, 스트림 경로의 두 번째 해시만 제거 + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 재개한 업로드가 다른 내용의 파일과 섞이면 안 된다. 서버는 create 때 fingerprint로 session을 묶는다(`server-file-capability-infrastructure.md` 5.2·5.3) | +| 2. 지킬 성질 | 서버가 가진 part와 지금 파일의 part가 checksum까지 같을 때만 이어 간다 | +| 3. 현재 보장 | [확인한 사실] manifest를 지금 파일로 계산하고(`upload-byte-source.ts:107-183`), 저장된 fingerprint·binding과 다르면 `STALE_RESULT/RESELECT`다(`resumable-upload-runtime.ts:397-408`). 서버 receipt는 `samePart`로 checksum까지 비교한다. [비용] 첫 PUT 전에 파일 전체를 읽고 해시한다. 5GiB면 이 호스트에서 해시만 약 9초, 복사 포함 약 13초다. 재개 때마다 반복한다. 진행률은 `PREPARING` 단계로 보인다(`:370-372`) | +| 4. 대안 | (a) 현상 유지. (b) 크기·수정 시각만 비교. (c) part를 보내면서 해시하고 fingerprint는 complete 때 보냄 | +| 5. 비교 | (b)는 수정 시각이 없는 source(OPFS 범위 reader, 스트림)가 있고, 같은 크기의 수정은 못 잡는다. 수락된 옛 part와 새 part가 섞인 객체가 완료될 수 있다. 2번을 깨므로 후보가 아니다. (c)는 create 때 binding이 없어져 서버 계약을 바꾸고, 재개 때는 결국 수락된 part를 다시 해시해야 한다 | +| 6. 판단 | 전체 해시는 안전한 재개의 값이다. 유지한다. 스트림 경로가 수락된 part를 한 번 더 해시하는 것만 낭비다(01-02) | +| 7. 재검토 조건 | 10GiB 넘는 파일이 흔해지거나 모바일에서 `PREPARING` 시간이 측정으로 문제가 될 때, 해시를 Worker로 옮기는 안을 본다 | + +### D3. 메모리 상한을 조립 시점 부등식으로 검사한다 — 구조는 유지, copyFactor는 구현 하한으로 + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 동시 업로드가 브라우저 탭 메모리를 넘지 않는다 | +| 2. 지킬 성질 | 설정이 어떻든 `동시 part × part 크기 × 실제 복사 수`가 `maxInFlightBytes` 이하다 | +| 3. 현재 보장 | [확인한 사실] `partSize × maxConcurrency × copyFactor ≤ maxInFlightBytes`를 조립 때 검사한다(`runtime-policy.ts:104-107`, M21 검출). worker 수는 정책·서버 동시성·남은 part 중 최소다(`resumable-upload-runtime.ts:799-803`). [보장하지 않음] copyFactor가 설정값이라 "실제 복사 수"를 보장하지 않는다(01-03). FILE 경로는 동시성 설정과 무관하게 순차다 | +| 4. 대안 | (a) 현상 유지. (b) copyFactor 하한을 구현 상수로. (c) 정책 필드 제거. (d) runtime이 버퍼 바이트를 세는 semaphore | +| 5. 비교 | (b)는 기존 기본 조립을 그대로 두고 잘못된 낮춤만 막는다. (c)는 같은 효과지만 정책 타입이 바뀐다. (d)는 실행기·브라우저 내부 복사를 볼 수 없어 정확하지 않고 코드가 늘어난다 | +| 6. 판단 | 부등식 구조는 싸고 충분하다. 사용자 입력인 항 하나만 구현 쪽으로 옮긴다 | +| 7. 재검토 조건 | 실행기를 바꿔 복사 수가 경로마다 크게 달라질 때 | + +## 6. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | 근거 | +| --- | --- | --- | --- | --- | +| R1 | 스트림 경로에서 수락 확인을 검증 앞으로(01-02) | 재개 때 해시·복사 절반 | 모든 part의 offset·length 대조(`INTEGRITY_FAILED/RESELECT`), 보낼 part의 `STALE_RESULT/RESELECT`, 진행률 시작값 | M18 249건 통과 | +| R2 | 중복 복사 제거: 스트림 경로 검증 복사(`upload-byte-source.ts:245`), digest wrapper 복사(`:101`), 실행기 digest 복사(`presigned-transfer-executor.ts:1119`) | WebCrypto `digest()`는 호출 순간 입력을 복사한다(WebCrypto 명세 "get a copy of the bytes"). 스트림 iterator는 yield한 버퍼를 다시 쓰지 않는다(`:483-486`). FILE 경로 최고점 4 → 3, part당 복사 시간 약 16ms → 약 3ms(벤치 환산) | 실행기 snapshot(`:290`)은 남긴다(M19 검출, 호출자 변경 방지). RANGE 경로 복사(`:216`)는 reader가 버퍼를 재사용할 수 있으므로 포트가 "소유권 이전"을 정하기 전에는 남긴다. iterator가 yield한 버퍼를 재사용하지 않는다는 테스트를 먼저 추가한다. TS `BufferSource` 타입 때문에 cast가 필요할 수 있다(`check:types`로 확인). 01-03 상수를 같은 변경에서 낮춘다 | M20·M26 249건 통과 | +| R3 | `RECOVERIES` Set(`resumable-upload-runtime.ts:118-132`)을 `satisfies Record` 객체로 | 공유 union(`shared.ts:69-82`)에 값이 늘면 지금은 조용히 `UNAVAILABLE/RESUME`으로 바뀐다. 컴파일 오류로 바꾼다 | 같은 13개 값, `normalizeProviderFailure`의 동작 | 정적 확인 | +| R4 | `isAbortSignal` 두 벌(`checkpoint-schema.ts:195`, `http-common.ts:209`), `MEDIA_TYPE` 두 벌(`checkpoint-schema.ts:26` 길이 63 제한, `presigned-capability-http-provider.ts:47` 제한 없음) 정리 | 갈라진 사본이다. 어느 쪽 규칙이 맞는지 코드가 말하지 않는다 | abort 판별은 더 엄격한 brand 검사(`http-common.ts`)를 기준으로. media type은 presigned 쪽을 좁히면 지금 받던 capability를 거절할 수 있으므로 [계약] 결정이 먼저다 | 정적 확인 | +| R5 | `resumable-upload-runtime.ts`(1,749줄)의 재시도 엔진(`callWithRetry`·`invokeProviderAttempt`·`waitForRetry`·`canRetry`, `:1334-1504`)을 `upload-retry.ts`로 | 재시도 정책을 찾으려면 가장 큰 파일 끝을 읽어야 한다. 01-01을 고칠 때도 이 부분을 본다 | 같은 재시도 의미(M29 검출), `physicalTasks` 등록(M23 검출), 관측 1회 규칙 | 선택. 효과는 탐색 비용뿐이다 | + +하지 않을 것: part마다 같은 값인 `digestUploadSessionBinding`(`resumable-upload-runtime.ts:934-941`)을 캐시하는 것. 100바이트 남짓한 해시 N번이라 이득이 없다. + +## 7. 폴더 구조와 테스트 + +**폴더 구조** + +- 하위 폴더 3개가 기능 3개(`presigned/`, `resumable-upload/`, `image-cdn/`)와 맞는다. 찾기 쉽다. +- `resumable-upload-runtime.ts`가 `../presigned/http-common.ts`의 `observeTransferResult`·`transferAllowanceMs`를 쓴다(`:31-34`). resumable이 presigned의 내부 helper에 기대므로 presigned를 따로 바꾸거나 지우기 어렵다. 같은 adapter 안이라 경계 위반은 아니다. +- `resumable-upload/checkpoint-schema.ts`는 checkpoint 스키마 말고도 요청 문법(`SAFE_UPLOAD_KEY`, `MEDIA_TYPE`, `isAbortSignal`, `exactRecord`)을 담는다. runtime과 part 실행기 bridge가 여기서 가져온다. 이름만 보면 찾기 어렵다(24). +- `image-cdn/README.md`가 소스 폴더 안에 있다. 조립 예가 코드 옆에 있어 찾기 쉽다. resumable upload에는 같은 조립 문서가 없다(20). + +**테스트** + +- 15파일 249건, 1.59초(부하 9.2). 영역 테스트 시간은 문제가 아니다. +- 변이 15건 결과(코드 한 곳을 바꾸고 영역 249건을 돌림): + +| ID | 바꾼 것 | 결과 | +| --- | --- | --- | +| M9 | ABORT 멱등 키를 시도마다 바꿈 | **249 통과 — 검출 못 함**(지난 라운드와 같음) | +| M18 | 스트림 경로에서 수락 확인을 검증 앞으로 | 249 통과 — 의도한 리팩토링 안전성 확인(R1) | +| M19 | 실행기 bytes snapshot 제거(`:290`) | 1 실패 — 검출 | +| M20 | 스트림 경로 검증 복사 제거 | 249 통과 — 중복 복사 확인(R2) | +| M20b | RANGE 경로 복사 제거(`upload-byte-source.ts:216`) | **249 통과 — 검출 못 함**(버퍼를 재사용하는 reader에 대한 방어가 테스트되지 않음) | +| M21 | 메모리 부등식 제거 | 1 실패 — 검출 | +| M22 | 첫 실패 때 형제 worker 중단 제거 | 1 실패 — 검출 | +| M23 | provider 실제 작업 등록 제거(TR-04) | 2 실패 — 검출 | +| M24 | download idle 제한 1000배 | 1 실패 — 검출 | +| M25 | 실행기 PUT deadline의 바이트 몫 제거 | 1 실패 — 검출 | +| M26 | digest wrapper 복사 제거 | 249 통과 — 중복 복사 확인(R2) | +| M28 | `put()` 끝의 vault 반환 제거(01-07) | 7 실패 — 검출 | +| M29 | `Retry-After` 무시 | 2 실패 — 검출(control plane 경로만. part 단계는 원래 무시한다, 01-01) | +| M33 | `abort()`의 같은 runtime 업로드 중단 제거 | 1 실패 — 검출 | +| M35 | IndexedDB CAS의 revision 비교 제거 | 1 실패 — 검출 | + +- 테스트가 위험을 놓치는 곳: ① part 단계 `Retry-After` 테스트가 출하 어댑터가 만들지 않는 값을 가짜로 넣는다(01-01). ② probe 동시성 테스트가 호출마다 새 reference를 써서 같은 이미지 중복을 보지 않는다(01-04). ③ M9·M20b. + +## 8. 성능 숫자 모음 + +| 항목 | 값 | 조건 | +| --- | --- | --- | +| 새 업로드 HTTP 요청 | `2N+4`, 기본 최대 2,052 | 코드 + X3 | +| 새 업로드 IndexedDB 트랜잭션 | `N+3`, 기본 최대 1,027 | 코드 | +| 재개 HTTP 요청 | `2(N−k)+3` | X3 | +| 실패하는 part 하나 | 요청 `2×(maxRetries+1)` = 8, 최악 약 9.4분 | X4, 정책 기본값 | +| part당 해시(FILE, 새 업로드) | 3회, 5MiB당 8.6ms | Node 24.14 WebCrypto, 부하 8.4 | +| part당 복사(FILE, 새 업로드) | 할당 7회(manifest 2, 전송 5), main thread 약 16ms | 같음 | +| part 버퍼 최고점 | FILE 4개, RANGE worker당 3개 + 잠깐 1개 | 정적 계산, 브라우저 미측정 | +| 재개 part 해시(N=8, k=6) | FILE 16, RANGE 10 | X3 | +| download 스트리밍 검증 | JS SHA-256 156MiB/s (WebCrypto 638MiB/s) | Node 24.14, 부하 9.4 | +| private 이미지 | 다운로드 2회(probe + img), 동시 같은 reference 5회 resolve → probe 5회 | 문서, X5 | +| 영역 테스트 | 15파일 249건 1.59초 | 부하 9.2 | +| file-transfer 레시피 번들 | 55,623 / 55,700 gzip bytes(여유 77) | `check-optional-recipes.ts` source 모드 | + +## 9. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +| --- | --- | --- | +| Playwright 영역 spec 3개(resumable-upload, presigned-streaming, image-cdn) | 공유 `heavy.lock` 대기가 길었다. 코드는 지난 라운드와 같다 | `playwright.capabilities.config.ts`로 3 브라우저 실행 | +| 브라우저 실제 메모리 최고점(01-03) | 측정 환경 없음 | DevTools memory로 part 64MiB × 동시성 4 업로드 | +| 실제 BFF가 part 발급에 `429`를 쓰는지(01-01) | 서버 구현은 repo 밖 | 짝 백엔드 템플릿의 발급 rate limit 확인 | +| 모바일 CPU의 해시·복사 시간 | 장비 없음 | 저사양 Android에서 5GiB `PREPARING` 시간 | +| 두 탭 같은 uploadKey 경쟁 | 단위 테스트는 메모리 lock만 쓴다 | Playwright page 2개 | +| `0929/01-03`·`01-04` 실험 재실행 | 코드가 같아 정적으로만 확인 | 지난 라운드 X3·X4 절차 | +| logout 때 `dispose()` → `deletePartition()` 순서 | 조립 코드가 없다 | 다운스트림 조립에서 확인 | + +## 10. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| **1** | 코드 성숙도 | O | M3 / M3 | E2 | checkpoint는 정확한 key만 받고 상태는 `ACTIVE → ABORT_PENDING → 삭제`, revision CAS로만 바뀐다(`indexeddb-checkpoint-store.ts:345-386`). M35·M22·M23 검출 | +| 2 | 구조적 성숙도 | O | M4 | E1, 게이트 | 배럴이 공개 경계. 다른 adapter import는 kernel뿐. `check:architecture` rc=0 | +| 3 | 변경 용이성 | O | M3 | E2 | 정책을 낮춘 빌드가 이전 checkpoint를 이어 가는 테스트(`resumable-upload-runtime-recovery.test.ts:951-999`)가 통과 | +| 4 | 인지 부하 | P | M1~M2 | E1 | 조립에 factory 6개, 같은 뜻의 값(timeout, min rate, `maxRetryAfterMs`)을 여러 곳에 넣는다. 조립 예는 Playwright spec뿐 | +| **5** | 위험 가시성 | P | M2 / M1~M2 | E2 | 29.4 문장은 대부분 코드로 채워진다(3.2·3.3절). 남은 것: part 단계 `Retry-After` 문서가 틀림(01-01), "hard ceiling"이 설정 하나로 무너짐(01-03), `0929/01-01`·`01-03`·`01-05` | +| **6** | 실패 성숙도 | P | M3 / M3(주 경로) | E2 | 재시도는 한 계층, 상한·jitter, PUT 403 재발급, 결과 불명 complete 조정(M29·M33 검출). 남은 것: 과부하 때 `Retry-After` 무시와 재시도 증폭(01-01), `0929/01-01`·`01-02` | +| 7 | 운영 성숙도 | O | M2 | E2 | part마다 `UPLOAD_PART` 관측 1건 + 시도 수 bucket(`resumable-upload-runtime.ts:833-839`). 수집·알림은 다운스트림 몫 | +| 8 | 디버깅 가능성 | P | M2 | E2 | 닫힌 code·operation·recovery 분류. `NONE`+`retryable:true` 조합이 여전히 나온다(X1a·X1b, `0929/01-01`) | +| 9 | 유지보수 성숙도 | P | M2 | E1 | 갈라진 사본 `isAbortSignal`·`MEDIA_TYPE` 두 벌, 손으로 복사한 `RECOVERIES`(R3·R4) | +| 10 | 테스트 성숙도 | P | M3 / M3(대부분) | E2(249 통과, 변이 10/15 검출) | 남은 것: M9·M20b 생존, `Retry-After` 테스트가 가짜 값을 씀(01-01), probe 동시성 테스트가 같은 reference를 보지 않음(01-04). 브라우저 spec 이번 미실행 | +| 11 | 데이터 성숙도 | P | M2~M4 | E2 | 계정 partition, key allowlist는 그대로. 재조정 경로 삭제 실패 때 resourceId 유실(`0929/01-02`, X2). 버려진 checkpoint 정리는 선언된 미구현 | +| **12** | 동시성 성숙도 | P | M3 / M3(업로드) | E2 | 업로드: Web Lock 직렬화(`upload-mutation-lock.ts:31-56`), CAS, receipt 저장 직렬화, 형제 worker 중단(M22), abort의 로컬 중단(M33) 검출. 남은 것: image probe의 "확인 후 대기" 순서로 같은 작업이 겹친다(01-04). 두 탭 실제 경쟁은 미검증 | +| 13 | 확장성 | P | M2 | E1, E2 | 발급 요청이 part 수에 비례(D1). `maxPartCount` 바이트 검사는 넘길 때만(`fetch-json-transport.ts:157-166`). 같은 이미지가 많은 화면에서 probe가 비례해 늘어남(01-04) | +| **14** | 성능 성숙도 | P | M3 / M2 | E2(X3·X5·벤치), E1(메모리) | 요청 `2N+4`, 해시 3회/part, 복사 할당 7회/part, 버퍼 최고점 4(8절). 남은 것: 01-01(과부하 때 증폭), 01-02, 01-03, 01-04, R2. 번들 55,623 / 55,700(여유 77바이트) | +| 15 | 보안 성숙도 | O | M4 | E2 | vault identity, `singleUse`, `credentials:"omit"`, `redirect:"error"`, `no-referrer`(`presigned-transfer-executor.ts:385-396`). M19·M28 검출 | +| 16 | 의존성 성숙도 | O | M2 | E1 | 외부 패키지 없음. WebCrypto와 자체 SHA-256 | +| **17** | API / Contract 성숙도 | P | M3 / M1~M3 | E2 | 포트 변경은 추가형. 남은 것: part 단계 `Retry-After` 문서 계약과 구현이 다름(01-01), recovery 표 6경로 불일치(`0929/01-01`), `abort()` 표 없음(`0929/01-05`) | +| 18 | 배포 성숙도 | O | M3 | E2 | 정책을 낮춘 새 빌드가 이전 checkpoint를 이어 감. 모르는 schema 행은 `abort()`로 지움 | +| 19 | 설정 성숙도 | P | M2 | E1, E2 | 각 factory는 값을 검증하지만 factory 사이 값은 서로 검사하지 않는다(`0929/01-03`). 구현 성질인 copyFactor를 설정으로 받는다(01-03) | +| 20 | 개발자 경험 | P | M1 | E1 | resumable upload 조립 문서가 없다. image-cdn은 README가 있다 | +| 21 | Guardrail 성숙도 | P | M3 | E2 | 영역 규칙은 변이로 검출된다. `check-adapter-inventory.ts:139-144`가 이 영역 파일 이름을 고정한다(`0929/01-04`) | +| 22 | 추상화 성숙도 | O | M3 | E1 | 앱 포트는 `upload()`·`abort()` 둘. 프로토콜 세부는 control plane 포트에 있다 | +| 23 | 일관성 | P | M2 | E2 | 같은 서버의 `429 Retry-After`를 control plane은 따르고 part 단계는 무시한다(01-01). 두 source 경로의 재개 비용이 다르다(01-02). `0929/01-01`·`01-02` | +| 24 | 네이밍 / 의미 성숙도 | P | M2 | E1 | `NONE`+`retryable:true`. `maxInFlightBytes`는 runtime 상한처럼 읽히지만 조립 시점 부등식이다. `checkpoint-schema.ts`가 요청 문법도 담는다 | +| 25 | 조직 확장성 | - | - | - | 적용 제외: 팀 1인 | +| 26 | Ownership 성숙도 | P | M1 | E0~E1 | 발급 단계에서 사라진 session의 응답 코드, 발급 rate limit과 `Retry-After`를 누가 정하는지가 서버·클라이언트 문서 사이에 비어 있다 | +| 27 | 삭제 가능성 | P | M3 주장 / 레시피 단위 M0 | E1 | 레시피는 production 번들에 조립돼 있지 않다. 어댑터만 지우면 게이트가 실패한다(`0929/01-04`, 이번 정적 확인). resumable이 presigned 내부 helper에 기댄다(7절) | +| **28** | 회복 가능성 | P | M3 / M3(주 경로) | E2 | 중단 뒤 재개, 결과 불명 complete 조정, `ABORT_PENDING`, teardown 미완료 보고가 테스트된다(3.3절, M23·M33·M35). 남은 것: `0929/01-02`. 과부하 뒤 회복이 빠른 포기와 파일 전체 재해시를 거친다(01-01) | + +충족 O 8 · 부분 충족 P 19 · 미충족 X 0 · 미검증 ? 0 · 적용 제외 1. diff --git a/docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md b/docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md new file mode 100644 index 00000000..636da7bc --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md @@ -0,0 +1,367 @@ +# 02 browser-files / cache-storage / cross-context-invalidation 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 깊게 본 관점: 1, 5, 6, 11, 12, 15, 24 · 이번 라운드 추가 렌즈: 리팩토링 후보, 성능 비용, 폴더 구조, 테스트가 위험을 잡는지 + +ID 표기: 이번 라운드의 새 발견은 `02-01`부터 쓴다. 지난 라운드(2026-09-29)의 발견은 `0929/02-01`처럼 앞에 날짜를 붙인다. + +## 요약 + +- 지난 기준 `af3d8e6` 뒤로 이 영역의 코드·테스트·설계 문서는 한 줄도 바뀌지 않았다. 지난 발견 6건(`0929/02-01`~`02-06`)은 모두 **남음**이다. 이번에 새 실행으로 다시 확인했다. + - 가장 큰 것은 여전히 `0929/02-01`(Medium)이다. `retainedPreviousReleaseCount`를 3에서 1로 줄이면 조회·활성화·정리·inspect가 모두 `CORRUPT_DATA`로 멈춘다. 이번에 Node(E-1)와 실제 Cache API 3엔진(E-2)에서 다시 재현했다. +- **새 구조적 위험(Medium).** `runtime.previews.dispose()`가 preview 것만이 아니라 공유 lease registry 전체를 비운다. 30초 grace 중인 download blob URL까지 revoke하고, 그 뒤 runtime이 살아 있는 동안 preview는 계속 `UNAVAILABLE`이다(02-01). 코드 주석은 이 dispose를 "route teardown"에서 쓰라고 안내한다. +- **새 Low 4건.** + - download 정책의 `safeExtension`은 금지 확장자 목록도, media type도 검사하지 않는다. `application/pdf` + `.exe` 정책이 통과하고 `invoice.pdf`가 `invoice.exe`로 저장된다(02-02). + - 이미 stage된 후보를 재검증하다 읽기 오류가 나면 stage 결과와 관측이 `CACHE_ACTIVATE`로 기록된다(02-03). + - 보호 규칙 7개가 변이 실험에서 살아남는다. object URL 합계 바이트 상한, host의 `storageArea` 동일성 비교, `no-cache` 응답 거절 등이다(02-04). + - cross-context publish 실패는 원인이 무엇이든 관측 reason이 `INVALID_ENVELOPE`다(02-05). +- 변이 25건: 검출 12, 생존 11, 동등 변이 2. 지난 라운드의 생존 4건(M05·M10·M13·M14)은 그대로 생존한다. +- 영역 단위 테스트 12파일 152건은 1.39초, 영역 browser spec 21건(3엔진)은 11.5초에 끝난다. 실행 시간은 문제가 아니다. +- 번들: service-worker-pwa 레시피가 9,662 / 10,000 gzip bytes로 여유가 338바이트뿐이다. cache-storage를 고치면 예산을 같이 봐야 한다(7.1절). + +**영역 판정 (35.8)** + +- cross-context-invalidation(기본 조립): **지정 범위에서 사용 가능.** 역순·중복(M11), 다른 storage 영역의 이벤트(M12), close 때 listener 제거(N20)를 테스트가 잡는다. 실제 분류를 하는 host의 `storageArea` 비교만 테스트가 없다(02-04). +- browser-files(file-transfer 레시피, 미조립): **조건부 사용 가능.** 조립하는 제품은 ① `previews.dispose()`를 route 정리에 쓰면 안 되고(02-01), ② download 정책의 확장자를 직접 검토해야 한다(02-02). +- cache-storage(service-worker-pwa 레시피, 미조립): **정책 값을 바꾸는 배포 전에는 사용 보류.** `0929/02-01`을 먼저 고친다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `src/adapters/browser-files/` 10파일 4,780줄, `src/adapters/cache-storage/` 5파일 2,301줄, `src/adapters/cross-context-invalidation/` 3파일 1,059줄. 포트 `src/application/ports/browser-file-storage/{file,shared,cache-storage-ports}.ts`, kernel `src/adapters/browser-file-storage/result.ts`, 계약 `src/contracts/cache-invalidation.ts` | +| 커밋·작업 상태 | `d99301b`. `git diff --stat af3d8e6 d99301b`를 세 폴더·포트·kernel·계약·`src/adapters/query-cache`·`.dependency-cruiser.json`·`tests/unit`·`tests/browser-capabilities`에 걸면 바뀐 파일은 `tests/unit/oklch-contrast.test.ts` 하나뿐이다(UI 감사). 워킹트리 미커밋은 `.claude/`뿐이다 | +| 전제 (0.1) | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. cross-context는 기본 조립(`src/bootstrap/runtime-adapters.ts:359-403`). browser-files는 file-transfer, cache-storage는 service-worker-pwa 레시피의 `AVAILABLE_NOT_COMPOSED` 런타임(`config/recipes/frontend-capability-recipes.json:118-131`, `:155-178`). 공개 경계는 배럴 세 개다. 규모·운영 목표는 없다. 코드의 상한 값을 사실상의 목표로 봤다 | +| 읽은 코드 | 세 폴더 전체. 포트 3파일 전체. `result.ts` 전체. `cache-invalidation.ts` 전체. 소비·조립: `src/adapters/query-cache/tanstack-cache-coordinator.ts:1-60`·crossContext 사용처, `src/bootstrap/runtime-adapters.ts:353-420`, `:610-625`, `src/features/installed-feature-contracts.ts:50-80` | +| 읽은 설정·문서(주장) | `.dependency-cruiser.json:241-251`, `CHANGELOG.md:51`, `docs/architecture/browser-file-and-origin-storage.md` 5.2절(445-470)·preview lease(350-372)·8.3절(950-1010)·9절, `docs/architecture/client-cache-and-storage.md:75-100`, 지난 리뷰 `2026-09-29-maturity-review/02-adapters-browser-files-cache.md`와 README 9.5 영역표 | +| 게이트(오케스트레이터 실행, 로그만 읽음) | `check:architecture`·`check:types`·`lint`·`test:unit`(165파일 2,353건)·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`verify:documentation`·`check:adapter-inventory`·`check:ci` rc=0. `test:system` rc=1은 `ci-artifact-contract.test.ts`의 문자열 기대값 문제로 이 영역과 무관하다 | +| 직접 실행 | ① 메인 repo: `node scripts/run-vitest.ts run` 영역 12파일 → **152건 통과, 1.39초**(직전 부하 8.25). ② 분리 worktree(`scratchpad/wt-02`, `d99301b`, 메인 `node_modules` 링크, pnpm 미사용): 실험 E-1·E-6~E-9(임시 테스트 2파일), 변이 25건(`scratchpad/review02-mutate.mjs`, 39.7초, 직전 부하 13.5), kernel 예외 probe 2개(`check-architecture.ts`를 `npm_execpath` shim으로 실행). ③ `flock heavy.lock`: 영역 browser spec 3개 + 임시 pointer spec을 chromium·firefox·webkit으로, recipe 번들 측정. 결과는 2절과 7절 | +| 확인 못 한 것 | 제거 드릴 `test:browser-file-storage-removal`(pnpm 전용 스크립트라 worktree에서 돌리지 않았다). 실제 제품 화면(소비자 없음). 다른 탭의 계정 전환 뒤 hint 영향. Safari의 blob URL 30초 grace 충분성. 9절에 정리했다 | +| 이전 리뷰와 비교 | 코드가 같으므로 지난 발견은 현재 줄 번호와 새 실행으로 다시 확인했다. 지난 라운드의 E-1~E-5와 변이 결과는 증거로 쓰지 않았다. 변이 번호 M01~M14는 지난 라운드와 같은 변형이다 | + +## 2. 실험 기록 + +| ID | 방법 | 결과 | +| --- | --- | --- | +| E-1a | `MemoryCacheStorage`에서 retained 3 정책으로 release 4개를 stage·activate한 뒤, 같은 저장소에 retained 1 adapter를 만든다. 조회, 새 release 2개 배포, cleanup, inspect | `{"lookup":"CORRUPT_DATA/REHYDRATE","deploys":[{"staged":"ok","activated":"CORRUPT_DATA/REHYDRATE"}×2],"cleanup":"CORRUPT_DATA","inspect":"CORRUPT_DATA","ownedCaches":7}` | +| E-1b | release 하나를 활성화한 뒤 pointer JSON을 잘라 넣고 다음 release를 배포 | `{"staged":true,"activated":"CORRUPT_DATA","cleanup":"CORRUPT_DATA"}` | +| E-2 | E-1a와 같은 시나리오를 Playwright로 실제 `caches`·`navigator.locks`에서 실행(임시 `tests/browser-capabilities/zz-review02-pointer.spec.ts`, 포트 4192 설정 사본) | chromium·firefox·webkit 모두 `{"lookup":"CORRUPT_DATA","deploys":[{"staged":"ok","activated":"CORRUPT_DATA"}×2],"cleanup":"CORRUPT_DATA","ownedCaches":7}`. 실행 직전 부하 14.73 | +| E-3 | 변이 25건. 규칙 한 곳을 바꾸고 관련 unit 파일만 실행 | 검출 12 · 생존 11 · 동등 2. 표는 8.3절 | +| E-4 | kernel 예외 probe. P1: `src/adapters/realtime/`에서 cross-context **배럴**의 런타임 팩토리를 import. P0: 같은 팩토리를 내부 파일 `browser-cross-context-host.ts`에서 import | P1: `check-architecture.ts` exit 0(통과). P0: exit 1, `adapters-do-not-know-other-concrete-adapters` 위반 | +| E-6 | stage 성공 뒤 같은 manifest를 다시 stage. 재검증 중 asset `match()`가 `InvalidStateError`를 던지게 함 | `{"code":"UNAVAILABLE","operation":"CACHE_ACTIVATE",...}`, 관측도 `operation:"CACHE_ACTIVATE"` | +| E-7 | download 정책 `{mediaType:"application/pdf", safeExtension:".exe"}`, `{mediaType:"text/html", safeExtension:".html"}`로 registry를 만들고 BOUNDED_OBJECT_URL 전달 | 두 정책 모두 생성 성공. handoff 파일명 `["invoice.exe","report.html"]`(입력 `invoice.pdf`, `report`) | +| E-8 | cross-context에서 `createEventId`가 던지게 한 뒤 publish, 등록되지 않은 topic version으로 publish | 두 경우 모두 `{ok:false, reason:"INVALID_EVENT"}`, 관측 reason `INVALID_ENVELOPE` | +| E-9 | jsdom에서 runtime을 만들고 bounded download를 handoff한 뒤(30초 grace 중) `runtime.previews.dispose()` 호출 | `{"first":"BROWSER_HANDOFF","revokedByPreviewDispose":["blob:runtime-0"],"previewAfter":"UNAVAILABLE","downloadAfter":"BROWSER_HANDOFF"}` | +| 브라우저 spec | `browser-files`·`cross-context-invalidation`·`public-cache-storage` spec을 3엔진으로(E-2와 같은 실행) | **21/21 통과**(browser-files 3, cross-context 2, public-cache-storage 2 × 3엔진). E-2 포함 24건, 11.5초 | + +worktree와 임시 파일은 끝난 뒤 지웠다. 실험 스크립트 사본은 `scratchpad/review02-mutate.mjs`, `scratchpad/review02-heavy.sh`, 임시 테스트 사본은 `scratchpad/review02-experiments/`다. + +## 3. 지난 발견 재확인 + +지난 라운드 뒤로 이 영역 파일이 바뀌지 않아 줄 번호도 같다. 필드 전체(36.3)는 지난 문서에 있고 내용이 그대로 유효하다. 아래는 현재 근거와 이번 실행 결과만 적는다. + +| 지난 ID | 심각도·우선순위 | 상태 | 현재 근거 | +| --- | --- | --- | --- | +| `0929/02-01` Cache Storage pointer를 현재 정책으로 검증해, 정책을 바꾼 배포나 손상 뒤에는 조회·활성화·정리가 영구히 멈춘다 | Medium · P2 | **남음** | `isActivePointer`가 rollback 목록 길이를 현재 `retainedPreviousReleaseCount`와 비교한다(`src/adapters/cache-storage/public-cache-codec.ts:455-456`). ID·캐시 이름도 현재 정책으로 본다(`:441`, `:459-464`). 실패는 `CORRUPT_DATA`/`REHYDRATE`(`public-response-cache-adapter.ts:1016-1020`)이고 조회(`:247-254`)·활성화(`:693-702`)·정리(`:783-789`)·inspect(`:855-859`)가 여기서 멈춘다. control cache를 지우는 API는 없다(`cache-storage-ports.ts:69-85`). E-1a·E-1b로 재현. 고정 테스트 없음(M13·M14 생존). E-2: 실제 Cache API 3엔진에서도 같은 결과(조회·활성화·정리 `CORRUPT_DATA`, 소유 캐시 7개) | +| `0929/02-02` `inspect()`의 비용·취소·판정 불가가 포트 계약에 드러나지 않는다 | Low · P3 | **남음** | 포트에 signal이 없다(`cache-storage-ports.ts:84`). 호출부가 `undefined`를 넘긴다(`public-response-cache-adapter.ts:883`). 읽기 오류(`UNKNOWN`)도 `verified:false`다(`:888`). 문서는 비용을 cache 수 비례로만 적는다(`browser-file-and-origin-storage.md:974-977`). M05 생존 | +| `0929/02-03` CHANGELOG 0.2.0의 browser-files [계약] 행이 실제 변경 경로·대상과 다르다 | Low · P3 | **남음** | `CHANGELOG.md:51`의 영향 경로가 여전히 `src/adapters/browser-file-storage/`다. 실제로 바뀐 `src/adapters/browser-files/`와 포트 `shared.ts`가 없다. cache 부분을 "browser-files recipe"로 적는다 | +| `0929/02-04` 이 영역 설계 문서의 줄 번호 참조가 다시 밀렸다 | Low · P3 | **남음** | `client-cache-and-storage.md:94`가 `server-state-scope-runtime.ts:148`(빈 줄)을 가리킨다. 실제 호출은 `:154`. `browser-file-and-origin-storage.md:368` `download-delivery-adapter.ts:385-391` → 실제 dispose `:386-393`. `:371` `runtime-adapters.ts:410-416` → 실제 `:411-417`. `client-cache-and-storage.md:79-81`의 "Chromium/Firefox만"도 그대로다 | +| `0929/02-05` bounded download에서 lease를 만든 뒤 handoff가 실패하면 lease를 돌려주는 규칙을 테스트가 고정하지 않는다 | Low · P3 | **남음** | `download-delivery-adapter.ts:827`에서 lease를 만들고 `:853-854`에서 돌려준다. 이 한 줄을 지운 M10이 file 테스트 68건을 모두 통과했다 | +| `0929/02-06` cross-context-invalidation kernel 예외가 실제 쓰임(타입 2개)보다 넓다 | Low · P3 · 결정 필요 | **남음** | 예외가 `cross-context-invalidation/index.ts` 전체를 연다(`.dependency-cruiser.json:249`). 쓰는 곳은 query-cache의 `import type` 한 곳뿐이다(`tanstack-cache-coordinator.ts:16-19`). E-4 P1: realtime에서 런타임 팩토리를 배럴로 import해도 통과한다. 내부 파일 import(P0)는 막힌다. 소유자 메모의 방향("새 파일 단위 예외를 늘리지 않는다, 공유 어휘는 `src/contracts/`로")과 이 제안이 같은 쪽이다 | + +FOLLOW-UP: 2026-09-29 라운드에는 `FOLLOW-UP.md`가 없다. 2026-09-25 FOLLOW-UP의 02-09(문서 줄 번호)는 `0929/02-04`에 흡수돼 있고 여전히 유효하다. + +## 4. 새 발견 (36.3) + +### 02-01 `previews.dispose()`가 공유 lease registry 전체를 비운다 — download의 grace 중 URL까지 revoke하고, runtime이 살아 있는 동안 preview를 영구히 끈다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험 | +| 관련 관점 | 5, 22, 24, 6, 17 | +| 근거 | runtime은 lease registry 하나를 preview와 download에 같이 넘긴다(`src/adapters/browser-files/create-browser-file-runtime.ts:109-120`, `:154`, `:163`). `BrowserTransientPreview.dispose()`는 그 registry의 `dispose()`를 부른다(`object-url-lease.ts:341-345`, 바인딩 `:231`). registry `dispose()`는 누가 만든 lease인지 구분하지 않고 전부 revoke한다(`:174-178`). preview는 `#disposed`가 켜지면 이후 모든 `create()`가 `UNAVAILABLE`이다(`:259-263`). 이 dispose는 앱이 받는 포트 `TransientPreviewPort`의 공개 메서드다(`src/application/ports/browser-file-storage/file.ts:166`). 포트에는 효과 범위 설명이 없다. registry 주석은 dispose를 "route/runtime teardown"의 안전망이라 부른다(`object-url-lease.ts:74-76`). E-9: download handoff 직후 `runtime.previews.dispose()`를 부르면 그 download의 blob URL이 즉시 revoke되고, 이후 preview는 `UNAVAILABLE`, download는 계속 동작한다 | +| 발생 조건 | 제품 기능이 route나 화면을 떠날 때 `runtime.previews.dispose()`를 부른다. runtime은 route보다 오래 산다(문서가 그렇게 권한다: `browser-file-and-origin-storage.md:365-372`) | +| 영향 | ① 다른 화면이 띄운 preview URL이 모두 revoke돼 이미지가 깨진다. ② runtime을 다시 만들 때(보통 로그아웃)까지 preview가 계속 `UNAVAILABLE`이다. ③ 30초 grace로 지키던 download blob URL이 바로 revoke된다. 브라우저가 아직 blob을 읽기 시작하지 않았다면 그 download가 실패할 수 있다(엔진별 시점은 미확인) | +| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 하지만 공개 포트 메서드 하나를 자연스럽게 쓰면 다른 포트(download)와 다른 화면의 기능이 함께 꺼진다. 코드 주석이 그 사용을 권하는 쪽으로 읽힌다. 레시피를 조립하는 다운스트림으로 복제된다 | +| 통제·증거 | M1(문서 `browser-file-and-origin-storage.md:354` "feature/runtime dispose는 모든 active lease를 즉시 revoke")· 코드·포트에는 효과 범위 표시 없음 · E2(E-9, jsdom) | +| 확실성과 남은 가정 | 동작은 E-9로 확정. 제품이 실제로 `previews.dispose()`를 route 정리에 쓸지는 모른다(repo 안 소비자 없음). 실제 브라우저에서 grace 중 revoke가 download를 끊는지는 확인하지 않았다 | +| 결정의 근거 | 5.2절. 한 예산을 공유하는 선택(지난 라운드 4.2절)은 유지할 근거가 있다. 문제는 예산 공유가 아니라 **해제 권한**이 포트마다 열려 있다는 점이다 | +| 이해 비용 | 기능 작성자는 `previews.dispose()`의 효과를 알려면 runtime 조립(`create-browser-file-runtime.ts`)과 registry 구현을 읽어야 한다. 이름과 포트만으로는 "preview 것만 정리"로 읽힌다 | +| 최소 개선 방향 | preview가 자기가 만든 lease 집합만 들고 `dispose()`에서 그것만 release한다. registry 전체 `dispose()`는 runtime `dispose()`만 부른다. download의 `dispose()`(`download-delivery-adapter.ts:386-393`)도 같은 방식으로 자기 lease만 정리하게 맞춘다 | +| 대안 비교 | (가) 현상 유지 + 포트 주석에 "runtime 전체에 영향" 명시: 코드 0줄. 함정은 남는다. (나) 위 최소 개선: 클래스 하나에 Set 하나. 포트 계약은 그대로다. (다) `TransientPreviewPort`에서 `dispose()`를 빼고 runtime만 수명을 소유: 가장 단순하지만 포트 변경([계약])이다. 소비자가 repo 안에 없으니 비용은 작다. (나)와 (다)는 함께 해도 된다 | +| 단순화의 보존 조건 | runtime `dispose()`는 여전히 preview·download lease를 모두 즉시 revoke한다(`browser-file-runtime.test.ts` 첫 테스트). lease `release()`는 멱등이다. 소진은 `retryable:true`(02-04 수정 사항)다. dispose 뒤 preview는 `UNAVAILABLE`이다 | +| 비용·부작용 | (나) 수십 줄과 테스트 1~2개. preview 쪽 lease 집합만큼 메모리가 조금 는다 | +| 재검토 조건 | preview와 download를 서로 다른 runtime 수명으로 나누는 요구가 생기면 registry 자체를 소비자별로 나누는 안을 다시 비교한다 | +| 완료 기준 | grace 중 download lease가 있는 상태에서 `previews.dispose()`를 불러도 그 URL이 revoke되지 않는다. 또는 포트에서 `dispose()`가 사라지고 runtime만 수명을 소유한다 | +| 검증 방법 | E-9를 `tests/unit/browser-file-runtime.test.ts`에 옮긴다. revoke 목록에 download URL이 없음을 단언한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-02 download 정책의 `safeExtension`은 금지 확장자 목록도 media type도 검사하지 않는다 — 문서는 "content type과 맞지 않는 executable extension 교체"라고 한다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(문서 주장과 다른 통제 범위) | +| 관련 관점 | 15, 5, 21, 23 | +| 근거 | `sanitizeSuggestedFileName`은 정책의 `safeExtension`을 형식(`EXTENSION` 정규식)만 검사한다(`src/adapters/browser-files/file-policy.ts:314`, `:378-384`). 금지 목록(`:63-97`)은 사용자 이름 안의 확장자에만 쓴다(`:357-361`). registry도 형식만 본다(`browser-file-policy-registry.ts:446-466`). mediaType과 확장자의 짝은 어디서도 보지 않는다. preview는 반대로 active content 금지 목록을 바닥값으로 둔다. 조립이 늘릴 수만 있고 줄일 수 없다(`object-url-lease.ts:202-209`, `:233-242`). 문서는 "content type과 맞지 않는 executable/double extension 교체"를 약속한다(`docs/architecture/browser-file-and-origin-storage.md:462`). E-7: `application/pdf` + `.exe`, `text/html` + `.html` 정책이 생성되고, `invoice.pdf`가 `invoice.exe`로 handoff된다 | +| 발생 조건 | 다운스트림이 download 정책을 만들 때 확장자를 잘못 넣는다(복사·붙여넣기, `.htm`/`.svg` 내보내기 기능). browser-managed 경로는 서버 capability의 `safeExtension`이 정책과 같아야 하므로 같은 값이 서버까지 이어진다(`download-input-validation.ts:279-280`) | +| 영향 | 사용자가 받은 파일이 실행 파일 확장자나 active content 확장자를 단다. 내용은 정책 media type(예: PDF)인데 OS는 확장자로 연다. 사용자 입력 이름의 확장자는 무력화되므로 공격자가 직접 고를 수는 없다 | +| 심각도·우선순위 | Low · P3 — 정책은 조립 코드(신뢰 영역)가 정한다. 공격자가 바꿀 수 없다. 다만 템플릿이 사용자 이름에는 금지 목록을 적용하면서 정책 값에는 적용하지 않아, 보호 범위가 문서보다 좁다 | +| 통제·증거 | 사용자 이름: M3(`browser-file-content.test.ts:133-141`, N31 검출) · 정책 확장자: M0 확인 · E2(E-7) | +| 확실성과 남은 가정 | 코드와 E-7로 확정. `.html`/`.svg` 내보내기가 정당한 제품 요구일 수 있다는 점은 열려 있다 | +| 결정의 근거 | 5.3절 | +| 이해 비용 | 정책 작성자는 금지 목록이 자기 값에도 걸린다고 기대하기 쉽다. 아니라는 사실은 `sanitizeSuggestedFileName` 본문을 읽어야 안다 | +| 최소 개선 방향 | registry가 download 정책을 만들 때 `safeExtension`이 기본 금지 목록에 있으면 거절한다. 정당한 경우를 위해 정책에 명시 플래그(예: `allowActiveExtension: true`)를 둔다. 문서 462행을 실제 범위에 맞게 고친다 | +| 대안 비교 | (가) 현상 유지 + 문서 수정: 비용 최소. 통제는 여전히 없다. (나) 금지 목록 + 명시 opt-in: 몇 줄. 실수는 막고 정당한 내보내기는 허용한다. (다) mediaType→확장자 표로 짝을 강제: 가장 엄격하지만 표 관리 비용이 크고 표에 없는 형식을 막는다 | +| 단순화의 보존 조건 | 사용자 이름 안의 금지 확장자 무력화(`invoice.exe.pdf` → `invoice_exe.pdf`)는 그대로다. browser-managed capability와 정책의 확장자 일치 검사도 그대로다 | +| 비용·부작용 | (나) 정책 타입에 선택 필드 하나. 기존 정책 중 금지 확장자를 쓰는 것이 있으면 조립이 실패한다(repo 안에는 없다) | +| 재검토 조건 | 제품이 확장자를 사용자에게 고르게 하거나, 서버가 `Content-Disposition`으로 이름을 확정하는 경로만 쓰게 되면 다시 본다 | +| 완료 기준 | `.exe` 정책이 명시 플래그 없이 registry 생성에서 실패한다. 문서 462행이 코드와 맞다 | +| 검증 방법 | E-7을 `browser-file-policy-registry.test.ts`에 옮겨 거절을 단언한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-03 stage된 후보를 재검증하다 읽기 오류가 나면 stage 결과와 관측이 `CACHE_ACTIVATE`로 기록된다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 23, 24 | +| 근거 | `verifyReleaseCandidate`는 실패 Result의 operation을 `CACHE_ACTIVATE`로 고정해 만든다(`src/adapters/cache-storage/public-response-cache-adapter.ts:1079-1098`). 활성화 경로는 `rebaseFailure`로 바꾼다(`:679-684`). stage의 재사용 경로는 바꾸지 않고 그대로 돌려준다(`:492-495`). 그 결과가 `observeFailure`로 관측된다(`:582-588`). E-6: stage 재호출 결과가 `{"code":"UNAVAILABLE","operation":"CACHE_ACTIVATE"}`이고 관측도 `operation:"CACHE_ACTIVATE"`다 | +| 발생 조건 | 이미 stage된 release를 다시 stage하고, 재검증 중 Cache API가 일시 오류를 낸다 | +| 영향 | 운영자가 관측에서 "활성화 실패"를 보지만 실제로는 stage 재시도가 실패했다. 호출자가 `error.operation`으로 분기하면 잘못된 경로를 탄다. 동작 자체(실패를 성공으로 바꾸지 않음, 후보를 지우지 않음)는 맞다 | +| 심각도·우선순위 | Low · P3 — 진단 정보만 틀린다 | +| 통제·증거 | M0(재사용 경로의 rebase 없음) · E2(E-6) | +| 확실성과 남은 가정 | 코드와 E-6으로 확정 | +| 결정의 근거 | 적용 제외 — 활성화 경로와 같은 rebase를 빠뜨린 단순 결함이라 선택 비교가 필요 없다 | +| 이해 비용 | 관측만 보는 사람은 Cache Storage를 직접 열기 전까지 원인을 잘못 짚는다 | +| 최소 개선 방향 | `:495`에서 `rebaseFailure(verified.failure.error, "CACHE_STAGE")`로 돌려준다. 또는 `verifyReleaseCandidate`가 operation을 인자로 받는다. `readAndValidateResponse`가 모든 실패를 `CACHE_STAGE`로 만드는 것(`public-cache-response-validation.ts:100`)도 같은 방식으로 정리한다 | +| 대안 비교 | 적용 제외 — 계약 위반을 바로잡는 단순 수정 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 한 줄과 테스트 1개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E-6 시나리오의 결과와 관측이 `CACHE_STAGE`다 | +| 검증 방법 | E-6을 `public-response-cache-repair.test.ts`에 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-04 이 영역의 보호 규칙 7개가 변이 실험에서 살아남는다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(테스트 공백) | +| 관련 관점 | 10, 15, 6, 12 | +| 근거 | E-3에서 아래 변이가 관련 unit 파일을 모두 통과했다. 지난 라운드부터 이어진 생존(M05·M10·M13·M14)은 각 발견(`0929/02-01`·`02-02`·`02-05`)에 이미 있어 여기서 세지 않는다. ① N29 object URL 합계 바이트 상한 삭제(`object-url-lease.ts:134-136`). ② N38 host가 `StorageEvent.storageArea`를 캡처한 localStorage와 비교하지 않음(`browser-cross-context-host.ts:289-295`). core 쪽 검사(M12)는 잡히지만 실제 분류를 하는 host는 unit·browser 테스트 어디에도 없다. ③ N27 재검사 때 이전 verification receipt를 무효화하지 않음(`browser-file-vault.ts:334`). ④ N26b `Cache-Control: no-cache` 응답 거절 삭제(`public-cache-response-validation.ts:57`). ⑤ N39 조회가 eviction 판정 전에 `keys()`를 다시 읽지 않음(`public-response-cache-adapter.ts:263-267`). ⑥ N30 browser-managed handoff의 fragment 거절 삭제(`download-input-validation.ts:348`). ⑦ N26 `Set-Cookie` 응답 거절 삭제(`public-cache-response-validation.ts:61-62`) | +| 발생 조건 | 리팩터링이나 단순화로 해당 줄이 빠진다 | +| 영향 | ① 탭 하나가 붙잡는 blob 메모리 상한이 사라져도 모른다. ② 같은 origin iframe의 sessionStorage 쓰기가 무효화 hint로 들어와도 모른다(영향은 불필요한 refetch). ③ 파일이 바뀐 뒤에도 옛 receipt로 preview를 만들 수 있다(브라우저는 바뀐 File 읽기를 보통 거부하므로 실제 노출은 작다). ④ 서버가 재검증을 요구한 응답을 release 캐시에 넣는다. ⑤ 다른 탭이 막 활성화한 release를 `STORAGE_EVICTED`로 잘못 보고한다. ⑥·⑦은 영향이 작다. ⑦은 브라우저 `fetch()`가 `Set-Cookie`를 응답 헤더에 노출하지 않아 원래 브라우저에서는 걸리지 않는 검사다. 실제 보호는 `credentials:"omit"`(`:232`, M08 검출)과 응답 헤더 allowlist(`public-cache-policy.ts:56-63`)다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. ①·②가 우선이다 | +| 통제·증거 | 각 규칙 M2 구현 · 검출 M3 없음 · E3(변이 생존) | +| 확실성과 남은 가정 | 변이 결과는 확정. 동등 변이 2건(N22, N36)은 생존이지만 동작이 같아 여기서 뺐다 | +| 결정의 근거 | 적용 제외 — 테스트를 더하는 문제 | +| 이해 비용 | 규칙을 고치는 사람은 테스트가 통과해도 보호가 남았는지 알 수 없다 | +| 최소 개선 방향 | 규칙마다 실패하는 테스트 하나. ① 개수는 남고 합계 바이트만 넘는 lease 생성이 `LIMIT_EXCEEDED`/`retryable:true`인지. ② host에 가짜 `storageArea`(sessionStorage 객체)로 같은 key·value 이벤트를 보내 무시되는지. ③ 재검사 뒤 옛 receipt로 preview가 `POLICY_REJECTED`인지. ④ `no-cache` 응답 stage가 `POLICY_REJECTED`인지(`public-response-cache-codec.test.ts:155` 옆). ⑤ 첫 `keys()` 뒤 활성화가 끼어드는 가짜 저장소. ⑦은 테스트를 더하거나, 브라우저에서는 걸리지 않는다는 주석을 남긴다 | +| 비용·부작용 | 테스트 6~7개 | +| 완료 기준 | N29·N38·N27·N26b·N39·N30이 실패한다 | +| 검증 방법 | `scratchpad/review02-mutate.mjs`의 같은 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 02-05 cross-context publish 실패는 원인과 상관없이 관측 reason이 `INVALID_ENVELOPE`다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(진단 정보) | +| 관련 관점 | 8, 24 | +| 근거 | `createEventId`가 던지면(`src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts:314-318`) 자기 envelope 검사 실패와 같은 `invalidPublish()`로 간다(`:336`). `invalidPublish()`는 항상 reason `INVALID_ENVELOPE`로 관측한다(`:367-375`). host의 `createEventId`는 secure random 실패 때 던진다(`browser-cross-context-host.ts:108-111`). reason 목록에는 `SECURE_RANDOM_UNAVAILABLE`, `TOPIC_REJECTED`가 이미 있다(`:38-55`, `contracts/cache-invalidation.ts:36-43`). bootstrap은 이 reason을 그대로 `cache.operation.failed` 진단에 싣는다(`src/bootstrap/runtime-adapters.ts:373-388`). E-8: random 실패와 topic version 불일치가 모두 `INVALID_ENVELOPE`로 남는다 | +| 발생 조건 | 부팅 뒤 secure random이 실패하거나, coordinator와 transport의 topic version이 어긋난다 | +| 영향 | 진단에서 "wire 형식 오류"로 보인다. 실제 원인(난수 실패, 버전 불일치)을 찾으려면 코드를 읽어야 한다 | +| 심각도·우선순위 | Low · P3 — 두 조건 모두 드물다. 동작(publish 거절)은 맞다 | +| 통제·증거 | M0(원인 구분 없음) · E2(E-8) | +| 확실성과 남은 가정 | 코드와 E-8로 확정 | +| 결정의 근거 | 적용 제외 — 이미 있는 reason 값을 쓰면 되는 단순 결함 | +| 이해 비용 | 운영자가 원인을 좁히려면 코드를 읽어야 한다 | +| 최소 개선 방향 | event ID 실패는 `SECURE_RANDOM_UNAVAILABLE`, parse 실패는 `parsed.reason`을 관측에 싣는다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E-8의 두 경우가 서로 다른 reason으로 관측된다 | +| 검증 방법 | E-8을 `cross-tab-invalidation.test.ts`에 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 검토 (41절) + +### 5.1 Cache Storage control pointer를 현재 정책으로 엄격하게 읽는다 (`0929/02-01`) + +지난 라운드 4.1절의 결론이 그대로다. 이번에 바뀐 근거만 적는다. + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 손상된 pointer로 검증 안 된 release를 서비스하지 않는다. 동시에 다음 배포가 활성화와 정리를 할 수 있어야 한다 | +| 2. 지킬 성질 | (a) 검증한 후보만 활성화 (b) manifest와 다른 바이트를 돌려주지 않음 (c) 읽을 수 있는 pointer가 가리키는 캐시는 지우지 않음 (d) 나쁜 pointer 하나가 이후 배포를 영구히 막지 않음 | +| 3. 현재 보장 | (a)~(c)는 보장한다. 이번 변이에서 N23(control 보존)·N24(repair 실패 시 기존 후보 보존)·N25(marker memo key)가 검출됐다. (d)는 보장하지 않는다(E-1a·E-1b) | +| 4. 대안 | (가) 현상 유지 (나) 활성화가 읽을 수 없는 이전 pointer를 "없음"으로 보고 덮어씀 (다) 읽을 때는 구조만, 정책 조건은 쓸 때 적용(쓰기는 이미 `slice(0, retained)`, `public-response-cache-adapter.ts:703-716`) (라) control 삭제 admin API | +| 5. 비교 | (나)+(다)가 (a)~(c)를 잃지 않고 (d)를 되찾는 가장 작은 변경이다. (라)는 포트가 늘고 호출 시점을 호출자가 알아야 한다 | +| 6. 선택 | (나)+(다). 지금 구현의 fail-closed는 무결성 쪽으로는 맞다. 진행성을 대가로 치른다 | +| 7. 재검토 조건 | Service Worker가 요청마다 이 조회를 쓰고 구버전 탭 drain 동안 rollback 캐시를 계속 서비스해야 하면(VD-15) 덮어쓰기 뒤 cleanup이 그 탭의 캐시를 지울 수 있다. 그때 (라)나 drain을 아는 보존 규칙을 비교한다 | + +구분: 현재 동작은 E-1로 확인했다. 작성 의도 기록은 찾지 못했다. 비용은 리뷰어 추정이다. + +### 5.2 lease registry 하나를 preview와 download가 같이 쓰고, 양쪽 모두 registry 전체를 dispose할 수 있다 (02-01) + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | blob URL은 revoke 전까지 Blob을 메모리에 붙잡는다. 탭 하나가 붙잡는 양에 상한이 필요하다. 로그아웃에서는 모든 URL을 한 번에 끊어야 한다 | +| 2. 지킬 성질 | 활성 URL 수·합계 바이트 ≤ 상한. lease마다 revoke 정확히 한 번. runtime dispose는 전부 revoke. **한 소비자의 정리가 다른 소비자의 lease를 끊지 않음** | +| 3. 현재 보장 | 앞의 셋은 보장한다(runtime dispose 테스트, 소진 retryable 테스트). 합계 바이트 상한은 구현돼 있지만 테스트가 없다(N29). 마지막 성질은 보장하지 않는다. preview·download 각각의 `dispose()`가 같은 registry의 `dispose()`를 부른다(`object-url-lease.ts:344`, `download-delivery-adapter.ts:391`). E-9 | +| 4. 대안 | (가) 현상 유지 (나) 예산은 공유, 해제는 소비자별(각자 만든 lease만 release, registry dispose는 runtime만) (다) 소비자별 registry 분리 (라) 포트에서 preview `dispose()` 제거 | +| 5. 비교 | (가) 비용 0. 함정이 남는다. (나) Set 하나. 예산의 의미(탭 전체 메모리)와 해제 범위가 둘 다 맞는다. (다) 해제 범위는 맞지만 합계 상한이 두 곳으로 갈라진다. 같은 메모리 보호를 하려면 상한을 나눠 설정해야 한다. (라) 가장 단순하지만 포트 변경이다 | +| 6. 선택 | (나). 지난 라운드의 "한 예산" 결론은 유지한다. 해제 권한만 좁힌다. (라)를 함께 하면 포트가 더 정직해진다 | +| 7. 재검토 조건 | preview와 download의 수명이 다른 runtime으로 나뉘면 (다)를 다시 본다. 관측에서 `PREVIEW`/`DOWNLOAD`의 `LIMIT_EXCEEDED`가 자주 보이면 소비자별 몫을 다시 본다 | + +구분: 확인한 사실은 E-9와 코드다. registry 주석의 "route/runtime teardown"은 기록된 의도다. route teardown에서 preview를 영구히 끄려는 의도였다는 기록은 없다(리뷰어 추론: 의도하지 않은 효과). + +### 5.3 download 파일 확장자는 조립 정책이 정하고, 템플릿은 형식만 본다 (02-02) + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 사용자가 받은 파일 이름이 실행 확장자나 active content 확장자로 위장되지 않아야 한다. 정당한 내보내기 형식은 허용해야 한다 | +| 2. 지킬 성질 | 사용자 입력 이름은 신뢰하지 않는다. 최종 확장자는 정책이 정한다. 정책이 실수로 위험한 확장자를 정하면 조립 시점에 드러나야 한다 | +| 3. 현재 보장 | 앞의 둘은 보장한다(`file-policy.ts:337-375`, N31 검출). 셋째는 보장하지 않는다(E-7) | +| 4. 대안 | (가) 현상 유지 + 문서 정정 (나) 금지 목록 + 명시 opt-in (다) mediaType→확장자 표 강제 | +| 5. 비교 | (가) 통제 없음. (나) 실수는 막고 opt-in으로 정당한 형식을 허용한다. preview의 "바닥값 + 추가만 허용" 방식과도 맞는다. (다) 표 관리 비용이 크고 표에 없는 형식을 막는다 | +| 6. 선택 | (나). 정책은 신뢰 영역이지만, 템플릿은 다른 조립 실수(잘못된 cache 정책 조합 등)를 이미 조립 시점 `TypeError`로 막는다(`public-cache-policy.ts:110-150`). 같은 기준을 적용한다 | +| 7. 재검토 조건 | 서버 `Content-Disposition`만 쓰는 구조로 바뀌면 클라이언트 쪽 검사는 줄여도 된다 | + +## 6. 리팩토링 후보 + +| 대상 | 무엇을 왜 | 보존해야 할 동작·타입·실패 계약 | 판정 | +| --- | --- | --- | --- | +| `BrowserTransientPreview.dispose()`와 download `dispose()` | 해제 범위를 자기 lease로 좁힌다(02-01) | runtime `dispose()`가 모든 lease를 즉시 revoke. lease `release()` 멱등. 소진 `LIMIT_EXCEEDED`/`retryable:true`. dispose 뒤 `UNAVAILABLE` | 바꾼다 | +| `isActivePointer` | 구조 검사와 정책 적용을 나눈다(`0929/02-01`) | 검증 안 된 후보 미활성화. 읽을 수 있는 pointer의 캐시 보존. 조회는 digest가 맞는 바이트만 | 바꾼다 | +| `verifyReleaseCandidate`·`readAndValidateResponse`의 operation 고정 | operation을 인자로 받거나 호출부가 rebase(02-03) | `UNKNOWN`은 성공도 삭제도 아님. `ABORTED`와 일시 오류 구분 | 바꾼다 | +| cross-context 채널 타입 | `src/contracts/cache-invalidation.ts`로 옮기고 파일 단위 예외 삭제(`0929/02-06`) | query-cache가 `subscribe`·`publish`·`close`와 delivery의 `ordering`·`transport`를 그대로 씀. bootstrap 조립 코드 무변경. 세대마다 새 transport | 소유자 결정 | +| `download-delivery-adapter.ts`(1,157줄) 전략별 파일 분리 | 파일 길이를 줄이는 안 | 세 전략이 `raceOwner`·`abortableFileChunks`·source holder·`observeResult`를 공유한다. 각 전략은 이미 명시적 context를 받는 별도 함수다. 분리하면 공유 helper 모듈이 하나 늘고 읽는 경로는 그대로다(39.7) | **유지** | +| `public-response-cache-adapter.ts`(1,185줄) | 연산별 분리 안 | 다섯 연산이 같은 `policy`·의존성 snapshot·lookup marker 메모를 공유한다. codec·policy·response 검증은 이미 분리돼 있다 | **유지** | +| `"Moved verbatim out of the adapter"` 주석 3곳 | 변경 이력이라 코드에 둘 이유가 없다(39.2) | 없음(주석) | 지운다(P3) | + +## 7. 추가 렌즈 + +### 7.1 성능 + +| 항목 | 숫자·근거 | +| --- | --- | +| 번들(미조립 레시피, gzip) | `measureOptionalRecipeBundle`(check:optional-recipes와 같은 함수, tree-shaking 끔)로 측정. service-worker-pwa 레시피 소스 9파일 **9,662 / 10,000 bytes(남은 여유 338, 3.4%)**. cache-storage 폴더만 8,744. browser-files 폴더만 14,792(file-transfer 레시피 예산 55,700은 browser-transfer와 같이 쓴다). cross-context 폴더(기본 번들, import 포함) 4,851. 실행 직전 부하 16.22. service-worker-pwa는 여유가 338바이트라 `0929/02-01`·02-03을 고치며 코드가 늘면 예산을 넘을 수 있다 | +| cache 조회 1회 | `keys()` 1회(활성 후보가 목록에 없으면 1회 더), pointer JSON 읽기 1회, marker는 활성 후보당 1회 메모(`public-response-cache-adapter.ts:280-319`), 본문 읽기 1회 + SHA-256 1회, 본문 복사 2회(검증 버퍼 + stream마다 사본 `:1032-1043`) | +| `inspect()` | 소유 후보 수 × 후보의 모든 entry 읽기·해시. 후보 하나는 최대 128 MiB(`public-cache-policy.ts:51`). 취소 불가(`0929/02-02`) | +| `cleanupOwned()` | `keys()` 1회 + 소유 캐시마다 `delete()` 1회. cursor·deadline 없음(문서 `browser-file-and-origin-storage.md:974-978`가 인정) | +| bounded download 메모리 | chunk마다 `slice()` 사본을 모은 뒤(`download-delivery-adapter.ts:796-797`) `new Blob(chunks)`를 만든다(`:826`). Blob 생성 시점에 최대 약 2× `maxBufferedBytes`가 잠시 살아 있다. 상한은 조립값(`hardMaxObjectUrlBytes`)이다 | +| object URL lease | 기본 16개, 합계는 단일 상한의 4배(`create-browser-file-runtime.ts:202-222`). 합계 상한은 테스트가 없다(02-04 ①) | +| cross-context | 이벤트마다 `pruneTracking`이 dedupe 맵 전체를 돈다(최대 1,024, 상한 4,096). source watermark 256(상한 1,024) LRU(`browser-cross-context-invalidation.ts:160-166`, `:556-560`) | +| 테스트 실행 시간 | 영역 unit 12파일 152건 1.39초(부하 8.25). 영역 browser spec 3엔진 21건 + E-2 3건 11.5초(부하 14.73). 변이 25건 39.7초(부하 13.5). 과하지 않다 | + +### 7.2 폴더 구조 + +- 세 폴더 안의 파일 이름은 책임과 맞다. cache-storage는 codec·policy·response 검증·adapter로, cross-context는 host(네이티브 캡처)와 core(프로토콜)로 나뉜다. 찾기 쉽다. +- browser-files의 `file-policy.ts`는 선택·검사 규칙 검증과 **파일명 정리**(`sanitizeSuggestedFileName`)를 같이 둔다. `browser-file-policy-registry.ts`와 이름이 겹친다. 파일명 정리를 찾는 사람은 "policy"에서 찾기 어렵다. 영향은 작다(개선 후보, 별도 발견으로 세지 않음). +- 포트 폴더 이름(`src/application/ports/browser-file-storage/`)과 어댑터 폴더 이름(`browser-files`, `cache-storage`)이 다르다. 어댑터에서 포트로 가려면 import 경로를 따라가야 한다. +- 이 영역이 쓰는 kernel `result.ts`는 구체 어댑터 `storage-manager-adapter.ts`와 같은 폴더(`src/adapters/browser-file-storage/`)에 있다. 영역 05 판단으로 넘긴다(>). +- 테스트가 배럴 대신 내부 파일을 직접 import한다(`tests/unit/browser-file-download.test.ts:11-20` 등). 배럴이 공개 경계라는 전제와 다르지만 테스트 범위라 결함으로 세지 않았다. + +### 7.3 테스트가 위험을 잡는가 + +- 잡는 것: preview resolve 뒤 abort(M01), 익명 stage 요청(M08), 역순·중복(M11), core `storageArea`(M12), close 때 listener 제거(N20), cleanup의 control 보존(N23), repair 실패 시 기존 후보 보존(N24), lookup marker 메모 key(N25), 파일명 bidi 제거(N31), native cancel 뒤 focus fallback 미설치(N32), download user activation(N33), content-type 헤더 보존 정책(N37). +- 못 잡는 것: 8.3절 생존 11건. 지난 라운드의 4건은 각 발견에, 새 7건은 02-04에 묶었다. +- 실행 시간은 1.4초대라 줄일 필요가 없다. + +## 8. 28개 관점 판정표 (36.2) + +### 8.1 판정 + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 근거와 잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| **1** | 코드 성숙도 | P | M2 / M2 | E2, E3 | lease 상한, 같은 턴 abort, "검증 뒤에만 성공"은 코드와 테스트로 지켜진다(M01·N24·N25 검출). pointer를 현재 정책으로 판단한다(`0929/02-01`). stage 재사용 경로가 rebase를 빠뜨렸다(02-03) | +| 2 | 구조적 성숙도 | P | M3 / M3 | E3(E-4) | 내부 파일 import는 게이트가 막는다(P0). 배럴 예외는 런타임 팩토리까지 연다(P1, `0929/02-06`) | +| 3 | 변경 용이성 | O | M2 / M2 | E1 | 새 파일 정책은 profile 추가, 새 topic은 registry 추가다. 이번 라운드는 변경 드릴을 다시 돌리지 않았다 | +| 4 | 인지 부하 | P | — / — | E1 | 1.1k줄대 파일 2개(`download-delivery-adapter.ts` 1,157, `public-response-cache-adapter.ts` 1,185). 리뷰 ID 주석 34곳, 대부분 이유 문장이 붙어 있다. 변경 이력 주석 3곳 | +| **5** | 위험 가시성 | P | M1~M2 / M1~M2 | E2, E3 | `BROWSER_HANDOFF`/`SAVED`/`DISMISSED`, `retryable` 구분은 읽힌다. `REHYDRATE`가 pointer 실패에서 지킬 수 없는 복구를 안내한다(`0929/02-01`). `previews.dispose()`의 runtime 전체 효과가 포트에 없다(02-01). `inspect()` 비용(`0929/02-02`). 브라우저에서 걸리지 않는 `Set-Cookie` 검사가 실제 보호처럼 보인다(02-04 ⑦) | +| **6** | 실패 성숙도 | P | M2 / M2 | E2, E3 | 취소·닫기·권한·소진·무결성을 Result로 나눈다. pointer 한 번 실패로 활성화·정리가 영구히 멈춘다(`0929/02-01`). handoff 실패 lease 반환이 테스트 밖이다(`0929/02-05`) | +| 7 | 운영 성숙도 | P | M2 / M2 | E1 | cross-context 실패는 bootstrap이 진단으로 연결한다(`runtime-adapters.ts:373-388`). file·cache observer는 레시피 조립 몫이라 repo에서 연결되지 않는다 | +| 8 | 디버깅 가능성 | P | M2 / M2 | E2 | 관측에 파일명·URL·키가 없다. pointer 손상과 marker 손상이 같은 `CORRUPT_DATA`다. stage 실패가 `CACHE_ACTIVATE`로 남는다(02-03). publish 실패 reason이 하나로 뭉친다(02-05) | +| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | CHANGELOG 행(`0929/02-03`), 문서 줄 번호(`0929/02-04`)가 그대로다 | +| 10 | 테스트 성숙도 | P | M3 / M3 | E2(unit 152 통과), E3(browser 21 통과, 변이 25) | 검출 12. 생존 11(지난 4 + 새 7, 02-04). 동등 2 | +| **11** | 데이터 성숙도 | P | M2 / M1 | E3(E-2), E2(E-1) | Cache Storage에는 익명 공개 응답만 들어간다(M08). pointer는 `schemaVersion:1`만 있고 정책이 바뀐 배포에서 읽는 규칙이 없다(`0929/02-01`). prefix를 바꾸면 옛 캐시가 남는다(문서화된 제한) | +| **12** | 동시성 성숙도 | O | M3 / M3 | E2, E3 | 탭 간 역순·중복(M11), Web Lock 직렬화, picker별 pending, owner race. 조회의 `keys()` 재확인(N39)은 테스트가 없다(02-04) | +| 13 | 확장성 | O | M2 / M2 | E1 | source 256·dedupe 1,024 LRU, 정책 profile 128개, entry·바이트 상한. 부하 목표 없음 | +| 14 | 성능 성숙도 | P | M2 / M2 | E1, E2, E3(번들 측정) | 조회는 `keys()` 1회와 본문 복사 2회. `inspect()`는 무제한이다(`0929/02-02`). bounded download는 Blob 생성 때 약 2× 버퍼. service-worker-pwa 번들 9,662 / 10,000 gzip bytes로 여유 338바이트 | +| **15** | 보안 성숙도 | P | M2~M3 / M2~M3 | E2, E3 | 익명 stage(M08), 파일명 무력화(N31), user activation(N33), 서명 기반 MIME, canonical handoff URL. 정책 확장자는 금지 목록 밖이다(02-02). host의 `storageArea` 비교가 테스트 밖이다(02-04 ②) | +| 16 | 의존성 성숙도 | - | — | E1 | 세 폴더 모두 외부 패키지 import가 0건이다 | +| 17 | API / Contract 성숙도 | P | M2 / M2 | E1, E2 | 포트 타입과 wire 계약은 닫혀 있다. CHANGELOG 행이 틀렸다(`0929/02-03`). `TransientPreviewPort.dispose()`의 범위가 정의돼 있지 않다(02-01). `inspect().verified` 뜻이 모호하다(`0929/02-02`) | +| 18 | 배포 성숙도 | P | M2 / M0(정책 변경 호환) | E3(E-2), E2(E-1) | 정책 값을 바꾼 배포 하나가 이후 모든 배포의 캐시 활성화를 막는다(`0929/02-01`) | +| 19 | 설정 성숙도 | P | M3 / M3 | E2 | 잘못된 상한·정책 조합은 조립 시 `TypeError`다(N37 검출). 허용 범위 안의 `retainedPreviousReleaseCount` 감소가 런타임을 멈춘다(`0929/02-01`). 위험한 `safeExtension`이 통과한다(02-02) | +| 20 | 개발자 경험 | > | — | — | 영역 14 | +| 21 | Guardrail 성숙도 | P | M3 / M3 | E3(E-4) | kernel 예외는 게이트가 강제하지만 쓰임보다 넓다(`0929/02-06`). 문서 줄 번호는 어떤 검사도 보지 않는다(`0929/02-04`). 정책 확장자 검사가 없다(02-02) | +| 22 | 추상화 성숙도 | P | — / — | E1, E2 | 네이티브 API를 조립 시 bind·snapshot하는 facade는 목적이 분명하다. 공유 registry의 해제 권한이 포트마다 열려 있다(02-01). concrete transport를 "kernel"로 부른다(`0929/02-06`) | +| 23 | 일관성 | P | — / — | E1 | 같은 `QUOTA_EXCEEDED`가 경로에 따라 `READ_ONLY`(`result.ts:80-85`)와 `ONLINE_ONLY`(`public-cache-codec.ts:592-598`)로 갈린다. stage가 `read.error`를 code만 남기고 다시 만들어 `NOT_READABLE`의 `REOPEN`을 잃는다(`public-response-cache-adapter.ts:529`). preview는 active content 바닥값이 있고 download 확장자는 없다(02-02) | +| **24** | 네이밍 / 의미 | P | M2 / M2 | E1, E2 | `inspect().verified`가 판정 불가를 `false`로 합친다(`0929/02-02`). `REHYDRATE`가 pointer 실패에서 약속을 못 지킨다(`0929/02-01`). `previews.dispose()`가 이름보다 넓게 작동한다(02-01). topic이 0개라 transport를 만들지 않은 빌드도 `DEGRADED_LOCAL_ONLY`로 보고한다(`runtime-adapters.ts:401-402`). download 조립 오류 메시지가 모든 설정 오류에 "timing policy"라고 한다(`download-delivery-adapter.ts:202`) | +| 25 | 조직 확장성 | - | — | — | 1인 관리. 팀 경계 검증 대상 없음 | +| 26 | Ownership | > | — | — | 영역 12. kernel 규칙 주석에 담당은 있고 재검토 조건은 없다(`0929/02-06`) | +| 27 | 삭제 가능성 | ? | M3 / 미확인 | E1 | 제거 드릴(`scripts/test-browser-file-storage-runtime-removal.ts:24-36`)이 browser-files·cache-storage를 포함한다. 이번에는 pnpm 전용 스크립트라 돌리지 않았다 | +| **28** | 회복 가능성 | X | 목표 M2 / 확인 M0(cache pointer) | E3(E-2), E2(E-1) | cross-context는 GAP·세대 교체로, browser-files는 dispose로 회복한다. cache-storage는 pointer가 한 번 읽히지 않으면 어댑터 API로 회복할 수 없다(`0929/02-01`). 범위는 opt-in cache-storage 한정이다 | + +집계(이 영역에서 판정한 24개): O 3(3, 12, 13) · P 19 · X 1(28) · ? 1(27). 적용 제외 2(16, 25) · 다른 영역 2(20, 26). + +### 8.2 발견 색인 + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 | +| --- | --- | --- | --- | --- | --- | +| 02-01 | Medium | P2 | 구조적 위험 | 5, 22, 24, 6, 17 | `previews.dispose()`가 공유 lease registry 전체를 비운다 | +| 02-02 | Low | P3 | 구조적 위험 | 15, 5, 21, 23 | download 정책의 `safeExtension`은 금지 목록도 media type도 검사하지 않는다 | +| 02-03 | Low | P3 | 확인된 결함 | 8, 23, 24 | stage 재검증 실패가 `CACHE_ACTIVATE`로 기록된다 | +| 02-04 | Low | P3 | 구조적 위험(테스트 공백) | 10, 15, 6, 12 | 보호 규칙 7개가 변이 실험에서 살아남는다 | +| 02-05 | Low | P3 | 확인된 결함 | 8, 24 | cross-context publish 실패 reason이 `INVALID_ENVELOPE` 하나다 | +| `0929/02-01` | Medium | P2 | 확인된 결함 | 28, 11, 18, 6, 19, 5, 24, 1 | Cache Storage pointer를 현재 정책으로 검증해 영구히 멈춘다(남음) | +| `0929/02-02` | Low | P3 | 구조적 위험 | 5, 14, 24, 10 | `inspect()`의 비용·취소·판정 불가(남음) | +| `0929/02-03` | Low | P3 | 확인된 결함 | 17, 9 | CHANGELOG 0.2.0 행 경로(남음) | +| `0929/02-04` | Low | P3 | 확인된 결함 | 9, 21 | 설계 문서 줄 번호 drift(남음) | +| `0929/02-05` | Low | P3 | 구조적 위험 | 10, 6, 14 | handoff 실패 lease 반환 테스트 공백(남음) | +| `0929/02-06` | Low | P3 | 개선 제안 | 2, 21, 22, 5, 26 | kernel 예외가 쓰임보다 넓다(남음, 결정 필요) | + +### 8.3 변이 실험 결과 (E-3) + +| ID | 바꾼 규칙 | 결과 | 연결 | +| --- | --- | --- | --- | +| M05 | `inspect()`의 판정 불가를 `verified:true`로 | 생존 | `0929/02-02` | +| M10 | bounded download catch의 `lease?.release()` 삭제 | 생존 | `0929/02-05` | +| M13 | pointer rollback 목록 길이 검사 삭제 | 생존 | `0929/02-01` | +| M14 | 활성화가 이전 pointer 실패를 무시 | 생존 | `0929/02-01` | +| M01 | preview가 resolve 뒤 abort를 다시 보지 않음 | 검출 | — | +| M08 | stage 요청 `credentials:"include"` | 검출 | — | +| M11 | cross-tab STALE 검사 삭제 | 검출 | — | +| M12 | core `storageArea` 검사 삭제 | 검출 | — | +| N20 | close에서 storage listener 제거 생략 | 검출 | — | +| N22 | broadcast publish 실패 뒤 `refreshStatus()` 삭제 | 생존(동등: 뒤따르는 storage 경로가 status를 다시 정한다) | — | +| N23 | cleanup이 control cache를 보존하지 않음 | 검출 | — | +| N24 | repair 실패 시 기존 후보도 삭제 | 검출 | — | +| N25 | lookup marker 메모의 key 비교 삭제 | 검출 | — | +| N26 | `Set-Cookie` 응답 거절 삭제 | 생존 | 02-04 ⑦ | +| N26b | `Cache-Control: no-cache` 거절 삭제 | 생존 | 02-04 ④ | +| N27 | 재검사 때 이전 receipt 무효화 삭제 | 생존 | 02-04 ③ | +| N29 | object URL 합계 바이트 상한 삭제 | 생존 | 02-04 ① | +| N30 | browser-managed handoff의 fragment 거절 삭제 | 생존 | 02-04 ⑥ | +| N31 | 파일명 bidi override 제거 삭제 | 검출 | — | +| N32 | native cancel을 본 뒤에도 focus fallback 설치 | 검출 | — | +| N33 | download user activation 검사 삭제 | 검출 | — | +| N36 | lease 해제 시 합계 차감 조건 삭제 | 생존(동등: `released` 가드 때문에 `delete()`는 항상 true) | — | +| N37 | cache 정책이 content-type 헤더 제거를 허용 | 검출 | — | +| N38 | host가 `storageArea` 동일성 비교 생략 | 생존 | 02-04 ② | +| N39 | 조회가 eviction 판정 전 `keys()`를 다시 읽지 않음 | 생존 | 02-04 ⑤ | + +## 9. 미검증 목록 + +| 항목 | 왜 확인하지 못했나 | 확인하려면 | +| --- | --- | --- | +| grace 중 blob URL revoke가 실제 브라우저 download를 끊는지(02-01) | Playwright는 다운로드 완료 시점을 보지 않는다 | 엔진별로 큰 Blob download 직후 revoke하고 저장 파일 크기 비교 | +| 다른 탭에서 계정이 바뀐 뒤 받은 무효화 hint가 이전 세대 캐시를 채우는지 | 탭 간 세션 변경은 auth 영역이고 조립된 2탭 E2E가 없다(`client-cache-and-storage.md:79-80`도 인정) | 탭 A 로그아웃·B 로그인 → B mutation → A 상태를 보는 2탭 E2E | +| Safari의 30초 grace 충분성 | 실제 다운로드 완료를 보지 않는다 | WebKit 실기 | +| `0929/02-01` 상태에서 쌓인 캐시가 origin 한도에 닿을 때 IndexedDB·OPFS 쓰기 영향 | 한도까지 채우는 실험을 하지 않았다 | 작은 quota 프로필에서 반복 stage | +| 제거 드릴 | pnpm 전용 스크립트, worktree에서 pnpm 금지 | 메인 repo에서 `corepack pnpm test:browser-file-storage-removal`(오케스트레이터 판단) | +| 이 영역 관측이 제품 telemetry로 이어지는지 | file·cache observer를 조립한 코드가 repo에 없다 | 레시피를 조립한 제품에서 확인 | diff --git a/docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md b/docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md new file mode 100644 index 00000000..a20dc705 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md @@ -0,0 +1,405 @@ +# 03 HTTP·서버 상태·인증·진단 — 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `src/adapters/http/`, `src/adapters/browser-rpc/`, `src/adapters/query-cache/`, `src/adapters/auth/`, `src/adapters/diagnostics/`, `src/adapters/telemetry/`. 흐름 확인용으로 `src/bootstrap/runtime-adapters.ts`, `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/contracts/server-state.ts`, 참조 기능 +> 깊게 본 관점: 5, 6, 8, 12, 15, 17, 22 · 이번 라운드 렌즈: 기능 개발자가 HTTP 연결을 만들 때 실수하기 쉬운 지점(멱등 키, 오류 분류, 캐시 무효화)이 코드·타입에서 드러나는가 +> 영역 판정(35.8): **조건부 사용 가능.** 조회 경로, 인증 세대 fence, 자격증명 경계, 전송 상한은 그대로 복제해도 된다. 결과 불명 쓰기 샘플은 P-03-01을 고치기 전까지 "처리 중"에 409를 주는 백엔드와 함께 복제하지 않는다. 새 기능을 붙일 때는 조회 namespace(03-01)와 mutation 정책(03-03)을 손으로 맞춰야 하며, 틀려도 조용하거나 "입력 거절"로만 보인다(03-02). + +ID 표기: `03-NN`은 이번(2026-11-01) 라운드 발견이다. 2026-09-29 라운드 발견은 `P-03-NN`으로 적는다. + +## 0. 결론 + +- **지난 발견 6건은 모두 남았다.** `af3d8e6..d99301b` 사이에 이 영역과 흐름 파일(`src/adapters`, `src/presentation/adapters`, `src/presentation/forms`, `src/features`, `src/contracts`, `src/bootstrap`, 관련 문서·설정)의 변경은 0줄이다(`git diff --stat`). P-03-01(High)은 이 커밋에서 다시 재현했다. 키가 `[K, K, K′]`였다(실험 E1). +- **조회 namespace가 무효화 레지스트리와 연결되지 않는다(03-01, Medium).** `bindQuery`는 아무 문자열이나 namespace로 받는다. 문서는 "namespace는 레지스트리 참조"라고 적는다. 오타 하나면 저장 뒤 목록이 갱신되지 않고, 오류도 진단도 없다(E7). 참조 기능은 화면 테스트가 잡지만(변이 M20) 새 기능에는 일반 검사가 없다. +- **연결 실수가 "입력 거절"로 보인다(03-02, Low).** 경로 placeholder 불일치, 미설치 계약, 멱등 키 배선 오류가 모두 전송 전에 막힌다. 안전하다. 하지만 사용자에게는 "입력값을 다시 확인해 주세요"가 뜨고, 진단에는 구체 원인이 없다. 미설치 계약은 진단을 하나도 남기지 않는다(E6). +- **mutation 정책이 계약을 다시 손으로 적는다(03-03, Low).** `operationId`와 `requiresIdempotencyKey`를 계약과 따로 쓴다. 틀리면 첫 저장에서 막히지만, 03-02 때문에 원인이 잘 안 보인다. P-03-03(키 없는 재전송)이 고쳐지지 않는 구조적 이유도 여기 있다. +- **효과 판정과 화면 분류가 두 함수로 나뉜다(03-04, Low).** 계약의 `classifyProblem`이 `MAYBE_APPLIED`, 바인딩의 분류가 `VALIDATION_REJECTED`면 화면이 "입력 오류"와 "결과를 확인할 수 없습니다"를 동시에 띄운다(E8). +- **분류기 실패를 기록한다는 주장이 사실이 아니다(03-05, Low).** 분류기가 throw해도 관측 기록이 정상 `MAYBE_APPLIED`와 같다(E5). 그 안전 기본값을 `NOT_APPLIED`로 바꿔도 테스트가 모른다(변이 M5). +- **변이 21개 중 13개가 검출됐다.** 생존 8개 중 4개는 같은 보호가 다른 곳에 있는 동등 변이다. 진짜 빈틈은 넷이다: P-03-06(M1), 03-05(M5), 03-06(M7·M8). +- **잘 된 점.** 설치 검사가 쓰기 계약의 빈칸을 막는다(`external-contract-runtime.ts:468-513`). 실행기는 결과 union으로 실패 종류와 효과를 구분한다. 세대 fence, 자격증명 프로필, 전송 상한은 변이 실험에서 대부분 검출됐다(1.2절). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `d99301b`. 메인 작업 트리 미커밋은 `.claude/`뿐이다 | +| 목적·실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음. 인증 `demo`/`external`. 기본 설정의 API는 다른 origin이다(`config/runtime/production.json:3`) | +| 줄 단위로 읽은 코드 | `http-execution-v3.ts` 전체, `feature-http-binding.ts` 전체, `http-contract-bridge.ts` 전체, `http-effect-certainty.ts`, `http-retry-lifecycle.ts`, `retry-policy.ts`, `bounded-json.ts`, `platform-error-mapping.ts`, `client.ts` 1~170행과 함수 목록, `query-cache/server-state-scope-runtime.ts`·`tanstack-cache-coordinator.ts`, `auth/external-session-adapter.ts`, `diagnostics/bounded-diagnostics.ts`, `telemetry/telemetry-collector.ts`, `best-effort-telemetry.ts` 185~230행, `browser-rpc-runtime.ts` 함수 목록과 1505~1545행, 영역 배럴 6개 | +| 흐름 확인용으로 읽은 코드 | `runtime-adapters.ts` 60~120·180~340·480~600행, `application-query.ts` 180~770행, `use-app-form.ts` 180~330행, `server-state.ts`, `query-keys.ts` 40~83행, `errors.ts` 247~257행, `form-contracts.ts` 56~85행, `external-contract-runtime.ts` 100~200·440~513행, 참조 기능 `contracts/`·`adapters/`·`presentation/use-reference-feature.ts`, `installed-feature-contracts.ts` | +| 읽은 문서(주장) | `docs/architecture/backend-api-and-server-state-contract.md` §5·§6·16.1, `docs/architecture/client-cache-and-storage.md` 440~470행, `docs/architecture/2026-07-30-…-closed-deep-design.md` 640~655행, `docs/architecture/typescript-state-and-data-flow.md` 300~345행, `docs/runbooks/FE-RB-003.md`, `src/features/reference-feature/README.md`, 지난 라운드 03 문서·README | +| 게이트 결과 | 오케스트레이터가 이 커밋에서 실행한 결과를 읽었다(`scratchpad/gates/`). 이 영역과 관련된 `check:architecture`, `check:types`, `lint`, `test:unit`(2,353), `test:integration`(155), `test:component`(211), `test:contract`(15)는 모두 rc=0. `test:system` rc=1은 CI runner 테스트 2건(영역 11) | +| 실험 환경 | 격리 worktree `scratchpad/wt-03`, `wt-03b`(`d99301b`, 메인 `node_modules` 심볼릭 링크). worktree 안에서 pnpm을 부르지 않았다. 실험 파일은 `scratchpad/r03/experiments/`, 변이 스크립트와 결과는 `scratchpad/r03/run-mutations.mjs`·`mutation-results.txt`. 끝난 뒤 두 worktree를 `git worktree remove --force`로 지웠다 | +| 확인하지 못한 범위 | 실제 백엔드와의 통합, 두 제품의 운영 CORS 값, 여러 탭, Browser RPC 실제 provider, 실제 브라우저에서의 화면(E1·E8은 jsdom). 9절에 이유를 적었다 | +| 이전 리뷰와 비교 | 코드가 같으므로 지난 발견 위치가 같은 줄에 있다. 지난 실행 결과는 증거로 쓰지 않고 이번에 다시 실행했다 | + +### 1.1 실험 + +| ID | 무엇 | 결과 | +|---|---|---| +| E1 | (P-03-01) 수직 테스트 harness(실제 `createRuntimeComposition` + MSW)에서 저장 → 504 → "같은 요청으로 다시 보내기" → 409(`code: IDEMPOTENT_IN_FLIGHT`, problem+json) → 저장 → 201 | 키 `[K, K, K′]`. 409 뒤 화면 문구: "충돌을 해결한 뒤 다시 제출할 수 있습니다." / "다른 변경과 충돌했습니다…" | +| E1-fix | E1과 같은 순서. 참조 분류기에서 409를 `NOT_APPLIED` 목록에서만 뺐다(`wt-03b`) | 키 `[K, K, K]`. 409 뒤 화면은 "변경 결과를 확인할 수 없습니다."를 유지한다. `tests/features/reference-feature` 16 files / 70 tests는 통과했지만, 통합 시나리오 카탈로그는 이 변경을 잡는다(1.2절 M21) | +| E2 | (P-03-03) `requiresIdempotencyKey: false`인 bound mutation이 `MAYBE_APPLIED`로 끝난 뒤 `resendUnknownEffect()` 호출 | `execute` 2회, `resendUnknownEffect` 반환값이 `null`이 아니다, 두 intent 모두 키 없음 | +| E3 | (P-03-05) 실행기 시계를 시도별 `budget = remaining()` 읽기 직후 마감 뒤로 옮긴다 | fetch 0회. 결과 `CONTRACT_VIOLATION`/`FINAL_REQUEST_INVARIANT_FAILED`, 바인딩 결과 `VALIDATION_REJECTED`(`action: none`) | +| E5 | (03-05) KEYED 계약의 `classifyProblem`이 `MAYBE_APPLIED`를 돌려줄 때와 throw할 때, 409 응답의 관측 기록을 비교 | `correlationId`(요청마다 새 UUID) 말고 모든 필드가 같다: `outcome PROBLEM`, `errorKind PROBLEM`, `effect MAYBE_APPLIED`, `terminalReason MAYBE_APPLIED` | +| E6a | (03-02, 03-03) KEYED 계약에 키 없는 intent, `operationId` 오타 intent를 넘긴다 | 둘 다 fetch 0회, `VALIDATION_REJECTED` / `code MISSING_IDEMPOTENCY_KEY`, `effect NOT_STARTED`. 관측 `errorKind`는 `MISSING_IDEMPOTENCY_KEY` | +| E6c | (03-02) 경로 `{id}`, `projectRequest`는 `entityId`를 주는 조회 계약 | fetch 0회. `CONTRACT_VIOLATION`/`FINAL_REQUEST_INVARIANT_FAILED`. 관측 `errorKind FINAL_REQUEST_INVARIANT_FAILED`, `terminalReason NOT_STARTED`. `PATH_PLACEHOLDER_MISSING`이라는 원인은 어디에도 없다 | +| E6b | (03-02) 설치되지 않은 계약을 실행 | 실행하지 않고 코드로만 확인(증거 수준 E1): `runtime-adapters.ts:540-552`는 실행기를 거치지 않고 위반을 바로 돌려준다. `finish()`/`observe`를 부르지 않으므로 진단이 0건이다 | +| E7 | (03-01) namespace 오타(`"reference-resources"`)로 `bindQuery` 호출 후, 설치된 무효화 레지스트리의 모든 topic이 그 namespace에 닿는지 확인 | 오류 없이 바인딩된다. 쿼리 키 접두사 `["query",2,"reference-resources",1]`. 어떤 topic도 닿지 않는다 | +| E8 | (03-04) 참조 분류기에서 422를 `NOT_APPLIED` 목록에서 뺀 뒤(`wt-03b`), 422 + `issues`로 저장 | POST 1회. 화면에 필드 오류("새 항목 이름: 입력값이 너무 짧습니다.")와 "변경 결과를 확인할 수 없습니다.", "같은 요청으로 다시 보내기" 버튼이 함께 나온다 | +| S1 | 영역 어댑터 크기. esbuild 0.28.1로 배럴마다 단독 번들(minify, ESM, `@tanstack/*`·`zod`·`react` 외부) | 7절 표 | +| S2 | 같은 커밋을 다른 영역 에이전트(11)가 빌드한 `scratchpad/wt-11/dist`에서 영역 문자열 검색 | V2 client 본문과 Browser RPC는 빠진다. V2 모듈의 최상위 식(봉투 zod 스키마, `Object.freeze` 상수 4개, 약 0.7KB)이 `design-system-*.js` 청크에 남는다 | + +E1·E2·E3·E5·E6·E7·E8은 단일 파일 실행이라 lock 없이 돌렸다(부하 12~16). 시간 측정은 1.2절의 baseline만 의미가 있다. + +### 1.2 변이 실험 (관점 10) + +`scratchpad/r03/run-mutations.mjs`가 `wt-03`에서 변이 하나씩 적용 → 영역 테스트 → 원복을 반복했다. 영역 테스트 목록은 `scratchpad/r03/area-tests.txt`(unit 20개 경로, `tests/integration`, component 10개, `tests/features/reference-feature`, `tests/platform/errors`·`telemetry`)다. heavy lock 아래에서 돌렸다. 끝난 뒤 `git status --short src`가 비어 있었다. + +- **baseline:** 70 files / 767 tests 통과, 15.4초(시작 load 22.16, 끝 load 21.06). +- **결과:** 21개 중 13개 검출, 8개 생존. 생존 8개 중 4개는 같은 보호가 다른 곳에도 있어 사실상 동등한 변이다. 동등 변이를 빼면 17개 중 13개 검출이다. + +| 변이 | 위치 | 결과 | 해석 | +|---|---|---|---| +| M1 UNKNOWN 동안 identity lease를 잡지 않음 | `application-query.ts:605-608` | **생존** | P-03-06 그대로 | +| M2 KEYED가 전송 뒤에도 재시도 | `http-retry-lifecycle.ts:27` | 검출(`http-execution-v3.test.ts`) | | +| M3 효과 누적이 단조가 아님 | `http-effect-certainty.ts:70-72` | 검출 | | +| M4 `classifyStatus` 없는 401·403·429를 `NOT_APPLIED`로 | `http-effect-certainty.ts:141-143` | 검출 | | +| M5 throw한 `classifyProblem`을 `NOT_APPLIED`로 | `http-effect-certainty.ts:113-117` | **생존** | 03-05. 안전 기본값을 고정하는 테스트가 없다 | +| M6 scope fence 뒤 JSON 성공을 받아들임 | `http-execution-v3.ts:1376-1382` `isCurrent` 검사 제거 | 생존 | 동등에 가까움. fence는 scope signal을 abort하고, 실행기는 admission 뒤 `terminalCancellation`으로 다시 막는다(`:1028-1030`). `isCurrent`만 false이고 signal은 살아 있는 scope 구현에서만 차이가 난다 | +| M7 서버 반사 correlation 값 문법 검사 제거 | `http-execution-v3.ts:1626` `safeMetadata` | **생존** | 03-06. 서버가 준 값이 그대로 `AppFailure.requestId`(화면의 지원 참조)와 진단으로 간다 | +| M8 전송 TIMEOUT을 `NETWORK_UNREACHABLE`로 | `feature-http-binding.ts:409-410` | **생존** | 03-06. V3 바인딩의 시간 초과 분류를 보는 테스트가 없다(`REQUEST_TIMEOUT` 단언은 V2 client 테스트에만 있다, `tests/integration/http-execution-contract.test.ts:316`) | +| M9 자격증명 owner가 transport 소유 헤더를 보내도 됨 | `http-contract-bridge.ts:77` | 생존 | 동등에 가까움. 그 헤더들은 자격증명 허용 목록에 없어 다음 줄에서 `CREDENTIAL_HEADER_NOT_ALLOWED`로 거절된다. 사유 코드만 바뀐다 | +| M10 `Retry-After` 5초 상한 무시 | `http-retry-lifecycle.ts:60` | 검출 | | +| M11 진행 중 mutation이 있어도 원격 무효화 실행 | `tanstack-cache-coordinator.ts:132-134` | 검출 | | +| M12 fence가 진행 중 세대를 abort하지 않음 | `server-state-scope-runtime.ts:122` | 검출 | | +| M13 텔레메트리 keepalive가 64KiB 할당량 무시 | `telemetry-collector.ts:123` | 검출 | | +| M14 진단 버퍼 상한 제거 | `bounded-diagnostics.ts:45` | 검출 | | +| M15 진단에서 `correlation_id` 제거 | `runtime-adapters.ts:252` | 검출 | | +| M16 `Idempotency-Key` 헤더 미전송 | `http-execution-v3.ts:810` | 검출 | | +| M17 경로 값 `.`·`..` 허용 | `http-contract-bridge.ts:203-204` | 검출 | | +| M18 auth 어댑터가 CR/LF 허용 | `external-session-adapter.ts:50` | 생존 | 동등에 가까움. 브리지의 ByteString 검사(`http-contract-bridge.ts:58`, `:90-96`)가 다시 거절한다 | +| M19 RPC KEYED가 유효 키 없이 재시도 | `browser-rpc-runtime.ts:1524-1526` | 생존 | 동등. 계약 검사가 `KEYED_COMMAND`에 `REQUIRED`를 강제하고(`src/contracts/browser-rpc.ts:726-727`), 호출 검사가 키 없는 호출을 먼저 막는다(`browser-rpc-runtime.ts:1285-1303`) | +| M20 참조 목록 조회 namespace 오타 | `use-reference-feature.ts:127` | 검출(`reference-page.test.tsx`) | 03-01. 참조 기능은 화면 테스트가 잡는다. 새 기능에는 일반 검사가 없다(E7) | +| M21 참조 분류기에서 409를 뺌(P-03-01 수정 탐침) | `reference-feature-contract-contribution.ts:42` | 검출(`http-scenario-catalog.test.ts`) | 시나리오 카탈로그의 `conflict-409`가 409 → `NOT_APPLIED`를 고정한다(`tests/mocks/scenarios/catalog.ts:260-265`). P-03-01을 고치면 이 카탈로그에 "처리 중 409" 시나리오를 더해야 한다 | + +## 2. 지난 발견 재확인 + +| ID | 지난 판정 | 상태 | 현재 근거 | +|---|---|---|---| +| P-03-01 같은 키 재전송이 "처리 중" 409를 받으면 키 보호가 풀린다 | High · P1 | **남음** | 분류기가 모든 409를 `NOT_APPLIED`로 본다(`reference-feature-contract-contribution.ts:42-44`). 코디네이터는 재전송을 시작할 때 이전 UNKNOWN admission을 정리하고(`application-query.ts:504-528`), `NOT_APPLIED`면 새 admission도 정리한 뒤 conflict를 세운다(`:584-589`). 폼은 CONFLICT에서 결과 불명 기록을 지운다(`use-app-form.ts:227-230`). 백엔드 계약은 여전히 "bounded `IN_PROGRESS` 결과"의 status를 정하지 않는다(`backend-api-and-server-state-contract.md:299-300`). 짝 백엔드 템플릿(`../clean-architecture-backend-template`, `01a8a2a`)은 지금도 처리 중인 같은 키를 409 `IDEMPOTENT_IN_FLIGHT`로 돌려준다(`src/application-core/src/main/java/dev/caskeleton/application/idempotency/IdempotencyInFlightException.java:9`, `:34`, 읽기만 함). **E1 재현: 키 `[K, K, K′]`** | +| P-03-02 `x-correlation-id` CORS 허용이 교차 origin 배포의 전제인데 문서 통제뿐이다 | Medium · P2 | **남음** | 헤더를 항상 붙이고(`http-execution-v3.ts:817-826`) 끄는 설정이 없다(`runtime-adapters.ts:489-533`). `docs/runbooks/FE-RB-003.md`에 CORS·preflight 언급이 없다. `README.md`에 preflight 점검 명령이 없다. 백엔드 계약 §5 허용 목록에 `traceparent`가 없다(grep 0건) | +| P-03-03 결과 불명 재전송이 키 없는 명령에도 열려 있다 | Medium · P2 | **남음 — 원인 구조는 03-03** | `resendUnknownEffect`는 head가 UNKNOWN이고 intent가 있는지만 본다(`application-query.ts:736-747`). **E2 재현: execute 2회, 키 없음.** 컨트롤러는 계약의 `commandRecovery.mode`를 알 방법이 없다(03-03) | +| P-03-04 결과 불명 쓰기에 문의 식별자가 없다 | Medium · P2 | **남음** | 바인딩은 응답 metadata의 반사값만 `requestId`로 싣는다(`feature-http-binding.ts:309-318`). `TRANSPORT_FAILURE`·`CANCELLED`에는 metadata가 없다(`:396-417`). 보낸 id(`http-execution-v3.ts:826`)는 관측 기록에만 간다. AsyncSurface의 결과 불명 분기는 지원 참조를 그리지 않는다(`async-surface.tsx` indicator 분기. 종료 오류 분기 146~165행만 그린다) | +| P-03-05 마감이 최종 불변식 검사 직전에 끝나면 시간 초과가 "입력 거절"이 된다 | Low · P2 | **남음 — 03-02에 포함** | 같은 동기 구간에서 `remaining()`을 두 번 읽는다(`http-execution-v3.ts:884`, `:925`). `DEADLINE_EXPIRED`를 따로 받지 않는다(`:933-938`). **E3 재현.** 같은 원인 계열(전송 전 실패를 한 코드로 합침)이 03-02로 넓어졌다. 03-02를 고치면 함께 닫힌다 | +| P-03-06 UNKNOWN 동안 identity lease를 잡는 코드를 검증하는 테스트가 없다 | Low · P3 | **남음** | 코드는 `application-query.ts:605-608`에 그대로다. 이 네 줄을 지운 변이 M1이 영역 테스트 767건을 모두 통과했다(1.2절) | + +## 3. 이번 라운드 렌즈 — 기능 개발자가 HTTP 연결을 하나 추가할 때 + +대표 과제: "참조 기능에 KEYED 쓰기 하나와 새 상세 조회 하나를 추가한다." 개발자가 직접 쓰는 값과, 틀렸을 때 그 사실이 언제 어떻게 드러나는지를 따라갔다. + +```text +계약(contracts/*-contract-contribution.ts) + retrySemantics, commandRecovery, commandEffect.classifyProblem / classifyStatus, + acceptedStatuses, frontend 정책, projectRequest + -> 설치 검사(external-contract-runtime.ts:440-513) [시작할 때 throw] +선언 행(contracts/*-contract.ts apiOperations) [07-02, 일치 테스트] +바인딩(adapters/*-http-gateway.ts) + mapSuccess, mapProblem(kind/code) [타입 검사] +mutation 정책(presentation/use-*.ts) + definitionId, operationId(문자열), requiresIdempotencyKey(불리언), invalidate + -> 첫 실행 때 실행기가 intent 검사(http-execution-v3.ts:378-436) [실행 시점] +조회 정의(presentation/use-*.ts) + namespace(문자열), namespaceVersion(숫자), profileId, measureResult + -> 검사 없음 [조용함] +``` + +| 개발자 실수 | 잡히는 시점·수단 | 사용자에게 보이는 것 | 진단에 남는 것 | 관련 | +|---|---|---|---|---| +| 쓰기 계약에 `commandEffect` 없음, KEYED인데 recovery 없음, NEVER인데 재시도 예산 | 앱 시작(설치 검사 throw) | 시작 실패 | throw 메시지 | 잘 막힘 | +| 분류기가 "처리 중" 409를 `NOT_APPLIED`로 판정 | 안 잡힘 | "충돌", 다음 저장은 새 키 | `PROBLEM`/`NOT_APPLIED` | P-03-01 | +| 분류기와 `mapProblem`이 어긋남(예: 422를 분류기가 빠뜨림) | 안 잡힘 | 필드 오류 + "결과를 확인할 수 없습니다" 동시 | `PROBLEM`/`MAYBE_APPLIED` | 03-04 | +| 분류기 코드가 throw | 안 잡힘(안전 쪽으로 `MAYBE_APPLIED`). 이 기본값을 고정하는 테스트도 없다(M5) | "결과를 확인할 수 없습니다" | 정상 `MAYBE_APPLIED`와 같음 | 03-05 | +| mutation 정책의 `requiresIdempotencyKey`나 `operationId`가 계약과 다름 | 첫 저장(실행기 intent 검사, fetch 0) | "입력값을 다시 확인해 주세요." | `MISSING_IDEMPOTENCY_KEY` 또는 `UNEXPECTED_IDEMPOTENCY_KEY` | 03-03, 03-02 | +| 경로 placeholder와 `projectRequest` 키가 다름 | 첫 실행(fetch 0) | 조회면 "서버가 입력값을 받아들이지 않았습니다." | `FINAL_REQUEST_INVARIANT_FAILED`(원인 없음) | 03-02 | +| 계약을 기능 모듈 `contractContributions`에 안 넣음 | 첫 실행(fetch 0) | 위와 같음 | **없음** | 03-02 | +| 키 없는 명령 폼에 재전송 버튼 연결 | 안 잡힘 | 재전송 → 중복 실행 가능 | 없음 | P-03-03 | +| 조회 namespace 오타·새 namespace를 무효화 레지스트리에 안 넣음 | 안 잡힘 | 저장 뒤 목록이 그대로(staleTime 또는 포커스까지) | 없음 | 03-01 | +| mutation `invalidate`에 미등록 topic | 첫 저장(`beginMutation`이 throw) | 저장 실패 | throw | 잘 막힘(`tanstack-cache-coordinator.ts:52-60`) | + +정리하면, 템플릿은 **계약 모양의 빈칸**은 시작할 때 막는다. 하지만 **같은 사실을 다른 곳에 다시 적는 값**(mutation 정책, 조회 namespace)과 **업무 의미를 판정하는 함수**(분류기)는 막지 못한다. 막더라도 원인이 "입력 거절"로 바뀌어 보인다. 참조 기능 README는 "feature는 operation ID, route ID, request type, 성공 value type, mapper만 소유한다"고 적지만(`src/features/reference-feature/README.md` HTTP adapter 절), 실제로는 위험이 가장 큰 효과 분류기와 mutation 정책도 기능이 쓴다. + +## 4. 새 발견 (36.3) + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 03-01 | Medium | P2 | 확인된 결함 | 5, 21, 22, 17, 20, 24 | 조회 정의의 namespace를 무효화 레지스트리와 대조하지 않는다 | +| 03-02 | Low | P2 | 확인된 결함 | 8, 6, 24, 20, 5 | 전송 전 실패(연결 실수·조립 실패·마감)가 모두 "입력 거절"로 합쳐지고 원인이 진단에 남지 않는다 | +| 03-03 | Low | P3 | 구조적 위험 | 22, 3, 5, 21, 39.5 | mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 손으로 적는다 | +| 03-04 | Low | P3 | 구조적 위험 | 5, 22, 6, 4 | 효과 판정과 화면 분류가 두 함수에서 따로 정해지고, 어긋나면 화면이 서로 반대되는 안내를 한다 | +| 03-05 | Low | P2 | 확인된 결함 | 8, 24, 10, 6 | 분류기 실패를 "contract runtime failure로 기록한다"는 주장과 달리 흔적이 없고, 안전 기본값을 고정하는 테스트도 없다 | +| 03-06 | Low | P3 | 개선 제안 | 10, 8, 15 | V3 바인딩의 시간 초과 분류와 서버 반사 correlation 값의 문법 검사를 고정하는 테스트가 없다 | + +### 03-01 조회 정의의 namespace를 무효화 레지스트리와 대조하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 5, 21, 22, 17, 20, 24 | +| 근거 | `QueryDefinition`의 `namespace`는 `string`, `namespaceVersion`은 `number`다(`src/contracts/server-state.ts:163-164`). `bindQuery`는 이 두 값으로 identity를 새로 만들 뿐(`:184-187`) 등록 여부를 보지 않는다. 무효화는 topic → 등록 namespace 접두사로만 간다(`tanstack-cache-coordinator.ts:73-88`). 설치 레지스트리에는 `namespaces` 목록이 있지만(`installed-feature-contracts.ts:56-75`) 조회 쪽에서 읽는 곳이 없다(grep). 문서는 "query namespace는 arbitrary caller string이 아니라 registry reference다"라고 적는다(`docs/architecture/client-cache-and-storage.md:466`). 참조 기능은 등록 객체에서 두 필드를 꺼내 따로 넘긴다(`use-reference-feature.ts:90-92`, `:127-129`). **E7:** 오타 namespace가 오류 없이 바인딩되고, 어떤 topic도 닿지 않는다. **변이 M20:** 참조 목록 조회 namespace를 오타로 바꾸면 `reference-page.test.tsx`가 잡는다(저장 뒤 목록 갱신을 확인하는 화면 테스트). 즉 참조 기능은 화면 테스트로 막혀 있고, 새 기능에는 그런 테스트를 따로 써야 한다. 일반 검사는 없다 | +| 발생 조건 | 기능 개발자가 새 조회를 만들면서 namespace 문자열을 직접 쓰거나, 새 namespace를 계약의 `invalidation.namespaces`·`edges`에 넣지 않거나, `namespaceVersion`만 올린다 | +| 영향 | 저장이 성공해도 그 조회는 무효화되지 않는다. 화면은 staleTime(목록 15초, 상세 30초, `LOOKUP_STABLE` 5분이며 포커스 갱신도 없음, `server-state.ts:34-81`)까지 이전 데이터를 보인다. 다른 탭 무효화도 닿지 않는다. 오류·진단이 없어 "가끔 갱신이 늦다"는 문의로만 드러난다. 데이터 손상은 없다 | +| 심각도·우선순위 | Medium · P2 — 피해는 화면 신선도에 한정된다. 하지만 새 조회마다 생기는 숨은 규칙이고, 문서가 이미 막혀 있다고 말한다. 고치는 비용이 작다 | +| 통제·증거 | 목표 M4(타입) 또는 M3(런타임 검사) / 확인 M1(문서 문장만) · E2(E7) | +| 확실성과 남은 가정 | 기전은 확정. 다운스트림에 이런 조회가 있는지는 보지 않았다 | +| 결정의 근거 | `[사실]` 레지스트리와 쿼리 키 접두사가 같은 `QueryNamespaceIdentity` 모양을 쓴다(`query-keys.ts:40-66`). `[추론]` `QueryDefinition`이 문자열 두 개를 받게 된 것은 TanStack 키를 만들 최소 정보만 요구했기 때문으로 보인다. 기록은 찾지 못했다 | +| 이해 비용 | 새 조회를 만드는 사람은 "이 namespace가 어떤 topic의 edge에 있는가"를 계약 파일에서 직접 확인해야 한다. 조회 코드만 보면 알 수 없다 | +| 최소 개선 방향 | ① `QueryDefinition`이 `namespace: QueryNamespaceIdentity`(등록 객체) 하나를 받게 한다. 문자열 두 개를 따로 넘기는 경로를 없앤다. ② 조회 provider가 설치 무효화 인덱스를 알고 있으므로, 첫 바인딩 때 namespace가 어떤 topic에도 없으면 진단 1건(개발 빌드는 throw)을 남긴다 | +| 대안 비교 | ①만: 오타는 막지만 "등록은 했는데 edge가 없음"은 못 막는다. ②만: 런타임 검사라 그 화면을 열어야 드러난다. 둘 다: 타입 1곳, 검사 1곳. 무효화가 필요 없는 조회(정적 조회)는 ②에서 예외 표시가 필요하다 — `invalidation: "NONE"` 같은 명시 값을 받는다. 현상 유지는 문서 주장과 코드가 계속 다르다 | +| 단순화의 보존 조건 | 쿼리 키 배열 모양 유지(`createBoundQueryKey`), 세대 fingerprint는 namespace 뒤에 둔다(접두사 무효화가 세대를 가로지르도록) | +| 비용·부작용 | 공개 타입 변경 1곳. 다운스트림 조회 정의를 한 줄씩 바꿔야 한다(CHANGELOG [계약] 행) | +| 재검토 조건 | 무효화를 topic이 아닌 서버 이벤트(ETag·SSE)로 바꾸면 다시 본다 | +| 완료 기준 | 등록되지 않은 namespace로 조회를 정의하면 타입 오류 또는 진단 1건이 생긴다. 참조 기능은 등록 객체를 그대로 넘긴다 | +| 검증 방법 | E7을 테스트로 넣고 기대를 "타입 오류(ts-expect-error fixture)" 또는 "진단 1건"으로 바꾼다. 변이 M20을 다시 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-02 전송 전 실패가 모두 "입력 거절"로 합쳐지고 원인이 진단에 남지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 6, 24, 20, 5 | +| 근거 | 전송 전 실패가 네 곳에서 하나의 위반 `FINAL_REQUEST_INVARIANT_FAILED`로 바뀐다. ① 입력 검증 실패(`http-execution-v3.ts:683-692`) ② 요청 조립 실패 10종(`PATH_PLACEHOLDER_MISSING`, `QUERY_TOO_LARGE`, `REQUEST_BODY_TOO_LARGE` 등, `http-contract-bridge.ts:135-145`)을 `:699-708`에서 ③ 최종 불변식 실패 12종(`DEADLINE_EXPIRED` 포함, `http-contract-bridge.ts:324-337`)을 `:933-938`에서 ④ 미설치 계약을 `runtime-adapters.ts:540-552`에서. 구체 원인은 결과에도 관측에도 실리지 않는다. 바인딩은 이 위반과 `MISSING_IDEMPOTENCY_KEY`·`UNEXPECTED_IDEMPOTENCY_KEY`를 `VALIDATION_REJECTED`로 바꾼다(`feature-http-binding.ts:467-471`). 사용자 문구는 "서버가 입력값을 받아들이지 않았습니다."(`catalog.ts:185`), 폼에서는 "입력값을 다시 확인해 주세요."(`form-contracts.ts:69-71`, `catalog.ts:144`)다. ④는 `finish()`를 거치지 않아 관측(진단·텔레메트리)이 0건이다. **E6a·E6c·E3:** 세 경우 모두 fetch 0회, `VALIDATION_REJECTED`. E6c 관측은 `errorKind FINAL_REQUEST_INVARIANT_FAILED`뿐이다 | +| 발생 조건 | 기능 개발자의 연결 실수(경로 placeholder, intent 배선, 계약 미설치), 사용자의 입력 크기 초과(본문·쿼리 상한), 마감 경계(P-03-05) | +| 영향 | 안전성 문제는 없다. 모두 전송 전에 막힌다. 문제는 진단이다. 개발자는 "서버가 거절했다"는 문구와 원인 없는 코드를 보고 서버 로그부터 찾게 된다. 미설치 계약은 진단 버퍼에도 흔적이 없다. 운영에서는 클라이언트 결함이 `api.request.failed`의 `error_kind FINAL_REQUEST_INVARIANT_FAILED`로 섞여, 사용자 입력 문제와 구분되지 않는다 | +| 심각도·우선순위 | Low · P2 — 데이터·보안 피해가 없고 개발 중 첫 실행에서 드러난다. 다만 새 기능을 붙이는 사람이 가장 먼저 부딪히는 실패이고, P-03-05(마감 오분류)도 같은 수정으로 닫힌다 | +| 통제·증거 | M2(전송 전 차단은 구현됨) / 원인 전달 M0 · E2(E3, E6a, E6c) + E1(E6b) | +| 확실성과 남은 가정 | 확정. 사용자가 상한을 넘는 입력을 실제로 얼마나 만드는지는 모른다 | +| 결정의 근거 | 적용 제외 — 분류를 합친 것은 선택이라기보다 누락이다. 바인딩 주석("Rejected before dispatch: the request, not the server answer, was wrong.", `feature-http-binding.ts:467`)도 "요청이 잘못됐다"는 뜻으로 쓰고, "서버가 거절했다"는 문구와 다르다 | +| 이해 비용 | 원인을 알려면 디버거로 `projectRequest`·`checkFinalInvariants`의 반환값을 직접 봐야 한다 | +| 최소 개선 방향 | ① `HttpContractViolation`에 선택 필드 `reason`(조립·불변식 실패 코드, 닫힌 집합)을 두고 관측 기록에 `terminalReason`으로 싣는다(진단 전용, 텔레메트리는 지금처럼 `error_kind`만). ② `DEADLINE_EXPIRED`는 `SCOPE_FENCED`처럼 따로 받아 `TRANSPORT_FAILURE`/`TIMEOUT`으로 끝낸다(P-03-05). ③ 바인딩은 클라이언트 쪽 원인(연결 실수·미설치)을 `VALIDATION_REJECTED`가 아닌 별도 종류(예: 기존 `MAPPING_CONTRACT_VIOLATION`처럼 "문의" 행동을 가진 종류)로 낸다. 입력 크기 초과만 `VALIDATION_REJECTED`로 둔다. ④ 미설치 계약 경로도 관측 1건을 남긴다 | +| 대안 비교 | 적용 제외 — 기존 분류 체계 안에서 빠진 구분을 채우는 문제다 | +| 단순화의 보존 조건 | 전송 전 실패는 fetch 0회. 효과 `NOT_STARTED`. 원인 코드는 텔레메트리에 넣지 않는다(VD-07) | +| 비용·부작용 | 공개 결과 타입에 선택 필드 1개, 오류 종류 매핑 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E6c에서 진단 `terminalReason`이 `PATH_PLACEHOLDER_MISSING`이다. E3에서 결과가 `TRANSPORT_FAILURE`/`TIMEOUT`이다. E6a·E6c의 사용자 문구가 "서버가 거절"이 아니다. 미설치 계약 실행이 진단 1건을 남긴다 | +| 검증 방법 | 실험 E3·E6을 테스트로 옮기고 기대값을 바꾼다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-03 mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 손으로 적는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 22, 3, 5, 21 (39.5 선언·실행 중복) | +| 근거 | `BoundMutation`은 `operationId: string`, `requiresIdempotencyKey: boolean`을 받는다(`server-state.ts:234-252`). 계약의 `operationId`·`retrySemantics`와 타입으로 이어져 있지 않다. 참조 기능은 `"CREATE_REFERENCE_RESOURCE"`와 `true`를 다시 쓴다(`use-reference-feature.ts:53-61`). 이 값으로 intent를 만들고(`application-query.ts:536-545`), 실행기가 첫 실행 때 계약과 대조한다(`http-execution-v3.ts:378-436`). 같은 사실이 계약(`retrySemantics: "KEYED"` + `commandRecovery`), 선언 행(`idempotencyKeyPolicy: "REQUIRED"`, 07-02), mutation 정책 세 곳에 있다. 앞의 두 곳은 일치 테스트가 있고(`http-operation-v2-v3-parity.test.ts`) mutation 정책은 없다. **E6a:** 틀리면 fetch 0회, `VALIDATION_REJECTED`. 컨트롤러가 계약의 `commandRecovery.mode`를 모르기 때문에 P-03-03(키 없는 재전송)을 고칠 자리도 없다 | +| 발생 조건 | 쓰기를 추가하거나 계약의 `retrySemantics`를 바꾸면서 mutation 정책을 함께 고치지 않는다 | +| 영향 | 지금은 안전 쪽으로 실패한다(첫 저장에서 막힘). 대신 03-02 때문에 "입력값을 다시 확인해 주세요"로 보인다. 계약을 `KEYED`에서 `IDEMPOTENT`로 바꾸면 mutation 정책도 바꿔야 한다는 사실은 어디에도 적혀 있지 않다 | +| 심각도·우선순위 | Low · P3 — 피해가 없고 첫 실행에서 드러난다. P-03-03을 구조적으로 닫을 때 함께 고치는 것이 싸다 | +| 통제·증거 | 잘못된 키 요청의 전송: M4(실행기가 경계에서 막음) / 정책과 계약의 일치: 실행 전에 검출하는 수단 없음 · E2(E6a) | +| 확실성과 남은 가정 | 확정 | +| 결정의 근거 | `[사실]` 프레젠테이션의 mutation 훅은 HTTP 어댑터를 import할 수 없다(경계 규칙). 그래서 정책 객체가 문자열·불리언을 받는다. `[추론]` 계약에서 파생하는 helper를 `contracts/` 쪽에 두면 경계를 지키며 연결할 수 있다 | +| 이해 비용 | 쓰기 하나를 바꾸는 사람이 계약·선언 행·mutation 정책 세 파일을 같이 열어야 한다 | +| 최소 개선 방향 | 설치 계약(또는 `FeatureHttpOperation`)을 받아 `operationId`, `requiresIdempotencyKey`(`retrySemantics === "KEYED"`), `recoveryMode`를 돌려주는 순수 helper를 `contracts/`에 둔다. 참조 기능의 mutation 정책은 이 helper를 펼친다. 컨트롤러는 `recoveryMode`로 `resendUnknownEffect`를 열지 정한다(P-03-03) | +| 대안 비교 | 5절 B. 현상 유지: 실행 시점 검출로 안전은 유지된다. 타입만 좁히기(`operationId`를 계약 literal로): 오타는 막지만 키 여부는 여전히 따로 적는다. helper 파생: 타입 1개·함수 1개, 경계 규칙 그대로 | +| 단순화의 보존 조건 | 실행기의 intent 검사는 남긴다(다른 경로로 들어오는 intent 방어). intent 생성은 계속 `MutationIntentFactory`가 맡는다 | +| 비용·부작용 | 공개 helper 1개. 다운스트림 mutation 정책이 바뀐다 | +| 재검토 조건 | mutation이 HTTP 외 전송(Browser RPC)을 쓰기 시작하면 helper 입력을 전송 중립 모양으로 바꾼다 | +| 완료 기준 | 참조 기능 mutation 정책에 `operationId`·`requiresIdempotencyKey` 리터럴이 없다. 키 없는 명령에서 `resendUnknownEffect`가 `null`이다 | +| 검증 방법 | E2 기대값을 "execute 1회"로 바꾼다. 계약 `retrySemantics`를 바꾸면 mutation 정책이 따라오는지 단위 테스트 1건 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-04 효과 판정과 화면 분류가 두 함수에서 따로 정해지고, 어긋나면 화면이 서로 반대되는 안내를 한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 5, 22, 6, 4 | +| 근거 | 같은 problem 응답을 두 번 분류한다. 효과는 계약의 `classifyProblem`이 정한다(`reference-feature-contract-contribution.ts:37-52`, 실행 `http-execution-v3.ts:1594-1601`). 화면 종류는 바인딩의 `mapProblem`, 없으면 `kindForStatus`가 정한다(`reference-http-gateway.ts:37-52`, `feature-http-binding.ts:361-379`, `errors.ts:247-257`). 두 함수는 다른 파일에 있고, 서로를 대조하는 검사는 없다. 코디네이터는 효과로 갈린다(`application-query.ts:583-614`). 폼은 `VALIDATION_REJECTED`와 `reauth`를 효과보다 먼저 본다(`use-app-form.ts:204-226`). **E8:** 분류기에서 422만 빠뜨리자, 코디네이터는 UNKNOWN admission을 만들고 폼은 필드 오류를 띄웠다. 화면에 "새 항목 이름: 입력값이 너무 짧습니다."와 "변경 결과를 확인할 수 없습니다." + "같은 요청으로 다시 보내기"가 같이 나왔다. 참조 기능의 두 함수는 지금 서로 맞는다 | +| 발생 조건 | 기능 패키지의 분류기가 어떤 상태를 `MAYBE_APPLIED`(기본값)로 두고, 바인딩은 그 상태를 `VALIDATION_REJECTED`로 본다. 분류기의 기본 가지가 `MAYBE_APPLIED`이므로(`:45`) 목록에서 하나만 빠져도 생긴다 | +| 영향 | 사용자가 입력을 고칠지, 같은 요청을 다시 보낼지 판단할 수 없다. 같은 입력으로 다시 저장하면 코디네이터가 이전 키를 재사용하므로 중복은 막힌다(데이터 피해 없음) | +| 심각도·우선순위 | Low · P3 — 참조 기능에는 경로가 없다. 기능을 복제할 때 생긴다 | +| 통제·증거 | M0(대조 없음) · E2(E8) | +| 확실성과 남은 가정 | 화면 결과는 jsdom에서 확인했다. 실제 브라우저 배치는 보지 않았다 | +| 결정의 근거 | 5절 A | +| 이해 비용 | 기능 작성자는 같은 상태 코드 목록을 두 파일에서 같은 뜻으로 유지해야 한다 | +| 최소 개선 방향 | 폼이 효과를 먼저 본다: `MAYBE_APPLIED`면 kind와 관계없이 결과 불명 화면을 우선한다(`reauth`는 지금처럼 먼저). 그리고 바인딩이 `VALIDATION_REJECTED`를 내면서 효과가 `MAYBE_APPLIED`인 조합을 진단 1건으로 남긴다 | +| 대안 비교 | 5절 A 표 | +| 단순화의 보존 조건 | `reauth`는 효과보다 먼저(D-2). 진짜 422(`NOT_APPLIED`)는 필드 오류로 간다 | +| 비용·부작용 | 폼 분기 순서 변경. 결과 불명 화면에서는 서버 필드 오류를 보여 주지 않게 된다 | +| 재검토 조건 | 분류를 패키지 한 곳으로 합치면(5절 A의 (c)) 이 항목은 사라진다 | +| 완료 기준 | E8 순서에서 화면 안내가 하나다 | +| 검증 방법 | E8을 테스트로 넣는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-05 분류기 실패를 기록한다는 주장과 달리 흔적이 없고, 안전 기본값을 고정하는 테스트도 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 24, 10, 6 | +| 근거 | `classifyProblemEffect`는 throw·모르는 값을 `MAYBE_APPLIED` + `contractRuntimeFailure: true`로 돌려준다(`http-effect-certainty.ts:92-129`). 주석은 "is recorded as a contract runtime failure"라고 적고, 설계서도 "contract runtime failure를 기록한다"고 적는다(`…closed-deep-design.md:650`). 실행기는 `.effect`만 쓰고 플래그를 버린다(`http-execution-v3.ts:1594-1601`). 플래그를 읽는 코드는 0곳이다(grep). **E5:** throw한 경우와 의도적으로 `MAYBE_APPLIED`를 낸 경우의 관측 기록이 요청 id만 빼고 같다. **변이 M5:** catch 가지를 `NOT_APPLIED`로 바꿔도 영역 테스트 767건이 모두 통과했다. `classifyStatus` throw는 테스트가 있지만(`http-execution-v3.test.ts:1220-1235`) `classifyProblem` throw는 없다 | +| 발생 조건 | 기능 패키지 분류기가 예상 못 한 problem 모양에서 throw한다(예: 선택 필드에 바로 접근) | +| 영향 | 지금은 안전 쪽(`MAYBE_APPLIED`)으로 실패한다. 하지만 "결과 불명"이 늘어도 분류기 결함 때문인지, 서버가 정말 애매한 답을 줬는지 운영자가 구분할 수 없다. 또 이 안전 기본값이 리팩터링 중에 `NOT_APPLIED`로 바뀌면 P-03-01과 같은 피해(키 결합 해제)가 생기는데 테스트가 모른다 | +| 심각도·우선순위 | Low · P2 — 현재 피해는 없다. 결과 불명 쓰기의 핵심 규칙 하나를 지키는 줄이 테스트 없이 있다는 점 때문에 P2로 둔다. 테스트 1건과 몇 줄이면 닫힌다 | +| 통제·증거 | M2(안전 쪽 기본값 구현) / 검출 없음(M5 생존) / 기록 M0 · E2(E5, M5) | +| 확실성과 남은 가정 | 확정 | +| 결정의 근거 | 적용 제외 — 주석·설계서에 적힌 동작이 빠졌다 | +| 이해 비용 | 적용 제외 | +| 최소 개선 방향 | 플래그가 참이면 관측 `terminalReason`을 `CLASSIFIER_FAILED`로 둔다(진단 전용). 아니면 플래그와 주석 문장을 지운다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 효과는 계속 `MAYBE_APPLIED`. 텔레메트리 라벨은 늘리지 않는다 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E5의 두 관측 기록이 `terminalReason`에서 갈린다. 변이 M5가 검출된다 | +| 검증 방법 | E5를 테스트로 넣고(throw → `MAYBE_APPLIED` + 진단 원인), M5를 다시 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 03-06 V3 바인딩의 시간 초과 분류와 서버 반사 correlation 값의 문법 검사를 고정하는 테스트가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 10, 8, 15 | +| 근거 | **변이 M8:** 바인딩이 전송 `TIMEOUT`을 `REQUEST_TIMEOUT`이 아닌 `NETWORK_UNREACHABLE`로 내도(`feature-http-binding.ts:407-417`) 영역 테스트 767건이 통과했다. `REQUEST_TIMEOUT` 단언은 V2 client 테스트에만 있다(`tests/integration/http-execution-contract.test.ts:316`). **변이 M7:** 응답 `x-correlation-id`의 문법 검사(`/^[A-Za-z0-9._:-]{1,128}$/`, `http-execution-v3.ts:1626`)를 지워도 통과했다. 이 값은 `AppFailure.requestId`가 되어 화면 지원 참조(`async-surface.tsx:146-151`)와 진단 `correlation_id`로 간다 | +| 발생 조건 | 바인딩이나 `safeMetadata`를 고치는 리팩터링 | +| 영향 | M8: 시간 초과가 "네트워크에 연결할 수 없습니다"로 안내된다. 운영 지표의 `error_kind`는 실행기 쪽 값이라 그대로다. M7: 서버(또는 중간 프록시)가 준 임의 문자열이 길이 제한 없이 화면과 진단에 실린다. React가 이스케이프하므로 스크립트 실행은 없다 | +| 심각도·우선순위 | Low · P3 — 현재 코드는 맞다. 회귀를 막는 테스트가 없을 뿐이다 | +| 통제·증거 | M2(구현) / 검출 없음 · E2(M7·M8 생존) | +| 확실성과 남은 가정 | 확정 | +| 결정의 근거 | 적용 제외 — 테스트 추가 문제다 | +| 이해 비용 | 적용 제외 | +| 최소 개선 방향 | `http-execution-v3.test.ts`의 바인딩 절에 ① 마감 초과 → `REQUEST_TIMEOUT` ② 반사 헤더가 문법 밖(공백, 129자)이면 `requestId` 없음 — 테스트 2건 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 2건 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | M7·M8이 검출된다 | +| 검증 방법 | `d99301b` 이후 커밋으로 worktree `wt-03`을 다시 만들고 `node scratchpad/r03/run-mutations.mjs M7 M8` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 검토 (41절) + +`[사실]`은 코드·실행으로 확인한 것, `[기록]`은 커밋·문서에 적힌 의도, `[추론]`은 리뷰어의 해석이다. + +### A. 쓰기 결과의 의미(효과)는 기능 패키지의 분류기가 정하고, 플랫폼은 그 판정을 그대로 믿는다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 응답을 받은 쓰기가 서버에 적용됐는지 판정한다. 그 판정으로 키 유지·재전송·충돌 안내를 정한다. `[기록]` 설계서 4.4절 "frontend는 problem effect meaning을 작성하지 않는다"(`…closed-deep-design.md:648`) | +| 2. 지킬 성질 | 결과를 모르면 `NOT_APPLIED`라고 말하지 않는다. 같은 논리 요청은 같은 키. 사용자 안내는 하나 | +| 3. 현재 보장 | `[사실]` 판정 실패·모르는 값은 `MAYBE_APPLIED`(`http-effect-certainty.ts:97-129`). 401·403·429는 `classifyStatus`가 없으면 `MAYBE_APPLIED`(`:136-151`). 실행기는 효과를 단조 누적한다(`:58-73`). **보장하지 않음:** 분류기가 틀린 `NOT_APPLIED`를 내면 플랫폼은 키 결합을 푼다(P-03-01). 화면 종류는 다른 함수가 정한다(03-04). 409 판정은 시나리오 카탈로그가 고정한다(M21 검출). 분류기 throw의 안전 기본값은 고정하지 않는다(M5 생존) | +| 4. 대안 | (a) 현재 (b) 플랫폼 방어: 같은 intent로 보낸 재전송이 `NOT_APPLIED`를 받아도 `APPLIED_CONFIRMED` 전까지 키 결합을 풀지 않는다 (c) 분류기 하나가 효과와 화면 종류를 함께 돌려준다(`{effect, kind, code}`) (d) 백엔드 inspect operation으로 조회한 뒤 판정 | +| 5. 비교 | (a) 패키지가 업무 의미를 소유한다는 원칙에 맞다. 대신 패키지 실수가 그대로 키 보호를 푼다. (b) 플랫폼 몇 줄. 진짜 거절(같은 입력의 422)도 같은 키로만 다시 나가므로 사용자가 입력을 바꿔야 새 요청이 된다. 이는 "입력이 바뀌면 새 키" 규칙과 같다. (c) 03-04를 없앤다. 공개 타입(`CommandEffectDescriptor`, `mapProblem`)을 둘 다 바꿔야 한다. (d) 백엔드 엔드포인트가 필요하다 | +| 6. 현재 조건에서 | `[추론]` (a)를 유지하되 (b)를 더하는 것이 가장 작다. 패키지 분류기는 앞으로도 틀릴 수 있고(tech-log는 4xx 전체를 `NOT_APPLIED`로 쓴다 — 지난 라운드 확인, 이번에는 다시 보지 않음), (b)는 그 실수가 중복 생성으로 번지는 것만 막는다. (c)는 03-04의 근본 해결이지만 지금은 피해가 작아 비용이 크다 | +| 7. 재검토 조건 | 백엔드가 in-flight 응답 status를 계약에 고정하면 (b)의 필요가 줄어든다. inspect 엔드포인트가 생기면 (d). 분류 불일치가 실제로 관측되면 (c) | + +### B. 기능의 mutation 정책과 조회 정의를 계약과 별도 객체로, 손으로 쓴다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 프레젠테이션 훅이 HTTP 어댑터를 import하지 않고 mutation(키 필요 여부, 무효화 topic)과 조회(namespace, profile)를 정의한다. `[사실]` 경계 규칙상 프레젠테이션은 어댑터를 import할 수 없다 | +| 2. 지킬 성질 | 정책의 값이 실행 계약과 같다. 저장 뒤 관련 조회가 무효화된다 | +| 3. 현재 보장 | `[사실]` 키 배선은 실행 시점에 실행기가 대조한다(전송 전 차단, E6a). mutation의 미등록 topic은 첫 저장에서 throw(`tanstack-cache-coordinator.ts:52-60`). **보장하지 않음:** 조회 namespace 등록(03-01, E7), 원인 표시(03-02) | +| 4. 대안 | (a) 현재 (b) `contracts/`에 계약·등록 객체를 받아 정책을 만드는 순수 helper(`bindMutation(contract, …)`, `bindQuery({ namespace: REGISTERED_NS, … })`) (c) 설치 시점 정적 검사(스크립트가 기능 파일을 읽어 대조) (d) 타입만 좁힘(`operationId`를 계약 literal union으로) | +| 5. 비교 | (a) 비용 0, 실수가 조용하거나 늦게 드러난다. (b) helper 2개, 경계 규칙 그대로, 오타와 불일치를 컴파일 시점에 없앤다. 다운스트림 이행 비용이 있다. (c) 정의가 훅 안에서 런타임에 만들어져 정적 분석이 어렵다. (d) 오타만 막고 키 여부·namespace 등록은 못 막는다 | +| 6. 현재 조건에서 | `[추론]` (b). 같은 사실을 다시 적게 하는 구조라 39.5의 "개발자가 두 곳을 항상 맞춰야 하는 중복"에 해당한다. 07-02(선언 행과 실행 descriptor의 이중 기재)와 같은 계열이지만 위치와 소비자가 다르다 — 이쪽은 실행 경로에 있다 | +| 7. 재검토 조건 | 기능이 한두 개로 고정되고 새 쓰기를 거의 추가하지 않는다면 (a)도 감당할 만하다. 계약 패키지가 프레젠테이션용 정책까지 생성해 주면 (b) 대신 그 생성물을 쓴다 | + +V3 `execute()`의 크기(약 620줄, `http-execution-v3.ts:472-1090`)는 지난 라운드에 39.7로 보고 유지로 판정했다. 코드가 바뀌지 않았고 이번에 다시 읽은 결과도 같다. 순수 판정은 `http-retry-lifecycle.ts`·`http-effect-certainty.ts`로 빠져 있다. 다만 03-02의 원인 코드를 실으려면 이 조율부의 반환 지점 네 곳을 고쳐야 한다. + +## 6. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R1 | V3가 V2 파일 `retry-policy.ts`에서 `parseRetryAfter`를 가져오는 import(`http-execution-v3.ts:44`)를 `adapters/platform/retry-after.ts`의 `parseRetryAfterDelay` 직접 import로 바꾼다 | `retry-policy.ts`는 V2 재시도 정책(`shouldRetry` — keyed도 전송 뒤 재시도) 파일이다. V2를 지우려는 사람은 V3가 이 파일에 기대는 것을 import를 봐야 안다(27) | `Retry-After` 파싱 결과(초·HTTP-date, 음수·잘못된 값 → `null`). `tests/unit/retry-policy.test.ts`, `http-retry-lifecycle.test.ts` 통과 | +| R2 | V2 파일 6개(`client.ts`, `request-builder.ts`, `schema-registry.ts`, `resource-mapper.ts`, `retry-policy.ts`, `bounded-json.ts`)를 `src/adapters/http/legacy-v2/`로 옮긴다. 배럴 export 이름은 그대로 | 지금은 V2·V3 파일이 한 폴더에 섞여 있고 이름으로 구분되지 않는다(`retry-policy.ts` vs `http-retry-lifecycle.ts`, `bounded-json.ts` vs `bounded-body-reader.ts`). 같은 이름 `bounded-json.ts`가 `src/platform/validation/`에도 있다 | 배럴(`src/adapters/http/index.ts`) export 목록, `.dependency-cruiser.json` 규칙, `check:adapter-inventory`의 INVENTORY 동시 수정. V2 client의 동작 테스트(`tests/integration/http-client.test.ts` 등) | +| R3 | `failureKindForViolation`(`feature-http-binding.ts:445-475`)과 `platformErrorForOutcome`(`platform-error-mapping.ts`)의 `default` 가지를 없애고 위반 종류를 모두 나열한다 | 지금은 `HttpContractViolationKind`에 새 값을 넣어도 컴파일러가 알리지 않고 `ENVELOPE_MISMATCH`·`RESPONSE_INVALID`로 흡수된다. 오류 분류를 타입에서 드러낸다 | 현재 매핑 값 그대로(`UNEXPECTED_STATUS`·`UNEXPECTED_EMPTY_BODY`·`UNEXPECTED_BODY` → `ENVELOPE_MISMATCH`). `tests/platform/errors/platform-errors.test.ts` 통과 | +| R4 | `projectCertaintyToUi`(`http-effect-certainty.ts:153-165`)를 지운다 | 배럴 밖이고 소비자가 0곳이다(grep: src·tests·scripts·docs). 다운스트림이 쓸 수 없는 위치라 확장 지점이 아니다 | 없음 | +| R5 | 03-05의 `contractRuntimeFailure` 플래그를 쓰거나 지운다 | 계산하고 버리는 값이 "기록한다"는 주석과 함께 있어 독자를 속인다 | 효과 `MAYBE_APPLIED` | +| R6 | 03-01·03-03의 helper | 5절 B | 5절 B, 각 항목의 보존 조건 | + +## 7. 성능·폴더 구조·테스트 + +### 7.1 성능 + +크기(S1, esbuild 단독 번들, minify, `@tanstack/*`·`zod`·`react` 외부, gzip -9). 단독 번들이라 공유 의존이 겹쳐 세어진다. 실제 청크 배치와 예산 판정은 13 영역이다. + +| 대상 | min | gzip | 기본 조합에 들어가는가 | +|---|---:|---:|---| +| `http` 배럴 전체 | 62,751 B | 18,661 B | 예(V3). V2 본문은 빠진다(S2) | +| `http-execution-v3.ts` 단독 | 34,573 B | 10,787 B | 예 | +| `client.ts`(V2) 단독 | 31,072 B | 10,212 B | 본문은 아니오, 최상위 식 약 0.7KB는 남음(S2) | +| `feature-http-binding.ts` 단독 | 7,100 B | 2,336 B | 예 | +| `query-cache` 배럴 | 22,103 B | 7,514 B | 예 | +| `browser-rpc` 배럴 | 36,457 B | 9,915 B | 아니오(확장 지점, S2에서 문자열 0건) | +| `telemetry` 배럴 | 20,515 B | 7,485 B | 예 | +| `diagnostics` 배럴 | 7,918 B | 2,614 B | 예 | +| `auth` 배럴 | 6,740 B | 2,390 B | 예 | + +- 요청 수: 목록 조회 1회(SAFE, 최대 3회 물리 요청 = 1 + 재시도 2, `reference-feature-contract-contribution.ts:95-100`). 저장 1회(KEYED, 재시도 0) + 성공 뒤 활성 목록 재조회 1회(`refetchType: "active"`, `tanstack-cache-coordinator.ts:83-87`). 결과 불명 뒤에는 자동 요청이 없다. +- 메모리 상한: 진단 기본 100건·최대 10,000건(`bounded-diagnostics.ts:16`, `:26`), 텔레메트리 큐 최대 10,000건(`best-effort-telemetry.ts:68`), 입력 identity 등록부 4,096개·4MiB(`query-keys.ts:198-199`), 진행 중 intent 1,024개(`server-state.ts`의 `MUTATION_COORDINATOR_BOUNDS`). 응답 본문은 계약 상한(목록 256KiB, 상세·생성 32KiB)과 problem 상한으로 막힌다. +- V2 잔여물: 봉투 zod 스키마가 부팅 때 한 번 생성된다. 크기·시간 모두 작아 개선 제안으로만 둔다(R2와 함께 `/*#__PURE__*/` 표시나 지연 생성). + +### 7.2 폴더 구조 + +- 어댑터 폴더 6개는 책임과 맞는다. 배럴이 공개 경계이고 영역 밖에서 내부 파일을 import하는 곳은 경계 검사가 막는다(`check:architecture` PASS). +- `http/`만 예외다. V2·V3가 섞여 있고 V3가 V2 파일에 기댄다(R1, R2). 새 개발자가 "어느 파일이 지금 쓰이는가"를 이름으로 알 수 없다. 배럴 주석(`index.ts:39-48`)이 유일한 안내다. +- 기능 개발자가 실제로 쓰는 위험한 값(분류기, mutation 정책, namespace)은 기능 폴더 세 곳(`contracts/`, `adapters/`, `presentation/`)에 흩어져 있다. 위치 자체는 계층 규칙에 맞지만, 서로를 맞춰야 한다는 사실은 어디에도 없다(3절). + +### 7.3 테스트 + +- 실행 시간: 영역 테스트 70 files / 767 tests가 15.4초다(heavy lock 아래, load 21~22). 검출된 변이는 대부분 3~5초 안에 첫 실패를 냈다(`--bail=1`). 과한 시간은 아니다. 오케스트레이터 게이트 기준으로는 `test:integration` 9.0초, `test:component` 7.0초, `test:unit` 11.7초 안에 이 영역 테스트가 들어 있다. +- 위험을 실제로 잡는가: 실행기의 재시도 권한(M2), 효과 누적(M3), 상태 코드 기본값(M4), 멱등 헤더(M16), 경로 탈출(M17), 세대 fence(M12), 원격 무효화 지연(M11), 전송 상한(M10, M13, M14)은 모두 단위 테스트가 첫 번째로 잡았다. 실패를 만드는 곳에 가까운 테스트가 있다는 뜻이다. +- 빈틈 넷: UNKNOWN identity lease(M1, P-03-06), 분류기 throw의 안전 기본값(M5, 03-05), 서버 반사 correlation 문법(M7), V3 바인딩의 시간 초과 분류(M8). 뒤의 둘은 03-06으로 묶었다. +- 참조 분류기의 409 판정은 통합 시나리오 카탈로그만 고정한다(M21). 참조 기능 폴더의 테스트 70건은 이 변경에 통과했다(E1-fix). 화면의 "충돌" 테스트(`reference-page.test.tsx:412-418`)는 분류기를 거치지 않고 효과가 정해진 실패를 주입한다. P-03-01을 고칠 때 "처리 중 409 → 결과 불명"과 "진짜 충돌 409 → 충돌"을 둘 다 카탈로그에 넣어야 한다(P-03-01 완료 기준에 더한다). +- `http-execution-v3.test.ts`는 `classifyStatus` throw는 다루지만(`:1220-1235`) `classifyProblem` throw는 다루지 않는다(M5 생존). + +## 8. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호는 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 이유·근거 | +|---|---|---|---| +| 1 | 코드 성숙도 | P | 효과 lattice와 intent 검사가 일관된다(`http-effect-certainty.ts:36-73`, `http-execution-v3.ts:378-436`). 마감 경계에서 시간 초과가 요청 위반이 된다(P-03-05). `default` 가지가 새 위반 종류를 흡수한다(R3) | +| 2 | 구조적 성숙도 | > | 12 영역. 오케스트레이터 `check:architecture` PASS | +| 3 | 변경 용이성 | P | 쓰기 하나를 바꾸면 계약·선언 행·mutation 정책 세 파일을 맞춰야 한다(03-03, 07-02). 조회 하나는 namespace 등록을 따로 해야 한다(03-01) | +| 4 | 인지 부하 | P | V3 `execute()` 한 곳 유지는 타당하다(5절 끝). 결과 불명 쓰기 규칙이 분류기·코디네이터·폼·폼 페이지·AsyncSurface에 나뉘어 있다. 효과와 화면 분류가 두 파일이다(03-04) | +| **5** | 위험 가시성 | P | 실행 결과 union이 실패 종류와 효과를 타입으로 드러낸다(`http-execution-v3.ts:126-182`). 조회의 무효화 범위(03-01), mutation 정책과 계약의 관계(03-03), 재전송 안전 조건(P-03-03), 교차 origin CORS 전제(P-03-02)는 코드에서 보이지 않는다 | +| **6** | 실패 성숙도 | P | 마감 하나, 재시도 권한 하나, 결과 불명 자동 재전송 금지가 유지된다(변이 1.2절). 처리 중 409 뒤 키 보호가 풀린다(P-03-01, E1). 키 없는 명령도 재전송된다(P-03-03, E2) | +| 7 | 운영 성숙도 | P | 텔레메트리 라벨이 닫혀 있고 build/release가 찍힌다(`telemetry-collector.ts:91-94`). 진단은 기본 sink가 없어 메모리에만 남는다(`runtime-adapters.ts:322`). 클라이언트 결함과 입력 문제가 같은 `error_kind`로 섞인다(03-02) | +| **8** | 디버깅 가능성 | P | 요청마다 `x-correlation-id`를 보내고 반사값을 `requestId`로 싣는다. 결과 불명 쓰기에 문의 식별자가 없다(P-03-04). 전송 전 실패의 원인이 없다(03-02). 분류기 실패가 보이지 않는다(03-05) | +| 9 | 유지보수 성숙도 | P | 런북 상태표가 코드 위치를 가리킨다. 문서가 막혀 있다고 말하는 규칙(namespace는 레지스트리 참조, 분류기 실패 기록)이 코드에 없다(03-01, 03-05). 백엔드 허용 헤더 목록에 `traceparent`가 없다(P-03-02) | +| 10 | 테스트 성숙도 | P | 영역 테스트 70 files / 767 tests, 15.4초. 변이 21개 중 13개 검출, 동등 변이 4개를 빼면 17개 중 13개(1.2절). 빈틈: UNKNOWN identity lease(P-03-06), 분류기 throw 기본값(03-05), 시간 초과 분류·반사 correlation 문법(03-06) | +| 11 | 데이터 성숙도 | - | 영속 데이터를 쓰지 않는다. 메모리 캐시와 intent만 있다 | +| **12** | 동시성 성숙도 | P | 세대 fence가 늦은 응답을 버린다(`server-state-scope-runtime.ts:99-185`, 변이 M12). 원격 무효화는 진행 중 mutation이 끝날 때까지 미룬다(변이 M11). 같은 입력은 같은 intent다. 처리 중 같은 키 재전송이 닫히면 다음 저장이 다른 작업이 된다(P-03-01). 새로고침·다른 탭은 새 키다(런북 6.3-7에 적힌 한계) | +| 13 | 확장성 | > | 11 영역 | +| 14 | 성능 성숙도 | O | 본문·JSON 구조·재시도·텔레메트리 상한이 계약값이다. 영역 어댑터 크기를 쟀다(7.1절). V2 잔여 약 0.7KB. 예산 판정은 13 영역 | +| **15** | 보안 성숙도 | O | 자격증명 헤더는 프로필이 정하고 transport 소유 헤더를 덮지 못한다(`http-contract-bridge.ts:66-106`. 변이 M9는 허용 목록 검사가 다시 막아 동등). 요청은 `redirect:"error"`, `no-referrer`, `no-store`(`http-execution-v3.ts:905-916`). 경로 값의 `.`·`..`·`/`를 막는다(`http-contract-bridge.ts:198-208`, 변이 M17). 서버 반사 correlation 값은 문법 검사 뒤에만 쓴다(`http-execution-v3.ts:1626`. 이 검사를 고정하는 테스트는 없다, 03-06). subject가 없으면 닫힘 방향이다 | +| 16 | 의존성 성숙도 | > | 13 영역 | +| **17** | API / Contract | P | 결과 union과 설치 검사는 강하다. "처리 중" 응답 status가 계약에 없다(P-03-01). 조회 namespace 계약이 문서와 다르다(03-01). 교차 origin CORS 요구는 문서 통제뿐이다(P-03-02) | +| 18 | 배포 성숙도 | > | 13 영역. P-03-02는 배포 절차에도 걸린다 | +| 19 | 설정 성숙도 | P | `REQUEST_TIMEOUT_MS`는 상한으로만 쓴다(`http-execution-v3.ts:450-456`). 다른 origin 기본 설정의 CORS 요구를 확인하는 수단이 없다(P-03-02) | +| 20 | 개발자 경험 | P | 이번 렌즈 결과(3절). 계약 빈칸은 시작 때 막히지만, 손으로 맞추는 값은 조용하거나 "입력 거절"로 보인다(03-01, 03-02, 03-03). 전체 판정은 14 영역 | +| 21 | Guardrail 성숙도 | P | 설치 검사가 쓰기 계약의 빈칸을 막는다(`external-contract-runtime.ts:468-513`). 미등록 무효화 topic은 첫 저장에서 throw. 조회 namespace(03-01)·mutation 정책(03-03)·재전송 조건(P-03-03)·CORS(P-03-02)는 검사가 없다 | +| **22** | 추상화 성숙도 | P | `FeatureHttpBinding`은 전송 정책을 숨기고 좁다. V3 단일 조율부 유지가 맞다. `BoundMutation`·`QueryDefinition`이 계약과 이어지지 않는다(03-01, 03-03). 효과와 화면 분류가 두 추상화로 나뉜다(03-04) | +| 23 | 일관성 | O | 전송 세 종류의 재시도·`Retry-After`·timeout 차이가 한 표에 있다(`backend-api-and-server-state-contract.md:598-611`). 차이는 의도된 것으로 기록돼 있다 | +| 24 | 네이밍 / 의미 | P | `FINAL_REQUEST_INVARIANT_FAILED`가 입력 검증·조립·불변식·미설치 네 원인을 덮는다(03-02). `resendUnknownEffect` 주석은 "keyed command carries the same key"인데 키 없는 명령에도 동작한다(P-03-03). "recorded as a contract runtime failure" 주석이 사실이 아니다(03-05) | +| 25 | 조직 확장성 | > | 14 영역 | +| 26 | Ownership | P | owner·백엔드 책임이 문서에 있다. 다운스트림 동기화 기록에 CORS 백엔드 작업이 없었다(P-03-02, 지난 라운드 확인, 이번에는 다시 보지 않음) | +| 27 | 삭제 가능성 | P | V2는 배럴에서 표시돼 있지만 V3가 V2 파일 `retry-policy.ts`에 기댄다(R1). 전체 판정은 09·14 영역 | +| 28 | 회복 가능성 | P | 결과 불명 쓰기는 같은 세대 안에서 같은 키로 복구된다(`reference-production-vertical.test.tsx`의 504 → 재전송 테스트, 1.2절 baseline에서 통과). 처리 중 409 뒤와 새로고침·fence 뒤에는 새 키다(P-03-01, 런북 6.3-7) | + +X(미충족)는 없다. 6·12·17·28은 P-03-01(High)이 남아 있어 P다. + +## 9. 미검증 목록 + +| 무엇을 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| 짝 백엔드와의 실제 통합(P-03-01) | 백엔드 코드는 grep으로만 읽었다(2절). E1은 그 응답을 MSW로 흉내 냈다 | 백엔드 통합 환경에서 504 → 같은 키 재전송 → 처리 중 응답 | +| 다운스트림에 03-01·03-03·03-04 경로가 있는가 | 제품 repo를 이번에 읽지 않았다 | tech-log·memento의 조회 정의와 분류기 grep | +| 두 제품의 운영 CORS 허용 헤더(P-03-02) | 배포 환경 값이 repo에 없다 | staging에 대한 preflight 요청 | +| E1·E8의 실제 브라우저 화면 | jsdom에서만 확인했다 | Playwright 수직 시나리오 | +| 미설치 계약 실행(E6b) | 조립 전체를 바꿔야 해서 정적 확인만 했다 | `installed-contract-contributions.ts`를 mock한 `createRuntimeAdapters` 실행 | +| 여러 탭의 결과 불명 쓰기 | intent가 탭 메모리에만 있다는 것은 코드로 확인했다 | 두 컨텍스트 e2e | +| Browser RPC 실제 provider | 기본 조합에 없다(확장 지점, S2) | Connect/gRPC-Web 통합 | +| 실제 번들 예산 대비 크기 | 단독 번들만 쟀다 | 13 영역 측정 | diff --git a/docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md b/docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md new file mode 100644 index 00000000..e91f386a --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md @@ -0,0 +1,293 @@ +# 04 realtime 어댑터 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 깊게 본 관점: 6, 7, 12, 13, 14, 17 + +ID 표기: 이번 라운드의 새 발견은 `04-01`부터 쓴다. 지난 라운드(2026-09-29)의 발견은 `0929/04-01`처럼 앞에 날짜를 붙인다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `src/adapters/realtime/` 16파일 9,790줄. 테스트 `tests/unit/realtime/` 테스트 14파일 + 보조 2파일(`fixture.ts`, `sse-parser-reference.ts`) | +| 커밋·작업 상태 | `d99301b`. `git log af3d8e6..d99301b -- src/adapters/realtime tests/unit/realtime`는 비어 있다. 지난 리뷰 기준 `af3d8e6` 뒤 realtime 코드와 테스트는 한 줄도 바뀌지 않았다. 이 사이 11커밋은 UI 감사·리뷰 문서다 | +| 전제 (0.1) | 템플릿. realtime은 `RECIPE_AVAILABLE` / `AVAILABLE_NOT_COMPOSED`이고 `productionComposition: false`다(`config/recipes/frontend-capability-recipes.json:29-60`). 조합 코드(attempt·session bridge, 환경 신호, 닫기)는 채택 프로젝트 몫이다. 브라우저 SPA, 탭마다 연결 1개(설계 5.6). 조합 코드는 `src/bootstrap`에서 배럴 `src/adapters/realtime/index.ts`만 import할 수 있다(`.dependency-cruiser.json:253-262`) | +| 읽은 코드 | 전부: `reconnect-coordinator.ts`, `sse/fetch-sse-connection.ts`, `result.ts`, `event-consumer.ts`, `stream-coordinator.ts`, `index.ts`와 하위 배럴. 필요한 부분: `websocket/websocket-connection.ts`(리스너, 큐, `processEvent`, heartbeat, 종료 분류), `polling/bounded-poll-coordinator.ts`(lease 루프, 결과 파싱), `live-poll-handoff-coordinator.ts`(머리, `invokeApply`, checkpoint), `event-codec.ts`, `sse/sse-parser.ts`(retry 필드), `reconnect-policy.ts`, `src/application/ports/realtime/*` | +| 읽은 문서(주장) | 설계 `realtime-events-web-push-and-bounded-polling.md` 머리글·5.3~5.6·6.3·6.4·11·13.1·14.1절, `optional-adapter-recipes.md` Realtime 절, `CHANGELOG.md:50`, 지난 리뷰 `2026-09-29-maturity-review/04-adapters-realtime.md`와 README | +| 게이트(오케스트레이터 실행) | `check:architecture`·`check:types`·`lint`·`test:unit` 등 rc=0. `test:unit` 로그에서 realtime 14파일 221건 통과 | +| 직접 실행 | 분리 worktree(`d99301b`, 리뷰 뒤 제거)에서 실행했다. 실험·변이 스크립트와 결과는 오케스트레이터 scratchpad의 `r04/`에 남겼다(`zz-review04-1101.test.ts`, `zz-review04-types.ts`, `zz-perf-04.test.ts`, `zz-measure-04.ts`, `mutate.py`, `*.jsonl`). ① `node scripts/run-vitest.ts run tests/unit/realtime/` → 15파일 229건 통과(기존 221 + 실험 8), 1.93초, 직전 `uptime` 부하 19.5 ② 실험 X1~X4(`tests/unit/realtime/zz-review04-1101.test.ts`) ③ 변이 11건(`scratchpad/r04/mutate.py`, 결과 `mutation-results.jsonl`) ④ `npx tsc -p tsconfig.test.json --noEmit`로 타입 탐침(`zz-review04-types.ts`) ⑤ 마이크로 벤치(`zz-perf-04.test.ts`), 직전 부하 9.4 ⑥ `node scripts/check-realtime-boundaries.ts` → PASS, `node scripts/check-realtime-boundary-fixtures.ts` → PASS(금지 규칙 2건 거절) ⑦ 레시피 번들 측정(8절) | +| 실험 조건 | 가짜 clock·fetch·ReadableStream을 썼다. 정책은 실제 값에 가깝게 두었다(base 1s, max delay 30s, 10회, 5분, stable 30s). SSE 조합은 설계 6.3이 조합 코드에 맡긴 최소 bridge를 실험 파일 안에 직접 썼다(`onOpen`에서 attempt를 끝내고 나머지 `read()`를 session으로 넘김) | +| 확인 못 한 것 | 실제 브라우저·SSE/WS 서버·프록시. `test:realtime-removal`(스크립트가 fixture 안에서 pnpm을 부른다. 지침상 worktree에서 pnpm 금지). 여러 클라이언트 재연결 분포. 브라우저에서의 파서·codec 성능. `0929/04-04`(hidden 탭 heartbeat)는 코드가 그대로라 정적으로만 다시 봤다. 9절에 정리했다 | +| 이전 리뷰와 비교 | 코드가 같으므로 지난 발견 5건의 상태를 코드와 새 실행으로 다시 확인했다. 지난 라운드의 실험 결과(E1~E11)는 증거로 쓰지 않았다 | + +**영역 판정 (35.8)** + +- codec·stream coordinator·WebSocket 연결·polling·handoff: **지정 범위에서 사용 가능.** 입력 검증, 자원 상한, 순서·중복·gap 처리, DRAINING fence가 유지되고 변이로 검출된다(MU6·MU8·MU9·MU10·MU11). 조합할 때 결과 객체 동결 규칙을 알아야 한다(04-01). +- reconnect coordinator + WebSocket: **조건부 사용 가능.** heartbeat ACK를 `markValidHeartbeatOrEvent`로 넘겨야 한다. `classifyClosed`가 만드는 결과는 동결해야 한다(04-01). +- reconnect coordinator + SSE: **해당 용도의 사용 보류.** `0929/04-01`이 그대로다. 브라우저가 online인 채 서버가 내려가거나 스트림이 끊기면 재연결도 종료도 없이 멈춘다(X1·X2). 이를 막는 테스트도 여전히 없다(MU1·MU2 생존). + +## 2. 지난 발견 재확인 + +| 지난 ID | 심각도 | 상태 | 근거 | +| --- | --- | --- | --- | +| 0929/04-01 SSE 네트워크 오류가 `OFFLINE`이 되어 run이 멈춘다 | High · P1 | **남음** | 코드 그대로: SSE는 fetch 거절(`sse/fetch-sse-connection.ts:213-218`)과 reader 거절(`:396-402`)을 `OFFLINE` retryable로 보고한다. coordinator는 `OFFLINE`이면 `requireOnline()`을 부른다(`reconnect-coordinator.ts:798`, `:994-998`). 이 함수는 지금보다 새 online 이벤트를 요구한다(`:424-429`). `waitOnline()`에는 타이머가 없다(`:455-479`). **X1**(연결 전 fetch 거절, 브라우저 online 유지): 20분 동안 fetch 1회, `getState()` `RUNNING`, 결과 없음, 관측은 `ATTEMPT_STARTED` 하나. **X2**(40초 열린 스트림에서 reader 거절): 20분 동안 fetch 1회, `RUNNING`, 결과 없음, 관측은 `ATTEMPT_STARTED`·`SESSION_OPENED`·`SESSION_CLOSED` 뒤 아무것도 없다. **막는 테스트:** 없다. 지난 리뷰의 2줄 수정(MU1)을 넣어도 realtime 221건이 모두 통과한다. SSE 쪽에서 `OFFLINE`을 `PROVIDER_UNAVAILABLE`로 바꾼 변이(MU2)도 모두 통과한다. `fetch-sse-connection.test.ts`에는 `OFFLINE`을 확인하는 줄이 하나도 없다 | +| 0929/04-02 SSE↔reconnect 세션 bridge 부재, 열린 SSE 세션 테스트 없음 | Medium · P2 | **남음** | 템플릿이 주는 도구는 여전히 `readSseForReconnect` 하나다(`fetch-sse-connection.ts:487-507`). SSE↔coordinator 테스트는 두 묶음 모두 "Only connect failures are exercised here"다(`realtime-reconnect-coordinator.test.ts:1931`, `:1995`). 이번 X2·X3도 리뷰어가 bridge를 직접 써서 재현했다 | +| 0929/04-03 SSE `retry:` 처리 규칙이 설계 5.3·6.3과 코드에서 다르다 | Low · P3 | **남음** | 파서는 `maxRetryMs`(60s)를 넘는 값을 버린다(`sse/sse-parser.ts:330-341`). **X3**(정책 max delay 30s, `retry:` 뒤 idle timeout): `retry: 45000` → fetch 1회, 재시도 없이 `IDLE_TIMEOUT retryable:true`로 끝남. `retry: 90000` → 값을 버리고 0.5초 뒤 재연결. 서버가 더 긴 대기를 요구할수록 더 빨리 재연결한다 | +| 0929/04-04 hidden 탭에서 heartbeat를 멈춘 조용한 WS는 예산을 새로 받지 못한다 | Low · P3 | **남음**(정적 확인) | `heartbeatEligible`에 여전히 주석이 없다(`websocket/websocket-connection.ts:177`). false면 heartbeat를 보내지 않는다(`:1083-1088`). 예산 초기화에는 유효 신호가 필요하다(`reconnect-coordinator.ts:888-900`). 이번에 실험은 다시 하지 않았다 | +| 0929/04-05 CHANGELOG [계약] 문장이 초기화 조건보다 넓다 | Low · P3 | **남음** | `CHANGELOG.md:50`은 여전히 "세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다"고 적는다. 코드는 유효 신호와 안정 유지를 모두 채운 세션만 초기화한다(`reconnect-coordinator.ts:888-900`). online 복귀 때 elapsed를 다시 시작한다(`:550-559`) | + +지난 라운드 README의 개선 순서 1번은 "04-01은 막는 테스트를 함께 넣는다"였다. 이 항목은 진행되지 않았다. + +## 3. 대표 흐름 (체크리스트 2절) + +### 3.1 피해가 큰 흐름 — 열린 SSE 스트림 중 서버가 연결을 끊는다 (0929/04-01, X2) + +```text +입력 조합 코드가 coordinator.run(). bridge가 onOpen에서 attempt를 끝내고 read()를 session으로 넘김 +상태 SESSION_OPENED. comment마다 markValidHeartbeatOrEvent +외부I/O 40초 뒤 프록시·백엔드 재시작으로 reader.read()가 reject. navigator.onLine은 계속 true +실패 fetch-sse-connection.ts:396-402 → OFFLINE(RECEIVE, retryable) + → classifyClosed가 그대로 넘김 → reconnect-coordinator.ts:994-998 requireOnline() +정책 다음 루프 :550 offlineWait=true → :551 waitOnline() → 새 online 이벤트만 기다림 +결과 20분 동안 재시도 0, 결과 없음, RETRY_SCHEDULED·RUN_ENDED 관측 없음 + stream freshness는 마지막 값(보통 CURRENT)에 머문다(리뷰어 추론: 새 event가 없어 바꿀 계기가 없다) +``` + +### 3.2 계약 흐름 — 조합 코드가 만든 결과를 경계가 받는다 (04-01, X4) + +```text +입력 조합 코드(src/bootstrap)가 classifyClosed에서 { result: { ok: true, value: undefined } } 반환 + → 타입은 통과한다(zz-review04-types.ts가 tsc 오류 0) +정책 reconnect-coordinator.ts:1384 parseResult가 동결되지 않은 결과를 거절 +결과 run이 PROTOCOL_MISMATCH(CONNECT, retryable:false)로 끝난다(X4b) +같은 값을 stream coordinator의 effects.apply가 반환하면 APPLIED로 받아들인다(X4d, stream-coordinator.ts:583) +``` + +### 3.3 변경 흐름 — 백엔드가 이벤트 종류를 추가한다 + +지난 리뷰의 흐름과 같다. codec이 `PROTOCOL_MISMATCH`/`REGISTRY`로 닫고(`event-codec.ts:172-176`), consumer가 그 stream을 `UNKNOWN`으로 바꾼다(`event-consumer.ts:87-91`). 코드가 바뀌지 않았고 `event-codec.test.ts`가 이번 실행에서도 통과했다. + +## 4. 새 발견 (36.3) + +### 04-01 `RealtimeResult`를 받는 경계마다 런타임 규칙이 다르고, 동결이 필요한 경계에 넘길 결과를 만드는 공개 함수가 배럴에 없다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(계약이 타입·문서에 드러나지 않음) | +| 관련 관점 | 17, 5, 20, 23, 8, 22, 10, 4 | +| 근거 | ① 같은 `RealtimeResult` 타입(`src/application/ports/realtime/shared.ts:64-66`, `Readonly<...>`일 뿐)을 받는 경계가 두 규칙으로 나뉜다. **동결 필수**: reconnect coordinator의 attempt·`classifyClosed`·`confirmTransportBarrier` 결과(`reconnect-coordinator.ts:1384`, `:1428`, `:1440`), handoff의 `apply`·`establishAuthoritativeCheckpoint`(`live-poll-handoff-coordinator.ts:339-344`, `:598-603`), SSE `onOpen`·`onEvent`(`fetch-sse-connection.ts:277`, `:347`), WS `onSubscribed`·`onEvent`(`websocket-connection.ts:906`, `:1016`). 모두 `isRealtimeResult`(`result.ts:194-199`)나 같은 검사로 2단계 `Object.freeze`를 요구한다. **동결 불필요**: stream coordinator의 `effects.apply`·`recovery.recover`(`stream-coordinator.ts:583`, `:774`, `snapshotRealtimeResult`로 한 번 복사), polling `execute`(`bounded-poll-coordinator.ts:616-654`). ② 결과를 만드는 `realtimeSuccess`/`realtimeFailure`(`result.ts:46-65`)는 배럴(`src/adapters/realtime/index.ts`)에서도, application port(`src/application/ports/realtime/*`)에서도 export되지 않는다. 배럴 밖의 조합 코드는 내부 파일을 import할 수 없다(`.dependency-cruiser.json:253-262`). 조합 예시는 테스트 안에만 있고, 테스트는 `result.ts`를 직접 import한다(`realtime-reconnect-coordinator.test.ts:26-29`). ③ 동결 규칙은 타입 주석(`reconnect-coordinator.ts:41-52`, `:90-104`), 설계 문서, `optional-adapter-recipes.md` 어디에도 없다. ④ **실험 X4**: 타입이 맞는 평범한 객체를 넘기면 — attempt 실패 → 1회 시도 뒤 `PROTOCOL_MISMATCH` 종료(동결하면 1분 동안 8회 재시도) / `classifyClosed` 성공 → `PROTOCOL_MISMATCH` 종료 / handoff `apply` 성공 → `MAPPING_CONTRACT_VIOLATION` / stream coordinator `effects.apply` 성공 → `APPLIED`(정상). ⑤ 같은 평범한 객체 3종이 `tsc -p tsconfig.test.json`에서 오류 없이 컴파일된다(`zz-review04-types.ts`). ⑥ **변이 MU4**: reconnect coordinator의 동결 검사 3곳을 지워도 realtime 221건이 모두 통과한다. 이 규칙은 reconnect 경계에서 테스트로 고정돼 있지 않다(헬퍼 단위로는 `result.test.ts:29`가 고정) | +| 발생 조건 | 채택 프로젝트가 reconnect bridge의 `classifyClosed`(예: SSE `EOF`를 재시도 실패로 바꾸기, 0929/04-02), handoff `apply`, 직접 쓴 `onEvent`·`onOpen`에서 결과를 손으로 만들 때. 배럴만 쓸 수 있으므로 손으로 만드는 경우가 기본이다 | +| 영향 | 연결이 첫 종료나 첫 실패에서 재시도 없이 끝난다. 오류 이름이 `PROTOCOL_MISMATCH`·`MAPPING_CONTRACT_VIOLATION`이라 원인(동결 누락)을 가리키지 않는다. 한 경계에서 통한 습관(stream coordinator·polling)이 다른 경계에서 실패한다. 매 실행 결정적으로 실패하므로 첫 통합 시험에서 드러난다. 운영에서 조용히 숨는 결함은 아니다 | +| 심각도·우선순위 | Medium · P2. 모든 조합자가 지나는 경계이고 진단 비용이 반복된다. fail-closed이고 첫 실행에서 드러나서 High는 아니다 | +| 통제·증거 | 규칙 구현 M2(경계 코드에 일관 적용) · 명시 M0(문서·주석 없음) · reconnect 경계 위반 검출 없음(MU4 생존). 증거 E1(코드) + E2(X4 실험, tsc 탐침, MU4) | +| 확실성과 남은 가정 | 코드와 실험으로 확인했다. 채택 프로젝트가 실제로 결과를 손으로 만드는지는 조합 코드가 없어 미확인이다. 다만 배럴만 허용되므로 다른 경로가 없다 | +| 결정의 근거 | 확인한 사실: reconnect coordinator는 받은 결과 객체를 그대로 돌려준다. 테스트가 `toBe`로 같은 객체인지 확인한다(`realtime-reconnect-coordinator.test.ts:291`). 그래서 이 경계는 원본을 재사용할 수 있도록 동결을 요구한다. stream coordinator는 한 번 복사해 새 객체를 쓴다(`result.ts:182-192` 주석). 두 방식은 각자 타당하다. 기록된 의도: 헬퍼 주석은 "rereading a mutable result"를 막는다고 한다(`result.test.ts:17`). 리뷰어 추론: 경계마다 다른 이유로 다른 규칙을 골랐고, 조합자에게 그 차이를 알리는 장치만 빠졌다. 41절 검토는 6.2절 | +| 이해 비용 | 조합자는 결과가 어느 경계로 가는지, 그 경계가 원본을 재사용하는지 알아야 한다. 그러려면 `result.ts`의 `requireFrozenSource` 인자와 각 경계의 파서를 읽어야 한다 | +| 최소 개선 방향 | 배럴에서 `realtimeSuccess`·`realtimeFailure`를 export한다(2줄). `RealtimeReconnectOutcome`·`RealtimeReconnectSession`·handoff `apply` 주석에 "결과는 `realtimeSuccess`/`realtimeFailure`로 만든다(동결 필수)"를 한 줄 적는다 | +| 대안 비교 | 6.2절. (a) 현상 유지 (b) 생성 함수 export + 주석(제안) (c) 엄격한 경계도 복사 방식으로 바꿔 동결을 요구하지 않기 (d) application port에 생성 함수를 두기 | +| 단순화의 보존 조건 | reconnect coordinator가 마지막 실패 객체를 그대로 돌려주는 계약(`:291` `toBe`)을 유지한다. 2단계 동결 모양과 `DEFAULT_RETRYABLE` 기본값(`result.ts:28-34`)을 바꾸지 않는다 | +| 비용·부작용 | export 2줄, 주석 몇 줄. 레시피 번들 영향은 없다(측정은 tree-shaking 없이 모든 모듈을 이미 포함한다, `scripts/lib/optional-recipe-bundle.ts:61-64`) | +| 재검토 조건 | 엄격한 경계 중 하나가 복사 방식으로 바뀌면 규칙을 하나로 합칠 수 있다. 조합 코드가 생겨 같은 실수가 반복되면 런타임 오류 이름을 따로 두는 것을 다시 본다 | +| 완료 기준 | 배럴만 import한 조합 코드가 동결된 결과를 만들 수 있다. 각 엄격한 경계의 주석에 규칙이 있다. reconnect 경계에 "동결되지 않은 결과는 거절" 테스트가 있어 MU4가 실패한다 | +| 검증 방법 | X4a~c를 테스트로 옮긴다. MU4를 다시 돌려 실패하는지 본다. `check:architecture`로 조합 코드가 배럴만 쓰는지 확인한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 지난 리뷰는 X4 같은 손으로 만든 결과를 시험하지 않았다. 테스트는 모두 `result.ts`를 직접 import해서 이 문제를 지나치지 않는다 | + +### 04-02 `IDLE_TIMEOUT`이 effect·recovery·close 마감에도 쓰여, 설계 13.1의 의미(전송 idle → 제한된 재연결)와 다르다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(코드와 설계의 어휘 불일치) | +| 관련 관점 | 24, 23, 8, 7, 17 | +| 근거 | ① 설계 13.1은 `IDLE_TIMEOUT`을 "heartbeat/byte deadline 초과 → close + bounded reconnect"로 정의한다(`realtime-events-web-push-and-bounded-polling.md:1891`). feature effect 실패는 `APPLY_FAILED`다(`:1906`). ② stream coordinator는 effect 마감 초과를 `IDLE_TIMEOUT`/`APPLY`/`retryable:false`로(`stream-coordinator.ts:557-566`), recovery 마감을 `IDLE_TIMEOUT`/`RECOVER`/false로(`:749-758`), close drain 초과를 `IDLE_TIMEOUT`/`CLOSE`로(`:1029-1031`) 보고한다. 테스트가 이 값을 고정한다(`stream-coordinator.test.ts:50`, `:99`). ③ 같은 "effect가 너무 오래 걸림"을 WS 연결은 자기 마감(30s)에서 `APPLY_FAILED`로 보고한다(`websocket-connection.ts:1019-1039`). stream coordinator 마감(기본 5s, `:61-66`)이 먼저 끝나므로 실제로는 `IDLE_TIMEOUT`이 나온다. ④ consumer는 이 실패를 그대로 transport에 넘긴다(`event-consumer.ts:184`). SSE는 그대로 read 결과로 돌려준다(`fetch-sse-connection.ts:355-357`). reconnect coordinator는 `retryable:false`라 run을 끝낸다. 관측은 `RUN_ENDED failureKind:IDLE_TIMEOUT reason:TERMINAL`이다(`reconnect-coordinator.ts:1596-1613`). 관측 타입에는 `operation`이 없다(`:134-152`) | +| 발생 조건 | feature effect가 5초, recovery가 10초를 넘을 때 | +| 영향 | 운영 지표에서 "서버가 조용해짐"과 "우리 effect가 멈춤"을 failureKind로 구분할 수 없다. 13.1 표를 보고 조합 코드를 쓰면 `IDLE_TIMEOUT`을 재연결 대상으로 보고 새 run을 만든다. stream은 effect가 끝날 때까지 `DRAINING`이라(`stream-coordinator.ts:244`) 새 run은 `CLOSED`를 받고 다시 끝난다(리뷰어 추론, 실행 미확인). 데이터 손상은 없다. effect가 끝나면 다음 event가 recovery부터 한다(`:246-250`, `:417-422`) | +| 심각도·우선순위 | Low · P3. 진단과 조합 판단을 헷갈리게 하지만 fail-closed다 | +| 통제·증거 | M1(13.1이 다른 의미를 적음) · E1(코드), E2(기존 테스트가 값을 고정) | +| 확실성과 남은 가정 | 코드 경로는 확인했다. SSE→reconnect까지 이 값이 지나는 것은 코드로 따라갔고 실행하지 않았다 | +| 결정의 근거 | 적용 제외 — 마감 초과 때 fail-closed하고 `DRAINING`으로 두는 선택(R-02, 설계 머리글 `:38-45`)은 유지한다. 문제는 그 결과에 붙인 이름이다. 6.3절에 선택 자체를 짧게 검토했다 | +| 이해 비용 | 같은 kind가 `operation`에 따라 뜻이 바뀐다는 것을 알아야 한다. reconnect 관측에서는 `operation`이 보이지 않는다 | +| 최소 개선 방향 | 둘 중 하나. (a) stream coordinator의 effect·recovery 마감을 `APPLY_FAILED`/`APPLY`, `PROVIDER_UNAVAILABLE`/`RECOVER`처럼 13.1에 맞는 kind로 바꾸고 테스트 기대값을 고친다. (b) 13.1 표의 `IDLE_TIMEOUT` 행에 "`operation` APPLY·RECOVER·CLOSE는 내부 task 마감, retry 없음"을 추가한다 | +| 대안 비교 | (a)는 어휘가 13.1과 맞고 WS 마감과도 같아진다. 테스트 몇 건을 고친다. (b)는 코드 0줄이지만 관측에서 여전히 구분이 안 된다. 관측에 `operation`을 넣는 것은 저카디널리티 원칙에는 맞지만 타입 변경이 생긴다 | +| 단순화의 보존 조건 | 마감 초과 뒤 `DRAINING` 유지, `recoveryRequired`·`resumeState` 폐기(`stream-coordinator.ts:243-250`), `retryable:false`를 유지한다 | +| 비용·부작용 | (a) 코드 3곳과 테스트 기대값 몇 건 | +| 재검토 조건 | 조합 코드가 생겨 failure kind로 재연결을 결정하게 되면 (a)로 정한다 | +| 완료 기준 | 13.1 표와 코드가 같은 의미를 말한다. effect 마감과 전송 idle을 관측에서 구분할 수 있다 | +| 검증 방법 | 문서 리뷰와 `stream-coordinator.test.ts` 기대값 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음. 지난 리뷰는 이 경로를 보지 않았다 | + +### 04-03 WebSocket 구독별 초당 이벤트 상한(256)이 테스트도 설계 11절 상한표에도 없다 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(테스트·문서 공백) | +| 관련 관점 | 10, 13, 9, 21 | +| 근거 | ① WS 연결은 구독마다 1초 창에서 이벤트 수를 센다. `maxEventsPerSecond`(기본 256, 서버 광고값과 작은 쪽, `websocket-connection.ts:208`, `:1692-1695`)를 넘으면 `EVENT_RATE_EXCEEDED` recovery를 요청하고 `QUEUE_OVERFLOW`/`CURSOR_RESET`로 닫는다(`:983-1006`). ② **변이 MU7**: 이 검사를 꺼도 realtime 221건이 모두 통과한다. `tests/`에 `EVENT_RATE_EXCEEDED`를 확인하는 줄이 없다. ③ 설계 11절 상한표(`realtime-events-web-push-and-bounded-polling.md:1763-1789`)에 이 값이 없다. 표 아래에 "event rate가 지속적으로 ceiling 근처라면"이라는 문장만 있다(`:1815-1816`). 비교로, 같은 파일의 inbound queue 상한은 테스트가 잡는다(MU8 검출) | +| 발생 조건 | 서버가 한 구독에 초당 256건 넘게 보낼 때. 또는 이 검사를 실수로 지우거나 단위(초)를 바꾸는 변경 | +| 영향 | 검사가 회귀해도 CI가 모른다. 그러면 폭주하는 서버에 대한 방어가 inbound queue 상한(256건/4MiB)만 남는다. 상한이 문서에 없어 채택자가 서버 광고값을 정할 근거가 없다 | +| 심각도·우선순위 | Low · P3. 현재 코드는 동작한다(정적 확인). 회귀 탐지와 문서 공백이다 | +| 통제·증거 | M2(구현) · 위반 검출 없음(MU7 생존) · E1, E2(MU7) | +| 확실성과 남은 가정 | 변이로 확인. 검사 자체가 맞게 동작하는지는 정적으로만 봤다 | +| 결정의 근거 | 적용 제외 — 기존 상한에 테스트와 문서 한 줄을 붙이는 문제다 | +| 이해 비용 | 상한을 바꾸려는 사람이 설계 11절만 보면 이 상한이 있는 줄 모른다 | +| 최소 개선 방향 | `websocket-connection.test.ts`에 같은 1초 안에 257번째 이벤트가 오면 `QUEUE_OVERFLOW`와 `EVENT_RATE_EXCEEDED` recovery 요청이 나오는 테스트 1건. 설계 11절 표에 "WebSocket 구독별 event rate | 초당 256" 한 행 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 1건, 문서 1행 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | MU7이 실패한다. 11절 표에 값이 있다 | +| 검증 방법 | MU7 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | +| 직전 리뷰 | 해당 없음 | + +## 5. 테스트 렌즈 — 변이 실험 + +worktree에서 한 건씩 넣고 `node scripts/run-vitest.ts run tests/unit/realtime/`을 돌린 뒤 되돌렸다. 기준 실행은 229건 통과, 1.93초다. + +| ID | 관점 | 변이 | 결과 | +| --- | --- | --- | --- | +| MU1 | 6 | coordinator에서 환경이 offline일 때만 `requireOnline()`(0929/04-01 수정안 b) | **생존** — 0929/04-01 동작을 고정한 테스트가 없다 | +| MU2 | 6, 17 | SSE fetch·reader 거절을 `PROVIDER_UNAVAILABLE`로 보고(수정안 c) | **생존** — SSE 네트워크 거절 분류를 확인하는 테스트가 없다 | +| MU4 | 17 | reconnect coordinator의 동결 검사 3곳 제거 | **생존** → 04-01 | +| MU5 | 12 | `confirmTransportBarrier`의 `queuedEvents !== 0` 조건 제거(`stream-coordinator.ts:968`) | **생존**. 리뷰어 판단: 남은 대기 이벤트는 generation fence(`:402-404`)가 막으므로 실제 피해는 작다. 발견으로 올리지 않았다 | +| MU6 | 12 | `processEvent`의 DRAINING 재확인 제거(`:401`) | 검출(1건) | +| MU7 | 13 | WS 초당 이벤트 상한 끔 | **생존** → 04-03 | +| MU8 | 13 | WS inbound queue 상한 끔 | 검출(1건) | +| MU9 | 6, 12 | 마감 초과 때 `DRAINING`으로 바꾸지 않음(`:244`) | 검출(5건) | +| MU10 | 13 | dedupe 상한 비교 `<` → `<=` | 검출(1건) | +| MU11 | 13, 14 | codec의 stream별 `maxEventBytes` 검사 제거 | 검출(1건) | +| MU14 | 6 | polling executor 거절을 `PROVIDER_UNAVAILABLE`로 | 검출(1건). 다만 실패 메시지가 아니라 10초 테스트 시간 초과로 드러났다(11.3초) | + +정리: 11건 중 6건 검출, 5건 생존. 생존 5건 중 3건(MU1·MU2·MU4)은 "조합 코드와 만나는 경계"에 있다. 내부 상태 기계(DRAINING, 큐, dedupe, 크기 상한)는 잘 고정돼 있다. 실행 시간은 과하지 않다. realtime 전체가 2초 안팎이고, 가장 긴 파일은 `stream-coordinator.test.ts` 791ms다(오케스트레이터 `test:unit` 로그). + +## 6. 설계 선택 검토 (41절) + +### 6.1 transport가 보고한 `OFFLINE`도 새 `online` 이벤트를 기다린다 (0929/04-01의 뿌리) + +1. **무엇이 필요한가:** 기기가 정말 offline이면 타이머로 헛된 재시도를 하지 않는다. 그 밖의 실패는 재연결하거나 예산 안에서 끝나야 한다. +2. **지킬 성질:** 어떤 실패 뒤에도 run은 재시도하거나 결과를 돌려준다. 무기한 대기는 조합 코드가 fallback으로 넘어갈 기회를 없앤다(설계 5.3 "budget을 소진하면 … fallback"). +3. **현재 보장:** 환경이 offline을 알린 경우는 맞게 동작한다(`observeOnline`, `reconnect-coordinator.ts:446-452`). **보장하지 않는 것:** transport가 스스로 `OFFLINE`을 보고하면 환경이 online이어도 새 online 이벤트를 요구한다(`:798`, `:994-998`). SSE는 모든 네트워크 거절을 `OFFLINE`이라 부른다(`fetch-sse-connection.ts:213-218`, `:396-402`). polling도 executor 거절을 `OFFLINE`이라 부르고 lease를 끝낸다(`bounded-poll-coordinator.ts:318-323`, `:388-393`). WS는 같은 상황을 `PROVIDER_UNAVAILABLE`로 부른다(`websocket-connection.ts:427-439`). 설계 5.3은 "`navigator.onLine`은 backend reachability authority가 아니다"라고 적는다(`:780`). 13.1은 `OFFLINE`을 "network hint/attempt failure"로 넓게 적는다(`:1889`). +4. **대안:** (a) 현상 유지 (b) coordinator 두 곳에서 환경이 offline일 때만 online 이벤트 요구 (c) SSE·polling이 네트워크 거절을 `PROVIDER_UNAVAILABLE`로 보고 (d) online 대기에 상한 시간. +5. **비교:** (a)는 X1·X2의 멈춤이 남는다. (b)는 2줄이고 모든 transport에 적용된다. MU1에서 기존 221건이 모두 통과했다. 환경 이벤트보다 transport가 먼저 실패를 보면 헛시도가 한두 번 생기지만 시도 상한(10회) 안이다. (c)는 SSE·polling 각 1~2줄이고 어휘가 WS와 같아진다. 대신 polling 테스트 1건(`bounded-poll-coordinator.test.ts:897`)의 기대값이 바뀐다. (b)와 (c)는 함께 쓸 수 있다. (d)는 상수와 상태가 늘어난다. +6. **현재 조건에서의 판단:** 작성 의도는 기록에 없다. 현상 유지 근거는 이번에도 찾지 못했다. (b)를 먼저 하고, 어휘 정리가 필요하면 (c)를 더한다. 어느 쪽이든 X1·X2를 테스트로 옮겨야 MU1·MU2가 실패한다. +7. **재검토 조건:** 실제 reachability 확인(가벼운 health 요청)을 환경 신호로 쓰게 되면 (d)나 별도 대기 상태를 다시 비교한다. + +### 6.2 경계마다 결과 동결을 요구하거나 요구하지 않는다 (04-01) + +1. **무엇이 필요한가:** 외부에서 받은 결과를 검증한 뒤 다시 읽어도 값이 바뀌지 않아야 한다(TOCTOU 방지). +2. **지킬 성질:** 검증한 값과 쓰는 값이 같다. reconnect coordinator는 받은 실패 객체를 그대로 돌려준다(`realtime-reconnect-coordinator.test.ts:291` `toBe`). +3. **현재 보장:** 엄격한 경계는 원본을 쓰므로 동결을 요구한다(`result.ts:311-322` `requireFrozenSource`). 느슨한 경계는 한 번 복사한다(`snapshotRealtimeResult`, `:187-192`). 두 방식 모두 성질 2를 지킨다. **보장하지 않는 것:** 조합자가 어느 경계가 엄격한지 알 수단이 없다. 엄격한 경계에 넘길 결과를 만들 공개 함수도 없다. +4. **대안:** (a) 현상 유지 (b) 생성 함수 2개를 배럴에서 export하고 엄격한 경계의 타입 주석에 규칙을 적는다 (c) 엄격한 경계도 복사 방식으로 바꾼다 (d) 생성 함수를 application port(`shared.ts`)에 둔다. +5. **비교:** (a)는 모든 조합자가 한 번씩 막힌다. (b)는 2줄과 주석이고, 동결 규칙은 그대로 둔다. (c)는 규칙이 하나가 되지만 "같은 객체를 돌려준다"는 기존 테스트 계약(`:291`)을 깬다. 복사본을 돌려주도록 계약을 바꿔야 한다. (d)는 feature application 코드도 쓸 수 있게 되지만, application 계층에 런타임 헬퍼가 생긴다. 지금 port 폴더에는 `realtimeTransportRecoveryCommitted`(`event-authority.ts:156-168`)라는 선례가 있다. +6. **현재 조건에서의 판단:** (b)가 가장 작다. feature effect 작성자도 결과를 만들어야 하므로(handoff `apply`), 선례를 따라 (d)도 타당하다. 리뷰어는 (b)를 권하고, handoff `apply`를 feature가 구현하는 것으로 정해지면 (d)로 옮긴다. +7. **재검토 조건:** 조합 코드가 생겨 결과를 만드는 위치가 bootstrap인지 feature인지 정해지면 다시 본다. + +### 6.3 effect·recovery 마감을 넘으면 fail-closed하고 stream을 `DRAINING`으로 둔다 (04-02 배경) + +1. **무엇이 필요한가:** 멈춘 effect 하나가 stream 전체를 영구히 막으면 안 된다. 동시에 늦게 끝난 effect가 새 상태를 덮어쓰면 안 된다. +2. **지킬 성질:** 마감 초과 뒤 그 effect는 commit할 수 없다. 끝날 때까지 새 작업을 시작하지 않는다. 끝난 뒤에는 recovery부터 한다. +3. **현재 보장:** 마감 때 commit 권한을 끊고(`stream-coordinator.ts:536-540`), `DRAINING`으로 바꾸고(`:244`), 재개 토큰을 버린다(`:248-250`). task가 끝나면 `OPEN`·`STALE`로 돌아간다(`:221-229`). MU6·MU9가 검출됐다. **보장하지 않는 것:** effect가 끝내 settle하지 않으면 그 stream은 `close()` 전까지 `DRAINING`이다. 새 event는 `CLOSED`로 거절된다(`:293-297`). 이것이 의도라고 머리글이 적는다(`realtime-events-web-push-and-bounded-polling.md:40-45`). +4. **대안:** (a) 현재 방식 (b) 마감 초과 task를 버리고 바로 `OPEN` (c) 마감 없이 기다림. +5. **비교:** (b)는 늦은 effect가 recovery 결과를 덮어쓸 수 있다. (c)는 멈춘 effect 하나가 stream을 영구히 막는다. (a)는 이름(04-02)만 정리하면 된다. +6. **현재 조건에서의 판단:** 기록된 의도(R-02)와 코드가 같고 변이로 고정돼 있다. 유지한다. +7. **재검토 조건:** effect가 자주 5초를 넘는 feature가 생기면 `effectTimeoutMs`를 registry로 옮길지 본다. + +## 7. 리팩토링 후보 + +| ID | 대상 | 무엇을 왜 | 보존할 동작·타입·실패 계약 | 권고 | +| --- | --- | --- | --- | --- | +| R-1 | `reconnect-coordinator.ts` `runLoop`(`:360-1031`, 약 670줄) | offline 뒤 drain 블록이 sleep(`:586-601`), attempt(`:710-735`), waitClosed(`:909-930`) 세 곳에 거의 같은 모양으로 있다. 하나의 내부 함수로 합치면 루프가 짧아진다 | drain 상한(2초 고정, `REALTIME_RECONNECT_CEILINGS.drainTimeoutMs`), `TIMED_OUT` → `PROVIDER_UNAVAILABLE`, task가 끝날 때까지 `DRAINING` 유지. 세 곳은 결과가 다르다: sleep은 기존 retry를 유지하고, attempt는 `pendingRecovery`의 terminal을 넘기고, waitClosed는 `session=null` 뒤 `RECEIVE` retry를 만든다. 테스트 `realtime-reconnect-coordinator.test.ts:1350`, `:1408`, `:1541`이 각 경로를 고정한다 | P3. 0929/04-01을 고칠 때 같이 하면 비용이 작다 | +| R-2 | 같은 파일 `:784-799`, `:976-999` | attempt 실패와 close 분류가 같은 일(`captureRetry` + `OFFLINE`이면 `requireOnline`)을 두 번 한다. 한 함수로 모으면 0929/04-01 수정이 한 곳에 들어간다 | 서버 hint 전달(`serverNotBeforeMs`), `pendingRecovery` terminal 우선, 환경 offline 때 타이머 없음(테스트 `:400-435`, `:437-467`) | P2. 0929/04-01 수정과 한 커밋 | +| R-3 | `src/adapters/realtime/index.ts` | 결과 생성 함수 export(04-01) | 2단계 동결 모양, `DEFAULT_RETRYABLE` | P2. 04-01 수정 자체 | +| R-4 | clock 읽기 헬퍼 4벌(`reconnect-coordinator.ts:1623`, `bounded-poll-coordinator.ts:782`, `fetch-sse-connection.ts:620`, `websocket-connection.ts:1513`) | 두 변형이다(`>= 0` 요구 여부). 합치고 싶어진다 | SSE·WS는 `Retry-After` 날짜 계산에 epoch를 쓰므로 `>= 0`이 필요하다. reconnect·polling은 상대 시간만 쓴다 | **하지 않음 권장.** 차이에 이유가 있고, 합치면 kernel(`platform/`)에 파일이 하나 늘어난다. 이득이 작다 | + +## 8. 성능·확장성 렌즈 + +| 항목 | 측정값 | 조건 | +| --- | --- | --- | +| codec decode | 이벤트당 15.9µs(342B) · 20.2µs(1.35KB) · 33.7µs(3.8KB) | Node 24, 테스트 registry(스키마가 단순), 20,000건, 직전 부하 9.4. 구독 하나가 상한(초당 256)이면 한 코어의 약 0.9%다. 구독 32개가 모두 상한이면 약 28%다. 실제 zod 스키마와 브라우저는 미측정 | +| SSE 파서 | 46.7MB/s(64B 이벤트, 이벤트당 1.8µs) · 438.6MB/s(1KB) · 1,323MB/s(32KB) | 같은 조건, 청크 약 200KB를 200번 | +| 레시피 번들(gzip) | 40,886 / 예산 40,900(여유 14). 상세 8.1절 | `measureOptionalRecipeBundle`, tree-shaking 끔 | +| 테스트 실행 시간 | realtime 221건 약 2초 | 직전 부하 19.5 | + +메모리 상한(큐 256건/4MiB, dedupe, 구독 32, outbound 128건/256KiB)은 코드와 변이(MU8·MU10)로 확인했다. 서버 재시작 직후 여러 클라이언트의 재연결 분포는 측정하지 않았다. 0929/04-01이 고쳐지기 전에는 SSE 클라이언트가 아예 재연결하지 않으므로, 수정 뒤 처음으로 재연결 폭주 여부를 볼 수 있다. + +### 8.1 레시피 번들 + +`scripts/lib/optional-recipe-bundle.ts`의 `measureOptionalRecipeBundle`을 worktree에서 직접 불렀다(`zz-measure-04.ts`, heavy lock 안에서). 메모리 빌드라 포트를 쓰지 않는다. 크기 측정이라 부하의 영향은 없다. + +| 측정 대상 | 소스 파일 | 원본 bytes | gzip bytes | +| --- | --- | --- | --- | +| realtime 레시피 전체(카탈로그 `sourceRoots`) | 36 | 148,415 | **40,886 / 예산 40,900, 여유 14** | +| `src/adapters/realtime` 단독 | 16 | 100,416 | 28,631 | +| `src/adapters/web-push` 단독 | 12 | 41,977 | 11,239 | +| `websocket/` 단독 | 3 | 29,444 | 8,745 | +| `reconnect-coordinator.ts` 단독 | 1 | 21,468 | 7,023 | +| `stream-coordinator.ts` 단독 | 1 | 22,806 | 6,888 | +| `sse/` 단독 | 3 | 17,088 | 6,287 | +| `polling/` 단독 | 2 | 12,923 | 4,604 | +| `live-poll-handoff-coordinator.ts` 단독 | 1 | 12,531 | 4,340 | +| `event-codec.ts` 단독 | 1 | 11,199 | 4,117 | + +단독 측정은 import한 `result.ts`·contracts·platform을 함께 묶는다. 그래서 행끼리 겹치고 합이 전체와 맞지 않는다. 비교용이다. + +해석: + +- 값은 지난 리뷰와 같은 40,886이다. 코드가 바뀌지 않았으니 맞다. +- 예산(`frontend-capability-recipes.json` `bundleBudgetGzipBytes: 40900`)은 설계 11절이 말하듯 "회귀 예산"이다(`realtime-events-web-push-and-bounded-polling.md:1800-1803`). 여유가 14바이트라 0929/04-01의 2줄 수정이나 04-01의 export 2줄도 예산을 넘길 가능성이 높다. 리뷰어 판단: 늘어날 때마다 예산을 명시적으로 올리게 하는 의도로 보이며 결함으로 올리지 않는다. 다만 수정 커밋에 예산 인상을 같이 넣어야 한다는 점을 수정자가 알아야 한다. +- production 번들에는 realtime이 들어가지 않는다(`productionComposition: false`). 사용자 성능 영향은 없다. + +## 9. 폴더 구조 렌즈 + +- 루트 8파일은 transport와 무관한 부품이다(codec, consumer, stream coordinator, reconnect, handoff, result). transport별 구현은 `sse/`, `websocket/`, `polling/`에 있다. 위치가 책임과 맞는다. +- `live-poll-handoff-coordinator.ts`가 `polling/`이 아니라 루트에 있는 것은 live와 poll 양쪽에 걸치기 때문이다. 맞는 위치다. +- `sse/fetch-sse-connection.ts`가 루트의 `reconnect-coordinator.ts`에서 타입을, `reconnect-policy.ts`에서 함수를 가져온다(`:15-16`). 방향은 transport → 공통이다. 반대 방향은 없다. +- 찾기 어려운 곳은 "결과를 어떻게 만드는가"다. 답이 `result.ts`에 있지만 배럴에 없어 조합자가 찾을 수 없다(04-01). +- 결론: 구조 변경은 필요 없다. + +## 10. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 판정 | 근거·잔여 위험 | +| --- | --- | --- | --- | +| 1 | 코드 성숙도 | O | 상태 기계(IDLE/RUNNING/DRAINING/CLOSED), terminal·idempotent close. 221건 통과(게이트, worktree 재실행) | +| 2 | 구조적 성숙도 | O | kernel·ports·contracts만 import. `check:architecture` rc=0(오케스트레이터), realtime boundaries PASS(직접) | +| 3 | 변경 용이성 | P | 이벤트 종류 추가는 생성 시 대조한다. SSE 조합은 bridge를 직접 써야 하고(0929/04-02), 결과를 손으로 동결해야 한다(04-01) | +| 4 | 인지 부하 | P | `runLoop` 약 670줄, drain 블록 3벌(R-1). 조합자는 markValid 출처, `OFFLINE` 의미, 동결 규칙을 알아야 한다 | +| 5 | 위험 가시성 | P | `isCurrent`·markValid·환경 신호 책임은 주석에 있다(`reconnect-coordinator.ts:58-63`, `:106-113`, `:175-181`). 동결 규칙(04-01)과 `OFFLINE` 대기(0929/04-01)는 코드 안쪽에만 있다 | +| 6 | 실패 성숙도 | **X** | SSE 네트워크 오류 뒤 run이 무기한 멈춘다(0929/04-01, X1·X2). 서버 `retry:` 값에 따라 결과가 뒤집힌다(0929/04-03, X3). 내부 마감·DRAINING은 잘 고정됐다(MU9) | +| 7 | 운영 성숙도 | P | reconnect·poll 관측 어휘가 닫혀 있다(`:128-152`). online 대기는 관측이 없다(X1: `ATTEMPT_STARTED`만, X2: `SESSION_CLOSED` 뒤 없음). `IDLE_TIMEOUT`이 두 뜻이고 관측에 `operation`이 없다(04-02) | +| 8 | 디버깅 가능성 | P | `REGISTRY` operation으로 구버전을 구분한다. 동결 누락이 `PROTOCOL_MISMATCH`·`MAPPING_CONTRACT_VIOLATION`으로 보인다(04-01). online 대기와 연결 중이 모두 `RUNNING`이다 | +| 9 | 유지보수 성숙도 | P | 설계 문서의 줄 번호 참조는 코드가 안 바뀌어 지금도 맞다. CHANGELOG `:50`이 넓다(0929/04-05). 11절 표에 rate 상한이 없다(04-03). 13.1이 `IDLE_TIMEOUT`을 좁게 정의한다(04-02) | +| 10 | 테스트 성숙도 | P | 221건 통과. 변이 11건 중 6건 검출, 5건 생존(MU1·MU2·MU4·MU5·MU7). 지난 리뷰가 요청한 0929/04-01 막는 테스트는 아직 없다. MU14는 10초 시간 초과로만 드러난다 | +| 11 | 데이터 성숙도 | O | cursor는 effect 성공 뒤에만 전진한다(`stream-coordinator.ts:583-596`). 메모리에만 있다. 바뀐 곳 없음 | +| 12 | 동시성 성숙도 | O | run 1개(`reconnect-coordinator.ts:363-364`), recovery single-flight(`stream-coordinator.ts:665`), DRAINING 재확인(MU6 검출), 마감 초과 fence(MU9 검출). MU5 생존은 generation fence가 받쳐 영향이 작다 | +| 13 | 확장성 | P | 큐·dedupe·크기 상한은 변이로 고정됐다(MU8·MU10·MU11). WS rate 상한은 고정·문서 모두 없다(04-03). 레시피 번들 여유 14바이트(8.1절). 재연결 분포는 미측정 | +| 14 | 성능 성숙도 | P | codec 이벤트당 16~34µs, 파서 47~1,323MB/s(Node). 브라우저 미측정. 레시피 번들 40,886/40,900 gzip(production 번들에는 없음) | +| 15 | 보안 성숙도 | O | 고정 same-origin HTTPS(`fetch-sse-connection.ts:509-529`), URL에 credential 없음, 401/403 즉시 종료(`:583-588`). 바뀐 곳 없음 | +| 16 | 의존성 성숙도 | O | 외부 패키지 없음. native API는 facade로 주입. boundary 검사 PASS | +| 17 | API/Contract 성숙도 | P | 결과 동결 규칙이 경계마다 다르고 숨어 있다(04-01). `OFFLINE`이 두 뜻이다(0929/04-01). `retry:` 규칙이 설계 두 곳과 다르다(0929/04-03). `IDLE_TIMEOUT`이 13.1과 다르게 쓰인다(04-02) | +| 18 | 배포 성숙도 | P | 새 이벤트 종류는 구버전 탭에서 `REGISTRY`로 드러난다. 백엔드 배포가 SSE 연결을 reset하면 멈춘다(0929/04-01, X2) | +| 19 | 설정 성숙도 | P | 정책은 생성 시 검증한다(`reconnect-policy.ts:43-67`). 파서 `maxRetryMs`와 정책 `maxDelayMs`가 따로 논다(0929/04-03) | +| 20 | 개발자 경험 | P | SSE bridge 예시가 없다(0929/04-02). 배럴만으로는 결과를 만들 수 없다(04-01) | +| 21 | Guardrail 성숙도 | O | realtime boundaries·fixture PASS, 배럴 규칙(`.dependency-cruiser.json:253-262`). 다만 배럴 규칙과 생성 함수 부재가 맞물려 04-01을 만든다 | +| 22 | 추상화 성숙도 | P | attempt/session 경계가 transport를 잘 숨긴다. SSE는 이 경계에 맞추는 부품이 없다(0929/04-02). 결과 경계 규칙이 둘이다(04-01) | +| 23 | 일관성 | P | 네트워크 거절이 SSE·polling은 `OFFLINE`, WS는 `PROVIDER_UNAVAILABLE`이다. effect 마감이 stream coordinator는 `IDLE_TIMEOUT`, WS는 `APPLY_FAILED`다(04-02). 동결 요구가 경계마다 다르다(04-01) | +| 24 | 네이밍/의미 | P | `OFFLINE`(0929/04-01), `IDLE_TIMEOUT`(04-02) | +| 25 | 조직 확장성 | - | 작성자 1인. registry `owner` 필드가 필수인 것만 확인 | +| 26 | Ownership | - | 제품 조합이 없다. recipe `owner: project-owner-required`(`frontend-capability-recipes.json:68`) | +| 27 | 삭제 가능성 | ? | `test:realtime-removal`은 fixture 안에서 pnpm을 부른다(`scripts/lib/removal-fixture.ts:185-196`). 지침상 실행하지 않았다. 오케스트레이터 게이트 목록에도 없다 | +| 28 | 회복 가능성 | P | gap·cursor 만료 → snapshot 복구는 유지된다. SSE 네트워크 오류 뒤 스스로 회복하지 못한다(0929/04-01) | + +## 11. 미검증 목록 + +| 항목 | 확인하지 못한 이유 | 확인하려면 | +| --- | --- | --- | +| 0929/04-01이 실제 브라우저·서버에서 같은 모양인지 | 실제 SSE 서버와 브라우저 실행 없음 | 로컬 SSE 서버 + Playwright로 서버 재시작(설계 15.3) | +| `test:realtime-removal` | pnpm 호출, 지침상 금지 | CI 또는 메인 트리 단독 실행 | +| 04-02의 SSE→reconnect 경로 실행 | 정적으로만 따라감 | effect가 5초 넘게 걸리는 실험 | +| 0929/04-04 재실험 | 코드가 같아 정적 확인만 | WS `heartbeatEligible: () => false` 실험 | +| 여러 클라이언트 재연결 분포 | 부하 실험 없음 | N개 클라이언트 시뮬레이션 | +| 브라우저에서 codec·파서 성능, 실제 zod 스키마 비용 | Node 마이크로 벤치만 함 | 브라우저 performance 측정 | diff --git a/docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md b/docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md new file mode 100644 index 00000000..a855fa3c --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md @@ -0,0 +1,322 @@ +# 영역 05 — 저장소·adapter kernel + +> 검토일: 2026-11-01 · 기준: 브랜치 `fix/ui-design-audit-2026-11-01` / `d99301b` (워킹트리는 추적되지 않는 `.claude/`만 있다) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 경로: `src/adapters/storage/`(Web Storage, `indexeddb/`, `opfs/`), `src/adapters/platform/`(adapter kernel), `src/adapters/browser-file-storage/`. 판정에 필요해서 함께 읽은 것: `src/application/ports/browser-file-storage/*`, `src/application/ports/storage-port.ts`, `src/contracts/storage-keys.ts`, `src/contracts/diagnostics.ts`, `src/bootstrap/runtime-adapters.ts`·`boot-release-recovery.ts`·`optional-runtime-host.ts`, `src/adapters/telemetry/telemetry-collector.ts`(pagehide 부분), `src/adapters/cross-context-invalidation/*`(pulse 부분), `.dependency-cruiser.json:242-254`, `eslint.config.ts`(browser-data 예외 부분), `docs/architecture/layers.md:38-52`, `config/recipes/frontend-capability-recipes.json:76-115`, `recipes/frontend-capabilities/browser-file-storage-contracts.ts`(port 이름 부분) +> 깊게 본 관점: 1, 11, 12, 22, 27, 28 +> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드와 같다. 이 영역 코드는 `af3d8e6` 이후 한 줄도 바뀌지 않았다. 그래서 지난 발견 10건이 모두 남아 있다. kernel과 Web Storage 어댑터는 지정 범위에서 쓸 수 있다. IndexedDB 런타임은 개인 데이터에도 쓸 수 있으나 릴리스 롤백 중 계정 삭제는 데이터를 남긴다([0929] 05-05). OPFS 런타임은 "계정 삭제 뒤 기기에 바이트가 남지 않는다"를 요구하는 제품이면 [0929] 05-01·05-02를 고친 뒤 조합한다. + +ID 표기: 지난 라운드(2026-09-29) 발견은 `[0929] 05-NN`, 이번 라운드 새 발견은 `05-NN`으로 쓴다. + +## 0. 결론 + +- **이 영역은 지난 리뷰 뒤 바뀌지 않았다.** `git diff --stat af3d8e6 d99301b -- src/adapters/storage src/adapters/platform src/adapters/browser-file-storage src/application/ports/browser-file-storage recipes config/recipes`는 빈 결과다. 이번 라운드의 커밋 11개는 UI 감사와 리뷰 문서뿐이다. +- **지난 발견 10건은 모두 남았다.** 코드 위치를 현재 커밋에서 다시 읽었다. [0929] 05-01은 기존 테스트가 그 동작을 그대로 고정하고 있다(`tests/unit/indexeddb-opfs-journal.test.ts:491-511`, `:669-680`). [0929] 05-09는 다시 실행해 거절되지 않는 것을 확인했다. [0929] 05-04는 다시 측정했다. offline-indexeddb 예산 여유는 여전히 9바이트다(36,891/36,900). +- **새 발견은 6건이고 모두 Low다.** 이번 라운드에 처음 깊게 본 Web Storage 어댑터(실제로 조립되는 유일한 저장소 어댑터)와 kernel의 작은 파일들에서 나왔다. + - registry의 pulse 키 행이 실제로 쓰는 값과 다른 codec을 적는다. StoragePort로 읽으면 다른 어댑터의 값을 지운다(05-01, 재현). + - Web Storage 진단 이벤트가 실패 원인을 버린다. 값 손상도 `STORAGE_UNAVAILABLE`로 남는다(05-02, 재현). + - kernel의 lifecycle 런타임은 "창 lifecycle 리스너의 유일한 주인"이라고 적는다. 실제로는 telemetry가 자기 `pagehide` 리스너를 단다. 이 규칙을 보는 검사도, lifecycle 런타임을 직접 부르는 테스트도 없다(05-03). + - kernel 폴더에 공유 메커니즘이 아닌 port 구현 2개가 있어 폴더 단위 예외를 그냥 받는다(05-04). + - kernel 주석의 `file:line` 참조가 이미 다른 코드를 가리킨다(05-05). + - Web Storage 어댑터·codec 변이 8개 중 5개를 테스트가 잡지 못한다(동작 기준). 대부분 기본 구성에서 도달하지 않는 확장 경로다. Firefox quota 이름 하나는 지금도 도달한다(05-06). +- **High 이상은 없다.** 지난 라운드의 Medium 3건([0929] 05-01·05-02·05-03)이 그대로 이 영역의 가장 큰 위험이다. + +## 1. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template` 영역 05 | +| 커밋·상태·시점 | `d99301b`, 2026-11-01. 영역 경로는 `af3d8e6`과 같다(위 `git diff --stat` 빈 결과). 판정에 쓴 바깥 파일 중 바뀐 것도 없다 | +| 실행 환경 | Node v24.14.0, 22 스레드. 다른 영역 에이전트가 동시에 돌아 loadavg 3.4~23 | +| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. 여러 탭 동시 실행. SSR 없음 | +| 조합 상태 | 기본 bootstrap이 조립하는 것은 Web Storage 어댑터 두 벌(`runtime-adapters.ts:420`, `boot-release-recovery.ts:57`)과 kernel의 `createBrowserMutationIntentFactory`(`runtime-adapters.ts:32`)다. IndexedDB·OPFS·StorageManager 런타임은 `AVAILABLE_NOT_COMPOSED`, `productionComposition: false`다(`config/recipes/frontend-capability-recipes.json:76-101`). lifecycle 런타임은 SW나 realtime이 켜질 때만 만든다(`optional-runtime-host.ts:88-92`). 기본 구성에서는 만들지 않는다 | +| 규모·운영 목표 | 없다. 13·14번은 미검증으로 둔다. 14번은 측정값만 적는다 | +| 읽은 코드 | Web Storage 어댑터·codec 전부, kernel 10개 파일 전부, `browser-file-storage/` 3개 파일 전부, `browser-opfs-runtime.ts` 전부, `opfs-worker-client.ts`의 RPC·소유 worker 부분, `indexeddb-migrations.ts` 전부, 지난 발견이 가리킨 위치 전부(journal 목록·purge·전체 삭제·정책 검사·이름 접두사·승인 정규식·canonical JSON), 두 sub-barrel | +| 주장으로만 읽은 것 | 지난 리뷰 `2026-09-29-maturity-review/05-adapters-storage-kernel.md`, `docs/architecture/layers.md` kernel 절, 코드 주석의 설계 설명 | +| 실행한 명령 | 아래 표. 무거운 실행은 공용 `heavy.lock`으로 감쌌다. 변이·재현 실험은 `scratchpad/wt-05`(d99301b worktree, 메인 `node_modules` 심볼릭 링크)에서 했다. worktree 안에서는 pnpm을 부르지 않았다 | +| 확인하지 못한 범위 | Playwright(`indexeddb-runtime.spec.ts`, `opfs-runtime.spec.ts`)를 이번에는 돌리지 않았다. 제거 드릴(`test-browser-file-storage-runtime-removal.ts`)은 fixture 안에서 pnpm을 부르므로 지침에 따라 돌리지 않았다. 지난 라운드의 X1~X5·I1~I4 재현은 실험 파일이 남아 있지 않아 다시 하지 않았다. 대신 코드 위치가 같다는 것과 기존 테스트 통과로 판단했다(2절) | +| 이전 리뷰와 비교 | 지난 발견 10건을 현재 코드로 다시 확인했다(2절). 지난 실행 결과(테스트 수, Playwright 16/16, 드릴 PASS, 변이 7/7)는 이번 증거로 쓰지 않았다 | + +| 명령·실험 | 결과 | +|---|---| +| `node scripts/run-vitest.ts run` + 영역 테스트 13개 파일(OPFS 3, IndexedDB 4, storage-manager, storage-registry, abortable-operation, system-clock, runtime-adapters, `tests/contract/consumer-experience/indexeddb-local-draft.test.ts`) | **290/290 통과**, 1.69초(transform 4.87초 포함 wall 2.2초). 실행 직전 loadavg 10.3 | +| 오케스트레이터 게이트 로그(`scratchpad/gates/`) | `check:architecture`·`check:types`·`lint`·`test:unit`·`test:integration`·`test:contract`·`check:adapter-inventory` rc=0. `check:adapter-inventory`: 145 files PASS, shared abort primitive 22 importers PASS. `test:system` rc=1은 `ci-artifact-contract.test.ts`의 `ps` 실패 2건으로 이 영역과 무관하다 | +| X1 재현 `scratchpad/r05/x1-pulse.ts` | registry의 pulse 키에 cross-context 어댑터가 쓰는 원시 JSON을 넣고 `read("CACHE_INVALIDATION_PULSE")` → `{ok:true}`(값 없음), `removeItem` 1회, 진단 `discard:CACHE_INVALIDATION_PULSE` / `STORAGE_UNAVAILABLE`. 이어서 `write(..., "hello")` → 키에 envelope `{"schemaVersion":1,"expiresAt":null,"value":"hello"}`가 써짐(05-01·05-02) | +| X2 재현 `scratchpad/r05/x2-policy.ts` | `resolveOpfsRuntimePolicy({putIdleTimeoutMs: 3_600_000, mutationLockWaitTimeoutMs: 1_000})` → 거절 없이 받아들여짐([0929] 05-09) | +| 변이 실험 `scratchpad/05-mutate.mjs` 14개 | 1차(변이 대상을 직접 부르는 테스트 파일만, 파일 단위 실행이라 lock 없이, 17:59 loadavg 19): 14개 중 **4개 검출**(W1 tombstone, W3 overlay 정리, K1 JSON 중복 키 escape, K2 Retry-After 날짜 형식), 10개 생존. 2차(생존 10개를 `tests/unit`·`component`·`integration`·`contract` 전체 2,734개로, `heavy.lock` 안, 18:12 loadavg 16): 7개 생존(W4, W6, W8, K3, K4, K5, O1). W2·W5·W7은 `two-feature-install-typecheck.test.ts` 하나만 실패했다. 이 테스트는 앱 타입 검사를 돌린다. 변이 코드가 남긴 미사용 선언에 걸린 것이고 동작을 본 것이 아니다. 선언을 남기도록 다시 쓴 W2·W5는 생존했다. W7은 다시 써도 타입 오류(never 좁힘)로만 걸린다. 지금 registry에서는 동작이 같은 변이다. **동작 기준 생존 9개/14개.** 한 번에 약 24초(2차) | +| `node scripts/check-optional-recipes.ts`(worktree) | `Optional recipes: PASS`, `bundle=NOT_BUILT`, 예산 `file-transfer:55623/55700`, `offline-indexeddb:36891/36900`, `realtime:40886/40900`, `service-worker-pwa:9662/10000` gzip bytes(`heavy.lock` 안) | +| esbuild 0.28.1 `--bundle --minify --format=esm`, gzip -9 | Web Storage 배럴 12,792 B / gzip 4,029 B(이 중 어댑터 3,540 B·codec 2,496 B, 나머지는 공유 contracts). kernel 배럴 5,323 / 2,068. IndexedDB 배럴 56,727 / 15,376. OPFS 배럴 88,005 / 22,780. `browser-file-storage` 배럴 4,534 / 1,851 | + +## 2. 지난 발견 재확인 + +상태: 해결 / 남음 / 바뀜. 심각도·우선순위는 지난 판정을 다시 따져 본 결과다. 조합 상태와 코드가 같으므로 모두 그대로 둔다. + +| ID | 제목 (요약) | 상태 | 심각도·우선 | 현재 근거 | +|---|---|---|---|---| +| [0929] 05-01 | OPFS journal 손상 한 건이 그 partition의 계정 삭제 purge와 authority 전체 reconcile·GC를 멈춘다 | **남음** | Medium · P2 | `listIncomplete`·`listCommittedObjects`가 손상 행 하나에 `context.fail(corrupt)`로 목록 전체를 실패시킨다(`indexeddb-opfs-journal.ts:714-723`, `:786-795`). purge는 그 실패를 그대로 반환한다(`opfs-byte-store-adapter.ts:797-799`). `isChunkReferenced`도 같다(`journal:848-855`). 기존 테스트가 "손상 행 하나면 목록 전체 `CORRUPT_DATA`"를 기대값으로 고정한다(`tests/unit/indexeddb-opfs-journal.test.ts:491-511`, `:669-680`, 이번 실행에서 통과). 즉 고치려면 이 테스트도 함께 바꿔야 한다 | +| [0929] 05-02 | purge가 지우지 못한 객체를 건너뛰고도 `chunkSweep: "COMPLETED"`로 보고 | **남음** | Medium · P2 | `CONFLICT`·`NOT_FOUND`면 `continue`(`opfs-byte-store-adapter.ts:820-823`). sweep 조건은 `!moreObjectsAvailable && !deadlineReached && !aborted`(`:855-861`). port 주석은 여전히 "once every object is removed"(`opfs-ports.ts:137`) | +| [0929] 05-03 | recipe의 같은 이름 port·fake가 src port와 다른 계약 | **남음** | Medium · P2 | `DurableObjectStorePort`(`recipes/frontend-capabilities/browser-file-storage-contracts.ts:590`), `DurableObjectMaintenancePort`(`:632`), `MemoryDurableObjectStore`(`browser-file-storage-fakes.ts:1691`). 마지막 변경 `6c52cdb9`(2026-07-30). catalog가 그 fake를 이 런타임의 fake로 적는다(`frontend-capability-recipes.json:106-107`) | +| [0929] 05-04 | offline-indexeddb 레시피 예산 여유가 거의 없다 | **남음** | Low · P2 | 이번 측정 `offline-indexeddb:36891/36900`. 여유 9바이트, 지난 측정과 바이트 단위로 같다(코드가 같으므로 당연하다). 예산 근거 문서는 여전히 없다. 이 영역의 어떤 수정([0929] 05-01·05-02 포함)도 예산 인상을 함께 요구한다. 이번에는 증가 변이를 다시 넣지 않았다 | +| [0929] 05-05 | IndexedDB 전체 삭제 경로의 적용 범위가 port·runbook 설명과 다르다 | **남음** | Low · P3 | 삭제 조건은 `POLICY_REJECTED`·`CORRUPT_DATA`뿐이다(`indexeddb-runtime.ts:2580-2587`). `RETENTION_SWEEP`이 아닌 모든 action이 이 경로를 탄다(`:2554-2558`). 덧붙임: OPFS에도 같은 계열의 길이 있다. `createBrowserOpfsRuntime`은 지원 판정이 실패하면 모든 메서드가 실패하는 런타임을 돌려준다(`browser-opfs-runtime.ts:94-97`, `:182-216`). 판정은 정책 값 `allowAsyncWritableChunkFallback`에 묶여 있다(`:165-170`). 다음 release가 이 값을 끄면 동기 접근 핸들이 없는 엔진에서 기존 OPFS 데이터의 `enforcePolicies(ACCOUNT_DELETION)`이 `UNSUPPORTED`로 끝난다(코드로만 판단, 별도 발견으로 세지 않음) | +| [0929] 05-06 | 한 레시피의 두 런타임이 삭제 승인 계약을 다르게 요구 | **남음** | Low · P3 | proof 정규식 `{16,128}`(`indexeddb-runtime.ts:97`)과 `{16,512}`(`opfs-byte-store-adapter.ts:1785`). 승인 콜백 1개 대 2개 | +| [0929] 05-07 | canonical JSON 3벌, OPFS `sameScope` 2벌 | **남음** | Low · P3 | `opfs-prepared-object.ts:138`, `cache-storage/public-cache-codec.ts:632`, `realtime/event-codec.ts:414`. `sameScope`는 `indexeddb-opfs-journal.ts:1303`, `opfs-worker-runtime.ts:1657` | +| [0929] 05-08 | kernel 범위 설명이 실제보다 좁고 편입 기준이 한 파일에만 있다 | **남음** | Low · P3 | `docs/architecture/layers.md:43-46`과 `.dependency-cruiser.json:242`는 여전히 "clock, abort primitive, capacity guard"라고 적는다. 편입 기준("must never own" 목록)은 `indexeddb-connection.ts:19-24`에만 있다. 새 발견 05-04가 이 기준 부재의 결과다 | +| [0929] 05-09 | `putIdleTimeoutMs < mutationLockWaitTimeoutMs`가 주석에만 있다 | **남음** | Low · P3 | 주석 `opfs-policy.ts:23-29`, 검사는 범위만 본다(`:102-107`). X2 실행에서 3,600,000 / 1,000 조합이 받아들여졌다 | +| [0929] 05-10 | OPFS journal DB 접두사를 설정으로 바꿀 수 없다 | **남음** | Low · P3 | `indexeddb-opfs-journal.ts:131` `ca-frontend-opfs-metadata-v1:`, `indexeddb-governance.ts:83` `ca-idb-v1:` 고정 | + +지난 라운드의 "설계 선택" 판단 세 가지(OPFS 동시성, IndexedDB 전체 삭제 조건, kernel 경계는 메커니즘만)는 코드가 같으므로 결론도 같다. 이번 라운드에는 다른 선택 세 가지를 4절에서 본다. + +## 3. 새 발견 (36.3) + +| ID | 심각도 | 우선 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 05-01 | Low | P3 | 확인된 결함 | 23, 24, 17, 5, 11 | registry의 `CACHE_INVALIDATION_PULSE` 행이 실제 값과 다른 codec을 적어, StoragePort로 읽으면 다른 어댑터의 값을 지운다 | +| 05-02 | Low | P3 | 확인된 결함 | 8, 24, 7 | Web Storage 진단 이벤트가 실패 원인을 버려 값 손상과 저장소 불가를 구분할 수 없다 | +| 05-03 | Low | P3 | 확인된 결함 | 5, 21, 10, 23 | lifecycle 런타임의 "유일한 리스너 주인" 규칙이 이미 깨졌고, 검사도 직접 테스트도 없다 | +| 05-04 | Low | P3 | 개선 제안 | 22, 2, 9 | kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 단위 예외를 받는다 | +| 05-05 | Low | P3 | 확인된 결함 | 9, 4, 24 | kernel 주석의 `file:line` 참조가 다른 코드를 가리킨다 | +| 05-06 | Low | P3 | 구조적 위험 | 10, 15, 11 | Web Storage 어댑터·codec의 분기 5개를 테스트가 잡지 못한다 | + +### 05-01 registry의 `CACHE_INVALIDATION_PULSE` 행이 실제 값과 다른 codec을 적어, StoragePort로 읽으면 다른 어댑터의 값을 지운다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (계약 불일치, 재현) | +| 관련 관점 | 23, 24, 17, 5, 11 | +| 근거 | ① registry 행은 `backend: "localStorage"`, `classification: "opaque-cache"`, `schemaVersion: 1`, `valueCodec: "opaque-string-v1"`이다(`src/contracts/storage-keys.ts:102-113`). `getStorageDefinition`은 이 키를 막지 않는다(`:173-184`). 그래서 StoragePort의 read·write·remove 대상이다.
② 실제로 이 물리 키에 쓰는 쪽은 cross-context 어댑터다. 이름만 registry에서 가져오고(`browser-cross-context-host.ts:35-37`, 주석 "The registry owns the physical-key policy for the pulse"), 값은 envelope 없이 `JSON.stringify(event)`를 `localStorage.setItem`으로 바로 쓴다(`browser-cross-context-invalidation.ts:398-402`).
③ Web Storage 어댑터는 envelope가 아닌 값을 읽으면 손상으로 보고 물리 키를 지운다(`browser-storage-adapter.ts:108-117`, `:84-100`).
④ 재현 X1: 원시 이벤트 JSON이 있는 상태에서 `read("CACHE_INVALIDATION_PULSE")` → `{ok:true}`, `removeItem("ca-frontend:cache-invalidation:v1:pulse")` 1회, 진단 경고 1건. 반대로 `write`는 그 키에 envelope 문자열을 쓴다. cross-context 수신 쪽은 이것을 잘못된 wire 이벤트로 버린다(`browser-cross-context-invalidation.ts:202-206`) | +| 발생 조건 | 다운스트림이 registry를 보고 이 키를 StoragePort로 읽거나 쓸 때. 현재 repo에는 그런 호출이 없다(`grep '"CACHE_INVALIDATION_PULSE"'` 0건) | +| 영향 | 지금은 피해가 거의 없다. 발행 쪽이 `setItem` 직후 `removeItem`을 하므로 지워질 값이 남아 있는 시간이 짧다. 수신 쪽도 `newValue`가 문자열이 아니면 무시한다. 문제는 registry가 "이 키는 Web Storage 어댑터가 opaque string으로 다룬다"는 거짓 정보를 준다는 점이다. 한 물리 키를 두 어댑터가 서로 다른 형식으로 다루는데, 그 사실은 어느 쪽 코드에도 적혀 있지 않다 | +| 심각도·우선순위 | Low · P3. 현재 도달 경로가 없고 도달해도 피해가 작다. 사용자가 정한 원칙("개발자가 따로 기억해야 하는 숨은 위험")에 해당해 결함으로 센다 | +| 통제·증거 | "registry 행은 그 키를 실제로 다루는 방식을 적는다" 규칙: M0 확인(행과 실제 writer를 잇는 검사 없음) · E2(X1 재현) | +| 확실성과 남은 가정 | 재현은 실제 어댑터 코드와 가짜 `Storage`로 했다. 브라우저 storage 이벤트까지는 돌리지 않았다. registry 쪽은 영역 07, cross-context 쪽은 영역 02 코드다. 오케스트레이터가 합칠 수 있다 | +| 결정의 근거 | [기록] pulse 키 이름을 registry에 둔 이유는 물리 키 정책을 한 곳에서 갖기 위해서다(`browser-cross-context-host.ts:35`, N-09). [추론] 이름만 빌리려고 넣은 행이 codec·schema 칸까지 채워야 해서 사실과 다른 값이 들어갔다. `StorageBackend`에 "다른 어댑터가 직접 다룬다"를 뜻하는 값이 없다 | +| 이해 비용 | registry만 읽는 사람은 이 키를 StoragePort로 다룰 수 있다고 본다. 사실을 알려면 cross-context 어댑터 두 파일을 열어야 한다 | +| 최소 개선 방향 | (a) `StorageBackend`에 `"external"` 같은 값을 더하고, `getStorageDefinition`이 그 키를 거절하게 한다. 물리 키 이름은 그대로 registry가 만든다. (b) 또는 행 위에 "이 키는 cross-context 어댑터가 원시 JSON으로 직접 쓴다. StoragePort로 다루지 않는다" 한 줄과 함께 `classification`을 막는 값으로 바꾼다 | +| 대안 비교 | (a) 현상 유지: 피해는 작지만 registry가 사실과 다르다. (b) 주석만: 가장 싸다. 다만 StoragePort 호출을 막지 못한다. (c) backend 값 추가(위 a): registry 타입이 바뀌고 `defineStorageKey` 검사 한 줄이 는다. 잘못된 호출을 실행 시점에 막는다. (d) cross-context 어댑터가 StoragePort를 통해 쓰게 한다: 수신 쪽이 envelope을 풀어야 하고, storage 이벤트의 `newValue` 형식이 바뀐다. 이미 배포된 탭과 섞이면 서로 못 읽는다. 기각. (c)를 권한다 | +| 단순화의 보존 조건 | 물리 키 문자열 `ca-frontend:cache-invalidation:v1:pulse`는 바뀌면 안 된다(배포된 탭 사이의 채널이다). cross-context wire 형식은 그대로 둔다 | +| 비용·부작용 | `StorageBackend` 유니온 값 하나, registry 검사 한 줄, 테스트 하나 | +| 재검토 조건 | registry에 "이름만 빌리는" 행이 하나 더 생길 때 (c)가 확실히 낫다 | +| 완료 기준 | `storage.read("CACHE_INVALIDATION_PULSE")`가 물리 키를 지우지 않고 실패를 돌려준다. registry 행의 칸이 실제 writer와 모순되지 않는다 | +| 검증 방법 | X1을 `tests/unit/storage-registry.test.ts`에 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 05-02 Web Storage 진단 이벤트가 실패 원인을 버려 값 손상과 저장소 불가를 구분할 수 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (재현) | +| 관련 관점 | 8, 24, 7 | +| 근거 | ① 어댑터 내부 원인은 넷이다: `QUOTA_EXCEEDED`, `SIZE_LIMIT_EXCEEDED`, `UNAVAILABLE`, `VALUE_REJECTED`(`browser-storage-adapter.ts:29-33`). 손상된 envelope은 `VALUE_REJECTED`로 바뀐다(`:310-316`).
② 진단 이벤트는 `error_kind`에 quota면 `STORAGE_QUOTA_EXCEEDED`, 나머지는 모두 `STORAGE_UNAVAILABLE`을 넣는다(`:364-385`). 원인은 버린다.
③ 호출자에게 돌려주는 실패의 `code`에는 원인이 들어 있다(`:342`, 예: `LOCALE_READ_VALUE_REJECTED`). 진단 쪽만 잃는다.
④ 진단 계약은 taxonomy 칸 `reason`을 허용한다(`src/contracts/diagnostics.ts:85`). 쓰지 않을 뿐이다.
⑤ 재현 X1: 손상 값 discard가 `{"operation":"discard:CACHE_INVALIDATION_PULSE","error_kind":"STORAGE_UNAVAILABLE"}`로 기록됐다 | +| 발생 조건 | 저장된 값이 깨졌거나 이전 schema일 때, 값이 크기 상한을 넘을 때 | +| 영향 | 운영자는 "브라우저 저장소를 못 쓴다"(사파리 private 모드 등)와 "저장된 값이 깨져서 버렸다"를 같은 이벤트로 본다. 둘은 대응이 다르다. 앞의 것은 환경 문제고, 뒤의 것은 배포한 codec이나 schema 문제일 수 있다 | +| 심각도·우선순위 | Low · P3. 기능 피해는 없다. 진단 정보가 줄어든다 | +| 통제·증거 | M1(원인은 코드에 있으나 진단까지 가지 않음) · E2(X1) | +| 확실성과 남은 가정 | 진단 수집기가 `reason` 칸을 실제로 내보내는지는 영역 03 소관이라 보지 않았다 | +| 결정의 근거 | 적용 제외 — 이미 있는 원인 값을 이미 허용된 칸에 싣는 단순 수정이다 | +| 이해 비용 | 운영자는 이벤트만 보고 원인을 좁힐 수 없다. 코드를 열어야 `STORAGE_UNAVAILABLE`이 넷 중 셋을 뜻한다는 것을 안다 | +| 최소 개선 방향 | `recordStorageFailure`의 context에 `reason: cause`를 더한다 | +| 대안 비교 | 적용 제외 — 기존 계약 안의 추가다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 한 줄. 진단 이벤트의 칸이 하나 는다(추가만) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 손상 값 discard 이벤트에 `reason: "VALUE_REJECTED"`가, 크기 초과에 `"SIZE_LIMIT_EXCEEDED"`가 있다 | +| 검증 방법 | `storage-registry.test.ts`의 discard·oversize 테스트에 진단 기대값을 더한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 05-03 lifecycle 런타임의 "유일한 리스너 주인" 규칙이 이미 깨졌고, 검사도 직접 테스트도 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (주석 계약과 코드 불일치 + 테스트 공백) | +| 관련 관점 | 5, 21, 10, 23 | +| 근거 | ① `browser-lifecycle.ts:1-6`: "The single owner of window lifecycle listeners. No capability adds its own `visibilitychange`, `online`, `offline`, `focus`, `pagehide` or `pageshow` listener. They subscribe here instead, so the listener count stays constant and leak inspection (§23.14) is meaningful." `optional-runtime-host.ts:88-89`도 "The lifecycle observer is the single window listener owner"라고 적는다.
② 실제: telemetry 수집기가 `globalThis`에 자기 `pagehide` 리스너를 단다(`telemetry-collector.ts:108-113`, `:165-176`). 기본 구성에서 조립된다(`runtime-adapters.ts:327`). 반면 lifecycle 런타임은 기본 구성에서 만들어지지 않고(`optional-runtime-host.ts:90-92`), src 안에 구독자가 없다(`browserLifecycle()` 호출은 테스트의 `toBeNull()` 2건뿐).
③ 이 규칙을 보는 검사가 없다. `eslint.config.ts`·`scripts/`에 해당 이벤트 이름을 막는 규칙이 없다(`grep visibilitychange\|pagehide` 0건).
④ `createBrowserLifecycleRuntime`을 직접 부르는 테스트가 없다(`grep` 0건). bfcache 복원 때 generation 증가, dispose 때 리스너 해제, dirty source가 있을 때만 `beforeunload`를 다는 동작이 테스트 밖이다. 변이 K3(bfcache 복원 때 generation 증가를 지움)와 K4(dispose에서 `pagehide`·`pageshow` 해제를 지움)는 lifecycle을 만지는 유일한 테스트 파일 `tests/unit/optional-runtime-host.test.ts`(6개)에서 살아남았다. 2차 전체 실행(2,734개)에서도 살아남았다 | +| 발생 조건 | 다운스트림이 SW나 realtime을 켜서 lifecycle 런타임이 만들어질 때. 그때 이 파일의 주석을 믿고 "창 리스너는 여기 하나"라고 판단하면 telemetry 리스너를 놓친다. 또는 lifecycle 런타임을 고칠 때 회귀를 잡을 테스트가 없다 | +| 영향 | 지금 사용자 피해는 없다. `pagehide` 리스너 하나가 더 있을 뿐이다. 영향은 두 가지다. ① 주석이 약속한 "리스너 수가 일정해서 누수 검사가 의미 있다"가 사실이 아니다. ② 확장 지점(lifecycle 런타임)이 테스트 없이 남아 있어, 다운스트림이 켜는 순간 처음 실행된다 | +| 심각도·우선순위 | Low · P3. 기본 구성에서는 lifecycle 런타임이 없다. 피해가 생기려면 다운스트림 조합과 추가 판단 실수가 필요하다 | +| 통제·증거 | "창 lifecycle 리스너는 lifecycle 런타임만 단다" 규칙: M0 확인(주석만 있고 이미 어긋남, 검사 없음) · E1(grep), E2(변이 K3·K4 생존) | +| 확실성과 남은 가정 | telemetry 쪽 코드는 영역 03이다. telemetry가 lifecycle 런타임을 쓰지 않은 이유는 기록에서 찾지 못했다. 기본 구성에서 lifecycle 런타임이 없으니 telemetry가 직접 달 수밖에 없었다고 본다(추론) | +| 결정의 근거 | [기록] 단일 주인 규칙의 목적은 리스너 수를 일정하게 유지해 누수 검사를 가능하게 하는 것이다(`browser-lifecycle.ts:5-6`). [추론] 규칙이 "lifecycle 런타임이 있을 때"만 성립하는데, 기본 구성에서는 그것이 없다. 규칙의 적용 범위가 주석에 적혀 있지 않다 | +| 이해 비용 | 창 리스너를 추가하려는 사람은 이 주석을 보고 lifecycle 런타임을 찾아간다. 기본 구성에서 그것이 `null`이라는 것은 `optional-runtime-host.ts`를 읽어야 안다 | +| 최소 개선 방향 | 둘 중 하나를 고른다. (a) 규칙을 사실에 맞춘다: 주석을 "lifecycle 런타임이 만들어진 구성에서 capability는 여기에 구독한다. 기본 구성의 telemetry `pagehide`는 예외다"로 고친다. (b) 규칙을 지킨다: telemetry가 lifecycle 런타임을 받도록 하고, 기본 구성에서도 런타임을 만든다. 어느 쪽이든 `createBrowserLifecycleRuntime` 단위 테스트를 하나 둔다(generation, dispose, beforeunload) | +| 대안 비교 | (a) 주석 수정: 가장 싸다. 규칙은 약해지지만 사실과 맞는다. (b) telemetry를 lifecycle에 연결: 규칙을 지키지만 "기본 구성에서는 부작용 없는 생성" 원칙(`optional-runtime-host.ts:17-19`)과 충돌하지 않는지 따져야 하고, telemetry 조립 순서가 바뀐다. (c) lint 규칙으로 해당 이벤트 이름을 막고 예외 파일을 적는다: 규칙이 코드에 드러난다. 예외 파일 목록을 관리해야 한다. 템플릿의 현재 크기에서는 (a)+단위 테스트가 비용 대비 낫다. 다운스트림이 lifecycle 런타임을 실제로 켜면 (c)를 다시 본다 | +| 단순화의 보존 조건 | 적용 제외 — 제거 제안이 아니다. 다만 (b)를 고르면 telemetry의 page-exit flush가 지금처럼 `pagehide`에서 동기 실행되어야 한다 | +| 비용·부작용 | 주석 몇 줄과 테스트 파일 하나 | +| 재검토 조건 | SW 또는 realtime을 켜는 다운스트림이 생길 때. 창 리스너를 다는 어댑터가 하나 더 생길 때 | +| 완료 기준 | 주석의 규칙과 코드가 모순되지 않는다. lifecycle 런타임의 generation·dispose·beforeunload 동작을 깨는 변이를 테스트가 잡는다 | +| 검증 방법 | `tests/unit/browser-lifecycle.test.ts` 추가 후 K3·K4 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 05-04 kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 단위 예외를 받는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 (폴더 위치와 책임) | +| 관련 관점 | 22, 2, 9 | +| 근거 | ① kernel 예외는 `platform/` 폴더 전체다(`.dependency-cruiser.json:249`). 규칙 주석은 kernel을 "shared on purpose and any adapter may import it"이라고 적는다(`:242`).
② `platform/` 파일 10개의 adapter 소비자(`grep`): `abortable-operation` 7개 그룹, `indexeddb-connection`·`-transaction` 2개 그룹(storage, browser-transfer), `retry-after` 3개 그룹, `system-clock` 3개 그룹, `json-member-scanner` 2개 그룹, `bounded-capacity` 2개 그룹. 반면 **`browser-lifecycle.ts`와 `browser-mutation-intent-factory.ts`는 adapter 소비자가 0이다.** bootstrap만 배럴로 쓴다(`optional-runtime-host.ts:1-4`, `runtime-adapters.ts:32`).
③ 두 파일은 공유 메커니즘이 아니라 port 구현이다. `createBrowserMutationIntentFactory`는 `MutationIntentFactory` port를 구현한다(`browser-mutation-intent-factory.ts:1`, `:9-11`). lifecycle 런타임은 창 이벤트를 소유하는 런타임이다.
④ kernel 편입 기준은 `indexeddb-connection.ts:19-24`에만 있고([0929] 05-08), 지난 리뷰의 재검토 조건은 "한 그룹만 쓰는 코드가 kernel에 들어올 때"였다 | +| 발생 조건 | 어느 adapter가 composition을 거치지 않고 `platform/browser-mutation-intent-factory.ts`를 직접 import할 때. `adapters-do-not-know-other-concrete-adapters`가 막지 않는다 | +| 영향 | 지금 피해는 없다. 위험은 두 가지다. ① port 구현을 composition 없이 직접 끌어다 쓰는 길이 규칙에서 열려 있다. ② "kernel = 여러 그룹이 공유하는 메커니즘"이라는 설명과 폴더 내용이 다르다. 다음 사람이 "port 구현도 platform에 둬도 된다"고 읽을 수 있다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | "kernel에는 여러 그룹이 쓰는 메커니즘만 둔다" 규칙: M0 확인(기준이 규칙·문서에 없음, 두 파일이 기준 밖) · E1(grep 전수) | +| 확실성과 남은 가정 | 두 파일이 platform에 들어온 이유는 커밋 메시지(`6f6c48eb` "도메인이 100개 1000개씩 늘어나도…", `cbcc7b5e`)에서 찾지 못했다. "platform"이라는 이름이 "브라우저 플랫폼 서비스"로도 읽혀서 들어왔다고 본다(추론) | +| 결정의 근거 | 4.2절 | +| 이해 비용 | kernel이 무엇인지 알려면 파일 10개의 소비자를 직접 세어야 한다 | +| 최소 개선 방향 | (a) 문서로 구분: `platform/index.ts` 머리말과 `layers.md` kernel 절에 "공유 메커니즘"과 "bootstrap만 쓰는 브라우저 플랫폼 서비스" 두 종류가 있다고 적고, 후자를 다른 adapter가 import하지 않는다고 명시한다. (b) 폴더 이동: 두 파일을 `src/adapters/browser-lifecycle/`, `src/adapters/mutation-intent/` 같은 일반 adapter 그룹으로 옮긴다. 새 예외는 생기지 않고 예외 범위가 줄어든다 | +| 대안 비교 | 4.2절 (a)~(d) | +| 단순화의 보존 조건 | bootstrap의 공개 import 경로는 배럴을 거친다. `eslint.config.ts`의 lifecycle 파일 단위 browser-data 예외(`:544`, `:713`)는 새 경로로 옮긴다. `docs/reviews/adapters/INVENTORY.md`를 같은 커밋에서 고친다(`check:adapter-inventory`가 강제) | +| 비용·부작용 | (b)는 파일 이동 2개, 배럴 2개, eslint 경로 2곳, INVENTORY 2행. 다운스트림 동기화 때 경로 충돌이 생긴다(tech-log는 3-way 이식) | +| 재검토 조건 | 어느 adapter가 두 파일 중 하나를 실제로 필요로 하게 되면 kernel에 두는 것이 맞다 | +| 완료 기준 | kernel의 각 파일이 문서에 적힌 기준을 만족한다. 또는 기준 밖 파일이 문서에 따로 적혀 있다 | +| 검증 방법 | `check:architecture`, `check:adapter-inventory`, 소비자 `grep` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 05-05 kernel 주석의 `file:line` 참조가 다른 코드를 가리킨다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (문서 불일치) | +| 관련 관점 | 9, 4, 24 | +| 근거 | kernel·`browser-file-storage` 주석에 `file:line` 참조가 20개 있다(`grep -oE '\.(ts|json|md):[0-9]+'`). 표본 8개를 열었다.
• `platform/index.ts:5` → `scripts/check-adapter-inventory.ts:63-83`: 실제 abort primitive 검사는 `:147-173`이다. 63-83은 INVENTORY 합계 검사다.
• `indexeddb-connection.ts:13-14` → `eslint.config.ts:40-63`, `:519-530`: 실제는 `:58-70`, `:535-546`·`:705-716`이다.
• `indexeddb-connection.ts:119` → `indexeddb-maintenance.ts:477-484`: 지금 그 줄은 durability 설정이다.
• `indexeddb-connection.ts:190` → `indexeddb-checkpoint-store.ts:449-462`: 몇 줄 밀려 있다(설명 주석은 `:458-460`).
• `indexeddb-transaction.ts:103-104` → `indexeddb-runtime.ts:2384`, `indexeddb-maintenance.ts:823`: 지금 그 줄은 각각 cursor 삭제 콜백, 동시 변경 카운트다.
• `indexeddb-transaction.ts:4-7` → `indexeddb-runtime.ts:976-1074` 외 3곳: kernel로 옮기기 전 코드를 가리킨다. 그 코드는 이미 없다.
표본 8개 중 7개는 다른 코드, 1개는 밀림이다 | +| 발생 조건 | 주석을 따라 근거를 확인하려 할 때 | +| 영향 | 주석이 "왜"를 설명하면서 근거를 줄 번호로만 준다. 줄 번호가 밀리면 근거를 찾을 수 없다. kernel은 여러 그룹이 의존하는 곳이라 설명의 정확도가 더 중요하다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1(주석) · E1(표본 대조) | +| 확실성과 남은 가정 | 20개 중 8개만 열었다. 나머지 12개도 같은 성격(다른 파일의 줄 번호)이다 | +| 결정의 근거 | 적용 제외 — 주석을 사실에 맞추는 단순 수정이다 | +| 이해 비용 | 독자가 근거를 따라가다 엉뚱한 코드를 읽는다 | +| 최소 개선 방향 | 줄 번호 대신 심볼 이름(`deleteUnadmittedDataset`, 규칙 id `browser-data-boundary` 등)을 쓴다. 이미 없어진 코드를 가리키는 역사 설명(`indexeddb-transaction.ts:4-7`)은 "kernel 이전에는 네 벌이 서로 달랐다(IDB-X-02)"처럼 ID로 줄인다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 주석 수정만 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | kernel 주석에 다른 파일의 줄 번호 참조가 없거나, 남은 참조가 모두 맞다 | +| 검증 방법 | 위 `grep`으로 남은 참조를 세고 수동 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 05-06 Web Storage 어댑터·codec의 분기 5개를 테스트가 잡지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (변이로 확인한 테스트 공백) | +| 관련 관점 | 10, 15, 11 | +| 근거 | ① Web Storage 어댑터를 직접 부르는 테스트는 `tests/unit/storage-registry.test.ts` 하나다(21개, `grep createBrowserStorageAdapter`).
② 변이 8개 중 6개가 그 파일에서 살아남았다. 전체 2,734개 테스트로 다시 돌려도 동작을 보는 테스트는 하나도 실패하지 않았다(1절 변이 행).
• W2: 읽기에서 "TTL 키인데 만료 시각이 없다 / TTL 키가 아닌데 만료 시각이 있다" 검사를 지움(`browser-storage-adapter.ts:123`).
• W4: Firefox 옛 quota 이름 `NS_ERROR_DOM_QUOTA_REACHED`를 quota로 보지 않게 함(`:324`).
• W5: codec의 `__proto__`·`constructor`·`prototype` 키 거절을 지움(`browser-storage-codec.ts:204`).
• W6: codec의 accessor(getter) 거절을 지움(`:205-206`).
• W7: 읽기 decode에서 값 검증을 건너뜀(`:69-81`).
• W8: 만료 비교 `<=`를 `<`로 바꿈(`browser-storage-adapter.ts:138`).
③ 잡힌 변이는 둘이다. W1(지우기 실패 뒤 tombstone)과 W3(쓰기 성공 뒤 overlay 정리)는 각각 3개, 1개 테스트가 실패했다.
④ 왜 비는가: 현재 registry의 codec 셋은 문자열만 허용하고(`storage-keys.ts:185-201`), 숫자 TTL 키가 없다(`:37-126`의 `ttl`은 모두 `null`이나 `"session"`). 그래서 객체 검증 경로(W5·W6·W7)와 TTL 모양 검사(W2)는 기본 구성에서 도달하지 않는다. W7은 지금 registry에서는 결과가 같은 변이다(문자열 아닌 값은 뒤에서 `isStorageValueAllowed`가 거절한다). 다운스트림이 객체 codec이나 숫자 TTL 키를 추가하는 순간 이 경로들이 살아난다(템플릿의 확장 지점). W4는 지금도 도달한다(Firefox quota 초과) | +| 발생 조건 | 누군가 어댑터나 codec을 고칠 때. 다운스트림이 객체 값이나 숫자 TTL 키를 추가한 뒤 특히 그렇다 | +| 영향 | W4가 깨지면 Firefox에서 quota 초과가 `STORAGE_UNAVAILABLE`로 보고되고 `quotaFallback` 판단이 달라진다. W5·W6이 깨지면 프로토타입 오염 키나 getter를 거르는 방어가 사라진다. 어느 쪽도 테스트가 알려 주지 않는다 | +| 심각도·우선순위 | Low · P3. 지금 사용자 피해는 없다. W4 하나만 현재 도달한다 | +| 통제·증거 | "Web Storage 경계가 위험한 값과 엔진별 quota를 처리한다" 규칙: 구현 M2 / 검출은 6개 분기에서 M0 확인 · E2(변이) | +| 확실성과 남은 가정 | 2차 실행은 `tests/unit`·`component`·`integration`·`contract`다. 브라우저 계층(Playwright)은 돌리지 않았다. W2·W5는 타입 검사 테스트에 걸리지 않게 다시 써서 확인했다. W7은 지금 registry에서 동작이 같은 변이라 테스트 공백으로 세지 않는다. 그래서 실제 공백은 5개 분기다(W2·W4·W5·W6·W8) | +| 결정의 근거 | [사실] 객체 경로와 TTL 모양 검사는 지금 확장 지점이다. CLAUDE.md 전제상 죽은 코드로 보지 않는다. [추론] 확장 지점이면 다운스트림이 켤 때 함께 따라갈 테스트가 있어야 한다. 주석이 이 경로를 "persistence boundary"의 방어라고 부르므로(`browser-storage-codec.ts:26-30`) 더 그렇다 | +| 이해 비용 | codec을 고치는 사람은 어떤 입력을 막아야 하는지 테스트에서 찾을 수 없다 | +| 최소 개선 방향 | `browser-storage-codec.ts`를 직접 부르는 작은 테스트 하나(`__proto__` 키, getter, symbol 키, 순환, 깊이 33)와 `storage-registry.test.ts`에 세 줄(Firefox quota 이름, TTL 모양 불일치, 만료 시각 = 현재 시각) | +| 대안 비교 | (a) 현상 유지: 도달할 때까지 위험 없음. W4는 지금도 빈다. (b) 객체 경로를 지우고 문자열만 허용: 코드는 줄지만 다운스트림이 다시 써야 하고, 템플릿 방침(확장 지점 유지)과 어긋난다. (c) 테스트 추가: 비용이 가장 작다. (c)를 권한다 | +| 단순화의 보존 조건 | 적용 제외 — 테스트 추가다 | +| 비용·부작용 | 테스트 파일 하나와 테스트 세 개 | +| 재검토 조건 | registry에 객체 codec이나 숫자 TTL 키가 생기면 우선순위를 올린다 | +| 완료 기준 | W2·W4·W5·W6·W8 변이를 테스트가 잡는다. W7은 객체 codec이 생길 때 같은 기준을 적용한다 | +| 검증 방법 | `scratchpad/05-mutate.mjs W2-expiry-shape,W4-firefox-quota,W5-proto-key,W6-accessor,W8-expiry-boundary` 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 설계 선택 검토 (41) + +**[사실]**은 현재 코드·실행 결과, **[기록]**은 주석·문서에 적힌 의도, **[추론]**은 리뷰어의 해석이다. + +### 4.1 Web Storage 어댑터: 인스턴스별 메모리 overlay와 tombstone + +1. **필요:** 기본 구성의 유일한 저장소 어댑터다. 테마·언어(localStorage)와 릴리스 복구 표시(sessionStorage)를 저장한다. Safari private 모드처럼 저장소가 없거나, quota가 찼거나, 지우기가 실패해도 앱이 돌아야 한다. +2. **지킬 성질:** 쓰기 실패 뒤에도 같은 탭 안에서는 방금 쓴 값이 읽혀야 한다(`quotaFallback: "memory"`). 손상되어 버린 값은 다시 읽혀 파싱되면 안 된다. 민감 키는 어떤 경로로도 저장되지 않는다. +3. **현재 보장:** [사실] quota 실패면 `memoryOverlay`에 envelope을 두고 읽기에서 먼저 본다(`browser-storage-adapter.ts:152-160`, `:253-266`). 나중에 쓰기가 성공하면 overlay를 지운다(`:245-247`). 손상 값을 지우다 실패하면 `suppressedPersistentValues`에 tombstone을 남겨 다시 파싱하지 않는다(`:84-100`, `:161-163`). 민감 키는 `getStorageDefinition`이 던지고, 어댑터는 그것을 `UNAVAILABLE`로 바꾼다(`:54-65`). 테스트: 우선순위·만료·overlay 정리·remove 실패(`storage-registry.test.ts:338-430`). 변이 W1(지우기 실패 뒤 tombstone을 남기지 않음)과 W3(쓰기 성공 뒤 overlay를 지우지 않음)는 테스트가 잡았다. **보장하지 않는 것:** overlay와 tombstone은 인스턴스마다 따로다. 기본 구성은 인스턴스 둘을 만든다(`runtime-adapters.ts:420`, `boot-release-recovery.ts:57`). 다른 탭이 나중에 쓴 값도 overlay가 있는 탭에서는 보이지 않는다. +4. **대안:** (a) 현상 유지. (b) 앱 전체에 인스턴스 하나만 두고 공유한다. (c) overlay를 버리고 실패를 그대로 돌려준다. (d) overlay를 다른 탭과 storage 이벤트로 맞춘다. +5. **비교:** (b)는 boot 단계(앱 조립 전)에 쓰는 복구 표시 때문에 조립 순서가 얽힌다. 두 인스턴스가 다루는 키가 겹치지 않으므로(`RELEASE_MISMATCH_RECOVERY`는 `no-persist`라 overlay를 쓰지 않는다) 얻는 것이 작다. (c)는 quota가 찬 기기에서 테마를 바꿔도 반영되지 않는다. (d)는 선호값 몇 개에 비해 복잡하다. +6. **선택 이유:** [추론] 저장 대상이 작은 선호값과 탭 한정 표시뿐이라, 탭 안에서만 일관되면 충분하다. 인스턴스 둘이 같은 키를 쓰지 않으므로 상태가 갈라지지 않는다. [기록] "Keep the in-memory tombstone so the rejected value is not parsed again"(`:98`). +7. **재검토 조건:** 두 인스턴스가 같은 `memory` fallback 키를 쓰게 될 때. 탭 사이에 일관되어야 하는 값(예: 로그인 상태 힌트)을 이 어댑터에 넣을 때. + +**판단:** 유지. 다만 "overlay는 인스턴스·탭 한정"을 `createBrowserStorageAdapter` 머리말에 한 줄 적으면 위 7번 조건을 다음 사람이 알 수 있다(작은 보강, 발견으로 세지 않음). + +### 4.2 kernel = `platform/` 폴더 전체 예외 (05-04, [0929] 05-08) + +1. **필요:** 여러 adapter 그룹이 같은 메커니즘(abort 경쟁, IndexedDB 연결·트랜잭션, Retry-After 파싱, JSON 중복 키 검사)을 써야 한다. adapter끼리는 서로 import할 수 없다. +2. **지킬 성질:** kernel은 정책(이름·스키마·실패 코드·관측 형태)을 갖지 않는다. kernel 밖 adapter끼리는 import하지 않는다. 새 파일 단위 예외를 늘리지 않는다. +3. **현재 보장:** [사실] 규칙은 `platform/` 폴더를 통째로 허용한다(`.dependency-cruiser.json:249`). 8개 파일은 2~7개 그룹이 쓴다. 2개 파일(lifecycle, mutation intent)은 adapter 소비자가 0이다(05-04 근거). [사실] `check:architecture` rc=0. **보장하지 않는 것:** 폴더에 무엇을 넣을지는 규칙이 보지 않는다. 기준은 한 파일 머리말에만 있다. +4. **대안:** (a) 현상 유지. (b) 기준을 문서에 적고, 기준 밖 파일은 "platform 서비스"로 따로 표시한다. (c) 기준 밖 파일을 일반 adapter 그룹으로 옮긴다. (d) kernel을 `platform/kernel/`과 `platform/services/`로 나누고 예외를 `kernel/`로 좁힌다. +5. **비교:** (b)는 문서 두 곳만 고친다. 직접 import를 막지는 못한다. (c)는 예외 범위가 줄고 규칙만으로 강제된다. 대신 파일 이동·INVENTORY·eslint 경로·다운스트림 동기화 비용이 있다. (d)는 (c)와 비슷한 비용에 kernel 경로가 모두 바뀌어 22개 소비자의 import가 바뀐다. 이득에 비해 비싸다. +6. **선택 이유:** [기록] 폴더 단위 예외는 "kernel에 파일을 추가할 때 규칙 변경이 필요 없게" 하려는 결정이다(리팩토링 방향 결정, 2026-09-16). [추론] 그 결정은 맞다. 문제는 예외의 범위가 아니라 폴더에 들어갈 기준이 없는 것이다. 템플릿의 현재 크기에서는 (b)로 기준을 드러내는 것이 가장 싸고, (c)는 다운스트림 동기화와 묶어서 할 때 비용이 낮다. +7. **재검토 조건:** 어느 adapter가 lifecycle이나 mutation intent를 직접 import하려 할 때(그때는 (c)가 필요하다). kernel 파일이 한 그룹만 쓰는 코드로 늘어날 때. + +**판단:** (b)를 먼저 한다. (c)는 다음 다운스트림 동기화 기준점을 잡을 때 같이 한다. + +### 4.3 폴더 구조: browser-file-storage 번들이 여섯 폴더에 흩어져 있다 + +1. **필요:** IndexedDB·OPFS·StorageManager·파일·전송·Cache Storage 런타임은 함께 조합되고 함께 제거되는 번들이다(`scripts/test-browser-file-storage-runtime-removal.ts`의 `runtimePaths`). Web Storage 어댑터는 번들을 지운 뒤에도 남아야 한다. +2. **지킬 성질:** 번들을 지워도 기본 앱이 빌드된다. 번들 안의 공유 헬퍼(`result.ts`)는 번들 그룹들이 함께 쓴다. 사람이 port에서 구현을 찾아갈 수 있다. +3. **현재 보장:** [사실] port는 번들 단위 폴더 하나(`src/application/ports/browser-file-storage/`)에 있다. 구현은 기술 단위로 흩어져 있다: `adapters/storage/indexeddb`, `adapters/storage/opfs`, `adapters/browser-file-storage`(StorageManager와 `result.ts`), `browser-files`, `browser-transfer`, `cache-storage`. [사실] `storage/index.ts:1-10`이 "indexeddb·opfs를 재수출하지 말라, 드릴이 번들 전체를 지운다"를 적는다. `.dependency-cruiser.json:254`가 두 sub-barrel만 공개 경계로 허용하는 이유를 적는다. [사실] `result.ts`의 소비자는 모두 번들 안이다(5개 그룹 30개 파일). 그런데도 번들이 여러 adapter 그룹에 걸쳐 있어서 kernel 파일 단위 예외가 필요하다. **보장하지 않는 것:** `adapters/browser-file-storage/` 폴더 이름은 "번들 전체"로 읽히지만 실제로는 StorageManager 어댑터와 `result.ts`만 있다. `IndexedDbRepositoryPort`의 구현을 찾는 사람은 이 폴더를 먼저 열고 빈손으로 나온다. 이 폴더의 `index.ts`에는 안내 주석이 없다. +4. **대안:** (a) 현상 유지. (b) `adapters/browser-file-storage/index.ts` 머리말에 "이 번들의 런타임은 `storage/indexeddb`, `storage/opfs`, …에 있다"를 적는다. (c) `storage/indexeddb`·`storage/opfs`를 `browser-file-storage/` 아래로 옮긴다. (d) 번들 전체를 한 상위 폴더로 모은다. +5. **비교:** (b)는 주석 몇 줄이다. (c)는 두 런타임이 같은 그룹이 되는 점은 지금(`storage` 그룹)과 같다. 대신 제거 드릴 경로, recipe `sourceRoots`, INVENTORY, eslint 경로, 두 제품 repo의 동기화가 모두 바뀐다. 얻는 것은 탐색 한 단계다. (d)는 규칙의 그룹 단위(`$1`)가 바뀌어 번들 안 그룹끼리 import가 자유로워진다. 지금 adapter 경계 규칙이 막는 것을 잃는다. 기각. +6. **선택 이유:** [추론] 번들을 지우는 단위는 드릴이 이미 강제하고, Web Storage를 남기는 이유는 코드 옆에 적혀 있다. 폴더 이동의 이득(탐색 한 단계)은 비용(드릴·recipe·INVENTORY·제품 동기화)보다 작다. +7. **재검토 조건:** IndexedDB만 따로 제거해야 하는 요구가 생길 때([0929] 리뷰 7절 미검증 항목). 번들에 런타임이 하나 더 들어올 때. + +**판단:** 유지. (b) 안내 주석만 권한다(발견으로 세지 않음. 리팩토링 후보 R6에 둔다). + +## 5. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존해야 할 동작·타입·실패 계약 | +|---|---|---|---| +| R1 | canonical JSON 3벌을 `platform/`의 한 함수로 ([0929] 05-07) | 비유한 수 처리가 이미 다르다. 한 곳만 고치면 fingerprint와 manifest 비교가 갈라진다 | realtime 이벤트 fingerprint 문자열이 바이트 단위로 같아야 한다(키 정렬·구분자). OPFS는 `NaN`·`undefined`에서 계속 throw. cache codec 결과도 같아야 한다. 폴더 단위 kernel이라 새 예외는 생기지 않는다 | +| R2 | OPFS 폴더의 `sameScope` 2벌을 한 파일로 | 내용이 같은 복사본이다 | 네 토큰과 namespace를 모두 비교한다. journal과 worker가 같은 함수를 쓴다 | +| R3 | `indexeddb-runtime.ts`(2,641줄)의 lifecycle 부분(`:1978-2612`, 약 635줄)을 `indexeddb-lifecycle.ts`로 | 한 파일에 읽기·쿼리·CAS·삭제·lifecycle purge·전체 삭제가 모두 있다. 계정 삭제 경로만 보려 해도 2,600줄 closure를 읽어야 한다 | closure가 쥔 상태(`connection`, `disposed`, `factory`, `databaseName`, `observe`, `translateFor`)를 명시적 context로 넘긴다. `enforceLifecycleBatch`의 승인 → open → 전체 삭제/행 단위 순서와 실패 코드를 그대로 둔다. sub-barrel 공개 심볼은 바뀌지 않는다. 레시피 예산이 함께 움직인다([0929] 05-04) | +| R4 | Web Storage 어댑터의 "진단 기록 + 실패 반환" 5곳을 helper 하나로 | `recordStorageFailure(...)` 뒤에 `{ok:false, error: storageFailure(...)}`가 반복된다(`browser-storage-adapter.ts:181-194`, `:222-231`, `:256-266`, `:268-278`, `:295-304`). 05-02를 고칠 때 한 곳만 바꾸면 된다 | 실패 `code` 문자열 형식 `${NAME}_${PHASE}_${CAUSE}`. `fallback` 칸은 영구 저장소 쓰기 실패에만 붙는다. quota면 `STORAGE_QUOTA_EXCEEDED`, 아니면 `STORAGE_UNAVAILABLE` | +| R5 | IDB·OPFS 승인 계약 하나로 ([0929] 05-06) | 정규식 둘, 콜백 모양 둘, 타입 위치 둘 | 삭제마다 승인. proof는 로그·관측에 나가지 않는다. 승인 실패는 삭제 0건 | +| R6 | `adapters/browser-file-storage/index.ts`에 번들 지도 주석 (4.3) | port에서 구현을 찾아가는 길이 폴더 이름과 다르다 | 코드 변경 없음 | + +## 6. 성능·테스트·폴더 렌즈 요약 + +- **번들(14):** 기본 구성에 들어가는 이 영역 코드는 Web Storage 어댑터·codec(min 6,036 B)과 kernel 일부다. Web Storage 배럴 전체가 gzip 4,029 B이고 그중 절반 넘게(min 기준 약 6.7 KB)는 앱이 어차피 싣는 `contracts`다. 선택형 런타임은 IndexedDB gzip 15,376 B, OPFS gzip 22,780 B다(esbuild 단독 측정, Vite 실제 청크와 다를 수 있다). 레시피 예산 측정은 offline-indexeddb 36,891/36,900, file-transfer 55,623/55,700, realtime 40,886/40,900 gzip B다. 예산이 측정값 바로 위에 붙어 있어 성능 신호보다 수정 마찰로 작동한다([0929] 05-04). +- **테스트 실행 시간(10, 14):** 영역 테스트 13개 파일 290개가 1.69초다. 과하지 않다. +- **테스트가 위험을 잡는가(10):** 변이 14개 중 동작이 같은 변이 1개(W7)를 빼면 13개다. 그중 4개 검출, 9개 생존. 검출: Web Storage tombstone·overlay 정리, JSON 중복 키 escape, Retry-After 날짜 형식. 생존: Web Storage 분기 5개(05-06), lifecycle 2개(05-03), StorageManager 압력 경계 `>=`(K5), OPFS 정책의 `maxObjectBytes ≤ chunkSizeBytes × maxChunkCount` 검사(O1). K5·O1은 경계값 하나와 정책 검사 하나라 따로 세지 않았다. 지난 라운드에 검출된 OPFS·IDB 핵심 변이 7개는 코드가 같아 이번에 반복하지 않았다. +- **폴더(9, 22):** `storage/`는 기본 구성 어댑터(Web Storage)와 다른 번들의 런타임 두 개를 함께 담는다. 그 이유가 코드 옆에 있어 찾을 수 있다(4.3). kernel 폴더는 기준 밖 파일 2개가 섞여 있다(05-04). 큰 파일 4개(1,288~2,641줄)는 그대로다(R3). + +## 7. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 판정 | 통제(목표/확인) | 증거 | 이유·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | O | M2 / M2 | E2(290/290) | CAS·revision·generation·fencing 규칙이 put·remove·CAS·reconcile 경로에 있다(코드 불변). Web Storage 어댑터는 시계·quota·remove 실패를 모두 결과로 바꾼다. 보고값 정확성 문제는 11·24에서 센다 | +| 2 | 구조적 성숙도 | O | M3 / M3 | E2(`check:architecture` rc=0) | kernel 예외 밖 adapter 간 import 0건. 이번에는 위반 주입을 하지 않았다. 폴더 단위 예외가 port 구현 2개에도 열려 있다(05-04) | +| 3 | 변경 용이성 | P | M3 / M3 | E2(레시피 측정) | 레시피 예산 여유가 작아 이 영역의 다음 수정이 예산 인상을 함께 요구한다([0929] 05-04). 제품이 OPFS 이름을 소스에서 고친다([0929] 05-10) | +| 4 | 인지 부하 | P | — | E1 | 큰 파일 4개(최대 2,641줄)는 그대로다(R3). kernel 주석의 근거 줄 번호가 어긋나 근거를 따라갈 수 없다(05-05) | +| 5 | 위험 가시성 | P | M1 / M1 | E1, E2(X1) | port 주석이 실제 동작과 다른 곳 둘([0929] 05-02·05-05). lifecycle 단일 주인 주석이 사실과 다르다(05-03). registry pulse 행이 사실과 다르다(05-01) | +| 6 | 실패 성숙도 | P | M2 / M2 | E2(journal 테스트) | journal 목록이 손상 행 하나에 전체 실패하고, 테스트가 그것을 고정한다([0929] 05-01). Web Storage는 실패를 모두 결과로 돌린다 | +| 7 | 운영 성숙도 | P | M1 / M1 | E2(X1) | 진단 이벤트는 있으나 원인을 버린다(05-02). 선택형 런타임은 조합이 없어 알림 경로가 없다(0.1 전제상 비대상) | +| 8 | 디버깅 가능성 | P | M2 / M1 | E2(X1) | 값 손상과 저장소 불가가 같은 진단으로 남는다(05-02). purge 보고에 건너뛴 객체 수가 없다([0929] 05-02) | +| 9 | 유지보수 성숙도 | P | M2 / M1 | E1 | canonical JSON 3벌·`sameScope` 2벌([0929] 05-07), kernel 문서가 좁다([0929] 05-08), 주석 줄 번호가 낡았다(05-05) | +| 10 | 테스트 성숙도 | P | M3 / M2 | E2(290/290, 변이 4/13 검출) | 영역 테스트는 빠르고 OPFS·IDB 핵심 경로를 잡는다. lifecycle 런타임은 직접 테스트가 없다(05-03). Web Storage 분기 5개가 변이에 걸리지 않는다(05-06). recipe fake가 다른 계약이다([0929] 05-03) | +| **11** | 데이터 성숙도 | P | M3 / M2 | E2(journal 테스트), E1 | OPFS purge가 손상 행에 막히고([0929] 05-01) 동시 덮어쓰기에서 완료로 보고한다([0929] 05-02). 롤백 중 계정 삭제가 데이터를 남긴다([0929] 05-05). pulse 키를 StoragePort로 읽으면 다른 어댑터 값을 지운다(05-01) | +| **12** | 동시성 성숙도 | P | M3 / M2 | E1(코드 불변), Playwright 미실행 | OPFS 동시성 설계는 코드가 같다. 이번 라운드에 2탭 실행 증거는 없다. Web Storage overlay는 탭·인스턴스 한정이고 그것으로 충분하다(4.1) | +| 13 | 확장성 | ? | — | E1 | 규모 목표가 없다. 배치 상한(500행/30초, 스캔 5,000행, reconcile 100행/5초)만 있다 | +| 14 | 성능 성숙도 | ? | — | E3(측정) | 목표가 없어 판정하지 않는다. 측정값: Web Storage 배럴 gzip 4,029 B, IDB 15,376 B, OPFS 22,780 B, 영역 테스트 1.69초. 2 GiB 객체 검증 시간은 미측정 | +| 15 | 보안 성숙도 | P | M2 / M2 | E1 | 민감 키는 registry가 막는다. opaque 이름, 관측에서 key·값 제외, 삭제마다 승인은 그대로다. 계정 삭제 뒤 잔존 경로 셋([0929] 05-01·02·05)과 승인 계약 둘([0929] 05-06)이 남았다. codec 방어가 테스트 밖이다(05-06) | +| 16 | 의존성 성숙도 | - | — | — | 외부 패키지 없이 브라우저 API만 쓴다 | +| 17 | API / Contract | P | M2 / M1 | E1, E2(X1) | 같은 이름 recipe port([0929] 05-03), 주석과 코드가 다른 port 둘([0929] 05-02·05-05), 사실과 다른 registry 행(05-01) | +| 18 | 배포 성숙도 | P | M2 / M2 | E1 | N-1 탭이 `INCOMPATIBLE`/`ONLINE_ONLY`로 닫히는 코드는 그대로다. 이번에 브라우저로 확인하지 않았다. 정책 값을 바꾸는 release가 OPFS purge를 막을 수 있다(2절 [0929] 05-05 덧붙임) | +| 19 | 설정 성숙도 | P | M3 / M2 | E2(X2) | 두 timeout의 관계를 검사하지 않는다([0929] 05-09). journal 접두사를 바꿀 수 없다([0929] 05-10) | +| 20 | 개발자 경험 | > | — | — | 영역 14 | +| 21 | Guardrail 성숙도 | P | M3 / M2 | E2(게이트 로그, 레시피 PASS) | 아키텍처·inventory·레시피 예산 게이트는 동작한다. lifecycle 단일 주인 규칙은 검사가 없다(05-03). 제거 드릴은 이번에 돌리지 않았다 | +| **22** | 추상화 성숙도 | P | M2 / M2 | E1 | kernel은 메커니즘만 갖고 실패 코드는 호출자 `translate`에 둔다(유지). 기준 밖 파일 2개(05-04), 갈라진 중복([0929] 05-07), 같은 이름 recipe port([0929] 05-03), 승인 계약 둘([0929] 05-06) | +| 23 | 일관성 | P | M1 / M1 | E1 | proof 정규식 둘([0929] 05-06), 비유한 수 처리 셋([0929] 05-07), pulse 키를 두 어댑터가 다른 형식으로 다룬다(05-01), 리스너 소유 규칙과 실제가 다르다(05-03) | +| 24 | 네이밍 / 의미 | P | M1 / M1 | E2(X1) | `chunkSweep: "COMPLETED"`의 의미([0929] 05-02), `STORAGE_UNAVAILABLE`이 원인 셋을 뜻한다(05-02) | +| 25 | 조직 확장성 | ? | — | E0 | 팀이 하나다 | +| 26 | Ownership | ? | — | E0 | 조합이 없어 runbook owner를 확인할 대상이 없다 | +| **27** | 삭제 가능성 | P | M3 / M1 | E1 | 번들 제거 단위와 Web Storage 잔존 이유가 코드 옆에 있다(`storage/index.ts:1-10`, `.dependency-cruiser.json:254`). 제거 드릴은 이번 라운드에 실행하지 않아 확인 통제를 M1로 둔다. 기기 데이터 삭제는 OPFS 쪽 빈틈이 남았다([0929] 05-01·05-02) | +| **28** | 회복 가능성 | P | M2 / M2 | E2(journal 테스트) | 손상 journal 행은 authority 전체 reconcile·GC를 멈추고, runbook이 수동 삭제를 금지해 승인된 탈출 경로가 없다([0929] 05-01). Web Storage는 손상 값을 버리고 tombstone으로 재파싱을 막아 스스로 회복한다(`browser-storage-adapter.ts:84-100`) | + +적용 항목 26개(16 제외, 20은 영역 14): 충족 2(1, 2), 부분 충족 20, 미충족 0, 미검증 4(13, 14, 25, 26). + +## 8. 미검증 목록 + +| 항목 | 이유 | 확인에 필요한 것 | +|---|---|---| +| OPFS·IndexedDB Playwright spec(2탭 동시성, 손상 governance, 미래 스키마) | 이번 라운드에 돌리지 않았다. 지난 라운드 결과는 증거로 쓰지 않는다 | `playwright.capabilities.config.ts`로 `indexeddb-runtime.spec.ts`, `opfs-runtime.spec.ts` 실행 | +| 제거 드릴 | fixture 안에서 pnpm을 불러 worktree 지침과 충돌한다 | 메인 repo에서 오케스트레이터가 `test:browser-file-storage-removal` 실행 | +| [0929] 05-02 동시 덮어쓰기, 05-05 롤백 중 계정 삭제의 재현 | 지난 실험 파일이 없다. 코드가 같아 정적 판단으로 남음 처리했다 | 05-02는 `opfs-worker-runtime.test.ts`에 두 탭 시나리오, 05-05는 `indexeddb-runtime.test.ts`에 migration 실패 시나리오 | +| OPFS 지원 판정이 정책 값에 묶여 purge가 막히는 경로 | 코드로만 판단했다 | `allowAsyncWritableChunkFallback`만 다른 두 런타임으로 같은 root를 여는 단위 테스트 | +| telemetry `pagehide`가 lifecycle 런타임과 공존할 때의 동작 | 기본 구성에서 lifecycle 런타임이 없다 | SW를 켠 구성에서 리스너 수 확인 | +| kernel 주석 `file:line` 참조 20개 중 12개 | 표본 8개만 대조했다 | 전수 대조 | +| 진단 수집기가 `reason` 칸을 실제로 내보내는지 | 영역 03 소관 | diagnostics 어댑터 테스트 | diff --git a/docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md b/docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md new file mode 100644 index 00000000..bf953d73 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md @@ -0,0 +1,377 @@ +# 06 Service Worker / Web Push 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 깊게 본 관점: 7, 12, 15, 18, 19, 28 + +ID 표기: 이번 라운드의 새 발견은 `06-01`부터 쓴다. 지난 라운드(2026-09-29)의 발견은 `0929/06-01`처럼 앞에 날짜를 붙인다. 그보다 앞선 라운드(2026-09-25)의 FOLLOW-UP 항목은 `0925/06-05`처럼 쓴다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +| --- | --- | +| 대상 | `src/adapters/service-worker/` 7파일 2,424줄, `src/adapters/web-push/` 12파일 3,811줄, `vite.service-worker.config.ts`, `tsconfig.service-worker.json`. 연결: `scripts/build-frontend.ts`, `scripts/generate-service-worker-assets.ts`, `scripts/lib/service-worker-build-input.ts`, `scripts/lib/self-unregistering-service-worker.ts`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts`, `config/hosting/cache-policy.json` | +| 커밋·작업 상태 | `d99301b`. `git log af3d8e6..d99301b`의 11커밋은 UI 감사·리뷰 문서다. 이 영역의 코드·빌드 설정·테스트·운영 문서는 지난 리뷰 기준 `af3d8e6` 뒤 한 줄도 바뀌지 않았다 | +| 전제 (0.1) | 템플릿. SW 선택 기본값은 `null`이다(`src/features/installed-runtime-capabilities.ts:39`). `ACTIVE`는 레시피가 안내하는 지원 옵션이다(`docs/architecture/optional-adapter-recipes.md:109-131`). Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH` handler를 거절한다(`scripts/lib/service-worker-build-input.ts:61-65`). 브라우저 SPA + 정적 호스팅 + SW. 여러 탭과 하위 경로 배포(`VITE_ROUTER_BASE_PATH`)는 지원 범위다 | +| 읽은 코드 | 범위 안 파일 전부. 연결 확인: `src/contracts/service-worker.ts`, `src/contracts/service-worker-static-manifest.ts`, `src/contracts/web-push.ts`, `src/application/ports/out/web-push-control.ts`, `src/bootstrap/{register-service-worker,optional-runtime-host,create-runtime-composition,runtime-application}.ts(x)`, `scripts/generate-runtime-config.ts`, `.dependency-cruiser.json:185-206` | +| 읽은 테스트 | `tests/unit/{service-worker-runtime,service-worker-web-push-remediation,service-worker-build-input,hosting-probe,sub-path-deployment,web-push-*}.test.ts`, `tests/e2e/service-worker-{update,recovery}.spec.ts`, `tests/e2e/support/service-worker-builds.ts` | +| 읽은 문서(주장) | `optional-adapter-recipes.md` 3절, `config/recipes/frontend-capability-recipes.json`(`service-worker-pwa`), `docs/operations/release-cache-rollback.md` SW 절, `docs/operations/browser-file-storage-recovery.md` 8절, `realtime-events-web-push-and-bounded-polling.md` 8.4·8.5절, 설계 `…closed-deep-design.md` 17.8~17.14절 | +| 게이트(오케스트레이터 실행) | `check:types` rc=0(`tsc --project tsconfig.service-worker.json` 포함), `check:architecture` rc=0, `test:unit` rc=0(이 영역 11파일 167건 통과), `test:component` rc=0(`runtime-composition-service-worker-telemetry.test.ts` 1건 통과). `test:system` rc=1은 `ci-artifact-contract.test.ts`의 문구 비교 실패로 이 영역과 무관하다 | +| 직접 실행 | 분리 worktree 2개(`scratchpad/wt-06`: 빌드 실험, `scratchpad/wt-06m`: 테스트·변이·e2e)에서 했다. `node_modules`는 `linkFixtureNodeModules`로 연결했고 pnpm은 부르지 않았다. 빌드·브라우저 실행은 `flock scratchpad/heavy.lock`으로 감쌌다. ① 영역 단위 테스트 11파일 → **167건 통과, 6.9초**(직전 부하 9.0) ② 변이 14건(`scratchpad/mutate-06.mjs`) → 11건 검출, 3건 생존 ③ SW `ACTIVE` + `APP_PROFILE=production` 빌드 → exit 0, `dist/config.json`이 local 문서, release admission 거절 4건 ④ SW `ACTIVE` + `VITE_ROUTER_BASE_PATH=/app/` 빌드 → 사전 캐시 URL 28/28이 `/assets/…` ⑤ `publicDir: false` 한 줄 추가 뒤 ③+④ 조합 빌드 ⑥ e2e 도우미의 `replaceOnce`를 `ACTIVE` 트리에 실행 → throw ⑦ 하위 경로 클릭 실험(임시 vitest 파일) ⑧ waiting 워커 활성화 실험(Playwright, 최소 워커) ⑨ SW e2e 2 spec(chromium·webkit) ⑩ 페이지 번들 측정 | +| 확인 못 한 것 | `test:realtime-removal`(fixture 안에서 pnpm을 부른다. 지침상 실행하지 않았다), 실제 CDN의 `service-worker.js` 캐시, 실제 푸시 서비스·VAPID 흐름, 얼어 있는 탭의 Web Lock 보유, Playwright Firefox의 SW 제어(격리 표기 `expires=2027-03-31`). 10절에 정리했다 | +| 이전 리뷰와 비교 | 코드가 같으므로 지난 발견 6건과 FOLLOW-UP 4건의 상태를 이번 커밋의 코드와 새 실행으로 다시 확인했다. 지난 라운드의 실행 결과는 증거로 쓰지 않았다 | + +**영역 판정 (35.8)** + +- 기본 구성(SW `null`, Web Push 미선택): **지정 범위에서 사용 가능.** 이 영역의 결함이 나타나지 않는다. 페이지 번들에 page controller와 프로토콜 코드가 들어가지만 실행되지 않는다(8절). +- SW `ACTIVE`: **해당 용도의 사용 보류.** `0929/06-01`이 그대로다. SW를 켜면 local이 아닌 모든 빌드가 local 런타임 설정을 싣는다(이번에 다시 재현). 한 줄 수정이다. 하위 경로에서는 워커가 설치되지 않는다(`0929/06-02`). +- Web Push: **조건부 사용 가능.** 탭 경합 방어와 두 번 읽는 fence 검사는 변이로 검출된다(M6·M7). 하위 경로 배포에서는 정상 클릭이 앱 밖 URL을 연다(06-01). 서버의 짧은 association TTL·send-time 인가와 `revokeForeign` 호출 규칙이 채택 조건이다. + +## 2. 지난 발견 재확인 + +### 2.1 2026-09-29 발견 + +| 지난 ID | 심각도 | 상태 | 근거 | +| --- | --- | --- | --- | +| 0929/06-01 SW `ACTIVE` 빌드가 `dist/config.json`을 `public/config.json`으로 덮어씀 | High · P1 | **남음** | `vite.service-worker.config.ts:69-82`에 여전히 `publicDir`·`build.copyPublicDir` 설정이 없다. 6단계 SW 빌드는 `:53-55`에서 프로필 문서를 읽은 뒤, Vite 출력 준비 단계에서 `public/`을 다시 복사한다. **재현**(wt-06, SW `ACTIVE`, `APP_PROFILE=production VITE_BUILD_ID=rev-prod-1106`): 빌드 exit 0. 4단계 로그는 `production profile written to dist/config.json (APP_ENV=production, AUTH_MODE=external)`이다. 빌드가 끝난 뒤 `dist/config.json`은 `APP_ENV: local`, `AUTH_MODE: demo`, `API_BASE_URL: http://localhost:8080/`, `TELEMETRY_ENABLED: false`이고 식별자만 `rev-prod-1106`이다. `RELEASE_TARGET=production node scripts/check-release-admission.ts` → exit 1, 거절 4건(APP_ENV, AUTH_MODE, API http, localhost). **하위 경로**(`/app/`, local): `generate-runtime-config.ts:59-67`이 만든 `/app/release-manifest.json`이 `/release-manifest.json`으로 되돌아간다. 워커는 덮어쓰기 전 값을 읽어 `/app/release-manifest.json`을 싣는다. 페이지와 워커가 서로 다른 manifest URL을 갖는다. **수정 확인**: `publicDir: false` 한 줄을 넣은 production + `/app/` 빌드 결과는 5.2절에 적었다 | +| 0929/06-02 SW 사전 캐시 목록이 router base path를 무시함 | Medium · P2 | **남음** | `scripts/generate-service-worker-assets.ts:66`이 URL을 `/${relative}`로 만든다. **빌드 산출물**(wt-06, `/app/`): `.generated/frontend-runtime/service-worker-assets.ts`의 URL 28개가 모두 `/assets/…`로 시작한다. 같은 빌드의 `dist/index.html`은 `/app/assets/index-BTTDjw29.js`를 부른다. 워커는 manifest URL을 scope 기준으로 풀지만 root-relative라 base가 사라진다(`service-worker-lifecycle.ts:67-88`). 이번에는 브라우저 설치 실패를 다시 돌리지 않았다(E1+빌드 산출물) | +| 0929/06-03 레시피는 오프라인 셸을 SW 설치 조건으로 적지만 SW 계약은 금지함 | Medium · P2 | **남음** | catalog `trigger`가 그대로다: `"Installability, a measured offline-shell requirement, …"`(`config/recipes/frontend-capability-recipes.json:140`), `failureKinds`에 `offline-fallback`(`:145`). 레시피 표도 그대로다: "install/offline shell"(`optional-adapter-recipes.md:94`). 코드는 navigation을 `NETWORK_ONLY`로 둔다(`service-worker-static-assets.ts:47`, 변이 M13이 검출) | +| 0929/06-04 SW e2e 도우미가 `null` 줄을 문자열로 바꿔 SW를 켠 트리에서 멈춤 | Medium · P2 | **남음** | `tests/e2e/support/service-worker-builds.ts:125-129`가 같은 문자열을 찾는다. **실행**: 선택을 `ACTIVE`로 바꾼 wt-06 파일에 도우미의 `replaceOnce`를 직접 불렀다 → `Expected exactly one "const SERVICE_WORKER: InstalledServiceWorkerSelection \| null = null;"` throw. recovery spec도 그 결과 문자열을 다시 찾는다(`service-worker-recovery.spec.ts:42-49`) | +| 0929/06-05 `service-worker.js`의 `no-cache`가 호스팅 정책·live probe에 없음 | Medium · P2 | **남음**(공백은 문서화됨) | `config/hosting/cache-policy.json`에는 index·config·release manifest·`/assets/*`만 있다. live probe도 이 넷만 요청한다(`scripts/verify-hosting-headers.ts:120-125`). 운영 문서는 이 공백을 직접 적는다: "`verify:hosting-headers`는 파일이 있는지만 보고 이 헤더는 보지 않는다"(`browser-file-storage-recovery.md:531-533`). 통제 수준은 M1 그대로다 | +| 0929/06-06 제거 2·3단계가 `service-worker.js`를 내보내지 않음 | Low · P3 | **남음** | 자기 해제 워커는 `REMOVE_REGISTRATION`에서만 쓴다(`scripts/build-frontend.ts:72-77`). hosting 검사는 `PURGE_OWNED_RESOURCES`에서 워커 파일을 거절한다(`scripts/lib/hosting-probe.ts:43-45`, 변이 M12가 검출). 운영 문서는 1단계 유지 기간을 적지 않는다(`release-cache-rollback.md:107-109`) | + +지난 README 개선 순서 1번은 "06-01은 수정이 작고 제품이 이미 막아 두었다"였다. 이 항목은 진행되지 않았다. + +### 2.2 2026-09-25 FOLLOW-UP + +| 항목 | 상태 | 현재 근거 | +| --- | --- | --- | +| 0925/06-05 (P2) 업데이트 설치 실패·`observe`·`health()` 미연결 | **남음**(문서화됨) | `watchForUpdates`는 `installed`만 알린다(`service-worker-page-controller.ts:328-349`). `create-runtime-composition.ts:50-62`는 `telemetry`만 넘긴다. 레시피 문서가 이 셋을 다운스트림 몫으로 적는다(`optional-adapter-recipes.md:114-124`) | +| 0925/06-08 (P2) 이전 빌드 fallback이 `assets/`를 하드코딩 | **남음** | `service-worker-static-assets.ts:66` `BUILD_ASSET_DIRECTORY = "assets/"` | +| 0925/06-10 (P3) SW Vite 설정의 `dist/config.json` 읽기 테스트 없음 | **남음** | 테스트는 `resolveServiceWorkerBuildInput`만 본다(`tests/unit/service-worker-build-input.test.ts`). 이 빈틈 때문에 0929/06-01이 게이트에 보이지 않는다 | +| 0925 P3 route chunk 변경용 export 덧붙이기를 도우미 옵션으로 | **남음** | `service-worker-update.spec.ts:38-57` 그대로 | + +## 3. 대표 흐름 (체크리스트 2절) + +### 3.1 정상 흐름 — 새 릴리스가 나온 뒤 워커가 바뀌는 경로 + +```text +릴리스 B 배포 (사용자는 A 워커의 제어를 받는 탭을 열어 둠) + → [정책] 6시간마다, 보이는 탭에서만 registration.update() + (service-worker-page-controller.ts:351-363) + → [외부 I/O] B 워커 install: 해시 자산 28개를 no-store·omit·redirect:error로 받음 + → 크기·타입·sha256 검증 → ca-static-v1-에 저장 + (service-worker-static-assets.ts:154-208, :269-349) + → [상태] B는 waiting. install에서 skipWaiting() 없음 (service-worker-entry.ts:82-85) + → [분기 1] 제품이 활성화 UI를 붙였다면: onUpdateWaiting → requestActivation() + → 범위 안 모든 창에 CLIENT_DRAIN_REQUEST → 30초 안에 모두 답하면 skipWaiting() + (service-worker-lifecycle.ts:325-374) + → [분기 2] 템플릿 기본: 활성화를 부르는 코드가 src에 없다 + → 범위 안 탭이 모두 닫히면 브라우저가 B를 활성화 (실험 ⑧) + → [결과] B activate: 현재 + 마커가 가장 높은 이전 캐시 1개만 남김 + (service-worker-lifecycle.ts:152-199) + 옛 탭의 A 청크 요청은 이전 릴리스 캐시에서 응답 (PREVIOUS_RELEASE_FALLBACK) +``` + +증거: e2e `announces update-waiting and reload-required …`, `serves A's removed chunk …`(결과 7절). 분기 2는 실험 ⑧과 저장소 자신의 테스트 주석(`service-worker-update.spec.ts:155-163`, "B skips `waiting` and activates by itself")이 근거다. + +### 3.2 피해가 큰 흐름 — SW를 켠 production 빌드 (0929/06-01, 이번에 다시 재현) + +```text +APP_PROFILE=production VITE_BUILD_ID=rev node scripts/build-frontend.ts + → [3] Vite 앱 빌드: public/ 복사 → dist/config.json = local 문서 + → [4] generate-runtime-config: dist/config.json = production 문서 (build-frontend.ts:65) + → [5] 자산 목록 생성 (config.json 제외) + → [6] SW Vite 빌드: dist/config.json(production)을 읽어 APP_ENV 검사 통과 + → 출력 준비 단계에서 public/ 재복사 → dist/config.json = local 문서 + (vite.service-worker.config.ts:53-55, :69-82) + → [7] generate-build-manifest: local 문서에 BUILD_ID·RELEASE_ID만 다시 찍음 + → [결과] 빌드 exit 0. APP_ENV local · AUTH_MODE demo · API http://localhost:8080/ + → [게이트] check:release-admission(production) → 거절 4건 +``` + +### 3.3 변경 흐름 — 하위 경로에 Web Push를 조립한 제품의 알림 클릭 (06-01) + +```text +제품: VITE_ROUTER_BASE_PATH=/app/, registry { routeIntent OPEN_INBOX, path "/inbox" } + → 워커 scope = https://host/app/ (service-worker-scope-host.ts:40) + → [거절된 클릭] 앱 루트 = scope → openWindow("https://host/app/") (0925/06-09 수정) + → [정상 클릭] target = new URL("/inbox", origin) → openWindow("https://host/inbox") + (notification-click-adapter.ts:190-193, :392-404) + → [결과] 정상 클릭만 앱 밖 URL을 연다. 열린 창이 있으면 handoff.path = "/inbox"를 보낸다 +``` + +## 4. 새 발견 (36.3) + +### 06-01 Web Push 정상 클릭의 대상 URL이 router base path를 무시해 하위 경로 배포에서 앱 밖을 엶 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 17, 1, 3 | +| 근거 | 정상 클릭은 registry 경로를 origin 기준으로 푼다: `safeTarget(origin, path)`(`src/adapters/web-push/inbound/notification-click-adapter.ts:190-193`), `new URL(path, origin)`(`:392-404`). 거절된 클릭만 `appRootUrl`(= `registration.scope`)을 쓴다(`:112-116`, `:264-282`). registry `path`는 `/`로 시작해야 한다는 검사만 있고 base를 포함하는지 정의가 없다(`notification-registry.ts:17-23`, `:106-122`). **실험 ⑦**(wt-06m 임시 vitest, 실제 `createWebPushServiceWorkerRuntime`, scope `https://app.example.test/app/`, registry `path: "/inbox"`): 정상 클릭 → `openWindow("https://app.example.test/inbox")`, 만료된 클릭 → `openWindow("https://app.example.test/app/")`. 기존 테스트는 base 없는 origin에서 정상 클릭만 본다(`tests/unit/web-push-worker-runtime.test.ts:501-526`) | +| 발생 조건 | 제품이 Web Push를 조립하고 `VITE_ROUTER_BASE_PATH`가 `/`가 아닌 곳에 배포한다 | +| 영향 | 열린 앱 창이 없을 때 정상 클릭이 앱 밖 페이지(404나 다른 앱)를 연다. registry에 base를 넣으면(`/app/inbox`) `openWindow`는 맞지만 같은 값이 handoff `path`로 페이지에 가서(`:215-223`) router basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수 없다 | +| 심각도·우선순위 | Low · P3. Web Push는 `NOT_SELECTED`이고 빌드가 `WEB_PUSH`를 거절한다. 조립 전에 고치면 된다. 같은 원인의 거절 경로(0925/06-09)는 이미 고쳐서 수정 방향이 정해져 있다 | +| 통제·증거 | M0(정상 클릭 경로에 base 처리 없음) · E2(실험 ⑦) | +| 확실성과 남은 가정 | 클릭 URL은 확인했다. 페이지가 handoff `path`를 basename 기준으로 쓸지는 제품 코드라 확인하지 않았다(템플릿에는 handoff 소비자가 없다) | +| 결정의 근거 | 적용 제외 — 하위 경로 일관성은 이미 정해진 계약이고(`vite.config.ts:26-34`), 거절 경로가 같은 계약을 따른다 | +| 이해 비용 | 제품 개발자는 registry `path`가 origin 기준인지 base 기준인지 코드에서 알 수 없다. 클릭 어댑터의 두 분기를 모두 읽어야 차이를 안다 | +| 최소 개선 방향 | 정상 클릭도 `appRootUrl` 기준으로 푼다(`new URL(path.slice(1), appRootUrl)`). registry `path`는 "앱 기준 경로"라고 타입 주석에 적는다 | +| 대안 비교 | 적용 제외 — 같은 원인의 다른 분기를 맞추는 수정이다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 수 줄. same-origin·hash 금지 검사는 그대로 둔다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | scope `/app/`, registry `/inbox`에서 정상 클릭이 `https://host/app/inbox`를 열고, handoff `path`는 `/inbox`다 | +| 검증 방법 | `web-push-worker-runtime.test.ts`의 base path 사례(`:450-482`)에 정상 클릭 사례 1개 | + +### 06-02 운영 문서는 새 워커가 `requestActivation()`으로만 활성화된다고 적지만, 브라우저는 탭이 모두 닫히면 waiting 워커를 활성화함 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 확인된 결함(운영 문서) | +| 관련 관점 | 28, 18, 26, 5 | +| 근거 | 문서: "새 워커는 install에서 `skipWaiting()`하지 않는다 … 활성화는 페이지의 `requestActivation()`으로만 일어나므로, 새 worker 활성화를 멈추려고 따로 할 일은 없다"(`docs/operations/browser-file-storage-recovery.md:534-536`). 코드: install은 `skipWaiting()`을 부르지 않는다(`service-worker-entry.ts:82-85`). 그러나 `requestActivation()`을 부르는 코드는 `src`에 없다(`grep` 결과 `tests/`에만 있음). e2e는 사본의 bootstrap을 고쳐서 부른다(`tests/e2e/support/service-worker-builds.ts:31-35`, `:61-81`). 저장소 자신의 테스트 주석도 "With no controlled client, B skips `waiting` and activates by itself"라고 적는다(`service-worker-update.spec.ts:155-163`). **실험 ⑧**(최소 워커: install·activate에서 아무것도 하지 않음, `updateViaCache: "none"`): chromium·webkit 모두 B가 `page.reload()` 뒤에도 waiting으로 남고, 탭을 모두 닫은 뒤 새 탭에서는 waiting이 사라지고 B가 활성화됐다(7.2절) | +| 발생 조건 | 결함 있는 새 워커가 배포돼 waiting에 있는 동안 운영자가 문서를 믿고 아무 조치를 하지 않는다. 사용자가 그 사이트의 탭을 모두 닫았다가 다시 연다 | +| 영향 | 운영자가 "아직 아무도 새 워커를 쓰지 않는다"고 판단하는 동안 탭을 닫았다 연 사용자부터 새 워커가 활성화된다. 대응(`REMOVE_REGISTRATION` 릴리스) 시작이 늦어진다. 저장하지 않은 편집 보호(blockers)는 handshake 경로에만 걸리지만, 기본 활성화는 열린 탭이 없을 때만 일어나므로 이 보호가 깨지지는 않는다 | +| 심각도·우선순위 | Low · P3. 문서 한 문장이다. 새 워커가 활성화돼도 해시 자산만 다루므로 피해는 그 워커의 결함 크기에 달렸다 | +| 통제·증거 | M1(문서가 틀림) · E3(실험 ⑧) + 저장소 테스트 주석 | +| 확실성과 남은 가정 | 표준 SW 수명주기 동작이다. 실제 사용자 탭 패턴은 제품마다 다르다 | +| 결정의 근거 | 적용 제외 — 문서를 실제 동작에 맞추는 일이다. handshake 자체의 선택은 5.1절에서 본다 | +| 이해 비용 | 운영자는 장애 중에 이 문장만 보고 판단한다. 실제 동작을 알려면 SW 명세와 e2e 주석을 읽어야 한다 | +| 최소 개선 방향 | 문장을 고친다: "새 워커는 `requestActivation()`이 성공하거나, 그 범위의 탭이 모두 닫히면 활성화된다. 결함 있는 워커가 waiting에 있으면 다음 릴리스로 교체하거나 `REMOVE_REGISTRATION`을 배포한다" | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 2줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 운영 문서의 활성화 조건이 두 경로를 모두 적는다 | +| 검증 방법 | 문서 대조 | + +### 06-03 설계의 페이지 쪽 계약 셋(PAGE_HELLO 호환 handshake, UPDATE_READY, SW reload guard)이 없고, 흔적만 남음 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 구조적 위험(설계와 코드 불일치) | +| 관련 관점 | 5, 17, 9, 24, 4 | +| 근거 | 설계 17.8은 메시지 12종에 `PAGE_HELLO`·`WORKER_HELLO_ACK`·`UPDATE_READY`를 넣는다. 17.10은 "waiting worker sends `UPDATE_READY`", 17.13은 "after reload `PAGE_HELLO` handshake required; handshake failure → `INCOMPATIBLE`"과 `SERVICE_WORKER_RELOAD_GUARD`(512바이트, 10분)를 정한다(`…closed-deep-design.md:3540-3542`, `:3599`, `:3644-3665`). 17.11은 drain 요청을 받은 탭이 "closes new mutation/realtime/offline admission"이라고 적는다(`:3619`). 코드: 파서는 세 kind를 받아들인다(`service-worker-protocol.ts:16-18`). 보내거나 처리하는 곳은 `src`·`tests`에 없다. 상수 `reloadGuardBytes`·`reloadGuardTtlMs`(`src/contracts/service-worker.ts:27-28`)는 읽는 곳이 없다. `retainedPreviousCaches`(`:26`)는 `void`로만 참조된다(`service-worker-lifecycle.ts:169`). drain 응답은 blocker 결과만 돌려주고 admission을 닫지 않는다(`service-worker-page-controller.ts:281-290`). `start()`는 컨트롤러가 어느 빌드의 워커인지 보지 않고 `ACTIVE`를 보고한다(`:208-216`) | +| 발생 조건 | 제품이 설계 문서를 보고 "호환 검사와 reload guard는 템플릿에 있다"고 판단하고 활성화·reload UI를 붙인다. 또는 쓰기 요청을 가로채는 handler(오프라인 sync, push)를 추가하면서 drain이 admission을 닫는다고 가정한다 | +| 영향 | 현재 handler(`PWA_STATIC_ASSETS`)는 해시 GET만 답하므로 지금 당장의 피해는 작다. 제품이 `onReloadRequired`에 자동 reload를 붙이면 반복 reload를 막을 장치가 없다(레시피 5단계는 "reload를 안내한다"만 적는다, `optional-adapter-recipes.md:129`). health가 `AVAILABLE`이어도 페이지와 워커의 빌드가 같다는 뜻이 아니다 | +| 심각도·우선순위 | Low · P3. 피해는 제품이 해당 기능을 붙일 때 생긴다. 지금은 주장과 코드의 차이다 | +| 통제·증거 | 설계 M1, 코드 M0 · E1 | +| 확실성과 남은 가정 | 세 기능이 없다는 것은 확인했다. 의도적으로 뺐다는 기록은 찾지 못했다 | +| 결정의 근거 | 확인한 사실: 위 코드 위치. 기록된 의도: 설계 17.8·17.10·17.13. 리뷰어의 추론: 현재 handler 구성에서는 handshake 없이도 안전하다(5.1절) | +| 이해 비용 | 제품 개발자는 설계 문서·프로토콜 타입·상수를 보고 기능이 있다고 읽는다. 없다는 것은 호출부를 모두 찾아봐야 안다 | +| 최소 개선 방향 | 둘 중 하나를 고른다. (a) 설계 17.8·17.10·17.13에 "baseline 미구현, 제품이 활성화 UI를 붙일 때 구현"을 적고, 세 kind와 상수 2개를 지운다. (b) 레시피 4·5단계에 reload guard 구현을 체크리스트로 넣는다 | +| 대안 비교 | (a) 문서 정정 + 흔적 제거: 비용 작음, 주장과 코드가 같아진다. (b) 체크리스트만: 흔적은 남지만 제품이 놓치지 않는다. (c) 세 기능 구현: 템플릿에 소비자(UI)가 없어 검증이 e2e 사본 고치기에 기대게 된다. 가장 비싸다. (a)를 먼저, 제품 UI가 생기면 (c)를 비교 | +| 단순화의 보존 조건 | kind를 지워도 V1 메시지의 키 집합·버전 검사는 그대로다. 새 kind가 오면 `UNKNOWN_KIND`로 거절된다(`service-worker-protocol.ts:66-68`). 현재+직전 캐시 1개 유지는 변이 M2가 지킨다 | +| 비용·부작용 | (a) 설계 3곳·코드 5줄 | +| 재검토 조건 | 제품이 자동 reload나 쓰기 handler를 붙이면 (c)를 다시 비교한다 | +| 완료 기준 | 설계·프로토콜 타입·상수가 실제 구현과 같다 | +| 검증 방법 | 문서 대조. kind를 지우면 `check:types`와 SW 단위 테스트 통과 | + +### 06-04 SW 보호 장치 3개는 지워도 테스트가 모두 통과함 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안(테스트 공백) | +| 관련 관점 | 10, 12, 15 | +| 근거 | 변이 14건 중 3건이 생존했다(`scratchpad/wt06-mutations.log`). **M1** install fetch의 `credentials: "omit"`·`redirect: "error"` 삭제(`service-worker-static-assets.ts:280-285`) → SW 테스트 70건 통과. **M3** 같은 `ACTIVATE_REQUEST` nonce 재사용 거절 삭제(`service-worker-lifecycle.ts:331`) → 70건 통과. **M9** 요청을 받지 않은 client의 `CLIENT_DRAINED` 거절 삭제(`service-worker-lifecycle.ts:465`) → 70건 통과. 같은 파일의 다른 보호 장치 11개는 검출됐다(7절) | +| 발생 조건 | 이 줄들을 리팩터링 중 지우거나 조건을 바꾼다 | +| 영향 | 지금 동작은 맞다. 회귀가 생겨도 게이트가 알리지 않는다. 각 장치의 단독 피해는 작다: M1은 sha256 검증이 바이트를 지키고, M3은 같은 drain을 한 번 더 돌릴 뿐이며, M9는 위조하려면 UUID nonce를 알아야 한다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 구현 M2, 검출 없음 · E2(변이) | +| 확실성과 남은 가정 | 단위 테스트 2파일만 돌렸다. e2e가 M1을 잡는지는 확인하지 않았다(코드상 fetch init을 보는 곳이 없다) | +| 결정의 근거 | 적용 제외 — 테스트를 더할지의 문제다 | +| 이해 비용 | 다음 수정자는 이 줄들이 지켜야 하는 규칙인지 테스트에서 알 수 없다 | +| 최소 개선 방향 | `service-worker-runtime.test.ts`에 3건: fetch init의 `credentials`·`redirect`를 기록해 비교, 같은 nonce 두 번째 요청이 `REJECTED`, 범위 밖 client id의 `CLIENT_DRAINED`가 drain을 끝내지 않음 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 3개, 기존 fake로 충분하다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | M1·M3·M9 변이를 다시 넣으면 각각 1건 이상 실패한다 | +| 검증 방법 | `scratchpad/mutate-06.mjs M1,M3,M9`와 같은 변이 재실행 | + +### 06-05 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 + +| 필드 | 내용 | +| --- | --- | +| 성격 | 개선 제안(성능) | +| 관련 관점 | 14, 13 | +| 근거 | install은 모든 자산을 `cache: "no-store"`로 받는다(`service-worker-static-assets.ts:280-285`). 이전 릴리스 캐시에 같은 URL(= 같은 해시 = 같은 바이트)이 있어도 쓰지 않는다(`installCandidate`, `:221-267`). 캐시 이름은 자산 집합 전체의 digest라(`:161`) 파일 하나만 바뀌어도 새 후보 캐시에 28개를 모두 받는다. 이번 빌드 기준 28파일 767,076바이트(749 KiB, 가장 큰 파일 216,610바이트)다. 상한은 256개·5 MiB다(`src/contracts/service-worker.ts:14-16`). 첫 설치에서도 페이지가 이미 받은 자산을 HTTP 캐시를 건너뛰고 다시 받는다. 설계 17.9는 `no-store`를 요구하지 않는다(`…closed-deep-design.md:3566-3595`) | +| 발생 조건 | SW `ACTIVE`인 제품이 릴리스할 때마다, 워커를 가진 모든 사용자 | +| 영향 | 사용자마다 릴리스당 사전 캐시 전체 크기만큼 내려받는다(지금 749 KiB, 압축 전). 기능이 늘면 5 MiB까지 커진다. 모바일 데이터 비용과 install 시간(상한 60초)에 영향을 준다 | +| 심각도·우선순위 | Low · P3. 정확성 문제는 없다 | +| 통제·증거 | 해당 없음 · E1 + 빌드 산출물 크기 | +| 확실성과 남은 가정 | 실제 전송량은 서버 압축에 따라 줄어든다. 측정하지 않았다 | +| 결정의 근거 | 확인한 사실: 위 코드. 기록된 의도: 없음. 리뷰어의 추론: `no-store`는 HTTP 캐시에 상한 바이트가 있을 가능성을 피하려는 선택으로 보인다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | 이전 릴리스 캐시에 같은 URL이 있으면 그 응답을 읽어 sha256을 다시 확인한 뒤 새 후보 캐시에 넣는다. 없을 때만 네트워크로 받는다 | +| 대안 비교 | (a) 현상 유지: 단순, 릴리스마다 전체 다운로드. (b) 이전 캐시 재사용 + digest 재확인: 바뀐 파일만 받는다. 검증 강도는 같다. (c) `cache: "default"`로 HTTP 캐시 사용: 코드 한 줄, 첫 설치 중복도 줄지만 HTTP 캐시의 깨진 항목이 install을 계속 실패시킬 수 있다(검증은 fail-closed라 안전하지만 회복이 늦다). (b)가 검증 강도를 지키면서 비용을 줄인다 | +| 단순화의 보존 조건 | 모든 바이트는 manifest sha256과 맞아야 캐시에 들어간다. 하나라도 실패하면 이번에 만든 후보 캐시만 지운다. 크기·타입 검사와 상한은 그대로다 | +| 비용·부작용 | install 코드 수십 줄과 테스트. 이전 캐시를 열어야 하므로 install 중 Cache Storage 읽기가 늘어난다 | +| 재검토 조건 | 사전 캐시가 1 MiB를 넘거나, 릴리스 빈도가 높아 사용자 다운로드가 문제로 관측되면 (b)를 한다 | +| 완료 기준 | 파일 1개만 바뀐 B 릴리스 install에서 네트워크 요청이 1건이다 | +| 검증 방법 | e2e 도우미의 `served` 기록으로 B install 요청 수를 센다(`service-worker-builds.ts:218-224`) | + +## 5. 설계 선택 검토 (41절) + +### 5.1 install에서 `skipWaiting()`을 부르지 않고, 활성화를 페이지 handshake에 맡긴다 + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 새 배포 뒤 옛 탭이 청크를 잃지 않는다. 새 워커가 옛 페이지와 섞여 화면을 깨지 않는다(설계 17.12). 저장하지 않은 편집이 있는 탭이 있으면 자동 활성화를 막는다(17.10) | +| 2. 지킬 성질 | 워커 교체가 열린 탭의 동작을 바꾸지 않는다. HTML과 자산은 같은 릴리스에서 온다 | +| 3. 현재 보장 | install에서 `skipWaiting()` 없음, activate에서 `clients.claim()` 없음(`service-worker-entry.ts:82-90`). `requestActivation()` → 범위 안 모든 창 drain → `skipWaiting()`(`service-worker-lifecycle.ts:325-374`). source·nonce·빌드 검사(변이 M4·M5·M11 검출). **보장하지 않는 것**: 템플릿 composition은 `requestActivation()`을 부르지 않는다. 실제 활성화는 범위 안 탭이 모두 닫힐 때 일어난다(실험 ⑧). drain은 admission을 닫지 않는다(06-03) | +| 4. 대안 | (a) 현행 유지 + 문서 정정 (b) handshake를 지우고 브라우저 기본 활성화만 쓴다 (c) install에서 `skipWaiting()`, claim 없음 (d) `skipWaiting()` + `clients.claim()` | +| 5. 비교 | (a) handshake 코드 약 290줄(page `runActivation`·drain 응답, worker drain)을 유지한다. 기본 동작은 (b)와 같고, 제품이 UI를 붙이면 바로 쓸 수 있다. (b) 코드가 줄지만, 쓰기 요청을 다루는 handler가 들어오면 다시 필요하다. 업데이트가 "탭을 모두 닫을 때까지" 늦어지는 점은 (a)의 기본과 같다. (c) 업데이트가 빠르다. 옛 탭은 이전 릴리스 캐시로 계속 동작하지만, 다음 릴리스의 activate가 그 캐시를 지운다. 옛 탭이 새 워커 아래에서 도는 기간이 길어진다. 설계 17.12가 금지한다. (d) 첫 방문 페이지까지 바로 제어한다. 해시 자산만 다루는 지금 이득이 작고 설계가 금지한다 | +| 6. 현재 조건의 선택 | (a)가 타당하다. 지금 handler(`PWA_STATIC_ASSETS`)만 보면 handshake가 막는 위험은 작다. 그러나 설계가 예고한 쓰기 handler(오프라인 sync)를 위한 확장 지점이고, source·nonce 검사가 테스트로 지켜진다. 다만 "활성화는 `requestActivation()`으로만"이라는 운영 문서(06-02)와 "drain이 admission을 닫는다"는 설계(06-03)는 코드와 다르다 | +| 7. 재검토 조건 | 두 소비자 모두 활성화 UI를 붙이지 않은 채 다음 동기화가 오면 (b)를 다시 비교한다. 쓰기 요청을 가로채는 handler가 추가되면 drain의 admission 닫기를 먼저 구현한다 | + +- 확인한 사실: 위 코드, 실험 ⑧, `src`에 `requestActivation` 호출 0건. +- 기록된 의도: 설계 17.10~17.12, 레시피 4·5단계(`optional-adapter-recipes.md:127-129`). +- 리뷰어의 추론: 해시 자산만 다루는 지금은 (b)와 (a)의 사용자 체감 차이가 없다. + +### 5.2 SW를 두 번째 Vite 빌드로 만든다 (0929 4.2절 재확인) + +| 질문 | 답 | +| --- | --- | +| 1. 무엇이 필요한가 | 워커가 앱 빌드의 해시 자산 목록을 컴파일 시점에 가진다(설계 18.3 "the worker never fetches one", `src/contracts/service-worker.ts:97`) | +| 2. 지킬 성질 | 워커 출력은 `dist/service-worker.js` 하나다. 두 번째 빌드는 앱 산출물을 바꾸지 않는다. 이 둘째 성질은 여전히 어디에도 적혀 있지 않다(`build-frontend.ts:31-37`은 3단계의 `public/` 복사만 적는다) | +| 3. 현재 보장 | 입력 1개, `emptyOutDir: false`, `inlineDynamicImports`(`vite.service-worker.config.ts:69-82`). 앱 산출물 불변은 보장하지 않는다(0929/06-01 재현). **수정 확인(실험 ⑤)**: `publicDir: false` 한 줄을 넣은 production + `/app/` 빌드 결과는 아래 표 | +| 4. 대안 | (a) 현상 유지 + `publicDir: false` (b) 앱 빌드 plugin의 `closeBundle`에서 워커를 만든다 (c) Vite `build()`를 `configFile: false`로 호출(`scripts/lib/optional-recipe-bundle.ts:112-130`과 같은 방식) | +| 5. 비교 | (a) 한 줄, 단계가 나뉘어 실패 지점이 분명하다. (b) 빌드 1회로 줄지만 앱 설정에 워커 지식이 섞인다. (c) 기본값이 명시적이지만 스크립트가 하나 는다 | +| 6. 현재 조건의 선택 | two-pass 유지가 타당하다. 다만 성질 2를 설정과 테스트로 고정해야 한다. 빌드 로그에는 Vite 8.1.5의 `inlineDynamicImports option is deprecated` 경고가 이번에도 나왔다 | +| 7. 재검토 조건 | Vite가 `inlineDynamicImports`를 없애거나 워커가 여러 청크를 필요로 하면 (b)·(c)를 비교한다 | + +| 실험 ⑤ 빌드 | `dist/config.json` | admission(production) | +| --- | --- | --- | +| 수정 없음, production | `APP_ENV local`, `AUTH_MODE demo`, `http://localhost:8080/` | 거절 4건 | +| `publicDir: false`, production + `/app/` | `APP_ENV production`, `AUTH_MODE external`, `https://api.example.com/`, `RELEASE_MANIFEST_URL /app/release-manifest.json` | `ADMITTED` | + +0929 4.1절(오프라인 셸 없이 해시 파일만 캐시)과 4.3절(Web Lock 직렬화, `revokeForeign`)은 코드가 같아 결론도 같다. 4.3절의 Web Lock 우회 변이는 지난 라운드에 검출됐다. 이번에는 다른 보호 장치를 골라 변이했다(7절). + +## 6. 리팩토링 후보 + +| 후보 | 왜 | 보존해야 할 동작·타입·실패 계약 | +| --- | --- | --- | +| R1. `SERVICE_WORKER_BOUNDS.retainedPreviousCaches`를 `selectCachesToDelete`가 쓰게 하거나 상수를 지운다(`service-worker-lifecycle.ts:169`) | 읽히지 않는 상수가 "설정 가능하다"는 오해를 만든다 | 현재 + 마커가 가장 높은 이전 캐시 1개 유지(M2가 검출). 소유하지 않은 캐시 이름은 건드리지 않는다 | +| R2. `validateActiveFence` 두 벌(`inbound/push-event-adapter.ts:196-214`, `inbound/notification-click-adapter.ts:353-379`)을 fence store의 함수 하나로 | 지금은 operation 이름만 다르고 갈라지지 않았다. 규칙이 바뀌면 두 곳을 같이 고쳐야 한다 | 처음과 마지막 두 번 읽기(M6·M7가 검출). 실패 코드 `ASSOCIATION_MISMATCH`·`RELEASE_MISMATCH`와 operation 이름 | +| R3. `SYNC_WAKE_OBSERVED`를 `createServiceWorkerMessage`로 만든다(`service-worker-entry.ts:169-176`) | 이곳만 `protocolVersion: 1`을 숫자로 직접 쓴다. 버전을 올리면 이 메시지만 파서에서 거절된다 | 키 집합(`protocolVersion`, `kind`, `messageId`, `sourceBuildId`)과 targetBuildId 없음 | +| R4. marker 읽기 deadline(5초)을 fake timer로 시험한다(`service-worker-lifecycle.ts:558`, 테스트 `service-worker-runtime.test.ts:1907-1923`) | 테스트 1건이 실제 5.0초를 기다린다. 이 영역 단위 테스트 6.9초 중 대부분이다 | 청크를 주지 않는 stream에서도 activate가 끝나고, reader cancel이 1회 이상 일어난다 | +| R5. `src/adapters/service-worker/`를 `worker/`·`page/`로 나누기 | 파일 이름만으로 realm을 알 수 없다 | **기각.** `tsconfig.service-worker.json:13-17`의 exclude 3줄과 배럴 주석(`index.ts:1-14`)이 이미 구분한다. 페이지 파일을 잘못 두면 `check:types:service-worker`가 `document`에서 실패한다. 파일 7개라 나누는 이득이 작다 | + +## 7. 실행 결과 상세 + +### 7.1 변이 실험 (wt-06m, 단위 테스트, `scratchpad/wt06-mutations.log`) + +| ID | 바꾼 것 | 결과 | 잡은 테스트 | +| --- | --- | --- | --- | +| M1 | install fetch의 `credentials: "omit"`·`redirect: "error"` 삭제 | **생존** (70 통과) | — (06-04) | +| M2 | activate가 직전 캐시도 지움 | 검출 (2 실패) | `retains the immediately previous verified static cache on activation` | +| M3 | 같은 activate nonce 재사용 허용 | **생존** (70 통과) | — (06-04) | +| M4 | 페이지가 모든 메시지 source를 신뢰 | 검출 | `accepts replies only from the captured waiting or controller source` | +| M5 | 활성화 응답 source 검사 삭제 | 검출 | `ends an activation whose reply source was swapped` | +| M6 | 클릭의 두 번째 fence 검사 삭제 | 검출 | `rechecks the durable generation after client enumeration` | +| M7 | push의 두 번째 fence 검사 삭제 | 검출 | `rechecks the durable generation after async push work` | +| M8 | `unregister()`가 false여도 `UNREGISTERED` | 검출 | `does not hide 'unregister false' behind DISABLED` | +| M9 | 요청받지 않은 client의 drain 응답 허용 | **생존** (70 통과) | — (06-04) | +| M10 | 선언 바이트를 넘어도 계속 읽음 | 검출 | `stops reading as soon as the streamed body exceeds declared bytes` | +| M11 | 범위 밖 창도 drain 대상 | 검출 | `drains only page clients inside the exact registration scope` | +| M12 | `PURGE_OWNED_RESOURCES`도 워커 파일 허용 | 검출 | `rejects a PURGE_OWNED_RESOURCES selection` | +| M13 | navigation을 network-only로 강제하지 않음 | 검출 | `answers manifest assets and leaves navigations, API, cross-origin and unhashed r…` | +| M14 | 잘못된 캐시 hit을 지우지 않고 응답 | 검출 | `deletes an invalid hit only from the current release cache` | + +### 7.2 waiting 워커 활성화 실험 ⑧ (`scratchpad/sw-waiting-activation.mjs`, `scratchpad/wt06-waiting.log`) + +조건: 같은 URL `/service-worker.js`의 A·B 두 버전을 내는 최소 서버. 두 워커 모두 install·activate에서 아무것도 하지 않는다(템플릿처럼 `skipWaiting()`·`clients.claim()` 없음). 등록은 `updateViaCache: "none"`. 순서: A 등록 → reload로 제어 확인 → 서버를 B로 바꾸고 `update()` → `page.reload()` → 탭을 닫고 1.5초 뒤 같은 context에 새 탭. 직전 부하 17.6. + +| 단계 | chromium | webkit | firefox | +| --- | --- | --- | --- | +| A 제어 | active, 제어됨 | active, 제어됨 | active, **제어 안 됨** | +| B `update()` 뒤 | B waiting(`installed`) | B waiting(`installed`) | waiting 없음(B가 바로 활성화) | +| `page.reload()` 뒤 | B 여전히 waiting | B 여전히 waiting | waiting 없음 | +| 탭을 모두 닫고 새 탭 | **waiting 없음, active 1개** → B 활성화 | **waiting 없음, active 1개** → B 활성화 | waiting 없음 | + +- 결론: `requestActivation()` 없이도 범위 안 탭이 모두 닫히면 B가 활성화된다(06-02). reload만으로는 활성화되지 않는다. +- firefox는 Playwright에서 페이지가 제어되지 않는다는 저장소의 격리 기록(`service-worker-update.spec.ts:155-163`)과 같은 결과다. 제어되는 탭이 없으니 B가 바로 활성화됐다. +- 한계: 워커 URL이 같아 active가 B인지 `scriptURL`로는 구분하지 못한다. B가 waiting에서 사라지고 active가 하나만 남은 것으로 판단했다(세 번째 버전은 없다). + +### 7.3 SW e2e (wt-06m, `playwright.review06.config.ts`, webServer 없음, `scratchpad/wt06-e2e.log`) + +조건: `npx playwright test -c playwright.review06.config.ts`(wt-06m, workers 1). spec이 스스로 A·B 빌드 2벌을 만들고 자체 서버를 띄운다. 직전 부하 25.3. + +- 결과: **12건 통과**(chromium 6, webkit 6), 23.5초, 전체 24초. +- 확인한 것: 해시 자산 install(JS MIME 2종, gzip), update-waiting·reload-required 알림과 handshake 활성화, B가 제어한 뒤 A의 지워진 청크를 이전 캐시에서 응답, `REMOVE_REGISTRATION` 자기 해제 워커가 부팅을 막는 워커를 걷어냄, 수정하지 않은 빌드 스크립트로 워커 1파일 생성. +- 한계: 모두 SW 선택 `null` → 사본에서 `ACTIVE`로 바꾸는 경로이고 local 프로필이다. 그래서 0929/06-01(비 local 프로필)과 0929/06-02(하위 경로)는 이 spec으로 보이지 않는다. firefox는 실행하지 않았다(격리). + +## 8. 렌즈별 관찰 + +### 8.1 성능 + +| 비용 | 값 | 근거 | +| --- | --- | --- | +| 워커 스크립트 | 21.27 kB, gzip 7.87 kB | SW `ACTIVE` 빌드 로그(`scratchpad/wt06-build-prod.log`) | +| 사전 캐시 | 28파일, 767,076바이트(749 KiB). 상한 대비 개수 11%, 바이트 14.6% | `.generated/frontend-runtime/service-worker-assets.ts` | +| install 요청 | 28건, 동시 4개, 모두 `no-store`. 릴리스마다 전체 재다운로드(06-05) | `service-worker-static-assets.ts:257-259`, `:280-285` | +| fetch 가로채기 | 동기 분류(URL 파싱 + Set 조회). 이전 릴리스 fallback 요청은 소유 캐시(최대 2개)를 열어 마커를 읽는다 | `service-worker-lifecycle.ts:228-248`, `:272-278` | +| 기본 구성의 페이지 번들 | 최대 14,790바이트, gzip 4,348바이트. SW `null`이어도 `register-service-worker.ts`가 page controller를 정적 import하므로 들어간다. 실제 `dist/assets/boot-*.js`에는 page controller·프로토콜 문자열이 있고 워커 전용 lifecycle 문자열(`__service-worker-activation-v1__`)은 없다. 위 값은 tree-shaking 전 모듈을 모두 센 상한이다 | 실험 ⑩(`register-service-worker.ts`만 진입점으로 둔 Vite lib 빌드), 메인 `dist` 문자열 검색 | +| 단위 테스트 | 11파일 167건 6.9초(부하 9.0). 이 중 1건이 실제 5.0초를 기다린다(R4). `test:unit` 전체에서는 4번째로 느린 파일(5.3초)이고 가장 느린 파일은 7.0초라 전체 시간을 늘리지는 않는다 | gate `test_unit.log` | + +### 8.2 폴더 구조 + +- `src/adapters/service-worker/`는 worker realm 4파일과 page realm 2파일, 배럴이 한 폴더에 있다. 구분은 `tsconfig.service-worker.json`의 exclude와 배럴 주석이 맡는다. 잘못 두면 타입 검사가 잡는다. 유지가 타당하다(R5). +- `src/adapters/web-push/`의 `inbound/`는 워커 이벤트 어댑터 2개를 담는다. page realm인 `push-subscription-adapter.ts`는 루트에 워커용 `service-worker-runtime.ts`와 나란히 있다. `service-worker-runtime.ts`라는 이름은 `service-worker/service-worker-lifecycle.ts`의 runtime과 헷갈린다. 파일 수가 적어 찾기는 어렵지 않다. +- SW 빌드 관련 파일이 루트(`vite.service-worker.config.ts`, `tsconfig.service-worker.json`)와 `scripts/`, `scripts/lib/` 세 곳에 흩어져 있다. `build-frontend.ts` 머리 주석이 순서를 설명해서 따라갈 수 있다. + +### 8.3 테스트 + +- 위험을 잡는가: 변이 14건 중 11건 검출. 생존 3건은 06-04. SW를 켠 비 local 빌드(0929/06-01)와 하위 경로(0929/06-02, 06-01)를 보는 테스트는 여전히 없다. +- 실행 시간: 단위 6.9초 중 5.0초가 1건(R4). SW e2e 12건은 빌드 4벌을 포함해 24초다(7.3절). + +## 9. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 | +| --- | --- | --- | --- | --- | --- | +| 1 | 코드 성숙도 | P | M2 / M2 | E1·E2 | 런타임 검증은 exact하다. 빌드 설정이 앱 산출물을 바꾸고(0929/06-01), 사전 캐시 URL(0929/06-02)과 정상 클릭 URL(06-01)이 base를 잃는다 | +| 2 | 구조적 성숙도 | O | M3 / M3 | E1·E2 | worker·page realm을 tsconfig로 나누고(`tsconfig.service-worker.json:8-17`), 워커가 page 코드를 import하지 못하게 막는다(`.dependency-cruiser.json:196-206`, `check:architecture` rc=0). 엔트리는 web-push를 import하지 않는다(`service-worker-entry.ts:144-158`) | +| 3 | 변경 용이성 | P | M1 / M1 | E1 | 오프라인 셸·WEB_PUSH 조립·활성화 UI 모두 템플릿 파일 수정이 필요하다(0929/06-03, `create-runtime-composition.ts`) | +| 4 | 인지 부하 | P | - | E1 | 계약 주석은 충실하다. page controller 642줄, lifecycle 736줄, push adapter 1,203줄. 설계·운영 문서가 코드보다 많은 기능을 주장한다(06-02, 06-03) | +| 5 | 위험 가시성 | P | M1 / M1 | E1 | `build-frontend.ts:31-37`이 6단계의 `public/` 복사를 적지 않는다. 읽히지 않는 상수 3개가 기능이 있는 것처럼 보이게 한다(06-03) | +| 6 | 실패 성숙도 | P | M2 / M2 | E1·E2 | install 거절 11종, drain 시간 초과와 명시 거절을 구분한다. 워커의 거절 코드는 페이지에 오지 않아 `INSTALL_FAILED`만 남는다 | +| 7 | 운영 성숙도 **(깊게)** | P | M2 / M1~M2 | E1·E2 | 시작 실패만 `service-worker.start.failed`로 남는다(`optional-runtime-host.ts:113-119`, component 테스트 통과). 업데이트 설치 실패·`observe`·`health()`는 연결되지 않았고 레시피가 다운스트림 몫으로 적는다(0925/06-05). 운영 문서의 활성화 조건이 틀렸다(06-02) | +| 8 | 디버깅 가능성 | P | M2 / M1 | E1 | `observe` hook과 reason 코드는 있으나 조립되지 않는다(7번과 같은 원인) | +| 9 | 유지보수 성숙도 | P | M1 / M1 | E1 | `retainedPreviousCaches`·`reloadGuard*` 상수와 메시지 kind 3개가 쓰이지 않는다(06-03, R1). `validateActiveFence` 두 벌은 아직 같다(R2) | +| 10 | 테스트 성숙도 | P | M3 / M3(기본 구성) | E2·E3 | 단위 167건 통과, 변이 11/14 검출(06-04). SW e2e 12건 통과(chromium·webkit, 7.3절). SW를 켠 비 local 빌드·하위 경로 테스트가 없고, SW를 켠 트리에서 e2e 도우미가 멈춘다(0929/06-04) | +| 11 | 데이터 성숙도 | O | M2 / M2 | E1·E2 | 캐시는 `credentials: "omit"`으로 받은 해시 공개 자산만 담는다. 소유 캐시 이름은 exact 비교(`src/contracts/service-worker.ts:129-134`). push fence에 계정 ID와 endpoint가 없다 | +| 12 | 동시성 성숙도 **(깊게)** | P | M3 / M2~M3 | E2 | Web Push 제어는 origin Web Lock으로 직렬화한다(`push-subscription-adapter.ts:467-512`). SW 활성화는 탭 안 single-flight(`service-worker-page-controller.ts:369-376`), source·범위 검사(M4·M5·M11 검출). nonce 재사용·요청받지 않은 응답 거절은 테스트가 없다(06-04, M3·M9). 응답하지 않는 창 하나가 활성화를 막는다(`includeUncontrolled: true`, 안전한 쪽 실패). lock 대기 상한은 호출자 signal에 기댄다 | +| 13 | 확장성 | P | M2 / M2 | E1 | 256개·5 MiB 상한을 빌드에서 막는다(`generate-service-worker-assets.ts:60-86`). 지금 28개·749 KiB. 기능 증가에 따른 도달 시점은 미측정 | +| 14 | 성능 성숙도 | P | M2 / M2 | E1·E3 | fetch 리스너는 `PWA_STATIC_ASSETS`일 때만 등록되고 해시 GET만 가로챈다(`service-worker-entry.ts:94-111`, M13 검출). 릴리스마다 사전 캐시 전체를 다시 받는다(06-05) | +| 15 | 보안 성숙도 **(깊게)** | P | M3 / M2~M3 | E1·E2·E3 | payload를 신뢰하지 않고 클릭 URL은 same-origin만 연다. 두 번 읽는 fence 검사가 변이로 검출된다(M6·M7). 0929/06-01이 demo 인증 설정을 production 산출물에 싣지만 admission이 거절한다(이번 실행 확인). install의 `credentials`·`redirect` 설정은 테스트가 없다(06-04, sha256이 바이트를 지킨다). `revokeForeign`은 호출 규칙에 기댄다(M1, `web-push-control.ts:29-38`) | +| 16 | 의존성 성숙도 | P | - | E3 | 런타임 외부 패키지는 없다. SW 빌드가 Vite 8.1.5에서 `inlineDynamicImports` deprecated 경고를 낸다(이번 빌드 로그) | +| 17 | API / Contract 성숙도 | P | M2 / M2 | E1 | SW 메시지 V1은 exact하다. 처리하지 않는 kind 3개를 받아들인다(06-03). registry `path`의 기준이 정의되지 않았다(06-01). catalog가 오프라인 셸을 약속한다(0929/06-03) | +| 18 | 배포 성숙도 **(깊게)** | P | M3 / M2 | E3 | 옛 탭 청크 fallback과 업데이트 handshake는 이번 e2e로 다시 확인했다(chromium·webkit, 7.3절). SW를 켜면 릴리스 산출물 설정이 틀린다(0929/06-01, 재현). 워커 스크립트의 CDN 캐시 정책이 검사되지 않는다(0929/06-05). 템플릿 기본에서는 활성화가 탭을 모두 닫을 때 일어난다(5.1절) | +| 19 | 설정 성숙도 **(깊게)** | X | M3 / M1 | E3 | SW를 켜는 순간 프로필 설정·`RUNTIME_*` 주입·base path 재작성이 local 문서로 되돌아간다(0929/06-01, 이번 재현). 페이지와 워커가 서로 다른 release manifest URL을 갖는다(`/release-manifest.json` 대 `/app/release-manifest.json`). 사전 캐시 URL(0929/06-02)과 정상 클릭 URL(06-01)이 base를 무시한다 | +| 20 | 개발자 경험 | P | M1 / M1 | E1·E3 | SW 켜기 체크리스트가 있다(`optional-adapter-recipes.md:109-131`). 활성화 UI·observe는 composition을 직접 고쳐야 한다. SW를 켜면 템플릿 e2e가 멈춘다(0929/06-04) | +| 21 | Guardrail 성숙도 | P | M3 / M3(일부) | E2·E3 | build-input 거절, hosting 검사의 워커 파일 검사(M12 검출), release admission은 동작한다. SW 빌드가 dist를 바꾸지 않는지와 워커 스크립트 헤더는 검사하지 않는다 | +| 22 | 추상화 성숙도 | O | M2 / M2 | E1·E2 | 구조적 facade로 워커 없이 테스트한다. WebIDL 모양 fake(`web-push-worker-runtime.test.ts`의 `WebIdlNotification`)가 실제 차이를 가리지 않는다 | +| 23 | 일관성 | P | - | E1 | 같은 repo의 다른 두 번째 Vite 빌드는 `publicDir: false`인데 SW 빌드만 없다(`scripts/lib/optional-recipe-bundle.ts:117`, `:127`). `SYNC_WAKE_OBSERVED`만 프로토콜 버전을 숫자로 직접 쓴다(R3). 거절 클릭과 정상 클릭이 서로 다른 기준 URL을 쓴다(06-01) | +| 24 | 네이밍 / 의미 | P | - | E1 | `retainedPreviousCaches`는 읽히지 않고 "이전 1개"는 코드에 고정돼 있다(06-03, R1) | +| 25 | 조직 확장성 | - | - | - | 적용 제외: 1인 관리 전제(0.1) | +| 26 | Ownership 성숙도 | P | M1 / M1 | E1 | 운영 문서가 코드 경로를 가리킨다. 제거 1단계 유지 기간이 없고(0929/06-06), 활성화 조건 문장이 틀렸다(06-02) | +| 27 | 삭제 가능성 | ? | M3 / 미확인 | E1 | 엔트리가 web-push를 import하지 않아 파일 삭제로 뺄 수 있다고 주장한다(`service-worker-entry.ts:157-158`). `test:realtime-removal`은 pnpm을 불러 실행하지 않았다 | +| 28 | 회복 가능성 **(깊게)** | P | M3 / M3(페이지·워커) | E2·E3 | 런타임 kill switch와 자기 해제 워커가 있다. 자기 해제 워커는 이번 e2e로 다시 확인했다(chromium·webkit, 7.3절). 그 경로는 CDN이 `service-worker.js`를 캐시하지 않는다는 전제에 기대는데 검사가 없다(0929/06-05). 제거 2·3단계에서 비상 경로가 사라진다(0929/06-06). 운영 문서가 새 워커의 활성화 조건을 잘못 적는다(06-02) | + +집계: 적용 27개 중 O 3 · P 22 · X 1 · ? 1, 적용 제외 1. + +## 10. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +| --- | --- | --- | +| `test:realtime-removal`(web-push 삭제 가능성, 27) | fixture 안에서 pnpm을 부른다(`scripts/lib/removal-fixture.ts:185-196`). 지침상 실행하지 않았다 | 오케스트레이터 게이트나 CI에서 실행 | +| 0929/06-02의 브라우저 설치 실패 | 이번에는 빌드 산출물만 봤다 | e2e 도우미에 base 옵션을 넣고 실행 | +| 0929/06-05의 실제 CDN 동작 | CDN 환경 없음 | staging CDN에서 `service-worker.js` 응답 헤더 확인 | +| 얼어 있는 탭이 Web Lock을 쥔 경우 | 브라우저 정책 의존, 재현 환경 없음 | 두 탭 중 하나를 `Page.setWebLifecycleState(frozen)`으로 얼린 채 enable 중 revoke | +| Web Push end-to-end(실제 푸시 서비스, VAPID, 클릭) | 푸시 서버 없음. WEB_PUSH는 빌드에서 거절된다 | 로컬 web-push 서버와 제품 조립 브랜치 | +| 06-05의 실제 전송량 | 서버 압축에 따라 다르다 | e2e 도우미 gzip 옵션으로 B install 전송량 측정 | +| Firefox의 SW 제어(update·recovery spec) | Playwright Firefox 제약으로 격리됨 | 수동 확인 또는 Playwright 업데이트 뒤 재실행 | diff --git a/docs/reviews/2026-11-01-maturity-review/07-contracts.md b/docs/reviews/2026-11-01-maturity-review/07-contracts.md new file mode 100644 index 00000000..d04f35c4 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/07-contracts.md @@ -0,0 +1,445 @@ +# 07 contracts (공유 어휘·외부 계약) — 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 영역 판정(35.8): **조건부 사용 가능** — 외부 입력 검증(런타임 설정·릴리스 매니페스트·exact decode)과 외부 계약 조립기(`composeContractContributions`)는 그대로 써도 된다. 그러나 기능 개발자가 **새 HTTP API 계약을 추가하는 과제**에서는 타입과 이름이 위험을 드러내지 못한다. API 하나를 선언용 행(V2)과 실행용 descriptor(V3)에 두 번 쓰고, 둘을 잇는 검사는 6개 필드뿐이다(07-02). zod를 검증기로 바꾸는 어댑터가 참조 기능 안에만 있어서 기능마다 복사하고, 검증하지 않는 검증기도 같은 타입으로 통과한다(07-03). 참조 기능의 `TEMPLATE_FIXTURE` 출처를 복사한 제품 API는 릴리스 계약 집합에서 조용히 빠진다(07-04). 지난 라운드 발견 7건은 코드가 바뀌지 않아 모두 남았다. + +ID 표기: 이 문서의 `07-NN`은 2026-11-01 라운드 ID다. 2026-09-29 라운드 발견은 `P-07-NN`, 2026-09-25 라운드 FOLLOW-UP 항목은 `F-07-NN`으로 적는다. + +## 0. 결론 + +- **지난 라운드 발견은 모두 남았다.** `af3d8e6..d99301b` 11커밋은 UI 감사 수정과 문서뿐이다. `src/contracts/`, `schemas/`, `config/contracts/`, 레지스트리 스크립트는 한 줄도 바뀌지 않았다(`git diff --stat`). 실험 X2~X5·R1·Z1·V2를 이 커밋에서 다시 돌렸고 결과가 같았다(2절). +- **API 하나를 두 벌로 쓴다(07-02, Medium).** 참조 기능의 `GET_REFERENCE_RESOURCE` 하나에 V2 행 26필드와 V3 descriptor 22필드(`traffic` 안 4필드 별도)를 쓴다. 같은 사실을 다른 이름으로 적는다(`successStatuses`/`acceptedStatuses`, `replayPolicy`/`retrySemantics`, `timeoutMs: null`/`totalDeadlineMs: 10_000`). 레지스트리 게이트는 실행되지 않는 V2만 본다. 실행되는 V3의 검증기 `schemaId`를 바꾸거나(L1), V3에만 새 API를 추가해도(L6) 관련 테스트와 `check:registries`가 모두 통과했다(4.3절). +- **zod 어댑터가 기능 안에 있다(07-03, Medium).** `zodValidator`는 `src/features/reference-feature/contracts/reference-schemas.ts:88`에만 있다. 기능끼리 import는 금지라서 새 기능은 복사한다. 복사본은 이미 갈라졌다(`tests/helpers`는 `structuredClone`이 없다). tech-log는 복사한 뒤 출력 검증기 5개를 모두 `z.unknown()` 통과로 바꿨다. `RuntimeValidator` 타입과 조립기는 이런 검증기를 구분하지 못한다(L5). +- **`TEMPLATE_FIXTURE`를 아무 기능이나 쓸 수 있다(07-04, Medium).** 설계서는 "product feature는 반드시 `EXTERNAL_PACKAGE`"이고 정적 검사가 이를 막는다고 적는다. 조립기는 `featureId`를 보지 않는다. 참조 계약 파일을 복사한 `order` 기능이 조립을 통과했고, 계약 집합 입력은 0개였다(L4). +- **"정본"이라고 적힌 결과 모양은 쓰는 곳이 없다(07-01, Low).** `MappingResult`라는 이름의 타입이 두 파일에 서로 다른 모양으로 있다. 주석이 정본이라고 부르는 쪽은 테스트만 쓴다. 실행 경로(`feature-http-binding.ts`)와 `boundary-mapper.ts` 자신의 helper는 `@deprecated` 별칭을 반환 타입으로 쓴다. F-07-07(폐기 별칭 lint 없음)을 이 항목에 합쳤다. +- **오류 어휘가 둘이다(07-05, Low).** `AppFailure`(`retryable: boolean`, `action`)와 `AppError`(`retryability`, `severity`)가 같은 개념을 다른 이름으로 적는다. 참조 기능은 둘 다 보여 주지만 실행 경로는 `AppFailure`만 읽는다. +- **잘 된 점도 확인했다.** 조립기는 행을 먼저 복사한 뒤 검증하고, 검증한 복사본만 설치한다. 쓰기 API는 `commandEffect` 없이는 조립되지 않고, `KEYED`는 복구 descriptor를, `NEVER`는 재시도 0을 강제한다(`external-contract-runtime.ts:468-513`). 결과 불명 쓰기는 `retryable=false`가 된다. +- **조립·선언 검증 규칙 5개는 테스트가 없다(07-06, Low).** 변이 10종 중 5종이 죽었다. 오류 분류·인증 프로필·검증 이슈 상한·시도 횟수는 잡힌다. 읽기 operation의 command descriptor 금지, `KEYED`의 복구 descriptor 필수, `NEVER`와 재시도 예산의 모순, V2 `KEYED_COMMAND` 정합, mapper 키 일치는 지워도 관련 테스트 686건이 통과했다. +- **`commandRecovery`는 실행기가 읽지 않는다(07-07, Low).** 조립기는 `KEYED` 쓰기에 이 descriptor를 요구하지만 HTTP 실행기는 읽지 않는다. 결과 불명 쓰기의 수습은 기능 gateway 책임이라는 사실이 설계서에만 있다. + +## 1. 리뷰 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 07 | +| 커밋·작업 상태 | `fix/ui-design-audit-2026-11-01` / `d99301b`. 메인 작업 트리 미커밋 변경은 `.claude/`뿐이다 | +| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 영역 경로 | `src/contracts/`(41파일, 8,750줄), `schemas/`(5파일), `config/contracts/`(4파일). 렌즈 과제를 따라가려고 함께 읽은 곳: 참조 기능 `contracts/` 5파일, `src/adapters/http/feature-http-binding.ts:1-120`, `src/features/installed-feature-contracts.ts`, `src/features/installed-contract-contributions.ts` | +| 깊게 본 관점 | 1, 3, 17, 19, 22, 23, 24. 이번 라운드 추가 렌즈: 새 API 계약(DTO 스키마, mapper, Result/AppFailure)을 추가할 때 의도와 위험이 타입·이름에서 드러나는가 | +| 줄 단위로 읽은 코드 | `external-contract-runtime.ts` 전체, `errors.ts` 전체, `result.ts`, `boundary-mapper.ts`, `schema-registry.ts`, `api-operations.ts`, `operation-id.ts`, `validation-issues.ts`, `mutation-intent.ts`, `zod.ts`, `contract-set.ts`, `env.ts:1-70`, `browser-rpc.ts:14-135`, `rest-profiles.ts:310-354`, `src/platform/errors/app-error.ts:1-80`, 참조 기능 `reference-schemas.ts`·`reference-mapper.ts`·`reference-feature-contract.ts`·`reference-feature-contract-contribution.ts`·`reference-error.ts`, `tests/unit/http-operation-v2-v3-parity.test.ts`, `tests/unit/second-api-feature-registries.test.ts:1-120`, `tests/helpers/external-contract-fixture.ts:1-60`, `scripts/lib/registry-compatibility.ts:77-336`, `config/contracts/registry-governance.json:1-245` | +| 읽은 문서(주장) | `docs/architecture/starter-experience.md:110-157`, `src/features/reference-feature/README.md`, `docs/contracts/compatibility.md:1-40`, `docs/architecture/2026-07-30-…-closed-deep-design.md` §4.8(736-746행)·§24.5(5227-5241행), `docs/architecture/api-contract-schema-mapper-and-server-state.md:1-200`, 커밋 `56de543d`(D-15) 메시지 | +| 게이트 결과 | 오케스트레이터가 이 커밋에서 실행한 결과를 읽었다(`scratchpad/gates/summary.txt`). `check:architecture` PASS(376 모듈), `check:types`·`lint` rc=0, `test:unit` 2,353/2,353, `test:contract` 15/15(0.47초), `test:runtime-schema` 56/56(0.59초). `test:system` rc=1은 CI runner 테스트 2건(영역 11) | +| 다운스트림 증거 | `../tech-log-frontend`(브랜치 `chore/template-sync-v0.2.0`, `7a4e201a`)와 `../memento-frontend`(`d3810a0`)를 `grep`으로만 읽었다. 두 repo는 바꾸지 않았다 | +| 이전 리뷰와 비교 | `docs/reviews/2026-09-29-maturity-review/07-contracts.md`의 P-07-01~07과 그 문서가 재확인한 F-07-03·F-07-07을 현재 코드에서 다시 확인했다(2절). 이전 실행 결과는 증거로 쓰지 않았다 | + +### 1.1 실행한 명령과 실험 + +실험은 모두 격리 worktree(`scratchpad/wt-07`, `d99301b`, 메인 `node_modules` 심볼릭 링크)에서 했다. worktree 안에서 `pnpm`은 부르지 않았다. 메인 repo에서는 읽기 전용 node 스크립트(scratchpad의 `tools07/*.ts`)만 돌렸다. + +| ID | 무엇 | 결과 | +|---|---|---| +| R1 | `node scripts/check-registries.ts` (변경 없음) | `11 registries PASS; compatibility=breaking`. diff 3건(breaking 2, additive 1). 증거 파일 15건 중 현재 diff와 맞는 것은 2건 | +| X2 | `REFERENCE_RESOURCE_LIST`의 `navigationLabel`·`navigationOrder`를 `null`로 | FAIL. `field-type-changed` 2건이 breaking 증거 누락 | +| X3 | `REFERENCE_RESOURCE_DETAIL.path`를 `/entries/:resourceId`로 | **PASS.** 기존 `/items/` 증거가 새 값을 덮었다 | +| X4 | governance `loadingSurface` 허용값 1개 추가 | FAIL. `$contract:allowedValues:contract-field-changed` breaking 증거 누락 | +| X5 | `REFERENCE_RESOURCE_STATUS.loadingSurface`를 새 이름으로 | FAIL. `has unknown value reference-resource-archive` | +| Z1 | `platform-route-codecs.ts`의 import를 `"zod/v4"`로 바꾸고 `check-architecture.ts` 실행(`npm_execpath`를 아무 일도 하지 않는 stub으로 지정해 pnpm 없이 그래프 검사만 확인) | 그래프 검사 PASS. 같은 곳을 `"zod"`로 바꾸면 `zod-is-reached-through-contracts-zod` 위반 | +| V2 | `ENV_REGISTRY` runtime 행과 `z.toJSONSchema(runtimeConfigV2ArtifactSchema, {io:"input"})` 비교(`tools07/env-vs-zod.ts`) | 불일치 5곳(`TELEMETRY_ENABLED`, `AUTH_MODE`, `RELEASE_MANIFEST_URL`, `CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`), 스키마에만 있는 키 2개(`BUILD_ID`, `RELEASE_ID`) | +| L1 | V3 `GET_REFERENCE_RESOURCE_CONTRACT`의 `outputValidator` `schemaId`를 `"Whatever"`로 | **모두 통과.** 관련 테스트 29파일 229건, `check:registries` PASS(diff 변화 없음) | +| L2 | V3 LIST `outputValidator`의 `.max(100)`을 `.max(1000)`으로 | 잡힘. `reference-request-fanout.test.ts` 1건 실패 | +| L3 | V3 GET `totalDeadlineMs` 10,000 → 60,000 | **모두 통과.** 29파일, `check:registries` PASS | +| L4 | 참조 계약 행을 복사해 `featureId: "order"`, `source.kind: "TEMPLATE_FIXTURE"`인 두 번째 기여를 만들어 조립(`tools07/fixture-copy.ts`) | **조립 통과.** fixture 기여 2개(`reference-feature`, `order`), `externalPackages` 0개 | +| L5 | 같은 스크립트에서 출력 검증기를 `{ success: true, data: value }`만 돌려주는 통과 검증기로 | 조립 통과. `invokeValidator(…, {anything: 1})` → `VALID` | +| L6 | V3 기여에만 새 operation `ARCHIVE_REFERENCE_RESOURCE`(새 경로)를 추가, V2 행 없음 | **모두 통과.** `tsc` 오류 0, 29파일, `check:registries` PASS(diff 변화 없음) | +| L7 | 참조 응답 DTO `referenceResourceDtoSchema`의 `.strip()`을 `.strict()`로(스키마 메타데이터는 `STRIP_UNKNOWN` 그대로) | 4.3절 표 | +| MX1~MX10 | `src/contracts/` 변이 10종 | 4.3절 표 | +| P1 | `composeContractContributions`(HTTP 3행) 2,000회 반복 시간(`tools07/bench-compose.ts`, 부하 9.0) | 1회 48µs | +| P2 | esbuild로 계약 모듈 단독 번들(minify) 크기, `dist/assets` 청크 크기(17:42 빌드본, 읽기만) | 7절 | +| D1 | 두 제품의 `zodValidator`·`TEMPLATE_FIXTURE`·`MappingResult`·`AppError` 사용 grep | tech-log: `zodValidator` 복사 1벌, 출력 검증기 5개 모두 envelope만 검증하고 payload는 `z.unknown()`, 입력 검증기 5개 모두 통과 검증기, 제품 기여 3개는 모두 `EXTERNAL_PACKAGE`, `AppError` 사용 0. memento: 제품 API 기여 없음 | + +### 1.2 확인하지 못한 범위 + +- `realtime-streams.ts`, `query-keys.ts`, `server-state.ts`, `service-worker*.ts`, `web-worker.ts`, `web-push.ts`, `cache-invalidation.ts`, `query-invalidation.ts`는 이번에도 줄 단위로 읽지 않았다. `browser-rpc.ts`는 타입 선언(14-135행)만 읽었다. +- zod `"zod/v4"` 우회가 실제 CSP 위반으로 이어지는 청크 배치는 이번에 빌드하지 않았다. 지난 라운드 결과(재현 안 됨)를 증거로 쓰지 않고 `미확인`으로 둔다. +- `src/contracts/` 코드가 실제 번들에서 차지하는 몫은 sourcemap이 없어 청크에서 떼어 재지 못했다. 단독 번들 크기로 대신했다(7절). +- 다운스트림에서 `check:registries`를 직접 돌리지 않았다. + +## 2. 지난 발견 재확인 + +| ID | 내용 | 상태 | 근거 (이 커밋) | +|---|---|---|---| +| P-07-01 | breaking 증거가 값과 묶이지 않아 같은 row·field의 다음 변경을 통과시킨다 | **남음** | 증거 키가 `registryId:row:field:kind`뿐이다(`scripts/lib/registry-compatibility.ts:83-90`). 증거는 5필드가 비었는지만 본다(`:300-336`). X3 PASS. R1: 증거 15건 중 13건이 현재 diff와 무관 | +| P-07-02 | nullable 전환·allowlist 확장을 breaking으로 막는다 | **남음** | 값의 JS 타입이 다르면 `breakingFields`를 보기 전에 breaking이다(`:237-239`). governance는 `string|null`로 선언한다(`config/contracts/registry-governance.json:38-39`). X2·X4 FAIL. 템플릿 자신의 증거가 "the value itself did not change"라고 적는다(`registry-change-evidence.json:110`) | +| P-07-03 | 기능 라우트 하나에도 템플릿 governance allowlist를 고쳐야 하고, 문서는 반대로 적는다 | **남음** | allowlist(`registry-governance.json:42-60`), 거부(`scripts/check-registries.ts:483`), 문서(`docs/architecture/starter-experience.md:145-147`), 고정 테스트는 `routes: {}`(`tests/unit/second-api-feature-registries.test.ts:38`). X5 FAIL | +| P-07-04 | 다운스트림 증거 절차가 안내되지 않는다 | **남음** | 실패 메시지가 changeId뿐이다(`registry-compatibility.ts:314`). `docs/contracts/compatibility.md`에 레지스트리 증거 절이 없다(grep 0건). 재승인은 owner·reason만 요구한다(`scripts/update-registry-baseline.ts:10-18`) | +| P-07-05 | `ENV_REGISTRY` runtime 행이 zod 스키마와 다르다 | **남음** | `src/contracts/env.ts:50-63` vs `release-artifacts.ts:170-178`. V2: 불일치 5곳 + 스키마 전용 키 2개 | +| P-07-06 | zod facade 규칙이 `"zod"`만 막는다 | **남음** | `.dependency-cruiser.json:60-70`의 `to.path`가 `^zod$`. Z1 | +| P-07-07 | CHANGELOG 0.2.0 [계약] 행이 바뀌지 않은 레지스트리 분류기를 가리킨다 | **남음** | `CHANGELOG.md:45` 그대로 | +| F-07-03 | V2/V3 일치 테스트가 V2 행에서만 V3를 찾고, 빈 집합·스키마 id를 안 본다 | **남음 → 07-02에 합침** | `tests/unit/http-operation-v2-v3-parity.test.ts:31-54` 그대로. L1·L6이 이 빈틈을 실행으로 보였다. 같은 결함(API 이중 기술의 불일치 검출 부족)이라 07-02 하나로 센다 | +| F-07-07 | 폐기 별칭에 `no-deprecated` lint가 없다 | **남음 → 07-01에 합침** | `eslint.config.ts`에 `deprecat` 문자열 0건. `ApiFailure` 6개 소스 파일, `boundary-mapper`의 `MappingResult` 별칭 4개 파일 + `boundary-mapper.ts` 자신. 실행 API가 별칭을 요구한다는 새 증거와 같은 결함이라 07-01 하나로 센다 | + +지난 라운드 4절의 설계 선택 검토(레지스트리 게이트, zod facade, `ENV_REGISTRY`)는 코드가 그대로라 결론도 그대로다. 이번 문서에서는 반복하지 않는다. + +## 3. 이번 렌즈 — 기능 개발자가 HTTP API 하나를 추가한다 + +### 3.1 대표 흐름 + +참조 기능의 `GET_REFERENCE_RESOURCE`를 따라 "API 하나 추가"에 필요한 일을 적었다. + +```text +입력 백엔드가 GET /api/orders/{id} 를 제공한다 + → 스키마 zod DTO·요청 스키마 작성 reference-schemas.ts:5-69 + → 어댑터 zod → RuntimeValidator 변환 (참조 기능 안에만 있다, 07-03) reference-schemas.ts:88-119 + → 선언 [V2] defineRestOperation 행 26필드 (게이트가 보는 쪽) reference-feature-contract.ts:213-240 + [V2] SchemaDefinition 행 2~3개 (schemaId·direction·unknownFieldPolicy) :20-73 + [V2] RuntimeSchemaCodec 행 2~3개 reference-schemas.ts:124-146 + [V2] registry mapper 행 (V2 행의 mapperId 때문에 필요) reference-mapper.ts:108-127 + → 실행 [V3] InstalledHttpContract 22필드(projectRequest 포함) (실행되는 쪽) reference-feature-contract-contribution.ts:108-156 + [V3] source.kind = TEMPLATE_FIXTURE 또는 EXTERNAL_PACKAGE (07-04) :216-231 + → 매핑 typed mapper: DTO → domain, MappingResult(폐기 별칭) 반환 (07-01) reference-mapper.ts:24-50 + → 바인딩 feature-http-binding: mapSuccess / mapProblem → Result src/adapters/http/feature-http-binding.ts:86-98 + → 오류 도메인 해석: AppFailure → ReferenceError(AppError) — 실행 경로는 호출 안 함 (07-05) reference-error.ts:60-71 + 검사 import 시점: validateApiRuntimeBindings (V2 ↔ 스키마·mapper) installed-feature-contracts.ts:91 + 부팅 시점: composeContractContributions (V3 형식·상한) installed-contract-contributions.ts:15 + CI: check:registries (V2만), parity 테스트 (V2→V3 6필드) + 결과 V2와 V3가 어긋나도 6필드 밖이면 아무도 모른다 (L1, L3, L6) +``` + +문서 쪽 안내는 `starter-experience.md:114-120`의 한 문장("contract (… API operations, … schemas, runtime schemas, mappers) … and its contract contributions")이 전부다. 이 문장은 API operations(V2)와 contract contributions(V3)가 같은 API를 두 번 적는다는 것, 어느 쪽이 실행되는지, 제품은 `EXTERNAL_PACKAGE`여야 한다는 것, zod 어댑터를 어디서 얻는지를 말하지 않는다. 템플릿 자신의 "API 기능 추가" 증명 테스트도 V2 행만 쓰고 `contractContributions: []`다(`tests/unit/second-api-feature-registries.test.ts:20-111`). 그 API는 V3로 실행될 수 없는데 테스트는 통과한다. + +### 3.2 같은 사실의 사본과 불일치 검출 (39.5) + +`GET_REFERENCE_RESOURCE` 하나 기준이다. + +| 사실 | 사본 (이름) | 실제로 쓰는 곳 | 불일치 검출 | +|---|---|---|---| +| 메서드·경로 | V2 `method`·`path` / V3 `method`·`pathTemplate` | V3 | parity 테스트(V2 행이 있을 때만) | +| 성공 상태 | V2 `successStatuses` / V3 `acceptedStatuses` | V3 | parity | +| 응답 상한 | V2 `maxResponseBytes` / V3 `responseByteLimit` | V3 | parity | +| 인증 프로필 | V2 `auth` + `authProfileId` / V3 `authProfileId` | V3 | parity(`authProfileId`만) | +| 재전송 규칙 | V2 `idempotency`·`retry`·`replayPolicy`·`idempotencyKeyPolicy` / V3 `retrySemantics`·`retryBudget`·`traffic.maxRetries` / Browser RPC `replayPolicy` | V3 | parity는 `replayPolicy ↔ retrySemantics` 대응표 하나(`parity.test.ts:12-17`). V2 내부 4필드 정합은 일부만(`api-operations.ts:185-200`) | +| 시간 제한 | V2 `timeoutMs: null` / V3 `totalDeadlineMs: 10_000` | V3 | **없음**(L3) | +| 응답 스키마 id | V2 `responseSchema`, SchemaDefinition 키·`schemaId`, codec 키·인자, mapper `inputSchemaId`, `payloadSchemas` 키, V3 `zodValidator` 인자 — 8곳 | 실행은 V3 검증기 객체. V3 `schemaId`는 아무도 읽지 않는다(`assertValidator`가 빈 문자열만 막음, `external-contract-runtime.ts:306-318`) | V2 쪽끼리는 `validateApiRuntimeBindings`(`api-operations.ts:90-131`). V2 ↔ V3: **없음**(L1) | +| 응답 스키마 본문 | V2 codec용 `payloadSchemas.ReferenceResourceListPayload` / V3 `z.array(referenceResourceDtoSchema).max(100)` 별도 생성(`contribution.ts:63-66`) | V3 | 상한은 fan-out 테스트가 잡음(L2). 그 밖의 모양 차이는 없음 | +| 알 수 없는 필드 정책 | SchemaDefinition `unknownFieldPolicy: "STRIP_UNKNOWN"` / zod `.strip()` | zod | **없음.** `unknownFieldPolicy`·`direction`을 읽는 코드가 없다(grep: 선언 1곳뿐) | +| DTO 모양 | zod `referenceResourceDtoSchema` / 손으로 쓴 `isReferenceResourceDto`(`reference-mapper.ts:52-60`, 길이·datetime 검사 없음) | 타입 경로는 zod, registry mapper는 손 guard | 없음(이미 다르다) | +| operation 존재 | V2 키·`operationId` / V3 `operationId` / `mapReferenceOperation` 문자열 3개 | V3 | V3에만 있는 operation은 **검출 없음**(L6) | + +이 표의 사본 중 실행되는 것은 V3 열이다. 레지스트리 게이트가 보는 것은 V2 열이다. + +## 4. 새 발견 (36.3) + +### 4.1 발견 목록 + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 제목 | +|---|---|---|---|---|---| +| 07-02 | Medium | P2 | 확인된 결함 | 17, 3, 5, 21, 22, 23, 24, 10, 4 | HTTP API 하나를 V2 선언 행과 V3 실행 descriptor에 두 번 쓰고, 둘을 잇는 검사는 6필드뿐이다 (F-07-03 흡수) | +| 07-03 | Medium | P2 | 구조적 위험 | 17, 3, 5, 15, 22, 23, 27, 20 | zod 어댑터가 참조 기능 안에만 있어 복사되고, `RuntimeValidator`는 검증하지 않는 검증기를 구분하지 못한다 | +| 07-04 | Medium | P2 | 확인된 결함 | 17, 21, 5, 1, 18 | `TEMPLATE_FIXTURE`를 아무 기능이나 쓸 수 있고 그 API는 계약 집합에서 빠진다 | +| 07-01 | Low | P3 | 확인된 결함 | 24, 23, 4, 22, 9, 26 | `MappingResult` 이름 하나가 두 모양을 가리키고, "정본"은 쓰는 곳이 없으며, 실행 API는 폐기 별칭을 요구한다 (F-07-07 흡수) | +| 07-05 | Low | P3 | 구조적 위험 | 24, 23, 4, 22 | 오류 어휘 둘(`AppFailure`·`AppError`)과 "retry" 세 이름의 관계가 타입·주석에 없다 | +| 07-06 | Low | P3 | 확인된 결함 | 10, 21, 5, 1 | 조립기·선언 검증의 쓰기 API 규칙 5개가 테스트 없이 남아 있다 | +| 07-07 | Low | P3 | 구조적 위험 | 5, 24, 17, 6 | `commandRecovery`를 실행기가 읽지 않고, 결과 불명 쓰기의 수습 책임이 타입 옆에 없다 | + +High 이상 발견은 없다. 지난 라운드에서 남은 P-07-01~04(Medium·P2), P-07-05~07(Low·P3)은 2절에 있다. + +### 4.2 발견 상세 + +### 07-01 `MappingResult`라는 이름이 두 모양을 가리키고, "정본"으로 적힌 모양은 쓰는 곳이 없으며, 실행 API는 폐기 별칭을 요구한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (기록된 의도와 실제 사용이 반대) | +| 관련 관점 | 24, 23, 4, 22, 9, 26 | +| 근거 | `external-contract-runtime.ts:42-46`은 "validator protocol and `MappingResult` below are the canonical shapes"라고 적고 `{ ok:false, error:{ kind, code } }` 모양을 둔다(`:100-105`). `boundary-mapper.ts:9-24`은 `{ ok:false, code }` 모양을 `BoundaryMappingResult`로 이름 붙이고 같은 이름 `MappingResult`를 `@deprecated` 별칭으로 남긴다. **사용처(grep):** 정본 `MappingResult`·`toContractMappingResult`·`mappingViolation`은 `tests/unit/boundary-mapper.test.ts`만 쓴다. 새 이름 `BoundaryMappingResult`는 자기 파일 밖 사용처 0. 폐기 별칭은 실행 경로가 쓴다: `FeatureHttpOperationSpec.mapSuccess`의 반환 타입(`src/adapters/http/feature-http-binding.ts:5, 91-93`), `client.ts:48`, `resource-mapper.ts`, 참조 mapper(`reference-mapper.ts:9`). `boundary-mapper.ts` 자신도 `map`(`:47`)·`mappingSuccess`(`:95`)·`mappingFailure`(`:99`)의 반환 타입에 별칭을 쓴다. 제거 조건은 "no module imports `MappingResult` from this file"(`:20-22`)인데 실행 API가 그 import를 요구한다. `ApiFailure` 별칭도 6개 소스 파일이 쓴다(참조 기능 2개 포함, 참조 README 27행은 폐기 표시 없이 "같은 type의 alias"라고 소개). `eslint.config.ts`에 폐기 검사 규칙이 없다. **결과 모양 수:** 기능 개발자가 API 하나에서 만나는 성공/실패 모양은 `Result`(`ok/value/error`), 매퍼 결과 2종(`ok/code`, `ok/error`), `RuntimeValidationResult`(`success/data/issues`, 경로 배열), `RuntimeSchemaResult`(`success`, 경로 문자열), `ValidatorInvocation`(`outcome`) 6종이다 | +| 발생 조건 | 새 기능 mapper를 쓰면서 주석을 따라 "정본" `MappingResult`를 import하거나, IDE 자동 import가 다른 파일의 같은 이름을 고를 때 | +| 영향 | 모양이 달라 `mapSuccess`에서 컴파일 오류가 난다. 런타임 피해는 없다. 대신 개발자는 D-15 이력(커밋 `56de543d` 메시지에만 있음)을 찾아 읽어야 어느 쪽을 쓸지 안다. IDE는 참조 기능과 바인딩이 쓰는 이름에 취소선을 긋는다. 폐기 별칭은 제거 조건이 충족될 수 없어 계속 남는다 | +| 심각도·우선순위 | Low · P3 — 컴파일러가 잘못된 조합을 막는다. 대표 과제마다 이해 비용을 반복해서 만들지만 계약 위반은 아니다 | +| 통제·증거 | 목표 M4(이름 하나에 모양 하나) / 확인 M4(잘못된 모양은 컴파일 실패) · 의도 표현 M1(주석이 실제와 반대) · E1(grep) | +| 확실성과 남은 가정 | 사용처는 grep으로 확인했다. 다운스트림 tech-log도 `mappingSuccess`(별칭 반환)를 쓴다(`tech-log-http-binding.ts:9, 112`) | +| 결정의 근거 | 기록된 결정: D-15는 `external-contract-runtime.ts`의 모양을 정본으로 정했다(커밋 `56de543d`). 확인한 사실: 그 뒤 실행 API와 helper는 바뀌지 않아 정본에 소비자가 없다. 리뷰어 추론: "정본"은 "실행 경로가 쓰는 모양"이어야 개발자가 따라갈 수 있다 | +| 이해 비용 | 기능 개발자가 mapper 하나를 쓰려면 `boundary-mapper.ts`, `external-contract-runtime.ts`, `feature-http-binding.ts` 세 파일의 주석과 타입을 대조해야 한다 | +| 최소 개선 방향 | (1) `mapSuccess`와 `boundary-mapper.ts`의 helper 반환 타입을 `BoundaryMappingResult`로 바꾼다. (2) 별칭 사용 4파일(`MappingResult`)·6파일(`ApiFailure`)을 옮기고 별칭을 지운다. (3) 정본 쪽 이름을 `ContractMappingResult`로 바꿔 같은 이름을 없앤다. (4) D-15 주석을 "기능 mapper는 `BoundaryMappingResult`를 반환하고, 계약 패키지 쪽 결과가 필요하면 `toContractMappingResult`로 바꾼다"로 고친다 | +| 대안 비교 | 5.2절. (A) 현 상태 + `no-deprecated` lint만 켬: 바인딩 파일이 즉시 lint 실패라 결국 (B)와 같은 이행이 필요하다. (B) 위 개선: 타입 이름만 바뀌고 런타임 변화 없음. (C) 바인딩이 정본 모양을 받게 바꿈: 실패 코드가 닫힌 3종(`MappingFailureCode`)에서 자유 문자열로 넓어져 오히려 계약이 약해진다 | +| 단순화의 보존 조건 | 매퍼 실패 코드는 `MAPPING_INVARIANT_REJECTED`·`UNSUPPORTED_WIRE_VALUE`·`OUTPUT_LIMIT_EXCEEDED` 닫힌 집합으로 남는다. 바인딩은 매퍼 실패를 `MAPPING_CONTRACT_VIOLATION`으로 정규화한다. 매퍼 예외는 실패 결과로 바뀐다(`boundary-mapper.ts:84-93`) | +| 비용·부작용 | 타입 이름 교체 10여 파일. 다운스트림은 동기화 때 import 이름만 바꾼다(CHANGELOG [계약] 행 필요) | +| 재검토 조건 | 외부 계약 패키지가 mapper를 함께 배포해 정본 모양을 직접 반환하게 되면 (C)를 다시 본다 | +| 완료 기준 | `MappingResult`라는 이름의 export가 하나다. `grep -rw "ApiFailure\|BoundaryMappingResult as MappingResult" src`가 0건이다. 폐기 검사 lint가 켜져 있다 | +| 검증 방법 | `check:types`, `lint`(폐기 규칙 포함), `tests/unit/boundary-mapper.test.ts` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 07-02 HTTP API 하나를 선언 사본(V2 행)과 실행 사본(V3 descriptor)에 두 번 쓰고, 둘을 잇는 검사는 6개 필드뿐이다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (같은 사실의 두 사본, 불일치 검출 부족, 실행으로 재현) | +| 관련 관점 | 17, 3, 5, 21, 22, 23, 24, 10, 4, 39.5 | +| 근거 | **두 사본:** V2 `RestOperationV2`(`src/contracts/api-operations.ts:1-51`)와 V3 `InstalledHttpContract`(`external-contract-runtime.ts:168-190`). 같은 사실을 다른 이름으로 적는다(3.2절 표). V2 행은 실행되지 않는다: 부팅 코드는 V2 클라이언트에 설치된 행을 넘기지 않는다(`src/bootstrap/runtime-adapters.ts:74-93`의 주석과 `:191-211`). V2 행은 `check:registries`(FE-REG-API, `registry-governance.json:143-208`), import 시점 바인딩 검사(`installed-feature-contracts.ts:91-96`), realtime snapshot 바인딩(`realtime-streams.ts:464-475`)이 읽는다. V3 행은 실행되지만 어떤 기준선에도 없다. "V2는 governance용, V3는 실행용"이라는 사실은 parity 테스트 주석에만 있다(`parity.test.ts:10-11`). `api-operations.ts`에는 이 설명이 없다. **V2가 강요하는 추가 사본:** V2 행의 `mapperId` 때문에 registry mapper(`reference-mapper.ts:108-127`)를 써야 한다. 이 mapper는 zod 대신 손으로 쓴 guard(`:52-60`)를 쓴다. 실행 경로는 typed mapper(`:24-50`)를 쓴다. `SchemaDefinition.unknownFieldPolicy`·`direction`(`schema-registry.ts:15-16`)은 읽는 코드가 없다. L7: 응답 DTO를 `.strict()`로 바꿔도(선언은 그대로 `STRIP_UNKNOWN`) 관련 테스트 686건이 통과했다. 그러면 백엔드가 응답에 필드 하나만 더해도 프론트가 `SCHEMA_MISMATCH`로 실패하는데, `docs/contracts/compatibility.md:28`은 이 경계를 "additive"라고 적는다. **불일치 검출:** parity 테스트는 V2 행에서 V3를 찾는 한 방향이고(`parity.test.ts:32-54`), 6필드만 비교하며, V2 행이 0개여도 통과한다. **실험:** L1(V3 `schemaId` 변경) 통과, L3(V3 deadline 6배) 통과, L6(V3에만 새 API 추가) `tsc`·29파일·`check:registries` 모두 통과. 템플릿의 "API 기능 추가" 증명 테스트는 V2 행만 쓰고 V3는 없다(`second-api-feature-registries.test.ts:40-69, 110`) | +| 발생 조건 | 기능 개발자가 (a) V3만 쓴다 — 실행은 되지만 공개 경로·메서드가 레지스트리 게이트 밖이다. (b) V2만 쓴다 — 게이트는 통과하지만 API가 실행되지 않는다. (c) 둘 다 쓰고 나중에 한쪽만 고친다 — 6필드 밖 차이는 검출되지 않는다 | +| 영향 | (a) 공개 API 경로를 바꿔도 breaking 증거 요구가 생기지 않는다(FE-REG-API의 약속이 실행 API에 적용되지 않음). (b) 화면에서 처음 호출할 때 `Unregistered` 류 실패로 드러난다. (c) 레지스트리 스냅샷이 실제와 다른 값(`timeoutMs: null`, 다른 스키마 id)을 공개 계약으로 기록한다. 리뷰어는 스냅샷을 믿을 수 없다 | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없다. 템플릿 대표 과제(API 추가)에서 매번 두 사본을 맞춰야 하고, 게이트가 실행 API를 보지 않는 빈틈이 실행으로 확인됐다. 참조 기능이 이 구조를 그대로 복제하게 한다 | +| 통제·증거 | 목표 M3(실행 API가 게이트 대상이거나, 두 사본의 전체 대조) / 확인 M3(부분: 6필드, 한 방향) · E2(L1, L3, L6, `tsc`, 29파일) | +| 확실성과 남은 가정 | 실행으로 확인했다. 다운스트림 tech-log는 V2 행을 쓰지 않는다(`defineRestOperation` grep 0). 그래서 tech-log의 실행 API는 FE-REG-API 밖이다(추론: 그 제품 레지스트리 스냅샷에 HTTP API가 없다. 직접 실행은 안 함) | +| 결정의 근거 | 기록된 의도: "Until V2 is generated from V3, both copies must agree"(`parity.test.ts:10-11`). 즉 이중 기술은 이행 중 상태로 기록돼 있다. 확인한 사실: 생성기는 없고 일치 검사는 6필드다. 리뷰어 추론: 실행 사본이 게이트 밖에 있는 한 "공개 계약 변경을 리뷰에서 식별한다"(가이드 17절)는 목표를 V3 API에 대해 지키지 못한다 | +| 이해 비용 | API 하나에 7곳(V2 행, SchemaDefinition, codec, registry mapper, V3 행, typed mapper, 바인딩)을 맞춘다. 같은 개념의 이름이 V2·V3·Browser RPC에서 다르다(재전송 규칙만 세 이름 체계) | +| 최소 개선 방향 | 1단계(작음): (1) `api-operations.ts` 머리 주석과 `starter-experience.md` "Adding a feature"에 "V2 행은 레지스트리 게이트용 선언이고 실행은 V3 descriptor다. 둘 다 쓴다"를 적는다. (2) parity 테스트를 양방향으로 바꾸고, V2 `requestSchema`·`responseSchema`·`pathSchema` ↔ V3 검증기 `schemaId`, V2 행 수 > 0을 단언한다. (3) 두 번째 기능 테스트에 V3 기여(EXTERNAL_PACKAGE 픽스처)를 넣는다. 2단계(구조): FE-REG-API 스냅샷을 V3 descriptor에서 투영하고 V2 행을 없앤다(5.1절 D) | +| 대안 비교 | 5.1절 | +| 단순화의 보존 조건 | FE-REG-API 스냅샷의 필드와 breaking 판정(`method`, `path`, `operationId`, `requestSchema`, `responseSchema` 등)이 유지된다. realtime snapshot 바인딩이 "REST·QUERY·SAFE/IDEMPOTENT" 조건을 계속 검사한다. 스키마 id ↔ 스키마 레지스트리 ↔ mapper 결합 검사(`validateApiRuntimeBindings`)가 V3 기준으로 남는다 | +| 비용·부작용 | 1단계: 테스트 수십 줄, 문서 몇 줄. 2단계: 투영 함수, FE-REG-API 기준선 재승인 1회, 다운스트림 동기화 때 V2 행 삭제 | +| 재검토 조건 | V2 전송 경로를 실제로 쓰는 제품이 생기면 V2 행은 실행 사본이 되므로 이중 기술 대신 "V2/V3 중 하나만 설치" 규칙을 다시 비교한다 | +| 완료 기준 | L1과 L6을 다시 하면 실패한다. V2 행 없이 V3만 있는 API, V3 없이 V2만 있는 API가 각각 실패한다 | +| 검증 방법 | L1·L6 재실행, 확장한 parity 테스트, `second-api-feature-registries.test.ts` | +| 담당·기한·상태 | 미정 · 미정 · 신규 (F-07-03 흡수) | + +### 07-03 zod를 검증기로 바꾸는 어댑터가 참조 기능 안에만 있어 기능마다 복사되고, `RuntimeValidator`는 검증하지 않는 검증기를 구분하지 못한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (갈라진 복사본 확인, 다운스트림에서 검증 생략 관찰) | +| 관련 관점 | 17, 3, 5, 15, 22, 23, 27, 20, 39.5 | +| 근거 | **위치:** `zodValidator`는 `src/features/reference-feature/contracts/reference-schemas.ts:88-119`에만 있다. 주석은 "The one zod wrapper"라고 부른다(`:83-87`). `src/contracts/`에는 zod를 `RuntimeValidator`로 바꾸는 함수가 없다. 아키텍처 규칙 `features-do-not-import-other-features`(`.dependency-cruiser.json:266`) 때문에 두 번째 기능은 이를 import할 수 없다. 참조 기능을 지우면(`test:sample-removal`) 어댑터도 사라진다. **복사본:** `tests/helpers/external-contract-fixture.ts:10-38`은 `structuredClone`을 뺀 복사본이다. tech-log는 `tech-log-studio-contract-contribution.ts:20-44`에 복사했다. **검증 생략:** tech-log는 복사한 어댑터로 `passthrough = zodValidator(schemaId, z.unknown() as unknown as z.ZodType)`를 만들고(`:52-53`), 출력 검증기 5개 정의 모두 envelope 뼈대만 보고 payload는 `z.unknown()`으로 통과시킨다(`envelopeData`, `:62-78`). 입력 검증기 5개도 모두 통과 검증기다. 주석은 "런타임 재검증은 계약 갱신 때마다 두 곳을 고치게 만든다"고 이유를 적는다(`:48-51`). 템플릿 자신의 두 번째 API 기능 테스트도 통과 검증기를 쓴다(`second-api-feature-registries.test.ts:30-34`). **구분 불가:** `RuntimeValidator`는 `schemaId`와 `safeParse`만 요구한다(`external-contract-runtime.ts:56-59`). 조립기는 `schemaId`가 비어 있지 않은지만 본다(`:306-318`). L5: 통과 검증기가 조립되고 `invokeValidator`가 `VALID`를 돌려줬다 | +| 발생 조건 | 새 기능이 HTTP API를 추가할 때(어댑터 복사). 생성된 타입을 가진 제품이 zod 스키마를 따로 쓰기 싫을 때(검증 생략) | +| 영향 | 복사본마다 규칙이 갈라진다(`structuredClone` 유무, 경로 변환). 검증을 생략한 API는 백엔드가 다른 모양을 보내도 `SCHEMA_MISMATCH`가 나지 않고, 잘못된 값이 `T` 타입으로 mapper까지 간다. mapper가 던지면 `MAPPING_INVARIANT_REJECTED`, 던지지 않으면 화면에 틀린 값이 나온다. 타입·이름·조립 결과 어디에도 "이 API는 런타임 검증을 안 한다"가 남지 않는다 | +| 심각도·우선순위 | Medium · P2 — 보안 경계 우회는 아니다(제품 자신의 백엔드 응답이다). 그러나 가이드 17절의 위험 신호("생성된 타입만 믿고 신뢰 경계의 런타임 입력을 검증하지 않는다")가 실제 다운스트림에서 나타났고, 템플릿 인터페이스에서는 보이지 않는다 | +| 통제·증거 | 목표 M2(공유 어댑터 + 검증 생략의 명시) / 확인 M0(공유 어댑터 없음, 생략 표시 수단 없음) · E1 · E2(L5) · E3(tech-log grep) | +| 확실성과 남은 가정 | 복사본과 통과 검증기는 코드로 확인했다. tech-log에서 실제로 잘못된 payload가 들어온 사례는 찾지 않았다 | +| 결정의 근거 | 확인한 사실: 검증기 프로토콜을 zod와 분리한 것은 외부 계약 패키지가 자기 검증기를 넣을 수 있게 하려는 것이다(`external-contract-runtime.ts:1-8`). 그 선택은 유지할 근거가 있다(5.3절). 리뷰어 추론: 분리는 "zod 어댑터를 기능이 만든다"까지 요구하지 않는다. 공유 어댑터는 `src/contracts/zod.ts` 옆이 자연스럽다(그 파일이 jitless 설정 때문에 이미 유일한 zod 입구다) | +| 이해 비용 | 새 기능 작성자는 참조 기능에서 어댑터를 찾아 복사하고, 왜 `structuredClone`이 있는지, 경로를 왜 배열로 두는지 스스로 판단해야 한다 | +| 최소 개선 방향 | (1) `zodValidator`를 `src/contracts/zod-validator.ts`로 옮기고 참조 기능·`tests/helpers`가 그것을 쓴다. (2) 검증을 일부러 생략하는 길을 이름으로 만든다: 예 `unvalidatedPayload(schemaId, reason)` — `RuntimeValidator`에 `validation: "NONE"` 표시를 붙이고, 조립 결과(`ComposedContractContributions`)와 플랫폼 개요 화면이 그런 operation 목록을 보여 준다 | +| 대안 비교 | 5.3절. (A) 현 상태. (B) 공유 어댑터만: 복사본 문제는 사라지고 검증 생략은 여전히 안 보인다. (C) (B) + 생략 표시: 생략은 막지 않지만 코드와 화면에 남는다. (D) 브랜드 타입으로 `zodValidator`가 만든 검증기만 받기: 외부 패키지의 자체 검증기까지 막아 §4 설계와 충돌한다 | +| 단순화의 보존 조건 | 검증기 호출은 계속 `invokeValidator`를 거쳐 예외가 `THROWN`이 된다. 성공 값은 복사본이다(`structuredClone`). 실패 경로는 `path` 배열·`code` 문자열이다. zod는 `src/contracts/zod.ts`를 통해서만 들어온다 | +| 비용·부작용 | 파일 1개 이동, import 3곳. (C)는 타입 필드 1개와 화면 목록 1개 | +| 재검토 조건 | 외부 계약 패키지가 표준 검증기(예: 생성된 zod 스키마)를 함께 배포하면 공유 어댑터는 그 패키지 쪽으로 옮긴다 | +| 완료 기준 | zod 스키마를 `RuntimeValidator`로 바꾸는 함수가 `src/contracts/` 한 곳에만 있고 참조 기능·`tests/helpers`가 그것을 import한다. 참조 기능을 지워도 어댑터가 남는다. 통과 검증기를 쓰는 operation이 조립 결과에서 목록으로 나온다 | +| 검증 방법 | `test:sample-removal` 뒤 어댑터 존재 확인, L5 재실행으로 표시 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 07-04 `TEMPLATE_FIXTURE` 출처를 아무 기능이나 쓸 수 있고, 그 기능의 API는 릴리스 계약 집합에서 조용히 빠진다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (설계 계약 미구현, 실행으로 재현) | +| 관련 관점 | 17, 21, 5, 1, 18, 30.3 | +| 근거 | 설계서는 fixture 규칙을 `featureId = reference-feature`로 정하고 "product feature는 반드시 `EXTERNAL_PACKAGE`다"라고 적는다(`docs/architecture/2026-07-30-…-closed-deep-design.md:736-746`). 같은 문서 §24.5는 정적 검사가 "product TEMPLATE_FIXTURE"를 거부해야 한다고 적는다(`:5227-5241`). 코드: 조립기의 fixture 분기는 `fixtureId`·`revision`·이벤트 0개만 본다(`external-contract-runtime.ts:777-800`). `featureId`와 fixture 기여 수는 보지 않는다. `scripts/`와 `.dependency-cruiser.json`에 `TEMPLATE_FIXTURE` 검사가 없다(grep: `generate-contract-set.ts` 주석과 scale 스크립트뿐). 계약 집합은 `EXTERNAL_PACKAGE`만 모은다(`installed-contract-contributions.ts:19-20`, `scripts/generate-contract-set.ts:13-17`). 참조 기여 파일의 안내는 주석 한 줄이다("A product feature MUST instead pin an external package", `reference-feature-contract-contribution.ts:22-25`). 기존 테스트도 `featureId: "test-feature"`인 fixture를 조립한다(`tests/unit/contract-snapshot-bypass.test.ts:66-78`). **L4:** 참조 계약 행을 복사한 `order` 기능 기여가 조립됐고 `externalPackages`는 0개였다 | +| 발생 조건 | 제품 기능 작성자가 참조 기능의 기여 파일을 복사해 operation id와 경로만 바꿀 때. 계약 패키지가 아직 없어서 "일단 fixture로" 시작할 때 | +| 영향 | 그 API는 실행된다. 그러나 부팅 때 `verifyContractSet`(`src/contracts/contract-set.ts:64-136`)가 비교할 패키지 identity가 없다. 프론트가 빌드된 계약 버전과 배포된 백엔드 계약 버전이 달라도 릴리스 정합 검사가 이 API를 보지 않는다. 경고나 실패가 없어서 언제 빠졌는지도 모른다 | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 직접 없다. 그러나 릴리스 정합(계약 집합)이라는 템플릿의 핵심 보호가 복사 한 번으로 조용히 꺼진다. 확인한 다운스트림(tech-log)은 `EXTERNAL_PACKAGE`를 써서 아직 발생하지 않았다 | +| 통제·증거 | 목표 M4(조립 경계에서 거부) / 확인 M1(설계서와 주석만) · E2(L4) | +| 확실성과 남은 가정 | 실행으로 확인했다. 제품 빌드에서 fixture 기여를 막아야 하는지(참조 기능은 기본 제품에 설치돼 있다)는 설계서 §4.8의 규칙(`featureId = reference-feature`)으로 충분하다고 봤다 | +| 결정의 근거 | 적용 제외 — 기대 계약이 설계서에 이미 정해져 있다. 구현만 빠졌다 | +| 이해 비용 | 적음. 다만 지금은 이 규칙을 5,000행 설계서와 주석 한 줄에서만 찾을 수 있다(`starter-experience.md`에 없음) | +| 최소 개선 방향 | 조립기 fixture 분기에 `featureId !== "reference-feature"`이면 실패를 추가한다. fixture 기여가 둘 이상이면 실패한다. `contract-snapshot-bypass.test.ts`의 fixture 행은 `featureId: "reference-feature"`로 고친다. `starter-experience.md` "Adding a feature"에 "API 기여는 `EXTERNAL_PACKAGE`"를 한 줄 적는다 | +| 대안 비교 | 적용 제외 — 계약이 정해져 있다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 조건 2줄, 테스트 1건 수정, 문서 1줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | L4가 `ContractContributionError`로 실패한다 | +| 검증 방법 | L4 재실행, `tests/unit/external-contract-runtime.test.ts`에 "다른 featureId의 fixture 거부" 사례 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 07-05 오류 어휘가 둘이고(`AppFailure`·`AppError`), "다시 시도"를 세 이름으로 적는데 관계가 타입·주석에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (이해 비용, 숨은 규칙) | +| 관련 관점 | 24, 23, 4, 22 | +| 근거 | `AppFailure`(`src/contracts/errors.ts:120-135`)는 닫힌 `kind` 38종, `retryable: boolean`, `action: ErrorAction`을 가진다. `AppError`(`src/platform/errors/app-error.ts:21-26`)는 열린 `kind`(`owner.reason`), `retryability: "never"|"safe"|"policy"`, `severity`, `category`를 가진다. `errors.ts:16-21`은 severity를 "읽는 곳이 없어서" 지웠다고 적는데 `AppError`에는 남아 있다. 참조 기능은 둘 다 보여 준다: gateway는 `Result`를 반환하고(`reference-feature-api.ts:29`), `reference-error.ts`는 `AppFailure`를 `ReferenceError`(`AppError`)로 바꾼다(`:60-71`). `toReferenceError`의 호출처는 테스트뿐이다. `platformErrorForOutcome`도 배럴 export 외 호출처가 없다(`src/adapters/http/index.ts:23`). **같은 이름, 다른 뜻:** `retryable`은 런타임 자동 재시도 허용이다(어댑터가 읽음). `action: "retry"`는 사용자에게 다시 시도 버튼을 보여 준다(`async-surface.tsx:161`, `use-app-form.ts:233`). 그래서 `CONFLICT`·`QUERY_CACHE_FAILURE`·`IDENTITY_INTERN_LIMIT_EXCEEDED`는 `defaultRetryable: false`이면서 `action: "retry"`다(`errors.ts:57-61, 76, 102`). `ErrorDefinition` 주석은 이 차이를 설명하지 않는다 | +| 발생 조건 | 기능 작성자가 도메인 오류를 정의하거나, 오류를 "재시도하지 말라"로 표시하려 할 때 | +| 영향 | `AppError.retryability: "never"`를 붙여도 HTTP 재시도 동작은 바뀌지 않는다(런타임은 `AppFailure.retryable`과 operation 재시도 정책만 읽는다). `retryable: false, action: "retry"`를 보고 모순으로 읽어 "고치는" 변경이 나올 수 있다. 피해는 동작 오해에 그친다 | +| 심각도·우선순위 | Low · P3 — 실행 동작은 일관된다. 이해 비용과 잘못된 수정 가능성만 남는다 | +| 통제·증거 | 목표 M1(두 어휘의 관계와 두 "retry"의 뜻이 타입 주석에 있음) / 확인 M0 · E1(grep) | +| 확실성과 남은 가정 | 호출처는 grep으로 확인했다. `AppError`는 이 repo 전제상 다운스트림 확장 지점이라 죽은 코드로 보지 않는다. tech-log는 `AppError`를 쓰지 않는다 | +| 결정의 근거 | 확인한 사실: `AppError` 주석(`app-error.ts:1-8`)은 "새 기능이 중앙 오류 타입을 고치지 않게" 하려는 의도를 적는다. `AppFailure`는 반대로 닫힌 집합이다(`errors.ts:106-111`). 두 의도는 각각 타당하다. 리뷰어 추론: 빠진 것은 "어느 경계에서 어느 것을 쓰는가" 한 문단이다 | +| 이해 비용 | 기능 작성자가 오류 하나를 다루려면 두 파일과 `platform-error-mapping.ts`를 읽어야 관계를 짐작할 수 있다 | +| 최소 개선 방향 | (1) `errors.ts`의 `AppFailure` 위에 "application 입력 경계를 넘는 실패는 `AppFailure`다. `AppError`는 기능 안의 도메인 해석용이며 런타임 재시도에 영향이 없다" 두 줄. (2) `retryable` 필드에 "런타임 자동 재시도 허용. 사용자 버튼은 `action`" 한 줄. 이름을 `autoRetryable`로 바꾸는 것은 비용 대비 효과가 작아 제안하지 않는다 | +| 대안 비교 | (A) 현 상태. (B) 위 주석: 비용 거의 없음. (C) 두 어휘를 하나로 합침: `AppFailure`의 닫힌 집합과 `AppError`의 열린 집합은 목적이 달라 합치면 한쪽 보호를 잃는다 | +| 단순화의 보존 조건 | 적용 제외 — 주석만 추가한다 | +| 비용·부작용 | 주석 몇 줄 | +| 재검토 조건 | `AppError`를 실행 경로가 읽기 시작하면(예: 텔레메트리 분류) 두 어휘의 변환 함수를 공식 경계로 정한다 | +| 완료 기준 | `AppFailure`·`retryable`·`action` 정의 옆에서 두 어휘와 두 "retry"의 차이를 읽을 수 있다 | +| 검증 방법 | 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 (`AppError` 쪽은 영역 09) | + +### 07-06 조립기·선언 검증의 쓰기 API 규칙 5개가 테스트 없이 남아 있다 — 지워도 관련 테스트 686건이 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 (테스트 공백, 변이로 재현) | +| 관련 관점 | 10, 21, 5, 1 | +| 근거 | 변이 MX1·MX2·MX5·MX6·MX9가 살아남았다(4.3절 표). 지운 규칙: 읽기 operation의 command descriptor 금지(`external-contract-runtime.ts:469-472`), `KEYED`의 복구 descriptor 필수(`:492-494`), `NEVER`와 재시도 예산의 모순 거부(`:508-513`), V2 `KEYED_COMMAND`의 `idempotencyKeyPolicy: "REQUIRED"` 정합(`api-operations.ts:193-195`), mapper 레지스트리 키 = `mapperId`(`boundary-mapper.ts:59`). 실행기는 operation이 쓰기인지 메서드가 아니라 `commandEffect !== null`로 정한다(`src/adapters/http/http-execution-v3.ts:386, 479, 1164`). 그래서 MX1이 지운 규칙은 "GET이 쓰기로 처리되는 것"을 막는 유일한 경계다. 조립기 테스트(`tests/unit/external-contract-runtime.test.ts`)는 출처·중복·메서드 어휘·검증기 프로토콜만 본다 | +| 발생 조건 | 조립기를 고칠 때(이 파일은 NS-02, LIVE-03, Q-6.7 등으로 여러 번 다시 쓰였다) 규칙 줄이 빠지는 경우 | +| 영향 | 규칙이 사라져도 CI가 모른다. 기능 작성자는 조립 오류 메시지로 쓰기 API 규칙을 배우는데(예: `KEYED commands require a recovery descriptor`), 그 안내가 조용히 없어진다. `NEVER` 재시도는 실행기가 한 번 더 막는다(`src/adapters/http/http-retry-lifecycle.ts:21-30`). 나머지 넷은 다른 방어가 없다 | +| 심각도·우선순위 | Low · P3 — 지금 코드는 맞다. 회귀를 잡지 못하는 위험이다 | +| 통제·증거 | 목표 M3 / 확인 M2(구현만, 검출 없음) · E2(MX1·MX2·MX5·MX6·MX9) | +| 확실성과 남은 가정 | 76개 관련 테스트 파일(`tools07/U2.txt`)로 돌렸다. 그 밖의 테스트(e2e, system, scale)는 돌리지 않았다. 이 규칙들이 그쪽에서 잡힐 가능성은 낮다고 봤다(조립 단위 규칙) | +| 결정의 근거 | 적용 제외 — 규칙은 이미 정해져 있고 테스트만 빠졌다 | +| 이해 비용 | 적음 | +| 최소 개선 방향 | `external-contract-runtime.test.ts`에 사례 4개(GET + commandEffect, KEYED + recovery 없음, NEVER + retryBudget 1, 정상 대조군), `boundary-mapper.test.ts`에 키 ≠ `mapperId` 1개, V2 정합 1개 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 사례 6개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | MX1·MX2·MX5·MX6·MX9가 모두 죽는다 | +| 검증 방법 | 4.3절 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 07-07 `commandRecovery`는 `KEYED` 쓰기에 필수지만 실행기는 읽지 않고, 결과 불명 쓰기를 누가 수습하는지 타입 옆에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 (위험 가시성) | +| 관련 관점 | 5, 24, 17, 6 | +| 근거 | `CommandRecoveryDescriptor`(`external-contract-runtime.ts:117-121`)는 `mode: "IDEMPOTENCY_REPLAY" | "INSPECT_OPERATION"`, `operationIdentityField`, `inspectOperationId`를 가진다. 주석이 없다. 조립기는 `KEYED`에 이를 요구한다(`:492-494`). 실행기(`http-execution-v3.ts`)에는 `commandRecovery`를 읽는 줄이 없다(grep). `src/` 전체에서 읽는 곳은 플랫폼 개요 화면의 표시뿐이다(`platform-overview-page.tsx:272-274`). 설계서는 "feature gateway가 package의 inspect operation을 application-safe outcome으로 mapping한다"고 적는다(`closed-deep-design.md:644-654`). 참조 기능은 `IDEMPOTENCY_REPLAY`를 선언하지만(`reference-feature-contract-contribution.ts:177-180`) gateway는 그 정보를 쓰지 않는다(`reference-http-gateway.ts:72-74`). 결과 불명 쓰기는 `MAYBE_APPLIED`로 `retryable=false`, `action: "contact-support"`가 된다(`errors.ts:166-170, 189-191`) — 실행은 안전하게 멈춘다 | +| 발생 조건 | 기능 작성자가 `mode: "INSPECT_OPERATION"`을 선언하고 런타임이 응답을 잃은 쓰기를 조회해 줄 것이라고 기대할 때 | +| 영향 | 결과 불명 쓰기가 사용자에게 "지원팀 문의"로만 끝난다. 제품이 수습 흐름을 만들어야 한다는 사실을 설계서 644행에서만 알 수 있다. 데이터 피해는 없다(실행은 fail-safe) | +| 심각도·우선순위 | Low · P3 — 동작은 안전하다. 책임 경계가 이름과 다르게 읽힌다 | +| 통제·증거 | 목표 M1(타입 옆에 "실행기는 읽지 않는다. 수습은 기능 gateway") / 확인 M0(설계서에만 있음) · E1(grep) | +| 확실성과 남은 가정 | 읽는 곳은 grep으로 확인했다. 오프라인 명령 큐(선택 안 됨)가 이 descriptor를 큐 자격 조건으로 쓸 계획이다(`closed-deep-design.md:3895-3903`). 이 repo 전제상 확장 지점이라 죽은 코드로 보지 않는다 | +| 결정의 근거 | 기록된 의도: 프론트는 서버 의미를 새로 만들지 않고 패키지가 준 recovery capability를 소비한다(`closed-deep-design.md:622`). 그 결정은 타당하다. 빠진 것은 그 결정을 타입 옆에 남기는 것이다 | +| 이해 비용 | 결과 불명 쓰기를 다루려면 5,000행 설계서 4.4절을 찾아 읽어야 한다 | +| 최소 개선 방향 | `CommandRecoveryDescriptor` 위에 세 줄: "HTTP 실행기는 이 값을 읽지 않는다. `MAYBE_APPLIED`가 되면 기능 gateway가 이 descriptor로 조회·재전송을 결정한다. 오프라인 큐의 자격 조건이기도 하다." 참조 기능 README에 결과 불명 쓰기를 어디서 처리하는지 한 줄 | +| 대안 비교 | (A) 현 상태. (B) 위 주석: 비용 거의 없음. (C) 실행기가 `IDEMPOTENCY_REPLAY`면 같은 키로 한 번 재조회: 서버 멱등 계약을 프론트가 가정하게 되어 설계서 결정(§4.4)과 충돌한다 | +| 단순화의 보존 조건 | 적용 제외 — 주석만 추가한다 | +| 비용·부작용 | 주석 몇 줄 | +| 재검토 조건 | 템플릿이 결과 불명 쓰기의 수습 흐름(조회 operation 호출)을 기본 제공하게 되면 실행기와 descriptor를 연결한다 | +| 완료 기준 | descriptor 정의 옆에서 "누가 읽는가"를 알 수 있다 | +| 검증 방법 | 리뷰 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 4.3 변이 실험 결과 (테스트 렌즈) + +worktree에서 변이 하나씩 넣고, 이 영역 모듈을 import하는 테스트 76파일(686건, `tests/unit`·`component`·`integration`·`features`·`platform`·`contract`·`runtime-schema` 중 관련 파일)을 돌렸다. 변이 전 기준은 686/686 통과. 부하 11~21, 한 번에 약 10초. + +처음에는 위 7개 폴더 전체(2,879건)를 돌렸는데 변이 없이도 79건이 실패했다(부하 21에서의 시간 초과로 보임, 원인은 조사하지 않음). 그래서 관련 파일만 골라 기준이 깨끗한 집합으로 바꿨다. 오케스트레이터의 게이트 로그에서는 같은 폴더들이 모두 통과했다. + +| ID | 변이 | 결과 | 잡은 테스트 | +|---|---|---|---| +| MX1 | 읽기 operation의 command descriptor 금지 제거 | **살아남음** | — (07-06) | +| MX2 | mapper 레지스트리 키 ≠ `mapperId` 허용 | **살아남음** | — (07-06) | +| MX3 | `kindForStatus(409)` → `UNKNOWN_CLIENT_FAILURE` | 죽음 | `error-classification.test.ts` | +| MX4 | `withFailureEffect(MAYBE_APPLIED)`가 `retryable`을 그대로 둠 | 죽음 | `application-query.test.tsx` | +| MX5 | V2 `KEYED_COMMAND` ↔ `REQUIRED` 정합 제거 | **살아남음** | — (07-06) | +| MX6 | V3 `NEVER` + 재시도 예산 모순 거부 제거 | **살아남음** | — (07-06, 실행기가 한 번 더 막음) | +| MX7 | 스키마 레지스트리가 검증 이슈를 상한 없이 그대로 반환 | 죽음 | `http-schema.test.ts` | +| MX8 | 모르는 `authProfileId` 허용 | 죽음 | `http-execution-v3-auth-profile.test.ts`, `rest-profile-contract.test.ts` | +| MX9 | V3 `KEYED`의 복구 descriptor 필수 제거 | **살아남음** | — (07-06) | +| MX10 | `attemptCount = attempt`(1 더하지 않음) | 죽음 | `http-diagnostics.test.ts` | +| L7 | 응답 DTO `.strip()` → `.strict()`(메타데이터는 `STRIP_UNKNOWN`) | **살아남음** | — (07-02: 선언과 실제 스키마를 대조하지 않음. 응답에 필드 하나를 더 준 테스트가 없다) | +| L1·L6 | 3.1절 실험을 같은 76파일로 다시 | 둘 다 686/686 통과, L6 `tsc` 오류 0 | — (07-02) | + +10종 중 5종이 죽었다. 입력 경계·오류 분류·인증 프로필처럼 실행 경로에 있는 규칙은 잡힌다. 조립기의 쓰기 API 규칙과 V2 선언 정합은 잡히지 않는다. + +## 5. 설계 선택 검토 (41절) + +### 5.1 한 HTTP API를 V2 선언 행과 V3 실행 descriptor로 나눠 둔다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 공개 API 계약(메서드·경로·스키마) 변경을 리뷰에서 식별한다(FE-REG-API). 실행할 때는 외부 계약 패키지가 준 검증기·상한·재시도 규칙을 그대로 쓴다(§4) | +| 2. 지킬 성질 | (a) 실행되는 API는 모두 게이트 대상이다. (b) 게이트가 기록한 값이 실행되는 값과 같다 | +| 3. 현재 보장 | 확인한 사실: V3는 조립기가 형식·상한을 강제한다(M4). V2는 레지스트리가 기준선과 비교한다(M3). 둘의 연결은 parity 테스트 6필드, 한 방향이다. **보장하지 않는 것:** (a) V3에만 있는 API(L6), (b) 스키마 id·deadline 등 6필드 밖 차이(L1, L3) | +| 4. 현실적인 대안 | (A) 현 상태. (B) parity 테스트를 양방향 + 스키마 id + 빈 집합 단언으로 넓힌다. (C) V2 행을 V3에서 생성한다(테스트 주석이 적은 방향). (D) FE-REG-API 스냅샷을 V3 조립 결과에서 직접 투영하고 V2 행을 없앤다 | +| 5. 대안의 비용 | (A) 비용 0, 빈틈 그대로. (B) 테스트 수십 줄. 두 사본과 7곳 작성 비용은 그대로. (C) 생성기와 V3에 없는 필드(`owner`, `requestSource`, `mapperId`, `providerId`) 보충, 생성물 커밋 규칙. (D) 투영 함수 1개, FE-REG-API 기준선 재승인 1회, realtime snapshot 바인딩을 V3 조회로 바꿈. 기능 작성자는 V3 하나만 쓴다 | +| 6. 현재 조건에서의 선택 | 기록된 의도는 (C)로 가는 이행 중 상태다. 확인한 조건에서는 (B)를 먼저 하는 것이 가장 작다. 구조 정리는 (D)가 (C)보다 사본을 하나 덜 남긴다. V2 전송 경로는 이 repo에서 실행되지 않으므로(`runtime-adapters.ts:74-93`) V2 행을 유지할 근거는 게이트 입력뿐이다 | +| 7. 재검토 조건 | 제품이 V2 전송을 실제로 쓰면 V2 행이 실행 사본이 된다. 그때는 operation마다 V2·V3 중 하나만 허용하는 규칙과 비교한다 | + +### 5.2 결과·검증 모양의 정본 지정(D-15) + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 검증기·매퍼·application 결과의 성공/실패 모양을 기능 작성자가 예측할 수 있게 한다 | +| 2. 지킬 성질 | 이름 하나는 모양 하나를 가리킨다. 정본은 실행 경로가 쓰는 모양이다 | +| 3. 현재 보장 | 확인한 사실: 잘못된 모양 조합은 컴파일 실패다(M4). 정본 표시는 실행 경로와 반대다(07-01). 검증기 쪽 정본(`RuntimeValidator`)은 실제로 V3 실행 경로가 쓴다(`invokeValidator`) — 이쪽은 표시와 실제가 맞다 | +| 4. 현실적인 대안 | (A) 현 상태. (B) 매퍼 결과의 정본을 `BoundaryMappingResult`로 바꾸고 다른 쪽 이름을 바꾼다. (C) 실행 경로를 `ContractMappingResult`로 옮긴다. (D) 매퍼 결과를 `Result`로 합쳐 모양 수를 줄인다 | +| 5. 대안의 비용 | (B) 타입 이름 교체만. (C) 실패 코드가 자유 문자열로 넓어진다. (D) `Result`의 `error` 필드로 통일돼 모양이 하나 준다. 바인딩·참조 mapper·realtime 코디네이터를 바꾸고 다운스트림 mapper도 바뀐다 | +| 6. 현재 조건에서의 선택 | (B). 비용이 가장 작고 닫힌 실패 코드를 지킨다. (D)는 모양 통일 효과가 있지만 다운스트림 이행 비용이 이번 문제(이름 혼동)에 비해 크다 | +| 7. 재검토 조건 | 다음 계약 버전에서 바인딩 API를 어차피 바꿀 때 (D)를 함께 본다 | + +### 5.3 zod를 `RuntimeValidator` 프로토콜 뒤에 두고, 어댑터는 기능이 만든다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 외부 계약 패키지가 zod가 아닌 검증기도 넣을 수 있어야 한다(§4, `external-contract-runtime.ts:1-8`). 템플릿 자신의 참조 기능은 zod를 쓴다 | +| 2. 지킬 성질 | 신뢰 경계의 응답은 런타임 검증을 거친다. 검증을 생략하면 그 사실이 보인다 | +| 3. 현재 보장 | 프로토콜 분리는 지켜진다. 검증기 예외도 `THROWN`으로 닫힌다(`:71-98`). **보장하지 않는 것:** zod 어댑터의 단일 출처(07-03), 검증 생략의 가시성(L5) | +| 4. 현실적인 대안 | (A) 현 상태. (B) 어댑터를 `src/contracts/`로 승격. (C) (B) + 검증 생략 표시. (D) 브랜드 타입으로 승인된 팩토리만 허용 | +| 5. 대안의 비용 | (B) 파일 이동. (C) 타입 필드 1개, 목록 출력 1곳. (D) 외부 패키지의 자체 검증기를 막아 §4와 충돌 | +| 6. 현재 조건에서의 선택 | 프로토콜 분리는 유지한다. (C)가 위험을 막지는 않지만 드러낸다. 이는 사용자 원칙(위험은 코드에 드러나야 한다)과 맞다 | +| 7. 재검토 조건 | 외부 계약 패키지가 표준 검증기를 배포하면 어댑터는 그쪽 책임으로 옮긴다 | + +## 6. 리팩토링 후보 + +| 후보 | 무엇을, 왜 | 보존해야 할 동작·타입·실패 계약 | 관련 | +|---|---|---|---| +| RF-1 | FE-REG-API 스냅샷을 V3 조립 결과에서 투영하고 V2 행·registry mapper·`SchemaDefinition` 중복을 없앤다. API 하나의 작성 위치가 7곳에서 3곳(zod 스키마, V3 행, typed mapper)으로 준다 | FE-REG-API 필드와 breaking 판정, realtime snapshot 바인딩 조건, 스키마·mapper 결합 검사, 레지스트리 스냅샷 artifact 형식 | 07-02 | +| RF-2 | `zodValidator`를 `src/contracts/zod-validator.ts`로 옮긴다 | `structuredClone`된 성공 값, 경로 배열, `schemaId` 필수, zod는 `contracts/zod.ts` 경유 | 07-03 | +| RF-3 | `MappingResult` 이름 정리: 실행 경로를 `BoundaryMappingResult`로, 정본 쪽은 `ContractMappingResult`로. 별칭 2개 제거 | 닫힌 매퍼 실패 코드 3종, `MAPPING_CONTRACT_VIOLATION` 정규화, 매퍼 예외 → 실패 결과 | 07-01 | +| RF-4 | 참조 registry mapper의 손 guard(`isReferenceResourceDto`)를 zod 스키마 `safeParse`로 바꾼다. RF-1을 하면 registry mapper 자체가 필요 없다 | 100개 초과 → `OUTPUT_LIMIT_EXCEEDED`, 모양 오류 → `MAPPING_INVARIANT_REJECTED`, 예외 없음 | 07-02 | +| RF-5 | `createFailure(kind, operationId, attempt, details)`의 세 번째 위치 인자를 옵션 객체 `{ attemptIndex }`로 바꾼다. 지금은 0부터 세는 값이라 `attemptCount = attempt + 1`이 되고(`errors.ts:172`), 호출 19곳 중 16곳이 리터럴 `0`을 넘긴다(grep) | `attemptCount ≥ 1`, 결과 불명 쓰기의 `retryable=false`·`action` 규칙, 허용 필드만 복사 | 24 | +| RF-6 | `src/contracts/` 41파일을 하위 폴더 3개(공유 어휘 / API 계약 / 릴리스·설정 산출물)로 나누거나 최소한 `README`로 지도를 둔다. "API 추가"에 필요한 파일은 41개 중 6개(`external-contract-runtime`, `api-operations`, `schema-registry`, `boundary-mapper`, `errors`, `result`)다 | 공개 import 경로(다운스트림이 직접 import), 아키텍처 규칙의 경로 패턴 | 4, 9 | + +## 7. 성능·폴더 구조·테스트 렌즈 + +**성능.** 이 영역의 실행 비용은 작다. + +| 항목 | 측정 | 조건 | +|---|---|---| +| 조립 시간 | `composeContractContributions`(HTTP 3행) 1회 48µs | node 24, 2,000회 평균, 부하 9.0 | +| 조립기 코드 크기 | `external-contract-runtime.ts`와 의존 단독 번들 15.1KB(min) / 5.2KB(gzip) | esbuild 0.28.1 `--minify`, zod 제외 | +| V2 선언 코드 | `api-operations.ts` 3.0KB / 1.3KB, `boundary-mapper.ts` 0.9KB / 0.5KB, `schema-registry.ts` 2.1KB / 0.9KB | 같음. V2 행 검증(`validateApiRuntimeBindings`)은 부팅 때 브라우저에서도 돈다 | +| zod 포함 청크 | `reference-feature-runtime-descriptor-*.js` 95.3KB / 25.0KB(gzip -9) | `dist/assets`, 17:42 빌드본(읽기만) | +| 설치 계약 청크 | `installed-feature-contracts-*.js` 3.7KB / 1.3KB | 같음 | +| 테스트 시간 | `test:contract` 0.47초, `test:runtime-schema` 0.59초, `second-api-feature-registries` 1.17초(repo 복사 포함) | 오케스트레이터 게이트 로그 | + +V2 이중 기술(07-02)의 비용은 바이트가 아니라 작성·검토 비용이다. 성능을 이유로 고칠 것은 없다. + +**폴더 구조.** `src/contracts/`는 41파일이 한 폴더에 있다. 공유 어휘(`result`, `errors`, `operation-id`), API 계약 기계(`external-contract-runtime`, `api-operations`, `rest-profiles`, `schema-registry`, `boundary-mapper`), 릴리스·설정 산출물(`env`, `release-artifacts`, `deployment-admission`, `contract-set*`), 브라우저 런타임 계약(`service-worker*`, `web-worker`, `web-push`, `realtime-*`)이 섞여 있다. API를 추가하는 사람은 이 중 6개만 알면 되는데 그 지도가 없다(RF-6). 계약에서 플랫폼으로 가는 간선은 하나다(`external-contract-runtime.ts:15-19` → `src/platform/traffic/traffic-budget.ts`). 반대 방향 간선은 없다. 기능별 API 계약 파일(`src/features//contracts/`)의 위치는 책임과 맞는다. 다만 zod 어댑터처럼 기능 공통인 코드가 거기 있다(07-03). + +**테스트.** 실행 경로의 규칙(오류 분류, 인증 프로필, 검증 이슈 상한, 시도 횟수)은 변이로 잡힌다. 조립기의 쓰기 API 규칙 4개와 V2 정합 1개는 잡히지 않는다(07-06). 응답 DTO의 strip 정책도 고정하는 테스트가 없다(L7). 두 사본 사이의 차이(L1, L3, L6)는 테스트 품질보다 07-02의 구조 문제다. `second-api-feature-registries`는 "governance 무수정"을 고정하지만, 그 기능은 V2 행만 있고 실행 사본이 없다. 그래서 "API 기능 추가가 된다"의 증명으로는 범위가 좁다. 실행 시간은 과하지 않다. + +## 8. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 판정 | 통제 (목표 / 확인) | 증거 | 이유·잔여 위험 | +|---|---|---|---|---|---| +| **1** | 코드 성숙도 | P | M4 / M3 | E2 (V2, L4, L5, MX) | 외부 JSON은 strict 파서나 exact decode를 거친다. 조립기는 복사 후 검증한다(`external-contract-runtime.ts:598-645, 699-712`). 설계서가 요구한 fixture 규칙이 빠졌다(07-04) | +| 2 | 구조적 성숙도 | O | M3 / M3 | E2 (`check:architecture` PASS) | contracts → application·presentation·bootstrap 금지 규칙. 계약 → 플랫폼 간선 1개, 반대 방향 없음 | +| **3** | 변경 용이성 | P | M3 / M1 | E2 (L6, X4, X5) | API 하나에 7곳(07-02), 라우트 하나에 governance 수정(P-07-03), 설정 키 하나에 3파일(P-07-05) | +| 4 | 인지 부하 | P | M1 / M1 | E1 | 성공/실패 모양 6종, 같은 이름 다른 모양(07-01), 재전송 규칙 세 이름 체계(07-02), 오류 어휘 둘(07-05) | +| 5 | 위험 가시성 | P | M2 / M2 | E2 (L4, L5) | 쓰기 API의 결과 불명·KEYED 규칙은 타입과 조립 규칙으로 드러난다. 다만 `commandRecovery`를 누가 읽는지는 타입 옆에 없다(07-07). 검증 생략(07-03)과 fixture 출처(07-04)는 드러나지 않는다. 레지스트리 정상 출력이 `PASS; compatibility=breaking`(P-07-01) | +| 6 | 실패 성숙도 | O | M3 / M3 | E2 | 조립 실패는 부팅을 멈춘다. 검증기 예외는 `THROWN`. 결과 불명 쓰기는 `retryable=false` | +| 7 | 운영 성숙도 | > | - | - | 영역 03·13 | +| 8 | 디버깅 가능성 | P | M2 / M2 | E1 | 조립 오류는 `featureId/operationId: 이유`를 담는다(`:410`). 레지스트리 증거 누락 메시지는 고칠 방법을 말하지 않는다(P-07-04) | +| 9 | 유지보수 성숙도 | P | M2 / M1 | E1 | 폐기 별칭의 제거 조건이 충족될 수 없다(07-01). 오래된 증거 13건(P-07-01). `compatibility.md`의 줄 번호가 실제와 다르다 | +| 10 | 테스트 성숙도 | P | M3 / M2 | E2 (MX1~MX10, L1~L7) | 변이 10종 중 5종 생존: 조립기 쓰기 API 규칙과 V2 정합(07-06). 응답 DTO `.strict()` 변이 생존(L7). 두 사본 사이 차이는 검출되지 않는다(07-02). 관련 76파일 약 10초로 실행 시간은 과하지 않다 | +| 11 | 데이터 성숙도 | > | - | - | 영역 05 | +| 12 | 동시성 성숙도 | - | - | - | 계약은 순수 선언과 파서다 | +| 13 | 확장성 | P | M2 / M1 | E2 | 기능 수에 비례해 중앙 allowlist(P-07-03)와 API당 사본 7곳(07-02)이 는다 | +| 14 | 성능 성숙도 | O | - / - | E2 (P1, P2) | 조립 48µs, 조립기 5.2KB gzip. 상한이 정해진 계산만 한다(7절) | +| 15 | 보안 성숙도 | P | M4 / M3 | E2 (Z1, L5) | 선언 안 된 `VITE_*`는 빌드 실패, 비밀 같은 설정 키는 부팅 거부. zod facade 규칙의 subpath 빈틈(P-07-06). 검증 생략 검증기가 보이지 않는다(07-03) | +| 16 | 의존성 성숙도 | > | - | - | 영역 13 | +| **17** | API / Contract 성숙도 | P | M3 / M3(부분) | E2 (L1, L3, L4, L6, X2~X5) · E3 (tech-log) | 런타임 설정은 기준선 비교(FE-GATE-014). 실행 API(V3)가 레지스트리 게이트 밖이다(07-02). 계약 집합에서 fixture 출처 API가 빠진다(07-04). 레지스트리 게이트의 과잉·과소 판정(P-07-01, P-07-02) | +| 18 | 배포 성숙도 | > | - | - | 영역 13. 계약 집합 누락(07-04)은 릴리스 정합 입력 문제라 여기서 셌다 | +| **19** | 설정 성숙도 | P | M3 / M2 | E2 (V2) | build 변수는 선언·기본값 일치 검사가 있다. runtime 행은 zod와 다르고 대조가 없다(P-07-05) | +| 20 | 개발자 경험 | P | M2 / M1 | E1 · E3 | "Adding a feature"가 HTTP 계약의 두 사본, `EXTERNAL_PACKAGE`, zod 어댑터 출처를 말하지 않는다(3.1절). 증거 절차 안내 없음(P-07-04) | +| 21 | Guardrail 성숙도 | P | M3 / M3(부분) | E2 | 6필드 parity(07-02), fixture 규칙 없음(07-04), 조립기 규칙의 회귀 검출 없음(07-06), zod subpath(P-07-06), 증거 값 미결합(P-07-01) | +| **22** | 추상화 성숙도 | P | M2 / M2 | E2 | `InstalledHttpContract` + 조립기는 외부 패키지 경계를 드러내는 추상화라 구현이 하나여도 정당하다(가이드 22절 판정 주의). V2 행 층은 실행되지 않는 두 번째 기술이다(07-02). 매퍼 결과 모양이 정본·별칭·변환기로 셋이다(07-01) | +| **23** | 일관성 | P | M2 / M1 | E1 | 재전송 규칙 이름: V2 `KEYED_COMMAND`·`NON_REPLAYABLE`, V3 `KEYED`·`NEVER`, Browser RPC는 V2와 같은 이름. "V3"라는 말이 HTTP(버전 필드 없음)와 Browser RPC(`contractVersion: 3`)에서 다른 것을 가리킨다. 오류 어휘 둘(07-05) | +| **24** | 네이밍 / 의미 성숙도 | P | M2 / M1 | E1 | 같은 이름 `MappingResult`, 틀린 "canonical" 표시(07-01). `retryable`과 `action: "retry"`의 뜻 차이(07-05). `RuntimeValidator`라는 이름이 검증하지 않는 구현도 허용(07-03). `createFailure`의 `attempt`는 0부터 센다(RF-5). `commandRecovery`라는 이름이 런타임 복구를 암시한다(07-07). `ENV_REGISTRY`가 런타임 설정 키도 담는다(P-07-05) | +| 25 | 조직 확장성 | P | M2 / M1 | E1 | 기능 팀마다 같은 governance JSON(P-07-03)을 고친다. API 계약은 기능 폴더 안에 있어 충돌이 적다 | +| 26 | Ownership 성숙도 | P | M2 / M1 | E1 | 폐기 별칭 owner는 있으나 제거 조건이 충족 불가(07-01). 오래된 증거 정리 책임 없음(P-07-01) | +| 27 | 삭제 가능성 | P | M3 / M2 | E1 | 참조 기능을 지우면 유일한 zod 어댑터도 사라진다(07-03). 삭제 드릴 실행은 영역 14 | +| 28 | 회복 가능성 | - | - | - | 계약은 복구 절차를 소유하지 않는다 | + +X(미충족)인 관점은 없다. + +## 9. 미검증 목록 + +| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| tech-log에서 검증 생략 때문에 실제로 잘못된 payload가 화면까지 간 사례 | 제품 운영 기록을 보지 않았다 | 제품의 `MAPPING_INVARIANT_REJECTED` 텔레메트리 | +| tech-log 레지스트리 스냅샷에 HTTP API가 없는지 | 제품에서 `check:registries`를 돌리지 않았다(grep으로 V2 행 0개만 확인) | 제품 브랜치를 풀어 `check:registries` artifact 확인 | +| `"zod/v4"` 우회가 CSP 위반으로 이어지는 청크 배치 | 이번에 빌드하지 않았다 | 변이 빌드 + `tests/e2e/production-csp.spec.ts` | +| `src/contracts/` 코드의 실제 번들 몫 | sourcemap 없음 | sourcemap 빌드 후 모듈별 크기 | +| 줄 단위로 읽지 않은 계약 파일 8개(1.2절) | 이번 렌즈(API 계약 추가)에 시간을 썼다 | 해당 파일의 경계 검증 읽기와 변이 실험 | diff --git a/docs/reviews/2026-11-01-maturity-review/08-presentation.md b/docs/reviews/2026-11-01-maturity-review/08-presentation.md new file mode 100644 index 00000000..499f0b58 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/08-presentation.md @@ -0,0 +1,572 @@ +# 08 presentation 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 영역: `src/presentation/` · 깊게 본 관점: 4, 5, 8, 14, 15, 23, 24 +> 이번 라운드 추가 요구: Firefox·WebKit 확인, 텍스트·화면 200% 확대, 접근성 트리, 정보 구조·위계 평가(`impeccable` critique, `ux-heuristics`), React 렌더·컴포지션 패턴(`vercel-react-best-practices`, `vercel-composition-patterns`) + +## 0. 요약 + +- **지난 라운드(2026-09-29) 발견 8건은 모두 남았다.** `af3d8e6..d99301b` 사이에 그 근거 파일은 한 줄도 바뀌지 않았다. 바뀐 것은 UI 감사 수정(CSS·토큰·예제 eyebrow·표 스크롤 영역)뿐이다. +- **UI 감사 수정(UI-01~08)은 유지된다.** 세 엔진에서 포커스 링이 모든 Tab 대상에 보였고, UI-04 검사가 chromium·firefox·webkit에서 통과했다. +- **세 엔진 모두 6개 라우트가 콘솔 오류 없이 그려지고 키보드로 이동된다.** 건너뛰기 링크, 주요 탐색 → 라우트 이동 → h1 포커스가 chromium·firefox·webkit에서 같게 동작했다. 접근성 트리도 세 엔진이 같다. +- **확대하면 기능이 사라진다(08-01, Medium·P1).** 폭 48rem 미만(모바일, 또는 1280px 창에서 약 170% 이상 확대)에서 색상 테마 선택, 세션 상태, 브랜드가 `display: none`이 되고 드로어에도 없다. WCAG 1.4.10 위반이다. +- **URL 검색값만 바뀌어도 라우트 이동으로 처리한다(08-02).** 필터를 URL에 묶으면 값을 바꿀 때마다 포커스가 `
`으로 튀고, 화면이 맨 위로 가고, `route.changed` 진단이 한 번 더 남는다(component probe로 확인). +- **서버 상태 훅의 raw(legacy) 입력이 공개돼 있다(08-03).** 이 형태로 쓴 쓰기는 멱등 키가 없고, 결과 불명 뒤 "같은 요청으로 다시 보내기"가 아무것도 하지 않는다(probe로 확인). 2026-08-01 계획서에 "제거"로 적혀 있지만 남아 있다. +- 화면 위계는 약하다. h2·h3이 본문과 같은 16px/400이다(08-04). 상태 화면 제목은 h2로 고정돼 카드 안에서 제목 순서가 뒤집힌다(08-05). 한국어 단어가 중간에서 끊긴다(08-06). +- High 이상 발견은 없다. 새 발견 9건: Medium 3(P1 1, P2 2), Low 6(P2 3, P3 3). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `fix/ui-design-audit-2026-11-01` / `d99301b`. 메인 작업 트리의 미추적 파일은 `.claude/`와 이번 리뷰 폴더뿐이다 | +| 목적·실행 구성 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 필수 요구 | `PRODUCT.md`: WCAG 2.2 AA, 한국어 기본 + 영어, 업무 도구·일반 서비스·랜딩을 한 디자인 시스템으로 받친다 | +| 읽은 코드 | `src/presentation/` 중 routes(`app-router.tsx` 전체), layouts, components 전부, pages, examples(정보 구조 평가용), templates, forms(`use-app-form.ts`, `form-components.tsx`, `use-dirty-navigation-guard.tsx`), boundaries, i18n(`message-contract.ts`, `locale-provider.tsx`, `catalog.ts` 일부), providers, design-system(index, primitives 일부, patterns, tokens), styles(base·responsive·pages·shell 일부), adapters/query(`application-query.ts` 60-400, 500-770행, `server-state-generation-provider.tsx`, `index.ts`). 연결 확인용으로 `src/features/reference-feature/presentation/*`, `tests/e2e/{accessibility,theme,responsive,compact-smoke,i18n}.spec.ts`, `tests/component/router.test.tsx`, `tests/helpers/fixture-feature.tsx`, `docs/architecture/routing-pages-and-patterns.md` 6.3절, `docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md` Task 3 | +| 읽은 리뷰 | 지난 `2026-09-29-maturity-review/08-presentation.md`·`README.md`, `2026-11-01-ui-design-audit.md`, 이번 라운드의 09·10·15·16 문서(중복 확인용) | +| 게이트 | 오케스트레이터가 이 커밋에서 실행한 결과를 읽었다. `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`(8s)·`test:integration`·`check:design-system`·`check:i18n` 모두 rc=0. `test:system` rc=1(영역 12·13 소관, 이 영역과 무관) | +| 이전 리뷰와 비교 | 지난 08-01~08-08은 현재 코드로 다시 확인했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 | + +### 1.1 실행한 명령과 실험 + +실험은 분리 worktree(`scratchpad/wt-08`, `d99301b`, 메인 `node_modules` 링크)에서 했다. 그 안에서는 `pnpm`을 부르지 않았다. 빌드·Playwright·preview는 `flock heavy.lock`으로 감쌌다. 측정 시점 부하는 표에 적었다(22코어 호스트, 다른 에이전트와 공유). + +| ID | 명령·실험 | 부하(1분) | 결과 | +|---|---|---|---| +| B1 | `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 4.7 | 성공. `design-system-*.js` 216.61 kB / gzip 66.75 kB. 첫 화면 정적 import 묶음 gzip -9 합계 203,521 B(직접 계산, 예산 204,800 B) | +| P1 | Playwright 전용 설정(`review08/playwright.review08.config.ts`, 포트 5190, `npx vite preview`), chromium·firefox·webkit. 6개 라우트 렌더·Tab 순서·건너뛰기 링크·주요 탐색 키보드 이동·텍스트 200%·화면 200%·aria snapshot·en-US 문서 언어·제목 크기 측정 | 10.7 | 96개 중 90 통과, 6 skip(chromium 전용 측정 3종 × 2엔진). 1.1분 | +| P2 | 같은 실행 안에서 기존 `tests/e2e/i18n.spec.ts`(UI-04 검사 포함)를 세 엔진에서 | 10.7 | 9/9 통과 | +| P3 | `impeccable detect --json src/presentation`(소스) | — | 1건: `bounce-easing` `primitive.css:49`(UI 감사가 이미 "채택 안 함"으로 판정) | +| P4 | `impeccable detect --json --viewport 1280x800·390x844` 6개 URL(빌드 preview, 끝난 뒤 서버 종료 확인) | 12.4 | `hero-eyebrow-chip`/`kicker-above-heading` 홈 1건, `nested-cards` `/examples/ui` 2·`/examples/states` 3건. `overused-font`는 사라졌다(UI-05 유지) | +| E1 | probe: 기능 presentation 파일에 raw 형태 `useApplicationMutation({ definitionId, execute })`·`useApplicationQuery({ queryKey, execute })`를 두고 `npx tsc -p tsconfig.app.json --noEmit`, `npx eslint`, `npx depcruise` | — | 셋 다 통과. 막는 장치가 없다 | +| E2 | component probe: raw mutation이 `MAYBE_APPLIED`로 실패한 뒤 `resendUnknownEffect()` | 22 | 결과 `null`, `execute` 1회만 호출(인자 1개, intent 없음), 상태는 `mutation-effect-unknown` 그대로 | +| E3 | component probe: 공개 fixture 라우트에서 ``가 `setSearchParams`로 `?limit=10`을 쓰자 포커스가 select에서 `main#main-content`로 갔고 `route.changed`가 1건 더 기록됐다. 같은 원인으로 이미 홈에서 "홈" 링크를 누르면 포커스가 `
`에 간다(P1, 세 엔진). 문서는 "route 성공 후 heading focus", "새 primary route는 top으로"만 말한다(`routing-pages-and-patterns.md:298-307`). 같은 라우트의 검색값 변경은 다루지 않는다. 반면 템플릿은 필터를 URL에 두라고 권한다(같은 문서 4.2절 search codec, `CollectionPage`의 `toolbar`·`activeFilters` slot) | +| 발생 조건 | 기능이 필터·정렬·페이지 번호를 URL 검색값에 묶고, 그 값을 화면 안의 컨트롤이 바꿀 때. 샘플에는 아직 그런 컨트롤이 없다 | +| 영향 | 키보드·스크린 리더 사용자가 필터를 바꿀 때마다 위치를 잃는다(WCAG 3.2.2 On Input). 긴 목록에서 페이지 번호를 누르면 맨 위로 간다(이건 바람직할 수도 있다). `route.changed` 진단이 필터 변경 수만큼 늘어 라우트 이동 지표가 부풀려진다 | +| 심각도·우선순위 | Medium · P2 — 지금 샘플에서는 드러나지 않는다. 다만 모든 제품의 목록 화면이 처음 만드는 기능에서 나타나고, 코드를 읽기 전에는 알 수 없다 | +| 통제·증거 | M0(검색값 변경과 라우트 변경을 나누는 규칙 없음) · E3(probe, jsdom). 실제 브라우저의 스크롤은 정적 확인(E1) | +| 확실성과 남은 가정 | 포커스 이동과 진단 중복은 확인. 실제 스크린 리더 발표는 미확인 | +| 결정의 근거 | 5.1절 | +| 이해 비용 | 목록 화면을 만드는 사람이 `app-router.tsx`의 `RouteLifecycle`과 `page-header.tsx`의 의존값을 함께 읽어야 결과를 예측한다(7.4절 대표 과제) | +| 최소 개선 방향 | 포커스·스크롤·`route.changed`의 기준을 "라우트 ID 또는 pathname이 바뀜"으로 좁힌다. 검색값만 바뀐 경우는 아무것도 하지 않는다. 페이지 번호처럼 맨 위로 보내야 하는 경우는 그 화면이 직접 한다 | +| 대안 비교 | 5.1절 (A)~(C) | +| 단순화의 보존 조건 | 뒤로·앞으로 이동의 스크롤 복원(`scroll-restoration.spec.ts`), locale 변경이 라우트 변경이 아님(`router.test.tsx:119-149`), 해시 대상 포커스(`page-header.tsx:37-41`), 상태 화면(인증 필요·잘못된 주소·꺼진 기능)에서도 제목·포커스·진단이 동작(`router.test.tsx:151-211`) | +| 비용·부작용 | `app-router.tsx` 한 곳과 테스트 1~2개. 지금 검색값 변경을 이동으로 세는 대시보드가 있다면 수치가 줄어든다 | +| 재검토 조건 | 검색값이 사실상 다른 화면을 뜻하는 라우트(예: 탭을 URL로)가 생기면 그 라우트만 선언으로 이동 처리 | +| 완료 기준 | E3 probe에서 포커스가 select에 남고 `route.changed` 증가가 0이다 | +| 검증 방법 | E3 probe를 `router.test.tsx`에 정식 테스트로 넣는다 | + +### 08-03 서버 상태 훅이 raw(legacy) 입력을 공개 API로 받아, 기능이 멱등 키·scope 검사 없이 쓰기를 보낼 수 있고 그 경로의 "다시 보내기"는 아무것도 하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 5, 17, 24, 22, 4, 6 | +| 근거 | `useApplicationQuery`가 `BoundQuery` 또는 `{ queryKey, execute }`를 받는다(`application-query.ts:60-69`). `useApplicationMutation`이 `BoundMutation` 또는 `LegacyMutationOptions`를 받는다(`:195-216`, `:277-284`). barrel이 둘 다 내보낸다(`presentation/adapters/query/index.ts`). raw mutation은 `execute(input)`만 받고(`:389`) 실행 종류가 `LEGACY`라 intent가 없다(`:547`). 결과 불명 재사용은 `candidate.intent?.canonicalInputIdentity`로 찾으므로 raw 경로는 항상 새 요청이다(`:507`). `resendUnknownEffect`는 `!head.intent`면 `null`을 돌려준다(`:736-746`). 폼은 결과 불명이 남아 있으면 새 제출을 막고(`use-app-form.ts:305`) 재전송 결과가 `null`이면 아무 처리도 하지 않는다(`:332`). E1: 기능 presentation 파일의 raw 사용이 `tsc`·`eslint`·`depcruise`를 모두 통과. E2: raw mutation `MAYBE_APPLIED` 뒤 `resendUnknownEffect()`는 `null`, `execute` 1회, 상태 그대로. 기록된 의도: `docs/superpowers/plans/2026-08-01-http-worker-adapter-remediation.md:63-75` Task 3 "remove `LegacyMutationOptions` and the raw query union from production exports"가 미완료(`[ ]`). 현재 제품 코드의 호출은 모두 bound다(`use-reference-feature.ts:81-113`, `:140-145`). raw 형태는 테스트만 쓴다(`application-query.test.tsx` 32회 등) | +| 발생 조건 | 기능 작성자가 짧은 raw 형태로 쓰기 훅을 만들 때. 타입·lint·아키텍처 검사가 막지 않는다 | +| 영향 | (1) 멱등 키 없이 POST가 나간다. 응답을 잃은 뒤 사용자가 다시 저장하면 새 요청으로 중복 생성될 수 있다. (2) 샘플 폼을 복사하면 "같은 요청으로 다시 보내기" 버튼이 보이지만 눌러도 아무 일이 없다. 새 제출도 막혀 사용자는 "변경됨으로 확인"이나 목록으로 나가는 링크 말고는 길이 없다(`reference-resource-form-page.tsx:146-170`의 구성). (3) 세션 세대 검사(`scope.isCurrent`)와 측정 profile이 빠진다 | +| 심각도·우선순위 | Medium · P2 — 결과가 크면 가이드 35.2의 "결과 불명 작업의 무방비 재실행"(High)에 닿는다. 다만 템플릿 코드는 bound만 쓰고, raw를 고르는 것은 기능 작성자의 선택이라 도달 가능성을 낮게 봤다 | +| 통제·증거 | 제품 코드에서 bound 사용 M2(샘플이 지킴) / raw 사용 차단 M0 · E3(E1, E2) | +| 확실성과 남은 가정 | 훅 동작은 확인. 서버가 키 없이도 중복을 막는지는 제품 몫이다 | +| 결정의 근거 | 5.2절 | +| 이해 비용 | 기능 작성자가 두 overload 중 어느 쪽이 안전한지 알려면 925줄 파일의 `LEGACY` 분기를 읽어야 한다. 이름 `Legacy`는 내부 타입에만 있고 공개 함수 시그니처에는 없다 | +| 최소 개선 방향 | 계획서 Task 3대로 raw overload를 제품 export에서 빼고 `tests/helpers`의 harness로 옮긴다. 먼저 "제품 훅이 raw 입력을 거절한다"는 타입 fixture를 넣는다 | +| 대안 비교 | 5.2절 (A)~(C) | +| 단순화의 보존 조건 | bound 경로의 동작(멱등 키 재사용, scope fence, JOIN_IDENTICAL·REJECT_WHILE_ACTIVE, 낙관적 레이어)과 그 테스트. raw로 쓰인 테스트는 harness로 옮겨 같은 단언을 유지한다. `check:types:fixture:*`는 그대로 통과 | +| 비용·부작용 | `application-query.ts` 분기 제거(수십~백여 줄), 테스트 파일 4개 이전. 제품이 raw를 쓰고 있다면 [계약] 변경 | +| 재검토 조건 | bound 정의가 너무 무거워 raw가 꼭 필요한 경우(예: 서버 없는 로컬 쓰기)가 생기면 이름에 위험을 드러낸 별도 훅(`useLocalMutation`)으로 둔다 | +| 완료 기준 | E1 probe가 `tsc`에서 실패한다. E2는 harness 밖에서 재현할 수 없다 | +| 검증 방법 | 타입 fixture(`tsconfig.*` 하나), component 테스트 전체 | + +### 08-04 h2·h3의 글자 크기·굵기가 본문과 같아 화면 위계가 보이지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 4, 9 | +| 근거 | 측정(P1 `heading-scale.json`, chromium): 6개 라우트 모두 H1 56px/400, H2·H3 16px/400. 본문 설명 문단은 16.8px/400이다. 즉 섹션 제목이 본문보다 작다. 원인: `theme.css:1`이 Tailwind preflight를 넣어 제목 크기·굵기를 초기화한다. `base.css:31-39`는 h1 크기와 h2 줄 간격만 정한다. 글자 토큰은 `--font-size-xs`~`--font-size-lg`(최대 1.125rem)뿐이다(`primitive.css:25-34`). 골든 `state-surfaces-light`에서 섹션 제목·카드 제목·상태 제목이 같은 크기로 보인다 | +| 발생 조건 | h2·h3을 쓰는 모든 화면. 컴포넌트 CSS가 따로 크기를 주지 않는 곳 | +| 영향 | 사용자가 구획을 훑어볼 수 없다. 디자인 시스템이 받칠 세 종류 서비스(업무 도구·일반 서비스·랜딩)가 각자 제목 크기를 만들어 서로 달라진다 | +| 심각도·우선순위 | Low · P2 — 가독성 문제다. 템플릿 전체에 복제되고 고치는 비용이 작다 | +| 통제·증거 | M0 · E3(P1 측정) | +| 확실성과 남은 가정 | 확인. 의도적으로 평평하게 둔 기록은 찾지 못했다 | +| 결정의 근거 | 적용 제외 — 정할 값이 빠진 것이다. 어떤 크기를 쓸지는 디자인 결정이다 | +| 이해 비용 | 제품 개발자가 제목이 왜 본문 같은지 알려면 Tailwind preflight를 알아야 한다 | +| 최소 개선 방향 | 제목 단계 토큰(`--font-size-heading-2`, `-3`, 굵기 semibold)을 primitive·semantic에 더하고 `base.css`에서 h2·h3에 적용한다. 컴포넌트 제목(카드·상태 화면)은 이 토큰을 쓴다 | +| 대안 비교 | 적용 제외 — 값 추가 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | CSS 수십 줄, 시각 골든 5장 갱신 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 6개 라우트에서 h2 > h3 > 본문 순으로 크기 또는 굵기가 다르다 | +| 검증 방법 | 계산된 스타일 단언(Playwright) 또는 `check:design-system`에 제목 토큰 존재·사용 규칙 | + +### 08-05 상태 화면·오류 요약의 제목이 h2로 고정돼, 카드나 섹션 안에 넣으면 제목 순서가 뒤집힌다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 24, 22, 10 | +| 근거 | 고정 h2: `EmptySurface`(`async-surface.tsx:52`), `TerminalErrorSurface`(`:94`), 접근 상태 화면(`state-surfaces.tsx:24`), `ErrorSummary`(`form-components.tsx:57`). 반면 `Card`는 `headingLevel`을 받는다(`core.tsx:252-269`). 접근성 트리(P1): `/examples/states`에서 `article "빈 화면"`(h3) 안에 h2, `article "복구 가능한 오류"`(h3) 안에 h2. 변이 M5(상태 화면 제목을 `

`로)가 component 211개를 모두 통과했다 | +| 발생 조건 | 상태 화면을 Card(h3)·상세 페이지 구획(h2) 안에 넣을 때 | +| 영향 | 스크린 리더의 제목 목록에서 구조가 틀린다. 카드 제목보다 그 안의 상태 문구가 상위 제목이 된다 | +| 심각도·우선순위 | Low · P3 — 갤러리에서 확인. 제품 화면에서는 배치에 따라 다르다 | +| 통제·증거 | M0 · E3(접근성 트리), 테스트 생존 E2 | +| 확실성과 남은 가정 | 확인 | +| 결정의 근거 | 적용 제외 — Card에 이미 있는 계약을 다른 컴포넌트에 적용하지 않은 누락이다 | +| 이해 비용 | 화면 작성자가 컴포넌트마다 제목 수준을 열어 봐야 한다 | +| 최소 개선 방향 | 네 컴포넌트에 `headingLevel?: 2 \| 3 \| 4`(기본 2)를 더한다. 갤러리는 3을 넘긴다 | +| 대안 비교 | 적용 제외(제목 수준 context는 R7에서 비교) | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 컴포넌트 4개, 테스트 1개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `/examples/states` 접근성 트리에서 카드 안 상태 제목이 h4다. M5 변이가 테스트에 잡힌다 | +| 검증 방법 | component 테스트에 `getByRole("heading", { level })` 단언 | + +### 08-06 한국어 줄바꿈 규칙이 없어 한국어 단어가 중간에서 끊긴다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 1 | +| 근거 | `src/presentation/styles`·`tokens`에 `word-break` 선언이 0건이다(`overflow-wrap: anywhere` 2곳만, `pages.css:103`, `:111`). 브라우저 기본 줄바꿈은 한국어를 글자 단위로 끊는다. 커밋된 골든: `app-shell-wide-light` "마운 / 트", `state-surfaces-light` "계 / 속할", "돌아가 / 세요". P1 텍스트 200%: 로그인 버튼 "로그 / 인", 카드 제목 "실행 계 / 약"(세 엔진) | +| 발생 조건 | 한국어 문구가 줄바꿈되는 모든 곳. 좁은 폭·확대에서 더 많다 | +| 영향 | 읽기 속도가 떨어지고 버튼 라벨이 쪼개진다. `PRODUCT.md` 원칙 5(한국어 기본)와 맞지 않는다. 모든 파생 서비스가 받는다 | +| 심각도·우선순위 | Low · P2 — 가독성. 한 줄로 고친다 | +| 통제·증거 | M0 · E3(골든, P1 스크린샷) | +| 확실성과 남은 가정 | 확인 | +| 결정의 근거 | 적용 제외 — 언어 기본 규칙 누락 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | `base.css`에 `:lang(ko) { word-break: keep-all; overflow-wrap: anywhere; }`. 긴 영문 토큰은 `overflow-wrap`이 받는다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | CSS 몇 줄, 시각 골든 갱신. 좁은 칸에서 한 줄 높이가 늘 수 있다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 골든과 320px·텍스트 200% 스크린샷에 단어 중간 줄바꿈이 없다 | +| 검증 방법 | 시각 골든 갱신 + `getComputedStyle(document.body).wordBreak` 단언 | + +### 08-07 en-US로 바꾸면 예제 화면 4개는 한국어 본문인데 문서 언어가 en-US다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 23, 24, 1 | +| 근거 | `LocaleProvider`가 ``을 선택한 locale로 바꾼다(`locale-provider.tsx:89-92`). 예제 화면은 의도적으로 i18n 밖이다(VD-06 `:72`, `check-i18n.ts:55-57`) — 문구가 한국어 literal이다(`platform-overview-page.tsx:317`, `ui-gallery-page.tsx:74`, `state-gallery-page.tsx:30`, `auth-example-page.tsx:14`). P1 `en-us-language.json`: en-US에서 `/examples/platform` main의 한글 1,013자, `lang` 속성 0개. 문서 제목은 "Platform composition"(영어), h1은 "플랫폼 구성" | +| 발생 조건 | 사용자가 언어를 English로 바꾸고 예제 화면을 볼 때 | +| 영향 | 스크린 리더가 한국어를 영어 음성 규칙으로 읽는다(WCAG 3.1.2 Language of Parts). 탭 제목과 h1 언어가 다르다 | +| 심각도·우선순위 | Low · P3 — 지울 수 있는 예제 화면이다. 다만 템플릿 첫인상이 이 화면들이다 | +| 통제·증거 | M0 · E3 | +| 확실성과 남은 가정 | 확인 | +| 결정의 근거 | 확인한 사실: 예제를 i18n 밖에 둔 것은 기록된 결정이다. 리뷰어 추론: 그 결정의 결과(`lang` 불일치)는 다루지 않았다. 결정 자체는 유지해도 된다 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | 예제 화면 루트 `section`에 `lang="ko-KR"`을 준다(4곳). 번역은 하지 않는다 | +| 대안 비교 | (A) 현 상태. (B) `lang="ko-KR"` 고정: 비용 4줄, 결정 유지. (C) 예제도 catalog로 번역: 문구 수백 개, 예제가 지울 수 있는 코드라 비용이 크다. (B) | +| 단순화의 보존 조건 | `check-i18n` 예외 범위는 그대로 | +| 비용·부작용 | 4줄 | +| 재검토 조건 | 예제를 제품 문서용으로 번역하기로 하면 (C) | +| 완료 기준 | en-US에서 예제 main 안에 `lang="ko-KR"` 요소가 있다 | +| 검증 방법 | P1의 en-US 측정 재실행 | + +### 08-08 갤러리에서만 쓰는 primitive가 셸이 쓰는 primitive와 같은 파일에 있어 초기 청크에 실린다(약 3.9 KB gzip) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 14, 13, 22 | +| 근거 | 셸이 `Drawer`(`overlays.tsx`), `Select`(`forms.tsx`), `Button`·`IconButton`(`core.tsx`)을 정적으로 import한다(`app-shell.tsx:11-17`). 같은 파일에 `Tooltip`·`Menu`·`Popover`·`ToastProvider`·`ConfirmationDialog`, `Switch`·`RadioGroup`·`Checkbox`·`TextArea`·`SearchField`, `Card`·`Alert`·`Badge`가 있다. 이 export를 쓰는 곳은 `examples/`와 stories뿐이다(import 분석). 빌드 결과: `ui-tooltip`·`ui-menu`·`ui-toast`·`ui-tabs`·`ui-data-table`·`ui-switch`·`ui-radio-group` 문자열이 초기 청크 `design-system-*.js`에 있고 `ui-gallery-page-*.js`에는 없다. R1: barrel 전체 31,142 B vs 예제 밖에서 쓰는 export만 27,263 B(gzip -9, react·router·zod 외부 처리). 초기 JS 203,521 B / 예산 204,800 B(`config/performance/budgets.json:4`). 영역 15는 "lazy 라우트 전용 **모듈**이 초기 청크에 들어온 것은 0 B"라고 했다(`15-performance.md` 0절). 모듈 단위로는 맞다. 이 항목은 그 모듈 안의 **export** 단위 비용이다 | +| 발생 조건 | 템플릿 그대로. 샘플 제거 뒤에도 제품의 lazy 페이지가 `Tooltip` 같은 primitive를 쓰면 그 코드는 셸의 `Drawer`와 같은 파일이라 초기 청크로 간다 | +| 영향 | 초기 JS 예산 여유(약 1.3 KB)보다 큰 코드가 첫 화면에 실린다. 제품이 lazy 화면에 primitive를 하나 더 쓸 때마다 초기 JS가 는다 | +| 심각도·우선순위 | Low · P2 — 예산이 거의 찼다(0929 FOLLOW-UP P1과 같은 지점) | +| 통제·증거 | 예산 게이트 M3(합계만 봄) · 모듈 구성 M0 · E3(빌드 결과, R1) | +| 확실성과 남은 가정 | 3.9 KB는 rolldown 단독 묶음 추정이다. 실제 Vite 청크에서의 차이는 파일을 나눈 빌드로 재야 한다 | +| 결정의 근거 | R3·5절 밖. 확인한 사실: primitive를 종류별 파일(`core`·`forms`·`overlays`·`navigation`)로 묶은 선택이다. 기록된 의도는 없다 | +| 이해 비용 | 성능을 보는 사람이 청크 이름(`design-system`)만으로는 안의 구성을 알 수 없다(영역 15의 청크 이름 문제와 같은 뿌리) | +| 최소 개선 방향 | primitive를 컴포넌트별 파일로 나눈다. `design-system/index.ts` barrel과 export 이름은 그대로 둔다(R3) | +| 대안 비교 | (A) 현 상태. (B) 컴포넌트별 파일: 공개 API 변화 없음, 파일 수 증가. (C) `manualChunks`로 갤러리 전용 코드를 분리: 빌드 설정에 이름을 박아야 하고 제품이 primitive를 쓰면 다시 맞춰야 한다. (B) | +| 단순화의 보존 조건 | `design-system/index.ts` export 목록, VD-05 재수출 파일 `components/ui/*.ts`, `.dependency-cruiser.json`의 `page-templates.tsx` 예외(`PaginationLandmarkContext`) | +| 비용·부작용 | 파일 이동 10여 개, import 경로 내부 정리 | +| 재검토 조건 | 초기 JS 예산이 넉넉해지거나(라이브러리 교체 등) 셸이 primitive를 더 쓰게 되면 | +| 완료 기준 | 템플릿 빌드에서 `ui-tooltip` 등 갤러리 전용 클래스 문자열이 초기 청크에 없다. 초기 JS가 약 3~4 KB 준다 | +| 검증 방법 | 빌드 후 문자열 검사 + `check:bundle` | + +### 08-09 접근성 기본 장치 일부를 지키는 테스트가 없다 — 변이 4종이 component 211개를 모두 통과 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21 | +| 근거 | 7.3절 표. 살아남은 변이: M3 건너뛰기 링크 대상을 `#content`로, M4 `LoadingSurface`의 `aria-live` 제거, M5 상태 화면 제목을 `

`로, M6 사이드바 랜드마크 이름 제거. e2e 쪽은 `accessibility.spec.ts`가 axe WCAG 태그만 쓴다. axe의 `skip-link` 규칙은 best-practice 태그라 돌지 않는다. 건너뛰기 링크를 누르는 e2e는 없다(grep) | +| 발생 조건 | 누군가 셸·상태 화면을 고칠 때 | +| 영향 | WCAG 2.4.1(블록 건너뛰기)의 유일한 수단이 조용히 깨질 수 있다. 로딩 상태 발표가 사라져도 모른다 | +| 심각도·우선순위 | Low · P3 — 지금 동작은 맞다(3.1절). 회귀 방지 장치의 빈 곳이다 | +| 통제·증거 | M0(해당 4개 규칙) · E2(변이 실행) | +| 확실성과 남은 가정 | component 계층 생존은 확인. 변이 빌드에서 e2e·axe를 돌리지는 않았다 | +| 결정의 근거 | 적용 제외 — 테스트 누락 | +| 이해 비용 | 필요한 범위만 | +| 최소 개선 방향 | `app-shell.test.tsx`에 건너뛰기 링크 `href`가 `main`의 `id`와 같다는 단언, `async-surface.test.tsx`에 `aria-live`, 상태 화면 제목 `heading` 역할 단언. e2e에 건너뛰기 링크 Enter 1건(3.1절의 확인을 그대로) | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 단언 4~5줄, e2e 1개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | M3~M6 변이가 각각 하나 이상의 테스트를 실패시킨다 | +| 검증 방법 | 7.3절 변이 재실행 | + +### 4.1 발견으로 올리지 않은 관찰 + +- 최종 사용자용 상태 화면 eyebrow가 HTTP 코드를 보인다("401 · 인증 필요", `catalog.ts:63,67,71`). 개발자에게는 유용하고 최종 사용자에게는 낯설다. 제품 문구 결정이다. +- 브랜드 "Frontend Skeleton"(`common.appName`)과 홈 h1 "Clean Architecture Frontend"(`route.APP_HOME.title`)가 다르다. `PRODUCT.md`가 자리표시자라고 적었다. +- 역할 없는 `div`의 `aria-label` 2곳(`home-page.tsx:44`, `ui-gallery-page.tsx:198`)은 트리에 전달되지 않는다. +- 예제 인증 화면이 세션 상태 원문(`unauthenticated`)을 보인다(`auth-example-page.tsx:20-22`). 헤더는 "로그인 전"이다. +- 홈 페이지가 디자인 시스템 `LinkButton` 대신 ``을 직접 쓴다(`home-page.tsx:68-82`). 샘플이 자기 primitive를 우회한다. +- 상태 갤러리의 `TerminalErrorSurface`는 `role="alert"`라 페이지를 열자마자 "네트워크에 연결할 수 없습니다."가 발표된다(데모 화면). + +## 5. 설계 선택 검토 (41절) + +### 5.1 라우트 이동을 `pathname + search` 변경으로 판단해 포커스·스크롤·진단을 한다 → 변경 권고(08-02) + +1. **무엇이 필요한가.** 화면이 바뀌면 키보드·스크린 리더 사용자에게 새 화면의 시작을 알려야 한다. 운영자는 라우트 이동 수를 본다. 목록 화면은 필터를 URL에 둔다(공유·뒤로 가기). +2. **지킬 성질.** 새 화면이면 포커스가 제목으로, 같은 화면의 입력이면 포커스가 그 컨트롤에 남는다(WCAG 3.2.2). 진단은 실제 화면 이동만 센다. +3. **현재 보장.** 확인한 사실: 새 pathname이면 `RouteLifecycle`이 main에, `PageHeader`가 h1에 포커스를 준다(세 엔진 확인). locale 변경은 이동이 아니다(테스트 있음). 보장하지 않는 것: 검색값만 바뀐 경우를 구분하지 않는다(E3). 기록된 의도: 문서 6.3절은 "route 성공 후"·"새 primary route"만 말한다. +4. **대안.** (A) 현 상태. (B) 기준을 라우트 ID 또는 pathname 변경으로 좁힌다. 검색값만 바뀌면 아무것도 하지 않는다. (C) 라우트 계약에 `searchChangeIsNavigation` 같은 선언을 두고 라우트별로 고른다. +5. **비용.** (A) 모든 URL 필터 화면이 포커스를 잃는다. 기능마다 우회 코드를 만든다. (B) effect 의존값 하나. 페이지 번호처럼 맨 위로 보내야 하는 화면은 그 화면이 직접 한다. (C) 계약 필드와 생성기·문서 변경, 대부분의 라우트는 같은 값을 쓴다. +6. **판단.** (B). 확인한 조건에서 검색값 변경을 이동으로 볼 라우트가 템플릿에 없다. 필요해지면 (C)를 더해도 (B)와 충돌하지 않는다. +7. **재검토 조건.** URL 검색값이 사실상 다른 화면을 고르는 라우트(탭·단계)가 생기면 (C)를 더한다. + +### 5.2 서버 상태 훅이 bound와 raw 입력을 함께 받는다 → 변경 권고(08-03) + +1. **무엇이 필요한가.** 기능의 쓰기는 멱등 키, 세션 세대 검사, 결과 불명 재사용을 받아야 한다. 테스트는 훅의 내부 규칙(동시 제출, 낙관적 레이어)을 정의 없이 시험하고 싶다. +2. **지킬 성질.** 제품 코드의 모든 쓰기는 intent를 가진다. 결과 불명 뒤 재전송은 같은 키로 나가거나, 불가능하면 그 사실이 타입이나 이름에 드러난다. +3. **현재 보장.** 확인한 사실: bound 경로는 이 성질을 지킨다(0929 E6, 샘플). raw 경로는 intent 없이 나가고 재전송이 `null`이다(E2). 막는 검사가 없다(E1). 기록된 의도: 2026-08-01 계획서 Task 3이 제거를 정했고 체크되지 않았다. +4. **대안.** (A) 현 상태. (B) raw overload를 제품 export에서 빼고 테스트 harness로 옮긴다(계획서대로). (C) raw를 남기되 이름을 `useUnsafeLocalMutation`처럼 바꾸고 lint로 `src/features`에서 금지한다. +5. **비용.** (A) 계속 짧은 쪽이 위험한 쪽이다. (B) 테스트 4파일 이전, 925줄 파일에서 분기 제거로 읽기 쉬워진다. (C) 분기는 남고 lint 규칙 하나가 는다. +6. **판단.** (B). 제품 코드에 raw 소비자가 없고, 기록된 결정도 (B)다. +7. **재검토 조건.** 서버 없는 로컬 쓰기처럼 intent가 의미 없는 쓰기가 실제로 필요해지면 (C)의 별도 이름으로 연다. + +### 5.3 좁은 화면에서 헤더 컨트롤을 숨기고 드로어에는 탐색만 둔다 → 변경 권고(08-01) + +1. **무엇이 필요한가.** 320~767px 폭에서 헤더가 한 줄에 들어가야 한다. 동시에 모든 사용자가 테마·언어·세션을 다룰 수 있어야 한다(WCAG 1.4.10). +2. **지킬 성질.** 폭이 줄어도 기능과 정보가 사라지지 않는다. 위치만 바뀐다. +3. **현재 보장.** 확인한 사실: 언어 선택·세션 버튼은 남고, 테마 선택·세션 상태·브랜드는 사라진다(`responsive.css:44-54`, 세 엔진 스크린샷). 드로어에는 탐색만 있다. 보장하지 않는 것: 사라진 기능의 대체 위치. 기록된 의도: 없음. +4. **대안.** (A) 현 상태. (B) 드로어 아래에 테마 선택과 세션 상태를 넣는다. (C) 헤더에 테마 아이콘 버튼(메뉴 형태)으로 남긴다. +5. **비용.** (A) AA 위반 유지. (B) 셸 몇 줄, 넓은 화면 변화 없음, 골든 1장. (C) 새 컴포넌트(메뉴 버튼)와 터치 영역 확보, 320px에서 헤더 공간 경쟁. +6. **판단.** (B). 가장 작은 변경으로 기능 손실을 없앤다. +7. **재검토 조건.** 셸에 계정·설정 메뉴가 생기면 테마를 그 메뉴로 옮긴다. + +## 6. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R1 | `RouteLifecycle`의 트리거를 라우트 ID·pathname 변경으로 좁힌다 | 08-02 | POP 스크롤 복원, locale 변경 비이동, 해시 대상 포커스, 상태 화면에서도 제목·포커스·진단 | +| R2 | `useApplicationQuery`·`useApplicationMutation`의 raw overload를 `tests/helpers` harness로 옮긴다 | 08-03. 925줄 파일의 `LEGACY` 분기와 `LEGACY_OPTIMISTIC_SCOPE`가 빠진다 | bound 경로 전부, 테스트 단언 수, 타입 fixture | +| R3 | `primitives/{core,forms,overlays,navigation}.tsx`를 컴포넌트별 파일로 나눈다 | 08-08. 찾기도 쉬워진다(473줄 `overlays.tsx`에 6개 컴포넌트) | `design-system/index.ts` export 목록, `components/ui/*.ts` 재수출, `PaginationLandmarkContext` 예외 | +| R4 | `application-query.ts`(925줄)를 조회·쓰기·결과 불명 채널 레지스트리로 나눈다(R2 뒤) | 쓰기 경로를 읽으려면 조회 코드를 지나야 한다 | QueryClient별 `WeakMap` 레지스트리 공유, 채널 키 규칙(`bound::::`) | +| R5 | `forwardRef` 8곳을 React 19의 `ref` prop으로 바꾼다 | 다음 메이저 대비. 코드가 짧아진다 | ref 전달 타입(`check:types:fixture:icon-button`), `displayName` | +| R6 | context 라우트 모듈을 탐색 링크 hover·focus 때 미리 받는다 | 3.5절의 직렬 왕복 2번 | 청크 실패 시 reload-once 복구(`context-route-gateway.test.tsx`) | +| R7 | 제목 수준을 상태 화면·오류 요약·Card가 같은 방법으로 받는다(prop 또는 `HeadingLevel` context) | 08-05 | 기본값 h2(상태 화면), h3(Card) | + +## 7. 성능·폴더 구조·테스트 렌즈 + +### 7.1 성능 + +| 비용 | 값 | 근거 | +|---|---|---| +| 첫 화면 JS(gzip -9, 정적 import 묶음) | 1,500 + 202,021 = 203,521 B / 예산 204,800 B | B1, manifest 계산. `check:bundle` 공식 수치는 영역 13·15 | +| 디자인 시스템이 든 초기 청크 | 216.61 kB / gzip 66.75 kB. 안에 react-router·HTTP adapter·catalog도 있다(영역 15) | B1 | +| 갤러리 전용 primitive가 초기에 실리는 양 | 약 3.9 KB gzip(추정) | 08-08, R1 | +| 라우트 페이지 청크(gzip) | 홈 0.77 KB, 플랫폼 4.11 KB, UI 2.90 KB, 상태 1.22 KB, 인증 0.80 KB, 참조 목록 0.66 KB(+ 공용 `use-reference-feature` 8.42 KB) | B1 | +| context 라우트 진입 요청 | 라우트 모듈 1개 → 페이지 청크 4개, 직렬 | P1 `waterfall*.json` | +| 렌더 | 불필요한 재렌더 원인 찾지 못함(3.5절). 측정은 하지 않음 | — | + +### 7.2 폴더 구조 + +- "디자인 시스템"이 네 폴더에 걸쳐 있다. `design-system/index.ts`가 `components/`(AsyncSurface, PageHeader, 상태 화면), `templates/`, `forms/`를 다시 내보낸다. `EmptySurface`를 찾는 사람은 `design-system/`이 아니라 `components/async-surface.tsx`를 열어야 한다. barrel이 공개 경계라 사용자는 영향이 없다. 템플릿을 고치는 사람의 탐색 비용이다. +- `components/ui/*.ts` 6개는 VD-05 롤백용 재수출이다(`.dependency-cruiser.json:73` 주석). 갈라진 사본이 아니다. 다만 presentation 내부 새 코드(`async-surface.tsx:12`, `page-templates.tsx:4`, `use-dirty-navigation-guard.tsx:4-5`)도 이 경로를 쓴다. 롤백 경로가 기본 경로처럼 쓰인다. 제거 조건이 없다. +- `presentation/adapters/query`의 `adapters`가 `src/adapters`와 다른 뜻이다. 16-05가 같은 내용을 셌다. 여기서 다시 세지 않는다. +- `examples/`와 `pages/`의 분리는 맞다. `examples/`는 지울 수 있고 i18n 검사 밖이다(08-07은 그 결과의 빈 곳). + +### 7.3 테스트 — 변이 실험 + +`node scripts/run-vitest.ts run tests/component`(34 files / 211 tests). 기준 실행 전부 통과. 부하 10~25에서 실행했고, M6 첫 실행은 10분 제한에 걸려 다시 돌렸다(부하 탓으로 보인다. 재실행은 정상 종료). 영역 10의 변이 18종과 겹치지 않게 접근성·화면 계약을 골랐다. + +| ID | 변이 | 결과 | 잡은 테스트 | +|---|---|---|---| +| M1 | `

`의 `tabIndex={-1}` 제거 | 잡힘 | `app-shell.test.tsx`, `router.test.tsx` | +| M2 | `PageHeader`가 h1에 포커스하지 않음 | 잡힘 | `app-shell`, `page-header-focus`, `router` | +| M3 | 건너뛰기 링크 `href`를 `#content`로 | **생존** | 없음(08-09) | +| M4 | `LoadingSurface`의 `aria-live` 제거 | **생존** | 없음(08-09) | +| M5 | 상태 화면 제목 `h2` → `p` | **생존** | 없음(08-05, 08-09) | +| M6 | 사이드바 `aria-label` 제거 | **생존** | 없음(08-09) | +| M7 | `TerminalErrorSurface`의 `role="alert"` 제거 | 잡힘 | `async-surface`, `form-foundation`, `render-boundary` | +| M8 | 폼 실패에 `supportReference={failure.requestId}` 추가(양성 대조) | 통과 | 0929/08-04를 고쳐도 깨지는 테스트가 없다. 지금 동작을 지키는 테스트도 없다 | + +실행 시간: 게이트 `test:component` 8s(오케스트레이터, 조용한 조건). 이 영역 전용 브라우저 검사 96개는 3 workers로 1.1분(부하 10.7). 과한 시간은 아니다. + +빈 곳: 좁은 화면 기능 유지(08-01), 검색값 변경 포커스(08-02), raw 훅 금지(08-03)는 테스트가 없다. + +### 7.4 대표 과제 (관점 4) + +과제: "URL에 필터를 둔 목록 화면을 만들 때, 필터를 바꾸면 포커스와 스크롤이 어떻게 되는지 알아내기." + +```text +문서 routing-pages-and-patterns.md 6.3절 → "route 성공 후 heading focus" ← 검색값 변경은 안 적힘 + → app-router.tsx RouteLifecycle(:161-200): effect 의존값에 search ← 코드를 읽어야 앎 + → page-header.tsx(:25-42): h1 포커스는 title 변경 때만 ← 두 파일 조합으로 결과가 정해짐 + → 결론: 포커스는
, POP이 아니면 맨 위로, route.changed +1 ← probe를 돌려야 확신 +``` + +- 필요한 지식: 두 컴포넌트의 effect 의존값, React Router의 navigation type, 진단 이벤트 의미. +- 막힌 곳: 문서에 없는 규칙(08-02). 쓰기 훅을 고를 때 어느 overload가 안전한지 이름으로 알 수 없다(08-03). +- 지난 라운드의 막힘(라우트 제목 세 곳, 보간 파라미터 우회)은 그대로다(0929/08-06, 08-03). + +## 8. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 목표·확인 통제 | 증거 | 이유·잔여 위험 | +|---|---|---|---|---|---| +| 1 | 코드 성숙도 | P | M3 / M2 | E3 | 좁은 화면 기능 손실(08-01), 제목 순서(08-05), 한국어 줄바꿈(08-06). 렌더·키보드는 세 엔진에서 정상 | +| 2 | 구조적 성숙도 | O | M3 / M3 | E2 | `check:architecture` PASS(게이트). raw 훅 사용은 구조 규칙 위반이 아니라 API 문제라 08-03으로 따로 셌다 | +| 3 | 변경 용이성 | P | M3 / M1~M3 | E1 | 0929/08-01(locale), 08-03(파라미터), 08-06(제목 세 곳) 그대로 | +| **4** | 인지 부하 | P | — | E3 | 7.4절. 검색값 포커스 규칙이 두 파일 조합에 숨어 있다(08-02). 디자인 시스템이 네 폴더에 걸쳐 있다(7.2절) | +| **5** | 위험 가시성 | P | M2 / M0~M2 | E3 | raw 쓰기 훅이 이름·타입에 위험을 드러내지 않는다(08-03). 검색값 변경의 부작용이 문서에 없다(08-02). 결과 불명 화면의 선택지 제한은 주석으로 드러난다(`async-surface.tsx:118-121`) | +| 6 | 실패 성숙도 | P | M2 / M2 | E3 | raw 경로의 재전송 no-op(08-03, E2). 0929/08-05(09-09와 같은 결함) | +| 7 | 운영 성숙도 | > | — | — | 영역 09·13 | +| **8** | 디버깅 가능성 | P | M3 / M0~M3 | E3 | 0929/08-04(폼·결과 불명 식별자 없음), 08-05 그대로. 검색값 변경이 `route.changed`를 부풀린다(08-02) | +| 9 | 유지보수 성숙도 | P | — | E1 | `application-query.ts` 925줄 이중 모드(R2·R4). 제목 크기가 정해지지 않아 제품마다 갈라질 값(08-04) | +| 10 | 테스트 성숙도 | P | M3 / M0~M3 | E2 | 변이 8종 중 3종 검출, 4종 생존(08-09). 좁은 화면 테마·검색값 포커스 테스트 없음 | +| 11 | 데이터 성숙도 | - | — | — | presentation은 저장을 소유하지 않는다 | +| 12 | 동시성 성숙도 | O | M3 / M3(bound 경로) | E2 | 중복 제출 차단·결과 불명 같은 키는 코드 변경 없음, 게이트 component 통과. raw 경로는 08-03 | +| 13 | 확장성 | > | — | — | 영역 09·15·16. 제품 primitive가 늘 때 초기 청크가 함께 커지는 점은 08-08 | +| **14** | 성능 성숙도 | P | M3 / M3(합계 예산) | E3 | 초기 JS 203.5 KB / 204.8 KB. 갤러리 전용 export 약 3.9 KB(08-08). context 라우트 직렬 요청(R6) | +| **15** | 보안 성숙도 | P | M3 / M3 | E2 | raw HTML 금지 lint(게이트 PASS), `SafeText`. 0929/08-07(폰트·CSP 안내), 08-08(`returnTo`) 그대로. raw 쓰기 훅의 멱등 키 누락은 08-03 | +| 16 | 의존성 성숙도 | > | — | — | 영역 13 | +| 17 | API / Contract 성숙도 | P | M3 / M2 | E3 | 공개 훅이 안전하지 않은 형태를 받는다(08-03). 0929/08-03, 08-08 | +| 18 | 배포 성숙도 | O | M3 / M3(화면 쪽) | E2 | 청크 복구 코드 변경 없음, 게이트 component 통과(`chunk-recovery-boundary`, `context-route-gateway`) | +| 19 | 설정 성숙도 | P | M2 / M2 | E1 | 0929/08-01, 08-08 그대로 | +| 20 | 개발자 경험 | P | — | E3 | 대표 과제의 숨은 규칙(7.4절). 샘플을 복사하면 08-02·08-03이 따라온다 | +| 21 | Guardrail 성숙도 | P | M3 / M0~M3 | E3 | UI 감사 뒤 `check:design-system` 규칙 4개 추가(유지 확인). raw 훅 금지 없음(E1), 접근성 회귀 검사 빈 곳(08-09). 0929/08-02 | +| 22 | 추상화 성숙도 | P | — | E1 | 페이지 템플릿 slot·`variant` 설계는 좋다(3.5절). 훅의 bound/raw 이중 입력(08-03), 제목 수준 API 불일치(08-05) | +| **23** | 일관성 | P | — | E3 | 제목 크기(08-04)·수준(08-05), 한국어 줄바꿈(08-06), 문서 언어(08-07), 이름 두 개(4.1절), 0929/08-06 | +| **24** | 네이밍 / 의미 성숙도 | P | — | E3 | `route.changed`가 검색값 변경에도 난다(08-02). `Legacy`가 내부 타입에만 있고 공개 시그니처에 없다(08-03). 랜드마크 이름 "사이드바"가 목적이 아니라 위치를 말한다(3.3절) | +| 25 | 조직 확장성 | P | — | E1 | 0929/08-01·08-03의 중앙 파일 그대로 | +| 26 | Ownership 성숙도 | ? | — | E1 | 수동 접근성 기록 10건 모두 `pending-manual-review`(`artifacts/tests/a11y-manual/`) | +| 27 | 삭제 가능성 | > | — | — | 영역 09·16 | +| 28 | 회복 가능성 | O | M2 / M2 | E2 | 라우트·청크·context 실패 화면의 "한 번 새로고침" 그대로(`app-router.tsx:110-114`, `chunk-recovery-boundary.tsx:137-140`) | + +## 9. 미검증 목록 + +| 무엇 | 왜 못 했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| 실제 스크린 리더 발표(로딩 끝, 세션 상태 변경, 상태 갤러리 alert) | 도구 없음 | NVDA·VoiceOver 수동 검토(U-2) | +| 브라우저의 "글자만 확대"·기본 글꼴 크기 설정 | 루트 `font-size`로 흉내 냈다. 미디어 쿼리 반응이 다르다 | 실제 브라우저 설정으로 수동 확인 | +| WebKit에서 `textarea "설명"`이 포커스 직후 뷰포트 밖 | 1회 측정. 다른 엔진은 정상 | 대기 후 재측정 | +| 변이 빌드에서 e2e·axe | 빌드·Playwright 반복 비용 | M3·M6 변이 빌드에서 `accessibility.spec.ts` 실행 | +| 실제 브라우저에서 검색값 변경 시 스크롤 | probe는 jsdom(스크롤 생략 경로) | URL 필터가 있는 화면의 e2e | +| 08-08의 실제 청크 감소량 | 파일을 나눈 빌드를 만들지 않았다 | R3 적용 브랜치 빌드 | +| 실제 모바일 기기 | 에뮬레이션만 | 기기 수동 확인 | diff --git a/docs/reviews/2026-11-01-maturity-review/09-app-core.md b/docs/reviews/2026-11-01-maturity-review/09-app-core.md new file mode 100644 index 00000000..5eacca7d --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/09-app-core.md @@ -0,0 +1,382 @@ +# 09 애플리케이션 코어·기능·조립 — 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 영역 판정(35.8): **조건부 사용 가능.** 템플릿의 틀(`AppShell` 아래 context, `http`·`telemetry` capability, 세션 기반 자격증명) 안에 들어가는 기능은 기능 디렉터리만 고쳐 설치할 수 있다. 단 기능 라우트 경로는 소유 context의 루트 아래에 둬야 하고, 이 규칙은 아무도 검사하지 않는다(09-06). 공개 API(`ANONYMOUS` 프로필)를 부르는 용도는 09-01 해결 전 사용 보류. 제품 홈·레이아웃·추가 capability·세션 밖 자격증명이 필요하면 템플릿 소유 파일을 고쳐야 한다(09-02, 09-03). + +지난 라운드(`docs/reviews/2026-09-29-maturity-review/09-app-core.md`, 기준 `af3d8e6`) 이후 이 영역의 코드는 바뀌지 않았다. `git log af3d8e6..d99301b -- src/application src/features src/bootstrap src/platform src/apps src/contexts scripts/generate-product-feature-index.ts src/presentation/routes/app-router.tsx`가 0건이다. 그래서 지난 발견 다섯 건은 모두 남아 있다. 이번 라운드는 지난 실험을 현재 커밋에서 다시 돌리고, 지난번에 보지 않은 조립 경로(context 루트와 라우트 경로, 경계의 진단, capability 전달, 선택 파일)를 새로 봤다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `d99301b`, 작업 트리 깨끗함(`.claude/`만 추적 안 됨) | +| 목적·실행 구성 | 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 영역 경로 | `src/application/`, `src/features/`, `src/bootstrap/`, `src/platform/`, `src/apps/`, `src/contexts/`. 조립 확인용으로 `scripts/generate-product-feature-index.ts`, `src/presentation/routes/app-router.tsx`의 `createRegisteredRoutes`·`ContextRouteGateway` | +| 깊게 본 관점 | 2, 3, 4, 9, 13, 22, 25, 27 | +| 읽은 코드 | `runtime-adapters.ts` 전체, `create-runtime-composition.ts`, `composition-root.ts`, `boot.tsx`, `main.tsx`, `optional-runtime-host.ts`, `server-state-generation-store.ts`, `boot-release-recovery.ts`, `create-application.ts`, `ports/in/application-api.ts`, `decide-chunk-recovery.ts`, `src/features/` 최상위 파일 전부, `reference-feature/feature-module.ts`·`context-routes.ts`, `local-draft-feature/NOT_INSTALLED`·adapters·application, `src/apps/*`, `src/contexts/*`, `src/.generated/*`, 생성기 전체, `platform/routing`·`platform/cardinality/compose-unique-record.ts`·`platform/errors/*`, `app-router.tsx` 1~72행·300~601행. 연결 확인용: `http-execution-v3.ts` 640~820행, `http-contract-bridge.ts` 60~95행, `rest-profiles.ts`, `auth-session-port.ts`, `runtime-capabilities.ts`, `product-features.ts`, `.dependency-cruiser.json`, `scripts/check-architecture.ts`, `scripts/test-sample-removal.ts`, `docs/architecture/starter-experience.md` 86~147행, `docs/architecture/optional-adapter-recipes.md` 100~190행 | +| 게이트 결과 | 오케스트레이터 실행 결과(`scratchpad/gates/summary.txt`)를 읽었다. 이 영역과 관련된 `check:architecture`, `check:types`, `test:unit`, `test:component`, `test:integration`, `test:contract`는 모두 rc=0. `test:system`은 rc=1이며 이 영역 원인인지는 보지 않았다(다른 영역 담당) | +| 이전 리뷰와 비교 | 2026-09-29 09-01~09-05를 현재 코드와 새 실행으로 다시 확인했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 | +| 다운스트림 | `../tech-log-frontend`(`chore/template-sync-v0.2.0`, `7a4e201a`, 2026-10-02)의 `src/bootstrap/runtime-adapters.ts:585-599`만 읽었다. 제품 쪽 `ANONYMOUS` 우회가 아직 있다. 다른 다운스트림 diff는 이번에 다시 뽑지 않았다 | + +### 1.1 실행한 명령과 실험 + +실험은 격리 worktree(`scratchpad/wt-09`, `d99301b`, 메인 `node_modules` 심볼릭 링크)에서 했다. worktree 안에서는 pnpm을 부르지 않았다. `check:architecture`는 pnpm 실행을 요구하므로(`scripts/check-architecture.ts:92-96`) `npm_execpath`에 `node_modules/.bin/eslint`를 직접 부르는 작은 대행 스크립트를 넣어 같은 스크립트를 돌렸다. + +| ID | 무엇 | 결과 | +|---|---|---| +| R1 | 메인 repo에서 영역 테스트: `node scripts/run-vitest.ts run tests/features tests/contract/reusable-capability/feature-adapter-composition.test.ts tests/unit/{product-features,two-feature-install-typecheck,product-feature-selection-build,runtime-adapters,feature-override-diagnostics,installed-feature-messages,product-index-entrypoints,second-api-feature-registries}.test.ts tests/scripts/generate-product-feature-index.test.ts tests/component/router.test.tsx` | **30 files / 147 tests 통과**, 6.26s (load 8.90) | +| E1 | 템플릿 fixture의 `ANONYMOUS` operation(`tests/helpers/external-contract-fixture.ts`의 `TEST_LIST_ENTITIES`)을 실제 `createRuntimeAdapters`로 실행했다. `installed-contract-contributions.ts`와 `installed-feature-adapters.ts`만 `vi.mock`으로 바꿨다. 로그인 뒤에는 scope가 `READY`가 될 때까지 기다렸다 | demo 로그아웃: `UNAUTHENTICATED`, fetch 0회. demo 로그인: `AUTH_INTEGRATION_FAILURE`/`CREDENTIAL_HEADER_NOT_ALLOWED`, fetch 0회. 외부 owner 로그인: 같은 실패, fetch 0회. owner가 받은 binding은 `{origin, method, operationId}`뿐이다. 외부 모드·owner 없음: `CREDENTIAL_OWNER_UNAVAILABLE`, fetch 0회 | +| E1c | 대조군: `attachCredentials`에 "프로필 transport가 `ANONYMOUS`면 빈 헤더로 READY" 3줄을 넣고 E1 재실행. 이어서 `tests/unit/runtime-adapters.test.ts tests/integration/http-execution-v3-auth-profile.test.ts tests/features/reference-feature` 실행 | 네 경우 모두 `SUCCESS`, fetch 1회. 관련 테스트 18 files / 96 tests 통과. 즉 지금 테스트는 버그 상태와 수정 상태를 구분하지 못한다. 수정은 원복했다 | +| E2 | 픽스처 기능(`shop-feature`, context 루트 `shop/*`)을 생성 인덱스 mock으로 설치하고 실제 `AppRouter`를 jsdom에서 렌더했다. 라우트: `SHOP_HOME`=`/`, `SHOP_CATALOG`=`/catalog`(탐색 순서 30), `SHOP_ITEMS`=`/shop/items` | 레지스트리 조립 오류 없음. `/` 경로 라우트 2개(`APP_HOME`, `SHOP_HOME`). 탐색 메뉴에 `Shop home->/`와 `Shop catalog->/catalog` 링크가 나온다. `/`는 플랫폼 홈(h1 "Clean Architecture Frontend")을 렌더한다. **`/catalog`는 `NOT_FOUND`(h1 "페이지를 찾을 수 없습니다.")를 렌더한다.** `/shop/items`만 기능 화면을 렌더한다 | +| E5 | 라우터와 같은 모양(`APP_SHELL` 아래 `*` + 같은 루트 `shop/*`를 가진 context 2개)을 `matchRoutes`로 확인 | `/shop/a`, `/shop/b/items`, `/shop` 모두 첫 context로 간다. 두 번째 context의 라우트는 닿지 않는다 | +| E6 | `needs: ["telemetry"]`만 선언한 기여를 `composeFeatureAdapterInputs`로 실행하고 `createInput`이 받은 객체의 키를 기록 | `["telemetry","http"]`. 선언하지 않은 capability도 받는다 | +| E7 | E2 픽스처에 route id가 레지스트리에 없는 context 라우트 핸들(`SHOP_ITEM`, 계약에는 없음)을 추가하고 `/shop/typo`를 렌더. `diagnostics.record` 호출을 기록 | `context-fallback-shop-context` 경계가 잡는다. 화면 지원 참조는 `local-build`(buildId)뿐이다. **진단 이벤트 0건**(`ui.render.failed`도 `route.changed`도 없음) | +| E3a | 변이: `installed-feature-contracts.ts`에 `NOT_INSTALLED` 디렉터리(`local-draft-feature`)의 값을 import해 만든 라우트를 `ROUTE_REGISTRY`에 끼웠다. `product-features.test.ts`, `feature-installation-surface.test.ts`, `installed-feature-messages.test.ts`, `feature-module.test.ts`, `check-architecture.ts`, `check-registries.ts` 실행 | 테스트 4 files / 21 tests 통과. `check:architecture` 통과. **`check:registries` 실패**(`FE-REG-ROUTE.LOCAL_DRAFTS.loadingSurface has unknown value`, runtime 행 없음). 상수 하나만 import하는 변형(`SPLICED_FEATURE_IDS`)으로 `product-feature-selection-build.test.ts`를 heavy lock 아래 돌리면 **실패**: `none` 빌드 모듈 목록에 `src/features/local-draft-feature/contracts/local-draft-contract.ts`가 남는다 | +| E3b | 변이: tech-log와 같은 모양으로 `runtime-adapters.ts`가 `local-draft-feature/application/local-draft-api.ts`를 직접 import해 `featureInputs`에 끼웠다. `tsc -p tsconfig.app.json`, `check-architecture.ts`, `check-registries.ts`, `tests/unit tests/features tests/contract` 실행 | tsc·`check:architecture`·`check:registries` 통과. **`tests/unit/product-feature-selection-build.test.ts` 실패**: `VITE_PRODUCT_FEATURES=none` 빌드의 모듈 목록에 `src/features/local-draft-feature/application/local-draft-api.ts`와 `domain/local-draft.ts`가 남는다. 나머지 187 files / 2445 tests 통과 | +| P1 | 부트 정적 그래프 크기. 같은 커밋(`d99301b`)으로 다른 영역 에이전트가 17:42에 만든 메인 `dist/.vite/manifest.json`에서 `src/bootstrap/boot.tsx`의 정적 import 폐포를 따라 gzip(레벨 9)으로 쟀다 | 폐포 12파일 202,021B. 그중 `installed-feature-contracts` 청크 1,246B, `installed-contract-contributions` 153B, `reference-feature-runtime-descriptor` 청크 25,042B(내용 대부분이 zod). 예산 판정은 13 영역 | + +E1·E3b·E6·E7 실행 중 부하는 load 10~19였다. 시간 측정은 R1만 의미가 있다. + +### 1.2 확인하지 못한 범위 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 09-01의 실제 브라우저 화면 | vitest로 조립 루트만 실행했다 | `ANONYMOUS` operation을 가진 픽스처 기능으로 빌드해 Playwright로 로그아웃·로그인 확인 | +| E3 변이가 `test:sample-removal`에서 잡히는지 | 무거운 검사라 돌리지 않았다 | 같은 변이로 실행 | +| 09-06 픽스처를 실제 파일로 설치했을 때 `check:registries`가 막는지 | 픽스처는 생성 인덱스 mock으로 설치했다. 라우트 행 governance가 경로·루트 관계를 보지 않는다는 것은 코드로만 확인했다(`scripts/check-registries.ts`에 경로 비교 없음) | `src/contexts`·`src/features`에 같은 픽스처를 파일로 두고 `check:registries`·`test:unit` 실행 | +| 09-02·09-03 제안이 실제 동기화 충돌을 줄이는지 | 설계 제안이다 | 구현 뒤 두 제품에 한 번 이식하고 템플릿 파일 diff가 0이 되는지 확인 | +| 다운스트림 diff 전체 | 이번에는 tech-log의 한 파일만 다시 읽었다 | `git diff --name-status <기준> `를 다시 뽑아 지난 라운드 6절과 비교 | + +## 2. 지난 발견 재확인 + +지난 라운드 ID 앞에 `0929-`를 붙였다. 이번 라운드의 ID는 3절 기준이다. + +| 지난 ID | 상태 | 이번 ID | 근거 | +|---|---|---|---| +| 0929-09-01 `ANONYMOUS` 요청이 전송되지 않음 (High·P1) | **남음** | 09-01 | `attachCredentials`가 여전히 프로필을 보지 않는다(`src/bootstrap/runtime-adapters.ts:501-531`). E1 재현(fetch 0회, 네 경우). tech-log는 아직 제품 쪽 우회를 가진다(제품 `src/bootstrap/runtime-adapters.ts:597-599`) | +| 0929-09-02 제품 capability·자격증명·설정 확장 지점 없음 (Medium·P1) | **남음** | 09-02 | `FeaturePlatformCapabilities`는 닫힌 type alias(`src/features/feature-adapter-contribution.ts:46-51`), capability 객체는 closure 안(`runtime-adapters.ts:592-595`), 설정 스키마에 제품 조각을 넣을 자리 없음(`src/bootstrap/runtime-config-schema.ts:19`, `:35-56`) | +| 0929-09-03 라우터가 `AppShell`과 `APP_HOME` 고정 (Medium·P1) | **남음**(일부 이동) | 09-03 | `createRegisteredRoutes`가 모든 context를 `APP_SHELL` 아래에 붙이고 플랫폼 `/`를 index로 둔다(`src/presentation/routes/app-router.tsx:530-577`). "다른 id의 `/`가 조용히 가려진다"는 부분은 원인이 더 넓어서(루트 밖 경로 전체) 09-06으로 옮겼다 | +| 0929-09-04 `NOT_INSTALLED`·생성기 밖 조립을 아무 검사도 구분 못 함 (Medium·P2) | **바뀜** — 검출 부분 정정 | 09-04 (Low·P3) | 코드는 같다. 지난번 E3는 테스트 3개와 `check:architecture`만 돌렸다. 이번에 게이트를 넓혀 돌리니 라우트 splice는 `check:registries`가(E3a), 부트스트랩 직접 import는 `test:unit`의 `product-feature-selection-build.test.ts`가(E3b) 잡았다. `check:architecture`는 둘 다 놓친다. 남은 것은 `NOT_INSTALLED`의 다의성과 졸업 경로 부재다 | +| 0929-09-05 선택 파일에 템플릿 설명과 제품 상수가 섞임 (Low·P3) | **남음** | 09-05 | `src/features/installed-runtime-capabilities.ts:16-41` 그대로 | +| FOLLOW-UP(09-25) 09-07: 기능 제거 검증이 lint·`check:i18n`·e2e를 건너뜀 | **남음** | — (지난 판정 유지, 새 항목 아님) | 제거 검증 목록에 lint·i18n·e2e 없음(`scripts/test-sample-removal.ts:413-428`) | +| FOLLOW-UP(09-25) 09-08: local-draft ABA를 주석으로 닫음 | **남음**(리뷰가 허용한 대안) | — | `src/features/local-draft-feature/domain/local-draft.ts:2-11` | + +## 3. 발견 사항 (36.3) + +요약: High 1 · Medium 3 · Low 5. P1 3 · P2 2 · P3 4. 이월 5건(09-01~09-05), 새 발견 4건(09-06~09-09). + +### 09-01 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 어떤 세션 상태에서도 전송되지 않는다 (이월: 0929-09-01) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 17, 6, 5, 8, 10, 3, 30.5 (HTTP 실행 쪽은 03 영역과 겹침) | +| 근거 | 템플릿은 `ANONYMOUS` 프로필을 설치하고(`src/contracts/rest-profiles.ts:68-74`), 익명 프로필은 자격증명 헤더를 하나도 허용하지 않는다(`:159-168`). `auth: "none"` operation은 이 프로필이어야 한다(`:297`). executor는 모든 operation에서 `attachCredentials`를 부르고 `authProfileId`를 넘긴다(`src/adapters/http/http-execution-v3.ts:719-724`). 조립 루트 구현은 그 값을 쓰지 않고 세션만 본다. 로그아웃이면 `UNAUTHENTICATED`(`src/bootstrap/runtime-adapters.ts:509-511`), 로그인이면 세션 헤더를 붙이고 bridge가 거절한다(`src/adapters/http/http-contract-bridge.ts:80-85`). owner에게 넘기는 binding에도 프로필이 없다(`src/application/ports/auth-session-port.ts:36-40`, `runtime-adapters.ts:513-520`). **E1**: 네 경우 모두 fetch 0회. **E1c**: 3줄 수정으로 네 경우 모두 fetch 1회, 관련 테스트 96개 그대로 통과 | +| 발생 조건 | 제품이 공개 API(`auth: "none"`) operation을 V3 경로로 설치 | +| 영향 | 그 기능은 어느 세션 상태에서도 요청을 보내지 못한다. fail-closed라 정보 노출은 없다. 실패 이유가 "허용되지 않은 자격증명 헤더"라 원인(프로필 무시)과 멀다 | +| 심각도·우선순위 | High · P1 — 템플릿이 지원한다고 설치한 프로필이 기본 조립에서 동작하지 않는다. 공개 화면은 흔한 요구다. 실제 제품 1곳이 이 결함 때문에 모든 공개 화면이 실패했고, 지금도 제품 쪽 우회를 들고 있다 | +| 통제·증거 | 목표 M3(조립 루트 경유 테스트) / 확인 M0 · E2(E1, E1c) + 다운스트림 코드(E1) | +| 확실성과 남은 가정 | 네 세션 상태를 모두 재현했다. 브라우저 화면은 보지 않았다 | +| 결정의 근거 | 적용 제외 — 계약(`rest-profiles.ts:159-168`)이 이미 정해져 있고 조립 루트가 지키지 않는 구현 결함이다. 확장 구조는 09-02에서 다룬다 | +| 이해 비용 | 원인을 찾으려면 executor·bridge·조립 루트 세 파일을 함께 읽어야 한다 | +| 최소 개선 방향 | `attachCredentials`에서 scope 확인 바로 다음에 `INSTALLED_REST_AUTH_PROFILES.get(operation.authProfileId)?.transport === "ANONYMOUS"`면 세션을 보지 않고 `{ kind: "READY", headers: {} }`를 돌려준다. E1c와 tech-log 제품 수정이 같은 모양이다 | +| 대안 비교 | 적용 제외 — 계약이 정해져 있다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 3줄. 로그인 상태의 익명 호출에 토큰이 붙지 않는 것이 의도된 결과다. 인증 통합이 실패한 상태(`integration-failed`)에서도 공개 읽기가 나간다(E1c). 이것도 계약과 맞다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 실제 `createRuntimeAdapters`로 `ANONYMOUS` operation을 로그아웃·로그인·외부 owner 상태에서 실행하면 fetch 1회, 자격증명 헤더 없음 | +| 검증 방법 | `tests/unit/runtime-adapters.test.ts`에 E1과 같은 케이스 추가. 수정 전 코드에서 실패하는지 먼저 확인 | +| 담당·기한·상태 | 미정 · 미정 · 이월(2회째) | + +### 09-02 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어 제품이 `runtime-adapters.ts`를 직접 고쳐야 한다 (이월: 0929-09-02) + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(지난 라운드에 다운스트림 diff 2건으로 발생 확인) | +| 관련 관점 | 3, 9, 25, 22, 15, 19, 20, 13, 30.3, 30.4, 30.7 | +| 근거 | 코드가 지난 라운드와 같다. capability 타입은 닫힌 alias다(`src/features/feature-adapter-contribution.ts:46-51`). IndexedDB 저장소만 확장 가능한 interface다(`:14`). capability 객체와 자격증명 판단은 637줄 `createRuntimeAdapters` 안 closure다(`src/bootstrap/runtime-adapters.ts:501-531`, `:592-595`). 런타임 설정은 템플릿 스키마를 그대로 쓴다(`src/bootstrap/runtime-config-schema.ts:19`). 문서는 이 파일을 `indexedDb`일 때만 고친다고 적는다(`docs/architecture/starter-experience.md:143`). 다운스트림 근거(memento +61줄, tech-log +118줄)는 지난 라운드 6절 자료다. 이번에는 tech-log 우회 하나만 다시 확인했다(1절) | +| 발생 조건 | 제품이 `http`·`telemetry`·`indexedDb` 밖의 capability, 세션 owner 밖 자격증명(쿠키 CSRF·BFF), 제품 런타임 설정 키 중 하나라도 필요 | +| 영향 | 템플릿 수정(보안·계약 포함)이 들어오는 파일을 제품도 고친 상태가 된다. 동기화마다 fail-closed 코드를 손으로 병합한다 | +| 심각도·우선순위 | Medium · P1 — 템플릿 자체의 기능 실패는 아니다. 제품을 더 늘리기 전에 해결할 항목이다. 지난 판정 유지 | +| 통제·증거 | 목표 M2(제품 소유 확장 파일 + 가드) / 확인 M0 · E1(현재 코드) + E3(지난 라운드 다운스트림 diff) | +| 확실성과 남은 가정 | 구조는 현재 코드로 재확인했다. 다음 동기화 충돌 수는 추정이다 | +| 결정의 근거 | 4.2절. 확인한 사실: 위 근거. 기록된 의도: `indexedDb`만 opt-in으로 제품이 추가(`runtime-adapters.ts:586-591`). 리뷰어 추론: fence 순서를 한 함수가 쥐는 것은 맞다. 제품 확장 방법이 그 함수 수정뿐인 것은 30.3에 어긋난다 | +| 이해 비용 | 제품 개발자는 capability 하나를 추가하려고 조립 루트 전체(scope fence, 세션, 텔레메트리 수명)를 읽는다 | +| 최소 개선 방향 | 4.2의 (B). (1) `FeaturePlatformCapabilities`를 확장 가능한 interface로 바꾼다. (2) 템플릿이 빈 구현으로 내보내는 제품 소유 파일 하나가 추가 capability와 "프로필 id → 자격증명 제공자"를 돌려준다. (3) `attachCredentials`는 fence → `ANONYMOUS`(09-01) → 등록 제공자 → 세션 순서를 템플릿이 쥔다. (4) 제품 설정 키는 제품 소유 zod 조각을 strict 스키마에 합친다 | +| 대안 비교 | 4.2절 | +| 단순화의 보존 조건 | 인증 요청을 익명으로 낮추지 않는다. scope 전환 중에는 보내지 않는다. 프로필 허용 헤더만 나간다. 제공자가 예외를 던지면 `CREDENTIAL_OWNER_FAILED`로 닫힌다 | +| 비용·부작용 | 템플릿 수십 줄 + 분기 테스트. 두 제품은 한 번 이행한다 | +| 재검토 조건 | 제품이 fence 순서 자체를 바꿔야 하는 요구(요청별 테넌트 전환)가 생기면 제공자 계약을 다시 본다 | +| 완료 기준 | 두 제품의 현재 요구(offsetUpload, runtime 값, BFF 쿠키 XSRF, Studio CSRF, 제품 설정 키)를 템플릿 파일 수정 없이 표현한다 | +| 검증 방법 | 픽스처 제품 파일로 capability 1개·프로필 제공자 1개를 추가하고 `check:types`·`runtime-adapters` 테스트 통과. 제공자가 fence 전에 불리지 않는지 순서 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 이월(2회째) | + +### 09-03 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해 기능이 `/`나 자기 레이아웃을 가질 수 없다 (이월: 0929-09-03) + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 3, 2, 22, 25, 23, 32.4, 30.3 | +| 근거 | `APP_HOME`은 플랫폼 소유다(`src/contracts/routes.ts:20-32`). 라우터는 플랫폼 라우트와 모든 context gateway를 `APP_SHELL` 하나 아래에 붙이고 플랫폼 `/`를 index 라우트로 만든다(`src/presentation/routes/app-router.tsx:530-577`). gateway는 leaf 하나만 렌더하고 context 라우트의 레이아웃 `Component`를 쓰지 않는다(`:500-528`). 기능이 같은 id `APP_HOME`을 선언하면 `composeUniqueRecord`가 throw한다(`src/platform/cardinality/compose-unique-record.ts:16-18`). E2: 다른 id로 `/`를 선언하면 플랫폼 홈이 렌더된다 | +| 발생 조건 | 제품 홈이 기능 화면이거나 기능 화면이 `AppShell`이 아닌 자기 레이아웃을 쓴다. 지난 라운드 기준 두 제품 모두 해당 | +| 영향 | 제품마다 템플릿 라우터·조립 카탈로그에 브리지를 넣고 동기화마다 병합한다. 한 제품(tech-log)은 라우터를 통째로 바꿔 생성기 설치 경로(context gateway)를 쓸 수 없다(지난 라운드 자료) | +| 심각도·우선순위 | Medium · P1 — 지난 판정 유지 | +| 통제·증거 | 목표 M3(선언 + 조립 검증) / 확인 M0 · E2(E2 실험) + E3(지난 라운드 다운스트림 diff) | +| 확실성과 남은 가정 | 조립·렌더 동작은 실험으로 확인했다 | +| 결정의 근거 | 지난 문서 4.3절을 그대로 쓴다. 이번 라운드는 루트 밖 경로 문제를 09-06으로 분리했다. 홈 대체·레이아웃 선언은 여전히 계약이 없다 | +| 이해 비용 | 제품 개발자는 라우터 내부(gateway 매칭, 플랫폼 index 우선순위)를 알아야 브리지를 만든다 | +| 최소 개선 방향 | 지난 문서 4.3 (B). 플랫폼이 "기능이 대신할 수 있는 라우트 id"(`APP_HOME`)를 선언하고 소유 기능은 최대 하나로 제한한다. context가 선택적 레이아웃을 선언하면 라우터가 그 context를 레이아웃 아래 붙인다 | +| 대안 비교 | 지난 문서 4.3절. (A) 현 상태: 제품마다 브리지. (C) `AppShell` 통째 교체: 레이아웃 그룹이 둘인 제품을 못 담는다 | +| 단순화의 보존 조건 | context 라우트는 늦게 읽힌다. 경계·청크 복구·not-found가 레이아웃 context에도 적용된다. 플랫폼 라우트는 기능을 꺼도 남는다 | +| 비용·부작용 | 라우터 수십~백 줄, 테스트 | +| 재검토 조건 | 세 번째 제품이 레이아웃 외 라우터 변형을 요구하면 선언 형태를 다시 본다 | +| 완료 기준 | memento의 두 브리지와 tech-log의 PUBLIC/STUDIO 구성을 템플릿 라우터 수정 없이 선언으로 표현한다 | +| 검증 방법 | 픽스처 context 2개(자기 레이아웃, `APP_HOME` 대체)를 설치한 컴포넌트 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 이월(2회째) | + +### 09-04 `NOT_INSTALLED` 표시가 여러 뜻으로 쓰이고, 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없다 (이월·재판정: 0929-09-04, Medium·P2 → Low·P3) + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(이름과 졸업 경로) | +| 관련 관점 | 24, 2, 21, 27, 4, 30.7 | +| 근거 | 생성기는 `NOT_INSTALLED` 파일의 존재만 보고 내용은 읽지 않는다(`scripts/generate-product-feature-index.ts:283-294`). 같은 단어가 런타임 상태 "선언됐지만 선택 안 됨"으로도 쓰인다(`src/contracts/product-features.ts:32`, `:121-122`). 표시 파일은 "아키텍처 샘플"이라고 적는다(`src/features/local-draft-feature/NOT_INSTALLED`). **정정**: 직접 조립은 게이트가 잡는다. E3a(라우트 splice)는 `check:registries`와 `product-feature-selection-build.test.ts:99`가, E3b(부트스트랩 직접 import)는 `product-feature-selection-build.test.ts:99`가 잡았다. 둘 다 `check:architecture`는 통과했다. `.dependency-cruiser.json`에는 `src/bootstrap`·`src/features/installed-*`에서 `src/features//`로 가는 간선을 막는 규칙이 없다 | +| 발생 조건 | 제품 도메인이 템플릿 틀(09-02, 09-03)에 안 맞아 생성기 밖에서 조립 | +| 영향 | 우회한 제품은 `product-feature-selection-build.test.ts`를 고쳐야 게이트를 통과한다(지난 라운드: tech-log가 이 테스트를 TechLog 예외로 고침). 그러면 유일한 검출 장치가 제품 쪽에서 꺼진다. `NOT_INSTALLED`를 볼 때마다 파일 내용과 조립 파일을 함께 읽어야 뜻을 안다 | +| 심각도·우선순위 | Low · P3 — 지난번 Medium의 근거였던 "아무 검사도 못 잡음"이 사실이 아니었다. 남은 것은 이름과 졸업 경로이고, 원인의 큰 부분은 09-02·09-03이다 | +| 통제·증거 | 직접 조립 검출: M3(느린 빌드 테스트, 실행 2.8s) / 이름 구분: M0 · E2(E3a, E3b) | +| 확실성과 남은 가정 | 카탈로그 splice(E3a 변형)와 부트스트랩 직접 import(E3b) 모두 selection build 테스트가 잡았다. 런타임에 동적으로 값을 끼우는 방식(빌드 모듈 목록에 안 남는 경우)은 시험하지 않았다 | +| 결정의 근거 | 지난 문서 4.1절. 리뷰어 추론: 검출은 충분하다. 검출 메시지가 원인을 직접 말하지 않는다("expected [...] to deeply equal []" + 모듈 경로) | +| 이해 비용 | 작다. 실패 메시지에 모듈 경로가 나온다 | +| 최소 개선 방향 | (1) 표시 이름을 뜻대로 나눈다(샘플은 `NOT_A_FEATURE` 같은 이름). (2) `feature-module.ts`와 표시가 함께 있으면 생성기가 실패한다. (3) 원하면 `check:architecture`에 `src/(bootstrap|features/installed-)` → `src/features/[^/]+/` 금지 규칙을 더해 빠른 게이트에서 먼저 잡는다 | +| 대안 비교 | (A) 현 상태: 느린 빌드 테스트만 잡는다. (B) 의존성 규칙 추가: 몇 줄, 빠르다. 단 tech-log 같은 제품은 규칙도 고쳐야 한다. (C) 09-02·09-03으로 모든 도메인을 `feature-module.ts`에 담는다: 근본 해결, 선행 작업 큼 | +| 단순화의 보존 조건 | 생성기 설치 기능의 선택·킬스위치·제거 검증은 그대로다. 표시 없는 디렉터리는 계속 실패한다 | +| 비용·부작용 | 생성기 몇 줄, 표시 파일 이름 변경 | +| 재검토 조건 | 모든 제품 도메인이 `feature-module.ts`로 옮겨지면 닫는다 | +| 완료 기준 | 표시 이름이 하나의 뜻만 가진다. 표시 + `feature-module.ts` 동시 존재가 생성 단계에서 실패한다 | +| 검증 방법 | 동시 존재 픽스처로 생성기 실패 확인 | +| 담당·기한·상태 | 미정 · 미정 · 이월(재판정) | + +### 09-05 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다 (이월: 0929-09-05) + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 9, 25, 30.3 | +| 근거 | `src/features/installed-runtime-capabilities.ts:16-20`이 "여기 추가하면 설치된다"고 제품 수정 지점을 선언하고, 같은 블록 `:22-33`이 "Current template state"를 설명하고, `:35-41`이 제품 상수다. 코드가 지난 라운드와 같다 | +| 발생 조건 | 템플릿이 선택 설명 주석이나 기본값을 고침 | +| 영향 | 제품이 의도대로 쓴 파일인데도 동기화에서 주석 충돌이 난다 | +| 심각도·우선순위 | Low · P3 — 지난 판정 유지 | +| 통제·증거 | 목표 M1 / 확인 M1 · E1 | +| 확실성과 남은 가정 | 실제 충돌 수는 보지 않았다 | +| 결정의 근거 | 적용 제외 — 파일 배치의 작은 정리다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | 템플릿 상태 설명을 `docs/architecture/optional-adapter-recipes.md`로 옮기고 파일에는 "이 상수는 제품이 소유한다" 한 줄만 둔다. 09-07의 주석 정정과 함께 한다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 주석 이동 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 제품이 상수만 바꿔도 템플릿 설명 변경과 줄이 겹치지 않는다 | +| 검증 방법 | 문서 확인 | +| 담당·기한·상태 | 미정 · 미정 · 이월(2회째) | + +### 09-06 기능 라우트 경로와 소유 context 루트의 관계를 아무도 검사하지 않아, 루트 밖 라우트가 탐색 메뉴에는 나오고 URL은 `NOT_FOUND`가 된다 (새 발견) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(조립 검증 누락) | +| 관련 관점 | 21, 4, 5, 8, 1, 13, 17, 20, 32.4 | +| 근거 | 라우터는 context마다 gateway 하나를 그 context의 루트 경로(`CONTEXT_ROUTE_PATH`)에 붙인다(`src/presentation/routes/app-router.tsx:549-563`, `src/platform/routing/context-route-module.ts:36-54`). 기능 라우트는 그 gateway 안에서만 렌더된다(`app-router.tsx:500-528`). 그런데 기능 라우트는 레지스트리와 탐색 메뉴에 경로와 무관하게 들어간다(`src/features/installed-feature-contracts.ts:23-29`, `:109-113`). 생성기는 같은 context 안 기능들의 루트가 같은지만 본다(`scripts/generate-product-feature-index.ts:67-78`). context끼리 루트가 겹치는지, 라우트 경로가 루트 아래인지, context 라우트 핸들의 route id가 레지스트리에 있는지는 어디서도 보지 않는다. 게이트 스크립트에 경로와 루트를 비교하는 코드가 없다(`scripts/` grep). 문서도 이 규칙을 적지 않는다. "owning context loads this file only when its route root is visited"라는 설명뿐이다(`docs/architecture/starter-experience.md:122-125`). **E2**: 루트 `shop/*` context의 `/catalog` 라우트가 탐색 메뉴 링크로 나오고, 그 URL은 `NOT_FOUND`를 렌더한다. 오류·경고는 없다. `/` 라우트도 같은 이유로 가려진다. **E5**: 루트가 같은 context가 둘이면 두 번째 context 전체가 닿지 않는다(생성기는 context를 id 순으로 정렬하므로 id가 늦은 쪽이 사라진다). **E7**: 핸들 route id가 레지스트리에 없으면 context 경계 실패 화면이 된다(진단 문제는 09-09) | +| 발생 조건 | 기능 작성자가 라우트 경로를 context 루트 밖에 두거나(오타, 루트 변경 후 경로 미수정, 제품 홈을 `/`로), 새 context가 기존 루트를 다시 쓰거나, `context-routes.ts`를 계약과 다르게 손으로 쓴다 | +| 영향 | 사용자는 메뉴 링크를 눌러 "페이지를 찾을 수 없습니다"를 본다. 개발자는 라우트 계약·codec·런타임을 다 맞췄는데 화면이 안 나오는 원인을 라우터 내부(gateway 매칭)까지 읽어야 찾는다. 같은 루트를 쓰는 context는 통째로 사라진다 | +| 심각도·우선순위 | Medium · P2 — 데이터 피해는 없고 개발 중 화면을 열면 드러난다. 그러나 기능 추가의 주 경로에서 계약 위반이 조용히 통과하고, 규칙이 코드에도 문서에도 없다. 검사 비용은 몇 줄이다 | +| 통제·증거 | 목표 M3(조립 시 throw 또는 생성 단계 실패) / 확인 M0 · E2(E2, E5, E7) | +| 확실성과 남은 가정 | 렌더 결과는 jsdom에서 확인했다. 실제 파일로 설치했을 때 `check:registries`가 막는지는 돌리지 않았다(1.2절). 코드상 경로·루트 비교는 없다 | +| 결정의 근거 | 4.3절. 확인한 사실: 루트 하나에 gateway 하나를 붙이는 구조가 context 단위 지연 로딩과 경계를 준다. 기록된 의도: context 라우트는 루트 방문 시에만 읽힌다(`starter-experience.md:122-125`). 리뷰어 추론: 구조는 유지할 근거가 있다. 빠진 것은 그 구조가 기대는 불변식("기능 라우트 경로 ⊂ 소유 context 루트, 루트는 context마다 하나")의 검사다 | +| 이해 비용 | 기능 작성자는 "라우트 경로는 소유 context 루트 아래"라는 적히지 않은 규칙을 기억해야 한다 | +| 최소 개선 방향 | 조립 카탈로그 한 곳(`installed-feature-contracts.ts` 옆이나 생성기)에서 세 가지를 검사하고 실패하면 throw한다. (1) 기능의 모든 라우트 경로가 소유 context 루트와 맞는다(루트 `shop/*`이면 `/shop` 또는 `/shop/...`). (2) context 루트가 서로 겹치지 않는다. (3) 생성기가 쓴 context 인덱스와 기능 계약의 라우트 id가 같다. (3)은 `context-routes.ts`를 eager로 읽지 않도록 "계약 라우트에서 `FEATURE_CONTEXT_ROUTES`를 만든다"는 reference 방식을 헬퍼로 제공하는 쪽이 싸다 | +| 대안 비교 | (A) 현 상태: 비용 0, 조용한 실패. (B) 조립 시 검사(위): 몇십 줄, 모듈 평가 시 throw하므로 부트 실패 화면과 테스트로 드러난다. 기능 라우트 정보는 이미 eager 그래프에 있어 번들 비용이 없다. (C) 생성기에서 검사: 더 일찍 실패하지만 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 알 수 없다. 라우트 경로 검사는 (B), 루트 중복 검사는 (C)가 맞다. (D) 루트를 없애고 모든 기능 라우트를 React Router `lazy` 라우트로 평평하게 등록: 루트 규칙 자체가 사라지지만 context 단위 경계·청크·이 템플릿의 gateway 테스트를 다시 만들어야 한다 | +| 단순화의 보존 조건 | context 라우트 모듈은 계속 늦게 읽힌다(검사가 `context-routes.ts`를 import하면 안 된다). 모르는 URL은 `NOT_FOUND`로 간다. 플랫폼 라우트는 검사 대상이 아니다 | +| 비용·부작용 | 검사 몇십 줄 + 실패 픽스처 테스트 3개. 제품 홈을 기능이 가지려는 제품은 지금보다 빨리 실패한다(09-03 해결 전까지는 그게 맞다) | +| 재검토 조건 | 09-03이 홈 대체 선언을 열면 `APP_HOME` 대체 라우트를 (1)의 예외로 둔다 | +| 완료 기준 | E2의 `/catalog`, E5의 같은 루트, E7의 미등록 핸들이 각각 모듈 평가 또는 생성 단계에서 기능 id·라우트 id·루트를 담은 메시지로 실패한다 | +| 검증 방법 | E2·E5·E7 픽스처를 테스트로 옮겨 실패를 확인한다. reference 기능은 그대로 통과한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 09-07 선택 파일은 "여기 추가하면 설치된다"고 하지만 realtime·webWorkers·offlineCommands는 아무것도 시작되지 않고, 진단 스냅샷은 active로 보고한다 (새 발견) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(주석·진단이 실제 동작과 다름) | +| 관련 관점 | 5, 7, 22, 20, 30.2 (realtime 런타임 자체는 04 영역, SW는 06 영역) | +| 근거 | 선택 파일: "Adding an entry here is what installs a capability"(`src/features/installed-runtime-capabilities.ts:16-20`). optional host는 realtime·webWorkers·offlineCommands를 타입부터 `null`로 고정하고(`src/bootstrap/optional-runtime-host.ts:22-26`, `:151-155`), 시작 순서에서 SW 말고는 아무것도 만들지 않는다(`:86-123`). 선택만 하면 health가 `UNAVAILABLE`로 남는다(`:68-73`). 반면 플랫폼 개요가 읽는 스냅샷은 선택 수를 그대로 `active`로 센다(`src/contracts/runtime-capabilities.ts:313-349`, `src/bootstrap/runtime-adapters.ts:441-448`). 플랫폼 개요는 `active`가 1 이상이면 "활성 (n)"을 성공 표시로 보인다(`src/presentation/examples/platform-overview-page.tsx:223-226`, `:304`). 문서는 realtime에 "현재 concrete runtime과 product selection은 없다"고 적고(`docs/architecture/optional-adapter-recipes.md:186-188`), composition root가 adapter를 주입하라고 한다(같은 문서 4절 7) | +| 발생 조건 | 제품이 선택 파일 주석을 믿고 `REALTIME`·`WEB_WORKERS`·`OFFLINE_COMMANDS`에 항목을 넣는다 | +| 영향 | 기능은 동작하지 않는데 플랫폼 개요는 "활성 (1)"을 보인다. 경고나 실패가 없다. SW는 실제로 시작되므로 네 capability가 같은 파일·같은 주석 아래 서로 다르게 동작한다 | +| 심각도·우선순위 | Low · P3 — 운영 데이터 피해는 없다. 제품 개발 중 기능이 안 도는 것으로 드러난다. 수정 비용이 작다 | +| 통제·증거 | 목표 M3(선택했는데 시작할 수단이 없으면 조립 시 실패) / 확인 M0 · E1(정적 확인) | +| 확실성과 남은 가정 | realtime 기여를 실제로 넣어 실행하지는 않았다. host에 realtime 시작 코드가 없다는 것은 파일 전체를 읽어 확인했다 | +| 결정의 근거 | 적용 제외 — 주석과 진단이 동작과 다른 결함이다. 런타임을 조립할지는 04·06 영역 판단이다 | +| 이해 비용 | 제품 개발자는 선택 파일, optional host, 레시피 문서 세 곳을 읽어야 "SW만 자동"이라는 사실을 안다 | +| 최소 개선 방향 | (1) 선택 파일 주석을 "SW만 여기서 설치된다. 나머지는 composition에 런타임을 연결해야 한다"로 고친다. (2) `createOptionalRuntimeHost`가 시작 수단이 없는 capability가 선택돼 있으면 throw한다. 부트 실패 화면으로 드러난다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄. 런타임을 연결한 제품은 host 확장과 함께 이 검사를 바꾼다(09-02의 확장 지점과 같은 자리) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | realtime 기여 하나를 선택한 픽스처가 조립 단계에서 원인을 말하며 실패한다 | +| 검증 방법 | `tests/unit`에 그 픽스처 테스트 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 09-08 기능이 선언한 capability만 받는다는 설명은 타입에서만 지켜지고, 실행 시에는 capability 객체 전체가 전달된다 (새 발견) + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안(주석과 실행이 다름) | +| 관련 관점 | 22, 5, 2 | +| 근거 | 조립 루트 주석: "Each installed contribution receives only the capabilities it declares"(`src/bootstrap/runtime-adapters.ts:586`). 실제로는 `composeFeatureAdapterInputs`가 받은 context 전체를 그대로 넘긴다(`src/features/feature-adapter-contribution.ts:136-144`, `:192-198`). **E6**: `needs: ["telemetry"]` 기여가 `["telemetry","http"]`를 받았다 | +| 발생 조건 | 기능 코드가 cast로 선언하지 않은 capability를 쓴다 | +| 영향 | 그 기능은 지금은 동작한다. 그 capability를 쓰는 다른 기능이 빠지거나 제품이 capability를 줄이면 그때 깨진다. `needs`가 실제 의존을 다 말하지 않게 된다 | +| 심각도·우선순위 | Low · P3 — cast가 필요해서 실수로 일어나기 어렵다 | +| 통제·증거 | 타입 경계 M4(cast 없이는 막힘) / 실행 경계 M0 · E2(E6) | +| 확실성과 남은 가정 | 실제로 cast하는 기능은 repo에 없다 | +| 결정의 근거 | 적용 제외 — 주석이 약속한 동작을 실행이 지키지 않는 작은 차이다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | `invokeContribution`에서 `needs`에 있는 키만 골라 새 frozen 객체로 넘긴다. 또는 주석을 "타입이 선언한 capability만 보인다"로 고친다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 누락 capability 오류 메시지(`feature-adapter-contribution.ts:186-189`), 중복 기여 오류, featureId 불일치 오류, 호출부 타입 추론은 그대로다 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E6이 `["telemetry"]`만 기록한다 | +| 검증 방법 | E6을 `tests/contract/reusable-capability/feature-adapter-composition.test.ts`에 추가 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 09-09 context·feature 오류 경계가 잡은 실패를 진단에 남기지 않고, 지원 참조로 buildId만 보인다 (새 발견) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 7, 23 (라우터 배선은 08 영역과 겹침) | +| 근거 | `ScopedErrorBoundary`는 `onError`를 받으면 보고한다(`src/platform/errors/scoped-error-boundary.tsx:35-43`). gateway는 `ContextErrorBoundary`·`FeatureErrorBoundary`에 `onError`를 넘기지 않고 fallback의 지원 참조로 buildId만 준다(`src/presentation/routes/app-router.tsx:466-472`, `:519-525`). 안쪽 `RenderErrorBoundary`는 incident id를 만들고 `ui.render.failed`를 남긴다(`src/presentation/boundaries/render-error-boundary.tsx:38-56`). 그래서 안쪽 경계 밖에서 난 실패(라우트 정의 조회, 경로 해석, 비활성·주소 오류 화면 렌더)는 바깥 경계로 올라가 아무 기록도 남기지 않는다. **E7**: 미등록 핸들 id로 `context-fallback-shop-context`가 렌더되고, 지원 참조는 `local-build`, 진단 이벤트 0건 | +| 발생 조건 | gateway의 `RegisteredRoute`·`RouteSurface`에서 안쪽 경계 전에 예외가 난다. 09-06 (3)의 핸들 불일치가 대표 경우다 | +| 영향 | 사용자 화면의 지원 참조로 이벤트를 찾을 수 없다. 운영에서는 이 실패가 일어났다는 사실 자체가 수집되지 않는다 | +| 심각도·우선순위 | Low · P2 — 닿는 경로가 좁다(대부분 조립 실수). 그러나 바깥 경계는 설계상 "다음 escalation"(`src/platform/errors/feature-error-boundary.tsx:8-11`)이고, 거기서 흔적이 없어진다. 수정이 작다 | +| 통제·증거 | 목표 M2(모든 경계가 같은 보고 경로) / 확인 M0 · E2(E7) | +| 확실성과 남은 가정 | 실제 브라우저 콘솔에는 React 오류가 남는다. 수집 경로로는 가지 않는다 | +| 결정의 근거 | 적용 제외 — 이미 있는 `onError`를 연결하지 않은 배선 누락이다. 경계 두 계열을 합칠지는 리팩토링 후보 R4 | +| 이해 비용 | 이름이 비슷한 경계 두 계열(`FeatureErrorBoundary` / `FeatureBoundary`)을 둘 다 알아야 어떤 실패가 기록되는지 안다 | +| 최소 개선 방향 | gateway가 두 경계에 `onError`를 넘겨 `reportRenderFailure`를 부르고, fallback 지원 참조에 incident id를 붙인다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | E7에서 `ui.render.failed` 1건이 남고 화면 지원 참조가 `:` 형식이다 | +| 검증 방법 | E7을 컴포넌트 테스트로 옮긴다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 설계 선택 검토 (41절) + +### 4.1 조립 카탈로그(`installed-*`)를 생성 인덱스의 투영으로만 두고, 직접 조립은 빌드 결과로 검출한다 + +1. **무엇이 필요한가.** 기능이 늘어도 중앙 파일을 고치지 않는다. 빌드 선택(`VITE_PRODUCT_FEATURES`)과 런타임 킬스위치가 모든 소비자에게 같게 적용된다. +2. **지킬 성질.** 설치된 기능 집합은 생성 인덱스 하나에서 나온다. 키 중복은 부트 전에 실패한다. 선택에서 빠진 기능의 코드는 번들에 없다. +3. **현재 보장.** 확인한 사실: 카탈로그는 `INSTALLED_PRODUCT_FEATURE_*`만 투영한다(`installed-feature-contracts.ts:17-29`, `installed-feature-adapters.ts:11-19`). 정적 테스트가 매니페스트 import를 확인한다(`tests/unit/product-features.test.ts:169-209`). `none` 빌드 테스트가 dist 모듈 목록에 기능 모듈이 없는지 본다(`tests/unit/product-feature-selection-build.test.ts:35`, `:99`). E3a·E3b에서 이 두 장치와 `check:registries`가 직접 조립을 잡았다. 보장하지 않는 것: 빠른 게이트(`check:architecture`)에서의 검출. 틀 밖 요구(09-02, 09-03)를 표현하는 방법. +4. **대안.** (A) 현 상태. (B) 의존성 규칙으로 `src/bootstrap`·`installed-*` → `src/features//` 간선을 막는다. (C) 제품 소유 조립 파일 하나를 열고 그 파일만 예외로 둔다(지난 문서 4.1 (B)). +5. **비용 비교.** (A) 비용 0. 검출은 되지만 2.8s짜리 빌드 테스트에서만, 원인 대신 모듈 경로로 알린다. (B) 규칙 몇 줄, 빠르고 메시지가 직접적이다. 우회하는 제품은 규칙도 고친다. (C) 파일 1개 + 규칙 예외. 우회가 파일 이름으로 드러나고 템플릿 테스트를 고칠 필요가 없어진다. +6. **현재 조건에서의 판단.** 투영 구조와 빌드 검출은 유지할 근거가 있다. 지난 라운드가 "검출 없음"이라고 본 것은 실행 범위가 좁았기 때문이다. 바꿀 것은 검출을 앞당기는 것(B)과, 틀 밖 요구의 자리(09-02, 09-03)다. +7. **재검토 조건.** 두 제품이 모두 `feature-module.ts`로 옮기면 (C)는 필요 없다. 빌드 테스트가 느려져 게이트에서 빠지면 (B)가 필수가 된다. + +### 4.2 `createRuntimeAdapters` 한 함수가 capability 객체와 자격증명 정책을 만든다 + +지난 문서 4.2절의 비교가 그대로 유효하다. 코드가 같다. 이번에 더한 사실만 적는다. + +- E1c: 3줄 분기로 `ANONYMOUS`가 동작하고 기존 테스트 96개가 그대로 통과한다. 즉 이 함수의 판단 순서를 고정하는 테스트가 없다. 확장 지점(4.2 (B))을 만들 때 순서 테스트를 먼저 써야 한다. +- 순서는 이렇게 고정하는 것이 맞다: scope fence → 프로필 transport(`ANONYMOUS`) → 제품 등록 제공자 → 세션 → patch 후 scope fence 재확인. 지금은 2·3단계가 없다. +- 재검토 조건(추가): 이 함수의 테스트가 판단 순서를 표로 고정하면 (B)의 제공자 계약을 작게 유지할 수 있다. + +### 4.3 context마다 루트 경로 하나에 gateway 하나를 붙이고, 기능 라우트는 그 안에서만 매칭한다 + +1. **무엇이 필요한가.** 기능 라우트 코드는 그 context를 방문할 때만 내려받는다. context·feature 단위로 실패를 가둔다. 모르는 URL은 `NOT_FOUND`로 간다. +2. **지킬 성질.** 기능 라우트 경로는 소유 context 루트 아래에 있다. 루트는 context마다 하나이고 겹치지 않는다. context 라우트 핸들은 레지스트리의 라우트를 가리킨다. +3. **현재 보장.** 확인한 사실: gateway는 루트에 붙고(`app-router.tsx:549-563`), 라우트 모듈을 한 번만 읽어 캐시한다(`context-route-module.ts:10-34`). 실패는 context 경계와 청크 복구로 간다(`app-router.tsx:475-497`). 보장하지 않는 것: 2의 세 성질 전부(09-06, E2·E5·E7). 기록된 의도: "the owning context loads this file only when its route root is visited"(`starter-experience.md:122-125`). +4. **대안.** (A) 현 상태. (B) 구조 유지 + 조립 시 세 성질 검사(09-06). (C) 루트 없이 모든 기능 라우트를 React Router `lazy`로 평평하게 등록. (D) 루트를 기능 라우트 경로의 공통 접두어로 자동 계산. +5. **비용 비교.** (A) 비용 0, 조용한 실패. (B) 몇십 줄, 번들 비용 0(라우트 정의는 이미 eager). (C) 루트 규칙이 없어지지만 context 경계·context 단위 청크·gateway 테스트를 다시 만든다. 라우트 수만큼 lazy 경계가 생긴다. (D) 선언 하나가 줄지만, 공통 접두어가 `/`가 되는 기능(제품 홈)이 모든 URL을 먹는다. 의도가 코드에서 사라진다. +6. **현재 조건에서의 판단.** (B). 구조가 주는 지연 로딩·경계는 실제로 동작한다(R1 `installed-context-routing.test.ts`, `router.test.tsx` 통과). 빠진 것은 구조가 기대는 불변식의 검사뿐이다. +7. **재검토 조건.** 09-03이 레이아웃 선언을 열면 "레이아웃 아래 여러 루트"를 2의 성질에 반영한다. 한 context가 서로 다른 루트 둘을 가져야 하는 제품이 나오면 루트를 목록으로 바꾸는 것을 비교한다. + +## 5. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R1 | `attachCredentials` closure를 bootstrap 안 별도 함수(예: `createCredentialAttacher({ scope, session, profiles, apiOrigin })`)로 꺼낸다 | 09-01 수정 자리이자 09-02 확장 자리다. 지금은 637줄 함수 안에 있어 판단 순서를 단독으로 테스트할 수 없다(E1c가 기존 테스트로 구분되지 않음) | patch 전후 두 번의 scope fence, 비익명 프로필은 세션 없으면 `UNAUTHENTICATED`(익명으로 낮추지 않음), owner 예외 → `UNAVAILABLE`, `CredentialPatchOutcome` 종류, 03-07 규칙(상태 코드 없는 `UNAUTHENTICATED`는 텔레메트리 아님, `runtime-adapters.ts:289-295`) | +| R2 | context 루트·라우트 경로·핸들 id 검사를 조립 카탈로그 한 곳에 모은다 | 09-06. 지금은 같은 context 안 루트 일치만 생성기가 본다 | `context-routes.ts`는 eager로 읽지 않는다. 모르는 URL은 `NOT_FOUND`. 검사 실패는 모듈 평가 시 throw해 부트 실패 화면으로 간다(`main.tsx:14-17`) | +| R3 | `composeFeatureAdapterInputs`가 `needs`의 키만 골라 넘긴다 | 09-08 | 누락 capability·중복 기여·featureId 불일치 오류 메시지, 호출부 타입 추론, 비활성 기능은 입력을 받지 않음(`feature-adapter-contribution.ts:176`) | +| R4 | 오류 경계 두 계열(`platform/errors/ScopedErrorBoundary`, `presentation/boundaries/RenderErrorBoundary`)을 하나의 보고 계약으로 맞춘다. 최소는 바깥 경계에 `onError` 연결 | 09-09. 이름이 비슷하고(`FeatureErrorBoundary`/`FeatureBoundary`) 한쪽만 보고한다 | 범위 밖 형제는 계속 렌더, 내비게이션 시 reset, 보고 실패가 렌더 실패로 번지지 않음, incident id가 화면과 진단에 같게 나감 | +| R5 | optional host가 시작 수단이 없는 선택 capability를 거절한다 | 09-07 | §3.4 시작 순서, SW 경로(시작·정지·텔레메트리) 그대로, host 생성은 부작용 없음 | + +16 영역과 겹치지 않게 구조 의견은 아래 6.2에 짧게만 둔다. + +## 6. 추가 렌즈 + +### 6.1 성능 + +| 비용 | 값 | 판단 | +|---|---|---| +| 영역 테스트 실행 시간 | R1 30 files / 147 tests 6.26s (load 8.90). 게이트 로그에서 무거운 셋: `product-feature-selection-build` 2.8s, `two-feature-install-typecheck` 2.4s, `second-api-feature-registries` 1.2s | 과하지 않다. 빌드·tsc를 띄우는 세 테스트가 직접 조립 검출(4.1)과 기능 2개 typecheck를 맡으므로 값어치가 있다 | +| 부트 정적 그래프에 들어가는 조립 코드 | `installed-feature-contracts` 청크 1,246B gz, `installed-contract-contributions` 153B gz(P1) | 작다 | +| 부트 정적 그래프에 들어가는 기능 설명자 | `reference-feature-runtime-descriptor` 청크 25,042B gz. 내용 대부분이 zod다. 설치 기능의 런타임 설명자(route codec)가 `installed-feature-runtimes.tsx`를 거쳐 eager로 들어가면서 zod 공용 청크가 이 이름을 받았다 | 기능 수가 늘면 설명자·계약·메시지가 함께 eager로 는다(지난 FOLLOW-UP P1과 같은 구조). 예산 판정과 청크 이름 문제는 13 영역 | +| 요청 수·메모리 | 조립 루트는 부트 시 1회. 요청마다 `attachCredentials`가 동기 검사 몇 개를 한다 | 해당 없음 | + +### 6.2 폴더 구조 (짧게, 깊은 판단은 16 영역) + +- `src/features/installed-*.ts`는 제품 조립인데 기능 디렉터리들과 같은 폴더에 있다. 의존성 규칙 주석도 "assembly를 bootstrap으로 올리면 다시 본다"고 적는다(`.dependency-cruiser.json:229-230`). +- `src/apps/template-app.ts`(선택된 앱의 런타임 모듈)와 `src/apps/template-app/app-module.ts`(템플릿 앱 선언)가 같은 이름을 쓴다. `TEMPLATE_APP_MODULE`에는 실제로 선택된 아무 앱이나 들어간다(`src/apps/template-app.ts:10-14`). +- `src/platform/cardinality/growth-regression.ts`, `topology-capacity.ts`는 `src`에서 import하는 곳이 없고 `scripts/scale`·`tests`만 쓴다. 런타임 코드가 아니라 측정 도구다. +- 오류 경계가 `src/platform/errors/`와 `src/presentation/boundaries/` 두 곳에 있다(R4). + +### 6.3 테스트 + +| 위험 | 지금 테스트가 잡는가 | 근거 | +|---|---|---| +| `ANONYMOUS` 미전송(09-01) | 못 잡는다. 버그 상태와 수정 상태 모두 통과 | E1, E1c | +| 직접 조립(09-04) | 잡는다. `product-feature-selection-build.test.ts`(빌드에 남는 모든 import, E3a·E3b 둘 다), `check:registries`(라우트 행, E3a). `check:architecture`는 못 잡는다 | E3a, E3b | +| 루트 밖 라우트·같은 루트·미등록 핸들(09-06) | 못 잡는다 | E2, E5, E7 | +| 바깥 경계 진단 누락(09-09) | 못 잡는다. `tests/platform/errors/failure-boundary.test.tsx`는 `onError` 없이 경계만 본다 | E7 | +| 선언하지 않은 capability 사용(09-08) | 타입만 잡는다 | E6 | + +추가로, `tests/unit/product-features.test.ts:212-215`는 "설치된 모든 기능이 라우트를 하나 이상 가진다"를 단언한다. `FeatureModule` 타입은 라우트 없는 기능을 허용하고(`src/features/feature-module.ts:10-28`), 템플릿 자신의 typecheck 픽스처도 라우트 없는 기능을 설치한다(`tests/unit/two-feature-install-typecheck.test.ts:20-68`). 라우트 없는 기능을 넣은 제품은 이 템플릿 테스트를 고쳐야 한다. 지난 라운드 6절의 "템플릿 테스트가 템플릿 내용을 기대값으로 쓴다"와 같은 종류다(테스트 설계 판정은 10 영역). + +## 7. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가 + +| 번호 | 관점 | 판정 | 근거·잔여 위험 | +|---|---|---|---| +| 1 | 코드 성숙도 | P | 조립 검증(중복 id·needs·예산)은 모듈 평가 시 throw한다(R1 통과). context 루트·라우트 경로·핸들 정합성 검증이 없다(09-06) | +| 2 | 구조적 성숙도 | P | 부트스트랩은 `installed-*`만 import한다. 기능 내부 직접 import를 빠른 게이트는 못 잡고 빌드 테스트가 잡는다(09-04, E3b). 경계 두 계열(R4) | +| 3 | 변경 용이성 | X | 실제 제품 기준. 홈·레이아웃·capability·세션 밖 자격증명·제품 설정에 템플릿 파일 수정이 필요하다(09-02, 09-03). 코드가 지난 라운드와 같다 | +| 4 | 인지 부하 | P | 기능 작성자는 선언 3종과 `defineFeatureModule`만 알면 된다. 그러나 "라우트 경로 ⊂ context 루트"를 기억해야 하고 문서에 없다(09-06). `NOT_INSTALLED` 다의(09-04) | +| 5 | 위험 가시성 | P | `attachCredentials`가 프로필을 보지 않는 사실이 호출부에서 안 보인다(09-01). 주석 두 곳이 동작과 다르다(09-07, 09-08) | +| 6 | 실패 성숙도 | P | 모듈 평가 실패도 부트 실패 화면으로 간다(`main.tsx:14-17`). `ANONYMOUS`는 안전한 방향으로 실패하지만 기능이 전혀 동작하지 않는다(09-01) | +| 7 | 운영 성숙도 | P | 모르는 `FEATURE_OVERRIDES` 키를 진단으로 남긴다(`runtime-adapters.ts:462-471`). 바깥 경계 실패는 수집되지 않는다(09-09). capability 스냅샷이 시작 안 된 런타임을 active로 센다(09-07) | +| 8 | 디버깅 가능성 | P | 조립 오류는 키·기능·파일 이름을 담는다. 루트 밖 라우트는 신호 없이 `NOT_FOUND`(09-06). 바깥 경계는 incident id 없이 buildId만 보인다(09-09). `CREDENTIAL_HEADER_NOT_ALLOWED`는 원인과 멀다(09-01) | +| 9 | 유지보수 성숙도 | P | 지난 라운드 이후 이 영역 코드 변경 0건이라 지난 다섯 건이 그대로 남았다. 이월 2회째 항목이 셋이다(09-01~09-03) | +| 10 | 테스트 성숙도 | P | 영역 테스트 147개 통과(R1). 직접 조립은 잡는다(E3). 09-01·09-06·09-09는 잡지 못한다(6.3) | +| 11 | 데이터 성숙도 | P | local-draft ABA는 주석으로만 막는다(`local-draft.ts:2-11`). 샘플 범위라 영향이 작다 | +| 12 | 동시성 성숙도 | > | scope fence는 03 영역. 이 영역의 `attachCredentials`는 patch 전후로 scope를 두 번 확인한다(`runtime-adapters.ts:502-504`, `:521-523`) | +| 13 | 확장성 | P | 기능 수 축: 2개 설치 typecheck(2.4s)와 context·app 예산이 있다. context 수 축: 같은 루트 충돌을 검사하지 않는다(09-06, E5). 제품 수 축: 09-02, 09-03 | +| 14 | 성능 성숙도 | > | 13 영역. 이 영역 수치는 6.1 | +| 15 | 보안 성숙도 | P | demo 인증 차단·외부 owner fail-closed는 유지된다(E1). 자격증명 정책을 넓힐 방법이 closure 수정뿐이라 제품이 fail-closed 코드를 손으로 병합한다(09-02) | +| 16 | 의존성 성숙도 | - | 이 영역 고유 의존성 없음 | +| 17 | API / Contract 성숙도 | P | 템플릿이 설치한 `ANONYMOUS` 프로필 계약을 조립 루트가 지키지 않는다. owner binding에 프로필이 없다(09-01) | +| 18 | 배포 성숙도 | > | 13 영역 | +| 19 | 설정 성숙도 | P | `VITE_PRODUCT_FEATURES`는 생성기 한 곳에서 적용된다. 제품 런타임 설정 키를 넣을 자리가 없다(09-02) | +| 20 | 개발자 경험 | P | 기능 추가 안내가 생성기 규칙과 맞는다(`starter-experience.md:86-147`). 라우트 경로·루트 규칙이 빠졌다(09-06). 선택 파일 주석이 셋에는 틀렸다(09-07) | +| 21 | Guardrail 성숙도 | P | 표시 없는 디렉터리·needs 누락·키 중복·예산 초과·직접 조립은 막힌다. 루트 밖 경로·같은 루트·미등록 핸들은 막히지 않는다(09-06) | +| 22 | 추상화 성숙도 | P | `FeatureModule` 제네릭은 호출부에서 추론된다. `FeaturePlatformCapabilities`는 닫힌 alias(09-02). `needs` 좁히기는 타입에서만(09-08). optional host가 세 capability를 `null` 타입으로 고정(09-07) | +| 23 | 일관성 | P | interface/alias 불일치(09-02). 경계 두 계열 중 한쪽만 보고(09-09). 같은 선택 파일의 네 capability가 서로 다르게 동작(09-07) | +| 24 | 네이밍 / 의미 성숙도 | P | `NOT_INSTALLED` 다의(09-04). `TEMPLATE_APP_MODULE`·`template-app.ts`가 선택된 아무 앱을 가리킨다(6.2) | +| 25 | 조직 확장성 | X | 구조 근거(09-02, 09-03)는 현재 코드로 재확인했다. 두 제품이 같은 템플릿 파일을 고친 근거는 지난 라운드 다운스트림 diff다. 이번에는 tech-log 우회 하나만 다시 확인했다 | +| 26 | Ownership 성숙도 | > | 파일별 템플릿/제품 소유 표는 14 영역 | +| 27 | 삭제 가능성 | P | 생성기 설치 기능은 `--feature=`로 제거를 검증한다. 제거 검증은 lint·`check:i18n`·e2e를 건너뛴다(`scripts/test-sample-removal.ts:413-428`). 생성기 밖 조립은 제거 경로가 없다(09-04) | +| 28 | 회복 가능성 | P | 부트 실패 화면에 재시도가 있다(`boot.tsx:56-58`). reload 반복은 TTL guard가 막는다(`release-mismatch-recovery.ts`, `decide-chunk-recovery.ts:39-54`). 부트 실패 후 자동 회복은 의도적으로 없다 | + +집계(판정한 23개): 충족 0 · 부분 충족 21 · 미충족 2(3, 25) · 미검증 0. 적용 제외 1(16), 다른 영역 4(12, 14, 18, 26). 지난 라운드의 유일한 O(1번)는 09-06 때문에 P로 내렸다. diff --git a/docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md b/docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md new file mode 100644 index 00000000..a1449297 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/10-tests-fast-layers.md @@ -0,0 +1,376 @@ +# 10 테스트 — 빠른 계층 성숙도 리뷰 (2026-11-01) + +> 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` · 체크리스트: `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 영역 판정(35.8): **조건부 사용 가능**. 개발 장비에서는 빠른 계층을 믿을 수 있다. 1코어 조건에서는 머지 게이트가 코드와 무관하게 떨어진다(지난 10-01, 이번에 5회 중 5회 재현). CI를 켜기(U-1) 전에 지난 10-01을 고친다. + +## 요약 + +- **지난 라운드 뒤로 이 영역의 테스트와 대상 코드는 바뀌지 않았다.** `af3d8e6..d99301b`에서 빠른 계층의 변경은 `tests/unit/oklch-contrast.test.ts` 추가와 `design-system-platform.test.tsx`의 단언 1개뿐이다. 지난 발견 5건(10-01~10-05)은 모두 남아 있다. +- **부하 의존 실패를 다시 재현했다(지난 10-01).** 1코어로 묶고 worker 4개로 돌리면 5회 모두 실패했다. 실패한 테스트는 4종이다. 그중 2종은 지난 라운드 목록에 없던 테스트다(`reference-production-vertical.test.tsx:102-104`, `router.test.tsx:244-250`). 2코어에서는 10회 모두 통과했다. 이번 호스트 부하(3~10)는 지난 라운드(8~23)보다 낮았다. CPU 제한 없이 전체 빠른 계층을 돌린 실행(부하 18)에서도 guardian 350ms 테스트가 한 번 실패했다. +- **검출력은 대체로 높지만 새 빈 곳이 셋 있다.** 변이 18종 중 13종을 잡았다. 살아남은 5종은 이렇다. 실행기 §10.8 검사(지난 10-04, 그대로), 이벤트 계약 검증 2종(10-01), 보호 라우트의 세션 복구 분기(10-03), Popover의 Escape 포커스 반환(10-02). 뒤의 넷은 이번에 새로 찾았다. +- **아무것도 단언하지 않고 통과하는 테스트가 1개 있다(10-01).** 모든 테스트에 `expect.hasAssertions()`를 걸고 3,108개를 돌렸다. `contract-registry-immutability.test.ts:322-335`는 fixture에 이벤트가 0개라서 첫 줄에서 return한다. 이름은 "정확하지 않은 이벤트 계약을 거부한다"이다. 실제로 이벤트 계약의 snapshot 검사(M17)와 내용 검증(M18)을 통째로 꺼도 관련 96파일 766개가 모두 통과했다. +- **`it.skip`·`it.todo`를 막는 장치가 없다(10-04).** `CI=true`에서도 skip·todo가 섞인 파일은 종료 코드 0으로 통과했다. `.only`는 Vitest 기본값 덕분에 CI에서만 막힌다. +- **느리게 만드는 원인은 몇 곳에 몰려 있다.** 빠른 계층 테스트 2,790개 중 22개(0.8%)가 합산 테스트 시간의 47%를 쓴다. `tests/unit`의 도구(scripts) 테스트 39파일이 unit 합산 시간의 58%를 쓴다(10-05). 실제 시계로 고정 상수를 기다리는 테스트가 약 14초를 쓴다(10-07). 머지 단계는 빠른 계층 파일 대부분을 두 번 돌린다(10-06). 전역 setup은 DOM이 없는 unit 163파일에도 React Testing Library를 읽는다(리팩토링 R1). + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `tests/unit`(166 테스트 파일, 약 68.5k줄), `tests/component`(34), `tests/integration`(13), `tests/contract`(3), `tests/runtime-schema`(3), `tests/features`(19), `tests/platform`(29), `tests/recipes`(3), `tests/helpers`(8), `tests/mocks`(5), `tests/support`(1, Playwright 전용), `vitest.config.ts`, `tests/setup.ts`, `scripts/run-vitest.ts` | +| 커밋·상태 | `d99301b`. 주 워킹트리에서 쓴 파일은 이 문서 하나다 | +| 전제 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. Vitest 4.1.10, Node 24, `@testing-library/dom` 10.4.1(`asyncUtilTimeout` 기본 1,000ms) | +| 읽은 코드·설정 | 위 설정 3개 전체. `package.json` 테스트 스크립트, `config/ci/gates.json`의 FE-GATE-004~007·010·020과 job 구성, `scripts/scale/run-scale-profile.ts:30-120`, `scripts/run-http-scenario-evidence.ts`, `scripts/test-sample-removal.ts:40-96`, `config/ci/ungated-tests.json`. 지난 발견의 근거 파일 전부. 변이 대상 코드 17곳. 느린 테스트 상위 22개와 그 대상 상수 | +| 읽은 문서(주장으로만) | `docs/testing/taxonomy.md`, 지난 리뷰 `2026-09-29-maturity-review/10-tests-fast-layers.md`·README | +| 게이트 결과 | 오케스트레이터 실행(이 커밋): `test:unit` 165파일 2,353개, `test:component` 34파일 211개, `test:integration` 13파일 155개, `test:contract` 3파일 15개, `test:runtime-schema` 3파일 56개 모두 rc=0. 다시 돌리지 않았다. junit(`artifacts/tests/*.xml`, 17:23)을 읽어 테스트별 시간을 뽑았다 | +| 실행한 실험 | 분리 worktree(`git worktree add --detach /wt-10 d99301b`, 메인 `node_modules` 심볼릭 링크)에서 `node scripts/run-vitest.ts`만 썼다. pnpm은 쓰지 않았다. CPU를 쓰는 실행은 모두 `flock heavy.lock`으로 감쌌다. 메인 `node_modules`의 `.modules.yaml`·`.pnpm/lock.yaml` 수정 시각은 2026-09-29 16:26 그대로다 | +| 확인하지 못한 것 | 실제 Gitea 러너(U-1)의 코어 수와 실패율. 조용한 호스트에서의 2코어 결과. jsdom과 실제 브라우저의 차이(11 영역). 실행 시간의 정밀 측정(15 영역) | +| 지난 리뷰와 비교 | 지난 결과는 증거로 쓰지 않았다. 지난 발견은 현재 코드와 이번 실행으로 다시 확인했다(2절) | + +### 1.1 실험 P1 — 부하 재현 + +대상: `tests/component tests/features tests/integration`(66파일, 441개), `--maxWorkers=4`. 호스트는 22코어다. 다른 영역 에이전트가 함께 돌았다. 각 실행 직전 1분 부하 평균을 적었다. + +| 실험 | 조건 | 결과 | +|---|---|---| +| B | 2코어(`taskset -c 0-1`) × 5회, 부하 3.0~9.2 | 5회 모두 통과(38~51s) | +| C2 | 2코어 × 5회, junit 기록, 부하 7.9~9.9 | 5회 모두 통과 | +| C1 | 1코어(`taskset -c 0`) × 5회, 부하 9.2~16.8 | **5회 모두 실패**, 회당 1~2개(72~120s) | +| P-A | CPU 제한 없음, 빠른 계층 8개 디렉터리 전체, 부하 18.2 | guardian 350ms 테스트 1개 실패 | + +C1에서 실패한 테스트: + +| 테스트 | 실패 횟수 | 실패 문구 | 원인 | +|---|---|---|---| +| `provider-guardian-transaction.test.ts:689-717` "expires an uncommitted lease…" | 2/5 (+ P-A 1회) | `deadline guardian READY timed out` | 자식 기동 시간이 350ms lease에 들어간다(`:704`) | +| `reference-production-vertical.test.tsx:102-104` | 1/5 | `Unable to find role="button" and name "로그인 시작"` | 지연 로딩 화면을 1초 기본값으로 기다린다 | +| `router.test.tsx:235-252` "focuses the route heading again…" | 1/5 | `Unable to find role="heading" and name "화면 상태"` | 같은 원인. 반복문 안에서 기본 `findByRole`·`waitFor`를 세 번 쓴다 | +| `http-execution-v3-live-authority.test.ts:357` "does not wait for a non-cooperative fetch…" | 2/5 | `expected 'CONTRACT_VIOLATION' to be 'TRANSPORT_FAILURE'` | 테스트 문제가 아니다. 실행기가 마감을 두 번 읽는다(지난 10-03) | + +여유 시간도 적었다. "allows exactly one same-kind guardian"(`provider-guardian-transaction.test.ts:619`)은 2코어에서 5.17~5.30s, 1코어에서 5.34~6.74s 걸렸다. 테스트 제한은 10s다. "traverses bootstrap, router…"는 2코어에서도 1.85~2.17s다. + +### 1.2 실험 P2 — 변이 + +worktree에서 원본을 고친 뒤 `node scripts/run-vitest.ts related <대상> --run`을 돌리고 원본을 되돌렸다. 마지막에 `git status`가 깨끗한 것을 확인했다. + +| ID | 지키는 규칙 | 바꾼 곳 | 결과 | 잡은 테스트 | +|---|---|---|---|---| +| M01 | 오래된 scope의 성공 응답은 버린다(§10.8) | `http-execution-v3.ts:1377` 조건을 `false`로 | **살아남음** (84파일 631개 통과) | 없음 — 지난 10-04 그대로 | +| M02 | 조회 실행 뒤 scope를 다시 확인한다 | `application-query.ts:112` 조건을 `false`로 | 잡힘 (1) | `application-query-scope-fence.test.tsx:58` | +| M03 | M01 + M02 동시 | 두 곳 모두 | 잡힘 (1) | 위와 같은 1개. 실행기 쪽 방어선은 여전히 아무도 보지 않는다 | +| M04 | 자동 새로고침은 키와 무관하게 TTL당 1회(Q-6.9-9) | `release-mismatch-recovery.ts:84`에 `previous.key === key &&` 추가 | 잡힘 (4, 3파일) | `release-mismatch-recovery.test.ts` 2, `chunk-recovery.test.ts` 1, `tests/release/mixed-replica.test.ts` 1 | +| M05 | 저장된 marker만 새로고침을 허가한다 | `release-mismatch-recovery.ts:94`를 항상 `"reload-once"`로 | 잡힘 (1) | `release-mismatch-recovery.test.ts` "fails closed without working storage" | +| M06 | 로컬이 아닌 endpoint는 https만 | `release-artifacts.ts:19` 조건 제거 | 잡힘 (2) | `deployment-admission.test.ts` 1, `runbook-drill.test.ts` 1 | +| M07 | manifest URL은 자기 자신으로 풀려야 한다(R-7.3) | `release-artifacts.ts:44`의 `pathname === value` 제거 | 잡힘 (2) | `runtime-config.test.ts`의 `%2e` 두 경우 | +| M08 | 같은 sequence는 STALE | `browser-cross-context-invalidation.ts:498` `<=`→`<` | 잡힘 (1) | `cross-tab-invalidation.test.ts` | +| M09 | 자기 echo는 버린다 | `:470` 조건을 `false &&`로 | 잡힘 (1) | `cross-tab-invalidation.test.ts` | +| M10 | 세션 복구 중인 보호 라우트는 "복구 대기"를 보인다 | `navigation-policy.ts:21` `wait-for-session`→`show-sign-in` | **살아남음** (14파일 81개 통과) | 없음 — 10-03 | +| M11 | redirect hop 상한 | `navigation-policy.ts:33` `>=`→`>` | 잡힘 (1) | `navigation-policy.test.ts` | +| M12 | 스트림 본문 바이트 상한 경계 | `bounded-body-reader.ts:86` `> max`→`> max + 1` | 잡힘 (1) | `bounded-body-reader.test.ts` | +| M13 | 레거시 client는 멱등이 아닌 요청을 재시도하지 않는다 | `retry-policy.ts:60`을 `return true` | 잡힘 (9) | `http-client.test.ts` 6, `retry-policy.test.ts` 2, `runbook-drill.test.ts` 1 | +| M14 | oklch 휘도 계산(UI-01 새 코드) | `oklch-contrast.ts:30` b 계수 부호 | 잡힘 (1) | `oklch-contrast.test.ts` "matches the ratio the browser measured…" | +| M15 | Popover는 Escape 뒤 포커스를 trigger로 돌려준다 | `overlays.tsx:74` `triggerRef.current?.focus()` 제거 | **살아남음** (23파일 150개 통과) | 없음 — 10-02 | +| M16 | 페이지 제목이 사용자의 포커스를 빼앗지 않는다 | `page-header.tsx:33` 줄 제거 | 잡힘 (2) | `page-header-focus.test.tsx`, `router.test.tsx` | +| M17 | 이벤트 계약 snapshot은 정확한 own data만 받는다(LIVE-03) | `external-contract-runtime.ts:664` snapshot을 건너뛰고 입력을 그대로 반환 | **살아남음** (96파일 766개 통과) | 없음 — 10-01 | +| M18 | 설치된 이벤트 계약의 `eventType`·validator를 검증한다 | `external-contract-runtime.ts:824` `assertEventContract` 호출 제거 | **살아남음** (96파일 766개 통과) | 없음 — 10-01 | + +M06·M13을 잡은 테스트 중 `runbook-drill.test.ts`는 우연이다. 이 테스트는 로컬 빌드의 판정을 보는데, 변이가 그 경로의 부수 결과를 바꿨다. 같은 변이를 규칙의 이름을 단 테스트도 잡았으므로 결론은 같다. + +### 1.3 실험 P3 — 단언 없는 테스트, skip·only, setup 비용 + +| ID | 방법 | 결과 | +|---|---|---| +| P-A | worktree의 `tests/setup.ts`에 `beforeEach(() => expect.hasAssertions())`를 넣고 빠른 계층 8개 디렉터리 전체(269파일 3,108개) 실행 | 단언 0개로 실패 2개. `recipes/browser-file-storage-contracts.test.ts:256`은 `expectTypeOf`만 쓴다. 이 파일은 `tsconfig.test.json`의 `tests/**`에 들어가 `check:types:test`(FE-GATE-003)가 검사하므로 문제가 아니다. `unit/contract-registry-immutability.test.ts:322`은 실제로 아무것도 검사하지 않는다(10-01). 나머지 1개 실패는 부하에 의한 guardian 실패다 | +| P-B | `it.skip`·`it.todo`가 든 파일과 `it.only`가 든 파일을 만들어 실행 | skip+todo, `CI=true`: 종료 코드 0, "1 passed, 1 skipped, 1 todo". `.only`, `CI=true`: 종료 코드 1, "Unexpected .only modifier". `.only`, CI 없음: 종료 코드 0, 나머지 테스트는 조용히 건너뜀 | +| P-C | `tests/setup.ts`를 "DOM이 있을 때만 jest-dom·RTL을 읽는" 판으로 바꾸고 `tests/unit`을 4코어로 3회씩 | setup 누적 시간 27~37s → 2~4s. 벽시계 29~36s → 22~39s. 부하가 14~23으로 흔들려 벽시계 차이는 믿기 어렵다. 2,353개 모두 통과 | + +## 2. 지난 발견 재확인 + +| 지난 ID | 상태 | 근거 | +|---|---|---| +| 10-01 실행 속도에 기대는 테스트 (Medium · P1) | **남음 — 범위 넓어짐** | 원인 코드 그대로: 전역 대기 설정 없음(`tests/setup.ts:1-11`), 홈 h1을 1초 기본값으로 대기(`runtime-application.test.tsx:64-68`), 350ms 실제 시계 lease(`provider-guardian-transaction.test.ts:704`), 5초 응답 제한을 그대로 대기(`:619`, `scripts/lib/provider-guardian-client.ts:22`), 절대 시간 예산(`extreme-scale-registry.test.ts:17-20`, `:78`). P1에서 1코어 5/5 실패. 새로 실패한 테스트 2종(1.1절). 이 영역에서 실제 시계 마감은 두 파일에만 있다: `Date.now() + N`은 guardian 파일에만, `performance.now()`와 `toBeLessThan`은 extreme-scale 파일에만 있다. 나머지 원인은 지연 로딩 대기다. 239개 `findBy*`·`waitFor` 중 시간 지정은 12개뿐이다. 추가 사실: `extreme-scale-registry.test.ts`는 `test:coverage`뿐 아니라 같은 FE-GATE-005의 `check:scale:pr`에서도 돈다. pr tier가 `tests/platform/cardinality` 전체를 돌리기 때문이다(`run-scale-profile.ts:41-43`). `ungated-tests.json`과 `ci-workflow-generation.test.ts:224`는 pr tier를 "CPU-independent"라고 부르지만, 이 파일은 1,500ms·3,000ms 벽시계 예산을 쓴다 | +| 10-02 플랫폼 테스트가 스타터 화면·참조 샘플을 대상으로 씀 (Medium · P2) | 남음 | `chunk-recovery-boundary.test.tsx:20`, `:148`, `:177`, `render-boundary.test.tsx:20`, `:58`, `runtime-application.test.tsx:66`, `router.test.tsx:71`, `:108`, `:244`, `route-status-surfaces.test.tsx:66`, `:108`. `scripts/test-sample-removal.ts:48-94`의 `SAMPLE_EXTRAS` 그대로 | +| 10-03 실행기가 마감을 두 번 읽음 (Low · P2, = 03-05) | 남음 — 재현 | `http-execution-v3.ts:884-889`와 `:918-941`, `http-contract-bridge.ts:407` 그대로. P1 C1에서 2회 재현(1.1절) | +| 10-04 §10.8 마지막 검사를 고정하는 테스트 없음 (Low · P3) | 남음 | 변이 M01이 84파일 631개에서 살아남음. M03에서 상위 방어선(`application-query.ts:112`)은 테스트 1개가 지킨다 | +| 10-05 `test:all`이 CI의 빠른 테스트 일부를 빠뜨림 (Low · P3) | 남음 | `package.json:83`은 `test:reference-feature`만 돌린다. `:81`의 `tests/features` 전체·`tests/scripts`·`browser-soak.contract`는 없다 | +| (지난 2절 12) `boot-unexpected-failure.test.tsx`의 `vi.stubGlobal` 미복원 | 남음 — 영향은 그 파일 안 | `:25`. 설정에 `unstubGlobals` 없음 | +| (지난 2절 9) `test:platform`만 `--no-file-parallelism`, 이유 없음 | 남음 | `package.json:141` | +| (FOLLOW-UP 07-03) V2/V3 일치 테스트가 V2 행 0개면 통과 | 남음 — 07 영역 | `http-operation-v2-v3-parity.test.ts:31` | +| (지난 2절 21) `tsc-diagnostics-parser.test.ts` 제외 사유가 사실과 다름 | 남음 — 11·12 영역 | `config/ci/ungated-tests.json` 마지막 항목 | + +## 3. 새 발견 (36.3) + +### 10-01 이벤트 계약 정확성 테스트가 fixture에 이벤트가 없어 첫 줄에서 return한다 — 이름이 말하는 규칙을 아무도 검사하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(검출 공백, 오해를 부르는 테스트) | +| 관련 관점 | 10, 17, 21, 24, 5 | +| 근거 | `tests/unit/contract-registry-immutability.test.ts:322-335`. `:324`가 `if (events.length === 0) return;`이다. 쓰는 fixture는 `TEST_CONTRACT_CONTRIBUTION`이고 `events: Object.freeze([])`다(`tests/helpers/external-contract-fixture.ts:219`). 그래서 이 테스트는 언제나 단언 없이 통과한다. P-A 실험에서 "expected any number of assertion, but got none"으로 드러났다. 대상 규칙은 `external-contract-runtime.ts:660-670`(`snapshotEventContract`가 정확한 own data만 받음), `:516-531`(`assertEventContract`가 `eventType` 길이·문자와 두 validator를 확인), `:818-830`(설치된 이벤트마다 snapshot·검증·중복 확인)이다. 변이 M17(snapshot 생략)과 M18(검증 호출 제거)을 각각 넣어도 `external-contract-runtime.ts`를 직접·간접으로 import하는 96파일 766개가 모두 통과했다. 즉 이 테스트 하나만 비어 있는 것이 아니라 이벤트 계약 검증 전체를 지키는 테스트가 없다. 템플릿 안에서 `eventByType` registry를 읽는 코드는 없다(확장 지점) | +| 발생 조건 | 템플릿 안에서는 이벤트를 기여하는 계약이 없다(참조 샘플은 이벤트를 기여하면 안 된다, `:797-799`). 제품이 외부 계약 패키지로 이벤트 계약을 설치할 때 이 경로가 처음 쓰인다 | +| 영향 | 리팩터링에서 이벤트 계약의 정확성 검사가 빠져도 빠른 테스트가 모른다. 테스트 목록과 이름만 보면 이 규칙이 고정돼 있다고 믿게 된다. 바로 위의 contribution 단위 대응 테스트는 실제로 단언한다(`:305-320`) | +| 심각도·우선순위 | Low · P2 — 지금 템플릿에서 도달하는 경로가 없어 피해는 없다. 우선순위를 P2로 둔 이유는 테스트가 보호를 주장하면서 하지 않기 때문이다. 수정 비용도 작다 | +| 확실성과 남은 가정 | 단언 0개와 변이 M17·M18 생존은 실행으로 확인했다. 실제 외부 패키지가 이벤트를 기여하는 제품은 아직 없다 | +| 결정의 근거 | 적용 제외 — 테스트 fixture 누락이다. 선택 비교가 필요하지 않다 | +| 이해 비용 | 테스트를 읽는 사람이 fixture 정의까지 따라가야 빈 배열임을 안다 | +| 최소 개선 방향 | 이벤트 계약 하나를 가진 fixture를 `tests/helpers/external-contract-fixture.ts`에 추가하고 이 테스트가 그것을 쓴다. `if (events.length === 0) return;`을 지운다. HTTP 쪽 `hostileRows`(`:296-303`)처럼 `eventType` 빈 문자열·공백·160바이트 초과, validator 누락 경우를 더한다. 같은 패턴(빈 데이터면 조용히 통과)을 막으려면 `expect.hasAssertions()`를 `tests/setup.ts`의 `beforeEach`에 두는 방법도 있다. 이번 실험에서 이것을 켜도 이 테스트 외에 깨지는 테스트가 없었다(타입 전용 테스트 1개는 `expect`를 한 줄 넣거나 파일을 tsc 전용으로 옮기면 된다) | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | fixture 10~20줄. 전역 `hasAssertions`를 켜면 `expectTypeOf`만 쓰는 테스트 1개를 손봐야 한다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | M17·M18 변이를 넣으면 이 테스트가 실패한다. P-A 실험에서 이 테스트가 더는 나오지 않는다 | +| 검증 방법 | worktree에서 M17·M18을 넣고 `node scripts/run-vitest.ts related src/contracts/external-contract-runtime.ts --run` | +| 담당·기한·상태 | 미정 · 미정 · 신규(07 영역 코드와 겹침) | + +### 10-02 Popover의 "Escape 뒤 포커스 반환" 단언이 전제를 만들지 않아 아무것도 검사하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(검출 공백) | +| 관련 관점 | 10, 24, 6 | +| 근거 | 변이 M15: `overlays.tsx:74`의 `triggerRef.current?.focus()`를 지워도 관련 23파일 150개가 통과했다. 이 동작을 보는 단언은 `design-system-platform.test.tsx:320-325` 하나다. 이 테스트는 trigger를 클릭해 포커스를 trigger에 둔 채 Escape를 누른다. Popover는 열 때 포커스를 내용으로 옮기지 않는다(`overlays.tsx:86-101`). 그래서 포커스는 처음부터 끝까지 trigger에 있고, `expect(popoverTrigger).toHaveFocus()`는 코드와 무관하게 참이다. 비슷한 Playwright 검사(`tests/e2e/ui-gallery.spec.ts:31-33`, `tests/storybook/workshop.spec.ts:22-23`)는 Dialog를 본다. Popover가 아니다 | +| 발생 조건 | 사용자가 Popover 안의 링크나 버튼으로 Tab한 뒤 Escape를 누를 때. 내용이 사라지면서 포커스가 `body`로 떨어지면 키보드 사용자는 위치를 잃는다(WCAG 2.4.3) | +| 영향 | 지금 코드는 맞다. 누군가 이 줄을 지우거나 내용 쪽에 포커스 관리를 추가해 순서를 바꿔도 테스트가 모른다 | +| 심각도·우선순위 | Low · P3 — 지금 동작은 맞고, 깨져도 키보드 사용자의 불편에 그친다 | +| 확실성과 남은 가정 | 변이 생존과 포커스 경로는 확인했다. Popover 안에 포커스 가능한 요소를 두는 화면은 갤러리 외에 확인하지 않았다 | +| 결정의 근거 | 적용 제외 — 테스트 전제 누락이다 | +| 이해 비용 | 단언만 읽으면 보호되는 것처럼 보인다 | +| 최소 개선 방향 | Popover 내용에 포커스 가능한 요소를 두고, Tab으로 포커스를 옮긴 뒤 Escape를 누르고 trigger 포커스를 확인한다. 전제도 단언한다(`expect(trigger).not.toHaveFocus()`를 Escape 전에) | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 변이 M15를 넣으면 실패한다 | +| 검증 방법 | M15 적용 후 `node scripts/run-vitest.ts related src/presentation/design-system/primitives/overlays.tsx --run` | +| 담당·기한·상태 | 미정 · 미정 · 신규(08 영역 코드) | + +### 10-03 보호 라우트의 "세션 복구 대기" 분기를 어떤 빠른 테스트도 고정하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험(검출 공백) | +| 관련 관점 | 10, 6, 15 | +| 근거 | 변이 M10: `navigation-policy.ts:20-22`가 `recovery-pending`에서 `show-sign-in`을 돌려주게 바꿔도 관련 14파일 81개가 통과했다. 이 결정은 `app-router.tsx:256-279`에서 화면과 동작을 고른다. 복구 중이면 "세션 복구" 제목과 `run("recover")`, 아니면 "로그인 필요" 제목과 `run("sign-in")`이다. `route-status-surfaces.test.tsx:86-101`은 로그인 분기만 본다. 테스트 디렉터리에서 `wait-for-session`이라는 문자열은 나오지 않는다. `recovery-pending`은 어댑터 상태 전이 테스트(`auth-session-adapter.test.ts:139-145`, `reference-runtime-composition.test.ts:229-241`)에만 나온다 | +| 발생 조건 | 토큰 갱신 중(`recovery-pending`)에 사용자가 보호 라우트로 이동할 때 | +| 영향 | 이 분기가 깨지면 복구할 수 있는 세션에서 사용자에게 다시 로그인하라고 한다. "로그인"을 누르면 새 로그인 흐름이 시작돼 복구 중인 세션과 겹칠 수 있다. 다만 세션 처리 자체는 어댑터가 하므로 데이터 피해 경로는 확인하지 못했다 | +| 심각도·우선순위 | Low · P3 — 인증 흐름의 UX 분기다. 지금 코드는 맞다 | +| 확실성과 남은 가정 | 미검출은 확인했다. 두 흐름이 겹칠 때의 실제 결과는 외부 세션 소유자에 달려 있어 확인하지 않았다 | +| 결정의 근거 | 적용 제외 — 테스트 누락이다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | `route-status-surfaces.test.tsx`에 세션 상태를 `recovery-pending`으로 둔 보호 라우트 경우를 하나 추가한다. 복구 제목과 복구 버튼, 클릭 시 `recover` 호출을 확인한다. 단위 수준으로는 `navigation-policy.test.ts`에 `decideRouteAccess`의 세 상태를 표로 고정한다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 테스트 1~2개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 변이 M10을 넣으면 실패한다 | +| 검증 방법 | M10 적용 후 `node scripts/run-vitest.ts related src/presentation/routes/navigation-policy.ts --run` | +| 담당·기한·상태 | 미정 · 미정 · 신규(08·09 영역 코드) | + +### 10-04 빠른 계층에 `it.skip`·`it.todo`가 들어가도 어떤 게이트도 실패하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(가드레일 부재) | +| 관련 관점 | 21, 10, 20 | +| 근거 | 실험 P-B. `CI=true`에서 skip·todo가 든 파일은 종료 코드 0으로 끝났다. Vitest는 skip을 실패로 보지 않는다. 설정에 이를 막는 옵션이 없다(`vitest.config.ts:16-44`). ESLint 설정에 테스트 규칙 플러그인이 없다(`eslint.config.ts`). junit의 `skipped` 수를 보는 검사는 브라우저 capability 증거에만 있다(`scripts/verify-browser-capability-evidence.ts:11`, `:61-62`). 빠른 계층 junit(`unit.xml` 등)은 아무도 보지 않는다. `.only`는 Vitest 기본값(`allowOnly`는 `CI`가 없을 때만 허용)과 workflow의 `CI: "true"`(`.gitea/workflows/quality-gates.yml:26-27`) 덕분에 CI에서 막힌다. 로컬에서는 `.only`가 같은 파일의 나머지 테스트를 조용히 건너뛴다. 현재 코드에는 skip·only·todo가 하나도 없다 | +| 발생 조건 | 개발자나 에이전트가 실패하는 테스트를 `it.skip`으로 잠시 끄고 그대로 머지할 때 | +| 영향 | 그 테스트가 지키던 규칙이 조용히 빠진다. 다운스트림 제품에도 같은 구멍이 복사된다. 커버리지 하한(`risk-coverage.json`)은 파일 단위라 테스트 하나가 빠진 것을 잡지 못할 수 있다 | +| 심각도·우선순위 | Low · P2 — 지금 피해는 없다. 고치는 비용이 한 줄 수준이고 모든 복사본에 효과가 있다 | +| 확실성과 남은 가정 | 실행으로 확인했다 | +| 결정의 근거 | 대안이 여럿이라 아래에 적는다. [확인한 사실] 브라우저 capability 증거는 이미 "skipped 0"을 요구한다. 같은 정책이 빠른 계층에는 없다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | ⓐ `vitest.config.ts`에 `allowOnly: false`를 둬 로컬에서도 `.only`를 막는다. ⓑ skip·todo는 빠른 계층 junit에서 `skipped > 0`이면 실패하는 검사를 `run-vitest.ts` 끝이나 기존 증거 검사에 더한다. 의도된 조건부 skip(`skipIf`)이 필요해지면 그때 허용 목록을 둔다 | +| 대안 비교 | ESLint `vitest/no-disabled-tests`·`no-focused-tests`: 정적으로 막고 메시지가 좋다. 새 의존성 하나가 생긴다. junit 검사: 의존성 없이 실행 결과로 막는다. 동적 skip(`ctx.skip()`)도 잡는다. 템플릿이 이미 junit 증거 체계를 가지고 있으므로 junit 검사가 덜 낯설다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 수 줄. 정당한 skip이 생기면 예외 목록이 필요하다 | +| 재검토 조건 | 플랫폼별 조건부 테스트가 필요해지면 `skipIf` 허용 목록을 둔다 | +| 완료 기준 | P-B 실험의 skip·todo 파일과 `.only` 파일이 로컬과 `CI=true` 모두에서 실패한다 | +| 검증 방법 | P-B 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규(12 영역과 공유) | + +### 10-05 `tests/unit`에 도구(scripts) 테스트가 섞여 있어 unit 계층 합산 시간의 58%를 쓴다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안(실행 비용·폴더 구조) | +| 관련 관점 | 14, 20, 4, 9, 3 | +| 근거 | `tests/unit`의 테스트 파일 166개 중 39개는 `scripts/`만 import한다(9개는 `scripts/`와 `src/`를 함께, 118개는 `src/`만). 오케스트레이터 junit(`artifacts/tests/unit.xml`) 기준으로 이 39파일은 파일의 24%, 테스트의 31%(740개)지만 합산 시간 73.4s 중 42.5s(58%)를 쓴다. 느린 unit 테스트 상위가 모두 여기 있다: `security-promotion-staging.test.ts`(7.0s, 자식 프로세스), `ci-workflow-generation.test.ts`(6.6s, 임시 디렉터리 fixture), `risk-coverage.test.ts`(6.4s), `fixture-node-modules.test.ts`(4.5s, pnpm 설치), `build-environment-bundle.test.ts`(4.0s, vite build), `product-feature-selection-build.test.ts`(2.8s), `two-feature-install-typecheck.test.ts`(2.4s, tsc). 한편 `tests/scripts/`라는 폴더가 따로 있고 파일 2개가 있다. 이 폴더는 `test:coverage`에서만 돌고 `test:unit`·`test:all`에는 없다(`package.json:50`, `:81`, `:83`). taxonomy는 짧은 자식 프로세스 테스트를 `tests/unit`에 두는 것을 허용한다(`docs/testing/taxonomy.md`의 "A script's own tests may start…") | +| 발생 조건 | 제품 개발자가 기능을 고치고 `test:unit`이나 `test:all`을 돌릴 때마다 | +| 영향 | 일상 루프에서 템플릿 CI 도구의 테스트(빌드·tsc·pnpm 설치 포함)를 함께 기다린다. 2코어 장비에서는 합산 시간이 벽시계에 거의 그대로 반영된다. 도구 테스트가 어디에 있는지 규칙이 둘이라(`tests/unit`과 `tests/scripts`) 새 도구 테스트의 위치를 정하기 어렵다 | +| 심각도·우선순위 | Low · P3 — 정확성 문제는 없다. 반복 비용이다 | +| 확실성과 남은 가정 | 파일 분류는 import 경로로 기계적으로 했다. 시간은 22코어·부하 2~3인 게이트 실행의 junit 값이다 | +| 결정의 근거 | 4.1절 | +| 이해 비용 | 새 도구 테스트를 만드는 사람이 두 폴더 중 하나를 골라야 하고, 고른 폴더에 따라 돌리는 게이트가 달라진다 | +| 최소 개선 방향 | `scripts/`만 대상으로 하는 39파일을 `tests/scripts/`로 옮긴다. `test:tooling`(가칭) 스크립트를 만들고 기존 게이트 하나(FE-GATE-005 또는 010)에 넣는다. `test:unit`은 `src/` 대상만 남는다 | +| 대안 비교 | 4.1절 | +| 단순화의 보존 조건 | 옮긴 파일이 모두 어떤 게이트에서 계속 돈다(`check:ci`의 게이트 소속 검사가 확인). 커버리지 실행 목록(`package.json:81`)에 `tests/scripts`가 이미 있으므로 커버리지 증거는 바뀌지 않는다. `PROCESS_HEAVY_TIMEOUT_MS` 같은 파일별 시간 제한은 그대로 둔다 | +| 비용·부작용 | 파일 이동과 import 경로 수정. 다운스트림은 다음 동기화 때 이동을 한 번 받는다 | +| 재검토 조건 | 도구 테스트가 몇 개 안 되게 줄면 지금 구조가 낫다 | +| 완료 기준 | `test:unit`이 `scripts/`만 import하는 파일을 수집하지 않는다. 옮긴 파일이 게이트 하나에서 돈다 | +| 검증 방법 | `vitest list --filesOnly tests/unit`과 import 분류 대조, `check:ci` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 10-06 머지 단계가 빠른 계층 파일 대부분을 두 번 돌린다 — 비용과 부하 실패 기회가 함께 두 배다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안(실행 비용) + 구조적 위험(부하 의존 테스트의 실패 기회 증가) | +| 관련 관점 | 14, 21, 20, 10, 12 | +| 근거 | FE-GATE-005는 한 job 안에서 `test-unit`, `test-contract`, `test-coverage`, `check-scale-pr`을 차례로 돈다(`config/ci/gates.json:1816-1823`). `test:coverage`는 `tests/runtime-schema tests/unit tests/contract tests/component tests/integration tests/features tests/platform tests/architecture tests/release tests/scripts`를 다시 돈다(`package.json:81`). 그래서 같은 job에서 unit 165파일과 contract 3파일이 두 번 돈다. `check-scale-pr`은 `tests/architecture`와 `tests/platform`의 cardinality·routing·execution·traffic·resilience를 한 번 더 돈다(`run-scale-profile.ts:39-48`). runtime-schema·component·integration은 FE-GATE-004·006·007 job에서 한 번, FE-GATE-005의 커버리지 실행에서 또 한 번 돈다. FE-GATE-007 안에서는 `http-scenario-catalog.test.ts`가 `test:integration`과 `test:http-scenario-evidence`(`scripts/run-http-scenario-evidence.ts:30`)에서 두 번 돈다. 모든 머지 게이트는 matrix job으로 따로 돈다(`gates.json`의 `merge_gate` job) | +| 발생 조건 | 모든 PR | +| 영향 | 비용: FE-GATE-005 job에서 unit·contract를 커버리지 없이 한 번 더 도는 만큼(이 리뷰의 4코어·부하 17~23 측정에서 `tests/unit`만 29~36s) 시간이 늘어난다. 실패 기회: 지난 10-01의 부하 의존 테스트는 006·007 job에서 한 번, 005의 커버리지 실행(V8 계측, `--maxWorkers=4`)에서 또 한 번 실패할 기회를 가진다. 커버리지 실행이 가장 무거운 조건이다 | +| 심각도·우선순위 | Low · P3 — 정확성 문제는 없다. 지난 10-01을 고치기 전에는 머지 실패 확률을 키운다 | +| 확실성과 남은 가정 | 실행 구성은 설정으로 확인했다. 실제 러너에서의 시간은 모른다(U-1, 15 영역) | +| 결정의 근거 | 4.2절 | +| 이해 비용 | "unit 테스트가 어느 게이트에서 몇 번 도는가"를 알려면 gates.json, package.json, run-scale-profile.ts 세 곳을 맞춰 봐야 한다 | +| 최소 개선 방향 | FE-GATE-005에서 `test-unit`·`test-contract`를 빼고 커버리지 실행이 `unit.xml`·`contract.xml` 증거를 대신 만들게 한다. 004·006·007은 빠른 실패 신호로 남긴다 | +| 대안 비교 | 4.2절 | +| 단순화의 보존 조건 | 머지마다 모든 빠른 계층 파일이 커버리지 계측 아래 한 번은 돈다. `risk-coverage` 검사가 같은 입력을 받는다. 증거 artifact ID(`artifact-artifacts-tests-unit-xml` 등)를 쓰는 검사(`check:ci`, artifact 스키마)가 계속 통과한다 | +| 비용·부작용 | gates.json·증거 매핑 수정. 증거 파일 이름을 유지하려면 커버리지 실행의 junit을 계층별로 나누는 작업이 필요하다(Vitest `projects` 또는 후처리) | +| 재검토 조건 | CI 러너가 8코어 이상이면 중복 비용이 작아 현 상태가 낫다. 지난 10-01을 고친 뒤에는 실패 기회 증가의 무게가 줄어든다 | +| 완료 기준 | 한 머지에서 각 빠른 계층 파일이 도는 횟수가 커버리지 1회 + 계층 게이트 최대 1회다 | +| 검증 방법 | `check:ci`, CI 로그에서 파일별 실행 횟수 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규(12·15 영역과 공유) | + +### 10-07 테스트가 프로덕션 시간 상수를 실제 시계로 기다린다 — 5개 테스트가 약 9초를 쓴다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안(실행 비용) | +| 관련 관점 | 14, 12, 10, 20 | +| 근거 | ① `service-worker-runtime.test.ts:1907-1923` "bounds a stream that never produces a chunk"가 5.01s 걸린다. 대상 상수는 `ACTIVATION_MARKER_READ_DEADLINE_MS = 5_000`(`service-worker-lifecycle.ts:558`)이고 `setTimeout`으로 직접 건다(`:589-592`). 주입할 방법이 없다. ② `browser-rpc-remediation.test.ts`의 4개 테스트가 각각 1.03~1.06s 걸린다. 대상은 `STREAM_CLEANUP_BOUND_MS = 1_000`(`browser-rpc-runtime.ts:1236`)이다. 이 런타임은 이미 `clock`(`ClockPort`, `sleep` 포함)을 주입받는다(`:69`, `:114`, `:1251`). 그런데 이 테스트들은 `clock`을 넘기지 않아 실제 시계로 1초를 잔다(예: `:579`). guardian의 5초 대기(`provider-guardian-transaction.test.ts:619`)도 같은 종류지만 지난 10-01에 포함돼 있어 여기서 세지 않는다 | +| 발생 조건 | 모든 unit 실행 | +| 영향 | 합산 약 9s. 2코어에서는 벽시계에 거의 그대로 더해진다. SW 테스트는 10s 테스트 제한 중 5s를 쓴다. 지금 실패 기록은 없다 | +| 심각도·우선순위 | Low · P3 | +| 확실성과 남은 가정 | 시간은 게이트 junit 값이다. `ClockPort` 주입 경로는 코드로 확인했다 | +| 결정의 근거 | 4.3절 | +| 이해 비용 | 테스트가 왜 5초 걸리는지 알려면 대상 모듈의 상수를 찾아야 한다 | +| 최소 개선 방향 | ② RPC 테스트는 `sleep`을 수동으로 끝내는 `ClockPort`를 넘긴다. 코드 변경이 없다. ① SW lifecycle은 deadline을 의존성(기본값 5,000)으로 받게 하거나, 이 테스트만 `vi.useFakeTimers()`와 `advanceTimersByTimeAsync`로 돌린다 | +| 대안 비교 | 4.3절 | +| 단순화의 보존 조건 | "멈춘 스트림도 activate를 영원히 붙잡지 못한다"는 동작과 "거절한 본문을 cancel한다"는 동작을 계속 검사한다. 상수 값 자체(5,000·1,000)는 한 곳에서 고정한다 | +| 비용·부작용 | 테스트 수십 줄. SW 쪽은 의존성 하나 추가 | +| 재검토 조건 | 가짜 시계가 스트림·마이크로태스크 순서와 얽혀 테스트가 불안정해지면 실제 시계로 되돌리고 상수를 테스트 전용 값으로 낮춘다 | +| 완료 기준 | 위 5개 테스트가 각각 100ms 아래로 끝난다 | +| 검증 방법 | 해당 파일을 junit으로 돌려 테스트별 시간 확인 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 10-08 같은 테스트 fixture가 갈라진 복사본으로 다섯 군데에 있다 — `scopeSnapshot` + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안(갈라진 중복) | +| 관련 관점 | 9, 23, 22, 10 | +| 근거 | `tests/helpers/traffic-test-kit.ts:13-21`에 공유 `scopeSnapshot()`이 있다. 그런데 다음 다섯 파일이 각자 정의한다: `tests/features/reference-feature/reference-diagnostics.test.ts:7-15`(인자 없음), `tests/integration/http-execution-v3-auth-profile.test.ts:41-49`(`isCurrent` 인자), `http-execution-v3-observability.test.ts:24-32`(`isCurrent` 인자), `http-execution-v3-live-authority.test.ts:23-31`(`signal` 인자), `tests/component/application-query-fixture.tsx:20-`(실제 identity registry와 `fence()`). 공유 도우미를 포함해 다섯 개가 `identities: Object.freeze({}) as never`로 타입 검사를 끈다. 어떤 복사본도 `isCurrent`와 `signal`을 따로 조절하게 해 주지 않는다. 지난 10-04(본문을 다 읽은 뒤 scope만 바뀌고 signal은 abort되지 않는 경우)를 테스트하려면 바로 그 조합이 필요하다. 비슷하게 `deferred()`가 7개 파일에 따로 있다(`optional-runtime-host.test.ts:18`, `realtime/stream-coordinator.test.ts:1267`, `realtime/live-poll-handoff-coordinator.test.ts:693`, `realtime/realtime-reconnect-coordinator.test.ts:220`, `route-status-surfaces.test.tsx:28`, `public-response-cache-fixture.ts:97`, `tests/helpers/fake-push-control-repository.ts:217`). Node 24에는 `Promise.withResolvers()`가 있다 | +| 발생 조건 | 실행기가 scope의 `identities`를 읽기 시작하거나 scope 타입이 바뀔 때 | +| 영향 | `as never` 복사본은 컴파일러가 아니라 실행 중 오류로 깨진다. 다섯 곳을 따로 고쳐야 한다. 새 테스트 작성자는 어느 것을 써야 할지 모른다 | +| 심각도·우선순위 | Low · P3 | +| 확실성과 남은 가정 | 정의와 차이는 코드로 확인했다 | +| 결정의 근거 | 적용 제외 — 테스트 도우미 정리이고 선택지가 사실상 하나다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | `tests/helpers/traffic-test-kit.ts`의 `scopeSnapshot`을 `{ isCurrent, signal, generation, fingerprint }` 선택 인자로 넓히고 다섯 복사본을 지운다. `identities`는 `as never` 대신 실제 registry(`createRuntimeIdentityRegistry`) 또는 타입이 맞는 stub을 쓴다. `deferred()`는 `Promise.withResolvers()`로 바꾼다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 기본값은 지금과 같다(`generation: 1`, `isCurrent: () => true`, abort되지 않은 signal). `application-query-fixture.tsx`의 `fence()`처럼 고유 기능이 있는 판은 공유 도우미 위에 얹는다 | +| 비용·부작용 | 파일 7~12개 수정 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `tests/`에서 `function scopeSnapshot` 정의가 1개다. `as never`로 만든 scope가 없다 | +| 검증 방법 | `grep`, 빠른 계층 실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 설계 선택 검토 (41절) + +지난 라운드 3.1절(비동기 대기 기본값)과 3.2절(플랫폼 테스트의 대상)은 코드가 그대로라 결론도 그대로다. 이번 실험은 3.1절의 판단을 더 강하게 만든다. 실패한 지연 로딩 테스트 3종이 모두 1초 기본값을 쓰고, 5초를 준 호출(`router.test.tsx:72`)은 실패하지 않았다. + +### 4.1 도구 테스트를 `tests/unit`에 앱 단위 테스트와 함께 둔다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 템플릿은 CI 계약·증거·공급망 도구를 `scripts/`에 많이 가진다. 이 도구의 규칙도 테스트가 지켜야 한다. 동시에 제품 개발자의 일상 루프(`test:unit`, `test:all`)는 빨라야 한다 | +| 2. 지킬 성질 | 모든 도구 테스트가 어떤 머지 게이트에서 돈다. 앱 코드만 바꾼 개발자가 기다리는 시간은 앱 테스트 비용에 가깝다 | +| 3. 현재 보장 | [확인한 사실] 도구 테스트 39파일이 `tests/unit`에 있어 FE-GATE-005에서 돈다. taxonomy가 이 배치를 허용한다. 따로 있는 `tests/scripts`(2파일)는 커버리지 실행에서만 돈다. [보장하지 않음] 일상 루프의 비용. unit 합산 시간의 58%가 도구 테스트다 | +| 4. 대안 | ⓐ 현 상태 ⓑ 도구 테스트를 `tests/scripts`로 모으고 `test:tooling`을 게이트 하나에 넣는다 ⓒ Vitest `projects`로 `app`·`tooling`을 나누고 폴더는 그대로 둔다 ⓓ 도구 테스트 중 무거운 것(빌드·tsc·pnpm)만 `tests/integration`으로 옮긴다 | +| 5. 비용 비교 | ⓐ 비용 없음. 루프가 느리고 폴더 규칙이 둘이다. ⓑ 파일 이동 한 번. 위치 규칙이 하나가 된다. `test:unit`이 앱 테스트만 남는다. ⓒ 폴더 이동은 없지만 분류가 설정 안의 glob으로 숨는다. ⓓ 무거운 7파일만 옮기면 시간은 대부분 줄지만 "도구 테스트는 어디에"라는 규칙은 그대로 둘이다 | +| 6. 현재 조건에서의 선택 | [추론] ⓑ. 이미 `tests/scripts` 폴더와 커버리지 경로가 있어 새 개념이 생기지 않는다. 제품이 도구를 갈아 끼우거나 지울 때도 폴더 하나만 보면 된다 | +| 7. 재검토 조건 | 도구가 별도 패키지로 빠지면 테스트도 따라간다. 도구 테스트가 몇 개로 줄면 ⓐ가 낫다 | + +### 4.2 커버리지 실행이 계층별 게이트와 별도로 같은 파일을 다시 돈다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 계층별 junit 증거(`unit.xml` 등), 위험 모듈의 커버리지 하한 검사(`check-risk-coverage.ts`), 빠른 실패 신호 | +| 2. 지킬 성질 | 머지마다 모든 빠른 계층 파일이 커버리지 계측 아래 한 번은 돈다. 계층별 증거가 남는다 | +| 3. 현재 보장 | [확인한 사실] 계층 게이트가 계측 없이 한 번, 커버리지 실행이 계측해 한 번 돈다. FE-GATE-005 안에서는 unit·contract가 같은 job에서 연달아 두 번 돈다. [보장하지 않음] 중복 비용과 부하 실패 기회 증가에 대한 고려 기록 | +| 4. 대안 | ⓐ 현 상태 ⓑ FE-GATE-005에서 `test-unit`·`test-contract`만 빼고 커버리지 실행이 그 증거를 만든다 ⓒ 각 계층 게이트가 `--coverage --reporter=blob`으로 돌고 뒤 job이 `vitest --merge-reports`로 합친 뒤 하한을 검사한다 ⓓ 계층 게이트를 없애고 빠른 계층 게이트 하나로 합친다 | +| 5. 비용 비교 | ⓐ 가장 단순하다. CPU 2배, 부하 실패 기회 2배. ⓑ 같은 job 안의 중복만 없앤다. 증거 파일 이름을 맞추는 작업이 있다. ⓒ 중복이 완전히 사라지지만 job 사이 artifact 전달과 의존이 생긴다. ⓓ 가장 싸지만 어느 계층이 깨졌는지 게이트 이름으로 바로 알 수 없다 | +| 6. 현재 조건에서의 선택 | [추론] ⓑ. 같은 job 안에서 연달아 도는 중복은 얻는 것이 없다. 004·006·007은 병렬 job이라 벽시계 비용이 작고 빠른 실패 신호를 준다 | +| 7. 재검토 조건 | CI 러너가 크면 ⓐ도 괜찮다. 러너가 1~2코어로 정해지면 ⓒ를 다시 본다 | + +### 4.3 테스트가 프로덕션 시간 상수를 실제 시계로 기다린다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | "멈춘 스트림·협조하지 않는 transport도 정해진 시간 뒤에는 놓아준다"는 상한 동작을 검사해야 한다 | +| 2. 지킬 성질 | 상한이 실제로 걸린다. 상한 값은 한 곳에서 정해진다. 테스트는 상한 값과 무관하게 빨리 끝난다 | +| 3. 현재 보장 | [확인한 사실] SW lifecycle은 `setTimeout`을 직접 쓰고 상수를 주입받지 않는다. browser-rpc 런타임은 `ClockPort`를 주입받지만 해당 테스트가 넘기지 않는다. guardian client는 5초 상수를 쓴다. [보장하지 않음] 테스트 시간. 이 세 곳이 합산 약 14초를 쓴다 | +| 4. 대안 | ⓐ 현 상태 ⓑ `vi.useFakeTimers()` ⓒ 시계·deadline 주입(browser-rpc는 이미 가능) ⓓ 이런 테스트를 느린 tier로 옮긴다 | +| 5. 비용 비교 | ⓐ 실제 동작에 가장 가깝다. 매 실행 수 초. ⓑ 코드 변경이 없지만 스트림·Promise·마이크로태스크와 얽히면 테스트가 불안정해진다. ⓒ 정확하고 빠르다. SW 쪽은 의존성 하나가 는다. ⓓ 머지 게이트에서 상한 검사가 빠진다 | +| 6. 현재 조건에서의 선택 | [추론] browser-rpc는 ⓒ(이미 있는 주입을 쓰기만 하면 된다). SW는 ⓑ를 먼저 시도하고 불안정하면 ⓒ. guardian은 자식 프로세스라 가짜 시계가 닿지 않으므로 지난 10-01의 방향(준비 신호를 기다린 뒤 시작)을 따른다 | +| 7. 재검토 조건 | 실제 시계에서만 드러나는 결함이 나오면 그 경우 하나만 실제 시계로 남긴다 | + +## 5. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R1 | `tests/setup.ts`에서 jest-dom·RTL을 DOM이 있을 때만 읽는다 | DOM이 없는 unit 163파일(전체 166 중 jsdom 지시자 3개)도 매번 RTL을 읽는다. 실험 P-C에서 setup 누적 시간이 27~37s에서 2~4s로 줄었다. 벽시계는 부하 때문에 판단하지 못했다 | jsdom 파일은 매 테스트 뒤 `cleanup()`. jest-dom matcher를 jsdom 파일에서 그대로 쓴다. 모든 파일은 매 테스트 뒤 `vi.useRealTimers()`(`tests/unit/test-setup.test.ts`가 고정) | +| R2 | 10-08: `scopeSnapshot` 하나로 합치고 `deferred()`를 `Promise.withResolvers()`로 | 갈라진 복사본 5벌·7벌. `as never`가 타입 검사를 끈다 | 기본값 동일. `fence()` 같은 고유 기능 유지 | +| R3 | 10-05: 도구 테스트 39파일을 `tests/scripts`로 | 위치 규칙 하나, `test:unit` 시간 절반 이하 | 모든 파일이 게이트에 남음(`check:ci`), 커버리지 경로 그대로 | +| R4 | 10-06: FE-GATE-005에서 `test-unit`·`test-contract` 제거 | 같은 job 안 중복 | 계층별 증거 artifact, `risk-coverage` 입력 | +| R5 | 10-07: browser-rpc 4개 테스트에 수동 `ClockPort` 주입, SW 테스트에 가짜 시계 | 약 9s | 상한 동작과 cancel 동작 검사 유지 | +| R6 | `tests/unit/typescript-tooling-smoke.test.ts`, `tests/component/typescript-tooling-smoke.test.tsx` 삭제 | 초기 골격의 흔적이다. TS·TSX 파싱과 렌더링은 다른 테스트 수백 개와 `check:types`·`lint`가 이미 증명한다. 이 두 파일이 잡을 실패는 다른 테스트와 게이트도 함께 잡는다 | 없음 | +| R7 | `ci-workflow-generation.test.ts`의 "before entering the runner callback" 묶음(이름에 "runner callback"이 든 테스트 69개, 임시 디렉터리 fixture를 만드는 호출 13곳)을 경로마다 대표 입력 1~2개로 줄인다 | 같은 입력 목록을 검증 함수 단위 테스트(예: `:1085`, `:800`, `:819`)가 이미 하나씩 확인한다. 전체 경로 테스트가 확인할 것은 "preflight가 검증 함수를 부른다"는 연결 하나다. 이 69개가 파일 6.6s 중 2.7s를 쓴다 | 모든 입력이 검증 함수에서 거부된다(단위 테스트 유지). 로더와 preflight가 runner callback 전에 실패한다(대표 입력으로 유지). 이 파일은 12 영역 도구의 테스트이므로 12 영역과 함께 판단한다 | +| R8 | 10-01: 이벤트 계약 fixture 추가, 빈 데이터 return 제거 | 단언 0개 테스트 | HTTP 쪽 대응 테스트 그대로 | + +## 6. 28개 관점 판정 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. 굵은 번호가 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 적용·통제(목표/확인)·증거 | 근거와 잔여 위험 | +|---|---|---|---|---| +| 1 | 코드 성숙도 | > | 01~09 | 이 영역에서 다시 재현한 실행기 결함은 지난 10-03(03 영역) | +| 2 | 구조적 성숙도 | > | 12 | — | +| 3 | 변경 용이성 | P | 적용 · M2/M2 · E2 | 테스트 추가는 쉽다(`create-test-application.ts`, `fixture-feature.tsx`). 스타터 화면을 바꾸면 플랫폼 테스트를 옮겨야 한다(지난 10-02). 도구 테스트 위치 규칙이 둘이다(10-05) | +| 4 | 인지 부하 | P | 적용 · M2/M2 · E1 | taxonomy가 계층과 파일 하나 실행법을 정확히 적는다. `test:all`과 CI 집합이 다르다(지난 10-05). unit 테스트가 몇 번 어디서 도는지 세 파일을 맞춰야 안다(10-06) | +| 5 | 위험 가시성 | P | 적용 · M1/M1 · E2 | 이름은 규칙을 주장하는데 검사하지 않는 테스트 2개(10-01, 10-02). guardian lease에 기동 시간이 들어간다는 사실이 코드에 없다(지난 10-01) | +| 6 | 실패 성숙도 | P | 적용 · M3/M3 · E2 | 실패 경로 변이 대부분 검출(M04·M05·M06·M12·M13). 마감 경계의 분류 결함이 부하에서 재현(지난 10-03) | +| 7 | 운영 성숙도 | - | 테스트 계층 밖 | — | +| 8 | 디버깅 가능성 | P | 적용 · M2/M2 · E3 | 부하 실패 문구가 원인(느림)을 가린다: "Unable to find role", "READY timed out"(1.1절) | +| 9 | 유지보수 성숙도 | P | 적용 · M2/M1 · E1 | 갈라진 fixture 복사본(10-08). `test:platform`의 `--no-file-parallelism` 이유 없음(`package.json:141`) | +| **10** | **테스트 성숙도** | **P** | 적용 · 목표 M3 / 확인 M3 · E2(변이)·E3(부하) | 변이 18종 중 13종 검출(1.2절). 생존: §10.8(지난 10-04), 이벤트 계약 검증 2종(10-01), 세션 복구 분기(10-03), Popover 포커스(10-02). 단언 0개 테스트 1개(10-01). 1코어 부하에서 5/5 실패(지난 10-01). 재시도 0. 한 규칙을 테스트 1개가 지키는 경우가 많다(M02, M05, M08, M09, M11, M12, M14) | +| 11 | 데이터 성숙도 | > | 05 | — | +| **12** | **동시성 성숙도** | **P** | 적용(테스트 격리·실행 경쟁) · M3/M2 · E3 | 테스트 사이 상태 격리는 좋다: `restoreMocks`·`clearMocks`·`mockReset`(`vitest.config.ts:20-22`), 전역 `useRealTimers`(`tests/setup.ts:5-11`), `process.env` 변경은 1파일이고 복원한다. 병렬 실행에서 순서 의존 실패는 없었다. CPU 경쟁에서는 실제 시계에 기대는 테스트가 실패한다(지난 10-01). 머지 단계 중복 실행이 그 기회를 늘린다(10-06) | +| 13 | 확장성 | > | 11 | — | +| 14 | 성능 성숙도 | P | 적용(테스트 실행 비용) · M2/M1 · E2 | 원인만 짚는다(시간 측정은 15 영역). 테스트 22개(0.8%)가 합산 시간 47%. unit의 도구 테스트가 unit 합산 58%(10-05). 실제 시계 대기 약 14s(10-07, 지난 10-01). 머지 단계 중복 실행(10-06). 전역 setup 비용(R1) | +| 15 | 보안 성숙도 | > | 02·03·09 | 보안 관련 변이 M06·M07·M13은 잡혔다 | +| 16 | 의존성 성숙도 | > | 13 | — | +| 17 | API / Contract | P | 적용(계약 테스트) · M3/M2 · E2 | contract·runtime-schema 게이트 통과(오케스트레이터). 이벤트 계약 규칙을 검사하지 않음(10-01). V2/V3 일치 테스트는 V2 행 0개여도 통과(07-03). §10.8 미고정(지난 10-04) | +| 18 | 배포 성숙도 | > | 11·13 | — | +| 19 | 설정 성숙도 | P | 적용(러너 설정) · M3/M2 · E2 | `include`·`exclude`·Node 확인·생성기 연결은 맞다(새 worktree에서 확인). 비동기 대기 기본값을 전역에서 정하지 않는다(지난 10-01). `test:runtime-schema`에 `--passWithNoTests`가 붙어 디렉터리가 비어도 통과한다(`package.json:49`). 참조 샘플처럼 지울 수 있는 경로가 아니라 이유가 보이지 않는다 | +| **20** | **개발자 경험** | **P** | 적용 · M2/M2 · E2 | 새 worktree에서 `node scripts/run-vitest.ts run <경로>`가 문서대로 동작했다. 일상 루프가 도구 테스트를 함께 기다린다(10-05). `test:all`이 CI 파일 일부를 빠뜨린다(지난 10-05). CI를 켜면 거짓 실패 조사 비용(지난 10-01) | +| **21** | **Guardrail 성숙도** | **P** | 적용 · M3/M2 · E2 | 게이트 소속 검사는 유지(`ungated-tests.json` 6개, 내용 변화 없음). skip·todo는 막는 장치가 없고, `.only`는 CI에서만 막힌다(10-04). 단언 없는 테스트를 막는 장치도 없다(10-01) | +| 22 | 추상화 성숙도 | P | 적용(테스트 도우미) · M2/M2 · E1 | `fixture-feature.tsx`·`external-contract-fixture.ts`가 샘플 대신 쓸 테스트 전용 대상을 준다. scope fixture는 공유 도우미가 있는데도 복사본이 갈라졌고 `as never`로 타입을 끈다(10-08) | +| 23 | 일관성 | P | 적용 · M2/M1 · E1 | 지연 로딩 대기 시간 지정이 세 방식이다(지난 라운드와 같음). 테스트 지원 코드 위치가 `tests/helpers`·`tests/mocks`·`tests/support`·`tests/fixtures`·`tests/unit/*-fixture.ts`로 흩어져 있다. 그중 colocated fixture는 같은 계층 안에서만 쓰여 문제는 아니다. `deferred()` 7벌(10-08) | +| 24 | 네이밍 / 의미 | P | 적용 · M1/M1 · E2 | 실패한 테스트 이름은 대부분 깨진 규칙을 말한다(1.2절 표). 이름과 실제 검사가 다른 테스트 2개(10-01, 10-02) | +| 25 | 조직 확장성 | - | 작성자 1인 | — | +| 26 | Ownership | P | 부분 적용 · M2/M1 · E1 | 커버리지 모듈에는 owner가 있다(`config/testing/risk-coverage.json`). `ungated-tests.json` 항목에는 담당·재검토 시점이 없다(12 영역) | +| 27 | 삭제 가능성 | P | 적용 · M3/M2 · E1 | 샘플 제거가 플랫폼 검사 일부를 함께 지우고, 스타터 화면 교체가 플랫폼 테스트를 깨뜨린다(지난 10-02, 그대로) | +| 28 | 회복 가능성 | - | 테스트 계층 밖 | — | + +집계(적용 18개 기준, `>`·`-` 제외): 충족 0 · 부분 충족 18 · 미충족 0 · 미검증 0. 지난 라운드에 O였던 24(네이밍)는 이번에 이름과 실제 검사가 다른 테스트 2개를 찾아 P로 내렸다. + +## 7. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 실제 CI 러너에서의 실패율 | CI가 꺼져 있다(U-1). 러너 사양이 없다 | U-1 뒤 FE-GATE-005~007을 20회 돌리고 실패를 센다 | +| 조용한 호스트의 2코어 결과 | 다른 에이전트와 호스트를 공유했다. 부하 발생기는 쓰지 않았다 | 전용 호스트에서 `taskset -c 0-1` + `--maxWorkers=4` 20회 | +| R1의 벽시계 효과 | P-C가 부하 14~23에서 3회씩이라 흔들렸다 | 조용한 호스트에서 각 10회(15 영역) | +| `test:platform`의 `--no-file-parallelism`이 필요한 이유 | 기록이 없다. 이번에는 돌리지 않았다 | `tests/platform` 병렬 20회 | +| 세션 복구 중 로그인 흐름이 겹칠 때의 실제 결과(10-03) | 외부 세션 소유자의 동작에 달렸다 | 09 영역에서 auth adapter 경로 확인 | diff --git a/docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md b/docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md new file mode 100644 index 00000000..78150141 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/11-tests-browser-release-scale.md @@ -0,0 +1,308 @@ +# 영역 11 — 테스트: 브라우저·릴리스·규모 + +> 검토일: 2026-11-01 · 기준: 브랜치 `fix/ui-design-audit-2026-11-01` / `d99301b` (워킹트리는 추적되지 않는 `.claude/`만 있다) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, 실행 순서: `TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 경로: `tests/e2e`, `tests/browser-capabilities`, `tests/visual`, `tests/storybook`, `tests/release`, `tests/scale`, `tests/system`, `tests/architecture`, `tests/scripts`, `playwright*.config.ts` 5개. 판정에 필요해서 함께 읽은 것: `config/ci/gates.json`(FE-GATE-008·013), `.gitea/workflows/quality-gates.yml`(merge job), `scripts/check-test-evidence.ts`(visual·quarantine 부분), `scripts/lib/fixture-node-modules.ts`, `src/presentation/design-system/tokens/semantic.css`, `docs/testing/frontend-platform-testing-strategy.md` 13.4절, `docs/architecture/decisions/VD-08-storybook-and-visual-evidence.md`, `docs/styling/design-system-platform.md` 10.3절, `docs/reviews/2026-11-01-ui-design-audit.md`(UI-04·UI-05), playwright-core 1.62.0에 들어 있는 Ubuntu 24.04 의존 패키지 목록. +> 깊게 본 관점: 10, 13, 14, 18, 28. +> 영역 판정(35.8): **조건부 사용 가능.** 브라우저 테스트는 세 엔진에서 실패 0이다(e2e 163 통과·3 quarantine skip, capability 63 통과). 엄격 fixture·재시도 0과 함께 참고 구현으로 써도 된다. 다음은 그대로 쓰지 않는다. merge 게이트 FE-GATE-013의 `test:system`은 서로 다른 두 원인으로 항상 실패한다(09-29/11-01, 11-01). merge 게이트 FE-GATE-008의 시각 회귀는 작성자 PC의 글꼴에서만 통과하고(11-02), 작은 회귀는 놓친다(11-03). 운영 drill·SW spec·lab 성능의 지난 결함은 코드가 그대로라 남아 있다. + +## 0. 결론 + +- **이번 게이트의 `test:system` 실패 2건 중 1건만 지난 원인과 같다.** `:1259` 기대 문자열은 09-29/11-01 그대로다. 다른 1건(`:810`)은 지난 라운드가 "부하 레이스"로 본 09-29/11-06인데, 실제로는 이미 끝나 회수된 PID의 argv를 조회하는 결정적 실패다. 문자열만 고쳐서는 FE-GATE-013이 초록이 되지 않는다(11-01). +- **e2e 세 엔진은 모두 통과했다.** chromium 56/56(26초), firefox 52 통과·3 skip(36초), webkit 55/55(43초). 재시도 0, flaky 0. 새 UI-04 테스트는 세 엔진 모두에서 변이를 잡았다. +- **시각 골든은 작성자 PC의 글꼴 4종에 묶여 있다.** Chromium이 실제로 그린 글꼴은 Noto Sans, Noto Sans CJK KR(Regular·Black), Liberation Mono다. Playwright가 맨 Ubuntu에 까는 글꼴 구성으로 바꾸면 0/5다. 세 글꼴 디렉터리만 보이게 하면 5/5다. 그래서 골든을 다시 찍지 않고 `fonts.conf`로 고정할 수 있다(11-02, 4.1절). +- **시각 허용치(이미지의 0.2%)는 UI-04 크기의 회귀를 통과시킨다.** 되돌린 UI-04는 넓은 셸에서 1,146 px 차이였고 허용치는 2,592 px다. compact 골든은 현재 코드와 175 px 다른 채로 통과하고 있다(11-03). +- **이 영역 코드는 지난 기준 `af3d8e6` 이후 골든 4장과 `i18n.spec.ts`만 바뀌었다.** 그래서 09-29의 나머지 발견 7건(drill PASS 경로 없음, SW spec 전제, lab 성능 뒤집힘, 규모 기준선 커밋 없음, helper 두 벌, 죽은 가드, 커밋된 로그)은 모두 남아 있다. + +## 1. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template` 영역 11 | +| 커밋·상태·시점 | `d99301b`, 2026-11-01. 지난 리뷰 기준 `af3d8e6` 이후 이 영역에서 바뀐 것은 시각 골든 4장과 `tests/e2e/i18n.spec.ts`(UI-04 테스트 1개 추가)뿐이다. 나머지 영역 경로, drill·성능·규모 스크립트, `config/scale`, `config/ci`, `.gitea`, `.gitignore`는 `git diff --quiet af3d8e6 d99301b -- …`로 같다는 것을 확인했다 | +| 실행 환경 | Ubuntu 24.04.5, Node v24.14.0, Playwright 1.62.0(chromium 1234, firefox 1538, webkit 2336), Intel Core Ultra 7 155H(22 스레드), fontconfig 2.15.0. 다른 영역 에이전트가 동시에 돌아 실행 시점 loadavg는 3~25였다 | +| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker. SSR 없음 | +| 규모·운영 목표 | 선언 상한만 있다. 성능 예산은 `config/performance/budgets.json`. RPO/RTO 없음 | +| 확인하지 못한 범위 | storybook spec, lab 성능 재측정, main·nightly·release scale tier, 실제 CI 러너(U-1), 컨테이너 이미지 방식 실측(이미지 내려받기 필요), 11-01 수정 뒤 나머지 단언. 7절 | +| 이전 리뷰와 비교 | 2026-09-29 영역 11의 발견 9건을 현재 코드로 다시 확인했다(2절). 지난 실행 결과는 증거로 쓰지 않았다 | + +실행 목록. 무거운 실행은 모두 공용 `heavy.lock`으로 감쌌다. e2e·capability 세 엔진 실행은 메인 repo에서 기본 설정 그대로 했다(webServer가 build·preview를 한다). 시각·변이 실험은 `scratchpad/wt-11`(d99301b worktree, 원본 `node_modules` 심볼릭 링크)에서 했다. worktree 안에서는 pnpm을 부르지 않았다. 빌드는 `node scripts/…`로, 서빙은 `vite preview --strictPort`를 쓰는 설정 사본으로 했다. 글꼴 실험은 같은 dist에서 `FONTCONFIG_FILE`만 바꿨다. + +| 명령·실험 | 결과 | +|---|---| +| 오케스트레이터 게이트 `test_system.log`(이 커밋, 메인 repo) | 2 failed / 110 passed, 52.1초. `:1259` 기대 문자열(09-29/11-01), `:810` `ps failed: `(새 11-01) | +| `scratchpad/r11/close-then-ps.mjs`: child의 `close` 뒤 `/proc`·`ps`로 argv 조회 | 20/20 조회 실패. `ps` 종료 코드 1, stderr 빈 문자열(게이트 메시지와 같은 모양). loadavg 9.3 | +| `node scripts/run-vitest.ts run tests/release tests/architecture tests/scripts tests/scale` | 25파일 147개 통과, 6.5초(loadavg 21.9) | +| `npx playwright test --project=chromium --project=chromium-compact` | 56 통과, 0 실패, 벽시계 26초(build 포함). loadavg 8.7→10.3 | +| `npx playwright test --project=firefox` | 52 통과, 3 skip(SW quarantine), 0 실패, 36초. 9.5→12.5 | +| `npx playwright test --project=webkit` | 55 통과, 0 실패, 43초. 10.0→21.9 | +| `npx playwright test --config playwright.capabilities.config.ts`(3엔진) | 63 통과(엔진별 21), 0 실패, 34초. 14.8→21.9. `resumable-upload`의 하드코딩 포트가 설정 포트(4174)와 같아서 통과 | +| visual, 호스트 글꼴 | 5/5 통과, 6.3초. 빌드 1초(vite 315ms) | +| visual, 글꼴 A: Playwright가 Ubuntu 24.04에 까는 글꼴 + DejaVu | 0/5. 차이 3~8%(허용 0.2%). compact·gallery·개요 3장은 높이도 달라짐(1263→1388, 2162→2159, 3741→3756) | +| visual, 글꼴 B: Noto core + Noto CJK 디렉터리만 | 4/5. 플랫폼 개요 실패(4%, 높이 3741→3708) | +| visual, 글꼴 C: B + DejaVu Sans Mono | 4/5. 같은 장 실패 | +| visual, 글꼴 D: B + Liberation 디렉터리 | 5/5 통과 | +| CDP `CSS.getPlatformFontsForNode`로 4개 화면의 실제 글꼴(host·A·C) | host: Noto Sans 3,206 · Noto Sans CJK KR 4,338 · Noto Sans CJK KR Black 68 · Liberation Mono 1,674 글리프. A: DejaVu Sans · WenQuanYi Zen Hei · Liberation Mono. C: monospace만 DejaVu Sans Mono | +| 변이: UI-04 `shell.css` 변경을 되돌린 빌드 → visual, i18n 3엔진 | visual 5/5 통과(놓침). `i18n.spec.ts:28` 세 엔진 모두 실패(잡음) | +| 같은 변이 빌드, visual 허용치 0 | 넓은 셸 1,146 px, compact 175 px 차이 | +| 깨끗한 빌드, visual 허용치 0 | 넓은 셸 0 px. compact 175 px(골든이 낡음) | + +실행 뒤 메인 repo `git status`는 이 문서 폴더와 `.claude/`만 보인다. `/tmp`에 e2e fixture 복사본이 남지 않았다. + +## 2. 지난 발견 재확인 + +지난 문서의 ID는 이번 ID와 겹치지 않게 `09-29/11-NN`으로 적는다. 이 영역의 코드는 지난 기준 `af3d8e6` 이후 바뀌지 않았다(1절). 그래서 대부분 "남음"이다. 상태 판단은 현재 코드 위치로 했다. + +### 2.1 2026-09-29 영역 11 발견 + +| 지난 ID | 내용 | 상태 | 근거 | +|---|---|---|---| +| 09-29/11-01 | `tests/system` 기대 문자열이 출력과 달라 FE-GATE-013이 항상 실패 | **남음** (Medium 조정 · P1) | `scripts/verify-exact-promotion-bundle.ts:78`은 `Exact promotion bundle verification (${freshness}): PASS`를 출력한다. `tests/system/ci-runner/ci-artifact-contract.test.ts:1259`는 여전히 `…verification: PASS`를 기대한다. 이번 게이트 `test_system.log`의 실패 2건 중 1건이 이것이다(Expected/Received 차이가 정확히 `(current)`) | +| 09-29/11-02 | 운영 drill이 어떤 입력으로도 PASS 불가 | 남음 | `scripts/drill-runbook.ts:240`, `:270`, `:312`, `:353`의 `providerVerificationRequired: true` 상수 그대로. 입력 경로 추가 없음 | +| 09-29/11-03 | SW e2e 두 spec의 전제가 소스 문자열 치환에 숨어 있음 | 남음 | `tests/e2e/support/service-worker-builds.ts:125-129`가 `src/features/installed-runtime-capabilities.ts:39`의 `= null;` 줄을 정확히 1회 찾는다. spec 머리 주석·SW 켜기 체크리스트 변경 없음 | +| 09-29/11-04 | lab 성능 게이트 판정이 같은 빌드에서 뒤집힘 | 남음(코드 기준) | `scripts/test-performance.ts:175`, `:209`는 loadavg를 기록만 한다. 판정 코드(`scripts/lib/performance-budgets.ts`) 변경 없음. 이번에는 다시 돌리지 않았다(7절) | +| 09-29/11-05 | 규모 기준선에 소스 커밋이 없음 | 남음 | `config/scale/feature-shape-growth.json:3`에 `measuredAt`만 있다. 결과 생성부(`scripts/scale/measure-feature-shape-growth.ts:232-248`)에 커밋 필드 없음. 이번 UI 수정은 CSS만 바꿔 기능당 JS 수치에는 영향이 작다(추론) | +| 09-29/11-06 | cgroup 테스트가 부하에서 끝난 프로세스를 조회하다 실패 | **바뀜 → 새 11-01** | 원인을 다시 판정했다. 실패 지점은 `:810`이고, 이 줄은 `await execution.completion`(`:795`) 뒤에 이미 회수된 PID를 조회한다. 부하와 관계없이 항상 실패한다. 지난 판정(Low · P2, "부하 레이스")은 틀렸다 | +| 09-29/11-07 | 두 빌드 준비 helper가 두 벌, SW 쪽은 실패 시 복사본을 남김 | 남음 | `tests/e2e/support/fixture-builds.ts:18-27`(제외 목록에 `.tmp` 있음)과 `service-worker-builds.ts:39-47`(없음). `fixture-builds.ts:70-90`은 실패 시 지우고, `service-worker-builds.ts:113-146`은 지우지 않는다. fixture 쪽 spec 2개도 서버는 SW 파일의 `startBuildServer`를 가져다 쓴다(`boot-module-failure.spec.ts:10`, `old-tab-chunk-recovery.spec.ts:11`) | +| 09-29/11-08 | drill "상수 판정 금지" 테스트가 옛 모양(`true`)만 찾음 | 남음 | `tests/unit/runbook-drill.test.ts:122-127` 정규식 3개 그대로 | +| 09-29/11-09 | 규모 tier 실행 로그가 커밋돼 있음 | 남음 | `git ls-files 'artifacts/**/*.log'` 63개. `.gitignore`에 `*.log` 규칙 없음 | + +### 2.2 FOLLOW-UP 계열 항목 중 이 영역 + +| 항목 | 상태 | 근거 | +|---|---|---| +| `resumable-upload.spec.ts` 포트 하드코딩 | 남음 | `tests/browser-capabilities/resumable-upload.spec.ts:7` `PAGE_ORIGIN = "http://127.0.0.1:4174"` | +| SW update spec의 route chunk 변경을 helper 옵션으로 | 남음 | `tests/e2e/service-worker-update.spec.ts:47-56`이 spec 안에서 not-found 페이지에 export를 덧붙인다 | +| Firefox SW quarantine | 남음(만료 2027-03-31) | `service-worker-update.spec.ts:163`, `service-worker-recovery.spec.ts:80`. 이번 Firefox 실행에서 3건 skip | +| 지난 README 5절 "전체 리뷰 게이트 목록에 `test:system` 추가" | 부분 | 루트 `CLAUDE.md` 2단계 목록에는 아직 없다. 이번 오케스트레이터는 목록 밖에서 `test:system`을 돌렸고, 그 결과가 09-29/11-01과 새 11-01을 드러냈다 | + +## 3. 새 발견 사항 (36.3) + +심각도 분포: Critical 0 · High 0 · Medium 2 · Low 2. 우선순위: P1 2 · P2 1 · P3 1. + +### 11-01 `tests/system`의 cgroup 테스트는 provider가 끝난 뒤 그 PID의 argv를 조회해서, 부하와 관계없이 항상 실패한다 (09-29/11-06 원인 재판정) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 8, 24 (+30.8) | +| 근거 | 테스트 `tests/system/ci-runner/ci-artifact-contract.test.ts:749`. `:795`에서 `await execution.completion`을 기다린다. 이 Promise는 child의 `close`에서 풀린다(`:1641`). `close`가 오면 Node는 이미 child를 회수했다. 그런데 `:810`은 `observedArguments` 배열을 만들면서 `showProcessArguments(execution.child.pid)`를 다시 부른다. 이 함수는 `/proc//cmdline`을 읽고, 못 읽으면 `ps -o args= -p `를 부르고, 0이 아니면 `ps failed: `를 던진다(`:1859-1871`). 바로 위 주석(`:801-804`)은 "아래는 실행 기록을 읽고 live snapshot을 보지 않는다"라고 적는다. 코드는 주석과 다르다. **게이트 로그:** `test_system.log`에서 이 테스트는 `:810:7`에서 `Error: ps failed: `(stderr 빈 문자열)로 실패했다(2,671ms). **메커니즘 실험:** child를 띄우고 `close`를 기다린 뒤 같은 방식으로 조회하는 독립 스크립트(`scratchpad/r11/close-then-ps.mjs`)에서 20/20회 `/proc` 읽기 실패, `ps` 종료 코드 1, stderr 빈 문자열이었다(loadavg 9.3). 같은 테스트의 `:793`도 live 조회다. provider는 1.5초 뒤 끝나므로(`:759`) 부하가 있으면 `:793`에서 먼저 실패할 수 있다. 지난 라운드의 "부하에서 15~17초 뒤 실패"는 이쪽으로 보인다(추론). 이 줄은 `5cc41467`(2026-09-18)부터 있었다 | +| 발생 조건 | 전제(bwrap, systemd user manager, cgroup v2)를 갖춘 모든 호스트의 `test:system` 실행. 부하는 어느 줄에서 먼저 실패하는지만 바꾼다 | +| 영향 | 09-29/11-01의 문자열 한 줄을 고쳐도 FE-GATE-013은 여전히 빨갛다. 지난 라운드 계획은 이 테스트를 "부하 레이스, Low · P2, CI 켜기 전 부하 테스트"로 분류했다. 그래서 수정 순서 1번(11-01)만 끝내면 게이트가 초록이 된다고 읽힌다. 실제로는 그렇지 않다. 2026-09-18 이후 이 테스트가 통과할 수 있는 실행은 없었다(PID 재사용 같은 우연 제외, 추론) | +| 심각도·우선순위 | Medium · P1 — 09-29/11-01과 같은 성격이다(merge 게이트 결정적 실패, CI 꺼짐, 수정 몇 줄). 오케스트레이터가 지난 라운드에 11-01에 쓴 조정 규칙(High → Medium, P1 유지)을 그대로 적용했다 | +| 통제·증거 | 목표 M3 / 확인 M2 — 검사는 있지만 결정적으로 실패해서 실제 회귀를 구분하지 못한다 · E3(게이트 실행 + 메커니즘 실험) | +| 확실성과 남은 가정 | `:810`이 항상 실패한다는 것은 코드 순서와 실험으로 확정이다. 이 줄을 고친 뒤 나머지 단언(`:811-831`)이 통과하는지는 확인하지 못했다. 그 실험은 base fixture가 `corepack pnpm build:release-candidate`를 부르는 구조라(`:2261`) worktree에서 돌리지 않았다 | +| 결정의 근거 | 적용 제외 — 이미 있는 샘플러를 쓰지 않은 단순 결함이다. 같은 파일이 샘플러(`recordProviderProcessTree`, `:1901`)를 두고 이유를 적어 두었다 | +| 이해 비용 | 적용 제외 — 지역 결함. 다만 주석이 코드와 반대로 말해서 읽는 사람이 원인을 부하로 오해하기 쉽다(지난 라운드가 그랬다) | +| 최소 개선 방향 | supervisor 자신의 argv를 시작 직후 한 번 기록한다(또는 샘플러가 supervisor PID도 기록하게 한다). `:793`과 `:810`의 live 조회를 그 기록으로 바꾼다 | +| 대안 비교·보존 조건·재검토 | 적용 제외 — 계약을 바꾸지 않는 테스트 수정 | +| 비용·부작용 | 두세 줄 | +| 완료 기준 | 전제를 갖춘 호스트에서 `-t 'aggregate cgroup'`이 부하 없음 5회, loadavg 20 부근 5회 모두 통과한다. 09-29/11-01과 함께 고친 뒤 `test:system` 전체가 0 failed다 | +| 검증 방법 | `node scripts/run-vitest.ts run tests/system/ci-runner/ci-artifact-contract.test.ts -t 'aggregate cgroup'`를 반복 | +| 담당·기한·상태 | 미정 · 미정 · 신규(원인 재판정) | + +### 11-02 시각 회귀 골든이 작성자 PC의 글꼴 4종으로 찍혀 있고 실행 환경의 글꼴을 고정하지 않아, 같은 코드라도 글꼴이 다른 호스트(CI 러너 포함)에서 FE-GATE-008이 실패한다 (UI-05 남은 절반) + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 19, 20, 5, 16 (+30.8) | +| 근거 | **설정:** `playwright.visual.config.ts:16-37`은 Chromium(패키지 버전), color scheme, locale, animation·caret, `maxDiffPixelRatio: 0.002`만 고정한다. 글꼴·fontconfig·컨테이너 이미지는 고정하지 않는다. **토큰:** `src/presentation/design-system/tokens/semantic.css:33`의 첫 글꼴이 `system-ui`다(UI-05 결정 b). 코드 글자는 토큰 없이 브라우저 기본 `monospace`로 그려진다. 둘 다 호스트가 무엇을 고르느냐에 달려 있다. **골든:** `d99301b` 커밋 메시지가 "Captured on this Linux host's fonts"라고 적는다. **문서 주장:** `docs/testing/frontend-platform-testing-strategy.md` 13.4절 "OS, browser, font, device scale을 CI image로 고정", `docs/styling/design-system-platform.md` 10.3절 "동일한 Linux image, browser version, font". 코드에는 이 고정이 없다. **CI:** `.gitea/workflows/quality-gates.yml:37` `runs-on: ubuntu-latest`, `:69` `playwright install --with-deps …`. 컨테이너·글꼴 설치 단계가 없다. FE-GATE-008에 `test-visual`이 들어 있다(`config/ci/gates.json:1869-1878`). playwright-core 1.62.0이 Ubuntu 24.04에 까는 글꼴 패키지는 `fonts-freefont-ttf`, `fonts-ipafont-gothic`, `fonts-liberation`, `fonts-noto-color-emoji`, `fonts-tlwg-loma-otf`, `fonts-unifont`, `fonts-wqy-zenhei`, `xfonts-*`다. Noto Sans와 Noto Sans CJK는 없다. **실측(같은 dist, `FONTCONFIG_FILE`만 바꿈, 1절 실행표):** 작성자 PC 글꼴로 Chromium이 실제로 그린 글꼴은 Noto Sans, Noto Sans CJK KR, Noto Sans CJK KR Black(굵기 800), Liberation Mono 4종이다(CDP `CSS.getPlatformFontsForNode`). 호스트 글꼴 5/5 통과. 위 Playwright 글꼴 + DejaVu(맨 Ubuntu 러너 근사) 0/5 실패 — `system-ui`가 DejaVu Sans, 한글이 WenQuanYi Zen Hei로 바뀌고, 차이 3~8%(허용 0.2%), 이미지 5장 중 3장은 높이까지 달라졌다. Noto 2종만 둔 경우와 여기에 DejaVu Sans Mono를 더한 경우는 4/5 — 코드 글자가 Liberation Mono가 아니어서 플랫폼 개요 1장이 실패했다. Noto 2개 디렉터리와 Liberation 디렉터리만 보이게 하면 5/5 통과했다. 즉 지금 골든은 이 세 글꼴 묶음만 있으면 재현된다. | +| 발생 조건 | 글꼴 구성이 작성자 PC와 다른 곳에서 `test:visual`을 돌릴 때. CI 러너, 다른 개발자의 Linux, macOS(스냅샷 이름이 `-darwin`이라 기준선 자체가 없다) | +| 영향 | CI를 켜면 FE-GATE-008이 첫 실행부터 모든 PR에서 실패할 가능성이 높다(러너 글꼴은 U-1이라 미확인). 팀은 골든을 러너에서 다시 찍거나 시각 검사를 끄게 된다. 다시 찍으면 작성자 PC에서 실패한다. 템플릿을 받은 제품도 같은 골든을 그대로 받는다. 실패 diff는 글자 전체가 밀린 모습이라 코드 회귀와 글꼴 차이를 구분하기 어렵다 | +| 심각도·우선순위 | Medium · P1 — 지원하는 CI 조건에서 merge 게이트가 코드와 무관하게 실패한다. 09-29/11-01과 같은 조정 규칙을 적용했다(CI 꺼짐, 수정 비용 중간) | +| 통제·증거 | 목표 M3(코드 변화만 검출) / 확인 M2(작성자 PC에서만 M3) · E3 | +| 확실성과 남은 가정 | 글꼴 의존과 실패는 재현했다. 실제 Gitea 러너 이미지의 글꼴 구성은 모른다(U-1). 실험 A는 Playwright 의존 목록 + DejaVu로 만든 근사다 | +| 결정의 근거 | 4.1절. 확인한 사실(설정·토큰·실측), 기록된 의도(문서 2곳의 "이미지·글꼴 고정", UI-05 "남은 것"), 추론(러너 글꼴)을 나눴다 | +| 이해 비용 | 시각 테스트가 실패한 개발자는 설정에도 테스트에도 글꼴 얘기가 없어서 diff 이미지를 보고 글꼴 차이라는 것을 스스로 알아내야 한다. 문서는 이미 고정돼 있다고 말한다 | +| 최소 개선 방향 | 4.1절 (c′). 저장소에 `fonts.conf` 하나를 두고 Noto Sans·Noto Sans CJK·Liberation 디렉터리만 보게 한다. `playwright.visual.config.ts`가 `use.launchOptions.env`로 `FONTCONFIG_FILE`을 넘긴다. 시작 전에 sans·한글·monospace가 기대한 글꼴로 잡히는지 확인하고, 아니면 설치할 패키지 이름을 적어 실패한다. CI merge job에 그 패키지 설치 한 줄을 더한다. 실험 D대로라면 골든은 다시 찍지 않아도 된다. 문서 2곳의 문장을 실제 방식에 맞춘다 | +| 대안 비교 | 4.1절 (a)~(g). 컨테이너 이미지(b)는 가장 많이 고정하지만 Docker와 러너의 컨테이너 지원이 필요하다. 임계값 완화(f)는 VD-08 8항과 13.4절이 금지한다 | +| 단순화의 보존 조건 | 적용 제외 — 단순화가 아니라 고정 추가 | +| 비용·부작용 | 설정 파일 1개, 설정 몇 줄, CI 한 줄. 글꼴 바이트가 아니라 패키지 이름을 고정하므로 배포판 버전이 바뀌면 다시 흔들릴 수 있다(4.1절 재검토 조건). 시각 테스트는 실제 사용자 기기의 글꼴이 아니라 고정 글꼴을 본다(원래도 작성자 PC 글꼴이었다) | +| 재검토 조건 | macOS·Windows 개발자가 골든을 갱신해야 하면 (b′). 제품이 웹폰트를 싣게 되면(UI-05 대안 a) 고정 대상이 그 웹폰트와 fallback으로 줄어든다 | +| 완료 기준 | 바깥 `FONTCONFIG_FILE`을 이번 실험의 host·A로 바꿔도 `test:visual` 결과가 같다. 필요한 글꼴이 없으면 diff가 아니라 설치 안내 문구로 실패한다. 문서 2곳이 실제 고정 방식과 일치한다 | +| 검증 방법 | 이번 실험처럼 `FONTCONFIG_FILE`을 두 가지로 바꿔 `test:visual`을 돌린다. 고정이 들어가면 바깥 값과 무관해야 한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 11-03 시각 회귀 허용치가 "이미지 전체의 0.2%"라서 UI-04 회귀(1,146 px)를 통과시키고, 갱신되지 않은 compact 골든도 175 px 차이로 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 9 | +| 근거 | `playwright.visual.config.ts:20` `maxDiffPixelRatio: 0.002`. 허용 픽셀은 이미지 크기에 비례한다. 넓은 셸 1440×900은 2,592 px, compact 390×1263은 985 px, 플랫폼 개요 1040×3741은 7,781 px다. VD-08 8항은 "실제 layout, copy, theme 또는 상태 변화가 숨겨지도록 확대하지 않는다"고 적는다. **변이(worktree):** UI-04 수정(`5d2ed17`)의 `shell.css` 변경을 되돌려 선택 상자 값이 다시 잘리게 했다. `test:visual`은 5/5 통과했다. 같은 빌드를 허용치 0으로 돌리면 넓은 셸이 1,146 px 달랐다. 같은 변이를 `tests/e2e/i18n.spec.ts:28`은 세 엔진 모두에서 잡았다(부족 폭 chromium 6/34 px, firefox 4/32 px, webkit 12/40 px). **깨끗한 빌드:** 허용치 0에서 넓은 셸은 0 px로 정확히 같았다. compact 골든만 175 px 달랐다. `d99301b`는 compact 골든을 갱신하지 않았다(4장만 갱신). UI 수정이 만든 compact 화면의 변화가 허용치(985 px) 안이라 테스트가 실패하지 않았다 | +| 발생 조건 | 넓은 화면에서 글자 몇 개, 작은 배지 색, 선택 상자 값 잘림처럼 수백~수천 픽셀 규모의 변화. 긴 전체 화면 캡처일수록 허용치가 커진다 | +| 영향 | 시각 게이트가 사용자가 보는 작은 회귀를 놓친다. UI-04는 지금 전용 e2e가 막지만, 같은 크기의 다른 회귀에는 그런 검사가 없다. 골든이 현재 코드와 조금씩 달라져도 실패하지 않으니, 골든에 결함이 들어가도 모른다(UI 감사가 UI-04를 골든 안에서 발견한 것과 같은 경로) | +| 심각도·우선순위 | Low · P2 — 피해는 화면 품질에 한정된다. 고치는 비용은 11-02 뒤에 설정 한 줄과 골든 1장이다 | +| 통제·증거 | 목표 M3 / 확인 M2 · E3(변이) | +| 확실성과 남은 가정 | 변이 결과로 확정이다. 0 px 허용이 다른 Linux 호스트에서도 흔들리지 않는지는 11-02의 글꼴 고정이 들어간 뒤에 확인할 수 있다 | +| 결정의 근거 | 비율 허용치는 "작은 rasterization 차이"를 흡수하려는 값이다(VD-08 8항). 이 호스트에서 깨끗한 빌드의 래스터 차이는 0 px였다. 즉 지금 허용치가 흡수하는 것은 래스터 차이가 아니라 글꼴 차이와 실제 변화다(리뷰어 추론) | +| 이해 비용 | 골든을 갱신하는 사람은 어느 골든이 갱신 대상인지 실패로 알 수 없다. compact 골든처럼 "통과하지만 낡은" 상태가 보이지 않는다 | +| 최소 개선 방향 | 11-02로 글꼴을 고정한 뒤 `maxDiffPixelRatio`를 작은 절대값 `maxDiffPixels`(예: 0~50)로 바꾼다. compact 골든을 다시 찍는다 | +| 대안 비교 | (a) 현상 유지: 회귀를 놓친다. (b) 화면 대신 위험 영역(머리글, 표)만 따로 찍어 비율 허용치의 분모를 줄인다: 골든이 늘어난다. (c) 절대값 허용치: 설정 한 줄. 글꼴이 고정되지 않으면 실패가 늘어서 11-02가 먼저다. (c)가 가장 작다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 글꼴 고정 전에는 적용할 수 없다. Chromium을 올릴 때 래스터가 바뀌면 골든 갱신이 필요해진다(원래도 필요) | +| 재검토 조건 | 글꼴을 고정했는데도 호스트 사이 래스터 차이가 수십 px 넘게 나오면 허용치를 그 측정값으로 정한다 | +| 완료 기준 | 위 UI-04 변이에서 `test:visual`이 실패한다. 깨끗한 빌드에서 5장 모두 통과한다 | +| 검증 방법 | 이번 변이(`git apply -R` UI-04 `shell.css` 패치)를 다시 넣고 `test:visual` | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 11-04 테스트 전략 문서의 "필수 baseline" 목록과 실제 시각 기준선이 다르고, 검사는 기준선 4장 이상만 본다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함(문서 주장과 구현의 불일치) | +| 관련 관점 | 5, 24, 10, 9 | +| 근거 | `docs/testing/frontend-platform-testing-strategy.md` 13.4절은 "필수 baseline"으로 각 page template, 모든 primitive group, invalid form, open dialog/drawer/menu, light/dark, pseudo-locale/RTL 대표 등을 적는다. 실제 기준선은 5장이다(`tests/visual/platform.visual.spec.ts:13-65`). invalid form, 열린 dialog·menu, RTL, page template별 기준선은 없다. `scripts/check-test-evidence.ts:409-410`은 기준선이 4장 이상인지만 본다. VD-08 5항은 최초 기준선을 지금의 범위로 적는다. 두 문서가 서로 다른 말을 한다 | +| 발생 조건 | 다운스트림이 전략 문서를 보고 dialog·폼 오류 화면이 시각 회귀로 보호된다고 믿을 때 | +| 영향 | 보호되지 않는 화면을 보호된다고 오해한다. 피해는 화면 품질 회귀를 늦게 아는 것에 한정된다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M1(문서만) · E1 | +| 확실성과 남은 가정 | 목록과 파일 비교로 확정이다. state 화면 기준선이 401/403/404를 모두 담는지는 따로 확인하지 않았다 | +| 결정의 근거 | 적용 제외 — 문서와 구현 중 어느 쪽을 맞출지의 단순 정리다 | +| 이해 비용 | 적용 제외 | +| 최소 개선 방향 | 13.4절의 목록을 "현재 기준선 5장(VD-08 5항)"과 "제품이 늘릴 후보"로 나눈다. 기준선을 늘리는 것은 11-02·11-03 뒤가 싸다 | +| 대안 비교·보존 조건·재검토 | 적용 제외 | +| 비용·부작용 | 문서 몇 줄 | +| 완료 기준 | 전략 문서, VD-08, 실제 기준선이 같은 범위를 말한다 | +| 검증 방법 | 문서 목록과 `tests/visual/__snapshots__` 파일 비교 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 4. 설계 선택 설명 (41절) + +### 4.1 시각 회귀의 실행 환경: 무엇을 고정하고, 글꼴은 어떻게 고정할 것인가 + +1. **무엇이 필요한가:** production build의 화면이 의도와 다르게 바뀌면 PR에서 실패해야 한다(FE-GATE-008, VD-08 4항). 소비자는 PR 작성자와 리뷰어, 템플릿을 받은 제품이다. 실행 장소는 작성자 PC와 CI 러너(U-1, `ubuntu-latest`)다. +2. **지킬 성질:** 같은 커밋이면 어느 지원 호스트에서도 같은 판정. 레이아웃·문구·테마 변화는 실패. 기준선은 명시적 명령으로만 바뀐다(VD-08 7항). 임계값을 키워 차이를 숨기지 않는다(VD-08 8항, 13.4절). +3. **현재 보장:** Chromium 버전(`@playwright/test` 1.62.0 고정), viewport, color scheme, locale, animation·caret, `scale: "css"`, 임계 0.2%(`playwright.visual.config.ts:16-37`). 전체 화면 mask 금지와 기준선 4장 이상은 `scripts/check-test-evidence.ts:307-309`, `:405-410`이 검사한다. **보장하지 않는 것:** 글꼴. 제품 토큰은 의도적으로 기기 글꼴을 쓴다(UI-05 결정 b, `semantic.css:33`). 그래서 골든은 "작성자 PC가 고른 글꼴 4종"(Noto Sans, Noto Sans CJK KR, 같은 글꼴 Black, Liberation Mono)에 묶인다(1절 실행표의 CDP 실측). +4. **대안:** + - (a) 현상 유지. + - (b) Playwright 공식 컨테이너 이미지(`mcr.microsoft.com/playwright:v1.62.0-noble`)를 digest로 고정하고 갱신·비교를 모두 그 안에서 한다. + - (b′) (b)를 바탕으로 Noto·Liberation 글꼴 패키지를 더한 파생 이미지. + - (c) 글꼴 파일을 저장소에 두고(`tests/visual/fonts/`), 그 폴더만 가리키는 `fonts.conf`를 `FONTCONFIG_FILE`로 브라우저에 넘긴다. + - (c′) 글꼴은 OS 패키지로 설치하고(`fonts-noto-core`, `fonts-noto-cjk`, `fonts-noto-cjk-extra`, `fonts-liberation`), 저장소의 `fonts.conf`가 그 디렉터리만 보게 한다. 시작 전에 세 갈래(sans·한글·monospace)가 기대한 글꼴로 잡히는지 확인하고, 아니면 설치 명령을 알려 주며 실패한다. + - (d) 시각 테스트에서만 `@font-face`를 주입해 `--font-sans`를 덮는다. + - (e) 제품이 웹폰트를 싣는다(UI-05 대안 a). + - (f) 임계값을 올린다. + - (g) 골든을 CI에서만 찍고 비교한다. +5. **대안별 비용:** + +| 대안 | 고정 범위 | 현재 골든 | 비용·한계 | +|---|---|---|---| +| (a) | Chromium만 | 작성자 PC에서만 통과 | 비용 0. 다른 호스트에서 0/5(실험 A) | +| (b) | OS 라이브러리·글꼴·브라우저 전부 | 다시 찍어야 함(이미지가 같은 Playwright 의존 목록으로 글꼴을 깔므로 실험 A와 같은 계열일 것이다, 추론) | Docker와 이미지 수 GB. 러너가 job container를 지원해야 한다. `@playwright/test`를 올릴 때 이미지 태그도 함께 올려야 한다(두 곳 동기화). macOS 개발자도 같은 결과를 낸다 | +| (b′) | (b) + 한국어 글꼴 | 그대로 쓸 가능성이 큼(패키지가 같으면, 미확인) | (b) 비용 + Dockerfile 관리 | +| (c) | 글꼴 바이트 | 작성자 PC 파일을 그대로 넣으면 유지. 다른 글꼴(예: KR 서브셋)이면 다시 찍음 | 지금 쓰는 CJK `.ttc`는 굵기마다 약 19 MB다(Regular·Bold·Black만 해도 약 58 MB). 서브셋으로 줄이면 골든을 다시 찍는다. Linux 전용(macOS Chromium은 fontconfig를 안 쓴다). OFL 라이선스 파일 필요 | +| (c′) | 글꼴 패밀리와 디렉터리 | **그대로 유지** — Noto 2개 디렉터리 + Liberation만 보이게 했을 때 5/5 통과(실험 D) | 설정 파일 1개, 설정 몇 줄, CI에 `apt-get install` 한 줄. 배포판 패키지 버전이 바뀌면 글자 모양이 바뀔 수 있다(바이트 고정 아님). Linux 전용 | +| (d) | 주입한 글꼴 | 다시 찍음 | 제품이 실제로 쓰는 글꼴 스택을 검사하지 않게 된다. 주입 글꼴에 없는 글자는 여전히 호스트 글꼴로 떨어진다 | +| (e) | 제품 글꼴 | 다시 찍음 | 전송량·라이선스가 제품 비용이 된다. UI-05는 시스템 글꼴을 골랐고 웹폰트는 서비스가 요구할 때로 미뤘다 | +| (f) | 없음 | — | 실험 A 차이는 3~8%다. 그만큼 올리면 실제 회귀도 통과한다. VD-08 8항 위반 | +| (g) | 러너에 따라 | 다시 찍음 | CI가 꺼져 있다(U-1). 개발자는 로컬에서 확인할 수 없다 | + +6. **현재 조건에서의 판단:** 기록된 의도는 두 가지다. "동일한 Linux image, browser version, font"(`design-system-platform.md` 10.3절)와 "저장소 안에서 외부 서비스 없이 실행"(VD-08 10항). 작성자와 CI는 모두 Linux다. 이 조건에서는 (c′)가 가장 작다. 현재 골든을 그대로 쓸 수 있다는 것을 실험 D로 확인했다. 시작 전 글꼴 확인을 넣으면 "글꼴이 다르다"는 사실이 diff 대신 오류 문구로 드러난다(리뷰어 추론). 바이트까지 고정해야 하거나 macOS·Windows 개발자가 골든을 갱신해야 하면 (b′)가 맞다. +7. **재검토 조건:** macOS·Windows 개발자가 기준선을 갱신해야 할 때 → (b′). 러너 배포판이 바뀌어 같은 패키지로 골든이 흔들릴 때 → (b′) 또는 (c). 제품이 웹폰트를 싣기로 하면(UI-05 대안 a) → 고정 대상이 그 웹폰트와 fallback으로 줄어든다. `@playwright/test`를 올릴 때는 어느 대안이든 골든을 다시 확인한다. + +### 4.2 merge 게이트에서 e2e를 세 엔진으로 모두 돌린다 + +1. **무엇이 필요한가:** 엔진마다 다른 동작(select의 기본 폭, Service Worker, 동적 import 실패 로그, IndexedDB)을 PR 단계에서 잡는다. 소비자는 PR 작성자다. +2. **지킬 성질:** 지원 브라우저에서 핵심 흐름이 같게 동작한다. 재시도로 흔들림을 숨기지 않는다. +3. **현재 보장:** 프로젝트 4개(`playwright.config.ts:23-48`), retries 기본 0, `forbidOnly`. CI가 세 엔진을 설치한다(`quality-gates.yml:69`). spec이 엔진별 차이를 코드로 다룬다(`old-tab-chunk-recovery.spec.ts:60-64`의 엔진별 허용 로그, Firefox SW quarantine `service-worker-update.spec.ts:163`). 이번 실행: chromium 56/56(26초), firefox 52 통과·3 skip(36초), webkit 55/55(43초). **보장하지 않는 것:** Firefox에서의 SW 업데이트·복구(quarantine, 만료 2027-03-31). 실제 Safari·모바일 기기. +4. **대안:** (a) 현상 유지. (b) PR은 chromium만, main·nightly에서 세 엔진. (c) 세 엔진 유지, 엔진과 무관한 fixture 빌드는 한 번만. +5. **대안별 비용:** (a) 이 호스트(11 worker)에서 세 엔진 합계 약 105초, 테스트 시간 합계 378초(74.7 + 116.9 + 186.6). 2 worker 러너라면 테스트만 약 3분으로 추정한다. (b) PR 시간은 3분의 1이지만 엔진 회귀를 merge 뒤에 안다. 이번 UI-04 테스트처럼 엔진마다 값이 다른 검사가 늘고 있다. (c) fixture 빌드는 엔진마다 7번(SW update 2, SW recovery 2, old-tab 2, boot 1), 세 엔진이면 21번이다. 하지만 빌드 1번이 약 1초(vite 315ms + 복사 21 MB)라 줄일 이득이 작다. +6. **현재 조건에서의 판단:** (a) 유지가 타당하다. 비용이 작고, 엔진별 분기가 코드에 실제로 있다. +7. **재검토 조건:** 러너가 2코어 이하이고 FE-GATE-008이 10분을 넘으면 (b)나 shard를 검토한다. Firefox quarantine 만료일(2027-03-31)에 Playwright Firefox의 SW 지원을 다시 확인한다. + +## 5. 이번 라운드 추가 렌즈 + +### 5.1 테스트가 위험을 실제로 잡는가 + +| 위험 | 검사 | 이번 확인 | 판단 | +|---|---|---|---| +| 머리글 선택 상자 값 잘림(UI-04) | `tests/e2e/i18n.spec.ts:28` | 변이를 세 엔진 모두 잡음. 실패 메시지가 언어별 부족 폭을 보여 준다 | 잡는다. 글꼴과 무관하게 "브라우저가 필요하다는 폭"과 비교해서 호스트에 덜 흔들린다 | +| 같은 회귀를 화면 비교로 | `tests/visual/platform.visual.spec.ts:13` | 1,146 px 차이로 통과 | 못 잡는다(11-03) | +| 화면 변화 일반 | 시각 회귀 5장 | 다른 글꼴 호스트에서 0/5 | 코드가 아니라 호스트를 잡는다(11-02) | +| provider 샌드박스 argv 유출 | `ci-artifact-contract.test.ts:749` | 결정적 실패 | 신호가 없다(11-01) | +| 엔진별 동작 차이 | e2e·capability 세 엔진 | 226 통과, 0 실패, Firefox SW 3건 quarantine | 잡을 준비가 돼 있다. 이번에는 실패가 없었다 | + +지난 라운드의 a11y·스키마 변이는 코드가 그대로라 다시 하지 않았다. 그 결과를 이번 증거로 쓰지 않는다. + +### 5.2 성능(테스트 실행 비용) + +| 대상 | 측정 | 조건 | +|---|---|---| +| e2e chromium + compact | 56개, 벽시계 26초, 테스트 시간 합계 74.7초 | 11 worker, loadavg 8.7~10.3 | +| e2e firefox | 55개(3 skip), 36초, 합계 116.9초 | loadavg 9.5~12.5 | +| e2e webkit | 55개, 43초, 합계 186.6초 | loadavg 10.0~21.9 | +| 가장 오래 걸리는 spec | `accessibility.spec.ts` 20.5 / 28.7 / 39.3초(chromium/firefox/webkit) | 합계 기준 | +| capability 3엔진 | 63개, 34초 | loadavg 14.8~21.9 | +| visual | 5개, 6.3초 | 1 worker | +| 프로덕션 빌드 1회 | 약 1초(vite 315ms) | worktree | +| `test:system` | 112개, 52.1초. 가장 긴 테스트 7.1초 | 게이트 로그 | +| 영역 vitest | 25파일 147개, 6.5초 | loadavg 21.9 | + +e2e는 엔진마다 fixture 빌드를 7번 한다(SW update 2, SW recovery 2, old-tab 2, boot 1). 세 엔진이면 21번이다. Firefox에서는 SW recovery 테스트가 본문 안에서 skip되므로 그 빌드 2번은 쓰이지 않는다(`service-worker-recovery.spec.ts:81`). 빌드 1번이 약 1초이고 복사량이 21 MB라 지금은 비용이 작다. 결함으로 올리지 않았다. + +### 5.3 폴더 구조 + +- `tests/e2e/support/`에 두 빌드 helper가 있다. fixture 쪽 spec 2개도 서버(`startBuildServer`)를 SW 이름의 파일에서 가져온다(`boot-module-failure.spec.ts:10`, `old-tab-chunk-recovery.spec.ts:11`). 일반 서버가 SW 파일에 있어 찾기 어렵다. 09-29/11-07을 고칠 때 함께 정리한다. +- 스크립트 테스트의 위치 규칙이 없다. `tests/scripts`에는 2개뿐이고, `tests/unit` 148개 중 53개가 `scripts/`를 시험한다. 스크립트 테스트를 찾는 사람은 `tests/scripts`부터 보게 된다. 결함으로 올리지는 않았다. 규칙을 한 줄 정하거나(`tests/unit`로 모으기) 지금대로 두고 README에 적는 것 중 하나면 된다. +- `tests/system/ci-runner/ci-artifact-contract.test.ts`는 2,515줄이고 describe 3개(validator, provider 경계, finalizer)를 담는다. 나누면 base fixture(`build:release-candidate`)를 파일마다 다시 만들게 되므로 지금은 나누지 않는 쪽이 싸다. +- `tests/visual/__snapshots__`와 spec, 설정의 위치는 책임과 맞다. 다만 글꼴 고정 파일(11-02)이 생기면 `tests/visual/` 아래에 두는 것이 찾기 쉽다. + +### 5.4 리팩토링 후보 + +| 후보 | 무엇을 왜 | 보존해야 할 동작·타입·실패 계약 | +|---|---|---| +| R-1 두 빌드 helper 통합(09-29/11-07) | `service-worker-builds.ts`가 `prepareFixtureBuilds`를 쓰고 SW 선택·probe 치환만 `edit`로 넘긴다. `startBuildServer`를 공용 파일로 옮긴다. 중복 약 60줄과 실패 시 정리 차이가 없어진다 | 작업 트리·`dist`를 건드리지 않는다. 빌드 ID 주입. `edit`가 그 빌드 직전에 돌고 다음 빌드에 남는 순서. 준비 실패 시 임시 폴더 삭제. 치환 대상이 정확히 1회일 때만 진행(`replaceOnce`) | +| R-2 cgroup 테스트의 live 조회 제거(11-01) | supervisor argv를 시작 때 기록하고 `:793`·`:810`이 그 기록을 본다 | 실행 전체 동안 어떤 argv에도 command·credential이 없다는 단언. systemd-run·guardian·wrapper·bwrap·provider가 각각 관측된다는 단언. 4초 안 완료 | +| R-3 시각 허용치를 비율에서 절대값으로(11-03) | 11-02 뒤에 `maxDiffPixelRatio` → `maxDiffPixels` | animation·caret 비활성, 전체 화면 mask 금지(`check-test-evidence.ts:307-309`), 갱신은 `test:visual:update`로만 | + +## 6. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. + +| 번호 | 관점 | 판정 | 이유와 근거 | +|---|---|---|---| +| 1 | 코드 성숙도 | > | src 담당 영역 | +| 2 | 구조적 성숙도 | > | 12 | +| 3 | 변경 용이성 | P | 기대값을 레지스트리에서 읽는다. SW harness는 소스 문자열에 묶여 있다(09-29/11-03 남음) | +| 4 | 인지 부하 | P | 시각 테스트의 글꼴 의존이 설정·spec 어디에도 없다(11-02). SW spec 전제는 코드를 거꾸로 읽어야 안다(09-29/11-03) | +| 5 | 위험 가시성 | P | drill record는 관측 못 한 항목을 적는다. cgroup 테스트 주석은 "기록을 본다"고 하지만 live 조회를 한다(11-01). 문서는 글꼴이 고정돼 있다고 말한다(11-02, 11-04) | +| 6 | 실패 성숙도 | O | 429 재시도, 스키마 위반 표시, 청크 누락 뒤 1회 reload, 부트 오류 화면, 깨진 SW 해제가 이번 실행에서 통과했다(SW 해제는 chromium·webkit, Firefox는 quarantine) | +| 7 | 운영 성숙도 | P | drill은 거짓 PASS를 내지 않지만 PASS 경로가 없다(09-29/11-02 남음, `drill-runbook.ts:240` 외 3곳) | +| 8 | 디버깅 가능성 | P | trace `retain-on-failure`. UI-04 테스트는 언어별 부족 폭을 보여 준다. `ps failed: `는 원인을 말하지 않는다(11-01). 글꼴 차이는 화면 전체가 밀린 diff로만 보인다(11-02) | +| 9 | 유지보수 성숙도 | P | helper 두 벌(09-29/11-07), 낡은 규모 기준선(09-29/11-05), 커밋된 로그 63개(09-29/11-09), 낡은 compact 골든(11-03) | +| 10 | 테스트 성숙도 (깊게) | P | 강점: 세 엔진 e2e 163 통과·0 실패, capability 63/63, 재시도 0, 엄격 fixture, UI-04 변이를 세 엔진이 모두 잡음(모두 이번 실행). 약점: FE-GATE-013 결정적 실패 2건(09-29/11-01, 11-01), 시각 회귀가 호스트 글꼴을 검사하고(11-02) 작은 회귀를 놓침(11-03) | +| 11 | 데이터 성숙도 | - | 이 영역에 데이터 이관·보관 경로가 없다 | +| 12 | 동시성 성숙도 | O | 두 페이지·두 context로 BroadcastChannel, IndexedDB versionchange, cross-context 무효화를 확인하는 capability 테스트가 세 엔진에서 63/63 통과(이번 실행) | +| 13 | 확장성 (깊게) | P | pr scale tier가 FE-GATE-005에 있다(코드 무변경). 규모 기준선에 소스 커밋이 없다(09-29/11-05). 이번에 기능 성장 측정은 다시 하지 않았다 | +| 14 | 성능 성숙도 (깊게) | P | 테스트 실행 비용은 작다(5.2절). lab 성능 게이트의 판정 뒤집힘은 코드가 그대로다(09-29/11-04, 이번 미실행) | +| 15 | 보안 성숙도 | > | 13(`tests/system`의 샌드박스 내용). 이 영역은 테스트의 결정성(11-01)만 다룬다 | +| 16 | 의존성 성숙도 | P | `@playwright/test` 1.62.0 고정, 브라우저는 패키지가 고정. 시각 테스트가 기대는 OS 글꼴 패키지는 고정되지 않았다(11-02) | +| 17 | API / Contract | > | 07 | +| 18 | 배포 성숙도 (깊게) | P | 구 탭 청크 복구는 세 엔진, SW A→B 업데이트와 이전 캐시 응답은 chromium·webkit에서 통과(이번 실행). SW를 켠 제품에서는 spec이 준비 단계에서 멈춘다(09-29/11-03). provider 전환을 drill로 기록할 수 없다(09-29/11-02) | +| 19 | 설정 성숙도 | P | `resumable-upload.spec.ts:7` 포트 하드코딩 남음. 시각 테스트 실행 환경(글꼴)이 설정에 없다(11-02) | +| 20 | 개발자 경험 | P | spec 하나도 전체 빌드를 하지만 빌드가 1초라 부담이 작다. 다른 글꼴 호스트·macOS에서는 시각 테스트를 돌릴 수 없다(11-02). worktree에서 `test:system`이 돌지 않는다(영역 13) | +| 21 | Guardrail 성숙도 | X | 이 영역이 담는 merge 게이트 두 개가 CI를 켜면 코드와 무관하게 실패한다. FE-GATE-013은 확정(09-29/11-01, 11-01), FE-GATE-008의 시각 회귀는 러너 글꼴이 다르면 실패(11-02, 러너 미확인). `forbidOnly`·quarantine 만료 검사는 동작한다 | +| 22 | 추상화 성숙도 | P | 두 빌드 helper(09-29/11-07). 나머지 helper는 얇다 | +| 23 | 일관성 | P | 공용 엄격 fixture를 쓴다. helper 두 벌의 제외 목록·정리가 다르다. 스크립트 테스트 위치 규칙이 없다(5.3절) | +| 24 | 네이밍 / 의미 | P | cgroup 테스트 주석이 코드와 반대다(11-01). "keeps no constant recovery verdict"는 실제 검사보다 넓다(09-29/11-08). 문서의 "필수 baseline"·"글꼴 고정"이 구현과 다르다(11-04, 11-02) | +| 25 | 조직 확장성 | > | 14 | +| 26 | Ownership 성숙도 | P | quarantine에 owner·expires가 있다. `test:system`은 아직 루트 `CLAUDE.md` 게이트 목록 밖이다. 골든을 어느 환경에서 갱신하는지 적힌 곳이 없다(11-02) | +| 27 | 삭제 가능성 | P | 커밋된 로그를 다운스트림이 매번 지워야 한다(09-29/11-09). 시각 테스트는 production 코드 변경 없이 뗄 수 있다(VD-08 Rollback) | +| 28 | 회복 가능성 (깊게) | P | 깨진 SW를 `REMOVE_REGISTRATION`으로 해제하는 흐름과 구 탭 청크 복구가 통과(이번 실행). provider 전환 뒤 smoke를 증거로 넣을 방법이 없다(09-29/11-02). 이전 release 재검증 경로의 system test가 실패한다(09-29/11-01) | + +집계(적용 22개): 충족 2(6, 12) · 부분 충족 19 · 미충족 1(21) · 미검증 0 · 적용 제외 1(11) · 다른 영역 5. +지난 라운드와 달라진 곳: 16은 O → P(시각 테스트의 OS 글꼴 의존). 21은 P → X(FE-GATE-013이 문자열 하나로는 고쳐지지 않는다는 것과 FE-GATE-008의 호스트 고정이 이번에 드러남). 12는 이번에 세 엔진으로 확인해 근거가 강해졌다. + +## 7. 미검증 목록 + +| 무엇 | 왜 확인하지 못했나 | 무엇이 있으면 확인할 수 있나 | +|---|---|---| +| 실제 CI 러너의 글꼴 구성과 job container 지원 | Gitea runner가 없다(U-1) | 같은 커밋의 FE-GATE-008 실행 기록, 러너 이미지 이름 | +| 컨테이너 이미지 방식(4.1 b·b′)의 실측 | 이미지 내려받기가 필요하다(이 리뷰 범위의 허가 밖) | `mcr.microsoft.com/playwright:v1.62.0-noble`에서 `test:visual` 1회 | +| 11-01 수정 뒤 cgroup 테스트의 나머지 단언 | base fixture가 `corepack pnpm build:release-candidate`를 불러서 worktree에서 돌리지 않았다 | `.git`이 디렉터리인 clone에서 `:793`·`:810`을 고친 뒤 `-t 'aggregate cgroup'` | +| storybook spec(`test:storybook`) | 이번 지시 범위는 e2e 세 엔진이었다. storybook 빌드가 필요하다 | `test:storybook` 1회 | +| lab 성능(09-29/11-04) 재측정 | 코드가 그대로이고 부하 조건(loadavg 3~25)이 지난번과 같은 문제를 갖는다 | 부하 없는 기계에서 10회 | +| main·nightly·release scale tier, 기능 성장 재측정 | 기준선 CPU와 긴 시간이 필요 | 기준선 기계에서 `check:scale:nightly`, `measure-feature-shape-growth.ts` | +| 글꼴 패키지 버전이 바뀔 때 골든 흔들림 | 이 호스트의 패키지 하나만 확인했다 | 다른 Ubuntu 릴리스에서 (c′) 설정으로 `test:visual` | +| state 화면 기준선이 401/403/404를 모두 담는지 | 11-04 범위 밖으로 두었다 | `/examples/states` 화면과 골든 비교 | diff --git a/docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md b/docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md new file mode 100644 index 00000000..be72bf8d --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md @@ -0,0 +1,296 @@ +# 12 — 가드레일·CI 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 영역 판정(35.8): **조건부 사용 가능** — 이번 브랜치의 디자인 규칙 4개는 직접 위반을 모두 잡는다. 다만 컴포넌트 토큰 규칙은 접두어 일치 때문에 지금 이 커밋에서 읽히지 않는 토큰 하나(`--field-border`)를 놓친다(12-01). 규칙 4개를 지키는 음성 fixture가 없어서 규칙을 꺼도 모든 게이트가 통과한다(12-02). 지난 라운드 발견 7건은 코드가 바뀌지 않아 모두 남았다. + +## 0. 결론 + +- **지난 라운드 12번 발견 7건은 모두 남았다.** `af3d8e6` 이후 커밋 11개는 UI 감사 수정과 문서뿐이다. 가드레일 쪽 변경은 `scripts/check-design-system.ts`(+84줄)와 `scripts/lib/oklch-contrast.ts`(새 파일)뿐이다. +- **새 디자인 규칙 4개는 직접 위반을 잡는다.** 옛 포커스 색, `in oklch` 혼합, 읽히지 않는 토큰, `Inter` 첫 글꼴을 넣으면 각각 실패했다(probe A1~A4). +- **컴포넌트 토큰 규칙은 이름의 앞부분만 맞춰 본다(12-01, Medium).** `var(--field-border` 문자열이 `var(--field-border-invalid)` 안에도 있다. 그래서 `--field-border`를 읽는 스타일이 0개인데 검사가 통과한다. 입력란 테두리는 토큰 대신 계산식을 직접 쓴다. UI 감사 기록은 UI-03을 "충족"으로 닫았다. +- **규칙 4개를 지키는 테스트가 없다(12-02, Low).** 네 규칙을 모두 끄고 옛 포커스 색과 `Inter`를 다시 넣어도 `check:design-system` 통과, `--fixture`의 "기대 실패" 충족, 관련 테스트 16개 통과였다. +- **규칙이 정해진 파일과 정해진 글자만 본다(12-03, Low).** `in OKLCH`(대문자), `linear-gradient(in oklch, …)`, TSX 인라인 스타일, `base.css`의 토큰 재정의, feature 폴더의 CSS 파일이 모두 통과한다. feature CSS에 `#ff0000`을 써도 `check:design-system`과 `check:architecture`가 모두 통과했다. +- **정상 CSS를 거부하는 경우가 있다(12-04, Low).** 포커스 규칙은 `color-mix()`·알파·`deg` 단위로 쓴 표면 토큰을 거부한다. 글꼴 규칙은 `-apple-system`과 JS·패키지로 싣는 글꼴을 거부한다. 규칙 설명은 코드 주석에만 있다. +- **npm script 142개 중 사문화된 것이 4개 있다(12-05, Low).** `scan:security:fixture`는 다른 검사로 대체됐고 테스트가 "게이트에 없어야 한다"고 단언하는데 package.json에 남아 있다. 게이트 밖 스크립트 검사는 이름이 `check|verify|test|drill|review`로 시작하는 것만 봐서 이것을 못 잡는다. `build:profile`, `generate:contract-set`, `build:app-only`는 어디서도 안내하지 않는 빌드 단계 별칭이다. +- **중복 실행은 의도된 것 하나가 크다.** FE-GATE-005는 `test:unit`·`test:contract`를 돌린 뒤 `test:coverage`로 같은 테스트를 다시 돈다. 약 12초다. 층별 JUnit 증거를 따로 남기려는 구조라 발견으로 세지 않았다(6절). +- **머지 시점 강제는 이번에 다시 확인하지 않았다.** 외부 요청 금지 규칙 때문에 Gitea API를 부르지 않았다. 지난 라운드 판정(X)을 이번 증거로 쓰지 않고 `미확인`으로 둔다. + +## 1. 리뷰 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 12 | +| 커밋·작업 상태 | `fix/ui-design-audit-2026-11-01` / `d99301b`. 메인 작업 트리 미커밋 변경은 `.claude/`뿐이다 | +| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. CI는 Gitea Actions용 생성 workflow | +| 이전 리뷰와 비교 범위 | `af3d8e6..d99301b` 11커밋. 가드레일 파일 변경은 `scripts/check-design-system.ts`, `scripts/lib/oklch-contrast.ts`, `tests/unit/oklch-contrast.test.ts`뿐이다(`git diff --stat`). `.dependency-cruiser.json`, `eslint.config.ts`, `tsconfig*.json`, `config/ci/*`, `.gitea/`는 바뀌지 않았다 | +| 읽은 코드·설정 | `scripts/check-design-system.ts` 전체, `scripts/lib/oklch-contrast.ts` 전체, `tests/unit/oklch-contrast.test.ts`, `tests/unit/design-system-contract.test.ts`, 토큰 CSS 3개 전체, `src/presentation/styles/theme/*.css`의 포커스·배경·테두리 선언, `token-contract.ts`, `config/ci/gates.json`(명령·게이트·잡), `config/ci/ungated-*.json`, `scripts/lib/ungated-scripts.ts:1-60`, `scripts/lib/ungated-tests.ts:15-35`·`:88-108`, `scripts/build-frontend.ts:40-80`, `scripts/check-architecture.ts:85-135`·`:210-262`, `.gitea/workflows/quality-gates.yml:1-80`, `package.json` scripts 142개 전체. 지난 발견 재확인용 줄은 2절 | +| 읽은 문서(주장) | `docs/reviews/2026-11-01-ui-design-audit.md`(UI-01~05와 조치 결과 표), `PRODUCT.md:31-49`, `docs/styling/design-system-platform.md:100-210`, `docs/operations/ci-quality-gates.md:19-30`·`:60-66`, `docs/testing/frontend-platform-testing-strategy.md:35-60` | +| 게이트 결과 | 오케스트레이터가 이 커밋에서 실행한 결과를 읽었다(`scratchpad/gates/summary.txt`). `check:architecture`·`check:types`·`lint`·`test:unit`·`test:component`·`test:integration`·`test:contract`·`test:runtime-schema`·`verify:documentation`·`check:adapter-inventory`·`check:ci`·`check:design-system`·`check:i18n` 모두 rc=0. `test:system` rc=1(`ci-artifact-contract.test.ts` 2건, `ps failed` 등 — 영역 11) | +| 직접 실행 | worktree `scratchpad/wt-12`(`d99301b`, `node_modules`는 메인 링크, `pnpm` 미사용, 끝나고 삭제). `node scripts/check-design-system.ts` PASS(0.30초, 부하 9.8) · `--fixture` exit 1(기대대로) · 디자인 규칙 probe 18종(4절 표) · 검사기 변이 1종(12-02) · `check-architecture.ts`를 pnpm shim(`exec eslint`만 `node_modules/.bin/eslint`로 넘김)으로 실행 1회(B14, exit 0) · `node scripts/check-remediation-ledger.ts`(4건 실패) · `npx tsc -p` 타입 fixture 4개 시간 측정 · `npx vitest run` 3파일 16테스트 · 토큰 대비·gamut 계산 스크립트(`scripts/lib/oklch-contrast.ts` 사용) · npm script 참조 분석 스크립트 | +| 메인 repo에서 한 일 | 이 문서 작성. 그 밖에 `node scripts/generate-product-feature-index.ts`를 한 번 실행했다. 출력 폴더 `src/.generated`는 gitignore 대상이고 `git status`는 그대로였다 | +| 확인하지 못한 범위 | 9절 | + +## 2. 지난 발견 재확인 + +| ID(2026-09-29) | 내용 | 상태 | 현재 근거 | +|---|---|---|---| +| 12-01 | `check:request-fanout`이 반복 횟수·요청 의존을 보지 않음 | 남음 | `scripts/check-request-fanout.ts:23`(receiver 이름 정규식), `:109`(같은 줄 `fanout-reviewed:`만 인정), `:173-175`(메시지에 이유·탈출 경로 없음). 허용 fixture는 여전히 `allowed/bulk-read.ts` 하나다. 탈출 관례는 `docs/`에 없다(`grep fanout-reviewed docs` 0건) | +| 12-02 (= 08-02) | `check:i18n`이 "파일에 한글이 있는가"를 봄 | 남음 | `scripts/check-i18n.ts:12` `koreanLiteral = /[가-힣]/`, `:95-96` 파일 전체에 적용 | +| 12-03 | feature 안의 layer 폴더 밖 폴더에 경계 규칙 없음 | 남음 | `.dependency-cruiser.json:290-291` 규칙과 "Inside a feature, only its adapters/ folder reaches src/adapters" 주석이 그대로다. 파일이 바뀌지 않았다 | +| 12-04 | CI 계약 크기가 기준선과 테스트 상수 두 곳 | 남음 | `config/ci/contract-baseline.json`(98/103/109/5)과 `tests/unit/ci-workflow-generation.test.ts:196-203`의 상수. 문서 절차 `docs/operations/ci-quality-gates.md:23-27`에 테스트 갱신 단계가 없다 | +| 12-05 | 실행하지 않는 `dependency-cruiser` 의존성 | 남음 | `package.json:182` `"dependency-cruiser": "18.1.0"`. `scripts/check-architecture.ts:115-117`은 "이 그래프가 유일한 검사기"라고 적는다 | +| 12-06 | Vitest 폴더의 `*.spec.ts`를 "게이트 안"으로 셈 | 남음 | `scripts/lib/ungated-tests.ts:18`(`test|spec`), `:94-95`(폴더 접두어로 판정), `vitest.config.ts:25`(`*.test.{ts,tsx}`만 실행) | +| 12-07 | 예외 목록에 담당·재검토 시점 없음 | 남음 | `ungated-tests.ts:20-32`, `ungated-scripts.ts:17-29` 스키마가 `path|script`와 `reason`뿐이다. 항목 수 6·17개로 그대로다 | +| FOLLOW-UP | `check:remediation-ledger` 실패 | 남음 | worktree 실행 4건 실패(TR-02·TR-03·TR-04 마커 없음, 예산 55,700 문구 없음). `config/ci/ungated-scripts.json:17` 이유 문구 그대로. 결정자 없음 | +| FOLLOW-UP | `noUnusedParameters`, `no-deprecated` 미적용 | 남음 | `tsconfig.base.json:14`는 `noUnusedLocals`뿐이다. `eslint.config.ts`에 `no-deprecated`가 없다 | +| FOLLOW-UP U-1 | Actions 꺼짐·상태 0개 | 미확인 | 이번에는 API를 부르지 않았다. workflow 트리거는 그대로 `[main, develop]`이다(`.gitea/workflows/quality-gates.yml:4-7`) | + +## 3. 이번 라운드 추가 렌즈 — 디자인 규칙 4개의 우회와 오탐 + +`scripts/check-design-system.ts`에 들어온 규칙 4개를 같은 probe로 시험했다. worktree에서 한 번에 하나씩 파일을 바꾸고 `node scripts/check-design-system.ts`를 돌린 뒤 되돌렸다. probe 스크립트: `scratchpad/probes-12/ds-probes.sh`. + +| 규칙 | 위치 | 직접 위반 | 우회(통과하면 안 되는데 통과) | 오탐(실패하면 안 되는데 실패) | +|---|---|---|---|---| +| 포커스 대비 3:1 (UI-01) | `:87-126` | A1 옛 값 `oklch(0.72 0.16 225)` → 실패(2.23:1 등) | B8 `base.css`에서 `:root { --color-focus: … }` 재정의 → 통과. B9 `outline-offset: 0` → 통과(전제를 검사하지 않음) | B10 표면을 `color-mix(in oklab, …)`로 → 실패. B11 알파 `oklch(… / 0.9)` → 실패. B13 `oklch(52% 0.15 230deg)` → 실패 | +| `color-mix`는 oklab (UI-02) | `:54-59` | A2 `in oklch` → 실패 | B1 `in OKLCH` → 통과. B2 `linear-gradient(in oklch, …)` → 통과. B3 TSX 인라인 `"color-mix(in oklch, …)"` → 통과. B14 feature CSS 파일 → 통과 | B12 CSS 주석에 `color-mix(in oklch` 글자 → 실패 | +| 컴포넌트 토큰을 읽는 스타일 존재 (UI-03) | `:128-136` | A3 `var(--drawer-width)` 제거 → 실패 | **B4 현재 상태: `--field-border` 독자 0개 → 통과(12-01)**. B5 주석 안의 `var(--toast-width)`만 남김 → 통과 | 없음 | +| `--font-sans` 첫 글꼴 (UI-05) | `:138-162` | A4 `Inter, system-ui, …` → 실패 | B7 `base.css`에서 `--font-sans: Inter` 재정의 → 통과 | B6 `-apple-system, BlinkMacSystemFont, system-ui, …` → 실패. 패키지 import·``로 싣는 글꼴은 저장소 CSS에 `@font-face`가 없으면 실패(코드 판독, `:150-155`) | + +정리: + +- 규칙은 "토큰 파일과 `src/presentation/styles/**`의 글자"를 본다. 값은 `primitive.css`와 `semantic.css`에서만 읽는다(`:100-107`, `:156`). 그 밖의 위치는 보지 않는다. +- 직접 위반은 모두 잡힌다. 실패 메시지도 파일·토큰·대비값·해결 방향("use oklab")을 적는다. 지난 라운드의 fanout·i18n 메시지보다 낫다. +- 우회 대부분은 지금 템플릿에 없는 경로다. 템플릿의 CSS는 모두 검사 위치 안에 있다(`git ls-files 'src/**/*.css'` 10개). 문제는 다운스트림이 feature CSS나 브랜드 CSS를 추가할 때다. +- 지금 실제로 놓치고 있는 것은 B4 하나다(12-01). + +참고로 계산한 포커스 대비(현재 토큰, `scratchpad/probes-12/contrast.mjs`): + +| 테마 | 표면 8종 최저 | 검사 밖 인접색 | +|---|---|---| +| light | 4.24:1 (`surface-muted`) | `action` 1.02:1, `danger` 1.06:1 — offset이 0이 되면 기본 버튼 위에서 링이 안 보인다 | +| dark | 8.38:1 (`warning-surface`) | `action` 1.57:1 | + +## 4. 새 발견 사항 (36.3) + +### 12-01 컴포넌트 토큰 사용 규칙이 이름 앞부분만 맞춰 본다 — `--field-border`를 읽는 스타일이 없는데 통과하고, UI-03은 "충족"으로 닫혔다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 10, 9, 23, 24, 5 | +| 근거 | **규칙:** `scripts/check-design-system.ts:133` `source.includes(\`var(${token}\`)`. 닫는 괄호나 쉼표를 확인하지 않는다. **계약:** `token-contract.ts:50-51`에 `--field-border`와 `--field-border-invalid`가 둘 다 있다. 정의는 `component.css:5-6`. **독자:** `--field-border-invalid`만 `primitives.css:172`에서 읽는다. 정확한 이름(`var\(\s*--field-border\s*[,)]`)으로 세면 9개 중 `--field-border`만 0개다. **스타일:** `.ui-field__input`은 토큰 대신 `color-mix(in oklab, var(--color-content-muted) 55%, var(--color-panel))`를 직접 쓴다(`primitives.css:163-164`). **이력:** UI-02 커밋 `84dbb3a`가 바로 이 식을 `in oklch`에서 `in oklab`으로 고쳤다. UI-03 커밋 `4bb15e6`은 "네 토큰이 읽히지 않았다"며 이 규칙을 넣었다. **기록:** `docs/reviews/2026-11-01-ui-design-audit.md:193`은 UI-03을 "충족", 미사용 토큰 4개로 적는다. **probe B4:** `var(--field-border)`를 찾는 치환이 대상 파일 0개로 끝났고 검사는 PASS였다. B5: 독자를 주석 안에만 남겨도 PASS | +| 발생 조건 | 한 토큰 이름이 다른 토큰 이름의 앞부분일 때. 지금은 `--field-border`/`--field-border-invalid` 한 쌍이다. 주석 안에 `var(--x)`가 있을 때도 같다 | +| 영향 | 제품이 `--field-border`로 입력란 테두리를 바꿔도 화면이 바뀌지 않는다. "브랜드는 토큰으로만 바꾼다"(`PRODUCT.md:49`)가 이 지점에서 깨진다. UI-03이 막으려던 결함과 같은 종류인데 검사는 통과를 보고한다. 참고로 계약 토큰값(`--color-border-strong`)은 흰 패널 대비 6.52:1이고, 실제 계산식은 2.53:1이다(같은 계산 함수로 계산. 브라우저 실측은 안 했다. 접근성 판정은 영역 08) | +| 심각도·우선순위 | Medium · P2 — 데이터·보안 피해는 없다. 그러나 이번 브랜치가 닫았다고 기록한 결함이 지금 남아 있고, 검사가 그것을 가린다. 모든 다운스트림이 같은 규칙과 같은 토큰을 받는다 | +| 통제·증거 | 목표 M3 / 확인 M3(이름이 겹치지 않는 토큰만), 접두어 쌍은 M0 · E3(probe B4·B5, 정확 이름 집계) | +| 확실성과 남은 가정 | 규칙 동작과 미사용은 확정이다. `.ui-field__input`이 일부러 토큰과 다른 색을 쓰는지는 기록이 없어 모른다 | +| 결정의 근거 | 적용 제외 — 문자열 일치 조건의 누락이다. 입력란 테두리 색을 어느 값으로 할지는 별도 디자인 결정이다(아래 최소 개선 방향) | +| 이해 비용 | 검사 결과를 믿는 사람은 "계약 토큰은 모두 쓰인다"고 생각한다. 실제를 알려면 토큰 9개를 하나씩 grep해야 한다 | +| 최소 개선 방향 | (1) 독자 판정을 정확한 이름으로 바꾼다: `new RegExp(\`var\\(\\s*${escape(token)}\\s*[,)]\`)`. CSS 주석(`/* … */`)을 지운 뒤 검사한다. (2) 그러면 검사가 `--field-border`에서 실패한다. 이어서 입력란 테두리를 정한다: `.ui-field__input`이 `var(--field-border)`를 읽고 토큰값을 현재 계산식으로 옮기거나, 토큰값(`--color-border-strong`)을 그대로 쓴다. 후자는 화면이 바뀌어 시각 골든 갱신이 필요하다. (3) `ui-design-audit.md`의 UI-03 행을 "부분 충족"으로 고치고 다섯 번째 토큰을 적는다 | +| 대안 비교 | 적용 제외 — 일치 조건 보강은 한 줄이다. 입력란 색 결정은 영역 08과 함께 한다 | +| 단순화의 보존 조건 | 지금 읽히는 8개 토큰은 계속 통과한다. A3 probe(`--drawer-width` 제거)는 계속 실패한다 | +| 비용·부작용 | 검사 수 줄. 입력란 색을 바꾸면 시각 골든 몇 장 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `d99301b`에 새 판정을 넣으면 `--field-border`에서 실패한다. 고친 뒤에는 통과한다. 주석 안에만 있는 독자는 독자로 세지 않는다 | +| 검증 방법 | 12-02의 음성 fixture에 "접두어 쌍 중 짧은 쪽만 미사용" 사례와 "주석 안 독자" 사례를 넣는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 12-02 새 디자인 규칙 4개를 지키는 음성 fixture·테스트가 없다 — 규칙을 모두 꺼도 모든 게이트가 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 21, 17, 8 | +| 근거 | **fixture 모드:** `--fixture`는 TSX 검사 대상만 `tests/fixtures/design-system/forbidden`으로 바꾼다(`check-design-system.ts:179-181`). CSS 규칙 4개는 두 모드 모두 실제 토큰 파일에 돈다(`:23-162`). 음성 fixture는 TSX 2개뿐이다(`raw-palette.tsx`, `tooltip-only.tsx`). **게이트:** `check-design-system-fixture`는 exit 1과 출력 문자열 `"Design system contract failed:"`만 요구한다(`config/ci/gates.json:327-333`). TSX fixture 두 개가 항상 이 조건을 채운다. **산출물:** 보고서 스키마는 `checkedTokenCount`, `failures`, `passed`뿐이다(`scripts/contracts/release-artifacts.ts:995-1004`). 어떤 규칙이 돌았는지 남지 않는다. 성공 메시지도 "48 tokens and headless vendor boundary PASS"다(`:229-231`). **테스트:** `tests/unit/oklch-contrast.test.ts`는 계산 함수만 본다. `tests/unit/design-system-contract.test.ts`는 토큰 존재만 본다. **변이 M1(worktree):** 대비 기준을 `< 0`으로, oklab 정규식을 매칭 불가로, 토큰 사용·글꼴 판정을 `false &&`로 바꿨다. 동시에 포커스를 옛 값, 첫 글꼴을 `Inter`로 되돌렸다. 결과: `check-design-system.ts` PASS, `--fixture` exit 1(기대 문자열 포함), `vitest run` 3파일 16테스트 PASS | +| 발생 조건 | 누군가 검사기를 고치다 규칙 하나를 깨뜨릴 때. 다운스트림이 규칙을 지우거나 기준을 낮출 때 | +| 영향 | UI-01(P1, WCAG 1.4.11) 회귀를 막는 유일한 장치가 조용히 꺼질 수 있다. UI 감사 기록의 "RED→GREEN"은 개발 당시 한 번의 증거이고 이후를 지키지 않는다 | +| 심각도·우선순위 | Low · P2 — 검사기 자체를 고쳐야 생기는 회귀라 발생 조건이 좁다. 고치는 비용이 작고, 규칙이 계속 늘어나는 파일이라 지금 넣는 편이 싸다 | +| 통제·증거 | 목표 M3 / 확인 M0(규칙의 회귀 검출) · E3(변이 M1) | +| 확실성과 남은 가정 | 확정 | +| 결정의 근거 | 적용 제외 — 이미 다른 검사기(`check:i18n:fixture`, `check:diagnostics:fixture`, request-fanout fixture)가 쓰는 음성 fixture 관례가 이 규칙들에만 빠졌다 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | (1) 검사 대상 경로를 인자로 받게 한다(`--root `). 기본값은 지금 경로다. (2) `tests/fixtures/design-system/forbidden-css/`에 규칙마다 위반 토큰·스타일 세트를 둔다: 대비 미달 포커스, `in oklch` 혼합, 읽히지 않는 토큰(접두어 쌍 포함), `Inter` 첫 글꼴. (3) 단위 테스트가 fixture마다 해당 실패 문자열이 나오는지 단언한다. 게이트의 단일 기대 문자열로는 규칙별 검출을 증명할 수 없다 | +| 대안 비교 | 적용 제외 — 기존 관례를 따른다 | +| 단순화의 보존 조건 | 지금의 source/fixture 두 산출물 경로와 스키마는 유지한다 | +| 비용·부작용 | 스크립트 수십 줄, fixture 파일 몇 개, 테스트 1개 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 변이 M1을 다시 넣으면 테스트가 규칙마다 실패한다 | +| 검증 방법 | 변이 M1 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 12-03 디자인 규칙이 정해진 파일과 소문자 글자만 본다 — 대문자 키워드, 그라디언트, TSX 인라인, 토큰 재정의, feature CSS가 모두 통과한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 21, 5, 2, 13, 25 | +| 근거 | **검사 위치:** CSS 규칙은 토큰 파일 3개와 `src/presentation/styles/**`만 읽는다(`check-design-system.ts:32-42`). 값은 `primitive.css`와 `semantic.css`에서만 읽는다(`:100-107`, `:156`). **probe 결과(3절 표):** B1 `in OKLCH` 통과(정규식이 대소문자를 구분한다, `:57`). B2 `linear-gradient(in oklch, …)` 통과(`color-mix`만 본다). B3 TSX 인라인 `color-mix(in oklch, …)` 통과(TSX는 hex·`oklch(`·`rgb(`만 본다, `:193-194`). B7·B8 `base.css`에서 `--font-sans`·`--color-focus` 재정의 통과. B9 `outline-offset: 0` 통과. **B14:** `src/features/reference-feature/presentation/probe.css`에 `#ff0000`, `in oklch` 혼합, 정의 안 된 토큰을 쓰고 페이지에서 import → `check:design-system` PASS, `check:architecture` exit 0(1,177 간선, CSS 규칙 없음). **전제:** 포커스 규칙 주석은 "링이 3px 떨어져 그려진다"를 전제로 한다(`:87-89`). 그 값은 `base.css:43`, `primitives.css:684`에 있고 검사가 읽지 않는다. UI 감사의 완료 기준은 "offset을 없애면 action 대비도 포함"이었다(`ui-design-audit.md:49`) | +| 발생 조건 | 다운스트림이 feature CSS, 브랜드 재정의 CSS, 인라인 스타일을 추가할 때. 누군가 포커스 링을 offset 없이 바꿀 때 | +| 영향 | 토큰 밖 색, 색조 끌림이 있는 혼합, 3:1 미만 포커스가 게이트를 통과한다. 지금 템플릿에는 이런 경로가 없다 | +| 심각도·우선순위 | Low · P3 — 현재 위반은 없다. 템플릿 CSS가 모두 검사 위치 안에 있다 | +| 통제·증거 | 목표 M3 / 확인 M3(`styles/**`와 토큰 파일), 그 밖 M0 · E3(probe 9종) | +| 확실성과 남은 가정 | 우회는 실행으로 확인했다. 다운스트림 두 repo에 feature CSS가 있는지는 보지 않았다 | +| 결정의 근거 | 5.1절. 확인한 사실: 템플릿은 CSS를 한 진입점(`theme.css`)으로 모은다. 추론: 검사 범위는 이 관례를 전제로 정했다. 관례는 문서·규칙 어디에도 적혀 있지 않다 | +| 이해 비용 | 다운스트림 작성자는 "디자인 규칙이 모든 CSS에 적용된다"고 생각하기 쉽다. 실제 범위를 알려면 스크립트를 읽어야 한다 | +| 최소 개선 방향 | (1) CSS를 `src/presentation/styles/`와 토큰 폴더에만 두게 하는 그래프 규칙 하나를 추가한다: `src/bootstrap/main.tsx` 밖에서 `.css`를 import하면 실패. 또는 CSS 검사 대상을 `src/**/*.css` 전체로 넓힌다. (2) `color-mix`·그라디언트 정규식을 대소문자 무시(`/i`)로 하고 `(?:color-mix|gradient)\(\s*in\s+(oklch|lch|hsl|hwb)` 형태로 넓힌다. (3) 토큰 값을 읽을 때 `styles/**`의 `:root` 재정의도 합친다. (4) `outline-offset` 값이 0보다 큰지 확인하거나, 0이면 `--color-action`·`--color-danger`를 비교 목록에 넣는다 | +| 대안 비교 | 5.1절 | +| 단순화의 보존 조건 | 지금 통과하는 템플릿 CSS는 계속 통과한다. 직접 위반 probe A1~A4는 계속 실패한다 | +| 비용·부작용 | (1)은 규칙 1개와 fixture 1개. (2)~(4)는 수 줄씩. CSS 대상 확대는 지금 위반 0건이다 | +| 재검토 조건 | 5.1절 7번 | +| 완료 기준 | B1·B2·B7·B8·B9·B14 probe가 실패한다 | +| 검증 방법 | 12-02의 음성 fixture에 같은 사례를 넣는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 12-04 디자인 규칙이 정상 CSS를 거부한다 — `color-mix`·알파·`deg` 표면 토큰, `-apple-system`, 패키지로 싣는 글꼴. 규칙 설명은 코드 주석에만 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 21, 19, 20, 25, 23, 8 | +| 근거 | **포커스 규칙:** `resolveColor`는 `var()` 사슬 끝이 `oklch(L C H)`가 아니면 `null`을 돌려준다(`scripts/lib/oklch-contrast.ts:52-66`). 파서는 알파·`deg` 단위·음수를 받지 않는다(`:12-15`). 검사는 이것을 실패로 센다(`check-design-system.ts:115-117`). probe B10(`color-mix(in oklab, …)` 표면), B11(`/ 0.9`), B13(`230deg`) 모두 실패. 셋 다 유효한 CSS다. B10은 UI-02 규칙이 권하는 형식이다. **글꼴 규칙:** 기본 글꼴 목록은 7개 키워드뿐이다(`:141-149`). `-apple-system`, `BlinkMacSystemFont`는 없다(B6 실패). "실었다"의 판정은 검사 위치 안의 `@font-face` 글자다(`:150-155`). npm 글꼴 패키지 import, `@import url(…)`, `index.html`의 ``는 보지 않는다. **문서:** 네 규칙의 설명과 지원 형식은 코드 주석과 UI 감사 기록에만 있다. `docs/styling/design-system-platform.md`·`docs/operations/ci-quality-gates.md`에는 없다(`git grep oklab|font-sans` 0건). **경미:** B12 — CSS 주석에 `color-mix(in oklch` 글자가 있으면 실패한다 | +| 발생 조건 | 다운스트림이 상태 표면을 `color-mix`로 만들 때, 반투명 표면을 쓸 때, 시스템 글꼴 스택을 `-apple-system`으로 시작할 때, Pretendard처럼 패키지·CDN으로 글꼴을 실을 때. 두 제품 repo는 한국어 제품이다 | +| 영향 | 올바른 CSS가 merge 게이트 FE-GATE-010을 막는다. 설정이 없어서 제품은 템플릿 소유 스크립트를 고치게 된다. 지난 라운드 fanout·i18n에서 두 제품이 실제로 스크립트를 고치거나 게이트를 빨간 채로 둔 것과 같은 모양이다 | +| 심각도·우선순위 | Low · P3 — 실패 쪽으로 닫힌다(안전). 메시지가 무엇이 문제인지 알려 준다. 현재 템플릿에는 오탐이 없다 | +| 통제·증거 | 해당 없음(오탐) · E3(probe B6·B10·B11·B12·B13) | +| 확실성과 남은 가정 | 동작은 확정이다. 다운스트림이 실제로 이런 형식을 쓰는지는 이번에 보지 않았다 | +| 결정의 근거 | 확인한 사실: 해석할 수 없는 값을 거부하는 것은 의도다("callers fail loudly instead of guessing", `oklch-contrast.ts:53-54`). 추론: 지원 형식을 넓히는 대신 문서로 범위를 밝히는 쪽이 비용이 작다 | +| 이해 비용 | 제품 작성자가 실패 원인을 알려면 `parseOklch` 정규식을 읽어야 한다 | +| 최소 개선 방향 | (1) 포커스 실패 메시지에 지원 형식(`oklch(L C H)`, 알파·`deg`·`color-mix` 미지원)을 적는다. (2) 파서가 `deg` 단위와 알파를 받게 한다. 알파가 있는 표면은 "배경 위에 섞어 계산" 대신 실패를 유지하되 메시지로 구분한다. (3) 기본 글꼴 목록에 `-apple-system`, `BlinkMacSystemFont`를 넣는다. (4) 저장소 밖에서 싣는 글꼴은 `token-contract.ts`에 "제품이 싣는 글꼴" 목록을 두어 선언하게 한다. (5) `docs/styling/design-system-platform.md`에 규칙 4개와 지원 형식을 한 단락으로 적는다 | +| 대안 비교 | 현 상태: 비용 0, 다운스트림이 스크립트를 고칠 가능성. 메시지·문서만: 수 줄, 막히는 경우는 같지만 해결 방법이 보인다. `color-mix` 해석까지 구현: 대비 계산에 혼합 계산을 넣어야 해서 코드가 커진다. 메시지·문서 + 글꼴 선언 목록이 비용 대비 낫다 | +| 단순화의 보존 조건 | 해석할 수 없는 값은 계속 실패한다(추측하지 않는다). A1·A4는 계속 실패한다 | +| 비용·부작용 | 수십 줄 | +| 재검토 조건 | 다운스트림 하나라도 이 규칙 때문에 스크립트를 고치면 `color-mix` 해석 구현을 다시 비교한다 | +| 완료 기준 | B6·B13은 통과한다. B10·B11은 실패하되 메시지가 지원 형식을 알려 준다. 문서에 네 규칙이 있다 | +| 검증 방법 | 12-02의 fixture에 허용 사례(`-apple-system`, `deg`)를 추가한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 12-05 사문화된 npm script 4개가 남아 있고, 게이트 밖 스크립트 검사는 이름 접두어 5개만 본다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 9, 27, 21, 20, 24 | +| 근거 | **분류(6절):** 142개 = 게이트 명령 93 + 합성 스크립트 경유 11 + 예외 목록 17 + 다른 스크립트가 이름으로 부름 11 + 참조 없음 10. **`scan:security:fixture`**(`package.json:96`): FE-GATE-013은 이것 대신 `check:security:fixtures`를 돌린다. 그 검사는 임시 폴더에서 스캐너를 직접 부른다(`scripts/lib/security-fixture-check.ts:97-101`). `tests/unit/supply-chain.test.ts:472-476`은 "이 스크립트가 게이트에 없어야 한다"고 단언한다. 그런데 스크립트는 남아 있다. 게이트 밖 스크립트 검사의 대상은 `^(?:check|verify|test|drill|review):`이다(`scripts/lib/ungated-scripts.ts:15`). `scan:`은 대상이 아니라 예외 목록에도 없이 통과한다. **빌드 단계 별칭:** `build:profile`(`:14`)은 `generate-runtime-config.ts`를 돈다. 이름과 하는 일이 다르다. `generate:contract-set`(`:126`)은 docs·tests·scripts 참조 0건이다. `build:app-only`(`:125`)는 `vite build`와 매니페스트만 만든다. `build-frontend.ts:58-80`의 계약 세트·런타임 설정·Service Worker 단계를 건너뛴 dist가 나온다. 참조는 생성 인덱스 진입점 목록 하나다(`tests/unit/product-index-entrypoints.test.ts:12`). **스스로 무력하다고 적힌 스크립트:** `check:feature-index`의 예외 이유는 "--check는 로컬 사본이 오래됐다는 것만 알려 줄 수 있다"이다(`config/ci/ungated-scripts.json`) | +| 발생 조건 | 항상. 새 사람이 package.json에서 명령을 고를 때 | +| 영향 | `scan:security:fixture`를 돌리면 실패 exit(음성 fixture)와 `artifacts/security/scan-fixture.sarif`가 남는다. 무엇을 증명하는지 설명이 없다. `build:app-only` 결과를 `preview`로 띄우면 런타임 설정·SW가 없는 앱을 보게 된다. 비용은 탐색과 오해다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | 게이트 밖 검증 스크립트 검사 M3(접두어 5개), `scan:`·`build:`·`generate:`·`collect:`는 M0 · E1(참조 분석 스크립트, `git grep`) | +| 확실성과 남은 가정 | 참조 없음은 확정이다(문자열 검색 기준). 개인 작업 습관으로 쓰는지는 모른다 | +| 결정의 근거 | 현 검사의 근거: "검증 계열" 스크립트만 게이트 연결을 요구하고 빌드·생성 명령은 자유롭게 둔다. 합리적이다. 빠진 것은 `scan:` 계열이다 | +| 이해 비용 | 142개 중 무엇이 게이트 명령이고 무엇이 로컬 편의인지 package.json만 보고는 알 수 없다 | +| 최소 개선 방향 | (1) `scan:security:fixture`, `build:profile`, `generate:contract-set`을 지운다. (2) `build:app-only`는 지우거나, 남길 이유가 있으면 이름을 `build:vite-only`처럼 바꾸고 "런타임 설정·SW 없음"을 문서에 적는다. (3) `VERIFICATION_SCRIPT`에 `scan`을 넣는다. (4) `check:feature-index`는 이유 문구대로라면 지울 후보다. 남긴다면 이유를 "로컬 확인용"으로 고친다 | +| 대안 비교 | 현 상태: 비용 0, 계속 쌓인다. 접두어 대신 "게이트에 없는 모든 스크립트는 예외 목록에"로 넓히기: `dev`·`storybook`·`update:*`까지 목록에 올려야 해서 목록이 커진다. 접두어에 `scan` 추가 + 고아 제거가 가장 작다 | +| 단순화의 보존 조건 | `check:security:fixtures`(FE-GATE-013)는 그대로다. `supply-chain.test.ts:472-476`의 단언은 스크립트가 없어도 통과한다. `product-index-entrypoints.test.ts`의 목록에서 `build:app-only`를 함께 뺀다 | +| 비용·부작용 | package.json 3~4줄, 테스트 목록 1줄, 정규식 1줄 | +| 재검토 조건 | 새 접두어(`audit:` 등)의 검증 스크립트가 생기면 `VERIFICATION_SCRIPT`를 다시 본다 | +| 완료 기준 | 참조 없는 검증·빌드 별칭이 0개다. `scan:`으로 시작하는 게이트 밖 스크립트는 예외 목록 없이는 `check:ci`에서 실패한다 | +| 검증 방법 | `scratchpad/probes-12/script-audit.mjs` 재실행. `check:ci` 실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 설명 (41절) + +### 5.1 디자인 규칙을 CSS 글자에 대한 정규식으로 검사하는 선택 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | "브랜드는 토큰으로만 바꾼다"(`PRODUCT.md:49`), WCAG 1.4.11 포커스 3:1, 색조 끌림 없는 혼합, 실제로 그려지는 글꼴. 쓰는 사람은 템플릿 관리자와 다운스트림 제품이다 | +| 2. 지킬 성질 | 배포되는 스타일이 계약 토큰을 실제로 읽는다. 금지된 혼합 방식이 배포 CSS에 없다. 검사가 거짓 통과를 내지 않는다 | +| 3. 현재 보장 | 토큰 파일과 `styles/**`의 글자를 정규식으로 본다. 직접 위반은 모두 잡는다(A1~A4). **보장하지 않는 것:** 정확한 토큰 이름(12-01), 주석·대소문자(12-01·12-03), 그 밖의 파일과 인라인 스타일(12-03), 규칙 자체의 회귀(12-02) | +| 4. 대안 | (a) 현 정규식을 유지하고 정확 이름 일치·주석 제거·대소문자 무시·대상 확대를 넣는다. (b) CSS 파서(`postcss`, 이미 lockfile에 전이 의존으로 있다)를 직접 의존으로 올려 선언 단위로 검사한다. (c) stylelint와 사용자 규칙 플러그인. (d) 빌드된 CSS(`dist`)를 검사한다 | +| 5. 대안별 비용 | (a) 수십 줄, 의존성 0. 파일 범위는 여전히 목록에 의존한다. (b) 직접 의존 1개와 수십 줄. 주석·대소문자·이름 경계 문제가 구조적으로 사라진다. (c) 도구·설정 추가. 대비 계산은 어차피 직접 짜야 한다. (d) 모든 출처(feature CSS, `@apply` 결과)를 본다. 대신 빌드 뒤에만 돌 수 있어 FE-GATE-010(빌드 없음)에서 FE-GATE-012로 옮겨야 하고, Tailwind가 쓰지 않는 토큰 변수를 지울 수 있어 토큰 판정이 달라진다 | +| 6. 현재 조건에서의 선택 | **(a).** 이번에 찾은 결함은 파싱 능력이 아니라 일치 조건의 정밀도 문제다. 템플릿 CSS는 한 진입점에 모여 있다. 규칙이 4개이고 검사 시간은 0.30초다. 리뷰어 추론이며 작성 당시 비교 기록은 없다 | +| 7. 재검토 조건 | 제품이 CSS 모듈이나 feature CSS를 정식으로 도입하면 (b) 또는 (d). 정규식 예외 처리가 규칙마다 붙기 시작하면 (b) | + +### 5.2 포커스 대비를 토큰 값에서 계산하는 선택 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 두 테마에서 포커스 링과 바로 옆 색의 대비 3:1(WCAG 1.4.11). UI 감사에서 P1이었다 | +| 2. 지킬 성질 | 포커스를 받는 모든 컨트롤에서 링 색과 실제 인접색의 대비가 3:1 이상이다 | +| 3. 현재 보장 | 토큰 값을 OKLab→선형 sRGB로 바꾸고 범위 밖은 잘라서 휘도를 계산한다(`oklch-contrast.ts:24-36`). 표면 8종 × 2테마를 비교한다. 단위 테스트가 Chromium 실측값 2.33:1에 맞춘다(`oklch-contrast.test.ts:21-26`). 현재 최저 4.24:1(light). **보장하지 않는 것:** 목록 밖 인접색(헤더 `color-mix(panel 92%, surface)`, sticky 영역 `color-mix(panel 94%, transparent)`, 활성 메뉴 배경), offset 전제(12-03), 토큰 파일 밖 재정의(12-03). 두 테마의 토큰 값 16개가 sRGB 범위 밖이다(두 포커스 색 포함). 라이브러리 주석은 "브라우저가 잘라서 그린다"고 적지만 P3 디스플레이와 브라우저의 gamut 처리는 확인하지 않았다 | +| 4. 대안 | (a) 현 상태. (b) 현 상태 + offset 전제 검사(12-03 개선 (4)). (c) Playwright로 컨트롤마다 포커스를 주고 계산된 outline 색과 주변 픽셀을 잰다. (d) axe — 포커스 표시 대비를 검사하지 않는다(UI 감사 기록) | +| 5. 대안별 비용 | (a) 비용 0. (b) 수 줄. (c) 반투명·혼합 배경은 픽셀 샘플링이 필요해 불안정하고 유지비가 크다. (d) 해당 없음 | +| 6. 현재 조건에서의 선택 | **(a)+(b).** 여유가 크다(최저 4.24 대 기준 3.0). 잘라내기 계산과 실제 표시의 차이가 판정을 뒤집을 가능성은 낮다. 남은 틈은 전제(offset) 하나라 수 줄로 닫힌다 | +| 7. 재검토 조건 | 최저 대비가 3.3 아래로 내려가거나, 링을 inset·offset 0으로 바꾸거나, 표면 토큰을 `color-mix`로 바꿀 때(12-04) | + +## 6. npm script 142개 — 중복과 사문화 (이번 라운드 추가 요구) + +분석 방법: `config/ci/gates.json`의 명령, package script 사이의 `pnpm ` 참조, `config/ci/ungated-scripts.json`, `scripts/`·`tests/`·`docs/`의 이름 검색을 합쳤다(`scratchpad/probes-12/script-audit.mjs`). + +| 분류 | 개수 | 내용 | +|---|---|---| +| 게이트 명령이 직접 부름 | 93 | 명령 98개 중 `drill:runbook` 5개, `review:a11y-manual` 2개는 같은 스크립트를 인자만 바꿔 부른다 | +| 합성 스크립트 경유 | 11 | `check:types:*` 5개, `check:artifact-schemas`, `check:ci-workflow`, `scan:security`, `verify:release` 등 | +| 예외 목록(이유 있음) | 17 | 규모 계층 4, 로컬 집계(`test:all`, `drill:runbooks`, `verify:extreme-scale`) 등. `check:remediation-ledger`는 빨간 채다 | +| 다른 스크립트가 이름으로 부름 | 11 | `verify-extreme-scale.ts`의 단계(`check:topology`, `check:traffic`, `check:observability`, `test:platform`, `check:release-coherence`), `run-http-scenario-evidence.ts`의 `test:http-scenario-catalog` 등. 모두 게이트가 이미 도는 테스트 경로의 부분 집합이다 | +| 참조 없음 | 10 | 진입점(`dev`, `storybook`), 문서화된 유지 명령(`generate:artifact-schemas`, `update:dependency-baseline`, `update:ci-contract-baseline`, `update:scale-baseline`), **사문화 4개**(`scan:security:fixture`, `build:profile`, `generate:contract-set`, `build:app-only` — 12-05) | + +중복 실행: + +| 중복 | 비용 | 판단 | +|---|---|---| +| FE-GATE-005: `test:unit`·`test:contract` 뒤에 `test:coverage`가 같은 경로를 다시 돈다 | 약 12초/회(`test:unit` 11.72초, `test:contract` 0.47초, 오케스트레이터 로그) | 층별 JUnit(`unit.xml`, `contract.xml`)이 게이트 증거로 등록돼 있다. 먼저 빠르게 실패하는 효과도 있다. 유지 가능 | +| `test:coverage`가 runtime-schema·component·integration·features도 돈다. 이것들은 FE-GATE-004·006·007에서도 돈다 | 병렬 runner라 벽시계 시간은 늘지 않는다. 계산량만 는다 | 유지 가능 | +| `build`가 FE-GATE-011·012·019·026에서 돈다 | 각각 다른 잡·runner다. release 잡의 matrix도 gate별 runner다(`quality-gates.yml:80-109`) | 유지 가능 | +| 55개 스크립트가 `generate-product-feature-index.ts`를 먼저 돈다 | 1회 0.07초. 한 게이트에서 최대 약 20회 | 비용 무시 가능. gitignore된 생성물을 위한 의도된 반복이다(`product-index-entrypoints.test.ts:6-7`) | +| `check:types:fixture:*` 23개가 tsc를 따로 띄운다 | 1회 0.9~2.2초(부하 19). FE-GATE-003에서 합계 약 30~45초 추정 | 7절 R-3 | + +## 7. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R-1 | `check-design-system.ts`의 손 목록(포커스 비교 표면 8개 `:90-99`, 다크 필수 토큰 15개 `:66-82`, 기본 글꼴 7개 `:141-149`)을 `token-contract.ts`로 옮긴다 | 제품이 표면 토큰 하나를 추가하면 템플릿 소유 스크립트를 고쳐야 한다. 07-03(중앙 allowlist)과 같은 모양이다. 토큰 정의 옆에 두면 한 곳에서 바꾼다 | 실패 메시지 문구와 실패 집합이 같다. 다크 목록은 지금처럼 `REQUIRED_SEMANTIC_TOKENS`와 별개 목록으로 둔다(독립 선언, 39.5) | +| R-2 | "토큰을 읽는가"와 "정의 안 된 토큰을 쓰는가"를 한 함수(정확 이름, 주석 제거)로 모은다 | 12-01·12-03의 일치 문제를 한 곳에서 고친다 | 지금 PASS인 템플릿 CSS는 PASS. `--field-border`는 FAIL로 바뀐다(의도) | +| R-3 | `check:types:fixture:*` 23개를 목록을 읽는 러너 하나로 합친다. 각 항목에 tsconfig와 기대 위치(`파일:줄 코드`)를 둔다 | package.json 23줄, gates.json 명령 23개, 기준선 숫자가 한 사실을 세 곳에 적는다. 지금은 오류 코드만 고정해서 같은 코드의 다른 오류도 통과한다(2026-09-25 07번에서 지적, "지금은 fixture마다 위반이 하나라 문제없다") | fixture마다 실패해야 한다. 기대 진단을 더 좁게(위치까지) 고정한다. 게이트 로그에 fixture별 결과가 남는다. 비용: CI 계약 기준선 재승인 1회, 다운스트림 `gates.json` 동기화 충돌 1회 | +| R-4 | 사문화 스크립트 제거 | 12-05 | 12-05 보존 조건 | + +## 8. 테스트·성능·폴더 구조 렌즈 + +- **테스트가 위험을 잡는가:** 디자인 규칙의 직접 위반은 검사가 잡는다(A1~A4). 검사기 자체의 회귀는 아무것도 잡지 않는다(변이 M1, 12-02). `oklch-contrast.test.ts`는 브라우저 실측값에 맞춘 단언이 있어 계산식 회귀는 잡는다. 실행 시간 0.31초. +- **성능(로컬, 조건 표시):** `check:design-system` 0.30초·122MB(부하 9.8). `check:architecture` 10초, `check:ci` 2초, `lint` 11초, `check:types` 6초(오케스트레이터 측정, 부하 기록 없음). 타입 fixture 1회 0.9~2.2초·100~377MB(부하 19). CI runner 실행 시간은 runner가 없어 측정하지 못했다. +- **폴더 구조:** `scripts/` 최상위 70개(검사 29개), `scripts/lib/` 66개, `scripts/contracts/`, `scripts/scale/`. 새 `oklch-contrast.ts`는 Node 전용 빌드 도구라 `scripts/lib/` 위치가 맞다. 규칙이 쓰는 토큰 목록이 스크립트 안에 있고 토큰 계약은 `src/presentation/design-system/tokens/`에 있어 둘이 떨어져 있다(R-1). CI 메타 층 크기는 그대로다: `gates.json` 2,940줄, `ci-gates.ts` 1,287, `package-script-graph.ts` 1,025, `ci-artifact-validator.ts` 742, `generate-ci-workflow.ts` 530, workflow 470. + +## 9. 미검증 목록 + +- **머지 시점 강제(U-1).** 이번에는 Gitea API를 부르지 않았다. 저장소 관리자가 `has_actions`, `/branch_protections`, main HEAD 상태를 확인해야 한다. +- **생성 workflow의 실제 runner 실행과 CI 소요 시간.** runner가 없다. +- **입력란 테두리 대비 2.53:1.** 계산 함수로만 계산했다. 브라우저 실측과 WCAG 1.4.11 해당 여부는 영역 08에서 판단한다. +- **sRGB 범위 밖 토큰 값 16개의 실제 표시.** 브라우저가 잘라내는지, CSS Color 4 gamut mapping을 하는지, P3 디스플레이에서 대비가 어떻게 바뀌는지 확인하지 않았다. 포커스 여유(최저 4.24)가 커서 판정이 뒤집힐 가능성은 낮다고 본다(추론). +- **다운스트림 두 repo에 feature CSS·`-apple-system`·패키지 글꼴이 있는지.** 이번에는 제품 repo를 읽지 않았다. +- **`test:platform`의 `--no-file-parallelism`이 필요한지.** 게이트(`test:coverage`)는 같은 테스트를 병렬(`--maxWorkers=4`)로 돈다. 병렬에서만 생기는 실패가 있는지 보지 않았다(영역 10·11). +- **지난 라운드 12-01~12-07 개선안의 실제 효과.** 코드가 바뀌지 않아 다시 실험하지 않았다. 지난 실험 결과를 이번 증거로 쓰지 않는다. + +## 10. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 굵은 번호가 이번에 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 근거 | +|---|---|---|---| +| 1 | 코드 성숙도 | - | 이 영역에 도메인 규칙이 없다. 검사기 정확성은 10·21에서 본다 | +| **2** | 구조적 성숙도 | P | feature 안 layer 밖 폴더 우회가 남았다(지난 12-03). CSS 파일 위치에 대한 규칙이 없어 feature CSS가 디자인 규칙과 그래프를 모두 통과한다(12-03, B14) | +| 3 | 변경 용이성 | P | 게이트 하나를 바꾸면 4곳이 움직인다(지난 12-04). 표면 토큰 하나를 추가하면 템플릿 스크립트의 손 목록을 고쳐야 한다(R-1) | +| 4 | 인지 부하 | P | CI 메타 층 약 7,000줄이 그대로다. npm script 142개 중 게이트 명령과 로컬 편의를 package.json만으로 구분할 수 없다(12-05) | +| 5 | 위험 가시성 | P | 검사가 PASS를 보고하는 동안 계약 토큰 하나가 읽히지 않는다(12-01). 포커스 규칙의 전제(offset 3px)가 주석에만 있다(12-03) | +| 6 | 실패 성숙도 | - | 런타임 실패 처리가 없는 영역이다 | +| 7 | 운영 성숙도 | > | 영역 13 | +| 8 | 디버깅 가능성 | P | 디자인 규칙 메시지는 파일·토큰·대비값·해결 방향을 준다. 산출물에는 어떤 규칙이 돌았는지 남지 않는다(12-02). fanout·i18n 메시지 문제는 남았다(지난 12-01·12-02) | +| 9 | 유지보수 성숙도 | P | 사문화 script 4개(12-05), 미사용 `dependency-cruiser`(지난 12-05), 읽히지 않는 토큰과 중복 계산식(12-01) | +| 10 | 테스트 성숙도 | P | 새 규칙 4개에 음성 fixture가 없어 변이가 살아남았다(12-02, E3). 계산 함수 테스트는 브라우저 실측에 맞춘다 | +| 11 | 데이터 성숙도 | - | 저장 데이터가 없다 | +| 12 | 동시성 성숙도 | - | 해당 없음 | +| 13 | 확장성 | > | 영역 09·11. 이 영역 몫: 디자인 규칙 범위가 고정 파일 목록이라 feature CSS 증가를 따라가지 못한다(12-03) | +| 14 | 성능 성숙도 | ? | CI runner가 없어 벽시계 시간을 재지 못했다. 로컬 수치는 8절. FE-GATE-005 중복 약 12초는 유지 가능 | +| 15 | 보안 성숙도 | O | workflow 범위. `permissions: contents: read`(`quality-gates.yml:23-24`), action 33개 40자 SHA 고정, `--frozen-lockfile --ignore-scripts`, `persist-credentials: false`, `pull_request_target` 없음(E1). 공급망 전체는 영역 13 | +| **16** | 의존성 성숙도 | P | 새 규칙은 색 라이브러리를 들이지 않고 변환식 40줄로 해결했다. 미사용 `dependency-cruiser@18.1.0`이 남았다(지난 12-05) | +| 17 | API / Contract | P | 게이트 계약 크기가 두 곳에 있다(지난 12-04). fixture 게이트는 기대 문자열 하나만 보고 규칙별 검출을 증명하지 않는다(12-02) | +| 18 | 배포 성숙도 | > | 영역 13 | +| 19 | 설정 성숙도 | P | i18n 정책(지난 12-02)과 디자인 규칙 목록(표면·기본 글꼴, 12-04·R-1)이 설정이 아니라 스크립트 코드에 있다 | +| 20 | 개발자 경험 | P | 디자인 메시지는 해결 방향을 준다. 오탐 시 탈출 경로와 규칙 문서가 없다(12-04). 게이트 변경 절차가 테스트 갱신을 빠뜨린다(지난 12-04) | +| **21** | Guardrail 성숙도 | ? (머지 시점) / P (로컬) | **머지 시점:** 이번에 확인하지 않았다(지난 라운드 X). **로컬:** 새 규칙 4개는 직접 위반을 잡는다(A1~A4, E3). 접두어 일치로 실제 미사용 토큰을 놓친다(12-01). 규칙 회귀 검출이 없다(12-02). 파일·대소문자 우회가 열려 있다(12-03). 지난 fanout·i18n·feature 폴더 문제가 남았다 | +| 22 | 추상화 성숙도 | P | 정규식 검사는 규칙 규모에 맞다(5.1). 손 목록이 토큰 계약과 떨어져 있다(R-1). 타입 fixture 23개가 한 사실을 세 곳에 적는다(R-3) | +| 23 | 일관성 | P | raw palette는 `src` 전체 TSX를 보고, CSS 규칙은 `styles/**`만 본다(12-03). oklab 규칙은 `color-mix`를 권하고 포커스 규칙은 `color-mix` 표면을 거부한다(12-04) | +| 24 | 네이밍 / 의미 | P | `build:profile`은 런타임 설정을 만든다(12-05). 성공 메시지 "48 tokens and headless vendor boundary PASS"는 새 규칙 4개를 말하지 않는다(12-02). 지난 i18n·규칙 주석 문제가 남았다 | +| **25** | 조직 확장성 | P (구조만) | 팀이 하나라 실제 검증은 미확인이다. 제품이 표면 토큰·글꼴을 바꾸면 템플릿 소유 스크립트를 고쳐야 한다(12-04, R-1). 지난 라운드에 fanout·i18n에서 같은 일이 실제로 있었다 | +| **26** | Ownership | P | 예외 목록에 담당·재검토가 없다(지난 12-07). 대체된 `scan:security:fixture`를 지운 사람이 없다(12-05). 원장 검사가 결정자 없이 빨간 채다(FOLLOW-UP). UI 감사 조치 표는 넣은 검사를 행마다 적어 책임 추적이 쉽다 | +| 27 | 삭제 가능성 | P | 사문화 script는 바로 지울 수 있다(12-05). 제거 게이트가 CI 테스트를 지운 뒤 통과를 증명하는 문제는 남았다(지난 12-04) | +| 28 | 회복 가능성 | - | 이 영역에 복구 경로가 없다 | diff --git a/docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md b/docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md new file mode 100644 index 00000000..d55e787f --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md @@ -0,0 +1,349 @@ +# 13 — 빌드·릴리스·설정·공급망 성숙도 리뷰 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`, `docs/reviews/TEMPLATE-MATURITY-REVIEW-EXECUTION-CHECKLIST.md` +> 영역 판정(35.8): **조건부 사용 가능.** 기본 구성(SW `null`, 루트 경로, 셸 환경변수)으로 "빌드 → 공개 대상 승인"까지는 그대로 써도 된다. **desktop 서버로 자동 배포(CD)하는 용도는 사용 보류다.** 운영 단계 검사는 배포된 release가 승격 후보인지 확인하지 않고, 배포 job을 넣을 자리도 CI 계약이 막는다(13-01). 템플릿에서 막 만든 프로젝트는 자리표시자 endpoint(`api.example.com`)로 운영 승인을 받는다(13-02). 지난 라운드 발견 10건은 코드가 바뀌지 않아 모두 남았다. + +## 0. 결론 + +- **지난 라운드 13번 발견 10건은 모두 남았다.** `af3d8e6..d99301b` 11커밋 중 이 영역 파일 변경은 `scripts/check-design-system.ts`, `scripts/lib/oklch-contrast.ts` 두 개뿐이다(디자인 규칙, 영역 12 소관). 09-29 13-01(= 06-01, High)은 이번 커밋에서 다시 재현했다(실험 E-B). +- **운영 단계 검사가 "무엇이 배포됐는가"를 보지 않는다(13-01, Medium, P1).** `production_gate`는 `promotion` 직후 같은 run에서 돈다. 그 사이에 배포 job이 없다. live probe는 배포된 `release-manifest.json`의 build id를 후보와 비교하지 않는다. 그래서 FE-GATE-019의 PASS는 "지금 떠 있는 이전 release의 헤더가 맞다"는 뜻일 수 있다. 배포 job이나 env 바인딩을 더하면 `check:ci`가 실패한다(실험 E-G). +- **공개 대상 승인이 템플릿 자리표시자를 통과시킨다(13-02, Medium, P1).** `config/runtime/production.json`의 `https://api.example.com/`, `https://telemetry.example.com/...`가 그대로 `ADMITTED`된다. CI는 `RUNTIME_*`를 넘길 수 없다. 새 프로젝트가 프로필을 안 고치면 모든 API 호출이 실패하는 빌드가 승인되고, telemetry는 프로젝트가 소유하지 않은 도메인으로 간다. +- **운영 승격이 요구하는 runner 전제가 desktop act_runner에서 성립하는지 아무도 확인하지 않았다(13-03, Medium, P2).** provider job은 호스트의 `bwrap`·systemd user manager 254+·cgroup v2 위임을 요구한다. 같은 job이 "`ubuntu-latest`를 고정 컨테이너 image에 매핑하라"는 전제로 돈다. provider 없이 무엇을 배포하는지는 문서에 없다. +- **호스팅 계약이 SPA fallback을 선언·검사하지 않는다(13-04, Medium, P2).** 라우터는 browser history를 쓴다. 호스트가 fallback을 빠뜨리면 새로고침·깊은 링크가 404인데 FE-GATE-019는 통과한다. e2e는 fallback을 기본 제공하는 `vite preview`라 드러나지 않는다. +- **"재빌드 없이 설정을 바꾼다"는 비상 스위치에 검증된 절차가 없다(13-05, Low, P2).** +- **이 영역 테스트는 있는 규칙을 잘 지킨다.** 변이 5개(사설 호스트 거절, 프로필≠대상 거절, staging·production build id 필수, manifest URL rebasing, fixture를 PASS로 세기)를 모두 잡았다. 빠진 것은 규칙 자체다(빌드 끝 `APP_ENV` 확인, 배포물 식별 대조, 자리표시자 거절). + +## 1. 리뷰 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 영역 13 — 빌드·릴리스·설정·공급망 | +| 커밋·상태 | `d99301b`. 메인 워킹트리 미커밋은 `.claude/`뿐. 실험은 분리 worktree 두 개(`scratchpad/wt-13`, `wt-13m`, `d99301b`)에서 했다. 빌드는 `flock scratchpad/heavy.lock`으로 감쌌다. worktree에서 pnpm은 부르지 않았다 | +| 목적과 실행 구성 | 템플릿. 브라우저 SPA + 정적 호스팅 + SW(기본 `null`). 이번 라운드 추가 용도: 이 템플릿으로 만든 서비스를 운영 중인 desktop 서버에 띄우고, Gitea 템플릿 기능으로 새 프로젝트를 만들고, CI/CD를 자동화한다 | +| 규모·운영 목표 | 수치 목표는 초기 JS 예산(`config/performance/budgets.json`, 204,800 gzip B)뿐 | +| 읽은 범위 | `scripts/build-frontend.ts`, `generate-runtime-config.ts`, `generate-build-manifest.ts`, `check-release-admission.ts`, `verify-hosting-headers.ts`, `run-ci-gate.ts`, `run-and-validate-provider.ts`(전제 부분), `update-dependency-baseline.ts`, `serve-static.ts`, `check-bundle.ts`, `scripts/lib/{build-environment,hosting-probe,classify-vite-bundle,supply-chain,service-worker-build-input}.ts`, `scripts/contracts/ci-gates.ts`(job·env 고정부), `scripts/generate-ci-workflow.ts`(env 렌더링), `vite.config.ts`, `vite.service-worker.config.ts`, `config/{runtime,hosting,release,security}`, `config/ci/gates.json`(FE-GATE-015·019·027, jobs), `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`, `.npmrc`, `.env.example`, `.nvmrc`, `public/config.json`, `.gitea/workflows/quality-gates.yml` 전체, `src/contracts/deployment-admission.ts`, `src/bootstrap/load-runtime-config.ts:150-168`, `src/presentation/routes/app-router.tsx`(라우터 종류). 주장 자료: `README.md:24-71`, `:94-133`, `:286-353`, `docs/operations/{ci-quality-gates,release-cache-rollback}.md`, `docs/architecture/static-delivery.md`, `docs/runbooks/FE-RB-001.md`, `docs/operations/adapter-remediation-ledger.md:505-530` | +| 실행한 명령 | 게이트 결과는 오케스트레이터 로그를 읽었다(다시 돌리지 않음). 직접 실행: ① 함수 probe `r13-probe.ts`(승인 규칙·호스팅 URL 분류기, 메인 repo 읽기 전용) ② CI 계약 변이 2종 → `node scripts/check-ci-contract.ts` ③ 테스트 변이 5종 → `npx vitest run`(4파일 38테스트) ④ 실험 E-A·E-B·E-C와 번들 측정(`scratchpad/r13/exp.sh`, flock) ⑤ 호스트 전제 확인(`which bwrap systemd-run`, `systemctl --user --version`, `bwrap --unshare-net`, `sysctl kernel.apparmor_restrict_unprivileged_userns`) | +| 결과 요약 | 2절·4절의 각 항목에 적었다. 실험 원본 로그: `scratchpad/r13/` | +| 확인하지 못한 것 | 8절. 요약: 실제 Gitea runner 실행, Gitea 템플릿 생성 동작, 실제 호스트(nginx·caddy) 헤더, 브라우저 부팅, provider 실행, Playwright | +| 이전 리뷰와 비교 | `2026-09-29-maturity-review/13-build-release-supply-chain.md`의 10건과 그 README의 FOLLOW-UP 항목을 현재 코드로 다시 확인했다. 지난 실험 결과는 증거로 쓰지 않았다 | + +### 1.1 게이트 결과 중 이 영역에 해당하는 것 (오케스트레이터 실행, `d99301b`) + +| 게이트 | 결과 | 이 영역에 주는 의미 | +|---|---|---| +| `test:unit` | rc=0, 165파일 2,353테스트 | 영역 테스트 16파일 통과: `deployment-admission`(16), `sub-path-deployment`(3), `supply-chain`(30), `build-environment-bundle`(2, 3.97s), `release-artifacts`(29), `hosting-probe`(17), `security-promotion-staging`(9, 7.0s) 등 | +| `check:ci` | rc=0 | CI 계약과 생성 workflow가 일치한다 | +| `test:system` | **rc=1**, 2 failed / 110 passed | `cgroup` 테스트의 `ps failed`, 승격 CLI 출력 문자열 불일치(09-29 11-01). merge 게이트 FE-GATE-013의 첫 명령이라, 이 커밋으로 만든 새 프로젝트는 CI를 켜는 순간 merge가 빨갛다(영역 11) | +| `check:bundle` | 게이트 목록에 없음 | 실험 E-A에서 직접 측정했다(7절) | + +### 1.2 실험 목록 + +| ID | 무엇을 | 결과 | 쓰인 곳 | +|---|---|---|---| +| probe | `findAdmissionViolations`·`classifyLiveHostingBaseUrl` 직접 호출 | `api.example.com`·`api.invalid`·`desktop.test` 승인, `100.101.102.103`·`192.168.0.10` 거절, `*.ts.net` 승인, `/app/` base URL 거절 | 13-02, 3절, 2절 13-06 | +| E-A | production 프로필 빌드(SW `null`, `RUNTIME_*` 없음) → 승인 → 번들 측정 | 빌드 rc=0, `ADMITTED` rc=0, 초기 JS 203,513 B | 13-02, 7절 | +| E-B | SW `ACTIVE` + production 빌드 → 승인 | `dist/config.json`이 local, 승인 rc=1 | 2절 13-01 | +| E-C | `.env.production.local`에 `VITE_BUILD_ID`만 → 빌드 | 번들과 설정·manifest의 build id 불일치 | 2절 13-02 | +| E-G | `gates.json`에 env 바인딩 추가 / `deploy` job 추가 → `node scripts/check-ci-contract.ts` | 둘 다 rc=1(1건 / 6건) | 13-01, 13-02, 5.3 | +| M1~M5 | 영역 규칙 5개를 끄는 변이 → 4파일 38테스트 | 5/5 검출 | 7절 | + +실험 E-A~E-C는 `flock` 안에서 한 번에 돌렸다(18:08:02~18:08:06, 부하 평균 27.6). 모든 변이는 되돌렸고 worktree 두 개는 `git worktree remove --force`로 지웠다. + +## 2. 지난 발견 재확인 + +| ID(2026-09-29) | 내용 | 상태 | 현재 근거 | +|---|---|---|---| +| 13-01 (= 06-01) | SW `ACTIVE` 빌드와 `build:app-only`가 프로필 대신 로컬 설정을 `dist/config.json`에 싣는다 | **남음** | `vite.service-worker.config.ts:69-82`에 `publicDir` 설정이 없고 `emptyOutDir: false`(`:72`)다. `scripts/generate-build-manifest.ts:58-60`, `:124-128`은 그 파일을 읽어 `BUILD_ID`·`RELEASE_ID`만 바꾼다. `APP_ENV` 확인이 없다. SW 설정의 `APP_ENV` 대조(`scripts/lib/service-worker-build-input.ts:78-80`)는 설정 로드 때 돌아서, 그 뒤 Vite의 `public/` 복사를 보지 못한다. `build:app-only`(`package.json:125`)는 4단계(프로필)와 8단계(권한)를 건너뛴다. **실험 E-B(이번 커밋):** SW `ACTIVE` + `APP_PROFILE=production` + `VITE_BUILD_ID=rel-prod-b` 빌드 rc=0. 로그에는 4단계 "production profile written"이 찍힌다. 그런데 최종 `dist/config.json`은 `APP_ENV=local, AUTH_MODE=demo, API_BASE_URL=http://localhost:8080/, BUILD_ID=rel-prod-b`. 승인(`RELEASE_TARGET=production`) rc=1, 위반 4건(APP_ENV, AUTH_MODE, `http:`, localhost) | +| 13-02 | `.env*` 파일로 준 빌드 변수를 번들과 스크립트가 다르게 읽는다 | **남음** | `vite.config.ts:14`만 `loadEnv`를 쓰고 `:64-65`는 `process.env`. 스크립트도 `process.env`만 읽는다: `generate-runtime-config.ts:59`, `:70-74`, `generate-build-manifest.ts:36-38`, `vite.service-worker.config.ts:57-58`, `:94-96`. `.env.example:11`은 여전히 "`.env.local`로 복사해 덮어쓰라"고 적는다. **실험 E-C:** `.env.production.local`에 `VITE_BUILD_ID=env-file-id`만 두고 빌드 rc=0. 번들(`render-boot-failure-*.js`)에는 `env-file-id`, `dist/config.json`·`release-manifest.json`의 build id는 `local-build`. 부팅 대조(`src/bootstrap/load-runtime-config.ts:154-167`)에서 `CONFIG_BUILD_MISMATCH`가 난다(코드 읽기, 브라우저 미실행) | +| 13-03 | 청크 이름이 선언 없이 계약처럼 쓰인다 | **남음** | `tests/unit/build-environment-bundle.test.ts:68-76`(`design-system-` 청크 정확히 1개), `scripts/generate-build-manifest.ts:64-71`(`entry.name === runtime.moduleId`). 파일이 바뀌지 않았다 | +| 13-04 | 운영 CSP 확장 안내·내용 검사 없음, 4벌 복사 | **남음** | `config/hosting/security-headers.json:4`와 `response-headers.fixture.json`의 3개 사본. `scripts/check-browser-security.ts`에 헤더 검사가 없다(`headers`·`csp` grep 0건). `scripts/`에서 `unsafe-inline`·`unsafe-eval` grep 0건 | +| 13-05 | SBOM이 `deduped` 노드를 따라가지 않는다 | **남음** | `scripts/lib/supply-chain.ts:195-267`의 `visit`에 `deduped` 처리가 없다(grep 0건). 기준선의 `scheduler@0.27.0`은 여전히 `development`, production 행은 10개 | +| 13-06 | 하위 경로 배포에서 base를 따르지 않는 소비자 두 곳 | **남음(근거 정정)** | SW: `vite.service-worker.config.ts:94-96` 그대로. probe: 지난 문서는 "`HOSTING_BASE_URL=https://host/app/`이어도 `https://host/config.json`을 본다"고 적었다. 실제로는 그 전에 `scripts/lib/hosting-probe.ts:122-129`가 루트가 아닌 URL을 거절한다. probe 결과 `https://host.example.org/app/` → "HOSTING_BASE_URL must be the canonical root URL". 그래서 하위 경로 배포에서 FE-GATE-019는 PASS할 수 없다(`invalid-live` → FAIL) | +| 13-07 | 청크 설정이 폐기 예정 별칭 `build.rollupOptions`에 있다 | **남음** | `vite.config.ts:72`, `vite.service-worker.config.ts:74` | +| 13-08 | pnpm 설치 정책을 지키는 검사가 없다 | **남음** | `pnpm-workspace.yaml:1-18`에 `minimumReleaseAge`·`minimumReleaseAgeStrict`가 없다. `scripts/`·`tests/`에서 `engineStrict`·`saveExact`·`minimumReleaseAge` grep 0건 | +| 13-09 | README 변수 표에 staging·production의 `VITE_BUILD_ID` 필수 조건이 없다 | **남음** | `README.md:46` 기본값 `local-build`만 적는다. 코드는 `generate-runtime-config.ts:70-72`에서 거절한다. 테스트 변이 M3으로 이 규칙 자체는 테스트가 지킨다는 것을 확인했다 | +| 13-10 | 선택 기능을 켜야 재현되는 템플릿 결함의 책임 | **남음** | `README.md:348-353` 문구 그대로 | + +| FOLLOW-UP 항목(09-29 README) | 상태 | 현재 근거 | +|---|---|---| +| P1 초기 JS 예산 여유 | **남음** — 203,513 / 204,800, 여유 1,287 B | 실험 E-A 측정(7절) | +| P2 레시피 번들 예산 여유 | 미재측정 | `check:optional-recipes --require-dist`를 이번에 돌리지 않았다 | +| P2 운영 단계는 archive SHA만 대조, `--archived`는 수동 | 남음 | `.gitea/workflows/quality-gates.yml:404-405`. 이번 13-01이 같은 단계의 더 큰 공백을 다룬다 | +| F-11 SBOM `scheduler` 분류 | 남음 | 09-29 13-05와 같다 | + +## 3. 이번 라운드 추가 렌즈 — desktop 서버 배포 · Gitea 템플릿 시작 · CI/CD 자동화 + +사용자가 가려는 경로를 순서대로 따라가며 막히는 지점을 적었다. "막힘"은 진행이 멈추는 곳, "함정"은 진행은 되지만 틀린 결과가 나오는 곳이다. + +``` +Gitea "템플릿으로 새 저장소" + → repo 변수 설정(RUNNER_IMAGE_DIGEST, APP_PROFILE, RELEASE_TARGET, provider 4종, HOSTING_BASE_URL) + → PR: merge_gate 13 job + → tag v*: release_gate 4 job → immutable_build(빌드 1회 + 승인 FE-GATE-027) + → workflow_dispatch stage=production: … → provider 2 job → promotion → production_gate 6 job + → (템플릿 밖) desktop 서버에 dist 올리기, 활성 HTML 전환, smoke +``` + +| 단계 | 지점 | 종류 | 근거 | 관련 | +|---|---|---|---|---| +| 새 저장소 | Gitea 템플릿 변수 치환 파일(`.gitea/template`)이 없다. `package.json` `name`, `.template-origin`을 손으로 바꾸거나 써야 한다. Gitea 템플릿 변수에는 원본 커밋·태그가 없어 `.template-origin`을 자동으로 채울 수 없다(Gitea 문서 기준, E0) | 함정 | `ls .gitea` → `workflows/`만. `README.md:322-324` 수동 절차 | > 14 (업데이트 전파) | +| 새 저장소 | repo 변수는 템플릿 생성 때 복사되지 않는다. 비어 있으면 **모든 게이트**가 실행 전에 `missing required CI build environment: CI_RUNNER_IMAGE`로 실패한다. 메시지는 분명하다. 조직 단위 변수로 줄일 수 있다 | 막힘(명확) | `scripts/run-ci-gate.ts:101-104`, `scripts/lib/build-environment.ts:1-16`, `:30-38` | 결함 아님 | +| merge | 이 커밋의 FE-GATE-013이 빨갛다(`test:system` 2 failed). 새 프로젝트가 CI를 켜면 바로 머지가 막힌다 | 막힘 | 오케스트레이터 `test_system.log` | > 11 (09-29 11-01) | +| merge·release | job마다 캐시 없이 전체 설치를 한다. production 단계까지 27 job × `pnpm install --frozen-lockfile`(node_modules 332 MB), 브라우저 job 3개는 3엔진 `--with-deps` 설치. 단일 desktop runner(기본 동시 1)에서는 직렬로 돈다. 계약이 단계 종류를 고정해 캐시 단계를 넣을 수 없다 | 비용 | `scripts/contracts/ci-gates.ts:912-927`, workflow 각 job의 `Frozen install` | 5.3절 | +| 빌드 | 산출물은 환경마다 따로 빌드한다(`dist/config.json`을 빌드 때 확정). desktop 단일 환경이면 비용은 작다 | 설계 | `scripts/build-frontend.ts:64-65` | 5.1절 | +| 빌드 | CI는 `RUNTIME_API_BASE_URL`·`RUNTIME_TELEMETRY_ENDPOINT`를 넘길 수 없다. endpoint는 `config/runtime/production.json`에 커밋해야 한다. 안 고치면 `api.example.com`이 승인된다 | 함정 | `scripts/contracts/ci-gates.ts:932-937`, 실험 E-G, E-A | **13-02** | +| 빌드 | SW를 `ACTIVE`로 켜면 운영 빌드에 로컬 설정이 실린다 | 막힘(승인 거절) | 실험 E-B | 09-29 13-01 (= 06-01) | +| 승인 | staging·production은 사설·CGNAT·`.local`·`.internal` 호스트를 거절한다. LAN IP(`192.168.x.x`)나 Tailscale IP(`100.64.0.0/10`)로만 닿는 desktop 서버는 운영 승인을 받을 수 없다. 공개 DNS 이름(예: `*.ts.net`)과 HTTPS를 쓰면 통과한다 | 설계(의도) | `src/contracts/deployment-admission.ts:154-181`, probe: `100.101.102.103` 거절, `desktop.tail1234.ts.net` 통과 | 결함 아님 | +| 릴리스 승인 | 운영 단계는 `workflow_dispatch stage=production`으로만 돈다. 승인자는 "repo 쓰기 권한자"이고 `APP_PROFILE`·`RELEASE_TARGET`은 repo 전체 변수 하나씩이다. Gitea Actions에는 환경별 승인 대기 기능이 없다(E0). 1인 운영이면 충분하다 | 설계 | workflow `:9-21`, `:372`, `:127-129` | 결함 아님 | +| 승격 | provider 2개(취약점·provenance)와 Ed25519 키가 없으면 `promotion`이 실패하고 `production_gate`는 돌지 않는다. provider job은 호스트 systemd·bwrap·cgroup 위임이 필요하다 | 막힘 | `scripts/run-and-validate-provider.ts:72-92`, `:109-119`, `docs/operations/ci-quality-gates.md:176-184` | **13-03** | +| 배포 | workflow에 배포 job이 없고, CI 계약이 job 9개를 고정해 넣을 수 없다 | 막힘 | `scripts/contracts/ci-gates.ts:875-911`, 실험 E-G | **13-01** | +| 배포 | 이전 release의 해시 자산을 남기고 HTML만 원자적으로 바꾸라는 규칙은 문서뿐이다. 단일 호스트용 참조 스크립트가 없다. `rsync --delete`처럼 흔한 방법은 열린 탭의 청크를 지운다 | 함정 | `docs/operations/release-cache-rollback.md:1-12`, `:73-77` | 5.3절 | +| 호스트 설정 | 헤더·캐시는 JSON 선언뿐이고 nginx·caddy 예시가 없다. SPA fallback 선언·검사가 없다 | 함정 | `config/hosting/*.json`, `verify-hosting-headers.ts:120-125` | **13-04** | +| 호스트 설정 | `Strict-Transport-Security: …; includeSubDomains`. 앱을 apex 도메인에 올리면 같은 도메인의 다른 서비스(HTTP만 쓰는 내부 서비스 포함)도 1년간 HTTPS가 강제된다. `app.example.org` 같은 하위 도메인이면 영향이 그 아래로 한정된다 | 주의 | `config/hosting/security-headers.json:5` | 결함 아님 | +| 배포 후 확인 | FE-GATE-019는 배포물이 후보인지 확인하지 않는다. 하위 경로 URL은 아예 거절한다 | 함정 | `verify-hosting-headers.ts:77-134`, `hosting-probe.ts:122-129` | **13-01**, 09-29 13-06 | +| 운영 중 변경 | 비상 스위치(SW `DISABLED`, `FEATURE_OVERRIDES`)는 배포된 `config.json`을 고쳐서 쓴다. 고친 문서를 검증하는 명령이 없다 | 함정 | `docs/operations/release-cache-rollback.md:93-98`, `docs/runbooks/FE-RB-001.md` | **13-05** | + +## 4. 새 발견 사항 (36.3) + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 한 줄 | +|---|---|---|---|---|---| +| 13-01 | Medium | P1 | 확인된 결함 | 18, 21, 5, 28, 3, 26 | 운영 단계 검사가 배포물을 후보와 대조하지 않고, 배포 job 자리가 없다 | +| 13-02 | Medium | P1 | 확인된 결함 | 19, 21, 15, 18, 20 | 승인이 `*.example.com` 자리표시자를 통과시키고 CI는 `RUNTIME_*`를 못 넘긴다 | +| 13-03 | Medium | P2 | 구조적 위험 | 18, 16, 20, 26 | provider job의 호스트 전제와 workflow의 컨테이너 전제가 어긋나고, provider 없는 배포 경로가 없다 | +| 13-04 | Medium | P2 | 확인된 결함 | 18, 21, 19, 20, 10 | 호스팅 계약이 SPA fallback·SW 스크립트 헤더를 선언·검사하지 않는다 | +| 13-05 | Low | P2 | 확인된 결함 | 19, 28, 8, 20, 24 | 재빌드 없는 설정 변경(비상 스위치)에 검증 명령·절차가 없다 | + +### 13-01 운영 단계 검사가 배포된 release가 승격 후보인지 확인하지 않고, 배포 job을 넣을 자리도 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 21, 5, 28, 3, 26 (+30.7, 30.8) | +| 근거 | **순서:** `production_gate`는 `needs: [immutable_build, promotion]`이고 `promotion` 직후 같은 run에서 시작한다(`.gitea/workflows/quality-gates.yml:369-372`). 그 사이에 배포 job이 없다. **문서 주장:** "FE-GATE-019 … runs after `promotion` and after the project has deployed the promoted release"(`docs/operations/release-cache-rollback.md:67-71`), 같은 문장이 `docs/architecture/static-delivery.md:31-34`, 코드 주석 `scripts/verify-hosting-headers.ts:79-80`, `scripts/contracts/ci-gates.ts:977-980`에 있다. **자리 없음:** CI 계약이 job 목록·그래프·env를 정확히 고정한다(`ci-gates.ts:875-911` "exact nine canonical jobs", `:895-911` job graph, `:929-998` env 바인딩). 실험 E-G: `promotion`과 `production_gate` 사이에 `deploy` job을 넣자 `node scripts/check-ci-contract.ts`가 6건으로 실패했다("job registry must contain the exact nine canonical jobs", "job graph drift: production_gate", "multiply owned gate: FE-GATE-019" 등). **식별 대조 없음:** live probe는 `/`, `/config.json`, `/release-manifest.json`, entry script의 상태·origin·헤더만 본다(`verify-hosting-headers.ts:81-134`). 배포된 manifest의 `buildId`·`releaseId`나 `index.html`을 후보 archive와 비교하지 않는다. **로컬 재빌드:** FE-GATE-019의 명령은 `[build, verify-hosting-headers]`다(`config/ci/gates.json:2073-2077`). `production_gate` env에는 `APP_PROFILE`이 없어(`ci-gates.ts:981-984`) 이 `build`는 local 프로필로 다시 빌드한다. source map·SW 검사(`verify-hosting-headers.ts:70-71`, `:192-205`)는 승격 후보가 아니라 이 재빌드의 `dist`를 본다. 같은 job의 drill 5개는 09-29 이전 수정으로 `--release-root .release/promoted-release`를 쓴다(`docs/operations/ci-quality-gates.md` 13-03 단락). | +| 발생 조건 | `workflow_dispatch stage=production`(또는 `field`)으로 운영 단계를 돌릴 때. 항상 | +| 영향 | FE-GATE-019 PASS는 "지금 떠 있는 release(대개 이전 것)의 헤더가 맞다"는 뜻이 된다. 새 release를 올린 뒤 같은 후보로 다시 검사할 방법이 없다. 다시 dispatch하면 `immutable_build`가 새 run id로 새 후보를 만든다(`CANDIDATE_ARCHIVE_SHA256`이 달라진다). CD를 자동화하려는 프로젝트는 계약을 고치거나 별도 workflow를 만들어야 하고, 그 workflow는 승격 후보와의 연결을 스스로 다시 만들어야 한다 | +| 심각도·우선순위 | Medium · P1 — 사이트를 직접 망가뜨리지는 않는다. 대신 배포 검증의 핵심 질문(가이드 18절 1번: 검증한 산출물과 배포한 산출물의 식별값이 같은가)에 거짓 PASS를 준다. 사용자가 밝힌 용도(CD 자동화)의 도입 전 차단 항목이다 | +| 통제·증거 | 배포물 식별 대조 M0 / 순서 보장 M0(문서 M1만) / CI 계약 고정 M3 · E3(실험 E-G) + E1(workflow·probe 코드) | +| 확실성과 남은 가정 | job 순서·계약 고정·probe 내용은 코드와 실험으로 확인했다. 실제 Gitea runner에서 돌려 보지는 않았다(U-1). Gitea Actions의 `workflow_run` 트리거 지원 여부는 확인하지 않았다(별도 workflow 대안의 실현성) | +| 결정의 근거 | 5.3절. 확인한 사실: 계약이 job을 고정한다. 기록된 의도: "This repository's workflow stops at promotion"(`release-cache-rollback.md:69-71`). 리뷰어 추론: 배포를 템플릿 밖에 두는 결정과, 배포 뒤에 도는 검사를 템플릿 안에 고정하는 결정이 서로 맞지 않는다 | +| 이해 비용 | CD를 붙이는 사람은 `gates.json` 2,940줄, `ci-gates.ts`의 고정 표 4개, 생성기, 계약 기준선(`config/ci/contract-baseline.json`)을 함께 바꿔야 한다는 것을 실패 메시지로 알게 된다 | +| 최소 개선 방향 | (1) live probe가 배포된 `release-manifest.json`의 `buildId`·`releaseId`와 `index.html`이 추출한 후보(`.release/promoted-release/dist`)와 같은지 확인한다. 다르면 FAIL. (2) FE-GATE-019의 `build`를 빼고 drill처럼 `--release-root`로 후보 `dist`를 본다. (3) 계약에 `promotion`과 `production_gate` 사이 "프로젝트 배포 슬롯" job 하나를 선언한다. 기본은 비어 있고, 비어 있으면 `production_gate`가 `UNVERIFIED`로 끝난다 | +| 대안 비교 | (a) 현상 유지 — 문서와 동작이 계속 어긋난다. (b) (1)·(2)만 — 거짓 PASS는 사라지지만 배포 자리는 여전히 없어 운영 단계가 항상 FAIL이 된다(정직하지만 쓸 수 없음). (c) (1)~(3) — 계약 강도를 유지하며 확장 자리를 준다. (d) `production_gate`를 별도 workflow로 분리하고 승격 run id·archive SHA를 입력으로 받는다 — 배포 시점과 검사 시점을 떼어 놓을 수 있지만 run 사이 artifact 전달 방법이 Gitea에서 검증되지 않았다 | +| 단순화의 보존 조건 | 승격 job은 빌드하지 않는다. drill은 후보 archive만 본다. fixture 모드는 `UNVERIFIED`(exit 3)로 끝난다. gate 소유 job은 하나다 | +| 비용·부작용 | (1)·(2)는 작다(probe에 비교 2개, gates.json 명령 1개). (3)은 계약·생성기·기준선·테스트 수정이 필요하다 | +| 재검토 조건 | 템플릿이 provider adapter(배포 스크립트)를 직접 제공하게 되면 슬롯 대신 그 job을 고정한다 | +| 완료 기준 | 이전 release가 떠 있는 호스트를 `HOSTING_BASE_URL`로 주면 FE-GATE-019가 FAIL한다. `production_gate`에서 `build`가 돌지 않는다. 계약이 허용하는 배포 job을 넣어도 `check:ci`가 통과한다 | +| 검증 방법 | `tests/unit/hosting-probe.test.ts`에 "manifest buildId 불일치 → FAIL" 케이스. `tests/unit/ci-workflow-generation.test.ts`에 배포 슬롯 케이스. 실제 runner 1회 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 13-02 공개 대상 승인이 템플릿 자리표시자 endpoint(`*.example.com`)를 통과시키고, CI에서는 `RUNTIME_*`로 바꿀 길이 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 21, 15, 18, 20 (+30.1, 30.5) | +| 근거 | **자리표시자:** `config/runtime/production.json:3`, `:7` — `https://api.example.com/`, `https://telemetry.example.com/v1/events`, `TELEMETRY_ENABLED: true`. staging도 같다(`staging.example.com`). **승인 규칙:** `publicEndpointViolations`는 `https:`와 비공개 호스트만 본다(`src/contracts/deployment-admission.ts:111-131`, `:154-181`). 같은 파일 주석은 이 규칙의 목적을 "a developer configuration that escaped"를 막는 것이라고 적는다(`:148-153`). **probe:** `api.example.com`, `api.invalid`, `desktop.test` → 모두 `ADMITTED`. RFC 2606·6761이 예시·테스트용으로 예약한 이름이다. **실험 E-A(종단):** `APP_PROFILE=production VITE_BUILD_ID=rel-prod-a RELEASE_ID=rel-a`, `RUNTIME_*` 없이 빌드 rc=0 → `dist/config.json`은 `API_BASE_URL=https://api.example.com/`, `TELEMETRY_ENABLED=true`, `TELEMETRY_ENDPOINT=https://telemetry.example.com/v1/events`. `RELEASE_TARGET=production` 승인 → `production ADMITTED`, rc=0. **CI 주입 불가:** CI 계약이 `immutable_build`의 env를 `APP_PROFILE`·`RELEASE_TARGET` 두 개로 고정한다(`scripts/contracts/ci-gates.ts:932-937`, `:991-997`). 실험 E-G: `RUNTIME_API_BASE_URL` 바인딩 하나를 더하자 "job environment binding drift: immutable_build"로 실패. 그런데 `generate-runtime-config.ts:29-36`은 이 두 값을 "the only values a deployment may inject"라고 부르고, README 운영 빌드 예시(`README.md:57-64`)는 `RUNTIME_API_BASE_URL=https://api.example.com/`을 그대로 쓴다 | +| 발생 조건 | Gitea 템플릿으로 만든 새 프로젝트가 `APP_PROFILE=production`, `RELEASE_TARGET=production`만 설정하고 `config/runtime/production.json`을 고치지 않았을 때. 또는 README 예시를 그대로 붙였을 때 | +| 영향 | 모든 API 호출이 실패하는 빌드가 운영 승인을 받는다. CD가 자동이면 그대로 배포된다. telemetry가 켜져 있어 사용자 이벤트가 프로젝트가 소유하지 않은 도메인으로 전송을 시도한다(`connect-src 'self' https:`라 CSP도 막지 않는다, `config/hosting/security-headers.json:4`) | +| 심각도·우선순위 | Medium · P1 — 첫 부팅에서 바로 드러나고 새 프로젝트라 사용자가 적다. 다만 사용자가 밝힌 "템플릿으로 자동 시작 + 자동 배포" 경로에서 정확히 이 값이 나간다. 고치는 비용은 몇 줄이다 | +| 통제·증거 | 비공개 호스트 거절 M3(변이 M1로 확인) / 자리표시자 거절 M0 · E3(실험 E-A) + E2(probe) | +| 확실성과 남은 가정 | `*.example.com` 하위 이름이 실제로 해석되는지는 확인하지 않았다(외부 요청 금지). 해석되지 않아도 API 실패라는 영향은 같다 | +| 결정의 근거 | 적용 제외 — 이미 있는 규칙("새어 나간 개발 설정을 거절한다")이 가장 흔한 새어 나간 값을 빠뜨린 구현 결함이다 | +| 이해 비용 | 새 프로젝트 작성자는 승인 통과를 "운영 설정이 맞다"로 읽는다. 실제로는 프로필 파일을 직접 열어 봐야 안다 | +| 최소 개선 방향 | (1) `isNonPublicHost` 옆에 예약 이름 거절을 더한다: `example.com`·`example.net`·`example.org`와 그 하위, `.example`, `.invalid`, `.test`. (2) README 운영 예시의 URL을 `` 같은 빈칸으로 바꾼다. (3) CI에서 endpoint를 바꾸는 방법은 "프로필 파일을 커밋한다" 하나라고 README 변수 표에 적는다(13-01 (3)의 슬롯을 만들면 거기에 `RUNTIME_*` 허용 목록을 둔다) | +| 대안 비교 | 프로필의 기본값을 비워 두는 방법도 있다. 그러면 스키마가 `API_BASE_URL`을 요구해 빌드가 실패한다. 더 확실하지만 `config/runtime/production.json`이 예시로서 읽히지 않고, staging·development 프로필도 같이 바꿔야 한다. 승인 규칙 한 곳이 더 작다 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 작다. 실제로 `*.test` 도메인을 운영에 쓰는 프로젝트는 없다고 가정한다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 프로필을 고치지 않은 production 빌드의 승인이 `API_BASE_URL`, `TELEMETRY_ENDPOINT` 두 위반으로 거절된다 | +| 검증 방법 | `tests/unit/deployment-admission.test.ts`에 예약 이름 3종 케이스. 실험 E-A 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 13-03 운영 승격의 runner 전제가 workflow의 runner 전제와 어긋나고, provider 없이 배포하는 경로가 문서에 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 18, 16, 20, 26 (+30.2, 30.6, 30.8) | +| 근거 | **provider 전제:** `scripts/run-and-validate-provider.ts:109-119`는 `/usr/bin/bwrap`, `/usr/bin/systemd-run`, `/usr/bin/systemctl`이 없으면 멈춘다. 문서는 active user bus, systemd user manager 254 이상, cgroup v2와 위임된 memory·pids·CPU 컨트롤러를 요구한다(`docs/operations/ci-quality-gates.md:176-184`). **workflow 전제:** provider job도 `runs-on: ubuntu-latest`다(workflow `:208`, `:254`). 문서는 이 label을 "immutable container image에 매핑하고 그 digest를 `RUNNER_IMAGE_DIGEST`에 넣으라"고 한다(`ci-quality-gates.md:288-294`). act_runner의 컨테이너 job 안에는 보통 systemd user manager와 user bus가 없다(리뷰어 추론, 미실행). `CI_RUNNER_IMAGE`는 `@sha256:` 형식만 확인하고 실제 image와 대조하지 않는다(`scripts/lib/build-environment.ts:30-38`). **호스트 확인(이 desktop):** `bwrap`, `systemd-run` 있음, `systemd 255`. `kernel.apparmor_restrict_unprivileged_userns = 1`. 이번 세션의 `bwrap --unshare-net --ro-bind / / /bin/true`는 rc=0이었지만, 원장은 같은 기계에서 같은 명령이 "Failed RTM_NEWADDR: Operation not permitted"로 실패한 기록을 남겼다(`docs/operations/adapter-remediation-ledger.md:517-526`). 오케스트레이터 `test:system`의 cgroup 테스트도 이번에 실패했다(`ps failed`). **provider 없는 경로:** provider 변수가 비면 `run-and-validate-provider.ts:72-92`가 멈추고 `promotion`·`production_gate`가 돌지 않는다. 그때 `immutable_build`의 승인된 후보 archive를 배포해도 되는지, 무엇을 잃는지는 문서에 없다(`docs/` grep) | +| 발생 조건 | desktop에 Gitea act_runner 한 대를 두고 운영 단계까지 자동화하려 할 때 | +| 영향 | runner를 컨테이너 모드로 두면 provider job이 실패한다(추론). 호스트 모드로 두면 `RUNNER_IMAGE_DIGEST`는 실제 환경과 무관한 자기 기재 값이 된다. 어느 쪽이든 사용자는 promotion을 우회하는 자체 경로를 만들 가능성이 높고, 그 경로는 템플릿이 검증하지 않는다 | +| 심각도·우선순위 | Medium · P2 — fail-closed라 틀린 것이 나가지는 않는다. 운영 단계 자동화를 막는다. provider를 둘지 결정이 먼저 필요하다 | +| 통제·증거 | provider 전제 검사 M3(preflight) / runner image 대조 M1(형식만) / provider 없는 경로 M0 · E1 + 호스트 확인 일부 | +| 확실성과 남은 가정 | 실제 act_runner(컨테이너·호스트 모드)에서 provider job을 돌리지 않았다. 컨테이너 안에서 실패한다는 것은 추론이다 | +| 결정의 근거 | 5.2절 | +| 이해 비용 | provider 하나를 붙이려면 서명 키 관리, 출력 스키마(`scripts/lib/provider-evidence.ts`), sandbox 전제, guardian 프로토콜을 알아야 한다 | +| 최소 개선 방향 | (1) `ci-quality-gates.md`에 "provider job은 호스트 모드 runner(별도 label 권장)에서 돈다. 그 job의 `CI_RUNNER_IMAGE`는 의미가 없다"를 적거나, provider job에 별도 label을 쓴다. (2) "provider 없이 배포할 때"를 한 절로 적는다: 무엇을 배포하는가(`immutable_build`의 `release-candidate-*.tar.gz`), 무엇이 빠지는가(독립 취약점 판정·provenance), 운영 단계 검사는 어떻게 되는가 | +| 대안 비교 | 5.2절 (a)~(c) | +| 단순화의 보존 조건 | provider가 있을 때의 서명·nonce·archive SHA 검증은 그대로 둔다 | +| 비용·부작용 | 문서 두 단락, 또는 label 하나와 계약 수정 | +| 재검토 조건 | 실제 Gitea runner에서 provider smoke 1회가 통과하면 (1)을 그 설정으로 대체한다 | +| 완료 기준 | 문서만 보고 provider job이 도는 runner를 만들 수 있다. provider가 없는 프로젝트가 배포할 파일과 남는 위험을 문서에서 찾을 수 있다 | +| 검증 방법 | 컨테이너 모드·호스트 모드 act_runner에서 provider job 1회씩 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 13-04 호스팅 계약이 SPA fallback과 SW 스크립트 헤더를 선언·검사하지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 18, 21, 19, 20, 10 (+30.1) | +| 근거 | **라우터:** `src/presentation/routes/app-router.tsx:10`, `:590` `createBrowserRouter`. 경로 기반 URL이라 `/examples/ui`를 새로고침하면 호스트가 `index.html`을 줘야 한다. **문서 주장:** "browser-history routing을 사용하면 hosting의 SPA fallback을 release 계약으로 검증한다"(`docs/architecture/frontend-ports-adapters-and-boundaries.md:1152-1153`). **선언:** `config/hosting/cache-policy.json`의 표면은 `index`(`/`), `runtimeConfig`, `releaseManifest`, `hashedAsset`, `sourceMap`뿐이다. 앱 경로 표면이 없다. `service-worker.js`도 없다. 그런데 운영 문서는 SW 스크립트를 `no-cache`로 서빙하라고 적는다(`docs/operations/release-cache-rollback.md:47-51`). **검사:** live probe는 `/`, `/config.json`, `/release-manifest.json`, entry script만 요청한다(`scripts/verify-hosting-headers.ts:120-125`). **e2e가 못 잡는 이유:** e2e 서버는 `vite preview`다(`playwright.config.ts:17-20`). Vite preview는 SPA fallback을 기본으로 한다. **호스트 예시:** `docs/`·`config/`에 nginx·caddy·`try_files` 예시가 없다(grep) | +| 발생 조건 | desktop 서버의 nginx·caddy에 fallback을 빠뜨렸을 때 | +| 영향 | 첫 화면(`/`)은 열린다. 앱 안 이동도 된다. 새로고침, 북마크, 공유 링크는 404다. FE-GATE-019는 PASS한다. fallback 응답에 보안 헤더가 빠져도 모른다 | +| 심각도·우선순위 | Medium · P2 — 운영에서 바로 보이는 기능 실패다. 대신 발견이 쉽고 고치기 쉽다. 프로젝트마다 같은 실수를 반복할 수 있다 | +| 통제·증거 | fallback 선언 M1(문서 한 줄) / 검사 M0 · E1 | +| 확실성과 남은 가정 | 실제 호스트에서 재현하지 않았다. 동작은 정적 호스팅의 일반 동작이다 | +| 결정의 근거 | 적용 제외 — 문서가 요구한 계약을 선언·검사에 넣지 않은 누락이다 | +| 이해 비용 | 서버를 설정하는 사람이 JSON 두 개와 운영 문서 세 곳을 읽고 직접 서버 문법으로 옮겨야 한다 | +| 최소 개선 방향 | (1) `cache-policy.json`에 `appRoute`(예: `/__probe/deep-link`, `index`와 같은 헤더) 표면과 SW `ACTIVE`일 때의 `serviceWorker`(`/service-worker.js`, `no-cache`) 표면을 더한다. (2) live probe가 두 표면을 요청한다. (3) `docs/operations/`에 desktop 서버용 nginx 예시 하나(fallback, 표면별 `Cache-Control`, 보안 헤더)를 둔다. 예시는 선언 JSON에서 생성하지 않고 손으로 쓰되, probe가 결과를 확인한다 | +| 대안 비교 | `createHashRouter`로 바꾸면 fallback이 필요 없다. URL이 바뀌고 기존 경로 계약·테스트가 모두 바뀌어 비용이 크다. 기각 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 작다. 호스트가 fallback 경로에 다른 캐시 헤더를 주면 새로 실패한다(의도) | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | fallback이 없는 호스트에서 FE-GATE-019가 FAIL한다 | +| 검증 방법 | `tests/unit/hosting-probe.test.ts` 또는 probe를 함수로 분리한 단위 테스트에 404 응답 케이스 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 13-05 "재빌드 없이 설정을 바꾼다"는 비상 스위치에 검증된 절차가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 19, 28, 8, 20, 24 | +| 근거 | **약속:** `.env.example:6-9` "materialized into `dist/config.json` at build time, so it can be changed without rebuilding". `docs/operations/release-cache-rollback.md:93-98` "Turn the worker off without a rebuild. Set `CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"` in the runtime config". 원장 OPS-21은 `FEATURE_OVERRIDES`로 기능을 재빌드 없이 내린다고 적는다(`docs/operations/adapter-remediation-ledger.md:506`). **절차 없음:** 런북 `docs/runbooks/FE-RB-001.md`는 세 줄이고 고치는 방법이 없다. 배포된 문서를 검증하는 명령이 없다. `check:release-admission`은 `dist/config.json` 경로를 고정해 읽는다(`scripts/check-release-admission.ts:29`). `build:profile`(`package.json:14`)은 프로필에서 문서를 다시 만들고 `BUILD_ID`를 `VITE_BUILD_ID` 또는 `local-build`로 덮는다(`scripts/generate-runtime-config.ts:73-76`). 배포 때와 같은 build id를 주지 않으면 부팅이 `CONFIG_BUILD_MISMATCH`로 멈춘다(`src/bootstrap/load-runtime-config.ts:154-167`). **부팅 검증:** 브라우저는 고친 문서를 스키마로 검사하고 실패하면 지원 화면으로 멈춘다(`load-runtime-config.ts:140-149`). 즉 잘못 고치면 전 사용자 부팅 실패다 | +| 발생 조건 | 장애 중에 운영자가 desktop 서버의 `config.json`을 직접 고칠 때 | +| 영향 | 오타 하나로 모든 사용자가 `BOOT_CONFIG_FAILURE`를 본다. 원래 장애보다 범위가 커진다. 고친 문서는 승인(FE-GATE-027)과 release 기록(`checksums.txt`, 승격 archive)과도 달라진다 | +| 심각도·우선순위 | Low · P2 — 평소에는 영향이 없다. 비상 도구는 쓸 때 안전해야 하고, 고치는 비용이 작다 | +| 통제·증거 | 부팅 시 스키마 검증 M3 / 변경 전 검증·절차 M0 · E1 | +| 확실성과 남은 가정 | 정적 확인. 실제로 문서를 고쳐 부팅해 보지 않았다 | +| 결정의 근거 | 5.1절의 결론(빌드 때 확정 유지)을 전제로, 그 예외 경로를 안전하게 만드는 문제다 | +| 이해 비용 | 운영자가 스키마(`src/contracts/release-artifacts.ts`), 승인 규칙, build id 대조를 알아야 안전하게 고칠 수 있다 | +| 최소 개선 방향 | (1) `check:release-admission`이 `--config `를 받게 해 배포된 사본을 검사할 수 있게 한다(스키마 + 대상 규칙 + 원래 `BUILD_ID` 유지 확인). (2) FE-RB-001과 `release-cache-rollback.md`에 "사본을 받아 고치고 → 검사하고 → 원자적으로 바꾸고 → 깨끗한 세션으로 부팅 확인" 네 줄을 적는다. (3) `.env.example:8-9` 문장을 "비상 스위치만 재빌드 없이 바꾼다"로 좁힌다 | +| 대안 비교 | 비상 스위치를 빌드로만 바꾸게 하는 방법도 있다. 장애 대응 시간이 빌드·승격 시간만큼 늘어 스위치의 목적이 사라진다. 기각 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 작다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 배포된 `config.json` 사본에 오타를 넣으면 명령 하나가 실패한다. 런북에 그 명령이 있다 | +| 검증 방법 | 승인 스크립트에 `--config` fixture 테스트 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 설명 (41절) + +지난 라운드의 4.1(public 복사 후 프로필로 덮어쓰기), 4.2(build id를 번들에 넣고 청크 분할은 자동), 4.3(모든 환경에 CSP 하나)은 코드가 그대로라 결론도 그대로다. 이번에는 CD 경로에 걸린 선택 세 개를 본다. + +### 5.1 런타임 설정을 빌드 때 `dist/config.json`으로 확정하고, 환경마다 따로 빌드한다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 부팅 전에 설정을 검증한다. 운영 대상에 맞는 설정인지 승인한다. JS와 설정이 같은 release인지 확인한다. 장애 때 일부 기능을 끌 수 있다 | +| 2. 지킬 성질 | 배포된 `config.json`은 승인된 프로필 + 승인된 endpoint + 같은 build id다. 운영 중 바꾼 값도 스키마와 승인 규칙을 통과한다 | +| 3. 현재 보장 | 빌드 4단계가 프로필로 문서를 만든다(`build-frontend.ts:64-65`). 승인이 `dist/config.json`을 읽는다(E3, 실험 E-A). 부팅이 build id를 대조한다(`load-runtime-config.ts:154-167`). **보장하지 않는 것:** SW 두 번째 빌드의 덮어쓰기(09-29 13-01), CI의 endpoint 주입(13-02), 배포 후 변경의 검증(13-05) | +| 4. 대안 | (a) 현상 유지. (b) 한 번 빌드하고, 배포 때 환경별 `config.json`만 만들어 승인하는 명령을 둔다(build once, configure per environment). (c) 호스트(nginx)가 설정을 치환한다 | +| 5. 비교 | (a) 승인 대상이 곧 배포물이다. 환경 수만큼 빌드·후보·provider 비용이 든다. desktop 단일 환경이면 비용이 작다. (b) staging에서 검증한 바이트를 production에 그대로 올리는 승격과 맞는다. 대신 승격 archive와 `checksums.txt`가 `config.json`을 포함하므로 archive 구성과 검증을 바꿔야 한다. (c) 승인 밖에서 값이 바뀐다. 기각 | +| 6. 현재 조건에서의 판단(리뷰어 추론) | 단일 desktop 서버, 환경 1~2개라는 조건에서는 (a) 유지가 맞다. 비상 스위치처럼 이미 있는 "재빌드 없는 변경" 경로만 검증 명령으로 막는다(13-05) | +| 7. 재검토 조건 | staging → production 바이트 동일 승격이 요구되거나 환경이 3개 이상으로 늘면 (b)를 다시 본다 | + +### 5.2 운영 승격에 독립 provider 두 개와 서명 검증을 필수로 둔다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 배포물의 취약점 판정과 출처 기록을 빌드한 주체가 아닌 쪽이 서명한다 | +| 2. 지킬 성질 | 검증한 archive와 승격한 archive가 같다. provider 결과를 위조하거나 다른 run에 재사용할 수 없다 | +| 3. 현재 보장 | archive SHA, nonce, Ed25519 검증, offline sandbox(`run-and-validate-provider.ts`, `scripts/lib/provider-*.ts`). `tests/system` 108개 중 106개가 이번에 통과했다(영역 11). **보장하지 않는 것:** runner가 전제를 만족하는지, provider 없는 프로젝트가 무엇을 배포하는지(13-03) | +| 4. 대안 | (a) 현상 유지. (b) provider를 선택으로 바꾼다. 없으면 `promotion`이 `UNVERIFIED`로 끝나고, 승인된 `immutable_build` 후보가 배포 입력이라고 문서화한다. (c) 템플릿이 로컬 scanner를 내장한다 | +| 5. 비교 | (a) 공급망 증거가 가장 강하다. desktop act_runner에서는 호스트 모드 runner와 systemd user 설정이 필요하고, 성립 여부가 미검증이다. (b) 1인 운영에 현실적이다. 승격의 의미가 약해지는 것을 문서에 드러내야 한다. (c) 의존성이 늘고 서명 주체가 분리되지 않아 (a)의 목적이 사라진다 | +| 6. 현재 조건에서의 판단(리뷰어 추론) | 템플릿 기본값으로 (a)를 유지할 가치는 있다. 다만 "provider 없이 배포할 때"를 적지 않으면 사용자는 검증되지 않은 우회 경로를 만든다. (b)의 문서 한 절이 최소 변경이다 | +| 7. 재검토 조건 | 실제 Gitea runner에서 provider smoke가 통과하거나, 조직 단위 provider가 생기면 다시 본다 | + +### 5.3 CI 계약이 job 9개·그래프·단계 종류·env 바인딩을 정확히 고정한다 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 생성된 workflow가 gate 순서와 승격 규칙을 우회하지 못하게 한다 | +| 2. 지킬 성질 | 승격은 검증된 archive로만 한다. gate마다 소유 job은 하나다. job 입력은 선언된 env뿐이다 | +| 3. 현재 보장 | `scripts/contracts/ci-gates.ts:875-998`(job 목록, 소유, 그래프, 단계 종류, env). 실험 E-G에서 env 추가·job 추가가 모두 거절됐다(M3, E3). **보장하지 않는 것:** 다운스트림이 꼭 넣어야 하는 배포 job, 설치 캐시, 환경별 endpoint를 넣을 자리 | +| 4. 대안 | (a) 현상 유지. (b) 확장 슬롯을 계약에 선언한다: `promotion`과 `production_gate` 사이 배포 job 하나(기본 비어 있음), `immutable_build`의 env 허용 목록(`RUNTIME_*`), 설치 단계의 캐시 옵션. (c) 고정 검사를 지우고 리뷰에 맡긴다 | +| 5. 비교 | (a) 가장 강하지만 CD를 붙이는 순간 계약을 고쳐야 한다(13-01). 27 job이 캐시 없이 설치하는 비용도 고정된다. (b) 계약 강도를 유지하며 소비자가 바꿀 곳을 이름 붙여 준다. 계약·생성기·기준선·테스트 수정 비용이 든다. (c) 우회를 다시 허용한다. 기각 | +| 6. 현재 조건에서의 판단(리뷰어 추론) | (b). 이 repo의 전제("빈 레지스트리는 다운스트림 확장 지점")와 같은 방식이다. 지금 계약에는 그 자리가 없다 | +| 7. 재검토 조건 | 템플릿이 배포 adapter를 직접 제공하게 되면 슬롯 대신 그 job을 고정한다 | + +## 6. 리팩토링 후보 + +| ID | 무엇을 | 왜 | 보존할 동작·타입·실패 계약 | +|---|---|---|---| +| R-1 | `build:app-only` 제거(또는 `build`의 별칭으로) | 프로필·권한 단계를 건너뛰어 로컬 설정과 0600 파일을 낸다(09-29 13-01). 소비자는 `tests/unit/product-index-entrypoints.test.ts:12` 목록뿐이다. 영역 12의 12-05(사문화 script)와 같은 대상이다 | 없음. 목록에서 이름을 지운다 | +| R-2 | 빌드 입력 읽기를 한 함수로(`readBuildInputs(env)`) 모은다 | `VITE_BUILD_ID` 기본값을 4곳에서 따로 계산한다: `generate-runtime-config.ts:73`(`||`), `generate-build-manifest.ts:36`(`??`), `vite.service-worker.config.ts:57`(`??`), 번들(`src/contracts/env.ts`). 빈 문자열이면 번들·4단계는 `local-build`, 7단계는 `""`를 써서 스키마(`nonEmptyString`, `scripts/contracts/release-artifacts.ts:1246`)에서 실패한다(코드 읽기·미실행). base·설정 URL도 두 방식이다(09-29 13-02, 13-06) | 미선언 `VITE_*` 거절(`vite.config.ts:13-24`), staging·production build id 필수(변이 M3이 지키는 테스트), 기본값 `local-build`·`local-release`, base 형식 검사(`vite.config.ts:35-44`) | +| R-3 | CSP 한 벌 — fixture가 선언 파일에서 읽는다 | 같은 문자열 4벌(09-29 13-04) | fixture 모드 `UNVERIFIED`(exit 3, 변이 M5가 지키는 테스트) | +| R-4 | FE-GATE-019의 `build` 제거, 후보 `dist`를 `--release-root`로 | 운영 단계에서 local 프로필로 다시 빌드한다(13-01) | source map 공개 금지, SW 스크립트 허용 목록 검사(`hosting-probe.ts:38-58`) | +| R-5 | `rollupOptions` → `rolldownOptions` | 폐기 별칭(09-29 13-07) | `preload-helper` 청크 분리 | + +## 7. 테스트·성능·폴더 구조 렌즈 + +**테스트.** 영역 테스트가 있는 규칙을 실제로 지키는지 변이 5개로 확인했다(`wt-13m`, 4파일 38테스트 기준선 통과, 실행 약 3초). + +| 변이 | 결과 | +|---|---| +| M1 비공개 호스트 거절을 끈다(`deployment-admission.ts:125`) | 잡음 — 2 failed | +| M2 `APP_PROFILE`≠`RELEASE_TARGET` 거절을 끈다(`check-release-admission.ts:48`) | 잡음 — 1 failed | +| M3 staging·production build id 필수를 끈다(`generate-runtime-config.ts:70`) | 잡음 — 1 failed | +| M4 manifest URL rebasing을 끈다(`generate-runtime-config.ts:66`) | 잡음 — 1 failed | +| M5 fixture 모드를 PASS로 센다(`hosting-probe.ts:15`) | 잡음 — 1 failed | + +빠진 것은 테스트가 아니라 규칙이다. 빌드 끝 `APP_ENV` 확인(09-29 13-01), live probe의 배포물 식별 대조(13-01), 자리표시자 거절(13-02), SPA fallback(13-04)은 규칙이 없어 테스트도 없다. 빌드를 실제로 도는 테스트는 `build-environment-bundle.test.ts` 하나(2개, 3.97s)이고 local 프로필·SW `null`·셸 변수만 본다. + +**성능.** 실험 E-A(`d99301b`, production 프로필, 부하 평균 27.6 — 다른 에이전트 동시 실행 중). `build-frontend.ts` 전체 1.42초, 그중 앱 Vite 빌드 333 ms(2,122 모듈). SW `ACTIVE`면 두 번째 빌드 23 ms가 더해진다. `dist`는 33파일 782,239 B. **초기 JS 203,513 / 204,800 gzip B, 여유 1,287 B**(지난 라운드 1,319 B에서 32 B 줄었다, UI 감사 수정분). 초기 파일 13개 중 큰 것은 `design-system` 66,251, `render-boot-failure` 58,640(react-dom 포함), `boot` 36,937, `reference-feature-runtime-descriptor` 25,138. lazy 파일 14개, 가장 큰 것 8,371 B(예산 122,880). 기능 모양 하나가 약 +2,980 B라(`config/scale/feature-shape-growth.json`) 다음 기능 하나가 `check:bundle`(release 게이트 FE-GATE-012)을 넘는다. 이 예산은 release 단계에서만 막으므로 merge는 통과하고 tag를 찍을 때 처음 실패한다. 빌드 시간은 CD의 병목이 아니다. + +CI 비용: production 단계까지 27 job이 각각 캐시 없이 `pnpm install --frozen-lockfile`을 한다(node_modules 332 MB). merge FE-GATE-008·009와 release FE-GATE-026은 3엔진 브라우저를 `--with-deps`로 설치한다(로컬 캐시 1.9 GB). 단일 desktop runner에서 직렬로 돌면 설치 시간이 테스트 시간보다 클 수 있다(측정하지 않음). 계약이 단계 종류를 고정해(`ci-gates.ts:912-927`) 다운스트림이 캐시 단계를 넣을 수 없다(5.3절). + +**폴더 구조.** `scripts/` 최상위에 70개가 섞여 있다(`build`·`generate` 9개, `check`·`verify` 41개). 빌드 경로만 따라가려면 `build-frontend.ts` 주석(`:10-38`)이 유일한 지도다. 주석은 정확하지만 SW 두 번째 단계가 `public/`을 다시 복사한다는 사실은 없다(09-29 13-01). `config/hosting`·`config/runtime`·`config/security`는 책임과 위치가 맞다. `config/release/coherence-fixtures.json`은 `scripts/verify-release.ts`만 쓰는 자기 검사 fixture라 `config/`보다 `tests/fixtures/`가 더 찾기 쉽다(낮은 우선순위). 배포에 필요한 정보(헤더 JSON, 캐시 JSON, 운영 문서 2개, 런북)가 네 폴더에 흩어져 있다. desktop 서버를 설정하는 사람이 한 곳에서 시작할 문서가 없다(13-04 (3)). + +## 8. 미검증 목록 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 실제 Gitea runner에서 workflow 실행(merge·release·provider·promotion·production) | Actions 실행 이력 없음(U-1), 외부 요청 금지 | runner 1대, PR 1건, dispatch 1건 | +| `pull_request`에서 `gitea.sha`와 checkout HEAD가 같은지 | `ciCheckoutIdentityFailures`(`build-environment.ts:64-85`)가 다르면 모든 게이트를 실패시킨다. Gitea의 PR 이벤트 값은 확인하지 않았다 | runner에서 PR 1건 | +| 컨테이너 모드 act_runner 안에서 provider job | 실행하지 않음(13-03의 추론) | 컨테이너·호스트 모드 각 1회 | +| Gitea 템플릿 생성 동작(복사 항목, 변수 치환, Actions 기본 활성) | Gitea API·UI를 쓰지 않음 | 테스트 조직에서 템플릿으로 저장소 1개 생성 | +| Gitea `workflow_run` 트리거 지원 | 문서 확인 안 함 | Gitea 버전별 문서 | +| 실제 호스트(nginx·caddy) 헤더·fallback | 호스트 없음 | desktop 서버에 HTTPS로 배포 후 `HOSTING_BASE_URL` | +| `*.example.com` 하위 이름의 DNS 해석 | 외부 요청 금지 | `dig` | +| 브라우저 부팅(E-B의 SW `ACTIVE` 운영 빌드, E-C의 build id 불일치) | 브라우저를 띄우지 않음(산출물만 확인) | `vite preview` + Playwright 1회 | +| 레시피 번들 예산 여유(FOLLOW-UP P2) | 이번에 측정하지 않음 | `check:optional-recipes --require-dist` | +| CI 설치 시간 | runner 없음 | runner에서 job별 시간 | + +## 9. 28개 관점 판정표 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. **굵은 번호**는 이번 영역이 깊게 본 관점이다. + +| 번호 | 관점 | 판정 | 이유·근거 | +|---|---|---|---| +| 1 | 코드 성숙도 | > | `src/` 규칙은 각 영역. 빌드 스크립트는 짧고 단계 주석이 있다 | +| 2 | 구조적 성숙도 | > | 영역 12 | +| 3 | 변경 용이성 | P | 프로필 추가는 파일 하나와 `DEPLOYMENT_TARGETS`면 된다. 배포 job·env·캐시를 넣으려면 템플릿 소유 CI 계약을 고쳐야 한다(13-01, 5.3). 청크 설정 변경은 이름 계약에 걸린다(09-29 13-03) | +| 4 | 인지 부하 | P | 빌드 8단계가 한 주석에 있다. 운영 단계까지 가려면 job 9개, provider 전제, 변수 10개를 알아야 한다(13-03). SW 두 번째 단계의 `public/` 복사는 어디에도 없다 | +| 5 | 위험 가시성 | P | fixture 모드가 `UNVERIFIED`로 드러난다(변이 M5). FE-GATE-019 PASS가 무엇을 증명하는지는 드러나지 않는다(13-01) | +| 6 | 실패 성숙도 | O | 빌드 단계 비정상 종료 시 즉시 중단(`build-frontend.ts:43-52`). 승인 fail-closed. CI 필수 변수가 없으면 실행 전에 이유와 함께 실패(`run-ci-gate.ts:101-104`) | +| 7 | 운영 성숙도 | > | telemetry는 영역 03. 비상 스위치 절차 공백은 13-05 | +| 8 | 디버깅 가능성 | P | build id·release id가 설정·manifest·승인 기록에 남는다. SW 경로의 승인 거절은 원인을 가리키지 않는다(09-29 13-01). `VITE_BUILD_ID=""`이면 4단계는 `local-build`, 7단계는 스키마 오류로 갈린다(R-2, 코드 읽기·미실행) | +| 9 | 유지보수 성숙도 | P | CSP 4벌(09-29 13-04), 폐기 별칭(09-29 13-07), 빌드 입력 기본값 4곳(R-2) | +| 10 | 테스트 성숙도 | P | 영역 테스트 16파일 통과(E2), 변이 5/5 검출(E3). 운영 프로필·SW `ACTIVE`·`.env` 입력·배포물 대조·자리표시자·fallback은 테스트할 규칙이 없다 | +| 11 | 데이터 성숙도 | > | 브라우저 저장소 영역 | +| 12 | 동시성 성숙도 | > | 탭·저장소 영역 | +| 13 | 확장성 | > | 영역 11 | +| 14 | 성능 성숙도 | P | 실험 E-A: 초기 JS 203,513 / 204,800 gzip B, 여유 1,287 B(지난 라운드 1,319 B). 다음 기능 하나(≈ +2,980 B, `config/scale/feature-shape-growth.json`)가 예산을 넘는다. CI는 27 job이 캐시 없이 설치한다(7절) | +| **15** | 보안 성숙도 | P | 미선언 `VITE_*` 거절(`vite.config.ts:13-24`), 기본 CSP는 강하다. 자리표시자 telemetry endpoint가 운영 승인을 받는다(13-02). CSP 확장 검사 없음(09-29 13-04). `connect-src 'self' https:`는 문서화된 한계 | +| **16** | 의존성 성숙도 | P | lockfile 561행 모두 sha512, tarball·git 0개. 기준선 `lockfileSha256`이 현재 lockfile과 같다. workflow action 4개는 커밋 SHA 고정. SBOM의 `scheduler` 분류(09-29 13-05), 설치 정책 검사 없음(09-29 13-08), runner image digest는 자기 기재(13-03) | +| 17 | API / Contract 성숙도 | > | 설정 스키마 호환은 영역 07 | +| **18** | 배포 성숙도 | X | 빌드 → 승인까지는 동작한다(E3). 배포한 산출물이 검증한 후보인지 확인하지 않고, 배포 job을 넣을 자리가 없다(13-01). SPA fallback 미검사(13-04). SW `ACTIVE` 운영 릴리스가 막힌다(09-29 13-01). 하위 경로에서 FE-GATE-019가 PASS할 수 없다(09-29 13-06) | +| **19** | 설정 성숙도 | X | 스키마 한 벌·프로필 정본·공개 대상 규칙은 동작한다. SW `ACTIVE`가 로컬 설정을 싣고(09-29 13-01, E-B), `.env*` 입력이 갈리고(09-29 13-02, E-C), 자리표시자가 승인되고(13-02), 배포 후 변경을 검증할 수 없다(13-05) | +| 20 | 개발자 경험 | P | README 변수 표와 운영 빌드 예시가 있다. 예시가 자리표시자를 쓴다(13-02). build id 필수 조건 누락(09-29 13-09). 호스트 설정 예시 없음(13-04). provider 붙이는 비용이 크다(13-03) | +| 21 | Guardrail 성숙도 | P | 승인 fail-closed(변이 M1·M2), 미선언 `VITE_*` 거절, CI 계약 고정(E-G). 빌드 끝 `APP_ENV` 확인, 배포물 대조, 자리표시자, CSP 내용 검사가 없다 | +| 22 | 추상화 성숙도 | > | 영역 09·12 | +| 23 | 일관성 | P | 빌드 변수 출처가 `loadEnv`와 `process.env`로 갈린다(09-29 13-02). 기본값 계산이 `||`와 `??`로 갈린다(R-2). 문서는 "배포 뒤 검사"라 하고 workflow는 "승격 직후 검사"다(13-01) | +| 24 | 네이밍 / 의미 성숙도 | P | `build:app-only`가 프로필을 건너뛴다는 사실을 드러내지 않는다. "runtime config"는 빌드 때 확정되는데 `.env.example`은 재빌드 없이 바꿀 수 있다고 적는다(13-05) | +| 25 | 조직 확장성 | - | 1인 관리 전제 | +| **26** | Ownership 성숙도 | P | 템플릿 결함 분류 규칙이 선택 기능을 다루지 않는다(09-29 13-10). 배포 job과 provider는 "프로젝트 몫"인데 그 자리를 템플릿 계약이 막는다(13-01, 13-03). 의존성 기준선 승인은 env 자기 기재다(`update-dependency-baseline.ts:6-13`) | +| 27 | 삭제 가능성 | > | 영역 14(FE-GATE-020) | +| 28 | 회복 가능성 | P | 보관 release 재검증 모드와 drill `--release-root`가 있다. 비상 스위치 절차가 없다(13-05). 이전 자산 보존·원자적 전환은 문서뿐이다(3절) | diff --git a/docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md b/docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md new file mode 100644 index 00000000..d434e4cb --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md @@ -0,0 +1,455 @@ +# 14 — 템플릿 제품성·문서·DX·업데이트 전파 + +> 검토일: 2026-11-01 · 기준: `fix/ui-design-audit-2026-11-01` / `d99301b` (`v0.2.0` 뒤 12커밋) · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 영역 판정(35.8): **조건부 사용 가능.** 지난 라운드와 같다. 복사해서 시작하고 Git으로 수정을 받는 용도는 동작한다. 샘플 제거 드릴도 이 커밋에서 통과했다(E2). 다만 지난 발견 6건이 모두 남았다. 새로 본 것은 두 가지다. 하나는 결정 근거가 지워도 되는 이력 문서에만 있다는 점이다(14-01). 다른 하나는 입구 문서가 지금 폴더 구조와 다르다는 점이다(14-03). 둘 다 사용자가 만들 `docs/manual/`의 출발점에 직접 걸린다. +> +> ID 표기: 이 문서의 새 발견은 `14-01`부터 쓴다. 지난 라운드(2026-09-29) 발견은 `0929/14-01`처럼 앞에 라운드를 붙인다. 라운드마다 같은 ID를 다시 쓰는 문제는 14-02에서 다룬다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `d99301b`. 미커밋 변경은 `.claude/`와 이 리뷰 폴더뿐이다 | +| 목적·실행 구성 | 복사해서 시작하고 Git으로 원본 수정을 받아 가는 프론트엔드 템플릿. 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 지난 리뷰 뒤 바뀐 것 | `af3d8e6..d99301b` 11커밋(태그 기준 12). `README.md`·`CHANGELOG.md`·`docs/`(리뷰 제외)는 바뀌지 않았다. 추가: `PRODUCT.md`, UI 감사 수정 UI-01~08(`scripts/check-design-system.ts` +84줄, 토큰·스타일, 시각 골든 4개), 리뷰 문서들 | +| 읽은 것 | `README.md`·`CHANGELOG.md`·`PRODUCT.md` 전체. `docs/README.md`, `starter-experience.md`, `layers.md`, `overview.md`, `capability-consumer-experience.md`, `static-delivery.md`, `taxonomy.md`, `design-tokens.md`, runbook 5개 전체. `frontend-application-foundation.md`·`contract-ownership.md`·`compatibility.md`·`ci-quality-gates.md` 앞부분. 목표 설계 문서와 VD 23개는 머리말·상태 줄과 경로만. `scripts/verify-documentation-readiness.ts`, `scripts/test-sample-removal.ts` 1~150·405~432행, `tests/unit/deletable-history-documents.test.ts`, `.dependency-cruiser.json` 규칙 이름, `.gitignore`, `config/ci/gates.json` stage 표 | +| 실행한 것 | ① `corepack pnpm test:sample-removal`(메인 repo, `flock`) → PASS. ② scratchpad worktree에서 README가 지워도 된다고 한 이력 파일 89개를 지우고 `verify:documentation`·`check:adapter-inventory`·지울 수 있는 기록 검사 실행 → 모두 PASS. 남은 문서의 끊긴 링크를 셌다. ③ 지울 수 있는 기록 검사에 대한 변이 3개. ④ `verify:documentation`에 대한 변이 2개. ⑤ 두 제품(`../tech-log-frontend`, `../memento-frontend`)을 scratchpad에 로컬 clone하고 `git merge-tree`로 `af3d8e6 → d99301b` 다음 동기화를 재현. 병합 트리에서 `check-design-system.ts`를 실행. 제품 repo 자체는 읽기만 했다. ⑥ 문서 경로·스크립트·게이트 ID 존재 검사 스크립트(scratchpad), 문서 간 같은 줄 비교, `git grep` 집계. worktree와 clone은 모두 지웠다 | +| 게이트 결과(오케스트레이터) | `verify:documentation` PASS_SCOPED, `check:adapter-inventory` PASS, `check:ci` PASS(27 gates), `check:design-system` PASS. `test:system` rc=1(11·12 영역) | +| 확인하지 못한 것 | 깨끗한 환경의 `install --frozen-lockfile` → `dev`. 나머지 제거 드릴 3개(`test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal`). Gitea 이슈 목록(외부 요청 금지). 목표 설계 문서 본문의 세부 주장(약 3.4만 줄) | +| 이전 리뷰와 비교 | 문서·README·CHANGELOG가 그대로라 지난 발견은 같은 줄에서 다시 확인했다. 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견 재확인 + +| ID | 상태 | 근거 (현재 커밋) | +|---|---|---| +| 0929/14-01 실행 로그·작업 기록이 복사 대상에 섞임 | 남음 | 추적 중인 `.log` 63개(`git ls-files artifacts`), `artifacts/tests/coverage-gateway/` 10개, `artifacts/local-preview/` 3개. `.gitignore:11-14`는 `.log`를 무시하지 않는다. `README.md:309-310`과 `docs/testing/taxonomy.md:109-110`은 "디렉터리 구조만 추적한다"고 적는다. 쓰는 곳 `scripts/scale/run-scale-profile.ts:153`, `scripts/verify-extreme-scale.ts:228`. `SPEC.md`·`tasks/`는 루트에 있고 `docs/README.md:72`의 사유("이 라운드가 쓰는 중")도 그대로다. 이번에 `check:scale:pr`는 다시 돌리지 않았다(E1) | +| 0929/14-02 README 업데이트 절차가 범위 반영을 다루지 않음 | 남음 | `README.md:315-353`이 그대로다. cherry-pick 1건 절차만 있다. 두 제품의 기준점 형식도 여전히 다르다(`memento-frontend/.template-origin` 한 줄, `tech-log-frontend/template.lock.json` JSON) | +| 0929/14-03 제품이 고치는 템플릿 파일 목록이 없어 같은 파일이 충돌 | 남음 | README·`starter-experience.md`에 표가 없다. **다음 동기화 재현(E3):** tech-log 10경로 충돌(modify/delete 10개. 그중 9개는 제품이 지운 예시 화면 4개·`tests/e2e/i18n.spec.ts`·골든 PNG 4개). memento 4경로 충돌(`src/presentation/design-system/tokens/semantic.css` 내용 충돌 + 골든 PNG 3개). 템플릿 변경은 40파일뿐인데, 제품이 브랜드를 입히는 토큰 파일과 제품이 지운 샘플에서 또 충돌한다 | +| 0929/14-04 CHANGELOG [계약]이 게이트를 좁힌 변경을 빠뜨림 | 남음·재발 | `CHANGELOG.md`에 `v0.2.0` 뒤 절(Unreleased)이 없다(`:13`이 첫 절). 그런데 그 뒤 FE-GATE-010(merge)이 돌리는 `check:design-system`에 규칙 4개가 들어왔다: oklab 외 `color-mix` 금지(`scripts/check-design-system.ts:54-59`), 포커스 링 대비 3:1(`:87-126`), 읽히지 않는 component 토큰 금지(`:128-136`), `--font-sans` 첫 글꼴 제한(`:138-162`). **재현(E3):** memento 병합 트리에서 새 UI-03 규칙이 제품 소유 토큰 8개(`--memento-dialog-background` 등)를 실패로 잡는다. tech-log 병합 트리는 PASS | +| 0929/14-05 `FEATURE_OVERRIDES` 남은 키를 "조용히 무시"로 적음 | 남음 | `docs/operations/ci-quality-gates.md:69` 그대로 | +| 0929/14-06 제품이 찾은 템플릿 결함 후보가 돌아오지 않음 | 남음(repo 기준) | repo에서 두 제품을 언급하는 곳은 여전히 `docs/superpowers/specs/2026-09-20-memento-…` 하나다. 이슈 트래커는 외부 요청 금지라 보지 않았다 | +| FOLLOW-UP(09-25) 09-07 기능 제거 검사가 lint·`check:i18n`·e2e를 건너뜀 | 남음 | 검사 목록 `scripts/test-sample-removal.ts:413-429`. 이번에 들어온 `check:design-system` 새 규칙도 제거 검사 밖이다 | +| FOLLOW-UP(09-25) 14-07 `verify:documentation` 범위가 좁음 | 남음 → 14-05로 승격 | 변이로 확인했다. 현재 계약 문서의 drift 6건을 새로 찾았다 | + +## 3. 실험과 측정 + +### 3.1 샘플 제거 드릴 + +| 항목 | 값 | +|---|---| +| 명령 | `flock /heavy.lock /usr/bin/time -v corepack pnpm test:sample-removal` (메인 repo) | +| 결과 | `reference-feature removal: PASS (13 checks, no fixture IDs)` | +| 시간 | wall 2:11.75, user 582.7s, sys 86.6s. 잠금 획득 시 load average 10.26(22코어) | +| 메모리 | 최대 RSS 1,186,032 KB | +| 정리 | 끝난 뒤 `.tmp/`가 비어 있고 `git status`에 변화가 없다 | +| 검사하지 않는 것 | lint, `check:i18n`, `check:design-system`, e2e, visual(`scripts/test-sample-removal.ts:413-429`) | + +### 3.2 이력 문서를 지웠을 때 (README "Files you can delete after copying" 그대로) + +worktree에서 `docs/superpowers/`, `docs/reviews/`(`adapters/INVENTORY.md`만 남김), `SPEC.md`, `tasks/`, `CLAUDE.md` 89파일을 지웠다. + +| 확인 | 결과 | +|---|---| +| `verify:documentation` | PASS_SCOPED | +| `check:adapter-inventory` | PASS | +| `tests/unit/deletable-history-documents.test.ts` | PASS | +| 남은 문서의 끊긴 링크 | `docs/reviews/adapters/INVENTORY.md` 145개(행마다 지운 리뷰 문서로 링크), `docs/operations/adapter-remediation-ledger.md` 7개, `CHANGELOG.md:15` 1개, `PRODUCT.md:56`(`SPEC.md` U-2) 1개 | +| 남은 코드의 끊긴 참조 | `Spec §N` 주석 68곳(57파일). 가리키는 문서 `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md`가 지워졌다(14-01) | + +게이트에 대한 README의 약속은 지켜진다. 그러나 사람이 읽는 근거는 끊긴다. + +### 3.3 변이 실험 + +| 대상 | 변이 | 결과 | 뜻 | +|---|---|---|---| +| 지울 수 있는 기록 검사 | `src/platform/errors/app-error.ts`에 `// see docs/superpowers/specs/x.md` 추가 | FAIL | 경로 참조는 잡는다 | +| 같은 검사 | `// Spec §4. budgets live here` 추가 | PASS | 이름 없는 설계서 참조는 못 잡는다 | +| 같은 검사 | `// review 12-07: see the review` 추가 | PASS | 리뷰 ID 참조는 못 잡는다 | +| `verify:documentation` | README 라우트 표에서 `/examples/ui`, `/examples/states` 행 삭제 | PASS | 라우트 표 drift는 못 잡는다 | +| 같은 검사 | README의 수동 접근성 문단에서 `EXAMPLES_PLATFORM` 삭제 | FAIL. 메시지는 "canonical scoped-review evidence is incomplete" | route ID는 잡지만 원인을 말하지 않는다(14-06) | + +### 3.4 다음 동기화 재현 (`af3d8e6 → d99301b`, 12커밋 40파일) + +| 측정 | tech-log | memento | +|---|---|---| +| 방식 | `git merge-tree --write-tree --merge-base=af3d8e6 --name-only <제품 sync 브랜치> d99301b` | `git merge-tree --write-tree --name-only <제품 sync 브랜치> d99301b` | +| 충돌 경로 | 10 (모두 modify/delete) | 4 (내용 충돌 1 + 바이너리 3) | +| 충돌 원인 | 제품이 지운 예시 화면 4개, `tests/e2e/i18n.spec.ts`, 골든 PNG 4개, 리뷰 가이드 1개 | 브랜드 토큰 파일 `semantic.css`, 골든 PNG 3개 | +| 새로 들어오는 템플릿 전용 파일 | `PRODUCT.md`, `docs/reviews/` 18파일 | `PRODUCT.md`, `docs/reviews/` 18파일 | +| 병합 트리의 `check:design-system` | PASS | FAIL — 제품 소유 component 토큰 8개가 새 UI-03 규칙에 걸림(`semantic.css`는 제품 쪽으로 풀고 실행) | + +### 3.5 문서 규모 (30.6) + +| 묶음 | 파일 | 줄 | +|---|---:|---:| +| `docs/**/*.md` 전체 | 151 | 75,450 | +| `docs/reviews/` | 55 | 23,981 | +| `docs/superpowers/` | 27 | 10,958 | +| `docs/architecture/` (VD 제외) | 24 | 22,681 | +| `docs/architecture/decisions/` (VD) | 23 | 11,656 | +| `operations` 8 / `testing` 2 / `styling` 2 / `security` 2 / `contracts` 1 / `runbooks` 5 / `accessibility` 1 | 21 | 6,102 | +| `README.md` + `CHANGELOG.md` + `PRODUCT.md` | 3 | 497 | + +`docs/README.md:19-28`의 입구 문서 6묶음은 README 포함 약 1,900줄이다. 가장 큰 문서는 정본이라고 표시된 `2026-07-30-…-closed-deep-design.md` 5,960줄이다. 문서 사이에 그대로 겹치는 줄은 적다(문서 쌍 최대 9줄, 50자 이상 줄 기준). 중복은 복사가 아니라 같은 주제를 다른 말로 다시 설명하는 형태다(7.5절). + +## 4. 새 발견 (36.3) + +### 14-01 코드와 현재 문서가 결정 근거를 "지워도 되는" 이력 문서로만 가리킨다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 9, 4, 26, 27, 21, 24, 30.3 | +| 근거 | ① **이름 없는 설계서 참조.** `src`·`scripts`·`config`·`tests`·`.dependency-cruiser.json`의 57파일에 `Spec §N` 주석이 68개 있다(`git grep -c 'Spec §'`). 많은 곳: `scripts/scale` 10, `src/platform/telemetry` 9, `src/platform/errors` 5, `src/adapters/http` 5. 예: `.dependency-cruiser.json:327` "Spec §4. src/platform holds product-neutral primitives…". 어느 주석도 문서 이름을 적지 않는다. 절 번호(§3~§55)가 맞는 문서는 `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md`(1,294줄) 하나다. 이 문서는 `README.md:201`이 복사 뒤 지워도 된다고 한 `docs/reviews/` 안에 있다. ② **현재 구조의 설계가 그 문서에만 있다.** `src/platform`(9폴더 30파일), `src/apps`, `src/contexts`는 `6f6c48e`(2026-09-24)에 들어왔다. 그 목표 구조·소유·의존 규칙·예산은 위 문서 §4~§8에 있다. 현재 계약 문서 중 `src/platform`을 다루는 곳은 없다(14-03). ③ **현재 문서도 이력 문서에 링크한다.** `docs/reviews/adapters/INVENTORY.md`(게이트가 읽는 파일) 145행이 모두 `./0N-*.md`로 링크한다. `docs/operations/adapter-remediation-ledger.md` 7곳, `CHANGELOG.md:15`, `PRODUCT.md:56`도 지워도 되는 파일을 가리킨다. ④ **검사가 막지 못한다.** `tests/unit/deletable-history-documents.test.ts:22-31`은 경로 문자열만 찾는다. 변이 실험에서 `Spec §4.` 주석은 통과했다(3.3절). ⑤ **실험(E3):** 이력 89파일을 지운 worktree에서 게이트는 모두 PASS였고, 위 참조는 모두 끊겼다(3.2절) | +| 발생 조건 | 복사한 프로젝트가 README대로 이력을 지울 때. 템플릿 안에서도 주석을 읽는 사람이 어느 "Spec"인지 모를 때 | +| 영향 | 제품 개발자가 `src/platform`의 예산·실행·텔레메트리 규칙을 바꾸려 할 때 이유를 찾을 곳이 없다. 같은 이유로 `docs/manual/`을 쓸 때 "기능을 어느 context·app에 둘까" 판단의 근거 문서가 현재 계약에 없다. 두 제품은 `docs/reviews`를 각각 다르게 처리했다(tech-log 제외, memento 유지 — 0929/14-01). 제외한 쪽에서는 이미 끊겨 있다. 데이터·보안 피해는 없다 | +| 심각도·우선순위 | Medium · P2 — 모든 복사본과 모든 유지보수자에게 반복되는 이해 비용이다. 게이트는 영향받지 않는다 | +| 통제·증거 | 목표 M3(참조 대상이 현재 문서이고, 이력 참조를 검사가 잡음). 확인: 경로 참조는 M3, `Spec §`·리뷰 ID·문서 링크는 M0 · E3(삭제 실험, 변이 3개) | +| 확실성과 남은 가정 | 68개 주석이 모두 같은 문서를 뜻한다는 것은 추론이다. 근거: 다른 "Spec"은 repo에 없고, 주석의 절 주제(§24 telemetry ownership, §45 release coherence 등)가 그 문서 목차와 맞는다 | +| 결정의 근거 | 확인된 사실: 설계서는 리뷰 묶음(`…-plan-bundle`) 안에 들어온 채 승격되지 않았다. 기록된 의도: `docs/README.md:3-9`는 "작업 이력은 지워도 된다"를 정책으로 둔다. 리뷰어의 추론: 설계서를 리뷰와 같이 받아 둔 위치가 그대로 굳었다. 선택 비교는 5.1절 | +| 이해 비용 | 주석 하나를 따라가려면 repo 전체에서 "§4"가 있는 문서를 찾아야 한다. 이력을 지운 복사본에서는 찾을 수 없다 | +| 최소 개선 방향 | ① 설계서에서 지금도 맞는 절(§3~§8 구조·소유·의존·예산, §10~§16 실행·트래픽, §17~§31 오류·검증·텔레메트리)을 `docs/architecture/`의 현재 계약 문서로 옮긴다. 절 번호는 유지하거나 번호 대응표를 둔다. ② 주석을 `Spec §4` → `topology.md §4`처럼 문서 이름을 붙인 형태로 바꾼다. ③ `INVENTORY.md`의 145개 링크는 리뷰 문서 대신 adapter 그룹 이름으로 바꾸거나, "지우면 끊긴다"를 README 목록에 적는다. ④ 지울 수 있는 기록 검사에 `Spec §` 패턴을 추가해, 이름 없는 참조가 다시 생기면 실패하게 한다 | +| 대안 비교 | 5.1절: (a) 현 상태 (b) 근거 승격 + 참조에 이름 + 검사 확장 (c) "이력을 지우지 말라"로 정책 변경 (d) 이력을 별도 저장소로. (b) 권장 | +| 단순화의 보존 조건 | 주석의 설명 문장은 지우지 않는다. 절 번호가 바뀌면 68곳을 함께 고친다. `check:adapter-inventory`가 읽는 `INVENTORY.md`의 행 구조는 바꾸지 않는다 | +| 비용·부작용 | 문서 1~2개 이동, 주석 68곳 치환(기계적), 검사 정규식 1개 | +| 재검토 조건 | 템플릿을 패키지·생성기로 배포하게 되면 복사 대상이 바뀌므로 다시 본다 | +| 완료 기준 | `git grep 'Spec §'`의 모든 결과가 문서 이름을 포함한다. 그 문서는 `docs/README.md` §1(현재 계약)에 있다. README 목록대로 이력을 지운 뒤 남은 문서·코드의 끊긴 참조가 0이다 | +| 검증 방법 | 3.2절 삭제 실험을 다시 돌려 끊긴 링크·참조를 센다. 확장한 지울 수 있는 기록 검사에 `// Spec §4.` 변이를 넣어 실패를 확인한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 14-02 리뷰 발견 ID가 라운드마다 같은 형식이라, CHANGELOG와 코드 주석의 ID가 어느 리뷰인지 알 수 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 24, 9, 17, 26 | +| 근거 | `CHANGELOG.md:10` "괄호 안 ID는 리뷰 발견 ID다. 근거와 재현 조건은 해당 리뷰 문서에 있다". `CHANGELOG.md:36`의 `(14-02)`는 2026-09-25 라운드의 "CI 계약 고정"이다(`docs/reviews/2026-09-25-maturity-review/README.md:266`). 2026-09-29 라운드의 14-02는 "README 업데이트 절차"다(`docs/reviews/2026-09-29-maturity-review/README.md:340`). 이번 라운드도 14-02를 쓴다. 코드 주석의 리뷰 ID 참조는 약 339곳·164파일이다(`NN-MM` 형식 정규식 집계, 근사값). 예: `src/adapters/browser-file-storage/result.ts:111` "05-11.". 라운드 날짜나 폴더를 함께 적은 주석은 찾지 못했다(`git grep maturity-review -- src scripts config tests` 0건) | +| 발생 조건 | CHANGELOG나 주석의 ID로 근거를 찾을 때. 라운드가 늘수록 같은 ID가 더 많아진다 | +| 영향 | 동기화 담당자가 CHANGELOG ID를 따라가다 다른 라운드의 다른 결함을 읽을 수 있다. 대부분의 주석은 ID 뒤에 이유를 직접 적어서(가이드 9절이 허용하는 형태) 피해는 작다 | +| 심각도·우선순위 | Low · P3 — 주석은 대체로 자기 설명을 갖고 있다. CHANGELOG는 ID가 유일한 근거 링크라 영향이 더 크다 | +| 통제·증거 | M0(ID 네임스페이스 규칙 없음) · E1 | +| 확실성과 남은 가정 | 339는 정규식 근사값이다. 일부는 리뷰 ID가 아닌 숫자일 수 있다 | +| 결정의 근거 | 적용 제외 — ID에 라운드를 붙이는 표기 규칙의 문제라 선택 비교가 필요하지 않다 | +| 이해 비용 | ID 하나마다 라운드 폴더 3개를 열어 대조해야 한다 | +| 최소 개선 방향 | ① CHANGELOG 표에 라운드 열을 두거나 ID를 `0925/14-02`처럼 적는다. ② 리뷰 가이드 36.3절 ID 규칙에 "라운드 접두어"를 더한다. ③ 기존 주석은 고치지 않는다. 새 주석부터 라운드를 붙인다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | CHANGELOG 표 한 열. 기존 주석은 그대로라 혼재 기간이 생긴다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | CHANGELOG의 모든 ID가 라운드를 함께 적는다. 다음 리뷰 라운드의 ID가 이전 라운드와 겹치지 않는다 | +| 검증 방법 | `grep -oE '\(([0-9]{2}-[0-9]{2})' CHANGELOG.md`가 라운드 없는 ID를 찾지 않는다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 14-03 입구 문서가 실제 폴더 9개 중 3개를 설명하지 않고, 없는 `src/domain`을 계층으로 보여 준다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 4, 9, 20, 24, 2 | +| 근거 | `src/` 최상위는 `adapters application apps bootstrap contexts contracts features platform presentation` 9개다. `src/domain`은 없다. **설명 누락:** `docs/architecture/layers.md:7-14` 표, `docs/architecture/frontend-application-foundation.md:17-31` 목록, `docs/architecture/overview.md:8-19` 그림, `README.md:140-147` 그림 어디에도 `src/platform`이 없다(4문서 모두 0회). `apps`·`contexts`는 `layers.md:28-36`의 금지 간선 설명에만 나온다. `docs/architecture/contract-ownership.md:17-24`의 배치 규칙은 "feature / adapter / `src/contracts`" 셋뿐이다. `src/platform`("product-neutral primitives", `.dependency-cruiser.json:327`)이라는 네 번째 자리가 없다. **없는 계층:** `layers.md:3,9`, `overview.md:15`, `README.md:143`이 `domain`을 최상위 계층처럼 그린다. 실제 domain은 기능 안(`src/features/reference-feature/domain`)에만 있다. 규칙 `domain-is-framework-neutral`(`.dependency-cruiser.json:4-8`)은 없는 `^src/domain`을 대상으로 한다. **틀린 보증:** `layers.md:51-52`는 "this table and the executable rules cannot drift apart"라고 적는다. 그러나 규칙 30개 중 `features-do-not-import-other-features`(`:266`), `contexts-do-not-import-other-contexts`(`:278`), `platform-kernel-is-product-neutral`(`:326`), `zod-is-reached-through-contracts-zod`, `presentation-does-not-fetch-directly`, `observability-vendors-live-behind-adapters` 등 13개는 `layers.md`에 설명이 없다(키워드 검색 0회). 검사는 "적힌 규칙이 강제되는가"만 보장하고 "규칙이 다 적혔는가"는 보장하지 않는다 | +| 발생 조건 | 새 개발자가 입구 문서를 보고 코드 위치를 정할 때. `docs/manual/`이 이 문서들을 근거로 "어디에 둘까" 판단 지점을 만들 때 | +| 영향 | 금지된 간선은 `check:architecture`가 막는다. 막지 못하는 것은 "허용되지만 틀린 자리"다. 예: 제품 중립 primitive를 `src/contracts`에 둔다. 최상위 `src/domain`을 새로 만든다(규칙은 있어서 통과한다). 기능 간 공유가 막힌 이유를 문서에서 찾지 못한다. 매뉴얼이 이 문서를 그대로 링크하면 틀린 판단 기준이 복제된다 | +| 심각도·우선순위 | Medium · P2 — 모든 기능 추가의 첫 판단에 걸린다. 매뉴얼 작성 전에 고쳐야 효과가 있다. 게이트가 금지 간선은 잡으므로 High는 아니다 | +| 통제·증거 | 목표 M3(입구 문서의 폴더·규칙 목록이 실제와 다르면 실패). 확인: 규칙 강제는 M4, 문서와 규칙의 일치는 M1(주장만) · E1 | +| 확실성과 남은 가정 | 13개 누락은 규칙 이름과 키워드 검색으로 셌다. 일부 규칙은 다른 말로 간접 설명됐을 수 있다 | +| 결정의 근거 | 적용 제외에 가깝다. 문서를 코드에 맞추는 일이다. 다만 `src/domain` 규칙을 확장 슬롯으로 둘지(빈 레지스트리처럼) 지울지는 09·12 영역의 선택이다. 이 문서는 "최상위 domain은 지금 없고, 둔다면 규칙이 이미 있다"를 적으면 된다 | +| 이해 비용 | 새 개발자는 9개 폴더의 역할을 `.dependency-cruiser.json` 주석과 `starter-experience.md:86-110`, 그리고 이력 설계서(14-01)를 모아 읽어야 안다 | +| 최소 개선 방향 | ① `layers.md` 표를 실제 9개 폴더로 바꾸고 `domain`은 "기능 안의 계층"으로 옮긴다. ② 표에 "규칙 이름" 열을 두어 `.dependency-cruiser.json`의 `name`과 1:1로 잇는다. ③ `contract-ownership.md` 배치 규칙에 `src/platform` 선택지를 넣는다. ④ `overview.md`·`README.md:140-147` 그림을 같은 표에서 다시 그린다. ⑤ `layers.md:51-52`의 보증 문장은 ②를 검사로 만들 때까지 "적힌 규칙은 강제된다"로 줄인다 | +| 대안 비교 | (A) 문서만 고친다: 싸다. 다시 어긋날 수 있다. (B) (A) + `verify:documentation`이 규칙 이름 목록과 `layers.md` 열을 대조: 규칙 추가 때 문서도 강제된다. 검사 수십 줄. (C) `layers.md`를 `.dependency-cruiser.json`에서 생성: 사람이 읽는 설명을 넣기 어렵다. (B) 권장 | +| 단순화의 보존 조건 | `layers.md`의 kernel 예외 절(`:38-65`)과 배럴 절(`:67-100`)은 이 repo의 전제(CLAUDE.md)와 같으므로 유지한다 | +| 비용·부작용 | 문서 4개 수정. (B)는 검사 하나 추가 | +| 재검토 조건 | 최상위 폴더가 추가·삭제될 때. `src/domain`을 실제로 만들 때 | +| 완료 기준 | 입구 문서 4개가 같은 9개 폴더 목록을 쓴다. `layers.md`가 모든 error 규칙 이름을 포함한다. `contract-ownership.md`에 `src/platform` 판단이 있다 | +| 검증 방법 | 규칙 이름을 하나 바꾸는 변이에서 `verify:documentation`이 실패하는지 본다((B)일 때). (A)만이면 문서 대조 | +| 담당·기한·상태 | 미정 · 미정 · 신규. 기능 추가 절차 자체는 16 영역 | + +### 14-04 `PRODUCT.md`가 예제 화면을 지울 수 있다고 적지만, 드릴은 reference feature만 지운다. 복사 처리 목록에도 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 30.3, 30.5, 27, 9, 24 | +| 근거 | `PRODUCT.md:33` "예제 기능과 라우트는 지울 수 있게 만들어져 있습니다(`test:sample-removal`). 예제 화면에만 있는 디자인은 파생 서비스에 남지 않습니다." 그러나 `scripts/test-sample-removal.ts:29-35`는 "Removes one installed feature"이고 기본값은 `reference-feature`다. 예제 라우트 `/`, `/examples/platform|ui|states|auth`는 플랫폼 라우트다(`src/contracts/routes.ts:20-80`). 화면은 `src/presentation/examples/` 4개와 홈이다. 어느 제거 드릴도 이들을 지우지 않는다(`git grep presentation/examples -- scripts/test-*removal*.ts` 0건). `README.md:101`도 예제 라우트를 Default 계층으로 둔다. **복사 처리:** `PRODUCT.md`는 템플릿 자신을 제품으로 설명한다(사용자 = "템플릿을 가져다 쓰는 개발자", 표시 이름 "Frontend Skeleton"). 그런데 `README.md:192-203` 목록에 없다. `PRODUCT.md:56`은 지워도 되는 `SPEC.md`(U-2)를 근거로 든다. **재현(E3):** 다음 동기화 병합 트리에서 두 제품 모두 `PRODUCT.md`를 새 파일로 받는다(3.4절) | +| 발생 조건 | 디자인 작업자(사람이나 도구)가 `PRODUCT.md`를 전제로 예제 화면에 디자인을 넣을 때. 제품이 템플릿을 동기화할 때 | +| 영향 | "예제 화면은 남지 않는다"를 믿고 예제 화면에만 패턴을 넣으면, 그 화면과 스타일이 제품 빌드에 남는다. 지우려면 제품이 템플릿 소유 파일을 고쳐야 하고, 그 결과는 다음 동기화의 충돌이다(tech-log가 예시 화면을 지워 이번 재현에서 9개 충돌, 3.4절). 제품 루트에 템플릿 설명 파일이 들어오면, 그 파일을 읽는 디자인 도구가 틀린 사용자·브랜드 전제로 일한다 | +| 심각도·우선순위 | Low · P3 — 문서 한 파일의 주장 오류다. 빌드·게이트 영향은 없다 | +| 통제·증거 | M1(틀린 주장) · E3(드릴 범위 확인, merge-tree 재현) | +| 확실성과 남은 가정 | `PRODUCT.md`를 실제로 읽는 도구가 무엇인지는 파일 머리의 `impeccable:product-schema` 표식으로 추정했다 | +| 결정의 근거 | 적용 제외 — 문서를 코드에 맞추고 목록에 한 줄을 넣는 일이다. 예제 화면을 지울 수 있게 만들지는 별도 선택이다(0929/14-03, 09 영역) | +| 이해 비용 | 작다. 다만 틀린 전제는 디자인 결정에 조용히 섞인다 | +| 최소 개선 방향 | ① `PRODUCT.md:33`을 "reference feature는 `test:sample-removal`로 지울 수 있다. 예제 라우트 4개와 홈은 Default 구성이며 제거 드릴이 없다"로 고친다. ② README 목록에 `PRODUCT.md`를 "템플릿 설명. 복사 뒤 제품 것으로 바꾼다"로 넣는다(`CLAUDE.md`와 같은 처리). ③ `PRODUCT.md:56`의 근거를 `SPEC.md` 대신 `docs/accessibility/manual-checklist.md`로 바꾼다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 두 곳 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `PRODUCT.md`의 제거 주장이 드릴 범위와 같다. README 목록에 `PRODUCT.md`가 있다. `PRODUCT.md`가 지워도 되는 파일을 근거로 들지 않는다 | +| 검증 방법 | 문서 대조. 14-01의 삭제 실험에서 `PRODUCT.md`의 끊긴 참조가 0인지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 14-05 현재 계약 문서의 drift를 잡는 검사가 3가지뿐이고, 그중 하나는 repo 밖 7월 diagram의 사본끼리만 대조한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 9, 21, 5, 20, 19 | +| 근거 | **검사 범위.** `scripts/verify-documentation-readiness.ts`는 ① diagram 리뷰 ledger와 `review-evidence.md`가 같은 해시·점수를 담는지(`:44-79`), ② README·수동 체크리스트가 route ID를 모두 적는지(`:18-21`, `:80-97`), ③ README가 빌드 변수를 모두 적는지(`:103-117`)만 본다. ①은 손으로 쓴 두 파일의 일치다. 원본 diagram과 리뷰 보고서는 repo에 없다(`review-ledger.json`의 `note`가 "deliberately not resolvable"이라고 적는다). diagram 날짜는 2026-07-18로, `src/apps`·`contexts`·`platform`이 들어온 `6f6c48e`(2026-09-24)보다 앞이다. 그래서 `DOCUMENTATION_READY`는 구조가 바뀌어도 계속 PASS다. **변이(E3):** README 라우트 표에서 행 2개를 지워도 PASS였다(3.3절). **이미 생긴 drift(이 리뷰에서 찾은 것):** (가) `README.md:79-85` 라우트 표에 `/examples/platform`(2026-08-01 추가, `src/contracts/routes.ts:33-35`)이 없다. `README.md:75-77`은 언어 선택기를 적지 않는다(`src/presentation/layouts/app-shell.tsx`). (나) `docs/styling/design-tokens.md:3`은 `src/presentation/styles/theme.css`를 "styling SSOT"라고 한다. 실제 토큰은 `src/presentation/design-system/tokens/{primitive,semantic,component}.css` 3계층이고 `theme.css`는 import 진입점이다. 같은 문서는 이번 커밋의 `check:design-system` 규칙 4개(oklab, 포커스 대비, 읽히지 않는 토큰, 글꼴)를 모른다. 제품이 토큰으로 브랜드를 바꿀 때 지켜야 할 조건인데, 적힌 곳은 스크립트 주석뿐이다. (다) `docs/contracts/compatibility.md:23,26`의 줄 번호가 어긋났다. `release-artifacts.ts:163-171`은 V1 스키마 끝이고 `"2.0"`은 `:173`에 있다. `:200-208`은 V1 매니페스트이고 V2는 `:214`다(문서 2026-09-26, 코드 2026-09-27 변경). (라) `docs/operations/adapter-remediation-ledger.md:47,211,339,359,383,468`이 옮겨진 `tests/unit/ci-artifact-contract.test.ts`(지금 `tests/system/ci-runner/`)를 설명 없이 가리킨다. (마) `CHANGELOG.md:11`은 커밋 해시가 `main`에서 다를 수 있다고 하지만, 표의 55개 해시는 모두 `HEAD`에서 닿는다. (바) 0929/14-01의 `taxonomy.md:109-110`, 0929/14-05의 `ci-quality-gates.md:69`, 14-03의 `layers.md`도 같은 원인이다 | +| 발생 조건 | 코드를 바꾸고 현재 계약 문서를 고치지 않을 때. 검사가 없으니 누구도 실패를 보지 못한다 | +| 영향 | `docs/README.md:6`은 현재 계약을 "게이트가 검사한다"고 소개한다. 실제로는 세 항목만 검사한다. 사용자가 만들 매뉴얼이 이 문서들을 링크하면 drift가 매뉴얼로 복제된다. `DOCUMENTATION_READY`라는 이름이 문서 전체가 준비됐다는 신호로 읽힌다 | +| 심각도·우선순위 | Medium · P2 — 하나하나는 Low다. 그러나 현재 계약 문서에서 이미 6건이 쌓였고, 매뉴얼 작성이 이 문서들을 입구로 삼는다 | +| 통제·증거 | 목표 M3(현재 계약 문서의 경로·스크립트·게이트 ID·폴더 목록이 실제와 다르면 실패). 확인: route ID·빌드 변수는 M3, 나머지는 M0 · E3(변이 2개), drift 6건 E1 | +| 확실성과 남은 가정 | drift 목록은 표본이다. 목표 설계 문서는 상태 줄만 봤다. 경로 존재 검사는 scratchpad 스크립트(47줄)로 돌렸고, 현재 계약 문서에서 없는 경로는 생성 산출물(`artifacts/**/*.json`), 의도적으로 풀리지 않게 둔 diagram 출처 경로(`review-evidence.md`), 위 (라)뿐이었다 | +| 결정의 근거 | 설계 선택이다. 5.3절 | +| 이해 비용 | 문서를 믿을지 매번 코드로 확인해야 한다 | +| 최소 개선 방향 | ① `verify:documentation`에 "`docs/README.md` §1의 현재 계약 문서에 적힌 repo 경로·package script·FE-GATE ID가 존재하는가" 검사를 더한다. 생성 산출물 경로는 제외 목록으로 둔다. ② 줄 번호 참조(`file.ts:163-171`)는 현재 계약 문서에서 심볼 이름으로 바꾼다. ③ diagram 검사는 이름과 뜻을 맞춘다. "2026-07-18 diagram 리뷰 기록의 일관성"으로 부르거나 `DOCUMENTATION_READY`에서 분리한다. ④ 위 (가)~(마)를 고친다 | +| 대안 비교 | 5.3절: (a) 현 상태 (b) 현재 계약 문서 한정 존재 검사 (c) 문서 전체 내용 검사 (d) 문서에서 수치·목록 제거(14-07 방식 확대). (b)+(d) 권장 | +| 단순화의 보존 조건 | 지금 검사하는 route ID·빌드 변수 대조는 그대로 둔다. 목표 설계 문서는 검사 대상에 넣지 않는다(설계상 경로가 아직 없다) | +| 비용·부작용 | 검사 수십 줄. 처음 실행 때 (라) 같은 낡은 경로가 실패로 드러난다 | +| 재검토 조건 | 현재 계약 문서 목록이 바뀔 때. 존재 검사가 오탐을 반복하면 제외 목록을 다시 본다 | +| 완료 기준 | 현재 계약 문서의 경로 하나를 없는 경로로 바꾸는 변이에서 `verify:documentation`이 실패한다. (가)~(마)가 고쳐졌다 | +| 검증 방법 | 변이 실험. README 라우트 표 행 삭제 변이도 같이 넣는다(표를 route registry에서 검사할 경우) | +| 담당·기한·상태 | 미정 · 미정 · 신규. FOLLOW-UP(09-25) 14-07의 후속 | + +### 14-06 `verify:documentation`이 route ID 누락을 "scoped-review evidence"가 부족하다고 보고한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 8, 20 | +| 근거 | 실패하면 `scripts/verify-documentation-readiness.ts:137-147`이 빌드 변수 누락만 stderr에 적는다. route ID 누락은 `artifacts/quality/documentation-review.json`의 `routeScope`에만 있다. 마지막 메시지는 원인과 무관하게 "Documentation readiness: FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)"다. 변이 실험에서 `EXAMPLES_PLATFORM` 한 개를 지웠을 때 이 메시지만 나왔다(3.3절) | +| 발생 조건 | 기능을 추가해 route가 늘었는데 README나 체크리스트에 ID를 적지 않았을 때. 기능 추가마다 생길 수 있다 | +| 영향 | 개발자가 diagram 리뷰 기록을 먼저 의심한다. 산출물 JSON을 열어야 원인을 안다 | +| 심각도·우선순위 | Low · P3 — 진단 문구의 문제다. 게이트는 올바르게 실패한다 | +| 통제·증거 | M2(검사는 있음, 진단이 틀림) · E3(변이) | +| 확실성과 남은 가정 | 없음 | +| 결정의 근거 | 적용 제외 — 진단 출력 보강 | +| 이해 비용 | 작다 | +| 최소 개선 방향 | 실패 시 `missingRouteIds`를 문서별로 stderr에 적고, 마지막 메시지를 실패한 검사 이름으로 바꾼다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | route ID 하나를 지우는 변이에서 stderr가 문서 경로와 빠진 ID를 적는다 | +| 검증 방법 | 3.3절 변이 재실행 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 14-07 문서 위치가 문서 상태를 드러내지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 4, 9, 20, 23 | +| 근거 | 상태 구분(현재 계약 / 목표 설계 / 이력)은 `docs/README.md:3-9`에만 있다. ① `docs/architecture/` 24개 문서 중 현재 계약은 8개(`docs/README.md:24-34`), 목표 설계는 15개, 게이트 증거 1개가 한 폴더에 섞여 있다. 문서 머리에도 상태 줄이 일정하지 않다(일부만 "상태:"를 가짐). ② 게이트가 읽는 현재 계약 `INVENTORY.md`가 이력 폴더 `docs/reviews/adapters/`에 있다(`README.md:201`의 예외로 관리). ③ 현재 구조의 설계서가 `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/`(6단계)에 있다(14-01). ④ `frontend-platform-implementation-roadmap.md`(기준 `cb195f8`, 2026-07-26의 12개 브랜치 계획, 마지막 수정 08-01)와 `frontend-platform-capability-review.md`(같은 기준, RP-01~12 누적 리뷰)는 작업 계획·리뷰인데 "목표 설계"(`docs/README.md:54`)와 README "Platform capability review"(`README.md:159-185`)에 있다 | +| 발생 조건 | 처음 온 사람이 `docs/`를 폴더로 탐색할 때. 매뉴얼이 링크할 문서를 고를 때 | +| 영향 | 목표 설계를 현재 동작으로 오해할 수 있다(문서마다 상태 값을 확인하라는 안내는 있다). `docs/manual/`이 생기면 네 번째 종류가 같은 방식으로 섞인다 | +| 심각도·우선순위 | Low · P3 — 안내 문서가 있어 오해를 줄인다. 탐색 비용 문제다 | +| 통제·증거 | M1(색인 문서) · E1 | +| 확실성과 남은 가정 | 없음 | +| 결정의 근거 | 설계 선택이다. 5.2절과 함께 본다 | +| 이해 비용 | 문서 하나를 열 때마다 `docs/README.md`와 대조해야 한다 | +| 최소 개선 방향 | (가) 폴더 이동 없이: 모든 `docs/**/*.md` 첫 줄 아래에 `상태: 현재 계약 | 목표 설계 | 이력` 한 줄을 두고, 14-05의 검사가 그 줄이 `docs/README.md` 분류와 같은지 본다. (나) roadmap·capability-review는 이력으로 재분류하고 README 링크 목록(`README.md:159-185`)을 줄인다. (다) `docs/manual/`은 처음부터 `상태: 현재 계약`으로 시작한다 | +| 대안 비교 | (A) 현 상태. (B) 위 (가)~(다): 링크가 깨지지 않는다. (C) 폴더를 상태별로 재배치(`docs/contracts`, `docs/design`, `docs/history`): 가장 분명하다. 링크 수백 개와 게이트 입력 경로(`INVENTORY.md`, `review-ledger.json`)를 함께 옮겨야 한다. (B) 권장, (C)는 매뉴얼이 자리 잡은 뒤 | +| 단순화의 보존 조건 | 게이트가 읽는 파일 4종(`docs/README.md:42-46`)의 경로는 검사 스크립트와 함께가 아니면 옮기지 않는다 | +| 비용·부작용 | 문서 약 100개에 한 줄. 검사 몇 줄 | +| 재검토 조건 | 문서 수가 크게 줄거나 매뉴얼이 입구를 대신하게 될 때 | +| 완료 기준 | 모든 문서가 상태 줄을 갖고, 색인 분류와 일치한다. roadmap·capability-review가 이력에 있다 | +| 검증 방법 | 상태 줄 하나를 바꾸는 변이에서 검사가 실패한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 검토 (41절) + +### 5.1 "작업 이력은 복사 뒤 지워도 된다" 정책 + +1. **무엇이 필요한가.** 복사한 제품이 템플릿의 작업 기록을 자기 계약으로 오해하지 않는다. 동시에 유지보수자는 결정 근거를 찾을 수 있다. +2. **지킬 성질.** 지운 뒤에도 빌드·게이트가 돈다. 지운 뒤에도 남은 코드·문서가 근거를 잃지 않는다. +3. **현재 보장.** 첫째 성질은 M3다(`deletable-history-documents.test.ts`, 3.2절 실험 PASS). 둘째 성질은 보장하지 않는다. `Spec §N` 68곳, `INVENTORY.md` 145링크, 리뷰 ID 약 339곳이 지워질 문서에 의존한다(14-01, 14-02). +4. **대안.** (a) 현 상태. (b) 아직 유효한 결정을 현재 계약으로 승격하고, 참조에 문서 이름을 쓰고, 검사가 이름 없는 참조를 잡는다. (c) "이력은 지우지 말라"로 정책을 바꾼다. (d) 이력을 별도 저장소로 옮긴다. +5. **비교.** + - (a)는 비용이 없다. 근거 손실은 복사본마다 반복된다. + - (b)는 문서 1~2개 이동과 주석 치환이 든다. 이력은 계속 지울 수 있다. + - (c)는 가장 싸다. 대신 0929/14-01의 동기화 비용(템플릿 기록을 매번 골라냄)이 그대로 남고, 목표 설계·이력·현재 계약이 계속 섞인다. + - (d)는 리뷰와 커밋을 한 저장소에서 대조하는 이 repo의 리뷰 절차(`CLAUDE.md`)와 맞지 않는다. +6. **선택.** (b). 결정 근거와 작업 기록은 수명이 다르다. 근거는 코드가 사는 동안 필요하다. +7. **재검토 조건.** 템플릿을 생성기·패키지로 배포해 복사 대상을 도구가 정하게 될 때. + +### 5.2 같은 주제를 ADR·주제 설계·정본·역량 리뷰·로드맵이 여러 겹으로 설명하는 구조 + +1. **무엇이 필요한가.** 결정(왜), 상세 설계(어떻게), 현재 상태(어디까지)를 각각 찾을 수 있다. `docs/manual/`은 주제마다 하나의 링크로 충분해야 한다. +2. **지킬 성질.** 같은 결정을 두 문서가 다르게 말하지 않는다. 어느 문서가 이길지 정해져 있다. +3. **현재 보장.** "정본" 지정이 두 겹이다. `docs/README.md:52`와 `capability-review.md`·`static-delivery.md` 머리말은 07-30 상세 설계(5,960줄)를 정본으로 둔다. VD-13 머리말은 `client-cache-and-storage.md`를 상세 설계로 둔다. 상태 원장(`browser-data-capability-completion-ledger.md`)과 README 지원 범위(`README.md:94-124`)도 상태를 따로 적는다. 그대로 겹치는 줄은 적다(쌍마다 최대 9줄). 그러나 같은 주제를 4~6문서가 다시 설명한다(7.5절). 내용 일치를 검사하는 장치는 없다. +4. **대안.** (a) 현 상태 + `docs/README.md` 색인. (b) 주제마다 정본 하나(주제 설계 문서)를 정하고, VD는 결정 요약과 재검토 조건만 남기고, roadmap·capability-review는 이력으로 보낸다. (c) 07-30 문서 하나로 합친다. +5. **비교.** + - (a)는 비용이 없다. 매뉴얼 작성자가 주제마다 4~6문서를 대조해야 한다. + - (b)는 문서 재분류와 머리말 정리가 든다. 매뉴얼은 "결정: VD-xx / 상세: 주제 문서 / 상태: 원장"의 세 링크로 끝난다. + - (c)는 5,960줄 문서가 더 커진다. 이 문서는 "구현 결정 폐쇄"라는 한 시점의 산출물이라 갱신 책임이 불분명하다. +6. **선택.** (b). 매뉴얼에는 VD(짧은 결정)와 주제 문서 하나만 링크하고, 07-30 정본은 "충돌 시 기준"으로만 둔다. +7. **재검토 조건.** 선택 capability가 실제로 설치되어 문서가 현재 계약으로 승격될 때. 그때 해당 주제 문서를 현재 계약으로 옮긴다. + +### 5.3 `verify:documentation`을 좁게 두는 선택 + +1. **무엇이 필요한가.** 현재 계약 문서가 코드와 다르면 누군가 안다. 동시에 문서 검사가 오탐으로 merge를 막지 않는다. +2. **지킬 성질.** "게이트가 검사한다"고 소개한 문서(`docs/README.md:6`)는 실제로 검사된다. +3. **현재 보장.** 3가지만 검사한다(14-05). 그중 diagram 검사는 사본끼리의 일치다. 14-07(09-25)에서 수치를 문서에서 지워 drift 자리를 줄였다(`capability-consumer-experience.md:25-27`). 실제로 그 문서의 남은 표(`:85-91`)는 이번에 코드와 맞았다(295줄, import 7개). +4. **대안.** (a) 현 상태. (b) 현재 계약 문서에 한해 경로·script·게이트 ID 존재 검사. (c) 문서 전체 내용 검사. (d) 문서에서 수치·목록·줄 번호를 더 지운다. +5. **비교.** + - (a)는 drift가 쌓인다(이미 6건). + - (b)는 scratchpad의 47줄 스크립트로 리뷰 폴더를 뺀 문서 99개 전부를 0.08초에 돌렸다(load average 9.55). 오탐은 생성 산출물 경로와 의도적으로 풀리지 않게 둔 diagram 출처 경로(`review-evidence.md`)뿐이었다. + - (c)는 자연어 주장을 기계로 검사할 수 없다. 과하다. + - (d)는 검사 없이 drift 자리를 줄인다. 라우트 표처럼 독자에게 필요한 목록은 지울 수 없다. +6. **선택.** (b)+(d). 라우트 표는 route registry와 대조하는 검사로 바꾸거나, `starter-experience.md:27-32`처럼 "런타임 화면을 보라"로 바꾼다. +7. **재검토 조건.** 존재 검사가 반복해서 오탐을 내면 제외 목록을 다시 본다. 현재 계약 문서가 매뉴얼로 옮겨지면 검사 대상도 옮긴다. + +## 6. 리팩토링 후보 + +| 후보 | 무엇을 왜 | 보존 조건 | +|---|---|---| +| R1 설계서 승격 | extreme-scale 설계서의 유효 절을 `docs/architecture/`로 옮기고 `Spec §N`에 문서 이름을 붙인다(14-01) | 주석의 설명 문장. 절 번호 의미(바꾸면 68곳 동시 수정). 설계서의 Non-Goals(§52) | +| R2 `INVENTORY.md` 위치 | 게이트가 읽는 현재 계약을 이력 폴더 밖으로 옮기거나, 리뷰 문서 링크 145개를 그룹 이름으로 바꾼다 | `check:adapter-inventory`의 입력 경로와 행 형식. `deletable-history-documents.test.ts:22-23`의 `KEPT` 예외. `docs/README.md:45`, `README.md:201` | +| R3 roadmap·capability-review 재분류 | 7월 계획·리뷰를 이력으로 옮기고 README 링크 목록을 줄인다(14-07) | `overview.md:64-80`, `README.md:159-185`의 링크를 함께 고친다. 07-30 정본이 이 둘을 인용하는지 확인한다 | +| R4 `design-tokens.md` 갱신·병합 | 3계층 토큰 파일과 `check:design-system` 규칙 4개를 적거나, `design-system-platform.md`의 "현재 구현" 절로 합친다(14-05 나) | `docs/README.md:37` 입구 링크. `/examples/ui` 설명. "구현된 것 / 목표"의 구분 문장(`design-tokens.md:44-49`) | +| R5 `SPEC.md`·`tasks/` 이동 | 루트 작업 기록을 이력 폴더 한 곳으로(0929/14-01 반복) | 지울 수 있는 기록 검사의 패턴(`:27-29`)을 새 경로로 바꾼다 | +| R6 `layers.md` 표 | 실제 9개 폴더 + 규칙 이름 열(14-03) | kernel 예외 절, 배럴 절의 문장 | + +## 7. `docs/manual/` 준비용 문서 상태 목록 (이번 라운드 추가) + +기준: 매뉴얼은 "작업 순서 + 판단 지점"을 쓴다. 아래는 문서의 상태만 본다. 기능 추가 절차의 내용은 16 영역이 다룬다. + +### 7.1 매뉴얼에서 그대로 링크할 문서 (현재 계약, 이번에 큰 어긋남 없음) + +| 문서 | 매뉴얼에서 쓸 곳 | 확인한 것 | +|---|---|---| +| `README.md` "Start locally"(`:7-22`), "Runtime configuration"(`:24-71`), "Verification"(`:211-284`), "CI and evidence" merge 게이트 루프(`:297-308`) | 시작, 프로필·배포 변수 판단, 로컬 검증 순서 | Node 24.14.0·Vite 8·Playwright 1.62·Tailwind 4 표기가 `package.json`·`.nvmrc`와 같다. merge 게이트 13개가 `config/ci/gates.json` stages와 같다. 변수 표는 게이트가 검사한다 | +| `docs/architecture/starter-experience.md` | 인증 모드 판단(`:38-76`), 기능 소속 선언(`:86-110`) | 파일·export 이름이 실제와 같다. `:145-147`의 "governance 파일은 바뀌지 않는다"는 09-29 07-03과 충돌(07 영역) | +| `docs/architecture/optional-adapter-recipes.md` | recipe를 넣을지 판단, 넣고 빼는 순서 | recipe 12개가 `config/recipes/frontend-capability-recipes.json`과 같다. SW 설명 차이는 09-29 06-03(06 영역) | +| `docs/architecture/capability-consumer-experience.md` | 기능 품질 체크리스트(`:132-155`) | 표 수치(295줄, import 7개)가 코드와 같다 | +| `docs/testing/taxonomy.md` | 테스트를 어느 계층에 둘지(`:85-99`), 파일 하나 실행(`:42-53`) | `test:all` 순서가 `package.json`과 같다. 파일 하나 실행 명령은 이번 worktree에서 동작했다. `:109-110`만 0929/14-01 | +| `docs/architecture/static-delivery.md` | 배포 흐름과 저장소 책임 경계 | 짧고 FE-GATE-019 설명이 맞다 | +| `docs/runbooks/FE-RB-001~005.md` | 장애 판단 지점(트리거·종료 조건) | 트리거 코드 5종이 `src`에 있다. 001~004는 정책 수준이고 명령이 없다. 명령은 005에만 있다 | +| `docs/operations/release-cache-rollback.md`, `performance-evidence.md` | 롤백·성능 예산 판단 | 경로 검사 이상 없음 | +| `docs/accessibility/manual-checklist.md` | release 전 수동 접근성 검토 | route ID를 게이트가 검사한다 | +| `docs/security/browser-boundary.md`, `supply-chain.md` | 비밀값·공급망 판단 | 경로 검사 이상 없음(내용은 13·15 영역) | +| VD-01, 03, 04, 05, 06, 07, 08, 09, 10 (58~140줄) | "왜 이 도구인가" 근거 링크 | 짧은 ADR이고 재검토 조건이 있다. VD-01은 TS 전환 뒤 갱신 절이 있다 | + +### 7.2 고친 뒤 링크할 문서 (낡았거나 코드와 어긋남) + +| 문서 | 어긋난 곳 | 발견 | +|---|---|---| +| `docs/architecture/layers.md` | 폴더 9개 중 3개 누락, 없는 `src/domain`, 규칙 13개 설명 없음, `:51-52` 보증 문장 | 14-03 | +| `docs/architecture/overview.md` | `:15` Domain 계층, platform·apps·contexts 없음 | 14-03 | +| `docs/architecture/frontend-application-foundation.md` | `:17-31` 수평 목록에 platform·apps·contexts 없음 | 14-03 | +| `docs/architecture/contract-ownership.md` | `:17-24` 배치 규칙에 `src/platform` 선택지 없음 | 14-03 | +| `README.md` "Included starter experience"·"Architecture" | 라우트 표에 `/examples/platform` 없음, 언어 선택기 없음, `:140-147` 그림 | 14-05, 14-03 | +| `README.md` "Files you can delete"·"Updating a copied project" | `PRODUCT.md` 없음, 로그 처리 없음, 범위 반영 절차 없음 | 14-04, 0929/14-01, 0929/14-02 | +| `docs/styling/design-tokens.md` | `:3` SSOT 표현, 3계층 토큰과 새 규칙 4개 없음 | 14-05 | +| `docs/contracts/compatibility.md` | `:23,26` 줄 번호 어긋남(판단표 자체는 유효) | 14-05 | +| `docs/operations/ci-quality-gates.md` | `:69` "조용히 무시". 매뉴얼에는 `:13-71`(기준선 갱신)만 링크하고 `:75-108`(셸 파서 정책)·provider sandbox 절은 운영자용으로 둔다 | 0929/14-05 | +| `PRODUCT.md` | `:33` 제거 주장, `:56` `SPEC.md` 근거 | 14-04 | +| `CHANGELOG.md` | v0.2.0 뒤 절 없음, `:11` 해시 주의문 낡음, ID 라운드 없음 | 0929/14-04, 14-05, 14-02 | +| `docs/operations/adapter-remediation-ledger.md` | 옮겨진 테스트 경로, 리뷰 문서 링크 7개. 읽는 검사 `check:remediation-ledger`가 이 커밋에서 실패(4건, 12 영역) | 14-05, 14-01 | + +### 7.3 이력으로 옮길 문서 (지금 "목표 설계"·README 링크 목록에 있음) + +| 문서 | 이유 | +|---|---| +| `docs/architecture/frontend-platform-implementation-roadmap.md` (1,277줄) | `cb195f8`(2026-07-26) 기준 12개 브랜치 계획. 마지막 수정 08-01. 브랜치는 이미 병합됐다 | +| `docs/architecture/frontend-platform-capability-review.md` (532줄) | 같은 기준의 RP-01~12 누적 리뷰. `:135`가 없는 `src/adapters/inbound/react/platform/query`를 목표로 적는다 | +| `docs/superpowers/`, `docs/reviews/`(INVENTORY 제외), `SPEC.md`, `tasks/` | 이미 이력. `SPEC.md`·`tasks/`는 루트에서 옮긴다(0929/14-01) | + +### 7.4 이력 안에 있지만 현재 계약으로 승격할 내용 + +| 위치 | 승격할 내용 | 이유 | +|---|---|---| +| `docs/reviews/2026-09-23-extreme-scale-frontend-plan-bundle/docs/superpowers/specs/2026-09-23-extreme-scale-frontend-architecture-design.md` | §3~§8(구조·소유·의존·예산·registry), §10~§16(실행·트래픽), §17~§31(오류·검증·텔레메트리) | 코드 주석 68곳의 근거. `src/apps`·`contexts`·`platform`을 설명하는 유일한 문서(14-01) | +| `docs/superpowers/specs/2026-09-20-memento-frontend-template-bootstrap-design.md:35,37,56` | "제품이 고치는 템플릿 파일은 영구 충돌 지점", "삭제한 파일은 매번 충돌" 원리 | 업데이트 판단 지점의 근거(0929/14-03). 이번 재현에서도 그대로 일어났다 | +| `docs/reviews/adapters/INVENTORY.md` | 파일 자체 | 게이트가 읽는 현재 계약(R2) | + +### 7.5 같은 주제를 여러 문서가 설명하는 묶음 (매뉴얼은 한 곳만 링크) + +| 주제 | 문서 | 매뉴얼에서 링크할 곳 | +|---|---|---| +| 계층과 의존 방향 | `README.md:134-157`, `overview.md`, `layers.md`, `frontend-application-foundation.md`, `frontend-ports-adapters-and-boundaries.md`(목표 경로 `src/adapters/outbound`·`inbound/react` — 실제와 다름) | 고친 `layers.md` 하나. 실행 기준은 `.dependency-cruiser.json` | +| 디자인 토큰·디자인 시스템 | `design-tokens.md`, `design-system-platform.md`(목표 경로 `src/adapters/inbound/react/design-system/`, 없는 `@/` 별칭 예시 `:406`), `PRODUCT.md:31` | 고친 `design-tokens.md` | +| 테스트 | `taxonomy.md`, `frontend-platform-testing-strategy.md`(1,408줄) | `taxonomy.md`(`:119-121`이 역할을 스스로 구분) | +| 지원 범위 상태 | `README.md:94-124`, `browser-data-capability-completion-ledger.md:28-39`, 각 VD 머리말 | README 표. 세부는 원장 | +| 클라이언트 캐시 | VD-13, `client-cache-and-storage.md`(같은 줄 9개), `client-cache-and-storage-recovery.md` | VD-13 + 주제 문서 | +| 브라우저 파일·origin storage | VD-11, VD-15, `browser-file-and-origin-storage.md`, `browser-file-storage-recovery.md` | VD-11 + 주제 문서 | +| 전송·Image CDN | VD-12, VD-14, VD-16, `presigned-transfer-and-image-cdn.md`, `server-file-capability-infrastructure.md`, `browser-transfer-recovery.md` | VD-12 + 주제 문서. VD-16의 "top-level transfer runtime 미구현"은 코드와 맞다(`src/adapters/browser-transfer/index.ts`는 재수출 3줄) | +| API·서버 상태 | VD-23~26, `api-contract-schema-mapper-and-server-state.md`, `backend-api-and-server-state-contract.md`, `api-contract-and-server-state-recovery.md` | VD-23 + 주제 문서 | +| Protobuf·gRPC-Web | VD-27, VD-29, VD-30, `protobuf-browser-transport-and-rest-gateway.md` | 주제 문서(Experimental이라 매뉴얼은 "더 읽기"만) | +| Realtime | VD-28, `realtime-events-web-push-and-bounded-polling.md`(2,479줄) | VD-28 | +| 상위 정본 | 07-30 상세 설계(5,960줄), capability-review, roadmap | 매뉴얼에서는 링크하지 않거나 "충돌 시 기준"으로 한 줄 | +| 지울 파일 목록 | `README.md:192-209`, `docs/README.md:62-72` | README(색인은 README를 가리킨다) | + +VD 번호에 빈칸이 있다(VD-02, VD-17~22 없음). VD-02는 `frontend-platform-implementation-roadmap.md`에서만 언급된다. 결함은 아니지만 매뉴얼의 VD 목록은 실제 파일에서 만든다. + +### 7.6 매뉴얼에 필요한데 없는 문서 + +| 빠진 것 | 지금 상태 | +|---|---| +| 문제 해결(설치 실패, 포트 충돌, 생성 인덱스 누락 등) | 템플릿 사용자용 문서가 없다. 생성 인덱스 누락 오류만 `taxonomy.md:48-51`에 있다 | +| 현재 폴더 구조(apps·contexts·features·platform)의 역할과 예산 | 이력 설계서에만 있다(14-01, 14-03) | +| 템플릿 동기화 절차(범위 반영, 기준점, 파생 기준선 재계산) | 없다(0929/14-02). 두 제품 기록에 같은 목차가 있다 | +| 제품이 고치게 되는 템플릿 파일 표 | 없다(0929/14-03) | +| 예제 화면을 지우는 방법과 비용 | 없다. 드릴이 없고, 지우면 동기화 충돌이 생긴다(14-04, 3.4절) | +| 토큰으로 브랜드를 바꿀 때 지켜야 할 조건 | `check-design-system.ts` 주석에만 있다(14-05 나) | + +## 8. 판정표 + +### 8.1 28개 관점 (36.2) + +기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. + +| 번호 | 관점 | 판정 | 통제·증거 | 근거와 잔여 위험 | +|---|---|---|---|---| +| 1 | 코드 성숙도 | > | - | 01~13 영역 | +| 2 | 구조적 성숙도 | > | - | 09·12 영역. 구조를 설명하는 문서의 어긋남은 14-03 | +| 3 | 변경 용이성 | P | M1 · E3 | 다음 동기화 재현에서 40파일 변경에 충돌 10/4. 같은 원인(제품이 지운 샘플, 제품이 바꾼 토큰 파일)이 반복된다(0929/14-03) | +| 4 | 인지 부하 | P | M1 · E1 | 문서 151개 75,450줄. 주제마다 4~6문서(7.5절). 입구 문서가 폴더 3개를 빠뜨린다(14-03). 문서 위치가 상태를 드러내지 않는다(14-07) | +| 5 | 위험 가시성 | P | M0~M3 · E3 | 결정 근거가 지워도 되는 문서에 있다(14-01). `DOCUMENTATION_READY`가 실제보다 넓은 준비 신호로 읽힌다(14-05) | +| 6 | 실패 성숙도 | > | - | 다른 영역 | +| 7 | 운영 성숙도 | > | - | runbook 5개는 있다. 내용은 11·13 영역 | +| 8 | 디버깅 가능성 | P | M2 · E3 | 제거 JUnit은 검사별 원인을 쓴다. `verify:documentation` 실패 메시지가 원인과 다르다(14-06) | +| 9 | 유지보수 성숙도 | P | M1 · E3 | **깊게 봄.** 근거 참조가 이력에 걸림(14-01), ID 충돌(14-02), 현재 계약 drift 6건(14-05), CHANGELOG에 v0.2.0 뒤 절 없음(0929/14-04) | +| 10 | 테스트 성숙도 | P | M3 · E2·E3 | 샘플 제거 13개 검사 PASS(2:12). lint·`check:i18n`·`check:design-system`·e2e는 제거 검사 밖. 지울 수 있는 기록 검사는 경로만 잡는다(변이) | +| 11 | 데이터 성숙도 | - | - | 이 영역에 데이터 경계가 없다 | +| 12 | 동시성 성숙도 | - | - | 이 영역에 동시 실행 경로가 없다 | +| 13 | 확장성 | > | - | 11 영역 | +| 14 | 성능 성숙도 | > | - | 13 영역. 이 영역의 비용은 3.1·3.5절 | +| 15 | 보안 성숙도 | > | - | 다른 영역 | +| 16 | 의존성 성숙도 | P | M2 · E3 | 제품에게 템플릿은 의존성이다. 태그 `v0.2.0` 뒤 12커밋이 태그 없이 쌓였다. 기준점 형식이 두 제품에서 다르다(0929/14-02) | +| 17 | API / Contract 성숙도 | P | M1 · E3 | merge 게이트 규칙 4개가 CHANGELOG 없이 들어왔고 memento 제품 토큰 8개를 실패로 만든다(0929/14-04 재발). CHANGELOG ID가 모호하다(14-02) | +| 18 | 배포 성숙도 | > | - | 13 영역 | +| 19 | 설정 성숙도 | P | M3 · E1 | README 변수 표는 검사된다. `ci-quality-gates.md:69`가 코드와 다르다(0929/14-05) | +| 20 | 개발자 경험 | P | M1~M3 · E2 | **깊게 봄.** 과제 1(런타임 확인)·3(파일 하나 테스트)은 문서대로 된다. 과제 5(샘플 제거)는 드릴이 PASS지만 제품은 "같은 일을 직접 하라"(`README.md:205-209`)만 받는다. 과제 6(문제 해결) 문서가 없다. 입구 문서의 폴더 설명이 틀렸다(14-03) | +| 21 | Guardrail 성숙도 | P | M3(경로) / M0(이름 없는 참조) · E3 | 지울 수 있는 기록 검사는 경로만 잡는다(14-01). 추적 로그 63개(0929/14-01). 문서 drift 검사 3종(14-05) | +| 22 | 추상화 성숙도 | > | - | 09 영역 | +| 23 | 일관성 | P | M1 · E3 | 기준점 형식 2개(0929/14-02). 문서 상태 표기가 문서마다 다르다(14-07) | +| 24 | 네이밍 / 의미 성숙도 | P | M1 · E1 | 리뷰 ID가 라운드 간 충돌(14-02). "정본"이 두 겹(5.2절). `PRODUCT.md`의 제거 주장(14-04) | +| 25 | 조직 확장성 | P | M1 · E3 | 두 제품이 다시 같은 종류의 템플릿 파일에서 충돌한다(3.4절) | +| 26 | Ownership 성숙도 | P | M1 · E1 | **깊게 봄.** 결함 후보 회수 경로 없음(0929/14-06). CHANGELOG에 조치 담당 칸 없음(0929/14-04). 문서 freshness 담당이 없다(14-05) | +| 27 | 삭제 가능성 | P | M3 · E2·E3 | **깊게 봄.** reference feature 제거는 PASS. 예제 화면은 제거 드릴이 없고, 지운 제품은 매번 충돌한다(14-04, 3.4절). 이력 삭제는 게이트를 지키지만 근거를 끊는다(14-01) | +| 28 | 회복 가능성 | > | - | 다른 영역. 동기화 되돌림은 30.4에서 본다 | + +### 8.2 30절 템플릿 기준 + +| 절 | 판정 | 근거 | +|---|---|---| +| 30.1 최소 구성과 안전한 기본값 | P | 바뀐 것 없음. 깨끗한 환경 실행은 이번에도 확인하지 못했다 | +| 30.2 옵션 조합 | P | 바뀐 것 없음. 지원 범위 표(`README.md:94-124`)는 있고 조합 검증 범위는 없다 | +| 30.3 생성·복사 후 수정 권한 | P | 템플릿 전용 파일이 하나 늘었다(`PRODUCT.md`, 목록에 없음, 14-04). 로그·`SPEC.md`·`tasks/` 그대로(0929/14-01) | +| 30.4 버전과 업데이트 전파 | P | **E3.** v0.2.0 뒤 12커밋이 CHANGELOG 없이 쌓였다. 다음 동기화 재현: 충돌 10/4, 템플릿 전용 파일 19개 유입, memento의 merge 게이트 FE-GATE-010 실패 예상 | +| 30.5 샘플 코드의 대표성 | P | 샘플 기능은 실패 분류까지 보여 준다. 예제 화면은 제거 경로가 없는데 `PRODUCT.md`는 있다고 적는다(14-04) | +| 30.6 도입·유지 비용 | P | package script 142, CI 게이트 27, 문서 151개 75,450줄(그중 이력 82개 34,939줄), 샘플 제거 드릴 2:12·CPU 669초·RSS 1.16GB | +| 30.7 템플릿에서 졸업할 수 있는가 | P | 바뀐 것 없음(0929 판정 유지) | +| 30.8 배포 판단에 필요한 최소 증거 | P | "선택 기능 분리"는 템플릿에서 E2(드릴 PASS). "패치 전달"은 재현에서 충돌·게이트 실패가 예상된다. "새 프로젝트 시작" 깨끗한 환경 증거는 여전히 없다 | + +## 9. 미검증 + +| 항목 | 이유 | 확인하려면 | +|---|---|---| +| 깨끗한 환경 `install --frozen-lockfile` → `dev` | 공유 `node_modules` 보호 | 새 clone이나 컨테이너에서 README 명령만 실행 | +| 나머지 제거 드릴 3개 | CPU·시간. 이번에는 `test:sample-removal`만 돌렸다 | `flock` 아래에서 `test:optional-recipe-removal`, `test:browser-file-storage-removal`, `test:realtime-removal` | +| `check:scale:pr`가 추적 로그를 다시 쓰는지(0929/14-01) | 이번에 재실행하지 않음. 쓰는 코드는 그대로다(E1) | worktree에서 실행 뒤 `git status --short` | +| 다음 동기화 뒤 두 제품의 전체 게이트 | `check:design-system`만 병합 트리에서 돌렸다 | 제품 sync 브랜치에서 실제 병합 후 merge 게이트 13개 | +| 목표 설계 문서 본문의 세부 주장 | 약 3.4만 줄. 머리말·상태 줄·경로만 봤다 | 매뉴얼이 링크하기로 정한 문서부터 상태 줄과 코드 대조 | +| 템플릿 이슈 트래커의 결함 후보 회수(0929/14-06) | 외부 요청 금지 | 사용자가 Gitea 이슈 목록 확인 | +| `PRODUCT.md`를 읽는 도구의 실제 동작 | 도구를 실행하지 않음 | 해당 디자인 도구 문서 확인 | diff --git a/docs/reviews/2026-11-01-maturity-review/15-performance.md b/docs/reviews/2026-11-01-maturity-review/15-performance.md new file mode 100644 index 00000000..df6db4e6 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/15-performance.md @@ -0,0 +1,425 @@ +# 영역 15 — 성능 실측·최적화 + +> 검토일: 2026-11-01 · 기준: 브랜치 `fix/ui-design-audit-2026-11-01` / `d99301b` · 가이드: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md` +> 경로: `config/performance/budgets.json`, `scripts/check-bundle.ts`, `scripts/lib/{performance-budgets,classify-vite-bundle,lab-performance}.ts`, `scripts/test-performance.ts`, `scripts/collect-web-vitals-evidence.ts`, `docs/operations/performance-evidence.md`, `vite.config.ts`, 부팅 경로(`src/bootstrap/`), 빠른 테스트 계층의 실행 시간. +> 깊게 본 관점: 14, 13, 10, 20. 이번 라운드 신규 영역이라 지난 같은 영역 문서는 없다. 대신 지난 리뷰의 성능 관련 발견(2026-09-25 `FOLLOW-UP.md` P1·P2, 2026-09-29 11-04·11-05, 영역 13의 4.2절·13-03)을 다시 확인했다. +> 영역 판정(35.8): **조건부 사용 가능.** 템플릿 그대로의 첫 화면은 lab 예산 안이다(LCP 중앙값 1.9초 / 2.5초, CLS 0, 화면 전환 80~114ms / 200ms). 그러나 초기 JS 예산이 99.4% 차 있다. 기능 1개를 넣으면 넘는다(실측 +3,906 B). 넘었는지 보는 검사는 release 단계에서만 돈다(15-01). 기능을 추가하기 전에 예산을 다시 정하고, 검사를 merge 단계로 옮겨야 한다. + +## 0. 결론 + +- **초기 JS는 203,507 / 204,800 gzip B다. 여유는 1,293 B(0.6%)다.** 기능 모양 1개를 넣으면 207,413 B가 된다(+3,906 B, 5개면 개당 +3,414 B). 첫 기능에서 예산을 넘는다. 이 검사(FE-GATE-012)와 lab 검사(FE-GATE-026)는 tag나 수동 release 실행에서만 돈다. 넘는 PR은 merge되고, 다음 release가 빨갛다(15-01). +- **초기 JS의 약 57%는 라이브러리다.** react-dom 56 KB, react-router 31 KB, zod 18 KB, TanStack 7 KB, react 3 KB(각각 단독 gzip 추정). 템플릿 코드는 약 81 KB다. 초기 청크의 모듈은 전부 `boot.tsx`의 정적 import로 닿는다. lazy 라우트 전용 코드가 초기 청크로 끌려온 것은 0 B다(2.1절). +- **lab LCP 1.9초 중 1.1초가 JS 다운로드다.** lab 프로필(CPU 4배 감속, 200,000 B/s)에서 마지막 JS가 1,277ms에 도착한다. 그 뒤 평가(122ms) → `config.json` → `release-manifest.json` → 홈 청크 → 렌더가 차례로 이어져 H1이 1,872~1,916ms에 그려진다(2.2절). 이 프로필에서 초기 JS 10 KB gzip은 LCP 약 50ms다. +- **lab 게이트는 이번에 10/10 통과했다.** 공용 락 안에서 5회씩 2번, LCP 중앙값 1,892·1,904ms, 상호작용 111·112ms. 지난 11-04의 판정 뒤집힘은 재현되지 않았다. 부하 가드가 없는 코드는 그대로다. +- **release마다 초기 JS의 47%(96,186 B)가 캐시에서 버려진다.** build id가 react-dom과 같은 청크에 들어가서다. `manualChunks` 한 줄로 react-dom을 떼면 40,929 B로 줄었다(실험, 기존 번들 테스트 통과, 6절 O1). +- **`performance-evidence.md`의 기준선 표가 현재 빌드와 다르다.** 문서는 96%·여유 8.2 KB·`index` 93.5 KB를 적는다. 실제는 99.4%·1.3 KB·`index` 0.8 KB다(15-02). +- **unit 테스트 시간의 54%는 빌드·pnpm·tsc를 띄우는 16개 파일이다.** integration의 가장 느린 파일은 테스트 안에서 `pnpm build:release-candidate`를 돌린다. SW 테스트 하나는 5초를 실제로 기다린다. 공용 setup은 모든 파일에 React Testing Library를 싣는다. DOM이 있을 때만 싣게 바꾸면 세 계층 합산이 22.6~23.9초에서 21.3초가 됐다(15-04). +- **`npx vitest`로 돌리면 unit 79건이 실패한다.** 테스트가 `npx`가 넣는 `npm_config_*` 환경변수를 그대로 읽는다. `scripts/run-vitest.ts`로 돌리면 통과한다(15-05). + +## 1. 범위와 방법 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template` 영역 15(성능) | +| 커밋·상태·시점 | `d99301b`, 2026-11-01. 메인 워킹트리는 추적되지 않는 `.claude/`만 있다 | +| 실행 환경 | Ubuntu, Node v24.14.0, Vite 8.1.5(rolldown), Vitest 4.1.10, Playwright 1.62.0 / Chromium 151.0.7922.34, Intel Core Ultra 7 155H(`nproc` 22). 다른 영역 에이전트가 동시에 돌았다. 무거운 실행은 공용 `heavy.lock` 안에서 했고, 시작 직전 loadavg를 같이 적었다. 락 밖의 다른 작업 때문에 loadavg는 5~24 사이였다 | +| 목적·실행 형태 | 템플릿(참고 구현). 브라우저 SPA + 정적 호스팅 + 선택형 Service Worker(기본 `null`). SSR 없음 | +| 성능 목표 | `config/performance/budgets.json:3-11`: 초기 JS 204,800 gzip B, lazy 청크 파일당 122,880 B, lab LCP 2,500ms·CLS 0.1·상호작용 200ms. field p75는 표본 기준이 미정이라 항상 `FAIL_UNVERIFIED`다(설계대로) | +| 읽은 범위 | 머리말 경로, `src/bootstrap/{main.tsx,boot.tsx,composition-root.ts,create-runtime-composition.ts,register-service-worker.ts,read-bounded-boot-json.ts}`, `src/presentation/routes/{route-runtime,app-router}.tsx`, `config/ci/gates.json`(FE-GATE-005·011·012·018·026, stages), `.gitea/workflows/quality-gates.yml:28`, `:79-92`, `config/scale/feature-shape-ceilings.json`, `tests/setup.ts`, `vitest.config.ts`, `scripts/run-vitest.ts`, 느린 테스트 파일 상위 항목 | +| 확인하지 못한 범위 | 8절. 요약: Firefox·WebKit, 실제 CDN·brotli 전송, field 수치(입력 없음), CI 러너, CPU 경합을 일부러 건 lab 재현, e2e 시간(영역 11) | +| 이전 리뷰와 비교 | 이 영역 문서는 처음이다. 지난 리뷰의 성능 관련 발견 5건을 현재 코드와 새 실측으로 다시 확인했다(3절). 지난 실행 결과는 증거로 쓰지 않았다 | + +실험은 `scratchpad/wt-15`(d99301b worktree, 원본 `node_modules` 심볼릭 링크)에서 했다. worktree 안에서 pnpm을 직접 부르지 않았다. lab 스크립트는 안에서 `corepack pnpm preview`를 띄운다. 그래서 worktree 사본에서만 이 부분을 `npx vite preview`로 바꿨다(`scripts/test-performance.ts:57`, `scripts/lib/lab-performance.ts:16`). 측정 로직은 그대로다. 테스트 시간의 기준 수치는 수정 없는 메인 트리에서 쟀다. 메인 repo에서 바꾼 파일은 이 문서뿐이다. + +알림: worktree에서 `tests/integration`을 돌릴 때 `security-followup-archive.test.ts:57-76`이 임시 복사본(`mkdtemp`, worktree 아님)에서 `corepack pnpm build:release-candidate`를 띄웠다. 테스트 자체가 하는 일이라 미리 알지 못했다. 복사본의 `node_modules`는 F-4 방식의 항목별 링크다(`scripts/lib/fixture-node-modules.ts`). 실행 뒤 원본 `node_modules`를 확인했다: `.pnpm` 425개, 최상위 27개, `.modules.yaml` 수정 시각 2026-09-29 그대로. + +| 명령·실험 | 시작 전 loadavg(1분) | 결과 | +|---|---|---| +| `node scripts/generate-product-feature-index.ts && node scripts/build-frontend.ts` | 8.70 | rc=0, 1.41초(앱 Vite 빌드 339ms). JS 27개, CSS 1개 | +| 청크 크기 계산: repo의 `classifyViteJavascript` + Node `gzipSync`(level 6, `check-bundle.ts`와 같은 방식) + brotli | — | 초기 JS 13개 파일 664,056 B raw / **203,507 B gzip** / 177,501 B brotli. 여유 1,293 B | +| 같은 설정 + sourcemap + 모듈 그래프 덤프 빌드(`vite.review15.config.ts`, worktree 전용) | 21.90 | 청크 해시가 기본 빌드와 같다. 모듈별 바이트와 정적 도달성 계산(2.1절) | +| `node scripts/test-performance.ts --runs=5` ×2 (`LAB_PERFORMANCE_PORT=4473`) | 18.54 / 15.49 | 2번 모두 PASS. LCP 중앙값 1,892 / 1,904ms, CLS 0, 상호작용 111 / 112ms | +| 자체 Playwright 스크립트: 같은 throttle로 cold 로드 3회의 resource timing·LCP 후보·long task | 12.78 | 2.2절 waterfall | +| 자체 Playwright 스크립트: 라우트 5개 × 5회 전환 시간(페이지 시계: 클릭 → `main h1` 변경) | 22.57 | 중앙값 80~114ms, 모두 SPA 전환(2.3절) | +| `VITE_BUILD_ID`만 다른 두 빌드의 자산 비교 | 5.35 | 3개 파일 바뀜: `boot`·`index`·`render-boot-failure`, 합계 96,186 B gzip | +| 같은 비교, `manualChunks`로 `react-dom`·`scheduler`를 전용 청크로 뺀 변이 | 20.20 | 바뀌는 파일 3개 합계 40,929 B. 초기 JS 203,126 B(−381 B). `build-environment-bundle`·`bundle-classification` 테스트 5/5 통과 | +| `node scripts/check-optional-recipes.ts --require-dist` | 5.35 | PASS. 여유 77·14·9·338 B(2.5절) | +| `node scripts/scale/measure-feature-shape-growth.ts --sizes=0,1,5 --repeats=1` | 10.36 | 초기 JS 203,507 → 207,413(+1) → 220,575(+5). lazy 23,521 → 28,642 → 47,719 | +| 메인 트리: `node scripts/run-vitest.ts run tests/unit` + 파일별 시간 reporter | 8.58 | 165파일 2,353건 통과, 벽시계 12.6초 | +| 메인 트리: `npx vitest run tests/component`, `tests/integration` + reporter | 22.46 / 23.66 | 모두 통과. 7.2초 / 9.3초 | +| 메인 트리: `npx vitest run tests/unit` | 19.28 | **79건 실패**(`ci-workflow-generation.test.ts`). 같은 파일을 `node node_modules/vitest/vitest.mjs`나 `run-vitest.ts`로 돌리면 415/415 통과(15-05) | +| 메인 트리: FE-GATE-005의 coverage 실행과 같은 파일 묶음, `--maxWorkers=4`, coverage 있음 / 없음 | 15.17 | 278파일, 57.1초 / 49.1초(`npx`로 띄워 위 79건 실패 포함) | +| worktree: 기준 setup vs DOM이 있을 때만 RTL을 싣는 setup, 세 계층 합산 2라운드 교차 | 5.16 | 기준 22.6 / 23.9초, 변이 21.3 / 21.3초. 통과·실패 수 동일 | + +게이트 시간은 오케스트레이터 실행 기록(`scratchpad/gates/summary.txt`)을 그대로 썼다. 그 기록에는 부하가 없다. + +## 2. 측정 결과 + +### 2.1 번들 + +**초기 JS.** 엔트리, 엔트리의 정적 import, 엔트리 청크의 dynamic import를 센다(`scripts/lib/classify-vite-bundle.ts:9-15`, `:37`). + +| 파일 | raw B | gzip B | 주요 내용(sourcemap 기준) | +|---|---:|---:|---| +| `design-system-*.js` | 216,610 | 66,251 | react-router 94 KB(min), i18n 카탈로그 17.6 KB, `adapters/http` 26 KB, design-system·forms·templates | +| `render-boot-failure-*.js` | 186,322 | 58,633 | react-dom·scheduler 178 KB(min), `contracts/env.ts`(build id), 부팅 실패 화면 | +| `boot-*.js` | 120,909 | 36,937 | 라우터 조립, SW page controller, query cache, cross-context invalidation, telemetry | +| `reference-feature-runtime-descriptor-*.js` | 95,318 | 25,138 | zod 69 KB(min), 계약 레지스트리, reference 기능 계약 | +| `route-input-*.js` | 19,703 | 6,228 | TanStack Query | +| `jsx-runtime-*.js` | 8,823 | 3,358 | | +| `react-*.js` | 8,163 | 3,157 | | +| 나머지 6개 | 8,208 | 4,805 | entry 819 B, preload-helper 675 B 등 | +| **합계** | **664,056** | **203,507** | 예산 204,800, 여유 1,293 B(99.4% 사용). brotli는 177,501 B | + +- CSS는 `index-*.css` 1개, 39,758 B raw / 8,592 B gzip이다. 예산에 들어가지 않는다(문서에 명시, `docs/operations/performance-evidence.md:33-34`). +- lazy JS는 14개, 합계 23,521 B gzip이다. 가장 큰 파일은 `use-reference-feature` 8,371 B다(예산 122,880 B). +- 영역 13의 production 프로필 측정(203,513 B)과 일치한다. build id 문자열 길이만큼 다르다. + +**구성(초기 청크, 출처별 단독 gzip 추정).** sourcemap으로 minify된 바이트를 원본 모듈에 나눠 붙이고, 묶음별로 따로 gzip했다. 따로 압축하므로 합은 실제 합계와 조금 다르다(196.5 KB vs 203.5 KB). + +| 출처 | min B | 단독 gzip B | 비고 | +|---|---:|---:|---| +| react-dom + scheduler | 181,623 | 56,456 | | +| react-router | 94,338 | 30,709 | data router(`createBrowserRouter`)와 `useBlocker`를 쓴다(`src/presentation/routes/app-router.tsx:10-12`) | +| zod | 69,240 | 18,441 | 부팅 때 config·manifest 검증에 필요 | +| @tanstack/* | 24,751 | 7,284 | | +| react | 7,923 | 2,989 | | +| 템플릿 `src` 전체 | 271,771 | 80,551 | 그중 `adapters/http` 8,002, i18n 카탈로그 2개 7,384, `features/reference-feature` 5,443, `adapters/service-worker` 3,373 | + +**도달성.** 모듈 그래프(rolldown `getModuleInfo`)에서 엔트리와 엔트리 청크의 dynamic import(`boot.tsx`, `render-boot-failure.tsx`)부터 정적 import만 따라갔다. 2,121개 중 2,102개가 닿는다. 초기 청크에 있으면서 닿지 않는 모듈은 0 B다. "lazy 라우트에서만 쓰는 공용 코드가 rolldown 분할 때문에 초기 청크로 올라왔다"는 가설은 틀렸다. 초기 JS를 줄이려면 `boot.tsx`의 정적 import 그래프 자체를 줄여야 한다. + +**청크 이름.** rolldown은 공용 청크에 안에 든 모듈 하나의 이름을 붙인다. 그래서 `design-system` 청크에 react-router와 HTTP adapter가, `render-boot-failure` 청크에 react-dom이, `reference-feature-runtime-descriptor` 청크에 zod가 들어 있다. 청크 이름만 보고 무엇이 커졌는지 판단하면 틀린다(15-02의 원인 중 하나로 보인다). + +**SW가 꺼져 있어도 SW 코드가 초기 JS에 있다.** 기본 선택은 `null`이다(`src/features/installed-runtime-capabilities.ts:39`). 그래도 `register-service-worker.ts:5`가 page controller를 정적으로 import한다. 런타임 override로 "끈 SW 정리"(`serviceWorkerDisabledCleanup`)를 켤 수 있어서 필요하다(`:33-36`). 약 3.4 KB gzip(단독 추정)이다. 6절 O5에서 다룬다. + +### 2.2 첫 화면 waterfall (lab 프로필) + +조건: `scripts/test-performance.ts`와 같은 throttle(CPU 4배, 지연 40ms, 다운로드 200,000 B/s), 1280×720, 새 context(cold), `vite preview`. 3회 중 run 0을 적는다. 나머지 2회도 ±50ms 안이다. + +``` +0 HTML 응답 끝 (48ms) +59~160 index.js 819 B · preload-helper 675 B · CSS 8,592 B +~200 FCP = 정적 부팅 셸 "불러오는 중" (index.html:13-20) +168 boot + 정적 import 12개 동시 요청 (Vite __vitePreload) +1,277 마지막 JS 도착 (design-system 66 KB). 약 203 KB ÷ 200 KB/s ≈ 1.0초 +1,282 long task 122ms (JS 평가, CPU 4배) +1,404 config.json 요청 → 1,450 도착 ┐ 직렬 +1,462 release-manifest.json 요청 → 1,510 도착 ┘ (composition-root.ts:37-38) +1,585 home-page 청크 777 B 요청 → 1,630 도착 (route-runtime.tsx:21, :26 lazy) +1,660 LCP 후보: "화면을 준비하고 있습니다." (라우트 로딩 표면) +1,916 LCP: H1 "Clean Architecture Frontend" (3회: 1,916 / 1,872 / 1,888ms) +``` + +| 구간 | 시간 | 비율 | +|---|---:|---:| +| HTML·엔트리·CSS | ~170ms | 9% | +| 초기 JS 다운로드 | ~1,110ms | 58% | +| JS 평가 | ~122ms | 6% | +| config → manifest(직렬 2회 왕복) | ~110ms | 6% | +| adapter 생성 → 홈 청크 → 렌더 | ~400ms | 21% | + +- LCP는 lab 예산(2,500ms) 안이다. 가장 큰 항목은 JS 다운로드다. +- `config.json`은 JS 평가가 끝난 뒤에야 요청된다. 두 JSON은 `cache: "no-store"`로 읽는다(`src/bootstrap/read-bounded-boot-json.ts:87`). manifest URL은 config 안에 있어서 직렬이 필요하다(`src/bootstrap/load-release-manifest.ts:229`). +- CLS는 0이다. 정적 셸과 라우트 로딩 표면이 자리를 먼저 잡는다. +- 클릭의 Event Timing 길이는 10회 모두 16ms(관찰 하한)다. 상호작용 111ms의 대부분은 lazy 청크 다운로드와 렌더다. + +### 2.3 라우트 전환 + +같은 throttle. 홈을 cold로 연 뒤 내비게이션 링크를 한 번 누른다. 시간은 페이지 안 시계로 클릭부터 `main h1` 문구가 바뀔 때까지다. 라우트마다 5회. + +| 라우트 | 새로 받은 파일 | gzip B | 중앙값(범위) | +|---|---|---:|---| +| `/examples/platform` | `platform-overview-page`, `server-state` | 5,019 | 110ms (107~114) | +| `/examples/ui` | `ui-gallery-page` | 2,903 | 114ms (106~126) | +| `/examples/states` | `state-gallery-page`, `async-state` | 1,730 | 96ms (92~99) | +| `/examples/auth` | `auth-example-page` | 800 | 80ms (74~88) | +| `/examples/reference-resources` | `context-routes` | 744 | 90ms (80~91) | + +- 모두 200ms 예산의 절반 근처다. 전환마다 왕복 1~2회(지연 40ms)와 렌더가 대부분이다. +- reference-resources는 context 라우트 청크만 받은 시점에 제목이 바뀌었다. 목록 페이지 청크는 측정 구간 안에 요청되지 않았다. 무엇이 그려졌는지는 확인하지 않았다. +- 라우트 hover·focus 프리페치는 없다(`src/`에서 `preload`·`prefetch` 검색 결과는 청크 오류 처리뿐). + +### 2.4 release마다 버려지는 캐시 + +`VITE_BUILD_ID`만 바꾼 두 빌드에서 `boot`(36,852 B), `index`(840 B), `render-boot-failure`(58,494 B)의 파일명이 바뀌었다. 합계 96,186 B gzip, 초기 JS의 47%다. 해시 자산은 `immutable`로 1년 캐시된다(`config/hosting/cache-policy.json:24`). 그래서 코드가 그대로여도 재방문 사용자는 release마다 react-dom을 다시 받는다. CI는 실행마다 다른 build id를 쓴다(`.gitea/workflows/quality-gates.yml:28`). + +원인: build id를 읽는 `src/contracts/env.ts`가 rolldown 분할에서 react-dom과 같은 청크에 들어간다. 지난 영역 13(4.2절, 13-03)이 같은 현상을 기록했고 "목표가 없어 결함으로 보지 않았다". 이번에도 결함으로 세지 않았다. + +변이 실험: `vite.config.ts:77-78`의 `manualChunks`에 react-dom·scheduler를 `vendor-react-dom`으로 보내는 조건 한 줄을 더했다. build id만 바뀐 두 빌드에서 바뀐 파일은 `boot` 36,888 B, `index` 863 B, `render-boot-failure` 3,178 B, 합계 40,929 B였다. react-dom 청크(58,822 B)는 그대로였다. 초기 JS는 203,126 B로 오히려 381 B 줄었다. `tests/unit/build-environment-bundle.test.ts`(이름이 `design-system-`인 청크가 build id와 무관한지 본다, `:72`)와 `bundle-classification.test.ts`는 5/5 통과했다. + +### 2.5 레시피 번들 예산 + +| 레시피 | 측정 / 예산(gzip B) | 여유 | +|---|---:|---:| +| file-transfer | 55,623 / 55,700 | 77 | +| realtime | 40,886 / 40,900 | 14 | +| offline-indexeddb | 36,891 / 36,900 | 9 | +| service-worker-pwa | 9,662 / 10,000 | 338 | + +지난 라운드와 바이트 단위로 같다. 레시피 코드를 조금만 고쳐도 위 세 개는 넘는다. + +### 2.6 테스트 실행 시간 + +**게이트(오케스트레이터 기록, 부하 미기록).** `check:architecture` 10s · `check:types` 6s · `lint` 11s · `test:unit` 13s · `test:component` 8s · `test:integration` 10s · `test:contract` 1s · `test:runtime-schema` 1s · `test:system` 53s(rc=1, 영역 11·13 소관). + +**계층별(이번 실측, 메인 트리).** 시간은 Vitest가 세는 누적값(모든 worker 합)이다. + +| 계층 | 파일 | 벽시계 | 테스트 누적 | import 누적 | setup 누적 | 환경 누적 | +|---|---:|---:|---:|---:|---:|---:| +| unit (`run-vitest.ts`) | 165 | 12.6초 | 80.3초 | 60.4초 | 56.3초 | 4.1초 | +| component | 34 | 7.2초 | 28.8초 | 26.2초 | 11.2초 | 49.9초 | +| integration | 13 | 9.3초 | 19.8초 | 6.3초 | 2.7초 | 0 | + +- unit의 setup 누적 56초는 파일마다 약 0.34초다. `tests/setup.ts:1-2`가 node 환경 파일에도 `@testing-library/jest-dom`과 `@testing-library/react`를 싣는다. +- component의 환경 누적 50초는 jsdom 생성 비용이다(파일당 약 1.5초). +- integration 벽시계 9.3초는 가장 느린 두 파일(각 8.7초)이 정한다. + +**가장 느린 파일 상위 10개(unit 8 + integration 2, 파일 총시간 = 테스트 + import + setup).** + +| 순위 | 파일 | 총시간 | 가장 느린 테스트 | 원인 | +|---:|---|---:|---|---| +| 1 | `tests/unit/security-promotion-staging.test.ts` | 10.9초 | "requires every external…" 5.7초 | 같은 CLI를 환경변수 하나씩 빼며 `node`로 4번 이상 띄운다(`:341`, `:357`) | +| 2 | `tests/integration/security-followup-archive.test.ts` | 8.7초 | 7.7초 | repo 전체를 복사하고 `corepack pnpm build:release-candidate`를 돌린다(`:29-76`) | +| 3 | `tests/integration/provider-guardian-transaction.test.ts` | 8.7초 | "allows exactly one same-kind…" 5.1초 | 실제 파일시스템에서 동시 시작 경쟁을 만든다(`:620-643`) | +| 4 | `tests/unit/ci-workflow-generation.test.ts` | 8.6초 | 0.8초 | 415개 테스트. 일부가 프로세스를 띄운다 | +| 5 | `tests/unit/risk-coverage.test.ts` | 7.5초 | "rejects the historical 14-file summary" 4.9초 | 실제 소스 트리에서 production 모듈 목록을 만든다(`:129-135`) | +| 6 | `tests/unit/service-worker-runtime.test.ts` | 6.8초 | "bounds a stream that never produces a chunk" 5.0초 | 실제 시계로 5초 마감(`ACTIVATION_MARKER_READ_DEADLINE_MS`, `src/adapters/service-worker/service-worker-lifecycle.ts:558`)을 기다린다(`:1907-1923`). 같은 파일의 다른 테스트는 fake timer를 쓴다(`:926`, `:962`, `:1085`) | +| 7 | `tests/unit/browser-rpc/browser-rpc-remediation.test.ts` | 5.9초 | 1.1초 | 테스트 수가 많다 | +| 8 | `tests/unit/fixture-node-modules.test.ts` | 5.7초 | "installs through the linked directory" 5.1초 | 임시 fixture에서 실제 pnpm install | +| 9 | `tests/unit/build-environment-bundle.test.ts` | 5.4초 | 3.6초 | Vite 빌드를 여러 번 한다 | +| 10 | `tests/unit/product-feature-selection-build.test.ts` | 5.3초 | 2.4초 | `VITE_PRODUCT_FEATURES=none` 빌드 | + +- unit에서 프로세스(node CLI, vite, tsc, pnpm)를 띄우는 파일은 16개다. 이 파일들의 테스트 시간 합은 43.7초로 unit 테스트 누적 80.3초의 54%다. +- FE-GATE-005는 `test:unit`을 돌린 뒤 `test:coverage`를 돌린다(`config/ci/gates.json`의 FE-GATE-005 commandIds). coverage 실행은 `tests/unit`을 포함한 278파일을 `--maxWorkers=4`로 다시 돈다(`package.json`의 `test:coverage`). 같은 묶음이 coverage 있이 57.1초, 없이 49.1초였다. unit은 같은 게이트에서 두 번 돈다. + +## 3. 지난 발견 재확인 + +| ID | 상태 | 근거 | +|---|---|---| +| 2026-09-25 FOLLOW-UP P1 초기 JS 예산 | **남음** → 15-01 | 203,507 / 204,800, 여유 1,293 B(지난 1,319 B). 예산(`config/performance/budgets.json:4`)과 게이트 위치(release 단계) 그대로 | +| 2026-09-25 FOLLOW-UP P2 레시피 예산 인상 | **남음** | 2.5절. 여유 77·14·9 B, 지난 라운드와 같다 | +| 2026-09-29 11-04 lab 게이트 판정 뒤집힘 | **코드 남음 / 이번 실측에서는 재현 안 됨** | 부하 가드 없음(`scripts/lib/performance-budgets.ts:35-64`, loadavg는 기록만 `scripts/test-performance.ts:188-191`, `:209`). 락 안 10회: LCP 1,884~1,948ms, 상호작용 105~121ms, 모두 PASS. CPU 경합을 일부러 건 재현은 하지 않았다(영역 11 소관) | +| 2026-09-29 11-05 기능 규모 기준선에 소스 커밋 없음 | **남음**(영역 11 소관) | `config/scale/feature-shape-growth.json` measuredAt 2026-09-27, 커밋 필드 없음. 이번 재측정은 기능당 +3,414~3,906 B다. `config/scale/feature-shape-ceilings.json`은 "about 2.9 KB", "exceeded after a few more"라고 적는다. 실제로는 첫 기능에서 넘는다 | +| 2026-09-29 13 4.2절·13-03 build id가 react-dom 청크를 바꾼다 | **남음**(측정 갱신) | 2.4절. 96,186 B가 release마다 바뀐다. 한 줄 변이로 40,929 B가 된다 | + +## 4. 새 발견 (36.3) + +### 15-01 초기 JS 예산 여유가 1,293 B인데, 넘었는지 보는 검사는 release 단계에서만 돈다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 14, 21, 13, 20, 18 | +| 근거 | 예산 204,800 gzip B(`config/performance/budgets.json:4`). 측정 203,507 B(2.1절). 기능 모양 1개를 넣은 빌드는 207,413 B로 2,613 B 넘는다(1절 실행표). bundle 게이트 FE-GATE-012와 lab 게이트 FE-GATE-026은 `release` stage에만 있다(`config/ci/gates.json:2232-2241`). merge stage(`:2212-2230`)의 어느 게이트에도 `check-bundle`이 없다. merge 게이트 FE-GATE-011은 이미 `build`를 돈다. workflow의 `release_gate` job은 `refs/tags/v*` push 또는 수동 `workflow_dispatch`(stage release 이상)에서만 돈다(`.gitea/workflows/quality-gates.yml:79-92`). 문서는 "첫 기능을 추가하기 전에 아래 숫자를 보고 예산을 정한다"고 적는다(`docs/operations/performance-evidence.md:16-17`). 그 숫자는 틀렸다(15-02) | +| 발생 조건 | 템플릿을 받은 프로젝트가 기능을 하나 추가하는 PR. 또는 템플릿 자체에서 부팅 경로 코드가 1.3 KB gzip 이상 늘어나는 변경 | +| 영향 | PR은 merge 게이트를 통과한다. 몇 PR 뒤 tag를 찍을 때 FE-GATE-012가 실패한다. 어느 PR이 얼마나 늘렸는지는 그때 git 이력을 거꾸로 따라가 찾아야 한다. 결국 예산을 근거 없이 올리기 쉽다. 레시피 예산이 실제로 그렇게 올라갔다(2.5절, FOLLOW-UP P2). 사용자 피해는 아직 없다. lab LCP는 1.9초다 | +| 심각도·우선순위 | Medium · P1 — 피해는 비용과 판단 지연이다. 다만 템플릿을 쓰는 모든 프로젝트가 첫 기능에서 반드시 만나는 차단이다. FOLLOW-UP도 P1로 두었다. 고치는 비용은 작다 | +| 통제·증거 | 목표 M3(merge에서 위반 검출) / 확인 M3(release에서만), merge에서는 M0 · E3(빌드 측정) + E1(게이트 설정) | +| 확실성과 남은 가정 | 바이트 수는 결정적이라 1회 측정했다. 실제 CI에서 release_gate가 도는지는 보지 않았다. 다운스트림 기능이 reference 기능과 비슷한 크기라고 가정했다 | +| 결정의 근거 | 5.1절. 확인한 사실: 예산은 고정 200 KiB, 검사는 release 단계. 기록된 의도: "첫 기능 전에 예산을 정한다". 게이트를 release에 둔 이유는 기록이 없다. 리뷰어 추론: 브라우저가 필요한 lab 게이트와 같이 묶인 것으로 보인다. bundle 검사는 빌드 1.4초 + 계산이라 비싸지 않다 | +| 이해 비용 | 기능을 추가하는 개발자는 merge 녹색만 본다. release 담당자가 원인 PR을 찾아야 한다 | +| 최소 개선 방향 | (1) `check-bundle`을 merge 게이트 FE-GATE-011(`build` 다음)에 넣는다. 추가 비용은 수 초다. (2) 예산을 템플릿 기준선 + 근거 있는 여유로 다시 정하고, 근거를 `performance-evidence.md` 표에 적는다 | +| 대안 비교 | (a) 현상 유지: 첫 기능 뒤 release에서 실패. (b) 예산만 올린다: 당장 녹색이지만 merge에서 못 잡는 구조는 남는다. (c) merge 단계 검사 + 예산 재설정(권장). (d) 고정 예산 대신 "PR당 증가량 상한"(base 대비): 기능 추가는 허용하고 큰 증가만 막는다. base 빌드가 하나 더 필요하다 | +| 단순화의 보존 조건 | release 단계의 `bundle.json` 증거와 fixture(`initial-js-over-budget`, `lazy-chunk-over-budget`, `scripts/check-bundle.ts:48-72`)는 그대로 둔다. 분류 규칙(엔트리 청크의 dynamic import도 초기, `classify-vite-bundle.ts:37`)도 바꾸지 않는다 | +| 비용·부작용 | merge 게이트 시간 수 초. 예산 재설정은 사람이 정해야 한다 | +| 재검토 조건 | field 데이터(FE-GATE-018)가 생겨 p75 LCP로 판단할 수 있으면 예산 근거를 field 기준으로 바꾼다 | +| 완료 기준 | 초기 JS를 예산 + 1 B로 만드는 PR이 merge 게이트에서 실패한다. `performance-evidence.md`의 기준선과 여유가 현재 측정과 같다 | +| 검증 방법 | worktree에서 부팅 경로에 1.3 KB 이상 코드를 넣는 변이 → merge 게이트 명령(`ci:gate FE-GATE-011`)이 실패하는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규(FOLLOW-UP P1 이어짐) | + +### 15-02 `performance-evidence.md`의 기준선·청크 구성·분류 규칙이 현재 빌드와 다르다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 9, 14, 20, 24, 8 | +| 근거 | 문서: "초기 JS 예산의 96%"(`docs/operations/performance-evidence.md:16-17`), 기준선 196,573 B·여유 약 8,200 B(4%)(`:22-23`), "`index` 93.5 KB, `design-system` 65.6 KB, `preload-helper` 28.5 KB(zod 포함)"(`:26-27`), "dynamic import chunk는 lazy다"(`:31-32`). 측정(2.1절): 203,507 B, 99.4%, 여유 1,293 B. `index` 819 B, `preload-helper` 675 B, zod는 `reference-feature-runtime-descriptor` 청크에 있다. 분류기는 엔트리 청크의 dynamic import(`boot`, `render-boot-failure`)도 초기로 센다(`scripts/lib/classify-vite-bundle.ts:9-15`, `:37`). `verify:documentation`은 rc=0이다. 이 검사는 수치를 보지 않는다 | +| 발생 조건 | 다운스트림이 이 문서로 첫 기능 전에 예산을 정할 때 | +| 영향 | "여유 8 KB, 기능 두어 개는 들어간다"로 판단한다. 실제로는 첫 기능에서 넘는다(15-01). 청크 이름별 크기를 보고 줄일 곳을 고르면 엉뚱한 파일을 본다(`index`는 이제 0.8 KB다) | +| 심각도·우선순위 | Low · P2 — 문서 불일치다. 다만 예산을 정할 때 쓰는 유일한 자료라 15-01과 같이 고친다 | +| 통제·증거 | 목표 M1(정확한 기록) / 확인 M1(기록은 있으나 틀림) · E3(빌드 측정과 대조) | +| 확실성과 남은 가정 | 문서 수치는 2026-09-25 측정이라고 적혀 있다. 그 뒤 09-03(엔트리 분리)과 lane 병합으로 청크 구성이 바뀐 것으로 보인다(추론, 커밋 단위로 확인 안 함) | +| 결정의 근거 | 적용 제외 — 오래된 수치를 고치는 문제다 | +| 이해 비용 | 문서를 믿은 사람이 직접 빌드해서 다시 재야 한다 | +| 최소 개선 방향 | 표를 현재 측정으로 바꾸고 측정 커밋을 적는다. 청크 이름 대신 출처(react-dom·react-router·zod·템플릿 src)별로 적는다. 분류 규칙 문장을 분류기와 맞춘다. 가능하면 `check:bundle`이 `bundle.json`에 출처별 합계를 남기고, 문서는 그 파일을 가리킨다 | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 문서 수정. 출처별 합계를 자동화하면 sourcemap 빌드가 한 번 더 필요하다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 문서의 기준선이 `check:bundle` 출력과 수백 바이트 안에서 같고, 측정 커밋이 적혀 있다 | +| 검증 방법 | 문서에 적힌 커밋에서 `check:bundle`을 다시 돌려 비교한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-03 예산이 사용자가 실제로 받는 단위를 재지 않는다 — CSS 제외, lazy는 파일 단위 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 14, 21, 13 | +| 근거 | 초기 예산은 JS만 센다(`scripts/check-bundle.ts:33-37`, 문서 `performance-evidence.md:33-34`). CSS 8,592 B gzip은 렌더를 막는 자원인데 빠진다. 2.2절에서 엔트리와 같은 시점에 받는다. lazy 예산은 파일마다 122,880 B다(`scripts/lib/performance-budgets.ts:17-21`). 라우트 하나가 여러 공용 청크를 끌어와도 합을 보지 않는다. 지금 가장 큰 라우트 비용은 5,019 B다(2.3절). lab 게이트는 라우트 하나(EXAMPLES_PLATFORM)만 잰다(`scripts/test-performance.ts:46`) | +| 발생 조건 | Tailwind 유틸리티나 전역 CSS가 늘 때. rolldown이 라우트 코드를 여러 공용 청크로 쪼갤 때 | +| 영향 | CSS 증가나 라우트 진입 비용 증가가 어떤 게이트에도 걸리지 않는다 | +| 심각도·우선순위 | Low · P3 — 지금 수치는 작다. 늘어날 때 알 수 없는 것이 문제다 | +| 통제·증거 | 목표 M3 / 확인 M0(CSS·라우트 합) · E3 | +| 확실성과 남은 가정 | CSS가 늘어나는 속도는 재지 않았다 | +| 결정의 근거 | CSS를 뺀 이유는 문서에 "들어가지 않는다"고만 있다. 기록된 이유는 없다(확인한 사실). 이유가 따로 있을 수 있다(미확인) | +| 이해 비용 | 낮다 | +| 최소 개선 방향 | `check-bundle.ts`에 초기 CSS gzip 합(엔트리의 `css` 필드)을 별도 예산으로 추가한다. lazy는 "dynamic entry + 그 정적 import 중 초기에 없는 파일"의 합을 라우트 단위로 잰다. 분류기가 이미 manifest를 걷고 있어 수십 줄이다 | +| 대안 비교 | (a) 현상 유지. (b) CSS를 초기 JS 예산에 합친다: 숫자 하나로 단순하지만 JS·CSS 증가를 구분하지 못한다. (c) 별도 예산(권장) | +| 단순화의 보존 조건 | 기존 파일 단위 lazy 예산과 fixture는 그대로 둔다 | +| 비용·부작용 | 예산 숫자 2개를 더 정해야 한다 | +| 재검토 조건 | 라우트별 CSS 분할로 바꾸면 CSS도 라우트 단위로 잰다 | +| 완료 기준 | CSS가 예산 + 1 B면 `check:bundle`이 실패한다. 라우트별 합계가 `bundle.json`에 남는다 | +| 검증 방법 | fixture 2개(CSS 초과, 라우트 합 초과) | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-04 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 10, 20, 14, 23 | +| 근거 | 2.6절. unit의 프로세스 생성 파일 16개가 테스트 누적의 54%(43.7 / 80.3초). integration의 가장 느린 파일이 테스트 안에서 `corepack pnpm build:release-candidate`를 돈다(`tests/integration/security-followup-archive.test.ts:57-76`). `service-worker-runtime.test.ts:1907-1923`은 실제 5초를 기다린다. 같은 파일의 다른 테스트는 fake timer를 쓴다. `tests/setup.ts:1-2`가 모든 파일에 RTL·jest-dom을 싣는다. FE-GATE-005는 unit을 `test:unit`과 `test:coverage`에서 두 번 돈다 | +| 발생 조건 | 개발자가 `test:unit`을 자주 돌릴 때. 코어 수가 적은 CI 러너(누적 시간이 벽시계로 바로 바뀐다) | +| 영향 | 22스레드에서는 unit 12.6초로 작다. 4 worker로 돌리는 coverage 실행은 57초다. 테스트 하나를 고칠 때마다 빌드·pnpm 테스트가 같이 돈다. 빠른 검증과 무거운 검증이 나뉘지 않는다(가이드 10절 "빠른 검증과 배포 전 검증이 구분되는가") | +| 심각도·우선순위 | Low · P3 — 지금 절대 시간은 작다. 테스트가 늘수록 커지는 비용이다 | +| 통제·증거 | 목표 M2(계층 분리) / 확인 M1(`docs/testing/taxonomy.md`의 계층 정의, 실제 배치는 섞임) · E3(실측·변이) | +| 확실성과 남은 가정 | 벽시계 절감은 lean setup만 실측했다(−1.3~2.7초, 세 계층 합산). 나머지 절감은 누적 시간에서 계산한 추정이다. CI 러너 코어 수는 모른다 | +| 결정의 근거 | 리뷰어 추론. 프로세스 생성 테스트는 각각 지난 리뷰의 결함(13-06, 09-02, F-4 등)을 막는 회귀 테스트라 지울 대상이 아니다. 위치(빠른 계층)만 문제다 | +| 이해 비용 | 낮다 | +| 최소 개선 방향 | (1) `tests/setup.ts`에서 DOM 도구를 `typeof document !== "undefined"`일 때만 싣는다(실측: setup 누적 73→19초, 통과·실패 수 동일). (2) SW 5초 테스트를 fake timer + `advanceTimersByTimeAsync(5_000)`로 바꾼다(파일 6.8초 → 약 1.8초 추정). (3) 프로세스를 띄우는 unit 16개 파일을 `tests/scripts`처럼 별도 계층으로 옮기고 같은 merge 게이트에서 돌린다. (4) FE-GATE-005에서 coverage 실행의 junit을 unit 증거로 쓰고 `test:unit` 단독 실행을 뺀다(약 13초) | +| 대안 비교 | (a) 현상 유지: 지금은 견딜 만하다. (b) (1)(2)만: 작은 diff로 CPU 누적을 줄인다. (c) (3)까지: 빠른 계층 벽시계가 가장 느린 일반 파일(약 6초)로 내려갈 것으로 추정한다. 게이트 정의 변경이 필요하다. (4)는 증거 artifact 계약(`artifacts/tests/unit.xml`)을 바꿔야 해서 비용이 가장 크다 | +| 단순화의 보존 조건 | (1) jsdom 파일의 `cleanup`과 jest-dom matcher, 모든 파일의 `vi.useRealTimers()` 복구. (2) 멈춘 스트림이 cancel되고 `onActivate`가 숫자로 끝나는 단언. (3) 옮긴 테스트가 계속 merge 게이트에서 돈다. 어느 게이트에도 빠지지 않는다. (4) 게이트 증거 파일 이름과 실패 검출 | +| 비용·부작용 | (3)(4)는 `config/ci/gates.json`·taxonomy 문서 수정이 필요하다 | +| 재검토 조건 | CI 러너 코어 수와 merge 대기 시간 목표가 정해지면 (3)(4)의 우선순위를 다시 본다 | +| 완료 기준 | `test:unit`에 자식 프로세스를 띄우는 파일이 없다. 실제 시간을 기다리는 테스트가 없다. 계층별 시간이 기록된다 | +| 검증 방법 | 이 문서의 timing reporter 방식(`TestModule.diagnostic()`)으로 전후 비교 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 15-05 `npx vitest`로 돌리면 unit 79건이 실패한다 — 테스트가 실행기의 npm 환경변수를 읽는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 20, 21 | +| 근거 | 같은 파일 `tests/unit/ci-workflow-generation.test.ts`: `npx vitest run …` → 79 failed / 336 passed. `node node_modules/vitest/vitest.mjs run …` → 415 passed. `node scripts/run-vitest.ts run …` → 415 passed. 실패 메시지는 `CI runner npm scope environment invalid`다. 실행 코드가 `process.env`를 직접 검사한다(`scripts/contracts/ci-gates.ts:646-651`, `scripts/lib/package-script-graph.ts:244-250`). `npx`는 `npm_config_*` 변수를 넣는다. `run-vitest.ts`만 그중 일부를 지운다(`scripts/run-vitest.ts:39-47`). 테스트는 `process.env`를 격리하지 않는다 | +| 발생 조건 | `npx vitest`, npm script를 거친 IDE 실행기, 리뷰 지침처럼 `npx vitest`를 쓰는 경우 | +| 영향 | 정상 코드에서 79건이 빨갛다. 원인이 환경이라는 것을 메시지만으로 알기 어렵다. 반대로 CI가 `npm_config_*`를 넣는 실행기로 바뀌면 같은 실패가 게이트에서 난다 | +| 심각도·우선순위 | Low · P3 — 제품 동작과 무관하다. 권장 명령(`pnpm test:unit`)은 통과한다 | +| 통제·증거 | 목표 M2(테스트가 환경을 스스로 고정) / 확인 M1(실행기 스크립트에만 의존) · E3(세 가지 실행 방법 비교) | +| 확실성과 남은 가정 | 어떤 변수가 걸리는지는 `npmDispatchScopeEnvironmentNames` 목록으로 정해진다. 목록 전체는 확인하지 않았다 | +| 결정의 근거 | 적용 제외 — 테스트 격리 누락이다. 실행 코드의 검사(실제 CI에서 npm scope 변수를 거부)는 옳다 | +| 이해 비용 | IDE나 `npx`로 돌린 개발자가 원인을 찾아야 한다 | +| 최소 개선 방향 | 해당 테스트의 `beforeEach`에서 `npm_config_*`를 지우고 `afterEach`에서 되돌리거나, 실행 함수가 환경을 인자로 받게 한다(`validateNpmScopeEnvironment`는 이미 인자로 받는다) | +| 대안 비교 | 적용 제외 | +| 단순화의 보존 조건 | 실제 게이트 실행기의 npm scope 거부는 그대로 둔다 | +| 비용·부작용 | 테스트 수정 몇 줄 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | `npx vitest run tests/unit/ci-workflow-generation.test.ts`가 415/415 통과한다 | +| 검증 방법 | 위 세 가지 실행 방법 비교를 다시 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규(영역 10과 겹칠 수 있다) | + +## 5. 설계 선택 검토 (41절) + +### 5.1 초기 JS 예산: 고정 200 KiB, JS만, gzip level 6, release 단계 + +1. **무엇이 필요한가.** 첫 화면 비용이 기능 추가로 조용히 커지지 않게 막아야 한다. 템플릿 자체에는 사용자 규모 목표가 없다. +2. **지킬 성질.** 첫 화면에 필요한 바이트가 합의한 상한을 넘으면 그 변경이 들어오기 전에 누군가 안다. +3. **현재 보장.** `check-bundle.ts`가 Vite manifest를 걸어 초기 파일을 고르고(`classify-vite-bundle.ts`), gzip 합을 예산과 비교하고, fixture로 판정기를 자가 검사한다(`:48-72`). 엔트리 청크의 dynamic import도 초기로 센다. 09-03 이후 실제 부팅 구조와 맞는 분류다(2.2절 waterfall에서 `boot`가 즉시 요청됨을 확인). **보장하지 않는 것:** merge 전 검출(15-01), CSS와 라우트 합(15-03), 숫자 자체의 근거(일반적인 200 KB 관례 외 기록 없음). +4. **대안.** (a) 현상 유지. (b) merge 단계에서도 같은 검사. (c) base 대비 증가량 상한. (d) lab LCP만 게이트로 두고 바이트 예산은 참고값. +5. **비교.** (b)는 비용 수 초로 15-01을 닫는다. (c)는 기능 추가를 막지 않고 큰 증가만 잡는다. base 빌드가 필요하다. (d)는 사용자가 느끼는 값에 가깝다. 대신 lab 측정이 부하에 흔들리고(11-04) 브라우저가 필요해 merge에 두기 비싸다. +6. **판단(리뷰어 추론).** 바이트 예산은 결정적이고 싸다. merge 게이트에 두기 좋은 신호다. (b)를 먼저 하고, 예산 숫자는 다운스트림이 정한다는 현재 원칙을 유지하되 문서 수치를 고친다(15-02). +7. **재검토 조건.** field p75 데이터가 생기면 바이트 예산의 근거를 field LCP에서 거꾸로 정한다. 기능이 10개를 넘어 초기 JS가 계속 커지면 5.3절의 구조 선택을 다시 본다. + +### 5.2 부팅 순서: 엔트리 → dynamic import boot → config → manifest → adapter → lazy 홈 + +1. **무엇이 필요한가.** 모듈 평가 오류(중복 메시지 키, 라우트 충돌)를 화면에 보여야 한다(`src/bootstrap/main.tsx:3-12`). JS와 config·manifest가 같은 release인지 대조해야 한다(`composition-root.ts:30-33` "Boot phases are explicit so failures can stop before product mount"). +2. **지킬 성질.** 실패는 정적 셸에 멈추지 않고 보인다. release가 섞이면 제품을 마운트하지 않는다. +3. **현재 보장.** 엔트리가 앱 그래프를 dynamic import하고 실패를 잡는다(`main.tsx:14-17`). Vite `__vitePreload`가 boot의 정적 의존 12개를 동시에 요청한다(2.2절, 168ms). config와 manifest는 `no-store`로 차례로 읽는다. manifest URL이 config 안에 있어 직렬이 필요하다. 홈 화면도 lazy다(`route-runtime.tsx:26`). **비용(실측):** 엔트리 → boot 사이 왕복 약 1회(59→168ms), JS 평가 뒤 config·manifest 직렬 약 110ms, 홈 청크 대기 약 45~75ms. 합쳐 LCP 1.9초 중 약 0.25초다. 가장 큰 비용은 구조가 아니라 JS 다운로드(1.1초)다. +4. **대안.** (a) 현상 유지. (b) 엔트리에서 `config.json` 요청을 먼저 시작하고 boot에 넘긴다(엔트리는 여전히 앱 그래프를 import하지 않는다). (c) 첫 라우트 청크를 boot와 같이 미리 받는다. (d) 홈 화면을 정적 import한다. +5. **비교.** (b)는 config 왕복(~46ms)을 JS 다운로드와 겹친다. no-store·크기 제한 읽기·`CONFIG_BUILD_MISMATCH` 대조를 그대로 옮겨야 한다. ``는 `no-store` 요청과 재사용이 맞지 않을 수 있어 두 번 받을 위험이 있다(미확인). (c)는 45~75ms를 줄인다. Vite는 동적 import 대상의 dynamic import를 미리 넣지 않아 플러그인이나 수동 힌트가 필요하다. (d)는 한 hop을 없애지만 초기 JS +777 B다. 지금 여유 1,293 B의 60%다. +6. **판단.** 현재 구조는 실패 표시와 release 대조라는 요구에 맞다. 비용(약 0.25초)은 lab 예산 안이다. 바꾼다면 (b)가 가장 효과 대비 위험이 낮다. 예산 여유가 없는 지금 (d)는 고르지 않는다. +7. **재검토 조건.** lab LCP가 2.2초를 넘거나, field p75 LCP가 생겨 목표를 넘으면 (b)(c)를 먼저 본다. manifest URL을 빌드 시점에 고정할 수 있게 되면 config와 manifest를 병렬로 읽는 안도 다시 본다. + +### 5.3 설치된 모든 기능의 계약을 부팅 때 싣는다 + +1. **무엇이 필요한가.** 라우트·operation·메시지 키 충돌을 부팅 시점에 한꺼번에 검사한다(09-03). 내비게이션과 라우트 표를 처음부터 그린다. +2. **지킬 성질.** 충돌이 있는 조합은 어떤 화면도 마운트하기 전에 실패한다. +3. **현재 보장.** 기능 계약·모듈이 초기 청크에 들어간다(`config/scale/feature-shape-ceilings.json` "every installed feature's contracts and module load at boot", 확인한 사실). 그래서 기능 1개 = 초기 JS +3,414~3,906 B다(이번 측정). 선언 상한은 context당 기능 200개(`src/contexts/reference-context/context-module.ts:10`)다. 같은 기울기면 200개는 초기 JS 약 880 KB다(추정). 문서는 "실질 한계는 초기 JS 예산"이라고 솔직하게 적는다. +4. **대안.** (a) 현상 유지. (b) 계약 중 라우트 표·메시지 키 같은 "충돌 검사에 필요한 최소 정보"만 초기에 두고 zod 스키마·mapper는 라우트 청크로 옮긴다. (c) 충돌 검사를 빌드 시점(`check:registries`)으로 옮기고 런타임은 lazy로만 싣는다. +5. **비교.** (b)는 기능당 초기 증가를 줄일 수 있다(얼마인지는 미측정). 계약을 두 조각으로 나눠 관리해야 한다. (c)는 런타임 검사를 잃는다. 빌드 검사를 우회한 조합(런타임 feature override)이 남는다. +6. **판단.** 템플릿의 현재 목표(기능 수 목표 없음)에서는 (a)를 유지할 수 있다. 다만 "기능 200개"라는 선언 상한과 실질 한계(기능 0개) 사이 간격이 크다. 이 간격을 문서 첫 줄에 두는 것이 최소 조치다. +7. **재검토 조건.** 다운스트림이 기능 10개 이상을 한 앱에 넣는 계획이 생기면 (b)를 측정과 함께 검토한다. + +## 6. 최적화·리팩토링 후보 + +기대 효과는 실측이면 "실측", 계산이면 "추정"으로 적는다. 코드는 고치지 않았다. + +| ID | 무엇을 | 기대 효과 | 위험 | 보존해야 할 동작 | 권고 | +|---|---|---|---|---|---| +| O1 | `vite.config.ts:77-78` `manualChunks`에 react-dom·scheduler → `vendor-react-dom` 한 줄 | release마다 바뀌는 바이트 96,186 → 40,929 B(**실측 −55 KB**). 초기 JS −381 B(실측). 청크 이름이 내용과 맞아진다 | 요청 1개 증가. 청크 이름에 기대는 테스트(13-03)는 이번 변이에서 통과 | build id는 `env.ts` 청크에만. preload-helper 분리. 엔트리가 앱 그래프를 import하지 않음(09-03) | 채택 권고(P3) | +| O2 | `check-bundle`을 merge 게이트 FE-GATE-011에 추가 | 예산 초과를 PR에서 잡음 | 거의 없음 | release `bundle.json` 증거 | 15-01 | +| O3 | 엔트리에서 `config.json` 요청을 먼저 시작 | lab LCP −46ms 전후(추정, 2.2절 config 구간) | no-store·크기 제한 읽기·대조 로직 이동. 엔트리 계약(09-03) | `CONFIG_BUILD_MISMATCH`, 부팅 실패 화면, base path | lab LCP가 목표에 가까워지면 | +| O4 | 첫 라우트 청크 미리 받기 | −45~75ms(추정) | 플러그인 필요. 정적 import로 하면 초기 +777 B | 라우트 lazy 경계, 청크 복구(`chunk-recovery-boundary.tsx`) | 보류 | +| O5 | SW page controller를 dynamic import | 초기 약 −3.4 KB gzip(단독 추정) | 망가진 SW를 정리하는 경로가 청크 요청에 의존하게 된다. 그 상황에서 청크를 못 받을 수 있다 | `serviceWorkerDisabledCleanup` 경로 | **기각** — 복구 경로를 네트워크에 묶는다 | +| O6 | zod → `zod/mini` | 초기 zod 18.4 KB(단독) 중 일부(미측정) | 계약 스키마 전체 API 변경. 오류 메시지 형식 | 런타임 스키마 검증 결과·오류 분류 | 측정 후 판단 | +| O7 | i18n 카탈로그를 라우트별로 분할 | 초기 7.4 KB(단독) 중 lazy 라우트 몫(미측정) | 타입 안전 키, 로케일 전환, lazy 라우트에서 메시지 누락 | 메시지 키 충돌 부팅 검사, `check:i18n` | 보류 | +| O8 | 내비 링크 hover·focus 프리페치 | 전환 80~114ms 중 왕복 1회(~40ms) 정도(추정) | 낭비 요청 | 청크 복구 경계 | 낮은 가치 — 이미 예산의 절반 | +| T1 | `tests/setup.ts`에서 DOM 도구를 DOM 있을 때만 | 세 계층 합산 벽시계 **−1.3~2.7초(실측)**, setup 누적 73 → 19초(실측) | 낮음. 통과·실패 수 동일(실측) | jsdom 파일 cleanup·matcher, 타이머 복구 | 채택 권고(P3) | +| T2 | SW 5초 테스트를 fake timer로 | 파일 6.8 → 약 1.8초(추정) | 낮음 | 멈춘 스트림 cancel, `onActivate` 종료 단언 | 채택 권고(P3) | +| T3 | 프로세스를 띄우는 unit 16개를 별도 계층으로 | unit 누적 −43.7초, 벽시계 12.6 → 약 6~7초(추정) | 게이트 정의 수정 | 같은 merge 게이트에서 계속 실행 | 15-04 | +| T4 | FE-GATE-005의 unit 중복 실행 제거 | 게이트 −약 13초(추정) | 증거 artifact 계약 변경 | `artifacts/tests/unit.xml` 의미 | 보류 | +| T5 | `ci-workflow-generation` 테스트의 환경 격리 | `npx vitest`에서 79건 실패 → 0 | 없음 | 게이트 실행기의 npm scope 거부 | 15-05 | + +**폴더 구조.** 성능 코드 위치는 책임과 맞다. 판정기(`scripts/lib/performance-budgets.ts`), 분류(`classify-vite-bundle.ts`), lab 신뢰 조건(`lab-performance.ts`)이 순수 함수로 떨어져 있고 unit 테스트가 있다(`tests/unit/{performance-budgets,bundle-classification,lab-performance}.test.ts`). 예산 숫자는 한 파일(`config/performance/budgets.json`)이다. 찾기 쉽다. 아쉬운 곳은 두 가지다. 측정 근거 문서(`docs/operations/performance-evidence.md`)의 수치가 생성물이 아니라 손으로 적혀 있어 어긋난다(15-02). 기능 규모 기준선은 `config/scale/`에 따로 있어 같은 "초기 JS" 이야기가 두 곳에 다른 숫자로 있다. + +**테스트가 위험을 잡는가.** 판정기의 경계(예산 +1 B 실패)는 fixture와 unit 테스트가 잡는다. 분류 규칙(엔트리 청크의 dynamic import)도 테스트가 있다(`bundle-classification.test.ts:29`). 잡지 못하는 것은 "언제 도는가"다. merge에서 돌지 않아 예산 초과가 늦게 드러난다(15-01). 변이 실험은 판정기 대신 게이트 위치와 build id 분할에 했다(2.4절). + +## 7. 28개 관점 판정표 + +판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. + +| 번호 | 관점 | 판정 | 한 줄 이유 | +|---|---|---|---| +| 1 | 코드 성숙도 | > | 영역별. 성능 스크립트는 순수 함수와 얇은 CLI로 나뉘어 있다 | +| 2 | 구조적 성숙도 | > | 09 | +| 3 | 변경 용이성 | P | 기능 1개 추가가 초기 JS 예산을 넘긴다(15-01, 5.3) | +| 4 | 인지 부하 | P | 청크 이름이 내용과 다르다(2.1). 분류 규칙이 문서와 다르다(15-02) | +| 5 | 위험 가시성 | P | 예산 99.4%라는 위험이 release 단계에서만 드러난다(15-01). 문서 수치는 96%로 적혀 있다 | +| 6 | 실패 성숙도 | > | 03·06. 부팅 실패 표시 경로는 성능 비용 약 1 왕복(5.2) | +| 7 | 운영 성숙도 | P | lab 증거에 러너·브라우저·throttle·빌드 ID가 남는다. field는 입력이 없어 설계대로 `FAIL_UNVERIFIED` | +| 8 | 디버깅 가능성 | P | `bundle.json`에 파일별 크기는 있으나 출처별 구성은 없다. module inventory는 청크별 모듈 목록을 남긴다(`scripts/lib/vite-module-inventory.ts`) | +| 9 | 유지보수 성숙도 | P | 손으로 적은 성능 수치가 어긋났다(15-02) | +| 10 | 테스트 성숙도 (깊게) | P | 판정기·분류기·lab 신뢰 조건에 unit 테스트가 있다. 빠른 계층에 프로세스 생성·실제 대기가 섞였다(15-04). 실행기에 따라 79건이 실패한다(15-05) | +| 11 | 데이터 성숙도 | - | 이 영역에 저장 데이터가 없다 | +| 12 | 동시성 성숙도 | > | 03·05 | +| 13 | 확장성 (깊게) | P | 기능당 초기 JS +3.4~3.9 KB, 실질 한계 0개 vs 선언 상한 200개. 문서가 한계를 인정한다(5.3). lazy 증가는 기능당 약 4.8~5.1 KB로 작다 | +| 14 | 성능 성숙도 (깊게) | P | lab LCP 1.9초·CLS 0·전환 80~114ms로 예산 안, 조건 기록됨. 초기 JS 99.4%, release 단계 검사(15-01), CSS·라우트 합 미측정(15-03), field 미검증 | +| 15 | 보안 성숙도 | > | 13 | +| 16 | 의존성 성숙도 | > | 13. 성능 관점에서 초기 JS의 57%가 react-dom·react-router·zod·TanStack이다(2.1) | +| 17 | API / Contract 성숙도 | > | 07 | +| 18 | 배포 성숙도 | P | 해시 자산 `immutable` 캐시. build id 때문에 release마다 96 KB가 바뀐다(2.4, 한 줄로 41 KB) | +| 19 | 설정 성숙도 | O | 예산은 한 JSON. lab 포트는 환경변수 + `--strictPort` | +| 20 | 개발자 경험 (깊게) | P | 게이트 시간은 짧다(unit 12.6초). 예산 초과를 늦게 안다(15-01). `npx vitest`에서 79건 실패(15-05). lab 스크립트는 pnpm을 안에서 띄운다 | +| 21 | Guardrail 성숙도 | P | bundle·lab 판정기는 fixture로 자가 검사한다. 위치가 release뿐이다(15-01). CSS·라우트 합은 검사가 없다(15-03) | +| 22 | 추상화 성숙도 | > | 09 | +| 23 | 일관성 | P | `manualChunks`는 build id 연쇄를 막으려고 preload-helper만 뗐다. 같은 이유의 react-dom 청크는 그대로다(2.4). SW 테스트 파일 안에서 fake timer 사용이 섞였다(15-04) | +| 24 | 네이밍 / 의미 성숙도 | P | rolldown 자동 청크 이름이 내용과 다르다(`design-system`에 react-router·HTTP adapter) | +| 25 | 조직 확장성 | > | 12 | +| 26 | Ownership 성숙도 | > | 14. 예산 결정은 다운스트림 몫이라고 문서에 있다 | +| 27 | 삭제 가능성 | > | 14. `VITE_PRODUCT_FEATURES=none` 빌드 테스트가 있다 | +| 28 | 회복 가능성 | > | 06. SW 정리 경로를 lazy로 바꾸지 않는 이유(6절 O5) | + +## 8. 미검증 + +| 항목 | 이유 | 필요한 것 | +|---|---|---| +| Firefox·WebKit lab 수치 | Chromium만 돌렸다 | 같은 스크립트를 다른 엔진으로 | +| 실제 전송 크기(brotli·HTTP/2·CDN) | 정적 호스팅 미실행. brotli는 파일 크기만 계산했다(177,501 B) | 실제 호스팅 응답 | +| field LCP·INP·CLS | 입력 데이터가 없다(설계상 `FAIL_UNVERIFIED`) | 동의 기반 RUM 28일 데이터 | +| CPU 경합 아래 lab 판정 | 락 안에서만 쟀다. 11-04 재현은 영역 11 소관 | busy loop를 건 상태에서 5회 ×5 | +| CI 러너 시간·코어 수 | Gitea 실행 기록을 보지 않았다 | CI 로그 | +| 메모리·장시간 사용(누수) | 이번 범위 밖. browser soak는 영역 11 | soak 실행 | +| O3·O4·O6·O7·T2·T3·T4의 효과 | 계산한 추정이다 | 각 변경 후 같은 방법으로 재측정 | +| reference-resources 전환에서 그려진 화면 | 측정 구간 안에 목록 청크 요청이 없었다 | 스크린샷과 요청 목록 확인 | +| e2e 실행 시간 | 영역 11 소관 | — | diff --git a/docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md b/docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md new file mode 100644 index 00000000..f8404b39 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md @@ -0,0 +1,554 @@ +# 16. 폴더 구조·리팩토링·기능 개발 패턴 + +> 기준 커밋 `d99301b`(`fix/ui-design-audit-2026-11-01`). 이번 라운드에 새로 만든 영역이다. 지난 라운드에는 같은 영역 문서가 없다. +> +> 영역 판정(35.8): **조건부 사용 가능.** 기능 하나를 수직 폴더로 넣고 빼는 구조는 실제로 동작한다. 복사한 기능이 경계 검사(`check:architecture`)와 lint를 그대로 통과했다. 다만 "기능 폴더 하나만 만들면 된다"는 문서 주장은 참조 기능 모양의 기능에서는 성립하지 않는다. 복사 실험에서 기능 폴더 밖 파일 7묶음을 고치고 문서에 없는 결정 2가지를 해야 했다. 절차 문서에 있는 것은 context 선언 하나다(16-01). 매뉴얼과 scaffold는 이 문서 8절의 실제 목록을 기준으로 만들어야 한다. + +## 0. 요약 + +- **복사 실험.** `reference-feature`를 `order-feature`로 복사하고 이름만 바꿨다. 통과까지 막힌 곳이 12번 나왔다(8.1절). 막힌 순서대로 고치면 typecheck·architecture·registries·documentation·i18n·design-system·diagnostics·lint가 모두 통과한다. +- **문서 주장과 실제가 다르다(16-01, Medium).** `starter-experience.md:136-147`은 기능 폴더 밖 수정을 4행으로 적고 "중앙 catalog와 governance는 바뀌지 않는다"고 쓴다. 실제는 기능 폴더 밖 7묶음과 결정 2가지다. 이 주장을 지키는 테스트(`second-api-feature-registries.test.ts`)는 라우트와 무효화가 없는 기능만 넣는다. +- **기능을 하나 추가하면 기능 밖 테스트 4개가 깨진다.** 3개는 "설치된 기능은 참조 기능 하나, 외부 계약 패키지는 0개"를 전제한 단정이다(16-02, Medium). 1개는 라우트마다 수동 a11y 기록을 요구하는 검사다(16-01). 공유 MSW 시나리오 카탈로그는 참조 기능의 operation 3개에 묶여 있다(16-02). +- **샘플이 복제될 패턴 일부를 안 보여 준다(16-04, 16-07).** 샘플 페이지는 URL을 문자열로 8곳에 적고, route 입력을 cast한다. 페이지네이션·낙관적 갱신은 런타임만 있고 기능 예제가 없다. 제품 기능이 반드시 써야 하는 `EXTERNAL_PACKAGE` 계약 기여의 예제도 없다. +- **같은 개념이 두 폴더에 비슷한 이름으로 있다(16-05).** `FeatureBoundary`(presentation)와 `FeatureErrorBoundary`(platform)가 겹쳐 쌓인다. `TelemetryPort`라는 타입이 두 개다. +- **번들.** 참조 모양 기능 하나를 더하면 초기 JS가 4,024 B 늘고, 예산 여유 1,299 B를 넘어 2,725 B 초과가 된다. `check:bundle`이 실패할 값이다(9절, 13·15 영역과 같은 사실). +- 다른 영역이 이미 적은 결함은 다시 세지 않았다. 이 영역 실험이 더한 증거만 2.2절에 적었다(09-06·09-09, 07 영역 P-07-02·P-07-03·07-02·07-03·07-04·07-05, 지난 12-03, 14-03·14-04·14-06). ID 표기: `P-07-xx`는 07 영역이 이어받은 지난 발견, `07-xx`는 이번 07 영역 새 발견이다. + +## 1. 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, `d99301b`. 메인 워킹트리는 이 문서 하나만 썼다 | +| 목적·실행 형태 | 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + Service Worker. SSR 없음 | +| 읽은 코드 | `src/` 최상위 9개 폴더 목록과 파일 목록 전체. `src/features/*.ts`(조립 카탈로그 8개) 전체. `src/features/reference-feature/**` 22개 파일 전체. `src/contexts/**`, `src/apps/**`, `scripts/generate-product-feature-index.ts` 전체. `.dependency-cruiser.json` 규칙 29개. `src/presentation/routes/{route-codecs,route-contract,route-input}.ts*`, `app-router.tsx:330-570`. `src/contracts/{external-contract-runtime,rest-profiles,errors,result}.ts`의 해당 부분. `src/platform/errors/*`, `src/presentation/boundaries/render-error-boundary.tsx`, 두 `telemetry-port.ts`. `scripts/test-sample-removal.ts:1-140`, `scripts/verify-documentation-readiness.ts` 전체 | +| 읽은 문서(주장) | `docs/architecture/layers.md`, `starter-experience.md`, `routing-pages-and-patterns.md` 4·5·8·9·10·11·12절, `frontend-ports-adapters-and-boundaries.md` 3·7·16·21절, `src/features/reference-feature/README.md`, 같은 폴더의 07·09·12·14 영역 문서(중복 확인용) | +| 쓴 스킬 | `codebase-design`(모듈 깊이, 삭제 시험, seam 용어). 리팩토링 후보 판단에 썼다 | +| 실행 | 게이트는 오케스트레이터 결과(`scratchpad/gates/summary.txt`, 11개 게이트 rc=0, `test:system` rc=1)를 썼다. 이 영역 실험은 분리 worktree 2개(`scratchpad/wt-16`, `wt-16b`, `d99301b`, 메인 `node_modules` 링크)에서 `node`, `npx tsc`, `node scripts/run-vitest.ts`, `node_modules/.bin/eslint`만 썼다. pnpm은 부르지 않았다. `check-architecture.ts`는 `pnpm exec eslint`를 부르므로, `exec `만 `node_modules/.bin/`으로 넘기는 shim(`scratchpad/r16/bin/pnpm-exec-shim.mjs`)을 `npm_execpath`로 줬다 | +| 실험 | E: 참조 기능 복사·이름 변경(8.1절). M1: 폼 라우트 경로만 바꿈. M2: context 루트를 기능 라우트 밖으로 바꿈. M3: 기능 `hooks/`·`contracts/` 재수출로 HTTP 어댑터 도달. B: 빌드 2회(참조 기능만 / 두 기능)와 초기 JS 측정 | +| 부하 | 다른 영역 에이전트와 함께 돌았다. 테스트 실행 직전 부하 평균 9~14, 빌드 직전 8.7(참조만), 21.4(두 기능). 이 영역 결론은 실행 시간에 기대지 않는다 | +| 확인하지 못한 것 | `test:coverage`와 `check-risk-coverage`(새 기능에 risk/test-evidence 행이 필요한지), `test:sample-removal --feature=order-feature`(pnpm을 부르므로 worktree에서 금지), e2e·a11y(새 기능 라우트), `check:bundle`(공급망 생성이 `corepack pnpm list`를 부른다. 같은 계산을 직접 했다, 9절), `check:ci` 전체 | +| 지난 리뷰와 비교 | 이 영역은 새로 만들었다. 기능 추가 경로에 걸리는 지난 발견만 2.1절에서 코드로 다시 봤다. 지난 실행 결과는 증거로 쓰지 않았다 | + +## 2. 지난 발견과 다른 영역 발견 + +### 2.1 기능 추가 경로에 걸리는 지난 발견 + +| ID(0929) | 내용 | 상태 | 근거 | +|---|---|---|---| +| 07-03 (07 영역 P-07-03) | 라우트 하나에도 governance allowlist를 고쳐야 하고 문서는 반대로 적는다 | 남음 | `config/contracts/registry-governance.json:44-52`. 실험 E: `check-registries`가 `FE-REG-ROUTE.ORDER_RESOURCE_LIST.searchSchema has unknown value` 등 6줄로 실패 | +| 07-02 (07 영역 P-07-02) | 분류기가 추가 성격 변경(allowlist 확장)을 breaking으로 막는다 | 남음, 범위가 더 넓다 | 실험 E: allowlist 확장이 `FE-REG-ROUTE:$contract:allowedValues:contract-field-changed`로, 새 topic·namespace·edge 추가가 `FE-REG-QUERY-INVALIDATION:invalidation-graph:{topics,namespaces,edges}:field-changed`로 breaking이 된다. 기준선 갱신(`update-registry-baseline.ts`) 뒤 통과 | +| 12-03 | feature 안 layer 폴더 밖 폴더에 경계 규칙이 없다 | 남음 (이번 12 영역도 남음) | 실험 M3: `presentation/*.ts` → `hooks/use-http.ts` → `src/adapters/http/index.ts`, 그리고 `presentation` → `contracts/reexport-http.ts` → 같은 어댑터. `check:architecture` rc=0, eslint rc=0. `feature-and-app-roots-do-not-reach-adapters`는 기능 루트 파일(`src/features//*.ts`)만 본다(`.dependency-cruiser.json` 해당 규칙) | +| 08-06 | 라우트 제목이 세 곳에 따로 있다 | 남음 | 계약 `title: "Reference feature"`(`reference-feature-contract.ts:85`), catalog `"Reference resources"`(`reference-message-catalog.ts:4`), 페이지 `title: "Reference feature"`(`reference-resource-page.tsx:25`). 복사하면 세 곳 모두 따라온다 | +| 10-02 | 플랫폼 테스트가 제품이 바꿀 콘텐츠를 대상으로 쓴다 | 남음, 기능 추가로도 깨진다 | `tests/component/product-feature-switch.test.tsx:24-25`. 기능 추가 쪽은 16-02로 따로 적었다 | +| FOLLOW-UP P1(초기 JS 여유) | 기능 하나가 초기 JS를 약 3KB 늘리는데 여유가 1,319 B | 바뀜 | 9절. 이번 측정: 여유 1,299 B, 참조 모양 기능 하나 추가 시 4,024 B 증가해 2,725 B 초과(13·15 영역 소관) | + +### 2.2 다른 영역 발견에 이 영역 실험이 더한 증거 + +같은 결함을 다시 세지 않는다. 이 영역의 실험 결과만 붙인다. + +| 발견 | 이 영역이 더한 증거 | +|---|---| +| 09-06 기능 라우트와 context 루트 관계를 아무도 검사하지 않는다 | 실험 M2: `CONTEXT_ROUTE_PATH`를 `"reference/*"`로 바꾸고 기능 라우트는 그대로 뒀다. `tsc` rc=0, `check-registries` rc=0, `check-architecture` rc=0, `verify-documentation-readiness` rc=0. 잡은 것은 라우터를 거치는 페이지 테스트뿐이다(`tests/features tests/component tests/unit tests/integration`에서 24개 실패). 새 기능이 페이지 테스트를 복사하지 않으면 아무것도 못 잡는다. 생성기는 `CONTEXT_ROUTE_PATH`를 읽지만(`generate-product-feature-index.ts:322`) 기능 라우트와 비교하지 않는다 | +| 07-04 `TEMPLATE_FIXTURE`를 아무 기능이나 쓸 수 있다 | 실험 E: `fixtureId`까지 이름을 바꾸면 `tsc`가 막는다(`"ORDER_FEATURE_V1"` → `"REFERENCE_FEATURE_V1"` 기대, `external-contract-runtime.ts:220-224`). 이름을 그대로 두면 07 영역 L4처럼 통과한다. 어느 쪽이든 복사한 개발자는 제품용 출처(`EXTERNAL_PACKAGE`) 예제를 찾을 수 없다(16-07) | +| 07-03 zod 어댑터가 참조 기능 안에만 있다 | 실험 E: 복사한 기능은 `zodValidator`를 그대로 한 벌 더 가진다(`order-schemas.ts`). 기능끼리 import가 금지라 다른 방법이 없다 | +| 14-06 `verify:documentation`이 route ID 누락을 "scoped-review evidence"로 보고한다 | 실험 E: 라우트 4개를 더하자 메시지는 `FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)` 한 줄뿐이었다. 누락 ID와 파일은 `artifacts/quality/documentation-review.json`의 `routeScope`에만 있다 | +| 14-03 입구 문서가 실제 폴더를 다 설명하지 않는다 | 이 영역 3절 표가 실제 폴더 역할을 정리했다. 추가로 `frontend-ports-adapters-and-boundaries.md:313-376`의 "권장 목표 디렉터리 구조"(`core/`, `adapters/inbound\|outbound`)는 현재 구조와 다르고 폐기 표시도 없다 | +| 14-04 예제 화면을 지울 수 있다고 적지만 드릴은 참조 기능만 지운다 | 3절 표 `src/presentation/examples` 행. 예제가 두 곳(플랫폼 4개 라우트, 참조 기능)에 있고 제거 계약이 다르다 | +| 09-09 context·feature 오류 경계가 진단을 남기지 않는다 | 16-05: 원인 중 하나가 경계 구현이 두 폴더에 두 벌이라는 점이다 | + +## 3. 폴더 구조 + +### 3.1 최상위 폴더 지도 + +`src/` 최상위는 9개 폴더와 생성 폴더 하나다. "규칙"은 `.dependency-cruiser.json`의 이름이다. + +| 폴더 | 파일 수 | 실제 책임 | 위치가 책임과 맞는가 | 새 개발자가 찾기 쉬운가 | +|---|---|---|---|---| +| `src/application` | 39 | 앱 공통 port(in/out), policy, use case 1개, view model 1개 | 맞다. React·어댑터 import 금지가 강제된다(`application-does-not-know-concrete-runtime`) | 보통. `ports/` 아래 capability별 하위 폴더(`browser-file-storage/` 등)와 단일 파일 port가 섞여 있다. `result.ts`는 소비자 0인 폐기 사본이다(16-05) | +| `src/contracts` | 41 | 계층이 같이 읽는 어휘(오류 레지스트리, 라우트·API·스키마·쿼리 레지스트리 타입, zod facade, 런타임 설정) | 대체로 맞다. "아래 패키지"라서 application·features를 못 읽는다(`contracts-do-not-know-application`) | 어렵다. 41개 파일이 평평하게 있다. 플랫폼 라우트 목록(`routes.ts`)과 인증 프로필(`rest-profiles.ts`)처럼 제품이 고치는 값이 계약 타입과 같은 폴더에 있다 | +| `src/platform` | 30 | 제품 중립 커널: 용량 예산, 오류 봉투, 실행 문맥, 릴리스 복구, 재시도·마감, 트래픽, telemetry 파이프라인, context 라우트 로더 | 대부분 맞다(`platform-kernel-is-product-neutral`). React 오류 경계 3개(`errors/*.tsx`)는 presentation 쪽 `boundaries/`와 같은 개념이다(16-05) | 어렵다. `layers.md` 표에 없다(14-03) | +| `src/presentation` | 73 | React 화면 어댑터: 라우터, 디자인 시스템, 폼, i18n, 템플릿, 공급자, 예제 화면 | 맞다. `presentation/adapters/query`만 TanStack을 쓴다 | 보통. `adapters`라는 이름이 `src/adapters`(외부로 나가는 구현)와 다른 뜻으로 쓰인다(16-05). 예제 화면 4개(`examples/`)가 플랫폼 코드와 같은 층에 있다 | +| `src/adapters` | 145 | 외부로 나가는 구현 16그룹. 배럴(`index.ts`)이 공개 경계 | 맞다. 배럴·커널 예외가 강제된다 | 쉽다. 그룹 이름이 capability 이름이다 | +| `src/bootstrap` | 16 | 조립 루트와 React mount | 맞다 | 쉽다. 다만 `runtime-adapters.ts` 한 파일에 capability 조립이 몰려 있다(09-02) | +| `src/features` | 37 | 기능 수직 폴더 2개 + 조립 카탈로그 8개 | 맞다. 기능끼리 import 금지(`features-do-not-import-other-features`) | 보통. 카탈로그 파일(`installed-*.ts`)과 기능 폴더가 같은 층에 섞여 있다. 카탈로그는 "손대지 않는 파일"인데 이름만으로는 알 수 없다 | +| `src/contexts` | 2 | bounded context 선언(앱 소속, 라우트 루트, 기능 예산) | 맞다 | 보통. 기능 라우트가 이 루트 밑에 있어야 한다는 규칙이 없다(09-06) | +| `src/apps` | 3 | 배포 앱 선언 | 맞다 | 쉽다 | +| `src/.generated` | 3 | 생성기 출력(기능·context·앱 인덱스). git 무시 | 맞다 | 첫 실행 전에는 없다. 모든 스크립트가 생성기를 먼저 부른다 | + +### 3.2 기능 폴더 안 + +참조 기능 22개 파일 1,919줄의 폴더별 크기는 `contracts` 891 · `presentation` 627 · `application` 208 · `adapters` 133 · `domain` 14다. + +| 폴더 | 담긴 것 | 판단 | +|---|---|---| +| `domain/` | 불변 모델 1개와 생성 함수 | 맞다. 14줄이다. 문서도 "도메인 규칙이 없으면 억지로 만들지 않는다"고 적는다(`frontend-ports-adapters-and-boundaries.md:1058-1059`) | +| `application/` | input port(`ReferenceFeatureInput`), output port(`ReferenceGateway`), use case 팩토리, 기능 오류 어휘(런타임 소비자 0, 07-05) | 맞다. 다만 뷰 모델(`ReferenceResourceView`)과 뷰 변환(`toReferenceView`)을 `contracts/`에서 가져온다 | +| `contracts/` | 계약 메타데이터(라우트·V2 operation·스키마 메타·무효화), V3 HTTP 기여, zod 스키마와 zod 어댑터, DTO→도메인 mapper 두 벌, 뷰 모델, 화면 문구 catalog | 넘친다. 폴더 이름은 "와이어 계약"인데 화면 문구와 뷰 모델까지 담는다. 이 폴더에는 어댑터 import 금지 규칙도 없다(12-03). 16-06 | +| `adapters/` | HTTP binding, gateway, 조립 기여(`needs`) | 맞다 | +| `presentation/` | 라우트 runtime 표, 쿼리·뮤테이션 hook, 실패 행동 hook, 폼 스키마·명령 mapper, 페이지 4개 | 맞다. 라우트 경로를 문자열로 다시 적는다(16-04) | +| 루트 | `feature-module.ts`(선언 헤더 + 모듈), `context-routes.ts`(지연 라우트), `README.md` | 맞다. 생성기가 읽는 이름이 고정이다 | + +### 3.3 흩어진 개념과 갈라진 사본 + +| 개념 | 위치 | 판단 | +|---|---|---| +| 기능 렌더 실패 경계 | `src/presentation/boundaries/render-error-boundary.tsx:98-101`의 `FeatureBoundary`, `src/platform/errors/feature-error-boundary.tsx`의 `FeatureErrorBoundary` | 갈라진 사본. 라우터가 둘을 겹쳐 쌓는다. 16-05 | +| telemetry port | `src/application/ports/telemetry-port.ts:5`(이벤트 이름+속성), `src/platform/telemetry/telemetry-port.ts:10`(봉투) | 의도된 두 파이프라인이다(`runtime-adapters.ts:323-325, 576-577`). 같은 이름이 문제다. 16-05 | +| `Result` | `src/contracts/result.ts`(정본), `src/application/result.ts`(폐기 재수출, 소비자 0) | 지울 사본. 16-05 | +| 실패 어휘 | `AppFailure`(`contracts/errors.ts`), `AppError`(`platform/errors/app-error.ts`) | 07-05 | +| zod 어댑터 | `reference-schemas.ts:88`(기능 안) | 07-03. 기능마다 복사된다 | +| 예제 화면 | `src/presentation/examples/*`(플랫폼, 제거 경로 없음), `src/features/reference-feature`(제거 드릴 있음) | 14-04 | +| 참조 기능이 소유하는 기능 폴더 밖 경로 | `scripts/test-sample-removal.ts:47-96`의 `SAMPLE_EXTRAS`: 경로 26개(타입 fixture 16, e2e 3, 규모 측정 4, `tests/mocks` 전체, 테스트 2)와 CI 스크립트 10개 | 수직 폴더가 실제로는 한 폴더가 아니다. 손 목록으로 관리된다. 16-02 | + +## 4. 새 발견 (36.3) + +### 16-01 기능 추가 절차 문서는 폴더 밖 수정을 4행으로 적지만, 참조 모양 기능은 폴더 밖 7묶음과 결정 2가지가 더 필요하다 — 이 주장을 지키는 테스트는 라우트·무효화 없는 기능만 넣는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 3, 20, 4, 21, 25, 9 (+30.3, 30.8) | +| 근거 | 주장: `docs/architecture/starter-experience.md:136-147` 표는 `src/.generated/*`, `src/contexts//context-module.ts`, `config/runtime/.json`, `src/bootstrap/runtime-adapters.ts`(indexedDb일 때)만 적고, "central catalogs ... and the registry governance file do not change"라고 쓴다. 검증 테스트: `tests/unit/second-api-feature-registries.test.ts:11-15`는 "governance, composers and the registry baseline stay as they are"를 주장하지만 넣는 기능은 `routes: {}`(`:38, :106`), 무효화 없음(`:70`)이다. `two-feature-install-typecheck.test.ts`는 라우트 기능을 넣지만 app typecheck만 돌린다. 실행(실험 E, 8.1절): 참조 기능을 복사해 이름만 바꾸자 다음을 고치거나 정해야 했다(①②③④⑤⑧⑨는 기능 폴더 밖 파일, ⑥⑦은 결정) — ① `src/contexts/order-context/context-module.ts`(문서에 있음) ② `config/contracts/registry-governance.json:44-52`(P-07-03) ③ `config/contracts/registry-baseline.json`·`.approval.json` 갱신 또는 `registry-change-evidence.json` 항목(P-07-02) ④ `README.md:273-274`와 `docs/accessibility/manual-checklist.md:7-9`에 route ID(`verify-documentation-readiness.ts:18-21, 81-97`) ⑤ `artifacts/tests/a11y-manual/.md` 라우트마다(`tests/unit/manual-a11y-evidence.test.ts:88-93`, `test:unit` 실패) ⑥ 인증 프로필: 새 이름이면 `src/contracts/rest-profiles.ts`, 아니면 `REFERENCE_EXTERNAL_BEARER` 재사용(16-03) ⑦ 계약 출처: `TEMPLATE_FIXTURE` 대신 `EXTERNAL_PACKAGE`(07-04, 16-07) ⑧ `tests/mocks/scenarios/catalog.ts`(복사한 테스트의 test typecheck 실패, 16-02) ⑨ 전역 상태를 단정하는 테스트 3개(16-02) | +| 발생 조건 | 라우트·API·쿼리 무효화를 가진 기능, 곧 참조 기능 모양의 기능을 추가할 때. 템플릿이 권하는 경로다 | +| 영향 | 문서만 믿은 개발자는 ① 말고 8가지를 실패 메시지에서 거꾸로 찾는다. 실험에서 opaque 오류가 3번 나왔다(`REST security profiles are incoherent.`, `FAIL_UNVERIFIED (canonical scoped-review evidence is incomplete)`, `Cannot read properties of undefined (reading 'includes')`). ②③④⑤는 템플릿 소유 파일이라 제품마다 같은 곳이 동기화 충돌이 된다(지난 14-03, 이번 14 영역 3.4절). scaffold가 문서 표를 기준으로 만들어지면 생성 직후 게이트가 실패한다 | +| 심각도·우선순위 | Medium · P2 — 기능이 잘못 동작하지는 않는다. 모든 기능 추가에서 비용이 반복되고, 다음 단계(매뉴얼·scaffold)의 입력이 틀린다. 이 문서 8절이 실제 목록을 주므로 매뉴얼 작성은 막히지 않는다 | +| 통제·증거 | 목표 M3(기능 폴더 밖 수정 목록이 검증된다). 확인: 문서 M1(틀린 주장), 테스트 M3(좁은 모양만) · E3(실험 E) | +| 확실성과 남은 가정 | ①~⑨는 실행으로 확인했다. `config/testing/risk-coverage.json`·`test-evidence.json`에 새 기능 행이 필요한지는 `test:coverage`를 안 돌려서 미확인이다. e2e·a11y 게이트(새 라우트의 수동 증거 서명)도 안 돌렸다 | +| 결정의 근거 | 확인한 사실: 생성기와 composer는 실제로 기능 폴더 밖 수정 없이 기능을 조립한다(카탈로그 8개는 안 고쳤다). 막힌 곳은 모두 조립 밖의 "증거·거버넌스·테스트 하네스"다. 기록된 의도: 09-07(F-3)은 "API 기능 추가에 폴더 밖 수정이 없어야 한다"를 목표로 했다. 리뷰어 추론: 목표를 검증하는 테스트가 가장 단순한 모양을 골라서, 라우트·무효화가 만드는 수정이 검증 밖에 남았다 | +| 이해 비용 | 기능 작성자가 생성기 규칙, governance allowlist, 기준선 승인 절차, 문서 route scope, 수동 a11y 기록 형식, 인증 프로필 표, 계약 출처 규칙, MSW 시나리오 카탈로그를 따로 알아야 한다. 이 중 문서 "Adding a feature"에 있는 것은 생성기 규칙뿐이다 | +| 최소 개선 방향 | (1) `starter-experience.md` 표를 실제 목록으로 고치고 각 행에 "어느 검사가 실패하는가"를 붙인다(이 문서 8.2절 표). (2) `second-api-feature-registries.test.ts`가 넣는 기능에 라우트 1개와 무효화 topic 1개를 더한다. 지금은 이 테스트가 ②③에서 실패해야 맞다. 고칠지(P-07-03·P-07-02), 문서에 "바뀐다"고 적을지 정한다 | +| 대안 비교 | (a) 문서만 고친다: 싸다. 테스트가 좁은 모양을 계속 증명한다. (b) 테스트 모양을 넓힌다: 실패가 먼저 드러나고, 고친 뒤에는 회귀를 막는다. (c) scaffold가 ②~⑤를 같이 생성한다: 템플릿 소유 파일을 제품이 계속 고친다는 사실은 그대로다. (a)+(b) 권장. ②③은 07 영역 개선(P-07-03 allowlist 제거, P-07-02 추가 분류)을 따르면 목록에서 빠진다 | +| 단순화의 보존 조건 | 기능 하나를 지우면 전부 사라지는 성질(`test:sample-removal`)을 유지한다. route scope 문서 검사(14-06)와 수동 a11y 기록 검사는 없애지 않고 위치만 기능 쪽으로 옮길 수 있는지 본다 | +| 비용·부작용 | (b)는 테스트 하나 수정. 고치지 않고 문서만 바꾸면 "중앙 파일이 바뀐다"를 공식화하게 된다 | +| 재검토 조건 | governance allowlist가 기능 기여로 바뀌거나(P-07-03), 수동 a11y 기록을 기능 폴더로 옮길 때 | +| 완료 기준 | 문서 표가 실험 E의 ①~⑨를 모두 담는다(고친 뒤 사라진 항목은 빼고). 라우트·무효화가 있는 두 번째 기능을 넣는 테스트가 머지 게이트에 있다 | +| 검증 방법 | 실험 E를 다시 한다(8.1절 절차). 또는 넓힌 `second-api-feature-registries.test.ts`가 문서 표와 같은 결과를 낸다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-02 기능 하나를 추가하면 무관한 테스트 3개가 깨지고, 공유 MSW 시나리오 카탈로그는 참조 기능 operation 3개에 묶여 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 10, 3, 25, 27, 20, 8 (+30.5) | +| 근거 | 실험 E에서 `order-feature`를 넣고 빠른 계층을 돌렸다(부하 9~11). 실패: ① `tests/features/reference-feature/installed-context-routing.test.ts:9` — context 목록이 정확히 `["reference-context"]`이기를 기대한다. ② `tests/component/product-feature-switch.test.tsx:24-25` — `FEATURE_ID = INSTALLED_PRODUCT_FEATURE_IDS[0]`(정렬 첫 기능)을 끄고 `ROUTE_REGISTRY.REFERENCE_RESOURCE_LIST`를 확인한다. `order-feature`가 앞에 정렬되면 깨진다. ③ `tests/runtime-schema/release-manifest.test.ts:53` — 매니페스트 fixture가 `contractSet.packages: []`로 고정이다. 제품 기능은 `EXTERNAL_PACKAGE`가 필수라서 첫 제품 HTTP 기능이 `CONTRACT_SET_PACKAGE_MISSING`으로 깬다. (같은 실행에서 `tests/unit/manual-a11y-evidence.test.ts:88-93`도 ENOENT로 실패했다. 이것은 의도된 증거 요구라서 16-01 ⑤로 센다.) 하네스: `tests/mocks/scenarios/catalog.ts:42-47`의 `HttpScenarioOperationId`가 참조 operation 3개 리터럴이고, 바이트 한도 같은 사실도 operation 이름으로 분기한다(`:74-83`). 복사한 테스트는 test typecheck에서 실패하고(`order-resources.ts(106,7)` 등 8건), 실행하면 `TypeError: Cannot read properties of undefined (reading 'includes')`(`catalog.ts:431`)로 끝난다. 제거 드릴은 `tests/mocks` 폴더 전체를 참조 기능 소유로 지운다(`scripts/test-sample-removal.ts:60`) | +| 발생 조건 | 기능을 하나 더 넣을 때(①②), 첫 외부 계약 패키지를 넣을 때(③), 새 기능 테스트가 MSW 시나리오를 쓸 때(하네스) | +| 영향 | 기능 작성자가 자기 기능과 무관한 테스트를 고쳐야 머지할 수 있다. ①②는 고치는 방법이 "기대값에 내 기능을 추가"라서 기능이 늘수록 같은 파일이 충돌한다. ③은 템플릿의 플랫폼 테스트가 "제품 HTTP 기능 0개" 상태에서만 통과한다는 뜻이다. 하네스가 참조 기능 모양이라 새 기능은 MSW 시나리오를 재사용하지 못하고 카탈로그를 고치거나 따로 만든다 | +| 심각도·우선순위 | Medium · P2 — 제품 동작 결함은 아니다. 기능 추가마다 반복되는 비용이고, 원인을 찾기 어려운 실패 문구가 섞여 있다 | +| 통제·증거 | 목표 M3(기능 추가가 다른 기능 테스트를 깨지 않는다). 확인 M0(그런 검사 없음, 오히려 반대 전제) · E3(실험 E 실행) | +| 확실성과 남은 가정 | 3건은 실행으로 확인했다. e2e(`tests/e2e/reference-*.spec.ts`)와 `tests/platform`은 돌리지 않았다 | +| 결정의 근거 | 확인한 사실: ①②는 "설치된 기능 = 참조 기능 하나"를 전제한 단정이다. ③은 매니페스트 fixture를 손으로 적어서 설치 집합과 따로 논다. 리뷰어 추론: 참조 기능이 유일한 기능일 때 쓴 테스트라 전역 상태를 단정해도 통과했다 | +| 이해 비용 | 새 기능 작성자가 `reference-context`·첫 정렬 기능·빈 계약 집합이라는 세 가지 숨은 전제를 실패 메시지로 거꾸로 찾아야 한다 | +| 최소 개선 방향 | ① 참조 테스트는 "목록에 `reference-context`가 있다"로 바꾼다. ② 첫 기능 대신 `REFERENCE_FEATURE_ID`를 쓴다(참조 기능이 없으면 skip은 제거 드릴이 이미 처리한다). ③ fixture의 `packages`를 `EXPECTED_CONTRACT_SET_PACKAGES`에서 만든다. 하네스: 시나리오 사실(바이트 한도·명령 여부)을 설치된 V3 descriptor에서 읽고, operation ID 타입을 문자열로 넓힌다. 참조 기능 전용 handler는 `tests/features/reference-feature/` 쪽으로 옮긴다 | +| 대안 비교 | (a) 현상 유지: 기능마다 이 4곳을 고친다. (b) 위 최소 개선: 테스트 3개 + 카탈로그 1개 수정. (c) 하네스를 기능별로 분리하고 공통부만 남긴다: (b)보다 크고, `test-evidence.json`의 시나리오 증거 경로도 바뀐다. (b) 권장 | +| 단순화의 보존 조건 | ①②가 지키던 동작(참조 라우트가 context로 지연 로드된다, 기능을 끄면 메뉴와 딥링크가 모두 막힌다)은 그대로 검사한다. HTTP 시나리오 증거(`test:http-scenario-evidence`)의 범위는 줄이지 않는다 | +| 비용·부작용 | 작다. 카탈로그 일반화는 `tests/integration/http-scenario-catalog.test.ts`와 같이 바꿔야 한다 | +| 재검토 조건 | 템플릿이 두 번째 샘플 기능을 넣을 때 | +| 완료 기준 | 실험 E처럼 두 번째 기능을 넣어도 ①~③이 통과한다. 새 기능 테스트가 카탈로그를 고치지 않고 MSW 시나리오를 쓴다 | +| 검증 방법 | 실험 E의 `order-feature`를 넣은 상태로 `tests/features tests/component tests/runtime-schema`를 돌린다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-03 유일한 bearer 인증 프로필 이름이 `REFERENCE_EXTERNAL_BEARER`이고, 틀리게 쓰면 어느 operation인지 말하지 않는 오류가 모든 게이트에서 난다 + +| 필드 | 내용 | +|---|---| +| 성격 | 확인된 결함 | +| 관련 관점 | 24, 8, 27, 20, 3 | +| 근거 | `src/contracts/rest-profiles.ts:61-62`의 인증 프로필은 `REFERENCE_EXTERNAL_BEARER`(bearer)와 `ANONYMOUS` 둘이다. 세션이 필요한 제품 기능은 이 이름을 쓰거나 템플릿 소유 파일에 프로필을 더해야 한다. 프로필이 없거나 조합이 틀리면 `resolveRestSecurityProfiles`가 6개 조건을 한 번에 보고 `"REST security profiles are incoherent."`만 던진다(`:292-305`). 이 검사는 `installed-feature-contracts.ts:44`에서 모듈 로드 때 돌므로, 실험 E에서 `check-architecture`·`check-registries`·`check-i18n`·`check-design-system`·`check-diagnostics`·`verify-documentation-readiness`가 같은 스택으로 모두 실패했다. 제거 드릴의 잔여 검사 정규식(`/REFERENCE_RESOURCE\|reference-feature\|reference-resource/i`, `test-sample-removal.ts:95`)은 이 이름을 잡지 않으므로 샘플을 지운 제품에도 남는다 | +| 발생 조건 | 참조 기능을 복사해 `REFERENCE`를 바꿀 때. 제품이 인증 프로필을 하나 더 만들 때 | +| 영향 | 제품 코드가 지워진 샘플의 이름을 계속 쓴다. 첫 실수 때 원인 operation·프로필 ID 없이 모든 검사가 멈춘다 | +| 심각도·우선순위 | Low · P2 — 기능 실패는 아니고 이름과 진단 비용이다. 고치는 비용이 작아서 P2 | +| 통제·증거 | 프로필 검증 자체는 M4(모듈 로드에서 거부). 오류 설명은 M0 · E3(실험 E) | +| 확실성과 남은 가정 | 실행으로 확인했다. 제품 repo가 이 이름을 쓰는지는 보지 않았다 | +| 결정의 근거 | 적용 제외 — 이름 변경과 오류 문구 보강이다. 프로필 구조를 바꾸는 선택이 아니다 | +| 이해 비용 | 복사한 개발자가 스택 트레이스에서 `rest-profiles.ts`를 열고 6개 조건을 하나씩 대조해야 한다 | +| 최소 개선 방향 | (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 한 릴리스 동안 옛 이름을 별칭으로 둔다(레지스트리 baseline 변경 증거 필요). (2) 오류에 `operationId`, `authProfileId`, 깨진 조건을 넣는다 | +| 대안 비교 | 적용 제외 — 단순 결함 수정 | +| 단순화의 보존 조건 | 적용 제외 | +| 비용·부작용 | 프로필 이름은 FE-REG-API 행에 있으므로 baseline 변경 증거가 필요하다. 제품은 이름을 바꾸거나 별칭 기간에 옮긴다 | +| 재검토 조건 | 적용 제외 | +| 완료 기준 | 템플릿 소스에 `REFERENCE_EXTERNAL_BEARER`가 별칭 한 줄 외에 없다. 틀린 프로필로 실험 E를 하면 오류에 operation ID가 보인다 | +| 검증 방법 | 실험 E의 ⑥ 단계를 다시 한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-04 샘플 페이지가 라우트 경로를 문자열로 8곳에 다시 적고 route 입력을 cast한다 — 문서가 권하는 URL builder와 route별 타입이 기능 쪽으로 오지 않는다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 3, 23, 24, 22, 4 (+30.5) | +| 근거 | 경로 정본은 계약의 `routes[*].path`다(`reference-feature-contract.ts:75-128`). 페이지는 같은 경로를 문자열로 다시 적는다: `reference-resource-page.tsx:32, 66`, `reference-resource-detail-page.tsx:24`, `reference-resource-form-page.tsx:74, 114, 161`, `reference-resource-status-page.tsx:21`, `use-reference-failure-action.ts:7`. URL builder `buildRouteUrl`(`src/presentation/routes/route-codecs.ts:45`)은 라우터(`app-router.tsx:213`)와 테스트 하나만 쓴다. route 입력 타입은 `params`·`search`가 `Record`이다(`route-contract.ts:5-9`). 그래서 샘플은 `routeInput.search as ReferenceListFilters`(`use-reference-feature.ts:120`)와 `String(route.params.resourceId)`(`reference-resource-detail-page.tsx:15`)로 cast한다. 문서는 "navigation link도 codec 기반 builder를 사용한다", "page에서 cast하지 않는다"고 적는다(`routing-pages-and-patterns.md` 4.2절, 10절 4단계). 실험 M1: 계약에서 폼 경로만 `/new` → `/create`로 바꾸면 tsc는 통과하고, 페이지 테스트 14개가 실패한다(테스트도 경로를 문자열로 적는다) | +| 발생 조건 | 기능 라우트 경로를 바꿀 때. 샘플을 복사해 새 기능을 만들 때 | +| 영향 | 샘플을 복사한 기능은 경로를 세 곳(계약, 페이지, 테스트)에 적는 습관을 가져간다. 경로를 바꾼 뒤 링크가 남으면 사용자는 `NOT_FOUND`를 본다. 샘플은 라우터를 거치는 페이지 테스트가 있어 잡았지만(M1), 복사한 기능이 그런 테스트를 빼면 아무것도 못 잡는다 | +| 심각도·우선순위 | Low · P2 — 지금 결함은 없다. 복제되는 샘플이 문서와 반대 패턴을 보여 준다(30.5) | +| 통제·증거 | 목표 M4(라우트 ID로만 링크를 만들고 타입이 맞지 않으면 컴파일 실패). 확인 M1(문서) · E3(M1 실험) | +| 확실성과 남은 가정 | 8곳은 grep으로 셌다. 기능 presentation이 `route-codecs.ts`를 import할 수 있는지는 규칙상 허용이다(generic presentation 목록 제한은 `src/presentation/` 아래만 본다). 순환 의존이 생기는지는 시험하지 않았다 | +| 결정의 근거 | 확인한 사실: `ParsedRouteInput`이 route별 타입을 버리는 것은 라우터가 런타임 표에서 codec을 찾기 때문이다. 기록된 의도: README는 "page는 좁은 `useRouteInput` 경계만 사용해 순환 의존을 피한다"고 적는다(`reference-feature/README.md` 4번째 문단). 리뷰어 추론: 순환을 피하려고 기능이 자기 codec·경로를 직접 쓰는 대신, 타입과 builder까지 포기했다 | +| 이해 비용 | 페이지 작성자가 search 타입을 hook 안의 cast로만 안다. 경로를 바꾸는 사람은 계약·페이지·테스트를 grep으로 찾아야 한다 | +| 최소 개선 방향 | 기능 `presentation/`에 자기 계약과 codec만 쓰는 작은 헬퍼 두 개를 둔다: `referenceRouteUrl(routeId, input)`(계약 `path`와 기능 codec으로 만든다)과 `useReferenceRouteInput()`(codec 출력 타입으로 좁힌다). 둘 다 기능 안 파일만 import하므로 라우터를 역참조하지 않는다. 샘플 8곳을 바꾼다 | +| 대안 비교 | (a) 현상 유지. (b) 위 기능 로컬 헬퍼: 순환 없음, 기능마다 30줄 안팎 복사. (c) 플랫폼 `buildRouteUrl`을 route ID로 타입 좁힘: 모든 기능이 한 함수를 쓰지만 기능 → 설치 카탈로그 의존이 생긴다. (b) 권장. 기능이 늘어 복사가 문제면 (b)의 생성기를 `defineFeatureRoutes` 같은 플랫폼 함수로 올린다 | +| 단순화의 보존 조건 | 라우터의 parse 경계와 canonical redirect(`app-router.tsx:213`)는 그대로다. URL 직렬화는 parse와 같은 codec을 쓴다 | +| 비용·부작용 | 샘플 5개 파일 수정. 기능 작성자가 알 개념이 하나 는다(헬퍼) | +| 재검토 조건 | 라우터가 route별 타입을 유지하는 API로 바뀔 때 | +| 완료 기준 | 기능 presentation에 `"/examples/` 문자열이 없다. cast 두 곳이 없다 | +| 검증 방법 | M1 실험을 다시 한다: 계약 경로만 바꿔도 링크가 따라오고 페이지 테스트가 통과한다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-05 같은 개념이 두 폴더에 비슷한 이름으로 있다 — 기능 오류 경계 두 벌이 겹쳐 쌓이고, `TelemetryPort` 타입이 둘이고, 소비자 없는 폐기 사본이 남아 있다 + +| 필드 | 내용 | +|---|---| +| 성격 | 구조적 위험 | +| 관련 관점 | 24, 23, 4, 2, 9, 27 | +| 근거 | ① 경계: `FeatureBoundary`(`src/presentation/boundaries/render-error-boundary.tsx:98-101`, incident id 발급·`onRenderFailure` 보고)와 `FeatureErrorBoundary`(`src/platform/errors/feature-error-boundary.tsx`, 보고는 선택 `onError`)가 따로 있다. 라우터는 context 라우트에서 `ContextErrorBoundary > FeatureErrorBoundary`(`app-router.tsx:466, 519`, `onError` 없음) 안에 `RegisteredRoute`를 넣고, 그 안에서 다시 `FeatureBoundary`(`:396-397`)를 쓴다. 09-09가 적은 진단 누락은 바깥 벌 쪽이다. ② `TelemetryPort`가 두 타입이다: `src/application/ports/telemetry-port.ts:5`(`emit(eventName, attributes)`)와 `src/platform/telemetry/telemetry-port.ts:10`(`emit(event)`). 의도된 두 파이프라인이지만 같은 이름이라 자동 import가 틀린 쪽을 고를 수 있다. ③ `adapters`가 `src/adapters`(외부로 나가는 구현)와 `src/presentation/adapters/query`(화면 쪽 TanStack 바인딩)에서 다른 뜻이다. ④ `src/application/result.ts`는 `@deprecated` 재수출이고 소비자가 0이다(grep). 제거 조건과 담당이 없다. 샘플은 폐기 별칭 `ApiFailure`(`contracts/errors.ts:137-143`, 제거 조건 "grep에서 이 줄만")를 `reference-error.ts:5`, `reference-feature-api.ts:11`에서 쓴다. 폐기 별칭에 lint가 없다는 점은 07-01(F-07-07 흡수)이 센다. 이 항목은 복사될 샘플이 폐기 이름을 퍼뜨린다는 점만 본다 | +| 발생 조건 | 경계·telemetry·결과 타입을 찾거나 고칠 때. 샘플을 복사할 때 | +| 영향 | 기능 렌더 실패가 어느 경계에서 잡히고 무엇이 보고되는지 두 파일을 같이 읽어야 안다. 한쪽만 고치면 다른 쪽과 계약이 갈린다(09-09가 그 결과다). 폐기 사본은 새 개발자에게 "어느 쪽이 정본인가"를 묻게 한다 | +| 심각도·우선순위 | Low · P3 — 지금 오동작은 09-09로 따로 센다. 이 항목은 이름·위치 비용이다 | +| 통제·증거 | M0(이름 충돌을 막는 수단 없음) · E1 | +| 확실성과 남은 가정 | 소비자 수는 grep으로 셌다. 두 경계의 중첩 순서는 코드로 확인했고 실행은 안 했다 | +| 결정의 근거 | 확인한 사실: platform 경계는 "소유 범위(context·feature)마다 하나"를 목표로 한다(`scoped-error-boundary.tsx:4-9`). presentation 경계는 route 단위 보고를 맡는다. 리뷰어 추론: 두 목적이 다르다는 점은 타당하다. 문제는 feature 수준에서 둘이 겹치고 이름이 거의 같다는 점이다 | +| 이해 비용 | 기능 작성자는 "feature-boundary" errorSurface(`reference-feature-contract.ts:83`)가 어느 컴포넌트인지 라우터 600줄을 읽어야 안다 | +| 최소 개선 방향 | ① feature 수준 경계를 하나로 합친다: `FeatureErrorBoundary`가 보고(incident id, 진단)를 맡고, `RegisteredRoute` 안쪽은 route 경계만 둔다. 또는 이름을 `RouteFeatureBoundary`/`FeatureScopeBoundary`처럼 역할로 나눈다. ② 한쪽 `TelemetryPort`를 `PlatformTelemetryPort`로 바꾼다. ③ `src/presentation/adapters/`를 `bindings/`로 바꾸는 것은 import 경로가 넓게 바뀌어 비용이 크다. 문서 한 줄로 둔다. ④ `application/result.ts`를 지우고 샘플을 `AppFailure`로 옮긴다 | +| 대안 비교 | (a) 현상 유지. (b) 이름만 바꾼다: 싸고 혼동은 준다. 중첩은 남는다. (c) feature 경계를 하나로 합친다: 09-09 수정과 같이 하면 한 번에 끝난다. ①은 (c), ②④는 (b) 권장 | +| 단순화의 보존 조건 | 실패가 소유 범위만 대체하고 형제는 계속 렌더한다(`scoped-error-boundary.tsx:7-8`). `resetKey`로 회복한다. route 실패의 incident id와 진단 보고(`render-error-boundary.tsx:23-30`)를 잃지 않는다 | +| 비용·부작용 | ①은 라우터와 경계 테스트 수정. ②는 타입 이름 변경 4파일 | +| 재검토 조건 | context 아래 기능이 여럿인 제품이 경계별 다른 fallback을 요구할 때 | +| 완료 기준 | feature 수준 경계 컴포넌트가 하나다. `TelemetryPort` 이름이 하나의 타입만 가리킨다. `application/result.ts`가 없다. `grep -rw ApiFailure src`가 별칭 줄만 찾는다 | +| 검증 방법 | 기존 경계 테스트(`tests/platform/errors/*`, `tests/component/context-route-gateway.test.tsx`)와 09-09의 검증 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-06 기능 `contracts/` 폴더가 와이어 계약·화면 문구·뷰 모델을 함께 담아 기능 코드의 46%를 차지한다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 2, 4, 22, 9 | +| 근거 | 참조 기능 1,919줄 중 `contracts/`가 891줄이다. 여기에 V2 operation 행·스키마 메타·라우트(`reference-feature-contract.ts`, 258줄), V3 HTTP 기여(`…-contribution.ts`, 231줄), zod 스키마와 zod 어댑터(`reference-schemas.ts`), DTO→도메인 mapper 두 벌과 뷰 모델(`reference-mapper.ts:13-18, 129-137`), 화면 문구(`reference-message-catalog.ts`, 92줄)가 있다. application은 뷰 변환을 `contracts/`에서 가져오고(`reference-feature-api.ts:3-6`), presentation은 뷰 타입을 여기서 가져온다(`use-reference-feature.ts:17`). 이 폴더에는 어댑터 import 금지 규칙이 없다(12-03 남음, 실험 M3) | +| 발생 조건 | 기능 작성자가 "이 코드를 어디에 둘까"를 정할 때 | +| 영향 | `contracts/`가 "기능 안의 공용 폴더"가 된다. 새 기능은 이 모양을 그대로 복사한다. 규칙이 없는 폴더라 경계 우회 통로도 된다 | +| 심각도·우선순위 | Low · P3 | +| 통제·증거 | M0(폴더 역할 규칙 없음) · E1 | +| 확실성과 남은 가정 | 줄 수는 `wc -l`로 셌다 | +| 결정의 근거 | 확인한 사실: 화면 문구는 `feature-module.ts`가 모으므로 루트에서 닿는 곳이면 된다. 뷰 모델은 application input의 반환 타입이라 application 쪽 소유가 자연스럽다. 리뷰어 추론: 계약 891줄 대부분은 07-02의 V2/V3 이중 선언에서 온다 | +| 이해 비용 | 기능 작성자가 와이어 스키마를 고치려고 열었을 때 화면 문구·뷰 변환이 같은 폴더에 있다 | +| 최소 개선 방향 | 뷰 모델과 `toReferenceView`를 `application/`으로, 문구 catalog를 `presentation/`으로 옮긴다. `contracts/`에 `feature-domain-is-framework-neutral`과 같은 꼴의 규칙(`src/adapters`·`presentation` import 금지)을 더한다(12-03 개선과 같이) | +| 대안 비교 | (a) 현상 유지. (b) 파일 3개 이동 + 규칙 1개. (c) 07-02의 V2 생성까지 해서 계약 크기를 줄인다: 효과가 가장 크다. (b) 먼저, (c)는 07 영역 순서를 따른다 | +| 단순화의 보존 조건 | `feature-module.ts`가 모으는 `messages` 타입(`installed-feature-messages.ts`의 locale 교집합 계산)이 그대로 추론된다. 제거 드릴 잔여 검사가 통과한다 | +| 비용·부작용 | 파일 이동과 테스트 import 수정 | +| 재검토 조건 | 기능 계약을 외부 패키지가 대부분 생성하게 될 때 | +| 완료 기준 | 기능 `contracts/`에 React 문구·뷰 모델이 없다. 규칙을 지우는 변이에서 architecture fixture가 실패한다 | +| 검증 방법 | 실험 M3의 `contracts/reexport-http.ts` 경로가 `check:architecture`에서 거부된다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +### 16-07 실무에서 자주 필요한 기능 패턴 7개는 런타임만 있거나 아무것도 없고, 복사할 기능 예제가 없다 + +| 필드 | 내용 | +|---|---| +| 성격 | 개선 제안 | +| 관련 관점 | 3, 20, 22, 17 (+30.5) | +| 근거 | 7절 표의 "빠진 패턴". 핵심 둘: (1) **제품용 계약 출처.** 제품 기능은 `EXTERNAL_PACKAGE`가 필수다(`external-contract-runtime.ts:215-225`, 설계서 `2026-07-30-…:746`). 참조 기능은 제품이 쓸 수 없는 `TEMPLATE_FIXTURE`다(`reference-feature-contract-contribution.ts:21-26, 220-224`). repo 안의 `EXTERNAL_PACKAGE` 예는 `tests/helpers/external-contract-fixture.ts`뿐이고 기능 모양이 아니다. `starter-experience.md` "Adding a feature"에 이 규칙이 없다(07-04 이해 비용과 같은 사실). (2) **페이지네이션.** `createCursorPaginationRuntime`(`src/adapters/query-cache/index.ts:6`)은 배럴에서 나가지만 bootstrap·application·presentation 어디에도 소비자가 없고 port도 없다. 참조 목록은 `cursor`·`limit` 필터를 받지만 응답 DTO에 다음 커서가 없다(`reference-schemas.ts:29-35`). 나머지: 낙관적 갱신(`application-query.ts:207-216`에 옵션이 있고 테스트도 있지만 기능 소비자 0, 뷰 모델의 `optimistic?: boolean`은 아무도 채우지 않는다), 수정·삭제 명령(생성만 있다), URL 필터 변경 UI(필터를 표시만 한다, `reference-resource-page.tsx:35-40`), 기능 간 협력(모든 기능 간 import 금지, 대안 경로 안내 없음), 클라이언트 권한 힌트(`access`가 `public`·`session-required` 둘뿐, `contracts/routes.ts:6`) | +| 발생 조건 | 제품이 목록 다음 페이지, 편집·삭제, 즉시 반영 UI, 역할별 메뉴를 만들 때. 첫 실제 HTTP 기능을 넣을 때 | +| 영향 | 제품마다 이 패턴을 따로 만든다. 템플릿이 공들인 실패 처리(결과 불명, 멱등 키, 스코프 펜스)가 새 패턴에 적용되는지 각자 판단해야 한다. (1)이 없으면 첫 HTTP 기능에서 막힌다(실험 E ⑦) | +| 심각도·우선순위 | Low · P2 — 기능이 없어서 생기는 결함은 아니다(0.1 지원 범위). (1)은 모든 제품 HTTP 기능이 지나는 길이라 P2 | +| 통제·증거 | 해당 없음(예제 유무) · E1 | +| 확실성과 남은 가정 | 소비자 0은 grep으로 확인했다. 제품 repo가 이미 이 패턴을 만들었는지는 보지 않았다 | +| 결정의 근거 | 확인한 사실: 문서 9절 패턴 카탈로그는 "reference usage, negative test, 실패 상태 test가 있어야 제공된 패턴으로 본다"고 적는다(`routing-pages-and-patterns.md:487-489`). 이 기준으로 낙관적 갱신·페이지네이션은 "제공"이 아니다. 리뷰어 추론: 런타임은 먼저 만들고 기능 예제가 따라오지 않았다 | +| 이해 비용 | 기능 작성자가 런타임 테스트(`tests/component/application-mutation-optimistic-cache.test.tsx`, `tests/unit/cursor-pagination-runtime.test.ts`)를 읽고 기능 쪽 연결을 추측해야 한다 | +| 최소 개선 방향 | (1) 참조 기능 옆에 "제품용 계약 기여" 예제 파일 하나(가짜 패키지 ID를 쓰되 테스트에서만 설치)와 매뉴얼 절을 둔다. (2) 참조 목록에 다음 커서와 "더 보기"를 더하고 커서 페이지네이션을 application input 뒤로 연결한다. 낙관적 갱신은 참조 생성 명령에 옵션 하나로 보여 준다. 나머지는 매뉴얼에 "아직 패턴 없음, 이 런타임을 써라"로 적는다 | +| 대안 비교 | (a) 현상 유지 + 매뉴얼에 "없음" 표시. (b) 참조 기능을 넓힌다: 샘플이 커지고 초기 JS가 늘 수 있다(9절, 여유가 작다). (c) 두 번째 샘플 기능(`patterns-feature`)을 넣는다: 16-02를 먼저 고쳐야 한다. (1)은 (b), 나머지는 (a) 먼저 권장 | +| 단순화의 보존 조건 | 참조 기능의 제거 드릴과 잔여 검사가 통과한다. 페이지네이션 예제가 `check:request-fanout`(12-01)에 걸리지 않게 한다 | +| 비용·부작용 | 샘플 크기 증가. 초기 JS는 지연 청크라 영향이 작아야 하지만 확인이 필요하다 | +| 재검토 조건 | 제품 두 곳 이상이 같은 패턴을 각자 만들었을 때 | +| 완료 기준 | 7절 표의 "빠진 패턴" 열에 예제 위치나 "의도적 비지원" 표시가 모두 있다 | +| 검증 방법 | 매뉴얼의 패턴 목록과 7절 표 대조. 예제를 넣으면 기능 테스트가 실패 상태까지 검사하는지 본다 | +| 담당·기한·상태 | 미정 · 미정 · 신규 | + +## 5. 설계 선택 검토 (41절) + +### 5.1 기능 설치를 "기능 폴더의 리터럴 헤더 → 생성기 → 생성 인덱스 → 중앙 카탈로그 투영"으로 하는 선택 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 기능을 넣고 뺄 때 중앙 파일을 고치지 않는다. 선택하지 않은 기능은 번들·Node 스크립트·라우터 어디에도 import되지 않는다. 잘못된 소속 선언은 첫 빌드 단계에서 실패한다 | +| 2. 지킬 성질 | 설치 집합이 하나다(번들·스크립트·라우터가 같은 목록). 기능 ID는 유일하다. 선언이 빠진 폴더를 조용히 버리지 않는다 | +| 3. 현재 보장 | 생성기가 `src/apps\|contexts\|features/*/…-module.ts`의 리터럴만 정규식으로 읽는다(`generate-product-feature-index.ts:241-258`). 폴더에 `feature-module.ts`도 `NOT_INSTALLED`도 없으면 실패한다(`:288-293`). ID 중복·미선언 context·예산 초과를 이름과 함께 거부한다. 카탈로그 8개는 생성 인덱스의 투영뿐이다. 실험 E에서 카탈로그를 한 줄도 고치지 않고 두 번째 기능이 조립됐다. **보장하지 않는 것:** 조립 밖의 거버넌스·증거·테스트 하네스(16-01, 16-02), 기능 라우트와 context 루트의 관계(09-06) | +| 4. 대안 | (a) 현재. (b) `import.meta.glob`로 기능 폴더를 자동 수집: 생성 단계가 없다. (c) 손으로 쓰는 설치 목록 한 파일. (d) 기능별 패키지(workspace) | +| 5. 득실 | (b)는 아키텍처 그래프가 import를 볼 수 없어 파서가 거부한다(`layers.md` 그래프 절). Node 스크립트도 같은 집합을 못 쓴다. (c)는 단순하지만 템플릿 소유 파일 하나를 기능마다 고쳐 동기화 충돌 지점이 된다. (d)는 경계가 가장 강하지만 설치·빌드 비용이 크다. (a)는 생성 단계 하나와 리터럴 규칙을 배워야 한다 | +| 6. 선택 이유 | 확인한 조건(정적 그래프 검사, Node 스크립트가 같은 설치 집합을 읽어야 함, 제품이 템플릿 파일을 덜 고쳐야 함)에서 (a)가 맞다. 실험 E가 조립 부분은 약속대로 동작함을 보였다 | +| 7. 재검토 조건 | 거버넌스·증거 파일도 기능 기여로 바뀌면 이 구조가 16-01의 나머지까지 덮는다. 기능이 수백 개가 되어 생성기 실행 시간이 문제가 되면(지금은 측정 안 함) 다시 본다 | + +### 5.2 기능 하나를 폴더 하나에 두고, 그 안을 `domain/application/contracts/adapters/presentation`으로 나누는 선택 + +| 질문 | 답 | +|---|---| +| 1. 무엇이 필요한가 | 기능 단위로 지울 수 있다. 기능 안에서도 안쪽(도메인·application)이 React·HTTP를 모른다 | +| 2. 지킬 성질 | 기능끼리 import 0. 기능 domain·application → presentation·adapters 금지. 기능 presentation → 외부 어댑터 금지 | +| 3. 현재 보장 | 규칙 4개(`feature-domain-is-framework-neutral`, `feature-application-does-not-know-runtime`, `feature-presentation-does-not-know-outbound-adapters`, `feature-adapters-do-not-know-presentation`)와 `features-do-not-import-other-features`가 `check:architecture`에서 강제된다. 실험 E의 복사본도 그대로 통과했다. **보장하지 않는 것:** 5개 이름 밖 폴더와 `contracts/`의 간선(12-03, 실험 M3). 폴더 역할(16-06) | +| 4. 대안 | (a) 현재. (b) 기능 안을 평평하게 두고 파일 이름 접미사로 역할 표시. (c) 기능 폴더 안에 허용 폴더 목록을 강제(목록 밖 폴더 거부) | +| 5. 득실 | (b)는 작은 기능에 싸지만 규칙을 경로 정규식으로 쓰기 어렵다. (c)는 12-03을 한 번에 막는다. 규칙 1개 추가로 비용이 작다. 기능 작성자가 `hooks/`를 못 만드는 불편이 생긴다 | +| 6. 선택 이유 | 경로 정규식 기반 검사와 맞는 (a)가 타당하다. 다만 (a)만으로는 목록 밖 폴더가 무규칙이라 (c)를 더하는 쪽이 낫다 | +| 7. 재검토 조건 | 기능 하나가 수천 줄이 되어 하위 기능이 필요할 때. 외부 계약 패키지가 대부분의 `contracts/`를 생성하게 될 때 | + +### 5.3 기능 라우트를 bounded context의 루트 경로 아래에서 지연 로드하는 선택 + +09 영역 4.3절이 같은 선택을 검토했다. 이 영역 실험(M2)이 더한 사실만 적는다. 정적 검사 4개는 루트 밖 라우트를 모두 통과시킨다. 페이지 테스트만 잡는다. 생성기는 이미 `CONTEXT_ROUTE_PATH`를 읽고 있어서, 기능 계약의 경로와 비교하는 검사는 생성 단계나 `installed-feature-contracts.ts`의 조립 검사에 몇 줄로 넣을 수 있다(리팩토링 R-1). + +## 6. 리팩토링 후보 + +`codebase-design`의 삭제 시험("지우면 복잡성이 사라지는가, 호출자 N곳에 다시 나타나는가")과 깊이(호출자가 배워야 할 인터페이스 대비 얻는 동작)를 기준으로 골랐다. + +| ID | 무엇을 | 왜 | 보존 조건 | 대안과 기각 이유 | +|---|---|---|---|---| +| R-1 | 기능 라우트 경로가 소유 context 루트 밑에 있는지 조립 때 검사 | 09-06. 지금은 페이지 테스트만 잡는다. 생성기가 이미 두 값을 안다 | 지금 URL이 바뀌지 않는다. 플랫폼 라우트는 대상 밖 | 문서만 고치기: 실험 M2처럼 정적 검사가 계속 통과한다. 기각 | +| R-2 | 기능 로컬 route 헬퍼(`RouteUrl`, `useRouteInput`) | 16-04. 경로 8곳 중복과 cast 2곳 제거 | parse·serialize가 같은 codec. 라우터 역참조 없음 | 플랫폼 `buildRouteUrl` 타입 좁히기: 기능 → 설치 카탈로그 의존. 보류 | +| R-3 | V2 선언(operation 행·스키마 메타·runtime codec·registry mapper)을 V3 descriptor에서 생성 | 07-02. operation 하나를 5곳에 적는다(표 아래 ①~⑤). 계약 891줄의 대부분. 손으로 쓴 registry mapper가 zod 스키마와 따로 논다(`reference-mapper.ts:52-60`의 타입 가드에는 `max(120)`·datetime 검사가 없다) | FE-REG-API 행이 지금과 같다(baseline 무변경). 일치 테스트가 남는다 | 일치 테스트 필드만 늘리기: 사본 수는 그대로. 07 영역 결정을 따른다 | +| R-4 | 공유 MSW 시나리오 카탈로그를 설치된 V3 descriptor 기반으로 일반화하고, 참조 전용 handler를 기능 테스트 폴더로 이동 | 16-02. 새 기능이 하네스를 쓰려면 공유 파일을 고친다 | HTTP 시나리오 증거 범위 | 기능별 하네스 복사: 사본이 늘어난다. 기각 | +| R-5 | 전역 상태를 단정하는 테스트 3개를 기능 로컬 단정으로 | 16-02 | 각 테스트가 지키던 동작 | 현상 유지: 기능마다 같은 파일 충돌. 기각 | +| R-6 | feature 수준 오류 경계를 하나로 합치기 | 16-05, 09-09 | 소유 범위 대체, `resetKey` 회복, incident id·진단 | 이름만 바꾸기: 중첩이 남는다. 09-09와 같이 하면 합치기가 싸다 | +| R-7 | `src/application/result.ts` 삭제, 샘플의 `ApiFailure` → `AppFailure` | 16-05. 삭제 시험: 지워도 아무 곳에서도 복잡성이 다시 나타나지 않는다(소비자 0) | `Result` 타입 계약 | 유지: 제거 조건이 영원히 충족되지 않는다. 기각 | +| R-8 | 기능 `contracts/`에서 뷰 모델·문구 분리 + 폴더 규칙 | 16-06, 12-03 | `messages` 타입 추론, 제거 드릴 | R-3 이후로 미루기: 규칙 공백(12-03)은 지금 있다 | +| R-9 | 인증 프로필 이름 변경 + 오류에 operation ID | 16-03 | 헤더 동작, baseline 증거 | 문구만 보강: 샘플 이름이 제품에 남는다. 둘 다 권장 | + +R-3의 "5곳"은 다음과 같다. ① V2 행(`reference-feature-contract.ts:157-240`) ② V3 descriptor(`…-contribution.ts:54-214`) ③ 스키마 메타(`reference-feature-contract.ts:19-74`) ④ runtime codec(`reference-schemas.ts:124-146`) ⑤ registry mapper(`reference-mapper.ts:108-127`). 실행에 쓰이는 것은 ②와 typed mapper(`reference-http-gateway.ts`의 `mapSuccess`)다. ①③④⑤는 레지스트리 게이트와 V2 경로용이다. + +## 7. 기능 개발 패턴 카탈로그 + +템플릿이 새 기능에 주는 패턴이다. "예제"는 복사할 수 있는 기능 코드가 있는지를 뜻한다. + +| 패턴 | 정의 위치(플랫폼) | 예제(참조 기능) | 검사 | 빠진 것 | +|---|---|---|---|---| +| 기능 모듈 등록 | `src/features/feature-module.ts`(`defineFeatureModule`), 생성기 | `feature-module.ts` | 생성기 오류, id↔contract featureId 일치(`feature-module.ts:72-77`) | — | +| context·앱 소속 선언 | `src/contexts/bounded-context-module.ts`, 생성기 | `src/contexts/reference-context/context-module.ts` | 미선언 context·예산 초과 거부 | 라우트가 루트 밑인지(09-06) | +| 라우트 기여 | `src/contracts/routes.ts`(타입), `route-runtime-contract.ts`, `platform/routing/context-route-module.ts` | 계약 `routes`·`routeRuntimeContracts`, `context-routes.ts`, `presentation/reference-feature-runtime*.ts` | 타입 완전성 fixture, 중복 키 거부, governance allowlist | route별 입력 타입·URL 헬퍼(16-04) | +| route 입력 codec | `presentation/routes/route-codecs.ts` | `reference-feature-runtime-descriptor.ts`(zod 스키마를 codec으로) | parse 실패 → `InvalidRouteSurface` | — | +| API operation 기여(V2 행) | `contracts/api-operations.ts`(`defineRestOperation`) | 계약 `apiOperations` | FE-REG-API, 프로필 결합 검증 | V3에서 생성(07-02) | +| HTTP 계약 기여(V3, 실행) | `contracts/external-contract-runtime.ts` | `…-contract-contribution.ts`(`TEMPLATE_FIXTURE`) | 조립기 검증, V2/V3 일치 6필드 | **제품용 `EXTERNAL_PACKAGE` 예제(16-07)** | +| gateway port + HTTP 어댑터 | `adapters/http`의 `createFeatureHttpBinding`, `defineFeatureHttpOperationForRoutes` | `application/…-api.ts`(`ReferenceGateway`), `adapters/reference-http-gateway.ts` | operation ID·route ID·입력 타입 음성 fixture | — | +| 문제 응답 → 실패 매핑 | `mapProblem`(HTTP binding) | `reference-http-gateway.ts:37-52`(409, 422) | 기능 테스트 | — | +| DTO 스키마·mapper | `contracts/zod.ts`, `boundary-mapper.ts` | `reference-schemas.ts`, `reference-mapper.ts` | 스키마·mapper ID 중복 거부 | zod 어댑터 공유(07-03), mapper 이중화(R-3) | +| Result·AppFailure | `contracts/result.ts`, `contracts/errors.ts` | gateway·input 반환 | `FailureKind` 닫힌 어휘 | 기능 오류 어휘(`AppError`)의 쓰임(07-05) | +| 실패 → 화면 행동 | `AppFailure.action` | `use-reference-failure-action.ts` | 페이지 테스트(401·403·429) | — | +| 기능 input 레지스트리 | `application/ports/in/application-api.ts`(module augmentation) | `reference-feature-api.ts:51-55` | 잘못된 ID·모양 음성 fixture | — | +| 조립 기여(`needs`) | `features/feature-adapter-contribution.ts` | `adapters/create-reference-feature-input.ts` | 중복·누락 capability 거부 | 실행 시 capability 전체 전달(09-08) | +| 쿼리 바인딩 | `contracts/server-state.ts`(`bindQuery`, profile), `presentation/adapters/query` | `use-reference-feature.ts:81-104, 116-147` | profile ID 검사 | `operationId`가 `string`이라 operation과 묶이지 않는다 | +| 쓰기 명령 멱등 처리 | V3 `retrySemantics: "KEYED"`, `commandRecovery`, 뮤테이션 policy | 생성 명령 + 결과 불명 UI(`reference-resource-form-page.tsx:146-171`) | 기능 테스트(504 재전송 같은 키) | 수정·삭제 명령 예제 | +| 무효화 | `contracts/query-invalidation.ts` | 계약 `invalidation`, 폼 페이지 재조회 링크 | 중복 거부(부팅·registries) | topic ID 생성 방법 안내 | +| 낙관적 갱신 | `application-query.ts:207-216` | **없음** | 런타임 테스트만 | 16-07 | +| 페이지네이션 | `adapters/query-cache`(`createCursorPaginationRuntime`) | **없음**(커서 필터만, 다음 커서 없음) | 런타임 테스트만 | 16-07, 12-01 | +| 폼 스키마·명령 mapper | `presentation/forms`(`useAppForm`, dirty guard) | `reference-resource-form.ts`, 폼 페이지 | 422 허용 필드, dirty 네비게이션 | — | +| 페이지 템플릿 | `presentation/templates`(Collection·Detail·Form·Status) | 페이지 4개 | template의 데이터 접근 금지 규칙 | — | +| 문구 catalog | `presentation/i18n`, 기능 `messages` | `reference-message-catalog.ts` | 키 중복 거부, `check:i18n` | 보간 파라미터 타입(08-03) | +| 기능 telemetry | `platform/telemetry`(fail-open) | `reference-feature-api.ts:76-105` | 기능 테스트 | — | +| 기능 끄기 | `FEATURE_OVERRIDES` 런타임 설정 | `config/runtime/*.json` | 기능 스위치 컴포넌트 테스트 | — | +| 로컬 저장(IndexedDB) | `FeatureIndexedDbRepositories` | `local-draft-feature`(`NOT_INSTALLED`) + 레시피 | 계약 테스트 | 설치 시 `runtime-adapters.ts` 수정(09-02) | +| 권한 분기 | `access: public\|session-required`, 서버 403 → `AppFailure` | 403 화면 테스트 | 가드 테스트 | 역할·권한 힌트(16-07) | +| URL 필터 변경 | search codec | 표시만 | — | 필터 폼 → URL 갱신 예제 | +| 기능 간 협력 | 금지 규칙만 | 없음 | `features-do-not-import-other-features` | 공유가 필요할 때의 경로 안내 | + +## 8. 매뉴얼 입력 — 새 기능 하나를 추가하는 작업 순서 + +### 8.1 복사 실험 기록 (실험 E) + +조건: `scratchpad/wt-16`(`d99301b`). `src/features/reference-feature`와 `tests/features/reference-feature`를 복사하면서 파일 내용과 이름의 `reference`/`Reference`/`REFERENCE`를 `order`/`Order`/`ORDER`로 바꿨다. 막힌 순서와 고친 것: + +| 순서 | 실행 | 결과 | 원인 | 고친 것 | +|---|---|---|---|---| +| 1 | 생성기 | 실패: `Feature order-feature belongs to undeclared context order-context` | context 선언 없음. 메시지가 정확하다 | `src/contexts/order-context/context-module.ts`(루트 `examples/order-resources/*`) | +| 2 | `tsc -p tsconfig.app.json` | 실패 2건: `fixtureId "ORDER_FEATURE_V1"`이 `"REFERENCE_FEATURE_V1"`이 아님, `supportOrder` 속성 없음 | `TEMPLATE_FIXTURE`는 참조 기능 전용 리터럴. 단순 치환이 `supportReference`까지 바꿨다 | 출처를 `EXTERNAL_PACKAGE`(가짜 신원)로 바꿈. `supportReference` 복원 | +| 3 | `tsc -p tsconfig.test.json` | 실패: `preference-providers` → `porder-providers`, `tests/mocks/handlers/order-resources.ts` 없음 | 단순 치환이 `preference`까지 바꿨다. 기능 테스트가 기능 폴더 밖 MSW handler를 쓴다 | 복원. handler 복사 | +| 4 | 같은 명령 | 실패 8건: 시나리오 카탈로그가 참조 operation 3개만 안다 | `tests/mocks/scenarios/catalog.ts:42-47` | 고치지 않고 진행(16-02 기록용) | +| 5 | 게이트 6개 | 모두 실패: `REST security profiles are incoherent.` | `ORDER_EXTERNAL_BEARER` 프로필 없음 | `REFERENCE_EXTERNAL_BEARER`로 되돌림(16-03) | +| 6 | 게이트 6개 | 모두 실패: `Invalid or duplicate schema definition: NoRequest` | 참조 기능의 스키마 ID `NoRequest`가 접두어 없는 일반 이름. 스키마 ID는 전역이다 | `OrderNoRequest` | +| 7 | `check-registries` | 실패: governance 미허용 값 6줄 + 무효화 topic 중복 | allowlist(P-07-03). topic ID `qinv.01k10f7m3w9p6r2c8v5n4x`는 이름에 `reference`가 없어 치환되지 않았다 | allowlist에 4값 추가. topic ID 끝 글자 변경 | +| 8 | `verify-documentation-readiness` | 실패: `FAIL_UNVERIFIED …` | `README.md`, `manual-checklist.md`에 새 route ID 없음(원인은 artifact JSON에만, 14-06) | 두 문서에 route ID 4개 | +| 9 | `check-registries` | 실패: breaking 4건(allowlist 확장, 무효화 그래프 3필드) | P-07-02 | `update-registry-baseline.ts`(owner·reason 환경변수) | +| 10 | `check-architecture`(shim) | 통과 | — | — | +| 11 | lint(새 파일) | 통과 | — | — | +| 12 | 빠른 계층 | 실패: 복사한 테스트 2건, 기능 밖 테스트 4건 | 3건은 16-02, 1건은 16-01 ⑤ | 고치지 않음(기록용) | + +최종: typecheck(app) · architecture · registries · documentation · i18n · design-system · diagnostics · adapter-inventory · ci-contract · lint 통과. 빠른 계층은 6건 실패(복사한 테스트 2건, 기능 밖 테스트 4건). 복사한 테스트 70개 중 68개 통과. test typecheck는 카탈로그 8건으로 실패한 채 남겼다. + +단순 치환에서 배운 것: **이름 치환은 토큰 경계로 해야 한다**(`preference`, `supportReference`). **접두어가 없는 전역 ID**(`NoRequest`, `qinv.*` topic, `REFERENCE_EXTERNAL_BEARER`, `navigationOrder: 50`)는 치환으로 처리되지 않는다. scaffold는 이 목록을 따로 다뤄야 한다(8.3절). + +### 8.2 작업 순서 + +각 단계에 손대는 파일, 판단 지점, 실수했을 때 무엇이 깨지고 무엇이 잡는지를 적었다. "못 잡음"은 이 커밋의 검사가 잡지 못한다는 뜻이다. + +**0단계. 기능 경계와 소속 정하기** + +- 판단: 기존 context에 넣을지, 새 context를 만들지. 기준 — 라우트 루트(URL 앞부분)를 공유하고 같은 시점에 지연 로드되어도 되면 같은 context다. URL이 다르면 새 context다. context 하나는 루트 경로 하나만 가진다. +- 판단: 기능 ID(케밥 표기), 라우트 루트. 기능 ID는 `FEATURE_MODULE_ID`, 계약 `featureId`, `ApplicationFeatureInputs` 키, `FEATURE_OVERRIDES` 키에 같은 문자열로 들어간다. +- 실수: 기능 라우트를 context 루트 밖에 둔다 → 메뉴에는 나오고 URL은 `NOT_FOUND`. **정적 검사는 못 잡는다**(09-06, 실험 M2). 라우터를 거치는 페이지 테스트만 잡는다. + +**1단계. 폴더와 선언 헤더** + +- 파일: `src/features//feature-module.ts`(`FEATURE_MODULE_ID`, `FEATURE_CONTEXT_ID`는 문자열 리터럴로 export), `src/features//context-routes.ts`(`FEATURE_CONTEXT_ROUTES`), 필요하면 `src/contexts//context-module.ts`(`CONTEXT_MODULE_ID`, `CONTEXT_APP_ID`, `CONTEXT_ROUTE_PATH`, `CONTEXT_MAX_FEATURES`). +- 확인: `node scripts/generate-product-feature-index.ts`. +- 실수 → 검사: 헤더를 상수 참조로 쓴다(리터럴 아님) → 생성기가 `must export a literal` 실패. 폴더에 `feature-module.ts`가 없다 → 생성기 실패(`NOT_INSTALLED` 표시를 두라는 안내). context ID 오타 → 생성기 `undeclared context`. 기능 ID 중복 → 생성기 실패. + +**2단계. 도메인 모델(선택)** + +- 파일: `domain/.ts`. 생성 함수에서 불변식을 검사하고 `Object.freeze`. +- 판단: 도메인 규칙이 없으면 만들지 않는다. 있으면 DTO가 아니라 업무 이름으로 짓는다(참조: `name` → `displayName`). +- 실수: React·HTTP·application import → `check:architecture`(`feature-domain-is-framework-neutral`). + +**3단계. API 계약 — 출처를 먼저 정한다** + +- 판단(가장 중요): 계약 출처. 제품 기능은 `EXTERNAL_PACKAGE`(`@org-contracts/` 패키지, 정확한 SemVer, `sha256` digest, `sourceRevision`)만 쓴다. `TEMPLATE_FIXTURE`는 참조 기능 전용이다. 외부 패키지가 아직 없으면 이 단계에서 멈추고 팀과 정한다. 지금 템플릿에는 제품용 예제가 없다(16-07). +- 파일: `contracts/-contract-contribution.ts`(V3 descriptor, `@org-contracts/*` import는 이 파일 이름에서만 허용 — `external-contract-package-single-import-path`), `contracts/-feature-contract.ts`의 `apiOperations`(V2 행), `schemas`(스키마 메타), `runtimeSchemas`, `mappers`, `contracts/-schemas.ts`(zod), `contracts/-mapper.ts`. +- operation마다 정할 것과 기준: + +| 결정 | 선택지 | 기준 | +|---|---|---| +| `retrySemantics` / V2 `replayPolicy` | `SAFE` / `IDEMPOTENT` / `KEYED`(`KEYED_COMMAND`) / `NEVER` | 읽기 = `SAFE`. 서버가 멱등 키로 중복을 막는 쓰기 = `KEYED` + `commandRecovery: IDEMPOTENCY_REPLAY` + `retryBudget: 0`. 서버가 중복을 못 막는 쓰기 = `NEVER` | +| `commandEffect.classifyProblem` | `NOT_APPLIED` / `MAYBE_APPLIED` | 서버 계약이 "상태를 안 바꿨다"를 보장하는 상태코드만 `NOT_APPLIED`. 모르면 `MAYBE_APPLIED`(결과 불명 UI로 간다) | +| `authProfileId` | `ANONYMOUS` / `REFERENCE_EXTERNAL_BEARER` / 새 프로필 | 세션이 필요하면 지금은 `REFERENCE_EXTERNAL_BEARER`. 새 이름이면 `src/contracts/rest-profiles.ts`에 추가(템플릿 소유 파일) | +| 바이트 한도·마감·트래픽 | `requestByteLimit`, `responseByteLimit`, `totalDeadlineMs`, `traffic.*` | 응답 최대 크기 × 여유. V2 `maxResponseBytes`와 같은 값(일치 테스트가 본다) | +| 스키마 ID·mapper ID·operation ID | 문자열 | **기능 접두어 필수.** 전역 공간이다 | + +- 실수 → 검사: V2와 V3의 method·path·성공 상태·응답 한도·인증 프로필·재시도 의미가 다르다 → `tests/unit/http-operation-v2-v3-parity.test.ts`. 스키마 ID·경로 파라미터 이름 차이 → **못 잡음**(07-02). 프로필 없음·조합 틀림 → 모든 게이트가 모듈 로드에서 `REST security profiles are incoherent.`(원인 ID 없음, 16-03). 스키마·mapper·operation ID 중복 → 모듈 로드에서 ID를 말하며 실패. `TEMPLATE_FIXTURE` 사용 → `fixtureId`를 바꾸면 tsc 실패, 안 바꾸면 **못 잡음**(07-04). zod를 직접 import → `zod-is-reached-through-contracts-zod`. + +**4단계. application input과 gateway port** + +- 파일: `application/-feature-api.ts` — input 타입, gateway 타입, `createXFeatureInput(gateway, { telemetry })`, `declare module "…/application-api.ts" { interface ApplicationFeatureInputs { "": XFeatureInput } }`. +- 판단: input 메서드 이름은 사용자 의도(`listResources`, `createResource`)로. 반환은 `Result`(`src/contracts/result.ts`). 폐기된 `src/application/result.ts`, `ApiFailure`는 쓰지 않는다(16-05). +- 실수 → 검사: augmentation 키와 조립 기여 `featureId`가 다르다 → 음성 fixture·조립기(`installed an input for …`). input 모양 불일치 → tsc. React import → `check:architecture`. + +**5단계. HTTP 어댑터와 조립 기여** + +- 파일: `adapters/-http-gateway.ts`(`defineFeatureHttpOperationForRoutes`, `mapSuccess`, 필요하면 `mapProblem`), `adapters/create--feature-input.ts`(`defineFeatureAdapterContribution`, `needs`). +- 판단: `needs`에 실제로 쓰는 capability만(`http`, `telemetry`, `indexedDb`). `indexedDb`면 `src/bootstrap/runtime-adapters.ts`도 고친다(09-02). +- 실수 → 검사: presentation에서 이 폴더 import → `feature-presentation-does-not-know-outbound-adapters`. 단 `hooks/`·`contracts/` 같은 다른 폴더를 거치면 **못 잡음**(12-03, 실험 M3). 선언 안 한 capability를 쓰면 tsc(타입만, 실행 시 전체가 전달됨 — 09-08). + +**6단계. 라우트** + +- 파일: 계약 `routes`, `routeRuntimeContracts`(같은 route ID 두 번), `presentation/-feature-runtime-descriptor.ts`(codec), `presentation/-feature-runtime.ts`(지연 페이지 표, `moduleId`가 계약과 같아야 함), `context-routes.ts`, 문구 `route..title|navigation`(ko-KR·en-US). +- 판단: `access`(`public`/`session-required`), `loadingSurface`, `errorSurface`(`feature-boundary` 권장), `chunkId`(전역 유일), `navigationOrder`(null이면 메뉴 밖, 숫자 중복은 검사 없음). +- 기능 폴더 밖: `config/contracts/registry-governance.json`의 `paramsSchema`·`searchSchema`·`loadingSurface` 허용 값(P-07-03), `README.md`와 `docs/accessibility/manual-checklist.md`의 route ID 목록, `artifacts/tests/a11y-manual/.md`(서명 형식은 기존 파일 복사). +- 실수 → 검사: allowlist 누락 → `check:registries`(값을 말한다). route ID 문서 누락 → `verify:documentation`(누락 ID를 말하지 않는다, 14-06). a11y 기록 없음 → `test:unit`(ENOENT). route ID 중복 → 조립 때 `Duplicate route registry key`. 경로·`chunkId` 중복 → governance `uniqueFields`로 `check:registries`가 잡을 것으로 읽힌다(실행 안 함). 페이지에서 경로를 문자열로 적어 계약과 어긋남 → 페이지 테스트가 있으면 잡음, 없으면 **못 잡음**(16-04). 루트 밖 경로 → **정적 검사는 못 잡음**(09-06). + +**7단계. 쿼리·뮤테이션 바인딩** + +- 파일: `presentation/use--feature.ts`. +- 판단: 쿼리 namespace(`defineQueryNamespaceIdentity(name, version)`), 무효화 topic(`qinv.<26자>`, 새로 만든다 — 복사하면 중복), profile(`LIST_STANDARD`/`DETAIL_STANDARD`/`LOOKUP_STABLE`/`VOLATILE_STATUS`), `measureResult`(바이트 추정, `JSON.stringify` 금지), 뮤테이션 policy(`requiresIdempotencyKey`, `duplicatePolicy: "REJECT_WHILE_ACTIVE"`, `invalidate`). +- 실수 → 검사: topic·namespace 중복 → `check:registries`와 부팅. 무효화 추가 자체가 breaking으로 분류된다 → 기준선 갱신 필요(P-07-02). `operationId` 문자열 오타 → **못 잡음**(`string` 타입). 없는 profile → 실행 시 `Unregistered server-state profile`. + +**8단계. 페이지** + +- 파일: `presentation/-*-page.tsx`, `use--failure-action.ts`, 폼이면 `-*-form.ts`(표현 스키마 + `toCreateXCommand`). +- 판단: 템플릿 선택(목록 `CollectionPage`, 상세 `DetailPage`, 생성·편집 `FormPage`, 안내 `StatusPage`). 쓰기 명령이 `KEYED`면 결과 불명 UI(`onReconcileUnknownEffect`, `onResendUnknownEffect`)를 반드시 둔다(참조 폼 페이지 146-171행). 폼 422 허용 필드(`allowedServerFields`). +- 실수 → 검사: TanStack·HTTP·storage 직접 import → `check:architecture`. 디자인 시스템 하위 경로 import → `design-system-is-reached-through-its-index`. 한국어 하드코딩 → `check:i18n`(영어 하드코딩은 못 잡음, 지난 08-02). 결과 불명 UI 누락 → **못 잡음**(기능 테스트가 있어야 한다). + +**9단계. 기준선과 증거** + +- 실행: `REGISTRY_BASELINE_OWNER=<담당> REGISTRY_BASELINE_REASON=<이유> corepack pnpm update:registry-baseline`(메인 repo에서). 또는 `config/contracts/registry-change-evidence.json`에 항목 추가(`docs/operations/ci-quality-gates.md:67`). +- 선택: `config/runtime/.json`의 `FEATURE_OVERRIDES`. +- 미확인: `config/testing/risk-coverage.json`, `test-evidence.json` 행 필요 여부(`test:coverage` 미실행). + +**10단계. 테스트** + +- 파일: `tests/features//`. 참조 기능 테스트 파일 16개를 복사하면 대부분 이름만 바꿔 통과한다(실험 E: 70개 중 68개). +- 기능 폴더 밖: MSW 시나리오를 쓰려면 `tests/mocks/handlers/-resources.ts`와 `tests/mocks/scenarios/catalog.ts`의 operation 목록·사실을 고친다(16-02). 무관한 테스트 3개가 깨질 수 있다(16-02 근거 ①~③). 라우트별 a11y 기록은 6단계. +- 판단: 라우터를 거치는 페이지 테스트를 최소 하나 둔다. 0·6·8단계의 "못 잡음" 항목 대부분을 이것이 잡는다. + +**11단계. 제거 확인** + +- 실행: `corepack pnpm test:sample-removal -- --feature=`(메인 repo). 기능 폴더, 기능 테스트 폴더, 마지막 기능이면 context, 런타임 override, 중앙 정책 행을 지운 복제본에서 게이트를 돈다. +- 실수: 기능 폴더 밖에 기능 전용 파일을 두면 드릴이 지우지 않는다. 참조 기능은 이런 파일을 `SAMPLE_EXTRAS`(경로 26개, CI 스크립트 10개)로 손으로 관리한다. 제품 기능에는 그런 목록이 없으므로 기능 전용 파일은 기능 폴더와 `tests/features//` 안에 둔다. + +### 8.3 scaffold가 따로 다뤄야 하는 전역 ID + +치환만으로는 안 되는 값이다. 실험 E에서 실제로 걸린 것은 굵게 표시했다. + +| ID | 위치 | 유일성 검사 | +|---|---|---| +| 기능 ID, context ID | 헤더, 계약, augmentation, `FEATURE_OVERRIDES` | 생성기 | +| route ID, 경로, `chunkId` | 계약 | route ID는 조립(`composeUniqueRecord`). 경로·`chunkId`는 governance `uniqueFields`(실행 안 함) | +| **스키마 ID**(`NoRequest` 같은 일반 이름 포함) | 계약 메타, zod 표, codec, V3 validator | 모듈 로드 | +| mapper ID, operation ID, `contributionId` | 계약, V3 | 모듈 로드·조립기 | +| `policyId`, `diagnosticsOperation` | V3 `frontend` | 미확인 | +| 쿼리 namespace, **무효화 topic**(`qinv.*`) | 계약 | `check:registries`, 부팅 | +| 쿼리·뮤테이션 `definitionId` | hook | 미확인 | +| 문구 키 | catalog | 조립(`Duplicate … message key`) | +| telemetry `kind` | application | 미확인 | +| **인증 프로필**(`REFERENCE_EXTERNAL_BEARER`) | V2·V3 | 모듈 로드(원인 없이) | +| `navigationOrder` | 계약 | 없음(같은 50이 둘이어도 통과) | +| `owner` 문자열 | 계약 메타 | 미확인 | + +### 8.4 매뉴얼이 링크하면 안 되는 설명 + +- `starter-experience.md:136-147`의 "폴더 밖 수정" 표와 "governance는 바뀌지 않는다" 문장(16-01, P-07-03). +- `frontend-ports-adapters-and-boundaries.md:313-376`의 "권장 목표 디렉터리 구조". 현재 구조가 아니다. +- 참조 페이지의 경로 하드코딩과 cast(16-04). 매뉴얼 예시는 route ID 기반으로 쓴다. + +## 9. 성능 — 기능 하나를 더할 때의 번들 비용 + +측정 방법: 같은 worktree에서 `VITE_PRODUCT_FEATURES=reference-feature`(참조 기능만)와 전체(참조 + `order-feature`)로 `scripts/build-frontend.ts`를 각각 돌렸다(`APP_PROFILE=local`, `flock heavy.lock`). 초기 JS는 `scripts/lib/classify-vite-bundle.ts`의 `classifyViteJavascript`로 고른 파일을 `zlib.gzipSync` 기본 수준으로 압축해 더했다(`check-bundle.ts`와 같은 분류 함수, 15 영역과 같은 방법. 참조만 구성의 값이 13·15 영역 측정과 20 B 안에서 맞는다). 측정 스크립트는 `scratchpad/r16/measure-initial.mjs`. 빌드 직전 부하: 8.7(참조만), 21.4(두 기능). 바이트 수는 부하와 무관하다. + +| 구성 | 초기 JS 파일 수 | 초기 JS gzip | 예산(`config/performance/budgets.json`) | 여유 | +|---|---|---|---|---| +| 참조 기능만 | 13 | 203,501 B | 204,800 B | 1,299 B | +| 참조 + order | 15 | 207,525 B | 204,800 B | 초과 2,725 B | + +참조 모양 기능 하나가 초기 JS를 4,024 B 늘린다. 예산을 2,725 B 넘는다. `check:bundle`은 이 값이면 실패한다(추론. 직접 실행은 공급망 생성이 pnpm을 불러 worktree에서 하지 않았다). 13·15 영역이 같은 여유를 적었으므로 새 발견으로 세지 않는다. 이 영역이 더한 사실은 **왜 지연 로드 기능이 초기 JS를 늘리는가**다. + +| 초기 파일 | 참조만 | 참조 + order | 차이 | +|---|---|---|---| +| `order-feature-runtime-descriptor` 청크 | 0 | 2,415 | +2,415 | +| `reference-feature-runtime-descriptor` 청크 | 25,138 | 2,426 | −22,712 | +| `schema-registry` 청크(두 기능이 공유하는 코드가 새 청크로 분리) | 0 | 23,209 | +23,209 | +| `design-system` | 66,258 | 67,252 | +994 | +| `boot`·`index` 등 나머지 | — | — | +118 | + +기능 페이지는 지연 청크다(order 페이지 5개, 340~1,317 B). 초기 청크에 들어가는 것은 `feature-module.ts`가 끌어오는 그래프 전체다: 계약 메타, V2 행, V3 descriptor, zod 스키마와 codec, mapper 두 벌, 문구 catalog, 조립 기여. 생성 인덱스가 `FEATURE_MODULE`을 정적으로 import하고(`src/.generated/product-feature-index.ts`), 카탈로그가 부팅 때 이를 조립하기 때문이다. 기능당 고정 비용은 약 2.4 KB(gzip)다. 두 번째 기능을 처음 넣을 때는 공유 코드 재배치로 1 KB 정도가 더해진다. 07-02의 V2 생성(R-3)과 16-06의 문구 분리는 이 고정 비용을 줄이는 방향이기도 하다. 문구 catalog는 locale별 지연 로드 대상이 될 수 있다(측정 안 함). + +## 10. 28개 관점 판정표 (36.2) + +판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역. + +| 번호 | 관점 | 판정 | 적용·통제·증거 | 근거와 잔여 위험 | +|---|---|---|---|---| +| 1 | 코드 성숙도 | > | 07·09 | 참조 도메인 불변식은 생성 함수에 있다(`reference-resource.ts:7-13`) | +| **2** | **구조적 성숙도** | **P** | 적용 · M4/M3 · E3 | 기능 경계 규칙 5개가 복사본에도 그대로 작동했다(실험 E). 목록 밖 폴더·`contracts/`가 무규칙(12-03, M3). 경계 두 벌(16-05) | +| **3** | **변경 용이성** | **P** | 적용 · M3/M2 · E3 | 기능 추가 시 카탈로그 무수정은 지켜진다. 폴더 밖 7묶음 + 결정 2가지(16-01), 무관한 테스트 3개(16-02), 경로 3곳 중복(16-04) | +| **4** | **인지 부하** | **P** | 적용 · M2/M1 · E3 | 기능 작성자가 채우는 선언 슬롯이 19개(헤더 4, 모듈 필드 5, 계약 필드 9, input augmentation 1), 계약 891줄. opaque 실패 3종(16-01) | +| 5 | 위험 가시성 | P | 적용 · M2/M1 · E3 | context 루트 규칙이 코드·문서에 없다(09-06, M2). 결과 불명 UI가 샘플에 드러나 있다(좋음) | +| 6 | 실패 성숙도 | > | 03·07 | 샘플의 409·422·결과 불명 처리는 03 영역 | +| 7 | 운영 성숙도 | - | 이 영역 밖 | — | +| 8 | 디버깅 가능성 | P | 적용 · M2/M1 · E3 | 인증 프로필 오류에 ID 없음(16-03), 문서 검사 원인 미표시(14-06), 시나리오 카탈로그 TypeError(16-02). 생성기 메시지는 좋다 | +| **9** | **유지보수 성숙도** | **P** | 적용 · M1/M1 · E1 | 폐기 사본 소비자 0(16-05), 목표 구조 문서 미폐기(14-03 증거). 참조 기능 밖 소유 경로 26개·CI 스크립트 10개를 손 목록으로 관리 | +| 10 | 테스트 성숙도 | P | 적용 · M3/M2 · E3 | 복사한 기능 테스트 68/70 통과. 전역 상태 단정 테스트 3개(16-02). 기능 추가 검증 테스트가 좁은 모양(16-01) | +| 11 | 데이터 성숙도 | > | 05 | — | +| 12 | 동시성 성숙도 | > | 03 | — | +| 13 | 확장성 | P | 적용(기능 수 축) · M3/M3 · E3 | 기능 하나가 초기 JS 4,024 B 증가, 예산 2,725 B 초과(9절, 13·15 영역 소관). context 예산 검사는 동작 | +| 14 | 성능 성숙도 | P | 적용(번들) · M3/M3 · E3 | 9절 | +| 15 | 보안 성숙도 | > | 03·13 | — | +| 16 | 의존성 성숙도 | > | 12·13 | — | +| 17 | API / Contract | P | 적용 · M3/M2 · E3 | V2/V3 이중 선언(07-02). 제품용 계약 출처 예제 없음(16-07) | +| 18 | 배포 성숙도 | > | 13 | — | +| 19 | 설정 성숙도 | > | 13 | `FEATURE_OVERRIDES`는 동작 | +| 20 | 개발자 경험 | P | 적용 · M1/M1 · E3 | 절차 문서와 실제가 다르다(16-01). 8절이 실제 순서를 준다 | +| 21 | Guardrail 성숙도 | P | 적용 · M3/M3(부분) · E3 | 중복 ID 대부분은 이름을 말하며 거부. context 루트(09-06), V2 스키마 ID(07-02), 목록 밖 폴더(12-03), `operationId` 문자열은 통과 | +| **22** | **추상화 성숙도** | **P** | 적용 · M2/M2 · E3 | 기능 모듈·조립 기여·HTTP binding은 깊다(작성자는 operation 표만 쓴다). 계약 선언은 얕다: operation 하나를 5곳(R-3). route 입력이 타입을 잃는다(16-04) | +| **23** | **일관성** | **P** | 적용 · M1/M1 · E1 | 경계·telemetry 이름 충돌(16-05). `adapters` 두 뜻. 라우트 제목 세 곳(08-06) | +| **24** | **네이밍 / 의미** | **P** | 적용 · M1/M1 · E3 | 플랫폼 프로필이 샘플 이름(16-03). `FeatureBoundary`/`FeatureErrorBoundary`(16-05) | +| 25 | 조직 확장성 | P | 적용(구조 준비만, 팀 1개) · M2/M2 · E3 | 기능끼리 import 금지와 카탈로그 무수정은 팀 분리를 돕는다. 템플릿 소유 파일 4곳을 기능마다 고친다(16-01) — 동기화 충돌 지점 | +| 26 | Ownership | > | 14 | — | +| **27** | **삭제 가능성** | **P** | 적용 · M3/M3 · E3(14 영역이 메인 repo에서 돌린 `test:sample-removal` PASS, 이 영역은 재실행 안 함) | 참조 기능은 드릴로 지워진다. 제품 기능에는 `SAMPLE_EXTRAS` 같은 밖 파일 목록이 없다. 플랫폼 예제는 제거 경로 없음(14-04). 샘플 이름 프로필이 남는다(16-03) | +| 28 | 회복 가능성 | > | 06·02 | — | + +집계(이 영역): P 17 · > 10 · - 1 · O 0 · X 0 · ? 0. + +## 부록 A. 실험 명령 요약 + +모두 `scratchpad/wt-16` 또는 `wt-16b`(`d99301b`)에서 실행했다. 로그는 `scratchpad/r16/`. + +| 실험 | 명령 | 결과 | +|---|---|---| +| E 1~9 | `node scripts/generate-product-feature-index.ts`, `npx tsc -p tsconfig.{app,test}.json`, `node scripts/{check-registries,check-i18n,check-design-system,check-diagnostics,verify-documentation-readiness,check-adapter-inventory,check-ci-contract}.ts`, `npm_execpath= node scripts/check-architecture.ts` | 8.1절 표 | +| E 11 | `node_modules/.bin/eslint src/features/order-feature src/contexts/order-context tests/features/order-feature tests/mocks/handlers/order-resources.ts --max-warnings=0` | rc=0 | +| E 12 | `node scripts/run-vitest.ts run tests/features/order-feature`, 같은 명령으로 `tests/features/reference-feature`, `tests/unit`, `tests/component`, `tests/integration`, `tests/contract`, `tests/runtime-schema` | order 70개 중 68 통과. reference 1파일·unit 1·component 1·runtime-schema 1 실패, integration·contract 통과 | +| M1 | 폼 경로 `/new` → `/create`(계약만) | tsc rc=0, 페이지 테스트 14개 실패 | +| M2 | `CONTEXT_ROUTE_PATH = "reference/*"` | tsc·registries·architecture·documentation rc=0, 테스트 24개 실패 | +| M3 | `hooks/use-http.ts`, `contracts/reexport-http.ts`로 HTTP 어댑터 재수출 후 presentation에서 import | architecture rc=0, eslint rc=0 | +| B | `VITE_PRODUCT_FEATURES=reference-feature APP_PROFILE=local flock heavy.lock node scripts/build-frontend.ts`, 전체로 한 번 더 | 9절 | diff --git a/docs/reviews/2026-11-01-maturity-review/README.md b/docs/reviews/2026-11-01-maturity-review/README.md new file mode 100644 index 00000000..e42538a2 --- /dev/null +++ b/docs/reviews/2026-11-01-maturity-review/README.md @@ -0,0 +1,308 @@ +# 성숙도 리뷰 — 2026-11-01 + +> 기준: `docs/reviews/TEMPLATE-MATURITY-REVIEW-GUIDE.md`. 범위: repo 전체를 지난 리뷰의 14개 영역에 2개(15 성능 실측, 16 폴더 구조·리팩토링·기능 개발 패턴)를 더한 16개 영역으로 나눴다. 영역 에이전트가 병렬로 읽고 실험했다. 이 문서는 오케스트레이터가 결과를 모으고, High와 P1 일부를 코드에서 다시 확인한 것이다. + +## 1. 사용 결정 (36.5-1) + +| 용도 | 결정 | 막는 항목 | +|---|---|---| +| 기능 1개를 추가해 출시 | **사용 보류** | 15-01: 참조 모양 기능 1개로 초기 JS가 예산을 2,725 B 넘는다(15·16 영역 실측). 16-01: 문서의 추가 절차가 실제 필요한 수정의 일부만 적는다. 16-02: 무관한 테스트 3개가 깨진다 | +| 공개(`ANONYMOUS`) API를 쓰는 제품 | 사용 보류 | 09-01 | +| 쓰기(command) 샘플을 결과 불명 처리 예제로 복제 | 사용 보류 | 0929/03-01, 08-03 | +| Service Worker를 `ACTIVE`로 켜서 릴리스 | 사용 보류 | 0929/06-01 (13 영역에서도 재현) | +| opt-in realtime(SSE)을 운영에 조립 | 사용 보류 | 0929/04-01 | +| 모바일·확대 화면이 중요한 제품 | 조건부 사용 가능 | 08-01: 48rem 미만에서 테마 선택·세션 상태가 사라진다 | +| desktop 서버로 자동 배포(로드맵 3·6) | 사용 보류 | 13-01(배포 job 자리 없음, 운영 검사가 옛 release를 볼 수 있음), 13-02(자리표시자 endpoint 승인) | +| 이 repo의 CI를 머지 차단 장치로 믿기 | 사용 보류 | U-1(Actions 꺼짐), 11-01(`test:system` 항상 실패), 15-01(번들 검사가 release 단계에만 있음), 0929/10-01(속도에 기대는 테스트) | +| 화면 디자인 시스템을 그대로 상속 | 조건부 사용 가능 | 12-01(UI-03 검사 결함, `--field-border` 미사용), 11-02(시각 골든이 호스트 글꼴에 의존) | + +## 2. 차단 항목 — High와 P1 (36.5-3) + +같은 결함을 두 영역이 적은 것은 하나로 합쳤다(4.3절). 재확인 칸의 "오케스트레이터 코드 확인"은 이 문서 작성자가 해당 줄을 직접 읽었다는 뜻이다. + +### 2.1 High + +| ID | 내용 | 재확인 | +|---|---|---| +| [09-01](09-app-core.md) (이월 0929/09-01) | 공개 API(`ANONYMOUS`) 요청이 어떤 세션 상태에서도 전송되지 않는다. `src/bootstrap/runtime-adapters.ts:501-531`의 `attachCredentials`가 요청의 인증 프로필을 읽지 않고 세션만 본다 | 오케스트레이터 코드 확인 + 에이전트 실험 E1(4개 상태 모두 fetch 0회). 3줄 수정 시 4개 상태 모두 1회 전송되는데 기존 테스트 96건이 그대로 통과한다. 막는 테스트가 없다 | +| 0929/03-01 ([03](03-adapters-http-state.md) 2절) | 결과 불명 쓰기를 같은 멱등 키로 다시 보냈을 때 서버가 "처리 중" 409를 주면 `NOT_APPLIED`로 판정한다. 다음 저장은 새 키로 나가 같은 리소스가 두 번 생길 수 있다 | 오케스트레이터 코드 확인(`reference-feature-contract-contribution.ts:42-44`, 409를 무조건 `NOT_APPLIED`) + 에이전트 재현(키 `[K, K, K′]`) | +| 0929/04-01 ([04](04-adapters-realtime.md) 2절) | SSE 연결이 끊기면 `OFFLINE`으로 보고하고, 재연결은 새 online 이벤트를 기다린다. 브라우저 네트워크는 정상이라 영원히 멈춘다 | 오케스트레이터 코드 확인(`sse/fetch-sse-connection.ts:215,398` → `reconnect-coordinator.ts:798`) + 에이전트 재현(20분 동안 fetch 1회). 수정안 두 가지 모두 기존 221건 통과 — 막는 테스트가 없다 | +| 0929/06-01 ([06](06-adapters-service-worker-push.md), [13](13-build-release-supply-chain.md)) | SW `ACTIVE` 빌드가 `dist/config.json`을 `public/config.json`(local·demo)으로 덮어쓴다. 빌드는 성공하고 admission만 거절한다 | 오케스트레이터 코드 확인(`vite.service-worker.config.ts`에 `publicDir` 설정 없음) + 두 영역 재현. `publicDir: false` 한 줄로 production·`/app/` 빌드가 ADMITTED | + +### 2.2 P1 (High 제외) + +| ID | 심각도 | 내용 | 재확인 | +|---|---|---|---| +| [15-01](15-performance.md) | Medium | 초기 JS 203,507 / 204,800 B(여유 1,293 B). 참조 모양 기능 1개를 넣으면 207,413 B로 넘는다. 번들·lab 검사는 release 단계에서만 돌아 예산을 넘는 PR이 머지된다(`config/ci/gates.json:2232-2241`). 원인은 `feature-module.ts` 그래프 전체가 초기 청크로 들어가는 것(16 영역) | 15·16 두 영역 실측 | +| [08-01](08-presentation.md) | Medium | 48rem 미만(모바일, 약 170% 확대)에서 테마 선택·세션 상태·브랜드가 `display:none`이고 서랍에도 없다. WCAG 1.4.10 | 에이전트 3엔진 스크린샷 | +| [11-01](11-tests-browser-release-scale.md) | Medium | `test:system` cgroup 테스트가 끝난 프로세스의 PID를 조회해 항상 실패한다(지난 11-06의 원인 재판정: 경쟁이 아니다) | 오케스트레이터 코드 확인(`ci-artifact-contract.test.ts:795`에서 완료를 기다린 뒤 `:810`에서 PID 조회) + 게이트 로그 | +| [11-02](11-tests-browser-release-scale.md) (= UI-05 후반) | Medium | 시각 골든이 작성자 PC 글꼴 4종으로 찍혀 있고 실행 환경 글꼴을 고정하지 않는다. 맨 Ubuntu 글꼴로는 0/5, 세 글꼴 폴더만 보이게 하면 5/5 | 에이전트 `FONTCONFIG_FILE` 실험 | +| [13-01](13-build-release-supply-chain.md) | Medium | 운영 검사가 승격 직후 돌고 배포 job이 없다. 검사는 배포된 build id를 후보와 비교하지 않아 PASS가 이전 release 결과일 수 있다. CI 계약이 job 9개를 고정해 배포 job을 넣으면 거절된다 | 에이전트 변이 | +| [13-02](13-build-release-supply-chain.md) | Medium | 승인 단계가 `api.example.com`·`telemetry.example.com`을 통과시킨다. CI 계약이 env를 고정해 `RUNTIME_*`를 넘길 수 없다 | 에이전트 실험(production 빌드 ADMITTED) | +| [09-02](09-app-core.md), [09-03](09-app-core.md) (이월) | Medium | 제품 capability·자격증명 확장 지점이 없고, 라우터가 `AppShell`과 플랫폼 홈을 고정한다 | 코드 변경 없음 확인 | +| 0929/11-01 ([11](11-tests-browser-release-scale.md) 2절) | Medium | `test:system`이 옛 문자열을 기대한다. 11-01과 함께 고쳐야 FE-GATE-013이 통과한다 | 게이트 로그(2 failed) | +| 0929/10-01 ([10](10-tests-fast-layers.md) 2절) | Medium | 속도에 기대는 테스트. 1코어 5/5 실패, 지난 목록에 없던 2종 추가 | 에이전트 `taskset` 재현 | +| 0929/08-01 ([08](08-presentation.md) 2절) | Medium | 지난 라운드 P1(제품이 지원 locale을 선언할 곳 없음) 그대로 | 코드 변경 없음 | + +## 3. 확인된 강점 (36.5-2) + +- **빠른 게이트가 모두 녹색이다.** 이 커밋에서 `check:architecture`, `check:types`, `lint`, unit 2,353건, component 211건, integration 155건, contract 15건, runtime-schema 56건이 통과했다(4.1절). +- **브라우저 3엔진이 안정적이다.** e2e: chromium 56/56, firefox 52 + skip 3(SW quarantine), webkit 55/55. capability 3엔진 63/63. 08 영역의 6라우트 렌더·키보드·200% 확대·aria 검사 90건 통과. +- **랩 성능이 좋다.** LCP 1.9초, CLS 0, 상호작용 111ms, 라우트 전환 80~114ms(15 영역, 5회×2). +- **UI 감사 수정이 유지된다.** UI-01·02·04·05·08의 수정과 새 검사가 그대로이고, UI-04를 되돌리면 i18n 테스트가 3엔진 모두에서 잡는다. 시각 회귀 테스트는 이 되돌림을 놓쳤다(허용치 안) — 의미 있는 검사를 따로 둔 이유다. +- **참조 기능을 복사해 이름만 바꾸면 결국 모든 정적 게이트를 통과한다.** 막힌 12곳은 모두 정확한 오류 메시지로 드러났다(16 영역 8절). 매뉴얼과 생성 명령으로 줄일 수 있는 종류다. + +## 4. 반복되는 원인 (36.5-4) + +1. **지난 라운드 이후 코드가 그대로다.** 이번 라운드 이월 항목 대부분은 `af3d8e6` 이후 해당 영역 코드가 한 줄도 바뀌지 않아서 남았다. 지난 개선 순서 1(High 5건)이 실행되지 않았다. +2. **결함을 막는 테스트가 없어 수정과 결함이 구분되지 않는다.** 09-01, 0929/04-01, 07-06, 12-02, 01-01이 같은 모양이다. 수정안을 넣어도 기존 테스트가 모두 통과한다. 변이 생존율도 높다(05 영역 13개 중 9개 생존, 06 영역 14개 중 3개, 07 영역 10개 중 5개). +3. **같은 정보를 두 곳에 쓴다.** HTTP API의 V2 행과 V3 descriptor(07-02), 컴포넌트 토큰과 스타일의 계산식(UI-03, 12-01), 조회 namespace와 무효화 레지스트리(03-01), 문서의 기능 추가 절차와 실제 절차(16-01). 사용자 원칙("위험은 코드에 드러나야 한다")과 정면으로 어긋나는 반복 원인이다. +4. **예산이 거의 꽉 찼다.** 초기 JS 1,293 B, 레시피 번들 77·14·9 B, SW 레시피 338 B. 작은 수정도 예산 인상과 묶여야 한다(04 영역 0929/04-01 수정 포함). +5. **확장 지점이 없어 제품이 템플릿 파일을 고친다.** 09-02·09-03·08-01(0929)이 그대로이고, 다음 동기화 merge-tree 충돌은 tech-log 10, memento 4다(14 영역). 이번 라운드에 넣은 디자인 검사 규칙 4개는 memento 토큰 8개에 걸린다. + +## 5. 결정이 필요한 것 + +| 항목 | 선택지 | 권고 | 승인자 | +|---|---|---|---| +| 초기 JS 예산 (15-01) | (가) 예산을 올린다. (나) `feature-module.ts` 그래프를 초기 청크에서 떼어 낸다. (다) 둘 다 | (나)를 먼저 측정한다. 기능이 늘수록 (가)만으로는 매번 다시 막힌다. 동시에 번들 검사를 PR 단계로 옮긴다 | 템플릿 소유자 | +| 확장 지점 범위 (09-02, 09-03, 0929/08-01) | (가) 템플릿이 확장 지점을 연다. (나) 제품이 템플릿 파일을 고치는 것을 공식 경로로 두고 문서화한다 | 지난 라운드와 같다. 세 번 충돌한 파일부터 (가). 효과는 다음 동기화 충돌 수로 잰다 | 템플릿 소유자 | +| 0929/03-01 수정 위치 | (가) 프론트 분류기가 problem code로 409를 나눈다. (나) 백엔드 계약에 "처리 중" status를 정한다 | 둘 다. 프론트는 모르는 409를 `MAYBE_APPLIED`로 본다 | 템플릿 소유자, 백엔드 템플릿 소유자 | +| 배포 job과 운영 검사 (13-01) | (가) CI 계약에 배포 job 자리를 열고 운영 검사가 배포된 build id를 비교한다. (나) 배포는 CI 밖에 두고 운영 검사만 build id를 비교한다 | 로드맵 6(CI/CD 자동화)과 함께 정한다. 어느 쪽이든 build id 비교는 먼저 넣는다 | 템플릿 소유자 | +| 시각 테스트 글꼴 (11-02) | (가) `fonts.conf`로 세 글꼴 폴더만 보이게 한다. (나) 컨테이너 이미지. (다) 글꼴 파일 번들 | (가). 골든을 다시 찍지 않아도 된다(실험 5/5) | 템플릿 소유자 | + +## 6. 미검증 (36.5-5) + +| 무엇 | 왜 | 확인하려면 | +|---|---|---| +| CI 러너에서의 실제 결과 | Gitea Actions가 꺼져 있다(U-1). 외부 API를 부르지 않았다 | runner 1대와 PR 1건 | +| 실제 스크린 리더 | 접근성 트리(aria snapshot)로 대신했다 | NVDA·VoiceOver 수동 점검(`docs/accessibility/manual-checklist.md`) | +| 실제 백엔드·SSE 서버·푸시 서비스와의 통합 | 모두 가짜 실행기·MSW·jsdom으로 재현했다 | 짝 백엔드와 통합 환경 | +| 제거 드릴 일부(`test:realtime-removal` 등) | fixture 안에서 pnpm을 불러 worktree에서 돌리지 않았다. `test:sample-removal`은 메인에서 통과(13 checks) | 메인 repo에서 오케스트레이터가 실행 | +| 실기기·모바일 CPU 성능 | 데스크톱 headless만 측정했다 | 실기기 측정 | +| 다운스트림 두 repo의 전체 diff | 이번에는 일부 우회만 다시 읽었다 | 다음 동기화 때 | + +## 7. 개선 순서 (36.5-6) + +| 순서 | 대상 | 이유 | 완료 기준 | +|---|---|---|---| +| 1 | 09-01, 0929/03-01, 0929/04-01, 0929/06-01, 11-01 + 0929/11-01, 12-01 | High와 P1이고 수정이 작다. 각각 막는 테스트를 먼저 넣는다(지금은 수정과 결함을 구분하는 테스트가 없다) | 각 영역 문서의 완료 기준. 수정 전에 실패하는 테스트가 있어야 한다 | +| 2 | 15-01, 08-01, 11-02, 0929/10-01 | 도입·머지 신뢰를 막는 P1 | 기능 1개 추가 후 예산 안, 48rem 미만 기능 손실 없음, 맨 Ubuntu에서 시각 5/5, 1코어 통과 | +| 3 | 16-01, 16-02, 07-03, 14-01, 14-03, 14-05 | 개발 매뉴얼(`docs/manual/`)과 기능 생성 명령의 재료. 매뉴얼이 실제 절차와 같아야 한다 | 생성 명령으로 만든 기능이 모든 게이트를 통과하고 무관한 테스트를 깨지 않는다 | +| 4 | 13-01, 13-02 | 로드맵 3·6(Gitea 템플릿 시작, CI/CD)과 함께 | 5절 결정 후 | +| 5 | 나머지 P2·P3 | 영역별 | 각 영역 문서 | + +## 8. 재검토 조건 (36.5-7) + +- 위 개선 순서 1·2가 끝나면 해당 영역만 다시 본다. +- 개발 매뉴얼과 기능 생성 명령이 생기면 16 영역을 그 명령으로 만든 기능 기준으로 다시 본다. +- 실제 CI runner가 켜지면 12·13 영역의 미검증을 닫는다. +- SW·realtime·OPFS를 실제로 조립하는 제품이 생기면 해당 영역을 그 제품 기준으로 다시 본다. + +## 9. 리뷰 범위 (36.1) + +| 항목 | 기록 | +|---|---| +| 대상 | `clean-architecture-frontend-template`, 브랜치 `fix/ui-design-audit-2026-11-01` / `d99301b`(트리 기준). 이 커밋은 `main`(`752a61f`)에 UI 감사 수정(`docs/reviews/2026-11-01-ui-design-audit.md`)을 더한 것이다. 리뷰가 끝난 뒤 커밋 규칙(`design-docs/conventions/commit-and-pr.md`)에 맞춰 메시지만 다시 썼다. 같은 트리가 지금 `c0c5d9c`다(`git diff d99301b c0c5d9c` 비어 있음). 영역 문서의 `d99301b`는 이 트리를 가리킨다 | +| 목적과 실행 구성 | 프론트엔드 템플릿(reference implementation). 브라우저 SPA + 정적 호스팅 + SW. SSR 없음 | +| 필수 요구·규모 | 기능 수 증가 축만 목표가 있다. 사용자 목표: 템플릿으로 서비스를 빠르게 만들어 desktop 서버에 배포(PRODUCT.md) | +| 읽은 범위 | `src/` 전체, `tests/` 전체(일부 표본), `scripts/`, `config/`, `.gitea/`, `docs/`, `recipes/`, 루트 설정 | +| 수행한 테스트·실험 | 4.1절 게이트. 각 영역 대상 테스트, 분리 worktree에서 변이·결함 주입(합계 140종 이상), 3엔진 Playwright(01·02·06·08·11), 빌드 실험(06·13·15·16), 랩 성능 5회×2(15), 참조 기능 복사 실험(16). 브라우저·빌드 실행은 공유 잠금으로 직렬화했다 | +| 이전 리뷰와 비교 | `2026-09-29-maturity-review`의 발견과 `FOLLOW-UP.md`를 현재 코드에서 다시 확인했다. 이전 실행 결과는 증거로 쓰지 않았다 | + +### 9.1 게이트 실행 결과 (오케스트레이터, `d99301b`, nproc 22) + +| 게이트 | 결과 | 시간 | +|---|---|---| +| `check:architecture` | 통과 | 10초 | +| `check:types` | 통과 | 6초 | +| `lint` | 통과 | 11초 | +| `test:unit` | 통과 — 165파일, 2,353개 | 13초 | +| `test:component` | 통과 — 34파일, 211개 | 8초 | +| `test:integration` | 통과 — 13파일, 155개 | 10초 | +| `test:contract` | 통과 — 3파일, 15개 | 1초 | +| `test:runtime-schema` | 통과 — 3파일, 56개 | 1초 | +| `verify:documentation` | `PASS_SCOPED` | 1초 | +| `check:adapter-inventory` | 통과 — 145파일 | 0초 | +| `check:ci` | 통과 — 27 gates | 2초 | +| `test:system` | **실패** — 2 failed / 110 passed. 11-01(PID 조회, 항상 실패)과 0929/11-01(옛 문자열) | 53초 | +| `check:design-system` | 통과 | 0초 | +| `check:i18n` | 통과 | 1초 | + +### 9.2 영역 분할 (다음 리뷰에서 재사용) + +지난 리뷰 9.5절의 01~14에 두 영역을 더했다. + +| 번호 | 영역 | 경로·대상 | 깊게 본 관점 | +|---|---|---|---| +| 15 | 성능 실측·최적화 | 빌드 산출물, 랩 측정, 테스트 실행 시간 | 10, 13, 14, 20 | +| 16 | 폴더 구조·리팩토링·기능 개발 패턴 | repo 구조, `src/features/reference-feature/`, 아키텍처 문서 | 2, 3, 4, 9, 22, 23, 24, 27 | + +### 9.3 합친 중복 + +| 대표 | 같은 결함 | 이유 | +|---|---|---| +| 15-01 | 16 영역의 "기능 1개 추가 시 예산 초과" 관찰, FOLLOW-UP P1 | 같은 원인(초기 청크 구성)과 같은 검사 공백 | +| 11-02 | UI 감사 UI-05의 남은 절반 | 같은 원인(실행 환경 글꼴 미고정) | +| 09-09 | 0929/08-05 | 08 영역이 같은 결함이라고 지적 | +| 0929/06-01 | 13 영역의 같은 재현 | 지난 라운드에서 이미 13-01과 합쳤다 | + +### 9.4 리뷰 중 안전 사항 + +- worktree에서는 pnpm을 부르지 않게 했다(지난 라운드 사고). 15 영역에서 integration 테스트 하나가 임시 복사본 안에서 pnpm을 띄웠지만, 메인 `node_modules`는 그대로였다(오케스트레이터가 `node_modules/.modules.yaml`과 `git status`로 확인). +- 모든 영역이 자기 문서 하나만 메인 repo에 썼다. 모든 worktree는 정리됐다. + +## 10. 이번 라운드 추가 렌즈 요약 + +사용자가 이번 라운드에 요구한 리팩토링·성능·폴더 구조·테스트 성능·기능 개발 패턴의 핵심만 모은다. 상세는 각 영역 문서에 있다. + +- **성능(15)**: 초기 로드의 58%가 JS 다운로드다. build id만 바꿔도 매 빌드 96 KB가 바뀌는데, react-dom을 따로 떼면 41 KB로 줄어 릴리스 간 캐시 재사용이 늘어난다(번들 테스트 통과). CSS와 라우트 합계는 예산에 들어가지 않는다(15-03). +- **테스트 성능(10·15)**: `test:unit` 12.6초 중 54%가 프로세스를 띄우는 테스트다(빠른 계층에 섞임, 15-04). setup 경량화로 세 계층 합산 1.3~2.7초를 줄일 수 있다. coverage 실행은 57초. 테스트 폴더 전체를 `npx vitest`로 한 번에 돌리면 부하 21에서 79건이 timeout으로 실패한다(15-05, 07 영역도 관찰). +- **폴더 구조(14·16)**: 입구 문서가 실제 폴더 9개 중 3개(platform·apps·contexts)를 설명하지 않고 없는 `src/domain`을 그린다(14-03). kernel 폴더에 공유 코드가 아닌 port 구현 2개가 있다(05-04). +- **리팩토링 후보**: 각 영역 문서의 "리팩토링 후보" 절. 공통 주제는 두 곳에 쓴 정보를 하나로 줄이는 것이다(4절 원인 3). +- **기능 개발 패턴(디자인 패턴 틀)과 매뉴얼 입력(16)**: 템플릿은 `reference-feature`로 수직 경계 패턴(feature module 등록, route·API·query contribution, gateway 포트와 HTTP adapter, DTO 스키마·mapper, `Result`/`AppFailure`, form schema·command mapper, list·detail·form·status 페이지)을 제공한다. 빠진 것과 기능 추가 작업 순서·판단 지점은 [16 영역 문서](16-structure-patterns.md)의 패턴 목록과 "매뉴얼 입력" 절에 있다. 다음 단계인 `docs/manual/`과 기능 생성 명령의 재료다. + +## 11. 28개 관점 판정 (36.2) + +영역별 판정 기호: O 충족 · P 부분 충족 · X 미충족 · ? 미검증 · - 적용 제외 · > 다른 영역에서 평가. 영역 순서는 01부터 16까지다. 종합 판정은 평균하지 않는다. 한 영역이라도 X면 X다(35.7절). + +미충족(X)의 이유: +- 3 변경 용이성 — 09 영역: 확장 지점이 없어 제품이 템플릿 파일을 고친다(09-02, 09-03). +- 6 실패 성숙도 — 04 영역: SSE 끊김에서 재연결이 멈춘다(0929/04-01). +- 18 배포 성숙도 — 13 영역: 배포 job 자리가 없고 운영 검사가 옛 release를 볼 수 있다(13-01). +- 19 설정 성숙도 — 06·13 영역: SW 빌드가 런타임 설정을 덮어쓰고(0929/06-01), 자리표시자 endpoint가 승인된다(13-02). +- 21 Guardrail 성숙도 — 11 영역: `test:system`이 항상 실패하고(11-01) 시각 골든이 호스트 글꼴에 의존한다(11-02). +- 25 조직 확장성 — 09 영역: 제품이 같은 파일을 고쳐 동기화마다 충돌한다(09-02, 09-03). +- 28 회복 가능성 — 02 영역: preview dispose가 download grace 중 URL까지 revoke한다(02-01). + +| 번호 | 관점 | 영역 01~16 | 종합 | +|---|---|---|---| +| 1 | 코드 성숙도 | `OPPOOPPPP>>->>>>` | P | +| 2 | 구조적 성숙도 | `OP>OOOOOP>>P>>>P` | P | +| 3 | 변경 용이성 | `OOPPPPPPXPPPPPPP` | X | +| 4 | 인지 부하 | `PPPPPPPPPPPPPPPP` | P | +| 5 | 위험 가시성 | `PPPPPPPPPPPPPPPP` | P | +| 6 | 실패 성숙도 | `PPPXPPOPPPO-O>>>` | X | +| 7 | 운영 성숙도 | `OPPPPP>>P-P>>>P-` | P | +| 8 | 디버깅 가능성 | `PPPPPPPPPPPPPPPP` | P | +| 9 | 유지보수 성숙도 | `PPPPPPPPPPPPPPPP` | P | +| 10 | 테스트 성숙도 | `PPPPPPPPPPPPPPPP` | P | +| 11 | 데이터 성숙도 | `PP-OPO>-P>-->-->` | P | +| 12 | 동시성 성숙도 | `POPOPP-O>PO->->>` | P | +| 13 | 확장성 | `PO>P?PP>P>P>>>PP` | P | +| 14 | 성능 성숙도 | `PPOP?POP>PP?P>PP` | P | +| 15 | 보안 성숙도 | `OPOOPPPPP>>OP>>>` | P | +| 16 | 의존성 성숙도 | `O->O-P>>->PPPP>>` | P | +| 17 | API / Contract 성숙도 | `PPPPPPPPPP>P>P>P` | P | +| 18 | 배포 성숙도 | `OP>PPP>O>>P>X>P>` | X | +| 19 | 설정 성숙도 | `PPPPPXPPPPPPXPO>` | X | +| 20 | 개발자 경험 | `P>PP>PPPPPPPPPPP` | P | +| 21 | Guardrail 성숙도 | `PPPOPPPPPPX?PPPP` | X | +| 22 | 추상화 성숙도 | `OPPPPOPPPPPP>>>P` | P | +| 23 | 일관성 | `PPOPPPPPPPPPPPPP` | P | +| 24 | 네이밍 / 의미 성숙도 | `PPPPPPPPPPPPPPPP` | P | +| 25 | 조직 확장성 | `-->-?-PPX->P-P>P` | X | +| 26 | Ownership 성숙도 | `P>P-?PP?>PPPPP>>` | P | +| 27 | 삭제 가능성 | `P?P?P?P>PPPP>P>P` | P | +| 28 | 회복 가능성 | `PXPPPP-OP-P-P>>>` | X | + +## 12. 발견 색인 + +이번 라운드 영역 문서에 36.3 양식으로 적힌 발견 95건이다. 그중 5건(09-01~09-05)은 지난 라운드 이월을 새 ID로 다시 적은 것이고, 새 발견은 90건이다: High 0 · Medium 24 · Low 66, P1 6 · P2 33 · P3 51, 확인된 결함 55 · 구조적 위험 20 · 개선 제안 15. 각 영역 문서 2절의 "지난 발견 재확인" 표에만 있는 이월 항목(0929/03-01 등)은 여기 세지 않았다. 2절 차단 항목에는 포함했다. + +| ID | 심각도 | 우선순위 | 성격 | 관련 관점 | 내용 | +|---|---|---|---|---|---| +| [09-01](09-app-core.md) | High | P1 | 확인된 결함 | 17, 6, 5, 8, 10, 3, 30.5 (HTTP | 조립 루트의 자격증명 판단이 인증 프로필을 보지 않아 `ANONYMOUS` operation이 어떤 세션 상태에서도 전송되지 않는다 (이월: 0929-09-01) | +| [08-01](08-presentation.md) | Medium | P1 | 확인된 결함 | 1, 10, 23, 20 | 좁은 화면(모바일, 또는 데스크톱 약 170% 이상 확대)에서 색상 테마 선택·세션 상태·브랜드가 사라지고 대체 수단이 없다 | +| [09-02](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 9, 25, 22, 15, 19, 20, 13, | 제품 capability·자격증명·제품 설정을 넣을 확장 지점이 없어 제품이 `runtime-adapters.ts`를 직접 고쳐야 한다 (이월: 0929-09-02) | +| [09-03](09-app-core.md) | Medium | P1 | 구조적 위험 | 3, 2, 22, 25, 23, 32.4, 30.3 | 라우터 조립이 `AppShell` 한 틀과 플랫폼 홈을 고정해 기능이 `/`나 자기 레이아웃을 가질 수 없다 (이월: 0929-09-03) | +| [11-01](11-tests-browser-release-scale.md) | Medium | P1 | 확인된 결함 | 10, 21, 8, 24 (+30.8) | `tests/system`의 cgroup 테스트는 provider가 끝난 뒤 그 PID의 argv를 조회해서, 부하와 관계없이 항상 실패한다 (09-29/11-06 원인 재판정) | +| [11-02](11-tests-browser-release-scale.md) | Medium | P1 | 확인된 결함 | 10, 21, 19, 20, 5, 16 (+30.8) | 시각 회귀 골든이 작성자 PC의 글꼴 4종으로 찍혀 있고 실행 환경의 글꼴을 고정하지 않아, 같은 코드라도 글꼴이 다른 호스트(CI 러너 포함)에서 FE-GATE-008이 실패한다 (UI-05 남은 절반) | +| [13-01](13-build-release-supply-chain.md) | Medium | P1 | 확인된 결함 | 18, 21, 5, 28, 3, 26 (+30.7, 3 | 운영 단계 검사가 배포된 release가 승격 후보인지 확인하지 않고, 배포 job을 넣을 자리도 없다 | +| [13-02](13-build-release-supply-chain.md) | Medium | P1 | 확인된 결함 | 19, 21, 15, 18, 20 (+30.1, 30. | 공개 대상 승인이 템플릿 자리표시자 endpoint(`*.example.com`)를 통과시키고, CI에서는 `RUNTIME_*`로 바꿀 길이 없다 | +| [15-01](15-performance.md) | Medium | P1 | 구조적 위험 | 14, 21, 13, 20, 18 | 초기 JS 예산 여유가 1,293 B인데, 넘었는지 보는 검사는 release 단계에서만 돈다 | +| [01-01](01-adapters-browser-transfer.md) | Medium | P2 | 확인된 결함 | 6, 5, 10, 14, 17, 23 | part 단계(발급·PUT)는 `Retry-After`를 읽지 않는다 — 문서는 읽는다고 하고, 테스트는 가짜 실행기로만 확인한다 | +| [02-01](02-adapters-browser-files-cache.md) | Medium | P2 | 구조적 위험 | 5, 22, 24, 6, 17 | `previews.dispose()`가 공유 lease registry 전체를 비운다 — download의 grace 중 URL까지 revoke하고, runtime이 살아 있는 동안 preview를 영구히 끈다 | +| [03-01](03-adapters-http-state.md) | Medium | P2 | 확인된 결함 | 5, 21, 22, 17, 20, 24 | 조회 정의의 namespace를 무효화 레지스트리와 대조하지 않는다 | +| [04-01](04-adapters-realtime.md) | Medium | P2 | 확인된 결함 | 17, 5, 20, 23, 8, 22, 10, 4 | `RealtimeResult`를 받는 경계마다 런타임 규칙이 다르고, 동결이 필요한 경계에 넘길 결과를 만드는 공개 함수가 배럴에 없다 | +| [07-02](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 3, 5, 21, 22, 23, 24, 10, | HTTP API 하나를 선언 사본(V2 행)과 실행 사본(V3 descriptor)에 두 번 쓰고, 둘을 잇는 검사는 6개 필드뿐이다 | +| [07-03](07-contracts.md) | Medium | P2 | 구조적 위험 | 17, 3, 5, 15, 22, 23, 27, 20, | zod를 검증기로 바꾸는 어댑터가 참조 기능 안에만 있어 기능마다 복사되고, `RuntimeValidator`는 검증하지 않는 검증기를 구분하지 못한다 | +| [07-04](07-contracts.md) | Medium | P2 | 확인된 결함 | 17, 21, 5, 1, 18, 30.3 | `TEMPLATE_FIXTURE` 출처를 아무 기능이나 쓸 수 있고, 그 기능의 API는 릴리스 계약 집합에서 조용히 빠진다 | +| [08-02](08-presentation.md) | Medium | P2 | 확인된 결함 | 5, 1, 8, 23, 24 | URL 검색값만 바뀌어도 라우트 이동으로 처리해, 포커스를 `
`으로 옮기고 맨 위로 스크롤하고 `route.changed`를 보고한다 | +| [08-03](08-presentation.md) | Medium | P2 | 구조적 위험 | 5, 17, 24, 22, 4, 6 | 서버 상태 훅이 raw(legacy) 입력을 공개 API로 받아, 기능이 멱등 키·scope 검사 없이 쓰기를 보낼 수 있고 그 경로의 "다시 보내기"는 아무것도 하지 않는다 | +| [09-06](09-app-core.md) | Medium | P2 | 확인된 결함 | 21, 4, 5, 8, 1, 13, 17, 20, 32 | 기능 라우트 경로와 소유 context 루트의 관계를 아무도 검사하지 않아, 루트 밖 라우트가 탐색 메뉴에는 나오고 URL은 `NOT_FOUND`가 된다 (새 발견) | +| [12-01](12-guardrails-ci.md) | Medium | P2 | 확인된 결함 | 21, 10, 9, 23, 24, 5 | 컴포넌트 토큰 사용 규칙이 이름 앞부분만 맞춰 본다 — `--field-border`를 읽는 스타일이 없는데 통과하고, UI-03은 "충족"으로 닫혔다 | +| [13-03](13-build-release-supply-chain.md) | Medium | P2 | 구조적 위험 | 18, 16, 20, 26 (+30.2, 30.6, 3 | 운영 승격의 runner 전제가 workflow의 runner 전제와 어긋나고, provider 없이 배포하는 경로가 문서에 없다 | +| [13-04](13-build-release-supply-chain.md) | Medium | P2 | 확인된 결함 | 18, 21, 19, 20, 10 (+30.1) | 호스팅 계약이 SPA fallback과 SW 스크립트 헤더를 선언·검사하지 않는다 | +| [14-01](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 9, 4, 26, 27, 21, 24, 30.3 | 코드와 현재 문서가 결정 근거를 "지워도 되는" 이력 문서로만 가리킨다 | +| [14-03](14-template-product-docs.md) | Medium | P2 | 확인된 결함 | 4, 9, 20, 24, 2 | 입구 문서가 실제 폴더 9개 중 3개를 설명하지 않고, 없는 `src/domain`을 계층으로 보여 준다 | +| [14-05](14-template-product-docs.md) | Medium | P2 | 구조적 위험 | 9, 21, 5, 20, 19 | 현재 계약 문서의 drift를 잡는 검사가 3가지뿐이고, 그중 하나는 repo 밖 7월 diagram의 사본끼리만 대조한다 | +| [16-01](16-structure-patterns.md) | Medium | P2 | 확인된 결함 | 3, 20, 4, 21, 25, 9 (+30.3, 30 | 기능 추가 절차 문서는 폴더 밖 수정을 4행으로 적지만, 참조 모양 기능은 폴더 밖 7묶음과 결정 2가지가 더 필요하다 — 이 주장을 지키는 테스트는 라우트·무효화 없는 기능만 넣는다 | +| [16-02](16-structure-patterns.md) | Medium | P2 | 확인된 결함 | 10, 3, 25, 27, 20, 8 (+30.5) | 기능 하나를 추가하면 무관한 테스트 3개가 깨지고, 공유 MSW 시나리오 카탈로그는 참조 기능 operation 3개에 묶여 있다 | +| [03-02](03-adapters-http-state.md) | Low | P2 | 확인된 결함 | 8, 6, 24, 20, 5 | 전송 전 실패가 모두 "입력 거절"로 합쳐지고 원인이 진단에 남지 않는다 | +| [03-05](03-adapters-http-state.md) | Low | P2 | 확인된 결함 | 8, 24, 10, 6 | 분류기 실패를 기록한다는 주장과 달리 흔적이 없고, 안전 기본값을 고정하는 테스트도 없다 | +| [08-04](08-presentation.md) | Low | P2 | 확인된 결함 | 23, 4, 9 | h2·h3의 글자 크기·굵기가 본문과 같아 화면 위계가 보이지 않는다 | +| [08-06](08-presentation.md) | Low | P2 | 확인된 결함 | 23, 1 | 한국어 줄바꿈 규칙이 없어 한국어 단어가 중간에서 끊긴다 | +| [08-08](08-presentation.md) | Low | P2 | 확인된 결함 | 14, 13, 22 | 갤러리에서만 쓰는 primitive가 셸이 쓰는 primitive와 같은 파일에 있어 초기 청크에 실린다(약 3.9 KB gzip) | +| [09-09](09-app-core.md) | Low | P2 | 확인된 결함 | 8, 7, 23 (라우터 배선은 08 영역과 겹침) | context·feature 오류 경계가 잡은 실패를 진단에 남기지 않고, 지원 참조로 buildId만 보인다 (새 발견) | +| [10-01](10-tests-fast-layers.md) | Low | P2 | 확인된 결함 | 10, 17, 21, 24, 5 | 이벤트 계약 정확성 테스트가 fixture에 이벤트가 없어 첫 줄에서 return한다 — 이름이 말하는 규칙을 아무도 검사하지 않는다 | +| [10-04](10-tests-fast-layers.md) | Low | P2 | 확인된 결함 | 21, 10, 20 | 빠른 계층에 `it.skip`·`it.todo`가 들어가도 어떤 게이트도 실패하지 않는다 | +| [11-03](11-tests-browser-release-scale.md) | Low | P2 | 확인된 결함 | 10, 21, 9 | 시각 회귀 허용치가 "이미지 전체의 0.2%"라서 UI-04 회귀(1,146 px)를 통과시키고, 갱신되지 않은 compact 골든도 175 px 차이로 통과한다 | +| [12-02](12-guardrails-ci.md) | Low | P2 | 확인된 결함 | 10, 21, 17, 8 | 새 디자인 규칙 4개를 지키는 음성 fixture·테스트가 없다 — 규칙을 모두 꺼도 모든 게이트가 통과한다 | +| [13-05](13-build-release-supply-chain.md) | Low | P2 | 확인된 결함 | 19, 28, 8, 20, 24 | "재빌드 없이 설정을 바꾼다"는 비상 스위치에 검증된 절차가 없다 | +| [15-02](15-performance.md) | Low | P2 | 확인된 결함 | 9, 14, 20, 24, 8 | `performance-evidence.md`의 기준선·청크 구성·분류 규칙이 현재 빌드와 다르다 | +| [16-03](16-structure-patterns.md) | Low | P2 | 확인된 결함 | 24, 8, 27, 20, 3 | 유일한 bearer 인증 프로필 이름이 `REFERENCE_EXTERNAL_BEARER`이고, 틀리게 쓰면 어느 operation인지 말하지 않는 오류가 모든 게이트에서 난다 | +| [16-04](16-structure-patterns.md) | Low | P2 | 구조적 위험 | 3, 23, 24, 22, 4 (+30.5) | 샘플 페이지가 라우트 경로를 문자열로 8곳에 다시 적고 route 입력을 cast한다 — 문서가 권하는 URL builder와 route별 타입이 기능 쪽으로 오지 않는다 | +| [16-07](16-structure-patterns.md) | Low | P2 | 개선 제안 | 3, 20, 22, 17 (+30.5) | 실무에서 자주 필요한 기능 패턴 7개는 런타임만 있거나 아무것도 없고, 복사할 기능 예제가 없다 | +| [01-02](01-adapters-browser-transfer.md) | Low | P3 | 개선 제안 | 14, 23 | `FILE_BYTE_SOURCE`로 재개하면 이미 수락된 part까지 다시 복사하고 해시한다 | +| [01-03](01-adapters-browser-transfer.md) | Low | P3 | 구조적 위험 | 14, 5, 19, 13 | 메모리 상한 식의 `partBufferCopyFactor`가 코드의 실제 복사 수가 아니라 정책 설정값이다 | +| [01-04](01-adapters-browser-transfer.md) | Low | P3 | 확인된 결함 | 14, 12, 13 | 같은 asset·preset을 동시에 resolve하면 probe가 호출 수만큼 돈다 | +| [02-02](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 15, 5, 21, 23 | download 정책의 `safeExtension`은 금지 확장자 목록도 media type도 검사하지 않는다 — 문서는 "content type과 맞지 않는 executable extension 교체"라고 한다 | +| [02-03](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 8, 23, 24 | stage된 후보를 재검증하다 읽기 오류가 나면 stage 결과와 관측이 `CACHE_ACTIVATE`로 기록된다 | +| [02-04](02-adapters-browser-files-cache.md) | Low | P3 | 구조적 위험 | 10, 15, 6, 12 | 이 영역의 보호 규칙 7개가 변이 실험에서 살아남는다 | +| [02-05](02-adapters-browser-files-cache.md) | Low | P3 | 확인된 결함 | 8, 24 | cross-context publish 실패는 원인과 상관없이 관측 reason이 `INVALID_ENVELOPE`다 | +| [03-03](03-adapters-http-state.md) | Low | P3 | 구조적 위험 | 22, 3, 5, 21 (39.5 선언·실행 중복) | mutation 정책이 `operationId`·`requiresIdempotencyKey`를 계약과 따로 손으로 적는다 | +| [03-04](03-adapters-http-state.md) | Low | P3 | 구조적 위험 | 5, 22, 6, 4 | 효과 판정과 화면 분류가 두 함수에서 따로 정해지고, 어긋나면 화면이 서로 반대되는 안내를 한다 | +| [03-06](03-adapters-http-state.md) | Low | P3 | 개선 제안 | 10, 8, 15 | V3 바인딩의 시간 초과 분류와 서버 반사 correlation 값의 문법 검사를 고정하는 테스트가 없다 | +| [04-02](04-adapters-realtime.md) | Low | P3 | 확인된 결함 | 24, 23, 8, 7, 17 | `IDLE_TIMEOUT`이 effect·recovery·close 마감에도 쓰여, 설계 13.1의 의미(전송 idle → 제한된 재연결)와 다르다 | +| [04-03](04-adapters-realtime.md) | Low | P3 | 구조적 위험 | 10, 13, 9, 21 | WebSocket 구독별 초당 이벤트 상한(256)이 테스트도 설계 11절 상한표에도 없다 | +| [05-01](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 23, 24, 17, 5, 11 | registry의 `CACHE_INVALIDATION_PULSE` 행이 실제 값과 다른 codec을 적어, StoragePort로 읽으면 다른 어댑터의 값을 지운다 | +| [05-02](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 8, 24, 7 | Web Storage 진단 이벤트가 실패 원인을 버려 값 손상과 저장소 불가를 구분할 수 없다 | +| [05-03](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 5, 21, 10, 23 | lifecycle 런타임의 "유일한 리스너 주인" 규칙이 이미 깨졌고, 검사도 직접 테스트도 없다 | +| [05-04](05-adapters-storage-kernel.md) | Low | P3 | 개선 제안 | 22, 2, 9 | kernel 폴더의 port 구현 2개가 공유 메커니즘이 아닌데 폴더 단위 예외를 받는다 | +| [05-05](05-adapters-storage-kernel.md) | Low | P3 | 확인된 결함 | 9, 4, 24 | kernel 주석의 `file:line` 참조가 다른 코드를 가리킨다 | +| [05-06](05-adapters-storage-kernel.md) | Low | P3 | 구조적 위험 | 10, 15, 11 | Web Storage 어댑터·codec의 분기 5개를 테스트가 잡지 못한다 | +| [06-01](06-adapters-service-worker-push.md) | Low | P3 | 확인된 결함 | 19, 17, 1, 3 | Web Push 정상 클릭의 대상 URL이 router base path를 무시해 하위 경로 배포에서 앱 밖을 엶 | +| [06-02](06-adapters-service-worker-push.md) | Low | P3 | 확인된 결함 | 28, 18, 26, 5 | 운영 문서는 새 워커가 `requestActivation()`으로만 활성화된다고 적지만, 브라우저는 탭이 모두 닫히면 waiting 워커를 활성화함 | +| [06-03](06-adapters-service-worker-push.md) | Low | P3 | 구조적 위험 | 5, 17, 9, 24, 4 | 설계의 페이지 쪽 계약 셋(PAGE_HELLO 호환 handshake, UPDATE_READY, SW reload guard)이 없고, 흔적만 남음 | +| [06-04](06-adapters-service-worker-push.md) | Low | P3 | 개선 제안 | 10, 12, 15 | SW 보호 장치 3개는 지워도 테스트가 모두 통과함 | +| [06-05](06-adapters-service-worker-push.md) | Low | P3 | 개선 제안 | 14, 13 | 릴리스마다 사전 캐시 전체를 `no-store`로 다시 받음 | +| [07-01](07-contracts.md) | Low | P3 | 확인된 결함 | 24, 23, 4, 22, 9, 26 | `MappingResult`라는 이름이 두 모양을 가리키고, "정본"으로 적힌 모양은 쓰는 곳이 없으며, 실행 API는 폐기 별칭을 요구한다 | +| [07-05](07-contracts.md) | Low | P3 | 구조적 위험 | 24, 23, 4, 22 | 오류 어휘가 둘이고(`AppFailure`·`AppError`), "다시 시도"를 세 이름으로 적는데 관계가 타입·주석에 없다 | +| [07-06](07-contracts.md) | Low | P3 | 확인된 결함 | 10, 21, 5, 1 | 조립기·선언 검증의 쓰기 API 규칙 5개가 테스트 없이 남아 있다 — 지워도 관련 테스트 686건이 통과한다 | +| [07-07](07-contracts.md) | Low | P3 | 구조적 위험 | 5, 24, 17, 6 | `commandRecovery`는 `KEYED` 쓰기에 필수지만 실행기는 읽지 않고, 결과 불명 쓰기를 누가 수습하는지 타입 옆에 없다 | +| [08-05](08-presentation.md) | Low | P3 | 확인된 결함 | 23, 24, 22, 10 | 상태 화면·오류 요약의 제목이 h2로 고정돼, 카드나 섹션 안에 넣으면 제목 순서가 뒤집힌다 | +| [08-07](08-presentation.md) | Low | P3 | 확인된 결함 | 23, 24, 1 | en-US로 바꾸면 예제 화면 4개는 한국어 본문인데 문서 언어가 en-US다 | +| [08-09](08-presentation.md) | Low | P3 | 확인된 결함 | 10, 21 | 접근성 기본 장치 일부를 지키는 테스트가 없다 — 변이 4종이 component 211개를 모두 통과 | +| [09-04](09-app-core.md) | Low | P3 | 구조적 위험 | 24, 2, 21, 27, 4, 30.7 | `NOT_INSTALLED` 표시가 여러 뜻으로 쓰이고, 생성기 밖에서 조립하는 제품 도메인의 공식 경로가 없다 (이월·재판정: 0929-09-04, Medium·P2 → Low·P3) | +| [09-05](09-app-core.md) | Low | P3 | 개선 제안 | 9, 25, 30.3 | 제품이 고치도록 설계한 선택 파일에 템플릿 상태 설명이 같은 블록으로 섞여 있다 (이월: 0929-09-05) | +| [09-07](09-app-core.md) | Low | P3 | 확인된 결함 | 5, 7, 22, 20, 30.2 (realtime 런 | 선택 파일은 "여기 추가하면 설치된다"고 하지만 realtime·webWorkers·offlineCommands는 아무것도 시작되지 않고, 진단 스냅샷은 active로 보고한다 (새 발견) | +| [09-08](09-app-core.md) | Low | P3 | 개선 제안 | 22, 5, 2 | 기능이 선언한 capability만 받는다는 설명은 타입에서만 지켜지고, 실행 시에는 capability 객체 전체가 전달된다 (새 발견) | +| [10-02](10-tests-fast-layers.md) | Low | P3 | 확인된 결함 | 10, 24, 6 | Popover의 "Escape 뒤 포커스 반환" 단언이 전제를 만들지 않아 아무것도 검사하지 않는다 | +| [10-03](10-tests-fast-layers.md) | Low | P3 | 구조적 위험 | 10, 6, 15 | 보호 라우트의 "세션 복구 대기" 분기를 어떤 빠른 테스트도 고정하지 않는다 | +| [10-05](10-tests-fast-layers.md) | Low | P3 | 개선 제안 | 14, 20, 4, 9, 3 | `tests/unit`에 도구(scripts) 테스트가 섞여 있어 unit 계층 합산 시간의 58%를 쓴다 | +| [10-06](10-tests-fast-layers.md) | Low | P3 | 개선 제안 | 14, 21, 20, 10, 12 | 머지 단계가 빠른 계층 파일 대부분을 두 번 돌린다 — 비용과 부하 실패 기회가 함께 두 배다 | +| [10-07](10-tests-fast-layers.md) | Low | P3 | 개선 제안 | 14, 12, 10, 20 | 테스트가 프로덕션 시간 상수를 실제 시계로 기다린다 — 5개 테스트가 약 9초를 쓴다 | +| [10-08](10-tests-fast-layers.md) | Low | P3 | 개선 제안 | 9, 23, 22, 10 | 같은 테스트 fixture가 갈라진 복사본으로 다섯 군데에 있다 — `scopeSnapshot` | +| [11-04](11-tests-browser-release-scale.md) | Low | P3 | 확인된 결함 | 5, 24, 10, 9 | 테스트 전략 문서의 "필수 baseline" 목록과 실제 시각 기준선이 다르고, 검사는 기준선 4장 이상만 본다 | +| [12-03](12-guardrails-ci.md) | Low | P3 | 구조적 위험 | 21, 5, 2, 13, 25 | 디자인 규칙이 정해진 파일과 소문자 글자만 본다 — 대문자 키워드, 그라디언트, TSX 인라인, 토큰 재정의, feature CSS가 모두 통과한다 | +| [12-04](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 21, 19, 20, 25, 23, 8 | 디자인 규칙이 정상 CSS를 거부한다 — `color-mix`·알파·`deg` 표면 토큰, `-apple-system`, 패키지로 싣는 글꼴. 규칙 설명은 코드 주석에만 있다 | +| [12-05](12-guardrails-ci.md) | Low | P3 | 확인된 결함 | 9, 27, 21, 20, 24 | 사문화된 npm script 4개가 남아 있고, 게이트 밖 스크립트 검사는 이름 접두어 5개만 본다 | +| [14-02](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 24, 9, 17, 26 | 리뷰 발견 ID가 라운드마다 같은 형식이라, CHANGELOG와 코드 주석의 ID가 어느 리뷰인지 알 수 없다 | +| [14-04](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 30.3, 30.5, 27, 9, 24 | `PRODUCT.md`가 예제 화면을 지울 수 있다고 적지만, 드릴은 reference feature만 지운다. 복사 처리 목록에도 없다 | +| [14-06](14-template-product-docs.md) | Low | P3 | 확인된 결함 | 8, 20 | `verify:documentation`이 route ID 누락을 "scoped-review evidence"가 부족하다고 보고한다 | +| [14-07](14-template-product-docs.md) | Low | P3 | 개선 제안 | 4, 9, 20, 23 | 문서 위치가 문서 상태를 드러내지 않는다 | +| [15-03](15-performance.md) | Low | P3 | 개선 제안 | 14, 21, 13 | 예산이 사용자가 실제로 받는 단위를 재지 않는다 — CSS 제외, lazy는 파일 단위 | +| [15-04](15-performance.md) | Low | P3 | 개선 제안 | 10, 20, 14, 23 | 빠른 테스트 계층의 시간을 프로세스 생성과 실제 대기가 정한다 | +| [15-05](15-performance.md) | Low | P3 | 확인된 결함 | 10, 20, 21 | `npx vitest`로 돌리면 unit 79건이 실패한다 — 테스트가 실행기의 npm 환경변수를 읽는다 | +| [16-05](16-structure-patterns.md) | Low | P3 | 구조적 위험 | 24, 23, 4, 2, 9, 27 | 같은 개념이 두 폴더에 비슷한 이름으로 있다 — 기능 오류 경계 두 벌이 겹쳐 쌓이고, `TelemetryPort` 타입이 둘이고, 소비자 없는 폐기 사본이 남아 있다 | +| [16-06](16-structure-patterns.md) | Low | P3 | 개선 제안 | 2, 4, 22, 9 | 기능 `contracts/` 폴더가 와이어 계약·화면 문구·뷰 모델을 함께 담아 기능 코드의 46%를 차지한다 |