Commit Graph
53 Commits
Author SHA1 Message Date
DongHyeonka f117a5af41 docs(src): 계층 폴더마다 지역 규칙 AGENTS.md를 두고 CLAUDE.md가 가져온다
계층별 규칙이 Claude만 읽는 .claude/rules/에만 있어 다른 에이전트에는
보이지 않았다. 하네스 자료의 3단계는 레이어마다 그 폴더에 AGENTS.md다.

src/의 9개 계층 폴더마다 AGENTS.md(16~20줄)를 둔다: 그 폴더가 하는 일,
그 폴더에만 걸리는 import 금지(.dependency-cruiser.json에서 from이 그
폴더에 맞는 규칙을 뽑아 이름과 함께), 검사하는 게이트, 테스트 위치. 모든
폴더에 걸리는 규칙은 루트 AGENTS.md와 layers.md를 가리킨다. 옆에
@AGENTS.md 한 줄 CLAUDE.md를 둬 Claude Code가 그 폴더 파일을 열 때 같은
책을 읽는다(백엔드와 같은 짝).

- .claude/rules/adapters·features는 폴더 AGENTS.md를 가리키게 줄였다.
- scripts/check-work-docs.py: src/**/AGENTS.md도 이력 ID 0·200줄·짝·링크를
  본다. 훅 N5는 이 파일들을 노트북 확인 파일로 친다.
- docs/reviews/adapters/INVENTORY.md: check:adapter-inventory가 src/adapters
  아래 추적 파일을 모두 요구하므로 두 행(142·143)을 더했다.
- 루트 AGENTS.md 지도가 가장 가까운 src/<계층>/AGENTS.md와 비전·문제 정의
  양식을 가리킨다.

버린 대안: .claude/rules/만 두기(다른 에이전트가 못 읽는다), 폴더 CLAUDE.md
없이 AGENTS.md만(Claude Code는 같은 폴더에 CLAUDE.md가 없고 Read로 열 때만
읽어 백엔드와 갈린다).

위험·한계: 규칙 이름은 지금 규칙 파일에서 뽑았다. 규칙을 더하거나 바꾸면
이 문서도 손으로 고쳐야 한다(정본은 규칙 파일과 check:architecture).

검증: scripts/verify.sh docs rc=0(src/**/AGENTS.md 9개, 최대 20/200),
python3 -m unittest discover -s scripts/tests 62건 통과.
2026-11-08 22:57:03 +09:00
DongHyeonka d5a70b4267 chore(review): 1105 테스트 조치 브랜치를 합친다 2026-11-06 02:59:02 +09:00
DongHyeonka 45c9c4dc48 chore(review): 1105 계약·앱 코어 조치 브랜치를 합친다
합치며 고친 것: 두 브랜치가 따로는 맞고 합치면 어긋나는 곳 하나.
- 1105/03-02(HTTP 판정 브랜치)가 §4의 503 `RATE_LIMIT_UNAVAILABLE`·
  `RATE_LIMIT_INCOMPATIBLE`을 답 표(`backend-idempotency-answers.json`)에
  옮겼다. 1105/07-01(이 브랜치)은 같은 두 code를 pin의 `notCopied`에
  두었다. 합친 트리에서 `backend-contract-pin.test.ts`의 "copies the
  answers from the backend table rows at the pin"이 "is both copied and
  listed in notCopied"로 실패한다.
- pin의 `notCopied`를 비우고, 계약 문서 4.1절의 "지금은 §4의 `RATE_LIMIT_*`
  둘"과 "§4 행은 `REQUEST_TIMEOUT` 하나"를 답 표에 맞게 고친다.
- `docs/manual/01-add-a-feature.md` 충돌은 앞 통합(1a4a220c)과 같게
  푼다: "5xx 여섯" 줄과 pin·사본·drift 명령 세 줄을 함께 둔다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/backend-contract-pin.test.ts tests/unit/backend-contract-drift.test.ts

Refs: 1105/03-02, 1105/07-01
2026-11-06 02:59:02 +09:00
DongHyeonka 57c34ea626 chore(review): 1105 realtime·Service Worker 조치 브랜치를 합친다 2026-11-06 02:59:01 +09:00
DongHyeonka 00076992f7 fix(recipes): 쿠키 세션 모드의 서버 401을 템플릿 세션에 잇는다
문제: 짝 백엔드 Redis session 모드를 쿠키 recipe와 매뉴얼 04 4.3대로
이으면 서버 401이 세션에 닿지 않는다. 1103/09-01 수정 뒤 조립 루트는
제품 provider 프로필의 401을 제품의 선택 hook `onCredentialRejected`에만
알린다. 쿠키 모드의 operation은 모두 제품 프로필(SESSION_COOKIE_*)인데
매뉴얼 예시는 그 hook을 잇지 않았고, recipe와 매뉴얼은 "서버 401 →
unauthenticated"라고 적었다. 이으려 해도 ProductCompositionContext에
세션에 알릴 길이 없었다. 리뷰 09-cookie401에서 세션 만료 뒤에도 상태가
authenticated, 이전 scope가 current로 남았다.

고른 방법: 두 가지를 더했다.
- ProductCompositionContext.notifySessionUnauthenticated(): 템플릿 세션의
  자기 401과 같은 판정(authSession.onUnauthenticated)을 제품이 부를 수
  있게 한다(리뷰 안 C).
- recipe의 createSessionCookieRejectionHandler(context): SESSION_COOKIE_*
  프로필의 401만 세션에 넘긴다. 다른 제품 프로필의 401은 넘기지 않으므로
  1103/09-01의 완료 기준(세션과 무관한 provider의 401은 로그아웃시키지
  않는다)은 그대로다.
매뉴얼 04 4.3 예시에 `onCredentialRejected` 한 줄을 넣고, recipe 주석,
매뉴얼 04 흐름도, 매뉴얼 02 5절과 7절 업로드 예시(BACKEND_SESSION 쿠키
세션)를 맞췄다. 버린 대안: recipe가 owner와 provider를 한 번에 만드는
함수(안 B). owner는 composeProductSessionOwner, provider는 composeProduct
에서 따로 만들어져 모듈 변수가 필요하다. provider 선언에 "세션 자격
증명" 표시를 두는 안(D)은 계약 칸이 늘고 판정이 선언과 hook 둘로 갈린다.

위험·한계: 제품이 이 한 줄을 빼면 여전히 세션 만료를 모른다. 이것을
막는 검사는 없다(매뉴얼과 recipe 주석이 적는다). 이미 recipe를 복사한
다운스트림은 handler를 복사본에 옮기고 composeProduct에 한 줄을 더해야
한다. ProductCompositionContext에 칸이 하나 늘었다. 이 context는 템플릿만
만들므로 제품 코드는 깨지지 않는다. 실제 Redis 백엔드에는 붙이지
않았다(1103/09-03 남은 부분).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/recipes/session-owners-runtime.test.ts tests/recipes/cookie-session-owner.test.ts
조립 루트를 지나는 테스트가 매뉴얼 4.3 연결로 쿠키 읽기·쓰기 401 뒤
세션 unauthenticated, 이전 scope not current를 본다.

Refs: 1105/09-02
2026-11-05 22:26:27 +09:00
DongHyeonka fdc1db9471 feat(bootstrap): 제품이 SW blockers·observe를 composeProduct로 넘긴다
문제: SW를 켜는 선택은 제품 소유 `product-capabilities.ts`로 옮겼다
(1103/09-05 일부). 그런데 저장하지 않은 편집이 있는 탭의 활성화 거절
(`blockers`)과 page controller 관측(`observe`)은 템플릿 소유
`src/bootstrap/create-runtime-composition.ts`를 고쳐야 이어진다(매뉴얼 03
"SW 켜기", 레시피 "Service Worker를 켤 때 확인할 것" 2·3). 그 파일을 고친
제품은 템플릿 동기화마다 충돌한다.

고른 방법: 기존 제품 확장 지점에 선택 칸 하나를 더한다.
`ProductComposition.serviceWorker?: { blockers?, observe? }`
(`product-composition-contract.ts`). `createRuntimeAdapters`가 `composeProduct`
결과의 이 칸을 bundle에 `productServiceWorker`로 싣고, 템플릿 조립
(`create-runtime-composition.ts`)이 telemetry와 같은 방식으로 받아
`createOptionalRuntimeHost`에 넘긴다. blockers 목록은 한 번 복사한다. 던지는
blocker는 page controller가 이미 막는 쪽으로 본다. page controller는
`observe`의 throw를 잡지 않으므로, 제품 sink가 던져도 worker 흐름이 바뀌지
않게 조립에서 감쌌다. 매뉴얼 03과 레시피 2·3을 새 자리로 고쳤다.
버린 대안:
- `product-composition.ts`에 새 export(`composeProductServiceWorker`)를 요구.
  이미 그 파일을 가진 다운스트림이 동기화하면 import가 깨진다. 선택 칸은
  기존 `composeProduct`를 그대로 둔다.
- `composeProduct`를 조립에서 한 번 더 부르기. capability와 credential이 두
  벌 생긴다.

위험·한계: 일부만 닫는다. 남은 것:
- 활성화 화면(`onUpdateWaiting`·`requestActivation()`)과 reload 안내를 이을
  제품 소유 자리가 없다(레시피 4·5, 0925/06-05).
- realtime·Web Worker·오프라인 명령은 여전히 조립이 거절한다
  (`optional-runtime-host.ts`, 그 런타임이 템플릿에 없다).
`product-composition.ts`(제품 소유, 출하 상태 빈 값)는 고치지 않았다. 칸이
선택이라 기존 제품 파일과 1105/09-01의 타입 검사 탐침 내용이 그대로
통과한다.

검증: desktop batch에서 확인.
- node scripts/run-vitest.ts run tests/component/runtime-composition-service-worker-product-wiring.test.ts tests/component/runtime-composition-service-worker-telemetry.test.ts
- RED: "passes the product's blockers and observer to the page controller"가
  옛 조립에서 observe 기록이 비어 실패한다.
- 함께: check:types, lint, check:architecture, verify:documentation

Refs: 1103/09-05
2026-11-05 22:19:06 +09:00
DongHyeonka f738348d9d fix(bootstrap): 실패한 scope closer를 label과 함께 진단에 남긴다
문제: 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
2026-11-05 22:14:54 +09:00
DongHyeonka 2e1acb1f21 fix(bootstrap): 금지된 설정 키로 멈춘 부팅 오류에 그 키 이름을 싣는다
문제: 런타임 설정에 비밀처럼 보이는 키(`CLIENT_SECRET` 등)가 있으면
부팅이 CONFIG_SECRET_NAME_REJECTED로 멈추지만, 안전한 부팅 오류에는
buildId만 있고 어느 키인지가 없다. assertSafeConfigNames가 던진 오류의
message에는 키 이름이 있었지만 loadRuntimeConfig가 그 오류를 버렸다.
같은 파일의 스키마 실패는 키 이름을 invalidKeys로 싣는다.

