feat: 기능 추가 과정중

docs/architecture/decisions/VD-14-resumable-download-and-background-transfer.md

@@ -0,0 +1,898 @@
+# VD-14: Resumable download와 background download 경계
+
+- 상태: Accepted — production design complete, implementation pending
+- 결정일: 2026-07-28
+- catalog recipe availability: `RECIPE_AVAILABLE` (primary status/selection과 별도)
+- Range resumable download primary status: `DESIGNED_NOT_IMPLEMENTED`
+- app-managed background download primary status: `NOT_SELECTED`
+- cross-browser app-managed background download guarantee: `PLATFORM_LIMITED`
+- 관련 결정: VD-10, VD-11, VD-12
+- current status ledger:
+  `docs/architecture/browser-data-capability-completion-ledger.md`
+- 재검토: 제품이 Range 재개, 탭 종료 뒤 전달 또는 대용량 Safari fallback을
+  선택할 때
+
+## 1. 배경과 현재 사실
+
+현재 reference runtime은 whole-object `200` response를 bounded stream으로 읽어
+foreground destination에 저장하거나 browser download manager에 handoff한다. 이
+경로는 전체 payload를 하나의 `Blob`으로 만들지 않고 byte length와 SHA-256을
+검증하지만, 네트워크나 탭이 중단되면 다음 실행은 byte 0부터 다시 시작한다.
+
+Range resume는 기존 stream에 `Range` header 하나를 추가하는 기능이 아니다.
+representation identity, exact `206 Content-Range`, durable partial destination,
+checkpoint CAS, `200/412/416` reconciliation과 마지막 whole-object integrity가
+하나의 protocol이어야 한다. background download도 Range resume와 동일하지 않다.
+브라우저 download manager에 넘기는 것과 애플리케이션이 Service Worker에서
+전송을 계속 관리하는 것은 완료 증거와 상호운용성이 전혀 다르다.
+
+이 ADR은 목표 계약을 정의한다. 이 문서가 존재한다는 사실은 runtime, endpoint,
+worker 또는 제품 UX가 구현·조합되었다는 뜻이 아니다.
+
+## 2. 표준 capability 상태
+
+설계, source 존재, 제품 조합과 플랫폼 한계를 하나의 `enabled` boolean으로 합치지
+않는다. primary current status는 다음 다섯 값 중 정확히 하나다. 이 taxonomy는
+선형 maturity model이 아니며 상태 이름만으로 rollout 또는 production readiness를
+추론하지 않는다.
+
+| primary status | 의미 |
+| --- | --- |
+| `NOT_SELECTED` | 제품 요구, owner, policy 또는 구현 범위가 아직 선택되지 않음 |
+| `DESIGNED_NOT_IMPLEMENTED` | versioned contract와 불변조건은 승인됐지만 reference source가 없음 |
+| `AVAILABLE_NOT_COMPOSED` | 검증 가능한 reference source가 있지만 제품 bootstrap/endpoint에는 연결되지 않음 |
+| `COMPOSED` | 특정 제품 facade, config와 dependency에 실제로 조합됨 |
+| `PLATFORM_LIMITED` | 요구 semantics를 target browser/platform 전체에서 보장할 수 없음 |
+
+production readiness와 traffic admission은 primary status와 독립된 축이다.
+운영 상태는 completion ledger가 정의한 네 canonical 축만 사용한다.
+
+```text
+Selection =
+  NOT_SELECTED | SELECTED | REMOVING
+TrafficAdmission =
+  DISABLED | SHADOW | CANARY | ENABLED
+RuntimeHealth =
+  UNKNOWN | AVAILABLE | DEGRADED | UNAVAILABLE | INCOMPATIBLE
+PromotionEvidence =
+  MISSING | PARTIAL | COMPLETE | EXPIRED
+```
+
+아래 `source evidence`는 ADR과 reference source의 존재를 설명하는 문서 표기일
+뿐 canonical readiness 축이 아니다. `DESIGN_REVIEWED`는 native browser나
+provider 증거가 아니고, `REFERENCE_TESTED`도 ledger의 browser component를
+`PROMOTABLE` 또는 `PromotionEvidence=COMPLETE`로 만들지 않는다.
+
+현재 capability별 판정:
+
+| capability | primary status | source evidence | 비고 |
+| --- | --- | --- | --- |
+| whole-object foreground streaming | `AVAILABLE_NOT_COMPOSED` | `REFERENCE_TESTED` | 기존 VD-12 범위 |
+| browser-managed handoff mechanism | `AVAILABLE_NOT_COMPOSED` | `REFERENCE_TESTED` | 실제 capability issuer는 제품 연결 시 필요 |
+| Range resumable download | `DESIGNED_NOT_IMPLEMENTED` | `DESIGN_REVIEWED` | 이 ADR의 구현 대상 |
+| app-managed background download | `NOT_SELECTED` | `DESIGN_REVIEWED` | 제품 요구가 선택될 때만 별도 구현 |
+| cross-browser app-managed background download guarantee | `PLATFORM_LIMITED` | `DESIGN_REVIEWED` | 공통 baseline으로 promotion 불가 |
+
+기존 foreground stream과 browser-managed handoff의 source/evidence를 Range나
+app-managed background download 구현 증거로 재사용하지 않는다.
+
+## 3. 결정 요약
+
+1. whole-object foreground streaming, Range resumable download,
+   browser-managed handoff와 app-managed background download를 서로 다른
+   capability와 결과 타입으로 유지한다.
+2. Range protocol literal은 `RANGE_RESUMABLE_DOWNLOAD_V1`로 고정한다. 기존
+   whole-object presigned contract에 암묵적으로 섞지 않는다.
+3. resume의 authority는 server-owned immutable generation과 strong validator다.
+   local offset, file name, timestamp 또는 partial byte 존재는 authority가 아니다.
+4. 각 data-plane capability는 exact representation, start/end range, method,
+   response status/header/length와 expiry를 묶고 한 번만 사용한다.
+5. checkpoint는 비권한성 recovery metadata만 account-partitioned storage에
+   보관한다. URL, signed query/header, raw ETag, bearer token과 file path는
+   저장하지 않는다.
+6. destination은 seek/truncate 가능한 명시적 port 또는 owned OPFS staging이다.
+   순차 writable에 검증되지 않은 partial bytes를 append하지 않는다.
+7. checkpoint offset은 destination segment가 durable하게 commit되고 exact length가
+   재확인된 뒤에만 CAS로 전진한다.
+8. final success는 destination 전체를 처음부터 다시 읽어 whole-object SHA-256을
+   검증하고 final commit을 마친 경우만 `SAVED_VERIFIED`다.
+9. browser-managed handoff는 탭 종료 뒤 계속될 수 있는 기본 server-file
+   fallback이지만 결과는 계속 `BROWSER_HANDOFF`다.
+10. app-managed background download는 cross-browser baseline이 아니다. 별도
+    optional protocol, platform probe, worker control plane과 owned staging이 모두
+    승인된 환경에서만 progressive enhancement로 조합한다.
+11. browser 차이는 user-agent 문자열이 아니라 capability probe와 정책으로
+    결정한다.
+
+## 4. Topology와 책임
+
+```text
+product download use case
+  -> product-owned download facade
+       -> DownloadStrategySelector
+            -> WHOLE_OBJECT_PICKER_STREAM
+            -> RANGE_RESUMABLE_FOREGROUND
+            -> BROWSER_MANAGED_HANDOFF
+            -> BOUNDED_OBJECT_URL
+            -> APP_MANAGED_BACKGROUND_DOWNLOAD (optional)
+
+RANGE_RESUMABLE_FOREGROUND
+  -> BFF control plane
+       authorization
+       immutable representation lookup
+       range capability issuance/reissue
+  -> browser RangeDownloadRuntime
+       checkpoint + mutation lock
+       exact HTTP state machine
+       seekable destination or OPFS staging
+       whole-object verification
+  -> object store/BFF byte plane
+
+APP_MANAGED_BACKGROUND_DOWNLOAD
+  -> window-owned admission and user intent
+  -> worker-specific control plane
+  -> owned OPFS staging
+  -> later foreground export
+```
+
+브라우저는 bucket, object key, provider generation locator, signing key 또는 cloud
+credential을 소유하지 않는다. BFF가 logical resource를 exact immutable
+representation에 binding한다. direct object-store Range가 해당 binding과
+capability의 `preconditionMode`가 선택한 exact `If-Range` 또는
+immutable-generation precondition을 실제로 강제하지 못하면 BFF proxy/relay를
+사용한다.
+
+## 5. Versioned Range capability
+
+### 5.1 Application-visible handle
+
+application에는 raw URL이나 validator를 노출하지 않는다.
+
+```text
+RangeDownloadCapability
+  protocol = RANGE_RESUMABLE_DOWNLOAD_V1
+  opaque identity
+  safe receipt
+  resourceId
+  representationBindingSha256
+  totalByteLength
+  mediaType
+  wholeObjectSha256
+  requestedStart
+  requestedEndExclusive
+  preconditionMode = STRONG_IF_RANGE | IMMUTABLE_GENERATION_PRECONDITION
+  allowWholeObjectFallback
+  expiresAtEpochMs
+```
+
+adapter-owned identity vault에는 다음 data-plane binding을 함께 둔다.
+
+```text
+exact HTTPS URL/query
+exact GET method
+exact origin/path
+exact Range header
+exact precondition header/value selected by preconditionMode
+required response headers
+allowed statuses = policy-derived exact subset of 200 | 206 | 412 | 416
+expected representation binding
+maximum response bytes
+single-use receipt
+```
+
+`representationBindingSha256`는 protocol/version, logical resource, immutable
+generation, precondition mode별 normalized strong validator 또는 generation
+binding, exact total length, media type와 expected whole-object digest의 canonical
+binding이다. 이것은 authorization proof가 아니다. BFF는 client 값을 echo하지
+않고 registry snapshot에서 직접 재계산한다.
+
+### 5.2 Strong validator
+
+resume에는 다음 중 하나가 필요하다.
+
+- server registry가 소유하는 immutable object generation과 그 generation에 pin된
+  proxy/direct request
+- RFC semantics를 만족하는 strong ETag와 exact `If-Range`
+
+weak ETag(`W/`), `Last-Modified`만 있는 representation, multipart ETag를 whole
+digest로 해석한 값과 CDN이 임의로 다시 쓴 validator는 resume authority로
+사용하지 않는다. provider가 strong validator를 제공하지 못하면 BFF가 immutable
+generation을 pin하거나 Range resume를 `UNSUPPORTED`로 닫는다.
+
+raw ETag와 provider generation locator는 application, checkpoint, diagnostics와
+telemetry에 노출하지 않는다. reload 뒤에는 BFF가 새 capability를 발급하고,
+runtime은 새 capability의 `representationBindingSha256`가 checkpoint와 같은지
+확인한 뒤 vault 안의 exact precondition만 사용한다.
+
+`STRONG_IF_RANGE` mode는 exact `If-Range`를 보내고 `206`, Range-ignore 또는
+validator mismatch의 full `200`과 해당 `416`만 계약한다.
+`IMMUTABLE_GENERATION_PRECONDITION` mode는 BFF/provider가 정한 exact `If-Match`
+또는 generation precondition을 보내며 `412`를 계약할 수 있다.
+`allowWholeObjectFallback`과 `allowedStatuses`는 mode, requested start와 provider
+topology에서 capability 발급 시 닫히며 executor가 임의로 넓히지 않는다.
+
+### 5.3 Capability 재발급
+
+capability expiry, data-plane `401/403/410` 또는 최소 잔여 lifetime 부족은 같은
+URL의 무조건 retry가 아니다.
+
+1. 현재 response reader를 cancel하고 capability를 consume한다.
+2. control plane에 `downloadKey`, resource와 expected representation binding,
+   exact next range를 전달한다.
+3. BFF가 authorization와 current generation을 다시 읽는다.
+4. binding이 같을 때만 새 capability로 같은 range를 재시도한다.
+5. binding이 바뀌었으면 partial destination을 append하지 않고
+   `REPRESENTATION_CHANGED/RESTART`로 닫는다.
+
+재발급 횟수, 전체 operation deadline과 retry backoff는 composition hard ceiling
+안에 둔다. capability를 durable queue나 worker message에 저장하지 않는다.
+
+## 6. Durable checkpoint
+
+### 6.1 Schema
+
+```text
+RangeDownloadCheckpointV1
+  schemaVersion = 1
+  protocol = RANGE_RESUMABLE_DOWNLOAD_V1
+  revision
+  state = ACTIVE | PAUSED | FINALIZING | CLEANUP_PENDING
+  downloadKey
+  resourceBindingSha256
+  representationBindingSha256
+  totalByteLength
+  nextOffset
+  committedSegmentCount
+  destination
+    kind = OPFS_STAGING | SEEKABLE_FILE
+    opaqueDestinationBinding
+  createdAtEpochMs
+  updatedAtEpochMs
+  retentionExpiresAtEpochMs
+```
+
+`downloadKey`, destination binding과 physical database/OPFS namespace는
+composition-issued opaque token이다. 사용자 file name, resource ID, account ID,
+tenant ID 또는 local path를 넣지 않는다.
+
+checkpoint에 금지하는 값:
+
+- presigned URL, query와 signed request/response header
+- bearer/session/auth/CSRF token
+- raw ETag, provider object key/generation locator
+- file name, user path와 native exception
+- incremental hash 내부 state
+- raw backend response나 retry body
+
+허용된 digest binding과 offset은 비권한성 recovery metadata다. account partition,
+retention, count/byte budget과 logout deletion을 적용하며 log/analytics/ticket에는
+내보내지 않는다.
+
+### 6.2 CAS와 durable offset
+
+한 `downloadKey`는 cross-context exclusive mutation lock으로 직렬화한다. lock은
+correctness의 유일한 authority가 아니며 checkpoint revision CAS와 exact
+destination binding이 최종 local authority다.
+
+`nextOffset`은 다음 순서가 모두 성공한 뒤에만 전진한다.
+
+1. exact `206` range를 bounded stream으로 읽는다.
+2. expected start 위치에만 쓴다.
+3. writer close/segment commit을 완료한다.
+4. destination의 committed length가 expected end 이상인지 확인한다.
+5. unexpected tail이 있으면 authorized `truncate(expectedEnd)`를 완료한다.
+6. checkpoint를 `revision + 1`, `nextOffset = expectedEnd`로 CAS한다.
+
+response가 성공했지만 destination commit 전에 crash하면 checkpoint는 이전
+offset에 머문다. 재시작은 destination을 checkpoint offset으로 truncate하고 같은
+range를 다시 요청한다. destination commit 뒤 checkpoint CAS가 유실된 경우도
+동일하게 checkpoint offset까지 truncate한 뒤 재전송한다. 따라서 중복 byte를
+append하지 않는다.
+
+### 6.3 Inventory와 retention
+
+checkpoint store는 단일 key read 외에 bounded admin operation을 제공해야 한다.
+
+- account partition 안의 safe summary를 cursor page로 list
+- expired/terminal checkpoint를 bounded batch로 classify
+- destination binding과 함께 exact owned staging을 cleanup
+- active lock/lease가 있는 항목은 건너뜀
+- count, logical bytes, maximum age와 cleanup retry budget 강제
+- cleanup receipt를 durable하게 남기고 response 유실을 reconcile
+
+inventory에는 resource ID, file name, digest, raw validator와 path를 반환하지
+않는다. 제품 resume UI가 필요한 경우 제품 database/query가 별도 safe display
+metadata를 소유하고 opaque `downloadKey`로만 연결한다.
+
+## 7. Destination 계약
+
+### 7.1 공통 port
+
+```text
+ResumableDownloadDestinationPort
+  inspect(binding) -> committedLength, readable, writable, permissionState
+  openWriter(binding, keepExistingData=true)
+  seek(offset)
+  write(chunk)
+  truncate(length)
+  commitSegment()
+  openReader(start=0)
+  finalize()
+  abortAttempt()
+  cleanup(authority)
+```
+
+native handle, OPFS handle와 path는 adapter 밖으로 노출하지 않는다. 모든 method는
+bounded deadline, AbortSignal과 closed failure를 사용한다.
+
+### 7.2 Seekable external file
+
+직접 외부 파일에 resume하려면 browser가 기존 data 보존, seek, truncate,
+재읽기와 permission 재확인을 실제로 지원해야 한다.
+
+- picker와 permission request는 Window의 명시적 user activation에서만 실행한다.
+- structured-cloned handle을 보존하는 경우 별도 privacy/retention 승인이 필요하다.
+- reopen 뒤 `queryPermission`/`requestPermission`을 거치며 denied면
+  `PERMISSION_DENIED/RESELECT`다.
+- writer가 temporary-file commit semantics를 쓰면 segment마다 close한 뒤
+  committed file size를 다시 확인한다.
+- checkpoint보다 큰 tail은 검증하지 않고 사용하지 않으며 exact checkpoint
+  offset으로 truncate한다.
+- checkpoint보다 파일이 작거나 다른 handle이면 `CONFLICT/RESTART`다.
+
+브라우저가 이 계약을 만족하지 못하면 external-file resume를 흉내 내지 않고 OPFS
+staging 또는 browser-managed handoff로 전환한다.
+
+### 7.3 OPFS staging
+
+cross-browser app-controlled resume의 우선 destination은 policy-owned OPFS
+staging이다.
+
+- physical path는 기존 OPFS authority/namespace/partition registry가 발급한다.
+- checkpoint와 OPFS object는 immutable binding과 generation journal로 연결한다.
+- quota estimate는 admission hint일 뿐이며 write 중 quota failure도 처리한다.
+- download 완료 뒤 staging 전체를 다시 읽어 SHA-256을 검증한다.
+- foreground user activation에서 새 외부 destination을 열고 staging을 stream
+  export한다.
+- 외부 export close가 성공하기 전 staging을 삭제하지 않는다.
+- export 결과가 유실되면 staging을 유지하고 user에게 retry 가능한 상태를
+  반환한다.
+
+OPFS 저장 성공은 사용자가 접근 가능한 파일 저장 완료가 아니다. 결과를
+`STAGED_VERIFIED`와 `SAVED_VERIFIED`로 구분한다. OPFS는 큰 파일에서 storage와
+I/O를 한 번 더 요구하므로 quota/retention owner 없는 기본 fallback이 아니다.
+
+## 8. HTTP 상태 머신
+
+### 8.1 요청 전
+
+1. checkpoint와 destination binding을 exact하게 읽는다.
+2. destination length를 검사하고 checkpoint보다 큰 tail을 truncate한다.
+3. checkpoint보다 작으면 partial을 신뢰하지 않고 restart/cleanup으로 닫는다.
+4. 새 capability의 representation binding과 exact range를 검증한다.
+5. `Range: bytes=S-E`와 capability의 `preconditionMode`가 정한 exact
+   `If-Range` 또는 immutable-generation precondition을 vault binding 그대로
+   보낸다.
+6. `credentials: omit`, `redirect: error`, `no-referrer`, `no-store`,
+   identity content encoding을 강제한다.
+
+한 request의 range 크기와 exact `S/E`는 capability 발급 **전에** composition
+maximum 안에서 계산한다. executor는 capability의 `requestedStart`,
+`requestedEndExclusive`와 exact Range header가 일치하는지 검증하고 그대로
+전송하며 다시 줄이거나 늘리지 않는다. ceiling을 넘는 capability는 사용 전에
+거절한다. 기본 protocol은 sequential range만 허용한다. parallel range와 sparse
+destination은 별도 protocol/version 없이는 사용하지 않는다.
+zero-byte representation은 유효하지 않은 byte range를 만들지 않는다. exact
+length가 0이고 empty-object SHA-256 binding이 일치하는 whole-object `200` 경로로
+body/length를 확인한 뒤 바로 final verification으로 이동한다.
+
+response body를 읽거나 destination writer를 열기 전에 `200`, `206`, `412`,
+`416` 중 수신한 status가 capability vault의 exact `allowedStatuses` member인지
+검사한다. 해당 네 값 중 허용되지 않은 status는 body를 cancel하고 capability를
+consume하며 destination과 checkpoint를 변경하지 않은 채
+`CONTRACT_MISMATCH`로 fail-closed한다. 아래 네 분기는 이 공통 admission gate를
+통과한 경우에만 실행한다. 그 밖의 status는 §8.6의 별도 failure/reissue 규칙으로
+처리한다.
+
+### 8.2 `206 Partial Content`
+
+성공 조건:
+
+- `206`이 capability의 `allowedStatuses` member
+- final response URL이 capability URL과 exact match
+- `Content-Range: bytes S-E/T`가 하나만 존재하고 parse가 엄격함
+- `S`가 requested start, `E + 1`이 requested end exclusive
+- `T`가 checkpoint total과 같음
+- `Content-Length = E - S + 1`
+- strong validator/immutable generation binding 일치
+- media type과 identity encoding 일치
+- body 실제 bytes가 exact content length
+
+하나라도 다르면 reader와 current destination attempt를 abort하고 checkpoint를
+전진시키지 않는다. 정상인 경우에만 앞 절의 durable offset 순서로 commit한다.
+
+### 8.3 `200 OK`
+
+`200`은 capability의 `allowedStatuses` member인 경우에만 이 분기로 들어온다.
+body를 destination에 쓰기 전에 final response URL, required response header,
+media type, identity encoding과 mode별 strong validator 또는 immutable-generation
+evidence가 capability의 exact representation binding과 일치하는지 검증한다.
+
+다음 순서로 배타적으로 처리한다.
+
+1. validator/generation evidence가 없거나 binding이 다르면 body를 cancel하고
+   capability를 consume한다. 기존 checkpoint와 partial은 append하지 않고
+   quarantine/retention policy로 전환한 뒤 control plane에서 current
+   representation을 다시 확인한다. 결과는
+   `REPRESENTATION_CHANGED/RESTART`이며 byte 0의 새 operation만 허용한다.
+2. binding은 같지만 requested start가 `0`이고
+   `allowWholeObjectFallback=true`이면 fresh whole-object destination에서 기존
+   whole-object stream 계약으로 처리한다. exact total length와 final
+   whole-object digest를 검증하기 전에는 success나 final commit을 반환하지 않는다.
+3. binding은 같고 requested start가 `0`이지만
+   `allowWholeObjectFallback=false`이면 body를 한 byte도 쓰지 않고 cancel한다.
+   결과는 `WHOLE_OBJECT_FALLBACK_NOT_ALLOWED`이며 policy가 허용한 새 Range
+   capability, browser handoff 또는 explicit unsupported만 선택한다.
+4. binding은 같고 requested start가 `0`보다 크면 server가 Range를 무시한
+   것이다. body를 한 byte도 쓰지 않고 cancel하며 기존 partial을 같은 writer에서
+   덮어쓰지 않는다. control plane reconcile 뒤 같은 representation의 byte 0
+   restart operation, browser handoff 또는 explicit unsupported만 선택한다.
+
+### 8.4 `412 Precondition Failed`
+
+`412`가 capability의 `allowedStatuses` member이고
+`preconditionMode=IMMUTABLE_GENERATION_PRECONDITION`인 경우에만 이 분기로 들어온다.
+representation precondition 실패다. body를 cancel하고 checkpoint를 유지한 채
+control plane에서 current generation을 확인한다. 같은 binding을 다시 발급하지
+못하면 partial은 cleanup policy에 따라 폐기하고 byte 0부터 새 operation을
+시작한다.
+
+RFC `If-Range` validator mismatch 자체의 정상 응답은 `200`이다. `412`는 BFF나
+provider가 immutable generation을 pin하기 위해 별도 `If-Match` 계열 precondition을
+함께 강제하는 topology에서만 이 상태 머신에 들어온다. topology가 `412`를 계약하지
+않았다면 unknown status로 fail-closed한다.
+
+### 8.5 `416 Range Not Satisfiable`
+
+`416`이 capability의 `allowedStatuses` member인 경우에만 이 분기로 들어온다.
+response body는 download data로 소비하지 않고 cancel한다.
+`Content-Range: bytes */T`를 strict하게 검사하며 final response URL, required
+headers와 mode별 validator/generation binding도 확인한다. provider의 `416`이
+binding evidence를 반환할 수 없는 topology라면 BFF control plane reconcile이
+exact immutable generation을 다시 증명하기 전에는 EOF나 missing-range 분기로
+진행하지 않는다.
+
+다음 순서를 사용하며 한 분기를 처리한 뒤 아래 분기로 fall through하지 않는다.
+
+1. malformed/missing `T`, final URL/header mismatch 또는 증명되지 않은
+   representation binding은 `CONTRACT_MISMATCH`로 fail-closed한다.
+2. `T != expected total`이면 representation changed다. local bytes를 `T`에 맞춰
+   자동 truncate하거나 append하지 않고 capability를 consume한 뒤 partial을
+   quarantine/restart한다.
+3. `nextOffset > T`이면 checkpoint 자체가 corrupt/stale이다. 잘못된 offset으로
+   truncate하지 않고 checkpoint와 partial을 quarantine한 뒤 restart/recovery로
+   닫는다.
+4. `nextOffset <= T`이지만 `local committed length != nextOffset`이면 먼저 local
+   state를 reconcile한다.
+   - local length가 더 크면 exact `nextOffset`까지만 uncommitted tail을
+     authorized truncate하고 durable length를 다시 확인한다.
+   - local length가 더 작으면 journal이 증명하는 마지막 confirmed segment로
+     destination과 checkpoint를 함께 CAS rollback할 수 있을 때만 복구한다.
+     그렇지 않으면 quarantine/restart한다.
+   이 분기는 reconcile 결과를 새 state-machine invocation에서 다시 평가하며 바로
+   finalization이나 missing-range request로 진행하지 않는다.
+5. `local committed length == nextOffset == T`이면 data transfer가 끝난 후보로
+   보고 `FINALIZING` whole-object verification으로 이동한다.
+6. `local committed length == nextOffset < T`이면 local missing range가 남아 있다.
+   새 capability로 exact `nextOffset` range를 재발급한다. 같은 total에 대해
+   satisfiable range가 다시 `416`이면 bounded retry하지 않고
+   `CONTRACT_MISMATCH`로 fail-closed한다.
+
+`416` 자체를 다운로드 성공으로 간주하지 않는다.
+
+### 8.6 나머지 상태와 network failure
+
+| 조건 | 처리 |
+| --- | --- |
+| `401/403/410` | bounded capability reissue; binding mismatch면 restart |
+| `404` | existence-hiding policy에 따라 unavailable/not-found, partial cleanup 예약 |
+| `409` | server representation/session reconcile |
+| `429`/모든 `5xx`/network | 동일 exact range만 bounded retry |
+| redirect/opaque response | policy rejection |
+| timeout/cancel | reader와 writer attempt abort, checkpoint 유지 |
+| overrun/truncation | integrity failure, checkpoint 유지 |
+
+retry는 destination commit 여부를 먼저 판단한다. effect가 ambiguous하면
+checkpoint와 destination length를 reconcile하기 전 새 offset으로 이동하지 않는다.
+
+## 9. Whole-object integrity와 final commit
+
+Range별 transport 검증은 whole-object 무결성 증거가 아니다. 모든 bytes가
+수신되면 checkpoint를 `FINALIZING`으로 CAS하고 다음을 수행한다.
+
+1. destination length가 exact total과 같은지 확인한다.
+2. destination을 byte 0부터 bounded chunk로 다시 읽는다.
+3. vetted incremental SHA-256으로 whole-object digest를 계산한다.
+4. capability/representation binding의 expected digest와 constant-time 비교한다.
+5. mismatch면 사용자 destination을 성공으로 표시하지 않고 staging을 격리하거나
+   authorized cleanup한다.
+6. OPFS staging이면 foreground external export와 destination close를 완료한다.
+7. final destination commit truth를 확인한 뒤만 `SAVED_VERIFIED`를 반환한다.
+8. checkpoint와 staging cleanup을 exact revision/receipt로 완료한다.
+
+portable하지 않은 incremental hash 내부 state를 checkpoint에 serialize하지 않는다.
+마지막 full reread 비용을 피하려면 chunk digest/Merkle manifest를 별도 protocol로
+설계하고 server가 exact proof를 제공해야 한다.
+
+## 10. Pause, cancel, crash와 account lifecycle
+
+### 10.1 Pause
+
+`pause(downloadKey)`는 browser work 중단이며 server resource/capability revoke가
+아니다.
+
+- 같은 runtime의 read/write/backoff를 AbortSignal로 중단한다.
+- same-origin context에는 opaque key만 담은 versioned ephemeral pause event를
+  보낸다.
+- mutation lock 안에서 checkpoint를 `PAUSED`로 CAS한다.
+- in-memory URL/header/capability는 즉시 retire한다.
+- committed segment는 유지하고 ambiguous writer attempt는 checkpoint offset으로
+  reconcile한다.
+
+### 10.2 Cancel과 discard
+
+cancel은 transfer 중단만 의미할 수 있고, discard는 local partial 삭제다. 제품
+facade가 두 의도를 구분해야 한다. discard는 exact partition/destination binding과
+short-lived maintenance authority를 요구하며 checkpoint와 OPFS staging을 하나의
+cleanup journal로 처리한다.
+
+### 10.3 Crash/reload
+
+reload 후 runtime은:
+
+1. account partition과 governance binding을 검증한다.
+2. checkpoint schema/protocol/revision을 검증한다.
+3. destination을 reopen하고 permission/length를 검사한다.
+4. server에서 새 capability를 발급받아 representation binding을 대조한다.
+5. exact checkpoint offset부터 resume한다.
+
+source가 같은지 사용자에게 묻는 file-name 기반 확인은 사용하지 않는다.
+
+### 10.4 Logout/account/tenant switch
+
+- 신규 capability 발급과 resume admission을 먼저 닫는다.
+- active foreground operation을 abort하고 writer를 정리한다.
+- vault와 worker channel을 close한다.
+- account partition의 checkpoint와 owned staging을 maintenance-authorized bounded
+  cleanup으로 제거한다.
+- blocked deletion을 성공으로 보고하지 않는다.
+- 이전 account handle/reference를 새 runtime에서 resolve하지 않는다.
+
+retention/legal-hold 정책이 local partial 보존을 요구하는 특별한 제품이 아니라면
+logout에서 partial을 제거하는 것이 기본이다.
+
+## 11. Download strategy selector
+
+selector는 presentation의 임의 조건문이 아니라 composition-owned immutable
+policy와 runtime probe를 받는 공통 application service다.
+
+입력:
+
+- source가 server resource인지 client-generated artifact인지
+- exact 또는 maximum byte length
+- verified integrity 필요 여부
+- resume/background 요구
+- system save picker, seek/truncate, OPFS와 worker capability
+- user activation
+- storage quota admission
+- browser-managed capability availability
+- data classification와 retention policy
+
+결과:
+
+| 조건 | 선택 |
+| --- | --- |
+| server file, 탭 종료 뒤 계속 필요 | `BROWSER_MANAGED_HANDOFF` |
+| server file, verified foreground save, picker 지원 | `WHOLE_OBJECT_PICKER_STREAM` |
+| server file, resume 필수, destination 계약 충족 | `RANGE_RESUMABLE_FOREGROUND` |
+| 작은 generated artifact | `BOUNDED_OBJECT_URL` |
+| 큰 generated artifact, picker 지원 | `WHOLE_OBJECT_PICKER_STREAM` |
+| 큰 generated artifact, picker 미지원 | `SERVER_GENERATION_REQUIRED` 또는 `UNSUPPORTED` |
+| app background download가 승인·지원되고 OPFS quota 확보 | `APP_MANAGED_BACKGROUND_DOWNLOAD` |
+
+selector는 fallback으로 byte/memory/security ceiling을 올리지 않는다. integrity가
+필수인데 browser handoff만 가능하면 “검증된 저장”으로 downgrade하지 않고 제품이
+handoff 또는 unsupported 중 하나를 명시적으로 선택한다.
+
+### Safari와 picker 미지원 환경
+
+user-agent 문자열로 Safari를 판별하지 않는다. 필요한 API와 실제 semantics를
+capability probe로 확인한다.
+
+- 대용량 server file: authorized `Content-Disposition` browser handoff
+- 작은 generated file: bounded Blob/object URL
+- 대용량 generated file: server-side generation 또는 unsupported
+- OPFS: app-private staging일 뿐 Finder/Files 저장 완료로 표시하지 않음
+- system save picker 미지원: unbounded Blob으로 자동 전환하지 않음
+- seek/truncate/permission semantics 미충족: external Range resume 비활성화
+
+browser-managed handoff endpoint는 cross-origin `download` attribute에 의존하지
+않고 server가 safe `Content-Disposition`, media type, byte/generation policy를
+실제 response에서 강제한다.
+
+## 12. Background download 전달의 세 의미
+
+### 12.1 Foreground app-managed
+
+page가 열린 동안 runtime이 fetch, progress, integrity와 destination을 모두
+관리한다. 현재 whole-object stream과 목표 Range resume가 이 범주다. page lifecycle
+종료 뒤 지속을 보장하지 않는다.
+
+### 12.2 Browser-managed handoff
+
+navigation/download manager에 authorized endpoint를 넘긴다.
+
+- page 종료 뒤 계속될 수 있는 가장 넓은 fallback
+- application은 실제 disk write, 저장 위치와 final digest를 관찰하지 못함
+- 결과는 `BROWSER_HANDOFF`, `SAVED`나 `VERIFIED`가 아님
+- pause/resume UI와 retry semantics는 browser가 소유
+
+### 12.3 App-managed background download
+
+Service Worker/Background Fetch 등에서 application이 progress/retry/staging을
+관리하려는 별도 optional capability다.
+
+필수 조건:
+
+- target browser/deployment의 explicit support matrix
+- worker-safe authenticated control plane
+- worker가 매 range마다 새 short-lived capability를 발급받는 계약
+- capability/URL/header를 IDB, OPFS, Cache Storage와 message에 저장하지 않음
+- private bytes는 Cache Storage가 아니라 policy-owned OPFS staging 사용
+- worker termination을 정상 상태로 보고 checkpoint에서 재개
+- concurrency, battery/network, quota와 retention ceiling
+- logout/revocation event와 worker admission fence
+- client/worker version compatibility와 upgrade drain
+- notification/foreground export UX
+
+일반 Service Worker의 수명이나 background execution 시간을 correctness 근거로
+삼지 않는다. Background Fetch가 없는 환경에서 timer/keepalive로 장기 download를
+흉내 내지 않는다. user-visible external save picker는 worker에서 호출하지 않고
+완료된 OPFS staging을 다음 foreground user gesture에서 export한다.
+
+따라서 app-managed background download가 향후 `AVAILABLE_NOT_COMPOSED` 또는 `COMPOSED`가
+되더라도 지원 browser의 progressive enhancement일 뿐이다. cross-browser 보장
+자체의 primary status는 계속 `PLATFORM_LIMITED`다.
+
+## 13. Security, privacy와 observability
+
+- URL/query/header, validator와 capability는 bearer 또는 sensitive metadata로
+  취급한다.
+- `Range`와 `preconditionMode`가 선택한 exact `If-Range` 또는
+  immutable-generation precondition은 adapter vault가 binding 그대로 생성한다.
+- caller는 offset을 늘리거나 arbitrary range를 요청하지 못한다.
+- account partition과 resource authorization을 매 capability reissue에서 검사한다.
+- partial bytes는 원본과 같은 data classification, retention, encryption-at-rest와
+  deletion policy를 적용한다.
+- OPFS quota pressure가 다른 account partial을 제거할 권한을 주지 않는다.
+- preview, execution 또는 Cache Storage promotion은 final verification 전 금지한다.
+- high-cardinality ID, file name, path, URL, raw ETag와 digest를 metric label/log에
+  넣지 않는다.
+
+허용된 aggregate observation:
+
+- strategy와 destination kind
+- response state bucket
+- expected/committed byte bucket
+- retry/reissue/resume count bucket
+- duration, pause, restart, integrity와 cleanup outcome
+- browser capability support reason code
+
+## 14. Composition과 operational admission
+
+`createBrowserTransferRuntime`에 해당하는 미래 composition owner만 다음을 조합한다.
+
+- versioned wire codecs와 fixed BFF endpoint
+- capability vault/provider/executor
+- Range checkpoint store, destination registry와 mutation lock
+- selector policy와 browser capability probe
+- presigned, upload, image와 Range lifecycle
+- account/logout cleanup authority
+- safe observer
+- traffic admission과 kill switch
+
+독립적인 canonical readiness 상태:
+
+```text
+Selection         = NOT_SELECTED | SELECTED | REMOVING
+TrafficAdmission  = DISABLED | SHADOW | CANARY | ENABLED
+RuntimeHealth     = UNKNOWN | AVAILABLE | DEGRADED | UNAVAILABLE | INCOMPATIBLE
+PromotionEvidence = MISSING | PARTIAL | COMPLETE | EXPIRED
+```
+
+primary status가 `COMPOSED`여도 `TrafficAdmission` 기본값은 `DISABLED`다.
+필수 config, strong validator/provider conformance, destination semantics, cleanup
+owner 또는 valid evidence가 없으면 `TrafficAdmission=DISABLED`,
+`RuntimeHealth=UNKNOWN | UNAVAILABLE`,
+`PromotionEvidence=MISSING | PARTIAL | EXPIRED`로 readiness를 fail-closed한다.
+이미 승인된 product selection 자체를 provider evidence 부족만으로 되돌리지
+않는다.
+
+Kill switch:
+
+- 신규 Range capability issuance off
+- Range resume off → whole-object restart 또는 browser handoff
+- direct object-store Range off → BFF proxy
+- external seek destination off → OPFS staging 또는 handoff
+- app-managed background download off → foreground/browser handoff
+- final export off → verified staging 유지
+
+kill switch는 partial을 자동 삭제하거나 handoff를 saved/verified로 바꾸지 않는다.
+
+## 15. Test와 conformance matrix
+
+### 15.1 Deterministic runtime
+
+- checkpoint CAS conflict와 corrupt/unknown field
+- exact segment commit 전/후 crash
+- destination larger/smaller/different binding
+- pause/resume/cancel/discard races
+- capability expiry/reissue와 representation change
+- `200/206/412/416` 모든 분기
+- malformed/multiple/overflow `Content-Range`
+- weak/missing/mismatched validator
+- overrun, truncation, stalled body와 abort
+- final whole-object digest mismatch
+- cleanup response loss와 replay
+- count/byte/age retention sweep
+
+### 15.2 Browser matrix
+
+- system picker 지원/미지원
+- seek/truncate/keep-existing-data semantics
+- OPFS quota, eviction, reload와 worker termination
+- cross-tab lock/pause delivery
+- user activation과 permission denied/revoked
+- large server handoff
+- foreground export close/abort
+- Chromium, Firefox와 WebKit 동일 필수 case set
+
+지원하지 않는 API는 skip이 아니라 selector의 expected fallback/`UNSUPPORTED` 결과로
+검증한다.
+
+### 15.3 BFF/object provider contract
+
+- immutable generation pin
+- capability `preconditionMode`에 따른 strong `If-Range` 또는 immutable
+  generation precondition
+- beginning/middle/end/empty/invalid range
+- exact `206 Content-Range`와 length
+- deliberate Range ignore `200`
+- mode가 계약한 경우의 precondition `412`, EOF/invalid `416`
+- mid-transfer capability expiry/revocation
+- redirect/CORS/exposed-header/identity-encoding
+- object replacement race
+- direct provider와 proxy 결과 동등성
+- URL/header/log redaction
+
+fake와 route interception은 actual provider conformance를 대체하지 않는다.
+
+### 15.4 Background-download-specific fault
+
+- worker가 range commit 전/후 종료
+- worker/client version 교체
+- logout과 capability revocation
+- offline/online 반복, quota exhaustion과 battery/network policy
+- notification 유실과 foreground export replay
+- unsupported browser가 foreground/handoff로 정확히 fallback
+
+## 16. Rollout과 promotion
+
+Primary status 변경과 readiness/traffic promotion은 별도로 승인한다.
+
+1. Range의 `DESIGNED_NOT_IMPLEMENTED`와 ADR-local
+   `sourceEvidence=DESIGN_REVIEWED`를 확인한다.
+2. provider-neutral ports/runtime, deterministic fake, negative fixture와 browser
+   test를 완성한 경우에만 Range primary status를
+   `AVAILABLE_NOT_COMPOSED`, source evidence를 `REFERENCE_TESTED`로 변경한다.
+   deterministic/reference test만으로 canonical `PromotionEvidence`를
+   `COMPLETE`로 바꾸지 않는다.
+3. 제품 요구, owner, data class와 fallback이 선택되지 않은 app-managed
+   background download는 계속 `NOT_SELECTED`로 둔다. cross-browser 보장은
+   `PLATFORM_LIMITED`다.
+4. fixed staging BFF/provider, actual config, account lifecycle와 runbook을 설치한
+   capability만 `COMPOSED`로 기록한다. 이때도
+   `TrafficAdmission=DISABLED`, `RuntimeHealth=UNKNOWN`,
+   `PromotionEvidence=PARTIAL`이다.
+5. operator probe와 shadow에서 contract evidence를 수집한다.
+6. internal cohort에서 BFF proxy Range를 먼저 canary한다.
+7. direct provider Range와 external seek destination은 각각 별도 canary한다.
+8. app-managed background download를 실제로 선택했다면 지원 browser cohort에서만 별도
+   opt-in canary한다.
+9. contract/provider/browser/operations component gate, SLO, cleanup drill,
+   rollback과 evidence freshness가 모두 충족된 승인 범위만
+   `PromotionEvidence=COMPLETE`, `RuntimeHealth=AVAILABLE`,
+   `TrafficAdmission=ENABLED`로 promotion한다.
+
+provider, endpoint, validator semantics, browser major behavior, destination adapter,
+wire protocol 또는 security policy가 바뀌면 relevant evidence를 만료시키고
+재승인한다.
+
+## 17. Rollback과 제거
+
+운영 rollback 순서:
+
+1. 신규 Range/background-download admission과 capability 발급을 중지한다.
+2. active writer/worker를 abort하고 checkpoint offset으로 reconcile한다.
+3. app background download를 foreground/browser handoff로 낮춘다.
+4. direct Range를 BFF proxy 또는 whole-object restart로 낮춘다.
+5. verified OPFS staging은 retention window 안에서 foreground export 가능 상태로
+   유지한다.
+6. ambiguous partial은 성공으로 표시하지 않고 cleanup queue로 넘긴다.
+7. provider/signing credential 노출이 원인이면 backend revoke와 key rotation을
+   수행한다.
+
+완전 제거:
+
+1. pending checkpoint/staging inventory를 bounded하게 drain, export 또는 discard한다.
+2. worker, channel, lock과 runtime을 close한다.
+3. account-partition checkpoint/OPFS namespace를 maintenance-authorized cleanup한다.
+4. endpoint, worker registration, config, policy와 feature facade를 제거한다.
+5. production bundle/module inventory와 removal test로 source 부재를 증명한다.
+
+rollback은 unbounded Blob fallback, validator 완화, digest 생략 또는 partial 자동
+append를 허용하지 않는다.
+
+## 18. 완료 기준
+
+Range resumable download는 다음이 모두 참일 때만 구현 완료다.
+
+- `RANGE_RESUMABLE_DOWNLOAD_V1` port와 strict wire codec이 있음
+- capability mode별 exact allowed-status subset과 `200/206/412/416` 처리
+  상태 머신이 실행 가능하게 검증됨
+- strong validator/immutable generation이 실제 provider에서 강제됨
+- checkpoint CAS, inventory, retention과 account cleanup이 구현됨
+- seek/truncate 또는 OPFS staging destination이 crash fault를 통과함
+- capability reissue가 representation mismatch를 fail-closed함
+- final whole-object SHA-256 뒤에만 verified success를 반환함
+- selector가 picker/seek 미지원과 대용량 fallback을 안전하게 결정함
+- actual BFF/provider와 Chromium/Firefox/WebKit evidence가 유효함
+- SLO, alert, runbook, kill switch, rollback과 cleanup drill이 승인됨
+
+app-managed background download는 위 항목에 더해 다음이 필요하다.
+
+- 지원 browser/deployment 범위가 명시됨
+- worker lifecycle 종료를 checkpoint로 복구함
+- worker control plane이 durable capability 저장 없이 동작함
+- logout/revocation/version upgrade fault가 통과함
+- 미지원 browser fallback이 동일 제품 요구를 안전하게 만족하거나 명시적
+  unsupported UX를 가짐
+
+이 기준 전에는 기존 foreground streaming 또는 browser handoff의 성공을 Range나
+background download 구현 완료 증거로 사용하지 않는다.
+
+## 19. 선택하지 않은 대안
+
+- `Range` header만 추가하고 기존 sequential writable에 append
+- weak ETag나 file name/lastModified를 representation identity로 사용
+- serialized incremental hash state를 검증 없이 checkpoint
+- `200` response를 기존 partial 뒤에 append
+- `416`을 곧바로 success로 해석
+- Service Worker keepalive를 cross-browser background 보장으로 간주
+- picker 미지원 대용량 파일을 unbounded Blob으로 fallback
+- OPFS staging을 사용자 파일 저장 완료로 표시
+- browser-managed handoff를 application-verified save로 표시
+- user-agent 문자열 기반 Safari 분기
+
+## 20. 참고
+
+- [Browser data capability completion ledger](../browser-data-capability-completion-ledger.md)
+- [VD-16 Browser transfer composition과 Image delivery](./VD-16-browser-transfer-composition-and-image-delivery.md)
+- [Browser transfer recovery](../../operations/browser-transfer-recovery.md)
+- [RFC 9110 HTTP Semantics](https://www.rfc-editor.org/rfc/rfc9110.html)
+- [Fetch Standard](https://fetch.spec.whatwg.org/)
+- [File System Standard](https://fs.spec.whatwg.org/)
+- [Service Workers](https://w3c.github.io/ServiceWorker/)
+- [Background Fetch draft](https://wicg.github.io/background-fetch/)
+- [기존 transfer 설계](../presigned-transfer-and-image-cdn.md)
+- [browser file/origin storage 설계](../browser-file-and-origin-storage.md)