Files
clean-architecture-frontend…/docs/operations/browser-file-storage-recovery.md
T
DongHyeonka 2a78169c58 fix(hosting): live probe가 redirect된 워커 스크립트를 거절한다
문제
워커를 싣는 빌드에서 live probe는 `/service-worker.js`를 기본 fetcher
`redirect: "follow"`로 받고, 최종 응답의 status와 origin만 본다
(`scripts/lib/hosting-probe.ts` `probeLiveRelease`). 같은 origin 안
redirect 뒤에 200·`no-cache`·JS MIME이 오면 FE-GATE-019가 PASS다.
브라우저는 워커 스크립트를 redirect mode "error"로 받는다(Service
Worker Update 알고리즘). 그런 호스트에서는 첫 등록, update 검사,
`REMOVE_REGISTRATION` kill switch가 모두 실패한다.

고른 방법과 버린 대안
- `serviceWorker` surface에만 `redirect` 행을 더한다.
  `response.redirected`이거나 `opaqueredirect`이면 FAIL이다. 자산
  probe(1105/06-02)와 같은 판정식이라 fetcher가 redirect를 따라가든
  manual이든 잡는다. 3xx 응답은 지금처럼 `http-status` 행이 FAIL로 본다.
- redirect가 없으면 이 행은 PASS로 남는다. 산출물에 이 검사를 했다는
  기록이 된다.
- 버린 대안: 모든 surface에서 redirect를 FAIL로 보기(리뷰 (b)).
  `index`·`appRoute`의 정상 redirect(끝 슬래시 정규화 등)까지 막는다.
  문서에만 적기(리뷰 (c))는 게이트가 그대로 PASS다.
- 운영 문서 두 곳에 "redirect 없이"를 적었다. release-cache-rollback.md의
  live probe 설명과 browser-file-storage-recovery.md의 kill switch
  전제다.

위험·한계
- 워커 스크립트를 redirect하던 호스트는 이제 FE-GATE-019에서 FAIL이다.
  그런 호스트에서는 지금도 워커가 동작하지 않는다.
- 브라우저 거절은 명세와 Chromium 오류 문구에 기댄 것이다. redirect하는
  호스트로 실제 등록을 돌려 보지 않았고, live 모드도 실제 호스트로 돌리지
  않았다(리뷰 §5 미검증 그대로).

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/hosting-probe.test.ts
- RED: "live hosting probe (1105/06-02) > fails a worker script the host
  answers only after a same-origin redirect"가 실패한다. 옛 probe에는
  redirect 행이 없어 실패 행이 비어 있다.
- 함께: check:types, lint, verify:documentation

Refs: 1106/06-01
2026-11-06 05:17:04 +09:00

45 KiB

Browser file and storage recovery runbook

이 runbook은 VD-11 capability를 실제 프로젝트에서 선택한 뒤 사용하는 production 운영 template이다. 현재 skeleton에는 native reference runtime이 AVAILABLE_NOT_COMPOSED로 존재하지만 제품 dataset과 bootstrap에는 연결되지 않았으므로 이 문서 자체가 현재 서비스 incident procedure를 활성화하지 않는다. 설치 branch는 owner, dashboard, alert threshold, kill-switch key, backend/storage 연락처와 evidence 위치를 채워야 한다.

VD-15가 설계한 origin-wide pressure/GC coordinator, OPFS/Cache forward migration, OPFS real readiness preflight, bounded Cache cleanup과 preview decode probe는 현재 DESIGNED_NOT_IMPLEMENTED다. 아래 절차에서 이 기능을 전제로 한 자동 조치는 해당 runtime이 구현·조합된 제품에서만 실행한다. 현재 reference primitive를 coordinator 완료 증거로 사용하지 않는다.

OPFS 보상 실패와 reconcile (STO-01)

put()이 commit 전에 실패하면 coordinator가 그 transaction의 staging을 지우고 journal row를 되돌린다(보상). 보상의 worker cleanup이나 journal rollback이 끝나지 않으면 put은 자기 실패 코드(QUOTA_EXCEEDED, ABORTED 등)와 operation OBJECT_WRITE를 그대로 두고 recovery만 RECONCILE로 바꿔 반환한다. journal row(PREPARING/FILES_READY)는 남는다(opfs-byte-store-adapter.ts compensatePreparedPut, Q-6.5-9). 이는 결함이 아니라 설계된 상태다. worker가 cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답한다. 별도의 "결과 불명" 값은 없다(05-09).

  1. journal에 PREPARING 또는 FILES_READY row가 남아 있는지 확인한다. 남아 있다면 staging bytes가 아직 존재할 수 있다는 뜻이다.
  2. maintenance.reconcile()을 실행한다. reconcile은 exact physical generation token만 삭제한다. report에서 다음을 본다.
    • skippedLiveTransactions: 어느 tab에서든 아직 진행 중인 put/delete의 row다. reconcile은 transaction별 Web Lock을 ifAvailable로 잡지 못한 row를 건드리지 않는다(05-01, reconcile의 holdTransactionLock). 결함이 아니다.
    • failedTransactions: 이번에 정리하지 못해 journal에 남긴 row 수다. 나머지 row와 orphan GC는 계속 돈다(05-02). 같은 row가 계속 실패하면 §7을 본다.
    • corruptTransactions: 읽을 수 없어 건너뛴 journal row 수다. 0이 아니면 저장소 손상이다. 예전에는 이런 row 하나가 목록 전체를 실패시켜 authority의 모든 partition에서 reconcile과 GC가 멈췄다. 이제 나머지 row와 orphan GC는 계속 돌고, 관측은 OBJECT_RECONCILE DEGRADED / CORRUPT_DATA로 남는다 ([0929] 05-01). reconcile은 그 row를 지우지 않는다. 그 partition이 승인된 purge로 통째로 지워질 때 함께 지워지는 것은 partition 키(logicalKey)를 읽을 수 있는 row뿐이다(§7). 승인된 LOGOUT/ACCOUNT_DELETION purge는 객체를 끝까지 돌면 늘 그 partition을 지운다(1103/05-01 잔여).
    • unattributedCorruptTransactions: 위 수 가운데 logicalKey까지 읽을 수 없는 row 수다. 어느 partition에도 속하지 않아 partition 삭제도 지우지 못한다. 그래서 따로 세고 DEGRADED 관측에서 뺀다(2026-11-03 05-03). 예전에는 이런 row 하나가 reconcile마다 DEGRADED를 남겨 경보가 늘 켜졌다. 같은 수로 남아 있으면 할 일이 없다. 수가 늘면 키 없는 row를 쓴 writer(다른 release, 외부 도구)를 찾는다. 이 row도 수동으로 지우지 않는다(3번). 그 row의 staging은 partition 디렉터리 안에 있어 승인된 purge가 그 partition을 지울 때 함께 지워진다. 예전에는 purge가 이 row를 세지 못해 chunk sweep으로 끝났고, staging receipt가 지킨 chunk·manifest가 COMPLETED 뒤에도 남았다(1103/05-01 잔여).
  3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할 근거가 사라지고 quota만 누수된다.
  4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지 않는다. rollback은 새 v2 write admission을 닫고 v1+v2 reader를 유지하는 것으로 수행한다. runtime이 스스로 통째로 지우는 것은 승인된 LOGOUT/ACCOUNT_DELETION purge의 그 partition 디렉터리 하나와 그 partition의 journal row뿐이다(§7).

