feat: add diagnostics and telemetry runtime

merge: internationalization message platform
feat: add internationalization message platform
2026-07-26 16:42:27 +09:00 · 2026-07-26 16:17:45 +09:00 · 2026-07-26 16:17:39 +09:00 · 2026-07-26 15:49:13 +09:00
90 changed files with 3462 additions and 308 deletions
@@ -82,7 +82,10 @@
        { "script": "check:types:fixture:async-overlay", "expect": "fail" },
        { "script": "check:types:fixture:route-runtime", "expect": "fail" },
        { "script": "check:types:fixture:page-action", "expect": "fail" },
-        { "script": "check:types:fixture:icon-button", "expect": "fail" }
+        { "script": "check:types:fixture:icon-button", "expect": "fail" },
+        { "script": "check:types:fixture:i18n-key", "expect": "fail" },
+        { "script": "check:types:fixture:i18n-params", "expect": "fail" },
+        { "script": "check:types:fixture:diagnostics", "expect": "fail" }
      ],
      "logPath": "artifacts/quality/check-types.txt",
      "evidence": ["artifacts/quality/check-types.txt"],
@@ -154,6 +157,10 @@
        { "script": "check:architecture", "expect": "pass" },
        { "script": "check:design-system", "expect": "pass" },
        { "script": "check:design-system:fixture", "expect": "fail" },
+        { "script": "check:i18n", "expect": "pass" },
+        { "script": "check:i18n:fixture", "expect": "fail" },
+        { "script": "check:diagnostics", "expect": "pass" },
+        { "script": "check:diagnostics:fixture", "expect": "fail" },
        { "script": "check:registries", "expect": "pass" },
        { "script": "check:registries:fixture", "expect": "fail" },
        { "script": "check:routes:fixture", "expect": "fail" }
@@ -163,6 +170,10 @@
        "artifacts/quality/dependency-report.json",
        "artifacts/quality/design-system.json",
        "artifacts/quality/design-system-fixture.json",
+        "artifacts/quality/i18n.json",
+        "artifacts/quality/i18n-fixture.json",
+        "artifacts/quality/diagnostics.json",
+        "artifacts/quality/diagnostics-fixture.json",
        "artifacts/quality/registries.json",
        "artifacts/quality/registry-fixture.json",
        "artifacts/quality/route-registry-fixture.json"
