Commit Graph
16 Commits
Author SHA1 Message Date
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
DongHyeonkaandClaude Opus 5.5 c6300e9d40 feat(auth): require readSubject so a token refresh keeps server state
An external owner without readSubject made every authenticated
notification (every token refresh) abort requests and clear the
server-state cache. readSubject is now a required owner method and
getSubject a required SessionGateway method.

- ExternalSessionOwner.readSubject(): required; the host owner check
  (EXTERNAL_OWNER_METHODS) rejects an owner without it, so the session
  fails closed as integration-failed like any other missing method.
- SessionGateway.getSubject(): required. Anonymous and unavailable
  adapters return null; demo already returned its fixed user.
- Scope runtime: same (state, subject) still skips the fence; a state
  or subject change still fences. An authenticated session with a
  null/empty subject still fences (fail closed) and now records
  cache.operation.failed {operation: SCOPE_FENCE, reason:
  SUBJECT_MISSING} once per fence. Bootstrap passes diagnostics in.
- Docs: starter-experience external owner section and port comments
  describe what readSubject returns, the fail-closed diagnostic and a
  migration note.

RED before the change (vitest tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters.test.ts): 4 failed | 31 passed
- fails closed when the owner lacks readSubject:
  expected 'authenticated' to be 'integration-failed'
- fences and reports SUBJECT_MISSING ... null / empty subject, and the
  external owner whose readSubject returns null:
  expected [] to deeply equal [[{ level: 'warn', ... }]]
- type level: an owner literal without readSubject compiled (tsc exit
  0). The new @ts-expect-error pin fails check:types:test with TS2578
  if readSubject becomes optional again.
Pins that stayed green: same-subject token refresh keeps the cache,
subject change fences, sign-out fences, owner missing readState is
rejected.

GREEN: check:architecture, check:types:app, check:types:test, lint,
test:unit (2084), test:component (182), test:reference-feature (59),
test:integration (151), verify:documentation, check:diagnostics,
check:ci all pass.

BREAKING: external auth owners must implement readSubject(); code that
implements AuthSessionPort/SessionGateway directly must implement
getSubject().

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 16:25:22 +09:00
DongHyeonkaandClaude Opus 5.5 55721f075a fix(auth): give the demo session a stable subject so a refresh keeps the cache (R3-3)
The demo adapter now reports "demo-user" as its subject while
authenticated (null otherwise), so an authenticated notification for the
same demo user no longer fences the server-state scope. Sign-out and any
state change still fence.

The scope runtime now treats an empty-string subject like a missing one
(fail-closed), so an owner that returns "" for everyone cannot disable
fencing between users.

Pinned: state change fences, subject change fences, an external owner
without readSubject fences on every authenticated notification.

RED (before the fix, tests/unit/server-state-scope-runtime.test.ts):
  x does not fence when the demo session re-announces the same user
    expected [ { kind: 'FENCED', ... } ] to deeply equal []
  x still fences when an authenticated session names an empty subject
    expected true to be false
  Tests 2 failed | 12 passed (14)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 15:15:26 +09:00
DongHyeonkaandClaude Opus 5.5 1d7ca9dcb8 fix(query-cache): measure pagination per page, reject bare W/" ETag, drop dead RPC helper (Q-6.3-12)
- cursor pagination re-serialized every accumulated item on each page
  (O(pages x total)) and used items.push(...page.items), which throws
  RangeError for a large page, so loadAll rejected instead of returning
  a Result. Each page is now measured once and summed (errs high by at
  most one byte per page), the item count is checked before copying,
  and items are appended one by one.
- conditional-validator-store accepted `W/"` as a weak ETag because its
  opening quote also satisfied endsWith('"'). The closing quote must now
  come after the opening one.
- browser-rpc-runtime's validTransportFailure had no callers, duplicated
  decodeTransportFailure and read properties directly, which RPC-RR-04
  forbids. Deleted (approved for this template).

Verified: new tests failed RED (18 serialized items instead of 6 because
the accumulated array was passed each time, RangeError for a 1,000,000
item page, `W/"` installed) and pass now. All lane gates pass except the
known removal-fixture test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:41:45 +09:00
DongHyeonkaandClaude Opus 5.5 fcd37a9d16 perf(query-cache): invalidate namespaces in parallel (Q-6.3-8)
TanStack 5 invalidateQueries resolves only after the active refetches
finish. The coordinator awaited each namespace in a for loop, so one
invalidation (and lease.release(), which waits on it) took the sum of
every namespace's refetch time. The namespaces now run through
Promise.allSettled; each rejected one is still reported once as
"invalidate".

Verified: new test holds the first namespace's refetch open and failed
RED (second invalidateQueries never started); it now passes and checks
that a failure is reported once. All lane gates pass except the known
removal-fixture test; provider-guardian-transaction timed out once under
load and passed on rerun.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:41:45 +09:00
DongHyeonkaandClaude Opus 5.5 a39eed6c11 fix(query-cache): fence the scope only when session state or subject changes (R-3.2)
Every session notification aborted in-flight requests, bumped the generation
and cleared the cache, even when nothing changed. A repeated sign-out or a
token-refresh notification wiped the cache, and with V3 calling
onUnauthenticated() on a logged-out query it could loop.

