# 계약 소유 `src/contracts`는 공유되는 것처럼 보이는 타입을 모두 넣는 기본 자리가 아니다. 계약을 바꿀 권한이 계층, capability, 빌드 도구, runtime 조립 사이에 정말로 나뉘어 있을 때만 계약이 거기 들어간다. ## 판단 규칙 제안된 계약마다 묻는다. 1. 어떤 요구 사항이 이 타입이나 정책을 바꾸게 할 수 있나? 2. 분명한 capability owner나 feature owner가 하나 있나? 3. 다른 runtime 경계나 도구 경계가 같은 의미의 계약을 쓰나? 4. 이 계약이 브라우저 runtime과 빌드·release 도구가 함께 따르는 wire 형식이나 산출물(artifact)의 기준인가? 두는 자리는 다음 규칙으로 정한다. - feature owner가 하나 -> 그 feature 아래에 둔다. - 재사용 capability owner가 하나 -> 그 adapter·capability 아래에 둔다. 그리고 capability의 공개 진입점으로 export한다. - 어느 계층이든 부를 수 있고 제품 어휘가 들어 있지 않은 제품 중립 primitive (budget, deadline, retry, 실행 context, telemetry pipeline 단계, 오류 envelope) -> `src/platform` - 서로 독립된 capability·계층 owner가 여럿 -> `src/contracts` - 브라우저·빌드·release가 함께 따르는 wire 형식이나 산출물의 기준 -> `src/contracts`. 브라우저 소스 그래프만 보면 작아 보여도 그렇다. 소비자 수만으로는 판단할 수 없다. script, 생성된 산출물, release gate도 의미상의 소비자다. `src/platform`과 `src/contracts`는 담는 것이 다르다. `src/contracts`는 제품의 공유 어휘를 담는다. 라우트, API operation, storage key, release 산출물 같은 registry, schema, wire 형식이다. `src/platform`은 그 어휘 없이 동작하는 장치를 담는다. 그리고 어느 feature도 소유하지 않는 몇 가지 오류 종류(network, deadline, 취소, 응답 한도)도 담는다. 지금은 `src/contracts`가 `src/platform`을 import하고, 반대 방향은 없다. `platform-kernel-is-product-neutral`은 `src/platform`이 feature, context, app, adapter, bootstrap, presentation, application 모듈을 import하지 못하게 막는다. 라우트, API operation, feature 어휘가 필요한 primitive는 제품 중립이 아니다. 그런 것은 `src/contracts`에 두거나 그 owner 곁에 둔다. ## 감사 결과 2026년 9월 아키텍처 리뷰를 계기로 그때 `src/contracts`에 있던 계약 파일 전체의 import 그래프를 감사했다. 지금 파일 목록은 `src/contracts/`가 정본이다. ### capability 소유 계약을 옮김 `cursor-pagination.ts`를 운영 코드에서 소유한 곳은 하나였다. `src/adapters/query-cache/cursor-pagination-runtime.ts`다. 이 파일은 다음으로 옮겼다. `src/adapters/query-cache/cursor-pagination-contract.ts` 그리고 다음을 거쳐 export된다. `src/adapters/query-cache/index.ts` 테스트도 그 capability 공개 진입점을 쓴다. pagination 어휘는 이제 adapter 하나 안에서 재사용된다는 이유만으로 전역 계약 자리를 차지하지 않는다. ### 일부러 전역에 둔 계약 다음 예는 의미상의 owner가 여럿이라 전역에 남는다. - `errors.ts` — application, presentation, 여러 adapter - `result.ts` — application 아래에서 쓰는 공통 성공·실패 운반 타입 - `boundary-mapper.ts` — HTTP, 브라우저 RPC, realtime, feature registry - `mutation-intent.ts` — application, presentation, HTTP, platform, bootstrap - `exact-snapshot.ts` — HTTP, query-cache, browser-transfer - `rest-profiles.ts` — auth, HTTP, bootstrap, feature 계약 검증 - `query-invalidation.ts` / `query-keys.ts` — query-cache, presentation, bootstrap, feature - `cache-invalidation.ts` — cross-context wire 프로토콜과 query 무효화 정책 - `storage-keys.ts` — 브라우저 storage와 cross-context 무효화 - `telemetry.ts` / `diagnostics.ts` — runtime adapter, application, bootstrap 어떤 계약은 브라우저 소스에서 쓰는 곳이 적어 보이지만, 여전히 여러 곳이 함께 따르는 기준이다. - `env.ts`는 bootstrap, runtime-schema·보안 테스트, registry governance가 쓴다. - `deployment-admission.ts`는 runtime-config 생성과 release 승인(admission)이 함께 쓴다. - `release-tokens.ts`는 runtime 정합성 도구와 테스트가 함께 쓴다. - `service-worker-static-manifest.ts`는 runtime에 묶이지 않는 정식 형식이다. 빌드 생성, 검증, Service Worker 증거가 함께 쓴다. `src/**`의 import 수만 보고 이것들을 옮기면, 의미상 하나인 기준이 여러 프로세스로 쪼개진다. ## feature 계약 feature 전용 계약은 세로 slice 안에 둔다. `features//contracts` feature는 자기 라우트, schema, mapper 정의, message 카탈로그, contribution 식별자를 소유한다(`create:feature`가 이것들을 그 feature의 `contracts/` 아래에 쓴다). 중앙 설치 파일은 이 contribution을 모을 뿐, 그 의미를 소유하지 않는다. message 카탈로그는 일부러 둔 예외다. 빌드 때 feature를 꺼도 컴파일된 카탈로그는 모든 키를 그대로 갖는다. 그래야 타입이 있는 message 조회가 일부 키에서 비지 않는다(partial이 되지 않는다). 그래서 중앙 message 파일은 컴파일된 message 키를 모은다. runtime에 설치됐다는 사실을 message 소유로 보지 않는다. ## 앞으로 더할 때의 리뷰 규칙 `src/contracts` 아래 새 파일은 다음이 모두 참이면 리뷰에서 거부한다. - 의미상의 owner가 feature 하나나 capability 하나뿐이다. - 같은 정의가 필요한 빌드·release·runtime wire 기준이 없다. - 정의를 그 owner로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다. 계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.