feat: add removable reference feature vertical slice

.dependency-cruiser.cjs

@@ -20,7 +20,7 @@ module.exports = {
     {
       name: "presentation-does-not-know-adapters",
       severity: "error",
-      from: { path: "^src/presentation" },
+      from: { path: "^src/presentation/(?!adapters/query)" },
       to: { path: "^(src/(adapters|bootstrap)|@tanstack)" },
     },
     {
@@ -29,10 +29,42 @@ module.exports = {
       from: { path: "^src/adapters" },
       to: { path: "^src/(presentation|bootstrap)" },
     },
+    {
+      name: "feature-domain-is-framework-neutral",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/domain" },
+      to: {
+        path: "^(src/(application|presentation|adapters|bootstrap)|src/features/[^/]+/(application|adapters|presentation)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "feature-application-does-not-know-runtime",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/application" },
+      to: {
+        path: "^(src/(presentation|adapters|bootstrap)|src/features/[^/]+/(adapters|presentation)|react|react-dom|@tanstack)",
+      },
+    },
+    {
+      name: "feature-presentation-does-not-know-outbound-adapters",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/presentation" },
+      to: {
+        path: "^(src/(adapters|bootstrap)|src/features/[^/]+/adapters|@tanstack)",
+      },
+    },
+    {
+      name: "feature-adapters-do-not-know-presentation",
+      severity: "error",
+      from: { path: "^src/features/[^/]+/adapters" },
+      to: {
+        path: "^(src/(presentation|bootstrap)|src/features/[^/]+/presentation)",
+      },
+    },
     {
       name: "concrete-adapters-compose-only-in-bootstrap",
       severity: "error",
-      from: { path: "^src/(domain|application|presentation|contracts|sample)" },
+      from: { path: "^src/(domain|application|presentation|contracts)" },
       to: { path: "^src/adapters" },
     },
     {

artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md

@@ -1,7 +1,7 @@
 # SAMPLE_RESOURCE_LIST accessibility review
 
 Status: pending-manual-review
-Route ID: SAMPLE_RESOURCE_LIST
+Route ID: REFERENCE_RESOURCE_LIST
 Release ID:
 Reviewer:
 Reviewed at:

config/ci/gates.json

@@ -78,7 +78,9 @@
         { "script": "check:types:fixture:ts-port", "expect": "fail" },
         { "script": "check:types:fixture:ts-result", "expect": "fail" },
         { "script": "check:types:fixture:application-output", "expect": "fail" },
-        { "script": "check:types:fixture:application-input", "expect": "fail" }
+        { "script": "check:types:fixture:application-input", "expect": "fail" },
+        { "script": "check:types:fixture:async-overlay", "expect": "fail" },
+        { "script": "check:types:fixture:route-runtime", "expect": "fail" }
       ],
       "logPath": "artifacts/quality/check-types.txt",
       "evidence": ["artifacts/quality/check-types.txt"],
@@ -107,9 +109,15 @@
     },
     "FE-GATE-007": {
       "name": "integration",
-      "steps": [{ "script": "test:integration", "expect": "pass" }],
+      "steps": [
+        { "script": "test:integration", "expect": "pass" },
+        { "script": "test:reference-feature", "expect": "pass" }
+      ],
       "logPath": "artifacts/quality/gates/FE-GATE-007.txt",
-      "evidence": ["artifacts/tests/integration.xml"],
+      "evidence": [
+        "artifacts/tests/integration.xml",
+        "artifacts/tests/reference-feature.xml"
+      ],
       "retentionClass": "merge-cycle"
     },
     "FE-GATE-008": {
@@ -132,7 +140,7 @@
         "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
         "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
         "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
-        "artifacts/tests/a11y-manual/SAMPLE_RESOURCE_LIST.md",
+        "artifacts/tests/a11y-manual/REFERENCE_RESOURCE_LIST.md",
         "artifacts/tests/a11y-manual/NOT_FOUND.md",
         "artifacts/tests/a11y-manual/report.json"
       ],
@@ -143,13 +151,15 @@
       "steps": [
         { "script": "check:architecture", "expect": "pass" },
         { "script": "check:registries", "expect": "pass" },
-        { "script": "check:registries:fixture", "expect": "fail" }
+        { "script": "check:registries:fixture", "expect": "fail" },
+        { "script": "check:routes:fixture", "expect": "fail" }
       ],
       "logPath": "artifacts/quality/gates/FE-GATE-010.txt",
       "evidence": [
         "artifacts/quality/dependency-report.json",
         "artifacts/quality/registries.json",
-        "artifacts/quality/registry-fixture.json"
+        "artifacts/quality/registry-fixture.json",
+        "artifacts/quality/route-registry-fixture.json"
       ],
       "retentionClass": "merge-cycle"
     },
@@ -157,7 +167,10 @@
       "name": "build",
       "steps": [{ "script": "build", "expect": "pass" }],
       "logPath": "artifacts/quality/gates/FE-GATE-011.txt",
