feat: per-parameter documentation for macros

Macros gain an optional arguments_schema (one nullable field per parameter,
carrying the per-parameter description via the same vgi_doc field-metadata key
functions use) on MacroCreateRequest and the macro listing/get responses, plus
a declarative Macro.parameter_docs API. Mirrors how functions carry per-argument
docs; additive + optional so older workers/extensions are unaffected. Closes the
gap where macro parameters were name-only and undocumentable.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: rustyconover

tests/catalog/test_serialization.py

@@ -615,6 +615,140 @@ def test_macro_type_enum_survival(self) -> None:
             restored = MacroInfo.deserialize_from_batch(batch)
             assert restored.macro_type == macro_type
 
+    def test_arguments_schema_round_trip(self) -> None:
+        """arguments_schema carries vgi_doc per documented param; absent doc -> no key."""
+        from vgi.argument_spec import VGI_DOC_KEY, macro_arguments_schema, macro_parameter_docs_from_schema
+
+        defaults = pa.RecordBatch.from_pydict({"lo": pa.array([0], type=pa.int64())})
+        args = macro_arguments_schema(
+            parameters=["val", "lo", "hi"],
+            parameter_default_values=defaults,
+            parameter_docs={"val": "value to clamp", "hi": "upper bound"},
+        )
+        original = MacroInfo(
+            name="clamp",
+            schema_name="main",
+            macro_type=MacroType.SCALAR,
+            parameters=["val", "lo", "hi"],
+            parameter_default_values=defaults,
+            definition="GREATEST(lo, LEAST(hi, val))",
+            comment=None,
+            tags={},
+            arguments_schema=args,
+        )
+        serialized = original.serialize_to_bytes()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = MacroInfo.deserialize_from_batch(batch)
+
+        assert restored.arguments_schema is not None
+        rs = restored.arguments_schema
+        # One field per parameter, in order.
+        assert rs.names == ["val", "lo", "hi"]
+        # Field type tracks the default value type when known, else null.
+        assert rs.field("lo").type == pa.int64()
+        assert rs.field("val").type == pa.null()
+        assert rs.field("hi").type == pa.null()
+        # Documented params carry vgi_doc; undocumented (lo) has no key.
+        assert (rs.field("val").metadata or {}).get(VGI_DOC_KEY) == b"value to clamp"
+        assert (rs.field("hi").metadata or {}).get(VGI_DOC_KEY) == b"upper bound"
+        assert VGI_DOC_KEY not in (rs.field("lo").metadata or {})
+        # Convenience extractor returns only documented params.
+        assert macro_parameter_docs_from_schema(rs) == {"val": "value to clamp", "hi": "upper bound"}
+
+    def test_none_arguments_schema(self) -> None:
+        """arguments_schema defaults to None (older workers) and survives round-trip."""
+        original = MacroInfo(
+            name="simple",
+            schema_name="main",
+            macro_type=MacroType.SCALAR,
+            parameters=["x"],
+            definition="x",
+            comment=None,
+            tags={},
+        )
+        serialized = original.serialize_to_bytes()
+        batch, _ = deserialize_record_batch(serialized)
+        restored = MacroInfo.deserialize_from_batch(batch)
+        assert restored.arguments_schema is None
+
+
+class TestMacroArgumentsSchemaWire:
+    """Macro per-parameter docs flow over create/list wire types."""
+
+    def test_declarative_macro_to_info_carries_docs(self) -> None:
+        """Declarative Macro.parameter_docs -> MacroInfo.arguments_schema vgi_doc."""
+        from vgi.argument_spec import macro_parameter_docs_from_schema
+        from vgi.catalog.descriptors import Macro
+
+        m = Macro(
+            name="clamp",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "lo", "hi"],
+            parameter_default_values=pa.RecordBatch.from_pydict(
+                {"lo": pa.array([0], type=pa.int64()), "hi": pa.array([100], type=pa.int64())}
+            ),
+            parameter_docs={"x": "value to clamp"},
+            definition="GREATEST(lo, LEAST(hi, x))",
+        )
+        info = m.to_macro_info("main")
+        assert info.arguments_schema is not None
+        assert info.arguments_schema.names == ["x", "lo", "hi"]
+        assert macro_parameter_docs_from_schema(info.arguments_schema) == {"x": "value to clamp"}
+
+    def test_declarative_macro_rejects_unknown_doc_param(self) -> None:
+        """parameter_docs keys must be in parameters (validated like defaults)."""
+        from vgi.catalog.descriptors import Macro
+
+        with pytest.raises(ValueError, match="documented parameter 'bogus' not found"):
+            Macro(
+                name="bad",
+                macro_type=MacroType.SCALAR,
+                parameters=["x"],
+                parameter_docs={"bogus": "nope"},
+                definition="x",
+            )
+
+    def test_macro_create_request_round_trip(self) -> None:
+        """MacroCreateRequest carries arguments_schema over the wire."""
+        from vgi.argument_spec import macro_arguments_schema, macro_parameter_docs_from_schema
+        from vgi.catalog import OnConflict
+        from vgi.protocol import MacroCreateRequest
+
+        args = macro_arguments_schema(
+            parameters=["x", "y"],
+            parameter_docs={"x": "first", "y": "second"},
+        )
+        req = MacroCreateRequest(
+            attach_opaque_data=b"attach",
+            schema_name="main",
+            name="add",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "y"],
+            definition="x + y",
+            on_conflict=OnConflict.ERROR,
+            arguments_schema=args,
+        )
+        restored = MacroCreateRequest.deserialize_from_bytes(req.serialize_to_bytes())
+        assert restored.arguments_schema is not None
+        assert macro_parameter_docs_from_schema(restored.arguments_schema) == {"x": "first", "y": "second"}
+
+    def test_macro_create_request_none_arguments_schema(self) -> None:
+        """MacroCreateRequest.arguments_schema defaults to None and round-trips."""
+        from vgi.catalog import OnConflict
+        from vgi.protocol import MacroCreateRequest
+
+        req = MacroCreateRequest(
+            attach_opaque_data=b"attach",
+            schema_name="main",
+            name="add",
+            macro_type=MacroType.SCALAR,
+            parameters=["x", "y"],
+            definition="x + y",
+            on_conflict=OnConflict.ERROR,
+        )
+        restored = MacroCreateRequest.deserialize_from_bytes(req.serialize_to_bytes())
+        assert restored.arguments_schema is None
+
 
 class TestFunctionInfoSerialization:
     """Test FunctionInfo serialization round-trip."""

