feat: add removable sample vertical contract fixture

.gitignore

@@ -1,6 +1,7 @@
 node_modules/
 dist/
 .vite/
+.tmp/
 playwright-report/
 test-results/
 coverage/

package.json

@@ -22,12 +22,14 @@
     "test:integration": "vitest run tests/integration --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/integration.xml",
     "test:e2e": "playwright test",
     "test:a11y": "playwright test --grep @a11y",
+    "test:sample-removal": "node scripts/test-sample-removal.mjs",
     "test:all": "pnpm test:runtime-schema && pnpm test:unit && pnpm test:component && pnpm test:integration"
   },
   "dependencies": {
     "@tanstack/react-query": "5.101.4",
     "react": "19.2.8",
     "react-dom": "19.2.8",
+    "react-router-dom": "7.18.1",
     "zod": "4.4.3"
   },
   "devDependencies": {

pnpm-lock.yaml

@@ -17,6 +17,9 @@ importers:
       react-dom:
         specifier: 19.2.8
         version: 19.2.8(react@19.2.8)
+      react-router-dom:
+        specifier: 7.18.1
+        version: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
       zod:
         specifier: 4.4.3
         version: 4.4.3
@@ -1260,6 +1263,23 @@ packages:
   react-is@17.0.2:
     resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
 
+  react-router-dom@7.18.1:
+    resolution: {integrity: sha512-KaZh+X/6UtEp28x51AUYZDMg9NGoz2ja3dNHa+ta/tk40vCzKhQ/RypCWBMLbmDr6//E24Vv5uPsrqXFozdkAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+
+  react-router@7.18.1:
+    resolution: {integrity: sha512-GDLgg3i3uM0aeJO3Fm+TCS+sDQ7gu12T6x0qdTEzcwqEfleci7JwugVNIF3U//0FWKnJT7ptG+20B2jfDqnZAg==}
+    engines: {node: '>=20.0.0'}
+    peerDependencies:
+      react: '>=18'
+      react-dom: '>=18'
+    peerDependenciesMeta:
+      react-dom:
+        optional: true
+
   react@19.2.8:
     resolution: {integrity: sha512-PWaYA1L/q9u2u7xYQi+Y3L3Yfnie7XyLeaJICV1MGD6LprsBxcAqGjYyr0eY3p+QdsA+x/Irkt4Qif8D63+Sbw==}
     engines: {node: '>=0.10.0'}
@@ -1312,6 +1332,9 @@ packages:
     engines: {node: '>=10'}
     hasBin: true
 
+  set-cookie-parser@2.7.2:
+    resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==}
+
   set-cookie-parser@3.1.2:
     resolution: {integrity: sha512-5/r/lTwbJ3zQ+qwdUFZYeRNqda7P5HD8zQKqlSjdGt1/S0cjLAphHusj4Y58ahDtWn/g32xrIS58/ikOvwl0Lw==}
 
@@ -2604,6 +2627,20 @@ snapshots:
 
   react-is@17.0.2: {}
 
+  react-router-dom@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      react: 19.2.8
+      react-dom: 19.2.8(react@19.2.8)
+      react-router: 7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8)
+
+  react-router@7.18.1(react-dom@19.2.8(react@19.2.8))(react@19.2.8):
+    dependencies:
+      cookie: 1.1.1
+      react: 19.2.8
+      set-cookie-parser: 2.7.2
+    optionalDependencies:
+      react-dom: 19.2.8(react@19.2.8)
+
   react@19.2.8: {}
 
   rechoir@0.8.0:
@@ -2663,6 +2700,8 @@ snapshots:
 
   semver@7.8.5: {}
 
+  set-cookie-parser@2.7.2: {}
+
   set-cookie-parser@3.1.2: {}
 
   shebang-command@2.0.0:

scripts/test-sample-removal.mjs

@@ -0,0 +1,77 @@
+import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+
+const fixtureRoot = path.resolve(".tmp/sample-removal");
+const sampleRoot = path.resolve("src/sample/contract-fixture");
+const sourceRoot = path.resolve("src");
+const pnpmCli = /** @type {string} */ (process.env.npm_execpath);
+
+/** @param {string} directory @returns {Promise<string[]>} */
+async function sourceFiles(directory) {
+  const entries = await readdir(directory, { withFileTypes: true });
+  const nested = /** @type {string[][]} */ (await Promise.all(
+    entries.map((entry) => {
+      const target = path.join(directory, entry.name);
+      return entry.isDirectory() ? sourceFiles(target) : [target];
+    }),
+  ));
+  return nested.flat();
+}
+
+await rm(fixtureRoot, { recursive: true, force: true });
+await mkdir(fixtureRoot, { recursive: true });
+
+const incomingImports = [];
+for (const sourceFile of await sourceFiles(sourceRoot)) {
+  if (sourceFile.startsWith(sampleRoot)) continue;
+  const content = await readFile(sourceFile, "utf8");
+  if (/from\s+["'][^"']*sample\/contract-fixture/.test(content)) {
+    incomingImports.push(path.relative(".", sourceFile));
+  }
+}
+
+let buildStatus = 1;
+if (incomingImports.length === 0) {
+  await cp("src", path.join(fixtureRoot, "src"), {
+    recursive: true,
+    filter: (source) => !source.startsWith(sampleRoot),
+  });
+  await cp("public", path.join(fixtureRoot, "public"), { recursive: true });
+  await cp("index.html", path.join(fixtureRoot, "index.html"));
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      pnpmCli,
+      "exec",
+      "vite",
+      "build",
+      fixtureRoot,
+      "--outDir",
+      path.join(fixtureRoot, "dist"),
+    ],
+    { stdio: "inherit" },
+  );
+  buildStatus = result.status ?? 1;
+}
+
+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}">` +
+    `<testcase name="no-product-import"/>` +
+    `<testcase name="production-build">${passed ? "" : "<failure/>"}</testcase>` +
+    `</testsuite>\n`,
+);
+await rm(fixtureRoot, { recursive: true, force: true });
+
+if (!passed) {
+  process.stderr.write(
+    `Sample removal failed. Incoming imports: ${incomingImports.join(", ")}\n`,
+  );
+  process.exit(1);
+}
+process.stdout.write("Sample removal smoke: PASS\n");

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

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

