문제 워커를 싣는 빌드에서 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
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).
- journal에
PREPARING또는FILES_READYrow가 남아 있는지 확인한다. 남아 있다면 staging bytes가 아직 존재할 수 있다는 뜻이다. 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_RECONCILEDEGRADED/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 잔여).
- journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할 근거가 사라지고 quota만 누수된다.
- 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분
- 영향 release, browser family/version, capability와 최초 발생 시각을 확인한다.
- user dismissal과 실제 failure를 분리한다.
- safe metric의
failure_kind,phase,strategy,backend,size_bucket,release_id만으로 범위를 좁힌다. - integrity mismatch, authorization/cache classification breach, committed user-data corruption이면 신규 write/cache activation을 즉시 중지한다.
- kill switch를 가장 좁은 범위로 적용한다.
- current와 N-1 release의 schema/cache compatibility를 확인한다.
- 복구 전후 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 전환 정체
확인 순서
- 사용자가 실제 취소한 flow가 error로 집계되지 않았는지 확인한다.
- user activation 전에 비동기 작업이 추가됐는지 확인한다.
- native input fallback이 Chromium/Firefox/WebKit에서 동작하는지 확인한다.
- count, per-file, total bytes, MIME/extension/signature policy version을 확인한다.
raw policy가 port caller에서 들어오지 않고 composition registry의 정확한
FilePolicyReferenceidentity로 resolve되는지, verification receipt가 같은 profile/file snapshot에 binding됐는지 확인한다. 같은policyKey/intention을 가진 새 객체는 거절되어야 한다. - File/OPFS/Cache/download byte source가 chunk마다 closed Result를 반환하고 첫 failure에서 consumer와 producer 모두 종료되는지 확인한다.
- 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의 별도 절차를 따른다. - whole-buffer API 또는 object URL lease 누수가 배포됐는지 확인한다.
- image preview를 설치했다면 object URL 발급 전에 header dimensions, pixel, decoded-byte와 animation/static-only 제한을 검사하는 VD-15 probe가 실제 조합됐는지 확인한다. 현재 byte/signature 검사만으로 decode safety를 주장하지 않는다.
- 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가
BLOCKEDfailure여도 runtime status는CLOSED / NOT_OPENED
- live attempt가 기다리는 동안 status는
versionchange뒤 connection이 남음- repeated reload/update loop
- open/maintenance의
POLICY_REJECTED: immutable dataset binding missing/mismatch - open의
UNSUPPORTED/ONLINE_ONLY와 statusINCOMPATIBLE: 더 새 release가 schema를 올린 DB를 이전 bundle이 열었다(05-06). migration 실패가 아니므로 §5로 가지 않는다. 이 bundle은 그 dataset을 읽지도 쓰지도 않고 online-only로 동작하며, 새 release로 reload하면 풀린다 (indexeddb-runtime.tsopen의VersionError분기). OPFS journal도 같은 답을 낸다(indexeddb-opfs-journal.tstranslateFor)
확인 순서
- target schema와 current/future schema, release ID를 확인한다.
- registry-issued
authorityToken,namespaceToken,partitionToken이 같은 dataset의 승인된 값인지 확인한다. readable namespace/account/business ID를 token이나 physical DB name에 넣지 않는다. - physical DB name이 세 opaque token에서만 파생됐는지, caller
databaseNameAssertion이 exact match인지 확인한다. - governance store의 immutable scope + full
BrowserStoragePolicybinding을 versionchange, post-open, maintenance 모두에서 확인한다. raw token이나 binding 내용을 incident log에 복사하지 않는다. - old tab, worker 또는 test/debug context가 connection을 닫지 않는지 확인한다.
- 모든 connection에
versionchange/forced-close handler가 설치됐는지 확인한다. - BroadcastChannel prepare hint는 참고만 하고 실제 open/connection registry를 확인한다.
- 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 failureCORRUPT_DATA,NOT_READABLE, forced closeRETENTION_SWEEP(INDEXEDDB_WRITE)과pruneExpiredReceipts(INDEXEDDB_MIGRATE)의CORRUPT_DATA관측은 실패가 아니다. 손상 행을 지우지 않고 건너뛴 수이고, 나머지 정상 행은 정리된다(05-05,indexeddb-runtime.tspurgeEligibleRecords,indexeddb-maintenance.tspruneExpiredReceipts). 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 없이 중단
확인 순서
- DDL schema version과 record codec version을 구분한다.
- migration ID, last safe keyset checkpoint, revision fence,
budgetExhausted, processed/remaining bucket과 old-writer drain proof를 확인한다. - caller budget과 구현 absolute budget(500 rows/30,000ms), async operation 사이 deadline check를 확인한다.
- codec
measureStoredBytes, retention sidecarmeasuredBytes,dataset-budget.usedBytes/receiptCount가 CAS/remove/lifecycle/migration transaction과 함께 갱신됐는지 확인한다. 이 값은 native physical size가 아니다. - actual
StoredRecord가key/codecVersion/revision/payload만 포함하고writtenAtEpochMs, synchronization,measuredBytes,eligibleAtEpochMs는retentionStoresidecar에 분리돼 있는지 확인한다. - receipt retention이 31일 이하인지, configured
maxIdempotencyReceipts가 1,000,000 이하인지, prune/purge가 receipt count를 같은 transaction에서 감소시켰는지 확인한다. - TTL record가 sweep 전 read에서
EXPIRED_RESOURCE, query에서 skip되는지,UNTIL_SYNCED는CONFIRMED만 eligible한지 확인한다. - lifecycle action마다 composition의
authorizeLifecycle(action, scope, frozen policy)가 호출됐고 opaque proof가 검증 후 비영속·비관측 상태로 폐기됐는지 확인한다. - historical schema fixture에서 같은 migration을 재현한다.
- reconstructable, synced copy, unsynced/user-authored 분류를 확인한다.
- partial batch가 row/sidecar/budget/checkpoint와 원자적으로 rollback됐는지 확인한다.
- full partition purge가 record/retention/idempotency와 등록된 모든
lifecycleMetadataStores를 bounded transaction으로 정리하고 immutable governance binding은 유지하는지 확인한다. - 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.tsdeleteUnadmittedDataset). - 범위: 세 opaque token에서 만든 그 partition의 DB 이름 하나
(
indexeddb-governance.tsindexedDbPhysicalDatabaseName). 다른 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
확인 순서
estimate()가 rough origin total임을 전제로 IndexedDB/OPFS/Cache 공동 증가를 확인한다.- exact free space를 계산하거나 예약했다고 가정하지 않는다.
- expired/reconstructable, synced copy, user-authored 사용량 bucket을 분리한다.
- IndexedDB의 exact logical dataset budget과 origin-wide
estimate()를 구분한다. 전자는 codec measurement + conservative reservation이고 native physical usage/free space가 아니다. - private mode, WebView, browser storage policy와 user clear 여부를 확인한다.
- 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으로 실행한다.
- 신규 speculative/reconstructable write admission 중지
- incomplete candidate와 stale staging 제거
- expired reconstructable record/object 제거
- grace가 지난 unreferenced immutable chunk 제거
- inactive public cache release 제거
- authoritative revision/sync receipt가 확인된 synced copy compact
- unsynced/user-authored sync/export UI
- 필요하면 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-possibleambiguity 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.tspreparePut,opfs-policy.ts). OPFS 쓰기는 origin 전체에서 한 번에 하나라서, 이 bound가 없으면 멈춘 source 하나가 모든 tab의 쓰기를mutationLockWaitTimeoutMs뒤BLOCKED로 만든다 - sensitive policy maintenance의
POLICY_REJECTED, proof replay/expiry 또는 authority provider/consumer unavailable
확인 순서
- mutation Web Lock owner와 timeout을 확인한다.
- worker protocol/version과 모든 sync handle의
finally close를 확인한다. - journal operation phase별 count와 age bucket을 확인한다.
- 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 조건으로 적용하지 않는다. - journal의 physical scope binding과 logical namespace binding이 둘 다 존재하고, 같은 scope/policy fingerprint를 가리키는지 확인한다. 한쪽만 없거나 mismatch면 자동 재생성하지 않는다.
- runtime/byte-store composition의 frozen scope와 policy namespace가 일치하는지 확인한다.
LOGOUT,UNTIL_SYNCED,ACCOUNT_DELETIONmaintenance에는 composition의requestMaintenanceAuthorityprovider와consumeMaintenanceAuthorityconsumer가 둘 다 주입됐는지 확인한다. application request에는 proof 필드가 없어야 한다.- provider가 exact reason/frozen scope/frozen policy에 묶인 새 proof와 최대 5분 expiry를 발급하고, consumer가 같은 binding을 원자적으로 검증·consume해 replay를 거절하는지 확인한다. proof/token/raw scope는 log에 복사하지 않는다.
- physical path/ID/digest를 log에 복사하지 않고 reconciliation tool이 manifest schema와 digest를 검증하게 한다.
- logical row가 commit authority인지 확인한다.
- 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.tsreconcileTransaction,opfs-worker-runtime.tscleanupTransactionLocked)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_DELETIONpurge는 객체를 하나씩 지운 뒤, 마지막 객체까지 돌았으면 늘 아래 partition 삭제로 끝낸다(1103/05-01 잔여,opfs-byte-store-adapter.tsenforcePolicies). 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).
- 예전 동작: 객체를 다 돈 뒤 journal row를 한 번 세고, 0이면 chunk를 grace 없이
sweep해
- 승인된
LOGOUT/ACCOUNT_DELETIONpurge의 partition 삭제([0929] 05-01, 2026-11-03 05-01, 1103/05-01 잔여,opfs-byte-store-adapter.tsenforcePolicies).- 조건: 정책이 그 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.tswithPartitionLock). 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도 그만큼 늦게 끝난다.
- 조건: 정책이 그 reason을 허용하고, authority가 이번 purge의 proof를 내주고
consumer가 소비했을 때(IndexedDB의 database 전체 삭제와 같은 승인). 그리고
다음 중 하나일 때: 마지막 객체까지 돌았다, 목록에서 건너뛴 손상 object row,
손상 row 때문에
- 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
확인 순서
- hosting/CDN cache와 browser Cache Storage를 별개로 확인한다.
- active/candidate/previous release ID와 manifest digest를 확인한다.
- candidate 모든 entry의 status,
expectedContentType, size, integrity 검증 marker를 확인한다. canonical manifest digest가 정규화된 Content-Type까지 binding하는지 확인한다. - 실제 response의 정규화된
Content-Type과 manifestexpectedContentType이 정확히 일치하는지 확인한다. body digest가 맞아도 type mismatch candidate는 폐기한다. - config/release manifest/auth/API가 network-only인지 확인한다.
- query/Vary exact match와
ignoreSearch/ignoreVary미사용을 확인한다. - Service Worker를 별도 선택했다면 old controlled clients와 current waiting/active worker 상태를 확인한다.
- Service Worker를 별도 선택했다면 unregister만 하고 owned cache cleanup을 빠뜨리지 않았는지 확인한다.
- cleanup caller가 cache name, release registry ID 또는 retain list를 제출할 수 없고 보존 집합이 verified active pointer와 composition retention에서만 계산되는지 확인한다.
- 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.tsresolveRuntimeCapabilities,service-worker-page-controller.tsstart()의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-headerslive 모드가/service-worker.js를 요청해 이 헤더와 redirect를 확인하고, 다르면 FAIL이다(config/hosting/cache-policy.jsonserviceWorker,scripts/verify-hosting-headers.ts). fixture 모드는 선언끼리만 대조하므로UNVERIFIED다. 하위 경로 base URL은 live probe가 아직 받지 않는다 (scripts/lib/hosting-probe.tsclassifyLiveHostingBaseUrl, 리뷰 0929/13-06). 그때는 이 헤더를 손으로 확인한다. - 새 워커는 install에서
skipWaiting()하지 않고 waiting에 머문다 (service-worker-entry.ts). 활성화는 두 경로로 일어난다: 페이지의requestActivation()이 성공하거나, 그 scope의 탭이 모두 닫힌다(브라우저 기본 동작). 새로고침만으로는 활성화되지 않는다. 템플릿에는requestActivation()을 부르는 화면이 없으므로 기본 경로는 뒤쪽이다. 따라서 결함 있는 워커가 waiting에 있으면 탭을 모두 닫았다 다시 연 사용자부터 그 워커를 쓴다. 기다리지 말고 다음 release로 교체하거나REMOVE_REGISTRATIONrelease를 배포한다. - 활성화를 기다리는 동안 소유 캐시는 release 수만큼 쌓인다. 캐시를 지우는 곳은
activate 하나이고, 현재 캐시와 마커가 가장 높은 직전 캐시 1개만 남긴다
(
service-worker-lifecycle.tsonActivate). 새 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.tsInstalledServiceWorkerSelection). 소유 캐시는PURGE_OWNED_RESOURCESrelease의 page controller가 지운다(service-worker-removal.tspurgeOwnedResources). old controlled client가 drain되기 전에는 이 release를 배포하지 않는다. 캐시가 사라지면 그 탭의 워커는 요청을 네트워크로 넘기고(service-worker-entry.tsfetch 리스너의cached ?? fetch(request)), 서버에 없는 옛 청크는 404가 된다. - 자기 해제
service-worker.js를 내보내는 것은REMOVE_REGISTRATIONrelease뿐이다 (scripts/build-frontend.ts).PURGE_OWNED_RESOURCESrelease에는 워커 파일이 없다. 페이지가 부팅하면 page controller가 unregister를 다시 하지만, 부팅을 막는 워커는 걷어내지 못한다.nullrelease는 아무것도 하지 않아 옛 워커가 계속 등록·제어한다(리뷰 1103 실험 L3:ACTIVE다음 바로null, update 검사는 404로 실패). 그래서REMOVE_REGISTRATIONrelease는 제품이 지원하는 최대 미방문 기간 이상 유지한 뒤 다음 단계로 넘어간다. 그 뒤에 옛 워커가 남은 사용자가 보이면REMOVE_REGISTRATIONrelease를 다시 배포한다(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로 해석하지 않는다.