routing

type Candidate struct {
	Harness            string
	Provider           string
	Endpoint           string
	Model              string
	Score              float64
	CostUSDPer1kTokens float64
	CostSource         string
	Power              int
	Eligible           bool
	Reason             string

	// FilterReason is the typed disqualification category, set at the
	// rejection site that decided why this candidate is ineligible.
	// Empty for eligible candidates. Service-layer code maps this to the
	// public FilterReason* string constants without parsing free-form
	// Reason text.
	FilterReason FilterReason

	// LatencyMS, SuccessRate, and CostClass expose the score-component
	// inputs so callers can render per-axis explanations alongside the
	// final Score. Zero / negative values mean unknown (see Inputs docs).
	LatencyMS   float64
	SuccessRate float64
	CostClass   string
	SpeedTPS    float64

	QuotaOK          bool
	QuotaPercentUsed int
	QuotaTrend       string
}

type Capabilities struct {
	ContextWindow      int      // resolved tokens; 0 = unknown
	SupportsTools      bool     // supports tool/function calling
	SupportsStreaming  bool     // supports streaming responses
	SupportedReasoning []string // supported public reasoning values
	MaxReasoningTokens int      // 0 means numeric reasoning is unsupported/unknown
	SupportedPerms     []string // {"safe","supervised","unrestricted"} subset
	ExactPinSupport    bool     // accepts exact concrete model pins
	SupportedModels    []string // nil = no static allow-list
}

type Decision struct {
	Harness    string
	Provider   string
	Endpoint   string
	Model      string
	Reason     string
	Candidates []Candidate
}

type ErrHarnessModelIncompatible struct {
	// Harness is the canonical harness name supplied by the caller.
	Harness string
	// Model is the exact concrete model pin supplied by the caller.
	Model string
	// SupportedModels is the harness allow-list that rejected Model.
	SupportedModels []string
}

type ErrNoLiveProvider struct {
	// PromptTokens is the request's EstimatedPromptTokens at the time
	// escalation began. Zero means no prompt-token gating was active.
	PromptTokens int
	// RequiresTools mirrors the request's RequiresTools flag.
	RequiresTools bool
	// StartingTier is the profile name that escalation began from
	// (the profile in the original request).
	StartingTier string
}

type ErrNoProfileCandidate struct {
	Profile           string
	MissingCapability string
	Rejected          int
}

type ErrProfilePinConflict struct {
	// Profile is the explicit profile requested by the caller.
	Profile string
	// ConflictingPin names the explicit pin that violates the profile, such as
	// "Harness=claude" or "Model=local-model".
	ConflictingPin string
	// ProfileConstraint is a short description of the profile placement rule,
	// such as "local-only" or "subscription-only".
	ProfileConstraint string
}

type FilterReason string

type HarnessEntry struct {
	Name                string
	Surface             string
	CostClass           string
	IsLocal             bool
	IsSubscription      bool
	IsHTTPProvider      bool
	AutoRoutingEligible bool
	TestOnly            bool
	ExactPinSupport     bool
	DefaultModel        string
	SupportedModels     []string
	SupportedReasoning  []string
	MaxReasoningTokens  int
	SupportedPerms      []string
	SupportsTools       bool

	// Available reflects the harness's discovered availability.
	Available bool

	// QuotaOK / QuotaPercentUsed reflect live quota state (when applicable).
	// SubscriptionOK gates subscription harnesses at the eligibility level:
	// when false, the candidate is ineligible regardless of score.
	QuotaOK          bool
	QuotaPercentUsed int
	QuotaStale       bool
	QuotaTrend       string // unknown|healthy|burning|exhausting
	SubscriptionOK   bool   // false = hard gate; true = score-based demotion

	// InCooldown marks the entire harness as being in a failure cooldown.
	// When true the harness is demoted in score (via candidateInternal.InCooldown)
	// but not hard-rejected, so it can still win when all other harnesses are
	// also unavailable.
	InCooldown bool

	// Providers is the list of providers this harness can dispatch to.
	// For subprocess harnesses (claude/codex) this is typically a single
	// vendor entry. For the native "agent" harness it is the configured
	// list of HTTP providers.
	Providers []ProviderEntry
}

type Inputs struct {
	Harnesses           []HarnessEntry
	HistoricalSuccess   map[string]float64   // by harness name; -1 = insufficient data
	ObservedSpeedTPS    map[string]float64   // by "provider:model"
	ProviderSuccessRate map[string]float64   // by ProviderModelKey(provider, endpoint, model)
	ObservedLatencyMS   map[string]float64   // by ProviderModelKey(provider, endpoint, model)
	ProviderCooldowns   map[string]time.Time // by provider name
	CooldownDuration    time.Duration        // 0 = no cooldown enforcement
	Now                 time.Time            // injected for deterministic testing; default time.Now()
	CatalogResolver     func(ref, surface string) (concreteModel string, ok bool)
	ModelEligibility    func(model string) (ModelEligibility, bool)

	// ReasoningResolver returns the catalog's surface_policy reasoning_default
	// for a (profile, surface) pair. When set, buildHarnessCandidates uses it
	// to resolve Reasoning=auto to a concrete level before invoking the
	// capability gate, so candidates that cannot satisfy the resolved level
	// (e.g. an off-only variant under a profile whose surface default is
	// "high") are correctly disqualified instead of slipping through.
	ReasoningResolver func(profile, surface string) (resolved string, ok bool)
}

type ModelEligibility struct {
	Power        int
	ExactPinOnly bool
	AutoRoutable bool
}

type NoViableCandidateError struct {
	Rejected int
	Model    string
	Provider string
	Harness  string
	MinPower int
	MaxPower int
}

type ProviderEntry struct {
	Name               string
	BaseURL            string
	EndpointName       string
	EndpointBaseURL    string
	DefaultModel       string
	DiscoveredIDs      []string // models discovered via /v1/models or equivalent
	DiscoveryAttempted bool
	ContextWindows     map[string]int
	SupportsTools      bool

	// CostUSDPer1kTokens is the estimated blended USD cost per 1,000 tokens.
	// A zero value with CostSourceUnknown means the provider cost is unknown.
	CostUSDPer1kTokens float64
	// CostSource describes where CostUSDPer1kTokens came from: catalog,
	// subscription, user-config, or unknown.
	CostSource string

	// InCooldown reflects whether this provider is in a failure-cooldown window.
	InCooldown bool
}

type Request struct {
	Profile            string // "cheap" | "standard" | "smart"
	ModelRef           string // catalog alias (e.g. "qwen/qwen3.6")
	Model              string // exact concrete model pin
	Provider           string // exact provider pin; constrains routing to one provider identity
	Harness            string // hard preference; constrains routing to one harness
	Reasoning          string // public reasoning scalar
	Permissions        string // "safe" | "supervised" | "unrestricted"
	ProviderPreference string // "local-first" | "subscription-first" | "local-only" | "subscription-only"

	// EstimatedPromptTokens, when > 0, drives context-window gating.
	EstimatedPromptTokens int

	// RequiresTools, when true, requires the candidate to support tool calling.
	RequiresTools bool
	MinPower      int
	MaxPower      int
}