Add argument monotonicity protocol metadata

Author: rustyconover

docs/catalog-interface.md

@@ -128,6 +128,7 @@ Information about a function in a schema:
 | `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 |
+| `argument_monotonicity` | `list[ArgumentMonotonicity] \| None` | Scalar-only claims aligned exactly with `arguments`; a vararg declaration occupies one slot |
 | `comment` | `str \| None` | Optional description |
 | `tags` | `dict[str, str]` | Key-value metadata |
 

docs/metadata.md

@@ -82,6 +82,7 @@ info = SumValuesFunction.describe()
 | `max_workers` | `int\|None` | `None` (unlimited) | Max parallel workers |
 | `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 |
 | `required_settings` | `list[str]` | `[]` | Required DuckDB settings |
 | `projection_pushdown` | `bool` | `True` | Enable column pruning |
 | `filter_pushdown` | `bool` | `False` | Enable filter pushdown |
@@ -90,6 +91,14 @@ info = SumValuesFunction.describe()
 | `distinct_dependent` | `DistinctDependence` | `NOT_DISTINCT_DEPENDENT` | Aggregate DISTINCT sensitivity |
 | `output_type` | `pa.DataType\|AnyArrow` | Required for ScalarFunction | Scalar output type |
 
+`argument_monotonicity` is only valid on scalar functions. When present, it
+contains exactly one entry for every field in the function's argument schema.
+Fixed, defaulted, and constant parameters each occupy one entry, and a vararg
+declaration also occupies one entry regardless of how many values a call
+supplies. The ordering is the declaration order, so named SQL calls do not
+reorder the metadata. Use `None` to make no claims; use
+`ArgumentMonotonicity.UNKNOWN` for an explicitly unknown individual slot.
+
 ## Metadata Inheritance
 
 Meta attributes are inherited from parent classes:

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

@@ -1,6 +1,6 @@
 # Proposed VGI protocol changes for DuckDB 2.0
 
-**Status:** design/audit report, not an implementation specification
+**Status:** design/audit report; the argument-monotonicity subsection records an accepted VGI 2.0 protocol addition
 **Audit date:** 2026-09-09
 **Filter-v2 decision:** 2026-09-09 — mandatory in VGI 2.0; no v1 compatibility path
 **DuckDB range examined:** `v1.5.5..03a1639e3bba0e50bab4c341ebc89137c86b793a` (`v2.0-cyanoptera` plus the multi-column table-function pushdown branch)
@@ -409,15 +409,30 @@ DuckDB replaces the old dynamic-to-string hook with `get_metrics` and `OperatorM
 
 ### Function metadata
 
-DuckDB 2.0 adds optimizer-facing per-argument monotonicity and strengthens fallibility handling. VGI already transports scalar stability and null handling, but not monotonicity or “can throw at runtime.” Defaults are conservative in the optimizer, so these are optional metadata additions:
+DuckDB 2.0 adds optimizer-facing per-argument monotonicity and strengthens
+fallibility handling. VGI 2.0 adds the following nullable field immediately
+after `FunctionInfo.null_handling`:
 
 ```text
