문제: 1103/02-01이 제품 closer를 scope reset에 넣었다. template
participant 하나가 제품 closer를 차례로 부르고, 하나라도 던지면 이유 없는
Error를 던진다. scope runtime은 그 실패를 `failed = true`로만 받아 scope를
`FAILED`에 둔다. 그동안 모든 서버 요청이 `SCOPE_FENCED`로 막히는데 진단
기록은 0건이다(리뷰 실험 E-3). 계약의 `ProductScopeParticipant.label`을
읽는 코드도 없다. 개발자는 "로그아웃 뒤 앱이 요청을 안 보낸다"만 보고 원인
closer를 찾으려면 closer를 하나씩 지워 봐야 한다.
고른 방법(리뷰 대안 (다)):
- scope runtime이 reset의 실패 단계마다 `cache.operation.failed`를 하나
남긴다. `operation: "SCOPE_RESET"`, `reason`은 `PARTICIPANT_FAILED`·
`CACHE_RESET_FAILED`·`GENERATION_ACTIVATION_FAILED`(+ 목록 함수가 던질
때 `PARTICIPANTS_UNREADABLE`), `error_kind`, participant 실패면
`scope_participant: <label>`. template participant 실패도 같은 길로
남는다.
- 진단 계약에 `scope_participant` 키를 더한다(cardinality `topology`,
값 정책 `isScopeParticipantLabel` = 소문자 kebab-case 48자 이하). label은
제품 코드가 고른 문자열이라 projection이 받는 닫힌 토큰으로 제한했다.
- 제품 closer를 wrapper 하나로 감싸지 않고 각자 order 10 participant로
넘긴다. 그래서 `participants`가 reset마다 읽는 함수도 받는다
(`ServerStateScopeDependencies`, 배열은 그대로 받는다). 순서와 "하나가
실패해도 나머지를 부른다"는 그대로다.
- 조립은 형식에 맞지 않는 제품 label을 `TypeError`로 거절한다. 부팅에서
바로 드러나야 진단에서 label이 빠지는 일이 없다.
버린 대안:
- (가) 문서에 "closer는 던지지 않게 쓴다"만 적기: 결함이 그대로다.
- (나) wrapper만 제품 label을 기록: template participant 실패는 계속
조용하고, 한 실패가 wrapper와 runtime에서 두 번 기록된다.
- label을 `operation`이나 `reason` 값에 섞기: 계약 변경은 없지만 그 키의
뜻이 흐려진다.
위험·한계:
- 진단 계약(`src/contracts/diagnostics.ts`)에 키 하나, 함수 하나가 더해진다.
더하기만 해서 호환은 깨지지 않는다. CHANGELOG [계약] 행이 필요하다.
- 제품 label 형식이 좁아졌다. `Browser Files` 같은 label을 쓰던 제품은
부팅에서 `TypeError`가 난다. 저장소 안의 label(`browser-files`, 테스트의
label)은 모두 맞는다.
- 화면이 `FAILED`를 어떻게 보이는지는 바꾸지 않았다(영역 08·09).
검증: desktop batch에서 확인
- node scripts/run-vitest.ts run tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters-product-scope-participants.test.ts
tests/unit/observability-cardinality.test.ts tests/unit/diagnostics.test.ts
- corepack pnpm check:diagnostics
- node scripts/run-vitest.ts run tests/recipes/browser-file-session-capability.test.ts
Refs: 1105/02-01
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>
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>
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>