Add VGI 2 function signature metadata

Author: rustyconover

docs/catalog-interface.md

@@ -127,6 +127,7 @@ Information about a function in a schema:
 | `function_type` | `FunctionType` | `SCALAR` or `TABLE` |
 | `arguments` | `SerializedSchema` | Argument schema as Arrow bytes |
 | `output_schema` | `SerializedSchema` | Output schema as Arrow bytes |
+| `parameter_default_values` | `pa.RecordBatch \| None` | One-row typed defaults batch containing only defaulted parameters in signature order; a present null is an explicit `NULL` default |
 | `comment` | `str \| None` | Optional description |
 | `tags` | `dict[str, str]` | Key-value metadata |
 

docs/protocol/vgi-protocol-proposed-changes.md

@@ -7,6 +7,10 @@
 **VGI examined:** `588bb2fd99de6a58461b3dfbbf26cc604da4c94e`
 **vgi-python examined:** `97b68f0f42d560bbc00947eddf39370ca167aa2d`
 
+**Function-signature decision:** 2026-09-10 — named fixed parameters,
+authoritative typed defaults, and bind-time resolved names are part of VGI 2.0;
+there is no protocol overload identifier.
+
 ## Executive answer
 
 Nested schemas are **not** the only possible VGI protocol change.
@@ -26,6 +30,43 @@ My confidence is **high that the audit has found the DuckDB 2.0 changes that alt
 
 VGI protocol 2.0 will not carry a v1 compatibility path. A 1.x peer is rejected during protocol negotiation. The DuckDB 1.5 extension can still implement the v2 wire format; its engine adapter simply produces the subset of the v2 AST that DuckDB 1.5 can offer.
 
+## Accepted function-signature contract
+
+DuckDB 2.0 can bind named arguments and defaults for scalar, aggregate, and
+window functions. VGI models the portable semantics rather than exposing a
+DuckDB overload handle:
+
+1. For scalar and aggregate functions, fields in `FunctionInfo.arguments` are
+   ordered fixed signature slots and each field name is the SQL/VGI parameter
+   name. `vgi_arg=named` remains reserved for table-function-style named-only
+   options. `vgi_const` is orthogonal to naming.
+2. `FunctionInfo.parameter_default_values` is a nullable IPC-serialized
+   `RecordBatch`. When present it has exactly one row and contains only
+   defaulted parameters, in signature order. Column absence means required/no
+   default; a present null scalar means an explicit `NULL` default. Each column
+   type exactly matches its argument field. Scalar and aggregate defaults form
+   a trailing sequence of fixed parameters, and varargs cannot have defaults.
+3. `BindRequest.argument_names` and `AggregateBindRequest.argument_names` are
+   nullable `list<utf8>` values aligned with the complete logical argument
+   order before constant arguments are separated for execution. Fixed slots
+   carry their declared names, unnamed varargs carry null elements, and named
+   varargs retain caller-provided names. A null list means the engine cannot
+   provide resolved names.
+
+The legacy `vgi_default` field metadata is discovery-only and may be removed in
+a later protocol. It is never authoritative when the typed batch is present.
+Implementations select behavior by inspecting the bound arguments, types, and
+resolved names; VGI does not add `overload_id`.
+
+The DuckDB 1.5 adapter implements this VGI 2.0 wire shape now. It advertises and
+validates typed defaults and synthesizes fixed names plus null unnamed-vararg
+entries. Because DuckDB 1.5 cannot register scalar/aggregate named calls or
+engine-applied defaults, SQL callers must still provide those values
+positionally. A DuckDB 2.0 adapter can map the same metadata to
+`FunctionSignature` without changing the worker protocol. DataFusion, Spark,
+and SQLite adapters should normalize their native call forms to the same bind
+representation.
+
 ## 1. Protocol version and rollout
 
 At the start of the audit, the application protocol declared `1.5.0`. It now declares `2.0.0` in the canonical `vgi-python/vgi/protocol_version.txt`. The documented version rules treat a parameter or return-type change as a major change, the framework enforces an exact major/minor match, and the C++ consumer rejects response column-count drift.

