vgi-python 0.38.1__py3-none-any.whl → 0.40.0__py3-none-any.whl

vgi/_test_fixtures/catalog_contents.py

@@ -0,0 +1,336 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Small catalogs for the ``catalog_contents`` RPC.
+
+The same static two-schema catalog is served under three names, differing only
+in how they answer ``catalog_contents`` (see ``vgi/docs/catalog_contents.md``):
+
+``contents_probe``
+    Advertises ``supports_catalog_contents`` and serves it normally (the
+    ``ReadOnlyCatalogInterface`` default: version-frozen, no etag, and cached
+    by the worker). A client loads it in one RPC.
+``contents_broken``
+    Advertises ``supports_catalog_contents`` but its ``catalog_contents``
+    raises. A client must fall back to ``catalog_schemas`` plus the per-schema
+    ``catalog_schema_contents_*`` RPCs and still see the whole catalog.
+``contents_legacy``
+    Does not advertise it, like an older worker. A client must never call
+    ``catalog_contents`` and must use the per-schema RPCs.
+
+Three DDL-capable ``InMemoryCatalog`` catalogs (version not frozen) advertise
+it too. Each ATTACH gets its own empty catalog (one ``main`` schema), so tests
+sharing a warm worker never see each other's objects:
+
+``contents_memory``
+    Reports ``catalog_version`` 0 ("unknown") and no etag. Exercises the
+    client's version-0 rule: the first load of an attach uses
+    ``catalog_contents``, but reloads (the client clears a version-0 catalog
+    at every transaction start) use the lazy per-schema RPCs instead.
+``contents_reval``
+    A revalidating catalog with a cheap validator: the etag is
+    ``"gen-<n>"``, where ``n`` is the catalog version, bumped by every DDL.
+    A matching ``if_none_match`` answers ``not_modified`` without building
+    anything. The client revalidates with it at transaction start instead of
+    polling ``catalog_version``.
+``contents_hash``
+    Returns no etag of its own but sets ``catalog_contents_etag =
+    "content-hash"``: the worker builds the snapshot on every call and uses
+    its SHA-256 as the etag, answering ``not_modified`` when it matches.
+
+The static catalog holds every kind the client seeds from ``catalog_contents``
+at least once (tables, a view, scalar / aggregate / table functions, scalar and
+table 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. Their functions
+re-use the example catalog's classes (``main.double`` ...), so every worker
+here sets ``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
+
+import uuid
+from dataclasses import replace
+from typing import Any
+
+import pyarrow as pa
+
+from vgi._test_fixtures.aggregate.basic import SumFunction
+from vgi._test_fixtures.catalog import CatalogData, InMemoryCatalog, SchemaData
+from vgi._test_fixtures.scalar.arithmetic import DoubleFunction
+from vgi._test_fixtures.table.sequence import SequenceFunction
+from vgi.arguments import Arguments
+from vgi.catalog import (
+    AttachOpaqueData,
+    Catalog,
+    CatalogAttachResult,
+    CatalogContentsResult,
+    CatalogInfo,
+    Macro,
+    MacroType,
+    ReadOnlyCatalogInterface,
+    Schema,
+    SchemaInfo,
+    Table,
+    View,
+)
+from vgi.worker import Worker
+
+CATALOG_PROBE = "contents_probe"
+CATALOG_BROKEN = "contents_broken"
+CATALOG_LEGACY = "contents_legacy"
+CATALOG_MEMORY = "contents_memory"
+CATALOG_REVAL = "contents_reval"
+CATALOG_HASH = "contents_hash"
+
+BROKEN_MESSAGE = "contents_broken: catalog_contents deliberately fails"
+
+
+def _catalog(name: str) -> Catalog:
+    return Catalog(
+        name=name,
+        default_schema="main",
+        comment=f"catalog_contents test catalog ({name})",
+        schemas=[
+            Schema(
+                path=["main"],
+                comment="Every object kind",
+                tables=[
+                    Table(
+                        name="ten",
+                        function=SequenceFunction,
+                        arguments=Arguments(positional=(pa.scalar(10),)),
+                        comment="Integers 0..9",
+                    ),
+                ],
+                views=[View(name="answer", definition="SELECT 42 AS answer", comment="One row")],
+                functions=[DoubleFunction, SumFunction, SequenceFunction],
+                macros=[
+                    Macro(
+                        name="contents_triple",
+                        macro_type=MacroType.SCALAR,
+                        parameters=["x"],
+                        definition="x * 3",
+                        comment="Triple a value",
+                    ),
+                    Macro(
+                        name="contents_range",
+                        macro_type=MacroType.TABLE,
+                        parameters=["n"],
+                        definition="SELECT * FROM range(n)",
+                        comment="Table macro over range(n)",
+                    ),
+                ],
+            ),
+            Schema(
+                path=["extra"],
+                comment="A second schema, tables only",
+                tables=[
+                    Table(
+                        name="five",
+                        function=SequenceFunction,
+                        arguments=Arguments(positional=(pa.scalar(5),)),
+                        comment="Integers 0..4",
+                    ),
+                ],
+            ),
+        ],
+    )
+
+
+_CATALOG_PROBE = _catalog(CATALOG_PROBE)
+_CATALOG_BROKEN = _catalog(CATALOG_BROKEN)
+_CATALOG_LEGACY = _catalog(CATALOG_LEGACY)
+
+
+class ContentsProbeCatalog(ReadOnlyCatalogInterface):
+    """Advertises and serves ``catalog_contents``."""
+
+    catalog = _CATALOG_PROBE
+    catalog_name = CATALOG_PROBE
+
+
+class ContentsBrokenCatalog(ReadOnlyCatalogInterface):
+    """Advertises ``catalog_contents`` but fails to serve it."""
+
+    catalog = _CATALOG_BROKEN
+    catalog_name = CATALOG_BROKEN
+
+    def catalog_contents(self, *, attach_opaque_data: Any, if_none_match: str | None = None) -> CatalogContentsResult:
+        """Always fail, to drive the client's per-schema fallback."""
+        raise RuntimeError(BROKEN_MESSAGE)
+
+
+class ContentsLegacyCatalog(ReadOnlyCatalogInterface):
+    """Does not advertise ``catalog_contents`` (an older worker)."""
+
+    catalog = _CATALOG_LEGACY
+    catalog_name = CATALOG_LEGACY
+
+    def catalog_attach(self, **kwargs: Any) -> CatalogAttachResult:
+        """Attach as the base class does, without the capability flag."""
+        return replace(super().catalog_attach(**kwargs), supports_catalog_contents=False)
+
+
+class ContentsProbeWorker(Worker):
+    """Serves ``contents_probe``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsProbeCatalog
+    catalog_name = CATALOG_PROBE
+    catalog = _CATALOG_PROBE
+
+
+class ContentsBrokenWorker(Worker):
+    """Serves ``contents_broken``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsBrokenCatalog
+    catalog_name = CATALOG_BROKEN
+    catalog = _CATALOG_BROKEN
+
+
+class ContentsLegacyWorker(Worker):
+    """Serves ``contents_legacy``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsLegacyCatalog
+    catalog_name = CATALOG_LEGACY
+    catalog = _CATALOG_LEGACY
+
+
+class _PrivateMemoryCatalog(InMemoryCatalog):
+    """DDL-capable in-memory catalog that advertises ``catalog_contents``.
+
+    Every ATTACH of `public_name` gets a private, empty catalog (one ``main``
+    schema) registered under an internal name, so state never leaks between
+    attaches that share one worker process.
+    """
+
+    public_name: str = ""
+
+    def __init__(self) -> None:
+        """Start with no catalogs; each attach creates its own."""
+        super().__init__()
+        self._catalogs.clear()
+
+    def catalogs(self) -> list[CatalogInfo]:
+        """Advertise only the public name (MetaWorker routes on it)."""
+        return [CatalogInfo(name=self.public_name, implementation_version=None, data_version_spec=None)]
+
+    def catalog_attach(
+        self,
+        *,
+        name: str,
+        options: dict[str, Any],
+        data_version_spec: str | None,
+        implementation_version: str | None,
+        ctx: Any = None,
+    ) -> CatalogAttachResult:
+        """Attach a fresh private catalog, advertising ``catalog_contents``."""
+        if name != self.public_name:
+            raise ValueError(f"Unknown catalog: {name!r}. Available: {self.public_name}")
+        private = f"{self.public_name}/{uuid.uuid4().hex}"
+        catalog = CatalogData(name=private)
+        catalog.schemas[("main",)] = SchemaData(
+            info=SchemaInfo(attach_opaque_data=AttachOpaqueData(b"\x00" * 16), path=["main"], comment=None, tags={})
+        )
+        self._catalogs[private] = catalog
+        result = super().catalog_attach(
+            name=private,
+            options=options,
+            data_version_spec=data_version_spec,
+            implementation_version=implementation_version,
+            ctx=ctx,
+        )
+        return replace(
+            result,
+            supports_catalog_contents=True,
+            catalog_version=self.catalog_version(
+                attach_opaque_data=result.attach_opaque_data, transaction_opaque_data=None
+            ),
+        )
+
+    def catalog_detach(self, *, attach_opaque_data: AttachOpaqueData) -> None:
+        """Detach and drop the private catalog."""
+        private = self._attachments.pop(attach_opaque_data, None)
+        if private is not None:
+            self._catalogs.pop(private, None)
+
+
+class ContentsMemoryCatalog(_PrivateMemoryCatalog):
+    """Private in-memory catalog reporting version 0 and no etag (the version-0 rule)."""
+
+    public_name = CATALOG_MEMORY
+
+    def catalog_version(
+        self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: Any, ctx: Any = None
+    ) -> int:
+        """Always 0: the catalog does not track its version."""
+        del attach_opaque_data, transaction_opaque_data, ctx
+        return 0
+
+
+class ContentsRevalCatalog(_PrivateMemoryCatalog):
+    """Private in-memory catalog that revalidates with a generation-counter etag."""
+
+    public_name = CATALOG_REVAL
+
+    def catalog_contents(
+        self, *, attach_opaque_data: AttachOpaqueData, if_none_match: str | None = None
+    ) -> CatalogContentsResult:
+        """Answer ``not_modified`` from the generation counter, building only on a miss."""
+        etag = f"gen-{self._get_catalog(attach_opaque_data).version}"
+        if if_none_match == etag:
+            return CatalogContentsResult(etag=etag, not_modified=True)
+        built = super().catalog_contents(attach_opaque_data=attach_opaque_data)
+        return CatalogContentsResult(schemas=built.schemas, etag=etag)
+
+
+class ContentsHashCatalog(_PrivateMemoryCatalog):
+    """Private in-memory catalog revalidated by the framework's content hash."""
+
+    public_name = CATALOG_HASH
+    catalog_contents_etag = "content-hash"
+
+
+class ContentsMemoryWorker(Worker):
+    """Serves ``contents_memory``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsMemoryCatalog
+    catalog_name = CATALOG_MEMORY
+
+
+class ContentsRevalWorker(Worker):
+    """Serves ``contents_reval``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsRevalCatalog
+    catalog_name = CATALOG_REVAL
+
+
+class ContentsHashWorker(Worker):
+    """Serves ``contents_hash``."""
+
+    route_unattached_calls = False
+
+    catalog_interface = ContentsHashCatalog
+    catalog_name = CATALOG_HASH
+
+
+CONTENTS_WORKERS: list[type[Worker]] = [
+    ContentsProbeWorker,
+    ContentsBrokenWorker,
+    ContentsLegacyWorker,
+    ContentsMemoryWorker,
+    ContentsRevalWorker,
+    ContentsHashWorker,
+]

vgi/_test_fixtures/http_server.py

@@ -187,6 +187,16 @@ def main() -> None:
                 "with no continuation escape. Default: no cap."
             ),
         ),
