# Milestone: [route-05] RAG 기반 Local Routing Model 운영 전환

## 목표

- [`Execution Preset 하이브리드 Mode 라우팅`](openai-compatible-hybrid-request-execution-routing.md)의 cloud-first 운영에서 충분한 route evidence가 축적되면, 동일한 preset mode decision contract를 반환하는 RAG 기반 local routing model을 운영한다.
- cloud judge의 과거 판단만 복제하지 않고 실제 실행 품질·지연·비용·fallback 결과가 결합된 curated corpus를 retrieval 근거로 사용한다.
- local router를 shadow → canary → primary 순으로 승격하고, 불확실하거나 분포 밖인 요청은 cloud judge 또는 preset에 명시된 deterministic Edge policy로 fallback한다. 둘 다 허용되지 않으면 표준 오류로 닫는다.
- cloud model은 초기 teacher와 장기 fallback·drift 재평가 역할을 유지하며, 운영 기본 경로는 검증된 local router로 점진 전환한다.

## 상태

[스케치]

## 구분 원칙

- 이 마일스톤의 RAG는 **라우팅 판정 evidence 검색**을 위한 것으로, [`Long-term Memory RAG 2nd Wave`](long-term-memory-rag-second-wave.md)의 repository 장기 기억·작업 컨텍스트 RAG와 corpus, index, retention, 평가 지표를 공유하지 않는다.
- local model은 advisory를 반환하며 최종 결정 권한은 계속 IOP Edge arbiter에 있다.
- raw Plan/Review artifact, prompt/output, tool argument/result와 외부 workflow 상태는 입력 feature나 retrieval corpus에 포함하지 않는다. redacted mode·stage outcome은 route evidence로 사용할 수 있다.
- Edge가 local router 호출과 최종 mode 판정을 소유한다. IOP Node는 선택된 local router model을 일반 provider stage로 실행할 수 있지만 corpus, policy 또는 판정 권한을 소유하지 않는다.

## 선행 작업

- [`Execution Preset 하이브리드 Mode 라우팅`](openai-compatible-hybrid-request-execution-routing.md)
- [`요청 실행 로그와 Usage Ledger 기반`](../../operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md)
- [`Provider-Device-Model Qualification 리포트와 Lifecycle 관리`](../../operational-observability-provider-management/milestones/provider-device-model-qualification-report.md)

## 승격 조건

- cloud-first route evidence가 합의된 최소 표본·coverage·품질·retention gate를 통과한다.
- routing corpus schema, embedding/index 전략, retrieval freshness와 삭제 전파 방식이 확정된다.
- local model 입력/출력이 기존 route decision contract와 호환되고 confidence/abstain 의미가 확정된다.
- shadow 평가의 disagreement, regret, latency, cost, safety 지표와 통과 기준이 확정된다.
- canary 대상, 비율, 자동 rollback, cloud fallback budget이 확정된다.
- API/config/event schema 및 model lifecycle을 다루는 필수 SDD가 작성·승인된다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재는 최종 운영 목표와 선행 gate를 정의하는 개념 스케치다. 구현 마일스톤 승격 시 corpus/index, model lifecycle, shadow/canary/rollback 계약을 다루는 SDD가 필요하다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 evidence·corpus·평가·rollout 기준이 모두 확정되어 있다.
  - [ ] routing RAG와 repository 장기 기억 RAG의 corpus/index/retention 경계가 검증되어 있다.
  - [ ] shadow MVP, canary, primary 승격 범위가 분리되어 있다.
  - [ ] 필요한 SDD가 작성·승인되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] production 학습 corpus로 승격할 최소 표본·coverage·품질·보존 기간을 결정한다.
  - [ ] local routing model, embedding model, index backend와 갱신 주기를 결정한다.
  - [ ] 허용 disagreement/regret/latency 임계값, cloud audit 비율과 fallback budget을 결정한다.

## 범위

### 1. Routing corpus

- route feature, cloud advisory, Edge override, preset/allowed mode/selected mode, 실제 품질·지연·비용과 validation/error 결과를 연결한다.
- request 원문과 secret을 기본 저장하지 않고, redaction된 feature와 필요한 최소 retrieval evidence만 보존한다.
- 오래된 policy/model/version에 종속된 evidence는 freshness와 drift 정책에 따라 감쇠하거나 제외한다.
- corpus eligibility와 index deletion은 retention 삭제를 정확히 전파한다.

