iop/agent-spec/runtime/provider-pool-config-refresh.md

spec_doc_type	spec_id	status	source_evidence
spec	runtime/provider-pool-config-refresh	부분	type path notes contract agent-contract/inner/edge-config-runtime-refresh.md Edge config, provider pool, config refresh, Node payload 연결 계약 type path notes code packages/go/config/config.go Edge config struct, provider/model validation, adapter normalization type path notes code configs/edge.yaml provider-pool 권장 설정 예시와 live refresh 설정 예시 type path notes code apps/edge/internal/service/model_queue.go provider/resource capacity, priority, queue, long-context slot admission type path notes code apps/edge/internal/configrefresh/classify.go dry-run/apply classification과 changed path report 생성 type path notes code apps/edge/internal/bootstrap/runtime.go mutable config apply, runtime snapshot 교체, Node refresh push type path notes test packages/go/config/config_test.go config load/validation 검증 type path notes test apps/edge/internal/configrefresh/classify_test.go refresh classification 검증

스펙: Provider Pool과 Config Refresh

목적

Edge 설정에서 provider-pool이 어떻게 모델 실행 후보를 고르고, 어떤 설정 변경이 재시작 없이 반영되는지 설명한다.

기능 목록

기능	설명
model catalog	models[].id는 외부 OpenAI-compatible model key이자 provider-pool ModelGroupKey다.
provider mapping	models[].providers는 provider id를 실제 served model name으로 매핑한다.
node provider catalog	nodes[].providers[]는 Node 아래 resource/provider catalog이며 provider id는 Edge config에서 전역 유일해야 한다.
config validation	config load가 provider id 참조, served model membership, numeric bounds, long-context budget을 검증한다.
provider 후보 필터링	dispatch는 connected node의 provider 후보 중 catalog match, enabled, healthy/available, capacity 조건을 만족하는 후보만 사용한다.
capacity/priority dispatch	in-flight가 capacity 미만인 후보를 고르고, 동률이면 낮은 priority와 round-robin을 적용한다.
long-context admission	estimated input token이 threshold 이상이면 context_class=long으로 분류하고, provider long slot이 있으면 일반 capacity slot과 함께 점유한다.
config refresh dry-run/apply	loopback admin HTTP POST /refresh가 candidate config를 dry-run 또는 apply한다.
refresh classification	listener, Edge identity, bootstrap path, adapter structural 변경 등은 restart-required로 분류한다.
mutable apply	적용 가능한 변경은 Edge Cfg, NodeStore, service/input model catalog, OpenAI long-context threshold를 copy-on-write로 교체한다.
Node config refresh push	변경이 있으면 Edge가 연결된 Node에 node-specific NodeConfigRefreshRequest를 push한다.
Node registry swap	Node는 refresh payload로 새 adapter registry를 만들고 router registry를 swap한다. old registry stop은 active run이 있으면 drain 이후로 지연한다.

범위

• 포함: Edge config load/default/validation, provider-pool dispatch, queue admission, long-context admission, config refresh classification/apply, Node config refresh payload.
• 제외: 개별 adapter의 provider API 호출 세부, OpenAI HTTP request/response shape, Control Plane 원격 config 변경 UX, private credential 관리.

주요 흐름

sequenceDiagram
  participant Caller
  participant Service as Edge service
  participant Queue as Provider queue
  participant Node

  Caller->>Service: SubmitRun(model)
  Service->>Queue: provider 후보 선택
  Queue-->>Service: adapter + served target
  Service->>Node: RunRequest(adapter, target)

  participant Operator
  participant Refresh as Config refresh
  Operator->>Refresh: POST /refresh(apply)
  Refresh->>Refresh: load, validate, classify
  Refresh->>Node: NodeConfigRefreshRequest

계약

• iop.edge-config-runtime-refresh: agent-contract/inner/edge-config-runtime-refresh.md
• iop.edge-node-runtime-wire: agent-contract/inner/edge-node-runtime-wire.md
• proto 원문: proto/iop/runtime.proto

설정/데이터/이벤트

• long_context_threshold_tokens 기본 예시는 100000이고 0 이하 값은 config load에서 거부된다.
• provider enabled=false는 dispatch pool에서 제외하지만 adapter process lifecycle 변경을 의미하지 않는다.
• provider capacity, priority, max queue, queue timeout, enabled toggle, model generation policy는 live apply 대상으로 분류된다.
• Edge listener, control plane, openai/a2a listener, bootstrap artifact path, node 추가/삭제, node token/alias, adapter 설정 변경은 restart-required 대상이다.
• refresh result는 changed nodes/providers/models와 restart-required paths를 stable non-nil slice로 보고한다.

검증

• go test ./packages/go/config
• go test ./apps/edge/internal/configrefresh
• go test ./apps/edge/internal/service
• go test ./apps/edge/internal/node
• go test ./apps/node/internal/adapters ./apps/node/internal/node

한계와 주의사항

• provider health는 현재 config/provider snapshot 기반이다. 모든 runtime에 대한 active health probe가 완성된 것은 아니다.
• refresh admin API는 operator-local 표면이다. 접근 제어 없이 public interface에 노출하지 않는다.
• adapter structural 변경은 contract상 restart-required로 분류된다. Node handler가 registry swap을 지원하더라도 Edge refresh classifier가 허용한 변경만 apply해야 한다.
• no-change apply는 runtime snapshot을 교체하지만 Node push는 생략한다.
• NodeRuntimeConfig.concurrency는 legacy metadata이며 provider-pool admission의 node-wide capacity로 쓰지 않는다.
• credential, private endpoint, bearer token 원문은 tracked config/docs/spec에 남기지 않는다.

변경 기록

• 2026-07-07: 현재 코드, 계약, config 예시 기준으로 bootstrap spec 작성.
• 2026-07-07: 기능 목록 중심으로 축소하고 주요 흐름을 Mermaid sequence diagram으로 정리.