src/bootstrap/main.jsx

@@ -1,28 +1,11 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
 
+import { createAnonymousSessionAdapter } from "../adapters/auth/external-session-adapter.js";
+import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.jsx";
+import { AppRouter } from "../presentation/routes/app-router.jsx";
 import { BootConfigError, loadRuntimeConfig } from "./load-runtime-config.js";
 
-/** @param {{ environment: string }} props */
-function BootstrapShell({ environment }) {
-  return (
-    <main>
-      <h1>Clean Architecture Frontend</h1>
-      <p>{environment} 런타임 계약이 검증되었습니다.</p>
-    </main>
-  );
-}
-
-/** @param {{ supportReference: string }} props */
-function BootErrorShell({ supportReference }) {
-  return (
-    <main role="alert">
-      <h1>애플리케이션을 시작할 수 없습니다.</h1>
-      <p>지원 참조: {supportReference}</p>
-    </main>
-  );
-}
-
 const rootElement = document.getElementById("root");
 
 if (!rootElement) {
@@ -36,16 +19,19 @@ async function boot() {
     const runtime = await loadRuntimeConfig();
     root.render(
       <StrictMode>
-        <BootstrapShell environment={runtime.config.APP_ENV} />
+        <AppRouter
+          authSession={createAnonymousSessionAdapter()}
+          basename={runtime.build.routerBasePath}
+        />
       </StrictMode>,
     );
   } catch (error) {
-    const supportReference =
+    const safe =
       error instanceof BootConfigError
-        ? error.safe.supportReference
+        ? error.safe
-        : "boot:unknown";
+        : { supportReference: "boot:unknown" };
 
-    root.render(<BootErrorShell supportReference={supportReference} />);
+    root.render(<BootErrorShell {...safe} />);
   }
 }
 

src/contracts/routes.js