고른 방법: assertSafeConfigNames가 UnsafeConfigNameError를 던지고 그
`key`에 거절한 키의 점 경로(`CAPABILITY_OVERRIDES.AUTH_TOKEN`,
`FEATURE_OVERRIDES.<id>.CLIENT_SECRET`)를 싣는다. 로더는 그 경로를
스키마 실패와 같은 SAFE_KEY_PATTERN으로 거른 뒤 invalidKeys에 넣는다.
오류 화면은 이미 invalidKeys를 "잘못된 설정 키"로 보인다. 값은 어디에도
싣지 않는다. 버린 대안: message에서 키를 정규식으로 다시 읽는 것.
message 문구가 바뀌면 조용히 빠진다.

위험·한계: 키 이름은 거절된 문서에서 온다. 그래서 길이·문자를 제한하고,
그 밖의 이름은 빼고 코드만 남긴다. 첫 번째로 걸린 키 하나만 싣는다
(검사가 첫 키에서 멈추는 동작은 그대로). assertSafeConfigNames의
시그니처와 message는 바꾸지 않았다. UnsafeConfigNameError는
src/contracts/env.ts에 새로 더한 export다(추가만).

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/runtime-schema/runtime-config.test.ts

Refs: 1103/07-04
2026-11-05 22:08:22 +09:00
DongHyeonka 00b12b35b9 test(bootstrap): 플랫폼 규칙 테스트 둘을 샘플 밖으로 옮긴다
문제
1103 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기댄다. 샘플을
지우면 두 테스트가 사라지거나 비어도 test:all과 제거 드릴이 통과한다.
- MAX_RETRY_ATTEMPTS가 실행기에 닿는다: 유일한 테스트가
  tests/features/reference-feature/reference-runtime-composition.test.ts
  에 있다. createRuntimeAdapters는 설치된 기능의 HTTP로만 실행기에 닿아,
  기능이 없으면 시험할 길이 없다. REQUEST_TIMEOUT_MS도 같은 모양이다.
- 복구 중인 세션은 보호 라우트에서 기다린다:
  tests/unit/navigation-policy.test.ts는 설치된 보호 라우트를 돌며
  단언하는데, 보호 라우트는 모두 샘플 것이라 샘플을 지우면 반복이 0번이다.

고른 방법과 버린 대안
- src/bootstrap/runtime-adapters.ts: 설정 두 값과 auth profile 표로
  실행기를 만드는 부분을 createRuntimeContractHttpExecutor로 뺀다.
  조립 루트는 이 함수로만 실행기를 만든다. tests/unit/runtime-adapters
  .test.ts가 테스트 계약(TEST_LIST, 재시도 예산 2)으로 MAX_RETRY_ATTEMPTS
  0·1·2에 1·2·3번 나가는지, REQUEST_TIMEOUT_MS 5가 10초 계약을 5ms에
  끊는지 본다. 이 파일은 이미 제거 드릴의 공통 테스트 목록에 있다.
- tests/unit/session-route-access.test.ts(새 파일): component 테스트와
  같은 방법으로 생성 index를 mock해 tests/helpers/fixture-feature.tsx를
  설치하고, 보호 라우트 FIXTURE_ITEMS에서 네 세션 상태의 결정을 본다.
  decideRouteAccess에 라우트 정의를 받는 순수 함수를 따로 두는 안(리뷰
  ⓐ)은 버렸다. fixture 기능을 설치하는 방법이 이미 있어서 운영 코드를
  바꾸지 않고 실제 getRoute 경로까지 시험할 수 있다.
- scripts/test-sample-removal.ts: 새 파일을 공통 테스트 목록에 넣어,
  제거 드릴이 그 파일이 남았는지 본다.
- 매뉴얼에 "샘플을 지우면 다시 고정한다"고만 적는 안(ⓒ)은 사람이
  기억해야 해서 버렸다.

위험·한계
- 조립 루트가 이 함수 대신 실행기를 직접 만들도록 바뀌면 새 unit
  테스트는 그걸 모른다. 템플릿 상태에서는 참조 기능 테스트가 계속
  조립 루트 전체를 지킨다.
- 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다.

검증
- desktop batch에서 확인:
  node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts tests/unit/session-route-access.test.ts tests/unit/navigation-policy.test.ts tests/features/reference-feature/reference-runtime-composition.test.ts
- RED: 부모 커밋의 운영 코드에는 createRuntimeContractHttpExecutor가
  없어 runtime-adapters.test.ts의 새 4건이 실패한다.
- 변이: 새 함수의 maxRetryAttempts를 상수 2로 바꾸면 "honours
  MAX_RETRY_ATTEMPTS 0/1"이, navigation-policy.ts의 recovery-pending
  분기를 show-sign-in으로 바꾸면 session-route-access.test.ts의
  "answers a recovery-pending session …"이 실패해야 한다.

Refs: 1105/10-01
2026-11-05 22:07:09 +09:00
DongHyeonka 6088f6e533 chore(review): 1103 HTTP 쓰기 경로 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 03-01~03-06 0929/03-03 08-05 10-02 10-04 12-06

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 22:28:57 +09:00
DongHyeonka 55d0d48424 chore(review): 1103 저장소·파일 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-01~02-05 05-01~05-04

# Conflicts:
#	docs/manual/03-outside-feature-folder.md
#	src/bootstrap/product-composition-contract.ts
#	src/bootstrap/runtime-adapters.ts
2026-11-04 21:46:20 +09:00
DongHyeonka c17b3a05d6 chore(review): 1103 세션 owner 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-03 09-11

# Conflicts:
#	docs/manual/02-decision-tables.md
2026-11-04 21:40:51 +09:00
DongHyeonka 39c1de2e5e feat(diagnostics): 결과 불명 쓰기의 effect와 원인을 진단에 싣는다
문제
실행 관측(HttpExecutionObservation)에는 effect가 있지만 조립 루트 projector는
진단에도 텔레메트리에도 싣지 않는다. 진단 허용 키에 effect가 없고 status는
묶음(4xx)만 남는다. 그래서 진단 버퍼에서 결과 불명과 적용 안 됨, 처리 중
409와 업무 409, 503 IDEMPOTENCY_UNAVAILABLE 재전송 소진이 같은 줄이 된다.
텔레메트리로는 결과 불명 쓰기의 비율을 셀 수 없다. 03-01이 고쳐져도 업무
거절은 선언 전까지 결과 불명이라 이 구분이 필요하다.

고른 방법
- effect_certainty 키: 진단·텔레메트리(api.request.failed 선택 속성) 모두
  HttpEffectCertainty 다섯 값만 받는 닫힌 value policy(isEffectCertainty)를
  쓴다. cardinality는 bounded. projector가 두 sink에 싣는다.
- 결과 불명 원인: Envelope 명령에서 표가 MAYBE_APPLIED를 줄 때 닫힌
  UnknownEffectReason을 진단 reason으로 싣는다. IN_FLIGHT(409 처리 중),
  IDEMPOTENCY_UNAVAILABLE, COMPLETION_UNKNOWN, RECOVERY_REQUIRED,
  SERVER_TIMEOUT(503 REQUEST_TIMEOUT), STAGE_UNKNOWN(단계를 모르는 400·409·
  422). 텔레메트리에는 싣지 않는다(VD-07: reason은 진단 전용).
- VD-07 5-1의 projector 키 목록과 reason 값 목록을 고쳤다. 남아 있던
  "effect_certainty는 필요해지면 더한다" 문장은 지웠다.

버린 대안
- 백엔드 error.code 원문을 진단에 싣기: cardinality 결정(1101 README 14.6)이
  먼저다. 닫힌 원인 집합이면 그 결정과 무관하다.
- 원인도 텔레메트리에: 텔레메트리 reason은 전달 실패용 닫힌 집합이라 뜻이
  섞인다. 비율은 effect_certainty로 센다.

위험·한계
- Envelope가 아닌 operation의 MAYBE_APPLIED는 원인 없이 effect만 남는다.
  응답을 잃은 경우는 outcome(TRANSPORT_FAILURE)이 원인을 보인다.
- 텔레메트리 수집기가 속성 목록을 고정해 두었다면 새 선택 속성을 받도록
  맞춰야 한다.

검증
- RED: envelope 진단 9행(effect·reason), observability 1건, cardinality
  8건 실패.
- GREEN: 처리 중 409는 reason IN_FLIGHT, 업무 409는 STAGE_UNKNOWN, 둘 다
  effect_certainty MAYBE_APPLIED. 진단 투영이 모두 통과한다.
  tests/unit·integration·component·features·contract·runtime-schema·platform
  282파일 중 281파일 통과. 남은 1건은 provider-guardian-transaction의 inotify
  한도(ENOSPC)로 이 변경과 무관하다.
- check:diagnostics, check:types, lint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/03-adapters-http-state.md 03-05
2026-11-04 20:54:24 +09:00
DongHyeonka f485e51e21 feat(bootstrap): 제품이 세션과 함께 닫을 것을 scopeParticipants로 넘긴다
문제: browser-files runtime은 세션을 모르고, 닫는 수단은
runtime.dispose() 하나다. 설계 문서는 로그아웃·계정 전환에 "server-state
scope reset participant로 dispose()를 등록하라"며 템플릿 소유 파일
runtime-adapters.ts를 가리키는데, 매뉴얼은 제품이 그 파일을 고치지
않는다고 한다(09-02). 제품 확장 지점 composeProduct는 부팅 때 한 번
불리고, context에 participant 등록도 lifecycle 구독도 없다. 그래서
연결하지 않으면 이전 사용자가 고른 File, preview blob URL, 진행 중
download가 다음 세션까지 남는다(공유 기기에서 이전 사용자 파일이
메모리와 다운로드 폴더에 남을 수 있다).

고른 방법(리뷰 5.3절 (다) + 레시피 예제):
- ProductComposition에 선택 칸 scopeParticipants(ProductScopeParticipant:
  label, close)를 둔다. 템플릿은 scope reset의 §10.6 10단계(offline
  lease 해제) 자리에 "product" participant 하나를 두고, composeProduct가
  돌려준 것을 순서대로 부른다. 하나가 실패해도 나머지를 부르고, 실패가
  있으면 template participant와 같이 READY로 가지 않는다(FAILED).
  composeProduct는 scope가 생긴 뒤 불리므로(context가 fence를 쓴다) 이
  자리를 미리 만들고 나중에 채운다.
- recipes/frontend-capabilities/browser-file-session-capability.ts:
  기능에는 runtime 대신 current() getter를 주고, participant가 dispose한
  뒤 다음 호출에서 새 runtime을 만든다. indexeddb 레시피와 같은 자리다.
- 설계 문서와 매뉴얼 03 C절이 이 방법을 가리킨다. 제거 드릴이 새
  레시피 파일도 같이 지운다.
