Commit Graph
287 Commits
Author SHA1 Message Date
DongHyeonka d3ddc8957f feat(contracts): zod 검증기 어댑터를 공유하고 검증 생략을 이름으로 드러낸다 (1101/07-03)
문제
- zod 스키마를 RuntimeValidator로 바꾸는 zodValidator가 참조 기능의
  reference-schemas.ts 안에만 있다. 기능끼리 import가 금지라 새 기능은
  복사하고, 복사본은 이미 갈라졌다(tests/helpers 복사본은 성공 값을
  structuredClone하지 않는다). 참조 기능을 지우면 어댑터도 사라진다.
- RuntimeValidator<T>는 schemaId와 safeParse만 요구한다. 아무것도
  검증하지 않는 검증기도 조립을 통과하고, 검증을 생략했다는 사실이
  타입·이름·조립 결과 어디에도 남지 않는다.

고른 방법 (C: 공유 어댑터 + 생략 표시)
- zodValidator를 src/contracts/zod-validator.ts로 옮긴다. 참조 기능과
  tests/helpers/external-contract-fixture.ts가 이것을 import한다. 동작은
  참조 기능 쪽 원본 그대로다(성공 값 structuredClone, 경로 배열, code
  문자열). tests/helpers도 이제 성공 값을 복사한다.
- unvalidatedPayload(schemaId, reason)를 external-contract-runtime.ts에
  둔다. 만든 검증기에는 validation: "NONE"과 unvalidatedReason이 붙는다.
  zod가 필요 없어서 검증기 프로토콜 옆에 뒀다.
- composeContractContributions가 이 표시가 붙은 검증기를
  unvalidatedPayloads(featureId, contractId, validator, schemaId, reason)로
  내놓는다. HTTP의 input·output·problem과 이벤트의 envelope·payload를 모두
  본다. 표시가 "NONE"이 아니거나 이유가 비어 있으면 조립을 거부한다.
- 플랫폼 개요 화면(스타터 화면)의 계약 절에 "런타임 검증을 생략한 계약"
  표를 둔다. 목록이 비면 그리지 않는다.

버린 대안
- (B) 공유 어댑터만: 검증 생략이 여전히 보이지 않는다.
- (D) 브랜드 타입으로 zodValidator가 만든 검증기만 받기: 외부 패키지의
  자체 검증기까지 막아 §4 설계와 충돌한다.

위험·한계
- 표시 없이 손으로 쓴 통과 검증기(리뷰 실험 L5)는 여전히 조립을
  통과하고 목록에도 없다. 이 변경은 생략을 막지 않는다. 이름 있는 길을
  만들어 그 길로 생략한 것만 드러낸다.
- 공개 계약 추가: RuntimeValidator에 선택 필드 2개,
  ComposedContractContributions에 필드 1개, 새 export zodValidator·
  unvalidatedPayload·UnvalidatedPayloadEntry. 기존 호출자는 바뀌지 않는다.
  ComposedContractContributions를 손으로 만드는 코드는 새 필드를 채워야
  한다(repo 안에는 없다).
- 초기 JS gzip 204,586 → 204,745 B(+159). 예산 204,800까지 55 B 남는다.
  플랫폼 개요 청크 4,625 → 4,750 B.
- 참조 기능은 모든 검증기가 검증하므로 화면 모양은 그대로다. 시각 회귀는
  돌리지 않았다.
- tests/unit/second-api-feature-registries.test.ts의 V2 codec 통과 검증기는
  그대로 둔다(16-01이 그 파일을 넓힌다).

검증
- RED(수정 전): zod-validator.test.ts "Cannot find module
  '../../src/contracts/zod-validator.ts'", external-contract-runtime.test.ts와
  starter-platform-overview-page.test.tsx "unvalidatedPayload is not a
  function". 3파일 모두 실패.
- GREEN: 같은 3파일 33건 통과.
- 회귀: tests/unit·contract·component·runtime-schema·features·platform
  268파일 3,189건, tests/integration 12파일 158건(pnpm을 띄우는
  security-followup-archive 제외), tests/architecture 7파일 33건 통과.
  tsc app·node·test·recipes·web-worker·service-worker 오류 0. 바꾼 파일
  eslint 0. check-registries PASS(compatibility=none), verify-documentation
  PASS_SCOPED, check-adapter-inventory PASS. 아키텍처 그래프 검사(pnpm 대신
  exec stub) 383 모듈 PASS.
- 참조 기능 삭제 모의: scripts/test-sample-removal.ts의 삭제 목록(기능
  폴더, tests/features, reference-context, SAMPLE_EXTRAS)을 복사본에 적용.
  src/contracts/zod-validator.ts가 남고, tsc app·test 오류 0, 어댑터·조립·
  플랫폼 개요·HTTP 시나리오 테스트 4파일 35건 통과.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md 07-03, 5.3
2026-11-03 01:34:32 +09:00
DongHyeonka ee81c448f0 fix(reference): 샘플 링크를 route ID로 만들고 route 입력 cast를 없앤다 (1101/16-04)
문제: 경로 정본은 계약의 `routes[*].path`인데, 샘플 페이지가 같은 경로를
문자열로 8곳에 다시 적는다(목록 2, 상세 1, 폼 3, 상태 1, 실패 행동 1).
route 입력은 `routeInput.search as ReferenceListFilters`와
`String(route.params.resourceId)`로 cast한다. 계약에서 경로만 바꾸면 tsc는
통과하고 링크는 NOT_FOUND로 간다. 문서(routing-pages-and-patterns 4.2절,
10절 4단계)는 codec 기반 builder와 cast 금지를 권하는데, 샘플이 반대
패턴을 보여 주고 복사되는 기능이 그 습관을 가져간다.

고른 방법: 이미 있는 URL builder를 쓴다.
- `buildRouteUrl(routeId, input, featureCodecs)`(`src/presentation/routes/
  route-codecs.ts`)가 route ID로 계약 `path`를 찾고, 라우터가 parse에 쓰는
  같은 codec으로 직렬화한다. canonical redirect도 이 함수를 쓴다.
  `src/platform`에는 URL builder가 없다. 그래서 플랫폼에 새 공개 헬퍼를
  더하지 않았다.
- 기능 쪽 helper는 `presentation/reference-routes.ts`에 둔다.
  - `referenceRouteUrl(routeId, input)`: `buildRouteUrl`에 이 기능의
    codec을 넘기는 한 줄 래퍼다. routeId는 이 기능 계약의 키로 좁힌다.
  - `useReferenceListFilters()`, `useReferenceResourceId()`: 라우터가 이미
    통과시킨 route 입력을 같은 codec으로 다시 parse해서 codec의 출력
    타입을 얻는다. cast가 없다. 목록 필터는 `useMemo`로 묶어 route 입력이
    그대로면 같은 객체를 준다.
- `REFERENCE_FEATURE_ROUTE_CODECS`를 `reference-feature-runtime.ts`에서
  새 `presentation/reference-route-codecs.ts`로 옮겼다.
  - runtime 파일이 페이지를 lazy import하므로, 페이지 쪽이 runtime 파일에서
    codec을 가져오면 순환 의존이 된다.
  - codec 표를 helper 파일에 같이 두지 않은 이유: 그러면
    `context-routes.ts`가 router의 builder·hook까지 끌어와 초기 JS가
    585 B 늘었다(204,809 B로 예산 204,800 B 초과). 분리하면 475 B다.
  - `context-routes.ts`와 `reference-contract.test.ts`는 새 위치에서
    가져온다.
- 페이지 8곳을 route ID 호출로 바꿨다. 기능 presentation에 `"/examples/`
  문자열이 0건, route 입력 cast가 0건이다. 남은 `"/examples/` 4건은 계약의
  `path`(정본)다.
- 기능 README에 helper 위치와 쓰는 법을 적었다.

버린 대안:
- 리뷰 (b)처럼 기능 안에 경로 치환·직렬화를 새로 쓰는 헬퍼: 라우터와 같은
  일을 두 번 구현한다. 플랫폼 builder가 이미 route ID와 기능 codec을 받는다.
- 리뷰 (c)처럼 `buildRouteUrl`의 input 타입을 route ID별로 좁히기: 플랫폼은
  기능 codec 타입을 모른다(15-01 이후 codec은 지연 적재). 라우터 API
  변경이라 이 발견 범위를 넘는다.
- 플랫폼 `useRouteInput`을 제네릭으로 바꿔 타입 단언하기: 런타임 검사 없는
  단언이라 cast를 다른 이름으로 옮길 뿐이다.

위험·한계:
- 목록 링크가 이제 정식 URL(`/examples/reference-resources?limit=20`)을
  가리킨다. 전에는 `?limit` 없는 주소로 갔다가 라우터가 같은 URL로
  replace했다. 도착 URL과 history 항목 수는 같다. 폼의 "목록을 새로
  불러와 확인" 링크 href 기대값을 이 값으로 바꿨다.
- `buildRouteUrl`은 codec이 거절하는 입력에 예외를 던진다. 백엔드가
  공백만 있는 id를 주면(DTO는 `min(1)`, route codec은 trim 후 `min(1)`)
  목록 렌더가 기능 오류 경계로 간다. 전에는 링크가 잘못된 주소 화면으로
  갔다. DTO와 route codec의 id 규칙 차이는 이 변경 전부터 있다.
- route 입력을 한 번 더 parse한다. 값이 작아 비용은 무시할 만하다.
- 초기 JS gzip이 204,224 B에서 204,699 B로 475 B 늘었다(예산 204,800 B,
  여유 576 B → 101 B). 새 코드가 초기 청크에 들어간 것이 아니다.
  `route-codecs.ts`는 원래 초기 청크에 있었다. 페이지가 이 모듈을 import하자
  rolldown이 `boot` 청크에 있던 것을 공유 청크(`route-input`)로 옮기고,
  `route-input`과 `server-state-scope-provider`를 두 청크로 나눴다. 늘어난
  양은 청크 분리 비용이다. 예산 값은 바꾸지 않았다.
- 페이지 테스트의 진입 URL 문자열은 그대로 뒀다. 테스트가 경로를 적는
  것은 이 발견의 완료 기준 밖이다.
- 상태 페이지의 `(state as ReferenceSupportState)`는 history state 처리라
  route 입력 cast가 아니다. 그대로 뒀다.

검증:
- RED(수정 전): 새 `tests/features/reference-feature/
  reference-route-links.test.tsx`는 계약의 네 경로를 모두 옮긴(vi.mock)
  상태로 목록→상세→목록→폼→목록, 목록→지원 페이지→목록을 걷는다.
  2개 모두 실패했다. 상세 링크가 `href=".../items/reference-1"`(기대
  `.../entries/reference-1`), 지원 페이지 대신 NOT_FOUND가 나왔다.
- GREEN(수정 후): 같은 테스트 2개 통과. `tests/features/reference-feature`
  18 files 89 tests 통과(href 기대값 1곳 변경 뒤).
- 회귀: tests/features, tests/component, tests/architecture, tests/scale,
  관련 unit 3개, generator 테스트 81 files 464 tests 통과. 첫 실행에서는
  부하(평균 23~35)로 타임아웃 2건(app-build-input,
  global-local-independence)이 났고, 단독 재실행과 최종 재실행에서 통과했다.
- 초기 JS gzip(`scripts/build-frontend.ts` 후 check-bundle과 같은 분류로
  측정): 수정 전 204,224 B, 수정 후 204,699 B.
- `tsc` app·test·node 통과. 바꾼 파일 `eslint --max-warnings=0` 통과.
- `check-architecture.ts`(pnpm 대신 exec 전용 shim): 381 modules,
  순환·위반 없음, rc=0. `verify-documentation-readiness` PASS_SCOPED,
  `check-i18n` PASS.
- 페이지 테스트 harness(`renderReference`, `inputWith`)는 새 테스트와
  함께 쓰도록 `reference-page-harness.tsx`로 옮겼다. 내용은 그대로다.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md 16-04
2026-11-03 01:34:32 +09:00
DongHyeonka b4ccadab77 feat(design-system): 제품이 싣는 글꼴을 토큰 계약에 선언하게 한다 (1101/12-04)
문제
첫 글꼴 규칙(check:design-system)은 --font-sans의 첫 글꼴이 일반
키워드이거나 검사하는 CSS 안의 @font-face로 실릴 때만 통과시킨다. 글꼴
패키지 import, @import url(…), index.html의 <link>로 싣는 글꼴은 볼 수
없어 실패한다. memento 토큰이 이미 이 규칙에 걸린다. 선언할 곳이 없으니
제품은 템플릿 소유 스크립트를 고치게 된다.

고른 방법
- token-contract.ts에 PRODUCT_LOADED_FONT_FAMILIES(템플릿은 빈 목록)를
  둔다. 제품은 토큰 계약 파일에서 자기가 싣는 글꼴 이름을 적는다.
- firstFontFamilyFailures가 세 번째 인자로 이 목록을 받아 @font-face로
  실은 글꼴과 같이 허용한다. check-design-system.ts가 목록을 넘긴다.
- 실패 메시지에 목록 이름을 넣어 어디에 선언하는지 알린다.
- docs/styling/design-system-platform.md 4.1절 표의 첫 글꼴 행을 고친다.
- 12-04의 (1)~(3)과 (5)는 e714c0d가 했다(deg·음수 색상각, 지원 형식을
  적는 포커스 메시지, -apple-system·BlinkMacSystemFont, 규칙 문서). 이
  커밋은 (4)만 한다.
버린 대안
- 패키지 import·<link>를 찾아 실제로 싣는지 판정: 진입점·CDN·번들러
  설정까지 봐야 해서 규칙이 커진다.
- 목록을 design-system/index.ts로도 내보내기: 앱 코드가 쓰지 않는다.

위험·한계
- 검사는 목록을 믿는다. 글꼴이 실제로 실리는지 보지 않는다. 주석과
  문서에 "모든 화면이 싣는 글꼴만 적는다"고 적었다.
- 실패 메시지 문구가 바뀐다. 문구를 단언하는 곳은
  tests/unit/design-system-rules.test.ts뿐이다.
- 새 공개 이름 PRODUCT_LOADED_FONT_FAMILIES가 생긴다.

검증
- RED: 새 테스트 "passes a family the product declares it loads, and only
  that one"이 실패(expected [ Array(1) ] to deeply equal []).
- GREEN: design-system-rules·oklch-contrast·design-system-contract
  22/22 통과.
- 실제 스크립트 probe: CSS 사본의 --font-sans를 "Pretendard Variable"로
  시작하게 하고 node scripts/check-design-system.ts → 빈 목록이면 새
  메시지로 실패(exit 1), 목록에 넣으면 PASS(exit 0). 저장소 CSS는 PASS.
- tsc(app·node·test), 바꾼 파일 eslint, verify-documentation-readiness
  PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-04
2026-11-03 01:24:31 +09:00
DongHyeonka 6dd4bc1c24 refactor(design-system): primitive를 컴포넌트마다 한 파일로 나눈다 (1101/08-08)
문제
primitive가 종류별 파일 5개(core·forms·overlays·navigation·feedback)에
모여 있다. 번들러는 export가 아니라 모듈 단위로 청크를
나눈다. 그래서 셸이 쓰는 Button·Drawer·Select와 같은 파일에 있는
Tooltip·Menu·Card 같은 갤러리 전용 primitive도 셸과 같은 청크로 간다.
다음 커밋(side effect 없음 선언)이 효과를 내려면 먼저 파일이 나뉘어야
한다.

고른 방법
- primitives/ 아래를 컴포넌트마다 파일 하나로 나눈다(32개). 본문은 원래
  줄을 그대로 옮기고 import만 새로 쓴다. ToastProvider·useToast는 한
  파일, 내부 타입 FieldCopy는 field.tsx에서 내보낸다.
- PaginationLandmarkContext는 pagination-landmark.ts로 따로 둔다.
  page-templates.tsx(StatusPage, 초기 청크)가 이것만 읽는데, Pagination과
  같은 파일이면 Pagination 코드가 초기 청크로 간다.