@@ -0,0 +1,63 @@
+/**
+ * @typedef {{
+ *   routeId: string,
+ *   path: string,
+ *   paramsSchema: string | null,
+ *   searchSchema: string | null,
+ *   access: "public" | "session-required" | "integration-defined",
+ *   loadingSurface: string,
+ *   errorSurface: string,
+ *   chunkId: string
+ * }} RouteDefinition
+ */
+
+/** @param {RouteDefinition} definition */
+const route = (definition) => Object.freeze(definition);
+
+export const ROUTE_REGISTRY = Object.freeze({
+  APP_HOME: route({
+    routeId: "APP_HOME",
+    path: "/",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "app-shell",
+    errorSurface: "route-boundary",
+    chunkId: "route-home",
+  }),
+  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",
+  }),
+  NOT_FOUND: route({
+    routeId: "NOT_FOUND",
+    path: "*",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "none",
+    errorSurface: "not-found",
+    chunkId: "route-not-found",
+  }),
+});
+
+/** @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/presentation/boundaries/boot-error-shell.jsx

@@ -0,0 +1,49 @@
+/**
+ * @param {{
+ *   kind?: string,
+ *   code?: string,
+ *   buildId?: string,
+ *   configSchemaVersion?: string,
+ *   releaseId?: string,
+ *   supportReference: string
+ * }} props
+ */
+export function BootErrorShell({
+  kind = "BOOT_CONFIG_FAILURE",
+  code = "BOOT_FAILED",
+  buildId,
+  configSchemaVersion,
+  releaseId,
+  supportReference,
+}) {
+  return (
+    <main role="alert">
+      <h1>애플리케이션을 시작할 수 없습니다.</h1>
+      <dl>
+        <dt>오류</dt>
+        <dd>{kind}</dd>
+        <dt>코드</dt>
+        <dd>{code}</dd>
+        {buildId && (
+          <>
+            <dt>빌드</dt>
+            <dd>{buildId}</dd>
+          </>
+        )}
+        {configSchemaVersion && (
+          <>
+            <dt>설정 스키마</dt>
+            <dd>{configSchemaVersion}</dd>
+          </>
+        )}
+        {releaseId && (
+          <>
+            <dt>릴리스</dt>
+            <dd>{releaseId}</dd>
+          </>
+        )}
+      </dl>
+      <p>지원 참조: {supportReference}</p>
+    </main>
+  );
+}

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

