Pull the topically-on-target primary instrument into the visible top

The legislation guarantee was named for what it did 6 months ago and had
fallen behind: it ensured 'some legislation' showed up in top_k by
fusion rank, in a top_k that with the eval default of 20 always already
contained incidental legislation, so the guarantee never fired even
when the GOVERNING provision was buried at rank 10+. And when it did
fire it picked by fusion rank, so a query about 'seize currency' lifted
PCMLTFA s.20 ('Report to President') over PCMLTFA s.18 ('Seizure and
forfeiture').

Renamed to _ensure_primary, now:

- Operates on a fixed visible window of min(top_k, 5), so a top_k=20
eval still gets the right Act provision pulled into the top 5
where the user actually looks.
- Counts all four primary instrument doc_types (legislation,
agreement, directive, delegation), so an FB-Agreement query that
surfaces only FPSLREB case law gets the agreement article promoted
too.
- Picks the candidate to promote by title-match score against the
query, not raw fusion rank -- so a topical question gets the
section about the topic, not a tangentially-ranked section that
happened to score higher on other vocabulary.
- Mirrors the fusion-stage hierarchy preferences (Act over
regulation, numbered articles over agreement back-matter) as
tiebreaks, so when IRPA s.112 and IRPR s.160 both have the
marginal note 'Application for protection' the Act wins.

141-question eval: Hit@1 0.79 / Hit@3 0.96 / Hit@5 0.98 / Hit@10 0.99
/ MRR 0.87 (vs pre-fix 0.79 / 0.93 / 0.96 / 0.98 / 0.87 -- Hit@3 +0.03,
Hit@5 +0.02, Hit@10 +0.01; 6 misses -> 3). IRPA s.112 #13->#2,
Sch-98.03 #6->#2, PCMLTFA s.12 #17->#2, PCMLTFA s.18 #10->#3.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

canlex/index.py

@@ -332,21 +332,58 @@ class LegislationIndex:
             (kept if counts[key] <= SOURCE_CAP else deferred).append(idx)
         return kept + deferred
 
-    def _ensure_legislation(self, ordered, top_k):
-        """Guarantee the governing statute is surfaced: when the natural top_k is
-        monopolised by case law or memoranda, pull the best legislation results
-        up to just below the top hit, displacing the lowest-ranked secondary
-        sources. The single best match is always kept in place."""
+    def _ensure_primary(self, ordered, top_k, q_tokens):
+        """Guarantee the governing primary instrument is surfaced: when the
+        natural top_k is monopolised by case law or D-memoranda that interpret
+        a statute, pull the most topically-on-target Act/agreement/directive/
+        delegation section into the top_k, displacing the lowest-ranked
+        secondary sources. The single best match is always kept in place.
+
+        Two changes from the older 'ensure_legislation' guarantee: (i) all
+        primary instruments count, not only legislation -- so an FB-Agreement
+        query that surfaces only FPSLREB case law gets the agreement article
+        pulled in too; (ii) the candidate to promote is chosen by title-match
+        against the query (the section whose marginal_note covers the most of
+        the query's distinctive vocabulary), not by raw fusion rank. The
+        fusion rank surfaces tangentially-on-topic sections that share the
+        Act's general vocabulary; the title-match scorer surfaces the section
+        actually about the topic ('Seizure and forfeiture' over 'Report to
+        President' for a 'seize currency' query)."""
         if top_k < 3:
             return ordered
-        def is_leg(i):
-            return self.chunks[i].get("doc_type", "legislation") == "legislation"
+        def is_primary(i):
+            return self.chunks[i].get("doc_type", "legislation") in PRIMARY_DOC_TYPES
         top, rest = ordered[:top_k], ordered[top_k:]
-        need = 2 - sum(1 for i in top if is_leg(i))
+        need = 2 - sum(1 for i in top if is_primary(i))
         if need <= 0:
             return ordered
-        promote = [i for i in rest if is_leg(i)][:need]
-        drop = [i for i in reversed(top) if not is_leg(i)][:len(promote)]
+        primary_in_rest = [i for i in rest if is_primary(i)]
+        if not primary_in_rest:
+            return ordered
+        if q_tokens:
+            def title_score(idx):
+                note_tokens = self._note_tokens[idx]
+                if not note_tokens:
+                    return 0.0
+                matched = sum(self.idf.get(t, 0.0)
+                              for t in note_tokens if t in q_tokens)
+                total = sum(self.idf.get(t, 0.0) for t in note_tokens) or 1.0
+                score = matched * matched / total
+                # Mirror the fusion-stage hierarchy preferences for tiebreaks:
+                # the governing Act beats its regulation, and numbered
+                # agreement articles beat their back-matter, when both have
+                # identical titles (e.g. IRPA s. 112 and IRPR s. 160 both
+                # marginal-noted 'Application for protection').
+                if self._is_regulation[idx]:
+                    score -= REG_PENALTY
+                if self._is_backmatter[idx]:
+                    score -= BACKMATTER_PENALTY
+                return score
+            # Sort by title-match descending, then by original fusion order as
+            # a tiebreak (stable sort: keep the original rest order).
+            primary_in_rest.sort(key=title_score, reverse=True)
+        promote = primary_in_rest[:need]
+        drop = [i for i in reversed(top) if not is_primary(i)][:len(promote)]
         if not drop:
             return ordered
         promote = promote[:len(drop)]
@@ -511,9 +548,14 @@ class LegislationIndex:
                 pinned_set = set(pinned)
                 candidates = pinned + [i for i in candidates if i not in pinned_set]
 
-        # Cap one-source monopolies, then guarantee the statute is represented.
+        # Cap one-source monopolies, then guarantee a primary instrument
+        # (statute/agreement/directive/delegation) on the topic is represented.
+        # The guarantee operates on a fixed visible window (5), not the full
+        # top_k -- with top_k=20 (the eval default) the larger window almost
+        # always contains incidental legislation, so the guarantee never fires
+        # even when the GOVERNING provision is buried at rank 10+.
         candidates = self._diversify(candidates)
-        candidates = self._ensure_legislation(candidates, top_k)
+        candidates = self._ensure_primary(candidates, min(top_k, 5), q_tokens)
 
         top = self._cosurface_appendices(candidates[:top_k])
         highlights = self._highlight(query, top)