docs(platform): kernel 주석의 줄 번호 참조를 심볼 이름으로 바꾼다 (05-05)
문제: kernel 주석이 근거를 다른 파일의 줄 번호로만 준다. 줄이 밀려 참조 20개 중 19개가 엉뚱한 코드를 가리킨다. 예를 들어 indexeddb-transaction.ts의 "runtime은 지운 행 수로 예산을 잰다"는 indexeddb-runtime.ts:2384를 가리키는데 그 줄은 cursor 삭제 onerror다. 네 벌의 transaction 상태 기계를 가리키는 참조 넷은 kernel 이전 코드라 이미 없다(네 어댑터 모두 지금은 runIndexedDbTransaction을 쓴다). 고른 방법: 리뷰 권고대로 줄 번호 대신 심볼 이름을 쓴다. - purgeEligibleRecords, scanBatch, monotonicClock, runCheckpointTransaction, bindScope, 체크포인트 store의 translate, BT-UP-03, restrictedBrowserDataProperties, browser-data-boundary 예외 목록, REQUIRED_ABORT_CONSUMERS. - 없어진 코드를 가리키던 역사 설명은 "IDB-X-02 이전에는 네 벌이 달랐다", "runtime의 kernel 이전 fail/requestFailed 의미"처럼 ID와 과거형으로 줄였다. "runtime이 지금 inline으로 한다"처럼 더는 사실이 아닌 문장은 지웠다. - 유일하게 맞던 abortable-operation.ts:11도 같은 규칙으로 줄 번호만 뺐다(심볼 AbortTerminalReason이 이미 문장에 있다). 버린 대안: 줄 번호를 지금 위치로 다시 맞추기. 다음 수정에서 또 밀린다. 위험·한계: 주석만 바뀐다. 코드·번들 크기(주석은 minify에서 빠짐)는 그대로다. 심볼 이름도 이름이 바뀌면 낡지만 grep으로 바로 찾을 수 있다. 검증: - RED(문서·코드 대조): platform/·browser-file-storage/의 `grep -rnE '\.(ts|json|md|mjs):[0-9]+'` 20건을 스크립트로 열어 대조. 19건이 다른 코드(예: check-adapter-inventory.ts:63-83은 INVENTORY 중복 행 검사, eslint.config.ts:519-530은 블록 끝 "},"), 1건만 맞음. - GREEN: 같은 grep 0건. 새로 적은 심볼은 모두 해당 파일에 있는 것을 확인했다. - 회귀: indexeddb-transaction, indexeddb-connection, browser-lifecycle 3파일 66/66 통과. tsc app 통과, eslint 통과, check-adapter-inventory 145 files PASS. Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
This commit is contained in:
@@ -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 {
|
||||
|
||||
@@ -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<Failure> = 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" }>;
|
||||
|
||||
|
||||
@@ -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<Failure> = 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<Value, Failure> = 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<Failure> = 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<IndexedDbBudgetVerdict, Failure>;
|
||||
}>;
|
||||
@@ -129,8 +129,7 @@ export type IndexedDbWalkInput<Failure> = Readonly<{
|
||||
budget?: IndexedDbBudget<Failure>;
|
||||
/**
|
||||
* 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<Value, Failure>(
|
||||
input: IndexedDbTransactionInput<Value, Failure>,
|
||||
@@ -318,7 +317,7 @@ export function onIndexedDbRequest<Value, Failure>(
|
||||
* 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<Failure>(
|
||||
input: IndexedDbWalkInput<Failure>,
|
||||
|
||||
Reference in New Issue
Block a user