Files
clean-architecture-frontend…/docs/architecture/contract-ownership.md
T
DongHyeonka e3c8db48ae chore(features): 참조 기능과 예제 화면을 지우고 레지스트리를 다시 승인한다
소유자 결정(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.
2026-11-08 14:07:58 +09:00

125 lines
5.2 KiB
Markdown

# 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:
1. Which requirement can cause this type or policy to change?
2. Is there one clear capability or feature owner?
3. Does another runtime/tooling boundary consume the same semantic contract?
4. 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/contracts` even
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.ts` is consumed by bootstrap, runtime-schema/security tests and
registry governance,
- `deployment-admission.ts` is shared by runtime-config generation and release
admission,
- `release-tokens.ts` is shared by runtime coherence tooling and tests,
- `service-worker-static-manifest.ts` is 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.