버린 대안: (가) 문서만 고침 — feature presentation은 adapter를 만들 수
없어 제품마다 factory를 다시 설계한다. (나) context에 lifecycle 구독
위임 — FENCED → participant → READY 순서와 "실패는 READY를 막는다"를
제품이 직접 지켜야 한다. (라) runtime이 세대 AbortSignal을 받음 —
adapter가 세대를 알게 되고 다른 opt-in runtime도 따로 받아야 한다.

위험·한계:
- 제품 계약 표면이 하나 는다(선택 칸이라 기존 제품 파일은 그대로
  컴파일된다, [계약]).
- 기능은 current()를 작업마다 불러야 한다. 이전 세대에서 받은 runtime을
  들고 있으면 UNAVAILABLE을 받는다. FENCED 동안 current()를 부르면 다음
  세대 runtime이 미리 만들어진다(빈 runtime이라 이전 사용자 데이터는
  없다).
- app dispose(infrastructure.dispose)는 제품 participant를 부르지 않는다.
- 실제 브라우저 2탭 로그아웃 E2E는 없다(조립된 화면이 없다).
- scripts/test-browser-file-storage-runtime-removal.ts는 02-06 담당 작업도
  고칠 수 있는 파일이다. runtimePaths에 한 줄만 더했다.

검증:
- RED: tests/recipes/browser-file-session-capability.test.ts가 계정 전환
  뒤에도 이전 runtime의 readRange가 ok로 실패.
- GREEN: 같은 테스트에서 계정 전환 뒤 ① 이전 runtime readRange
  UNAVAILABLE ② 진행 중 bounded download ABORTED, handoff 0회 ③ 새 세대
  runtime의 파일 선택 SELECTED. tests/unit/runtime-adapters-product-scope-
  participants.test.ts 2건(순서, 실패 시 FAILED와 나머지 실행).
- 변이 4개(등록 누락, 실패 삼킴, 첫 실패에서 멈춤, 레시피 dispose 누락)
  모두 새 테스트가 잡았다.
- runtime-adapters 관련 unit 3파일 + tests/recipes 47건 통과.
  check:types, 바꾼 파일 eslint, check:architecture, verify:documentation
  통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
2026-11-04 20:54:20 +09:00
DongHyeonka d02efe7bc9 feat(bootstrap): 세션 owner context에 시간 제한 있는 fetch와 페이지를 준다
문제: composeProductSessionOwner는 config와 raw fetcher만 받는다. owner는
http보다 먼저 만들어져 세션 조회·토큰 호출을 직접 해야 하는데, 응답하지
않는 호출 하나가 세션을 recovery-pending에 영원히 둔다. 픽스처의 쿠키
owner 스케치가 바로 그렇게 쓴다. 로그인 리다이렉트에 필요한 페이지
(location·history)와 sessionStorage도 bootstrap lint가 전역 접근을 막아
제품 파일에서 얻을 길이 없다.

고른 방법: ProductSessionOwnerContext에 넷을 더한다.
- fetch: 헤더와 본문 전체에 마감 하나(REQUEST_TIMEOUT_MS가 상한, 호출이
  줄일 수만 있다). 본문은 64 KiB까지 메모리로 읽어 새 Response로 준다.
  redirect는 항상 error. fetcher가 signal을 무시해도 경합으로 끝난다.
- readCookie: composeProduct와 같은 host cookie 읽기.
- page: href·replaceUrl·assign. host에 없으면 throw로 닫힌다.
  replaceUrl은 라우터의 history state를 그대로 둔다.
- redirectStorage: host sessionStorage. 토큰이 아니라 리다이렉트 한 번
  동안의 상태만 둔다고 계약에 적었다.
조립은 새 파일 product-session-owner-context.ts에 두고
runtime-adapters.ts는 호출 한 곳만 바꿨다. fetch 구현
(session-owner-fetch.ts)은 처음 쓸 때 동적 import로 읽는다. 초기 번들
여유가 3 KB 남짓이라 demo 모드나 owner 없는 제품이 이 코드를 내려받지
않게 했다.
버린 대안:
- platform 커널 createAbortableOperation 사용. 커널이 boot가 이미 읽는
  배럴과 같은 청크로 묶여 지연 청크로 빼도 초기 번들에 남았다(빌드로
  확인). 그래서 read-bounded-boot-json.ts와 같은 마감 방식을 쓴다.
- 마감만 주고 본문은 owner가 읽게 두기. 본문이 멈추면 다시 무한 대기다.

위험·한계: fetch는 필수 필드라 ProductSessionOwnerContext를 직접 만드는
제품 테스트는 컴파일이 깨진다. 기존 fetcher는 그대로 둔다. 지연 청크
적재 시간은 마감에 들어가지 않는다(라우트 청크와 같다).

검증: tests/unit/product-session-owner-context.test.ts 12건(구현 전 모듈
없음으로 실패 확인), product-composition-fixture·runtime-adapters 테스트
통과, check:types, eslint 통과. build + check:bundle: initial JS
202,242 / 204,800 B gzip(09-11 포함, 기준 201,848), 지연 청크
session-owner-fetch 0.81 kB gzip.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:46:40 +09:00
DongHyeonka 2963c6f42c fix(features): 선택 런타임(SW 등) 선택을 제품 소유 파일로 옮긴다 (1103/09-05)
문제
Service Worker를 켜는 유일한 방법은 src/features/installed-runtime-capabilities.ts의
SERVICE_WORKER 상수를 바꾸는 것이었다. 그 파일에는 "Product-owned." 표시가
없고, 매뉴얼 03 D절은 src/features/installed-*.ts를 고치지 말라고 한다.
매뉴얼대로 하면 SW를 켤 수 없고, 켜면 동기화마다 템플릿 파일을 손으로
병합한다. 템플릿 상태 설명과 제품 선택 상수가 한 블록에 섞여 있었다(1101/09-05).

고른 방법
리뷰의 최소 방향을 따른다.
- 선택 상수 넷(REALTIME, WEB_WORKERS, SERVICE_WORKER, OFFLINE_COMMANDS)을 제품
  소유 src/features/product-capabilities.ts의
  PRODUCT_RUNTIME_CAPABILITY_SELECTION으로 옮긴다. 09-02에서 만든 같은 새 제품
  소유 파일이다. product-contracts.ts에 넣지 않은 이유: 계약 층(src/contracts)이
  아니라 기능 카탈로그 옆의 선택이고, 템플릿은 복사 뒤 기존 제품 소유 파일에
  칸을 더하지 않는다.
- installed-runtime-capabilities.ts는 템플릿 소유로 남고 그 선택을 검사
  (validateRealtimeContributions, validateWebWorkerContributions)하고 투영만
  한다. §3.5 설명과 템플릿 상태 설명은 여기에 남는다.
- 매뉴얼 03 C절에 "SW 켜기"를 넣었다. 조립 거절 메시지, e2e SW 빌드 도우미의
  편집 대상(premise 1), 레시피·운영 문서, dependency-cruiser 주석의 경로를
  새 파일로 바꿨다.
- 09-02 typecheck 테스트는 이제 출하된 product-capabilities.ts에 타입만 채우고
  (선택은 유지), 복사 목록은 REMOVAL_FIXTURE_COPY_TARGETS 하나를 쓴다.

위험·한계
- 리뷰가 함께 제안한 composeProduct의 SW 연결 칸(blockers, observe)은 만들지
  않았다. 그 연결은 여전히 템플릿 파일 create-runtime-composition.ts를 고쳐야
  한다. 매뉴얼 "SW 켜기"에 적었다.
- 템플릿 안의 선택을 이미 바꾼 다운스트림은 값을 새 파일로 옮겨야 한다.

검증
- RED: tests/unit/product-runtime-capability-selection.test.ts 3건(선택이 제품
  소유 파일에만 있음, 제품 SW 선택 투영, 잘못된 선택은 여전히 검사)이 수정 전
  실패.
- 그 테스트, service-worker-build-output, optional-runtime-host,
  runtime-composition-service-worker-telemetry, product-features,
  product-extension-typecheck, runtime-adapters 통과.
- check:types, check:architecture, eslint, verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-05
2026-11-04 20:35:11 +09:00
DongHyeonka 245f428123 fix(features): 제품 capability 타입과 기본값 설정 키가 타입 검사 3종을 통과한다 (1103/09-02)
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.

고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
  FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
  extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
  프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
  capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
  파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
  고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
  쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
  테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
  바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
  강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
  기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
  frontend-application-foundation, 계약 주석.

위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
  아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
  적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
  옮겨야 node 검사가 통과한다.

검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
  테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
  verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
2026-11-04 20:30:47 +09:00
DongHyeonka 0aada28b91 fix(bootstrap): 401을 그 요청의 자격 증명을 낸 쪽에만 알린다 (1103/09-01)
문제
조립 루트는 응답이 있는 UNAUTHENTICATED면 프로필을 보지 않고
authSession.onUnauthenticated()를 불렀다. ANONYMOUS 요청은 세션을 묻지 않고
헤더 없이 나가는데도, 그 401이 로그인한 사용자를 로그아웃시키고 scope fence가
서버 상태 캐시를 모두 비웠다. 제품 credentialProviders가 자격 증명을 낸
요청의 401도 템플릿 세션을 로그아웃시켰다.

고른 방법
attachCredentials와 같은 순서로 401의 주인을 가른다(reportServerUnauthenticated).
- ANONYMOUS 프로필: 아무에게도 알리지 않는다.
- 제품 provider 프로필: 세션은 그대로 두고, ProductComposition의 선택 hook
  onCredentialRejected({operationId, authProfileId})를 부른다. BFF 제품은
  거기서 자기 owner에게 알린다. hook의 throw는 결과를 바꾸지 않는다.
- 나머지(템플릿 세션이 낸 자격 증명): 지금처럼 onUnauthenticated().
버린 대안: ANONYMOUS만 빼기(2줄)는 provider 경로의 과잉 로그아웃이 남는다.
owner가 401을 직접 판단하게 하면 owner 계약이 바뀌고 모든 owner가 판단
로직을 쓴다.

위험·한계
- 제품 provider가 템플릿 세션과 같은 세션의 자격 증명을 내는 경우, 제품이
  hook을 쓰지 않으면 그 401은 세션을 바꾸지 않는다. 계약 주석과 매뉴얼 02
  5절에 적었다.
- 401 도착과 계정 전환이 겹치는 경쟁은 여전히 확인하지 않았다.

검증
- RED: 새 테스트 3건(ANONYMOUS 401 demo·external, provider 401)이 수정 전
  실패했다. bearer 대조군은 수정 전후 모두 통과.
- node scripts/run-vitest.ts run runtime-adapters-{auth-profile,credential-order},
  runtime-adapters, product-composition-fixture, reference-runtime-composition
  → 5 files / 62 tests 통과. check:types 통과. eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-01
2026-11-04 20:15:26 +09:00
DongHyeonka e40684b4e1 chore(review): 리뷰 기준으로 두 작업 브랜치를 합친다
문제
2026-11-03 전체 리뷰는 출시될 코드 전체를 봐야 한다. 오늘 고친 것이 두 브랜치에
나뉘어 있다. claude/happy-easley-233d07(Envelope, V2 삭제, 거절 표, CSRF·KEYED
재전송)과 fix/ui-design-audit-2026-11-01(남은 위험 16커밋)이다. 사용자가 두
브랜치를 합친 상태를 리뷰 기준으로 골랐다.