+        identity: bool = typer.Option(
+            False,
+            "--identity",
+            envvar="VGI_FIXTURE_IDENTITY",
+            help=(
+                "Host vgi_rpc.Identity.v1 with the vgi-rpc conformance fixture policy and its "
+                "spoofable X-Conformance-Principal header authentication. Test-only; for "
+                "vgi-rpc-test-hosted --identity."
+            ),
+        ),
         port_file: str | None = typer.Option(
             None,
             "--port-file",
@@ -198,7 +208,7 @@ def main() -> None:
         ),
     ) -> None:
         try:
-            from vgi_rpc import Compression, ExternalLocationConfig, RpcServer
+            from vgi_rpc import Compression, ExternalLocationConfig
             from vgi_rpc.http import make_wsgi_app
         except ImportError:
             sys.stderr.write(
@@ -301,8 +311,6 @@ def main() -> None:
 
         import socket
 
-        from vgi.protocol import VgiProtocol
-
         if port == 0:
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
                 s.bind((host, 0))
@@ -316,6 +324,13 @@ def main() -> None:
         authenticate = _resolve_authenticate()
         oauth_metadata = _resolve_oauth_resource_metadata()
 
+        introspect_principals: list[str] | None = None
+        if identity:
+            from vgi._test_fixtures.identity_fixture import INTROSPECT_PRINCIPALS, conformance_authenticate
+
+            authenticate = conformance_authenticate
+            introspect_principals = INTROSPECT_PRINCIPALS
+
         if authenticate is None:
             # Test-only OPTIONAL bearer auth. Lets the cache identity-isolation
             # test attach the same worker under different principals (alice/bob)
@@ -354,9 +369,10 @@ def main() -> None:
         # and not the other fails the file on that transport alone — which reads
         # as a transport bug and is not one. narrow_bind drifted exactly that
         # way, and it guards a client SIGSEGV, so it was the worst one to lose.
+        from vgi._test_fixtures.catalog_contents import CONTENTS_WORKERS
         from vgi._test_fixtures.narrow_bind.worker import NarrowBindWorker
         from vgi._test_fixtures.twin_catalogs import TwinAWorker, TwinBWorker
-        from vgi.worker import _get_vgi_version
+        from vgi.rpc_server import build_rpc_server
 
         worker_classes: list[type] = [
             ExampleWorker,
@@ -366,6 +382,7 @@ def main() -> None:
             NarrowBindWorker,
             TwinAWorker,
             TwinBWorker,
+            *CONTENTS_WORKERS,
         ]
         try:
             from vgi._test_fixtures.writable.worker import WritableWorker
@@ -373,6 +390,11 @@ def main() -> None:
             pass
         else:
             worker_classes.append(WritableWorker)
+        if identity:
+            # Same "example" catalog, plus the conformance identity hooks.
+            from vgi._test_fixtures.identity_fixture import IdentityExampleWorker
+
+            worker_classes[worker_classes.index(ExampleWorker)] = IdentityExampleWorker
         workers = [wc(quiet=True, log_level=effective_level) for wc in worker_classes]
         # One signing key shared by every sub-worker (which seal catalog
         # opaque-data envelopes) and the HTTP state-token machinery.
@@ -380,12 +402,12 @@ def main() -> None:
         for w in workers:
             w._signing_key = signing_key
         worker: Any = workers[0] if len(workers) == 1 else MetaWorker(workers)
-        server = RpcServer(
-            VgiProtocol,
+        server = build_rpc_server(
             worker,
+            transport="http",
+            describe=describe,
             external_location=external_location,
-            enable_describe=describe,
-            server_version=_get_vgi_version(),
+            introspect_principals=introspect_principals,
         )
         wsgi_app = make_wsgi_app(
             server,

vgi/_test_fixtures/identity_fixture.py

@@ -0,0 +1,75 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Opt the HTTP fixture into ``vgi_rpc.Identity.v1`` with the conformance policy.
+
+Enabled by ``vgi-fixture-http --identity`` (or ``VGI_FIXTURE_IDENTITY=1``) so
+the cross-SDK hosted-protocols group can run its identity cases with
+``vgi-rpc-test-hosted --url ... --identity``. Off by default, so the DuckDB
+integration runs see the same worker as before.
+
+The policy is pinned by vgi-rpc's ``IDENTITY_CONFORMANCE_FIXTURE.md``. The
+hooks and constants come straight from the reference
+(``vgi_rpc.conformance.identity_fixture``) rather than being transcribed.
+Copying them would let this fixture drift from the contract it claims to meet.
+
+.. warning::
+
+   The header authenticator below is trivially spoofable by anyone who can
+   reach the port. It is a test fixture and must never be deployed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vgi_rpc.conformance.identity_fixture import (
+    AUTH_TIME_HEADER,
+    INTROSPECTOR_PRINCIPAL,
+    PRINCIPAL_HEADER,
+    conformance_mint_grant,
+    conformance_resolve_token,
+)
+from vgi_rpc.rpc import AuthContext
+
+from vgi._test_fixtures.worker import ExampleWorker
+from vgi.auth import IssuedGrant, TokenIdentity
+
+__all__ = ["INTROSPECT_PRINCIPALS", "IdentityExampleWorker", "conformance_authenticate"]
+
+#: The introspector allowlist the conformance policy pins: exactly one principal.
+INTROSPECT_PRINCIPALS = [INTROSPECTOR_PRINCIPAL]
+
+
+class IdentityExampleWorker(ExampleWorker):
+    """``ExampleWorker`` whose identity hooks follow the conformance policy.
+
+    It replaces ``ExampleWorker`` in the fixture's ``MetaWorker``, so it is the
+    only child that implements the hooks.
+    """
+
+    @classmethod
+    def resolve_token(cls, token: str) -> TokenIdentity | None:
+        """Resolve per the conformance policy (§3.3)."""
+        return conformance_resolve_token(token)
+
+    @classmethod
+    def mint_grant(cls, principal: str, purpose: str, scopes: list[str], ttl_seconds: int) -> IssuedGrant:
+        """Mint per the conformance policy (§3.4)."""
+        return conformance_mint_grant(principal, purpose, scopes, ttl_seconds)
+
+
+def conformance_authenticate(req: Any) -> AuthContext:
+    """Derive the caller from ``X-Conformance-Principal`` / ``X-Conformance-Auth-Time``.
+
+    An absent principal header means *unauthenticated*. The auth-time header is
+    placed in the claims verbatim and unparsed, because the guard does the
+    parsing and the fixture only carries the value.
+    """
+    principal = req.get_header(PRINCIPAL_HEADER)
+    if not principal:
+        return AuthContext(domain=None, authenticated=False, principal=None)
+    claims: dict[str, object] = {}
+    auth_time = req.get_header(AUTH_TIME_HEADER)
+    if auth_time is not None:
+        claims["auth_time"] = auth_time
+    return AuthContext(domain="conformance", authenticated=True, principal=principal, claims=claims)

vgi/_test_fixtures/scalar/geo.py

@@ -106,12 +106,12 @@ class GeoDistanceListFunction(ScalarFunction):
     @classmethod
     def compute(
         cls,
-        p1: Annotated[  # type: ignore[type-arg]
-            pa.ListArray,
+        p1: Annotated[
+            pa.ListArray,  # type: ignore[type-arg]
             Param(doc="First point [lat, lon]", arrow_type=pa.list_(pa.float64())),
         ],
-        p2: Annotated[  # type: ignore[type-arg]
-            pa.ListArray,
+        p2: Annotated[
+            pa.ListArray,  # type: ignore[type-arg]
             Param(doc="Second point [lat, lon]", arrow_type=pa.list_(pa.float64())),
         ],
     ) -> Annotated[pa.DoubleArray, Returns()]:
@@ -151,12 +151,12 @@ class GeoDistanceFixedFunction(ScalarFunction):
     @classmethod
     def compute(
         cls,
-        p1: Annotated[  # type: ignore[type-arg]
-            pa.FixedSizeListArray,
+        p1: Annotated[
+            pa.FixedSizeListArray,  # type: ignore[type-arg]
             Param(doc="First point [lat, lon]", arrow_type=pa.list_(pa.float64(), 2)),
         ],
-        p2: Annotated[  # type: ignore[type-arg]
-            pa.FixedSizeListArray,
+        p2: Annotated[
+            pa.FixedSizeListArray,  # type: ignore[type-arg]
             Param(doc="Second point [lat, lon]", arrow_type=pa.list_(pa.float64(), 2)),
         ],
     ) -> Annotated[pa.DoubleArray, Returns()]:
@@ -240,8 +240,8 @@ class GeoCentroidListFunction(ScalarFunction):
     @classmethod
     def compute(
         cls,
-        points: Annotated[  # type: ignore[type-arg]
-            list[pa.ListArray],
+        points: Annotated[
+            list[pa.ListArray],  # type: ignore[type-arg]
             Param(
                 doc="Point columns [lat, lon]",
                 arrow_type=pa.list_(pa.float64()),
@@ -284,8 +284,8 @@ class GeoCentroidFixedFunction(ScalarFunction):
     @classmethod
     def compute(
         cls,
-        points: Annotated[  # type: ignore[type-arg]
-            list[pa.FixedSizeListArray],
+        points: Annotated[
+            list[pa.FixedSizeListArray],  # type: ignore[type-arg]
             Param(
                 doc="Point columns [lat, lon]",
                 arrow_type=pa.list_(pa.float64(), 2),

vgi/_test_fixtures/worker.py

@@ -35,6 +35,7 @@ except ImportError:
 import os
 import tempfile
 import uuid
+from collections.abc import Sequence
 from typing import Annotated, Any
 
 import pyarrow as pa
@@ -2143,6 +2144,19 @@ class ExampleWorker(Worker):
     # operations go through catalog_interface.
     catalog = _EXAMPLE_CATALOG
 
+    @classmethod
+    def hosted_protocols(cls) -> Sequence[tuple[type, object]]:
+        """Host ``conformance.Secondary.v1`` beside ``vgi.v2``, on every transport.
+
+        The cross-SDK hosted-protocols group (``vgi-rpc-test-hosted``) expects
+        every SDK fixture worker to host the vgi-rpc reference secondary. Only
+        this child of the fixture's ``MetaWorker`` returns it: one process
+        hosts a protocol name once.
+        """
+        from vgi_rpc.conformance.secondary import conformance_extra_protocols
+
+        return conformance_extra_protocols()
+
     class Settings:
         """Settings exposed via catalog_attach."""
 
@@ -2151,8 +2165,8 @@ class ExampleWorker(Worker):
         multiplier: Annotated[int, Setting(desc="Value multiplier")] = 1
         threshold: Annotated[int, Setting(desc="Filter threshold")] = 0
         scale_factor: Annotated[float, Setting(desc="Float scale factor")] = 1.0
-        config: Annotated[  # type: ignore[valid-type]
-            pa.struct([("start", pa.int64()), ("step", pa.int64()), ("label", pa.string())]),
+        config: Annotated[
+            pa.struct([("start", pa.int64()), ("step", pa.int64()), ("label", pa.string())]),  # type: ignore[valid-type]
             Setting(desc="Sequence configuration struct"),
         ] = None
 
@@ -2178,12 +2192,13 @@ def main() -> None:
 
     Always serves the base ExampleWorker catalog plus the
     ``projection_repro``, ``schema_reconcile``, ``accumulate``,
-    ``narrow_bind``, ``twin_a`` and ``twin_b`` fixture catalogs (all
+    ``narrow_bind``, ``twin_a``, ``twin_b`` and ``contents_*`` fixture catalogs (all
     depend on the ``vgi[test-fixtures]`` extra). Adds the writable
     catalog when the ``vgi[test-fixtures-writable]`` extra is also
     installed.
     """
     from vgi._test_fixtures.accumulate.worker import AccumulateWorker
+    from vgi._test_fixtures.catalog_contents import CONTENTS_WORKERS
     from vgi._test_fixtures.narrow_bind.worker import NarrowBindWorker
     from vgi._test_fixtures.projection_repro.worker import ProjReproWorker
     from vgi._test_fixtures.schema_reconcile.worker import SchemaReconcileWorker
@@ -2200,6 +2215,9 @@ def main() -> None:
         # `test_same_name_catalog` — only the attached catalog tells them apart.
         TwinAWorker,
         TwinBWorker,
+        # contents_*: catalog_contents served / failing / not advertised, and
+        # the version-0, revalidating and content-hash DDL catalogs.
+        *CONTENTS_WORKERS,
     ]
     try:
         from vgi._test_fixtures.writable.worker import WritableWorker

vgi/catalog/__init__.py

@@ -10,6 +10,7 @@ from vgi.catalog.catalog_interface import (
     AttachCatalogInfo,
     AttachOpaqueData,
     CatalogAttachResult,
+    CatalogContentsResult,
     CatalogDataVersionRelease,
     CatalogExample,
     CatalogInfo,
@@ -30,6 +31,7 @@ from vgi.catalog.catalog_interface import (
     ScanBranch,
     ScanBranchesResult,
     ScanFunctionResult,
+    SchemaContentsInfo,
     SchemaInfo,
     SchemaObjectType,
     SerializedSchema,
@@ -69,6 +71,8 @@ __all__ = [
     "ForeignKeyInfo",
     "IndexInfo",
     "MacroInfo",
+    "CatalogContentsResult",
+    "SchemaContentsInfo",
     "SchemaInfo",
     "SecretTypeSpec",
     "Setting",