fix(meta_worker): let contents_* fixture workers opt out of unattached routing

2eb142d's contents_* catalogs re-declare main.double / vgi_sum / sequence (the
example catalog's classes), so MetaWorker found four declarers for an
attach-less main.double and raised "Cannot route", failing 44 client
round-trip / HTTP upload / resumable-scan tests.

New Worker class attribute route_unattached_calls (default True). MetaWorker's
_candidates_for considers only workers that allow it; attach routing is
unchanged. The four contents_* workers set it False, so they are reachable only
through their own attach and the example worker stays the unambiguous owner of
unattached calls. Object names are unchanged.

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

Author: Rusty Conover

tests/test_schema_scoped_functions.py

@@ -239,3 +239,40 @@ def test_an_unknown_name_reports_unknown_not_ambiguous(self) -> None:
         request = dataclasses.replace(self._request(None), function_name="no_such_function")
         with pytest.raises(ValueError, match="Unknown function"):
             meta._resolve_function(request)
+
+
+class TestAttachedOnlyWorkers:
+    """``route_unattached_calls = False`` keeps a sub-worker out of name routing.
+
+    The catalog_contents fixture catalogs re-declare ``main.double`` (the example
+    catalog's class). Without the opt-out an attach-less ``main.double`` call
+    would have four declarers and raise; with it the example worker stays the
+    sole owner, while an attach still reaches the fixture catalog.
+    """
+
+    @staticmethod
+    def _request(attach_opaque_data: bytes | None) -> BindRequest:
+        return BindRequest(
+            function_name="double",
+            arguments=Arguments(positional=()),
+            function_type=FunctionType.SCALAR,
+            input_schema=_INPUT_SCHEMA,
+            schema_path=["main"],
+            attach_opaque_data=attach_opaque_data,
+        )
+
+    def test_unattached_call_routes_to_the_routable_worker(self) -> None:
+        """Only the example worker is a candidate for an attach-less call."""
+        from vgi._test_fixtures.catalog_contents import CONTENTS_WORKERS
+
+        meta = MetaWorker([ExampleWorker(), *(w() for w in CONTENTS_WORKERS)])
+        assert meta._candidates_for("double", ["main"]) == [meta._workers[0]]
+        assert meta._resolve_function(self._request(None)) is not None
+
+    def test_attach_still_reaches_an_attached_only_worker(self) -> None:
+        """Opting out of name routing does not affect attach routing."""
+        from vgi._test_fixtures.catalog_contents import CATALOG_PROBE, ContentsProbeWorker
+
+        meta = MetaWorker([ExampleWorker(), ContentsProbeWorker()])
+        attach = meta._workers[1]._seal_attach_with_catalog(b"\x00" * 16, CATALOG_PROBE)
+        assert meta._maybe_worker_for_attach(attach) is meta._workers[1]

vgi/_test_fixtures/catalog_contents.py

@@ -26,7 +26,10 @@
 macros), split over two schemas (``main`` and ``extra``), so RPC accounting in
 ``vgi/test/sql/integration/catalog/catalog_contents*.test`` is deterministic.
 Served by ``vgi-fixture-worker`` and ``vgi-fixture-http`` (MetaWorker), so the
-same tests run over every transport.
+same tests run over every transport. Their functions re-use the example
+catalog's classes (``main.double`` …), so the workers set
+``route_unattached_calls = False``: they are reachable only through their own
+attach, and an unattached ``main.double`` still routes to the example worker.
 """
 
 from __future__ import annotations
@@ -155,6 +158,8 @@ def catalog_attach(self, **kwargs: Any) -> CatalogAttachResult:
 class ContentsProbeWorker(Worker):
     """Serves ``contents_probe``."""
 
+    route_unattached_calls = False
+
     catalog_interface = ContentsProbeCatalog
     catalog_name = CATALOG_PROBE
     catalog = _CATALOG_PROBE
@@ -163,6 +168,8 @@ class ContentsProbeWorker(Worker):
 class ContentsBrokenWorker(Worker):
     """Serves ``contents_broken``."""
 
+    route_unattached_calls = False
+
     catalog_interface = ContentsBrokenCatalog
     catalog_name = CATALOG_BROKEN
     catalog = _CATALOG_BROKEN
@@ -171,6 +178,8 @@ class ContentsBrokenWorker(Worker):
 class ContentsLegacyWorker(Worker):
     """Serves ``contents_legacy``."""
 
+    route_unattached_calls = False
+
     catalog_interface = ContentsLegacyCatalog
     catalog_name = CATALOG_LEGACY
     catalog = _CATALOG_LEGACY
@@ -230,6 +239,8 @@ def catalog_detach(self, *, attach_opaque_data: AttachOpaqueData) -> None:
 class ContentsMemoryWorker(Worker):
     """Serves ``contents_memory``."""
 
+    route_unattached_calls = False
+
     catalog_interface = ContentsMemoryCatalog
     catalog_name = CATALOG_MEMORY
 

vgi/meta_worker.py

@@ -239,13 +239,18 @@ def _maybe_worker_for_attach(self, attach_opaque_data: bytes | None) -> Worker |
         return self._workers[idx]
 
     def _candidates_for(self, function_name: str, schema_path: list[str] | None) -> list[Worker]:
-        """Every sub-worker declaring ``function_name``, most specific first."""
+        """Every sub-worker declaring ``function_name``, most specific first.
+
+        Only sub-workers that accept unattached calls (``route_unattached_calls``)
+        are candidates; the rest are reachable solely through their own attach.
+        """
+        workers = [w for w in self._workers if type(w).route_unattached_calls]
         if schema_path is not None:
             key = (schema_path_key(schema_path), function_name)
-            scoped = [w for w in self._workers if key in type(w)._build_schema_registry()]
+            scoped = [w for w in workers if key in type(w)._build_schema_registry()]
             if scoped:
                 return scoped
-        return [w for w in self._workers if function_name in type(w)._build_registry()]
+        return [w for w in workers if function_name in type(w)._build_registry()]
 
     def _worker_for_unattached(self, function_name: str, schema_path: list[str] | None) -> Worker | None:
         """Pick a sub-worker for a call that carries no usable attach.

vgi/worker.py

@@ -1145,6 +1145,9 @@ class Worker:
             to use the auto-generated default (or disable the catalog).
         catalog_name: Name of the default catalog; set to ``None`` to disable the
             default catalog.
+        route_unattached_calls: Whether a [`MetaWorker`][]
+            may route a call carrying no attach to this worker by function name.
+            ``False`` makes the worker reachable only through its own catalog.
         catalog: Optional declarative `[`Catalog`][]` describing the worker's
             schemas, tables, and views.
     """
@@ -1158,6 +1161,12 @@ class Worker:
     protocol_class: ClassVar[type[VgiProtocol]] = VgiProtocol  # type: ignore[type-abstract]
     catalog_interface: type[CatalogInterface] | None = None
     catalog_name: str | None = "functions"  # Set to None to disable default catalog
+    # Whether a MetaWorker may route a call that carries no attach (a
+    # non-catalog caller) to this worker by function name. A worker whose
+    # functions are only meant to be reached through its own attached catalog
+    # sets this False, so re-declaring a name another sub-worker owns does not
+    # make that name ambiguous for unattached callers.
+    route_unattached_calls: ClassVar[bool] = True
     catalog: Catalog | None = None
     _registry: dict[str, list[type[Function]]] | None = None
     # (lowercased structural schema path, function name) -> classes declared there.