### 2. RAG local router

- 현재 request feature로 유사 route evidence를 검색하고, local model이 근거·confidence·abstain을 포함한 advisory를 반환한다.
- local advisory는 cloud selector와 같은 decision envelope를 사용해 Edge arbiter, execution preset과 mode handler를 변경하지 않고 교체 가능해야 한다.
- retrieval miss, low-confidence, out-of-distribution, index unavailable은 cloud judge 또는 preset에 명시된 deterministic policy로만 fallback하고 허용된 경로가 없으면 표준 오류로 닫는다.
- retrieved evidence와 model output은 실행 권한이 아니며 hard gate를 우회할 수 없다.

### 3. 운영 전환

- shadow에서 cloud decision과 local decision을 동시 평가하되 local 결과는 실행에 반영하지 않는다.
- canary에서는 합의된 요청군과 비율에만 local advisory를 적용하고 regret/safety 예산 초과 시 자동 rollback한다.
- primary 전환 뒤에도 sampling 기반 cloud audit와 drift detection으로 corpus/model refresh를 수행한다.
- model/index/policy version별 승격·rollback 이력을 유지한다.

## 기능

### Epic: [route-corpus] Route Corpus

- [ ] [evidence-gate] corpus 진입을 위한 표본·coverage·품질·privacy gate를 정의한다.
- [ ] [corpus-schema] feature/advisory/outcome/version 연결 schema를 고정한다.
- [ ] [retrieval-index] embedding, index partition, freshness, 삭제 전파를 구현한다.

### Epic: [local-router] Local Router

- [ ] [rag-input] request feature와 retrieval evidence 조합 입력을 정의한다.
- [ ] [decision-parity] cloud/local judge가 공유하는 decision envelope 호환성을 구현한다.
- [ ] [uncertainty-fallback] confidence, abstain, OOD, cloud/preset-declared fallback과 no-fallback 표준 오류를 구현한다.

### Epic: [route-rollout] Route Rollout

- [ ] [shadow-eval] disagreement, regret, 품질, latency, cost를 shadow에서 평가한다.
- [ ] [canary-policy] 대상 요청군, 적용 비율, 예산과 safety gate를 정의한다.
- [ ] [promotion-rollback] primary 승격과 자동·수동 rollback 절차를 구현한다.
- [ ] [drift-refresh] sampling audit, drift 감지, corpus/model refresh를 운영한다.

## 제외 범위

- repository 장기 기억·코드 검색·사용자 지식 검색을 위한 일반 RAG
- cloud model을 즉시 제거하거나 모든 요청을 local router로 강제하는 전환
- Edge hard gate, preset allowlist와 arbiter를 local model output으로 대체하는 설계
- 외부 workflow 상태를 학습 feature로 사용하는 설계
- IOP Node가 corpus/index/model policy를 관리하는 기능

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 최종 운영 목표와 선행 gate를 정리한 스케치이며 승격 조건과 기능 Task가 아직 충족되지 않았다.
- 검토 항목: 없음
- 리뷰 코멘트: 없음

## 작업 컨텍스트

- Phase: [`Knowledge / Tool 최적화 확장`](../PHASE.md)
- 선행: [`Execution Preset 하이브리드 Mode 라우팅`](openai-compatible-hybrid-request-execution-routing.md), [`요청 실행 로그와 Usage Ledger 기반`](../../operational-observability-provider-management/milestones/request-execution-log-usage-ledger-foundation.md), [`Provider-Device-Model Qualification 리포트와 Lifecycle 관리`](../../operational-observability-provider-management/milestones/provider-device-model-qualification-report.md)
- 구분 대상: [`Long-term Memory RAG 2nd Wave`](long-term-memory-rag-second-wave.md)
- 큐 배치: route lane의 `[route-05]` 5번이며 [`Execution Preset 하이브리드 Mode 라우팅`](openai-compatible-hybrid-request-execution-routing.md) 뒤에 실행한다. 별도 선행 gate는 [`Provider-Device-Model Qualification 리포트와 Lifecycle 관리`](../../operational-observability-provider-management/milestones/provider-device-model-qualification-report.md)다.
- 확인 필요: `구현 잠금 > 결정 필요`
