문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.
고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
cache.operation.failed(operation: unregistered-query-namespace) 진단을
남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.
버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.
위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
BoundQuery.invalidation, 상수 1개).
검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
bound query whose namespace no registered topic reaches (03-01)" 실패.
"expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
다른 실행 때문)로 이 변경과 무관하다.
tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
gzipSync로 쟀다. 298201f 202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적
202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다.
- 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은
0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts,
presentation -> contracts뿐이다.
Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
문서 색인
docs/의 문서를 세 묶음으로 나눈다.
1. 현재 계약 지금 코드가 지키는 규칙. 게이트가 검사한다
2. 목표 설계 앞으로의 설계와 결정. 구현됐다는 뜻이 아니다
3. 작업 이력 리뷰·계획·작업 추적. 복사한 프로젝트는 지워도 된다
문서와 코드가 다르면 코드가 맞다. 목표 설계 문서에 적힌 기능이 지금 동작하는지는
문서 안의 상태 값(COMPOSED, AVAILABLE_NOT_COMPOSED, DESIGNED_NOT_IMPLEMENTED 등)으로
확인한다. 상태 값의 뜻은 README.md의 "Support scope" 절에 있다.
README와 입구 문서는 영어, recipe·ledger·스타일 문서는 한국어다.
1. 현재 계약
처음 읽을 입구 문서 6개다.
| 문서 | 정하는 것 |
|---|---|
README.md |
시작, 런타임 설정과 배포 변수, 검증 명령, CI, 지원 범위, 원본 업데이트 반영 |
architecture/frontend-application-foundation.md |
이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계 |
architecture/layers.md, architecture/overview.md |
계층과 import 방향. check:architecture가 검사한다 |
architecture/starter-experience.md |
기본 라우트, 인증 모드, 기능 추가·제거 절차 |
architecture/optional-adapter-recipes.md |
선택 기능(recipe)을 넣고 빼는 절차 |
operations/ci-quality-gates.md, testing/taxonomy.md |
게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선 |
입구 문서가 가리키는 세부 규칙:
- 계약 소유와 호환성:
architecture/contract-ownership.md,contracts/compatibility.md - 정적 배포와 런타임 설정:
architecture/static-delivery.md - 기능 개발자가 알아야 하는 양:
architecture/capability-consumer-experience.md - 운영·복구:
operations/,runbooks/ - 보안과 공급망:
security/browser-boundary.md,security/supply-chain.md - 디자인 토큰과 수동 접근성 검토:
styling/design-tokens.md,accessibility/manual-checklist.md - 버전별 변경:
../CHANGELOG.md
게이트가 직접 읽는 파일이라 지우거나 옮기면 게이트가 실패한다.
| 파일 | 읽는 명령 |
|---|---|
architecture/review-ledger.json, architecture/review-evidence.md, accessibility/manual-checklist.md |
verify:documentation (FE-GATE-017) |
reviews/adapters/INVENTORY.md |
check:adapter-inventory (FE-GATE-010) |
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json |
check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json) |
2. 목표 설계
설계와 결정 기록이다. 구현된 부분과 계획이 한 문서에 섞여 있다. 행마다 상태 값을 본다.
- 런타임 capability 결정의 정본:
architecture/2026-07-30-frontend-runtime-capability-repository-aligned-implementation-closed-deep-design.md - 상태 원장:
architecture/browser-data-capability-completion-ledger.md - 전체 검토와 로드맵:
architecture/frontend-platform-capability-review.md,architecture/frontend-platform-implementation-roadmap.md - 포트·경계·데이터 흐름:
architecture/frontend-ports-adapters-and-boundaries.md,architecture/typescript-state-and-data-flow.md,architecture/routing-pages-and-patterns.md - API와 서버 상태:
architecture/api-contract-schema-mapper-and-server-state.md,architecture/backend-api-and-server-state-contract.md,architecture/protobuf-browser-transport-and-rest-gateway.md - 브라우저 데이터:
architecture/client-cache-and-storage.md,architecture/browser-file-and-origin-storage.md,architecture/presigned-transfer-and-image-cdn.md,architecture/server-file-capability-infrastructure.md - 실시간:
architecture/realtime-events-web-push-and-bounded-polling.md - 디자인 시스템과 테스트 전략:
styling/design-system-platform.md,testing/frontend-platform-testing-strategy.md - 결정 기록(ADR):
architecture/decisions/VD-*.md
3. 작업 이력·리뷰
템플릿을 만들면서 쓴 계획, 리뷰, 작업 추적이다. 현재 계약이 아니다.
복사한 프로젝트는 지워도 된다. 지울 때 남길 파일은 README.md의
"Files you can delete after copying" 절에 있다.
| 경로 | 내용 |
|---|---|
superpowers/ |
과거 작업 계획과 스펙 |
reviews/ |
리뷰 결과와 리뷰 가이드. reviews/adapters/INVENTORY.md만 게이트가 읽는다 |
../SPEC.md, ../tasks/ |
2026-09-25 리뷰 수정 라운드의 요구사항과 작업 목록. 이 라운드가 쓰는 중이라 docs/ 밖에 그대로 둔다 |