vgi-python 0.46.0__tar.gz → 0.47.0__tar.gz

{vgi_python-0.46.0 → vgi_python-0.47.0}/.github/workflows/integration.yml

@@ -27,7 +27,7 @@ concurrency:
 env:
   # The test suite and native Actions artifact must come from this exact ref.
   # The downloader verifies its provenance against the checked-out commit.
-  VGI_REF: 3a2249f815ff6e2a8b5289a3e6284326084e3630
+  VGI_REF: fc3e08f7e7fd800165a0edc00313de46fed15329
   # CI is not a user: its ATTACHes should not land in Query.Farm's adoption data.
   # The vgi extension fires a telemetry event per successful ATTACH, and this
   # suite performs several hundred of them per lane, so opting out keeps the

{vgi_python-0.46.0 → vgi_python-0.47.0}/PKG-INFO

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

{vgi_python-0.46.0 → vgi_python-0.47.0}/docs/generator-api.md

@@ -275,15 +275,33 @@ class SumFunction(TableInOutFunction):
         )]
 ```
 
-**Multiple outputs per input (HAVE_MORE_OUTPUT status):**
-```python
-from vgi_rpc.rpc import OutputCollector
+**Multiple outputs per input (`more=True` and `resume()`):**
 
-def process(cls, params, state, batch, out: OutputCollector) -> None:
-    # Emit multiple batches for one input by setting vgi.status metadata
-    out.emit(batch, custom_metadata={b"vgi.status": b"HAVE_MORE_OUTPUT"})
+Each call still emits exactly one batch. To return several for one input
+batch, emit the first with `more=True`; the framework then calls `resume()`,
+with no input, for each next batch until one is emitted without `more=True`.
+`resume()` continues from `state` alone, so the function must declare a
+serializable `TState`; over HTTP it travels in the stream's state token, so
+store positions to resume from, not output rows. A function with `resume()`
+cannot set `max_workers = 1`: the client runs such a function on one connection
+shared by every pipeline, which cannot leave output pending.
+
+```python test="skip"
+@classmethod
+def process(cls, params, state, batch, out) -> None:
+    state.pages = plan_pages(batch)  # where each page starts: small
+    cls.resume(params, state, out)
+
+@classmethod
+def resume(cls, params, state, out) -> None:
+    page = fetch(state.pages.pop(0))
+    out.emit(page.batch, parent_rows=page.parent_rows, more=bool(state.pages))
 ```
 