- design-system/index.ts의 export 이름은 그대로다(값 71개, 타입 36개를
  전후 비교). components/ui/*.ts 재수출, page-templates.tsx,
  common-patterns.tsx는 새 경로를 가리킨다. .dependency-cruiser.json의
  page-templates 예외는 출발 파일 기준이라 그대로 맞다.
버린 대안
- 셸이 쓰는 것과 나머지 두 파일로 나누기: 제품 셸이 Tooltip 하나를
  쓰면 나머지가 다시 초기 청크로 간다.

위험·한계
- 이 커밋만으로는 번들이 바뀌지 않는다. 배럴이 다시 내보내는 모듈은
  side effect가 있다고 보고 모두 초기 청크에 남는다(초기 JS 16개 청크,
  203,818 → 203,824 B). 다음 커밋이 같이 있어야 효과가 난다.
- primitives/ 안의 파일 경로를 직접 import하던 다운스트림 코드는 경로를
  바꿔야 한다. 공개 경계(index.ts)는 그대로다.

검증
- 원래 5개 파일의 import 아래 본문 줄이 새 파일에 빠짐없이 한 번씩
  있다(줄 다중집합 비교).
- tsc(app·node·test) 통과, 바꾼 파일 eslint 통과.
- node scripts/run-vitest.ts run tests/component: 35파일 228/228 통과.
- 빌드(flock): 초기 JS 16개 청크 203,824 B, ui-tooltip 등 갤러리 클래스는
  여전히 초기 청크에 있다(예상대로).

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-08
2026-11-03 01:24:31 +09:00
DongHyeonka 72edb55475 fix(storage): 손상 행을 건너뛰고 끝나지 못한 삭제는 partition을 지운다 (0929/05-01)
문제: OPFS journal의 `listCommittedObjects`·`listIncomplete`는 손상 행
하나에 목록 전체를 `CORRUPT_DATA`로 실패시킨다. 그래서
- 승인된 LOGOUT·ACCOUNT_DELETION purge가 그 partition의 정상 객체까지
  하나도 지우지 못하고, 개인 바이트가 기기에 계속 남는다.
- journal DB는 authority 단위라 손상 행 하나가 모든 partition의
  reconcile과 orphan GC를 멈춘다.
스스로 풀리지 않고, runbook은 journal 수동 삭제를 금지해 출구가 없다.

고른 방법 (리뷰의 (c)):
1. 두 목록은 손상 행을 건너뛰고 `corruptRows`로 센다. 행은 지우지
   않는다. 꽉 찬 페이지는 다음 행 앞에서 멈추므로 한 행은 그 행에 닿은
   페이지에서 한 번만 센다. reconcile은 `corruptTransactions`로 보고하고,
   0이 아니면 `OBJECT_RECONCILE` `DEGRADED` / `CORRUPT_DATA`로 관측한다.
2. LOGOUT·ACCOUNT_DELETION purge가 손상 때문에 끝날 수 없으면(건너뛴
   object 행, 손상으로 `CORRUPT_DATA`가 된 remove나 chunk sweep,
   `STAGING_STATE_UNREADABLE`) partition을 통째로 지운다.
   - 승인: 기존 `maintenanceReasonAllowed` + authority proof 요청·소비를
     통과한 뒤에만 이 지점에 온다. IndexedDB의 database 전체 삭제
     (0929 05-03)와 같은 조건이다.
   - 파일: 새 worker 요청 `REMOVE_PARTITION`이 origin mutation lease를
     쥔 채 `authorities/<a>/<ns>/<p>`를 지운다.
   - 행: 새 journal 메서드 `removePartition`이 그 partition 키로 시작하는
     object·journal·chunk reference 행과 budget 행을 키로 찾아 지운다.
     손상 행도 지워진다. scope binding 행은 남긴다.
   - 보고: `partitionDeleted: true`, `corruptObjects`,
     `moreObjectsAvailable: false`. 파일을 먼저, 행을 나중에 지워서 중간에
     실패해도 다시 부르면 이어서 끝난다.
버린 대안:
- 현상 유지: 손상이 있으면 삭제가 영구히 실패한다.
- 1만: reconcile·GC와 정상 객체 purge는 돌지만 손상 행의 바이트가 남는다.
- journal DB 전체 삭제: 같은 authority의 다른 partition까지 지운다.
기존 테스트 주석("손상 행이 목록 전체를 실패시키는 것이 의도")과
runbook(`browser-file-storage-recovery.md`)을 새 동작에 맞게 고쳤다.

위험·한계:
- 공개 계약 변경. `OpfsJournalPort`에 `removePartition`, 두 page 타입에
  `corruptRows`가 필수로 생겼다. journal이나 worker gateway를 직접 구현한
  쪽은 추가해야 한다(adapter가 생성 시점에 TypeError로 알린다).
  report에는 `corruptTransactions`(필수)와 `corruptObjects`·
  `partitionDeleted`(선택)가 생겼다.
- lease는 put의 BEGIN~FINISH만 막는다. 그 밖에 있던 다른 tab의 같은
  partition put은 journal 행이 지워져 다음 journal 단계에서 실패할
  것으로 보지만, 이 경합은 실행으로 확인하지 않았다.
- partition 삭제는 IndexedDB 전체 삭제처럼 시간 예산에 묶이지 않는다.
- reconcile GC의 `isChunkReferenced` 손상(리뷰 근거 ③)과 reconcile 쪽
  `STAGING_STATE_UNREADABLE`(④)은 이번 결정 범위 밖이다. purge에서만
  partition 삭제로 빠져나간다.
- offline-indexeddb 레시피 gzip: 36,889 → 37,327 B (한도 36,900, 427 B
  초과). 예산은 올리지 않았다.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.

검증:
- RED (수정 전): journal 4건 실패 — `listIncomplete`·
  `listCommittedObjects`가 `CORRUPT_DATA`, `removePartition is not a
  function`. adapter·worker 4건 실패 — LOGOUT·ACCOUNT_DELETION purge가
  `CORRUPT_DATA`, reconcile이 `CORRUPT_DATA`, `REMOVE_PARTITION` 뒤에도
  디렉터리가 남음. 승인 거절 테스트는 수정 전후 모두 통과(가드).
- GREEN: `node scripts/run-vitest.ts run tests/unit tests/recipes`
  177 files 2,523건 통과, `tests/contract` 41건 통과.
  `tsc` app·test·node·web-worker·service-worker·recipes 통과, 바꾼 파일
  eslint 통과, `check-adapter-inventory` 통과.
- 미실행: `check:browser-file-storage-boundaries`(pnpm 필요),
  `check:architecture`(pnpm 필요), Playwright OPFS spec.

Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md 05-01
2026-11-03 01:23:05 +09:00
DongHyeonka c4052f0f8e fix(storage): 여러 페이지를 다 지운 purge를 끝났다고 보고한다 (1101/13.6)
문제: OPFS `enforcePolicies`의 LOGOUT·ACCOUNT_DELETION purge가
journal 목록을 두 페이지 이상 읽으면, 객체를 모두 지워도
`moreObjectsAvailable: true`를 보고하고 chunk sweep을 하지 않는다.
페이지를 넘길 때 `moreObjectsAvailable = page.value.moreAvailable`가
true를 넣고, 마지막 페이지의 `||=`가 그 값을 그대로 둔다. 호출자는
다시 불러야 끝나고, 그 사이 chunk 바이트가 기기에 남는다.

고른 방법: 페이지 넘김 대입을 지운다. 대신 "다음 페이지를 읽기 전에
멈췄다"(객체 한도나 시간 예산 소진)는 루프 머리에서 true로 적는다.
`while` 조건을 루프 안 첫 검사로 옮긴 것이다. 0929/05-02(`85d8b59`)의
"건너뛴 객체가 있으면 true" 규칙은 그대로다. 그 값을 지우는 대입이
없다(마지막 페이지는 `||=`, PRESSURE 대입은 sweep하지 않는 purge).
버린 대안: 건너뜀 표시를 별도 변수로 나누기. 페이지 넘김 true가
남는 한 마지막 페이지에서 여전히 섞여 고쳐지지 않는다.

위험·한계:
- 동봉 IndexedDB journal은 페이지 한도를 "남은 객체 한도"로 받아 꽉 찬
  페이지를 돌려주므로, 한 번의 호출에서 두 번째 페이지가 생기지 않는다.
  결함은 port가 허용하는 짧은 페이지를 돌려주는 journal에서 드러난다.
  테스트도 그 journal(페이지 1개씩)로 재현했다.
- 동작 차이 하나: 앞선 시간 검사를 통과한 직후 첫 페이지를 읽기 전에
  시간이 다 되면, 전에는 `moreObjectsAvailable: false`로 sweep을
  시도했고 이제는 true로 보고하고 sweep하지 않는다. 아무 객체도 읽지
  않았으니 이쪽이 사실에 맞다.
- offline-indexeddb 레시피 gzip: 36,896 → 36,889 B (한도 36,900).

검증:
- RED: 새 테스트 "finishes a purge that walked more than one journal
  page"가 수정 전 `moreObjectsAvailable: true`, `chunkSweep` 없음으로
  실패했다.
- GREEN: `node scripts/run-vitest.ts run tests/unit/opfs-worker-runtime.test.ts
  tests/unit/opfs-byte-store.test.ts tests/unit/indexeddb-opfs-journal.test.ts`
  103건 통과. `tsc` app·test·web-worker 통과, 바꾼 파일 eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/README.md 13.6절
2026-11-03 01:23:05 +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 7b34756355 fix(release): 공개 대상 승인이 예시·테스트용 예약 이름을 거절한다 (1101/13-02)
문제
staging·production 프로필은 `https://api.example.com/`,
`https://telemetry.example.com/v1/events`를 싣고 텔레메트리를 켠다.
공개 대상 승인(FE-GATE-027)은 https와 비공개 호스트만 보므로 프로필을
고치지 않은 production 빌드가 `production ADMITTED`로 통과한다. 모든 API
호출이 실패하고 이벤트는 프로젝트가 소유하지 않은 도메인으로 간다.
CI 계약은 immutable_build의 env를 APP_PROFILE·RELEASE_TARGET로 고정해
RUNTIME_*를 넘길 수 없는데, README 변수 표는 이를 적지 않고 운영 예시는
`api.example.com`을 그대로 쓴다.

고른 방법
- publicEndpointViolations에 예약 이름 거절을 더한다. RFC 2606·6761의
  `example.com`·`example.net`·`example.org`와 그 하위, `.example`,
  `.invalid`, `.test`. 비공개 호스트와 겹치면 비공개 사유 하나만 낸다.
- README 운영 예시의 URL을 `<your-api-origin>/` 같은 빈칸으로 바꾼다.
- README 변수 표와 본문에 CI에서 endpoint를 바꾸는 방법은 프로필 파일을
  커밋하는 것 하나라고 적는다.
- 테스트 fixture의 공개 endpoint를 예약되지 않은 이름으로 바꾸고, 프로필을
  고치지 않은 빌드는 두 위반, endpoint를 준 빌드는 승인되는 것을 고정한다.

버린 대안
- 프로필 기본값을 비워 스키마가 빌드를 막게 하기: 더 확실하지만 프로필이
  예시로 읽히지 않고 네 프로필을 같이 바꿔야 한다. 리뷰 대안 비교에서 승인
  규칙 한 곳이 더 작다고 봤다.
- 리뷰 13-02 (3)의 괄호("13-01 배포 슬롯에 RUNTIME_* 허용 목록")는 하지
  않았다. RUNTIME_*는 빌드 때 쓰이는 값이고, 슬롯은 승격 뒤 배포 job이라
  거기서 넘겨도 이미 만든 후보에 닿지 않는다.

위험·한계
- 템플릿을 그대로 쓰는 프로젝트(이 repo 포함)가 APP_PROFILE=production으로
  immutable_build를 돌리면 FE-GATE-027이 새로 실패한다(의도).
- `*.test` 같은 이름을 실제 운영 endpoint로 쓰는 프로젝트는 없다고 본다.

검증
- RED: node scripts/run-vitest.ts run tests/unit/deployment-admission.test.ts
  2 failed / 22 passed. "refuses names reserved for examples and tests"
  (`expected [] to deeply equal [...]`), "refuses a public build from the
  unedited profile on both endpoints"(`staging: expected [] to deeply equal
  [ 'API_BASE_URL', 'TELEMETRY_ENDPOINT' ]`)
- GREEN: 같은 파일 24 passed. feature-override-diagnostics,
  documentation-readiness 포함 29 passed
- 실험 E-A 재실행: APP_PROFILE=production VITE_BUILD_ID=rel-prod-a
  RELEASE_ID=rel-a 빌드 뒤 RELEASE_TARGET=production 승인 rc=1,
  API_BASE_URL·TELEMETRY_ENDPOINT 두 위반으로 거절
- tsc(app, test) 0, eslint 바뀐 파일 0, verify-documentation-readiness
  PASS_SCOPED

Refs: docs/reviews/2026-11-01-maturity-review/13-build-release-supply-chain.md 13-02
2026-11-03 00:56:00 +09:00
DongHyeonka 6c5818faec refactor(contracts): bearer 인증 프로필을 EXTERNAL_BEARER로 바꾼다 (1101/16-03)
문제
유일한 bearer 인증 프로필 이름이 샘플 이름 REFERENCE_EXTERNAL_BEARER다.
세션이 필요한 제품 기능은 지운 샘플의 이름을 계속 쓰거나 템플릿 소유
파일에 프로필을 더해야 한다. 샘플 제거 드릴의 잔여 검사 정규식도 이
이름을 잡지 않아 샘플을 지운 제품에 그대로 남는다. 리뷰 (2) 오류
메시지는 abf3ce5가 했고 (1) 이름 변경이 남았다.

고른 방법 (2026-11-03 결정)
- 프로필 이름을 EXTERNAL_BEARER로 바꿨다. 참조 기능의 V2 operation 3개와
  V3 descriptor 3개, external-session-adapter 주석, 테스트, VD-23 문서를
  새 이름으로 옮겼다.
- 옛 이름은 한 릴리스 동안 REST_AUTH_PROFILES에 별칭 한 줄로 남기고
  JSDoc @deprecated를 붙였다. 레지스트리는 키와 authProfileId가 같아야
  하므로 별칭은 EXTERNAL_BEARER를 펼치고 id만 옛 이름으로 둔 객체다.
  그래서 옛 이름을 적은 다운스트림 operation도 같은 transport·헤더로
  해석된다.
- scripts/scale의 PLATFORM_TOKENS에서 이 이름을 뺐다. 참조 기능에 더는
  "REFERENCE"가 든 프로필 이름이 없어 이름 바꾸기에서 보호할 것이 없다.
- 새 테스트 두 개: 별칭이 id만 빼고 EXTERNAL_BEARER와 같게 설치되는지,
  src에 옛 이름이 별칭 한 줄 외에 없는지(완료 기준).

버린 대안
- 별칭 없이 바로 바꾸기: 옛 이름을 쓰는 다운스트림 기능이 모듈 로드에서
  바로 실패한다. 공개 이름을 깨는 변경은 BREAKING 결정이 있을 때만 한다.
- 조회 시점의 이름 매핑(alias 표): resolve·executor·composition 세 곳이
  매핑을 알아야 한다. 프로필 항목 하나가 더 작다.

위험·한계
- 설치된 프로필이 셋이 된다. 같은 설정이 두 id로 있을 뿐 권한이 넓어지지
  않는다. 별칭은 다음 minor에서 지우고 CHANGELOG [계약] 행을 남긴다.
  그때 "src only on the alias line" 테스트의 기대값을 빈 목록으로 바꾼다.
- 다운스트림 문자열 id("REFERENCE_EXTERNAL_BEARER")에는 @deprecated 표시가
  보이지 않는다. CHANGELOG로 알린다.
- FE-REG-API 행 3개의 authProfileId가 바뀐다. breakingFields가 아니라
  behavior-change이므로 증거 없이 게이트를 통과한다. 기준선 재승인은 이번
  작업 묶음 끝에서 한 번에 한다.
- 초기 JS gzip(초기 청크 파일별 gzip 합) 203,818 → 203,840 B(+22 B). 별칭
  항목이 rest-profiles가 있는 초기 청크에 실린다. 참조 기능 계약은 lazy
  청크라 초기 크기에 영향이 없다.

검증
- RED(수정 전): rest-profile-contract.test.ts 새 사례 2건 실패("expected
  undefined to match object { transport: 'BEARER_HEADER', …(1) }",
  "expected [ …(9) ] to deeply equal [ Array(1) ]").
- GREEN: 같은 파일 10/10 통과. check-registries "11 registries PASS"
  (FE-REG-API authProfileId 3건 behavior-change).
- 회귀: tests/{unit,integration,features,contract,runtime-schema}
  207 파일 2,366건 통과(pnpm·corepack을 띄우는 6개 제외:
  http-scenario-evidence, ci-workflow-generation, lab-performance,
  fixture-node-modules, deployment-admission, security-followup-archive).
  tsc app·test·node rc=0, 바꾼 파일 eslint rc=0. vite build 성공.
- 미실행: check:architecture, test:sample-removal(pnpm 필요), e2e.

Refs: docs/reviews/2026-11-01-maturity-review/16-structure-patterns.md
2026-11-03 00:55:33 +09:00
DongHyeonka 855d22ac1b fix(i18n): 화면 문구 literal 검사를 ESLint 선택자로 옮긴다 (0929/08-02)
문제: `check:i18n`은 화면 파일 전체에 `/[가-힣]/`를 돌린다. 한국어 주석
한 줄에 실패하고, 영어 JSX 문구와 영어 접근성 이름은 통과한다. 샘플
화면에도 영어 literal이 이미 있었다(목록 h1 "Reference feature",
`limit {n}`, 목록 aria-label, 상세 "DetailPage"·"Resource ID"·"Created",
폼·상태 eyebrow). ko-KR 사용자에게 영어 문구와 스크린리더 이름이 섞인다.

고른 방법: (B) 문구 literal 검사를 ESLint `no-restricted-syntax` 선택자로
옮긴다(`eslint.config.ts`의 `screenTextSelectors`).
- 대상: 글자(`\p{L}`)가 든 `JSXText`, 표시·접근성 속성(`aria-label`,
  `aria-description`, `aria-roledescription`, `aria-valuetext`,
  `aria-placeholder`, `title`, `placeholder`, `alt`, `label`)의 문자열
  literal, 그리고 `{"..."}` 형태의 같은 literal. 주석은 AST에 없어 빠진다.
  구두점·숫자만 있는 문구는 통과한다.
- 범위(4.3절 "화면 코드"): 지난 `check:i18n`과 같은 폴더다. 공통 UI
  폴더와 `src/features/*/presentation`. 컴포넌트 갤러리
  `src/presentation/examples`는 지금처럼 뺀다. stories(`*.stories.tsx`)는
  workshop 코드라 뺀다. 테스트는 이 폴더 밖이라 대상이 아니다.
- 이 항목은 일반 `no-restricted-syntax` 목록을 대체하므로 FE-OC-019
  선택자(raw HTML, script 생성)를 함께 싣는다.
- `check:i18n`에는 catalog parity와 raw backend 메시지 검사만 남긴다.
  raw HTML은 원래 전역 FE-OC-019 ESLint 규칙이 거절한다.
- `check:i18n:fixture`는 ESLint Node API로 같은 규칙을 fixture 트리에도
  돌린다. forbidden 파일은 하나하나 거절돼야 하고(아니면 종료 코드 2),
  새 `tests/fixtures/i18n/allowed` 트리(한국어 주석, 구두점, catalog
  문구)는 통과해야 한다(거절되면 종료 코드 2). 게이트 기대값(종료 1,
  "I18n contract failed:")은 그대로다.
- fixture 추가: allowed `korean-comment.tsx`, forbidden
  `english-jsx-text.tsx`, `english-accessible-name.tsx`.
- 샘플의 영어 literal 11곳을 catalog로 옮겼다. 새 키 10개
  (`reference.list.title`·`filterLimit`·`filterTags`·`resources`,
  `reference.detail.eyebrow`·`titlePending`·`resourceId`·`createdAt`,
  `reference.form.eyebrow`, `reference.status.eyebrow`). en-US 값은
  예전 영어 문구 그대로라 en-US 화면은 바뀌지 않는다. ko-KR 화면은 한국어가
  된다.

버린 대안:
- (A) 현 상태: 두 제품이 각각 막히거나 스크립트를 고쳤다.
- (C) "행동·상태 문구"만 정규식으로 고르는 제품 정책: 한국어 문장 목록에
  기대 영어를 못 잡고, 템플릿 기본값으로 쓰기에 제품 특화다.
ESLint 설정은 제품이 자기 규칙으로 덮어쓸 수 있는 자리다(한 locale 제품,
고유명사 허용).

위험·한계:
- 식 안에서 만든 문구는 보지 못한다. template literal, 삼항식, 객체
  prop(`heading.title` 같은 것)이 그렇다. 샘플의 이런 문구는 손으로
  옮겼고, `reference-page.test.tsx`가 ko-KR main 영역을 catalog·데이터
  밖 라틴 문자로 검사해 그 빈 곳을 샘플에서만 막는다.
- 고유명사·브랜드 이름도 걸린다. 제품이 선택자를 덮어쓰거나 그 줄에
  `eslint-disable-next-line`을 쓴다.
- ko-KR route 제목(`route.REFERENCE_RESOURCE_*`)은 catalog 안의 영어라
  그대로 뒀다(라우트 제목 정리는 0929/08-06 몫).
- `tests/e2e/reference-form.spec.ts`의 ko-KR 목록 h1 기대값을 "참조
  기능"으로 바꿨다. e2e는 이 worktree에서 돌리지 않았다(webServer가
  pnpm build를 부른다).
- 시각 골든(`tests/visual`)은 /examples/ui·states·platform만 찍는다.
  샘플 화면과 nav 문구는 바뀌지 않아 골든 영향이 없다고 본다(미실행).

검증:
- RED(수정 전):
  - E1 한글 주석 변이: `node scripts/check-i18n.ts` -> "hardcoded common
    user-facing locale literal in .../reference-resource-status-page.tsx",
    exit 1
  - E1b 영어 JSX 문구 변이: `check-i18n.ts` PASS exit 0, `eslint` exit 0
  - `check-i18n.ts --fixture` -> "I18n fixture was not rejected:
    english-accessible-name.tsx, english-jsx-text.tsx", exit 2
  - 새 ko-KR main 테스트: "limit 5 · tags ..." 가 남아 실패
- GREEN(수정 후):
  - E1 변이: `check-i18n.ts` PASS, `eslint` exit 0
  - E1b 변이: `eslint` -> 42:13 no-restricted-syntax, exit 1
  - `check-i18n.ts` PASS(224 keys), `--fixture` -> forbidden 7개 모두
    거절, "I18n contract failed:", exit 1. allowed에 영어 문구를 넣으면
    "I18n allowed fixture was rejected", exit 2
  - ko-KR main 테스트 통과
- `npx eslint src scripts tests recipes .storybook ... --max-warnings=0`
  통과, app·test·node 타입 검사 통과
- vitest: tests/unit + tests/component 209 files 2725 tests,
  tests/features 등 25 files 141 tests 통과
- `check-registries.ts` PASS, `check-ci-contract.ts` PASS,
  `verify-documentation-readiness.ts` PASS_SCOPED

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-02, 4.3
2026-11-03 00:54:18 +09:00
DongHyeonka ff33d58e95 feat(i18n): 문구 보간 파라미터를 catalog의 {이름}에서 만든다 (0929/08-03)
문제: 보간 파라미터 타입이 플랫폼 파일의 닫힌 목록 `MessageParameters`에만
있다. 목록에 없는 기능 키는 `[parameters?: never]`가 된다. 그래서
`formatMessage("ko-KR", "reference.list.resultCount")`는 타입 검사를
통과하고 실행하면 대체 문구를 돌려주며, `{ count: 1 }`을 넣으면 TS2345로
거절된다. 샘플은 타입 없는 `resolveMessage`로 우회했고, tech-log는 템플릿
파일에 키 11개를 넣었다.

고른 방법: (B) catalog가 `as const`이므로 ko-KR 문자열 literal의
`{이름}`에서 `MessageArguments<Key>`를 만든다. 값 타입은
`string | number`다. 값 타입을 좁히고 싶은 키만 `MessageParameters`로
덮어쓴다. 덮어쓰기는 catalog 파라미터와 교집합이라 좁히기만 한다. 덮어쓴
항목이 catalog 문자열과 어긋나도 catalog의 자리표시자는 계속 필수다.
`ParameterlessMessageKey`도 "자리표시자가 없는 키"로 같은 규칙에서
만든다. 기존 덮어쓰기 8개는 값 타입을 좁히므로 그대로 둔다.
새 개념이 없고, 기능이 템플릿 파일을 고치지 않는다.

버린 대안: (C) 기능 모듈이 파라미터 타입을 따로 선언하고 설치 조립이
교집합을 만든다. 값 타입을 정확히 쓸 수 있지만 catalog와 선언을 따로
맞춰야 한다.

위험·한계:
- 값 타입이 `string | number`로 넓다. 좁히려면 `MessageParameters`에
  덮어쓴다.
- 자리표시자는 ko-KR 문자열에서 읽는다. 다른 locale과의 일치는
  `tests/unit/i18n-contract.test.ts`의 parity 검사가 지킨다.
- ICU 복수형·select처럼 `{이름}`으로 표현하지 못하는 문구는 다루지
  않는다(VD-06 재검토 조건).
- 타입 검사 비용(`tsc -p tsconfig.app.json --extendedDiagnostics`):
  Types 287,440 -> 289,911(+0.9%), Instantiations 721,217 -> 748,663
  (+3.8%). 실행 시간은 load average 9~21에서 전·후 모두 1.0~2.6초로
  흔들려 차이를 구분할 수 없었다.
- 기능 키 검사(`tests/features/reference-feature/feature-module.test.ts`)는
  샘플과 함께 지워지도록 샘플 테스트 폴더에 두었다. 플랫폼 fixture는
  샘플 키에 기대지 않는다.

검증:
- RED: `npx tsc -p tsconfig.test.json --noEmit`
  feature-module.test.ts(23,5): error TS2578: Unused '@ts-expect-error'
  feature-module.test.ts(26,60): error TS2345: Argument of type
  '{ count: number; }' is not assignable to parameter of type 'undefined'.
- GREEN: 같은 명령 오류 0. app·node·recipes 타입 검사 통과.
- `check:types:fixture:i18n-params` fixture: 기존 3줄은 TS2554/TS2345로
  계속 실패하고, 더한 덮어쓰기 좁힘 줄은 TS2322로 실패한다.
- vitest: tests/features/reference-feature, i18n-contract,
  locale-platform 19 files 97 tests 통과.
- 샘플 목록 화면이 타입 있는 `message()`로 결과 수를 그린다.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-03
2026-11-03 00:54:18 +09:00
DongHyeonka d6e4e51688 fix(contexts): 계약에 없는 라우트 핸들을 라우트 적재 때 막는다 (09-06)
문제: context gateway는 적재한 라우트의 handle `routeId`가 가리키는
등록 라우트를 그린다. `context-routes.ts`가 기능 계약에 없는 route id를
handle에 실으면(오타, 계약에서 지운 라우트) 적재는 성공하고, 그 URL을
그릴 때 context 경계 실패 화면이 된다. 7139c7c가 리뷰의 (1)(2)를 했고
(3) "핸들의 route id가 레지스트리에 있는가"는 설계 선택으로 남겼다.

고른 방법: 적재 때 검사한다. `defineBoundedContextModule`이
`route.loadRoutes`를 감싸, 적재한 각 라우트의 handle `routeId`가 그
context 기능들의 계약 라우트 id에 없으면 TypeError로 실패한다. 메시지에
route id, context id, 기능 id를 담는다. handle에 `routeId`가 없어도
실패한다(gateway는 그 라우트를 NOT_FOUND로 그린다).
- 모든 context가 이 함수를 거치므로(생성된 product-context-index) 모든
  context에 걸린다. 모든 context의 라우트를 적재하는 기존 단위 테스트
  (tests/unit/route-runtime.test.ts)가 개발 단계에서 잡는다.
- 적재 실패는 09-09(de48db2)의 "청크 누락이 아닌 적재 실패" 경로로
  context 경계에 가서 `ui.render.failed` 진단을 남긴다. 테스트로 확인했다.
- 라우트는 계속 늦게 읽는다. context를 정의할 때는 loadRoutes를 부르지
  않는다.
- 7139c7c의 `contractRoutePaths`를 bounded-context-module.ts로 옮겨
  앱 모듈과 같이 쓴다. "계약 라우트"의 정의가 한 곳에 남는다.
- starter-experience.md 기능 추가 3단계에 규칙을 적었다.

버린 대안:
- 헬퍼로 제공: 그 헬퍼를 쓰는 context만 지킨다. 안 쓰면 그만이다.
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 handle을 모른다.

위험·한계:
- 생성된 index는 기능별 라우트를 합쳐서 돌려주므로, 어느 기능의
  `context-routes.ts`가 잘못된 handle을 냈는지는 알 수 없다. 메시지는
  그 context의 기능 id 전부를 적는다. 기능이 하나인 context(지금
  reference)는 정확하다.
- 최상위 라우트만 본다. 지금 context 라우트는 평평하다. children을 쓰는
  context가 생기면 재귀가 필요하다.
- `defineBoundedContextModule`을 거치지 않고 손으로 만든 context 객체는
  검사되지 않는다. 그 경우는 기존처럼 렌더 때 context 경계가 잡는다.
- 등록 라우트가 없는 URL에서 난 적재 실패는 진단 route_id가 NOT_FOUND다.
  레지스트리의 NOT_FOUND splat이 모든 URL에 맞아 gateway의
  `?? routeModule.id` 대체가 쓰이지 않는다. 09-09의 동작이고 고치지 않았다.
- 초기 JS gzip +141 B(203,818 -> 203,959 B, 여유 982 -> 841 B).
  같은 worktree에서 `vite build` 두 번으로 쟀다.

검증:
- RED: tests/architecture/context-route-roots.test.ts 새 3건 중 거절
  2건이 "promise resolved ... instead of rejecting"으로 실패(10건 중 2
  실패). tests/component/context-boundary-diagnostics.test.tsx 새 1건이
  route_id "FIXTURE_ITEMSS"(렌더 때 경계)로 실패.
- GREEN: 두 파일 10건, 4건 통과.
- 회귀: tests/{architecture,unit,features,platform,component,contract,
  runtime-schema,integration,scripts,scale}(pnpm을 띄우는 4개 제외)
  296 files 중 3,383 통과, 1건 실패. 실패는 telemetry-storm.test.ts의
  10초 timeout(부하 34)이고 단독 재실행에서 4건 통과했다.
  check-registries, check-adapter-inventory 통과.
- tsc app·test·node 통과. 바꾼 파일 eslint 통과.
  verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm이 필요해 돌리지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-06
2026-11-03 00:53:27 +09:00
DongHyeonka 1196b86426 fix(realtime): stream 마감 실패를 13.1의 kind로 보고한다 (04-02)
문제: stream coordinator는 effect 마감 초과를 IDLE_TIMEOUT/APPLY로,
recovery 마감 초과를 IDLE_TIMEOUT/RECOVER로, close drain 초과를
IDLE_TIMEOUT/CLOSE로 보고한다. 설계 13.1에서 IDLE_TIMEOUT은 전송
idle(heartbeat/byte deadline -> close + bounded reconnect)이다. reconnect
관측(RUN_ENDED failureKind)에는 operation이 없어서 운영에서 "서버가
조용해짐"과 "우리 effect가 멈춤"을 failureKind로 나눌 수 없다.
5b3f5b0은 13.1에 두 뜻을 적기만 했다(리뷰의 (b)).

고른 방법: 리뷰의 (a). kind만 바꾸고 retryable:false, DRAINING 유지,
resume token 폐기는 그대로 둔다.
- effect 마감: APPLY_FAILED/APPLY. 13.1의 "feature effect 실패"이고,
  WebSocket 연결도 자기 apply 마감을 APPLY_FAILED로 보고한다.
- recovery 마감: PROVIDER_UNAVAILABLE/RECOVER. recovery source가 제때
  답하지 않은 것이다. recovery가 throw한 경우와 같은 kind다.
- close drain 마감: PROVIDER_UNAVAILABLE/CLOSE. reconnect coordinator가
  drain 상한 초과를 PROVIDER_UNAVAILABLE로 보고하는 것과 맞춘다.
- 관측 reason도 같은 kind로 바꾼다.
- 13.1 표는 IDLE_TIMEOUT 행에서 stream coordinator 설명을 빼고,
  APPLY_FAILED·PROVIDER_UNAVAILABLE 행에 마감 경우를 적는다.
  VD-28의 같은 설명도 고친다.
이 템플릿으로 운영 중인 제품이 아직 없어서 관측 값을 바꾸는 비용이
지금 가장 작다.

버린 대안: (b) 문서만 고친다. 5b3f5b0이 한 것이고, 관측에서는 여전히
구분되지 않는다. close 마감에 CLOSED를 쓰는 것도 버렸다. 아직
DRAINING인데 "닫힘"으로 읽힌다.

위험·한계:
- 공개로 관측되는 값이 바뀐다. stream coordinator 결과의 kind와
  RealtimeObservation.reason에서 IDLE_TIMEOUT을 보던 조합 코드는
  APPLY_FAILED/PROVIDER_UNAVAILABLE을 봐야 한다. repo 안에 그런
  소비자는 없다.
- live-poll handoff coordinator의 quiescence·checkpoint·close 마감은
  여전히 IDLE_TIMEOUT이다. 결정 범위(stream coordinator)를 지켰다.
  13.1 IDLE_TIMEOUT 행에 handoff 마감만 남겨 적었다.
- realtime 레시피 번들 gzip이 40,897 B에서 40,902 B로 늘어 예산
  40,900 B를 2 B 넘는다. "PROVIDER_UNAVAILABLE"이 "IDLE_TIMEOUT"보다
  8자 길어 3곳에서 원본이 24 B 늘었다. 예산은 올리지 않았다.
  check-optional-recipes가 REFERENCE_RUNTIME_BUNDLE_BUDGET_EXCEEDED로
  실패한다.

검증:
- RED: 기대값을 먼저 바꾸고 stream-coordinator.test.ts 실행 ->
  7 failed | 31 passed. 예: expected kind APPLY_FAILED, received
  IDLE_TIMEOUT.
- GREEN: tests/unit/realtime 14 files, 230 passed.
- tsc (tsconfig.app.json, tsconfig.test.json) 통과. 바꾼 두 파일 eslint
  통과. verify-documentation-readiness PASS_SCOPED.
- check-optional-recipes: realtime 40902 > 40900 실패(위험 참고).

Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-02
2026-11-03 00:53:27 +09:00
DongHyeonka 1fa5f3e237 fix(query)!: 제품 mutation 훅이 raw 입력을 받지 않게 한다 (1101/08-03)
문제: useApplicationMutation이 BoundMutation과 함께 raw
LegacyMutationOptions({ execute, definitionId })도 공개 overload로
받는다. raw 쓰기는 intent가 없어 Idempotency-Key 없이 나가고, scope
세대 확인과 측정 profile을 건너뛴다. 결과 불명 뒤 resendUnknownEffect()는
null이라 샘플 폼을 복사하면 "같은 요청으로 다시 보내기"를 눌러도 아무
일이 없고 새 제출도 막힌다. tsc·eslint·depcruise 어느 것도 기능 코드의
raw 사용을 막지 않는다.

고른 방법(결정대로):
- 공개 useApplicationMutation에서 raw overload를 뺀다. 남은 공개
  시그니처는 BoundMutation 하나다. 런타임 LEGACY 분기는 그대로 둔다.
- raw로 쓰인 테스트 24곳(3파일)은 tests/helpers/legacy-application-
  query-harness.ts의 useLegacyApplicationMutation으로 옮긴다. harness는
  명시적 cast로만 그 분기에 닿는다. 단언은 한 줄도 바꾸지 않았다.
- 타입 fixture: application-mutation-admission 테스트에 제품 훅에 raw
  입력을 넘기는 @ts-expect-error를 둔다. raw overload가 돌아오면
  tsconfig.test.json 검사가 TS2578로 실패한다.
- raw query({ queryKey, execute })는 남긴다. 먼저 확인했다: raw query는
  세션이 바뀐 뒤 이전 사용자의 결과를 보이지 않는다. FENCED에서
  ServerStateScopeProvider가 하위 트리를 내리고, READY는 이전
  QueryClient를 비우고 세대 key로 새 QueryClient를 붙인 뒤에 온다. 늦게
  온 이전 응답은 버려진 client에 쓰인다. 이 동작을
  server-state-generation-provider 테스트로 고정했고, 생성 저장소가 같은
  client를 비우지 않고 다시 쓰게 바꾸면 이 테스트가 실패한다(변이 확인).
  시그니처 JSDoc에 "scope·측정 profile 없이 도는 읽기 경로"와 provider
  밖에서는 훅이 막지 않는다는 위험을 적었다.
- typescript-state-and-data-flow.md 4.3의 raw 예시를 bound 정의로 바꾼다.
버린 대안: raw query까지 제거 — 다운스트림 memento의 raw query 12곳이
깨지는데 읽기는 다시 보내도 부작용이 없어 얻는 안전이 작다. 현상 유지 —
쓰기 경로의 중복 생성과 동작하지 않는 재전송이 남는다. 런타임 LEGACY
분기 제거 — legacy 전용 테스트 4건의 단언이 바뀌어 "같은 단언 유지"를
못 지킨다. 별도 tests/fixtures/typecheck + CI 명령 — package.json,
gates.json, contract-baseline.json, 명령 수를 고정한 테스트까지 바꾸고
다른 수정과 baseline 해시가 충돌한다. 같은 tsc 검사를 기존
check:types:test 게이트가 돈다.

위험·한계: 공개 계약 변경(BREAKING). 런타임에는 raw 분기가 남아 cast로
여전히 닿는다(타입으로만 막음). LegacyMutationOptions 타입은 harness가
쓰도록 application-query.ts에서 export한다(배럴에는 없음). raw query는
ServerStateGenerationProvider 밖에서 쓰면 세션 보호가 없다.

검증:
- RED: 원래 훅(raw overload 있음)으로 tsc -p tsconfig.test.json →
  "error TS2578: Unused '@ts-expect-error' directive."
- GREEN: tsc app·test·node 통과. tests/component 35 files 229 tests
  통과(옮긴 테스트 포함). tests/unit·component·features·contract·
  runtime-schema·architecture·scripts·integration(security-followup-
  archive 제외, pnpm 사용) 256 files 중 3 files 4 tests가 부하(load
  avg 32)에서 실패했고 세 파일을 3회 다시 돌려 모두 통과(78/78). eslint
  (바꾼 파일) 통과.
- 다운스트림(읽기만): memento 10곳, tech-log 34곳 모두 bound. 깨지는
  제품 호출 0곳. 두 repo의 tests/component 템플릿 소유 테스트 3파일은
  raw 호출이 있어 harness와 함께 동기화해야 한다.

BREAKING CHANGE: useApplicationMutation이 raw { execute, definitionId }
입력을 받지 않는다. BoundMutation(definitionId, definitionVersion,
operationId, requiresIdempotencyKey, owner, duplicatePolicy, scope,
invalidate, execute(input, { signal, intent }))을 넘긴다. scope는
useServerStateScope()에서 얻는다.
Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-03
2026-11-03 00:53:16 +09:00
DongHyeonka 849d000342 fix(http): 결과 불명 쓰기에 보낸 요청 id를 지원 참조로 싣는다 (0929/03-04)
문제: 바인딩은 서버가 돌려준 x-correlation-id만 AppFailure.requestId로
싣는다. 마감 초과·연결 끊김(TRANSPORT_FAILURE)과 취소에는 응답이 없고,
헤더를 노출하지 않는 서버·게이트웨이의 504에도 반사값이 없다. 실행기는
보낸 id를 알지만 observation(기본 sink 없는 메모리 diagnostics)에만
넣었다. 그래서 e54fbf2(0929/08-04)가 결과 불명 화면에 더한 "지원 참조"
줄이 가장 흔한 결과 불명 경우(마감 초과)에 비어 있었다. 요청은 id를
싣고 서버 로그에 남는데도 지원 담당은 시각·사용자로 찾아야 했다.

고른 방법: 리뷰의 최소 개선 방향 ①을 한다. ②(화면)는 e54fbf2가 이미
했다.
- V3 실행 결과(HttpExecutionOutcome)의 모든 가지에 선택 필드
  sentRequestId를 더한다. finish()가 요청에 넣은 x-correlation-id를
  싣는다. observation의 correlationId와 같은 값이다.
- 바인딩은 반사값이 없으면 sentRequestId를 requestId로 쓴다.
- 런북 5.2-6과 백엔드 계약 5절에 "반사값이 없으면 보낸 값" 한 줄씩.
버린 대안: metadata 없는 가지에만 필드 두기 — 반사 헤더 없는 504는
metadata가 있어 빠진다. 바인딩이 id를 만들어 실행기에 넘기기 — 실행기가
이미 id를 만들고 재시도에 공유하므로 생성 지점이 둘이 된다.

위험·한계: 공개 결과 타입에 선택 필드 하나가 붙는다(추가만). 요청을
조립하기 전에 끝난 실패(자격 증명 없음, 입력 거절)와 id 생성 실패(보안
컨텍스트 아님)에는 값이 없다. 서버가 id를 바꿔 쓰면 반사값을 우선하므로
두 값이 다를 수 있다. telemetry에는 넣지 않는다(VD-07). 초기 JS gzip은
이 커밋 단독으로 재지 않았다(두 커밋 뒤 함께 잼).

검증:
- RED: reference-production-vertical에 새 테스트. REQUEST_TIMEOUT_MS
  200, MSW가 abort까지 응답하지 않는다. 수정 전 "변경 결과를 확인할 수
  없습니다."는 보이지만 "Unable to find an element with the text: 지원
  참조: 29d7f444-…"로 실패.
- GREEN: 같은 테스트 통과(화면 식별자 = 요청 헤더 x-correlation-id).
  tests/features·unit·integration·component 242 files 2975 tests,
  tests/contract·runtime-schema·architecture 13 files 109 tests 통과.
  tsc app·test, eslint(바꾼 파일), verify-documentation-readiness,
  check-adapter-inventory, check-registries 통과.

Refs: docs/reviews/2026-09-29-maturity-review/03-adapters-http-state.md 03-04
2026-11-03 00:53:16 +09:00
DongHyeonka c5f87aaef5 fix(browser-transfer): part 발급 401/403을 NONE으로 낸다 (0929/01-01)
문제: part 발급(BFF)이 401/403으로 거절하면 upload()가
{PERMISSION_DENIED, UPLOAD_PART, retryable:false, RESUME}을 돌려준다.
세션 만료나 권한 회수라서 재인증 전에는 다시 불러도 같은 거절이다.
그런데 RESUME을 믿는 화면은 "다시 시도"를 띄우고, 다시 부르면 파일
전체를 재해시한 뒤 같은 거절을 받는다. 지난 수정(9142390)은 이 경로를
남겼다. object store PUT 403과 code·단계·recovery가 모두 같아서
toUploadAction 한 곳에서 가를 수 없었다.

고른 방법: 실패의 출처를 아는 곳에서 표시한다. runtime의
uploadPartWithRetry 발급 분기만 그 실패가 BFF 발급에서 왔다는 것을
안다. 그 분기에서 PERMISSION_DENIED를 {retryable:false, NONE}으로
만든다. 표시는 별도 필드 대신 기존 recovery 값(NONE)이다. 번역
(toUploadAction)은 NONE을 그대로 두고 retryable:false를 강제한다. 공개
타입은 바뀌지 않는다. 발급 분기는 모든 control plane 구현이 지나는
곳이라 http-control-plane-adapter 말고 다른 구현에도 같은 답이 나온다.
PUT 403은 그대로 RESUME이다. 서명 만료가 보통 원인이고 다음 시도가 새
capability를 받는다(지난 수정의 보존 조건).

버린 대안:
- 백엔드가 code를 나눈다: 두 repo 계약이 바뀌고 다른 백엔드에도 기대야
  한다.
- code만 보고 번역에서 추측한다: 두 출처의 code가 같아 불가능하다.
  PERMISSION_DENIED를 모두 NONE으로 하면 PUT 403 테스트 2건이 깨진다.
- 실패의 stage(operation) union에 발급 값을 더한다: 공개 타입 변경이라
  [계약]이다. 같은 일을 기존 값으로 할 수 있다.
- 내부 표시 필드나 WeakSet: 발급 분기와 번역 사이에서 실패는 공개
  BrowserDataFailure로 오간다. 필드를 실으려면 타입 단언이 필요하고,
  WeakSet은 객체 동일성에 기대는 숨은 결합이다. 중간에 실패를 다시
  만들면 말없이 표시가 사라진다.
- control plane adapter에서 바꾼다: 다른 control plane 구현은 여전히
  RESUME을 낸다.

위험·한계:
- BFF 발급 401/403의 recovery가 RESUME → NONE으로 바뀐다. 다운스트림
  화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이 필요하다.
- control plane이 발급 거절을 retryable:true로 줘도 이제 재시도하지
  않는다. 재인증 전에는 결과가 같기 때문이다.
- 재인증 자체는 앱 세션 계층 몫이라 다루지 않았다.
- 실제 BFF·object store가 아니라 fetch 가짜 서버로 확인했다.
- file-transfer 레시피 번들 56,031 → 56,053 gzip B(예산 56,100).

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 3건 중
  BFF 발급 401·403 2건 실패(recovery 기대 NONE, 실제 RESUME). PUT 403
  1건은 수정 전에도 RESUME으로 통과(보존 조건 고정).
- GREEN: 같은 파일 37건 통과. 세 경로 모두 retryable:false를 단언한다.
- 변이: 번역에 "PERMISSION_DENIED → NONE"을 넣으면 PUT 403 2건(새
  테스트, 기존 01-05 표 테스트)이 실패한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
  image-cdn 단위 20파일 329건 통과. tsc app·test·recipes 통과. 바꾼
  파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
  check-optional-recipes(source) file-transfer 56053/56100.
- 미실행: check:architecture(pnpm 필요).

Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
2026-11-03 00:36:28 +09:00
DongHyeonka e4ace51099 fix(features): 기능이 하나도 없을 때도 타입 검사와 커버리지가 통과하게 한다 (15-01)
문제: 샘플 제거 드릴(test:sample-removal)이 reference feature를 지우면
설치된 기능이 0개가 된다. 15-01 이후 그 상태에서 기능 기여 타입이 never가
되어 installed-feature-adapters.ts와 테스트 2개가 타입 검사에서 실패했다.
features.load는 기능 테스트로만 검증되고 있어서, 기능 테스트가 같이
지워지면 create-application.ts 커버리지가 90% 아래로 떨어졌다. 드릴 사본에
README.md·CHANGELOG.md가 없어 문서 테스트 2개도 실패했다.

방법: never일 때도 통과하는 넓은 타입으로 받아서 읽는다(as 단언 없이 대입).
features.load는 가짜 로더로 플랫폼 테스트를 추가했다(한 번만 적재, 남의
input 거부, 실패 후 재시도). 문서 테스트 2개는 드릴 제외 목록에 넣었다.
드릴 사본에 문서를 복사하는 안은 버렸다. 기능 제거와 무관한 파일이 사본
목록에 들어간다.

위험: 넓힌 타입은 기여 타입이 바뀌어도 featureId 검사 부분은 잡지 못한다.
그 검사는 실행 시 TypeError로 남아 있다.

검증: tsc -p tsconfig.test.json 통과, check:types 통과, 관련 단위 테스트
20/20 통과. 드릴은 고치기 전 실행에서 coverage PASS를 확인했고 타입 오류
2건이 남아 있었다. 그 2건을 고친 뒤 드릴 전체는 다시 돌리지 않았다.
2026-11-01 23:44:29 +09:00
DongHyeonka e54fbf2014 feat(presentation): 폼 저장 실패와 결과 불명 화면에 지원 참조를 보인다 (0929/08-04)
문제: 조회 실패는 failure.requestId를 "지원 참조"로 보이는데, 폼의
FormFailureStatus는 넘기지 않았다. 결과 불명 저장은 AsyncSurface의
indicator 분기라 실패 객체가 없고, 폼도 MAYBE_APPLIED 실패를 버렸다.
사용자가 가장 문의하고 싶은 경우에 줄 식별자가 없었다. 샘플의
contact-support 이동은 식별자를 버리고, 상태 페이지는 식별자처럼 보이는
고정 문자열 "REFERENCE-STATUS-DEMO"를 보였다.

고른 방법: 리뷰의 최소 개선 방향(기대 계약 고정)대로 했다.
- FormFailureStatus가 supportReference={failure.requestId}를 넘긴다.
- useAppForm이 MAYBE_APPLIED 실패도 보관하고 supportReference(현재
  보이는 상태 실패 또는 결과 불명 저장의 requestId)를 돌려준다. failure는
  여전히 상태 결과에만 값이 있어 FormFailureStatus가 결과 불명을 두 번
  그리지 않는다.
- AsyncSurface가 supportReference prop을 받아 결과 불명 indicator에서만
  보인다. 샘플 폼 페이지가 form.supportReference를 넘긴다.
- 샘플 contact-support 이동은 식별자를 history state로 넘기고(URL에
  넣지 않음), 상태 페이지는 받은 문자열만 보이고 없으면 줄을 숨긴다.
공개 API는 추가만 했다(useAppForm 반환 필드, AsyncSurface prop).
버린 대안: 결과 불명 식별자를 mutation 채널(application-query.ts)에
두기 — 재마운트 뒤에도 남지만 925줄 파일의 채널 구조를 바꾸고 08-03
(raw 경로 정리)과 겹친다.

위험·한계: 폼이 재마운트되면 결과 불명 배너는 mutation 채널에서
남지만 식별자는 사라진다(제출 값과 같은 수명). 서버가
x-correlation-id를 노출하지 않으면 식별자가 없다(0929 FOLLOW-UP 03-03).
결과 불명 화면에 줄 하나가 생긴다. 초기 JS는 이번 브랜치 전체 기준
202,520 → 202,631 B(예산 204,800 B).

검증:
- RED: 새 테스트 6건이 수정 전 실패(form-foundation 2, async-surface 1,
  reference-page 3. 예: "Unable to find an element with the text: 지원
  참조: corr-save-500"). 새 e2e가 이전 빌드에서 실패(getByText('지원 참조:
  corr-save-500') not found).
- GREEN: 관련 3파일 70/70, tests/component·features·architecture
  59 files 336 tests 통과. e2e reference-save·reference-form·
  reference-route chromium·firefox·webkit 42/42. tsc app·test, eslint,
  check-i18n, check-design-system 통과.

Refs: docs/reviews/2026-09-29-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:32 +09:00
DongHyeonka ad73e56476 fix(presentation): 예제 화면이 자기 언어를 ko-KR로 밝힌다 (08-07)
문제: LocaleProvider가 <html lang>을 선택한 locale로 바꾸는데, 예제
화면 4개는 의도적으로 catalog 밖이라 본문이 한국어 literal이다.
en-US로 바꾸면 /examples/platform main의 한글 1,013자가 lang="en-US"
아래에 있어 스크린 리더가 영어 규칙으로 읽는다(WCAG 3.1.2).

고른 방법: 리뷰 대안 (B). 예제 화면 루트 section에 lang="ko-KR"을
준다. 예제를 catalog 밖에 둔 결정(VD-06, check-i18n 예외)은 그대로다.
버린 대안: (C) 예제 문구 번역 — 문구 수백 개이고 지울 수 있는 예제다.
예제 안에 중첩 LocaleProvider(ko-KR) — <html lang>을 전역으로 바꾼다.

위험·한계: 예제 안에서 디자인 시스템 컴포넌트가 catalog로 그리는
문구(접근 상태 화면, 오류 문구, 닫기 같은 접근성 이름)는 en-US에서
영어인데 ko-KR 구역 안에 놓인다. 화면 상태 갤러리에 몇 줄 있다. 한국어
본문 전체가 영어 규칙으로 읽히던 것보다 범위가 훨씬 작아 받아들였다.
예제를 번역하기로 하면 (C)로 간다. 눈에 보이는 화면 변화는 없다.

검증:
- RED: i18n.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (Platform composition: lang Expected "ko-KR", Received "").
- GREEN: i18n·accessibility·ui-gallery·platform-overview e2e
  chromium·firefox·webkit 69/69 통과. tests/component 220/220,
  check-i18n PASS, tsc app 통과, eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-07
2026-11-01 23:20:31 +09:00
DongHyeonka dda153b25e feat(presentation): 상태 화면과 오류 요약이 제목 수준을 받는다 (08-05)
문제: EmptySurface, TerminalErrorSurface, 접근 상태 화면, ErrorSummary의
제목이 h2로 고정돼 있다. Card(h3)나 상세 구획(h2) 안에 넣으면 그 안의
상태 문구가 카드 제목보다 상위 제목이 된다. /examples/states에서
h3 카드 안에 h2가 있었고, 섹션 h2 아래 접근 상태 화면도 h2였다.
상태 화면 제목을 <p>로 바꾸는 변이(M5)를 잡는 테스트도 없었다.

고른 방법: Card에 이미 있는 계약을 그대로 옮겼다. 위 네 컴포넌트에
headingLevel?: 2 | 3 | 4(기본 2)를 더하고, 이들을 그리는 AsyncSurface와
AccessSurface가 같은 prop을 넘긴다(그러지 않으면 가장 흔한 진입점에서
뒤집힘이 남는다). 타입은 state-surfaces.tsx의 HeadingLevel 하나에 둔다.
갤러리는 카드 안 상태에 4, 섹션 바로 아래 접근 상태에 3을 준다.
상태·오류 요약 CSS 선택자는 :is(h2, h3, h4)로 넓혔다. 공개 prop은 추가만
했고 기본값이 그대로라 기존 화면은 바뀌지 않는다. 버린 대안: 제목
수준 context(R7) — 모든 컨테이너가 제공자를 둬야 하고 Card의 prop
계약과 갈린다. Card의 인라인 2 | 3 | 4와 HeadingLevel을 합치는 것은
VD-05 재수출 경로를 건드려 이번 범위에서 뺐다.

위험·한계: 갤러리 화면이 바뀐다(카드 안 상태 제목 h4 16px, 접근 상태
h3 20px). 시각 골든은 오케스트레이터가 갱신한다. 실제 스크린 리더
제목 목록은 확인하지 않았다(접근성 트리 대신 component 단언).

검증:
- RED: async-surface.test.tsx 새 테스트 7건이 수정 전 실패(예: "expected
  [ <h2></h2> ] to have a length of +0 but got 1").
- GREEN: async-surface.test.tsx 31/31, tests/component 220/220(4회 반복
  통과, 부하 32에서 첫 실행 1건 실패 뒤 재현 안 됨). tsc app·test 통과,
  eslint 통과. e2e accessibility·typography·reference-form·reference-save
  chromium 27/27.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-05
2026-11-01 23:20:31 +09:00
DongHyeonka 8ed5beb8fd fix(design-system): 한국어 문구가 단어 사이에서만 줄바꿈되게 한다 (08-06)
문제: 스타일·토큰 어디에도 word-break가 없어 브라우저 기본값으로
한국어를 음절마다 끊는다. 골든에 "마운 / 트", "계 / 속할"이 있고, 텍스트
200%에서 로그인 버튼이 "로그 / 인"으로 쪼개졌다. PRODUCT.md의 한국어
기본 원칙과 맞지 않고 모든 파생 서비스가 받는다.

고른 방법: base.css에 :lang(ko) { word-break: keep-all; overflow-wrap:
break-word; }를 둔다. :lang(ko)라 en-US 문서 안의 lang="ko-KR" 구역에도
적용된다. 버린 대안: 리뷰 제안의 overflow-wrap: anywhere — min-content
계산에도 끊을 자리를 더해, 공간이 좁은 flex 항목(헤더 버튼)이 줄어들며
라벨을 다시 쪼갠다. break-word는 넘칠 때만 끊는다. 긴 영문·코드
토큰은 기존 pages.css의 anywhere 두 곳이 그대로 받는다.

위험·한계: 화면이 바뀐다. 좁은 칸에서 줄 수가 늘 수 있다. 시각 골든은
오케스트레이터가 갱신한다. 실제 브라우저 "글자만 확대" 설정에서의
줄바꿈은 눈으로 확인하지 않았다.

검증:
- RED: typography.spec.ts 새 테스트가 수정 전 chromium에서 실패
  (wordBreak "normal", overflowWrap "normal").
- GREEN: typography.spec.ts chromium·firefox·webkit 6/6 통과.
  accessibility·i18n(320px 가로 넘침 포함)·ui-gallery·app-shell·
  responsive·theme·compact-smoke·platform-overview chromium/compact
  34/34 통과. check-design-system PASS. 시각 회귀는 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-06
2026-11-01 23:20:31 +09:00
DongHyeonka 6fc77bb71f fix(design-system): h2·h3·h4에 제목 단계 크기와 굵기를 준다 (08-04)
문제: theme.css가 넣는 Tailwind preflight가 제목의 크기·굵기를 본문으로
되돌린다. base.css는 h1 크기와 h2 줄 간격만 정해, 6개 라우트 모두
h2·h3이 16px/400으로 본문과 같았다. 구획을 훑어볼 수 없고, 제품마다
제목 크기를 따로 만들게 된다.

고른 방법: 리뷰의 최소 개선 방향대로 primitive에 --font-size-xl(1.25rem)
·--font-size-2xl(1.5rem)을 더하고, semantic에 제목 단계 토큰
(--font-size-heading-2/3/4, --font-weight-heading = semibold)을 둔 뒤
base.css에서 h2·h3·h4에 적용했다. 컴포넌트 제목(카드 h3, 상태 화면
h2)은 자기 수준의 기본 스타일을 그대로 받는다. 제품은 semantic 토큰
값만 바꿔 단계를 조정한다. 값(24/20/16px, 650)은 1.2배 안팎의 단계로
골랐다. 버린 대안: 컴포넌트마다 크기를 주기 — 같은 값이 여러 곳에
흩어진다. token-contract 필수 목록에 추가 — 다운스트림 토큰 파일이
바로 실패하고, 결과는 아래 e2e가 지킨다.

위험·한계: 화면이 바뀐다. 시각 골든(app-shell, state-surfaces 등)은
오케스트레이터가 갱신한다. 상태 화면이 카드(h3) 안에서 h2로 더 크게
보이는 문제는 08-05가 다룬다. 값 자체는 디자인 결정이라 바꿀 수 있다.

검증:
- RED: 새 tests/e2e/typography.spec.ts가 수정 전 chromium에서 실패
  (h2 16px, h3 16px: "Expected: > 16, Received: 16").
- GREEN: 같은 spec chromium·firefox·webkit 3/3 통과. accessibility·i18n·
  ui-gallery·app-shell·responsive·theme·design-system-interactions·
  compact-smoke + typography chromium/chromium-compact 32/32 통과(별도
  playwright 설정, vite preview, pnpm 없이 빌드).
- check-design-system PASS(48 tokens). 시각 회귀는 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-04
2026-11-01 23:20:31 +09:00
DongHyeonka d0f3993b60 fix(presentation): 검색값만 바뀌면 포커스·스크롤·진단을 건드리지 않는다 (08-02)
문제: RouteLifecycle이 pathname·search·navigationType을 effect 의존값으로
썼다. 그래서 URL에 묶은 필터를 바꾸면 포커스가 컨트롤에서 <main>으로
튀고, POP이 아니면 맨 위로 스크롤하고, route.changed를 한 번 더 남겼다.
이미 보고 있는 화면의 링크를 눌러도(React Router가 REPLACE로 바꿈)
navigationType만 바뀌어 같은 일이 났다. 템플릿은 필터를 URL에 두라고
권하므로 첫 목록 화면에서 바로 드러난다(WCAG 3.2.2).

고른 방법: 이동 판단을 route ID 또는 pathname 변경으로 좁혔다(리뷰 5.1
(B)). 포커스·스크롤·진단은 useEffectEvent로 옮겨 navigationType을 읽기만
하고 트리거로 쓰지 않는다. 검색값 변경에 맨 위가 필요한 화면(페이지
번호)은 그 화면이 직접 스크롤한다. routing 문서 6.3절에 규칙을 적었다.
버린 대안: (C) 라우트 계약에 searchChangeIsNavigation 선언 — 그런
라우트가 템플릿에 없고 생성기·문서까지 바뀐다. 필요해지면 (B) 위에
더할 수 있다. navigationType을 ref로 들고 있기 — 렌더 중 ref 쓰기라
React 19의 useEffectEvent보다 의도가 덜 드러난다.

위험·한계: 지금 검색값 변경을 이동으로 세던 대시보드가 있다면 수치가
준다. 실제 브라우저의 스크롤 유지는 jsdom이 스크롤을 건너뛰어 정적
확인만 했다. 테스트용 fixture 페이지에 URL에 묶은 select를 더했다.

검증:
- RED: router.test.tsx 새 테스트 2건이 수정 전 실패. 포커스가
  <main id="main-content">에 있었고 route.changed가 필터 테스트 1→3,
  링크 테스트 1→2로 늘었다.
- GREEN: router.test.tsx 11/11, tests/component 34 files 213 tests 통과.
  tsc(app, test) 통과, eslint(바꾼 파일) 통과,
  verify-documentation-readiness PASS_SCOPED.
- check:architecture는 pnpm 실행을 요구해 이 worktree에서 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-02
2026-11-01 23:20:31 +09:00
DongHyeonka 9142390422 fix(browser-transfer): upload 실패 번역이 code도 보고 행동을 고른다 (0929/01-01)
문제: 포트는 upload() 실패의 recovery가 호출자 행동 하나를 가리킨다고
적는다. 번역은 toUploadAction 한 곳이 하는데 recovery 단어만 본다. 표
밖 값이면 REISSUE_CAPABILITY·RETRY만 RESUME, 나머지는 NONE으로 바꾸고
retryable은 그대로 둔다. 그래서 지난 리뷰 실험 X1의 경로들이 표와 다른
행동을 가리킨다.
- ① 고른 파일이 바뀜(NOT_READABLE/REOPEN): NONE에 retryable:true.
  표대로면 RESELECT다.
- ② IndexedDB 일시 오류(UNAVAILABLE/REOPEN, retryable:true): NONE.
  다시 부르면 성공한다.
- ③ part 발급 404(서버가 session을 모름): NONE. 다시 부르면 새
  session으로 성공한다.
- ⑤ 닫힌 runtime: RESUME. 같은 runtime은 늘 같은 답이다.
- ⑥ session보다 긴 capability(POLICY_REJECTED/REISSUE_CAPABILITY):
  RESUME. 서버가 같은 값을 다시 준다.

고른 방법(지난 리뷰 3절 D1의 (a), 번역 기준 보강): 번역은 계속 한 곳에
둔다. 몇 가지 code가 먼저 정한다. POLICY_REJECTED → NONE, file store의
NOT_READABLE/REOPEN → RESELECT, UPLOAD_PART의 NOT_FOUND → RECONCILE.
나머지는 지금처럼 표 안 값은 그대로 두고, 표 밖이면 retryable:true나
REISSUE_CAPABILITY·RETRY일 때 RESUME, 아니면 NONE이다. NONE과 RESELECT는
번역 끝에서 retryable:false로 맞춘다. 닫힌 runtime은 NONE을 돌려준다.
포트 표 주석과 설계 문서 표에 이 규칙을 적었다.

버린 대안:
- 리뷰 예시의 STALE_RESULT → RESELECT. 기존 STALE_RESULT/RECONCILE
  경로(resumable-upload-runtime.ts의 재조정)를 깨뜨린다. 지금
  STALE_RESULT는 모두 표 안 값을 갖고 있어 규칙이 필요 없다.
- 리뷰 예시의 NOT_READABLE → RESELECT(조건 없이). PUT 중 네트워크 읽기
  실패도 NOT_READABLE(REISSUE_CAPABILITY)이라 파일 재선택으로 잘못
  보낸다. 그래서 REOPEN(file store가 붙이는 값)일 때만 RESELECT다.
- 출처마다 포트 어휘를 만들게 하는 안(b), action 필드 추가(c). 지난
  리뷰가 다른 포트를 틀어지게 하거나 공유 타입을 바꾼다고 기각했다.

위험·한계:
- ④ part 발급(BFF) 401/403은 고치지 않았다. 지금도 RESUME이다. object
  store PUT 403(재발급으로 풀리고, 기존 01-05 표 테스트가 RESUME으로
  고정)과 code·단계·recovery가 모두 같아 번역 한 곳에서 가를 수 없다.
  리뷰 예시("PERMISSION_DENIED는 단계와 무관하게 NONE")와 보존 조건
  ("기존 7경로 기대값 유지")이 이 경로에서 서로 어긋난다. runtime
  호출 지점에서 발급 거절만 따로 표시할지는 소유자 판단이 필요하다.
  그래서 이 발견은 부분 충족이다.
- 몇 경로의 recovery 값이 바뀐다(위 ①②③⑤⑥). 기존 테스트 하나
  (resumable-upload-runtime-contract.test.ts "rejects a part capability
  that outlives its session")의 기대값을 RESUME → NONE으로 바꿨다.
  다운스트림 화면이 이 값으로 분기하므로 CHANGELOG [계약] 한 줄이
  필요하다. 이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지
  않았다.
- 실제 브라우저 오류 발생은 재현하지 않았다. 단위 harness에서 오류
  값을 주입했다.
- file-transfer 레시피 번들이 55,937 → 56,031 gzip bytes가 되어 예산
  56,000을 넘었다. 다음 백 단위 규칙대로 56,100으로 올렸다.

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 5건 실패.
  ① recovery NONE·retryable true(기대 RESELECT·false), ② NONE(기대
  RESUME), ③ NONE(기대 RECONCILE), ⑤ RESUME(기대 NONE), ⑥ RESUME(기대
  NONE). 수정 전 번역 규칙으로 되돌리면 같은 5건이 실패한다.
- GREEN: 같은 파일 통과. 기존 7경로 표 테스트에 "NONE이면
  retryable:false" 단언을 더했고 통과한다.
- 회귀: resumable-upload·presigned·upload-cancellation·browser-file·
  image-cdn 단위 20파일 326건 통과. tsc app·test·recipes 통과. 바꾼
  파일 eslint 통과. verify-documentation-readiness PASS_SCOPED.
  check-architecture(exec 전용 shim) 통과. check-optional-recipes
  (source) file-transfer 56031/56100.

Refs: docs/reviews/2026-09-29-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:48 +09:00
DongHyeonka aedd32841f fix(cache-storage): 정책 변경과 손상 뒤에도 다음 배포가 pointer를 덮어쓴다 (0929/02-01)
문제: active pointer를 읽을 때 rollback 목록 길이를 현재
retainedPreviousReleaseCount와 비교한다. 3에서 1로 줄이는 정상 설정
변경이나 pointer JSON 손상 뒤에는 읽기가 CORRUPT_DATA가 되고, 조회·
활성화·정리·inspect가 모두 여기서 멈춘다. control cache를 지우는 API가
없어 사용자가 사이트 데이터를 지우기 전까지 오프라인 캐시가 꺼진 채로
남고, cleanup이 막혀 배포마다 release cache가 쌓인다. 이번 라운드에도
Node와 실제 Cache API 3엔진에서 재현됐다.

고른 방법(지난 리뷰 4.1절의 (나)+(다)):
- (다) isActivePointer는 목록 길이를 현재 값이 아니라 정책이 허용하는
  최댓값(5, MAX_RETAINED_PREVIOUS_RELEASE_COUNT)과만 비교한다. 정책
  검증과 같은 상수를 쓴다. 다음 activation이 이미 하던 slice로 목록을
  현재 값으로 자른다.
- (나) activateRelease는 이전 pointer 읽기가 CORRUPT_DATA면 없는
  것으로 보고, 전체 재검증을 통과한 후보로 rollback 목록 없이
  덮어쓴다. 일시 오류(UNAVAILABLE 등)는 지금처럼 활성화를 멈춘다.

버린 대안:
- 현상 유지 + "사이트 데이터 삭제" 안내. 운영자가 원인을 알 수 없고
  캐시가 계속 쌓인다.
- control을 지우는 admin API. 포트가 늘고 호출자가 언제 불러야 하는지
  알아야 한다.
- (다)만 적용. 정책 변경은 풀리지만 JSON 손상은 풀리지 않는다.

위험·한계:
- 지키던 성질은 그대로다. 검증한 후보만 활성화하고(재검증은 pointer
  읽기 전에 끝난다), 조회는 manifest digest가 맞는 바이트만 돌려준다.
  읽을 수 있는 pointer가 가리키는 캐시는 cleanup이 지우지 않는다.
  손상 pointer 상태의 조회와 cleanup은 다음 activation까지 여전히
  CORRUPT_DATA다.
- 덮어쓰면 손상 pointer의 rollback 목록을 잃는다. 원래 읽을 수 없던
  값이다. 덮어쓴 뒤 cleanup이 구버전 탭이 쓰던 캐시를 지울 수 있다.
  그 탭의 조회는 네트워크로 떨어진다. Service Worker drain(VD-15)을
  구현하면 이 규칙을 다시 본다(지난 리뷰 4.1절 7).
- 리뷰가 "가능하면"으로 적은 3엔진 browser spec(E-2)은 추가하지
  않았다. 단위 테스트(MemoryCacheStorage)로만 확인했다.
- service-worker-pwa 레시피 번들 9,665 → 9,716 / 10,000 gzip bytes.

검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 2건 실패.
  retained 3 → 1 뒤 조회가 { ok: false }(기대 ok:true), 잘린 pointer
  뒤 다음 배포의 activate가 { ok: false }.
- GREEN: 같은 파일 8건 통과. 일시 오류 가드 테스트 1건을 함께 넣었다.
  activate가 모든 pointer 실패를 무시하도록 바꾼 변이를 이 테스트가
  잡는다(1건 실패 확인 뒤 되돌림).
- 회귀: public-response-cache 단위 3파일 40건 통과. tsc app·test·
  service-worker·recipes 통과. 바꾼 파일 eslint 통과.
  verify-documentation-readiness PASS_SCOPED. check-optional-recipes
  (source) PASS.

Refs: docs/reviews/2026-09-29-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:48 +09:00
DongHyeonka 8ad11c0b64 fix(browser-files): preview와 download의 dispose가 자기 lease만 푼다 (02-01)
문제: runtime은 object URL lease registry 하나를 preview와 download에
같이 넘긴다. 두 쪽의 dispose()가 모두 registry 전체의 dispose()를
불러, 누가 만든 lease인지 구분하지 않고 전부 revoke한다.
runtime.previews.dispose()를 부르면 30초 grace 중인 download blob
URL까지 바로 revoke된다(E-9). 브라우저가 아직 blob을 읽기 전이면 그
download가 실패할 수 있다. 반대로 download의 dispose()는 다른 화면의
preview URL을 끊는다. registry 주석은 이 dispose를 "route teardown"
에서 쓰라고 읽혔다.

고른 방법(리뷰 5.2절의 (나)): 한도는 같이 쓰고 해제 권한만 나눈다.
registry에 scope()를 두어 소비자마다 자기가 만든 lease 집합을
들고, scope의 dispose()는 그것만 release한다. preview와 download
adapter는 각자 scope로 lease를 만든다. registry 전체 dispose()는
runtime.dispose()만 부른다. 포트 시그니처는 그대로이고,
TransientPreviewPort.dispose()에 효과 범위를 주석으로 적었다. 설계
문서 3.5절에 해제 권한과 route 정리 방법을 적고, 바뀐 줄 번호를
맞췄다.

버린 대안:
- 포트 주석만 고친다(가). 함정이 코드에 그대로 남는다.
- 소비자마다 registry를 나눈다(다). 해제 범위는 맞지만 탭 전체의
  합계 바이트 상한이 두 곳으로 갈라진다.
- TransientPreviewPort에서 dispose()를 뺀다(라). 공개 포트 변경이라
  이번 범위(포트는 추가만)를 넘는다. (나)와 함께 할 수 있어 남겨 둔다.

위험·한계:
- previews.dispose() 뒤 그 runtime의 preview가 계속 UNAVAILABLE인
  것(영향 ②)과, previews.dispose()가 다른 화면의 preview lease까지
  푸는 것(영향 ①, 같은 소비자 안)은 그대로다. 문서에 route 정리는
  lease마다 release()로 하라고 적었다. 완전히 막으려면 (라)가 필요하다.
- scope가 들고 있는 release 함수 집합만큼 메모리가 조금 는다. lease
  release 때 집합에서 빠지므로 lease 수 상한(기본 16)을 넘지 않는다.
- file-transfer 레시피 번들이 55,856 → 55,937 gzip bytes가 되어 예산
  55,900을 넘었다. 다음 백 단위 규칙대로 56,000으로 올렸다.

검증:
- RED(수정 전): browser-file-runtime.test.ts 새 1건 "expected
  [ 'blob:runtime-download' ] to deeply equal []"(previews.dispose()가
  download URL을 revoke). browser-file-download.test.ts 새 1건
  "expected [ 'blob:shared-1', 'blob:shared-2' ] to deeply equal
  [ 'blob:shared-2' ]"(download dispose()가 다른 소비자의 lease를
  revoke).
- GREEN: browser-file 단위 5파일 64건 통과. runtime dispose가 모든
  lease를 즉시 revoke하는 기존 테스트도 통과.
- 회귀: browser-file·presigned·json-schema 단위 10파일 168건 통과.
  tsc app·test·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
  (exec 전용 shim) 통과, check-adapter-inventory 통과,
  verify-documentation-readiness PASS_SCOPED,
  check-optional-recipes(source) file-transfer 55937/56000.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 5b96529c53 fix(cross-context-invalidation): publish 실패 원인을 관측 reason에 싣는다 (02-05)
문제: cross-context publish가 실패하면 원인과 상관없이 관측 reason이
INVALID_ENVELOPE다. createEventId가 던질 때(host에서는 secure random
실패)와 자기 envelope 검사 실패가 같은 invalidPublish()로 가고, 그
함수가 reason을 고정한다. bootstrap은 이 reason을 그대로
cache.operation.failed 진단에 싣는다. 난수 실패나 topic version
불일치가 "wire 형식 오류"로 보여 원인을 찾으려면 코드를 읽어야 한다.

고른 방법: invalidPublish가 reason을 인자로 받는다. event ID 실패는
이미 reason 목록에 있는 SECURE_RANDOM_UNAVAILABLE, envelope 검사
실패는 parse 결과의 reason(TOPIC_REJECTED 등)을 싣는다. 새 reason
값은 만들지 않는다. 호출자에게 돌려주는 결과
{ok:false, reason:"INVALID_EVENT"}는 그대로다.

위험·한계: 관측 reason 값이 바뀌므로 INVALID_ENVELOPE로 경보를 거는
대시보드가 있다면 새 값도 봐야 한다. 이 repo 안에는 그런 소비자가
없다. cross-context는 기본 조립이라 초기 JS에 들어간다. 바뀐 코드는
수십 바이트이고, 빌드 기반 번들 게이트(check:bundle)는 pnpm이 필요해
이 worktree에서 돌리지 않았다.

검증:
- RED(수정 전): cross-tab-invalidation.test.ts 새 1건이
  "expected [ 'INVALID_ENVELOPE' ] to deeply equal
  [ 'SECURE_RANDOM_UNAVAILABLE' ]"로 실패.
- GREEN: 같은 파일 통과.
- 회귀: cross-tab-invalidation·tanstack-cache-coordinator·
  runtime-adapters 단위 3파일 46건 통과. tsc app·test 통과. 바꾼 파일
  eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 3bb1829cda fix(cache-storage): stage 재검증 실패를 CACHE_STAGE로 기록한다 (02-03)
문제: 이미 stage된 release를 다시 stage하면 후보를 재검증한다.
재검증 함수 verifyReleaseCandidate는 활성화와 같이 쓰는 함수라 실패
Result의 operation을 CACHE_ACTIVATE로 만든다. 활성화 경로는
rebaseFailure로 바꾸지만 stage의 재사용 경로는 그대로 돌려준다.
Cache API가 재검증 중 일시 오류를 내면 stage 결과와 관측이 모두
CACHE_ACTIVATE가 된다. 운영자는 "활성화 실패"로 읽고, error.operation
으로 분기하는 호출자는 잘못된 경로를 탄다.

고른 방법: stage 재사용 경로도 활성화 경로처럼
rebaseFailure(..., "CACHE_STAGE")로 돌려준다. 한 줄이다.

버린 대안: verifyReleaseCandidate가 operation을 인자로 받게 하는 안.
호출부 세 곳(stage, activate, inspect)을 모두 바꾸고, inspect는 실패를
밖으로 내지 않아 이득이 없다. 리뷰가 함께 적은
readAndValidateResponse의 CACHE_STAGE 고정은 두 소비 경로가 이미
rebase하거나 결과를 내보내지 않아 겉으로 드러나는 결함이 없으므로
건드리지 않았다.

위험·한계: 동작(실패를 성공으로 바꾸지 않음, 후보를 지우지 않음)은
그대로다. 바뀌는 것은 실패의 operation 값뿐이다. service-worker-pwa
레시피 번들 9,662 → 9,665 / 10,000 gzip bytes.

검증:
- RED(수정 전): public-response-cache-repair.test.ts 새 1건이
  operation "CACHE_ACTIVATE"(기대 "CACHE_STAGE")로 실패.
- GREEN: public-response-cache 단위 3파일 37건 통과.
- 회귀: tsc app·test·service-worker 통과. 바꾼 파일 eslint 통과.
  check-optional-recipes(source) PASS.

Refs: docs/reviews/2026-11-01-maturity-review/02-adapters-browser-files-cache.md
2026-11-01 23:14:47 +09:00
DongHyeonka 6b7b53fe01 perf(image-cdn): 같은 이미지를 동시에 resolve하면 probe를 한 번만 돌린다 (01-04)
문제: resolve()는 통과한 probe 기록(passedProbes)을 slot을 기다리기
전에만 본다. 같은 asset·preset을 동시에 5번 resolve하면 probe가 5번
돈다. probe마다 preset의 encoded 예산까지 no-store로 내려받고
decode하며, 같은 이미지가 probe slot을 차지해 다른 이미지의 probe가
밀린다.

고른 방법: asset·preset별로 "진행 중인 probe 단계"(slot 대기, probe,
통과 기록)를 promise 하나로 둔다. 뒤에 온 호출은 그 단계가 끝나기를
자기 signal로 기다린 뒤 기록된 통과를 재사용한다. probe 자체를
공유하지 않으므로 호출마다 abort가 독립이다. 앞선 probe가 실패하면
기다린 호출이 직접 probe한다(실패는 재사용하지 않는다는 기존 규칙).
X5(동시 5회, maxConcurrentProbes 2)에서 probe가 1회다.

버린 대안:
- 리뷰가 제안한 slot 획득 뒤 재확인. 넣어 보니 X5에서 probe가 3회로
  완료 기준(2회 이하)을 못 맞춘다. slot은 원시 probe가 끝날 때
  넘겨지는데(TR-RR-07), 통과 기록은 그보다 몇 microtask 뒤에 남는다.
  다음 대기자가 기록 전에 깨어난다.
- 진행 중 probe의 결과를 공유(single-flight). 호출자마다 signal이
  달라 참조 수를 세야 한다.
- slot 해제를 통과 기록 뒤로 미룬다. 해제 지점이 원시 probe 정착과
  wrapper 종료 두 곳으로 갈라진다.

위험·한계:
- 대기 뒤 재사용할 때 만료를 따로 다시 보지 않는다. 통과를 기록한
  호출이 기록 직전에 만료를 봤고, 대기자는 같은 task 안에서 이어서
  실행된다. 시작할 때의 만료 검사(기존)는 그대로다.
- 앞선 probe가 실패하면 기다리던 호출들이 각자 probe한다(slot 수로
  묶임). 실패가 반복되는 이미지는 지금과 같은 수의 probe가 돈다.
- probe 블록을 try/finally로 감싸면서 들여쓰기가 바뀌었다. 로직
  변경은 `git show -w`로 보면 짧다.
- file-transfer 레시피 번들이 55,725 → 55,856 gzip bytes가 되어 예산
  55,800을 넘었다. 다음 백 단위로 올리는 기존 규칙대로 55,900으로
  올렸다.

검증:
- RED(수정 전 코드에 새 테스트): "probes once and lets the other calls
  reuse the pass"가 "expected vi.fn() to be called 1 times, but got 5
  times"로 실패. 재확인 안(버린 대안)에서는 2회 기대에 3회로 실패.
  나머지 새 테스트 2건(앞선 probe 실패 시 대기자가 직접 probe, 대기
  중 abort가 진행 중 probe를 끊지 않음)은 새 분기를 고정한다.
- GREEN: image-cdn 단위 3파일 37건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·json-schema
  단위 20파일 323건 통과. tsc app·test·recipes 통과. 바꾼 파일 eslint
  통과. check-optional-recipes(source) file-transfer 55856/55900.

Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:47 +09:00
DongHyeonka 95e4445243 fix(browser-transfer): part 발급과 PUT이 서버의 Retry-After를 기다린다 (01-01)
문제: part 단계(BFF capability 발급, object store PUT)의 상태표
statusFailure는 상태 코드만 받아 429의 Retry-After를 버린다. 서버가
`429 Retry-After: 5`로 답해도 runtime은 지수 backoff(기본 250·500·
1000ms)로 다시 보내고, 1.75초 안에 요청 8개를 쓴 뒤 retryable 실패를
돌려준다. 설계 문서 두 곳(presigned-transfer-and-image-cdn.md,
server-file-capability-infrastructure.md)은 part 단계도 bounded
Retry-After를 따른다고 적는다. 헤더를 읽는 곳은 control plane
transport뿐이었다.

고른 방법: statusFailure가 Response와 현재 시각을 받아 429·503이면
kernel parseRetryAfterDelay로 retryAfterMs를 채운다. 상한
maxRetryAfterMs는 runtime의 canRetry·waitForRetry가 이미 적용하므로
presigned 계층은 값을 그대로 넘긴다. 상한을 넘으면 재시도하지 않는다
(control plane과 같은 규칙). PresignedUploadPartCapabilityProvider.
issueUploadPart와 PresignedUploadPartPort.put의 반환 타입을
UploadProviderResult로 넓혔다. 기존 구현은 그대로 대입되므로
추가형이다. HTTP control plane 어댑터의 발급 브리지가 실패를 다시
만들면서 retryAfterMs를 버리던 것도 넘기게 했다.

버린 대안:
- 문서를 "part 단계는 Retry-After를 읽지 않는다"로 고친다. 재시도
  증폭이 그대로 남는다.
- BFF 응답 본문에 대기 시간을 넣는 별도 계약. 표준 헤더를 두고 서버와
  클라이언트를 함께 바꿔야 한다.
- download 경로만 빼고 읽는다. 하나로 합친 상태표(Q-6.1-9)를 다시
  둘로 가르게 된다. download 소비자(browser-files 전달 어댑터)는
  실패를 다시 만들어 이 값을 읽지 않는다.

위험·한계:
- 다른 origin의 object store가 Access-Control-Expose-Headers에
  Retry-After를 넣지 않으면 헤더가 없는 것으로 읽혀 지금처럼 backoff만
  쓴다. statusFailure 주석에 적었다.
- part 단계에서 Retry-After가 없거나 형식이 틀린 429는 지금처럼
  retryable backoff다. control plane은 이 경우 재시도하지 않는다. 이
  차이는 이번에 바꾸지 않았다.
- issueDownload·open 실패에도 retryAfterMs가 실린다. 이 두 포트의
  타입(BrowserDataResult)에는 드러나지 않는다.
- file-transfer 레시피 번들이 55,623 → 55,725 gzip bytes가 되어 예산
  55,700을 넘었다. 측정값 위 약 100바이트로 반올림하는 기존 규칙
  (4b0e44a9)대로 55,800으로 올렸다.
- 포트 반환 타입이 넓어졌으므로 CHANGELOG [계약] 한 줄이 필요하다.
  이번 수정 묶음은 CHANGELOG를 한 번에 쓰므로 여기서는 쓰지 않았다.

검증:
- RED(수정 전): resumable-upload-runtime-recovery.test.ts 새 4건 실패.
  발급·PUT이 `429 Retry-After: 5`일 때 "expected 0 to be greater than
  or equal to 5000"(첫 sleep 0ms). maxRetryAfterMs 1000을 넘을 때
  재시도해서 ok:true. resumable-upload-http-control-plane.test.ts 새
  1건 실패: 브리지 결과에 retryAfterMs 5000이 없다.
- GREEN: 두 파일 33건 통과.
- 회귀: browser-file·image-cdn·presigned·resumable-upload·
  upload-cancellation·json-schema 단위 21파일 322건 통과. tsc app·
  test·node·recipes 통과. 바꾼 파일 eslint 통과. check-architecture
  (exec 전용 shim, pnpm 미사용) 통과, check-adapter-inventory 통과,
  check-optional-recipes(source) PASS file-transfer 55725/55800.

Refs: docs/reviews/2026-11-01-maturity-review/01-adapters-browser-transfer.md
2026-11-01 23:14:47 +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 abf3ce521d fix(contracts): REST 보안 프로필 오류가 operation·프로필·깨진 조건을 말한다 (16-03)
문제: `resolveRestSecurityProfiles`는 프로필이 없거나 조합이 틀리면 일곱
조건을 한 번에 보고 "REST security profiles are incoherent."만 던진다.
참조 기능을 복사해 `REFERENCE_EXTERNAL_BEARER`를 바꾸면 이 한 문장으로
레지스트리를 읽는 게이트가 모두 멈추고, 개발자는 스택에서
rest-profiles.ts를 열어 조건을 하나씩 대조해야 한다.

고른 방법: 조건마다 깨졌을 때의 문장을 만들어 모은 뒤, operation id와
함께 한 오류로 던진다. 예: "REST security profiles are incoherent for
CREATE_SAMPLE_RESOURCE: unknown authProfileId ORDER_EXTERNAL_BEARER."
operation 인자 타입에 선택 필드 `operationId`를 더했다(추가만). 호출부
두 곳(`validateRestProfileBindings`, V2 client)은 이미 operation 전체를
넘기므로 고칠 곳이 없다. 기존 문장 앞부분은 그대로라 "incoherent"를 찾는
테스트·로그 검색은 계속 맞는다.

버린 대안: 첫 번째로 깨진 조건에서 바로 throw하기. 조건이 둘 이상
깨진 경우(예: 이름도 틀리고 CSRF도 틀림) 고칠 때마다 다음 오류를 다시
봐야 한다.

위험·한계:
- 리뷰 16-03의 (1) 프로필 이름을 `EXTERNAL_BEARER`로 바꾸고 옛 이름을
  별칭으로 두는 부분은 하지 않았다. FE-REG-API 행이 바뀌어 레지스트리
  기준선을 다시 써야 하고, `update-registry-baseline.ts`는 소유자와
  사유(REGISTRY_BASELINE_OWNER/REASON)를 승인 파일에 남긴다. 그 승인은
  사용자 몫이다. 제거 드릴 잔여 정규식이 이 이름을 못 잡는 문제도 그
  작업에 남는다.
- 초기 JS +189 B gzip(202,806 → 202,995 B, 여유 1,805 B). rest-profiles가
  초기 청크에 있어 오류 문장이 그대로 실린다.

검증:
- RED: tests/unit/rest-profile-contract.test.ts의 새 테스트가
  "expected [Function] to throw error matching /incoherent.*
  CREATE_SAMPLE_RESOURCE.*u…/ but got 'REST security profiles are
  incoherent.'"로 실패.
- GREEN: 같은 파일 8건 통과(미등록 프로필, auth "none"+bearer 두 경우).
- 회귀: tests/unit(pnpm을 띄우는 5개 제외) 1,930건, tests/integration
  (프로세스를 띄우는 3개 제외) 131건, tests/{contract,features,
  runtime-schema,component,architecture,platform} 626건 통과. tsc app·test
  통과. 바꾼 파일 eslint 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka de48db25d9 fix(router): context·feature 경계와 라우트 모듈 실패를 진단에 남긴다 (09-09)
문제: context gateway의 `ContextErrorBoundary`·`FeatureErrorBoundary`는
`onError`를 받지 않아 잡은 실패를 진단에 남기지 않고, 화면 지원 참조는
buildId뿐이다. 라우트 모듈이 청크 누락이 아닌 이유로 실패할 때(평가 중
throw, 15-01 뒤로는 기능 실행부 적재 실패)도 같은 화면만 그리고 기록이
없다. 안쪽 경계(`RenderErrorBoundary`) 밖에서 난 실패, 예를 들어 핸들의
route id가 레지스트리에 없거나 핸들에 라우트 codec이 없을 때는 사용자
신고로도 사건을 찾을 수 없다. 0929/08-05와 같은 결함이다.

고른 방법:
- `ScopedErrorBoundary`가 잡을 때 incident id를 만들어 `onError` 보고에
  넣고, 함수형 fallback에 같은 id를 넘긴다. 둘 다 추가 변경이다(기존
  ReactNode fallback과 `{scope, ownerId}`를 읽는 쪽은 그대로 동작).
- incident id 생성기를 `src/platform/errors/incident-id.ts`로 옮겨 두
  경계 계열이 같은 함수를 쓴다(platform은 presentation을 import할 수 없다).
- gateway가 두 경계에 `reportRenderFailure` 호출과
  `<buildId>:<incidentId>` 지원 참조를 넘긴다. context 경계는
  `component_boundary`를 "route"로 보고한다. 진단·텔레메트리 계약에
  context 값이 없고, 같은 gateway의 청크 복구 보고도 "route"를 쓴다.
- 비청크 적재 실패는 context 경계 안에서 다시 throw해 같은 보고 경로를
  탄다. route id는 URL의 등록 라우트, 없으면 context id다.

버린 대안:
- 세 곳을 presentation `RouteBoundary`로 바꾸기(0929/08-05 제안): 경계
  두 계열 통합(리팩토링 R4) 성격이고 context/feature 소유 범위 표시
  (`data-boundary`, testid)가 바뀐다.
- gateway가 URL마다 incident id를 하나 만들어 두 경계에 나눠 주기:
  두 경계가 같은 id를 공유해 사건 구분이 흐려진다.
- `component_boundary`에 "context" 추가: 진단·텔레메트리 계약과
  레지스트리 기준선을 바꾸는 일이라 이번 범위 밖이다.

위험·한계:
- `APP_SHELL`의 `errorElement`(0929/08-05가 함께 적은 곳)는 그대로
  buildId만 보이고 보고하지 않는다. React Router 오류 요소라 다른 방식
  (useRouteError + 마운트 시 보고)이 필요해 남겼다.
- 실패한 context 안에서 URL을 바꾸면 경계가 리셋되고 다시 throw해 방문마다
  한 번 보고한다.
- 화면 변화: context·feature 경계 실패 화면과 비청크 적재 실패 화면의
  지원 참조가 `build:incident` 형식이 된다. 시각 골든에는 없는 화면이다.
- 초기 JS +58 B gzip(202,748 → 202,806 B, 여유 1,994 B).

검증:
- RED: tests/component/context-boundary-diagnostics.test.tsx 3건(context
  경계: 미등록 핸들 id, feature 경계: codec 없는 핸들, 비청크 적재 실패)이
  모두 `Unable to find an element with the text: /^지원 참조:
  build-a:[0-9a-f]{8}$/`로 실패. 화면은 "지원 참조: build-a"였다.
- GREEN: 3건 통과. failure-boundary.test.tsx에 함수형 fallback이 보고한
  incident id를 받는지 1건 추가, `onError` 보고 기대값에 incidentId 추가.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
  95 files / 592 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
  1,929 tests 통과. tsc app·test 통과. 바꾼 파일 eslint 통과.
  check-architecture(shim), check-adapter-inventory, check-diagnostics,
  check-registries 통과.
2026-11-01 22:56:29 +09:00
DongHyeonka 7139c7c61e fix(apps): 소유 context 루트가 닿지 않는 기능 라우트를 조립 때 막는다 (09-06)
문제: 라우터는 context마다 gateway 하나를 그 루트 경로에 붙이고 기능
라우트를 그 안에서만 렌더한다. 레지스트리와 탐색 메뉴는 경로와 상관없이
모든 기능 라우트를 싣는다. 그래서 루트 `shop/*` context의 `/catalog`
라우트는 메뉴 링크로 나오고 그 URL은 NOT_FOUND가 된다. 같은 루트를 쓰는
context가 둘이면 id가 늦은 쪽 전체가 닿지 않는다. 어떤 게이트도 경로와
루트를 비교하지 않았다.

고른 방법: `defineDeployableAppModule`이 context별 기능 계약 라우트를
React Router `matchRoutes`로 전체 context 루트에 맞춰 보고, 그 라우트를
받는 context가 소유 context가 아니면 라우트 id·경로·기능 id·context
id·루트를 담아 throw한다. 앱 모듈은 부트 정적 그래프에서 평가되므로
부트 실패 화면과 라우터를 거치는 모든 테스트에서 드러난다. 라우터와 같은
매칭 규칙을 쓰므로 루트 밖 경로, `/`, 루트 없는 context, 같은 루트, 더
구체적인 다른 루트에 먹히는 경로를 한 검사로 잡는다. 중첩 루트 자체는
허용한다(`tests/component/context-route-gateway.test.tsx`가 쓰는 모양).
starter-experience.md 기능 추가 4단계에 규칙을 적었다.

버린 대안:
- 생성기에서 검사: 생성기는 정규식으로 리터럴만 읽어 라우트 경로를 모른다.
- `defineBoundedContextModule`에서 검사: 다른 context의 루트를 모른다.
  같은 루트·중첩 루트를 앱 단위에서 따로 또 봐야 해서 검사가 두 곳이 된다.
- 루트 문자열 접두어 비교: `:param`·splat 규칙을 다시 구현하게 된다.

위험·한계:
- 리뷰 09-06의 (3) "context 라우트 핸들의 route id가 레지스트리에 있는가"는
  넣지 않았다. 핸들은 `context-routes.ts`를 읽어야 보이는데 이 파일은 늦게
  읽어야 한다. 헬퍼 제공과 적재 시 검사 중 고르는 설계 선택이라 남긴다.
  그 실패의 진단 누락은 09-09에서 다룬다.
- 플랫폼 라우트와 기능 라우트의 경로 충돌은 검사하지 않는다.
- 초기 JS +239 B gzip(202,509 → 202,748 B, 여유 2,291 → 2,052 B).
  같은 worktree에서 `vite build` 두 번으로 쟀다.

검증:
- RED: tests/architecture/context-route-roots.test.ts 7건 중 거절 5건이
  "expected [Function] to throw an error"로 실패(수정 전, 298201f 기준).
- GREEN: 같은 파일 7건 통과.
- 회귀: tests/{architecture,platform,component,features,scripts,contract}
  94 files / 588 tests, tests/unit(pnpm을 띄우는 5개 제외) 164 files /
  1,929 tests 통과. tsc app·test·node 통과. 바꾼 파일 eslint 통과.
  check-architecture.ts(pnpm exec를 node_modules/.bin으로 넘기는 shim)
  통과.
2026-11-01 22:56:29 +09:00
DongHyeonka c67edd2557 fix(web-push): 정상 알림 클릭이 router base path 아래 경로를 연다 (06-01)
문제: Web Push 정상 클릭은 registry path를 origin 기준으로 풀었다
(`new URL(path, origin)`). 거절된 클릭은 이미 앱 루트(=
registration.scope = router base path)를 쓴다(06-09). 그래서
VITE_ROUTER_BASE_PATH=/app/ 배포에서 열린 창이 없으면 정상 클릭이
https://host/inbox, 즉 앱 밖을 열었다. registry에 /app/inbox를 넣으면
openWindow는 맞지만 같은 값이 handoff path로 페이지에 가서 router
basename과 겹친다. 어떤 registry 값으로도 두 경로를 함께 맞출 수
없었다.

고른 방법: registry path를 "base path를 뺀 앱 기준 경로"로 정하고,
클릭 어댑터가 앱 루트의 pathname(끝 / 제외)을 앞에 붙여 openWindow
대상을 만든다. handoff path는 registry 값 그대로 둔다. same-origin·
userinfo·hash 검사(safeTarget)는 그대로 거친다. 규칙은
WebPushNotificationDefinition.path 주석, appRootUrl 주석, 설계 8.5절에
적었다. 앱 루트가 origin 루트(기본값)면 결과가 전과 같다.

버린 대안: 리뷰가 적은 `new URL(path.slice(1), appRootUrl)`. 앱 루트가
/로 끝나지 않으면(`https://host/app`) 마지막 segment가 사라지고,
`/a:b` 같은 경로는 `a:b`가 scheme으로 읽혀 거절된다. pathname을 앞에
붙이면 두 경우 모두 의도대로 된다.

위험·한계:
- realtime 레시피 번들(web-push 포함) 40,879 -> 40,897 / 40,900 gzip
  B(+18 B, 여유 3 B). 예산은 그대로다. 다음 realtime·web-push 변경은
  예산 인상과 함께 와야 한다.
- 페이지가 handoff path를 basename 기준으로 쓰는지는 제품 코드 몫이라
  확인하지 않았다(템플릿에는 handoff 소비자가 없다).
- 실제 브라우저·푸시 서비스에서는 실행하지 않았다.

검증:
- RED: 새 테스트 "opens an accepted click's route under the base
  path"가 수정 전 openWindow 인자 `https://app.example.test/inbox`
  (기대 `https://app.example.test/app/inbox`)로 실패(1 failed | 19
  passed).
- GREEN: 같은 테스트가 통과하고, 열린 창에는 handoff path `/inbox`가
  간다. `node scripts/run-vitest.ts run tests/unit/web-push
  tests/unit/sub-path-deployment.test.ts
  tests/unit/service-worker-web-push-remediation.test.ts` -> 8파일
  82건 통과(web-push-worker-runtime 20건 포함).
- `npx tsc` app·test·service-worker -> 오류 0.
- `npx eslint <바꾼 ts 3개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
  `node scripts/check-optional-recipes.ts` -> PASS(realtime
  40897/40900), `node scripts/verify-documentation-readiness.ts` ->
  PASS_SCOPED.

Refs: docs/reviews/2026-11-01-maturity-review/06-adapters-service-worker-push.md 06-01
2026-11-01 22:49:38 +09:00
DongHyeonka 3fe28dec2e fix(realtime): 배럴에서 결과 생성 함수를 내보내고 동결 규칙을 적는다 (04-01)
문제: reconnect coordinator, live/poll handoff, SSE onOpen·onEvent,
WS onSubscribed·onEvent는 받은 RealtimeResult를 2단계로 동결된
객체만 받는다. 타입은 Readonly일 뿐이라 같은 모양의 평범한 객체도
컴파일된다. 그런데 동결된 결과를 만드는 realtimeSuccess /
realtimeFailure는 result.ts에만 있고 배럴에 없다. 조합 코드는 배럴만
import할 수 있으므로 결과를 손으로 만들게 되고, 그러면 첫 실패나 첫
종료에서 PROTOCOL_MISMATCH·MAPPING_CONTRACT_VIOLATION으로 재시도
없이 끝난다. 이 규칙은 주석에도 없었고, reconnect 경계의 동결 검사
3곳을 지워도(MU4) 테스트가 모두 통과했다.

고른 방법: 리뷰 6.2절의 (b). 배럴 src/adapters/realtime/index.ts에서
두 함수를 export하고(추가만, 기존 시그니처 변화 없음), 엄격한 경계의
타입 주석(RealtimeReconnectOutcome, RealtimeReconnectSession,
confirmTransportBarrier, handoff apply·establishAuthoritativeCheckpoint,
SSE onOpen·onEvent, WS onEvent·onSubscribed)과 생성 함수 주석에 규칙을
적었다. 동결 규칙 자체와 DEFAULT_RETRYABLE 기본값은 그대로다.

버린 대안:
- (c) 엄격한 경계도 stream coordinator처럼 한 번 복사하기. 규칙이
  하나가 되지만 "검증한 실패 객체를 그대로 돌려준다"(toBe) 계약을
  깬다.
- (d) 생성 함수를 application port(shared.ts)에 두기. feature 코드도
  쓸 수 있게 되지만 application 계층에 런타임 헬퍼가 는다. handoff
  apply를 feature가 구현한다고 정해지면 그때 옮긴다.
- 런타임 오류 이름을 따로 두기(예: RESULT_NOT_FROZEN). failure kind
  어휘가 바뀌는 계약 변경이라 이번 범위 밖이다.

위험·한계:
- 동결하지 않은 결과는 여전히 컴파일된다. 타입으로 막으려면 brand가
  필요하고, 그건 공개 타입을 깨는 변경이다. 주석과 테스트로만 알린다.
- realtime 레시피 번들 40,863 -> 40,879 / 40,900 gzip B(+16 B, 여유
  21 B). 예산은 그대로다.

검증:
- RED: 새 테스트 "retries a failure built with the barrel's
  realtimeFailure"가 수정 전 `TypeError: realtimeFailure is not a
  function`으로 실패(1 failed | 43 passed).
- 새 테스트 4건(시도의 평범한 실패, 동결된 실패 안의 평범한 error,
  classifyClosed의 평범한 성공 -> PROTOCOL_MISMATCH, 재시도 없음)과
  handoff apply의 평범한 성공 -> MAPPING_CONTRACT_VIOLATION 1건.
- MU4(reconnect 동결 검사 3곳 제거)를 다시 넣으면 새 테스트 3건이
  실패한다(수정 전에는 생존).
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/` ->
  14파일 230건 통과.
- `npx tsc --project tsconfig.app.json --noEmit`,
  `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 파일 8개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS,
  `node scripts/check-adapter-inventory.ts` -> PASS,
  `node scripts/check-optional-recipes.ts` -> PASS(realtime 40879/40900).

Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 04-01, 6.2절
2026-11-01 22:49:38 +09:00
DongHyeonka ffb6782b0c fix(query): 무효화 topic이 닿지 않는 조회 namespace를 진단으로 알린다 (03-01)
문제
QueryDefinition의 namespace는 아무 문자열, namespaceVersion은 아무
숫자다. bindQuery는 이 둘로 쿼리 키를 만들 뿐 무효화 registry에 있는지
보지 않는다. 저장 뒤 무효화는 topic -> 등록 namespace 접두사로만 가므로,
namespace 오타나 version만 올린 조회, registry에 빠진 namespace의 조회는
저장 뒤에도 갱신되지 않는다. 오류도 진단도 없다(E7). 문서는 "query
namespace는 registry reference"라고 적지만(client-cache-and-storage.md),
참조 기능도 registry 객체에서 두 필드를 꺼내 문자열로 다시 넘긴다.

고른 방법
- 런타임 검사(리뷰 ②): cache coordinator가 QueryCache의 "added"
  이벤트를 구독한다. bindQuery 키 접두사(["query", 2, id, version])를
  읽어 registry 인덱스(topicsForNamespace)에 없으면 namespace당 한 번
  cache.operation.failed(operation: unregistered-query-namespace) 진단을
  남긴다. registry와 TanStack 키의 연결은 원래 이 coordinator가 갖고
  있으므로(무효화 접두사) 새 결합을 만들지 않는다. dispose 때 구독을 푼다.
- 정적 조회 예외: QueryDefinition에 선택 필드 invalidation: "NONE"을
  더한다. bindQuery가 BoundQuery로 옮기고, useApplicationQuery가 공유 상수
  QUERY_WITHOUT_INVALIDATION_META를 TanStack meta로 넣고, coordinator가 같은
  상수로 읽는다. 상수는 query-keys.ts에 둔다. server-state.ts에 두면
  coordinator(초기 청크)가 그 모듈 전체를 끌어와 초기 JS에 server-state
  청크가 하나 생긴다(측정: +1,407 B gzip, 파일 16 -> 17).
- 타입(리뷰 ①, 추가만): QueryDefinition.namespace가 registry의
  QueryNamespaceIdentity 객체를 그대로 받는다. 참조 기능의 두 조회는 등록
  객체를 넘긴다. 문자열 id + namespaceVersion 쌍도 계속 받는다.

버린 대안
- 문자열 쌍을 없애고 객체만 받기(리뷰 ①의 원안): 공개 타입 시그니처를
  깨서 다운스트림 조회 정의를 모두 고쳐야 한다. 이번 범위에서는 공개
  포트를 추가만 한다. 문자열 쌍의 오타는 위 진단이 잡는다.
- useApplicationQuery에서 검사하고 QueryInvalidationCoordinator에 메서드
  추가: 공개 인터페이스가 늘고, 다른 경로로 cache에 들어오는 bound 키는
  못 본다.
- 개발 빌드에서 throw(리뷰 ②): QueryCache 구독 콜백에서 throw하면 TanStack
  알림 경로가 깨진다. 진단 1건으로 완료 기준("타입 오류 또는 진단 1건")을
  채운다.
- 진단에 namespace id 싣기: id는 80바이트까지 허용돼 진단 값 문법(64자)을
  넘으면 기록 전체가 버려진다. id 없이 operation만 남겼다.

위험·한계
- 런타임 검사라 그 조회가 처음 cache에 들어갈 때(화면을 열 때) 드러난다.
- "등록은 했지만 edge가 없음"은 registry 인덱스가 시작 때 orphan
  namespace로 거절하므로 여기까지 오지 않는다.
- 진단에서 어느 namespace인지는 알 수 없다. 개수만 보인다.
- useApplicationQuery -> meta 연결은 타입 검사로만 확인했다. 그 경로의
  런타임 테스트는 없다.
- 공개 타입은 추가만 했다(QueryDefinition namespace 유니언, invalidation,
  BoundQuery.invalidation, 상수 1개).

검증
- RED(수정 전): tests/unit/tanstack-cache-coordinator.test.ts "reports a
  bound query whose namespace no registered topic reaches (03-01)" 실패.
  "expected vi.fn() to be called 2 times, but got 0 times".
- GREEN: 같은 파일 10/10, tests/features/reference-feature 포함 17 files /
  89 tests 통과. 변이 M20(참조 목록 조회 namespace를 문자열 오타 쌍으로)을
  넣으면 reference-page.test.tsx가 실패하는 것을 확인하고 원복했다.
- 회귀: run-vitest tests/unit tests/integration tests/component
  tests/features tests/contract tests/runtime-schema(pnpm을 언급하는 파일
  12개 제외) 228 files 중 227 통과, 2369/2370. 실패 1건은
  provider-guardian-transaction의 ENOSPC(inotify watcher 한도, 이 머신의
  다른 실행 때문)로 이 변경과 무관하다.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0.
  check-adapter-inventory PASS. verify-documentation-readiness PASS_SCOPED.
- 번들: build-frontend로 빌드해 check-bundle과 같은 분류로 초기 JS를
  gzipSync로 쟀다. 298201f 202,509 B(16 파일) -> 이 커밋까지 세 커밋 누적
  202,913 B(16 파일), +404 B. 예산 204,800 B. 예산은 바꾸지 않았다.
- 미실행: check:architecture(pnpm 스크립트 필요). depcruise 직접 실행은
  0 modules라 사실상 미검증이다. 새 import는 adapter -> contracts,
  presentation -> contracts뿐이다.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 22:42:44 +09:00
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 fc303d89bc refactor(contracts): 폐기 별칭 import를 새 이름으로 옮기고 lint로 막는다 (07-01)
문제
MappingResult라는 이름이 두 모양을 가리킨다. external-contract-runtime.ts의
MappingResult({ ok:false, error:{ kind, code } })는 주석이 "정본"이라고
부르지만 테스트 말고 쓰는 곳이 없다. boundary-mapper.ts는
{ ok:false, code } 모양을 BoundaryMappingResult로 이름 붙이고 같은 이름
MappingResult를 @deprecated 별칭으로 남겼는데, 실행 경로가 그 별칭을
요구한다(feature-http-binding mapSuccess, client.ts, resource-mapper,
참조 mapper, boundary-mapper 자신의 helper 반환 타입). 그래서 별칭의 제거
조건("이 파일에서 MappingResult를 import하는 모듈이 없을 때")이 충족될 수
없다. ApiFailure 별칭도 포트 2개와 참조 기능을 포함해 7개 파일이 쓴다.
eslint 설정에 폐기 검사가 없다.

고른 방법 (리뷰 최소 개선 (1)·(4)와 lint, 공개 이름은 그대로)
- boundary-mapper의 BoundaryMapper.map, mapWithBoundaryRegistry,
  mappingSuccess, mappingFailure와 바인딩 mapSuccess가
  BoundaryMappingResult를 반환한다. 참조 mapper·client·resource-mapper도
  옮겼다. ApiFailure를 쓰던 파일은 AppFailure를 쓴다. 타입이 같아서
  런타임과 공개 시그니처는 바뀌지 않는다.
- D-15 주석을 실제와 맞췄다. 기능 mapper와 HTTP 바인딩은
  BoundaryMappingResult(닫힌 실패 코드)를 반환하고, 계약 패키지 쪽 결과가
  필요하면 toContractMappingResult로 바꾼다. 참조 기능 README의 "ApiFailure는
  같은 type의 alias" 문장도 고쳤다.
- 폐기 검사: 이 repo의 ESLint는 babel 파서라 타입 정보가 없어
  @typescript-eslint/no-deprecated를 쓸 수 없다. 대신 core
  no-restricted-imports의 patterns.importNames로 boundary-mapper의
  MappingResult와 errors의 ApiFailure import를 src·tests 전체에서 막는다.
  층별 no-restricted-imports 설정이 같은 규칙을 덮어쓰므로
  restrictedImports()가 별칭 패턴을 항상 덧붙이고, 층 규칙이 없는 파일은
  그 앞에 둔 공통 블록이 받는다.

버린 대안
- 별칭 export 삭제와 정본 이름을 ContractMappingResult로 바꾸기(리뷰 (2)
  후반·(3)): 다운스트림 import를 깨는 공개 이름 변경이다. 이번 묶음 규칙상
  공개 시그니처를 깨는 변경은 하지 않는다. 별칭 주석에 "repo 안 사용 0,
  lint로 강제, 제거는 minor 릴리스 + CHANGELOG [계약] 행"을 적었다.
- typescript-eslint 도입 후 no-deprecated: 새 의존성과 type-aware lint
  설정(속도·설정 범위)이 필요하다.
- 바인딩이 정본 모양을 받게 바꾸기(리뷰 C): 실패 코드가 닫힌 3종에서 자유
  문자열로 넓어져 계약이 약해진다.

위험·한계
- 이름 MappingResult는 여전히 두 파일에서 export된다(한쪽은 폐기 별칭).
  리뷰 완료 기준("MappingResult export 하나, grep 0건")은 별칭을 지워야
  충족된다. 제거 시점은 릴리스 결정으로 남긴다.
- 다운스트림이 eslint.config.ts를 동기화하면 그쪽의 별칭 import가 lint
  오류가 된다. 이름만 바꾸면 된다(tech-log는 mappingSuccess를 쓰는데,
  반환 타입은 같은 모양이라 영향 없음).
- adapters/http의 client.ts·feature-http-binding.ts는 타입 이름만 바꿨다.
  같은 파일을 고치는 다른 수정과 합칠 때 줄 단위 충돌이 날 수 있다.

검증
- RED: 규칙만 먼저 넣고 eslint src tests -> 9개 파일 11 errors
  ("'MappingResult' import from '../../contracts/boundary-mapper.ts' is
  restricted ... deprecated alias: import BoundaryMappingResult", ApiFailure
  같은 꼴).
- GREEN: lint 전체 범위(src scripts tests recipes .storybook 설정 파일)
  --max-warnings=0 rc=0. src에서 별칭을 쓰는 곳은 정의 줄뿐(git grep).
- 회귀: tsc app/test/node rc=0. run-vitest tests/architecture tests/unit
  tests/features tests/platform tests/component tests/contract
  tests/runtime-schema tests/integration(pnpm·corepack을 띄우는 4파일 제외)
  273 files / 3136 tests 중 3135 통과. 실패 1건은
  provider-guardian-transaction(guardian exit=126, 단독 실행도 같음, 이
  변경과 무관한 scripts/lib 프로세스 테스트).
  check-registries PASS, verify-documentation-readiness PASS_SCOPED,
  check-adapter-inventory PASS.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 0 modules로
  사실상 미검증.

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka 3c31576940 test(contracts): V2 행과 V3 descriptor를 양방향과 스키마 id까지 맞춰 본다 (07-02)
문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.

고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
  V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
  commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
  요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
  (V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
  응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
  대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
  정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
  게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.

버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
  V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
  변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
  defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
  생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
  이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
  비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
  fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
  parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.

위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
  않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
  주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
  zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
  파일을 돌려야 걸린다.

검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
  L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
  ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
  ("responseSchema": "ReferenceResourcePayload" vs "...V2").
  L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
  "cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
  함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka c06338956e fix(contracts): 참조 기능 밖의 TEMPLATE_FIXTURE 기여를 거부한다 (07-04)
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.

고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
  ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
  쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
  기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
  있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
  (REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
  이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
  EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
  featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
  테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
  바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
  단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
  읽었는지 아닌지를 구분하지 못했다.

버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
  test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
  /REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
  잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
  남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
  필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
  depcruise로 볼 수 없다.

위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
  (라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
  스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
  복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
  거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
  측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
  꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
  참조 기능 id 하나로만 풀린다.

검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
  external-contract-runtime "rejects a fixture copied into a product
  feature" -> "Expected contract composition to fail."
  reference-fixture-provenance "rejects a second fixture contribution"
  -> "expected undefined to be 'reference-feature: only one
  TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features
  tests/platform tests/component tests/contract tests/runtime-schema
  tests/integration (pnpm·corepack을 띄우는 fixture-node-modules,
  security-followup-archive, deployment-admission, lab-performance 제외)
  267 files / 3107 tests 중 3106 통과. 실패 1건은
  provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로
  scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0.
- 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep).
- 미실행: test:sample-removal, check:architecture(pnpm 필요).

Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
2026-11-01 22:35:54 +09:00
DongHyeonka 68e88b081d fix(opfs): 객체를 못 지운 purge가 완료와 chunk sweep을 보고하지 않는다 (0929/05-02)
문제: OPFS purge는 remove가 CONFLICT·NOT_FOUND면 그 객체를 건너뛴다.
chunk sweep 조건은 "남은 객체가 없다"가 아니라 !moreObjectsAvailable
&& !deadlineReached && !aborted라서, 다른 탭이 같은 객체를 덮어쓰는 동안
ACCOUNT_DELETION purge를 부르면 {removedObjects: 0,
moreObjectsAvailable: false, chunkSweep: "COMPLETED"}를 돌려준다. 객체와
chunk는 남아 있는데 보고는 완료로 읽힌다. port 주석은 sweep이 "once
every object is removed"라고 약속하고 runbook도 COMPLETED를 완료
조건으로 적는다.

고른 방법: 지난 리뷰의 첫 방향. 건너뛸 때 moreObjectsAvailable을 true로
두어 report가 미완료를 드러내고 sweep 조건이 sweep을 막게 한다
(chunkSweep 칸이 빠진다). port 계약은 바꾸지 않고 코드를 기존 주석에
맞춘다. 이 값을 뒤에서 false로 되돌리는 대입이 없다는 근거(다음
페이지로 넘어가는 대입은 그 페이지에 객체가 더 있을 때만 실행되고,
PRESSURE는 sweep하지 않는다)를 코드 주석에 적었다. port의
moreObjectsAvailable 주석과 runbook에 "다시 호출한다"를 더했다.

버린 대안:
- skippedObjects 칸을 report에 더하고 완료 조건을 "skippedObjects === 0
  그리고 COMPLETED"로 고친다: port 추가와 문서 조건 변경이 필요하고
  번들도 더 커진다. offline-indexeddb 예산 여유가 9 B뿐이다.
- 따로 skipped 플래그를 두고 끝에서 합친다: 같은 동작에 바이트가 더 든다.

위험·한계:
- offline-indexeddb 레시피 번들 36,891 -> 36,896 / 36,900 gzip B.
  예산은 올리지 않았지만 여유가 4 B로 줄었다([0929] 05-04).
- 별도로 발견했고 고치지 않은 것: 여러 페이지에 걸친 purge는 마지막
  페이지의 OR 대입이 앞 페이지에서 넘어올 때 넣은 true를 유지해, 다
  지워도 moreObjectsAvailable true를 보고하고 sweep하지 않는다. 보수적
  방향이라 다시 부르면 끝나지만 한 번에 끝나지 않는다. 코드로만
  확인했고 실행하지 않았다. 동작 변경이라 범위 밖.
- 실제 브라우저(Playwright OPFS spec)에서는 돌리지 않았다.

검증:
- RED: opfs-worker-runtime "reports a purge that skipped a changing object
  as unfinished"가 `- "moreObjectsAvailable": true`
  `+ "moreObjectsAvailable": false`로 실패(removedObjects 0, 6번째 칸
  chunkSweep 존재).
- GREEN: 같은 파일 64/64 통과. 두 번째 purge가 removedObjects 1,
  chunkSweep COMPLETED, partition 파일 0개로 끝난다.
- 회귀: opfs-worker-runtime, opfs-byte-store, indexeddb-opfs-journal,
  indexeddb-local-draft 4파일 104/104 통과. tsc app·test·web-worker·
  recipes 통과, eslint 통과, verify-documentation-readiness PASS_SCOPED,
  check-optional-recipes PASS.

Refs: docs/reviews/2026-09-29-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka cc011bc740 docs(platform): kernel 주석의 줄 번호 참조를 심볼 이름으로 바꾼다 (05-05)
문제: kernel 주석이 근거를 다른 파일의 줄 번호로만 준다. 줄이 밀려
참조 20개 중 19개가 엉뚱한 코드를 가리킨다. 예를 들어
indexeddb-transaction.ts의 "runtime은 지운 행 수로 예산을 잰다"는
indexeddb-runtime.ts:2384를 가리키는데 그 줄은 cursor 삭제 onerror다.
네 벌의 transaction 상태 기계를 가리키는 참조 넷은 kernel 이전 코드라
이미 없다(네 어댑터 모두 지금은 runIndexedDbTransaction을 쓴다).

고른 방법: 리뷰 권고대로 줄 번호 대신 심볼 이름을 쓴다.
- purgeEligibleRecords, scanBatch, monotonicClock, runCheckpointTransaction,
  bindScope, 체크포인트 store의 translate, BT-UP-03,
  restrictedBrowserDataProperties, browser-data-boundary 예외 목록,
  REQUIRED_ABORT_CONSUMERS.
- 없어진 코드를 가리키던 역사 설명은 "IDB-X-02 이전에는 네 벌이
  달랐다", "runtime의 kernel 이전 fail/requestFailed 의미"처럼 ID와
  과거형으로 줄였다. "runtime이 지금 inline으로 한다"처럼 더는 사실이
  아닌 문장은 지웠다.
- 유일하게 맞던 abortable-operation.ts:11도 같은 규칙으로 줄 번호만
  뺐다(심볼 AbortTerminalReason이 이미 문장에 있다).

버린 대안: 줄 번호를 지금 위치로 다시 맞추기. 다음 수정에서 또 밀린다.

위험·한계: 주석만 바뀐다. 코드·번들 크기(주석은 minify에서 빠짐)는
그대로다. 심볼 이름도 이름이 바뀌면 낡지만 grep으로 바로 찾을 수 있다.

검증:
- RED(문서·코드 대조): platform/·browser-file-storage/의
  `grep -rnE '\.(ts|json|md|mjs):[0-9]+'` 20건을 스크립트로 열어 대조.
  19건이 다른 코드(예: check-adapter-inventory.ts:63-83은 INVENTORY 중복
  행 검사, eslint.config.ts:519-530은 블록 끝 "},"), 1건만 맞음.
- GREEN: 같은 grep 0건. 새로 적은 심볼은 모두 해당 파일에 있는 것을
  확인했다.
- 회귀: indexeddb-transaction, indexeddb-connection, browser-lifecycle
  3파일 66/66 통과. tsc app 통과, eslint 통과, check-adapter-inventory
  145 files PASS.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +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 12c23feba9 fix(storage): 저장소 진단 이벤트에 실패 원인을 싣는다 (05-02)
문제: Web Storage 어댑터의 실패 원인은 QUOTA_EXCEEDED,
SIZE_LIMIT_EXCEEDED, UNAVAILABLE, VALUE_REJECTED 넷이다. 진단 이벤트
storage.operation.failed는 error_kind에 quota면 STORAGE_QUOTA_EXCEEDED,
나머지는 모두 STORAGE_UNAVAILABLE을 넣고 원인을 버린다. 그래서 운영자는
"브라우저 저장소를 못 쓴다"와 "저장된 값이 깨져서 버렸다"를 같은
이벤트로 본다. 호출자에게 주는 실패 code에는 원인이 이미 들어 있다.

고른 방법: recordStorageFailure의 context에 reason: cause를 더한다.
reason은 진단 계약의 허용 칸(taxonomy)이고 원인 값은 어댑터의 닫힌
유니온이라 cardinality가 늘지 않는다. projectDiagnosticRecord에 넣어
칸이 그대로 남는 것을 확인했다.

버린 대안: error_kind를 원인별로 나누는 것. error_kind는 createFailure의
error kind taxonomy와 맞춰져 있어, 값을 늘리면 그 taxonomy를 바꿔야
한다. 이미 있는 reason 칸에 싣는 쪽이 추가만으로 끝난다.

위험·한계: 진단 이벤트에 칸이 하나 는다(추가만). 수집기가 reason을
바깥으로 내보내는지는 영역 03 소관이라 보지 않았다.

검증:
- RED: storage-registry의 quota, discard 3종(malformed, invalid
  envelope, oversized), oversize write 테스트 5개가 실패.
  예: "expected vi.fn() to be called with arguments" 차이
  `- "reason": "VALUE_REJECTED"`.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, runtime-adapters, diagnostics,
  release-mismatch-recovery 4파일 68/68 통과. tsc app·test 통과,
  eslint 통과.

Refs: docs/reviews/2026-11-01-maturity-review/05-adapters-storage-kernel.md
2026-11-01 22:25:41 +09:00
DongHyeonka e98a980dff fix(storage): pulse 키를 외부 소유로 적어 StoragePort가 거절한다 (05-01)
문제: registry의 CACHE_INVALIDATION_PULSE 행은 backend localStorage,
valueCodec opaque-string-v1이다. 실제로 이 키에 쓰는 쪽은 cross-context
어댑터이고 envelope 없는 wire JSON을 setItem으로 바로 쓴다. 그래서
StoragePort로 read하면 Web Storage 어댑터가 값을 손상 envelope로 보고
물리 키를 지우고, write하면 envelope 문자열로 덮어써 수신 탭이 버린다.

고른 방법: StorageBackend에 "external"을 더하고 pulse 행을
backend external, valueCodec none으로 바꾼다. getStorageDefinition이
external 키를 던지므로 어댑터의 read/write/remove는 물리 키를 건드리지
않고 *_UNAVAILABLE 실패를 돌려준다. defineStorageKey는 external 키에
codec이 붙으면 거절해 같은 거짓 행이 다시 생기지 않게 한다. 물리 키
문자열 ca-frontend:cache-invalidation:v1:pulse와 wire 형식은 그대로다.
registry-governance의 backend 허용값에 external을 더하고, breaking
필드 변경 두 건은 registry-change-evidence에 근거를 남긴다(baseline
재승인 대신 기존 08-13·F-6과 같은 evidence 방식).

버린 대안:
- 행 위 주석만: 가장 싸지만 StoragePort 호출을 막지 못한다.
- cross-context 어댑터가 StoragePort로 쓰게 함: storage 이벤트의
  newValue 형식이 바뀌어 이미 배포된 탭과 서로 못 읽는다.

위험·한계: StoragePort 공개 시그니처는 그대로다. StorageBackend
유니온에 값이 하나 늘어(추가만) exhaustive switch를 쓰는 다운스트림은
분기를 더해야 한다. check:registries 결과는 compatibility=breaking
(evidence로 통과)다. 기본 구성에는 이 키를 StoragePort로 쓰는 호출이
없어 실제 동작 변화는 없다.

검증:
- RED: storage-registry "refuses the externally owned pulse key..."가
  "expected { ok: true, value: undefined } to match object { ok: false }"
  로 실패(손상 discard 경로), codec 거절 테스트는 "expected [Function]
  to throw an error"로 실패.
- GREEN: 같은 파일 23/23 통과.
- 회귀: storage-registry, registry-governance, cross-tab-invalidation,
  contract-registry-lookup, browser-security, runtime-adapters,
  release-mismatch-recovery 7파일 87/87 통과. tsc app·test 통과,
  eslint 통과, check-registries PASS, verify-documentation-readiness
  PASS_SCOPED. check:architecture는 pnpm 실행을 요구해 미실행.

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 d2a882fde6 fix(presentation): 좁은 화면에서 테마 선택과 세션 상태를 메뉴 서랍에 둔다 (08-01)
문제: 폭 48rem 미만(휴대폰, 1280px 창의 약 170% 이상 확대)에서
responsive.css가 머리글의 색상 테마 선택, 세션 상태, 브랜드를
display: none으로 숨긴다. 메뉴 서랍에는 주요 탐색만 있어서 이 기능과
정보를 쓸 곳이 없다. WCAG 2.2 1.4.10(Reflow)의 "기능·정보 손실 없이"
조건을 어긴다.

고른 방법: 머리글은 지금처럼 두고, 서랍에 브랜드 이름(탐색 위)과 색상
테마 선택·세션 상태(탐색 아래)를 넣는다.
- 테마 선택과 세션 상태를 app-shell.tsx 안의 ThemePreferenceSelect,
  SessionStatus로 뽑아 머리글과 서랍이 같은 컴포넌트를 쓴다. 둘 다
  기존 ThemeProvider·SessionProvider를 직접 읽어 따로 든 상태가 없다.
- 서랍 쪽 select id는 mobile-theme-preference로 달리 줘서 id가 겹치지
  않는다. 머리글 #theme-preference는 그대로다(시각 테스트가 쓴다).
- 서랍 쪽은 라벨을 보이게 두고 theme-selector 클래스를 붙이지 않는다.
  그래서 i18n.spec의 "머리글 선택 상자 2개" 검사가 그대로 맞는다.
- 브랜드는 화면을 보고 서랍 위쪽에 링크가 아닌 글자로 넣었다. 서랍에
  "홈" 링크가 이미 있어 링크로 두면 같은 곳으로 가는 Tab 정지가 는다.
- 숨김 규칙(responsive.css)과 머리글(app-shell.tsx)에 서랍이 대신
  보여 준다는 주석을 달았다.

버린 대안:
- 머리글에 테마 아이콘 메뉴 버튼(리뷰 5.3 (C)): 새 컴포넌트가 필요하고
  320px 머리글 공간을 다툰다. 머리글은 단순하게 두기로 정했다.
- 서랍이 열릴 때만 서랍 쪽 컨트롤을 렌더: DOM 중복은 없어지지만 탐색은
  항상, 나머지는 조건부로 그리는 이유가 코드에 드러나지 않는다. 탐색이
  이미 사이드바와 서랍에 두 벌 있는 방식에 맞췄다.
- 서랍 제목을 앱 이름으로 바꾸기: 대화상자 이름 "메뉴"가 바뀌어 기존
  접근성 이름과 테스트가 깨진다.

위험·한계:
- 세션 상태 문구와 테마 select가 DOM에 두 벌 있다. 접근성 트리에는
  한 번만 나온다(좁은 폭은 머리글 쪽이 display: none, 넓은 폭은 닫힌
  dialog). 다만 페이지 전체에서 getByText로 셸 문구를 찾는 테스트는
  strict mode에 걸린다. reference-route.spec의 "인증됨"을 banner로
  좁혔다. 다운스트림 테스트도 같은 수정이 필요할 수 있다.
- 640x400(200% 확대)에서는 테마 선택이 서랍 첫 화면 아래에 있어 서랍을
  스크롤해야 보인다.
- 좁은 화면 서랍 화면이 바뀐다. 시각 골든
  app-shell-compact-pseudo-drawer.png는 이 커밋에서 갱신하지 않았다.
- 초기 JS gzip 203,572 -> 203,648 B(+76 B, 예산 204,800 B). check:bundle은
  pnpm을 불러 돌리지 않았고, 같은 분류(classifyViteJavascript)와
  gzipSync로 직접 쟀다.
- 실제 기기 터치, 스크린 리더 발표는 확인하지 않았다.

검증:
- RED: tests/e2e/responsive.spec.ts 새 테스트(320·375·640px)가 수정 전
  chromium·firefox·webkit 9/9 실패. getByRole('dialog', { name: '메뉴' })
  .getByRole('combobox', { name: '색상 테마' }): element(s) not found.
- GREEN: 같은 테스트 9/9 통과. 마지막 탐색 링크에서 Tab으로 테마 선택에
  닿고, dark·light 선택에 html[data-theme]이 바뀐다. 서랍에 "로그인 전"과
  브랜드가 보인다.
- 회귀 e2e: responsive·i18n·theme·accessibility·app-shell·reference-route
  (세 엔진) + compact-smoke(chromium-compact) 85/85 통과. app-shell.spec의
  Esc 닫기·포커스 복원·서랍 링크 뒤 h1 포커스 포함. 수정 전에는
  reference-route가 세 엔진에서 strict mode로 실패하는 것을 확인했다.
- 열린 서랍 axe(375px, light·dark, 세 엔진) 위반 0(일회성, 커밋 안 함).
- node scripts/run-vitest.ts run tests/component: 211/211 통과.
- tsc(app·test·node) 0, eslint(바꾼 tsx·spec) 0, check-design-system
  PASS, check-architecture(pnpm 대신 exec 전용 shim) PASS.
- Playwright는 webServer만 `npx vite preview`로 바꾼 임시 설정으로
  돌렸다(빌드는 node scripts/build-frontend.ts).

Refs: docs/reviews/2026-11-01-maturity-review/08-presentation.md 08-01
2026-11-01 20:32:47 +09:00
DongHyeonka 4d27b2071e fix(realtime): 서버만 끊긴 OFFLINE 실패를 online 대기 없이 재시도한다 (0929/04-01)
문제: SSE 어댑터는 fetch 거절과 열린 스트림의 reader 거절을 모두
OFFLINE(retryable)으로 보고한다. reconnect coordinator는 transport가
OFFLINE을 보고하면 requireOnline()으로 "새 online 이벤트"를 요구했다.
서버만 내려가거나 프록시가 연결을 끊으면 브라우저 navigator.onLine은
true 그대로라 online 이벤트가 오지 않는다. run이 재시도도 종료도 없이
RUNNING으로 멈췄다(리뷰 재현: 20분 동안 fetch 1회, 결과 없음).

고른 방법: 수정안 b. coordinator의 attempt 실패 경로와 classifyClosed
경로에서 transport OFFLINE 뒤의 requireOnline() 두 줄을 지운다. 이제
transport OFFLINE은 다른 retryable 실패처럼 backoff로 재시도하고, 시도
상한이나 elapsed 상한에 닿으면 마지막 실패로 끝난다. online 대기는
환경 신호(observeOnline(false))가 offline을 알렸을 때만 한다.
- 리뷰의 MU1은 "&& !online" 조건을 붙이는 방식이었다. 두 지점에
  닿을 때 online은 항상 true다. 그 사이에 offline이 오면 wentOffline
  분기가 먼저 받고, observeOnline(false)가 이미 requireOnline()을
  부른다. 그래서 조건을 붙이는 것과 줄을 지우는 것은 동작이 같고,
  지우는 쪽이 짧다.
- 규칙은 RealtimeReconnectEnvironment 주석과 설계 5.3절에 적었다.

버린 대안: 수정안 c(SSE가 네트워크 거절을 PROVIDER_UNAVAILABLE로
보고). SSE 한 곳의 어휘만 바뀌고 coordinator의 함정은 남는다. 조합
코드가 classifyClosed에서 OFFLINE을 돌려주거나 다른 transport가
OFFLINE을 보고하면 같은 방식으로 멈춘다. OFFLINE을 보고 화면에
"오프라인"을 띄우는 소비자의 분류도 바뀐다. b는 모든 transport가
지나는 한 곳에서 고친다. (d) online 대기에 상한 시간을 두는 방식은
상수와 상태가 늘어서 버렸다.

위험·한계:
- 환경 offline 이벤트보다 transport 실패를 먼저 보면, 첫 backoff
  타이머가 잡힌다. offline 이벤트가 오면 그 sleep을 끊고 online을
  기다린다(새 테스트 "after"가 고정). offline 이벤트가 타이머보다
  늦게 오면 헛시도가 한두 번 생길 수 있다. 시도 상한 안이다.
- lie-fi(브라우저는 online, 실제 네트워크 없음)에서는 이제 상한까지
  재시도한 뒤 OFFLINE으로 끝난다. 설계 5.3의 "budget 소진 뒤
  fallback"과 같다.
- 0929/04-02(열린 SSE 세션 bridge 부재)는 그대로다. 테스트 안의
  sseAttempt는 설계 6.3이 조합 코드에 맡긴 최소 bridge다.
- 설계 문서의 reconnect-coordinator.ts 줄 번호를 새 위치로 고쳤다.
- 레시피 번들(realtime): 40,886 -> 40,863 / 40,900 gzip B. 예산은
  바꾸지 않았다.

검증:
- RED(수정 전): `node scripts/run-vitest.ts run
  tests/unit/realtime/realtime-reconnect-coordinator.test.ts`
  -> X1·X2 2건 실패 "expected "vi.fn()" to be called 3 times, but
  got 1 times". 실제 offline 대기 테스트 2건(before/after)은 통과.
- GREEN: `node scripts/run-vitest.ts run tests/unit/realtime/`
  -> 14파일 225건 통과(기존 221 + 새 4).
- 변이: 수정 위에 MU2(SSE 거절 -> PROVIDER_UNAVAILABLE)를 넣으면 X1·X2
  2건 실패.
- `node scripts/run-vitest.ts run tests/unit` -> 165파일 2357건 통과.
- `npx tsc --project tsconfig.app.json --noEmit`,
  `npx tsc --project tsconfig.test.json --noEmit` -> 오류 0.
- `npx eslint <바꾼 ts 2개> --max-warnings=0` -> 통과.
- `node scripts/check-realtime-boundaries.ts` -> PASS.
- `node scripts/verify-documentation-readiness.ts` -> PASS_SCOPED.
- `node scripts/check-optional-recipes.ts` -> PASS, realtime 40863/40900.
- 미실행: check:architecture(pnpm을 띄운다). depcruise 직접 실행은
  0 modules로 끝나 의미가 없다. import는 바꾸지 않았다.

Refs: docs/reviews/2026-11-01-maturity-review/04-adapters-realtime.md 2절, 6.1절
2026-11-01 19:11:24 +09:00