@@ -0,0 +1,96 @@
+# VD-06: Intl과 typed local message catalog
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-i18n-message-formatting-contract`
+- 재검토: 승인 locale·복수형 문법·번역 추출 workflow가 local catalog 범위를 넘을 때
+
+## 배경
+
+공통 셸, route surface, async/form 상태와 디자인 시스템 기본 문구가 JSX와
+JavaScript에 분산돼 있었다. 날짜는 일부 application mapper에서 고정 locale로
+가공되어 presentation이 locale을 바꿀 수 없었고, direction·누락 key·보간 실패
+정책도 없었다. 반면 현재 skeleton에는 번역 관리 서비스, 실제 번역 승인 절차,
+복잡한 ICU 문법이라는 제품 요구가 아직 없다. 이 단계에서 i18n vendor를 기본
+번들에 넣으면 소비 프로젝트가 제거하거나 다시 감싸야 할 의존성만 늘어난다.
+
+## 결정
+
+1. 표준 `Intl.DateTimeFormat`, `NumberFormat`, `RelativeTimeFormat`,
+   `ListFormat`, `PluralRules`와 typed local catalog를 기본 엔진으로 사용한다.
+2. `MessageKey`는 한국어 canonical catalog에서 도출하며 영어와 RTL smoke
+   catalog는 `satisfies Record<MessageKey, string>`으로 compile-time parity를
+   강제한다.
+3. 보간이 필요한 key는 `MessageParameters`에 key별 parameter object를
+   선언한다. 잘못된 key, 누락·초과 parameter는 TypeScript negative fixture가
+   거절한다.
+4. 기본 locale은 `ko-KR`, fallback locale도 `ko-KR`이다. 알려지지 않은 locale은
+   language fallback 후 `ko-KR`로 정규화한다. 알려지지 않은 key와 누락 보간은
+   raw key나 외부 값을 출력하지 않고 안전한 공통 fallback을 반환한다.
+5. `en-XA`는 영어 문구를 확장·accent 처리하는 pseudo locale이고 `ar-EG`는
+   RTL 동작 smoke locale이다. 이 두 locale은 실제 제품 번역 완료를 의미하지
+   않는다.
+6. 날짜 formatter의 기본 timezone은 테스트와 SSR/브라우저 결과가 흔들리지
+   않도록 `UTC`다. 제품 timezone이 필요하면 호출자가 명시한다. invalid
+   date/number/timezone은 `—`를 반환하고 throw하지 않는다.
+7. locale state는 React inbound concern이다. `LocaleProvider`가 copy,
+   formatter와 `<html lang/dir>`을 제공하며 application/domain은 미리 번역된
+   문자열 대신 의미 값과 timestamp를 반환한다.
+8. backend `message`, raw HTML, stack과 내부 key를 catalog 입력으로 신뢰하지
+   않는다. transport/application failure kind를 등록된 사용자 message key로
+   매핑한 뒤 presentation이 해석한다.
+9. key rename은 즉시 제거하지 않고 `MESSAGE_KEY_ALIASES`에 compatibility alias를
+   둔다. alias는 새 호출의 타입에 포함하지 않아 신규 코드는 canonical key만
+   사용한다.
+10. extraction, ICU rich message, 번역 SaaS 또는 framework adapter가 필요해지면
+    `presentation/i18n` public API 뒤에서 교체한다. vendor type은 feature와
+    design-system public prop으로 노출하지 않는다.
+
+## 실행 경계
+
+```text
+route/form/failure 의미 값
+  -> presentation message key
+  -> LocaleProvider
+  -> typed catalog / Intl formatter
+  -> text node와 accessible name
+```
+
+- canonical catalog: `src/presentation/i18n/catalog.ts`
+- feature contribution: `src/features/*/contracts/*-message-catalog.js`를
+  `src/features/installed-feature-messages.js`에서 조립
+- key/보간/fallback/alias: `message-contract.ts`
+- locale-safe value formatting: `formatters.ts`
+- React composition과 document metadata: `locale-provider.tsx`
+- public entry: `src/presentation/i18n/index.ts`
+
+## 검증
+
+- `check:i18n`은 catalog key와 placeholder parity, common UI의 한국어 literal,
+  backend message JSX 렌더링과 raw HTML 사용을 검사한다.
+- `check:i18n:fixture`는 세 금지 사례를 실제로 거절해야 성공으로 인정된다.
+- type negative fixture는 unknown key와 잘못된 parameter shape를 거절한다.
+- unit test는 fallback, alias, pseudo 확장, direction과 timezone/number/relative/
+  list/plural/select의 결정성을 검증한다.
+- component test는 document `lang/dir`, RTL Tabs와 direction-aware pagination,
+  Drawer semantics를 검증한다.
+- Playwright는 320px pseudo reflow와 RTL compact shell/Drawer/focus restore를
+  Chromium, Firefox, WebKit project에서 실행한다.
+
+## 한계와 재검토 조건
+
+현재 catalog는 실제 번역 승인, ICU rich text, locale별 plural 문장 전체 조합,
+메시지 추출/번역 메모리와 서버 locale negotiation을 제공하지 않는다. 다음 중
+하나가 확인되면 별도 ADR로 엔진을 재평가한다.
+
+- 세 개 이상의 실제 승인 locale과 번역 담당 workflow
+- 복수형·성별·select가 한 문장 안에서 중첩되는 제품 copy
+- server/client extraction, namespace lazy-loading 또는 번역 SaaS 연동
+- SSR locale negotiation과 hydration 일치가 필요한 rendering mode
+
+## Rollback
+
+`ko-KR` catalog가 기존 기본 문구를 보존하므로 provider를 고정 locale adapter로
+되돌려도 기본 UX를 유지한다. formatter/vendor 교체 시 public `message`,
+`date`, `number`, `relativeTime`, `list`, `plural`, `select` 계약과 negative
+fixture는 유지한다. alias는 migration window 종료 근거 없이 제거하지 않는다.
@@ -0,0 +1,97 @@
+# VD-07: Diagnostics와 telemetry exporter 경계
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-diagnostics-telemetry-runtime`
+- 재검토: 실제 운영 sink, consent가 필요한 analytics 또는 분산 tracing provider가
+  선정될 때
+
+## 배경
+
+기존 telemetry registry와 best-effort HTTP queue는 있었지만 운영 진단 record와
+semantic event의 책임이 하나의 telemetry port에 섞여 있었다. boot, HTTP,
+cache, storage, route와 release failure의 선언도 실제 production producer와
+완전히 연결되지 않았다. 이 상태에서는 retry attempt마다 같은 사건을 발행하거나
+raw URL, query, request body와 오류 객체가 queue에 들어갈 위험이 있다.
+
+반면 skeleton 단계에는 실제 관측 vendor, endpoint의 운영 보안 정책, analytics
+consent와 보존 기간이 결정되지 않았다. 특정 SDK를 기본 번들에 설치하는 것은
+vendor 결정 전에는 안전한 기본값이 아니다.
+
+## 결정
+
+1. level 기반 운영 진단은 `DiagnosticsPort`, registry 기반 semantic event는
+   `TelemetryPort`로 분리한다. application은 두 port의 concrete adapter나
+   exporter SDK를 알지 못한다.
+2. diagnostics의 level, event ID와 context key는 닫힌 registry/allowlist다.
+   telemetry도 event별 required/optional attribute와 value policy를 적용한다.
+   등록되지 않은 event·context·고카디널리티 값은 전송하지 않는다.
+3. 기본 diagnostics adapter는 bounded in-memory evidence이고 telemetry는
+   설정이 없으면 true no-op이다. endpoint가 있을 때만 bounded oldest-drop
+   queue와 best-effort HTTP sink를 사용한다.
+4. raw path/URL/query/body/response/storage value, credential, cookie, email,
+   stack과 오류 객체 전체는 context에 넣지 않는다. route ID, operation ID,
+   correlation ID, release ID, error kind, status/attempt/duration bucket만
+   허용한다.
+5. HTTP logical execution은 success, retry recovery, terminal failure 또는
+   abort마다 `http.request.completed` diagnostics를 정확히 한 번 남긴다.
+   `api.request.failed` telemetry는 retry가 끝난 terminal non-abort failure에만
+   정확히 한 번 발행한다.
+6. `app.boot.failed`, `ui.render.failed`, `release.mismatch.detected`,
+   `telemetry.delivery.dropped`를 production path에 연결한다. cache와 storage
+   실패는 diagnostics로 기록하되 raw key/value를 기록하지 않는다.
+7. queue full, invalid event/context, serialization과 sink failure는 제한된
+   reason bucket으로 집계한다. drop observer의 failure는 다시 telemetry를
+   발행하지 않는 nonrecursive 경계다.
+8. diagnostics와 telemetry failure는 제품 흐름, HTTP 결과, route transition,
+   storage/cache fallback과 React error surface를 바꾸지 않는다.
+9. mount 전 bootstrap failure는 안전한 build/config/error kind만 별도 evidence로
+   만들며 untrusted error message, stack과 support 입력을 serialize하지 않는다.
+10. 실제 error reporter, RUM, analytics나 tracing SDK는 같은 port 뒤의 외부
+    adapter로만 추가한다. SDK type과 event API를 application/feature/presentation
+    public contract에 노출하지 않는다.
+
+## 실행 경계
+
+```text
+route/application/HTTP/cache/storage/bootstrap
+  -> typed DiagnosticsPort 또는 TelemetryPort
+  -> registry + allowlist + value policy
+  -> bounded memory/no-op 또는 best-effort HTTP adapter
+  -> 프로젝트가 선택한 외부 sink
+```
+
+- diagnostics contract: `src/contracts/diagnostics.ts`
+- telemetry contract: `src/contracts/telemetry.js`
+- application ports: `src/application/ports/diagnostics-port.ts`,
+  `telemetry-port.ts`
+- bounded diagnostics: `src/adapters/diagnostics/bounded-diagnostics.ts`
+- best-effort telemetry: `src/adapters/telemetry/best-effort-telemetry.js`
+- composition: `src/bootstrap/runtime-adapters.js`
+
+## 검증
+
+- `check:diagnostics`는 모든 registry event에 production producer가 있는지와
+  source의 direct console/sensitive context 우회를 검사한다.
+- negative source fixture는 direct console, unknown event와 raw context를 실제로
+  거절하며 TypeScript fixture는 잘못된 level/event ID를 거절한다.
+- unit test는 allowlist, hostile/circular error, bounded diagnostics, no-op,
+  queue full, sink/observer failure와 pre-mount boot evidence를 검증한다.
+- HTTP integration은 success, retry recovery, terminal failure와 abort의 producer
+  횟수, route/operation/correlation context와 요청 값 비노출을 검증한다.
+- cache/storage/release/application/runtime test는 각 production wiring과
+  diagnostics failure isolation을 검증한다.
+
+## 한계와 재검토 조건
+
+기본 adapter는 운영 log 검색, source map 연계, session replay, distributed span,
+analytics consent, sampling budget과 장기 보존을 제공하지 않는다. 실제 sink를
+선정할 때 데이터 처리 지역, 보존 기간, consent, CSP, source map 접근 제어,
+sampling과 비용 상한을 별도 결정해야 한다.
+
+## Rollback
+
+telemetry exporter는 runtime 설정을 끄거나 adapter wiring을 `noOpTelemetry`로
+바꾸어 독립적으로 제거할 수 있다. 이때도 `DiagnosticsPort`, registry,
+redaction/value policy, producer-count와 negative fixture는 유지한다. 외부 SDK
+문제로 application producer와 안전 계약을 함께 되돌리지 않는다.
@@ -12,7 +12,7 @@
 - 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
 - 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.

-최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-04 구현 결과를 이 문서에
+최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-08 구현 결과를 이 문서에
 누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은
 문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다.

@@ -33,13 +33,14 @@

 특히 다음은 선행 해결이 필요하다.

-RP-01~RP-05에서 TypeScript 도구 안전망, application runtime 주입,
+RP-01~RP-09에서 TypeScript 도구 안전망, application runtime 주입,
 query/mutation inbound adapter, HTTP 실행 계약과 executable route/release
-recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다. 현재 선행 해결
+recovery 계약, 제거 가능한 reference 수직 슬라이스, form/page, design system과
+i18n 실행 경계와 diagnostics/telemetry production wiring은 구현됐다. 현재 선행 해결
 대상은 다음과 같다.

-1. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치
-2. 국제화, diagnostics, optional adapter recipe와 심화 품질 게이트
+1. registry evidence와 실제 compatibility diff
+2. 공급망과 optional adapter recipe 심화 게이트

 따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
 더 정확한 표현은 다음과 같다.
@@ -65,7 +66,7 @@ recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다.
 | 계층 의존 방향 | 부분 준비 | `.dependency-cruiser.cjs`, `src/application/ports` | inbound/outbound 명명과 `contracts` 소유권까지 집행 |
 | application facade | 준비됨 | typed input/output catalog, provider, production composition test | feature input use case를 contribution으로 확장 |
 | HTTP client | 준비됨 | path/search/body projection, runtime timeout/retry, abort/cleanup test | feature gateway 뒤에서 사용 |
-| retry | 준비됨 | HTTP 단일 소유, runtime max attempts, Query retry off | RP-09에서 telemetry 연결 |
+| retry | 준비됨 | HTTP 단일 소유, runtime max attempts, Query retry off, logical execution당 bounded diagnostics | terminal event 중복 방지 계약 유지 |
 | 오류 모델 | 부분 준비 | error registry와 normalization 존재 | typed discriminated union과 계층별 mapper |
 | 검증 | 준비됨 | runtime/API/route/form Zod parse 결과를 실행 경계에서 사용하고 domain invariant와 분리 | feature별 schema 소유권 유지 |
 | 인증 연동 | 준비됨/프로젝트 선택 | opaque auth owner와 demo seam 존재 | 인증 방식별 recipe; 기본 token 저장소는 추가하지 않음 |
@@ -73,15 +74,15 @@ recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다.
 | 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 |
 | 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 |
 | 라우팅 | 준비됨 | Data Router, typed runtime map, codec, metadata consumer, bounded chunk recovery | reference feature route와 release E2E로 사용 범위 확장 |
-| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss와 focus restore | RP-08에서 RTL/direction 검증 |
+| 앱 셸·반응형 | 준비됨 | native modal Drawer, compact/desktop layout, Escape/link dismiss/focus restore, pseudo reflow와 RTL direction | compact browser matrix 유지 |
 | 페이지 템플릿 | 준비됨 | Standard/Collection/Detail/Form/Status와 public design-system entry | feature별 slot 조합 유지 |
 | 디자인 토큰 | 준비됨 | primitive/semantic/component CSS, 48-token 자동 계약, dark/forced-colors/reduced-motion | 제품 brand token은 외부 프로젝트에서 확장 |
 | 공통 UI | 준비됨 | action/form/feedback/overlay/navigation primitive와 pattern, compatibility export | Storybook/visual은 RP-10 |
 | 아이콘 | 준비됨 | Lucide static vendor facade와 semantic icon/IconButton 접근성 계약 | 의미 icon 추가 시 bundle/접근성 기준 적용 |
 | 폼 | 준비됨 | Zod 기반 local facade, error summary/focus, 422 allowlist, dirty/pending/conflict 정책 | 복합 form 요구가 생기면 VD-04 조건으로 vendor adapter 평가 |
-| 국제화 | 미제공 | 한국어 문자열·locale이 하드코딩 | typed message/formatter/locale/RTL 경계 |
-| logging/diagnostics | 미제공 | telemetry port는 있으나 logger 없음 | redaction이 적용된 diagnostics/logging 경계 |
-| telemetry | 부분 준비 | registry, queue, redaction 존재 | HTTP·boot·cache·storage·route 사건에 실제 연결 |
+| 국제화 | 준비됨 | 137-key typed catalog, locale provider, Intl formatter, safe fallback/alias, pseudo·RTL gate | 실제 locale·번역 승인은 프로젝트에서 연결 |
+| logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 |
+| telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 |
 | 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
 | 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 |
 | UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 |
@@ -216,11 +217,14 @@ guard → browser navigation adapter의 1회 reload로 연결됐다. 일반 rend
 failure는 이 경로에서 제외되고, 반복 실패·offline·malformed manifest·storage
 실패는 지원 표면으로 fail-closed된다.

-#### telemetry, registry, 공급망 gate의 실행 깊이가 부족하다
+#### RP-09에서 diagnostics/telemetry 실행 깊이 보강

-telemetry registry에는 여러 사건이 있지만 실제 production producer는 제한적이다.
-boot, API attempt/final failure, auth recovery, storage/cache degradation, release/chunk
-recovery를 registry 사건에 연결해야 한다.
+`DiagnosticsPort`와 `TelemetryPort`를 분리하고 boot, HTTP logical outcome,
+render, cache, storage, route, release mismatch와 delivery drop을 production
+producer에 연결했다. HTTP retry는 attempt별 terminal event를 발행하지 않고
+logical execution 종료 시 한 번만 bounded outcome을 남긴다. allowlist와
+value policy가 raw URL/query/body/storage value/error object를 거절하고 queue와
+sink failure는 nonrecursive drop evidence로 제한된다.

 registry/compatibility 검사는 다음까지 확장한다.

@@ -242,7 +246,7 @@ known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해
 - token → primitive → pattern → template로 이어지는 디자인 시스템
 - Lucide를 감싼 local icon registry와 `IconButton`
 - typed message key, locale provider, formatter, pseudo-locale/RTL smoke
- redacted structured diagnostics/logger와 telemetry wiring
+- RP-09에서 완료한 redacted structured diagnostics와 telemetry wiring 유지
 - Storybook 또는 동급 isolated UI workshop
 - Playwright visual baseline, shared MSW scenarios, built-dist E2E
 - React Hooks, JSX accessibility, TanStack Query 관련 lint
@@ -250,6 +254,24 @@ known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해
 - registry/compatibility의 실제 diff와 orphan reference 검사
 - transitive vulnerability, license, SBOM/provenance 공급망 gate

+#### RP-08에서 국제화 실행 경계 구현
+
+`src/presentation/i18n`은 shell, route, async/form error, page template와
+design-system 기본 copy의 canonical 경계다. `MessageKey`와 key별
+`MessageParameters`가 잘못된 key/보간을 compile time에 막고, runtime
+`resolveMessage`는 unknown locale/key와 누락 보간에서 raw 값 대신 안전한
+fallback을 반환한다. application mapper는 locale-formatted date를 반환하지
+않고 timestamp를 유지하며 presentation formatter가 `UTC` 또는 명시 timezone을
+적용한다.
+
+`LocaleProvider`는 `ko-KR`, `en-US`, `en-XA`, `ar-EG` smoke set과 document
+`lang/dir`을 동기화한다. `en-XA`는 긴 문구 reflow, `ar-EG`는 logical CSS,
+Drawer, Tabs arrow와 pagination 방향 icon을 검증하기 위한 개발 locale이다.
+실제 아랍어 번역 완료를 뜻하지 않는다. `check:i18n`과 negative fixture는 common
+UI literal, backend raw message render와 raw HTML interpolation을 거절한다.
+새 key rename은 canonical type에는 넣지 않고 runtime alias/migration window로
+호환한다.
+
 ### 5.3 P2: 경계와 recipe를 제공할 선택 항목

 다음 기능을 모든 앱의 초기 번들에 설치할 필요는 없다. 대신 port 또는 local
@@ -361,7 +383,8 @@ bootstrap → React TSX → tests 순서로 이동한다.

 - retry: `src/adapters/http/retry-policy.js`, 부분 준비
 - API client: `src/adapters/http/client.js`, 부분 준비
- logger: 없음. telemetry와 분리하거나 diagnostics port로 합치는 결정 필요
+- logger: `DiagnosticsPort`로 telemetry와 분리해 구현. closed event/level,
+  allowlist와 bounded/no-op adapter 제공
 - token manager: 의도적으로 없음. opaque external auth owner가 credential을 소유
 - error: `src/contracts/errors.js`와 HTTP normalization, 부분 준비
 - validation: runtime/API Zod는 존재, route/form/domain 분리는 미완성
@@ -651,6 +651,26 @@ token rename은 alias/migration 기간을 두고, vendor adapter와 local API co
 RP-08은 기존 기본 언어 catalog를 fallback으로 유지한다. 번역 catalog를
 파괴적으로 덮어쓰지 않는다.

+**구현 증거 (2026-07-26)**
+
+- VD-06에서 dependency를 추가하지 않는 browser `Intl` + typed local catalog를
+  채택하고 vendor 재평가 조건, fallback과 key migration 정책을 문서화했다.
+- `src/presentation/i18n`이 137개 common key, key별 interpolation,
+  `ko-KR` fallback, compatibility alias, date/number/relative/list/plural/select
+  formatter와 `LocaleProvider`를 제공한다.
+- shell, route lifecycle/access/recovery, async/form error, page template와
+  design-system default copy가 catalog consumer로 연결됐다.
+- feature route copy는 feature-owned catalog contribution으로 분리되어 reference
+  feature 제거 시 source와 built artifact에 전용 message key가 남지 않는다.
+- reference application mapper는 locale-formatted date 대신 timestamp를
+  반환하고 presentation formatter가 UTC 또는 명시 timezone을 적용한다.
+- `check:i18n`과 type negative fixture가 catalog/placeholder 불일치,
+  hardcoded common literal, backend raw message render, unsafe HTML,
+  unknown key와 interpolation mismatch를 거절한다.
+- unit/component/browser test가 safe fallback, pseudo 320px reflow,
+  document `lang/dir`, RTL Drawer/Tabs/directional icon과 deterministic formatter를
+  검증한다.
+
 ### 09. `feature-frontend-diagnostics-telemetry-runtime`

 **목표**
@@ -703,6 +723,28 @@ render와 release 사건을 실제 producer에 연결한다.
 RP-09는 exporter를 제거하고 즉시 no-op adapter로 전환할 수 있어야 한다.
 diagnostics port와 redaction test는 유지한다.

+**구현 증거 (2026-07-26)**
+
+- VD-07에서 level/event 기반 `DiagnosticsPort`와 semantic `TelemetryPort`를
+  분리하고 bounded memory/no-op 또는 설정 기반 best-effort HTTP exporter를
+  채택했다.
+- diagnostics 8종과 telemetry 5종의 registry, context/attribute allowlist,
+  고카디널리티 value policy, timestamp와 status/attempt/duration/queue bucket을
+  구현했다.
+- boot, route, render, HTTP logical outcome, cache, storage, release mismatch와
+  telemetry drop을 production composition에 연결했다. HTTP는 success/recovery/
+  terminal/abort 각각 logical execution당 diagnostics 한 번, terminal
+  non-abort failure telemetry 한 번만 발행한다.
+- bounded oldest-drop queue, drop reason 집계, sink/observer failure 격리와
+  nonrecursive delivery evidence를 구현했다. exporter가 없으면 network와 queue
+  side effect가 없는 true no-op이다.
+- `check:diagnostics`, source negative fixture와 TypeScript negative fixture가
+  producer 누락, direct console, unknown event/context, raw URL/query/body/
+  credential 경계를 거절한다.
+- unit/integration test가 circular/hostile error, pre-mount boot, queue/sink
+  failure, no-op, cache/storage/release producer, success/retry recovery/terminal/
+  abort 횟수와 reference route/operation/correlation context를 검증한다.
+
 ### 10. `feature-frontend-test-registry-evidence-hardening`

 **목표**
@@ -178,6 +178,15 @@ template public API이며 feature와 shell은 이 entry만 소비한다. Lucide
 port가 아니다. native Dialog/Drawer/Menu/Tabs의 focus·keyboard 상태도
 presentation이 소유하고 use case나 outbound adapter로 올리지 않는다.

+RP-08에서 i18n은 application output port가 아니라 React inbound adapter의
+local facade로 확정됐다. domain/application은 locale이나 번역 문장을 알지 않고
+timestamp, number, failure kind 같은 의미 값만 반환한다.
+`src/presentation/i18n`이 typed message catalog, formatter, fallback,
+`<html lang/dir>`과 pseudo/RTL smoke를 소유한다. backend raw `message`는
+application failure registry를 우회해 렌더링할 수 없으며 `check:i18n` negative
+fixture가 이 경계를 집행한다. 번역 vendor를 나중에 선택해도 이 facade 뒤의
+adapter만 교체한다.
+
 이 문서의 목표 구조는 기존 기반을 폐기하는 것이 아니라 이러한
 불일치를 제거하는 것이다.

@@ -770,22 +779,31 @@ Logger와 telemetry는 같은 것이 아니다.
 - Telemetry: registry에 정의된 semantic event와 metric
 - Error reporter: 예외 집계와 release correlation

-기본 `Logger` output port는 safe context만 받는다.
+VD-07에 따라 기본 구현은 임의 message 문자열을 받는 `Logger`가 아니라 닫힌
+event ID와 safe context만 받는 `DiagnosticsPort`다.

 ```ts
-export interface Logger {
-  debug(message: string, context?: SafeLogContext): void;
-  info(message: string, context?: SafeLogContext): void;
-  warn(message: string, context?: SafeLogContext): void;
-  error(message: string, context?: SafeLogContext): void;
+export interface DiagnosticsPort {
+  record(input: {
+    level: DiagnosticLevel;
+    eventId: DiagnosticEventId;
+    context?: DiagnosticContext;
+  }): void;
 }
 ```

-개발 환경에는 redacted console adapter, production에는 allowlist 기반
-remote adapter, 테스트에는 recording 또는 no-op adapter를 연결한다.
+기본 runtime에는 bounded in-memory diagnostics와 설정 기반 best-effort
+telemetry adapter, 테스트에는 recording 또는 no-op adapter를 연결한다.
+direct `console`은 redaction 경계를 우회하므로 source gate가 거절한다.
 민감정보 redaction은 각 호출자의 선의가 아니라 adapter와 contract에서
 강제한다.

+현재 production producer는 boot, logical HTTP outcome, cache, storage, route,
+render, release mismatch와 telemetry delivery drop을 포함한다. HTTP terminal
+telemetry는 모든 retry가 끝난 뒤 한 번만 발행하며 abort에는 발행하지 않는다.
+raw path/query/body/error 대신 route/operation/correlation ID와
+status/attempt/duration bucket만 전달한다.
+
 ## 16. Feature 경계와 removable reference feature

 Reference feature는 단순 UI fixture가 아니라 다음 경로를 모두 실행해야
@@ -1214,9 +1232,10 @@ contract와 실패 분기를 우선한다.
 - [ ] runtime timeout/retry 설정이 실제 HTTP transport에 반영된다.
 - [ ] QueryClient와 feature query bridge가 실제 route에서 동작한다.
 - [ ] session UI API와 credential attachment가 분리되어 있다.
- [ ] logger와 telemetry가 HTTP/render/storage/cache failure 경로에
+- [x] diagnostics와 telemetry가 HTTP/render/storage/cache failure 경로에
      연결된다.
- [ ] page lifecycle에서 필요한 telemetry flush/cleanup이 수행된다.
+- [x] `pagehide`에서 bounded telemetry queue를 flush하고 adapter `dispose`가
+      lifecycle listener를 정리한다.

 ### 26.3 HTTP와 validation

@@ -447,6 +447,13 @@ controller가 소유하지 않는 것:
 | Page Template | 반복 layout/state | 접근성과 반응형 구조 재사용 | data fetching을 template에 포함 |
 | Registry + Runtime Map | route/operation/event | 선언과 실행 완전성 | 모든 설정을 하나의 거대 전역 파일에 집중 |

+RP-08 이후 route contract의 `title`/`navigation` 필드는 fallback metadata이며
+실제 document title, navigation, loading/error/access surface는
+`route.<ROUTE_ID>.title|navigation` typed catalog key를 해석한다. route params,
+search, backend message를 translation key로 조립하지 않는다. locale 변경은
+현재 route를 재요청하거나 query key를 바꾸지 않고 document title과 화면 copy만
+다시 렌더링한다.
+
 패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative
 architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다.

@@ -468,23 +468,57 @@ raw response body, stack, token, URL query, PII를 사용자 copy나 일반 log

 ### 7.3 diagnostics와 telemetry

-현재 telemetry event contract와 별도로 개발·진단용 structured logger가 필요하다.
-다음 두 설계 중 하나를 ADR로 결정한다.
-
-1. `DiagnosticsPort`가 log/event/span을 내부 method로 구분
-2. `LoggerPort`와 `TelemetryPort`를 분리
+VD-07에서 level/event 기반 `DiagnosticsPort`와 semantic
+`TelemetryPort`를 분리했다. diagnostics는 8개 event ID와 safe context
+allowlist를, telemetry는 event별 required/optional attribute와 value policy를
+사용한다.

 공통 요구:

 - log level과 event key는 닫힌 union
 - attribute allowlist와 중앙 redaction
- dev adapter는 console을 사용하되 동일 redaction 적용
- production adapter는 provider SDK를 감싸며 앱 코드는 SDK를 import하지 않음
+- 기본 adapter는 bounded memory/no-op이고 endpoint가 있을 때만 best-effort
+  HTTP queue를 사용
+- production provider SDK를 추가할 때도 port 뒤에서 감싸며 앱 코드는 SDK를
+  import하지 않음
 - 오류 객체 전체를 그대로 serialize하지 않음
 - trace ID/build ID/route ID/operation ID를 허용된 범위에서 연결
 - logging failure가 제품 flow를 실패시키지 않음
 - consent가 필요한 analytics와 essential diagnostics를 분리

+HTTP는 route/operation/correlation ID를 logical execution context로 생성하고
+success/recovered/failed/aborted 종료 시 diagnostics를 한 번만 기록한다.
+terminal non-abort failure만 telemetry를 한 번 발행한다. cache/storage와 boot
+producer는 raw key, value, message, stack을 버리고 error kind와 bounded
+operation만 남긴다. queue full과 sink failure는 제한된 reason bucket이며 drop
+observer가 실패해도 재귀 발행하지 않는다.
+
+### 7.4 locale, message와 표시 값
+
+RP-08부터 locale은 presentation-owned React context다. server/application
+state에 번역된 문자열을 저장하거나 query key에 locale을 넣는 것은 응답 자체가
+locale별 데이터인 경우에만 허용한다. 공통 UI copy 변경 때문에 query cache를
+복제하지 않는다.
+
+```text
+API timestamp/number/failure kind
+  -> schema + mapper (의미 값 유지)
+  -> application result
+  -> presentation controller
+  -> useLocale().date/number/message
+```
+
+- message key는 `MessageKey` union이며 interpolation은 key별 tuple type이다.
+- unknown external key는 `resolveMessage`에 전달해도 raw key가 표시되지 않는다.
+- backend `message`는 diagnostic input일 수 있지만 사용자 copy가 아니다.
+- form validation code는 `ParameterlessMessageKey` allowlist로 mapping한다.
+- date의 기본 timezone은 UTC이고 제품 timezone은 presentation 호출자가
+  명시한다.
+- pseudo/RTL locale state는 local interaction state이며 persistence와 server
+  synchronization을 기본 제공하지 않는다.
+- key rename은 typed canonical key를 먼저 이동하고 runtime alias에 migration
+  기간을 둔다.
+
 ## 8. 폼 표준

 VD-04에 따라 현재 기본 엔진은 React native form event와 controlled value이며
@@ -584,4 +618,5 @@ backend message와 알 수 없는 path는 field copy로 사용하지 않는다.
 - 상태 종류별 소유권이 테스트와 문서에서 확인된다.
 - token은 UI와 일반 storage/store에 노출되지 않는다.
 - failure와 validation의 각 계층이 typed mapper로 분리된다.
+- common UI copy, locale formatter와 direction이 typed i18n facade를 통과한다.
 - query/mutation/form recipe만으로 새 기능을 만들 수 있다.
@@ -534,8 +534,9 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.

 ## 9. 국제화 계약

-디자인 시스템 primitive는 한국어 문구를 내부 기본값으로 숨기지 않는다.
-접근성 label이나 오류 문구가 필요하면 명시적인 prop 또는 message key를 받는다.
+RP-08에서 디자인 시스템 primitive의 닫기, alert, toast, 글자 수 같은 기본
+문구는 `useLocale()` typed catalog로 이동했다. 제품 의미를 가진 label은 여전히
+명시적인 prop으로 받으며 primitive가 feature message key를 소유하지 않는다.

 필수 국제화 기반:

@@ -551,6 +552,17 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
 - pseudo-locale
 - RTL story와 E2E smoke

+현재 구현 위치와 실패 정책:
+
+- `presentation/i18n/catalog.ts`: 137개 canonical common key와 locale parity
+- `message-contract.ts`: key별 interpolation, fallback과 compatibility alias
+- `formatters.ts`: UTC-default date, number, relative time, list, plural/select
+- `locale-provider.tsx`: document `lang/dir`과 React consumer API
+- missing key/parameter와 formatter 예외: 빈 문자열이나 raw key 대신 안전한
+  fallback
+- `en-XA`: 긴 문자열/320px reflow, `ar-EG`: logical layout/RTL keyboard smoke
+- backend raw message와 translated HTML: 정적 negative gate에서 거절
+
 금지 패턴:

 - 번역 문장 중간에 JSX 문자열을 연결한다.
@@ -559,7 +571,7 @@ Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다.
 - route title, navigation label, toast message를 JSX literal로 분산한다.
 - 번역 누락 시 빈 문자열을 렌더링한다.

-Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.
+RP-10의 Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.

 - `ko-KR`, light
 - `en-US`, light
@@ -410,6 +410,8 @@ Page / AsyncSurface / Form pattern
 - filter 순서가 달라도 canonical key가 같다.
 - route unmount 또는 superseded input에서 request를 abort한다.
 - aborted request는 terminal error나 telemetry failure로 오분류되지 않는다.
+- success와 retry recovery는 terminal failure telemetry를 만들지 않고,
+  exhausted retry는 logical execution당 한 번만 발행한다.
 - offline/paused와 loading을 구분한다.
 - 401 복구는 한 번만 수행한다.
 - 재로그인 후 허용된 operation만 다시 실행한다.
@@ -569,6 +571,23 @@ RP-07의 실행 경로는 `check:design-system`,
 baseline은 VD-08/RP-10에서 추가하며 현재 runtime gallery를 isolated workshop
 완료 증거로 사용하지 않는다.

+RP-08의 국제화 실행 경로는 `check:i18n`, `check:i18n:fixture`,
+`check:types:fixture:i18n-key`, `check:types:fixture:i18n-params`,
+`tests/unit/i18n-contract.test.ts`, `tests/component/locale-platform.test.tsx`와
+`tests/e2e/i18n.spec.js`다.
+
+- unit: locale catalog/placeholder parity, safe fallback/alias, pseudo expansion,
+  direction과 UTC date/number/relative/list/plural/select
+- component: document `lang/dir`, RTL tab arrow semantics, direction-aware
+  pagination과 modal Drawer
+- E2E: 320px pseudo reflow와 compact RTL shell/Drawer/focus restore
+- negative: common UI locale literal, backend message JSX render, raw translated
+  HTML, unknown key와 잘못된 interpolation parameter
+
+`ar-EG` catalog가 영어 smoke copy를 재사용하는 것은 RTL behavior 검증용이며
+번역 품질 PASS가 아니다. 실제 locale catalog에는 언어 담당 승인 evidence가
+추가되어야 한다.
+
 ### 10.1 Component behavior

 - native role/name/value
@@ -1266,7 +1285,8 @@ CI registry에 추가한다.
 - [ ] high-risk module branch 목표를 충족한다.
 - [ ] 신규 코드의 미검증 branch에 승인 없는 예외가 없다.
 - [ ] bundle/performance budget을 통과한다.
- [ ] telemetry/error output에 민감 정보가 없다.
+- [x] diagnostics/telemetry output의 allowlist, value policy와 negative fixture가
+      raw URL/query/body/storage value/error object를 거절한다.
 - [ ] 관련 gate와 evidence registry가 갱신되었다.

 ## 19. 금지 패턴
@@ -76,6 +76,8 @@ export default [
      "artifacts/**",
      "tests/fixtures/typecheck/**",
      "tests/fixtures/architecture/forbidden/**",
+      "tests/fixtures/diagnostics/forbidden/**",
+      "tests/fixtures/i18n/forbidden/**",
      "tests/fixtures/security/forbidden/**",
    ],
  },
@@ -115,6 +117,25 @@ export default [
      "no-unused-vars": "off",
    },
  },
+  {
+    files: ["**/*.d.ts"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            ["@babel/plugin-syntax-typescript", { dts: true }],
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
  {
    files: ["**/*.tsx"],
    languageOptions: {
@@ -17,6 +17,10 @@
    "check:architecture": "node scripts/check-architecture.mjs",
    "check:design-system": "node scripts/check-design-system.mjs",
    "check:design-system:fixture": "node scripts/check-design-system.mjs --fixture",
+    "check:i18n": "node scripts/check-i18n.mjs",
+    "check:i18n:fixture": "node scripts/check-i18n.mjs --fixture",
+    "check:diagnostics": "node scripts/check-diagnostics.mjs",
+    "check:diagnostics:fixture": "node scripts/check-diagnostics.mjs --fixture",
    "check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test",
    "check:types:app": "tsc --project tsconfig.app.json",
    "check:types:node": "tsc --project tsconfig.node.json",
@@ -30,6 +34,9 @@
    "check:types:fixture:route-runtime": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-route-runtime.ts",
    "check:types:fixture:page-action": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-page-action.tsx",
    "check:types:fixture:icon-button": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler --jsx react-jsx tests/fixtures/typecheck/invalid-icon-button.tsx",
+    "check:types:fixture:i18n-key": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-key.ts",
+    "check:types:fixture:i18n-params": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-message-params.ts",
+    "check:types:fixture:diagnostics": "tsc --ignoreConfig --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-diagnostics-port.ts",
    "test:runtime-schema": "vitest run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
    "test:unit": "vitest run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
    "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
@@ -0,0 +1,120 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
+import { DIAGNOSTIC_EVENT_REGISTRY } from "../src/contracts/diagnostics.ts";
+import { TELEMETRY_REGISTRY } from "../src/contracts/telemetry.js";
+
+const fixtureMode = process.argv.includes("--fixture");
+const failures = [];
+const extensions = /\.(?:js|jsx|mjs|ts|tsx|mts)$/;
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function filesBelow(directory) {
+  const result = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...(await filesBelow(target)));
+    else if (extensions.test(entry.name)) result.push(target);
+  }
+  return result;
+}
+
+const telemetryProducerFiles =
+  /** @type {Readonly<Record<string, string>>} */ ({
+  "app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
+  "api.request.failed": "src/adapters/http/client.js",
+  "ui.render.failed": "src/application/create-application.ts",
+  "release.mismatch.detected": "src/application/create-application.ts",
+  "telemetry.delivery.dropped":
+    "src/adapters/telemetry/best-effort-telemetry.js",
+  });
+const diagnosticProducerFiles =
+  /** @type {Readonly<Record<string, string>>} */ ({
+  "app.boot.failed": "src/adapters/diagnostics/bounded-diagnostics.ts",
+  "http.request.completed": "src/adapters/http/client.js",
+  "cache.operation.failed":
+    "src/adapters/query-cache/tanstack-query-cache.js",
+  "storage.operation.failed":
+    "src/adapters/storage/browser-storage-adapter.js",
+  "route.changed": "src/application/create-application.ts",
+  "ui.render.failed": "src/application/create-application.ts",
+  "release.mismatch.detected": "src/application/create-application.ts",
+  "telemetry.delivery.dropped": "src/bootstrap/runtime-adapters.js",
+  });
+
+if (!fixtureMode) {
+  for (const eventName of Object.keys(TELEMETRY_REGISTRY)) {
+    const producer = telemetryProducerFiles[eventName];
+    if (!producer) {
+      failures.push(`telemetry event has no declared producer: ${eventName}`);
+      continue;
+    }
+    const source = await readFile(producer, "utf8");
+    if (!source.includes(`"${eventName}"`)) {
+      failures.push(`telemetry producer is not executable: ${eventName}`);
+    }
+  }
+  for (const eventId of Object.keys(DIAGNOSTIC_EVENT_REGISTRY)) {
+    const producer = diagnosticProducerFiles[eventId];
+    if (!producer) {
+      failures.push(`diagnostic event has no declared producer: ${eventId}`);
+      continue;
+    }
+    const source = await readFile(producer, "utf8");
+    if (!source.includes(`"${eventId}"`)) {
+      failures.push(`diagnostic producer is not executable: ${eventId}`);
+    }
+  }
+}
+
+const sources = fixtureMode
+  ? await filesBelow("tests/fixtures/diagnostics/forbidden")
+  : await filesBelow("src");
+const sensitiveContext =
+  /\b(?:authorization|cookie|access_token|refresh_token|request_body|response_body|raw_url|query_string|email|user_name)\b/i;
+for (const file of sources) {
+  const source = await readFile(file, "utf8");
+  if (file.includes("contracts/telemetry.js")) continue;
+  if (source.includes("console.")) {
+    failures.push(`direct console diagnostics bypass in ${file}`);
+  }
+  const calls = source.match(
+    /(?:\.record\(\{|\.emit\()[\s\S]{0,700}?(?:\}\)|\}\);)/g,
+  ) ?? [];
+  if (calls.some((call) => sensitiveContext.test(call))) {
+    failures.push(`sensitive diagnostic or telemetry context in ${file}`);
+  }
+  if (
+    file.includes("tests/fixtures/diagnostics/forbidden") &&
+    source.includes("UNKNOWN_DIAGNOSTIC_EVENT")
+  ) {
+    failures.push(`unknown diagnostic event in ${file}`);
+  }
+}
+
+const report = {
+  schemaVersion: 1,
+  mode: fixtureMode ? "negative-fixture" : "source",
+  telemetryEventCount: Object.keys(TELEMETRY_REGISTRY).length,
+  diagnosticEventCount: Object.keys(DIAGNOSTIC_EVENT_REGISTRY).length,
+  checkedFiles: sources.length,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  fixtureMode
+    ? "artifacts/quality/diagnostics-fixture.json"
+    : "artifacts/quality/diagnostics.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+if (failures.length > 0) {
+  process.stderr.write(
+    `Diagnostics contract failed:\n${failures.join("\n")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write(
+  `Diagnostics contract: ${report.diagnosticEventCount} diagnostics and ${report.telemetryEventCount} telemetry producers PASS\n`,
+);
@@ -0,0 +1,108 @@
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// @ts-expect-error Node 24 executes erasable TypeScript for this build-time gate.
+import { EN_MESSAGES, KO_MESSAGES, MESSAGE_CATALOGS } from "../src/presentation/i18n/catalog.ts";
+
+const fixtureMode = process.argv.includes("--fixture");
+const failures = [];
+const sourceExtensions = /\.(?:js|jsx|mjs|ts|tsx|mts)$/;
+const koreanLiteral = /[가-힣]/;
+const rawFailureRender =
+  /(?<!\$)\{\s*(?:failure|error|response|backend)(?:\?\.|\.)[\w?.]*message\s*\}/;
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function listSourceFiles(directory) {
+  const result = [];
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const target = path.join(directory, entry.name);
+    if (entry.isDirectory()) result.push(...(await listSourceFiles(target)));
+    else if (sourceExtensions.test(entry.name)) result.push(target);
+  }
+  return result;
+}
+
+/** @param {string} template */
+function placeholders(template) {
+  return [...template.matchAll(/\{([a-zA-Z][a-zA-Z0-9]*)\}/g)]
+    .map((match) => match[1])
+    .sort();
+}
+
+if (!fixtureMode) {
+  const canonicalKeys = Object.keys(KO_MESSAGES).sort();
+  for (const [locale, catalog] of Object.entries(MESSAGE_CATALOGS)) {
+    const readableCatalog =
+      /** @type {Readonly<Record<string, string>>} */ (catalog);
+    const canonicalCatalog =
+      /** @type {Readonly<Record<string, string>>} */ (KO_MESSAGES);
+    const keys = Object.keys(catalog).sort();
+    if (JSON.stringify(keys) !== JSON.stringify(canonicalKeys)) {
+      failures.push(`${locale} catalog keys do not match ko-KR`);
+    }
+    for (const key of canonicalKeys) {
+      if (
+        JSON.stringify(placeholders(readableCatalog[key] ?? "")) !==
+        JSON.stringify(placeholders(canonicalCatalog[key] ?? ""))
+      ) {
+        failures.push(`${locale}:${key} interpolation parameters do not match`);
+      }
+    }
+  }
+  if (Object.keys(EN_MESSAGES).length !== canonicalKeys.length) {
+    failures.push("en-US catalog key count does not match ko-KR");
+  }
+}
+
+const commonDirectories = [
+  "src/presentation/boundaries",
+  "src/presentation/components",
+  "src/presentation/design-system",
+  "src/presentation/forms",
+  "src/presentation/layouts",
+  "src/presentation/routes",
+  "src/presentation/templates",
+];
+const sources = fixtureMode
+  ? await listSourceFiles("tests/fixtures/i18n/forbidden")
+  : (
+      await Promise.all(commonDirectories.map((directory) => listSourceFiles(directory)))
+    ).flat();
+
+for (const file of sources) {
+  const source = await readFile(file, "utf8");
+  if (koreanLiteral.test(source)) {
+    failures.push(`hardcoded common user-facing locale literal in ${file}`);
+  }
+  if (rawFailureRender.test(source)) {
+    failures.push(`raw backend/error message rendered in ${file}`);
+  }
+  if (source.includes("dangerouslySetInnerHTML")) {
+    failures.push(`untrusted HTML interpolation boundary in ${file}`);
+  }
+}
+
+const report = {
+  schemaVersion: 1,
+  mode: fixtureMode ? "negative-fixture" : "source",
+  localeCount: Object.keys(MESSAGE_CATALOGS).length + 1,
+  messageKeyCount: Object.keys(KO_MESSAGES).length,
+  checkedFiles: sources.length,
+  failures,
+  passed: failures.length === 0,
+};
+await mkdir("artifacts/quality", { recursive: true });
+await writeFile(
+  fixtureMode
+    ? "artifacts/quality/i18n-fixture.json"
+    : "artifacts/quality/i18n.json",
+  `${JSON.stringify(report, null, 2)}\n`,
+);
+
+if (failures.length > 0) {
+  process.stderr.write(`I18n contract failed:\n${failures.join("\n")}\n`);
+  process.exit(1);
+}
+process.stdout.write(
+  `I18n contract: ${report.messageKeyCount} keys across ${report.localeCount} locales PASS\n`,
+);
@@ -89,6 +89,12 @@ export function createInstalledFeatureInputs(_context: FeatureContext) {
 }
 `;

+const emptyMessages = `export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
+  "ko-KR": Object.freeze({}),
+  "en-US": Object.freeze({}),
+});
+`;
+
 /** @param {string} directory @returns {Promise<string[]>} */
 async function filesBelow(directory) {
  const entries = await readdir(directory, { withFileTypes: true });
@@ -135,6 +141,10 @@ await writeFile(
  path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"),
  emptyAdapters,
 );
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-messages.js"),
+  emptyMessages,
+);

 /** @type {string[]} */
 const residue = [];
@@ -0,0 +1,102 @@
+import type { DiagnosticsPort } from "../../application/ports/diagnostics-port.js";
+import {
+  projectDiagnosticRecord,
+  safeErrorKind,
+  type DiagnosticRecord,
+  type DiagnosticRecordInput,
+} from "../../contracts/diagnostics.js";
+import { projectTelemetryEvent } from "../../contracts/telemetry.js";
+
+export const noOpDiagnostics: DiagnosticsPort = Object.freeze({
+  record() {},
+});
+
+export function createDiagnosticsAdapter(
+  options: Readonly<{
+    maxEntries?: number;
+    now?: () => number;
+    sink?: (record: DiagnosticRecord) => void;
+  }> = {},
+) {
+  const maxEntries = Math.max(1, options.maxEntries ?? 100);
+  const entries: DiagnosticRecord[] = [];
+  const droppedReasons = new Map<string, number>();
+
+  function drop(reason: string) {
+    droppedReasons.set(reason, (droppedReasons.get(reason) ?? 0) + 1);
+  }
+
+  function record(input: DiagnosticRecordInput) {
+    try {
+      const projected = projectDiagnosticRecord(input, options.now);
+      if (!projected.success) {
+        drop(projected.reason);
+        return;
+      }
+      if (entries.length >= maxEntries) {
+        entries.shift();
+        drop("queue-full");
+      }
+      entries.push(projected.record);
+      try {
+        options.sink?.(projected.record);
+      } catch {
+        drop("sink-failure");
+      }
+    } catch {
+      drop("serialization-failure");
+    }
+  }
+
+  return Object.freeze({
+    record,
+    entries: () => structuredClone(entries) as readonly DiagnosticRecord[],
+    dropped: () => Object.freeze(Object.fromEntries(droppedReasons)),
+  });
+}
+
+type BootSafeContext = Readonly<{
+  kind?: string;
+  buildId?: string;
+  configSchemaVersion?: string;
+  supportReference?: string;
+}>;
+
+let lastBootEvidence:
+  | Readonly<{
+      diagnostic: DiagnosticRecord | null;
+      telemetry: Readonly<Record<string, unknown>> | null;
+    }>
+  | undefined;
+
+export function recordBootFailure(
+  error: unknown,
+  safe: BootSafeContext,
+  now: () => number = Date.now,
+) {
+  const errorKind =
+    typeof safe.kind === "string" ? safe.kind : safeErrorKind(error);
+  const attributes = {
+    error_kind: errorKind,
+    build_id: safe.buildId ?? "unknown",
+    config_schema_version: safe.configSchemaVersion ?? "unknown",
+  };
+  const diagnostic = projectDiagnosticRecord(
+    {
+      level: "error",
+      eventId: "app.boot.failed",
+      context: attributes,
+    },
+    now,
+  );
+  const telemetry = projectTelemetryEvent("app.boot.failed", attributes, now);
+  lastBootEvidence = Object.freeze({
+    diagnostic: diagnostic.success ? diagnostic.record : null,
+    telemetry: telemetry.success ? telemetry.event : null,
+  });
+  return lastBootEvidence;
+}
+
+export function getLastBootEvidence() {
+  return lastBootEvidence ? structuredClone(lastBootEvidence) : undefined;
+}
@@ -14,6 +14,11 @@ import {
  validateOperationRequest,
 } from "./schema-registry.js";
 import { buildRequestTarget } from "./request-builder.js";
+import {
+  attemptBucket,
+  durationBucket,
+  statusGroup,
+} from "../../contracts/diagnostics.js";

 const noAuthSession =
  /** @type {import("../../application/ports/auth-session-port.js").AuthSessionPort} */ ({
@@ -54,7 +59,10 @@ const noAuthSession =
 *   timeoutMs?: number,
 *   maxRetryAttempts?: number,
 *   scheduler?: Scheduler,
- *   getOperation?: typeof getApiOperation
+ *   getOperation?: typeof getApiOperation,
+ *   diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort,
+ *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort,
+ *   correlationIdFactory?: () => string
 * }} dependencies
 */
 export function createHttpClient(dependencies) {
@@ -72,6 +80,11 @@ export function createHttpClient(dependencies) {
  const defaultTimeoutMs = dependencies.timeoutMs ?? 10_000;
  const maxRetryAttempts = dependencies.maxRetryAttempts ?? 2;
  const selectOperation = dependencies.getOperation ?? getApiOperation;
+  const diagnostics = dependencies.diagnostics;
+  const telemetry = dependencies.telemetry;
+  const correlationIdFactory =
+    dependencies.correlationIdFactory ??
+    (() => `request-${Math.floor(random() * 1_000_000).toString(36)}`);
  const scheduler =
    dependencies.scheduler ??
    /** @type {Scheduler} */ ({
@@ -91,7 +104,8 @@ export function createHttpClient(dependencies) {
   *   pathParams?: Record<string, string | number>,
   *   searchParams?: unknown,
 *   signal?: AbortSignal,
- *   idempotencyKey?: string
+ *   idempotencyKey?: string,
+ *   correlationId?: string
   * }} [legacyInput]
 * @returns {Promise<HttpResult>}
 */
@@ -106,9 +120,55 @@ export function createHttpClient(dependencies) {
            body: legacyInput.body,
            signal: legacyInput.signal,
            idempotencyKey: legacyInput.idempotencyKey,
+            correlationId: legacyInput.correlationId,
          }
        : request;
    const operation = selectOperation(input.operationId);
+    const startedAt = clock.now();
+    const correlationId = input.correlationId ?? correlationIdFactory();
+    /**
+     * @param {HttpResult} outcome
+     * @param {"success" | "recovered" | "failed" | "aborted"} outcomeKind
+     */
+    function finalize(outcome, outcomeKind) {
+      const error = outcome.ok ? undefined : outcome.error;
+      const context = {
+        route_id: input.routeId,
+        operation_id: input.operationId,
+        correlation_id: correlationId,
+        outcome: outcomeKind,
+        error_kind: error?.kind ?? "NONE",
+        http_status_group: statusGroup(error?.httpStatus),
+        attempt_count_bucket: attemptBucket(
+          error?.attemptCount ?? retryCount + 1,
+        ),
+        duration_bucket: durationBucket(clock.now() - startedAt),
+      };
+      try {
+        diagnostics?.record({
+          level: error ? "warn" : "info",
+          eventId: "http.request.completed",
+          context,
+        });
+      } catch {
+        // Diagnostics cannot change the HTTP result.
+      }
+      if (error && outcomeKind !== "aborted") {
+        try {
+          telemetry?.emit("api.request.failed", {
+            error_kind: context.error_kind,
+            http_status_group: context.http_status_group,
+            attempt_count_bucket: context.attempt_count_bucket,
+            route_id: context.route_id,
+            operation_id: context.operation_id,
+            duration_bucket: context.duration_bucket,
+          });
+        } catch {
+          // Telemetry cannot change the HTTP result.
+        }
+      }
+      return outcome;
+    }
    const logicalIdempotencyKey =
      operation.idempotency === "keyed"
        ? input.idempotencyKey ?? idempotencyKeyFactory()
@@ -126,28 +186,40 @@ export function createHttpClient(dependencies) {
        idempotencyKey: logicalIdempotencyKey,
      });

-      if (outcome.ok) return outcome;
+      if (outcome.ok) {
+        return finalize(
+          outcome,
+          retryCount > 0 || recoveryUsed ? "recovered" : "success",
+        );
+      }

      if (outcome.error.httpStatus === 401 && !recoveryUsed) {
        recoveryUsed = true;
-        const recovered = await recoverSession(authSession, operation, outcome.error);
-        if (!recovered.ok) return recovered;
+        const recovered = await recoverSession(
+          authSession,
+          operation,
+          outcome.error,
+        );
+        if (!recovered.ok) return finalize(recovered, "failed");
        if (operation.idempotency === "none") {
-          return {
-            ok: false,
-            error: {
-              ...outcome.error,
-              retryable: false,
-              action: "retry",
+          return finalize(
+            {
+              ok: false,
+              error: {
+                ...outcome.error,
+                retryable: false,
+                action: "retry",
+              },
            },
-          };
+            "failed",
+          );
        }
        continue;
      }

      if (outcome.error.httpStatus === 401 && recoveryUsed) {
        authSession.onUnauthenticated();
-        return outcome;
+        return finalize(outcome, "failed");
      }

      if (
@@ -158,7 +230,10 @@ export function createHttpClient(dependencies) {
          maxRetryAttempts,
        )
      ) {
-        return outcome;
+        return finalize(
+          outcome,
+          outcome.error.kind === "REQUEST_ABORTED" ? "aborted" : "failed",
+        );
      }

      const delay = retryDelay(outcome.error, retryCount, random, clock.now());
@@ -167,12 +242,15 @@ export function createHttpClient(dependencies) {
      try {
        await clock.sleep(delay, input.signal);
      } catch {
-        return {
-          ok: false,
-          error: failure("REQUEST_ABORTED", input.operationId, retryCount, {
-            code: "REQUEST_ABORTED",
-          }),
-        };
+        return finalize(
+          {
+            ok: false,
+            error: failure("REQUEST_ABORTED", input.operationId, retryCount, {
+              code: "REQUEST_ABORTED",
+            }),
+          },
+          "aborted",
+        );
      }
    }
  }
@@ -8,6 +8,7 @@ export type OperationRequestInput = Readonly<{
  body?: unknown;
  signal?: AbortSignal;
  idempotencyKey?: string;
+  correlationId?: string;
 }>;

 export type RequestTargetResult =
@@ -1,6 +1,7 @@
-import { QueryClient } from "@tanstack/react-query";
+import { MutationCache, QueryCache, QueryClient } from "@tanstack/react-query";

 import { createFailure } from "../../contracts/errors.js";
+import { safeErrorKind } from "../../contracts/diagnostics.js";

 export const QUERY_CACHE_DEFAULTS = Object.freeze({
  staleTime: 30_000,
@@ -11,8 +12,32 @@ export const QUERY_CACHE_DEFAULTS = Object.freeze({
  persistence: false,
 });

-export function createQueryClient() {
+/**
+ * @param {{diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort}} [dependencies]
+ */
+export function createQueryClient(dependencies = {}) {
+  /** @param {string} operation @param {unknown} error */
+  function report(operation, error) {
+    try {
+      dependencies.diagnostics?.record({
+        level: "warn",
+        eventId: "cache.operation.failed",
+        context: {
+          operation,
+          error_kind: safeErrorKind(error),
+        },
+      });
+    } catch {
+      // Query behavior remains independent from diagnostics.
+    }
+  }
  return new QueryClient({
+    queryCache: new QueryCache({
+      onError: (error) => report("query", error),
+    }),
+    mutationCache: new MutationCache({
+      onError: (error) => report("mutation", error),
+    }),
    defaultOptions: {
      queries: {
        staleTime: QUERY_CACHE_DEFAULTS.staleTime,
@@ -29,15 +54,16 @@ export function createQueryClient() {

 /**
 * @param {QueryClient} queryClient
+ * @param {{diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort}} [dependencies]
 * @returns {import("../../application/ports/query-cache-port.js").QueryCachePort}
 */
-export function createQueryCacheAdapter(queryClient) {
+export function createQueryCacheAdapter(queryClient, dependencies = {}) {
  return Object.freeze({
    read(key) {
      try {
        return { ok: true, value: queryClient.getQueryData(key) };
      } catch {
-        return cacheFailure("read", key);
+        return cacheFailure("read", key, dependencies.diagnostics);
      }
    },
    write(key, value) {
@@ -45,7 +71,7 @@ export function createQueryCacheAdapter(queryClient) {
        queryClient.setQueryData(key, structuredClone(value));
        return { ok: true };
      } catch {
-        return cacheFailure("write", key);
+        return cacheFailure("write", key, dependencies.diagnostics);
      }
    },
    async invalidate(namespace) {
@@ -53,15 +79,31 @@ export function createQueryCacheAdapter(queryClient) {
        await queryClient.invalidateQueries({ queryKey: namespace, exact: false });
        return { ok: true };
      } catch {
-        return cacheFailure("invalidate", namespace);
+        return cacheFailure("invalidate", namespace, dependencies.diagnostics);
      }
    },
  });
 }

-/** @param {string} phase @param {readonly unknown[]} key */
-function cacheFailure(phase, key) {
+/**
+ * @param {string} phase
+ * @param {readonly unknown[]} key
+ * @param {import("../../application/ports/diagnostics-port.js").DiagnosticsPort | undefined} diagnostics
+ */
+function cacheFailure(phase, key, diagnostics) {
  const namespace = typeof key[0] === "string" ? key[0] : "unknown";
+  try {
+    diagnostics?.record({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: {
+        operation: phase,
+        error_kind: "QUERY_CACHE_FAILURE",
+      },
+    });
+  } catch {
+    // Cache behavior remains independent from diagnostics.
+  }
  return {
    ok: /** @type {false} */ (false),
    error: createFailure("QUERY_CACHE_FAILURE", "QUERY_CACHE", 0, {
@@ -5,7 +5,8 @@ import { getStorageDefinition } from "../../contracts/storage-keys.js";
 * @param {{
 *   localStorage?: Storage,
 *   sessionStorage?: Storage,
- *   now?: () => number
+ *   now?: () => number,
+ *   diagnostics?: import("../../application/ports/diagnostics-port.js").DiagnosticsPort
 * }} [dependencies]
 * @returns {import("../../application/ports/storage-port.js").StoragePort}
 */
@@ -26,7 +27,7 @@ export function createBrowserStorageAdapter(dependencies = {}) {
      try {
        definition = getStorageDefinition(logicalName);
      } catch {
-        return unavailable("read", logicalName);
+        return unavailable("read", logicalName, dependencies.diagnostics);
      }

      const backend = backendFor(definition.backend);
@@ -50,7 +51,7 @@ export function createBrowserStorageAdapter(dependencies = {}) {
        }
        return { ok: true, value: structuredClone(envelope.value) };
      } catch {
-        return unavailable("read", logicalName);
+        return unavailable("read", logicalName, dependencies.diagnostics);
      }
    },

@@ -59,7 +60,7 @@ export function createBrowserStorageAdapter(dependencies = {}) {
      try {
        definition = getStorageDefinition(logicalName);
      } catch {
-        return unavailable("write", logicalName);
+        return unavailable("write", logicalName, dependencies.diagnostics);
      }

      const expiresAt =
@@ -82,12 +83,24 @@ export function createBrowserStorageAdapter(dependencies = {}) {

        if (definition.quotaFallback === "memory") {
          memory.set(definition.physicalKey, structuredClone(value));
+          recordStorageFailure(
+            dependencies.diagnostics,
+            "write",
+            logicalName,
+            quota,
+          );
          return {
            ok: false,
            error: storageFailure(quota, "write", logicalName),
            fallback: "memory",
          };
        }
+        recordStorageFailure(
+          dependencies.diagnostics,
+          "write",
+          logicalName,
+          quota,
+        );
        return {
          ok: false,
          error: storageFailure(quota, "write", logicalName),
@@ -101,14 +114,14 @@ export function createBrowserStorageAdapter(dependencies = {}) {
      try {
        definition = getStorageDefinition(logicalName);
      } catch {
-        return unavailable("remove", logicalName);
+        return unavailable("remove", logicalName, dependencies.diagnostics);
      }
      try {
        backendFor(definition.backend)?.removeItem(definition.physicalKey);
        memory.delete(definition.physicalKey);
        return { ok: true };
      } catch {
-        return unavailable("remove", logicalName);
+        return unavailable("remove", logicalName, dependencies.diagnostics);
      }
    },
  });
@@ -128,10 +141,38 @@ function storageFailure(quota, phase, logicalName) {
  );
 }

-/** @param {string} phase @param {string} logicalName */
-function unavailable(phase, logicalName) {
+/**
+ * @param {string} phase
+ * @param {string} logicalName
+ * @param {import("../../application/ports/diagnostics-port.js").DiagnosticsPort | undefined} diagnostics
+ */
+function unavailable(phase, logicalName, diagnostics) {
+  recordStorageFailure(diagnostics, phase, logicalName, false);
  return {
    ok: /** @type {false} */ (false),
    error: storageFailure(false, phase, logicalName),
  };
 }
+
+/**
+ * @param {import("../../application/ports/diagnostics-port.js").DiagnosticsPort | undefined} diagnostics
+ * @param {string} phase
+ * @param {string} logicalName
+ * @param {boolean} quota
+ */
+function recordStorageFailure(diagnostics, phase, logicalName, quota) {
+  try {
+    diagnostics?.record({
+      level: "warn",
+      eventId: "storage.operation.failed",
+      context: {
+        operation: `${phase}:${logicalName}`,
+        error_kind: quota
+          ? "STORAGE_QUOTA_EXCEEDED"
+          : "STORAGE_UNAVAILABLE",
+      },
+    });
+  } catch {
+    // Storage behavior remains independent from diagnostics.
+  }
+}
@@ -1,7 +1,14 @@
 import { projectTelemetryEvent } from "../../contracts/telemetry.js";
+import { queueSizeBucket } from "../../contracts/diagnostics.js";

 export const noOpTelemetry = Object.freeze({
  emit: () => {},
+  flush: async () => {},
+  pendingCount: () => 0,
+  droppedCount: () => 0,
+  dropReasons: () => Object.freeze({}),
+  deliveryEvidence: () => null,
+  dispose: () => {},
 });

 /**
@@ -10,22 +17,20 @@ export const noOpTelemetry = Object.freeze({
 *   endpoint?: string,
 *   fetcher?: typeof fetch,
 *   maxQueue?: number,
- *   schedule?: (callback: () => void) => void
+ *   schedule?: (callback: () => void) => void,
+ *   now?: () => number,
+ *   onDrop?: (event: Readonly<Record<string, unknown>>) => void,
+ *   lifecycle?: Pick<EventTarget, "addEventListener" | "removeEventListener">
 * }} options
 */
 export function createTelemetryAdapter(options) {
  if (!options.enabled || !options.endpoint) {
-    return Object.freeze({
-      ...noOpTelemetry,
-      flush: async () => {},
-      pendingCount: () => 0,
-      droppedCount: () => 0,
-    });
+    return noOpTelemetry;
  }

  const endpoint = /** @type {string} */ (options.endpoint);
  const fetcher = options.fetcher ?? fetch;
-  const maxQueue = options.maxQueue ?? 100;
+  const maxQueue = Math.max(1, options.maxQueue ?? 100);
  const schedule = options.schedule ?? queueMicrotask;
  const queue =
    /** @type {Array<{eventName: string, attributes: Readonly<Record<string, unknown>>}>} */ (
@@ -34,18 +39,63 @@ export function createTelemetryAdapter(options) {
  let scheduled = false;
  let flushing = false;
  let dropped = 0;
+  const dropReasons = new Map();
+  let lastDeliveryEvidence =
+    /** @type {Readonly<Record<string, unknown>> | null} */ (null);
+  const lifecycle =
+    options.lifecycle ??
+    (typeof globalThis.addEventListener === "function" &&
+    typeof globalThis.removeEventListener === "function"
+      ? globalThis
+      : undefined);
+
+  /** @param {string} reason @param {number} count */
+  function recordDrop(reason, count = 1) {
+    const safeReason =
+      {
+        "queue-full": "queue-full",
+        "sink-failure": "sink-failure",
+        "serialization-failure": "serialization-failure",
+        "unknown-attributes": "invalid-context",
+        "invalid-attribute-value": "invalid-context",
+        "missing-required-attributes": "invalid-context",
+        "unregistered-event": "invalid-event",
+      }[reason] ?? "invalid-event";
+    dropped += count;
+    dropReasons.set(safeReason, (dropReasons.get(safeReason) ?? 0) + count);
+    const internal = projectTelemetryEvent(
+      "telemetry.delivery.dropped",
+      {
+        reason: safeReason,
+        queue_size_bucket: queueSizeBucket(queue.length),
+      },
+      options.now,
+    );
+    if (internal.success) {
+      lastDeliveryEvidence = internal.event;
+      try {
+        options.onDrop?.(internal.event);
+      } catch {
+        // Drop observers are deliberately nonrecursive.
+      }
+    }
+  }

  /** @param {string} eventName @param {Record<string, unknown>} attributes */
  function emit(eventName, attributes) {
-    const projected = projectTelemetryEvent(eventName, attributes);
+    const projected = projectTelemetryEvent(
+      eventName,
+      attributes,
+      options.now,
+    );
    if (!projected.success) {
-      dropped += 1;
+      recordDrop(projected.reason);
      return;
    }

    if (queue.length >= maxQueue) {
      queue.shift();
-      dropped += 1;
+      recordDrop("queue-full");
    }
    queue.push(projected.event);

@@ -69,19 +119,32 @@ export function createTelemetryAdapter(options) {
        body: JSON.stringify({ events: batch }),
        keepalive: true,
      });
-      if (!response.ok) dropped += batch.length;
+      if (!response.ok) recordDrop("sink-failure", batch.length);
    } catch {
-      dropped += batch.length;
+      recordDrop("sink-failure", batch.length);
    } finally {
      flushing = false;
    }
  }

+  const flushBeforePageExit = () => {
+    void flush();
+  };
+  lifecycle?.addEventListener("pagehide", flushBeforePageExit);
+
+  function dispose() {
+    lifecycle?.removeEventListener("pagehide", flushBeforePageExit);
+  }
+
  return Object.freeze({
    emit,
    flush,
    pendingCount: () => queue.length,
    droppedCount: () => dropped,
+    dropReasons: () => Object.freeze(Object.fromEntries(dropReasons)),
+    deliveryEvidence: () =>
+      lastDeliveryEvidence ? structuredClone(lastDeliveryEvidence) : null,
+    dispose,
  });
 }

@@ -3,6 +3,7 @@ import type {
  ApplicationApi,
  ColorSchemePreference,
  RenderFailureReport,
+  RouteChangedReport,
 } from "./ports/in/application-api.js";
 import type { ApplicationOutputPorts } from "./ports/out/application-output-ports.js";
 import { decideChunkRecovery } from "./use-cases/decide-chunk-recovery.js";
@@ -43,7 +44,20 @@ export function createApplication(
  const diagnostics = Object.freeze({
    reportRenderFailure(report: RenderFailureReport) {
      try {
-        outputPorts.diagnostics.emit("ui.render.failed", {
+        outputPorts.diagnostics.record({
+          level: "error",
+          eventId: "ui.render.failed",
+          context: {
+            route_id: report.routeId,
+            build_id: report.buildId,
+            component_boundary: report.boundaryName,
+          },
+        });
+      } catch {
+        // Diagnostics are best-effort and cannot become an application failure.
+      }
+      try {
+        outputPorts.telemetry.emit("ui.render.failed", {
          route_id: report.routeId,
          build_id: report.buildId,
          component_boundary: report.boundaryName,
@@ -52,6 +66,20 @@ export function createApplication(
        // Diagnostics are best-effort and cannot become an application failure.
      }
    },
+    reportRouteChanged(report: RouteChangedReport) {
+      try {
+        outputPorts.diagnostics.record({
+          level: "info",
+          eventId: "route.changed",
+          context: {
+            route_id: report.routeId,
+            build_id: report.buildId,
+          },
+        });
+      } catch {
+        // Diagnostics are best-effort and cannot become navigation failure.
+      }
+    },
  });

  const runtime = Object.freeze({
@@ -74,6 +102,37 @@ export function createApplication(
      try {
        const current = await outputPorts.releaseInfo.getCurrent();
        const active = await outputPorts.releaseInfo.refresh();
+        if (
+          current.buildId !== active.buildId ||
+          current.releaseId !== active.releaseId
+        ) {
+          const mismatchKind =
+            current.buildId !== active.buildId
+              ? "BUILD_MISMATCH"
+              : "RELEASE_MISMATCH";
+          try {
+            outputPorts.diagnostics.record({
+              level: "warn",
+              eventId: "release.mismatch.detected",
+              context: {
+                build_id: current.buildId,
+                active_release_id: active.releaseId,
+                mismatch_kind: mismatchKind,
+              },
+            });
+          } catch {
+            // Recovery remains independent from diagnostics.
+          }
+          try {
+            outputPorts.telemetry.emit("release.mismatch.detected", {
+              build_id: current.buildId,
+              active_release_id: active.releaseId,
+              mismatch_kind: mismatchKind,
+            });
+          } catch {
+            // Recovery remains independent from telemetry.
+          }
+        }
        if (!active.routeChunks[input.chunkId]) {
          return {
            action: "support" as const,
@@ -0,0 +1,5 @@
+import type { DiagnosticRecordInput } from "../../contracts/diagnostics.js";
+
+export type DiagnosticsPort = Readonly<{
+  record(input: DiagnosticRecordInput): void;
+}>;
@@ -11,6 +11,11 @@ export type RenderFailureReport = Readonly<{
  boundaryName: "route" | "feature";
 }>;

+export type RouteChangedReport = Readonly<{
+  routeId: string;
+  buildId: string;
+}>;
+
 export type ReleaseSummary = Readonly<{
  buildId: string;
  releaseId: string;
@@ -34,6 +39,7 @@ export type ApplicationApi = Readonly<{
  }>;
  diagnostics: Readonly<{
    reportRenderFailure(report: RenderFailureReport): void;
+    reportRouteChanged(report: RouteChangedReport): void;
  }>;
  runtime: Readonly<{
    getReleaseSummary(): Promise<ReleaseSummary>;
@@ -2,6 +2,7 @@ import type { AuthSessionPort } from "../auth-session-port.js";
 import type { ReleaseInfoPort } from "../release-info-port.js";
 import type { StoragePort } from "../storage-port.js";
 import type { TelemetryPort } from "../telemetry-port.js";
+import type { DiagnosticsPort } from "../diagnostics-port.js";

 /**
 * Capabilities required by application use cases. Implementations live in
@@ -13,7 +14,8 @@ export type ApplicationOutputPorts = Readonly<{
    "getState" | "subscribe" | "beginSignIn" | "signOut" | "recover"
  >;
  preferences: StoragePort;
-  diagnostics: TelemetryPort;
+  diagnostics: DiagnosticsPort;
+  telemetry: TelemetryPort;
  releaseInfo: ReleaseInfoPort;
  navigation: Readonly<{ reload(): void }>;
 }>;
@@ -9,3 +9,4 @@ export type { QueryCachePort } from "../query-cache-port.js";
 export type { ReleaseInfoPort } from "../release-info-port.js";
 export type { StoragePort } from "../storage-port.js";
 export type { TelemetryPort } from "../telemetry-port.js";
+export type { DiagnosticsPort } from "../diagnostics-port.js";
@@ -1,5 +0,0 @@
-/**
- * @typedef {{ emit(eventName: string, attributes: Record<string, unknown>): void }} TelemetryPort
- */
-
-export {};
@@ -0,0 +1,10 @@
+import type { TelemetryEventName } from "../../contracts/telemetry.js";
+
+export type { TelemetryEventName };
+
+export type TelemetryPort = Readonly<{
+  emit(
+    eventName: TelemetryEventName,
+    attributes: Record<string, unknown>,
+  ): void;
+}>;
@@ -1,5 +1,6 @@
 import { createRoot } from "react-dom/client";

+import { recordBootFailure } from "../adapters/diagnostics/bounded-diagnostics.js";
 import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.jsx";
 import { createRuntimeComposition } from "./create-runtime-composition.js";
 import { initializeColorScheme } from "./initialize-color-scheme.js";
@@ -27,6 +28,7 @@ async function boot() {
        ? error.safe
        : { supportReference: "boot:unknown" };

+    recordBootFailure(error, safe);
    root.render(<BootErrorShell {...safe} />);
  }
 }
@@ -4,6 +4,7 @@ import {
  createUnavailableSessionAdapter,
 } from "../adapters/auth/external-session-adapter.js";
 import { createHttpClient } from "../adapters/http/client.js";
+import { createDiagnosticsAdapter } from "../adapters/diagnostics/bounded-diagnostics.js";
 import {
  createQueryClient,
 } from "../adapters/query-cache/tanstack-query-cache.js";
@@ -53,6 +54,8 @@ function storageOrUndefined(value) {
 *   fetcher?: typeof fetch,
 *   clock?: import("../application/ports/clock-port.js").ClockPort,
 *   scheduler?: Parameters<typeof createHttpClient>[0]["scheduler"]
+ *   diagnostics?: Parameters<typeof createHttpClient>[0]["diagnostics"],
+ *   telemetry?: Parameters<typeof createHttpClient>[0]["telemetry"]
 * }} context
 */
 export function createRuntimeHttpClient(context, contract = {}) {
@@ -64,6 +67,8 @@ export function createRuntimeHttpClient(context, contract = {}) {
    fetcher: context.fetcher,
    clock: context.clock,
    scheduler: context.scheduler,
+    diagnostics: context.diagnostics,
+    telemetry: context.telemetry,
    ...contract,
  });
 }
@@ -86,15 +91,28 @@ export async function createRuntimeAdapters(context) {
      : externalOwner
        ? createExternalAuthSessionAdapter(externalOwner)
        : createUnavailableSessionAdapter();
-  const queryClient = createQueryClient();
-  const storage = createBrowserStorageAdapter({
-    localStorage: storageOrUndefined(host.localStorage),
-    sessionStorage: storageOrUndefined(host.sessionStorage),
-  });
+  const diagnostics = createDiagnosticsAdapter();
  const telemetry = createTelemetryAdapter({
    enabled: config.TELEMETRY_ENABLED,
    endpoint: config.TELEMETRY_ENDPOINT,
    fetcher: context.fetcher,
+    onDrop(event) {
+      const attributes =
+        event.attributes && typeof event.attributes === "object"
+          ? event.attributes
+          : {};
+      diagnostics.record({
+        level: "warn",
+        eventId: "telemetry.delivery.dropped",
+        context: /** @type {Record<string, unknown>} */ (attributes),
+      });
+    },
+  });
+  const queryClient = createQueryClient({ diagnostics });
+  const storage = createBrowserStorageAdapter({
+    localStorage: storageOrUndefined(host.localStorage),
+    sessionStorage: storageOrUndefined(host.sessionStorage),
+    diagnostics,
  });
  const releaseInfo = Object.freeze({
    async getCurrent() {
@@ -125,6 +143,8 @@ export async function createRuntimeAdapters(context) {
          runtime: context.runtime,
          authSession,
          fetcher: context.fetcher,
+          diagnostics,
+          telemetry,
        },
        contract,
      ),
@@ -134,7 +154,8 @@ export async function createRuntimeAdapters(context) {
    outputPorts: Object.freeze({
      session: authSession,
      preferences: storage,
-      diagnostics: telemetry,
+      diagnostics,
+      telemetry,
      releaseInfo,
      navigation,
    }),
@@ -0,0 +1,183 @@
+export const DIAGNOSTIC_LEVELS = Object.freeze([
+  "debug",
+  "info",
+  "warn",
+  "error",
+] as const);
+export type DiagnosticLevel = (typeof DIAGNOSTIC_LEVELS)[number];
+
+export const DIAGNOSTIC_EVENT_REGISTRY = Object.freeze({
+  "app.boot.failed": Object.freeze({ level: "error" }),
+  "http.request.completed": Object.freeze({ level: "info" }),
+  "cache.operation.failed": Object.freeze({ level: "warn" }),
+  "storage.operation.failed": Object.freeze({ level: "warn" }),
+  "route.changed": Object.freeze({ level: "info" }),
+  "ui.render.failed": Object.freeze({ level: "error" }),
+  "release.mismatch.detected": Object.freeze({ level: "warn" }),
+  "telemetry.delivery.dropped": Object.freeze({ level: "warn" }),
+});
+export type DiagnosticEventId = keyof typeof DIAGNOSTIC_EVENT_REGISTRY;
+
+export const DIAGNOSTIC_CONTEXT_ALLOWLIST = Object.freeze([
+  "app_version",
+  "build_id",
+  "release_id",
+  "active_release_id",
+  "config_schema_version",
+  "api_contract_version",
+  "route_id",
+  "operation_id",
+  "correlation_id",
+  "error_kind",
+  "outcome",
+  "http_status_group",
+  "attempt_count_bucket",
+  "duration_bucket",
+  "component_boundary",
+  "mismatch_kind",
+  "operation",
+  "reason",
+  "queue_size_bucket",
+] as const);
+export type DiagnosticContextKey =
+  (typeof DIAGNOSTIC_CONTEXT_ALLOWLIST)[number];
+export type DiagnosticContext = Readonly<
+  Partial<Record<DiagnosticContextKey, string | number | boolean>>
+>;
+
+export type DiagnosticRecordInput = Readonly<{
+  level: DiagnosticLevel;
+  eventId: DiagnosticEventId;
+  context?: Readonly<Record<string, unknown>>;
+}>;
+
+export type DiagnosticRecord = Readonly<{
+  level: DiagnosticLevel;
+  eventId: DiagnosticEventId;
+  timestamp: string;
+  context: DiagnosticContext;
+}>;
+
+const SAFE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/;
+
+function projectDiagnosticRecordUnsafe(
+  input: DiagnosticRecordInput,
+  now: () => number = Date.now,
+):
+  | Readonly<{ success: true; record: DiagnosticRecord }>
+  | Readonly<{ success: false; reason: string }> {
+  if (!Object.hasOwn(DIAGNOSTIC_EVENT_REGISTRY, input.eventId)) {
+    return { success: false, reason: "unregistered-event" };
+  }
+  if (!DIAGNOSTIC_LEVELS.includes(input.level)) {
+    return { success: false, reason: "invalid-level" };
+  }
+  const contextEntries = Object.entries(input.context ?? {});
+  if (contextEntries.length > DIAGNOSTIC_CONTEXT_ALLOWLIST.length) {
+    return { success: false, reason: "invalid-context" };
+  }
+  const projected: Partial<
+    Record<DiagnosticContextKey, string | number | boolean>
+  > = {};
+  for (const [key, value] of contextEntries) {
+    if (
+      !DIAGNOSTIC_CONTEXT_ALLOWLIST.includes(key as DiagnosticContextKey)
+    ) {
+      return { success: false, reason: "unknown-context" };
+    }
+    if (typeof value === "string") {
+      if (!SAFE_VALUE.test(value)) {
+        return { success: false, reason: "invalid-context" };
+      }
+      projected[key as DiagnosticContextKey] = value;
+    } else if (typeof value === "number" && Number.isFinite(value)) {
+      projected[key as DiagnosticContextKey] = value;
+    } else if (typeof value === "boolean") {
+      projected[key as DiagnosticContextKey] = value;
+    } else {
+      return { success: false, reason: "invalid-context" };
+    }
+  }
+  let timestamp: string;
+  try {
+    timestamp = new Date(now()).toISOString();
+  } catch {
+    timestamp = new Date(0).toISOString();
+  }
+  return {
+    success: true,
+    record: Object.freeze({
+      level: input.level,
+      eventId: input.eventId,
+      timestamp,
+      context: Object.freeze(projected),
+    }),
+  };
+}
+
+export function projectDiagnosticRecord(
+  input: DiagnosticRecordInput,
+  now: () => number = Date.now,
+): ReturnType<typeof projectDiagnosticRecordUnsafe> {
+  try {
+    return projectDiagnosticRecordUnsafe(input, now);
+  } catch {
+    return { success: false, reason: "serialization-failure" };
+  }
+}
+
+export function safeErrorKind(error: unknown): string {
+  try {
+    if (error && typeof error === "object") {
+      const record = error as Readonly<Record<string, unknown>>;
+      if (
+        typeof record.kind === "string" &&
+        /^[A-Z][A-Z0-9_]{0,63}$/.test(record.kind)
+      ) {
+        return record.kind;
+      }
+      if (
+        typeof record.name === "string" &&
+        /^[A-Za-z][A-Za-z0-9]{0,63}$/.test(record.name)
+      ) {
+        const normalized = record.name
+          .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+          .toUpperCase();
+        return /^[A-Z][A-Z0-9_]{0,63}$/.test(normalized)
+          ? normalized
+          : "UNKNOWN_FAILURE";
+      }
+    }
+  } catch {
+    return "UNKNOWN_FAILURE";
+  }
+  return "UNKNOWN_FAILURE";
+}
+
+export function statusGroup(status: number | undefined): string {
+  return typeof status === "number" && Number.isFinite(status)
+    ? `${Math.max(0, Math.min(9, Math.floor(status / 100)))}xx`
+    : "none";
+}
+
+export function attemptBucket(attemptCount: number): string {
+  if (attemptCount <= 1) return "1";
+  if (attemptCount === 2) return "2";
+  if (attemptCount <= 4) return "3-4";
+  return "5+";
+}
+
+export function durationBucket(durationMs: number): string {
+  if (!Number.isFinite(durationMs) || durationMs < 0) return "unknown";
+  if (durationMs < 100) return "lt100ms";
+  if (durationMs < 500) return "100-499ms";
+  if (durationMs < 2_000) return "500-1999ms";
+  return "gte2000ms";
+}
+
+export function queueSizeBucket(size: number): string {
+  if (size <= 0) return "0";
+  if (size <= 10) return "1-10";
+  if (size <= 50) return "11-50";
+  return "51+";
+}
@@ -0,0 +1,36 @@
+export type TelemetryEventName =
+  | "app.boot.failed"
+  | "api.request.failed"
+  | "ui.render.failed"
+  | "release.mismatch.detected"
+  | "telemetry.delivery.dropped";
+
+export type TelemetryDefinition = Readonly<{
+  eventName: TelemetryEventName;
+  trigger: string;
+  requiredAttributes: readonly string[];
+  optionalAttributes: readonly string[];
+  forbiddenAttributes: readonly string[];
+  sampling: string;
+  delivery: "best-effort";
+}>;
+
+export type TelemetryEvent = Readonly<{
+  eventName: TelemetryEventName;
+  timestamp: string;
+  attributes: Readonly<Record<string, unknown>>;
+}>;
+
+export const TELEMETRY_ATTRIBUTE_ALLOWLIST: readonly string[];
+export const TELEMETRY_FORBIDDEN_ATTRIBUTES: readonly string[];
+export const TELEMETRY_REGISTRY: Readonly<
+  Record<TelemetryEventName, TelemetryDefinition>
+>;
+
+export function projectTelemetryEvent(
+  eventName: string,
+  attributes: Record<string, unknown>,
+  now?: () => number,
+):
+  | Readonly<{ success: true; event: TelemetryEvent }>
+  | Readonly<{ success: false; reason: string }>;
@@ -81,7 +81,7 @@ export const TELEMETRY_REGISTRY = Object.freeze({
    "http_status_group",
    "attempt_count_bucket",
    "route_id",
-  ]),
+  ], ["operation_id", "duration_bucket"]),
  "ui.render.failed": event("ui.render.failed", "React boundary catch", [
    "route_id",
    "build_id",
@@ -101,11 +101,44 @@ export const TELEMETRY_REGISTRY = Object.freeze({
  ),
 });

+const SAFE_IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,63}$/;
+const ATTRIBUTE_VALUE_POLICIES =
+  /** @type {Readonly<Record<string, (value: string) => boolean>>} */ (
+    Object.freeze({
+      route_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      operation_id: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      error_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      http_status_group: (value) => /^(?:[1-5]xx|none)$/.test(value),
+      attempt_count_bucket: (value) => /^(?:1|2|3|3-4|5\+)$/.test(value),
+      duration_bucket: (value) =>
+        /^(?:lt100ms|100-499ms|500-1999ms|gte2000ms|unknown)$/.test(
+          value,
+        ),
+      component_boundary: (value) =>
+        /^(?:route|feature|boot)$/.test(value),
+      mismatch_kind: (value) => /^[A-Z][A-Z0-9_]{0,63}$/.test(value),
+      reason: (value) =>
+        /^(?:queue-full|sink-failure|invalid-event|invalid-context|serialization-failure)$/.test(
+          value,
+        ),
+      queue_size_bucket: (value) =>
+        /^(?:0|1-10|11-50|51\+)$/.test(value),
+    })
+  );
+
+/** @param {string} key @param {unknown} value */
+function validAttributeValue(key, value) {
+  if (typeof value !== "string") return false;
+  const policy = ATTRIBUTE_VALUE_POLICIES[key];
+  return policy ? policy(value) : SAFE_IDENTIFIER.test(value);
+}
+
 /**
 * @param {string} eventName
 * @param {Record<string, unknown>} attributes
+ * @param {() => number} [now]
 */
-export function projectTelemetryEvent(eventName, attributes) {
+function projectTelemetryEventUnsafe(eventName, attributes, now = Date.now) {
  const registry =
    /** @type {Record<string, (typeof TELEMETRY_REGISTRY)[keyof typeof TELEMETRY_REGISTRY]>} */ (
      TELEMETRY_REGISTRY
@@ -118,13 +151,47 @@ export function projectTelemetryEvent(eventName, attributes) {
    };
  }

+  const attributeKeys = Object.keys(attributes);
+  if (
+    attributeKeys.length >
+    TELEMETRY_ATTRIBUTE_ALLOWLIST.length +
+      TELEMETRY_FORBIDDEN_ATTRIBUTES.length
+  ) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "invalid-attribute-value",
+    };
+  }
+  const unknown = attributeKeys.filter(
+    (key) =>
+      !TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+      !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+  );
+  if (unknown.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "unknown-attributes",
+    };
+  }
  const projected = Object.fromEntries(
    Object.entries(attributes).filter(
-      ([key]) =>
+      ([key, value]) =>
        TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
-        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key),
+        !TELEMETRY_FORBIDDEN_ATTRIBUTES.includes(key) &&
+        validAttributeValue(key, value),
    ),
  );
+  const invalid = Object.entries(attributes).filter(
+    ([key, value]) =>
+      TELEMETRY_ATTRIBUTE_ALLOWLIST.includes(key) &&
+      !validAttributeValue(key, value),
+  );
+  if (invalid.length > 0) {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "invalid-attribute-value",
+    };
+  }
  const missing = definition.requiredAttributes.filter(
    (key) => projected[key] === undefined,
  );
@@ -135,11 +202,34 @@ export function projectTelemetryEvent(eventName, attributes) {
    };
  }

+  let timestamp;
+  try {
+    timestamp = new Date(now()).toISOString();
+  } catch {
+    timestamp = new Date(0).toISOString();
+  }
  return {
    success: /** @type {true} */ (true),
    event: Object.freeze({
      eventName,
+      timestamp,
      attributes: Object.freeze(projected),
    }),
  };
 }
+
+/**
+ * @param {string} eventName
+ * @param {Record<string, unknown>} attributes
+ * @param {() => number} [now]
+ */
+export function projectTelemetryEvent(eventName, attributes, now = Date.now) {
+  try {
+    return projectTelemetryEventUnsafe(eventName, attributes, now);
+  } catch {
+    return {
+      success: /** @type {false} */ (false),
+      reason: "serialization-failure",
+    };
+  }
+}
@@ -0,0 +1,10 @@
+import { REFERENCE_MESSAGE_CATALOGS } from "./reference-feature/contracts/reference-message-catalog.js";
+
+export const INSTALLED_MESSAGE_CATALOGS = Object.freeze({
+  "ko-KR": Object.freeze({
+    ...REFERENCE_MESSAGE_CATALOGS["ko-KR"],
+  }),
+  "en-US": Object.freeze({
+    ...REFERENCE_MESSAGE_CATALOGS["en-US"],
+  }),
+});
@@ -6,7 +6,7 @@ import {
 export type ReferenceResourceView = Readonly<{
  resourceId: string;
  title: string;
-  createdAtLabel: string | null;
+  createdAt: string | null;
  optimistic?: boolean;
 }>;

@@ -44,14 +44,10 @@ export function mapReferenceOperation(

 export function toReferenceView(
  resource: ReferenceResource,
-  formatDate: (value: Date) => string = (value) =>
-    new Intl.DateTimeFormat("ko-KR").format(value),
 ): ReferenceResourceView {
  return Object.freeze({
    resourceId: resource.id,
    title: resource.displayName,
-    createdAtLabel: resource.createdAt
-      ? formatDate(new Date(resource.createdAt))
-      : null,
+    createdAt: resource.createdAt,
  });
 }
@@ -0,0 +1,22 @@
+export const REFERENCE_MESSAGE_CATALOGS = Object.freeze({
+  "ko-KR": Object.freeze({
+    "route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
+    "route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
+    "route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
+    "route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
+    "route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
+    "route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
+    "route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
+    "route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
+  }),
+  "en-US": Object.freeze({
+    "route.REFERENCE_RESOURCE_LIST.navigation": "Reference feature",
+    "route.REFERENCE_RESOURCE_LIST.title": "Reference resources",
+    "route.REFERENCE_RESOURCE_DETAIL.navigation": "Reference detail",
+    "route.REFERENCE_RESOURCE_DETAIL.title": "Reference resource detail",
+    "route.REFERENCE_RESOURCE_FORM.navigation": "Reference form",
+    "route.REFERENCE_RESOURCE_FORM.title": "Create reference resource",
+    "route.REFERENCE_RESOURCE_STATUS.navigation": "Reference status",
+    "route.REFERENCE_RESOURCE_STATUS.title": "Reference resource status",
+  }),
+});
@@ -5,9 +5,11 @@ import {
  DetailPage,
 } from "../../../presentation/design-system/index.js";
 import { useRouteInput } from "../../../presentation/routes/app-router.js";
+import { useLocale } from "../../../presentation/i18n/index.js";
 import { useReferenceDetail } from "./use-reference-feature.js";

 export default function ReferenceResourceDetailPage() {
+  const { date, message } = useLocale();
  const route = useRouteInput();
  const resourceId = String(route.params.resourceId);
  const { query } = useReferenceDetail(resourceId);
@@ -30,7 +32,11 @@ export default function ReferenceResourceDetailPage() {
            <dt>Resource ID</dt>
            <dd>{resource.resourceId}</dd>
            <dt>Created</dt>
-            <dd>{resource.createdAtLabel ?? "표시 정보 없음"}</dd>
+            <dd>
+              {resource.createdAt
+                ? date(new Date(resource.createdAt))
+                : message("common.noDisplayValue")}
+            </dd>
          </dl>
        ) : (
          <p>요약 정보를 준비하고 있습니다.</p>
@@ -70,7 +70,7 @@ export function useReferenceFeature() {
          {
            resourceId: `optimistic:${command.name}`,
            title: command.name,
-            createdAtLabel: null,
+            createdAt: null,
            optimistic: true,
          },
        ];
@@ -1,3 +1,5 @@
+import { formatMessage } from "../i18n/index.js";
+
 /**
 * @param {{
 *   kind?: string,
@@ -18,32 +20,36 @@ export function BootErrorShell({
 }) {
  return (
    <main role="alert">
-      <h1>애플리케이션을 시작할 수 없습니다.</h1>
+      <h1>{formatMessage("ko-KR", "boot.failure.title")}</h1>
      <dl>
-        <dt>오류</dt>
+        <dt>{formatMessage("ko-KR", "boot.field.error")}</dt>
        <dd>{kind}</dd>
-        <dt>코드</dt>
+        <dt>{formatMessage("ko-KR", "boot.field.code")}</dt>
        <dd>{code}</dd>
        {buildId && (
          <>
-            <dt>빌드</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.build")}</dt>
            <dd>{buildId}</dd>
          </>
        )}
        {configSchemaVersion && (
          <>
-            <dt>설정 스키마</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.configSchema")}</dt>
            <dd>{configSchemaVersion}</dd>
          </>
        )}
        {releaseId && (
          <>
-            <dt>릴리스</dt>
+            <dt>{formatMessage("ko-KR", "boot.field.release")}</dt>
            <dd>{releaseId}</dd>
          </>
        )}
      </dl>
-      <p>지원 참조: {supportReference}</p>
+      <p>
+        {formatMessage("ko-KR", "boot.supportReference", {
+          reference: supportReference,
+        })}
+      </p>
    </main>
  );
 }
@@ -3,6 +3,7 @@ import {
  type ErrorInfo,
  type ReactNode,
 } from "react";
+import { useLocale } from "../i18n/index.js";

 type RecoveryResult =
  | Readonly<{ action: "reload-once"; releasePair: string }>
@@ -71,27 +72,44 @@ export class ChunkRecoveryBoundary extends Component<Props, State> {
    const { error, recovery, reason } = this.state;
    if (error && !isChunkLoadFailure(error)) throw error;
    if (error && recovery === "checking") {
-      return (
-        <section className="ui-page" aria-live="polite" aria-busy="true">
-          새 릴리스 정보를 확인하고 있습니다.
-        </section>
-      );
+      return <ChunkRecoverySurface recovery="checking" />;
    }
    if (error && recovery === "reload-requested") {
-      return (
-        <section className="ui-page" aria-live="polite">
-          새 버전으로 한 번만 전환합니다.
-        </section>
-      );
+      return <ChunkRecoverySurface recovery="reload-requested" />;
    }
    if (error && recovery === "support") {
-      return (
-        <section className="ui-page" role="alert" data-recovery-reason={reason}>
-          <h1>화면 자산을 복구하지 못했습니다.</h1>
-          <p>문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.</p>
-        </section>
-      );
+      return <ChunkRecoverySurface recovery="support" reason={reason} />;
    }
    return this.props.children;
  }
 }
+
+function ChunkRecoverySurface({
+  recovery,
+  reason,
+}: Readonly<{
+  recovery: Exclude<State["recovery"], "idle">;
+  reason?: string;
+}>) {
+  const { message } = useLocale();
+  if (recovery === "checking") {
+    return (
+      <section className="ui-page" aria-live="polite" aria-busy="true">
+        {message("chunk.checking")}
+      </section>
+    );
+  }
+  if (recovery === "reload-requested") {
+    return (
+      <section className="ui-page" aria-live="polite">
+        {message("chunk.reloadOnce")}
+      </section>
+    );
+  }
+  return (
+    <section className="ui-page" role="alert" data-recovery-reason={reason}>
+      <h1>{message("chunk.failure.title")}</h1>
+      <p>{message("chunk.failure.description")}</p>
+    </section>
+  );
+}
@@ -1,4 +1,5 @@
 import { Component } from "react";
+import { formatMessage } from "../i18n/index.js";

 /**
 * @typedef {{
@@ -57,9 +58,9 @@ export class RenderErrorBoundary extends Component {
      return (
        this.props.fallback ?? (
          <section role="alert">
-            <p>error.render_failure</p>
+            <p>{formatMessage("ko-KR", "error.render_failure")}</p>
            <button type="button" onClick={this.reset}>
-              retry
+              {formatMessage("ko-KR", "action.retry")}
            </button>
          </section>
        )
@@ -2,19 +2,22 @@ import { useId } from "react";

 import { errorMessage } from "./error-copy.js";
 import { Button } from "./ui/button.jsx";
+import { useLocale } from "../i18n/index.js";

 /** @param {{ label?: string }} props */
-export function LoadingSurface({ label = "불러오는 중" }) {
+export function LoadingSurface({ label }) {
+  const { message } = useLocale();
+  const accessibleLabel = label ?? message("async.loading");
  return (
    <section
      className="state-surface state-surface--loading"
      aria-busy="true"
-      aria-label={label}
+      aria-label={accessibleLabel}
      aria-live="polite"
      aria-atomic="true"
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <span className="visually-hidden">{label}</span>
+      <span className="visually-hidden">{accessibleLabel}</span>
    </section>
  );
 }
@@ -27,13 +30,14 @@ export function LoadingSurface({ label = "불러오는 중" }) {
 * }} props
 */
 export function EmptySurface({
-  title = "표시할 항목이 없습니다.",
+  title,
  description,
  action,
 }) {
+  const { message } = useLocale();
  return (
    <section className="ui-empty state-surface" aria-live="polite">
-      <h2>{title}</h2>
+      <h2>{title ?? message("async.empty")}</h2>
      {description ? <p>{description}</p> : null}
      {action}
    </section>
@@ -49,13 +53,14 @@ export function EmptySurface({
 * }} props
 */
 export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
+  const { locale, message } = useLocale();
  const messageId = useId();
  const actionLabels = Object.freeze({
-    retry: "다시 시도",
-    reauth: "로그인",
-    navigate: "안전한 화면으로 이동",
-    "reload-once": "한 번 새로고침",
-    "contact-support": "지원 정보 확인",
+    retry: message("action.retry"),
+    reauth: message("action.reauth"),
+    navigate: message("action.navigateSafe"),
+    "reload-once": message("action.reloadOnce"),
+    "contact-support": message("action.contactSupport"),
  });
  return (
    <section
@@ -64,7 +69,7 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
      aria-labelledby={messageId}
      data-message-key={userMessageKey}
    >
-      <h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
+      <h2 id={messageId}>{errorMessage(userMessageKey, locale)}</h2>
      {action !== "none" && onAction && (
        <Button onClick={onAction}>{actionLabels[action]}</Button>
      )}
@@ -88,6 +93,7 @@ export function AsyncSurface({
  onRetry,
  onResolveConflict,
 }) {
+  const { message } = useLocale();
  if (state.base === "initial-loading") return <LoadingSurface />;
  if (state.base === "empty") return <EmptySurface />;
  if (state.base === "terminal-error" && state.failure) {
@@ -104,12 +110,24 @@ export function AsyncSurface({
    <section aria-busy={state.overlay.refreshing || state.overlay.mutationPending}>
      {state.indicator ? (
        <div role="status" aria-live="polite">
-          <span>{state.indicator}</span>
+          <span>
+            {message(
+              state.indicator === "stale-degraded"
+                ? "async.staleDegraded"
+                : state.indicator === "mutation-conflict"
+                  ? "async.mutationConflict"
+                  : state.indicator === "mutation-pending"
+                    ? "async.mutationPending"
+                    : "async.refreshing",
+            )}
+          </span>
          {state.indicator === "stale-degraded" && onRetry ? (
-            <Button onClick={onRetry}>다시 시도</Button>
+            <Button onClick={onRetry}>{message("action.retry")}</Button>
          ) : null}
          {state.indicator === "mutation-conflict" && onResolveConflict ? (
-            <Button onClick={onResolveConflict}>충돌 해결</Button>
+            <Button onClick={onResolveConflict}>
+              {message("action.resolveConflict")}
+            </Button>
          ) : null}
        </div>
      ) : null}
@@ -1,26 +1,6 @@
-const ERROR_MESSAGES = Object.freeze({
-  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
-  "error.request_timeout": "요청 시간이 초과되었습니다.",
-  "error.auth_required": "계속하려면 로그인이 필요합니다.",
-  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
-  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
-  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
-  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
-  "error.server_failure": "요청을 완료하지 못했습니다.",
-  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
-  "error.build_mismatch": "현재 화면과 활성 빌드가 일치하지 않습니다.",
-  "error.config_mismatch": "런타임 설정 버전이 현재 화면과 일치하지 않습니다.",
-  "error.api_contract_mismatch": "API 계약 버전이 현재 화면과 일치하지 않습니다.",
-  "error.release_mismatch": "현재 화면과 활성 릴리스가 일치하지 않습니다.",
-  "error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.",
-  "error.render_failure": "화면을 표시하지 못했습니다.",
-  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
-});
+import { resolveMessage } from "../i18n/index.js";

-/** @param {string} messageKey */
-export function errorMessage(messageKey) {
-  const messages = /** @type {Readonly<Record<string, string>>} */ (
-    ERROR_MESSAGES
-  );
-  return messages[messageKey] ?? "요청을 완료하지 못했습니다.";
+/** @param {string} messageKey @param {string} [locale] */
+export function errorMessage(messageKey, locale = "ko-KR") {
+  return resolveMessage(locale, messageKey);
 }
@@ -1,4 +1,5 @@
 import { Button } from "./ui/button.jsx";
+import { useLocale } from "../i18n/index.js";

 /**
 * @param {{
@@ -30,12 +31,13 @@ function StateSurface({

 /** @param {{ onSignIn?: () => void }} props */
 export function AuthRequiredSurface({ onSignIn }) {
+  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="401 · 인증 필요"
-      title="로그인이 필요합니다."
-      description="세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다."
-      actionLabel="로그인 시작"
+      eyebrow={message("access.auth.eyebrow")}
+      title={message("access.auth.title")}
+      description={message("access.auth.description")}
+      actionLabel={message("action.signIn")}
      onAction={onSignIn}
    />
  );
@@ -43,12 +45,13 @@ export function AuthRequiredSurface({ onSignIn }) {

 /** @param {{ onNavigate?: () => void }} props */
 export function ForbiddenSurface({ onNavigate }) {
+  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="403 · 권한 없음"
-      title="접근할 수 없습니다."
-      description="권한을 확인하거나 접근 가능한 화면으로 이동하세요."
-      actionLabel="안전한 화면으로 이동"
+      eyebrow={message("access.forbidden.eyebrow")}
+      title={message("access.forbidden.title")}
+      description={message("access.forbidden.description")}
+      actionLabel={message("action.navigateSafe")}
      onAction={onNavigate}
      tone="warning"
    />
@@ -57,12 +60,13 @@ export function ForbiddenSurface({ onNavigate }) {

 /** @param {{ onNavigate?: () => void }} props */
 export function NotFoundSurface({ onNavigate }) {
+  const { message } = useLocale();
  return (
    <StateSurface
-      eyebrow="404 · 찾을 수 없음"
-      title="요청한 화면이 없습니다."
-      description="주소를 확인하거나 시작 화면으로 돌아가세요."
-      actionLabel="시작 화면으로 이동"
+      eyebrow={message("access.notFound.eyebrow")}
+      title={message("access.notFound.title")}
+      description={message("access.notFound.description")}
+      actionLabel={message("action.goHome")}
      onAction={onNavigate}
    />
  );
@@ -8,6 +8,7 @@ import {
 import { createPortal } from "react-dom";

 import { CloseIcon } from "../icons/semantic-icons.js";
+import { useLocale } from "../../i18n/index.js";

 export type ButtonVariant = "primary" | "secondary" | "danger" | "ghost";
 export type ButtonSize = "default" | "compact";
@@ -277,6 +278,7 @@ export function Alert({
  dismissLabel,
  onDismiss,
 }: AlertProps) {
+  const { message } = useLocale();
  return (
    <section
      className={`ui-alert ui-alert--${variant}`}
@@ -288,7 +290,9 @@ export function Alert({
      </div>
      {onDismiss ? (
        <IconButton
-          accessibleName={dismissLabel ?? `${title} 알림 닫기`}
+          accessibleName={
+            dismissLabel ?? message("action.alertCloseNamed", { title })
+          }
          className="ui-alert__dismiss"
          onClick={onDismiss}
          variant="ghost"
@@ -334,8 +338,10 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
    },
    forwardedRef,
  ) {
+    const { message } = useLocale();
    const dialogRef = useRef<HTMLDialogElement | null>(null);
    const previousFocusRef = useRef<HTMLElement | null>(null);
+    const focusRestoreGenerationRef = useRef(0);
    const titleId = useId();
    const descriptionId = useId();
    useImperativeHandle(forwardedRef, () => dialogRef.current!, []);
@@ -343,6 +349,8 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
    useEffect(() => {
      const dialog = dialogRef.current;
      if (!dialog) return;
+      const generation = focusRestoreGenerationRef.current + 1;
+      focusRestoreGenerationRef.current = generation;

      if (open) {
        previousFocusRef.current =
@@ -364,8 +372,21 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
        if (typeof dialog.close === "function") dialog.close();
        else dialog.removeAttribute("open");
      }
-      previousFocusRef.current?.focus();
+      const previousFocus = previousFocusRef.current;
      previousFocusRef.current = null;
+      const restoreFocus = () => {
+        if (
+          focusRestoreGenerationRef.current === generation &&
+          previousFocus?.isConnected
+        ) {
+          previousFocus.focus();
+        }
+      };
+      if (typeof globalThis.requestAnimationFrame === "function") {
+        const frame = globalThis.requestAnimationFrame(restoreFocus);
+        return () => globalThis.cancelAnimationFrame(frame);
+      }
+      queueMicrotask(restoreFocus);
    }, [open]);

    return (
@@ -395,7 +416,9 @@ export const Dialog = forwardRef<HTMLDialogElement, DialogProps>(
              {description ? <p id={descriptionId}>{description}</p> : null}
            </div>
            <IconButton
-              accessibleName={closeLabel ?? `${title} 닫기`}
+              accessibleName={
+                closeLabel ?? message("action.closeNamed", { title })
+              }
              className="ui-dialog__close"
              onClick={onClose}
              variant="ghost"
@@ -9,6 +9,7 @@ import {
 import { CloseIcon, SearchIcon } from "../icons/semantic-icons.js";
 import { Field, IconButton } from "./core.js";
 import type { TextFieldProps } from "./core.js";
+import { useLocale } from "../../i18n/index.js";

 type FieldCopy = Readonly<{
  id?: string;
@@ -41,6 +42,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
    },
    ref,
  ) {
+    const { message } = useLocale();
    const [uncontrolledValue, setUncontrolledValue] = useState(
      String(defaultValue ?? ""),
    );
@@ -80,7 +82,7 @@ export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
              <output className="ui-field__counter">
                {maxLengthMessage
                  ? maxLengthMessage(remaining)
-                  : `${remaining}자 남음`}
+                  : message("form.remaining", { count: remaining })}
              </output>
            ) : null}
          </>
@@ -1,5 +1,6 @@
 import { useId, useRef, useState } from "react";

+import { useLocale } from "../../i18n/index.js";
 import { NextIcon, PreviousIcon } from "../icons/semantic-icons.js";
 import { IconButton, LinkButton } from "./core.js";

@@ -62,6 +63,7 @@ export function Tabs({
  const selected = value ?? internalValue;
  const tabRefs = useRef<Array<HTMLButtonElement | null>>([]);
  const baseId = useId();
+  const { direction } = useLocale();

  function select(id: string) {
    if (value === undefined) setInternalValue(id);
@@ -98,10 +100,10 @@ export function Tabs({
            onKeyDown={(event) => {
              if (event.key === "ArrowRight") {
                event.preventDefault();
-                move(index, 1);
+                move(index, direction === "rtl" ? -1 : 1);
              } else if (event.key === "ArrowLeft") {
                event.preventDefault();
-                move(index, -1);
+                move(index, direction === "rtl" ? 1 : -1);
              } else if (
                activation === "manual" &&
                (event.key === "Enter" || event.key === " ")
@@ -156,6 +158,10 @@ export function Pagination({
  onChange(page: number): void;
 }>) {
  const pages = Array.from({ length: pageCount }, (_, index) => index + 1);
+  const { direction } = useLocale();
+  const PreviousDirectionalIcon =
+    direction === "rtl" ? NextIcon : PreviousIcon;
+  const NextDirectionalIcon = direction === "rtl" ? PreviousIcon : NextIcon;
  return (
    <nav aria-label={label} className="ui-pagination">
      <IconButton
@@ -164,7 +170,7 @@ export function Pagination({
        onClick={() => onChange(page - 1)}
        variant="secondary"
      >
-        <PreviousIcon />
+        <PreviousDirectionalIcon />
      </IconButton>
      {pages.map((candidate) => (
        <LinkButton
@@ -186,7 +192,7 @@ export function Pagination({
        onClick={() => onChange(page + 1)}
        variant="secondary"
      >
-        <NextIcon />
+        <NextDirectionalIcon />
      </IconButton>
    </nav>
  );
@@ -11,6 +11,7 @@ import {

 import { CloseIcon } from "../icons/semantic-icons.js";
 import { Button, Dialog, IconButton } from "./core.js";
+import { useLocale } from "../../i18n/index.js";

 export type DrawerProps = Readonly<{
  open: boolean;
@@ -343,9 +344,10 @@ function ToastRegion({
  toasts: readonly ToastEntry[];
  dismiss(id: string): void;
 }>) {
+  const { message } = useLocale();
  return (
    <section
-      aria-label="Notifications"
+      aria-label={message("toast.region")}
      aria-live="polite"
      className="ui-toast-region"
    >
@@ -363,6 +365,7 @@ function ToastItem({
  toast: ToastEntry;
  dismiss(id: string): void;
 }>) {
+  const { message } = useLocale();
  const [paused, setPaused] = useState(false);
  useEffect(() => {
    if (paused) return;
@@ -391,7 +394,7 @@ function ToastItem({
        {toast.description ? <p>{toast.description}</p> : null}
      </div>
      <IconButton
-        accessibleName={`${toast.title} 닫기`}
+        accessibleName={message("action.closeNamed", { title: toast.title })}
        onClick={() => dismiss(toast.id)}
        variant="ghost"
      >
@@ -1,6 +1,7 @@
 import { useId, type FormHTMLAttributes, type ReactNode } from "react";

 import { TextField } from "../components/ui/text-field.jsx";
+import { useLocale } from "../i18n/index.js";
 import type {
  FieldErrors,
  FieldName,
@@ -31,6 +32,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
  fieldId(name: FieldName<Values>): string;
  onFocusField?(name: FieldName<Values>): void;
 }>) {
+  const { message } = useLocale();
  const {
    fieldErrors,
    formErrors = [],
@@ -50,7 +52,7 @@ export function ErrorSummary<Values extends FormValues>(props: Readonly<{
      role="alert"
      aria-labelledby={headingId}
    >
-      <h2 id={headingId}>입력 내용을 확인해 주세요.</h2>
+      <h2 id={headingId}>{message("form.errorSummary")}</h2>
      {entries.length > 0 ? (
        <ul>
          {entries.map(([name, message]) => (
@@ -1,4 +1,8 @@
 import type { ApiFailure } from "../../contracts/errors.js";
+import {
+  formatMessage,
+  type ParameterlessMessageKey,
+} from "../i18n/index.js";

 export type FormValues = Readonly<Record<string, unknown>>;
 export type FieldName<Values extends FormValues> = Extract<keyof Values, string>;
@@ -23,24 +27,32 @@ export type MappedValidationFailure<Values extends FormValues> = Readonly<{
 }>;

 const VALIDATION_COPY = Object.freeze({
-  REQUIRED: "필수 입력값입니다.",
-  too_small: "입력값이 너무 짧습니다.",
-  too_big: "입력값이 너무 깁니다.",
-  invalid_type: "입력 형식을 확인해 주세요.",
-  invalid_format: "입력 형식을 확인해 주세요.",
-  invalid_value: "허용된 값을 선택해 주세요.",
+  REQUIRED: "form.validation.required",
+  too_small: "form.validation.tooSmall",
+  too_big: "form.validation.tooBig",
+  invalid_type: "form.validation.invalidType",
+  invalid_format: "form.validation.invalidFormat",
+  invalid_value: "form.validation.invalidValue",
 });

-export function validationMessage(code: string): string {
-  return (
+type MessageResolver = (key: ParameterlessMessageKey) => string;
+
+const defaultMessage: MessageResolver = (key) => formatMessage("ko-KR", key);
+
+export function validationMessage(
+  code: string,
+  message: MessageResolver = defaultMessage,
+): string {
+  return message(
    VALIDATION_COPY[code as keyof typeof VALIDATION_COPY] ??
-    "입력값을 확인해 주세요."
+      "form.validation.unknown",
  );
 }

 export function mapValidationFailureToFields<Values extends FormValues>(
  failure: ApiFailure,
  allowedFields: readonly FieldName<Values>[],
+  message: MessageResolver = defaultMessage,
 ): MappedValidationFailure<Values> {
  if (failure.kind !== "VALIDATION_REJECTED") {
    return Object.freeze({ fieldErrors: Object.freeze({}), formErrors: [] });
@@ -51,15 +63,15 @@ export function mapValidationFailureToFields<Values extends FormValues>(
  const issues = failure.validationIssues ?? [];

  if (issues.length === 0) {
-    formErrors.push("입력값을 다시 확인해 주세요.");
+    formErrors.push(message("form.validation.retry"));
  }
  for (const issue of issues) {
    const field = issue.path.split(".").at(0) ?? "";
    if (allowed.has(field)) {
      const name = field as FieldName<Values>;
-      fieldErrors[name] ??= validationMessage(issue.code);
+      fieldErrors[name] ??= validationMessage(issue.code, message);
    } else {
-      formErrors.push("서버가 확인하지 못한 입력 항목이 있습니다.");
+      formErrors.push(message("form.validation.unknownField"));
    }
  }
  return Object.freeze({
@@ -8,6 +8,10 @@ import {
  type FormEvent,
 } from "react";
 import type { ZodType, ZodIssue } from "zod";
+import {
+  useLocale,
+  type ParameterlessMessageKey,
+} from "../i18n/index.js";

 import {
  mapValidationFailureToFields,
@@ -37,6 +41,7 @@ export function useAppForm<
  Command,
  Output,
 >(options: AppFormOptions<Values, Command, Output>) {
+  const { message } = useLocale();
  const {
    schema,
    defaultValues,
@@ -142,13 +147,14 @@ export function useAppForm<
        const errors = issuesToFieldErrors<Values>(
          parsed.error.issues,
          allowedServerFields,
+          message,
        );
        setFieldErrors(errors);
        setFormErrors(
          parsed.error.issues.some(
            (issue) => !allowedServerFields.includes(issue.path[0] as FieldName<Values>),
          )
-            ? ["입력 구성을 다시 확인해 주세요."]
+            ? [message("form.validation.configuration")]
            : [],
        );
        setTouched(new Set(allowedServerFields));
@@ -178,6 +184,7 @@ export function useAppForm<
          const mapped = mapValidationFailureToFields<Values>(
            outcome.error,
            allowedServerFields,
+            message,
          );
          setFieldErrors(mapped.fieldErrors);
          setFormErrors(mapped.formErrors);
@@ -185,11 +192,11 @@ export function useAppForm<
          focusFirstError(mapped.fieldErrors);
        } else if (outcome.error.kind === "CONFLICT") {
          setFormErrors([
-            "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
+            message("form.conflict"),
          ]);
          setResult("conflict");
        } else {
-          setFormErrors(["저장하지 못했습니다. 잠시 후 다시 시도해 주세요."]);
+          setFormErrors([message("form.unavailable")]);
          setResult("unavailable");
        }
        return outcome;
@@ -203,6 +210,7 @@ export function useAppForm<
      defaultValues,
      focusFirstError,
      mapToCommand,
+      message,
      resetOnSuccess,
      schema,
      submit,
@@ -231,6 +239,7 @@ export function useAppForm<
 function issuesToFieldErrors<Values extends FormValues>(
  issues: readonly ZodIssue[],
  allowedFields: readonly FieldName<Values>[],
+  message: (key: ParameterlessMessageKey) => string,
 ): FieldErrors<Values> {
  const allowed = new Set<PropertyKey>(allowedFields);
  const errors: Partial<Record<FieldName<Values>, string>> = {};
@@ -238,7 +247,7 @@ function issuesToFieldErrors<Values extends FormValues>(
    const field = issue.path[0];
    if (!allowed.has(field)) continue;
    const name = field as FieldName<Values>;
-    errors[name] ??= validationMessage(issue.code);
+    errors[name] ??= validationMessage(issue.code, message);
  }
  return Object.freeze(errors);
 }
@@ -3,6 +3,7 @@ import { useBeforeUnload, useBlocker } from "react-router-dom";

 import { Button } from "../components/ui/button.jsx";
 import { Dialog } from "../components/ui/dialog.jsx";
+import { useLocale } from "../i18n/index.js";

 export function useDirtyNavigationGuard(when: boolean) {
  const blocker = useBlocker(when);
@@ -33,19 +34,20 @@ export function useDirtyNavigationGuard(when: boolean) {
 export function DirtyNavigationDialog(props: Readonly<{
  guard: ReturnType<typeof useDirtyNavigationGuard>;
 }>) {
+  const { message } = useLocale();
  return (
    <Dialog
      open={props.guard.blocked}
      onClose={props.guard.stay}
-      title="저장하지 않은 변경이 있습니다."
-      description="이 화면을 떠나면 입력한 내용이 사라집니다."
+      title={message("form.unsaved.title")}
+      description={message("form.unsaved.description")}
      actions={
        <>
          <Button variant="secondary" onClick={props.guard.stay}>
-            계속 작성
+            {message("action.continueEditing")}
          </Button>
          <Button variant="danger" onClick={props.guard.leave}>
-            변경 버리고 이동
+            {message("action.discardAndLeave")}
          </Button>
        </>
      }
@@ -0,0 +1,304 @@
+import { INSTALLED_MESSAGE_CATALOGS } from "../../features/installed-feature-messages.js";
+
+const PLATFORM_KO_MESSAGES = {
+  "common.unavailable": "요청한 문구를 표시할 수 없습니다.",
+  "common.processing": "처리 중…",
+  "common.appName": "Frontend Skeleton",
+  "common.noDisplayValue": "표시 정보 없음",
+  "action.retry": "다시 시도",
+  "action.reauth": "로그인",
+  "action.navigateSafe": "안전한 화면으로 이동",
+  "action.reloadOnce": "한 번 새로고침",
+  "action.contactSupport": "지원 정보 확인",
+  "action.resolveConflict": "충돌 해결",
+  "action.continueEditing": "계속 작성",
+  "action.discardAndLeave": "변경 버리고 이동",
+  "action.signIn": "로그인 시작",
+  "action.recoverSession": "세션 복구",
+  "action.signOut": "로그아웃",
+  "action.goHome": "홈으로 이동",
+  "action.closeNamed": "{title} 닫기",
+  "action.alertCloseNamed": "{title} 알림 닫기",
+  "shell.skipToContent": "본문으로 건너뛰기",
+  "shell.menu": "메뉴",
+  "shell.closeMenu": "메뉴 닫기",
+  "shell.sidebar": "사이드바",
+  "shell.primaryNavigation": "주요 탐색",
+  "shell.theme": "색상 테마",
+  "shell.theme.system": "시스템 테마",
+  "shell.theme.light": "라이트 테마",
+  "shell.theme.dark": "다크 테마",
+  "shell.locale": "언어",
+  "shell.locale.ko": "한국어",
+  "shell.locale.en": "English",
+  "shell.locale.pseudo": "Pseudo",
+  "shell.locale.rtl": "RTL smoke",
+  "shell.session.authenticated": "인증됨",
+  "shell.session.unauthenticated": "로그인 전",
+  "shell.session.recoveryPending": "복구 대기",
+  "shell.session.integrationFailed": "연동 필요",
+  "shell.session.actionFailed": "세션 작업을 완료하지 못했습니다.",
+  "route.APP_HOME.navigation": "홈",
+  "route.APP_HOME.title": "Clean Architecture Frontend",
+  "route.EXAMPLES_UI.navigation": "UI 구성요소",
+  "route.EXAMPLES_UI.title": "UI 구성요소",
+  "route.EXAMPLES_STATES.navigation": "화면 상태",
+  "route.EXAMPLES_STATES.title": "화면 상태",
+  "route.EXAMPLES_AUTH.navigation": "인증 연동",
+  "route.EXAMPLES_AUTH.title": "인증 연동",
+  "route.NOT_FOUND.navigation": "찾을 수 없음",
+  "route.NOT_FOUND.title": "페이지를 찾을 수 없습니다.",
+  "async.loading": "불러오는 중",
+  "async.empty": "표시할 항목이 없습니다.",
+  "async.refreshing": "최신 정보를 확인하고 있습니다.",
+  "async.staleDegraded": "기존 정보를 표시하고 있습니다.",
+  "async.mutationPending": "변경 사항을 저장하고 있습니다.",
+  "async.mutationConflict": "다른 변경과 충돌했습니다.",
+  "access.auth.eyebrow": "401 · 인증 필요",
+  "access.auth.title": "로그인이 필요합니다.",
+  "access.auth.description":
+    "세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다.",
+  "access.forbidden.eyebrow": "403 · 권한 없음",
+  "access.forbidden.title": "접근할 수 없습니다.",
+  "access.forbidden.description":
+    "권한을 확인하거나 접근 가능한 화면으로 이동하세요.",
+  "access.notFound.eyebrow": "404 · 찾을 수 없음",
+  "access.notFound.title": "요청한 화면이 없습니다.",
+  "access.notFound.description":
+    "주소를 확인하거나 시작 화면으로 돌아가세요.",
+  "route.loading": "화면을 준비하고 있습니다.",
+  "route.loadingNamed": "{title} 로딩 중",
+  "route.failure.title": "화면을 표시하지 못했습니다.",
+  "route.failure.description":
+    "잠시 후 다시 시도해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요.",
+  "route.invalid.title": "올바르지 않은 주소입니다.",
+  "route.invalid.description": "주소의 경로 또는 검색 조건을 확인해 주세요.",
+  "route.invalid.action": "안전한 탐색 링크를 사용해 주세요.",
+  "route.auth.integration.title": "로그인 연동이 필요합니다.",
+  "route.auth.integration.description":
+    "외부 인증 소유자가 연결되면 이 보호 라우트를 사용할 수 있습니다.",
+  "route.auth.recovering.title": "세션을 복구하고 있습니다.",
+  "route.auth.required.title": "세션이 필요합니다.",
+  "route.auth.recovering.description":
+    "기존 세션 확인을 계속하려면 복구를 실행하세요.",
+  "route.auth.required.description":
+    "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다.",
+  "route.documentTitle": "{title} · {appName}",
+  "chunk.checking": "새 릴리스 정보를 확인하고 있습니다.",
+  "chunk.reloadOnce": "새 버전으로 한 번만 전환합니다.",
+  "chunk.failure.title": "화면 자산을 복구하지 못했습니다.",
+  "chunk.failure.description":
+    "문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.",
+  "page.notFound.title": "페이지를 찾을 수 없습니다.",
+  "page.notFound.description":
+    "주소를 확인하거나 준비된 시작 화면으로 돌아가세요.",
+  "template.breadcrumb": "현재 위치",
+  "template.relatedInformation": "관련 정보",
+  "template.searchAndFilter": "검색과 필터",
+  "template.pagination": "페이지 탐색",
+  "template.summary": "요약 정보",
+  "template.dangerActions": "위험 작업",
+  "template.supportReference": "지원 참조: {reference}",
+  "form.errorSummary": "입력 내용을 확인해 주세요.",
+  "form.unsaved.title": "저장하지 않은 변경이 있습니다.",
+  "form.unsaved.description": "이 화면을 떠나면 입력한 내용이 사라집니다.",
+  "form.validation.required": "필수 입력값입니다.",
+  "form.validation.tooSmall": "입력값이 너무 짧습니다.",
+  "form.validation.tooBig": "입력값이 너무 깁니다.",
+  "form.validation.invalidType": "입력 형식을 확인해 주세요.",
+  "form.validation.invalidFormat": "입력 형식을 확인해 주세요.",
+  "form.validation.invalidValue": "허용된 값을 선택해 주세요.",
+  "form.validation.unknown": "입력값을 확인해 주세요.",
+  "form.validation.retry": "입력값을 다시 확인해 주세요.",
+  "form.validation.unknownField":
+    "서버가 확인하지 못한 입력 항목이 있습니다.",
+  "form.validation.configuration": "입력 구성을 다시 확인해 주세요.",
+  "form.conflict":
+    "다른 변경과 충돌했습니다. 입력은 유지되었으니 최신 상태를 확인해 주세요.",
+  "form.unavailable": "저장하지 못했습니다. 잠시 후 다시 시도해 주세요.",
+  "form.remaining": "{count}자 남음",
+  "toast.region": "알림",
+  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
+  "error.request_timeout": "요청 시간이 초과되었습니다.",
+  "error.auth_required": "계속하려면 로그인이 필요합니다.",
+  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
+  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
+  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
+  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
+  "error.server_failure": "요청을 완료하지 못했습니다.",
+  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
+  "error.build_mismatch": "현재 화면과 활성 빌드가 일치하지 않습니다.",
+  "error.config_mismatch": "런타임 설정 버전이 현재 화면과 일치하지 않습니다.",
+  "error.api_contract_mismatch": "API 계약 버전이 현재 화면과 일치하지 않습니다.",
+  "error.release_mismatch": "현재 화면과 활성 릴리스가 일치하지 않습니다.",
+  "error.asset_mismatch": "화면 자산 구성이 현재 릴리스와 일치하지 않습니다.",
+  "error.render_failure": "화면을 표시하지 못했습니다.",
+  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
+  "boot.failure.title": "애플리케이션을 시작할 수 없습니다.",
+  "boot.field.error": "오류",
+  "boot.field.code": "코드",
+  "boot.field.build": "빌드",
+  "boot.field.configSchema": "설정 스키마",
+  "boot.field.release": "릴리스",
+  "boot.supportReference": "지원 참조: {reference}",
+} as const;
+
+export const KO_MESSAGES = {
+  ...PLATFORM_KO_MESSAGES,
+  ...INSTALLED_MESSAGE_CATALOGS["ko-KR"],
+} as const;
+
+export type MessageKey = keyof typeof KO_MESSAGES;
+
+const PLATFORM_EN_MESSAGES = {
+  "common.unavailable": "This message is unavailable.",
+  "common.processing": "Processing…",
+  "common.appName": "Frontend Skeleton",
+  "common.noDisplayValue": "No display value",
+  "action.retry": "Try again",
+  "action.reauth": "Sign in",
+  "action.navigateSafe": "Go to an available page",
+  "action.reloadOnce": "Reload once",
+  "action.contactSupport": "View support information",
+  "action.resolveConflict": "Resolve conflict",
+  "action.continueEditing": "Continue editing",
+  "action.discardAndLeave": "Discard and leave",
+  "action.signIn": "Start sign-in",
+  "action.recoverSession": "Recover session",
+  "action.signOut": "Sign out",
+  "action.goHome": "Go home",
+  "action.closeNamed": "Close {title}",
+  "action.alertCloseNamed": "Dismiss {title} alert",
+  "shell.skipToContent": "Skip to content",
+  "shell.menu": "Menu",
+  "shell.closeMenu": "Close menu",
+  "shell.sidebar": "Sidebar",
+  "shell.primaryNavigation": "Primary navigation",
+  "shell.theme": "Color theme",
+  "shell.theme.system": "System theme",
+  "shell.theme.light": "Light theme",
+  "shell.theme.dark": "Dark theme",
+  "shell.locale": "Language",
+  "shell.locale.ko": "한국어",
+  "shell.locale.en": "English",
+  "shell.locale.pseudo": "Pseudo",
+  "shell.locale.rtl": "RTL smoke",
+  "shell.session.authenticated": "Authenticated",
+  "shell.session.unauthenticated": "Signed out",
+  "shell.session.recoveryPending": "Recovery pending",
+  "shell.session.integrationFailed": "Integration required",
+  "shell.session.actionFailed": "The session action could not be completed.",
+  "route.APP_HOME.navigation": "Home",
+  "route.APP_HOME.title": "Clean Architecture Frontend",
+  "route.EXAMPLES_UI.navigation": "UI components",
+  "route.EXAMPLES_UI.title": "UI components",
+  "route.EXAMPLES_STATES.navigation": "Screen states",
+  "route.EXAMPLES_STATES.title": "Screen states",
+  "route.EXAMPLES_AUTH.navigation": "Authentication",
+  "route.EXAMPLES_AUTH.title": "Authentication",
+  "route.NOT_FOUND.navigation": "Not found",
+  "route.NOT_FOUND.title": "Page not found",
+  "async.loading": "Loading",
+  "async.empty": "There are no items to display.",
+  "async.refreshing": "Checking for the latest information.",
+  "async.staleDegraded": "Showing previously loaded information.",
+  "async.mutationPending": "Saving changes.",
+  "async.mutationConflict": "The change conflicts with another update.",
+  "access.auth.eyebrow": "401 · Authentication required",
+  "access.auth.title": "Sign-in is required.",
+  "access.auth.description":
+    "Start a session to safely continue the previous task.",
+  "access.forbidden.eyebrow": "403 · Access denied",
+  "access.forbidden.title": "You cannot access this page.",
+  "access.forbidden.description":
+    "Check your permissions or go to an available page.",
+  "access.notFound.eyebrow": "404 · Not found",
+  "access.notFound.title": "The requested page does not exist.",
+  "access.notFound.description": "Check the address or return to the start page.",
+  "route.loading": "Preparing the page.",
+  "route.loadingNamed": "Loading {title}",
+  "route.failure.title": "The page could not be displayed.",
+  "route.failure.description":
+    "Try again shortly. If the problem continues, check the support reference.",
+  "route.invalid.title": "This address is invalid.",
+  "route.invalid.description": "Check the path and search parameters.",
+  "route.invalid.action": "Use a safe navigation link.",
+  "route.auth.integration.title": "Sign-in integration is required.",
+  "route.auth.integration.description":
+    "This protected route is available after an external authentication owner is connected.",
+  "route.auth.recovering.title": "Recovering the session.",
+  "route.auth.required.title": "A session is required.",
+  "route.auth.recovering.description":
+    "Run recovery to continue checking the existing session.",
+  "route.auth.required.description":
+    "This protected route demonstrates the authentication integration seam.",
+  "route.documentTitle": "{title} · {appName}",
+  "chunk.checking": "Checking the new release information.",
+  "chunk.reloadOnce": "Switching to the new version once.",
+  "chunk.failure.title": "The page assets could not be recovered.",
+  "chunk.failure.description":
+    "If the problem continues, check deployment status and support information.",
+  "page.notFound.title": "Page not found.",
+  "page.notFound.description": "Check the address or return to the start page.",
+  "template.breadcrumb": "Current location",
+  "template.relatedInformation": "Related information",
+  "template.searchAndFilter": "Search and filters",
+  "template.pagination": "Pagination",
+  "template.summary": "Summary information",
+  "template.dangerActions": "Dangerous actions",
+  "template.supportReference": "Support reference: {reference}",
+  "form.errorSummary": "Review the entered information.",
+  "form.unsaved.title": "You have unsaved changes.",
+  "form.unsaved.description":
+    "The entered information will be lost if you leave this page.",
+  "form.validation.required": "This field is required.",
+  "form.validation.tooSmall": "This value is too short.",
+  "form.validation.tooBig": "This value is too long.",
+  "form.validation.invalidType": "Check the input type.",
+  "form.validation.invalidFormat": "Check the input format.",
+  "form.validation.invalidValue": "Choose an allowed value.",
+  "form.validation.unknown": "Check the entered value.",
+  "form.validation.retry": "Review the entered values.",
+  "form.validation.unknownField":
+    "The server reported an unrecognized input field.",
+  "form.validation.configuration": "Review the input configuration.",
+  "form.conflict":
+    "Another update conflicts with this change. Your input has been preserved.",
+  "form.unavailable": "The change could not be saved. Try again shortly.",
+  "form.remaining": "{count} characters remaining",
+  "toast.region": "Notifications",
+  "error.network_unreachable": "The network is unavailable.",
+  "error.request_timeout": "The request timed out.",
+  "error.auth_required": "Sign in to continue.",
+  "error.auth_integration_failure": "Sign-in integration is unavailable.",
+  "error.forbidden": "You are not allowed to perform this action.",
+  "error.not_found": "The requested item could not be found.",
+  "error.rate_limited": "Too many requests were made. Try again shortly.",
+  "error.server_failure": "The request could not be completed.",
+  "error.chunk_load_failure": "The new page assets could not be loaded.",
+  "error.build_mismatch": "The active build does not match this page.",
+  "error.config_mismatch": "The runtime configuration does not match this page.",
+  "error.api_contract_mismatch": "The API contract does not match this page.",
+  "error.release_mismatch": "The active release does not match this page.",
+  "error.asset_mismatch": "The page assets do not match this release.",
+  "error.render_failure": "The page could not be displayed.",
+  "error.unknown_failure": "An unexpected problem occurred.",
+  "boot.failure.title": "The application could not start.",
+  "boot.field.error": "Error",
+  "boot.field.code": "Code",
+  "boot.field.build": "Build",
+  "boot.field.configSchema": "Configuration schema",
+  "boot.field.release": "Release",
+  "boot.supportReference": "Support reference: {reference}",
+} as const satisfies Record<keyof typeof PLATFORM_KO_MESSAGES, string>;
+
+export const EN_MESSAGES = {
+  ...PLATFORM_EN_MESSAGES,
+  ...INSTALLED_MESSAGE_CATALOGS["en-US"],
+} as const satisfies Record<MessageKey, string>;
+
+export const MESSAGE_CATALOGS = Object.freeze({
+  "ko-KR": KO_MESSAGES,
+  "en-US": EN_MESSAGES,
+  "ar-EG": EN_MESSAGES,
+});
@@ -0,0 +1,96 @@
+import { normalizeLocale, type SupportedLocale } from "./message-contract.js";
+
+const FORMAT_FALLBACK = "—";
+
+export type DateFormatStyle = "short" | "medium" | "long";
+
+export function formatDate(
+  locale: SupportedLocale,
+  value: Date | number,
+  options: Readonly<{
+    dateStyle?: DateFormatStyle;
+    timeZone?: string;
+  }> = {},
+): string {
+  try {
+    const date = value instanceof Date ? value : new Date(value);
+    if (Number.isNaN(date.getTime())) return FORMAT_FALLBACK;
+    return new Intl.DateTimeFormat(normalizeLocale(locale), {
+      dateStyle: options.dateStyle ?? "medium",
+      timeZone: options.timeZone ?? "UTC",
+    }).format(date);
+  } catch {
+    return FORMAT_FALLBACK;
+  }
+}
+
+export function formatNumber(
+  locale: SupportedLocale,
+  value: number,
+  options: Readonly<{
+    style?: "decimal" | "percent";
+    maximumFractionDigits?: number;
+  }> = {},
+): string {
+  try {
+    if (!Number.isFinite(value)) return FORMAT_FALLBACK;
+    return new Intl.NumberFormat(normalizeLocale(locale), options).format(value);
+  } catch {
+    return FORMAT_FALLBACK;
+  }
+}
+
+export function formatRelativeTime(
+  locale: SupportedLocale,
+  value: number,
+  unit: Intl.RelativeTimeFormatUnit,
+): string {
+  try {
+    if (!Number.isFinite(value)) return FORMAT_FALLBACK;
+    return new Intl.RelativeTimeFormat(normalizeLocale(locale), {
+      numeric: "auto",
+    }).format(value, unit);
+  } catch {
+    return FORMAT_FALLBACK;
+  }
+}
+
+export function formatList(
+  locale: SupportedLocale,
+  values: readonly string[],
+): string {
+  try {
+    return new Intl.ListFormat(normalizeLocale(locale), {
+      style: "long",
+      type: "conjunction",
+    }).format(values);
+  } catch {
+    return values.join(", ");
+  }
+}
+
+export function selectPlural(
+  locale: SupportedLocale,
+  value: number,
+  choices: Readonly<
+    Partial<Record<Intl.LDMLPluralRule, string>> & { other: string }
+  >,
+): string {
+  try {
+    if (!Number.isFinite(value)) return choices.other;
+    return choices[
+      new Intl.PluralRules(normalizeLocale(locale)).select(value)
+    ] ?? choices.other;
+  } catch {
+    return choices.other;
+  }
+}
+
+export function selectMessage(
+  value: string,
+  choices: Readonly<Record<string, string> & { other: string }>,
+): string {
+  return choices[value] ?? choices.other;
+}
+
+export { FORMAT_FALLBACK };
@@ -0,0 +1,29 @@
+export { LocaleProvider, useLocale } from "./locale-provider.js";
+export {
+  catalogKeys,
+  fallbackMessage,
+  formatMessage,
+  localeDirection,
+  MESSAGE_KEY_ALIASES,
+  messagePlaceholders,
+  normalizeLocale,
+  resolveMessage,
+  SUPPORTED_LOCALES,
+} from "./message-contract.js";
+export type {
+  MessageArguments,
+  MessageParameters,
+  ParameterlessMessageKey,
+  SupportedLocale,
+  TextDirection,
+} from "./message-contract.js";
+export type { MessageKey } from "./catalog.js";
+export {
+  FORMAT_FALLBACK,
+  formatDate,
+  formatList,
+  formatNumber,
+  formatRelativeTime,
+  selectMessage,
+  selectPlural,
+} from "./formatters.js";
@@ -0,0 +1,118 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from "react";
+
+import {
+  formatDate,
+  formatList,
+  formatNumber,
+  formatRelativeTime,
+  selectMessage,
+  selectPlural,
+} from "./formatters.js";
+import {
+  formatMessage,
+  localeDirection,
+  normalizeLocale,
+  resolveMessage,
+  type MessageArguments,
+  type SupportedLocale,
+  type TextDirection,
+} from "./message-contract.js";
+import type { MessageKey } from "./catalog.js";
+
+type LocaleContextValue = Readonly<{
+  locale: SupportedLocale;
+  direction: TextDirection;
+  setLocale(locale: SupportedLocale): void;
+  message<Key extends MessageKey>(
+    key: Key,
+    ...args: MessageArguments<Key>
+  ): string;
+  resolve(key: string): string;
+  date(
+    value: Date | number,
+    options?: Parameters<typeof formatDate>[2],
+  ): string;
+  number(value: number, options?: Parameters<typeof formatNumber>[2]): string;
+  relativeTime(
+    value: number,
+    unit: Intl.RelativeTimeFormatUnit,
+  ): string;
+  list(values: readonly string[]): string;
+  plural(
+    value: number,
+    choices: Parameters<typeof selectPlural>[2],
+  ): string;
+  select(
+    value: string,
+    choices: Readonly<Record<string, string> & { other: string }>,
+  ): string;
+}>;
+
+const DEFAULT_LOCALE = "ko-KR" as const;
+const DEFAULT_CONTEXT: LocaleContextValue = Object.freeze({
+  locale: DEFAULT_LOCALE,
+  direction: "ltr",
+  setLocale() {},
+  message: (key, ...args) => formatMessage(DEFAULT_LOCALE, key, ...args),
+  resolve: (key) => resolveMessage(DEFAULT_LOCALE, key),
+  date: (value, options) => formatDate(DEFAULT_LOCALE, value, options),
+  number: (value, options) => formatNumber(DEFAULT_LOCALE, value, options),
+  relativeTime: (value, unit) =>
+    formatRelativeTime(DEFAULT_LOCALE, value, unit),
+  list: (values) => formatList(DEFAULT_LOCALE, values),
+  plural: (value, choices) => selectPlural(DEFAULT_LOCALE, value, choices),
+  select: (value, choices) => selectMessage(value, choices),
+});
+const LocaleContext = createContext<LocaleContextValue>(DEFAULT_CONTEXT);
+
+export function LocaleProvider({
+  children,
+  initialLocale = "ko-KR",
+}: Readonly<{
+  children: React.ReactNode;
+  initialLocale?: SupportedLocale;
+}>) {
+  const [locale, setLocaleState] = useState<SupportedLocale>(() =>
+    normalizeLocale(initialLocale),
+  );
+  const direction = localeDirection(locale);
+
+  useEffect(() => {
+    document.documentElement.lang = locale;
+    document.documentElement.dir = direction;
+  }, [direction, locale]);
+
+  const value = useMemo<LocaleContextValue>(
+    () => ({
+      locale,
+      direction,
+      setLocale: setLocaleState,
+      message: (key, ...args) => formatMessage(locale, key, ...args),
+      resolve: (key) => resolveMessage(locale, key),
+      date: (dateValue, options) => formatDate(locale, dateValue, options),
+      number: (numberValue, options) =>
+        formatNumber(locale, numberValue, options),
+      relativeTime: (relativeValue, unit) =>
+        formatRelativeTime(locale, relativeValue, unit),
+      list: (values) => formatList(locale, values),
+      plural: (pluralValue, choices) =>
+        selectPlural(locale, pluralValue, choices),
+      select: (selectValue, choices) => selectMessage(selectValue, choices),
+    }),
+    [direction, locale],
+  );
+
+  return (
+    <LocaleContext.Provider value={value}>{children}</LocaleContext.Provider>
+  );
+}
+
+export function useLocale(): LocaleContextValue {
+  return useContext(LocaleContext);
+}
@@ -0,0 +1,135 @@
+import {
+  EN_MESSAGES,
+  KO_MESSAGES,
+  MESSAGE_CATALOGS,
+  type MessageKey,
+} from "./catalog.js";
+
+export const SUPPORTED_LOCALES = Object.freeze([
+  "ko-KR",
+  "en-US",
+  "en-XA",
+  "ar-EG",
+] as const);
+export type SupportedLocale = (typeof SUPPORTED_LOCALES)[number];
+export type TextDirection = "ltr" | "rtl";
+
+export type MessageParameters = Readonly<{
+  "action.closeNamed": { title: string };
+  "action.alertCloseNamed": { title: string };
+  "route.loadingNamed": { title: string };
+  "route.documentTitle": { title: string; appName: string };
+  "template.supportReference": { reference: string };
+  "form.remaining": { count: number };
+  "boot.supportReference": { reference: string };
+}>;
+export type ParameterlessMessageKey = Exclude<
+  MessageKey,
+  keyof MessageParameters
+>;
+
+export type MessageArguments<Key extends MessageKey> =
+  Key extends keyof MessageParameters
+    ? [parameters: MessageParameters[Key]]
+    : [parameters?: never];
+
+const PLACEHOLDER_PATTERN = /\{([a-zA-Z][a-zA-Z0-9]*)\}/g;
+const FALLBACK_LOCALE = "ko-KR" as const;
+export const MESSAGE_KEY_ALIASES = Object.freeze({
+  "action.login": "action.reauth",
+  "async.pending": "common.processing",
+} as const satisfies Readonly<Record<string, MessageKey>>);
+
+export function normalizeLocale(locale: string): SupportedLocale {
+  if ((SUPPORTED_LOCALES as readonly string[]).includes(locale)) {
+    return locale as SupportedLocale;
+  }
+  const language = locale.split("-")[0]?.toLowerCase();
+  if (language === "ko") return "ko-KR";
+  if (language === "ar") return "ar-EG";
+  if (language === "en") return "en-US";
+  return FALLBACK_LOCALE;
+}
+
+export function localeDirection(locale: SupportedLocale): TextDirection {
+  return locale === "ar-EG" ? "rtl" : "ltr";
+}
+
+export function messagePlaceholders(template: string): readonly string[] {
+  return Object.freeze(
+    [...template.matchAll(PLACEHOLDER_PATTERN)].map((match) => match[1] ?? ""),
+  );
+}
+
+export function resolveMessage(
+  locale: string,
+  key: string,
+  parameters?: Readonly<Record<string, string | number>>,
+): string {
+  const normalized = normalizeLocale(locale);
+  const sourceLocale: keyof typeof MESSAGE_CATALOGS =
+    normalized === "en-XA" ? "en-US" : normalized;
+  const catalog =
+    MESSAGE_CATALOGS[sourceLocale] ??
+    MESSAGE_CATALOGS[FALLBACK_LOCALE];
+  const fallback = KO_MESSAGES["common.unavailable"];
+  const canonicalKey =
+    MESSAGE_KEY_ALIASES[key as keyof typeof MESSAGE_KEY_ALIASES] ?? key;
+  const template = catalog[canonicalKey as MessageKey] ?? fallback;
+  const placeholders = messagePlaceholders(template);
+  if (
+    placeholders.some(
+      (placeholder) =>
+        parameters?.[placeholder] === undefined ||
+        parameters?.[placeholder] === null,
+    )
+  ) {
+    return fallback;
+  }
+  const formatted = template.replace(
+    PLACEHOLDER_PATTERN,
+    (_, placeholder: string) => String(parameters?.[placeholder] ?? ""),
+  );
+  return normalized === "en-XA" ? pseudoLocalize(formatted) : formatted;
+}
+
+export function formatMessage<Key extends MessageKey>(
+  locale: string,
+  key: Key,
+  ...args: MessageArguments<Key>
+): string {
+  return resolveMessage(
+    locale,
+    key,
+    args[0] as Readonly<Record<string, string | number>> | undefined,
+  );
+}
+
+function pseudoLocalize(value: string): string {
+  const expanded = value.replace(/[A-Za-z]/g, (character) => {
+    const replacements: Readonly<Record<string, string>> = {
+      a: "á",
+      e: "é",
+      i: "í",
+      o: "ó",
+      u: "ú",
+      A: "Á",
+      E: "É",
+      I: "Í",
+      O: "Ó",
+      U: "Ú",
+    };
+    return replacements[character] ?? character;
+  });
+  return `［${expanded} ···］`;
+}
+
+export function catalogKeys(
+  locale: "ko-KR" | "en-US" | "ar-EG",
+): MessageKey[] {
+  return Object.keys(MESSAGE_CATALOGS[locale]).sort() as MessageKey[];
+}
+
+export function fallbackMessage() {
+  return EN_MESSAGES["common.unavailable"];
+}
@@ -12,20 +12,22 @@ import {
  MenuIcon,
  Select,
 } from "../design-system/index.js";
+import { useLocale } from "../i18n/index.js";
 import { useSession } from "../providers/session-provider.jsx";
 import { useTheme } from "../providers/theme-provider.jsx";

-const SESSION_LABELS = Object.freeze({
-  authenticated: "인증됨",
-  unauthenticated: "로그인 전",
-  "recovery-pending": "복구 대기",
-  "integration-failed": "연동 필요",
+const SESSION_MESSAGE_KEYS = Object.freeze({
+  authenticated: "shell.session.authenticated",
+  unauthenticated: "shell.session.unauthenticated",
+  "recovery-pending": "shell.session.recoveryPending",
+  "integration-failed": "shell.session.integrationFailed",
 });

 export function AppShell() {
  const location = useLocation();
  const { sessionState, beginSignIn, signOut, recover } = useSession();
  const { preference, setPreference } = useTheme();
+  const { locale, setLocale, message } = useLocale();
  const [navigationOpen, setNavigationOpen] = useState(false);
  const [sessionActionPending, setSessionActionPending] = useState(false);
  const [sessionActionFailed, setSessionActionFailed] = useState(false);
@@ -56,20 +58,20 @@ export function AppShell() {

  const sessionActionLabel =
    sessionState === "authenticated"
-      ? "로그아웃"
+      ? message("action.signOut")
      : sessionState === "recovery-pending"
-        ? "세션 복구"
-        : "로그인";
+        ? message("action.recoverSession")
+        : message("action.reauth");
  const integrationAvailable = sessionState !== "integration-failed";

  return (
    <div className="app-shell">
      <a className="skip-link" href="#main-content">
-        본문으로 건너뛰기
+        {message("shell.skipToContent")}
      </a>
      <header className="app-shell__header">
        <IconButton
-          accessibleName="메뉴"
+          accessibleName={message("shell.menu")}
          className="app-shell__menu-button"
          aria-controls="mobile-primary-navigation"
          aria-expanded={navigationOpen}
@@ -79,17 +81,17 @@ export function AppShell() {
          <MenuIcon />
        </IconButton>
        <NavLink className="app-shell__brand" to={routePath("APP_HOME")}>
-          Frontend Skeleton
+          {message("common.appName")}
        </NavLink>
        <div className="app-shell__session">
          <Select
            className="theme-selector"
            id="theme-preference"
-            label="색상 테마"
+            label={message("shell.theme")}
            options={[
-              { value: "system", label: "시스템 테마" },
-              { value: "light", label: "라이트 테마" },
-              { value: "dark", label: "다크 테마" },
+              { value: "system", label: message("shell.theme.system") },
+              { value: "light", label: message("shell.theme.light") },
+              { value: "dark", label: message("shell.theme.dark") },
            ]}
            value={preference}
            onChange={(event) =>
@@ -100,8 +102,27 @@ export function AppShell() {
              )
            }
          />
+          <Select
+            className="locale-selector"
+            id="locale-preference"
+            label={message("shell.locale")}
+            options={[
+              { value: "ko-KR", label: message("shell.locale.ko") },
+              { value: "en-US", label: message("shell.locale.en") },
+              { value: "en-XA", label: message("shell.locale.pseudo") },
+              { value: "ar-EG", label: message("shell.locale.rtl") },
+            ]}
+            value={locale}
+            onChange={(event) =>
+              setLocale(
+                /** @type {import("../i18n/index.js").SupportedLocale} */ (
+                  event.currentTarget.value
+                ),
+              )
+            }
+          />
          <span className="session-status" data-state={sessionState}>
-            {SESSION_LABELS[sessionState]}
+            {message(SESSION_MESSAGE_KEYS[sessionState])}
          </span>
          {integrationAvailable ? (
            <Button
@@ -109,24 +130,29 @@ export function AppShell() {
              onClick={() => void runSessionAction()}
              size="compact"
            >
-              {sessionActionPending ? "처리 중…" : sessionActionLabel}
+              {sessionActionPending
+                ? message("common.processing")
+                : sessionActionLabel}
            </Button>
          ) : null}
        </div>
        {sessionActionFailed ? (
          <p className="app-shell__session-error" role="alert">
-            세션 작업을 완료하지 못했습니다.
+            {message("shell.session.actionFailed")}
          </p>
        ) : null}
      </header>
-      <aside className="app-shell__sidebar" aria-label="사이드바">
+      <aside
+        className="app-shell__sidebar"
+        aria-label={message("shell.sidebar")}
+      >
        <PrimaryNavigation id="primary-navigation" />
      </aside>
      <Drawer
-        closeLabel="메뉴 닫기"
+        closeLabel={message("shell.closeMenu")}
        onClose={() => setNavigationOpen(false)}
        open={navigationOpen}
-        title="메뉴"
+        title={message("shell.menu")}
      >
        <PrimaryNavigation id="mobile-primary-navigation" />
      </Drawer>
@@ -141,8 +167,9 @@ export function AppShell() {
 * @param {{ id: string }} props
 */
 function PrimaryNavigation({ id }) {
+  const { resolve, message } = useLocale();
  return (
-    <nav id={id} aria-label="주요 탐색">
+    <nav id={id} aria-label={message("shell.primaryNavigation")}>
      <ul className="app-navigation">
        {NAVIGATION_ROUTES.map((definition) => (
          <li key={definition.routeId}>
@@ -153,7 +180,7 @@ function PrimaryNavigation({ id }) {
              end={definition.path === "/"}
              to={definition.path}
            >
-              {definition.navigationLabel}
+              {resolve(`route.${definition.routeId}.navigation`)}
            </NavLink>
          </li>
        ))}
@@ -2,17 +2,19 @@ import { Link } from "react-router-dom";

 import { routePath } from "../../features/installed-feature-contracts.js";
 import { PageHeader } from "../design-system/index.js";
+import { useLocale } from "../i18n/index.js";

 export default function NotFoundPage() {
+  const { message } = useLocale();
  return (
    <section className="ui-page">
      <PageHeader
-        title="페이지를 찾을 수 없습니다."
-        description="주소를 확인하거나 준비된 시작 화면으로 돌아가세요."
+        title={message("page.notFound.title")}
+        description={message("page.notFound.description")}
      />
      <div>
        <Link className="ui-button" to={routePath("APP_HOME")}>
-          홈으로 이동
+          {message("action.goHome")}
        </Link>
      </div>
    </section>
@@ -28,7 +28,8 @@ import {
  RouteBoundary,
 } from "../boundaries/render-error-boundary.jsx";
 import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.js";
-import { PageHeader } from "../design-system/index.js";
+import { Button, PageHeader } from "../design-system/index.js";
+import { LocaleProvider, useLocale } from "../i18n/index.js";
 import { AppShell } from "../layouts/app-shell.jsx";
 import { useApplication } from "../providers/application-provider.js";
 import { SessionProvider, useSession } from "../providers/session-provider.jsx";
@@ -54,6 +55,8 @@ export function useRouteInput(): ParsedRouteInput {
 }

 function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
+  const { message, resolve } = useLocale();
+  const title = resolve(`route.${definition.routeId}.title`);
  return (
    <section
      className="ui-page route-loading"
@@ -62,8 +65,10 @@ function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
      data-surface={definition.loadingSurface}
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <p>화면을 준비하고 있습니다.</p>
-      <span className="visually-hidden">{definition.title} 로딩 중</span>
+      <p>{message("route.loading")}</p>
+      <span className="visually-hidden">
+        {message("route.loadingNamed", { title })}
+      </span>
    </section>
  );
 }
@@ -73,35 +78,48 @@ function RouteFailureSurface({
 }: {
  definition?: RouteDefinition;
 }) {
+  const { message } = useLocale();
  return (
    <section
      className="ui-page"
      data-surface={definition?.errorSurface ?? "route-boundary"}
    >
      <PageHeader
-        title="화면을 표시하지 못했습니다."
-        description="잠시 후 다시 시도해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
+        title={message("route.failure.title")}
+        description={message("route.failure.description")}
      />
    </section>
  );
 }

 function InvalidRouteSurface({ code }: { code: string }) {
+  const { message } = useLocale();
  return (
    <section className="ui-page" data-surface="invalid-route">
      <PageHeader
-        title="올바르지 않은 주소입니다."
-        description="주소의 경로 또는 검색 조건을 확인해 주세요."
+        title={message("route.invalid.title")}
+        description={message("route.invalid.description")}
      />
-      <p data-route-error={code}>안전한 탐색 링크를 사용해 주세요.</p>
+      <p data-route-error={code}>{message("route.invalid.action")}</p>
    </section>
  );
 }

-function RouteLifecycle({ definition }: { definition: RouteDefinition }) {
+function RouteLifecycle({
+  definition,
+  buildId,
+}: {
+  definition: RouteDefinition;
+  buildId: string;
+}) {
  const location = useLocation();
+  const { message, resolve } = useLocale();
+  const { diagnostics } = useApplication();
  useEffect(() => {
-    document.title = `${definition.title} · Frontend Skeleton`;
+    document.title = message("route.documentTitle", {
+      title: resolve(`route.${definition.routeId}.title`),
+      appName: message("common.appName"),
+    });
    const main = document.getElementById("main-content");
    main?.focus({ preventScroll: true });
    try {
@@ -111,7 +129,19 @@ function RouteLifecycle({ definition }: { definition: RouteDefinition }) {
    } catch {
      // Non-browser test hosts may not implement scrolling.
    }
-  }, [definition, location.key, location.pathname]);
+    diagnostics.reportRouteChanged({
+      routeId: definition.routeId,
+      buildId,
+    });
+  }, [
+    buildId,
+    definition,
+    diagnostics,
+    location.key,
+    location.pathname,
+    message,
+    resolve,
+  ]);
  return null;
 }

@@ -146,6 +176,7 @@ function ProtectedRoute({
 }) {
  const location = useLocation();
  const { sessionState, beginSignIn, recover } = useSession();
+  const { message } = useLocale();
  const [pending, setPending] = useState(false);
  const [failed, setFailed] = useState(false);
  const decision = decideRouteAccess(routeId, sessionState);
@@ -173,8 +204,8 @@ function ProtectedRoute({
    return (
      <section className="ui-page" data-surface="auth-integration-required">
        <PageHeader
-          title="로그인 연동이 필요합니다."
-          description="외부 인증 소유자가 연결되면 이 보호 라우트를 사용할 수 있습니다."
+          title={message("route.auth.integration.title")}
+          description={message("route.auth.integration.description")}
        />
      </section>
    );
@@ -183,24 +214,30 @@ function ProtectedRoute({
  return (
    <section className="ui-page" data-surface="authentication-required">
      <PageHeader
-        title={recovering ? "세션을 복구하고 있습니다." : "세션이 필요합니다."}
+        title={
+          recovering
+            ? message("route.auth.recovering.title")
+            : message("route.auth.required.title")
+        }
        description={
          recovering
-            ? "기존 세션 확인을 계속하려면 복구를 실행하세요."
-            : "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."
+            ? message("route.auth.recovering.description")
+            : message("route.auth.required.description")
        }
      />
-      <button
-        className="ui-button"
-        type="button"
+      <Button
        disabled={pending}
        onClick={() => void continueSession()}
      >
-        {pending ? "처리 중…" : recovering ? "세션 복구" : "로그인 시작"}
-      </button>
+        {pending
+          ? message("common.processing")
+          : recovering
+            ? message("action.recoverSession")
+            : message("action.signIn")}
+      </Button>
      {failed ? (
        <p className="ui-terminal-error" role="alert">
-          세션 작업을 완료하지 못했습니다.
+          {message("shell.session.actionFailed")}
        </p>
      ) : null}
    </section>
@@ -226,7 +263,7 @@ function RegisteredRoute({
  const content = (
    <RouteInputContext.Provider value={parsed.data}>
      <CanonicalRouteRedirect input={parsed.data} />
-      <RouteLifecycle definition={definition} />
+      <RouteLifecycle definition={definition} buildId={buildId} />
      <Suspense fallback={<RouteLoadingSurface definition={definition} />}>
        <ChunkRecoveryBoundary
          chunkId={definition.chunkId}
@@ -300,10 +337,12 @@ export function AppRouter({
    [basename, buildId],
  );
  return (
-    <ThemeProvider>
-      <SessionProvider>
-        <RouterProvider router={router} />
-      </SessionProvider>
-    </ThemeProvider>
+    <LocaleProvider>
+      <ThemeProvider>
+        <SessionProvider>
+          <RouterProvider router={router} />
+        </SessionProvider>
+      </ThemeProvider>
+    </LocaleProvider>
  );
 }
@@ -131,11 +131,13 @@
    margin-inline-start: auto;
  }

-  .theme-selector {
+  .theme-selector,
+  .locale-selector {
    display: block;
  }

-  .theme-selector .ui-field__label {
+  .theme-selector .ui-field__label,
+  .locale-selector .ui-field__label {
    position: absolute;
    width: 1px;
    height: 1px;
@@ -147,13 +149,18 @@
    border: 0;
  }

-  .theme-selector .ui-field__input {
+  .theme-selector .ui-field__input,
+  .locale-selector .ui-field__input {
    min-height: var(--size-control-sm);
    max-width: 8.5rem;
    padding: 0.35rem 2rem 0.35rem 0.65rem;
    cursor: pointer;
  }

+  .locale-selector .ui-field__input {
+    max-width: 7rem;
+  }
+
  .app-shell__session-error {
    position: absolute;
    top: calc(100% + 0.25rem);
@@ -1340,6 +1347,10 @@
    display: none;
  }

+  .app-shell__session .theme-selector {
+    display: none;
+  }
+
  .app-shell__brand {
    display: none;
  }
@@ -2,6 +2,7 @@ import type { ReactNode } from "react";

 import { PageHeader } from "../components/page-header.jsx";
 import { Button } from "../components/ui/button.jsx";
+import { useLocale } from "../i18n/index.js";

 export type PageHeading = Readonly<{
  title: string;
@@ -36,10 +37,14 @@ export type PageTemplateSlots = Readonly<{
 }>;

 export function StandardPage(props: PageTemplateSlots) {
+  const { message } = useLocale();
  return (
    <article className="ui-page page-template page-template--standard">
      {props.breadcrumb ? (
-        <nav className="page-template__breadcrumb" aria-label="현재 위치">
+        <nav
+          className="page-template__breadcrumb"
+          aria-label={message("template.breadcrumb")}
+        >
          {props.breadcrumb}
        </nav>
      ) : null}
@@ -64,7 +69,10 @@ export function StandardPage(props: PageTemplateSlots) {
      >
        <div className="page-template__content">{props.children}</div>
        {props.aside ? (
-          <aside className="page-template__aside" aria-label="관련 정보">
+          <aside
+            className="page-template__aside"
+            aria-label={message("template.relatedInformation")}
+          >
            {props.aside}
          </aside>
        ) : null}
@@ -83,6 +91,7 @@ export function CollectionPage(
      pagination?: ReactNode;
    }>,
 ) {
+  const { message } = useLocale();
  return (
    <StandardPage
      {...props}
@@ -92,7 +101,7 @@ export function CollectionPage(
          {props.toolbar ? (
            <section
              className="collection-page__toolbar"
-              aria-label="검색과 필터"
+              aria-label={message("template.searchAndFilter")}
            >
              {props.toolbar}
            </section>
@@ -117,7 +126,10 @@ export function CollectionPage(
    >
      <div className="collection-page__results">{props.children}</div>
      {props.pagination ? (
-        <nav className="collection-page__pagination" aria-label="페이지 탐색">
+        <nav
+          className="collection-page__pagination"
+          aria-label={message("template.pagination")}
+        >
          {props.pagination}
        </nav>
      ) : null}
@@ -132,16 +144,23 @@ export function DetailPage(
      destructiveAction?: ReactNode;
    }>,
 ) {
+  const { message } = useLocale();
  return (
    <StandardPage {...props}>
      {props.metadata ? (
-        <section className="detail-page__metadata" aria-label="요약 정보">
+        <section
+          className="detail-page__metadata"
+          aria-label={message("template.summary")}
+        >
          {props.metadata}
        </section>
      ) : null}
      <div className="detail-page__sections">{props.children}</div>
      {props.destructiveAction ? (
-        <section className="detail-page__danger" aria-label="위험 작업">
+        <section
+          className="detail-page__danger"
+          aria-label={message("template.dangerActions")}
+        >
          {props.destructiveAction}
        </section>
      ) : null}
@@ -190,6 +209,7 @@ export function StatusPage(
    supportReference?: string;
  }>,
 ) {
+  const { message } = useLocale();
  return (
    <section
      className={`ui-page page-template status-page status-page--${props.variant}`}
@@ -208,7 +228,9 @@ export function StatusPage(
      ) : null}
      {props.supportReference ? (
        <p className="status-page__support">
-          지원 참조: <code>{props.supportReference}</code>
+          {message("template.supportReference", {
+            reference: props.supportReference,
+          })}
        </p>
      ) : null}
    </section>
@@ -50,7 +50,9 @@ describe("async UI state matrix", () => {
    render(<AsyncSurface state={state}>existing content</AsyncSurface>);

    expect(screen.getByText("existing content")).toBeVisible();
-    expect(screen.getByRole("status")).toHaveTextContent("refreshing");
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "최신 정보를 확인하고 있습니다.",
+    );
  });

  it("connects stale retry and conflict resolution to real callbacks", async () => {
@@ -60,7 +60,9 @@ describe("chunk recovery boundary classification", () => {
      </FeatureBoundary>,
    );

-    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "화면을 표시하지 못했습니다.",
+    );
    expect(recover).not.toHaveBeenCalled();
  });
 });
@@ -189,7 +189,7 @@ describe("design-system platform interactions", () => {
    await user.click(screen.getByRole("button", { name: "중복" }));
    expect(screen.getByText("×2")).toBeVisible();
    await user.click(screen.getByRole("button", { name: "다섯 개" }));
-    const region = screen.getByRole("region", { name: "Notifications" });
+    const region = screen.getByRole("region", { name: "알림" });
    expect(within(region).getAllByRole("article")).toHaveLength(3);
    expect(within(region).queryByText("알림 0")).not.toBeInTheDocument();
    expect(within(region).getByText("알림 4")).toBeVisible();
@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it } from "vitest";
+
+import {
+  Button,
+  Drawer,
+  Pagination,
+  Tabs,
+} from "../../src/presentation/design-system/index.js";
+import {
+  LocaleProvider,
+  useLocale,
+  type SupportedLocale,
+} from "../../src/presentation/i18n/index.js";
+
+function LocaleHarness() {
+  const { direction, locale, message, setLocale } = useLocale();
+  const [drawerOpen, setDrawerOpen] = useState(false);
+  return (
+    <>
+      <label htmlFor="test-locale">{message("shell.locale")}</label>
+      <select
+        id="test-locale"
+        onChange={(event) =>
+          setLocale(event.currentTarget.value as SupportedLocale)
+        }
+        value={locale}
+      >
+        <option value="ko-KR">한국어</option>
+        <option value="en-US">English</option>
+        <option value="ar-EG">RTL</option>
+      </select>
+      <output>{`${locale}:${direction}`}</output>
+      <Button onClick={() => setDrawerOpen(true)}>
+        {message("shell.menu")}
+      </Button>
+      <Drawer
+        closeLabel={message("shell.closeMenu")}
+        onClose={() => setDrawerOpen(false)}
+        open={drawerOpen}
+        title={message("shell.menu")}
+      >
+        content
+      </Drawer>
+    </>
+  );
+}
+
+describe("locale provider runtime", () => {
+  it("switches copy and synchronizes the document language and direction", async () => {
+    const user = userEvent.setup();
+    render(
+      <LocaleProvider>
+        <LocaleHarness />
+      </LocaleProvider>,
+    );
+
+    expect(document.documentElement).toHaveAttribute("lang", "ko-KR");
+    await user.selectOptions(screen.getByLabelText("언어"), "en-US");
+    expect(screen.getByLabelText("Language")).toHaveValue("en-US");
+    expect(document.documentElement).toHaveAttribute("lang", "en-US");
+    expect(document.documentElement).toHaveAttribute("dir", "ltr");
+
+    await user.selectOptions(screen.getByLabelText("Language"), "ar-EG");
+    expect(document.documentElement).toHaveAttribute("lang", "ar-EG");
+    expect(document.documentElement).toHaveAttribute("dir", "rtl");
+    await user.click(screen.getByRole("button", { name: "Menu" }));
+    expect(screen.getByRole("dialog", { name: "Menu" })).toHaveAttribute(
+      "open",
+    );
+  });
+
+  it("reverses horizontal tab focus semantics in RTL", async () => {
+    const user = userEvent.setup();
+    render(
+      <LocaleProvider initialLocale="ar-EG">
+        <Tabs
+          activation="manual"
+          label="sections"
+          tabs={[
+            { id: "one", label: "One", panel: "One panel" },
+            { id: "two", label: "Two", panel: "Two panel" },
+            { id: "three", label: "Three", panel: "Three panel" },
+          ]}
+        />
+      </LocaleProvider>,
+    );
+    const first = screen.getByRole("tab", { name: "One" });
+    first.focus();
+    await user.keyboard("{ArrowRight}");
+    expect(screen.getByRole("tab", { name: "Three" })).toHaveFocus();
+    await user.keyboard("{ArrowLeft}");
+    expect(first).toHaveFocus();
+  });
+
+  it("keeps pagination semantics while direction-aware icons remain decorative", () => {
+    render(
+      <LocaleProvider initialLocale="ar-EG">
+        <Pagination
+          label="pages"
+          nextLabel="Next page"
+          onChange={() => {}}
+          page={2}
+          pageCount={3}
+          pageLabel={(page) => `Page ${page}`}
+          previousLabel="Previous page"
+        />
+      </LocaleProvider>,
+    );
+    expect(
+      screen.getByRole("button", { name: "Previous page" }),
+    ).toBeEnabled();
+    expect(screen.getByRole("button", { name: "Next page" })).toBeEnabled();
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+  });
+});
@@ -86,7 +86,7 @@ describe("page template slot contracts", () => {
      />,
    );
    expect(screen.getByRole("heading", { level: 1, name: "Offline" })).toBeVisible();
-    expect(screen.getByText("SAFE-123")).toBeVisible();
+    expect(screen.getByText(/SAFE-123/)).toBeVisible();
    expect(document.body).not.toHaveTextContent("stack");
  });
 });
@@ -28,7 +28,9 @@ describe("render recovery boundaries", () => {
      </FeatureBoundary>,
    );

-    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "화면을 표시하지 못했습니다.",
+    );
    expect(onRenderFailure).toHaveBeenCalledWith({
      routeId: "APP_HOME",
      buildId: "build-a",
@@ -83,7 +85,7 @@ describe("render recovery boundaries", () => {
      </FeatureBoundary>,
    );
    shouldThrow = false;
-    await user.click(screen.getByRole("button", { name: "retry" }));
+    await user.click(screen.getByRole("button", { name: "다시 시도" }));
    view.rerender(
      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
        <Recoverable />
@@ -0,0 +1,41 @@
+import { expect, test } from "@playwright/test";
+
+test("switches the shell locale and keeps pseudo-locale copy within compact layout", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 320, height: 720 });
+  await page.goto("/");
+
+  const locale = page.getByRole("combobox", { name: "언어" });
+  await locale.selectOption("en-US");
+  await expect(page.locator("html")).toHaveAttribute("lang", "en-US");
+  await expect(page.locator("html")).toHaveAttribute("dir", "ltr");
+  await expect(page.getByRole("button", { name: "Menu" })).toBeVisible();
+
+  await page.getByRole("combobox", { name: "Language" }).selectOption("en-XA");
+  await expect(page.locator("html")).toHaveAttribute("lang", "en-XA");
+  const dimensions = await page.evaluate(() => ({
+    clientWidth: document.documentElement.clientWidth,
+    scrollWidth: document.documentElement.scrollWidth,
+  }));
+  expect(dimensions.scrollWidth).toBeLessThanOrEqual(dimensions.clientWidth);
+  await expect(page.getByRole("button", { name: /Ménú/ })).toBeVisible();
+});
+
+test("applies RTL to the shell and modal navigation without changing action semantics", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/");
+  await page.getByRole("combobox", { name: "언어" }).selectOption("ar-EG");
+
+  await expect(page.locator("html")).toHaveAttribute("lang", "ar-EG");
+  await expect(page.locator("html")).toHaveAttribute("dir", "rtl");
+  const trigger = page.getByRole("button", { name: "Menu" });
+  await trigger.click();
+  await expect(page.getByRole("dialog", { name: "Menu" })).toBeVisible();
+  await expect(page.getByRole("navigation", { name: "Primary navigation" }))
+    .toHaveCount(1);
+  await page.keyboard.press("Escape");
+  await expect(trigger).toBeFocused();
+});
@@ -72,10 +72,10 @@ describe("reference feature boundary contracts", () => {
      createdAt: "2026-07-26T00:00:00.000Z",
    });
    if (!("id" in model)) throw new Error("expected one model");
-    expect(toReferenceView(model, () => "formatted")).toEqual({
+    expect(toReferenceView(model)).toEqual({
      resourceId: "reference-1",
      title: "Example",
-      createdAtLabel: "formatted",
+      createdAt: "2026-07-26T00:00:00.000Z",
    });
  });

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createHttpClient } from "../../../src/adapters/http/client.js";
+import { createReferenceHttpGateway } from "../../../src/features/reference-feature/adapters/reference-http-gateway.js";
+import { createReferenceFeatureInput } from "../../../src/features/reference-feature/application/reference-feature-api.js";
+import { REFERENCE_FEATURE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract.js";
+import { mapReferenceOperation } from "../../../src/features/reference-feature/contracts/reference-mapper.js";
+import {
+  validateReferencePayload,
+  validateReferenceRequest,
+} from "../../../src/features/reference-feature/contracts/reference-schemas.js";
+
+describe("reference feature diagnostics correlation", () => {
+  it("preserves route, operation and request correlation through the vertical path", async () => {
+    const record = vi.fn();
+    const operations =
+      REFERENCE_FEATURE_CONTRACT.apiOperations as Readonly<
+        Record<
+          string,
+          ReturnType<
+            NonNullable<Parameters<typeof createHttpClient>[0]["getOperation"]>
+          >
+        >
+      >;
+    const client = createHttpClient({
+      baseUrl: "https://api.test",
+      fetcher: async () =>
+        Response.json({
+          success: true,
+          data: [{ id: "reference-1", name: "Reference" }],
+          meta: { requestId: "safe-request", traceId: "safe-trace" },
+        }),
+      getOperation(operationId) {
+        const operation = operations[operationId];
+        if (!operation) throw new Error("Unregistered reference operation");
+        return operation;
+      },
+      validatePayload: validateReferencePayload,
+      validateRequest: validateReferenceRequest,
+      mapPayload: mapReferenceOperation,
+      correlationIdFactory: () => "reference-correlation",
+      diagnostics: { record },
+      scheduler: {
+        setTimeout: () => 1,
+        clearTimeout: () => {},
+      },
+    });
+    const application = createReferenceFeatureInput(
+      createReferenceHttpGateway(client),
+    );
+
+    await expect(
+      application.listResources({ limit: 20 }),
+    ).resolves.toMatchObject({ ok: true });
+    expect(record).toHaveBeenCalledOnce();
+    expect(record).toHaveBeenCalledWith({
+      level: "info",
+      eventId: "http.request.completed",
+      context: expect.objectContaining({
+        route_id: "REFERENCE_RESOURCE_LIST",
+        operation_id: "LIST_REFERENCE_RESOURCES",
+        correlation_id: "reference-correlation",
+        outcome: "success",
+      }),
+    });
+  });
+});
@@ -55,7 +55,7 @@ function inputWith(
      value: {
        resourceId: "created",
        title: name,
-        createdAtLabel: null,
+        createdAt: null,
      },
    }),
    getResource: async (resourceId) => ({
@@ -63,7 +63,7 @@ function inputWith(
      value: {
        resourceId,
        title: "Detail",
-        createdAtLabel: null,
+        createdAt: null,
      },
    }),
    ...overrides,
@@ -90,7 +90,7 @@ describe("reference feature page states", () => {
        {
          resourceId: "reference-1",
          title: "Loaded",
-          createdAtLabel: null,
+          createdAt: null,
        },
      ],
    });
@@ -191,7 +191,7 @@ describe("reference feature page states", () => {
          {
            resourceId: "existing",
            title: "Existing",
-            createdAtLabel: null,
+            createdAt: null,
          },
        ],
      })
@@ -209,7 +209,7 @@ describe("reference feature page states", () => {
          {
            resourceId: "recovered",
            title: "Recovered",
-            createdAtLabel: null,
+            createdAt: null,
          },
        ],
      });
@@ -217,7 +217,9 @@ describe("reference feature page states", () => {
    await screen.findByText("Existing");
    await user.click(screen.getByRole("button", { name: "새로고침" }));

-    expect(await screen.findByText("stale-degraded")).toBeVisible();
+    expect(
+      await screen.findByText("기존 정보를 표시하고 있습니다."),
+    ).toBeVisible();
    expect(screen.getByText("Existing")).toBeVisible();
    await user.click(screen.getByRole("button", { name: "다시 시도" }));
    expect(await screen.findByText("Recovered")).toBeVisible();
@@ -0,0 +1,3 @@
+export function leakToConsole(token: string) {
+  console.error("UNKNOWN_DIAGNOSTIC_EVENT", token);
+}
@@ -0,0 +1,8 @@
+export function leakSensitiveContext(telemetry: {
+  emit(eventName: string, context: Record<string, unknown>): void;
+}) {
+  telemetry.emit("api.request.failed", {
+    authorization: "Bearer secret",
+    request_body: { email: "private@example.test" },
+  });
+}
@@ -0,0 +1,5 @@
+export function UnsafeBackendFailure({
+  failure,
+}: Readonly<{ failure: { message: string } }>) {
+  return <p>{failure.message}</p>;
+}
@@ -0,0 +1,3 @@
+export function HardcodedCommonAction() {
+  return <button type="button">다시 시도</button>;
+}
@@ -0,0 +1,3 @@
+export function UnsafeTranslatedMarkup({ value }: Readonly<{ value: string }>) {
+  return <p dangerouslySetInnerHTML={{ __html: value }} />;
+}
@@ -0,0 +1,11 @@
+import type { DiagnosticsPort } from "../../../src/application/ports/diagnostics-port.js";
+import type { TelemetryPort } from "../../../src/application/ports/telemetry-port.js";
+
+declare const diagnostics: DiagnosticsPort;
+declare const telemetry: TelemetryPort;
+
+diagnostics.record({
+  level: "fatal",
+  eventId: "UNKNOWN_DIAGNOSTIC_EVENT",
+});
+telemetry.emit("unknown.telemetry.event", {});
@@ -0,0 +1,3 @@
+import { formatMessage } from "../../../src/presentation/i18n/index.js";
+
+formatMessage("ko-KR", "unknown.translation.key");
@@ -0,0 +1,5 @@
+import { formatMessage } from "../../../src/presentation/i18n/index.js";
+
+formatMessage("en-US", "route.documentTitle");
+formatMessage("en-US", "route.documentTitle", { title: "Missing app name" });
+formatMessage("en-US", "action.retry", { unexpected: "value" });
@@ -5,7 +5,8 @@ import { createApplication } from "../../src/application/create-application.js";
 * @param {{
 *   session?: import("../../src/application/ports/auth-session-port.js").AuthSessionPort,
 *   preferences?: import("../../src/application/ports/storage-port.js").StoragePort,
- *   diagnostics?: import("../../src/application/ports/telemetry-port.js").TelemetryPort,
+ *   diagnostics?: import("../../src/application/ports/diagnostics-port.js").DiagnosticsPort,
+ *   telemetry?: import("../../src/application/ports/telemetry-port.js").TelemetryPort,
 *   releaseInfo?: import("../../src/application/ports/release-info-port.js").ReleaseInfoPort,
 *   navigation?: { reload(): void },
 *   featureInputs?: Readonly<Record<string, unknown>>
@@ -22,7 +23,8 @@ export function createTestApplication(overrides = {}) {
          write: () => ({ ok: /** @type {const} */ (true) }),
          remove: () => ({ ok: /** @type {const} */ (true) }),
        },
-      diagnostics: overrides.diagnostics ?? { emit: () => {} },
+      diagnostics: overrides.diagnostics ?? { record: () => {} },
+      telemetry: overrides.telemetry ?? { emit: () => {} },
      releaseInfo:
        overrides.releaseInfo ??
        {
@@ -0,0 +1,193 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { createHttpClient } from "../../src/adapters/http/client.js";
+import type { DiagnosticRecordInput } from "../../src/contracts/diagnostics.js";
+import { TEST_HTTP_CONTRACT } from "../helpers/http-contract-fixture.js";
+
+function successResponse(data: unknown) {
+  return Response.json({
+    success: true,
+    data,
+    meta: { requestId: "request-1", traceId: "trace-1" },
+  });
+}
+
+function failureResponse(status: number) {
+  return Response.json(
+    {
+      success: false,
+      error: { code: "TEMPORARY" },
+      meta: { requestId: "request-1", traceId: "trace-1" },
+    },
+    { status },
+  );
+}
+
+type EmittedEvent = Readonly<{
+  eventName: string;
+  attributes: Readonly<Record<string, unknown>>;
+}>;
+
+function harness(fetcher: typeof fetch, maxRetryAttempts = 1) {
+  const records: DiagnosticRecordInput[] = [];
+  const emitted: EmittedEvent[] = [];
+  let currentTime = 0;
+  const client = createHttpClient({
+    ...TEST_HTTP_CONTRACT,
+    baseUrl: "https://api.test",
+    fetcher,
+    maxRetryAttempts,
+    clock: {
+      now: () => currentTime,
+      sleep: async () => {
+        currentTime += 150;
+      },
+    },
+    scheduler: {
+      setTimeout: () => 1,
+      clearTimeout: () => {},
+    },
+    correlationIdFactory: () => "correlation-fixed",
+    diagnostics: {
+      record(input) {
+        records.push(structuredClone(input));
+      },
+    },
+    telemetry: {
+      emit(eventName, attributes) {
+        emitted.push({
+          eventName,
+          attributes: structuredClone(attributes),
+        });
+      },
+    },
+  });
+  return { client, records, emitted };
+}
+
+describe("HTTP diagnostics and terminal telemetry", () => {
+  it("records one successful reference route outcome and no failure event", async () => {
+    const { client, records, emitted } = harness(
+      vi.fn(async () => successResponse([])),
+    );
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+      }),
+    ).resolves.toMatchObject({ ok: true });
+
+    expect(records).toEqual([
+      {
+        level: "info",
+        eventId: "http.request.completed",
+        context: {
+          route_id: "TEST_ROUTE",
+          operation_id: "LIST_ENTITIES",
+          correlation_id: "correlation-fixed",
+          outcome: "success",
+          error_kind: "NONE",
+          http_status_group: "none",
+          attempt_count_bucket: "1",
+          duration_bucket: "lt100ms",
+        },
+      },
+    ]);
+    expect(emitted).toEqual([]);
+  });
+
+  it("summarizes retry recovery once without a terminal failure event", async () => {
+    const fetcher = vi
+      .fn<typeof fetch>()
+      .mockResolvedValueOnce(failureResponse(503))
+      .mockResolvedValueOnce(successResponse([]));
+    const { client, records, emitted } = harness(fetcher);
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+      }),
+    ).resolves.toMatchObject({ ok: true });
+
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      eventId: "http.request.completed",
+      context: {
+        outcome: "recovered",
+        correlation_id: "correlation-fixed",
+        duration_bucket: "100-499ms",
+      },
+    });
+    expect(emitted).toEqual([]);
+  });
+
+  it("emits one bounded terminal failure after all attempts", async () => {
+    const fetcher = vi.fn(async () => failureResponse(503));
+    const { client, records, emitted } = harness(fetcher);
+
+    await expect(
+      client.execute({
+        operationId: "CREATE_ENTITY",
+        routeId: "TEST_ROUTE",
+        body: { name: "private user input" },
+        idempotencyKey: "private-idempotency-key",
+      }),
+    ).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "SERVER_FAILURE" },
+    });
+
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(records).toHaveLength(1);
+    expect(emitted).toEqual([
+      {
+        eventName: "api.request.failed",
+        attributes: {
+          error_kind: "SERVER_FAILURE",
+          http_status_group: "5xx",
+          attempt_count_bucket: "2",
+          route_id: "TEST_ROUTE",
+          operation_id: "CREATE_ENTITY",
+          duration_bucket: "100-499ms",
+        },
+      },
+    ]);
+    expect(JSON.stringify({ records, emitted })).not.toMatch(
+      /private user input|private-idempotency-key/,
+    );
+  });
+
+  it("records navigation abort without failure telemetry", async () => {
+    const caller = new AbortController();
+    caller.abort("navigation");
+    const fetcher = vi.fn(async (request: RequestInfo | URL) => {
+      const signal = (request as Request).signal;
+      if (signal.aborted) throw new DOMException("aborted", "AbortError");
+      return successResponse([]);
+    });
+    const { client, records, emitted } = harness(
+      fetcher as unknown as typeof fetch,
+    );
+
+    await expect(
+      client.execute({
+        operationId: "LIST_ENTITIES",
+        routeId: "TEST_ROUTE",
+        signal: caller.signal,
+      }),
+    ).resolves.toMatchObject({
+      ok: false,
+      error: { kind: "REQUEST_ABORTED" },
+    });
+
+    expect(records).toHaveLength(1);
+    expect(records[0]).toMatchObject({
+      eventId: "http.request.completed",
+      context: { outcome: "aborted", error_kind: "REQUEST_ABORTED" },
+    });
+    expect(emitted).toEqual([]);
+  });
+});
@@ -36,6 +36,7 @@ describe("application input/output boundary", () => {
  it("uses fake output ports for preference, session, and safe diagnostics flows", () => {
    const write = vi.fn(() => ({ ok: true as const }));
    const emit = vi.fn();
+    const record = vi.fn();
    const ports = {
      session: {
        getState: () => "authenticated" as const,
@@ -49,7 +50,8 @@ describe("application input/output boundary", () => {
        write,
        remove: () => ({ ok: true as const }),
      },
-      diagnostics: { emit },
+      diagnostics: { record },
+      telemetry: { emit },
      releaseInfo: {
        getCurrent: async () => ({
          buildId: "build-a",
@@ -82,20 +84,43 @@ describe("application input/output boundary", () => {
      buildId: "build-a",
      boundaryName: "route",
    });
+    expect(record).toHaveBeenCalledWith({
+      level: "error",
+      eventId: "ui.render.failed",
+      context: {
+        route_id: "APP_HOME",
+        build_id: "build-a",
+        component_boundary: "route",
+      },
+    });
    expect(emit).toHaveBeenCalledWith("ui.render.failed", {
      route_id: "APP_HOME",
      build_id: "build-a",
      component_boundary: "route",
    });
+    application.diagnostics.reportRouteChanged({
+      routeId: "APP_HOME",
+      buildId: "build-a",
+    });
+    expect(record).toHaveBeenCalledWith({
+      level: "info",
+      eventId: "route.changed",
+      context: { route_id: "APP_HOME", build_id: "build-a" },
+    });
  });

  it("does not let a failing diagnostics output escape into presentation", () => {
    const application = createTestApplication({
      diagnostics: {
-        emit() {
+        record() {
          throw new Error("sink details");
        },
      },
+      telemetry: {
+        emit() {
+          throw new Error("telemetry details");
+        },
+      },
    });

    expect(() =>
@@ -3,6 +3,8 @@ import { describe, expect, it, vi } from "vitest";
 import { createApplication } from "../../src/application/create-application.js";
 import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
 import type { StoragePort } from "../../src/application/ports/storage-port.js";
+import type { DiagnosticsPort } from "../../src/application/ports/diagnostics-port.js";
+import type { TelemetryPort } from "../../src/application/ports/telemetry-port.js";

 type ReleaseFixture = {
  buildId: string;
@@ -40,12 +42,15 @@ function applicationWith(options: {
  storage?: StoragePort;
  refresh?: () => Promise<ReturnType<typeof release>>;
  reload?: () => void;
+  diagnostics?: DiagnosticsPort;
+  telemetry?: TelemetryPort;
 }) {
  const current = release("build-a", "release-a");
  return createApplication({
    session: createAnonymousSessionAdapter(),
    preferences: options.storage ?? memoryStorage(),
-    diagnostics: { emit: () => {} },
+    diagnostics: options.diagnostics ?? { record: () => {} },
+    telemetry: options.telemetry ?? { emit: () => {} },
    releaseInfo: {
      getCurrent: async () => current,
      refresh:
@@ -59,7 +64,13 @@ function applicationWith(options: {
 describe("production chunk recovery application input", () => {
  it("reloads exactly once for one active build/release pair", async () => {
    const reload = vi.fn();
-    const application = applicationWith({ reload });
+    const record = vi.fn<DiagnosticsPort["record"]>();
+    const emit = vi.fn<TelemetryPort["emit"]>();
+    const application = applicationWith({
+      reload,
+      diagnostics: { record },
+      telemetry: { emit },
+    });
    const input = {
      chunkId: "route-home",
      failureKind: "CHUNK_LOAD_FAILURE" as const,
@@ -69,6 +80,20 @@ describe("production chunk recovery application input", () => {
      action: "reload-once",
      releasePair: "build-a/release-a->build-b/release-b",
    });
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "release.mismatch.detected",
+      context: {
+        build_id: "build-a",
+        active_release_id: "release-b",
+        mismatch_kind: "BUILD_MISMATCH",
+      },
+    });
+    expect(emit).toHaveBeenCalledWith("release.mismatch.detected", {
+      build_id: "build-a",
+      active_release_id: "release-b",
+      mismatch_kind: "BUILD_MISMATCH",
+    });
    await expect(application.recovery.recoverChunk(input)).resolves.toEqual({
      action: "support",
      reason: "reload-already-attempted",
@@ -0,0 +1,141 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  createDiagnosticsAdapter,
+  getLastBootEvidence,
+  noOpDiagnostics,
+  recordBootFailure,
+} from "../../src/adapters/diagnostics/bounded-diagnostics.js";
+import {
+  projectDiagnosticRecord,
+  safeErrorKind,
+} from "../../src/contracts/diagnostics.js";
+
+describe("structured diagnostics contract", () => {
+  it("projects only registered, bounded context with deterministic time", () => {
+    const projected = projectDiagnosticRecord(
+      {
+        level: "info",
+        eventId: "route.changed",
+        context: { route_id: "APP_HOME", build_id: "build-a" },
+      },
+      () => 0,
+    );
+
+    expect(projected).toEqual({
+      success: true,
+      record: {
+        level: "info",
+        eventId: "route.changed",
+        timestamp: "1970-01-01T00:00:00.000Z",
+        context: { route_id: "APP_HOME", build_id: "build-a" },
+      },
+    });
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: { raw_url: "https://example.test/private?token=secret" },
+      }),
+    ).toEqual({ success: false, reason: "unknown-context" });
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: { route_id: "private value with whitespace" },
+      }),
+    ).toEqual({ success: false, reason: "invalid-context" });
+  });
+
+  it("bounds evidence and isolates throwing sinks and hostile error objects", () => {
+    const sink = vi.fn(() => {
+      throw new Error("sink-secret");
+    });
+    const adapter = createDiagnosticsAdapter({
+      maxEntries: 1,
+      now: () => 0,
+      sink,
+    });
+    const circular: Record<string, unknown> = { name: "TypeError" };
+    circular.self = circular;
+    const hostile = new Proxy(
+      {},
+      {
+        get() {
+          throw new Error("private getter");
+        },
+        ownKeys() {
+          throw new Error("private keys");
+        },
+      },
+    );
+
+    expect(safeErrorKind(circular)).toBe("TYPE_ERROR");
+    expect(safeErrorKind(hostile)).toBe("UNKNOWN_FAILURE");
+    expect(
+      projectDiagnosticRecord({
+        level: "error",
+        eventId: "ui.render.failed",
+        context: hostile,
+      }),
+    ).toEqual({ success: false, reason: "serialization-failure" });
+    expect(() =>
+      adapter.record({
+        level: "info",
+        eventId: "route.changed",
+        context: { route_id: "APP_HOME" },
+      }),
+    ).not.toThrow();
+    adapter.record({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: { operation: "query", error_kind: "UNKNOWN_FAILURE" },
+    });
+
+    expect(adapter.entries()).toHaveLength(1);
+    expect(adapter.entries()[0]?.eventId).toBe("cache.operation.failed");
+    expect(adapter.dropped()).toEqual({
+      "queue-full": 1,
+      "sink-failure": 2,
+    });
+    expect(JSON.stringify(adapter.entries())).not.toMatch(
+      /sink-secret|private getter/,
+    );
+  });
+
+  it("creates safe pre-mount boot evidence and supports a true no-op", () => {
+    const circular: Record<string, unknown> = {
+      name: "TypeError",
+      token: "credential-value",
+      stack: "private-stack",
+    };
+    circular.self = circular;
+
+    expect(() =>
+      recordBootFailure(
+        circular,
+        {
+          buildId: "build-a",
+          configSchemaVersion: "1",
+          supportReference: "support-private",
+        },
+        () => 0,
+      ),
+    ).not.toThrow();
+    const evidence = getLastBootEvidence();
+    expect(evidence?.diagnostic?.eventId).toBe("app.boot.failed");
+    expect(evidence?.telemetry).toMatchObject({
+      eventName: "app.boot.failed",
+      timestamp: "1970-01-01T00:00:00.000Z",
+    });
+    expect(JSON.stringify(evidence)).not.toMatch(
+      /credential-value|private-stack|support-private/,
+    );
+    expect(() =>
+      noOpDiagnostics.record({
+        level: "error",
+        eventId: "app.boot.failed",
+      }),
+    ).not.toThrow();
+  });
+});
@@ -0,0 +1,115 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  catalogKeys,
+  FORMAT_FALLBACK,
+  formatDate,
+  formatList,
+  formatMessage,
+  formatNumber,
+  formatRelativeTime,
+  localeDirection,
+  messagePlaceholders,
+  normalizeLocale,
+  resolveMessage,
+  selectMessage,
+  selectPlural,
+} from "../../src/presentation/i18n/index.js";
+import {
+  EN_MESSAGES,
+  KO_MESSAGES,
+  MESSAGE_CATALOGS,
+} from "../../src/presentation/i18n/catalog.js";
+
+describe("internationalization message contract", () => {
+  it("keeps every registered catalog and interpolation contract in parity", () => {
+    expect(catalogKeys("en-US")).toEqual(catalogKeys("ko-KR"));
+    expect(catalogKeys("ar-EG")).toEqual(catalogKeys("ko-KR"));
+
+    for (const key of catalogKeys("ko-KR")) {
+      expect(messagePlaceholders(EN_MESSAGES[key])).toEqual(
+        messagePlaceholders(KO_MESSAGES[key]),
+      );
+    }
+    expect(MESSAGE_CATALOGS["ar-EG"]).toBe(EN_MESSAGES);
+  });
+
+  it("formats typed parameters and expands the pseudo locale", () => {
+    expect(
+      formatMessage("en-US", "route.documentTitle", {
+        title: "Settings",
+        appName: "Skeleton",
+      }),
+    ).toBe("Settings · Skeleton");
+    const pseudo = formatMessage("en-XA", "action.closeNamed", {
+      title: "Account",
+    });
+    expect(pseudo).toMatch(/^［.+ ···］$/);
+    expect(pseudo.length).toBeGreaterThan("Close Account".length);
+  });
+
+  it("falls back safely for unknown locale, key and missing interpolation", () => {
+    expect(normalizeLocale("fr-FR")).toBe("ko-KR");
+    expect(resolveMessage("fr-FR", "action.retry")).toBe("다시 시도");
+    expect(resolveMessage("en-US", "action.login")).toBe("Sign in");
+    expect(resolveMessage("en-US", "backend.stack.trace")).toBe(
+      "요청한 문구를 표시할 수 없습니다.",
+    );
+    expect(resolveMessage("en-US", "action.closeNamed")).toBe(
+      "요청한 문구를 표시할 수 없습니다.",
+    );
+    expect(resolveMessage("en-US", "backend.stack.trace")).not.toContain(
+      "backend.stack.trace",
+    );
+  });
+
+  it("defines direction without inferring it in components", () => {
+    expect(localeDirection("ko-KR")).toBe("ltr");
+    expect(localeDirection("en-XA")).toBe("ltr");
+    expect(localeDirection("ar-EG")).toBe("rtl");
+  });
+});
+
+describe("internationalization formatter contract", () => {
+  const instant = new Date("2026-07-26T23:30:00.000Z");
+
+  it("uses an explicit UTC default and deterministic locale formatting", () => {
+    expect(formatDate("en-US", instant, { dateStyle: "short" })).toBe(
+      "7/26/26",
+    );
+    expect(
+      formatDate("en-US", instant, {
+        dateStyle: "short",
+        timeZone: "Asia/Seoul",
+      }),
+    ).toBe("7/27/26");
+    expect(formatNumber("en-US", 1234.5)).toBe("1,234.5");
+    expect(formatRelativeTime("en-US", -1, "day")).toBe("yesterday");
+    expect(formatList("en-US", ["one", "two", "three"])).toBe(
+      "one, two, and three",
+    );
+    expect(selectPlural("en-US", 1, { one: "item", other: "items" })).toBe(
+      "item",
+    );
+    expect(
+      selectPlural("en-US", 3, { one: "item", other: "items" }),
+    ).toBe("items");
+    expect(
+      selectMessage("pending", {
+        ready: "Ready",
+        pending: "Pending",
+        other: "Unknown",
+      }),
+    ).toBe("Pending");
+  });
+
+  it("does not throw or expose invalid formatter input", () => {
+    expect(formatDate("en-US", Number.NaN)).toBe(FORMAT_FALLBACK);
+    expect(formatNumber("en-US", Number.POSITIVE_INFINITY)).toBe(
+      FORMAT_FALLBACK,
+    );
+    expect(
+      formatDate("en-US", instant, { timeZone: "not/a-time-zone" }),
+    ).toBe(FORMAT_FALLBACK);
+  });
+});
@@ -52,7 +52,10 @@ describe("TanStack QueryCachePort adapter", () => {
  it("normalizes adapter exceptions without raw key data", async () => {
    const client = new QueryClient();
    vi.spyOn(client, "invalidateQueries").mockRejectedValue(new Error("secret-key"));
-    const adapter = createQueryCacheAdapter(client);
+    const record = vi.fn();
+    const adapter = createQueryCacheAdapter(client, {
+      diagnostics: { record },
+    });
    const result = await adapter.invalidate(["resource", "sensitive-filter"]);

    expect(result).toMatchObject({
@@ -60,5 +63,16 @@ describe("TanStack QueryCachePort adapter", () => {
      error: { kind: "QUERY_CACHE_FAILURE" },
    });
    expect(JSON.stringify(result)).not.toContain("sensitive-filter");
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "cache.operation.failed",
+      context: {
+        operation: "invalidate",
+        error_kind: "QUERY_CACHE_FAILURE",
+      },
+    });
+    expect(JSON.stringify(record.mock.calls)).not.toMatch(
+      /sensitive-filter|secret-key/,
+    );
  });
 });
@@ -46,6 +46,9 @@ describe("runtime adapter composition", () => {
      releaseId: "release-a",
    });
    expect(adapters.infrastructure.queryClient).toBeDefined();
+    expect(adapters.outputPorts.diagnostics.record).toEqual(expect.any(Function));
+    expect(adapters.outputPorts.telemetry.emit).toEqual(expect.any(Function));
+    expect(adapters.outputPorts.telemetry.pendingCount()).toBe(0);
    expect(adapters).not.toHaveProperty("http");
    expect(adapters).not.toHaveProperty("storage");
  });
@@ -1,4 +1,4 @@
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";

 import { createBrowserStorageAdapter } from "../../src/adapters/storage/browser-storage-adapter.js";
 import {
@@ -61,13 +61,27 @@ describe("storage registry", () => {

  it("falls back to memory when preference storage quota is exceeded", () => {
    const localStorage = createStorage({ quota: true });
-    const adapter = createBrowserStorageAdapter({ localStorage });
+    const record = vi.fn();
+    const adapter = createBrowserStorageAdapter({
+      localStorage,
+      diagnostics: { record },
+    });
    expect(adapter.write("COLOR_SCHEME", "dark")).toMatchObject({
      ok: false,
      fallback: "memory",
      error: { kind: "STORAGE_QUOTA_EXCEEDED" },
    });
    expect(adapter.read("COLOR_SCHEME")).toEqual({ ok: true, value: "dark" });
+    expect(record).toHaveBeenCalledOnce();
+    expect(record).toHaveBeenCalledWith({
+      level: "warn",
+      eventId: "storage.operation.failed",
+      context: {
+        operation: "write:COLOR_SCHEME",
+        error_kind: "STORAGE_QUOTA_EXCEEDED",
+      },
+    });
+    expect(JSON.stringify(record.mock.calls)).not.toContain("dark");
  });

  it("discards data from a previous schema version", () => {
@@ -33,15 +33,26 @@ describe("telemetry registry and redaction", () => {
    }
  });

-  it("uses a default-deny attribute projection", () => {
+  it("redacts forbidden attributes and rejects unknown context", () => {
    const projected = projectTelemetryEvent("api.request.failed", {
      ...validAttributes,
      raw_url: "https://api.test/path?token=secret",
-      unregistered: "private",
    });

    expect(projected.success).toBe(true);
-    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret|unregistered/);
+    expect(JSON.stringify(projected)).not.toMatch(/raw_url|token|secret/);
+    expect(
+      projectTelemetryEvent("api.request.failed", {
+        ...validAttributes,
+        unregistered: "private",
+      }),
+    ).toEqual({ success: false, reason: "unknown-attributes" });
+    expect(
+      projectTelemetryEvent("api.request.failed", {
+        ...validAttributes,
+        route_id: "/users/actual-user-id",
+      }),
+    ).toEqual({ success: false, reason: "invalid-attribute-value" });
  });

  it("validates traceparent without exposing invalid values", () => {
@@ -71,10 +82,18 @@ describe("best-effort telemetry adapter", () => {

    expect(adapter.pendingCount()).toBe(2);
    expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.dropReasons()).toEqual({ "queue-full": 1 });
+    expect(adapter.deliveryEvidence()).toMatchObject({
+      eventName: "telemetry.delivery.dropped",
+      attributes: { reason: "queue-full", queue_size_bucket: "1-10" },
+    });
    expect(scheduled).toHaveLength(1);
  });

  it("degrades on sink failure without throwing or recursive events", async () => {
+    const onDrop = vi.fn(() => {
+      throw new Error("observer unavailable");
+    });
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
@@ -82,13 +101,50 @@ describe("best-effort telemetry adapter", () => {
      fetcher: async () => {
        throw new Error("sink unavailable");
      },
+      onDrop,
    });
    expect(() => adapter.emit("api.request.failed", validAttributes)).not.toThrow();
    await expect(adapter.flush()).resolves.toBeUndefined();
    expect(adapter.droppedCount()).toBe(1);
+    expect(adapter.dropReasons()).toEqual({ "sink-failure": 1 });
+    expect(onDrop).toHaveBeenCalledOnce();
    expect(adapter.pendingCount()).toBe(0);
  });

+  it("never serializes circular or unbounded event context", () => {
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+    });
+    const circular = {};
+    circular.self = circular;
+    const hostile = new Proxy(
+      {},
+      {
+        ownKeys() {
+          throw new Error("private proxy value");
+        },
+      },
+    );
+
+    expect(() =>
+      adapter.emit("api.request.failed", {
+        ...validAttributes,
+        unregistered: circular,
+      }),
+    ).not.toThrow();
+    expect(adapter.pendingCount()).toBe(0);
+    expect(adapter.dropReasons()).toEqual({ "invalid-context": 1 });
+    expect(() =>
+      adapter.emit("api.request.failed", hostile),
+    ).not.toThrow();
+    expect(adapter.dropReasons()).toEqual({
+      "invalid-context": 1,
+      "serialization-failure": 1,
+    });
+  });
+
  it("performs no network or queue work when disabled", async () => {
    const fetcher = vi.fn();
    const adapter = createTelemetryAdapter({
@@ -102,4 +158,25 @@ describe("best-effort telemetry adapter", () => {
    expect(fetcher).not.toHaveBeenCalled();
    expect(adapter.pendingCount()).toBe(0);
  });
+
+  it("flushes on page exit and removes the lifecycle listener", async () => {
+    const lifecycle = new EventTarget();
+    const remove = vi.spyOn(lifecycle, "removeEventListener");
+    const fetcher = vi.fn(async () => new Response(null, { status: 204 }));
+    const adapter = createTelemetryAdapter({
+      enabled: true,
+      endpoint: "https://telemetry.test/events",
+      schedule: () => {},
+      lifecycle,
+      fetcher,
+    });
+    adapter.emit("api.request.failed", validAttributes);
+
+    lifecycle.dispatchEvent(new Event("pagehide"));
+    await vi.waitFor(() => expect(fetcher).toHaveBeenCalledOnce());
+    adapter.dispose();
+
+    expect(adapter.pendingCount()).toBe(0);
+    expect(remove).toHaveBeenCalledWith("pagehide", expect.any(Function));
+  });
 });
Author	SHA1	Message	Date
donghyeon-ka	5173b6c8d6	feat: add diagnostics and telemetry runtime	2026-07-26 16:42:27 +09:00
donghyeon-ka	2fa0baa577	merge: internationalization message platform	2026-07-26 16:17:45 +09:00
donghyeon-ka	668bf05b48	feat: add internationalization message platform	2026-07-26 16:17:39 +09:00
donghyeon-ka	b8c0444217	merge: design system platform	2026-07-26 15:49:13 +09:00