uv.lock

@@ -752,6 +752,7 @@ def macro_create(
         definition: str,
         on_conflict: OnConflict,
         parameter_default_values: pa.RecordBatch | None = None,
+        arguments_schema: pa.Schema | None = None,
     ) -> None:
         """Create a new macro."""
         schema_data = self._get_schema(attach_opaque_data, schema_name)
@@ -773,6 +774,7 @@ def macro_create(
                 definition=definition,
                 comment=None,
                 tags={},
+                arguments_schema=arguments_schema,
             )
         )
         self._increment_version(attach_opaque_data)

vgi/_test_fixtures/catalog.py

@@ -519,6 +519,10 @@ def _build_enum_stats() -> dict[str, ColumnStatisticsInput]:
                     parameters=["x", "y"],
                     definition="x * y",
                     comment="Multiply two values",
+                    parameter_docs={
+                        "x": "First factor",
+                        "y": "Second factor",
+                    },
                 ),
                 Macro(
                     name="vgi_clamp",
@@ -530,13 +534,19 @@ def _build_enum_stats() -> dict[str, ColumnStatisticsInput]:
                     ),
                     definition="GREATEST(lo, LEAST(hi, val))",
                     comment="Clamp a value between lo and hi (defaults: 0..100)",
+                    parameter_docs={
+                        "val": "Value to clamp",
+                        "lo": "Lower bound (inclusive)",
+                        "hi": "Upper bound (inclusive)",
+                    },
                 ),
                 Macro(
                     name="vgi_range_table",
                     macro_type=MacroType.TABLE,
                     parameters=["n"],
                     definition="SELECT * FROM range(n)",
                     comment="Table macro returning range of values",
+                    parameter_docs={"n": "Number of rows to generate"},
                 ),
             ],
         ),

vgi/_test_fixtures/worker.py

@@ -27,6 +27,8 @@
     "ArgumentSpec",
     "argument_specs_to_schema",
     "extract_argument_specs",
+    "macro_arguments_schema",
+    "macro_parameter_docs_from_schema",
     "schema_to_argument_specs",
     # Metadata constants for parsing schemas
     "VGI_ARG_KEY",
@@ -280,6 +282,86 @@ def schema_to_argument_specs(schema: pa.Schema) -> list[ArgumentSpec]:
     return specs
 
 