@@ -0,0 +1,68 @@
+import { Component } from "react";
+
+/**
+ * @typedef {{
+ *   children: React.ReactNode,
+ *   boundaryName: string,
+ *   routeId: string,
+ *   buildId: string,
+ *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort,
+ *   fallback?: React.ReactNode
+ * }} RenderBoundaryProps
+ * @typedef {{ hasError: boolean }} RenderBoundaryState
+ */
+
+/** @extends {Component<RenderBoundaryProps, RenderBoundaryState>} */
+export class RenderErrorBoundary extends Component {
+  /** @param {RenderBoundaryProps} props */
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false };
+  }
+
+  static getDerivedStateFromError() {
+    return { hasError: true };
+  }
+
+  componentDidCatch() {
+    try {
+      this.props.telemetry?.emit("ui.render.failed", {
+        route_id: this.props.routeId,
+        build_id: this.props.buildId,
+        component_boundary: this.props.boundaryName,
+      });
+    } catch {
+      // Telemetry must never recurse into another render failure.
+    }
+  }
+
+  reset = () => {
+    this.setState({ hasError: false });
+  };
+
+  render() {
+    if (this.state.hasError) {
+      return (
+        this.props.fallback ?? (
+          <section role="alert">
+            <p>error.render_failure</p>
+            <button type="button" onClick={this.reset}>
+              retry
+            </button>
+          </section>
+        )
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/** @param {Omit<RenderBoundaryProps, "boundaryName">} props */
+export function RouteBoundary(props) {
+  return <RenderErrorBoundary {...props} boundaryName="route" />;
+}
+
+/** @param {Omit<RenderBoundaryProps, "boundaryName">} props */
+export function FeatureBoundary(props) {
+  return <RenderErrorBoundary {...props} boundaryName="feature" />;
+}

src/presentation/routes/app-router.jsx

@@ -0,0 +1,79 @@
+import {
+  BrowserRouter,
+  Link,
+  Route,
+  Routes,
+} from "react-router-dom";
+
+import { routePath } from "../../contracts/routes.js";
+import { decideRouteAccess } from "./navigation-policy.js";
+
+function HomePage() {
+  return (
+    <main>
+      <h1>Clean Architecture Frontend</h1>
+      <p>런타임 계약이 검증되었습니다.</p>
+      <Link to={routePath("SAMPLE_RESOURCE_LIST")}>샘플 리소스</Link>
+    </main>
+  );
+}
+
+function SamplePlaceholder() {
+  return (
+    <main>
+      <h1>샘플 리소스</h1>
+      <p>계약 fixture를 준비하고 있습니다.</p>
+    </main>
+  );
+}
+
+function NotFoundPage() {
+  return (
+    <main>
+      <h1>페이지를 찾을 수 없습니다.</h1>
+      <Link to={routePath("APP_HOME")}>홈으로 이동</Link>
+    </main>
+  );
+}
+
+/**
+ * @param {{
+ *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort
+ * }} props
+ */
+function GuardedSampleRoute({ authSession }) {
+  const decision = decideRouteAccess(
+    "SAMPLE_RESOURCE_LIST",
+    authSession.getState(),
+  );
+  if (!decision.allowed) {
+    return (
+      <main>
+        <h1>세션이 필요합니다.</h1>
+        <button type="button">로그인</button>
+      </main>
+    );
+  }
+  return <SamplePlaceholder />;
+}
+
+/**
+ * @param {{
+ *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort,
+ *   basename?: string
+ * }} props
+ */
+export function AppRouter({ authSession, basename = "/" }) {
+  return (
+    <BrowserRouter basename={basename}>
+      <Routes>
+        <Route path={routePath("APP_HOME")} element={<HomePage />} />
+        <Route
+          path={routePath("SAMPLE_RESOURCE_LIST")}
+          element={<GuardedSampleRoute authSession={authSession} />}
+        />
+        <Route path={routePath("NOT_FOUND")} element={<NotFoundPage />} />
+      </Routes>
+    </BrowserRouter>
+  );
+}

src/presentation/routes/navigation-policy.js

@@ -0,0 +1,37 @@
+import { getRoute } from "../../contracts/routes.js";
+
+/**
+ * @param {string} routeId
+ * @param {import("../../application/ports/auth-session-port.js").SessionState} sessionState
+ */
+export function decideRouteAccess(routeId, sessionState) {
+  const route = getRoute(routeId);
+  if (route.access === "public") return { allowed: true, action: "none" };
+  if (sessionState === "authenticated") {
+    return { allowed: true, action: "none" };
+  }
+  if (sessionState === "recovery-pending") {
+    return { allowed: false, action: "wait-for-session" };
+  }
+  return { allowed: false, action: "show-sign-in" };
+}
+
+export function createRedirectLoopGuard() {
+  const visitedPairs = new Set();
+
+  return Object.freeze({
+    /**
+     * @param {string} source
+     * @param {string} target
+     */
+    allow(source, target) {
+      const pair = `${source}->${target}`;
+      if (source === target || visitedPairs.has(pair)) return false;
+      visitedPairs.add(pair);
+      return true;
+    },
+    reset() {
+      visitedPairs.clear();
+    },
+  });
+}

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

@@ -0,0 +1,53 @@
+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

@@ -0,0 +1,61 @@
+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/render-boundary.test.jsx

@@ -0,0 +1,87 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { createFailure } from "../../src/contracts/errors.js";
+import { deriveAsyncState } from "../../src/application/view-models/async-state.js";
+import { AsyncSurface } from "../../src/presentation/components/async-surface.jsx";
+import { BootErrorShell } from "../../src/presentation/boundaries/boot-error-shell.jsx";
+import { FeatureBoundary } from "../../src/presentation/boundaries/render-error-boundary.jsx";
+
+function Defect() {
+  throw new Error("raw render stack");
+}
+
+describe("render recovery boundaries", () => {
+  it("catches programmer defects and emits best-effort safe telemetry", () => {
+    const telemetry = { emit: vi.fn() };
+    render(
+      <FeatureBoundary
+        routeId="APP_HOME"
+        buildId="build-a"
+        telemetry={telemetry}
+      >
+        <Defect />
+      </FeatureBoundary>,
+    );
+
+    expect(screen.getByRole("alert")).toHaveTextContent("error.render_failure");
+    expect(telemetry.emit).toHaveBeenCalledWith("ui.render.failed", {
+      route_id: "APP_HOME",
+      build_id: "build-a",
+      component_boundary: "feature",
+    });
+  });
+
+  it("keeps normalized operational failures in normal async state", () => {
+    const state = deriveAsyncState({
+      failure: createFailure("SERVER_FAILURE", "LIST", 0),
+    });
+    render(
+      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
+        <AsyncSurface state={state} />
+      </FeatureBoundary>,
+    );
+    expect(screen.getByRole("alert")).toHaveTextContent("error.server_failure");
+  });
+
+  it("renders a safe boot shell with no endpoint or stack", () => {
+    render(
+      <BootErrorShell
+        kind="BOOT_CONFIG_FAILURE"
+        code="CONFIG_SCHEMA_INVALID"
+        buildId="build-a"
+        configSchemaVersion="1"
+        supportReference="build-a:CONFIG_SCHEMA_INVALID"
+      />,
+    );
+    const shell = screen.getByRole("alert");
+    expect(shell).toHaveTextContent("build-a:CONFIG_SCHEMA_INVALID");
+    expect(shell).not.toHaveTextContent("https://");
+    expect(shell).not.toHaveTextContent("stack");
+  });
+
+  it("allows a boundary reset action without reloading the page", async () => {
+    let shouldThrow = true;
+    function Recoverable() {
+      if (shouldThrow) throw new Error("defect");
+      return <p>recovered</p>;
+    }
+    const user = userEvent.setup();
+    const view = render(
+      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
+        <Recoverable />
+      </FeatureBoundary>,
+    );
+    shouldThrow = false;
+    await user.click(screen.getByRole("button", { name: "retry" }));
+    view.rerender(
+      <FeatureBoundary routeId="APP_HOME" buildId="build-a">
+        <Recoverable />
+      </FeatureBoundary>,
+    );
+    expect(screen.getByText("recovered")).toBeVisible();
+  });
+});

tests/component/router.test.jsx

@@ -0,0 +1,24 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
+import { AppRouter } from "../../src/presentation/routes/app-router.jsx";
+
+describe("application router", () => {
+  it("renders not-found without making an API request", () => {
+    window.history.pushState({}, "", "/missing");
+    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+    expect(
+      screen.getByRole("heading", { name: "페이지를 찾을 수 없습니다." }),
+    ).toBeVisible();
+  });
+
+  it("shows session-required UX without claiming authorization", () => {
+    window.history.pushState({}, "", "/sample/resources");
+    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+    expect(screen.getByRole("heading", { name: "세션이 필요합니다." })).toBeVisible();
+    expect(screen.getByRole("button", { name: "로그인" })).toBeVisible();
+  });
+});

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

@@ -0,0 +1,49 @@
+// @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 () => {
+    const facade = {
+      listResources: async () => ({
+        ok: true,
+        value: [
+          {
+            resourceId: "resource-1",
+            title: "Example",
+            createdAtLabel: null,
+          },
+        ],
+      }),
+      createResource: async () => ({ ok: true, value: {} }),
+    };
+    render(<SampleResourcePage facade={facade} />);
+
+    expect(screen.getByLabelText("불러오는 중")).toBeVisible();
+    expect(await screen.findByText("Example")).toBeVisible();
+  });
+
+  it("renders normalized terminal errors without raw DTO fields", async () => {
+    const facade = {
+      listResources: async () => ({
+        ok: 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: true, value: {} }),
+    };
+    render(<SampleResourcePage facade={facade} />);
+
+    expect(await screen.findByRole("alert")).toHaveTextContent("error.server_failure");
+  });
+});