tests/catalog/test_example_worker_catalog.py

@@ -217,6 +217,25 @@ def test_function_info_has_arguments(self) -> None:
         field_names = [f.name for f in args_schema]
         assert "value" in field_names
 
+    def test_scalar_signature_names_and_typed_defaults(self) -> None:
+        """Fixed field names and the typed default batch share one signature order."""
+        client = Client(EXAMPLE_WORKER)
+        attach_result = client.catalog_attach(
+            name="example", options={}, data_version_spec=None, implementation_version=None
+        )
+        functions = _get_all_functions(client, attach_result.attach_opaque_data)
+        probe = next(fn for fn in functions if fn.name == "argument_names_probe")
+
+        arguments = pa.ipc.read_schema(pa.py_buffer(probe.arguments))
+        assert arguments.names == ["left", "right", "scale"]
+        assert all(b"vgi_arg" not in (field.metadata or {}) for field in arguments)
+
+        defaults = probe.parameter_default_values
+        assert defaults is not None
+        assert defaults.schema.names == ["scale"]
+        assert defaults.column("scale").type == pa.int64()
+        assert defaults.column("scale")[0].as_py() == 2
+
     def test_function_info_has_description(self) -> None:
         """FunctionInfo has description from docstring or Meta."""
         client = Client(EXAMPLE_WORKER)

tests/catalog/test_serialization.py

@@ -2,6 +2,8 @@
 
 """Tests for catalog dataclass serialization/deserialization."""
 
+from decimal import Decimal
+
 import pyarrow as pa
 import pytest
 from vgi_rpc.utils import deserialize_record_batch
@@ -776,6 +778,37 @@ def test_scalar_function(self) -> None:
         assert restored.arguments == original.arguments
         assert restored.output_schema == original.output_schema
 
+    def test_function_parameter_default_values_round_trip(self) -> None:
+        """FunctionInfo preserves typed defaults and explicit nulls."""
+        args_schema = schema(value=pa.int64(), scale=pa.decimal128(10, 2), label=pa.string())
+        output_schema = schema(result=pa.int64())
+        defaults = pa.RecordBatch.from_arrays(
+            [
+                pa.array([Decimal("1.25")], type=pa.decimal128(10, 2)),
+                pa.array([None], type=pa.string()),
+            ],
+            names=["scale", "label"],
+        )
+        original = FunctionInfo(
+            name="configured",
+            schema_path=["main"],
+            function_type=FunctionType.SCALAR,
+            arguments=SerializedSchema(args_schema.serialize().to_pybytes()),
+            output_schema=SerializedSchema(output_schema.serialize().to_pybytes()),
+            parameter_default_values=defaults,
+            comment=None,
+            tags={},
+        )
+
+        restored = FunctionInfo.deserialize_from_bytes(original.serialize_to_bytes())
+
+        assert restored.parameter_default_values is not None
+        actual = restored.parameter_default_values
+        assert actual.schema.names == ["scale", "label"]
+        assert actual.column("scale").type == pa.decimal128(10, 2)
+        assert str(actual.column("scale")[0].as_py()) == "1.25"
+        assert actual.column("label")[0].as_py() is None
+
     def test_table_function(self) -> None:
         """Test with table function type."""
         args_schema = schema(count=pa.int32())

tests/conformance/test_scalar_attach_opaque_data.py

@@ -35,6 +35,7 @@ class Meta:
     def on_bind(cls, params: BindParameters) -> BindResult:
         _seen["attach_opaque_data"] = params.attach_opaque_data
         _seen["transaction_opaque_data"] = params.transaction_opaque_data
+        _seen["argument_names"] = params.argument_names
         return BindResult(pa.int64())
 
     @classmethod
