# Milestone: Node Resource Model Unification

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operational-observability-provider-management/PHASE.md`

## 목표

Node를 provider/CLI를 함께 담는 Edge 연결 identity로 정리한다.
Node 자체는 global gate가 되지 않고, CLI, OpenAI-compatible provider, 기타 resource는 Node 아래 catalog로 나열되며 concurrency와 queue는 provider/resource capacity에서만 관리한다.
Mac dev-runtime에서는 Codex CLI와 MLX vLLM provider를 하나의 `mac-codex-node` 아래 resource로 합치고, Edge routing/status와 smoke 기준을 이 모델에 맞춘다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/sdd/operational-observability-provider-management/node-resource-model-unification/SDD.md`
- SDD 사유: Node identity, config schema, runtime wire 의미, Edge dispatch/status, Node admission, dev field smoke가 함께 바뀌는 runtime 책임 경계 변경이다.
- 잠금 해제 조건: 아래 체크리스트
  - [x] SDD 잠금이 해제되어 있다.
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다.
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다.
  - [x] Evidence Map이 완료 시 `Roadmap Completion`과 최종 검증 evidence로 검증 가능하게 연결되어 있다.
- 결정 필요: 없음

## 범위

- `NodeRuntimeConfig.concurrency`와 `runtime.concurrency`를 legacy/compat metadata로 낮추고 node-wide admission source에서 제외한다.
- `nodes[].providers[]`를 Node 아래 resource/provider catalog로 해석하고, provider가 참조하는 adapter instance validation을 강화한다.
- Node runtime admission에서 global gate를 제거하고 provider adapter capacity gate만 유지한다.
- CLI adapter는 IOP 레벨 concurrency 제한을 갖지 않는 unlimited resource로 표현한다.
- Edge dispatch는 provider pool 요청만 queue/concurrency path를 사용하고, CLI/legacy direct route는 provider queue를 타지 않는다.
- Edge status는 Node 아래 정의된 resource/provider catalog를 우선해 중복 snapshot을 피한다.
- dev-runtime 구성과 문서, smoke 기준을 `mac-codex-node` 하나에 Codex CLI와 `mac-mlx-vllm` provider resource가 함께 있는 형태로 정렬한다.

## 기능

### Epic: [node-resource-model] Node Identity and Resource Catalog

Node를 Edge 연결 owner로 두고, 실행 제어는 Node 하위 resource/provider가 소유하도록 계약, runtime, dev 검증을 하나로 묶는다.

- [x] [contract-schema] Node runtime contract와 config validation이 Node identity, resource catalog, provider adapter reference 의미를 고정한다. 완료 evidence: `agent-task/archive/2026/06/m-node-resource-model-unification/01_contract_schema/complete.log`. 검증: contract/config/proto 관련 unit test와 `Roadmap Completion` evidence가 남아 있다.
- [x] [node-admission] Node runtime admission에서 node-wide global gate가 제거되고 CLI는 unlimited, provider adapter는 capacity gate를 유지한다. 완료 evidence: `agent-task/archive/2026/06/m-node-resource-model-unification/02+01_node_admission/complete.log`. 검증: Node concurrency regression test와 CLI capability test가 통과한다.
- [x] [edge-routing-status] Edge dispatch와 status가 provider pool/resource catalog 기준으로 동작하고 CLI/direct route는 provider queue에 묶이지 않는다. 완료 evidence: `agent-task/archive/2026/06/m-node-resource-model-unification/03+01_edge_dispatch_status/complete.log`. 검증: Edge queue, OpenAI-compatible route, status provider test가 통과한다.
- [x] [dev-runtime-profile] dev-runtime에서 Mac Codex CLI와 MLX vLLM provider가 하나의 Node identity 아래 resource로 배포되고 3 connected nodes, 3 provider candidates, total capacity 10 smoke가 확인된다. 완료 evidence: `agent-task/archive/2026/06/m-node-resource-model-unification/04+01,02,03_dev_runtime_profile/complete.log`. 검증: clean sync/rebuild, config check, refresh dry-run 또는 apply, `/v1/responses`와 `/v1/chat/completions` capacity smoke evidence가 남아 있다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-29
- 완료 근거: `contract-schema`, `node-admission`, `edge-routing-status`, `dev-runtime-profile` 모두 PASS complete log와 `Roadmap Completion`을 남겼고, SDD Acceptance Scenario S01-S07과 Evidence Map을 충족한다. 종료 전 코드레벨 검토에서 provider catalog zero-capacity status fallback과 stale CLI help 문구를 보정했고 `go test -count=1 ./...`가 통과했다.
- 검토 항목: 완료 archive 전환
- 리뷰 코멘트: 남은 차단 항목 없음. 2026-06-29 완료 archive로 이동한다.

## 범위 제외

- Node를 여러 resource의 global gate 또는 global scheduler로 확장하는 설계
- Control Plane을 Edge-local runtime registry의 canonical store로 만드는 변경
- 새 외부 HTTP/gRPC endpoint 추가
- provider/device/model qualification report, lifecycle policy, 품질 기반 routing
- billing, chargeback, 조직 IAM, 장기 audit retention

## 작업 컨텍스트

- 관련 경로: `agent-contract/inner/edge-node-runtime-wire.md`, `agent-contract/inner/edge-config-runtime-refresh.md`, `proto/iop/runtime.proto`, `packages/go/config`, `apps/edge`, `apps/node`, `configs`, `agent-test/dev`, `agent-test/local`, `docs/edge-local-dev-guide.md`
- 표준선(선택): Node는 Edge와 연결되는 identity와 resource registry 책임을 가진다. Node 자체는 global admission gate가 아니며, resource/provider는 정의된 대로만 실행에 사용된다.
- 표준선(선택): provider concurrency와 queue는 provider pool/resource capacity에서만 관리하고, CLI 호출 수는 IOP 레벨에서 제한하지 않는다.
- 선행 작업: Model Alias Provider Pool과 Provider Catalog
- 후속 작업: 요청 실행 로그와 Usage Ledger 기반, Provider-Device-Model Qualification 리포트
- 완료 작업 evidence:
  - `agent-task/archive/2026/06/m-node-resource-model-unification/01_contract_schema/complete.log`
  - `agent-task/archive/2026/06/m-node-resource-model-unification/02+01_node_admission/complete.log`
  - `agent-task/archive/2026/06/m-node-resource-model-unification/03+01_edge_dispatch_status/complete.log`
  - `agent-task/archive/2026/06/m-node-resource-model-unification/04+01,02,03_dev_runtime_profile/complete.log`
- 확인 필요: 없음
