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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.4
+Version: 0.29.6
 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

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

@@ -1,6 +1,6 @@
 [project]
 name = "vgi-python"
-version = "0.29.4"
+version = "0.29.6"
 description = "Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow"
 readme = "README.md"
 keywords = [

vgi_python-0.29.6/tests/table_in_out/test_blended_exchange.py

@@ -0,0 +1,282 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""RPC-level exchange coverage for blended (`RowTransformFunction`) table functions.
+
+`test_blended_metadata.py` covers `resolve_metadata()` in isolation — no worker
+subprocess. This file is the first exchange-level coverage for the blended
+fixtures registered in `vgi/_test_fixtures/table_in_out.py`: it drives them
+through `Client.table_in_out_function(...)`'s new `parent_row_callback`, which
+decodes `vgi_rpc.parent_row#b64` provenance for a 1->N / 1->0 emit (see
+`vgi.protocol._decode_parent_rows`).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pyarrow as pa
+import pytest
+
+from tests.conftest import make_schema
+from vgi.arguments import Arguments
+from vgi.client import Client
+from vgi.client.client import ClientError
+
+
+class TestBlendedExplodeProvenance:
+    """`blended_explode`: 1->N fan-out with per-output-row parent_row provenance."""
+
+    def test_parent_row_pairing_is_correct(self, fixture_worker: str) -> None:
+        """Each output row's parent index must point at the input row that produced it.
+
+        Asserting only the final row *set* would pass even for a naive
+        "assume identity" implementation whenever fan-out counts differ
+        across rows -- so this reconstructs the exact expected
+        (parent_row, emitted_value) pairs in emission order and compares.
+        """
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        counts = [0, 1, 3, 2]
+        batch = pa.RecordBatch.from_pydict({"n": counts}, schema=input_schema)
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        out = results[0]
+        i_values = out.column("i").to_pylist()
+
+        assert len(i_values) == sum(counts)
+        assert len(parent_rows_seen) == len(i_values)
+
+        expected_pairs = [(row_idx, k) for row_idx, n in enumerate(counts) for k in range(n)]
+        actual_pairs = list(zip(parent_rows_seen, i_values, strict=True))
+        assert actual_pairs == expected_pairs
+
+    def test_all_rows_filtered_to_empty_result(self, fixture_worker: str) -> None:
+        """n=0 for every input row -> a correctly-schemed, zero-row output."""
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"n": [0, 0, 0]}, schema=input_schema)
+
+        parent_rows_seen: list[list[int]] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.append,
+                )
+            )
+
+        assert len(results) == 1
+        out = results[0]
+        assert out.num_rows == 0
+        assert out.schema.names == ["i"]
+        assert parent_rows_seen == [[]]
+
+    def test_identity_map_when_row_counts_match(self, fixture_worker: str) -> None:
+        """n=1 for every row -> a 1:1 emit; the identity map is a valid decode.
+
+        `blended_explode` never encodes `vgi_rpc.parent_row` for a 1:1 emit
+        (the C++ reference assumes identity for that case too), so this
+        exercises `_decode_parent_rows`'s absent-metadata branch, not just
+        the explicit-array branch the other tests exercise.
+        """
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"n": [1, 1, 1]}, schema=input_schema)
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("i").to_pylist() == [0, 0, 0]
+        assert parent_rows_seen == [0, 1, 2]
+
+
+class TestHostileProvenance:
+    """`hostile_provenance`: adversarial worker payloads must raise, never corrupt."""
+
+    @pytest.mark.parametrize("mode", ["range", "length", "base64"])
+    def test_malformed_provenance_raises_client_error(
+        self,
+        client_transport: Any,
+        mode: str,
+    ) -> None:
+        """Each hostile mode must raise ClientError on both subprocess and HTTP.
+
+        Symmetry matters here: an asymmetry between transports would mean one
+        parse path validates and the other doesn't -- a security bug, not
+        just an inconsistency.
+        """
+        input_schema = make_schema([pa.field("x", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"x": [1, 2, 3]}, schema=input_schema)
+
+        with client_transport() as client, pytest.raises(ClientError):
+            list(
+                client.table_in_out_function(
+                    function_name="hostile_provenance",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"mode": pa.scalar(mode)}),
+                    parent_row_callback=lambda _rows: None,
+                )
+            )
+
+    def test_no_callback_no_decode_no_raise(self, fixture_worker: str) -> None:
+        """Without `parent_row_callback`, malformed provenance is never even decoded.
+
+        `decode_parent_rows` is derived from `parent_row_callback is not None`
+        -- this is the backward-compat guarantee that an ordinary (non-blended)
+        table-in-out caller, which never passes the callback, is completely
+        unaffected by this feature existing.
+        """
+        input_schema = make_schema([pa.field("x", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"x": [1, 2, 3]}, schema=input_schema)
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="hostile_provenance",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"mode": pa.scalar("range")}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("hv").to_pylist() == [1, 2, 3]
+
+
+class TestBlendedArityAndVarargs:
+    """Broader coverage once the core provenance mechanism is proven."""
+
+    def test_geo_encode_two_arg_overload(self, fixture_worker: str) -> None:
+        """`geo_encode(lat, lon)` -- the 2-arg overload, identity 1:1 map."""
+        input_schema = make_schema([pa.field("latitude", pa.float64()), pa.field("longitude", pa.float64())])
+        batch = pa.RecordBatch.from_pydict(
+            {"latitude": [52.0, 48.5], "longitude": [13.0, 2.3]},
+            schema=input_schema,
+        )
+
+        parent_rows_seen: list[int] = []
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="geo_encode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"precision": pa.scalar(1)}),
+                    parent_row_callback=parent_rows_seen.extend,
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("geohash").to_pylist() == ["52.0:13.0", "48.5:2.3"]
+        assert parent_rows_seen == [0, 1]
+
+    def test_geo_encode_three_arg_overload(self, fixture_worker: str) -> None:
+        """`geo_encode(lat, lon, alt)` -- same Meta.name, resolved by input arity."""
+        input_schema = make_schema(
+            [
+                pa.field("latitude", pa.float64()),
+                pa.field("longitude", pa.float64()),
+                pa.field("altitude", pa.float64()),
+            ]
+        )
+        batch = pa.RecordBatch.from_pydict(
+            {"latitude": [52.0], "longitude": [13.0], "altitude": [100.0]},
+            schema=input_schema,
+        )
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="geo_encode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"precision": pa.scalar(0)}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("geohash").to_pylist() == ["52.0:13.0:100.0"]
+
+    def test_row_sum_varargs(self, fixture_worker: str) -> None:
+        """`row_sum(a, b, c)` -- varargs positional input, positionally-named columns."""
+        input_schema = make_schema([pa.field("col0", pa.float64()), pa.field("col1", pa.float64())])
+        batch = pa.RecordBatch.from_pydict({"col0": [1.0, -2.0], "col1": [2.0, -3.0]}, schema=input_schema)
+
+        with Client(fixture_worker) as client:
+            results = list(
+                client.table_in_out_function(
+                    function_name="row_sum",
+                    schema_name="main",
+                    input=iter([batch]),
+                    arguments=Arguments(named={"absolute": pa.scalar(True)}),
+                )
+            )
+
+        assert len(results) == 1
+        assert results[0].column("row_sum").to_pylist() == [3.0, 5.0]
+
+
+class TestHasFinalizeSkip:
+    """`has_finalize=False` skips the FINALIZE `init()` entirely for a no-finalize function.
+
+    Real interop bug found live against a non-Python worker SDK: the client
+    unconditionally sent a FINALIZE-phase init() for every table-in-out call,
+    which the Python fixture worker happens to no-op gracefully but a
+    TypeScript-SDK worker rejects outright ("a blended row-transform function
+    has no FINALIZE phase"). `has_finalize=False` avoids sending that init()
+    at all rather than depending on every SDK tolerating an unexpected one.
+    Output must be identical either way for a function that has no finalize
+    stage (there is nothing to skip yielding) -- this is the equivalence this
+    suite can prove locally; the cross-SDK rejection itself is TypeScript-only.
+    """
+
+    def test_output_identical_with_and_without_has_finalize(self, client_transport: Any) -> None:
+        """Same output whether the FINALIZE init() is sent or skipped, both transports."""
+        input_schema = make_schema([pa.field("n", pa.int64())])
+        batch = pa.RecordBatch.from_pydict({"n": [0, 1, 3, 2]}, schema=input_schema)
+
+        with client_transport() as client:
+            with_finalize = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                )
+            )
+        with client_transport() as client:
+            without_finalize = list(
+                client.table_in_out_function(
+                    function_name="blended_explode",
+                    schema_name="main",
+                    input=iter([batch]),
+                    has_finalize=False,
+                )
+            )
+
+        assert len(with_finalize) == 1
+        assert len(without_finalize) == 1
+        assert with_finalize[0].column("i").to_pylist() == without_finalize[0].column("i").to_pylist()

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

