# 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[].id`는 전체 Edge config 안에서 중복되면 안 된다.
- 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, `models[]` display/provider mapping, node runtime concurrency.
- restart required: Edge identity/listen/bootstrap/logging/metrics/console/control-plane/openai/a2a listener config, node 추가/삭제, node token/alias/agent kind, adapter 설정, node workspace root, provider type/category/adapter/models/health/lifecycle capability.
- 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`