iop/agent-ops/rules/project/domain/edge/rules.md

edge

목적 / 책임

여러 Node를 하나의 로컬 실행 그룹으로 묶는 백엔드 실행 그룹 컨트롤러 영역이다. 현재는 node 연결을 수락하고 token 기반 등록을 검증한 뒤 adapter/runtime 설정을 내려주며, console 기반 실행 요청과 run event relay를 검증한다.

포함 경로

• apps/edge/cmd/edge/ — edge CLI 진입점과 serve 커맨드
• apps/edge/internal/bootstrap/ — fx 의존성 주입과 서버 시작/종료 lifecycle
• apps/edge/internal/node/ — 연결된 node registry와 node 선택
• apps/edge/internal/transport/ — node 연결 수락, RegisterRequest/Response 처리, run event 수신
• apps/edge/README.md — edge 계획과 현재 placeholder 범위

제외 경로

• apps/node/ — 실제 모델 실행과 adapter 관리
• apps/control-plane/ — 여러 Edge 연결 관리와 운영 화면 제공 예정 영역
• apps/worker/ — 비동기 작업 처리 예정 영역
• packages/ — 공통 설정/관측성/인증 패키지
• proto/ — 메시지 계약 원본과 생성물

주요 구성 요소

• transport.Server — proto-socket TCP 서버 wrapper; NodeStore와 Registry를 모두 주입받아 등록 흐름을 처리
• node.Registry — 연결된 node의 NodeEntry 저장/조회 (ID·alias 이중 인덱스, 동시성 안전)
• node.NodeEntry — node ID, alias, TCP client 정보
• node.NodeStore — 사전 등록된 NodeRecord를 token/ID로 조회; 설정 파일에서 seed
• node.NodeRecord — 사전 등록된 node 정의 (ID, alias, token, adapter/runtime config)
• node.BuildConfigPayload() — NodeRecord의 adapter 설정을 proto NodeConfigPayload로 변환하는 mapper
• bootstrap.Module — edge 서버와 metrics lifecycle 구성
• consoleEventRouter — console 모드에서 run event를 표준 출력으로 라우팅 (cmd/edge/)

유지할 패턴

• edge는 사전 등록된 node 정의를 검증하고 연결 상태를 registry에 반영하는 역할을 먼저 안정화한다.
• edge는 단순 gateway가 아니라 Node registry, adapter/profile configuration, routing, stream relay의 소유자다.
• 외부 OpenAI-compatible HTTP API는 node/transport 안정화 이후 확장하며, 내부 실행 모델 전체를 대표하지 않는다.
• node가 연결 직후 RegisterRequest를 보내고 edge가 RegisterResponse로 중앙 설정을 응답하는 흐름을 유지한다.
• Registry는 동시성 안전성을 유지하고 외부로 내부 map을 노출하지 않는다.
• NodeStore는 설정 파일에서 한 번 seed되며 런타임 중 변경하지 않는다; token 중복·빈 token은 LoadFromConfig에서 즉시 거부한다.
• adapter config 변환(mapper)은 node.BuildConfigPayload()에서만 수행하고 transport 레이어에 변환 로직을 두지 않는다.
• 내부 실행 요청은 adapter + target으로 표현한다. 외부 API 호환 경계의 model 표현을 edge 내부 책임 전체로 확장하지 않는다.

다른 도메인과의 경계

• node: edge는 node 내부 adapter를 직접 실행하지 않는다. edge는 사전 등록 정보와 연결 registry를 기반으로 요청을 보낼 대상과 실행 설정을 관리한다.
• platform-common: edge 설정, metrics, protobuf 타입은 platform-common 계약을 따른다.
• control-plane 후보: control-plane은 Edge를 통해 시스템을 제어한다. Node 직접 연결/직접 스케줄링을 control-plane 책임으로 굳히지 않는다.

금지 사항

• edge를 구현하면서 node adapter 실행 로직을 복제하지 않는다.
• OpenAI-compatible HTTP API를 추가할 때 내부 TCP/protobuf 경계를 우회하지 않는다.
• Control Plane 구현 전이라도 Node를 Control Plane에 직접 연결하는 경로를 edge 도메인에 추가하지 않는다.
• gRPC 또는 WebSocket을 기본 내부 transport로 바꾸지 않는다.
• proto/gen/iop/*.pb.go 생성 파일을 직접 수정하지 않는다.