Address review: document structural-set tie-breaking, add no-lookup formatter test

Author: JSv4

opencontractserver/mcp/tests/test_mcp.py

@@ -7265,6 +7265,16 @@ def test_structural_passage_resolves_document_slug(self):
         self.assertEqual(hit["document_slug"], self.document.slug)
         self.assertEqual(hit["document_title"], self.document.title)
 
+    def test_structural_passage_without_lookup_returns_none_slug(self):
+        """Without a lookup the formatter preserves the old null-slug behaviour."""
+        from opencontractserver.mcp.formatters import format_search_passage
+
+        result = format_search_passage(
+            self.struct_ann, similarity_score=None, struct_doc_lookup=None
+        )
+        self.assertIsNone(result["document_slug"])
+        self.assertEqual(result["document_title"], "")
+
 
 class MCPGetCorpusInfoLabelsTest(TestCase):
     """get_corpus_info surfaces only labels actually used on annotations (#1861)."""

opencontractserver/mcp/tools.py

@@ -427,6 +427,9 @@ def search_corpus(
                 .order_by("structural_annotation_set_id", "slug")
                 .distinct()
             ):
+                # If a structural set maps to multiple corpus documents, pick
+                # the first alphabetically by slug — deterministic (guaranteed
+                # by the order_by above); the edge case is rare in practice.
                 struct_doc_lookup.setdefault(set_id, (slug, title or ""))
 
         formatted.extend(