feat: 기능 추가 과정중

2026-07-30 15:58:20 +09:00
parent d3ef801fe6
commit 6c52cdb916
648 changed files with 126325 additions and 6680 deletions
@@ -0,0 +1,880 @@
+# VD-13: Client cache scope, persistence와 탭 간 일관성 경계
+
+- 상태: Accepted — staged implementation required
+- 결정일: 2026-07-28
+- 관련 결정: VD-10, VD-11
+- 상세 설계:
+  `docs/architecture/client-cache-and-storage.md`
+- current status ledger:
+  `docs/architecture/browser-data-capability-completion-ledger.md`
+- 재검토:
+  account/tenant switching, query persistence, SSR 또는 offline mutation을
+  제품 capability로 선택할 때
+
+## 1. 배경
+
+TanStack Query memory cache, Web Storage, IndexedDB와 BroadcastChannel은 모두
+client state에 관여하지만 같은 authority, 수명과 commit point를 갖지 않는다.
+
+- TanStack Query memory cache는 현재 JavaScript runtime의 server-state projection다.
+- `localStorage`와 `sessionStorage`는 작은 preference/control record를 위한
+  동기식 browser storage다.
+- IndexedDB는 transaction, index와 durable structured record를 제공한다.
+- BroadcastChannel과 `storage` event는 같은 storage partition 안의 best-effort
+  notification이다.
+- SSR dehydration과 browser persistence hydration은 서로 다른 source에서 생성된
+  cache projection을 합치는 별도 protocol이다.
+
+현재 skeleton은 memory QueryClient, 두 개의 등록 Web Storage key와
+invalidate-only cross-tab runtime을 production bootstrap에 조립한다. domain-neutral
+IndexedDB runtime은 source와 native contract test가 있지만 product dataset 없이
+bootstrap에서 제외돼 있다. IndexedDB query persister, durable namespace epoch,
+session/account-scoped QueryClient lifecycle과 SSR hydration은 아직 구현되지
+않았다.
+
+이 차이를 숨긴 채 “client cache가 구현됐다”고 표현하면 다음 문제가 생긴다.
+
+- logout 뒤 old account의 cache나 늦은 async result가 새 account 화면에 나타남
+- best-effort invalidation event를 authorization 또는 server commit으로 오인함
+- 여러 tab의 full cache snapshot이 서로 오래된 record를 다시 살림
+- browser persistence가 최신 SSR payload를 덮음
+- Web Storage memory fallback 성공과 durable write 성공을 구분하지 못함
+- query cache를 offline command repository처럼 사용해 unsynced user data를
+  eviction으로 잃음
+
+## 2. 표준 capability 상태
+
+이 결정과 상세 설계는 다음 상태만 사용한다.
+
+| 상태 | 의미 |
+| --- | --- |
+| `COMPOSED` | 구현·계약·test가 있고 production bootstrap이 실제 생성·소비한다. |
+| `AVAILABLE_NOT_COMPOSED` | reusable runtime과 test가 있지만 production bootstrap에서 생성하지 않는다. |
+| `DESIGNED_NOT_IMPLEMENTED` | 경계와 invariant는 승인됐지만 실행 코드가 없다. |
+| `NOT_SELECTED` | 제품 요구·owner·policy가 승인되지 않아 설치 대상이 아니다. |
+| `PLATFORM_LIMITED` | browser/platform이 요구 의미를 cross-browser로 보장하지 못한다. |
+
+`AVAILABLE_NOT_COMPOSED`와 `NOT_SELECTED`는 같은 말이 아니다. 전자는 reusable
+runtime의 구현 상태고, 후자는 제품 capability 선택 상태다. 하나의 capability에
+두 축이 필요하면 “reference runtime”과 “product selection”을 별도 행으로 쓴다.
+
+### 2.1 현재 상태
+
+| 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로 사용 |
+| 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만 포함 |
+| strict query policy/key codec | `DESIGNED_NOT_IMPLEMENTED` | 현재 object key order canonicalization만 존재 |
+| IndexedDB query persistence facade | `DESIGNED_NOT_IMPLEMENTED` | persistence는 registry에서 강제로 disabled |
+| durable namespace invalidation ledger | `DESIGNED_NOT_IMPLEMENTED` | 없음 |
+| product query persistence | `NOT_SELECTED` | persist 대상 query/owner가 없음 |
+| SSR dehydration/hydration | `NOT_SELECTED` | 현재 runtime은 client SPA composition |
+| exactly-once cross-tab delivery | `PLATFORM_LIMITED` | BroadcastChannel/storage event는 acknowledgement를 제공하지 않음 |
+| browser storage non-eviction guarantee | `PLATFORM_LIMITED` | persist 요청도 user-agent eviction을 절대 금지하지 않음 |
+
+## 3. 결정
+
+### 3.1 하나의 cache/storage abstraction으로 합치지 않는다
+
+다음 경계를 유지한다.
+
+```text
+server response
+  -> feature application result
+    -> query inbound adapter
+      -> scope-owned TanStack QueryClient
+
+small approved preference/control value
+  -> registered Web Storage facade
+    -> exact localStorage/sessionStorage key
+
+optional reconstructable query projection
+  -> query persistence facade
+    -> query-specific stable wire codec
+      -> governance-bound IndexedDB runtime
+
+committed mutation
+  -> local namespace invalidation
+  -> optional durable namespace epoch commit
+  -> best-effort cross-tab hint
+```
+
+QueryClient, native `Storage`, `IDBDatabase`, BroadcastChannel, dehydrated TanStack
+types와 physical key/store/index 이름을 application/domain에 노출하지 않는다.
+
+### 3.2 source of truth와 authority
+
+1. 일반 server state와 authorization의 source of truth는 서버다.
+2. memory cache와 persisted query record는 재구성 가능한 projection이다.
+3. cache hit, persisted restore와 invalidation event는 authorization proof가 아니다.
+4. 모든 protected network request는 현재 session credential과 server
+   authorization을 다시 통과한다.
+5. remote invalidation event는 `invalidate`만 요청할 수 있다. `remove`, `clear`,
+   logout, account deletion과 credential revocation authority를 갖지 않는다.
+6. unsynced command, local-first draft와 user-authored offline data는 query
+   persistence에 저장하지 않는다. feature-specific IndexedDB repository와
+   sync use case가 소유한다.
+
+## 4. session/account/release scope
+
+### 4.1 immutable scope snapshot
+
+composition의 session authority는 다음 의미를 갖는 immutable snapshot을 발급한다.
+구현 type과 field name은 이 의미를 보존해야 한다.
+
+```ts
+type CacheScopeSnapshot = Readonly<{
+  protocolVersion: 1;
+  authorityToken: string;
+  partitionToken: string;
+  sessionEpoch: string;
+  accountEpoch: string;
+  releaseEpoch: string;
+  generation: number;
+}>;
+```
+
+- 모든 token은 registry/session authority가 발급한 충분한 entropy의 opaque
+  identifier다.
+- email, account/tenant/user ID, domain ID, access token과 낮은 entropy identifier의
+  단순 hash를 사용하지 않는다.
+- `generation`은 현재 page runtime에서 단조 증가하는 local lifecycle fence다.
+  backend entity revision이나 wire ordering으로 사용하지 않는다.
+- `sessionEpoch`는 sign-in, re-auth, credential owner 교체 때 바뀐다.
+- `accountEpoch`는 account/tenant switch, logout, account deletion 때 바뀐다.
+- `releaseEpoch`는 query-key, mapper, codec 또는 persistence wire compatibility가
+  깨질 때 바뀐다.
+- scope object와 nested policy는 construction 때 copy/freeze한다. async operation은
+  시작 시 exact snapshot과 generation을 캡처한다.
+
+### 4.2 profile별 scope projection
+
+모든 query가 account token을 key에 넣지는 않는다. registry가 분류에 따라 다음을
+고정한다.
+
+| scope | binding |
+| --- | --- |
+| `ORIGIN_SHARED` | release epoch와 origin-shared token |
+| `ACCOUNT_BOUND` | partition token, account epoch, release epoch |
+| `SESSION_BOUND` | partition token, account epoch, session epoch, release epoch |
+
+- `PUBLIC`만 `ORIGIN_SHARED`를 사용할 수 있다.
+- `INTERNAL`은 제품 authority가 origin-shared public semantics를 증명하지 않는 한
+  `ACCOUNT_BOUND` 이상이다.
+- `PERSONAL`은 `ACCOUNT_BOUND` 이상이고 persistence에는 explicit approval,
+  bounded retention과 logout purge가 필요하다.
+- `CONFIDENTIAL`은 query persistence가 금지되고 필요한 순간의 memory
+  `SESSION_BOUND`만 허용한다.
+- credential은 memory query data, persistence, query key와 invalidation wire
+  모두에서 금지한다.
+
+### 4.3 composite cache epoch
+
+cross-tab `cacheEpoch`는 raw token을 연결한 문자열이 아니라 선택된 scope projection과
+protocol major의 opaque compatibility fingerprint다. receiver는 exact equality만
+검사하고 원래 account/session/release 의미 값을 wire에서 복원하지 않는다.
+
+현재 `release.<releaseId>`만 사용하는 값은 transitional implementation이다.
+account-dependent query를 production에 설치하기 전에 composite scope fingerprint로
+교체한다.
+
+## 5. QueryClient lifecycle와 late-result fence
+
+### 5.1 runtime state
+
+scope-owned query runtime은 다음 terminal lifecycle을 갖는다.
+
+```text
+CREATING
+  -> ACTIVE
+  -> FENCING
+  -> DISPOSING
+  -> DISPOSED
+```
+
+- `ACTIVE`만 신규 query/mutation/cache update를 admission한다.
+- scope transition이 시작되면 먼저 `FENCING`으로 바꾸고 generation을 올린다.
+- `DISPOSING`에서 old query를 cancel하고 provider/controller를 detach한 뒤
+  QueryClient를 clear한다.
+- old cross-tab channel, persistence writer/connection, timer와 listener를 닫는다.
+- exact old Web Storage key/IndexedDB partition purge는 policy와 authority를
+  통과한 bounded lifecycle operation으로 수행한다.
+- 새 scope는 새 QueryClient와 새 coordinator를 만든다. old client를 재사용해
+  key prefix만 바꾸지 않는다.
+- dispose와 scope transition은 idempotent하다.
+
+### 5.2 query fence
+
+query execution은 TanStack의 AbortSignal과 scope generation을 모두 캡처한다.
+
+1. 시작 전 runtime이 `ACTIVE`인지 확인한다.
+2. application request에 AbortSignal을 전달한다.
+3. 완료 시 captured generation과 current generation을 비교한다.
+4. mismatch면 성공/실패 모두 새 cache/UI에 적용하지 않고 `STALE_RESULT`로
+   폐기한다.
+5. query cancellation 실패가 scope clear를 막지 않게 하되 safe diagnostic을
+   남긴다.
+
+### 5.3 mutation fence
+
+frontend abort는 이미 서버에 도달한 mutation을 되돌리지 않는다.
+
+- 시작 전 admission과 generation을 확인한다.
+- server commit 전 cancellation은 transport의 idempotency/cancellation 계약을
+  따른다.
+- server 결과가 old generation에서 돌아오면 새 cache에 optimistic result,
+  invalidation 또는 success UI를 적용하지 않는다.
+- server side effect의 authoritative 결과는 새 scope에서 정상 revalidation한다.
+- mutation success 후 local invalidation 실패나 hint publish 실패가 이미 committed
+  server mutation을 실패로 바꾸지 않는다.
+- conflict resolution은 backend revision/ETag/idempotency 계약과 feature policy가
+  소유한다. query cache는 business merge authority가 아니다.
+
+### 5.4 session owner 연결
+
+production bootstrap은 auth/session owner subscription을 query lifecycle에
+연결한다. 단순 `authenticated` boolean만으로 account identity를 추론하지 않는다.
+owner는 opaque scope snapshot 또는 이를 발급할 authority를 제공해야 한다.
+
+다른 tab의 logout은 cache invalidation event에 의존하지 않는다. 각 tab의 auth
+owner가 credential/session 변화를 독립적으로 감지하고 local lifecycle을
+실행해야 한다.
+
+## 6. strict query scope/persistence registry와 key codec
+
+### 6.1 registry
+
+모든 installed query namespace는 immutable scope/persistence profile을 갖는다.
+freshness, GC, refetch, retry, result budget, pagination과 conditional policy의
+유일한 source of truth는 VD-25 `ServerStateProfile`이다.
+
+```ts
+type QueryScopePersistencePolicy = Readonly<{
+  policyId: string;
+  namespace: readonly [string, number];
+  keySchemaVersion: number;
+  classification: "PUBLIC" | "INTERNAL" | "PERSONAL" | "CONFIDENTIAL";
+  scope: "ORIGIN_SHARED" | "ACCOUNT_BOUND" | "SESSION_BOUND";
+  persistence:
+    | Readonly<{ kind: "MEMORY_ONLY" }>
+    | Readonly<{
+        kind: "INDEXEDDB";
+        profileId: string;
+        maxAgeMs: number;
+        maxEntryBytes: number;
+      }>;
+  crossTab: "NONE" | "INVALIDATE";
+  invalidationTopics: readonly Readonly<{
+    topicId: string;
+    topicVersion: number;
+  }>[];
+}>;
+```
+
+construction은 최소 다음을 검증한다.
+
+- namespace/topic/policy ID가 closed syntax와 unique version을 가짐
+- persistence가 classification, scope, max age와 맞음
+- `NONE`은 topic 0개, `INVALIDATE`는 namespace당 unique topic 1..8개
+- `(topicId, topicVersion)` 하나는 최대 32개 namespace에 fan-out하며 global
+  topic→namespace set과 namespace→topic set이 서로 exact inverse
+- profile과 nested allowlist를 deep snapshot/freeze함
+- VD-25 query definition/`ServerStateProfile`과 join했을 때 owner,
+  classification, scope, namespace, persistence와 invalidation topic set/version이
+  일치함
+
+composition은 `QueryDefinition -> QueryScopePersistencePolicy ->
+ServerStateProfile`을 exact ID로 join한 뒤에만 TanStack option을 만든다. global
+QueryClient default는 안전 baseline일 뿐이고 installed query의 정책 증거가
+아니다.
+
+### 6.2 query key wire subset
+
+query key factory의 canonical input은 다음만 허용한다.
+
+- `null`, boolean, finite number, bounded string
+- 위 값의 dense array
+- own enumerable data property만 가진 plain/null-prototype object
+
+다음을 fail-closed로 거절한다.
+
+- cycle/shared exotic graph
+- `undefined`, `BigInt`, symbol, function, accessor
+- `NaN`, infinity, negative zero를 구분하지 않는 암묵 변환
+- Date, RegExp, Map, Set, class/DOM/native object
+- File, Blob, ArrayBuffer와 typed array
+- sparse array
+- `__proto__`, `prototype`, `constructor` key
+- 허용 depth/node/part/string/serialized-byte ceiling 초과
+
+구현 절대 상한:
+
+| 항목 | 상한 |
+| --- | ---: |
+| installed query profile | 256 |
+| query key top-level part | 16 |
+| canonical value depth | 8 |
+| canonical value node | 256 |
+| 단일 string UTF-8 | 1,024 bytes |
+| 전체 canonical key UTF-8 | 4,096 bytes |
+
+제품 profile은 더 낮출 수 있지만 이 상한을 높이려면 ADR amendment와
+memory/telemetry cardinality evidence가 필요하다.
+
+normative key layout:
+
+```text
+[
+  "query",
+  keySchemaVersion,
+  scopeFingerprint,
+  namespaceName,
+  namespaceVersion,
+  queryDefinitionVersion,
+  canonicalSemanticInput
+]
+```
+
+VD-25는 이 배열을 재정의하지 않고 마지막 두 field의 의미와 pagination
+projection만 소유한다. query function이 의존하는 모든 non-secret input을
+포함하되 URL 전체, bearer
+token, email, filename, human-readable personal label을 넣지 않는다. domain entity
+identity가 필요하면 backend/product contract가 발급한 opaque ID와 bounded codec을
+사용한다.
+
+### 6.3 memory pressure
+
+`gcTime`은 inactive retention이지 active cache hard cap이 아니다.
+
+- gateway/mapper가 response count/byte ceiling을 검증한다.
+- binary, native object와 unbounded collection을 query cache에 넣지 않는다.
+- cache entry/active/inactive와 estimated payload를 safe bucket으로 관측한다.
+- hard eviction controller는 joined VD-25 profile별 정책으로만 설치한다.
+- memory pressure를 이유로 active personal data를 arbitrary global timer로
+  삭제하지 않는다. scope lifecycle의 remove/clear와 일반 eviction을 구분한다.
+
+## 7. Web Storage contract
+
+### 7.1 registered key policy
+
+Web Storage는 registered small value 전용이다.
+
+```ts
+type WebStorageDefinition<Value> = Readonly<{
+  logicalName: string;
+  backend: "localStorage" | "sessionStorage";
+  scope: "ORIGIN_SHARED" | "OPAQUE_PARTITION" | "TAB";
+  classification: "PUBLIC_PREFERENCE" | "OPAQUE_CONTROL";
+  schemaVersion: number;
+  maxSerializedBytes: number;
+  retention:
+    | Readonly<{ kind: "SESSION" }>
+    | Readonly<{ kind: "TTL"; maxAgeMs: number }>
+    | Readonly<{ kind: "EXPLICIT_DELETE" }>;
+  valueCodec: string;
+  migration:
+    | Readonly<{ kind: "DISCARD" }>
+    | Readonly<{ kind: "ADJACENT"; migrationId: string }>;
+  quotaFallback: "MEMORY" | "NO_PERSIST" | "FEATURE_DISABLE";
+  logoutAction: "KEEP" | "PURGE_PARTITION";
+}>;
+```
+
+구현 절대 상한:
+
+| 항목 | 상한 |
+| --- | ---: |
+| registered persistent key | 64 |
+| key별 serialized value | 16,384 bytes |
+| 한 sweep에서 검사할 key | 16 |
+| 한 read에서 migration step | 2 |
+
+현재 두 key는 각각 더 좁은 codec을 유지한다. `COLOR_SCHEME`은 public
+origin-shared preference이고 `CHUNK_RELOAD_GUARD`는 tab session control이다.
+server response, credential, signed URL, File/Blob, large draft와 queue를 Web
+Storage에 넣지 않는다.
+
+### 7.2 physical identity와 envelope
+
+physical key는 application/environment, scope kind, opaque partition 또는 tab
+instance, logical key, schema version에서 결정적으로 파생한다. account/user ID를
+포함하거나 origin 전체 key를 열거하지 않는다.
+
+partition-aware 새 envelope는 기존 v1 세 필드의 의미를 변경하지 않고 새
+envelope version으로 도입한다.
+
+```ts
+type BrowserStorageEnvelopeV2 = Readonly<{
+  envelopeVersion: 2;
+  schemaVersion: number;
+  scopeFingerprint: string;
+  writtenAtEpochMs: number;
+  expiresAtEpochMs: number | null;
+  value: unknown;
+}>;
+```
+
+- exact field set, schema, scope, codec, written/expiry time 순으로 검증한다.
+- TTL expiry는 write time과 registry max age에서 계산하며 caller가 직접 주지 않는다.
+- 비정상적으로 먼 expiry, future write time과 clock skew는 fail-closed miss다.
+- corrupt/expired/future/wrong-scope record는 exact key만 best-effort 제거한다.
+- cleanup 실패는 validated miss를 raw exception으로 바꾸지 않는다.
+- memory overlay도 exact envelope와 TTL/scope validation을 공유한다.
+
+### 7.3 read/write outcome
+
+stored `undefined`와 miss를 암묵적으로 합치지 않는다.
+
+```ts
+type WebStorageReadResult<Value> =
+  | Readonly<{ ok: true; state: "HIT"; value: Value; durability: "PERSISTED" | "MEMORY_ONLY" }>
+  | Readonly<{ ok: true; state: "MISS" }>
+  | Readonly<{ ok: false; error: ClientStorageFailure }>;
+
+type WebStorageWriteResult =
+  | Readonly<{ ok: true; durability: "PERSISTED" }>
+  | Readonly<{ ok: true; durability: "MEMORY_ONLY"; degraded: true }>
+  | Readonly<{ ok: false; error: ClientStorageFailure }>;
+```
+
+memory fallback이 current runtime에서 승인된 성공이면 `ok: true`와
+`MEMORY_ONLY`를 반환한다. durable write가 필수인 key는 fallback을 성공으로
+가장하지 않는다.
+
+### 7.4 migration, quota와 sweep
+
+- migration은 registry에 등록된 deterministic adjacent version만 실행한다.
+- migration callback은 network/native storage/telemetry side effect 없이 bounded
+  pure codec으로 동작한다.
+- future version과 unsupported old version은 `DISCARD` policy에서 miss다.
+- `QuotaExceededError`이면 reconstructable exact key cleanup 뒤 동일 idempotent
+  write를 최대 한 번 재시도한다.
+- origin 전체 `clear()`와 arbitrary LRU key enumeration을 금지한다.
+- TTL은 visibility rule이므로 boot/idle/focus 중 registry-owned bounded sweep을
+  별도로 수행한다.
+- logout/account switch는 exact partition key만 purge한다. public origin-shared
+  preference를 지우지 않는다.
+- `sessionStorage` opener snapshot을 authority로 사용하지 않는다. tab-local
+  control에는 새 tab instance와 `noopener` policy를 적용한다.
+
+## 8. optional IndexedDB query persistence
+
+### 8.1 selection
+
+query persistence reference facade의 현재 상태는
+`DESIGNED_NOT_IMPLEMENTED`, product selection은 `NOT_SELECTED`다. 단순 warm-start
+기대만으로 자동 설치하지 않는다.
+
+다음 조건을 모두 충족한 query만 등록한다.
+
+- server-authoritative이며 재구성 가능함
+- stable query-key와 payload codec이 있음
+- classification/scope/retention owner 승인
+- entry/dataset/restore byte와 count budget이 있음
+- logout/account deletion/release busting이 정의됨
+- measured offline/warm-start 가치가 있음
+- three-engine native contract와 rollback evidence가 있음
+
+### 8.2 stable record, raw TanStack snapshot 금지
+
+full QueryClient snapshot이나 library-private object를 그대로 저장하지 않는다.
+
+```ts
+type PersistedQueryRecord = Readonly<{
+  recordVersion: 1;
+  queryHash: string;
+  encodedQueryKey: unknown;
+  policyId: string;
+  scopeFingerprint: string;
+  releaseEpoch: string;
+  namespaceEpoch: number;
+  dataUpdatedAtEpochMs: number;
+  persistedAtEpochMs: number;
+  expiresAtEpochMs: number;
+  payloadCodecVersion: number;
+  payload: unknown;
+  measuredBytes: number;
+  revision: number;
+}>;
+```
+
+- approved successful query data만 저장한다.
+- error, pending state, mutation, function, Promise, AbortSignal, native/binary
+  object, credential와 capability를 저장하지 않는다.
+- query key와 payload를 각각 strict codec으로 검증한다.
+- generic IndexedDB runtime의 opaque scope/policy binding, transaction complete,
+  CAS, byte budget, migration, lifecycle와 failure mapping을 재사용한다.
+
+### 8.3 구현 상한
+
+reference facade의 기본 절대 상한:
+
+| 항목 | 상한 |
+| --- | ---: |
+| persisted query record | 1,024 |
+| 단일 encoded entry | 512 KiB |
+| query persistence dataset | 32 MiB |
+| 한 restore record | 256 |
+| 한 restore decoded bytes | 8 MiB |
+| boot restore deadline | 2,000 ms |
+| max age | 7 days |
+| write debounce | 250–2,000 ms |
+
+제품 policy는 더 낮출 수 있다. 상한 확대는 memory/quota/startup-latency evidence와
+ADR amendment가 필요하다.
+
+### 8.4 durable namespace epoch
+
+full snapshot last-write-wins를 금지한다. 기본 writer model은 shared per-query
+record + monotonic namespace epoch다.
+
+```ts
+type DurableCacheLedger = Readonly<{
+  ledgerVersion: 1;
+  scopeFingerprint: string;
+  releaseEpoch: string;
+  namespaces: Readonly<Record<string, number>>;
+  revision: number;
+}>;
+```
+
+- mutation invalidation은 namespace epoch를 같은 IndexedDB transaction에서
+  증가시킨 뒤 cross-tab hint를 publish한다.
+- persisted record의 namespace epoch가 ledger보다 작으면 hydrate하지 않는다.
+- record write는 current ledger epoch와 revision을 CAS 검증한다.
+- BroadcastChannel sequence나 wall clock을 global durable ordering으로 사용하지
+  않는다.
+- localStorage read-modify-write counter와 best-effort leader election을 correctness
+  fence로 쓰지 않는다.
+- ledger commit 뒤 hint를 publish한다. hint가 먼저 나가면 receiver가 commit 전
+  record를 읽을 수 있다.
+
+### 8.5 restore와 hydration order
+
+1. bounded deadline으로 IndexedDB를 연다.
+2. immutable dataset/scope/release binding을 검증한다.
+3. ledger와 record schema/codec/TTL/byte cap을 검증한다.
+4. approved profile과 current namespace epoch만 decode한다.
+5. current memory/SSR state와 precedence를 적용한다.
+6. hydrate 뒤 normal stale/refetch policy를 실행한다.
+
+wrong scope, expired, busted와 corrupt reconstructable record는 cache miss로
+격하하고 exact bounded cleanup한다. persistence unavailable/blocked/timeout은
+제품이 optional로 선택했다면 memory+network `ONLINE_ONLY`로 fail open한다.
+offline-required workflow를 query persistence로 가장하지 않는다.
+
+### 8.6 writer lifecycle
+
+- cache events는 bounded debounce/coalescing한다.
+- writer 하나에서 concurrent save를 serialize하고 superseded write를 버린다.
+- `pagehide`/`beforeunload` transaction 완료를 보장으로 간주하지 않는다.
+- 정상 runtime 중 주기적으로 commit하고 unload flush는 보조 수단이다.
+- dispose는 timer를 취소하고 connection/listener를 닫는다.
+- 아직 transaction complete가 아닌 write를 persisted success로 기록하지 않는다.
+
+## 9. cross-tab invalidation
+
+### 9.1 authority
+
+cross-tab wire는 payload/query-key-free invalidate hint만 전달한다.
+
+- query state/data replication 금지
+- authorization/logout/server commit 증명 금지
+- distributed lock/leader election 금지
+- exactly-once/ordered delivery 주장 금지
+- offline command 전송 금지
+
+remote hint는 registry topic을 local namespace로 해석해 active query를
+invalidate/refetch한다. inactive query는 다음 mount/focus/freshness 정책에서
+revalidate한다. remote hint는 `removeQueries`, `clear()` 또는 session transition을
+직접 실행하지 않는다.
+
+### 9.2 transport와 source validation
+
+```text
+BroadcastChannel
+  -> construction/post failure
+    -> registered localStorage pulse + storage event
+      -> failure/unavailable
+        -> DEGRADED_LOCAL_ONLY + normal stale/focus/reconnect
+```
+
+- current 2,048-byte exact wire envelope와 bounded TTL/dedupe/source tracking을
+  유지한다.
+- topic registry 수에도 query profile과 같은 256개 절대 상한을 적용한다.
+- localStorage fallback key를 Web Storage control registry에 등록한다.
+- receiver는 exact key, exact `storageArea === localStorage`, exact composite
+  cache epoch와 event codec을 검증한다.
+- `sessionStorage`를 cross-tab fallback으로 사용하지 않는다.
+- publisher는 local invalidation을 직접 수행한다.
+- publish success는 receiver acknowledgement가 아니다.
+- BroadcastChannel과 storage 양쪽 delivery는 event ID로 dedupe한다.
+- per-source sequence gap은 global order 증명이 아니라 “hint를 잃었을 수 있음”을
+  나타낸다.
+
+### 9.3 lost hint
+
+query persistence가 꺼져 있으면 finite stale time, focus/reconnect와 manual refresh가
+eventual revalidation을 제공한다. persistence가 켜져 있으면 visibility/focus와
+sequence gap에서 durable namespace ledger를 bounded refresh한다.
+
+즉시 global consistency가 업무 invariant라면 browser bus만으로 충족하지 않는다.
+backend revision/ETag, server push stream 또는 feature sync protocol을 추가한다.
+
+## 10. SSR 선택 경계
+
+현재 SSR product capability는 `NOT_SELECTED`다. browser-only code가 있다는 이유로
+SSR support가 구현됐다고 주장하지 않는다.
+
+SSR을 선택하면 별도 implementation gate에서 다음을 모두 구현한다.
+
+1. HTTP request마다 새 QueryClient를 생성하고 response 뒤 폐기한다.
+2. server process에서 Web Storage, IndexedDB와 BroadcastChannel에 접근하지 않는다.
+3. approved successful query만 dehydrate한다.
+4. serialized state를 HTML context에 안전하게 escape하고 byte/count cap을 적용한다.
+5. browser의 최신 SSR payload가 old persisted projection보다 우선한다.
+6. persisted state merge는 missing approved query만 복원하거나 explicit server
+   revision을 비교한다.
+7. browser storage read 때문에 initial server/client markup이 달라지지 않게
+   hydration-safe bootstrap 단계에서 restore한다.
+8. request A의 QueryClient/data/scope가 request B에 공유되지 않는 test를 둔다.
+
+SSR support와 IndexedDB query persistence는 서로 독립 선택이다.
+
+## 11. privacy와 encryption
+
+- credential, token, signed URL, authorization header, password와 crypto key는
+  memory query key/data, Web Storage, query persistence와 invalidation wire에
+  넣지 않는다.
+- logical/physical key, query key/hash input, payload, account/user ID, URL과 native
+  exception message/stack을 telemetry에 보내지 않는다.
+- 같은 origin JavaScript가 ciphertext와 key를 모두 읽을 수 있는 client-side
+  encryption은 XSS authorization boundary가 아니다.
+- external/non-extractable key lifecycle과 compliance requirement가 있는 제품은
+  encryption을 defense-in-depth로 별도 선택할 수 있지만, 금지 classification을
+  허용하는 근거가 되지 않는다.
+- logout purge는 confidentiality의 유일한 방어가 아니다. wrong-scope binding은
+  crash로 old bytes가 남아도 새 runtime이 읽지 못하게 해야 한다.
+
+## 12. failure와 observability
+
+failure는 최소 operation, closed code, retry owner, effect certainty와 fallback을
+표현한다.
+
+- `ABORTED`와 `DEADLINE_EXCEEDED`를 구분한다.
+- IndexedDB transaction `complete`만 `APPLIED`다.
+- Broadcast publish success의 remote effect는 `UNKNOWN`이다.
+- memory fallback과 persisted success를 구분한다.
+- optional persistence failure는 `ONLINE_ONLY`로 degrade할 수 있다.
+- scope mismatch/corruption/future version은 raw record를 반환하지 않는다.
+- diagnostics failure가 query, storage, lifecycle와 cleanup을 실패시키지 않는다.
+
+safe metric:
+
+- memory active/inactive/estimated-byte bucket
+- Web Storage hit/miss/degraded/quota bucket
+- persistence restore success/miss/busted/corrupt/deadline bucket
+- scope reset duration/cleanup-incomplete
+- invalidation publish/receive/drop/duplicate/gap/coalesced bucket
+- listener/channel/connection leak count
+
+## 13. implementation gate
+
+### Gate 0 — 상태와 문서
+
+- 이 ADR과 상세 설계가 current/target 상태를 분리한다.
+- capability catalog, runbook과 test evidence의 상태가 같은 taxonomy를 사용한다.
+- 구현되지 않은 target type을 current API처럼 문서화하지 않는다.
+
+### Gate 1 — strict registry와 codec
+
+- query policy registry와 query key closed codec 구현
+- profile/key absolute ceiling 구현
+- Web Storage per-key cap, HIT/MISS/durability result 구현
+- current v1 key의 discard/upgrade 전략 확정
+- hostile/cyclic/oversize/property-accessor test 통과
+
+이 gate는 scope lifecycle을 자동 활성화하지 않는다.
+
+### Gate 2 — scope-owned QueryClient lifecycle
+
+- session authority scope snapshot contract 구현
+- auth owner subscription과 local generation fence 구현
+- old query cancel/provider detach/client clear/dispose 구현
+- late query/mutation result 폐기 구현
+- account switch/logout exact partition cleanup 구현
+- two-account and lost-event tests 통과
+
+account-dependent query promotion은 이 gate 전 금지한다.
+
+### Gate 3 — cross-tab scope hardening
+
+- composite cache epoch 구현
+- registered localStorage pulse와 storageArea 검증 구현
+- browser production coordinator E2E와 bfcache/StrictMode leak test
+- Chromium/Firefox/WebKit 동일 case evidence
+
+### Gate 4 — optional query persistence reference runtime
+
+- stable query record codec와 IndexedDB facade 구현
+- durable namespace ledger/CAS/commit-before-hint 구현
+- bounded restore/write/dispose 구현
+- wrong-scope/TTL/release/migration/quota/blocked test
+- production bootstrap import와 DB open이 없는 module-inventory/removal gate
+
+완료 뒤에도 product selection은 `NOT_SELECTED`이고 reference 상태만
+`AVAILABLE_NOT_COMPOSED`로 바뀐다.
+
+### Gate 5 — product composition
+
+- measured requirement와 owner 승인
+- exact query profile/persistence allowlist/retention/budget 등록
+- account/logout/backend conflict contract 승인
+- disabled → canary → enabled traffic admission
+- rollback, cleanup-only release와 operational drill
+
+### Gate 6 — SSR 또는 offline workflow
+
+각 capability를 별도 선택하고 별도 gate를 통과한다.
+
+- SSR: request isolation, safe dehydration, precedence와 hydration test
+- offline mutation: feature repository, server idempotency/revision/sync protocol,
+  conflict/export/recovery UX
+
+query persistence gate 통과가 SSR/offline workflow 통과를 의미하지 않는다.
+
+## 14. test와 promotion evidence
+
+### 14.1 deterministic
+
+- independent QueryClient per runtime/scope
+- session/account/release transition과 late result
+- query key hostile value/ceiling/canonical equality
+- Web Storage HIT/MISS/durability, TTL, migration, quota, cleanup, partition
+- IndexedDB transaction complete, CAS, ledger epoch와 concurrent writer
+- hint commit ordering, duplicate/self/stale/gap/coalescing
+- diagnostics redaction와 dispose leak 0
+
+### 14.2 real browser
+
+Chromium, Firefox와 WebKit에서 같은 case set을 실행한다.
+
+- native BroadcastChannel two-page delivery
+- localStorage fallback과 exact storageArea
+- account switch 중 in-flight query
+- event loss 뒤 local auth lifecycle
+- IndexedDB concurrent writer/blocked/versionchange/restore deadline
+- bfcache/pagehide/StrictMode listener·connection cleanup
+- sessionStorage tab/opener semantics
+- N-1 release reader와 incompatible buster
+
+현재 native transport spec이 존재해도 production QueryClient lifecycle 전체와
+세 engine promotion artifact가 없으면 Gate 3 완료로 보지 않는다.
+
+### 14.3 promotion artifact
+
+artifact는 engine/browser version/OS image/build/release ID/contract suite
+version/pass/fail/skip/실행 시각을 보존한다. fake/jsdom 통과를 native provider
+통과로 보고하지 않는다. WebKit system dependency 부족은 capability skip이 아니라
+promotion evidence 미충족이다.
+
+## 15. rollout과 rollback
+
+### 15.1 rollout
+
+1. strict registry/codec을 기존 behavior 뒤 shadow validation으로 배포한다.
+2. scope lifecycle을 single-account environment에서 먼저 관측한다.
+3. account switch/logout fault test 뒤 account-dependent query를 허용한다.
+4. optional persistence는 source와 test만 추가하고 production composition은
+   계속 끈다.
+5. product selection 뒤 read-only restore/shadow write를 먼저 검증한다.
+6. 작은 cohort에서 write/restore/quota/blocked/rollback drill을 수행한다.
+7. error budget과 N-1 compatibility를 확인한 뒤 확대한다.
+
+### 15.2 kill switch
+
+서로 독립적으로 끌 수 있어야 한다.
+
+- persistence restore off
+- persistence write off
+- cross-tab publish off
+- cross-tab receive off
+- offline mutation admission off
+
+memory QueryClient와 정상 server fetch는 유지한다. account/session local lifecycle은
+security boundary이므로 best-effort invalidation kill switch와 함께 끄지 않는다.
+
+### 15.3 rollback
+
+1. 신규 persistence write/restore admission을 중지한다.
+2. writer/timer/channel/listener/DB connection을 dispose한다.
+3. scope fence와 memory QueryClient clear는 유지한다.
+4. rollback bundle이 future record/schema를 miss/online-only로 처리하게 한다.
+5. cleanup-only compatible release에서 exact owned partition을 bounded purge한다.
+6. retention/rollback window 뒤 registry/adapter/dependency를 제거한다.
+
+schema version을 내리거나 origin 전체 `localStorage.clear()`/
+`indexedDB.deleteDatabase()`를 자동 실행하지 않는다. unsynced user-authored data는
+export/sync 확인 없이 query-cache cleanup으로 삭제하지 않는다.
+
+## 16. 완료 기준
+
+- [ ] session/account/release scope가 QueryClient, key와 event에 binding된다.
+- [ ] scope transition은 admission fence, cancel, detach, clear, dispose와 새
+      QueryClient 생성으로 완료된다.
+- [ ] old generation query/mutation result가 새 scope UI/cache를 변경하지 않는다.
+- [ ] strict query scope/persistence registry와 closed key codec이 모든 absolute
+  ceiling을 강제하고 VD-25 profile과 exact join된다.
+- [ ] Web Storage가 per-key cap, HIT/MISS, durability, partition, logout,
+      migration과 bounded sweep을 구현한다.
+- [ ] localStorage invalidation fallback이 registered key와 exact storageArea를
+      검증한다.
+- [ ] Chromium/Firefox/WebKit production coordinator/account lifecycle evidence가
+      있다.
+- [ ] optional query persistence reference facade는 stable record와 durable
+      namespace ledger를 사용하고 production 미선택 시 zero side effect다.
+- [ ] persisted mutation/error/native object/credential이 없음을 negative test가
+      증명한다.
+- [ ] SSR을 선택한 경우 request isolation과 hydration precedence가 증명된다.
+- [ ] offline mutation을 선택한 경우 backend idempotency/revision/sync와
+      conflict/recovery UX가 별도 계약으로 증명된다.
+- [ ] rollout/kill-switch/rollback/removal artifact가 보존된다.
+
+현재 이 체크리스트는 완료 선언이 아니라 implementation gate다. 각 행을 실제
+source, deterministic test, native evidence와 composition inventory로 증명하기
+전에는 완료로 바꾸지 않는다.
+
+## 17. 선택하지 않은 대안
+
+- module singleton QueryClient
+- account switch에서 query key prefix만 교체
+- BroadcastChannel logout event를 lifecycle authority로 사용
+- arbitrary query key와 raw TanStack cache snapshot persistence
+- localStorage full-cache snapshot 또는 monotonic counter
+- browser persistence를 offline command queue로 사용
+- same-origin client encryption을 credential authorization boundary로 사용
+- origin 전체 storage clear를 quota/logout/rollback 복구로 사용
+- fake browser test만으로 production promotion
+
+## 18. 결과
+
+장점:
+
+- account/session boundary와 best-effort invalidation의 권한 차이가 명확하다.
+- persistence를 선택하지 않은 제품에는 DB open/listener/bundle side effect가 없다.
+- query key, Web Storage와 IndexedDB의 migration/retention을 독립적으로 검증한다.
+- old tab/snapshot이 invalidated data를 되살리는 경로를 durable epoch로 닫는다.
+- SSR, offline workflow와 query warm-start를 서로 독립 선택할 수 있다.
+
+비용:
+
+- scope authority와 QueryClient remount lifecycle이 필요하다.
+- registry/codec/historical fixture와 multi-page browser test가 늘어난다.
+- optional persistence를 설치하는 제품은 IndexedDB migration, quota와 cleanup
+  runbook을 운영해야 한다.
+
+이 비용은 cache hit, durable restore, cross-tab hint와 server truth를 하나의
+“cached” 상태로 잘못 합치지 않기 위한 의도적인 비용이다.