# Milestone: Model route Queue 정책 정합화

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/inference-provider-extension/PHASE.md`

## 목표

Edge-owned model group queue의 정책 원천을 OpenAI-compatible `model_routes`의 model alias로 정리한다.
`max_queue`와 `queue_timeout_ms`는 model alias queue 정책으로 두고, Node/provider instance의 `capacity`는 per-node 동시 실행 slot 기준으로 남긴다.
기존 adapter instance queue 설정은 호환 fallback으로만 유지해, 다중 Node/다중 provider pool에서 queue owner와 설정 위치가 어긋나지 않게 만든다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/archive/sdd/inference-provider-extension/model-route-queue-policy-alignment/SDD.md`
- SDD 사유: OpenAI route config schema와 Edge queue dispatch 계약을 바꾸는 작업이다.
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다
- 결정 필요: 없음

## 범위

- `openai.model_routes[]`에 Edge-owned model group queue 정책 필드를 추가한다.
- route-level `max_queue`와 `queue_timeout_ms`가 있으면 Edge queue group policy에서 우선 사용한다.
- route-level queue policy가 없으면 기존 Node/provider adapter instance의 queue 설정을 호환 fallback으로 유지한다.
- Node/provider instance의 `capacity`는 각 Node가 해당 adapter instance로 동시에 받을 수 있는 요청 slot으로 유지한다.
- `/v1/chat/completions`와 `/v1/responses` 모두 같은 route-level queue policy 전달 경로를 사용한다.
- 설정 예시와 테스트에서 model alias queue policy와 per-node capacity의 책임 경계를 명확히 한다.

## 기능

### Epic: [route-policy] Model Route Queue Policy

OpenAI-compatible model alias가 Edge queue group의 정책 원천이 되도록 config, dispatch DTO, queue admission 경로를 정리한다.

- [x] [config-schema] `openai.model_routes[]`가 `max_queue`, `queue_timeout_ms`를 받을 수 있고 validation/default/fallback 문서가 정리되어 있다. 검증: `go test -count=1 ./packages/go/config ./apps/edge/internal/openai`
- [x] [dispatch-contract] OpenAI Chat Completions와 Responses route resolution이 route-level queue policy를 `SubmitRunRequest`로 전달한다. 검증: `go test -count=1 ./apps/edge/internal/openai`
- [x] [queue-policy] Edge queue admission이 route-level queue policy를 adapter instance fallback보다 우선하고, route policy가 없을 때 기존 fallback을 유지한다. 검증: `go test -count=1 ./apps/edge/internal/service`
- [x] [docs-example] `configs/edge.yaml` 예시가 model alias queue policy와 Node/provider `capacity`의 책임 경계를 보여준다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-17
- 완료 근거:
  - `agent-task/archive/2026/06/m-model-route-queue-policy-alignment/01_config_route_policy/complete.log`가 `config-schema`, `dispatch-contract`, `docs-example`과 SDD S01, S02, S04 PASS를 기록했다.
  - `agent-task/archive/2026/06/m-model-route-queue-policy-alignment/02+01_service_queue_policy/complete.log`가 `queue-policy`와 SDD S03 PASS를 기록했다.
  - 최종 검증으로 `go test -count=1 ./packages/go/config ./apps/edge/internal/openai`, `go test -count=1 ./apps/edge/internal/service`, `git diff --check`가 PASS로 기록되어 있다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-17 코드 레벨 검토와 관련 테스트 재검증 후 종료 승인에 따라 완료 처리했다.

## 범위 제외

- GPU/CPU/VRAM 실측 기반 자동 capacity 조정
- cross-Edge 부하 라우팅, cloud fallback, 품질/비용 기반 모델 선택
- `model_routes` 하나에서 provider별로 서로 다른 target을 선언하는 route 후보 목록
- vLLM/Lemonade/Ollama provider 자체의 실서비스 smoke 완료 판정
- Node bootstrap, Control Plane, Client UI 변경

## 작업 컨텍스트

- 관련 경로: `packages/go/config`, `configs/edge.yaml`, `apps/edge/internal/openai`, `apps/edge/internal/service`, `agent-test/local/edge-smoke.md`, `agent-test/local/platform-common-smoke.md`
- 표준선(선택): queue owner는 Edge이며, OpenAI-compatible `model` 값은 model group key다.
- 표준선(선택): `model_routes`는 외부 model alias와 Edge queue policy를 소유하고, Node/provider instance는 adapter endpoint와 per-node `capacity`를 소유한다.
- 표준선(선택): 기존 adapter instance `max_queue`/`queue_timeout_ms`는 route-level queue policy가 없는 설정의 호환 fallback으로 유지한다.
- 선행 작업: Edge 모델 그룹 Queue 스케줄링 전환
- 후속 작업: vLLM provider 서빙 경로 추가, SGLang provider 서빙 경로 추가, provider catalog/device status에서 queue policy 표시 확장
- 확인 필요: 없음
