Edge Config And Runtime Refresh Contract

계약 메타

id: iop.edge-config-runtime-refresh
boundary: inner
status: active
원본 경로:
- packages/go/config/config.go
- configs/edge.yaml
- apps/edge/internal/configrefresh/request.go
- apps/edge/internal/configrefresh/result.go
- apps/edge/internal/configrefresh/classify.go
- proto/iop/runtime.proto
- apps/edge/internal/node/mapper.go
- apps/node/internal/adapters/config_set.go
human docs: apps/edge/README.md

읽는 조건

configs/edge.yaml, packages/go/config, provider pool, openai.model_routes, models[], nodes[].providers[], adapter instance 설정을 바꿀 때
iop-edge config refresh의 dry-run/apply 결과 schema나 restart/applied 분류를 바꿀 때
Edge가 Node에 전달하는 NodeConfigPayload 또는 NodeConfigRefresh* payload를 바꿀 때

범위

이 계약은 Edge 설정 YAML, Go config struct, config refresh 결과, Edge-to-Node runtime config payload의 연결 규칙이다. tracked config에는 public 예시와 기본 구조만 두고, 실제 endpoint/credential/private host 값은 환경별 private 설정으로 주입한다.

핵심 규칙

openai.model_routes[]는 외부 OpenAI-compatible model id를 내부 adapter + target route로 매핑하는 compatibility catalog다.
models[]는 provider pool 방향의 canonical routing key이며 nodes[].providers[].id를 참조한다.
nodes[].providers[]는 Node 아래 resource/provider catalog다. category는 api, cli, local_inference resource kind를 나타낸다.
nodes[].providers[].id는 전체 Edge config 안에서 중복되면 안 된다.
nodes[].providers[].adapter는 같은 Node 안의 enabled adapter instance key를 참조해야 한다. Exact instance key를 우선하고, legacy type-name route는 같은 type의 enabled instance가 정확히 하나일 때만 허용한다. category: cli resource는 enabled CLI adapter가 필요하다.
nodes[].providers[].enabled: 생략 또는 true → provider pool dispatch 후보에 포함. false → dispatch pool에서 제외. 비활성화된 provider는 status snapshot에 status=disabled, health=disabled, capacity=0으로 표시된다. adapter process lifecycle 변경 없음. config refresh 시 enabled 토글은 live-apply(restart 불필요)로 분류된다. disabled provider의 adapter reference check는 skip되지만 structural validation(type, category, models, numeric bounds)은 수행된다.
legacy single-instance adapter 설정은 load 시 named instance slice로 normalize된다.
NodeConfigPayload는 Edge가 Node에 내려주는 실행 adapter/runtime payload다.
refresh 결과는 applied, restart_required, rejected를 구분하고, changed node/provider/model/report slice는 안정적으로 non-nil이어야 한다.

refresh 분류 기준

live apply 가능: provider capacity, provider max queue, provider queue timeout, provider enabled toggle, models[] display/provider mapping, legacy node runtime concurrency metadata.
restart required: Edge identity/listen/bootstrap/logging/metrics/console/control-plane/openai/a2a listener config, node 추가/삭제, node token/alias/agent kind, adapter 설정, provider type/category/adapter/models/health/lifecycle capability, provider-first execution fields(provider, endpoint, base_url, headers, command, args, env, mode, resume_args, output_format, context_size, request_timeout_ms) 변경.
rejected: candidate config load/validate 실패, invalid refresh mode, apply failure.

금지 사항

설정 파일만 바꾸고 packages/go/config loading/default/validation과 불일치하게 두지 않는다.
provider id, model id, route id의 의미를 섞지 않는다. 외부 model은 OpenAI-compatible 경계의 route key이고, 내부 실행은 adapter + target이다.
credential, bearer token, private endpoint 원문을 tracked docs/roadmap/contract에 기록하지 않는다.
Node bootstrap 기본 경로에서 사용자가 직접 node config를 작성하거나 adapter/provider 값을 명령줄로 넣어야 하는 계약을 만들지 않는다.

변경 시 확인할 코드/테스트

packages/go/config/config_test.go
apps/edge/internal/configrefresh/classify_test.go
apps/edge/internal/edgecmd/edgecmd_test.go
apps/edge/internal/node/mapper_test.go
apps/node/internal/adapters/config_set_test.go
agent-test/local/platform-common-smoke.md
agent-test/local/edge-smoke.md

4.5 KiB Raw Blame History