1. 공통 원칙

incident 중에도 다음 작업은 금지한다.

  • 자동 또는 일괄 deleteDatabase()
    • 예외는 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된 governance 때문에 dataset을 열 수 없을 때, runtime이 그 partition의 DB 하나만 지운다(§5 "database 전체 삭제" 참고).
  • origin의 모든 caches.keys() 삭제
  • user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge
    • OPFS의 예외도 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된 row나 staging, 또는 그 partition의 끝나지 않은 put·delete 때문에 끝나지 못할 때, runtime이 그 partition 디렉터리 하나와 그 partition의 journal row만 지운다(§7 recovery).
  • schema version downgrade
  • 무한 reload/update loop
  • filename, path, record/object key, URL/query, digest, body를 incident log에 복사
  • fake/unavailable adapter로 바꾸고 정상 복구로 선언

공통 안전한 degrade 순서는 다음과 같다.

선택 capability의 신규 write/activation 중지
  -> 진행 중 operation 정리
  -> read-only
  -> online-only/network-only
  -> authoritative server re-read

read-only나 online-only가 사용자 작성 내용을 잃게 한다면 먼저 export/sync 경로를 제공하고 UI에 명시적으로 알린다.

2. 최초 10분

  1. 영향 release, browser family/version, capability와 최초 발생 시각을 확인한다.
  2. user dismissal과 실제 failure를 분리한다.
  3. safe metric의 failure_kind, phase, strategy, backend, size_bucket, release_id만으로 범위를 좁힌다.
  4. integrity mismatch, authorization/cache classification breach, committed user-data corruption이면 신규 write/cache activation을 즉시 중지한다.
  5. kill switch를 가장 좁은 범위로 적용한다.
  6. current와 N-1 release의 schema/cache compatibility를 확인한다.
  7. 복구 전후 diagnostic count와 browser smoke evidence를 저장한다.

심각도 시작점:

상황 시작 심각도
authorization 우회, private/auth response cache, content integrity mismatch P1
committed user-authored data unreadable/corrupt, widespread migration failure P1
upload/download 실패 급증, IndexedDB blocked 증가, OPFS reconstructable loss P2
enhanced picker만 실패하고 baseline 정상 P3

실제 조직 severity policy가 있으면 그 정책이 우선한다.

3. File/picker/download와 별도 upload example

신호

  • PERMISSION_DENIED, NOT_READABLE, INTEGRITY_FAILED
  • closed byte stream이 failure chunk 뒤 추가 byte를 내보내거나 raw exception을 throw
  • browser handoff는 정상인데 confirmed save가 감소
  • large download에서 memory/stall failure
  • 별도 backend upload를 설치한 feature만 session expiry/conflict, quarantined/available 전환 정체

확인 순서

  1. 사용자가 실제 취소한 flow가 error로 집계되지 않았는지 확인한다.
  2. user activation 전에 비동기 작업이 추가됐는지 확인한다.
  3. native input fallback이 Chromium/Firefox/WebKit에서 동작하는지 확인한다.
  4. count, per-file, total bytes, MIME/extension/signature policy version을 확인한다. raw policy가 port caller에서 들어오지 않고 composition registry의 정확한 FilePolicyReference identity로 resolve되는지, verification receipt가 같은 profile/file snapshot에 binding됐는지 확인한다. 같은 policyKey/intention을 가진 새 객체는 거절되어야 한다.
  5. File/OPFS/Cache/download byte source가 chunk마다 closed Result를 반환하고 첫 failure에서 consumer와 producer 모두 종료되는지 확인한다.
  6. download Content-Type, Content-Disposition, CORS exposed header와 short-lived capability expiry를 확인한다. browser-managed resolver receipt가 caller의 branded receipt와 정확히 같고 resource ID, media type, safe extension, server max, optional digest와 expiry를 synchronous하게 정확히 binding하는지 확인한다. 현재 save path는 whole-object foreground streaming이며 Range resume가 아니다. partial destination에 append하지 않고, Range를 선택한 제품은 VD-14와 browser-transfer runbook의 별도 절차를 따른다.
  7. whole-buffer API 또는 object URL lease 누수가 배포됐는지 확인한다.
  8. image preview를 설치했다면 object URL 발급 전에 header dimensions, pixel, decoded-byte와 animation/static-only 제한을 검사하는 VD-15 probe가 실제 조합됐는지 확인한다. 현재 byte/signature 검사만으로 decode safety를 주장하지 않는다.
  9. upload를 별도 설치했다면 backend 401/403/409/413/415/422/429/5xx, CORS/preflight, session TTL/clock skew, part checksum, idempotency, orphan cleanup과 quarantine queue를 그 feature runbook에서 확인한다.

안전한 조치

  • enhanced open/save picker off → native input/direct authorized download
  • active-content preview off
  • preview pixel/decode/frame probe가 없거나 실패하면 object URL preview off
  • client-generated large download off → server-side artifact generation
  • broken stream adapter off → bounded fallback 또는 operation 중지; raw exception을 성공/EOF로 변환하지 않음
  • upload를 별도 설치했다면 multipart concurrency/part size 하향, resumable off → approved hard cap의 simple upload, 문제 MIME 임시 차단
  • expired upload session은 authorization 후 새 session; 기존 session을 재활성화하지 않음

