vgi-python 0.29.6__tar.gz → 0.31.0__tar.gz

{vgi_python-0.29.6 → vgi_python-0.31.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.6
+Version: 0.31.0
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python
@@ -162,7 +162,7 @@ Requires-Dist: httpx2>=2.9.1
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.43.2
+Requires-Dist: vgi-rpc>=0.44.1
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.29.6 → vgi_python-0.31.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.29.6"
+version = "0.31.0"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [
@@ -40,7 +40,7 @@ dependencies = [
     "pyarrow",
     "typer>=0.9",
     "platformdirs",
-    "vgi-rpc>=0.43.2",
+    "vgi-rpc>=0.44.1",
     "httpx2>=2.9.1",
 ]
 

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/catalog/test_serialization.py

@@ -1008,6 +1008,33 @@ class TestScanFunctionResultSerialization:
 
         assert restored.required_extensions == ["iceberg", "parquet", "httpfs"]
 
+    def test_schema_name_round_trip(self) -> None:
+        """schema_name (protocol 1.5.0) round-trips when set."""
+        original = ScanFunctionResult(
+            function_name="rowid_sequence",
+            positional_arguments=[],
+            named_arguments={},
+            schema_name="main",
+        )
+        serialized = original.serialize()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = ScanFunctionResult.deserialize(batch)
+
+        assert restored.schema_name == "main"
+
+    def test_schema_name_defaults_to_none(self) -> None:
+        """schema_name is None when the caller doesn't set it (e.g. a pre-1.5.0 peer)."""
+        original = ScanFunctionResult(
+            function_name="read_parquet",
+            positional_arguments=[],
+            named_arguments={},
+        )
+        serialized = original.serialize()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = ScanFunctionResult.deserialize(batch)
+
+        assert restored.schema_name is None
+
 
 class TestSettingSpecSerialization:
     """Test SettingSpec serialization round-trip."""
@@ -1176,6 +1203,10 @@ class TestArrowSchemaCorrectness:
         assert schema.field("function_name").type == pa.string()
         assert schema.field("arguments").type == pa.binary()
         assert schema.field("required_extensions").type == pa.list_(pa.string())
+        # Added in protocol 1.5.0 — nullable so a pre-1.5.0 peer's payload
+        # still deserializes (the column is simply absent there).
+        assert schema.field("schema_name").type == pa.string()
+        assert schema.field("schema_name").nullable is True
 
 
 class TestScanBranchSerialization:
@@ -1192,6 +1223,10 @@ class TestScanBranchSerialization:
         assert schema.field("branch_filter").nullable is True
         assert schema.field("writable").type == pa.bool_()
         assert schema.field("writable").nullable is False
+        # Added in protocol 1.5.0 — function-branch only; None for a
+        # catalog-table/format branch or a pre-1.5.0 peer.
+        assert schema.field("schema_name").type == pa.string()
+        assert schema.field("schema_name").nullable is True
 
     def test_scan_branches_result_schema(self) -> None:
         """ScanBranchesResult Arrow schema: branches as list<binary>, required_extensions hoisted to top-level."""
@@ -1249,6 +1284,36 @@ class TestScanBranchSerialization:
         assert restored.branch_filter == "ts >= TIMESTAMP '2026-05-15 00:00:00'"
         assert len(restored.positional_arguments) == 2
 
+    def test_scan_branch_schema_name_round_trip(self) -> None:
+        """A function branch's schema_name (protocol 1.5.0) round-trips when set."""
+        from vgi.catalog import ScanBranch
+
+        original = ScanBranch(
+            function_name="rowid_sequence",
+            positional_arguments=[],
+            named_arguments={},
+            schema_name="main",
+        )
+        batch, _ = deserialize_record_batch(original.serialize())
+        restored = ScanBranch.deserialize(batch)
+        assert restored.schema_name == "main"
+
+    def test_scan_branch_schema_name_defaults_to_none(self) -> None:
+        """schema_name is None for a branch that doesn't set it (e.g. a catalog-table branch)."""
+        from vgi.catalog import ScanBranch
+
+        original = ScanBranch(
+            function_name="",
+            positional_arguments=[],
+            named_arguments={},
+            source_catalog="lakehouse",
+            source_schema="bronze",
+            source_table="orders",
+        )
+        batch, _ = deserialize_record_batch(original.serialize())
+        restored = ScanBranch.deserialize(batch)
+        assert restored.schema_name is None
+
     def test_scan_branches_result_round_trip(self) -> None:
         """ScanBranchesResult round-trips two heterogeneous branches + required_extensions."""
         from vgi.catalog import ScanBranch, ScanBranchesResult

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/client/test_batch_metadata_callback.py

@@ -69,7 +69,7 @@ def test_callback_sees_none_for_a_batch_without_custom_metadata(client: Any) ->
         client.table_function(
             function_name="sequence",
             schema_name="main",
-            arguments=Arguments(positional=[pa.scalar(4)]),
+            arguments=Arguments(positional=(pa.scalar(4),)),
             batch_metadata_callback=metas.append,
         )
     )

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/client/test_scan_branches_client.py

@@ -60,8 +60,11 @@ def test_single_branch_table_falls_back_to_legacy_rpc(client: Any) -> None:
         name="numbers",
     )
     assert len(result.branches) == 1
