문제
1103 수정이 더한 플랫폼 규칙 테스트 둘이 참조 샘플에 기댄다. 샘플을
지우면 두 테스트가 사라지거나 비어도 test:all과 제거 드릴이 통과한다.
- MAX_RETRY_ATTEMPTS가 실행기에 닿는다: 유일한 테스트가
tests/features/reference-feature/reference-runtime-composition.test.ts
에 있다. createRuntimeAdapters는 설치된 기능의 HTTP로만 실행기에 닿아,
기능이 없으면 시험할 길이 없다. REQUEST_TIMEOUT_MS도 같은 모양이다.
- 복구 중인 세션은 보호 라우트에서 기다린다:
tests/unit/navigation-policy.test.ts는 설치된 보호 라우트를 돌며
단언하는데, 보호 라우트는 모두 샘플 것이라 샘플을 지우면 반복이 0번이다.
고른 방법과 버린 대안
- src/bootstrap/runtime-adapters.ts: 설정 두 값과 auth profile 표로
실행기를 만드는 부분을 createRuntimeContractHttpExecutor로 뺀다.
조립 루트는 이 함수로만 실행기를 만든다. tests/unit/runtime-adapters
.test.ts가 테스트 계약(TEST_LIST, 재시도 예산 2)으로 MAX_RETRY_ATTEMPTS
0·1·2에 1·2·3번 나가는지, REQUEST_TIMEOUT_MS 5가 10초 계약을 5ms에
끊는지 본다. 이 파일은 이미 제거 드릴의 공통 테스트 목록에 있다.
- tests/unit/session-route-access.test.ts(새 파일): component 테스트와
같은 방법으로 생성 index를 mock해 tests/helpers/fixture-feature.tsx를
설치하고, 보호 라우트 FIXTURE_ITEMS에서 네 세션 상태의 결정을 본다.
decideRouteAccess에 라우트 정의를 받는 순수 함수를 따로 두는 안(리뷰
ⓐ)은 버렸다. fixture 기능을 설치하는 방법이 이미 있어서 운영 코드를
바꾸지 않고 실제 getRoute 경로까지 시험할 수 있다.
- scripts/test-sample-removal.ts: 새 파일을 공통 테스트 목록에 넣어,
제거 드릴이 그 파일이 남았는지 본다.
- 매뉴얼에 "샘플을 지우면 다시 고정한다"고만 적는 안(ⓒ)은 사람이
기억해야 해서 버렸다.
위험·한계
- 조립 루트가 이 함수 대신 실행기를 직접 만들도록 바뀌면 새 unit
테스트는 그걸 모른다. 템플릿 상태에서는 참조 기능 테스트가 계속
조립 루트 전체를 지킨다.
- 샘플을 지운 복사본에 변이를 넣어 돌리지는 않았다.
검증
- desktop batch에서 확인:
node scripts/run-vitest.ts run tests/unit/runtime-adapters.test.ts tests/unit/session-route-access.test.ts tests/unit/navigation-policy.test.ts tests/features/reference-feature/reference-runtime-composition.test.ts
- RED: 부모 커밋의 운영 코드에는 createRuntimeContractHttpExecutor가
없어 runtime-adapters.test.ts의 새 4건이 실패한다.
- 변이: 새 함수의 maxRetryAttempts를 상수 2로 바꾸면 "honours
MAX_RETRY_ATTEMPTS 0/1"이, navigation-policy.ts의 recovery-pending
분기를 show-sign-in으로 바꾸면 session-route-access.test.ts의
"answers a recovery-pending session …"이 실패해야 한다.
Refs: 1105/10-01
문제
V2를 지울 때(048f490) 같이 지운 테스트 둘이 V3 동작도 지키고 있었다.
- 운영 설정 MAX_RETRY_ATTEMPTS가 실행기에 닿는지. V3는
runtime-adapters.ts에서 넘긴다. 값을 상수 2로 바꾼 변이 H53이 15파일
143건을 통과했다. 장애 때 재시도를 끄는 손잡이가 조용히 사라질 수 있다
(REQUEST_TIMEOUT_MS는 실제로 한 번 그렇게 버려졌다).
- 호출자·scope signal에 단 abort listener를 지우는지. 호출자 쪽 제거를 지운
H56은 머지 게이트 테스트를 모두 통과했고, scope 쪽(H57)은 nightly
tier의 long-session 테스트 하나만 잡았다.
고른 방법
- tests/features/reference-feature/reference-runtime-composition.test.ts:
실제 createRuntimeAdapters에 MAX_RETRY_ATTEMPTS 0·1을 주고, 재시도
예산 2인 참조 목록 조회가 503에 1회·2회 나가는지 센다(Math.random 0으로
backoff 대기 없음). 설치된 기능의 HTTP가 있어야 조립 루트 경로를 탈 수
있어 참조 기능 테스트에 두었다. test:reference-feature는 머지 게이트다.
- tests/unit/http-execution-v3.test.ts: 응답으로 끝날 때와 호출자 abort로
끝날 때, 호출자·scope signal에 더한 abort listener가 같은 함수로 모두
지워지는지 센다.
위험·한계
- ①은 참조 기능에 기댄다. 샘플을 지운 제품에서는 이 테스트도 같이
빠진다. 조립 루트를 기능 없이 부를 수단이 없어서다.
- 10-04 ③(realtime snapshot의 GET 조건)은 다른 작업 몫이다.
검증
- 변이 H53·H56·H57을 하나씩 넣으면 새 테스트가 실패하고, 되돌리면 통과한다.
- 두 파일 76건 통과. check:types:test, eslint 통과.
Refs: docs/reviews/2026-11-03-maturity-review/10-tests-fast-layers.md 10-04
문제
제품 확장 지점이 실행 경로에서는 동작했지만 타입 검사 경로에서 막혔다.
(a) 문서대로 product-composition.ts에서 FeaturePlatformCapabilities를
보강하면 check:types:node가 실패했다. scripts 프로그램은 기능 코드를 끌어오지만
product-composition.ts는 끌어오지 않아 보강이 보이지 않았고, 오류는 기능
파일을 가리켰다. (b) 기본값 있는 제품 설정 키(.default()) 하나가 RuntimeConfig를
리터럴로 쓰는 템플릿 테스트 7개 파일의 타입을 깼다. 픽스처는 vi.mock이라 이
경로를 지나지 않았다.
고른 방법
- 제품 소유 빈 파일 src/features/product-capabilities.ts를 두고
FeaturePlatformCapabilities가 그 ProductFeaturePlatformCapabilities를
extends한다. feature-adapter-contribution.ts가 import하므로 기능을 보는 모든
프로그램에 들어간다. 문서만 "기능 파일 안에서 보강"으로 고치는 최소안은
capability 하나를 여러 기능이 쓸 때 보강 위치가 갈려 버렸다. 기존 제품 소유
파일에 칸을 더하지 않고 새 파일로 둔 이유: 템플릿은 복사 뒤 제품 소유 파일을
고치지 않으므로, 새 파일이어야 동기화 때 충돌 없이 들어간다.
- tests/helpers/runtime-config.ts의 testRuntimeConfig: 템플릿 키는 테스트가
쓰고, 제품 키는 실제 스키마(validateRuntimeConfig)로 기본값을 채운다. 템플릿
테스트 6개 파일이 이것을 쓰고, release-coherence는 문서 타입을 z.input으로
바꿨다. 제품 키를 모두 Partial로 하는 대안은 기본값 키에도 undefined 처리를
강요해 버렸다.
- tests/unit/product-extension-typecheck.test.ts: 복사본에 제품 소유 파일 세 개와
기능 하나를 실제 파일로 채우고 tsc app·node·test를 돈다.
- 문서: starter-experience 표, 매뉴얼 01·03·patterns·create-feature,
frontend-application-foundation, 계약 주석.
위험·한계
- 기본값 없는 필수 제품 키는 여전히 템플릿 테스트에서 실패한다(이제 타입이
아니라 helper가 이유를 적고 throw). 문서에 ".default() 또는 .optional()"을
적었다.
- product-composition.ts 안에서 이미 보강한 다운스트림은 보강을 새 파일로
옮겨야 node 검사가 통과한다.
검증
- RED: 새 typecheck 테스트가 수정 전 app·node(보강 미연결)와 test(템플릿
테스트 8건, E-PROD와 같은 위치)에서 실패.
- 수정 후 그 테스트와 영향받는 9개 테스트 파일 → 10 files / 83 tests 통과.
- check:types(tsc app·node·test), check:architecture, eslint,
verify:documentation PASS_SCOPED.
Refs: docs/reviews/2026-11-03-maturity-review/09-app-core.md 09-02
문제
초기 JS는 203,572 / 204,800 B(gzip)였다. 생성 인덱스가 각 기능의
feature-module.ts를 정적으로 import하고, 그 파일이 계약(zod 스키마·mapper
포함), HTTP 계약 contribution, application input 팩토리, route codec까지
모두 끌고 왔다. 참조 모양 기능 1개를 더하면 +3,922 B가 늘어 첫 기능에서
예산을 넘었다.
고른 방법
- 기능을 두 부분으로 나눈다. 선언(FeatureModule: route 표, route runtime
계약, invalidation, 문구, 부팅 때 release manifest와 맞춰 볼
contractPackages)은 초기 청크에 남는다. 실행부(FeatureRuntime: V2 API
계약, adapter contribution, contract contribution)는 feature-runtime.ts로
옮기고 loadRuntime이 동적 import한다. route codec은 context-routes.ts의
route handle에 실어 route와 함께 적재한다.
- 적재 시점은 그 기능의 route에 들어갈 때다. ContextRouteGateway가 route
모듈과 함께 application.features.load(featureId)를 부르고, 끝난 뒤에
화면을 그린다(공개 포트에는 load만 추가). 들어온 URL의 기능은 route
모듈과 병렬로 적재해 왕복을 늘리지 않는다. 런타임 설정으로 꺼진 기능은
적재하지 않는다.
- 조립부는 기능별 로더를 만든다(installed-feature-adapters.ts). contract
registry는 기능이 적재될 때마다 전체를 다시 합쳐 검증한다
(installed-contract-contributions.ts). 선언하지 않은 contract package를
적재하면 거절한다.
- 모든 실행부를 한꺼번에 읽는 registry(V2 API, contract contribution)는
installed-feature-runtime-registries.ts의 async 함수로, Node·테스트·
registry 거버넌스용 상수는 top-level await 모듈 loaded-feature-runtimes.ts로
둔다. src에서 후자를 import하면 새 아키텍처 규칙
boot-does-not-load-every-feature-runtime이 막는다. 플랫폼 구성 화면은
route 로더에서 async 함수를 불러 결과를 prop으로 받는다.
- vite.config.ts에 청크 그룹 2개를 둔다. rolldown은 부팅 그래프와 lazy
청크가 같이 쓰는 모듈을 importer 집합마다 따로 청크로 뗀다. 그대로 두면
기능마다 선언 청크가 하나씩 늘고(기능당 +1,471 B), 실행부와 공유하는
플랫폼 모듈(HTTP executor, contract runtime, zod)이 6개 청크로 쪼개져
템플릿 자체가 +438 B 커졌다. feature-declarations는 모든 기능의 선언을,
feature-platform은 실행부가 같이 쓰는 부팅 모듈을 한 청크로 묶는다.
render-boot-failure.tsx가 쓰는 모듈은 feature-platform에서 뺀다(09-03:
애플리케이션 그래프가 평가 중 던져도 실패 화면은 떠야 한다).
버린 대안
- 부팅 때 feature 청크를 미리 동적 import하고 기다린 뒤 렌더: 분류기는
lazy로 세지만 첫 렌더 경로의 바이트는 그대로다. 예산을 속이는 것이라
버렸다.
- 실행부 일부만 지연(adapter와 contribution만): 모두 같은 zod 스키마를
공유해 줄지 않았다. 실측 +4,031 B로 오히려 늘었다.
- 선언과 실행부를 같은 lazy 청크(context-routes)에 두기: 기능당
-60 B 수준이라 그룹 없이 목표에 못 미쳤다.
- 페이지 문구까지 실행부로 옮기기: 기능당 약 300~450 B를 더 줄이지만
i18n catalog를 런타임 등록 구조로 바꿔야 해 이번 범위에서 뺐다.
- boot.tsx를 별도 진입점으로 추가: 분류기가 boot의 동적 import를 모두
초기로 세어 218,303 B가 됐다.
위험·한계
- FeatureModule 모양이 바뀐다. 다운스트림 기능은 feature-runtime.ts로
실행부를 옮겨야 한다(BREAKING CHANGE).
- 기능 계약 간 중복(operation, schema, contribution) 검사가 부팅이 아니라
그 기능의 적재 시점과 Node 검사(loaded-feature-runtimes를 읽는 스크립트·
테스트)로 옮겨 간다.
- 기능 route에 처음 들어갈 때 실행부 청크(약 5 KB gzip)를 받는다. 플랫폼
구성 화면은 모든 기능의 실행부를 받은 뒤 그린다. lab 게이트(FE-GATE-026)가
재는 화면이라 LCP가 조금 늘 수 있다. 측정하지 않았다.
- 청크 그룹은 rolldown 자동 분할을 일부 대신한다. feature-declarations가
비면 기능당 증가 상한 테스트가 실패한다. feature-platform이 비면 템플릿
총량(약 2 KB)만 늘고 번들 예산 검사가 잡는다.
- config/contracts/registry-baseline.json의 FE-REG-API/SCHEMA source는 아직
installed-feature-contracts.ts다. 승인 digest가 걸려 있어 소유자 재승인
때 고친다. check-registries는 통과한다.
- 예산 안에 들어가는 참조 모양 기능은 약 3개다. 플랫폼 자체가 예산의
98.8%다.
수치 (vite build, classifyViteJavascript + gzipSync 기본 수준)
- 템플릿: 203,572 B(13파일) -> 202,361 B(16파일), -1,211 B
- 참조 복사본 +1: 207,494 B(+3,922) -> 203,102 B(+741)
- 참조 복사본 +2: 210,818 B(+3,324) -> 203,750 B(+648)
- 참조 복사본 +5: 205,629 B
- lazy JS: 23,516 B -> 28,204 B
검증
- RED: node scripts/run-vitest.ts run tests/unit/feature-shape-growth.test.ts
"adds at most 1 KiB ... (15-01)" 실패: expected 3934 to be less than or
equal to 1024
- GREEN: 같은 테스트 통과(+741 B)
- node scripts/run-vitest.ts run tests/unit: 168파일 2,383 통과
- node scripts/run-vitest.ts run tests/component tests/features
tests/integration tests/contract tests/runtime-schema tests/architecture
tests/platform tests/recipes (security-followup-archive 제외, pnpm 호출):
109파일 787 통과
- npx tsc --noEmit: app, node, test, recipes, web-worker, service-worker 통과
- npx eslint 바뀐 파일 통과
- check-architecture.ts(pnpm exec 대신 eslint를 부르는 shim): PASS, 새 규칙이
boot.tsx의 import를 거절하는 것 확인
- check-adapter-inventory, check-registries, verify-documentation-readiness,
check-ci-contract: PASS
- e2e Chromium 전체(pnpm 없는 build-frontend + vite preview, 별도 포트):
55 통과
- storybook build 성공
- 미실행: Firefox·WebKit e2e, 시각 회귀, lab 성능(FE-GATE-026),
pnpm 경로의 check:bundle, test:system
BREAKING CHANGE: FeatureModule은 id, contracts(선언), routes, messages,
loadRuntime만 가진다. adapters, contractContributions와 V2 API 계약
(apiOperations, schemas, runtimeSchemas, mappers)은 defineFeatureRuntime으로
만든 feature-runtime.ts로, route codec은 context-routes.ts의 route handle
codecs로 옮긴다. contracts에는 contractPackages를 추가한다.
Refs: docs/reviews/2026-11-01-maturity-review/15-performance.md 15-01,
16-structure-patterns.md 9절
package.json and public/release-manifest.json carry the version the
release manifest reports; the three tests that build a manifest for the
installed app use the same value. Test fixtures that pin 0.1.0 as an
arbitrary release stay as they are.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
V3 returned the same UNAUTHENTICATED outcome for "no credential, nothing
sent" and for a server 401, and the composition root called
onUnauthenticated() for both. With the demo owner that overwrote a
recovery-pending session with "unauthenticated", and the demo setState
notified even when the value did not change, which fed the scope-fence loop.
- V3: the server-401 UNAUTHENTICATED outcome now carries its response
`metadata` (additive optional field). The pre-dispatch one does not.
- runtime-adapters: onUnauthenticated() only when metadata is present.
- demo session: setState is a no-op for the current value.
RED before fix: reference-runtime-composition.test.ts "does not report a
request refused before dispatch as a sign-out" (state became
"unauthenticated"), auth-session-adapter.test.ts "does not notify when the
demo state is set to its current value" (1 notification),
http-execution-v3.test.ts "tells a missing credential apart from a server
401" (no metadata). Pinned: "still signs out when the server answers 401".
Gates: check:architecture, check:types:app, check:types:test, lint,
test:component, test:integration, test:reference-feature, test:contract
pass. test:unit passes except removal-fixture.test.ts (needs generated
artifacts/ release evidence absent in a fresh worktree; unrelated).
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Which features a build contains was not a decision anybody could express. The
reference feature was spread directly into the route, API, schema, codec and
adapter registries, so shipping without it meant editing five files by hand and
hoping nothing still referred to it — and there was no way at all to take it out
of service on a running deployment. The removability gate proved the editing
worked; nothing made it a choice.
There is now one manifest. `VITE_PRODUCT_FEATURES` narrows it at build time and
`FEATURE_OVERRIDES` in the runtime document takes an installed feature out of
service without a rebuild. Every registry composes from the manifest, and a test
fails if a new one forgets to.
Both inputs are subtractive, and the vocabulary is what enforces it rather than
a check somewhere downstream: the override enum has no `ENABLED`, and a
build-time selection naming something the source tree does not declare is
refused instead of ignored. A configuration document that could name a feature
into existence would be a configuration document choosing which code runs.
Disabling is not just hiding. Withdrawing a route from navigation would leave a
typed deep link that still mounts the feature, so the router refuses it too and
answers with a surface that says the deployment switched it off. The platform
overview now distinguishes the three states an operator actually needs: serving,
switched off, and not in this build.
What this is not: an env var does not shrink the bundle. A static import cannot
be undone by a value, and making the import graph itself depend on a
configuration string is the thing §3.5 exists to prevent — measured, `none`
changes the output by 58 bytes. Physical removal remains FE-GATE-020's job, and
the code comments say so rather than implying otherwise.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>