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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.29.4
+Version: 0.29.5
 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.5}/pyproject.toml

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

vgi_python-0.29.5/tests/table_in_out/test_blended_exchange.py

@@ -0,0 +1,240 @@
+# 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]

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

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

{vgi_python-0.29.4 → vgi_python-0.29.5}/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,7 @@ 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,
     ) -> Generator[pa.RecordBatch]:
         """Invoke a table-in-out function on the worker and stream results.
 
@@ -1865,6 +1942,20 @@ 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.
 
         Yields:
             Output `RecordBatch`es from the function. In single-worker mode, output
@@ -1915,6 +2006,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
@@ -2299,7 +2392,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
 

{vgi_python-0.29.4 → vgi_python-0.29.5}/vgi/protocol.py

@@ -24,6 +24,7 @@ StreamState Implementations
 from __future__ import annotations
 
 import base64
+import binascii
 import contextlib
 import dataclasses
 import logging
@@ -1516,6 +1517,80 @@ def _merge_parent_rows(
     return merged
 
 
+def _decode_parent_rows(
+    metadata: pa.KeyValueMetadata | None,
+    *,
+    output_rows: int,
+    input_rows: int,
+) -> list[int]:
+    """Decode ``vgi_rpc.parent_row#b64`` from an exchange output batch's metadata.
+
+    The client-side counterpart to :func:`_merge_parent_rows` above — ported
+    from the VGI DuckDB extension's own reference decoder
+    (``vgi_lateral_batch_operator.cpp``'s ``DecodeParentRow``) byte-for-byte,
+    since a wrong or malformed ``parent_row`` array is not a missed
+    optimization the way most other worker-declared metadata is: the caller
+    has no independent way to recompute which output row came from which
+    input row, so an unvalidated value here would produce silent data
+    corruption (or an out-of-bounds read) rather than a merely suboptimal
+    result. Every check below is load-bearing, not defensive polish.
+
+    Args:
+        metadata: The output batch's ``custom_metadata``, or ``None``.
+        output_rows: Row count of the output batch this metadata came with.
+        input_rows: Row count of the input batch shipped for this call.
+
+    Returns:
+        ``parent_rows[i]`` = the 0-based index into the input batch that
+        produced output row ``i``. Always a concrete list — absent metadata
+        synthesizes the identity map (only valid when ``output_rows ==
+        input_rows``, else it's a raise, not a ``None``; see below).
+
+    Raises:
+        RuntimeError: If the metadata is malformed, or if it's absent but
+            the row counts don't match (a worker emitting a different row
+            count without provenance is a worker bug, not something to
+            silently paper over).
+
+    """
+    if output_rows == 0:
+        # Unambiguous regardless of input_rows or whether metadata is present:
+        # a 0-row emit is a legitimate 1->0 filter (every input row dropped),
+        # and _merge_parent_rows never encodes vgi_rpc.parent_row for an empty
+        # emit in the first place (see its own `batch.num_rows == 0` branch) --
+        # so this must be checked BEFORE the absent-metadata row-count-mismatch
+        # check below, or a fully-filtered batch would wrongly look like a
+        # worker bug.
+        return []
+
+    raw_b64 = metadata.get(b"vgi_rpc.parent_row#b64") if metadata else None
+    if raw_b64 is None:
+        if output_rows != input_rows:
+            raise RuntimeError(
+                f"worker returned {output_rows} output row(s) for {input_rows} input row(s) "
+                "without vgi_rpc.parent_row provenance; a fan-out (1->N) or filtering (1->0) "
+                "blended row-transform emit must carry per-output-row parent indices"
+            )
+        return list(range(output_rows))
+
+    try:
+        raw = base64.b64decode(raw_b64, validate=True)
+    except (binascii.Error, ValueError) as e:
+        raise RuntimeError(f"vgi_rpc.parent_row#b64 is not valid base64: {e}") from e
+
+    expected_len = output_rows * 4
+    if len(raw) != expected_len:
+        raise RuntimeError(
+            f"vgi_rpc.parent_row is {len(raw)} byte(s) for {output_rows} output row(s) (expected {expected_len})"
+        )
+
+    values = struct.unpack(f"<{output_rows}i", raw)
+    for i, v in enumerate(values):
+        if v < 0 or v >= input_rows:
+            raise RuntimeError(f"parent_row[{i}] = {v} is out of range [0, {input_rows})")
+    return list(values)
+
+
 def _merge_cache_control(
     *,
     cache_control: CacheControl | None,