성공 판정:

  • user cancellation 제외 file/download start 대비 success rate 회복
  • integrity/authorization mismatch 0
  • 세 browser baseline smoke 통과
  • object URL/file ref cleanup count 0 leak
  • preview를 설치한 경우 malformed/oversize/animated image가 object URL 발급 전에 거절되고 native decode resource 0 leak
  • upload를 별도 설치했다면 orphan session/quarantine backlog SLO와 session cleanup 0 leak

4. IndexedDB upgrade blocked/versionchange

신호

  • BLOCKED, UPGRADE_BLOCKED 또는 blocked duration bucket 증가
    • live attempt가 기다리는 동안 status는 BLOCKED
    • blocked deadline settle 뒤에는 open result가 BLOCKED failure여도 runtime status는 CLOSED / NOT_OPENED
  • versionchange 뒤 connection이 남음
  • repeated reload/update loop
  • open/maintenance의 POLICY_REJECTED: immutable dataset binding missing/mismatch
  • open의 UNSUPPORTED / ONLINE_ONLY와 status INCOMPATIBLE: 더 새 release가 schema를 올린 DB를 이전 bundle이 열었다(05-06). migration 실패가 아니므로 §5로 가지 않는다. 이 bundle은 그 dataset을 읽지도 쓰지도 않고 online-only로 동작하며, 새 release로 reload하면 풀린다 (indexeddb-runtime.ts open의 VersionError 분기). OPFS journal도 같은 답을 낸다(indexeddb-opfs-journal.ts translateFor)

확인 순서

  1. target schema와 current/future schema, release ID를 확인한다.
  2. registry-issued authorityToken, namespaceToken, partitionToken이 같은 dataset의 승인된 값인지 확인한다. readable namespace/account/business ID를 token이나 physical DB name에 넣지 않는다.
  3. physical DB name이 세 opaque token에서만 파생됐는지, caller databaseNameAssertion이 exact match인지 확인한다.
  4. governance store의 immutable scope + full BrowserStoragePolicy binding을 versionchange, post-open, maintenance 모두에서 확인한다. raw token이나 binding 내용을 incident log에 복사하지 않는다.
  5. old tab, worker 또는 test/debug context가 connection을 닫지 않는지 확인한다.
  6. 모든 connection에 versionchange/forced-close handler가 설치됐는지 확인한다.
  7. BroadcastChannel prepare hint는 참고만 하고 실제 open/connection registry를 확인한다.
  8. N-1 bundle이 future schema를 INCOMPATIBLE / ONLINE_ONLY로 처리하는지 확인한다. reference runtime은 read-only가 아니라 online-only로 닫는다.

안전한 조치

  • 신규 offline write와 background migration 중지
  • 사용자에게 다른 tab close와 명시적 retry UI 제공
  • current connection을 draining 후 close
  • upgrade release rollout 중지 또는 compatible N-1 online-only로 rollback
  • binding mismatch를 caller DB 이름 변경, policy 덮어쓰기 또는 DB 전체 삭제로 우회하지 않고 registry/composition 오류를 forward fix

remote tab 강제 종료, database 삭제, 무한 reload는 금지한다.

성공 판정:

  • connection registry와 blocked request 0
  • fresh tab과 two-tab versionchange/blocked smoke 통과
  • future schema에서 N-1이 destructive write 없이 기동
  • open과 maintenance에서 동일 scope/policy binding 검증 통과

5. IndexedDB migration/corruption

신호

  • MIGRATION_FAILED, unknown codec, schema postcondition failure
  • CORRUPT_DATA, NOT_READABLE, forced close
    • RETENTION_SWEEP(INDEXEDDB_WRITE)과 pruneExpiredReceipts (INDEXEDDB_MIGRATE)의 CORRUPT_DATA 관측은 실패가 아니다. 손상 행을 지우지 않고 건너뛴 수이고, 나머지 정상 행은 정리된다(05-05, indexeddb-runtime.ts purgeEligibleRecords, indexeddb-maintenance.ts pruneExpiredReceipts). budget이 삭제 bytes나 receipt 수를 감당하지 못하면 그 값은 내리지 않고 둔다
  • transaction request success 후 commit failure
  • LIMIT_EXCEEDED: dataset logical byte/receipt budget 초과
  • lifecycle batch가 proof 없이 실행되거나 TTL/UNTIL_SYNCED record가 잘못 노출·삭제
  • migration/lifecycle batch가 500 rows 또는 30,000ms를 넘거나 checkpoint 없이 중단

확인 순서

  1. DDL schema version과 record codec version을 구분한다.
  2. migration ID, last safe keyset checkpoint, revision fence, budgetExhausted, processed/remaining bucket과 old-writer drain proof를 확인한다.
  3. caller budget과 구현 absolute budget(500 rows/30,000ms), async operation 사이 deadline check를 확인한다.
  4. codec measureStoredBytes, retention sidecar measuredBytes, dataset-budget.usedBytes/receiptCount가 CAS/remove/lifecycle/migration transaction과 함께 갱신됐는지 확인한다. 이 값은 native physical size가 아니다.
  5. actual StoredRecord가 key/codecVersion/revision/payload만 포함하고 writtenAtEpochMs, synchronization, measuredBytes, eligibleAtEpochMs는 retentionStore sidecar에 분리돼 있는지 확인한다.
  6. receipt retention이 31일 이하인지, configured maxIdempotencyReceipts가 1,000,000 이하인지, prune/purge가 receipt count를 같은 transaction에서 감소시켰는지 확인한다.
  7. TTL record가 sweep 전 read에서 EXPIRED_RESOURCE, query에서 skip되는지, UNTIL_SYNCED는 CONFIRMED만 eligible한지 확인한다.
  8. lifecycle action마다 composition의 authorizeLifecycle(action, scope, frozen policy)가 호출됐고 opaque proof가 검증 후 비영속·비관측 상태로 폐기됐는지 확인한다.
  9. historical schema fixture에서 같은 migration을 재현한다.
  10. reconstructable, synced copy, unsynced/user-authored 분류를 확인한다.
  11. partial batch가 row/sidecar/budget/checkpoint와 원자적으로 rollback됐는지 확인한다.
  12. full partition purge가 record/retention/idempotency와 등록된 모든 lifecycleMetadataStores를 bounded transaction으로 정리하고 immutable governance binding은 유지하는지 확인한다.
  13. raw record, opaque scope/proof를 ticket/log에 복사하지 않고 승인된 local recovery tooling만 사용한다.

