diff --git a/docs/architecture/client-cache-and-storage.md b/docs/architecture/client-cache-and-storage.md index 731cb08b..a71033be 100644 --- a/docs/architecture/client-cache-and-storage.md +++ b/docs/architecture/client-cache-and-storage.md @@ -41,8 +41,8 @@ | `NOT_SELECTED` | 제품 요구·owner·policy가 승인되지 않았다. | | `PLATFORM_LIMITED` | browser/platform이 요구 의미를 cross-browser로 보장하지 못한다. | -현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 한 runtime당 -`QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을 +현재 `src/adapters/query-cache/tanstack-query-cache.ts`는 server-state +generation마다 `QueryClient`를 만들고, query retry를 끄며, 30초 `staleTime`과 5분 `gcTime`을 기본값으로 사용한다. `src/bootstrap/runtime-adapters.ts`와 `src/bootstrap/runtime-application.tsx`가 이 client를 실제 provider tree에 조립한다. @@ -79,13 +79,26 @@ native two-page browser spec은 BroadcastChannel primary와 localStorage fallbac delivery/cleanup을 검증한다. 다만 production QueryClient/coordinator까지 연결한 account transition, bfcache/StrictMode lifecycle E2E는 없고, 현재 보존 artifact도 Chromium/Firefox만 통과해 WebKit을 포함한 promotion evidence는 충족하지 않는다. -localStorage fallback physical key는 아직 storage registry 밖의 상수이고 native -`StorageEvent.storageArea`도 facade에서 검증하지 않는다. +localStorage fallback physical key는 storage registry의 +`CACHE_INVALIDATION_PULSE` 항목에서 온다(`src/contracts/storage-keys.ts:102`, +`src/adapters/cross-context-invalidation/browser-cross-context-host.ts:36-37`). +host facade는 native `StorageEvent.storageArea`를 캡처한 `localStorage` 객체와 +동일성으로 비교하고(`browser-cross-context-host.ts:286-296`), core는 +`EXPECTED_LOCAL_STORAGE`로 표시된 pulse만 받는다 +(`browser-cross-context-invalidation.ts:197-201`). -현재 epoch 구현은 `release.` 하나다. session/account epoch, opaque -account partition, scope 전환 시 새 QueryClient 생성과 durable namespace epoch는 -아직 구현되지 않았다. 따라서 현재 cross-tab event는 같은 release의 등록 query -topic을 빠르게 stale 처리하는 용도에 한정된다. +현재 epoch는 release 하나다. `cacheEpoch`는 release ID의 64-bit FNV-1a digest를 +`release.<16자리 hex>`로 쓴 값이다(`browser-cross-context-host.ts:45-51`, 조립 +`src/bootstrap/runtime-adapters.ts:364-366`). 세션 identity가 바뀌면 scope +runtime이 다음 server-state generation을 열고 +(`src/adapters/query-cache/server-state-scope-runtime.ts:148`), generation마다 +새 `QueryClient`와 새 cross-context transport(새 `sourceId`·`sourceEpoch`)를 +만든다(`src/bootstrap/server-state-generation-store.ts:50-57`, +`runtime-adapters.ts:359-372`). 이전 generation의 transport는 coordinator +dispose에서 닫힌다(`src/adapters/query-cache/tanstack-cache-coordinator.ts:276-280`). +session/account epoch, opaque account partition과 durable namespace epoch는 +아직 없다. wire event에 사용자·세션 scope가 없으므로 현재 cross-tab event는 같은 +release의 등록 query topic을 빠르게 stale 처리하는 용도에 한정된다. `QUERY_REGISTRY`의 모든 현재 entry와 `createTanStackCacheCoordinator()`는 `persistence: "disabled"`만 허용한다. @@ -113,10 +126,10 @@ blocked/versionchange를 다루는 reference runtime이 있다. 이 설계는 | capability | primary current status | current implementation | target delta | delta implementation status | | --- | --- | --- | --- | --- | -| memory QueryClient | `COMPOSED` | runtime별 생성, global stale/gc/retry default | session/account scope owner, generation fence, per-query policy | `DESIGNED_NOT_IMPLEMENTED` | +| 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` | -| cross-tab invalidation | `COMPOSED` | release epoch, versioned hint, duplicate/gap, BC→localStorage | composite scope epoch, registered pulse, storageArea, durable ledger hook | `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` | | product persistence | `NOT_SELECTED` | owner/query allowlist 없음 | measured need와 explicit composition | `NOT_SELECTED` |