refactor(storage): move the IndexedDB error table to the kernel exception file (05-11)

The OPFS journal imported mapIndexedDbException from the IndexedDB runtime's
folder, so the two runtimes were not separable as the comments claimed. The
table now lives in browser-file-storage/result.ts next to the DOM table, with
the differences between the two written down; storage/opfs imports nothing
from storage/indexeddb. The storage barrel comment now states the drill's
real scope: it removes the whole bundle, never one folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:52:29 +09:00
co-authored by Claude Opus 5.5
parent 3767ed7ccb
commit 6cc652610d
9 changed files with 132 additions and 126 deletions
@@ -31,7 +31,7 @@
| 파일 | 책임 | 주요 의존성 / 리뷰 결과 |
| --- | --- | --- |
| `src/adapters/browser-file-storage/index.ts` | browser data 공통 Result와 StorageManager adapter barrel export | 내부 두 모듈만 export. 경계가 작고 유지 대상. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공 | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/result.ts` | native 예외를 closed `BrowserDataFailure`로 정규화하고 안전한 observation 제공. IndexedDB 예외 표 `mapIndexedDbException`도 여기 있다(05-11, 옛 `storage/indexeddb/indexeddb-failure.ts`) | `application/ports/browser-file-storage/shared.ts`; raw path/name/message 비노출, observer 예외 격리가 좋다. |
| `src/adapters/browser-file-storage/storage-manager-adapter.ts` | `estimate/persisted/persist` snapshot, pressure bucket, user-activation-bound persistence 요청 | storage durability port/result. estimate를 예약량으로 오인하지 않고 irreversible `persist()` truth를 보존한다. origin coordinator는 의도적으로 없음(GAP-03). |
### 1.2 `browser-files`
@@ -66,7 +66,6 @@
| `src/adapters/storage/browser-storage-adapter.ts` | registry key별 local/session/memory 저장, TTL, failure overlay/tombstone, quota fallback | `storage-keys`, `StoragePort`, codec, diagnostics. strict registry와 stale persistent suppression을 유지. adjacent physical-key migration/sweep는 문서상 미구현. |
| `src/adapters/storage/browser-storage-codec.ts` | bounded exact JSON envelope, exotic/accessor/unsafe-key/cycle/depth/node 거절 | 독립 codec. prototype pollution/JSON silent coercion 방어가 좋다. |
| `src/adapters/storage/indexeddb/index.ts` | IndexedDB runtime/maintenance/governance/migration export | native IDB type을 application port 밖으로 내보내지 않는 구조 유지. |
| `src/adapters/storage/indexeddb/indexeddb-failure.ts` | IDB/DOM failure를 closed browser failure로 변환 | common Result. raw native detail 비노출 유지. |
| `src/adapters/storage/indexeddb/indexeddb-governance.ts` | opaque dataset scope/physical DB identity 및 frozen policy binding | indexeddb/shared ports. account/business ID를 physical name에 쓰지 않는 양방향 binding 유지. |
| `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | post-open codec migration 및 idempotency receipt prune, keyset checkpoint, budget/revision fencing | IndexedDB port/types/failure/governance. async transform outside tx, row+sidecar+budget+checkpoint atomic commit은 좋다. STO-06 및 temporal drain lease 개선 후보. |
| `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | additive-only contiguous DDL planner/validator | indexeddb types. destructive DDL 거절 유지. |
+32 -33
View File
@@ -122,38 +122,37 @@
| 112 | `src/adapters/storage/browser-storage-codec.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 113 | `src/adapters/storage/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 114 | `src/adapters/storage/indexeddb/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-failure.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 131 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 135 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 146 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 115 | `src/adapters/storage/indexeddb/indexeddb-governance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 116 | `src/adapters/storage/indexeddb/indexeddb-maintenance.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 117 | `src/adapters/storage/indexeddb/indexeddb-migrations.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 118 | `src/adapters/storage/indexeddb/indexeddb-records.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 119 | `src/adapters/storage/indexeddb/indexeddb-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 120 | `src/adapters/storage/indexeddb/indexeddb-types.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 121 | `src/adapters/storage/opfs/browser-opfs-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 122 | `src/adapters/storage/opfs/index.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 123 | `src/adapters/storage/opfs/indexeddb-opfs-journal.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 124 | `src/adapters/storage/opfs/opfs-byte-store-adapter.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 125 | `src/adapters/storage/opfs/opfs-policy.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 126 | `src/adapters/storage/opfs/opfs-prepared-object.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 127 | `src/adapters/storage/opfs/opfs-worker-client.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 128 | `src/adapters/storage/opfs/opfs-worker-protocol.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 129 | `src/adapters/storage/opfs/opfs-worker-runtime.ts` | [Storage/files](./03-storage-and-browser-files.md) |
| 130 | `src/adapters/telemetry/best-effort-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 131 | `src/adapters/telemetry/feature-telemetry.ts` | [Network/state](./01-network-and-state.md) |
| 132 | `src/adapters/telemetry/index.ts` | [Network/state](./01-network-and-state.md) |
| 133 | `src/adapters/telemetry/telemetry-collector.ts` | [Network/state](./01-network-and-state.md) |
| 134 | `src/adapters/web-push/codec-primitives.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 135 | `src/adapters/web-push/inbound/notification-click-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 136 | `src/adapters/web-push/inbound/push-event-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 137 | `src/adapters/web-push/index.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 138 | `src/adapters/web-push/notification-registry.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 139 | `src/adapters/web-push/push-association-fence-store.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 140 | `src/adapters/web-push/push-codec.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 141 | `src/adapters/web-push/push-registration-gateway.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 142 | `src/adapters/web-push/push-subscription-adapter.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 143 | `src/adapters/web-push/runtime-support.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 144 | `src/adapters/web-push/service-worker-runtime.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
| 145 | `src/adapters/web-push/service-worker-scope-host.ts` | [Worker/push](./05-service-worker-and-web-push.md) |
합계: **146/146**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
합계: **145/145**. 새 adapter 파일이 추가되면 이 ledger와 해당 상세 리뷰 inventory를 같은 변경에서 갱신한다.
@@ -40,6 +40,12 @@ export function abortedResult(
: null;
}
/**
* The table for File, Storage Manager, Cache Storage and download DOM errors.
* IndexedDB errors use `mapIndexedDbException` below: the same exception name
* means something else there (a `NotFoundError` is a missing store, not a
* missing file).
*/
export function mapBrowserDataException(
error: unknown,
operation: BrowserDataOperation,
@@ -89,6 +95,81 @@ export function mapBrowserDataException(
}
}
function exceptionName(error: unknown): string {
if (
error &&
typeof error === "object" &&
"name" in error &&
typeof error.name === "string"
) {
return error.name;
}
return "";
}
/**
* 05-11. The one table for native IndexedDB errors. It lives in this kernel
* exception file so the OPFS journal no longer reaches into the IndexedDB
* runtime's folder for it. It maps the closed DOMException vocabulary without
* exposing an exception object, message, key or stored value across the
* adapter boundary.
*
* Differences from `mapBrowserDataException`, on purpose: a missing store or
* index, an inactive or read-only transaction and a `VersionError` are schema
* problems (`MIGRATION_FAILED`, READ_ONLY), not a missing file or a transient
* failure; quota and constraint failures are not retried blindly.
*/
export function mapIndexedDbException(
error: unknown,
operation: BrowserDataOperation,
): BrowserDataResult<never> {
switch (exceptionName(error)) {
case "AbortError":
return browserDataFailure("ABORTED", operation);
case "ConstraintError":
return browserDataFailure("CONFLICT", operation);
case "DataCloneError":
case "DataError":
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "READ_ONLY",
});
case "InvalidAccessError":
case "InvalidStateError":
case "NotFoundError":
case "ReadOnlyError":
case "TransactionInactiveError":
case "VersionError":
return browserDataFailure("MIGRATION_FAILED", operation, {
recovery: "READ_ONLY",
});
case "NotAllowedError":
case "SecurityError":
return browserDataFailure("PERMISSION_DENIED", operation, {
recovery: "ONLINE_ONLY",
});
case "NotReadableError":
return browserDataFailure("NOT_READABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
case "QuotaExceededError":
case "NS_ERROR_DOM_QUOTA_REACHED":
return browserDataFailure("QUOTA_EXCEEDED", operation, {
recovery: "READ_ONLY",
});
case "UnknownError":
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
default:
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
});
}
}
export function observeBrowserData(
observer: BrowserDataObserver | undefined,
observation: BrowserDataObservation,
+5 -3
View File
@@ -2,9 +2,11 @@
* 최상위 storage 배럴은 Web Storage 어댑터만 내보낸다.
*
* `./indexeddb/index.ts`와 `./opfs/index.ts`를 여기서 재수출하지 말 것.
* `scripts/test-browser-file-storage-runtime-removal.ts:23-34`가 그 두 폴더만
* 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면 제거 드릴이 죽는다.
* 두 서브배럴이 각자 제거 가능한 런타임의 경계다.
* `scripts/test-browser-file-storage-runtime-removal.ts`의 `runtimePaths`는 이 두
* 폴더를 browser-file-storage 번들 전체(ports, browser-files, browser-transfer,
* cache-storage 등)와 함께 삭제한 뒤 잔존 import를 예외로 잡는다 — 재수출하면
* 제거 드릴이 죽는다. 드릴은 번들을 통째로만 지운다. 두 폴더 중 하나만 지우는
* 경우는 드릴이 검증하지 않는다.
*/
export {
createBrowserStorageAdapter,
@@ -1,72 +0,0 @@
import type {
BrowserDataOperation,
BrowserDataResult,
} from "../../../application/ports/browser-file-storage/shared.ts";
import { browserDataFailure } from "../../browser-file-storage/result.ts";
function exceptionName(error: unknown): string {
if (
error &&
typeof error === "object" &&
"name" in error &&
typeof error.name === "string"
) {
return error.name;
}
return "";
}
/**
* Maps the closed DOMException vocabulary without exposing an exception
* object, message, key or stored value across the adapter boundary.
*/
export function mapIndexedDbException(
error: unknown,
operation: BrowserDataOperation,
): BrowserDataResult<never> {
switch (exceptionName(error)) {
case "AbortError":
return browserDataFailure("ABORTED", operation);
case "ConstraintError":
return browserDataFailure("CONFLICT", operation);
case "DataCloneError":
case "DataError":
return browserDataFailure("CORRUPT_DATA", operation, {
recovery: "READ_ONLY",
});
case "InvalidAccessError":
case "InvalidStateError":
case "NotFoundError":
case "ReadOnlyError":
case "TransactionInactiveError":
case "VersionError":
return browserDataFailure("MIGRATION_FAILED", operation, {
recovery: "READ_ONLY",
});
case "NotAllowedError":
case "SecurityError":
return browserDataFailure("PERMISSION_DENIED", operation, {
recovery: "ONLINE_ONLY",
});
case "NotReadableError":
return browserDataFailure("NOT_READABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
case "QuotaExceededError":
case "NS_ERROR_DOM_QUOTA_REACHED":
return browserDataFailure("QUOTA_EXCEEDED", operation, {
recovery: "READ_ONLY",
});
case "UnknownError":
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "REOPEN",
});
default:
return browserDataFailure("UNAVAILABLE", operation, {
retryable: true,
recovery: "RETRY",
});
}
}
@@ -12,6 +12,7 @@ import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import {
openIndexedDbDatabase,
@@ -24,7 +25,6 @@ import {
type IndexedDbBudget,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "./indexeddb-failure.ts";
import {
createIndexedDbDatasetBinding,
indexedDbPhysicalDatabaseName,
@@ -322,10 +322,9 @@ export function createIndexedDbMaintenance<WireValue>(
}
/**
* STO-06. Maintenance keeps `mapIndexedDbException`, which the runtime and
* the OPFS journal share, rather than the checkpoint store's own table: the
* same native error is a different answer in the two families, and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-06. Maintenance uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that the runtime and the OPFS journal
* share (05-11).
*
* One translator covers the whole adapter because the operation label is the
* constant `INDEXEDDB_MIGRATE` here — the runtime needs one per operation.
@@ -20,6 +20,7 @@ import {
abortedResult,
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import { snapshotAbortTimers } from "../../platform/abortable-operation.ts";
import {
@@ -36,7 +37,6 @@ import {
type IndexedDbCursorVisit,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "./indexeddb-failure.ts";
import {
createIndexedDbDatasetBinding,
indexedDbPhysicalDatabaseName,
@@ -559,10 +559,9 @@ export function createIndexedDbRuntime<Value, WireValue, Query>(
}
/**
* STO-06. The runtime keeps `mapIndexedDbException`, which maintenance and
* the OPFS journal share, rather than the checkpoint store's own table: the
* same native error is a different answer in the two families, and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-06. The runtime uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that maintenance and the OPFS journal
* share (05-11).
*
* A translator per operation, because a read, a write and an open carry
* different labels. `CLOSED` is mapped explicitly: closing the handle while
@@ -17,6 +17,7 @@ import {
import {
browserDataFailure,
browserDataSuccess,
mapIndexedDbException,
} from "../../browser-file-storage/result.ts";
import { snapshotAbortTimers } from "../../platform/abortable-operation.ts";
import {
@@ -31,7 +32,6 @@ import {
type IndexedDbRequestSink,
type IndexedDbTransactionContext,
} from "../../platform/indexeddb-transaction.ts";
import { mapIndexedDbException } from "../indexeddb/indexeddb-failure.ts";
import { isValidOpfsStorageScope } from "./opfs-policy.ts";
import { isPreparedObject, stableJson } from "./opfs-prepared-object.ts";
@@ -1676,10 +1676,9 @@ function limitExceeded(
}
/**
* STO-01. The journal keeps `mapIndexedDbException`, which the IndexedDB
* runtime and maintenance share, rather than the checkpoint store's own table:
* the same native error is a different answer in the two families and unifying
* them is a separate change from moving the mechanics onto the kernel.
* STO-01. The journal uses `mapIndexedDbException`, the one IndexedDB table
* in `browser-file-storage/result.ts` that the IndexedDB runtime and
* maintenance share (05-11). It imports nothing from `storage/indexeddb/`.
*
* A translator per operation, because the journal labels a read and a write
* differently. The connection always translates as `INDEXEDDB_OPEN`: an open
+1 -1
View File
@@ -6,7 +6,7 @@ import type {
IndexedDbObservation,
IndexedDbRuntimeDependencies,
} from "../../src/adapters/storage/indexeddb/indexeddb-types.ts";
import { mapIndexedDbException } from "../../src/adapters/storage/indexeddb/indexeddb-failure.ts";
import { mapIndexedDbException } from "../../src/adapters/browser-file-storage/result.ts";
import { MemoryIndexedDbFactory } from "../helpers/memory-indexeddb.ts";
type Item = Readonly<{