+# =============================================================================
+# Macro Argument Schemas
+# =============================================================================
+
+
+def macro_arguments_schema(
+    parameters: Sequence[str],
+    parameter_default_values: pa.RecordBatch | None = None,
+    parameter_docs: dict[str, str] | None = None,
+) -> pa.Schema:
+    """Build a macro ``arguments_schema`` describing macro parameters.
+
+    Mirrors the function ``arguments_schema`` mechanism: one Arrow field per
+    macro parameter, in ``parameters`` order, each nullable. The per-parameter
+    description is carried via the same ``vgi_doc`` field-metadata key functions
+    use (UTF-8, presence-only — the key is omitted entirely when there is no
+    doc). A parameter's field type is the type of its default value when one is
+    known (from ``parameter_default_values``), else ``pa.null()``.
+
+    Args:
+        parameters: Ordered list of macro parameter names.
+        parameter_default_values: Optional one-row ``RecordBatch`` whose columns
+            are parameter names with typed default values; used to infer each
+            parameter's field type.
+        parameter_docs: Optional mapping of parameter name to description. Empty
+            or missing descriptions yield no ``vgi_doc`` metadata on the field.
+
+    Returns:
+        Arrow schema with one nullable field per parameter, in order.
+
+    """
+    docs = parameter_docs or {}
+
+    # Map parameter name -> Arrow type from the typed default values, if any.
+    default_types: dict[str, pa.DataType] = {}
+    if parameter_default_values is not None:
+        for default_field in parameter_default_values.schema:
+            default_types[default_field.name] = default_field.type
+
+    fields: list[pa.Field[Any]] = []
+    for name in parameters:
+        metadata: dict[bytes, bytes] = {}
+        doc = docs.get(name, "")
+        if doc:
+            metadata[VGI_DOC_KEY] = doc.encode("utf-8")
+
+        field = pa.field(
+            name,
+            default_types.get(name, pa.null()),
+            nullable=True,
+            metadata=metadata if metadata else None,
+        )
+        fields.append(field)
+
+    return pa.schema(fields)
+
+
+def macro_parameter_docs_from_schema(schema: pa.Schema) -> dict[str, str]:
+    """Extract per-parameter descriptions from a macro ``arguments_schema``.
+
+    Inverse of [`macro_arguments_schema`][]'s ``vgi_doc`` handling: reads the
+    ``vgi_doc`` field metadata (UTF-8) for each field. Fields without the key
+    (undocumented) are omitted from the result.
+
+    Args:
+        schema: A macro ``arguments_schema`` (one field per parameter).
+
+    Returns:
+        Mapping of parameter name to description, for documented parameters only.
+
+    """
+    docs: dict[str, str] = {}
+    for field in schema:
+        metadata = field.metadata or {}
+        doc_bytes = metadata.get(VGI_DOC_KEY)
+        if doc_bytes:
+            docs[field.name] = doc_bytes.decode("utf-8")
+    return docs
+
+
 # =============================================================================
 # Extraction from Function Classes
 # =============================================================================

vgi/argument_spec.py

@@ -435,13 +435,23 @@ class MacroInfo(CatalogSchemaObject, ArrowSerializableDataclass):
             names and values are typed defaults. None if no defaults.
             Serialized as IPC bytes over the wire.
         definition: The SQL expression (scalar) or query (table).
+        arguments_schema: Optional Arrow schema (serialized as IPC bytes) with one
+            nullable field per parameter, in ``parameters`` order. Each field's type
+            is the parameter's default value type when known (else null), and the
+            ``vgi_doc`` field metadata key carries the parameter's description (UTF-8,
+            presence-only — omitted when undocumented). Mirrors the per-argument doc
+            channel functions expose via ``FunctionInfo.arguments``. None means the
+            worker did not supply per-parameter docs (older workers); the extension
+            falls back to ``parameters`` for names. Built with
+            ``vgi.argument_spec.macro_arguments_schema``.
 
     """
 
     macro_type: "MacroType"
     parameters: list[str]
     parameter_default_values: Annotated[pa.RecordBatch | None, ArrowType(pa.binary())] = None
     definition: str = ""
+    arguments_schema: Annotated[pa.Schema | None, ArrowType(pa.binary())] = None
 
 
 class FunctionType(Enum):
@@ -1979,8 +1989,25 @@ def macro_create(
         definition: str,
         on_conflict: OnConflict,
         parameter_default_values: pa.RecordBatch | None = None,
+        arguments_schema: pa.Schema | None = None,
     ) -> None:
-        """Create a new macro with the given definition."""
+        """Create a new macro with the given definition.
+
+        Args:
+            attach_opaque_data: Per-attach catalog session token.
+            transaction_opaque_data: Optional transaction handle.
+            schema_name: Schema to create the macro in.
+            name: Name for the new macro.
+            macro_type: Whether this is a scalar or table macro.
+            parameters: Ordered list of parameter names.
+            definition: SQL expression (scalar) or query (table).
+            on_conflict: Behavior if the macro already exists.
+            parameter_default_values: One-row ``RecordBatch`` with typed defaults.
+            arguments_schema: Optional Arrow schema (one nullable field per
+                parameter, in ``parameters`` order) carrying per-parameter
+                descriptions via the ``vgi_doc`` field metadata key. ``None`` when
+                no per-parameter docs are supplied.
+        """
         raise NotImplementedError("Macro create not implemented.")
 
     def macro_drop(