문제: 1105 리뷰 README에는 수정 라운드의 기록이 없다. 1103 리뷰는 14절에 방법·결정·통합 문제·발견별 상태를 적었다. 초기 JS 예산 상향(D7)은 결정이라 이유·대안·재검토 조건을 남겨야 한다. 고른 방법: README 16절에 방법, 결정 표(7절 D1~D6의 결과, 새 D7과 그 근거: 커밋별 증가와 올린 뒤 여유), 합칠 때 생긴 문제와 고친 위치, 새 발견 48건·1103 이월 22건·그 밖의 이월 상태, 돌린 검사와 돌리지 않은 것을 적는다. CHANGELOG의 예산 행에 예산 커밋 `287dc6f`를 더한다. 버린 대안: 결정을 `docs/improvement/` 결정 색인에 적기. 그 폴더는 매뉴얼 PR(#6)과 겹쳐 건드리지 않는다. 위험·한계: 해시는 이 브랜치 끝에서 닿는 커밋이다. 브랜치를 다시 쓰면 함께 고쳐야 한다. 검증: desktop batch에서 확인. 옆 백엔드 checkout 없는 verify:documentation node scripts/run-vitest.ts run tests/unit/changelog-review-ids.test.ts tests/unit/documentation-readiness.test.ts tests/unit/deletable-history-documents.test.ts Refs: 1105/15-02, docs/reviews/2026-11-05-maturity-review/README.md
121 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다. 리뷰 README의 절은MMDD README N.N으로 적고 다시 돌린 항목은 그 뒤에X2처럼 번호를 붙인다. 영역 문서가 따로 매긴 ID는MMDD NN 영역 P-NN-NN, 짝 백엔드 리뷰의 ID는백엔드 리뷰 MMDD/NN-MM으로 적는다.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').
미출시 — 409d72e → 브랜치 fix/maturity-review-2026-11-05-b
2026-11-05 성숙도 리뷰(docs/reviews/2026-11-05-maturity-review/) 조치다. 범위는 main 409d72e(아래 절의 묶음을 합친 커밋)부터 브랜치 fix/maturity-review-2026-11-05-b(PR B)의 끝까지다. 앞의 세 조치(9655958, 629c713, 397664e)는 PR A(PR #5, 브랜치 fix/maturity-review-2026-11-05)에 있고, PR B는 그 위에 쌓였다. 기준점 409d72e를 빼면 이 절의 해시는 모두 이 범위에 있다. 아래 절을 아직 받지 않은 프로젝트는 아래 절부터 받는다.
먼저 할 일 (BREAKING)
아래 절의 "먼저 할 일"을 마친 뒤 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
옮기는 법
- HTTP descriptor마다
responseEnvelope를 적는다.InstalledHttpContract의 필수 칸이 됐다. 감싸지 않는 백엔드(memento-web, TechLog)는"NONE" as const, 짝 백엔드 Envelope는"ENVELOPE_V1" as const다. 빠뜨리면 그 descriptor의satisfies InstalledHttpContract<...>에서check:types가 실패한다. 런타임 동작은 같다 (1103/16-01) - 뮤테이션 정책의 operation ID를 손으로 적지 않는다.
BoundMutation.operationId는 brand 타입MutationOperationId다.operationId: "<ID>"와requiresIdempotencyKey를...commandMutationIdentity(<descriptor>)로 바꾼다. 문자열로 적으면check:types가 실패한다 (1103/16-05) refusedBeforeWrite에서 플랫폼 code를 뺀다. 계약 문서 6.1절이 "쓰기 뒤 가능"으로 둔 code(PLATFORM_CODES_POSSIBLY_AFTER_WRITE:BAD_PARAMETER,MAPPING_FAILED,DB_*8개,LOCK_ACQUISITION_TIMEOUT, Fileserver code)를 적으면 계약 조립이 거절해 부팅이 멈춘다. 그 code의 실패는 결과 불명으로 남는다 (1105/03-01)- bounded poll의
execute는 실패를 던지지 않고 결과로 돌려준다. 던지면(lease 자신의 abort 제외) 재시도 없이PROTOCOL_MISMATCH(retryable 아님)로 lease가 끝난다. 네트워크 실패를 throw로 내던execute는 retryablePROVIDER_UNAVAILABLE결과로 바꾼다. 실행기에는 클로저의 descriptor 대신input.operation(생성 때 검사한 descriptor)을 넘긴다 (1105/04-02, 1103/04-01) artifacts/tests/a11y.json을 읽는 도구는 schemaVersion 2를 읽는다.scope는 실패 화면으로만 본 라우트를 빼고, 그 라우트는 새notChecked배열에{ routeId, reason }으로 들어간다. 설치된 라우트 전체는 둘을 합친 것이다 (1103/11-01)- 제품 scope participant의
label은 소문자 kebab-case 48자 이하로 쓴다. 아니면 조립이TypeError로 멈춘다 (1105/02-01) - 레시피를 복사한 제품은 복사본을 고친다. 쿠키 세션 모드는
createSessionCookieRejectionHandler(context)를composeProduct의onCredentialRejected에 잇는다. 잇지 않으면 서버 401이 템플릿 세션에 닿지 않는다(매뉴얼 04 4.3) (1105/09-02). OIDC PKCE owner는 sign-in transaction 키를 registry 행AUTH_REDIRECT_TRANSACTION의physicalKey에서 가져온다. 키 글자는 같다 (1105/05-01) - Service Worker를 켠 제품은
blockers·observe를composeProduct의 선택 칸serviceWorker로 옮긴다. 템플릿 파일src/bootstrap/create-runtime-composition.ts는 템플릿 것으로 되돌린다 (1103/09-05) - 제품 merge 게이트(
config/ci/product-gates.json의mergeGates)가 있는 제품은corepack pnpm generate:ci-workflow를 다시 돈다.release_gate가product_merge_gate도 기다리는 줄이 생긴다. 다시 돌리지 않으면check:ci가 실패한다 (1105/13-02) - 기능 안
adapters/밖에서src/adapters를 import하는 파일은adapters/로 옮긴다. 아니면check:architecture가feature-and-app-roots-do-not-reach-adapters로 실패한다 (0929/12-03)
옮긴 뒤 확인
- 로컬 merge 게이트 14개를 돈다. 이 절 때문에 먼저 볼 것:
check:types(1·2단계), 앱을 조립하는test:unit·test:component(3·6단계),check:ci(9단계),check:architecture(10단계),check:registries(응답 스키마 행을REJECT_UNKNOWN으로 좁힌 변경은 이제 breaking). - 한 checkout에서 브라우저 테스트 실행 두 개를 함께 돌리려면 실행마다
TEST_RUN_ID를 다르게 준다. 게이트(ci:gate)와 증거 검사는 기본 경로만 읽으므로 한 checkout에서 하나씩 돈다. - 배포가 있는 제품: 자산을 redirect로 주는 호스트는 FE-GATE-019가 FAIL이다.
보안·계약 변경
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | FE-GATE-013(test:system) 러너는 비특권 user namespace와 network namespace를 허용해야 한다(provider 샌드박스의 bwrap --unshare-net). 사전 점검이 bwrap을 실제로 띄워 보고, 허용하지 않는 호스트에서는 provider 테스트를 돌리기 전에 이유·호스트 설정·고치는 방법을 적고 멈춘다. 요구는 러너 요구 목록, gate 정의의 hostRequirements, workflow 주석에 있다 (1105/12-01) |
scripts/check-system-test-prerequisites.ts, scripts/lib/provider-sandbox-namespaces.ts, config/ci/gates.json, docs/operations/ci-quality-gates.md |
9655958 |
| [계약] | release job immutable_build가 FE-GATE-015·027의 gate 로그·evidence와 의존성 advisory 기록을 결과와 상관없이 immutable-gate-evidence-<run>-<attempt>로 올린다. 후보 archive와 그 upload는 그대로다 (1105/13-01) |
scripts/generate-ci-workflow.ts, scripts/contracts/ci-gates.ts, .gitea/workflows/quality-gates.yml |
629c713 |
| [계약] | gate 모양 기준선(canonicalGateShapeSha256)이 FE-GATE-013의 hostRequirements도 본다. 요구를 지우거나 바꾸면 check:ci가 기준선 차이로 실패하고, 바꿀 때는 update:ci-contract-baseline(owner·reason 필수)으로 다시 기록한다. 제품이 config/ci/contract-baseline.json을 자기 값으로 다시 기록해 두었다면 받은 뒤 다시 기록한다 (1105/12-01) |
scripts/contracts/ci-gates.ts, config/ci/contract-baseline.json |
67082cc |
| [계약] | 제품 overlay에 merge 게이트가 있으면 release_gate가 product_merge_gate를 기다린다. 제품 검사가 실패하면 같은 run의 release·immutable_build·promotion·deployment가 멈춘다. 게이트가 없으면 workflow는 그대로다. check:ci가 그 연결이 없는 workflow를 거절한다. 위 "먼저 할 일" 9단계 (1105/13-02) |
scripts/generate-ci-workflow.ts, scripts/contracts/ci-gates.ts |
92d5019 |
| [계약] | 한 checkout에서 실행 두 개가 서로를 지우지 않는다. TEST_RUN_ID를 주면 Playwright 결과·report·JUnit과 서빙할 빌드가 .tmp/runs/<id>/ 아래로 간다. 빌드 단계는 RUN_OUTPUT_ROOT(설정이 web server에 넘긴다) 아래에 쓴다. 다섯 Playwright 설정은 빈 포트를 골라 TEST_E2E_PORT·TEST_VISUAL_PORT·TEST_CAPABILITIES_PORT·TEST_STORYBOOK_PORT·TEST_DEV_PORT에 적고(미리 주면 그 포트), vite는 --strictPort로 뜨고, dev 설정은 떠 있는 서버를 쓰지 않는다. 변수가 없으면 출력 경로는 전과 같다. 기능 인덱스 생성기는 내용이 같으면 쓰지 않고 다르면 rename으로 바꾼다. 상세는 docs/testing/frontend-platform-testing-strategy.md 13.6절 (1105/12-04) |
scripts/lib/run-isolation.ts, playwright*.config.ts, vite.config.ts, scripts/build-frontend.ts, scripts/generate-product-feature-index.ts |
ddbda4d, f4d5761, 0e72c0c, 510e2bb |
| [계약] | verify:documentation이 짝 백엔드 경로·링크를 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리(옆 checkout의 git 기록)에서 찾는다. 작업 트리와 HEAD는 보지 않는다. checkout이나 그 커밋이 없으면 확인하지 못한 것으로 남긴다. repo 밖으로 나가는 링크가 pin한 저장소가 아니면(이름 오타 포함) 실패한다 (1105/12-02) |
scripts/verify-documentation-readiness.ts |
fc95672 |
| [계약] | verify:documentation은 지울 수 있는 템플릿 기능(참조 기능, 예제 화면 기능. scripts/lib/removable-template-features.ts)의 경로와 script를 그 기능이 설치돼 있으면 검사하고, src/features/<id>/feature-module.ts가 없으면 요구하지 않는다. 그래서 아래 절 6단계대로 예제 기능을 지운 제품도 문서 검사와 FE-GATE-005가 통과한다. 참조 기능 경로는 다시 백틱으로 적어 검사를 받는다. 1절 문서가 그 경로를 백틱 밖에 적으면 test:unit이 실패한다 (1105/14-01, 1105/14-03) |
scripts/verify-documentation-readiness.ts, scripts/lib/removable-template-features.ts, scripts/test-sample-removal.ts, docs/ |
50b631e, 332bfee, 1dda18d |
| [계약] | 아키텍처 규칙 feature-and-app-roots-do-not-reach-adapters가 기능의 adapters/ 폴더와 feature-adapter-contribution.ts를 뺀 src/features 전체를 본다. 기능 안 support/ 같은 계층 밖 폴더가 src/adapters에 닿으면 실패한다. 위 "먼저 할 일" 10단계 (0929/12-03) |
.dependency-cruiser.json, scripts/check-architecture.ts |
a37ebba |
| [계약] BREAKING | artifacts/tests/a11y.json이 schemaVersion 2다. 실패 화면으로만 axe를 돌린 라우트(일반 답이 없는 상세 라우트)는 scope에서 빠져 notChecked({ routeId, reason })에 들어간다. 라우트 test가 자기 상태를 artifacts/tests/a11y-data-state/<ROUTE_ID>.json에 남긴다. 위 "먼저 할 일" 5단계 (1103/11-01) |
scripts/write-a11y-report.ts, scripts/lib/a11y-data-state.ts, scripts/contracts/release-artifacts.ts, tests/e2e/accessibility.spec.ts |
757d1c7 |
| [계약] | lab(FE-GATE-026)이 기능 라우트 첫 진입을 잰다. 대상은 설치된 기능의 첫 공개 내비게이션 라우트(labFeatureRoute, 템플릿에서는 EXAMPLES_UI)이고 예산은 budgets.json의 lab.featureRouteInteractionMs 500 ms다. 그런 라우트가 없으면 measured: false로 남기고 판정하지 않는다. run마다 대상 라우트를 직접 열어 CLS도 잰다(metrics.targetDeepLinkCls, 예산 lab.cls). lab은 스크롤바를 보이게 띄운다. lab.json schema에 새 칸이 필수다 (1105/15-04, 1105/15-01, 1105/15-05) |
config/performance/budgets.json, config/schemas/lab-performance.schema.json, scripts/test-performance.ts, scripts/lib/lab-performance.ts |
81701ad, 138c195, e02f252 |
| [계약] | 초기 JS 기록 대조(tests/unit/feature-shape-growth.test.ts)의 합계 허용 오차가 1%(약 2 KB)가 아니라 256 B다. 초기 JS를 수백 바이트 움직이는 변경은 기록을 다시 쓴다 (1105/15-02) |
scripts/scale/measure-feature-shape-growth.ts |
46359a1 |
| [계약] | 초기 JS 예산(initialJsGzipBytes)이 204,800 B가 아니라 206,848 B(202 KiB)다. 이 묶음의 검사·진단 코드가 초기 JS를 1,184 B 늘려 생성 기능 둘을 더한 드릴(FE-GATE-020)이 예산을 넘었다. 템플릿 기록은 204,111 B·초기 파일 27개로 다시 적었다. 예산을 복사한 제품은 자기 값을 그대로 두거나 같은 이유로 올린다. 재검토 조건은 docs/operations/performance-evidence.md (1105/15-02) |
config/performance/budgets.json, config/scale/feature-shape-ceilings.json |
0fee3fe, 287dc6f |
| [계약] | test:all이 test:coverage(FE-GATE-005)가 도는 Vitest 경로를 모두 돈다(tests/features 전체, tests/scripts, browser-soak 계약 테스트). tests/unit/test-all-paths.test.ts가 대조한다 (0929/10-05) |
package.json |
7ead8d3 |
| [계약] | 제품 기능 제거 드릴(test:sample-removal -- --feature=<id>)의 잔여 판정: src는 기능 ID·폴더 이름을 담은 파일, tests는 이름에 기능 ID가 있거나 그 기능 폴더에서 import하는 파일만이다. 템플릿 테스트가 예시 ID(invoice-feature 등)를 데이터로 쓰는 것은 잔여가 아니다. 참조 기능은 전처럼 넓게 찾는다 (1105/16-04) |
scripts/lib/feature-residue.ts, scripts/test-sample-removal.ts |
b45d6a0 |
| [계약] BREAKING | InstalledHttpContract의 contract.responseEnvelope가 필수다. 참조 기능과 테스트 fixture는 "NONE"을 적는다. 조립은 빠진 값을 전처럼 NONE으로 읽는다. 위 "먼저 할 일" 1단계 (1103/16-01) |
src/contracts/external-contract-runtime.ts, scripts/create-feature.ts, src/features/reference-feature/contracts/ |
56272e8 |
| [계약] BREAKING | refusedBeforeWrite에 PLATFORM_CODES_POSSIBLY_AFTER_WRITE(계약 문서 6.1절의 "쓰기 뒤 가능" 플랫폼 code)를 적으면 composeContractContributions가 거절한다. 실행기의 fail-close도 그 목록을 무시한다. tests/unit/backend-contract-pin.test.ts가 6.1절 표와 목록을 양방향으로 대조한다. 위 "먼저 할 일" 3단계 (1105/03-01) |
src/contracts/external-contract-runtime.ts, src/adapters/http/backend-envelope.ts |
5c0b37e |
| [계약] | Envelope operation의 503 RATE_LIMIT_UNAVAILABLE·RATE_LIMIT_INCOMPATIBLE은 쓰기 전 거절(NOT_APPLIED)이다. kind는 SERVER_FAILURE(action retry)이고 IDEMPOTENT 쓰기는 retryBudget 안에서 다시 보낸다. KEYED·NEVER는 자동 재전송이 없다 (1105/03-02) |
src/adapters/http/backend-envelope.ts, config/contracts/backend-idempotency-answers.json |
c6c37f3 |
| [계약] | 짝 백엔드 http-contract.md §2·§4 표를 pin 커밋 그대로 config/contracts/backend-http-contract-excerpt.json에 옮겼다. test:unit이 답 표와 사본을 행마다 대조한다(옮기지 않은 행은 pin의 notCopied). check:backend-contract-drift(게이트 밖)는 사본을 pin 커밋의 문서와 비교하고, pin의 backend.scaffoldSources(백엔드 생성기 템플릿 파일과 옮긴 프론트 위치)가 pin 뒤 바뀌었는지도 본다. 비교하지 못하면 rc=2다. pin을 올릴 때는 --write-excerpt (1105/07-01, 1105/16-02) |
config/contracts/backend-contract-pin.json, config/contracts/backend-http-contract-excerpt.json, scripts/check-backend-contract-drift.ts, scripts/lib/backend-contract-excerpt.ts |
daf3474, f600e6b |
| [계약] | Fileserver 업로드 client: 202 REJECTED는 실패 VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED다(전에는 SCHEMA_MISMATCH). 빈 파일은 보내지 않고 FILE_EMPTY, NOT_STARTED로 끝난다. 504 TRANSFER_TIMEOUT은 결과 불명(MAYBE_APPLIED, retryable 아님, 자동 재전송 없음)이다. 멱등성 code와 V3 판정 표에 있는 답은 V3 표대로 판정해 503 IDEMPOTENCY_UNAVAILABLE도 결과 불명이다. 실패 Envelope의 meta.traceId를 AppFailure.traceId로 싣는다 (1105/01-01, 1103/01-01, 1105/01-02, 1105/01-03) |
src/adapters/http/fileserver-upload.ts, docs/manual/ |
6608fef, 471b001, 8b92f45 |
| [계약] | FE-REG-SCHEMA direction: "RESPONSE" 행의 unknownFieldPolicy를 REJECT_UNKNOWN으로 좁히면 check:registries가 breaking(response-reader-narrowed)으로 본다. 넓히는 쪽과 REQUEST 행은 그대로 behavior-change다 (1105/07-02) |
scripts/lib/registry-compatibility.ts |
3b62ccd |
| [계약] BREAKING | BoundMutation.operationId와 commandMutationIdentity가 돌려주는 operationId가 brand 타입 MutationOperationId다. 위 "먼저 할 일" 2단계 (1103/16-05) |
src/contracts/server-state.ts |
48c1ab7 |
| [계약] | 키 없는(NEVER) 결과 불명 요청과 같은 입력으로 submit하면 보내지 않고 NOT_STARTED DUPLICATE_IN_FLIGHT(code UNKNOWN_EFFECT_PENDING)를 돌려준다. AsyncSurface는 unknownEffectResendable === true일 때만 재전송 버튼을 그린다. 손으로 만든 결과 불명 상태를 넘기던 화면은 버튼이 사라진다 (0929/03-03) |
src/presentation/adapters/query/application-query.ts, src/presentation/components/async-surface.tsx |
683ccfb |
| [계약] BREAKING | createBoundedPollCoordinator의 execute가 던지면(abort 제외) 재시도 없이 PROTOCOL_MISMATCH(retryable 아님)로 lease가 끝난다. execute 입력에 생성 때 검사한 descriptor input.operation이 실린다(추가만). 위 "먼저 할 일" 4단계 (1105/04-02, 1103/04-01) |
src/adapters/realtime/ |
05330e3, 27e3dec |
| [계약] | scope reset이 실패하면 단계마다 진단 cache.operation.failed(operation: "SCOPE_RESET", reason PARTICIPANT_FAILED·CACHE_RESET_FAILED·GENERATION_ACTIVATION_FAILED·PARTICIPANTS_UNREADABLE, participant면 scope_participant: <label>)를 남긴다. 진단 계약에 키 scope_participant(값 정책 isScopeParticipantLabel)가 생겼다. 제품 closer는 각자 participant가 되고, 형식에 맞지 않는 label은 조립이 TypeError로 거절한다. 위 "먼저 할 일" 6단계 (1105/02-01) |
src/contracts/diagnostics.ts, src/adapters/query-cache/server-state-scope-runtime.ts, src/bootstrap/runtime-adapters.ts |
f738348 |
| [계약] | ProductCompositionContext.notifySessionUnauthenticated()가 생겼다. 쿠키 세션 recipe의 createSessionCookieRejectionHandler(context)는 SESSION_COOKIE_* 프로필의 401만 세션에 넘긴다. 위 "먼저 할 일" 7단계 (1105/09-02) |
src/bootstrap/product-composition-contract.ts, recipes/session-owners/cookie-session-owner.ts |
0007699 |
| [계약] | ProductComposition.serviceWorker(선택): { blockers?, observe? }. 템플릿 조립이 createOptionalRuntimeHost에 넘긴다. observe가 던져도 worker 흐름은 바뀌지 않는다. 위 "먼저 할 일" 8단계 (1103/09-05) |
src/bootstrap/product-composition-contract.ts, src/bootstrap/create-runtime-composition.ts |
fdc1db9 |
| [계약] | 금지된 설정 키로 멈춘 부팅 오류의 invalidKeys에 그 키의 점 경로가 실린다. src/contracts/env.ts가 UnsafeConfigNameError(key)를 새로 내보낸다(추가만) (1103/07-04) |
src/contracts/env.ts, src/bootstrap/load-runtime-config.ts |
2e1acb1 |
| [계약] | 저장소 registry 행 AUTH_REDIRECT_TRANSACTION(backend: "external", FE-REG-STORAGE additive). OIDC PKCE recipe의 sessionStorage 키가 이 행의 physicalKey다. 사용처가 지울 수 있는 레시피뿐이라 FE-REG-STORAGE orphan 검사에서 뺀다. 위 "먼저 할 일" 7단계 (1105/05-01) |
src/contracts/storage-keys.ts, recipes/session-owners/oidc-pkce-session-owner.ts, config/contracts/registry-governance.json |
dc7c95b |
| [계약] | 승인된 LOGOUT·ACCOUNT_DELETION purge가 마지막 객체까지 돌면 늘 partition을 지운다. 성공 report는 partitionDeleted와 moreObjectsAvailable 중 정확히 하나를 가진다. port의 chunkSweep은 아무도 채우지 않아 @deprecated다 (1103/05-01) |
src/adapters/storage/opfs/opfs-byte-store-adapter.ts, src/application/ports/browser-file-storage/opfs-ports.ts, recipes/frontend-capabilities/ |
23662fb |
| [계약] | Cache Storage: 본문을 읽지 못한 entry는 판정 UNREADABLE이고, 다시 stage하면 모든 asset을 다시 받아 덮어쓴다. activation은 그 경우 code는 그대로 두고 recovery를 REHYDRATE로 준다 (1105/02-02) |
src/adapters/cache-storage/public-response-cache-adapter.ts |
8e9fb1f |
| [계약] | Service Worker 사전 캐시는 assets/(BUILD_ASSET_DIRECTORY) 아래 해시 파일만 담는다. public/의 루트 파일(아이콘 등)은 빠진다. build.assetsDir를 바꾸는 제품은 이 상수도 바꾼다 (1105/06-01) |
src/contracts/service-worker.ts, scripts/generate-service-worker-assets.ts, src/adapters/service-worker/service-worker-static-assets.ts, scripts/lib/hosting-probe.ts |
1c7c614 |
| [계약] | 자산 MIME probe(FE-GATE-019 live)가 redirect를 FAIL로 본다(install fetch는 redirect: "error"). live 분기는 probeLiveHosting 하나다 (1105/06-02) |
scripts/lib/hosting-probe.ts, scripts/verify-hosting-headers.ts |
4d6f254 |
그 밖의 수정
- 테스트: 제품 확장 타입 검사 탐침이 복사본의
product-contracts.ts·product-composition.ts를 덮어쓰지 않고 덧붙인다. 기능이 제품 capability를 쓰는 다운스트림에서도 FE-GATE-005가 통과한다 (1105/09-01,397664e) - 폼·화면: 기능이
useAppForm의refusalMessages로 쓰기 전 거절 code에 자기 문구와 필드를 붙인다 (1103/03-01,12d97d7). 복구 버튼으로 끝낸 저장 뒤 포커스가 feedback 자리로 간다 (1105/08-01,4f3c10b). 다른 저장이 진행 중이면 저장 버튼을 끄고 진행 문구를 보인다 (1105/08-04,f2b8ba7). 생성 폼이 "변경됨으로 확인" 뒤 목록으로 간다 (1105/08-02,90c489c). 홈 시작 링크가 런타임에 꺼진 기능을 고르지 않는다 (1105/08-03,f849d78).:root에scrollbar-gutter: stable. 스크롤바 자리만큼 내용 폭이 15 px 줄어 시각 골든 5장을 다시 찍었다. base.css를 받은 제품은 자기 골든도 다시 찍는다 (1105/15-05,e02f252). 플랫폼 구성 화면이 릴리스 신원 칸 자리를 처음부터 잡는다 (1105/15-01) - 레지스트리 도구:
check:registries가 계약 조립 실패 원인을 한 번만 적는다 (1105/09-03,bfd9d50) - 문서: VD-28과 realtime 설계 3절의 poll 규칙을 V3 descriptor로 (1105/04-03,
05880d1). 테스트 전략 11.2절의 지운 auth-recovery 테스트 (1103/12-05,e72fb6e). 기능마다 바뀌는 추적 파일 둘과 충돌 처리 (1105/16-01,6d084cf). 매뉴얼 04 §3.2 설정 키 예시의defaultValue와 그 블록을 그대로 타입 검사하는 테스트 (1105/14-02,e6b2a4f). Cache Storage inspect의verified뜻과 비용 (0929/02-02,f2a4f32). 세션 파일 recipe 주석의 capability 타입 위치 (1105/02-03,d31c7d6). 남은FEATURE_OVERRIDES키의 경고 (0929/14-05,1c4e57c). 루트SPEC.md·tasks/의 이유 (0929/14-01,1ac336a). README에 미출시 범위를 받는 두 명령과 기준점 기록 (0929/14-02,57e3586) - CHANGELOG: 아래 절의 초기 파일 상한 32·알려진 제한 기준·FE-GATE-017 단계 (1103/14-01, 1103/15-02,
832774f), poll 행 (1105/04-02,1e576ef), "옮기기 전" 2단계 목록 (1103/14-02,f4be426), 리뷰 참조 꼴과 그 테스트 (1101/14-02,b834b8d) - 테스트 고정: interaction signal listener 정리 (1105/10-02,
dae44f5), 조합 transport의 OFFLINE 재시도 (1105/04-01,bde7fa4), MAX_RETRY_ATTEMPTS·REQUEST_TIMEOUT_MS와 복구 중 세션의 보호 라우트를 샘플 밖에서 (1105/10-01,00b12b3), 옛 탭이 지워진 route를 reload 없이 연다 (1105/06-03,aaa782b), Fileserver 5xx·deadline·읽기 전 크기 거절 (1105/01-04,f2f7dc4), strict fixture가 preload 기록으로 test를 실패시킨다(browserFailureVerdict) (1105/11-01,e025529), 오래된 scope의 성공 응답 (0929/10-04,c842bac), 손상 code 목록의 경계 (1105/02-04,56c0bd0), 실제 시계를 기다리던 테스트 5개 (1101/10-07,ce191be), cross-context host의 localStorage 영역 (1101/02-04,11a0fd0), vite 빌드 입력 목록 한 모듈 (1105/15-03,c9aa73f)
알려진 제한
이 절의 범위 끝에서 사실인 것만 적었다. 하나씩 결정 대기·백엔드로 넘김·일부를 적는다.
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다.
- 기능 라우트 첫 진입: lab이
EXAMPLES_UI를 500 ms 예산으로 잰다(1105/15-04). 진입은 여전히 요청 두 묶음(context 라우트 모듈·실행부, 그다음 페이지 청크)이다. 하나로 줄이려면 초기 청크의 라우트 선언이 페이지 로더를 가져야 한다. 결정 대기(선언 모양·초기 JS). 예산 여유는 94 ms이고 lab 부하 가드는 없다(0929/11-04). - 예제 기능 제거 드릴(
test:sample-removal -- --feature=platform-examples-feature)은 어느 게이트도 돌리지 않는다. 문서 쪽은test:unit의 사본 테스트가 본다. 일부(1105/14-01). - 결정 대기: KEYED 결과 불명의 같은 키 재전송이 500
IDEMPOTENCY_RECOVERY_REQUIRED를 받아도 재전송 버튼이 남는다. 고르는 사람은 프론트 템플릿 담당이다(재전송을 거두기 / 백엔드가 롤백을 효과 없음으로 기록 / 지금대로) (1103/03-01). - 결정 대기: 워커 없는 빌드에서 자산 MIME probe를 script·style만 보게 좁힐지. 지금은 글꼴·이미지 MIME도 FAIL이다 (1105/06-02).
- 결정 대기: Cache Storage inspect에
signal과 판정 불가 칸을 더할지(VD-15 목표 runtime과 함께) (0929/02-02). - 결정 대기: dev manifest를 생성 파일로 둘지, 초기 JS 기록에서 제품 기능을 뺄지. 지금은 기능 브랜치 둘이 같은 줄에서 충돌하고 명령을 다시 돌려 푼다 (1105/16-01).
- 결정 대기: 1절 밖 문서(목표 설계)의 경로 검사. 문서별 예외 방식부터 정해야 한다 (1103/12-05).
- 결정 대기: 두 제품이 고친 템플릿 파일 중 제품 소유 자리가 없는 것을 템플릿에 들일지(아래 절 "옮기기 전" 2단계) (1103/14-02, 0929/14-03). 다운스트림이 찾은 템플릿 결함을 어디에 기록할지 (0929/14-06). 현재 계약 절과 목표 설계 절이 섞인 문서를 나눌지 (1101/14-07).
- 백엔드로 넘김: Fileserver 504
TRANSFER_TIMEOUT은 작업이 시작된 뒤에도 retryable로 온다. 백엔드가ambiguous표시를 주거나 504가 "READY 없음"을 보장하면 프론트 판정을 다시 본다.POST /v1/files는Idempotency-Key를 읽지 않는다 (1105/01-02). - 백엔드로 넘김: 백엔드 매뉴얼의 짝 경로 안내와
docs/fileserver/http-contract.md의 202 state 목록. 실제 백엔드 업로드는 돌리지 않았다 (1103/01-01). - 백엔드로 넘김:
RateLimitInterceptor가 비동기 재디스패치에서도 평가되면 503 rate-limit이 쓰기 뒤에도 나올 수 있다. 요청은DispatcherType.REQUEST에서만 평가하기다. 지금 백엔드에는 그런 쓰기 컨트롤러가 없다 (1105/03-02). - 일부: poll 조합 코드가
input.operation을 무시하고 다른 descriptor를 넘기면 attempt마다 요청이 최대 3번이다 (1103/04-01). - 일부: Service Worker 활성화 화면(
onUpdateWaiting·requestActivation())과 reload 안내를 이을 제품 소유 자리가 없다. realtime·Web Worker·오프라인 명령 선택은 조립이 거절한다 (1103/09-05). - 일부: 짝 백엔드 표 사본과 백엔드 문서의 일치, 생성기 템플릿 변경은
check:backend-contract-drift(게이트 밖, 옆 checkout 필요)만 본다. Fileserver 자신의 code 표는 pin 대조 밖이다 (1105/07-01, 1105/16-02, 1105/01-02). - 일부: 실행 격리는 브라우저 테스트 실행까지다. 게이트와 증거 검사는 기본 경로만 읽고, 선택이 다른 두 실행은
src/.generated를 서로 바꾸고, Storybook 캐시는 공유한다 (1105/12-04). - 일부: 쿠키 세션 handler를 잇지 않은 제품은 여전히 세션 만료를 모르고, 막는 검사는 없다. 세션 owner recipe는 실제 Keycloak·Redis에 붙여 보지 않았다 (1105/09-02).
- 일부: 아래 절 "옮기기 전" 목록(0929/14-03 포함), 루트 작업 기록 위치, README 범위 동기화 명령은 문서만 고쳤고 명령은 실행하지 않았다 (1103/14-02, 0929/14-01, 0929/14-02).
미출시(main 409d72e에 합침) — 752a61f → 브랜치 fix/maturity-review-2026-11-03
한 번의 동기화로 받는 변경의 순 요약이다. 범위는 main 752a61f부터 브랜치 fix/maturity-review-2026-11-03의 끝까지다. 이 절을 쓸 때 끝은 f887817이었다(병합 커밋을 빼고 310개). 그 뒤 깨끗한 clone 검증(merge 단계 14개)에서 찾은 수정과 pin 갱신을 더했다. 버전 번호와 태그는 아직 정하지 않았다.
이 묶음은 세 갈래를 합쳤다.
fix/ui-design-audit-2026-11-01: 2026-11-01 UI 디자인 감사(docs/reviews/2026-11-01-ui-design-audit.md, IDUI-NN)와 2026-11-01 성숙도 리뷰(docs/reviews/2026-11-01-maturity-review/) 조치.claude/happy-easley-233d07: 짝 백엔드 Envelope 읽기, V2 HTTP 경로 삭제, 거절 판정 표, 쿠키 쓰기 CSRF, KEYED 재전송. 앞 갈래와e40684b에서 합쳤다.- 2026-11-03 성숙도 리뷰(
docs/reviews/2026-11-03-maturity-review/) 조치 브랜치 11개.fix/maturity-review-2026-11-03에서 합쳤다.
읽는 법:
- 최종 상태만 적는다. 같은 범위 안에서 뒤 커밋이 다시 바꾼 중간 상태는 적지 않는다. 예를 들어 V2 클라이언트를 고친 커밋들은 V2를 지운 행 하나로 남겼다. 중간 기록은 커밋 이력에 있다.
- 이 repo의 커밋 해시는 기준점
752a61f·af3d8e6을 빼면 모두 이 범위에 있다. 브랜치 끝에서 닿고752a61f에서는 닿지 않는다. 다른 repo의 커밋(다운스트림, 짝 백엔드)은 repo 이름과 함께 적었다. - 두 다운스트림(tech-log-frontend, memento-frontend)의 기준점은
af3d8e6이다.af3d8e6과752a61f사이에는 리뷰 문서만 있다. 그래서 두 제품이 받을 변경은 이 절과 같다.
먼저 할 일 (BREAKING)
복사한 프로젝트가 이 묶음을 받을 때 순서대로 한다. 단계 끝의 괄호는 아래 표의 근거 행이다. 두 다운스트림에서 읽은 모양(memento-frontend d3810a0, tech-log-frontend 7a4e201a, 2026-11-05)을 단계마다 적었다. 템플릿은 이 안내를 두 제품 코드에 적용해 게이트를 돌려 보지는 않았다(알려진 제한).
옮기기 전
- 기준점을 확인한다. memento는
.template-origin, tech-log는template.lock.json의sourceRevision에 있다. 둘 다af3d8e6이다. - 제품이 고친 템플릿 파일을 뽑는다. 이 묶음은 그 일을 받을 제품 소유 파일을 새로 둔다(옮기는 법 2단계). 템플릿 파일을 고친 채로 두면 동기화마다 충돌한다.
- memento:
src/bootstrap/runtime-adapters.ts,src/features/feature-adapter-contribution.ts(capabilityoffsetUpload·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 WorkerACTIVE),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 라우터). - 위 목록은 일부다.
af3d8e6뒤 두 제품이 고친 템플릿src파일(기능·context 폴더 밖,git diff --name-status af3d8e6 HEAD -- src)은 memento 26개(수정 23, 추가 3), tech-log 40개(수정 38, 추가 2, 그 밖에 삭제. 추가 중reference-feature/NOT_INSTALLED는 옮기는 법 1단계)다. 2026-11-05에 두 repo의 diff를 읽어 나눴다(1103/14-02). - 제품 소유 자리가 있는 것. tech-log
src/contracts/release-artifacts.ts의TECH_LOG_STUDIO_SOURCE·TECH_LOG_PUBLIC_SOURCE필드는PRODUCT_RUNTIME_CONFIG_FIELDS로 간다(옮기는 법 2단계). mementosrc/adapters/http/offset-upload.ts(추가)와src/adapters/http/index.ts의 그 export는 capabilityoffsetUpload를 만드는 제품 코드라src/bootstrap/product-composition.ts쪽 제품 파일로 옮기고 HTTP 배럴은 템플릿 것으로 되돌린다. tech-log의 라우팅 파일(src/contracts/routes.ts·route-runtime-contract.ts의layoutGroup과 플랫폼 라우트 삭제, 참조 기능 계약reference-feature-contract.ts의layoutGroup,src/presentation/routes/6개와 추가route-url-builder.ts)은 직접 조립의 일부라 3단계 끝의 기능 모듈 길로 바꾸면 템플릿 것으로 돌아간다. - 제품 소유 자리가 아직 없는 것. 템플릿이 자리를 정하지 않았다. 동기화 때 충돌하거나 제품이 고친 채로 남는다(알려진 제한). memento: 요청 헤더
if-match(http-contract-bridge.ts,http-execution-v3.ts. V3 descriptor에는 요청 헤더 칸이 없다), Service Worker 오프라인 navigation shell(service-worker-lifecycle.ts)과 사전 캐시 확장자.html·.jpg(service-worker-static-manifest.ts), 저장소 이름APP_NAMESPACE(storage-keys.ts)와 OPFS 이름(opfs-policy.ts,indexeddb-opfs-journal.ts), 앱 이름 문구(catalog.ts의common.appName·route.APP_HOME.title), 브랜드 토큰·글꼴·primitive(design-system/tokens/CSS 3개와token-contract.ts,primitives/core.tsx,design-system/index.ts,styles/theme.css, 추가 폴더design-system/memento/). tech-log:AppFailure.detail(errors.ts,feature-http-binding.ts),BoundMutation.identity(server-state.ts)와 그것을 쓰는application-query.ts,deriveAsyncState와 조회 훅이null을 데이터 없음이 아닌 빈 상태로 보는 것(async-state.ts,application-query.ts), 폼(use-app-form.ts의 select,use-dirty-navigation-guard.tsx), 디자인 시스템(primitives/core.tsx·forms.tsx·navigation.tsx,patterns/common-patterns.tsx,design-system/index.ts,page-templates.tsx,app-shell.tsx), 문구(catalog.ts,message-contract.ts), 전역 글꼴·스타일 import(src/bootstrap/main.tsx). - 템플릿 결함 후보. tech-log
application-query.ts는 마운트한 같은 이벤트 턴에 저장하면 결과 불명 채널이 아직 없어 거절되던 것을 고쳤다(채널을 제출 때도 얻는다). 템플릿은 이것을 재현하지 않았다.
- memento:
- 기능마다 HTTP descriptor를 센다. method,
retrySemantics,responseEnvelope, 입력·응답·실패 검증기의 schemaId, 그 검증기가 zod인지. 옮기는 법 4·5단계의 작업량이 이 숫자로 정해진다.- memento-web: descriptor 29개. 입력·응답 schemaId 42개와 실패 본문
MementoProblem1개. 검증기는 zod가 아니라 손으로 쓴isRecord검사다.responseEnvelope는 없다. GET은SAFE, 쓰기는KEYED·IDEMPOTENT·NEVER다. - TechLog: 검증기는
zodValidator다. 출력은 Envelope 뼈대만 검사하고 본문은 통과시킨다.responseEnvelope는 없다. GET은SAFE, 쓰기는KEYED나NEVER(둘 다retryBudget0)다.
- memento-web: descriptor 29개. 입력·응답 schemaId 42개와 실패 본문
- 지금 게이트 결과를 남긴다. 동기화 뒤의 실패가 원래 있던 것인지 가르는 데 쓴다. 두 제품의 지난 동기화 기록(
docs/operations/template-sync-2026-09-29.md)과 같은 목록이면 된다.
옮기는 법
-
기능이 아닌 폴더의 표시.
src/features/<dir>/NOT_INSTALLED를 같은 자리의NOT_A_FEATURE로 바꾼다. 생성기는NOT_INSTALLED를 더는 읽지 않는다. 표시와feature-module.ts가 한 폴더에 있으면 생성기가 실패한다.- memento:
local-draft-feature. 템플릿 폴더라 병합으로 바뀐다. - tech-log:
tech-log,reference-feature,local-draft-feature.reference-feature는 템플릿이 그 폴더에 둔feature-module.ts·feature-runtime.ts·context-routes.ts를 받지 않는다. (1103/09-09)
- memento:
-
제품 코드를 제품 소유 파일로 옮긴다. 템플릿은 아래 파일을 비워서 내보내고, 복사한 뒤에는 고치지 않는다. 제품 코드를 여기로 옮기고 "옮기기 전" 2단계의 템플릿 파일은 템플릿 것으로 되돌린다.
src/contracts/product-contracts.tsPRODUCT_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.tscomposeProductSessionOwner(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(mementooffsetUpload·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.tsProductFeaturePlatformCapabilities: 제품 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 WorkerACTIVE선택이 여기 온다.
config/ci/product-gates.json: 배포(deployment)와 제품 merge 검사(mergeGates, IDPRODUCT-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)
-
기능을 선언과 실행부로 나눈다. 기능 하나가 초기 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)로 적재한다.
순서:
- 기능 계약에서 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개)는 새 메타데이터 파일로 간다. - 선언 계약에
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.md2절이다. - route codec을
context-routes.ts의 각 routehandle.codecs로 옮긴다(참조:presentation/reference-route-codecs.ts의REFERENCE_FEATURE_ROUTE_CODECS). 플랫폼 codec과 같은 id는 쓸 수 없다.*-runtime-descriptor.ts와src/features/installed-feature-runtimes.tsx는 없어졌다. feature-runtime.ts를 만들고,feature-module.ts에서adapters·contractContributions·runtimes를 지운 뒤loadRuntime: async () => (await import("./feature-runtime.ts")).FEATURE_RUNTIME을 넣는다.feature-runtime.ts를 어디서도 정적으로 import하지 않는다. 그러면 실행부가 다시 초기 청크에 들어간다.featureId가 모듈 id와 다르면 적재 때 실패한다.- runtime descriptor에 붙인 제품 칸은 context로 옮긴다. memento-web의
ownsShell: true와app-router.tsx다리는src/contexts/memento-context/context-layout.tsx의CONTEXT_LAYOUT이 대신한다. 레이아웃은 skip link와<main id="main-content" tabIndex={-1}>하나를 그린다.tests/component/layout-landmarks.test.tsx가 설치된 레이아웃을 모두 검사한다. memento-web은 이미 route idAPP_HOME을 선언하므로 그것만으로 플랫폼 홈을 대신한다.installed-feature-contracts.ts의FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS다리는 지운다. - 기능 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이 막는다. 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 묶음은 자기 레이아웃을 가진studiocontext가 된다. 이 모양은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) - 선언(
-
HTTP descriptor 조립 규칙. 계약 조립(
composeContractContributions)이 아래를 어기는 기여를 거절한다. 메시지는Installed contract contribution is not composable: <reason>이다.- GET·HEAD의
retrySemantics는SAFE나IDEMPOTENT다. 재시도를 막으려면retryBudget: 0. - POST·PUT·PATCH·DELETE에는
SAFE를 쓸 수 없다.IDEMPOTENT,KEYED(commandRecovery필요),NEVER(retryBudget0) 중 하나다. - 계약 기여 하나 안의 operation은 모두 같은
responseEnvelope를 읽는다. 값이 없는 것과"NONE"은 같다. 두 백엔드를 쓰면 기여를 나눈다. - 쿠키 인증 프로필로 쓰기를 하면 그 프로필이
x-csrf-token이나x-xsrf-token을requiredCredentialHeaders로 요구해야 한다. commandEffect.refusedBeforeWrite(쓰기 전에 나는 업무 거절 code 목록)는responseEnvelope: "ENVELOPE_V1"operation에만 쓴다.IDEMPOTENT_*·IDEMPOTENCY_*code는 적을 수 없다.
두 다운스트림의 지금 descriptor는 앞의 넷을 지킨다. memento의 쓰기 프로필
MEMENTO_BFF_WRITE는x-xsrf-token을, TechLog의TECH_LOG_STUDIO_SESSION은x-csrf-token을 요구한다.responseEnvelope가 없는 operation의 적용 여부는 지금처럼classifyProblem이 정한다.뮤테이션:
useApplicationMutation은useServerStateScope()의 scope를 담은BoundMutation만 받는다. memento-web의 뮤테이션 8곳과 TechLog는 이미 그 모양이다.operationId·requiresIdempotencyKey는commandMutationIdentity(<descriptor>)로 받을 수 있고, 그러면 오타를 타입 검사가 잡는다.BoundMutation.owner와QueryDefinition.owner·operationId는@deprecated선택 칸이 됐고 다음 릴리스에서 지운다. (1103/07-01, 1103/03-03, 1103/16-01, 1103/07-02, 1103/03-01, 1101/08-03, 1103/16-05, 1103/16-06) - GET·HEAD의
-
레지스트리 행과 기준선.
- 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,MementoProblem1)을 더한다. 없으면check:registries가 operation마다FE-REG-API.<operationId>.requestSchema references unknown FE-REG-SCHEMA.schemaId=<id>로 실패한다. - 행의 칸:
boundary는 쓰인 자리대로 적는다(api-request입력,api-response응답,api-problem실패 본문,route-params,route-search,route-search-api-request).direction은 입력이REQUEST, 응답·실패 본문이RESPONSE다.unknownFieldPolicy는 적으면 검증기 동작과 같아야 한다.tests/unit/schema-metadata-policy.test.ts(test:unit)가 설치된 기능 전부를 대조한다. runtime은"zod"만 받는다. 손으로 쓴 검증기를 그대로 두고"zod"라고 적으면 행이 사실과 다르다. memento-web의 검증기는zodValidator(schemaId, schema)(src/contracts/zod-validator.ts)로 옮긴다. 지금 검사하는 만큼(객체인지,items가 배열인지)만 옮겨도 된다. 일부러 검증하지 않을 칸은unvalidatedPayload(schemaId, reason)로 바꾼다. 그 칸은 FE-REG-API 행의unvalidated와 플랫폼 구성 화면에 드러난다. governance의runtime허용값을 제품 쪽에서 넓히지 않는다.- 다 맞춘 뒤 기준선을 한 번 다시 승인한다. FE-REG-API governance가 바뀌어 동기화 직후
check:registries가contract-field-changed로 실패하기 때문이다.REGISTRY_BASELINE_OWNER=<owner> REGISTRY_BASELINE_REASON="<이유>" corepack pnpm update:registry-baseline. 지금 diff와 맞지 않는 옛 breaking 증거 행도 이 명령이 지운다. (1103/07-01, 1103/16-04, 1103/07-03, 1101/07-03, 0929/07-01)
-
쓰는 곳이 있을 때만.
- 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)은 이 기능 폴더,tests/features/platform-examples-feature/,src/contexts/platform-examples-context/를 지우고corepack pnpm generate:feature-index를 돈다. 지우기 전에corepack pnpm test:sample-removal -- --feature=platform-examples-feature가 사본에서 같은 삭제로 게이트를 돈다. 템플릿 문서가 지운 폴더를 계속 적어도verify:documentation과 FE-GATE-005가 통과하는 것은 위 절의 수정부터다(1105/14-01). 그래서 두 절을 함께 받는다. 예제 화면을 여는 제품 테스트는 그 기능을 설치해 두거나 제품 화면으로 옮긴다. 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)
- V2 HTTP 클라이언트와 V2 API 행에서 지운 이름(아래
-
초기 JS 예산. 예산은 gzip 204,800 B와 초기 파일 32개다(
config/performance/budgets.json, merge 게이트 FE-GATE-012의check:bundle). 템플릿 자체가 202,927 B와 파일 26개를 쓴다. 여유는 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)
옮긴 뒤 확인
- 로컬 merge 게이트 14개를 돈다(README "CI and evidence"의 반복문).
config/ci/product-gates.json에 적은PRODUCT-GATE-NNN은 workflow의product_merge_gatejob이 돈다. - 그중 이 묶음 때문에 먼저 볼 것:
check:registries:11 registries PASS. 기준선을 다시 승인한 뒤에는compatibility=none.test:unit:schema-metadata-policy,env-registry-coverage,feature-shape-growth,documentation-readiness(문서 검사. 참조 기능을 지운 제품도 통과한다).test:component:layout-landmarks,context-layouts.build뒤check:bundle: 예산 안.
- merge 게이트 밖에서 한 번 돈다.
verify:documentation(FE-GATE-017, documentation 단계). merge 단계에서는 FE-GATE-005의documentation-readiness가 같은 스크립트를 돈다.test:sample-removal -- --feature=<제품 기능 id>: 그 기능을 지운 사본이 게이트를 통과한다. FE-GATE-020은 참조 기능만 지워 본다.
- 배포가 있는 제품: FE-GATE-019는 TLS ALPN
h2와 entry 응답의Content-Encoding(br·gzip·zstd)을 요구한다. HTTP/1.1이나 압축하지 않는 호스트는 FAIL이다.
보안·계약 변경
기능 구조와 조립
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] BREAKING | 기능을 선언(feature-module.ts)과 실행부(feature-runtime.ts)로 나눴다. 위 "먼저 할 일" 3단계. ApplicationApi.features에 load(featureId)가 생겼다. *-runtime-descriptor.ts와 src/features/installed-feature-runtimes.tsx는 없다 (1101/15-01) |
src/features/, src/application/ports/in/application-api.ts, src/presentation/routes/, vite.config.ts, .dependency-cruiser.json |
298201f |
| [계약] BREAKING | 기능이 아닌 폴더의 표시는 NOT_A_FEATURE다. NOT_INSTALLED는 읽지 않는다. 표시와 feature-module.ts가 함께 있으면 생성기가 실패한다 (1103/09-09) |
scripts/generate-product-feature-index.ts, src/features/*/NOT_A_FEATURE |
9edc830 |
| [계약] | 제품 코드는 템플릿 파일이 아니라 제품 소유 파일에 둔다. src/bootstrap/product-composition.ts(capability, 인증 프로필별 자격증명 provider, composeProductSessionOwner, 선택 onCredentialRejected·scopeParticipants), src/contracts/product-contracts.ts(제품 인증 프로필, 런타임 설정 키, 그 FE-REG-ENV 행), src/features/product-capabilities.ts(capability 타입 ProductFeaturePlatformCapabilities, 선택 런타임 PRODUCT_RUNTIME_CAPABILITY_SELECTION). 자격증명 순서는 scope fence → ANONYMOUS → 제품 provider → 세션 → fence 재확인이다. 제품 설정 키는 .default()나 .optional()이어야 템플릿 테스트가 통과한다 (1101/09-02, 1103/09-02, 1103/09-05) |
src/bootstrap/product-composition.ts, src/bootstrap/product-composition-contract.ts, src/contracts/product-contracts.ts, src/features/product-capabilities.ts, src/features/installed-runtime-capabilities.ts |
da1e128, ece944d, 245f428, 2f6df14, 2963c6f |
| [계약] | 런타임 설정 키마다 FE-REG-ENV 행이 있어야 하고, 행의 required·defaultValue가 스키마와 같아야 한다(tests/unit/env-registry-coverage.test.ts). 템플릿 행 RELEASE_ID·BUILD_ID를 더했고 TELEMETRY_ENABLED·AUTH_MODE·RELEASE_MANIFEST_URL·CAPABILITY_OVERRIDES·FEATURE_OVERRIDES 행을 스키마에 맞췄다. defaultValue는 객체일 수 있다 (1101/09-02, 1103/13-04) |
src/contracts/env.ts, config/contracts/registry-governance.json, tests/unit/env-registry-coverage.test.ts |
d0414c8, a144b57 |
| [계약] | 기능 어댑터 기여는 실행 중에도 needs에 적은 capability만 받는다. cast로 다른 capability를 읽던 기능은 undefined를 받는다 (1103/09-08) |
src/features/feature-adapter-contribution.ts |
e7d6358 |
| [계약] | 기능 계약이 route id APP_HOME을 선언하면 플랫폼 홈을 대신한다. 둘이 선언하면 두 기능 id를 적고 실패한다. src/contexts/<context>/context-layout.tsx가 CONTEXT_LAYOUT을 내보내면 그 context의 라우트가 AppShell 대신 그 레이아웃 아래에 놓인다. 레이아웃은 skip link와 <main id="main-content" tabIndex={-1}> 하나를 그려야 하고, tests/component/layout-landmarks.test.tsx가 설치된 레이아웃을 모두 실행해 본다 (1101/09-03) |
src/contracts/routes.ts, src/contexts/bounded-context-module.ts, scripts/generate-product-feature-index.ts, tests/component/layout-landmarks.test.tsx |
ca16187, 27f4523 |
| [계약] | 앱 조립이 닿지 않는 기능 라우트를 앱 모듈을 평가할 때 throw로 거절한다. 소유 context 루트 밖의 라우트, 계약에 없는 route handle, 플랫폼 라우트가 먼저 받는 경로, 다른 기능과 같은 경로(파라미터 이름만 다른 것과 대소문자·끝 슬래시만 다른 것 포함)다. 시작할 런타임이 없는 선택 capability(realtime·webWorkers·offlineCommands)도 거절한다 (1101/09-06, 1101/09-07, 1103/08-04, 1101 README 14.4) | src/apps/deployable-app-module.ts, src/contexts/bounded-context-module.ts, src/bootstrap/ |
7139c7c, d6e4e51, 7d85589, 8469554, 851fded, 48a4074 |
| [계약] BREAKING | 예제 화면 EXAMPLES_UI·EXAMPLES_STATES·EXAMPLES_AUTH가 끌 수 있는 기능 platform-examples-feature(context platform-examples-context, 루트 examples/*)로 옮겼다. 페이지 파일은 그 기능의 presentation/에 있다. PLATFORM_ROUTE_REGISTRY·PLATFORM_ROUTE_RUNTIME_CONTRACT·PLATFORM_ROUTE_RUNTIME에서 키가 빠졌다. 홈 문구 home.starter.platform·ui·states는 home.starter.open({title})로 바뀌었다. 예제를 지운 제품은 이 기능 폴더, 그 테스트 폴더, context를 지운다(위 "먼저 할 일" 6단계). /examples/platform은 플랫폼 라우트로 남는다 (1103/09-04) |
src/features/platform-examples-feature/, src/contexts/platform-examples-context/, src/contracts/routes.ts |
b96d61d |
| [계약] | 계약 기여의 출처는 EXTERNAL_PACKAGE이고, TEMPLATE_FIXTURE는 참조 기능만 하나 쓸 수 있다. 다른 출처 종류는 unknown contribution source kind로 거절한다 (1101/07-04) |
src/contracts/external-contract-runtime.ts |
c063389 |
| [계약] BREAKING | useApplicationMutation은 raw { execute, definitionId }를 받지 않는다. useServerStateScope()의 scope로 만든 BoundMutation을 넘기고 execute(input, { signal, intent })로 부른다. commandMutationIdentity(<descriptor>)가 operationId·requiresIdempotencyKey를 descriptor에서 준다. QueryDefinition.owner·operationId와 BoundMutation.owner는 아무도 읽지 않아 @deprecated 선택 칸으로 바꿨고 다음 릴리스에서 지운다. raw query는 남았다. 세션이 바뀌면 이전 결과가 보이지 않는다(JSDoc에 위험 표기) (1101/08-03, 1103/16-05, 1101/03-03, 1103/16-06) |
src/presentation/adapters/query/application-query.ts, src/presentation/adapters/query/ |
1fa5f3e, f59a806, 68f94f5 |
HTTP와 계약
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] BREAKING | V2 HTTP 클라이언트를 지웠다. HTTP 경로는 V3 실행기 하나다. 배럴(src/adapters/http/index.ts)에서 createHttpClient, HttpClient, HttpClientDependencies, HttpFailure, HttpResult, LegacyHttpInput, Scheduler, OperationRequestInput가, src/bootstrap/runtime-adapters.ts에서 createRuntimeHttpClient, RuntimeHttpContract가 없어졌다. 지운 파일: client.ts, bounded-json.ts, request-builder.ts, resource-mapper.ts, retry-policy.ts, schema-registry.ts(src/adapters/http/). Envelope 스키마는 backend-envelope.ts에 있다. V2 클라이언트를 부르는 코드는 그 operation의 V3 descriptor를 만들어 createFeatureHttpBinding으로 실행한다 |
src/adapters/http/, src/bootstrap/runtime-adapters.ts, scripts/drill-runbook.ts |
048f490 |
| [계약] BREAKING | 기능마다 적던 V2 API 행을 지웠다. FE-REG-API 행은 contract contribution의 V3 descriptor에서 뽑는다(src/contracts/api-operations.ts의 projectApiOperationRows, 22칸: operation·경로·인증·재시도 의미·본문 모양·Envelope·스키마 세 개·acceptedStatuses·emptyBodyStatuses·unvalidated·바이트 상한 둘·totalDeadlineMs·retryBudget·traffic·commandEffect·commandRecovery). problemSchema도 FE-REG-SCHEMA를 참조하고, 그 행의 boundary는 새 값 api-problem이다. problemSchema·unvalidated 변경과 status 값 제거는 breaking이다. FeatureRuntime은 apiContract 대신 schemas(FE-REG-SCHEMA 행)를 받는다. 지운 이름: defineRestOperation, ApiOperation, RestOperationV2, composeApiOperations, validateApiRuntimeBindings, getApiOperation, contracts의 API_OPERATIONS; rest-profiles.ts의 createRestProviderProfile, RestProviderProfile, resolveRestSecurityProfiles, validateRestProfileBindings, REST_CSRF_PROFILES, RestCsrfProfile; loaded-feature-runtimes.ts의 RUNTIME_SCHEMA_CODECS, MAPPER_REGISTRY, REST_PROFILE_BINDINGS_VALID, API_RUNTIME_BINDINGS_VALID. realtime apiOperations 바인딩은 ApiOperationRow를 받고, snapshot operation을 method: "GET"과 SAFE·IDEMPOTENT로 본다. 옮기는 법은 위 "먼저 할 일" 3·5단계 (1103/07-01, 1103/16-04) |
src/contracts/api-operations.ts, src/contracts/schema-registry.ts, src/features/feature-module.ts, src/features/installed-feature-runtime-registries.ts, config/contracts/, scripts/create-feature.ts |
12f3bb7, 08ed0a0, 3b40f73 |
| [계약] BREAKING | 재시도 의미를 조립 때 검사한다. GET·HEAD는 SAFE·IDEMPOTENT만, POST·PUT·PATCH·DELETE는 SAFE를 쓸 수 없다 (1103/07-01, 1103/03-03) |
src/contracts/external-contract-runtime.ts |
e4caafd, 61f70cb |
| [계약] | 계약 기여 하나 안의 operation이 서로 다른 responseEnvelope를 읽으면 조립이 거절한다. 두 백엔드는 기여를 나눈다 (1103/16-01) |
src/contracts/external-contract-runtime.ts |
3f7e10c |
| [보안] [계약] | 쿠키 인증 프로필(SAME_ORIGIN_COOKIE)로 쓰기(GET·HEAD 밖)를 하는 operation은 그 프로필이 x-csrf-token이나 x-xsrf-token을 requiredCredentialHeaders로 요구해야 한다. 아니면 조립이 거절한다. POST·PUT·PATCH·DELETE × 두 헤더 표로 테스트한다 (1103/07-02) |
src/contracts/external-contract-runtime.ts |
365d8c3, a94006b |
| [계약] | V3 descriptor의 선택 칸 responseEnvelope: "ENVELOPE_V1"이면 실행기가 짝 백엔드 Envelope({success, data|error, meta})를 읽는다. outputValidator는 data(키가 없으면 null), problemValidator는 error를 받는다. meta.requestId·traceId는 선택이다. 성공 status의 Envelope 아닌 본문은 새 위반 ENVELOPE_MISMATCH다(HttpContractViolationKind에 추가). create:feature가 만든 기능은 이 값을 선언한다. 참조 기능과 값이 없는 descriptor는 DTO와 problem details를 읽는다 (1101 README 14.3) |
src/contracts/external-contract-runtime.ts, src/adapters/http/, scripts/create-feature.ts, tests/mocks/handlers/http-scenarios.ts |
7db32e1, bd83b49 |
| [계약] | Envelope operation의 400·409·422와 백엔드가 정한 5xx 넷은 classifyProblem 대신 백엔드 기준 표(backend-envelope.ts, 근거는 계약 문서 6.1절)가 정한다. 적용 안 됨(NOT_APPLIED)은 400 VALIDATION_FAILED(details 모양과 상관없음), 400 IDEMPOTENCY_KEY_INVALID, 422 IDEMPOTENT_REQUEST_MISMATCH와 그 operation의 refusedBeforeWrite code다. 그 밖의 400·409·422는 결과 불명이다. 503 IDEMPOTENCY_UNAVAILABLE, 503 IDEMPOTENCY_COMPLETION_UNKNOWN, 500 IDEMPOTENCY_RECOVERY_REQUIRED, 503 REQUEST_TIMEOUT은 분류기와 상관없이 결과 불명이고 키를 지킨다. KEYED operation은 503 IDEMPOTENCY_UNAVAILABLE을 retryBudget 안에서 같은 키로 다시 보낸다. 필드 목록이 있는 거절은 VALIDATION_REJECTED와 필드 오류, 필드 목록 없는 422는 UNKNOWN_CLIENT_FAILURE다. 진단은 두 멱등성 거절에 reason을 싣는다 (1101 README 14.4, 1103/03-04, 1103/08-05) |
src/adapters/http/backend-envelope.ts, src/adapters/http/http-execution-v3.ts, docs/architecture/backend-api-and-server-state-contract.md |
3261208, c05f41a, 3761507, 613c1cf |
| [계약] | CommandEffectDescriptor.refusedBeforeWrite(선택, Envelope operation 전용): 그 엔드포인트가 쓰기 전에만 내는 업무 거절 code. 적은 code의 400·409·422는 NOT_APPLIED라 폼에서 값을 고쳐 다시 저장할 수 있다. 멱등성 code를 적거나 Envelope가 아닌 operation에 적으면 조립이 거절한다 (1103/03-01) |
src/contracts/external-contract-runtime.ts, src/adapters/http/backend-envelope.ts, src/contracts/api-operations.ts |
1e8b3d0, 3fba68b |
| [계약] | 짝 백엔드 계약 기준점을 기계가 읽는다. config/contracts/backend-contract-pin.json(백엔드 45d2a478)과 백엔드 docs/web/http-contract.md §2 답 표(config/contracts/backend-idempotency-answers.json)를 tests/unit/backend-contract-pin.test.ts가 프론트 판정 표와 대조한다. check:backend-contract-drift --backend <백엔드 checkout>(로컬, 게이트 밖)이 pin 뒤의 백엔드 변경을 알린다 (1103/12-06) |
config/contracts/, scripts/check-backend-contract-drift.ts, src/adapters/http/backend-envelope.ts |
ba2b4f4, 5379c80 |
| [계약] | 성공 결과에 Envelope meta.page가 page로 실리고, mapSuccess 두 번째 인자 FeatureHttpSuccessContext { page }로 받는다(배럴 EnvelopePage). bulk results는 지원하지 않는다. 실패 Envelope의 meta.traceId는 AppFailure.traceId가 된다. 실행 결과의 선택 칸 sentRequestId: 서버가 x-correlation-id를 돌려주지 않으면 AppFailure.requestId는 보낸 값이고, 결과 불명·조회 실패 화면에 "지원 참조" 줄이 보인다 (1103/03-02, 1103/03-06, 0929/03-04) |
src/adapters/http/ |
49a0986, 631ce33, 849d000 |
| [계약] | 결과 불명 쓰기의 진단·텔레메트리에 effect_certainty가, 진단 reason에 UnknownEffectReason이 실린다 (1103/03-05) |
src/adapters/http/, config/contracts/ |
39c1de2 |
| [계약] | 키 없는(NEVER) 결과 불명 요청에는 "같은 요청으로 다시 보내기"가 없다. mutation 컨트롤러 canResendUnknownEffect, AsyncState.unknownEffectResendable. 처리 중 409의 Retry-After는 retryAfterMs로 실리고, 결과 불명 요청을 같은 키로 다시 보낼 때 그 시각까지(최대 5초) 기다린다 (0929/03-03, 백엔드 리뷰 1101/02-01) |
src/presentation/adapters/query/application-query.ts, src/presentation/components/async-surface.tsx |
2017ef7, 47fec5c |
| [계약] | 전송 전 거절의 원인이 진단에 남는다. 연결 실수·멱등 키 위반은 UNKNOWN_CLIENT_FAILURE이고 화면 문구는 "요청을 처리할 수 없습니다."다 (1101/03-02) |
src/adapters/http/ |
4da0466 |
| [계약] | 참조 기능의 생성 분류기가 409를 problem code로 나눈다. 선언한 충돌 code(CONFLICT)만 적용 안 됨이고, IDEMPOTENT_IN_FLIGHT·code 없는 409·모르는 409는 결과 불명이라 다음 전송이 같은 멱등 키를 쓴다 (0929/03-01) |
src/features/reference-feature/contracts/reference-feature-contract-contribution.ts |
112c870 |
| [계약] | 인증 프로필 REFERENCE_EXTERNAL_BEARER의 새 이름은 EXTERNAL_BEARER다. 옛 이름은 한 릴리스 동안 @deprecated 별칭으로 남는다. CREDENTIAL_HEADER_NAMES에 짝 백엔드 CSRF 헤더 x-xsrf-token을 더했다 (1101/16-03, 1101/09-02) |
src/contracts/rest-profiles.ts |
6c5818f, 183a4a3 |
| [계약] | zodValidator(src/contracts/zod-validator.ts)가 zod 스키마를 RuntimeValidator로 바꾼다. 검증을 일부러 생략할 때는 unvalidatedPayload(schemaId, reason)를 쓴다. listUnvalidatedPayloads(composed)가 생략 목록을 만들어 플랫폼 구성 화면이 보여 준다 (1101/07-03) |
src/contracts/zod-validator.ts, src/contracts/unvalidated-payload.ts |
d3ddc89, 8b7c6eb |
| [계약] | 폐기 별칭 MappingResult(boundary-mapper.ts)와 ApiFailure(errors.ts)는 export로 남지만 lint가 src·tests의 import를 막는다. BoundaryMappingResult, AppFailure로 바꾼다 (1101/07-01) |
eslint.config.ts, src/contracts/boundary-mapper.ts, src/contracts/errors.ts |
fc303d8 |
레지스트리
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | breaking 증거(config/contracts/registry-change-evidence.json)에 after가 필요하고 diff의 after 값과 같아야 한다. 지금 diff와 맞지 않는 증거 행은 check:registries가 적고 실패하며, update:registry-baseline이 그런 행을 지운다 (0929/07-01) |
scripts/lib/registry-compatibility.ts, scripts/update-registry-baseline.ts, docs/operations/ci-quality-gates.md |
5e6be9a, 4ada84e |
| [계약] | 분류기가 덜 깐깐해졌다. 선언 타입 안의 null ↔ 값 전환은 breakingFields로 등급을 정하고(보통 behavior-change), allowedValues에 값을 더하기만 하면 additive다. 무효화 그래프에 원소를 더하기만 한 변경도 additive다. 빼거나 바꾸면 그대로 breaking이다 (0929/07-02) |
scripts/lib/registry-compatibility.ts, scripts/check-registries.ts |
82c9e59, 605fd17 |
| [계약] | FE-REG-ROUTE가 paramsSchema·searchSchema를 허용 목록으로 보지 않고, loadingSurface는 kebab-case 형식만 본다. 기능 라우트를 더해도 governance를 고치지 않는다. 다운스트림은 목록에 더해 둔 값을 지운다 (0929/07-03) |
config/contracts/registry-governance.json, scripts/check-registries.ts |
e8d7fb4 |
| [계약] | StorageBackend에 "external"이 생겼다. cross-context pulse 키는 외부 소유라 StoragePort로 읽고 쓰면 *_UNAVAILABLE로 거절된다. exhaustive switch는 분기를 더한다 (1101/05-01) |
src/contracts/storage-keys.ts, config/contracts/ |
e98a980, 65ea208 |
| [계약] | 진단 ui.render.failed의 route_id: 등록 라우트가 없는 URL의 적재 실패는 NOT_FOUND 대신 UNREGISTERED_ROUTE, 복구하지 못한 context 라우트 청크 실패는 context id 대신 그 라우트 id다. 이 값으로 거르는 대시보드·알림은 고친다 (1101 README 14.3) |
src/presentation/routes/, src/contracts/routes.ts |
7c8cb19 |
세션·인증
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 401은 그 요청의 자격증명을 낸 쪽에만 알린다. 템플릿 세션이 낸 자격증명의 401만 세션을 로그아웃시키고 캐시를 비운다. ANONYMOUS 요청과 제품 provider 요청의 401은 ProductComposition.onCredentialRejected(선택)로 간다 (1103/09-01) |
src/bootstrap/runtime-adapters.ts, src/bootstrap/product-composition-contract.ts |
0aada28 |
| [계약] | 인증 프로필이 ANONYMOUS인 요청은 세션 상태와 상관없이 자격증명 없이 나간다. 전에는 어느 세션 상태에서도 보내지 않았다 (1101/09-01) | src/bootstrap/runtime-adapters.ts |
ddf411e |
| [계약] | ProductSessionOwnerContext에 fetch(필수. 마감 REQUEST_TIMEOUT_MS, 본문 64 KiB, redirect 거부), page(href, replaceUrl, assign), redirectStorage, readCookie가 생겼다. 짝 백엔드 두 인증 모드의 owner recipe는 recipes/session-owners/(oidc-pkce-session-owner.ts, cookie-session-owner.ts)이고 매뉴얼은 docs/manual/04-paired-backend-session.md다. src가 이 recipe를 import하면 check:optional-recipes가 PRODUCTION_IMPORTS_RECIPE로 거절한다 (1103/09-03) |
src/bootstrap/product-composition-contract.ts, recipes/session-owners/, scripts/check-optional-recipes.ts |
d02efe7, 05958bb, f3fd10f |
| [계약] | 세션 상태 전이: 복구 성공은 authenticated, no-session은 unauthenticated(또는 integration-failed), 거절은 상태 유지다. "세션 복구" 화면은 no-session이면 로그인 버튼을 보인다 (1103/09-11) | src/adapters/auth/external-session-adapter.ts, src/presentation/providers/session-provider.tsx |
d7c6cb4 |
| [계약] | ProductComposition.scopeParticipants(선택): 로그아웃·계정 전환 때 FENCED와 READY 사이에서 닫을 제품 자원. 닫기가 실패하면 READY로 가지 않는다. 예시는 recipes/frontend-capabilities/browser-file-session-capability.ts (1103/02-01) |
src/bootstrap/product-composition-contract.ts, src/bootstrap/runtime-adapters.ts, recipes/frontend-capabilities/ |
f485e51 |
저장소·파일·전송
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | OPFS journal 목록이 손상 행을 건너뛰고 corruptRows로 센다. reconcile은 corruptTransactions, 소속 partition이 없는 손상 행은 선택 칸 unattributedRows·unattributedCorruptTransactions로 따로 세고 DEGRADED 관측에서 뺀다. 승인된 LOGOUT·ACCOUNT_DELETION purge는 끝나지 않은 행을 보면 진행 중인 put을 기다린 뒤 partition을 지우고 partitionDeleted를 보고한다. partition 삭제는 partition Web Lock으로 다른 탭의 put과 겹치지 않는다. OpfsJournalPort의 countPartitionTransactions(scope)·removePartition과 worker gateway removePartition은 필수 메서드다 (0929/05-01, 1103/05-01, 1103/05-03) |
src/adapters/storage/opfs/, src/application/ports/browser-file-storage/ |
72edb55, e5b7b3e, d13a393, fd6b631 |
| [계약] | OPFS partition lock을 기다리는 put·remove는 자기 abort로 ABORTED, mutationLockWaitTimeoutMs를 넘으면 BLOCKED(retryable)다. 정책의 putIdleTimeoutMs가 mutationLockWaitTimeoutMs 이상이면 조립이 거절한다 (1103/05-02, 0929/05-09) |
src/adapters/storage/opfs/ |
7b55f0f, f6b74ed |
| [계약] BREAKING | recipe의 browser-file·OPFS·storage durability·cache 타입 중 src와 이름이 같은 34개는 src 타입을 다시 내보낸다. fake는 src port를 구현하고 BrowserDataResult를 돌려준다. MemoryDurableObjectStore 생성자가 바뀌었고 DurableObjectDataClass·DurableObjectIntegrity·DurableObjectRead·ObjectStoreRecoverySummary는 지웠다. 이 fake의 reconcile은 FILES_READY put을 runtime처럼 commit하고 LOGOUT·ACCOUNT_DELETION은 멈춘 행도 지운다. offline-indexeddb recipe를 쓰는 프로젝트만 해당 (0929/05-03, 1103/05-04) |
recipes/frontend-capabilities/ |
e1a4580, 36ff633 |
| [계약] | PublicCacheInspection.activePointer가 필수 칸이다. 손상 pointer에서도 inspect가 상태와 후보를 보여 준다. 포트를 직접 구현한 쪽은 채운다 (1103/02-05) |
src/adapters/cache-storage/public-response-cache-adapter.ts, src/application/ports/browser-file-storage/cache-storage-ports.ts |
7e7614f |
| [보안] | download 정책의 safeExtension이 위험 확장자이거나 그것으로 끝나면 조립이 거절한다 (1101/02-02) |
src/adapters/browser-files/ |
4f78890 |
| [계약] | 업로드 part 발급·PUT이 서버의 Retry-After를 기다린다. maxRetryAfterMs를 넘으면 다시 보내지 않고 upload()·abort()가 RESUME·retryable: false를 준다. 실패 결과에 대기 시간이 붙도록 포트 반환 타입이 넓어졌다(추가만). upload 실패 번역은 HTTP 상태와 code로 recovery를 고르고, part 발급(BFF)의 401/403은 NONE(retryable: false)이다. file-transfer recipe를 쓰는 프로젝트만 해당 (1101/01-01, 1103/01-02, 0929/01-01) |
src/adapters/browser-transfer/ |
95e4445, c695898, 9142390, c5f87aa |
realtime·Service Worker·Web Push
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] BREAKING | BoundedPollOperationContract(V2 어휘)를 지웠다. createBoundedPollCoordinator의 operation과 assertBoundedPollOperation의 둘째 인자는 V3 descriptor(BoundedPollOperation)다. 조립된 행을 넘기고, frontend.retryBudget 0인 poll 전용 operation을 등록한다. 0이 아니면 생성 때 거절한다 (1103/04-01) |
src/adapters/realtime/ |
a65df74 |
| [계약] BREAKING | SSE의 fetch·reader 거절과 bounded poll의 execute 거절은 OFFLINE 대신 PROVIDER_UNAVAILABLE(retryable)로 끝난다. 브라우저가 online이면 online 이벤트를 기다리지 않고 backoff로 다시 시도하고 상한에서 끝난다. poll은 이 범위 끝에서 던지는 execute를 lease 안에서 다시 시도했다. 위 절에서 다시 바뀌어, 던지는 execute는 재시도 없이 PROTOCOL_MISMATCH로 끝난다(1105/04-02). OFFLINE은 환경 신호에서만 나온다 (1103/04-04, 0929/04-01) |
src/adapters/realtime/ |
af00067, 4d27b20 |
| [계약] | stream coordinator와 live-poll handoff coordinator의 마감 실패가 IDLE_TIMEOUT 대신 APPLY_FAILED·PROVIDER_UNAVAILABLE로 나온다. stream coordinator의 RealtimeObservation.reason도 같다. IDLE_TIMEOUT은 전송 idle에만 쓴다 (1101/04-02) |
src/adapters/realtime/stream-coordinator.ts, src/adapters/realtime/ |
1196b86, 17fa8d1 |
| [계약] | realtime 배럴이 결과 생성 함수 realtimeSuccess·realtimeFailure를 내보낸다. 동결이 필요한 경계에 직접 만든 결과를 넘기던 코드는 이 함수로 바꾼다 (1101/04-01) |
src/adapters/realtime/index.ts |
3fe28de |
| [계약] | Service Worker 빌드가 public/을 다시 복사하지 않는다(publicDir: false). 전에는 SW를 켠 빌드의 dist/config.json이 local 문서로 덮어써졌다 (0929/06-01) |
vite.service-worker.config.ts, scripts/build-frontend.ts |
c7b9cb8 |
| [계약] | 라우터 base path(VITE_ROUTER_BASE_PATH)를 쓰면 Web Push 정상 클릭, SW 사전 캐시 URL, SW의 설정 URL이 모두 그 경로 아래로 간다 (1101/06-01, 0929/06-02) |
src/adapters/web-push/, scripts/generate-service-worker-assets.ts |
c67edd2, 85d55e0 |
| [보안] | Web Push registry가 URL로 해석하면 바뀌는 path(.., %2e%2e, .)를 생성 때 거절한다 (1103/06-02) |
src/adapters/web-push/ |
a145f30 |
화면·문구·디자인 시스템
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | check:design-system 규칙 4개: 두 테마에서 --color-focus가 표면 토큰 8종 모두와 3:1 이상, color-mix()는 in oklab만, 계약의 컴포넌트 토큰은 스타일 하나 이상이 var(--name)으로 읽음, --font-sans 첫 글꼴은 기본 키워드이거나 @font-face로 싣는 글꼴이거나 PRODUCT_LOADED_FONT_FAMILIES(token-contract.ts)에 있는 글꼴. deg 색상각과 시스템 글꼴 이름은 받는다 (UI-01, UI-02, UI-03, UI-05, 1101/12-01, 1101/12-02, 1101/12-04) |
scripts/check-design-system.ts, scripts/lib/design-system-rules.ts, src/presentation/design-system/tokens/token-contract.ts |
35b183b, bfa7dd9, 165ed19, 8576ce1, 49d8675, e714c0d, b4ccada |
| [계약] | design-system primitive가 src/presentation/design-system/primitives/<컴포넌트>.tsx로 나뉘었다. design-system/index.ts의 export 목록은 같다. 파일을 직접 import하던 코드는 경로를 바꾼다 (1101/08-08) |
src/presentation/design-system/primitives/, vite.config.ts |
6dd4bc1, 51941a5 |
| [계약] | MessageArguments<Key>가 catalog 문자열의 {이름}에서 파라미터를 만든다(값은 string 또는 number). check:i18n은 catalog parity와 raw backend 메시지만 보고, 화면 문구 literal은 ESLint screenTextSelectors가 잡는다(template literal·삼항식·객체 prop 문구는 못 본다) (0929/08-03, 0929/08-02) |
src/presentation/i18n/message-contract.ts, eslint.config.ts, scripts/check-i18n.ts |
ff33d58, 855d22a |
빌드·배포·CI
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 번들 예산 게이트 FE-GATE-012가 merge 단계에서 돈다. 예산은 gzip 204,800 B와 초기 파일 32개(initialJsFiles, 템플릿 26개 + 기능 여유)다. 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, 2fef27d, c9e7bab, f887817 |
| [계약] | 호스팅 계약: 파일이 없는 모든 경로에 그 release의 index.html을 HTML 헤더로 준다(SPA fallback, appRoute). 워커를 싣는 빌드의 service-worker.js는 no-cache다. live probe는 사전 캐시 확장자마다 Content-Type을 확인한다. nginx 예시는 docs/operations/release-cache-rollback.md (1101/13-04, 1103/06-03) |
config/hosting/cache-policy.json, scripts/lib/hosting-probe.ts, scripts/verify-hosting-headers.ts |
629c8f0, 0f58abb |
| [계약] | FE-GATE-019(production 단계)는 workflow의 deployment 슬롯이 배포한 승격 release를 본다. 슬롯이 비어 있으면 UNVERIFIED다. 배포된 release-manifest.json의 buildId·releaseId, config.json(비상 스위치 제외), index.html entry가 후보와 다르면 FAIL이다. TLS ALPN h2와 entry Content-Encoding(br·gzip·zstd)을 요구한다(config/hosting/cache-policy.json). HTTP/1.1이나 비압축 호스트는 FAIL이다. nginx 예시가 http2·gzip을 켠다 (1101/13-01, 1103/13-01, 1103/13-02) |
.gitea/workflows/quality-gates.yml, config/ci/gates.json, config/hosting/cache-policy.json, scripts/verify-hosting-headers.ts |
de379ea, 4bce8bf, 2e12d2f |
| [계약] | 제품 소유 config/ci/product-gates.json: 배포(deployment, package script와 vars.*·secrets.* 바인딩)와 제품 merge 검사(PRODUCT-GATE-NNN, job product_merge_gate). 템플릿은 승격 후보를 받아 CANDIDATE_ARCHIVE_SHA256으로 확인하고 푸는 단계를 만든다. 배포 슬롯은 gates.json이 아니라 여기서 채운다 (1103/12-07, 1103/13-01) |
config/ci/product-gates.json, scripts/contracts/product-ci-overlay.ts, scripts/generate-ci-workflow.ts |
4c4248a, 2e12d2f |
| [보안] | 배포 슬롯의 secrets.*는 deploy 단계 env에만 간다 (1103/13-05) |
scripts/generate-ci-workflow.ts, scripts/contracts/ci-gates.ts |
2e12d2f |
| [계약] | staging·production 승인(FE-GATE-027)이 example.com·example.net·example.org와 그 하위 도메인, .example·.invalid·.test endpoint와 자리표시자 계약 신원(digest PLACEHOLDER_CONTRACT_PACKAGE_DIGEST)을 거절한다. findAdmissionViolations가 세 번째 인자로 계약 패키지를 받는다. CI에서 endpoint는 config/runtime/<profile>.json에 커밋한다 (1101/13-02, 1101/16-01) |
src/contracts/deployment-admission.ts, scripts/check-release-admission.ts |
7b34756, 1269992 |
| [보안] | release 단계 FE-GATE-027이 scan:dependency-advisories로 의존성 advisory를 템플릿 정책에 따라 판정해 남긴다(막지 않음). renovate.json을 더했다. 개발 의존성의 high·critical advisory를 범위 안에서 고쳤다(storybook 10.6.5, vite 8.1.6, vitest 4.1.12) (1103/13-03) |
scripts/scan-dependency-advisories.ts, renovate.json, package.json, pnpm-lock.yaml |
eeb6f92, 26ca2fd |
| [보안] | provider 샌드박스가 .git 파일(worktree·서브모듈)을 /dev/null 읽기 전용 bind로 가린다. worktree에서도 test:system이 돈다 (1103/11-04) |
scripts/run-and-validate-provider.ts |
0edc3fc |
| [계약] | create:feature <id> [--context <ctx>] [--with-create [--keyed]] [--package <name@version> --digest <sha256> --revision <hex>]가 기능 뼈대를 만든다. 목록 경로는 짝 백엔드 new-feature.sh와 같은 /<plural>이고 결과 수는 meta.page.total이다. --with-create는 짝 백엔드 생성기와 같은 상세 GET·작성 POST(기본 NEVER, --keyed면 KEYED)·폼·결과 불명 화면·백엔드 본문 테스트를 더한다. FE-GATE-020의 test:feature-scaffold는 생성한 기능으로 gates.json의 merge 단계 명령을 돌고(브라우저 게이트·test:system·verify:lockfile·제거 드릴은 이유와 함께 뺀다) 그 기능의 제거 드릴도 돈다 (1101/16-01, 1103/03-07, 1103/09-06, 1103/12-02, 1103/16-02) |
scripts/create-feature.ts, scripts/create-feature-write-slice.ts, scripts/test-feature-scaffold.ts, config/ci/gates.json |
d166aa3, 2ec9d56, e1b4e28, 7411d4a |
| [계약] | verify:documentation(FE-GATE-017)이 입구 문서 4개의 src 최상위 폴더 설명과 layers.md의 아키텍처 규칙 이름을 검사한다(sourceStructure). docs/README.md 1절 현재 계약 문서의 repo 경로·명령 안 경로·링크·package script·FE-GATE ID와 짝 백엔드 참조를 검사한다(documentReferences, 짝 저장소가 옆에 없으면 unverifiedLinks). 수동 접근성 범위는 라우트별 기록 파일로 검사한다. 참조 기능 경로와 그 전용 script는 문서에 백틱 없이 적어, 참조 기능을 지워도 통과한다 (1101/14-03, 1101/14-05, 1103/12-05, 1103/14-04) |
scripts/verify-documentation-readiness.ts, docs/README.md, docs/manual/ |
61baf96, 16202fd, b4e4f98, c4d5870, fd11d08 |
| [계약] | 규모 설계서는 docs/architecture/scale-architecture.md(현재 계약, 절 번호 유지)다. 코드 주석 Spec §N은 scale-architecture.md §N이고, 문서 이름 없는 spec § 참조는 tests/unit/deletable-history-documents.test.ts가 막는다. docs/reviews/adapters/는 지울 수 있는 기록이 아니다 (1101/14-01) |
docs/architecture/scale-architecture.md, README.md, docs/README.md |
0a7fbed, b26517e |
| [계약] | 쓰지 않는 npm script 4개(scan:security:fixture, build:profile, generate:contract-set, build:app-only)를 지웠다. 게이트가 닿지 않는 scan:* script는 config/ci/ungated-scripts.json 항목이 있어야 한다 (1101/12-05) |
package.json, scripts/lib/ungated-scripts.ts |
98b9682 |
| [계약] | Vitest가 CI에서 skip·todo·only가 남은 실행을 실패시킨다(-t나 file:line으로 좁힌 실행은 제외). quarantine 주석이 붙은 skip도 실패한다 (1101/10-04) |
vitest.config.ts, tests/support/ |
95e7d11 |
| [계약] | 시각 테스트: tests/visual/fonts.conf로 글꼴을 고정하고 스크린샷 전에 실제 글꼴을 검사한다(Linux 전용). CI 브라우저 설치 단계가 글꼴 4종(fonts-noto-core fonts-noto-cjk fonts-noto-cjk-extra fonts-liberation)을 설치한다. 허용치는 절대 50 px다. 골든은 설치된 기능의 링크·목록·계약 다이제스트를 가리고 찍어, 기능을 더해도 다시 찍지 않는다 (1101/11-02, 1103/11-02, 1101/11-03, 1103/12-01) |
tests/visual/, playwright.visual.config.ts, .gitea/workflows/quality-gates.yml |
08b5ccc, b0195e3, 5ce3db9, 0a6ff6e |
| [계약] | 레시피 번들 예산: file-transfer 57,800, offline-indexeddb 38,500, realtime 42,200, service-worker-pwa 10,100 B. 측정값 + 3%를 100 B 단위로 올린 값이고, 3%를 넘는 증가는 커밋 본문에 이유를 적는다. 규칙은 docs/architecture/optional-adapter-recipes.md (0929/05-04) |
config/recipes/frontend-capability-recipes.json |
313f9ba |
그 밖의 수정
- 화면: 라이트 포커스 링 대비, oklab 색 혼합, 기본 버튼·현재 메뉴가 컴포넌트 토큰을 읽음,
--font-sans가 실제로 그려지는 시스템 글꼴, 테마·언어 선택 상자 폭, 예제 머리글의 반복 "예제" 라벨 삭제, 표 스크롤 영역 이름, 입력란 테두리가--field-border를 읽음 (UI-01, UI-02, UI-03, UI-04, UI-05, UI-06, UI-08, 1101/12-01) - 화면: 좁은 화면(48rem 미만)에서 머리글이 숨기던 테마 선택과 세션 상태를 메뉴 서랍에 둔다. 셸 문구가 DOM에 두 벌이라 페이지 전체에서
getByText로 찾는 테스트는 범위를 좁혀야 한다 (1101/08-01) - 화면: 검색값만 바뀌면 포커스·스크롤·
route.changed를 건드리지 않는다 (1101/08-02). h2·h3·h4 제목 크기·굵기 (1101/08-04), 한국어 단어 단위 줄바꿈 (1101/08-06), 상태 화면·오류 요약의 제목 수준 (1101/08-05), 예제 화면의lang="ko-KR"(1101/08-07), 폼 저장 실패와 결과 불명 화면의 지원 참조 (0929/08-04) - 폼: 짝 백엔드 필드 검증 code(
NOT_BLANK,SIZE등 20개)마다 문구가 있다. 모르는 code는 기본 문구다 (8a09c90, 1101 README 14.4).constructor같은 필드 code는 기본 문구다 (1103/08-03). 키보드 저장이 결과 불명·429 등 필드 오류가 아닌 실패로 끝나면 포커스가 실패 상태로 간다(FormPagefeedbackId, 저장 버튼 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). 짝 백엔드 FileserverPOST /v1/files한 번 업로드 clientcreateFileserverUploadClient(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의contractsprop은 Promise다 (1103/15-01). 성능 문서의 번들 기준선과 분류 규칙을 지금 빌드에 맞췄다 (1101/15-02, 1103/15-02) - 레지스트리 도구:
check:registries가 조립 실패의reason을 적고, 읽지 못한 레지스트리를 지운 것으로 세지 않는다 (1103/14-06). FE-REG-SCHEMA 행의direction·unknownFieldPolicy·boundary를 검증기·쓰임과 대조한다 (1103/07-03, 1103/16-04). 금지 조각이 든 런타임 설정 키를test:unit이 이름과 함께 막는다 (1103/07-04).check:feature-index예외 이유를 실제 사용처로 고쳤다 (1101/12-05) - 아키텍처 검사: zod 하위 경로(
zod/v4등) import도src/contracts/zod.ts를 거쳐야 한다 (64f19ac, 1103 07 영역 P-07-06). 금지 fixture를 그 계층의 운영 ESLint 설정으로 검사하고 fixture 전용 블록을 지웠다 (1103/12-04). adapter kernel 설명을 실제platform폴더 내용에 맞췄다 (3f72ae7). 두 오류 어휘(AppFailure·AppError)와commandRecovery를 누가 읽는지 타입 옆에 적었다 (1101/07-05, 1101/07-07) - 게이트·드릴: coverage 증거 검사(FE-GATE-005)가 istanbul summary의
branchesTrue를 받는다 (1103/12-09). compact smoke e2e가 빌드에 준VITE_BUILD_ID를 기대해 CI 값에서 FE-GATE-008이 항상 실패하지 않는다 (1103/11-06). vitest와 dev server를 띄우는 Playwright 설정(capabilities, dev)이 CI의VITE_BUILD_ID·VITE_COMMIT_SHA를 물려받지 않는다. 전에는 CI env에서 앱을 local-build fixture로 조립하는 테스트와 capability e2e가CONFIG_BUILD_MISMATCH로 떨어져 FE-GATE-005·006·007·008·020이 항상 실패했다 (1103/11-07). 테스트가 만드는 로컬 빌드(fixture 빌드, 시각 골든 build, 브라우저 테스트의 dev server)는CI=true에서도 release 빌드로 검사되지 않는다(localBuildEnvironment,LOCAL_BUILD_IDENTITY). 전에는 workflow env에서 FE-GATE-005·008·020이 실패했다 (1103/11-08). 브라우저 테스트의 strict fixture가 WebKit의 "preload했지만 몇 초 안에 쓰지 않았다" 경고 문구만 무시하고, 대신 preload된 build script가 실제로 실행됐는지를 세 엔진에서 검사한다(preloadunused:,tests/support/browser/preload-use.ts). WebKit은 load 3초 뒤 한 번 추정해서, 곧 쓰일 청크를 preload한 화면에서 FE-GATE-008이 가끔 떨어졌고 정말 안 쓴 preload는 놓쳤다. build script를 직접 fulfill하는 test는fulfillBuildScript를 쓴다 (1103/11-09). browser capability의 파일 선택·다운로드 test가 붙이는 버튼을 앱 위 고정 층에 둔다. 앱이 그리는 도중 내용이 자라 클릭 사이에 버튼이 움직였고, 클릭이 버튼에 닿지 않아 firefox에서 FE-GATE-008이 가끔 30초 시간 초과로 떨어졌다 (1103/11-10). 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:systemprovider 묶음 30초 예산 (1103/11-03), scope wrapper EOF 테스트 (1103/10-01)와 IndexedDB 차단 업그레이드 테스트 (1103/11-05)의 부하 원인을 없앴다.artifacts/**/*.log를 추적하지 않는다 (1103/12-08) - 기능 추가 뒤 검증(1103 README 14.6 X2): [계약]
create:feature와 기능 제거 드릴이 dev server의 manifest(public/release-manifest.json)의 contract set을 설치된 기능으로 다시 쓴다(node scripts/write-dev-release-manifest.ts). 기능과 함께 커밋한다. 낡으면tests/unit/dev-release-manifest.test.ts가 실패한다. 전에는create:feature직후 dev server와 dev server를 쓰는 capability e2e가CONTRACT_SET_PACKAGE_MISSING으로 부팅하지 못했다 (1103/16-09). dev server가artifacts/·dist/·.tmp/를 감시하지 않는다. 기능 제거 드릴(test:sample-removal -- --feature=<id>)이 지운 뒤 초기 JS 기록을 다시 쓴다 (1103/15-02). 초기 JS 파일 상한이 32다(템플릿 26 + 여유) (1103/15-05). Fileserver 업로드 client가 browser-file-storage 포트를 import하지 않아 그 런타임을 지워도 남는다(FileserverByteSource) (1103/01-01). 제품 확장 타입 검사 탐침이 예약 이름(typecheck-probe-*)을 쓰고 제품의 capability 선언을 덮어쓰지 않는다 (1103/09-02). 시각 골든 build와 storybook workshop spec이 CI 식별값·a11y 애드온 자동 검사와 겹치지 않는다 (1103/11-07) - 테스트: 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 repoconventions/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.md1절이 링크해 경로 검사를 받는다 (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)
알려진 제한
이 절의 범위 끝(브랜치 fix/maturity-review-2026-11-03의 8a44226)에서 사실인 것만 적었다. 위 절이 바꾼 것은 위 절에 적는다.
- 다운스트림 이행: 위 안내를 두 제품 코드에 적용해 게이트를 돌려 보지 않았다. memento-web의 숫자(descriptor 29개, schemaId 42개 +
MementoProblem)는 mementod3810a0을 정적으로 센 값이다. - 두 제품이 고친 템플릿 파일 중 제품 소유 자리가 없는 것("옮기기 전" 2단계의 셋째 항목: memento의
if-match·오프라인 shell·저장소 이름·브랜드 토큰, tech-log의AppFailure.detail·BoundMutation.identity·null빈 상태·디자인 시스템 등)은 이 묶음이 옮길 곳을 주지 않는다. 동기화 때 충돌하거나 제품이 고친 채로 남는다. 어느 것을 템플릿에 들일지는 정하지 않았다. - 직접 조립 제품(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를 붙이는 법)는 템플릿이 정하지 않았다. - 참조 기능은 DTO와 problem details만 읽는다(이 범위 끝에서는
responseEnvelope를 선언하지 않았고, 위 절에서 필수 칸이 되어"NONE"을 적는다). 짝 백엔드에 붙는 완성 예시는create:feature --with-create가 만드는 기능이다. - 짝 백엔드 생성기(
new-feature.sh)에 목록 GET이 없다.create:feature목록 화면은 백엔드가GET /<plural>을 더한 뒤에야 닿는다 (1103/03-07). - 짝 백엔드 계약 pin은
45d2a478(2026-11-05)이다. 그 뒤 백엔드가 바뀌면check:backend-contract-drift --backend <백엔드 checkout>가 알린다. 이 검사는 게이트 밖이라 CI는 알리지 않는다. - 업로드: 백엔드
POST /v1/files는Idempotency-Key를 읽지 않는다. 결과 불명 뒤 같은 키로 다시 보내도 파일이 둘 생길 수 있다. client의 code 목록은 백엔드 기준점에 묶여 있다.EXTERNAL_BEARER로 올리려면 제품 provider가 필요하다. 실제 백엔드 업로드와 firefox·webkit은 돌리지 않았다. - 세션 owner recipe는 실제 Keycloak·Redis와 붙여 보지 않았다. jwt 모드: 백엔드 realm에 브라우저용 public client가 없어 제품이 더한다(매뉴얼 04에 JSON). redis-session 모드: 백엔드 운영 코드에 로그인·로그아웃·세션 조회·CSRF 발급 엔드포인트가 없어 owner가 URL을 기본값 없이 받는다. OIDC owner는 토큰을 메모리에 두어 새로고침하면 로그아웃되고, ID token 서명을 검사하지 않는다.
- 플랫폼 구성 화면(
EXAMPLES_PLATFORM,/examples/platform)은 플랫폼 라우트라 끌 수 없고 FE-GATE-028 서명 대상이다. 예제 기능을 뺀 제품에서 예제 화면을 여는 e2e·visual spec은 실패한다 (1103/09-04). - 기능 라우트 첫 진입(실행부 청크, 약 430 ms)은 이 범위 끝에서 어느 게이트도 재지 않았다. 위 절에서 lab이
EXAMPLES_UI첫 진입을 500 ms 예산으로 잰다. 요청 두 묶음은 그대로다(1105/15-04). - 초기 JS 여유가 1,873 B다.
--with-create기능 하나(약 +964 B)를 넣으면 약 900 B가 남는다. - 운영 의존성 high advisory 2건이 남았다:
zod4.4.3 GHSA-mrhx-c7xc-m3w5(고치는 버전은 초기 JS 약 +7 KB로 예산을 넘는다),react-router7.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)은 이 범위 끝에서 없었다. 위 절에서ProductComposition.serviceWorker가 생겼다 (1103/09-05). SW e2e와 실제 live probe는 이 묶음에서 돌리지 않았다. - OPFS:
logicalKey까지 깨진 행은 staging에 남을 틈이 있고, 같은 lock 대기 상한이 partition 삭제에도 걸린다.dispose()는scopeParticipants를 부르지 않는다. 실제 로그아웃 E2E는 없다. - 라우트 계약의
title·navigationLabel은 화면이 읽지 않는다(catalog가 읽는다) (1103/16-06). 키보드 저장 실패 포커스는 스크린리더로 확인하지 않았다 (1103/08-02).
0.2.0 — 태그 v0.2.0 (2026-09-27)
2026-09-25 성숙도 리뷰(docs/reviews/2026-09-25-maturity-review/) 수정 묶음이다.
기준은 main 4626b73이다. package.json의 version은 0.2.0이다.
보안·계약 변경
먼저 볼 항목이다. 복사한 프로젝트가 이 경로를 고쳤다면 충돌을 직접 풀어야 한다.
| 표시 | 변경 | 영향 경로 | 커밋 |
|---|---|---|---|
| [계약] | 모든 V3 HTTP 요청이 논리 실행마다 x-correlation-id 헤더를 하나 보낸다. 다른 origin API는 preflight Access-Control-Allow-Headers에 이 헤더를 넣어야 요청이 나간다. 응답의 같은 헤더를 읽으려면 Access-Control-Expose-Headers에도 넣는다 (0925/03-03) |
src/adapters/http/http-execution-v3.ts, src/adapters/http/feature-http-binding.ts, src/bootstrap/runtime-adapters.ts, docs/operations/api-contract-and-server-state-recovery.md |
c5da3cf, f0a6495 |
| [계약] | 결과를 모르는 쓰기(응답 유실)를 다시 보낼 때 처음의 멱등 키를 그대로 쓴다. 백엔드는 같은 키의 재전송을 한 번만 적용해야 한다 (0925/03-01, 0925/08-03) | src/presentation/adapters/query/application-query.ts, src/presentation/forms/use-app-form.ts, src/presentation/components/async-surface.tsx |
dfb1b9e |
| [계약] | 명령의 401/403/429를 기능 패키지가 분류할 수 있다(classifyStatus, 선택 필드). 재로그인이 먼저다 (0925/03-02) |
src/adapters/http/http-effect-certainty.ts, src/adapters/http/http-execution-v3.ts, src/contracts/errors.ts, src/contracts/external-contract-runtime.ts |
2afee67 |
| [계약] | 422 problem body의 필드 오류(path, code)를 폼까지 전달한다 (0925/03-04) |
src/adapters/http/feature-http-binding.ts, src/features/reference-feature/contracts/reference-schemas.ts |
479acd5 |
| [계약] | 텔레메트리 수집기 이벤트마다 build_id, release_id가 붙는다. 한 번에 보내는 본문은 60KiB 아래로 나뉜다 (0925/13-11, 0925/03-05) |
src/adapters/telemetry/telemetry-collector.ts, src/bootstrap/runtime-adapters.ts |
43e47f4, e14c613 |
| [보안] | 번들이 읽지 않는 VITE_* 값까지 통째로 넣던 문제를 고쳤다. 값은 키로만 읽고, ENV_REGISTRY에 없는 VITE_* 이름은 빌드를 멈춘다 (0925/13-06) |
src/contracts/env.ts, vite.config.ts, eslint.config.ts |
2ec59ad |
| [보안] | 로그아웃·계정 삭제 purge가 손상된 IndexedDB 때문에 열리지 않으면 그 파티션의 DB를 지운다. OPFS purge는 남은 chunk를 바로 지운다 (0925/05-03, 0925/05-04) | src/adapters/platform/indexeddb-connection.ts, src/adapters/storage/indexeddb/indexeddb-runtime.ts, src/adapters/storage/opfs/opfs-byte-store-adapter.ts, src/application/ports/browser-file-storage/ |
3e37fbf, 6ab564f |
| [계약] | RELEASE_TARGET이 APP_PROFILE과 다르면 배포 승인이 거절된다 (0925/12-02, 0925/13-01) |
scripts/check-release-admission.ts, .gitea/workflows/quality-gates.yml |
239b22a |
| [계약] | 설정·매니페스트 URL이 VITE_ROUTER_BASE_PATH를 따른다. base 밖의 설정 URL은 빌드를 멈춘다 (0925/13-07) |
scripts/generate-runtime-config.ts, src/contracts/env.ts, vite.config.ts |
e215c84 |
| [계약] | VITE_PRODUCT_FEATURES는 생성기에서 적용되고, 모르는 기능 ID는 빌드를 멈춘다 (0925/09-02) |
scripts/generate-product-feature-index.ts, src/contracts/product-features.ts |
a8111f7 |
| [계약] | src/features/<id>/에 feature-module.ts도 NOT_INSTALLED 표식도 없으면 생성기가 실패한다. 기능 제거 검사는 --feature=<id>를 받는다 (0925/09-07, 0925/14-03) |
scripts/generate-product-feature-index.ts, scripts/test-sample-removal.ts, config/contracts/registry-governance.json, docs/architecture/starter-experience.md |
ad0e83c |
| [계약] | 기능 루트·context·app 파일은 src/adapters를 import할 수 없다. presentation은 app·context를 import할 수 없다(app-router.tsx 예외) (0925/12-03) |
scripts/check-architecture.ts, .dependency-cruiser.json, docs/architecture/layers.md |
f8b6a36 |
| [계약] | CI 계약의 게이트 수·해시가 config/ci/contract-baseline.json으로 옮겨졌다. 게이트를 바꾸면 update:ci-contract-baseline로 갱신한다 (0925/14-02) |
config/ci/contract-baseline.json, scripts/check-ci-contract.ts |
0114b1e |
| [계약] | 모든 테스트 파일은 어떤 게이트가 돌리거나 config/ci/ungated-tests.json에 이유가 있어야 한다 (0925/12-04, 0925/09-11, 0925/11-03) |
config/ci/gates.json, config/ci/ungated-tests.json, scripts/lib/ungated-tests.ts |
840de45, 45ee231 |
| [계약] | 게이트 판정 변경: 서명된 수동 접근성 검토는 release 게이트 FE-GATE-028로, runbook drill은 관측하지 못한 단계를 UNVERIFIED(exit 3)로, FE-GATE-016은 폐지, FE-GATE-019는 배포 뒤 production 단계에서 돈다 (0925/08-06, 0925/11-01, 0925/13-03, 0925/13-05) |
config/ci/gates.json, .gitea/workflows/quality-gates.yml, scripts/drill-runbook.ts, docs/operations/ci-quality-gates.md |
7298275, 7f889a6, a263d8c |
| [계약] | engineStrict, saveExact를 pnpm-workspace.yaml로 옮겼다. 지원하지 않는 Node에서 설치가 실패한다 (0925/13-09) |
pnpm-workspace.yaml, .npmrc |
a5dc851 |
| [계약] | 폼 저장 실패에 재로그인·권한 없음·나중에 재시도 상태가 따로 생겼다 (0925/08-01) | src/presentation/forms/form-contracts.ts, src/presentation/forms/use-app-form.ts, src/presentation/forms/form-components.tsx |
9894a70 |
| [계약] | browser-transfer 포트: upload() 실패의 recovery 값이 다섯 개로 정리됐고, 완료된 업로드는 resourceId를 잃지 않는다. 시간 제한이 바이트 수에 비례한다 (0925/01-01~01-11). file-transfer recipe를 쓰는 프로젝트만 해당 |
src/application/ports/browser-transfer/, src/adapters/browser-transfer/ |
648fe4e, 7b2cefb, 5a6665a, 426b6b8 외 |
| [계약] | IndexedDB·OPFS 포트: 미래 스키마는 INCOMPATIBLE, 빈 receipt는 없음으로 본다 (0925/05-01~05-14). offline-indexeddb recipe를 쓰는 프로젝트만 해당 |
src/application/ports/browser-file-storage/, src/adapters/storage/ |
7f45afa, 47cf040, 8fc816e 외 |
| [계약] | 외부 세션 owner의 readSubject()와 SessionGateway.getSubject()가 필수가 됐다. readSubject가 없는 owner는 integration-failed로 닫힌다. 토큰 갱신마다 서버 상태 캐시가 비워지던 문제를 막는다 |
src/adapters/auth/external-session-adapter.ts, src/application/ports/, docs/architecture/starter-experience.md |
c6300e9 |
| [보안] | 운영 CSP(unsafe-eval 없음) 아래에서 zod가 eval을 시험하지 않는다. src/의 코드는 zod를 src/contracts/zod.ts로만 가져온다(dependency-cruiser 규칙) (0925/13-08, 0925/F-7) |
src/contracts/zod.ts, .dependency-cruiser.json, tests/e2e/production-csp.spec.ts |
9dc95ca |
| [계약] | 설정 스키마 호환성 분류기(classifyObjectSchemaChange)가 모르는 스키마 변경을 breaking으로 본다. 런타임 설정 스키마도 기준선과 비교한다(FE-GATE-014, verify:compatibility). 레지스트리 분류기(scripts/lib/registry-compatibility.ts)와는 다른 것이다 (0925/07-02, 0925/13-10) |
src/contracts/compatibility.ts, scripts/check-compatibility.ts, config/compatibility/ |
17d617a |
| [계약] | 오류 레지스트리에서 읽지 않는 필드를 뺐다. 호환 별칭과 V1 reader에 @deprecated와 제거 조건을 붙였다 (0925/07-04, 0925/07-07) |
src/contracts/errors.ts, src/contracts/ |
aff5f43, 9e616d3 |
| [계약] | staging·production 빌드는 VITE_BUILD_ID가 없으면 실패한다 (0925/13-15, 0925/F-6) |
scripts/generate-runtime-config.ts, src/contracts/env.ts |
063375e |
| [계약] | Service Worker 빌드가 public/config.json 대신 프로필에서 만든 dist/config.json을 읽고, APP_ENV가 APP_PROFILE과 다르면 빌드를 멈춘다 (0925/06-10, 0925/F-8) |
vite.service-worker.config.ts, scripts/lib/service-worker-build-input.ts |
cefb0b2 |
| [계약] | Web Push: 탭 사이 구독 제어를 Web Lock으로 직렬화하고, 새 세션이 다른 계정의 push fence를 넘겨받는다. REMOVE_REGISTRATION은 스스로 등록을 해지하는 worker를 배포한다 (0925/06-02, 0925/06-06, 0925/06-03) |
src/adapters/web-push/, scripts/lib/self-unregistering-service-worker.ts, docs/runbooks/ |
e6c683e, 996a959, 9f2305a |
| [계약] | realtime: 세션이 끝날 때마다 재시도 예산을 초기화하고 offline 동안 멈춘다. SSE Retry-After를 따른다. 등록되지 않은 이벤트 종류는 registry mismatch로 끝난다 (0925/04-01~04-08). realtime recipe를 쓰는 프로젝트만 해당. 레시피 번들 예산은 40,900 bytes로 올렸다 |
src/adapters/realtime/, config/recipes/frontend-capability-recipes.json |
bcad7b0, 02d3fdf, 7e37660, 2c5e268 외 |
| [계약] | browser-files 포트: 같은 턴의 abort는 ABORTED, 닫은 선택 창은 DISMISSED, 소진된 object URL lease는 재시도 가능으로 보고한다. Cache Storage는 후보 항목을 검증한 뒤에만 verified로 보고한다 (0925/02-01~02-09). browser-files recipe를 쓰는 프로젝트만 해당 |
src/adapters/browser-file-storage/, src/adapters/cache-storage/ |
c9be8d6, d76653b, 0b41cb3, 55c0bf5 외 |
| [계약] | 샘플 상세 경로가 /examples/reference-resources/items/:resourceId로 옮겨졌다. ID가 new·status인 항목도 상세가 열린다 (0925/08-13) |
src/features/reference-feature/contracts/reference-feature-contract.ts, config/contracts/registry-change-evidence.json |
d7b81c6 |
| [계약] | tsconfig.base.json에 noUnusedLocals를 켰다. 복사한 프로젝트의 쓰지 않는 import·변수가 check:types에서 실패한다 (0925/12-12) |
tsconfig.base.json |
49413af |
그 밖의 수정
-
부트: 앱 모듈 평가 실패, 분류되지 않은 오류, 재시도 가능한 실패에 오류 화면을 보여 준다 (0925/09-03, 0925/09-04, 0925/09-10).
src/bootstrap/,src/presentation/boundaries/boot-error-shell.tsx -
부트:
FEATURE_OVERRIDES의 모르는 키를 진단으로 남긴다 (0925/09-09).src/bootstrap/runtime-adapters.ts,scripts/check-release-admission.ts -
빌드:
dist파일을 다른 사용자도 읽을 수 있게 한다 (0925/13-02).scripts/lib/dist-permissions.ts -
공급망: 번들에 들어간 패키지 목록과 각 증거의 범위를 남긴다. 승격된 릴리스를 나중에 다시 검증한다 (0925/13-12, 0925/13-04).
scripts/lib/vite-module-inventory.ts,scripts/verify-exact-promotion-bundle.ts -
아키텍처 검사: dependency-cruiser 실행을 멈추고 import graph 하나로 검사한다. 경계 예외를 좁히고, 위반 메시지에 이유와 갈 곳을 적는다 (0925/12-05~12-11).
scripts/check-architecture.ts -
기능 조립:
needs검사, 기능 두 개 설치 시 타입 유지, local-draft 샘플 정리 (0925/09-01, 0925/09-05, 0925/09-06, 0925/09-08, 0925/09-12, 0925/00-02).src/features/,src/bootstrap/runtime-adapters.ts -
테스트 보강: production CSP 아래 빌드 smoke, 멱등 키 재사용, IndexedDB fake, KEYED 재시도 (0925/13-08, 0925/01-04, 0925/05-08, 0925/10-03)
-
샘플 제거:
test:sample-removal이 다시 통과한다. 플랫폼 테스트가 샘플 대신 테스트 전용 기능을 쓴다 (0925/14-01, 0925/14-08, 0925/00-01, 0925/10-01).scripts/test-sample-removal.ts,scripts/lib/removal-fixture.ts -
문서: README에 런타임 프로필·배포 변수·우선순위를 적고
verify:documentation이 변수 목록을 검사한다 (0925/13-15). 성능 예산, 공급망, 운영 runbook 문서를 코드에 맞췄다 (0925/13-13, 0925/13-14, 0925/03-06, 0925/03-08). -
화면: 오류 종류마다 문구가 있고, 실패 화면에 지원 참조와 다음 행동이 나온다. 언어를 바꾸면 폼 오류도 다시 번역된다. 조회 실패의 인증·권한·없음 화면이 갤러리와 같은 컴포넌트다. 수정키 클릭은 브라우저에 맡긴다. 스크롤·해시 이동을 복원한다 (0925/07-01, 0925/08-02, 0925/08-04, 0925/08-07~08-12, 0925/F-10).
src/presentation/,src/presentation/i18n/ -
접근성·visual 검사가 로그인 뒤 실제 화면을 상태별로 검사한다 (0925/08-05, 0925/11-02).
tests/e2e/accessibility.spec.ts -
계약 테스트: V2/V3 일치, 두 번째 기능의 레지스트리 통과, validator 결과 검사 (0925/07-03, 0925/07-05, 0925/07-06, 0925/09-07, 0925/F-3).
tests/unit/,src/contracts/ -
Service Worker: 알림 클릭, kill switch, drain 시간 초과, 이전 릴리스 fallback, 거절 클릭 경로, 시작 실패 텔레메트리 (0925/06-01, 0925/06-04, 0925/06-05, 0925/06-07~06-09).
src/adapters/web-push/,src/adapters/service-worker/,src/bootstrap/ -
테스트 체계: 부하에 강한 대기, 커버리지 정책, 파일 하나 실행, 실제 타이머 복원, 포커스 테스트 금지, reference 데이터 E2E, 실제 모양 기능 규모 측정, SW 없는 구 탭 청크 복구, 성능 측정 중앙값, 모듈 평가 실패 부트 화면 (0925/10-02, 0925/10-04
10-07, 0925/11-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 |