# Edge Config And Runtime Refresh Contract

## 계약 메타

- id: `iop.edge-config-runtime-refresh`
- boundary: `inner`
- status: active
- 원본 경로:
  - `packages/go/config/edge_types.go`
  - `packages/go/config/provider_types.go`
  - `packages/go/config/execution_preset_types.go`
  - `packages/go/config/load.go`
  - `packages/go/config/validate.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/edge/internal/service/model_queue_release.go`
  - `apps/edge/internal/service/model_queue_snapshot.go`
  - `apps/edge/internal/openai/stream_gate_runtime.go`
  - `apps/edge/internal/openai/stream_gate_stall_recovery_test.go`
  - `apps/node/internal/adapters/config_set.go`
- human docs: `apps/edge/README.md`

## 읽는 조건

- `configs/edge.yaml`, `packages/go/config`, credential plane, TLS/key material references, provider pool, `openai.model_routes`, `models[]`, `models[].execution_preset`, `execution_presets[]`, `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 설정으로 주입한다.

## 핵심 규칙

- `credential_plane.enabled` is the single managed-versus-legacy credential mode switch. Managed Edge startup requires Edge-Node server TLS, a TLS-enabled Control Plane connector, and OpenAI ingress TLS when that listener is enabled. Managed mode rejects `openai.bearer_token`, `openai.principal_tokens[]`, `openai.provider_auth`, provider credential headers/environment/arguments, and endpoint user-info so no legacy credential source competes with a lease.
- Managed Node startup requires Edge transport TLS, a recipient key id/private key, a lease issuer key id/public key, and a bounded replay cache. Control Plane managed startup separately requires credential HTTPS, CP-Edge mTLS, durable storage, an external at-rest keyring, and an external lease issuer private key.
- TLS certificate/key/CA paths, credential keyring paths, issuer signing keys, and Node recipient keys are file references to operator-mounted material. Raw keys, principal tokens, and provider credentials never belong in tracked YAML. Role/name workload identities and HTTP server names must match their configured peer expectations.
- Managed provider credentials are selected only through an authenticated projected route. The effective route binds one principal, slot, profile, upstream model, resource selector, credential revision, route revision, and projection generation; caller metadata and legacy provider-auth headers cannot replace any binding field.
- `openai.principal_tokens[]`는 raw token을 저장하지 않고 hash/reference로 principal 매핑을 관리한다. 각 entry는 `token_ref` (non-empty, unique), `token_hash_sha256` (64-char hex, duplicate hash rejection), `principal_ref` (non-empty), optional `principal_alias` 필드를 갖는다. 여러 entry가 같은 `principal_ref`와 `principal_alias`를 공유할 수 있으며, 이때 `token_ref`가 앱/통합/용도별 사용량 분해 기준이 된다. tracked config에는 raw token을 저장하지 않고 hash/reference만 둔다.
- `protocol_profiles` is the top-level map of custom profile overlays, keyed by stable profile id. Each `ProtocolProfileConf` can declare `base`, `driver`, `base_url`, an operation-path map, `auth`, `capabilities`, `model_mapping`, and `extensions`. A custom overlay extends one built-in or custom base; cycles, unknown bases, and invalid driver/operation/capability combinations are rejected during config normalization.
- `nodes[].providers[].profile` selects a built-in or custom catalog entry. If the selector is empty, legacy provider-type normalization can select a compatibility profile; this is distinct from `base` inheritance. Normalization resolves the selection into the runtime-only `ProviderDefinition.RuntimeProfile` snapshot, which is not serialized back into YAML. The resolved snapshot is copied into the nested OpenAI-compatible adapter config, not into a per-request tunnel message.
- `ConcreteProtocolProfile.MapModel(model)`은 provider의 model alias 정규화를 수행한다. provider가 model mapping을 정의하면 IOP external `model` key를 provider served target으로 변환한다. 매핑이 없으면 original model을 그대로 사용한다.
- `ConcreteProtocolProfile.HasCapability(cap)`는 provider capability admission에 사용된다. closed vocabulary (`models`, `chat`, `messages`, `responses`, `streaming`, `tool_calling`, `count_tokens`)만 허용한다.
- `ConcreteProtocolProfile.ResolveOperationURL(op)`는 완성된 resolved upstream URL을 반환한다. absolute operation URL은 그대로 보존하며 relative operation path는 normalized base URL에 1회 join된다. 표기된 `/v1/...` 값은 return value가 아니라 operation-path input이다 (`models` → `GET /v1/models` 또는 `GET /anthropic/v1/models`, `chat_completions` → `POST /v1/chat/completions`, `messages` → `POST /v1/messages`, `count_tokens` → `POST /v1/messages/count_tokens`, `responses` → `POST /v1/responses`).
- `validOperationsByDriver`는 driver별 허용 operation의 closed set이다. `openai_chat`은 `models`, `chat_completions`, `responses`, `count_tokens`를 허용한다. `anthropic_messages`는 `models`, `messages`, `count_tokens`를 허용한다. `openai_responses`는 `models`, `responses`, `count_tokens`를 허용한다.
- `openai.provider_auth` is a legacy-mode-only request-time raw provider token forwarding rule. `enabled=false` is the default; when enabled in legacy mode, omitted fields resolve to `from_header=X-IOP-Provider-Authorization`, `target_header=Authorization`, `scheme=Bearer`, and `required=true`. Managed mode rejects this configuration and rejects a caller-supplied legacy provider credential header.
- `openai.stream_evidence_gate` configures request-local Recovery Coordinator limits, the ingress snapshot bound, and optional semantic policy. Every supported Chat Completions, normalized Responses, provider tunnel, provider-pool, and tool-validation response already uses the `packages/go/streamgate` request runtime as its sole liveness owner. `enabled` defaults to false and controls only configured semantic filter registration/capability admission; false preserves endpoint-native compatibility inside the same runtime and does not restore a legacy response or retry owner. `max_request_fault_recovery`는 요청당 전체 fault recovery 상한(`0..3`, omitted 기본값 3, explicit 0은 모든 fault recovery 비활성화)이다. `max_strategy_fault_recovery`는 fault strategy(exact_replay/continuation_repair/schema_repair)별 상한(`0..max_request_fault_recovery`, omitted 기본값은 effective request total 상속, explicit 0은 해당 strategy 비활성화)이며 request-start 시점에 immutable runtime option snapshot으로 각 fault strategy에 동일하게 적용된다. `max_ingress_snapshot_bytes`는 ingress snapshot 바이트 상한(`1..16777216` [16 MiB], omitted/0 기본값 16 MiB)이다. `environment`는 request-start selector snapshot이며 `dev|dev-corp`만 허용하고 omitted 기본값은 `dev`다. `filters[]`는 unique `filter` (`repeat_guard|schema_gate|provider_error`) policy이다. `enabled` omitted=true, `enforcement` omitted=`blocking`, `capability` omitted=`output.<filter>`, `hold_evidence_runes` omitted=500, `timeout_ms` omitted=5000으로 정규화하며 selector는 `environment|model_group|model|provider`로만 filter enablement/enforcement를 보정한다. base-disabled filter도 registry snapshot에 남아 더 구체적인 selector가 활성화할 수 있고, 실제 target에서 활성화된 `blocking` filter만 provider capability admission에 참여한다. `observe_only`는 evidence를 만들지만 admission을 막지 않는다. `repeat_guard` uses the configured rune bound for active request-local history/current-stream inspection and stores only bounded fingerprints, counts, and offsets in its semantic snapshot and observations. `schema_gate` and `provider_error` remain lifecycle foundations until their matcher Tasks; an unmatched provider error never creates exact replay. Config accepts no caller/agent selector.
- `openai.stream_evidence_gate` 설정은 request-start 시점에 snapshot으로 고정되며 in-flight request의 실행 중 refresh 영향에서 격리된다 (generation isolation). 새 generation의 설정은 이후 시작되는 새 request에만 적용된다.
- The internal `response_stalled` recovery registration is always present for a supported OpenAI runtime request. It is not a member of `filters[]`, has no configurable capability, and does not participate in provider capability admission. It consumes only an Edge-confirmed typed handoff; configurable `provider_error` keeps its generic foundation behavior.
- The request-start `models[].context_window_tokens` snapshot is the resume builder's target context bound. Each Chat/Responses runtime shares one request-local content/reasoning recorder across its initial and recovery event sources. A continuation rebuild uses only that recorder and the fixed directive; unknown or exceeded context rejects the rebuild before re-admission. An omitted caller temperature selects `0.2`, `0.4`, then `0.6` by continuation strategy attempt, while an explicit value is preserved. Recorder state and its raw values remain request-local, are consumed once per attempt, and are never added to config refresh state or observations. Repeat history and counters are pinned to the same request-start config generation and are not refreshable TTL/session state.
- `openai` deep diff는 restart-required로 분류한다. `openai.principal_tokens[]`, `openai.stream_evidence_gate`, top-level 및 `openai.model_routes[].provider_id` 변경은 restart-required classifier에 포함된다.
- Any `credential_plane` mode/TTL/cache change, TLS identity change, Control Plane attachment change, or key path change is restart-required. A refresh cannot switch between managed and legacy credential ownership or rotate process-held signing/recipient material in place.
- Changes to either `protocol_profiles` or `nodes[].providers[].profile` are restart-required. Immutable runtime snapshots describe the loaded configuration only; they do not make profile catalog or selector changes live-refreshable.
- `openai.model_routes[]`는 외부 OpenAI-compatible `model` id를 내부 `adapter + target` route로 매핑하는 compatibility catalog다. direct dispatch의 provider attribution identity는 route-level `provider_id`를 우선하고, 없으면 top-level `openai.provider_id`를 사용한다. `openai.enabled=true`이면 단일 target fallback도 dispatch 가능하므로 top-level fallback은 nonblank여야 하며, 이 검증은 기존 route/provider/model 진단 뒤에 수행한다. legacy direct provider id는 명시적 attribution identity이며 `nodes[].providers[].id` 참조를 요구하지 않고 adapter 문자열에서 추론하지 않는다.
- `long_context_threshold_tokens`는 Edge root의 입력 토큰 추정 기준 long-context 분류 threshold다. 기본값은 `100000`이며 0 이하 값은 config load에서 거부한다.
- `provider_pool.max_queue`와 `provider_pool.queue_timeout_ms`는 모든 model group과 provider candidate에 공통인 Edge provider-pool queue policy의 canonical owner다. `max_queue`는 Edge provider-pool 전체 pending 상한이며 0/생략은 기본값 `16`으로 정규화된다. `queue_timeout_ms`는 각 pending request의 최대 대기 시간이며 명시적 `0`은 timeout 없음, 생략은 기본값 `30000`이다.
- canonical `provider_pool` key가 없을 때만 legacy `nodes[].providers[].max_queue`/`queue_timeout_ms`를 compatibility 입력으로 읽는다. 참여 provider의 유효 pair가 모두 같으면 root policy로 승격하고, 하나라도 다르면 first-candidate 값을 택하지 않고 load를 거부한다. canonical root key가 있으면 legacy provider queue 값은 effective policy와 refresh diff에 영향을 주지 않는다.
- `models[]`는 provider pool 방향의 canonical routing key이며 `nodes[].providers[].id`를 참조한다. `usage_attribution`은 `provider|model_group`만 허용하고 생략 시 `provider`로 해석한다. `model_group`은 운영자가 model-group 귀속을 명시적으로 승인하는 opt-in이다. `context_window_tokens`는 해당 model group의 provider 공통 단일 요청 최대 context 계약이다. `default_max_tokens`, `min_max_tokens`, `default_thinking_token_budget`은 OpenAI-compatible 요청을 내부 실행으로 넘기기 전에 적용하는 모델 단위 generation policy다.
- 하나의 `models[]` entry는 OpenAI-compatible provider와 normalized-only provider를 함께 참조할 수 있다. 선택된 provider가 OpenAI-compatible 호출 방식을 지원하면 passthrough 실행 경로를 사용하고, `ollama`/`cli` 같은 normalized-only provider면 normalized 실행 경로를 사용한다. Ollama 후보는 model group에서 제거하지 않고 `capacity`와 `priority`로 낮은 동시성/선호도를 표현한다.
- `models[].providers`와 `models[].execution_preset`는 상호 배타(one-of)다. 한 `models[]` entry는 정확히 하나만 설정해야 하며, 둘 다 설정하거나 둘 다 비우면 load에서 거부한다. `execution_preset`가 설정된 entry는 provider pool을 갖지 않는 virtual(preset-only) model이며 named execution preset shape에 실행을 위임한다. provider-only budget/token-counter validation은 virtual entry에 적용하지 않는다.
- `models[].execution_preset` 값은 앞뒤 공백을 제거해 정규화한다. 공백만 있는 값은 unset으로 처리해 provider-only one-of 규칙을 적용하고, 정규화된 non-empty id는 `execution_presets[]` catalog의 entry로 resolve되어야 한다. dangling reference는 fail-closed로 거부한다. resolve에 성공한 non-empty id는 canonical(trimmed) 형태로 저장되어 downstream lookup이 admission 시점 값과 정확히 일치한다.
- `execution_presets[]`는 top-level frozen execution shape catalog이며 `models[].execution_preset`가 참조하는 대상이다. 각 preset의 `selector.model`과 route stage `model`은 기존 `models[].id` catalog를 참조해야 한다. `execution_presets[]` catalog 변경과 `models[].execution_preset` mapping 변경은 모두 live-apply로 분류되며 refresh 이후 새로 시작되는 logical request에만 적용되고 in-flight request에는 영향을 주지 않는다.
- `execution_presets[].single_request`는 operator-owned fixed single-request policy다. 설정 시 preset은 `allowed_modes=["light"]`, `stages=[plan, work, review]`의 승인된 plan→work→review 경로를 고수한다. 절대 상한은 `wall_clock_ms ≤ 1800000`, `timeout_ms ≤ 600000`, `max_tool_iterations ≤ 64`, `max_output_bytes ≤ 16777216`이며 `timeout_ms`는 `wall_clock_ms`를 초과할 수 없다. selector와 plan/review stage는 `reasoning_effort=high`를 강제하고 work stage는 `reasoning_effort`를 선언할 수 없다. `workspace_ref`는 비어있을 수 없으며 raw path, credential, Node id, endpoint를 포함하지 않는다. single_request preset은 `workspace_tools`를 선언할 수 없다. catalog 변경과 mapping 변경은 live-apply로 분류되며 refresh 이후 새로 시작되는 logical request에만 적용된다. admitted single-request binding은 refresh 이후에도 frozen public model, stage binding, workspace reference, limits를 유지한다.
- `nodes[].providers[]`는 Node 아래 resource/provider catalog다. `category`는 `api`, `cli`, `local_inference` resource kind를 나타낸다.
- `nodes[].providers[].type`의 `seulgivibe_claude`와 `seulgivibe_openai`는 runtime type을 `openai_compat`로 정규화한다. Edge가 Node adapter payload를 만들 때 명시 provider label이 없으면 원래 Seulgivibe type alias를 `OpenAICompatAdapterConfig.provider`로 보존한다.
- `nodes[].providers[].response_stall_timeout_ms`는 provider-originated response-stall timeout을 밀리초 단위로 선언한다. 양수 값은 그대로 사용되고, 0 또는 생략은 문서화된 기본값 `300000`을 적용한다. 음수 값과 safe duration bound를 초과하는 양수 값은 `NodeProviderConf.Validate()`에서 거부한다. effective 값은 `NodeProviderConf.EffectiveResponseStallTimeoutMS()`에서 계산한다. 이 필드는 config refresh에서 `restart_required`로 분류되며, effective-zero 등가성(생략 vs 명시적 0)은 변경으로 보고되지 않는다. request hard timeout, queue timeout, heartbeat/disconnect, CLI `response_idle_timeout_ms`는 기존 소유권을 유지한다.
- `nodes[].providers[].id`는 전체 Edge config 안에서 중복되면 안 된다.
- `nodes[].providers[].adapter`는 같은 Node 안의 enabled adapter instance key를 참조해야 한다. Exact instance key를 우선하고, legacy type-name route는 같은 type의 enabled instance가 정확히 하나일 때만 허용한다.
- `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)은 수행된다.
- `nodes[].providers[].capacity`와 `long_context_capacity`는 `node_id + provider_id` resource가 소유한다. 같은 provider를 참조하는 여러 `models[].id`는 일반·long slot을 합산 공유한다. `total_context_tokens`는 runtime counter가 아니라 `context_window_tokens * long_context_capacity` 이상이어야 하는 정적 load/refresh validation 값이다.
- `nodes[].providers[].priority`: provider-pool dispatch tie-breaker다. 기본값은 `0`이고 음수는 validation error다. dispatch는 `in_flight < capacity` 후보 중 가장 낮은 `in_flight`를 먼저 선택하며, `in_flight`가 같은 후보에서만 낮은 숫자의 `priority`를 우선한다. `in_flight`와 `priority`가 모두 같으면 기존 순환을 유지한다. priority 변경은 live-apply(restart 불필요)로 분류된다.
- Configured provider health remains an immutable input snapshot during request execution. Confirmed current bound runtime-unavailable evidence is stored separately under `(node_id, connection_generation, provider_id)`, gates effective admission, and projects the runtime ProviderSnapshot unavailable without changing `NodeProviderConf.Health`, refresh diffs, or Node config payloads. A later exact higher-sequence available CAPABILITIES probe or a newer connection generation clears effective exclusion under the runtime contract, not through config refresh.
- After the queue makes that authoritative overlay decision, Edge emits bounded operational evidence only: `iop_edge_provider_health_evidence_total{source,evidence_health,decision}` and `iop_edge_provider_health_transitions_total{from_health,to_health}`, plus `edge_provider_health_observation`. Sources, health values, and decisions use closed vocabularies; provider/node/run/session/adapter/target identity, payloads, and credentials are excluded. The observer is post-lock and cannot validate or mutate config/overlay state.
- `nodes[].workspaces[]` is the operator-owned bounded capability catalog for each node. Each entry is keyed by a globally unique, trimmed `ref` and declares `platform` in the closed `darwin|linux` implementation set, `root` (absolute clean path other than `/`), closed-set `operations` (`read`, `list`, `write`, `delete`, `command`), approved `commands` (id + fixed executable + fixed args, present iff `command` is in operations), `environment_allowlist` (unique portable env var names), and bounded `max_read_bytes`, `max_write_bytes`, `max_output_bytes`, `max_command_timeout_ms` (each enabled `read`, `write`, `list`, or `command` operation requires its effective positive bound; absolute maxima are 1 GiB / 1 hour). Refs are globally unique across all nodes. An empty workspaces slice is backward-compatible on any host. A non-empty Node catalog requires a supported host and every entry platform must equal that host before any root is opened; Windows and unknown hosts fail closed. The catalog is compiled into `NodeRecord.Workspaces` at load time, delivered in the Node-private config payload, and retained immutably by the workspace runtime; runtime mutation is restart-required. Raw root paths and command details never enter execution presets, caller-visible responses, provider requests, or public metadata. `workspace_ref` in `execution_presets[].single_request` references one entry by ref; operating system is runtime ownership evidence, not a caller selector.
- Config refresh classifies any `nodes[].workspaces` change (root, capability, command template, environment allowlist, or limits) as `restart_required`. Active requests must never observe a root/capability mutation.
- legacy single-instance adapter 설정은 load 시 named instance slice로 normalize된다.
- `NodeConfigPayload`는 Edge가 Node에 내려주는 실행 adapter/runtime payload다.
- `provider_id`와 effective `usage_attribution`은 OpenAI route에서 Edge service dispatch result까지 보존되는 Edge-local attribution binding이다. `response_stall_timeout_ms`는 이 attribution과 별개로 선택된 provider의 effective timeout을 `RunRequest`와 `ProviderTunnelRequest` wire field에 보존한다.
- refresh 결과는 `applied`, `restart_required`, `rejected`를 구분하고, changed node/provider/model/report slice는 안정적으로 non-nil이어야 한다.

