[flyinprogrammer]

Closes #310

Summary

A small tree ensemble rescales each candidate's boosted score using signals the ranking stage already computes. It's evaluated in numpy from a packaged JSON file, so there's no new runtime dependency.

 search(query, …)
-  retrieve, fuse, boost                    # inline
-  rerank_topk(boosted)
+  signals = score_candidates(query, …)     # same retrieval/fusion/boosts, returns RankingSignals
+  scores = signals.boosted
+  if load_ranker() is not None:            # ranking/ranker.json; SEMBLE_LEARNED_RANKER=0 disables
+    scores = boosted × exp(ranker.predict(ranking_features(signals)))
+  rerank_topk(scores)                      # path penalties + file saturation, unchanged

 src/semble/ranking/
 ├── boosting.py        # + query_boost_deltas (stem/definition parts, for features); apply_query_boost unchanged
+├── learned.py         # RankingSignals, 21 features, numpy TreeEnsemble, load_ranker
+└── ranker.json        # 150 trees × 7 leaves, 69 KB
 benchmarks/
+└── train_ranker.py    # LightGBM via `uv run --with lightgbm` (never a dependency); --cv for leave-one-repo-out

• Features: list ranks and scores; fused rank and score; file, stem and definition boost amounts; path penalty; file shape (chunks per file, whether this is the file's best chunk, path depth).
• Training: LambdaRank, starting from the current boosted score, so an empty model reproduces today's ranking. Only the best-ranked chunk per annotated target is labelled relevant.

Evidence

• Off switch is exact: with SEMBLE_LEARNED_RANKER=0, all 1,251 benchmark queries score exactly as on main.

• Exported model matches LightGBM: the numpy evaluator differs from LightGBM's predictions by at most 3e-15 (checked by train_ranker.py before writing).

• Held-out quality:

  Evaluation	NDCG@10	Δ	95% CI (by repo)
  Benchmark, leave-one-repo-out (train_ranker.py --cv)	0.8550 → 0.8627	+0.78	[+0.36, +1.19]
  Commit-message queries (Benchmark: add a commit-message query set so ranking changes aren't tuned to the annotations' style #301): 840 from 21 repos, trained on the other 42 repos' benchmark queries	0.7637 → 0.7721	+0.84	[+0.40, +1.30]

• Latency (run_benchmark, M5 Max): median query 1.3 ms → 3.1 ms, 95th percentile 6.0 → 7.7 ms. Indexing is unchanged.

• Tests: new tests/test_learned_ranker.py covers the evaluator on a hand-built tree, feature construction, score rescaling, and that the packaged model matches FEATURES and can be disabled. make test 395 passed; make lint and make typecheck clean.

Merge Danger

Door: two-way

SEMBLE_LEARNED_RANKER=0 or a revert restores today's ranking exactly, and no index or cache format changes.

Blast Radius: ranking

• What changes: result order for every reranked query, and about 2 ms more per query. Docs search (rerank=False) is untouched.
• Maintenance: ranker.json encodes the current ranking signals. Whenever boosting.py, penalties.py or the fusion changes, it should be retrained (uv run --with lightgbm python -m benchmarks.train_ranker), including if feat: Strengthen the same-file saturation decay #306, feat: Rank symbol queries with BM25 only #308 or feat: Lightly stem BM25 tokens #311 merge.