toki/iop
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
iop/agent-ops/rules/project/domain/platform-common/rules.md
toki de78479670 refactor: organize contract files and update agent-ops structure 
- Move contract files to inner/outer directory structure
- Add create-contract and update-contract skills
- Update agent-ops rules and domain rules
- Update roadmap and SDD documentation
- Update README files across apps
2026-06-27 07:02:48 +09:00

6.6 KiB
Raw Blame History

domain last_rule_review_commit last_rule_updated_at
platform-common 49872ae120 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와 불일치하게 두지 않는다.