문제 14.7은 V2 삭제로 "401 뒤 세션 복구 재전송"과 "보낸 KEYED 요청 자동 재시도"가 사라졌다고만 적었다. 사용자가 없어져도 되는지 물었고, V2 보안 프로필 일관성 검사도 같이 사라졌다. 고른 방법 14.7에 세 동작의 판정 표를 적었다. 기준은 설계 정본(2026-07-30 closed deep design) 8절이다. - 401 재전송: 없어져도 된다(8.4 FRT-D016 hidden replay 금지). VD-23의 낡은 문장은 리뷰 대상으로 남긴다. - KEYED 자동 재시도: 정본 8.3이 허용하는 부분(재시도를 허락하는 알려진 응답)만 되살렸다(c05f41a). - 보안 프로필 검사: 쿠키 인증 쓰기의 CSRF 요구만 보안 불변식이라 되살렸다 (365d8c3). CHANGELOG에 [보안] 행과 [계약] 행을 더했다. 검증 - verify:documentation PASS_SCOPED, tests/unit/changelog-review-ids.test.ts 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
58 KiB
변경 이력
이 템플릿을 복사해 쓰는 프로젝트가 원본의 수정을 골라 가져갈 때 보는 문서다.
가져오는 방법은 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').
미출시 — 브랜치 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/) 수정 묶음이다.
기준은 main 752a61f이다. 버전 번호와 태그는 아직 정하지 않았다. 커밋 해시는 이 브랜치 기준이다.
먼저 할 일 — 기능 모양 변경 (BREAKING, 1101/15-01)
298201f. 기능 하나가 초기 JS에 약 3.9 KB gzip을 더해서, 참조 모양 기능 하나만 더해도 초기 JS 예산(204,800 B)을 넘었다. 그래서 기능을 두 부분으로 나눴다.
- 선언(
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/가 완성된 모양이다):
- 기능 계약에서 스키마 메타데이터(
schemas)를 별도 파일로 뺀다. 참조:contracts/reference-schema-metadata.ts의REFERENCE_SCHEMA_METADATA. V2 API 필드(apiOperations,runtimeSchemas,mappers)는 지운다. - 선언 계약에
contractPackages를 더한다. 그 기능의EXTERNAL_PACKAGEcontribution이 고정하는 계약 패키지 identity 목록이다. 없으면Object.freeze([]). 부팅 때 release manifest를 이 목록과 맞춰 본다. 선언하지 않은 패키지를 적재하면 거절한다(src/features/installed-contract-contributions.ts). src/features/<feature>/feature-runtime.ts를 만든다.defineFeatureRuntime({ featureId, schemas, adapters: [...], contractContributions: [...] }). 참조:src/features/reference-feature/feature-runtime.ts.featureId가 모듈 id와 다르면 적재 때 실패한다.feature-module.ts에서adapters,contractContributions,runtimes(route codec·route runtime)를 지우고loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME을 넣는다.feature-runtime.ts를 어디서도 정적으로 import하지 않는다. 그러면 실행부 전체가 다시 초기 청크에 들어간다.- route codec을 runtime descriptor에서
context-routes.ts의 각 routehandle.codecs로 옮긴다. 참조:REFERENCE_FEATURE_ROUTE_CODECS(presentation/reference-feature-runtime.ts). 플랫폼 codec과 같은 id는 쓸 수 없다. - 기능 input(
application.features.get(id))은 적재 뒤에만 있다. 그 기능의 route 밖에서 읽는 코드는 먼저await application.features.load(id)를 부른다.ApplicationApi.features를 직접 구현하거나 fake로 만든 코드는load를 더한다(공개 포트에 추가만 했다). 런타임 설정으로 꺼진 기능은 적재하지 않는다. - 모든 기능의 실행부가 필요한 화면은
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이 막는다. vite.config.ts의 청크 그룹 두 개(feature-declarations,feature-platform)를 가져간다. 없으면 기능마다 선언 청크가 하나씩 는다(기능당 약 +1.5 KB).check:architecture,check:types,test:sample-removal -- --feature=<feature id>,tests/unit/feature-shape-growth.test.ts(기능 하나 1 KiB 이하)를 돌린다.
수치(298201f 측정): 템플릿 초기 JS 203,572 → 202,361 B. 참조 모양 기능 하나 +3,922 → +741 B. 예산 안에 참조 모양 기능이 약 3개 더 들어간다. 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 기능 계약끼리의 중복 검사는 부팅이 아니라 그 기능의 적재 시점과 Node 검사로 옮겨 갔다.
보안·계약 변경
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 기능 모양 변경. 위 "먼저 할 일" 절을 본다. 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>/context-layout.tsx가 CONTEXT_LAYOUT을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 <main id="main-content" tabIndex={-1}> 하나를 가져야 한다 (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로 본다. 레지스트리 기준선을 다시 승인했다. 옮기는 법: <base>-api-contract.ts의 schemas를 <base>-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<Key>가 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 |
| [계약] | 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/<profile>.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 <id> [--context <ctx>] [--package <name@version> --digest <sha256> --revision <hex>]로 기능 뼈대를 만든다. 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 |
그 밖의 수정
- 화면: 라이트 포커스 링 대비, 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 repoconventions/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)
알려진 제한
- 백엔드 응답 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와
<main>은 타입 주석·문서·테스트로만 지킨다. 실행 검사는 없다 (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 예시는 실행해 보지 않았다.
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 |
| [계약] | 레지스트리 호환성 분류기가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014) (0925/07-02, 0925/13-10) | src/contracts/compatibility.ts, scripts/check-registries.ts, config/contracts/ |
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-0411-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 |