문제: src/ 최상위 폴더는 adapters application apps bootstrap contexts
contracts features platform presentation 9개다. layers.md 표,
frontend-application-foundation.md 목록, overview.md 그림, README 구조
그림은 src/platform을 한 번도 적지 않았고 apps·contexts는 금지 간선
설명에만 나왔다. 대신 없는 최상위 domain을 계층으로 그렸다.
contract-ownership.md의 배치 규칙에는 src/platform 선택지가 없었다.
layers.md는 "표와 규칙이 어긋날 수 없다"고 적었지만
.dependency-cruiser.json 규칙 31개 중 25개의 이름이 없었다.
게이트는 금지 간선만 막으므로, 허용되지만 틀린 자리(최상위 domain 신설,
제품 중립 primitive를 contracts에 두기)를 문서로 막을 수 없었다.
고른 방법: 리뷰의 (B)안. 문서를 코드에 맞추고 verify:documentation에
대조 검사를 더한다.
- layers.md: 9개 폴더 표(폴더 | 소유)를 정본으로 두고, 금지 간선 글머리
목록을 규칙 31개 표(규칙 이름 | 적용 대상 | 금지)로 바꾼다. domain은
기능 안의 계층으로 옮기고 "최상위 domain 폴더는 지금 없고, 만들면
domain-is-framework-neutral이 이미 적용된다"고 적는다. 보증 문장은
실제로 검사하는 범위로 줄인다. kernel 절과 배럴 절은 그대로 둔다.
- README·overview·foundation: layers.md 표의 설명을 한 글자도 바꾸지
않고 "`src/<폴더>` — <설명>" 목록으로 싣는다. 그림은 실제 import
방향(presentation -> application -> contracts -> platform,
apps -> contexts -> features)으로 다시 그린다.
- contract-ownership.md: src/platform 선택지와 contracts와의 차이,
platform-kernel-is-product-neutral을 적는다.
- verify-documentation-readiness.ts: 폴더 목록은 src/를 읽고, 규칙 목록은
.dependency-cruiser.json을 읽는다. layers.md 표에 행이 없는 폴더,
나머지 세 문서에서 설명이 다른 폴더, 네 문서가 적은 없는 최상위
src 폴더, layers.md에 없는 규칙 이름이 있으면 실패한다. 결과는
documentation-review.json의 sourceStructure로 남긴다(스키마는 필드
하나를 더한다).
버린 대안: (A) 문서만 고치기 — 규칙이나 폴더가 늘면 다시 어긋난다.
(C) layers.md를 .dependency-cruiser.json에서 생성 — 사람이 읽는 설명을
넣기 어렵다. 네 문서 모두에 규칙 31개를 싣는 것 — 같은 목록이 네 벌이
되어 어긋날 곳만 늘어난다. 규칙 표는 layers.md 한 곳에 둔다.
위험·한계:
- 검사는 규칙 이름이 있는지만 본다. 행의 설명이 규칙과 맞는지는 보지
않는다(문서에도 그렇게 적었다).
- 없는 폴더 검사는 "src/<이름>" 꼴만 잡는다. "domain"처럼 src/ 없이
계층 이름만 쓰는 것은 잡지 못한다.
- README·overview·foundation에는 같은 9줄이 복사되어 있다. 설명을 바꾸면
네 곳을 함께 고쳐야 하고, 검사가 그것을 강제한다.
- .dependency-cruiser.json 주석의 "like src/domain"(feature-domain 규칙)은
코드 주석이라 이번 범위 밖이다.
- 문서 drift 전반(경로·줄 번호, 14-05)은 다루지 않는다.
검증:
- RED: 새 검사를 기준 커밋(7a70cea)의 문서에 돌리면 FAIL_UNVERIFIED
(failed: source structure). layers.md는 규칙 25개가 없고, 네 문서
모두 9개 폴더를 설명하지 않는다고 나온다.
- GREEN: node scripts/verify-documentation-readiness.ts -> PASS_SCOPED.
tests/unit/documentation-readiness.test.ts 6개 통과. 새 변이 3개:
규칙 이름 하나를 바꾸면, README에 `src/domain`을 넣으면, overview의
platform 설명을 바꾸면 각각 실패하고 원인 문서와 이름을 적는다.
- 회귀: tests/unit 전체(fixture-node-modules 제외, pnpm 설치를 띄운다)
173파일 2494개 통과. ci-artifact-contract의 "semantically invalid"
16개 통과. tsc(node, test) 통과, 바꾼 ts 파일 eslint 통과.
- 미실행: check:architecture(pnpm 필요, worktree에서 금지).
Refs: docs/reviews/2026-11-01-maturity-review/14-template-product-docs.md 14-03
125 lines
5.1 KiB
Markdown
125 lines
5.1 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`
|
|
|
|
The reference feature owns routes, schemas, mapper definitions, message
|
|
catalogs and contribution identities. 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.
|