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

9 KiB
Raw Permalink Blame History

domain last_rule_review_commit last_rule_updated_at
platform-common 7ca329ac9e 2026-07-14

platform-common

목적 / 책임

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

포함 경로

  • packages/go/auth/ — mTLS 인증 설정 helper
  • packages/go/audit/ — 공통 audit event envelope, event type, policy decision baseline
  • 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.EdgeRefreshConf — Edge-local runtime config refresh admin server 설정 계약
  • config.EdgeOpenAIConf / config.EdgeA2AConf / config.EdgeConsoleConf — edge 입력 표면과 console 기본 설정 계약
  • config.OpenAIPrincipalTokenConf / config.EdgeOpenAIProviderAuthConf — OpenAI-compatible caller principal token hash mapping과 provider auth forwarding 설정 계약
  • config.ModelCatalogEntry / config.NodeProviderConf — provider pool model catalog와 node provider candidate 설정 계약
  • config.CLIProfileConf / config.CompletionMarkerConf — CLI adapter profile, mode, resume args, completion marker 설정 계약
  • config.OllamaConf / config.VllmConf / config.OpenAICompatConf — provider endpoint, capacity, queue, timeout 설정 계약
  • config.NormalizeAgentKind() / config.NormalizeProviderType() — agent kind와 provider type canonicalization helper
  • audit.Event / audit.EventType / audit.PolicyDecision — 실행, terminal, bootstrap event와 정책 판단 공통 envelope
  • 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 — 앱 간 메시지 원본 계약
  • Job / JobListRequest / JobListResponse — worker/job 상태 조회 placeholder protobuf 계약
  • ProviderTunnelRequest / ProviderTunnelFrame — Edge-Node provider raw tunnel protobuf 계약
  • NodeConfigRefreshRequest / NodeConfigRefreshResponse — Edge runtime config refresh를 node에 전달하는 protobuf 계약
  • ProviderSnapshot / AgentUsageStatus — Edge/Control Plane status와 node command result에 쓰는 runtime 상태 계약
  • ClientHelloRequest / ClientHelloResponse — Client-Control Plane hello baseline 계약
  • EdgeHelloRequest / EdgeHelloResponse — Edge가 Control Plane으로 연결할 때 쓰는 hello baseline 계약
  • EdgeStatusRequest / EdgeStatusResponse / EdgeNodeSnapshot — Control Plane이 Edge-owned node snapshot을 조회하는 wire 계약
  • EdgeCommandRequest / EdgeCommandResponse / EdgeCommandEvent — Control Plane이 Edge-owned operation을 요청하고 결과/event를 관찰하는 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에는 소유권과 금지 사항만 둔다.
  • 공통 패키지는 작고 명확한 계약을 유지하고 앱별 정책을 과도하게 끌어올리지 않는다.
  • audit package는 공통 event envelope와 validation/redaction baseline까지만 제공한다. durable audit store, retention executor, query API는 앱/운영면 설계에서 별도로 둔다.
  • 공통 event helper는 envelope 생성과 상수 정의까지만 담당하고, edge 내부 fanout/replay/store 정책은 edge 도메인에 둔다.
  • RunRequest, ExecutionSpec, NodeCommandRequest, ProviderTunnelRequest, CLIProfileConfig, job/history 계열 계약을 변경할 때 내부 실행 용어는 target을 우선하고, model은 외부 호환 경계인지 확인한다.
  • provider pool/config refresh schema를 바꾸면 models[], nodes[].providers[], adapter instance config, configs/*.yaml, agent-contract/inner/edge-config-runtime-refresh.md를 함께 확인한다.
  • raw OpenAI-compatible usage token이나 provider token을 공통 config에 저장하지 않는다. caller principal은 hash/ref/alias로 표현하고 provider auth forwarding 설정은 header 이름과 정책만 담는다.
  • 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/audit/**, packages/go/events/**, packages/go/hostsetup/**, configs/**, proto/iop/**처럼 edge-node 실행 설정, setup, audit/lifecycle event, 메시지 계약에 영향을 주는 작업을 한 뒤에는 testing domain rule의 작업 후 검증 기준을 따른다.

다른 도메인과의 경계

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

금지 사항

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