diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 00000000..ef12230a --- /dev/null +++ b/SPEC.md @@ -0,0 +1,103 @@ +# 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이면 같은 내용이라 안전하다. | diff --git a/tasks/plan.md b/tasks/plan.md new file mode 100644 index 00000000..5bf885fc --- /dev/null +++ b/tasks/plan.md @@ -0,0 +1,93 @@ +# Implementation Plan: src 리뷰 긴급·필수 항목 수정 + +## Overview + +`SPEC.md`의 요구사항 47개(R-0 + R-1.1 ~ R-9.3)를 작업 50개로 나눠 고친다. R-3.2, R-6.3, R-8.3은 각각 두 작업으로 쪼갰다. 작업마다 실패하는 테스트를 먼저 쓰고, 고치고, 전체 게이트를 돌리고, 커밋 하나를 만든다. 작업 목록과 완료 조건은 `tasks/todo.md`에 있다. + +- 브랜치: `fix/src-review-2026-09-24` +- 기준 커밋: `b04d570` + +## Architecture Decisions + +- 결정 D-1 ~ D-7은 `SPEC.md` "결정" 표를 따른다. +- 공용 로직은 `src/adapters/platform/`(kernel) 또는 `src/contracts/`에 둔다. 새로운 파일 단위 예외 규칙은 만들지 않는다. +- 공개 포트는 추가만 한다. 기존 시그니처는 깨지 않는다. +- 버그를 정상 동작으로 고정한 기존 테스트는 같은 커밋에서 고친다. 해당 테스트: `tests/unit/legacy-and-optional-network-remediation.test.ts:136`, `tests/unit/release-mismatch-recovery.test.ts:64` 부근, `tests/platform/telemetry/telemetry-pipeline.test.ts:93`. + +## 실행 방식 + +1. **Phase 0 (순차):** T01(R-0)을 먼저 끝낸다. 이게 끝나야 모든 작업에서 게이트를 돌릴 수 있다. +2. **Phase 1 (병렬 레인 9개):** 영역별 레인을 독립 git worktree에서 서브에이전트가 진행한다. 각 레인은 `fix/src-review-2026-09-24` HEAD(T01 반영 후)에서 갈라진다. 레인 안의 작업은 todo 순서대로 하나씩 RED → GREEN → 게이트 → 커밋한다. +3. **통합 (순차):** 레인 브랜치를 하나씩 `fix/src-review-2026-09-24`에 rebase·병합한다. 레인마다 병합한 뒤 전체 게이트를 돌린다(체크포인트). +4. **최종 체크포인트:** 전체 게이트, `build`, 깨끗한 체크아웃 재현(`src/.generated` 삭제 후 게이트)을 확인한다. + +| 레인 | 영역 | 작업 | +|---|---|---| +| A | browser-transfer | T02–T05 | +| B | browser-files / cache / cross-context | T06–T10 | +| C | http / query-cache / auth | T11–T16 | +| D | realtime | T17–T20 | +| E | storage | T21–T25 | +| F | service-worker / web-push | T26–T33 | +| G | contracts | T34–T38 | +| H | presentation | T39–T47 | +| I | bootstrap / platform | T48–T50 | + +레인끼리는 파일이 거의 겹치지 않는다. 겹칠 수 있는 곳은 `docs/reviews/adapters/INVENTORY.md`(adapter 파일 추가 시)와 `src/bootstrap/`(H의 T45와 I)이다. 통합 단계에서 해결한다. + +## Task List (요약 — 상세는 tasks/todo.md) + +### Phase 0: 기반 +- [ ] T01 R-0 깨끗한 체크아웃에서 게이트 동작 + +### Checkpoint 0 +- [ ] `src/.generated` 삭제 후 arch/types/lint/unit/component/verify:documentation 통과 + +### Phase 1: 레인 A–I (병렬) +- [ ] 레인 A: T02–T05 +- [ ] 레인 B: T06–T10 +- [ ] 레인 C: T11–T16 (고위험 T12, T13, T15 포함) +- [ ] 레인 D: T17–T20 +- [ ] 레인 E: T21–T25 (고위험 T21, T22, T24, T25 포함) +- [ ] 레인 F: T26–T33 (고위험 T33 포함) +- [ ] 레인 G: T34–T38 (고위험 T37 포함) +- [ ] 레인 H: T39–T47 +- [ ] 레인 I: T48–T50 (고위험 T50 포함) + +### Checkpoint 레인별 (통합할 때마다) +- [ ] check:architecture, check:types:app, check:types:test, lint, test:unit, test:component 통과 +- [ ] adapter 파일을 바꿨으면 check:adapter-inventory 통과 + +### Checkpoint 최종 +- [ ] 위 게이트 + `corepack pnpm build` 통과 +- [ ] 깨끗한 체크아웃 재현 통과 +- [ ] 리뷰 문서의 해당 항목 47개에 해결 커밋을 대응(todo 체크) + +## 고위험 작업 (계획 승인 = 이 작업들의 사전 승인) + +| 작업 | 이유 | 안전장치 | +|---|---|---| +| T12, T13 (R-3.2) | 세션·캐시 fence 동작이 바뀜 | 상태가 실제로 바뀌면 여전히 fence됨을 테스트로 고정 | +| T15 (R-3.4) | 자격증명 헤더 검증 | 기존 정상 토큰 통과 테스트 유지 | +| T21, T22, T24 (R-5.1, R-5.2, R-5.4) | 삭제 경로 | 참조 중 청크와 다른 파티션 행은 절대 지우지 않음을 테스트로 고정 | +| T25 (R-5.5) | 저장 데이터 판독 규칙 | 기존 manifest 객체가 정책 변경 뒤에도 읽힘을 테스트로 고정 | +| T33 (R-6.7) | 푸시 동의 | 크래시 복구(local ACTIVE) 재등록은 유지됨을 테스트로 고정 | +| T37 (R-7.4) | CSRF 규칙 강화 | 설치된 기존 operation이 모두 통과함을 확인 | +| T50 (R-9.3) | 리댁션 | 정상 텔레메트리 값(enum, id)이 가려지지 않음을 테스트로 고정 | + +모두 코드 변경이라 `git revert`로 되돌릴 수 있다. 배포, 데이터 마이그레이션, 비밀값 변경은 없다. + +## Risks and Mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| worktree마다 `node_modules`가 없음 | Med | 레인 시작 시 `corepack pnpm install --frozen-lockfile --prefer-offline` | +| 레인 9개가 동시에 테스트를 돌려 느려짐 | Low | 레인 안에서는 관련 테스트만, 커밋 전에만 전체 unit/component | +| INVENTORY.md 병합 충돌 | Low | 통합 단계에서 수동 병합 후 `check:adapter-inventory` | +| 브라우저에서만 재현되는 항목(T06, T09, T26, T29, T31, T32, T44) | Med | fake로 조건을 재현. 실제 브라우저 확인은 "미검증"으로 최종 보고 | +| T20 성능 요구(10배)는 CI에서 측정하기 불안정 | Low | 정확성 테스트는 자동, 성능은 벤치 스크립트 수동 측정값을 커밋 메시지에 기록 | +| R-0 방식이 pnpm pre/post 훅에 의존하면 환경마다 다름 | Med | 훅에 의존하지 않고 진입점에서 명시적으로 생성 | + +## Open Questions + +- 없음. 방향이 여러 개인 항목은 SPEC.md의 D-1 ~ D-7로 정했다. 승인하면 그대로 진행한다. diff --git a/tasks/todo.md b/tasks/todo.md new file mode 100644 index 00000000..0c5f291f --- /dev/null +++ b/tasks/todo.md @@ -0,0 +1,337 @@ +# Tasks: src 리뷰 긴급·필수 항목 수정 + +각 작업의 문제 설명은 `docs/reviews/2026-09-24-src-full-review.md` 해당 섹션을 본다. 요구사항은 `SPEC.md`, 실행 방식은 `tasks/plan.md`에 있다. + +## 모든 작업에 공통인 검증 + +- [ ] RED: 재현 테스트가 수정 전에 실패한다 +- [ ] GREEN: 해당 테스트 파일 통과 — `node scripts/run-vitest.ts run ` +- [ ] 게이트 통과 — `corepack pnpm check:architecture && corepack pnpm check:types:app && corepack pnpm check:types:test && corepack pnpm lint && corepack pnpm test:unit && corepack pnpm test:component` +- [ ] adapter 파일을 추가하거나 이동했으면 `docs/reviews/adapters/INVENTORY.md`를 갱신하고 `corepack pnpm check:adapter-inventory` 통과 +- [ ] 커밋 1개, 메시지에 R-ID 포함, 해당 작업 파일만 스테이징 + +--- + +## Phase 0 + +### T01 — R-0 깨끗한 체크아웃에서 게이트 동작 (리뷰 6.0) +- 완료 조건: + - [ ] `rm -rf src/.generated` 뒤 `dev`(기동까지), `build`, `check:architecture`, `check:types:app`, `test:unit`, `test:component`, `verify:documentation`이 통과한다 + - [ ] CI(`config/ci/gates.json` → 생성 workflow)도 생성 단계를 거친다. `check:ci-contract` 등 관련 검사가 통과한다 +- 테스트: 스크립트 레벨 검증(위 명령). 필요하면 `tests/scripts/generate-product-feature-index.test.ts`에 보강 +- 파일: `package.json`, `scripts/*`(진입점), `config/ci/gates.json`, 생성 workflow +- 의존: 없음 · 크기: M + +--- + +## 레인 A — browser-transfer + +### T02 — R-1.1 dispose 재시도 가능 (6.1-1) +- 완료 조건: [ ] deadline 초과 뒤 작업이 끝나면 두 번째 `dispose()`가 성공하고 `lifecycle()==="CLOSED"`, checkpoint store가 닫힌다 +- 테스트: `tests/unit/resumable-upload-runtime-teardown.test.ts` +- 파일: `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` +- 의존: T01 · 크기: S + +### T03 — R-1.4 크기 초과는 LIMIT_EXCEEDED (6.1-4) +- 완료 조건: [ ] `maxFileBytes`/`maxPartCount` 초과 upload가 `LIMIT_EXCEEDED`를 반환한다 +- 테스트: `tests/unit/resumable-upload-runtime.test.ts` +- 파일: `resumable-upload-runtime.ts` +- 의존: T01 · 크기: S + +### T04 — R-1.2 opaque ID 문법 단일화 (6.1-2) +- 완료 조건: [ ] `-`/`_`로 시작하는 43자 base64url ID가 session, part 발급, download 발급까지 통과한다 [ ] 정규식 정의는 한 곳 +- 테스트: `tests/unit/presigned-transfer*.test.ts` 또는 `resumable-upload-*` 중 해당 파일 +- 파일: `resumable-upload/checkpoint-schema.ts`, `presigned/presigned-capability-http-provider.ts`, `presigned/presigned-transfer-executor.ts` +- 의존: T01 · 크기: S + +### T05 — R-1.3 동시성 정책 정합 (6.1-3, D-2) +- 완료 조건: [ ] 정책 검증이 `partSize×maxConcurrency×copyFactor > maxInFlightBytes`를 거절한다 [ ] 기본 정책이 검증을 통과한다 [ ] createSession이 실제 worker 수를 요청한다 +- 테스트: `tests/unit/resumable-upload-runtime.test.ts`(기본 정책 사용 케이스) +- 파일: `resumable-upload/runtime-policy.ts`, `resumable-upload-runtime.ts`, 필요 시 `docs/architecture/presigned-transfer-and-image-cdn.md` +- 의존: T01 · 크기: S + +## 레인 B — browser-files / cache-storage / cross-context + +### T06 — R-2.1 BOUNDED_OBJECT_URL open 실패 시 Result 반환 (6.2-1) +- 완료 조건: [ ] presigned source + BOUNDED_OBJECT_URL에서 open 중 abort하면 `deliver()`가 `{ok:false, ABORTED}`로 resolve된다 [ ] 늦게 온 lease가 닫힌다 +- 테스트: `tests/unit/browser-file-download.test.ts` +- 파일: `src/adapters/browser-files/download-delivery-adapter.ts` +- 의존: T01 · 크기: S + +### T07 — R-2.2 watermark를 TTL과 분리 (6.2-2) +- 완료 조건: [ ] 같은 source의 seq 1 → 61초 뒤 seq 2가 `NEXT`로 전달된다 [ ] watermark 메모리는 `sourceCapacity`로만 제한된다 +- 테스트: `tests/unit/cross-tab-invalidation.test.ts` +- 파일: `src/adapters/cross-context-invalidation/browser-cross-context-invalidation.ts` +- 의존: T01 · 크기: S + +### T08 — R-2.3 발행 실패 뒤에도 수신 유지, 수신 불가면 DEGRADED (6.2-3, D-4) +- 완료 조건: [ ] postMessage가 한 번 실패한 탭이 다른 탭의 broadcast를 계속 받는다 [ ] BroadcastChannel을 만들 수 없는 탭의 status가 DEGRADED다 +- 테스트: `tests/unit/cross-tab-invalidation.test.ts`(발행 탭은 정상, 수신 탭이 실패하는 구성) +- 파일: `browser-cross-context-invalidation.ts`, 필요 시 status 타입(`src/application/ports/…`) +- 의존: T07 · 크기: S + +### T09 — R-2.4 picker 함수 bind 제거 (6.2-4) +- 완료 조건: [ ] `this`가 options이면 throw하는 fake picker를 주입해도 picker와 save가 동작한다 +- 테스트: `tests/unit/browser-file-picker.test.ts`, `tests/unit/browser-file-download.test.ts` +- 파일: `src/adapters/browser-files/browser-file-picker.ts`, `download-delivery-adapter.ts` +- 의존: T06 · 크기: S + +### T10 — R-2.5 cache 정책의 Vary/content-type (6.2-5) +- 완료 조건: [ ] 기본 정책으로 `Vary: Accept-Encoding` 응답을 stage하고 activate할 수 있다 [ ] `content-type`이 없는 정책은 `assertPublicCachePolicy`가 거부한다 +- 테스트: `tests/unit/public-response-cache.test.ts` +- 파일: `src/adapters/cache-storage/public-response-cache-adapter.ts`, `public-cache-policy.ts` +- 의존: T01 · 크기: S + +## 레인 C — http / query-cache / auth + +### T11 — R-3.1 경로 값 `.`/`..` 거부 (6.3-1) +- 완료 조건: [ ] V3 bridge가 `PATH_VALUE_INVALID`, V2 request-builder가 `PATH_PARAMETER_INVALID`를 반환한다(`"."`, `".."` 각각) +- 테스트: `tests/unit/http-contract-bridge*.test.ts`(없으면 신규), V2 request-builder 테스트 +- 파일: `src/adapters/http/http-contract-bridge.ts`, `src/adapters/http/request-builder.ts` +- 의존: T01 · 크기: S + +### T12 — R-3.2a scope fence는 상태가 바뀔 때만 (6.3-2) [고위험] +- 완료 조건: [ ] 같은 (상태, 주체) 알림은 fence·abort·cache clear를 일으키지 않는다 [ ] 상태나 주체가 바뀌면 여전히 fence된다 +- 테스트: server-state-scope 런타임 테스트(`tests/unit/…server-state-scope…`) +- 파일: `src/adapters/query-cache/server-state-scope-runtime.ts` +- 의존: T01 · 크기: S + +### T13 — R-3.2b 요청 전 미인증과 서버 401 구분, demo 동일 값 무알림 (6.3-2) [고위험] +- 완료 조건: [ ] V3 요청 전 자격증명 없음은 `onUnauthenticated`를 호출하지 않는다 [ ] 서버 401은 호출한다 [ ] demo `setState`는 같은 값이면 listener를 부르지 않는다 +- 테스트: `tests/unit/http-execution-v3*.test.ts`, `tests/unit/runtime-adapters.test.ts` 또는 auth 어댑터 테스트 +- 파일: `src/adapters/http/http-execution-v3.ts`, `src/adapters/auth/external-session-adapter.ts`, `src/bootstrap/runtime-adapters.ts` +- 의존: T12 · 크기: M + +### T14 — R-3.3 5xx 비정상 바디와 요청 쪽 위반 분류 (6.3-3) +- 완료 조건: [ ] HTML/빈 바디 502/503/504가 status를 담은 서버 장애(재시도 가능)로 끝난다 [ ] 바인딩 결과가 `contact-support`가 아니다 [ ] `FINAL_REQUEST_INVARIANT_FAILED`/`MISSING_IDEMPOTENCY_KEY`가 `ENVELOPE_MISMATCH`로 매핑되지 않는다 +- 테스트: `tests/unit/http-execution-v3.test.ts`, feature-http-binding 테스트 +- 파일: `http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts` +- 의존: T13 · 크기: M + +### T15 — R-3.4 자격증명 헤더 ByteString 검증 (6.3-4) [고위험] +- 완료 조건: [ ] NUL, 비 Latin-1, 제어문자가 든 값이 전송 전에 `CREDENTIAL_HEADER_VALUE_INVALID`가 된다(NETWORK_FAILURE 아님) [ ] 대소문자만 다른 중복 헤더가 거부된다 [ ] 정상 Bearer 토큰은 통과한다 +- 테스트: bridge/V3 테스트, auth 어댑터 테스트 +- 파일: `http-contract-bridge.ts`, `http-execution-v3.ts`, `external-session-adapter.ts` +- 의존: T14 · 크기: M + +### T16 — R-3.5 매퍼 예외를 Result로 (6.3-5) +- 완료 조건: [ ] `mapSuccess`/`mapProblem`이 throw하면 `MAPPING_CONTRACT_VIOLATION` Result가 반환되고 effect가 보존된다 +- 테스트: feature-http-binding 테스트 +- 파일: `feature-http-binding.ts` +- 의존: T14 · 크기: S + +## 레인 D — realtime + +### T17 — R-4.2 hint 없는 retryable 실패도 재연결 (6.4-2) +- 완료 조건: [ ] WS `NETWORK_LOST`/`RESTART`, SSE 502/504(hint 없음)가 재연결된다 [ ] polling도 같다 [ ] `retryable:false`는 여전히 종료된다 +- 테스트: `tests/unit/realtime/realtime-reconnect-coordinator.test.ts` + WS↔reconnect 연결 테스트 신규 +- 파일: `src/adapters/realtime/reconnect-coordinator.ts`, `polling/bounded-poll-coordinator.ts` +- 의존: T01 · 크기: S + +### T18 — R-4.1 DRAINING 중 recovery 차단 (6.4-1) +- 완료 조건: [ ] quiescence를 기다리는 동안 effect가 DRAINING이 되면 recovery가 authority를 호출하지 않고 실패한다 +- 테스트: `tests/unit/realtime/stream-coordinator.test.ts` +- 파일: `src/adapters/realtime/stream-coordinator.ts` +- 의존: T01 · 크기: S + +### T19 — R-4.3 barrier NONE recovery는 계속 진행 (6.4-3) +- 완료 조건: [ ] SNAPSHOT_ONLY + barrier NONE 스트림에서 gap → recovery 뒤 연결이 유지되고 PROTOCOL_MISMATCH가 나지 않는다 +- 테스트: consumer + coordinator 실제 조합 테스트(mock 없이) +- 파일: `src/adapters/realtime/event-consumer.ts`, 필요 시 `stream-coordinator.ts` +- 의존: T18 · 크기: M + +### T20 — R-4.4 SSE 파서 성능 (6.4-4) +- 완료 조건: [ ] 기존 파서 테스트가 모두 통과한다(CRLF, 분할 chunk, BOM 등) [ ] 250KB chunk 벤치에서 10배 이상 빨라진다(수동 측정값을 커밋 메시지에 기록) +- 테스트: `tests/unit/realtime/sse-parser*.test.ts` + 대형 chunk 정확성 케이스 +- 파일: `src/adapters/realtime/sse/sse-parser.ts` +- 의존: T01 · 크기: S + +## 레인 E — storage + +### T21 — R-5.1 orphan 후보 커서 (6.5-1) [고위험] +- 완료 조건: [ ] 참조 중 청크 150개 뒤에 있는 orphan이 reconcile로 지워진다 [ ] 참조 중 청크는 지워지지 않는다 +- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/opfs-byte-store.test.ts` +- 파일: `src/adapters/storage/opfs/opfs-worker-runtime.ts`, `opfs-worker-protocol.ts`, `opfs-worker-client.ts`, `opfs-byte-store-adapter.ts` +- 의존: T01 · 크기: M + +### T22 — R-5.2 dedup 재사용 청크의 grace 보호 (6.5-2) [고위험] +- 완료 조건: [ ] 같은 digest를 다시 쓰면 청크의 mtime이 갱신되어 `listOrphanCandidates`에 나오지 않는다 +- 테스트: `tests/unit/opfs-worker-runtime.test.ts` +- 파일: `opfs-worker-runtime.ts` +- 의존: T21 · 크기: S + +### T23 — R-5.3 lock 대기를 RPC 타임아웃에서 분리 (6.5-3, D-3) +- 완료 조건: [ ] 긴 put이 lock을 잡고 있어도 뒤에 온 put/remove가 60초에 실패하지 않고 lock을 얻은 뒤 진행된다 [ ] lock 대기는 정책값 상한으로 끝난다 +- 테스트: 배타 lease를 쓰는 worker/client 테스트 신규 +- 파일: `opfs-worker-client.ts`, `opfs-worker-runtime.ts`, `opfs-policy.ts` +- 의존: T22 · 크기: M + +### T24 — R-5.4 파티션 purge가 손상 행을 넘어 끝까지 (6.5-4) [고위험] +- 완료 조건: [ ] 손상 record/sidecar/budget이 섞인 파티션에서 LOGOUT/ACCOUNT_DELETION purge가 COMPLETE된다 [ ] 다른 파티션의 행은 남는다 [ ] 손상은 observe로 보고된다 +- 테스트: `tests/unit/indexeddb-runtime.test.ts` +- 파일: `src/adapters/storage/indexeddb/indexeddb-runtime.ts` +- 의존: T01 · 크기: M + +### T25 — R-5.5 prepared-object 검증 단일화 (6.5-5) [고위험] +- 완료 조건: [ ] 4MiB 청크로 저장한 객체를 정책 `chunkSizeBytes=8MiB`인 런타임에서 open, reconcile할 수 있다 [ ] 검증 함수 정의는 한 곳 +- 테스트: `tests/unit/opfs-worker-runtime.test.ts`, `tests/unit/indexeddb-opfs-journal.test.ts` +- 파일: 신규 공용 모듈(`src/adapters/storage/opfs/…`), `opfs-worker-runtime.ts`, `indexeddb-opfs-journal.ts`, `opfs-worker-client.ts`, INVENTORY +- 의존: T23 · 크기: M + +## 레인 F — service-worker / web-push + +### T26 — R-6.1 확정 이후 메시지 처리 (6.6-1) +- 완료 조건: [ ] ACCEPTED 도착 시 `registration.waiting===null`, `active===worker`여도 활성화가 성공한다 [ ] 관련 없는 메시지(SYNC_WAKE_OBSERVED 등)가 활성화를 실패시키지 않는다 +- 테스트: page-controller 테스트 +- 파일: `src/adapters/service-worker/service-worker-page-controller.ts` +- 의존: T01 · 크기: S + +### T27 — R-6.2 drain 짝 맞추기 수정 (6.6-2) +- 완료 조건: [ ] 빌드 N 탭과 N+1 탭이 함께 있어도 활성화가 drain을 끝내고 완료된다 +- 테스트: lifecycle 테스트 + page-controller 테스트 +- 파일: `service-worker-lifecycle.ts`, `service-worker-page-controller.ts` +- 의존: T26 · 크기: S + +### T28 — R-6.3a reloadRequired/updateWaiting 구독 (6.6-3) +- 완료 조건: [ ] host 계약에 구독 API가 추가되고, 다른 탭의 `ACTIVATED_RELOAD_REQUIRED`와 주기 update의 waiting이 구독자에게 전달된다 +- 테스트: page-controller 테스트 +- 파일: `service-worker-page-controller.ts`, `src/contracts/service-worker.ts`, 관련 host 타입 +- 의존: T27 · 크기: M + +### T29 — R-6.3b previous 캐시 fallback (6.6-3, D-7) +- 완료 조건: [ ] current 캐시에 없는 hashed asset을 previous 캐시에서 제공한다 [ ] hashed가 아닌 URL에는 적용되지 않는다 +- 테스트: lifecycle/runtime 테스트 +- 파일: `service-worker-lifecycle.ts`, 필요 시 `service-worker-static-assets.ts` +- 의존: T28 · 크기: S + +### T30 — R-6.4 설치 중 워커를 ACTIVE로 보고하지 않음 (6.6-4) +- 완료 조건: [ ] `installing`만 있는 등록에서 `start()`가 ACTIVE가 아닌 상태를 반환한다 [ ] 설치가 끝나면 올바른 상태로 수렴한다 +- 테스트: page-controller 테스트(`installing` fixture 추가) +- 파일: `service-worker-page-controller.ts` +- 의존: T27 · 크기: S + +### T31 — R-6.5 MIME 동의어와 content-encoding (6.6-5) +- 완료 조건: [ ] `application/javascript` 응답과 `content-encoding: gzip` + 압축 크기 Content-Length 응답이 설치된다 [ ] 바이트와 sha256 검증은 유지된다 +- 테스트: static-assets 테스트 +- 파일: `service-worker-static-assets.ts` +- 의존: T01 · 크기: S + +### T32 — R-6.6 fetch 가로채기 범위 (6.6-6) +- 완료 조건: [ ] navigate, 비 GET, manifest 밖 URL에서는 `respondWith`가 호출되지 않는다 [ ] manifest asset은 캐시에서 제공된다 +- 테스트: service-worker entry/runtime 테스트 +- 파일: `service-worker-entry.ts`, 필요 시 runtime의 `manifestUrls` 노출 +- 의존: T29 · 크기: S + +### T33 — R-6.7 ABSENT 재등록 조건 (6.6-7) [고위험] +- 완료 조건: [ ] fence REVOKED/UNASSOCIATED + native 구독 잔존 + 서버 ABSENT → 재등록하지 않고 native를 해제한다 [ ] local ACTIVE(크래시 복구)면 재등록한다 +- 테스트: `tests/unit/web-push-subscription-adapter.test.ts` +- 파일: `src/adapters/web-push/push-subscription-adapter.ts` +- 의존: T01 · 크기: S + +## 레인 G — contracts + +### T34 — R-7.1 멱등 키 문법 (6.7-1) +- 완료 조건: [ ] 앞뒤 공백, 비 ASCII, 257자 키가 거부된다 [ ] UUID 등 정상 키는 통과한다 [ ] 기존 고정 테스트(`legacy-and-optional-network-remediation.test.ts:136`)를 고친다 +- 테스트: 위 테스트 + mutation-intent 테스트 +- 파일: `src/contracts/mutation-intent.ts` +- 의존: T01 · 크기: S + +### T35 — R-7.2 FEATURE_OVERRIDES 키는 금지어 검사 제외 (6.7-2) +- 완료 조건: [ ] `{"FEATURE_OVERRIDES":{"cookie-consent":"DISABLED"}}`로 부팅 설정 로드가 성공한다 [ ] 최상위나 다른 중첩의 금지 이름은 여전히 거부된다 +- 테스트: runtime-config 테스트 +- 파일: `src/contracts/env.ts` +- 의존: T01 · 크기: S + +### T36 — R-7.3 매니페스트 URL 검증 (6.7-3) +- 완료 조건: [ ] `"/\t/evil.example/m.json"`, 개행 포함, `/a/%2e%2e/b`가 거부된다 [ ] 정상 경로는 통과한다 +- 테스트: `tests/runtime-schema/runtime-config.test.ts` +- 파일: `src/contracts/release-artifacts.ts` +- 의존: T01 · 크기: S + +### T37 — R-7.4 REST V2 COMMAND 메서드 규칙 (6.7-4) [고위험] +- 완료 조건: [ ] `{semantics:"COMMAND", method:"GET"}`와 모르는 `semantics`/`replayPolicy` 값이 거부된다 [ ] 설치된 기존 operation은 모두 통과한다 +- 테스트: api-operations 테스트 +- 파일: `src/contracts/api-operations.ts` +- 의존: T01 · 크기: S + +### T38 — R-7.5 operationId 문법 단일화 (6.7-5) +- 완료 조건: [ ] `getUser` 같은 V3 operationId의 `api.request.failed` 이벤트가 검증을 통과해 드롭되지 않는다 [ ] 정의는 contracts 한 곳 [ ] diagnostics도 같은 규칙 +- 테스트: telemetry/diagnostics 계약 테스트 +- 파일: `src/contracts/telemetry.ts`, `diagnostics.ts`, `external-contract-runtime.ts`, 공용 정의 위치 +- 의존: T01 · 크기: M + +## 레인 H — presentation + +### T39 — R-8.1 청크 복구 상태 라우트별 초기화 (6.8-1) +- 완료 조건: [ ] 라우트 A에서 청크 실패 → 라우트 B로 이동하면 B가 정상 렌더된다 [ ] 실패 화면에 한 번 새로고침 버튼이 있다 +- 테스트: `tests/component/chunk-recovery-boundary.test.tsx` 또는 라우터 컴포넌트 테스트 +- 파일: `src/presentation/routes/app-router.tsx`, `src/presentation/boundaries/chunk-recovery-boundary.tsx` +- 의존: T01 · 크기: S + +### T40 — R-8.2 WebKit/Vite 청크 실패 인식 (6.8-2) +- 완료 조건: [ ] 두 메시지가 `isChunkLoadFailure`에서 true다 [ ] `vite:preloadError`가 복구 경로로 이어진다 +- 테스트: chunk-recovery 테스트 +- 파일: `chunk-recovery-boundary.tsx`, 필요 시 `src/bootstrap/main.tsx` +- 의존: T39 · 크기: S + +### T41 — R-8.8 enabled:false는 로딩 아님 (6.8-8) +- 완료 조건: [ ] disabled 쿼리의 `isInitialLoading`이 false다 [ ] 실제 첫 로딩은 여전히 true다 +- 테스트: `tests/component/application-query*.test.tsx` +- 파일: `src/presentation/adapters/query/application-query.ts` +- 의존: T01 · 크기: XS + +### T42 — R-8.4 로케일 변경 시 포커스·스크롤·재보고 없음 (6.8-4) +- 완료 조건: [ ] 언어를 바꾸면 제목만 갱신되고 focus, scrollTo, reportRouteChanged가 호출되지 않는다 +- 테스트: 라우터 컴포넌트 테스트 +- 파일: `app-router.tsx` +- 의존: T39 · 크기: S + +### T43 — R-8.5 모든 분기에서 RouteLifecycle (6.8-5) +- 완료 조건: [ ] 인증필요, 잘못된 주소, 비활성 기능 화면에서 title, main focus, route 텔레메트리가 동작한다 +- 테스트: 라우터 컴포넌트 테스트 +- 파일: `app-router.tsx` +- 의존: T42 · 크기: S + +### T44 — R-8.6 드로어 이동 시 포커스 (6.8-6) +- 완료 조건: [ ] 드로어 링크로 이동하면 activeElement가 새 페이지 h1 또는 main이다 [ ] Escape로 닫으면 여전히 메뉴 버튼으로 돌아간다 +- 테스트: app-shell 컴포넌트 테스트 +- 파일: `src/presentation/layouts/app-shell.tsx`, 필요 시 `design-system/primitives/core.tsx` +- 의존: T43 · 크기: S + +### T45 — R-8.3a 로케일 저장 (6.8-3, D-5) +- 완료 조건: [ ] 로케일 선택이 preferences에 저장되고 새 mount 때 저장값으로 시작한다 +- 테스트: `tests/component/locale-platform.test.tsx` +- 파일: `src/presentation/i18n/locale-provider.tsx`, `src/application/ports/in/application-api.ts`, `src/application/create-application.ts`, preferences 저장 경로 +- 의존: T42 · 크기: M + +### T46 — R-8.3b provider를 scope fence 밖으로, router dispose (6.8-3) +- 완료 조건: [ ] scope가 FENCED → READY가 되어도 LocaleProvider/ThemeProvider 상태가 유지된다 [ ] AppRouter unmount 시 `router.dispose()`가 호출된다 +- 테스트: 컴포넌트 테스트(세션 전환) +- 파일: `app-router.tsx`, `src/presentation/adapters/query/server-state-scope-provider.tsx`, provider 조립 위치(bootstrap/runtime-application 등) +- 의존: T45 · 크기: M + +### T47 — R-8.7 context 게이트웨이 key와 청크 복구 (6.8-7) +- 완료 조건: [ ] context가 바뀌면 이전 routes로 매칭하지 않는다(NOT_FOUND 텔레메트리 없음) [ ] routes 모듈 로드의 청크 실패가 `recoverChunk`를 거친다 +- 테스트: 라우터 컴포넌트 테스트(가짜 context 2개) +- 파일: `app-router.tsx` +- 의존: T46 · 크기: S + +## 레인 I — bootstrap / platform + +### T48 — R-9.1 부트 reload 세션당 1회 (6.9-1) +- 완료 조건: [ ] 키가 A→B→A로 바뀌어도 TTL 안에서는 두 번째부터 `show-failure`다 [ ] 기존 연속 reload 기대 테스트를 고친다 +- 테스트: `tests/unit/release-mismatch-recovery.test.ts`, `tests/release/mixed-replica.test.ts` +- 파일: `src/platform/release/release-mismatch-recovery.ts` +- 의존: T01 · 크기: S + +### T49 — R-9.2 중복 발생 횟수 전달 (6.9-2, D-6) +- 완료 조건: [ ] 기본 스케줄(queueMicrotask)에서 같은 이벤트 1000회 → 수집기가 받는 occurrences 합계가 1000이다 +- 테스트: `tests/platform/telemetry/telemetry-pipeline.test.ts`(자동 flush 켠 케이스 추가, 기존 기대값 정리) +- 파일: `src/platform/telemetry/telemetry-pipeline.ts` +- 의존: T01 · 크기: M + +### T50 — R-9.3 리댁션 보강 (6.9-3) [고위험] +- 완료 조건: [ ] 중간의 `Authorization: Bearer …`, URL `?access_token=…`, 이메일, `pwd`/`pass`/`auth`/`otp`/`pin` 키가 가려진다 [ ] 정상 enum/id 값은 가려지지 않는다 +- 테스트: redact-telemetry 테스트 +- 파일: `src/platform/telemetry/redact-telemetry.ts` +- 의존: T01 · 크기: S