고른 방법
새 브랜치 review/2026-11-03-merged에서 두 브랜치를 합쳤다. 원래 두 브랜치는
건드리지 않았다. 충돌은 계약 문서 4.1·6절 두 곳이었다.
- 4.1: 백엔드 기준 SHA(5786126c) 문장은 fix 쪽을, Envelope를 읽는 곳은 V2가
  없어진 이쪽을 택했다.
- 6절: 거절 판정 위치는 backend-envelope.ts 표다.
- 6.1 "프론트 판정과 표가 다른 곳"에서 3261208이 고친 두 항목을 지웠다.

위험·한계
- 이 합치기는 리뷰 기준을 고정하려는 것이다. 어느 브랜치를 main에 합칠지는
  사용자가 정한다.

검증
- check:types 통과. 나머지 게이트는 리뷰 기록(9절)에 적는다.
2026-11-03 22:49:20 +09:00
DongHyeonka 048f490ada refactor(http)!: V2 HTTP 클라이언트를 지우고 V3 실행기 하나만 남긴다
문제
HTTP 실행 경로가 둘이다. V3 실행기(createContractHttpExecutor)가 모든 기능을
실행하고, V2 클라이언트(createHttpClient)는 bootstrap의
createRuntimeHttpClient에서만 만들어지는데 그 함수를 앱 안에서 부르는 곳이
없다(테스트만 부른다). tech-log·memento도 같다. 그런데도 V2는 초기 청크에
들어가고, 짝 백엔드 해석(7db32e1~3261208)과 테스트를 두 벌로 유지하게 했다.
사용자 지시: 레거시를 두지 말고 최신 경로 하나만 남긴다.

고른 방법
- src/adapters/http/의 client.ts, bounded-json.ts, request-builder.ts,
  resource-mapper.ts, retry-policy.ts, schema-registry.ts를 지웠다. Envelope
  스키마는 backend-envelope.ts로 옮겼다. V3가 retry-policy.ts에서 쓰던
  parseRetryAfter는 그것이 감싸던 platform/retry-after.ts의
  parseRetryAfterDelay를 직접 부른다.
- 배럴의 V2 export와 bootstrap의 createRuntimeHttpClient·RuntimeHttpContract를
  지웠다.
- V2 전용 테스트(http-client, http-diagnostics, auth-recovery,
  legacy-http-credential-authority, bounded-json-compatibility,
  request-builder, retry-policy)와 tests/helpers/http-contract-fixture.ts를
  지웠다. 섞인 파일(http-execution-contract, runtime-adapters,
  boundary-mapper)은 V2 블록만 지웠다.
- V2로 돌던 폼 테스트(form-foundation)는 Envelope을 읽는 V3 keyed create
  계약으로 옮겼다. 400 VALIDATION_FAILED 필드 오류, {cause} 뒤 다시 저장,
  422 뒤 저장 꺼짐을 그대로 검사한다. http-execution-v3-envelope 테스트는 V2와
  비교하던 행을 기대 판정을 직접 적는 행으로 바꿨다.
- drill:runbook FE-RB-003은 V2 shouldRetry 대신 V3 실행기를 실제로 돌려
  보낸 요청 수를 센다(NEVER 503: 1회, SAFE 503: 재시도, SAFE 스키마 불일치:
  1회).
- check:diagnostics의 http 이벤트 생산자, registry-governance의 오류 표 소비자,
  risk-coverage 고위험 경로, 아키텍처 금지 fixture, adapter INVENTORY, 문서의
  경로를 V3 파일로 바꿨다.

버린 대안
- V2를 @deprecated로 한 릴리스 남기기: 템플릿과 두 다운스트림 모두 부르는
  곳이 없어 옮겨 갈 사용자가 없다. 남기면 초기 JS와 두 벌 유지 비용만 남는다.

위험·한계
- BREAKING: 배럴과 bootstrap의 V2 이름을 쓰던 제품 코드는 컴파일이 깨진다.
  CHANGELOG에 옮기는 방법을 적었다.
- V2에만 있던 동작이 사라졌다: 401 뒤 세션 복구 후 한 번 재전송, KEYED 503
  자동 재시도. V3는 401을 UNAUTHENTICATED로 넘기고 KEYED 요청은 보낸 뒤
  재시도하지 않는다.
- 기능마다 적는 V2 API 행(*-api-contract.ts, check:registries가 읽음)은 이
  커밋에서 지우지 않았다. 다음 커밋이 지운다.

검증
- check:types, lint, check:architecture(금지 fixture 9건 거절),
  check:adapter-inventory(140 files), check:diagnostics, check:registries,
  check:ci, verify:documentation 통과.
- test:unit 2,585, test:integration 114, test:component 245, test:contract 23,
  test:runtime-schema 56, tests/features 101 통과.
- drill:runbook FE-RB-003: no local check failed.
- check:bundle 통과. 초기 JS 203,354 → 201,598 B(−1,756 B).

BREAKING CHANGE: src/adapters/http/index.ts가 createHttpClient, HttpClient,
HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler,
OperationRequestInput를, src/bootstrap/runtime-adapters.ts가
createRuntimeHttpClient, RuntimeHttpContract를 내보내지 않는다. 그 operation의
V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다.
2026-11-03 21:12:34 +09:00
DongHyeonka ece944d08b feat(bootstrap): 제품 세션 owner와 FE-REG-ENV 행을 제품 파일로 받는다 (1101/09-02)
문제
09-02(da1e128) 뒤에도 tech-log가 하는 일 두 가지는 템플릿 파일을 고쳐야
한다(리뷰 1101 README 14.4 "09-02 이식").
- 제품 설정 키의 FE-REG-ENV 행: tech-log는 템플릿 src/contracts/env.ts의
  ENV_REGISTRY에 TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE 행을 직접
  넣었다(tech-log env.ts:63-70).
- 부트 전 BFF 세션 owner: 세션이 httpOnly 쿠키라 owner가 백엔드에 묻는다.
  tech-log는 템플릿 create-runtime-composition.ts에서 AUTH_MODE external이고
  Studio가 HTTP일 때 createRuntimeAdapters 전에 host 전역
  __CA_FRONTEND_AUTH_OWNER__에 owner를 넣는다(:2, :36-52,
  bff-session-owner.ts:188-194). composeProduct는 http가 생긴 뒤에 불리고
  http는 세션이 필요해서 이 일을 받을 수 없다.

고른 방법
- product-contracts.ts에 PRODUCT_ENV_REGISTRY를 빈 값으로 둔다. env.ts는
  PRODUCT_REST_AUTH_PROFILES·PRODUCT_RUNTIME_CONFIG_FIELDS와 같은 모양으로
  그 행을 ENV_REGISTRY에 합친다. 템플릿 키와 이름이 겹치면 모듈 로드 때
  throw한다. check:registries와 vite.config.ts가 같은 객체를 읽으므로 제품
  행도 같은 필드 검사를 받는다. 행을 더하기만 하면 additive라 기준선을
  고치지 않는다(실험: 제품 행 2개 → compatibility=additive PASS, 허용 밖
  classification → 실패).
- product-composition.ts에 composeProductSessionOwner(context)를 둔다.
  템플릿은 null을 돌려준다. 조립 루트가 세션을 고르기 전에, AUTH_MODE가
  external일 때만 부른다. 제품 owner가 host 전역보다 먼저다. null이면
  지금처럼 host 전역, 없으면 unavailable이다. demo 모드는 묻지 않는다.
  context는 config와 fetcher뿐이다(http 전이라 capability가 없다).

버린 대안
- owner를 composeProduct 반환값에 넣기: http가 세션을 쓰므로 순서가 꼬인다.
- 제품이 host 전역에 계속 넣게 두고 문서화: 부트 전 훅이 템플릿 파일
  (create-runtime-composition.ts)에 남는다.
- FE-REG-ENV 행을 PRODUCT_RUNTIME_CONFIG_FIELDS에서 자동으로 만들기: zod
  필드로는 classification·required를 알 수 없다.
- 행 타입·도우미를 product-contracts.ts가 env.ts에서 import: 순환 의존
  (no-circular-dependencies)이다. 타입 검사는 env.ts의 대입에서 한다.

위험·한계
- product-composition.ts에 export가 하나 늘었다. 이 파일을 이미 복사한
  제품은 composeProductSessionOwner를 더해야 한다. da1e128은 아직 main에
  없고 두 다운스트림 모두 받지 않았다.
- 제품 행을 as const 없이 쓰면 phase가 string으로 넓어져 tsc 오류가
  env.ts:78(템플릿 파일)에서 난다. 메시지에 키 이름은 나온다. product-
  contracts.ts 주석에 as const를 적었다.
- 제품 설정 키에 FE-REG-ENV 행이 있는지 요구하는 검사는 여전히 없다.
  템플릿 키도 RELEASE_ID·BUILD_ID는 행이 없어서 이 변경에서 넣지 않았다.
- 제품 owner가 throw하면 createRuntimeAdapters가 실패해 부트 실패
  화면이 된다. composeProduct와 같다.
- tech-log의 owner는 subject를 null로 돌려준다(템플릿 동작대로 매 변경
  fence). 이 변경과 무관하다.

검증
- RED: tests/unit/product-composition-fixture.test.ts 13건 중 3건 실패.
  FE-REG-ENV 행 없음, external 모드 세션이 authenticated가 아니라
  integration-failed, env 이름 충돌을 거절하지 않음.
- GREEN: 같은 파일 13/13, runtime-adapters-credential-order 7/7(mock에
  composeProductSessionOwner: () => null 추가).
- fixture는 vi.mock 대상이 제품 소유 두 파일(머리 주석 "Product-owned.")과
  설치 기능 seam 두 개뿐이고, tech-log가 고친 템플릿 파일 4개(env.ts,
  create-runtime-composition.ts, runtime-config-schema.ts,
  runtime-adapters.ts)는 대상이 아님을 이 파일의 소스를 읽어 확인한다.
- 회귀: tests/unit·contract·runtime-schema·integration 198 files 2861
  tests 통과(heavy lock 아래).
- tsc app·node·test 통과, 바꾼 파일 eslint 통과, check:registries PASS
  (compatibility=none, 재승인 불필요), verify:documentation PASS_SCOPED,
  check:adapter-inventory PASS.
- 초기 JS gzip 202,770 → 202,931 B(+161, 예산 204,800). 같은 방법(dist
  manifest의 초기 파일 26개, gzipSync 기본 레벨)으로 전·후를 쟀다.