-    assert result.branches[0].function_name == client.table_scan_function_get(
-        attach_opaque_data=_attach_opaque(client),
-        schema_name=DATA,
-        name="numbers",
-    ).function_name
+    assert (
+        result.branches[0].function_name
+        == client.table_scan_function_get(
+            attach_opaque_data=_attach_opaque(client),
+            schema_name=DATA,
+            name="numbers",
+        ).function_name
+    )

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/client/test_time_travel_client.py

@@ -79,7 +79,7 @@ def test_table_function_with_no_at_clause_is_unaffected(client: Any) -> None:
     """The new `at_unit`/`at_value` params default to `None` — unchanged behavior without them."""
     batches = list(
         client.table_function(
-            function_name="sequence", schema_name="main", arguments=Arguments(positional=[pa.scalar(5)])
+            function_name="sequence", schema_name="main", arguments=Arguments(positional=(pa.scalar(5),))
         )
     )
     assert sum(b.num_rows for b in batches) == 5

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/conformance/test_protocol_version.py

@@ -32,14 +32,14 @@ CLIENT_PROTOCOL_VERSION = VgiProtocol.protocol_version
 
 def test_client_protocol_version_is_canonical() -> None:
     """Sanity-check the constants this test reasons about haven't drifted apart."""
-    assert CLIENT_PROTOCOL_VERSION == "1.4.0"
+    assert CLIENT_PROTOCOL_VERSION == "1.5.0"
     # The fixture must be a genuine mismatch in the major/minor that the
     # framework compares; a patch-only difference would (correctly) pass.
     assert BAD_PROTOCOL_VERSION.split(".")[:2] != CLIENT_PROTOCOL_VERSION.split(".")[:2]
 
 
 def test_mismatched_worker_protocol_version_raises() -> None:
-    """A worker enforcing 99.0.0 must reject the 1.4.0 client at dispatch."""
+    """A worker enforcing 99.0.0 must reject the 1.5.0 client at dispatch."""
     with Client("vgi-fixture-bad-protocol-worker") as client, pytest.raises(ClientError) as exc_info:
         list(
             client.table_function(
@@ -54,5 +54,5 @@ def test_mismatched_worker_protocol_version_raises() -> None:
     assert "protocol_version mismatch" in message
     assert CLIENT_PROTOCOL_VERSION in message
     assert BAD_PROTOCOL_VERSION in message
-    # Directional hint: the client (1.3.0) is older than the worker (99.0.0).
+    # Directional hint: the client (1.5.0) is older than the worker (99.0.0).
     assert "upgrade the VGI extension/client" in message

vgi_python-0.31.0/tests/test_client_oauth.py

@@ -0,0 +1,204 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Tests for vgi.client.Client's OAuth wiring (oauth=/oauth_refresh_token=/oauth_flow=).
+
+The device-code/PKCE flow logic itself is tested exhaustively in
+vgi-rpc-python's tests/test_oauth_client.py (mock IdP, no network). These
+tests cover the integration seam: does `Client` build a `VgiOAuthAuth` with
+the right configuration, does construction-time validation reject bad
+combinations, and does a full round trip actually work when driven through
+`Client`'s real request path (via the `httpx_client=` escape hatch, wired to
+a mock IdP the same way vgi-rpc-python's own tests are).
+"""
+
+from __future__ import annotations
+
+import httpx2
+import pytest
+from vgi_rpc.http import VgiOAuthAuth
+
+from vgi.client.client import Client
+
+RESOURCE_METADATA_URL = "https://api.example.com/.well-known/oauth-protected-resource"
+DEVICE_AUTH_URL = "https://auth.example.com/device/code"
+TOKEN_URL = "https://auth.example.com/token"
+
+
+class _MockIdp:
+    """Minimal mock IdP + protected resource for one full device-code round trip."""
+
+    def __init__(self) -> None:
+        self.device_auth_calls = 0
+        self.granted_token = "mock-access-token"
+
+    def handler(self, request: httpx2.Request) -> httpx2.Response:
+        """Route a request to the matching mock endpoint by exact URL."""
+        url = str(request.url)
+        if url == RESOURCE_METADATA_URL:
+            return httpx2.Response(
+                200,
+                json={
+                    "resource": "https://api.example.com",
+                    "authorization_servers": ["https://auth.example.com"],
+                    "device_code_client_id": "device-client",
+                    "device_code_client_secret": "device-secret",
+                },
+            )
+        if url == "https://auth.example.com/.well-known/openid-configuration":
+            return httpx2.Response(
+                200,
+                json={
+                    "token_endpoint": TOKEN_URL,
+                    "device_authorization_endpoint": DEVICE_AUTH_URL,
+                    "grant_types_supported": ["urn:ietf:params:oauth:grant-type:device_code"],
+                },
+            )
+        if url == DEVICE_AUTH_URL:
+            self.device_auth_calls += 1
+            return httpx2.Response(
+                200,
+                json={
+                    "device_code": "devcode-123",
+                    "user_code": "ABCD-EFGH",
+                    "verification_uri": "https://auth.example.com/activate",
+                    "expires_in": 600,
+                    "interval": 0,
+                },
+            )
+        if url == TOKEN_URL:
+            return httpx2.Response(200, json={"access_token": self.granted_token, "token_type": "Bearer"})
+        if url.endswith("/vgi/catalogs"):
+            token = request.headers.get("authorization", "")
+            if token:
+                return httpx2.Response(200, json={"authorization": token})
+            return httpx2.Response(
+                401,
+                headers={"www-authenticate": f'Bearer resource_metadata="{RESOURCE_METADATA_URL}"'},
+            )
+        return httpx2.Response(404, json={"error": "not_found", "url": url})  # pragma: no cover
+
+
+class TestConstructorValidation:
+    """Tests for the mutually-exclusive oauth/bearer_token/httpx_client combinations."""
+
+    def test_oauth_and_bearer_token_raises(self) -> None:
+        """Passing both oauth=True and bearer_token= raises ValueError."""
+        with pytest.raises(ValueError, match="mutually exclusive"):
+            Client(transport="http", base_url="https://example.com", oauth=True, bearer_token="tok")
+
+    def test_oauth_refresh_token_and_bearer_token_raises(self) -> None:
+        """oauth_refresh_token= (which implies oauth=True) also conflicts with bearer_token=."""
+        with pytest.raises(ValueError, match="mutually exclusive"):
+            Client(
+                transport="http",
+                base_url="https://example.com",
+                oauth_refresh_token="seed",
+                bearer_token="tok",
+            )
+
+    def test_oauth_and_httpx_client_raises(self) -> None:
+        """Passing both oauth=True and httpx_client= raises ValueError."""
+        with pytest.raises(ValueError, match="httpx_client"):
+            Client(
+                transport="http",
+                base_url="https://example.com",
+                oauth=True,
+                httpx_client=httpx2.Client(),
+            )
+
+    def test_invalid_oauth_flow_raises(self) -> None:
+        """An unrecognized oauth_flow value raises ValueError, not a silent no-op."""
+        with pytest.raises(ValueError, match="oauth_flow"):
+            Client(transport="http", base_url="https://example.com", oauth=True, oauth_flow="carrier-pigeon")  # type: ignore[arg-type]
+
+    def test_invalid_oauth_prompt_raises(self) -> None:
+        """An unrecognized oauth_prompt value raises ValueError, not a silent no-op."""
+        with pytest.raises(ValueError, match="oauth_prompt"):
+            Client(transport="http", base_url="https://example.com", oauth=True, oauth_prompt="shout")  # type: ignore[arg-type]
+
+    def test_bearer_token_alone_still_works(self) -> None:
+        """The existing bearer_token= path is unaffected by the new oauth params."""
+        client = Client(transport="http", base_url="https://example.com", bearer_token="tok")
+        assert client._bearer_token == "tok"
+        assert not client._use_oauth
+
+
+class TestOAuthWiring:
+    """Tests that Client(oauth=...) builds a correctly-configured VgiOAuthAuth."""
+
+    def test_oauth_true_builds_vgi_oauth_auth(self) -> None:
+        """oauth=True lazily builds a VgiOAuthAuth with the client's own oauth_* settings."""
+        client = Client(
+            transport="http",
+            base_url="https://example.com",
+            oauth=True,
+            oauth_flow="device_code",
+            oauth_timeout_seconds=42.0,
+            oauth_prompt="consent",
+        )
+        assert client.oauth_identity() is None  # nothing has authenticated yet
+        client._get_or_create_httpx_client()
+        assert isinstance(client._oauth_auth, VgiOAuthAuth)
+        assert client._oauth_auth._flow == "device_code"  # noqa: SLF001 -- white-box wiring check
+        assert client._oauth_auth._timeout_seconds == 42.0  # noqa: SLF001
+        assert client._oauth_auth._prompt == "consent"  # noqa: SLF001
+        client._oauth_auth.close()
+
+    def test_oauth_refresh_token_seeds_the_auth_object(self) -> None:
+        """oauth_refresh_token= implies oauth=True and seeds the refresh token."""
+        client = Client(
+            transport="http",
+            base_url="https://example.com",
+            oauth_refresh_token="pre-seeded-token",
+        )
+        assert client._use_oauth
+        client._get_or_create_httpx_client()
+        assert client._oauth_auth is not None
+        assert client._oauth_auth._token.refresh_token == "pre-seeded-token"  # noqa: SLF001
+        client._oauth_auth.close()
+
+
+class TestOAuthEndToEnd:
+    """A full device-code login round trip through the exact client Client would use.
+
+    Uses the httpx_client= escape hatch to wire a VgiOAuthAuth against a mock
+    IdP (httpx2.MockTransport) -- the same technique vgi-rpc-python's own
+    tests use. The device-code/PKCE flow mechanics are covered exhaustively
+    there (mock IdP, no network); this test's job is narrower: prove
+    ``Client`` actually issues its RPCs through the httpx2.Client it was
+    handed (so a real attach would carry the OAuth-obtained token), and that
+    a 401-triggered login on that client completes end to end.
+    """
+
+    def test_client_issues_requests_through_the_oauth_authed_httpx_client(self) -> None:
+        """A 401 on the client Client._get_or_create_httpx_client() returns triggers a real login."""
+        idp = _MockIdp()
+        auth = VgiOAuthAuth(
+            base_url="https://example.com",
+            flow="device_code",
+            timeout_seconds=5.0,
+            transport=httpx2.MockTransport(idp.handler),
+        )
+        httpx_client = httpx2.Client(
+            transport=httpx2.MockTransport(idp.handler), auth=auth, base_url="https://example.com"
+        )
+        # Not started (no worker spawned) -- this test only exercises the HTTP/OAuth
+        # plumbing, not a full RPC call, so client.stop() (which requires start())
+        # doesn't apply; the httpx_client/auth are closed directly instead.
+        client = Client(transport="http", base_url="https://example.com", httpx_client=httpx_client)
+        try:
+            # This is the exact client object Client's own RPC machinery sends
+            # every request through -- not a parallel one built just for the test.
+            assert client._get_or_create_httpx_client() is httpx_client
+
+            resp = httpx_client.get("/vgi/catalogs")
+            assert resp.status_code == 200
+            assert resp.json()["authorization"] == f"Bearer {idp.granted_token}"
+            assert idp.device_auth_calls == 1
+
+            # A second request reuses the cached token -- no second login.
+            httpx_client.get("/vgi/catalogs")
+            assert idp.device_auth_calls == 1
+        finally:
+            httpx_client.close()
+            auth.close()

{vgi_python-0.29.6 → vgi_python-0.31.0}/tests/test_wire_record_schema_parity.py

@@ -81,6 +81,7 @@ def _scan_function_result() -> ScanFunctionResult:
         positional_arguments=positional,
         named_arguments=named,
         required_extensions=["parquet"],
+        schema_name="main",
     )
 
 
@@ -98,6 +99,7 @@ def _scan_branch() -> ScanBranch:
         format_name="parquet",
         format_locations=["s3://bucket/a.parquet"],
         format_options={"delim": pa.scalar("|", pa.string())},
+        schema_name="main",
     )
 
 

