vgi-python 0.43.1__py3-none-any.whl → 0.45.0__py3-none-any.whl

vgi/_test_fixtures/aggregate/dynamic.py

@@ -232,7 +232,9 @@ class _DynamicAggregateBase(AggregateFunction[DynamicState]):
                     t = t.filter(null_mask)
             slices.append(t)
         if not slices:
-            return pa.table({c: pa.array([], type=cols[i].type) for i, c in enumerate(col_names)})
+            # pa.nulls(0, ...), not pa.array([], ...): the latter has no
+            # builder for union or extension types.
+            return pa.table({c: pa.nulls(0, type=cols[i].type) for i, c in enumerate(col_names)})
         return pa.concat_tables(slices)
 
     @staticmethod

vgi/_test_fixtures/http_server.py

@@ -193,7 +193,7 @@ def main() -> None:
             "--identity",
             envvar="VGI_FIXTURE_IDENTITY",
             help=(
-                "Host vgi_rpc.Identity.v1 with the vgi-rpc conformance fixture policy and its "
+                "Host vgi_rpc.Identity.v2 with the vgi-rpc conformance fixture policy and its "
                 "spoofable X-Conformance-Principal header authentication. Test-only; for "
                 "vgi-rpc-test-hosted --identity."
             ),

vgi/_test_fixtures/identity_fixture.py

@@ -1,6 +1,6 @@
 # Copyright 2025, 2026 Query Farm LLC - https://query.farm
 
-"""Opt the HTTP fixture into ``vgi_rpc.Identity.v1`` with the conformance policy.
+"""Opt the HTTP fixture into ``vgi_rpc.Identity.v2`` with the conformance policy.
 
 Enabled by ``vgi-fixture-http --identity`` (or ``VGI_FIXTURE_IDENTITY=1``) so
 the cross-SDK hosted-protocols group can run its identity cases with

vgi/_test_fixtures/scalar/_common.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 import pyarrow as pa
 
-from vgi.exceptions import SchemaValidationError
+from vgi.exceptions import ArgumentTypeError
 
 
 def _is_addable_type(dtype: pa.DataType) -> bool:
@@ -66,4 +66,4 @@ def _promote_for_addition(dtype: pa.DataType) -> pa.DataType:
         # accepts that values >= 5e37 will overflow at compute time.
         new_precision = min(dtype.precision + 1, 38)
         return pa.decimal128(new_precision, dtype.scale)
-    raise SchemaValidationError(f"Unsupported numeric type for addition: {dtype}")
+    raise ArgumentTypeError(f"Unsupported numeric type for addition: {dtype}")

vgi/arguments.py

@@ -19,10 +19,11 @@ import typing
 import warnings
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
-from typing import TYPE_CHECKING, Any, Final, TypeVar, overload
+from typing import TYPE_CHECKING, Any, ClassVar, Final, TypeVar, overload
 
 import pyarrow as pa
 from vgi_rpc import ArrowSerializableDataclass
+from vgi_rpc.errors import Code
 
 if TYPE_CHECKING:
     from pyarrow import Scalar
@@ -638,6 +639,7 @@ class ArgumentValidationError(ValueError):
         valid_range: Human-readable description of valid values.
         default: Default value (if any) that could be used instead.
         choices: Valid choices, if the argument is constrained to a set.
+        error_code: ``INVALID_ARGUMENT`` -- the caller's input is wrong, not the worker.
 
     """
 
@@ -649,6 +651,7 @@ class ArgumentValidationError(ValueError):
     valid_range: str | None
     default: Any
     choices: Sequence[Any] | None
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
 
     def __init__(
         self,
@@ -1429,10 +1432,12 @@ class Arg[ArgT]:
             field_type: The Arrow type of the column to validate.
 
         Raises:
-            [`SchemaValidationError`][]: If the type bound is not satisfied.
+            [`ArgumentTypeError`][vgi.exceptions.ArgumentTypeError]: If the type bound is
+                not satisfied (a [`SchemaValidationError`][vgi.exceptions.SchemaValidationError]
+                coded ``INVALID_ARGUMENT``).
 
         """
-        from vgi.exceptions import SchemaValidationError
+        from vgi.exceptions import ArgumentTypeError
 
         if self.type_bound is None:
             return
