Commit Graph
837 Commits
Author SHA1 Message Date
DongHyeonka b9524cfdd5 test(storage): scope participant 조립 테스트가 제품 설정 기본값을 같이 받는다
문제
fix/r1103-storage가 더한 browser-file-session-capability·
runtime-adapters-product-scope-participants 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)의 제품 확장 타입 검사
테스트가 이 두 파일에서 TS2322로 실패한다(9b9d62a와 같은 원인).

고른 방법
- 두 테스트도 testRuntimeConfig로 설정을 만든다.

위험·한계
- 동작 변경은 없다.

검증
- tests/unit/product-extension-typecheck.test.ts, 두 테스트, test:recipes,
  lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 02-01
2026-11-04 21:50:30 +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 9b9d62ae8f test(recipes): 세션 owner 조립 테스트가 제품 설정 기본값을 같이 받는다
문제
fix/r1103-session의 session-owners-runtime 테스트는 RuntimeConfig를
글자 그대로 적는다. fix/r1103-app(09-02)은 템플릿 테스트가 제품 설정
키의 기본값을 받도록 testRuntimeConfig로 설정을 만들게 했고, 복사본에
제품 키를 넣은 뒤 tsc test 프로그램을 도는 테스트를 더했다. 두 브랜치를
합치자 그 테스트가 session-owners-runtime.test.ts:161에서 TS2322로
실패한다.

고른 방법
- 이 테스트도 tests/helpers/runtime-config.ts의 testRuntimeConfig로
  설정을 만든다. 다른 템플릿 테스트와 같은 방식이다.

위험·한계
- 동작 변경은 없다. 테스트 입력 모양만 바뀐다.

검증
- tests/unit/product-extension-typecheck.test.ts 통과.
- tests/recipes/session-owners-runtime.test.ts 통과, lint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02 09-03
2026-11-04 21:45:04 +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 d5e3bf2e2c chore(review): 1103 계약·레지스트리 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 07-01~07-04 13-04 14-06
2026-11-04 21:28:13 +09:00
DongHyeonka 4f78890576 fix(browser-files): 위험 확장자를 safe extension으로 쓰는 다운로드 정책을 거절한다
문제: download 정책 registry는 safeExtension의 형식만 본다. 파일명
금지 목록(.exe, .html, .js 등)은 사용자가 준 이름에만 쓴다
(1101/02-02). 그래서 mediaType application/pdf + safeExtension .exe
정책이 조립되고, invoice.pdf가 invoice.exe로 browser handoff된다
(리뷰 E-7).

고른 방법: snapshotDownload가 금지 목록에 있거나 그것으로 끝나는
(.tar.js) safeExtension을 다른 정책 오류와 같이 TypeError로 거절한다.
목록은 file-policy.ts의 DEFAULT_FORBIDDEN_EXTENSIONS 하나를 쓰고,
isForbiddenDownloadExtension으로 내보낸다. browser-managed capability는
정책과 같은 safeExtension이어야 하므로 그 경로도 함께 막힌다.
버린 대안: media type과 확장자 짝 표를 두는 것. 표를 누가 소유할지
정해야 하고 범위가 크다. 이번에는 하지 않았다.

위험·한계: 이 확장자를 쓰던 다운스트림 정책은 조립 때 실패한다(보안
강화 방향). media type과 확장자가 서로 맞는지는 여전히 보지 않는다
(설계 문서에 적었다). file-transfer 번들 56,068 → 56,100 / 57,800 gzip B.

검증:
- RED: browser-file-policy-registry.test.ts 새 3건(.exe, .HTML, .tar.js)이
  throw 없음으로 실패.
- GREEN: browser-files 단위 5파일 + tests/recipes 98건 통과.
  check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-02
