feat: 공식 문서 근거자료, 브랜치 기능 문서 작성

raw/branch-notes/feature-frontend-binary-file-io-store-contract.md

@@ -52,7 +52,7 @@ status_label: in-progress
 | Decision Ref | Project Summary | Branch Application | Source |
 |---|---|---|---|
 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1` | 신규 runtime capability 6종은 FE-REG-CAPABILITY flag로 default OFF이며 활성화는 owner·gate·runbook을 동반한다 | `CAP_FE_BINARY_IO` 를 이 branch 가 소유하고 default OFF 로 유지한다 | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] |
-| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-BINARY-STORE-001@1` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 service worker 호스팅 response cache 전용이다 | `BlobStorePort` adapter 의 backend 선택 순서에 적용한다 | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] |
+| `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-BINARY-STORE-001@1` | 로컬 바이너리 backend는 IndexedDB를 default로 하고 OPFS는 대용량 순차 write에 opt-in, Cache Storage는 정책상 service worker 호스팅 response cache 전용으로 제한한다 | `BlobStorePort` adapter 의 backend 선택 순서에 적용한다 | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] |
 | `DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-REGISTRY-001@1` | route, API operation, env, storage, error, query, telemetry, release token, capability를 9개 registry로 관리한다 | `FE-REG-STORAGE` 신규 4행(`UPLOAD_PART_STATE`·`TRANSFER_OBJECT_BUFFER`·`QUERY_CACHE_SNAPSHOT`·`SW_RESPONSE_CACHE`)의 `payloadClass`·`evictionOrder` 를 소비한다 | [[raw/project-notes/ca-skeleton-frontend-operational-contract]] |
 
 <!-- section-id: branch-local-decisions -->
@@ -181,7 +181,7 @@ status_label: in-progress
 | D3 | `<input type=file>` + `<a download>` 를 기준선, File System Access picker 를 progressive enhancement | 항상. 대상 브라우저 매트릭스가 picker 전량 지원으로 확정되면(`FE-Q-007`) 기준선을 picker 로 올릴 수 있음 | `mdn-file-system-access-opfs.md#C1`(not Baseline), `#C2`(transient activation), `#C4`(secure context) | `official-reference` | 두 경로의 UX 가 달라진다 — picker 는 저장 위치 선택, fallback 은 브라우저 다운로드 폴더 고정 |
 | D4 | 취소와 "위험 파일 거부"를 구분하지 않고 `FILE_PICKER_DISMISSED` 로 정규화 | 항상. 브라우저가 두 사유를 구분 가능한 신호로 분리하면 재검토 | `mdn-file-system-access-opfs.md#C3`(둘 다 같은 `AbortError`) | `official-reference` | 거부 사유를 사용자에게 설명할 수 없다. "선택된 파일이 없습니다" 수준의 중립 문구만 가능 |
 | D5 | OPFS 는 비동기 API 기본, 동기 handle 이 필요할 때만 `WorkerTaskPort` 경유 | 대용량 순차 write 로 메인 스레드 블로킹이 측정될 때만 동기 경로. 그 전에는 비동기 | `mdn-file-system-access-opfs.md#C5`(동기 API 는 worker 전용), `#C6`(속도 우위의 비교 대상은 File System Access API) | `official-reference` | worker 경유는 `CAP_FE_BACKGROUND_EXEC` 활성을 전제한다 — 두 capability 가 얽힌다 |
