llm-wiki/raw/branch-notes/feature-frontend-cache-tier-cross-tab-invalidation-contract.md

title, source_type, status, id, kind, project, work_item, inherits, refines, overrides, depends_on, imports, delegates, accepts_delegations, contract_packet, branch, parent_branch, related_projects, tags, created, target_merge, status_label

title	source_type	status	id	kind	project	work_item	inherits	refines	overrides	depends_on	imports	delegates	accepts_delegations	contract_packet	branch	parent_branch	related_projects	tags	created	target_merge	status_label
branch / feature-frontend-cache-tier-cross-tab-invalidation-contract	branch-note	raw	BR-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-029	project-work-item	ca-skeleton-frontend-operational-contract	WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-029	DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1 DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001@1 DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SERVER-STATE-001@1			WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-010 WI-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-011	FE-GATE-028@1 FE-OC-012@1 FE-OC-013@1 FE-OC-023@1	DELEG-FE-009@1		1	feature-frontend-cache-tier-cross-tab-invalidation-contract		ca-skeleton-frontend ca-skeleton	branch ca-skeleton-frontend cache server-state cross-tab	2026-07-28		in-progress

branch: feature-frontend-cache-tier-cross-tab-invalidation-contract

부모 (필수)

• raw/project-notes/ca-skeleton-frontend-operational-contract

형제 branch (같은 부모, 이번 확장에서 함께 생성):

• raw/branch-notes/feature-frontend-binary-file-io-store-contract
• raw/branch-notes/feature-frontend-large-object-transfer-contract
• raw/branch-notes/feature-frontend-multi-protocol-api-transport-contract
• raw/branch-notes/feature-frontend-realtime-subscription-lifecycle-contract
• raw/branch-notes/feature-frontend-background-execution-worker-contract

브랜치 계약 패킷

• 생성 시 프로젝트 개정: 2
• 패킷 스키마: contract_packet: 1
• 완료 조건: version 파티션·탭 간 무효화·채널 부재 fallback fixture가 통과한다

상속한 프로젝트 결정

Decision Ref	Project Summary	Branch Application	Source
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CAPABILITY-001@1	신규 runtime capability 6종은 FE-REG-CAPABILITY flag로 default OFF이며 활성화는 owner·gate·runbook을 동반한다	CAP_FE_CACHE_PERSISTENCE 를 이 branch 가 소유하고 default OFF 로 유지한다	raw/project-notes/ca-skeleton-frontend-operational-contract
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001@1	탭 간 무효화는 BroadcastChannel 우선에 storage event fallback을 쓰고 leader election 없이 무효화 key만 전파한다	CrossTabSyncPort adapter 의 transport 선택과 메시지 봉투에 적용한다	raw/project-notes/ca-skeleton-frontend-operational-contract
DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SERVER-STATE-001@1	application-owned QueryCachePort와 TanStack Query adapter를 사용하고 client store에 server state를 복제하지 않는다	영속 tier 를 추가해도 QueryCachePort 를 우회하지 않는다	raw/project-notes/ca-skeleton-frontend-operational-contract

브랜치 지역 결정

Decision ID	Decision	Relation	Supporting Claims	Status
D1	영속 캐시 파티션 키는 releaseId·configSchemaVersion·apiContractVersion 세 값을 모두 포함하고 하나라도 불일치하면 복원하지 않고 폐기한다	refines DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-SERVER-STATE-001@1	근거 raw 미수집 (FE-Q-011)	proposed
D2	탭 간 메시지는 무효화 key 만 싣고 값을 싣지 않는다	refines DEC-CA-SKELETON-FRONTEND-OPERATIONAL-CONTRACT-CROSS-TAB-001@1	근거 raw 미수집 (FE-Q-011)	proposed
D3	CachePersistencePort 는 BlobStorePort 를 재사용하지 않고 자체 백엔드를 가진다	local	근거 raw 미수집 (FE-Q-011)	proposed

선언한 예외

해당 없음.

가져온 artifact 계약

Artifact Ref	Owner	Producer	Schema Ref

가져온 프로젝트 계약

Ref	Owner	요약	Branch 적용
FE-GATE-028@1	raw/project-notes/ca-skeleton-frontend-operational-contract	version 파티션·탭 간 무효화 fixture 가 실패하면 merge 를 MUST 차단	이 branch 가 owner 로서 fixture 와 report 를 산출
FE-OC-012@1	raw/branch-notes/feature-server-state-caching-contract	query key와 invalidation은 registry factory만 MUST 사용	탭 간 전파도 factory key 만 사용
FE-OC-013@1	raw/branch-notes/feature-frontend-storage-registry-contract	storage key는 namespace·version·classification을 MUST 가지며 token/secret 저장을 금지	QUERY_CACHE_SNAPSHOT 행을 소비
FE-OC-023@1	raw/branch-notes/feature-frontend-contract-compatibility-governance	API/config/storage/release schema의 breaking change는 migration 또는 version bump 없이 배포하면 안 됨	파티션 키 불일치 시 폐기 규칙이 migration 대체

