Files
clean-architecture-frontend…/docs/architecture/contract-ownership.md
DongHyeonka 374af98640 docs: 번역하며 찾은 낡은 서술을 코드·설정에 맞춘다
문제: 살아 있는 문서를 옮길 때 뜻을 바꾸지 않는다는 규칙 때문에 남겨
둔 낡은 서술이 있다.
- 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에서 돌린다.
2026-11-12 09:40:51 +09:00

5.9 KiB

계약 소유

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로 옮겨도 안쪽 방향 의존성 규칙을 어기지 않는다.

계약 파일 수를 줄이려고 계약을 옮기지 않는다. 목표는 디렉터리를 작게 하는 것이 아니라 소유를 분명히 하는 것이다.