안전한 조치

  • migration 중지, repository read-only/online-only
  • reconstructable만 purge/re-fetch
  • synced copy는 revision 확인 후 rehydrate
  • unsynced/user-authored는 quarantine marker + export/sync/recovery
  • adapter bounded reopen 최대 한 번
  • schema/codec compatible fix를 새 forward migration으로 배포
  • migration은 old-writer drain authority를 복구한 뒤 더 작은 bounded batch로 checkpoint부터 resume
  • lifecycle authority가 불명확하면 deletion을 재시도하지 않고 read-only; proof를 운영자가 수동 생성·재사용하지 않음

database 전체 삭제는 data owner가 export/recovery와 영향 scope를 승인한 별도 action이다. runtime이 스스로 DB를 지우는 경우는 하나뿐이다(05-03).

  • 조건: enforceLifecycleBatch의 action이 LOGOUT 또는 ACCOUNT_DELETION이고, authorizeLifecycle이 proof를 내준 뒤, open이 POLICY_REJECTED 또는 CORRUPT_DATA로 실패했을 때(budget/binding 행 손상, 바뀐 policy). 행 단위 purge는 open이 필요해서 이 상태에서는 영영 돌 수 없다 (src/adapters/storage/indexeddb/indexeddb-runtime.ts deleteUnadmittedDataset).
  • 범위: 세 opaque token에서 만든 그 partition의 DB 이름 하나 (indexeddb-governance.ts indexedDbPhysicalDatabaseName). 다른 partition과 origin의 다른 DB는 건드리지 않는다.
  • 결과: 지워지면 receipt COMPLETE와 datasetDeleted: true(행 수는 세지 않는다). 다른 context가 연결을 닫지 않아 blocked deadline이 지나면 BLOCKED / RELOAD_OTHER_CONTEXTS를 반환한다. 이때 삭제 요청은 브라우저에 살아 있어 나중에 적용될 수 있으므로 다른 tab을 닫고 같은 purge를 다시 호출한다.
  • governance가 정상이면 지금처럼 행 단위 purge만 하고 DB는 지우지 않는다.

성공 판정:

  • historical fixture의 fresh, interrupted, resume, replay가 모두 통과
  • corrupted user-authored row 자동 삭제 0
  • migration canary failure 0
  • N-1 rollback/read-only smoke 통과
  • dataset budget/sidecar/receipt count 재검증과 bounded lifecycle fixture 통과

6. Origin quota, persistence denial, storage eviction

신호

  • usage ratio pressure bucket 증가
  • QUOTA_EXCEEDED, STORAGE_EVICTED
  • startup sentinel과 logical manifest 불일치
  • persistence request denied

확인 순서

  1. estimate()가 rough origin total임을 전제로 IndexedDB/OPFS/Cache 공동 증가를 확인한다.
  2. exact free space를 계산하거나 예약했다고 가정하지 않는다.
  3. expired/reconstructable, synced copy, user-authored 사용량 bucket을 분리한다.
  4. IndexedDB의 exact logical dataset budget과 origin-wide estimate()를 구분한다. 전자는 codec measurement + conservative reservation이고 native physical usage/free space가 아니다.
  5. private mode, WebView, browser storage policy와 user clear 여부를 확인한다.
  6. persistence denial을 capability failure가 아닌 best-effort outcome으로 처리했는지 확인한다.

안전한 조치

현재 공통 coordinator가 없으면 다음 순서를 자동 실행하거나 “exact one retry”를 보장한다고 기록하지 않는다. 제품 owner가 store별 primitive와 retention policy를 확인해 수동/feature-local로 안전하게 수행하거나 write를 read-only/online-only로 닫는다. VD-15 coordinator가 조합된 경우에만 동일 mutation owner 안에서 다음을 bounded orchestration으로 실행한다.

  1. 신규 speculative/reconstructable write admission 중지
  2. incomplete candidate와 stale staging 제거
  3. expired reconstructable record/object 제거
  4. grace가 지난 unreferenced immutable chunk 제거
  5. inactive public cache release 제거
  6. authoritative revision/sync receipt가 확인된 synced copy compact
  7. unsynced/user-authored sync/export UI
  8. 필요하면 offline read-only/online-only

각 GC invocation은 기본 100 items/5초, 구현 절대 상한 500 items/30초와 opaque cursor를 지킨다. failed write의 자동 retry는 다음 조건이 모두 맞을 때만 정확히 한 번 허용한다.

  • 첫 write가 실제 quota failure로 원자적 rollback됨
  • 같은 idempotency key, revision fence와 payload digest
  • 외부 side effect/cross-store publish가 commit되지 않음
  • bounded GC가 실제 candidate를 제거했거나 pressure가 내려감
  • 현재 revision/generation 재확인과 새 admission token 발급

두 번째 failure나 effect certainty가 unknown이면 retry하지 않는다.

persist()를 boot나 반복 loop에서 요청하지 않는다. 사용자가 durable offline 기능을 선택하고 unsynced data 보호 이유를 이해하는 동작에서만 요청한다.

성공 판정:

  • coordinator를 설치한 경우 pressure가 hysteresis lower bound 아래
  • partial logical/physical marker mismatch는 rehydrate 또는 explicit read-only/export-required로 닫힘
  • 모든 local marker가 소실된 경우 backend opaque installation epoch로 authorization 후 구분하거나 storage-reset-possible ambiguity UX를 표시함; 이를 “첫 설치로 판별 완료”라고 기록하지 않음
  • user-authored 자동 purge 0
  • storage clear 뒤 reconstructable rehydrate/explicit degraded UI 통과

7. OPFS partial write/corruption/worker crash