## refresh 분류 기준

- live apply 가능: Edge root `long_context_threshold_tokens`, `provider_pool.max_queue`, `provider_pool.queue_timeout_ms`, provider capacity, provider long-context capacity, provider total-context validation budget, provider priority, provider `enabled` toggle, `models[]` display/context window/provider/generation/`usage_attribution` policy mapping, `models[].execution_preset` mapping, `execution_presets[]` preset catalog, legacy node runtime concurrency metadata. 기존 lease는 유지하며 새 admission과 모든 pending item은 새 policy/candidate 상태로 재평가한다. preset catalog/mapping 변경은 refresh 이후 새로 시작되는 logical request에만 반영된다.
- restart required: credential-plane/TLS/key references, 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`) 변경, `nodes[].workspaces` 변경 (root, capability, command template, environment allowlist, limits).
- 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에 기록하지 않는다.
- provider auth raw token 원문을 config, docs, task artifact, metric label에 기록하지 않는다.
- Do not enable managed credential mode with a plaintext hop, a legacy auth source, static provider credential material, or a tracked private-key/keyring file.
- Node bootstrap 기본 경로에서 사용자가 직접 node config를 작성하거나 adapter/provider 값을 명령줄로 넣어야 하는 계약을 만들지 않는다.

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

- `packages/go/config/edge_openai_config_test.go`
- `packages/go/config/edge_runtime_config_test.go`
- `packages/go/config/node_config_test.go`
- `packages/go/config/provider_catalog_config_test.go`
- `packages/go/config/provider_catalog_validation_config_test.go`
- `packages/go/config/model_execution_preset_config_test.go`
- `apps/edge/internal/configrefresh/execution_preset_classify_test.go`
- `apps/edge/internal/configrefresh/node_runtime_classify_test.go`
- `apps/edge/internal/configrefresh/path_refresh_test.go`
- `apps/edge/internal/configrefresh/provider_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`
