diff --git a/docs/architecture/browser-file-and-origin-storage.md b/docs/architecture/browser-file-and-origin-storage.md index 8389839f..45e72674 100644 --- a/docs/architecture/browser-file-and-origin-storage.md +++ b/docs/architecture/browser-file-and-origin-storage.md @@ -759,7 +759,7 @@ CLEANED -> journal 제거 - journal row와 budget reservation은 physical cleanup effect가 `CLEANED` 또는 `ALREADY_CLEAN`으로 확인된 뒤에만 해제한다. timeout, crash, - malformed response, `EFFECT_UNKNOWN`은 성공이 아니며 `PREPARING`/`FILES_READY`를 + malformed response, worker cleanup 실패는 성공이 아니며 `PREPARING`/`FILES_READY`를 그대로 남긴다. 이때 put은 자기 실패 코드(취소면 `ABORTED`, 쿼터 초과면 `QUOTA_EXCEEDED` 등)를 그대로 반환하고 recovery만 `RECONCILE`로 바꾼다 (Q-6.5-9). journal rollback이 실패해도 같다. diff --git a/docs/operations/browser-file-storage-recovery.md b/docs/operations/browser-file-storage-recovery.md index 36367cff..b2e8d014 100644 --- a/docs/operations/browser-file-storage-recovery.md +++ b/docs/operations/browser-file-storage-recovery.md @@ -16,15 +16,24 @@ primitive를 coordinator 완료 증거로 사용하지 않는다. ## OPFS 보상 실패와 reconcile (STO-01) -`put()`이 실패했는데 보상 cleanup effect가 확인되지 않으면 runtime은 실패를 -`OBJECT_RECONCILE` / `CONFLICT`(recovery `RETRY`)로 보고하고 journal row를 남긴다. -이는 결함이 아니라 설계된 상태다. +`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만 삭제하고, effect가 여전히 `EFFECT_UNKNOWN`이면 journal을 - 유지한 채 다시 `OBJECT_RECONCILE`을 반환한다. +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을 본다. 3. journal row를 수동으로 삭제하지 않는다. row가 사라지면 stale staging을 추적할 근거가 사라지고 quota만 누수된다. 4. OPFS root나 journal database를 통째로 삭제하거나 schema를 downgrade하지 @@ -406,9 +415,16 @@ VD-15 목표 runtime을 먼저 구현한다. ### recovery -- `PREPARING`: partial staging 검증 후 idempotent resume 또는 purge -- `FILES_READY`: expected generation/digest 일치 시 logical commit, 아니면 - quarantine +- `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 후 제거 diff --git a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts index fa803da7..2390325a 100644 --- a/src/adapters/storage/opfs/opfs-byte-store-adapter.ts +++ b/src/adapters/storage/opfs/opfs-byte-store-adapter.ts @@ -1052,7 +1052,7 @@ export function createOpfsByteStoreAdapter( * The journal row and its budget reservation are the only durable evidence * that a physical staging generation may still exist, so they are released * exactly when the physical effect is confirmed `CLEANED` or - * `ALREADY_CLEAN`. A timeout, crash, malformed response or `EFFECT_UNKNOWN` + * `ALREADY_CLEAN`. A timeout, crash, malformed response or worker failure * keeps `PREPARING`/`FILES_READY` in place and asks for reconciliation. */ /** @@ -1074,7 +1074,6 @@ export function createOpfsByteStoreAdapter( }); const compensated = cleanup.ok && - cleanup.value.kind !== "EFFECT_UNKNOWN" && ( await dependencies.journal.rollback( transaction.transactionId, @@ -1102,11 +1101,6 @@ export function createOpfsByteStoreAdapter( signal, ); if (!cleaned.ok) return cleaned; - if (cleaned.value.kind === "EFFECT_UNKNOWN") { - return browserDataFailure("CONFLICT", "OBJECT_RECONCILE", { - recovery: "RETRY", - }); - } const rolledBack = await dependencies.journal.rollback( transaction.transactionId, transaction.fencingToken, diff --git a/src/application/ports/browser-file-storage/opfs-ports.ts b/src/application/ports/browser-file-storage/opfs-ports.ts index 227b314d..7091ab07 100644 --- a/src/application/ports/browser-file-storage/opfs-ports.ts +++ b/src/application/ports/browser-file-storage/opfs-ports.ts @@ -233,11 +233,12 @@ export type OpfsPreparedObject = OpfsPreparedObjectV1 | OpfsPreparedObjectV2; /** * STO-01. Compensation is only allowed to release journal and budget state - * after the physical effect is confirmed. `EFFECT_UNKNOWN` is never a success. + * after the physical effect is confirmed. An effect the worker cannot confirm + * comes back as a failure, never as a success value (05-09). */ -export type OpfsCleanupEffect = - | Readonly<{ kind: "CLEANED" | "ALREADY_CLEAN" }> - | Readonly<{ kind: "EFFECT_UNKNOWN" }>; +export type OpfsCleanupEffect = Readonly<{ + kind: "CLEANED" | "ALREADY_CLEAN"; +}>; export type OpfsJournalMutation = "PUT" | "DELETE"; export type OpfsJournalPhase = diff --git a/tests/unit/opfs-byte-store.test.ts b/tests/unit/opfs-byte-store.test.ts index 734a2d9e..a81d5f2e 100644 --- a/tests/unit/opfs-byte-store.test.ts +++ b/tests/unit/opfs-byte-store.test.ts @@ -630,7 +630,7 @@ describe("OPFS byte-store coordinator", () => { }, { async abortPreparedPut() { - return browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }); + return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"); }, }, ]) { @@ -775,11 +775,11 @@ describe("OPFS byte-store coordinator", () => { }); }); - it("does not roll back journal after an unknown worker mutation effect", async () => { + it("does not roll back journal after an unconfirmed worker cleanup", async () => { const journal = createJournal(); const worker = createWorker({ async abortPreparedPut() { - return browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }); + return browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"); }, }); const rollback = vi.spyOn(journal, "rollback"); @@ -843,8 +843,8 @@ describe("OPFS byte-store coordinator", () => { async () => browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"), ], [ - "an unknown cleanup effect", - async () => browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }), + "an aborted cleanup", + async () => browserDataFailure("ABORTED", "OBJECT_RECONCILE"), ], ])("after %s", async (_label, abortPreparedPut) => { const journal = createJournal(); @@ -910,7 +910,7 @@ describe("OPFS byte-store coordinator", () => { await putWith( { abortPreparedPut: async () => - browserDataSuccess({ kind: "EFFECT_UNKNOWN" as const }), + browserDataFailure("UNAVAILABLE", "OBJECT_RECONCILE"), }, journal, ),