현재 capability/property probe와 native conformance test는 존재하지만 composition readiness에서 worker/lock/journal/small write-read-delete-cleanup을 한 번에 검증하는 real preflight는 아직 없다. preflight success를 운영 전제에 넣으려면 VD-15 목표 runtime을 먼저 구현한다.

신호

  • journal이 PREPARING/FILES_READY에 오래 머묾
  • committed logical row와 physical manifest/file 불일치
  • digest/length mismatch
  • worker crash, handle lock timeout, NoModificationAllowedError
  • put의 retryable NOT_READABLE: source가 putIdleTimeoutMs(기본 2분) 동안 다음 bytes를 주지 않아 put을 끝내고 origin mutation lock을 풀었다(05-07, opfs-worker-client.ts preparePut, opfs-policy.ts). OPFS 쓰기는 origin 전체에서 한 번에 하나라서, 이 bound가 없으면 멈춘 source 하나가 모든 tab의 쓰기를 mutationLockWaitTimeoutMs 뒤 BLOCKED로 만든다
  • sensitive policy maintenance의 POLICY_REJECTED, proof replay/expiry 또는 authority provider/consumer unavailable

확인 순서

  1. mutation Web Lock owner와 timeout을 확인한다.
  2. worker protocol/version과 모든 sync handle의 finally close를 확인한다.
  3. journal operation phase별 count와 age bucket을 확인한다.
  4. VD-15 forward migrator를 설치하지 않은 현재 v1 reference runtime에서는 physical layout이 /ca-frontend-opfs-v1/authorities/<authorityToken>/<namespaceToken>/<partitionToken>/ 아래의 objects, chunks/sha256, staging인지 확인한다. readable namespace, filename, account ID가 path segment이면 신규 write를 중지한다. migrator를 설치한 조합에는 이 v1 path를 authoritative target 조건으로 적용하지 않는다.
  5. journal의 physical scope binding과 logical namespace binding이 둘 다 존재하고, 같은 scope/policy fingerprint를 가리키는지 확인한다. 한쪽만 없거나 mismatch면 자동 재생성하지 않는다.
  6. runtime/byte-store composition의 frozen scope와 policy namespace가 일치하는지 확인한다.
  7. LOGOUT, UNTIL_SYNCED, ACCOUNT_DELETION maintenance에는 composition의 requestMaintenanceAuthority provider와 consumeMaintenanceAuthority consumer가 둘 다 주입됐는지 확인한다. application request에는 proof 필드가 없어야 한다.
  8. provider가 exact reason/frozen scope/frozen policy에 묶인 새 proof와 최대 5분 expiry를 발급하고, consumer가 같은 binding을 원자적으로 검증·consume해 replay를 거절하는지 확인한다. proof/token/raw scope는 log에 복사하지 않는다.
  9. physical path/ID/digest를 log에 복사하지 않고 reconciliation tool이 manifest schema와 digest를 검증하게 한다.
  10. logical row가 commit authority인지 확인한다.
  11. VD-15 forward migrator를 설치했다면 source/target physical layout와 journal version, migration checkpoint, copy-on-write generation, publish authority, rollback window와 N-1 reader 결과를 확인한다.