-error_mode: unknown | cannot_throw | can_throw_runtime_error
-argument_monotonicity: list[unknown | constant | non_decreasing | strictly_increasing |
-                            non_increasing | strictly_decreasing]
+argument_monotonicity: list<utf8>?
 ```
 
-Do not claim `cannot_throw` for remote functions unless transport, worker code, and data-dependent errors are all covered by that guarantee.
+The allowed strings are `UNKNOWN`, `CONSTANT`, `NON_DECREASING`,
+`STRICTLY_INCREASING`, `NON_INCREASING`, and `STRICTLY_DECREASING`. This field
+is valid only for scalar functions. Null means that the function makes no
+claims. A present list contains exactly one non-null entry for every ordered
+field in `FunctionInfo.arguments`. Fixed, defaulted, and constant parameters
+each occupy a slot; a vararg declaration occupies one slot and its property
+applies independently to every expansion. The order is declaration order and
+is unaffected by `BindRequest.argument_names` or named call syntax.
+
+The DuckDB 1.5 extension validates and preserves this metadata using VGI-owned
+types, but does not apply it to the optimizer. A DuckDB 2.0 adapter can later
+map the same values to `ArgProperties` without changing the wire format.
+
+`error_mode` remains out of scope. In particular, VGI must not claim that a
+remote function cannot throw unless transport, worker code, and all
+data-dependent failures are covered by that guarantee.
 
 ## 6. Catalog and DML features to reject explicitly unless separately designed
 

tests/catalog/test_catalog_interface.py

@@ -28,6 +28,7 @@
     ViewInfo,
 )
 from vgi.catalog.catalog_interface import (
+    ArgumentMonotonicity,
     DistinctDependence,
     FunctionStability,
     MacroType,
@@ -575,6 +576,7 @@ def test_default_values(self) -> None:
         # Scalar behavior fields default to None (set by _function_to_info)
         assert info.stability is None
         assert info.null_handling is None
+        assert info.argument_monotonicity is None
 
         # Documentation fields
         assert info.examples == []
@@ -606,6 +608,7 @@ def test_serialization_roundtrip_with_all_fields(self) -> None:
             tags={},
             stability=FunctionStability.VOLATILE,
             null_handling=NullHandling.SPECIAL,
+            argument_monotonicity=[],
             examples=[
                 CatalogExample(sql="SELECT test_func(1)"),
                 CatalogExample(sql="SELECT test_func(2)"),
@@ -634,6 +637,7 @@ def test_serialization_roundtrip_with_all_fields(self) -> None:
         # New fields
         assert restored.stability == info.stability
         assert restored.null_handling == info.null_handling
+        assert restored.argument_monotonicity == info.argument_monotonicity
         # Examples are deserialized to CatalogExample objects
         assert len(restored.examples) == len(info.examples)
         for restored_ex, orig_ex in zip(restored.examples, info.examples, strict=True):
@@ -660,6 +664,7 @@ def test_enum_serialization(self) -> None:
             tags={},
             stability=FunctionStability.CONSISTENT_WITHIN_QUERY,
             null_handling=NullHandling.SPECIAL,
+            argument_monotonicity=[],
             order_preservation=OrderPreservation.NO_ORDER_GUARANTEE,
             order_dependent=OrderDependence.ORDER_DEPENDENT,
             distinct_dependent=DistinctDependence.DISTINCT_DEPENDENT,
@@ -672,6 +677,7 @@ def test_enum_serialization(self) -> None:
         row = batch.to_pydict()
         assert row["stability"][0] == "CONSISTENT_WITHIN_QUERY"
         assert row["null_handling"][0] == "SPECIAL"
+        assert row["argument_monotonicity"][0] == []
         assert row["order_preservation"][0] == "NO_ORDER_GUARANTEE"
         assert row["order_dependent"][0] == "ORDER_DEPENDENT"
         assert row["distinct_dependent"][0] == "DISTINCT_DEPENDENT"
@@ -680,10 +686,56 @@ def test_enum_serialization(self) -> None:
         restored = FunctionInfo.deserialize_from_batch(batch)
         assert restored.stability == FunctionStability.CONSISTENT_WITHIN_QUERY
         assert restored.null_handling == NullHandling.SPECIAL
+        assert restored.argument_monotonicity == []
         assert restored.order_preservation == OrderPreservation.NO_ORDER_GUARANTEE
         assert restored.order_dependent == OrderDependence.ORDER_DEPENDENT
         assert restored.distinct_dependent == DistinctDependence.DISTINCT_DEPENDENT
 
+    def test_argument_monotonicity_round_trip_uses_argument_order(self) -> None:
+        """Claims use the serialized declaration order, including named slots."""
+        arguments = SerializedSchema(
+            pa.schema([pa.field("value", pa.int64()), pa.field("offset", pa.int64())]).serialize().to_pybytes()
+        )
+        info = FunctionInfo(
+            name="shift",
+            schema_path=["main"],
+            function_type=FunctionType.SCALAR,
+            arguments=arguments,
+            output_schema=empty_schema_bytes(),
+            comment=None,
+            tags={},
+            argument_monotonicity=[
+                ArgumentMonotonicity.STRICTLY_INCREASING,
+                ArgumentMonotonicity.NON_DECREASING,
+            ],
+        )
+
+        batch, _ = deserialize_record_batch(info.serialize_to_bytes())
+        assert batch.to_pydict()["argument_monotonicity"][0] == ["STRICTLY_INCREASING", "NON_DECREASING"]
+        assert FunctionInfo.deserialize_from_batch(batch).argument_monotonicity == info.argument_monotonicity
+
+    def test_argument_monotonicity_rejects_invalid_shape(self) -> None:
+        """The DTO rejects non-scalar and misaligned claims."""
+        arguments = SerializedSchema(pa.schema([pa.field("value", pa.int64())]).serialize().to_pybytes())
+        common = {
+            "name": "bad",
+            "schema_path": ["main"],
+            "arguments": arguments,
+            "output_schema": empty_schema_bytes(),
+            "comment": None,
+            "tags": {},
+            "argument_monotonicity": [ArgumentMonotonicity.UNKNOWN],
+        }
+
+        with pytest.raises(ValueError, match="only valid for scalar functions"):
+            FunctionInfo(function_type=FunctionType.TABLE, **common)
+
+        with pytest.raises(ValueError, match="1 declaration slots"):
+            FunctionInfo(
+                function_type=FunctionType.SCALAR,
+                **{**common, "argument_monotonicity": []},
+            )
+
     def test_v2_record_without_optional_fields(self) -> None:
         """Deserialize a protocol-v2 record that omits optional fields."""
         # Create a minimal protocol-v2 schema without optional fields.

tests/test_metadata.py

@@ -7,6 +7,7 @@
 from typing import Any
 
 import pyarrow as pa
+import pytest
 from vgi_rpc.rpc import OutputCollector
 
 from vgi import (
@@ -19,6 +20,7 @@
     functions_to_arrow,
 )
 from vgi.metadata import (
+    ArgumentMonotonicity,
     arrow_to_functions,
     extract_parameters,
     resolve_metadata,
@@ -400,6 +402,90 @@ def compute(
         assert resolve_metadata(ScalarWithFinalize).has_finalize is False
 
 
+class TestArgumentMonotonicity:
+    """Tests for scalar-only per-declaration monotonicity metadata."""
+
+    def test_scalar_metadata_round_trip(self) -> None:
+        """A unary scalar claim survives metadata resolution and Arrow IPC."""
+        from typing import Annotated
+
+        from vgi.arguments import Param, Returns
+        from vgi.scalar_function import ScalarFunction
+
+        class IdentityFunction(ScalarFunction):
+            class Meta:
+                argument_monotonicity = [ArgumentMonotonicity.STRICTLY_INCREASING]
+
+            @classmethod
+            def compute(
+                cls,
+                value: Annotated[pa.Int64Array, Param()],
+            ) -> Annotated[pa.Int64Array, Returns()]:
+                return value
+
+        metadata = resolve_metadata(IdentityFunction)
+        assert metadata.argument_monotonicity == [ArgumentMonotonicity.STRICTLY_INCREASING]
+
+        restored = arrow_to_functions(functions_to_arrow([IdentityFunction]))[0]
+        assert restored.argument_monotonicity == [ArgumentMonotonicity.STRICTLY_INCREASING]
+
+    def test_entry_count_must_match_declaration_slots(self) -> None:
+        """A list is aligned with declarations rather than a particular call."""
+        from typing import Annotated
+
+        from vgi.arguments import Param, Returns
+        from vgi.scalar_function import ScalarFunction
+
+        class BadCountFunction(ScalarFunction):
+            class Meta:
+                argument_monotonicity: list[ArgumentMonotonicity] = []
+
+            @classmethod
+            def compute(
+                cls,
+                value: Annotated[pa.Int64Array, Param()],
+            ) -> Annotated[pa.Int64Array, Returns()]:
+                return value
+
+        with pytest.raises(ValueError, match="1 argument slots"):
+            resolve_metadata(BadCountFunction)
+
+    def test_varargs_declaration_occupies_one_slot(self) -> None:
+        """Call-time vararg expansion does not expand metadata declarations."""
+        from typing import Annotated
+
+        from vgi.arguments import Param, Returns
+        from vgi.scalar_function import ScalarFunction
+
+        class VarargsFunction(ScalarFunction):
+            class Meta:
+                argument_monotonicity = [ArgumentMonotonicity.NON_DECREASING]
+
+            @classmethod
+            def compute(
+                cls,
+                values: Annotated[list[pa.Array[Any]], Param(varargs=True)],
+            ) -> Annotated[pa.Array[Any], Returns()]:
+                return values[0]
+
+        metadata = resolve_metadata(VarargsFunction)
+        assert len(metadata.parameters) == 1
+        assert metadata.parameters[0].is_varargs is True
+        assert metadata.argument_monotonicity == [ArgumentMonotonicity.NON_DECREASING]
+
+    def test_rejected_for_non_scalar_function(self) -> None:
+        """DuckDB exposes argument properties only on scalar functions."""
+
+        class BadTableFunction(TableInOutFunction):  # type: ignore[type-arg]
+            class Meta:
+                argument_monotonicity = [ArgumentMonotonicity.UNKNOWN]
+
+            data: TableInput = Arg[TableInput](0, doc="Input table")  # type: ignore[assignment]
+
+        with pytest.raises(TypeError, match="only valid for scalar functions"):
+            resolve_metadata(BadTableFunction)
+
+
 class TestArrowSerialization:
     """Tests for Arrow serialization of metadata."""
 

vgi/__init__.py

@@ -80,6 +80,7 @@
     value_payload,
 )
 from vgi.metadata import (
+    ArgumentMonotonicity,
     CatalogFunctionType,
     EvaluationContextCapability,
     FilterFunctionCapability,
@@ -138,6 +139,7 @@
     "ArgumentSpec",
     "ArgumentValidationError",
     "Arguments",
+    "ArgumentMonotonicity",
     "Auth",
     "AuthContext",
     "CallContext",

vgi/_test_fixtures/scalar/null_handling.py

@@ -10,7 +10,7 @@
 import pyarrow.compute as pc
 
 from vgi.arguments import ConstParam, Param, Returns
-from vgi.metadata import FunctionExample, NullHandling
+from vgi.metadata import ArgumentMonotonicity, FunctionExample, NullHandling
 from vgi.scalar_function import ScalarFunction
 
 
@@ -87,6 +87,7 @@ class Meta:
         name = "null_handling"
         description = "Returns value or -5000 if null"
         null_handling = NullHandling.SPECIAL
+        argument_monotonicity = [ArgumentMonotonicity.STRICTLY_INCREASING]
         examples = [
             FunctionExample(
                 sql="SELECT null_handling(value) FROM data",

vgi/catalog/catalog_interface.py

@@ -40,6 +40,7 @@
 from vgi.arguments import Arguments, SecretLookupEntry
 from vgi.exceptions import CatalogReadOnlyError
 from vgi.metadata import (
+    ArgumentMonotonicity,
     DistinctDependence,
     EvaluationContextCapability,
     FilterFunctionCapability,
@@ -696,6 +697,10 @@ class FunctionInfo(CatalogSchemaObject, ArrowSerializableDataclass):
             functions).
         null_handling: Scalar function behavior field (None for non-scalar
             functions).
+        argument_monotonicity: Scalar-only properties aligned with the ordered
+            fields in ``arguments``. A present list has exactly one entry per
+            declaration slot, including one for a vararg declaration. ``None``
+            means no claims.
         description: Intrinsic documentation from function metadata
             (``Meta.description``). ``comment`` (inherited from the base
             object) is a separate, shorter operator-facing note from
@@ -801,6 +806,7 @@ class FunctionInfo(CatalogSchemaObject, ArrowSerializableDataclass):
 
     stability: FunctionStability | None = None
     null_handling: NullHandling | None = None
+    argument_monotonicity: Annotated[list[ArgumentMonotonicity] | None, ArrowType(pa.list_(pa.string()))] = None
 
     description: str = ""
     examples: list[CatalogExample] = field(default_factory=list)
@@ -857,6 +863,22 @@ class FunctionInfo(CatalogSchemaObject, ArrowSerializableDataclass):
 
     required_secrets: list[SecretLookupEntry] = field(default_factory=list)
 
+    def __post_init__(self) -> None:
+        """Validate scalar-only argument monotonicity claims."""
+        if self.argument_monotonicity is None:
+            return
+        if self.function_type is not FunctionType.SCALAR:
+            raise ValueError("argument_monotonicity is only valid for scalar functions")
+        argument_schema = pa.ipc.read_schema(pa.py_buffer(self.arguments))
+        if len(self.argument_monotonicity) != len(argument_schema):
+            raise ValueError(
+                f"argument_monotonicity has {len(self.argument_monotonicity)} entries "
+                f"but arguments has {len(argument_schema)} declaration slots"
+            )
+        for index, value in enumerate(self.argument_monotonicity):
+            if not isinstance(value, ArgumentMonotonicity):
+                raise ValueError(f"argument_monotonicity[{index}] is not a valid ArgumentMonotonicity")
+
 
 @dataclass(frozen=True)
 class CopyFromFormatInfo(CatalogObject, ArrowSerializableDataclass):
@@ -3465,6 +3487,7 @@ def _function_to_info(self, func_cls: type, schema_path: SchemaPath) -> Function
             # Scalar/aggregate function behavior fields
             stability=meta.stability if is_scalar else None,
             null_handling=meta.null_handling if (is_scalar or is_aggregate) else None,
+            argument_monotonicity=meta.argument_monotonicity if is_scalar else None,
             # Documentation fields
             description=meta.description or "",  # Intrinsic from Meta.description
             examples=[

vgi/codegen/ts_client.py

@@ -419,8 +419,6 @@ def emit(out: TextIO) -> None:
         body.write(
             f"export const decode{ts_name} = (b: Uint8Array): {ts_name} => decodeASD<{ts_name}>({schema_ref}, b);\n",
         )
-    body.write("\n")
-
     out.write("// ============================================================================\n")
     out.write(
         provenance_comment(