diff --git a/docs/reviews/2026-09-24-src-full-review.md b/docs/reviews/2026-09-24-src-full-review.md new file mode 100644 index 00000000..87b2b829 --- /dev/null +++ b/docs/reviews/2026-09-24-src-full-review.md @@ -0,0 +1,827 @@ +# src/ 전체 코드 리뷰 + +> 검토일: 2026-09-24 +> +> 검토 기준: `main` / `e59994a` +> +> 검토 범위: `src/` 전체 (diff 리뷰 아님). 약 8.7만 줄, 9개 영역 +> +> 검토 관점: 정확성, 보안, 성능, 구조(중복·경계·파일 크기), 테스트 공백 +> +> 판정: **NEEDS_FIX** +> +> 이 문서는 리뷰 결과 기록이다. 이 리뷰에서 코드는 수정하지 않았다. + +## 1. 결론 + +레이어 규칙과 입력 경계 검증은 전반적으로 잘 지켜져 있다. presentation이 adapter를 직접 import하는 곳이 없고, 신뢰할 수 없는 입력은 크기 상한과 정확한 키 검사를 거친 뒤에 파싱한다. + +문제는 세 가지로 모인다. + +1. **깨끗한 체크아웃에서 게이트가 깨진다.** 생성 파일을 만드는 단계가 dev/build/test/CI 어디에도 없다. +2. **버그가 모듈과 모듈이 이어지는 지점에 몰려 있다.** 모듈 하나하나는 테스트가 있지만, 연결 부분은 테스트가 없다. +3. **같은 로직이 여러 벌로 복사되어 규칙이 서로 다르다.** 한 곳을 고쳐도 다른 복사본은 그대로 남는다. + +## 2. 검토 방법과 표기 + +```text +src/ 8.7만 줄 → 9개 영역으로 분할 → 리뷰 에이전트 9개가 병렬로 읽음 +→ 오케스트레이터가 주요 12건을 코드에서 직접 재확인 → 게이트 직접 실행 +``` + +| 영역 | 경로 | 규모 | +|---|---|---| +| 1 | `src/adapters/browser-transfer/` | 약 12.8k줄 | +| 2 | `src/adapters/browser-files/`, `cache-storage/`, `cross-context-invalidation/` | 약 8k줄 | +| 3 | `src/adapters/http/`, `browser-rpc/`, `query-cache/`, `auth/`, `diagnostics/`, `telemetry/` | 약 8.2k줄 | +| 4 | `src/adapters/realtime/` | 약 10.3k줄 | +| 5 | `src/adapters/storage/`, `platform/`, `browser-file-storage/` | 약 14.9k줄 | +| 6 | `src/adapters/web-push/`, `service-worker/` | 약 5.9k줄 | +| 7 | `src/contracts/` | 약 8.3k줄 | +| 8 | `src/presentation/` | 약 7.8k줄 | +| 9 | `src/application/`, `features/`, `bootstrap/`, `platform/`, `apps/`, `contexts/` | 약 10.6k줄 | + +리뷰 전제 (소유자 결정, `refactor-direction-decisions` 참조): + +- 이 레포는 템플릿이다. 레포 안에서 쓰는 곳이 없는 코드나 빈 레지스트리는 다운스트림용 seam이므로 "죽은 코드"로 보지 않았다. 다만 갈라진 중복 복사본은 문제로 봤다. +- adapter 배럴(`index.ts`)은 공개 경계다. +- adapter는 다른 concrete adapter를 import할 수 없다. 예외는 `src/adapters/platform/`(폴더 전체), `src/adapters/browser-file-storage/result.ts`, `src/adapters/cross-context-invalidation/index.ts`다. + +표기: + +- **심각도**: 긴급(데이터 손실·보안 구멍·기능 고장) / 필수(실제 버그 또는 고쳐야 할 구조 문제) / 권장 / 사소 +- **확신도**: 확인됨(코드 경로를 따라가 반드시 일어남을 확인) / 가능성(조건에 따라 일어남. 확인 방법을 적음) +- **✓ 재확인**: 오케스트레이터가 코드를 직접 다시 읽어 확인한 항목. 나머지는 에이전트 보고이고, 일부는 에이전트가 레포 밖 scratchpad의 node 스크립트로 재현했다. + +## 3. 게이트 실행 결과 + +깨끗한 체크아웃(`e59994a`, `src/.generated/` 없음): + +| 게이트 | 결과 | +|---|---| +| `corepack pnpm check:architecture` | 실패 — `ERR_MODULE_NOT_FOUND: src/.generated/product-feature-index.ts` | +| `corepack pnpm check:types:app` | 실패 — TS 에러 20개 | +| `corepack pnpm lint` | 통과 | +| `corepack pnpm test:unit` | 실패 — 131개 파일 중 18개 실패 | +| `corepack pnpm test:component` | 실패 — 25개 파일 중 13개 실패 | +| `corepack pnpm verify:documentation` | 실패 — 같은 `ERR_MODULE_NOT_FOUND` | + +`node scripts/generate-product-feature-index.ts` 실행 후: + +| 게이트 | 결과 | +|---|---| +| `check:architecture` | 통과 | +| `check:types:app` | 통과 | +| `test:unit` | 통과 — 1779/1779 | +| `test:component` | 통과 — 132/132 | +| `verify:documentation` | `PASS_SCOPED` | + +생성한 `src/.generated/`는 확인 뒤 다시 지웠다. `dev`와 `build`는 실행하지 않았다. 두 명령 모두 같은 import를 거치므로 실패할 것으로 보인다. + +## 4. 먼저 고칠 것 + +| 순위 | 항목 | 위치 | 섹션 | +|---|---|---|---| +| 1 | 깨끗한 체크아웃에서 게이트 실패 | `src/features/installed-product-manifest.ts:4` | 6.0 | +| 2 | 경로 값 `..`가 다른 엔드포인트로 요청을 보냄 | `src/adapters/http/http-contract-bridge.ts:191` | 6.3-1 | +| 3 | 로그아웃 해제 실패 뒤 새 계정이 opt-in 없이 push 등록됨 | `src/adapters/web-push/push-subscription-adapter.ts:345` | 6.6-7 | +| 4 | 파티션 purge가 손상 행 1개에 영구히 막힘 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584` | 6.5-4 | +| 5 | 멱등 키 앞뒤 공백이 잘려 두 명령이 같은 키가 됨 | `src/contracts/mutation-intent.ts:34` | 6.7-1 | +| 6 | 롤링 배포 중 부트 reload 무한 반복 | `src/platform/release/release-mismatch-recovery.ts:59` | 6.9-1 | +| 7 | 킬스위치 기능 ID에 금지어가 있으면 부팅 실패 | `src/contracts/env.ts:80` | 6.7-2 | +| 8 | WS/SSE가 네트워크 끊김·서버 재시작 뒤 재연결 안 함 | `src/adapters/realtime/reconnect-coordinator.ts:1661` | 6.4-2 | +| 9 | 빌드가 다른 탭이 있으면 SW 활성화가 항상 30초 타임아웃 | `src/adapters/service-worker/service-worker-lifecycle.ts:368` | 6.6-2 | +| 10 | 세션 알림마다 캐시 전체 비움 + 앱 트리 remount | `src/adapters/query-cache/server-state-scope-runtime.ts:90` | 6.3-2, 6.8-3 | + +## 5. 영역을 가로지르는 패턴 + +### 5.1 갈라진 복사본 + +같은 개념이 여러 벌 구현되어 있고 규칙이 서로 다르다. 한 벌만 고치면 나머지는 그대로 남는다. + +| 개념 | 복사본 위치 | 차이 | +|---|---|---| +| abort/timeout race | browser-files(`download-delivery-adapter.ts:1032`, `browser-file-vault.ts:872`), realtime 6곳, browser-transfer runtime(`resumable-upload-runtime.ts:1299`) | kernel `src/adapters/platform/abortable-operation.ts`의 `createAbortableOperation`을 쓰지 않음. 일부는 늦게 도착한 자원을 닫지 않음 | +| opaque ID 정규식 | `resumable-upload/checkpoint-schema.ts:11`, `presigned/*`, web-push 3곳 | 첫 글자·길이 규칙이 다름 | +| exact-key 스냅샷 | contracts 6곳(`exact-snapshot.ts:66`, `read-only-registry.ts:54`, `browser-rpc.ts:399`, `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`), realtime 3곳, web-push | enumerable·getter·Proxy 처리 수준이 다름. 두 곳은 우회 가능 | +| IndexedDB 저장 행 검증 | `indexeddb-runtime.ts`, `indexeddb-maintenance.ts`, `indexeddb-governance.ts` | 필드 추가 시 한쪽만 고치면 정상 행이 손상으로 판정됨 | +| OPFS prepared-object 검증 | worker, journal, client | 정책 변경 시 기존 객체가 읽히지 않음 | +| 텔레메트리 전송기 | `src/adapters/telemetry/best-effort-telemetry.ts`, `feature-telemetry.ts`, `src/platform/telemetry/telemetry-pipeline.ts` | rate limit 합산 40/분, credentials 설정·body 스키마가 다름 | +| "한 번만 reload" 가드 | `src/application/use-cases/decide-chunk-recovery.ts`, `src/platform/release/release-mismatch-recovery.ts` | 키 형식·TTL·마커 삭제 규칙이 다름 | +| operationId 형식 | `telemetry.ts:111`, `external-contract-runtime.ts:237`, `api-operations.ts:54`, `browser-rpc.ts:185` | 텔레메트리 규칙이 가장 엄격해서 실패 이벤트가 드롭됨 | +| 자격증명 헤더 검증 | `http-contract-bridge.ts:83`, `http-execution-v3.ts:1100`, `auth/external-session-adapter.ts:37` | CR/LF만 막음. 길이를 UTF-16과 UTF-8로 따로 셈 | + +수렴할 곳은 이미 있다. adapter 공용 로직은 `src/adapters/platform/`(규칙 변경 불필요), 공유 어휘는 `src/contracts/exact-snapshot.ts`와 `read-only-registry.ts`다. + +### 5.2 테스트가 없는 연결 지점 + +모듈 단위 테스트는 각자의 동작을 고정한다. 그런데 연결된 두 모듈이 서로 다른 약속을 하고 있다. + +- 전송 계층 ↔ reconnect: 전송은 `PROVIDER_UNAVAILABLE retryable:true`를 보내는데 reconnect는 이를 종료로 처리한다 (6.4-2). +- event consumer ↔ stream coordinator ↔ 전송: barrier NONE 스트림이 recovery 한 번에 종료된다 (6.4-3). +- SW page controller ↔ worker: drain 요청과 응답의 필터가 서로 맞지 않는다 (6.6-1, 6.6-2). +- 세션 알림 ↔ scope fence ↔ presentation 트리: 알림마다 캐시 비움과 remount가 일어난다 (6.3-2, 6.8-3). +- cross-tab 수신 ↔ query-cache coordinator: GAP이 전체 무효화로 이어진다 (6.2-2). + +### 5.3 텔레메트리 + +영역 3과 9에서 같이 나왔다. occurrences가 항상 1이다 (6.9-2). 리댁션이 문자열 시작 부분만 검사한다 (6.9-3). camelCase operationId의 API 실패 이벤트가 드롭된다 (6.7-5). best-effort fetch에는 타임아웃이 없다 (6.3-10). + +## 6. 영역별 발견 + +### 6.0 공통 — 깨끗한 체크아웃에서 게이트 실패 + +**[긴급·확인됨 ✓]** + +- 위치: `src/features/installed-product-manifest.ts:4` +- 문제: 이 파일이 `../.generated/product-feature-index.ts`를 import한다. `.gitignore:4`가 `.generated/`를 제외하므로 이 파일은 커밋되지 않는다. 생성 명령은 `generate:feature-index`(`scripts/generate-product-feature-index.ts`)인데, `dev`/`build`(`scripts/build-frontend.ts`)/`check:*`/`test:*` 스크립트, `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, README 어디에도 이 명령을 먼저 실행하는 단계가 없다. +- 시나리오: 레포를 새로 clone한 사람이나 CI는 아키텍처 검사, 타입체크, 단위·컴포넌트 테스트를 모두 실패한다(3장 참조). +- 도입 시점: `6f6c48e`(도메인 확장 리팩터링). +- 수정 방향: `generate:feature-index`를 `pre*` 스크립트나 각 게이트 앞에 붙이고, CI 게이트에 `check:feature-index`를 추가한다. 또는 생성물을 커밋하고 `check:feature-index`로 최신 여부만 검사한다. + +### 6.1 browser-transfer (`src/adapters/browser-transfer/`) + +요약: 보안 경계는 탄탄하다(vault 식별자, 1회용 replay guard, redirect/credential 차단, 스트리밍 SHA-256, 이미지 헤더 bounds check). 결함은 resumable upload의 수명 관리, 정책 처리, 실패 분류, 그리고 계층 간 ID 규칙 불일치에 몰려 있다. + +1. **[필수·확인됨 ✓] `dispose()` 결과가 캐시되어 한 번 실패하면 영구히 CLOSING** + - 위치: `resumable-upload/resumable-upload-runtime.ts:331`, `:363-369` + - 문제: `drain ??= (async () => …)()`가 cleanup deadline을 넘기면 `UNAVAILABLE, retryable:true`를 반환하고 그 promise를 계속 들고 있다. 뒤에서 `quiescent`가 결국 `"DRAINED"`가 되어도 기다리는 쪽이 없다. 그래서 `checkpoints.close()`와 `lifecycle = "CLOSED"`가 실행되지 않는다. + - 시나리오: provider가 느려 첫 `dispose()`가 EXPIRED로 끝남 → 몇 초 뒤 작업은 모두 끝남 → 호출자가 retryable을 믿고 다시 `dispose()` → 같은 실패가 그대로 돌아옴. IDB 연결도 열린 채 남는다. + - 수정 방향: EXPIRED일 때 `drain = null`로 되돌리거나, `quiescent.then`으로 늦게라도 store를 닫고 CLOSED로 전환한다. + - 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts`는 첫 실패만 확인한다. 재호출 시나리오는 없다. + +2. **[필수·불일치는 확인됨, 실제 발생은 가능성] opaque ID 문법이 계층마다 다름** + - 위치: `resumable-upload/checkpoint-schema.ts:11`, `presigned/presigned-capability-http-provider.ts:38`, `:380-383`, `presigned/presigned-transfer-executor.ts:1213-1223` + - 문제: control plane은 `/^[A-Za-z0-9_-]{8,512}$/`를 받고, presigned 계층은 `/^[a-z0-9][a-z0-9._:-]{0,255}$/i`로 다시 검사한다. presigned 쪽은 `-`/`_`로 시작하는 ID와 256자를 넘는 ID를 거부한다. + - 시나리오: 서버가 base64url 랜덤 ID를 발급하면 약 3%가 `-`/`_`로 시작한다. 세션 생성과 checkpoint 저장은 통과하지만, 이후 part마다 `issueUploadPart`가 `INVALID_INPUT`(재시도 안 함)으로 실패한다. 같은 ACTIVE 세션을 재사용하므로 만료나 abort 전까지 계속 실패한다. complete에서 받은 resourceId를 `issueDownload`에 넘길 때도 같다. + - 수정 방향: ID 문법을 한 곳에 두고 provider와 executor가 import한다. + - 테스트: fixture는 안전한 ID만 쓴다. + +3. **[필수·확인됨] 기본 정책에서 동시 업로드가 조용히 1로 줄어듦 (문서와 반대)** + - 위치: `resumable-upload/runtime-policy.ts:101-117`, `:140-141`, `resumable-upload-runtime.ts:806-819` + - 문제: 기본값에서 `maxInFlightBytes 20MiB / (partSize 5MiB × copyFactor 4) = 1`이라 `workerCount = min(3, …, 1) = 1`이다. `maxConcurrency: 3`은 효과가 없는데 createSession은 서버에 concurrency 3을 요청한다. `docs/architecture/presigned-transfer-and-image-cdn.md:257`은 `partSize × concurrency × copyFactor`가 한도를 넘으면 시작 전에 거절하라고 한다. 코드는 `partSize × copyFactor`만 검사하고 조용히 clamp한다. copyFactor 4는 part마다 방어적 복사가 4~5번 일어나서 필요하다(`presigned-upload-part-executor.ts:274`의 `Uint8Array.from`, executor `slice()` 등). + - 수정 방향: 정책 검증에 `maxConcurrency`를 곱해 문서대로 거절하거나 기본값을 맞춘다. 겹치는 복사는 하나로 줄인다. + - 테스트: 테스트는 항상 정책을 override해서 기본 정책의 실제 동시성은 검증하지 않는다. + +4. **[필수·확인됨 ✓] 크기 초과 파일이 `LIMIT_EXCEEDED`가 아니라 `INVALID_INPUT`으로 보고됨** + - 위치: `resumable-upload-runtime.ts:1755-1761`, `:217-221`, `:385-392` + - 문제: `snapshotRequest`가 한도 초과에 TypeError를 던지고 `upload()`의 catch가 `INVALID_INPUT`으로 바꾼다. `executeUpload`의 `LIMIT_EXCEEDED` 분기는 같은 policy로 다시 검사하므로 실행될 수 없다. + - 시나리오: 6GB 파일을 올리면 UI가 "파일이 너무 큽니다" 대신 "잘못된 입력"을 받는다. + - 수정 방향: `snapshotRequest`에서 크기 검사를 빼고 `executeUpload` 분기를 살린다. + - 테스트: 없음. + +5. **[권장·확인됨] 한 worker가 실패해도 다른 worker가 취소되지 않음** + - 위치: `resumable-upload-runtime.ts:820-865` + - 문제: `firstFailure`는 다음 루프에서만 확인한다. in-flight worker는 retry 횟수만큼 issue와 PUT을 반복한다(시도당 30초 timeout + backoff). 호출자는 최악의 경우 몇 분 뒤에 실패를 받는다. + - 수정 방향: transfer 단위 AbortController를 `request.signal`과 합치고 `firstFailure` 설정 시 abort한다. + - 테스트: 없음. + +6. **[권장·가능성] 손상되었거나 모르는 schema의 checkpoint 행이 upload와 abort를 모두 막음** + - 위치: `resumable-upload/indexeddb-checkpoint-store.ts:314-318`, `resumable-upload-runtime.ts:1149-1150` + - 시나리오: 같은 DB 버전에서 새 빌드가 schemaVersion 2 행을 씀 → 롤백 → 해당 uploadKey는 read와 abort가 모두 `CORRUPT_DATA`로 영구 실패. 복구하려면 partition 전체를 삭제해야 한다. + - 확인 방법: 새 schema 행을 넣고 abort를 호출한다. + - 수정 방향: abort 경로에 "해석할 수 없는 행은 revision을 무시하고 삭제" 분기를 두고 ORPHANED로 보고한다. + +7. **[권장·가능성] image preset `fit: "inside"/"outside"` + PRIMARY_REQUIRED probe 조합에서 비율이 다른 asset이 모두 실패** + - 위치: `image-cdn/image-cdn-policy.ts:116-122`, `:468`, `image-cdn-runtime.ts:496-503`, `:1019-1020`, `browser-image-probe.ts:211-219` + - 문제: probe는 decode 크기가 `primary.pixelWidth × pixelHeight`와 정확히 같아야 통과한다. inside/outside는 원본 비율을 유지하므로 크기가 다르게 나와 `INTEGRITY_FAILED`가 된다. PRIVATE_SIGNED는 PRIMARY_REQUIRED가 강제라 이 조합을 쓸 수 없다. + - 확인 방법: 대상 CDN의 fit 의미를 확인한다. 테스트는 `fit: "cover"`만 쓴다. + - 수정 방향: PRIMARY_REQUIRED일 때 fit을 cover/contain/fill로 제한하거나, 예상 출력 크기를 계산해 비교한다. + +8. **[권장·가능성] 이미지 probe가 EXIF/`irot` 회전을 고려하지 않음** + - 위치: `image-cdn/browser-image-probe.ts:51-53`, `:231-235` + - 문제: 헤더 파서는 회전 전 크기를 읽고, `createImageBitmap`은 기본으로 EXIF orientation을 적용한다. orientation 5~8 JPEG나 `irot` AVIF는 폭과 높이가 뒤바뀌어 거절된다(fail-closed라 보안 문제는 아님). + - 확인 방법: CDN이 출력에서 EXIF를 제거하는지 확인한다. + - 수정 방향: `createImageBitmap(blob, { imageOrientation: "none" })`. + +9. **[권장·확인됨] presigned HTTP helper 중복과 동작 차이, 죽은 helper** + - 위치: `presigned/presigned-transfer-executor.ts:997-1178`, `presigned/presigned-capability-http-provider.ts:834-1032`, `resumable-upload-runtime.ts:1299-1349` + - 문제: + - `createAbortScope`, `readWithSignal`, `transferFailure`, `isAbortSignal`, `byteBucket`, `cancelBody`가 두 파일에 거의 그대로 있다. + - `statusFailure`의 401/403 recovery가 executor는 `REISSUE_CAPABILITY`, provider는 `NONE`이다. + - executor의 `compensateLateResponse`(`:1052`)는 호출하는 곳이 없다. + - download의 `Number(declaredLength)`(`:787`)는 `"1e3"`, `"0x10"`, `""`를 통과시킨다. + - runtime의 `invokeProviderAttempt`만 kernel `createAbortableOperation`을 쓰지 않는다. + - 수정 방향: `presigned/http-common.ts`로 모으고 runtime attempt를 kernel 위로 옮긴다. + +10. **[권장·확인됨] `resumable-upload-runtime.ts` 2298줄** + - 위치: `resumable-upload-runtime.ts:1422-1705`, `:1772-2020` + - 문제: upload 흐름, retry/deadline, 서버 응답 검증, 의존성 snapshot 래퍼 8개가 한 파일에 있다. 검증과 snapshot만 분리해도 약 800줄이 줄어든다. + +11. **[사소·확인됨] vault `register`가 snapshot 뒤에 원본 객체를 다시 읽음** + - 위치: `presigned/presigned-capability-vault.ts:279-287` + - 문제: 중복 receipt 검사는 `registration.capabilityReceipt`(원본)를 읽고 저장은 `snapshot.capabilityReceipt`로 한다. stateful issuer면 중복 검사를 우회할 수 있다. issuer가 내부 코드라 영향은 작다. + - 수정 방향: 세 곳 모두 `snapshot.capabilityReceipt`를 쓴다. + +잘 된 점: presigned vault의 SSRF·capability 유출 방어(WeakMap 식별자, 1회용 replay guard, `redirect: "error"`, `credentials: "omit"`, 경로 이중 인코딩 차단). 이미지 헤더 파서의 bounds check와 P-256 서명 검증. adapter 간 import 규칙 준수. + +### 6.2 browser-files / cache-storage / cross-context-invalidation + +요약: 다운로드 abort 경로에서 Result 계약이 깨지고, cross-tab 무효화가 60초마다 전체 무효화로 떨어진다. 기본 cache 정책은 실제 CDN 응답을 거부하고, 조회 비용이 크다. + +1. **[필수·확인됨] BOUNDED_OBJECT_URL + presigned source에서 open 실패 시 `deliver()`가 reject되고 lease가 샘** + - 위치: `src/adapters/browser-files/download-delivery-adapter.ts:733-743` + - 문제: `promptAndStream`은 `resolveByteSource`를 try/finally 안에서 부르지만 `boundedObjectUrlHandoff`는 try 밖에서 부른다. `resolveByteSource`는 `open()` 동기 throw(1085), open 중 abort(1095), `pendingOpen` reject 때 throw한다. + - 시나리오: 사용자가 취소 → `deliver()`가 `{ok:false, ABORTED}` 대신 AbortError로 reject된다. observer 기록도 없다. `closeHeldSource`가 호출되지 않아 늦게 온 lease는 `compensateLateSource`(1039)가 닫지 않는다. + - 수정 방향: `resolveByteSource`부터 try/finally로 감싸고 catch에서 `mapDownloadException`으로 Result를 반환한다. + - 테스트: 기존 테스트는 PROMPT_AND_STREAM만 쓴다. + +2. **[필수·확인됨 ✓] sequence 기준점이 이벤트 TTL(60초)과 함께 삭제되어 60초 이상 쉰 뒤 이벤트가 매번 GAP** + - 위치: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts:494-503`, `:544-554` + - 문제: watermark가 `expiresAt: event.expiresAt`로 저장되고 `pruneTracking`이 지운다. 다음 이벤트는 `!previous && event.sequence > 1`로 GAP이 된다. 받는 쪽 `src/adapters/query-cache/tanstack-cache-coordinator.ts:106-110`은 GAP이면 모든 topic을 무효화한다. + - 시나리오: 탭 A에서 몇 분에 한 번 수정할 때마다 탭 B가 모든 namespace의 active 쿼리를 다시 가져온다. + - 수정 방향: watermark 수명을 이벤트 TTL과 분리한다. 메모리는 이미 `sourceCapacity` LRU로 제한된다. + - 테스트: TTL 테스트(`tests/unit/cross-tab-invalidation.test.ts:618`)는 서로 다른 source에 seq 1만 보낸다. + +3. **[필수·확인됨] storage fallback 탭이 다른 탭의 이벤트를 못 받는데 상태는 정상으로 표시됨** + - 위치: `browser-cross-context-invalidation.ts:349-373` + - 문제: broadcast 발행에 성공하면 storage pulse를 쓰지 않는다. `postMessage`가 한 번 실패한 탭은 `closeBroadcast()`(369)로 수신 listener까지 제거한다. 그 뒤로 다른 탭의 broadcast를 못 받는데 status는 `ACTIVE_STORAGE_FALLBACK`이다. + - 수정 방향: 발행 실패 시 송신만 storage로 바꾸고 수신은 유지한다. 또는 발행 쪽이 broadcast와 storage 모두에 쓴다(eventId dedupe 있음). 아니면 DEGRADED로 보고한다. + - 테스트: `tests/unit/cross-tab-invalidation.test.ts:463`은 발행 탭에 `failPost = true`를 걸어 문제 경로를 우회한다. + +4. **[필수·확인됨(Web IDL 기준)] 브라우저 picker 함수를 options 객체에 bind함** + - 위치: `src/adapters/browser-files/browser-file-picker.ts:434-435`, `download-delivery-adapter.ts:225-229` + - 문제: `showOpenFilePicker.bind(options)`는 `this`를 options로 고정한다. Window operation은 `this`가 Window가 아니면 TypeError("Illegal invocation")를 던진다. `window.showOpenFilePicker`를 그대로 넘기면 매번 실패한다. + - 확인 방법: `window.showOpenFilePicker.call({}, {})`가 TypeError인지 본다. user gesture 없이 확인할 수 있다. + - 수정 방향: bind 없이 호출하거나 composition 단계에서 `window`에 bind한 host를 주입한다. + +5. **[필수·코드 경로 확인됨, 전제는 실제 서버 동작] 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 전부 거부** + - 위치: `src/adapters/cache-storage/public-response-cache-adapter.ts:1299-1333`, `public-cache-policy.ts:69` + - 문제: `allowedVaryHeaderNames: []`라 Vary가 있으면 `POLICY_REJECTED`다. nginx `gzip_vary`와 대부분의 CDN이 JS/CSS에 이 헤더를 붙인다. `accept-encoding`은 브라우저가 Request에서 지우는 금지 헤더라 정책으로 풀기도 어렵다. `allowedResponseHeaderNames`에서 `content-type`을 빼면 activate가 항상 `INTEGRITY_FAILED`가 되는데 `assertPublicCachePolicy`가 이를 막지 않는다. + - 수정 방향: `accept-encoding`을 브라우저 관리 Vary로 따로 허용하고, `content-type` 필수 검사를 정책 검증에 추가한다. + - 테스트: `tests/browser-capabilities/public-cache-storage.spec.ts:106-125`는 Vary 없는 응답만 쓴다. + +6. **[권장·확인됨] 캐시 조회 한 번의 비용이 큼** + - 위치: `public-response-cache-adapter.ts:1453`, `:263-319`, `:1540-1544` + - 문제: `matchActiveExact` 한 번에 `keys()` 2번, 2 MiB 버퍼 2개(총 4 MiB) 선할당, 최대 10k asset marker 전체 재검증과 SHA-256, 선형 탐색, 본문 SHA-256과 복사 3~4회가 일어난다. SW처럼 요청마다 조회하면 페이지 로드 한 번에 수백 MiB 할당이 생긴다. + - 수정 방향: JSON은 chunk를 모아 읽고, 검증된 marker를 `cacheName+manifestDigest`로 메모리 캐시하고, asset 탐색은 Map으로 바꾼다. + +7. **[권장·가능성] kernel의 abort race를 손으로 다시 구현해 틈이 생김** + - 위치: `download-delivery-adapter.ts:1032-1050`, `:1482-1524`, `browser-file-vault.ts:872-891` + - 문제: `combineAbortSignals`(동일 복사본 2개), `awaitWithSignal`, `compensateLateSource`가 `src/adapters/platform/abortable-operation.ts:90`을 다시 구현한다. abort 직후 finally 전 몇 microtask 사이에 lease가 resolve되면 아무도 닫지 않는다. `awaitWithSignal(handle.createWritable(), signal)`(595)은 늦게 온 writable을 abort하지 않는다(Chrome `.crswap` 임시 파일). + - 수정 방향: kernel `race`와 compensate로 교체한다. + +8. **[권장·가능성] native `cancel` 지원 브라우저에서도 focus fallback이 켜져 있어 느린 `change`가 버려짐** + - 위치: `src/adapters/browser-files/browser-file-picker.ts:301-317` + - 시나리오: Android 클라우드 provider처럼 파일을 받아온 뒤 change를 보내는 경우, 사용자가 파일을 골랐는데 "취소됨"으로 처리된다. + - 수정 방향: native `cancel`을 한 번이라도 관찰하면 fallback을 끈다. + - 테스트: `tests/unit/browser-file-picker.test.ts:215`는 grace 안에 도착하는 경우만 본다. + +9. **[권장·확인됨] host factory가 조용히 `undefined`를 반환해 cross-tab 기능이 진단 없이 꺼짐** + - 위치: `src/adapters/cross-context-invalidation/browser-cross-context-host.ts:52-62` + - 시나리오: `RELEASE_ID`가 `1.2.3+sha.abc`, `feature/x`, `app@1.2.3`처럼 `+`, `/`, `@`를 포함하거나 120자를 넘으면 `cacheEpoch` 검사에 실패해 `undefined`가 반환된다. `RELEASE_ID` 자체는 빈 문자열만 아니면 통과한다(`src/contracts/deployment-admission.ts:95-106`). + - 수정 방향: 반환 전 `observe(OPEN, FAILED)`를 호출하고, epoch는 releaseId를 hash/인코딩해 만든다. + +10. **[권장·확인됨] 파일명 자르기가 O(n²)이고 입력 길이 상한이 없음** + - 위치: `src/adapters/browser-files/file-policy.ts:357-362` + - 시나리오: 서버가 10만 자 파일명을 주면 약 10^10번 연산으로 탭이 멈춘다. deliver 한 번에 두 번 호출된다(`download-delivery-adapter.ts:318`, `:1003`). + - 수정 방향: 루프 전에 `maxUtf8Bytes`개 code point로 먼저 자른다. + +11. **[권장·확인됨] 1000줄 넘는 파일 2개** + - `public-response-cache-adapter.ts`(1949줄): facade, 조회/stage/activate/cleanup, 매니페스트·marker 코덱(약 400줄), 응답 검증(약 200줄). + - `download-delivery-adapter.ts`(1528줄): 전략 3개, 입력 검증, abort 유틸. + +12. **[사소·확인됨] 중복 helper와 죽은 분기** + - `MEDIA_TYPE` 정규식 3곳: `object-url-lease.ts:187`, `download-delivery-adapter.ts:137`, `browser-file-policy-registry.ts:84`. + - `safeOpaqueValue`(`browser-file-vault.ts:868`)와 `safeGeneratedToken`(`download-delivery-adapter.ts:1376`)이 같은 정규식이다. + - `object-url-lease.ts:112-118`의 안쪽 `if`는 바깥 조건과 반대라 실행되지 않는다. + +잘 된 점: cross-context wire 이벤트의 파싱 검증(key 집합, 크기, epoch, topic 허용 목록, TTL). cache stage 경로의 abort 뒤 쓰기 차단과 교체본 검증 전 기존 candidate 보존. object URL의 단일 lease registry. + +### 6.3 http / browser-rpc / query-cache / auth / diagnostics / telemetry + +요약: V3 실행기의 자원 한도, 마감, abort 관리는 좋다. 문제는 URL 조립, 오류 분류, 자격증명 헤더 검증, 세션 변경 시 scope fence에 있다. + +1. **[필수·확인됨 ✓] 경로 값 `.`/`..`가 URL 정규화로 다른 엔드포인트를 가리킴** + - 위치: `src/adapters/http/http-contract-bridge.ts:185-205`, `src/adapters/http/request-builder.ts:72-86`, `:106` + - 문제: `/`와 `\`만 막는다. `encodeURIComponent("..")`는 `..` 그대로이고 `new URL`이 상위 경로로 해석한다. 결과가 base 경로 아래라 `URL_ORIGIN_ESCAPED`도 통과한다. + - 시나리오: `/v1/projects/{p}/members/{m}`에 `m=".."` → `/v1/projects/p1/`. DELETE 명령이면 멤버가 아니라 프로젝트 쪽으로 요청이 간다. 레퍼런스 스키마 `resourceId: z.string().trim().min(1).max(120)`(`reference-schemas.ts:24`)는 `".."`를 통과시킨다. V2도 `base.pathname =` 대입에서 같은 정규화가 일어난다. + - 수정 방향: 값이 `"."`이나 `".."`이면 `PATH_VALUE_INVALID`로 거절한다. `src/contracts/release-artifacts.ts:37`에 같은 규칙이 있다. + - 테스트: `PATH_VALUE_INVALID`, `URL_ORIGIN_ESCAPED` 모두 없음. + +2. **[필수·흐름은 확인됨, 무한 반복은 가능성] 세션 알림마다 무조건 scope fence + V3가 "요청 전 자격증명 없음"과 "서버 401"을 구분하지 못함** + - 위치: `src/adapters/query-cache/server-state-scope-runtime.ts:90-105`, `src/adapters/http/http-execution-v3.ts:709-712` / `1155-1163`, `src/adapters/auth/external-session-adapter.ts:111-114`, `:135` + - 문제: scope 런타임은 `session.subscribe` 알림마다 상태 비교 없이 generation을 올리고, 진행 중 요청을 abort하고, 캐시를 비운다. V3는 요청 전 `UNAUTHENTICATED`와 서버 401을 같은 결과로 돌려주고, 조합 루트(`src/bootstrap/runtime-adapters.ts:462`, `:520`)가 둘 다 `onUnauthenticated()`를 부른다. demo `setState`는 값이 같아도 알림을 보낸다. + - 시나리오: 로그아웃 상태에서 V3 쿼리 실행 → `onUnauthenticated` → 알림 → fence → 캐시 비움 → 쿼리 재마운트 → 반복 가능. `recovery-pending` 상태의 요청은 demo가 `"unauthenticated"`로 덮어 복구가 끊긴다. 외부 owner가 토큰 갱신 때도 알림을 보내면 갱신마다 캐시가 비워진다. presentation 쪽 영향은 6.8-3. + - 확인 방법: demo 모드, 로그아웃 상태에서 쿼리가 켜진 페이지를 열고 FENCED 이벤트 횟수를 센다. + - 수정 방향: (state, 식별자)가 바뀔 때만 fence한다. demo `setState`는 같은 값이면 알리지 않는다. V3의 요청 전 판정을 서버 401과 구분한다. + - 테스트: "상태가 그대로인 알림" 테스트 없음. + +3. **[필수·확인됨] 게이트웨이 5xx(HTML/빈 바디)가 계약 위반으로 분류되어 status가 사라지고 "지원팀 문의, 재시도 불가"로 표시** + - 위치: `src/adapters/http/http-execution-v3.ts:1486-1510`, `:300-306`, `src/adapters/http/feature-http-binding.ts:356-362`, `:366-390`, `src/adapters/http/client.ts:858-869` + - 문제: nginx `text/html` 502는 재시도 후 `CONTRACT_VIOLATION{CONTENT_TYPE_MISMATCH}`, 빈 바디는 `PROBLEM_SCHEMA_INVALID`가 된다. metadata가 없어 `httpStatus`와 `http_status_group`이 빠진다. 바인딩을 거치면 `retryable:false`, `action:"contact-support"`다. V2는 content-type 검사가 status 검사보다 먼저이고 `retry-policy.ts:1`에 이 종류가 없어 재시도도 안 한다. 입력 검증 실패(`FINAL_REQUEST_INVARIANT_FAILED`)와 `MISSING_IDEMPOTENCY_KEY`도 기본값 `ENVELOPE_MISMATCH`로 떨어진다(`feature-http-binding.ts:388`). + - 수정 방향: 5xx/408/425에서 problem 바디가 유효하지 않으면 status를 담은 서버 장애로 끝낸다. 요청 쪽 위반은 `VALIDATION_REJECTED` 계열로 매핑한다. + - 테스트: 없음. + +4. **[필수·확인됨] 자격증명 헤더 값 검증이 CR/LF만 막아, NUL/비 Latin-1 토큰이 "전송 후 네트워크 실패"로 분류됨** + - 위치: `src/adapters/http/http-contract-bridge.ts:83-90`, `http-execution-v3.ts:893-907`, `:927`, `src/adapters/auth/external-session-adapter.ts:37-46` + - 문제: `new Headers({authorization:"Bearer 한"})`는 TypeError, `fetch`는 reject된 Promise를 준다. V3는 `fetcher()`가 Promise를 반환한 시점에 `DISPATCHED`로 표시하므로 명령은 `MAYBE_APPLIED` + NETWORK_FAILURE, 쿼리는 재시도 예산만 쓴다. 검증기가 3벌이고, auth 어댑터는 대소문자만 다른 중복 헤더를 조용히 합친다. `decodeCredentialPatch`(`http-execution-v3.ts:1100-1106`)는 UTF-16 길이, bridge는 UTF-8 바이트로 잰다. + - 수정 방향: bridge 한 곳에서 제어문자 없는 ByteString을 검사하고, `checkFinalInvariants`에서 `new Headers(headers)`를 미리 만들어 본다. + - 테스트: `CREDENTIAL_HEADER_VALUE_INVALID` 테스트 없음. + +5. **[필수·확인됨] feature 바인딩이 `mapSuccess`/`mapProblem` 예외를 잡지 않음** + - 위치: `src/adapters/http/feature-http-binding.ts:300`, `:311` + - 문제: V2(`client.ts:919-956`), `mapWithBoundaryRegistry`, RPC `mapResponse`는 try/catch로 감싸는데 여기만 없다. 매퍼가 던지면 `execute`가 reject되고, 서버가 `APPLIED_CONFIRMED`로 확정한 명령도 `normalizeUnknownFailure`를 거쳐 `MAYBE_APPLIED`가 된다(`src/presentation/adapters/query/application-query.ts:726-727`). + - 수정 방향: 두 호출을 감싸 `MAPPING_CONTRACT_VIOLATION`에 `effect: outcome.effect`를 실어 반환한다. + - 테스트: 없음. + +6. **[권장·확인됨] 백오프 중 scope fence가 TIMEOUT으로 분류됨 + 종료 사유 판정이 6곳에 복사됨** + - 위치: `http-execution-v3.ts:941-950`, `:1031-1040` + - 문제: 재시도 sleep 중 로그아웃하면 `terminalCancellation === "SCOPE_FENCE"`인데 코드는 `"CALLER"`만 확인해 `TRANSPORT_FAILURE{TIMEOUT}`이 된다. 사용자에게 "시간 초과, 재시도"가 뜬다. 같은 판정이 679-692, 813-822, 915-927, 941-950, 986-998, 1031-1040에 따로 있고 scope 종료가 위치에 따라 세 가지 결과로 나온다. `execute()`는 약 620줄이다. + - 수정 방향: `terminalOutcomeFor(owner, phase)` 헬퍼로 모은다. + - 테스트: caller abort 중 sleep은 있음(`tests/unit/http-execution-v3.test.ts:687`), scope fence 중 sleep은 없음. + +7. **[권장·코드 경로 확인됨, 영향은 분류기에 따라 가능성] 명령의 최종 effect가 누적 certainty와 합쳐지지 않음** + - 위치: `http-execution-v3.ts:1045`, `:1486-1497`, `:1579` + - 시나리오: IDEMPOTENT DELETE가 504(빈 바디, 실제로는 적용됨) → 재시도 → 404 → 분류기가 `NOT_APPLIED`로 판정하면 최종 결과가 "적용 안 됨, 재시도 가능"이 된다. + - 수정 방향: 명령이면 `finish` 직전 `joinMutationEffectCertainty(logical, attempt)`를 적용하거나, `MAYBE_APPLIED`면 retryHint를 false로 둔다. + - 테스트: 없음. + +8. **[권장·확인됨] 무효화가 namespace별 refetch를 하나씩 기다림** + - 위치: `src/adapters/query-cache/tanstack-cache-coordinator.ts:79-89` + - 문제: TanStack 5의 `invalidateQueries`는 active refetch가 끝나야 resolve되는데 for 루프에서 순차 await한다. `lease.release()`도 이를 기다린다. + - 수정 방향: `Promise.allSettled`로 병렬 실행. + +9. **[권장·가능성] Browser RPC 명령 경로에 effect certainty와 scope 확인이 없음** + - 위치: `src/adapters/browser-rpc/browser-rpc-runtime.ts:352-401`, `:424-435`, `:487-499`, `:1535-1574` + - 문제: `NON_REPLAYABLE`/`KEYED_COMMAND` unary가 전송 후 timeout/THREW/`UNAVAILABLE`이면 `retryable:true`, `action:"retry"`로 나간다. 재시도 전 generation을 확인하지 않아 로그아웃 뒤에도 이전 사용자 요청이 재전송될 수 있다. server stream은 소비자가 `return()`을 안 부르면 `RPC_STREAM_DRAINING`에 막힌다. + - 수정 방향: 전송 후 실패에 `effect: "MAYBE_APPLIED"`를 붙이고, 매 attempt 전 `safeIsCurrent`를 확인하고, abort 리스너에서 항목을 정리한다. + +10. **[권장·확인됨] best-effort 텔레메트리 fetch에 타임아웃이 없고 전송기가 두 벌** + - 위치: `src/adapters/telemetry/best-effort-telemetry.ts:211-238`, `src/adapters/telemetry/feature-telemetry.ts:23-36` + - 문제: 수집기가 응답하지 않으면 `activeFlush`가 끝나지 않아 이후 flush가 모두 이 Promise를 받고, 큐가 차면 세션 동안 텔레메트리가 꺼진다. feature 쪽은 `credentials:"omit"`, best-effort 쪽은 기본값(same-origin)이라 쿠키가 같이 간다. + - 수정 방향: `AbortSignal.timeout(...)`을 걸고 `createFetchTelemetryTransport` 하나로 통일한다. + +11. **[권장·확인됨] V2 관련 두 가지** + - 401 복구가 재시도 예산에 묶여 있다(`src/adapters/http/client.ts:339-344`). `MAX_RETRY_ATTEMPTS=0`이거나 503 → 401 순서면 복구 없이 로그아웃된다. `auth-recovery.test.ts`에 없음. + - "롤백 가능 seam" 문제가 알려진 것보다 넓다(`src/adapters/http/schema-registry.ts:12-16`). 슬롯 4개를 모두 주입해도 V2는 `{success,data,meta}` 봉투를, V3는 DTO 자체를 검증한다(`http-execution-v3.ts:1325`). 같은 백엔드로 V2로 되돌리면 모든 응답이 `ENVELOPE_MISMATCH`다. + +12. **[권장/사소·확인됨] 기타** + - `src/adapters/query-cache/cursor-pagination-runtime.ts:111-114`: 페이지마다 누적 items 전체를 `JSON.stringify`(O(pages × 누적 크기)). `items.push(...page.items)`는 큰 페이지에서 RangeError로 reject된다. + - `browser-rpc-runtime.ts:1468`의 `validTransportFailure`는 쓰는 곳이 없고 RPC-RR-04 주석이 금지한 직접 속성 읽기를 한다. `decodeTransportFailure`와 중복이다. + - `src/adapters/query-cache/conditional-validator-store.ts:141-146`: 닫는 따옴표 없는 `W/"`를 유효 ETag로 받는다. + +잘 된 점: V3의 모든 대기(자격증명, lease, fetch, 바디, 백오프)를 하나의 수명 signal과 경쟁시키고 늦은 응답의 바디를 취소한다. 바디는 선언 길이 → 스트림 누적 → JSON 구조 예산 순으로 제한한다. conditional validator 키를 튜플 `JSON.stringify`로 만들어 구분자 충돌을 막았다. + +### 6.4 realtime (`src/adapters/realtime/`) + +요약: 경계 검증과 상한은 꼼꼼하다. 문제는 모듈 연결 지점에 있다. 멈춘 effect와 recovery가 겹치고, WS/SSE가 끊김 뒤 재연결하지 않고, barrier NONE 스트림이 recovery 한 번에 종료된다. SSE 파서는 느리다. + +1. **[필수·확인됨] recovery가 DRAINING effect와 동시에 실행되고 `recoveryRequired`를 해제함** + - 위치: `src/adapters/realtime/stream-coordinator.ts:707-721` + - 문제: DRAINING 검사는 진입 시점(`:666`)에만 있다. `await quiescence` 뒤에는 closed/abort/scope만 본다. 그 사이 effect가 timeout으로 DRAINING이 되어도 recovery가 authority를 호출하고 `:843`에서 커밋한다. 늦게 끝난 effect가 snapshot을 덮어쓸 수 있다(RT-RR-01/02가 막으려던 상황). + - 재현: `recover(SEQUENCE_GAP) called; effectStillRunning=true` → `hasResumeState:true` → `late effect settled`. + - 수정 방향: `await quiescence` 직후 `state.lifecycle === "DRAINING"`이면 실패를 반환한다. + - 테스트: 없음(`:503`은 협조적 apply, `:1282`는 scheduler 고장만). + +2. **[필수·확인됨 ✓] 네트워크 끊김, 서버 재시작, 502/504 뒤 재연결하지 않음** + - 위치: `src/adapters/realtime/reconnect-coordinator.ts:1661-1671` + - 문제: `reconnectable()`은 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`에 `serverNotBeforeMs`가 없으면 `retryable:true`여도 false를 반환한다. 전송 계층은 hint 없이 이 값을 보낸다: WS `RESTART`/`NETWORK_LOST`(1006/1001/1012, `websocket/websocket-connection.ts:1923-1930`), error 이벤트(`:429-443`), SSE 502/504(`sse/fetch-sse-connection.ts:588-590`). WS에는 Retry-After가 없어 hint가 생길 수 없다. 결과적으로 WS는 IDLE_TIMEOUT, CONNECT_TIMEOUT, OFFLINE일 때만 재연결한다. 설계 문서(`docs/architecture/realtime-events-web-push-and-bounded-polling.md:1008`, `:1150-1156`)는 이들을 bounded reconnect로 정의한다. polling도 같은 규칙이다(`polling/bounded-poll-coordinator.ts:344-351`). + - 수정 방향: "hint 필수" 조건을 빼고 `retryable`만 본다. 전송 계층은 hint가 필요한데 없으면 이미 `retryable:false`를 보낸다(SSE `:573-587`, WS OVERLOADED `:1931-1937`). + - 테스트: 양쪽 동작이 각각 고정되어 있다(`realtime-reconnect-coordinator.test.ts:308-331`, `websocket-connection.test.ts:930-957`). 둘을 잇는 통합 테스트는 없다. + +3. **[필수·확인됨] barrier NONE 스트림이 recovery 한 번으로 PROTOCOL_MISMATCH 종료** + - 위치: `src/adapters/realtime/event-consumer.ts:181-194` + - 문제: consumer는 모든 `RECOVERED`를 `RECOVERY_COMMITTED`로 넘긴다. SNAPSHOT_ONLY + barrier NONE 스트림은 barrier를 기다리지 않는다(`stream-coordinator.ts:844-848`). 전송이 연결을 닫고 → reconnect가 `confirmTransportBarrier` 호출(`reconnect-coordinator.ts:769-803`) → `stream-coordinator.ts:986-994`가 PROTOCOL_MISMATCH를 반환하고 종료된다. + - 재현: gap 이벤트 → `RECOVERY_COMMITTED` → `confirmTransportBarrier: PROTOCOL_MISMATCH`. + - 수정 방향: barrier가 필요 없는 recovery는 `CONTINUE`로 넘긴다. disposition에 barrier 필요 여부를 싣는다. + - 테스트: `event-consumer.test.ts`는 accept를 mock해서 이 조합을 못 본다. + +4. **[필수·확인됨] SSE 파서가 문자마다 `TextEncoder.encode`를 호출해 250KB chunk에 120~170ms** + - 위치: `src/adapters/realtime/sse/sse-parser.ts:166-167` + - 측정: 250KB chunk 121~169ms(약 2MB/s). 같은 데이터를 `split`으로 처리하면 1.3ms. + - 문제: 메인 스레드 코드라 재연결 직후 replay 같은 몰아치는 수신이 long task가 된다. + - 수정 방향: `indexOf`로 줄바꿈을 찾아 `slice`하고 UTF-8 길이는 코드포인트 범위로 계산하거나 줄마다 한 번만 센다. + - 테스트: 성능 테스트 없음. + +5. **[권장·가능성] `maxItemsPerChunk`(256)를 넘으면 non-retryable QUEUE_OVERFLOW로 종료** + - 위치: `sse/sse-parser.ts:282-294`, `fetch-sse-connection.ts:437-441` + - 재현: 333바이트 이벤트 300개(104KB) chunk 하나 → `QUEUE_OVERFLOW retryable:false`. + - 문제: 메모리는 `maxChunkBytes`가 이미 막는다. 이 상한은 정상적인 몰아치기 수신만 죽인다. + - 확인 방법: replay 중 실제 reader chunk 크기를 측정한다. + - 수정 방향: 남은 텍스트를 다음 처리로 넘기거나 상한을 없앤다. COMMENT는 상수 객체를 재사용한다. + +6. **[권장·확인됨] dedupe가 가득 차면 매번 전체 recovery, fingerprint로 원문 전체 저장** + - 위치: `stream-coordinator.ts:490-502`, `event-codec.ts:189`, `stream-coordinator.ts:1108-1126` + - 문제: 초당 3.4건 이상(2048건/600초)이 계속 오면 윈도우마다 snapshot 재수신과 재연결이 일어난다. fingerprint가 canonical envelope 전체(최대 64KB)라 4MB 한도가 빨리 찬다. `pruneDedupe`는 시간순 항목에서 `break` 대신 `continue`를 써서 매번 전부 훑는다. 주석끼리도 어긋난다(`:621` "eviction 금지", `:1681` "2,048 ID 또는 10분"). + - 수정 방향: FIFO 제거, fingerprint는 해시로, prune에서 `break`. + +7. **[권장·확인됨] heartbeat 한 번이면 재시도 예산이 초기화되어 불안정한 서버에 끝없이 재연결** + - 위치: `reconnect-coordinator.ts:950-961`, `:980-990`, `reconnect-policy.ts:135` + - 시나리오: 연결 후 `:` comment 하나 보내고 끊는 서버/프록시 → `attemptIndex`가 0에 머물고 대기가 [0, baseDelay)라 `maxAttempts`/`maxElapsed`에 도달하지 못한다. 여러 클라이언트가 동시에 몰린다. + - 수정 방향: 유효 신호가 있고 동시에 `stableOpenMs`가 지났을 때만 초기화한다. + +8. **[권장·확인됨] 같은 로직의 복사본과 동작 차이** + - DataSnapshot 3벌: `result.ts:141`(`Object.hasOwn` + frozen 계산), `reconnect-coordinator.ts:1485`(`"value" in`), `polling/bounded-poll-coordinator.ts:789`(enumerable 검사 없음, null prototype 거부). + - abort/timeout race 6종: `fetch-sse-connection.ts:601`, `reconnect-coordinator.ts:1036`, `:1058`(전역 `setTimeout` 사용), `bounded-poll-coordinator.ts:563`, `:605`, `live-poll-handoff-coordinator.ts:673`, `:696`(본문 동일), `stream-coordinator.ts:204`, WS 인라인 2곳. + - 영역 밖: `json-member-scanner.ts`와 `web-push/push-codec.ts:211`(최상위 키만 검사). `reconnect-policy.ts:147`과 `http/retry-policy.ts:17`(http 쪽은 `" "`를 0ms로, `"1e3"`, `"1.5"`도 허용). + - 수정 방향: realtime 내부는 `result.ts`로, 여러 adapter 공용은 kernel로 올린다. + +9. **[권장·확인됨] 거대 함수와 무시되는 파라미터** + - `reconnect-coordinator.ts:307-1016`: `run()` 약 700줄. 정리 코드 4줄이 약 15번 반복된다. + - `websocket/websocket-connection.ts:1987-2003`: `failure()`/`connectionFailure()`의 4번째 인자 `_recovery`를 무시한다. 호출부 41곳이 값을 넘기지만 효과가 없다. + - 수정 방향: `endAttempt()` 헬퍼, `_recovery`는 제거하거나 receipt에 싣는다. + +10. **[권장·확인됨] probe 버퍼 상한이 현재 버퍼가 아니라 누적 수신량 기준** + - 위치: `src/adapters/realtime/live-poll-handoff-coordinator.ts:266-282` + - 문제: `acceptedEvents`/`acceptedBytes`가 drain(`:522-541`)에서 줄지 않는다. 활성화 중 누적 256건을 넘으면 `failClosed()`로 영구 CLOSED. + - 테스트: 없음. + +11. **[사소]** + - `bounded-poll-coordinator.ts:284-289`: `execute` throw가 무조건 OFFLINE + `retryable:false` 종료(`:344-351`). 다른 곳의 OFFLINE은 retryable이다. + - `sse-parser.ts:56-59`, `:138-141`: BOM을 두 번 제거한다(스펙은 한 번). + - `event-codec.ts:104`, `:108`: 원문을 두 번 encode한다. + - `fetch-sse-connection.ts:308`: 이벤트마다 `new TextEncoder()`. + - `websocket-protocol.ts:472-484`: `exceedsUtf8ByteLimit` JSDoc이 `utf8ByteLength` 위에 붙어 있다. + +잘 된 점: 신뢰할 수 없는 프레임 처리 순서(바이트 상한 → 중복 키 스캔 → `JSON.parse` → 정확한 키 검사 → freeze). 모든 queue/buffer/rate의 상한. generation/lease로 늦은 콜백 차단. 위험 경로 대부분의 단위 테스트(15개 파일). + +### 6.5 storage / adapter kernel / browser-file-storage + +요약: kernel(connection/transaction/abortable)과 Web Storage 코덱은 튼튼하다. OPFS GC가 멈추고, dedup 재사용 청크를 지울 수 있고, 전역 lock과 60초 RPC 타임아웃이 겹친다. IndexedDB purge는 손상 행 하나에 막히고, 저장 스키마 검증기가 갈라져 있다. + +1. **[필수·확인됨 ✓] OPFS orphan GC가 앞쪽 100개에서 더 나아가지 못함** + - 위치: `src/adapters/storage/opfs/opfs-worker-runtime.ts:995-1022`, `opfs-byte-store-adapter.ts:1099-1158` + - 문제: worker의 `listOrphanCandidates`는 참조 여부를 모르고 "staging에 없고 24시간 넘은 청크"를 디렉터리 순서로 최대 100개 준다. 커밋된 청크도 포함된다. coordinator는 참조 중이면 건너뛴다. 프로토콜에 이어 볼 커서가 없다(`opfs-worker-protocol.ts:119`). + - 시나리오: 하루 넘은 커밋 청크가 100개를 넘으면 매번 같은 100개(전부 참조 중)만 받는다. 뒤에 있는 진짜 orphan은 지워지지 않고 쿼터가 샌다. 상태는 `DEADLINE_REACHED`로 보고된다. + - 수정 방향: `LIST_ORPHAN_CANDIDATES`에 `afterDigest` 커서를 추가한다. + - 테스트: `tests/unit/opfs-worker-runtime.test.ts:428`은 청크 1개만. + +2. **[필수·가능성] dedup으로 재사용한 오래된 청크를 GC가 지워 커밋된 객체 손실** + - 위치: `opfs-worker-runtime.ts:1197-1211`, `:1059-1063`, `opfs-byte-store-adapter.ts:1127-1141` + - 문제: `writeImmutableChunk`는 같은 digest가 있으면 바로 `return`해 `lastModified`가 갱신되지 않는다. 참조 확인(메인 스레드 IDB)과 삭제(worker)가 원자적이지 않다. + - 시나리오(탭 2개): 참조 0인 오래된 청크 D → 탭1 reconcile이 `isChunkReferenced(D)=false` 읽음 → 탭2가 같은 파일 재업로드, D 재사용, refcount 1, staging 삭제 → 탭1의 `DELETE_ORPHAN_CHUNK`가 D 삭제 → 그 객체를 열면 `INTEGRITY_FAILED`. + - 발생 조건: 같은 탭에서는 lock FIFO가 막는다. 여러 탭에서 스레드가 지연될 때만 열린다. + - 수정 방향: dedup hit 때 mtime을 갱신한다. + - 테스트: 없음. + +3. **[필수·확인됨] origin 전체 lock을 업로드 내내 잡음 + 60초 RPC 타임아웃 → 동시 업로드 실패** + - 위치: `opfs-worker-runtime.ts:362`, `:538-541`, `opfs-policy.ts:47`, `:51`, `opfs-worker-client.ts:170-176` + - 문제: `beginPut`이 공용 Web Lock(`ca-frontend-opfs-v1:mutation`)을 FINISH/ABORT까지 잡는다. 다른 BEGIN_PUT, REMOVE_OBJECT, FINALIZE_PUT, GC가 기다리고 각 RPC는 60초 타임아웃이다. + - 시나리오: 2GiB 파일 A와 작은 파일 B를 동시에 put → A가 60초를 넘기면 B는 `UNAVAILABLE`(`opfs-worker-client.ts:612-616`). 같은 시간 remove는 logical delete만 커밋되고 DEGRADED. journal 행이 COMMITTED로 남아 같은 objectId 재업로드가 reconcile 전까지 CONFLICT. + - 수정 방향: lock을 objectId/scope 단위로 좁히거나 page 쪽 put 큐를 둔다. 최소한 한계를 주석과 문서로 명시한다. + - 테스트: worker 테스트는 배타적이지 않은 `immediateLeases`(`tests/unit/opfs-worker-runtime.test.ts:202`)를 써서 경합을 보지 않는다. + +4. **[필수·확인됨] IndexedDB 파티션 purge(LOGOUT/ACCOUNT_DELETION/SESSION_END)가 손상 행 하나에 영구히 막힘** + - 위치: `src/adapters/storage/indexeddb/indexeddb-runtime.ts:2584-2619`, `:2485-2531`, `:2533-2582` + - 문제: purge가 지울 행까지 `isStoredRecord` 등으로 검증하고 budget 카운터도 확인한다. 하나라도 어긋나면 `CORRUPT_DATA`로 트랜잭션이 abort되고 다음 batch도 처음부터 다시 시작한다. `deleteDatabase` 같은 우회 경로가 없다. + - 시나리오: sidecar 없는 record 1개나 budget 카운터 1 차이로 계정 삭제가 매번 실패하고 개인 데이터가 기기에 남는다. + - 수정 방향: 파티션 purge는 값 검증 없이 key로 지우고 COMPLETE 때 budget을 0으로 리셋한다. 손상은 observe로만 보고한다. + - 테스트: 손상 행 테스트는 RETENTION_SWEEP에만 있다(`tests/unit/indexeddb-runtime.test.ts:1035`). + +5. **[필수·확인됨] prepared-object 검증기 3벌 → OPFS 정책을 바꾸면 기존 객체를 못 읽음** + - 위치: `opfs-worker-runtime.ts:1687-1783`(`:1739`), `indexeddb-opfs-journal.ts:1624-1720`, `opfs-worker-client.ts:664-677` + - 문제: journal은 `chunkSizeBytes >= 1`만, worker는 현재 정책값과 정확히 같아야 통과, client는 얕은 검사만 한다. `isSupportedPhysicalSchema` 3벌(`client:646`, `worker:1677`, `journal:1614`), `stableJson` 2벌(NaN 처리 다름: `worker:1648` throw, `journal:1722` `"null"`). + - 시나리오: `chunkSizeBytes`를 4MiB → 8MiB로 바꾸면(`opfs-policy.ts:77-79` 허용 범위) 기존 객체 전부 `INTEGRITY_FAILED`, FILES_READY reconcile은 `CORRUPT_DATA`, COMMITTED reconcile은 `INVALID_INPUT`으로 계속 실패. + - 수정 방향: 검증기를 한 모듈로 합치고, 저장된 객체는 manifest의 `chunkSizeBytes`로 검증한다. 정책값은 새로 쓰는 데이터에만 적용한다. + +6. **[권장·확인됨, 타임아웃은 가능성] `openObject`가 객체 전체를 두 번 읽고 두 번 해시함** + - 위치: `opfs-worker-client.ts:335-347`, `opfs-worker-runtime.ts:691-735`, `:737-763` + - 문제: VERIFY_OBJECT가 모든 청크를 읽고 해시한 뒤 READ_CHUNK가 다시 읽고 해시한다. 2GiB 객체는 첫 바이트 전에 2GiB를 처리해야 하고, 60초 RPC 안에 못 끝나면 영영 열 수 없다. + - 수정 방향: 사전 검증은 manifest 대조만 하고 root digest는 스트림 끝에서 확인한다. + +7. **[권장·확인됨] IndexedDB 저장 스키마 타입·검증기가 runtime/maintenance/governance에 복제됨** + - 위치: `indexeddb-runtime.ts:59-90`, `:225-303`, `indexeddb-maintenance.ts:40-79`, `:124-229`, `indexeddb-governance.ts:282-305` + - 문제: `Stored*` 타입, `isStored*`, 측정 공식, `countBucket`, `failureOf`가 두 파일에 있고 governance에 세 번째 budget 검사가 있다. 한쪽만 고치면 정상 행이 손상으로 판정된다(4번과 겹치면 purge도 막힘). runtime은 2744줄이고 CAS 하나(`:1647-1878`)가 콜백 10단 중첩이다. + - 수정 방향: `indexeddb-records.ts`로 모은다. + +8. **[권장·확인됨] 삭제 후 재생성 시 revision/generation이 1로 돌아감 (ABA)** + - 위치: `indexeddb-runtime.ts:1693`, `:1955`, `opfs-byte-store-adapter.ts:204` + - 시나리오: 삭제 전에 revision 1을 읽은 writer가 `expectedRevision: 1`로 CAS하면 새 레코드를 덮어쓴다. OPFS도 `open({generation: 1})`이 다른 객체를 돌려줄 수 있다. + - 수정 방향: 마지막 revision을 tombstone으로 남기고 이어서 번호를 매긴다. 의도라면 port 주석에 명시한다. + +9. **[사소·확인됨] 보상이 실패하면 put의 원래 실패 원인이 가려짐** + - 위치: `opfs-byte-store-adapter.ts:248-264` + - 시나리오: 사용자 취소(ABORTED)나 쿼터 초과에 ABORT_PUT 보상까지 실패하면 `CONFLICT`/`OBJECT_RECONCILE`만 받는다. + - 수정 방향: 원래 코드를 유지하고 recovery만 `RECONCILE`로 바꾼다. + +10. **[사소·확인됨] kernel 계약의 작은 구멍 2개 (현재 걸리는 호출자 없음)** + - `src/adapters/platform/indexeddb-transaction.ts:246-277`: `succeed()` 뒤 `fail(x)`가 오면 x가 버려진다("first failure wins"와 다름). + - `src/adapters/platform/indexeddb-connection.ts:328-359`: caller abort가 upgrade보다 먼저 settle되어도 `onupgradeneeded`가 migration을 커밋한다. + - 수정 방향: `fail`이 성공 후보를 덮어쓰게 하고, `onupgradeneeded` 첫 줄에 `if (settled) { abortUpgrade(); return; }`. + +잘 된 점: kernel이 settle-once, 늦은 연결 닫기, 리스너/타이머 정리를 한 곳에서 처리하며 예전 4벌 상태 기계를 대체했다. worker 응답 디코더가 accessor, 미정의 key, kind 불일치를 거절한다. 쿼리 페이지네이션이 "페이지 가득 참"과 "스캔 한도 도달"의 재개 지점을 구분한다. + +### 6.6 web-push / service-worker + +요약: 업데이트 활성화(페이지 ↔ 대기 워커 메시지)에 막히는 경로가 3개 있다. 첫 방문에 설치 중인 워커를 ACTIVE로 보고한다. Web Push는 입력 검증과 클릭 URL 제한이 튼튼하지만, logout 뒤 해제 실패 시 새 계정을 자동 등록한다. + +1. **[필수·가능성(높음)] 활성화 성공 응답을 페이지가 PROTOCOL_MISMATCH로 처리** + - 위치: `src/adapters/service-worker/service-worker-page-controller.ts:334` + - 문제: 워커는 `skipWaiting()` 뒤에 `ACTIVATE_ACCEPTED`/`ACTIVATED_RELOAD_REQUIRED`를 보낸다(`service-worker-lifecycle.ts:292-305`). 이때 `registration.waiting`은 이미 `null`이다. 속성 갱신이 메시지보다 먼저 오면 `registration?.waiting !== waiting` 검사에 걸린다. + - 시나리오: 활성화는 확정됐는데 요청한 탭은 실패로 알고 새로고침하지 않는다. 옛 빌드 코드로 새 워커 아래에서 계속 돈다. + - 확인 방법: 실제 Chromium에서 두 빌드로 업데이트를 돌리는 Playwright 테스트. + - 수정 방향: 확정 이후 메시지는 `registration.active === waiting`도 허용하고, nonce/kind로 먼저 거른 뒤 source를 검사한다. + - 테스트: 성공 경로 테스트 없음. fixture가 `registration.waiting`을 바꾸지 않는다. + +2. **[필수·확인됨 ✓] 다른 빌드 탭이 하나라도 있으면 활성화가 항상 30초 타임아웃** + - 위치: `service-worker-lifecycle.ts:364-370`, `:381-395`, `service-worker-page-controller.ts:209-215` + - 문제: 워커가 drain 요청을 `targetBuildId: requesterBuildId`로 보낸다. 페이지는 target이 자기 빌드가 아니면 `TARGET_BUILD_MISMATCH`로 버린다. 워커도 `sourceBuildId !== requesterBuildId` 응답을 무시한다. + - 시나리오: 배포 후 탭 A는 빌드 N, 새로고침한 탭 B는 N+1(navigation이 NETWORK_ONLY라 항상 이렇게 됨). B가 활성화를 요청하면 A가 답하지 않아 30초 뒤 `CLIENT_DRAIN_TIMEOUT`. 반대도 같다. Chrome이 얼린 백그라운드 탭도 활성화를 막는다. + - 수정 방향: requester 빌드 필터를 없애고 워커 자신의 buildId와 nonce로만 짝을 맞춘다. + - 테스트: 없음. + +3. **[필수·확인됨] 요청하지 않은 탭은 활성화 뒤에도 새로고침하지 않고, 새 워커는 이전 캐시를 안 씀** + - 위치: `service-worker-page-controller.ts:242`, `service-worker-lifecycle.ts:194-199`, `:220-226`, `src/contracts/service-worker.ts:147-152` + - 문제: 모든 탭에 `ACTIVATED_RELOAD_REQUIRED`를 보내지만 일반 리스너는 `observe()`만 하고, `ServiceWorkerRuntimeHost`에 앱에 알릴 방법이 없다. 새 워커의 `onFetch`는 현재 캐시만 읽는다. 옛 빌드 lazy chunk는 네트워크로 가고 서버에서 지웠으면 ChunkLoadError. `onActivate`가 남긴 이전 캐시는 어디서도 읽지 않고, `void SERVICE_WORKER_BOUNDS.retainedPreviousCaches`(`:199`)는 아무 일도 안 한다. 6시간마다 `registration.update()`로 waiting이 생겨도 앱에 알리는 경로가 없다. + - 수정 방향: host 계약에 `onReloadRequired`/`onUpdateWaiting` 구독을 추가하고, current miss 때 marker로 찾은 previous 캐시를 fallback으로 읽는다. + +4. **[필수·확인됨] 첫 방문에서 `start()`가 설치 중인 워커를 `ACTIVE`로 보고** + - 위치: `service-worker-page-controller.ts:183-197` + - 문제: `register()`는 `installing` 상태에서 resolve된다. 첫 방문에는 `active`/`waiting`이 `null`이라 `{kind:"ACTIVE"}`를 돌려준다. 설치가 실패해도(5번) 매 방문 ACTIVE를 보고한다. + - 수정 방향: `installing`이 있으면 `statechange`를 제한 시간 안에서 기다리거나, `!container.controller`면 `RELOAD_TO_ENABLE`/INSTALLING을 반환한다. + - 테스트: fixture가 `installing: null`로 고정. + +5. **[필수·가능성] 흔한 서버 설정에서 static 설치가 항상 실패** + - 위치: `service-worker-static-assets.ts:250-256`, `:319-327` + - 문제: content-type을 정확 일치로 비교한다(`.js` → `text/javascript`). `application/javascript`로 응답하는 서버에서 `CONTENT_TYPE_INVALID`. `Content-Encoding: gzip/br` + `Content-Length`(압축 크기)를 압축 해제 크기와 비교해 `BYTES_MISMATCH`. + - 확인 방법: nginx gzip_static 또는 `application/javascript`로 dist를 서빙하고 install이 rejected 되는지 본다. + - 수정 방향: JS MIME 동의어 집합을 쓰고, `content-encoding`이 있으면 Content-Length 비교를 건너뛴다(크기는 스트림 바이트와 sha256으로 이미 검증). + +6. **[필수·확인됨 ✓] fetch 핸들러가 모든 요청에 `respondWith` 호출 (성능)** + - 위치: `src/adapters/service-worker/service-worker-entry.ts:92-103` + - 문제: navigation, API, cross-origin까지 `onFetch → fetch(request)`를 거친다. `PWA_STATIC_ASSETS` 없이 WEB_PUSH만 선택해도 그렇다. navigation preload도 꺼져 있어 모든 이동과 API 호출이 "워커 부팅 → 네트워크"로 직렬화된다. + - 수정 방향: GET이고 navigate가 아니고 `runtime.manifestUrls.has(url)`일 때만 `respondWith`를 부른다. + - 테스트: 없음. + +7. **[필수·확인됨] logout 뒤 native 구독이 남으면 `reconcile`이 새 계정을 opt-in 없이 자동 등록** + - 위치: `src/adapters/web-push/push-subscription-adapter.ts:345-354`, `:876-880`, `push-association-fence-store.ts:246-256` + - 시나리오: 오프라인 logout → `unsubscribe()` 실패 → fence는 REVOKED, native 구독은 살아 있음 → 사용자 B 부팅 → `reconcile(B)` → 서버 `ABSENT` → `registerAndActivate`. fence store도 REVOKED → 다른 epoch ACTIVE 전환을 허용한다. 설계 문서의 "새 account opt-in은 consent 재평가", "기존 association 재사용 금지"와 어긋난다. 이전에 연기한 WP-04와는 다른 문제다. + - 수정 방향: `ABSENT` 재등록은 local association이 ACTIVE였던 경우(크래시 복구)에만 하고, REVOKED/UNASSOCIATED면 native를 unsubscribe한다. + - 테스트: 없음. + +8. **[권장·확인됨] asset 목록이 같은 두 워커 빌드에서 설치가 실패하면 현재 쓰는 캐시를 지움** + - 위치: `service-worker-static-assets.ts:126`, `:150-151`, `scripts/generate-service-worker-assets.ts:89-91` + - 문제: 캐시 이름이 asset 목록 digest로만 정해져 같은 `VITE_BUILD_ID`로 워커만 바뀐 빌드는 active 워커와 같은 캐시에 설치한다. 실패 시 `caches.delete(cacheName)`이 서빙 중인 캐시와 marker를 지운다. + - 수정 방향: 후보 캐시 이름이 active 캐시와 같으면 설치를 건너뛰거나 실패해도 지우지 않는다. + +9. **[권장·확인됨] activate가 marker를 쓴 뒤에야 오래된 캐시를 지움** + - 위치: `service-worker-lifecycle.ts:171-198` + - 문제: 공간 부족으로 `currentCache.put(marker)`가 throw하면 삭제 루프가 실행되지 않는다. 공간이 영영 회복되지 않는다. + - 수정 방향: 삭제를 먼저 하고 marker 쓰기는 try/catch로 감싼다. + +10. **[권장·확인됨] 활성화 대기 중 관련 없는 메시지로 PROTOCOL_MISMATCH + 페이지·워커 타임아웃 동일** + - 위치: `service-worker-page-controller.ts:317-337`, `:299` + - 문제: `SYNC_WAKE_OBSERVED`(`service-worker-entry.ts:161-166`)나 `CACHE_RESET_RESULT`가 오면 nonce/kind 확인 전에 source 검사에 걸려 실패한다. 두 deadline이 모두 `clientDrainMs`(30초)라 마지막 탭이 29초에 답하면 페이지는 TIMEOUT인데 워커는 `skipWaiting`까지 확정한다. + - 수정 방향: nonce/kind로 먼저 거르고, 페이지 deadline에 여유분을 더한다. + +11. **[권장·가능성] push/알림 클릭을 거절할 때 사용자에게 아무것도 보여주지 않음** + - 위치: `src/adapters/web-push/inbound/push-event-adapter.ts:106-150`, `inbound/notification-click-adapter.ts:110-114`, `:163-170` + - 문제: EXPIRED, RELEASE_MISMATCH, fence 읽기 실패, deadline 초과가 알림 없이 끝난다. Chrome은 대신 "This site has been updated in the background"를 띄운다. Safari는 조용한 push가 반복되면 구독을 취소한다고 알려져 있다. 클릭도 `expiresAt`(최대 24시간) 초과나 fence 불일치면 창을 열지 않는다. drop 자체는 설계 의도다. + - 확인 방법: WebKit의 조용한 push 정책 문서 확인. + - 수정 방향: 계정 정보 없는 generic 알림 fallback, 클릭 실패 시 앱 루트 열기. 또는 트레이드오프를 문서에 명시한다. + +12. **[사소·확인됨] web-push 중복 helper, 파일 비대, 버려지는 주입값** + - `base64UrlDecode` 2벌: `push-subscription-adapter.ts:1093`(`>>>`), `push-registration-gateway.ts:298`(`>>`), 끝 비트 검증 조건도 다르다. + - `OPAQUE_ID` 3벌: `push-codec.ts:11`, `push-association-fence-store.ts:19`, `push-registration-gateway.ts:9`. + - `validAuthority` 2벌: `push-association-fence-store.ts:668`, `push-registration-gateway.ts:247`(null 방어 없음 → TypeError). + - `push-subscription-adapter.ts` 1139줄. + - `service-worker-page-controller.ts:268`이 전역 `document`를 쓴다. `src/bootstrap/register-service-worker.ts:22`는 `host.document`를 받지만 넘기지 않는다. + - 수정 방향: `web-push/codec-primitives.ts`로 모은다. + +잘 된 점: push payload에서 제목·본문·URL을 받지 않고 registry 고정 문구와 same-origin 경로만 쓴다. static 설치의 sha256 검증, 바이트 상한, all-or-nothing, deadline 뒤 정리. 캐시·등록 소유권 판정으로 남의 캐시를 지우는 경로가 없다. + +### 6.7 contracts (`src/contracts/`) + +요약: 입력 검증 함수 5개가 잘못된 값을 통과시킨다(멱등 키, 설정 키, 매니페스트 URL, REST 명령 메서드, operationId). 모두 에이전트가 node로 재현했다. 스냅샷·exact-key 로직이 모듈마다 달라 두 곳에서 불변식이 깨진다. 레이어 위반은 없고 1000줄 넘는 파일도 없다(최대 `browser-rpc.ts` 979줄). + +1. **[필수·확인됨] 멱등 키 검증이 fetch가 잘라내거나 거부할 값을 통과시킴** + - 위치: `src/contracts/mutation-intent.ts:34` + - 문제: `trim()` 후 비어 있지 않은지와 C0/C1 제어문자만 검사한다. 주석은 "never trimmed"라고 한다. + - 시나리오 A: `" order-1 "`가 통과하고 `Headers.set`이 `order-1`로 잘라 보낸다. 서로 다른 두 명령이 같은 키를 갖고 두 번째는 재전송으로 처리되어 적용되지 않는다. + - 시나리오 B: `"키-값"`이 통과하고 `headers.set`이 ByteString TypeError를 던진다. `src/adapters/http/client.ts:772`의 catch가 `NETWORK_UNREACHABLE`(재시도 가능)로 바꾼다. + - 수정 방향: `^[\x21-\x7E]{1,256}$`로 제한한다(`realtime-events.ts:77` `HEADER_SAFE_CURSOR`와 같은 규칙). + - 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`이 `"키-값"`, `"ключ"`를 유효 키로 고정하고 있다. 함께 고쳐야 한다. + +2. **[필수·확인됨 ✓] 설정 키 금지어 검사가 FEATURE_OVERRIDES 안의 기능 ID까지 걸러 킬스위치 사용 시 부팅 실패** + - 위치: `src/contracts/env.ts:73-89` + - 문제: `assertSafeConfigNames`가 중첩 객체 키까지 재귀 검사한다. FEATURE_OVERRIDES의 키는 설정 이름이 아니라 기능 ID(데이터)다. `release-artifacts.ts:67`의 기능 ID 정규식은 `cookie-consent`, `password-reset`, `token-wallet`을 허용한다. + - 시나리오: 장애 중 `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`를 배포하면 `load-runtime-config.ts:110`에서 `CONFIG_SECRET_NAME_REJECTED`가 나고 앱 전체가 부팅되지 않는다. + - 수정 방향: 값을 키로 쓰는 맵은 재귀에서 빼거나, 그런 기능 ID를 빌드 시점에 거부한다. + - 테스트: 없음. + +3. **[필수·확인됨] 릴리스 매니페스트 URL의 same-origin 검사를 탭 문자로 우회** + - 위치: `src/contracts/release-artifacts.ts:28` + - 문제: `//` 시작, `?`, `#`, `\`, `%2f`만 검사한다. WHATWG URL 파서는 탭/CR/LF를 지운다. `"/\t/evil.example/m.json"`이 통과해 `https://evil.example/m.json`이 된다. `/a/%2e%2e/b`도 통과 후 `/b`가 된다. 설정은 운영자가 관리해 원격 공격 경로는 아니지만 검증 약속이 깨져 있다. + - 수정 방향: `new URL(v, "https://x.invalid")`로 해석해 origin 유지와 `pathname === v`를 확인하거나, `^/[A-Za-z0-9._~/-]+$` 허용 목록. + - 테스트: `tests/runtime-schema/runtime-config.test.ts:49-54`는 `..`와 `?`만. + +4. **[필수·확인됨] REST V2가 COMMAND를 GET으로 허용하고 CSRF 필요 여부는 메서드로만 판단** + - 위치: `src/contracts/api-operations.ts:182`, `src/contracts/rest-profiles.ts:240` + - 문제: `validateRestOperation`은 QUERY가 GET/HEAD인지만 보고, `semantics`/`replayPolicy` enum도 검증하지 않는다. `resolveRestSecurityProfiles`는 `unsafe`를 메서드로만 정한다. `{semantics:"COMMAND", method:"GET"}` + SAME_ORIGIN_COOKIE + csrf NONE이 통과한다. browser-rpc(`browser-rpc.ts:652-666`)와 V3(`external-contract-runtime.ts:448-469`)는 이 규칙을 강제한다. 지금 설치된 쿠키 프로필이 없어 잠재 결함이다. + - 수정 방향: COMMAND면 POST/PUT/PATCH/DELETE만 허용하고 enum을 검증한다. + - 테스트: 없음. + +5. **[필수·확인됨] operationId 형식이 4곳에서 달라 API 실패 텔레메트리가 드롭됨** + - 위치: `src/contracts/telemetry.ts:111`, `src/contracts/external-contract-runtime.ts:237` + - 문제: V3 합성은 `^[A-Za-z][A-Za-z0-9_.-]{0,127}$`(camelCase 허용), 텔레메트리 `operation_id`는 `^[A-Z][A-Z0-9_]{0,63}$`다. `api.request.failed`가 `invalid-attribute-value`로 떨어지고 `best-effort-telemetry.ts:162`에서 drop된다. diagnostics `SAFE_VALUE`(`diagnostics.ts:123`)는 64자 제한이다. `api-operations.ts:54`, `browser-rpc.ts:185`는 `{2,79}`다. `http_status_group`도 diagnostics `[0-9]xx`, 텔레메트리 `[1-5]xx`로 다르다. + - 수정 방향: OPERATION_ID를 contracts에 하나만 두고 재사용한다. + +6. **[권장·확인됨] 스냅샷 불변식이 모듈마다 달라 두 곳에서 뚫림** + - (a) `external-contract-runtime.ts:751` vs `:770`: TEMPLATE_FIXTURE의 이벤트 기여 금지 검사는 `.length`로, 설치는 iterator로 한다. 배열에 `Symbol.iterator`를 달면 길이 0으로 통과 후 이벤트가 설치된다. `exact-snapshot.ts:154`의 `snapshotExactArray`를 쓰지 않는다. + - (b) `realtime-streams.ts:529` `hasExactKeys`가 `Object.keys`만 봐서 getter를 허용하고, 검증과 `{...input}` 복사에서 두 번 읽는다(`:465-486`). getter로 `maxEventBytes` 999,999,999가 설치된다(하드 상한 65,536). + - exact-key 구현 6곳: `exact-snapshot.ts:66`, `read-only-registry.ts:54`(try/catch 없음), `browser-rpc.ts:399`(enumerable 미검사), `realtime-streams.ts:529`, `cache-invalidation.ts:208`, `service-worker-static-manifest.ts:98`. + - 입력이 컴파일 시점 코드라 권장으로 분류했다. + - 수정 방향: `exact-snapshot.ts`로 통일하고 배열 스냅샷을 추가한다. + - 테스트: `tests/unit/contract-registry-immutability.test.ts`는 객체 단위만. + +7. **[권장·확인됨] 검증된 인덱스/레지스트리가 수정 가능한 상태로 반환됨** + - 위치: `src/contracts/query-invalidation.ts:185`, `:232`, `web-worker.ts:138`, `offline-command.ts:152`, `runtime-capabilities.ts:199` + - 문제: `Object.freeze({ namespacesForTopic: new Map(...) })`는 바깥만 얼린다. `.clear()`가 동작한다. 나머지는 바깥 배열만 얼려 내부 상한값 객체를 바꿀 수 있다. `read-only-registry.ts` 주석(LIVE-02)이 바로 이 버그를 설명한다. + - 수정 방향: `createReadOnlyRegistry`를 쓰고 각 row를 스냅샷해 얼린다. + +8. **[권장·확인됨] 같은 개념이 두 모양: 검증기 프로토콜 2개, `MappingResult` 2개** + - `RuntimeValidator.safeParse`(`external-contract-runtime.ts:43-50`, path 배열) vs `RuntimeSchemaCodec.parse`(`schema-registry.ts:18-28`, path 문자열). reference feature가 zod 래퍼를 두 번 쓴다(`reference-feature-contract-contribution.ts:34`, `:88`). + - `MappingResult`: `boundary-mapper.ts:6` `{ok:false, code}` vs `external-contract-runtime.ts:84` `{ok:false, error:{kind, code}}`. 잘못 import해도 컴파일된다. + - 수정 방향: 각각 하나로 합친다. + +9. **[권장·확인됨] 인증 프로필 기준 원본이 둘로 갈림** + - 위치: `external-contract-runtime.ts:337`, `rest-profiles.ts:235` + - 문제: 합성은 모듈 전역 `INSTALLED_REST_AUTH_PROFILES`, 실행기는 주입된 `dependencies.authProfiles`(`http-execution-v3.ts:413`)를 쓴다. V2 클라이언트는 검증 안 된 `REST_AUTH_PROFILES`를 직접 쓴다(`client.ts:565`). BEARER_HEADER + `credentials:"same-origin"`이 install에서는 거부되지만 resolve에서는 통과한다. + - 수정 방향: resolve가 `InstalledRestAuthProfiles`를 받게 하고 합성은 레지스트리를 매개변수로 받는다. + +10. **[권장·확인됨] 배포 승인이 IPv6·사설 대역 호스트를 공개 주소로 봄** + - 위치: `src/contracts/deployment-admission.ts:139` + - 문제: `https://[::ffff:127.0.0.1]/`, `[fd00::1]`, `[fe80::1]`, `100.64.0.1`, `0.1.2.3`, `api.internal`이 production 승인을 받는다. 로컬 호스트 목록이 3곳에 따로 있다(`browser-rpc.ts:780`, `rest-profiles.ts`, 이 파일). + - 테스트: IPv4 사설 대역만(`tests/unit/deployment-admission.test.ts:67-68`). + +11. **[사소·확인됨] 레지스트리 조회가 프로토타입 체인까지 내려감** + - `getApiOperation("constructor")`가 `Object` 함수를 반환(`api-operations.ts:203`). + - `getStorageDefinition("__proto__")`가 `Object.prototype`을 반환(`storage-keys.ts:162`). + - `isAllowedOfflineTransition`이 모르는 상태에 TypeError를 던짐(`offline-command.ts:102`). false가 맞다. + - 지금 호출자는 상수만 넘긴다. 수정: `Object.hasOwn`. + +12. **[사소·확인됨] 조용한 통과와 자잘한 문제** + - `release-tokens.ts:62`: runtime 쪽 `assetManifestHash`를 release 자신의 값으로 채워 비교가 항상 일치한다. "비교 안 함"이 아니라 "통과"로 나온다. + - `contract-set.ts:119`: `expected`에 packageId 중복 + `expectedSetDigest` 없음이면 예외가 나서 Promise가 reject된다. + - `query-keys.ts:217`: 새 identity intern마다 전체 row 복사·정렬(O(n log n), n ≤ 4096). + - `.dependency-cruiser.json`은 contracts → presentation/bootstrap 방향을 막지 않는다(현재 위반은 없음). + +잘 된 점: `contract-set-canonical.ts`의 정규화(길이 접두, UTF-8 바이트 정렬, 중복 거부). `realtime-events.ts`의 시퀀스(BigInt 상한)·타임스탬프 검증, `cache-invalidation.ts`의 크기·TTL·clock skew 제한. `read-only-registry.ts`의 Map 불변 처리. + +### 6.8 presentation (`src/presentation/`) + +요약: adapter 직접 import, `any`, `@ts-ignore`, `dangerouslySetInnerHTML`은 없다. 버그는 라우팅에 몰려 있다. React Router가 형제 라우트의 컴포넌트 인스턴스를 재사용하는 점, route-change 부수효과(포커스·제목·텔레메트리)의 위치에서 청크 복구 고착, 로케일 초기화, 포커스 버그가 나온다. 상태 화면과 세션 액션이 여러 벌이다. + +1. **[필수·확인됨 ✓] 청크 복구 실패 화면이 다른 라우트로 이동해도 풀리지 않음** + - 위치: `src/presentation/boundaries/chunk-recovery-boundary.tsx:38-84`, `src/presentation/routes/app-router.tsx:316-326` + - 문제: React Router 7.18은 `RenderedRoute`에 key를 붙이지 않아 형제 라우트 이동 시 `ChunkRecoveryBoundary`까지 같은 인스턴스가 재사용된다. boundary에 resetKey/key가 없어 `error`/`support` 상태가 남는다. 실패 화면(`:109-114`)에 재시도·새로고침 버튼이 없다. + - 시나리오: 오프라인에서 아직 안 받은 `/examples/states`로 이동 → 청크 실패 → `manifest-unavailable`로 `support` → 메모리에 있는 홈으로 돌아가도 "화면 자산을 복구하지 못했습니다"가 계속 보인다. 브라우저 새로고침만이 탈출구다. + - 수정 방향: `` 또는 resetKey + `componentDidUpdate`. 실패 화면에 `action.reloadOnce` 버튼. + - 테스트: `tests/component/chunk-recovery-boundary.test.tsx`에 리셋 케이스 없음. + +2. **[필수·확인됨] Safari와 Vite CSS preload 실패를 청크 실패로 인식하지 못함** + - 위치: `chunk-recovery-boundary.tsx:27-36` + - 문제: 판별 문자열에 WebKit `"Importing a module script failed."`와 Vite `"Unable to preload CSS for …"`가 없다. Safari 사용자는 배포 뒤 옛 청크 요청 시 일반 렌더 오류로 분류되어 reload-once 복구가 실행되지 않는다. + - 수정 방향: 두 문자열을 추가하고, bootstrap에서 `vite:preloadError`도 받는다. + - 테스트: Chrome 메시지 하나만. + +3. **[필수·확인됨] 로케일이 저장되지 않고 세션이 바뀔 때마다 ko-KR로 초기화** + - 위치: `src/presentation/i18n/locale-provider.tsx:76`, `:81`, `app-router.tsx:497`, `src/presentation/adapters/query/server-state-scope-provider.tsx:31-35` + - 문제: 로케일이 `useState`에만 있고 preferences 포트에 locale 항목이 없다(테마는 `preferences.setColorScheme`으로 저장됨). `LocaleProvider`는 `AppRouter` 안, `AppRouter`는 `ServerStateScopeProvider` 아래에 있다. 세션 알림 → scope `FENCED`(`server-state-scope-runtime.ts:90-104`) → transitionFallback 렌더로 앱 트리 전체 unmount → `READY`에서 `ko-KR`로 다시 mount된다. + - 시나리오: en-US를 고르고 로그인/로그아웃하면 한국어로 돌아간다. + - 같은 remount의 추가 영향: 작성 중 폼 입력이 dirty guard 없이 사라진다(가능성, auth owner의 알림 빈도에 따름). `AppRouter:489`의 `useMemo` browser router가 `dispose()`되지 않아 remount마다 popstate 리스너가 쌓인다. + - 수정 방향: locale을 preferences 포트로 저장하고, Locale/Theme provider를 scope fence 바깥(bootstrap)으로 올리고, unmount 시 `router.dispose()`. + - 테스트: `tests/e2e/i18n.spec.ts`, `tests/component/locale-platform.test.tsx`에 저장·세션 전환 케이스 없음. + +4. **[필수·확인됨] 언어를 바꾸면 포커스 이동, 맨 위 스크롤, route 변경 재보고** + - 위치: `app-router.tsx:145-171` + - 문제: `RouteLifecycle` effect 의존성에 `message`/`resolve`가 있고, 이 둘이 locale 변경마다 새로 만들어진다(`locale-provider.tsx:108`). `docs/architecture/routing-pages-and-patterns.md:467`의 "locale 변경은 title과 copy만 다시 렌더" 계약과 어긋난다. + - 가능성: `location.key` 의존 때문에 해시만 바뀌는 이동(스킵 링크, `ErrorSummary`의 `#field`)에서도 다시 실행될 수 있다. 브라우저 확인 필요. + - 수정 방향: 제목 effect(locale 의존)와 포커스·스크롤·텔레메트리 effect(`pathname`+`search` 의존)를 나눈다. + - 테스트: 없음. + +5. **[필수·확인됨] 인증필요·잘못된 주소·비활성 기능 화면에서 제목·포커스·텔레메트리가 동작하지 않음** + - 위치: `app-router.tsx:304-314`, `:316-335` + - 문제: `RouteLifecycle`이 `content` 안에만 있는데 `ProtectedRoute`, `InvalidRouteSurface`, `DisabledFeatureSurface`는 `content`를 렌더하지 않는다. + - 시나리오: 익명 상태에서 reference 라우트에 들어가면 `document.title`이 이전 페이지 그대로이고, 포커스가 NavLink에 남아 스크린리더 사용자는 페이지가 바뀐 것을 모른다. 텔레메트리도 빠진다. + - 수정 방향: `RouteLifecycle`을 `RegisteredRoute` 최상단으로 올린다. + +6. **[필수·확인됨] 모바일 드로어로 이동하면 포커스가 햄버거 버튼으로 감** + - 위치: `src/presentation/layouts/app-shell.tsx:44-46`, `:153-161`, `src/presentation/design-system/primitives/core.tsx:374-391` + - 문제: 자식 effect `RouteLifecycle`이 `main.focus()`를 먼저 부르지만 modal이 열려 있어 main이 inert다. 부모 effect가 드로어를 닫고, `Dialog`가 `setTimeout`으로 `returnFocusRef`(메뉴 버튼)에 포커스를 복원한다. 데스크톱은 h1이 포커스를 받는다. + - 수정 방향: 네비게이션으로 닫힐 때는 포커스 복원을 끄거나, route 포커스를 dialog 닫힘 뒤로 미룬다. + - 테스트: `tests/e2e/app-shell.spec.ts`는 Escape 닫기만. + +7. **[필수·확인됨] context 라우트 게이트웨이가 이전 context의 routes로 한 번 렌더되고 청크 실패 복구를 거치지 않음** + - 위치: `app-router.tsx:375-419` + - 문제 (a): `ContextRouteGateway`도 key 없이 재사용된다. context A → B 이동 첫 렌더에서 A의 routes로 B 경로를 매칭해 `NOT_FOUND`가 mount되고 텔레메트리·제목·포커스가 한 번 튄다. 지금은 context가 하나라 드러나지 않지만 하나 더 추가하면 바로 발생한다. + - 문제 (b): `loadRoutes()`의 dynamic import 실패 시 `RouteFailureSurface`만 보이고 `recoverChunk`(reload-once)를 거치지 않는다. 도메인 확장의 주 경로가 배포 직후 청크 실패 복구에서 빠져 있다. + - 수정 방향: `key={routeModule.id}` 또는 `{moduleId, routes}` 상태. 로드 실패는 `isChunkLoadFailure`로 판별해 `recoverChunk`로 넘긴다. + +8. **[필수·확인됨 ✓] `useApplicationQuery({enabled:false})`가 영원히 로딩으로 보임** + - 위치: `src/presentation/adapters/query/application-query.ts:180` + - 문제: TanStack Query v5에서 데이터 없는 disabled 쿼리는 `isPending=true`(fetchStatus `idle`)다. `isInitialLoading: query.isPending`을 그대로 넘긴다. + - 시나리오: 선행 값을 기다리는 의존 쿼리가 `AsyncSurface`에서 계속 스켈레톤과 `aria-busy`를 보여준다. + - 수정 방향: `query.isLoading`(isPending && isFetching)을 넘긴다. + - 테스트: `enabled` 케이스 없음. + +9. **[권장·확인됨] 디자인시스템 링크가 router와 basename을 우회** + - 위치: `src/presentation/templates/page-templates.tsx:247-254`, `design-system/primitives/navigation.tsx:24`, `:178`, `core.tsx:78-105` + - 문제: `PageActionBar` link, `Breadcrumbs`, `LinkButton`이 모두 ``다. `routerBasePath`가 `/`가 아닌 배포에서 basename이 빠진 URL로 이동하고, 전체 리로드로 query cache와 UI 상태가 날아간다. `Pagination`의 `href="?page=N"`은 다른 검색 파라미터를 지운다. + - 수정 방향: `to`를 받아 `Link`로 렌더한다. + +10. **[권장·확인됨] 상태 화면과 세션 액션이 여러 벌** + - 로딩: `components/async-surface.tsx:9`, `app-router.tsx:64`, `app-router.tsx:407-413`(라벨 없음), `chunk-recovery-boundary.tsx:96`, `pages/home-page.tsx:29-37`과 `examples/platform-overview-page.tsx:287-295`(`.catch` 없어 reject 시 멈춤). + - 인증필요: `ProtectedRoute`(`app-router.tsx:243-273`), `AuthRequiredSurface`(`state-surfaces.tsx:31`), `StatusPage variant="unauthenticated"`. + - 404: `NotFoundPage`, `NotFoundSurface`, `StatusPage`. + - 세션 액션: `app-shell.tsx:48`, `app-router.tsx:213`, `auth-example-page.tsx:13`(세 번째만 `returnTo`에서 hash 누락). + - 수정 방향: route 레벨도 `LoadingSurface`/`StatusPage` 하나로, 세션 액션은 hook 하나로. + +11. **[권장·확인됨] Tooltip 설명이 보조기술에 전달되지 않음** + - 위치: `src/presentation/design-system/primitives/overlays.tsx:114` + - 문제: `aria-describedby`가 포커스 안 받는 wrapper ``에 붙어 있다. 내용이 항상 DOM에 있고 opacity만 0이다. Escape로 닫을 수 없다(WCAG 1.4.13). + - 수정 방향: `cloneElement`로 자식에 `aria-describedby`를 주입하고 Escape 닫기를 추가한다. + - 테스트: 없음. + +12. **[권장·확인됨] Pagination이 페이지 수만큼 링크를 전부 렌더** + - 위치: `design-system/primitives/navigation.tsx:160` + - 문제: `pageCount=5000`이면 링크 5000개, Tab 이동이 사실상 불가능하다. `CollectionPage`의 `