@@ -2569,7 +2569,7 @@ requires-dist = [
 
 [[package]]
 name = "vgi-python"
-version = "0.29.4"
+version = "0.29.6"
 source = { editable = "." }
 dependencies = [
     { name = "click" },

{vgi_python-0.29.4 → vgi_python-0.29.6}/vgi/client/client.py

@@ -118,6 +118,7 @@ from vgi.protocol import (
     TableBufferingProcessRequest,
     TableFunctionPlanRequest,
     VgiProtocol,
+    _decode_parent_rows,
 )
 from vgi.table_function import TableInOutFunctionInitPhase
 
@@ -296,6 +297,33 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             return batches[0]
         return combined[0]
 
+    @staticmethod
+    def _combine_parent_rows(parent_rows_batches: list[list[int]]) -> list[int]:
+        """Concatenate per-output-batch parent-row lists in emission order.
+
+        Mirrors `_combine_batches` for blended row-transform provenance: when
+        a table-in-out call produces multiple output batches for one input
+        batch (a worker replying `HAVE_MORE_OUTPUT` more than once), each
+        sub-batch's decoded parent-row list already indexes into that same
+        shipped input batch (see `_decode_parent_rows`'s contract), so
+        concatenating the lists in the order the sub-batches were emitted is
+        sound — no index renumbering is needed, because `_combine_batches`
+        also concatenates the sub-batches themselves in that same order.
+
+        Args:
+            parent_rows_batches: One decoded parent-row list per output
+                sub-batch, in emission order.
+
+        Returns:
+            The concatenated parent-row list, aligned row-for-row with what
+            `_combine_batches` produces from the corresponding output batches.
+
+        """
+        combined: list[int] = []
+        for batch_rows in parent_rows_batches:
+            combined.extend(batch_rows)
+        return combined
+
     @staticmethod
     def _on_worker_log(msg: Message) -> None:
         """Forward log messages from vgi_rpc to the worker logger."""
@@ -1618,7 +1646,9 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         worker: WorkerConnection,
         input_batch: pa.RecordBatch,
         batch_index: int,
-    ) -> list[pa.RecordBatch]:
+        *,
+        decode_parent_rows: bool = False,
+    ) -> tuple[list[pa.RecordBatch], list[list[int]] | None]:
         """Send a batch to a worker and collect all output batches.
 
         Sends the input batch via stream.exchange(), then checks the vgi.status
@@ -1629,19 +1659,32 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             worker: The worker connection to use. Must have stream initialized.
             input_batch: The input `RecordBatch` to send to the worker.
             batch_index: Index of this batch in the input sequence (for logging).
+            decode_parent_rows: When True, additionally decode each output
+                batch's `vgi_rpc.parent_row#b64` metadata (see
+                `vgi.protocol._decode_parent_rows`) — used by blended
+                row-transform table functions, where a worker's output row
+                count need not match its input row count. False for every
+                other table-in-out / scalar caller, which has no provenance
+                concept and must not have the row-count-mismatch check inside
+                `_decode_parent_rows` start firing for it.
 
         Returns:
-            List of output `RecordBatch`es produced by processing this input batch.
+            A tuple of (output batches, per-batch decoded parent-row lists).
+            The second element is `None` when `decode_parent_rows` is False —
+            keeps the common path from building a list it never uses.
 
         Raises:
-            [`ClientError`][]: If worker.stream is None, or if the worker returns
-                an unexpected status, or if the RPC call fails.
+            [`ClientError`][]: If worker.stream is None, if the worker returns
+                an unexpected status, if the RPC call fails, or (when
+                `decode_parent_rows` is True) if `vgi_rpc.parent_row#b64` is
+                malformed or absent-with-mismatched-row-counts.
 
         """
         if worker.stream is None:
             raise ClientError(f"Worker {worker.worker_index} stream not initialized")
 
         output_batches: list[pa.RecordBatch] = []
