selection

type Candidate struct {
	File          format.FileEntry
	PreferredMode string
	Signals       Signals
	AreaWeight    float64
	Area          string
}

type Decision struct {
	Path            string  `json:"path"`
	Area            string  `json:"area,omitempty"`
	Mode            Mode    `json:"mode"`
	Selected        bool    `json:"selected"`
	Score           float64 `json:"score"`
	Utility         float64 `json:"utility"`
	Tokens          int     `json:"tokens"`
	FullTokens      int     `json:"full_tokens"`
	SignatureTokens int     `json:"signature_tokens"`
	Role            string  `json:"role,omitempty"`
	RoleConfidence  float64 `json:"role_confidence,omitempty"`
	TaskRelevance   float64 `json:"task_relevance,omitempty"`
	Signals         Signals `json:"signals,omitempty"`
	Reason          string  `json:"reason"`
}

type Mode string

type Report struct {
	Result  Result
	Skipped []walker.SkippedItem
}

type Request struct {
	Budget    int
	MaxStates int    // zero uses the default sparse-DP state limit.
	Prompt    string // optional task text used to improve path relevance.
	// Tuning carries the optimizer's numeric knobs. The zero value means the
	// built-in defaults; config layers pass an explicit tuning to override.
	Tuning Tuning
}

type Result struct {
	Decisions  []Decision
	Selected   []format.FileEntry
	UsedTokens int
	Budget     int
}

type Signals struct {
	Recency      float64 `json:"recency,omitempty"`
	Churn        float64 `json:"churn,omitempty"`
	Centrality   float64 `json:"centrality,omitempty"`
	Role         float64 `json:"role,omitempty"`
	TestAffinity float64 `json:"test_affinity,omitempty"`
	// Distance is the import-graph hop count from a follow seed. It is zero
	// for ordinary selections and carried through to reports so the walk
	// that picked a file stays observable.
	Distance float64 `json:"distance,omitempty"`
}

type Tuning struct {
	BaseMin         float64
	BaseMax         float64
	RelevanceWeight float64
	PreferenceBonus float64
	SignatureBonus  float64
	SkipMultiplier  float64
	SigQualityMin   float64
	SigQualityMax   float64
	// TestTaskBoost raises test-file utility when the prompt is test-focused.
	TestTaskBoost float64
	// RetentionFloor is the minimum retention value at or above which a file
	// is guaranteed a slot under budget (its best affordable variant is
	// reserved first). Files below the floor compete through the DP.
	RetentionFloor float64
	// AreaDiminishing reduces utility for later files in the same area.
	AreaDiminishing float64
	// AreaBudgetShare is the default maximum fraction of the total budget one
	// area may consume when several distinct areas are present.
	AreaBudgetShare float64
	// AreaRoots maps directory prefixes to explicit area names. Longest
	// matching prefix wins; this lets repositories override inferred areas.
	AreaRoots map[string]string
	// Retention overrides the lang role defaults per role name (e.g.
	// "entrypoint"). Config takes priority over the lang default.
	Retention map[string]float64
	// SkipRoles are role names that automatic selection excludes before
	// optimization. An empty list uses the conservative built-in defaults.
	SkipRoles []string
}

type Variant struct {
	Mode    Mode
	Tokens  int
	Utility float64
	Reason  string
}