- 미실행: check:architecture(pnpm 필요), test:component, e2e.
2026-11-03 20:23:14 +09:00
DongHyeonka b26517e6f2 fix(docs): 설계 주석에 문서 이름을 붙이고 지운 뒤 끊기는 링크를 없앤다 (1101/14-01)
문제: 코드 주석 87곳(74파일, .dependency-cruiser.json 포함)이 "Spec §N"
처럼 문서 이름 없이 절 번호만 적는다(대문자 83, 소문자 "spec §" 4).
가리키는 설계서는 README가 복사 뒤 지워도 된다고 한 docs/reviews/ 안에
있었다. 지울 수 있는 기록 검사는 경로 문자열만 찾아 이 참조를 잡지
못했다. 현재 계약 문서도 지울 수 있는 파일로 링크한다:
docs/reviews/adapters/INVENTORY.md 145행이 옆의 adapter 리뷰로,
docs/operations/adapter-remediation-ledger.md가 adapter 리뷰와
docs/superpowers/plans의 계획으로.

고른 방법:
- 주석의 "Spec §"/"spec §"를 "scale-architecture.md §"로 바꾼다(앞
  커밋이 옮긴 docs/architecture/scale-architecture.md). 설명 문장과 절
  번호는 그대로다. 절 번호가 없는 "Spec §"는 없었다.
- tests/unit/deletable-history-documents.test.ts에 "spec" + 선택 공백 +
  "§"(대소문자 무시)를 거부하는 검사를 더하고, 검사 대상에
  .dependency-cruiser.json을 넣는다.
- README "Files you can delete after copying"에서 INVENTORY.md 한 파일
  대신 docs/reviews/adapters/ 폴더를 남기게 하고 이유(INVENTORY 행과
  ledger가 그 리뷰로 링크한다)를 적는다. docs/README.md §3도 같게 고친다.
  INVENTORY의 행 구조는 바꾸지 않는다.
- 남긴 adapter 리뷰와 ledger가 docs/superpowers/plans로 거는 링크 5곳은
  링크를 풀고 "작업 이력 계획, 복사본은 지울 수 있다"로 적는다.
버린 대안: INVENTORY 145칸의 링크를 그룹 이름으로 바꾸기. 템플릿에서도
상세 리뷰로 가는 길이 없어지고 수정이 145곳이다. 계획 3개도 지우기
목록에서 빼기. 지울 수 있는 폴더 안에 예외가 흩어지고, 계획이 다시
다른 이력을 가리키면 남길 목록이 계속 커진다.

위험·한계: 검사는 "HTML spec §4"처럼 다른 명세를 "spec §"로 부르는
주석도 거부한다. 그때는 "HTML Standard §4"처럼 이름을 쓴다.
src/contracts/storage-keys.ts:79의 "release-coherence plan Task 6"처럼
이름 없는 계획 참조는 이 검사가 잡지 않는다. 복사한 프로젝트가 이미
docs/reviews/adapters/를 지웠다면 링크는 계속 끊겨 있다. CHANGELOG.md의
이력 언급 4곳(:15 두 경로, :75 PRODUCT.md, :93)은 고치지 않았다.
check:remediation-ledger는 이 변경 전후 같은 4줄로 실패한다(이미 있던
실패, 게이트 밖). tests/unit/telemetry.test.ts의 describe 이름 하나가
바뀐다.

검증:
- RED: 치환 전 새 검사가 87줄을 들어 실패(1 failed | 1 passed).
- GREEN: 같은 테스트 2 passed. 변이 "// Spec §4. budgets live here"를
  src/platform/errors/app-error.ts에 넣으면 그 한 줄로 실패, 되돌림.
- 치환 diff: 바뀐 87줄 쌍이 토큰 외에 같음(스크립트 대조, 불일치 0).
- 삭제 실험(작업 트리 복사본에서 README 목록대로 지움): 끊긴 링크
  148→0, 끊긴 경로 언급 10→4(남은 4는 CHANGELOG.md), 이름 없는 설계
  참조 87→0, scale-architecture.md §N 87곳 중 없는 절 0. 같은 복사본에서
  verify-documentation-readiness PASS_SCOPED, 지울 수 있는 기록 테스트
  2 passed.
- node scripts/verify-documentation-readiness.ts: PASS_SCOPED
- node scripts/check-adapter-inventory.ts: PASS
- node scripts/run-vitest.ts run tests/unit/deletable-history-documents.test.ts
  tests/unit/documentation-readiness.test.ts tests/unit/telemetry.test.ts:
  50 passed. tests/architecture: 39 passed.
- npx tsc --noEmit (app·node·test): 모두 통과. 바꾼 TS 74파일 eslint 통과.
  .dependency-cruiser.json JSON 파싱 통과.
- 미실행: check:architecture(pnpm 필요).
2026-11-03 07:17:49 +09:00
DongHyeonka da1e128999 feat(bootstrap): 제품 capability·자격증명·설정 키를 제품 소유 파일로 받는다 (1101/09-02)
문제
제품이 http·telemetry·indexedDb 밖의 capability, 세션 밖 자격증명(BFF
쿠키 XSRF, Studio CSRF), 제품 런타임 설정 키를 넣으려면
runtime-adapters.ts, feature-adapter-contribution.ts, rest-profiles.ts,
release-artifacts.ts, runtime-config-schema.ts를 직접 고쳐야 한다. 이
파일들은 템플릿이 보안·계약 수정을 자주 넣는 곳이라, 동기화 때마다
fail-closed 코드를 손으로 병합한다(memento +61줄, tech-log +118줄).

고른 방법 (리뷰 09 4.2의 (B))
- FeaturePlatformCapabilities를 interface로 바꾼다. 제품은 이 repo의
  FeatureIndexedDbRepositories·ApplicationFeatureInputs와 같은
  declaration merging으로 capability를 더한다.
- 제품 소유 파일 둘을 빈 구현으로 둔다.
  - src/bootstrap/product-composition.ts: 추가 capability와 "인증 프로필
    id → 자격증명 제공자" 표. 계약 타입은 템플릿 소유
    product-composition-contract.ts에 둔다.
  - src/contracts/product-contracts.ts: 제품 인증 프로필과 런타임 설정
    zod 조각. 프로필 레지스트리와 strict 설정 스키마는 contracts 층에
    있고 빌드 스크립트도 읽는다. contracts는 bootstrap을 import할 수
    없어서 파일을 하나로 합치지 못했다.
- 판단 순서는 조립 루트가 쥔다: scope fence → ANONYMOUS 프로필 → 제품
  제공자 → 세션 → 응답 뒤 fence 재확인. 제공자가 throw하면 executor가
  CREDENTIAL_OWNER_FAILED로 닫는다. 나가는 헤더는 여전히 프로필 허용
  목록이 정한다.
- 제공자 계약은 기존 attachCredentials 시그니처를 그대로 쓴다.
- 제품 composition은 http capability가 생긴 뒤에 부른다. tech-log가
  두었던 전방 참조 stub이 필요 없다.
- 제품에 host 전체를 넘기지 않고 readCookie(name)만 넘긴다. host를 객체에
  담으면 browser-data-boundary/no-capability-alias가 막는다.
- http·telemetry는 spread 뒤에 둬서 제품이 바꿀 수 없다(타입에서도 뺀다).
  제품 프로필 id나 설정 키가 템플릿 이름과 겹치면 모듈 로드 때 throw한다.

버린 대안
- (A) 현 상태: 템플릿 비용은 0이지만 제품마다 동기화 비용이 반복된다.
- (C) 기능 계약 기여가 인증 프로필과 제공자를 함께 가져온다: 인증
  정책이 기능마다 흩어져 보안 리뷰 범위가 넓어진다.
- 제공자에 응답 관찰 훅 추가: tech-log의 401/403 토큰 폐기는 제품
  capability가 http를 감싸서 표현된다(픽스처). 제공자 계약을 작게 둔다.

위험·한계
- memento의 x-xsrf-token은 닫힌 자격증명 헤더 목록(VD-23,
  CREDENTIAL_HEADER_NAMES)에 없다. 그 이름을 쓰려면 여전히
  rest-profiles.ts를 고치거나 백엔드가 x-csrf-token을 받아야 한다.
  픽스처는 x-csrf-token으로 표현했다.
- 제품 설정 키의 FE-REG-ENV 행(src/contracts/env.ts)은 이 변경 밖이다.
  그 행을 요구하는 검사는 없다.
- tech-log가 부트 전에 BFF 세션 owner를 설치하는 코드
  (create-runtime-composition.ts)는 이 확장 지점 밖이다.
- 제공자 응답 뒤 fence 재확인은 executor가 같은 fence로 먼저 전송을
  끊어서 조립 루트 경유 테스트로는 따로 보이지 않는다. 세션 경로와 같은
  이중 방어로 둔다.
- V1 설정 문서도 제품 키를 받는다(없으면 기본값). V1은 한 릴리스 동안만
  쓰는 리더다.
- 초기 JS gzip 203,818 → 204,178 B(+360, 예산 204,800).

검증
- RED: tests/unit/runtime-adapters-credential-order.test.ts 7행 중 제품
  제공자를 기대하는 4행 실패(세션이 먼저 답해 UNAUTHENTICATED, owner가
  먼저 답해 SUCCESS). fence·ANONYMOUS·세션 3행은 통과.
- GREEN: 같은 파일 7/7. tests/unit/product-composition-fixture.test.ts
  9/9(가짜 제품 파일 두 개로 offsetUpload, runtime, BFF 쿠키 XSRF 읽기·
  쓰기, Studio CSRF 발급·403 폐기, 제품 설정 키, 이름 충돌 거절). 09-01
  tests/unit/runtime-adapters-auth-profile.test.ts 12/12.
- 회귀: tests/unit·contract·runtime-schema 182 files 2590 tests 통과.
  integration·component 47 files 386 tests 통과(pnpm을 띄우는
  security-followup-archive 제외). tsc app·test·node·recipes·web-worker·
  service-worker 통과. 바꾼 파일 eslint 통과. check:registries PASS
  (compatibility=breaking은 기존 route·storage 행). verify:documentation
  PASS_SCOPED. check:adapter-inventory PASS. check:architecture는 pnpm 대신
  exec 전용 shim으로 그래프·fixture PASS. 템플릿 런타임 설정 JSON
  schema는 baseline과 같다.
2026-11-03 00:56:40 +09:00
DongHyeonka 48a4074e3a fix(bootstrap): 시작할 런타임이 없는 선택 capability를 조립 때 거절한다 (09-07)
문제: 선택 파일은 "Adding an entry here is what installs a capability"라고
적지만 optional host가 실제로 시작하는 것은 Service Worker뿐이다.
realtime·webWorkers·offlineCommands에 항목을 넣으면 아무것도 시작되지
않고 health는 UNAVAILABLE로 남는데, 플랫폼 개요가 읽는 스냅샷은 그
선택을 active로 세어 "활성 (1)"을 보인다. 경고도 실패도 없다.

고른 방법:
- `createOptionalRuntimeHost`가 시작 수단이 없는 capability(realtime,
  webWorkers, offlineCommands)가 선택돼 있으면 그 이름을 모두 담아
  throw한다. 런타임 설정으로 끈 선택은 resolve 단계에서 빠지므로 막지
  않는다. host는 부트 조립에서 만들어지므로 부트 실패 화면으로 드러난다.