The scope runtime now reads (getState, getSubject) and skips a notification
that leaves both unchanged. An identity it cannot prove unchanged still
fences: a session without getState (old behavior), a throwing owner, or an
authenticated session with no subject. A FAILED scope still retries its
reset on any notification.

To make the subject observable, SessionGateway gets an optional
`getSubject?(): string | null` and ExternalSessionOwner an optional
`readSubject?()` (additive; existing owners keep fencing on every
authenticated notification).

RED before fix: tests/unit/server-state-scope-runtime.test.ts "does not
fence, abort or clear on a repeated sign-out" / "... on a token refresh for
the same subject" saw FENCED. Pinned (passing before and after): "still
fences when the state changes / the subject changes / an authenticated
session cannot name its subject", "retries a failed reset ...".
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, test:integration, test:reference-feature pass. test:unit
passes except removal-fixture.test.ts (needs generated artifacts/ release
evidence absent in a fresh worktree; unrelated).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 12:25:01 +09:00
donghyeon-ka 5cc41467ae refactor: 프론트 템플릿 리펙토링 2026-09-18 15:16:58 +09:00
DongHyeonkaandClaude Opus 5 a42d96185f docs: record the barrel boundary and IndexedDB kernel designs with a plan
모듈별 구조 리뷰에서 나온 두 설계를 spec으로 남기고, 그중 배럴 경계
작업의 실행 계획을 쓴다. 배럴 규칙은 실제 import 그래프에 돌려 위반
15건이 치환 대상 15줄과 일치함을 확인했고, 재수출할 심볼 82개는 실제
export와 대조했다.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-16 18:50:02 +09:00
DongHyeonkaandClaude Opus 5 df18349682 fix: validate the snapshot that installs, not the object that was shown
Three trust boundaries checked a caller's object and then read it again to
use it. Between those two reads an accessor or a Proxy can answer
differently, so the value that passed validation and the value that was
installed were not the same value.

A credential owner's answer was read field by field outside the auth
boundary: a throwing `kind` getter escaped into the transport catch and an
auth outage reached operators as `NETWORK_FAILURE`. Contract composition
validated a contribution and then copied it, so a policy that answered
10,000 to the ceiling check and 999,999 to the copy installed the second
value. The cursor runtime validated its profile once and re-read it on
every page, so raising `maxPages` after construction widened a cap that
had already been checked.

`src/contracts/exact-snapshot.ts` is the one descriptor-based decoder they
now share: every property is read exactly once, an accessor, a symbol, an
inherited or non-enumerable field and a throwing trap all resolve to a
typed failure, and validation runs on the owned copy.

Separately, the `responseBody: NONE` probe awaited a bare `read()`. The
deadline produced a bounded public result while the raw reader kept its
lease, so the body stayed locked and the outer compensator could not
cancel it. The probe now takes the operation lifetime and owns the cancel
and the lock release itself.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-15 01:25:12 +09:00
DongHyeonkaandClaude Opus 5 ca210d3bc5 fix: align the legacy and optional network paths with V3 authority
LEG-01. AuthSessionPort.recover now takes the request's lifetime context, and
the raw recovery helper returns data only. The sign-out notification moved to
the site that adopts the result, so a recovery that answers after the deadline
or a caller abort is observed and discarded instead of logging the user out of
a request nobody is waiting on.

LEG-02. The V2 client shares V3's credential admission validator instead of
checking the allowed set alone. A bearer profile whose patch omits, empties,
duplicates or corrupts Authorization now fails closed with zero fetches rather
than dispatching an anonymous request under an authenticated profile.

OPT-NET-01. A cursor loader rejection is re-thrown exactly as it is with no
signal at all. Only a signal that has actually aborted classifies the outcome
as PAGINATION_ABORTED, so a real upstream failure stops being filed as a user
cancellation.

OPT-NET-02. defineMutationIntent and the V3 admission site now share the single
isValidIdempotencyKey authority, closing the drift that let a control character
through intent definition.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-14 13:50:44 +09:00
DongHyeonkaandClaude Opus 5 4fe924ee0f fix: harden bounded state sidecars
N-05: the conditional-validator key was a colon join over components that may
themselves contain colons, so two distinct valid bindings could collide and one
definition's ETag could be prepared for another. The key is now a validated,
byte-bounded fixed tuple encoded with JSON.stringify.

N-09: capture localStorage exactly once and compare StorageEvent.storageArea
against that object identity, so a pulse from sessionStorage or any other area
is rejected instead of matching on key and value alone. The pulse key is
registered in the storage registry as CACHE_INVALIDATION_PULSE.

N-10: race loadPage against the caller signal and re-check before observing a
page, so a non-cooperative loader can neither hold loadAll forever nor have a
post-abort completion accumulated into a successful result.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-13 23:35:48 +09:00
DongHyeonka 73a50426d6 fix: index many-to-many query invalidation 2026-08-01 23:17:09 +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
donghyeon-ka 5173b6c8d6 feat: add diagnostics and telemetry runtime 2026-07-26 16:42:27 +09:00
donghyeon-ka 184eb67282 feat: add application-owned query cache contract 2026-07-25 20:55:27 +09:00