diff --git a/.dependency-cruiser.json b/.dependency-cruiser.json index b3c60795..1e022fd6 100644 --- a/.dependency-cruiser.json +++ b/.dependency-cruiser.json @@ -167,6 +167,17 @@ "path": "^src/(application|features)" } }, + { + "name": "contracts-do-not-know-presentation-or-bootstrap", + "comment": "Q-6.7-12. `src/contracts` is shared vocabulary read by every layer, including the service worker and web worker builds. Importing presentation or the composition root from it would pull React and the whole app into those builds. There is no such import today; this keeps it that way.", + "severity": "error", + "from": { + "path": "^src/contracts" + }, + "to": { + "path": "^src/(presentation|bootstrap)" + } + }, { "name": "generic-presentation-does-not-compose-the-product", "comment": "§4 / §9. Which features are installed is a product decision that belongs to bootstrap. Generic presentation reads the installed registries directly today; the paths below are the exact set that does so, frozen so the coupling cannot spread while the assembly is lifted into bootstrap.", diff --git a/.gitignore b/.gitignore index 2269a056..b19dcdf9 100644 --- a/.gitignore +++ b/.gitignore @@ -24,3 +24,6 @@ artifacts/tests/visual/ .env .env.* !.env.example + +# graphify knowledge-graph output (local analysis, not part of the product). +graphify-out/ diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 00000000..ad261b3a --- /dev/null +++ b/SPEC.md @@ -0,0 +1,228 @@ +# SPEC: src 리뷰(2026-09-24) 긴급·필수 항목 수정 + +## 목적 + +`docs/reviews/2026-09-24-src-full-review.md`의 **긴급 1건 + 필수 46건**을 고친다. 권장·사소 항목은 이번 범위가 아니다. + +각 요구사항 ID(R-x.y)는 리뷰 문서의 섹션 번호(6.x-y)와 같다. 문제 설명, 근거 코드, 실패 시나리오는 리뷰 문서를 기준으로 한다. 이 문서에는 **무엇이 되면 완료인지**와 **방향이 여러 개인 항목의 결정**만 적는다. + +## 범위 밖 + +- 리뷰의 권장·사소 항목. 단, 같은 코드 줄을 고치다가 자연히 해결되는 경우는 예외다. +- `src/` 밖의 리팩터링. 단, R-0이 요구하는 스크립트와 설정 변경, 그리고 버그를 고정하고 있는 기존 테스트의 수정은 포함한다. +- 공개 포트 시그니처의 파괴적 변경. 추가만 허용한다. + +## 공통 완료 기준 (모든 요구사항) + +1. 버그를 재현하는 테스트가 먼저 실패하고(RED), 수정 뒤 통과한다(GREEN). 브라우저 없이는 재현할 수 없는 항목은 fake/fixture로 조건을 만들어 재현한다. +2. `corepack pnpm check:architecture`, `check:types:app`, `check:types:test`, `lint`, `test:unit`, `test:component`이 통과한다. +3. adapter 파일을 추가하거나 이동하면 `docs/reviews/adapters/INVENTORY.md`를 함께 고치고 `check:adapter-inventory`가 통과한다. +4. adapter 간 공용 로직은 `src/adapters/platform/`(kernel)으로, 공유 어휘는 `src/contracts/`로 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다. +5. 요구사항 하나에 커밋 하나. 커밋 메시지에 R-ID를 적는다. + +## 요구사항 + +### R-0 빌드 기반 (긴급) +- 깨끗한 체크아웃(`src/.generated/` 없음)에서 `dev`, `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 사전 수동 명령 없이 동작한다. +- CI 게이트도 같은 조건에서 통과한다. + +### R-1 browser-transfer +- R-1.1 `dispose()`가 deadline 초과로 실패한 뒤 작업이 끝나면, 다시 호출할 때 store를 닫고 `CLOSED`가 된다. +- R-1.2 opaque ID 문법은 한 곳에서 정의한다. control plane이 받은 ID는 presigned 계층도 받는다. +- R-1.3 동시성 정책 검증은 `partSize × maxConcurrency × copyFactor`를 기준으로 한다. 기본 정책은 이 검증을 통과하고, createSession은 **실제 worker 수**를 요청한다. +- R-1.4 크기나 part 수 한도 초과는 `LIMIT_EXCEEDED`로 보고된다. + +### R-2 browser-files / cache-storage / cross-context +- R-2.1 BOUNDED_OBJECT_URL 전략에서 source open이 실패하거나 abort되면 `deliver()`는 reject하지 않고 Result를 반환한다. 늦게 온 lease는 닫힌다. +- R-2.2 source별 sequence watermark는 이벤트 TTL로 지워지지 않는다. 60초 넘게 쉰 뒤의 seq N+1은 `NEXT`다. +- R-2.3 broadcast 발행이 실패해도 수신 listener는 유지된다. broadcast를 받을 수 없는 탭은 `DEGRADED`로 보고된다. +- R-2.4 picker/save picker 함수는 options 객체에 bind되지 않는다. `window` 함수를 그대로 주입해도 동작한다. +- R-2.5 기본 cache 정책이 `Vary: Accept-Encoding` 응답을 받아들인다. `content-type`이 허용 응답 헤더에 없는 정책은 정책 검증에서 거부된다. + +### R-3 http / query-cache / auth +- R-3.1 경로 값 `.`과 `..`는 V3와 V2 모두에서 `PATH_VALUE_INVALID`(V2는 `PATH_PARAMETER_INVALID`)로 거부된다. +- R-3.2 세션 알림은 (상태, 주체)가 바뀔 때만 scope fence를 건다. demo 어댑터는 같은 값이면 알리지 않는다. V3의 요청 전 자격증명 없음은 `onUnauthenticated()`를 부르지 않는다. 서버 401만 부른다. **[고위험: 인증·캐시]** +- R-3.3 5xx/408/425 응답의 problem 바디가 유효하지 않으면 HTTP status를 담은 서버 장애로 분류된다. 요청 쪽 위반은 서버 응답 오류(`ENVELOPE_MISMATCH`)로 매핑되지 않는다. +- R-3.4 자격증명 헤더 값은 전송 전에 ByteString(제어문자 없음)으로 검증된다. 실패는 요청 전 단계의 인증 결함으로 분류된다. 대소문자만 다른 중복 헤더는 거부된다. **[고위험: 인증]** +- R-3.5 feature 바인딩에서 `mapSuccess`/`mapProblem`이 던지면 `MAPPING_CONTRACT_VIOLATION` Result로 반환되고 effect가 보존된다. + +### R-4 realtime +- R-4.1 `await quiescence` 뒤 DRAINING이면 recovery는 authority를 호출하지 않고 실패한다. +- R-4.2 `retryable:true`인 `PROVIDER_UNAVAILABLE`/`RATE_LIMITED`는 서버 hint가 없어도 재연결 대상이다(reconnect와 polling 모두). +- R-4.3 barrier가 필요 없는 recovery(barrier NONE)는 전송을 닫지 않고 계속된다. +- R-4.4 SSE 파서는 문자마다 인코딩하지 않는다. 250KB chunk 처리가 기존 대비 10배 이상 빨라진다(수동 측정 기록). + +### R-5 storage +- R-5.1 orphan 후보 목록은 커서로 이어서 볼 수 있다. 참조 중 청크가 100개를 넘어도 뒤의 orphan이 지워진다. **[고위험: 삭제]** +- R-5.2 dedup으로 재사용한 청크는 grace period 보호를 다시 받는다(mtime 갱신). **[고위험: 삭제]** +- R-5.3 mutation lock 대기 시간은 60초 RPC 타임아웃에 포함되지 않는다. lock 대기는 별도 상한 정책값으로 제한된다. +- R-5.4 파티션 purge는 손상 행이 있어도 끝까지 지운다. 손상은 observe로 보고한다. **[고위험: 삭제]** +- R-5.5 prepared-object 검증은 한 모듈에서 한다. 저장된 객체는 자기 manifest의 `chunkSizeBytes`로 검증되고, 현재 정책값은 새로 쓰는 데이터에만 적용된다. **[고위험: 데이터 판독]** + +### R-6 service-worker / web-push +- R-6.1 확정 이후 메시지(ACCEPTED/RELOAD_REQUIRED)는 `registration.waiting`이 비어도 성공으로 처리된다. 메시지는 nonce/kind로 먼저 거른다. +- R-6.2 drain 요청과 응답은 요청자 빌드와 무관하게 워커 buildId + nonce로 짝을 맞춘다. 다른 빌드 탭이 있어도 활성화가 끝난다. +- R-6.3 앱이 `reloadRequired`/`updateWaiting`을 구독할 수 있다. current 캐시에 없는 asset은 previous 캐시에서 찾는다. +- R-6.4 첫 방문에서 설치 중인 워커는 `ACTIVE`로 보고되지 않는다. +- R-6.5 JavaScript MIME 동의어를 허용한다. `content-encoding`이 있으면 Content-Length와 압축 해제 크기를 비교하지 않는다. +- R-6.6 fetch 핸들러는 manifest에 있는 same-origin GET(비 navigate) 요청에만 `respondWith`를 부른다. +- R-6.7 reconcile에서 서버가 `ABSENT`이면, local association이 ACTIVE였던 경우에만 재등록한다. 그 밖에는 native 구독을 해제한다. **[고위험: 동의]** + +### R-7 contracts +- R-7.1 멱등 키는 `^[\x21-\x7E]{1,256}$`만 허용한다. 이 버그를 고정한 기존 테스트도 고친다. +- R-7.2 FEATURE_OVERRIDES의 키(기능 ID)는 설정 이름 금지어 검사 대상이 아니다. +- R-7.3 릴리스 매니페스트 URL은 해석 뒤 origin과 pathname이 입력과 같아야 한다. 탭, 개행, 인코딩된 점 세그먼트는 거부된다. +- R-7.4 REST V2의 COMMAND는 POST/PUT/PATCH/DELETE만 허용된다. `semantics`/`replayPolicy`는 enum으로 검증된다. **[고위험: CSRF]** +- R-7.5 operationId 문법은 contracts 한 곳에서 정의하고 텔레메트리와 진단이 재사용한다. V3가 받는 operationId의 실패 이벤트는 드롭되지 않는다. + +### R-8 presentation +- R-8.1 청크 복구 실패 상태는 라우트가 바뀌면 초기화된다. 실패 화면에 "한 번 새로고침" 버튼이 있다. +- R-8.2 WebKit(`Importing a module script failed`)과 Vite CSS preload 실패가 청크 실패로 인식된다. +- R-8.3 선택한 로케일이 preferences에 저장되고 새로고침 뒤에도 유지된다. 세션이 바뀌어도 로케일과 테마는 초기화되지 않는다. unmount 시 router가 dispose된다. +- R-8.4 로케일 변경은 제목과 문구만 갱신한다. 포커스 이동, 스크롤, route 변경 보고는 일어나지 않는다. +- R-8.5 인증필요/잘못된 주소/비활성 기능 화면에서도 제목, 포커스, route 텔레메트리가 동작한다. +- R-8.6 모바일 드로어에서 링크로 이동하면 포커스가 새 페이지(h1/main)로 간다. 메뉴 버튼으로 가지 않는다. +- R-8.7 context 라우트 게이트웨이는 context가 바뀌면 이전 routes로 매칭하지 않는다. 모듈 로드 청크 실패는 `recoverChunk`를 거친다. +- R-8.8 `enabled:false` 쿼리는 로딩으로 표시되지 않는다. + +### R-9 bootstrap / platform +- R-9.1 TTL 안에 reload 마커가 있으면 키와 상관없이 자동 reload하지 않는다(세션당 최대 1회). 번갈아 오는 키 테스트를 추가하고, 연속 reload를 기대하던 테스트를 고친다. +- R-9.2 dedup 창 안의 중복 발생 횟수가 수집기로 전달된다. +- R-9.3 리댁션은 문자열 중간의 자격증명, URL 쿼리의 토큰, 이메일을 가린다. 키 목록에 `pwd`, `pass`, `auth`, `otp`, `pin` 계열을 추가한다. **[고위험: 보안]** + +## 결정 (방향이 여러 개였던 항목의 기본값) + +| ID | 결정 | 이유 | +|---|---|---| +| D-1 (R-0) | 생성 파일을 커밋하지 않는다. 생성 파일을 읽는 진입점(스크립트 또는 package script) 앞에서 생성기를 실행한다. | 6f6c48e가 앱별 생성(`PRODUCT_APP_ID`)을 의도했으므로 gitignore를 유지한다. | +| D-2 (R-1.3) | 기본 `maxConcurrency`를 실제 동작값에 맞춘다. 메모리 한도(`maxInFlightBytes`)는 올리지 않는다. | 지금 기본 동작(동시 1)을 바꾸지 않고, 문서와 코드만 일치시킨다. 다운스트림이 올릴 수 있다. | +| D-3 (R-5.3) | lock 범위는 줄이지 않는다(GC·dedup 정합성). lock 대기만 RPC 타임아웃에서 빼고, 별도 상한을 둔다. | 범위를 줄이면 R-5.2 같은 경합이 새로 생긴다. | +| D-4 (R-2.3) | 발행 쪽 이중 쓰기(broadcast + storage)는 하지 않는다. 수신 유지 + DEGRADED 보고만 한다. | 가장 작은 변경으로 흔한 경로(발행 1회 실패)를 고친다. | +| D-5 (R-8.3) | 로케일 저장은 테마와 같은 `preferences` 경로를 쓴다. Locale/Theme provider는 scope fence 바깥으로 올린다. | 이미 있는 테마 패턴을 재사용한다. | +| D-6 (R-9.2) | 누적 count는 dedup 창이 닫힐 때나 다음 flush 때 요약 이벤트의 `occurrences`로 보낸다. | 기존 이벤트 스키마(`occurrences`)를 그대로 쓴다. | +| D-7 (R-6.3) | previous 캐시 fallback은 hashed URL에만 적용한다. | hashed URL은 같은 URL이면 같은 내용이라 안전하다. | + +--- + +# 2차 라운드: 권장·사소 항목과 1차 후속 결정 + +1차 라운드(R-0 ~ R-9.3)는 `9bef702`로 main에 병합했다. 2차 라운드에서는 리뷰의 **권장·사소 항목 전부**와 1차에서 남긴 결정 두 건을 처리한다. 요구사항 ID는 `Q-<리뷰 섹션>` 형식이다(예: Q-6.1-5 = 리뷰 6.1-5). + +## 공통 완료 기준 (2차) + +1차 공통 기준과 같다. 여기에 두 가지를 더한다. +- **동작을 바꾸지 않는 정리(파일 분리, 중복 합치기)**: 새 RED 테스트 대신 기존 테스트가 안전망이다. 해당 경로에 테스트가 없으면 현재 동작을 고정하는 테스트(characterization)를 먼저 추가한다. +- **번들**: 정리가 끝난 뒤 `check:optional-recipes`가 통과해야 한다. 예산은 올리지 않는다(D-11). + +## 요구사항 + +### browser-transfer +- Q-6.1-5 worker 하나가 실패하면 transfer 단위 abort로 나머지 worker를 즉시 멈춘다. +- Q-6.1-6 해석할 수 없는 checkpoint 행이 있어도 abort는 그 행을 지우고 ORPHANED로 보고한다. +- Q-6.1-7 PRIMARY_REQUIRED probe를 쓰는 preset은 fit이 cover/contain/fill일 때만 정책을 통과한다(D-12). +- Q-6.1-8 probe의 decode는 EXIF/irot 회전을 적용하지 않는다(`imageOrientation: "none"`). +- Q-6.1-9 presigned HTTP helper를 한 모듈로 합친다. statusFailure recovery를 통일하고, 쓰지 않는 `compensateLateResponse`는 삭제한다. download Content-Length를 엄격하게 파싱하고, runtime attempt는 kernel `createAbortableOperation`을 쓴다. +- Q-6.1-3b part마다 일어나는 방어적 복사 중 겹치는 것(`Uint8Array.from`과 `slice()`)을 하나로 줄인다. +- Q-6.1-10 `resumable-upload-runtime.ts`에서 서버 응답 검증과 의존성 snapshot 래퍼를 별도 모듈로 분리한다. 동작은 바꾸지 않는다. +- Q-6.1-11 vault `register`는 snapshot 값만 읽는다. + +### browser-files / cache-storage / cross-context +- Q-6.2-6 cache 조회 비용: JSON은 chunk를 모아 읽고, 검증된 marker는 메모리에 캐시하고, asset 탐색은 Map으로 한다. +- Q-6.2-7 browser-files의 abort race를 kernel `race`와 compensate로 교체한다. 늦게 도착한 lease와 writable은 닫는다. +- Q-6.2-8 native `cancel`을 한 번이라도 관찰했으면 focus fallback을 끈다. +- Q-6.2-9 host factory가 비활성으로 끝날 때 observe로 보고한다. epoch는 releaseId를 인코딩해서 만든다. +- Q-6.2-10 파일명 자르기를 O(n)으로 바꾸고, 중복 호출을 하나로 줄인다. +- Q-6.2-11 `public-response-cache-adapter.ts`와 `download-delivery-adapter.ts`에서 코덱·검증 모듈을 분리한다. 동작은 바꾸지 않는다. +- Q-6.2-12 `MEDIA_TYPE`/opaque 정규식과 `positiveSafeInteger` 중복을 합치고, `object-url-lease.ts`의 죽은 분기를 지운다. + +### http / browser-rpc / query-cache / auth +- Q-6.3-6 요청 종료 사유 판정을 `terminalOutcomeFor` 하나로 모은다. 백오프 중 scope fence는 scope 종료로 분류된다. +- Q-6.3-7 명령의 최종 effect는 누적 certainty와 합친다. `MAYBE_APPLIED`면 재시도하지 않는다. +- Q-6.3-8 namespace 무효화를 병렬로 실행한다. +- Q-6.3-9 RPC 명령이 전송 뒤 실패하면 `MAYBE_APPLIED`로 보고한다. 재시도 전에 scope를 확인하고, 소비자가 abort한 stream은 정리한다. +- Q-6.3-11 V2 401 복구를 재시도 예산과 분리한다. "롤백 가능 seam" 문서의 잘못된 주장을 고친다(V2와 V3는 wire 형식이 다르다). +- Q-6.3-12 cursor pagination의 누적 직렬화와 `push(...)` 한도 문제를 고친다. 쓰지 않는 `validTransportFailure`를 삭제하고, 따옴표가 닫히지 않은 `W/"` ETag를 거부한다. +- Q-6.3-3b V2도 5xx/408/425의 HTML/빈 바디를 status를 담은 서버 장애로 분류하고 재시도 대상으로 둔다. + +### realtime +- Q-6.4-5 chunk당 item 상한을 넘으면 실패하지 않고 다음 처리로 넘긴다. COMMENT는 상수 객체를 쓴다. +- Q-6.4-6 dedupe는 FIFO로 제거하고, fingerprint는 해시로 저장하고, prune은 `break`한다. 가득 차도 전체 recovery를 하지 않는다. +- Q-6.4-7 재시도 예산은 유효 신호가 있고 `stableOpenMs`가 지났을 때만 초기화한다. +- Q-6.4-8 realtime 내부의 DataSnapshot과 abort/timeout race 헬퍼를 한 벌로 합친다. Retry-After 파싱과 JSON 중복 키 스캐너는 kernel(`src/adapters/platform/`)로 올리고, http retry-policy와 web-push codec도 이를 쓴다. +- Q-6.4-9 반복되는 attempt 정리를 `endAttempt()`로 뽑고, 무시되던 `_recovery` 파라미터를 없앤다. +- Q-6.4-10 probe 버퍼 상한을 현재 버퍼 기준으로 계산한다. +- Q-6.4-11 사소 항목: poll execute가 throw하면 retryable OFFLINE으로 둔다. BOM은 한 번만 제거하고, 이중 encode와 이벤트마다 만드는 TextEncoder를 없애고, 잘못 붙은 JSDoc을 옮긴다. + +### storage +- Q-6.5-6 openObject는 사전 검증에서 manifest만 대조하고, root digest는 스트림 끝에서 확인한다. +- Q-6.5-7 IndexedDB 저장 행 타입·검증기·측정 공식을 `indexeddb-records.ts` 하나로 모은다. 동작은 바꾸지 않는다. +- Q-6.5-8 삭제 후 재생성하면 revision/generation이 다시 시작한다는 점을 port 주석과 문서에 명시한다(D-13). +- Q-6.5-9 보상이 실패해도 put의 원래 실패 코드를 유지하고, recovery만 RECONCILE로 바꾼다. +- Q-6.5-10 kernel: `succeed` 뒤에 온 `fail`이 이기도록 하고, settle된 뒤의 upgrade는 abort한다. + +### service-worker / web-push +- Q-6.6-6b fetch 가로채기를 "same-origin GET, navigate 아님, 해시 파일명 또는 manifest URL"로 넓힌다. previous 캐시 fallback이 옛 빌드 chunk에 실제로 동작해야 한다(1차 T29/T32 후속, 사용자 결정). +- Q-6.6-8 후보 캐시 이름이 active 캐시와 같으면 설치 실패 시 지우지 않는다. +- Q-6.6-9 activate는 오래된 캐시부터 지우고, marker 쓰기 실패가 삭제를 막지 않는다. +- Q-6.6-10b 페이지 쪽 활성화 deadline에 워커 drain 시간과 여유분을 더한다. +- Q-6.6-11 알림 클릭이 거절되면 handoff 데이터 없이 앱 루트를 연다. 조용한 push drop은 트레이드오프를 문서에 명시한다(D-14). +- Q-6.6-12 web-push codec primitive(base64url, OPAQUE_ID, validAuthority, exactRecord)를 한 모듈로 합친다. page controller가 주입받은 document를 쓴다. + +### contracts +- Q-6.7-6 exact-key/스냅샷 구현을 `exact-snapshot.ts` 하나로 모으고 배열 스냅샷을 추가한다. iterator·getter 우회를 막는다. +- Q-6.7-7 검증된 인덱스·레지스트리는 `createReadOnlyRegistry`를 쓰고 row마다 스냅샷해서 얼린다. +- Q-6.7-8 검증기 프로토콜과 `MappingResult`의 기준 모양을 하나로 정하고, 나머지는 호환 alias나 어댑터로 둔다(D-15). +- Q-6.7-9 REST 인증 프로필은 설치된 레지스트리 하나를 기준으로 한다. V2 resolve도 검증된 레지스트리를 쓴다. +- Q-6.7-10 배포 승인은 IPv6 loopback·ULA·link-local, IPv4-mapped, CGNAT, `0.0.0.0/8`, `.internal`/`.local`을 사설 주소로 본다. 로컬 호스트 목록은 한 곳에 둔다. +- Q-6.7-11 레지스트리 조회는 `Object.hasOwn`으로 한다. 목록에 없는 offline 전이는 false를 반환한다. +- Q-6.7-12 release-tokens는 비교하지 않은 값을 통과로 보고하지 않는다. contract-set 중복은 실패 코드로 반환한다. query-keys 정렬은 필요할 때만 한다. dependency-cruiser에 contracts → presentation/bootstrap 금지 규칙을 추가한다. + +### presentation +- Q-6.8-9 디자인시스템 링크(`PageActionBar`, `Breadcrumbs`, `LinkButton`)는 router `Link`로 렌더한다. Pagination은 다른 검색 파라미터를 보존한다. +- Q-6.8-10 로딩·인증필요·404 화면을 하나씩으로 합치고, 세션 액션은 hook 하나로 묶는다. reject 시 멈추던 임시 로딩도 고친다. +- Q-6.8-11 Tooltip: `aria-describedby`를 포커스되는 자식에 붙이고, Escape로 닫는다. +- Q-6.8-12 Pagination은 현재 페이지 주변과 처음·끝만 보여주고(windowing), landmark 중첩을 없앤다. +- Q-6.8-13a 플랫폼 라우트의 `none` 코덱은 모르는 쿼리 파라미터를 거부하지 않고 무시한다(D-16). +- Q-6.8-13b 폼 제출은 비동기 검증 중에도 두 번 일어나지 않는다. 저장 직후 이동할 때 dirty guard가 뜨지 않는다. +- Q-6.8-13c 기본 fallback 문구는 현재 로케일을 따른다. SearchField를 지우면 입력으로 포커스를 돌려준다. +- Q-6.8-13d `theme.css`를 여러 파일로 나눈다. 빌드 결과 CSS 바이트가 달라지지 않아야 한다. + +### application / features / bootstrap / platform (+ telemetry adapter) +- Q-6.9-4 텔레메트리 전송 계층을 하나로 합친다(rate limit, credentials `omit`, `pagehide` flush, dispose abort). best-effort fetch에 타임아웃을 둔다(6.3-10 포함). +- Q-6.9-5 킬스위치로 끈 feature는 `features.get()`이 API를 돌려주지 않는다. +- Q-6.9-6 adapter contribution의 featureId가 중복되거나 소속 module과 다르면 throw한다. +- Q-6.9-7 execution context interaction에 완료/정리 API를 두어 부모 signal listener가 남지 않게 한다. +- Q-6.9-8 부트 중에 정적 boot shell(로딩 표시, `aria-busy`)을 보여준다. +- Q-6.9-9 chunk와 boot의 "한 번만 reload" 가드를 공용 guard 하나로 합친다. +- Q-6.9-10 검증을 통과한 config 값만 safe 에러에 싣는다. +- Q-6.9-11 텔레메트리 버퍼는 필요한 공간이 확보될 때만 낮은 severity를 지운다. 주석을 코드와 맞춘다. +- Q-6.9-12 re-export만 하는 `reference-feature-runtime.tsx`를 삭제한다. CI 전용 정책(`promotion-readiness`, `performance-budgets`)은 src 소비자가 없으면 `scripts/`로 옮긴다. 메시지 로케일은 하드코딩하지 않고 카탈로그에서 도출한다. + +### 통합 +- Q-B 번들 예산: 모든 레인을 병합한 뒤 `check:optional-recipes`를 통과시킨다. 필요하면 해당 번들 코드를 줄인다(D-11). + +## 결정 (2차) + +| ID | 결정 | +|---|---| +| D-11 | 번들 예산은 올리지 않는다. 코드를 줄여 맞춘다(사용자 결정). | +| D-12 | PRIMARY_REQUIRED는 fit cover/contain/fill만 허용한다. 비율을 유지하는 fit은 probe를 쓰지 않는 preset에서만 허용한다. | +| D-13 | 삭제 뒤 revision 재시작(ABA)은 스키마를 바꾸지 않고 문서로 계약을 명시한다. tombstone 도입은 저장 스키마 변경이라 범위 밖이다. | +| D-14 | 클릭 실패 시 앱 루트를 연다. push drop은 설계 의도로 두고 문서에 명시한다. | +| D-15 | `external-contract-runtime`의 모양을 기준으로 삼는다. 다른 쪽은 호환 alias나 어댑터로 유지한다(공개 타입을 삭제하지 않음). | +| D-16 | 플랫폼 라우트의 모르는 쿼리 파라미터는 무시한다(strip). URL은 건드리지 않는다. | + +--- + +# 3차 라운드: 남은 문제 8건 + +2차 뒤에 남은 문제 8건을 처리한다(사용자 결정 2026-09-24). ID는 `R3-n`이다. + +- R3-1 HTTP V2: 408/425 응답을 안전하거나 멱등인 요청에 한해 재시도한다. `client.ts`의 Retry-After 파싱은 kernel `platform/retry-after.ts`를 쓴다. +- R3-2 업로드 fetch transport의 Retry-After 파싱도 kernel을 쓴다. file-transfer 번들은 동작을 바꾸지 않는 축소로 예산 대비 여유를 546B(1%) 이상 확보한다. 예산은 바꾸지 않는다. +- R3-3 세션 subject: demo 어댑터가 subject를 제공해서, 같은 사용자의 인증 상태 알림(토큰 갱신 등)은 캐시를 비우지 않는다. subject를 주지 않는 외부 owner는 fail-closed로 동작하고, 그 사실과 `readSubject` 구현 방법을 문서에 적는다. +- R3-4 꺼 둔(`enabled:false`) 쿼리는 `idle` 상태로 표시한다. loading이나 empty가 아니다. `AsyncSurface`는 idle에서 로딩이나 빈 상태 문구를 보여주지 않는다. +- R3-5 SSE 파서는 디코딩 전 바이트 단위로 줄 경계를 찾는다. 멀티바이트 입력에서도 원래 파서 대비 10배 이상 빨라진다(수동 벤치로 측정). +- R3-6 실제 브라우저 검증: 모바일 드로어 이동 후 포커스, bind하지 않은 picker 호출, 서비스 워커 두 빌드 간 업데이트와 옛 chunk의 이전 캐시 fallback, `application/javascript`와 gzip 응답의 static 설치, 실제 Cache API의 `Vary: Accept-Encoding`을 Playwright 스펙으로 확인한다. 여러 탭 OPFS 경합은 결정적으로 재현할 수 있으면 넣고, 없으면 그 이유를 기록한다. +- R3-7 WebKit: 시스템 라이브러리를 설치한 뒤 Playwright 스위트 전체를 WebKit으로 돌린다(Safari 청크 오류 메시지 포함). +- R3-8 원격 반영: 3차가 끝나면 브랜치를 push하고 Gitea PR을 만든다(사용자 결정). diff --git a/config/hosting/cache-policy.json b/config/hosting/cache-policy.json index 45b79bff..1bf46db8 100644 --- a/config/hosting/cache-policy.json +++ b/config/hosting/cache-policy.json @@ -27,9 +27,6 @@ }, "sourceMap": { "public": false - }, - "serviceWorker": { - "enabled": false } } } diff --git a/config/testing/risk-coverage.json b/config/testing/risk-coverage.json index 11cbb039..f3b5eb7b 100644 --- a/config/testing/risk-coverage.json +++ b/config/testing/risk-coverage.json @@ -119,26 +119,6 @@ "branches": 75 } }, - { - "path": "src/application/policies/performance-budgets.ts", - "owner": "application-policy", - "minimum": { - "lines": 80, - "statements": 80, - "functions": 80, - "branches": 40 - } - }, - { - "path": "src/application/policies/promotion-readiness.ts", - "owner": "release-runtime", - "minimum": { - "lines": 95, - "statements": 95, - "functions": 95, - "branches": 95 - } - }, { "path": "src/application/use-cases/decide-chunk-recovery.ts", "owner": "application-runtime", @@ -212,8 +192,6 @@ "src/adapters/telemetry/best-effort-telemetry.ts", "src/application/create-application.ts", "src/contracts/compatibility.ts", - "src/application/policies/performance-budgets.ts", - "src/application/policies/promotion-readiness.ts", "src/application/use-cases/decide-chunk-recovery.ts", "src/bootstrap/load-release-manifest.ts", "src/bootstrap/read-bounded-boot-json.ts", diff --git a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md index cd0c5d76..a7bec984 100644 --- a/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md +++ b/docs/architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md @@ -2604,7 +2604,7 @@ export const DEFAULT_REALTIME_RECONNECT_POLICY = Object.freeze({ - remaining episode budget 초과 hint: reconnect 종료; - attempts/exhausted: `DEGRADED`, explicit recovery action; - automatic new episode cooldown: 300,000ms; -- valid event/heartbeat 또는 60s stable open 후 attempt counter reset; +- valid event/heartbeat를 받고 60s stable open도 지난 뒤에만 attempt counter reset; - offline state에서는 timer 대신 `online` signal을 기다림. ### 14.4 error classification diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index e3e787b5..8389839f 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -525,6 +525,14 @@ recipe의 feature-facing `StoredRecord` view model과 혼동하지 않는다. `writtenAtEpochMs`, synchronization, `measuredBytes`, `eligibleAtEpochMs`는 record envelope에 중복 저장하지 않고 `retentionStore` sidecar에 둔다. +revision은 살아 있는 record 하나 안에서만 순서를 매긴다(D-13). `remove`는 행을 +tombstone 없이 지우므로 같은 key를 다시 만들면 revision이 1부터 다시 시작한다. +그래서 `(key, revision)`은 key의 전체 수명에서 유일하지 않다. 삭제 전에 +revision N을 읽은 writer는 재생성된 record가 N에 도달하면 `expectedRevision: N` +CAS로 그 record를 덮어쓸 수 있다. 이 구분이 필요한 호출자는 revision과 함께 +자기가 소유한 값(server version, payload 안의 ID)을 비교한다. tombstone으로 +번호를 이어 가는 방식은 저장 스키마 변경이라 이 템플릿 범위 밖이다. + - structured clone 성공을 업무 schema 검증으로 간주하지 않는다. - 모든 read는 `unknown`에서 runtime codec으로 envelope와 payload version을 검증한 뒤 domain value로 mapping한다. @@ -752,7 +760,9 @@ CLEANED -> journal 제거 - journal row와 budget reservation은 physical cleanup effect가 `CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash, malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를 - 그대로 남기고 `OBJECT_RECONCILE`로 반환한다. + 그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면 + `QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다 + (Q-6.5-9). journal rollback이 실패해도 같다. - coordinator가 `abortPreparedPut()` 하나만 소유한다. worker client는 prepare 실패 시 별도의 fire-and-forget abort를 발행하지 않는다. 중복 보상은 아직 남아 있어야 할 journal row를 조기에 지우는 경로였다. @@ -771,6 +781,11 @@ CLEANED -> journal 제거 `STORAGE_EVICTED`; reconstructable만 rehydrate한다. - delete는 logical row tombstone을 먼저 commit해 신규 open을 막고 physical bytes를 나중에 정리한다. +- delete가 끝나면 logical row가 없어지므로 같은 object ID의 다음 put은 + generation 1부터 다시 시작한다(D-13). 삭제 전에 기억한 generation이나 + `expectedGeneration`은 다른 객체와 일치할 수 있다. `(objectId, generation)`을 + 객체 수명 전체의 식별자로 쓰지 않고, 필요하면 integrity root digest를 함께 + 비교한다. - operation ID로 replay를 deduplicate한다. `Web Locks`를 쓰면 고정된 origin mutation lock과 AbortSignal/timeout을 사용한다. diff --git a/docs/architecture/presigned-transfer-and-image-cdn.md b/docs/architecture/presigned-transfer-and-image-cdn.md index 3a96f604..2a07e968 100644 --- a/docs/architecture/presigned-transfer-and-image-cdn.md +++ b/docs/architecture/presigned-transfer-and-image-cdn.md @@ -360,7 +360,10 @@ resume through upload() 정한 `schemaVersion: 2`가 필요하다. 기존 schema에 필드를 몰래 추가하지 않는다. 현재 checkpoint store도 single-key `read/CAS/remove`와 account partition 전체 -삭제만 제공한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local +삭제만 제공한다. 예외로 읽을 수 없는 행(손상, 또는 이 빌드가 모르는 +`schemaVersion`)은 명시적 `abort()`가 `removeUnreadable`로 지우고 `ORPHANED`로 +보고한다. 그 행에서는 session을 알 수 없으므로 server session은 만료에 맡긴다. +`upload()`는 같은 행에서 계속 `CORRUPT_DATA`로 fail-closed한다. abandoned upload가 같은 `uploadKey`로 다시 열리지 않으면 local checkpoint를 retention 기준으로 자동 발견·정리하지 못한다. 향후 admin lifecycle은 다음을 제공한다. @@ -545,6 +548,9 @@ DOM, persisted state, telemetry 또는 query cache에 장기 보관하지 않는 private delivery는 `PRIMARY_REQUIRED` browser probe가 필수이며 이를 `NONE`으로 낮출 수 없다. probe는 `credentials: omit`, redirect 금지, exact response URL과 `Cache-Control: no-store`를 실제 response에서 확인한다. +probe는 decode 크기가 primary 후보의 pixel 크기와 정확히 같아야 통과하므로 +`PRIMARY_REQUIRED` preset의 `fit`은 `cover`/`contain`/`fill`만 허용한다(D-12). +원본 비율을 유지하는 `inside`/`outside`는 probe를 쓰지 않는 preset에서만 쓴다. 실제 ``는 same-origin일 때 cookie를 보낼 수 있으므로 registry는 CDN origin이 composition의 application origin과 같으면 생성 단계에서 거절한다. private CDN 응답은 cookie나 ambient authorization에 diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index 27c735fb..fc581c94 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -618,7 +618,8 @@ stream + epoch별 `lastAppliedSequence`를 기준으로 처리한다. | `sequence == lastApplied + 1` | 순차 적용 | | `sequence > lastApplied + 1` | gap; delta 적용 중지, `RESYNC_REQUIRED` | | unknown `streamEpoch` | old/new epoch를 섞지 않고 registered snapshot 또는 session rebuild | -| dedupe/queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery | +| dedupe window 가득 참 | 가장 오래된 항목부터 제거(FIFO)하고 계속 적용. 창에서 밀려난 재전송은 `sequence <= lastApplied`로 drop | +| queue ceiling 초과 | 임의 eviction 후 계속 적용하지 않고 registered recovery | | captured old runtime generation | late callback safe drop + aggregate diagnostic | | current connection의 `scopeBinding` mismatch | effect/sequence/cursor 0, freshness `UNKNOWN`, close + session revalidation + registered recovery | @@ -763,8 +764,9 @@ effectiveDelay = max(localDelay, validServerNotBefore) bound로 취급한다. `effectiveDelay`가 implementation max delay나 남은 elapsed budget을 넘으면 낮춰 clamp하지 않고 reconnect/poll을 종료해 `DEGRADED`/`STALE`로 전환한다. -- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. stable-open - window 또는 valid heartbeat/event 뒤에만 reset한다. +- connection이 잠깐 열렸다는 이유로 attempt를 0으로 만들지 않는다. valid + heartbeat/event를 받았고 stable-open window도 지났을 때만 reset한다(둘 중 + 하나만으로는 reset하지 않는다). - stream reconnect는 realtime recovery coordinator, credential recovery는 session owner, Poll attempt 사이 cadence는 poll coordinator가 각각 소유한다. Poll-bound REST transport retry와 Query retry는 끈다. 같은 logical recovery의 @@ -1411,6 +1413,20 @@ Service Worker는 언제든 종료될 수 있다. in-memory cursor, queue, auth timer를 authority로 사용하지 않는다. `waitUntil`도 무제한 lifetime을 보장하지 않으므로 large fetch, retry loop, data migration을 넣지 않는다. +**조용한 drop은 설계 의도다(D-14).** 검증에 실패한 push(EXPIRED, +RELEASE_MISMATCH, association mismatch, fence 읽기 실패, handler deadline 초과, +malformed/unknown)는 알림을 띄우지 않고 끝난다. 계정 정보가 없는 generic +알림으로 대신 띄우지 않는 이유는 logout·계정 전환 뒤에 도착한 push가 어떤 +형태로든 사용자에게 보이면 안 되기 때문이다. 대가는 두 가지다. + +- Chrome은 `userVisibleOnly` push가 알림 없이 끝나면 "This site has been updated + in the background" 같은 기본 알림을 대신 띄울 수 있다. +- Safari(WebKit)는 알림 없는 push가 반복되면 구독을 취소할 수 있다. + +그래서 drop은 드물어야 한다. backend는 ACTIVE association에만 보내고, 짧은 +server TTL을 쓰고, release를 바꾼 직후에는 이전 release epoch로 보내지 않는다. +drop은 `web_push_hint_processed`의 `FAILED` + reason으로 관측한다. + ### 8.5 Notification content와 click - title/body/icon/action은 closed notification registry가 만든다. @@ -1438,8 +1454,14 @@ type NotificationClickDataV1 = Readonly<{ worker가 종료·재시작된 뒤에도 click을 처리할 수 있도록 이 bounded, non-sensitive envelope만 `NotificationOptions.data`에 넣는다. click handler는 codec/size/expiry, -current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch는 -route를 열지 않고 notification을 닫는다. 이미 표시된 notification은 logout 뒤 +current local `ACTIVE` fence와 release epoch를 다시 검증한다. unknown/mismatch +(만료, fence·release 불일치, fence 읽기 실패, 모르는 route)는 notification을 닫고 +요청한 route 대신 **앱 루트(`/`)를 handoff 데이터 없이 연다**(D-14). +사용자의 탭이 아무 반응 없이 사라지지 않게 하되, 거절된 click의 route와 +notification 정보는 페이지로 넘기지 않는다. 결과는 여전히 실패로 보고하고 +(`web_push_click_dispatched` `FAILED` + reason, `nativeEffect`는 루트 창의 +확실성), 브라우저가 창 열기를 거절한 native 실패나 deadline/abort 뒤에는 루트를 +다시 시도하지 않는다. 이미 표시된 notification은 logout 뒤 OS notification center에 남을 수 있으므로 copy는 항상 account-neutral하고 민감하지 않아야 하며, `getNotifications()` cleanup 성공을 privacy 보장으로 과장하지 않는다. diff --git a/docs/architecture/starter-experience.md b/docs/architecture/starter-experience.md index fb548969..ab757891 100644 --- a/docs/architecture/starter-experience.md +++ b/docs/architecture/starter-experience.md @@ -53,6 +53,20 @@ An external owner implements `readState`, `subscribe`, `beginSignIn`, `signOut`, `attachCredential`, `recoverSession`, and `notifyUnauthenticated`. It owns token acquisition and storage. +The owner may also implement `readSubject()`. The server-state cache is cleared +only when the session state or the subject changes, so a token refresh for the +same user keeps cached data. `readSubject()` must return: + +- an opaque, non-empty string that stays the same for one user across token + refreshes and differs between users, such as a hashed account id +- `null` when nobody is signed in +- never an access token, refresh token, or any other credential + +Without `readSubject()` (or when it returns `null` or `""` while +authenticated), the runtime cannot tell a refresh from an account switch, so +every notification from an authenticated owner clears server state. This is the +safe default. The `demo` adapter reports one fixed demo user as its subject. + ## Extending the starter The steps below describe the current extension path. New platform work should follow diff --git a/docs/operations/client-cache-and-storage-recovery.md b/docs/operations/client-cache-and-storage-recovery.md index cd432943..5780b9c5 100644 --- a/docs/operations/client-cache-and-storage-recovery.md +++ b/docs/operations/client-cache-and-storage-recovery.md @@ -31,6 +31,12 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle `allowedResponseHeaderNames`에 `vary`를 포함해야 한다. 아니면 composition이 `TypeError`로 즉시 실패한다. 저장된 variant가 같은 key로 충돌하는 상태를 만들지 않기 위한 cross-field invariant다. +- `allowedResponseHeaderNames`에 `content-type`이 없는 policy도 composition에서 + `TypeError`로 실패한다. activation이 저장된 `content-type`을 다시 검증하기 + 때문이다. +- `Vary: Accept-Encoding`은 policy 없이 항상 허용한다. `Accept-Encoding`은 + script가 만든 Request에 들어가지 않는 금지 헤더라 저장과 조회 요청 모두 이 + 값이 없다. nginx `gzip_vary`와 대부분의 CDN이 이 헤더를 붙인다. ## 1. 변경할 수 없는 복구 원칙 @@ -54,7 +60,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle 2. `cache.operation.failed`와 `storage.operation.failed`의 allowlisted operation/outcome/reason만으로 범위를 좁힌다. 3. runtime status가 `ACTIVE_BROADCAST`, `ACTIVE_STORAGE_FALLBACK`, - `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 확인한다. + `DEGRADED_STORAGE_FALLBACK`, `DEGRADED_LOCAL_ONLY`, `CLOSED` 중 무엇인지 + 확인한다. `DEGRADED_STORAGE_FALLBACK`은 BroadcastChannel open에 실패한 tab이다. + 다른 tab이 broadcast로만 보낸 event를 받지 못한다. 4. 현재 tab의 mutation 성공 후 local namespace가 stale 처리되는지 확인한다. 5. 다른 tab의 오래된 화면이 단순 stale 표시인지, 실제 server authorization 우회인지 분리한다. authorization 우회는 cache incident가 아니라 P1 security @@ -70,7 +78,9 @@ session/account Query lifecycle, strict query policy와 Web Storage v2 lifecycle - `BROADCAST_PUBLISH_FAILED` - `STORAGE_LISTENER_FAILED` - `STORAGE_PUBLISH_FAILED` -- runtime status `DEGRADED_LOCAL_ONLY` +- `INVALID_CACHE_EPOCH`, `SECURE_RANDOM_UNAVAILABLE`(OPEN FAILED): runtime을 + 만들지 못해 이 tab은 cross-tab 무효화 없이 `DEGRADED_LOCAL_ONLY`로 동작한다 +- runtime status `DEGRADED_STORAGE_FALLBACK` 또는 `DEGRADED_LOCAL_ONLY` ### 확인 diff --git a/docs/operations/release-cache-rollback.md b/docs/operations/release-cache-rollback.md index 6dde83c7..8237b3d2 100644 --- a/docs/operations/release-cache-rollback.md +++ b/docs/operations/release-cache-rollback.md @@ -18,7 +18,9 @@ The provider-independent cache defaults are: - HTML: `no-cache` - runtime config and release manifest: `no-store` - public source maps: disabled -- service worker/offline cache: disabled +- service worker/offline cache: disabled, unless the static selection in + `src/features/installed-runtime-capabilities.ts` is `ACTIVE`; then `dist` + holds exactly the selected `service-worker.js` HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared to the declared allowlist; a cache-correct response with a mismatched 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`의 `