- 선택 파일 주석을 "Service Worker만 여기서 설치된다. 나머지는
  composition에 런타임을 먼저 연결해야 한다"로 고쳤다.

버린 대안: 주석만 고치기. 스냅샷이 계속 active로 세고, 선택한 제품은
여전히 아무 신호도 받지 못한다.

위험·한계:
- 런타임을 연결하는 제품은 host의 시작 순서와 이 검사를 함께 바꿔야
  한다(09-02 확장 지점과 같은 자리). 검사 주석에 적었다.
- health 계산의 세 capability `UNAVAILABLE` 분기는 이제 닿지 않지만,
  런타임을 연결할 때 쓸 자리라 남겼다.
- 리뷰 09-05(선택 파일에서 템플릿 상태 설명 분리)는 하지 않았다.
- 초기 JS +127 B gzip(202,995 → 203,122 B, 여유 1,678 B).

검증:
- RED: tests/unit/optional-runtime-host.test.ts의 새 테스트 3건(capability별
  하나)이 "expected [Function] to throw an error"로 실패.
- GREEN: 같은 파일 9건 통과.
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,933건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{component,platform,
  architecture,features,contract} 570건 통과. 그중
  app-build-input.test.ts 1건이 부하 25에서 10초 시간 초과로 실패했고,
  heavy lock 아래 단독 재실행에서 4건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka 4da046683f fix(http): 전송 전 거절의 원인을 진단에 남기고 연결 실수를 구분한다 (03-02)
문제
전송 전 실패가 네 곳에서 원인 없는 위반 FINAL_REQUEST_INVARIANT_FAILED
하나로 바뀐다. 입력 검증 실패, 요청 조립 실패 10종(PATH_PLACEHOLDER_MISSING
등), 최종 불변식 실패 12종, 미설치 계약이다. 바인딩은 이 위반과
MISSING_IDEMPOTENCY_KEY·UNEXPECTED_IDEMPOTENCY_KEY를 모두 VALIDATION_REJECTED로
바꿔 "서버가 입력값을 받아들이지 않았습니다"를 띄운다. 그래서 경로
placeholder 오타나 mutation 정책과 계약의 불일치 같은 개발자 연결 실수가
사용자 입력 문제처럼 보이고, 진단에는 원인이 없다. 미설치 계약은 실행기를
거치지 않아 진단이 0건이다. 또 마감이 시도별 budget 읽기와 최종 불변식
검사 사이에 끝나면 DEADLINE_EXPIRED도 같은 위반이 되어, 시간 초과가 "입력
거절"로 보인다(P-03-05).

고른 방법
- HttpContractViolation에 선택 필드 reason(닫힌 집합
  HttpRequestRejectionReason)을 더한다. 실행기의 세 거절 지점이
  refusedRequest(reason)로 위반을 만들고, finish()가 그 reason을 관측의
  diagnosticReason으로 옮긴다. projector는 03-05에서 만든 경로대로
  diagnostics에만 reason을 싣는다. telemetry는 error_kind 그대로다.
- 최종 불변식의 DEADLINE_EXPIRED는 budget 읽기 분기와 똑같이
  TRANSPORT_FAILURE/TIMEOUT으로 끝낸다(P-03-05).
- 바인딩은 사용자가 입력을 바꿔 고칠 수 있는 거절(INPUT_INVALID,
  PATH_VALUE_INVALID, QUERY_TOO_LARGE, URL_TOO_LARGE, REQUEST_BODY_TOO_LARGE)과
  reason 없는 거절만 VALIDATION_REJECTED로 둔다. 나머지 reason과 멱등 키
  위반은 UNKNOWN_CLIENT_FAILURE(문의 행동, "요청을 처리할 수 없습니다.")로
  낸다. V2 client가 미등록 operation을 같은 종류로 내는 것과 맞췄다.
- 미설치 계약 분기는 같은 projector로 관측 1건(reason
  CONTRACT_NOT_INSTALLED)을 직접 남긴다.

버린 대안
- 새 FailureKind 추가: 오류 레지스트리·i18n 카탈로그·화면 분기를 다 바꿔야
  한다. 이미 있는 UNKNOWN_CLIENT_FAILURE가 "클라이언트 결함, 문의"라는 같은
  뜻이고 V2에서 같은 상황에 쓰고 있다.
- 리뷰 예시대로 MAPPING_CONTRACT_VIOLATION으로 내기: 문구가 "서버 응답을 화면
  데이터로 바꾸지 못했습니다"라 응답이 없는 전송 전 실패와 맞지 않는다.
- 사용자 입력 쪽을 reason별 Record로 망라하기: 컴파일 시 분류를 강제하지만
  20여 줄이 는다. 새 reason은 기본으로 클라이언트 결함이 되는 쪽이 안전하므로
  입력 쪽 5개만 Set으로 적었다.
- terminalReason에 원인을 싣기(리뷰 문구): 03-05와 같은 이유로 버렸다.

위험·한계
- 동작 변경: 멱등 키 위반과 연결 실수가 VALIDATION_REJECTED에서
  UNKNOWN_CLIENT_FAILURE로 바뀐다. 폼은 필드 오류 대신 "unavailable" 상태
  안내를 띄운다. 기존 계약 테스트의 기대값을 이에 맞게 바꿨다.
- 입력 검증 실패(INPUT_INVALID)는 리뷰 문구("입력 크기 초과만")와 달리
  VALIDATION_REJECTED로 남겼다. 입력 validator의 거절은 사용자 입력 문제다.
- reason 없는 FINAL_REQUEST_INVARIANT_FAILED(다른 실행기 구현)는 기존대로
  VALIDATION_REJECTED다.
- AppFailure.code는 지금처럼 위반 종류다. 원인 코드는 진단에만 있다.
- 공개 타입은 추가만 했다(위반 선택 필드 1개, 진단 reason 집합 확장).
- validator가 throw하는 경우(VALIDATOR_RUNTIME_FAILURE → SCHEMA_MISMATCH,
  "서버 응답 데이터가…" 문구)는 이번 범위가 아니라 그대로다.
- 미설치 계약 거절도 다른 CONTRACT_VIOLATION처럼 api.request.failed
  telemetry 1건을 낸다(VD-07 규칙 5).
- 화면: 정상 상태는 그대로이고 위 실패에서만 문구가 바뀐다. 시각 골든은
  다시 찍지 않았다.

검증
- RED(수정 전):
  - http-execution-v3-observability "names a refused request's assembly
    cause in diagnostics only (03-02)": violation.reason 없음.
  - 같은 파일 "ends a deadline that expires at the final invariant check as
    a timeout (P-03-05)": TRANSPORT_FAILURE 기대, 실제 CONTRACT_VIOLATION.
  - feature-http-binding 계약 테스트 5건: PATH_PLACEHOLDER_MISSING,
    CONTRACT_NOT_INSTALLED, HEADER_NOT_ALLOWED, MISSING_IDEMPOTENCY_KEY,
    UNEXPECTED_IDEMPOTENCY_KEY가 VALIDATION_REJECTED로 나옴.
  - runtime-adapters-auth-profile "is refused without a fetch and leaves one
    diagnostic naming the cause": reason 없음, 진단 0건.
- GREEN: 세 파일 38/38 통과.
- 회귀: run-vitest tests/unit tests/integration tests/component
  tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
  13개 제외) 227 files 중 226 통과, 2354/2355. 실패 1건은
  provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
  다른 실행 때문)로 HTTP와 무관하다. 제외했던 http-scenario-evidence는
  pnpm을 띄우지 않아 따로 돌렸고 14/14 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 스크립트 필요), 번들 크기 측정.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
DongHyeonka f8a492a6ad fix(http): 문제 응답 분류기 실패를 진단 reason으로 남긴다 (03-05)
문제
기능 패키지의 classifyProblem이 throw하거나 집합 밖 값을 돌려주면
classifyProblemEffect는 MAYBE_APPLIED + contractRuntimeFailure: true를
돌려준다. 주석과 설계서(closed-deep-design.md:650)는 이것을 "contract
runtime failure로 기록한다"고 적지만, 실행기는 .effect만 쓰고 플래그를
버린다. 그래서 분류기가 throw한 409와 분류기가 정말 MAYBE_APPLIED라고
답한 409의 관측 기록·진단이 요청 id 말고 똑같다. 또 이 안전 기본값을
NOT_APPLIED로 바꿔도(변이 M5) 영역 테스트가 하나도 실패하지 않는다.

고른 방법
- HttpExecutionObservation에 선택 필드 diagnosticReason을 더한다. 타입은
  닫힌 집합 HttpDiagnosticReason이고 지금 값은 CLASSIFIER_FAILED 하나다.
  문제 응답 admission이 명령의 contractRuntimeFailure를 이 값으로 바꾸고,
  finish()가 관측 기록에 싣는다.
- 조립 지점의 projector는 이 값을 diagnostics에만 reason으로 더한다
  (reason은 이미 허용 목록의 taxonomy 키). telemetry 속성은 그대로다.
- 효과는 계속 MAYBE_APPLIED다. 재시도 판단에 쓰는 certainty는 건드리지
  않았다.

버린 대안
- 리뷰 문서 문구대로 terminalReason을 CLASSIFIER_FAILED로 바꾸기:
  terminalReason은 "sink로 나가지 않는 내부 라벨"(VD-07 5-1)이고, 문제
  응답에서는 certainty 값이 그대로 terminalReason이 되며 재시도 차단
  조건(certainty !== "MAYBE_APPLIED")에도 쓰인다. 값을 바꾸면 그 이중
  차단이 하나로 줄고, projector가 문자열을 걸러 내야 한다. 별도 닫힌
  타입 필드가 의도가 더 잘 보인다.
- 플래그와 주석 문장을 지우기(리뷰의 두 번째 안): 운영자가 "결과 불명"이
  분류기 결함 때문인지 구분할 수단이 계속 없다.

위험·한계
- classifyStatus(401·403·429) 분류기의 throw는 지금처럼 MAYBE_APPLIED만
  내고 reason을 남기지 않는다. 그 함수는 기록을 주장하지 않아 이번 범위에서
  뺐다.
- 공개 타입은 추가만 했다(관측 선택 필드 1개, 배럴 type export 1개).
- VD-07 5-1에 reason 전달 규칙을 적었다.

검증
- RED(수정 전): tests/integration/http-execution-v3-observability.test.ts
  "keeps MAYBE_APPLIED and records a failed problem classifier in
  diagnostics only (03-05)" 실패. 기대 reason "CLASSIFIER_FAILED", 실제
  undefined.
