# Browser file and origin-storage platform 이 문서는 File, Blob, 파일 선택기, 다운로드, IndexedDB, OPFS, Cache Storage를 프로덕션에 도입할 때의 경계, 프로토콜, 실패·복구 정책과 promotion evidence를 정의한다. 최초 결정 기준일은 2026-07-27이며 lifecycle/migration 설계는 2026-07-28에 갱신했다. 현재 skeleton에는 요청된 browser API를 직접 호출하는 **정책 주입형 reference runtime**이 `AVAILABLE_NOT_COMPOSED` 상태로 들어 있다. catalog exposure의 recipe availability는 `RECIPE_AVAILABLE`이지만 이는 primary status나 product selection 값이 아니다. 제품 capability는 아직 선택·조합하지 않았고 bootstrap/installed feature에는 연결하지 않았다. 따라서 production build에는 포함되지 않고, 실제 제품 요구·dataset owner와 해당 capability가 server 경계를 넘는 경우 backend protocol까지 정한 프로젝트가 필요한 adapter만 조립한다. Service Worker 등록, 제품 데이터 schema와 owner-specific migration policy는 아직 조합하지 않았다. 이 상태는 catalog의 `productionComposition: false`만 믿지 않는다. build가 생성하는 `artifacts/quality/vite-module-inventory.json`과 `check:optional-recipes`가 아래 runtime source root가 production chunk에 없음을 검증한다. IndexedDB reference runtime 자체에는 additive DDL planner, codecVersion 기반 resumable maintenance, dataset budget, retention lifecycle과 receipt retention/prune가 구현되어 있으며 bootstrap에서만 분리되어 있다. 실행 가능한 계약·runtime·evidence는 다음 위치에 있다. - `src/application/ports/browser-file-storage/` - `src/adapters/browser-files/` - `src/adapters/storage/indexeddb/` - `src/adapters/storage/opfs/` - `src/adapters/cache-storage/` - `src/adapters/browser-file-storage/storage-manager-adapter.ts` - `tests/browser-capabilities/` - `recipes/frontend-capabilities/browser-file-storage-contracts.ts` - `recipes/frontend-capabilities/browser-file-storage-fakes.ts` - `tests/recipes/browser-file-storage-contracts.test.ts` - `config/recipes/frontend-capability-recipes.json` - `artifacts/quality/vite-module-inventory.json` (build-generated evidence) - `scripts/test-browser-file-storage-runtime-removal.ts` ## 0. 후속 lifecycle/migration 결정과 현재 delta origin storage를 제품에 composition하기 전 남은 공통 lifecycle 설계는 [VD-15: Origin storage lifecycle, migration, and optional file capabilities](./decisions/VD-15-origin-storage-lifecycle-and-migration.md)에 고정한다. VD-15가 Accepted됐다는 사실은 해당 runtime이 구현 또는 조립됐다는 뜻이 아니다. 현재와 목표를 구분하면 다음과 같다. | 항목 | 현재 reference runtime | VD-15 목표 | | --- | --- | --- | | StorageManager | `estimate/persisted/persist`와 pressure 분류 구현 | IDB·OPFS·Cache write admission, hysteresis, bounded GC와 quota failure 뒤 exact 1회 retry coordinator | | eviction | OPFS logical/physical 및 Cache pointer/candidate의 partial mismatch 감지 | dataset sentinel/backend epoch 연계; origin 전체 marker 소실은 first install과 완전 구분할 수 없음을 유지 | | IndexedDB migration | additive DDL, codecVersion, bounded resumable maintenance 구현 | origin coordinator와 N-1 promotion/rollback evidence 연계 | | OPFS migration | journal/physical manifest v1, reconciliation 구현 | copy-on-write physical/journal forward migration과 historical fixture | | OPFS readiness | API property와 required primitive 확인, 실제 operation은 native browser test에서 검증 | composition readiness에서 worker/lock/journal/small write-read-delete-cleanup real preflight | | Cache Storage | public static release stage/verify/activate, previous retain, owned cleanup 구현 | cursor/count/deadline이 있는 bounded inspect/cleanup과 control-schema migration | | Service Worker | 미조립·미구현 | 제품이 PWA를 선택할 때만 별도 update/client-drain controller | | local preview | byte/signature/media/active-content/object URL lease 구현 | object URL 발급 전 pixel/decoded-byte/animation/real-decode safety probe | | directory/persistent handle/drop | 미구현, transient file picker만 제공 | 제품 workspace/consent 요구가 있을 때 별도 optional capability | | Range resumable download | 현재 download/public cache에 없음 | `DESIGNED_NOT_IMPLEMENTED`; VD-14의 별도 runtime/provider 계약 | | private/sparse Range cache | public cache에서 명시적으로 거부 | 제품이 별도 선택하기 전 `NOT_SELECTED` | | app-managed background download | 현재 미선택 | `NOT_SELECTED`; 지원 browser용 별도 optional capability | | cross-browser app-managed background download guarantee | 대상 browser 전체에서 지속 실행을 보장할 수 없음 | `PLATFORM_LIMITED`; browser-managed handoff와 명시적 progressive enhancement | 따라서 이 문서 아래에서 “해야 한다”로 표현된 항목 중 위 표의 VD-15 목표는 아직 executable implementation이 아니다. primary current-status literal은 `COMPOSED`, `AVAILABLE_NOT_COMPOSED`, `DESIGNED_NOT_IMPLEMENTED`, `NOT_SELECTED`, `PLATFORM_LIMITED` 다섯 값만 사용하며 선형 maturity로 해석하지 않는다. 현재 기존 native runtime은 `AVAILABLE_NOT_COMPOSED`, 새 coordinator/migrator/probe와 Range resumable download는 `DESIGNED_NOT_IMPLEMENTED`, directory/persistent handle/Service Worker/private·sparse Range cache와 app-managed background download capability는 `NOT_SELECTED`, 그 cross-browser guarantee는 `PLATFORM_LIMITED`다. selection, traffic admission, runtime health와 promotion evidence는 이 primary status와 별도 축이다. 축의 canonical 이름과 literal은 completion ledger의 `Selection`, `TrafficAdmission`, `RuntimeHealth`, `PromotionEvidence`를 그대로 사용한다. contract/provider/browser/operations는 별도 축 이름을 만들지 않고 `PromotionEvidence`를 계산하는 component gate다. projection과 evidence expiry도 ledger 규칙을 따른다. ## 1. 변경할 수 없는 경계 결정 ### 1.1 기술별 소유권 | 기술 | 소유하는 것 | 소유하지 않는 것 | | --- | --- | --- | | `File`/`Blob` | 현재 사용자가 선택했거나 현재 작업이 생성한 transient bytes | 영구 ID, 권한, 신뢰 가능한 MIME, persistence | | native file input/picker | user activation 안의 선택 의도와 transient handle | application/domain model, boot permission | | download/save | 검증된 artifact를 브라우저 또는 사용자가 고른 파일에 전달 | server authorization, 파일 처리 완료를 가장한 anchor click | | IndexedDB | 구조화 record, index, revision, idempotency, OPFS journal; 명시적으로 선택된 feature command queue의 storage mechanism이 될 수 있음 | command/sync protocol authority, 큰 immutable payload, HTTP response cache, credential | | OPFS | 큰 opaque immutable bytes, chunk, integrity manifest, staging | query/index, domain metadata authority, 사용자에게 보이는 파일 경로 | | Cache Storage | 정책이 승인한 public HTTP `Request`/`Response` representation | domain repository, TanStack Query cache, 인증/개인 API response | | HTTP cache | 서버 header가 소유하는 일반 freshness/revalidation | application offline database | | 기존 `StoragePort` | 작은 동기식 public preference | IndexedDB, OPFS, Cache Storage | 이 표가 가장 중요한 설계 규칙이다. `StorageAdapter`, `FileManager`, `BrowserPersistence` 같은 범용 mega-port 하나로 합치지 않는다. 각 API는 transaction, 수명, quota, 일관성, 복구 방식이 다르다. ### 1.2 source of truth - 서버는 명시적으로 승인된 offline-first 동기화 protocol을 제외하면 업무 entity와 authorization의 source of truth다. - IndexedDB record는 server state 전체 복제가 아니라 offline projection, unsynced command, local-only product state 중 승인된 하나다. - OPFS의 physical manifest는 integrity/recovery 자료다. 논리적 object의 commit authority는 IndexedDB journal과 logical row다. - Cache Storage hit는 authorization proof가 아니다. 저장 대상 자체를 anonymous public representation으로 제한한다. - `File.name`, `File.type`, extension, `lastModified`와 picker permission은 authorization 또는 content safety의 근거가 아니다. ### 1.3 clean architecture 배치 실제 capability를 선택한 프로젝트의 권장 배치는 다음과 같다. ```text src/features// application/ -offline-repository.ts file-intake.ts file-delivery.ts adapters/ indexeddb/ codec.ts schema.ts migrations.ts repository.ts file/ browser-file-vault.ts download-delivery-adapter.ts upload-example/ quarantined-upload-http-adapter.ts src/adapters/storage/opfs/ opfs-object-store.ts opfs.worker.ts worker-protocol.ts journal-repository.ts src/platform/offline/ cache-policy.ts cache-storage-adapter.ts service-worker-runtime.ts ``` 공통 reference runtime은 domain-neutral한 low-level policy port로 제공한다. 제품 feature는 이를 직접 UI에 노출하지 않고, feature-specific repository/use case가 schema, codec, query plan, authority와 retention policy를 주입해 더 좁은 domain contract로 감싼다. application/domain에는 `IDBDatabase`, transaction callback, store/index 이름, `File`, `Blob`, `FileSystemHandle`, `Request`, `Response`, `Cache`가 보이면 안 된다. ### 1.4 정책과 도메인의 분리 브라우저 API의 안전한 실행 규칙은 도메인과 무관한 공통 정책이다. 예를 들면 transaction-complete 이후 성공 처리, picker user activation, stream chunk 상한, object URL lease, blocked/versionchange 처리, OPFS staging/journal 순서, Cache Storage의 exact match와 fail-closed 검증이 여기에 속한다. 반대로 모든 값을 하나의 전역 정책으로 고정할 수는 없다. 어떤 record를 저장할지, 어떤 index/query가 필요한지, server와 local 중 누가 authority인지, data classification·retention·quota 우선순위, 허용 MIME과 공개 cache 대상은 dataset/use-case owner가 결정한다. 코드에서는 전자는 공통 adapter에, 후자는 주입되는 `*Policy`, codec, query planner와 feature facade에 둔다. 따라서 reference runtime이 제공하는 것은 transaction 완료 판정, bounded stream, scope/policy binding, integrity와 recovery 같은 **공통 메커니즘**이다. 제품 composition root는 dataset별 owner, opaque scope, `BrowserStoragePolicy`, schema/codec/query planner, lifecycle authority와 backend protocol을 명시적으로 주입한다. runtime은 이 구성 객체를 검증한 뒤 깊은 snapshot/freeze하고 persisted binding과 대조한다. 서로 다른 dataset을 하나의 편의상 전역 repository나 가변 policy 객체로 합치지 않는다. ## 2. 공통 데이터 정책 browser persistence를 선택하기 전에 dataset별로 아래 catalog를 채운다. 한 항목이라도 비어 있으면 runtime을 설치하지 않는다. | 필드 | 필수 결정 | | --- | --- | | owner | product owner와 operational owner | | namespace | 고정된 application/feature/dataset ID | | classification | public, internal, personal, confidential; credential은 금지 | | authority | server, local-first, reconstructable 중 하나 | | retention | session, TTL, until-synced, explicit delete | | soft/hard budget | origin 전체와 dataset별 bytes/entries/object limit | | persistence | best-effort 허용 여부와 `persist()` 요청 조건 | | eviction priority | reconstructable → synced copy → user-authored | | account scope | opaque partition key, logout/account deletion 처리 | | failure UX | online-only, read-only, export-required 중 하나 | | recovery | re-fetch, replay, quarantine, operator/user action | | observability | allowlisted event와 bucket attribute | | rollback | N-1 reader, destructive migration 보류 기간 | credential, session token, password, signing key, raw authorization header는 IndexedDB, OPFS, Cache Storage 모두에서 금지한다. 동일 origin JavaScript가 암·복호화 key를 사용할 수 있는 client-side encryption은 XSS에 대한 권한 경계가 아니다. `navigator.storage.estimate()`는 IndexedDB, OPFS, Cache Storage 등이 공유하는 origin storage의 거친 추정치다. free-space 예약이나 기술별 정확한 사용량으로 사용하지 않는다. 기본 pressure policy의 출발점은 다음과 같고 실제 field evidence로 조정한다. | 추정 사용률 | 상태 | 동작 | | --- | --- | --- | | `< 70%` | normal | 승인된 write 계속 | | `70–85%` | pressure | expired/reconstructable data bounded GC | | `>= 85%` | critical | nonessential cache write 중지, sync/export 유도 | | `QuotaExceededError` | authoritative failure | transaction rollback, GC, idempotent operation만 최대 1회 재시도 | 추정치는 hysteresis trigger일 뿐이다. user-authored committed data를 quota 대응 명목으로 자동 삭제하거나 DB 전체를 자동 `deleteDatabase()`하지 않는다. 현재 `storage-manager-adapter.ts`는 이 표의 한 시점 pressure 분류와 명시적 `persist()` 요청만 제공한다. threshold 하향 hysteresis, 기술 간 write admission, GC ordering과 `QuotaExceededError` 뒤 idempotent operation의 최대 1회 retry는 아직 구현되지 않았고 VD-15 coordinator의 목표다. estimate 결과만으로 native free space를 예약했다고 간주해서는 안 된다. ## 3. File, Blob, 파일 선택기 ### 3.1 native type의 수명 `File`은 `Blob`에 이름과 수정 시각 metadata가 추가된 browser object다. application에는 native object 대신 opaque `LocalFileRef`와 정규화된 metadata를 전달한다. adapter의 transient vault가 ref에서 native object를 찾고 bounded inspection/range read를 수행한다. ```text click/user activation -> native input 또는 enhanced picker -> transient browser file vault -> opaque LocalFileRef + untrusted metadata -> bounded inspection -> preview 또는 download 또는 별도 선택한 backend workflow -> ref release ``` `File`, `FileList`, `Blob`, `FileSystemFileHandle`, 로컬 경로와 object URL은 domain, application state, query cache, global store, diagnostics에 넣지 않는다. 같은 파일을 다시 선택할 수 있도록 input value reset 책임도 picker adapter가 소유한다. ### 3.2 picker baseline과 enhancement - 접근 가능한 ``가 모든 browser의 canonical baseline이다. baseline adapter는 `input.click()`으로 이 경로를 활성화한다. `showPicker()` 존재 여부는 portable baseline capability의 판정 기준으로 사용하지 않는다. - `showOpenFilePicker()`와 `showSaveFilePicker()`는 runtime method별 feature detection을 거친 progressive enhancement다. UA sniffing을 사용하지 않는다. - picker 호출은 click/keyboard handler의 첫 browser action이어야 한다. 그 전에 config fetch, analytics flush, permission query를 `await`하면 transient user activation을 잃을 수 있다. - boot, route mount 또는 background effect에서 permission을 요청하지 않는다. - 선택/저장 대화상자 취소는 정상적인 `DISMISSED` outcome이다. error toast, retry alert, error telemetry로 기록하지 않는다. - native input의 `cancel` event는 즉시 authoritative dismissal로 처리한다. `window.focus` 기반 fallback만 사용하는 engine은 focus 복귀 뒤 기본 1초 동안 늦은 `change`/`FileList` 반영을 기다린 다음 dismissal로 확정한다. - permission denied, unsupported, user dismissal, active transfer abort를 서로 다른 outcome으로 다룬다. - enhanced picker가 실패한 같은 click에서 native picker를 자동으로 다시 열면 activation이 소진될 수 있다. fallback 버튼을 보여 다음 명시적 사용자 동작에서 baseline을 실행한다. - directory handle이나 persistent file handle은 별도 제품 capability와 별도 consent/retention decision 없이는 저장하지 않는다. ### 3.3 intake policy와 검증 선택 전에 composition root가 `BrowserFilePolicyProfile`에 다음을 고정한다. application port의 caller는 raw selection/inspection/preview/download 정책을 전달하지 않는다. composition에서 발급·등록한 정확한 `FilePolicyReference` 객체와 더 작은 count/byte limit만 전달한다. registry는 배열, signature pattern, MIME allowlist까지 깊게 snapshot하며 동일한 `policyKey`/`intention` 문자열로 새 reference를 만들어도 권한으로 인정하지 않는다. 따라서 presentation이 다른 feature의 전략, MIME, extension, integrity 또는 byte ceiling을 선택할 수 없다. - purpose/policy version - single/multiple, 최대 file count - 개별 byte limit과 누적 byte limit - zero-byte 허용 여부 - allowlisted extension과 reported MIME pair - bounded inspection bytes와 content signature rule - active content/archive 처리 방식 - classification, retention, telemetry redaction inspection 성공 receipt는 `policyId` 문자열이 아니라 정확한 registered profile과 file snapshot에 묶인다. 같은 inspection rule ID를 공유하는 다른 preview profile로 receipt를 replay하면 `POLICY_REJECTED`다. picker/save dialog를 기다리는 동안 caller request, handle array, byte-source method 또는 composition dependency가 바뀌어도 이미 snapshot/bind한 ref, signal, limits, handle loader와 stream만 사용한다. `accept`, extension, `File.type`과 magic byte는 모두 client-side 조기 UX다. 선택·preview·client-generated download만 도입한 feature에는 backend upload가 필수가 아니다. 업로드를 별도 선택했다면 최종 backend는 authorization과 함께 다음을 다시 검증한다. - 실제 byte length, MIME sniffing, allowlisted parser - image dimensions/pixel budget, PDF active content - archive entry count, nesting, expanded size/ratio, path traversal와 symlink - malware scan/CDR/quarantine - polyglot/malformed input과 decompression bomb - resource owner와 upload session scope 그 별도 upload workflow에서 서버 검증이 끝나기 전 resource 상태는 `QUARANTINED`다. public URL이나 active preview를 발급하지 않는다. ### 3.4 Blob과 memory budget 다음 API는 전체 payload를 메모리에 올릴 수 있으므로 제품별 hard cap 아래에서만 허용한다. - `Blob.arrayBuffer()`, `Blob.text()`, `Blob.bytes()` - `Response.arrayBuffer()`, `Response.blob()`, `Response.text()` - base64/Data URL conversion - 대형 `Uint8Array` 하나로 합치기 대용량 경로는 `Blob.stream()`/`Response.body`와 bounded chunk 또는 multipart를 사용한다. application 계약에는 `readRange` 또는 닫힌 `AsyncIterable>`만 노출하며 adapter가 browser `ReadableStream`/`WritableStream`과 연결한다. recipe contract의 동일 경계는 `CapabilityResult`를 쓴다. 각 chunk는 성공 또는 allowlisted failure고, consumer는 첫 실패에서 소비를 중지한다. native `DOMException`, rejection 또는 부분 byte 뒤의 raw throw가 application 경계를 통과해서는 안 된다. memory upper bound는 적어도 다음 식으로 review한다. ```text part size × concurrent parts × implementation copy factor + preview decode surface + framework/network buffering <= approved foreground memory budget ``` progress의 total은 `null`일 수 있다. unknown total을 억지 percent로 표시하지 않고 indeterminate UI를 사용한다. progress event는 animation frame 또는 4–10Hz 정도로 throttle하고 항상 단조 증가해야 한다. Web Crypto `digest()`는 incremental stream hash가 아니다. 대용량 whole-file을 한 번에 넣지 않는다. 업로드는 bounded part SHA-256, OPFS는 명시적인 chunk-tree digest 또는 별도 검토된 streaming hash adapter를 사용한다. ### 3.5 object URL lease `URL.createObjectURL()`은 호출마다 새 URL과 Blob 수명 lease를 만든다. `TransientPreviewPort` 한 곳만 생성 권한을 갖고 `{url, release}`를 반환한다. - preview 대상 교체, load error, unmount에서 정확히 한 번 revoke한다. - one-shot 작은 download는 click handoff 뒤 cross-engine scheduling을 위해 기본 30초 grace를 두고 revoke한다. runtime dispose는 grace를 기다리지 않고 모든 active lease를 즉시 revoke한다. - preview와 download는 runtime 하나의 lease registry를 같이 쓴다 (`src/adapters/browser-files/create-browser-file-runtime.ts:154`, `:163`). lease 개수나 합계 바이트 한도가 차면 둘 다 `LIMIT_EXCEEDED`를 `retryable: true`, `recovery: "RETRY"`로 반환한다 (`src/adapters/browser-files/object-url-lease.ts:48-71`, `:143-151`). download lease는 grace(`download-delivery-adapter.ts:150`)가 끝나면 풀리므로 잠시 뒤 다시 시도하면 된다. Blob 하나가 단일 lease 상한을 넘으면 재시도 불가다. - 한도는 같이 쓰지만 해제 권한은 나뉜다. `runtime.previews.dispose()`와 download의 `dispose()`는 각자 만든 lease만 revoke한다(`ObjectUrlLeaseScope`). registry 전체를 비우는 것은 `runtime.dispose()`뿐이다. `previews.dispose()` 뒤에는 그 runtime의 preview가 계속 `UNAVAILABLE`이므로 route 정리에는 쓰지 않고 lease마다 `release()`한다. - URL을 global state, IndexedDB, query cache, log, analytics에 보관하지 않는다. - Service Worker에서 object URL을 사용하지 않는다. - 로그아웃·계정 전환에서는 runtime 전체를 dispose한다. browser file runtime은 세션을 모른다(`src/adapters/browser-files/create-browser-file-runtime.ts:93`). `runtime.dispose()`(`:177-188`)가 이전 사용자가 고른 File 참조, preview lease, 진행 중 download(`download-delivery-adapter.ts:390-396`)를 한 번에 닫는다. runtime을 route·feature보다 오래 사는 곳(`product-composition.ts`의 capability)에서 만들었다면 제품 소유 파일만 고친다. `composeProduct`가 `scopeParticipants`로 `dispose()`를 돌려주면 템플릿이 로그아웃·계정 전환마다 FENCED와 READY 사이에서 부르고, 실패하면 READY로 가지 않는다 (`ProductScopeParticipant`, `src/bootstrap/product-composition-contract.ts`). 실패한 close마다 진단 `cache.operation.failed`(`operation: SCOPE_RESET`, `reason: PARTICIPANT_FAILED`, `scope_participant: