# TechLog Backend Alignment Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Studio HTTP 계약을 canonical `studio-v1.yaml` 단일 출처에 고정하고, `StudioGateway`의 모든 operation과 Asset capability를 HTTP 어댑터로 구현한다.

**Architecture:** canonical OpenAPI를 저장소에 vendor하고 타입을 생성한다. 계약 기여(`EXTERNAL_PACKAGE` provenance)의 digest로 canonical revision을 암호학적으로 고정해 drift를 빌드에서 막는다. JSON operation 18개는 플랫폼 계약 런타임(`contractOperations`)을 통과하고, 계약 런타임이 표현할 수 없는 multipart 업로드 1개만 전용 전송 seam으로 분리한다. mock gateway는 삭제하지 않고 런타임 스위치 뒤의 기본값으로 유지한다.

**Tech Stack:** TypeScript 7, React 19, Vite 8, Vitest 4, MSW 2, zod 4, `openapi-typescript`(신규)

**Spec:** `docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md`

## Global Constraints

- Canonical 계약: `/home/donghyeon/workspace/tech-log-design-package/contracts/openapi/studio-v1.yaml`, spec version `2.0.0`, operation 19개.
- **digest와 revision은 생성 시점에 `canonical-source.json`에 기록한다. 계획서나 테스트에 값을 박지 않는다.** canonical 저장소는 활발히 편집 중이다(2026-08-17 하루에만 두 번 변경, 마지막은 description 전용이라 구조 영향 없음). 고정 값을 박으면 계약이 그대로인데도 테스트가 깨진다.
- 생성기는 저장소 의존성에 넣지 않는다. `openapi-typescript`는 TypeScript 5의 classic compiler API를 요구하고 이 저장소는 TypeScript `7.0.2`를 고정한다(VD-01). TS7 루트 export는 `{version, versionMajorMinor}`뿐이라 compiler API가 없다. 격리된 `pnpm dlx`로 실행한다.
- canonical operation은 **19개**다. JSON 18개는 계약 기여에, multipart `uploadStudioAsset` 1개는 업로드 전송 seam에 존재해야 한다.
- 오류 코드는 **23개** 전부를 처리한다. 목록은 Task 2에 있다.
- 브랜치는 `feature/techlog-backend-alignment`다. `main`에 직접 커밋하지 않는다.
- `src/application/ports/studio-gateway.ts`의 시그니처를 변경하지 않는다. UI는 어댑터 종류를 알지 못한다.
- 현재 Public UI·라우트와 Studio 작업 흐름을 변경하지 않는다. `presentation/public/**`, `presentation/shared/public-render/**`, 기존 `document-*`/`validation-*`/`publish-*`/`publication-*` 컴포넌트는 Task 8~10에서 지정한 지점 외에는 손대지 않는다.
- **`tests/mocks/scenarios/catalog.ts`의 `HTTP_SCENARIO_OPERATION_IDS`에 TechLog operation을 추가하지 않는다.** 그 카탈로그는 플랫폼 전송 계층의 실패 모드 행렬이며 reference feature 3개 operation으로 이미 입증돼 있다. 어떤 스크립트도 계약 등록부와 대조하지 않으므로(확인함) TechLog operation을 넣으면 19 시나리오 × 18 operation의 증거 부담만 생긴다. TechLog는 `tests/features/tech-log/`에서 MSW로 gateway 수준 계약을 검증한다.
- 플랫폼 파일 중 이 계획이 수정을 허용하는 것은 `src/contracts/release-artifacts.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/contracts/env.ts`, `src/contracts/rest-profiles.ts`, `src/features/installed-contract-contributions.ts`, `src/features/installed-feature-adapters.ts`, `src/bootstrap/runtime-adapters.ts`뿐이다. `src/contracts/external-contract-runtime.ts`, `src/adapters/http/client.ts`, `src/adapters/http/http-execution-v3.ts`는 **수정하지 않는다**(template 동기화 대상).
- **인증·CSRF·Idempotency는 플랫폼 seam을 쓴다. 직접 헤더를 만들지 않는다.** 계약의 `projectRequest`는 `pathValues`/`queryEntries`/`body`만 만들 수 있고 헤더 채널이 없다(`external-contract-runtime.ts`의 `HttpRequestProjection`). 헤더는 두 경로로만 들어간다.
  - `Idempotency-Key`: 실행 context의 `intent.idempotencyKey`에서 온다(`http-execution-v3.ts:689-690`). 계약 소유 헤더이므로 credential 쪽에서 공급하면 거절된다(`:657-661`). 명령 gateway는 `intent`를 넘기고 **입력 본문에 `idempotencyKey`를 넣지 않는다**.
  - `x-csrf-token`: `attachCredentials` collaborator가 공급하고 `admitCredentialHeaders`가 auth profile의 허용 목록으로 검사한다(`http-execution-v3.ts:435, :672`). gateway 입력에 `csrfToken`을 넣지 않는다.
- 계약 기여의 `packageId`는 **npm scope 형식**이어야 한다: `PACKAGE_ID = /^@[a-z0-9][a-z0-9._-]{0,62}\/[a-z0-9][a-z0-9._-]{0,62}$/`(`external-contract-runtime.ts:218-219`). scope 없는 이름은 composition 시점에 거절된다. 이 계약의 값은 `@tech-log/studio-contract`다 — 플랫폼이 기여를 게시된 패키지로 모델링하기 때문이며, 실제 배포로 승격할 때 같은 이름을 쓴다.
- `frontend.authProfileId`는 `INSTALLED_REST_AUTH_PROFILES`에 등록된 값이어야 한다. 없는 값이면 **composition이 실패한다**(`external-contract-runtime.ts:325-326`). 등록은 Task 3 Step 1이 한다.
- `frontend.responseByteLimit`은 **1 이상**이어야 하고(`external-contract-runtime.ts:336-337`) `hardResponseBytes: 8_388_608`을 넘을 수 없다. `requestByteLimit`은 0 이상 `hardRequestBytes: 1_048_576` 이하다.
- 매 Task는 red → green → 게이트 → commit 순서를 지킨다.

---

### Task 1: 계약 생성 파이프라인과 drift 게이트

canonical yaml을 vendor하고 타입을 재생성 가능하게 만든다. 현재 `generated.ts`는 `openapi-typescript`로 만들어졌으나 도구도 스크립트도 저장소에 없어 재생성이 불가능하다 — 두 계약이 갈라진 근본 원인이다.

**Files:**
- Create: `scripts/generate-tech-log-contract.ts`
- Create: `src/features/tech-log/contracts/studio/canonical-source.json`
- Modify: `src/features/tech-log/contracts/studio/studio-api.openapi.yaml` (canonical 사본으로 교체)
- Modify: `src/features/tech-log/contracts/studio/generated.ts` (재생성)
- Modify: `package.json` (devDependency + scripts)
- Test: `tests/features/tech-log/contract-generation.test.ts`

**Interfaces:**
- Consumes: 없음 (첫 Task)
- Produces: `canonical-source.json` — `{ packageId: string, version: string, digest: string, sourceRevision: string, operationIds: string[] }`. Task 2가 provenance와 parity 검증에 사용한다.

- [ ] **Step 1: 실패하는 테스트 작성**

`tests/features/tech-log/contract-generation.test.ts`:

```typescript
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
import { test } from "vitest";

import canonicalSource from "../../../src/features/tech-log/contracts/studio/canonical-source.json" with { type: "json" };

const YAML_PATH = "src/features/tech-log/contracts/studio/studio-api.openapi.yaml";

test("vendored contract matches the recorded canonical digest", () => {
  const bytes = readFileSync(YAML_PATH);
  const digest = `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
  assert.equal(digest, canonicalSource.digest);
});

test("canonical source records the pinned revision and version", () => {
  assert.equal(canonicalSource.packageId, "@tech-log/studio-contract");
  assert.equal(canonicalSource.version, "2.0.0");
  // revision은 생성 시점에 기록된다. canonical 저장소는 활발히 편집 중이므로
  // 특정 값을 박아두면 계약이 그대로인데도 테스트가 깨진다. 형식만 고정한다.
  assert.match(canonicalSource.sourceRevision, /^[0-9a-f]{7,64}$/);
  assert.match(canonicalSource.digest, /^sha256:[0-9a-f]{64}$/);
});

test("canonical source lists all 19 operationIds", () => {
  assert.equal(canonicalSource.operationIds.length, 19);
  assert.ok(canonicalSource.operationIds.includes("uploadStudioAsset"));
  assert.ok(canonicalSource.operationIds.includes("getStudioSession"));
});

test("vendored contract declares the CSRF header", () => {
  const yaml = readFileSync(YAML_PATH, "utf8");
  assert.ok(yaml.includes("X-CSRF-TOKEN"));
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/contract-generation.test.ts`
Expected: FAIL — `canonical-source.json` 모듈을 찾을 수 없다.

- [ ] **Step 3: 생성 스크립트 작성**

`scripts/generate-tech-log-contract.ts`. 두 모드는 **의존성이 다르다**. 생성은 canonical 저장소와 네트워크가 필요하고, 검증은 저장소 안의 파일만 읽는다 — CI에는 canonical 사본도 생성 도구도 없기 때문이다.

```typescript
/**
 * canonical studio-v1.yaml을 vendor하고 타입을 생성한다.
 *
 * 생성기는 저장소 의존성에 넣지 않는다. `openapi-typescript`는 TypeScript 5의
 * classic compiler API를 요구하는데 이 저장소는 TypeScript 7.0.2를 고정하고
 * 있고(VD-01), TS7 루트는 compiler API를 노출하지 않는다. 격리된 `pnpm dlx`
 * 환경에서 실행하면 lockfile과 peer 계약을 건드리지 않고 같은 산출물을 얻는다.
 *
 * `--check`는 canonical 저장소도 생성기도 없이 동작한다. vendor된 계약이
 * 기록된 digest와 일치하는지, 기록된 operationId가 생성물에 모두 존재하는지만
 * 본다. 손으로 yaml이나 generated.ts를 고치면 여기서 걸린다.
 */
import { createHash } from "node:crypto";
import { execFileSync } from "node:child_process";
import { readFileSync, writeFileSync } from "node:fs";
import { argv, env, exit } from "node:process";

const CANONICAL_ROOT =
  env.TECH_LOG_DESIGN_PACKAGE ?? "/home/donghyeon/workspace/tech-log-design-package";
const CANONICAL_YAML = `${CANONICAL_ROOT}/contracts/openapi/studio-v1.yaml`;
const VENDOR_YAML = "src/features/tech-log/contracts/studio/studio-api.openapi.yaml";
const GENERATED = "src/features/tech-log/contracts/studio/generated.ts";
const SOURCE_RECORD = "src/features/tech-log/contracts/studio/canonical-source.json";

const OPENAPI_TYPESCRIPT = "openapi-typescript@7.9.1";
const GENERATOR_TYPESCRIPT = "typescript@5.9.3";

const check = argv.includes("--check");

function digestOf(bytes: Buffer | string): string {
  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
}

function operationIdsOf(yaml: string): string[] {
  return [...yaml.matchAll(/^\s+operationId:\s*(\S+)\s*$/gmu)].map((match) => match[1]!);
}

function specVersionOf(yaml: string): string {
  const match = /^\s{2}version:\s*(\S+)\s*$/mu.exec(yaml);
  if (!match) throw new Error("canonical yaml has no info.version");
  return match[1]!;
}

type CanonicalRecord = Readonly<{
  packageId: string;
  version: string;
  digest: string;
  sourceRevision: string;
  operationIds: readonly string[];
}>;

function fail(problems: readonly string[]): never {
  console.error(`tech-log contract drift:\n- ${problems.join("\n- ")}`);
  console.error("Run: corepack pnpm generate:tech-log-contract");
  exit(1);
}

if (check) {
  const vendored = readFileSync(VENDOR_YAML, "utf8");
  const generated = readFileSync(GENERATED, "utf8");
  const record = JSON.parse(readFileSync(SOURCE_RECORD, "utf8")) as CanonicalRecord;
  const problems: string[] = [];

  if (digestOf(readFileSync(VENDOR_YAML)) !== record.digest) {
    problems.push(`${VENDOR_YAML} does not hash to the recorded digest`);
  }
  const vendoredOperations = operationIdsOf(vendored);
  if (vendoredOperations.join(" ") !== [...record.operationIds].join(" ")) {
    problems.push(`${SOURCE_RECORD} operationIds differ from ${VENDOR_YAML}`);
  }
  if (specVersionOf(vendored) !== record.version) {
    problems.push(`${SOURCE_RECORD} version differs from ${VENDOR_YAML}`);
  }
  // 생성물은 operationId로 키가 매겨진 `operations` 인터페이스를 노출한다.
  for (const operationId of record.operationIds) {
    if (!new RegExp(`^\\s{4}${operationId}:`, "mu").test(generated)) {
      problems.push(`${GENERATED} is missing operation ${operationId}`);
    }
  }
  if (problems.length > 0) fail(problems);
  console.log(
    `tech-log contract is in sync: ${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations.`,
  );
  exit(0);
}

const canonicalBytes = readFileSync(CANONICAL_YAML);
const canonicalText = canonicalBytes.toString("utf8");

const record: CanonicalRecord = {
  packageId: "@tech-log/studio-contract",
  version: specVersionOf(canonicalText),
  digest: digestOf(canonicalBytes),
  sourceRevision: execFileSync(
    "git",
    ["-C", CANONICAL_ROOT, "rev-parse", "--short=7", "HEAD"],
    { encoding: "utf8" },
  ).trim(),
  operationIds: operationIdsOf(canonicalText),
};

// 격리 실행. 저장소의 node_modules와 lockfile은 그대로다.
const generated = execFileSync(
  "corepack",
  [
    "pnpm",
    "dlx",
    "--package",
    GENERATOR_TYPESCRIPT,
    "--package",
    OPENAPI_TYPESCRIPT,
    "openapi-typescript",
    CANONICAL_YAML,
  ],
  { encoding: "utf8", maxBuffer: 32 * 1024 * 1024 },
);

writeFileSync(VENDOR_YAML, canonicalText);
writeFileSync(GENERATED, generated);
writeFileSync(SOURCE_RECORD, `${JSON.stringify(record, null, 2)}\n`);
console.log(
  `Generated from ${record.packageId}@${record.version} (${record.sourceRevision}), ${record.operationIds.length} operations.`,
);
```

- [ ] **Step 4: 스크립트 등록**

`openapi-typescript`를 devDependency로 **추가하지 않는다**. `package.json`의 `scripts`에 세 줄만 더한다:

```json
"generate:tech-log-contract": "node scripts/generate-tech-log-contract.ts",
"check:tech-log-contract": "node scripts/generate-tech-log-contract.ts --check",
"test:tech-log": "vitest run tests/features/tech-log --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/tech-log.xml",
```

`test:all` 스크립트의 `test:reference-feature` 뒤에 `&& corepack pnpm test:tech-log`를 추가한다.

- [ ] **Step 5: 생성 실행**

Run: `corepack pnpm generate:tech-log-contract`
Expected: `Generated from @tech-log/studio-contract@2.0.0 (<7자리 revision>), 19 operations.`

`generated.ts`의 diff가 크다. `paths`에 `/api/v1/studio/session`, `/api/v1/studio/assets`, `/api/v1/studio/assets/{assetId}`가 생기고 `components.schemas`에 `StudioSession`, `Asset`, `AssetDetail`, `AssetPage`, `AssetUploadForm`, `UpdateAssetCommand`, `AssetUsage`, `AssetKind`, `AssetManagementStatus`가 생기는지 육안 확인한다.

- [ ] **Step 6: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/contract-generation.test.ts`
Expected: 4 tests PASS

- [ ] **Step 7: drift 게이트가 실제로 잡는지 확인**

Run:

```bash
printf '\n# tampered\n' >> src/features/tech-log/contracts/studio/studio-api.openapi.yaml
corepack pnpm check:tech-log-contract; echo "exit=$?"
git checkout -- src/features/tech-log/contracts/studio/studio-api.openapi.yaml
corepack pnpm check:tech-log-contract; echo "exit=$?"
```

Expected: 첫 실행 `exit=1`과 digest 불일치 메시지, 복원 후 `exit=0`.

생성물 훼손도 잡는지 확인한다. `generated.ts`에서 `getStudioSession` operation 키 이름을 임시로 바꾼 뒤 `check`를 실행하고 되돌린다.

Expected: `exit=1`과 `missing operation getStudioSession`.

- [ ] **Step 8: 기존 계약 소비자 회귀 확인**

Run: `corepack pnpm check:types:app && corepack pnpm test:tech-log`
Expected: PASS. `contract.ts`의 기존 타입 alias가 새 `generated.ts`에서도 전부 해석돼야 한다. 실패하면 `contract.ts`에서 이름이 바뀐 alias만 수정한다 — 새 타입 추가는 Task 6에서 한다.

- [ ] **Step 9: 커밋**

```bash
git add package.json scripts/generate-tech-log-contract.ts \
  src/features/tech-log/contracts/studio/ tests/features/tech-log/contract-generation.test.ts
git commit -m "build: generate the TechLog Studio contract from canonical source"
```

---

### Task 2: 오류 매핑과 CSRF 세션

계약 기여를 쓰기 전에, 모든 operation이 공유할 두 조각을 먼저 만든다.

**Files:**
- Create: `src/features/tech-log/adapters/http/studio-error-mapping.ts`
- Create: `src/features/tech-log/adapters/http/studio-session-csrf.ts`
- Test: `tests/features/tech-log/studio-error-mapping.test.ts`

**Interfaces:**
- Consumes: `StudioGatewayError`(`application/ports/studio-gateway-error.ts`), `ProblemDetails`(`contracts/studio/contract.ts`), `HttpExecutionOutcome`(`adapters/http/http-execution-v3.ts`)
- Produces:
  - `STUDIO_ERROR_CODES: readonly ProblemDetails["code"][]` — 23개
  - `toStudioGatewayError(outcome: HttpExecutionOutcome<unknown, unknown>, operationId: string): StudioGatewayError`
  - `createCsrfTokenProvider(deps: { execute: CsrfSessionExecutor }): { token(options?: { signal?: AbortSignal }): Promise<string>; invalidate(): void }`
  - `type CsrfSessionExecutor = (options?: { signal?: AbortSignal }) => Promise<{ csrfToken: string; csrfHeaderName: string }>`

- [ ] **Step 1: 실패하는 테스트 작성**

`tests/features/tech-log/studio-error-mapping.test.ts`:

```typescript
import assert from "node:assert/strict";
import { test } from "vitest";

import {
  STUDIO_ERROR_CODES,
  toStudioGatewayError,
} from "../../../src/features/tech-log/adapters/http/studio-error-mapping.ts";
import { createCsrfTokenProvider } from "../../../src/features/tech-log/adapters/http/studio-session-csrf.ts";
import { isStudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

test("covers every canonical error code exactly once", () => {
  assert.equal(STUDIO_ERROR_CODES.length, 23);
  assert.equal(new Set(STUDIO_ERROR_CODES).size, 23);
  for (const code of ["IDEMPOTENCY_KEY_REUSED", "WARNING_ACKNOWLEDGEMENT_REQUIRED", "ASSET_QUARANTINED"]) {
    assert.ok(STUDIO_ERROR_CODES.includes(code as never), `${code} is missing`);
  }
});

test("maps a PROBLEM outcome onto the port error, preserving the code", () => {
  const error = toStudioGatewayError(
    {
      kind: "PROBLEM",
      problem: {
        type: "https://techlog.local/problems/version-conflict",
        title: "VERSION_CONFLICT",
        status: 409,
        detail: "Expected 3; current 4.",
        code: "VERSION_CONFLICT",
      },
      metadata: { status: 409 },
      effect: "NOT_APPLIED",
    } as never,
    "saveStudioDocument",
  );

  assert.ok(isStudioGatewayError(error));
  assert.equal(error.code, "VERSION_CONFLICT");
  assert.equal(error.status, 409);
});

test("maps a transport failure onto STUDIO_UNAVAILABLE without inventing a domain code", () => {
  const error = toStudioGatewayError(
    { kind: "TRANSPORT_FAILURE", failure: { kind: "TIMEOUT" }, effect: "MAYBE_APPLIED" } as never,
    "getStudioDashboard",
  );

  assert.equal(error.code, "STUDIO_UNAVAILABLE");
  assert.equal(error.retryable, true);
});

test("maps UNAUTHENTICATED onto AUTHENTICATION_REQUIRED", () => {
  const error = toStudioGatewayError(
    { kind: "UNAUTHENTICATED", effect: "NOT_APPLIED" } as never,
    "getStudioDashboard",
  );

  assert.equal(error.code, "AUTHENTICATION_REQUIRED");
  assert.equal(error.status, 401);
});

test("fetches the CSRF token once and reuses it until invalidated", async () => {
  let calls = 0;
  const provider = createCsrfTokenProvider({
    async execute() {
      calls += 1;
      return { csrfToken: `token-${calls}`, csrfHeaderName: "X-CSRF-TOKEN" };
    },
  });

  assert.equal(await provider.token(), "token-1");
  assert.equal(await provider.token(), "token-1");
  assert.equal(calls, 1);

  provider.invalidate();
  assert.equal(await provider.token(), "token-2");
  assert.equal(calls, 2);
});

test("does not stampede concurrent CSRF requests", async () => {
  let calls = 0;
  const provider = createCsrfTokenProvider({
    async execute() {
      calls += 1;
      await Promise.resolve();
      return { csrfToken: "token", csrfHeaderName: "X-CSRF-TOKEN" };
    },
  });

  await Promise.all([provider.token(), provider.token(), provider.token()]);
  assert.equal(calls, 1);
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-error-mapping.test.ts`
Expected: FAIL — 두 모듈을 찾을 수 없다.

- [ ] **Step 3: 오류 매핑 구현**

`src/features/tech-log/adapters/http/studio-error-mapping.ts`:

```typescript
import type { HttpExecutionOutcome } from "../../../../adapters/http/http-execution-v3.ts";
import { StudioGatewayError } from "../../application/ports/studio-gateway-error.ts";
import type { ProblemDetails } from "../../contracts/studio/contract.ts";

/** canonical studio-v1.yaml `ProblemDetails.code` enum과 1:1이다. */
export const STUDIO_ERROR_CODES = Object.freeze([
  "AUTHENTICATION_REQUIRED",
  "STUDIO_ACCESS_DENIED",
  "DOCUMENT_NOT_FOUND",
  "VERSION_CONFLICT",
  "REQUEST_VALIDATION_FAILED",
  "VALIDATION_FAILED",
  "VALIDATION_STALE",
  "PREVIEW_NOT_FOUND",
  "PREVIEW_STALE",
  "PREVIEW_EXPIRED",
  "PUBLICATION_NOT_FOUND",
  "PUBLICATION_CONFLICT",
  "PUBLICATION_EVENT_NOT_FOUND",
  "PUBLICATION_SNAPSHOT_NOT_FOUND",
  "WARNING_ACKNOWLEDGEMENT_REQUIRED",
  "IDEMPOTENCY_KEY_REUSED",
  "ASSET_NOT_FOUND",
  "ASSET_NOT_READY",
  "ASSET_IN_USE",
  "ASSET_QUARANTINED",
  "PAYLOAD_TOO_LARGE",
  "UNSUPPORTED_MEDIA_TYPE",
  "STUDIO_UNAVAILABLE",
]) as readonly ProblemDetails["code"][];

const CODES = new Set<string>(STUDIO_ERROR_CODES);

function synthetic(
  code: ProblemDetails["code"],
  status: number,
  detail: string,
  retryable: boolean,
): StudioGatewayError {
  return new StudioGatewayError({
    type: `https://techlog.local/problems/${code.toLowerCase().replaceAll("_", "-")}`,
    title: code,
    status,
    detail,
    code,
    retryable,
  });
}

