소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.4절)으로 템플릿 샘플을 지운다. 샘플이 맡던 시험 대상은 앞 커밋들이 옮겼다. 참조 기능과 예제 화면, 두 context, 그 시험, e2e 3개, 수동 접근성 기록 7개, 런타임 프로필 키, test:reference-feature(명령, 산출물, 게이트 참조), 커버리지 정책 행을 지웠다. removable-template-features 목록은 비우고 장치는 남겼다: test:sample-removal은 인자가 없으면 목록을 하나씩 지우고, 비면 SKIP을 출력하고 보고서에 건너뛴 사례를 남긴다. 기능 스위치 시험과 홈 시작 링크 스위치 시험은 시험 전용 fixture 기능으로 옮겼다. browser soak은 생성 기능을 넣은 빌드에서 돈다. 문서의 샘플 경로를 고쳤다. 날짜가 붙은 설계·리뷰 기록의 본문은 그대로 두었다. 레지스트리 기준선(update:registry-baseline, OWNER DongHyeonka), CI 계약 기준선과 workflow, 초기 JS 기록(194,354B, 17파일, 첫 기능 6,327B, 기능 539B, context 4B)을 다시 받았다. 위험: 레지스트리 행 삭제는 breaking이다. 샘플을 고쳐 쓰는 다운스트림은 수정/삭제 충돌을 만난다. 성능 lab의 기능 라우트 측정은 템플릿에 공개 기능 라우트가 없어 measured:false다. TEMPLATE_FIXTURE 출처는 플랫폼 코드에 남았다. 검증(desktop): check:types, lint, check:architecture, check:registries, check:ci, verify:documentation, test:unit, test:component, test:contract, test:integration, test:recipes, test:coverage(Risk coverage PASS 378/378, 문턱 68개), test:e2e 183, test:a11y, test:visual, test:storybook, test:browser-capabilities, test:feature-scaffold PASS(76 checks), test:sample-removal SKIP, build, check:bundle.
5.2 KiB
Contract ownership
src/contracts is not a default destination for every shared-looking type.
A contract belongs there only when the change authority is genuinely shared
across layers, capabilities, build tooling, or runtime composition.
Decision rule
For every proposed contract, ask:
- Which requirement can cause this type or policy to change?
- Is there one clear capability or feature owner?
- Does another runtime/tooling boundary consume the same semantic contract?
- Is the contract a wire/artifact authority shared by browser runtime and build/release tooling?
The placement rule is:
- one feature owner -> keep it under that feature,
- one reusable capability owner -> keep it under that adapter/capability and export it through the capability public entry point,
- a product-neutral primitive any layer may call, with no product vocabulary
in it (a budget, deadline, retry, execution context, telemetry pipeline step
or error envelope) ->
src/platform, - multiple independent capability/layer owners ->
src/contracts, - browser/build/release wire or artifact authority ->
src/contractseven when the browser source graph alone looks small.
Consumer count alone is not sufficient. Scripts, generated artifacts and release gates are semantic consumers too.
src/platform and src/contracts differ in what they hold. src/contracts
holds the product's shared vocabulary: registries, schemas and wire formats
such as routes, API operations, storage keys and release artifacts.
src/platform holds mechanisms that work without that vocabulary, plus the
few error kinds no feature owns (network, deadline, cancellation, response
bounds). Today src/contracts imports src/platform and not the other way
round. platform-kernel-is-product-neutral stops src/platform from importing
any feature, context, app, adapter, bootstrap, presentation or application
module. A primitive that needs a route, an API operation or a feature's
vocabulary is not product-neutral: put it in src/contracts or with its owner.
Audit result
The September 2026 architecture review triggered an import-graph audit of all 39 contract files.
Capability-owned contract moved
cursor-pagination.ts had one production owner:
src/adapters/query-cache/cursor-pagination-runtime.ts.
It moved to:
src/adapters/query-cache/cursor-pagination-contract.ts
and is exported through:
src/adapters/query-cache/index.ts
Tests use that public capability entry point. Pagination vocabulary no longer occupies the global contract bucket merely because it is reusable inside one adapter.
Contracts intentionally kept global
The following examples have multiple semantic owners and remain global:
errors.ts— application, presentation and several adapters,result.ts— common success/failure carrier below application,boundary-mapper.ts— HTTP, browser RPC, realtime and feature registries,mutation-intent.ts— application, presentation, HTTP, platform and bootstrap,exact-snapshot.ts— HTTP, query-cache and browser-transfer,rest-profiles.ts— auth, HTTP, bootstrap and feature contract validation,query-invalidation.ts/query-keys.ts— query-cache, presentation, bootstrap and features,cache-invalidation.ts— cross-context wire protocol plus query invalidation policy,storage-keys.ts— browser storage and cross-context invalidation,telemetry.ts/diagnostics.ts— runtime adapters, application and bootstrap.
Some contracts appear to have few browser-source consumers but are still shared authorities:
env.tsis consumed by bootstrap, runtime-schema/security tests and registry governance,deployment-admission.tsis shared by runtime-config generation and release admission,release-tokens.tsis shared by runtime coherence tooling and tests,service-worker-static-manifest.tsis a runtime-neutral canonical format shared by build generation, validation and service-worker evidence.
Moving those based only on src/** import counts would split one semantic
authority across processes.
Feature contracts
Feature-specific contracts stay inside the vertical slice:
features/<feature>/contracts
A feature owns its routes, schemas, mapper definitions, message catalogs and
contribution identities (create:feature writes them under its contracts/). Central installed files aggregate those
contributions; they do not own their semantics.
The message catalog is a deliberate special case: the compiled catalog remains total even when a feature is build-time disabled so the typed message lookup does not become partial. The central message file therefore aggregates compiled message keys rather than treating runtime installation as message ownership.
Review rule for future additions
A new file under src/contracts should be rejected during review when all of
the following are true:
- one feature or one capability is the only semantic owner,
- no build/release/runtime wire authority needs the same definition,
- moving the definition to that owner does not create an inward dependency violation.
Do not move a contract merely to reduce the number 39. The goal is explicit ownership, not a smaller directory.