recovery

  • PREPARING: reconcile은 resume하지 않는다. staging receipt가 가리키는 그 transaction의 physical generation과 staging을 지우고 journal row를 rollback한다. receipt가 없거나 0바이트면(첫 receipt 쓰기가 quota나 crash로 끝나지 못함) 지울 generation이 없으므로 staging만 지운다(05-02). 읽을 수 없는 receipt는 지우지 않고 그 row를 failedTransactions로 남긴다 (opfs-byte-store-adapter.ts reconcileTransaction, opfs-worker-runtime.ts cleanupTransactionLocked)
  • FILES_READY: worker가 manifest와 모든 chunk digest를 다시 검증한다. 맞으면 logical commit 뒤 finalize한다. 맞지 않으면 quarantine하지 않고 그 generation과 staging을 지운 뒤 rollback한다. 지워지는 것은 commit 전 staging뿐이다
  • COMMITTED + file missing/corrupt: reconstructable만 server rehydrate; user-created private는 read-only/export/recovery
  • stale staging/orphan chunk는 grace period와 bounded mark/sweep 후 제거
  • LOGOUT/ACCOUNT_DELETION purge는 객체를 하나씩 지운 뒤, 마지막 객체까지 돌았으면 늘 아래 partition 삭제로 끝낸다(1103/05-01 잔여, opfs-byte-store-adapter.ts enforcePolicies). chunk sweep으로 끝내지 않는다.
    • 예전 동작: 객체를 다 돈 뒤 journal row를 한 번 세고, 0이면 chunk를 grace 없이 sweep해 chunkSweep: "COMPLETED"를 돌려줬다(05-04, 2026-11-03 05-01). 목록과 세기는 각각 한 순간만 본다. 그래서 두 경우에 bytes가 남은 채 COMPLETED였다. ① 다른 tab이 새 객체를 put하는 중이고 partition에 객체가 3개 이상이면, 그 put이 목록 뒤에 commit하고 세기 전에 끝났다. 목록에도 row 수에도 없어 sweep이 그 chunk를 건너뛰었고, 그 파일이 계정 삭제 뒤에도 읽혔다(메모리 20/20, Chromium 6/6). ② 멈춘 put의 journal row가 logicalKey를 잃으면 세지 못했고, 그 staging receipt·chunk·manifest가 purge마다 남았다.
    • 이제 결과: 그 partition의 bytes가 지워진 것은 report에 partitionDeleted가 있을 때다. chunkSweep은 더 이상 채우지 않는다(port 타입에는 호환을 위해 남겼다).
    • 예산(budgetMs·maxObjects)이나 다른 tab의 변경 때문에 객체를 끝까지 돌지 못하면 report는 moreObjectsAvailable: true이고 partitionDeleted가 없다. 같은 purge를 다시 호출한다([0929] 05-02). 다만 이때 그 partition의 journal row(다른 tab에서 진행 중인 put·delete, crash가 남긴 PREPARING·FILES_READY, 키는 읽히는 손상 row)가 하나라도 있으면 그 호출이 바로 partition을 지운다 (2026-11-03 05-01).
  • 승인된 LOGOUT/ACCOUNT_DELETION purge의 partition 삭제([0929] 05-01, 2026-11-03 05-01, 1103/05-01 잔여, opfs-byte-store-adapter.ts enforcePolicies).
    • 조건: 정책이 그 reason을 허용하고, authority가 이번 purge의 proof를 내주고 consumer가 소비했을 때(IndexedDB의 database 전체 삭제와 같은 승인). 그리고 다음 중 하나일 때: 마지막 객체까지 돌았다, 목록에서 건너뛴 손상 object row, 손상 row 때문에 CORRUPT_DATA로 끝난 remove, 끝까지 돌지 못한 호출에서 그 partition 키를 가진 journal row(countPartitionTransactions가 1 이상). TTL·SESSION_END·UNTIL_SYNCED·PRESSURE는 손상 row를 건너뛰고 세기만 한다.
    • 범위: worker가 origin mutation lease를 쥔 채 authorities/<authorityToken>/<namespaceToken>/<partitionToken> 디렉터리를 지우고, 이어서 journal에서 그 partition 키로 시작하는 object·journal·chunk reference row와 budget row를 지운다. 값을 읽지 않고 키로 찾으므로 키가 남은 손상 row도 지워진다. journal row는 logicalKey 인덱스로 찾으므로 그 값까지 깨진 row는 남는다(§0 2번 unattributedCorruptTransactions). scope binding row는 남긴다. 다른 partition은 건드리지 않는다.
    • 결과: partitionDeleted: true, moreObjectsAvailable: false, 건너뛴 row 수 corruptObjects. 이 report면 그 partition의 bytes는 모두 지워진 것이다. removedObjects·releasedBytes는 삭제 전에 하나씩 지운 객체만 센다. 디렉터리는 지웠는데 journal 정리가 실패하면 실패를 반환한다. 같은 purge를 다시 호출하면 이어서 끝난다.
    • 다른 tab의 put·delete와의 순서: 모든 put·delete는 journal begin부터 끝날 때까지 partition lock(Web Lock <mutationLockName>:partition:<authorityToken>:<namespaceToken>:<partitionToken>)을 shared로 쥐고, partition 삭제는 디렉터리·journal 두 단계를 그 lock을 exclusive로 쥔 채 한다. 그래서 진행 중이던 put은 삭제 전에 끝나고 삭제가 그 결과까지 지운다. 삭제가 기다리는 동안 새로 온 put은 삭제 뒤에 돈다 ([0929] 05-01, opfs-byte-store-adapter.ts withPartitionLock). origin lease는 put의 BEGINFINISH만 막으므로 이 lock이 없을 때는, 삭제의 디렉터리 단계가 다른 tab put의 BEGIN보다 먼저 끝나면 그 put이 새 디렉터리에 파일을 쓰고 journal 단계가 그 row를 지워 파일을 치울 주체가 없었다(commit 전이면 manifest·staging receipt·chunk, commit 뒤면 manifest·chunk가 남음). 삭제 전체가 put의 FINISHcommit 사이에 들어가는 경우는 그때도 put이 CONFLICT로 실패하고 bytes가 남지 않았다. 막는 테스트: tests/unit/opfs-worker-runtime.test.ts "leaves no partition bytes when an approved purge meets another tab's put parked before …"(5가지 순서).
    • 한계: 삭제는 진행 중인 put·delete를 기다린다. source가 멈춘 put은 put idle bound(05-07)까지 삭제를 붙잡는다. purge의 signal을 abort하면 기다림을 멈추고 ABORTED를 반환한다. 삭제 뒤에 줄 선 put·delete도 자기 signal로 기다림을 멈춘다. 어느 쪽이든 partition lock 기다림은 mutationLockWaitTimeoutMs(기본 10분)에서 BLOCKED(retryable)로 끝난다 (2026-11-03 05-02). 삭제가 lock을 요청한 뒤 온 put의 데이터는 남는다 (point-in-time). 그 전에 시작한 put은 삭제가 기다렸다가 함께 지운다. 모든 승인 purge가 이제 이 lock을 기다리므로, 다른 tab에서 오래 걸리는 put이 있으면 purge도 그만큼 늦게 끝난다.
  • lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only
  • scope binding mismatch면 affected scope를 read-only로 격리하고 registry/ composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지
  • sensitive maintenance authority provider/consumer가 없거나 replay/expiry 검증이 실패하면 삭제를 재시도하지 않고 read-only로 전환한다. 운영자가 proof를 직접 생성·주입·재사용하지 않는다.
  • forward migration 중단이면 target generation을 publish하지 않고 bounded checkpoint에서 resume한다. publish 뒤에는 source generation을 rollback window까지 보존하고, N-1이 target을 이해하지 못하면 read-only/online-only로 닫는다. source/target을 in-place 혼합하거나 layout version을 내리지 않는다.

committed object를 sync handle로 in-place repair하지 않는다. 새 generation에 정상 object를 만들고 generation CAS로 logical pointer를 전환한다.

성공 판정:

  • unresolved old journal 0
  • committed read integrity failure 0
  • worker/handle registry 0 leak
  • 각 journal phase fault injection과 concurrent put/delete/GC 통과
  • sensitive maintenance의 fresh proof consume 성공, replay/expired/mismatched proof와 provider/consumer 누락은 모두 deletion 전 fail-closed

8. Cache Storage/Service Worker stale or poisoned release

public static Cache release runtime은 존재하지만 cursor/count/deadline이 있는 bounded inspect/cleanup은 아직 없다. Service Worker의 waiting/client-drain 활성화는 page controller의 requestActivation() 핸드셰이크로 구현돼 있다 (src/adapters/service-worker/service-worker-page-controller.ts). 템플릿에는 이를 부르는 화면이 없다. Service Worker는 제품이 static selection (src/features/product-capabilities.ts)을 ACTIVE로 바꾼 경우에만 아래 worker 절차를 적용한다.

신호

  • incomplete candidate activation
  • integrity/type/size mismatch
  • auth/private/no-store/opaque policy rejection
  • Service Worker를 별도 선택한 조합의 stale worker/update/reload loop
  • active asset miss 또는 offline boot failure