-| D6 | `evictionOrder` 는 애플리케이션 주도 정리 순서로만 유효 | 항상. 브라우저가 per-key eviction 힌트 API 를 제공하면 재검토 | `mdn-storage-quotas-eviction-persistence.md#C1`(origin 전량 삭제), `#C3`(LRU origin 단위) | `official-reference` | hub §5.5 의 필드 설명이 이 경계를 담고 있지 않다 — §Audit & Findings `EVICTION_SCOPE_DRIFT` |
+| D6 | `evictionOrder` 는 애플리케이션 주도 정리 순서로만 유효 | 항상. 브라우저가 per-key eviction 힌트 API 를 제공하면 재검토 | `mdn-storage-quotas-eviction-persistence.md#C1`(origin 전량 삭제), `#C3`(LRU origin 단위) | `official-reference` | 없음 — 2026-07-28 hub §5.5 필드 Rule 이 이 경계를 담도록 정정됐다(§Audit & Findings `EVICTION_SCOPE_DRIFT` `resolved`) |
 | D7 | correctness 값 사용 시 `persist()` 1회 요청 + 미허가를 표면화 | correctness 값(`UPLOAD_PART_STATE` 등)을 쓰는 capability 가 활성일 때. 순수 캐시만 쓰면 요청하지 않음 | `mdn-storage-quotas-eviction-persistence.md#C4`(persist 는 LRU 제외), `#C5`(허가는 브라우저 재량), `#C7`(Safari 7일 규칙) | `official-reference` | persist 미허가 + Safari ITP 조합이면 재개 가능 전송이 7일 만에 무효가 된다. 제품이 이를 수용 가능한지 미확인 |
 
 <!-- section-id: implementation -->
@@ -284,14 +284,14 @@ status_label: in-progress
 
 ## Audit & Findings
 
-> `/branch-spec` 2026-07-28 조사에서 발견한 **상위 계약의 사실 오류**. 이 branch 가 자동 수정하지 않고 정합 권고만 남긴다 — `FE-D027` 과 `FE-REG-STORAGE` 는 hub 소유이며 변경은 hub §3.3 프로토콜을 따라야 한다.
+> `/branch-spec` 2026-07-28 조사에서 발견한 **상위 계약의 사실 오류**. `FE-D027` 과 `FE-REG-STORAGE` 는 hub 소유이므로 이 branch 는 권고만 냈고, 실제 반영은 사용자 승인 후 hub §3.3 프로토콜(둘 다 `compatibility_impact: none`, revision 유지)로 수행했다.
 
