Commit Graph
247 Commits
Author SHA1 Message Date
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
DongHyeonka 112c870fe3 fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)
문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).

고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.

버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
  NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
  같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
  APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
  틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
  변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
  목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
  응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
  요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
  만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.

위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
  contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
  적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
  고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
  백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
  (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
  템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
  Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
  참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
  referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
  code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
  (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
  이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
  "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
  확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
  run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
  두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.

검증
- RED(수정 전): reference-production-vertical "keeps the key when the
  resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
  분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
  (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
  카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
  tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
  제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
  PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
  읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
  check:ci 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
2026-11-01 19:09:47 +09:00
DongHyeonka 3a0ac74d4e fix(design-system): 입력란 테두리가 --field-border 토큰을 읽게 한다 (12-01)
문제: .ui-field__input 테두리는 계약 토큰 --field-border 대신
color-mix(in oklab, var(--color-content-muted) 55%, var(--color-panel))
를 직접 쓴다. 제품이 --field-border로 입력란 테두리를 바꿔도 화면이
그대로다. 이 식은 패널 대비 라이트 2.53:1, 다크 2.98:1이라 WCAG
1.4.11이 입력란 경계에 요구하는 3:1보다 낮다. check:design-system은
var(--field-border-invalid) 글자를 --field-border의 독자로 세어 이것을
놓쳤다(검사 수정은 다음 커밋).

고른 방법: 테두리가 var(--field-border)를 읽게 한다. 토큰값은 계약
그대로 --color-border-strong이다.
버린 대안: 토큰값을 지금 계산식으로 바꾸기. 화면은 안 바뀌지만 3:1
미달을 토큰에 굳히고, 다크 테마에서도 계약의 border-strong과 따로
노는 색이 남는다.

위험·한계: 입력란 테두리가 두 테마 모두 진해진다(화면 변경). 시각
골든은 이 커밋에서 갱신하지 않았다. 대비는 계산값이고 브라우저 실측은
하지 않았다.

검증: scripts/lib/oklch-contrast.ts로 --field-border 대비를 계산했다.
- light: panel 6.52, surface 6.24, surface-muted 5.47, elevated 6.52
- dark:  panel 4.19, surface 4.54, surface-muted 3.74, elevated 3.90
- 바꾸기 전 식(oklab로 직접 섞은 값): light 2.53, dark 2.98(panel 대비)
node scripts/check-design-system.ts PASS.

Refs: docs/reviews/2026-11-01-maturity-review/12-guardrails-ci.md 12-01
2026-11-01 19:07:05 +09:00
DongHyeonka ddf411e4e2 fix(bootstrap): ANONYMOUS 프로필 요청을 세션 상태와 상관없이 보낸다 (09-01)
조립 루트의 attachCredentials가 operation의 인증 프로필을 보지 않고
세션 상태만 본다. 그래서 auth: "none" operation(ANONYMOUS 프로필)이
로그아웃이면 UNAUTHENTICATED, 로그인이면 세션 헤더가 붙어
CREDENTIAL_HEADER_NOT_ALLOWED로 거절되고, 외부 owner가 없으면
CREDENTIAL_OWNER_UNAVAILABLE로 끝난다. 어느 상태에서도 fetch가 0회다.

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

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

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

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

Refs: docs/reviews/2026-11-01-maturity-review/09-app-core.md 09-01
2026-11-01 19:07:05 +09:00
DongHyeonka 5008013db2 fix(design-system): 표 스크롤 영역에 표 제목으로 이름을 붙인다 (UI-08)
표를 감싼 스크롤 영역이 키보드 포커스(tabIndex 0)를 받지만 역할과
이름이 없었다. 스크린 리더가 이름 없는 정지점으로 읽었다.

영역에 role="region"을 주고 caption을 aria-labelledby로 연결했다.

위험: 없음. 시각 변화가 없다.
검증: 이름 있는 region을 요구하는 컴포넌트 테스트가 고치기 전 실패했고,
고친 뒤 통과했다(design-system-platform.test.tsx 10/10).
2026-11-01 18:34:28 +09:00
DongHyeonka 9363fa84e3 refactor(examples): 예제 화면 머리글의 반복 "예제" 라벨을 지운다 (UI-06)
예제 화면 4곳이 제목 위에 같은 "예제" 라벨을 달았다. 이미 예제 메뉴
묶음 안에 있는 화면이라 정보가 없고, 예제를 복사하면 이 구성도 따라간다.

예제 화면의 eyebrow만 지웠다. PageHeader의 eyebrow 속성은 남겼다.
접근 상태 화면과 홈은 의미 있는 라벨을 쓴다. 검사는 넣지 않았다.
지울 수 있는 예제 화면의 문구라 검사 비용이 더 크다.

위험: 없음. 예제 화면은 i18n 검사 대상이 아니다.
검증: lint, check:types:app 통과. 시각 골든에 반영했다.
2026-11-01 18:34:28 +09:00
DongHyeonka 8576ce16c7 fix(design-system): --font-sans가 실제로 그려지는 글꼴을 가리키게 한다 (UI-05)
토큰이 Inter로 시작했지만 Inter를 불러오는 코드가 없었다. Inter가
없는 기기는 자기 글꼴로 그렸고, Inter에는 한글이 없어 한국어는 처음부터
Inter로 그려지지 않았다.

토큰을 시스템 UI 글꼴과 플랫폼별 한국어 글꼴 목록으로 바꿨다(사용자
결정). 한글 웹폰트 배포는 버렸다. 전송량과 글꼴 파일 관리가 생기고,
중립 템플릿에서는 서비스가 브랜드 글꼴로 바꾸면 되기 때문이다.
check:design-system이 첫 글꼴이 기본 키워드도 아니고 @font-face로 싣지도
않으면 실패한다.

위험: OS마다 글꼴 모양이 다르다. 시각 테스트 실행 환경의 글꼴 고정은
아직 남았다(UI-05 후반).
검증: 바꾸기 전 검사가 Inter를 보고했고, 바꾼 뒤 통과했다.
2026-11-01 18:34:28 +09:00
DongHyeonka f1b9d3c953 fix(shell): 테마·언어 선택 상자가 옵션 폭만큼 넓어지게 한다 (UI-04)
max-width 8.5rem과 7rem 때문에 모든 언어에서 선택값이 잘렸다
("Light then", "Englisl", "라이트 테ㅁ"). 커밋된 시각 골든에도 잘린
머리글이 들어 있어, 시각 테스트가 결함을 정답으로 지키고 있었다.

고정 폭을 지웠다. 좁은 화면은 기존 메뉴 서랍 배치가 그대로 맡는다.
새 i18n e2e 테스트가 ko-KR, en-US, en-XA에서 선택 상자 폭을 브라우저가
옵션에 필요한 폭과 비교한다.

위험: 중간 폭에서 머리글이 넓어진다. responsive·app-shell·theme·compact
테스트가 통과했다.
검증: 새 테스트가 고치기 전 실패했고, 고친 뒤 chromium·firefox·webkit
모두 통과했다.
2026-11-01 18:34:28 +09:00
DongHyeonka 165ed19968 fix(design-system): 컴포넌트 토큰을 복사하지 않고 읽게 한다 (UI-03)
계약에 있는 컴포넌트 토큰 4개를 읽는 스타일이 없었다. 기본 버튼은
bg-action을 직접 썼고, 현재 메뉴는 --navigation-active-background의
계산식을 다시 적었다. 그래서 서비스가 이 토큰으로 브랜드를 바꿔도
화면이 바뀌지 않았다.

기본 버튼과 현재 메뉴가 토큰을 읽게 했다. 변형 버튼은 뒤에 오는 같은
우선순위 규칙이라 그대로 덮어쓴다. check:design-system이 계약의
컴포넌트 토큰을 읽는 스타일이 하나도 없으면 실패한다.

위험: 기본 버튼 배경 지정 방식이 utility에서 토큰으로 바뀐다.
보이는 색은 같다.
검증: 바꾸기 전 검사가 토큰 4개를 보고했고, 바꾼 뒤 통과했다.
2026-11-01 18:34:28 +09:00
DongHyeonka bfa7dd9188 fix(design-system): 색 혼합을 oklab으로 해서 무채색이 색상각을 끌어오지 않게 한다 (UI-02)
라이트 테마에서 현재 메뉴 배경이 파랑이 아니라 분홍으로 그려졌다.
color-mix(in oklch, action 14%, panel)에서 panel이 oklch(1 0 0)으로
색상각 0을 명시해, 보간된 색상각이 255에서 345로 끌려갔다.

15곳의 혼합을 모두 in oklab으로 바꿨다. oklab에는 보간할 색상각이
없다. 흰색을 oklch(1 0 none)으로 바꾸는 방법은 버렸다. 앞으로 생길
무채색 토큰마다 같은 규칙을 기억해야 하기 때문이다.
check:design-system이 oklch·lch·hsl·hwb 혼합을 실패로 처리한다.

위험: 섞인 색이 미세하게 달라진다. 시각 골든을 갱신했다.
검증: 바꾸기 전 검사가 15곳을 보고했고, 바꾼 뒤 통과했다.
2026-11-01 18:34:28 +09:00
DongHyeonka 35b183b64f fix(design-system): 라이트 포커스 링이 모든 표면에서 3:1을 넘게 한다 (UI-01)
라이트 --color-focus가 흰 패널에서 2.33:1, surface-muted에서 1.95:1로
WCAG 1.4.11 기준(3:1)에 못 미쳤다. 포커스 링은 컨트롤에서 3px 떨어져
그려지므로, 대비를 따질 인접색은 컨트롤 뒤의 표면이다.

라이트 포커스를 oklch(0.52 0.15 230)으로 바꿨다. 가장 낮은 대비가
4.24:1이다. 다크는 그대로다. check:design-system이 두 테마에서 포커스
토큰과 표면 토큰 8종의 대비를 계산하고, 3:1 미만이면 실패한다.
안팎 이중 링은 버렸다. 한 색으로 충분하고 링 모양이 바뀌지 않는다.

위험: 포커스 링 색이 진해져 시각 골든이 바뀐다(별도 커밋에서 갱신).
검증: 토큰을 바꾸기 전 검사가 라이트 표면 8종 모두에서 실패했고,
바꾼 뒤 통과했다. 계산식은 브라우저 실측값 2.33:1과 일치한다
(tests/unit/oklch-contrast.test.ts).
2026-11-01 18:34:28 +09:00
donghyeon-kaandClaude Opus 5.5 33bf559bce fix(storage): check the fixed object id grammar at every write, not only by sample (05-10)
Resolving a policy only rejected predicates that admitted one of seven sample
ids, so a policy also allowing ':', '@' or letters passed BEGIN_PUT and failed
at FINISH_PUT. Writes now require the grammar alongside the policy, and the
samples cover those widenings so they are refused when the policy is resolved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 14:02:35 +09:00
donghyeon-kaandClaude Opus 5.5 0f35c985d8 fix(browser-transfer): release the vault slot on every exit of put() and open() (01-07)
Early returns before resolve (invalid input, pre-aborted signal, byte-length
mismatch) left the capability registered, so maxActiveCapabilities: 1 refused
the next issuance. The public methods now release it once in a finally.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:32:33 +09:00
donghyeon-ka 2b2cabb7f2 Merge lane/H: presentation (07-01, 08-02, 08-04, 08-05, 08-07~08-13, 11-02, F-10)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	config/contracts/registry-change-evidence.json
2026-09-27 13:19:31 +09:00
donghyeon-kaandClaude Opus 5.5 67117cc5a5 fix(forms): show unavailable save failures as a status, not an input error (F-10)
Save failures outside sign-in, permission and retry still went into
ErrorSummary under "review the entered information". They now reach
FormFailureStatus with their own copy and action; the unused copy is gone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:11:25 +09:00
donghyeon-kaandClaude Opus 5.5 d7b81c633d fix(reference): move the detail route under items/ (08-13)
The detail path /examples/reference-resources/:resourceId lost to the static
new and status routes, so an item with one of those ids opened the wrong
screen. The breaking route change carries registry evidence.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:09:06 +09:00
donghyeon-kaandClaude Opus 5.5 340acc55e9 Merge lane/G: contracts (07-02~07-07, 13-10, F-3, F-6, F-7)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:08:05 +09:00
donghyeon-kaandClaude Opus 5.5 cef6744299 fix(presentation): leave modified pagination clicks to the browser (08-12)
The page links prevented every click, so Ctrl/Cmd/Shift-click changed the page
in place instead of opening a new tab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:06:01 +09:00
donghyeon-kaandClaude Opus 5.5 96cf513485 Merge lane/F: service worker / web push (06-01~06-10, F-8)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:03:51 +09:00
donghyeon-kaandClaude Opus 5.5 a5fff8f4b7 fix(presentation): draw query access failures with the access surfaces (08-11)
AsyncSurface drew auth-required, forbidden and not-found query failures with
its own copy while the gallery used AccessSurface. Both now use one set, and
a state surface without a handler shows no dead button.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 13:03:27 +09:00
donghyeon-kaandClaude Opus 5.5 9dc95ca066 fix(contracts): set zod jitless before any schema is built so the production csp sees no eval (F-7, 13-08)
zod probed Function("") on its first object schema, which the production CSP
(no unsafe-eval) reported on every boot. Schema code now imports z from
src/contracts/zod.ts, enforced by a dependency-cruiser rule, and the CSP smoke
drops its init-script workaround.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 12:58:57 +09:00
donghyeon-kaandClaude Opus 5.5 ee9b09563a fix(presentation): re-translate form errors on locale change (08-10)
The form kept translated strings in state, so errors already on screen stayed
in the old language. It now keeps message keys and translates on render.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 12:58:46 +09:00
donghyeon-kaandClaude Opus 5.5 46417e3cff Merge lane/D: realtime (04-01~04-08)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-27 12:53:38 +09:00
DongHyeonkaandClaude Opus 5.5 dd7a44677b fix(web-push): open the registration scope for a refused click (06-09)
The fallback opened `${origin}/`, outside the app under a router base path.
The scope host now passes registration.scope and the click adapter opens it,
refusing any app root outside the origin.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:06:48 +09:00
DongHyeonkaandClaude Opus 5.5 9d61eacdc7 fix(reference): show the result count only for a settled list (08-09)
The count status said "checking results" next to a failure alert, and the
sample judged the state from `data` instead of `state.base`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:06:43 +09:00
DongHyeonkaandClaude Opus 5.5 dbe6b769bf fix(presentation): keep back-navigation scroll and open hash targets (08-08)
A direct link to /page#target stayed at the top: the target renders with the
lazy page, after the router scrolled up. PageHeader now scrolls to it below
the sticky header, focus never scrolls, and POP no longer scrolls to top.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:01:52 +09:00
DongHyeonkaandClaude Opus 5.5 8c17eab668 fix(service-worker): limit the previous-release fallback to build assets (06-08)
Any same-origin GET with a hashed-looking name, API and download URLs
included, was routed through the worker. The fallback now applies only under
the build asset directory of the registration scope.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 01:01:47 +09:00
DongHyeonkaandClaude Opus 5.5 3aacbd94da fix(browser-transfer): map checkpoint store IndexedDB errors with the shared table (F-1, 05-11)
The checkpoint store still used the File/Cache table, so a missing store read
as NOT_FOUND and a quota failure as retryable. It now uses
mapIndexedDbException, leaving one IndexedDB exception table in the repo.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:36:49 +09:00
DongHyeonkaandClaude Opus 5.5 f2e14af0a8 fix(service-worker): report a drain timeout as CLIENT_DRAIN_TIMEOUT (06-07)
The worker sent ACTIVATE_REJECTED for a client refusal, a drain timeout and a
failed skipWaiting() alike, so the page blamed a dirty tab. Two worker reply
kinds now carry the timeout and the commit failure.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:36:28 +09:00
DongHyeonkaandClaude Opus 5.5 063375ed04 fix(contracts): fail public builds without VITE_BUILD_ID and record the local default (F-6, 13-15)
ENV_REGISTRY called VITE_BUILD_ID required with no default while every reader
fell back to local-build. Staging and production builds now fail without it;
local builds keep the placeholder, and the registry records that default.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:32:54 +09:00
DongHyeonkaandClaude Opus 5.5 03991aaafb fix(realtime): add observe hooks to the reconnect and poll coordinators (04-07)
Design 14.1 connect and bounded_poll events had no place to come from, and
an exhausted budget looked the same as a terminal failure. Both coordinators
now emit a closed observation vocabulary through a best-effort sink.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:32:33 +09:00
DongHyeonkaandClaude Opus 5.5 996a9591c8 fix(web-push): let a new session take over a foreign push fence (06-06)
After an account switch without logout the new session could not name the
stored authority, so enable and reconcile stayed STALE_AUTHORITY. The port
gains revokeForeign: it rotates a fence another fence generation holds and
revokes its association, and leaves the caller's own fence alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:32:19 +09:00
DongHyeonkaandClaude Opus 5.5 b7fc7e53ce fix(presentation): show a support reference on failure screens (08-07)
Route render, unrecovered chunk and query failure screens now show the id
a user quotes to support, and the render diagnostic records the same id as
correlation_id. The route failure page also offers a reload.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:32:12 +09:00
DongHyeonkaandClaude Opus 5.5 9e616d3a06 docs(contracts): mark compatibility aliases and V1 readers deprecated with removal conditions (07-07)
The aliases and V1 config/manifest readers had no @deprecated tag, replacement
or removal condition in code, so they could only become permanent.

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

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:54 +09:00
DongHyeonkaandClaude Opus 5.5 2cbf500fcc perf(cache-storage): one keys() and two body copies per cache lookup (02-07)
A lookup listed the cache names twice and copied the body four times (read
buffer, digest input, stored source, stream). The name list is now shared and
only the read buffer and the per-stream copy remain; WebCrypto copies its
input itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:17 +09:00
DongHyeonkaandClaude Opus 5.5 0bcee348c5 fix(contracts): report malformed validator results as THROWN instead of throwing (07-06)
invokeValidator spread result.issues outside its try and treated any truthy
success as valid, so a hand-written validator could throw past the executor
or pass unchecked data. The result is now read inside the try and checked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:26:10 +09:00
DongHyeonkaandClaude Opus 5.5 2138896472 fix(realtime): feed SSE reader chunks to the parser in maxChunkBytes slices (04-05)
The browser picks the read size, so a chunk over 256KB ended the stream as
EVENT_TOO_LARGE even when every event was normal size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:22:48 +09:00
DongHyeonkaandClaude Opus 5.5 d76653bfcd fix(browser-files): observe dismissals as DISMISSED instead of SUCCEEDED (02-06)
A cancelled save dialog and a browser handoff were both recorded as
DOWNLOAD SUCCEEDED, so the cancel rate hid inside the handoff success rate.
BrowserDataObservation.outcome gains DISMISSED (additive).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:20:17 +09:00