Commit Graph
12 Commits
Author SHA1 Message Date
DongHyeonka d13a393600 fix(storage): 계정 삭제 purge가 끝나지 않은 put을 보면 partition을 지운다
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
  그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
  commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
  그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.

고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.

위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
  쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
  되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
  지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
  남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
  does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
  0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
  바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
  일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
  손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
  tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
  1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
  3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
2026-11-04 20:29:34 +09:00
DongHyeonka 72edb55475 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
2026-11-03 01:23:05 +09:00
donghyeon-kaandClaude Opus 5.5 49413af045 fix(types): turn on noUnusedLocals and drop the unused declarations (12-12)
VD-01 decision 3 hands unused diagnostics to tsc and turns off ESLint's
no-unused-vars for TS files, but tsconfig.base.json never enabled the
tsc check (D-19). The flag found 46 unused imports, types and helpers
across 22 files; none of them were read, so removing them changes no
behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:32:33 +09:00
DongHyeonkaandClaude Opus 5.5 4d8ceade21 fix(storage): match the OPFS runbook to the adapter and drop the dead EFFECT_UNKNOWN branch (05-09)
The runbook named failure codes the adapter stopped using and promised a
resume and a quarantine reconcile never does. It now states the put's own
code with RECONCILE, the skipped and failed row counts, and what reconcile
really does per phase. The worker never sent EFFECT_UNKNOWN and the client
refused it, so the cleanup effect type and its two adapter branches go.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:44:51 +09:00
DongHyeonkaandClaude Opus 5.5 47cf040586 fix(storage): treat an empty OPFS receipt as none and keep reconcile going past a failed row (05-02)
A first receipt write that hit the quota left a zero-byte receipt.json that
cleanup and orphan GC could not parse, so reconcile and GC for the whole
authority stopped for good. An empty receipt now counts as no receipt, and
reconcile counts a failed row, observes it and moves on to the rest and GC.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:12:33 +09:00
DongHyeonkaandClaude Opus 5.5 8fc816ee25 fix(storage): hold a per-transaction lock so reconcile skips a live OPFS put (05-01)
Reconcile cleaned up any incomplete journal row, including a put still
running in another tab, and the put then reported success for deleted files.
Put and delete now hold a Web Lock per transaction from begin to return;
reconcile takes those locks with ifAvailable, re-reads the page under them
and reports the rows it skipped (D-3).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:09:30 +09:00
DongHyeonkaandClaude Opus 5.5 510cd80a5c fix(storage): keep a put's own failure code when compensation fails (Q-6.5-9)
When a put failed before commit and the compensating ABORT_PUT or the
journal rollback did not complete, the coordinator returned a generic
CONFLICT / OBJECT_RECONCILE (or the rollback's own code). A user cancel or
a full disk reached the caller as a bare conflict.

compensatePreparedPut now takes the put's failure and returns it. If the
compensation completes, the failure is returned as before. If it does not,
the journal row is still left for reconciliation, and the failure keeps its
code, operation and retryable flag; only recovery becomes RECONCILE. The
architecture doc's compensation rule says the same.

Verified: new tests in tests/unit/opfs-byte-store.test.ts were RED (5
cases: failed cleanup, unknown cleanup effect, caller cancel, failed
rollback, FILES_READY failure) and are GREEN; the successful-compensation
case pins the unchanged path. All gates pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:30:26 +09:00
DongHyeonkaandClaude Opus 5.5 d758934e9c fix(storage): page orphan GC candidates by digest cursor (R-5.1)
LIST_ORPHAN_CANDIDATES returned at most 100 old chunks in directory order,
committed ones included, and had no way to continue. Once more than 100
day-old committed chunks existed, every reconcile got the same referenced
page, deleted nothing and reported DEADLINE_REACHED; real orphans behind it
leaked quota forever.

The request now takes an optional afterDigest cursor. The worker walks
prefix directories and chunk names in ascending digest order and returns
only digests after the cursor. The coordinator pages on with the last
digest of each page until no more are available or its deadline hits.
The gateway method gets the cursor as a new trailing optional parameter.
Deletion safety checks (journal reference, staging receipts, grace period)
are unchanged.

Verified: new test "R-5.1 orphan GC pages past referenced chunks" wires the
real worker runtime, client gateway and coordinator. Before the fix it
failed with inspected 100, deleted 0, DEADLINE_REACHED; now both orphans
(lowest and highest digest) are deleted and all 150 referenced chunks
remain. The existing listOrphanCandidates call-arity assertion now expects
the extra undefined cursor argument.
Gates: check:architecture, check:types:app/test/web-worker, lint,
test:component pass; test:unit passes except removal-fixture.test.ts,
which needs gitignored release artifacts absent from a fresh worktree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 12:27:48 +09:00
DongHyeonkaandClaude Opus 5 632b230c82 fix: report OPFS completion honestly and bound public cache staging
A durable write whose journal transaction could not be completed returned
plain success with `SUCCEEDED` telemetry. The payload was committed but
the transaction stayed `COMMITTED`, so the reconcile backlog and its quota
pressure grew while every caller was told the write had settled. That is
now a `RECONCILE` failure with the effect certainty preserved, and an
unfinished delete is observed `DEGRADED` rather than clean.

The worker seam lost causes in both directions. A bootstrap failure
answered every request with kind `CAPABILITIES`, so the gateway read a
kind mismatch and replaced the real `BLOCKED` or `QUOTA_EXCEEDED` with a
generic `UNSUPPORTED`; the envelope's correlation is now captured once at
the listener. On the client, the pending row and its timer were released
before the reply was decoded, so a trap that threw inside the decoder left
the public promise pending with nothing left to time it out, and a
throwing `requestId` getter produced a timeout instead of a prompt
protocol failure.

Public cache staging handed its signal to each `Request` and called that
ownership. A fetch that ignored it held the mutation lock forever, and a
digest that finished after the abort still wrote both the asset and the
activation marker — publishing a release nobody was waiting for. One
terminal owner now covers the whole staging body and every await
re-checks it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 01:25:26 +09:00
DongHyeonkaandClaude Opus 5 6a8281a941 fix: make OPFS finalization and public cache repair failure-atomic
STO-RR-01. finalizePut re-acquired the origin mutation lease it was already
holding. A Web Lock is not reentrant, so an ordinary PUT stopped for good at
FINALIZE; it now calls the locked cleanup directly. A strict non-reentrant fake
lease manager pins one acquire and one release per finalization. The adapter no
longer reports a failed finalization as a plain write success either: the
journal row stays COMMITTED for reconciliation, but the caller is told the
write did not settle.

STO-RR-02. A failure raised while serving a validated request now carries that
request's kind. Defaulting every catch to CAPABILITIES made the client's own
expected-kind check reject genuine quota, integrity and abort failures as
protocol breaches and report them as UNSUPPORTED. Only an envelope the runtime
could not read still answers at protocol level.

STO-RR-03. The worker client decodes a response instead of adopting it: exact
own-data descriptors, the negotiated protocol version, the exact awaited kind,
a code inside the closed BrowserDataFailure set and a boolean retryable. An
accessor, a proxy trap, an inherited or extra field and an unknown code all
close the call as UNSUPPORTED rather than leaving it to time out.

STO-RR-04. A marker read that fails transiently is unknown, not damaged, so it
no longer deletes the candidate that may be serving traffic. Only a confirmed
corrupt or missing marker enters the repair path.

STO-RR-05. Staging never deletes a candidate it did not create. A repair
replaces exact entries in place, so a failed fetch leaves every healthy asset
and the active release usable; a candidate this call created is still removed
on failure.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 14:00:41 +09:00
DongHyeonkaandClaude Opus 5 618da9abf5 fix: preserve OPFS recovery authority during cleanup
Repair the compensating half of the OPFS put saga.

The coordinator now owns a single abortPreparedPut() driven by a
composition-owned bounded signal instead of the caller's already aborted one,
and the worker client no longer issues a duplicate fire-and-forget abort.
Journal rows and budget reservations are released only after the physical
effect is confirmed CLEANED or ALREADY_CLEAN; a timeout, malformed response or
EFFECT_UNKNOWN keeps PREPARING/FILES_READY and returns OBJECT_RECONCILE.

New writes carry a transaction-unique physicalGenerationId through the staging
receipt, manifest path and prepared object, so a late compensation deletes only
its own transaction's directory even when a newer transaction legitimately
reuses the same logical generation. v1 paths, receipts and prepared objects stay
readable through the rollback window.

Abort and cleanup hold the origin mutation lease through physical deletion and
staging removal. A transaction that never reached staging returns ALREADY_CLEAN
without waiting for the lease, which would otherwise deadlock against the BEGIN
it is cancelling.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 23:21:58 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00