quality

type Candidate struct {
	// Index lets the caller map the choice back to its own slice.
	Index  int
	Format string
	// Score is the search match confidence (0-100). It is a gate applied by
	// the caller, and a late tie-break here; quality rank comes first.
	Score float64
	Size  int64
}

type CandidateDecision struct {
	Candidate Candidate
	Decision  Decision
}

type Decision struct {
	// Accept reports whether the candidate should be grabbed.
	Accept bool
	// Upgrade is set when Accept is true because the candidate would replace
	// an existing, lower-ranked file.
	Upgrade bool
	// Rank is the candidate's position in the profile ranking (0 = best), or
	// -1 when the format is not in the profile.
	Rank int
	// Reason is a short human-readable explanation, suitable for logs and for
	// the "last result" line on a wanted item.
	Reason string
}

type Profile struct {
	ID        int64
	Name      string
	MediaType string
	// Ranking lists the grabbable formats, best first. Formats absent from the
	// ranking are not grabbable under this profile.
	Ranking []string
	// Cutoff is the format at which upgrading stops. Empty or unknown means
	// the best format in the ranking.
	Cutoff string
	// UpgradesAllowed enables replacing an existing file with a better format.
	UpgradesAllowed bool
	// PreferredSizeMin/Max (bytes) are a soft tie-break between releases of
	// the same format. Zero means no preference on that bound.
	PreferredSizeMin int64
	PreferredSizeMax int64
}