feat: operational observability provider management milestones and phase updates

2026-07-04 16:58:09 +09:00 · 2026-07-04 16:58:09 +09:00 · 7261b919d5
commit 7261b919d5
parent b55d1a2e85
5 changed files with 339 additions and 6 deletions
--- a/agent-roadmap/phase/operational-observability-provider-management/PHASE.md
+++ b/agent-roadmap/phase/operational-observability-provider-management/PHASE.md
@ -28,6 +28,10 @@ provider 확장 Phase에서 검증한 Ollama, vLLM, SGLang, Lemonade 같은 추
  - 경로: `agent-roadmap/archive/phase/operational-observability-provider-management/milestones/node-provider-first-config-surface.md`
  - 요약: Node 설정 표면을 `providers[]` resource list 중심으로 재정렬하고, adapter 설정은 내부 실행 IR 또는 legacy compat로 낮춰 운영자가 한 Node의 CLI/provider 자원을 한 곳에서 이해하고 관리하게 만들었다.

+- [계획] Model Group Long-Context Admission
+  - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/model-group-long-context-admission.md`
+  - 요약: model group의 단일 context window 계약을 유지하면서 입력 기준 long-context 요청을 별도 slot으로 admission하고, long 요청이 찬 provider와 queue 앞 long 요청이 normal 요청을 불필요하게 막지 않도록 라우팅 정책을 정리한다.
+
 - [스케치] 사용량, 토큰, 로그 운영 추적 MVP
  - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/usage-token-log-ops-mvp.md`
  - 요약: 사용자 관리, token 관리, API/CLI/local inference 사용량 집계, 요청별 device/provider/time/token ledger, 로그 관리의 1차 운영 경계를 스케치한다.
