routing

type AffinityMode string

type AliasResolver struct {
	// contains filtered or unexported fields
}

type AttemptCandidate struct {
	Primary Primary
	// Key matches Primary.String() for exclusion maps.
	Key string
	// MarkedFirst is true when this candidate came from a [first]-annotated weighted branch.
	MarkedFirst bool
	// IsParallel is true when this candidate belongs to a parallel group (selector '!' arm).
	IsParallel bool
	// Handicap is the per-leg head-start delay for parallel routing (0 = no handicap).
	Handicap time.Duration
	// InterleavedRole labels thinker/executor candidates in thinker-aware weighted cycles.
	// It is RoleNone for non-thinker weighted selectors.
	InterleavedRole interleavedstate.Role
	// SelectorKey is the thinker-aware weighted selector key the candidate was planned from.
	// Empty for non-thinker weighted selectors.
	SelectorKey string
}

type AttemptGroup struct {
	Candidates []AttemptCandidate
	// NextThinkerCycle is the advanced thinker-aware weighted cycle cursor produced by
	// picking a thinker-aware weighted branch. It is nil for non-thinker weighted selectors
	// and for primary/parallel arms. Callers persist it when route selection becomes
	// authoritative so the next request in the same session continues from the next position.
	NextThinkerCycle *interleavedstate.CycleState
}

type BackendExecutionResolver interface {
	ResolveBackendExecution(backendID string) (class lipsdk.BackendExecutionClass, ok bool)
}

type BackendExecutionResolverFunc func(backendID string) (lipsdk.BackendExecutionClass, bool)

type CandidateAdmissionCheck struct {
	Call              lipapi.Call
	Invocation        lipapi.Invocation
	Candidate         AttemptCandidate
	BackendCaps       lipapi.BackendCaps
	TransportCaps     lipapi.BackendTransportCaps
	ReplaySupport     lipapi.ReasoningReplaySupport
	DialectSupport    lipapi.DialectSupport
	ProjectionTarget  lipapi.LegacyProjectionTarget
	TransportPolicy   lipapi.TransportFallbackPolicy
	RequireProjection bool
	Continuation      *ContinuationConstraint
}

type ContinuationConstraint struct {
	Lineage            lipcont.Lineage
	Requirements       lipapi.ProtocolRequirements
	NativeRequirements []lipcont.NativeRequirement
}

type FailoverAlt struct {
	Primary  *Primary
	Weighted *Weighted
	Parallel *Parallel
}

type GenerationSelectorValidator struct {
	Aliases                    *AliasResolver
	DefaultBackend             string
	KnownBackends              map[string]struct{}
	BackendExecutionResolver   BackendExecutionResolver
	ExecutionCompositionPolicy config.ExecutionCompositionPolicy
}

type ModelAliasRule struct {
	Pattern     string
	Replacement string
}

type ModelBinding struct {
	Kind   ModelBindingKind
	Native string // set for ExactCanonical and KnownNative
}

type ModelBindingKind int

type NativeModelResolver interface {
	ResolveModelBinding(backendID, model string) ModelBinding
}

type Parallel struct {
	Branches []ParallelBranch
}

type ParallelBranch struct {
	Target   Primary
	Handicap time.Duration
}

type PlanOptions struct {
	Excluded  map[string]struct{}
	Unhealthy map[string]struct{}
	// RequestSize is the current request size estimate used for per-leaf min/max context filters.
	// When unavailable, size filters fail open and do not exclude candidates.
	RequestSize RequestSizeEstimate
	Session     *SessionRoutingState
	// PreferredCandidateKeys hints expand order when keys are already eligible (design §12, advisory).
	PreferredCandidateKeys []string
	// StickyBackendID forces a currently bound backend instance ahead of normal weighted/failover selection
	// when at least one candidate for that backend is eligible in the current selector.
	StickyBackendID string
	// Rand supplies weighted-branch rolls. When nil, weighted selection uses a fixed-seeded
	// math/rand/v2 PCG stream (deterministic, not crypto-safe); inject for tests or concurrency-safe rolls.
	Rand        Rng
	IsRetryPath bool
	// ThinkerCycle is the persisted thinker-aware weighted cycle cursor for the current selector.
	// A zero-value (empty) state means no cycle has been established yet; the planner builds a
	// fresh cycle from the weighted branches and starts at position 0.
	ThinkerCycle interleavedstate.CycleState
	// SuppressThinker skips the thinker position during cycle advancement (continuation turns)
	// and returns deterministic no-eligible-route outcomes when no executor candidate remains.
	SuppressThinker bool
}

type Primary struct {
	// Backend is empty for model-only selectors. It may contain dots (e.g. openai.azure).
	Backend string
	// Model is the requested/logical identity (canonical or raw pass-through).
	// Route keys, affinity, catalog matching, traces, and diagnostics use Model.
	Model string
	// NativeModel is the request-bound backend wire id when the registry mapped
	// this leaf. Empty means unresolved pass-through (use Model at seams).
	// NativeModel must not appear in String()/exclusion keys.
	NativeModel string
	Params      url.Values
	Size        RequestSizeConstraint
	TTFTTimeout *time.Duration
}

type RequestSizeConstraint struct {
	MinContextTokens *int64
	MaxContextTokens *int64
}

type RequestSizeEstimate struct {
	Available bool
	Tokens    int64
	Basis     string
}

type Rng interface {
	Intn(n int) int
}

type RoutingScenarioSpec struct {
	ID               string
	InvariantSummary string
	TestName         string // exists in internal/core/routing/*_test.go
}

type Selector struct {
	Alternatives      []FailoverAlt
	GlobalTTFTTimeout *time.Duration
	Affinity          AffinityMode
}

type SessionRoutingState struct {
	FirstRequestConsumed bool
}

type UnsafeExecutionCompositionError struct {
	Composition string
	BackendID   string
	Class       lipsdk.BackendExecutionClass
	Policy      config.ExecutionCompositionPolicy
}

type Weighted struct {
	Branches []WeightedBranch
}

type WeightedBranch struct {
	Weight int
	// IsFirst marks a [first] annotation (only meaningful when not on retry path and session allows).
	IsFirst bool
	// IsThinker marks a [thinker] annotation; the branch produces a planning memo
	// in interleaved-thinking cycles. At most one thinker branch is allowed per
	// weighted group, and it cannot combine with [first] on the same branch.
	IsThinker bool
	// Target is the resolved primary for this branch. Zero when Parallel is set.
	Target Primary
	// Parallel, when non-nil, marks this branch as targeting an embedded parallel
	// executor group. Allowed only on the non-thinker branch of a thinker hybrid
	// weighted selector; the parser enforces that narrow shape. Target is zero in
	// that case. General weighted/parallel mixing remains rejected.
	Parallel *Parallel
}

type WrongBackendCanonicalError struct {
	Backend string
	Model   string
}