<!-- task=m-vllm-provider-serving-validation/02+01_config_contract plan=1 tag=VLLM_CONFIG -->
# Plan: vLLM OpenAI-compatible config contract

## 이 파일을 읽는 구현 에이전트에게

이 plan은 `config-contract` Task를 구현하기 위한 실행 계약이다. 선행 작업 `01_spark_container`의 PASS evidence 또는 동등한 field evidence를 확인한 뒤 진행한다. 구현 에이전트는 실제 변경과 검증 출력으로 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 반드시 채운다.

사용자 전용 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌 없이는 안전하게 진행할 수 없는 경우 직접 질문하지 말고 review stub의 `사용자 리뷰 요청` 섹션에 정확한 blocker를 기록한 뒤 중단한다. 후속 에이전트가 재실행/증거 수집으로 해소할 수 있는 검증 공백은 사용자 리뷰 요청이 아니다.

## 사용자 리뷰 요청 흐름

구현 중 blocker는 active `CODE_REVIEW-*-G??.md`의 `사용자 리뷰 요청` 섹션에만 기록한다. 구현 에이전트는 chat에서 사용자에게 선택지를 제시하거나 `request_user_input`을 호출하지 않는다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/inference-provider-extension/milestones/vllm-provider-serving-validation.md`
- Task: `config-contract`

## Spec Targets

- SDD: `agent-roadmap/sdd/inference-provider-extension/vllm-provider-serving-validation/SDD.md`
- Scenario: `S02`

## 분석 결과

### 읽은 파일

- `packages/go/config/config.go`
- `proto/iop/runtime.proto`
- `apps/edge/internal/node/mapper.go`
- `apps/node/internal/adapters/factory.go`
- `apps/node/internal/adapters/openai_compat/openai_compat.go`
- `configs/edge.yaml`
- `agent-test/local/platform-common-smoke.md`

### 테스트 환경 규칙

- config/proto 변경은 `platform-common` 규칙을 따른다.
- vLLM OpenAI-compatible provider는 internal `adapter + target` 경계를 유지해야 한다.
- private endpoint와 secret은 tracked config example에 고정하지 않는다.

### 테스트 커버리지 공백

- 현재 `openai_compat` adapter는 provider, endpoint, headers, queue/timeout 구조가 있다.
- vLLM용 contract example과 test fixture가 부족하므로 config/example/test를 함께 보강한다.

### 심볼 참조

- `config.EdgeOpenAIConf.ModelRoutes`
- `config.OpenAICompatInstanceConf`
- `node.adapterToProto`
- `adapters.BuildFromPayload`
- `openai_compat.BuildFromConfig`

### 분할 판단

- 이 작업은 code/config contract만 다룬다.
- chat/streaming smoke script와 field smoke는 후속 plan에서 실행한다.

### 범위 결정 근거

- 포함: `configs/edge.yaml` vLLM example, config load/normalize test, mapper/factory test 필요시 보강.
- 제외: vLLM container 기동, smoke script 신설, 실제 field chat smoke.

### 빌드 등급

- `local-G06`: config와 adapter boundary 변경 가능성이 있고 여러 Go package 검증이 필요하다.

## 구현 체크리스트

- [ ] `01_spark_container`의 PASS evidence 또는 동등한 field evidence에서 실제 image/tag와 served model 기준을 확인한다.
- [ ] `configs/edge.yaml`에 vLLM OpenAI-compatible provider example을 추가하거나 기존 예시를 조정해 alias `qwen3.6:35b`, served model `nvidia/Qwen3.6-35B-A3B-NVFP4`, endpoint placeholder, headers 없음, timeout/queue/option passthrough 의도를 드러낸다.
- [ ] `packages/go/config`와 Edge/Node mapper/factory 테스트에 vLLM provider contract fixture를 추가하거나 기존 coverage로 충분한 이유를 review stub에 기록한다.
- [ ] direct `vllm` adapter 예시가 남아 있다면 legacy/experimental 의미가 혼동되지 않도록 문맥을 정리한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 구현 항목

- [VLLM_CONFIG-1] vLLM OpenAI-compatible config example 정리
- [VLLM_CONFIG-2] config/mapper/factory contract test 보강
- [VLLM_CONFIG-3] adapter/target/model naming drift 점검

## 수정 파일 요약

- 예상 변경: `configs/edge.yaml`
- 예상 변경 가능: `packages/go/config/*_test.go`, `apps/edge/internal/node/*_test.go`, `apps/node/internal/adapters/*_test.go`
- 변경 금지: private endpoint/token을 tracked 파일에 기록하지 않는다.

## 최종 검증

```bash
go test ./packages/go/config ./apps/edge/internal/node ./apps/node/internal/adapters ./apps/node/internal/adapters/openai_compat
git diff --check
```

예상 결과: vLLM provider config fixture가 통과하고 whitespace error가 없다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