@@ -1446,7 +1451,7 @@ class Arg[ArgT]:
         # OR logic: at least one predicate must pass
         if not any(predicate(field_type) for predicate in predicates):
             predicate_names = [getattr(p, "__name__", str(p)) for p in predicates]
-            raise SchemaValidationError(
+            raise ArgumentTypeError(
                 self.format_error(f"column type {field_type} does not match any of: {', '.join(predicate_names)}")
             )
 

vgi/attach_ticket.py

@@ -3,7 +3,7 @@
 r"""Attach tickets: a user's ATTACH, sealed so a runner can replay it later as that user.
 
 A ticket is the *what* half of an unattended session; a sealed grant
-(``vgi_rpc.Identity.v1`` ``issue_grant``) is the *who*. While the user is
+(``vgi_rpc.Identity.v2`` ``issue_grant``) is the *who*. While the user is
 attached and logged in, the client asks the worker to seal the options it
 attached with -- secret ones included -- into a ticket only this worker can
 open. Later any runner holding the user's grant attaches with the single option
@@ -43,7 +43,6 @@ from __future__ import annotations
 
 import base64
 import dataclasses
-import math
 import os
 import re
 import secrets
@@ -51,6 +50,7 @@ import struct
 import sys
 import time
 from collections.abc import Mapping, Sequence
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Annotated, Any, ClassVar, Protocol
 
 import pyarrow as pa
@@ -553,13 +553,20 @@ class AttachTicket(ArrowSerializableDataclass):
 
     Attributes:
         ticket: ``vgia1.`` text. Not a credential, but never logged.
-        expires_at: Unix seconds after which the worker refuses it; ``+inf``
-            when the worker sets no maximum lifetime.
+        expires_at: The UTC instant after which the worker refuses it, carried
+            as ``timestamp[us, tz="UTC"]``; ``None`` (null on the wire) when
+            the worker sets no maximum lifetime. Protocol ``1.0.0`` carried a
+            float64 of unix seconds with ``+inf`` for "no expiry".
 
     """
 
     ticket: str
-    expires_at: float
+    expires_at: Annotated[datetime | None, ArrowType(pa.timestamp("us", tz="UTC"))]
+
+    def __post_init__(self) -> None:
+        """Refuse a naive ``expires_at``, which has no defined instant."""
+        if self.expires_at is not None and (self.expires_at.tzinfo is None or self.expires_at.utcoffset() is None):
+            raise ValueError("AttachTicket.expires_at must be timezone-aware (UTC) or None")
 
 
 class AttachTickets(Protocol):
@@ -571,7 +578,7 @@ class AttachTickets(Protocol):
     """
 
     protocol_name: ClassVar[str] = ATTACH_TICKETS_PROTOCOL_NAME
-    protocol_version: ClassVar[str] = "1.0.0"
+    protocol_version: ClassVar[str] = "2.0.0"
 
     def seal_attach(self, request: SealAttachRequest) -> AttachTicket:
         """Seal the caller's attach of ``request.catalog_name`` into a ticket.
@@ -730,4 +737,6 @@ class AttachTicketsImpl:
             )
         except ValueError as exc:
             raise _invalid_request("seal_attach request is invalid", [("request", str(exc))]) from exc
-        return AttachTicket(ticket=token, expires_at=math.inf if expires_at == 0 else float(expires_at))
+        return AttachTicket(
+            ticket=token, expires_at=None if expires_at == 0 else datetime.fromtimestamp(expires_at, tz=UTC)
+        )

vgi/auth.py

@@ -24,7 +24,7 @@ from typing import TYPE_CHECKING, Any
 
 from vgi_rpc.rpc import AuthContext, CallContext
 
-# ``vgi_rpc.Identity.v1`` lives at the RPC layer as of vgi-rpc 0.46.0 -- it was
+# ``vgi_rpc.Identity.v2`` lives at the RPC layer as of vgi-rpc 0.46.0 -- it was
 # an HTTP JSON route (``POST {prefix}/__introspect_token__``) through 0.45.x,
 # which meant it existed on exactly one transport.  So this is no longer gated
 # on the ``http`` extra.  Still not re-exported by ``vgi_rpc.rpc`` itself, so

vgi/catalog/attach_option.py

@@ -23,6 +23,7 @@ from dataclasses import dataclass
 from typing import Any, ClassVar
 
 import pyarrow as pa
+from vgi_rpc.errors import Code
 
 from vgi.catalog._descriptor_spec import _DescriptorBase, _extract_specs, _SpecBase
 
