From 02a761f06406d543af47b802d0f16e51008ddad4 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Fri, 6 Nov 2026 05:17:33 +0900 Subject: [PATCH] =?UTF-8?q?docs(storage):=20=EC=A0=80=EC=9E=A5=EC=86=8C=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C=EA=B0=80=20registry=20=ED=82=A4=20=EB=AA=A9?= =?UTF-8?q?=EB=A1=9D=20=EB=8C=80=EC=8B=A0=20=EC=A0=95=EB=B3=B8=EC=9D=84=20?= =?UTF-8?q?=EA=B0=80=EB=A6=AC=ED=82=A4=EA=B2=8C=20=ED=95=9C=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제: 저장소 설계 문서와 VD-13이 Web Storage registry 행을 "현재" 목록으로 적는다. 설계 문서 50-52행은 8행 중 4행(`COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`, `AUTH_TOKEN`, `QUERY_PERSISTENCE`)만, 0절 표와 16.2절 기본 조립 표와 VD-13 2.1절 표·7.1절 문단은 `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD` 둘만("두 key") 적는다. registry에는 기본 조립이 쓰는 `LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 행 `CACHE_INVALIDATION_PULSE`·`AUTH_REDIRECT_TRANSACTION`도 있다 (`src/contracts/storage-keys.ts`, `create-application.ts`, `boot-release-recovery.ts`). 행을 더한 커밋들이 이 문장을 따라 고치지 않았다. 고른 방법: 목록 문장을 지우고 `STORAGE_REGISTRY`를 정본으로 가리킨다. StoragePort가 거절하는 행의 규칙(`sensitive-forbidden` 분류와 `backend: "external"`, `getStorageDefinition`)만 문장으로 남긴다. 표 두 행은 "StoragePort 행" 한 행으로 합친다. 8행을 모두 적는 대안은 버렸다. 다음에 행이 늘면 같은 식으로 낡는다. 위험·한계: 이 문장을 보는 검사는 없다. 두 문서는 docs/README.md 2절(목표 설계)이라 verify:documentation이 읽지 않는다. 다시 목록을 적으면 리뷰가 손으로 찾아야 한다. 검증: 문서만 바꿨다. 검사 없음(위). `git grep -n 'COLOR_SCHEME' -- docs/architecture`에 목록 문장이 남지 않았다(starter-experience.md의 테마 설명 한 줄만 남는다). Refs: 1106/05-01 --- docs/architecture/client-cache-and-storage.md | 13 +++++++------ .../VD-13-client-cache-scope-and-persistence.md | 8 +++++--- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index 8e7143d6..95922e0e 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -47,9 +47,11 @@ generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `stale `src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에 조립한다. -현재 `src/contracts/storage-keys.ts`에는 `COLOR_SCHEME`, -`CHUNK_RELOAD_GUARD`, 금지된 `AUTH_TOKEN`과 비활성 -`QUERY_PERSISTENCE`가 등록되어 있다. +등록된 Web Storage 키의 정본은 `src/contracts/storage-keys.ts`의 +`STORAGE_REGISTRY`다. 이 문서는 행 목록을 옮겨 적지 않는다. 옮겨 적은 목록은 +행이 늘 때 따라오지 않았다(1106/05-01). StoragePort(`getStorageDefinition`)는 +`classification: "sensitive-forbidden"` 행과 `backend: "external"` 행을 거절하고 +나머지 행만 읽고 쓴다. `src/adapters/storage/browser-storage-codec.ts`와 `browser-storage-adapter.ts`는 closed JSON codec, 기본 16,384-byte 상한, schema envelope, TTL과 동일 envelope를 쓰는 memory fallback을 제공한다. @@ -132,7 +134,7 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는 | --- | --- | --- | --- | --- | | memory QueryClient | `COMPOSED` | server-state generation별 생성(session identity 변경 시 FENCED 뒤 새 client), global stale/gc/retry default | per-query policy | `DESIGNED_NOT_IMPLEMENTED` | | application query bridge | `COMPOSED` | AbortSignal, stale error, optimistic rollback/conflict surface | old-generation query/mutation callback 폐기 | `DESIGNED_NOT_IMPLEMENTED` | -| Web Storage | `COMPOSED` | 두 key, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | +| Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행, strict v1 envelope/codec, lazy TTL, global 16 KiB cap | per-key cap, HIT/MISS, durability, v2 scope, migration, sweep/logout | `DESIGNED_NOT_IMPLEMENTED` | | cross-tab invalidation | `COMPOSED` | release epoch(FNV-1a digest), versioned hint, duplicate/gap, BC→localStorage, registry pulse key, storageArea 동일성 검사, generation별 transport | composite scope epoch, durable ledger hook | `DESIGNED_NOT_IMPLEMENTED` | | generic IndexedDB | `AVAILABLE_NOT_COMPOSED` | reusable repository/maintenance runtime | product dataset schema/codec/query/policy composition | product selection `NOT_SELECTED` | | query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | 없음, registry가 disabled 강제 | stable per-query record, bounded restore, namespace epoch/CAS | `DESIGNED_NOT_IMPLEMENTED` | @@ -1403,8 +1405,7 @@ invalidate-only runtime은 installed query contract가 실제로 소비하므로 | capability | 기본 | | --- | --- | | TanStack memory QueryClient | `COMPOSED` | -| 등록된 COLOR_SCHEME localStorage | `COMPOSED` | -| 등록된 CHUNK_RELOAD_GUARD sessionStorage | `COMPOSED` | +| `STORAGE_REGISTRY`의 StoragePort 행(`localStorage`·`sessionStorage`) | `COMPOSED` | | generic IndexedDB repository/maintenance reference | `AVAILABLE_NOT_COMPOSED` | | IndexedDB query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | | product query persistence | `NOT_SELECTED` | diff --git a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md index 571fbd94..b7c79db4 100644 --- a/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md +++ b/docs/architecture/decisions/VD-13-client-cache-scope-and-persistence.md @@ -63,7 +63,7 @@ runtime의 구현 상태고, 후자는 제품 capability 선택 상태다. 하 | capability | 현재 상태 | 현재 보장 | | --- | --- | --- | | TanStack Query memory runtime | `COMPOSED` | runtime별 QueryClient, finite inactive GC, retry owner, query AbortSignal | -| registered Web Storage | `COMPOSED` | `COLOR_SCHEME`, `CHUNK_RELOAD_GUARD`만 strict codec/envelope로 사용 | +| registered Web Storage | `COMPOSED` | `STORAGE_REGISTRY`의 StoragePort 행만 strict codec/envelope로 사용. 행 목록은 `src/contracts/storage-keys.ts`가 정본이다 | | invalidate-only cross-tab runtime | `COMPOSED` | versioned topic, BroadcastChannel 우선, localStorage pulse fallback | | generic IndexedDB repository/maintenance runtime | `AVAILABLE_NOT_COMPOSED` | CAS, idempotency, transaction complete, policy binding, bounded lifecycle/migration | | session/account-scoped QueryClient lifecycle | `DESIGNED_NOT_IMPLEMENTED` | 없음; 현재 cache epoch는 release ID만 포함 | @@ -392,8 +392,10 @@ type WebStorageDefinition = Readonly<{ | 한 sweep에서 검사할 key | 16 | | 한 read에서 migration step | 2 | -현재 두 key는 각각 더 좁은 codec을 유지한다. `COLOR_SCHEME`은 public -origin-shared preference이고 `CHUNK_RELOAD_GUARD`는 tab session control이다. +현재 StoragePort 행은 행마다 더 좁은 `valueCodec`(`color-scheme-v1`, +`opaque-string-v1`)을 유지한다. `localStorage` 행은 public origin-shared +preference이고 `sessionStorage` 행은 tab session control이다. 행 목록은 +`src/contracts/storage-keys.ts`의 `STORAGE_REGISTRY`가 정본이다. server response, credential, signed URL, File/Blob, large draft와 queue를 Web Storage에 넣지 않는다.