/**
 * 서버가 계약 밖 코드를 보내면 도메인 코드를 지어내지 않는다. 전송 계층
 * 실패와 마찬가지로 `STUDIO_UNAVAILABLE`로 접는다.
 */
export function toStudioGatewayError(
  outcome: HttpExecutionOutcome<unknown, unknown>,
  operationId: string,
): StudioGatewayError {
  switch (outcome.kind) {
    case "PROBLEM": {
      const problem = outcome.problem as ProblemDetails;
      if (problem && typeof problem.code === "string" && CODES.has(problem.code)) {
        return new StudioGatewayError(problem);
      }
      return synthetic(
        "STUDIO_UNAVAILABLE",
        outcome.metadata.status,
        `${operationId} returned an uncontracted problem code.`,
        false,
      );
    }
    case "UNAUTHENTICATED":
      return synthetic("AUTHENTICATION_REQUIRED", 401, `${operationId} requires authentication.`, false);
    case "FORBIDDEN":
      return synthetic("STUDIO_ACCESS_DENIED", 403, `${operationId} was denied.`, false);
    case "CANCELLED":
      return synthetic("STUDIO_UNAVAILABLE", 499, `${operationId} was cancelled.`, false);
    case "RATE_LIMITED":
      return synthetic("STUDIO_UNAVAILABLE", 429, `${operationId} was rate limited.`, true);
    case "TRANSPORT_FAILURE":
      return synthetic("STUDIO_UNAVAILABLE", 503, `${operationId} transport failed.`, true);
    case "AUTH_INTEGRATION_FAILURE":
    case "CONTRACT_VIOLATION":
      return synthetic("STUDIO_UNAVAILABLE", 502, `${operationId} broke its contract.`, false);
    case "SUCCESS":
      throw new Error(`${operationId}: success outcome is not an error`);
  }
}
```

- [ ] **Step 4: CSRF 제공자 구현**

`src/features/tech-log/adapters/http/studio-session-csrf.ts`:

```typescript
export type StudioSessionSnapshot = Readonly<{
  csrfToken: string;
  csrfHeaderName: string;
}>;

export type CsrfSessionExecutor = (
  options?: Readonly<{ signal?: AbortSignal }>,
) => Promise<StudioSessionSnapshot>;

export type CsrfTokenProvider = Readonly<{
  token(options?: Readonly<{ signal?: AbortSignal }>): Promise<string>;
  headerName(options?: Readonly<{ signal?: AbortSignal }>): Promise<string>;
  invalidate(): void;
}>;

/**
 * CSRF는 전송 관심사다. UI는 토큰을 보지 않으므로 포트로 노출하지 않고
 * 어댑터 내부에서 캐시한다. 동시 요청은 하나의 in-flight 조회를 공유한다.
 */
export function createCsrfTokenProvider(
  deps: Readonly<{ execute: CsrfSessionExecutor }>,
): CsrfTokenProvider {
  let cached: StudioSessionSnapshot | null = null;
  let inFlight: Promise<StudioSessionSnapshot> | null = null;

  async function resolve(
    options?: Readonly<{ signal?: AbortSignal }>,
  ): Promise<StudioSessionSnapshot> {
    if (cached) return cached;
    inFlight ??= deps.execute(options).then(
      (snapshot) => {
        cached = snapshot;
        inFlight = null;
        return snapshot;
      },
      (error: unknown) => {
        inFlight = null;
        throw error;
      },
    );
    return inFlight;
  }

  return Object.freeze({
    async token(options) {
      return (await resolve(options)).csrfToken;
    },
    async headerName(options) {
      return (await resolve(options)).csrfHeaderName;
    },
    invalidate() {
      cached = null;
    },
  });
}
```

- [ ] **Step 5: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-error-mapping.test.ts`
Expected: 6 tests PASS

- [ ] **Step 6: 커밋**

```bash
git add src/features/tech-log/adapters/http/ tests/features/tech-log/studio-error-mapping.test.ts
git commit -m "feat: add TechLog Studio error mapping and CSRF token provider"
```

---

### Task 3: Studio 계약 기여 — JSON operation 18개

계약 기여는 서비스 패키지당 하나다. Asset의 JSON operation 4개도 같은 `studio-v1` 패키지이므로 한 파일에 선언한다.

**Files:**
- Create: `src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts`
- Modify: `src/contracts/rest-profiles.ts` (auth profile 등록)
- Modify: `src/features/installed-contract-contributions.ts`
- Test: `tests/features/tech-log/studio-contract-contribution.test.ts`, `tests/runtime-schema/http-schema.test.ts`

**Interfaces:**
- Consumes: `canonical-source.json`(Task 1), `InstalledContractContribution`/`InstalledHttpContract`(`src/contracts/external-contract-runtime.ts`)
- Produces:
  - `TECH_LOG_STUDIO_CONTRIBUTION: InstalledContractContribution`
  - `TECH_LOG_STUDIO_OPERATION_IDS: readonly string[]` — 18개
  - `type TechLogStudioOperationId = (typeof TECH_LOG_STUDIO_OPERATION_IDS)[number]`

**선언할 operation 18개.** 각 항목은 `operationId · method · pathTemplate · requestBody · retrySemantics · acceptedStatuses · responseByteLimit`이다. `retrySemantics: "KEYED"`인 항목은 전부 `commandRecovery = { mode: "IDEMPOTENCY_REPLAY", operationIdentityField: "idempotencyKey" }`, `frontend.retryBudget = 0`이다. `SAFE`는 `commandRecovery: null`, `commandEffect: null`, `retryBudget: 2`다. 모든 항목의 `frontend.authProfileId`는 `"TECH_LOG_STUDIO_SESSION"`, `totalDeadlineMs`는 `10_000`이다.

| operationId | method | pathTemplate | requestBody | retry | accepted | respLimit |
|---|---|---|---|---|---|---|
| `getStudioSession` | GET | `/api/v1/studio/session` | NONE | SAFE | 200 | 8_192 |
| `getStudioDashboard` | GET | `/api/v1/studio/dashboard` | NONE | SAFE | 200 | 262_144 |
| `listStudioDocuments` | GET | `/api/v1/studio/documents` | NONE | SAFE | 200 | 262_144 |
| `createStudioDocument` | POST | `/api/v1/studio/documents` | JSON | KEYED | 201 | 131_072 |
| `getStudioDocument` | GET | `/api/v1/studio/documents/{documentId}` | NONE | SAFE | 200 | 524_288 |
| `saveStudioDocument` | PUT | `/api/v1/studio/documents/{documentId}` | JSON | KEYED | 200 | 524_288 |
| `validateStudioDocument` | POST | `/api/v1/studio/documents/{documentId}/validate` | JSON | KEYED | 200 | 262_144 |
| `getCurrentStudioPreview` | GET | `/api/v1/studio/documents/{documentId}/preview` | NONE | SAFE | 200 | 1_048_576 |
| `createStudioPreview` | POST | `/api/v1/studio/documents/{documentId}/preview` | JSON | KEYED | 201 | 1_048_576 |
| `publishStudioDocument` | POST | `/api/v1/studio/documents/{documentId}/publish` | JSON | KEYED | 200 | 131_072 |
| `listStudioPublications` | GET | `/api/v1/studio/publications` | NONE | SAFE | 200 | 262_144 |
| `unpublishStudioPublication` | POST | `/api/v1/studio/publications/{publicationId}/unpublish` | JSON | KEYED | 200 | 131_072 |
| `getStudioPublicationSnapshot` | GET | `/api/v1/studio/publications/{publicationEventId}/preview` | NONE | SAFE | 200 | 1_048_576 |
| `listStudioCatalog` | GET | `/api/v1/studio/catalog` | NONE | SAFE | 200 | 131_072 |
| `listStudioAssets` | GET | `/api/v1/studio/assets` | NONE | SAFE | 200 | 262_144 |
| `getStudioAsset` | GET | `/api/v1/studio/assets/{assetId}` | NONE | SAFE | 200 | 65_536 |
| `updateStudioAsset` | PUT | `/api/v1/studio/assets/{assetId}` | JSON | KEYED | 200 | 65_536 |
| `deleteStudioAsset` | DELETE | `/api/v1/studio/assets/{assetId}` | NONE | KEYED | 204 | 65_536 |

`deleteStudioAsset`만 `responseBody: "NONE"`, `emptyBodyStatuses: [204]`다. 나머지는 `responseBody: "REQUIRED_JSON"`, `emptyBodyStatuses: []`다. `deleteStudioAsset`의 `responseByteLimit`이 0이 아닌 이유는 플랫폼이 1 이상을 요구하기 때문이다 — 본문 없는 204여도 오류 응답은 본문을 가진다.

- [ ] **Step 1: Studio auth profile 등록**

`authProfileId`가 `INSTALLED_REST_AUTH_PROFILES`에 없으면 계약 composition이 실패한다. 현재 등록된 것은 `REFERENCE_EXTERNAL_BEARER`와 `ANONYMOUS`뿐이므로 Studio 세션 profile을 먼저 만든다.

canonical은 "Mutating Studio Operation은 Session Cookie와 `X-CSRF-TOKEN`을 요구한다"고 정한다. 플랫폼에는 이 조합이 이미 1급으로 있다 — `transport: "SAME_ORIGIN_COOKIE"`와 credential header `"x-csrf-token"`.

`src/contracts/rest-profiles.ts`의 `REST_AUTH_PROFILES`에 추가한다:

```typescript
  TECH_LOG_STUDIO_SESSION: Object.freeze({
    authProfileId: "TECH_LOG_STUDIO_SESSION",
    transport: "SAME_ORIGIN_COOKIE",
    credentials: "include",
    allowedCredentialHeaders: Object.freeze(["x-csrf-token"] as const),
    requiredCredentialHeaders: Object.freeze(["x-csrf-token"] as const),
  }),
```

`installRestAuthProfileRegistry`의 `SAME_ORIGIN_COOKIE` 불변식을 만족하는지 확인한다: `credentials !== "omit"` ✓, `allowed`에 `"authorization"`이 없어야 함 ✓, `required ⊆ allowed` ✓.

`tests/runtime-schema/http-schema.test.ts`(또는 rest-profile을 다루는 기존 테스트)에 profile이 설치되는지 단언을 추가한다:

```typescript
test("installs the TechLog Studio session auth profile", () => {
  const profile = INSTALLED_REST_AUTH_PROFILES.get("TECH_LOG_STUDIO_SESSION");
  assert.ok(profile);
  assert.equal(profile.transport, "SAME_ORIGIN_COOKIE");
  assert.deepEqual([...profile.requiredCredentialHeaders], ["x-csrf-token"]);
});
```

Run: `corepack pnpm test:runtime-schema`
Expected: PASS

- [ ] **Step 2: 실패하는 테스트 작성**

`tests/features/tech-log/studio-contract-contribution.test.ts`:

```typescript
import assert from "node:assert/strict";
import { test } from "vitest";

import canonicalSource from "../../../src/features/tech-log/contracts/studio/canonical-source.json" with { type: "json" };
import {
  TECH_LOG_STUDIO_CONTRIBUTION,
  TECH_LOG_STUDIO_OPERATION_IDS,
} from "../../../src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts";
import { composeContractContributions } from "../../../src/contracts/external-contract-runtime.ts";

const UPLOAD = "uploadStudioAsset";

test("declares every canonical operation except the multipart upload", () => {
  const expected = canonicalSource.operationIds.filter((id) => id !== UPLOAD);
  assert.equal(expected.length, 18);
  assert.deepEqual([...TECH_LOG_STUDIO_OPERATION_IDS].sort(), [...expected].sort());
});

test("pins the canonical digest and revision as external package provenance", () => {
  const source = TECH_LOG_STUDIO_CONTRIBUTION.source;
  assert.equal(source.kind, "EXTERNAL_PACKAGE");
  if (source.kind !== "EXTERNAL_PACKAGE") return;
  assert.equal(source.package.packageId, canonicalSource.packageId);
  assert.equal(source.package.version, canonicalSource.version);
  assert.equal(source.package.digest, canonicalSource.digest);
  assert.equal(source.package.sourceRevision, canonicalSource.sourceRevision);
  assert.equal(source.package.runtimeProtocolVersion, 1);
});

test("composes without violating the platform contract runtime", () => {
  const composed = composeContractContributions([TECH_LOG_STUDIO_CONTRIBUTION]);
  assert.equal(composed.externalPackages.length, 1);
});

test("every mutating operation replays by idempotency key and never auto-retries", () => {
  for (const entry of TECH_LOG_STUDIO_CONTRIBUTION.http) {
    if (entry.contract.retrySemantics !== "KEYED") continue;
    assert.deepEqual(entry.contract.commandRecovery, {
      mode: "IDEMPOTENCY_REPLAY",
      operationIdentityField: "idempotencyKey",
    }, `${entry.contract.operationId} recovery`);
    assert.equal(entry.frontend.retryBudget, 0, `${entry.contract.operationId} budget`);
  }
});

test("path templates match the canonical /api/v1/studio prefix", () => {
  for (const entry of TECH_LOG_STUDIO_CONTRIBUTION.http) {
    assert.ok(
      entry.contract.pathTemplate.startsWith("/api/v1/studio/"),
      `${entry.contract.operationId}: ${entry.contract.pathTemplate}`,
    );
  }
});
```

- [ ] **Step 3: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-contract-contribution.test.ts`
Expected: FAIL — 기여 모듈을 찾을 수 없다.

- [ ] **Step 4: 기여 파일 작성**

`src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts`. 먼저 공용 헬퍼와 대표 operation 두 개를 정확한 형태로 만든 뒤, 위 표의 나머지 16개를 같은 헬퍼로 선언한다.

```typescript
import { z } from "zod";

import type {
  CommandEffectDescriptor,
  InstalledContractContribution,
  InstalledHttpContract,
  RuntimeValidator,
} from "../../../contracts/external-contract-runtime.ts";
import { TECH_LOG_FEATURE_ID } from "../application/tech-log-feature-input.ts";
import canonicalSource from "./studio/canonical-source.json" with { type: "json" };
import { STUDIO_ERROR_CODES } from "../adapters/http/studio-error-mapping.ts";

function zodValidator<T>(schemaId: string, schema: z.ZodType<T>): RuntimeValidator<T> {
  return Object.freeze({
    schemaId,
    safeParse(value: unknown) {
      const result = schema.safeParse(value);
      if (result.success) {
        return Object.freeze({ success: true as const, data: structuredClone(result.data) });
      }
      return Object.freeze({
        success: false as const,
        issues: Object.freeze(
          result.error.issues.map((issue) =>
            Object.freeze({
              path: Object.freeze(
                issue.path.map((segment): string | number =>
                  typeof segment === "number" ? segment : String(segment),
                ),
              ),
              code: String(issue.code),
            }),
          ),
        ),
      });
    },
  });
}

/**
 * 서버 payload는 canonical 계약이 소유한다. 전송 계층은 문제 문서만 엄격히
 * 검증하고 성공 payload는 통과시킨다 — generated 타입이 컴파일 시점 계약이고,
 * 런타임 재검증은 계약 갱신 때마다 두 곳을 고치게 만든다.
 */
const passthrough = <T>(schemaId: string) =>
  zodValidator<T>(schemaId, z.unknown() as unknown as z.ZodType<T>);

const problemSchema = z
  .object({
    type: z.string().min(1).max(512),
    title: z.string().min(1).max(240),
    status: z.int().min(400).max(599),
    detail: z.string().min(1).max(5000),
    code: z.enum(STUDIO_ERROR_CODES as unknown as [string, ...string[]]),
  })
  .loose();

const PROBLEM = zodValidator("StudioProblemDetails", problemSchema);

/** 4xx 도메인 거절은 적용되지 않았음이 확정이다. 5xx/네트워크는 불확정이다. */
const COMMAND_EFFECT: CommandEffectDescriptor<z.output<typeof problemSchema>> =
  Object.freeze({
    successEffect: "APPLIED_CONFIRMED" as const,
    classifyProblem({ status }: Readonly<{ status: number; problem: unknown }>) {
      return status >= 400 && status < 500 ? "NOT_APPLIED" : "MAYBE_APPLIED";
    },
  });

type PathValues = Readonly<Record<string, string>>;
type QueryEntries = readonly (readonly [string, string])[];

function safeOperation(
  operationId: string,
  pathTemplate: string,
  responseByteLimit: number,
  project: (input: never) => Readonly<{ pathValues: PathValues; queryEntries: QueryEntries }>,
): InstalledHttpContract<unknown, unknown, unknown> {
  return Object.freeze({
    contract: Object.freeze({
      operationId,
      method: "GET" as const,
      pathTemplate,
      inputValidator: passthrough(`${operationId}Input`),
      outputValidator: passthrough(`${operationId}Output`),
      problemValidator: PROBLEM,
      acceptedStatuses: Object.freeze([200]),
      emptyBodyStatuses: Object.freeze([]),
      retrySemantics: "SAFE" as const,
      requestBody: "NONE" as const,
      responseBody: "REQUIRED_JSON" as const,
      commandRecovery: null,
      commandEffect: null,
      projectRequest(input: never) {
        const projected = project(input);
        return Object.freeze({ ...projected, body: null });
      },
    }),
    frontend: Object.freeze({
      policyId: `${operationId}_V1`,
      requestByteLimit: 0,
      responseByteLimit,
      totalDeadlineMs: 10_000,
      retryBudget: 2 as const,
      authProfileId: "TECH_LOG_STUDIO_SESSION",
      diagnosticsOperation: `techLog.studio.${operationId}`,
    }),
  }) as InstalledHttpContract<unknown, unknown, unknown>;
}

function keyedOperation(
  operationId: string,
  method: "POST" | "PUT" | "DELETE",
  pathTemplate: string,
  options: Readonly<{
    acceptedStatus: number;
    responseByteLimit: number;
    requestByteLimit: number;
    hasBody: boolean;
  }>,
  project: (input: never) => Readonly<{
    pathValues: PathValues;
    queryEntries: QueryEntries;
    body: unknown;
  }>,
): InstalledHttpContract<unknown, unknown, unknown> {
  return Object.freeze({
    contract: Object.freeze({
      operationId,
      method,
      pathTemplate,
      inputValidator: passthrough(`${operationId}Input`),
      outputValidator: passthrough(`${operationId}Output`),
      problemValidator: PROBLEM,
      acceptedStatuses: Object.freeze([options.acceptedStatus]),
      emptyBodyStatuses: Object.freeze(options.acceptedStatus === 204 ? [204] : []),
      retrySemantics: "KEYED" as const,
      requestBody: options.hasBody ? ("JSON" as const) : ("NONE" as const),
      responseBody: options.acceptedStatus === 204 ? ("NONE" as const) : ("REQUIRED_JSON" as const),
      commandRecovery: Object.freeze({
        mode: "IDEMPOTENCY_REPLAY" as const,
        operationIdentityField: "idempotencyKey",
      }),
      commandEffect: COMMAND_EFFECT,
      projectRequest: project,
    }),
    frontend: Object.freeze({
      policyId: `${operationId}_V1`,
      requestByteLimit: options.requestByteLimit,
      responseByteLimit: options.responseByteLimit,
      totalDeadlineMs: 10_000,
      // §8.3. 발신된 KEYED 명령은 자동 재시도하지 않는다.
      retryBudget: 0 as const,
      authProfileId: "TECH_LOG_STUDIO_SESSION",
      diagnosticsOperation: `techLog.studio.${operationId}`,
    }),
  }) as InstalledHttpContract<unknown, unknown, unknown>;
}

const NO_PATH = Object.freeze({});
const NO_QUERY = Object.freeze([]) as QueryEntries;

function queryOf(input: Readonly<Record<string, unknown>>): QueryEntries {
  const entries: (readonly [string, string])[] = [];
  for (const [key, value] of Object.entries(input)) {
    if (value === undefined || value === null) continue;
    entries.push([key, String(value)]);
  }
  return Object.freeze(entries);
}
```

대표 operation 두 개:

```typescript
const GET_STUDIO_SESSION = safeOperation(
  "getStudioSession",
  "/api/v1/studio/session",
  8_192,
  () => Object.freeze({ pathValues: NO_PATH, queryEntries: NO_QUERY }),
);

const SAVE_STUDIO_DOCUMENT = keyedOperation(
  "saveStudioDocument",
  "PUT",
  "/api/v1/studio/documents/{documentId}",
  { acceptedStatus: 200, responseByteLimit: 524_288, requestByteLimit: 524_288, hasBody: true },
  (input: never) => {
    const value = input as unknown as Readonly<{
      documentId: string;
      expectedVersion: number;
      document: unknown;
    }>;
    return Object.freeze({
      pathValues: Object.freeze({ documentId: value.documentId }),
      queryEntries: NO_QUERY,
      body: Object.freeze({
        expectedVersion: value.expectedVersion,
        document: value.document,
      }),
    });
  },
);
```

나머지 16개를 같은 두 헬퍼로 선언한다. 표의 `respLimit`을 `responseByteLimit`에, 본문이 있는 KEYED operation의 `requestByteLimit`은 `responseByteLimit`과 같은 값을, 본문 없는 `deleteStudioAsset`은 `0`을 쓴다.

query를 갖는 SAFE operation의 `projectRequest`는 `queryOf`를 쓴다. 예를 들어 `listStudioDocuments`는 `q, kind, publicationStatus, nextAction, projectId, sort, cursor, limit`을, `listStudioPublications`는 `q, type, cursor, limit`을, `listStudioCatalog`는 `type, q, cursor, limit`을, `listStudioAssets`는 `q, kind, managementStatus, cursor, limit`을 넘긴다.

path 파라미터를 갖는 operation의 `pathValues` 키는 템플릿과 정확히 같아야 한다: `documentId`, `publicationId`, `publicationEventId`, `assetId`.

마지막에 기여를 조립한다:

```typescript
const HTTP_CONTRACTS = Object.freeze([
  GET_STUDIO_SESSION,
  GET_STUDIO_DASHBOARD,
  LIST_STUDIO_DOCUMENTS,
  CREATE_STUDIO_DOCUMENT,
  GET_STUDIO_DOCUMENT,
  SAVE_STUDIO_DOCUMENT,
  VALIDATE_STUDIO_DOCUMENT,
  GET_CURRENT_STUDIO_PREVIEW,
  CREATE_STUDIO_PREVIEW,
  PUBLISH_STUDIO_DOCUMENT,
  LIST_STUDIO_PUBLICATIONS,
  UNPUBLISH_STUDIO_PUBLICATION,
  GET_STUDIO_PUBLICATION_SNAPSHOT,
  LIST_STUDIO_CATALOG,
  LIST_STUDIO_ASSETS,
  GET_STUDIO_ASSET,
  UPDATE_STUDIO_ASSET,
  DELETE_STUDIO_ASSET,
]);

export const TECH_LOG_STUDIO_OPERATION_IDS = Object.freeze(
  HTTP_CONTRACTS.map((entry) => entry.contract.operationId),
);

export type TechLogStudioOperationId =
  (typeof TECH_LOG_STUDIO_OPERATION_IDS)[number];

export const TECH_LOG_STUDIO_CONTRIBUTION: InstalledContractContribution =
  Object.freeze({
    contributionId: "tech-log-studio-http-v1",
    featureId: TECH_LOG_FEATURE_ID,
    source: Object.freeze({
      kind: "EXTERNAL_PACKAGE" as const,
      package: Object.freeze({
        packageId: canonicalSource.packageId,
        version: canonicalSource.version,
        digest: canonicalSource.digest as `sha256:${string}`,
        runtimeProtocolVersion: 1 as const,
        sourceRevision: canonicalSource.sourceRevision,
      }),
    }),
    http: HTTP_CONTRACTS,
    events: Object.freeze([]),
  });
```

- [ ] **Step 5: 설치 등록부에 추가**

`src/features/installed-contract-contributions.ts`의 `INSTALLED_CONTRACT_CONTRIBUTIONS`를 수정한다. TechLog는 항상 설치되므로 조건 없이 포함한다:

```typescript
import { TECH_LOG_STUDIO_CONTRIBUTION } from "./tech-log/contracts/tech-log-studio-contract-contribution.ts";

export const INSTALLED_CONTRACT_CONTRIBUTIONS: readonly InstalledContractContribution[] =
  Object.freeze(
    INSTALLED_PRODUCT_FEATURE_IDS.includes(REFERENCE_FEATURE_ID)
      ? [REFERENCE_FEATURE_TEMPLATE_CONTRIBUTION, TECH_LOG_STUDIO_CONTRIBUTION]
      : [TECH_LOG_STUDIO_CONTRIBUTION],
  );
```

- [ ] **Step 6: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-contract-contribution.test.ts`
Expected: 5 tests PASS

- [ ] **Step 7: 계약 집합과 아키텍처 게이트 확인**

Run: `corepack pnpm check:types:app && corepack pnpm generate:contract-set && corepack pnpm check:architecture`
Expected: PASS. `contractSet`에 `@tech-log/studio-contract@2.0.0`이 나타난다. `EXTERNAL_PACKAGE`이므로 `TEMPLATE_FIXTURE`와 달리 release digest에 반영된다.

- [ ] **Step 8: 커밋**

```bash
git add src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts \
  src/contracts/rest-profiles.ts src/features/installed-contract-contributions.ts \
  tests/features/tech-log/studio-contract-contribution.test.ts \
  tests/runtime-schema/http-schema.test.ts .generated/
git commit -m "feat: register the TechLog Studio contract contribution"
```

---

### Task 4: HTTP StudioGateway 구현

**Files:**
- Create: `src/features/tech-log/adapters/http/http-studio-gateway.ts`
- Create: `tests/mocks/handlers/tech-log-studio.ts`
- Move: `src/features/tech-log/adapters/mock/stable-stringify.ts` → `src/features/tech-log/adapters/stable-stringify.ts` (mock의 import 경로를 함께 고친다)
- Test: `tests/features/tech-log/http-studio-gateway.test.ts`

HTTP 어댑터가 `mock/`에서 import하면 프로덕션 경로가 mock 경로에 의존한다. 두 어댑터가 공유하는 순수 함수이므로 한 단계 위로 옮긴다. 내용은 바꾸지 않는다.

**Interfaces:**
- Consumes: `toStudioGatewayError`/`createCsrfTokenProvider`(Task 2), `TechLogStudioOperationId`(Task 3), `StudioGateway`(`application/ports/studio-gateway.ts`), `InstalledContractOperationExecutor`(`features/reference-feature/adapters/create-reference-feature-input.ts`의 동형 타입)
- Produces:
  - `type StudioOperationExecutor = Readonly<{ execute(operationId: string, input: unknown, context: Readonly<{ routeId: string; signal?: AbortSignal; intent?: MutationIntent }>): Promise<HttpExecutionOutcome<unknown, unknown>> }>`
  - `createHttpStudioGateway(deps: Readonly<{ operations: StudioOperationExecutor }>): StudioGateway`
  - `mutationIntent(operationId: string, idempotencyKey: string, input: unknown): MutationIntent` — Task 6도 이 함수를 쓴다

- [ ] **Step 1: MSW 핸들러 작성**

`tests/mocks/handlers/tech-log-studio.ts`. mock gateway가 이미 canonical 의미론의 완전한 구현체이므로 재사용한다.

```typescript
import { http, HttpResponse } from "msw";

import { createMockStudioGateway } from "../../../src/features/tech-log/adapters/mock/mock-studio-gateway.ts";
import { isStudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

const BASE = "http://api.test";

function problemResponse(error: unknown) {
  if (isStudioGatewayError(error)) {
    return HttpResponse.json(error.problem, {
      status: error.status,
      headers: { "content-type": "application/problem+json" },
    });
  }
  throw error;
}

async function json(work: () => Promise<unknown>, status = 200) {
  try {
    return HttpResponse.json((await work()) as never, { status });
  } catch (error) {
    return problemResponse(error);
  }
}

export function createTechLogStudioHandlers(
  gateway = createMockStudioGateway(),
  baseUrl = BASE,
) {
  const key = (request: Request) =>
    request.headers.get("Idempotency-Key") ?? "missing-key";

  return {
    gateway,
    handlers: [
      http.get(`${baseUrl}/api/v1/studio/session`, () =>
        HttpResponse.json({
          authenticated: true,
          displayName: "테스트 편집자",
          roles: ["STUDIO_EDITOR"],
          csrfToken: "csrf-test-token",
          csrfHeaderName: "X-CSRF-TOKEN",
        }),
      ),
      http.get(`${baseUrl}/api/v1/studio/dashboard`, () =>
        json(() => gateway.getDashboard()),
      ),
      http.get(`${baseUrl}/api/v1/studio/documents`, ({ request }) => {
        const url = new URL(request.url);
        const limit = url.searchParams.get("limit");
        return json(() =>
          gateway.listDocuments({
            ...(url.searchParams.get("q") ? { q: url.searchParams.get("q")! } : {}),
            ...(limit ? { limit: Number(limit) } : {}),
          } as never),
        );
      }),
      http.post(`${baseUrl}/api/v1/studio/documents`, async ({ request }) =>
        json(
          async () =>
            gateway.createDocument((await request.json()) as never, {
              idempotencyKey: key(request),
            }),
          201,
        ),
      ),
      http.get(`${baseUrl}/api/v1/studio/documents/:documentId`, ({ params }) =>
        json(() => gateway.getDocument(String(params.documentId))),
      ),
      http.put(
        `${baseUrl}/api/v1/studio/documents/:documentId`,
        async ({ request, params }) =>
          json(async () =>
            gateway.saveDocument(
              String(params.documentId),
              (await request.json()) as never,
              { idempotencyKey: key(request) },
            ),
          ),
      ),
      http.post(
        `${baseUrl}/api/v1/studio/documents/:documentId/validate`,
        async ({ request, params }) =>
          json(async () =>
            gateway.validateDocument(
              String(params.documentId),
              (await request.json()) as never,
              { idempotencyKey: key(request) },
            ),
          ),
      ),
      http.get(
        `${baseUrl}/api/v1/studio/documents/:documentId/preview`,
        ({ params }) => json(() => gateway.getCurrentPreview(String(params.documentId))),
      ),
      http.post(
        `${baseUrl}/api/v1/studio/documents/:documentId/preview`,
        async ({ request, params }) =>
          json(
            async () =>
              gateway.createPreview(
                String(params.documentId),
                (await request.json()) as never,
                { idempotencyKey: key(request) },
              ),
            201,
          ),
      ),
      http.post(
        `${baseUrl}/api/v1/studio/documents/:documentId/publish`,
        async ({ request, params }) =>
          json(async () =>
            gateway.publishDocument(
              String(params.documentId),
              (await request.json()) as never,
              { idempotencyKey: key(request) },
            ),
          ),
      ),
      http.get(`${baseUrl}/api/v1/studio/publications`, () =>
        json(() => gateway.listPublications({})),
      ),
      http.post(
        `${baseUrl}/api/v1/studio/publications/:publicationId/unpublish`,
        async ({ request, params }) =>
          json(async () =>
            gateway.unpublishPublication(
              String(params.publicationId),
              (await request.json()) as never,
              { idempotencyKey: key(request) },
            ),
          ),
      ),
      http.get(
        `${baseUrl}/api/v1/studio/publications/:publicationEventId/preview`,
        ({ params }) =>
          json(() => gateway.getPublicationSnapshot(String(params.publicationEventId))),
      ),
      http.get(`${baseUrl}/api/v1/studio/catalog`, ({ request }) => {
        const url = new URL(request.url);
        return json(() =>
          gateway.getCatalog({ type: url.searchParams.get("type") as never }),
        );
      }),
    ],
  };
}
```

- [ ] **Step 2: 실패하는 gateway 테스트 작성**

`tests/features/tech-log/http-studio-gateway.test.ts`:

