feat(selection): expose ranked_candidates(); refactor select() onto it

Per docs/superpowers/plans/2026-06-04-experience-simulator.md Task 1.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

hef/selection.py

@@ -58,6 +58,38 @@ def candidates_for_mode(records, mode: str, pool_size: int) -> list[Record]:
 from typing import Optional
 
 
+def ranked_candidates(
+    records,
+    coord: Coordinate,
+    mode: str,
+    *,
+    pool_size: int = 4,
+    weights: Weights = Weights(),
+    approved_only: bool = False,
+) -> list[tuple[Record, float]]:
+    """Mode-eligible records sorted nearest-first, each paired with its distance.
+
+    Applies the same approved_only filter and 'av' pool fallback as select(),
+    then returns up to pool_size nearest (record, distance) pairs. This is the
+    single source of truth for "the pool"; select() picks from it.
+    """
+    if mode not in CONTENT_MODES:
+        raise ValueError(
+            f"ranked_candidates expects a content mode {sorted(CONTENT_MODES)}, "
+            f"got {mode!r}"
+        )
+    pool = records
+    if approved_only:
+        pool = [r for r in pool if r.review_status == "approved"]
+    candidates = candidates_for_mode(pool, mode, pool_size)
+    ranked = sorted(
+        candidates,
+        key=lambda r: (distance(coord, record_coordinate(r), weights), r.id),
+    )
+    nearest = ranked[:pool_size]
+    return [(r, distance(coord, record_coordinate(r), weights)) for r in nearest]
+
+
 def select(
     records,
     coord: Coordinate,
@@ -82,17 +114,17 @@ def select(
         )
     if mode == "none":
         return None
-    pool = records
-    if approved_only:
-        pool = [r for r in pool if r.review_status == "approved"]
-    candidates = candidates_for_mode(pool, mode, pool_size)
-    if not candidates:
-        return None
-    ranked = sorted(
-        candidates,
-        key=lambda r: (distance(coord, record_coordinate(r), weights), r.id),
+    ranked = ranked_candidates(
+        records,
+        coord,
+        mode,
+        pool_size=pool_size,
+        weights=weights,
+        approved_only=approved_only,
     )
-    nearest = ranked[:pool_size]
+    if not ranked:
+        return None
+    nearest = [r for r, _ in ranked]
     if rng is None:
         return nearest[0]
     return rng.choice(nearest)