---
domain: platform-common
last_rule_review_commit: 49872ae120627c47175194e837d90f8915d67397
last_rule_updated_at: 2026-06-01
---

# platform-common

## 목적 / 책임

여러 앱이 공유하는 설정, 인증, 이벤트 helper, host setup, 정책, 메타데이터, 작업 상태, 관측성, 버전, protobuf 계약을 관리한다. 앱별 구현보다 안정적인 공통 계약과 작은 유틸리티를 제공하며, 내부 실행 계약은 `adapter + target` 방향을 우선한다.

## 포함 경로

- `packages/go/auth/` — mTLS 인증 설정 helper
- `packages/go/config/` — 앱 설정 struct, 기본값, YAML 로딩
- `packages/go/events/` — 공통 EdgeNodeEvent 생성 helper와 lifecycle 상수
- `packages/go/hostsetup/` — edge/node systemd 설치 준비와 기본 설정 템플릿
- `packages/go/jobs/` — 작업 상태와 작업 메타데이터 타입
- `packages/go/metadata/` — 공통 metadata map helper
- `packages/go/observability/` — zap logger와 Prometheus health/metrics 서버
- `packages/go/policy/` — 정책 엔진 인터페이스와 passthrough 구현
- `packages/go/version/` — 앱 버전 상수
- `proto/iop/` — protobuf 메시지 계약 원본
- `proto/gen/iop/` — protobuf 생성물
- `configs/` — 앱별 설정 예시

## 제외 경로

- `apps/node/` — node 실행 파이프라인과 adapter 관리
- `apps/edge/` — 실행 그룹 컨트롤러와 node registry
- `apps/control-plane/` — 중앙 제어면 앱 구현 영역
- `apps/client/` — Flutter client app과 Dart protobuf 생성물 사용 영역
- `packages/flutter/iop_console/` — Flutter client/console UI package이므로 client domain 소유
- `apps/worker/` — worker 앱 구현 예정 영역

## 주요 구성 요소

- `config.NodeConfig` / `config.EdgeConfig` — node/edge 앱 설정 계약
- `config.EdgeInfo` / `config.EdgeControlPlaneConf` — Edge identity와 Control Plane outbound connector 설정 계약
- `config.EdgeServerConf` / `config.EdgeBootstrapConf` — Edge listen/advertise host와 artifact bootstrap URL 설정 계약
- `config.EdgeOpenAIConf` / `config.EdgeA2AConf` / `config.EdgeConsoleConf` — edge 입력 표면과 console 기본 설정 계약
- `config.CLIProfileConf` / `config.CompletionMarkerConf` — CLI adapter profile, mode, resume args, completion marker 설정 계약
- `config.OllamaConf` — Ollama base URL과 context size 설정 계약
- `auth.LoadServerTLS` / `auth.LoadClientTLS` — mTLS TLS config 생성
- `events.NewEdgeNodeEvent()` — node/edge lifecycle event envelope 생성
- `hostsetup.Run()` / `hostsetup.EdgeSpec()` / `hostsetup.NodeSpec()` / `hostsetup.EdgeBundleConfigTemplate()` — systemd unit, 설정 파일, bundle-local edge config, 데이터 디렉터리 준비
- `observability.NewLogger` / `observability.ServeMetrics` — 공통 로깅/메트릭
- `policy.Engine` — 정책 적용/검증 계약
- `jobs.Job` — 비동기 작업 상태 placeholder; 내부 실행 대상은 `target`으로 표현
- `proto/iop/*.proto` — 앱 간 메시지 원본 계약
- `ClientHelloRequest` / `ClientHelloResponse` — Client-Control Plane hello baseline 계약
- `EdgeHelloRequest` / `EdgeHelloResponse` — Edge가 Control Plane으로 연결할 때 쓰는 hello baseline 계약
- `EdgeStatusRequest` / `EdgeStatusResponse` / `EdgeNodeSnapshot` — Control Plane이 Edge-owned node snapshot을 조회하는 wire 계약
- 상세 계약 라우팅은 `agent-contract/index.md`를 따르고, schema 원본은 `proto/iop/*.proto`와 `packages/go/config/config.go`를 우선한다.

## 유지할 패턴

- 공통 패키지는 특정 앱의 내부 패키지를 import하지 않는다.
- 설정 struct 필드 변경 시 YAML tag, mapstructure tag, default, `configs/*.yaml` 예시를 함께 확인한다.
- host setup 기본 템플릿을 바꿀 때는 `packages/go/hostsetup`의 `EdgeSpec`/`NodeSpec`, 기본 경로, systemd unit, 관련 CLI `setup` 옵션과 함께 확인한다.
- protobuf 계약 변경은 `proto/iop/*.proto`에서 시작하고 `make proto`로 Go 생성물을 갱신한다.
- Client가 소비하는 proto 계약을 변경하면 `make proto-dart`로 `apps/client/lib/gen/proto/iop/*.dart` 생성물도 갱신한다.
- 생성 파일(`proto/gen/iop/*.pb.go`)은 사람이 직접 편집하지 않는다.
- Edge-Node, Control Plane-Edge, Client-Control Plane, config/runtime refresh 계약 상세는 `agent-contract/inner/**` 문서를 기준으로 확인하고 domain rule에는 소유권과 금지 사항만 둔다.
- 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다.
- 공통 event helper는 envelope 생성과 상수 정의까지만 담당하고, edge 내부 fanout/replay/store 정책은 edge 도메인에 둔다.
- `RunRequest`, `ExecutionSpec`, `NodeCommandRequest`, `CLIProfileConfig`, job/history 계열 계약을 변경할 때 내부 실행 용어는 `target`을 우선하고, `model`은 외부 호환 경계인지 확인한다.
- Control Plane hello 계열 proto는 Edge/Node scheduling 계약으로 확장하지 않는다.
- Control Plane-Edge status proto는 Edge-owned snapshot을 표현한다. Node address, token, direct scheduling 필드를 싣지 않는다.
- `packages/go/config/**`, `packages/go/events/**`, `packages/go/hostsetup/**`, `configs/**`, `proto/iop/**`처럼 edge-node 실행 설정, setup, lifecycle event, 메시지 계약에 영향을 주는 작업을 한 뒤에는 `testing` domain rule의 작업 후 검증 기준을 따른다.

## 다른 도메인과의 경계

- **node**: node가 필요로 하는 설정/타입/계약을 제공하지만 실행 파이프라인의 소유자는 node이다.
- **edge**: edge가 필요로 하는 설정/관측성/protobuf 계약을 제공하지만 실행 그룹 제어와 node registry 동작의 소유자는 edge이다.
- **control-plane/client/worker**: 앱별 구현에 필요한 공통 타입만 이 영역으로 승격하고 앱 내부 책임은 각 도메인에 둔다.

## 금지 사항

- `packages/go`에서 `apps/*/internal` 패키지를 import하지 않는다.
- 앱 하나만을 위한 임시 타입을 충분한 근거 없이 공통 패키지로 승격하지 않는다.
- edge fanout bus, web UI state, control-plane session 관리처럼 특정 앱의 운영 상태를 공통 패키지로 끌어올리지 않는다.
- 내부 실행 계약을 확장하면서 `model` 중심 명명을 되살리지 않는다. 외부 API 호환이 필요한 경우 경계와 변환 위치를 명시한다.
- protobuf 생성물을 직접 수정하지 않는다.
- Client Dart protobuf 생성물을 proto 원본과 불일치하게 두지 않는다.
- 설정 파일만 바꾸고 `packages/go/config`의 로딩/default와 불일치하게 두지 않는다.