```typescript
import assert from "node:assert/strict";
import { afterAll, afterEach, beforeAll, test } from "vitest";
import { setupServer } from "msw/node";

import { createHttpStudioGateway } from "../../../src/features/tech-log/adapters/http/http-studio-gateway.ts";
import { createCsrfTokenProvider } from "../../../src/features/tech-log/adapters/http/studio-session-csrf.ts";
import { createTechLogStudioHandlers } from "../../mocks/handlers/tech-log-studio.ts";
import { FIXTURE_IDS } from "../../../src/features/tech-log/adapters/mock/fixtures.ts";
import { isStudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

const { handlers } = createTechLogStudioHandlers();
const server = setupServer(...handlers);

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

/**
 * 전송 계층을 얇게 세운다. 이 테스트가 증명하는 것은 gateway가 canonical
 * 경로/본문/헤더를 정확히 만들고 응답을 포트 계약으로 되돌린다는 것이다.
 */
function gatewayUnderTest() {
  const seen: { csrf: string | null; idempotency: string | null }[] = [];
  const operations = {
    async execute(operationId: string, input: unknown, context: never) {
      void operationId;
      void input;
      void context;
      throw new Error("replaced in Step 4");
    },
  };
  return { operations, seen };
}

test("reads the dashboard through the canonical path", async () => {
  const gateway = createHttpStudioGateway(await realDependencies());
  const dashboard = await gateway.getDashboard();
  assert.equal(typeof dashboard.totals.documents, "number");
  assert.ok(dashboard.totals.documents > 0);
});

test("saves with expectedVersion and returns the new version", async () => {
  const gateway = createHttpStudioGateway(await realDependencies());
  const before = await gateway.getDocument(FIXTURE_IDS.fetchJoinCase);
  const { id, version, updatedAt, ...input } = before.document;
  void id;
  void updatedAt;

  const saved = await gateway.saveDocument(
    before.document.id,
    { expectedVersion: version, document: { ...input, title: "HTTP 경로로 저장" } },
    { idempotencyKey: "save-1" },
  );

  assert.equal(saved.document.title, "HTTP 경로로 저장");
  assert.equal(saved.document.version, version + 1);
});

test("surfaces VERSION_CONFLICT as the port error, not a transport error", async () => {
  const gateway = createHttpStudioGateway(await realDependencies());
  const before = await gateway.getDocument(FIXTURE_IDS.fetchJoinCase);
  const { id, version, updatedAt, ...input } = before.document;
  void id;
  void updatedAt;

  await assert.rejects(
    gateway.saveDocument(
      before.document.id,
      { expectedVersion: version + 99, document: input },
      { idempotencyKey: "conflict-1" },
    ),
    (error: unknown) => {
      assert.ok(isStudioGatewayError(error));
      assert.equal(error.code, "VERSION_CONFLICT");
      assert.equal(error.status, 409);
      return true;
    },
  );
});

test("sends the CSRF header and an Idempotency-Key on every mutation", async () => {
  const captured: { csrf: string | null; key: string | null }[] = [];
  server.use(
    ...createTechLogStudioHandlers().handlers,
  );
  server.events.on("request:start", ({ request }) => {
    if (request.method === "GET") return;
    captured.push({
      csrf: request.headers.get("X-CSRF-TOKEN"),
      key: request.headers.get("Idempotency-Key"),
    });
  });

  const gateway = createHttpStudioGateway(await realDependencies());
  const before = await gateway.getDocument(FIXTURE_IDS.fetchJoinCase);
  const { id, version, updatedAt, ...input } = before.document;
  void id;
  void updatedAt;
  await gateway.saveDocument(
    before.document.id,
    { expectedVersion: version, document: input },
    { idempotencyKey: "csrf-1" },
  );

  assert.equal(captured.length, 1);
  assert.equal(captured[0]!.csrf, "csrf-test-token");
  assert.equal(captured[0]!.key, "csrf-1");
});
```

`realDependencies()`는 Step 4에서 만드는 헬퍼다. 이 Step에서는 파일이 없어 실패해야 정상이다.

- [ ] **Step 3: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/http-studio-gateway.test.ts`
Expected: FAIL — `http-studio-gateway.ts`를 찾을 수 없다.

- [ ] **Step 4: gateway 구현**

`src/features/tech-log/adapters/http/http-studio-gateway.ts`. 모든 메서드는 같은 두 헬퍼를 통과한다.

```typescript
import {
  defineIdempotencyKey,
  defineMutationIntent,
  type MutationIntent,
} from "../../../../contracts/mutation-intent.ts";
import type { HttpExecutionOutcome } from "../../../../adapters/http/http-execution-v3.ts";
import { stableStringify } from "../stable-stringify.ts";
import type {
  IdempotentOptions,
  RequestOptions,
  StudioGateway,
} from "../../application/ports/studio-gateway.ts";
import { toStudioGatewayError } from "./studio-error-mapping.ts";
import type { CsrfTokenProvider } from "./studio-session-csrf.ts";

export type StudioOperationExecutor = Readonly<{
  execute(
    operationId: string,
    input: unknown,
    context: Readonly<{
      routeId: string;
      signal?: AbortSignal;
      intent?: MutationIntent;
    }>,
  ): Promise<HttpExecutionOutcome<unknown, unknown>>;
}>;

export type HttpStudioGatewayDependencies = Readonly<{
  operations: StudioOperationExecutor;
}>;

const ROUTE_ID = "TECH_LOG_STUDIO";

/**
 * `createBrowserMutationIntentFactory`는 쓰지 않는다. 그 factory는
 * `requiresIdempotencyKey`일 때 키를 **스스로 생성**하는데, 이 포트의 키는
 * 호출자가 만들어 안전한 재시도에 재사용하는 값이다. `defineMutationIntent`가
 * 호출자 공급 키를 검증하며 받아주는 정식 경로다(`mutation-intent.ts`의
 * "A caller-supplied value is never trimmed, regenerated or silently dropped").
 */
export function mutationIntent(
  operationId: string,
  idempotencyKey: string,
  input: unknown,
): MutationIntent {
  return defineMutationIntent({
    intentId: globalThis.crypto.randomUUID(),
    operationId,
    canonicalInputIdentity: canonicalIdentity(input),
    idempotencyKey: defineIdempotencyKey(idempotencyKey),
    createdAtMonotonicMs: globalThis.performance.now(),
  });
}

/** 같은 명령의 재시도가 같은 신원을 갖도록 키 순서를 고정해 직렬화한다. */
function canonicalIdentity(input: unknown): string {
  const identity = stableStringify(input);
  return identity.length > 16_000 ? identity.slice(0, 16_000) : identity;
}

/**
 * 헤더는 gateway가 만들지 않는다. `Idempotency-Key`는 실행 context의 intent에서,
 * `x-csrf-token`은 credential collaborator에서 온다. gateway가 입력 본문에
 * 넣으면 계약 본문이 오염되고 계약 소유 헤더는 거절된다.
 */
export function createHttpStudioGateway(
  deps: HttpStudioGatewayDependencies,
): StudioGateway {
  async function read<T>(
    operationId: string,
    input: unknown,
    options?: RequestOptions,
  ): Promise<T> {
    const outcome = await deps.operations.execute(operationId, input, {
      routeId: ROUTE_ID,
      ...(options?.signal ? { signal: options.signal } : {}),
    });
    if (outcome.kind !== "SUCCESS") throw toStudioGatewayError(outcome, operationId);
    return outcome.value as T;
  }

  async function command<T>(
    operationId: string,
    input: unknown,
    options: IdempotentOptions,
  ): Promise<T> {
    const outcome = await deps.operations.execute(operationId, input, {
      routeId: ROUTE_ID,
      intent: mutationIntent(operationId, options.idempotencyKey, input),
      ...(options.signal ? { signal: options.signal } : {}),
    });
    if (outcome.kind === "SUCCESS") return outcome.value as T;
    throw toStudioGatewayError(outcome, operationId);
  }

  return Object.freeze({
    getDashboard: (options) => read("getStudioDashboard", {}, options),
    listDocuments: (query, options) => read("listStudioDocuments", query, options),
    createDocument: (input, options) => command("createStudioDocument", input, options),
    getDocument: (documentId, options) =>
      read("getStudioDocument", { documentId }, options),
    saveDocument: (documentId, cmd, options) =>
      command("saveStudioDocument", { documentId, ...cmd }, options),
    validateDocument: (documentId, cmd, options) =>
      command("validateStudioDocument", { documentId, ...cmd }, options),
    createPreview: (documentId, cmd, options) =>
      command("createStudioPreview", { documentId, ...cmd }, options),
    getCurrentPreview: (documentId, options) =>
      read("getCurrentStudioPreview", { documentId }, options),
    publishDocument: (documentId, cmd, options) =>
      command("publishStudioDocument", { documentId, ...cmd }, options),
    unpublishPublication: (publicationId, cmd, options) =>
      command("unpublishStudioPublication", { publicationId, ...cmd }, options),
    listPublications: (query, options) => read("listStudioPublications", query, options),
    getPublicationSnapshot: (publicationEventId, options) =>
      read("getStudioPublicationSnapshot", { publicationEventId }, options),
    getCatalog: (query, options) => read("listStudioCatalog", query, options),
  }) satisfies StudioGateway;
}
```

- [ ] **Step 5: 테스트 헬퍼 완성**

`http-studio-gateway.test.ts`의 `gatewayUnderTest` 스텁을 지우고 `realDependencies()`를 넣는다. 플랫폼 계약 런타임을 실제로 조립하지 않고, 계약 기여의 `projectRequest`로 요청을 만들어 `fetch`로 보내는 얇은 executor를 쓴다 — 이 테스트의 대상은 gateway이지 플랫폼 전송이 아니다.

```typescript
import { TECH_LOG_STUDIO_CONTRIBUTION } from "../../../src/features/tech-log/contracts/tech-log-studio-contract-contribution.ts";

const BASE = "http://api.test";

async function realDependencies() {
  const byId = new Map(
    TECH_LOG_STUDIO_CONTRIBUTION.http.map((entry) => [entry.contract.operationId, entry]),
  );

  const csrf = createCsrfTokenProvider({
    async execute() {
      const response = await fetch(`${BASE}/api/v1/studio/session`);
      const body = (await response.json()) as {
        csrfToken: string;
        csrfHeaderName: string;
      };
      return { csrfToken: body.csrfToken, csrfHeaderName: body.csrfHeaderName };
    },
  });

  const operations = {
    async execute(operationId: string, input: unknown, context: { signal?: AbortSignal; intent?: unknown }) {
      const entry = byId.get(operationId);
      if (!entry) throw new Error(`unregistered operation: ${operationId}`);
      const { contract } = entry;
      const projected = contract.projectRequest(input as never);

      let path = contract.pathTemplate;
      for (const [name, value] of Object.entries(projected.pathValues)) {
        path = path.replace(`{${name}}`, encodeURIComponent(value));
      }
      const url = new URL(`${BASE}${path}`);
      for (const [name, value] of projected.queryEntries) {
        url.searchParams.append(name, value);
      }

      // 실행기가 헤더를 만드는 두 경로를 그대로 재현한다: intent → Idempotency-Key,
      // credential collaborator → x-csrf-token.
      const headers: Record<string, string> = {};
      if (contract.retrySemantics === "KEYED") {
        const intent = (context as { intent?: { idempotencyKey?: string } }).intent;
        if (intent?.idempotencyKey) headers["Idempotency-Key"] = intent.idempotencyKey;
        headers["X-CSRF-TOKEN"] = await csrf.token();
      }
      if (contract.requestBody === "JSON") headers["content-type"] = "application/json";

      const response = await fetch(url, {
        method: contract.method,
        headers,
        ...(contract.requestBody === "JSON"
          ? { body: JSON.stringify(projected.body) }
          : {}),
        ...(context.signal ? { signal: context.signal } : {}),
      });

      if (contract.acceptedStatuses.includes(response.status)) {
        const value =
          contract.responseBody === "NONE" ? null : await response.json();
        return { kind: "SUCCESS" as const, value, effect: "APPLIED_CONFIRMED" as const };
      }
      return {
        kind: "PROBLEM" as const,
        problem: await response.json(),
        metadata: { status: response.status },
        effect: "NOT_APPLIED" as const,
      };
    },
  };

  return { operations } as never;
}
```

Task 3의 각 KEYED `projectRequest`는 body를 명시적으로 조립해야 한다(`SAVE_STUDIO_DOCUMENT` 예시가 그렇게 돼 있다) — 입력을 그대로 spread하면 계약에 없는 필드가 본문에 섞인다. 이 테스트가 그 규칙을 지킨다.

- [ ] **Step 6: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/http-studio-gateway.test.ts`
Expected: 4 tests PASS

- [ ] **Step 7: 커밋**

```bash
git add src/features/tech-log/adapters/http/http-studio-gateway.ts \
  tests/mocks/handlers/tech-log-studio.ts \
  tests/features/tech-log/http-studio-gateway.test.ts
git commit -m "feat: implement the TechLog Studio HTTP gateway"
```

---

### Task 5: 런타임 스위치

`config/runtime/*.json`은 `.strict()` zod 스키마로 검증되므로 새 키는 스키마에 먼저 추가해야 한다. **선택 필드 + 기본값 `MOCK`**으로 추가해 기존 문서와 V1 호환성을 깨지 않는다.

**Files:**
- Modify: `src/contracts/release-artifacts.ts:153-161` (V2 스키마에만 추가)
- Modify: `src/bootstrap/runtime-config-schema.ts:35-55, 108-141`
- Modify: `src/contracts/env.ts:33-56`
- Modify: `config/runtime/local.json`, `development.json`, `staging.json`, `production.json`
- Modify: `src/features/tech-log/adapters/create-tech-log-feature-input.ts`
- Modify: `src/features/installed-feature-adapters.ts`
- Modify: `src/bootstrap/runtime-adapters.ts:506-508`
- Test: `tests/runtime-schema/runtime-config.test.ts`, `tests/features/tech-log/runtime-composition.test.ts`

**Interfaces:**
- Consumes: `createHttpStudioGateway`(Task 4), `createCsrfTokenProvider`(Task 2)
- Produces: `createTechLogFeatureInstalledInput(context: Readonly<{ studioSource: "MOCK" | "HTTP"; contractOperations: StudioOperationExecutor }>)` — 기존 무인자 시그니처를 대체한다.

- [ ] **Step 1: 실패하는 스키마 테스트 추가**

`tests/runtime-schema/runtime-config.test.ts`에 추가:

```typescript
test("accepts TECH_LOG_STUDIO_SOURCE and defaults it to MOCK", () => {
  const base = {
    APP_ENV: "local",
    API_BASE_URL: "http://localhost:8080/",
    TELEMETRY_ENABLED: false,
    AUTH_MODE: "demo",
    CONFIG_SCHEMA_VERSION: "2.0",
    CAPABILITY_OVERRIDES: {
      REALTIME: "DEFAULT",
      WEB_WORKER: "DEFAULT",
      SERVICE_WORKER: "DEFAULT",
      OFFLINE_COMMANDS: "DEFAULT",
    },
    FEATURE_OVERRIDES: {},
  };

  const defaulted = validateRuntimeConfig(base);
  assert.equal(defaulted.success, true);
  if (defaulted.success) {
    assert.equal(defaulted.data.TECH_LOG_STUDIO_SOURCE, "MOCK");
  }

  const explicit = validateRuntimeConfig({ ...base, TECH_LOG_STUDIO_SOURCE: "HTTP" });
  assert.equal(explicit.success, true);
  if (explicit.success) {
    assert.equal(explicit.data.TECH_LOG_STUDIO_SOURCE, "HTTP");
  }

  const invalid = validateRuntimeConfig({ ...base, TECH_LOG_STUDIO_SOURCE: "LIVE" });
  assert.equal(invalid.success, false);
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm test:runtime-schema`
Expected: FAIL — strict 스키마가 알 수 없는 키를 거절한다.

- [ ] **Step 3: 스키마 확장**

`src/contracts/release-artifacts.ts`의 `runtimeConfigV2ArtifactSchema`에만 한 줄 추가한다. V1은 호환성 리더이므로 건드리지 않는다:

```typescript
export const runtimeConfigV2ArtifactSchema = z
  .object({
    ...runtimeConfigArtifactFields,
    CONFIG_SCHEMA_VERSION: z.literal("2.0"),
    CAPABILITY_OVERRIDES: capabilityOverrideArtifactSchema,
    FEATURE_OVERRIDES: featureOverrideArtifactSchema,
    // TechLog Studio 어댑터 선택. Backend가 없을 때 기본값은 mock이다.
    TECH_LOG_STUDIO_SOURCE: z.enum(["MOCK", "HTTP"]).default("MOCK"),
  })
  .strict()
  .superRefine(runtimeConfigArtifactInvariants);
```

`src/bootstrap/runtime-config-schema.ts`의 `RuntimeConfig` 타입에 추가:

```typescript
  FEATURE_OVERRIDES: ProductFeatureOverrideMap;
  /** §3.5과 같은 결의 런타임 선택. V1 문서는 항상 MOCK으로 정규화된다. */
  TECH_LOG_STUDIO_SOURCE: "MOCK" | "HTTP";
```

같은 파일의 `normalized` 조립에 추가:

```typescript
    FEATURE_OVERRIDES: Object.freeze({
      ...(isV2 ? (parsed as RuntimeConfigV2).FEATURE_OVERRIDES : {}),
    }),
    TECH_LOG_STUDIO_SOURCE: isV2
      ? (parsed as RuntimeConfigV2).TECH_LOG_STUDIO_SOURCE
      : "MOCK",
```

`src/contracts/env.ts`의 `ENV_REGISTRY`에 추가:

```typescript
  FEATURE_OVERRIDES: runtime("public", false, null),
  // TechLog Studio 어댑터 선택. Backend 미완성 구간의 기본값은 MOCK이다.
  TECH_LOG_STUDIO_SOURCE: runtime("public", false, "MOCK"),
```

- [ ] **Step 4: 프로필 갱신**

`config/runtime/local.json`과 `development.json`에 `"TECH_LOG_STUDIO_SOURCE": "MOCK"`을, `staging.json`과 `production.json`에 `"TECH_LOG_STUDIO_SOURCE": "HTTP"`를 `FEATURE_OVERRIDES` 앞에 추가한다.

- [ ] **Step 5: green 확인**

Run: `corepack pnpm test:runtime-schema`
Expected: PASS

- [ ] **Step 6: 합성 테스트 갱신**

`tests/features/tech-log/runtime-composition.test.ts`의 `installedInputs()`가 새 인자를 넘기도록 고치고, 스위치 테스트를 추가한다:

```typescript
function installedInputs(
  studioSource: "MOCK" | "HTTP" = "MOCK",
): InstalledInputs {
  return createInstalledFeatureInputs({
    studioSource,
    contractOperations: {
      async execute() {
        throw new Error("executor is not used by composition tests");
      },
    },
  });
}

test("selects the mock gateway by default and the HTTP gateway when switched", () => {
  const mockGateway = installedInputs("MOCK")["tech-log"].createStudioGateway();
  const httpGateway = installedInputs("HTTP")["tech-log"].createStudioGateway();

  // mock은 인메모리 픽스처를 즉시 읽는다. HTTP는 executor를 호출해 실패한다.
  assert.doesNotReject(mockGateway.getDashboard());
  assert.rejects(httpGateway.getDashboard());
});
```

- [ ] **Step 7: 합성 배선 구현**

`src/features/tech-log/adapters/create-tech-log-feature-input.ts`:

```typescript
import {
  TECH_LOG_FEATURE_ID,
  type TechLogFeatureInput,
} from "../application/tech-log-feature-input.ts";
import { createHttpStudioGateway, type StudioOperationExecutor } from "./http/http-studio-gateway.ts";
import { createCsrfTokenProvider } from "./http/studio-session-csrf.ts";
import { createMockStudioGateway } from "./mock/mock-studio-gateway.ts";
import { publicContentQueries } from "./static/public-query.ts";

export type TechLogInstallContext = Readonly<{
  studioSource: "MOCK" | "HTTP";
  contractOperations: StudioOperationExecutor;
}>;

export function createTechLogFeatureInstalledInput(context: TechLogInstallContext) {
  const createStudioGateway = () => {
    if (context.studioSource === "MOCK") return createMockStudioGateway();
    // 세션은 gateway 수명과 같다. 새 Studio 세션은 새 CSRF 토큰을 받는다.
    const csrf = createCsrfTokenProvider({
      async execute(options) {
        const outcome = await context.contractOperations.execute(
          "getStudioSession",
          {},
          { routeId: "TECH_LOG_STUDIO", ...(options?.signal ? { signal: options.signal } : {}) },
        );
        if (outcome.kind !== "SUCCESS") {
          throw new Error("studio session is unavailable");
        }
        const value = outcome.value as { csrfToken: string; csrfHeaderName: string };
        return { csrfToken: value.csrfToken, csrfHeaderName: value.csrfHeaderName };
      },
    });
    return createHttpStudioGateway({ operations: context.contractOperations, csrf });
  };

  const input: TechLogFeatureInput = Object.freeze({
    publicContent: publicContentQueries,
    createStudioGateway,
  });

  return Object.freeze({ featureId: TECH_LOG_FEATURE_ID, input });
}
```

`src/features/installed-feature-adapters.ts`의 `createInstalledFeatureInputs` 시그니처에 `studioSource`를 더하고 `createTechLogFeatureInstalledInput(context)`로 넘긴다.

`src/bootstrap/runtime-adapters.ts:506`의 호출을 고친다:

```typescript
  const featureInputs = createInstalledFeatureInputs({
    contractOperations,
    studioSource: config.TECH_LOG_STUDIO_SOURCE,
  });
```

`config`는 그 스코프에서 이미 쓰이는 런타임 설정 값이다. 이름이 다르면 같은 스코프의 런타임 설정 식별자를 사용한다.

- [ ] **Step 8: green과 전체 회귀 확인**

Run: `corepack pnpm check:types && corepack pnpm test:runtime-schema && corepack pnpm test:tech-log && corepack pnpm test:unit`
Expected: PASS. 기본값이 `MOCK`이므로 기존 Studio 화면 테스트가 전부 그대로 통과해야 한다.

- [ ] **Step 9: 커밋**

```bash
git add src/contracts/release-artifacts.ts src/contracts/env.ts \
  src/bootstrap/runtime-config-schema.ts src/bootstrap/runtime-adapters.ts \
  src/features/installed-feature-adapters.ts \
  src/features/tech-log/adapters/create-tech-log-feature-input.ts \
  config/runtime/ tests/runtime-schema/runtime-config.test.ts \
  tests/features/tech-log/runtime-composition.test.ts
git commit -m "feat: select the TechLog Studio adapter from runtime configuration"
```

---

### Task 6: Asset 포트와 JSON gateway

**Files:**
- Create: `src/features/tech-log/application/ports/studio-asset-gateway.ts`
- Create: `src/features/tech-log/adapters/http/http-studio-asset-gateway.ts`
- Modify: `src/features/tech-log/contracts/studio/contract.ts`
- Test: `tests/features/tech-log/studio-asset-gateway.test.ts`

**Interfaces:**
- Consumes: Task 3의 4개 asset operation, Task 2의 오류 매핑·CSRF, Task 4의 `StudioOperationExecutor`
- Produces:
  - `contract.ts` 신규 alias: `Asset`, `AssetDetail`, `AssetPage`, `AssetKind`, `AssetManagementStatus`, `AssetUsage`, `UpdateAssetCommand`
  - `type ListAssetsQuery = { q?: string; kind?: AssetKind; managementStatus?: AssetManagementStatus; cursor?: string; limit?: number }`
  - `type UploadAssetForm = { file: File; kind: AssetKind; altText?: string; decorative?: boolean }`
  - `interface StudioAssetGateway { listAssets(query, options?): Promise<AssetPage>; uploadAsset(form, options): Promise<Asset>; getAsset(assetId, options?): Promise<AssetDetail>; updateAssetMetadata(assetId, command, options): Promise<Asset>; deleteAsset(assetId, options): Promise<void> }`
  - `createHttpStudioAssetGateway(deps: { operations: StudioOperationExecutor; csrf: CsrfTokenProvider; upload: StudioAssetUploadTransport }): StudioAssetGateway`
  - `type StudioAssetUploadTransport = { upload(form: UploadAssetForm, headers: Readonly<Record<string,string>>, options?: { signal?: AbortSignal }): Promise<Asset> }` — 구현은 Task 7이 제공한다.

- [ ] **Step 1: 계약 alias 추가**

`src/features/tech-log/contracts/studio/contract.ts` 끝에 추가:

```typescript
export type Asset = Schemas["Asset"];
export type AssetDetail = Schemas["AssetDetail"];
export type AssetPage = Schemas["AssetPage"];
export type AssetUsage = Schemas["AssetUsage"];
export type AssetKind = Schemas["AssetKind"];
export type AssetManagementStatus = Schemas["AssetManagementStatus"];
export type UpdateAssetCommand = Schemas["UpdateAssetCommand"];
export type StudioSession = Schemas["StudioSession"];
```

- [ ] **Step 2: 실패하는 테스트 작성**

`tests/features/tech-log/studio-asset-gateway.test.ts`:

```typescript
import assert from "node:assert/strict";
import { test } from "vitest";

import { createHttpStudioAssetGateway } from "../../../src/features/tech-log/adapters/http/http-studio-asset-gateway.ts";
import { createCsrfTokenProvider } from "../../../src/features/tech-log/adapters/http/studio-session-csrf.ts";
import { isStudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

const READY_ASSET = {
  id: "11111111-1111-4111-8111-111111111111",
  assetKey: "fetch-strategy-boundary",
  kind: "DIAGRAM",
  mediaType: "image/svg+xml",
  originalFilename: "boundary.svg",
  byteSize: 4096,
  width: 1080,
  height: 420,
  altText: "Fetch Join과 Batch Fetch 비교",
  decorative: false,
  managementStatus: "READY",
  publicPath: "/media/fetch-strategy-boundary.svg",
  usageCount: 1,
  version: 1,
  createdAt: "2026-08-14T01:00:00.000Z",
  updatedAt: "2026-08-14T01:00:00.000Z",
};

function deps(outcomes: Record<string, unknown>) {
  const calls: { operationId: string; input: unknown }[] = [];
  return {
    calls,
    dependencies: {
      operations: {
        async execute(operationId: string, input: unknown) {
          calls.push({ operationId, input });
          const outcome = outcomes[operationId];
          if (!outcome) throw new Error(`no outcome for ${operationId}`);
          return outcome as never;
        },
      },
      csrf: createCsrfTokenProvider({
        async execute() {
          return { csrfToken: "csrf", csrfHeaderName: "X-CSRF-TOKEN" };
        },
      }),
      upload: {
        async upload() {
          return READY_ASSET as never;
        },
      },
    },
  };
}

test("lists assets through the canonical operation", async () => {
  const { calls, dependencies } = deps({
    listStudioAssets: {
      kind: "SUCCESS",
      value: { items: [READY_ASSET], nextCursor: null },
      effect: "APPLIED_CONFIRMED",
    },
  });
  const gateway = createHttpStudioAssetGateway(dependencies as never);

  const page = await gateway.listAssets({ kind: "DIAGRAM", limit: 20 });

  assert.equal(page.items.length, 1);
  assert.equal(calls[0]!.operationId, "listStudioAssets");
});

test("delegates upload to the transport with CSRF and idempotency headers", async () => {
  let received: Record<string, string> = {};
  const { dependencies } = deps({});
  const gateway = createHttpStudioAssetGateway({
    ...dependencies,
    upload: {
      async upload(_form: unknown, headers: Record<string, string>) {
        received = headers;
        return READY_ASSET as never;
      },
    },
  } as never);

  const asset = await gateway.uploadAsset(
    { file: new File(["<svg/>"], "boundary.svg", { type: "image/svg+xml" }), kind: "DIAGRAM" },
    { idempotencyKey: "upload-1" },
  );

  assert.equal(asset.managementStatus, "READY");
  assert.equal(received["X-CSRF-TOKEN"], "csrf");
  assert.equal(received["Idempotency-Key"], "upload-1");
});

test("surfaces ASSET_IN_USE from a rejected delete", async () => {
  const { dependencies } = deps({
    deleteStudioAsset: {
      kind: "PROBLEM",
      problem: {
        type: "https://techlog.local/problems/asset-in-use",
        title: "ASSET_IN_USE",
        status: 409,
        detail: "사용 중인 Asset은 삭제할 수 없습니다.",
        code: "ASSET_IN_USE",
      },
      metadata: { status: 409 },
      effect: "NOT_APPLIED",
    },
  });
  const gateway = createHttpStudioAssetGateway(dependencies as never);

  await assert.rejects(
    gateway.deleteAsset(READY_ASSET.id, { idempotencyKey: "delete-1" }),
    (error: unknown) => {
      assert.ok(isStudioGatewayError(error));
      assert.equal(error.code, "ASSET_IN_USE");
      return true;
    },
  );
});

test("sends expectedVersion when updating metadata", async () => {
  const { calls, dependencies } = deps({
    updateStudioAsset: {
      kind: "SUCCESS",
      value: { ...READY_ASSET, version: 2, decorative: true, altText: null },
      effect: "APPLIED_CONFIRMED",
    },
  });
  const gateway = createHttpStudioAssetGateway(dependencies as never);

  const updated = await gateway.updateAssetMetadata(
    READY_ASSET.id,
    { expectedVersion: 1, decorative: true, altText: null },
    { idempotencyKey: "update-1" },
  );

  assert.equal(updated.version, 2);
  const input = calls[0]!.input as Record<string, unknown>;
  assert.equal(input["expectedVersion"], 1);
  assert.equal(input["assetId"], READY_ASSET.id);
});
```

- [ ] **Step 3: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-asset-gateway.test.ts`
Expected: FAIL — 두 모듈이 없다.

- [ ] **Step 4: 포트 정의**

`src/features/tech-log/application/ports/studio-asset-gateway.ts`:

```typescript
import type {
  Asset,
  AssetDetail,
  AssetKind,
  AssetManagementStatus,
  AssetPage,
  UpdateAssetCommand,
} from "../../contracts/studio/contract.ts";
import type { IdempotentOptions, RequestOptions } from "./studio-gateway.ts";

export type ListAssetsQuery = Readonly<{
  q?: string;
  kind?: AssetKind;
  managementStatus?: AssetManagementStatus;
  cursor?: string;
  limit?: number;
}>;

export type UploadAssetForm = Readonly<{
  file: File;
  kind: AssetKind;
  altText?: string;
  decorative?: boolean;
}>;

/**
 * Asset은 `StudioGateway`와 별도 포트다. 파일 전송과 JSON orchestration은
 * 실패 모델이 다르고, 업로드 구현을 presigned/resumable로 바꿀 때 교체 범위가
 * 이 포트 뒤에서 끝나야 한다.
 */
export interface StudioAssetGateway {
  listAssets(query: ListAssetsQuery, options?: RequestOptions): Promise<AssetPage>;
  uploadAsset(form: UploadAssetForm, options: IdempotentOptions): Promise<Asset>;
  getAsset(assetId: string, options?: RequestOptions): Promise<AssetDetail>;
  updateAssetMetadata(
    assetId: string,
    command: UpdateAssetCommand,
    options: IdempotentOptions,
  ): Promise<Asset>;
  deleteAsset(assetId: string, options: IdempotentOptions): Promise<void>;
}
```

- [ ] **Step 5: gateway 구현**

`src/features/tech-log/adapters/http/http-studio-asset-gateway.ts`:

```typescript
import type {
  Asset,
  AssetDetail,
  AssetPage,
  UpdateAssetCommand,
} from "../../contracts/studio/contract.ts";
import type {
  ListAssetsQuery,
  StudioAssetGateway,
  UploadAssetForm,
} from "../../application/ports/studio-asset-gateway.ts";
import type { IdempotentOptions, RequestOptions } from "../../application/ports/studio-gateway.ts";
import { toStudioGatewayError } from "./studio-error-mapping.ts";
import { mutationIntent, type StudioOperationExecutor } from "./http-studio-gateway.ts";
import type { CsrfTokenProvider } from "./studio-session-csrf.ts";

export type StudioAssetUploadTransport = Readonly<{
  upload(
    form: UploadAssetForm,
    headers: Readonly<Record<string, string>>,
    options?: Readonly<{ signal?: AbortSignal }>,
  ): Promise<Asset>;
}>;

export type HttpStudioAssetGatewayDependencies = Readonly<{
  operations: StudioOperationExecutor;
  csrf: CsrfTokenProvider;
  upload: StudioAssetUploadTransport;
}>;

const ROUTE_ID = "TECH_LOG_STUDIO_ASSETS";

export function createHttpStudioAssetGateway(
  deps: HttpStudioAssetGatewayDependencies,
): StudioAssetGateway {
  async function read<T>(operationId: string, input: unknown, options?: RequestOptions) {
    const outcome = await deps.operations.execute(operationId, input, {
      routeId: ROUTE_ID,
      ...(options?.signal ? { signal: options.signal } : {}),
    });
    if (outcome.kind !== "SUCCESS") throw toStudioGatewayError(outcome, operationId);
    return outcome.value as T;
  }

  async function command<T>(operationId: string, input: unknown, options: IdempotentOptions) {
    // Task 4와 동일한 규칙: 헤더는 gateway가 만들지 않는다. `Idempotency-Key`는
    // intent에서, `x-csrf-token`은 credential collaborator에서 온다.
    const outcome = await deps.operations.execute(operationId, input, {
      routeId: ROUTE_ID,
      intent: mutationIntent(operationId, options.idempotencyKey, input),
      ...(options.signal ? { signal: options.signal } : {}),
    });
    if (outcome.kind === "SUCCESS") return outcome.value as T;
    throw toStudioGatewayError(outcome, operationId);
  }

  return Object.freeze({
    listAssets: (query, options) => read<AssetPage>("listStudioAssets", query, options),
    getAsset: (assetId, options) => read<AssetDetail>("getStudioAsset", { assetId }, options),
    async uploadAsset(form, options) {
      const [token, headerName] = await Promise.all([
        deps.csrf.token(options.signal ? { signal: options.signal } : undefined),
        deps.csrf.headerName(options.signal ? { signal: options.signal } : undefined),
      ]);
      return deps.upload.upload(
        form,
        Object.freeze({
          [headerName]: token,
          "Idempotency-Key": options.idempotencyKey,
        }),
        options.signal ? { signal: options.signal } : undefined,
      );
    },
    updateAssetMetadata: (assetId, cmd: UpdateAssetCommand, options) =>
      command<Asset>("updateStudioAsset", { assetId, ...cmd }, options),
    async deleteAsset(assetId, options) {
      await command<null>("deleteStudioAsset", { assetId }, options);
    },
  }) satisfies StudioAssetGateway;
}
```

- [ ] **Step 6: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-asset-gateway.test.ts`
Expected: 4 tests PASS

- [ ] **Step 7: 커밋**

```bash
git add src/features/tech-log/application/ports/studio-asset-gateway.ts \
  src/features/tech-log/adapters/http/http-studio-asset-gateway.ts \
  src/features/tech-log/contracts/studio/contract.ts \
  tests/features/tech-log/studio-asset-gateway.test.ts
git commit -m "feat: add the TechLog Studio asset gateway port and JSON adapter"
```

---

### Task 7: multipart 업로드 전송

플랫폼 계약 런타임은 `requestBody: "NONE" | "JSON"`만 허용하고 저수준 client는 본문을 `JSON.stringify`로 고정한다. 업로드 한 operation만 전용 seam으로 분리한다.

**Files:**
- Create: `src/features/tech-log/adapters/http/asset-upload-transport.ts`
- Create: `docs/reviews/adapters/06-tech-log-asset-upload.md`
- Test: `tests/features/tech-log/asset-upload-transport.test.ts`

**Interfaces:**
- Consumes: `StudioAssetUploadTransport`, `UploadAssetForm`, `Asset`(Task 6), `toStudioGatewayError`(Task 2)
- Produces: `createAssetUploadTransport(deps: Readonly<{ baseUrl: string; timeoutMs: number; fetch?: typeof globalThis.fetch }>): StudioAssetUploadTransport`

- [ ] **Step 1: 실패하는 테스트 작성**

`tests/features/tech-log/asset-upload-transport.test.ts`:

```typescript
import assert from "node:assert/strict";
import { afterAll, afterEach, beforeAll, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";

import { createAssetUploadTransport } from "../../../src/features/tech-log/adapters/http/asset-upload-transport.ts";
import { isStudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

const BASE = "http://api.test";
const server = setupServer();

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

const transport = () =>
  createAssetUploadTransport({ baseUrl: `${BASE}/`, timeoutMs: 10_000 });

const svg = () => new File(["<svg/>"], "b.svg", { type: "image/svg+xml" });

test("posts multipart form data with the supplied headers", async () => {
  let seen: { kind: unknown; alt: unknown; csrf: string | null; key: string | null } | null = null;

  server.use(
    http.post(`${BASE}/api/v1/studio/assets`, async ({ request }) => {
      const form = await request.formData();
      seen = {
        kind: form.get("kind"),
        alt: form.get("altText"),
        csrf: request.headers.get("X-CSRF-TOKEN"),
        key: request.headers.get("Idempotency-Key"),
      };
      return HttpResponse.json({ id: "a", managementStatus: "READY" }, { status: 201 });
    }),
  );

  const asset = await transport().upload(
    { file: svg(), kind: "DIAGRAM", altText: "경계 다이어그램", decorative: false },
    { "X-CSRF-TOKEN": "csrf", "Idempotency-Key": "up-1" },
  );

  assert.equal((asset as { id: string }).id, "a");
  assert.equal(seen!.kind, "DIAGRAM");
  assert.equal(seen!.alt, "경계 다이어그램");
  assert.equal(seen!.csrf, "csrf");
  assert.equal(seen!.key, "up-1");
});

test("does not set content-type itself so the boundary survives", async () => {
  let contentType: string | null = "unset";
  server.use(
    http.post(`${BASE}/api/v1/studio/assets`, ({ request }) => {
      contentType = request.headers.get("content-type");
      return HttpResponse.json({ id: "a" }, { status: 201 });
    }),
  );

  await transport().upload({ file: svg(), kind: "IMAGE" }, {});

  assert.ok(contentType?.startsWith("multipart/form-data; boundary="));
});

test("maps 413 onto PAYLOAD_TOO_LARGE", async () => {
  server.use(
    http.post(`${BASE}/api/v1/studio/assets`, () =>
      HttpResponse.json(
        {
          type: "https://techlog.local/problems/payload-too-large",
          title: "PAYLOAD_TOO_LARGE",
          status: 413,
          detail: "파일이 너무 큽니다.",
          code: "PAYLOAD_TOO_LARGE",
        },
        { status: 413, headers: { "content-type": "application/problem+json" } },
      ),
    ),
  );

  await assert.rejects(
    transport().upload({ file: svg(), kind: "IMAGE" }, {}),
    (error: unknown) => {
      assert.ok(isStudioGatewayError(error));
      assert.equal(error.code, "PAYLOAD_TOO_LARGE");
      return true;
    },
  );
});

test("maps 415 onto UNSUPPORTED_MEDIA_TYPE", async () => {
  server.use(
    http.post(`${BASE}/api/v1/studio/assets`, () =>
      HttpResponse.json(
        {
          type: "https://techlog.local/problems/unsupported-media-type",
          title: "UNSUPPORTED_MEDIA_TYPE",
          status: 415,
          detail: "지원하지 않는 형식입니다.",
          code: "UNSUPPORTED_MEDIA_TYPE",
        },
        { status: 415, headers: { "content-type": "application/problem+json" } },
      ),
    ),
  );

  await assert.rejects(transport().upload({ file: svg(), kind: "IMAGE" }, {}), (error: unknown) => {
    assert.ok(isStudioGatewayError(error));
    assert.equal(error.code, "UNSUPPORTED_MEDIA_TYPE");
    return true;
  });
});

test("maps a network failure onto STUDIO_UNAVAILABLE", async () => {
  server.use(http.post(`${BASE}/api/v1/studio/assets`, () => HttpResponse.error()));

  await assert.rejects(transport().upload({ file: svg(), kind: "IMAGE" }, {}), (error: unknown) => {
    assert.ok(isStudioGatewayError(error));
    assert.equal(error.code, "STUDIO_UNAVAILABLE");
    return true;
  });
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/asset-upload-transport.test.ts`
Expected: FAIL — 모듈 없음.

- [ ] **Step 3: 전송 구현**

`src/features/tech-log/adapters/http/asset-upload-transport.ts`:

```typescript
import { StudioGatewayError } from "../../application/ports/studio-gateway-error.ts";
import type { UploadAssetForm } from "../../application/ports/studio-asset-gateway.ts";
import type { Asset, ProblemDetails } from "../../contracts/studio/contract.ts";
import type { StudioAssetUploadTransport } from "./http-studio-asset-gateway.ts";
import { STUDIO_ERROR_CODES } from "./studio-error-mapping.ts";

const CODES = new Set<string>(STUDIO_ERROR_CODES);

/**
 * 계약 런타임은 `requestBody: "NONE" | "JSON"`만 표현할 수 있고 저수준 client는
 * 본문을 JSON으로 직렬화한다. canonical `POST /assets`는 multipart이므로 이
 * operation만 좁은 seam으로 분리한다. presigned/resumable로 옮기거나 플랫폼에
 * MULTIPART 모드가 생기면 이 파일만 교체한다.
 */
export function createAssetUploadTransport(
  deps: Readonly<{
    baseUrl: string;
    timeoutMs: number;
    fetch?: typeof globalThis.fetch;
  }>,
): StudioAssetUploadTransport {
  const doFetch = deps.fetch ?? globalThis.fetch.bind(globalThis);
  const endpoint = new URL("api/v1/studio/assets", deps.baseUrl).href;

  function unavailable(detail: string): StudioGatewayError {
    return new StudioGatewayError({
      type: "https://techlog.local/problems/studio-unavailable",
      title: "STUDIO_UNAVAILABLE",
      status: 503,
      detail,
      code: "STUDIO_UNAVAILABLE",
      retryable: true,
    });
  }

  return Object.freeze({
    async upload(form: UploadAssetForm, headers, options) {
      const body = new FormData();
      body.append("file", form.file, form.file.name);
      body.append("kind", form.kind);
      if (form.altText !== undefined) body.append("altText", form.altText);
      if (form.decorative !== undefined) body.append("decorative", String(form.decorative));

      const timeout = AbortSignal.timeout(deps.timeoutMs);
      const signal = options?.signal
        ? AbortSignal.any([options.signal, timeout])
        : timeout;

      let response: Response;
      try {
        // content-type을 직접 넣지 않는다. boundary는 fetch가 만든다.
        response = await doFetch(endpoint, {
          method: "POST",
          headers: { ...headers },
          body,
          signal,
          credentials: "include",
        });
      } catch (error) {
        throw unavailable(
          error instanceof Error ? `Upload transport failed: ${error.message}` : "Upload transport failed.",
        );
      }

      if (response.status === 201 || response.status === 200) {
        return (await response.json()) as Asset;
      }

      let problem: ProblemDetails | null = null;
      try {
        problem = (await response.json()) as ProblemDetails;
      } catch {
        problem = null;
      }
      if (problem && typeof problem.code === "string" && CODES.has(problem.code)) {
        throw new StudioGatewayError(problem);
      }
      throw unavailable(`Upload returned an uncontracted status ${response.status}.`);
    },
  });
}
```

- [ ] **Step 4: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/asset-upload-transport.test.ts`
Expected: 5 tests PASS

- [ ] **Step 5: Asset gateway를 feature input에 배선**

여기까지는 Asset gateway를 만들 수 있을 뿐 UI가 도달할 수 없다. 이제 두 조각이 다 있으므로 배선한다.

`src/features/tech-log/application/tech-log-feature-input.ts`:

```typescript
import type { PublicContentQueries } from "./ports/public-content-queries.ts";
import type { StudioAssetGateway } from "./ports/studio-asset-gateway.ts";
import type { StudioGateway } from "./ports/studio-gateway.ts";

export const TECH_LOG_FEATURE_ID = "tech-log" as const;

export type TechLogFeatureInput = Readonly<{
  publicContent: PublicContentQueries;
  createStudioGateway(): StudioGateway;
  createStudioAssetGateway(): StudioAssetGateway;
}>;
```

CSRF 제공자는 **하나**이고 두 곳이 쓴다: 플랫폼 실행기의 credential seam(JSON operation 18개)과 업로드 전송(multipart 1개). 그러므로 feature input이 아니라 **composition root가 소유**한다. 나눠 가지면 Studio 세션 하나에 토큰이 두 개 생긴다.

`src/bootstrap/runtime-adapters.ts`에서 `contractHttp` 조립 **앞에** 제공자를 만든다. `getStudioSession` 자체는 SAFE operation이라 CSRF가 필요 없으므로 재귀하지 않는다:

```typescript
const techLogCsrf = createCsrfTokenProvider({
  async execute(options) {
    const outcome = await contractOperations.execute(
      "getStudioSession",
      {},
      { routeId: "TECH_LOG_STUDIO", ...(options?.signal ? { signal: options.signal } : {}) },
    );
    if (outcome.kind !== "SUCCESS") throw new Error("studio session is unavailable");
    const value = outcome.value as { csrfToken: string; csrfHeaderName: string };
    return { csrfToken: value.csrfToken, csrfHeaderName: value.csrfHeaderName };
  },
});
```

`contractOperations`가 아직 없는 위치라면 제공자를 지연 생성(`let` + 최초 호출 시 조립)해 순환을 피한다.

같은 파일 `attachCredentials`(`:435`)에 Studio 분기를 더한다. 이것이 `x-csrf-token`이 요청에 실리는 **유일한** 경로다:

```typescript
    async attachCredentials(operation, authContext) {
      if (serverStateScope.getPhase() !== "READY") {
        return Object.freeze({ kind: "SCOPE_FENCED" as const });
      }
      if (operation.authProfileId === "TECH_LOG_STUDIO_SESSION") {
        // Studio는 세션 쿠키로 인증하고 CSRF 토큰만 증명 헤더로 싣는다.
        // 조회 operation은 이 profile을 쓰더라도 헤더 없이 통과해야 하므로
        // 토큰 조회 실패를 세션 상태로 승격하지 않는다.
        try {
          return Object.freeze({
            kind: "READY" as const,
            headers: Object.freeze({
              "x-csrf-token": await techLogCsrf.token({ signal: authContext.signal }),
            }),
          });
        } catch {
          return Object.freeze({ kind: "UNAVAILABLE" as const });
        }
      }
      const state = authSession.getState();
      // ... 기존 bearer 경로는 그대로 둔다
    },
```

`create-tech-log-feature-input.ts`의 `TechLogInstallContext`에 `apiBaseUrl: string`, `requestTimeoutMs: number`, `csrf: CsrfTokenProvider`를 더한다:

```typescript
export function createTechLogFeatureInstalledInput(context: TechLogInstallContext) {
  // MOCK에서도 Asset gateway는 필요하다. 백엔드가 없으면 목록이 비고 업로드는
  // 전송 실패로 끝난다 — UI가 그 상태를 표시하는 것이 정상 동작이다.
  const createStudioAssetGateway = () =>
    createHttpStudioAssetGateway({
      operations: context.contractOperations,
      csrf: context.csrf,
      upload: createAssetUploadTransport({
        baseUrl: context.apiBaseUrl,
        timeoutMs: context.requestTimeoutMs,
      }),
    });

  const createStudioGateway = () =>
    context.studioSource === "MOCK"
      ? createMockStudioGateway()
      : createHttpStudioGateway({ operations: context.contractOperations });

  const input: TechLogFeatureInput = Object.freeze({
    publicContent: publicContentQueries,
    createStudioGateway,
    createStudioAssetGateway,
  });

  return Object.freeze({ featureId: TECH_LOG_FEATURE_ID, input });
}
```

`src/features/installed-feature-adapters.ts`와 `src/bootstrap/runtime-adapters.ts:506`의 호출에 `apiBaseUrl: config.API_BASE_URL`, `requestTimeoutMs: config.REQUEST_TIMEOUT_MS`, `csrf: techLogCsrf`를 더한다.

Studio 세션이 만료돼 `AUTHENTICATION_REQUIRED`가 오면 캐시된 토큰을 버려야 한다. gateway가 아니라 `attachCredentials` 소유자가 버린다 — `authSession.onUnauthenticated()`를 호출하는 `runtime-adapters.ts:499` 부근의 `UNAUTHENTICATED` 분기에서 `techLogCsrf.invalidate()`를 함께 호출한다.

`src/features/tech-log/presentation/studio/studio-provider.tsx`가 `createStudioGateway`를 lazy state/ref로 한 번만 호출하는 방식과 **동일하게** `createStudioAssetGateway`도 한 번만 호출해 제공하도록 확장한다. bfcache `pageshow`로 provider generation이 바뀔 때 두 gateway가 함께 재생성돼야 한다.

- [ ] **Step 6: 합성 테스트 갱신과 green 확인**

`tests/features/tech-log/runtime-composition.test.ts`의 키 단언을 고친다:

```typescript
  assert.deepEqual(Object.keys(installed["tech-log"]).sort(), [
    "createStudioAssetGateway",
    "createStudioGateway",
    "publicContent",
  ]);
```

같은 파일에 공유 검증을 추가한다:

```typescript
test("each Studio session gets its own asset gateway instance", () => {
  const installed = installedInputs("HTTP");
  assert.notEqual(
    installed["tech-log"].createStudioAssetGateway(),
    installed["tech-log"].createStudioAssetGateway(),
  );
});
```

Run: `corepack pnpm check:types:app && corepack pnpm test:tech-log`
Expected: PASS

- [ ] **Step 7: 어댑터 리뷰 문서 작성**

`docs/reviews/adapters/06-tech-log-asset-upload.md`에 다음을 기록한다: 우회 대상(`external-contract-runtime.ts`의 `requestBody` 제약, `client.ts:719`의 JSON 고정), 우회 범위(19개 중 `uploadStudioAsset` 1개), 유지되는 보증(CSRF·Idempotency-Key·오류 코드 매핑·타임아웃·credentials), 포기한 보증(계약 런타임의 byte limit·retry policy·진단 계측), 교체 계획(presigned/resumable 또는 플랫폼 MULTIPART 모드 도입 시 이 파일만 교체). `docs/reviews/adapters/INVENTORY.md`에 항목을 추가한다.

- [ ] **Step 8: 게이트 확인**

Run: `corepack pnpm check:adapter-inventory && corepack pnpm check:architecture && corepack pnpm check:browser-security`
Expected: PASS

- [ ] **Step 9: 커밋**

```bash
git add src/features/tech-log/adapters/http/asset-upload-transport.ts \
  src/features/tech-log/application/tech-log-feature-input.ts \
  src/features/tech-log/adapters/create-tech-log-feature-input.ts \
  src/features/tech-log/presentation/studio/studio-provider.tsx \
  src/features/installed-feature-adapters.ts src/bootstrap/runtime-adapters.ts \
  docs/reviews/adapters/ tests/features/tech-log/
git commit -m "feat: add the TechLog asset multipart upload transport"
```

---

### Task 8: evidence alt 규칙을 publish 검증으로 이동

parser는 Asset의 `decorative`를 모르므로 빈 alt의 필요 여부를 판단할 수 없다. 규칙을 옮긴다. 이는 content format의 **의미 변경**이므로 픽스처를 함께 갱신한다.

**Files:**
- Modify: `src/features/tech-log/domain/content-format/parse-case-content.ts:505`
- Modify: `src/features/tech-log/adapters/mock/validate-working-copy.ts:166`
- Test: `tests/features/tech-log/content-format.test.ts`

**Interfaces:**
- Consumes: 없음
- Produces: parser는 빈 `alt`를 허용한다. `EVIDENCE_FIGURE.alt`는 여전히 `string`이며 빈 문자열이 될 수 있다.

- [ ] **Step 1: 실패하는 테스트 추가**

`tests/features/tech-log/content-format.test.ts`에 추가:

```typescript
test("parses a decorative evidence figure with an empty alt", () => {
  const source = ':::evidence key="fetch-strategy-boundary" alt="" caption="" zoom="false"\n:::\n';
  const parsed = parseCaseContent(source);

  assert.equal(parsed.ok, true);
  if (!parsed.ok) return;
  const block = parsed.value.blocks.find((item) => item.type === "EVIDENCE_FIGURE");
  assert.ok(block);
  assert.equal(block.alt, "");
});

test("round-trips an empty alt without reintroducing it as an error", () => {
  const source = ':::evidence key="fetch-strategy-boundary" alt="" caption="" zoom="false"\n:::\n';
  const parsed = parseCaseContent(source);
  assert.equal(parsed.ok, true);
  if (!parsed.ok) return;
  const reparsed = parseCaseContent(serializeCaseContent(parsed.value));
  assert.equal(reparsed.ok, true);
});

test("still rejects an unsafe evidence key", () => {
  const parsed = parseCaseContent(':::evidence key="../etc" alt="x" caption="" zoom="false"\n:::\n');
  assert.equal(parsed.ok, false);
});
```

기존 테스트 중 "빈 alt가 파싱 오류"를 단언하는 케이스가 있으면 위 의미로 고친다. 삭제하지 말고 반대 단언으로 바꾼다.

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/content-format.test.ts`
Expected: FAIL — parser가 빈 alt를 거절한다.

- [ ] **Step 3: parser 규칙 제거**

`src/features/tech-log/domain/content-format/parse-case-content.ts:505`의 한 줄을 지우고 주석으로 대체한다:

```typescript
      // alt 필요 여부는 Asset의 `decorative`에 달려 있어 여기서는 판단할 수
      // 없다. 빈 alt는 구문 오류가 아니며 publish 검증이 Asset metadata와 함께
      // 판정한다(설계 §7.7).
```

- [ ] **Step 4: publish 검증에 규칙 추가**

`src/features/tech-log/adapters/mock/validate-working-copy.ts:166` 부근의 evidence 검사에 alt 규칙을 더한다. mock은 Asset metadata를 모르므로 정적 레지스트리를 `decorative: false`로 간주한다:

```typescript
        if (!isSupportedEvidenceKey(block.key)) {
          error("EVIDENCE_UNSUPPORTED", "/bodyMarkdown", `지원하지 않는 Evidence: ${block.key}`);
        } else if (block.alt.trim().length === 0) {
          // 정적 evidence 자산은 장식용이 아니다. Asset 기반 경로에서는 서버가
          // Asset.decorative로 같은 판정을 한다.
          error("EVIDENCE_ALT_REQUIRED", "/bodyMarkdown", `Evidence에 대체 텍스트가 필요합니다: ${block.key}`);
        }
```

- [ ] **Step 5: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/content-format.test.ts && corepack pnpm test:tech-log`
Expected: PASS

- [ ] **Step 6: 커밋**

```bash
git add src/features/tech-log/domain/content-format/parse-case-content.ts \
  src/features/tech-log/adapters/mock/validate-working-copy.ts \
  tests/features/tech-log/content-format.test.ts