확인 순서

  1. hosting/CDN cache와 browser Cache Storage를 별개로 확인한다.
  2. active/candidate/previous release ID와 manifest digest를 확인한다.
  3. candidate 모든 entry의 status, expectedContentType, size, integrity 검증 marker를 확인한다. canonical manifest digest가 정규화된 Content-Type까지 binding하는지 확인한다.
  4. 실제 response의 정규화된 Content-Type과 manifest expectedContentType이 정확히 일치하는지 확인한다. body digest가 맞아도 type mismatch candidate는 폐기한다.
  5. config/release manifest/auth/API가 network-only인지 확인한다.
  6. query/Vary exact match와 ignoreSearch/ignoreVary 미사용을 확인한다.
  7. Service Worker를 별도 선택했다면 old controlled clients와 current waiting/active worker 상태를 확인한다.
  8. Service Worker를 별도 선택했다면 unregister만 하고 owned cache cleanup을 빠뜨리지 않았는지 확인한다.
  9. cleanup caller가 cache name, release registry ID 또는 retain list를 제출할 수 없고 보존 집합이 verified active pointer와 composition retention에서만 계산되는지 확인한다.
  10. active pointer/release marker control JSON이 정확히 2 MiB(2,097,152 bytes) cap의 stream reader와 strict UTF-8/runtime schema를 통과하며 oversized body를 초과 지점에서 cancel하는지 확인한다.

안전한 조치

static Cache-only 조합:

  • 신규 candidate activation/cache write 중지
  • verified current 또는 previous release로 explicit rollback
  • incomplete candidate와 runtime-public cache부터 owned-prefix cleanup
  • 현재 cleanup/inspect가 cache 개수에 대해 unbounded임을 고려해 incident invocation을 추가 budget으로 반복 실행하지 않는다. VD-15 bounded cursor runtime 구현 전에는 큰 namespace를 자동 sweep하지 않는다.

Service Worker를 별도 선택한 조합에서만 추가. 워커의 fetch 가로채기만 끄는 스위치는 없다. 끄는 경로는 아래 둘이다.

  • 페이지가 부팅하면: runtime config에 CAPABILITY_OVERRIDES.SERVICE_WORKER: "DISABLED"를 넣는다. 재빌드는 필요 없다. 사본을 고쳐 검사한 뒤 바꾸는 절차는 docs/runbooks/FE-RB-001.md에 있다. 다음 부팅 때 page controller가 scope와 script가 정확히 일치하는 등록만 unregister하고, 새 등록은 하지 않는다 (src/contracts/runtime-capabilities.ts resolveRuntimeCapabilities, service-worker-page-controller.ts start()의 disabledCleanup 분기). 소유 캐시는 지우지 않는다. unregister는 이미 열린 탭의 제어를 끊지 않으므로, 그 탭은 닫히거나 다시 load될 때까지 현재 워커를 쓴다.
  • 워커 때문에 페이지가 부팅하지 못하면: static selection을 { mode: "REMOVE_REGISTRATION", scriptPath: "service-worker.js" }로 바꾼 release를 배포한다. 이 release는 같은 URL에 자기 해제 service-worker.js를 낸다 (scripts/build-frontend.ts, scripts/lib/self-unregistering-service-worker.ts). 페이지 코드가 돌지 않아도 브라우저 update 검사(내비게이션 때, 등록은 updateViaCache: "none")가 이 파일을 받아 설치한다. 설치 즉시 skipWaiting()하고, 활성화 때 registration.unregister()한다. fetch handler가 없어서 그동안의 요청은 모두 네트워크로 간다. 다음 load부터는 제어받지 않는다. 브라우저 확인: tests/e2e/service-worker-recovery.spec.ts.
  • 이 경로가 동작하려면 service-worker.js를 Cache-Control: no-cache로, redirect 없이 서빙해야 한다. 브라우저는 워커 스크립트의 redirect를 같은 origin 안이라도 거절한다. 워커를 싣는 빌드(ACTIVE·REMOVE_REGISTRATION)에서는 verify:hosting-headers live 모드가 /service-worker.js를 요청해 이 헤더와 redirect를 확인하고, 다르면 FAIL이다(config/hosting/cache-policy.json serviceWorker, scripts/verify-hosting-headers.ts). fixture 모드는 선언끼리만 대조하므로 UNVERIFIED다. 하위 경로 base URL은 live probe가 아직 받지 않는다 (scripts/lib/hosting-probe.ts classifyLiveHostingBaseUrl, 리뷰 0929/13-06). 그때는 이 헤더를 손으로 확인한다.
  • 새 워커는 install에서 skipWaiting()하지 않고 waiting에 머문다 (service-worker-entry.ts). 활성화는 두 경로로 일어난다: 페이지의 requestActivation()이 성공하거나, 그 scope의 탭이 모두 닫힌다(브라우저 기본 동작). 새로고침만으로는 활성화되지 않는다. 템플릿에는 requestActivation()을 부르는 화면이 없으므로 기본 경로는 뒤쪽이다. 따라서 결함 있는 워커가 waiting에 있으면 탭을 모두 닫았다 다시 연 사용자부터 그 워커를 쓴다. 기다리지 말고 다음 release로 교체하거나 REMOVE_REGISTRATION release를 배포한다.
  • 활성화를 기다리는 동안 소유 캐시는 release 수만큼 쌓인다. 캐시를 지우는 곳은 activate 하나이고, 현재 캐시와 마커가 가장 높은 직전 캐시 1개만 남긴다 (service-worker-lifecycle.ts onActivate). 새 release가 waiting 워커를 밀어내도 밀려난 워커의 후보 캐시는 지우지 않는다. 예: 탭 하나를 연 채 A 활성 상태에서 B, C를 받으면 소유 캐시는 A·B·C 3개다. 탭을 모두 닫아 C가 활성화되면 C·A 2개로 줄어든다(리뷰 1103/06-04 실험 L2, chromium·webkit). 캐시 하나는 사전 캐시 크기(상한 5 MiB, src/contracts/service-worker.ts)다. origin 쿼터에 닿으면 다음 install이 QUOTA_EXCEEDED로 실패하고, 저장소가 부족하면 브라우저가 origin 저장소 전체(IndexedDB·OPFS 포함)를 지울 수 있다. 사용자가 탭을 오래 열어 두고 release가 잦은 제품은 requestActivation()을 부르는 화면을 붙여 waiting 기간을 줄인다. install이 밀려난 캐시를 지우지 않는 이유: install하는 워커는 활성 워커의 캐시 이름을 모르고, 마커 쓰기에 실패한 활성 캐시는 마커가 없어 후보와 구별되지 않는다.
  • 제거는 ACTIVE → REMOVE_REGISTRATION → PURGE_OWNED_RESOURCES → null 순서로 release를 나눈다(src/contracts/service-worker.ts InstalledServiceWorkerSelection). 소유 캐시는 PURGE_OWNED_RESOURCES release의 page controller가 지운다(service-worker-removal.ts purgeOwnedResources). old controlled client가 drain되기 전에는 이 release를 배포하지 않는다. 캐시가 사라지면 그 탭의 워커는 요청을 네트워크로 넘기고(service-worker-entry.ts fetch 리스너의 cached ?? fetch(request)), 서버에 없는 옛 청크는 404가 된다.
  • 자기 해제 service-worker.js를 내보내는 것은 REMOVE_REGISTRATION release뿐이다 (scripts/build-frontend.ts). PURGE_OWNED_RESOURCES release에는 워커 파일이 없다. 페이지가 부팅하면 page controller가 unregister를 다시 하지만, 부팅을 막는 워커는 걷어내지 못한다. null release는 아무것도 하지 않아 옛 워커가 계속 등록·제어한다(리뷰 1103 실험 L3: ACTIVE 다음 바로 null, update 검사는 404로 실패). 그래서 REMOVE_REGISTRATION release는 제품이 지원하는 최대 미방문 기간 이상 유지한 뒤 다음 단계로 넘어간다. 그 뒤에 옛 워커가 남은 사용자가 보이면 REMOVE_REGISTRATION release를 다시 배포한다(0929/06-06).

