Files
clean-architecture-frontend…/CHANGELOG.md
T
DongHyeonka 53567879e7 docs(changelog): 깨끗한 clone 검증에서 찾은 CI 빌드 식별값 수정을 미출시 절에 더한다
문제
af312de(vitest와 dev server Playwright가 CI의 VITE_BUILD_ID·VITE_COMMIT_SHA를
물려받지 않는다)는 CHANGELOG 재작성(44aa44d) 뒤에 들어왔다. 미출시 절
머리의 끝 커밋 설명도 그 뒤의 변경을 말하지 않는다.

고른 방법
- 게이트·드릴 행에 1103/11-07 행을 더한다. 리뷰 README 13절에 발견으로
  적는다.
- 머리에 f887817 뒤로 검증 수정과 pin 갱신이 더해졌다고 적는다.

검증
- tests/unit/changelog-review-ids.test.ts 통과.

Refs: docs/reviews/2026-11-03-maturity-review/README.md 13절 11-07
2026-11-05 00:25:24 +09:00

353 lines
86 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 `README.md`의 "Updating a copied project" 절에 있다.
- 버전은 git 태그 `vX.Y.Z`로 식별한다. 태그 사이의 변경을 여기 적는다.
- 미출시 절은 한 번의 동기화 단위(기준 커밋 → 브랜치 끝)에서 받는 변경의 순 요약이다. 최종 상태만 적고, 같은 범위 안에서 뒤 커밋이 바꾼 중간 상태는 지운다. 호환을 깨는 변경은 절 첫머리 "먼저 할 일"에 옮기기 전·옮기는 법·옮긴 뒤 확인 순서로 적는다.
- **[보안]** 복사한 프로젝트도 가져가야 하는 보안·개인정보 수정이다.
- **[계약]** 백엔드, 배포 설정, CI, 또는 기능 코드가 함께 바뀌어야 하는 변경이다(헤더, 변수, 게이트, 공개 포트).
- 표시가 없으면 템플릿 안에서 끝나는 수정이다.
- 괄호 안 ID는 리뷰 발견 ID다. `MMDD/NN-MM`으로 적는다. `MMDD`는 리뷰 폴더 `docs/reviews/YYYY-MM-DD-maturity-review/`의 월일이고, 근거와 재현 조건은 그 폴더의 영역 문서에 있다. 복사한 프로젝트가 README대로 `docs/reviews/`를 지웠다면 이 폴더와 `PRODUCT.md`는 원본 템플릿 repo에서 찾는다. 라운드마다 `NN-MM`을 새로 매기므로 같은 `14-02`라도 라운드가 다르면 다른 결함이다. `F-N`은 그 라운드 `FOLLOW-UP.md`의 ID다. `tests/unit/changelog-review-ids.test.ts`가 라운드 없는 ID를 막는다.
- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`).
## 미출시 — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03`
한 번의 동기화로 받는 변경의 순 요약이다. 범위는 `main` `752a61f`부터 브랜치 `fix/maturity-review-2026-11-03`의 끝까지다. 이 절을 쓸 때 끝은 `f887817`이었다(병합 커밋을 빼고 310개). 그 뒤 깨끗한 clone 검증(merge 단계 14개)에서 찾은 수정과 pin 갱신을 더했다. 버전 번호와 태그는 아직 정하지 않았다.
이 묶음은 세 갈래를 합쳤다.
- `fix/ui-design-audit-2026-11-01`: 2026-11-01 UI 디자인 감사(`docs/reviews/2026-11-01-ui-design-audit.md`, ID `UI-NN`)와 2026-11-01 성숙도 리뷰(`docs/reviews/2026-11-01-maturity-review/`) 조치.
- `claude/happy-easley-233d07`: 짝 백엔드 Envelope 읽기, V2 HTTP 경로 삭제, 거절 판정 표, 쿠키 쓰기 CSRF, KEYED 재전송. 앞 갈래와 `e40684b`에서 합쳤다.
- 2026-11-03 성숙도 리뷰(`docs/reviews/2026-11-03-maturity-review/`) 조치 브랜치 11개. `fix/maturity-review-2026-11-03`에서 합쳤다.
읽는 법:
- 최종 상태만 적는다. 같은 범위 안에서 뒤 커밋이 다시 바꾼 중간 상태는 적지 않는다. 예를 들어 V2 클라이언트를 고친 커밋들은 V2를 지운 행 하나로 남겼다. 중간 기록은 커밋 이력에 있다.
- 이 repo의 커밋 해시는 기준점 `752a61f`·`af3d8e6`을 빼면 모두 이 범위에 있다. 브랜치 끝에서 닿고 `752a61f`에서는 닿지 않는다. 다른 repo의 커밋(다운스트림, 짝 백엔드)은 repo 이름과 함께 적었다.
- 두 다운스트림(tech-log-frontend, memento-frontend)의 기준점은 `af3d8e6`이다. `af3d8e6`과 `752a61f` 사이에는 리뷰 문서만 있다. 그래서 두 제품이 받을 변경은 이 절과 같다.
### 먼저 할 일 (BREAKING)
복사한 프로젝트가 이 묶음을 받을 때 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림에서 읽은 모양(memento-frontend `d3810a0`, tech-log-frontend `7a4e201a`, 2026-11-05)을 단계마다 적었다. 템플릿은 이 안내를 두 제품 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
#### 옮기기 전
1. 기준점을 확인한다. memento는 `.template-origin`, tech-log는 `template.lock.json`의 `sourceRevision`에 있다. 둘 다 `af3d8e6`이다.
2. 제품이 고친 템플릿 파일을 뽑는다. 이 묶음은 그 일을 받을 제품 소유 파일을 새로 둔다(옮기는 법 2단계). 템플릿 파일을 고친 채로 두면 동기화마다 충돌한다.
- memento: `src/bootstrap/runtime-adapters.ts`, `src/features/feature-adapter-contribution.ts`(capability `offsetUpload`·`runtime`), `src/contracts/rest-profiles.ts`(`MEMENTO_BFF_READ`·`MEMENTO_BFF_WRITE`), `src/contracts/external-contract-runtime.ts`(출처 종류 `PRODUCT_LOCAL_CONTRACT`), `src/features/installed-feature-contracts.ts`(`APP_HOME` 다리), `src/features/installed-runtime-capabilities.ts`(Service Worker `ACTIVE`), `src/presentation/routes/app-router.tsx`(`ownsShell` 다리).
- tech-log: `src/contracts/env.ts`(`TECH_LOG_STUDIO_SOURCE`·`TECH_LOG_PUBLIC_SOURCE` 행), `src/bootstrap/create-runtime-composition.ts`(부트 전 BFF 세션 owner), `src/contracts/rest-profiles.ts`(`TECH_LOG_STUDIO_SESSION`·`TECH_LOG_STUDIO_BOOTSTRAP`), `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/runtime-config-schema.ts`, `src/features/installed-*` 다섯 개(TechLog 직접 조립. 그중 `installed-feature-runtimes.tsx`는 템플릿이 지웠다), `src/presentation/routes/app-router.tsx`(PUBLIC/STUDIO 라우터).
3. 기능마다 HTTP descriptor를 센다. method, `retrySemantics`, `responseEnvelope`, 입력·응답·실패 검증기의 schemaId, 그 검증기가 zod인지. 옮기는 법 4·5단계의 작업량이 이 숫자로 정해진다.
- memento-web: descriptor 29개. 입력·응답 schemaId 42개와 실패 본문 `MementoProblem` 1개. 검증기는 zod가 아니라 손으로 쓴 `isRecord` 검사다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`·`IDEMPOTENT`·`NEVER`다.
- TechLog: 검증기는 `zodValidator`다. 출력은 Envelope 뼈대만 검사하고 본문은 통과시킨다. `responseEnvelope`는 없다. GET은 `SAFE`, 쓰기는 `KEYED`나 `NEVER`(둘 다 `retryBudget` 0)다.
4. 지금 게이트 결과를 남긴다. 동기화 뒤의 실패가 원래 있던 것인지 가르는 데 쓴다. 두 제품의 지난 동기화 기록(`docs/operations/template-sync-2026-09-29.md`)과 같은 목록이면 된다.
#### 옮기는 법
1. **기능이 아닌 폴더의 표시.** `src/features/<dir>/NOT_INSTALLED`를 같은 자리의 `NOT_A_FEATURE`로 바꾼다. 생성기는 `NOT_INSTALLED`를 더는 읽지 않는다. 표시와 `feature-module.ts`가 한 폴더에 있으면 생성기가 실패한다.
- memento: `local-draft-feature`. 템플릿 폴더라 병합으로 바뀐다.
- tech-log: `tech-log`, `reference-feature`, `local-draft-feature`. `reference-feature`는 템플릿이 그 폴더에 둔 `feature-module.ts`·`feature-runtime.ts`·`context-routes.ts`를 받지 않는다.
(1103/09-09)
2. **제품 코드를 제품 소유 파일로 옮긴다.** 템플릿은 아래 파일을 비워서 내보내고, 복사한 뒤에는 고치지 않는다. 제품 코드를 여기로 옮기고 "옮기기 전" 2단계의 템플릿 파일은 템플릿 것으로 되돌린다.
- `src/contracts/product-contracts.ts`
- `PRODUCT_REST_AUTH_PROFILES`: 제품 인증 프로필. memento의 `MEMENTO_BFF_READ`·`MEMENTO_BFF_WRITE`, tech-log의 `TECH_LOG_STUDIO_SESSION`·`TECH_LOG_STUDIO_BOOTSTRAP`이 여기 온다. 템플릿 프로필과 id가 겹치면 모듈 로드가 실패한다.
- `PRODUCT_RUNTIME_CONFIG_FIELDS`와 `PRODUCT_ENV_REGISTRY`: 제품 런타임 설정 키(zod, `.default()`나 `.optional()`)와 그 FE-REG-ENV 행(`as const`). 키마다 행이 있어야 하고 행의 `required`·`defaultValue`가 스키마와 같아야 한다(`tests/unit/env-registry-coverage.test.ts`, `test:unit`). tech-log의 `TECH_LOG_*_SOURCE` 두 키가 여기 온다.
- `src/bootstrap/product-composition.ts`
- `composeProductSessionOwner(context)`: 부트 전 세션 owner. `AUTH_MODE=external`일 때만 불린다. tech-log가 `create-runtime-composition.ts`에서 host 전역에 넣던 BFF owner가 여기 온다. context의 `fetch`는 필수 칸이다(마감 `REQUEST_TIMEOUT_MS`, 본문 64 KiB, redirect 거부). 이 context를 직접 만드는 제품 테스트는 `fetch`를 더한다. 짝 백엔드 두 인증 모드의 owner 예시는 `recipes/session-owners/`에 있다.
- `composeProduct(context)`: `capabilities`(memento `offsetUpload`·`runtime`, tech-log Studio 소스·HTTP), `credentialProviders`(인증 프로필별 자격증명. memento는 `x-xsrf-token`, tech-log는 `x-csrf-token`), 선택 칸 `onCredentialRejected`와 `scopeParticipants`.
- 401 처리가 바뀌었다. 제품 provider가 자격증명을 낸 요청의 401은 템플릿 세션을 로그아웃시키지 않고 `onCredentialRejected`로만 온다. 두 제품처럼 provider와 세션 owner가 한 쿠키 세션을 쓰면 여기서 owner에 알린다(예: owner의 `notifyUnauthenticated`). 알리지 않으면 템플릿 세션은 그 401을 모른다.
- `scopeParticipants`: 로그아웃·계정 전환 때 FENCED와 READY 사이에서 닫을 제품 자원. 닫기가 실패하면 READY로 가지 않는다.
- `src/features/product-capabilities.ts`
- `ProductFeaturePlatformCapabilities`: 제품 capability의 타입. `feature-adapter-contribution.ts`의 `FeaturePlatformCapabilities`에 `declare module`로 붙이던 보강을 여기로 옮긴다. 템플릿이 만드는 키(`http`, `telemetry`, `indexedDb`)는 다시 선언할 수 없다.
- `PRODUCT_RUNTIME_CAPABILITY_SELECTION`: Service Worker·realtime·web worker·offline command 선택. memento가 `installed-runtime-capabilities.ts`에 적은 Service Worker `ACTIVE` 선택이 여기 온다.
- `config/ci/product-gates.json`: 배포(`deployment`)와 제품 merge 검사(`mergeGates`, ID `PRODUCT-GATE-NNN`). 배포 슬롯을 `config/ci/gates.json`에서 채웠다면 여기로 옮긴다. `deployment`에는 package script 이름과 `vars.*`·`secrets.*` 바인딩만 적는다. 승격 후보를 받아 digest를 확인하고 푸는 단계는 템플릿이 만들고, `secrets.*`는 deploy 단계에만 간다.
- 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 코드는 `undefined`를 받는다.
(1101/09-02, 1103/09-01, 1103/09-02, 1103/09-03, 1103/09-05, 1103/09-08, 1103/02-01, 1103/12-07, 1103/13-05)
3. **기능을 선언과 실행부로 나눈다.** 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서 나눴다. 완성된 모양은 `src/features/reference-feature/`다.
- 선언(`feature-module.ts`, `FeatureModule`): 초기 청크에 남는다. `id`, `contracts`(route 표, route runtime 계약, invalidation, topic version, `contractPackages`), `routes`, `messages`, `loadRuntime`만 가진다.
- 실행부(`feature-runtime.ts`, `defineFeatureRuntime({ featureId, schemas, adapters, contractContributions })`): 그 기능의 route에 처음 들어갈 때 router가 `application.features.load(featureId)`로 적재한다.
순서:
1. 기능 계약에서 V2 칸 `apiOperations`·`runtimeSchemas`·`mappers`를 지운다. 스키마 메타데이터 `schemas`는 별도 파일로 빼서 `defineFeatureRuntime`에 넘긴다(참조: `contracts/reference-schema-metadata.ts`). memento-web에는 `*-api-contract.ts`가 없다. 이 칸들은 `contracts/memento-feature-contract.ts`에 있다. `apiOperations`와 `mappers`는 비어 있어 지우기만 한다. `runtimeSchemas`(`MEMENTO_RUNTIME_SCHEMA_CODECS`, 라우트 codec 7개)는 3번으로, `schemas`(라우트 행 7개)는 새 메타데이터 파일로 간다.
2. 선언 계약에 `contractPackages`를 더한다. 기능의 `EXTERNAL_PACKAGE` 계약 기여가 고정하는 패키지 신원 목록이다. 없으면 `Object.freeze([])`. 부팅 때 release manifest를 이 목록과 맞춰 본다. 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능 전용이다. memento가 템플릿 파일에 더한 `PRODUCT_LOCAL_CONTRACT`는 조립이 `unknown contribution source kind`로 거절한다. `EXTERNAL_PACKAGE`로 바꾸고 신원(패키지 이름·정확한 버전·`sha256:` digest·revision)을 준다. 자리표시자 신원은 로컬·개발 빌드에서는 되지만 staging·production 승인(FE-GATE-027)이 거절한다. 선택 기준은 `docs/manual/02-decision-tables.md` 2절이다.
3. route codec을 `context-routes.ts`의 각 route `handle.codecs`로 옮긴다(참조: `presentation/reference-route-codecs.ts`의 `REFERENCE_FEATURE_ROUTE_CODECS`). 플랫폼 codec과 같은 id는 쓸 수 없다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없어졌다.
4. `feature-runtime.ts`를 만들고, `feature-module.ts`에서 `adapters`·`contractContributions`·`runtimes`를 지운 뒤 `loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME`을 넣는다. `feature-runtime.ts`를 어디서도 정적으로 import하지 않는다. 그러면 실행부가 다시 초기 청크에 들어간다. `featureId`가 모듈 id와 다르면 적재 때 실패한다.
5. runtime descriptor에 붙인 제품 칸은 context로 옮긴다. memento-web의 `ownsShell: true`와 `app-router.tsx` 다리는 `src/contexts/memento-context/context-layout.tsx`의 `CONTEXT_LAYOUT`이 대신한다. 레이아웃은 skip link와 `<main id="main-content" tabIndex={-1}>` 하나를 그린다. `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 검사한다. memento-web은 이미 route id `APP_HOME`을 선언하므로 그것만으로 플랫폼 홈을 대신한다. `installed-feature-contracts.ts`의 `FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS` 다리는 지운다.
6. 기능 input(`application.features.get(id)`)은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저 `await application.features.load(id)`를 부른다. `ApplicationApi.features`를 직접 구현하거나 fake로 만든 코드는 `load`를 더한다. 모든 기능의 실행부가 필요한 화면은 `loadInstalledFeatureRuntimeRegistries()`를, Node 스크립트와 테스트는 `src/features/loaded-feature-runtimes.ts`를 쓴다. `src/`에서 이 파일을 import하면 아키텍처 규칙 `boot-does-not-load-every-feature-runtime`이 막는다.
7. `vite.config.ts`의 청크 그룹(`feature-declarations`, `feature-platform`, `react-dom`)을 가져간다. 없으면 기능마다 선언 청크가 하나씩 는다.
**직접 조립 제품(tech-log).** TechLog는 `feature-module.ts` 없이 `installed-*` 파일에 직접 조립된다. 이 묶음에는 그 자리가 없다. `installed-feature-runtimes.tsx`가 없어졌고, route codec은 context route handle에 실리고, 계약 기여는 기능 실행부를 적재할 때 설치되고, FE-REG-API·FE-REG-SCHEMA는 생성기가 설치한 기능만 본다. 템플릿이 준비한 길은 TechLog를 기능 모듈로 바꾸는 것이다. PUBLIC 묶음은 루트 `*`에 자기 레이아웃과 `APP_HOME`을 가진 context가 되고, 필요하면 같은 레이아웃을 쓰는 두 번째 루트 context(예: `topics/*`)를 둔다. STUDIO 묶음은 자기 레이아웃을 가진 `studio` context가 된다. 이 모양은 `tests/helpers/fixture-layout-product.tsx`가 선언하고 `tests/component/context-layouts.test.tsx`와 `layout-landmarks.test.tsx`가 실행한다. 바꾸면 TechLog descriptor에도 4·5단계가 적용된다. 직접 조립을 유지하면 `installed-*`와 라우터를 제품이 계속 고쳐야 하고, 템플릿은 그 경로를 검사하지 않는다(알려진 제한).
(1101/15-01, 1101/07-04, 1101/09-03, 1101/16-04)
4. **HTTP descriptor 조립 규칙.** 계약 조립(`composeContractContributions`)이 아래를 어기는 기여를 거절한다. 메시지는 `Installed contract contribution is not composable: <reason>`이다.
- GET·HEAD의 `retrySemantics`는 `SAFE`나 `IDEMPOTENT`다. 재시도를 막으려면 `retryBudget: 0`.
- POST·PUT·PATCH·DELETE에는 `SAFE`를 쓸 수 없다. `IDEMPOTENT`, `KEYED`(`commandRecovery` 필요), `NEVER`(`retryBudget` 0) 중 하나다.
- 계약 기여 하나 안의 operation은 모두 같은 `responseEnvelope`를 읽는다. 값이 없는 것과 `"NONE"`은 같다. 두 백엔드를 쓰면 기여를 나눈다.
- 쿠키 인증 프로필로 쓰기를 하면 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다.
- `commandEffect.refusedBeforeWrite`(쓰기 전에 나는 업무 거절 code 목록)는 `responseEnvelope: "ENVELOPE_V1"` operation에만 쓴다. `IDEMPOTENT_*`·`IDEMPOTENCY_*` code는 적을 수 없다.
두 다운스트림의 지금 descriptor는 앞의 넷을 지킨다. memento의 쓰기 프로필 `MEMENTO_BFF_WRITE`는 `x-xsrf-token`을, TechLog의 `TECH_LOG_STUDIO_SESSION`은 `x-csrf-token`을 요구한다. `responseEnvelope`가 없는 operation의 적용 여부는 지금처럼 `classifyProblem`이 정한다.
뮤테이션: `useApplicationMutation`은 `useServerStateScope()`의 scope를 담은 `BoundMutation`만 받는다. memento-web의 뮤테이션 8곳과 TechLog는 이미 그 모양이다. `operationId`·`requiresIdempotencyKey`는 `commandMutationIdentity(<descriptor>)`로 받을 수 있고, 그러면 오타를 타입 검사가 잡는다. `BoundMutation.owner`와 `QueryDefinition.owner`·`operationId`는 `@deprecated` 선택 칸이 됐고 다음 릴리스에서 지운다.
(1103/07-01, 1103/03-03, 1103/16-01, 1103/07-02, 1103/03-01, 1101/08-03, 1103/16-05, 1103/16-06)
5. **레지스트리 행과 기준선.**
- FE-REG-API 행은 설치된 기능의 모든 V3 descriptor에서 뽑는다(22칸). V2 API 행이 없던 기능도 descriptor마다 행이 새로 생긴다. memento-web은 29행이다.
- 각 행의 `requestSchema`·`responseSchema`·`problemSchema`는 FE-REG-SCHEMA 행을 가리켜야 한다. 그 기능의 `schemas`에 schemaId마다 행을 더한다. memento-web은 지금 라우트 행 7개뿐이라 43행(입력·응답 42, `MementoProblem` 1)을 더한다. 없으면 `check:registries`가 operation마다 `FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>`로 실패한다.
- 행의 칸: `boundary`는 쓰인 자리대로 적는다(`api-request` 입력, `api-response` 응답, `api-problem` 실패 본문, `route-params`, `route-search`, `route-search-api-request`). `direction`은 입력이 `REQUEST`, 응답·실패 본문이 `RESPONSE`다. `unknownFieldPolicy`는 적으면 검증기 동작과 같아야 한다. `tests/unit/schema-metadata-policy.test.ts`(`test:unit`)가 설치된 기능 전부를 대조한다.
- `runtime`은 `"zod"`만 받는다. 손으로 쓴 검증기를 그대로 두고 `"zod"`라고 적으면 행이 사실과 다르다. memento-web의 검증기는 `zodValidator(schemaId, schema)`(`src/contracts/zod-validator.ts`)로 옮긴다. 지금 검사하는 만큼(객체인지, `items`가 배열인지)만 옮겨도 된다. 일부러 검증하지 않을 칸은 `unvalidatedPayload(schemaId, reason)`로 바꾼다. 그 칸은 FE-REG-API 행의 `unvalidated`와 플랫폼 구성 화면에 드러난다. governance의 `runtime` 허용값을 제품 쪽에서 넓히지 않는다.
- 다 맞춘 뒤 기준선을 한 번 다시 승인한다. FE-REG-API governance가 바뀌어 동기화 직후 `check:registries`가 `contract-field-changed`로 실패하기 때문이다. `REGISTRY_BASELINE_OWNER=<owner> REGISTRY_BASELINE_REASON="<이유>" corepack pnpm update:registry-baseline`. 지금 diff와 맞지 않는 옛 breaking 증거 행도 이 명령이 지운다.
(1103/07-01, 1103/16-04, 1103/07-03, 1101/07-03, 0929/07-01)
6. **쓰는 곳이 있을 때만.**
- V2 HTTP 클라이언트와 V2 API 행에서 지운 이름(아래 `048f490`·`12f3bb7` 행). 두 다운스트림은 앱 코드에서 V2 클라이언트를 부르지 않는다. 부르는 곳은 템플릿의 `tests/unit/runtime-adapters.test.ts`뿐이고 그 파일은 템플릿 것으로 바뀐다.
- realtime: `BoundedPollOperationContract`를 지웠다. SSE·poll이 서버에 닿지 못한 실패는 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`이다.
- 예제 화면 3개(`EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`)가 `platform-examples-feature`로 옮겼다. 예제를 지운 제품(tech-log)은 이 기능 폴더와 `src/contexts/platform-examples-context/`를 지운다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. memento의 `production-csp.spec.ts`·`old-tab-chunk-recovery.spec.ts`가 `/examples/states`·`/examples/ui`에서 시작한다. `/examples/platform`(플랫폼 구성 화면)은 플랫폼 라우트로 남는다.
- 포트를 직접 구현한 코드: `OpfsJournalPort.countPartitionTransactions`·`removePartition`, worker gateway의 `removePartition`, `PublicCacheInspection.activePointer`가 필수 칸이다.
- offline-indexeddb recipe 타입: `src`와 이름이 같은 34개가 `src` 타입을 다시 내보낸다.
(1103/04-01, 1103/04-04, 1103/09-04, 1103/05-01, 0929/05-01, 1103/02-05, 0929/05-03)
7. **초기 JS 예산.** 예산은 gzip 204,800 B와 초기 파일 26개다(`config/performance/budgets.json`, merge 게이트 FE-GATE-012의 `check:bundle`). 템플릿 자체가 202,927 B를 쓴다. 여유는 1,873 B다. 측정용 기능 복사본 하나를 같은 context에 더하면 +768 B, 새 context 하나는 +233 B다(`config/scale/feature-shape-ceilings.json`. `tests/unit/feature-shape-growth.test.ts`가 기능 1 KiB·context 512 B로 막는다). 제품 기능의 선언(라우트 표, 문구)은 초기 청크에 들어간다. memento-web(라우트 14개)과 기능 모듈로 바꾼 TechLog의 크기는 템플릿이 재지 않았다. `build` 뒤 `check:bundle`이 넘은 한도와 초과량을 적는다. 예산을 올릴 때는 `docs/operations/performance-evidence.md`대로 기준선·새 측정값·이유를 같은 변경에 적는다. 초기 파일 수는 HTTP/2 서빙이 전제다.
(1101/15-01, 1103/15-02, 1103/15-03, 1103/15-04, 1103/15-05)
#### 옮긴 뒤 확인
1. 로컬 merge 게이트 14개를 돈다(README "CI and evidence"의 반복문). `config/ci/product-gates.json`에 적은 `PRODUCT-GATE-NNN`은 workflow의 `product_merge_gate` job이 돈다.
2. 그중 이 묶음 때문에 먼저 볼 것:
- `check:registries`: `11 registries PASS`. 기준선을 다시 승인한 뒤에는 `compatibility=none`.
- `test:unit`: `schema-metadata-policy`, `env-registry-coverage`, `feature-shape-growth`.
- `test:component`: `layout-landmarks`, `context-layouts`.
- `build` 뒤 `check:bundle`: 예산 안.
- `verify:documentation`(FE-GATE-017): 참조 기능을 지운 제품도 통과한다.
- `test:sample-removal -- --feature=<제품 기능 id>`: 그 기능을 지운 사본이 게이트를 통과한다.
3. 배포가 있는 제품: FE-GATE-019는 TLS ALPN `h2`와 entry 응답의 `Content-Encoding`(br·gzip·zstd)을 요구한다. HTTP/1.1이나 압축하지 않는 호스트는 FAIL이다.
### 보안·계약 변경
#### 기능 구조와 조립
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] **BREAKING** | 기능을 선언(`feature-module.ts`)과 실행부(`feature-runtime.ts`)로 나눴다. 위 "먼저 할 일" 3단계. `ApplicationApi.features`에 `load(featureId)`가 생겼다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없다 (1101/15-01) | `src/features/`, `src/application/ports/in/application-api.ts`, `src/presentation/routes/`, `vite.config.ts`, `.dependency-cruiser.json` | `298201f` |
| [계약] **BREAKING** | 기능이 아닌 폴더의 표시는 `NOT_A_FEATURE`다. `NOT_INSTALLED`는 읽지 않는다. 표시와 `feature-module.ts`가 함께 있으면 생성기가 실패한다 (1103/09-09) | `scripts/generate-product-feature-index.ts`, `src/features/*/NOT_A_FEATURE` | `9edc830` |
| [계약] | 제품 코드는 템플릿 파일이 아니라 제품 소유 파일에 둔다. `src/bootstrap/product-composition.ts`(capability, 인증 프로필별 자격증명 provider, `composeProductSessionOwner`, 선택 `onCredentialRejected`·`scopeParticipants`), `src/contracts/product-contracts.ts`(제품 인증 프로필, 런타임 설정 키, 그 FE-REG-ENV 행), `src/features/product-capabilities.ts`(capability 타입 `ProductFeaturePlatformCapabilities`, 선택 런타임 `PRODUCT_RUNTIME_CAPABILITY_SELECTION`). 자격증명 순서는 scope fence → ANONYMOUS → 제품 provider → 세션 → fence 재확인이다. 제품 설정 키는 `.default()`나 `.optional()`이어야 템플릿 테스트가 통과한다 (1101/09-02, 1103/09-02, 1103/09-05) | `src/bootstrap/product-composition.ts`, `src/bootstrap/product-composition-contract.ts`, `src/contracts/product-contracts.ts`, `src/features/product-capabilities.ts`, `src/features/installed-runtime-capabilities.ts` | `da1e128`, `ece944d`, `245f428`, `2f6df14`, `2963c6f` |
| [계약] | 런타임 설정 키마다 FE-REG-ENV 행이 있어야 하고, 행의 `required`·`defaultValue`가 스키마와 같아야 한다(`tests/unit/env-registry-coverage.test.ts`). 템플릿 행 `RELEASE_ID`·`BUILD_ID`를 더했고 `TELEMETRY_ENABLED`·`AUTH_MODE`·`RELEASE_MANIFEST_URL`·`CAPABILITY_OVERRIDES`·`FEATURE_OVERRIDES` 행을 스키마에 맞췄다. `defaultValue`는 객체일 수 있다 (1101/09-02, 1103/13-04) | `src/contracts/env.ts`, `config/contracts/registry-governance.json`, `tests/unit/env-registry-coverage.test.ts` | `d0414c8`, `a144b57` |
| [계약] | 기능 어댑터 기여는 실행 중에도 `needs`에 적은 capability만 받는다. cast로 다른 capability를 읽던 기능은 `undefined`를 받는다 (1103/09-08) | `src/features/feature-adapter-contribution.ts` | `e7d6358` |
| [계약] | 기능 계약이 route id `APP_HOME`을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. `src/contexts/<context>/context-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `<main id="main-content" tabIndex={-1}>` 하나를 그려야 하고, `tests/component/layout-landmarks.test.tsx`가 설치된 레이아웃을 모두 실행해 본다 (1101/09-03) | `src/contracts/routes.ts`, `src/contexts/bounded-context-module.ts`, `scripts/generate-product-feature-index.ts`, `tests/component/layout-landmarks.test.tsx` | `ca16187`, `27f4523` |
| [계약] | 앱 조립이 닿지 않는 기능 라우트를 앱 모듈을 평가할 때 throw로 거절한다. 소유 context 루트 밖의 라우트, 계약에 없는 route handle, 플랫폼 라우트가 먼저 받는 경로, 다른 기능과 같은 경로(파라미터 이름만 다른 것과 대소문자·끝 슬래시만 다른 것 포함)다. 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands)도 거절한다 (1101/09-06, 1101/09-07, 1103/08-04, 1101 README 14.4) | `src/apps/deployable-app-module.ts`, `src/contexts/bounded-context-module.ts`, `src/bootstrap/` | `7139c7c`, `d6e4e51`, `7d85589`, `8469554`, `851fded`, `48a4074` |
| [계약] **BREAKING** | 예제 화면 `EXAMPLES_UI`·`EXAMPLES_STATES`·`EXAMPLES_AUTH`가 끌 수 있는 기능 `platform-examples-feature`(context `platform-examples-context`, 루트 `examples/*`)로 옮겼다. 페이지 파일은 그 기능의 `presentation/`에 있다. `PLATFORM_ROUTE_REGISTRY`·`PLATFORM_ROUTE_RUNTIME_CONTRACT`·`PLATFORM_ROUTE_RUNTIME`에서 키가 빠졌다. 홈 문구 `home.starter.platform`·`ui`·`states`는 `home.starter.open({title})`로 바뀌었다. 예제를 지운 제품은 이 기능 폴더와 context를 지운다. `/examples/platform`은 플랫폼 라우트로 남는다 (1103/09-04) | `src/features/platform-examples-feature/`, `src/contexts/platform-examples-context/`, `src/contracts/routes.ts` | `b96d61d` |
| [계약] | 계약 기여의 출처는 `EXTERNAL_PACKAGE`이고, `TEMPLATE_FIXTURE`는 참조 기능만 하나 쓸 수 있다. 다른 출처 종류는 `unknown contribution source kind`로 거절한다 (1101/07-04) | `src/contracts/external-contract-runtime.ts` | `c063389` |
| [계약] **BREAKING** | `useApplicationMutation`은 raw `{ execute, definitionId }`를 받지 않는다. `useServerStateScope()`의 scope로 만든 `BoundMutation`을 넘기고 `execute(input, { signal, intent })`로 부른다. `commandMutationIdentity(<descriptor>)`가 `operationId`·`requiresIdempotencyKey`를 descriptor에서 준다. `QueryDefinition.owner`·`operationId`와 `BoundMutation.owner`는 아무도 읽지 않아 `@deprecated` 선택 칸으로 바꿨고 다음 릴리스에서 지운다. raw query는 남았다. 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기) (1101/08-03, 1103/16-05, 1101/03-03, 1103/16-06) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/adapters/query/` | `1fa5f3e`, `f59a806`, `68f94f5` |
#### HTTP와 계약
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] **BREAKING** | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(`src/adapters/http/index.ts`)에서 `createHttpClient`, `HttpClient`, `HttpClientDependencies`, `HttpFailure`, `HttpResult`, `LegacyHttpInput`, `Scheduler`, `OperationRequestInput`가, `src/bootstrap/runtime-adapters.ts`에서 `createRuntimeHttpClient`, `RuntimeHttpContract`가 없어졌다. 지운 파일: `client.ts`, `bounded-json.ts`, `request-builder.ts`, `resource-mapper.ts`, `retry-policy.ts`, `schema-registry.ts`(`src/adapters/http/`). Envelope 스키마는 `backend-envelope.ts`에 있다. V2 클라이언트를 부르는 코드는 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다 | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `048f490` |
| [계약] **BREAKING** | 기능마다 적던 V2 API 행을 지웠다. FE-REG-API 행은 contract contribution의 V3 descriptor에서 뽑는다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`, 22칸: operation·경로·인증·재시도 의미·본문 모양·Envelope·스키마 세 개·`acceptedStatuses`·`emptyBodyStatuses`·`unvalidated`·바이트 상한 둘·`totalDeadlineMs`·`retryBudget`·`traffic`·`commandEffect`·`commandRecovery`). `problemSchema`도 FE-REG-SCHEMA를 참조하고, 그 행의 `boundary`는 새 값 `api-problem`이다. `problemSchema`·`unvalidated` 변경과 status 값 제거는 breaking이다. `FeatureRuntime`은 `apiContract` 대신 `schemas`(FE-REG-SCHEMA 행)를 받는다. 지운 이름: `defineRestOperation`, `ApiOperation`, `RestOperationV2`, `composeApiOperations`, `validateApiRuntimeBindings`, `getApiOperation`, contracts의 `API_OPERATIONS`; `rest-profiles.ts`의 `createRestProviderProfile`, `RestProviderProfile`, `resolveRestSecurityProfiles`, `validateRestProfileBindings`, `REST_CSRF_PROFILES`, `RestCsrfProfile`; `loaded-feature-runtimes.ts`의 `RUNTIME_SCHEMA_CODECS`, `MAPPER_REGISTRY`, `REST_PROFILE_BINDINGS_VALID`, `API_RUNTIME_BINDINGS_VALID`. realtime `apiOperations` 바인딩은 `ApiOperationRow`를 받고, snapshot operation을 `method: "GET"`과 `SAFE`·`IDEMPOTENT`로 본다. 옮기는 법은 위 "먼저 할 일" 3·5단계 (1103/07-01, 1103/16-04) | `src/contracts/api-operations.ts`, `src/contracts/schema-registry.ts`, `src/features/feature-module.ts`, `src/features/installed-feature-runtime-registries.ts`, `config/contracts/`, `scripts/create-feature.ts` | `12f3bb7`, `08ed0a0`, `3b40f73` |
| [계약] **BREAKING** | 재시도 의미를 조립 때 검사한다. GET·HEAD는 `SAFE`·`IDEMPOTENT`만, POST·PUT·PATCH·DELETE는 `SAFE`를 쓸 수 없다 (1103/07-01, 1103/03-03) | `src/contracts/external-contract-runtime.ts` | `e4caafd`, `61f70cb` |
| [계약] | 계약 기여 하나 안의 operation이 서로 다른 `responseEnvelope`를 읽으면 조립이 거절한다. 두 백엔드는 기여를 나눈다 (1103/16-01) | `src/contracts/external-contract-runtime.ts` | `3f7e10c` |
| [보안] [계약] | 쿠키 인증 프로필(`SAME_ORIGIN_COOKIE`)로 쓰기(GET·HEAD 밖)를 하는 operation은 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다. 아니면 조립이 거절한다. POST·PUT·PATCH·DELETE × 두 헤더 표로 테스트한다 (1103/07-02) | `src/contracts/external-contract-runtime.ts` | `365d8c3`, `a94006b` |
| [계약] | V3 descriptor의 선택 칸 `responseEnvelope: "ENVELOPE_V1"`이면 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. `meta.requestId`·`traceId`는 선택이다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가). `create:feature`가 만든 기능은 이 값을 선언한다. 참조 기능과 값이 없는 descriptor는 DTO와 problem details를 읽는다 (1101 README 14.3) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/`, `scripts/create-feature.ts`, `tests/mocks/handlers/http-scenarios.ts` | `7db32e1`, `bd83b49` |
| [계약] | Envelope operation의 400·409·422와 백엔드가 정한 5xx 넷은 `classifyProblem` 대신 백엔드 기준 표(`backend-envelope.ts`, 근거는 계약 문서 6.1절)가 정한다. 적용 안 됨(`NOT_APPLIED`)은 400 `VALIDATION_FAILED`(details 모양과 상관없음), 400 `IDEMPOTENCY_KEY_INVALID`, 422 `IDEMPOTENT_REQUEST_MISMATCH`와 그 operation의 `refusedBeforeWrite` code다. 그 밖의 400·409·422는 결과 불명이다. 503 `IDEMPOTENCY_UNAVAILABLE`, 503 `IDEMPOTENCY_COMPLETION_UNKNOWN`, 500 `IDEMPOTENCY_RECOVERY_REQUIRED`, 503 `REQUEST_TIMEOUT`은 분류기와 상관없이 결과 불명이고 키를 지킨다. KEYED operation은 503 `IDEMPOTENCY_UNAVAILABLE`을 `retryBudget` 안에서 같은 키로 다시 보낸다. 필드 목록이 있는 거절은 `VALIDATION_REJECTED`와 필드 오류, 필드 목록 없는 422는 `UNKNOWN_CLIENT_FAILURE`다. 진단은 두 멱등성 거절에 `reason`을 싣는다 (1101 README 14.4, 1103/03-04, 1103/08-05) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/http-execution-v3.ts`, `docs/architecture/backend-api-and-server-state-contract.md` | `3261208`, `c05f41a`, `3761507`, `613c1cf` |
| [계약] | `CommandEffectDescriptor.refusedBeforeWrite`(선택, Envelope operation 전용): 그 엔드포인트가 쓰기 전에만 내는 업무 거절 code. 적은 code의 400·409·422는 `NOT_APPLIED`라 폼에서 값을 고쳐 다시 저장할 수 있다. 멱등성 code를 적거나 Envelope가 아닌 operation에 적으면 조립이 거절한다 (1103/03-01) | `src/contracts/external-contract-runtime.ts`, `src/adapters/http/backend-envelope.ts`, `src/contracts/api-operations.ts` | `1e8b3d0`, `3fba68b` |
| [계약] | 짝 백엔드 계약 기준점을 기계가 읽는다. `config/contracts/backend-contract-pin.json`(백엔드 `45d2a478`)과 백엔드 `docs/web/http-contract.md` §2 답 표(`config/contracts/backend-idempotency-answers.json`)를 `tests/unit/backend-contract-pin.test.ts`가 프론트 판정 표와 대조한다. `check:backend-contract-drift --backend <백엔드 checkout>`(로컬, 게이트 밖)이 pin 뒤의 백엔드 변경을 알린다 (1103/12-06) | `config/contracts/`, `scripts/check-backend-contract-drift.ts`, `src/adapters/http/backend-envelope.ts` | `ba2b4f4`, `5379c80` |
| [계약] | 성공 결과에 Envelope `meta.page`가 `page`로 실리고, `mapSuccess` 두 번째 인자 `FeatureHttpSuccessContext { page }`로 받는다(배럴 `EnvelopePage`). bulk `results`는 지원하지 않는다. 실패 Envelope의 `meta.traceId`는 `AppFailure.traceId`가 된다. 실행 결과의 선택 칸 `sentRequestId`: 서버가 `x-correlation-id`를 돌려주지 않으면 `AppFailure.requestId`는 보낸 값이고, 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (1103/03-02, 1103/03-06, 0929/03-04) | `src/adapters/http/` | `49a0986`, `631ce33`, `849d000` |
| [계약] | 결과 불명 쓰기의 진단·텔레메트리에 `effect_certainty`가, 진단 `reason`에 `UnknownEffectReason`이 실린다 (1103/03-05) | `src/adapters/http/`, `config/contracts/` | `39c1de2` |
| [계약] | 키 없는(`NEVER`) 결과 불명 요청에는 "같은 요청으로 다시 보내기"가 없다. mutation 컨트롤러 `canResendUnknownEffect`, `AsyncState.unknownEffectResendable`. 처리 중 409의 `Retry-After`는 `retryAfterMs`로 실리고, 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다 (0929/03-03, 백엔드 리뷰 1101/02-01) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/components/async-surface.tsx` | `2017ef7`, `47fec5c` |
| [계약] | 전송 전 거절의 원인이 진단에 남는다. 연결 실수·멱등 키 위반은 `UNKNOWN_CLIENT_FAILURE`이고 화면 문구는 "요청을 처리할 수 없습니다."다 (1101/03-02) | `src/adapters/http/` | `4da0466` |
| [계약] | 참조 기능의 생성 분류기가 409를 problem code로 나눈다. 선언한 충돌 code(`CONFLICT`)만 적용 안 됨이고, `IDEMPOTENT_IN_FLIGHT`·code 없는 409·모르는 409는 결과 불명이라 다음 전송이 같은 멱등 키를 쓴다 (0929/03-01) | `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` | `112c870` |
| [계약] | 인증 프로필 `REFERENCE_EXTERNAL_BEARER`의 새 이름은 `EXTERNAL_BEARER`다. 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남는다. `CREDENTIAL_HEADER_NAMES`에 짝 백엔드 CSRF 헤더 `x-xsrf-token`을 더했다 (1101/16-03, 1101/09-02) | `src/contracts/rest-profiles.ts` | `6c5818f`, `183a4a3` |
| [계약] | `zodValidator`(`src/contracts/zod-validator.ts`)가 zod 스키마를 `RuntimeValidator`로 바꾼다. 검증을 일부러 생략할 때는 `unvalidatedPayload(schemaId, reason)`를 쓴다. `listUnvalidatedPayloads(composed)`가 생략 목록을 만들어 플랫폼 구성 화면이 보여 준다 (1101/07-03) | `src/contracts/zod-validator.ts`, `src/contracts/unvalidated-payload.ts` | `d3ddc89`, `8b7c6eb` |
| [계약] | 폐기 별칭 `MappingResult`(`boundary-mapper.ts`)와 `ApiFailure`(`errors.ts`)는 export로 남지만 lint가 `src`·`tests`의 import를 막는다. `BoundaryMappingResult`, `AppFailure`로 바꾼다 (1101/07-01) | `eslint.config.ts`, `src/contracts/boundary-mapper.ts`, `src/contracts/errors.ts` | `fc303d8` |
#### 레지스트리
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | breaking 증거(`config/contracts/registry-change-evidence.json`)에 `after`가 필요하고 diff의 after 값과 같아야 한다. 지금 diff와 맞지 않는 증거 행은 `check:registries`가 적고 실패하며, `update:registry-baseline`이 그런 행을 지운다 (0929/07-01) | `scripts/lib/registry-compatibility.ts`, `scripts/update-registry-baseline.ts`, `docs/operations/ci-quality-gates.md` | `5e6be9a`, `4ada84e` |
| [계약] | 분류기가 덜 깐깐해졌다. 선언 타입 안의 null ↔ 값 전환은 `breakingFields`로 등급을 정하고(보통 behavior-change), `allowedValues`에 값을 더하기만 하면 additive다. 무효화 그래프에 원소를 더하기만 한 변경도 additive다. 빼거나 바꾸면 그대로 breaking이다 (0929/07-02) | `scripts/lib/registry-compatibility.ts`, `scripts/check-registries.ts` | `82c9e59`, `605fd17` |
| [계약] | FE-REG-ROUTE가 `paramsSchema`·`searchSchema`를 허용 목록으로 보지 않고, `loadingSurface`는 kebab-case 형식만 본다. 기능 라우트를 더해도 governance를 고치지 않는다. 다운스트림은 목록에 더해 둔 값을 지운다 (0929/07-03) | `config/contracts/registry-governance.json`, `scripts/check-registries.ts` | `e8d7fb4` |
| [계약] | `StorageBackend`에 `"external"`이 생겼다. cross-context pulse 키는 외부 소유라 StoragePort로 읽고 쓰면 `*_UNAVAILABLE`로 거절된다. exhaustive switch는 분기를 더한다 (1101/05-01) | `src/contracts/storage-keys.ts`, `config/contracts/` | `e98a980`, `65ea208` |
| [계약] | 진단 `ui.render.failed`의 `route_id`: 등록 라우트가 없는 URL의 적재 실패는 `NOT_FOUND` 대신 `UNREGISTERED_ROUTE`, 복구하지 못한 context 라우트 청크 실패는 context id 대신 그 라우트 id다. 이 값으로 거르는 대시보드·알림은 고친다 (1101 README 14.3) | `src/presentation/routes/`, `src/contracts/routes.ts` | `7c8cb19` |
#### 세션·인증
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 401은 그 요청의 자격증명을 낸 쪽에만 알린다. 템플릿 세션이 낸 자격증명의 401만 세션을 로그아웃시키고 캐시를 비운다. ANONYMOUS 요청과 제품 provider 요청의 401은 `ProductComposition.onCredentialRejected`(선택)로 간다 (1103/09-01) | `src/bootstrap/runtime-adapters.ts`, `src/bootstrap/product-composition-contract.ts` | `0aada28` |
| [계약] | 인증 프로필이 ANONYMOUS인 요청은 세션 상태와 상관없이 자격증명 없이 나간다. 전에는 어느 세션 상태에서도 보내지 않았다 (1101/09-01) | `src/bootstrap/runtime-adapters.ts` | `ddf411e` |
| [계약] | `ProductSessionOwnerContext`에 `fetch`(필수. 마감 `REQUEST_TIMEOUT_MS`, 본문 64 KiB, redirect 거부), `page`(`href`, `replaceUrl`, `assign`), `redirectStorage`, `readCookie`가 생겼다. 짝 백엔드 두 인증 모드의 owner recipe는 `recipes/session-owners/`(`oidc-pkce-session-owner.ts`, `cookie-session-owner.ts`)이고 매뉴얼은 `docs/manual/04-paired-backend-session.md`다. `src`가 이 recipe를 import하면 `check:optional-recipes`가 `PRODUCTION_IMPORTS_RECIPE`로 거절한다 (1103/09-03) | `src/bootstrap/product-composition-contract.ts`, `recipes/session-owners/`, `scripts/check-optional-recipes.ts` | `d02efe7`, `05958bb`, `f3fd10f` |
| [계약] | 세션 상태 전이: 복구 성공은 authenticated, no-session은 unauthenticated(또는 integration-failed), 거절은 상태 유지다. "세션 복구" 화면은 no-session이면 로그인 버튼을 보인다 (1103/09-11) | `src/adapters/auth/external-session-adapter.ts`, `src/presentation/providers/session-provider.tsx` | `d7c6cb4` |
| [계약] | `ProductComposition.scopeParticipants`(선택): 로그아웃·계정 전환 때 FENCED와 READY 사이에서 닫을 제품 자원. 닫기가 실패하면 READY로 가지 않는다. 예시는 `recipes/frontend-capabilities/browser-file-session-capability.ts` (1103/02-01) | `src/bootstrap/product-composition-contract.ts`, `src/bootstrap/runtime-adapters.ts`, `recipes/frontend-capabilities/` | `f485e51` |
#### 저장소·파일·전송
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | OPFS journal 목록이 손상 행을 건너뛰고 `corruptRows`로 센다. reconcile은 `corruptTransactions`, 소속 partition이 없는 손상 행은 선택 칸 `unattributedRows`·`unattributedCorruptTransactions`로 따로 세고 DEGRADED 관측에서 뺀다. 승인된 LOGOUT·ACCOUNT_DELETION purge는 끝나지 않은 행을 보면 진행 중인 put을 기다린 뒤 partition을 지우고 `partitionDeleted`를 보고한다. partition 삭제는 partition Web Lock으로 다른 탭의 put과 겹치지 않는다. `OpfsJournalPort`의 `countPartitionTransactions(scope)`·`removePartition`과 worker gateway `removePartition`은 필수 메서드다 (0929/05-01, 1103/05-01, 1103/05-03) | `src/adapters/storage/opfs/`, `src/application/ports/browser-file-storage/` | `72edb55`, `e5b7b3e`, `d13a393`, `fd6b631` |
| [계약] | OPFS partition lock을 기다리는 put·remove는 자기 abort로 `ABORTED`, `mutationLockWaitTimeoutMs`를 넘으면 `BLOCKED`(retryable)다. 정책의 `putIdleTimeoutMs`가 `mutationLockWaitTimeoutMs` 이상이면 조립이 거절한다 (1103/05-02, 0929/05-09) | `src/adapters/storage/opfs/` | `7b55f0f`, `f6b74ed` |
| [계약] **BREAKING** | recipe의 browser-file·OPFS·storage durability·cache 타입 중 `src`와 이름이 같은 34개는 `src` 타입을 다시 내보낸다. fake는 `src` port를 구현하고 `BrowserDataResult`를 돌려준다. `MemoryDurableObjectStore` 생성자가 바뀌었고 `DurableObjectDataClass`·`DurableObjectIntegrity`·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 지웠다. 이 fake의 reconcile은 `FILES_READY` put을 runtime처럼 commit하고 LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지운다. offline-indexeddb recipe를 쓰는 프로젝트만 해당 (0929/05-03, 1103/05-04) | `recipes/frontend-capabilities/` | `e1a4580`, `36ff633` |
| [계약] | `PublicCacheInspection.activePointer`가 필수 칸이다. 손상 pointer에서도 inspect가 상태와 후보를 보여 준다. 포트를 직접 구현한 쪽은 채운다 (1103/02-05) | `src/adapters/cache-storage/public-response-cache-adapter.ts`, `src/application/ports/browser-file-storage/cache-storage-ports.ts` | `7e7614f` |
| [보안] | download 정책의 `safeExtension`이 위험 확장자이거나 그것으로 끝나면 조립이 거절한다 (1101/02-02) | `src/adapters/browser-files/` | `4f78890` |
| [계약] | 업로드 part 발급·PUT이 서버의 `Retry-After`를 기다린다. `maxRetryAfterMs`를 넘으면 다시 보내지 않고 `upload()`·`abort()`가 `RESUME`·`retryable: false`를 준다. 실패 결과에 대기 시간이 붙도록 포트 반환 타입이 넓어졌다(추가만). upload 실패 번역은 HTTP 상태와 code로 recovery를 고르고, part 발급(BFF)의 401/403은 `NONE`(`retryable: false`)이다. file-transfer recipe를 쓰는 프로젝트만 해당 (1101/01-01, 1103/01-02, 0929/01-01) | `src/adapters/browser-transfer/` | `95e4445`, `c695898`, `9142390`, `c5f87aa` |
#### realtime·Service Worker·Web Push
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] **BREAKING** | `BoundedPollOperationContract`(V2 어휘)를 지웠다. `createBoundedPollCoordinator`의 operation과 `assertBoundedPollOperation`의 둘째 인자는 V3 descriptor(`BoundedPollOperation`)다. 조립된 행을 넘기고, `frontend.retryBudget` 0인 poll 전용 operation을 등록한다. 0이 아니면 생성 때 거절한다 (1103/04-01) | `src/adapters/realtime/` | `a65df74` |
| [계약] **BREAKING** | SSE의 fetch·reader 거절과 bounded poll의 execute 거절은 `OFFLINE` 대신 `PROVIDER_UNAVAILABLE`(retryable)로 끝난다. 브라우저가 online이면 online 이벤트를 기다리지 않고 backoff로 다시 시도하고 상한에서 끝난다. poll은 던지는 execute도 lease 안에서 다시 시도한다. `OFFLINE`은 환경 신호에서만 나온다 (1103/04-04, 0929/04-01) | `src/adapters/realtime/` | `af00067`, `4d27b20` |
| [계약] | stream coordinator와 live-poll handoff coordinator의 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`·`PROVIDER_UNAVAILABLE`로 나온다. stream coordinator의 `RealtimeObservation.reason`도 같다. `IDLE_TIMEOUT`은 전송 idle에만 쓴다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts`, `src/adapters/realtime/` | `1196b86`, `17fa8d1` |
| [계약] | realtime 배럴이 결과 생성 함수 `realtimeSuccess`·`realtimeFailure`를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) | `src/adapters/realtime/index.ts` | `3fe28de` |
| [계약] | Service Worker 빌드가 `public/`을 다시 복사하지 않는다(`publicDir: false`). 전에는 SW를 켠 빌드의 `dist/config.json`이 local 문서로 덮어써졌다 (0929/06-01) | `vite.service-worker.config.ts`, `scripts/build-frontend.ts` | `c7b9cb8` |
| [계약] | 라우터 base path(`VITE_ROUTER_BASE_PATH`)를 쓰면 Web Push 정상 클릭, SW 사전 캐시 URL, SW의 설정 URL이 모두 그 경로 아래로 간다 (1101/06-01, 0929/06-02) | `src/adapters/web-push/`, `scripts/generate-service-worker-assets.ts` | `c67edd2`, `85d55e0` |
| [보안] | Web Push registry가 URL로 해석하면 바뀌는 path(`..`, `%2e%2e`, `.`)를 생성 때 거절한다 (1103/06-02) | `src/adapters/web-push/` | `a145f30` |
#### 화면·문구·디자인 시스템
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | `check:design-system` 규칙 4개: 두 테마에서 `--color-focus`가 표면 토큰 8종 모두와 3:1 이상, `color-mix()`는 `in oklab`만, 계약의 컴포넌트 토큰은 스타일 하나 이상이 `var(--name)`으로 읽음, `--font-sans` 첫 글꼴은 기본 키워드이거나 `@font-face`로 싣는 글꼴이거나 `PRODUCT_LOADED_FONT_FAMILIES`(`token-contract.ts`)에 있는 글꼴. deg 색상각과 시스템 글꼴 이름은 받는다 (UI-01, UI-02, UI-03, UI-05, 1101/12-01, 1101/12-02, 1101/12-04) | `scripts/check-design-system.ts`, `scripts/lib/design-system-rules.ts`, `src/presentation/design-system/tokens/token-contract.ts` | `35b183b`, `bfa7dd9`, `165ed19`, `8576ce1`, `49d8675`, `e714c0d`, `b4ccada` |
| [계약] | design-system primitive가 `src/presentation/design-system/primitives/<컴포넌트>.tsx`로 나뉘었다. `design-system/index.ts`의 export 목록은 같다. 파일을 직접 import하던 코드는 경로를 바꾼다 (1101/08-08) | `src/presentation/design-system/primitives/`, `vite.config.ts` | `6dd4bc1`, `51941a5` |
| [계약] | `MessageArguments<Key>`가 catalog 문자열의 `{이름}`에서 파라미터를 만든다(값은 string 또는 number). `check:i18n`은 catalog parity와 raw backend 메시지만 보고, 화면 문구 literal은 ESLint `screenTextSelectors`가 잡는다(template literal·삼항식·객체 prop 문구는 못 본다) (0929/08-03, 0929/08-02) | `src/presentation/i18n/message-contract.ts`, `eslint.config.ts`, `scripts/check-i18n.ts` | `ff33d58`, `855d22a` |
#### 빌드·배포·CI
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 번들 예산 게이트 FE-GATE-012가 merge 단계에서 돈다. 예산은 gzip 204,800 B와 초기 파일 26개(`initialJsFiles`)다. `check:bundle`은 넘은 한도와 초과량을 적고, `bundle.json`에 `initialJsFiles`·`initialFilesPassed`가 있다. 초기 JS 기준선은 `config/scale/feature-shape-ceilings.json`의 `initialJavascript`(지금 202,927 B, 26개, 기능 하나 +768 B, context 하나 +233 B)이고 `test:unit`이 빌드와 대조한다 (1101/15-01, 1103/15-05, 1103/15-03, 1103/15-02, 1103/15-04) | `config/ci/gates.json`, `config/performance/budgets.json`, `scripts/check-bundle.ts`, `config/scale/` | `f41e3d5`, `46dfe23`, `1b8cb12`, `c9e7bab`, `f887817` |
| [계약] | 호스팅 계약: 파일이 없는 모든 경로에 그 release의 `index.html`을 HTML 헤더로 준다(SPA fallback, `appRoute`). 워커를 싣는 빌드의 `service-worker.js`는 `no-cache`다. live probe는 사전 캐시 확장자마다 `Content-Type`을 확인한다. nginx 예시는 `docs/operations/release-cache-rollback.md` (1101/13-04, 1103/06-03) | `config/hosting/cache-policy.json`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts` | `629c8f0`, `0f58abb` |
| [계약] | FE-GATE-019(production 단계)는 workflow의 `deployment` 슬롯이 배포한 승격 release를 본다. 슬롯이 비어 있으면 `UNVERIFIED`다. 배포된 `release-manifest.json`의 buildId·releaseId, `config.json`(비상 스위치 제외), `index.html` entry가 후보와 다르면 FAIL이다. TLS ALPN `h2`와 entry `Content-Encoding`(br·gzip·zstd)을 요구한다(`config/hosting/cache-policy.json`). HTTP/1.1이나 비압축 호스트는 FAIL이다. nginx 예시가 http2·gzip을 켠다 (1101/13-01, 1103/13-01, 1103/13-02) | `.gitea/workflows/quality-gates.yml`, `config/ci/gates.json`, `config/hosting/cache-policy.json`, `scripts/verify-hosting-headers.ts` | `de379ea`, `4bce8bf`, `2e12d2f` |
| [계약] | 제품 소유 `config/ci/product-gates.json`: 배포(`deployment`, package script와 `vars.*`·`secrets.*` 바인딩)와 제품 merge 검사(`PRODUCT-GATE-NNN`, job `product_merge_gate`). 템플릿은 승격 후보를 받아 `CANDIDATE_ARCHIVE_SHA256`으로 확인하고 푸는 단계를 만든다. 배포 슬롯은 `gates.json`이 아니라 여기서 채운다 (1103/12-07, 1103/13-01) | `config/ci/product-gates.json`, `scripts/contracts/product-ci-overlay.ts`, `scripts/generate-ci-workflow.ts` | `4c4248a`, `2e12d2f` |
| [보안] | 배포 슬롯의 `secrets.*`는 deploy 단계 env에만 간다 (1103/13-05) | `scripts/generate-ci-workflow.ts`, `scripts/contracts/ci-gates.ts` | `2e12d2f` |
| [계약] | staging·production 승인(FE-GATE-027)이 `example.com`·`example.net`·`example.org`와 그 하위 도메인, `.example`·`.invalid`·`.test` endpoint와 자리표시자 계약 신원(digest `PLACEHOLDER_CONTRACT_PACKAGE_DIGEST`)을 거절한다. `findAdmissionViolations`가 세 번째 인자로 계약 패키지를 받는다. CI에서 endpoint는 `config/runtime/<profile>.json`에 커밋한다 (1101/13-02, 1101/16-01) | `src/contracts/deployment-admission.ts`, `scripts/check-release-admission.ts` | `7b34756`, `1269992` |
| [보안] | release 단계 FE-GATE-027이 `scan:dependency-advisories`로 의존성 advisory를 템플릿 정책에 따라 판정해 남긴다(막지 않음). `renovate.json`을 더했다. 개발 의존성의 high·critical advisory를 범위 안에서 고쳤다(storybook 10.6.5, vite 8.1.6, vitest 4.1.12) (1103/13-03) | `scripts/scan-dependency-advisories.ts`, `renovate.json`, `package.json`, `pnpm-lock.yaml` | `eeb6f92`, `26ca2fd` |
| [보안] | provider 샌드박스가 `.git` 파일(worktree·서브모듈)을 `/dev/null` 읽기 전용 bind로 가린다. worktree에서도 `test:system`이 돈다 (1103/11-04) | `scripts/run-and-validate-provider.ts` | `0edc3fc` |
| [계약] | `create:feature <id> [--context <ctx>] [--with-create [--keyed]] [--package <name@version> --digest <sha256> --revision <hex>]`가 기능 뼈대를 만든다. 목록 경로는 짝 백엔드 `new-feature.sh`와 같은 `/<plural>`이고 결과 수는 `meta.page.total`이다. `--with-create`는 짝 백엔드 생성기와 같은 상세 GET·작성 POST(기본 `NEVER`, `--keyed`면 `KEYED`)·폼·결과 불명 화면·백엔드 본문 테스트를 더한다. FE-GATE-020의 `test:feature-scaffold`는 생성한 기능으로 `gates.json`의 merge 단계 명령을 돌고(브라우저 게이트·`test:system`·`verify:lockfile`·제거 드릴은 이유와 함께 뺀다) 그 기능의 제거 드릴도 돈다 (1101/16-01, 1103/03-07, 1103/09-06, 1103/12-02, 1103/16-02) | `scripts/create-feature.ts`, `scripts/create-feature-write-slice.ts`, `scripts/test-feature-scaffold.ts`, `config/ci/gates.json` | `d166aa3`, `2ec9d56`, `e1b4e28`, `7411d4a` |
| [계약] | `verify:documentation`(FE-GATE-017)이 입구 문서 4개의 src 최상위 폴더 설명과 `layers.md`의 아키텍처 규칙 이름을 검사한다(`sourceStructure`). `docs/README.md` 1절 현재 계약 문서의 repo 경로·명령 안 경로·링크·package script·FE-GATE ID와 짝 백엔드 참조를 검사한다(`documentReferences`, 짝 저장소가 옆에 없으면 `unverifiedLinks`). 수동 접근성 범위는 라우트별 기록 파일로 검사한다. 참조 기능 경로와 그 전용 script는 문서에 백틱 없이 적어, 참조 기능을 지워도 통과한다 (1101/14-03, 1101/14-05, 1103/12-05, 1103/14-04) | `scripts/verify-documentation-readiness.ts`, `docs/README.md`, `docs/manual/` | `61baf96`, `16202fd`, `b4e4f98`, `c4d5870`, `fd11d08` |
| [계약] | 규모 설계서는 `docs/architecture/scale-architecture.md`(현재 계약, 절 번호 유지)다. 코드 주석 `Spec §N`은 `scale-architecture.md §N`이고, 문서 이름 없는 `spec §` 참조는 `tests/unit/deletable-history-documents.test.ts`가 막는다. `docs/reviews/adapters/`는 지울 수 있는 기록이 아니다 (1101/14-01) | `docs/architecture/scale-architecture.md`, `README.md`, `docs/README.md` | `0a7fbed`, `b26517e` |
| [계약] | 쓰지 않는 npm script 4개(`scan:security:fixture`, `build:profile`, `generate:contract-set`, `build:app-only`)를 지웠다. 게이트가 닿지 않는 `scan:*` script는 `config/ci/ungated-scripts.json` 항목이 있어야 한다 (1101/12-05) | `package.json`, `scripts/lib/ungated-scripts.ts` | `98b9682` |
| [계약] | Vitest가 CI에서 skip·todo·only가 남은 실행을 실패시킨다(`-t`나 `file:line`으로 좁힌 실행은 제외). quarantine 주석이 붙은 skip도 실패한다 (1101/10-04) | `vitest.config.ts`, `tests/support/` | `95e7d11` |
| [계약] | 시각 테스트: `tests/visual/fonts.conf`로 글꼴을 고정하고 스크린샷 전에 실제 글꼴을 검사한다(Linux 전용). CI 브라우저 설치 단계가 글꼴 4종(`fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`)을 설치한다. 허용치는 절대 50 px다. 골든은 설치된 기능의 링크·목록·계약 다이제스트를 가리고 찍어, 기능을 더해도 다시 찍지 않는다 (1101/11-02, 1103/11-02, 1101/11-03, 1103/12-01) | `tests/visual/`, `playwright.visual.config.ts`, `.gitea/workflows/quality-gates.yml` | `08b5ccc`, `b0195e3`, `5ce3db9`, `0a6ff6e` |
| [계약] | 레시피 번들 예산: file-transfer 57,800, offline-indexeddb 38,500, realtime 42,200, service-worker-pwa 10,100 B. 측정값 + 3%를 100 B 단위로 올린 값이고, 3%를 넘는 증가는 커밋 본문에 이유를 적는다. 규칙은 `docs/architecture/optional-adapter-recipes.md` (0929/05-04) | `config/recipes/frontend-capability-recipes.json` | `313f9ba` |
### 그 밖의 수정
- 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음, `--font-sans`가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가 `--field-border`를 읽음 (UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, UI-08, 1101/12-01)
- 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서 `getByText`로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-01)
- 화면: 검색값만 바뀌면 포커스·스크롤·`route.changed`를 건드리지 않는다 (1101/08-02). h2·h3·h4 제목 크기·굵기 (1101/08-04), 한국어 단어 단위 줄바꿈 (1101/08-06), 상태 화면·오류 요약의 제목 수준 (1101/08-05), 예제 화면의 `lang="ko-KR"` (1101/08-07), 폼 저장 실패와 결과 불명 화면의 지원 참조 (0929/08-04)
- 폼: 짝 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등 20개)마다 문구가 있다. 모르는 code는 기본 문구다 (`8a09c90`, 1101 README 14.4). `constructor` 같은 필드 code는 기본 문구다 (1103/08-03). 키보드 저장이 결과 불명·429 등 필드 오류가 아닌 실패로 끝나면 포커스가 실패 상태로 간다(`FormPage` `feedbackId`, 저장 버튼 pending) (1103/08-02)
- 진단: context·feature 오류 경계와 라우트 모듈 실패가 진단에 남고 지원 참조가 `build:incident` 형식이다 (1101/09-09). 계약 조립 오류 메시지가 `reason`을 싣는다 (1103/09-07). 문제 응답 분류기 실패는 `CLASSIFIER_FAILED` (1101/03-05). 어느 무효화 topic도 닿지 않는 조회 namespace를 진단으로 한 번 알린다 (1101/03-01)
- 저장소: 진단 `storage.operation.failed`에 `reason`이 붙는다 (1101/05-02). lifecycle 리스너 주인 규칙과 테스트 (1101/05-03). OPFS purge가 객체를 못 지우면 완료와 chunk sweep을 보고하지 않는다 (0929/05-02). 여러 페이지를 다 지운 purge는 한 번에 끝났다고 보고한다 (`c4052f0`, 1101 README 13.6)
- 브라우저 파일·캐시: preview·download의 dispose가 자기 lease만 푼다 (1101/02-01). 같은 이미지 동시 resolve는 probe를 한 번만 돈다 (1101/01-04). 캐시 stage 재검증 실패는 `CACHE_STAGE` (1101/02-03), 정책 변경·손상 뒤에도 다음 배포가 pointer를 덮어쓴다 (0929/02-01), cross-context publish 실패 원인이 관측 reason에 실린다 (1101/02-05). Cache Storage 활성화의 본문 읽기 일시 오류는 손상이 아니라 `UNAVAILABLE`·`RETRY`다 (1103/02-02). browser-files vault에서 inspect 중에 놓은 ref는 `NOT_FOUND`·`RESELECT`다 (1103/02-04)
- 전송: 재조정에서 checkpoint 삭제가 실패해도 `upload()`가 `resourceId`를 준다 (0929/01-02). `FILE_BYTE_SOURCE` 이어 올리기는 수락된 part를 다시 해시하지 않는다 (1101/01-02). 짝 백엔드 Fileserver `POST /v1/files` 한 번 업로드 client `createFileserverUploadClient`(`src/adapters/http` 배럴, 201·202, 실패 Envelope, `Idempotency-Key`, `Retry-After`)를 더했다. 413·415·422 파일 거절은 `VALIDATION_REJECTED`, 같은 키 불일치 422는 공통 판정이다. presigned 업로드 레시피가 짝 백엔드와 맞지 않음을 문서에 적었다 (1103/01-01)
- 운영: 배포된 `config.json`의 비상 스위치(`CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`)를 바꾸기 전에 `check:release-admission --config <고친 사본> --original <배포된 원본>`으로 검사한다. 두 스위치 밖의 필드가 바뀌면 거절한다. 절차는 `docs/runbooks/FE-RB-001.md` (1101/13-05). 워커 스크립트 헤더 검사 범위 (1103/06-01), waiting 기간의 소유 캐시 누적 (1103/06-04), 워커 제거 1단계 유지 기간 (0929/06-06)을 운영 문서에 적었다
- realtime 문서: 짝 백엔드 실시간 출구와 프론트 transport 대응표 (1103/04-02), 레지스트리 세 바인딩의 출처 (1103/04-06), heartbeat를 멈춘 WebSocket (0929/04-04), Service Worker 레시피가 오프라인 셸을 약속하지 않음 (0929/06-03). WebSocket 구독별 초당 event 상한 (1101/04-03)과 워커 보호 장치 4개 (1101/06-04)를 테스트로 고정했다
- 빌드: react-dom과 scheduler를 자기 청크로 빼 build id만 바뀐 release의 캐시 손실을 줄였다 (1103/15-06). 운영 빌드가 react-router의 운영 빌드를 싣는다 (1103/15-07). 폐기 예정 `build.rollupOptions`를 `rolldownOptions`로 바꿨다 (0929/13-07). pnpm 설치 정책 키가 빠지거나 약해지면 테스트가 실패한다 (0929/13-08). README 변수 표에 `VITE_BUILD_ID`가 staging·production에서 필수임을 적었다 (0929/13-09). 갤러리 전용 primitive를 초기 청크에서 뺐다 (1101/08-08)
- 성능: 플랫폼 구성 화면이 제목과 선언 정보를 먼저 그리고 실행부 표만 나중에 채운다. lab 게이트 FE-GATE-026이 다시 통과한다. `PlatformOverviewPage`의 `contracts` prop은 Promise다 (1103/15-01). 성능 문서의 번들 기준선과 분류 규칙을 지금 빌드에 맞췄다 (1101/15-02, 1103/15-02)
- 레지스트리 도구: `check:registries`가 조립 실패의 `reason`을 적고, 읽지 못한 레지스트리를 지운 것으로 세지 않는다 (1103/14-06). FE-REG-SCHEMA 행의 `direction`·`unknownFieldPolicy`·`boundary`를 검증기·쓰임과 대조한다 (1103/07-03, 1103/16-04). 금지 조각이 든 런타임 설정 키를 `test:unit`이 이름과 함께 막는다 (1103/07-04). `check:feature-index` 예외 이유를 실제 사용처로 고쳤다 (1101/12-05)
- 아키텍처 검사: zod 하위 경로(`zod/v4` 등) import도 `src/contracts/zod.ts`를 거쳐야 한다 (`64f19ac`, 1103 07 영역 P-07-06). 금지 fixture를 그 계층의 운영 ESLint 설정으로 검사하고 fixture 전용 블록을 지웠다 (1103/12-04). adapter kernel 설명을 실제 `platform` 폴더 내용에 맞췄다 (`3f72ae7`). 두 오류 어휘(`AppFailure`·`AppError`)와 `commandRecovery`를 누가 읽는지 타입 옆에 적었다 (1101/07-05, 1101/07-07)
- 게이트·드릴: coverage 증거 검사(FE-GATE-005)가 istanbul summary의 `branchesTrue`를 받는다 (1103/12-09). compact smoke e2e가 빌드에 준 `VITE_BUILD_ID`를 기대해 CI 값에서 FE-GATE-008이 항상 실패하지 않는다 (1103/11-06). vitest와 dev server를 띄우는 Playwright 설정(capabilities, dev)이 CI의 `VITE_BUILD_ID`·`VITE_COMMIT_SHA`를 물려받지 않는다. 전에는 CI env에서 앱을 local-build fixture로 조립하는 테스트와 capability e2e가 `CONFIG_BUILD_MISMATCH`로 떨어져 FE-GATE-005·006·007·008·020이 항상 실패했다 (1103/11-07). capability 제거 드릴 3개가 문서 테스트 `ENOENT`로 항상 실패하던 것을 고쳤다. 문서를 읽는 테스트 목록은 `scripts/lib/removal-fixture.ts` 한 곳이다 (1103/02-06). `test:sample-removal`이 문서를 복사해 `lint`·`verify:documentation`·`check:i18n`·`check:design-system`을 돈다 (1103/14-04). 제품 기능 제거 드릴이 CI 기준선 사유 공백으로 멈추지 않는다 (1103/16-02). `test:system` provider 묶음 30초 예산 (1103/11-03), scope wrapper EOF 테스트 (1103/10-01)와 IndexedDB 차단 업그레이드 테스트 (1103/11-05)의 부하 원인을 없앴다. `artifacts/**/*.log`를 추적하지 않는다 (1103/12-08)
- 테스트: Testing Library 대기 기한을 `tests/setup.ts` 한 곳에서 5초로 정했다 (0929/10-01). `npx vitest`나 npm을 거친 IDE 실행기로 돌려도 실패하지 않는다 (1101/15-05). cgroup 시스템 테스트가 실행 단계가 남긴 PID·argv 기록을 읽는다 (1101/11-01). exact-five CLI 테스트가 실제 출력 문구를 기대한다 (0929/11-01). guardian이 실패하면 stdin을 기다리지 않고 끝난다 (`3c175a5`). 계약 조립기의 쓰기 API 규칙 5개 (1101/07-06), 이벤트 계약 검증 (1101/10-01), Envelope 판정 경계와 처리 중 409 무재전송 (1103/10-02), `MAX_RETRY_ATTEMPTS` 전달과 signal listener 정리 (1103/10-04)를 테스트로 고정했다. 규모 측정 기준선을 다시 쟀고 측정용 기능 복사본은 외부 패키지를 고정한다 (`9333595`, 1101/07-04). 설치 기능이 0개여도 타입 검사와 커버리지가 통과한다 (`e4ace51`, 1101/15-01)
- 테스트: 플랫폼 component 테스트가 스타터 화면 대신 테스트 전용 페이지(`tests/helpers/fixture-feature.tsx`)를 쓴다. 스타터 화면을 바꾸는 제품은 `tests/component/starter-*.test.tsx`를 함께 지운다. HTTP 시나리오 증거(FE-GATE-007)와 기능 API 타입 음성 fixture(FE-GATE-003)는 샘플을 지워도 남는다 (0929/10-02). 기능 테스트는 `createHttpScenarioHandler(<설치 계약>, { scenario, payload })`로 공유 MSW 시나리오를 쓰고, `tests/mocks/**`는 플랫폼 소유다 (1101/16-02, 1101/16-01). SW e2e가 제품이 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 접근성 e2e가 설치된 descriptor의 경로와 `responseEnvelope`로 빈 목록을 답하고 목록 화면에 경고 상자가 없음을 단언한다. 기능을 더해도 spec을 고치지 않는다 (1103/11-01, 1103/16-03)
- 참조 기능: 샘플 페이지가 `referenceRouteUrl(routeId, input)`으로 링크를 만들고 route 입력 cast를 없앴다. `REFERENCE_FEATURE_ROUTE_CODECS`는 `presentation/reference-route-codecs.ts`에 있다. 목록 링크 href는 `?limit=20`이 붙은 정식 URL이다 (1101/16-04). `create:feature --context reference-context`로 만들어도 참조 라우팅 테스트가 깨지지 않는다 (`e8c4197`)
- 문서: 새 기능 추가 매뉴얼 `docs/manual/`(한국어)을 더했다. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것을 적고, 결정표·기능 폴더 밖 파일·`create:feature` 인자·전역 ID·패턴·오류 메시지 참조를 둔다. 두 템플릿 공통 원칙은 design-docs repo `conventions/feature-design-principles.md`에 있다 (1101/16-01). 짝 백엔드 생성 기능의 쓰기 값 넷 결정표 (1103/16-07), 업무 거절 code를 `refusedBeforeWrite`에 적는 안내 (1103/03-01), 짝 백엔드 세션에 처음 붙이기 `docs/manual/04-paired-backend-session.md` (1103/09-03), 기능 실행부 설명 네 곳 (1103/09-10, 1103/07-05)
- 문서: 목표 설계 문서 VD-23·VD-24와 `api-contract-schema-mapper-and-server-state.md`의 V2 상태를 `REMOVED`로 바꾸고, VD-23의 401 문장을 정본 8.4("401 뒤 숨은 refresh-and-replay 없음")에 맞췄다. 쓰기 전 거절 표(계약 문서 6.1절)는 `docs/README.md` 1절이 링크해 경로 검사를 받는다 (1103/14-03). 정본 표가 제품 설정 키의 FE-REG-ENV 행을 요구하는 테스트를 적는다 (1103/14-05). `PRODUCT.md`를 더하고 예제 제거 주장을 드릴 범위에 맞췄다 (1101/14-04). 리뷰 ID에 라운드를 붙인다 (1101/14-02). `verify:documentation`이 실패하면 실패한 검사 이름과 고칠 문서·빠진 route ID를 적는다 (1101/14-06)
### 알려진 제한
이 절을 쓴 끝 커밋(`f887817`)에서 사실인 것만 적었다.
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento-web의 숫자(descriptor 29개, schemaId 42개 + `MementoProblem`)는 memento `d3810a0`을 정적으로 센 값이다.
- 직접 조립 제품(tech-log의 TechLog): 템플릿에 그 자리가 없다. 기능 모듈로 바꾸는 길은 fixture(`tests/helpers/fixture-layout-product.tsx`)로만 검사했고 TechLog 화면으로는 해 보지 않았다. 직접 조립을 유지하면 FE-REG-API·FE-REG-SCHEMA와 스키마 메타 대조 테스트가 TechLog descriptor를 보지 않는다.
- 제품 안에 적은 계약(memento `PRODUCT_LOCAL_CONTRACT`)에 줄 출처 종류가 없다. `EXTERNAL_PACKAGE` 신원을 어떻게 정할지(패키지 없이 digest를 붙이는 법)는 템플릿이 정하지 않았다.
- 참조 기능은 `responseEnvelope`를 선언하지 않아 DTO와 problem details만 읽는다. 짝 백엔드에 붙는 완성 예시는 `create:feature --with-create`가 만드는 기능이다.
- 짝 백엔드 생성기(`new-feature.sh`)에 목록 GET이 없다. `create:feature` 목록 화면은 백엔드가 `GET /<plural>`을 더한 뒤에야 닿는다 (1103/03-07).
- 짝 백엔드 계약 pin은 `45d2a478`(2026-11-05)이다. 그 뒤 백엔드가 바뀌면 `check:backend-contract-drift --backend <백엔드 checkout>`가 알린다. 이 검사는 게이트 밖이라 CI는 알리지 않는다.
- 업로드: 백엔드 `POST /v1/files`는 `Idempotency-Key`를 읽지 않는다. 결과 불명 뒤 같은 키로 다시 보내도 파일이 둘 생길 수 있다. client의 code 목록은 백엔드 기준점에 묶여 있다. `EXTERNAL_BEARER`로 올리려면 제품 provider가 필요하다. 실제 백엔드 업로드와 firefox·webkit은 돌리지 않았다.
- 세션 owner recipe는 실제 Keycloak·Redis와 붙여 보지 않았다. jwt 모드: 백엔드 realm에 브라우저용 public client가 없어 제품이 더한다(매뉴얼 04에 JSON). redis-session 모드: 백엔드 운영 코드에 로그인·로그아웃·세션 조회·CSRF 발급 엔드포인트가 없어 owner가 URL을 기본값 없이 받는다. OIDC owner는 토큰을 메모리에 두어 새로고침하면 로그아웃되고, ID token 서명을 검사하지 않는다.
- 플랫폼 구성 화면(`EXAMPLES_PLATFORM`, `/examples/platform`)은 플랫폼 라우트라 끌 수 없고 FE-GATE-028 서명 대상이다. 예제 기능을 뺀 제품에서 예제 화면을 여는 e2e·visual spec은 실패한다 (1103/09-04).
- 기능 라우트 첫 진입(실행부 청크, 약 430 ms)은 어느 게이트도 재지 않는다.
- 초기 JS 여유가 1,873 B다. `--with-create` 기능 하나(약 +964 B)를 넣으면 약 900 B가 남는다.
- 운영 의존성 high advisory 2건이 남았다: `zod` 4.4.3 GHSA-mrhx-c7xc-m3w5(고치는 버전은 초기 JS 약 +7 KB로 예산을 넘는다), `react-router` 7.18.1 GHSA-qwww-vcr4-c8h2(약 +470 B). 둘 다 owner와 다른 reviewer의 `config/security/dependency-change-evidence.json` 항목이 필요하다. moderate 2건(`minimatch`, `glob`)은 major 범위 밖이다.
- 실제 Gitea runner, 실제 HTTPS 호스트, nginx 예시에서는 돌리지 않았다. FE-GATE-019 배포 슬롯은 주입한 fetcher로만 시험했다.
- `test:feature-scaffold` 한 번이 513~866초 걸린다(부하에 따라). FE-GATE-020 job 상한은 45분이다. 브라우저 게이트는 scaffold 드릴 밖이다. 짝 저장소 참조(1103/12-05)는 CI와 중첩 worktree에서 `not verified`다.
- Service Worker를 켠 제품의 `composeProduct` 쪽 칸(SW blocker·observe)은 없다 (1103/09-05). SW e2e와 실제 live probe는 이 묶음에서 돌리지 않았다.
- OPFS: `logicalKey`까지 깨진 행은 staging에 남을 틈이 있고, 같은 lock 대기 상한이 partition 삭제에도 걸린다. `dispose()`는 `scopeParticipants`를 부르지 않는다. 실제 로그아웃 E2E는 없다.
- 라우트 계약의 `title`·`navigationLabel`은 화면이 읽지 않는다(catalog가 읽는다) (1103/16-06). 키보드 저장 실패 포커스는 스크린리더로 확인하지 않았다 (1103/08-02).
## 0.2.0 — 태그 `v0.2.0` (2026-09-27)
2026-09-25 성숙도 리뷰(`docs/reviews/2026-09-25-maturity-review/`) 수정 묶음이다.
기준은 `main` `4626b73`이다. `package.json`의 `version`은 `0.2.0`이다.
### 보안·계약 변경
먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 `x-correlation-id` 헤더를 하나 보낸다. 다른 origin API는 preflight `Access-Control-Allow-Headers`에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 `Access-Control-Expose-Headers`에도 넣는다 (0925/03-03) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts`, `src/bootstrap/runtime-adapters.ts`, `docs/operations/api-contract-and-server-state-recovery.md` | `c5da3cf`, `f0a6495` |
| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (0925/03-01, 0925/08-03) | `src/presentation/adapters/query/application-query.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/components/async-surface.tsx` | `dfb1b9e` |
| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(`classifyStatus`, 선택 필드). 재로그인이 먼저다 (0925/03-02) | `src/adapters/http/http-effect-certainty.ts`, `src/adapters/http/http-execution-v3.ts`, `src/contracts/errors.ts`, `src/contracts/external-contract-runtime.ts` | `2afee67` |
| [계약] | 422 problem body의 필드 오류(`path`, `code`)를 폼까지 전달한다 (0925/03-04) | `src/adapters/http/feature-http-binding.ts`, `src/features/reference-feature/contracts/reference-schemas.ts` | `479acd5` |
| [계약] | 텔레메트리 수집기 이벤트마다 `build_id`, `release_id`가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (0925/13-11, 0925/03-05) | `src/adapters/telemetry/telemetry-collector.ts`, `src/bootstrap/runtime-adapters.ts` | `43e47f4`, `e14c613` |
| [보안] | 번들이 읽지 않는 `VITE_*` 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, `ENV_REGISTRY`에 없는 `VITE_*` 이름은 빌드를 멈춘다 (0925/13-06) | `src/contracts/env.ts`, `vite.config.ts`, `eslint.config.ts` | `2ec59ad` |
| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (0925/05-03, 0925/05-04) | `src/adapters/platform/indexeddb-connection.ts`, `src/adapters/storage/indexeddb/indexeddb-runtime.ts`, `src/adapters/storage/opfs/opfs-byte-store-adapter.ts`, `src/application/ports/browser-file-storage/` | `3e37fbf`, `6ab564f` |
| [계약] | `RELEASE_TARGET`이 `APP_PROFILE`과 다르면 배포 승인이 거절된다 (0925/12-02, 0925/13-01) | `scripts/check-release-admission.ts`, `.gitea/workflows/quality-gates.yml` | `239b22a` |
| [계약] | 설정·매니페스트 URL이 `VITE_ROUTER_BASE_PATH`를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (0925/13-07) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts`, `vite.config.ts` | `e215c84` |
| [계약] | `VITE_PRODUCT_FEATURES`는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (0925/09-02) | `scripts/generate-product-feature-index.ts`, `src/contracts/product-features.ts` | `a8111f7` |
| [계약] | `src/features/<id>/`에 `feature-module.ts`도 `NOT_INSTALLED` 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 `--feature=<id>`를 받는다 (0925/09-07, 0925/14-03) | `scripts/generate-product-feature-index.ts`, `scripts/test-sample-removal.ts`, `config/contracts/registry-governance.json`, `docs/architecture/starter-experience.md` | `ad0e83c` |
| [계약] | 기능 루트·context·app 파일은 `src/adapters`를 import할 수 없다. presentation은 app·context를 import할 수 없다(`app-router.tsx` 예외) (0925/12-03) | `scripts/check-architecture.ts`, `.dependency-cruiser.json`, `docs/architecture/layers.md` | `f8b6a36` |
| [계약] | CI 계약의 게이트 수·해시가 `config/ci/contract-baseline.json`으로 옮겨졌다. 게이트를 바꾸면 `update:ci-contract-baseline`로 갱신한다 (0925/14-02) | `config/ci/contract-baseline.json`, `scripts/check-ci-contract.ts` | `0114b1e` |
| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 `config/ci/ungated-tests.json`에 이유가 있어야 한다 (0925/12-04, 0925/09-11, 0925/11-03) | `config/ci/gates.json`, `config/ci/ungated-tests.json`, `scripts/lib/ungated-tests.ts` | `840de45`, `45ee231` |
| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 `UNVERIFIED`(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (0925/08-06, 0925/11-01, 0925/13-03, 0925/13-05) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/drill-runbook.ts`, `docs/operations/ci-quality-gates.md` | `7298275`, `7f889a6`, `a263d8c` |
| [계약] | `engineStrict`, `saveExact`를 `pnpm-workspace.yaml`로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (0925/13-09) | `pnpm-workspace.yaml`, `.npmrc` | `a5dc851` |
| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (0925/08-01) | `src/presentation/forms/form-contracts.ts`, `src/presentation/forms/use-app-form.ts`, `src/presentation/forms/form-components.tsx` | `9894a70` |
| [계약] | browser-transfer 포트: `upload()` 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 `resourceId`를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (0925/01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-transfer/`, `src/adapters/browser-transfer/` | `648fe4e`, `7b2cefb`, `5a6665a`, `426b6b8` 외 |
| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 `INCOMPATIBLE`, 빈 receipt는 없음으로 본다 (0925/05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 | `src/application/ports/browser-file-storage/`, `src/adapters/storage/` | `7f45afa`, `47cf040`, `8fc816e` 외 |
| [계약] | 외부 세션 owner의 `readSubject()`와 `SessionGateway.getSubject()`가 필수가 됐다. `readSubject`가 없는 owner는 `integration-failed`로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 | `src/adapters/auth/external-session-adapter.ts`, `src/application/ports/`, `docs/architecture/starter-experience.md` | `c6300e9` |
| [보안] | 운영 CSP(`unsafe-eval` 없음) 아래에서 zod가 eval을 시험하지 않는다. `src/`의 코드는 zod를 `src/contracts/zod.ts`로만 가져온다(dependency-cruiser 규칙) (0925/13-08, 0925/F-7) | `src/contracts/zod.ts`, `.dependency-cruiser.json`, `tests/e2e/production-csp.spec.ts` | `9dc95ca` |
| [계약] | 설정 스키마 호환성 분류기(`classifyObjectSchemaChange`)가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014, `verify:compatibility`). 레지스트리 분류기(`scripts/lib/registry-compatibility.ts`)와는 다른 것이다 (0925/07-02, 0925/13-10) | `src/contracts/compatibility.ts`, `scripts/check-compatibility.ts`, `config/compatibility/` | `17d617a` |
| [계약] | 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 `@deprecated`와 제거 조건을 붙였다 (0925/07-04, 0925/07-07) | `src/contracts/errors.ts`, `src/contracts/` | `aff5f43`, `9e616d3` |
| [계약] | staging·production 빌드는 `VITE_BUILD_ID`가 없으면 실패한다 (0925/13-15, 0925/F-6) | `scripts/generate-runtime-config.ts`, `src/contracts/env.ts` | `063375e` |
| [계약] | Service Worker 빌드가 `public/config.json` 대신 프로필에서 만든 `dist/config.json`을 읽고, `APP_ENV`가 `APP_PROFILE`과 다르면 빌드를 멈춘다 (0925/06-10, 0925/F-8) | `vite.service-worker.config.ts`, `scripts/lib/service-worker-build-input.ts` | `cefb0b2` |
| [계약] | Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. `REMOVE_REGISTRATION`은 스스로 등록을 해지하는 worker를 배포한다 (0925/06-02, 0925/06-06, 0925/06-03) | `src/adapters/web-push/`, `scripts/lib/self-unregistering-service-worker.ts`, `docs/runbooks/` | `e6c683e`, `996a959`, `9f2305a` |
| [계약] | realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE `Retry-After`를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (0925/04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 | `src/adapters/realtime/`, `config/recipes/frontend-capability-recipes.json` | `bcad7b0`, `02d3fdf`, `7e37660`, `2c5e268` 외 |
| [계약] | browser-files 포트: 같은 턴의 abort는 `ABORTED`, 닫은 선택 창은 `DISMISSED`, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (0925/02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 | `src/adapters/browser-file-storage/`, `src/adapters/cache-storage/` | `c9be8d6`, `d76653b`, `0b41cb3`, `55c0bf5` 외 |
| [계약] | 샘플 상세 경로가 `/examples/reference-resources/items/:resourceId`로 옮겨졌다. ID가 `new`·`status`인 항목도 상세가 열린다 (0925/08-13) | `src/features/reference-feature/contracts/reference-feature-contract.ts`, `config/contracts/registry-change-evidence.json` | `d7b81c6` |
| [계약] | `tsconfig.base.json`에 `noUnusedLocals`를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 `check:types`에서 실패한다 (0925/12-12) | `tsconfig.base.json` | `49413af` |
### 그 밖의 수정
- 부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (0925/09-03, 0925/09-04, 0925/09-10). `src/bootstrap/`, `src/presentation/boundaries/boot-error-shell.tsx`
- 부트: `FEATURE_OVERRIDES`의 모르는 키를 진단으로 남긴다 (0925/09-09). `src/bootstrap/runtime-adapters.ts`, `scripts/check-release-admission.ts`
- 빌드: `dist` 파일을 다른 사용자도 읽을 수 있게 한다 (0925/13-02). `scripts/lib/dist-permissions.ts`
- 공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (0925/13-12, 0925/13-04). `scripts/lib/vite-module-inventory.ts`, `scripts/verify-exact-promotion-bundle.ts`
- 아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (0925/12-05~12-11). `scripts/check-architecture.ts`
- 기능 조립: `needs` 검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (0925/09-01, 0925/09-05, 0925/09-06, 0925/09-08, 0925/09-12, 0925/00-02). `src/features/`, `src/bootstrap/runtime-adapters.ts`
- 테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (0925/13-08, 0925/01-04, 0925/05-08, 0925/10-03)
- 샘플 제거: `test:sample-removal`이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (0925/14-01, 0925/14-08, 0925/00-01, 0925/10-01). `scripts/test-sample-removal.ts`, `scripts/lib/removal-fixture.ts`
- 문서: README에 런타임 프로필·배포 변수·우선순위를 적고 `verify:documentation`이 변수 목록을 검사한다 (0925/13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (0925/13-13, 0925/13-14, 0925/03-06, 0925/03-08).
- 화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (0925/07-01, 0925/08-02, 0925/08-04, 0925/08-07~08-12, 0925/F-10). `src/presentation/`, `src/presentation/i18n/`
- 접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (0925/08-05, 0925/11-02). `tests/e2e/accessibility.spec.ts`
- 계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (0925/07-03, 0925/07-05, 0925/07-06, 0925/09-07, 0925/F-3). `tests/unit/`, `src/contracts/`
- Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (0925/06-01, 0925/06-04, 0925/06-05, 0925/06-07~06-09). `src/adapters/web-push/`, `src/adapters/service-worker/`, `src/bootstrap/`
- 테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (0925/10-02, 0925/10-04~10-07, 0925/11-04~11-08, 0925/F-2). `tests/`, `scripts/scale/`, `scripts/lib/lab-performance.ts`
- 테스트 fixture가 공유 `node_modules`를 다시 쓰지 않고, 임시 폴더를 지운다 (0925/F-4, 0925/F-12, 0925/00-03). `scripts/lib/removal-fixture.ts`, `tests/unit/`
- 문서: 손으로 적은 게이트 수와 LOC를 지우고 `verify:documentation`의 검사 범위를 적었다 (0925/14-07)
### 알려진 제한
- Playwright spec은 chromium·firefox·webkit에서 확인했다. WebKit에서만 난 실패 1건(구 탭 청크 복구 spec의 콘솔 문구 허용 목록)은 `b1a36ab`로 고쳤다.
- 사용자 몫(SPEC "범위 밖" U-1~U-5, 0925/F-11)은 이 버전에 들어 있지 않다.
## 0.1.0 — `main` `4626b73` (2026-09-24)
태그가 없는 `main`이고 `package.json` 버전은 `0.1.0`이다. 이 커밋보다 앞에서 복사한 프로젝트는 아래 보안 수정부터 확인한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [보안] | 자격증명 헤더 값은 제어 문자가 없는 ByteString만 받는다. 대소문자만 다른 헤더 이름은 거절한다 (R-3.4) | `src/adapters/http/http-contract-bridge.ts`, `src/adapters/auth/external-session-adapter.ts` | `5e62b7e` |
| [보안] | REST v2 COMMAND는 POST/PUT/PATCH/DELETE만 쓴다. GET으로 선언된 명령이 CSRF 보호 없이 나가던 문제다 (R-7.4) | `src/contracts/api-operations.ts` | `f26fd18` |
| [보안] | 텔레메트리 리댁션이 문자열 중간의 토큰, URL 비밀 파라미터, 이메일을 가린다 (R-9.3) | `src/platform/telemetry/redact-telemetry.ts` | `4e0745c` |