# Milestone: [route-04] Execution Preset 하이브리드 Mode 라우팅

## 목표

- 폐기된 [`OpenAI-compatible Hybrid Routing · Context Optimization`](../../../archive/phase/routing-policy-model-orchestration/milestones/openai-compatible-hybrid-routing-context-optimization.md)의 핵심 의도 중 **IOP 내부 요청 난이도·실행 형태 라우팅과 학습 가능한 decision evidence**만 현재 책임 경계에 맞게 복원한다.
- 외부 호출자가 선택한 model이 execution preset을 먼저 고정하고, IOP Edge가 요청 난이도, 기능 요구, 컨텍스트 규모, 지연·비용 예산과 model 가용성을 종합해 그 preset의 `allowed_modes` 안에서 최종 mode를 결정한다.
- 초기 운영에서는 cloud model이 의미·난이도 advisory를 제공하고 deterministic hard gate와 Edge arbiter가 최종 권한을 갖는다. cloud selector의 timeout/schema/provider 실패는 다른 mode로 조용히 우회하지 않고 표준 model/API 오류로 종료한다.
- 기존 provider-direct 실행, [`IOP 단일 요청 Agent 실행`](iop-owned-single-request-agent-execution.md)의 fixed `light`와 [`Heavy Plan/Review 실행과 검증 MVP`](knowledge-tool-validation-optimization.md)의 `heavy`를 같은 preset mode contract로 연결한다.
- route-02의 fixed `light` preset과 single-request runtime을 그대로 지원한다. 이 마일스톤은 advisory-only selector와 mode별 entry stage를 분리하는 explicit selection strategy를 추가하며 기존 fixed preset의 의미를 암묵적으로 바꾸지 않는다.
- route decision/evidence를 축적해 후속 [`RAG 기반 Local Routing Model 운영 전환`](rag-local-routing-model-operations.md)이 selector 구현만 대체하고 preset/runtime은 그대로 재사용할 수 있게 한다.

## 상태

[스케치]

## 복원 원칙

- archive의 폐기 문서는 당시 스냅샷으로 유지하고 직접 수정하지 않는다.
- 폐기 설계의 artifact lane, grade와 자동화 runtime을 복원하지 않는다. 현재 기준은 exposed model → execution preset → allowed mode decision이다.
- preset은 selection strategy, selector와 mode별 model/stage 조합을 소유한다. 이 milestone의 router는 preset을 바꾸거나 preset 밖 model/target을 만들지 않는다. route-02의 fixed strategy와 새 advisory-then-dispatch strategy는 config에서 명시적으로 구분한다.
- Plan/Review artifact와 internal tool cycle은 선택된 `light/heavy` handler와 IOP Node tool executor가 소유한다. route evidence에는 raw plan/review, prompt, output과 tool argument/result를 저장하지 않는다.
- target agent나 외부 workflow 제품의 process, state, contract나 runtime은 연결하지 않는다.
- IOP Node는 Edge가 확정한 stage model과 request-scoped workspace tool을 실행·취소하고 상태·usage를 보고하되 preset이나 mode를 판정하지 않는다.

## 선행 작업

- [`IOP 단일 요청 Agent 실행`](iop-owned-single-request-agent-execution.md)
- [`Heavy Plan/Review 실행과 검증 MVP`](knowledge-tool-validation-optimization.md)

## 승격 조건

- `preset_id`, allowed mode, advisory, hard-gate reason, confidence와 policy version을 포함한 mode decision contract가 확정된다.
- cloud selector와 Edge arbiter 사이의 권한 경계 및 model output 불신 원칙이 확정된다.
- 여러 preset이 `direct/light/heavy/추가 mode`를 서로 다르게 조합할 때 selector input과 mode handler registry 경계가 확정된다.
- 기존 fused preset 호환성, advisory-only selector와 mode별 direct-executor/planner entry stage schema가 확정된다.
- selector/target unavailable, timeout, low-confidence와 schema failure가 표준 오류로 수렴하는 규칙이 확정된다.
- route evidence의 저장 위치, 보존 기간, 민감정보 제거, 학습 후보 승격 기준이 확정된다.
- API/config/event schema가 수반되는 구현 전 필수 SDD가 작성·승인된다.

## 구현 잠금

- 상태: 잠금
- SDD: 불필요
- SDD 문서: 없음
- SDD 사유: 현재는 복원된 cloud-first mode router와 후속 local selector의 경계를 정의하는 개념 스케치다. decision/evidence schema와 운영 policy 구현 전에 필수 SDD가 필요하다.
- 잠금 해제 조건: 아래 체크리스트
  - [ ] 승격 조건의 decision·failure·evidence 항목이 모두 해소되어 있다.
  - [ ] route-02/03에서 재사용할 preset/mode/runtime 계약과 이 milestone의 일반화 범위가 분리되어 있다.
  - [ ] 기존 fused preset을 재해석하지 않는 selection strategy와 mode entry migration/validation이 확정되어 있다.
  - [ ] cloud-first 운영과 RAG local selector 후속 범위가 분리되어 있다.
  - [ ] 필요한 SDD가 작성·승인되어 있다.
- 결정 필요: 아래 체크리스트
  - [ ] cloud selector model, 입력 feature, confidence 의미와 stage budget을 결정한다.
  - [ ] preset별 mode 난이도·비용·지연 policy와 deterministic hard gate를 결정한다.
  - [ ] route evidence 최소 표본·품질·보존 기간과 민감정보 제거 기준을 결정한다.

## 범위

### 1. Mode decision contract

- 모든 decision은 provider-specific 응답이 아니라 IOP 공통 envelope로 정규화한다.
- 최소 필드는 `decision_id`, `request_id`, `preset_id`, `allowed_modes`, selected `mode`, hard-gate reason, advisory 요약, confidence, timing과 policy version이다.
- cloud selector는 mode와 난이도 근거를 제안할 수 있지만 preset, stage target, tool parameter와 실행 권한을 갖지 않는다.
- Edge arbiter는 preset snapshot, capability, health, context와 budget으로 advisory를 검증하고 최종 mode를 확정한다.
- advisory-then-dispatch strategy에서 mode가 확정되면 해당 preset의 mode별 entry stage부터 ordered stage/model/options를 handler에 전달한다. `direct`는 direct executor, `light/heavy`는 각 planner entry를 가질 수 있다.
- 기존 fixed `light` strategy는 route-02 의미대로 plan entry로 바로 시작하며, 운영자가 명시적으로 migration하지 않는 한 advisory-only selector를 암묵 추가하지 않는다.

### 2. Preset별 mode 조합

- balanced preset은 `direct/light/heavy`, plan-only preset은 `light/heavy`, high-think one-shot preset은 `direct`만 허용할 수 있다.
- `direct`는 fast/weak와 동의어가 아니며 preset stage binding에 따라 strong cloud와 high thinking을 사용할 수 있다.
- `light/heavy`의 차이는 model 강도가 아니라 Plan/Review lifecycle과 작업 형태다.
- 미래 mode는 registered handler가 있을 때 같은 decision contract에 추가하고, 알 수 없는 mode는 config validation에서 거부한다.

### 3. Cloud-first 판단과 오류

- request facts와 deterministic hard gate를 먼저 계산한 뒤 cloud selector에는 필요한 최소 semantic context와 preset allowed mode만 전달한다.
- hard gate는 endpoint/tool/workspace capability, context ceiling, deadline, cost ceiling과 target health를 포함한다.
- cloud selector timeout·provider 오류·low-confidence·schema failure, 선택 mode의 capability/target unavailable은 endpoint 표준 오류로 종료한다.
- fallback이나 default mode가 필요하면 preset에 명시된 별도 policy로만 추가할 수 있으며 이 milestone의 암묵 기본값으로 두지 않는다.

### 4. Route evidence

- request 원문 전체가 아니라 redacted feature snapshot, selector advisory, Edge override, selected mode, stage outcome, latency/cost와 error reason을 학습 가능한 evidence로 정규화한다.
- [`요청 실행 로그와 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)의 운영 지표를 참조하되 mode policy 소유권은 Edge에 유지한다.
- evidence schema는 후속 local selector가 같은 입력·출력 계약을 shadow replay할 수 있어야 한다.
- 민감정보 제거와 retention을 통과하지 못한 기록은 학습 corpus 후보에 포함하지 않는다.

## 기능

### Epic: [mode-decision] Preset Mode Decision

- [ ] [decision-contract] selection strategy, preset/allowed mode/selected mode/advisory/hard-gate를 연결하는 versioned decision envelope를 정의한다.
- [ ] [cloud-selector] cloud model selector의 최소 입력/출력, timeout, confidence와 표준 오류 계약을 구현한다.
- [ ] [edge-arbiter] preset allowlist, capability, health, context와 budget으로 advisory를 검증하고 최종 mode를 확정한다.
- [ ] [mode-dispatch] 확정 mode를 registered handler와 preset의 mode entry/ordered stage binding에 연결하고 기존 fused preset 호환성을 유지한다.

### Epic: [preset-policy] Preset Policy

- [ ] [preset-composition] direct-only, plan-only, balanced와 custom mode 조합을 검증한다.
- [ ] [mode-threshold] preset별 난이도·기능·지연·비용 threshold와 hard-gate reason을 정의한다.
- [ ] [failure-policy] selector/mode/target 실패가 암묵 fallback 없이 표준 API 오류로 닫히는 정책을 구현한다.

### Epic: [route-evidence] Route Evidence

- [ ] [route-events] selector/arbiter/stage outcome을 하나의 request/decision identity로 연결한다.
- [ ] [dataset-curation] redaction, retention, 중복 제거와 outcome label 규칙을 정의한다.
- [ ] [eval-gate] cloud 판단과 실제 결과의 일치도·regret·비용·지연 평가 기준을 정의한다.
- [ ] [local-handoff] 후속 RAG local selector가 소비할 corpus/export contract를 고정한다.

## 제외 범위

- 외부 model 선택을 무시하고 router가 다른 preset으로 전환하는 기능
- preset 밖 model/target/tool을 cloud model이 직접 선택하는 기능
- 범용 external workflow 제품과의 상태·artifact·process 공유
- IOP Node가 preset, 요청 난이도 또는 mode policy를 자율 판정하는 기능
- 이 milestone에서 RAG local selector를 production primary로 승격하는 작업
- repository 장기 기억 RAG와 routing evidence corpus의 통합

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 복원 범위와 preset 중심 선후 관계를 정리한 스케치이며 승격 조건과 기능 Task가 아직 충족되지 않았다.
- 검토 항목: 없음
- 리뷰 코멘트: 없음

## 작업 컨텍스트

- Phase: [`지식과 도구 최적화 확장`](../PHASE.md)
- 복원 근거: [`OpenAI-compatible Hybrid Routing · Context Optimization`](../../../archive/phase/routing-policy-model-orchestration/milestones/openai-compatible-hybrid-routing-context-optimization.md)
- 선행: [`IOP 단일 요청 Agent 실행`](iop-owned-single-request-agent-execution.md), [`Heavy Plan/Review 실행과 검증 MVP`](knowledge-tool-validation-optimization.md)
- 후속: [`RAG 기반 Local Routing Model 운영 전환`](rag-local-routing-model-operations.md)
- 큐 배치: `[route-03]` 바로 뒤인 `[route-04]` 4번이다.
- 확인 필요: `구현 잠금 > 결정 필요`