@@ -45,7 +46,11 @@ def compute(
         return x
 
 
-def _bind(attach_opaque_data: bytes | None, transaction_opaque_data: bytes | None) -> None:
+def _bind(
+    attach_opaque_data: bytes | None,
+    transaction_opaque_data: bytes | None,
+    argument_names: list[str | None] | None = None,
+) -> None:
     _seen.clear()
     # The worker unwraps the sealed attach to the framework plaintext
     # ``uuid(16) || catalog_bytes`` and threads it as ``attach_plaintext``; the
@@ -60,6 +65,7 @@ def _bind(attach_opaque_data: bytes | None, transaction_opaque_data: bytes | Non
             input_schema=pa.schema([("x", pa.int64())]),
             attach_opaque_data=attach_opaque_data,
             transaction_opaque_data=transaction_opaque_data,
+            argument_names=argument_names,
         ),
         attach_plaintext=attach_plaintext,
     )
@@ -84,3 +90,9 @@ def test_on_bind_attach_opaque_data_optional() -> None:
     _bind(attach_opaque_data=None, transaction_opaque_data=None)
     assert _seen["attach_opaque_data"] is None
     assert _seen["transaction_opaque_data"] is None
+
+
+def test_on_bind_receives_argument_names() -> None:
+    """Resolved logical argument names reach scalar implementation bind code."""
+    _bind(None, None, ["x", None])
+    assert _seen["argument_names"] == ["x", None]

tests/test_argument_spec.py

@@ -26,6 +26,7 @@
     _format_range,
     argument_specs_to_schema,
     extract_argument_specs,
+    parameter_default_values_from_specs,
     schema_to_argument_specs,
 )
 from vgi.arguments import AnyArrow, AnyArrowValue, Arg, TableInput
@@ -824,3 +825,55 @@ def compute(
         # The columnar Param carries no constraints.
         assert specs["value"].choices_json is None
         assert specs["value"].range_notation is None
+
+    def test_scalar_signature_defaults_build_typed_batch(self) -> None:
+        """Python method defaults become typed FunctionInfo default values."""
+        from vgi.arguments import ConstParam, Param, Returns
+        from vgi.scalar_function import ScalarFunction
+
+        class DefaultedScalar(ScalarFunction):
+            class Meta:
+                name = "defaulted_scalar"
+
+            @classmethod
+            def compute(
+                cls,
+                value: Annotated[pa.Int64Array, Param()],
+                factor: Annotated[int, ConstParam()] = 2,
+                label: Annotated[str | None, ConstParam(arrow_type=pa.string())] = None,
+            ) -> Annotated[pa.Int64Array, Returns()]:
+                raise AssertionError("metadata-only test")
+
+        specs = extract_argument_specs(DefaultedScalar)
+        defaults = parameter_default_values_from_specs(specs, require_trailing=True)
+
+        assert defaults is not None
+        assert defaults.num_rows == 1
+        assert defaults.schema.names == ["factor", "label"]
+        assert defaults.column("factor").type == pa.int64()
+        assert defaults.column("factor")[0].as_py() == 2
+        assert defaults.column("label").type == pa.string()
+        assert defaults.column("label")[0].as_py() is None
+
+    def test_typed_default_requires_concrete_parameter_type(self) -> None:
+        """An ANY parameter cannot carry an untyped protocol default."""
+        spec = ArgumentSpec(
+            name="value",
+            position=0,
+            arrow_type=pa.null(),
+            is_any_type=True,
+            default_value=1,
+        )
+
+        with pytest.raises(ValueError, match="typed defaults require an explicit parameter type"):
+            parameter_default_values_from_specs([spec], require_trailing=True)
+
+    def test_typed_defaults_reject_case_insensitive_duplicate_names(self) -> None:
+        """Default-batch field names must identify one signature slot."""
+        specs = [
+            ArgumentSpec(name="Scale", position=0, arrow_type=pa.int64()),
+            ArgumentSpec(name="scale", position=1, arrow_type=pa.int64(), default_value=2),
+        ]
+
+        with pytest.raises(ValueError, match="Duplicate function parameter name"):
+            parameter_default_values_from_specs(specs)

tests/test_protocol_classes.py

@@ -1183,6 +1183,28 @@ def _make_bind(self) -> BindRequest:
             function_type=FunctionType.TABLE,
         )
 
