From cc011bc74004527bf3e77b5600e6438d48e611f1 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 1 Nov 2026 22:07:51 +0900 Subject: [PATCH] =?UTF-8?q?docs(platform):=20kernel=20=EC=A3=BC=EC=84=9D?= =?UTF-8?q?=EC=9D=98=20=EC=A4=84=20=EB=B2=88=ED=98=B8=20=EC=B0=B8=EC=A1=B0?= =?UTF-8?q?=EB=A5=BC=20=EC=8B=AC=EB=B3=BC=20=EC=9D=B4=EB=A6=84=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EB=B0=94=EA=BE=BC=EB=8B=A4=20(05-05)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 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 --- src/adapters/platform/index.ts | 7 ++- src/adapters/platform/indexeddb-connection.ts | 19 ++++--- .../platform/indexeddb-transaction.ts | 57 +++++++++---------- 3 files changed, 43 insertions(+), 40 deletions(-) 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,