+        parent_rows_batches: list[list[int]] | None = [] if decode_parent_rows else None
 
         while True:
             _logger.debug(
@@ -1665,6 +1708,18 @@ class Client(CatalogClientMixin, AggregateClientMixin):
 
             output_batches.append(output.batch)
 
+            if parent_rows_batches is not None:
+                try:
+                    parent_rows_batches.append(
+                        _decode_parent_rows(
+                            output.custom_metadata,
+                            output_rows=output.batch.num_rows,
+                            input_rows=input_batch.num_rows,
+                        )
+                    )
+                except RuntimeError as e:
+                    raise ClientError(str(e)) from e
+
             # Check vgi.status for table-in-out status
             status = None
             if output.custom_metadata:
@@ -1678,22 +1733,25 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             else:
                 raise ClientError(f"Unexpected status from worker {worker.worker_index}: {status!r}")
 
-        return output_batches
+        return output_batches, parent_rows_batches
 
     def _worker_thread_loop(
         self,
         worker: WorkerConnection,
         input_queue: Queue[tuple[int, pa.RecordBatch] | None],
-        output_queue: Queue[tuple[int, list[pa.RecordBatch]] | BaseException],
+        output_queue: Queue[tuple[int, list[pa.RecordBatch], list[list[int]] | None] | BaseException],
+        *,
+        decode_parent_rows: bool = False,
     ) -> None:
         """Thread function that processes batches for a single worker.
 
         Runs in a dedicated thread, pulling (batch_index, batch) tuples from
         the input queue, processing them via _process_batch_on_worker, and
-        pushing (batch_index, output_batches) tuples to the output queue.
+        pushing (batch_index, output_batches, parent_rows_batches) tuples to
+        the output queue.
 
         When None is received from input_queue, signals thread completion by
-        pushing (-1, []) to output_queue and exits.
+        pushing (-1, [], None) to output_queue and exits.
 
         If an exception occurs during processing, it is caught, logged, and
         pushed to output_queue as the exception object itself.
@@ -1703,6 +1761,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             input_queue: Thread-safe queue providing (batch_index, `RecordBatch`)
                 tuples for processing. A None value signals end of input.
             output_queue: Thread-safe queue for results.
+            decode_parent_rows: Forwarded to `_process_batch_on_worker` — see
+                its docstring.
 
         """
         try:
@@ -1710,12 +1770,14 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 item = input_queue.get()
                 if item is None:
                     # End of input - signal thread completion
-                    output_queue.put((-1, []))
+                    output_queue.put((-1, [], None))
                     break
 
                 batch_index, input_batch = item
-                outputs = self._process_batch_on_worker(worker, input_batch, batch_index)
-                output_queue.put((batch_index, outputs))
+                outputs, parent_rows_batches = self._process_batch_on_worker(
+                    worker, input_batch, batch_index, decode_parent_rows=decode_parent_rows
+                )
+                output_queue.put((batch_index, outputs, parent_rows_batches))
         except Exception as e:
             _logger.exception("worker_thread_error worker_index=%s", worker.worker_index)
             output_queue.put(e)
@@ -1726,6 +1788,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         all_workers: list[WorkerConnection],
         first_batch: pa.RecordBatch,
         remaining_input: Iterator[pa.RecordBatch],
+        decode_parent_rows: bool = False,
+        parent_row_callback: Callable[[list[int]], None] | None = None,
     ) -> Generator[pa.RecordBatch]:
         """Distribute input batches round-robin across workers and collect output.
 
@@ -1738,6 +1802,15 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             first_batch: The first input batch, already consumed from the
                 iterator by the calling method.
             remaining_input: Iterator for remaining input batches.
+            decode_parent_rows: See `_process_batch_on_worker`. Forwarded to
+                every worker thread; False (the default) preserves today's
+                behavior exactly for every existing caller.
+            parent_row_callback: Optional callback invoked once per yielded
+                output batch, immediately before the yield, with that batch's
+                combined parent-row list (see `_combine_parent_rows`) — the
+                same "callback then yield" contract `table_function`'s
+                `batch_metadata_callback` uses. Only meaningful when
+                `decode_parent_rows` is True; ignored otherwise.
 
         Yields:
             Output `RecordBatch`es from processing. When multiple batches are
@@ -1754,7 +1827,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
 
         # Create queues for each worker
         input_queues: list[Queue[tuple[int, pa.RecordBatch] | None]] = [Queue() for _ in range(num_workers)]
-        output_queue: Queue[tuple[int, list[pa.RecordBatch]] | BaseException] = Queue()
+        output_queue: Queue[tuple[int, list[pa.RecordBatch], list[list[int]] | None] | BaseException] = Queue()
 
         # Start worker threads
         threads: list[threading.Thread] = []
@@ -1762,6 +1835,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             thread = threading.Thread(
                 target=self._worker_thread_loop,
                 args=(worker, input_queues[i], output_queue),
+                kwargs={"decode_parent_rows": decode_parent_rows},
                 daemon=True,
             )
             thread.start()
@@ -1804,12 +1878,14 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                     raise ClientError.from_rpc_error(result) from result
                 raise ClientError(f"Worker thread failed: {result}") from result
 
-            batch_idx, output_batches = result
+            batch_idx, output_batches, parent_rows_batches = result
             outputs_received += 1
 
             # Combine output batches if needed
             combined = self._combine_batches(output_batches)
             if combined is not None:
+                if decode_parent_rows and parent_row_callback is not None and parent_rows_batches is not None:
+                    parent_row_callback(self._combine_parent_rows(parent_rows_batches))
                 yield combined
 
             _logger.debug(
@@ -1838,6 +1914,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
         pushdown_filters: bytes | None = None,
         settings: dict[str, Any] | None = None,
         transaction_opaque_data: bytes | None = None,
+        parent_row_callback: Callable[[list[int]], None] | None = None,
+        has_finalize: bool = True,
     ) -> Generator[pa.RecordBatch]:
         """Invoke a table-in-out function on the worker and stream results.
 
