DongHyeonka
d6dfda64ab
- REGISTRY-001 Summary 문자열 4곳 (additive, revision 은 1 유지). registry-governance 는 본문 서술 12곳의 '8개'도 함께 9개로 갱신 - OFFLINE-CACHE-001 pin @1->@2 와 Summary·적용점 (behavior-change) - DELEG-FE-007~011 delegate 5곳 접수 완료 — 미접수 위임 0건 - runtime-schema-validation 이 FLOW-FE-EVENT-003/004 소유를 명시 - env-runtime-config 가 FE-REG-CAPABILITY registry 와 FE-GATE-033 gate owner 를 취득하고 claim 2건 추가 - 신규 6개 노트의 delegation pin 을 기존 @1 형식으로 정규화
14 KiB
14 KiB
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 |
|
|
|
|
1 | feature-frontend-cache-tier-cross-tab-invalidation-contract |
|
|
2026-07-28 | in-progress |
branch: feature-frontend-cache-tier-cross-tab-invalidation-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 우선,storageevent fallback, 채널 부재 시 탭 내 무효화만persistenceTier·crossTabScope규칙(FE-REG-QUERY확장) 소비- release·config·API version 파티션과 불일치 시 폐기
CAP_FE_CACHE_PERSISTENCEcapability 행 소유
제외 범위
- 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인터페이스와 파티션 키 규칙 확정 — 등급:plannedCrossTabSyncPort인터페이스와 메시지 봉투 확정 — 등급:planned- version 불일치 캐시 폐기 fixture — 등급:
planned - 탭 A mutation → 탭 B 무효화 integration fixture — 등급:
planned - BroadcastChannel 부재 시
storageevent fallback fixture — 등급:planned - 두 transport 모두 불가 시
CROSS_TAB_CHANNEL_UNAVAILABLE처리 — 등급:planned FE-GATE-028cache 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 과
storageevent 모두 불가 →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 에서 나옴
- raw/branch-notes/feature-server-state-caching-contract 의
검증해야 할 주장
| 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