git commit -m "fix: judge evidence alt text with asset metadata, not syntax"
```

---

### Task 9: Asset 기반 evidence resolver

렌더러에는 이미 `resolveEvidenceAsset: ResolveEvidenceAsset` 주입점이 6개 지점에 있다(`domain/public-render-content.ts:9`). 새로 만들 것은 렌더러 구조가 아니라 **Backend Asset을 해석하는 resolver 구현**이다. 이 Task 없이 Task 10을 하면 사용자가 삽입한 backend `assetKey`를 `getEvidenceAsset`이 `throw`해 즉시 미리보기가 깨진다.

canonical `EvidenceFigureBlock`은 `ResolvedAsset`(`assetId`, `assetKey`, `mediaType`, `publicPath`, `width`, `height`, `decorative`)을 블록 안에 담아 보낸다. 따라서 서버가 만든 세 표면(Public Preview·Snapshot·Published)은 블록에서 바로 해석하고, **Instant Preview만** 클라이언트가 적재한 Asset 목록으로 해석한다.

**Files:**
- Create: `src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts`
- Modify: `src/features/tech-log/presentation/studio/components/instant-preview.tsx:49`
- Modify: `src/features/tech-log/presentation/studio/components/public-preview-screen.tsx:290`
- Modify: `src/features/tech-log/presentation/studio/components/publication-event-preview-screen.tsx:169`
- Test: `tests/features/tech-log/evidence-asset-resolver.test.tsx`

**Interfaces:**
- Consumes: `Asset`(Task 6), `ResolveEvidenceAsset`/`EvidenceAsset`(`domain/public-render-content.ts`)
- Produces:
  - `createAssetCatalogResolver(assets: readonly Asset[]): ResolveEvidenceAsset` — Instant Preview용. 정적 레지스트리로 폴백한다.
  - `createResolvedAssetResolver(blocks: readonly { type: string; key?: string; asset?: ResolvedAssetLike }[]): ResolveEvidenceAsset` — 서버 render model용.
  - `MISSING_EVIDENCE_ASSET: EvidenceAsset` — 해석 실패 시의 안전한 자리표시자.

- [ ] **Step 1: 실패하는 테스트 작성**

`tests/features/tech-log/evidence-asset-resolver.test.tsx`:

```typescript
import assert from "node:assert/strict";
import { test } from "vitest";

import {
  createAssetCatalogResolver,
  createResolvedAssetResolver,
  MISSING_EVIDENCE_ASSET,
} from "../../../src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts";

const READY = {
  id: "11111111-1111-4111-8111-111111111111",
  assetKey: "boundary",
  kind: "DIAGRAM",
  mediaType: "image/svg+xml",
  originalFilename: "b.svg",
  byteSize: 10,
  width: 1080,
  height: 420,
  altText: "경계",
  decorative: false,
  managementStatus: "READY",
  publicPath: "/media/boundary.svg",
  usageCount: 0,
  version: 1,
  createdAt: "2026-08-14T01:00:00.000Z",
  updatedAt: "2026-08-14T01:00:00.000Z",
} as never;

test("resolves a backend asset key to its public path", () => {
  const resolve = createAssetCatalogResolver([READY]);
  const asset = resolve("boundary");

  assert.equal(asset.src, "/media/boundary.svg");
  assert.equal(asset.width, 1080);
  assert.equal(asset.height, 420);
});

test("falls back to the static registry for the legacy hardcoded key", () => {
  const resolve = createAssetCatalogResolver([]);
  const asset = resolve("fetch-strategy-boundary");

  assert.equal(asset.src, "/media/fetch-strategy-boundary.svg");
});

test("returns the placeholder instead of throwing on an unknown key", () => {
  const resolve = createAssetCatalogResolver([]);
  assert.deepEqual(resolve("does-not-exist"), MISSING_EVIDENCE_ASSET);
});

test("never resolves a QUARANTINED asset", () => {
  const resolve = createAssetCatalogResolver([
    { ...(READY as object), managementStatus: "QUARANTINED" } as never,
  ]);
  assert.deepEqual(resolve("boundary"), MISSING_EVIDENCE_ASSET);
});