@@ -156,10 +157,12 @@ class MissingAttachOptionsError(ValueError):
 
     Attributes:
         missing: Names of the required options that were not supplied.
+        error_code: ``INVALID_ARGUMENT``.
 
     """
 
     missing: list[str]
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
 
     def __init__(self, catalog_name: str, missing: list[str]) -> None:
         """Build the error from the catalog name and the missing option names."""

vgi/catalog/catalog_interface.py

@@ -38,7 +38,7 @@ from vgi_rpc import ArrowSerializableDataclass, ArrowType
 from vgi_rpc.utils import deserialize_record_batch, serialize_record_batch_bytes
 
 from vgi.arguments import Arguments, SecretLookupEntry
-from vgi.exceptions import CatalogReadOnlyError
+from vgi.exceptions import CatalogReadOnlyError, InvalidArgumentError, NotFoundError, UnsupportedOperationError
 from vgi.metadata import (
     ArgumentMonotonicity,
     DistinctDependence,
@@ -100,7 +100,7 @@ __all__ = [
 def _validate_at_params(at_unit: str | None, at_value: str | None) -> None:
     """Validate that at_unit and at_value are both provided or both absent."""
     if bool(at_unit) != bool(at_value):
-        raise ValueError("at_unit and at_value must both be provided or both be None")
+        raise InvalidArgumentError("at_unit and at_value must both be provided or both be None")
 
 
 @dataclass(frozen=True)
@@ -1810,12 +1810,12 @@ class CatalogInterface(ABC):
         If on_conflict is ERROR and the catalog already exists, raise an error.
 
         """
-        raise NotImplementedError("Catalog create not implemented.")
+        raise UnsupportedOperationError("Catalog create not implemented.")
 
     # Drop a catalog
     def catalog_drop(self, *, name: str) -> None:
         """Drop the catalog with the given name."""
-        raise NotImplementedError("Catalog drop not implemented.")
+        raise UnsupportedOperationError("Catalog drop not implemented.")
 
     # Transactions are initiated and driven by DuckDB it is rare for CatalogInterface
     # implementors to implement them, but I want to support them.