수신한 위임

없음. 이 branch 는 DELEG-FE-009 의 delegator 다.

가져온 흐름 단계

Stage Ref	Order	Owner	Input	Action	Output

목표

CachePersistencePort 와 CrossTabSyncPort 를 정의하고, memory↔session↔local↔IndexedDB 캐시 계층과 탭 간 무효화를 고정한다. 이 계약이 없으면 탭 A 의 mutation 이 탭 B 의 캐시를 무효화하지 않아 두 탭이 서로 다른 사실을 보여주고, release 를 넘어 살아남은 영속 캐시가 새 스키마로 파싱되어 렌더 트리 깊은 곳에서 터진다.

• 이슈:
• PR:

범위

포함 범위

• CachePersistencePort — 캐시 스냅샷 직렬화·영속·복원과 복원 거부
• CrossTabSyncPort — BroadcastChannel 우선, storage event fallback, 채널 부재 시 탭 내 무효화만
• persistenceTier·crossTabScope 규칙(FE-REG-QUERY 확장) 소비
• release·config·API version 파티션과 불일치 시 폐기
• CAP_FE_CACHE_PERSISTENCE capability 행 소유

제외 범위

• use case, domain model, business rule — port 와 adapter 계약까지만 정의한다
• QueryCachePort 의 정책(stale time·gc·refetch·invalidation 매핑) — raw/branch-notes/feature-server-state-caching-contract 소유
• physical storage key·namespace·classification·quota fallback — DELEG-FE-009 로 raw/branch-notes/feature-frontend-storage-registry-contract 에 위임
• offline-first 동기화 충돌 해결(CRDT·last-write-wins 등)
• leader election 기반 단일 리더 동기화 — FE-D028 이 명시적으로 배제

근거 (필수, 최소 1개+)

Source	정당화하는 결정
[[docs/superpowers/specs/2026-07-28-ca-skeleton-frontend-runtime-adapter-features-design]] §5.1·§6.2	port 분해와 FE-REG-QUERY 확장
raw/official-docs/tanstack-query-server-state-official	QueryCachePort 정책의 상위 근거 (persistence 는 이 문서가 다루지 않음)
raw/project-notes/ca-skeleton-frontend-operational-contract §5.7·§9.2	query key registry 와 cache defaults

근거 등급 경계: FE-D028(탭 간 무효화 transport)의 rationale 은 project-local default, 외부 source claim 아님 이다. TanStack Query 공식 문서는 persister 를 다루지만 이 repo 의 raw 발췌에는 그 내용이 없으며, BroadcastChannel·storage event 근거도 미수집이다(FE-Q-011).

TODO

• CachePersistencePort 인터페이스와 파티션 키 규칙 확정 — 등급: planned
• CrossTabSyncPort 인터페이스와 메시지 봉투 확정 — 등급: planned
• version 불일치 캐시 폐기 fixture — 등급: planned
• 탭 A mutation → 탭 B 무효화 integration fixture — 등급: planned
• BroadcastChannel 부재 시 storage event fallback fixture — 등급: planned
• 두 transport 모두 불가 시 CROSS_TAB_CHANNEL_UNAVAILABLE 처리 — 등급: planned
• FE-GATE-028 cache tier report 산출 — 등급: planned

진행 중 메모

crossTabScope: same-origin 이 값이 아니라 key 만 전파하는 이유는 두 가지다. 값을 전파하면 (1) 수신 탭이 자기 권한으로 얻지 않은 데이터를 갖게 되고, (2) 메시지가 커져 storage event fallback 의 크기 제한에 부딪힌다. 수신 탭은 key 를 받아 자기 QueryCachePort 로 refetch 한다.

결정 사항

• 2026-07-28: 파티션 키에 세 version 을 모두 포함 / 이유: 하나만 쓰면 config 만 바뀐 배포에서 stale 캐시가 살아남음 / 검토한 대안: releaseId 단독 / 근거: 근거 raw 미수집, project-local 판단 (FE-Q-011)
• 2026-07-28: leader election 미도입 / 이유: 탭 간 무효화에 리더가 필요 없고 리더 선출 자체가 새 실패 모드 / 검토한 대안: Web Locks 기반 리더 / 근거: FE-D028