+    def test_argument_names_round_trip(self) -> None:
+        """Bind requests preserve aligned names, including unnamed varargs."""
+        from vgi.invocation import FunctionType
+        from vgi.protocol import AggregateBindRequest, BindRequest
+
+        bind = BindRequest(
+            function_name="f",
+            arguments=Arguments(),
+            function_type=FunctionType.SCALAR,
+            argument_names=["value", None, "named_tail"],
+        )
+        restored = BindRequest.deserialize_from_bytes(bind.serialize_to_bytes())
+        assert restored.argument_names == ["value", None, "named_tail"]
+
+        aggregate_bind = AggregateBindRequest(
+            function_name="agg",
+            arguments=Arguments(),
+            argument_names=["value", "separator"],
+        )
+        restored_aggregate = AggregateBindRequest.deserialize_from_bytes(aggregate_bind.serialize_to_bytes())
+        assert restored_aggregate.argument_names == ["value", "separator"]
+
     def test_init_request_bind_call_is_binary(self) -> None:
         """``InitRequest.bind_call`` serializes as binary and round-trips."""
         from vgi.protocol import InitRequest

vgi/__init__.py

@@ -26,6 +26,7 @@
     VGI_VARARGS_TRUE,
     ArgumentSpec,
     argument_specs_to_schema,
+    parameter_default_values_from_specs,
     schema_to_argument_specs,
 )
 from vgi.arguments import (
@@ -132,6 +133,7 @@
     "AuthContext",
     "CallContext",
     "argument_specs_to_schema",
+    "parameter_default_values_from_specs",
     "BindRequest",
     "ColumnBounds",
     "ColumnRefNode",

vgi/_test_fixtures/scalar/__init__.py

@@ -19,6 +19,7 @@
 
 from vgi._test_fixtures.scalar.arithmetic import (
     AddValuesFunction,
+    ArgumentNamesProbeFunction,
     CachedAddConstScalarFunction,
     CachedDoubleScalarFunction,
     CachedLabelScalarFunction,
@@ -92,6 +93,7 @@
 __all__ = [
     "_POINT_STRUCT_TYPE",
     "AddValuesFunction",
+    "ArgumentNamesProbeFunction",
     "AnyMixedIntFunction",
     "AnyMixedStrFunction",
     "BernoulliFunction",

vgi/_test_fixtures/scalar/arithmetic.py

@@ -281,6 +281,34 @@ def compute(
         return result
 
 
+class ArgumentNamesProbeFunction(ScalarFunction):
+    """Verify that the engine forwards the complete resolved bind signature."""
+
+    class Meta:
+        """Function metadata."""
+
+        name = "argument_names_probe"
+        description = "Checks VGI 2.0 bind-time argument names"
+
+    @classmethod
+    def on_bind(cls, params: BindParameters) -> BindResult:
+        """Reject a bind that loses names or separates ConstParam too early."""
+        expected = ["left", "right", "scale"]
+        if params.argument_names != expected:
+            raise ValueError(f"argument_names_probe expected {expected!r}, got {params.argument_names!r}")
+        return BindResult(pa.int64())
+
+    @classmethod
+    def compute(
+        cls,
+        left: Annotated[pa.Int64Array, Param(doc="Left value")],
+        right: Annotated[pa.Int64Array, Param(doc="Right value")],
+        scale: Annotated[int, ConstParam("Scale factor", arrow_type=pa.int64())] = 2,
+    ) -> Annotated[pa.Int64Array, Returns(pa.int64())]:
+        """Add both inputs and multiply by the constant scale."""
+        return pc.multiply(pc.add(left, right), scale)
+
+
 class SumValuesFunction(ScalarFunction):
     """Sums multiple numeric values.