@@ -1830,7 +1830,7 @@ class CatalogInterface(ABC):
 
         If the implementation does not support transactions, it can return None.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     def catalog_transaction_commit(
         self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: TransactionOpaqueData
@@ -1839,7 +1839,7 @@ class CatalogInterface(ABC):
 
         If the transaction cannot be committed, an exception should be raised.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     def catalog_transaction_rollback(
         self, *, attach_opaque_data: AttachOpaqueData, transaction_opaque_data: TransactionOpaqueData
@@ -1848,7 +1848,7 @@ class CatalogInterface(ABC):
 
         If the transaction cannot be rolled back, an exception should be raised.
         """
-        raise NotImplementedError("Catalog transactions not implemented.")
+        raise UnsupportedOperationError("Catalog transactions not implemented.")
 
     @abstractmethod
     def catalog_attach(
@@ -1936,7 +1936,7 @@ class CatalogInterface(ABC):
         tags: dict[str, str],
     ) -> None:
         """Create a new schema with the given path, comment, and tags."""
-        raise NotImplementedError("Schema create not implemented.")
+        raise UnsupportedOperationError("Schema create not implemented.")
 
     def schema_drop(
         self,
@@ -1948,7 +1948,7 @@ class CatalogInterface(ABC):
         cascade: bool,
     ) -> None:
         """Drop the schema with the given path."""
-        raise NotImplementedError("Schema drop not implemented.")
+        raise UnsupportedOperationError("Schema drop not implemented.")
 
     @overload
     def schema_contents(
@@ -2034,7 +2034,7 @@ class CatalogInterface(ABC):
             depending on the type parameter.
 
         """
-        raise NotImplementedError("Schema contents not implemented.")
+        raise UnsupportedOperationError("Schema contents not implemented.")
 
     def catalog_contents(
         self,
@@ -2159,7 +2159,7 @@ class CatalogInterface(ABC):
 
         Comments and tags are not supported on table creation.
         """
-        raise NotImplementedError("Table create not implemented.")
+        raise UnsupportedOperationError("Table create not implemented.")
 
     def table_drop(
         self,
@@ -2172,7 +2172,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the table with the given name."""
-        raise NotImplementedError("Table drop not implemented.")
+        raise UnsupportedOperationError("Table drop not implemented.")
 
     def table_comment_set(
         self,
@@ -2185,7 +2185,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for the table with the given name."""
-        raise NotImplementedError("Table comment set not implemented.")
+        raise UnsupportedOperationError("Table comment set not implemented.")
 
     def table_column_comment_set(
         self,
@@ -2199,7 +2199,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for a column in the table."""
-        raise NotImplementedError("Table column comment set not implemented.")
+        raise UnsupportedOperationError("Table column comment set not implemented.")
 
     def table_rename(
         self,
@@ -2212,7 +2212,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the table with the given name to the new name."""
-        raise NotImplementedError("Table rename not implemented.")
+        raise UnsupportedOperationError("Table rename not implemented.")
 
     def table_column_add(
         self,
@@ -2228,7 +2228,7 @@ class CatalogInterface(ABC):
         if_column_not_exists: bool,
     ) -> None:
         """Add a column to the table with the given name."""
-        raise NotImplementedError("Table column add not implemented.")
+        raise UnsupportedOperationError("Table column add not implemented.")
 
     def table_column_drop(
         self,
@@ -2243,7 +2243,7 @@ class CatalogInterface(ABC):
         cascade: bool,
     ) -> None:
         """Drop the column from the table with the given name."""
-        raise NotImplementedError("Table column drop not implemented.")
+        raise UnsupportedOperationError("Table column drop not implemented.")
 
     def table_column_rename(
         self,
@@ -2257,7 +2257,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the column in the table with the given name."""
-        raise NotImplementedError("Table column rename not implemented.")
+        raise UnsupportedOperationError("Table column rename not implemented.")
 
     def table_column_default_set(
         self,
@@ -2271,7 +2271,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the default expression for the column."""
-        raise NotImplementedError("Table column default set not implemented.")
+        raise UnsupportedOperationError("Table column default set not implemented.")
 
     def table_column_default_drop(
         self,
@@ -2284,7 +2284,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the default expression for the column."""
-        raise NotImplementedError("Table column default drop not implemented.")
+        raise UnsupportedOperationError("Table column default drop not implemented.")
 
     def table_column_type_change(
         self,
@@ -2303,7 +2303,7 @@ class CatalogInterface(ABC):
 
         The name of the column to change is taken from the field in the provided schema.
         """
-        raise NotImplementedError("Table column type change not implemented.")
+        raise UnsupportedOperationError("Table column type change not implemented.")
 
     def table_not_null_drop(
         self,
@@ -2316,7 +2316,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the NOT NULL constraint from the column."""
-        raise NotImplementedError("Table NOT NULL drop not implemented.")
+        raise UnsupportedOperationError("Table NOT NULL drop not implemented.")
 
     def table_not_null_set(
         self,
@@ -2329,7 +2329,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the NOT NULL constraint on the column."""
-        raise NotImplementedError("Table NOT NULL set not implemented.")
+        raise UnsupportedOperationError("Table NOT NULL set not implemented.")
 
     def table_scan_function_get(
         self,
@@ -2347,7 +2347,7 @@ class CatalogInterface(ABC):
         Returns information about the VGI table function to call when scanning
         this table. The at_unit and at_value support time travel queries.
         """
-        raise NotImplementedError("Table scan function get not implemented.")
+        raise UnsupportedOperationError("Table scan function get not implemented.")
 
     def table_scan_branches_get(
         self,
@@ -2466,7 +2466,7 @@ class CatalogInterface(ABC):
         For single-branch tables this is ``None`` (or unset for legacy
         overrides).
         """
-        raise NotImplementedError("Table insert not supported.")
+        raise UnsupportedOperationError("Table insert not supported.")
 
     def table_update_function_get(
         self,
@@ -2482,7 +2482,7 @@ class CatalogInterface(ABC):
         to call for updating rows in this table. Input batches will include a
         rowid column plus the columns being updated.
         """
-        raise NotImplementedError("Table update not supported.")
+        raise UnsupportedOperationError("Table update not supported.")
 
     def table_delete_function_get(
         self,
@@ -2498,7 +2498,7 @@ class CatalogInterface(ABC):
         to call for deleting rows from this table. Input batches will contain
         a rowid column identifying the rows to delete.
         """
-        raise NotImplementedError("Table delete not supported.")
+        raise UnsupportedOperationError("Table delete not supported.")
 
     def view_create(
         self,
@@ -2511,7 +2511,7 @@ class CatalogInterface(ABC):
         on_conflict: OnConflict,
     ) -> None:
         """Create a new view with the given definition."""
-        raise NotImplementedError("View create not implemented.")
+        raise UnsupportedOperationError("View create not implemented.")
 
     def view_drop(
         self,
@@ -2524,7 +2524,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the view with the given name."""
-        raise NotImplementedError("View drop not implemented.")
+        raise UnsupportedOperationError("View drop not implemented.")
 
     def view_rename(
         self,
@@ -2537,7 +2537,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Rename the view to the new name."""
-        raise NotImplementedError("View rename not implemented.")
+        raise UnsupportedOperationError("View rename not implemented.")
 
     @abstractmethod
     def view_get(
@@ -2564,7 +2564,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Set the comment for the view with the given name."""
-        raise NotImplementedError("View comment set not implemented.")
+        raise UnsupportedOperationError("View comment set not implemented.")
 
     # ---- Macros ----
 
@@ -2613,7 +2613,7 @@ class CatalogInterface(ABC):
                 descriptions via the ``vgi_doc`` field metadata key. ``None`` when
                 no per-parameter docs are supplied.
         """
-        raise NotImplementedError("Macro create not implemented.")
+        raise UnsupportedOperationError("Macro create not implemented.")
 
     def macro_drop(
         self,
@@ -2625,7 +2625,7 @@ class CatalogInterface(ABC):
         ignore_not_found: bool,
     ) -> None:
         """Drop the macro with the given name."""
-        raise NotImplementedError("Macro drop not implemented.")
+        raise UnsupportedOperationError("Macro drop not implemented.")
 
     # ---- Indexes ----
 
@@ -2659,7 +2659,7 @@ class CatalogInterface(ABC):
         options: dict[str, str] | None = None,
     ) -> None:
         """Create a new index on the specified table."""
-        raise NotImplementedError("Index create not implemented.")
+        raise UnsupportedOperationError("Index create not implemented.")
 
     def index_drop(
         self,
@@ -2672,7 +2672,7 @@ class CatalogInterface(ABC):
         cascade: bool = False,
     ) -> None:
         """Drop the index with the given name."""
-        raise NotImplementedError("Index drop not implemented.")
+        raise UnsupportedOperationError("Index drop not implemented.")
 
     def copy_from_formats(
         self,
@@ -3015,7 +3015,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
         del data_version_spec, implementation_version, ctx
         effective_name = self._effective_catalog_name
         if name != effective_name:
-            raise ValueError(f"Unknown catalog: {name!r}. Available: {effective_name}")
+            raise NotFoundError(f"Unknown catalog: {name!r}. Available: {effective_name}")
         validate_required_attach_options(effective_name, self.attach_option_specs, options)
 
         # Serialize settings and secret types for the attach result
@@ -3276,7 +3276,7 @@ class ReadOnlyCatalogInterface(CatalogInterface):
 
         table = self._table_registry.get((schema_path_key(schema_path), name.lower()))
         if table is None:
-            raise NotImplementedError(f"Table {schema_path_display(schema_path)}::{name!r} not found in catalog.")
+            raise NotFoundError(f"Table {schema_path_display(schema_path)}::{name!r} not found in catalog.")
 
         write_func = getattr(table, attr_name, None)
         if write_func is None:

vgi/client/aggregate.py

@@ -50,6 +50,7 @@ from typing import Any
 
 import pyarrow as pa
 from vgi_rpc.rpc import RpcError
+from vgi_rpc.utils import empty_batch
 
 from vgi.aggregate_function import GROUP_COLUMN_NAME
 from vgi.arguments import Arguments
@@ -783,12 +784,9 @@ class AggregateClientMixin:
                 batch = next(batches, None)
 
             if not group_keys:
-                results = [
-                    pa.RecordBatch.from_arrays(
-                        [pa.array([], type=field.type) for field in session.output_schema],
-                        schema=session.output_schema,
-                    )
-                ]
+                # empty_batch, not pa.array([], type=...): that has no builder
+                # for union or extension types.
+                results = [empty_batch(session.output_schema)]
             else:
                 results = [
                     session.finalize(range(start, min(start + finalize_chunk_size, len(group_keys))))

vgi/exceptions.py

@@ -14,15 +14,21 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, ClassVar
 
+from vgi_rpc.errors import Code
+
 if TYPE_CHECKING:
     import pyarrow as pa
 
 __all__ = [
+    "ArgumentTypeError",
     "BindStateNotFoundError",
     "CatalogReadOnlyError",
     "ExecutionIdentifierError",
+    "InvalidArgumentError",
+    "NotFoundError",
     "OpaqueDataNotRecognizedError",
     "SchemaValidationError",
+    "UnsupportedOperationError",
 ]
 
 
@@ -55,8 +61,14 @@ class CatalogReadOnlyError(Exception):
     - table_get(), view_get() - get table/view info
     - table_scan_function_get() - get scan function for tables
 
+    Also raised when a write targets a table that has no write function.
+    ``FAILED_PRECONDITION``: the request is well-formed, the catalog is just
+    not in a state that permits it.
+
     """
 
+    error_code: ClassVar[Code] = Code.FAILED_PRECONDITION
+
 
 class OpaqueDataNotRecognizedError(ValueError):
     """An opaque value (``attach_opaque_data`` / ``transaction_opaque_data``) failed to open.
@@ -72,7 +84,7 @@ class OpaqueDataNotRecognizedError(ValueError):
     working.
     """
 
-    error_code: ClassVar[str] = "INVALID_ARGUMENT"
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
     error_kind: ClassVar[str] = "opaque_data_not_recognized"
 
     def __init__(self, field: str) -> None:
@@ -230,3 +242,52 @@ class SchemaValidationError(Exception):
             lines.append(f"    {field.name}: {field.type}{nullable}")
 
         return "\n".join(lines)
+
+
+class ArgumentTypeError(SchemaValidationError):
+    """An argument or input column has a type the function does not accept.
+
+    Raised when a value fails an ``Arg[AnyArrow]`` ``type_bound`` -- e.g.
+    ``double('abc')`` against a numeric-only bound. Unlike its base class,
+    which reports a worker's *own* output violating its declared schema (a
+    bug, sent as ``UNKNOWN``), this is the caller's input being wrong, so it is
+    ``INVALID_ARGUMENT``. Subclasses [`SchemaValidationError`][] so existing
+    handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
+
+
+class InvalidArgumentError(ValueError):
+    """A request's arguments cannot be accepted (``INVALID_ARGUMENT``).
+
+    For argument problems that are not a single argument's constraint (those
+    raise [`ArgumentValidationError`][vgi.arguments.ArgumentValidationError]):
+    no overload matching the supplied argument types, an ambiguous call, or a
+    call shape the function does not take. Subclasses ``ValueError`` so
+    existing handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.INVALID_ARGUMENT
+
+
+class NotFoundError(ValueError):
+    """A named function, table, schema, or catalog does not exist (``NOT_FOUND``).
+
+    Subclasses ``ValueError`` so existing handlers keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.NOT_FOUND
+
+
+class UnsupportedOperationError(NotImplementedError):
+    """An operation the SDK or catalog explicitly does not support (``UNIMPLEMENTED``).
+
+    Raised by the [`CatalogInterface`][vgi.catalog.CatalogInterface] defaults
+    for DDL/DML a catalog has not implemented, and by framework paths that are
+    not supported yet. Subclasses ``NotImplementedError`` so existing handlers
+    -- including the ones that treat an unimplemented optional hook as
+    "absent" -- keep working.
+    """
+
+    error_code: ClassVar[Code] = Code.UNIMPLEMENTED

vgi/filter_v2.py

@@ -16,6 +16,7 @@ from typing import Any
 from typing import Literal as TypingLiteral
 
 import pyarrow as pa
+from vgi_rpc.utils import empty_batch
 
 FILTER_ENCODING = "vgi.filters.v2"
 FILTER_VERSION = "2"
@@ -765,10 +766,9 @@ class _Parser:
             and not isinstance(expression, RuntimeFilter)
             and not _REPLAYING_ACCEPTED_STATE.get()
         ):
-            empty = pa.RecordBatch.from_arrays(
-                [pa.array([], type=field.type) for field in self.output_schema],
-                schema=self.output_schema,
-            )
+            # empty_batch, not pa.array([], type=...): that has no builder
+            # for union or extension types.
+            empty = empty_batch(self.output_schema)
             try:
                 _evaluate_expression(expression, empty, self.context)
             except Exception as exc: