04. Model Routing Spec

1. Purpose

Define the capability-vector selection contract for IModelVectorRouter, ensuring both dynamic optimization in normal execution and deterministic reproducibility in replay execution.

2. Scope

• ModelCapacityVector
• IDynamicCapacityProvider
• IVectorMatcher
• IModelVectorRouter
• IComputeShapeAdvisor
• ICapabilityRegistry

3. Normative Requirements

• MRS-001 Routing MUST be capability-driven, not model-name driven.
• MRS-002 Candidates failing mandatory axes MUST be excluded.
• MRS-003 Dynamic constraints (budget, latency, load) MUST be evaluated.
• MRS-004 Routing scores MUST be recorded for auditability.
• MRS-005 Multidimensional Vector Mapping: Required capability MUST be evaluated across the five core axes: Reasoning, Fidelity, Latency, Economy, and ContextWindow.
• MRS-006 Hardware Awareness: Through IComputeShapeAdvisor, routing MUST prioritize candidates with higher energy efficiency on the current device shape (GPU/NPU).
• MRS-007 Deterministic Tie-breaking: When multiple candidates share identical scores, selection MUST converge via a deterministic algorithm based on hash and/or priority list.

3.1 Replay-Aware Routing Bypass

• MRS-REPLAY-001 IModelVectorRouter MUST NOT execute dynamic routing when replay execution detects ReplayContext.LockedProviderInfo.
• MRS-REPLAY-002 During replay, the execution engine MUST enable Force Provider Mode and apply Provider/Model/Quantization values from LockedProviderInfo without alteration.
• MRS-REPLAY-003 A replay dump missing LockedProviderInfo MUST NOT be treated as deterministic replay.

4. Fail-Closed

• MRS-F001 Abort when no candidate satisfies mandatory axes.
• MRS-F002 Block new routing when budget hard limit is reached.
• MRS-F003 Reject capability declarations with schema mismatch.
• MRS-F004 Dynamic Limit Violation: If IDynamicCapacityProvider detects overload or unstable connectivity immediately before execution, abort instead of degraded forced execution.
• MRS-F005 Capability Mismatch (ROM Integrity): If required ROM capabilities (for example [[capability.vision]]) cannot be satisfied by a selected model, block as validation failure.

5. Acceptance Criteria

• AC1: Identical inputs and constraints produce identical routing output.
• AC2: Mandatory-axis failing candidates are never selected.
• AC3: Tie cases are resolved deterministically with stable output.
• AC4: During replay execution, selected provider MUST match previously selected provider with 100% consistency.

6. Interface / DTO Definition

Define immutable data structures that guarantee routing lock behavior.

public sealed record LockedProviderInfo(\n    string ProviderId,\n    string ModelId,\n    string QuantizationProfile,\n    ModelCapacityVector CapacitySnapshot,\n    DateTime CapturedAtUtc);\n\npublic sealed record ReplayRoutingPolicy(\n    bool ForceProviderMode,\n    LockedProviderInfo LockedProviderInfo);

7. ModelCapacityVector Structure (ROM Representation)

Model capability is registered in ICapabilityRegistry as ROM.

---\nid: "provider.openai.gpt4o"\ntype: "model.capability"\nversion: "1.0.0"\n---\n# Capacity Axes\n* [reasoning]: 0.95\n* [fidelity]: 0.98\n* [latency_score]: 0.60\n* [token_cost_index]: 0.80\n\n# Physical Constraints\n* [preferred_device]: [[device.gpu]]\n* [max_concurrency]: 50

8. Routing Algorithm

IModelVectorRouter finalizes routing in the following steps.

1. Context Check

Check whether replay mode is active and LockedProviderInfo exists. If present, jump to step 5.

2. Requirement Extraction

Extract mandatory axes from input ROM (for example reasoning > 0.9).

3. Hard Filtering

Remove candidates that fail mandatory axes.

4. Soft Scoring & Dynamic Adjustment

IVectorMatcher computes cosine similarity or weighted distance, then apply budget/load penalties from IDynamicCapacityProvider.

5. Final Selection

Select highest score candidate (or LockedProvider) and record traceability matrix into Replay Dump.

Changelog

• v0.0.0 / v0.0.0.0: Initial draft
• v0.0.1 (2026-05-06): Version upgrade aligned with documentation guidelines