@@ -1865,6 +1943,34 @@ class Client(CatalogClientMixin, AggregateClientMixin):
             settings: Optional dictionary of settings/pragmas to
                 pass to the function.
             transaction_opaque_data: Optional unique identifier for the DuckDB transaction.
+            parent_row_callback: Optional callback invoked once per yielded
+                output batch (before finalize), immediately before the yield,
+                with that batch's decoded `vgi_rpc.parent_row` provenance —
+                `parent_rows[i]` is the 0-based index into the input batch
+                that produced output row `i`. Passing this switches on
+                provenance decoding: a batch with no `vgi_rpc.parent_row`
+                metadata is only accepted when its row count matches the
+                input batch's (raising `ClientError` otherwise), since a
+                worker changing row count without provenance is a worker bug
+                for a function that opted into this contract. Intended for
+                blended row-transform functions (`RowTransformFunction`,
+                `FunctionInfo.input_from_args`); leave unset for ordinary
+                table-in-out functions, which have no provenance concept and
+                may legitimately change row count.
+            has_finalize: Whether this function declares a FINALIZE stage
+                (`FunctionInfo.has_finalize`). Defaults to `True` — every
+                caller before this parameter existed got a FINALIZE-phase
+                `init()` unconditionally, so this preserves that exactly.
+                Pass `False` for a function known to have no finalize (every
+                blended `RowTransformFunction` — `has_finalize` is always
+                false for those, enforced at `resolve_metadata()`) to skip
+                the FINALIZE `init()` entirely, not just send one expecting
+                an empty reply. Confirmed load-bearing, not cosmetic: some
+                worker SDKs (e.g. the TypeScript one) actively reject an
+                unexpected FINALIZE `init()` for a function that never
+                advertised `has_finalize`, rather than silently no-op'ing
+                it — the C++ DuckDB extension avoids this the same way, by
+                conditionally registering `in_out_function_final` at all.
 
         Yields:
             Output `RecordBatch`es from the function. In single-worker mode, output