- GREEN: 같은 파일 7/7 통과. 변이 M5(catch를 NOT_APPLIED로)를 다시 넣으면
  이 테스트가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/integration tests/features/reference-feature
  tests/unit/http-execution-v3.test.ts 30 files / 302 tests 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 스크립트 필요).

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
DongHyeonka 49f7cde50e fix(platform): lifecycle 리스너 주인 규칙을 실제에 맞추고 테스트를 둔다 (05-03)
문제: browser-lifecycle.ts는 자신을 "창 lifecycle 리스너의 유일한
주인"이라 적고 어떤 capability도 visibilitychange·online·offline·focus·
pagehide·pageshow 리스너를 직접 달지 않는다고 약속한다.
optional-runtime-host.ts도 같은 말을 한다. 실제로는
- telemetry 수집기가 기본 구성에서 자기 pagehide 리스너를 단다
  (telemetry-collector.ts onPageExit).
- 네이티브 파일 선택기가 선택 창이 열린 동안 window focus 리스너를
  단다(browser-file-picker.ts, 리뷰가 세지 않은 두 번째 예외).
- lifecycle 런타임은 SW나 realtime이 있을 때만 만들어져 기본 구성에는
  없다.
또 createBrowserLifecycleRuntime을 직접 부르는 테스트가 없어 bfcache
복원 때 generation 증가(K3), dispose 때 리스너 해제(K4) 변이가
살아남았다.

고른 방법: 리뷰 권고 (a). 주석을 "런타임이 있을 때 capability는 여기에
구독한다"로 좁히고, 런타임이 생기는 조건과 알려진 예외 둘을 적는다.
tests/unit/browser-lifecycle.test.ts를 추가해 리스너 수, generation,
visibility·connectivity, 구독자 격리, beforeunload 부착·해제·prompt,
dispose 뒤 0개를 확인한다.

버린 대안:
- (b) telemetry를 lifecycle 런타임에 연결하고 기본 구성에서도 런타임을
  만든다: "기본 구성은 부작용 없는 생성" 원칙과 조립 순서를 함께 바꿔야
  해 이번 범위를 넘는다.
- (c) lint로 이벤트 이름을 막고 예외 파일을 적는다: 예외 목록 관리 비용에
  비해 지금 이득이 작다. 다운스트림이 lifecycle 런타임을 켤 때 다시 본다.

위험·한계: 규칙은 여전히 주석뿐이고 검사가 없다(주석에 그렇게 적었다).
src 동작은 바뀌지 않는다.

검증:
- RED(주석): 주석의 "single owner"와 telemetry-collector.ts의 pagehide,
  browser-file-picker.ts의 focus 리스너를 대조해 불일치 확인.
- RED(테스트 공백): 새 테스트는 현재 코드에서 5/5 통과하고, 변이 4개를
  모두 잡는다. K3(generation += 1 제거) → "expected {...} to match
  object { generation: 2 }", K4(dispose의 pagehide·pageshow 해제 제거) →
  "expected 2 to be +0", beforeunload 상시 부착 → "expected 1 to be +0",
  dirty 검사 제거 → preventDefault "to not be called".
- 회귀: browser-lifecycle, optional-runtime-host, runtime-adapters
  3파일 30/30 통과. tsc app·test 통과, eslint 통과,
  check-adapter-inventory PASS.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka 298201f3ee perf(features)!: 기능 실행부를 초기 청크에서 떼어 라우트 진입 때 적재한다 (15-01)
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.

고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
  계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
  contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
  계약, adapter contribution, contract contribution)는 feature-runtime.ts로
  옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
  route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
  모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
  화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
  모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
  적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
  registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
  (installed-contract-contributions.ts). 선언하지 않은 contract package를
  적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
  installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
  registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
  둔다. src에서 후자를 import하면 새 아키텍처 규칙
  boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
  route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
  청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
  기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
  플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
  템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
  feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
  render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
  애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).

버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
  lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
  버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
  공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
  -60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
  i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
  초기로 세어 218,303 B가 됐다.

위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
  실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
  그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
  테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
  구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
  재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
  비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
  총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
  installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
  때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
  98.8%다.

수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B

검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
  "adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
  equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
  tests/integration tests/contract tests/runtime-schema tests/architecture
  tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
  109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
  boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
  check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
  55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
  pnpm 경로의 check:bundle, test:system

BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
  loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
  (apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
  만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
  codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
  16-structure-patterns.md 9절
2026-11-01 21:57:53 +09:00
DongHyeonka ddf411e4e2 fix(bootstrap): ANONYMOUS 프로필 요청을 세션 상태와 상관없이 보낸다 (09-01)
조립 루트의 attachCredentials가 operation의 인증 프로필을 보지 않고
세션 상태만 본다. 그래서 auth: "none" operation(ANONYMOUS 프로필)이
로그아웃이면 UNAUTHENTICATED, 로그인이면 세션 헤더가 붙어
CREDENTIAL_HEADER_NOT_ALLOWED로 거절되고, 외부 owner가 없으면
CREDENTIAL_OWNER_UNAVAILABLE로 끝난다. 어느 상태에서도 fetch가 0회다.

scope 확인 바로 다음에 INSTALLED_REST_AUTH_PROFILES에서
operation.authProfileId의 transport를 읽고, ANONYMOUS면 세션을 보지
않고 빈 헤더로 READY를 돌려준다. executor에 넘기는 레지스트리와 같은
값을 같은 객체 안에서 읽는다. 그 밖의 프로필은 기존 경로 그대로다.

버린 대안:
- executor(http-execution-v3.ts)가 ANONYMOUS면 attachCredentials를
  부르지 않게 하기. adapter 공개 동작이 바뀐다. 지금 executor는 익명
  프로필에도 협력자를 부르고 헤더를 내면 거절하며, 이 동작을 고정한
  계약 테스트가 있다. 세션을 아는 쪽은 조립 루트라서 판단도 거기 둔다.
- 리뷰 R1(attachCredentials를 createCredentialAttacher로 꺼내기).
  구조 변경이라 이번 범위를 넘는다. 09-02에서 함께 다룬다. 새 테스트가
  실제 createRuntimeAdapters를 거치므로 그때도 그대로 쓸 수 있다.
- 새 케이스를 tests/unit/runtime-adapters.test.ts에 넣기. vi.mock은
  파일 단위라 설치된 계약 묶음을 바꾸면 그 파일의 기존 테스트에도
  번진다. 그래서 runtime-adapters-auth-profile.test.ts를 따로 만들었다.

위험·한계:
- 로그인 상태의 익명 호출에 토큰이 붙지 않고 owner에게도 가지 않는다.
  ANONYMOUS 프로필이 자격증명 헤더를 하나도 허용하지 않으니 의도한
  결과다. 인증 통합이 실패한 상태에서도 공개 읽기는 나간다.
- scope fence는 익명 분기보다 먼저 본다. 모르는 프로필 id는 executor가
  attachCredentials 전에 UNKNOWN_AUTH_PROFILE로 막는다.
- 브라우저 화면은 보지 않았다. test:sample-removal도 돌리지 않았다.
  새 테스트는 템플릿 소유 fixture와 src/contracts의 프로필만 쓴다.
- tech-log 제품 쪽 우회는 다음 동기화 때 지운다.

검증:
- RED(수정 전): 새 테스트 11건 중 5건 실패. ANONYMOUS 4개 상태가
  expected 'UNAUTHENTICATED' to be 'SUCCESS'(demo 로그아웃),
  expected 'AUTH_INTEGRATION_FAILURE' to be 'SUCCESS'(demo 로그인,
  외부 owner 로그인, owner 없음)로 실패. owner의 attachCredential이
  1회 불림. 인증 필요 프로필의 UNAUTHENTICATED, CREDENTIAL_OWNER_
  UNAVAILABLE 2건, fence 중 ABORTED_BY_SCOPE, 로그인 후 bearer 전송,
  익명 요청의 SCOPE_FENCED 6건은 수정 전후 모두 통과.
- GREEN: 새 테스트 11/11 통과.
- 회귀: runtime-adapters, http-execution-v3(unit·integration),
  auth-recovery, legacy-http-credential-authority, tests/features,
  tests/component, 영역 R1 목록 71 files / 485 tests 통과.
- tsc(tsconfig.app.json, tsconfig.test.json) 오류 0. 바꾼 두 파일
  eslint 통과. check:architecture(pnpm 대신 exec 대행) 통과,
  376 modules.

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-01
2026-11-01 19:07:05 +09:00
donghyeon-kaandClaude Opus 5.5 e04d1d7a40 Merge fix/session-subject-required: require readSubject on the external session owner
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:32:40 +09:00
donghyeon-kaandClaude Opus 5.5 49413af045 fix(types): turn on noUnusedLocals and drop the unused declarations (12-12)
VD-01 decision 3 hands unused diagnostics to tsc and turns off ESLint's
no-unused-vars for TS files, but tsconfig.base.json never enabled the
tsc check (D-19). The flag found 46 unused imports, types and helpers
across 22 files; none of them were read, so removing them changes no
behaviour.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:32:33 +09:00
DongHyeonkaandClaude Opus 5.5 cd47516592 fix(bootstrap): report a Service Worker that did not start through telemetry (06-05)
An ACTIVE worker whose install failed left a trace only in health(), which
nothing reads. The optional host now emits service-worker.start.failed on the
application telemetry port, and the recipe doc lists what else to wire.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:54 +09:00
DongHyeonkaandClaude Opus 5.5 4c27a9cb0a Merge lane I: app core, feature assembly and build input fixes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:42:29 +09:00
DongHyeonkaandClaude Opus 5.5 fc8142b2b9 fix(bootstrap): offer a retry on boot failures a reload can fix (09-10)
A config or manifest request that failed or timed out left only an error code
on screen. The boot shell now explains and offers a "try again" button for
those codes; it never reloads on its own, so the reload-once rule holds.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:27:14 +09:00
DongHyeonkaandClaude Opus 5.5 b685b616e4 fix(bootstrap): report FEATURE_OVERRIDES keys the build does not declare (09-09)
A misspelt kill-switch key was ignored without a trace, so the feature kept
running. Boot now records feature.override.unknown once per such key, and
release admission lists them as warnings in its record without refusing the
artifact (a shared document may still name another build's features).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:25:24 +09:00
DongHyeonkaandClaude Opus 5.5 69e40f106f fix(bootstrap): report unexpected boot errors without a console call (09-04)
check:diagnostics refuses direct console use in src. The development report of
an unclassified boot error now goes through reportError, which still lands in
the browser console.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 23:25:24 +09:00
DongHyeonkaandClaude Opus 5.5 aca949042f fix(bootstrap): report unclassified boot failures as BOOT_UNEXPECTED_FAILURE (09-04)
Any error the loaders did not classify was shown as BOOT_CONFIG_FAILURE and
dropped. It now shows BOOT_UNEXPECTED_FAILURE with the build id and error class,
logs the original in development, and a schema failure lists the rejected key
names (bounded, never values).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:58:29 +09:00
DongHyeonkaandClaude Opus 5.5 9c8a5f417a fix(bootstrap): show the boot error shell when the app graph fails to evaluate (09-03)
A module that threw while evaluating stopped main.tsx before boot() ran, so the
static loading shell stayed up. The entry now imports the app (boot.tsx)
dynamically and renders the shell on rejection; the shell reads boot messages
without the feature catalog. The preload helper gets its own chunk so lazy
chunks do not import the per-build entry, and the bundle budget counts the
entry's dynamic imports as initial JS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:54:40 +09:00
DongHyeonkaandClaude Opus 5.5 f329cc8042 fix(telemetry): keep a never-sent unauthenticated request out of api.request.failed (03-07)
With no credential V3 sends nothing and returns UNAUTHENTICATED without a
status, yet it was counted as an API failure, so signed-out states raised
the failure rate. Diagnostics still record it once; telemetry does not.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:52:18 +09:00
DongHyeonkaandClaude Opus 5.5 43e47f4bbb fix(telemetry): stamp build_id and release_id on every collector event (13-11)
API failure telemetry had no build or release identity, so a failure rate
could not be split by release while old and new tabs coexist. The collector
now stamps both on every event of both ports from the release manifest.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:46:31 +09:00
DongHyeonkaandClaude Opus 5.5 c5da3cf001 fix(http): send a request id and carry the server correlation id to failures (03-03)
V3 read the response x-correlation-id and dropped it, and untraced requests
sent no id, so a support reference could not be matched to a server log.
Each logical execution now sends one x-correlation-id; failures carry the
echoed value as requestId and diagnostics record it as correlation_id.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:27:42 +09:00
DongHyeonkaandClaude Opus 5.5 bc7c46b2d5 fix(features): check declared needs and show the IndexedDB capability assembly (09-05)
A missing capability reached the feature factory as an anonymous TypeError.
The composer now names the feature and the capability, and the IndexedDB
provider example moves from a browser spec into an opt-in recipe with a test.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-25 22:14:11 +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 924ef3891c fix(bootstrap): keep unvalidated config values out of the safe boot error (Q-6.9-10)
On CONFIG_SCHEMA_INVALID the loader copied the raw RELEASE_ID and
CONFIG_SCHEMA_VERSION strings (up to the 64 KB body limit) into the
"safe" error that BootErrorShell and diagnostics show, contradicting the
file's own contract. The error now carries the schema version only when
it passed the version gate (no validator issue at CONFIG_SCHEMA_VERSION)
and never the release id of a rejected document.

Verified: two cases in tests/runtime-schema/runtime-config.test.ts
(invalid field with a 10 KB RELEASE_ID; unsupported 10 KB version) RED
before, green after; test:runtime-schema and all gates PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:58:35 +09:00
DongHyeonkaandClaude Opus 5.5 76de74a0fa fix(features): withhold feature inputs switched off by FEATURE_OVERRIDES (Q-6.9-5)
createRuntimeAdapters computed activeFeatureIds and then composed feature
inputs for every installed feature, so a feature disabled by the kill
switch still got its API from application.features.get(); only the
router honoured the switch. createInstalledFeatureInputs now takes the
active ids (optional; the default stays "every installed feature" for
callers without runtime config) and the runtime passes them.

Verified: tests/unit/runtime-adapters.test.ts — disabled feature has no
features.has/get (RED before: has() was true); every installed feature
still resolves when nothing is switched off. All gates pass except the
known tests/unit/removal-fixture.test.ts (artifacts/ absent).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:58:35 +09:00
DongHyeonkaandClaude Opus 5.5 a328776bf2 fix(telemetry): send both telemetry ports through one collector transport (Q-6.9-4)
The application port (best-effort-telemetry) and the feature port
(feature-telemetry pipeline) each posted to TELEMETRY_ENDPOINT on their
own: 20+20 sends per minute, cookies on the application side, no
pagehide flush or dispose abort on the feature side, and no deadline on
any fetch, so a hung collector held activeFlush forever (6.3-10).

New src/adapters/telemetry/telemetry-collector.ts is the one transport:
shared send-rate window (createTelemetrySendRate, now in the platform
pipeline and injectable via `sendRate`), credentials "omit", cache
"no-store", a per-request deadline through the kernel
createAbortableOperation, and one pagehide fan-out. runtime-adapters
builds one collector and passes it to both ports. Body projections are
unchanged and pinned by characterization tests first.

Verified: new tests in tests/unit/telemetry.test.ts (5 RED before
wiring: credentials/cache, hung collector timeout, shared rate,
feature pagehide flush, feature dispose abort); all gates pass except
the known tests/unit/removal-fixture.test.ts (artifacts/ absent);
check:adapter-inventory 137/137; FE-RB-004 drill PASS.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:58:35 +09:00
DongHyeonkaandClaude Opus 5.5 1b9e2c5ec6 fix(http): recover a V2 401 outside the retry budget and correct the rollback claim (Q-6.3-11)
The V2 client only attempted 401 session recovery while the physical
attempt count was under maxRetryAttempts + 1. With MAX_RETRY_ATTEMPTS=0,
or when a 503 retry had already used the budget, a recoverable 401 went
straight to onUnauthenticated() and logged the user out. Recovery is
already bounded to one replay by recoveryUsed and by the deadline, so
the budget check is removed.

The comments in runtime-adapters.ts and adapters/http/index.ts said V2
works as a rollback path for V3 once its four slots are injected. That
is wrong: V2 validates the {success,data,meta} envelope and V3 the bare
DTO, so the same backend fails every V2 response with
ENVELOPE_MISMATCH. The comments and the client.ts ledger row in
docs/reviews/adapters/01-network-and-state.md now say a rollback also
needs a V2-envelope server. No docs/architecture page made the claim.
V2 code is kept.

Verified: two new auth-recovery cases (retries disabled; 503 then 401)
failed RED with ok:false and now recover. All lane gates pass except
the known removal-fixture test; verify:documentation passes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:41:45 +09:00
DongHyeonkaandClaude Opus 5.5 63ce5f6486 fix(cross-context): report an inactive host and hash the release epoch (Q-6.2-9)
createBrowserCrossContextInvalidationFromHost returned undefined without any
diagnostic when the cache epoch was invalid or secure random was missing, and
bootstrap built the epoch as `release.${releaseId}`, so any release ID with
`+`, `/`, `@` or over the length limit silently turned cross-tab
invalidation off.

- The host factory now reports OPEN/FAILED/NONE with the new reasons
  INVALID_CACHE_EPOCH or SECURE_RANDOM_UNAVAILABLE before returning
  undefined (the zero-topic build still probes nothing and reports nothing).
- New crossContextCacheEpochForRelease() derives `release.<fnv1a-64 hex>`
  from the release ID; bootstrap uses it (one call-site change in
  src/bootstrap/runtime-adapters.ts).
- The observation reason union gains two members (additive); the ops runbook
  lists them.

Verified: two new unit tests failed before (no observation; missing epoch
helper) and pass now. Lane gates, reference-feature and V3 integration tests,
and check:diagnostics pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:39:59 +09:00
DongHyeonkaandClaude Opus 5.5 ec71b0b0a2 refactor(web-push): merge codec primitives into one module and inject the page document (Q-6.6-12)
web-push/codec-primitives.ts now owns OPAQUE_ID/validOpaqueId, isRecord,
hasExactKeys, exactRecord, validAuthority, base64UrlDecode and (to share the
alphabet) base64UrlEncode. push-codec,
push-registration-gateway, push-association-fence-store,
push-subscription-adapter and service-worker-runtime import them instead of
carrying their own copies (the fence store's control/association key checks
now use exactRecord/hasExactKeys with the same key lists). The duplicate-key
JSON scan in push-codec.ts is untouched (realtime lane, T76).

Where the copies differed, the stricter validated behavior is kept:
- validAuthority: the fence store's null guard. The gateway's copy threw a
  TypeError for a null authority, so register()/reconcile() rejected instead
  of returning INVALID_INPUT; they now return INVALID_INPUT (the only change a
  caller can observe; characterization test was RED before the merge).
  Non-record values (arrays) are also refused.
- base64UrlDecode: the gateway's decoder, which refuses a lone trailing
  character (length % 4 == 1). The window adapter's copy accepted it when the
  spare bits were zero; its only caller pre-checks an 87-char VAPID key, so
  that difference was not reachable. `>>` vs `>>>` gave identical bytes.
- OPAQUE_ID, isRecord/hasExactKeys/exactRecord were already identical.

Page controller: PageControllerDependencies gains optional `document`; the
6-hour update check reads it (falling back to the global document), and
bootstrap/register-service-worker.ts now passes host.document through.

New adapter file: INVENTORY.md row 126 + renumber, total 137/137; detail row in
docs/reviews/adapters/05-service-worker-and-web-push.md.

Verified: characterization tests pinned the caller-visible behavior of every
copy before the merge (spare-bit keys, VAPID key, null authority in fence
store and gateway, array/extra-key backend answers, opaque ids); all pass
after, plus direct base64UrlDecode tests and an encode round-trip against
Node's base64url for lengths 0..66. Document injection test was RED
(update() ran while the injected document was hidden), green after. Gates:
check:architecture, types app/test/service-worker, lint, test:unit (only
pre-existing removal-fixture failure), test:component,
check:realtime-boundaries, check:adapter-inventory.
Realtime reference bundle (check:optional-recipes:source, already over budget
at b953142): 40139 -> 40097 gzip bytes after T89+T90.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 13:37:56 +09:00
DongHyeonkaandClaude Opus 5.5 ddf74ed6e9 fix(presentation): keep preferences above the scope fence, dispose routers (R-8.3)
LocaleProvider and ThemeProvider lived inside AppRouter, below the
server-state scope fence (and below QueryClientProvider keyed by
generation). A session change (FENCED -> READY) unmounted and remounted
them, so their live state was thrown away and re-read from storage. The
browser router was created in useMemo and never disposed, so every
remount (and StrictMode's double useMemo) left a popstate listener behind.

- New presentation/providers/preference-providers.tsx: persisted
  LocaleProvider + ThemeProvider (the wiring T45 added to AppRouter).
- bootstrap/runtime-application.tsx: ApplicationProvider >
  PreferenceProviders > ServerStateGenerationProvider > AppRouter, so the
  fence only remounts session-scoped UI.
- AppRouter no longer mounts Locale/Theme. It creates the router in the
  effect that disposes it: a disposed router never listens to history
  again, so useMemo + cleanup would break back/forward under StrictMode's
  replayed mount.
- Tests that mount AppRouter directly now wrap it in PreferenceProviders
  (router, chunk-recovery-boundary, app-shell, product-feature-switch,
  locale-platform, reference-feature reference-page).

Verified: RED "keeps locale state across a session scope fence and
disposes routers" (RuntimeApplication, demo sign-in, storage cleared after
choosing en-US) came back in Korean before and passes after; with the
providers hoisted but no dispose it fails on popstate listeners (4 added,
0 removed). check:architecture, check:types:app, check:types:test, lint,
test:component, test:reference-feature pass; test:unit passes except the
pre-existing removal-fixture test (needs generated artifacts/ files absent
from a fresh worktree).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-24 12:39:51 +09:00