perf(core): define bounded reference search

tests/test_reference_options.py

@@ -10,6 +10,10 @@ from govoplan_core.core.access import (
     UserRef,
 )
 from govoplan_core.core.references import (
+    CAPABILITY_ACCESS_REFERENCE_OPTIONS,
+    ReferenceOption,
+    ReferenceSearchPage,
+    access_scope_reference_page,
     access_scope_reference_options,
     validate_access_scope_reference,
 )
@@ -84,6 +88,38 @@ class _Registry:
         return self.directory if self.has_capability(name) else None
 
 
+class _ReferenceProvider:
+    def __init__(self) -> None:
+        self.requests = []
+
+    def search_reference_options(self, session, principal, *, request):
+        del session, principal
+        self.requests.append(request)
+        return ReferenceSearchPage(
+            options=(
+                ReferenceOption(
+                    value="account-1",
+                    label="Ada",
+                    kind="user",
+                    source_module="access",
+                ),
+            ),
+            next_cursor="offset:1",
+            has_more=True,
+        )
+
+
+class _ProviderRegistry:
+    def __init__(self) -> None:
+        self.provider = _ReferenceProvider()
+
+    def has_capability(self, name):
+        return name == CAPABILITY_ACCESS_REFERENCE_OPTIONS
+
+    def capability(self, name):
+        return self.provider if self.has_capability(name) else None
+
+
 class ReferenceOptionTests(unittest.TestCase):
     def setUp(self) -> None:
         self.principal = SimpleNamespace(
@@ -168,6 +204,34 @@ class ReferenceOptionTests(unittest.TestCase):
         self.assertEqual("account-1", options[0].value)
         self.assertEqual("core", options[0].source_module)
 
+    def test_bounded_provider_receives_normalized_search_and_retains_stale_selection(self) -> None:
+        registry = _ProviderRegistry()
+
+        page = access_scope_reference_page(
+            registry,
+            self.principal,
+            scope_type="user",
+            query="  Ada  ",
+            selected_values=("removed-account",),
+            limit=500,
+            cursor="offset:20",
+            administrative=True,
+            session=object(),
+        )
+
+        request = registry.provider.requests[0]
+        self.assertEqual("ada", request.query)
+        self.assertEqual(200, request.limit)
+        self.assertEqual("offset:20", request.cursor)
+        self.assertTrue(request.context["administrative"])
+        self.assertEqual(
+            ["account-1", "removed-account"],
+            [option.value for option in page.options],
+        )
+        self.assertEqual("unavailable", page.options[1].availability)
+        self.assertTrue(page.has_more)
+        self.assertEqual("offset:1", page.next_cursor)
+
 
 if __name__ == "__main__":
     unittest.main()