fix(storage): 손상 행을 건너뛰고 끝나지 못한 삭제는 partition을 지운다 (0929/05-01)

문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
  하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
  reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.

고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
   않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
   페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
   0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
   object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
   `STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
   - 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
     통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
     (0929 05-03)와 같은 조건이다.
   - 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
     쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
   - 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
     object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
     손상 행도 지워진다. scope binding 행은 남긴다.
   - 보고: `partitionDeleted: true`, `corruptObjects`,
     `moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
     실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.

위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
  `corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
  쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
  report에는 `corruptTransactions`(필수)와 `corruptObjects`·
  `partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
  partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
  것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
  `STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
  partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
  초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.

검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
  `listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
  function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
  `CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
  디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
  177 files 2,523건 통과, `tests/contract` 41건 통과.
  `tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
  eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
  `check:architecture`(pnpm 필요), Playwright OPFS spec.

Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
This commit is contained in:
DongHyeonka
2026-11-03 01:23:05 +09:00
parent c4052f0f8e
commit 72edb55475
10 changed files with 592 additions and 48 deletions
@@ -34,11 +34,18 @@ cleanup 결과를 확인하지 못하면 성공 값이 아니라 실패로 답
않는다(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를 지우지 않는다. 그 row가 속한
partition이 승인된 purge로 통째로 지워질 때만 함께 지워진다(§7).
3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할
근거가 사라지고 quota만 누수된다.
4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지
않는다. rollback은 새 v2 write admission을 닫고 v1+v2 reader를 유지하는 것으로
수행한다.
수행한다. runtime이 스스로 지우는 것은 승인된 purge가 손상 때문에 끝나지 못할
때의 그 partition 디렉터리 하나와 그 partition의 journal row뿐이다(§7).
## 1. 공통 원칙
@@ -50,6 +57,9 @@ incident 중에도 다음 작업은 금지한다.
하나만 지운다(§5 "database 전체 삭제" 참고).
- origin의 모든 `caches.keys()` 삭제
- user-authored/unsynced IndexedDB 또는 OPFS data 자동 purge
- OPFS의 예외도 하나다. authority가 승인한 LOGOUT/ACCOUNT_DELETION이 손상된
journal row나 staging 때문에 끝나지 못할 때, runtime이 그 partition
디렉터리 하나와 그 partition의 journal row만 지운다(§7 recovery).
- schema version downgrade
- 무한 reload/update loop
- filename, path, record/object key, URL/query, digest, body를 incident log에 복사
@@ -436,6 +446,28 @@ VD-15 목표 runtime을 먼저 구현한다.
처리한다. 다른 탭이 바꾸고 있던 객체를 지우지 못하면 report는
`moreObjectsAvailable: true`이고 `chunkSweep`이 없다. 이때도 같은 purge를 다시
호출한다([0929] 05-02)
- 손상 때문에 끝나지 못하는 `LOGOUT`/`ACCOUNT_DELETION` purge는 partition을
통째로 지운다([0929] 05-01, `opfs-byte-store-adapter.ts` `enforcePolicies`).
- 조건: 정책이 그 reason을 허용하고, authority가 이번 purge의 proof를 내주고
consumer가 소비했을 때(IndexedDB의 database 전체 삭제와 같은 승인). 그리고
다음 중 하나를 만났을 때: 목록에서 건너뛴 손상 object row, 손상 row 때문에
`CORRUPT_DATA`로 끝난 remove나 chunk sweep, `STAGING_STATE_UNREADABLE`.
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도
지워진다. scope binding row는 남긴다. 다른 partition은 건드리지 않는다.
- 결과: `partitionDeleted: true`, `moreObjectsAvailable: false`, 건너뛴 row 수
`corruptObjects`. 이 report면 그 partition의 bytes는 모두 지워진 것이다.
`chunkSweep`은 없다. 디렉터리는 지웠는데 journal 정리가 실패하면 실패를
반환한다. 같은 purge를 다시 호출하면 이어서 끝난다.
- 한계: lease는 put의 streaming 구간(BEGIN~FINISH)만 막는다. 그 밖에 있던 다른
tab의 같은 partition put은 journal row가 지워져 다음 journal 단계에서
fencing 검사에 걸려 실패할 것으로 본다. 이 경합은 실행으로 확인하지 않았다.
purge가 시작된 뒤 새로 시작한 put의 데이터는 다른 purge처럼 남는다
(point-in-time). purge 전에 그 partition의 쓰기를 멈추는 것이 composition의
몫이다.
- lock/worker 문제면 OPFS write off → approved capped fallback 또는 online-only
- scope binding mismatch면 affected scope를 read-only로 격리하고 registry/
composition을 forward fix; 다른 token path로 bytes를 이동하거나 추측 복구 금지