diff --git a/src/adapters/platform/index.ts b/src/adapters/platform/index.ts index 015735f8..defdf44d 100644 --- a/src/adapters/platform/index.ts +++ b/src/adapters/platform/index.ts @@ -2,9 +2,10 @@ * 어댑터 커널의 공개 경계. * * `src/adapters/**` 안에서는 이 배럴을 쓰지 않는다. 커널 프리미티브는 파일 - * 경로로 직접 import한다 — `scripts/check-adapter-inventory.ts:63-83`이 - * `platform/abortable-operation.ts`로 해석되는 specifier를 네 소비자에게 - * 요구하고, `.dependency-cruiser.json`의 kernel carve-out도 폴더 단위다. + * 경로로 직접 import한다 — `scripts/check-adapter-inventory.ts`의 + * `REQUIRED_ABORT_CONSUMERS` 검사가 `platform/abortable-operation.ts`로 + * 해석되는 specifier를 네 소비자에게 요구하고, `.dependency-cruiser.json`의 + * kernel carve-out도 폴더 단위다. * 이 배럴은 bootstrap·features·tests 같은 그룹 바깥 소비자를 위한 문이다. */ export { diff --git a/src/adapters/platform/indexeddb-connection.ts b/src/adapters/platform/indexeddb-connection.ts index 9ba02c16..d0c880a9 100644 --- a/src/adapters/platform/indexeddb-connection.ts +++ b/src/adapters/platform/indexeddb-connection.ts @@ -10,10 +10,12 @@ * generic storage layer. * * The `IDBFactory` is a required parameter rather than a read of - * `globalThis.indexedDB`. `eslint.config.ts:40-63` bans that property on every - * browser root and `eslint.config.ts:519-530` grants the owned-adapter escape - * hatch to `src/adapters/platform/browser-lifecycle.ts` as a single file, not - * to this folder. Requiring the factory is also what all four callers already + * `globalThis.indexedDB`. `restrictedBrowserDataProperties` in + * `eslint.config.ts` bans that property on every browser root, and the + * owned-adapter lists there (the `browser-data-boundary/no-capability-alias` + * ignores and the block that turns `no-restricted-properties` off) name + * `src/adapters/platform/browser-lifecycle.ts` as a single file, not this + * folder. Requiring the factory is also what all four callers already * do, so nothing in eslint.config.ts has to change. * * What this module owns: event wiring, the settle-once latch, the blocked @@ -32,7 +34,7 @@ import type { AbortTimerSnapshot } from "./abortable-operation.ts"; * value. The kernel reports the cause; the caller's `translate` turns it into * that subsystem's failure code. * - * This union is the extension point. `abortable-operation.ts:11` baked a closed + * This union is the extension point. `abortable-operation.ts` baked a closed * three-member `AbortTerminalReason` into its return type, so http v3 needed * five owners and could not use the kernel at all. Here the owner vocabulary is * never in a return type: adding a member is a compile error in every @@ -116,7 +118,7 @@ export type IndexedDbOpenInput = Readonly<{ /** * Called inside the versionchange transaction. Omitting it means any upgrade * is unexpected and the open fails with `UPGRADE_REJECTED` — which is what - * `indexeddb-maintenance.ts:477-484` does by hand today. + * IndexedDB maintenance relies on by omitting it. */ upgrade?: (context: IndexedDbUpgradeContext) => IndexedDbUpgradeOutcome; /** Post-open validation. Omitting it admits every successful open. */ @@ -187,8 +189,9 @@ export type IndexedDbDeleteOutcome = /** * The request is still live in the browser. It is not a failure and it is not * "not applied": `deleteDatabase` cannot be cancelled after dispatch, so the - * effect is unknown. `indexeddb-checkpoint-store.ts:449-462` makes the same - * distinction and its comment explains why. + * effect is unknown. The checkpoint store's admin delete (BT-UP-03 in + * `indexeddb-checkpoint-store.ts`) makes the same distinction and its + * comment explains why. */ | Readonly<{ kind: "BLOCKED_DEADLINE" }>; diff --git a/src/adapters/platform/indexeddb-transaction.ts b/src/adapters/platform/indexeddb-transaction.ts index e97a1617..8e6c344a 100644 --- a/src/adapters/platform/indexeddb-transaction.ts +++ b/src/adapters/platform/indexeddb-transaction.ts @@ -1,14 +1,13 @@ /** * IDB-X-02. Shared IndexedDB transaction and cursor mechanics. * - * The same settle-once transaction state machine exists four times - * (`indexeddb-runtime.ts:976-1074`, `indexeddb-maintenance.ts:606-705`, - * `indexeddb-opfs-journal.ts:1098-1174`, - * `indexeddb-checkpoint-store.ts:497-596`) and the four already disagree: one - * of them never routes a request error at all, one aborts on a request error - * while two only record it, and one reports a value-less completion as - * CORRUPT_DATA while three report UNAVAILABLE. This module owns the mechanics - * and keeps every one of those choices at the call site. + * Before IDB-X-02 the same settle-once transaction state machine existed four + * times (the IndexedDB runtime, IndexedDB maintenance, the OPFS journal and the + * resumable-upload checkpoint store), and the four disagreed: one never routed + * a request error at all, one aborted on a request error while two only + * recorded it, and one reported a value-less completion as CORRUPT_DATA while + * three reported UNAVAILABLE. All four now call this module. It owns the + * mechanics and keeps every one of those choices at the call site. * * Like `indexeddb-connection.ts`, it owns no policy: not a store name, not a * durability default, not a budget criterion, not a failure code. @@ -28,18 +27,19 @@ export type IndexedDbRequestSink = Readonly<{ /** * Records the failure and aborts the transaction. The first failure wins, * and it wins over an earlier `succeed`. - * This is `indexeddb-runtime.ts:1047-1054`'s `fail`. + * These are the IndexedDB runtime's pre-kernel `fail` semantics. */ fail(failure: Failure): void; /** * Records a request-level error **without aborting**: the transaction is left * to complete or abort on its own, and the recorded error becomes the reported - * failure if it aborts. This is `indexeddb-runtime.ts:1055-1060`'s - * `requestFailed`. + * failure if it aborts. These are the IndexedDB runtime's pre-kernel + * `requestFailed` semantics. * - * `indexeddb-checkpoint-store.ts:577-588` deliberately aborts instead. It - * keeps doing so by calling `fail(translate({kind:"NATIVE_EXCEPTION", error}))`. - * The kernel does not pick. + * The checkpoint store (`runCheckpointTransaction` and `bindScope` in + * `indexeddb-checkpoint-store.ts`) deliberately aborts instead. It keeps + * doing so by routing each request error through `fail` with its mapped + * failure. The kernel does not pick. */ requestFailed(error: unknown): void; }>; @@ -61,10 +61,11 @@ export type IndexedDbTransactionInput = Readonly<{ /** Aborts the transaction; the outcome is `CALLER_ABORT` unless completion won. */ signal?: AbortSignal; /** - * `undefined` opens with **no options bag at all**, which is - * `indexeddb-checkpoint-store.ts:512`'s current behavior — not the same as - * `"default"`, which passes `{durability:"default"}`. A named value falls back - * to the no-options form when the engine rejects the bag with a `TypeError`. + * `undefined` opens with **no options bag at all**, which is what the + * checkpoint store's `runCheckpointTransaction` and `bindScope` pass — not + * the same as `"default"`, which passes `{durability:"default"}`. A named + * value falls back to the no-options form when the engine rejects the bag + * with a `TypeError`. */ durability?: IndexedDbDurability; queue: ( @@ -99,12 +100,11 @@ export type IndexedDbBudgetVerdict = "CONTINUE" | "ROW_BUDGET" | "TIME_BUDGET"; export type IndexedDbBudget = Readonly<{ /** * Checked before each row, with the number of rows already handed to `visit`. - * The kernel counts nothing itself: runtime bounds on rows it deleted - * (`indexeddb-runtime.ts:2384`) while maintenance bounds on rows it scanned - * (`indexeddb-maintenance.ts:823`), so the counter, the clock and the deadline - * all belong to the caller. A clock that cannot be read is a failure rather - * than a `false`, which is what `monotonicClock()` - * (`indexeddb-runtime.ts:2260-2269`) already does. + * The kernel counts nothing itself: the runtime's `purgeEligibleRecords` + * bounds on rows it deleted while maintenance's `scanBatch` bounds on rows it + * scanned, so the counter, the clock and the deadline all belong to the + * caller. A clock that cannot be read is a failure rather than a `false`, + * which is what the runtime's `monotonicClock()` already does. */ admit(scannedRows: number): Result; }>; @@ -129,8 +129,7 @@ export type IndexedDbWalkInput = Readonly<{ budget?: IndexedDbBudget; /** * Checked at each row. An aborted signal aborts the transaction and ends the - * walk with `reason: "ABORTED"`, which is what `indexeddb-runtime.ts:1375-1382` - * does inline today. + * walk with `reason: "ABORTED"`. */ signal?: AbortSignal; visit: (visit: IndexedDbCursorVisit) => IndexedDbCursorStep; @@ -174,8 +173,8 @@ export function openIndexedDbTransaction( /** * A transaction that completes without `succeed()` is reported through * `translate({kind:"NO_VALUE_PRODUCED"})`. Three callers map that to - * UNAVAILABLE and `indexeddb-checkpoint-store.ts:541-547` maps it to - * CORRUPT_DATA; the kernel never picks. + * UNAVAILABLE and the checkpoint store's `translate` maps it to CORRUPT_DATA; + * the kernel never picks. */ export function runIndexedDbTransaction( input: IndexedDbTransactionInput, @@ -318,7 +317,7 @@ export function onIndexedDbRequest( * Drives an open cursor. It reports a native advance failure through `sink` and * never decides what a finished walk means — `reason` distinguishes a row budget * from a time budget so a caller can keep reporting `budgetExhausted` exactly as - * it does now (`indexeddb-runtime.ts:2387`). + * the runtime's `purgeEligibleRecords` does. */ export function walkIndexedDbCursor( input: IndexedDbWalkInput,