Cap per-source recall so one deep decision cannot flood the candidate pool

Canfield exposed a recall-stage monopoly: its 94 paragraphs filled both
retrievers' CANDIDATES slices on device-search queries, so the result-stage
SOURCE_CAP deferred surplus chunks with nothing left to promote and
_ensure_primary found no statute in the pool at all. _capped_top now limits
each capped source (_source_key: a decision, a memorandum) to RECALL_CAP
chunks per retriever slice, with the semantic ranking over-fetching 4x so
other sources backfill the freed slots.

RECALL_CAP=20, env-overridable (CANLEX_RECALL_CAP), swept 2026-07-10 over
{12,16,20,24} on the 159-Q eval: 12 and 20 tie at 0.80/0.94/0.97/0.99/0.87
(4 misses) -- above the uncapped baseline (0.79/0.93/0.97/0.99/0.87, 5
misses); 20 chosen as the lightest touch. The device-search canary now
returns a spread of Canfield/Pike/Fearon instead of one decision six times,
and the PCMLTFA canary keeps its legitimate multi-decision cluster while
surfacing s. 18 and s. 20. Four unit tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

canlex/index.py

@@ -42,6 +42,22 @@ BACKMATTER_PENALTY = float(os.environ.get("CANLEX_BACKMATTER_PENALTY", "0.004"))
                     # (memoranda, letters of understanding) vs its numbered articles
                     # (sweep-tuned 2026-05-23 from 0.008 -> 0.004)
 SOURCE_CAP = 2      # max chunks one case or memorandum may contribute
+RECALL_CAP = int(os.environ.get("CANLEX_RECALL_CAP", "20"))
+                    # max chunks one capped source (anything _source_key keys:
+                    # a decision, a memorandum) may contribute to EACH
+                    # retriever's CANDIDATES slice at the recall stage. Without
+                    # it, a deep decision whose every paragraph matches a
+                    # specific query (Canfield: 94 paragraphs on device border
+                    # searches) fills the entire fusion pool, so the result-
+                    # stage SOURCE_CAP defers its surplus with nothing left to
+                    # promote and _ensure_primary finds no statute to pull in.
+                    # Generous by design: SOURCE_CAP=2 governs display; this
+                    # only has to leave room for other sources to survive
+                    # recall. Uncapped sources (_source_key None) are unlimited.
+                    # Swept 2026-07-10 over {12,16,20,24} on the 159-Q eval:
+                    # 12 and 20 tie at 0.80/0.94/0.97/0.99/0.87 (4 misses),
+                    # both above the uncapped baseline; 20 chosen as the
+                    # lightest-touch winner (24 regresses Hit@3/@5).
 APPENDIX_CAP = 3    # max referenced appendices co-surfaced into a result set
 
 # Primary instruments -- enacted law, collective agreements, the NJC directives
@@ -312,7 +328,10 @@ class LegislationIndex:
     def _semantic_ranking(self, query):
         qv = self.embedder.encode_query(query)
         sims = self.vectors @ qv
-        order = self._np.argsort(sims)[::-1][:CANDIDATES]
+        # Over-fetch 4x: the recall-stage source cap (_capped_top) drops the
+        # surplus chunks of any one deep source, and the extra depth is what
+        # lets other sources backfill the freed CANDIDATES slots.
+        order = self._np.argsort(sims)[::-1][:CANDIDATES * 4]
         # The top cosine similarity doubles as a corpus-coverage signal: a query
         # the corpus cannot answer has no passage close to it.
         return [int(i) for i in order], float(sims.max())
@@ -354,6 +373,25 @@ class LegislationIndex:
             return ("memorandum", c["section"])   # act_code is a shared constant
         return (doc_type, c["act_code"])          # one decision, keyed by citation
 
