recall

type NoteTrace struct {
	ID, Title                     string
	Hits                          []TermHit
	Raw, Final                    float64 // pre-boost / post-boost score
	Lesson, ProjectMatch, Expired bool    // which boosts fired
	Excluded                      string  // "" | "no-match" | "precision-floor" | "tail-trim" | "limit"
	// StrongTerms is the note's strong-bag (title/tags/description) vocabulary
	// after stemming — only populated for an ExplainNote target. It's the
	// actionable half of "why is my note missing": the words it WOULD need to
	// share with the query.
	StrongTerms []string
}

type Result struct {
	Note         *note.Note
	Score        int
	Lesson       bool
	ProjectMatch bool // note belongs to the caller's project (soft ranking boost applied)
	Expired      bool // note.Note.Expired() as of ranking time — valid_until has passed
	// Faded/DecayFactor: relevance decay as of ranking time (memory-dynamics
	// spec §3). Faded = aged past one half-life un-reconfirmed; DecayFactor is
	// the multiplier applied to the ranking score (1.0 = no decay). Like the
	// expired flag: a signal to doubt, never a filter.
	Faded       bool
	DecayFactor float64
	// Confidence is the PRE-BOOST score over the best score this query could
	// possibly award (see fMax below) — comparable across queries and store
	// sizes, unlike Score, which is IDF-scaled and therefore query-dependent.
	// Boosts (lesson/project/expired) are deliberately excluded: they express
	// preference, not evidence, and folding them in would let a thinly-matched
	// lesson print as confident — the exact promotion pathology the precision
	// floor already fights. Matched/QueryTerms are the raw coverage fraction
	// (m/n query words that hit at all), shown alongside the tier because a
	// tier alone hides *how much* of the query a note actually covers.
	Confidence float64
	Matched    int
	QueryTerms int
}

type TermHit struct {
	Term    string  // stemmed query word
	Concept string  // synonym-group id ("g0"…), or the word itself if ungrouped
	Where   string  // "strong-exact" | "strong-syn" | "weak-exact" | "weak-syn" | ""
	Base    float64 // 4, 2, 2, 1, or 0 — matches Where
	IDF     float64
}

type Trace struct {
	QueryTerms  []string // stemmed, sorted — the scorer's actual fixed iteration order
	NumNotes    int
	FloorActive bool
	TargetID    string // set by ExplainNote; empty for ExplainProject
	Notes       []NoteTrace
}