2026-11-04 21:18:51 +09:00
DongHyeonka b029dcc00a chore(review): 1103 앱 코어·폼 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 09-01 09-02 09-05 09-07~09-10 08-02~08-04
2026-11-04 21:17:43 +09:00
DongHyeonka 3f72ae7df9 docs(architecture): adapter kernel 설명을 실제 platform 폴더 내용에 맞춘다
문제: layers.md와 .dependency-cruiser.json 규칙 주석은 kernel
(src/adapters/platform/**)을 "clock, abort primitive, capacity guard"로만
적는다(0929/05-08). 실제 폴더에는 IndexedDB 연결·트랜잭션, Retry-After,
JSON member scanner와 bootstrap만 쓰는 lifecycle runtime·mutation intent
factory까지 10개 파일이 있다. 편입 기준("must never own")은
indexeddb-connection.ts 머리 주석에만 있어, 폴더에 무엇을 넣어도 되는지
문서로는 알 수 없다.

고른 방법: 리뷰 5.3절 (b). 두 곳의 설명을 실제 목록으로 고치고, 공유
메커니즘과 bootstrap 전용 서비스를 나눠 적고, 기준이 있는 위치를
가리킨다. 파일을 옮기는 (c)·(d)는 하지 않았다(1101/05-04, 남음).

위험·한계: 문서와 규칙 주석만 바꾼다. 규칙 동작은 같다. 폴더에 무엇을
넣을지를 기계가 보지 않는 것은 그대로다.

검증: check:architecture, verify:documentation 통과. bootstrap 밖에서
lifecycle·mutation intent factory를 쓰는 곳이 없음을 grep으로 확인했다.

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

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

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

검증: verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-04
2026-11-04 21:02:15 +09:00
DongHyeonka 3bfe6a8580 test(cache-storage): 조회가 eviction 판정 전에 캐시 목록을 다시 읽는지 고정한다
문제: 조회는 cache 이름 목록을 pointer보다 먼저 읽는다. 그 사이 다른
탭의 activation이 pointer를 새 캐시로 옮기면 목록에 그 캐시가 없다.
코드는 목록을 한 번 더 읽고서야 STORAGE_EVICTED를 낸다
(1101/02-04 ⑤, N39). 이 재확인을 지워도 테스트가 모두 통과했다. 빠지면
방금 배포한 release의 첫 조회가 "지워졌다"로 끝나고 REHYDRATE로 간다.

고른 방법: 첫 keys()만 배포 전 목록을 돌려주는 저장소로 r2 활성화 뒤
조회한다. adapter는 만들 때 keys를 잡아 두므로 저장소 하위 클래스로
한 번만 낡은 답을 준다.

위험·한계: 테스트만 바꾼다. 1101/02-04의 N38(host storageArea 비교)은
pulse wire 값을 만드는 하네스가 필요해 이번에 하지 않았다.

검증: N39 변이를 넣으면 이 테스트가 STORAGE_EVICTED로 실패하고(cache
단위 3파일 + tests/recipes 71건 중 1건), 되돌리면 같은 파일 14건 통과.
check:types:test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
2026-11-04 21:01:49 +09:00
DongHyeonka de2670cda5 test(cache-storage): no-cache와 Set-Cookie 응답 거절을 따로 고정한다
문제: 1101/02-04의 두 변이가 이번에도 cache 단위 테스트를 모두
통과했다. N26b는 Cache-Control: no-cache 거절, N26은 Set-Cookie 응답
거절을 지운다. 둘 다 빠지면 사용자별이거나 재검증이 필요한 응답이 익명
공용 캐시에 들어간다. 기존 표는 no-store·pragma·www-authenticate만 따로
보았다.

고른 방법: 응답 검증 표("keeps response validation failure codes")에 두
행을 더한다. 각 행은 규칙 하나만 어긴다.

위험·한계: 테스트만 바꾼다.

검증: 두 변이를 하나씩 넣고 cache 단위 3파일 + tests/recipes를 돌렸다.
둘 다 이 테스트가 실패했고 되돌린 뒤 통과. eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 1101/02-04
2026-11-04 21:00:22 +09:00
DongHyeonka 0a74bd42b0 test(browser-files): handoff 실패 lease 반환과 남은 보호 규칙 3개를 고정한다
문제: 이번 리뷰에서도 아래 browser-files 변이가 관련 unit 파일을 모두
통과했다.
- M10(0929/02-05): bounded download의 catch에서 lease?.release()를 지운다.
  handoff가 던지면 만든 blob URL이 runtime dispose까지 남는다.
- N27(1101/02-04 ③): 같은 파일을 다시 inspect할 때 이전 receipt를
  무효화하지 않는다. 다른 정책으로 검사한 옛 receipt로 preview가 열린다.
- N29(1101/02-04 ①): object URL lease의 합계 바이트 상한을 지운다. 기존
  테스트는 개수 상한이 먼저 막아 바이트 상한을 보지 못했다.
- N30(1101/02-04 ⑥): browser-managed handoff의 fragment 거절을 지운다.

고른 방법: 규칙마다 실패하는 테스트 하나. N29는 개수 여유가 있을 때도
바이트가 막는 경우를 기존 상한 테스트 끝에 더했고, N30은 target 규칙
표에 fragment href 한 줄을 더했다.

위험·한계: 테스트만 바꾼다. 1101/02-04의 나머지(N26·N26b는 다음 커밋,
N38 host storageArea, N39 조회 keys() 재확인)는 이 커밋에 없다.

검증: 네 변이를 하나씩 넣고 browser-files 단위 5파일 + tests/recipes를
돌렸다. 모두 새 테스트(또는 늘린 행)가 실패했고 되돌린 뒤 통과. 원래
코드에서 두 파일 47건 통과. check:types:test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/02-adapters-browser-files-cache.md 0929/02-05, 1101/02-04
2026-11-04 20:59:25 +09:00
DongHyeonka b5c7128bda test(storage): Web Storage의 Firefox quota 이름과 만료 경계를 고정한다
문제: 2026-11-01 05-06에서 남은 두 분기를 테스트가 잡지 못한다. 이번
리뷰에서도 두 변이가 Web Storage 관련 테스트 3파일 49건을 통과했다.
- W4: quota 판정 목록에서 Firefox의 NS_ERROR_DOM_QUOTA_REACHED를 빼도
  테스트가 통과한다. 빠지면 Firefox의 quota 실패가 memory fallback 없이
  STORAGE_UNAVAILABLE이 된다.
- W8: 만료 비교 `<=`를 `<`로 바꿔도 통과한다. 만료 시각과 같은 순간에
  값을 돌려준다.

고른 방법: 각 분기에 실패하는 테스트 하나씩. 저장소 test double에
Firefox 이름으로 던지는 모드를 더했고, 만료 경계는 expiresAt 100·101을
now 100에서 읽는다.

위험·한계: 테스트만 바꾼다. codec을 직접 부르는 테스트는 여전히 없다.

검증: W4·W8 변이를 하나씩 넣고 storage-registry·runtime-adapters·
browser-storage-policy 테스트를 돌렸다. 둘 다 새 테스트가 실패했고,
원래 코드에서 storage-registry 26건 통과. check:types:test, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 1101/05-06
2026-11-04 20:57:19 +09:00
DongHyeonka 2f6df14f4b test(features): 제품 확장 typecheck 픽스처가 샘플 제거 뒤에도 통과한다 (1103/09-02)
문제
test:sample-removal은 참조 기능을 지운 복사본에서 test:unit을 돈다. 그때
product-extension-typecheck 픽스처 기능이 유일한 기능이 되는데, 메시지
catalog가 비어 있어(messages: {}) 메시지 키 타입이 무너져 tsc app이 presentation
파일 수십 곳에서 실패했다. 템플릿 결함이 아니라 픽스처 기능의 모양 문제다.

고른 방법
픽스처 기능에 두 locale의 메시지를 준다. two-feature-install-typecheck 픽스처와
같은 모양이다.

위험·한계
없다고 보는 이유: 테스트 픽스처 문자열만 바뀐다.

검증
- product-extension-typecheck.test.ts 통과(전체 repo).
- test:sample-removal 재실행 결과는 브랜치 보고에 적는다.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
2026-11-04 20:56:34 +09:00
DongHyeonka f6b74ed496 fix(storage): put idle 상한이 lock 대기 상한보다 짧지 않은 OPFS 정책을 거절한다
문제: putIdleTimeoutMs < mutationLockWaitTimeoutMs는 05-07이 기대는
관계다(멈춘 put이 idle 상한에서 origin lock을 놓아야 줄 선 writer가
대기 상한 전에 돈다). 이 관계가 opfs-policy.ts 주석에만 있고, 정책
검사는 각 값의 범위만 본다. 두 값을 뒤집은 정책은 조용히 통과하고,
멈춘 put 하나가 다른 탭의 모든 쓰기를 BLOCKED로 끝낸다.

고른 방법: assertOpfsRuntimePolicy가 putIdleTimeoutMs >=
mutationLockWaitTimeoutMs를 TypeError로 거절한다. 다른 정책 오류와
같은 자리·같은 방식이다. 기본값(2분 < 10분)과 repo 안의 모든 정책은
이미 관계를 지킨다.

위험·한계: 이 관계를 어긴 정책을 쓰던 다운스트림은 조립 때 실패한다.
의도한 동작이다.

검증:
- RED: opfs-worker-runtime.test.ts 새 2건(같음, 김)이 throw 없음으로 실패.
- GREEN: OPFS 단위 3파일 + tests/recipes + tests/contract 174건 통과.
  check:types, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 0929/05-09
2026-11-04 20:56:03 +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 f3fd10f17c docs(manual): 짝 백엔드에 처음 붙이기 절을 더한다
문제: 제품이 짝 백엔드에 처음 붙을 때 볼 문서가 없다. owner 작성자는
SessionGateway 주석, subject·scope fence 규칙, R-3.2, recover 규약을
여러 파일에서 모아야 하고, 백엔드가 무엇을 주고 무엇을 안 주는지(realm의
브라우저 client, 로그인·로그아웃·세션 엔드포인트)는 백엔드 코드를 읽어야
안다.

고른 방법: docs/manual/04-paired-backend-session.md를 새로 둔다.
- 두 모드 비교표와 근거 위치(백엔드 bbe944bd의 SecurityConfig,
  security.yml, application-local.yml, realm JSON).
- 공통 준비: AUTH_MODE external, 백엔드 local CORS 출처
  http://localhost:3000에 맞춘 dev 포트, owner context 필드, recipe는
  복사(import 금지).
- jwt: 흐름도, realm에 더할 public client JSON(audience mapper 포함),
  제품 설정 키 OIDC_ISSUER·OIDC_CLIENT_ID, product-composition 예시,
  하지 않는 것(새로고침 로그아웃, ID token 서명, id_token_hint).
- redis-session: 흐름도, 제품이 더할 엔드포인트 셋과 CSRF 토큰 읽기,
  프로필을 product-contracts.ts에 옮겨 적는 이유, 예시, 같은 host 조건.
- 상태 전이 표, 확인 방법(실제 백엔드 e2e는 아직 없음), 증상별 원인.
매뉴얼 README·02 §5, starter-experience·foundation·optional-adapter-
recipes에는 위치만 가리키는 줄을 더했다. 백엔드 표는 복사하지 않고 위치만
적었다(매뉴얼 README 규칙).

위험·한계: 백엔드 설정이 바뀌면 이 문서가 낡는다. 기준 커밋을 문서
첫머리에 적었다. Keycloak client JSON은 실제 Keycloak에 넣어 보지 않았다.

검증: verify:documentation PASS_SCOPED(새 문서와 고친 문서 모두 경로·
명령·게이트 ID 누락 0).

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:51:51 +09:00
DongHyeonka 05958bbdb6 feat(recipes): 짝 백엔드 두 인증 모드의 세션 owner recipe를 더한다
문제: AUTH_MODE external은 제품이 owner 8개 메서드를 직접 써야 하는데,
짝 백엔드(JWT·Keycloak 또는 Redis session)에 맞는 owner가 src·recipes
어디에도 없다. 쿠키 owner 모양은 테스트 파일 안 스케치뿐이다. 그래서
제품마다 첫 연동 전에 토큰 획득·갱신·subject·상태 전이·401 처리를
처음부터 쓴다.

짝 백엔드(bbe944bd)에서 확인한 계약:
- jwt 모드(기본): OAuth2 resource server. iss = APP_SECURITY_JWT_ISSUER
  (local http://localhost:8081/realms/ca-skeleton), aud 필수. CSRF·세션
  없음. 그러나 realm에는 서비스용 confidential client(ca-skeleton-api,
  standard flow 꺼짐)만 있고 브라우저용 public client가 없다.
- redis-session 모드: CA_SESSION httpOnly 쿠키, CookieCsrfTokenRepository
  (XSRF-TOKEN 쿠키, X-XSRF-TOKEN 헤더, plain handler). 로그인·로그아웃·
  세션 조회·CSRF 발급 엔드포인트는 운영 코드에 없다(테스트 픽스처만).

고른 방법: recipes/session-owners/에 둘을 둔다. 제품은 src/bootstrap/로
복사해 composeProductSessionOwner에서 돌려준다.
- oidc-pkce-session-owner.ts: authorization code + PKCE S256, WebCrypto와
  context fetch만 쓴다(라이브러리 없음). 토큰은 메모리에만, sessionStorage
  에는 10분짜리 거래(verifier·state·nonce·returnTo)만 두고 콜백이 먼저
  지운다. 콜백 URL에서 code를 네트워크 호출 전에 지운다. state·RFC 9207
  iss·nonce·aud·azp·exp·sub를 검사하고, 갱신 때 sub가 바뀌면 로그아웃.
  bearer는 apiOrigins에만 보낸다. 만료 30초 전 갱신은 한 번만 하고 상태
  알림이 없다. 401이면 refresh token으로 한 번 복구하고, 그 토큰도 401이면
  로그아웃. 설정이 틀리면 integration-failed로 닫는다.
- cookie-session-owner.ts: 세션 조회·로그아웃 URL과 로그인 시작을 기본값
  없이 받는다(백엔드에 없는 엔드포인트를 지어내지 않는다). 200+subject →
  authenticated, 401 → unauthenticated, 그 밖은 reject(상태 유지).
  SESSION_COOKIE_READ/WRITE 프로필과 XSRF-TOKEN → x-xsrf-token provider.
  쿠키가 없으면 쓰기는 UNAVAILABLE로 아무것도 보내지 않는다.
- 두 owner 모두 SessionState·recover 전이 계약을 따른다.
- PRODUCTION_IMPORTS_RECIPE 검사를 recipes/session-owners에도 건다.
  recipe는 복사하지 import하지 않는다(초기 번들 밖).
버린 대안: src에 기본 owner 내장(IdP 결합이 템플릿 본체에 들어간다),
OIDC 라이브러리 의존(fetch·WebCrypto로 충분), 매뉴얼만(같은 실수 반복).

위험·한계: 실제 Keycloak·Redis session 백엔드에 붙여 보지 않았다. ID
token 서명은 검사하지 않는다(토큰 엔드포인트 직접 응답, OIDC Core
3.1.3.7 (6)); access token 서명은 백엔드가 본다. 새로고침하면 메모리
토큰이 사라져 다시 로그인한다(Keycloak SSO면 비밀번호 없이 돌아온다).
쿠키 모드는 페이지와 API가 같은 host여야 XSRF-TOKEN을 읽는다.

검증: tests/recipes 3파일 52건(구현 전 모듈 없음으로 실패 확인).
변이 15개(state·origin·401 한 번·nonce·iss·URL 정리·갱신 sub·TTL,
CSRF 헤더·401·로그아웃 실패·notify·단일 조회·subject 상한·credentials)
모두 실패로 잡힘. runtime 조립 테스트 4건이 실제 createRuntimeAdapters로
EXTERNAL_BEARER bearer, 401 뒤 갱신, 쿠키 쓰기의 x-xsrf-token을 확인.
check:optional-recipe-fixtures(regex 변경 없이는 실패 확인),
check:optional-recipes:source, check:types, eslint 통과. 두 recipe의
minify+gzip 크기 3.8 kB, 1.1 kB.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-03
2026-11-04 20:47:24 +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 36ff633794 fix(recipes): OPFS fake가 FILES_READY에서 멈춘 put을 runtime처럼 commit한다
문제: recipe fake MemoryDurableObjectStore의 reconcile은 멈춘 put 행을
모두 rollback으로 센다. runtime은 FILES_READY 행을 다시 검증한 뒤
commit하고 finalize한다(runbook, 설계 문서의 roll-forward). recipe 테스트
주석은 "Like the runtime, reconcile rolls a stopped put back"이라고 적는다.
이 fake로 쓴 다운스트림 테스트는 "멈춘 업로드는 reconcile 뒤 사라진다"를
통과하지만 실제로는 객체가 다시 생긴다. fake의 LOGOUT·ACCOUNT_DELETION도
멈춘 행을 보지 않아 05-01을 fake 테스트로 찾을 수 없었다.

고른 방법: fake가 멈춘 단계를 기억한다. FILES_READY까지 간 행은 commit될
객체를 함께 둔다. reconcile은 그 행을 runtime과 같은 generation 검사로
commit하고(committedTransactions), PREPARING 행은 rollback한다.
LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지우고, 그런 행이 있었으면 runtime처럼
chunkSweep 대신 partitionDeleted를 보고한다. 같은 네 시나리오(두 단계 ×
reconcile 전 계정 삭제 여부)를 메모리 OPFS·IndexedDB 위의 실제 runtime과
fake에 돌려 결과가 같은지 보는 parity 테스트를 tests/recipes에 더했다.
unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로
parity 테스트는 recipe 쪽에 두었다(앞 커밋이 메모리 OPFS를 helper로
옮긴 이유).

위험·한계: 이 fake를 쓰는 다운스트림 테스트 중 FILES_READY 멈춤 뒤
rollback을 기대하던 것은 기대값이 바뀐다. 기존 recipe 테스트는 같은
흐름을 유지하려고 PREPARING 멈춤으로 바꿨다. fake는 runtime의 재검증
실패(digest 불일치) 경로는 흉내 내지 않는다.

검증:
- RED: parity 테스트 4건 중 3건 실패(fake가 FILES_READY를 rollback,
  계정 삭제가 partitionDeleted 없이 COMPLETED). runtime 쪽 기대값은
  처음부터 통과.
- GREEN: tests/recipes 24건 통과. check:types, 바꾼 파일 eslint,
  check:optional-recipes:source PASS.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04
2026-11-04 20:46:30 +09:00
DongHyeonka 2d5d41f85d fix(forms): 필드 오류가 아닌 저장 실패 뒤 키보드 포커스를 실패 상태로 옮긴다 (1103/08-02)
문제
참조 폼 페이지는 저장 중과 결과 불명 동안 저장 버튼에 disabled를 준다.
포커스가 있던 버튼이 꺼지면 브라우저가 포커스를 body로 내려놓는다. 폼은 필드
오류일 때만 포커스를 옮겼으므로, 키보드로 저장했다가 결과 불명(500)이나 429를
받으면 세 엔진 모두 포커스가 body로 떨어졌다. 복구 버튼은 폼 위 feedback
자리에 있어 셸 머리말부터 다시 지나야 닿았다.

고른 방법
- useAppForm이 feedbackId를 내고, 필드 오류·성공이 아닌 결과(결과 불명,
  재인증, 권한 없음, 다시 시도, 사용 불가, 충돌)로 끝나면 렌더 뒤 그 요소에
  포커스를 준다. FormPage(StandardPage)는 feedbackId를 받으면 feedback 자리를
  id + tabIndex=-1인 포커스 대상으로 만든다. 페이지마다 포커스 코드를 복사하지
  않게 하려고 hook과 템플릿에 두었다.
- 참조 폼의 저장 버튼은 저장 중에 disabled 대신 Button의 pending(aria-busy)을
  쓴다. 중복 제출은 지금처럼 폼(submitForm)과 onSubmit 가드가 막는다. 결과
  불명 동안에는 여전히 꺼진다(08-01 범위). 그때는 위의 포커스 이동이 받는다.
- 첫 행동 버튼 대신 feedback 자리 전체를 포커스한 이유: 실패 종류마다 버튼
  구성이 다르고, Tab 한 번에 첫 복구 버튼에 닿는다.
매뉴얼 02 6절 FormPage에 feedbackId와 pending을 적었다.

위험·한계
- 스크린 리더가 포커스된 feedback 자리를 어떻게 읽는지는 확인하지 않았다.
- 파생 폼 페이지는 feedbackId를 넘겨야 이 동작을 얻는다.
- "deduplicates create" 테스트의 저장 중 단언을 disabled에서 aria-busy와
  포커스 유지로 바꿨다. 한 번만 호출되는 단언은 그대로다.

검증
- RED: reference-page.test.tsx 새 2행(결과 불명, 429)이 수정 전 실패. e2e
  reference-save.spec.ts 새 2건이 수정 전 소스에서 chromium·firefox·webkit
  6건 모두 실패(feedback 자리 focused 아님).
- 수정 후 reference-save·reference-form e2e 3엔진 45건 통과(heavy lock,
  CHOKIDAR_USEPOLLING=1). tests/component·tests/features 60 files / 368
  tests 통과. check:types, eslint, check:design-system, check:i18n,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/08-presentation.md 08-02
2026-11-04 20:42:32 +09:00
DongHyeonka 8da33a5cf0 test(storage): 메모리 OPFS 파일 시스템을 테스트 helper로 옮긴다
문제: OPFS worker runtime을 메모리에서 돌리는 MemoryDirectory·MemoryFile이
tests/unit/opfs-worker-runtime.test.ts 안에만 있다. 05-04를 고치려면
recipe fake와 runtime에 같은 시나리오를 돌리는 parity 테스트가
tests/recipes에 필요한데, 그 테스트는 이 파일 시스템을 쓸 수 없다.
unit 테스트가 recipe를 import하면 optional-recipe 제거 드릴이 깨지므로
parity 테스트를 unit 쪽에 둘 수도 없다.

고른 방법: 그 블록(MemoryNode·MemoryFile·MemoryDirectory·fileHandle·
notFound)을 그대로 tests/helpers/memory-opfs.ts로 옮기고 export한다.
memory-indexeddb.ts와 같은 자리다. 코드는 바꾸지 않았다. helper는 src를
import하지 않아 browser-file-storage 제거 드릴에서도 남아도 된다.

위험·한계: 동작 변경 없음.

검증: opfs-worker-runtime.test.ts 82건 통과. check:types:test, 바꾼 파일
eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-04
2026-11-04 20:40:25 +09:00
DongHyeonka 4f19cd9e8b test(service-worker): 살아남던 워커 보호 장치 변이 4건을 테스트로 잡는다
문제
워커 보호 장치 넷은 지워도 테스트가 모두 통과한다(1101/06-04, 이번
리뷰에서 다시 생존). install fetch의 credentials: "omit"·redirect:
"error"(M1), activate nonce 한 번만 쓰기(M3), 요청받지 않은 client의
CLIENT_DRAINED 거절(M9), 첫 설치를 "업데이트 대기"로 알리지 않기(N8).

고른 방법
- service-worker-runtime.test.ts에 테스트 3건을 더한다.
  - install이 자산마다 cache no-store, credentials omit, redirect error로
    요청한다(M1).
  - 같은 nonce의 두 번째 ACTIVATE_REQUEST는 REJECTED, 요청받지 않은
    client의 drain 응답은 세지 않는다(M3, M9).
  - active 워커가 없는 첫 설치는 onUpdateWaiting을 부르지 않는다(N8).
- 동작은 바꾸지 않는다.

위험·한계
- N8 테스트는 시작 뒤 registration.active를 null로 바꿔 첫 설치를
  흉내 낸다. 실제 브라우저 첫 설치 순서는 e2e가 본다.

검증
- service-worker-runtime 64건 통과.
- 변이 4건(M1·M3·M9·N8)을 하나씩 넣어 각각 1건 실패를 확인하고
  되돌렸다.
- 바꾼 파일 eslint, check:types:test 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 1101/06-04
2026-11-04 20:40:11 +09:00
DongHyeonka fd6b6315c0 fix(storage): 소속 partition이 없는 손상 journal 행을 따로 세고 경보에서 뺀다
문제: partition 삭제는 journal 행을 LOGICAL_KEY_INDEX로 찾는다. 인덱스에는
logicalKey 값이 있는 행만 들어가므로, 그 값까지 깨진 행은 승인된
ACCOUNT_DELETION으로도 지워지지 않는다(X4: partition 파일 0개인데 행은
남음). 그 행은 reconcile마다 corruptTransactions 1, OBJECT_RECONCILE
DEGRADED/CORRUPT_DATA로 남는다. runbook은 "키로 찾으므로 손상 row도
지워진다", "partition이 승인된 purge로 지워질 때만 함께 지워진다"고 적고
수동 삭제를 금지한다. 운영자는 늘 켜진 경보를 받지만 할 수 있는 일이 없고,
그 경보가 진짜 손상을 가린다.

고른 방법(리뷰 (a)+(b)): 소속을 모르는 행은 지울 근거가 없으므로 지우지
않는다. 대신
- journal의 listIncomplete가 손상 행 가운데 이 authority의 partition 키
  범위에 들지 않는 행을 unattributedRows로 따로 센다(0이면 칸 없음).
- reconcile report에 unattributedCorruptTransactions를 싣고(0이면 칸
  없음), DEGRADED 관측은 purge가 지울 수 있는 손상 행이 있을 때만 낸다.
- runbook §0·§7 문장을 코드와 맞추고, 이런 행에 대해 할 일(같은 수면
  없음, 늘면 writer를 찾음, 수동 삭제 금지)을 적었다.
버린 대안: (a)만 — 경보가 계속 켜진다. (c) 소속을 모르는 행 자동 삭제 —
그 행이 가리키던 staging을 추적할 근거가 사라진다(runbook §0 3번).

위험·한계: 공개 타입에 선택 칸 두 개가 는다(OpfsJournalPage
.unattributedRows, OpfsReconciliationReport
.unattributedCorruptTransactions). 직접 만든 journal이 칸을 채우지 않으면
지금처럼 모든 손상 행이 경보에 남는다. 소속 없는 행만 있을 때 관측이
SUCCEEDED가 되므로, 그 수는 report로만 보인다. 이런 행의 staging은 purge의
partition 삭제 조건(countPartitionTransactions)에 잡히지 않는다.
offline-indexeddb 번들 37,555 → 37,705 / 38,500 gzip B.

검증:
- RED: indexeddb-opfs-journal.test.ts 새 테스트가 unattributedRows 없음,
  opfs-worker-runtime.test.ts 새 X4 테스트가 unattributedCorruptTransactions
  없음으로 실패.
- GREEN: 키 있는 손상 행은 removePartition이 지우고 키 없는 행은 남는다.
  키 없는 행만 있으면 관측 SUCCEEDED, 키 있는 손상 행이 더해지면
  DEGRADED:CORRUPT_DATA. OPFS 단위 3파일 + optional-runtime-host +
  tests/recipes + tests/contract 176건 통과. check:types, 바꾼 파일
  eslint, check:optional-recipes:source PASS, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-03
2026-11-04 20:38:17 +09:00
DongHyeonka c99b7a7f63 docs(contracts): 두 오류 어휘와 commandRecovery를 누가 읽는지 타입 옆에 적는다
문제
- AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason
  kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과
  action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry)
  설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05).
- CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지
  않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만
  있다(1101/07-07).
- 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에
  없다.

고른 방법
주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다
재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고,
화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지
않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행.

버린 대안
- retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는
  비용에 비해 얻는 것이 작다.

위험·한계
- 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금
  상태다.

검증
- grep: src/presentation·bootstrap·features·application에서
  AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요
  화면뿐.
- eslint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07
2026-11-04 20:38:14 +09:00
DongHyeonka 64f19ac665 fix(architecture): zod 하위 경로 import도 src/contracts/zod.ts를 거치게 한다
문제
zod-is-reached-through-contracts-zod 규칙의 to.path가 ^zod$다. src 파일이
"zod/v4"를 import하면 check:architecture가 rc=0으로 통과한다(실험 Z1). 그
모듈은 src/contracts/zod.ts의 jitless 설정보다 먼저 스키마를 만들 수 있고,
그러면 운영 CSP가 zod의 Function 탐침을 부팅마다 보고한다(F-7).

고른 방법
to.path를 ^zod(/|$)로 넓힌다. 그래프 fixture에 "zod/v4"를 import하는 파일과
그것이 거절되는지 보는 회귀 검사를 더했다. layers.md 규칙 표도 고쳤다.

버린 대안
- eslint no-restricted-imports에 zod 패턴 추가: 같은 규칙을 두 도구에
  둔다. 경계 규칙은 dependency-cruiser가 정본이다.

위험·한계
- src 안에 zod 하위 경로 import는 지금 없다(grep). 다운스트림이 쓰고
  있으면 check:architecture가 실패한다. src/contracts/zod.ts의 z로 바꾼다.

검증
- 수정 뒤: 참조 기능 스키마 파일 import를 "zod/v4"로 바꾸면
  "Architecture violation [zod-is-reached-through-contracts-zod]: ... ->
  zod/v4"로 실패, "zod"도 실패.
- 규칙을 ^zod$로 되돌리면 새 회귀 검사 "zod subpath import outside
  src/contracts/zod.ts is rejected"가 실패한다.
- check:architecture(29 regression checks PASS), check:types, eslint,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-06
2026-11-04 20:38:14 +09:00
DongHyeonka 84d6e526a3 fix(registries): 계약 조립 실패의 reason을 적고 읽지 못한 레지스트리를 지운 것으로 세지 않는다
문제
기능 계약 조립이 실패하면(예: 없는 authProfileId) check:registries 출력은
"missing registry source src/features/loaded-feature-runtimes.ts: Installed
contract contribution is not composable" 두 줄, "FE-REG-API is not an
object registry", "FE-REG-ROUTE references unknown registry FE-REG-SCHEMA",
"breaking change missing evidence: FE-REG-API:*:*:removed" 등이다. 원인은
ContractContributionError.reason에 있는데 검사기는 message 첫 줄만 적는다.
끝의 removed 줄은 "breaking 증거를 더하라"로 읽혀 틀린 다음 행동을
제안한다(실험 E-9).

고른 방법
- source를 읽다 난 오류에 문자열 reason이 있으면 "(reason: ...)"로 함께
  적는다.
- 읽지 못한 레지스트리는 따로 모은다. 그 레지스트리에 대해서는 행 검사
  ("is not an object registry"), 그것을 가리키는 참조 검사, 기준선 비교
  (removed 증거 요구)를 하지 않는다. 같은 실패를 다른 이름으로 다시 적지
  않기 위해서다. 게이트는 load 실패 한 줄로 그대로 실패한다.
- errors.md 레지스트리 표에 이 메시지 행을 더했다.

버린 대안
- 메시지 접두어를 "failed to load"로 바꾸기: 의미는 더 맞지만 기존 테스트와
  CI 진단 기대값이 "missing registry source"를 쓴다. 이번에는 바꾸지 않았다.

위험·한계
- source 파일을 실수로 지운 경우에도 removed 증거 요구를 건너뛴다. 그래도
  "missing registry source" 실패로 게이트는 막힌다. 레지스트리를 의도해서
  지우면 governance에서도 빠지므로 removed 증거 요구는 그대로다.
- FE-REG-API와 FE-REG-SCHEMA가 같은 source라 load 실패 줄은 두 번 나온다.

검증
- RED: registry-governance에 임시 디렉터리 fixture(두 레지스트리, 하나가
  다른 하나를 참조, 기준선 있음)를 더했다. source가 reason 있는 오류를
  던지면 출력이 load 실패 한 줄이어야 한다. 고치기 전에는 reason이 없고
  cascade 3줄이 더 나와 실패했다.
- GREEN: registry-governance 11건 통과. E-9 재실행(참조 기능 목록
  operation의 authProfileId를 NOTICE_NOPE로): 출력이 "... (reason:
  reference-feature/LIST_REFERENCE_RESOURCES: unknown authProfileId
  NOTICE_NOPE)" 두 줄뿐이고 removed 줄이 없다.
- check:registries:fixture·check:routes:fixture·baseline-fixture가 기대
  진단으로 실패한다. eslint, check:types:node, check:types:test 통과.

Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-06
2026-11-04 20:38:14 +09:00
DongHyeonka 5bee9abed9 test(contracts): FE-REG-SCHEMA 행의 방향·모르는 필드 정책을 검증기와 대조한다
문제
참조 기능의 FE-REG-SCHEMA 행은 응답 스키마를 STRIP_UNKNOWN, 요청 스키마를
REJECT_UNKNOWN이라 적는다. 실제 정책은 zod .strip()·.strict()가 정하고,
unknownFieldPolicy·direction을 읽는 실행 코드는 없다. 응답 DTO를 .strict()로
바꿔도 check:registries와 관련 테스트가 모두 통과한다(실험 X8). 그러면
백엔드가 응답에 필드 하나를 더할 때마다 그 API가 SCHEMA_MISMATCH로
실패하는데, 스냅샷과 docs/contracts/compatibility.md는 여전히 additive라
말한다.

고른 방법
설치된 기능의 HTTP descriptor마다 입력·출력 검증기를 FE-REG-SCHEMA 행과
대조하는 테스트를 더한다.
- direction: 입력 검증기 행은 REQUEST, 출력 검증기 행은 RESPONSE.
- unknownFieldPolicy: 아무 스키마도 선언하지 않는 키 하나를 가진 객체와,
  그 객체 하나를 담은 배열을 검증기에 넣는다. 그 객체 위치의
  unrecognized_keys면 REJECT_UNKNOWN, 객체 안을 봤는데 그 issue가 없으면
  STRIP_UNKNOWN이다. 정책을 적은 행만 본다.
loaded-feature-runtimes를 읽으므로 다운스트림이 더한 기능도 같은 검사를
받는다. create:feature 뼈대(NoRequest strict, 목록 응답 strip)도 맞는다.

버린 대안
- 메타데이터에서 두 칸을 지우기: 읽는 곳이 없어 가장 단순하지만 호환
  문서의 근거가 사라지고 기준선 재승인이 필요하다. 메타데이터 생성은
  다른 작업(16-04~06) 범위다.
- 스키마마다 유효한 예시 값을 두고 모르는 키를 더하기: 기능마다 예시를
  손으로 써야 해 다운스트림 기능을 자동으로 덮지 못한다.

위험·한계
- 탐침은 payload의 첫 객체 단계(객체, 또는 배열의 항목)만 본다. 그 아래
  중첩 객체의 정책은 보지 않는다.
- problem 검증기는 FE-REG-SCHEMA 행이 없어 대상이 아니다.

검증
- 변이: 응답 DTO .strip()→.strict()(X8), 생성 명령 .strict()→.strip(),
  응답 행 direction을 REQUEST로 바꾸면 각각 실패한다. 되돌리면 2건 통과. 설치된 기능이 없으면(샘플 제거 뒤) 두 건 모두 빈 채로 통과한다.
- eslint, check:types:test 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-03
2026-11-04 20:38:14 +09:00
DongHyeonka c3aa5eba35 docs(recipes): Service Worker 레시피가 오프라인 셸을 약속하지 않게 한다
문제
catalog의 service-worker-pwa trigger는 "a measured offline-shell
requirement"를 설치 조건으로 적고 failureKinds에 offline-fallback이
있다. 레시피 표도 "install/offline shell"이다. 그러나 reference 워커는
navigation을 NETWORK_ONLY로 두고, 사전 캐시에 index.html을 넣지 않으며,
설계는 cached index.html fallback을 금지한다(closed deep design 18.8).
catalog를 보고 온 제품은 템플릿 파일을 고쳐야 한다는 것을 뒤늦게
알고, 이후 동기화마다 같은 파일에서 충돌한다(0929 리뷰의 memento 사례).

고른 방법
- 0929/06-03 최소 방향대로 주장을 설계에 맞춘다. trigger에서 오프라인
  셸을 빼고 "navigation network-only, offline shell 없음, 별도 제품
  capability"를 적는다. failureKinds의 offline-fallback을
  offline-navigation-network-error로 바꾼다.
- 레시피 3절 표를 고치고, 같은 절에 졸업 경로(넘겨받는 파일 넷, 다시
  증명할 e2e 단언과 성질, 동기화 충돌)를 적는다.
- 버린 대안: 선택 handler로 오프라인 셸 확장 지점을 만들기. 설계가
  금지한 동작이고 재검토 조건(제품 요구)이 아직 없다.

위험·한계
- catalog 문구만 바뀐다. 오프라인 셸을 켜는 확장 지점은 여전히 없다.

검증
- json-schema 테스트 6건 통과, check:remediation-ledger·
  check:optional-recipe-fixtures PASS, verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-03
2026-11-04 20:35:38 +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 7b55f0f83d fix(storage): partition lock을 기다리는 put·delete가 자기 abort로 끝난다
문제: withTransactionLock은 partition lock을 signal 없이 요청한다
(withPartitionLock("shared", operation, undefined, run)). put·remove의
request.signal이 거기까지 오지 않고, Web Locks 요청은 signal이 없으면
시간 제한도 없다. mutationLockWaitTimeoutMs는 worker의 origin lease에만
걸린다. 다른 탭의 partition 삭제가 큰 업로드를 기다리는 동안 같은
partition에 put·remove(또는 만료 객체를 지우는 open)를 부르고 취소하면,
삭제가 끝날 때까지 결과가 오지 않는다(X5: abort 뒤 200 ms 동안 대기).
05-01로 정상 purge도 partition 삭제를 쓰게 되어 이 대기가 더 자주 난다.

고른 방법: put·remove가 request.signal을 withTransactionLock에 넘기고,
withPartitionLock은 kernel createAbortableOperation으로 caller signal과
mutationLockWaitTimeoutMs를 묶은 signal로 lock을 요청한다. caller
abort면 ABORTED, 시간이 다 되면 BLOCKED(retryable, RETRY)다. worker의
acquireLease와 같은 값·같은 결과다. lock을 얻으면 바로 close해 타이머를
지운다(얻은 lock에 대한 abort는 Web Locks에서 아무 일도 하지 않는다).
lock 전 abort는 journal begin 전이라 보상할 것이 없다.
버린 대안: signal만 넘기기(리뷰 최소안). 취소는 되지만 "상한 없음"이
남는다. 새 정책 값 추가. 같은 의미의 값이 이미 있다.

위험·한계: 같은 상한이 partition 삭제(exclusive)의 기다림에도 걸린다.
다른 탭 put이 10분(기본값)보다 오래 걸리면 purge가 BLOCKED로 끝나고
호출자가 다시 부른다. 전에는 끝없이 기다렸다. 실제 브라우저에서 abort
경합은 돌리지 않았고 Node Web Locks로만 확인했다. offline-indexeddb
번들 37,521 → 37,555 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 2건. abort한 put이 200 ms 안에
  끝나지 않음(STILL_WAITING), 가짜 시계로 상한을 넘겨도 put이 끝나지
  않아 10초 timeout.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes 151건
  통과. check:types, 바꾼 파일 eslint, check:optional-recipes:source
  PASS, verify:documentation 통과.
- browser: heavy lock 안에서 opfs-runtime·indexeddb-runtime spec 3엔진
  27/27 통과. 첫 실행은 dev server가 실행 중에 페이지를 다시 불러
  5건이 "Execution context was destroyed"로 떨어졌고, 다시 돌려 통과했다.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-02
2026-11-04 20:34:28 +09:00
DongHyeonka 3bc690d3fb test(realtime): WebSocket 구독별 초당 event 상한을 테스트로 고정한다
문제
WebSocket 연결은 구독마다 1초 창에 maxEventsPerSecond(256, server가
알린 값과 작은 쪽)를 넘는 event가 오면 EVENT_RATE_EXCEEDED recovery를
요청하고 QUEUE_OVERFLOW로 닫는다. 이를 확인하는 테스트가 없어 검사를
꺼도 모든 테스트가 통과한다(리뷰 변이 R7, 두 라운드째). 설계 11절
상한표에도 행이 없다.

고른 방법
- 상한을 2로 낮춘 연결에서 2개 → 1초 뒤 2개(열림 유지) → 1개 더(닫힘,
  EVENT_RATE_EXCEEDED)를 보내는 테스트 1건을 더한다. 창 초기화와 상한
  값 출처까지 한 테스트가 본다.
- 설계 11절 상한표에 행 하나를 더한다.

위험·한계
- 동작은 바꾸지 않았다. 실제 서버 부하로는 확인하지 않았다.

검증
- 새 테스트 통과(websocket-connection 24건).
- 변이 3건 모두 검출: 상한 검사 끄기(R7), 1초 창 초기화 삭제, 협상된
  상한 대신 256 고정.
- 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 1101/04-03
2026-11-04 20:34:12 +09:00
DongHyeonka 0cc2553381 docs(operations): 워커 제거 1단계를 최대 미방문 기간 이상 유지하라고 적는다
문제
자기 해제 service-worker.js는 REMOVE_REGISTRATION release만 낸다
(build-frontend.ts). 다음 단계 release에는 워커 파일이 없어 update
검사가 404로 실패한다. PURGE_OWNED_RESOURCES는 부팅한 페이지만 다시
unregister하고, null은 아무것도 하지 않는다. 1단계 기간에 오지 않은
사용자에게 부팅을 막는 워커나 옛 워커가 남는다(리뷰 1103 실험 L3).
운영 문서는 세 단계 순서만 적고 각 단계 유지 기간이 없다.

고른 방법
- 0929/06-06의 최소 방향 중 문서 한 줄을 고른다. SW runbook 8절과
  release-cache-rollback.md 4단계에 "1단계를 최대 미방문 기간 이상 유지,
  그 뒤 남은 사용자가 보이면 1단계를 다시 배포"를 적는다.
- 버린 대안: 2단계도 자기 해제 워커를 내보내고 hosting 허용 목록을
  맞추기. 빌드·hosting 검사·e2e를 함께 바꿔야 해서 이월 항목의 작은
  수정 범위를 넘는다.

위험·한계
- 동작은 그대로다. 유지 기간을 지키는지는 운영자 몫이다.

검증
- 문서와 코드(build-frontend.ts, service-worker-page-controller.ts
  PURGE_OWNED_RESOURCES 분기, service-worker-removal.ts)를 대조했다.
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 2절 0929/06-06
2026-11-04 20:32:32 +09:00
DongHyeonka 5d0f5ad7f8 docs(realtime): heartbeat를 멈춘 WebSocket이 예산을 새로 받지 못함을 적는다
문제
heartbeatEligible()이 false면 WebSocket 연결은 HEARTBEAT를 보내지
않는다. 그러면 HEARTBEAT_ACK가 없고, 이벤트도 없는 조용한 stream은
유효 신호가 없어 reconnect 예산이 초기화되지 않는다(0929 실험 E7).
훅에 주석이 없어 채택자가 이 결과를 코드 두 곳(heartbeat 송신,
isReconnectAttemptResetEligible)을 같이 읽어야 안다.

고른 방법
- 0929/04-04의 최소 방향대로 훅 옆에 주석을 달고 설계 5.3 예산 문단에
  같은 문장을 더한다. hidden 연결은 닫거나 visible 복귀 때 새 run을
  만들라고 적는다. 동작은 바꾸지 않는다.

위험·한계
- 동작 변경이 없다. 주석이 코드와 어긋나면 잡는 검사는 없다.

검증
- 바꾼 파일 eslint 통과. 주석만 바꿨다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 2절 0929/04-04
2026-11-04 20:31:51 +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 5b2106df25 docs(realtime): realtime 레지스트리 세 바인딩의 출처를 레시피에 적는다
문제
realtime 레지스트리는 schemaCodecs·mappers·apiOperations 세 바인딩을
받아 event type과 checkpoint를 대조한다. V2 삭제(12f3bb7)로 기능의
runtimeSchemas·mappers 칸이 사라져 지금 출처가 있는 것은
apiOperations뿐이다. 레시피는 "제품 feature는 이 runtime에
schema/codec/query … 주입"이라고만 적어 조합자가 codec·mapper를 어디서
만드는지 알 수 없다.

고른 방법
- 리뷰의 최소 방향대로 레시피 Realtime 절에 세 바인딩의 출처를 적는다.
  apiOperations는 loadInstalledFeatureRuntimeRegistries().apiOperations,
  schemaCodecs는 V3 events[].payloadValidator·checkpoint outputValidator를
  runtimeSchemaCodecFromValidator + composeRuntimeSchemaCodecs로,
  mappers는 조합 코드의 BoundaryMapper + composeBoundaryMapperRegistry다.
  등록 때 맞아야 하는 id(payloadSchemaId = validator schemaId =
  mapper inputSchemaId)도 적었다(realtime-streams.ts 등록 검사).
- 버린 대안: 지금 기능 모듈에 realtimeMappers 칸을 더하거나 V3 events에서
  event type을 뽑기. 공개 계약이 바뀌고, 04-02의 push 경로(STOMP hint면
  delta mapper가 필요 없을 수 있음)를 고른 뒤 정하는 것이 맞다.

위험·한계
- 코드 변경이 없다. 같은 이벤트를 V3 events와 realtime 등록 두 곳에
  적는 중복은 문서 규칙으로만 막는다.

검증
- verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-06
2026-11-04 20:30:22 +09:00
DongHyeonka d13a393600 fix(storage): 계정 삭제 purge가 끝나지 않은 put을 보면 partition을 지운다
문제: 손상이 없는 LOGOUT·ACCOUNT_DELETION purge는 commit된 object 행과
참조 없는 chunk만 본다. 같은 partition의 끝나지 않은 journal 행
(PREPARING·FILES_READY)은 보지 않고, sweep은 staging receipt가 가리키는
chunk를 건너뛰면서도 COMPLETED를 돌려준다. 그래서
- 다른 탭이 put 중이면 purge가 "COMPLETED"를 보고한 뒤 그 객체가
  그대로 읽힌다(X1, 실제 Chromium·Firefox에서도 같음).
- commit 직전에 멈춘 put(FILES_READY)은 purge 뒤 다음 reconcile이
  commit해 계정 삭제한 사용자 파일이 객체로 다시 생긴다(X2).
- 업로드 중 멈춘 put(PREPARING)은 chunk가 grace 기간 동안 남고(X2b),
  그 행이 손상됐으면 partition 삭제도 일어나지 않아 영원히 남는다(X3).
손상이 있을 때만 partition 삭제가 진행 중 put까지 기다렸다 지웠다.

고른 방법(리뷰 5.1절 (c)): LOGOUT·ACCOUNT_DELETION이 객체를 다 돈 뒤
그 partition 키를 가진 journal 행 수를 센다. 하나라도 있으면(읽을 수
있든 없든) sweep 대신 이미 있는 partition 삭제로 넘긴다. partition
삭제는 exclusive partition lock으로 진행 중 put·delete가 돌아오기를
기다린 뒤 디렉터리와 그 partition의 행을 모두 지운다(e5b7b3e).
OpfsJournalPort에 countPartitionTransactions(scope)를 더했다.
removePartition이 지우는 같은 LOGICAL_KEY_INDEX 범위를 세므로, 센 행은
삭제가 지운다.
버린 대안: (a) 문서에 "reconcile 먼저" 안내 — X1·X3을 막지 못한다.
(b) report에 수만 추가 — 지울 방법이 없다(X3). (d) 항상 partition
삭제 — 더 단순하지만 끝나지 않은 행이 없을 때의 예산 단위 진행과
removedObjects·releasedBytes 보고를 잃는다.

위험·한계:
- 공개 포트에 필수 메서드가 하나 는다. OpfsJournalPort를 직접 구현한
  쪽은 추가해야 한다([계약]).
- 끝나지 않은 행이 하나라도 있으면 purge가 예산 없는 partition 삭제가
  되고, 다른 탭의 진행 중 put이 끝날 때까지 기다린다. 그 put의 결과도
  지운다(손상 경로와 같은 의미). purge가 행을 센 뒤 시작한 put은
  남는다(point-in-time).
- 기존 테스트 "never sweeps the chunk of a put that runs while the purge
  does"는 X1 동작을 기대값으로 고정하고 있었다. 새 의미로 바꿨다.
  0929/05-02 테스트는 덮어쓰기가 purge의 목록과 remove 사이에 끝나도록
  바꿔 CONFLICT 경로를 계속 본다.
- 소속을 알 수 없는(logicalKey가 깨진) 행은 여기서도 세지 못한다(05-03).
- WebKit은 기본 정책에서 OPFS 지원 판정을 통과하지 못해 browser spec이
  일찍 끝난다. offline-indexeddb 번들 37,423 → 37,521 / 38,500 gzip B.

검증:
- RED: opfs-worker-runtime.test.ts 새 4건(X1, FILES_READY, PREPARING,
  손상 행)이 partitionDeleted 없음으로 실패.
- GREEN: OPFS 단위 3파일 + optional-runtime-host + tests/recipes +
  tests/contract 172건 통과. journal에 countPartitionTransactions 테스트
  1건(손상 행 포함, 다른 partition 제외, 삭제 뒤 0).
- browser: opfs-runtime.spec.ts에 X1 2탭 판을 더했다. heavy lock 안에서
  3엔진 9/9 통과(WebKit은 지원 판정에서 끝남).
- check:types, 바꾼 파일 eslint, check:optional-recipes:source PASS,
  verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/05-adapters-storage-kernel.md 05-01
2026-11-04 20:29:34 +09:00
DongHyeonka 615da352b9 docs(realtime): 짝 백엔드 실시간 출구와 프론트 transport 대응표를 적는다
문제
짝 백엔드의 실시간 출구는 STOMP-over-SockJS 채널(/ws, /topic 구독 1개,
Map<String,String> 투영, 재전송 없음)과 raw WebSocket 라이브러리 API,
NDJSON·JSON text sequence writer다. 프론트 SSE 어댑터는
text/event-stream과 REALTIME_EVENT_V1 envelope을, WebSocket 어댑터는
subprotocol "realtime.v1"을 요구한다. 어느 repo에도 이 불일치와 지금
되는 경로가 적혀 있지 않아, 채택자가 두 repo를 다 읽어야 안다.

고른 방법
- 리뷰의 최소 방향을 프론트 repo 안에서 따른다. 설계 문서에 0.1절을
  두고 transport별 대응표(지금 연결되나·이유), push가 필요할 때의 세
  길, 재검토 조건을 적는다. 레시피 Realtime 절과 매뉴얼 03 C절에서 한
  줄로 링크한다.
- 다시 확인한 백엔드 사실(읽기만): 아키텍처 테스트가 MVC SseEmitter를
  금지한다(ForbiddenApiArchitectureTest NO_SSE_EMITTER, 결정 D3).
  StreamMediaType.SSE는 OpenAPI 생성기만 쓴다. subprotocol 협상 코드는
  없다. 그래서 첫째 길을 SSE가 아니라 realtime.v1 WebSocket handler로
  적었다.
- 지금 되는 경로(bounded polling)는 사실로 적고, push 경로는 고르지
  않았다. 제품 결정이다.
- 버린 대안: desktop-server-git/design-docs/에 쓰기. 이 브랜치 밖이라
  함께 합쳐지지 않는다. 필요하면 그쪽에서 이 절을 링크한다.

위험·한계
- 백엔드 사실은 지금 백엔드 HEAD(70fb80bf)를 읽은 것이다. 백엔드가
  바뀌면 표가 낡는다. 재검토 조건에 적었다.
- 실제 연결은 실행하지 않았다(리뷰와 같음).

검증
- verify:documentation PASS_SCOPED. documentation-readiness·
  changelog-review-ids 테스트 15건 통과.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-02
2026-11-04 20:29:32 +09:00
DongHyeonka 9800bc89f3 test(contracts): 금지 조각이 든 런타임 설정 키를 test:unit에서 막는다
문제
설정 키 금지 조각 검사(assertSafeConfigNames: TOKEN, COOKIE, SECRET 등)는
부팅 때 한 곳에서만 돈다. ece944d가 연 제품 키 경로로 PRODUCT_COOKIE_NOTICE
같은 키를 zod 필드·FE-REG-ENV 행·config/runtime 값으로 더하면
generateRuntimeConfig, 범위 테스트, check:registries가 모두 통과한다. 그
config.json으로 배포하면 모든 사용자가 부팅 실패 화면을 보고, 오류 코드
CONFIG_SECRET_NAME_REJECTED에는 키 이름이 없다(실험 E-4).

고른 방법
env-registry-coverage에 사례 하나를 더한다. V2 스키마가 읽는 키와
FE-REG-ENV 런타임 행 키 전부로, 값은 스키마 기본값(CAPABILITY_OVERRIDES의
중첩 키 포함)으로 문서를 만들어 assertSafeConfigNames에 넣는다. 실패
메시지가 키 이름을 말한다. 규칙은 매뉴얼 03 C절의 product-contracts.ts
항목에 적었다.

버린 대안
- product-contracts.ts 주석에 규칙 적기: 이 파일은 제품 소유이고 템플릿이
  복사 뒤에 고치지 않는다고 약속한 파일이다. 동기화 때 충돌을 만든다.
- generate-runtime-config에서도 검사: 스키마가 strict라 제품 키는 스키마
  필드여야 들어가고, 그 키는 이 테스트가 먼저 잡는다. 같은 검사를 한 곳
  더 두지 않았다.

위험·한계
- 부팅 오류 CONFIG_SECRET_NAME_REJECTED에 거절한 키 이름을 싣는 것은 하지
  않았다(src/bootstrap/load-runtime-config.ts, 다른 작업 범위).
- 제품 record 필드의 임의 중첩 키(값으로만 생기는 키)는 기본값에 없으면
  이 테스트가 보지 못한다. 부팅 검사가 여전히 막는다.

검증
- E-4 재실행: PRODUCT_COOKIE_NOTICE를 제품 zod 필드와 행으로 더하면 이
  사례가 "Forbidden client configuration key: PRODUCT_COOKIE_NOTICE"로
  실패한다. 되돌리면 4건 통과.
- eslint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-04
2026-11-04 20:28:49 +09:00
DongHyeonka a144b575e5 fix(contracts): FE-REG-ENV 런타임 행의 필수 여부·기본값을 스키마와 맞춘다
문제
FE-REG-ENV 런타임 행 13개 중 5개의 required·defaultValue가 실제 V2
runtime config 스키마(runtimeConfigV2ArtifactSchema)와 다르다.
- TELEMETRY_ENABLED: 행 기본값 false / 스키마 필수, 기본값 없음
- AUTH_MODE: 행 기본값 "external" / 스키마 기본값 없음
- RELEASE_MANIFEST_URL: 행 required true / 스키마 선택(기본값 있음)
- CAPABILITY_OVERRIDES: 행 기본값 null / 스키마 기본값 네 항목 DEFAULT
- FEATURE_OVERRIDES: 행 기본값 null / 스키마 기본값 {}
d0414c8의 테스트는 스키마 키마다 행이 있는지만 본다. 스키마에 없는 런타임
행도, 값이 다른 행도 통과한다. 이 레지스트리는 기준선 호환 검사 대상이라
틀린 값이 계약으로 굳는다. AUTH_MODE를 빼도 external이 된다고 읽으면
부팅이 스키마 오류로 멈춘다.

고른 방법
- env-registry-coverage에 두 방향을 더한다. 스키마가 읽지 않는 런타임 행은
  실패한다. 각 행의 required·defaultValue는 스키마 필드에 undefined를 넣은
  결과(실패 = 필수·기본값 없음, 성공 = 선택·그 값)와 같아야 한다. 차이는
  키·행 값·스키마 값을 한 줄로 보인다. 제품 키(PRODUCT_*)도 같은 검사를
  받는다.
- 5개 행을 스키마에 맞춘다. 두 override 기본값은 객체라 governance의
  defaultValue 타입에 object를 더했다.
- ENV_REGISTRY 주석에 두 칸의 뜻(null = 스키마가 기본값을 주지 않음)을
  적었다.

버린 대안
- 행의 required·defaultValue를 스키마에서 계산해 채우기: 손으로 맞출 일이
  사라지지만 env.ts가 zod 스키마를 import해야 한다. env.ts는 부팅 경로
  (getBuildConfig)에 있어 초기 청크에 zod 스키마가 끌려 들어간다.

위험·한계
- RELEASE_MANIFEST_URL required true→false는 breaking 칸 변경이고
  governance fieldTypes도 바뀌어 기준선을 다시 승인했다.
- 스키마 superRefine의 조건부 필수(TELEMETRY_ENABLED면 TELEMETRY_ENDPOINT)는
  행에 표현하지 않는다.

검증
- RED: 새 대조 테스트가 위 5개 행을 정확히 보고하며 실패했다.
- GREEN: env-registry-coverage 3건 통과. 변이: 스키마 REQUEST_TIMEOUT_MS
  기본값만 20,000으로 바꾸면 실패, 스키마 필드 없는 제품 행을 더하면 실패.
- check:registries(재승인 뒤 compatibility=none), run-vitest related
  (env.ts, governance) 18파일 154건, registry-governance·product-composition
  23건, check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/13-build-release-supply-chain.md 13-04
Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-05
2026-11-04 20:27:35 +09:00
DongHyeonka b4ae4c1ed3 docs(operations): waiting 기간에 소유 캐시가 쌓이는 것과 정리 시점을 적는다
문제
캐시를 지우는 곳은 activate 하나다(현재 + 마커가 가장 높은 직전 1개).
템플릿은 requestActivation()을 부르지 않으므로 활성화는 그 scope의
탭이 모두 닫혀야 일어난다. 그 사이 release마다 새 후보가 waiting
워커를 밀어내지만 밀려난 캐시는 남는다(리뷰 실험 L2: A 활성 + 탭
유지에서 B, C를 받으면 소유 캐시 3개, 활성화 뒤 2개). 운영 문서는
"현재 + 직전 1개"만 말해 waiting 기간의 캐시 수가 보이지 않는다.

고른 방법
- 리뷰 5.1 판단대로 (a) 문서만 고친다. SW runbook 8절에 쌓이는 규칙,
  예, 크기 상한, 쿼터에 닿았을 때의 결과, 줄이는 방법
  (requestActivation 화면)과 install이 지우지 않는 이유를 적는다.
  release-cache-rollback.md SW 1단계에 한 문장과 링크를 둔다.
- 버린 대안: (b) install 성공 뒤 "무마커 + 이번 후보 아님 + 활성 캐시
  아님"을 지우기. install하는 워커는 활성 캐시 이름을 모르고, 마커
  쓰기에 실패한 활성 캐시는 후보와 구별되지 않는다. (c) 이번 후보를 뺀
  무마커 캐시를 모두 지우기. 그 활성 캐시를 지워 직전 캐시 보존 성질을
  깬다.

위험·한계
- 쌓이는 동작 자체는 그대로다. 사전 캐시가 1 MiB를 넘고 release가 잦아
  지면 (b)를 다시 본다(리뷰 재검토 조건).
- 브라우저 종료로 활성화되는지는 확인하지 않았다.

검증
- 문서와 코드(service-worker-lifecycle.ts onActivate,
  service-worker-static-assets.ts QUOTA_EXCEEDED, service-worker.ts
  assetSetBytes)를 대조했다.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-04
2026-11-04 20:27:30 +09:00
DongHyeonka 7144653109 docs(operations): 워커 스크립트 헤더 검사 범위를 지금 코드에 맞춘다
문제
SW runbook(browser-file-storage-recovery.md 8절)은
"verify:hosting-headers는 파일이 있는지만 보고 이 헤더는 보지 않는다"고
적는다. 지금은 워커를 싣는 빌드에서 serviceWorker surface가 필수이고
Cache-Control이 no-cache가 아니면 FAIL이다(cache-policy.json
serviceWorker, verify-hosting-headers.ts). release-cache-rollback.md는
맞게 적어 두 운영 문서가 반대로 말한다.

고른 방법
- 그 문장을 live 모드가 /service-worker.js의 no-cache를 확인한다로
  고친다. fixture 모드가 UNVERIFIED라는 것과, 하위 경로 base는 probe가
  아직 받지 않아 손으로 확인해야 한다는 것을 함께 적는다.

위험·한계
- 하위 경로 문장은 0929/13-06이 고쳐지면 지워야 한다.

검증
- 문서와 코드(cache-policy.json, verify-hosting-headers.ts,
  hosting-probe.ts classifyLiveHostingBaseUrl)를 대조했다.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-01
2026-11-04 20:27:00 +09:00
DongHyeonka 0f58abbd32 fix(hosting): live probe가 사전 캐시 확장자마다 Content-Type을 확인한다
문제
워커 install은 사전 캐시 자산마다 응답 MIME이 manifest 값
(CACHEABLE_ASSET_CONTENT_TYPES: .css .js .mjs .png .svg .webp .woff2)과
정확히 같아야 하고, 하나라도 틀리면 release 전체를 거절한다. 호스팅
live probe는 index가 가리키는 entry script 하나만 요청하고
hashedAsset.contentTypes도 JavaScript뿐이다. 그래서 CSS를 text/plain,
글꼴을 octet-stream으로 보내는 호스트도 게이트는 PASS다. 페이지는
글꼴을 그대로 쓰므로 워커만 조용히 설치되지 않는다.

고른 방법
- probeAssetContentTypes를 더한다. 후보 dist의 assets/에서 확장자마다
  첫 파일(이름순)을 요청하고, 그 확장자의 워커 표 MIME과 비교한다.
  결과는 surface hashedAsset.<ext>, header content-type이다.
  verify-hosting-headers live 모드에서만 부른다.
- 기대 MIME은 워커 표에서 바로 읽는다. .js 계열은 hashedAsset surface와
  같이 application/javascript도 받는다. 두 목록이 같다는 것을 테스트가
  지킨다(acceptedAssetContentTypes(".js") = cache-policy hashedAsset).
- 운영 문서(release-cache-rollback.md)에 새 검사를 적는다.
- 버린 대안: (b) 워커가 비JS 자산 MIME을 느슨하게 받기 — 캐시에서 꺼낸
  응답이 틀린 MIME을 그대로 갖고 설계 §18 확인 순서 4와 어긋난다.
  (c) 사전 캐시를 JS·CSS로 줄이기 — 글꼴 캐시 이득을 잃는다. (d) 문서만
  — 검출이 없다(리뷰 5.2).

위험·한계
- live probe 요청이 확장자 수만큼 는다(지금 빌드는 .js·.css 2개).
- 확장자마다 파일 하나만 본다. 같은 확장자 안에서 경로마다 MIME이
  다른 호스트는 잡지 못한다.
- cache-control은 이 자산들에서 다시 보지 않는다. entry script의
  hashedAsset 검사가 그대로 본다.
- 실제 호스트로 live 모드를 돌리지 않았다. fetcher 대역으로만 확인했다.
- 하위 경로 base는 probe가 아직 거절한다(0929/13-06, 다른 영역). 새
  함수는 base 기준 상대 경로로 요청하므로 그 수정 뒤에도 그대로 쓴다.

검증
- 새 테스트 4건을 옛 코드에 돌림: 4건 실패(RED). 새 코드:
  hosting-probe·service-worker-build-output 테스트 통과.
- CSS를 text/plain으로 보내는 호스트 → hashedAsset.css FAIL.
- check:types:node·check:types:test 통과, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-03
2026-11-04 20:26:24 +09:00
DongHyeonka 08ed0a088d fix(contracts)!: FE-REG-API 행에 status 목록·상한·재시도 예산·검증 생략을 담는다
문제
V2 행과 V2/V3 parity 테스트를 지운 뒤 FE-REG-API 행은 descriptor에서
12칸만 뽑는다. acceptedStatuses, emptyBodyStatuses, 바이트 상한, 마감,
retryBudget, traffic, commandEffect, commandRecovery, 검증 생략 표시는 행에
없다. 그래서 생성 API의 acceptedStatuses를 [200, 201]에서 [201]로 줄여도
check:registries가 통과한다(실험 X2). 이전 커밋 d99301b에서는 같은 변경이
breaking 증거 누락으로 실패했다. 응답 상한·마감 변경은 기록에서 사라졌고
(X3·X6), problemSchema는 breaking 칸이 아니어서 problem 검증기 id를 바꿔도
behavior-change로 통과했다(X4). 짝 백엔드는 생성에 201, 본문 없는 응답에
204를 쓴다. 이 status를 빼면 배포 뒤 그 API가 모두 실패한다.

고른 방법
- projectApiOperationRows가 함수 밖의 descriptor 값을 모두 뽑는다:
  acceptedStatuses, emptyBodyStatuses, unvalidated(검증을 건너뛰는 검증기
  칸 이름: input·output·problem), requestByteLimit, responseByteLimit,
  totalDeadlineMs, retryBudget, traffic, commandEffect, commandRecovery.
- commandEffect는 함수를 빼고 데이터만 남긴다: classifyStatus가 있는지
  (classifiesStatus)와, descriptor가 이름을 붙였을 때만 refusedBeforeWrite
  목록. refusedBeforeWrite는 다른 작업에서 더해지는 선택 칸이라 구조로
  읽고, 없으면 행에도 없다.
- governance: problemSchema와 unvalidated를 breakingFields에 넣는다.
  status 배열은 breakingFields에 넣지 않는다. 분류기가 배열에서 값이
  빠지면 이미 allowed-value-removed breaking으로 본다. breakingFields에
  넣으면 status를 더하는 것(전에 받던 응답을 모두 계속 받는 변경)까지
  증거를 요구한다. 숫자 칸·traffic·command 칸은 behavior-change로 기록한다.
- 매뉴얼 01 9단계에 무엇이 breaking이고 무엇이 behavior-change인지,
  descriptor 함수는 행에 없다는 것을 적었다.

버린 대안
- descriptor 전체(함수 제외)를 투영: policyId·diagnosticsOperation까지
  기준선이 흔들려 리뷰 잡음만 는다. 둘은 wire 값이 아니다.
- V2/V3 parity 테스트 부활: 사본이 다시 둘이 된다.
- 숫자 칸 감소를 breaking으로: 분류기에 방향 규칙이 없고, 상한·마감
  조정은 자주 하는 운영 값이다. 기록만 하고 PR에서 본다.

위험·한계
- governance 계약(requiredFields·fieldTypes·breakingFields)이 바뀌어
  기준선을 다시 승인했다. 다운스트림은 동기화 때 재승인 1회가 필요하다.
- FE-REG-SCHEMA에 problem 스키마 행이 없어 problemSchema는 참조 검사
  대상이 아니다. breaking 칸으로만 잠근다.
- classifyProblem이 무엇을 NOT_APPLIED로 보는지는 함수라 기록되지 않는다.

검증
- 기준선 재승인 뒤 실험 재실행(check:registries):
  X2 [200,201]->[201] 실패(acceptedStatuses:allowed-value-removed 증거 누락),
  X4 problem 검증기 id 변경 실패(problemSchema:field-changed 3건),
  X5 GET 출력 검증기 생략 실패(unvalidated:field-changed),
  X3 응답 상한·X6 마감 변경은 behavior-change로 통과하고 스냅샷에 남는다.
- tests/unit/api-operation-rows.test.ts: 새 칸 고정, refusedBeforeWrite
  있음·없음, governance JSON으로 분류한 8가지 변경.
- run-vitest related(api-operations.ts, governance) 21파일 156건,
  registry 테스트 4파일 63건, check:registries:compatibility-fixtures,
  check:types, eslint, verify:documentation 통과.

BREAKING CHANGE: FE-REG-API governance 계약이 바뀌어 다운스트림의
check:registries가 FE-REG-API:$contract:* contract-field-changed로
실패한다. 동기화 뒤 REGISTRY_BASELINE_OWNER·REGISTRY_BASELINE_REASON을
주고 update:registry-baseline을 한 번 돌린다.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 07-01
Refs: docs/reviews/2026-11-03-maturity-review/README.md 3절
2026-11-04 20:24:41 +09:00
DongHyeonka a145f30b48 fix(web-push): dot segment가 든 registry path를 생성 때 거절한다
문제
registry path는 router base path를 뺀 앱 경로이고, 정상 클릭은
`${appBasePath}${path}`를 URL로 풀어 연다. registry 검사는 `/` 시작,
`//`·`\`·`#` 금지, 같은 origin만 본다. URL parser는 `..`와 `%2e%2e`를
dot segment로 풀기 때문에 scope `/app/`에서 `/../admin`과
`/%2e%2e/admin`이 모두 `https://app.example.test/admin`을 연다(리뷰
실험 ⑤). 검사를 통과한 경로가 앱 밖을 연다.

고른 방법
- safePath가 `new URL(path, base)`의 pathname + search가 입력과 같을 때만
  받는다. `..`·`.`·`%2e%2e`(대소문자 무관)는 parser가 바꾸므로 거절된다.
  query는 그대로 남는다.
- 버린 대안: 클릭 때 target.pathname이 앱 루트 아래인지 보기. 잘못된
  registry가 클릭할 때에야 드러난다. registry는 제품 코드라 생성 시점에
  throw하는 쪽이 이르고 작다(리뷰 5.3 (a)).

위험·한계
- 정규화되지 않은 경로(인코딩 안 된 비ASCII 문자, 빈 query `?`)도
  거절된다. registry를 쓰는 제품 코드는 아직 없다.
- registry가 서버가 내려주는 런타임 데이터가 되면 클릭 때 검사도 함께
  둬야 한다(리뷰 재검토 조건).

검증
- 새 테스트를 옛 코드에 돌림: 5건 실패(RED). 새 코드: web-push 단위
  6파일 76건 통과.
- 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/06-adapters-service-worker-push.md 06-02
2026-11-04 20:24:14 +09:00
DongHyeonka d7c6cb4fd2 fix(auth): 세션 복구가 no-session이면 로그인 버튼을 보인다
문제: 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
2026-11-04 20:23:22 +09:00
DongHyeonka af000673ef fix(realtime)!: 서버에 닿지 않은 SSE·poll 실패를 PROVIDER_UNAVAILABLE로 낸다
문제
브라우저는 online인데 서버·프록시만 닿지 않을 때 실패 이름이
transport마다 다르다. SSE는 fetch·reader 거절을 OFFLINE, poll은
execute 거절을 OFFLINE, WebSocket은 error를 PROVIDER_UNAVAILABLE로
낸다. reconnect coordinator는 transport OFFLINE을 backoff로 재시도하고
예산을 다 쓰면 online인데도 OFFLINE으로 끝낸다. 설계 13.1의 OFFLINE
행은 "online hint 뒤 bounded check"라 5.3과 다른 말을 한다. kind로
화면 문구나 조합 판단을 고르면 같은 서버 장애가 SSE에서는 "오프라인",
WS에서는 "서비스 이용 불가"가 되고, "OFFLINE이면 online 이벤트를
기다린다"는 조합 코드는 다시 멈춘다(0929/04-01의 모양).

고른 방법
- 리뷰 5.3절 판단대로 어휘를 맞춘다. SSE fetch 거절(CONNECT)과 reader
  거절(RECEIVE), poll execute 거절을 PROVIDER_UNAVAILABLE(retryable)로
  바꾼다. 이제 OFFLINE은 환경 신호에서만 나온다.
- poll은 PROVIDER_UNAVAILABLE을 lease 안에서 재시도하므로, 던지는
  execute는 바로 끝나지 않고 backoff로 maxAttempts까지 다시 시도한다.
  executor가 PROVIDER_UNAVAILABLE을 돌려준 경우와 같은 처리다.
- 설계 13.1의 OFFLINE·PROVIDER_UNAVAILABLE 행과 5.3 문단을 고친다.
- 버린 대안: 13.1에 OFFLINE의 두 뜻을 적기만 하기. 비용은 1행이지만
  조합자가 navigator.onLine을 따로 봐야 원인을 안다. 운영 중인 제품이
  없는 지금 어휘를 바꾸는 비용이 가장 작다(리뷰 5.3).

위험·한계
- 배럴로 공개된 SSE 연결·poll coordinator의 결과 kind가 바뀐다. repo
  안 소비자는 테스트뿐이다.
- 던지는 execute(조합 코드의 버그 포함)는 이제 lease 예산만큼 다시
  불린다. 상한은 maxAttempts·maxElapsed 그대로다.
- 환경 신호가 늦게 offline이 되는 경우 첫 실패는 PROVIDER_UNAVAILABLE로
  보인다. offline 대기는 kind가 아니라 환경 신호로 걸리므로 멈춤은 없다
  (before/after 테스트 그대로 통과).

검증
- 바꾼 기대값 3건을 옛 코드에 돌림: 3건 실패(RED). 새 코드: realtime
  단위 241건 통과.
- check:types 통과, 바꾼 파일 eslint 통과.

BREAKING CHANGE: SSE 연결의 fetch·reader 거절과 bounded poll의 execute
거절이 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. poll은
던지는 execute를 lease 안에서 재시도한다. OFFLINE을 서버 장애로 읽던
조합 코드는 PROVIDER_UNAVAILABLE을 함께 본다.

Refs: docs/reviews/2026-11-03-maturity-review/04-adapters-realtime.md 04-04
2026-11-04 20:23:21 +09:00
DongHyeonka e7d63586b6 fix(features): 기능 어댑터 기여에 needs에 적은 capability만 넘긴다 (1103/09-08)
문제
조립 루트 주석과 생성 뼈대 주석은 "기능은 needs에 적은 capability만 받는다"고
했지만, invokeContribution은 context 전체를 넘겼다. needs: ["telemetry"] 기여가
["telemetry","http"]를 받았다(E6). 제품 capability도 모든 기능에 갔다. 타입이
막고 있어 cast가 있어야 생기지만, 그러면 needs가 실제 의존을 다 말하지 않는다.

고른 방법
invokeContribution이 needs의 키만 골라 새 frozen 객체로 넘긴다. 주석을 "타입만
그렇다"로 고치는 대안은 생성 뼈대 주석(scripts/create-feature.ts)까지 모든
기능에 퍼진 설명을 바꿔야 해서 버렸다. 이제 두 주석이 실행과 맞는다.

위험·한계
needs에 적지 않은 capability를 cast로 쓰던 다운스트림 기능은 그 값이
undefined가 된다. repo 안에는 그런 기능이 없다.

검증
- RED: feature-adapter-composition.test.ts에 E6 행(받은 키가 ["telemetry"])을
  더했고 수정 전 실패.
- tests/contract/reusable-capability, tests/features, runtime-adapters 계열,
  product-composition-fixture → 27 files / 178 tests 통과.
- check:types, eslint 통과.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-08
2026-11-04 20:22:58 +09:00
DongHyeonka f98d0c3663 fix(contracts): 계약 조립 오류 메시지에 원인을 싣는다 (1103/09-07)
문제
ContractContributionError의 message는 "Installed contract contribution is not
composable" 하나였고 원인은 reason 속성에만 있었다. check:registries는
message 첫 줄만 적으므로, 제품 인증 프로필 id를 잘못 적으면 게이트 출력에
operation id도 프로필 id도 없었다("missing registry source …: Installed
contract contribution is not composable"). 매뉴얼 02 5절과 starter-experience
정본 표는 V2 해석기와 함께 지워진 "REST security profiles are incoherent …"
메시지를 약속했다.

고른 방법
message에 reason을 붙인다: "Installed contract contribution is not composable:
<reason>". 메시지를 읽는 모든 곳(check:registries, vitest, 부팅 오류)이 원인을
보게 된다. check-registries.ts만 reason을 적게 하는 대안은 다른 출력 경로를
그대로 두어 버렸다. reason은 기능·operation·프로필 id 같은 개발자 식별자뿐이다.
문서 세 곳(매뉴얼 02 5절, errors.md, starter-experience 표)을 실제 출력으로
고쳤고, V3 descriptor에 없는 auth 칸 조합 문장을 지웠다.

위험·한계
- check:registries가 같은 실패 뒤에 적는 연쇄 줄(FE-REG-API is not an object
  registry, breaking change missing evidence … removed)은 그대로다(14-06 범위).
- message 문자열 전체를 비교하는 다운스트림 테스트가 있으면 바뀐다.

검증
- RED: second-api-feature-registries.test.ts에 authProfileId를 SECOND_UNKNOWN
  으로 바꾼 행을 더했고, 수정 전 stderr에 원인이 없어 실패.
- 같은 파일, external-contract-runtime, http-execution-v3-auth-profile,
  reference-fixture-provenance, tests/platform → 33 files / 255 tests 통과.
- eslint, tsc(test), verify:documentation PASS_SCOPED.

Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-07
2026-11-04 20:21:55 +09:00