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
@@ -698,6 +698,7 @@ export function createIndexedDbOpfsJournal(
"INDEXEDDB_READ",
(transaction, context) => {
const rows: OpfsJournalTransaction[] = [];
let corruptRows = 0;
walkIndexedDbCursor<BrowserDataFailure>({
request: transaction
.objectStore(JOURNAL_STORE)
@@ -708,21 +709,18 @@ export function createIndexedDbOpfsJournal(
// OP-4. Neither a signal nor a budget is passed: the journal
// offers no cancellation and bounds the page on `limit` alone.
visit: ({ cursor }) => {
// The row is validated before the page limit is checked, so a
// corrupt row one past the page still fails the read rather
// than being hidden behind `moreAvailable`.
if (
!isStoredJournalRow(cursor.value) ||
!isBoundScope(cursor.value.scope)
) {
context.fail(corrupt("INDEXEDDB_READ"));
// `fail` aborts, so the pump has nowhere to go. Suspending
// without ever resuming says that without claiming a summary
// the scan never reached.
return { kind: "SUSPEND" };
}
if (rows.length === limit) return { kind: "STOP" };
rows.push(cursor.value);
// [0929] 05-01. One unreadable row used to fail the read, which
// stopped reconcile and GC for the whole authority. It is
// skipped and counted; nothing here deletes it.
if (
isStoredJournalRow(cursor.value) &&
isBoundScope(cursor.value.scope)
) {
rows.push(cursor.value);
} else {
corruptRows += 1;
}
return { kind: "CONTINUE" };
},
done: (summary) => {
@@ -731,6 +729,7 @@ export function createIndexedDbOpfsJournal(
transactions: Object.freeze(rows),
moreAvailable:
summary.reason === "STOPPED" && rows.length === limit,
corruptRows,
}),
);
},
@@ -774,6 +773,7 @@ export function createIndexedDbOpfsJournal(
false,
);
const objects: OpfsPreparedObject[] = [];
let corruptRows = 0;
walkIndexedDbCursor<BrowserDataFailure>({
request: transaction
.objectStore(OBJECT_STORE)
@@ -782,20 +782,21 @@ export function createIndexedDbOpfsJournal(
sink: context,
translate: translateFor("INDEXEDDB_READ"),
visit: ({ cursor }) => {
if (objects.length === request.limit) {
return { kind: "STOP" };
}
// [0929] 05-01. Skipped and counted, as in `listIncomplete`.
if (
!isStoredObjectRow(cursor.value) ||
!sameScope(
isStoredObjectRow(cursor.value) &&
sameScope(
cursor.value.preparedObject.descriptor.scope,
request.scope,
)
) {
context.fail(corrupt("INDEXEDDB_READ"));
return { kind: "SUSPEND" };
objects.push(cursor.value.preparedObject);
} else {
corruptRows += 1;
}
if (objects.length === request.limit) {
return { kind: "STOP" };
}
objects.push(cursor.value.preparedObject);
return { kind: "CONTINUE" };
},
done: (summary) => {
@@ -811,6 +812,7 @@ export function createIndexedDbOpfsJournal(
? objects.at(-1)?.descriptor.objectId ?? null
: null,
moreAvailable: more,
corruptRows,
}),
);
},
@@ -862,6 +864,62 @@ export function createIndexedDbOpfsJournal(
);
},
async removePartition(scope) {
if (
!keyRange ||
!isBoundScope(scope) ||
!isValidOpfsStorageScope(scope)
) {
return browserDataFailure(
keyRange ? "INVALID_INPUT" : "UNSUPPORTED",
"INDEXEDDB_WRITE",
);
}
return await withDatabase("INDEXEDDB_WRITE", (db) =>
runTransaction<void>(
db,
[JOURNAL_STORE, OBJECT_STORE, BUDGET_STORE, CHUNK_REFERENCE_STORE],
"readwrite",
"INDEXEDDB_WRITE",
(transaction, context) => {
// [0929] 05-01. Rows are found by key, never by value, so a row
// nothing can read still goes. Tokens cannot hold `|`, so this
// prefix matches this one partition only.
const scopeKey = storageScopeKey(scope);
const range = keyRange.bound(
`${scopeKey}|`,
`${scopeKey}|￿`,
);
// The transaction's commit publishes this; a failed delete aborts
// it and replaces it.
context.succeed(undefined);
watchWrite(
transaction.objectStore(BUDGET_STORE).delete(scopeKey),
context,
);
for (const [storeName, indexName] of [
[JOURNAL_STORE, LOGICAL_KEY_INDEX],
[OBJECT_STORE],
[CHUNK_REFERENCE_STORE],
] as const) {
const store = transaction.objectStore(storeName);
walkIndexedDbCursor<BrowserDataFailure>({
request: (indexName ? store.index(indexName) : store)
.openCursor(range),
sink: context,
translate: translateFor("INDEXEDDB_WRITE"),
visit: ({ cursor }) => {
watchWrite(store.delete(cursor.primaryKey), context);
return { kind: "CONTINUE" };
},
done: () => {},
});
}
},
),
);
},
close() {
connection.close();
},
@@ -614,6 +614,7 @@ export function createOpfsByteStoreAdapter(
deadlineReached: boolean;
skippedLiveTransactions: number;
failedTransactions: number;
corruptTransactions: number;
} = {
inspectedTransactions: 0,
committedTransactions: 0,
@@ -626,6 +627,7 @@ export function createOpfsByteStoreAdapter(
deadlineReached: false,
skippedLiveTransactions: 0,
failedTransactions: 0,
corruptTransactions: 0,
};
// 05-01 (D-3). A row is reconciled only while this call holds its
// per-transaction lock, so a put or delete still running in any tab is
@@ -654,6 +656,8 @@ export function createOpfsByteStoreAdapter(
return rebaseFailure(page.error, "OBJECT_RECONCILE");
}
report.moreTransactionsAvailable = page.value.moreAvailable;
// [0929] 05-01. The journal skipped these rows; they stop nothing now.
report.corruptTransactions = page.value.corruptRows;
for (const transaction of page.value.transactions) {
if (!held.has(transaction.transactionId)) continue;
if (request.signal?.aborted) {
@@ -698,8 +702,11 @@ export function createOpfsByteStoreAdapter(
}
observeOpfsSafely(dependencies.observer, {
operation: "OBJECT_RECONCILE",
outcome: "SUCCEEDED",
transactionBucket: transactionBucket(report.inspectedTransactions),
// A skipped corrupt row is observed, not hidden behind a success.
...(report.corruptTransactions
? { outcome: "DEGRADED", failureCode: "CORRUPT_DATA" }
: { outcome: "SUCCEEDED" }),
});
return browserDataSuccess<OpfsReconciliationReport>(
Object.freeze({ ...report }),
@@ -781,6 +788,13 @@ export function createOpfsByteStoreAdapter(
let releasedBytes = 0;
let moreObjectsAvailable = false;
let deadlineReached = false;
const sweeping =
request.reason === "LOGOUT" || request.reason === "ACCOUNT_DELETION";
// [0929] 05-01. Rows the journal could not read and skipped, and damage
// met past the listing: a remove or the sweep failing on an unreadable
// row, or staging the sweep cannot read.
let corruptObjects = 0;
let damaged = false;
for (;;) {
// 1101/13.6. Only stopping before a page is read leaves objects
@@ -801,6 +815,7 @@ export function createOpfsByteStoreAdapter(
if (!page.ok) {
return rebaseFailure(page.error, "OBJECT_RECONCILE");
}
corruptObjects += page.value.corruptRows;
const candidates = [...page.value.objects].sort(
policyMaintenanceOrder,
);
@@ -825,11 +840,16 @@ export function createOpfsByteStoreAdapter(
if (removed.error.code === "CONFLICT" || removed.error.code === "NOT_FOUND") {
// [0929] 05-02. Another context changed this object, so it may
// still be here: report more work and skip the chunk sweep. No
// later assignment clears this — the last-page one ORs, and the
// PRESSURE one only runs for a purge that never sweeps.
// later assignment clears this — the last-page one ORs, the
// PRESSURE one only runs for a purge that never sweeps, and a
// partition delete leaves no object behind.
moreObjectsAvailable = true;
continue;
}
if (sweeping && removed.error.code === "CORRUPT_DATA") {
damaged = true;
continue;
}
return rebaseFailure(removed.error, "OBJECT_RECONCILE");
}
removedObjects += 1;
@@ -861,8 +881,9 @@ export function createOpfsByteStoreAdapter(
// staged put references.
let chunkSweep: OpfsPolicyMaintenanceReport["chunkSweep"];
if (
(request.reason === "LOGOUT" ||
request.reason === "ACCOUNT_DELETION") &&
sweeping &&
!corruptObjects &&
!damaged &&
!moreObjectsAvailable &&
!deadlineReached &&
!request.signal?.aborted
@@ -872,13 +893,48 @@ export function createOpfsByteStoreAdapter(
request.signal,
now(),
);
if (!swept.ok) return rebaseFailure(swept.error, "OBJECT_RECONCILE");
chunkSweep = swept.value.status;
if (chunkSweep === "DEADLINE_REACHED") {
deadlineReached = true;
moreObjectsAvailable = true;
if (!swept.ok) {
if (swept.error.code !== "CORRUPT_DATA") {
return rebaseFailure(swept.error, "OBJECT_RECONCILE");
}
damaged = true;
} else {
chunkSweep = swept.value.status;
damaged = chunkSweep === "STAGING_STATE_UNREADABLE";
if (chunkSweep === "DEADLINE_REACHED") {
deadlineReached = true;
moreObjectsAvailable = true;
}
}
}
// [0929] 05-01. A row nothing can read never lets this purge finish, so
// the user's bytes would stay on the device for good. The authority
// approved this exact LOGOUT or ACCOUNT_DELETION (the same approval the
// IndexedDB dataset delete runs on), so the partition directory goes
// under the origin lease and then the partition's journal rows. Both
// are keyed by this partition's tokens alone; no other partition is
// touched. Like that delete, this step is not bounded by the budget.
const partitionDeleted =
sweeping &&
(corruptObjects > 0 || damaged) &&
!request.signal?.aborted;
if (partitionDeleted) {
const removedFiles = await dependencies.worker.removePartition(
dependencies.scope,
request.signal,
);
if (!removedFiles.ok) {
return rebaseFailure(removedFiles.error, "OBJECT_RECONCILE");
}
const removedRows = await dependencies.journal.removePartition(
dependencies.scope,
);
if (!removedRows.ok) {
return rebaseFailure(removedRows.error, "OBJECT_RECONCILE");
}
chunkSweep = undefined;
moreObjectsAvailable = false;
}
const report: OpfsPolicyMaintenanceReport = Object.freeze({
inspectedObjects,
removedObjects,
@@ -886,6 +942,8 @@ export function createOpfsByteStoreAdapter(
moreObjectsAvailable,
deadlineReached,
...(chunkSweep ? { chunkSweep } : {}),
...(corruptObjects ? { corruptObjects } : {}),
...(partitionDeleted ? { partitionDeleted } : {}),
});
return browserDataSuccess(report);
},
@@ -1506,6 +1564,7 @@ function snapshotOpfsJournal(
listIncomplete,
listCommittedObjects,
isChunkReferenced,
removePartition,
} = source;
if (
[
@@ -1519,6 +1578,7 @@ function snapshotOpfsJournal(
listIncomplete,
listCommittedObjects,
isChunkReferenced,
removePartition,
].some((method) => typeof method !== "function")
) {
throw new TypeError("OPFS journal dependency is invalid.");
@@ -1534,6 +1594,7 @@ function snapshotOpfsJournal(
listIncomplete: listIncomplete.bind(source),
listCommittedObjects: listCommittedObjects.bind(source),
isChunkReferenced: isChunkReferenced.bind(source),
removePartition: removePartition.bind(source),
});
}
@@ -1554,6 +1615,7 @@ function snapshotOpfsWorker(
finalizePut,
listOrphanCandidates,
deleteOrphanChunk,
removePartition,
close,
} = source;
if (
@@ -1568,6 +1630,7 @@ function snapshotOpfsWorker(
finalizePut,
listOrphanCandidates,
deleteOrphanChunk,
removePartition,
close,
].some((method) => typeof method !== "function")
) {
@@ -1584,6 +1647,7 @@ function snapshotOpfsWorker(
finalizePut: finalizePut.bind(source),
listOrphanCandidates: listOrphanCandidates.bind(source),
deleteOrphanChunk: deleteOrphanChunk.bind(source),
removePartition: removePartition.bind(source),
close: close.bind(source),
});
}
@@ -511,6 +511,17 @@ export function createOpfsWorkerGateway(
);
},
async removePartition(
scope: OpfsPreparedObject["descriptor"]["scope"],
signal?: AbortSignal,
) {
return await invoke<void>(
"OBJECT_RECONCILE",
{ kind: "REMOVE_PARTITION", scope },
signal,
);
},
close() {
if (disposed) return;
disposed = true;
@@ -140,6 +140,13 @@ export type OpfsWorkerRequest =
scope: OpfsStorageScope;
digestHex: string;
olderThanEpochMs: number;
}>
| Readonly<{
requestId: string;
protocolVersion: typeof OPFS_WORKER_PROTOCOL_VERSION;
/** [0929] 05-01. Removes `authorities/<a>/<ns>/<p>` under the lease. */
kind: "REMOVE_PARTITION";
scope: OpfsStorageScope;
}>;
/**
@@ -157,6 +164,7 @@ export const OPFS_LOCK_WAITING_REQUEST_KINDS: ReadonlySet<
"FINALIZE_PUT",
"LIST_ORPHAN_CANDIDATES",
"DELETE_ORPHAN_CHUNK",
"REMOVE_PARTITION",
]);
export type OpfsWorkerRequestBody =
@@ -276,5 +284,14 @@ export interface OpfsWorkerGateway {
olderThanEpochMs: number,
signal?: AbortSignal,
): Promise<BrowserDataResult<OpfsOrphanDeleteResult>>;
/**
* [0929] 05-01. Deletes the whole partition directory while holding the
* origin mutation lease. Only an approved LOGOUT or ACCOUNT_DELETION purge
* that damage kept from finishing calls it.
*/
removePartition(
scope: OpfsStorageScope,
signal?: AbortSignal,
): Promise<BrowserDataResult<void>>;
close(): void;
}
@@ -308,6 +308,9 @@ export function createOpfsWorkerRuntime(
request.olderThanEpochMs,
),
);
case "REMOVE_PARTITION":
await removePartition(request.scope);
return success(request.requestId, request.kind);
}
} catch (error) {
// STO-RR-02. The kind travels with the failure so the client's
@@ -816,6 +819,36 @@ export function createOpfsWorkerRuntime(
}
}
/**
* [0929] 05-01. The exit an approved purge takes when damage keeps it from
* finishing. Under the origin lease no put is streaming, so nothing is
* half-written into the directory while it goes.
*/
async function removePartition(
scope: OpfsPreparedObject["descriptor"]["scope"],
): Promise<void> {
assertWorkerAvailable();
if (!isValidOpfsStorageScope(scope)) {
throw new OpfsRuntimeFailure("INVALID_INPUT");
}
const lease = await acquireLease();
try {
await removeEntryIfPresent(
await getDirectory(
dependencies.root,
scopeRootPath(scope).slice(0, -1),
false,
),
scope.partitionToken,
true,
);
} catch (error) {
if (!isNotFound(error)) throw error;
} finally {
lease.release();
}
}
/**
* STO-01. Cleanup deletes exactly one transaction's physical generation while
* holding the origin mutation lease, and reports whether the effect actually
@@ -1892,6 +1925,7 @@ const WORKER_REQUEST_KINDS = new Set<string>([
"FINALIZE_PUT",
"LIST_ORPHAN_CANDIDATES",
"DELETE_ORPHAN_CHUNK",
"REMOVE_PARTITION",
]);
function extractReceiptDigests(
@@ -125,6 +125,12 @@ export type OpfsReconciliationReport = Readonly<{
* stops the rest of the page or orphan GC.
*/
failedTransactions: number;
/**
* [0929] 05-01. Journal rows this run could not read. They are skipped, not
* deleted, and no longer stop the other rows or orphan GC. Anything above
* zero is storage damage for an operator to look at.
*/
corruptTransactions: number;
}>;
export type OpfsPolicyMaintenanceReport = Readonly<{
@@ -141,9 +147,20 @@ export type OpfsPolicyMaintenanceReport = Readonly<{
/**
* 05-04. LOGOUT and ACCOUNT_DELETION only, once every object is removed:
* how the sweep of the partition's now unreferenced chunks ended. Chunk
* bytes are gone only when it is `COMPLETED`.
* bytes are gone only when it is `COMPLETED`, or when `partitionDeleted`.
*/
chunkSweep?: "COMPLETED" | "DEADLINE_REACHED" | "STAGING_STATE_UNREADABLE";
/**
* [0929] 05-01. Committed object rows this run could not read and skipped.
* Present only when there were some.
*/
corruptObjects?: number;
/**
* [0929] 05-01. An approved LOGOUT or ACCOUNT_DELETION that damage kept
* from finishing removed the whole partition directory and the partition's
* journal rows instead. Every byte of the partition is gone.
*/
partitionDeleted?: true;
}>;
export type OpfsSensitiveMaintenanceReason =
@@ -291,15 +308,23 @@ export type BeginOpfsJournalTransaction = Readonly<{
startedAtEpochMs: number;
}>;
/**
* [0929] 05-01. A listing skips a row it cannot read and counts it in
* `corruptRows`; it never deletes it. The rows of one page do not include
* skipped ones, so a full page stops before the next row and a row is counted
* once, by the page that reaches it.
*/
export type OpfsJournalPage = Readonly<{
transactions: readonly OpfsJournalTransaction[];
moreAvailable: boolean;
corruptRows: number;
}>;
export type OpfsCommittedObjectPage = Readonly<{
objects: readonly OpfsPreparedObject[];
nextObjectId: string | null;
moreAvailable: boolean;
corruptRows: number;
}>;
export interface OpfsJournalPort {
@@ -351,4 +376,13 @@ export interface OpfsJournalPort {
scope: OpfsStorageScope,
digestHex: string,
): Promise<BrowserDataResult<boolean>>;
/**
* [0929] 05-01. Deletes every row keyed to this one partition, readable or
* not: committed objects, journal rows, chunk references and the budget.
* Scope bindings stay. Only an approved LOGOUT or ACCOUNT_DELETION purge
* calls it, after the partition's directory is gone.
*/
removePartition(
scope: OpfsStorageScope,
): Promise<BrowserDataResult<void>>;
}