{vgi_python-0.29.6 → vgi_python-0.31.0}/uv.lock

@@ -2569,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.29.6"
+version = "0.31.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },
@@ -2686,7 +2686,7 @@ requires-dist = [
     { name = "vgi-python", extras = ["test-fixtures"], marker = "extra == 'test-fixtures-writable'" },
     { name = "vgi-python", extras = ["test-fixtures", "test-fixtures-writable", "http", "launch", "oauth", "otel", "sentry", "azure"], marker = "extra == 'dev'" },
     { name = "vgi-python", extras = ["transactor"], marker = "extra == 'test-fixtures-writable'" },
-    { name = "vgi-rpc", specifier = ">=0.43.2" },
+    { name = "vgi-rpc", specifier = ">=0.44.1" },
     { name = "vgi-rpc", extras = ["cli"], marker = "extra == 'launch'" },
     { name = "vgi-rpc", extras = ["cli", "conformance", "external", "http", "oauth", "otel", "sentry"], marker = "extra == 'dev'" },
     { name = "vgi-rpc", extras = ["http"], marker = "extra == 'granian'" },
@@ -2716,7 +2716,7 @@ docs = [
 
 [[package]]
 name = "vgi-rpc"
-version = "0.43.2"
+version = "0.44.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "docstring-parser" },
@@ -2724,9 +2724,9 @@ dependencies = [
     { name = "pywin32", marker = "sys_platform == 'win32'" },
     { name = "tzdata", marker = "sys_platform == 'win32'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/ce/04/efb99f0fb56535bcba110e6c12448c31b429e0861aae4bc2f7136299cfc2/vgi_rpc-0.43.2.tar.gz", hash = "sha256:6a06437af17442451bfe07186bc472a2efb57e030b0e5b38a28922034a814123", size = 1147340, upload-time = "2026-08-27T18:33:54.608Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/1a/16/5a78053080117cac00a8945b70298d636a63d57801a33528bb63b14cdd95/vgi_rpc-0.44.1.tar.gz", hash = "sha256:37a54ae2cb7e5a7a2603aad69ece92c3c99a96906c96d2196806202ee4b70825", size = 1170809, upload-time = "2026-08-28T15:03:07.221Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/ac/b9/33cdb4fe27ef3893e1cded63f396af8bc517e390615f34db6f4bd227ef4c/vgi_rpc-0.43.2-py3-none-any.whl", hash = "sha256:b112ab76828367176a41f1b9a4ceeaba8979629e4e5972f64bf769c94b3e36a4", size = 528134, upload-time = "2026-08-27T18:33:52.829Z" },
+    { url = "https://files.pythonhosted.org/packages/8f/d6/3bfff42bd723ffcd0c2550d932e766aa65d39a886017cb9c002174e68196/vgi_rpc-0.44.1-py3-none-any.whl", hash = "sha256:e9785753bdb30e3f07f2bdbeafcddd09533cc014baa310e093a94fdeda6ad517", size = 545257, upload-time = "2026-08-28T15:03:05.268Z" },
 ]
 
 [package.optional-dependencies]

vgi_python-0.31.0/vgi/_test_fixtures/table/same_name_schemas.py

@@ -0,0 +1,136 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Same-name-in-two-schemas producer, backing a DECLARATIVE TABLE in each schema.
+
+The table-dispatch member of the schema-disambiguation family (see
+``scalar/same_name.py``, ``table_in_out_same_name.py``, ``aggregate/same_name.py``,
+and ``table/same_name_cached.py`` for the result-cache member). Those probe a
+function called directly (or the result cache); this one probes
+``catalog_table_scan_function_get``/``catalog_table_scan_branches_get`` — the RPC
+pair that tells a client which function backs a *declarative catalog table*.
+
+``test_same_name_table_scan`` is a one-row producer registered under the SAME
+NAME in BOTH the ``main`` and ``data`` schemas of the ``example`` catalog, each
+emitting a single row tagged with its own schema. A declarative ``Table``
+descriptor named ``test_same_name_table`` is registered in each schema too, each
+backed by that schema's own implementation.
+
+This is also the end-to-end regression guard for protocol 1.5.0's
+``ScanFunctionResult.schema_name``/``ScanBranch.schema_name``: the C++ extension
+now prefers the worker-declared schema over its old table-schema/default-schema
+heuristic when resolving which catalog entry ``function_name`` refers to. A
+worker that regressed to leaving ``schema_name`` unset, or a client that stopped
+consuming it, would silently fall back to the old heuristic — which still
+happens to get *this* two-schema case right (the table's own schema is tried
+first and always matches here), so a regression here would show up not as a
+wrong row, but as the exact filter/projection-pushdown breakage this session's
+own investigation traced to passing the wire-parsed schema string somewhere the
+resolver couldn't safely reuse it — see ``cache/filter_pushdown_keys.test`` and
+this table family's own pushdown assertions below. Driven by
+``table/same_name_schemas.test``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import ClassVar
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import OutputCollector
+
+from vgi.metadata import FunctionExample
+from vgi.schema_utils import schema
+from vgi.table_function import (
+    ProcessParams,
+    TableFunctionGenerator,
+    bind_fixed_schema,
+    init_single_worker,
+)
+
+FUNCTION_NAME = "test_same_name_table_scan"
+TABLE_NAME = "test_same_name_table"
+
+
+@dataclass(slots=True, frozen=True)
+class _SameNameTableArgs:
+    """Arguments for the same-name table producer (none)."""
+
+
+@dataclass(kw_only=True)
+class _SameNameTableState(ArrowSerializableDataclass):
+    """One-shot emit latch for the single output row."""
+
+    done: bool = False
+
+
+class _SameNameTableScan(TableFunctionGenerator[_SameNameTableArgs, _SameNameTableState]):
+    """Shared body; each subclass supplies the schema it is declared in."""
+
+    #: Schema this implementation is declared in — the tag it stamps.
+    OWNING_SCHEMA: ClassVar[str] = ""
+
+    FunctionArguments = _SameNameTableArgs
+    FIXED_SCHEMA: ClassVar[pa.Schema] = schema(tag=pa.string())
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[_SameNameTableArgs]) -> _SameNameTableState:
+        """Fresh latch per invocation."""
+        return _SameNameTableState()
+
+    @classmethod
+    def process(
+        cls,
+        params: ProcessParams[_SameNameTableArgs],
+        state: _SameNameTableState,
+        out: OutputCollector,
+    ) -> None:
+        """Emit the single schema-tagged row once."""
+        if state.done:
+            out.finish()
+            return
+        batch = pa.RecordBatch.from_pydict({"tag": [cls.OWNING_SCHEMA]}, schema=params.output_schema)
+        out.emit(batch)
+        state.done = True
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameTableMainScan(_SameNameTableScan):
+    """``test_same_name_table_scan`` as declared in the ``main`` schema."""
+
+    OWNING_SCHEMA = "main"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the main-schema table producer"
+        categories = ["generator", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.main.test_same_name_table",
+                description="One row tagged 'main'",
+            ),
+        ]
+
+
+@init_single_worker
+@bind_fixed_schema
+class SameNameTableDataScan(_SameNameTableScan):
+    """``test_same_name_table_scan`` as declared in the ``data`` schema."""
+
+    OWNING_SCHEMA = "data"
+
+    class Meta:
+        """Function metadata."""
+
+        name = FUNCTION_NAME
+        description = "Schema-disambiguation probe; the data-schema table producer"
+        categories = ["generator", "testing"]
+        examples = [
+            FunctionExample(
+                sql="SELECT * FROM example.data.test_same_name_table",
+                description="One row tagged 'data'",
+            ),
+        ]