+On the wire the reply carries `vgi.status: HAVE_MORE_OUTPUT` and the client
+asks for the next batch with a zero-row input carrying `vgi.status: CONTINUE`.
+While output is pending that tick is the only valid input.
+
 **In-band logging via OutputCollector:**
 ```python
 from vgi_rpc.rpc import OutputCollector

{vgi_python-0.46.0 → vgi_python-0.47.0}/docs/metadata.md

@@ -80,6 +80,7 @@ info = SumValuesFunction.describe()
 | `tags` | `dict[str, str]` | `{}` | Custom key-value tags |
 | `examples` | `list` | `[]` | SQL examples (str or FunctionExample) |
 | `max_workers` | `int\|None` | `None` (unlimited) | Max parallel workers |
+| `input_rows_per_call` | `int\|None` | `None` (a whole chunk) | `RowTransformFunction` only: most input rows per worker call; the client splits each chunk into calls of at most this many rows |
 | `stability` | `FunctionStability` | `CONSISTENT` | Output determinism |
 | `null_handling` | `NullHandling` | `DEFAULT` | NULL input behavior |
 | `argument_monotonicity` | `list[ArgumentMonotonicity]\|None` | `None` | Scalar-only monotonicity claims in argument declaration order |

vgi_python-0.47.0/examples/paged_api_worker.py

@@ -0,0 +1,117 @@
+# /// script
+# requires-python = ">=3.13"
+# dependencies = ["vgi-python"]
+# ///
+"""A lateral function backed by a paged API, returning one API page per reply.
+
+``orders(customer_id)`` lists a customer's orders from an API that returns them a
+page at a time behind a cursor. Rather than fetching every page before replying,
+``process()`` fetches the first page and emits it with ``more=True``; the framework
+then calls ``resume()`` for each next page. The state holds only where to resume
+(which input row, which page cursor), never fetched rows, so it is small enough to
+travel in an HTTP state token.
+
+    ATTACH 'shop' (TYPE vgi, LOCATION 'uv run paged_api_worker.py');
+    SELECT c.id, o.order_id, o.total
+    FROM (VALUES (1), (2), (3)) c(id), shop.orders(c.id) o;
+"""
+
+from dataclasses import dataclass
+from typing import Annotated, Any, cast
+
+import pyarrow as pa
+from vgi_rpc import ArrowSerializableDataclass
+
+from vgi import Arg, Worker
+from vgi.catalog import Catalog, Schema
+from vgi.invocation import BindResponse
+from vgi.table_function import BindParams, ProcessParams
+from vgi.table_in_out_function import OutputCollector, RowTransformFunction
+
+PAGE_SIZE = 5
+
+
+def fetch_orders_page(customer_id: int, cursor: str) -> tuple[list[dict[str, Any]], str]:
+    """Stand-in for an HTTP API: one page of a customer's orders and the next cursor.
+
+    Customer ``n`` has ``7 * n`` orders. An empty next cursor means the last page.
+    """
+    start = int(cursor or "0")
+    total = 7 * customer_id
+    orders = [
+        {"order_id": customer_id * 1000 + k, "total": round(10.0 + k * 2.5, 2)}
+        for k in range(start, min(start + PAGE_SIZE, total))
+    ]
+    end = start + len(orders)
+    return orders, str(end) if end < total else ""
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class OrdersArgs:
+    """One positional input column: the customer to list orders for."""
+
+    customer_id: Annotated[int, Arg(0, doc="Customer whose orders to list")]
+
+
+@dataclass(kw_only=True)
+class OrdersCursor(ArrowSerializableDataclass):
+    """Where the next reply resumes: the input's customer ids, a row, and that row's page cursor."""
+
+    customer_ids: list[int] | None = None
+    row: int = 0
+    cursor: str = ""
+
+
+class Orders(RowTransformFunction[OrdersArgs, OrdersCursor]):
+    """List each input customer's orders, one API page per reply."""
+
+    @classmethod
+    def on_bind(cls, params: BindParams[OrdersArgs]) -> BindResponse:
+        """A fixed output schema."""
+        return BindResponse(output_schema=pa.schema([("order_id", pa.int64()), ("total", pa.float64())]))
+
+    @classmethod
+    def initial_state(cls, params: ProcessParams[OrdersArgs]) -> OrdersCursor:
+        """An empty cursor; ``process()`` fills it for each input batch."""
+        return OrdersCursor()
+
+    @classmethod
+    def process(
+        cls, params: ProcessParams[OrdersArgs], state: OrdersCursor, batch: pa.RecordBatch, out: OutputCollector
+    ) -> None:
+        """Start a new input batch at its first row, then emit the first page."""
+        state.customer_ids = [-1 if c is None else c for c in batch.column("customer_id").to_pylist()]
+        state.row = 0
+        state.cursor = ""
+        cls.resume(params, state, out)
+
+    @classmethod
+    def resume(cls, params: ProcessParams[OrdersArgs], state: OrdersCursor, out: OutputCollector) -> None:
+        """Emit the next non-empty page, with ``more=True`` unless it is the last."""
+        ids = state.customer_ids or []
+        orders: list[dict[str, Any]] = []
+        row = state.row
+        while state.row < len(ids) and not orders:
+            row = state.row
+            orders, state.cursor = fetch_orders_page(ids[row], state.cursor) if ids[row] > 0 else ([], "")
+            if not state.cursor:  # that customer is done: the next page starts the next row
+                state.row += 1
+        # Every row of a page came from one input row; parent_rows says which.
+        cast(Any, out).emit(
+            pa.RecordBatch.from_pylist(orders, schema=params.output_schema),
+            parent_rows=[row] * len(orders),
+            more=state.row < len(ids),
+        )
+
+
+class ShopWorker(Worker):
+    """A worker exposing the ``shop`` catalog with the paged ``orders`` function."""
+
+    catalog = Catalog(
+        name="shop",
+        schemas=[Schema(path=["main"], functions=[Orders])],
+    )
+
+
+if __name__ == "__main__":
+    ShopWorker().run()

{vgi_python-0.46.0 → vgi_python-0.47.0}/packages/vgi-fixtures/pyproject.toml

@@ -8,7 +8,7 @@
 # and the conformance suite import it by its normal `vgi._test_fixtures` path.
 [project]
 name = "vgi-fixtures"
-version = "0.46.0"
+version = "0.47.0"
 description = "Example/test VGI worker modules and entry points (not for production use)"
 readme = "README.md"
 # Local copy of the repo-root LICENSE (kept in sync): the build can't reach

{vgi_python-0.46.0 → vgi_python-0.47.0}/pyproject.toml

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

{vgi_python-0.46.0 → vgi_python-0.47.0}/scripts/regen_generated.py

@@ -16,7 +16,11 @@ and only then written.
 
 Targets in sibling repos that are not checked out are skipped, not failed:
 nobody has all of them. A registry backend's ``root_env`` (``VGI_JAVA_ROOT``,
-``VGI_TYPESCRIPT_ROOT``, ...) points its SDK target at another checkout.
+``VGI_TYPESCRIPT_ROOT``, ...) points its SDK target at another checkout, as does
+``--root REPO=PATH``. ``--only REPO`` (repeatable) limits the run to those repos,
+so regenerating one SDK's worktree writes nothing into any other checkout:
+
+    uv run python scripts/regen_generated.py --only vgi-go --root vgi-go=~/Development/vgi-go-feature
 """
 
 from __future__ import annotations
@@ -96,9 +100,9 @@ _ROOT_ENV: dict[str, str] = {b.repo: b.root_env for b in _REGISTRY_BACKENDS}
 _ROOT_ENV.setdefault("vgi", "VGI_EXTENSION_ROOT")
 
 
-def _repo_root(name: str) -> Path | None:
+def _repo_root(name: str, roots: dict[str, str]) -> Path | None:
     """Locate a sibling checkout, or ``None`` when it is not present."""
-    override = os.environ.get(_ROOT_ENV.get(name, ""))
+    override = roots.get(name) or os.environ.get(_ROOT_ENV.get(name, ""))
     if override:
         return Path(override) if Path(override).is_dir() else None
     siblings = Path(__file__).resolve().parents[2]
@@ -135,12 +139,38 @@ def main() -> int:
         action="store_true",
         help="report drift without writing anything (exit 1 if any file is stale)",
     )
+    parser.add_argument(
+        "--only",
+        action="append",
+        default=[],
+        metavar="REPO",
+        help="only these repos' targets (repeatable), e.g. --only vgi-go",
+    )
+    parser.add_argument(
+        "--root",
+        action="append",
+        default=[],
+        metavar="REPO=PATH",
+        help="the checkout to use for REPO (repeatable), e.g. --root vgi-go=../vgi-go-feature",
+    )
     args = parser.parse_args()
+    known = {repo for _, _, repo in _TARGETS}
+    unknown = set(args.only) - known
+    if unknown:
+        parser.error(f"--only: unknown repo(s) {sorted(unknown)}; known: {sorted(known)}")
+    roots: dict[str, str] = {}
+    for spec in args.root:
+        repo, sep, path = spec.partition("=")
+        if not sep or repo not in known:
+            parser.error(f"--root expects REPO=PATH with REPO one of {sorted(known)}, got {spec!r}")
+        roots[repo] = str(Path(path).expanduser())
 
     stale, wrote, skipped, failed = [], [], [], []
 
     for module_name, relative, repo in _TARGETS:
-        root = _repo_root(repo)
+        if args.only and repo not in args.only:
+            continue
+        root = _repo_root(repo, roots)
         if root is None:
             skipped.append(f"{repo} (not checked out)")
             continue

vgi_python-0.47.0/tests/table_in_out/test_continuation.py

@@ -0,0 +1,391 @@
+# Copyright 2025, 2026 Query Farm LLC - https://query.farm
+
+"""Continued output: several replies for one table-in-out input batch.
+
+A function emits ``out.emit(..., more=True)`` and the framework calls its
+``resume()`` for each next batch. Each batch is its own reply; the client
+fetches the next one with a zero-row ``vgi.status: CONTINUE`` tick.
+``blended_paged`` is the fixture: ``blended_explode``'s output, ``page_size``
+rows per reply.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Annotated, Any
+
+import pyarrow as pa
+import pytest
+from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.rpc import AnnotatedBatch, OutputCollector
+
+from tests.conftest import make_schema
+from vgi.arguments import Arg, Arguments, TableInput
+from vgi.cache_control import CacheControl
+from vgi.client import Client
+from vgi.client.client import ClientError
+from vgi.invocation import BindResponse
+from vgi.metadata import resolve_metadata
+from vgi.protocol import (
+    CONTINUE,
+    STATUS_KEY,
+    _FilteringOutputCollector,
+    _TrackingOutputCollector,
+)
+from vgi.schema_utils import schema
+from vgi.table_function import BindParams, ProcessParams
+from vgi.table_in_out_function import RowTransformFunction, TableInOutGenerator
+
+_INPUT_SCHEMA = make_schema([pa.field("n", pa.int64())])
+
+
+def _expected_pairs(counts: Sequence[int | None]) -> list[tuple[int, int]]:
+    return [(row, k) for row, n in enumerate(counts) for k in range(n or 0)]
+
+
+def _run_paged(
+    client: Client,
+    monkeypatch: pytest.MonkeyPatch,
+    batches: Sequence[Sequence[int | None]],
+    page_size: int,
+) -> tuple[list[tuple[int, int]], list[int]]:
+    """Run ``blended_paged``; return (parent_row, value) pairs and replies per input batch."""
+    replies: list[int] = []
+    original = Client._process_batch_on_worker
+
+    def counting(self: Client, *args: Any, **kwargs: Any) -> Any:
+        outputs, parent_rows = original(self, *args, **kwargs)
+        replies.append(len(outputs))
+        return outputs, parent_rows
+
+    monkeypatch.setattr(Client, "_process_batch_on_worker", counting)
+    parent_rows_seen: list[int] = []
+    with client:
+        results = list(
+            client.table_in_out_function(
+                function_name="blended_paged",
+                schema_path=["main"],
+                input=iter(
+                    [pa.RecordBatch.from_pydict({"n": list(counts)}, schema=_INPUT_SCHEMA) for counts in batches]
+                ),
+                arguments=Arguments(named={"page_size": pa.scalar(page_size)}),
+                parent_row_callback=parent_rows_seen.extend,
+            )
+        )
+    values: list[Any] = [v for batch in results for v in batch.column("i").to_pylist()]
+    return list(zip(parent_rows_seen, values, strict=True)), replies
+
+
+class TestContinuedOutput:
+    """A client that accepts more output gets one reply per page."""
+
+    def test_pages_cover_the_output_in_order(
+        self, client_transport: Callable[[], Client], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Every transport, including HTTP, where the cursor rides the state token."""
+        counts = [0, 1, 3, 2, 0, 4]
+        pairs, replies = _run_paged(client_transport(), monkeypatch, [counts], page_size=2)
+        assert pairs == _expected_pairs(counts)
+        assert replies == [5]  # 10 rows, 2 per reply
+
+    def test_each_input_batch_pages_independently(
+        self, client_transport: Callable[[], Client], monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """A second input batch starts over: provenance indexes its own rows."""
+        pairs, replies = _run_paged(client_transport(), monkeypatch, [[3], [1, 2]], page_size=2)
+        assert pairs == _expected_pairs([3]) + _expected_pairs([1, 2])
+        assert replies == [2, 2]
+
+    @pytest.mark.parametrize(("page_size", "expected_replies"), [(1, 10), (3, 4), (4, 3), (10, 1), (100, 1)])
+    def test_page_size_sets_the_reply_count(
+        self,
+        client_transport: Callable[[], Client],
+        monkeypatch: pytest.MonkeyPatch,
+        page_size: int,
+        expected_replies: int,
+    ) -> None:
+        """10 output rows: one reply per page_size rows, pages crossing input rows."""
+        counts = [0, 1, 3, 2, 0, 4]
+        pairs, replies = _run_paged(client_transport(), monkeypatch, [counts], page_size=page_size)
+        assert pairs == _expected_pairs(counts)
+        assert replies == [expected_replies]
+
+    def test_null_and_trailing_empty_rows_add_no_reply(
+        self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """NULL counts as 0, and rows with no output after the last page add no empty reply."""
+        counts: list[int | None] = [None, 2, 0, 0]
+        pairs, replies = _run_paged(Client(fixture_worker), monkeypatch, [counts], page_size=2)
+        assert pairs == _expected_pairs(counts)
+        assert replies == [1]
+
+    def test_invalid_page_size_is_refused_at_bind(self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """page_size := 0 fails at bind, before any exchange."""
+        with pytest.raises(ClientError, match="page_size must be at least 1"):
+            _run_paged(Client(fixture_worker), monkeypatch, [[3]], page_size=0)
+
+    def test_output_that_fits_one_page_is_one_reply(self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A function that never says more=True answers with a single reply."""
+        pairs, replies = _run_paged(Client(fixture_worker), monkeypatch, [[2, 1]], page_size=10)
+        assert pairs == _expected_pairs([2, 1])
+        assert replies == [1]
+
+    def test_no_output_is_one_empty_reply(self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """No output rows at all is one empty reply, not a page followed by an empty one."""
+        pairs, replies = _run_paged(Client(fixture_worker), monkeypatch, [[0, 0]], page_size=2)
+        assert pairs == []
+        assert replies == [1]
+
+
+def _tick() -> AnnotatedBatch:
+    return AnnotatedBatch(
+        batch=pa.RecordBatch.from_pydict({"n": []}, schema=_INPUT_SCHEMA),
+        custom_metadata=pa.KeyValueMetadata({STATUS_KEY: CONTINUE}),
+    )
+
+
+def _real(*counts: int) -> AnnotatedBatch:
+    return AnnotatedBatch(batch=pa.RecordBatch.from_pydict({"n": list(counts)}, schema=_INPUT_SCHEMA))
+
+
+class TestOutOfTurnInput:
+    """While output is pending only a tick is valid, and a tick only then."""
+
+    @staticmethod
+    def _send(fixture_worker: str, monkeypatch: pytest.MonkeyPatch, sequence: list[AnnotatedBatch]) -> None:
+        """Send ``sequence`` raw on one blended_paged stream (page_size 2); the last must be refused."""
+
+        def send(self: Client, worker: Any, input_batch: pa.RecordBatch, *args: Any, **kwargs: Any) -> Any:
+            from vgi_rpc.rpc import RpcError
+
+            try:
+                for batch in sequence:
+                    worker.stream.exchange(batch)
+            except RpcError as e:
+                raise ClientError.from_rpc_error(e) from e
+            raise AssertionError("the worker accepted out-of-turn input")
+
+        monkeypatch.setattr(Client, "_process_batch_on_worker", send)
+        with Client(fixture_worker) as client:
+            list(
+                client.table_in_out_function(
+                    function_name="blended_paged",
+                    schema_path=["main"],
+                    input=iter([_real(3).batch]),
+                )
+            )
+
+    def test_tick_without_pending_output_is_refused(self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """A tick before any reply said HAVE_MORE_OUTPUT is a protocol error."""
+        with pytest.raises(ClientError, match="no output is pending"):
+            self._send(fixture_worker, monkeypatch, [_tick()])
+
+    def test_tick_after_the_last_page_is_refused(self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        """3 rows in pages of 2: the second reply is the last, so a third tick is refused."""
+        with pytest.raises(ClientError, match="no output is pending"):
+            self._send(fixture_worker, monkeypatch, [_real(3), _tick(), _tick()])
+
+    def test_input_while_output_is_pending_is_refused(
+        self, fixture_worker: str, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Skipping the pending pages with new input would lose them: refused."""
+        with pytest.raises(ClientError, match="while output is pending"):
+            self._send(fixture_worker, monkeypatch, [_real(3), _real(1)])
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _NArgs:
+    n: Annotated[int, Arg(0)]
+
+
+@dataclass(slots=True, frozen=True, kw_only=True)
+class _TableArgs:
+    data: Annotated[TableInput, Arg(0)]
+
+
+@dataclass(kw_only=True)
+class _CursorState(ArrowSerializableDataclass):
+    row: int = 0
+
+
+class TestResumeRegistration:
+    """resume() continues from state alone, so it needs a serializable TState."""
+
+    def test_resume_without_state_is_refused(self) -> None:
+        """Without a TState the cursor would be lost between HTTP turns."""
+
+        class _Stateless(RowTransformFunction[_NArgs]):
+            class Meta:
+                name = "stateless_resume"
+
+            @classmethod
+            def on_bind(cls, params: BindParams[_NArgs]) -> BindResponse:
+                return BindResponse(output_schema=schema({"i": pa.int64()}))
+
+            @classmethod
+            def resume(cls, params: ProcessParams[_NArgs], state: None, out: OutputCollector) -> None:
+                pass
+
+        with pytest.raises(TypeError, match="serializable TState"):
+            resolve_metadata(_Stateless)
+
+    def test_resume_with_max_workers_1_is_refused(self) -> None:
+        """max_workers = 1 runs on one shared connection, which cannot continue."""
+
+        class _Serial(RowTransformFunction[_NArgs, _CursorState]):
+            class Meta:
+                name = "serial_resume"
+                max_workers = 1
+
+            @classmethod
+            def on_bind(cls, params: BindParams[_NArgs]) -> BindResponse:
+                return BindResponse(output_schema=schema({"i": pa.int64()}))
+
+            @classmethod
+            def resume(cls, params: ProcessParams[_NArgs], state: _CursorState, out: OutputCollector) -> None:
+                pass
+
+        with pytest.raises(TypeError, match="max_workers = 1"):
+            resolve_metadata(_Serial)
+
+    def test_resume_with_state_resolves(self) -> None:
+        """RowTransformFunction[Args, State] is the supported shape."""
+
+        class _Stateful(RowTransformFunction[_NArgs, _CursorState]):
+            class Meta:
+                name = "stateful_resume"
+
+            @classmethod
+            def on_bind(cls, params: BindParams[_NArgs]) -> BindResponse:
+                return BindResponse(output_schema=schema({"i": pa.int64()}))
+
+            @classmethod
+            def resume(cls, params: ProcessParams[_NArgs], state: _CursorState, out: OutputCollector) -> None:
+                pass
+
+        assert resolve_metadata(_Stateful).input_from_args is True
+
+
+class _RecordingCollector:
+    def __init__(self) -> None:
+        self.emits: list[dict[str, Any]] = []
+
+    def emit(self, batch: pa.RecordBatch, **kwargs: Any) -> None:
+        self.emits.append({"batch": batch, **kwargs})
+
+
+class _MaskFilters:
+    """Stands in for PushdownFilters: keeps the rows a fixed mask selects."""
+
+    def __init__(self, mask: list[bool]) -> None:
+        self._mask = pa.array(mask)
+
+    def __bool__(self) -> bool:
+        return True
+
+    def evaluate(self, batch: pa.RecordBatch) -> pa.BooleanArray:
+        return self._mask
+
+
+class TestFilteredProvenance:
+    """Auto-applied filters must drop the parent_rows of the rows they drop."""
+
+    def test_parent_rows_follow_the_filter(self) -> None:
+        """Filtering rows 1 and 3 drops their provenance; more= passes through."""
+        inner = _RecordingCollector()
+        out = _FilteringOutputCollector(inner, RowTransformFunction, _MaskFilters([True, False, True, False]))  # type: ignore[arg-type]
+        out.emit(pa.record_batch({"i": [10, 11, 12, 13]}), parent_rows=[0, 0, 1, 2], more=True)
+        [emit] = inner.emits
+        assert emit["batch"].column("i").to_pylist() == [10, 12]
+        assert emit["parent_rows"] == [0, 1]
+        assert emit["more"] is True
+
+
+class _FakeOut:
+    """The innermost collector: records what reaches the wire."""
+
+    def __init__(self) -> None:
+        self.emits: list[tuple[pa.RecordBatch, dict[str, str] | None]] = []
+        self.output_schema = pa.schema([pa.field("i", pa.int64())])
+        self.finished = False
+
+    def emit(self, batch: pa.RecordBatch, metadata: dict[str, str] | None = None) -> None:
+        self.emits.append((batch, metadata))
+
+
+def _rows(*values: int) -> pa.RecordBatch:
+    return pa.record_batch({"i": pa.array(values, type=pa.int64())})
+
+
+class TestCollectors:
+    """The tracking collector's continuation rules."""
+
+    def test_more_sets_have_more_output(self) -> None:
+        """more=True is the reply's vgi.status, and the collector remembers it."""
+        fake = _FakeOut()
+        out = _TrackingOutputCollector(fake, allows_more=True)  # type: ignore[arg-type]
+        out.emit(_rows(1), more=True)
+        assert out.more is True
+        assert fake.emits[0][1] == {"vgi.status": "HAVE_MORE_OUTPUT"}
+
+    def test_more_is_refused_outside_a_table_in_out_exchange(self) -> None:
+        """Only a table-in-out exchange is ever ticked, so more=True elsewhere is an error."""
+        fake = _FakeOut()
+        out = _TrackingOutputCollector(fake)  # type: ignore[arg-type]
+        with pytest.raises(ValueError, match="only valid in a table-in-out"):
+            out.emit(_rows(1), more=True)
+        assert fake.emits == []
+
+    def test_cache_control_is_refused_on_a_continuation(self) -> None:
+        """A reply to a tick is never an input's first batch, so it can't carry cache_control."""
+        out = _TrackingOutputCollector(_FakeOut(), continuation=True)  # type: ignore[arg-type]
+        with pytest.raises(RuntimeError, match="only valid on the first emitted batch"):
+            out.emit(_rows(1), cache_control=CacheControl(ttl=60))
+
+
+class TestInputRowsPerCall:
+    """Meta.input_rows_per_call: a positive int, on a RowTransformFunction only."""
+
+    def test_declared_value_resolves_and_round_trips(self) -> None:
+        """blended_sliced declares 3; it survives the Arrow and dict round-trips."""
+        from vgi._test_fixtures.table_in_out import BlendedSlicedFunction
+        from vgi.metadata import ResolvedMetadata, arrow_to_metadata, metadata_to_arrow
+
+        m = resolve_metadata(BlendedSlicedFunction)
+        assert m.input_rows_per_call == 3
+        assert arrow_to_metadata(metadata_to_arrow(m)).input_rows_per_call == 3
+        assert ResolvedMetadata.from_dict(m.to_dict()).input_rows_per_call == 3
+
+    def test_default_is_a_whole_chunk(self) -> None:
+        """Undeclared means no limit: the client sends a whole chunk per call."""
+        from vgi._test_fixtures.table_in_out import BlendedPagedFunction
+
+        assert resolve_metadata(BlendedPagedFunction).input_rows_per_call is None
+
+    @pytest.mark.parametrize("value", [0, -1, True, 2.5, "3"])
+    def test_non_positive_or_non_int_is_refused(self, value: object) -> None:
+        """Only a positive int is a row count."""
+
+        class _Bad(RowTransformFunction[_NArgs]):
+            class Meta:
+                name = "bad_rows_per_call"
+                input_rows_per_call = value
+
+            @classmethod
+            def on_bind(cls, params: BindParams[_NArgs]) -> BindResponse:
+                return BindResponse(output_schema=schema({"i": pa.int64()}))
+
+        with pytest.raises(ValueError, match="must be a positive int"):
+            resolve_metadata(_Bad)
+
+    def test_refused_outside_a_row_transform_function(self) -> None:
+        """A classic table-in-out function receives DuckDB's chunks as they are."""
+
+        class _Classic(TableInOutGenerator[_TableArgs]):
+            class Meta:
+                name = "classic_rows_per_call"
+                input_rows_per_call = 3
+
+        with pytest.raises(TypeError, match="applies only to a RowTransformFunction"):
+            resolve_metadata(_Classic)