문제: useSessionAction이 recover()의 결과를 버린다. owner가
"no-session"을 돌려주고 상태를 recovery-pending으로 두면 보호 라우트와
셸은 계속 "세션 복구" 버튼만 보이고, 로그인으로 갈 길이 없다. owner가
지켜야 할 상태 전이도 어디에도 적혀 있지 않아 owner 작성자가 화면
코드를 읽고 추론해야 했다.
고른 방법: 두 가지를 함께 한다.
- SessionState·SessionGateway.recover·ExternalSessionOwner에 전이
계약을 적는다. restored면 authenticated, no-session이면
unauthenticated(또는 integration-failed), reject면 상태 유지.
- SessionProvider가 recover()의 답을 쓴다. no-session을 받았는데
owner가 아직 recovery-pending이면, owner가 다음에 알릴 때까지 화면에
unauthenticated로 보인다. 그래서 라우트 문과 셸 모두 로그인 버튼을
보인다.
버린 대안: 어댑터가 전이를 검사해 throw. 그러면 화면은 "작업 실패"만
보이고 여전히 로그인 버튼이 없다. 어댑터가 상태를 덮어쓰는 것은 구독
알림을 새로 만들어야 해서 scope fence와 얽힌다.
위험·한계: 계약을 어기는 owner의 상태를 화면에서만 바로잡는다.
application·scope fence는 owner의 상태를 그대로 본다.
검증: tests/component/session-recovery.test.tsx 4건(수정 전 2건 실패
확인), router·app-shell·route-status-surfaces·auth-session-adapter
테스트 통과, check:types, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-11
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.
고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
"REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).
버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
매핑을 알아야 한다. 프로필 항목 하나가 더 작다.
위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
청크라 초기 크기에 영향이 없다.
검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
undefined to match object { transport: 'BEARER_HEADER', …(1) }",
"expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
(FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
http-scenario-evidence, ci-workflow-generation, lab-performance,
fixture-node-modules, deployment-admission, security-followup-archive).
tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.
Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
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>
The shared credential admission (V2 and V3) only rejected CR/LF. A token
with NUL, a non-Latin-1 character or another control character passed,
then Fetch rejected it after V3 had marked the attempt dispatched: a query
burned its retry budget and a command ended MAYBE_APPLIED with
NETWORK_FAILURE. The external session adapter also merged header names
that differ only in case, silently keeping the last value.
- admitCredentialHeaders: the value must match [\x20-\x7E\xA0-\xFF]+ (a
ByteString without C0/C1 controls); the size limit is now the string
length, which is the wire byte count for a ByteString. Failure stays
CREDENTIAL_HEADER_VALUE_INVALID, i.e. AUTH_INTEGRATION_FAILURE before
dispatch.
- checkFinalInvariants: builds `new Headers(headers)` first; any value
Fetch would reject fails as HEADER_VALUE_INVALID (new additive member of
FinalInvariantFailure) with zero fetch calls.
- validateCredentialPatch: rejects case-only duplicate header names.
RED before fix: http-execution-v3-live-authority.test.ts "rejects a NUL /
non-Latin-1 credential value before dispatch" (got TRANSPORT_FAILURE, fetch
called), http-contract-bridge.test.ts "rejects a NUL/non-Latin-1/tab/DEL/C1
control value ..." and "fails before dispatch when Fetch would reject a
header value", auth-session-adapter.test.ts "rejects credential headers
that differ only in case instead of merging them". Pinned: "admits an
ordinary bearer token", CR/LF rejection, existing "Bearer ok"/"Bearer
token" integration paths.
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, test:integration, test:contract, test:platform,
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>
V3 returned the same UNAUTHENTICATED outcome for "no credential, nothing
sent" and for a server 401, and the composition root called
onUnauthenticated() for both. With the demo owner that overwrote a
recovery-pending session with "unauthenticated", and the demo setState
notified even when the value did not change, which fed the scope-fence loop.
- V3: the server-401 UNAUTHENTICATED outcome now carries its response
`metadata` (additive optional field). The pre-dispatch one does not.
- runtime-adapters: onUnauthenticated() only when metadata is present.
- demo session: setState is a no-op for the current value.
RED before fix: reference-runtime-composition.test.ts "does not report a
request refused before dispatch as a sign-out" (state became
"unauthenticated"), auth-session-adapter.test.ts "does not notify when the
demo state is set to its current value" (1 notification),
http-execution-v3.test.ts "tells a missing credential apart from a server
401" (no metadata). Pinned: "still signs out when the server answers 401".
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, test:integration, test:reference-feature, test:contract
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>
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>
모듈별 구조 리뷰에서 나온 두 설계를 spec으로 남기고, 그중 배럴 경계
작업의 실행 계획을 쓴다. 배럴 규칙은 실제 import 그래프에 돌려 위반
15건이 치환 대상 15줄과 일치함을 확인했고, 재수출할 심볼 82개는 실제
export와 대조했다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Install the REST auth profile registry once at composition and make it the
single transport authority for V3. Contract composition now rejects an
unregistered authProfileId, so the executor never resolves a profile at
runtime.
The credential collaborator contributes proof headers only: Fetch credentials
come from the resolved profile, transport-owned and forbidden headers are
rejected, headers outside the profile's allowed set are rejected, and a missing
required header fails closed as AUTH_INTEGRATION_FAILURE with zero fetch calls.
The final invariant re-proves credentials mode and the exact header sets.
Demo mode satisfies the strict bearer profile with a fixed non-secret marker
instead of weakening REFERENCE_EXTERNAL_BEARER. Credential owners now receive
the operation lifetime through AuthOperationContext.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>