@@ -1915,6 +2021,8 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                     all_workers=all_workers,
                     first_batch=first_batch,
                     remaining_input=input,
+                    decode_parent_rows=parent_row_callback is not None,
+                    parent_row_callback=parent_row_callback,
                 )
 
                 # Close all input streams
@@ -1926,7 +2034,14 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 # Close secondary workers
                 self._close_secondary_workers()
 
-                # Finalize on primary worker
+                # Finalize on primary worker — skipped entirely (not just
+                # sent expecting an empty reply) when the function has no
+                # finalize stage. See has_finalize's docstring: some worker
+                # SDKs reject an unadvertised FINALIZE init() outright.
+                if not has_finalize:
+                    _logger.debug("skipping_finalize_no_finalize_stage")
+                    return
+
                 _logger.debug("finalizing_primary_worker")
                 yield from self._finalize_primary_worker(
                     bind_request,
@@ -2299,7 +2414,7 @@ class Client(CatalogClientMixin, AggregateClientMixin):
                 cursor=cursor,
             )
             try:
-                response: PlanResponse = self._primary.proxy.table_function_plan(request=plan_request)  # type: ignore[assignment]
+                response: PlanResponse = self._primary.proxy.table_function_plan(request=plan_request)
             except RpcError as e:
                 raise ClientError.from_rpc_error(e) from e