문제: 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
5.1 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
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.