-      "evidence": ["artifacts/release/build-manifest.json"],
+      "evidence": [
+        "artifacts/release/build-manifest.json",
+        "artifacts/release/runtime-config.schema.json"
+      ],
       "retentionClass": "release-coherence"
     },
     "FE-GATE-012": {
@@ -249,7 +262,7 @@
       "retentionClass": "release-coherence"
     },
     "FE-GATE-020": {
-      "name": "sample-removal",
+      "name": "reference-feature-removal",
       "steps": [{ "script": "test:sample-removal", "expect": "pass" }],
       "logPath": "artifacts/quality/gates/FE-GATE-020.txt",
       "evidence": ["artifacts/tests/sample-removal.xml"],

config/contracts/registry-governance.json

@@ -3,9 +3,40 @@
   "registries": [
     {
       "registryId": "FE-REG-ROUTE",
-      "path": "src/contracts/routes.js",
+      "path": "src/features/installed-feature-contracts.js",
       "exportName": "ROUTE_REGISTRY",
       "owner": "feature-routing-navigation-guard-contract",
+      "uniqueFields": ["routeId", "path", "chunkId"],
+      "allowedValues": {
+        "paramsSchema": [null, "NotFoundSplat"],
+        "searchSchema": [null, "ReferenceResourceListQuery"],
+        "loadingSurface": [
+          "app-shell",
+          "example-page",
+          "reference-resource-list",
+          "none"
+        ],
+        "errorSurface": [
+          "route-boundary",
+          "feature-boundary",
+          "not-found"
+        ],
+        "chunkId": [
+          "route-home",
+          "route-examples-ui",
+          "route-examples-states",
+          "route-examples-auth",
+          "route-reference-resources",
+          "route-not-found"
+        ]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "FE-REG-ROUTE-RUNTIME",
+          "targetField": "routeId"
+        }
+      ],
       "requiredFields": [
         "routeId",
         "path",
@@ -17,9 +48,41 @@
         "chunkId"
       ]
     },
+    {
+      "registryId": "FE-REG-ROUTE-RUNTIME",
+      "path": "src/features/installed-feature-contracts.js",
+      "exportName": "ROUTE_RUNTIME_CONTRACT",
+      "owner": "feature-frontend-routing-release-recovery-runtime",
+      "requiredFields": [
+        "routeId",
+        "moduleId",
+        "paramsCodec",
+        "searchCodec"
+      ],
+      "uniqueFields": ["routeId", "moduleId"],
+      "allowedValues": {
+        "moduleId": [
+          "home-page",
+          "ui-gallery-page",
+          "state-gallery-page",
+          "auth-example-page",
+          "reference-resource-page",
+          "not-found-page"
+        ],
+        "paramsCodec": ["none", "NotFoundSplat"],
+        "searchCodec": ["none", "ReferenceResourceListQuery"]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "FE-REG-ROUTE",
+          "targetField": "routeId"
+        }
+      ]
+    },
     {
       "registryId": "FE-REG-API",
-      "path": "src/contracts/api-operations.js",
+      "path": "src/features/installed-feature-contracts.js",
       "exportName": "API_OPERATIONS",
       "owner": "feature-api-client-response-envelope-contract",
       "requiredFields": [
@@ -29,6 +92,8 @@
         "auth",
         "timeoutMs",
         "idempotency",
+        "retry",
+        "requestSource",
         "requestSchema",
         "responseSchema",
         "owner"
@@ -74,7 +139,7 @@
     },
     {
       "registryId": "FE-REG-QUERY",
-      "path": "src/contracts/query-keys.js",
+      "path": "src/features/installed-feature-contracts.js",
       "exportName": "QUERY_REGISTRY",
       "owner": "feature-server-state-caching-contract",
       "requiredFields": [
@@ -111,6 +176,6 @@
   ],
   "compatibilityImpact": {
     "allowed": ["none", "additive", "behavior-change", "breaking"],
-    "current": "additive"
+    "current": "behavior-change"
   }
 }

docs/accessibility/manual-checklist.md

@@ -4,7 +4,7 @@ Automated axe checks do not establish WCAG conformance. A human reviewer must
 review all six route records in `artifacts/tests/a11y-manual/` against one
 release candidate and sign them. The required scope is derived from the route
 registry: `APP_HOME`, `EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`,
-`SAMPLE_RESOURCE_LIST`, and `NOT_FOUND`. Copy the template fields exactly; the
+`REFERENCE_RESOURCE_LIST`, and `NOT_FOUND`. Copy the template fields exactly; the
 gate rejects blank identity/timestamp/signature fields, pending verdicts,
 mismatched release IDs, or missing routes.
 

docs/architecture/decisions/VD-03-react-router-data-mode.md

@@ -0,0 +1,58 @@
+# VD-03: React Router Data Mode와 서버 상태 소유권
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-routing-release-recovery-runtime`
+
+## 배경
+
+기존 라우터는 `BrowserRouter`와 수동 JSX route 목록을 사용했다. 직렬화 가능한
+route registry에 params/search schema, loading/error surface, access, title,
+navigation과 chunk ID가 있었지만 실행 route tree와 독립적이어서 선언과 행동이
+어긋날 수 있었다.
+
+이 저장소는 client-only SPA이며 서버 상태는 application input과 TanStack Query가
+소유한다. Framework Mode의 loader/action 중심 데이터 소유권이나 SSR을 도입하지
+않으면서 route object, 오류 경계와 navigation lifecycle은 중앙에서 조립할
+필요가 있다.
+
+## 결정
+
+1. 고정된 React Router `7.18.1`의 `createBrowserRouter`와 `RouterProvider`를
+   사용하는 Data Mode를 기본값으로 채택한다.
+2. 직렬화 가능한 route contract와 React component/codec runtime map을 분리한다.
+3. 모든 executable route object와 navigation은 registry에서 생성한다. JSX에서
+   route 목록을 다시 열거하지 않는다.
+4. params/search는 route 경계의 Zod codec으로 parse하고 같은 codec으로 canonical
+   URL을 생성한다.
+5. loader/action은 같은 서버 데이터를 직접 다시 요청하지 않는다. 필요하면
+   application input 또는 query adapter 한 경로를 호출한다.
+6. 서버 상태, retry, cache와 mutation lifecycle은 application input과 TanStack
+   Query가 계속 소유한다.
+7. lazy chunk rejection만 release recovery input으로 보내며 일반 render error는
+   route/feature boundary가 소유한다.
+8. Framework Mode, SSR, static generation과 router version upgrade는 별도
+   dependency/architecture 브랜치에서 결정한다.
+
+## 검증
+
+- route contract/runtime map의 누락과 orphan은 TypeScript negative fixture와
+  registry gate가 모두 거절한다.
+- duplicate ID/path, unknown codec/surface/chunk와 참조 불일치를 negative registry
+  fixture로 검증한다.
+- params/search parse/build round-trip, canonical redirect, 최대 redirect hop,
+  access rejection, title/focus와 boundary reset을 unit/component test로 검증한다.
+- Vite dynamic entry와 release route chunk map, runtime config JSON Schema를
+  build/release 검증기가 확인한다.
+- chunk failure는 no-store manifest refetch 후 build/release 쌍마다 한 번만
+  reload하며 offline, malformed manifest와 storage 실패는 fail-closed한다.
+
+## 결과와 rollback
+
+Data Router는 navigation lifecycle의 조립 경계이며 서버 데이터 계층이 아니다.
+이 구분을 지키면 React Router를 교체해도 application input과 output port는
+유지된다.
+
+rollback은 RP-04 merge를 되돌려 이전 수동 router와 generic route failure
+surface로 복구한다. URL shape와 application API는 유지하고, 이미 배포된 asset
+cache의 purge는 저장소 rollback 범위에 포함하지 않는다.

docs/architecture/frontend-platform-capability-review.md

@@ -12,9 +12,9 @@
 - 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
 - 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.
 
-검토 기준 브랜치는 `develop`, 기준 커밋은 `cb195f8`이다. 이후 구현으로 경로나
+최초 검토 기준은 `develop`의 `cb195f8`이며, RP-01~RP-04 구현 결과를 이 문서에
-세부 내용이 달라질 수 있으므로, 각 항목은 문서의 경로뿐 아니라 해당 테스트와
+누적 반영했다. 이후 구현으로 경로나 세부 내용이 달라질 수 있으므로, 각 항목은
-아키텍처 게이트로 계속 검증해야 한다.
+문서의 경로뿐 아니라 해당 테스트와 아키텍처 게이트로 계속 검증해야 한다.
 
 ## 2. 결론
 
@@ -33,13 +33,13 @@
 
 특히 다음은 선행 해결이 필요하다.
 
-1. React 화면이 호출할 application input API와 런타임 주입 경계
+RP-01~RP-05에서 TypeScript 도구 안전망, application runtime 주입,
-2. TanStack Query를 사용하는 표준 query/mutation inbound adapter
+query/mutation inbound adapter, HTTP 실행 계약과 executable route/release
-3. TypeScript 전환 전에 TS 파일까지 검사하도록 만드는 도구 안전망
+recovery 계약, 제거 가능한 reference 수직 슬라이스는 구현됐다. 현재 선행 해결
-4. path/query/body projection과 runtime timeout/retry가 정확히 연결된 HTTP 계층
+대상은 다음과 같다.
-5. 선언과 실행이 일치하는 typed route 계약
+
-6. 전체를 제거할 수 있는 실제 reference feature
+1. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치
-7. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치
+2. 국제화, diagnostics, optional adapter recipe와 심화 품질 게이트
 
 따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
 더 정확한 표현은 다음과 같다.
@@ -63,16 +63,16 @@
 | --- | --- | --- | --- |
 | 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
 | 계층 의존 방향 | 부분 준비 | `.dependency-cruiser.cjs`, `src/application/ports` | inbound/outbound 명명과 `contracts` 소유권까지 집행 |
-| application facade | 부분 준비 | `create-application.js`는 있으나 `main.jsx`에서 우회 | UI에는 input API만 주입 |
+| application facade | 준비됨 | typed input/output catalog, provider, production composition test | feature input use case를 contribution으로 확장 |
-| HTTP client | 부분 준비 | timeout, abort, retry, auth, envelope, Zod가 존재 | path/query, parsed body, runtime 설정, 정리 로직 보완 |
+| HTTP client | 준비됨 | path/search/body projection, runtime timeout/retry, abort/cleanup test | feature gateway 뒤에서 사용 |
-| retry | 부분 준비 | safe/keyed 요청 정책 존재 | retry 소유자 단일화, 설정 연결, telemetry |
+| retry | 준비됨 | HTTP 단일 소유, runtime max attempts, Query retry off | RP-09에서 telemetry 연결 |
 | 오류 모델 | 부분 준비 | error registry와 normalization 존재 | typed discriminated union과 계층별 mapper |
-| 검증 | 부분 준비 | runtime/API Zod 존재 | route/form/domain 경계를 분리하고 실제 parse 결과 사용 |
+| 검증 | 부분 준비 | runtime/API Zod parse 결과를 실제 request에 사용 | route/form/domain 경계를 추가 |
 | 인증 연동 | 준비됨/프로젝트 선택 | opaque auth owner와 demo seam 존재 | 인증 방식별 recipe; 기본 token 저장소는 추가하지 않음 |
-| 서버 상태 | 미제공에 가까운 부분 준비 | QueryClientProvider와 cache port는 존재 | query/mutation hook과 화면 reference flow |
+| 서버 상태 | 준비됨 | reference route의 query/mutation, cancellation, stale, optimistic/conflict/rollback | feature별 query contribution recipe 유지 |
 | 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 |
 | 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 |
-| 라우팅 | 부분 준비 | lazy route, access hint, registry 존재 | typed runtime map, codec, recovery, metadata 집행 |
+| 라우팅 | 준비됨 | Data Router, typed runtime map, codec, metadata consumer, bounded chunk recovery | reference feature route와 release E2E로 사용 범위 확장 |
 | 앱 셸·반응형 | 부분 준비 | header/sidebar/content/theme 구현 | 접근 가능한 mobile drawer와 focus 복원 |
 | 페이지 템플릿 | 미제공 | 각 페이지가 직접 레이아웃 조립 | list/detail/form/status 등 슬롯 기반 템플릿 |
 | 디자인 토큰 | 부분 준비 | semantic color/theme 토큰 존재 | typography, spacing, motion, layer 등 3단계 토큰 |
@@ -82,10 +82,10 @@
 | 국제화 | 미제공 | 한국어 문자열·locale이 하드코딩 | typed message/formatter/locale/RTL 경계 |
 | logging/diagnostics | 미제공 | telemetry port는 있으나 logger 없음 | redaction이 적용된 diagnostics/logging 경계 |
 | telemetry | 부분 준비 | registry, queue, redaction 존재 | HTTP·boot·cache·storage·route 사건에 실제 연결 |
-| 비동기 상태 불변식 | 부분 준비 | 공통 model/surface는 있으나 일부 모순 상태를 허용 | query/mutation 상태 조합과 action latch를 닫음 |
+| 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
 | 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 |
 | UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 |
-| 샘플 제거 | 부분 준비 | fixture 제거 테스트 존재 | sample domain/registry/runtime 전체 제거 검증 |
+| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 8단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
 | registry·compatibility 집행 | 부분 준비 | registry와 gate는 있으나 실제 before/after 및 orphan 검사가 제한적 | type/reference/orphan/diff/migration을 자동 검증 |
 | 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 |
 | realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 |
@@ -94,13 +94,12 @@
 
 ### 5.1 P0: 기능 개발을 막는 항목
 
-#### application 계층이 런타임에서 우회된다
+#### RP-02에서 application 런타임 우회 해결
 
-`src/bootstrap/composition-root.js`는 application을 생성하지만
+`src/bootstrap/composition-root.js`가 만든 typed application input API는
-`src/bootstrap/main.jsx`는 이를 라우터에 주입하지 않는다. UI에는 auth, storage,
+production `ApplicationProvider`에 주입된다. raw auth, storage, telemetry와
-telemetry 같은 raw outbound dependency와 concrete QueryClient가 전달된다.
+release port는 closure 안에 남고 UI는 session, preference, diagnostics와 runtime
-`src/application/create-application.js`도 use case 중심 input API보다 outbound
+query만 사용한다.
-capability를 다시 노출하는 형태다.
 
 목표 상태:
 
@@ -110,12 +109,13 @@ capability를 다시 노출하는 형태다.
 - bootstrap만 concrete outbound adapter를 알고 조합한다.
 - 실제 bootstrap부터 reference page까지 연결한 통합 테스트가 있다.
 
-#### 서버 상태 라이브러리는 마운트됐지만 사용할 수 없다
+#### RP-03에서 표준 서버 상태 bridge 구현
 
-`QueryClientProvider`는 존재하지만 저장소의 제품 코드에서 `useQuery`와
+`src/presentation/adapters/query` 한 경계만 `@tanstack/**`를 import한다.
-`useMutation`을 사용하지 않는다. 동시에 presentation의 `@tanstack/**` import는
+`useApplicationQuery`와 `useApplicationMutation`은 application result를 React
-금지돼 있다. 현재 `QueryCachePort`는 명령형 read/write/invalidate만 제공하여
+lifecycle에 연결하며 cancellation, stale failure, duplicate submit, optimistic
-React 구독, 요청 상태, cancellation, optimistic update를 대신할 수 없다.
+rollback, conflict resolution과 invalidation을 검증한다. 다른 presentation
+경로의 직접 TanStack import는 negative fixture가 거절한다.
 
 목표 상태:
 
@@ -128,7 +128,7 @@ React 구독, 요청 상태, cancellation, optimistic update를 대신할 수
 - loading, empty, refreshing, stale, offline, error, conflict, optimistic rollback을
   reference feature에서 보여 준다.
 
-#### TypeScript 전환 전에 검사 도구가 TS를 인식해야 한다
+#### RP-01에서 TypeScript 검사 도구 안전망 구현
 
 현재 source는 모두 JS/JSX이고 `strict + allowJs + checkJs`를 사용한다. 이는 좋은
 중간 안전망이지만 다음 도구는 TS migration을 그대로 따라가지 못한다.
@@ -143,31 +143,29 @@ TypeScript 전환은
 [TypeScript의 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
 처럼 점진적으로 진행하되, 이 저장소에서는 tooling glob과 CI를 먼저 고쳐야 한다.
 
-#### HTTP 계약에 선언과 실행의 차이가 있다
+#### RP-03에서 HTTP 선언과 실행의 차이 해결
 
-현재 HTTP 계층은 공통화 수준이 높지만 다음 정확성 문제가 남아 있다.
+HTTP request builder는 path segment escaping, canonical optional/array search,
-
+Zod default/trim 결과의 실제 query/body 전송을 담당한다. runtime timeout과
-- runtime config의 `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS`가 client 생성에
+0/1/N max retry가 client factory에 주입되고 caller abort와 timeout을 다른 typed
-  전달되지 않는다.
+failure로 투영한다. validation 조기 반환은 fetch/timer 0회이며 success, schema
-- operation path에 path parameter와 search parameter를 투영하는 표준 builder가
+failure, abort, timeout과 exhausted retry는 scheduler/listener cleanup을
-  없다.
+검증한다. HTTP 사건의 semantic telemetry 연결은 RP-09 범위다.
-- sample filter는 cache key에만 반영되고 실제 요청 URL에는 반영되지 않는다.
-- Zod의 parsed/transformed request body 대신 원본 body를 전송한다.
-- request validation의 조기 반환 경로에서 timeout/listener 정리가 늦어진다.
-- HTTP failure, retry, recovery가 telemetry 사건과 이어지지 않는다.
 
 client를 거대한 범용 함수로 계속 확장하지 말고 transport, request builder, auth,
 timeout, retry, decoder, mapper 책임을 분리해야 한다. application에는 범용 HTTP
 메서드보다 feature가 요구하는 gateway interface를 노출한다.
 
-#### route registry가 실행 계약이 아니다
+#### RP-04에서 route registry를 실행 계약으로 전환
 
-route registry에는 `paramsSchema`, `searchSchema`, `loadingSurface`,
+platform route 계약과 `src/features/installed-feature-contracts.js`의 직렬화
-`errorSurface`, `chunkId`가 있지만 실제 router tree, lazy module, navigation
+가능한 contribution을 기준으로
-목록은 별도로 작성된다. 여러 필드는 선언만 되고 런타임에 사용되지 않는다.
+`src/presentation/routes/app-router.tsx`가 Data Router route object와
-chunk recovery use case와 redirect loop guard도 실제 route flow에 연결되지 않는다.
+navigation을 생성한다. `route-runtime.tsx`는 lazy component의 실행 map만
+소유하며 contract/runtime 누락과 orphan은 TypeScript negative fixture와 registry
+gate가 모두 거절한다.
 
-목표 상태:
+현재 보장:
 
 - serializable contract와 executable runtime map을 분리한다.
 - `satisfies Record<RouteId, RouteRuntime>`로 양방향 완전성을 검사한다.
@@ -175,19 +173,23 @@ chunk recovery use case와 redirect loop guard도 실제 route flow에 연결되
   사용한다.
 - loading/error/chunk/access/title/navigation metadata를 실제 route object에
   연결한다.
-- route change 시 boundary reset, focus, scroll, navigation cancellation을
+- route change 시 boundary reset, title, focus와 scroll을 검증한다.
-  검증한다.
+- Vite manifest의 실제 dynamic entry와 route chunk ID를 release manifest에
+  연결하고, no-store manifest 재조회와 build/release 쌍별 1회 reload를
+  production application input까지 연결한다.
 
-#### reference feature가 완전히 제거되지 않는다
+#### RP-05에서 제거 가능한 reference feature 구현
 
-현재 sample removal gate는 `src/sample/contract-fixture`만 삭제한다. sample API
+`src/features/reference-feature`가 domain, application input, outbound gateway,
-operation, schema, mapper, domain model, query key는 다른 production 경로에 남는다.
+DTO/schema, mapper, route/API/query contract, query/mutation controller와 page를
-반면 화면에 노출된 `/sample/resources`는 실제 query 수직 흐름을 실행하지 않는다.
+한 소유 경계에 둔다. production composition은 generic feature input catalog를
+통해 이 input을 주입하며 UI는 HTTP나 output port를 직접 보지 않는다.
 
-reference feature는 domain, application input/output, schemas, operation,
+`test:sample-removal`은 임시 복제본에서 feature source/tests를 삭제하고 installed
-mapper, query controller, pages, tests를 한 소유 경계 아래 모아야 한다. 해당 모듈과
+contract/runtime/adapter catalog를 빈 목록으로 재생성한다. 그 뒤 typecheck,
-registry contribution을 제거한 뒤 typecheck, architecture, test, build가 모두
+architecture, registry, unit/integration, home smoke, build와 fixture ID 잔여
-통과해야 “제거 가능”으로 판정한다.
+0개를 검사한다. 설치 모드에서는 MSW를 사용한 bootstrap → router → application
+→ HTTP → schema → mapper → query cache → page 수직 테스트가 실행된다.
 
 #### 비동기·복구 상태의 불변식이 닫혀 있지 않다
 
@@ -208,9 +210,11 @@ mutation-pending
 mutation-conflict
 ```
 
-chunk recovery와 release coherence도 policy 함수가 존재하는 것으로 완료되지
+RP-04에서 lazy import failure는 `ChunkRecoveryBoundary` → application recovery
-않는다. 실제 lazy import failure가 manifest 재확인, build 비교, 단 한 번의 guarded
+input → `ReleaseInfoPort.refresh()`의 no-store manifest 조회 → build/release 쌍
-reload, 반복 실패 지원 표면까지 이어지고 E2E로 검증되어야 한다.
+guard → browser navigation adapter의 1회 reload로 연결됐다. 일반 render
+failure는 이 경로에서 제외되고, 반복 실패·offline·malformed manifest·storage
+실패는 지원 표면으로 fail-closed된다.
 
 #### telemetry, registry, 공급망 gate의 실행 깊이가 부족하다
 
@@ -382,7 +386,8 @@ tree-shakable SVG icon source로 적절하지만 select, dialog, menu, focus man
 - TS source와 test 전체 typecheck
 - 실제 composition root부터 page까지의 통합
 - query/mutation controller와 optimistic rollback
-- route registry/runtime map 정합성
+- route registry/runtime map 정합성은 RP-04에서 unit, component, negative
+  registry/type fixture와 built artifact 검증으로 구현됨
 - runtime timeout/retry와 path/query/parsed body
 - shared MSW scenario catalog
 - isolated component stories와 interaction test

docs/architecture/frontend-ports-adapters-and-boundaries.md

@@ -116,7 +116,7 @@ bootstrap은 page별 orchestration이나 업무 규칙을 소유하지 않는다
 | `src/adapters` | HTTP, auth, storage, cache, telemetry 구현 | outbound adapter |
 | `src/bootstrap` | runtime config와 구현 조립 | 유일한 composition root |
 | `src/contracts` | 여러 계층의 registry가 혼재 | 소유 계층으로 분산 |
-| `src/sample` | 제거 가능한 예제 일부 | 완전한 removable reference feature |
+| `src/features/reference-feature` | 완전한 제거 가능 수직 예제 | installed contribution과 8단계 제거 gate 유지 |
 
 현재 구조가 잘 제공하는 기반은 다음과 같다.
 
@@ -141,17 +141,27 @@ RP-02 구현으로 다음 경계는 실행 경로에 연결됐다.
 - presentation의 direct fetch/browser storage/concrete adapter/TanStack import와
   application의 React/concrete adapter import는 negative fixture가 거절한다.
 
-후속 브랜치에서 닫아야 할 실행 불일치는 다음과 같다.
+RP-03 구현으로 HTTP와 server-state 경계도 다음처럼 연결됐다.
 
-1. `QueryClientProvider`는 존재하지만 실제 product route에서
+- `src/presentation/adapters/query`만 TanStack Query import를 허용하며
-   `useQuery` 또는 `useMutation`을 연결하는 query bridge가 없다.
+  application query/mutation을 cancellation, invalidation, deduplication,
-2. route registry의 `paramsSchema`, `searchSchema`, `loadingSurface`,
+  optimistic rollback과 conflict 해제에 연결한다.
-   `errorSurface`, `chunkId` 일부는 실행 route와 연결되지 않았다.
+- HTTP request builder는 path escaping과 canonical search를 소유하고 Zod가
-3. 제거 테스트는 `src/sample/contract-fixture`만 제거하며, sample API
+  변환한 search/body를 실제 request에 사용한다.
-   operation, Zod schema, mapper, domain model과 query key는 다른 경로에
+- runtime timeout과 max retry attempts가 transport factory에 주입되며
-   남는다.
+  validation, success, abort, timeout과 exhausted retry의 timer/listener
-4. runtime의 `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS`는 검증되지만
+  정리를 테스트한다.
-   concrete HTTP client 구성에 전달되지 않는다.
+- HTTP가 자동 network retry를 소유하고 query/mutation adapter의 vendor retry는
+  비활성화한다.
+
+RP-04에서 route 실행 불일치는 닫혔다. route registry와 runtime map은
+Data Router tree, codec, surface, title, navigation, chunk/release recovery의
+단일 조립 입력이며 registry/type/build 검증이 누락과 orphan을 거절한다.
+
+RP-05에서 두 번째 불일치도 닫혔다. feature별 domain/application/adapter/
+contract/presentation은 `src/features/reference-feature`가 소유하고, generic
+installed catalog만 bootstrap과 router에 노출된다. 제거 gate는 feature와 test를
+삭제한 복제본에서 전체 P0 경로를 다시 실행한다.
 
 이 문서의 목표 구조는 기존 기반을 폐기하는 것이 아니라 이러한
 불일치를 제거하는 것이다.
@@ -1203,19 +1213,19 @@ contract와 실패 분기를 우선한다.
 
 ### 26.4 Routing과 상태
 
-- [ ] route registry와 실행 route tree가 동일 source에서 생성된다.
+- [x] route registry와 실행 route tree가 동일 source에서 생성된다.
-- [ ] params/search schema가 실제 navigation에서 실행된다.
+- [x] params/search schema가 실제 navigation에서 실행된다.
-- [ ] loading/error/chunk/access metadata가 실행 behavior와 연결된다.
+- [x] loading/error/chunk/access metadata가 실행 behavior와 연결된다.
 - [ ] local, URL, server, session, persisted state가 분류 규칙을 따른다.
 - [ ] server state를 별도 global store에 중복 보관하지 않는다.
 
 ### 26.5 Reference feature
 
-- [ ] route부터 API mapper와 화면까지 완전한 수직 경로가 실행된다.
+- [x] route부터 API mapper와 화면까지 완전한 수직 경로가 실행된다.
-- [ ] list/create 등 최소 query와 mutation 예제가 있다.
+- [x] list/create 등 최소 query와 mutation 예제가 있다.
-- [ ] loading/empty/error/refresh/conflict 상태가 있다.
+- [x] loading/empty/error/refresh/conflict 상태가 있다.
-- [ ] reference feature 전체 삭제 후 typecheck/test/build가 통과한다.
+- [x] reference feature 전체 삭제 후 typecheck/architecture/registry/test/home/build가 통과한다.
-- [ ] built asset에 reference operation, schema, mapper가 남지 않는다.
+- [x] 제거 모드 built asset에 reference operation, schema, mapper가 남지 않는다.
 
 ### 26.6 품질
 

docs/architecture/overview.md

@@ -44,12 +44,13 @@ flowchart LR
 The current executable route tree is mounted only after runtime configuration
 and release-manifest coherence pass. It receives the composed query client,
 credential-opaque session port, storage port, telemetry port, and immutable
-build ID. Visible starter pages do not depend on the removable sample fixture.
+build ID. Generic starter pages do not depend on the removable reference
+feature.
 
 This describes the current starter composition, not the completed target. The
 capability review found that raw outbound capabilities still reach the React
 tree, the composed application facade is not yet its entry point, and several
-route, HTTP, recovery, telemetry, and sample-removal contracts are only
+route, HTTP, recovery, telemetry, and reference-feature removal contracts are only
 partially connected. Use the following documents for the evidence and migration
 plan:
 

docs/architecture/routing-pages-and-patterns.md

@@ -14,24 +14,22 @@
 
 ## 2. 현재 상태와 문제
 
-현재 구현에는 다음 장점이 있다.
+RP-04 이후 현재 구현에는 다음 장점이 있다.
 
 - route registry가 path와 access policy를 소유한다.
-- route component를 lazy import한다.
+- contract에서 Data Router route object와 navigation을 생성한다.
+- runtime map이 route component를 lazy import하고 codec을 연결한다.
 - 앱 셸과 보호 route, not-found surface가 있다.
 - route heading focus와 비동기/render error boundary가 있다.
-- redirect loop와 chunk recovery에 대한 policy 함수가 일부 존재한다.
+- redirect loop와 chunk recovery가 bounded production call graph에 연결돼 있다.
 
-하지만 `src/contracts/routes.js`의 metadata와
+platform route 계약, `src/features/installed-feature-contracts.js`,
-`src/presentation/routes/app-router.jsx`의 executable route tree가 별도 수동 목록이다.
+`src/features/installed-feature-runtimes.tsx`의 완전성은 TypeScript와 registry
-그 결과 다음 필드는 선언돼도 실제 행동을 보장하지 않는다.
+negative fixture가 함께 검사한다. params/search codec, loading/error surface,
-
+access, title, navigation, chunk ID는
-- params/search schema
+`src/presentation/routes/app-router.tsx`에서 모두 소비된다. built Vite
-- loading/error surface
+manifest의 dynamic entry는 release manifest route chunk map과 검증되며,
-- chunk ID
+`ChunkRecoveryBoundary`는 일반 render error와 chunk rejection을 분리한다.
-- route title/navigation label
-- redirect loop guard
-- chunk recovery policy
 
 페이지도 공통 `PageHeader` 외에는 각자 section과 class를 직접 조립한다. 목록,
 상세, 편집, 오류 페이지의 반복되는 접근성·반응형·상태 표면을 기능 팀이 다시
@@ -50,15 +48,14 @@ selector를 `7.18.1`로 맞춰 확인한다.
 
 | mode | 선택 조건 | 이 저장소에서의 판단 |
 | --- | --- | --- |
-| Declarative | React composition과 외부 data layer가 route data를 소유 | 현재 구현이 사용 중인 기준선 |
+| Declarative | React composition과 외부 data layer가 route data를 소유 | RP-04 이전 기준선 |
-| Data | route object, blocker, scroll restoration, pending/navigation state가 필요 | 목표 skeleton의 navigation lifecycle에 적합 |
+| Data | route object, blocker, scroll restoration, pending/navigation state가 필요 | VD-03으로 채택하고 RP-04에서 구현 |
 | Framework | route module, type-safe href, code splitting, SSR/static 전략을 framework가 소유 | client-only skeleton 기본값으로는 범위가 큼 |
 
-목표 결정:
+채택한 결정:
 
 - client-only SPA와 TanStack Query/application use case를 유지한다.
-- 현재 `BrowserRouter` 기반 Declarative Mode에서 `createBrowserRouter`와
+- `createBrowserRouter`와 `RouterProvider` 기반 Data Mode를 사용한다.
-  `RouterProvider` 기반 Data Mode로 이동한다.
 - Data Mode를 선택하는 이유는 route object, navigation blocker, scroll
   restoration, route error 경계를 일관되게 소유하기 위해서다. loader/action으로
   서버 상태를 다시 소유하기 위해서가 아니다.
@@ -68,8 +65,9 @@ selector를 `7.18.1`로 맞춰 확인한다.
 - SSR/static generation을 선택하기 전에는 Framework Mode를 기본값으로 만들지
   않는다.
 
-전환 브랜치 전까지 현재 Declarative router에 새 custom scroll/blocker
+결정 근거와 rollback 경계는
-implementation을 추가하지 않는다. 전환할 수 없는 프로젝트만 별도 ADR과
+`docs/architecture/decisions/VD-03-react-router-data-mode.md`에 고정한다.
+Data Mode를 사용할 수 없는 프로젝트만 별도 ADR과
 `NavigationLifecycleAdapter`를 구현한다.
 
 ## 4. route 계약과 runtime map

docs/architecture/starter-experience.md

@@ -11,7 +11,8 @@ primitives, and state surfaces remain reusable.
 validated config + coherent release manifest
   -> concrete adapters
   -> QueryClientProvider
-  -> BrowserRouter
+  -> ApplicationProvider
+  -> RouterProvider
   -> ThemeProvider
   -> SessionProvider
   -> AppShell
@@ -31,7 +32,7 @@ remain stable in the shell.
 | `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
 | `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
 | `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
-| `SAMPLE_RESOURCE_LIST` | `/sample/resources` | integration-defined | protected integration seam |
+| `REFERENCE_RESOURCE_LIST` | `/examples/reference-resources` | integration-defined | removable vertical slice |
 | `NOT_FOUND` | `*` | public | safe navigation recovery |
 
 Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
@@ -54,24 +55,25 @@ An external owner implements `readState`, `subscribe`, `beginSignIn`,
 
 ## Extending the starter
 
-The steps below describe the current extension path. The platform review found
+The steps below describe the current extension path. New platform work should follow
-that several route metadata fields and the composed application facade are not
-yet connected end to end. New platform work should follow
 [routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
 and the
 [TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
 rather than adding another independent route or data-loading convention.
 
-1. Register the route path, access hint, title, chunk, loading surface, error
+1. Add a serializable contribution under the feature ownership boundary and
-   surface, and optional navigation metadata in `src/contracts/routes.js`.
+   install it through `src/features/installed-feature-contracts.js`.
-2. Add a lazy page in `src/presentation/` and render it through `RouteSurface`.
+2. Add the lazy component and route codecs through
-3. Use application ports or use cases; do not import concrete adapters.
+   `src/features/installed-feature-runtimes.tsx`.
+3. Compose feature application inputs and outbound gateways only through
+   `src/features/installed-feature-adapters.ts`.
 4. Use the semantic tokens, UI primitives, and state surfaces before adding a
    project-specific variant.
 5. Add component behavior, all-engine E2E, automated axe, and signed manual
    route evidence.
-6. Run `test:sample-removal` to prove the visible starter still builds without
+6. Run `test:sample-removal` to prove the generic starter typechecks, passes
-   `src/sample/contract-fixture`.
+   architecture/registry/tests/home smoke, and builds without the complete
+   reference feature.
 
 Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
 tokens and other secrets remain forbidden storage keys.

docs/architecture/typescript-state-and-data-flow.md

@@ -387,6 +387,20 @@ retry 조건:
 timer와 event listener는 성공, 실패, validation 조기 반환, external abort 모든
 경로에서 정리되어야 한다.
 
+RP-03의 현재 구현은 다음 계약을 자동 검증한다.
+
+- `request-builder.ts`가 path 값을 escape하고 search key를 정렬하며 array 순서를
+  보존한다.
+- operation의 `requestSource`가 search/body schema를 선택하고 Zod의
+  default/trim 결과만 URL 또는 JSON payload에 전달한다.
+- runtime `REQUEST_TIMEOUT_MS`와 `MAX_RETRY_ATTEMPTS`가 transport factory에
+  주입된다.
+- query adapter의 자동 retry는 끄고 HTTP만 bounded network retry를 소유한다.
+- `AsyncOverlay`는 refreshing/stale-degraded/mutation-pending/
+  mutation-conflict를 TypeScript union으로 배타화한다.
+- `useApplicationQuery`와 `useApplicationMutation`은 cancellation, stale latch,
+  duplicate submit, optimistic rollback, conflict resolution을 제공한다.
+
 ## 6. 인증과 token 소유권
 
 기본 skeleton은 token manager를 제공하지 않는다.

docs/styling/design-tokens.md

@@ -37,8 +37,9 @@ Arbitrary-value policy:
 - user-controlled or runtime-composed class strings are forbidden
 - class variants must be selected from a closed static map
 
-The removable sample may demonstrate tokens, but production starter modules do
+The removable reference feature may demonstrate tokens, but generic production
-not import from `src/sample/contract-fixture`.
+starter modules do not import its domain, application, adapter, or presentation
+implementation.
 
 This file documents the currently implemented token and primitive baseline.
 The [design-system platform contract](./design-system-platform.md) defines the

docs/testing/frontend-platform-testing-strategy.md

@@ -91,12 +91,14 @@ Vitest의 변환 성공을 TypeScript typecheck의 대체물로 취급하지 않
 - boot error shell의 safe metadata
 - StrictMode와 unmount cleanup
 
-#### TanStack Query의 React integration test가 없다
+#### TanStack Query의 React integration test 기반
 
-Query cache adapter의 명령형 `read/write/invalidate` unit test는 있지만
+`tests/component/application-query.test.jsx`는 production query inbound
-`useQuery`, `useMutation`, cancellation, stale/background refresh, optimistic
+adapter의 query/mutation lifecycle을 검증한다. cancellation, initial terminal
-rollback을 사용하는 production presentation adapter가 아직 없다. 따라서 query
+failure, background stale-failure latch와 retry 복구, duplicate submit,
-provider가 마운트되어도 React 사용자의 실제 상태 전환은 검증되지 않는다.
+optimistic commit/rollback, conflict 해제와 namespace invalidation이 실제
+QueryClient 위에서 실행된다. HTTP 자동 retry가 소유자이므로 이 adapter의
+query/mutation vendor retry는 꺼져 있다.
 
 #### Form 테스트가 단일 TextField 흐름에 머문다
 
@@ -368,10 +370,9 @@ QueryClientProvider
           -> AppShell
 ```
 
-04 routing branch에서 Data Mode로 전환할 때 `BrowserRouter`를
+RP-04에서 `RouterProvider` 기반 Data Mode로 전환했다. router component test와
-`RouterProvider`로 바꾸고 테스트 fixture도 같은 composition factory에서
+runtime composition test는 production `AppRouter`와 composition 함수를 사용하며,
-생성한다. 문서에 적힌 provider 순서를 테스트 전용 shell로 재현하지 말고
+문서에 적힌 provider 순서를 테스트 전용 shell로 재현하지 않는다.
-production composition 함수를 호출한다.
 
 ### 6.3 Boot E2E
 
@@ -445,6 +446,14 @@ tests/support/query/
 helper는 production default를 복사하지 않는다. production factory를 호출하고
 필요한 시간·retry만 test override로 주입한다.
 
+RP-05의 executable reference matrix는
+`tests/features/reference-feature`에 모여 있다. 설치 모드에서는 URL codec과
+query key/HTTP search의 동일성, DTO 차단, loading/success/empty/terminal,
+refreshing/stale, pending/duplicate/optimistic/conflict/rollback과 MSW production
+composition을 검증한다. 제거 모드는 feature source/tests와 installed
+contract/runtime/adapter contribution을 제거한 복제본에서 P0 gate와 built asset
+잔여 0개를 다시 검증한다.
+
 ## 8. Form 테스트
 
 Form test는 field primitive, form controller, application command mapping을
@@ -1271,7 +1280,8 @@ CI registry에 추가한다.
 3. MSW handlers/scenario/factory를 중앙 catalog로 이동한다.
 4. query/mutation presentation adapter와 integration harness를 만든다.
 5. form foundation과 form/controller test matrix를 만든다.
-6. route registry/runtime map contract와 built-dist E2E를 추가한다.
+6. route registry/runtime map contract와 built-dist artifact 검증을 유지하고,
+   release server를 사용하는 built-dist E2E까지 확장한다.
 7. Storybook build, interaction, a11y gate를 추가한다.
 8. pinned Chromium visual baseline을 추가한다.
 9. critical flow의 3-engine release profile을 분리한다.

eslint.config.js

@@ -176,12 +176,82 @@ export default [
       ],
     },
   },
+  {
+    files: [
+      `src/presentation/adapters/query/**/*.${sourceExtensions}`,
+    ],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/adapters/http/**",
+        "**/adapters/storage/**",
+        "**/adapters/auth/**",
+        "**/bootstrap/**",
+        "**/application/ports/out/**",
+      ]),
+    },
+  },
   {
     files: [`src/adapters/**/*.${sourceExtensions}`],
     rules: {
       "no-restricted-imports": restrictedImports(layerPatterns.adapters),
     },
   },
+  {
+    files: [`src/features/*/domain/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.domain),
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/application/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports(layerPatterns.application),
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/presentation/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/features/*/adapters/**",
+        "**/adapters/http/**",
+        "**/adapters/storage/**",
+        "**/adapters/auth/**",
+        "**/bootstrap/**",
+        "**/application/ports/out/**",
+        "@tanstack/**",
+      ]),
+      "no-restricted-globals": [
+        "error",
+        "fetch",
+        "localStorage",
+        "sessionStorage",
+      ],
+    },
+  },
+  {
+    files: [`src/features/*/adapters/**/*.${sourceExtensions}`],
+    rules: {
+      "no-restricted-imports": restrictedImports([
+        "**/presentation/**",
+        "**/bootstrap/**",
+        "@tanstack/**",
+      ]),
+    },
+  },
   {
     files: [`tests/**/*.${sourceExtensions}`],
     languageOptions: {

package.json

@@ -24,6 +24,8 @@
     "check:types:fixture:ts-result": "tsc --ignoreConfig --strict --noEmit --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-result-narrowing.ts",
     "check:types:fixture:application-output": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-application-output.ts",
     "check:types:fixture:application-input": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-application-input.ts",
+    "check:types:fixture:async-overlay": "tsc --ignoreConfig --allowJs --checkJs --strict --noEmit --skipLibCheck --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-async-overlay.ts",
+    "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",
     "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",
@@ -32,13 +34,15 @@
     "test:a11y": "playwright test --grep @a11y && node scripts/write-a11y-report.mjs",
     "review:a11y-manual": "node scripts/verify-a11y-manual.mjs",
     "test:sample-removal": "node scripts/test-sample-removal.mjs",
-    "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration",
+    "test:reference-feature": "vitest run tests/features/reference-feature --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/reference-feature.xml --passWithNoTests",
+    "test:all": "corepack pnpm test:runtime-schema && corepack pnpm test:unit && corepack pnpm test:component && corepack pnpm test:integration && corepack pnpm test:reference-feature",
     "verify:lockfile": "corepack pnpm install --frozen-lockfile",
     "generate:supply-chain": "node scripts/generate-supply-chain.mjs",
     "scan:security": "node scripts/security-scan.mjs",
     "check:browser-security": "node scripts/check-browser-security.mjs",
     "check:registries": "node scripts/check-registries.mjs",
     "check:registries:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
+    "check:routes:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/routes/governance.json --artifact artifacts/quality/route-registry-fixture.json",
     "verify:compatibility": "node scripts/check-compatibility.mjs",
     "verify:release": "node scripts/verify-release.mjs",
     "verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",

public/release-manifest.json

@@ -7,5 +7,13 @@
   "apiContractVersion": "1",
   "assetManifestHash": "generated-during-build",
   "releaseId": "local-release",
-  "builtAt": "1970-01-01T00:00:00.000Z"
+  "builtAt": "1970-01-01T00:00:00.000Z",
+  "routeChunks": {
+    "route-home": "src/presentation/pages/home-page.jsx",
+    "route-examples-ui": "src/presentation/examples/ui-gallery-page.jsx",
+    "route-examples-states": "src/presentation/examples/state-gallery-page.jsx",
+    "route-examples-auth": "src/presentation/examples/auth-example-page.jsx",
+    "route-reference-resources": "src/features/reference-feature/presentation/reference-resource-page.tsx",
+    "route-not-found": "src/presentation/pages/not-found-page.jsx"
+  }
 }

scripts/check-registries.mjs

@@ -103,6 +103,24 @@ for (const specification of governance.registries) {
     }
   }
 
+  for (const [field, allowed] of Object.entries(
+    specification.allowedValues ?? {},
+  )) {
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      if (
+        !allowed.some(
+          /** @param {unknown} value */
+          (value) => Object.is(value, row[field]),
+        )
+      ) {
+        failures.push(
+          `${specification.registryId}.${rowName}.${field} has unknown value ${String(row[field])}`,
+        );
+      }
+    }
+  }
+
   snapshots.push({
     registryId: specification.registryId,
     owner: specification.owner,

scripts/drill-runbook.mjs

@@ -123,6 +123,8 @@ async function drillChunkMismatch() {
     failureKind: "DEPLOY_MISMATCH",
     manifestLoaded: true,
     currentBuildId: "build-a",
+    currentReleaseId: "release-a",
+    activeBuildId: "build-b",
     activeReleaseId: "release-b",
     storage,
   };

scripts/generate-build-manifest.mjs

@@ -1,6 +1,13 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import process from "node:process";
+import { z } from "zod";
+
+import {
+  ROUTE_REGISTRY,
+  ROUTE_RUNTIME_CONTRACT,
+} from "../src/features/installed-feature-contracts.js";
+import { runtimeConfigSchema } from "../src/bootstrap/runtime-config-schema.js";
 
 const packageJson = JSON.parse(await readFile("package.json", "utf8"));
 const packageManagerVersion = packageJson.packageManager.split("@").at(-1);
@@ -9,11 +16,31 @@ const commitSha = process.env.VITE_COMMIT_SHA ?? "local";
 const releaseId = process.env.RELEASE_ID ?? "local-release";
 const runnerImage = process.env.CI_RUNNER_IMAGE ?? `${process.platform}-${process.arch}`;
 const builtAt = new Date().toISOString();
-const viteManifest = await readFile("dist/.vite/manifest.json");
+const viteManifest = await readFile("dist/.vite/manifest.json", "utf8");
+const viteManifestObject =
+  /** @type {Record<string, {file: string, name?: string, isDynamicEntry?: boolean}>} */ (
+    JSON.parse(viteManifest)
+  );
 const assetManifestHash = createHash("sha256")
   .update(viteManifest)
   .digest("hex");
 const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
+/** @type {Record<string, string>} */
+const routeChunks = {};
+for (const definition of Object.values(ROUTE_REGISTRY)) {
+  const runtime =
+    /** @type {Record<string, {moduleId: string}>} */ (
+      ROUTE_RUNTIME_CONTRACT
+    )[definition.routeId];
+  const asset = Object.values(viteManifestObject).find(
+    (entry) => entry.name === runtime?.moduleId && entry.isDynamicEntry,
+  );
+  if (!runtime || !asset?.file) {
+    throw new Error(`Missing built route chunk: ${definition.routeId}`);
+  }
+  routeChunks[definition.chunkId] = asset.file;
+}
+const runtimeConfigJsonSchema = z.toJSONSchema(runtimeConfigSchema);
 
 runtimeConfig.BUILD_ID = buildId;
 runtimeConfig.RELEASE_ID = releaseId;
@@ -31,6 +58,8 @@ const manifest = {
   outputs: {
     directory: "dist",
     viteManifest: "dist/.vite/manifest.json",
+    routeChunks,
+    runtimeConfigSchema: "dist/runtime-config.schema.json",
   },
 };
 
@@ -44,6 +73,7 @@ const releaseManifest = {
   assetManifestHash,
   releaseId,
   builtAt,
+  routeChunks,
 };
 
 await mkdir("artifacts/release", { recursive: true });
@@ -52,6 +82,14 @@ await writeFile(
   "dist/release-manifest.json",
   `${JSON.stringify(releaseManifest, null, 2)}\n`,
 );
+await writeFile(
+  "dist/runtime-config.schema.json",
+  `${JSON.stringify(runtimeConfigJsonSchema, null, 2)}\n`,
+);
+await writeFile(
+  "artifacts/release/runtime-config.schema.json",
+  `${JSON.stringify(runtimeConfigJsonSchema, null, 2)}\n`,
+);
 await writeFile(
   "artifacts/release/build-manifest.json",
   `${JSON.stringify(manifest, null, 2)}\n`,

scripts/lib/manual-a11y-evidence.mjs

@@ -1,11 +1,8 @@
-export const MANUAL_A11Y_ROUTE_IDS = Object.freeze([
+import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
-  "APP_HOME",
+
-  "EXAMPLES_UI",
+export const MANUAL_A11Y_ROUTE_IDS = Object.freeze(
-  "EXAMPLES_STATES",
+  Object.values(ROUTE_REGISTRY).map((route) => route.routeId),
-  "EXAMPLES_AUTH",
+);
-  "SAMPLE_RESOURCE_LIST",
-  "NOT_FOUND",
-]);
 
 const REVIEW_FIELDS = Object.freeze([
   "M1 Keyboard",

scripts/test-performance.mjs

@@ -6,7 +6,7 @@ import process from "node:process";
 import { chromium } from "@playwright/test";
 
 import { evaluateLabBudget } from "../src/application/policies/performance-budgets.js";
-import { ROUTE_REGISTRY } from "../src/contracts/routes.js";
+import { ROUTE_REGISTRY } from "../src/features/installed-feature-contracts.js";
 
 const server = spawn(
   "corepack",
@@ -67,8 +67,9 @@ try {
       }).observe({ type: "layout-shift", buffered: true });
     });
     await page.goto(baseUrl, { waitUntil: "networkidle" });
-    const targetLabel =
+    const targetLabel = Object.values(ROUTE_REGISTRY).find(
-      ROUTE_REGISTRY.SAMPLE_RESOURCE_LIST.navigationLabel;
+      (definition) => definition.access === "integration-defined",
+    )?.navigationLabel;
     if (!targetLabel) {
       throw new Error("Performance route must be present in navigation.");
     }

scripts/test-sample-removal.mjs

@@ -1,78 +1,218 @@
-import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { spawnSync } from "node:child_process";
+import {
+  cp,
+  mkdir,
+  readFile,
+  readdir,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
 import path from "node:path";
 
-const fixtureRoot = path.resolve(".tmp/sample-removal");
+const fixtureRoot = path.resolve(".tmp/reference-feature-removal");
-const sampleRoot = path.resolve("src/sample/contract-fixture");
-const sourceRoot = path.resolve("src");
 const pnpmCli = /** @type {string} */ (process.env.npm_execpath);
+const featureSource = "src/features/reference-feature";
+const featureTests = "tests/features/reference-feature";
+const copyTargets = [
+  "src",
+  "tests",
+  "scripts",
+  "config",
+  "public",
+  "index.html",
+  "package.json",
+  "tsconfig.base.json",
+  "tsconfig.json",
+  "tsconfig.app.json",
+  "tsconfig.node.json",
+  "tsconfig.test.json",
+  "vite.config.js",
+  "vitest.config.js",
+  "playwright.config.js",
+  "eslint.config.js",
+  ".dependency-cruiser.cjs",
+];
+
+const emptyContracts = `import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js";
+import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js";
+
+export const INSTALLED_FEATURE_CONTRACTS =
+  /** @type {readonly unknown[]} */ (Object.freeze([]));
+export const ROUTE_REGISTRY = PLATFORM_ROUTE_REGISTRY;
+export const ROUTE_RUNTIME_CONTRACT = PLATFORM_ROUTE_RUNTIME_CONTRACT;
+export const API_OPERATIONS = Object.freeze({});
+export const QUERY_REGISTRY = Object.freeze({});
+export const NAVIGATION_ROUTES = Object.freeze(
+  Object.values(ROUTE_REGISTRY)
+    .filter((definition) => definition.navigationOrder !== null)
+    .sort(
+      (left, right) =>
+        /** @type {number} */ (left.navigationOrder) -
+        /** @type {number} */ (right.navigationOrder),
+    ),
+);
+/** @param {string} routeId */
+export function getRoute(routeId) {
+  const registry =
+    /** @type {Readonly<Record<string, import("../contracts/routes.js").RouteDefinition>>} */ (
+      ROUTE_REGISTRY
+    );
+  const selected = registry[routeId];
+  if (!selected) throw new Error(\`Unregistered route: \${routeId}\`);
+  return selected;
+}
+/** @param {string} routeId */
+export function routePath(routeId) {
+  return getRoute(routeId).path;
+}
+`;
+
+const emptyRuntimes = `import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.js";
+import { PLATFORM_ROUTE_RUNTIME } from "../presentation/routes/route-runtime.js";
+
+export const ROUTE_CODECS = PLATFORM_ROUTE_CODECS;
+export const ROUTE_RUNTIME = PLATFORM_ROUTE_RUNTIME;
+`;
+
+const emptyAdapters = `type FeatureContext = Readonly<{
+  createHttpClient(contract: Readonly<Record<string, unknown>>): unknown;
+}>;
+export function createInstalledFeatureInputs(_context: FeatureContext) {
+  void _context;
+  return Object.freeze({});
+}
+`;
 
 /** @param {string} directory @returns {Promise<string[]>} */
-async function sourceFiles(directory) {
+async function filesBelow(directory) {
   const entries = await readdir(directory, { withFileTypes: true });
-  const nested = /** @type {string[][]} */ (await Promise.all(
+  const groups = await Promise.all(
     entries.map((entry) => {
       const target = path.join(directory, entry.name);
-      return entry.isDirectory() ? sourceFiles(target) : [target];
+      return entry.isDirectory() ? filesBelow(target) : [target];
     }),
-  ));
+  );
-  return nested.flat();
+  return groups.flat();
+}
+
+/** @param {string} script @param {string[]} [extra] */
+function runPnpm(script, extra = []) {
+  const result = spawnSync(process.execPath, [pnpmCli, script, ...extra], {
+    cwd: fixtureRoot,
+    stdio: "inherit",
+  });
+  return result.status === 0;
 }
 
 await rm(fixtureRoot, { recursive: true, force: true });
 await mkdir(fixtureRoot, { recursive: true });
+for (const target of copyTargets) {
+  await cp(target, path.join(fixtureRoot, target), { recursive: true });
+}
+await symlink(path.resolve("node_modules"), path.join(fixtureRoot, "node_modules"), "dir");
 
-const incomingImports = [];
+await rm(path.join(fixtureRoot, featureSource), {
-for (const sourceFile of await sourceFiles(sourceRoot)) {
+  recursive: true,
-  if (sourceFile.startsWith(sampleRoot)) continue;
+  force: true,
-  const content = await readFile(sourceFile, "utf8");
+});
-  if (/from\s+["'][^"']*sample\/contract-fixture/.test(content)) {
+await rm(path.join(fixtureRoot, featureTests), {
-    incomingImports.push(path.relative(".", sourceFile));
+  recursive: true,
+  force: true,
+});
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-contracts.js"),
+  emptyContracts,
+);
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-runtimes.tsx"),
+  emptyRuntimes,
+);
+await writeFile(
+  path.join(fixtureRoot, "src/features/installed-feature-adapters.ts"),
+  emptyAdapters,
+);
+
+/** @type {string[]} */
+const residue = [];
+for (const root of ["src", "tests"]) {
+  for (const file of await filesBelow(path.join(fixtureRoot, root))) {
+    const relative = path.relative(fixtureRoot, file);
+    const content = await readFile(file, "utf8");
+    if (
+      /REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(
+        `${relative}\n${content}`,
+      )
+    ) {
+      residue.push(relative);
+    }
   }
 }
 
-let buildStatus = 1;
+const checks = [
-if (incomingImports.length === 0) {
+  ["typecheck", runPnpm("check:types")],
-  await cp("src", path.join(fixtureRoot, "src"), {
+  ["architecture", runPnpm("check:architecture")],
-    recursive: true,
+  ["registry", runPnpm("check:registries")],
-    filter: (source) => !source.startsWith(sampleRoot),
+  ["unit-integration", runPnpm("test:all")],
-  });
+  [
-  await cp("public", path.join(fixtureRoot, "public"), { recursive: true });
+    "home-smoke",
-  await cp("index.html", path.join(fixtureRoot, "index.html"));
+    runPnpm("exec", [
-  await cp("vite.config.js", path.join(fixtureRoot, "vite.config.js"));
+      "vitest",
-
+      "run",
-  const result = spawnSync(
+      "tests/component/router.test.jsx",
-    process.execPath,
+      "--reporter=default",
-    [
+    ]),
-      pnpmCli,
+  ],
-      "exec",
+  ["build", runPnpm("build")],
-      "vite",
+];
-      "build",
+/** @type {string[]} */
-      fixtureRoot,
+const builtResidue = [];
-      "--outDir",
+for (const file of await filesBelow(path.join(fixtureRoot, "dist"))) {
-      path.join(fixtureRoot, "dist"),
+  if (!/\.(?:js|css|html|json)$/.test(file)) continue;
-    ],
+  const content = await readFile(file, "utf8");
-    { stdio: "inherit" },
+  if (
-  );
+    /REFERENCE_RESOURCE|reference-feature|reference-resource/i.test(content)
-  buildStatus = result.status ?? 1;
+  ) {
+    builtResidue.push(path.relative(fixtureRoot, file));
+  }
 }
+const routeCatalog = await import(
+  `${new URL(
+    "../src/features/installed-feature-contracts.js",
+    `file://${fixtureRoot}/scripts/`,
+  ).href}?removed=${Date.now()}`
+);
+const routeIds = Object.keys(routeCatalog.ROUTE_REGISTRY);
+const routeAbsent = routeIds.every((routeId) => !routeId.startsWith("REFERENCE_"));
+checks.push(["route-absent", routeAbsent]);
+checks.push(["fixture-id-residue", residue.length === 0]);
+checks.push(["built-fixture-id-residue", builtResidue.length === 0]);
 
+const passed = checks.every(([, result]) => result);
 await mkdir("artifacts/tests", { recursive: true });
-const passed = incomingImports.length === 0 && buildStatus === 0;
 await writeFile(
   "artifacts/tests/sample-removal.xml",
   `<?xml version="1.0" encoding="UTF-8"?>\n` +
-    `<testsuite name="sample-removal" tests="2" failures="${passed ? 0 : 1}">` +
+    `<testsuite name="reference-feature-removal" tests="${checks.length}" failures="${passed ? 0 : 1}">` +
-    `<testcase name="no-product-import"/>` +
+    checks
-    `<testcase name="production-build">${passed ? "" : "<failure/>"}</testcase>` +
+      .map(
+        ([name, result]) =>
+          `<testcase name="${name}">${result ? "" : `<failure>${[...residue, ...builtResidue].join(", ")}</failure>`}</testcase>`,
+      )
+      .join("") +
     `</testsuite>\n`,
 );
 await rm(fixtureRoot, { recursive: true, force: true });
 
 if (!passed) {
+  const failures = checks
+    .filter(([, result]) => !result)
+    .map(([name]) => name);
   process.stderr.write(
-    `Sample removal failed. Incoming imports: ${incomingImports.join(", ")}\n`,
+    `Reference feature removal failed: ${failures.join(", ")}; residue: ${[...residue, ...builtResidue].join(", ")}\n`,
   );
   process.exit(1);
 }
-process.stdout.write("Sample removal smoke: PASS\n");
+process.stdout.write(
+  `Reference feature removal: PASS (${checks.length} checks, no fixture IDs)\n`,
+);

scripts/verify-release.mjs

@@ -6,6 +6,10 @@ import {
   compareReleaseToRuntime,
   RELEASE_TOKEN_REGISTRY,
 } from "../src/contracts/release-tokens.js";
+import {
+  ROUTE_REGISTRY,
+  ROUTE_RUNTIME_CONTRACT,
+} from "../src/features/installed-feature-contracts.js";
 
 const fixturesDocument =
   /** @type {{
@@ -34,7 +38,17 @@ const fixturesDocument =
   );
 const release = JSON.parse(await readFile("dist/release-manifest.json", "utf8"));
 const runtimeConfig = JSON.parse(await readFile("dist/config.json", "utf8"));
-const viteManifest = await readFile("dist/.vite/manifest.json");
+const buildManifest = JSON.parse(
+  await readFile("artifacts/release/build-manifest.json", "utf8"),
+);
+const runtimeConfigJsonSchema = JSON.parse(
+  await readFile("dist/runtime-config.schema.json", "utf8"),
+);
+const viteManifest = await readFile("dist/.vite/manifest.json", "utf8");
+const viteManifestObject =
+  /** @type {Record<string, {file: string, name?: string, isDynamicEntry?: boolean}>} */ (
+    JSON.parse(viteManifest)
+  );
 const actualAssetManifestHash = createHash("sha256")
   .update(viteManifest)
   .digest("hex");
@@ -52,6 +66,58 @@ if (!Number.isFinite(Date.parse(release.builtAt))) {
 if (release.assetManifestHash !== actualAssetManifestHash) {
   artifactMismatches.push("assetManifestContent");
 }
+if (
+  runtimeConfigJsonSchema.$schema !== "https://json-schema.org/draft/2020-12/schema" ||
+  runtimeConfigJsonSchema.type !== "object" ||
+  !runtimeConfigJsonSchema.properties
+) {
+  artifactMismatches.push("runtimeConfigSchema");
+}
+if (
+  buildManifest.outputs?.runtimeConfigSchema !==
+  "dist/runtime-config.schema.json"
+) {
+  artifactMismatches.push("buildManifest:runtimeConfigSchema");
+}
+
+const expectedChunkIds = new Set(
+  Object.values(ROUTE_REGISTRY).map((definition) => definition.chunkId),
+);
+const actualChunkIds = new Set(Object.keys(release.routeChunks ?? {}));
+for (const chunkId of expectedChunkIds) {
+  if (!actualChunkIds.has(chunkId)) {
+    artifactMismatches.push(`routeChunk:missing:${chunkId}`);
+  }
+}
+for (const chunkId of actualChunkIds) {
+  if (!expectedChunkIds.has(chunkId)) {
+    artifactMismatches.push(`routeChunk:orphan:${chunkId}`);
+  }
+}
+for (const definition of Object.values(ROUTE_REGISTRY)) {
+  const runtime =
+    /** @type {Record<string, {moduleId: string}>} */ (
+      ROUTE_RUNTIME_CONTRACT
+    )[definition.routeId];
+  const viteEntry = Object.values(viteManifestObject).find(
+    (entry) => entry.name === runtime?.moduleId && entry.isDynamicEntry,
+  );
+  const routeAsset = release.routeChunks?.[definition.chunkId];
+  if (!runtime || !viteEntry || routeAsset !== viteEntry.file) {
+    artifactMismatches.push(`routeChunk:mismatch:${definition.chunkId}`);
+    continue;
+  }
+  if (
+    buildManifest.outputs?.routeChunks?.[definition.chunkId] !== routeAsset
+  ) {
+    artifactMismatches.push(`buildManifest:routeChunk:${definition.chunkId}`);
+  }
+  try {
+    await readFile(`dist/${routeAsset}`);
+  } catch {
+    artifactMismatches.push(`routeChunk:file:${definition.chunkId}`);
+  }
+}
 
 const fixtures = fixturesDocument.fixtures.map((fixture) => {
   const result = verifyCompatibilityTuple({

src/adapters/http/client.js

@@ -12,6 +12,7 @@ import {
   validateOperationPayload,
   validateOperationRequest,
 } from "./schema-registry.js";
+import { buildRequestTarget } from "./request-builder.js";
 
 const noAuthSession =
   /** @type {import("../../application/ports/auth-session-port.js").AuthSessionPort} */ ({
@@ -22,6 +23,14 @@ const noAuthSession =
 });
 
 /** @typedef {import("../../contracts/errors.js").ApiFailure} HttpFailure */
+/** @typedef {import("./request-builder.js").OperationRequestInput} OperationRequestInput */
+
+/**
+ * @typedef {{
+ *   setTimeout(callback: () => void, milliseconds: number): unknown,
+ *   clearTimeout(handle: unknown): void
+ * }} Scheduler
+ */
 
 /**
  * @typedef {{ ok: true, value: unknown, meta: Record<string, string> } |
@@ -37,8 +46,14 @@ const noAuthSession =
  *   random?: () => number,
  *   validatePayload?: (schemaId: string, value: unknown) =>
  *     { success: true, data: unknown } | { success: false },
+ *   validateRequest?: (schemaId: string, value: unknown) =>
+ *     { success: true, data: unknown } | { success: false },
  *   mapPayload?: (operationId: string, payload: unknown) => unknown,
- *   idempotencyKeyFactory?: () => string
+ *   idempotencyKeyFactory?: () => string,
+ *   timeoutMs?: number,
+ *   maxRetryAttempts?: number,
+ *   scheduler?: Scheduler,
+ *   getOperation?: typeof getApiOperation
  * }} dependencies
  */
 export function createHttpClient(dependencies) {
@@ -48,22 +63,51 @@ export function createHttpClient(dependencies) {
   const random = dependencies.random ?? Math.random;
   const validatePayload =
     dependencies.validatePayload ?? validateOperationPayload;
+  const validateRequest =
+    dependencies.validateRequest ?? validateOperationRequest;
   const mapPayload = dependencies.mapPayload ?? mapOperationPayload;
   const idempotencyKeyFactory =
     dependencies.idempotencyKeyFactory ?? (() => crypto.randomUUID());
+  const defaultTimeoutMs = dependencies.timeoutMs ?? 10_000;
+  const maxRetryAttempts = dependencies.maxRetryAttempts ?? 2;
+  const selectOperation = dependencies.getOperation ?? getApiOperation;
+  const scheduler =
+    dependencies.scheduler ??
+    /** @type {Scheduler} */ ({
+      setTimeout: (callback, milliseconds) =>
+        globalThis.setTimeout(callback, milliseconds),
+      clearTimeout: (handle) =>
+        globalThis.clearTimeout(
+          /** @type {ReturnType<typeof setTimeout>} */ (handle),
+        ),
+    });
 
   /**
-   * @param {string} operationId
+   * @param {string | OperationRequestInput} request
    * @param {{
-   *   body?: unknown,
+ *   body?: unknown,
-   *   routeId?: string,
+ *   routeId?: string,
-   *   signal?: AbortSignal,
+   *   pathParams?: Record<string, string | number>,
-   *   idempotencyKey?: string
+   *   searchParams?: unknown,
-   * }} [input]
+ *   signal?: AbortSignal,
-   * @returns {Promise<HttpResult>}
+ *   idempotencyKey?: string
-   */
+   * }} [legacyInput]
-  async function execute(operationId, input = {}) {
+ * @returns {Promise<HttpResult>}
-    const operation = getApiOperation(operationId);
+ */
+  async function execute(request, legacyInput = {}) {
+    const input =
+      typeof request === "string"
+        ? {
+            operationId: request,
+            routeId: legacyInput.routeId ?? "UNSPECIFIED_ROUTE",
+            pathParams: legacyInput.pathParams,
+            searchParams: legacyInput.searchParams,
+            body: legacyInput.body,
+            signal: legacyInput.signal,
+            idempotencyKey: legacyInput.idempotencyKey,
+          }
+        : request;
+    const operation = selectOperation(input.operationId);
     const logicalIdempotencyKey =
       operation.idempotency === "keyed"
         ? input.idempotencyKey ?? idempotencyKeyFactory()
@@ -105,7 +149,14 @@ export function createHttpClient(dependencies) {
         return outcome;
       }
 
-      if (!shouldRetry(operation, outcome.error, retryCount)) {
+      if (
+        !shouldRetry(
+          operation,
+          outcome.error,
+          retryCount,
+          maxRetryAttempts,
+        )
+      ) {
         return outcome;
       }
 
@@ -117,7 +168,7 @@ export function createHttpClient(dependencies) {
       } catch {
         return {
           ok: false,
-          error: failure("REQUEST_ABORTED", operationId, retryCount, {
+          error: failure("REQUEST_ABORTED", input.operationId, retryCount, {
             code: "REQUEST_ABORTED",
           }),
         };
@@ -128,7 +179,7 @@ export function createHttpClient(dependencies) {
   /**
    * @param {{
    *   operation: ReturnType<typeof getApiOperation>,
-   *   input: { body?: unknown, routeId?: string, signal?: AbortSignal },
+   *   input: OperationRequestInput,
    *   attempt: number,
    *   idempotencyKey?: string
    * }} context
@@ -136,23 +187,19 @@ export function createHttpClient(dependencies) {
    */
   async function performAttempt(context) {
     const { operation, input, attempt, idempotencyKey } = context;
-    const controller = new AbortController();
+    /** @type {unknown} */
-    let timedOut = false;
+    let parsedSearch = {};
-    const timeout = setTimeout(() => {
+    let parsedBody;
-      timedOut = true;
+    const requestValue =
-      controller.abort("timeout");
+      operation.requestSource === "search"
-    }, operation.timeoutMs);
+        ? input.searchParams ?? {}
-    const onExternalAbort = () => controller.abort(input.signal?.reason);
+        : operation.requestSource === "body"
-    input.signal?.addEventListener("abort", onExternalAbort, { once: true });
+          ? input.body
-
+          : {};
-    const headers = new Headers({ Accept: "application/json" });
+    if (operation.requestSource !== "none") {
-    if (input.body !== undefined) headers.set("Content-Type", "application/json");
+      const requestValidation = validateRequest(
-    if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
-
-    if (input.body !== undefined) {
-      const requestValidation = validateOperationRequest(
         operation.requestSchema,
-        input.body,
+        requestValue,
       );
       if (!requestValidation.success) {
         return {
@@ -162,12 +209,46 @@ export function createHttpClient(dependencies) {
           }),
         };
       }
+      if (operation.requestSource === "search") {
+        parsedSearch = requestValidation.data;
+      } else {
+        parsedBody = requestValidation.data;
+      }
     }
 
-    let request = new Request(new URL(operation.path, dependencies.baseUrl), {
+    const target = buildRequestTarget(
+      dependencies.baseUrl,
+      operation,
+      input.pathParams,
+      parsedSearch,
+    );
+    if (!target.success) {
+      return {
+        ok: false,
+        error: failure("VALIDATION_REJECTED", operation.operationId, attempt, {
+          code: target.code,
+        }),
+      };
+    }
+
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = scheduler.setTimeout(() => {
+      timedOut = true;
+      controller.abort("timeout");
+    }, operation.timeoutMs ?? defaultTimeoutMs);
+    const onExternalAbort = () => controller.abort(input.signal?.reason);
+    input.signal?.addEventListener("abort", onExternalAbort, { once: true });
+    if (input.signal?.aborted) onExternalAbort();
+
+    const headers = new Headers({ Accept: "application/json" });
+    if (parsedBody !== undefined) headers.set("Content-Type", "application/json");
+    if (idempotencyKey) headers.set("Idempotency-Key", idempotencyKey);
+
+    let request = new Request(target.url, {
       method: operation.method,
       headers,
-      body: input.body === undefined ? undefined : JSON.stringify(input.body),
+      body: parsedBody === undefined ? undefined : JSON.stringify(parsedBody),
       signal: controller.signal,
     });
 
@@ -237,7 +318,7 @@ export function createHttpClient(dependencies) {
         }),
       };
     } finally {
-      clearTimeout(timeout);
+      scheduler.clearTimeout(timeout);
       input.signal?.removeEventListener("abort", onExternalAbort);
     }
   }

src/adapters/http/request-builder.ts

@@ -0,0 +1,73 @@
+import type { ApiOperation } from "../../contracts/api-operations.js";
+
+export type OperationRequestInput = Readonly<{
+  operationId: string;
+  routeId: string;
+  pathParams?: Readonly<Record<string, string | number>>;
+  searchParams?: unknown;
+  body?: unknown;
+  signal?: AbortSignal;
+  idempotencyKey?: string;
+}>;
+
+export type RequestTargetResult =
+  | Readonly<{ success: true; url: URL }>
+  | Readonly<{
+      success: false;
+      code: "PATH_PARAMETER_MISSING" | "SEARCH_PARAMETER_INVALID";
+    }>;
+
+const pathParameterPattern = /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g;
+
+export function buildRequestTarget(
+  baseUrl: string,
+  operation: ApiOperation,
+  pathParams: Readonly<Record<string, string | number>> = {},
+  parsedSearch: unknown = {},
+): RequestTargetResult {
+  let missingPathParameter = false;
+  const pathname = operation.path.replace(
+    pathParameterPattern,
+    (_token, colonName: string | undefined, braceName: string | undefined) => {
+      const name = colonName ?? braceName ?? "";
+      const value = pathParams[name];
+      if (value === undefined) {
+        missingPathParameter = true;
+        return "";
+      }
+      return encodeURIComponent(String(value));
+    },
+  );
+  if (missingPathParameter) {
+    return { success: false, code: "PATH_PARAMETER_MISSING" };
+  }
+
+  if (
+    parsedSearch === null ||
+    typeof parsedSearch !== "object" ||
+    Array.isArray(parsedSearch)
+  ) {
+    return { success: false, code: "SEARCH_PARAMETER_INVALID" };
+  }
+
+  const url = new URL(pathname, baseUrl);
+  const search = parsedSearch as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(search).sort((left, right) =>
+    left.localeCompare(right),
+  )) {
+    const value = search[key];
+    if (value === undefined || value === null) continue;
+    const values = Array.isArray(value) ? value : [value];
+    for (const item of values) {
+      if (
+        typeof item !== "string" &&
+        typeof item !== "number" &&
+        typeof item !== "boolean"
+      ) {
+        return { success: false, code: "SEARCH_PARAMETER_INVALID" };
+      }
+      url.searchParams.append(key, String(item));
+    }
+  }
+  return { success: true, url };
+}

src/adapters/http/resource-mapper.js

@@ -1,30 +1,5 @@
-import { createResource } from "../../domain/models/resource.js";
-
-/** @param {unknown} value */
-export function mapResourceDto(value) {
-  if (!value || typeof value !== "object") {
-    throw new TypeError("Validated resource DTO is required");
-  }
-  const dto = /** @type {Record<string, unknown>} */ (value);
-  if (typeof dto.id !== "string" || typeof dto.name !== "string") {
-    throw new TypeError("Validated resource DTO invariants were breached");
-  }
-
-  return createResource({
-    id: dto.id,
-    displayName: dto.name,
-    createdAt: typeof dto.createdAt === "string" ? dto.createdAt : null,
-  });
-}
-
 /** @param {string} operationId @param {unknown} payload */
 export function mapOperationPayload(operationId, payload) {
-  if (operationId === "LIST_SAMPLE_RESOURCES") {
+  void payload;
-    if (!Array.isArray(payload)) throw new TypeError("Expected a resource list");
-    return payload.map(mapResourceDto);
-  }
-  if (operationId === "CREATE_SAMPLE_RESOURCE") {
-    return mapResourceDto(payload);
-  }
   throw new TypeError(`No boundary mapper registered for ${operationId}`);
 }

src/adapters/http/retry-policy.js

@@ -35,12 +35,13 @@ export function parseRetryAfter(value, now = Date.now()) {
 }
 
 /**
- * @param {{ idempotency: "safe" | "keyed" | "none" }} operation
+ * @param {{ idempotency: "safe" | "keyed" | "none", retry?: "runtime" | "never" }} operation
  * @param {{ kind: string, retryAfterMs?: number, httpStatus?: number }} failure
  * @param {number} retryCount
  * @param {number} [maxRetries]
  */
 export function shouldRetry(operation, failure, retryCount, maxRetries = 2) {
+  if (operation.retry === "never") return false;
   if (retryCount >= maxRetries) return false;
   if (!retryKinds.has(failure.kind)) return false;
   if (

src/adapters/http/schema-registry.js

@@ -37,34 +37,11 @@ export const responseEnvelopeSchema = z.discriminatedUnion("success", [
   failureEnvelopeSchema,
 ]);
 
-const sampleResourceSchema = z
-  .object({
-    id: z.string().min(1),
-    name: z.string().min(1),
-    createdAt: z.string().optional(),
-  })
-  .passthrough();
-
 const payloadSchemas =
-  /** @type {Readonly<Record<string, z.ZodType>>} */ (Object.freeze({
+  /** @type {Readonly<Record<string, z.ZodType>>} */ (Object.freeze({}));
-  SampleResourceListPayload: z.array(sampleResourceSchema),
-  SampleResourcePayload: sampleResourceSchema,
-}));
 
 const requestSchemas =
-  /** @type {Readonly<Record<string, z.ZodType>>} */ (Object.freeze({
+  /** @type {Readonly<Record<string, z.ZodType>>} */ (Object.freeze({}));
-  SampleResourceListQuery: z
-    .object({
-      cursor: z.string().optional(),
-      limit: z.int().min(1).max(100).default(20),
-    })
-    .strict(),
-  CreateSampleResourceCommand: z
-    .object({
-      name: z.string().trim().min(1).max(120),
-    })
-    .strict(),
-}));
 
 /** @param {unknown} value */
 export function validateEnvelope(value) {

src/adapters/platform/system-clock.js

@@ -8,9 +8,13 @@ export const systemClock = Object.freeze({
         return;
       }
 
-      const timer = setTimeout(resolve, milliseconds);
+      const timer = setTimeout(() => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve();
+      }, milliseconds);
       const onAbort = () => {
         clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
         reject(signal?.reason);
       };
       signal?.addEventListener("abort", onAbort, { once: true });

src/application/create-application.ts

@@ -5,6 +5,7 @@ import type {
   RenderFailureReport,
 } 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";
 
 export type { ApplicationApi, ApplicationOutputPorts };
 
@@ -14,6 +15,7 @@ export type { ApplicationApi, ApplicationOutputPorts };
  */
 export function createApplication(
   outputPorts: ApplicationOutputPorts,
+  featureInputs: Readonly<Record<string, unknown>> = {},
 ): ApplicationApi {
   const session = Object.freeze({
     getSnapshot: () => outputPorts.session.getState(),
@@ -64,10 +66,67 @@ export function createApplication(
     },
   });
 
+  const recovery = Object.freeze({
+    async recoverChunk(input: {
+      chunkId: string;
+      failureKind: "CHUNK_LOAD_FAILURE" | "DEPLOY_MISMATCH";
+    }) {
+      try {
+        const current = await outputPorts.releaseInfo.getCurrent();
+        const active = await outputPorts.releaseInfo.refresh();
+        if (!active.routeChunks[input.chunkId]) {
+          return {
+            action: "support" as const,
+            reason: "active-chunk-unknown",
+          };
+        }
+        const decision = decideChunkRecovery({
+          failureKind: input.failureKind,
+          manifestLoaded: true,
+          currentBuildId: current.buildId,
+          currentReleaseId: current.releaseId,
+          activeBuildId: active.buildId,
+          activeReleaseId: active.releaseId,
+          storage: outputPorts.preferences,
+        });
+        if (decision.action === "reload-once") {
+          try {
+            outputPorts.navigation.reload();
+          } catch {
+            return {
+              action: "support" as const,
+              reason: "reload-failed",
+            };
+          }
+        }
+        return decision;
+      } catch {
+        return {
+          action: "support" as const,
+          reason: "manifest-unavailable",
+        };
+      }
+    },
+  });
+  const installedFeatureInputs = Object.freeze({ ...featureInputs });
+  const features = Object.freeze({
+    has(featureId: string) {
+      return Object.hasOwn(installedFeatureInputs, featureId);
+    },
+    get(featureId: string) {
+      if (!Object.hasOwn(installedFeatureInputs, featureId)) {
+        throw new Error(`Application feature is not installed: ${featureId}`);
+      }
+      return installedFeatureInputs[featureId];
+    },
+  });
+
   return Object.freeze({
     session,
     preferences,
     diagnostics,
     runtime,
+    recovery,
+    features,
   });
 }

src/application/ports/in/application-api.ts

@@ -38,4 +38,17 @@ export type ApplicationApi = Readonly<{
   runtime: Readonly<{
     getReleaseSummary(): Promise<ReleaseSummary>;
   }>;
+  recovery: Readonly<{
+    recoverChunk(input: Readonly<{
+      chunkId: string;
+      failureKind: "CHUNK_LOAD_FAILURE" | "DEPLOY_MISMATCH";
+    }>): Promise<
+      | Readonly<{ action: "reload-once"; releasePair: string }>
+      | Readonly<{ action: "support"; reason: string }>
+    >;
+  }>;
+  features: Readonly<{
+    has(featureId: string): boolean;
+    get(featureId: string): unknown;
+  }>;
 }>;

src/application/ports/out/application-output-ports.ts

@@ -15,4 +15,5 @@ export type ApplicationOutputPorts = Readonly<{
   preferences: StoragePort;
   diagnostics: TelemetryPort;
   releaseInfo: ReleaseInfoPort;
+  navigation: Readonly<{ reload(): void }>;
 }>;

src/application/ports/out/index.ts

@@ -7,11 +7,5 @@ export type {
 export type { ClockPort } from "../clock-port.js";
 export type { QueryCachePort } from "../query-cache-port.js";
 export type { ReleaseInfoPort } from "../release-info-port.js";
-export type {
-  RequestContext,
-  ResourceCommandPort,
-  ResourceQueryPort,
-  Result,
-} from "../resource-ports.js";
 export type { StoragePort } from "../storage-port.js";
 export type { TelemetryPort } from "../telemetry-port.js";

src/application/ports/release-info-port.js

@@ -9,7 +9,16 @@
  *     apiContractVersion: string,
  *     assetManifestHash: string,
  *     releaseId: string,
- *     builtAt?: string
+ *     builtAt?: string,
+ *     routeChunks: Record<string, string>
+ *   }>,
+ *   refresh(): Promise<{
+ *     buildId: string,
+ *     configSchemaVersion: string,
+ *     apiContractVersion: string,
+ *     assetManifestHash: string,
+ *     releaseId: string,
+ *     routeChunks: Record<string, string>
  *   }>
  * }} ReleaseInfoPort
  */

src/application/ports/resource-ports.js

@@ -1,28 +0,0 @@
-/**
- * @template Query
- * @template Model
- * @typedef {{ execute(query: Query, context?: RequestContext): Promise<Result<Model>> }} ResourceQueryPort
- */
-
-/**
- * @template Command
- * @template Model
- * @typedef {{ execute(command: Command, context?: RequestContext): Promise<Result<Model>> }} ResourceCommandPort
- */
-
-/**
- * @typedef {{
- *   operationId: string,
- *   routeId: string,
- *   signal?: AbortSignal,
- *   idempotencyKey?: string
- * }} RequestContext
- */
-
-/**
- * @template Value
- * @typedef {{ ok: true, value: Value, meta?: Record<string, unknown> } |
- *   { ok: false, error: import("../../contracts/errors.js").ApiFailure }} Result
- */
-
-export {};

src/application/use-cases/decide-chunk-recovery.js

@@ -1,13 +1,21 @@
 const RECOVERABLE_KINDS = new Set(["CHUNK_LOAD_FAILURE", "DEPLOY_MISMATCH"]);
 
+/**
+ * @typedef {{action: "reload-once", releasePair: string} |
+ *   {action: "support", reason: string}} ChunkRecoveryDecision
+ */
+
 /**
  * @param {{
  *   failureKind: string,
  *   manifestLoaded: boolean,
  *   currentBuildId: string,
+ *   currentReleaseId: string,
+ *   activeBuildId: string,
  *   activeReleaseId: string,
  *   storage: import("../ports/storage-port.js").StoragePort
  * }} input
+ * @returns {ChunkRecoveryDecision}
  */
 export function decideChunkRecovery(input) {
   if (!RECOVERABLE_KINDS.has(input.failureKind)) {
@@ -16,13 +24,21 @@ export function decideChunkRecovery(input) {
   if (!input.manifestLoaded) {
     return { action: "support", reason: "manifest-unavailable" };
   }
-  if (input.activeReleaseId === input.currentBuildId) {
+  if (
+    input.activeBuildId === input.currentBuildId &&
+    input.activeReleaseId === input.currentReleaseId
+  ) {
     return { action: "support", reason: "same-release" };
   }
 
-  const releasePair = `${input.currentBuildId}->${input.activeReleaseId}`;
+  const releasePair =
+    `${input.currentBuildId}/${input.currentReleaseId}` +
+    `->${input.activeBuildId}/${input.activeReleaseId}`;
   const guard = input.storage.read("CHUNK_RELOAD_GUARD");
-  if (!guard.ok || guard.value === releasePair) {
+  if (!guard.ok) {
+    return { action: "support", reason: "guard-read-failed" };
+  }
+  if (guard.value === releasePair) {
     return { action: "support", reason: "reload-already-attempted" };
   }
 

src/application/view-models/async-state.js

@@ -1,81 +0,0 @@
-export const ASYNC_BASE_STATES = Object.freeze([
-  "initial-loading",
-  "success",
-  "empty",
-  "terminal-error",
-]);
-
-export const ASYNC_OVERLAYS = Object.freeze([
-  "refreshing",
-  "stale-degraded",
-  "mutation-pending",
-  "mutation-conflict",
-]);
-
-/**
- * @typedef {{
- *   data?: unknown,
- *   isInitialLoading?: boolean,
- *   failure?: import("../../contracts/errors.js").ApiFailure,
- *   isFetching?: boolean,
- *   isStale?: boolean,
- *   isDegraded?: boolean,
- *   isMutationPending?: boolean,
- *   hasMutationConflict?: boolean
- * }} AsyncSignals
- */
-
-/** @param {AsyncSignals} signals */
-export function deriveAsyncState(signals) {
-  const hasData = signals.data !== undefined && signals.data !== null;
-  const empty =
-    hasData &&
-    ((Array.isArray(signals.data) && signals.data.length === 0) ||
-      signals.data === "");
-
-  let base;
-  if (signals.isInitialLoading && !hasData) {
-    base = "initial-loading";
-  } else if (signals.failure && !hasData) {
-    base = "terminal-error";
-  } else if (empty) {
-    base = "empty";
-  } else if (hasData) {
-    base = "success";
-  } else {
-    base = "initial-loading";
-  }
-
-  const overlay = Object.freeze({
-    refreshing: Boolean(signals.isFetching && hasData),
-    staleDegraded: Boolean(signals.isStale && signals.isDegraded && hasData),
-    mutationPending: Boolean(signals.isMutationPending && hasData),
-    mutationConflict: Boolean(signals.hasMutationConflict && hasData),
-  });
-
-  const state = {
-    base,
-    data: base === "success" || base === "empty" ? signals.data : undefined,
-    failure: base === "terminal-error" ? signals.failure : undefined,
-    overlay,
-    indicator: selectOverlayIndicator(overlay),
-  };
-
-  return Object.freeze(state);
-}
-
-/**
- * @param {{
- *   refreshing: boolean,
- *   staleDegraded: boolean,
- *   mutationPending: boolean,
- *   mutationConflict: boolean
- * }} overlay
- */
-export function selectOverlayIndicator(overlay) {
-  if (overlay.mutationConflict) return "mutation-conflict";
-  if (overlay.mutationPending) return "mutation-pending";
-  if (overlay.staleDegraded) return "stale-degraded";
-  if (overlay.refreshing) return "refreshing";
-  return null;
-}

src/application/view-models/async-state.ts

@@ -0,0 +1,156 @@
+import type { ApiFailure } from "../../contracts/errors.js";
+
+export const ASYNC_BASE_STATES = Object.freeze([
+  "initial-loading",
+  "success",
+  "empty",
+  "terminal-error",
+] as const);
+
+export const ASYNC_OVERLAYS = Object.freeze([
+  "refreshing",
+  "stale-degraded",
+  "mutation-pending",
+  "mutation-conflict",
+] as const);
+
+export type AsyncOverlay =
+  | Readonly<{
+      refreshing: false;
+      staleDegraded: false;
+      mutationPending: false;
+      mutationConflict: false;
+    }>
+  | Readonly<{
+      refreshing: true;
+      staleDegraded: false;
+      mutationPending: false;
+      mutationConflict: false;
+    }>
+  | Readonly<{
+      refreshing: false;
+      staleDegraded: true;
+      mutationPending: false;
+      mutationConflict: false;
+    }>
+  | Readonly<{
+      refreshing: false;
+      staleDegraded: false;
+      mutationPending: true;
+      mutationConflict: false;
+    }>
+  | Readonly<{
+      refreshing: false;
+      staleDegraded: false;
+      mutationPending: false;
+      mutationConflict: true;
+    }>;
+
+export type AsyncSignals = Readonly<{
+  data?: unknown;
+  isInitialLoading?: boolean;
+  failure?: ApiFailure;
+  isFetching?: boolean;
+  isStale?: boolean;
+  isDegraded?: boolean;
+  isMutationPending?: boolean;
+  hasMutationConflict?: boolean;
+}>;
+
+export type AsyncState = Readonly<{
+  base: (typeof ASYNC_BASE_STATES)[number];
+  data?: unknown;
+  failure?: ApiFailure;
+  overlay: AsyncOverlay;
+  indicator: (typeof ASYNC_OVERLAYS)[number] | null;
+}>;
+
+export function deriveAsyncState(signals: AsyncSignals): AsyncState {
+  const hasData = signals.data !== undefined && signals.data !== null;
+  const empty =
+    hasData &&
+    ((Array.isArray(signals.data) && signals.data.length === 0) ||
+      signals.data === "");
+
+  const base =
+    signals.isInitialLoading && !hasData
+      ? "initial-loading"
+      : signals.failure && !hasData
+        ? "terminal-error"
+        : empty
+          ? "empty"
+          : hasData
+            ? "success"
+            : "initial-loading";
+
+  const indicator =
+    signals.hasMutationConflict && hasData
+      ? "mutation-conflict"
+      : signals.isMutationPending && hasData
+        ? "mutation-pending"
+        : signals.isStale && signals.isDegraded && hasData
+          ? "stale-degraded"
+          : signals.isFetching && hasData
+            ? "refreshing"
+            : null;
+  const overlay = overlayFor(indicator);
+
+  return Object.freeze({
+    base,
+    data: base === "success" || base === "empty" ? signals.data : undefined,
+    failure: base === "terminal-error" ? signals.failure : undefined,
+    overlay,
+    indicator,
+  });
+}
+
+export function selectOverlayIndicator(
+  overlay: AsyncOverlay,
+): AsyncState["indicator"] {
+  if (overlay.mutationConflict) return "mutation-conflict";
+  if (overlay.mutationPending) return "mutation-pending";
+  if (overlay.staleDegraded) return "stale-degraded";
+  if (overlay.refreshing) return "refreshing";
+  return null;
+}
+
+function overlayFor(indicator: AsyncState["indicator"]): AsyncOverlay {
+  if (indicator === "refreshing") {
+    return Object.freeze({
+      refreshing: true,
+      staleDegraded: false,
+      mutationPending: false,
+      mutationConflict: false,
+    });
+  }
+  if (indicator === "stale-degraded") {
+    return Object.freeze({
+      refreshing: false,
+      staleDegraded: true,
+      mutationPending: false,
+      mutationConflict: false,
+    });
+  }
+  if (indicator === "mutation-pending") {
+    return Object.freeze({
+      refreshing: false,
+      staleDegraded: false,
+      mutationPending: true,
+      mutationConflict: false,
+    });
+  }
+  if (indicator === "mutation-conflict") {
+    return Object.freeze({
+      refreshing: false,
+      staleDegraded: false,
+      mutationPending: false,
+      mutationConflict: true,
+    });
+  }
+  return Object.freeze({
+    refreshing: false,
+    staleDegraded: false,
+    mutationPending: false,
+    mutationConflict: false,
+  });
+}

src/application/view-models/resource-view-model.js

@@ -1,16 +0,0 @@
-/**
- * @param {import("../../domain/models/resource.js").Resource} resource
- * @param {(value: Date) => string} [formatDate]
- */
-export function toResourceViewModel(
-  resource,
-  formatDate = (value) => new Intl.DateTimeFormat("ko-KR").format(value),
-) {
-  return Object.freeze({
-    resourceId: resource.id,
-    title: resource.displayName,
-    createdAtLabel: resource.createdAt
-      ? formatDate(new Date(resource.createdAt))
-      : null,
-  });
-}

src/bootstrap/composition-root.js

@@ -16,7 +16,8 @@ import { createApplication } from "../application/create-application.js";
  *     release: Release
  *   }): Promise<{
  *     outputPorts: OutputPorts,
- *     infrastructure: Infrastructure
+ *     infrastructure: Infrastructure,
+ *     featureInputs?: Readonly<Record<string, unknown>>
  *   }>
  * }} factories
  * @returns {Promise<Readonly<{
@@ -30,7 +31,10 @@ export async function createCompositionRoot(factories) {
   const config = await factories.loadConfig();
   const release = await factories.loadRelease(config);
   const adapters = await factories.createAdapters({ config, release });
-  const application = createApplication(adapters.outputPorts);
+  const application = createApplication(
+    adapters.outputPorts,
+    adapters.featureInputs,
+  );
 
   return Object.freeze({
     config,

src/bootstrap/load-release-manifest.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 
 const version = z.string().regex(/^\d+(?:\.\d+){0,2}$/);
-const releaseManifestSchema = z
+export const releaseManifestSchema = z
   .object({
     schemaVersion: z.literal(1),
     appVersion: z.string().min(1),
@@ -12,6 +12,7 @@ const releaseManifestSchema = z
     assetManifestHash: z.string().min(1),
     releaseId: z.string().min(1),
     builtAt: z.string().min(1),
+    routeChunks: z.record(z.string().min(1), z.string().min(1)),
   })
   .strict();
 
@@ -20,7 +21,14 @@ export class ReleaseManifestError extends Error {
   constructor(code, safe) {
     super("Release manifest could not be loaded");
     this.name = "ReleaseManifestError";
-    this.kind = "RELEASE_MANIFEST_FAILURE";
+    this.kind =
+      {
+        MANIFEST_BUILD_MISMATCH: "BUILD_MISMATCH",
+        MANIFEST_CONFIG_SCHEMA_MISMATCH: "CONFIG_MISMATCH",
+        MANIFEST_API_CONTRACT_MISMATCH: "API_CONTRACT_MISMATCH",
+        MANIFEST_RELEASE_MISMATCH: "RELEASE_MISMATCH",
+        MANIFEST_ASSET_MISMATCH: "ASSET_MISMATCH",
+      }[code] ?? "RELEASE_MANIFEST_FAILURE";
     this.code = code;
     this.safe = Object.freeze({
       kind: this.kind,
@@ -33,75 +41,98 @@ export class ReleaseManifestError extends Error {
 }
 
 /**
- * @param {Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>} runtime
+ * Fetches and validates the active manifest without imposing the current
- * @param {{fetcher?: typeof fetch}} [options]
+ * build tuple. Chunk recovery uses this no-store view to detect a new release.
+ *
+ * @param {string} url
+ * @param {{
+ *   fetcher?: typeof fetch,
+ *   buildId: string,
+ *   releaseId?: string
+ * }} options
  */
-export async function loadReleaseManifest(runtime, options = {}) {
+export async function fetchReleaseManifest(url, options) {
   const fetcher = options.fetcher ?? fetch;
   let response;
   try {
-    response = await fetcher(runtime.config.RELEASE_MANIFEST_URL, {
+    response = await fetcher(url, {
       cache: "no-store",
       headers: { Accept: "application/json" },
     });
   } catch {
-    throw new ReleaseManifestError("MANIFEST_FETCH_FAILED", {
+    throw new ReleaseManifestError("MANIFEST_FETCH_FAILED", options);
-      buildId: runtime.build.buildId,
-      releaseId: runtime.config.RELEASE_ID,
-    });
   }
   if (!response.ok) {
-    throw new ReleaseManifestError("MANIFEST_HTTP_FAILED", {
+    throw new ReleaseManifestError("MANIFEST_HTTP_FAILED", options);
-      buildId: runtime.build.buildId,
-      releaseId: runtime.config.RELEASE_ID,
-    });
   }
-
   let raw;
   try {
     raw = await response.json();
   } catch {
-    throw new ReleaseManifestError("MANIFEST_JSON_INVALID", {
+    throw new ReleaseManifestError("MANIFEST_JSON_INVALID", options);
-      buildId: runtime.build.buildId,
-      releaseId: runtime.config.RELEASE_ID,
-    });
   }
   const parsed = releaseManifestSchema.safeParse(raw);
   if (!parsed.success) {
-    throw new ReleaseManifestError("MANIFEST_SCHEMA_INVALID", {
+    throw new ReleaseManifestError("MANIFEST_SCHEMA_INVALID", options);
+  }
+  return Object.freeze(structuredClone(parsed.data));
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>} runtime
+ * @param {{fetcher?: typeof fetch, expectedAssetManifestHash?: string}} [options]
+ */
+export async function loadReleaseManifest(runtime, options = {}) {
+  const manifest = await fetchReleaseManifest(
+    runtime.config.RELEASE_MANIFEST_URL,
+    {
+      fetcher: options.fetcher,
       buildId: runtime.build.buildId,
       releaseId: runtime.config.RELEASE_ID,
-    });
+    },
+  );
+  let mismatchCode = null;
+  if (manifest.buildId !== runtime.build.buildId) {
+    mismatchCode = "MANIFEST_BUILD_MISMATCH";
   }
-
-  const manifest = parsed.data;
-  const mismatches = [];
-  if (manifest.buildId !== runtime.build.buildId) mismatches.push("buildId");
   if (
+    !mismatchCode &&
     runtime.config.BUILD_ID &&
     manifest.buildId !== runtime.config.BUILD_ID
   ) {
-    mismatches.push("runtimeBuildId");
+    mismatchCode = "MANIFEST_BUILD_MISMATCH";
   }
   if (
+    !mismatchCode &&
     manifest.configSchemaVersion !== runtime.config.CONFIG_SCHEMA_VERSION
   ) {
-    mismatches.push("configSchemaVersion");
+    mismatchCode = "MANIFEST_CONFIG_SCHEMA_MISMATCH";
-  }
-  if (manifest.apiContractVersion !== runtime.config.API_CONTRACT_VERSION) {
-    mismatches.push("apiContractVersion");
   }
   if (
+    !mismatchCode &&
+    manifest.apiContractVersion !== runtime.config.API_CONTRACT_VERSION
+  ) {
+    mismatchCode = "MANIFEST_API_CONTRACT_MISMATCH";
+  }
+  if (
+    !mismatchCode &&
     runtime.config.RELEASE_ID &&
     manifest.releaseId !== runtime.config.RELEASE_ID
   ) {
-    mismatches.push("releaseId");
+    mismatchCode = "MANIFEST_RELEASE_MISMATCH";
   }
-  if (mismatches.length > 0) {
+  if (
-    throw new ReleaseManifestError("MANIFEST_RUNTIME_MISMATCH", {
+    !mismatchCode &&
+    options.expectedAssetManifestHash &&
+    manifest.assetManifestHash !== options.expectedAssetManifestHash
+  ) {
+    mismatchCode = "MANIFEST_ASSET_MISMATCH";
+  }
+  if (mismatchCode) {
+    throw new ReleaseManifestError(mismatchCode, {
       buildId: runtime.build.buildId,
       releaseId: runtime.config.RELEASE_ID,
     });
   }
-  return Object.freeze(structuredClone(manifest));
+  return manifest;
 }

src/bootstrap/runtime-adapters.js

@@ -3,11 +3,14 @@ import {
   createExternalAuthSessionAdapter,
   createUnavailableSessionAdapter,
 } from "../adapters/auth/external-session-adapter.js";
+import { createHttpClient } from "../adapters/http/client.js";
 import {
   createQueryClient,
 } from "../adapters/query-cache/tanstack-query-cache.js";
 import { createBrowserStorageAdapter } from "../adapters/storage/browser-storage-adapter.js";
 import { createTelemetryAdapter } from "../adapters/telemetry/best-effort-telemetry.js";
+import { fetchReleaseManifest } from "./load-release-manifest.js";
+import { createInstalledFeatureInputs } from "../features/installed-feature-adapters.js";
 
 /**
  * @param {Record<string, unknown>} host
@@ -40,6 +43,31 @@ function storageOrUndefined(value) {
     : undefined;
 }
 
+/**
+ * Runtime-aware transport factory. Feature gateway composition calls this
+ * factory when a registered API capability is installed.
+ *
+ * @param {{
+ *   runtime: Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>,
+ *   authSession: import("../application/ports/auth-session-port.js").AuthSessionPort,
+ *   fetcher?: typeof fetch,
+ *   clock?: import("../application/ports/clock-port.js").ClockPort,
+ *   scheduler?: Parameters<typeof createHttpClient>[0]["scheduler"]
+ * }} context
+ */
+export function createRuntimeHttpClient(context, contract = {}) {
+  return createHttpClient({
+    baseUrl: context.runtime.config.API_BASE_URL,
+    timeoutMs: context.runtime.config.REQUEST_TIMEOUT_MS,
+    maxRetryAttempts: context.runtime.config.MAX_RETRY_ATTEMPTS,
+    authSession: context.authSession,
+    fetcher: context.fetcher,
+    clock: context.clock,
+    scheduler: context.scheduler,
+    ...contract,
+  });
+}
+
 /**
  * @param {{
  *   runtime: Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>,
@@ -72,6 +100,34 @@ export async function createRuntimeAdapters(context) {
     async getCurrent() {
       return structuredClone(context.release);
     },
+    async refresh() {
+      return fetchReleaseManifest(config.RELEASE_MANIFEST_URL, {
+        fetcher: context.fetcher,
+        buildId: context.release.buildId,
+        releaseId: context.release.releaseId,
+      });
+    },
+  });
+  const navigation = Object.freeze({
+    reload() {
+      const location =
+        /** @type {{reload?: () => void} | undefined} */ (host.location);
+      if (typeof location?.reload !== "function") {
+        throw new Error("Browser reload is unavailable");
+      }
+      location.reload();
+    },
+  });
+  const featureInputs = createInstalledFeatureInputs({
+    createHttpClient: (contract) =>
+      createRuntimeHttpClient(
+        {
+          runtime: context.runtime,
+          authSession,
+          fetcher: context.fetcher,
+        },
+        contract,
+      ),
   });
 
   return Object.freeze({
@@ -80,9 +136,11 @@ export async function createRuntimeAdapters(context) {
       preferences: storage,
       diagnostics: telemetry,
       releaseInfo,
+      navigation,
     }),
     infrastructure: Object.freeze({
       queryClient,
     }),
+    featureInputs,
   });
 }

src/contracts/api-operations.js

@@ -4,45 +4,21 @@
  *   path: string,
  *   operationId: string,
  *   auth: "none" | "external-session",
- *   timeoutMs: number,
+ *   timeoutMs: number | null,
  *   idempotency: "safe" | "keyed" | "none",
+ *   retry: "runtime" | "never",
+ *   requestSource: "search" | "body" | "none",
  *   requestSchema: string,
  *   responseSchema: string,
  *   owner: string
  * }} ApiOperation
  */
 
-/** @param {ApiOperation} definition */
+export const API_OPERATIONS = Object.freeze({});
-const operation = (definition) => Object.freeze(definition);
-
-export const API_OPERATIONS = Object.freeze({
-  LIST_SAMPLE_RESOURCES: operation({
-    method: "GET",
-    path: "/api/sample/resources",
-    operationId: "LIST_SAMPLE_RESOURCES",
-    auth: "external-session",
-    timeoutMs: 10_000,
-    idempotency: "safe",
-    requestSchema: "SampleResourceListQuery",
-    responseSchema: "SampleResourceListPayload",
-    owner: "feature-sample-feature-slice-contract-fixture",
-  }),
-  CREATE_SAMPLE_RESOURCE: operation({
-    method: "POST",
-    path: "/api/sample/resources",
-    operationId: "CREATE_SAMPLE_RESOURCE",
-    auth: "external-session",
-    timeoutMs: 10_000,
-    idempotency: "keyed",
-    requestSchema: "CreateSampleResourceCommand",
-    responseSchema: "SampleResourcePayload",
-    owner: "feature-sample-feature-slice-contract-fixture",
-  }),
-});
 
 /** @param {string} operationId */
-export function getApiOperation(operationId) {
+export function getApiOperation(operationId, operations = API_OPERATIONS) {
-  const registry = /** @type {Record<string, ApiOperation>} */ (API_OPERATIONS);
+  const registry = /** @type {Record<string, ApiOperation>} */ (operations);
   const selected = registry[operationId];
   if (!selected) {
     throw new Error(`Unregistered API operation: ${operationId}`);

src/contracts/errors.js

@@ -111,6 +111,41 @@ export const ERROR_REGISTRY = Object.freeze({
     "reload-once",
     "release.mismatch.detected",
   ),
+  BUILD_MISMATCH: row(
+    "BUILD_MISMATCH",
+    false,
+    "error",
+    "reload-once",
+    "release.mismatch.detected",
+  ),
+  CONFIG_MISMATCH: row(
+    "CONFIG_MISMATCH",
+    false,
+    "error",
+    "contact-support",
+    "app.boot.failed",
+  ),
+  API_CONTRACT_MISMATCH: row(
+    "API_CONTRACT_MISMATCH",
+    false,
+    "error",
+    "contact-support",
+    "app.boot.failed",
+  ),
+  RELEASE_MISMATCH: row(
+    "RELEASE_MISMATCH",
+    false,
+    "error",
+    "reload-once",
+    "release.mismatch.detected",
+  ),
+  ASSET_MISMATCH: row(
+    "ASSET_MISMATCH",
+    false,
+    "error",
+    "reload-once",
+    "release.mismatch.detected",
+  ),
   STORAGE_UNAVAILABLE: row(
     "STORAGE_UNAVAILABLE",
     false,

src/contracts/query-keys.js

@@ -1,26 +1,4 @@
-const RESOURCE_NAMESPACE = Object.freeze(["resource", 1]);
+export const QUERY_REGISTRY = Object.freeze({});
-
-export const queryKeys = Object.freeze({
-  resource: Object.freeze({
-    all: () => RESOURCE_NAMESPACE,
-    list: (filters = {}) =>
-      Object.freeze([...RESOURCE_NAMESPACE, "list", canonicalize(filters)]),
-    /** @param {string} resourceId */
-    detail: (resourceId) =>
-      Object.freeze([...RESOURCE_NAMESPACE, "detail", String(resourceId)]),
-  }),
-});
-
-export const QUERY_REGISTRY = Object.freeze({
-  RESOURCE: Object.freeze({
-    namespace: RESOURCE_NAMESPACE,
-    serialization: "canonical-object-order",
-    identity: "no-pii-token-or-raw-url",
-    invalidation: "resource namespace after successful mutation",
-    version: 1,
-    persistence: "disabled",
-  }),
-});
 
 /** @param {unknown} value @returns {unknown} */
 export function canonicalize(value) {

src/contracts/route-runtime-contract.js

@@ -0,0 +1,39 @@
+/**
+ * @typedef {"none" | "NotFoundSplat"} RouteCodecId
+ */
+
+/** @param {Readonly<{routeId: string, moduleId: string, paramsCodec: RouteCodecId, searchCodec: RouteCodecId}>} value */
+const runtime = (value) => Object.freeze(value);
+
+export const PLATFORM_ROUTE_RUNTIME_CONTRACT = Object.freeze({
+  APP_HOME: runtime({
+    routeId: "APP_HOME",
+    moduleId: "home-page",
+    paramsCodec: "none",
+    searchCodec: "none",
+  }),
+  EXAMPLES_UI: runtime({
+    routeId: "EXAMPLES_UI",
+    moduleId: "ui-gallery-page",
+    paramsCodec: "none",
+    searchCodec: "none",
+  }),
+  EXAMPLES_STATES: runtime({
+    routeId: "EXAMPLES_STATES",
+    moduleId: "state-gallery-page",
+    paramsCodec: "none",
+    searchCodec: "none",
+  }),
+  EXAMPLES_AUTH: runtime({
+    routeId: "EXAMPLES_AUTH",
+    moduleId: "auth-example-page",
+    paramsCodec: "none",
+    searchCodec: "none",
+  }),
+  NOT_FOUND: runtime({
+    routeId: "NOT_FOUND",
+    moduleId: "not-found-page",
+    paramsCodec: "NotFoundSplat",
+    searchCodec: "none",
+  }),
+});

src/contracts/routes.js

@@ -17,7 +17,7 @@
 /** @param {RouteDefinition} definition */
 const route = (definition) => Object.freeze(definition);
 
-export const ROUTE_REGISTRY = Object.freeze({
+export const PLATFORM_ROUTE_REGISTRY = Object.freeze({
   APP_HOME: route({
     routeId: "APP_HOME",
     path: "/",
@@ -70,23 +70,10 @@ export const ROUTE_REGISTRY = Object.freeze({
     navigationLabel: "인증 연동",
     navigationOrder: 40,
   }),
-  SAMPLE_RESOURCE_LIST: route({
-    routeId: "SAMPLE_RESOURCE_LIST",
-    path: "/sample/resources",
-    paramsSchema: null,
-    searchSchema: "SampleResourceListQuery",
-    access: "integration-defined",
-    loadingSurface: "sample-resource-list",
-    errorSurface: "feature-boundary",
-    chunkId: "route-sample-resources",
-    title: "보호된 연동 지점",
-    navigationLabel: "보호된 연동 지점",
-    navigationOrder: 50,
-  }),
   NOT_FOUND: route({
     routeId: "NOT_FOUND",
     path: "*",
-    paramsSchema: null,
+    paramsSchema: "NotFoundSplat",
     searchSchema: null,
     access: "public",
     loadingSurface: "none",
@@ -97,28 +84,3 @@ export const ROUTE_REGISTRY = Object.freeze({
     navigationOrder: null,
   }),
 });
-
-export const NAVIGATION_ROUTES = Object.freeze(
-  Object.values(ROUTE_REGISTRY)
-    .filter((definition) => definition.navigationOrder !== null)
-    .sort(
-      (left, right) =>
-        /** @type {number} */ (left.navigationOrder) -
-        /** @type {number} */ (right.navigationOrder),
-    ),
-);
-
-/** @param {string} routeId */
-export function getRoute(routeId) {
-  const registry = /** @type {Record<string, Readonly<RouteDefinition>>} */ (
-    ROUTE_REGISTRY
-  );
-  const selected = registry[routeId];
-  if (!selected) throw new Error(`Unregistered route: ${routeId}`);
-  return selected;
-}
-
-/** @param {string} routeId */
-export function routePath(routeId) {
-  return getRoute(routeId).path;
-}

src/domain/models/resource.js

@@ -1,19 +0,0 @@
-/**
- * @typedef {{
- *   id: string,
- *   displayName: string,
- *   createdAt: string | null
- * }} Resource
- */
-
-/** @param {Resource} values @returns {Readonly<Resource>} */
-export function createResource(values) {
-  if (!values.id || !values.displayName) {
-    throw new TypeError("Resource invariants require id and displayName");
-  }
-  return Object.freeze({
-    id: values.id,
-    displayName: values.displayName,
-    createdAt: values.createdAt,
-  });
-}

src/features/installed-feature-adapters.ts

@@ -0,0 +1,15 @@
+import { createReferenceFeatureInstalledInput } from "./reference-feature/adapters/create-reference-feature-input.js";
+
+export function createInstalledFeatureInputs(
+  context: Parameters<typeof createReferenceFeatureInstalledInput>[0],
+): Readonly<Record<string, unknown>> {
+  const installed = [createReferenceFeatureInstalledInput(context)];
+  return Object.freeze(
+    Object.fromEntries(
+      installed.map((contribution) => [
+        contribution.featureId,
+        contribution.input,
+      ]),
+    ),
+  );
+}

src/features/installed-feature-contracts.js

@@ -0,0 +1,48 @@
+import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../contracts/route-runtime-contract.js";
+import { PLATFORM_ROUTE_REGISTRY } from "../contracts/routes.js";
+import { REFERENCE_FEATURE_CONTRACT } from "./reference-feature/contracts/reference-feature-contract.js";
+
+export const INSTALLED_FEATURE_CONTRACTS = Object.freeze([
+  REFERENCE_FEATURE_CONTRACT,
+]);
+
+export const ROUTE_REGISTRY = Object.freeze({
+  ...PLATFORM_ROUTE_REGISTRY,
+  ...REFERENCE_FEATURE_CONTRACT.routes,
+});
+export const ROUTE_RUNTIME_CONTRACT = Object.freeze({
+  ...PLATFORM_ROUTE_RUNTIME_CONTRACT,
+  ...REFERENCE_FEATURE_CONTRACT.routeRuntimeContracts,
+});
+export const API_OPERATIONS = Object.freeze({
+  ...REFERENCE_FEATURE_CONTRACT.apiOperations,
+});
+export const QUERY_REGISTRY = Object.freeze({
+  ...REFERENCE_FEATURE_CONTRACT.queryRegistry,
+});
+
+export const NAVIGATION_ROUTES = Object.freeze(
+  Object.values(ROUTE_REGISTRY)
+    .filter((definition) => definition.navigationOrder !== null)
+    .sort(
+      (left, right) =>
+        /** @type {number} */ (left.navigationOrder) -
+        /** @type {number} */ (right.navigationOrder),
+    ),
+);
+
+/** @param {string} routeId */
+export function getRoute(routeId) {
+  const registry =
+    /** @type {Readonly<Record<string, import("../contracts/routes.js").RouteDefinition>>} */ (
+      ROUTE_REGISTRY
+    );
+  const selected = registry[routeId];
+  if (!selected) throw new Error(`Unregistered route: ${routeId}`);
+  return selected;
+}
+
+/** @param {string} routeId */
+export function routePath(routeId) {
+  return getRoute(routeId).path;
+}

src/features/installed-feature-runtimes.tsx

@@ -0,0 +1,16 @@
+import { PLATFORM_ROUTE_CODECS } from "../presentation/routes/platform-route-codecs.js";
+import { PLATFORM_ROUTE_RUNTIME } from "../presentation/routes/route-runtime.js";
+import {
+  REFERENCE_FEATURE_ROUTE_CODECS,
+  REFERENCE_FEATURE_ROUTE_RUNTIME,
+} from "./reference-feature/presentation/reference-feature-runtime.js";
+
+export const ROUTE_CODECS = Object.freeze({
+  ...PLATFORM_ROUTE_CODECS,
+  ...REFERENCE_FEATURE_ROUTE_CODECS,
+});
+
+export const ROUTE_RUNTIME = Object.freeze({
+  ...PLATFORM_ROUTE_RUNTIME,
+  ...REFERENCE_FEATURE_ROUTE_RUNTIME,
+});

src/features/reference-feature/README.md

@@ -0,0 +1,39 @@
+# Reference feature ownership and removal
+
+이 모듈은 제품 도메인이 아니라 새 기능의 수직 경계를 검증하는 제거 가능한
+reference implementation이다.
+
+## 소유 경계
+
+- `domain`: 외부 DTO와 React를 모르는 불변 model
+- `application`: UI가 호출하는 list/create input과 gateway 계약
+- `adapters`: HTTP executor를 gateway로 투영하는 outbound adapter
+- `contracts`: route/API/query contribution, Zod DTO와 request schema, mapper
+- `presentation`: route input을 query/mutation controller로 연결하는 inbound
+  adapter와 page
+
+generic application은 `features.get(featureId)` catalog만 제공한다. feature hook이
+자신의 input shape를 확인하며 page는 HTTP client, storage, auth owner, output
+port나 TanStack API를 직접 import하지 않는다.
+
+## 설치 지점
+
+- 직렬화 계약: `src/features/installed-feature-contracts.js`
+- component/codec: `src/features/installed-feature-runtimes.tsx`
+- bootstrap input 조립: `src/features/installed-feature-adapters.ts`
+
+새 기능도 이 세 지점에 contribution을 합성하되 feature ID를 generic application,
+router나 HTTP client에 하드코딩하지 않는다.
+
+## 검증과 제거
+
+```sh
+corepack pnpm test:reference-feature
+corepack pnpm test:sample-removal
+```
+
+첫 명령은 URL filter와 query key/HTTP request의 동일성, schema/mapper, 모든
+query/mutation 상태와 production composition을 검증한다. 두 번째 명령은 임시
+복제본에서 이 source/test 디렉터리를 제거하고 installed catalog를 빈 목록으로
+재생성한 뒤 typecheck, architecture, registry, unit/integration, home smoke,
+production build와 fixture ID 잔여 0개를 검사한다.

src/features/reference-feature/adapters/create-reference-feature-input.ts

@@ -0,0 +1,43 @@
+import { createReferenceFeatureInput } from "../application/reference-feature-api.js";
+import {
+  REFERENCE_FEATURE_CONTRACT,
+  REFERENCE_FEATURE_ID,
+} from "../contracts/reference-feature-contract.js";
+import { mapReferenceOperation } from "../contracts/reference-mapper.js";
+import {
+  validateReferencePayload,
+  validateReferenceRequest,
+} from "../contracts/reference-schemas.js";
+import { createReferenceHttpGateway } from "./reference-http-gateway.js";
+
+type HttpContract = Readonly<{
+  getOperation(operationId: string): unknown;
+  validatePayload: typeof validateReferencePayload;
+  validateRequest: typeof validateReferenceRequest;
+  mapPayload: typeof mapReferenceOperation;
+}>;
+
+type HttpExecutor = Parameters<typeof createReferenceHttpGateway>[0];
+
+export function createReferenceFeatureInstalledInput(context: Readonly<{
+  createHttpClient(contract: HttpContract): HttpExecutor;
+}>) {
+  const operations =
+    REFERENCE_FEATURE_CONTRACT.apiOperations as Readonly<Record<string, unknown>>;
+  const http = context.createHttpClient({
+    getOperation(operationId) {
+      const operation = operations[operationId];
+      if (!operation) {
+        throw new Error(`Unknown reference operation: ${operationId}`);
+      }
+      return operation;
+    },
+    validatePayload: validateReferencePayload,
+    validateRequest: validateReferenceRequest,
+    mapPayload: mapReferenceOperation,
+  });
+  return Object.freeze({
+    featureId: REFERENCE_FEATURE_ID,
+    input: createReferenceFeatureInput(createReferenceHttpGateway(http)),
+  });
+}

src/features/reference-feature/adapters/reference-http-gateway.ts

@@ -0,0 +1,56 @@
+import type { ApiFailure } from "../../../contracts/errors.js";
+import type {
+  ReferenceGateway,
+  ReferenceListFilters,
+} from "../application/reference-feature-api.js";
+import type { ReferenceResource } from "../domain/reference-resource.js";
+
+type HttpResult =
+  | Readonly<{ ok: true; value: unknown }>
+  | Readonly<{ ok: false; error: ApiFailure }>;
+
+type HttpExecutor = Readonly<{
+  execute(
+    request: Readonly<{
+      operationId: string;
+      routeId: string;
+      searchParams?: unknown;
+      body?: unknown;
+      signal?: AbortSignal;
+    }>,
+  ): Promise<HttpResult>;
+}>;
+
+export function createReferenceHttpGateway(
+  http: HttpExecutor,
+): ReferenceGateway {
+  return Object.freeze({
+    async list(
+      filters: ReferenceListFilters,
+      context?: Readonly<{ signal?: AbortSignal }>,
+    ) {
+      const result = await http.execute({
+        operationId: "LIST_REFERENCE_RESOURCES",
+        routeId: "REFERENCE_RESOURCE_LIST",
+        searchParams: filters,
+        signal: context?.signal,
+      });
+      return result.ok
+        ? {
+            ok: true as const,
+            value: result.value as readonly ReferenceResource[],
+          }
+        : result;
+    },
+    async create(command: Readonly<{ name: string }>) {
+      const result = await http.execute({
+        operationId: "CREATE_REFERENCE_RESOURCE",
+        routeId: "REFERENCE_RESOURCE_LIST",
+        body: command,
+      });
+      return result.ok
+        ? { ok: true as const, value: result.value as ReferenceResource }
+        : result;
+    },
+  });
+}

src/features/reference-feature/application/reference-feature-api.ts

@@ -0,0 +1,58 @@
+import type { ApiFailure } from "../../../contracts/errors.js";
+import {
+  toReferenceView,
+  type ReferenceResourceView,
+} from "../contracts/reference-mapper.js";
+import type { ReferenceResource } from "../domain/reference-resource.js";
+
+export type ReferenceListFilters = Readonly<{
+  cursor?: string;
+  limit: number;
+  tags?: readonly string[];
+}>;
+
+export type ReferenceResult<Value> =
+  | Readonly<{ ok: true; value: Value }>
+  | Readonly<{ ok: false; error: ApiFailure }>;
+
+export type ReferenceFeatureInput = Readonly<{
+  listResources(
+    filters: ReferenceListFilters,
+    context?: Readonly<{ signal?: AbortSignal }>,
+  ): Promise<ReferenceResult<readonly ReferenceResourceView[]>>;
+  createResource(
+    command: Readonly<{ name: string }>,
+  ): Promise<ReferenceResult<ReferenceResourceView>>;
+}>;
+
+export type ReferenceGateway = Readonly<{
+  list(
+    filters: ReferenceListFilters,
+    context?: Readonly<{ signal?: AbortSignal }>,
+  ): Promise<ReferenceResult<readonly ReferenceResource[]>>;
+  create(
+    command: Readonly<{ name: string }>,
+  ): Promise<ReferenceResult<ReferenceResource>>;
+}>;
+
+export function createReferenceFeatureInput(
+  gateway: ReferenceGateway,
+): ReferenceFeatureInput {
+  return Object.freeze({
+    async listResources(filters, context) {
+      const result = await gateway.list(filters, context);
+      return result.ok
+        ? {
+            ok: true as const,
+            value: result.value.map((resource) => toReferenceView(resource)),
+          }
+        : result;
+    },
+    async createResource(command) {
+      const result = await gateway.create(command);
+      return result.ok
+        ? { ok: true as const, value: toReferenceView(result.value) }
+        : result;
+    },
+  });
+}

src/features/reference-feature/contracts/reference-feature-contract.js

@@ -0,0 +1,75 @@
+import { canonicalize } from "../../../contracts/query-keys.js";
+
+export const REFERENCE_FEATURE_ID = "reference-feature";
+const REFERENCE_NAMESPACE = Object.freeze(["reference-resource", 1]);
+
+export const referenceQueryKeys = Object.freeze({
+  all: () => REFERENCE_NAMESPACE,
+  list: (filters = {}) =>
+    Object.freeze([...REFERENCE_NAMESPACE, "list", canonicalize(filters)]),
+});
+
+export const REFERENCE_FEATURE_CONTRACT = Object.freeze({
+  featureId: REFERENCE_FEATURE_ID,
+  routes: Object.freeze({
+    REFERENCE_RESOURCE_LIST: Object.freeze({
+      routeId: "REFERENCE_RESOURCE_LIST",
+      path: "/examples/reference-resources",
+      paramsSchema: null,
+      searchSchema: "ReferenceResourceListQuery",
+      access: "integration-defined",
+      loadingSurface: "reference-resource-list",
+      errorSurface: "feature-boundary",
+      chunkId: "route-reference-resources",
+      title: "Reference feature",
+      navigationLabel: "Reference feature",
+      navigationOrder: 50,
+    }),
+  }),
+  routeRuntimeContracts: Object.freeze({
+    REFERENCE_RESOURCE_LIST: Object.freeze({
+      routeId: "REFERENCE_RESOURCE_LIST",
+      moduleId: "reference-resource-page",
+      paramsCodec: "none",
+      searchCodec: "ReferenceResourceListQuery",
+    }),
+  }),
+  apiOperations: Object.freeze({
+    LIST_REFERENCE_RESOURCES: Object.freeze({
+      method: "GET",
+      path: "/api/reference-resources",
+      operationId: "LIST_REFERENCE_RESOURCES",
+      auth: "external-session",
+      timeoutMs: null,
+      idempotency: "safe",
+      retry: "runtime",
+      requestSource: "search",
+      requestSchema: "ReferenceResourceListQuery",
+      responseSchema: "ReferenceResourceListPayload",
+      owner: "feature-frontend-reference-feature-vertical-slice",
+    }),
+    CREATE_REFERENCE_RESOURCE: Object.freeze({
+      method: "POST",
+      path: "/api/reference-resources",
+      operationId: "CREATE_REFERENCE_RESOURCE",
+      auth: "external-session",
+      timeoutMs: null,
+      idempotency: "keyed",
+      retry: "runtime",
+      requestSource: "body",
+      requestSchema: "CreateReferenceResourceCommand",
+      responseSchema: "ReferenceResourcePayload",
+      owner: "feature-frontend-reference-feature-vertical-slice",
+    }),
+  }),
+  queryRegistry: Object.freeze({
+    REFERENCE_RESOURCE: Object.freeze({
+      namespace: REFERENCE_NAMESPACE,
+      serialization: "canonical-object-order",
+      identity: "no-pii-token-or-raw-url",
+      invalidation: "reference resource namespace after successful mutation",
+      version: 1,
+      persistence: "disabled",
+    }),
+  }),
+});

src/features/reference-feature/contracts/reference-mapper.ts

@@ -0,0 +1,54 @@
+import {
+  createReferenceResource,
+  type ReferenceResource,
+} from "../domain/reference-resource.js";
+
+export type ReferenceResourceView = Readonly<{
+  resourceId: string;
+  title: string;
+  createdAtLabel: string | null;
+  optimistic?: boolean;
+}>;
+
+function mapReferenceDto(value: unknown): ReferenceResource {
+  if (!value || typeof value !== "object") {
+    throw new TypeError("Validated reference DTO is required");
+  }
+  const dto = value as Record<string, unknown>;
+  if (typeof dto.id !== "string" || typeof dto.name !== "string") {
+    throw new TypeError("Validated reference DTO invariants were breached");
+  }
+  return createReferenceResource({
+    id: dto.id,
+    displayName: dto.name,
+    createdAt: typeof dto.createdAt === "string" ? dto.createdAt : null,
+  });
+}
+
+export function mapReferenceOperation(
+  operationId: string,
+  payload: unknown,
+): ReferenceResource | readonly ReferenceResource[] {
+  if (operationId === "LIST_REFERENCE_RESOURCES") {
+    if (!Array.isArray(payload)) throw new TypeError("Expected a reference list");
+    return payload.map(mapReferenceDto);
+  }
+  if (operationId === "CREATE_REFERENCE_RESOURCE") {
+    return mapReferenceDto(payload);
+  }
+  throw new TypeError(`No reference mapper registered for ${operationId}`);
+}
+
+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,
+  });
+}

src/features/reference-feature/contracts/reference-schemas.ts

@@ -0,0 +1,67 @@
+import { z } from "zod";
+
+export const referenceResourceListQuerySchema = z
+  .object({
+    cursor: z.string().min(1).optional(),
+    limit: z.coerce.number().int().min(1).max(100).default(20),
+    tags: z
+      .preprocess(
+        (value) =>
+          value === undefined
+            ? undefined
+            : Array.isArray(value)
+              ? value
+              : [value],
+        z.array(z.string().trim().min(1)),
+      )
+      .optional(),
+  })
+  .strict();
+
+const referenceResourceDtoSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    createdAt: z.string().datetime().optional(),
+  })
+  .strict();
+
+const payloadSchemas = {
+  ReferenceResourceListPayload: z.array(referenceResourceDtoSchema),
+  ReferenceResourcePayload: referenceResourceDtoSchema,
+} satisfies Record<string, z.ZodType>;
+
+const requestSchemas = {
+  ReferenceResourceListQuery: referenceResourceListQuerySchema,
+  CreateReferenceResourceCommand: z
+    .object({
+      name: z.string().trim().min(1).max(120),
+    })
+    .strict(),
+} satisfies Record<string, z.ZodType>;
+
+function project(result: z.ZodSafeParseResult<unknown>) {
+  return result.success
+    ? ({ success: true as const, data: structuredClone(result.data) })
+    : ({
+        success: false as const,
+        issues: result.error.issues.map((issue) => ({
+          path: issue.path.join("."),
+          code: issue.code,
+        })),
+      });
+}
+
+export function validateReferencePayload(schemaId: string, value: unknown) {
+  const schema = payloadSchemas[schemaId as keyof typeof payloadSchemas];
+  return schema
+    ? project(schema.safeParse(value))
+    : { success: false as const, issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }] };
+}
+
+export function validateReferenceRequest(schemaId: string, value: unknown) {
+  const schema = requestSchemas[schemaId as keyof typeof requestSchemas];
+  return schema
+    ? project(schema.safeParse(value))
+    : { success: false as const, issues: [{ path: "", code: "SCHEMA_NOT_REGISTERED" }] };
+}

src/features/reference-feature/domain/reference-resource.ts

@@ -0,0 +1,14 @@
+export type ReferenceResource = Readonly<{
+  id: string;
+  displayName: string;
+  createdAt: string | null;
+}>;
+
+export function createReferenceResource(
+  values: ReferenceResource,
+): ReferenceResource {
+  if (!values.id || !values.displayName) {
+    throw new TypeError("Reference resource invariants require id and displayName");
+  }
+  return Object.freeze({ ...values });
+}

src/features/reference-feature/presentation/reference-feature-runtime.tsx

@@ -0,0 +1,14 @@
+import { lazy } from "react";
+
+import { referenceResourceListQuerySchema } from "../contracts/reference-schemas.js";
+
+export const REFERENCE_FEATURE_ROUTE_CODECS = {
+  ReferenceResourceListQuery: referenceResourceListQuerySchema,
+} as const;
+
+export const REFERENCE_FEATURE_ROUTE_RUNTIME = {
+  REFERENCE_RESOURCE_LIST: Object.freeze({
+    moduleId: "reference-resource-page",
+    Component: lazy(() => import("./reference-resource-page.js")),
+  }),
+} as const;

src/features/reference-feature/presentation/reference-resource-page.tsx

@@ -0,0 +1,60 @@
+import { useState, type FormEvent } from "react";
+
+import { AsyncSurface } from "../../../presentation/components/async-surface.jsx";
+import { Button } from "../../../presentation/components/ui/button.jsx";
+import { PageHeader } from "../../../presentation/components/page-header.jsx";
+import { useReferenceFeature } from "./use-reference-feature.js";
+
+export default function ReferenceResourcePage() {
+  const { filters, query, mutation } = useReferenceFeature();
+  const [name, setName] = useState("");
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const result = await mutation.submit({ name });
+    if (result.ok) setName("");
+  }
+
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="제거 가능한 수직 슬라이스"
+        title="Reference feature"
+        description="URL codec, application input, HTTP/schema/mapper와 query/mutation 상태를 한 경로로 검증합니다."
+      />
+      <p data-testid="reference-filter">
+        limit {filters.limit}
+        {filters.tags?.length ? ` · tags ${filters.tags.join(", ")}` : ""}
+      </p>
+      <AsyncSurface state={query.state} onRetry={query.retry}>
+        <ul aria-label="Reference resources">
+          {(query.data ?? []).map((resource) => (
+            <li
+              key={resource.resourceId}
+              data-optimistic={resource.optimistic || undefined}
+            >
+              {resource.title}
+            </li>
+          ))}
+        </ul>
+      </AsyncSurface>
+      <AsyncSurface
+        state={mutation.state}
+        onResolveConflict={mutation.resolveConflict}
+      >
+        <form onSubmit={(event) => void submit(event)}>
+          <label htmlFor="reference-resource-name">새 항목 이름</label>
+          <input
+            id="reference-resource-name"
+            value={name}
+            onChange={(event) => setName(event.currentTarget.value)}
+            required
+          />
+          <Button type="submit" disabled={mutation.state.overlay.mutationPending}>
+            추가
+          </Button>
+        </form>
+      </AsyncSurface>
+    </section>
+  );
+}

src/features/reference-feature/presentation/use-reference-feature.ts

@@ -0,0 +1,62 @@
+import { useApplication } from "../../../presentation/providers/application-provider.js";
+import {
+  useApplicationMutation,
+  useApplicationQuery,
+} from "../../../presentation/adapters/query/application-query.js";
+import { useRouteInput } from "../../../presentation/routes/app-router.js";
+import type { ReferenceResourceView } from "../contracts/reference-mapper.js";
+import {
+  REFERENCE_FEATURE_ID,
+  referenceQueryKeys,
+} from "../contracts/reference-feature-contract.js";
+import type {
+  ReferenceFeatureInput,
+  ReferenceListFilters,
+} from "../application/reference-feature-api.js";
+
+function useReferenceFeatureInput(): ReferenceFeatureInput {
+  const candidate = useApplication().features.get(REFERENCE_FEATURE_ID);
+  if (
+    !candidate ||
+    typeof candidate !== "object" ||
+    typeof (candidate as ReferenceFeatureInput).listResources !== "function" ||
+    typeof (candidate as ReferenceFeatureInput).createResource !== "function"
+  ) {
+    throw new Error("Reference feature application input is invalid");
+  }
+  return candidate as ReferenceFeatureInput;
+}
+
+export function useReferenceFeature() {
+  const input = useReferenceFeatureInput();
+  const routeInput = useRouteInput();
+  const filters = routeInput.search as ReferenceListFilters;
+  const queryKey = referenceQueryKeys.list(filters);
+  const query = useApplicationQuery({
+    queryKey,
+    execute: ({ signal }) => input.listResources(filters, { signal }),
+  });
+  const mutation = useApplicationMutation({
+    execute: input.createResource,
+    invalidate: [referenceQueryKeys.all()],
+    currentData: true,
+    optimistic: {
+      queryKey,
+      update(previous, command: Readonly<{ name: string }>) {
+        const current = Array.isArray(previous)
+          ? (previous as readonly ReferenceResourceView[])
+          : [];
+        return [
+          ...current,
+          {
+            resourceId: `optimistic:${command.name}`,
+            title: command.name,
+            createdAtLabel: null,
+            optimistic: true,
+          },
+        ];
+      },
+    },
+  });
+  return Object.freeze({ filters, query, mutation });
+}

src/presentation/adapters/query/application-query.ts

@@ -0,0 +1,194 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+} from "@tanstack/react-query";
+
+import {
+  deriveAsyncState,
+  type AsyncState,
+} from "../../../application/view-models/async-state.js";
+import type { ApiFailure } from "../../../contracts/errors.js";
+
+export type ApplicationResult<Value> =
+  | Readonly<{ ok: true; value: Value }>
+  | Readonly<{ ok: false; error: ApiFailure }>;
+
+class ApplicationQueryError extends Error {
+  readonly failure: ApiFailure;
+
+  constructor(failure: ApiFailure) {
+    super(failure.kind);
+    this.name = "ApplicationQueryError";
+    this.failure = failure;
+  }
+}
+
+export function useApplicationQuery<Value>(
+  options: Readonly<{
+    queryKey: readonly unknown[];
+    execute(context: Readonly<{ signal: AbortSignal }>): Promise<
+      ApplicationResult<Value>
+    >;
+    enabled?: boolean;
+  }>,
+): Readonly<{
+  data: Value | undefined;
+  state: AsyncState;
+  retry(): Promise<void>;
+}> {
+  const { queryKey, execute, enabled = true } = options;
+  const [staleFailure, setStaleFailure] = useState(false);
+  const query = useQuery<Value, ApplicationQueryError>({
+    queryKey,
+    enabled,
+    retry: false,
+    queryFn: async ({ signal }) => {
+      const result = await execute({ signal });
+      if (result.ok) return result.value;
+      if (signal.aborted || result.error.kind === "REQUEST_ABORTED") {
+        throw new DOMException("Query cancelled", "AbortError");
+      }
+      throw new ApplicationQueryError(result.error);
+    },
+  });
+  const hasData = query.data !== undefined && query.data !== null;
+
+  useEffect(() => {
+    if (query.isError && hasData) {
+      setStaleFailure(true);
+    } else if (query.isSuccess && !query.isFetching) {
+      setStaleFailure(false);
+    }
+  }, [hasData, query.isError, query.isFetching, query.isSuccess]);
+
+  const retry = useCallback(async () => {
+    setStaleFailure(false);
+    await query.refetch();
+  }, [query]);
+
+  return Object.freeze({
+    data: query.data,
+    state: deriveAsyncState({
+      data: query.data,
+      isInitialLoading: query.isPending,
+      failure:
+        !hasData && query.error instanceof ApplicationQueryError
+          ? query.error.failure
+          : undefined,
+      isFetching: query.isFetching && !query.isPending,
+      isStale: staleFailure,
+      isDegraded: staleFailure,
+    }),
+    retry,
+  });
+}
+
+export function useApplicationMutation<Input, Value>(
+  options: Readonly<{
+    execute(input: Input): Promise<ApplicationResult<Value>>;
+    invalidate?: readonly (readonly unknown[])[];
+    optimistic?: Readonly<{
+      queryKey: readonly unknown[];
+      update(previous: unknown, input: Input): unknown;
+    }>;
+    currentData?: unknown;
+  }>,
+): Readonly<{
+  state: AsyncState;
+  submit(input: Input): Promise<ApplicationResult<Value>>;
+  resolveConflict(): Promise<void>;
+}> {
+  const queryClient = useQueryClient();
+  const { execute, invalidate = [], optimistic, currentData } = options;
+  const [conflict, setConflict] = useState<ApiFailure | null>(null);
+  const inFlight = useRef<Promise<ApplicationResult<Value>> | null>(null);
+  const mutation = useMutation<Value, ApplicationQueryError, Input>({
+    retry: false,
+    mutationFn: async (input) => {
+      const result = await execute(input);
+      if (result.ok) return result.value;
+      throw new ApplicationQueryError(result.error);
+    },
+  });
+
+  const submit = useCallback(
+    (input: Input): Promise<ApplicationResult<Value>> => {
+      if (inFlight.current) return inFlight.current;
+      setConflict(null);
+      mutation.reset();
+
+      const previous = optimistic
+        ? queryClient.getQueryData(optimistic.queryKey)
+        : undefined;
+      if (optimistic) {
+        queryClient.setQueryData(
+          optimistic.queryKey,
+          optimistic.update(previous, input),
+        );
+      }
+
+      const pending = mutation
+        .mutateAsync(input)
+        .then(async (value) => {
+          for (const queryKey of invalidate) {
+            await queryClient.invalidateQueries({ queryKey, exact: false });
+          }
+          return { ok: true as const, value };
+        })
+        .catch((error: unknown) => {
+          if (optimistic) {
+            queryClient.setQueryData(optimistic.queryKey, previous);
+          }
+          const failure =
+            error instanceof ApplicationQueryError
+              ? error.failure
+              : unexpectedMutationFailure();
+          if (failure.kind === "CONFLICT") setConflict(failure);
+          return { ok: false as const, error: failure };
+        })
+        .finally(() => {
+          inFlight.current = null;
+        });
+      inFlight.current = pending;
+      return pending;
+    },
+    [invalidate, mutation, optimistic, queryClient],
+  );
+
+  const resolveConflict = useCallback(async () => {
+    setConflict(null);
+    mutation.reset();
+    for (const queryKey of invalidate) {
+      await queryClient.invalidateQueries({ queryKey, exact: false });
+    }
+  }, [invalidate, mutation, queryClient]);
+
+  return Object.freeze({
+    state: deriveAsyncState({
+      data: currentData ?? true,
+      isMutationPending: mutation.isPending,
+      hasMutationConflict: conflict !== null,
+    }),
+    submit,
+    resolveConflict,
+  });
+}
+
+function unexpectedMutationFailure(): ApiFailure {
+  return {
+    kind: "UNKNOWN_FAILURE",
+    code: "UNKNOWN_FAILURE",
+    retryable: false,
+    operationId: "APPLICATION_MUTATION",
+    attemptCount: 1,
+    userMessageKey: "error.unknown_failure",
+    action: "contact-support",
+  };
+}

src/presentation/adapters/query/index.ts

@@ -0,0 +1,5 @@
+export {
+  useApplicationMutation,
+  useApplicationQuery,
+  type ApplicationResult,
+} from "./application-query.js";

src/presentation/boundaries/chunk-recovery-boundary.tsx

@@ -0,0 +1,97 @@
+import {
+  Component,
+  type ErrorInfo,
+  type ReactNode,
+} from "react";
+
+type RecoveryResult =
+  | Readonly<{ action: "reload-once"; releasePair: string }>
+  | Readonly<{ action: "support"; reason: string }>;
+
+type Props = Readonly<{
+  children: ReactNode;
+  chunkId: string;
+  recover(input: Readonly<{
+    chunkId: string;
+    failureKind: "CHUNK_LOAD_FAILURE";
+  }>): Promise<RecoveryResult>;
+}>;
+
+type State = Readonly<{
+  error: unknown | null;
+  recovery: "idle" | "checking" | "reload-requested" | "support";
+  reason?: string;
+}>;
+
+export function isChunkLoadFailure(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const value = `${error.name} ${error.message}`.toLowerCase();
+  return (
+    value.includes("chunkloaderror") ||
+    value.includes("loading chunk") ||
+    value.includes("dynamically imported module") ||
+    value.includes("failed to fetch module script")
+  );
+}
+
+export class ChunkRecoveryBoundary extends Component<Props, State> {
+  state: State = { error: null, recovery: "idle" };
+
+  static getDerivedStateFromError(error: unknown): State {
+    return { error, recovery: "checking" };
+  }
+
+  componentDidCatch(error: unknown, _info: ErrorInfo) {
+    if (!isChunkLoadFailure(error)) return;
+    void this.props
+      .recover({
+        chunkId: this.props.chunkId,
+        failureKind: "CHUNK_LOAD_FAILURE",
+      })
+      .then((result) => {
+        this.setState({
+          error,
+          recovery:
+            result.action === "reload-once"
+              ? "reload-requested"
+              : "support",
+          ...(result.action === "support" ? { reason: result.reason } : {}),
+        });
+      })
+      .catch(() => {
+        this.setState({
+          error,
+          recovery: "support",
+          reason: "recovery-controller-failed",
+        });
+      });
+  }
+
+  render() {
+    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>
+      );
+    }
+    if (error && recovery === "reload-requested") {
+      return (
+        <section className="ui-page" aria-live="polite">
+          새 버전으로 한 번만 전환합니다.
+        </section>
+      );
+    }
+    if (error && recovery === "support") {
+      return (
+        <section className="ui-page" role="alert" data-recovery-reason={reason}>
+          <h1>화면 자산을 복구하지 못했습니다.</h1>
+          <p>문제가 계속되면 배포 상태와 지원 참조 정보를 확인해 주세요.</p>
+        </section>
+      );
+    }
+    return this.props.children;
+  }
+}

src/presentation/boundaries/render-error-boundary.jsx

@@ -6,6 +6,7 @@ import { Component } from "react";
  *   boundaryName: string,
  *   routeId: string,
  *   buildId: string,
+ *   resetKey?: string,
  *   onRenderFailure?: (report: import("../../application/ports/in/application-api.js").RenderFailureReport) => void,
  *   fallback?: React.ReactNode
  * }} RenderBoundaryProps
@@ -37,6 +38,16 @@ export class RenderErrorBoundary extends Component {
     }
   }
 
+  /** @param {RenderBoundaryProps} previous */
+  componentDidUpdate(previous) {
+    if (
+      this.state.hasError &&
+      previous.resetKey !== this.props.resetKey
+    ) {
+      this.setState({ hasError: false });
+    }
+  }
+
   reset = () => {
     this.setState({ hasError: false });
   };

src/presentation/components/async-surface.jsx

@@ -65,7 +65,7 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
       data-message-key={userMessageKey}
     >
       <h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
-      {action !== "none" && (
+      {action !== "none" && onAction && (
         <Button onClick={onAction}>{actionLabels[action]}</Button>
       )}
     </section>
@@ -76,10 +76,18 @@ export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
  * @param {{
  *   state: ReturnType<typeof import("../../application/view-models/async-state.js").deriveAsyncState>,
  *   children?: React.ReactNode,
- *   onAction?: () => void
+ *   onAction?: () => void,
+ *   onRetry?: () => void,
+ *   onResolveConflict?: () => void
  * }} props
  */
-export function AsyncSurface({ state, children, onAction }) {
+export function AsyncSurface({
+  state,
+  children,
+  onAction,
+  onRetry,
+  onResolveConflict,
+}) {
   if (state.base === "initial-loading") return <LoadingSurface />;
   if (state.base === "empty") return <EmptySurface />;
   if (state.base === "terminal-error" && state.failure) {
@@ -87,18 +95,24 @@ export function AsyncSurface({ state, children, onAction }) {
       <TerminalErrorSurface
         userMessageKey={state.failure.userMessageKey}
         action={state.failure.action}
-        onAction={onAction}
+        onAction={onRetry ?? onAction}
       />
     );
   }
 
   return (
     <section aria-busy={state.overlay.refreshing || state.overlay.mutationPending}>
-      {state.indicator && (
+      {state.indicator ? (
-        <p role="status" aria-live="polite">
+        <div role="status" aria-live="polite">
-          {state.indicator}
+          <span>{state.indicator}</span>
-        </p>
+          {state.indicator === "stale-degraded" && onRetry ? (
-      )}
+            <Button onClick={onRetry}>다시 시도</Button>
+          ) : null}
+          {state.indicator === "mutation-conflict" && onResolveConflict ? (
+            <Button onClick={onResolveConflict}>충돌 해결</Button>
+          ) : null}
+        </div>
+      ) : null}
       {children}
     </section>
   );

src/presentation/components/error-copy.js

@@ -8,6 +8,11 @@ const ERROR_MESSAGES = Object.freeze({
   "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": "예상하지 못한 문제가 발생했습니다.",
 });

src/presentation/components/page-header.jsx

@@ -11,7 +11,6 @@ export function PageHeader({ title, description, eyebrow }) {
   const headingRef = useRef(/** @type {HTMLHeadingElement | null} */ (null));
 
   useEffect(() => {
-    document.title = `${title} · Frontend Skeleton`;
     headingRef.current?.focus();
   }, [title]);
 

src/presentation/layouts/app-shell.jsx

@@ -1,7 +1,10 @@
 import { useEffect, useState } from "react";
 import { NavLink, Outlet, useLocation } from "react-router-dom";
 
-import { NAVIGATION_ROUTES, routePath } from "../../contracts/routes.js";
+import {
+  NAVIGATION_ROUTES,
+  routePath,
+} from "../../features/installed-feature-contracts.js";
 import { useSession } from "../providers/session-provider.jsx";
 import { useTheme } from "../providers/theme-provider.jsx";
 

src/presentation/pages/home-page.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react";
 import { Link } from "react-router-dom";
 
-import { routePath } from "../../contracts/routes.js";
+import { routePath } from "../../features/installed-feature-contracts.js";
 import { PageHeader } from "../components/page-header.jsx";
 import { useApplication } from "../providers/application-provider.js";
 

src/presentation/pages/not-found-page.jsx

@@ -1,6 +1,6 @@
 import { Link } from "react-router-dom";
 
-import { routePath } from "../../contracts/routes.js";
+import { routePath } from "../../features/installed-feature-contracts.js";
 import { PageHeader } from "../components/page-header.jsx";
 
 export default function NotFoundPage() {

src/presentation/pages/sample-contract-page.jsx

@@ -1,23 +0,0 @@
-import { PageHeader } from "../components/page-header.jsx";
-import { useSession } from "../providers/session-provider.jsx";
-
-export default function SampleContractPage() {
-  const { sessionState } = useSession();
-
-  return (
-    <section className="ui-page">
-      <PageHeader
-        eyebrow="보호 라우트"
-        title="보호된 연동 지점"
-        description="실제 도메인 기능이 인증된 세션과 연결되는 위치를 보여주는 중립적인 계약 화면입니다."
-      />
-      <section className="ui-panel" aria-labelledby="protected-state-title">
-        <h2 id="protected-state-title">라우트 접근 허용</h2>
-        <p>
-          현재 세션 상태는 <strong>{sessionState}</strong>입니다. 서버의
-          권한 검증은 이 클라이언트 라우트 정책과 별도로 유지해야 합니다.
-        </p>
-      </section>
-    </section>
-  );
-}

src/presentation/routes/app-router.jsx

@@ -1,260 +0,0 @@
-import { lazy, Suspense, useState } from "react";
-import {
-  BrowserRouter,
-  Route,
-  Routes,
-  useLocation,
-} from "react-router-dom";
-
-import { getRoute, routePath } from "../../contracts/routes.js";
-import { RouteBoundary } from "../boundaries/render-error-boundary.jsx";
-import { AppShell } from "../layouts/app-shell.jsx";
-import { PageHeader } from "../components/page-header.jsx";
-import { useApplication } from "../providers/application-provider.js";
-import { SessionProvider, useSession } from "../providers/session-provider.jsx";
-import { ThemeProvider } from "../providers/theme-provider.jsx";
-import { decideRouteAccess } from "./navigation-policy.js";
-
-const HomePage = lazy(() => import("../pages/home-page.jsx"));
-const UiGalleryPage = lazy(() => import("../examples/ui-gallery-page.jsx"));
-const StateGalleryPage = lazy(
-  () => import("../examples/state-gallery-page.jsx"),
-);
-const AuthExamplePage = lazy(
-  () => import("../examples/auth-example-page.jsx"),
-);
-const SampleContractPage = lazy(
-  () => import("../pages/sample-contract-page.jsx"),
-);
-const NotFoundPage = lazy(() => import("../pages/not-found-page.jsx"));
-
-/** @param {{ routeId: string }} props */
-function RouteLoadingSurface({ routeId }) {
-  const definition = getRoute(routeId);
-  return (
-    <section className="ui-page route-loading" aria-live="polite" aria-busy="true">
-      <div className="ui-skeleton" aria-hidden="true" />
-      <p>화면을 준비하고 있습니다.</p>
-      <span className="visually-hidden">{definition.title} 로딩 중</span>
-    </section>
-  );
-}
-
-function RouteFailureSurface() {
-  return (
-    <section className="ui-page">
-      <PageHeader
-        title="화면을 표시하지 못했습니다."
-        description="잠시 후 페이지를 새로고침해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
-      />
-    </section>
-  );
-}
-
-/**
- * @param {{
- *   routeId: string,
- *   buildId: string,
- *   children: React.ReactNode
- * }} props
- */
-function RouteSurface({ routeId, buildId, children }) {
-  const { diagnostics } = useApplication();
-  return (
-    <RouteBoundary
-      routeId={routeId}
-      buildId={buildId}
-      onRenderFailure={diagnostics.reportRenderFailure}
-      fallback={<RouteFailureSurface />}
-    >
-      <Suspense fallback={<RouteLoadingSurface routeId={routeId} />}>
-        {children}
-      </Suspense>
-    </RouteBoundary>
-  );
-}
-
-/**
- * @param {{
- *   routeId: string,
- *   children: React.ReactNode
- * }} props
- */
-function ProtectedRoute({ routeId, children }) {
-  const location = useLocation();
-  const { sessionState, beginSignIn, recover } = useSession();
-  const [pending, setPending] = useState(false);
-  const [failed, setFailed] = useState(false);
-  const decision = decideRouteAccess(routeId, sessionState);
-
-  async function continueSession() {
-    setPending(true);
-    setFailed(false);
-    try {
-      if (decision.action === "wait-for-session") {
-        await recover();
-      } else {
-        await beginSignIn(
-          `${location.pathname}${location.search}${location.hash}`,
-        );
-      }
-    } catch {
-      setFailed(true);
-    } finally {
-      setPending(false);
-    }
-  }
-
-  if (decision.allowed) return children;
-
-  if (sessionState === "integration-failed") {
-    return (
-      <section className="ui-page">
-        <PageHeader
-          title="로그인 연동이 필요합니다."
-          description="외부 인증 소유자가 런타임에 연결되면 이 보호 라우트를 사용할 수 있습니다."
-        />
-      </section>
-    );
-  }
-
-  const recovering = decision.action === "wait-for-session";
-  return (
-    <section className="ui-page">
-      <PageHeader
-        title={recovering ? "세션을 복구하고 있습니다." : "세션이 필요합니다."}
-        description={
-          recovering
-            ? "기존 세션 확인을 계속하려면 복구를 실행하세요."
-            : "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."
-        }
-      />
-      <div>
-        <button
-          className="ui-button"
-          type="button"
-          disabled={pending}
-          onClick={() => void continueSession()}
-        >
-          {pending
-            ? "처리 중…"
-            : recovering
-              ? "세션 복구"
-              : "로그인 시작"}
-        </button>
-      </div>
-      {failed ? (
-        <p className="ui-terminal-error" role="alert">
-          세션 작업을 완료하지 못했습니다.
-        </p>
-      ) : null}
-    </section>
-  );
-}
-
-/**
- * @param {{
- *   routeId: string,
- *   buildId: string,
- *   children: React.ReactNode
- * }} props
- */
-function PublicRoute({ routeId, buildId, children }) {
-  return (
-    <RouteSurface routeId={routeId} buildId={buildId}>
-      {children}
-    </RouteSurface>
-  );
-}
-
-/**
- * @param {{
- *   basename?: string,
- *   buildId?: string
- * }} props
- */
-export function AppRouter({
-  basename = "/",
-  buildId = "local-build",
-}) {
-  return (
-    <BrowserRouter basename={basename}>
-      <ThemeProvider>
-        <SessionProvider>
-          <Routes>
-            <Route element={<AppShell />}>
-            <Route
-              index
-              element={
-                <PublicRoute
-                  routeId="APP_HOME"
-                  buildId={buildId}
-                >
-                  <HomePage />
-                </PublicRoute>
-              }
-            />
-            <Route
-              path={routePath("EXAMPLES_UI")}
-              element={
-                <PublicRoute
-                  routeId="EXAMPLES_UI"
-                  buildId={buildId}
-                >
-                  <UiGalleryPage />
-                </PublicRoute>
-              }
-            />
-            <Route
-              path={routePath("EXAMPLES_STATES")}
-              element={
-                <PublicRoute
-                  routeId="EXAMPLES_STATES"
-                  buildId={buildId}
-                >
-                  <StateGalleryPage />
-                </PublicRoute>
-              }
-            />
-            <Route
-              path={routePath("EXAMPLES_AUTH")}
-              element={
-                <PublicRoute
-                  routeId="EXAMPLES_AUTH"
-                  buildId={buildId}
-                >
-                  <AuthExamplePage />
-                </PublicRoute>
-              }
-            />
-            <Route
-              path={routePath("SAMPLE_RESOURCE_LIST")}
-              element={
-                <RouteSurface
-                  routeId="SAMPLE_RESOURCE_LIST"
-                  buildId={buildId}
-                >
-                  <ProtectedRoute routeId="SAMPLE_RESOURCE_LIST">
-                    <SampleContractPage />
-                  </ProtectedRoute>
-                </RouteSurface>
-              }
-            />
-            <Route
-              path={routePath("NOT_FOUND")}
-              element={
-                <PublicRoute
-                  routeId="NOT_FOUND"
-                  buildId={buildId}
-                >
-                  <NotFoundPage />
-                </PublicRoute>
-              }
-            />
-            </Route>
-          </Routes>
-        </SessionProvider>
-      </ThemeProvider>
-    </BrowserRouter>
-  );
-}

src/presentation/routes/app-router.tsx

@@ -0,0 +1,309 @@
+import {
+  createContext,
+  type ReactNode,
+  Suspense,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import {
+  createBrowserRouter,
+  RouterProvider,
+  type RouteObject,
+  useLocation,
+  useNavigate,
+  useParams,
+  useSearchParams,
+} from "react-router-dom";
+
+import {
+  getRoute,
+  ROUTE_REGISTRY,
+} from "../../features/installed-feature-contracts.js";
+import type { RouteDefinition } from "../../contracts/routes.js";
+import {
+  FeatureBoundary,
+  RouteBoundary,
+} from "../boundaries/render-error-boundary.jsx";
+import { ChunkRecoveryBoundary } from "../boundaries/chunk-recovery-boundary.js";
+import { PageHeader } from "../components/page-header.jsx";
+import { AppShell } from "../layouts/app-shell.jsx";
+import { useApplication } from "../providers/application-provider.js";
+import { SessionProvider, useSession } from "../providers/session-provider.jsx";
+import { ThemeProvider } from "../providers/theme-provider.jsx";
+import {
+  createRedirectLoopGuard,
+  decideRouteAccess,
+} from "./navigation-policy.js";
+import {
+  buildRouteUrl,
+  parseRouteInput,
+  type ParsedRouteInput,
+  type RouteId,
+} from "./route-codecs.js";
+import { ROUTE_RUNTIME } from "../../features/installed-feature-runtimes.js";
+
+const RouteInputContext = createContext<ParsedRouteInput | null>(null);
+
+export function useRouteInput(): ParsedRouteInput {
+  const input = useContext(RouteInputContext);
+  if (!input) throw new Error("Registered route input is required");
+  return input;
+}
+
+function RouteLoadingSurface({ definition }: { definition: RouteDefinition }) {
+  return (
+    <section
+      className="ui-page route-loading"
+      aria-live="polite"
+      aria-busy="true"
+      data-surface={definition.loadingSurface}
+    >
+      <div className="ui-skeleton" aria-hidden="true" />
+      <p>화면을 준비하고 있습니다.</p>
+      <span className="visually-hidden">{definition.title} 로딩 중</span>
+    </section>
+  );
+}
+
+function RouteFailureSurface({
+  definition,
+}: {
+  definition?: RouteDefinition;
+}) {
+  return (
+    <section
+      className="ui-page"
+      data-surface={definition?.errorSurface ?? "route-boundary"}
+    >
+      <PageHeader
+        title="화면을 표시하지 못했습니다."
+        description="잠시 후 다시 시도해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
+      />
+    </section>
+  );
+}
+
+function InvalidRouteSurface({ code }: { code: string }) {
+  return (
+    <section className="ui-page" data-surface="invalid-route">
+      <PageHeader
+        title="올바르지 않은 주소입니다."
+        description="주소의 경로 또는 검색 조건을 확인해 주세요."
+      />
+      <p data-route-error={code}>안전한 탐색 링크를 사용해 주세요.</p>
+    </section>
+  );
+}
+
+function RouteLifecycle({ definition }: { definition: RouteDefinition }) {
+  const location = useLocation();
+  useEffect(() => {
+    document.title = `${definition.title} · Frontend Skeleton`;
+    const main = document.getElementById("main-content");
+    main?.focus({ preventScroll: true });
+    try {
+      if (!navigator.userAgent.toLowerCase().includes("jsdom")) {
+        window.scrollTo({ top: 0, left: 0, behavior: "auto" });
+      }
+    } catch {
+      // Non-browser test hosts may not implement scrolling.
+    }
+  }, [definition, location.key, location.pathname]);
+  return null;
+}
+
+function CanonicalRouteRedirect({
+  input,
+}: {
+  input: ParsedRouteInput;
+}) {
+  const location = useLocation();
+  const navigate = useNavigate();
+  const guard = useRef(createRedirectLoopGuard(3));
+  useEffect(() => {
+    if (input.routeId === "NOT_FOUND") return;
+    const source = `${location.pathname}${location.search}`;
+    const target = buildRouteUrl(input.routeId, {
+      params: input.params,
+      search: input.search,
+    });
+    if (source !== target && guard.current.allow(source, target)) {
+      void navigate(target, { replace: true });
+    }
+  }, [input, location.pathname, location.search, navigate]);
+  return null;
+}
+
+function ProtectedRoute({
+  routeId,
+  children,
+}: {
+  routeId: RouteId;
+  children: ReactNode;
+}) {
+  const location = useLocation();
+  const { sessionState, beginSignIn, recover } = useSession();
+  const [pending, setPending] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const decision = decideRouteAccess(routeId, sessionState);
+
+  async function continueSession() {
+    setPending(true);
+    setFailed(false);
+    try {
+      if (decision.action === "wait-for-session") {
+        await recover();
+      } else {
+        await beginSignIn(
+          `${location.pathname}${location.search}${location.hash}`,
+        );
+      }
+    } catch {
+      setFailed(true);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  if (decision.allowed) return children;
+  if (sessionState === "integration-failed") {
+    return (
+      <section className="ui-page" data-surface="auth-integration-required">
+        <PageHeader
+          title="로그인 연동이 필요합니다."
+          description="외부 인증 소유자가 연결되면 이 보호 라우트를 사용할 수 있습니다."
+        />
+      </section>
+    );
+  }
+  const recovering = decision.action === "wait-for-session";
+  return (
+    <section className="ui-page" data-surface="authentication-required">
+      <PageHeader
+        title={recovering ? "세션을 복구하고 있습니다." : "세션이 필요합니다."}
+        description={
+          recovering
+            ? "기존 세션 확인을 계속하려면 복구를 실행하세요."
+            : "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."
+        }
+      />
+      <button
+        className="ui-button"
+        type="button"
+        disabled={pending}
+        onClick={() => void continueSession()}
+      >
+        {pending ? "처리 중…" : recovering ? "세션 복구" : "로그인 시작"}
+      </button>
+      {failed ? (
+        <p className="ui-terminal-error" role="alert">
+          세션 작업을 완료하지 못했습니다.
+        </p>
+      ) : null}
+    </section>
+  );
+}
+
+function RegisteredRoute({
+  routeId,
+  buildId,
+}: {
+  routeId: RouteId;
+  buildId: string;
+}) {
+  const definition = getRoute(routeId);
+  const runtime = ROUTE_RUNTIME[routeId];
+  const params = useParams();
+  const [search] = useSearchParams();
+  const location = useLocation();
+  const { diagnostics, recovery } = useApplication();
+  const parsed = parseRouteInput(routeId, params, search);
+  if (!parsed.success) return <InvalidRouteSurface code={parsed.code} />;
+
+  const content = (
+    <RouteInputContext.Provider value={parsed.data}>
+      <CanonicalRouteRedirect input={parsed.data} />
+      <RouteLifecycle definition={definition} />
+      <Suspense fallback={<RouteLoadingSurface definition={definition} />}>
+        <ChunkRecoveryBoundary
+          chunkId={definition.chunkId}
+          recover={recovery.recoverChunk}
+        >
+          <runtime.Component />
+        </ChunkRecoveryBoundary>
+      </Suspense>
+    </RouteInputContext.Provider>
+  );
+  const protectedContent =
+    definition.access === "public" ? (
+      content
+    ) : (
+      <ProtectedRoute routeId={routeId}>{content}</ProtectedRoute>
+    );
+  const boundaryProps = {
+    routeId,
+    buildId,
+    resetKey: `${location.pathname}${location.search}`,
+    onRenderFailure: diagnostics.reportRenderFailure,
+    fallback: <RouteFailureSurface definition={definition} />,
+    children: protectedContent,
+  };
+  return definition.errorSurface === "feature-boundary" ? (
+    <FeatureBoundary {...boundaryProps} />
+  ) : (
+    <RouteBoundary {...boundaryProps} />
+  );
+}
+
+function createRegisteredRoutes(buildId: string): RouteObject[] {
+  const children = Object.values(ROUTE_REGISTRY).map((definition) => {
+    const routeId = definition.routeId as RouteId;
+    if (definition.path === "/") {
+      return {
+        id: routeId,
+        index: true,
+        element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
+      };
+    }
+    return {
+      id: routeId,
+      path:
+        definition.path === "*"
+          ? "*"
+          : definition.path.replace(/^\//, ""),
+      element: <RegisteredRoute routeId={routeId} buildId={buildId} />,
+    };
+  });
+  return [
+    {
+      id: "APP_SHELL",
+      path: "/",
+      element: <AppShell />,
+      errorElement: <RouteFailureSurface />,
+      children,
+    },
+  ];
+}
+
+export function AppRouter({
+  basename = "/",
+  buildId = "local-build",
+}: Readonly<{ basename?: string; buildId?: string }>) {
+  const router = useMemo(
+    () =>
+      createBrowserRouter(createRegisteredRoutes(buildId), {
+        basename,
+      }),
+    [basename, buildId],
+  );
+  return (
+    <ThemeProvider>
+      <SessionProvider>
+        <RouterProvider router={router} />
+      </SessionProvider>
+    </ThemeProvider>
+  );
+}

src/presentation/routes/navigation-policy.js

@@ -1,4 +1,4 @@
-import { getRoute } from "../../contracts/routes.js";
+import { getRoute } from "../../features/installed-feature-contracts.js";
 
 /**
  * @param {string} routeId
@@ -16,8 +16,10 @@ export function decideRouteAccess(routeId, sessionState) {
   return { allowed: false, action: "show-sign-in" };
 }
 
-export function createRedirectLoopGuard() {
+/** @param {number} [maxHops] */
+export function createRedirectLoopGuard(maxHops = 5) {
   const visitedPairs = new Set();
+  let hops = 0;
 
   return Object.freeze({
     /**
@@ -26,12 +28,23 @@ export function createRedirectLoopGuard() {
      */
     allow(source, target) {
       const pair = `${source}->${target}`;
-      if (source === target || visitedPairs.has(pair)) return false;
+      if (
+        source === target ||
+        visitedPairs.has(pair) ||
+        hops >= maxHops
+      ) {
+        return false;
+      }
       visitedPairs.add(pair);
+      hops += 1;
       return true;
     },
     reset() {
       visitedPairs.clear();
+      hops = 0;
+    },
+    get hopCount() {
+      return hops;
     },
   });
 }

src/presentation/routes/platform-route-codecs.ts

@@ -0,0 +1,6 @@
+import { z } from "zod";
+
+export const PLATFORM_ROUTE_CODECS = {
+  none: z.object({}).strict(),
+  NotFoundSplat: z.object({ "*": z.string().optional() }).strict(),
+} as const;

src/presentation/routes/route-codecs.ts

@@ -0,0 +1,110 @@
+import { getRoute, ROUTE_RUNTIME_CONTRACT } from "../../features/installed-feature-contracts.js";
+import { ROUTE_CODECS } from "../../features/installed-feature-runtimes.js";
+
+export type RouteId = keyof typeof ROUTE_RUNTIME_CONTRACT;
+
+export type ParsedRouteInput = Readonly<{
+  routeId: RouteId;
+  params: Readonly<Record<string, unknown>>;
+  search: Readonly<Record<string, unknown>>;
+}>;
+
+export type RouteInputResult =
+  | Readonly<{ success: true; data: ParsedRouteInput }>
+  | Readonly<{
+      success: false;
+      code: "ROUTE_PARAMS_INVALID" | "ROUTE_SEARCH_INVALID";
+    }>;
+
+function codecById(codecId: string) {
+  const codec = ROUTE_CODECS[codecId as keyof typeof ROUTE_CODECS];
+  if (!codec) throw new TypeError(`Unregistered route codec: ${codecId}`);
+  return codec;
+}
+
+export function parseRouteInput(
+  routeId: RouteId,
+  rawParams: Readonly<Record<string, string | undefined>>,
+  rawSearch: URLSearchParams,
+): RouteInputResult {
+  const runtime = ROUTE_RUNTIME_CONTRACT[routeId];
+  const params = codecById(runtime.paramsCodec).safeParse(rawParams);
+  if (!params.success) {
+    return { success: false, code: "ROUTE_PARAMS_INVALID" };
+  }
+  const search = codecById(runtime.searchCodec).safeParse(
+    searchRecord(rawSearch),
+  );
+  if (!search.success) {
+    return { success: false, code: "ROUTE_SEARCH_INVALID" };
+  }
+  const parsedParams: Record<string, unknown> = { ...params.data };
+  const parsedSearch: Record<string, unknown> = { ...search.data };
+  return {
+    success: true,
+    data: Object.freeze({
+      routeId,
+      params: Object.freeze(parsedParams),
+      search: Object.freeze(parsedSearch),
+    }),
+  };
+}
+
+export function buildRouteUrl(
+  routeId: RouteId,
+  input: Readonly<{
+    params?: Readonly<Record<string, unknown>>;
+    search?: Readonly<Record<string, unknown>>;
+  }> = {},
+): string {
+  const definition = getRoute(routeId);
+  if (definition.path === "*") {
+    throw new TypeError("The not-found route cannot build a canonical URL");
+  }
+  const runtime = ROUTE_RUNTIME_CONTRACT[routeId];
+  const params = codecById(runtime.paramsCodec).parse(input.params ?? {});
+  const search = codecById(runtime.searchCodec).parse(input.search ?? {});
+  const parsedParams: Record<string, unknown> = { ...params };
+  const parsedSearch: Record<string, unknown> = { ...search };
+  let path = definition.path;
+  path = path.replace(
+    /:([A-Za-z][A-Za-z0-9_]*)|\{([A-Za-z][A-Za-z0-9_]*)\}/g,
+    (
+      _token: string,
+      colonName: string | undefined,
+      braceName: string | undefined,
+    ) => {
+      const name = colonName ?? braceName ?? "";
+      const value = parsedParams[name];
+      if (typeof value !== "string" && typeof value !== "number") {
+        throw new TypeError(`Missing route path parameter: ${name}`);
+      }
+      return encodeURIComponent(String(value));
+    },
+  );
+  const query = new URLSearchParams();
+  for (const key of Object.keys(parsedSearch).sort((left, right) =>
+    left.localeCompare(right),
+  )) {
+    const value = parsedSearch[key];
+    if (value === undefined || value === null) continue;
+    for (const item of Array.isArray(value) ? value : [value]) {
+      query.append(key, String(item));
+    }
+  }
+  const serialized = query.toString();
+  return serialized ? `${path}?${serialized}` : path;
+}
+
+function searchRecord(
+  search: URLSearchParams,
+): Readonly<Record<string, string | readonly string[]>> {
+  const result: Record<string, string | readonly string[]> = {};
+  for (const key of [...new Set(search.keys())].sort((left, right) =>
+    left.localeCompare(right),
+  )) {
+    const values = search.getAll(key);
+    result[key] = values.length === 1 ? values[0] : values;
+  }
+  return result;
+}

src/presentation/routes/route-runtime.tsx

@@ -0,0 +1,43 @@
+import {
+  lazy,
+  type ComponentType,
+  type LazyExoticComponent,
+} from "react";
+
+import { PLATFORM_ROUTE_RUNTIME_CONTRACT } from "../../contracts/route-runtime-contract.js";
+
+type RouteModule = Readonly<{ default: ComponentType }>;
+type RouteRuntime = Readonly<{
+  moduleId: string;
+  Component: LazyExoticComponent<ComponentType>;
+}>;
+
+function runtime(
+  routeId: keyof typeof PLATFORM_ROUTE_RUNTIME_CONTRACT,
+  load: () => Promise<RouteModule>,
+): RouteRuntime {
+  return Object.freeze({
+    moduleId: PLATFORM_ROUTE_RUNTIME_CONTRACT[routeId].moduleId,
+    Component: lazy(load),
+  });
+}
+
+export const PLATFORM_ROUTE_RUNTIME = {
+  APP_HOME: runtime("APP_HOME", () => import("../pages/home-page.jsx")),
+  EXAMPLES_UI: runtime(
+    "EXAMPLES_UI",
+    () => import("../examples/ui-gallery-page.jsx"),
+  ),
+  EXAMPLES_STATES: runtime(
+    "EXAMPLES_STATES",
+    () => import("../examples/state-gallery-page.jsx"),
+  ),
+  EXAMPLES_AUTH: runtime(
+    "EXAMPLES_AUTH",
+    () => import("../examples/auth-example-page.jsx"),
+  ),
+  NOT_FOUND: runtime(
+    "NOT_FOUND",
+    () => import("../pages/not-found-page.jsx"),
+  ),
+} satisfies Record<keyof typeof PLATFORM_ROUTE_RUNTIME_CONTRACT, RouteRuntime>;

src/sample/contract-fixture/design-token-showcase.jsx

@@ -1,15 +0,0 @@
-export function DesignTokenShowcase() {
-  return (
-    <section className="ui-panel" aria-labelledby="token-showcase-title">
-      <h2 id="token-showcase-title" className="text-xl font-semibold">
-        Design token fixture
-      </h2>
-      <p className="text-content-muted">
-        Semantic tokens style loading, empty, and terminal surfaces.
-      </p>
-      <button className="ui-button" type="button">
-        Token action
-      </button>
-    </section>
-  );
-}

src/sample/contract-fixture/sample-facade.js

@@ -1,53 +0,0 @@
-import { toResourceViewModel } from "../../application/view-models/resource-view-model.js";
-import { queryKeys } from "../../contracts/query-keys.js";
-
-/**
- * @param {{
- *   http: { execute(operationId: string, input?: Record<string, unknown>): Promise<
- *     {ok: true, value: unknown} | {ok: false, error: import("../../contracts/errors.js").ApiFailure}
- *   > },
- *   cache: import("../../application/ports/query-cache-port.js").QueryCachePort
- * }} ports
- */
-export function createSampleFacade(ports) {
-  return Object.freeze({
-    async listResources(filters = {}) {
-      const key = queryKeys.resource.list(filters);
-      const result = await ports.http.execute("LIST_SAMPLE_RESOURCES", {
-        routeId: "SAMPLE_RESOURCE_LIST",
-      });
-      if (!result.ok) return result;
-
-      const models =
-        /** @type {Array<import("../../domain/models/resource.js").Resource>} */ (
-          result.value
-        );
-      const cached = ports.cache.write(key, models);
-      if (!cached.ok) return cached;
-      return {
-        ok: /** @type {true} */ (true),
-        value: models.map((model) => toResourceViewModel(model)),
-      };
-    },
-
-    /** @param {{ name: string }} command */
-    async createResource(command) {
-      const result = await ports.http.execute("CREATE_SAMPLE_RESOURCE", {
-        body: command,
-        routeId: "SAMPLE_RESOURCE_LIST",
-      });
-      if (!result.ok) return result;
-
-      const invalidated = await ports.cache.invalidate(queryKeys.resource.all());
-      if (!invalidated.ok) return invalidated;
-      return {
-        ok: /** @type {true} */ (true),
-        value: toResourceViewModel(
-          /** @type {import("../../domain/models/resource.js").Resource} */ (
-            result.value
-          ),
-        ),
-      };
-    },
-  });
-}

src/sample/contract-fixture/sample-resource-page.jsx

@@ -1,61 +0,0 @@
-import { useEffect, useState } from "react";
-
-import { deriveAsyncState } from "../../application/view-models/async-state.js";
-import { AsyncSurface } from "../../presentation/components/async-surface.jsx";
-
-/**
- * @typedef {{
- *   loading: boolean,
- *   resources?: Array<{resourceId: string, title: string, createdAtLabel: string | null}>,
- *   failure?: import("../../contracts/errors.js").ApiFailure
- * }} SamplePageState
- */
-
-/**
- * @param {{
- *   facade: ReturnType<typeof import("./sample-facade.js").createSampleFacade>
- * }} props
- */
-export function SampleResourcePage({ facade }) {
-  const [result, setResult] = useState(
-    /** @type {SamplePageState} */ ({
-      loading: true,
-      resources: undefined,
-      failure: undefined,
-    }),
-  );
-
-  useEffect(() => {
-    let active = true;
-    void facade.listResources().then((outcome) => {
-      if (!active) return;
-      setResult(
-        outcome.ok
-          ? { loading: false, resources: outcome.value, failure: undefined }
-          : { loading: false, resources: undefined, failure: outcome.error },
-      );
-    });
-    return () => {
-      active = false;
-    };
-  }, [facade]);
-
-  const state = deriveAsyncState({
-    isInitialLoading: result.loading,
-    data: result.resources,
-    failure: result.failure,
-  });
-
-  return (
-    <main>
-      <h1>샘플 리소스</h1>
-      <AsyncSurface state={state}>
-        <ul>
-          {(result.resources ?? []).map((resource) => (
-            <li key={resource.resourceId}>{resource.title}</li>
-          ))}
-        </ul>
-      </AsyncSurface>
-    </main>
-  );
-}

tests/component/application-query.test.jsx

@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+
+import {
+  act,
+  renderHook,
+  waitFor,
+} from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  useApplicationMutation,
+  useApplicationQuery,
+} from "../../src/presentation/adapters/query/application-query.js";
+import { createFailure } from "../../src/contracts/errors.js";
+
+function queryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, staleTime: 0, gcTime: Infinity },
+      mutations: { retry: false },
+    },
+  });
+}
+
+/** @param {QueryClient} client */
+function wrapper(client) {
+  /** @param {{children: React.ReactNode}} props */
+  return function QueryWrapper({ children }) {
+    return (
+      <QueryClientProvider client={client}>{children}</QueryClientProvider>
+    );
+  };
+}
+
+describe("application query inbound bridge", () => {
+  it("latches a background failure over stale data and clears it on retry success", async () => {
+    const client = queryClient();
+    const responses = [
+      { ok: /** @type {const} */ (true), value: ["first"] },
+      {
+        ok: /** @type {const} */ (false),
+        error: createFailure("SERVER_FAILURE", "LIST", 0),
+      },
+      { ok: /** @type {const} */ (true), value: ["recovered"] },
+    ];
+    const execute = vi.fn(async () => responses.shift() ?? responses[0]);
+    const hook = renderHook(
+      () =>
+        useApplicationQuery({
+          queryKey: ["resource", "list"],
+          execute,
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(hook.result.current.data).toEqual(["first"]));
+    await act(() => hook.result.current.retry());
+    await waitFor(() =>
+      expect(hook.result.current.state.indicator).toBe("stale-degraded"),
+    );
+    expect(hook.result.current.state.base).toBe("success");
+    expect(hook.result.current.data).toEqual(["first"]);
+
+    await act(() => hook.result.current.retry());
+    await waitFor(() =>
+      expect(hook.result.current.data).toEqual(["recovered"]),
+    );
+    expect(hook.result.current.state.indicator).toBeNull();
+    expect(execute).toHaveBeenCalledTimes(3);
+  });
+
+  it("projects an initial application failure into terminal state", async () => {
+    const client = queryClient();
+    const failure = createFailure("FORBIDDEN", "LIST", 0);
+    const hook = renderHook(
+      () =>
+        useApplicationQuery({
+          queryKey: ["forbidden"],
+          execute: async () => ({ ok: false, error: failure }),
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() =>
+      expect(hook.result.current.state.base).toBe("terminal-error"),
+    );
+    expect(hook.result.current.state.failure).toBe(failure);
+  });
+
+  it("passes cancellation to the application and does not retain an unmounted error", async () => {
+    const client = queryClient();
+    let aborted = false;
+    const execute = vi.fn(
+      ({ signal }) =>
+        new Promise((resolve) => {
+          signal.addEventListener(
+            "abort",
+            () => {
+              aborted = true;
+              resolve({
+                ok: false,
+                error: createFailure("REQUEST_ABORTED", "LIST", 0),
+              });
+            },
+            { once: true },
+          );
+        }),
+    );
+    const hook = renderHook(
+      () =>
+        useApplicationQuery({
+          queryKey: ["cancelled"],
+          execute,
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    await waitFor(() => expect(execute).toHaveBeenCalledOnce());
+    hook.unmount();
+    await waitFor(() => expect(aborted).toBe(true));
+    expect(client.getQueryState(["cancelled"])?.status).not.toBe("error");
+  });
+});
+
+describe("application mutation inbound bridge", () => {
+  it("deduplicates submit and commits one optimistic mutation", async () => {
+    const client = queryClient();
+    const key = ["resource", "list"];
+    client.setQueryData(key, ["existing"]);
+    /** @type {(value: {ok: true, value: string}) => void} */
+    let complete = () => {};
+    const execute = vi.fn(
+      () =>
+        new Promise((resolve) => {
+          complete = resolve;
+        }),
+    );
+    const hook = renderHook(
+      () =>
+        useApplicationMutation({
+          execute,
+          invalidate: [["resource"]],
+          currentData: client.getQueryData(key),
+          optimistic: {
+            queryKey: key,
+            update: (previous, input) => [
+              .../** @type {string[]} */ (previous),
+              input,
+            ],
+          },
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    /** @type {ReturnType<typeof hook.result.current.submit> | null} */
+    let first = null;
+    /** @type {ReturnType<typeof hook.result.current.submit> | null} */
+    let duplicate = null;
+    act(() => {
+      first = hook.result.current.submit("created");
+      duplicate = hook.result.current.submit("created");
+    });
+    expect(first).toBe(duplicate);
+    expect(client.getQueryData(key)).toEqual(["existing", "created"]);
+    await waitFor(() => expect(execute).toHaveBeenCalledOnce());
+    await waitFor(() =>
+      expect(hook.result.current.state.indicator).toBe("mutation-pending"),
+    );
+
+    complete({ ok: true, value: "created" });
+    if (!first) throw new Error("expected pending mutation");
+    await act(() => first);
+    expect(client.getQueryState(key)?.isInvalidated).toBe(true);
+    await waitFor(() =>
+      expect(hook.result.current.state.indicator).toBeNull(),
+    );
+  });
+
+  it("rolls optimistic data back and exposes a resolvable conflict", async () => {
+    const client = queryClient();
+    const key = ["resource", "list"];
+    client.setQueryData(key, ["existing"]);
+    const conflict = createFailure("CONFLICT", "CREATE", 0);
+    const hook = renderHook(
+      () =>
+        useApplicationMutation({
+          execute: async () => ({ ok: false, error: conflict }),
+          invalidate: [["resource"]],
+          currentData: client.getQueryData(key),
+          optimistic: {
+            queryKey: key,
+            update: (previous, input) => [
+              .../** @type {string[]} */ (previous),
+              input,
+            ],
+          },
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    let outcome;
+    await act(async () => {
+      outcome = await hook.result.current.submit("conflicting");
+    });
+    expect(outcome).toEqual({ ok: false, error: conflict });
+    expect(client.getQueryData(key)).toEqual(["existing"]);
+    expect(hook.result.current.state.indicator).toBe("mutation-conflict");
+    expect(hook.result.current.state.overlay).toMatchObject({
+      mutationPending: false,
+      mutationConflict: true,
+    });
+
+    await act(() => hook.result.current.resolveConflict());
+    expect(hook.result.current.state.indicator).toBeNull();
+    expect(client.getQueryState(key)?.isInvalidated).toBe(true);
+  });
+});

tests/component/async-surface.test.jsx

@@ -1,7 +1,8 @@
 // @vitest-environment jsdom
 
 import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
 
 import { deriveAsyncState } from "../../src/application/view-models/async-state.js";
 import { AsyncSurface } from "../../src/presentation/components/async-surface.jsx";
@@ -29,7 +30,7 @@ describe("async UI state matrix", () => {
     expect(deriveAsyncState(signals).indicator).toBe(indicator);
   });
 
-  it("uses deterministic overlay priority for crossed states", () => {
+  it("makes crossed overlay inputs mutually exclusive by priority", () => {
     const state = deriveAsyncState({
       data: ["value"],
       isFetching: true,
@@ -38,8 +39,8 @@ describe("async UI state matrix", () => {
     });
     expect(state.indicator).toBe("mutation-conflict");
     expect(state.overlay).toMatchObject({
-      refreshing: true,
+      refreshing: false,
-      mutationPending: true,
+      mutationPending: false,
       mutationConflict: true,
     });
   });
@@ -52,12 +53,45 @@ describe("async UI state matrix", () => {
     expect(screen.getByRole("status")).toHaveTextContent("refreshing");
   });
 
+  it("connects stale retry and conflict resolution to real callbacks", async () => {
+    const user = userEvent.setup();
+    const retry = vi.fn();
+    const resolveConflict = vi.fn();
+    const stale = deriveAsyncState({
+      data: ["value"],
+      isStale: true,
+      isDegraded: true,
+    });
+    const view = render(
+      <AsyncSurface state={stale} onRetry={retry}>
+        existing content
+      </AsyncSurface>,
+    );
+    await user.click(screen.getByRole("button", { name: "다시 시도" }));
+    expect(retry).toHaveBeenCalledOnce();
+
+    const conflict = deriveAsyncState({
+      data: ["value"],
+      hasMutationConflict: true,
+    });
+    view.rerender(
+      <AsyncSurface
+        state={conflict}
+        onResolveConflict={resolveConflict}
+      >
+        existing content
+      </AsyncSurface>,
+    );
+    await user.click(screen.getByRole("button", { name: "충돌 해결" }));
+    expect(resolveConflict).toHaveBeenCalledOnce();
+  });
+
   it("renders only safe error vocabulary", () => {
     const failure = createFailure("SERVER_FAILURE", "LIST", 0, {
       code: "SERVER_FAILURE",
     });
     const state = deriveAsyncState({ failure });
-    render(<AsyncSurface state={state} />);
+    render(<AsyncSurface state={state} onRetry={vi.fn()} />);
 
     expect(screen.getByRole("alert")).toHaveTextContent(
       "요청을 완료하지 못했습니다.",

tests/component/chunk-recovery-boundary.test.tsx

@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  ChunkRecoveryBoundary,
+  isChunkLoadFailure,
+} from "../../src/presentation/boundaries/chunk-recovery-boundary.js";
+import { FeatureBoundary } from "../../src/presentation/boundaries/render-error-boundary.jsx";
+
+function ChunkDefect(): never {
+  throw new TypeError("Failed to fetch dynamically imported module");
+}
+
+function RenderDefect(): never {
+  throw new Error("ordinary render defect");
+}
+
+describe("chunk recovery boundary classification", () => {
+  it("recognizes lazy module failures without classifying ordinary render errors", () => {
+    expect(
+      isChunkLoadFailure(
+        new TypeError("Failed to fetch dynamically imported module"),
+      ),
+    ).toBe(true);
+    expect(isChunkLoadFailure(new Error("ordinary render defect"))).toBe(false);
+  });
+
+  it("runs the recovery input only for a lazy chunk rejection", async () => {
+    const recover = vi.fn(async () => ({
+      action: "support" as const,
+      reason: "reload-already-attempted",
+    }));
+    render(
+      <ChunkRecoveryBoundary chunkId="route-home" recover={recover}>
+        <ChunkDefect />
+      </ChunkRecoveryBoundary>,
+    );
+
+    expect(
+      await screen.findByRole("heading", {
+        name: "화면 자산을 복구하지 못했습니다.",
+      }),
+    ).toBeVisible();
+    expect(recover).toHaveBeenCalledOnce();
+    expect(recover).toHaveBeenCalledWith({
+      chunkId: "route-home",
+      failureKind: "CHUNK_LOAD_FAILURE",
+    });
+  });
+
+  it("rethrows an ordinary component defect to the local render boundary", () => {
+    const recover = vi.fn();
+    render(
+      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
+        <ChunkRecoveryBoundary chunkId="route-home" recover={recover}>
+          <RenderDefect />
+        </ChunkRecoveryBoundary>
+      </FeatureBoundary>,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(recover).not.toHaveBeenCalled();
+  });
+});

tests/component/design-tokens.test.jsx

@@ -3,12 +3,17 @@
 import { render, screen } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
 
-import { DesignTokenShowcase } from "../../src/sample/contract-fixture/design-token-showcase.jsx";
+import { Button } from "../../src/presentation/components/ui/button.jsx";
+import { Card } from "../../src/presentation/components/ui/card.jsx";
 
 describe("design-token fixture", () => {
   it("uses static semantic primitive classes", () => {
-    render(<DesignTokenShowcase />);
+    render(
-    expect(screen.getByRole("region")).toHaveClass("ui-panel");
+      <Card title="Design token fixture">
+        <Button>Token action</Button>
+      </Card>,
+    );
+    expect(screen.getByRole("article")).toHaveClass("ui-card");
     expect(screen.getByRole("button")).toHaveClass("ui-button");
   });
 });

tests/component/render-boundary.test.jsx

@@ -91,4 +91,34 @@ describe("render recovery boundaries", () => {
     );
     expect(screen.getByText("recovered")).toBeVisible();
   });
+
+  it("resets a route failure when the registered location key changes", async () => {
+    let shouldThrow = true;
+    function RouteContent() {
+      if (shouldThrow) throw new Error("route defect");
+      return <p>next route</p>;
+    }
+    const view = render(
+      <FeatureBoundary
+        routeId="APP_HOME"
+        buildId="build-a"
+        resetKey="/first"
+      >
+        <RouteContent />
+      </FeatureBoundary>,
+    );
+    expect(screen.getByRole("alert")).toBeVisible();
+
+    shouldThrow = false;
+    view.rerender(
+      <FeatureBoundary
+        routeId="APP_HOME"
+        buildId="build-a"
+        resetKey="/second"
+      >
+        <RouteContent />
+      </FeatureBoundary>,
+    );
+    expect(await screen.findByText("next route")).toBeVisible();
+  });
 });

tests/component/router.test.jsx

@@ -4,29 +4,27 @@ import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { describe, expect, it } from "vitest";
 
-import {
+import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
-  createAnonymousSessionAdapter,
-  createDemoSessionAdapter,
-} from "../../src/adapters/auth/external-session-adapter.js";
 import { ApplicationProvider } from "../../src/presentation/providers/application-provider.js";
 import { AppRouter } from "../../src/presentation/routes/app-router.jsx";
 import { createTestApplication } from "../helpers/create-test-application.js";
 
-/**
+function renderRouter() {
- * @param {import("../../src/application/ports/auth-session-port.js").AuthSessionPort} session
- */
-function renderRouter(session) {
   return render(
-    <ApplicationProvider application={createTestApplication({ session })}>
+    <ApplicationProvider
+      application={createTestApplication({
+        session: createAnonymousSessionAdapter(),
+      })}
+    >
       <AppRouter />
     </ApplicationProvider>,
   );
 }
 
-describe("application router", () => {
+describe("generic application router", () => {
-  it("renders the app shell and not-found route without an API request", async () => {
+  it("renders the app shell and not-found route without a feature input", async () => {
     window.history.pushState({}, "", "/missing");
-    renderRouter(createAnonymousSessionAdapter());
+    renderRouter();
 
     expect(
       await screen.findByRole("heading", {
@@ -37,10 +35,10 @@ describe("application router", () => {
     expect(screen.getByRole("main")).toBeVisible();
   });
 
-  it("navigates between registry-backed example routes", async () => {
+  it("navigates between registry-backed platform routes", async () => {
     const user = userEvent.setup();
     window.history.pushState({}, "", "/");
-    renderRouter(createAnonymousSessionAdapter());
+    renderRouter();
 
     await user.click(
       await screen.findByRole("link", { name: "UI 구성요소" }),
@@ -50,36 +48,9 @@ describe("application router", () => {
       await screen.findByRole("heading", { name: "UI 구성요소", level: 1 }),
     ).toBeVisible();
     expect(window.location.pathname).toBe("/examples/ui");
-  });
+    expect(document.title).toBe("UI 구성요소 · Frontend Skeleton");
-
-  it("reacts to demo sign-in and opens the protected integration route", async () => {
-    const user = userEvent.setup();
-    const authSession = createDemoSessionAdapter();
-    window.history.pushState({}, "", "/sample/resources");
-    renderRouter(authSession);
-
     expect(
-      await screen.findByRole("heading", { name: "세션이 필요합니다." }),
+      screen.getByRole("heading", { name: "UI 구성요소", level: 1 }),
-    ).toBeVisible();
+    ).toHaveFocus();
-    await user.click(screen.getByRole("button", { name: "로그인 시작" }));
-
-    expect(
-      await screen.findByRole("heading", { name: "보호된 연동 지점" }),
-    ).toBeVisible();
-    expect(screen.getByText("인증됨")).toBeVisible();
-  });
-
-  it("fails closed when the auth integration does not change state", async () => {
-    const user = userEvent.setup();
-    window.history.pushState({}, "", "/sample/resources");
-    renderRouter(createAnonymousSessionAdapter());
-
-    await user.click(
-      await screen.findByRole("button", { name: "로그인 시작" }),
-    );
-
-    expect(
-      screen.getByRole("heading", { name: "세션이 필요합니다." }),
-    ).toBeVisible();
   });
 });

tests/component/runtime-application.test.jsx

@@ -30,6 +30,13 @@ const releaseManifest = {
   assetManifestHash: "test-hash",
   releaseId: "local-release",
   builtAt: "2026-07-26T00:00:00.000Z",
+  routeChunks: {
+    "route-home": "assets/home.js",
+    "route-examples-ui": "assets/ui.js",
+    "route-examples-states": "assets/states.js",
+    "route-examples-auth": "assets/auth.js",
+    "route-not-found": "assets/not-found.js",
+  },
 };
 
 describe("production runtime application tree", () => {

tests/component/sample-resource-page.test.jsx

@@ -1,70 +0,0 @@
-// @vitest-environment jsdom
-
-import { render, screen } from "@testing-library/react";
-import { describe, expect, it } from "vitest";
-
-import { SampleResourcePage } from "../../src/sample/contract-fixture/sample-resource-page.jsx";
-
-describe("removable sample feature page", () => {
-  it("renders the API-to-view-model result through AsyncSurface", async () => {
-    /** @type {Parameters<typeof SampleResourcePage>[0]["facade"]} */
-    const facade = {
-      listResources: async () => ({
-        ok: /** @type {const} */ (true),
-        value: [
-          {
-            resourceId: "resource-1",
-            title: "Example",
-            createdAtLabel: null,
-          },
-        ],
-      }),
-      createResource: async () => ({
-        ok: /** @type {const} */ (true),
-        value: {
-          resourceId: "resource-created",
-          title: "Created",
-          createdAtLabel: null,
-        },
-      }),
-    };
-    render(<SampleResourcePage facade={facade} />);
-
-    expect(screen.getByLabelText("불러오는 중")).toBeVisible();
-    expect(await screen.findByText("Example")).toBeVisible();
-  });
-
-  it("renders normalized terminal errors without raw DTO fields", async () => {
-    /** @type {Parameters<typeof SampleResourcePage>[0]["facade"]} */
-    const facade = {
-      listResources: async () => ({
-        ok: /** @type {const} */ (false),
-        error: {
-          kind: "SERVER_FAILURE",
-          code: "SERVER_FAILURE",
-          retryable: true,
-          operationId: "LIST_SAMPLE_RESOURCES",
-          attemptCount: 1,
-          userMessageKey: "error.server_failure",
-          action: "retry",
-        },
-      }),
-      createResource: async () => ({
-        ok: /** @type {const} */ (true),
-        value: {
-          resourceId: "resource-created",
-          title: "Created",
-          createdAtLabel: null,
-        },
-      }),
-    };
-    render(<SampleResourcePage facade={facade} />);
-
-    const alert = await screen.findByRole("alert");
-    expect(alert).toHaveTextContent("요청을 완료하지 못했습니다.");
-    expect(alert).toHaveAttribute(
-      "data-message-key",
-      "error.server_failure",
-    );
-  });
-});

tests/e2e/accessibility.spec.js

@@ -1,14 +1,10 @@
 import AxeBuilder from "@axe-core/playwright";
 import { expect, test } from "@playwright/test";
+import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
 
-for (const route of [
+for (const route of Object.values(ROUTE_REGISTRY).map((definition) =>
-  "/",
+  definition.path === "*" ? "/not-found" : definition.path,
-  "/examples/ui",
+)) {
-  "/examples/states",
-  "/examples/auth",
-  "/sample/resources",
-  "/not-found",
-]) {
   test(`@a11y ${route} has no critical or serious axe violations`, async ({
     page,
   }) => {

tests/e2e/app-shell.spec.js

@@ -1,4 +1,5 @@
 import { expect, test } from "@playwright/test";
+import { ROUTE_REGISTRY } from "../../src/features/installed-feature-contracts.js";
 
 test("boots the public app shell", async ({ page }) => {
   await page.goto("/");
@@ -27,7 +28,11 @@ test("navigates to a registry-backed example without a page reload", async ({
 test("opens the protected integration route through the local demo seam", async ({
   page,
 }) => {
-  await page.goto("/sample/resources");
+  const protectedRoute = Object.values(ROUTE_REGISTRY).find(
+    (definition) => definition.access === "integration-defined",
+  );
+  if (!protectedRoute) throw new Error("An integration route is required");
+  await page.goto(protectedRoute.path);
   await expect(
     page.getByRole("heading", { name: "세션이 필요합니다." }),
   ).toBeVisible();
@@ -35,7 +40,7 @@ test("opens the protected integration route through the local demo seam", async
   await page.getByRole("button", { name: "로그인 시작" }).click();
 
   await expect(
-    page.getByRole("heading", { name: "보호된 연동 지점" }),
+    page.getByRole("heading", { name: protectedRoute.title }),
   ).toBeVisible();
   await expect(page.getByText("인증됨")).toBeVisible();
 });

tests/features/reference-feature/reference-contract.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  buildRouteUrl,
+  parseRouteInput,
+} from "../../../src/presentation/routes/route-codecs.js";
+import {
+  mapReferenceOperation,
+  toReferenceView,
+} from "../../../src/features/reference-feature/contracts/reference-mapper.js";
+import {
+  validateReferencePayload,
+  validateReferenceRequest,
+} from "../../../src/features/reference-feature/contracts/reference-schemas.js";
+import {
+  REFERENCE_FEATURE_CONTRACT,
+  referenceQueryKeys,
+} from "../../../src/features/reference-feature/contracts/reference-feature-contract.js";
+
+describe("reference feature boundary contracts", () => {
+  it("round-trips one canonical filter through URL and query identity", () => {
+    const filters = {
+      tags: ["open", "new"],
+      cursor: "a/b",
+      limit: 5,
+    };
+    const url = buildRouteUrl("REFERENCE_RESOURCE_LIST", { search: filters });
+    expect(url).toBe(
+      "/examples/reference-resources?cursor=a%2Fb&limit=5&tags=open&tags=new",
+    );
+    const parsed = parseRouteInput(
+      "REFERENCE_RESOURCE_LIST",
+      {},
+      new URL(url, "https://app.test").searchParams,
+    );
+    expect(parsed).toMatchObject({
+      success: true,
+      data: { search: filters },
+    });
+    expect(referenceQueryKeys.list(filters).at(-1)).toEqual(filters);
+  });
+
+  it("rejects unknown search and malformed DTO before mapping", () => {
+    expect(
+      parseRouteInput(
+        "REFERENCE_RESOURCE_LIST",
+        {},
+        new URLSearchParams("unknown=value"),
+      ),
+    ).toEqual({ success: false, code: "ROUTE_SEARCH_INVALID" });
+    expect(
+      validateReferencePayload("ReferenceResourceListPayload", [
+        { id: "unsafe", name: 42 },
+      ]),
+    ).toMatchObject({ success: false });
+    expect(() =>
+      mapReferenceOperation("LIST_REFERENCE_RESOURCES", [
+        { id: "unsafe", name: 42 },
+      ]),
+    ).toThrow();
+  });
+
+  it("normalizes request input and maps only owned domain fields", () => {
+    expect(
+      validateReferenceRequest("CreateReferenceResourceCommand", {
+        name: "  Example  ",
+      }),
+    ).toMatchObject({ success: true, data: { name: "Example" } });
+    const model = mapReferenceOperation("CREATE_REFERENCE_RESOURCE", {
+      id: "reference-1",
+      name: "Example",
+      createdAt: "2026-07-26T00:00:00.000Z",
+    });
+    if (!("id" in model)) throw new Error("expected one model");
+    expect(toReferenceView(model, () => "formatted")).toEqual({
+      resourceId: "reference-1",
+      title: "Example",
+      createdAtLabel: "formatted",
+    });
+  });
+
+  it("owns route, operation and query contributions in one removable contract", () => {
+    expect(Object.keys(REFERENCE_FEATURE_CONTRACT.routes)).toEqual([
+      "REFERENCE_RESOURCE_LIST",
+    ]);
+    expect(Object.keys(REFERENCE_FEATURE_CONTRACT.apiOperations)).toEqual([
+      "LIST_REFERENCE_RESOURCES",
+      "CREATE_REFERENCE_RESOURCE",
+    ]);
+    expect(Object.keys(REFERENCE_FEATURE_CONTRACT.queryRegistry)).toEqual([
+      "REFERENCE_RESOURCE",
+    ]);
+  });
+});

tests/features/reference-feature/reference-page.test.tsx

@@ -0,0 +1,234 @@
+// @vitest-environment jsdom
+
+import {
+  QueryClient,
+  QueryClientProvider,
+} from "@tanstack/react-query";
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { createDemoSessionAdapter } from "../../../src/adapters/auth/external-session-adapter.js";
+import type {
+  ReferenceFeatureInput,
+  ReferenceResult,
+} from "../../../src/features/reference-feature/application/reference-feature-api.js";
+import { REFERENCE_FEATURE_ID } from "../../../src/features/reference-feature/contracts/reference-feature-contract.js";
+import type { ReferenceResourceView } from "../../../src/features/reference-feature/contracts/reference-mapper.js";
+import { createFailure } from "../../../src/contracts/errors.js";
+import { ApplicationProvider } from "../../../src/presentation/providers/application-provider.js";
+import { AppRouter } from "../../../src/presentation/routes/app-router.js";
+import { createTestApplication } from "../../helpers/create-test-application.js";
+
+function renderReference(
+  input: ReferenceFeatureInput,
+  url = "/examples/reference-resources?limit=5",
+) {
+  window.history.pushState({}, "", url);
+  const client = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false, gcTime: Infinity },
+      mutations: { retry: false },
+    },
+  });
+  return render(
+    <QueryClientProvider client={client}>
+      <ApplicationProvider
+        application={createTestApplication({
+          session: createDemoSessionAdapter("authenticated"),
+          featureInputs: { [REFERENCE_FEATURE_ID]: input },
+        })}
+      >
+        <AppRouter />
+      </ApplicationProvider>
+    </QueryClientProvider>,
+  );
+}
+
+function inputWith(
+  overrides: Partial<ReferenceFeatureInput> = {},
+): ReferenceFeatureInput {
+  return {
+    listResources: async () => ({ ok: true, value: [] }),
+    createResource: async ({ name }) => ({
+      ok: true,
+      value: {
+        resourceId: "created",
+        title: name,
+        createdAtLabel: null,
+      },
+    }),
+    ...overrides,
+  };
+}
+
+describe("reference feature page states", () => {
+  it("renders loading, success and empty states through the installed route", async () => {
+    let resolveList:
+      | ((result: ReferenceResult<readonly ReferenceResourceView[]>) => void)
+      | undefined;
+    const pending = new Promise<
+      ReferenceResult<readonly ReferenceResourceView[]>
+    >((resolve) => {
+      resolveList = resolve;
+    });
+    const loaded = renderReference(
+      inputWith({ listResources: async () => pending }),
+    );
+    expect(await screen.findByLabelText("불러오는 중")).toBeVisible();
+    resolveList?.({
+      ok: true,
+      value: [
+        {
+          resourceId: "reference-1",
+          title: "Loaded",
+          createdAtLabel: null,
+        },
+      ],
+    });
+    expect(await screen.findByText("Loaded")).toBeVisible();
+    loaded.unmount();
+
+    renderReference(inputWith(), "/examples/reference-resources?limit=10");
+    expect(
+      await screen.findByRole("heading", {
+        name: "표시할 항목이 없습니다.",
+      }),
+    ).toBeVisible();
+  });
+
+  it("rejects invalid URL input before the feature application input", async () => {
+    const listResources = vi.fn();
+    renderReference(
+      inputWith({ listResources }),
+      "/examples/reference-resources?limit=invalid",
+    );
+    expect(
+      await screen.findByRole("heading", {
+        name: "올바르지 않은 주소입니다.",
+      }),
+    ).toBeVisible();
+    expect(listResources).not.toHaveBeenCalled();
+  });
+
+  it("renders backend forbidden even when the client access hint allowed entry", async () => {
+    renderReference(
+      inputWith({
+        listResources: async () => ({
+          ok: false,
+          error: createFailure(
+            "FORBIDDEN",
+            "LIST_REFERENCE_RESOURCES",
+            0,
+          ),
+        }),
+      }),
+    );
+    expect(await screen.findByRole("alert")).toHaveTextContent(
+      "이 작업을 수행할 권한이 없습니다.",
+    );
+  });
+
+  it("deduplicates optimistic create and rolls back a conflict", async () => {
+    const user = userEvent.setup();
+    let finish:
+      | ((result: ReferenceResult<ReferenceResourceView>) => void)
+      | undefined;
+    const createResource = vi.fn(
+      () =>
+        new Promise<ReferenceResult<ReferenceResourceView>>((resolve) => {
+          finish = resolve;
+        }),
+    );
+    renderReference(
+      inputWith({
+        listResources: async () => ({
+          ok: true,
+          value: [
+            {
+              resourceId: "existing",
+              title: "Existing",
+              createdAtLabel: null,
+            },
+          ],
+        }),
+        createResource,
+      }),
+    );
+    await screen.findByText("Existing");
+    await user.type(screen.getByLabelText("새 항목 이름"), "Conflicting");
+    const submit = screen.getByRole("button", { name: "추가" });
+    await user.dblClick(submit);
+
+    await waitFor(() => expect(createResource).toHaveBeenCalledOnce());
+    expect(await screen.findByText("Conflicting")).toHaveAttribute(
+      "data-optimistic",
+      "true",
+    );
+    expect(screen.getByText("mutation-pending")).toBeVisible();
+
+    finish?.({
+      ok: false,
+      error: createFailure(
+        "CONFLICT",
+        "CREATE_REFERENCE_RESOURCE",
+        0,
+      ),
+    });
+    expect(
+      await screen.findByRole("button", { name: "충돌 해결" }),
+    ).toBeVisible();
+    expect(screen.queryByText("Conflicting")).not.toBeInTheDocument();
+    await user.click(screen.getByRole("button", { name: "충돌 해결" }));
+    await waitFor(() =>
+      expect(screen.queryByText("mutation-conflict")).not.toBeInTheDocument(),
+    );
+  });
+
+  it("keeps stale data visible during refresh failure and recovers on retry", async () => {
+    const user = userEvent.setup();
+    const listResources = vi
+      .fn<ReferenceFeatureInput["listResources"]>()
+      .mockResolvedValueOnce({
+        ok: true,
+        value: [
+          {
+            resourceId: "existing",
+            title: "Existing",
+            createdAtLabel: null,
+          },
+        ],
+      })
+      .mockResolvedValueOnce({
+        ok: false,
+        error: createFailure(
+          "SERVER_FAILURE",
+          "LIST_REFERENCE_RESOURCES",
+          0,
+        ),
+      })
+      .mockResolvedValue({
+        ok: true,
+        value: [
+          {
+            resourceId: "recovered",
+            title: "Recovered",
+            createdAtLabel: null,
+          },
+        ],
+      });
+    renderReference(inputWith({ listResources }));
+    await screen.findByText("Existing");
+    await user.type(screen.getByLabelText("새 항목 이름"), "Created");
+    await user.click(screen.getByRole("button", { name: "추가" }));
+
+    expect(await screen.findByText("stale-degraded")).toBeVisible();
+    expect(screen.getByText("Existing")).toBeVisible();
+    await user.click(screen.getByRole("button", { name: "다시 시도" }));
+    expect(await screen.findByText("Recovered")).toBeVisible();
+    await waitFor(() =>
+      expect(screen.queryByText("stale-degraded")).not.toBeInTheDocument(),
+    );
+    expect(listResources).toHaveBeenCalledTimes(3);
+  });
+});

tests/features/reference-feature/reference-production-vertical.test.tsx

@@ -0,0 +1,129 @@
+// @vitest-environment jsdom
+
+import { HttpResponse, http } from "msw";
+import { setupServer } from "msw/node";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  it,
+  vi,
+} from "vitest";
+
+import { createRuntimeComposition } from "../../../src/bootstrap/create-runtime-composition.js";
+import { RuntimeApplication } from "../../../src/bootstrap/runtime-application.jsx";
+
+const runtimeConfig = {
+  APP_ENV: "local",
+  API_BASE_URL: "https://api.test",
+  REQUEST_TIMEOUT_MS: 10_000,
+  MAX_RETRY_ATTEMPTS: 0,
+  TELEMETRY_ENABLED: false,
+  AUTH_MODE: "demo",
+  CONFIG_SCHEMA_VERSION: "1",
+  API_CONTRACT_VERSION: "1",
+  RELEASE_MANIFEST_URL: "/release-manifest.json",
+  BUILD_ID: "local-build",
+  RELEASE_ID: "local-release",
+};
+const releaseManifest = {
+  schemaVersion: 1,
+  appVersion: "0.1.0",
+  buildId: "local-build",
+  commitSha: "local",
+  configSchemaVersion: "1",
+  apiContractVersion: "1",
+  assetManifestHash: "test-hash",
+  releaseId: "local-release",
+  builtAt: "2026-07-26T00:00:00.000Z",
+  routeChunks: {
+    "route-home": "assets/home.js",
+    "route-examples-ui": "assets/ui.js",
+    "route-examples-states": "assets/states.js",
+    "route-examples-auth": "assets/auth.js",
+    "route-reference-resources": "assets/reference.js",
+    "route-not-found": "assets/not-found.js",
+  },
+};
+
+const listRequests = vi.fn();
+const createRequests = vi.fn();
+const resources = [{ id: "reference-1", name: "Existing" }];
+const server = setupServer(
+  http.get("http://app.test/config.json", () =>
+    HttpResponse.json(runtimeConfig),
+  ),
+  http.get("http://app.test/release-manifest.json", () =>
+    HttpResponse.json(releaseManifest),
+  ),
+  http.get("https://api.test/api/reference-resources", ({ request }) => {
+    listRequests(new URL(request.url).search);
+    return HttpResponse.json({
+      success: true,
+      data: resources,
+      meta: { requestId: "request-list", traceId: "trace-list" },
+    });
+  }),
+  http.post("https://api.test/api/reference-resources", async ({ request }) => {
+    const body = (await request.json()) as { name: string };
+    createRequests(body);
+    const created = { id: "reference-created", name: body.name };
+    resources.push(created);
+    return HttpResponse.json({
+      success: true,
+      data: created,
+      meta: { requestId: "request-create", traceId: "trace-create" },
+    });
+  }),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => {
+  listRequests.mockClear();
+  createRequests.mockClear();
+  resources.splice(1);
+});
+afterAll(() => server.close());
+
+const absoluteFetch: typeof fetch = (input, init) => {
+  if (input instanceof Request) return fetch(input, init);
+  const url = new URL(
+    input instanceof URL ? input.href : input,
+    "http://app.test",
+  );
+  return fetch(url, init);
+};
+
+describe("reference feature production vertical path", () => {
+  it("traverses bootstrap, router, application, HTTP schema/mapper and query cache", async () => {
+    const user = userEvent.setup();
+    const composition = await createRuntimeComposition({
+      fetcher: absoluteFetch,
+      host: {},
+    });
+    window.history.pushState(
+      {},
+      "",
+      "/examples/reference-resources?tags=open&tags=new&limit=5",
+    );
+    render(<RuntimeApplication composition={composition} />);
+
+    await user.click(
+      await screen.findByRole("button", { name: "로그인 시작" }),
+    );
+    expect(await screen.findByText("Existing")).toBeVisible();
+    expect(listRequests).toHaveBeenCalledWith(
+      "?limit=5&tags=open&tags=new",
+    );
+
+    await user.type(screen.getByLabelText("새 항목 이름"), "  Created  ");
+    await user.click(screen.getByRole("button", { name: "추가" }));
+    expect(await screen.findByText("Created")).toBeVisible();
+    expect(createRequests).toHaveBeenCalledWith({ name: "Created" });
+    expect(listRequests.mock.calls.length).toBeGreaterThanOrEqual(2);
+  });
+});

tests/fixtures/architecture/forbidden/presentation-imports-tanstack.tsx

@@ -0,0 +1,3 @@
+import { useQuery } from "@tanstack/react-query";
+
+export const leakedQueryHook = useQuery;

tests/fixtures/registry/routes/governance.json

@@ -0,0 +1,59 @@
+{
+  "schemaVersion": 1,
+  "sourceDirectories": [],
+  "registries": [
+    {
+      "registryId": "ROUTES",
+      "path": "tests/fixtures/registry/routes/invalid-routes.js",
+      "exportName": "INVALID_ROUTES",
+      "owner": "fixture",
+      "requiredFields": [
+        "routeId",
+        "path",
+        "paramsSchema",
+        "searchSchema",
+        "loadingSurface",
+        "errorSurface",
+        "chunkId"
+      ],
+      "uniqueFields": ["routeId", "path", "chunkId"],
+      "allowedValues": {
+        "paramsSchema": [null],
+        "searchSchema": [null],
+        "loadingSurface": ["app-shell"],
+        "errorSurface": ["route-boundary"],
+        "chunkId": ["route-home"]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "RUNTIME",
+          "targetField": "routeId"
+        }
+      ]
+    },
+    {
+      "registryId": "RUNTIME",
+      "path": "tests/fixtures/registry/routes/invalid-routes.js",
+      "exportName": "INVALID_RUNTIME",
+      "owner": "fixture",
+      "requiredFields": ["routeId", "moduleId", "paramsCodec", "searchCodec"],
+      "allowedValues": {
+        "moduleId": ["home-page"],
+        "paramsCodec": ["none"],
+        "searchCodec": ["none"]
+      },
+      "references": [
+        {
+          "field": "routeId",
+          "registryId": "ROUTES",
+          "targetField": "routeId"
+        }
+      ]
+    }
+  ],
+  "compatibilityImpact": {
+    "allowed": ["none", "additive", "behavior-change", "breaking"],
+    "current": "breaking"
+  }
+}

tests/fixtures/registry/routes/invalid-routes.ts

@@ -0,0 +1,29 @@
+export const INVALID_ROUTES = {
+  FIRST: {
+    routeId: "DUPLICATE",
+    path: "/duplicate",
+    paramsSchema: "UnknownParams",
+    searchSchema: "UnknownSearch",
+    loadingSurface: "unknown-loading",
+    errorSurface: "unknown-error",
+    chunkId: "unknown-chunk",
+  },
+  SECOND: {
+    routeId: "DUPLICATE",
+    path: "/duplicate",
+    paramsSchema: null,
+    searchSchema: null,
+    loadingSurface: "app-shell",
+    errorSurface: "route-boundary",
+    chunkId: "route-home",
+  },
+};
+
+export const INVALID_RUNTIME = {
+  ORPHAN: {
+    routeId: "ORPHAN",
+    moduleId: "unknown-module",
+    paramsCodec: "none",
+    searchCodec: "none",
+  },
+};

tests/fixtures/typecheck/invalid-async-overlay.ts

@@ -0,0 +1,8 @@
+import type { AsyncOverlay } from "../../../src/application/view-models/async-state.js";
+
+export const invalidPendingConflict: AsyncOverlay = {
+  refreshing: false,
+  staleDegraded: false,
+  mutationPending: true,
+  mutationConflict: true,
+};