Module score 

§4.3 score-field detection.

Given the parsed items list, identify a numeric field that should be treated as the score. Preference order:

1. Named candidates (in this order): score, rank, relevance, confidence, bm25, distance. The first candidate that resolves to a numeric value at the top level on the first item is chosen.
2. Single nested numeric: if no named candidate matches, walk the first item recursively. If exactly one path resolves to a numeric value, use it. More than one → no score detected with the fallback reason "multiple numeric fields, none named".
3. Top-level beats nested when multiple named candidates appear at different depths (the top-level candidate wins).

“No score detected” is a normal outcome, not an error — the caller falls back to grouping (§5).

Structs

ScoreDetection

Outcome of §4.3 score-field detection.

ScoreOptions

Tunable inputs for §4.3 score-field detection.

Functions

detect_score

§4.3: scan the items for a numeric score field.

detect_score_with_options

§4.3 score detection with caller-supplied named candidates.

validate_score_path

Validate a user-supplied --score=PATH.