문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨 둔 낡은 서술이 있다. - contract-ownership: 계약 파일 「39개」. 지금 src/contracts의 .ts는 44개다. - capability-consumer-experience: Local Draft를 「두 번째 구체 소비자」, 「두 feature」라고 부른다. 지금은 제품 feature가 아니라 테스트 fixture (tests/fixtures/indexeddb-consumer)다. - static-delivery: initialJavascript.files가 「예시 feature 기준」이라고 한다. feature-shape-ceilings.json은 feature가 없는 지금 템플릿 빌드라고 적는다. - .dependency-cruiser.json:254 주석이 번호 없는 layers.md의 「§4」를 가리킨다. - runbook 문서 제목 셋이 runbooks.json title과 다르다. FE-RB-002는 영어 원문부터 manifest가 빠져 있었고, 001·003은 번역에서 갈라졌다. - ci-quality-gates: zod 행의 고친 버전은 4.6.6인데 이유 칸은 4.6.7을 말한다. 4.6.7은 올렸을 때 잰 버전이다(26ca2fdb원문 "4.6.7 also adds"). - 같은 문서 FE-GATE-016 문단 끝 두 문장은 원래 runbook record 고정 경로 문단의 것이다(6c52cdb9원문). 폐기 문장 뒤로 밀려 뜻이 끊겼다. 고른 방법: 숫자는 옮겨 적지 않고 정본(src/contracts/)을 가리킨다. Local Draft는 fixture라고 쓰고, 편의 프로필을 들일 조건을 「IndexedDB를 쓰는 제품 feature」로 좁힌다. 절 번호는 절 이름으로, 문서 제목은 등록부 title로 맞춘다. zod는 「고친 버전 이상으로 올리면」으로 쓰고 잰 버전과 날짜를 괄호에 둔다. 두 문장은 원래 문단으로 옮긴다. 위험: zod 7 KB는 다시 재지 않았다(2026-11-04 측정값 그대로). cruiser 주석은 check:architecture 위반 메시지의 why 줄에 나온다. 이 주석을 비교하는 시험은 없다. 검증: 각 사실을 git ls-files, feature-shape-ceilings.json, runbooks.json, layers.md 절 제목, 원문 커밋으로 확인했다. 문서 검사와 관련 시험은 desktop에서 돌린다.
116 lines
5.9 KiB
Markdown
116 lines
5.9 KiB
Markdown
# 계약 소유
|
|
|
|
`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/<feature>/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로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.
|
|
|
|
계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.
|