결정-근거 매핑

Decision ID	Decision	선택 조건 (언제 이 결정 / 언제 대안)	Supporting Claims	Evidence Strength	Open Risk
D1	세 version 파티션 + 불일치 시 폐기	항상. migration 이 폐기보다 싼 대용량 캐시가 생기면 재검토	없음 — FE-Q-011	project-local default	매 배포마다 캐시가 비워져 첫 로드가 느려질 수 있음
D2	key 만 전파	항상. 값 전파가 필요한 실시간 협업 요구가 생기면 재검토	없음 — FE-Q-011	project-local default	수신 탭의 refetch 가 몰려 backend 부하가 튈 수 있음
D3	CachePersistencePort 가 자체 백엔드 보유	항상. 두 port 가 같은 IndexedDB 를 두고 quota 경쟁하면 재검토	없음 — FE-Q-011	project-local default	같은 origin 에서 두 개의 IndexedDB 사용처가 생김

구현 가이드

근거 raw 자료(FE-Q-011) 수집 전까지 비워 둔다. 지금 채우면 모든 cell 이 UNSUPPORTED_IMPL_DECISION 이 된다.

엣지·실패·의존

• 실패·엣지 경로
  • 직렬화·영속·복원 실패 → CACHE_PERSISTENCE_FAILURE, 메모리 캐시만 사용하고 제품 흐름을 막지 않음
  • BroadcastChannel 과 storage event 모두 불가 → CROSS_TAB_CHANNEL_UNAVAILABLE, 탭 내 무효화만 수행
  • 파티션 키 불일치 캐시 발견 → 복원하지 않고 폐기. 부분 복원 금지
  • 수신 탭이 무효화 key 를 받았으나 해당 query 를 구독하지 않음 → 무시 (에러 아님)
  • 다중 탭이 동시에 같은 key 를 무효화 → 중복 refetch 를 QueryCachePort 의 dedup 이 흡수해야 함
• 다른 계약 의존
  • raw/branch-notes/feature-server-state-caching-contract 의 QueryCachePort 정책에 의존 — invalidation 매핑이 바뀌면 전파 대상이 바뀜
  • raw/branch-notes/feature-frontend-storage-registry-contract 의 QUERY_CACHE_SNAPSHOT 행에 의존 (DELEG-FE-009)
  • raw/branch-notes/feature-frontend-contract-compatibility-governance 의 version tuple 에 의존 — 파티션 키가 그 tuple 에서 나옴

검증해야 할 주장

Claim	Why uncertain	How to verify	Status
version 불일치 캐시가 복원되지 않는다	부분 복원이 조용히 성공하기 쉬움	negative fixture — 이전 version 스냅샷 주입 후 복원 시도가 폐기로 끝나는지	planned
탭 A mutation 이 탭 B 캐시를 무효화한다	BroadcastChannel 은 같은 origin 의 다른 탭에서만 동작	integration test — 두 컨텍스트에서 발행/수신 확인	planned
BroadcastChannel 부재 시 storage event 로 대체된다	fallback 경로가 실제로 도달하는지 불확실	fixture — BroadcastChannel 을 undefined 로 만들고 전파 확인	planned
key 만 전파해도 UI 가 일관된다	수신 탭의 refetch 타이밍에 따라 잠깐 어긋날 수 있음	integration test — 전파 후 두 탭의 최종 상태 일치	needs-confirmation
다중 탭 동시 무효화가 refetch 폭주를 만들지 않는다	dedup 이 QueryCachePort 책임인지 이 branch 책임인지 경계가 얇음	부하 fixture — N개 탭 시뮬레이션 후 실제 요청 수 측정	needs-confirmation

관심사 커버리지 (coverage-auditor 자동 생성 — 있을 때)

미생성.

마주친 문제

없음.

묶음 (이 branch에서 파생된 자료)

Sub-branches (세부 작업)

아직 없음.

오류 기록 (이 branch 작업 중 발생)

아직 없음.

면접 준비 (이 작업에서 나올 수 있는 면접 질문)

아직 없음.

강의 (이 작업을 위해 학습한 강의)

아직 없음.

job-posting tie-ins (이 작업에서 파생된 글감)

아직 없음.

관련 일일 노트

• 아직 없음

완료 후 정리

• PR 링크:
• 리뷰 메모:
• 머지 결과 / 배포 환경:
• wiki 추출 대상 (verified만, wiki/projects/로만 추출):
  • actually-implemented 항목: 없음
  • locally-verified 항목: 없음
  • prod-verified 항목: 없음
• 추출하지 않을 항목: 현재 전 항목 planned