-| Finding ID | 대상 | 현재 서술 | 조사 결과 | 권고 |
-|---|---|---|---|---|
-| `EVICTION_SCOPE_DRIFT` | hub §5.5 `FE-REG-STORAGE.evictionOrder` | "quota 압박 시 제거 순서(정수, 낮을수록 먼저)" — 주체가 명시되지 않아 브라우저 eviction 에도 적용되는 것처럼 읽힌다 | `mdn-storage-quotas-eviction-persistence#C1`: "When an origin's data is evicted by the browser, **all of its data, not parts of it**, is deleted at the same time." `#C3`: LRU 는 **origin 단위** | 필드 Rule 에 "**애플리케이션 주도** 정리 순서. 브라우저 eviction 은 origin 전량 삭제이므로 이 순서가 적용되지 않는다" 를 추가 |
-| `CACHE_STORAGE_CONSTRAINT_DRIFT` | hub `FE-D027` / `DEC-…-BINARY-STORE-001@1` | "Cache Storage는 service worker 호스팅 response cache 전용이다" — 기술 제약처럼 읽힌다 | `mdn-object-url-cache-storage#C3`: "you're not limited to only using it with service workers", `Window.caches` 로 접근 가능 | 결정 자체는 유효(정책 선택). §5.5 또는 `FE-D027` rationale 에 "플랫폼 제약이 아니라 release coherence 를 위한 **정책** 선택" 임을 명시 |
-| `NO_GROUND_TRUTH` | `/branch-spec` §2 ca-tmpl 대조 | 명령은 `/home/donghyeon/workspace/ca-tmpl` 의 registry·코드와 대조하라고 요구 | `ca-tmpl` 은 Gradle/Java **백엔드 전용**(`domain-core`·`adapter-web`·`shared-contract`). `package.json`·`vite.config`·`.jsx` 부재. frontend 구현 repo 는 hub §0.3 대로 미식별 | 이 branch 의 모든 명세는 `planned`. `actually-implemented` 승격은 frontend repo 식별(`FE-Q-001`) 이후 |
-| `CAPABILITY_NAME_COLLISION` | `ca-tmpl/docs/registries/capabilities.yaml` vs hub `FE-REG-CAPABILITY` | 두 registry 가 같은 "capability" 어휘를 쓴다 | ca-tmpl 은 *use case → infrastructure 접근 권한*(`READ_REPOSITORY` 등), hub 는 *브라우저 런타임 기능 flag*(`CAP_FE_BINARY_IO` 등). **다른 개념** | 계약을 상호 참조하지 않는다. 혼동 방지를 위해 frontend 쪽은 `CAP_FE_` prefix 를 유지 |
+| Finding ID | 대상 | 현재 서술 | 조사 결과 | 권고 | 처리 |
+|---|---|---|---|---|---|
+| `EVICTION_SCOPE_DRIFT` | hub §5.5 `FE-REG-STORAGE.evictionOrder` | "quota 압박 시 제거 순서(정수, 낮을수록 먼저)" — 주체가 명시되지 않아 브라우저 eviction 에도 적용되는 것처럼 읽힌다 | `mdn-storage-quotas-eviction-persistence#C1`: "When an origin's data is evicted by the browser, **all of its data, not parts of it**, is deleted at the same time." `#C3`: LRU 는 **origin 단위** | 필드 Rule 에 "**애플리케이션 주도** 정리 순서. 브라우저 eviction 은 origin 전량 삭제이므로 이 순서가 적용되지 않는다" 를 추가 | `resolved` 2026-07-28 — hub §5.5 필드 Rule + 해설 문단 반영, §6.1 개정 기록 등재 |
+| `CACHE_STORAGE_CONSTRAINT_DRIFT` | hub `FE-D027` / `DEC-…-BINARY-STORE-001@1` | "Cache Storage는 service worker 호스팅 response cache 전용이다" — 기술 제약처럼 읽힌다 | `mdn-object-url-cache-storage#C3`: "you're not limited to only using it with service workers", `Window.caches` 로 접근 가능 | 결정 자체는 유효(정책 선택). §5.5 또는 `FE-D027` rationale 에 "플랫폼 제약이 아니라 release coherence 를 위한 **정책** 선택" 임을 명시 | `resolved` 2026-07-28 — `FE-D027` 서술·rationale + `DEC-…-BINARY-STORE-001` Summary·Evidence 정정, 위 상속 표 동기화 |
+| `NO_GROUND_TRUTH` | `/branch-spec` §2 ca-tmpl 대조 | 명령은 `/home/donghyeon/workspace/ca-tmpl` 의 registry·코드와 대조하라고 요구 | `ca-tmpl` 은 Gradle/Java **백엔드 전용**(`domain-core`·`adapter-web`·`shared-contract`). `package.json`·`vite.config`·`.jsx` 부재. frontend 구현 repo 는 hub §0.3 대로 미식별 | 이 branch 의 모든 명세는 `planned`. `actually-implemented` 승격은 frontend repo 식별(`FE-Q-001`) 이후 | `open` — `FE-Q-001` 해소 전까지 유지 |
+| `CAPABILITY_NAME_COLLISION` | `ca-tmpl/docs/registries/capabilities.yaml` vs hub `FE-REG-CAPABILITY` | 두 registry 가 같은 "capability" 어휘를 쓴다 | ca-tmpl 은 *use case → infrastructure 접근 권한*(`READ_REPOSITORY` 등), hub 는 *브라우저 런타임 기능 flag*(`CAP_FE_BINARY_IO` 등). **다른 개념** | 계약을 상호 참조하지 않는다. 혼동 방지를 위해 frontend 쪽은 `CAP_FE_` prefix 를 유지 | `accepted` — prefix 유지로 종결, 추가 조치 없음 |
 
 ## 관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)