Commit Graph
7 Commits
Author SHA1 Message Date
DongHyeonka 02a761f064 docs(storage): 저장소 문서가 registry 키 목록 대신 정본을 가리키게 한다
문제: 저장소 설계 문서와 VD-13이 Web Storage registry 행을 "현재"
목록으로 적는다. 설계 문서 50-52행은 8행 중 4행(`COLOR_SCHEME`,
`CHUNK_RELOAD_GUARD`, `AUTH_TOKEN`, `QUERY_PERSISTENCE`)만, 0절 표와
16.2절 기본 조립 표와 VD-13 2.1절 표·7.1절 문단은 `COLOR_SCHEME`,
`CHUNK_RELOAD_GUARD` 둘만("두 key") 적는다. registry에는 기본 조립이 쓰는
`LOCALE`·`RELEASE_MISMATCH_RECOVERY`와 외부 소유 행
`CACHE_INVALIDATION_PULSE`·`AUTH_REDIRECT_TRANSACTION`도 있다
(`src/contracts/storage-keys.ts`, `create-application.ts`,
`boot-release-recovery.ts`). 행을 더한 커밋들이 이 문장을 따라 고치지 않았다.

고른 방법: 목록 문장을 지우고 `STORAGE_REGISTRY`를 정본으로 가리킨다.
StoragePort가 거절하는 행의 규칙(`sensitive-forbidden` 분류와
`backend: "external"`, `getStorageDefinition`)만 문장으로 남긴다. 표 두 행은
"StoragePort 행" 한 행으로 합친다. 8행을 모두 적는 대안은 버렸다. 다음에
행이 늘면 같은 식으로 낡는다.

위험·한계: 이 문장을 보는 검사는 없다. 두 문서는 docs/README.md 2절(목표
설계)이라 verify:documentation이 읽지 않는다. 다시 목록을 적으면 리뷰가
손으로 찾아야 한다.

검증: 문서만 바꿨다. 검사 없음(위). `git grep -n 'COLOR_SCHEME' --
docs/architecture`에 목록 문장이 남지 않았다(starter-experience.md의 테마
설명 한 줄만 남는다).

Refs: 1106/05-01
2026-11-06 05:17:33 +09:00
DongHyeonka d9ca6537d8 docs(architecture): 캐시 문서의 밀린 줄 번호 참조를 심볼 이름으로 바꾼다
문제: client-cache-and-storage.md의 cross-context 조립 설명이
runtime-adapters.ts·server-state-scope-runtime.ts·tanstack-cache-
coordinator.ts의 줄 번호를 가리키는데, 네 곳 모두 다른 코드로 밀렸다
(0929/02-04). 문서 줄 번호를 보는 검사는 없어서 다음 변경에도 또 밀린다.
browser-file-and-origin-storage.md의 participant 등록 예 줄 번호는 앞
커밋(02-01)이 이미 고쳤다.

고른 방법: 줄 번호 대신 함수·호출 이름을 적는다(1101/05-05와 같은
방식). 리뷰가 맞다고 확인한 다른 줄 번호는 그대로 둔다.

위험·한계: 문서만 바꾼다. 다른 문서의 줄 번호 참조는 건드리지 않았다.

검증: verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-04
2026-11-04 21:02:15 +09:00
DongHyeonka ffb6782b0c fix(query): 무효화 topic이 닿지 않는 조회 namespace를 진단으로 알린다 (03-01)
문제
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
2026-11-01 22:42:44 +09:00
DongHyeonka e98a980dff fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.

고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).

버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
  newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.

위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.

검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
  "expected { ok: true, value: undefined } to match object { ok: false }"
  로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
  to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
  contract-registry-lookup, browser-security, runtime-adapters,
  release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
  eslint 통과, check-registries PASS, verify-documentation-readiness
  PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonkaandClaude Opus 5.5 4358ced65b docs(cache): bring the cross-tab invalidation status up to the code (02-09)
The doc still called the registry pulse key, the storageArea check and the
per-scope QueryClient unimplemented and gave the old release.<id> epoch. Only
session/account epoch and the durable ledger remain missing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:33:00 +09:00
DongHyeonka c6da03369c refactor: 리펙토링 2026-08-01 19:39:59 +09:00
donghyeon-ka 6c52cdb916 feat: 기능 추가 과정중 2026-07-30 15:58:20 +09:00