tests/integration/sample-vertical-slice.test.js

@@ -0,0 +1,53 @@
+import { HttpResponse, http } from "msw";
+import { setupServer } from "msw/node";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { createHttpClient } from "../../src/adapters/http/client.js";
+import {
+  createQueryCacheAdapter,
+  createQueryClient,
+} from "../../src/adapters/query-cache/tanstack-query-cache.js";
+import { queryKeys } from "../../src/contracts/query-keys.js";
+import { createSampleFacade } from "../../src/sample/contract-fixture/sample-facade.js";
+
+const server = setupServer(
+  http.get("https://api.test/api/sample/resources", () =>
+    HttpResponse.json({
+      success: true,
+      data: [{ id: "resource-1", name: "Example" }],
+      meta: { requestId: "request-1", traceId: "trace-1" },
+    }),
+  ),
+);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterAll(() => server.close());
+
+describe("sample vertical contract fixture", () => {
+  it("traverses API, schema, mapper, application facade, and cache", async () => {
+    const queryClient = createQueryClient();
+    const cache = createQueryCacheAdapter(queryClient);
+    const facade = createSampleFacade({
+      http: createHttpClient({
+        baseUrl: "https://api.test",
+        clock: { now: () => 0, sleep: async () => {} },
+      }),
+      cache,
+    });
+
+    await expect(facade.listResources()).resolves.toEqual({
+      ok: true,
+      value: [
+        {
+          resourceId: "resource-1",
+          title: "Example",
+          createdAtLabel: null,
+        },
+      ],
+    });
+    expect(cache.read(queryKeys.resource.list({}))).toMatchObject({
+      ok: true,
+      value: [{ id: "resource-1", displayName: "Example" }],
+    });
+  });
+});

