routing

type Candidate struct {
	Harness            string
	Provider           string
	Endpoint           string
	ServerInstance     string
	Model              string
	Score              float64
	CostUSDPer1kTokens float64
	CostSource         string
	Power              int
	ContextLength      int
	ContextSource      string
	ScoreComponents    map[string]float64
	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
	Utilization     float64
	ContextHeadroom int

	QuotaOK          bool
	QuotaPercentUsed int
	QuotaTrend       string
	StickyAffinity   float64
}

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
	ServerInstance string
	Model          string
	Reason         string
	Candidates     []Candidate
}

type EndpointLoad struct {
	LeaseCount           int
	NormalizedLoad       float64
	UtilizationFresh     bool
	UtilizationSaturated bool
}

type ErrAllProvidersQuotaExhausted struct {
	RetryAfter         time.Time
	ExhaustedProviders []string
}

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
	QuotaReason      string
	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 "fiz" 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)
	EndpointLoads                map[string]EndpointLoad
	EndpointLoadResolver         func(provider, endpoint, model string) (EndpointLoad, bool)
	StickyServerInstanceResolver func(stickyKey string) (string, bool)
	ProviderCooldowns            map[string]time.Time // by provider name
	CooldownDuration             time.Duration        // 0 = no cooldown enforcement

	// ProviderQuotaExhaustedUntil maps provider name → retry_after time.
	// A provider with retry_after > Now is treated as quota_exhausted and
	// disqualified from candidate selection. The service maintains the
	// per-provider quota state machine and projects it into this map for
	// each routing call.
	ProviderQuotaExhaustedUntil map[string]time.Time
	Now                         time.Time // injected for deterministic testing; default time.Now()
	CatalogResolver             func(ref, surface string) (concreteModel string, ok bool)
	CatalogCandidatesResolver   func(ref, surface string) (concreteModels []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
	ServerInstance       string
	EndpointName         string
	EndpointBaseURL      string
	DefaultModel         string
	CostClass            string
	DiscoveredIDs        []string // models discovered via /v1/models or equivalent
	DiscoveryAttempted   bool
	ContextWindows       map[string]int
	ContextWindowSources map[string]string
	ContextWindow        int
	ContextWindowSource  string
	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"
	CorrelationID      string // validated sticky route key, when available

	// 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
}