test("resolves from the server render model blocks", () => {
  const resolve = createResolvedAssetResolver([
    {
      type: "EVIDENCE_FIGURE",
      key: "boundary",
      asset: {
        assetId: "11111111-1111-4111-8111-111111111111",
        assetKey: "boundary",
        mediaType: "image/svg+xml",
        publicPath: "/media/boundary.svg",
        width: 800,
        height: 300,
        decorative: false,
      },
    },
  ]);

  assert.equal(resolve("boundary").src, "/media/boundary.svg");
  assert.equal(resolve("boundary").width, 800);
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/evidence-asset-resolver.test.tsx`
Expected: FAIL — 모듈 없음.

- [ ] **Step 3: resolver 구현**

`src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts`:

```typescript
import {
  getEvidenceAsset,
  isSupportedEvidenceKey,
} from "../../../adapters/static/evidence-assets.ts";
import type { Asset } from "../../../contracts/studio/contract.ts";
import type {
  EvidenceAsset,
  ResolveEvidenceAsset,
} from "../../../domain/public-render-content.ts";

export type ResolvedAssetLike = Readonly<{
  assetKey: string;
  mediaType: string;
  publicPath: string;
  width: number | null;
  height: number | null;
  decorative: boolean;
}>;

/**
 * `ResolveEvidenceAsset`은 total 함수다. 해석 실패에 throw하면 편집 중인 문서
 * 하나가 화면 전체를 무너뜨리므로 자리표시자를 돌려준다. 게시 차단은 publish
 * 검증이 담당한다.
 */
export const MISSING_EVIDENCE_ASSET: EvidenceAsset = Object.freeze({
  src: "",
  width: 1,
  height: 1,
  triggerLabel: "사용할 수 없는 Evidence",
  dialogLabel: "사용할 수 없는 Evidence",
});

function fromDescriptor(descriptor: ResolvedAssetLike): EvidenceAsset {
  const label = `${descriptor.assetKey} 이미지 크게 보기`;
  return Object.freeze({
    src: descriptor.publicPath,
    width: descriptor.width ?? 1,
    height: descriptor.height ?? 1,
    triggerLabel: label,
    dialogLabel: `${descriptor.assetKey} 확대`,
  });
}

function staticFallback(key: string): EvidenceAsset {
  return isSupportedEvidenceKey(key) ? getEvidenceAsset(key) : MISSING_EVIDENCE_ASSET;
}

/** Instant Preview: 편집기가 적재한 Asset 목록으로 해석한다. */
export function createAssetCatalogResolver(
  assets: readonly Asset[],
): ResolveEvidenceAsset {
  const byKey = new Map<string, Asset>();
  for (const asset of assets) {
    // QUARANTINED/REJECTED는 어떤 표면에도 렌더링하지 않는다.
    if (asset.managementStatus !== "READY") continue;
    byKey.set(asset.assetKey, asset);
  }

  return (key: string) => {
    const asset = byKey.get(key);
    if (!asset || asset.publicPath === null) return staticFallback(key);
    return fromDescriptor({
      assetKey: asset.assetKey,
      mediaType: asset.mediaType,
      publicPath: asset.publicPath,
      width: asset.width,
      height: asset.height,
      decorative: asset.decorative,
    });
  };
}

/** Public Preview·Snapshot·Published: 서버가 블록에 실어 보낸 descriptor를 쓴다. */
export function createResolvedAssetResolver(
  blocks: readonly Readonly<{ type: string; key?: string; asset?: ResolvedAssetLike }>[],
): ResolveEvidenceAsset {
  const byKey = new Map<string, ResolvedAssetLike>();
  for (const block of blocks) {
    if (block.type !== "EVIDENCE_FIGURE" || !block.asset) continue;
    byKey.set(block.asset.assetKey, block.asset);
  }

  return (key: string) => {
    const descriptor = byKey.get(key);
    return descriptor ? fromDescriptor(descriptor) : staticFallback(key);
  };
}
```

- [ ] **Step 4: 주입 지점 교체**

`public-preview-screen.tsx:290`과 `publication-event-preview-screen.tsx:169`의 resolver를 `createResolvedAssetResolver(renderModel.bodyBlocks)`로 바꾼다. `renderModel`에 `bodyBlocks`가 없는 kind(REFERENCE/QUESTION/PROJECT_DECISION)는 빈 배열을 넘긴다.

`instant-preview.tsx:49`는 `createAssetCatalogResolver(assets)`를 쓴다. `assets`는 Task 10에서 Asset Picker가 적재하는 목록과 같은 출처여야 하므로, Studio provider가 보유한 Asset 목록 상태를 props로 받는다. Task 10 이전에는 빈 배열을 넘겨도 정적 폴백으로 기존 동작이 유지된다.

기존 `resolvePreviewEvidenceAsset`, `resolvePublicEvidenceAsset`, `missingQuestionEvidence`, `missingReferenceEvidence`는 그대로 둔다. Public 화면(`case-document-page.tsx` 등)은 이 사이클에서 정적 경로를 유지한다.

- [ ] **Step 5: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/evidence-asset-resolver.test.tsx && corepack pnpm test:tech-log`
Expected: PASS. 기존 preview·snapshot 화면 테스트가 그대로 통과해야 한다 — 정적 키는 폴백으로 같은 결과를 낸다.

- [ ] **Step 6: 커밋**

```bash
git add src/features/tech-log/presentation/shared/public-render/asset-resolvers.ts \
  src/features/tech-log/presentation/studio/components/ \
  tests/features/tech-log/evidence-asset-resolver.test.tsx
git commit -m "feat: resolve evidence figures from backend asset descriptors"
```

---

### Task 10: Asset Picker와 evidence directive 삽입

편집 흐름의 기본 진입점이다. Studio primary navigation은 변경하지 않는다.

**Files:**
- Create: `src/features/tech-log/presentation/studio/components/asset-picker.tsx`
- Create: `src/features/tech-log/presentation/studio/components/asset-upload-dialog.tsx`
- Modify: `src/features/tech-log/presentation/studio/components/case-fields.tsx`
- Test: `tests/features/tech-log/asset-picker.test.tsx`

**Interfaces:**
- Consumes: `StudioAssetGateway`(Task 6)
- Produces:
  - `buildEvidenceDirective(input: Readonly<{ assetKey: string; alt: string; caption: string; zoom: boolean }>): string`
  - `<AssetPicker gateway={...} onInsert={(directive: string) => void} />`
  - `<AssetUploadDialog gateway={...} onUploaded={(asset: Asset) => void} onClose={() => void} />`

- [ ] **Step 1: 실패하는 테스트 작성**

`tests/features/tech-log/asset-picker.test.tsx`:

```tsx
import assert from "node:assert/strict";
import { test } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

import {
  AssetPicker,
  buildEvidenceDirective,
} from "../../../src/features/tech-log/presentation/studio/components/asset-picker.tsx";
import type { StudioAssetGateway } from "../../../src/features/tech-log/application/ports/studio-asset-gateway.ts";

const READY = {
  id: "11111111-1111-4111-8111-111111111111",
  assetKey: "fetch-strategy-boundary",
  kind: "DIAGRAM",
  mediaType: "image/svg+xml",
  originalFilename: "boundary.svg",
  byteSize: 4096,
  width: 1080,
  height: 420,
  altText: "Fetch Join 경계",
  decorative: false,
  managementStatus: "READY",
  publicPath: "/media/fetch-strategy-boundary.svg",
  usageCount: 1,
  version: 1,
  createdAt: "2026-08-14T01:00:00.000Z",
  updatedAt: "2026-08-14T01:00:00.000Z",
};

const QUARANTINED = { ...READY, id: "22222222-2222-4222-8222-222222222222", assetKey: "unsafe", managementStatus: "QUARANTINED" };

function gatewayOf(items: unknown[]): StudioAssetGateway {
  return {
    async listAssets() {
      return { items, nextCursor: null } as never;
    },
    async uploadAsset() {
      throw new Error("not used");
    },
    async getAsset() {
      throw new Error("not used");
    },
    async updateAssetMetadata() {
      throw new Error("not used");
    },
    async deleteAsset() {},
  };
}

test("builds the evidence directive with escaped attribute values", () => {
  assert.equal(
    buildEvidenceDirective({
      assetKey: "fetch-strategy-boundary",
      alt: "Fetch Join 경계",
      caption: "그림 1",
      zoom: true,
    }),
    ':::evidence key="fetch-strategy-boundary" alt="Fetch Join 경계" caption="그림 1" zoom="true"\n:::',
  );
});

test("inserts the directive for the chosen asset", async () => {
  const user = userEvent.setup();
  const inserted: string[] = [];
  render(<AssetPicker gateway={gatewayOf([READY])} onInsert={(value) => inserted.push(value)} />);

  await user.click(await screen.findByRole("button", { name: /fetch-strategy-boundary/ }));

  assert.equal(inserted.length, 1);
  assert.ok(inserted[0]!.includes('key="fetch-strategy-boundary"'));
  assert.ok(inserted[0]!.startsWith(":::evidence "));
});

test("does not offer a QUARANTINED asset for insertion", async () => {
  render(<AssetPicker gateway={gatewayOf([READY, QUARANTINED])} onInsert={() => {}} />);

  await screen.findByRole("button", { name: /fetch-strategy-boundary/ });
  assert.equal(screen.queryByRole("button", { name: /unsafe/ }), null);
});
```

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/asset-picker.test.tsx`
Expected: FAIL — 컴포넌트 없음.

- [ ] **Step 3: directive 빌더와 picker 구현**

`asset-picker.tsx`. directive 속성값은 `"`를 포함할 수 없다 — 파서가 속성을 따옴표로 구분하기 때문이다. 값에서 `"`를 제거하고 개행을 공백으로 접는다.

```tsx
import { useEffect, useState } from "react";

import type { Asset } from "../../../contracts/studio/contract.ts";
import type { StudioAssetGateway } from "../../../application/ports/studio-asset-gateway.ts";

function attributeValue(raw: string): string {
  return raw.replaceAll('"', "").replace(/\s+/gu, " ").trim();
}

export function buildEvidenceDirective(
  input: Readonly<{ assetKey: string; alt: string; caption: string; zoom: boolean }>,
): string {
  const key = attributeValue(input.assetKey);
  const alt = attributeValue(input.alt);
  const caption = attributeValue(input.caption);
  return `:::evidence key="${key}" alt="${alt}" caption="${caption}" zoom="${input.zoom}"\n:::`;
}

export function AssetPicker(props: Readonly<{
  gateway: StudioAssetGateway;
  onInsert: (directive: string) => void;
}>) {
  const [assets, setAssets] = useState<readonly Asset[]>([]);
  const [failed, setFailed] = useState(false);

  useEffect(() => {
    const controller = new AbortController();
    props.gateway
      .listAssets({ managementStatus: "READY", limit: 50 }, { signal: controller.signal })
      .then((page) => setAssets(page.items))
      .catch(() => setFailed(true));
    return () => controller.abort();
  }, [props.gateway]);

  // READY만 삽입 후보다. 서버 필터를 신뢰하되 방어적으로 한 번 더 거른다.
  const selectable = assets.filter((asset) => asset.managementStatus === "READY");

  if (failed) return <p className="studio-error">Asset 목록을 불러오지 못했습니다.</p>;

  return <div className="asset-picker">
    <ul>
      {selectable.map((asset) => <li key={asset.id}>
        <button
          type="button"
          onClick={() => props.onInsert(buildEvidenceDirective({
            assetKey: asset.assetKey,
            alt: asset.decorative ? "" : (asset.altText ?? ""),
            caption: "",
            zoom: asset.kind === "DIAGRAM",
          }))}
        >
          {asset.assetKey}
        </button>
      </li>)}
    </ul>
  </div>;
}
```

- [ ] **Step 4: 업로드 상태 기계 구현**

업로드 상태는 설계 §7.8이 요구하는 8가지를 구분한다. 상태 판정은 순수 함수로 분리해 dialog와 독립적으로 테스트한다.

`asset-upload-dialog.tsx`:

```tsx
import { useRef, useState } from "react";

import type { Asset, AssetKind } from "../../../contracts/studio/contract.ts";
import type { StudioAssetGateway } from "../../../application/ports/studio-asset-gateway.ts";
import { isStudioGatewayError } from "../../../application/ports/studio-gateway-error.ts";

export type UploadState =
  | { kind: "IDLE" }
  | { kind: "SELECTION_FAILED"; message: string }
  | { kind: "UPLOADING" }
  | { kind: "TRANSPORT_FAILED"; message: string }
  | { kind: "TOO_LARGE" }
  | { kind: "UNSUPPORTED_TYPE" }
  | { kind: "READY"; asset: Asset }
  | { kind: "REJECTED"; asset: Asset }
  | { kind: "QUARANTINED"; asset: Asset };

/** 업로드 전송 성공과 서버 검증 성공은 다르다. 성공 응답도 상태로 나눈다. */
export function stateForUploaded(asset: Asset): UploadState {
  switch (asset.managementStatus) {
    case "READY":
      return { kind: "READY", asset };
    case "QUARANTINED":
      return { kind: "QUARANTINED", asset };
    case "REJECTED":
    case "ARCHIVED":
      return { kind: "REJECTED", asset };
  }
}

export function stateForError(error: unknown): UploadState {
  if (isStudioGatewayError(error)) {
    if (error.code === "PAYLOAD_TOO_LARGE") return { kind: "TOO_LARGE" };
    if (error.code === "UNSUPPORTED_MEDIA_TYPE") return { kind: "UNSUPPORTED_TYPE" };
    return { kind: "TRANSPORT_FAILED", message: error.problem.detail };
  }
  return { kind: "TRANSPORT_FAILED", message: "업로드를 전송하지 못했습니다." };
}

const MESSAGES: Record<UploadState["kind"], string> = {
  IDLE: "",
  SELECTION_FAILED: "파일을 선택하지 못했습니다.",
  UPLOADING: "업로드 중입니다.",
  TRANSPORT_FAILED: "업로드를 전송하지 못했습니다.",
  TOO_LARGE: "파일 크기가 허용 범위를 넘었습니다.",
  UNSUPPORTED_TYPE: "지원하지 않는 파일 형식입니다.",
  READY: "업로드했습니다.",
  REJECTED: "서버 검증에서 거절되어 사용할 수 없습니다.",
  QUARANTINED: "보안 검사에서 격리되어 사용할 수 없습니다.",
};

export function AssetUploadDialog(props: Readonly<{
  gateway: StudioAssetGateway;
  kind: AssetKind;
  idempotencyKey: string;
  onUploaded: (asset: Asset) => void;
  onClose: () => void;
}>) {
  const [state, setState] = useState<UploadState>({ kind: "IDLE" });
  const inputRef = useRef<HTMLInputElement>(null);

  async function submit(file: File) {
    setState({ kind: "UPLOADING" });
    try {
      const asset = await props.gateway.uploadAsset(
        { file, kind: props.kind },
        { idempotencyKey: props.idempotencyKey },
      );
      const next = stateForUploaded(asset);
      setState(next);
      if (next.kind === "READY") props.onUploaded(asset);
    } catch (error) {
      setState(stateForError(error));
    }
  }

  return <div className="asset-upload-dialog">
    <input
      ref={inputRef}
      type="file"
      accept="image/png,image/jpeg,image/webp,image/gif,image/svg+xml,application/pdf"
      disabled={state.kind === "UPLOADING"}
      onChange={(event) => {
        const file = event.currentTarget.files?.[0];
        if (!file) {
          setState({ kind: "SELECTION_FAILED", message: MESSAGES.SELECTION_FAILED });
          return;
        }
        void submit(file);
      }}
    />
    <p role="status" aria-live="polite">{MESSAGES[state.kind]}</p>
    <button type="button" onClick={props.onClose}>닫기</button>
  </div>;
}
```

`unpublish-dialog.tsx`의 focus trap·복귀 패턴과 클래스 구성을 그대로 따라 dialog 껍데기를 맞춘다.

- [ ] **Step 5: 편집기에 연결**

`case-fields.tsx`의 `bodyMarkdown` textarea 옆에 Picker 진입 버튼을 둔다. 삽입은 커서 위치를 보존한다:

```tsx
function insertAtCursor(
  textarea: HTMLTextAreaElement,
  directive: string,
  commit: (next: string) => void,
) {
  const { selectionStart, selectionEnd, value } = textarea;
  const prefix = value.slice(0, selectionStart);
  const suffix = value.slice(selectionEnd);
  // directive는 블록이므로 앞뒤 빈 줄을 보장한다.
  const before = prefix.length === 0 || prefix.endsWith("\n\n") ? prefix : `${prefix}\n\n`;
  const after = suffix.startsWith("\n") ? suffix : `\n${suffix}`;
  commit(`${before}${directive}${after}`);
}
```

다른 필드와 레이아웃 구조는 바꾸지 않는다. Picker와 Upload dialog는 `bodyMarkdown`을 가진 CASE 편집기에만 붙인다.

**적재한 Asset 목록을 즉시 미리보기에 넘긴다.** Task 9가 `instant-preview.tsx`에 `assets` prop을 열어뒀지만 아직 빈 배열이 들어간다. 이 단계에서 실제로 연결하지 않으면 방금 삽입한 directive가 즉시 미리보기에서 자리표시자로 보인다.

Picker가 적재한 목록을 편집기 화면(`document-editor-screen.tsx`)이 소유하게 하고, Picker와 InstantPreview 양쪽에 같은 배열을 내려준다. Picker가 아직 목록을 못 받았거나 업로드 직후라면 새 Asset을 배열에 더한다:

```tsx
const [assets, setAssets] = useState<readonly Asset[]>([]);
// Picker의 목록 적재 결과와 업로드 성공 결과가 같은 배열로 모인다.
<AssetPicker gateway={assetGateway} onLoaded={setAssets} onInsert={insert} />
<AssetUploadDialog
  gateway={assetGateway}
  onUploaded={(asset) => setAssets((current) => [asset, ...current])}
  …
/>
<InstantPreview assets={assets} … />
```

`AssetPicker`에 `onLoaded?: (assets: readonly Asset[]) => void` prop을 더하고 `listAssets` 성공 시 호출한다. Task 10 Step 1의 기존 테스트는 이 prop 없이도 통과해야 하므로 선택 prop으로 둔다.

- [ ] **Step 6: green 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/asset-picker.test.tsx && corepack pnpm test:tech-log`
Expected: PASS

- [ ] **Step 7: 커밋**

```bash
git add src/features/tech-log/presentation/studio/components/ \
  tests/features/tech-log/asset-picker.test.tsx
git commit -m "feat: insert evidence directives from the TechLog asset picker"
```

---

### Task 11: Asset Library 화면과 라우트

**Files:**
- Create: `src/features/tech-log/presentation/studio/pages/assets-page.tsx`
- Create: `src/features/tech-log/presentation/studio/components/asset-library.tsx`
- Modify: `src/features/tech-log/contracts/tech-log-route-contract.ts`
- Modify: `src/features/tech-log/presentation/tech-log-route-runtime.tsx`
- Test: `tests/features/tech-log/route-contract.test.ts`, `tests/features/tech-log/asset-library.test.tsx`

**Interfaces:**
- Consumes: `StudioAssetGateway`(Task 6)
- Produces: 라우트 `TECH_LOG_STUDIO_ASSETS` — `path: "/studio/assets"`, `layoutGroup: "STUDIO"`, `paramsSchema: null`, `searchSchema: null`, `title: "Asset"`, `navigationLabel: null`, `navigationOrder: null`

`navigationLabel`을 `null`로 두는 것이 핵심이다. Asset은 secondary utility이며 primary navigation(`작업본 · 게시 기록 · 새 문서`)을 CMS 구조로 바꾸지 않는다.

- [ ] **Step 1: 라우트 테스트 갱신**

`tests/features/tech-log/route-contract.test.ts`에서 기대 라우트 수를 27에서 28로 올리고 새 항목을 단언한다:

```typescript
test("registers the studio asset library outside primary navigation", () => {
  const route = TECH_LOG_ROUTE_DEFINITIONS.find(
    (item) => item.routeId === "TECH_LOG_STUDIO_ASSETS",
  );

  assert.ok(route);
  assert.equal(route.path, "/studio/assets");
  assert.equal(route.layoutGroup, "STUDIO");
  assert.equal(route.navigationLabel, null);
  assert.equal(route.navigationOrder, null);
});
```

기존 "정확히 27개" 단언이 있으면 28로 고친다. `/studio/*` catch-all보다 앞에 선언돼야 한다.

- [ ] **Step 2: red 확인**

Run: `corepack pnpm exec vitest run tests/features/tech-log/route-contract.test.ts`
Expected: FAIL

- [ ] **Step 3: 라우트 추가**

`tech-log-route-contract.ts`의 `TECH_LOG_ROUTE_SPECS`에서 `TECH_LOG_STUDIO_PUBLICATION_PREVIEW` 뒤, `TECH_LOG_STUDIO_NOT_FOUND` 앞에 추가한다:

```typescript
  defineSpec({ routeId: "TECH_LOG_STUDIO_ASSETS", path: "/studio/assets", layoutGroup: "STUDIO", paramsSchema: null, searchSchema: null, title: "Asset", navigationLabel: null, navigationOrder: null }),
```

`tech-log-route-runtime.tsx`에 `TECH_LOG_STUDIO_ASSETS → <AssetsPage />` 매핑을 더한다.

- [ ] **Step 4: 화면 구현**

삭제 가능 여부 판정을 순수 함수로 분리한다 — 이것이 이 화면의 유일한 규칙이다.

`asset-library.tsx`:

```tsx
import { useEffect, useState } from "react";

import type { Asset, AssetDetail } from "../../../contracts/studio/contract.ts";
import type { StudioAssetGateway } from "../../../application/ports/studio-asset-gateway.ts";
import { isStudioGatewayError } from "../../../application/ports/studio-gateway-error.ts";

/**
 * 공개 이력이 있거나 사용 중인 Asset은 hard delete하지 않는다. 서버도 같은
 * 규칙으로 `ASSET_IN_USE`를 던지므로 화면은 시도 자체를 막아 왕복을 줄인다.
 */
export function canHardDelete(detail: AssetDetail): boolean {
  return !detail.hasPublicationHistory && detail.usages.length === 0 &&
    detail.asset.usageCount === 0;
}

export function AssetLibrary(props: Readonly<{ gateway: StudioAssetGateway }>) {
  const [assets, setAssets] = useState<readonly Asset[]>([]);
  const [selected, setSelected] = useState<AssetDetail | null>(null);
  const [notice, setNotice] = useState("");

  useEffect(() => {
    const controller = new AbortController();
    props.gateway
      .listAssets({ limit: 50 }, { signal: controller.signal })
      .then((page) => setAssets(page.items))
      .catch(() => setNotice("Asset 목록을 불러오지 못했습니다."));
    return () => controller.abort();
  }, [props.gateway]);

  async function archive(detail: AssetDetail) {
    try {
      await props.gateway.updateAssetMetadata(
        detail.asset.id,
        { expectedVersion: detail.asset.version, managementStatus: "ARCHIVED" },
        { idempotencyKey: `archive-${detail.asset.id}-${detail.asset.version}` },
      );
      setNotice("보관했습니다.");
    } catch (error) {
      setNotice(isStudioGatewayError(error) ? error.problem.detail : "보관하지 못했습니다.");
    }
  }

  async function remove(detail: AssetDetail) {
    try {
      await props.gateway.deleteAsset(detail.asset.id, {
        idempotencyKey: `delete-${detail.asset.id}-${detail.asset.version}`,
      });
      setAssets((current) => current.filter((item) => item.id !== detail.asset.id));
      setNotice("삭제했습니다.");
    } catch (error) {
      setNotice(isStudioGatewayError(error) ? error.problem.detail : "삭제하지 못했습니다.");
    }
  }

  return <section className="asset-library">
    <p role="status" aria-live="polite">{notice}</p>
    <ul>
      {assets.map((asset) => <li key={asset.id}>
        <button
          type="button"
          onClick={() => {
            void props.gateway.getAsset(asset.id).then(setSelected).catch(() => {
              setNotice("Asset 상세를 불러오지 못했습니다.");
            });
          }}
        >
          {asset.assetKey}
        </button>
        <span>{asset.managementStatus}</span>
        <span>사용 {asset.usageCount}건</span>
      </li>)}
    </ul>
    {selected ? <div className="asset-detail">
      <h2>{selected.asset.assetKey}</h2>
      <ul>
        {selected.usages.map((usage) => <li key={usage.documentId}>{usage.title}</li>)}
      </ul>
      {canHardDelete(selected)
        ? <button type="button" onClick={() => void remove(selected)}>삭제</button>
        : <button type="button" onClick={() => void archive(selected)}>보관</button>}
    </div> : null}
  </section>;
}
```

`assets-page.tsx`는 Studio shell 안에서 `AssetLibrary`에 `createStudioAssetGateway()` 결과를 넘겨 렌더링한다. gateway는 Studio provider가 보유한 인스턴스를 쓰고 화면에서 새로 만들지 않는다.

- [ ] **Step 5: 화면 테스트 작성과 green 확인**

`tests/features/tech-log/asset-library.test.tsx`:

```tsx
import assert from "node:assert/strict";
import { test } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";

import {
  AssetLibrary,
  canHardDelete,
} from "../../../src/features/tech-log/presentation/studio/components/asset-library.tsx";
import { StudioGatewayError } from "../../../src/features/tech-log/application/ports/studio-gateway-error.ts";

const ASSET = {
  id: "11111111-1111-4111-8111-111111111111",
  assetKey: "boundary",
  kind: "DIAGRAM",
  mediaType: "image/svg+xml",
  originalFilename: "b.svg",
  byteSize: 10,
  width: 1080,
  height: 420,
  altText: "경계",
  decorative: false,
  managementStatus: "READY",
  publicPath: "/media/boundary.svg",
  usageCount: 0,
  version: 1,
  createdAt: "2026-08-14T01:00:00.000Z",
  updatedAt: "2026-08-14T01:00:00.000Z",
} as never;

function gatewayOf(detail: unknown, onDelete?: () => never) {
  return {
    async listAssets() {
      return { items: [ASSET], nextCursor: null } as never;
    },
    async getAsset() {
      return detail as never;
    },
    async uploadAsset() {
      throw new Error("not used");
    },
    async updateAssetMetadata() {
      return ASSET;
    },
    async deleteAsset() {
      if (onDelete) onDelete();
    },
  } as never;
}

test("offers hard delete only for an unused asset with no publication history", () => {
  assert.equal(
    canHardDelete({ asset: ASSET, usages: [], hasPublicationHistory: false } as never),
    true,
  );
  assert.equal(
    canHardDelete({ asset: ASSET, usages: [], hasPublicationHistory: true } as never),
    false,
  );
  assert.equal(
    canHardDelete({
      asset: ASSET,
      usages: [{ documentId: "d", documentKind: "CASE", title: "문서", published: true }],
      hasPublicationHistory: false,
    } as never),
    false,
  );
});

test("shows archive instead of delete for an asset in use", async () => {
  const user = userEvent.setup();
  render(<AssetLibrary gateway={gatewayOf({
    asset: { ...(ASSET as object), usageCount: 1 },
    usages: [{ documentId: "d", documentKind: "CASE", title: "사용 중 문서", published: true }],
    hasPublicationHistory: true,
  })} />);

  await user.click(await screen.findByRole("button", { name: "boundary" }));

  assert.ok(await screen.findByRole("button", { name: "보관" }));
  assert.equal(screen.queryByRole("button", { name: "삭제" }), null);
});

test("surfaces ASSET_IN_USE when the server rejects a delete", async () => {
  const user = userEvent.setup();
  render(<AssetLibrary gateway={gatewayOf(
    { asset: ASSET, usages: [], hasPublicationHistory: false },
    () => {
      throw new StudioGatewayError({
        type: "https://techlog.local/problems/asset-in-use",
        title: "ASSET_IN_USE",
        status: 409,
        detail: "사용 중인 Asset은 삭제할 수 없습니다.",
        code: "ASSET_IN_USE",
      });
    },
  )} />);

  await user.click(await screen.findByRole("button", { name: "boundary" }));
  await user.click(await screen.findByRole("button", { name: "삭제" }));

  assert.ok(await screen.findByText("사용 중인 Asset은 삭제할 수 없습니다."));
});
```

Run: `corepack pnpm exec vitest run tests/features/tech-log/route-contract.test.ts tests/features/tech-log/asset-library.test.tsx`
Expected: PASS

- [ ] **Step 6: 라우트 거버넌스 기준선 갱신**

Run: `corepack pnpm check:registries:structure && corepack pnpm check:registries`
기준선 불일치가 나오면 라우트 추가에 맞춰 승인된 기준선을 갱신하고 다시 실행한다.

- [ ] **Step 7: 커밋**

```bash
git add src/features/tech-log/presentation/ src/features/tech-log/contracts/tech-log-route-contract.ts \
  tests/features/tech-log/ config/
git commit -m "feat: add the TechLog Studio asset library route and screen"
```

---

### Task 12: 전체 게이트와 정합 증거

**Files:**
- Modify: `docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md` (완료 상태 기록)
- Modify: `README.md` (스위치 사용법)
- Test: 전체 스위트

- [ ] **Step 1: 계약 parity 최종 확인**

Run: `corepack pnpm check:tech-log-contract`
Expected: `tech-log contract is in sync with the canonical source.`

- [ ] **Step 2: 전체 테스트**

Run: `corepack pnpm test:all && corepack pnpm test:coverage`
Expected: PASS. 실패한 항목이 있으면 그 Task로 돌아가 고친다. 통과 여부를 추정하지 않는다.

- [ ] **Step 3: 정적 게이트**

Run:

```bash
corepack pnpm lint && corepack pnpm check:types && corepack pnpm check:architecture \
  && corepack pnpm check:design-system && corepack pnpm check:i18n \
  && corepack pnpm check:adapter-inventory && corepack pnpm check:registries \
  && corepack pnpm scan:security && corepack pnpm check:browser-security
```

Expected: 전부 PASS

- [ ] **Step 4: Studio 흐름과 렌더러 불변 회귀 확인**

Run: `corepack pnpm test:e2e -- --grep "tech-log-studio"`
Expected: PASS. 기본 스위치가 `MOCK`이므로 기존 Studio 워크플로가 변경 없이 통과해야 한다.

렌더러 불변(설계 §9)을 확인한다. 같은 문서에 대해 `Instant Preview`, `Public Preview`, `Published Public`, `Publication Snapshot` 네 화면이 같은 semantic output을 내야 한다. 네 화면 모두 같은 `case-body-renderer.tsx`를 쓰고 Task 9가 resolver를 통일했으므로, 기존 preview·snapshot·public 화면 테스트가 전부 통과하면 성립한다. 실패하는 화면이 있으면 resolver 주입 지점이 어긋난 것이므로 Task 9로 돌아간다.

Run: `corepack pnpm exec vitest run tests/features/tech-log/studio-validation-preview.test.tsx tests/features/tech-log/studio-publication-flow.test.tsx tests/features/tech-log/public-document-screens.test.tsx`
Expected: PASS

- [ ] **Step 5: HTTP 스위치 수동 확인**

`config/runtime/local.json`의 `TECH_LOG_STUDIO_SOURCE`를 임시로 `HTTP`로 바꾸고 `corepack pnpm dev`를 띄운다. `/studio`가 백엔드 부재로 오류 상태를 표시하되 화이트스크린이나 처리되지 않은 예외가 없어야 한다. 확인 후 `MOCK`으로 되돌린다.

- [ ] **Step 6: 문서 갱신**

`README.md`에 `TECH_LOG_STUDIO_SOURCE` 스위치와 `generate:tech-log-contract` / `check:tech-log-contract` 사용법을 추가한다. spec 문서 상단 `## 상태`에 완료 Task와 미완료 항목(실서버 대조, Public HTTP 전환)을 기록한다.

- [ ] **Step 7: 커밋**

```bash
git add README.md docs/superpowers/specs/2026-08-17-techlog-backend-alignment-design.md
git commit -m "docs: record TechLog backend alignment completion state"
```

---

## 완료 확인

계획 종료 시 다음이 모두 성립해야 한다.

1. `check:tech-log-contract`가 canonical drift를 잡는다.
2. canonical 19개 operation이 전부 덮인다 — 18개는 계약 기여, 1개는 업로드 seam.
3. `StudioGateway` 13개 메서드가 HTTP 어댑터로 동작하고 MSW로 검증된다.
4. 23개 오류 코드가 매핑되고 `VERSION_CONFLICT`와 `IDEMPOTENCY_KEY_REUSED`가 구분된다.
5. Asset을 업로드·조회·수정·보관·삭제할 수 있고 `READY`만 삽입 후보다.
6. `QUARANTINED` Asset이 picker에도 렌더러에도 나타나지 않는다.
7. Backend `assetKey`가 네 렌더 표면에서 전부 해석되고, 미해석 키가 화면을 무너뜨리지 않는다.
8. evidence alt 판정이 parser에서 publish 검증으로 옮겨졌다.
9. `createStudioAssetGateway`가 feature input에 배선돼 UI가 Asset 포트에 도달한다.
10. `/studio/assets`가 primary navigation을 바꾸지 않고 추가됐다.
11. 기본 `MOCK`에서 기존 Public·Studio parity 스위트가 전부 통과한다.
12. `main`이 아닌 `feature/techlog-backend-alignment`에 커밋돼 있다.