hosting/CDN purge는 두 branch와 분리된 provider 절차로 실행한다.

auth/private response가 cache에 실제 저장됐을 가능성이 있으면 P1로 승격하고 owned affected namespace를 정확히 식별해 제거한다. origin의 unrelated cache는 삭제하지 않는다.

성공 판정:

  • static Cache-only 조합은 verified active/previous release와 candidate cleanup이 일관되고 network-only fallback smoke를 통과
  • Service Worker를 별도 선택한 조합만 clean/old controlled client가 같은 verified release로 수렴하고 online/offline/update/rollback smoke를 통과
  • auth/private cache entry 0
  • update/reload loop 0
  • config/release manifest network-only header contract 통과

9. Drill evidence

실제 capability를 project catalog의 INSTALLED로 바꾸기 전에 최소 다음 drill을 실행하고 release-specific evidence를 저장한다. 이 legacy selection label은 primary status COMPOSED와 별도 TrafficAdmission/RuntimeHealth/PromotionEvidence 축이 준비된 제품 상태를 뜻하며 새로운 primary status literal이 아니다. 각 축의 literal과 contract/provider/browser/operations component gate에서 PromotionEvidence를 계산하는 규칙은 completion ledger를 그대로 따른다.

drill 필수 증적
별도 upload workflow를 설치한 경우 session abort/expiry/checksum orphan cleanup, quarantine state, retry/idempotency
large save abort/integrity partial commit 0, memory high-water
IndexedDB two-tab upgrade blocked close/retry UX, connection leak 0
IndexedDB governance/lifecycle opaque scope binding, logical budget/TTL, proof discard, receipt cap
interrupted historical migration old-writer drain proof, 500 rows/30s budget, checkpoint resume, atomicity, N-1 fallback
quota/persistence denied/storage clear reconstructable GC, user data 보존, degraded UI
VD-15 coordinator를 설치한 경우 pressure/one-retry hysteresis, bounded cursor/deadline, store priority와 retry 최대 1회
OPFS journal phase crash/scope mismatch/maintenance authority bidirectional binding, actual opaque layout, invisible partial object, reconcile summary, integrity, provider/consumer one-time proof
OPFS preflight/migration을 설치한 경우 worker/lock/journal/small operation cleanup, interrupted copy-on-write와 N-1 fallback
cache candidate poison/update rollback expectedContentType binding, active release 불변, previous rollback, caller retain 부재, 2 MiB control cap, auth rejection
bounded Cache/SW lifecycle을 설치한 경우 cursor/count/deadline, waiting activation, controlled-client drain과 network-only rollback
preview probe를 설치한 경우 pixel/decoded-byte/static-only rejection, timeout와 decode resource cleanup

evidence에는 raw 사용자 data를 포함하지 않는다. 허용 metadata는 release/build, browser engine/version, fixture ID, fault phase, bounded counts/buckets와 PASS/FAIL 결과뿐이다.

promotion 직전에는 다음 repository evidence도 함께 보존한다.

  • test:browser-capabilities가 만든 JUnit에서 Chromium, Firefox, WebKit이 source suite의 동일 testcase set을 실제 실행하고 failure/error/skipped가 모두 0이어야 한다. 구체적인 case 수는 이 runbook에 복제하지 않는다. verify:browser-capability-evidence가 Chromium을 baseline으로 testcase set과 engine 집합을 동적으로 검증한다. native capability가 없는 engine도 testcase를 skip하지 않고 adapter의 명시적 UNSUPPORTED/degraded 결과를 검증해야 한다. 세 engine 중 하나라도 실행되지 않은 artifact는 promotion 가능 상태가 아니다.
  • artifacts/quality/vite-module-inventory.json에서 optional runtime source root가 production chunk에 없음을 check:optional-recipes로 검증한다.
  • check:browser-file-storage-boundaries로 native API 경계 위반을 막고, test:browser-file-storage-removal로 runtime과 전용 gate를 제거한 격리 copy가 base typecheck/lint/architecture/test/build/catalog/CI contract를 통과함을 검증한다.
  • catalog의 referenceRuntime.status는 AVAILABLE_NOT_COMPOSED, productionComposition은 false로 유지한다. dataset owner가 모든 policy와 evidence를 승인하고 실제 composition을 추가하기 전에는 INSTALLED로 해석하지 않는다.

10. 관련 문서