# Milestone: Edge 모델 그룹 Queue 스케줄링 전환

## 위치

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

## 목표

OpenAI-compatible 요청의 `model` 필드를 그대로 queue group key로 사용해, 같은 모델 그룹의 요청은 Edge에 있는 단일 FIFO queue에 세운다.
Node는 Edge가 dispatch한 실행을 수행하고 현재 실행 상태를 보고하는 역할로 단순화하며, Edge는 각 Node의 완료/실패/취소/연결 종료 이벤트를 기준으로 다음 대기 요청을 순차 dispatch한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- SDD: 불필요
- 사유: 현재 동기화는 기존 구현 결과와 active 작업현황을 맞추는 문서 상태 보정이며, 새 API/proto/config 계약이나 사용자 결정이 필요한 설계 변경을 만들지 않는다.

## 범위

- OpenAI-compatible `model` 값을 model group queue key로 사용한다.
- Edge service 계층이 model group별 FIFO queue, capacity, in-flight, queued, queue timeout을 소유한다.
- 같은 model group에 연결된 여러 Node 후보가 있어도 queue는 Edge에 하나만 두고, runnable slot이 생긴 Node로 순차 dispatch한다.
- Node의 provider/adapter admission queue는 제거하거나 Edge dispatch 이후의 실행 안전장치 수준으로 축소한다.
- Node command/capability snapshot의 queued/in-flight 의미를 Edge-owned runtime snapshot과 충돌하지 않게 정리한다.
- OpenAI Chat Completions/Responses 경로가 `model` 값 기반 Edge-owned queue를 우회하지 않게 하고, A2A/console은 별도 model group key를 만들지 않으면서 같은 Edge dispatch primitive를 공유할 수 있는 경계를 확인한다.

## 기능

### Epic: [edge-queue] Edge-Owned Model Queue

- [x] [group-key] OpenAI-compatible 요청의 `model` 값을 그대로 model group queue key로 쓰는 routing 계약이 정리되어 있다.
- [x] [edge-admission] Edge service가 model group별 FIFO admission queue, capacity, max_queue, queue_timeout, in-flight 상태를 소유한다.
- [x] [node-dispatch] Edge가 Node별 실행 가능 slot과 terminal run event를 기준으로 queue head를 다음 Node에 순차 dispatch한다.
- [x] [node-simplify] Node-local provider FIFO queue가 제거되거나 Edge dispatch 이후의 실행 안전장치로 축소되어, 각 Node가 queue owner가 되지 않는다.
- [x] [snapshot-contract] Edge-visible capacity/in-flight/queued snapshot이 Edge-owned model group 상태를 기준으로 표현되고 Node capability snapshot과 충돌하지 않는다.
- [x] [surface-coverage] OpenAI Chat Completions/Responses 실행 경로가 `model` 값 기반 Edge-owned queue를 우회하지 않고, A2A/console 경로는 별도 model group key 없이 같은 Edge dispatch primitive와 충돌하지 않는다.
- [x] [verification] Edge-owned queue의 FIFO 순서, queue overflow/timeout, run terminal release, node disconnect release, multi-node dispatch가 테스트로 검증되어 있다. 검증: 대상 Go 패키지 테스트와 queue 관련 regression test가 통과한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-16
- 완료 근거: `group-key`는 OpenAI Chat/Responses handler가 request `model`을 `SubmitRunRequest.ModelGroupKey`로 전달하고, service queue path가 non-empty `ModelGroupKey`를 Edge queue key로 사용하는 코드와 테스트 근거로 충족되었다. 기존 archive `complete.log`의 `Roadmap Completion`에는 `group-key` id가 누락되어 자동 체크되지 않았지만, `surface-coverage`와 `edge-admission` 완료 로그가 같은 계약을 검증한다. `edge-admission`, `node-dispatch`, `node-simplify`, `snapshot-contract`, `surface-coverage`, `verification`은 `agent-task/archive/2026/06/m-edge-model-group-queue-scheduling/` 하위 PASS `complete.log`의 `Roadmap Completion` 근거로 충족되었다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 코드 레벨 재검토와 관련 Go 테스트, 보조 edge-node smoke가 통과해 완료 승인 후 archive한다.

## 범위 제외

- cloud fallback, 자동 품질 평가 feedback, cross-Edge 부하 라우팅
- provider별 실제 endpoint 운영/배포 제품화
- vLLM/SGLang provider 실테스트 완료 판정
- OpenAI-compatible `model` 외 별도 `model_group` 공개 필드 추가

## 작업 컨텍스트

- 관련 경로: `apps/edge`, `apps/node`, `packages/go/config`, `proto/iop`, `configs`
- 표준선(선택): 내부 실행은 계속 `adapter + target` 기준을 유지하고, OpenAI-compatible 외부 경계의 `model` 값만 Edge queue group key로 사용한다.
- 표준선(선택): queue owner는 Edge이며, Node는 dispatch된 실행과 provider availability/probe 결과를 제공하는 실행자다.
- 선행 작업: Node provider 상태와 Capacity Queue 기반, Lemonade provider 서빙 경로 추가
- 후속 작업: vLLM provider 서빙 경로 추가, SGLang provider 서빙 경로 추가
- 현재 작업현황(2026-06-16): active `agent-task/m-edge-model-group-queue-scheduling` 작업은 없고, 모든 기능 Task와 코드 레벨 재검토가 충족되어 archive 완료 상태다.
- 확인 필요: 없음
