문제
HTTP API 하나를 V2 행(check:registries가 보는 선언)과 V3 descriptor(실제로
실행되는 사본)에 두 번 쓴다. 15-01 뒤에도 둘은 feature-runtime.ts의
apiContract와 contractContributions로 나뉘어 그대로 두 벌이다. 둘을 잇는
parity 테스트는 V2 행에서 V3를 찾는 한 방향이고 6필드만 비교한다. 그래서
V3 검증기의 schemaId를 바꾸거나(L1) V3에만 API를 추가해도(L6) 테스트가
통과한다. V3에만 있는 API는 공개 경로·메서드가 FE-REG-API 게이트 밖에서
실행된다. "V2는 게이트용, V3는 실행용"이라는 사실은 테스트 주석에만 있다.
고른 방법 (리뷰 5.1절의 B, 1단계)
- 두 사본의 operation id 집합이 같아야 한다(양방향). V3만 있는 API와
V2만 있는 API가 각각 실패한다.
- 비교 필드에 같은 사실의 사본 넷을 더했다: 쓰기 여부(V2 semantics ↔ V3
commandEffect 유무, 실행기가 쓰기를 메서드가 아니라 effect로 정하므로),
요청 본문(V2 requestSource body ↔ V3 requestBody JSON), 입력 스키마 id
(V2 pathSchema/requestSchema 중 NoRequest가 아닌 것 ↔ V3 inputValidator),
응답 스키마 id(V2 responseSchema ↔ V3 outputValidator).
- V2가 path와 request 스키마를 둘 다 가진 operation은 V3 입력 스키마 하나와
대응 규칙이 아직 없다. 조용히 넘기지 않고 테스트가 실패하며 규칙을
정하라고 알린다. 지금 설치된 operation에는 없다.
- RestOperationV2 위와 starter-experience.md "Adding a feature"에 V2는
게이트용 선언, V3는 실행 사본이고 둘 다 쓴다는 것을 적었다.
버린 대안
- V2 행을 V3에서 생성(5.1절 C)하거나 FE-REG-API 스냅샷을 V3에서 투영하고
V2 행을 없애기(D): 생성기·투영 함수와 기준선 재승인이 필요한 구조
변경이라 이번 범위를 넘는다. 15-01로 V2와 V3가 같은
defineFeatureRuntime 객체에 모였으므로 D로 갈 때 기능 단위 투영 지점은
생겼다.
- "V2 행이 1개 이상" 단언: test:sample-removal이 참조 기능을 지운 사본에서
이 파일을 돌리면 두 집합이 모두 비어 정상인데 실패한다. 양방향 집합
비교가 한쪽만 빈 경우를 잡는다.
- 두 번째 기능 테스트(second-api-feature-registries)에 V3 기여 넣기:
fixture 복사본에서 check:registries를 도는 테스트라 V3 기여를 넣어도 이
parity 검사가 그 사본에서 돌지 않는다. 비용 대비 효과가 작아 뺐다.
위험·한계
- 시간 제한(V2 timeoutMs null ↔ V3 totalDeadlineMs 10000, L3)은 비교하지
않는다. 맞추려면 V2 행 값을 바꿔야 하고 FE-REG-API 기준선이 바뀐다.
주석에 비교하지 않는다고 적었다.
- 응답 스키마 본문, unknownFieldPolicy ↔ zod strip/strict(L7), 손 guard ↔
zod DTO 차이는 여전히 대조하지 않는다.
- 설치된 기능에 대한 테스트다. CI 밖에서 V3만 추가한 다운스트림은 이
파일을 돌려야 걸린다.
검증
- RED: 기존 테스트와 새 테스트를 같은 변이에 돌렸다.
L1(V3 GET_REFERENCE_RESOURCE outputValidator schemaId를
ReferenceResourcePayloadV2로): 기존 통과, 새 테스트 실패
("responseSchema": "ReferenceResourcePayload" vs "...V2").
L6(V3에만 GET_REFERENCE_RESOURCE_V3_ONLY 추가): 기존 통과, 새 테스트
"cover the same operations" 실패(+ "GET_REFERENCE_RESOURCE_V3_ONLY").
- GREEN: 변이 없이 2/2 통과.
- 회귀: tsc test rc=0, 바꾼 파일 eslint rc=0. 전체 회귀는 다음 커밋들과
함께 마지막에 돌렸다(이 커밋의 src 변경은 주석뿐).
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
조립기(composeContractContributions)의 TEMPLATE_FIXTURE 분기는
fixtureId·revision·이벤트 0개만 보고 featureId를 보지 않는다. 참조 기여
파일을 복사한 제품 기능(order)이 fixture 출처 그대로 조립을 통과한다.
fixture 기여는 계약 집합(externalPackages)에 들어가지 않으므로 그 API는
실행되지만 부팅 때 릴리스 계약 정합 검사에서 경고 없이 빠진다. 설계서
§4.8은 "product feature는 반드시 EXTERNAL_PACKAGE", §24.5는 정적 검사가
product TEMPLATE_FIXTURE를 거부한다고 적지만 구현이 없다.
고른 방법
- 조립기 fixture 분기에서 featureId가 fixture의 주인과 다르면
ContractContributionError로 실패한다. 메시지가 EXTERNAL_PACKAGE를
쓰라고 안내한다.
- fixture 기여가 둘 이상이면 실패한다(설계서의 "유일한 예외").
- 15-01 뒤 조립은 기능 적재 때마다 전체를 다시 조립하므로 두 검사 모두
기능이 따로 적재돼도 걸린다. registry.install의 featureId 일치 검사가
있어 다른 기능이 참조 기능 id를 빌려 쓰는 길도 막혀 있다.
- 주인 featureId는 리터럴로 쓰지 않고 fixtureId에서 만든다
(REFERENCE_FEATURE_V1 -> 대문자 스네이크를 소문자 kebab으로, _V1 제거).
이유를 주석에 적었다.
- starter-experience.md "Adding a feature"에 제품 기여는
EXTERNAL_PACKAGE라는 문장을 넣었다.
- contract-snapshot-bypass의 "iterator에 숨긴 이벤트" 테스트는
featureId test-feature의 fixture를 썼다. 새 검사가 그 행을 먼저 막아
테스트가 아무것도 확인하지 못하게 되므로 EXTERNAL_PACKAGE 출처로
바꿨다. 패키지 출처는 이벤트를 받으므로 숨긴 이벤트를 읽으면 설치되어
단언이 실패한다. 예전 fixture 출처는 이벤트가 하나라도 있으면 던져서
읽었는지 아닌지를 구분하지 못했다.
버린 대안
- 리뷰 문서 그대로 featureId !== "reference-feature" 리터럴 비교:
test:sample-removal이 샘플 제거 뒤 src/·tests/ 전체에서
/REFERENCE_RESOURCE|reference-feature|reference-resource/i를 찾아
잔여물로 실패시킨다(scripts/test-sample-removal.ts:95). 플랫폼 코드와
남는 단위 테스트에 그 id를 쓰면 이 게이트가 깨진다.
- 조립기에 허용 featureId 인자를 추가하거나 feature module에 fixture 표시
필드를 추가: 공개 함수·타입 변경이라 이번 범위를 넘는다.
- 정적 검사(dependency-cruiser) 규칙: 출처 종류는 import가 아니라 값이라
depcruise로 볼 수 없다.
위험·한계
- 실패 시점은 15-01 구조에 따라 부팅이 아니라 그 기능의 런타임 적재
(라우트 진입) 때다. Node 쪽 loaded-feature-runtimes와 레지스트리
스크립트는 import 때 전부 조립하므로 CI에서는 바로 드러난다.
- scripts/scale/measure-feature-shape-growth.ts는 참조 기능을 이름만 바꿔
복사하고 REFERENCE_FEATURE_V1을 그대로 둔다. 그 복사본은 이제 조립에서
거부된다. 이 스크립트는 tsc와 vite build만 하고 기여를 조립하지 않아
측정에는 영향이 없다(실행하지 않음).
- 주인 id 유도는 fixtureId가 "<기능 id 대문자 스네이크>_V<revision>"
꼴이라는 이름 규칙에 기댄다. fixtureId는 닫힌 리터럴 하나라 지금은
참조 기능 id 하나로만 풀린다.
검증
- RED(수정 전 조립기): 새 테스트 2건 실패.
external-contract-runtime "rejects a fixture copied into a product
feature" -> "Expected contract composition to fail."
reference-fixture-provenance "rejects a second fixture contribution"
-> "expected undefined to be 'reference-feature: only one
TEMPLATE_FIXTURE contribution is allowed'".
- GREEN: 같은 3파일 22/22 통과.
- 회귀(298201f 위로 rebase 뒤): run-vitest tests/unit tests/features
tests/platform tests/component tests/contract tests/runtime-schema
tests/integration (pnpm·corepack을 띄우는 fixture-node-modules,
security-followup-archive, deployment-admission, lab-performance 제외)
267 files / 3107 tests 중 3106 통과. 실패 1건은
provider-guardian-transaction(guardian exit=126, 단독 실행도 같음)으로
scripts/lib 프로세스 테스트라 이 변경과 무관하다. tsc app/test rc=0. 바꾼 파일 eslint rc=0.
- 바꾼 src·tests/unit 파일에 샘플 잔여물 정규식 일치 0건(grep).
- 미실행: test:sample-removal, check:architecture(pnpm 필요).
Refs: docs/reviews/2026-11-01-maturity-review/07-contracts.md
문제
초기 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절
A feature directory without feature-module.ts vanished silently, registry
consumers listed only the sample's directories, and the removal gate only knew
the sample. The generator now fails unless a NOT_INSTALLED marker says so
(D-10), consumer directories are globs over every feature, and the removal
script takes --feature=<id>. starter-experience.md documents the current
ownership declarations and the files a new feature touches.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An external owner without readSubject made every authenticated
notification (every token refresh) abort requests and clear the
server-state cache. readSubject is now a required owner method and
getSubject a required SessionGateway method.
- ExternalSessionOwner.readSubject(): required; the host owner check
(EXTERNAL_OWNER_METHODS) rejects an owner without it, so the session
fails closed as integration-failed like any other missing method.
- SessionGateway.getSubject(): required. Anonymous and unavailable
adapters return null; demo already returned its fixed user.
- Scope runtime: same (state, subject) still skips the fence; a state
or subject change still fences. An authenticated session with a
null/empty subject still fences (fail closed) and now records
cache.operation.failed {operation: SCOPE_FENCE, reason:
SUBJECT_MISSING} once per fence. Bootstrap passes diagnostics in.
- Docs: starter-experience external owner section and port comments
describe what readSubject returns, the fail-closed diagnostic and a
migration note.
RED before the change (vitest tests/unit/server-state-scope-runtime.test.ts
tests/unit/runtime-adapters.test.ts): 4 failed | 31 passed
- fails closed when the owner lacks readSubject:
expected 'authenticated' to be 'integration-failed'
- fences and reports SUBJECT_MISSING ... null / empty subject, and the
external owner whose readSubject returns null:
expected [] to deeply equal [[{ level: 'warn', ... }]]
- type level: an owner literal without readSubject compiled (tsc exit
0). The new @ts-expect-error pin fails check:types:test with TS2578
if readSubject becomes optional again.
Pins that stayed green: same-subject token refresh keeps the cache,
subject change fences, sign-out fences, owner missing readState is
rejected.
GREEN: check:architecture, check:types:app, check:types:test, lint,
test:unit (2084), test:component (182), test:reference-feature (59),
test:integration (151), verify:documentation, check:diagnostics,
check:ci all pass.
BREAKING: external auth owners must implement readSubject(); code that
implements AuthSessionPort/SessionGateway directly must implement
getSubject().
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
readSubject/getSubject must be an opaque, non-empty id that is stable per
user and never a token. Without it, every authenticated notification
clears server state.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>