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 라우트에서 `