From 44aa44dbc50caa12795b7bcb16730d28b03834d8 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Thu, 5 Nov 2026 00:21:49 +0900 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=EB=AF=B8=EC=B6=9C=EC=8B=9C?= =?UTF-8?q?=20=EC=A0=88=EC=9D=84=20=EB=8F=99=EA=B8=B0=ED=99=94=20=EB=8B=A8?= =?UTF-8?q?=EC=9C=84=EC=9D=98=20=EC=88=9C=20=EB=B3=80=EA=B2=BD=20=EC=9A=94?= =?UTF-8?q?=EC=95=BD=EC=9C=BC=EB=A1=9C=20=EB=8B=A4=EC=8B=9C=20=EC=93=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 미출시 절은 fix/ui-design-audit-2026-11-01 한 브랜치의 누적 기록이었다. - 같은 묶음에 들어온 그 브랜치 뒤 16커밋(ece944d d0414c8 7d85589 7c8cb19 17fa8d1 27f4523 8a09c90 e5b7b3e 등)과 2026-11-03 조치 11개 브랜치가 없다. - V2를 고친 행과 V2를 지운 행이 함께 있고, 알려진 제한 13줄 중 대부분이 이미 고쳐졌다. - BREAKING 이행 안내가 "memento-web이 V2 API 행을 쓴다"고 적었다. memento-web의 apiOperations는 비어 있고, 실제 작업은 descriptor 29개의 FE-REG-API 행, 스키마 행 43개, zod가 아닌 검증기다. tech-log의 직접 조립 경로는 안내가 없었다. - 0.2.0의 17d617a 행이 설정 스키마 분류기를 "레지스트리 호환성 분류기"라고 부르고, 그 커밋이 고치지 않은 scripts/check-registries.ts를 적는다. 고른 방법 - 결정 D5 (b): 752a61f → fix/maturity-review-2026-11-03 범위를 한 동기화 단위로 보고 최종 상태만 적는다. 머리에 범위·세 갈래·읽는 법, 이어서 "먼저 할 일 (BREAKING)"을 옮기기 전 / 옮기는 법 / 옮긴 뒤 확인 순서로, 그 뒤 영역별 [보안]·[계약] 표, 그 밖의 수정, f887817에서 사실인 알려진 제한을 둔다. 뒤 커밋이 바꾼 중간 상태 행(V2 Envelope·V2 거절·V2/V3 대조, REST 보안 프로필 메시지, 초기 청크 16→25개 등)은 최종 행에 합치거나 지웠다. - 14-02: 두 다운스트림(memento d3810a0, tech-log 7a4e201a)을 읽고 단계마다 실제 모양을 적었다. memento: PRODUCT_LOCAL_CONTRACT 출처, ownsShell·APP_HOME 다리, SW ACTIVE 선택, 손으로 쓴 검증기. tech-log: NOT_INSTALLED 직접 조립과 기능 모듈로 바꾸는 길(fixture-layout-product 모양). - 리뷰 P-07-07은 경로를 scripts/lib/registry-compatibility.ts로 바꾸라고 했지만, 17d617a가 고친 것은 src/contracts/compatibility.ts(FE-GATE-014)다. 경로를 바꾸면 틀린다. 그래서 이름을 "설정 스키마 호환성 분류기"로, 둘째 경로를 scripts/check-compatibility.ts로 고쳤다. - 머리 규칙에 미출시 절이 동기화 단위 순 요약이라는 줄을 더했다. - 버린 대안: 브랜치별 누적 기록을 유지하고 빠진 행만 더하기(14-01 (a)). 다운스트림이 서로 뒤집는 행을 직접 걸러야 한다. 커밋 trailer 검사 (14-01 (c))는 이번에 넣지 않았다. 위험·한계 - 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento 숫자는 정적 집계다. 알려진 제한에 적었다. - 끝 커밋은 f887817 기준이다. 이 브랜치를 합친 뒤 끝이 바뀌어도 해시 규칙 (범위 안)은 그대로다. - 짝 백엔드가 pin c508b1ba 뒤로 바뀐 것(HEAD 45d2a478, §2 두 행 설명)을 알려진 제한에 적었다. pin은 올리지 않았다. 검증 - 미출시 절의 이 repo 해시 148개: 모두 f887817에서 닿고 752a61f에서 닿지 않는다(merge-base --is-ancestor 스크립트). 나머지는 기준점 2개와 다른 repo 커밋 4개. - vitest changelog-review-ids, documentation-readiness 20건 통과. - verify:documentation PASS_SCOPED, check:types, lint 통과. - 인증 프로필 오타 변이(참조 기능): check:registries가 reason과 함께 실패, check:types·check:architecture·verify:documentation 통과를 확인했다. Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-01 Refs: docs/reviews/2026-11-03-maturity-review/14-template-product-docs.md 14-02 Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md P-07-07 --- CHANGELOG.md | 357 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 246 insertions(+), 111 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 266b3b11..e988776e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,140 +4,275 @@ 가져오는 방법은 `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'`). +- 0.2.0의 커밋 해시는 브랜치 `fix/maturity-review-2026-09-25`에서 만들었고, `main`에서도 같은 해시로 찾을 수 있다(2026-11-03에 52개 모두 확인). 그 뒤 절은 절 머리에 범위(기준 커밋과 브랜치)를 적고, 그 절의 해시는 모두 그 범위에 있다. 0.2.0의 커밋 제목은 라운드 없이 ID만 적었다(`git log --grep '03-03'`). -## 미출시 — 브랜치 `fix/ui-design-audit-2026-11-01` +## 미출시 — `752a61f` → 브랜치 `fix/maturity-review-2026-11-03` -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/`) 수정 묶음이다. -기준은 `main` `752a61f`이다. 버전 번호와 태그는 아직 정하지 않았다. 커밋 해시는 이 브랜치 기준이다. +한 번의 동기화로 받는 변경의 순 요약이다. 범위는 `main` `752a61f`부터 브랜치 `fix/maturity-review-2026-11-03`의 끝까지다. 이 절을 쓸 때 끝은 `f887817`이었다(병합 커밋을 빼고 310개). 버전 번호와 태그는 아직 정하지 않았다. -### 먼저 할 일 — 기능 모양 변경 (BREAKING, 1101/15-01) +이 묶음은 세 갈래를 합쳤다. -`298201f`. 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서, 참조 모양 기능 하나만 더해도 초기 JS 예산(204,800 B)을 넘었다. 그래서 기능을 두 부분으로 나눴다. +- `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`에서 합쳤다. -- **선언**(`feature-module.ts`, `FeatureModule`): 초기 청크에 남는다. `id`, `contracts`(route 표, route runtime 계약, invalidation, topic version, 새 `contractPackages`), `routes`, `messages`, `loadRuntime`만 가진다. -- **실행부**(`feature-runtime.ts`, `defineFeatureRuntime`): 그 기능의 route에 처음 들어갈 때 router가 `application.features.load(featureId)`로 적재한다. 스키마 메타데이터(`schemas`), adapter contribution, contract contribution을 가진다. HTTP operation은 contract contribution에만 적는다(아래 V2 API 행 삭제 행). -- route codec은 `context-routes.ts`의 route handle(`handle.codecs`)에 실려 route와 함께 적재된다. `*-runtime-descriptor.ts`와 `src/features/installed-feature-runtimes.tsx`는 없어졌다. +읽는 법: -기존 기능을 옮기는 순서(`src/features/reference-feature/`가 완성된 모양이다): +- 최종 상태만 적는다. 같은 범위 안에서 뒤 커밋이 다시 바꾼 중간 상태는 적지 않는다. 예를 들어 V2 클라이언트를 고친 커밋들은 V2를 지운 행 하나로 남겼다. 중간 기록은 커밋 이력에 있다. +- 이 repo의 커밋 해시는 기준점 `752a61f`·`af3d8e6`을 빼면 모두 이 범위에 있다. 브랜치 끝에서 닿고 `752a61f`에서는 닿지 않는다. 다른 repo의 커밋(다운스트림, 짝 백엔드)은 repo 이름과 함께 적었다. +- 두 다운스트림(tech-log-frontend, memento-frontend)의 기준점은 `af3d8e6`이다. `af3d8e6`과 `752a61f` 사이에는 리뷰 문서만 있다. 그래서 두 제품이 받을 변경은 이 절과 같다. -1. 기능 계약에서 스키마 메타데이터(`schemas`)를 별도 파일로 뺀다. 참조: `contracts/reference-schema-metadata.ts`의 `REFERENCE_SCHEMA_METADATA`. V2 API 필드(`apiOperations`, `runtimeSchemas`, `mappers`)는 지운다. -2. 선언 계약에 `contractPackages`를 더한다. 그 기능의 `EXTERNAL_PACKAGE` contribution이 고정하는 계약 패키지 identity 목록이다. 없으면 `Object.freeze([])`. 부팅 때 release manifest를 이 목록과 맞춰 본다. 선언하지 않은 패키지를 적재하면 거절한다(`src/features/installed-contract-contributions.ts`). -3. `src/features//feature-runtime.ts`를 만든다. `defineFeatureRuntime({ featureId, schemas, adapters: [...], contractContributions: [...] })`. 참조: `src/features/reference-feature/feature-runtime.ts`. `featureId`가 모듈 id와 다르면 적재 때 실패한다. -4. `feature-module.ts`에서 `adapters`, `contractContributions`, `runtimes`(route codec·route runtime)를 지우고 `loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME`을 넣는다. `feature-runtime.ts`를 어디서도 정적으로 import하지 않는다. 그러면 실행부 전체가 다시 초기 청크에 들어간다. -5. route codec을 runtime descriptor에서 `context-routes.ts`의 각 route `handle.codecs`로 옮긴다. 참조: `REFERENCE_FEATURE_ROUTE_CODECS`(`presentation/reference-feature-runtime.ts`). 플랫폼 codec과 같은 id는 쓸 수 없다. -6. 기능 input(`application.features.get(id)`)은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저 `await application.features.load(id)`를 부른다. `ApplicationApi.features`를 직접 구현하거나 fake로 만든 코드는 `load`를 더한다(공개 포트에 추가만 했다). 런타임 설정으로 꺼진 기능은 적재하지 않는다. -7. 모든 기능의 실행부가 필요한 화면은 `loadInstalledFeatureRuntimeRegistries()`(async, `src/features/installed-feature-runtime-registries.ts`)를 부른다. Node 스크립트와 테스트는 `src/features/loaded-feature-runtimes.ts`를 읽는다. `src/`에서 이 파일을 import하면 새 아키텍처 규칙 `boot-does-not-load-every-feature-runtime`이 막는다. -8. `vite.config.ts`의 청크 그룹 두 개(`feature-declarations`, `feature-platform`)를 가져간다. 없으면 기능마다 선언 청크가 하나씩 는다(기능당 약 +1.5 KB). -9. `check:architecture`, `check:types`, `test:sample-removal -- --feature=`, `tests/unit/feature-shape-growth.test.ts`(기능 하나 1 KiB 이하)를 돌린다. +### 먼저 할 일 (BREAKING) -수치(`298201f` 측정): 템플릿 초기 JS 203,572 → 202,361 B. 참조 모양 기능 하나 +3,922 → +741 B. 예산 안에 참조 모양 기능이 약 3개 더 들어간다. 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 기능 계약끼리의 중복 검사는 부팅이 아니라 그 기능의 적재 시점과 Node 검사로 옮겨 갔다. +복사한 프로젝트가 이 묶음을 받을 때 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림에서 읽은 모양(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//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와 `
` 하나를 그린다. `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: `이다. + - 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()`로 받을 수 있고, 그러면 오타를 타입 검사가 잡는다. `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..requestSchema references unknown FE-REG-SCHEMA.schemaId=`로 실패한다. + - 행의 칸: `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= 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이다. ### 보안·계약 변경 +#### 기능 구조와 조립 + | 표시 | 변경 | 영향 경로 | 커밋 | |---|---|---|---| -| [계약] | 기능 모양 변경. 위 "먼저 할 일" 절을 본다. `ApplicationApi.features`에 `load(featureId)`가 생겼다 (1101/15-01) | `src/features/`, `src/application/ports/in/application-api.ts`, `src/presentation/routes/`, `vite.config.ts`, `.dependency-cruiser.json` | `298201f` | -| [계약] | 번들 예산 게이트 FE-GATE-012가 release 단계에서 merge 단계로 옮겼다. 초기 JS를 예산보다 키우는 PR이 merge 게이트에서 실패한다 (1101/15-01) | `config/ci/gates.json`, `.gitea/workflows/quality-gates.yml`, `scripts/lib/promotion-readiness.ts` | `f41e3d5` | -| [계약] | 참조 기능의 생성 분류기가 409를 problem code로 나눈다. 선언한 충돌 code(`CONFLICT`)만 적용 안 됨이고, `IDEMPOTENT_IN_FLIGHT`·code 없는 409·모르는 409는 결과 불명이라 다음 전송이 같은 멱등 키를 쓴다. 백엔드는 같은 키의 처리 중 재전송에 409 `IDEMPOTENT_IN_FLIGHT`를 주고, 진짜 충돌 409 code를 계약에 적어야 한다 (0929/03-01) | `src/features/reference-feature/contracts/reference-feature-contract-contribution.ts` | `112c870` | -| [계약] | 인증 프로필이 ANONYMOUS(`auth: "none"`)인 요청을 세션 상태와 상관없이 자격증명 없이 보낸다. 전에는 어느 세션 상태에서도 fetch가 0회였다. 제품 쪽 우회가 있으면 지운다 (1101/09-01) | `src/bootstrap/runtime-adapters.ts` | `ddf411e` | -| [계약] | realtime: 서버만 끊긴 OFFLINE 실패(브라우저는 online)를 online 이벤트를 기다리지 않고 backoff로 재시도하고, 상한에 닿으면 끝낸다. realtime recipe를 쓰는 프로젝트만 해당 (0929/04-01) | `src/adapters/realtime/` | `4d27b20` | -| [계약] | Service Worker 빌드가 `public/`을 다시 복사하지 않는다(`publicDir: false`). 전에는 SW를 켠 빌드의 `dist/config.json`이 local 문서로 덮어써져 운영 승인이 거절됐다. SW를 켠 프로젝트만 해당 (0929/06-01) | `vite.service-worker.config.ts`, `scripts/build-frontend.ts` | `c7b9cb8` | -| [계약] | `check:design-system` 규칙 4개가 생겼다. 두 테마에서 `--color-focus`가 표면 토큰 8종 모두와 3:1 이상, `color-mix()`는 `in oklab`만(oklch·lch·hsl·hwb 혼합은 실패), 계약의 컴포넌트 토큰은 스타일 하나 이상이 `var(--name)`으로 읽음, `--font-sans` 첫 글꼴은 기본 키워드이거나 `@font-face`로 싣는 글꼴. 규칙은 `scripts/lib/design-system-rules.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`, `scripts/lib/oklch-contrast.ts` | `35b183b`, `bfa7dd9`, `165ed19`, `8576ce1`, `49d8675`, `e714c0d` | -| [계약] | 시각 테스트가 `tests/visual/fonts.conf`로 글꼴을 고정하고, 스크린샷 전에 실제로 그려진 글꼴을 검사한다(`visual-fonts` setup 프로젝트). CI runner에 `fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation`이 있어야 한다. Linux 전용이다 (1101/11-02) | `tests/visual/fonts.conf`, `tests/visual/fonts.setup.ts`, `playwright.visual.config.ts`, `docs/testing/frontend-platform-testing-strategy.md` | `08b5ccc` | -| [계약] | 레지스트리 breaking 증거(`config/contracts/registry-change-evidence.json`)에 `after`가 필요하고, diff의 after 값과 같아야 한다. 한 번 쓴 증거로 같은 row·field의 다음 변경이 통과하던 문제다. diff에 남은 breaking 변경의 증거 행마다 `after`를 넣어야 게이트가 통과한다 (0929/07-01) | `scripts/lib/registry-compatibility.ts`, `config/contracts/registry-change-evidence.json`, `docs/operations/ci-quality-gates.md` | `5e6be9a` | -| [계약] | 레지스트리 호환성 분류: 선언 타입(`string\|null` 등) 안의 null ↔ 값 전환은 타입 변경(breaking)이 아니라 `breakingFields`로 등급을 정하고(보통 behavior-change), contract `allowedValues`에 값을 더하기만 하면 additive다. 값을 빼거나 제한을 없애면 그대로 breaking이다 (0929/07-02) | `scripts/lib/registry-compatibility.ts`, `scripts/check-registries.ts` | `82c9e59` | -| [계약] | 참조 기능 밖의 기능이 `TEMPLATE_FIXTURE` 출처 contract contribution을 쓰면 조립 때 `ContractContributionError`로 실패한다. 제품 기능은 `EXTERNAL_PACKAGE`를 쓴다. fixture 기여가 둘 이상이어도 실패한다 (1101/07-04) | `src/contracts/external-contract-runtime.ts`, `docs/architecture/starter-experience.md` | `c063389` | -| [계약] | 폐기 별칭 `MappingResult`(`boundary-mapper.ts`)와 `ApiFailure`(`errors.ts`)는 export로 남지만 lint(`no-restricted-imports`)가 `src`·`tests`의 import를 막는다. `BoundaryMappingResult`, `AppFailure`로 바꾼다. 타입이 같아 런타임은 그대로다 (1101/07-01) | `eslint.config.ts`, `src/contracts/boundary-mapper.ts`, `src/contracts/errors.ts`, `src/adapters/http/` | `fc303d8` | -| [계약] | `StorageBackend`에 `"external"`이 생겼다. cross-context pulse 키는 외부 소유로 바뀌어 StoragePort로 읽고 쓰면 `*_UNAVAILABLE`로 거절된다. exhaustive switch를 쓰는 코드는 분기를 더한다 (1101/05-01) | `src/contracts/storage-keys.ts`, `config/contracts/registry-governance.json`, `config/contracts/registry-change-evidence.json` | `e98a980` | -| [계약] | 쓰지 않는 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`, `docs/operations/ci-quality-gates.md` | `98b9682` | -| [계약] | 호스팅 계약에 앱 경로(`appRoute`, `/__probe/deep-link`)와 워커 스크립트(`serviceWorker`, 워커를 싣는 빌드만) 표면이 생겼다. 호스트는 파일이 없는 모든 경로에 그 release의 `index.html`을 HTML 헤더로 주고(SPA fallback), `service-worker.js`는 `no-cache`로 준다. fallback이 없으면 FE-GATE-019 live probe가 실패한다. nginx 예시는 `docs/operations/release-cache-rollback.md`에 있다 (1101/13-04) | `config/hosting/cache-policy.json`, `config/hosting/response-headers.fixture.json`, `scripts/lib/hosting-probe.ts`, `scripts/verify-hosting-headers.ts` | `629c8f0` | -| [계약] | 업로드 part 발급·PUT이 서버의 `Retry-After`를 기다리고, `maxRetryAfterMs`를 넘으면 다시 보내지 않는다. 실패 결과에 대기 시간이 붙도록 포트 반환 타입이 넓어졌다(추가만) (1101/01-01) | `src/adapters/browser-transfer/` | `95e4445` | -| [계약] | upload 실패 번역이 HTTP 상태와 함께 code를 보고 복구 행동(recovery)을 고른다. 6개 경로 중 5개의 recovery 값이 표대로 바뀌었다. BFF 발급 401/403은 아직 object store 403과 구분되지 않는다 (0929/01-01) | `src/adapters/browser-transfer/` | `9142390` | -| [계약] | realtime 배럴이 결과 생성 함수 `realtimeSuccess`·`realtimeFailure`를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) | `src/adapters/realtime/index.ts` | `3fe28de` | -| [계약] | 라우터 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` | -| [계약] | 앱 조립이 소유 context 루트가 닿지 않는 기능 라우트(1101/09-06)와 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands, 1101/09-07)를 throw로 거절한다. 전에는 조용히 NOT_FOUND가 되거나 아무것도 시작하지 않았다 | `src/apps/deployable-app-module.ts`, `src/bootstrap/` | `7139c7c`, `48a4074` | -| [계약] | 전송 전 거절의 원인이 진단에 남고, 연결 실수·멱등 키 위반은 `VALIDATION_REJECTED` 대신 `UNKNOWN_CLIENT_FAILURE`로 나온다. 그 실패의 화면 문구가 "요청을 처리할 수 없습니다."로 바뀐다 (1101/03-02) | `src/adapters/http/` | `4da0466` | -| [계약] | Vitest가 CI에서 skip·todo·only가 남은 실행을 실패시킨다(`-t`나 `file:line`으로 좁힌 실행은 제외). quarantine 주석이 붙은 skip도 실패한다(`docs/testing/frontend-platform-testing-strategy.md` 16.5절) (1101/10-04) | `vitest.config.ts`, `tests/support/` | `95e7d11` | -| [계약] | 시각 회귀 허용치가 비율 0.2%에서 절대 50 px로 바뀌었다. 전에는 잘린 선택 상자(UI-04, 1,145 px)도 통과했다 (1101/11-03) | `playwright.visual.config.ts` | `5ce3db9` | -| [계약] **BREAKING** | `useApplicationMutation`이 raw `{ execute, definitionId }` 입력을 받지 않는다. `useServerStateScope()`의 scope로 만든 `BoundMutation`(definitionVersion·operationId·requiresIdempotencyKey·owner·duplicatePolicy·invalidate)을 넘기고 `execute(input, { signal, intent })`로 부른다. raw query는 남았다. raw query는 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기). LEGACY 실행 분기는 legacy 전용 테스트 때문에 남겼다 (1101/08-03) | `src/presentation/adapters/query/application-query.ts`, `tests/helpers/legacy-application-query-harness.ts` | `1fa5f3e` | -| [계약] **BREAKING** | recipe의 browser-file·OPFS·storage durability·cache 타입 중 `src`와 이름이 같은 34개는 `src` 타입을 다시 내보낸다. fake는 `src` port를 구현하고 `BrowserDataResult`를 돌려준다. `MemoryDurableObjectStore` 생성자가 바뀌었고 `DurableObjectDataClass`·`DurableObjectIntegrity`·`DurableObjectRead`·`ObjectStoreRecoverySummary`는 지웠다. offline-indexeddb recipe를 쓰는 프로젝트만 해당 (0929/05-03) | `recipes/frontend-capabilities/` | `e1a4580` | -| [계약] | 제품은 `runtime-adapters.ts`를 고치지 않는다. 추가 capability(`FeaturePlatformCapabilities` 확장, indexedDb 포함)와 인증 프로필별 자격증명 제공자는 `src/bootstrap/product-composition.ts`에서, 제품 인증 프로필과 런타임 설정 키(zod)는 `src/contracts/product-contracts.ts`에서 돌려준다. 자격증명 순서는 scope fence → ANONYMOUS → 제품 제공자 → 세션 → fence 재확인이다. 그동안 `runtime-adapters.ts`·`feature-adapter-contribution.ts`·`rest-profiles.ts`·`release-artifacts.ts`·`runtime-config-schema.ts`에 넣은 제품 코드를 이 두 파일로 옮긴다 (1101/09-02) | `src/bootstrap/product-composition.ts`, `src/contracts/product-contracts.ts`, `src/bootstrap/runtime-adapters.ts` | `da1e128` | -| [계약] | 기능 계약에 route id `APP_HOME`을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. `src/contexts//context-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `
` 하나를 가져야 한다 (1101/09-03) | `src/contracts/routes.ts`, `src/contexts/bounded-context-module.ts`, `scripts/generate-product-feature-index.ts` | `ca16187` | -| [계약] | context 라우트 적재 때 기능 계약에 없는 handle routeId가 있으면 route id·context id·기능 id를 담은 오류로 실패한다 (1101/09-06) | `src/contexts/bounded-context-module.ts`, `src/apps/deployable-app-module.ts` | `d6e4e51` | -| [계약] | 인증 프로필 `REFERENCE_EXTERNAL_BEARER`의 새 이름은 `EXTERNAL_BEARER`다. 옛 이름은 한 릴리스 동안 `@deprecated` 별칭으로 남는다 (1101/16-03) | `src/contracts/rest-profiles.ts` | `6c5818f` | -| [계약] | `CREDENTIAL_HEADER_NAMES`에 `x-xsrf-token`을 더했다. 짝 백엔드(Spring `CookieCsrfTokenRepository`)의 기본 CSRF 헤더다 (1101/09-02) | `src/contracts/rest-profiles.ts` | `183a4a3` | -| [계약] | V2 Envelope에 `data` 키가 없으면 `null`로 읽는다. `meta.requestId`·`traceId`는 선택이다. 짝 백엔드는 null 필드를 생략한다 (백엔드 리뷰 1101/02-02) | `src/adapters/http/schema-registry.ts` | `969979d` | -| [계약] | V2: 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`가 `effect: "NOT_APPLIED"`와 진단 reason을 싣는다. 409의 `Retry-After`는 `retryAfterMs`로 실린다(V3 PROBLEM 실패도 같다). 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다. 응답 code의 정본은 백엔드 템플릿 `docs/web/http-contract.md` §2다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/adapters/http/feature-http-binding.ts`, `src/presentation/adapters/query/application-query.ts` | `93782b0`, `47fec5c` | -| [계약] | V2 클라이언트가 짝 백엔드의 400 `VALIDATION_FAILED`(필드 목록 `details: [{field, code, message}]`)를 422와 같은 `VALIDATION_REJECTED`·`validationIssues`로 읽는다. 필드 검증 거절(422와 이 400)은 `effect: "NOT_APPLIED"`다. 전에는 결과 불명으로 붙들어 폼에서 값을 고쳐도 다시 저장할 수 없었다. 그 밖의 400·409는 그대로 결과 불명이다. 적용 여부는 다음 행이 다시 정했다 (백엔드 리뷰 1101/02-01) | `src/adapters/http/client.ts`, `src/contracts/errors.ts` | `02e35d2`, `64e98ee` | -| [계약] | 거절의 적용 여부를 계약 문서 6.1절 표(백엔드 `5786126c` 코드 기준)로 정한다. V2와 V3 Envelope operation이 같은 표(`src/adapters/http/backend-envelope.ts`)를 쓴다. 적용 안 됨은 400 `VALIDATION_FAILED`(details 모양과 상관없음)·400 `IDEMPOTENCY_KEY_INVALID`·422 `IDEMPOTENT_REQUEST_MISMATCH`뿐이고, 그 밖의 400·409·422는 결과 불명이다. V2에서 `IDEMPOTENT_REQUEST_MISMATCH`가 아닌 422는 이제 결과 불명이라 폼에서 값을 고쳐도 다시 저장할 수 없다. 필드 검증을 422로 보내는 백엔드를 쓰는 프로젝트는 영향을 받는다. 필드 목록 없는 400 `VALIDATION_FAILED`는 바로 다시 저장할 수 있다. V3 Envelope operation의 400·409·422는 `classifyProblem` 대신 이 표가 정한다 (1101/14.4) | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/client.ts`, `src/adapters/http/http-execution-v3.ts` | `3261208` | -| [보안] [계약] | 쿠키 인증 프로필(`SAME_ORIGIN_COOKIE`)로 쓰기(GET·HEAD 밖)를 하는 operation은 그 프로필이 `x-csrf-token`이나 `x-xsrf-token`을 `requiredCredentialHeaders`로 요구해야 한다. 아니면 계약 조립이 거절한다. V2 클라이언트가 지키던 검사를 V3 조립으로 옮겼다 | `src/contracts/external-contract-runtime.ts` | `365d8c3` | -| [계약] | KEYED Envelope operation이 503 `IDEMPOTENCY_UNAVAILABLE`(백엔드가 실행 전에 거절)을 받으면 `retryBudget` 안에서 같은 키로 자동으로 다시 보낸다. 다 쓰면 결과 불명(`MAYBE_APPLIED`)이고 키를 지킨다. 응답 없는 실패 뒤에는 여전히 다시 보내지 않는다 | `src/adapters/http/backend-envelope.ts`, `src/adapters/http/http-execution-v3.ts` | `c05f41a` | -| [계약] **BREAKING** | 기능마다 적던 V2 API 행을 지웠다. HTTP operation은 contract contribution의 descriptor에 한 번만 적는다. FE-REG-API 행은 그 descriptor에서 뽑는다(`src/contracts/api-operations.ts`의 `projectApiOperationRows`: operationId·featureId·method·path·authProfileId·retrySemantics·requestBody·responseBody·responseEnvelope·requestSchema·responseSchema·problemSchema). `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"`과 `retrySemantics` `SAFE`·`IDEMPOTENT`로 본다. 레지스트리 기준선을 다시 승인했다. 옮기는 법: `-api-contract.ts`의 `schemas`를 `-schema-metadata.ts`로 옮겨 `defineFeatureRuntime({ schemas })`에 넘기고, `apiOperations`·`runtimeSchemas`·`mappers`와 mapper 레지스트리 행을 지운다. 스키마 메타데이터에 descriptor 입력·응답 검증기의 schemaId가 있어야 한다. memento-frontend의 `memento-web`이 해당한다 | `src/contracts/api-operations.ts`, `src/features/feature-module.ts`, `src/features/installed-feature-runtime-registries.ts`, `config/contracts/`, `scripts/create-feature.ts` | `12f3bb7` | -| [계약] **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`로 옮겼다. 템플릿과 tech-log·memento 모두 앱 안에서 V2 클라이언트를 부르는 곳이 없었다. 부르는 코드가 있으면 그 operation의 V3 descriptor를 만들어 `createFeatureHttpBinding`으로 실행한다. 초기 JS 203,354 → 201,598 B | `src/adapters/http/`, `src/bootstrap/runtime-adapters.ts`, `scripts/drill-runbook.ts` | `048f490` | -| [계약] | V3 descriptor에 선택 필드 `responseEnvelope`가 생겼다. `"ENVELOPE_V1"`이면 V3 실행기가 짝 백엔드 Envelope(`{success, data\|error, meta}`)를 읽는다. `outputValidator`는 `data`(키가 없으면 `null`), `problemValidator`는 `error`를 받는다. 400·409·422와 503 `IDEMPOTENCY_UNAVAILABLE`의 적용 여부는 실행기가 V2와 같은 표로 정하고(아래 6.1 표 행), `mapProblem`이 답하지 않으면 V2와 같은 kind·code·필드 오류로 읽는다. 성공 status의 Envelope 아닌 본문은 새 위반 `ENVELOPE_MISMATCH`다(`HttpContractViolationKind`에 추가만, exhaustive switch는 분기를 더한다). Envelope operation의 진단은 422 `IDEMPOTENT_REQUEST_MISMATCH`·400 `IDEMPOTENCY_KEY_INVALID`에 V2와 같은 `reason`을 싣는다(`HttpDiagnosticReason`에 두 값 추가). `create:feature`가 만든 기능은 이 값을 선언하고 problem 스키마가 Envelope `error`다. 값이 없는 descriptor(참조 기능 포함)는 그대로다. 이전에 만든 기능을 짝 백엔드에 붙이려면 contribution에 `responseEnvelope: "ENVELOPE_V1" as const`를 더하고 problem 스키마를 `error` 모양(`code` 필수)으로 바꾼다 (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` | -| [계약] | V3 실행 결과에 선택 필드 `sentRequestId`가 생겼다. 서버가 `x-correlation-id`를 돌려주지 않으면 `AppFailure.requestId`는 보낸 값이다. 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (0929/03-04) | `src/adapters/http/http-execution-v3.ts`, `src/adapters/http/feature-http-binding.ts` | `849d000` | -| [계약] | `ResumableUploadPort.upload()`: part 발급(BFF)이 401/403으로 거절하면 recovery가 `RESUME` 대신 `NONE`(`retryable: false`)이다. 세션 만료·권한 회수라 재인증 전에는 다시 불러도 같다. object store PUT 403은 그대로 `RESUME`이다 (0929/01-01) | `src/adapters/browser-transfer/resumable-upload/resumable-upload-runtime.ts` | `c5f87aa` | -| [계약] | realtime stream coordinator의 effect·recovery·close 마감 실패가 `IDLE_TIMEOUT` 대신 `APPLY_FAILED`/`APPLY`, `PROVIDER_UNAVAILABLE`/`RECOVER`, `PROVIDER_UNAVAILABLE`/`CLOSE`로 나온다. `RealtimeObservation.reason`도 같다 (1101/04-02) | `src/adapters/realtime/stream-coordinator.ts` | `1196b86` | -| [계약] | OPFS journal 목록이 손상 행을 건너뛰고 `corruptRows`로 센다. reconcile은 `corruptTransactions`를 보고한다. 손상 때문에 끝나지 못한 승인된 LOGOUT·ACCOUNT_DELETION은 partition을 지우고 `partitionDeleted`를 보고한다. `OpfsJournalPort.removePartition`과 worker gateway `removePartition`이 필수 메서드로 추가됐다 (0929/05-01) | `src/adapters/storage/opfs/` | `72edb55` | -| [계약] | `MessageArguments`가 catalog 문자열의 `{이름}`에서 파라미터를 만든다(값은 string 또는 number). `MessageParameters`는 값 타입을 좁히는 덮어쓰기이고, `ParameterlessMessageKey`는 자리표시자 없는 키만이다 (0929/08-03) | `src/presentation/i18n/message-contract.ts` | `ff33d58` | -| [계약] | `check:i18n`은 catalog parity와 raw backend 메시지만 검사한다. 화면 문구 literal은 ESLint `screenTextSelectors`가 잡는다. 한글 주석은 통과하고, 영어 JSX 문구·접근성 이름은 실패한다. template literal·삼항식·객체 prop 문구는 못 본다 (0929/08-02) | `eslint.config.ts`, `scripts/check-i18n.ts` | `855d22a` | -| [계약] | 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` | -| [계약] | `token-contract.ts`에 `PRODUCT_LOADED_FONT_FAMILIES`가 생겼다. 첫 글꼴 규칙이 이 목록의 글꼴을 허용한다 (1101/12-04) | `src/presentation/design-system/tokens/token-contract.ts`, `scripts/lib/design-system-rules.ts` | `b4ccada` | -| [계약] | 지금 diff와 맞지 않는 breaking 증거 행이 있으면 `check:registries`가 그 행을 적고 실패한다. `update:registry-baseline`이 그런 행을 지운다. 다운스트림은 오래된 행을 지우거나 한 번 재승인한다 (0929/07-01) | `scripts/lib/registry-compatibility.ts`, `scripts/update-registry-baseline.ts` | `4ada84e` | +| [계약] **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-layout.tsx`가 `CONTEXT_LAYOUT`을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 `
` 하나를 그려야 하고, `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()`가 `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`(백엔드 `c508b1ba`)과 백엔드 `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` | -| [계약] | 레지스트리 분류기가 무효화 그래프(topics·namespaces·edges)에 원소를 더하기만 한 변경을 additive로 본다. 빼거나 바꾸면 그대로 breaking이다. 이런 추가에 적어 둔 breaking 증거 행은 stale로 실패하니 `update:registry-baseline`으로 지운다 (0929/07-02) | `scripts/lib/registry-compatibility.ts` | `605fd17` | -| [계약] | 레지스트리 기준선을 한 번 재승인했다. FE-REG-API·FE-REG-SCHEMA `source`를 1101/15-01 뒤 위치로 고쳤고, 그 전 승인 뒤 쌓인 변경도 함께 승인했다. 다운스트림은 동기화 뒤 한 번 재승인한다 (1101/15-01) | `config/contracts/registry-baseline.json` | `70d0ac1` | -| [계약] | staging·production 승인(FE-GATE-027)이 `example.com`·`example.net`·`example.org`와 그 하위 도메인, `.example`·`.invalid`·`.test` endpoint를 거절한다. 프로필을 고치지 않은 운영 빌드는 두 위반으로 거절된다. CI에서 endpoint는 `config/runtime/.json`에 커밋한다 (1101/13-02) | `src/contracts/deployment-admission.ts` | `7b34756` | -| [계약] | staging·production 승인이 자리표시자 계약 신원(digest `PLACEHOLDER_CONTRACT_PACKAGE_DIGEST`)을 거절한다. `findAdmissionViolations`가 세 번째 인자로 계약 패키지를 받는다. `--config` 수정본 검사는 패키지를 보지 않는다 (1101/16-01) | `src/contracts/deployment-admission.ts`, `scripts/check-release-admission.ts` | `1269992` | -| [계약] | workflow의 promotion과 production_gate 사이에 deployment 배포 슬롯 job이 생겼다(job 10개). 슬롯이 비어 있으면 FE-GATE-019가 UNVERIFIED다. FE-GATE-019는 다시 빌드하지 않고 `--release-root .release/promoted-release`를 보며, 배포된 `release-manifest.json`의 buildId·releaseId가 후보와 다르면 FAIL이다. 예전에 PASS하던 FE-GATE-019가 이제 UNVERIFIED 또는 FAIL이다 (1101/13-01) | `.gitea/workflows/quality-gates.yml`, `config/ci/gates.json` | `de379ea` | -| [계약] | `src/contracts/zod-validator.ts`의 `zodValidator`로 zod 스키마를 `RuntimeValidator`로 바꾼다. 검증을 일부러 생략할 때는 `unvalidatedPayload(schemaId, reason)`(`src/contracts/unvalidated-payload.ts`)를 쓴다. 이 검증기에는 `validation: "NONE"` 표시가 붙고, `listUnvalidatedPayloads(composed)`가 조립 결과에서 생략 목록을 만들어 플랫폼 개요 화면이 보여 준다 (1101/07-03) | `src/contracts/zod-validator.ts`, `src/contracts/unvalidated-payload.ts` | `d3ddc89`, `8b7c6eb` | -| [계약] | `pnpm create:feature [--context ] [--package --digest --revision ]`로 기능 뼈대를 만든다. FE-GATE-020이 `test:feature-scaffold`(생성한 기능으로 merge 게이트 15개)를 돈다. `test:sample-removal`은 샘플을 지운 뒤 기능을 생성해 게이트를 다시 돈다 (1101/16-01) | `scripts/create-feature.ts`, `scripts/test-feature-scaffold.ts`, `config/ci/gates.json` | `d166aa3` | -| [계약] | `verify:documentation`(FE-GATE-017)이 입구 문서 4개의 src 최상위 폴더 설명과 `layers.md`의 아키텍처 규칙 이름을 검사한다(`sourceStructure`). `docs/README.md` 1절 현재 계약 문서에 적힌 repo 경로·링크·package script·FE-GATE ID가 실제로 있는지도 검사한다(`documentReferences`). 수동 접근성 범위는 route ID 목록 대신 라우트별 기록 파일로 검사하므로 라우트를 더해도 README·체크리스트를 고치지 않는다. 참조 기능을 지운 복사본은 그 파일을 가리키는 문서를 고쳐야 통과한다 (1101/14-03, 1101/14-05) | `scripts/verify-documentation-readiness.ts`, `docs/README.md` | `61baf96`, `16202fd` | -| [계약] | 규모 설계서를 `docs/architecture/scale-architecture.md`(현재 계약, 절 번호 유지)로 옮겼다. 절마다 현재 계약·기록만 상태와 코드와 다른 점을 적었다. 코드 주석 `Spec §N` 87곳은 `scale-architecture.md §N`으로 바꿨고, 문서 이름 없는 `spec §` 참조는 `tests/unit/deletable-history-documents.test.ts`가 막는다. 지울 수 있는 기록 목록에서 `docs/reviews/adapters/`를 뺐다(INVENTORY와 remediation ledger가 그 안의 리뷰로 링크한다). 복사한 프로젝트는 이 폴더를 지우지 않는다 (1101/14-01) | `docs/architecture/scale-architecture.md`, `README.md`, `docs/README.md`, `tests/unit/deletable-history-documents.test.ts` | `0a7fbed`, `b26517e` | -| [계약] | 레시피 번들 예산을 측정값 + 3%를 100 B 단위로 올린 값으로 다시 정했다: file-transfer 57,800, offline-indexeddb 38,500, realtime 42,200, service-worker-pwa 10,100. 3%를 넘는 증가는 커밋 본문에 이유를 적고 같은 규칙으로 올린다. 규칙은 `docs/architecture/optional-adapter-recipes.md`에 있다. 그 전에 file-transfer가 이 브랜치에서 55,700 → 56,100으로 한 번 올랐다 (0929/05-04) | `config/recipes/frontend-capability-recipes.json` | `95e4445` 외, `313f9ba` | +| [계약] | `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`가 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/.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 [--context ] [--with-create [--keyed]] [--package --digest --revision ]`가 기능 뼈대를 만든다. 목록 경로는 짝 백엔드 `new-feature.sh`와 같은 `/`이고 결과 수는 `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`를 읽음(대비 3:1 이상) (UI-01~UI-06, UI-08, 1101/12-01). `src/presentation/design-system/`, `src/presentation/styles/theme/`, `src/presentation/examples/`. 시각 골든은 `373b27b`에서 고정 글꼴로 다시 찍었다 -- 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서 `getByText`로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-01). `src/presentation/layouts/app-shell.tsx`, `src/presentation/styles/theme/` -- 저장소: 진단 이벤트 `storage.operation.failed`에 실패 원인(`reason`)이 붙는다 (1101/05-02). lifecycle 리스너 주인 주석을 실제에 맞추고 테스트를 뒀다 (1101/05-03). OPFS purge가 객체를 못 지우면 완료와 chunk sweep을 보고하지 않는다 (0929/05-02). `src/adapters/storage/`, `src/adapters/platform/` -- 운영: 배포된 `config.json`의 비상 스위치(`CAPABILITY_OVERRIDES`, `FEATURE_OVERRIDES`)를 바꿀 때 `check:release-admission --config <고친 사본> --original <배포된 원본>`으로 먼저 검사한다. 두 스위치 밖의 필드가 바뀌면 거절한다. 절차는 `docs/runbooks/FE-RB-001.md` (1101/13-05). `scripts/check-release-admission.ts`, `.env.example` -- 문서: 성능 문서의 번들 기준선(202,509~202,522 B, 여유 약 2,280 B)과 출처별 크기, 분류 규칙을 1101/15-01 뒤 빌드에 맞췄다 (1101/15-02). `PRODUCT.md`를 더하고 예제 제거 주장을 드릴 범위에 맞췄다 (1101/14-04). 이 문서와 리뷰 가이드가 리뷰 ID에 라운드를 붙인다 (1101/14-02) -- `verify:documentation`이 실패하면 실패한 검사 이름과 고칠 문서·빠진 route ID를 적는다 (1101/14-06) -- 테스트: Testing Library 대기 기한을 `tests/setup.ts` 한 곳에서 5초로 정하고, 부하에 흔들리던 극한 규모·guardian 테스트를 고쳤다 (0929/10-01). `npx vitest`나 npm을 거친 IDE 실행기로 돌려도 npm scope 환경변수 때문에 실패하지 않는다(`vitest.config.ts`) (1101/15-05). cgroup 시스템 테스트가 `/proc` 표본 대신 실행 단계가 남긴 PID·argv 기록을 읽는다 (1101/11-01). exact-five CLI 테스트가 실제 출력 문구를 기대한다 (0929/11-01). guardian이 실패하면 stdin을 기다리지 않고 끝난다(`3c175a5`). 계약 조립기와 V2/V3 대조 테스트 보강 (1101/07-02, 1101/07-06) -- 브라우저 파일·캐시: preview와 download의 dispose가 자기 lease만 풀어 grace 중인 download URL을 끊지 않는다 (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) -- HTTP·조회: 문제 응답 분류기 실패가 진단 reason `CLASSIFIER_FAILED`로 남는다 (1101/03-05). 어느 무효화 topic도 닿지 않는 조회 namespace를 진단으로 한 번 알린다 (1101/03-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) -- 진단: context·feature 오류 경계와 라우트 모듈 실패가 진단에 남고, 지원 참조가 `build:incident` 형식이다 (1101/09-09). REST 보안 프로필 오류가 operation과 깨진 조건을 말한다 (1101/16-03) -- 테스트·운영 도구: guardian이 실패하면 stdin을 기다리지 않고 바로 끝난다 (G-1). SW e2e가 제품이 이미 켠 worker와 빌드가 만든 사전 캐시 목록을 쓴다 (0929/11-03, 0929/06-04). 이벤트 계약 검증이 실제 이벤트 행으로 고정됐다 (1101/10-01). 규모 측정 기준선을 1101/15-01 뒤 코드로 다시 쟀다. 측정용 기능 복사본은 외부 패키지를 고정하고 선언한다 (`9333595`, 1101/07-04). reference feature를 지워 설치 기능이 0개여도 타입 검사와 `create-application.ts` 커버리지가 통과한다 (`e4ace51`, 1101/15-01) -- 문서: 새 기능 추가 매뉴얼 `docs/manual/`(한국어)을 더했다. 0~11단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것을 적고, 결정표·기능 폴더 밖 파일·`create:feature` 인자·전역 ID·패턴·오류 메시지 참조를 둔다. 두 템플릿 공통 원칙은 design-docs repo `conventions/feature-design-principles.md`에 있다. `verify:documentation`이 매뉴얼의 경로·명령·게이트 ID를 검사한다 (1101/16-01) -- 성능: 갤러리 전용 primitive를 초기 청크에서 빼 초기 JS를 2,718 B 줄였다. 초기 청크는 16 → 25개가 됐다. HTTP/1.1로 호스팅하면 청크 수를 다시 본다 (1101/08-08) -- 테스트: 플랫폼 component 테스트가 스타터 화면 대신 테스트 전용 페이지(`tests/helpers/fixture-feature.tsx`)를 쓴다. 스타터 화면을 바꾸는 제품은 `tests/component/starter-*.test.tsx`를 함께 지운다. HTTP 시나리오 증거(FE-GATE-007)와 기능 API 타입 음성 fixture(FE-GATE-003)는 샘플을 지워도 남는다. `tests/mocks/handlers/reference-resources.ts`는 `tests/features/reference-feature/reference-resource-handlers.ts`로 옮겼다 (0929/10-02) -- 테스트: 기능 테스트가 `createHttpScenarioHandler(<설치 계약>, { scenario, payload })`로 공유 MSW 시나리오를 쓴다. 기능을 더해도 카탈로그와 기능 밖 테스트를 고치지 않는다. `tests/mocks/**`는 플랫폼 소유다 (1101/16-02, 1101/16-01) -- 참조 기능: 샘플 페이지가 경로 문자열 대신 `referenceRouteUrl(routeId, input)`으로 링크를 만들고 route 입력 cast를 없앴다. `REFERENCE_FEATURE_ROUTE_CODECS`는 `presentation/reference-route-codecs.ts`로 옮겼다. 목록 링크 href가 `?limit=20`이 붙은 정식 URL이 된다 (1101/16-04) -- 저장소: OPFS purge가 여러 페이지를 다 지우면 끝났다고 보고하고 chunk sweep을 한다. 전에는 한 번 더 불러야 끝났다 (README 13.6) -- 운영 도구: 적재에 실패한 레지스트리 source는 "missing" 대신 그 오류 메시지를 적는다. `check:feature-index` 예외 이유를 실제 사용처로 고쳤다 (1101/12-05). 워커를 싣는 빌드의 SW 스크립트 헤더 검사를 테스트로 고정했다 (0929/06-05) +- 화면: 라이트 포커스 링 대비, 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). 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) ### 알려진 제한 -- 백엔드 응답 code 정본(`clean-architecture-backend-template/docs/web/http-contract.md`)은 아직 백엔드 repo에 커밋되지 않았다. 그래서 프론트 계약 문서는 커밋 SHA 대신 결정일로 기준을 적었다. 백엔드 application 층이 쓰기 뒤에 `VALIDATION_FAILED`를 던지면 "적용 안 됨" 판정이 틀린다. 지금 백엔드는 이 code를 요청 바인딩 단계에서만 낸다. -- 백엔드 필드 검증 code(`NOT_BLANK`, `SIZE` 등)가 폼 문구 표에 없어 "입력값을 확인해 주세요." 기본 문구가 나온다. V3 실행기 진단은 Envelope operation의 멱등성 거절 두 가지만 V2와 같은 `reason`으로 남긴다. 그 밖의 백엔드 code는 진단에 없고 실패의 `code`에만 있다. DTO 모드 operation의 진단에는 code가 없다. -- 참조 기능은 `responseEnvelope`를 선언하지 않아 지금도 DTO와 problem details만 읽는다. 짝 백엔드에 붙이려면 그 기능의 contribution과 problem 스키마·`mapProblem`·MSW 본문을 Envelope로 바꾼다. `create:feature`로 만든 기능은 Envelope를 읽는다 (1101 README 14.3). -- V3 Envelope 경로와 V2의 차이 세 가지(1101 README 14.6): 64 KiB를 넘는 실패 Envelope는 V3만 읽지 않는다. 보낸 KEYED 요청의 503은 V2만 같은 키로 자동 재시도한다(판정은 둘 다 결과 불명). 구조 예산(깊이 64 등)은 V3에만 있다. -- `tests/e2e/accessibility.spec.ts`는 모든 API에 `[]`로 답한다. 생성한 기능은 그 본문을 Envelope 불일치로 읽으므로, 그 라우트는 빈 목록 대신 오류 화면이 검사된다. e2e로 확인하지는 않았다. -- webkit에서 `old-tab-chunk-recovery.spec.ts`가 가끔 "preload했지만 쓰지 않음" 경고로 실패할 수 있다(한 번 관찰, 10회 반복은 통과). -- context 레이아웃의 skip link와 `
`은 타입 주석·문서·테스트로만 지킨다. 실행 검사는 없다 (1101/09-03). -- OPFS: lease 밖(FINISH~commit)에서 다른 탭이 같은 partition에 쓰는 경합은 검증하지 않았다 (0929/05-01). -- realtime: live-poll handoff coordinator의 마감 4곳은 아직 `IDLE_TIMEOUT`이다 (1101/04-02 범위 밖). -- 등록 라우트가 없는 URL에서 적재가 실패하면 진단 route_id가 `NOT_FOUND`다 (1101/09-09). -- `ui-gallery-page.tsx`는 component 테스트 커버리지가 0%다. e2e와 시각 테스트만 본다. -- `create:feature --context reference-context`로 만들면 참조 기능 라우팅 테스트가 깨진다. 생성 명령은 기본으로 새 context를 만든다. -- 실제 Gitea runner와 실제 HTTPS 호스트에서는 돌리지 않았다(SPEC U-1). FE-GATE-019 배포 슬롯은 주입한 fetcher로만 시험했다 (1101/13-01). 시각 테스트의 글꼴 패키지 설치 단계는 workflow에 넣지 않았다. nginx 예시는 실행해 보지 않았다. +이 절을 쓴 끝 커밋(`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 /`을 더한 뒤에야 닿는다 (1103/03-07). +- 짝 백엔드 계약 pin(`c508b1ba`) 뒤로 백엔드가 바뀌었다. 2026-11-05에 `check:backend-contract-drift`가 HEAD `45d2a478`에서 `docs/web/http-contract.md` §2 두 행(`IDEMPOTENT_IN_FLIGHT`, `IDEMPOTENCY_UNAVAILABLE`)의 설명 변경을 알렸다. status·code·재시도 칸은 같다. pin은 아직 올리지 않았다. +- 업로드: 백엔드 `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) @@ -171,7 +306,7 @@ | [계약] | 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` | -| [계약] | 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (0925/07-02, 0925/13-10) | `src/contracts/compatibility.ts`, `scripts/check-registries.ts`, `config/contracts/` | `17d617a` | +| [계약] | 설정 스키마 호환성 분류기(`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` |