tests/unit/chunk-recovery.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from "vitest";
+
+import { decideChunkRecovery } from "../../src/application/use-cases/decide-chunk-recovery.js";
+
+function memoryStorage() {
+  let value;
+  return {
+    read: () => ({ ok: true, value }),
+    write: (_key, next) => {
+      value = next;
+      return { ok: true };
+    },
+    remove: () => ({ ok: true }),
+  };
+}
+
+describe("controlled chunk recovery", () => {
+  it("records the release pair before allowing one reload", () => {
+    const storage = memoryStorage();
+    const input = {
+      failureKind: "CHUNK_LOAD_FAILURE",
+      manifestLoaded: true,
+      currentBuildId: "build-a",
+      activeReleaseId: "release-b",
+      storage,
+    };
+    expect(decideChunkRecovery(input)).toEqual({
+      action: "reload-once",
+      releasePair: "build-a->release-b",
+    });
+    expect(decideChunkRecovery(input)).toEqual({
+      action: "support",
+      reason: "reload-already-attempted",
+    });
+  });
+
+  it.each([
+    [{ failureKind: "SERVER_FAILURE" }, "not-recoverable"],
+    [{ manifestLoaded: false }, "manifest-unavailable"],
+    [{ activeReleaseId: "build-a" }, "same-release"],
+  ])("stops when a recovery invariant fails: %#", (override, reason) => {
+    const result = decideChunkRecovery({
+      failureKind: "DEPLOY_MISMATCH",
+      manifestLoaded: true,
+      currentBuildId: "build-a",
+      activeReleaseId: "release-b",
+      storage: memoryStorage(),
+      ...override,
+    });
+    expect(result).toEqual({ action: "support", reason });
+  });
+});

tests/unit/navigation-policy.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createRedirectLoopGuard,
+  decideRouteAccess,
+} from "../../src/presentation/routes/navigation-policy.js";
+import { ROUTE_REGISTRY } from "../../src/contracts/routes.js";
+
+describe("route registry", () => {
+  it("matches the stable registry snapshot", () => {
+    expect(ROUTE_REGISTRY).toMatchInlineSnapshot(`
+      {
+        "APP_HOME": {
+          "access": "public",
+          "chunkId": "route-home",
+          "errorSurface": "route-boundary",
+          "loadingSurface": "app-shell",
+          "paramsSchema": null,
+          "path": "/",
+          "routeId": "APP_HOME",
+          "searchSchema": null,
+        },
+        "NOT_FOUND": {
+          "access": "public",
+          "chunkId": "route-not-found",
+          "errorSurface": "not-found",
+          "loadingSurface": "none",
+          "paramsSchema": null,
+          "path": "*",
+          "routeId": "NOT_FOUND",
+          "searchSchema": null,
+        },
+        "SAMPLE_RESOURCE_LIST": {
+          "access": "integration-defined",
+          "chunkId": "route-sample-resources",
+          "errorSurface": "feature-boundary",
+          "loadingSurface": "sample-resource-list",
+          "paramsSchema": null,
+          "path": "/sample/resources",
+          "routeId": "SAMPLE_RESOURCE_LIST",
+          "searchSchema": "SampleResourceListQuery",
+        },
+      }
+    `);
+  });
+
+  it("treats client access as a UX hint, not authorization", () => {
+    expect(decideRouteAccess("APP_HOME", "unauthenticated")).toEqual({
+      allowed: true,
+      action: "none",
+    });
+    expect(decideRouteAccess("SAMPLE_RESOURCE_LIST", "unauthenticated")).toEqual({
+      allowed: false,
+      action: "show-sign-in",
+    });
+    expect(decideRouteAccess("SAMPLE_RESOURCE_LIST", "authenticated")).toEqual({
+      allowed: true,
+      action: "none",
+    });
+  });
+
+  it("allows at most one automatic redirect per source-target pair", () => {
+    const guard = createRedirectLoopGuard();
+    expect(guard.allow("/private", "/signin")).toBe(true);
+    expect(guard.allow("/private", "/signin")).toBe(false);
+    expect(guard.allow("/signin", "/signin")).toBe(false);
+  });
+});