@ -38,7 +42,11 @@ provider 확장 Phase에서 검증한 Ollama, vLLM, SGLang, Lemonade 같은 추

 - [스케치] Provider-Device-Model Qualification 리포트와 Lifecycle 관리
  - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/provider-device-model-qualification-report.md`
-  - 요약: provider catalog와 device 상태 기준선 뒤에, provider/device/model 조합별 compatibility, performance, quality, lifecycle capability 테스트와 운영 리포트 저장/조회/비교 경계를 깊게 스케치한다.
+  - 요약: provider catalog와 device 상태 기준선 뒤에, 여러 모델을 각 device/provider에서 측정하고 공식 공개 benchmark와 함께 보여주는 qualification 리포트, compatibility/performance/quality/lifecycle 비교 경계를 깊게 스케치한다.
+
+- [스케치] Provider Runtime 설정과 모델 획득 오케스트레이션
+  - 경로: `agent-roadmap/phase/operational-observability-provider-management/milestones/provider-runtime-model-acquisition-orchestration.md`
+  - 요약: IOP가 vLLM, vLLM-MLX, Lemonade 같은 provider runtime의 launch/profile 설정과 모델 후보 선정, 다운로드, 캐시, 검증, 적용 경계를 어디까지 소유할지 장기 후속 축으로 스케치한다.

 ## Phase 경계

--- a/agent-roadmap/phase/operational-observability-provider-management/milestones/model-group-long-context-admission.md
+++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/model-group-long-context-admission.md
@ -0,0 +1,91 @@
+# Milestone: Model Group Long-Context Admission
+
+## 위치
+
+- Roadmap: `agent-roadmap/ROADMAP.md`
+- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
+
+## 목표
+
+Model group의 단일 요청 context window 계약을 유지하면서, 입력 토큰 기준 long-context 요청을 별도 admission slot으로 제어한다.
+일반 요청은 기존 provider capacity와 priority 기반으로 적극 배정하되, long-context 요청은 provider별 long slot과 model group 전체 long slot 여유가 있을 때만 배정해 256k급 요청이 서로 몰려 전체 사용성을 떨어뜨리지 않게 한다.
+long slot이 찬 provider도 일반 capacity가 남아 있으면 normal 요청 후보로 유지한다.
+
+## 상태
+
+[계획]
+
+## 승격 조건
+
+- 없음
+
+## 구현 잠금
+
+- 상태: 해제
+- SDD: 필요
+- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/model-group-long-context-admission/SDD.md`
+- SDD 사유: model group routing, queue admission, provider runtime config, dev provider pool smoke 기준을 함께 바꾸는 설계 Milestone이다.
+- 잠금 해제 조건: 없음
+- 결정 필요: 없음
+
+## 범위
+
+- Edge root 설정의 `long_context_threshold_tokens` 도입. 초기 기준은 입력 토큰 추정치 `100000` 이상이다.
+- model group의 `context_window_tokens`를 단일 요청 최대 context 계약으로 둔다. `qwen3.6:35b` 기준은 `262144`이며 같은 model group provider가 이를 낮춰 다르게 해석하지 않는다.
+- provider별 `total_context_tokens` 또는 이에 대응하는 runtime KV/context budget 기준을 명시하고, `long_context_capacity`와 비례 검증한다. 기본 검증식은 `total_context_tokens >= context_window_tokens * long_context_capacity`이다.
+- provider별 `long_context_capacity` 도입. long slot은 provider가 확보한 전체 KV/context budget을 `context_window_tokens * long_context_capacity`로 해석하며, 일반 동시성 capacity와 별도로 관리한다.
+- long-context 판별은 요청 입력 기준으로만 수행한다. output 길이와 hidden thinking은 사전 분류 기준에 넣지 않고, provider fit과 timeout/usage 관측은 별도 운영 지표로 둔다.
+- long-context 요청은 일반 `in_flight` capacity도 점유하고, 별도 `long_in_flight`도 점유한다.
+- 할당 직전 queue item의 long flag를 보고 long slot이 꽉 찬 provider는 후보에서 제외한다. model group 전체 long slot이 모두 찼으면 long 요청은 대기한다.
+- long slot full은 long 요청에 대한 후보 제외 조건이며, 해당 provider의 일반 capacity가 남아 있으면 normal 요청 후보에서는 제외하지 않는다.
+- queue 앞 long 요청이 long slot을 기다리는 동안, 뒤의 normal 요청이 빈 일반 capacity로 처리 가능하면 normal 요청을 먼저 dispatch한다.
+- dev 기준 OneXPlayer는 `ctx_size=524288`, `long_context_capacity=2`, `-np 3`을 유지한다. `-np`는 단순 최대 동시 요청 수로 취급하며, `ctx_size`를 `262144 * 3 = 786432`로 키우는 방향은 제외한다.
+- GX10, OneXPlayer, mac-mlx-vllm provider pool에서 long-context admission 상태와 queue 회복을 smoke로 검증한다.
+
+## 기능
+
+### Epic: [long-admission] Long-Context Admission Policy
+
+long-context 요청을 model group과 provider의 별도 slot 기준으로 admission하는 capability를 묶는다.
+
+- [ ] [threshold-config] Edge root 설정에 `long_context_threshold_tokens`를 추가하고 dev 기준 `100000`으로 설정한다. 검증: 설정 로딩과 config check에서 threshold가 반영된다.
+- [ ] [model-window] model group에 `context_window_tokens=262144` 계약을 명시하고 같은 model group provider가 provider별 단일 요청 최대 context를 낮춰 해석하지 않도록 한다. 검증: `qwen3.6:35b` catalog/config에서 context window가 단일 기준으로 조회된다.
+- [ ] [provider-long-capacity] provider별 `total_context_tokens` 또는 runtime KV/context budget 기준, `long_context_capacity`, `long_in_flight` 상태를 추가하고, long 요청이 일반 capacity와 long capacity를 함께 점유하도록 한다. 검증: `total_context_tokens >= context_window_tokens * long_context_capacity` 검증과 long 요청 dispatch 중 `long_in_flight` 증가가 확인된다.
+- [ ] [input-estimator] OpenAI-compatible chat/responses 요청의 system/developer/user messages, tool schema, metadata payload를 입력 기준으로 토큰 근사 추정해 long flag를 붙인다. 검증: 100k 이상 입력은 long, 작은 설명형 요청은 normal로 분류된다.
+- [ ] [queue-skip] queue head의 long 요청이 long slot 부족으로 대기 중이어도 뒤의 normal 요청이 빈 일반 capacity로 dispatch될 수 있게 한다. 검증: long queue 대기 중 normal 요청이 head-of-line blocking 없이 완료된다.
+- [ ] [provider-exclusion] long 요청 배정 시 이미 long slot이 찬 provider를 long 후보에서 제외하고, model group 전체 long slot이 모두 차면 long 요청을 대기시킨다. 검증: long 요청이 같은 provider에 과밀 배정되지 않고, normal 요청은 남은 일반 capacity로 계속 dispatch되며, long slot 회복 뒤 long 요청이 dispatch된다.
+- [ ] [dev-runtime-policy] dev provider pool에서 GX10, OneXPlayer, mac-mlx-vllm의 `context_window_tokens`, `long_context_capacity`, 실제 runtime context/KV 설정을 인벤토리와 config에 맞춘다. 검증: OneXPlayer는 `ctx_size=524288`, `-np 3`, long slot 2 기준을 유지하며 `786432`로 변경하지 않는다.
+- [ ] [status-logs] status/log에 `estimated_input_tokens`, `context_class`, `long_context_capacity`, `long_in_flight`, long queue reason을 남긴다. 검증: Control Plane status 또는 Edge log로 long admission 판단을 재구성할 수 있다.
+- [ ] [capacity-smoke] dev 환경에서 normal 10-way, mixed long/normal, all-long-slot-full queue 시나리오를 수행하고 완료 후 `in_flight=0`, `queued=0`, `long_in_flight=0` 회복 근거를 남긴다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 계획 Milestone이며 기능 Task가 아직 충족되지 않았다.
+- 검토 항목:
+  - [ ] long-context 분류가 입력 기준으로만 수행된다.
+  - [ ] 같은 model group provider는 `context_window_tokens=262144` 단일 요청 계약을 공유한다.
+  - [ ] long slot이 찬 provider는 long 요청 후보에서 제외되지만 일반 capacity가 남으면 normal 요청 후보로 유지된다.
+  - [ ] OneXPlayer는 `ctx_size=524288`, `-np 3`, long slot 2 기준을 유지하며 `786432`로 키우지 않는다.
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- output 길이나 hidden thinking budget을 이용한 사전 long-context 분류
+- provider별 단일 요청 최대 context를 model group 계약보다 낮게 허용하는 혼합 model group
+- OneXPlayer `ctx_size`를 `786432`로 올리는 설정 변경
+- billing/chargeback, 장기 usage ledger 저장, 품질 기반 route recommendation
+- tokenizer별 완전 정확한 토큰 계산기 구현. 초기 분류는 보수적 근사 추정으로 시작한다.
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/edge/internal/service`, `apps/edge/internal/openai`, `apps/node/internal/adapters/openai_compat`, `packages/go/config`, `configs/edge.yaml`, `agent-test/dev/inventory.yaml`, `agent-test/dev/edge-smoke.md`, `agent-test/dev/node-smoke.md`
+- 표준선(선택): model group의 `context_window_tokens`가 단일 요청 최대 context 계약을 소유하고, provider는 이를 낮춰 해석하지 않는다.
+- 표준선(선택): `long_context_capacity`는 provider가 가진 전체 KV/context budget을 model group context window 몇 개분으로 운영할지 나타내며, 일반 `capacity`와 분리한다.
+- 표준선(선택): provider runtime의 ctx/KV budget은 `total_context_tokens >= context_window_tokens * long_context_capacity` 기준으로 검증한다.
+- 표준선(선택): OneXPlayer에서 `-np 3`은 단순 최대 동시 요청 수로 다루고, long slot 산정은 `ctx_size=524288 = 262144 * 2` 기준으로 고정한다.
+- 선행 작업: Model Alias Provider Pool과 Provider Catalog, Node Resource Model Unification, Node Provider-First Config Surface
+- 후속 작업: 요청 실행 로그와 Usage Ledger 기반, Provider-Device-Model Qualification 리포트와 Lifecycle 관리
+- 확인 필요: 없음
--- a/agent-roadmap/phase/operational-observability-provider-management/milestones/provider-device-model-qualification-report.md
+++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/provider-device-model-qualification-report.md
@ -8,7 +8,7 @@
 ## 목표

 Provider Catalog와 로컬 디바이스 상태 기준선 뒤에, Ollama, vLLM, SGLang, Lemonade 같은 provider의 device/model 조합을 테스트하고 결과를 운영 리포트로 축적하는 제품 경계를 스케치한다.
-provider별 모델 lifecycle capability 차이를 IOP가 어떻게 흡수하고, 어떤 결과를 production route 후보 판단에 사용할지 정리한다.
+provider별 모델 lifecycle capability 차이를 IOP가 어떻게 흡수하고, 여러 모델 후보를 각 디바이스/provider에서 측정한 결과와 공식 공개 benchmark를 함께 보여 production route 후보 판단에 사용할지 정리한다.

 ## 상태

@ -19,6 +19,8 @@ provider별 모델 lifecycle capability 차이를 IOP가 어떻게 흡수하고,
 - [ ] provider/device/model qualification report의 최소 스키마와 저장 책임을 결정한다.
 - [ ] Ollama/Lemonade의 model API 관리와 vLLM/SGLang의 process/container lifecycle 관리 차이를 어떻게 추상화할지 결정한다.
 - [ ] compatibility, performance, quality, resource, failure report 중 MVP에 포함할 항목을 결정한다.
+- [ ] 여러 모델을 다운로드/적용해 벤치마킹할 대상 model set, provider/device matrix, 실행 비용/시간 상한을 결정한다.
+- [ ] 공식 공개 benchmark를 어떤 source에서 수집/인용하고 최신성, 출처, 조건 차이를 어떻게 표시할지 결정한다.
 - [ ] Control Plane, Edge-local CLI, Client 중 report 조회와 lifecycle 제어 표면을 어디에 둘지 결정한다.
 - [ ] 현재 provider 확장 Phase의 vLLM/SGLang serving path 검증 결과를 seed evidence로 어떻게 연결할지 결정한다.

@ -36,10 +38,15 @@ provider별 모델 lifecycle capability 차이를 IOP가 어떻게 흡수하고,
  - [ ] IOP가 provider별 모델 설치/삭제/load/unload 또는 container/process start/stop을 어느 수준까지 직접 제어할지 결정한다.
  - [ ] qualification report를 route recommendation에 바로 사용할지, 초기에는 관찰/리포트로만 둘지 결정한다.
  - [ ] 성능/품질 테스트가 자동 실행이어야 하는지, 사용자 승인 기반 수동 실행으로 시작할지 결정한다.
+  - [ ] benchmark 대상 모델 다운로드와 provider 설정 변경을 이 Milestone에서 직접 수행할지, `Provider Runtime 설정과 모델 획득 오케스트레이션` Milestone의 선행 결과로 받을지 결정한다.
+  - [ ] 공식 공개 benchmark를 웹에서 직접 수집할 때 허용 source, citation 방식, 갱신 주기, 측정 조건 차이 표시 기준을 결정한다.

 ## 범위

 - provider/device/model 조합별 compatibility, performance, quality, resource, failure report의 최소 필드
+- 여러 모델 후보를 각 device/provider에서 실행해 TTFT, tokens/sec, latency, concurrency, queue wait, resource usage를 측정하는 benchmark matrix
+- benchmark 대상 모델의 download/apply/verify 흐름과 provider runtime 설정은 `Provider Runtime 설정과 모델 획득 오케스트레이션` Milestone과 연결한다.
+- 공식 공개 benchmark 수치, 출처 URL, 측정 조건, 수집 시각, 로컬 측정값과의 비교 표시 기준
 - Ollama, Lemonade, vLLM, SGLang의 model lifecycle capability 차이를 표현하는 공통 추상화
 - vLLM/SGLang처럼 single-model serving process/container 중심인 provider와 Ollama/Lemonade처럼 model API가 있는 provider의 운영 차이
 - provider 확장 Phase에서 나온 serving smoke/field evidence를 qualification seed report로 연결하는 기준
@ -51,9 +58,11 @@ provider별 모델 lifecycle capability 차이를 IOP가 어떻게 흡수하고,

 provider/device/model 조합을 테스트하고 운영 판단에 쓸 수 있는 리포트로 남기는 capability를 묶는다.

- [ ] [report-schema] provider, device, model alias, checkpoint, served model, runtime version, launch/container args, endpoint, auth policy, test timestamp, result status를 포함한 최소 report schema가 정리되어 있다.
+- [ ] [report-schema] provider, device, model alias, checkpoint, served model, runtime version, launch/container args, endpoint, auth policy, test timestamp, result status, benchmark source/citation을 포함한 최소 report schema가 정리되어 있다.
 - [ ] [compat-suite] `/v1/models`, non-streaming chat, streaming chat, usage/finish reason, timeout/error mapping 같은 compatibility test matrix가 정리되어 있다.
- [ ] [perf-suite] TTFT, tokens/sec, latency p50/p95, concurrency, queue wait, resource usage 후보와 필수/선택 구분이 정리되어 있다.
+- [ ] [model-matrix] 여러 모델 후보를 어떤 device/provider 조합에 다운로드/적용/측정할지 benchmark matrix와 실행 비용/시간 상한이 정리되어 있다.
+- [ ] [perf-suite] TTFT, tokens/sec, latency p50/p95, concurrency, queue wait, resource usage 후보와 필수/선택 구분이 모델별/디바이스별 비교 기준으로 정리되어 있다.
+- [ ] [official-bench] 공식 공개 benchmark source, URL/citation, 수집 시각, 측정 조건 차이, 로컬 측정값과의 비교/경고 표시 기준이 정리되어 있다.
 - [ ] [quality-suite] canonical prompt set, structured output, reasoning/content handling, tool/schema readiness 같은 quality/eval 후보와 MVP 제외 범위가 정리되어 있다.
 - [ ] [lifecycle-map] Ollama/Lemonade의 model API와 vLLM/SGLang의 process/container lifecycle을 IOP lifecycle action으로 매핑하는 후보가 정리되어 있다.
 - [ ] [ops-surface] Control Plane, Client, Edge-local CLI에서 report 조회, 비교, lifecycle action을 어디까지 노출할지 후보가 정리되어 있다.
@ -73,6 +82,7 @@ provider/device/model 조합을 테스트하고 운영 판단에 쓸 수 있는

 - 현재 provider 확장 Phase의 vLLM/SGLang adapter 구현 자체
 - 개별 provider serving path의 최초 연결 검증
+- provider runtime 설정과 모델 다운로드 자동화 구현 자체. 이 범위는 `Provider Runtime 설정과 모델 획득 오케스트레이션` Milestone에서 다룬다.
 - cloud fallback 자동화와 cross-Edge/global balancing
 - billing/chargeback, 조직 IAM, 장기 audit retention
 - fully automated model marketplace
@ -82,6 +92,7 @@ provider/device/model 조합을 테스트하고 운영 판단에 쓸 수 있는
 - 관련 경로: `apps/edge`, `apps/node`, `apps/control-plane`, `apps/client`, `packages/go/config`, `proto/iop`, `agent-test/local`
 - 표준선(선택): provider serving path와 capacity/concurrency 검증은 `추론 서버 provider 확장` Phase에서 먼저 닫고, 이 Milestone은 그 결과를 운영 데이터와 lifecycle 제어 모델로 승격한다.
 - 표준선(선택): OpenAI-compatible compatibility는 공통 test matrix로 보되, provider별 native lifecycle API는 capability 기반으로 optional 처리한다.
- 선행 작업: Provider Catalog와 로컬 디바이스 상태 관리, vLLM/SGLang provider 서빙 경로 추가
+- 표준선(선택): 공식 공개 benchmark는 로컬 측정값을 대체하지 않고 참고 비교값으로만 표시하며, 출처 URL과 측정 조건 차이를 함께 보여준다.
+- 선행 작업: Provider Catalog와 로컬 디바이스 상태 관리, vLLM/SGLang provider 서빙 경로 추가, Provider Runtime 설정과 모델 획득 오케스트레이션
 - 후속 작업: route recommendation, cloud fallback, 품질 기반 routing/fallback 고도화
- 확인 필요: report schema, lifecycle 제어 범위, 자동/수동 테스트 실행 경계, 운영 표면
+- 확인 필요: report schema, lifecycle 제어 범위, 자동/수동 테스트 실행 경계, benchmark 대상 모델과 provider/device matrix, 공식 benchmark source/citation 정책, 운영 표면
--- a/agent-roadmap/phase/operational-observability-provider-management/milestones/provider-runtime-model-acquisition-orchestration.md
+++ b/agent-roadmap/phase/operational-observability-provider-management/milestones/provider-runtime-model-acquisition-orchestration.md
@ -0,0 +1,94 @@
+# Milestone: Provider Runtime 설정과 모델 획득 오케스트레이션
+
+## 위치
+
+- Roadmap: `agent-roadmap/ROADMAP.md`
+- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
+
+## 목표
+
+IOP가 provider routing 정책의 충분조건을 보장하기 위해 vLLM, vLLM-MLX, Lemonade 같은 provider runtime 설정과 모델 선정, 다운로드, 캐시, 검증, 적용 경계를 어디까지 소유할지 스케치한다.
+model group의 context/capacity 계약을 실제 provider launch option, 모델 artifact, local cache 상태와 연결해 “설정된 capacity가 실제 runtime에서도 성립한다”는 운영 보증 모델을 장기 후속 작업으로 정리한다.
+
+## 상태
+
+[스케치]
+
+## 승격 조건
+
+- [ ] IOP가 provider runtime 설정을 관찰만 할지, launch profile 생성/수정/restart까지 담당할지 단계별 책임 경계를 결정한다.
+- [ ] vLLM, vLLM-MLX, Lemonade의 runtime option을 공통 profile로 표현할 최소 필드와 provider별 extension 필드를 결정한다.
+- [ ] 모델 후보 선정, artifact source, quantization variant, download/cache 경로, checksum/revision pinning, disk quota 정책을 결정한다.
+- [ ] 모델 다운로드와 provider restart/apply가 사용자 승인 기반인지, 자동화 가능한 작업인지, 실패 시 rollback 기준은 무엇인지 결정한다.
+- [ ] runtime 설정 검증을 `config check`, dry-run, health, `/v1/models`, context/capacity smoke 중 어디까지 요구할지 결정한다.
+- [ ] long-context admission의 `context_window_tokens`, `total_context_tokens`, `long_context_capacity`와 provider runtime option을 어떻게 일관 검증할지 결정한다.
+
+## 구현 잠금
+
+- 상태: 잠금
+- SDD: 필요
+- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/provider-runtime-model-acquisition-orchestration/SDD.md`
+- SDD 사유: provider runtime launch/restart, 모델 다운로드, artifact cache, rollback, 외부 provider 쓰기와 host 자원 변경을 포함하는 장기 설계 Milestone이다.
+- 잠금 해제 조건: 아래 체크리스트
+  - [ ] SDD 잠금이 해제되어 있다.
+  - [ ] SDD 사용자 리뷰가 없거나 승인/해결되었다.
+  - [ ] provider runtime 설정 책임과 모델 다운로드/적용 승인 경계가 구현 계획을 만들 수 있을 만큼 확정되어 있다.
+- 결정 필요: 아래 체크리스트
+  - [ ] IOP가 vLLM/vLLM-MLX process/container 기동 옵션을 직접 쓰고 재시작할 권한을 가질지 결정한다.
+  - [ ] Lemonade처럼 별도 앱/API가 설정을 소유하는 provider를 IOP가 어디까지 제어할지 결정한다.
+  - [ ] 모델 선정과 다운로드를 자동 추천/자동 실행/사용자 승인 실행 중 어떤 수준으로 시작할지 결정한다.
+  - [ ] 모델 artifact cache, 삭제, downgrade, failed download cleanup의 소유자를 결정한다.
+
+## 범위
+
+- provider runtime profile: vLLM, vLLM-MLX, Lemonade의 launch/config option, env, cache dir, endpoint, auth, health, restart policy
+- model acquisition profile: model alias, upstream repo/artifact, quantization variant, revision pin, checksum, expected served model, disk/cache path
+- capacity contract enforcement: model group `context_window_tokens`, provider `capacity`, `total_context_tokens`, `long_context_capacity`와 runtime option 일관성 검증
+- lifecycle action 후보: plan, dry-run, download, verify, apply, restart, rollback, cleanup
+- status/report: runtime config verified/degraded/misconfigured, model downloaded/verified/loaded, capacity verified/unverified
+- dev provider pool에서 vLLM, vLLM-MLX, Lemonade를 대상으로 장기적으로 적용할 운영 기준
+
+## 기능
+
+### Epic: [runtime-model-ops] Provider Runtime and Model Operations
+
+provider runtime 설정과 모델 artifact 획득을 IOP 운영 계약으로 끌어올리는 장기 capability를 묶는다.
+
+- [ ] [runtime-profile] vLLM, vLLM-MLX, Lemonade의 runtime option을 공통 profile과 provider-specific extension으로 나누는 후보가 정리되어 있다.
+- [ ] [model-candidate] model group별 모델 후보 선정 기준, quantization variant, upstream artifact, served model alias, revision pinning 기준이 정리되어 있다.
+- [ ] [download-cache] 모델 다운로드, cache path, checksum/revision 검증, disk quota, 실패 cleanup, 삭제/보존 정책 후보가 정리되어 있다.
+- [ ] [apply-lifecycle] runtime 설정 변경과 모델 교체를 dry-run, apply, restart, rollback 단계로 나누는 lifecycle 후보가 정리되어 있다.
+- [ ] [contract-verify] `context_window_tokens`, `total_context_tokens`, `long_context_capacity`, runtime ctx/KV/max seq option의 일관성 검증 후보가 정리되어 있다.
+- [ ] [provider-boundary] vLLM/vLLM-MLX처럼 IOP가 launch profile을 소유하기 쉬운 provider와 Lemonade처럼 외부 앱/API 설정이 섞인 provider의 제어 경계가 정리되어 있다.
+- [ ] [ops-status] runtime config, model artifact, provider health, capacity verification 상태를 운영자가 볼 수 있는 status/report 후보가 정리되어 있다.
+- [ ] [safety-policy] 모델 다운로드/삭제/restart가 필요한 작업의 사용자 승인, 롤백, 장애 처리, credential/secret 노출 금지 기준이 정리되어 있다.
+
+## 완료 리뷰
+
+- 상태: 없음
+- 요청일: 없음
+- 완료 근거: 스케치 Milestone이며 기능 Task가 아직 충족되지 않았다.
+- 리뷰 필요:
+  - [ ] 사용자가 provider runtime 설정 소유 범위를 검토했다.
+  - [ ] 사용자가 모델 선정/다운로드 자동화 수준을 검토했다.
+  - [ ] archive 이동을 승인했다.
+- agent-ui 상태 반영: 해당 없음
+- 리뷰 코멘트: 없음
+
+## 범위 제외
+
+- 현재 `Model Group Long-Context Admission` 계획 Milestone의 routing/admission 구현
+- 당장 dev provider pool의 모델 교체, 다운로드, process restart 자동화 구현
+- fully automated model marketplace
+- cloud fallback, cross-Edge/global balancing, billing/chargeback
+- 사용자 승인 없이 host disk를 크게 쓰거나 기존 모델 artifact를 삭제하는 동작
+
+## 작업 컨텍스트
+
+- 관련 경로: `apps/edge`, `apps/node`, `packages/go/config`, `configs/edge.yaml`, `agent-test/dev/inventory.yaml`, `agent-test/dev/edge-smoke.md`, `agent-test/dev/node-smoke.md`
+- 표준선(선택): long-context admission은 routing 필요조건이며, provider runtime/model acquisition orchestration은 그 정책을 실제 runtime에서 만족하게 만드는 충분조건 후보이다.
+- 표준선(선택): vLLM/vLLM-MLX는 launch profile과 health/capacity verification부터 시작하고, Lemonade는 앱/API 설정 소유권 경계를 먼저 확인한다.
+- 표준선(선택): 모델 다운로드와 삭제는 disk/resource 영향이 크므로 초기에는 사용자 승인 기반 dry-run/apply 흐름을 우선한다.
+- 선행 작업: Model Group Long-Context Admission, Provider-Device-Model Qualification 리포트와 Lifecycle 관리
+- 후속 작업: route recommendation, model marketplace, cross-Edge/cloud fallback 고도화
+- 확인 필요: provider runtime 설정 소유권, 모델 다운로드 자동화 수준, cache/delete/rollback 정책, 사용자 승인 경계
--- a/agent-roadmap/sdd/operational-observability-provider-management/model-group-long-context-admission/SDD.md
+++ b/agent-roadmap/sdd/operational-observability-provider-management/model-group-long-context-admission/SDD.md
@ -0,0 +1,129 @@
+# SDD: Model Group Long-Context Admission
+
+## 위치
+
+- Milestone: `agent-roadmap/phase/operational-observability-provider-management/milestones/model-group-long-context-admission.md`
+- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`
+
+## 상태
+
+[승인됨]
+
+## SDD 잠금
+
+- 상태: 해제
+- 사용자 리뷰: 없음
+- 잠금 항목:
+  - [x] [D01] long-context 판별은 output reserve나 hidden thinking이 아니라 입력 토큰 추정치만 기준으로 한다.
+  - [x] [D02] model group의 `context_window_tokens=262144`를 provider 공통 단일 요청 최대 context 계약으로 둔다.
+  - [x] [D03] provider별 차이는 단일 요청 최대 context가 아니라 `long_context_capacity`로 표현한다.
+  - [x] [D04] OneXPlayer dev 기준은 `ctx_size=524288`, `long_context_capacity=2`, `-np 3`이며 `ctx_size=786432`로 키우지 않는다.
+  - [x] [D05] queue 앞 long 요청이 long slot을 기다릴 때 뒤의 normal 요청은 빈 일반 slot이 있으면 먼저 dispatch할 수 있다.
+  - [x] [D06] long slot full은 long 요청 후보 제외 조건이며, 해당 provider의 일반 capacity가 남아 있으면 normal 요청 후보에서는 유지한다.
+
+## 문제 / 비목표
+
+- 문제: 현재 provider pool routing은 `in_flight`, capacity, priority 중심이라 요청이 5k인지 200k인지 알지 못한 채 provider를 선택한다. 256k 근처 요청이 1~3개 섞이는 실사용에서는 long-context 요청을 provider별 long slot으로 분산하고, long 요청이 찬 provider 또는 queue head 때문에 normal 요청 처리량이 같이 떨어지지 않게 admission 정책이 필요하다.
+- 비목표:
+  - output 길이나 hidden thinking token을 이용한 사전 long-context 분류
+  - provider별 단일 요청 최대 context를 model group보다 낮게 허용하는 혼합 그룹
+  - OneXPlayer `ctx_size`를 `786432`로 올리는 설정
+  - billing/chargeback, 장기 usage ledger, 품질 기반 자동 route recommendation
+
+## Source of Truth
+
+| 영역 | 기준 | 메모 |
+|------|------|------|
+| Roadmap | `agent-roadmap/phase/operational-observability-provider-management/milestones/model-group-long-context-admission.md` | Milestone 목표, 기능 Task, 완료 검토 기준 |
+| Code | `apps/edge/internal/service`, `apps/edge/internal/openai`, `packages/go/config`, `configs/edge.yaml` | queue admission, OpenAI-compatible request classification, config schema 구현 기준 |
+| Dev Inventory | `agent-test/dev/inventory.yaml`, `agent-test/dev/edge-smoke.md`, `agent-test/dev/node-smoke.md` | GX10, OneXPlayer, mac-mlx-vllm capacity/context smoke 기준 |
+| External Provider | GX10 vLLM, OneXPlayer Lemonade, mac vLLM-MLX | provider별 runtime option은 model group context 계약과 long capacity를 만족해야 한다 |
+| User Decision | D01-D06 | 이번 SDD에서 모두 결정 완료 |
+
+## State Machine
+
+| 상태 | 진입 조건 | 다음 상태 | 근거 |
+|------|-----------|-----------|------|
+| accepted | Edge OpenAI-compatible request를 수신했다 | classified | request body, model alias |
+| classified_normal | 추정 입력 토큰이 Edge root `long_context_threshold_tokens` 미만이다 | queued 또는 dispatched | `estimated_input_tokens`, `context_class=normal` |
+| classified_long | 추정 입력 토큰이 Edge root `long_context_threshold_tokens` 이상이다 | queued 또는 dispatched | `estimated_input_tokens`, `context_class=long` |
+| queued_normal | 일반 capacity가 없어 normal 요청이 대기한다 | dispatched 또는 cancelled/error | model group queue |
+| queued_long | long slot 또는 일반 capacity가 없어 long 요청이 대기한다 | dispatched 또는 cancelled/error | queue reason `long_context_capacity_full` 또는 일반 capacity full |
+| dispatched_normal | provider 일반 capacity가 예약되었다 | completed/error/cancelled | provider `in_flight` 증가 |
+| dispatched_long | provider 일반 capacity와 long slot이 함께 예약되었다 | completed/error/cancelled | provider `in_flight`, `long_in_flight` 증가 |
+| completed | provider 응답이 정상 종료되었다 | 없음 | completion event, usage |
+| error | provider, queue timeout, request validation 중 하나가 실패했다 | 없음 | error event |
+| cancelled | caller 또는 runtime이 취소했다 | 없음 | cancel event |
+
+## Interface Contract
+
+- 계약 원문: 없음
+- 입력:
+  - `context_window_tokens`: model group의 단일 요청 최대 context 계약. `qwen3.6:35b` dev 기준 `262144`.
+  - `long_context_threshold_tokens`: Edge root 설정의 입력 기준 long-context 분류 threshold. 초기 dev 기준 `100000`.
+  - `provider.capacity`: provider의 일반 동시 요청 admission capacity.
+  - `provider.total_context_tokens`: provider runtime이 long-context admission 기준으로 제공하는 전체 KV/context budget. runtime별 실제 옵션은 이 값에 매핑한다.
+  - `provider.long_context_capacity`: 해당 provider가 동시에 허용하는 262144 context window급 long slot 수.
+  - `estimated_input_tokens`: 요청 수신 시 Edge가 messages/tool schema/metadata를 근사 계산한 입력 토큰 수.
+  - `context_class`: `normal` 또는 `long`.
+- 출력:
+  - provider snapshot 또는 운영 log의 `long_context_capacity`, `long_in_flight`, `estimated_input_tokens`, `context_class`, queue reason.
+  - long-context 요청 대기, dispatch, 완료/실패 이벤트.
+- 금지:
+  - 같은 model group 안에서 provider별 단일 요청 최대 context를 262144보다 낮게 두어 라우팅 운에 따라 context 계약이 달라지게 하지 않는다.
+  - OneXPlayer에서 long slot 2개를 이유로 `ctx_size=786432`로 키우지 않는다. dev 기준은 `ctx_size=524288`, `-np 3`, `long_context_capacity=2`다.
+  - `provider.total_context_tokens < context_window_tokens * long_context_capacity`인 설정을 정상 long admission 설정으로 받아들이지 않는다.
+  - long slot full을 normal 요청 후보 제외 조건으로 사용하지 않는다. normal 요청은 일반 capacity가 남아 있으면 기존 routing policy를 따른다.
+  - long queue head가 long slot을 기다린다는 이유만으로 뒤의 normal 요청까지 무조건 막지 않는다.
+  - output 길이나 hidden thinking token을 long-context 사전 분류 기준으로 쓰지 않는다.
+
+## Acceptance Scenarios
+
+| ID | Milestone Task | Given | When | Then |
+|----|----------------|-------|------|------|
+| S01 | `threshold-config` | Edge root config에 long threshold가 설정되어 있다 | config check와 runtime start를 수행한다 | `long_context_threshold_tokens=100000`이 로드되고 잘못된 값은 검증에서 거부된다 |
+| S02 | `model-window` | `qwen3.6:35b` model group이 provider pool에 연결되어 있다 | `/v1/chat/completions` 또는 status/catalog를 확인한다 | model group 단일 context window가 `262144`로 일관되게 기록된다 |
+| S03 | `input-estimator` | 작은 설명형 요청과 100k 이상 입력 요청이 들어온다 | Edge가 요청을 queue에 넣기 전 분류한다 | 작은 요청은 normal, 100k 이상 요청은 long flag를 가진다 |
+| S04 | `provider-long-capacity` | provider에 일반 capacity, total context budget, long capacity가 설정되어 있다 | config check와 long 요청 dispatch를 수행한다 | `total_context_tokens >= context_window_tokens * long_context_capacity`가 검증되고 일반 `in_flight`와 `long_in_flight`가 함께 증가/회복된다 |
+| S05 | `provider-exclusion` | 특정 provider의 long slot이 이미 꽉 차 있다 | 새 long 요청을 dispatch하려 한다 | 해당 provider는 후보에서 제외되고 다른 long slot 가능 provider 또는 queue 대기를 선택한다 |
+| S06 | `queue-skip` | queue 앞 long 요청이 모든 long slot full로 대기하고 뒤에 normal 요청이 있다 | normal 요청을 받을 일반 capacity가 비어 있다 | normal 요청이 head-of-line blocking 없이 먼저 dispatch되고 long slot full provider도 normal 후보로는 유지된다 |
+| S07 | `dev-runtime-policy` | dev OneXPlayer provider를 설정한다 | inventory와 runtime option을 확인한다 | `ctx_size=524288`, `long_context_capacity=2`, `-np 3`이 유지되고 `786432`로 변경되지 않는다 |
+| S08 | `status-logs` | normal/long/mixed 요청이 실행된다 | Control Plane status 또는 Edge log를 확인한다 | `estimated_input_tokens`, `context_class`, `long_in_flight`, queue reason으로 admission 판단을 재구성할 수 있다 |
+| S09 | `capacity-smoke` | GX10, OneXPlayer, mac-mlx-vllm이 dev provider pool로 연결되어 있다 | normal 10-way, mixed long/normal, all-long-slot-full smoke를 수행한다 | 완료 후 일반/long in-flight와 queue가 모두 0으로 회복된다 |
+
+## Evidence Map
+
+| Scenario | Required Evidence | `agent-task` 연결 | 완료 Evidence 기대 |
+|----------|-------------------|------------------|---------------------------|
+| S01 | config loader/unit test, config check output | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `threshold-config`와 S01 충족 근거 |
+| S02 | model catalog/config test 또는 status snapshot | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `model-window`와 S02 충족 근거 |
+| S03 | estimator unit test와 request classification log | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `input-estimator`와 S03 충족 근거 |
+| S04 | config validation, scheduler/service test, provider snapshot | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `provider-long-capacity`와 S04 충족 근거 |
+| S05 | scheduler/service test 또는 dev mixed smoke | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `provider-exclusion`와 S05 충족 근거 |
+| S06 | queue ordering test와 dev smoke | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `queue-skip`와 S06 충족 근거 |
+| S07 | `agent-test/dev/inventory.yaml`, OneX runtime load/status evidence | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `dev-runtime-policy`와 S07 충족 근거 |
+| S08 | Control Plane status 또는 Edge log sample | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `status-logs`와 S08 충족 근거 |
+| S09 | dev smoke script/output and final recovery snapshot | `agent-task/m-model-group-long-context-admission/...` | `Roadmap Completion`에 `capacity-smoke`와 S09 충족 근거 |
+
+## Cross-repo Dependencies
+
+- 없음
+
+## Drift Check
+
+- [x] Milestone 기능 Task와 Acceptance Scenario가 일치한다.
+- [x] Evidence Map이 code-review/complete.log에서 검증 가능하다.
+- [x] agent-contract를 쓰는 경우 SDD에 계약 원문을 복제하지 않았다.
+- [x] 사용자 리뷰가 필요한 항목은 `USER_REVIEW.md`에만 남겼다.
+
+## 사용자 리뷰 이력
+
+- 2026-07-04: 사용자가 long-context 판별은 입력 기준, model group context window는 262144, provider 차이는 `long_context_capacity`, OneXPlayer는 `ctx_size=524288`/`-np 3`/long slot 2 유지, `786432` 확장 금지를 확정했다. long slot full은 long 요청 후보 제외 조건이며 normal 요청은 일반 capacity가 남으면 기존 policy로 dispatch한다.
+
+## 작업 컨텍스트
+
+- 표준선: 기존 provider pool routing의 일반 admission은 `in_flight`, capacity, priority 기준을 유지하고, long-context 요청에만 추가 long slot gate를 얹는다.
+- 표준선: `long_context_capacity`는 provider 전체 KV/context budget이 model group context window 몇 개분인지 나타내는 운영 설정이다.
+- 표준선: provider runtime ctx/KV budget은 `total_context_tokens >= context_window_tokens * long_context_capacity` 기준으로 검증한다.
+- 표준선: OneXPlayer `-np`는 이 Milestone에서 단순 최대 동시 요청 수로 취급한다.
+- 후속 SDD: 요청 실행 로그와 Usage Ledger 기반