+    def _capped_top(self, ordered):
+        """The first CANDIDATES indices of `ordered`, keeping at most
+        RECALL_CAP per capped source. The recall-stage counterpart of
+        _diversify: where _diversify reorders the fused candidates so a deep
+        source cannot monopolise the visible results, this stops that source
+        from monopolising the candidate pool itself -- skipped surplus frees
+        slots that later, weaker-ranked chunks of OTHER sources backfill."""
+        out, counts = [], defaultdict(int)
+        for idx in ordered:
+            key = self._source_key(idx)
+            if key is not None:
+                counts[key] += 1
+                if counts[key] > RECALL_CAP:
+                    continue
+            out.append(idx)
+            if len(out) >= CANDIDATES:
+                break
+        return out
+
     def _diversify(self, ordered):
         """Reorder so no single case, memorandum, agreement or directive can
         monopolise the results: once a source has contributed SOURCE_CAP chunks,
@@ -490,11 +528,12 @@ class LegislationIndex:
         confidence = None
         fused = defaultdict(float)
         bm25 = self._bm25_scores(expanded)
-        for rank, idx in enumerate(sorted(bm25, key=bm25.get, reverse=True)[:CANDIDATES]):
+        for rank, idx in enumerate(self._capped_top(
+                sorted(bm25, key=bm25.get, reverse=True))):
             fused[idx] += 1.0 / (RRF_K + rank)
         if self.semantic:
             sem_order, confidence = self._semantic_ranking(expanded)
-            for rank, idx in enumerate(sem_order):
+            for rank, idx in enumerate(self._capped_top(sem_order)):
                 fused[idx] += W_SEM / (RRF_K + rank)
 
         # Ensure explicitly-referenced sections are retrieved even if recall

tests/test_index.py

@@ -10,8 +10,8 @@ or reranker are loaded.
 import unittest
 
 from canlex.index import (
-    LegislationIndex, SOURCE_CAP, APPENDIX_CAP, tokenize, _section_refs,
-    _provision_units,
+    LegislationIndex, SOURCE_CAP, APPENDIX_CAP, RECALL_CAP, CANDIDATES,
+    tokenize, _section_refs, _provision_units,
 )
 
 
@@ -207,6 +207,47 @@ class DocTypeFlagTests(unittest.TestCase):
         self.assertEqual(self.idx._note_tokens[5], set(tokenize("Importing goods")))
 
 
+class CappedTopTests(unittest.TestCase):
+    """_capped_top limits how many chunks one capped source can contribute to
+    a retriever's CANDIDATES slice, so a deep decision cannot monopolise the
+    fusion pool before the result-stage diversity cap even runs."""
+
+    def test_deep_source_is_capped_and_others_backfill(self):
+        # RECALL_CAP+5 chunks of one decision ranked first, then legislation.
+        n_case = RECALL_CAP + 5
+        chunks = [chunk(doc_type="caselaw", act_code="2020 ABCA 383",
+                        id=f"canlii-x-{i}") for i in range(n_case)]
+        chunks += [chunk(doc_type="legislation", section=str(i),
+                         id=f"leg-{i}") for i in range(10)]
+        idx = bare_index(chunks)
+        out = idx._capped_top(range(len(chunks)))
+        n_kept = sum(1 for i in out
+                     if idx.chunks[i]["doc_type"] == "caselaw")
+        self.assertEqual(n_kept, RECALL_CAP)          # surplus dropped
+        self.assertEqual(sum(1 for i in out
+                             if idx.chunks[i]["doc_type"] == "legislation"),
+                         10)                          # others backfilled
+
+    def test_uncapped_sources_are_unlimited(self):
+        chunks = [chunk(doc_type="legislation", section=str(i), id=f"l-{i}")
+                  for i in range(RECALL_CAP + 10)]
+        idx = bare_index(chunks)
+        out = idx._capped_top(range(len(chunks)))
+        self.assertEqual(len(out), RECALL_CAP + 10)   # no cap applied
+
+    def test_respects_candidates_ceiling(self):
+        chunks = [chunk(doc_type="legislation", section=str(i), id=f"l-{i}")
+                  for i in range(CANDIDATES + 20)]
+        idx = bare_index(chunks)
+        self.assertEqual(len(idx._capped_top(range(len(chunks)))), CANDIDATES)
+
+    def test_order_preserved(self):
+        chunks = [chunk(doc_type="legislation", section=str(i), id=f"l-{i}")
+                  for i in range(5)]
+        idx = bare_index(chunks)
+        self.assertEqual(idx._capped_top([3, 1, 4, 0, 2]), [3, 1, 4, 0, 2])
+
+
 class CosurfaceAppendixTests(unittest.TestCase):
     """_cosurface_appendices pulls a directive appendix into the result set
     when a directive result cites it but retrieval missed it."""