Add argument monotonicity protocol metadata

Author: rustyconover

README.md

@@ -99,6 +99,13 @@ public final class DemoWorker {
 
 The `compute()` signature drives everything: `@Vector` parameters are per-row input columns, `@Const` parameters are bind-time constants, `@Setting` parameters read session settings, and the last unannotated Arrow vector is the framework-allocated output.
 
+Scalar functions may override `argumentMonotonicity()` and return a
+`List<ArgumentMonotonicity>`. The optional list follows `argumentSpecs()`
+declaration order and must contain exactly one entry per declaration. Fixed,
+defaulted, and constant arguments each occupy one slot; a vararg declaration
+occupies one slot regardless of call-time expansion. Named SQL invocation order
+does not reorder these claims. Returning `null` makes no claims.
+
 **The worker JVM needs two flags** — Apache Arrow requires access to `java.nio` internals, and the shared-memory transport uses the FFM API:
 
 ```

vgi-example-worker/src/main/java/farm/query/vgi/example/scalar/NullHandlingFunction.java

@@ -3,6 +3,7 @@
 package farm.query.vgi.example.scalar;
 
 import farm.query.vgi.function.FunctionMetadata;
+import farm.query.vgi.function.ArgumentMonotonicity;
 import farm.query.vgi.function.NullHandling;
 import farm.query.vgi.function.Stability;
 import farm.query.vgi.scalar.ScalarFn;
@@ -19,6 +20,10 @@ public final class NullHandlingFunction extends ScalarFn {
                 Stability.CONSISTENT, NullHandling.SPECIAL, false, false, false, false);
     }
 
+    @Override public java.util.List<ArgumentMonotonicity> argumentMonotonicity() {
+        return java.util.List.of(ArgumentMonotonicity.STRICTLY_INCREASING);
+    }
+
     public void compute(@Vector BigIntVector value, BigIntVector result) {
         int rows = value.getValueCount();
         for (int i = 0; i < rows; i++) {

vgi/src/main/java/farm/query/vgi/function/ArgumentMonotonicity.java

@@ -0,0 +1,16 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.function;
+
+/** Monotonicity of a scalar function in one argument, with all others fixed. */
+public enum ArgumentMonotonicity {
+    UNKNOWN,
+    CONSTANT,
+    NON_DECREASING,
+    STRICTLY_INCREASING,
+    NON_INCREASING,
+    STRICTLY_DECREASING;
+
+    /** @return the canonical uppercase VGI wire value. */
+    public String wireName() { return name(); }
+}

vgi/src/main/java/farm/query/vgi/function/FunctionDescriptor.java

@@ -55,6 +55,15 @@ default FunctionSpec spec() {
      */
     default List<ArgSpec> argumentSpecs() { return spec().argumentSpecs(); }
 
+    /**
+     * Scalar-only monotonicity claims in {@link #argumentSpecs()} declaration
+     * order. {@code null} makes no claims; a vararg declaration occupies one
+     * slot regardless of call-time expansion.
+     *
+     * @return one claim per argument declaration, or {@code null}.
+     */
+    default List<ArgumentMonotonicity> argumentMonotonicity() { return null; }
+
     /**
      * Authoritative typed parameter defaults. When present this is exactly one
      * row containing only defaulted parameters in signature order; a present

vgi/src/main/java/farm/query/vgi/internal/FunctionInfoSerializer.java

@@ -20,6 +20,7 @@
 import static farm.query.vgi.internal.IpcStructBuilder.I64;
 import static farm.query.vgi.internal.IpcStructBuilder.UTF8;
 import static farm.query.vgi.internal.IpcStructBuilder.writeNullableInt64;
+import static farm.query.vgi.internal.IpcStructBuilder.writeNullableStringList;
 import static farm.query.vgi.internal.IpcStructBuilder.listOf;
 import static farm.query.vgi.internal.IpcStructBuilder.listOfPrim;
 import static farm.query.vgi.internal.IpcStructBuilder.mapUtf8Utf8;
@@ -92,6 +93,9 @@ static void enableBadEnumNullHandling() {
             nullable("parameter_default_values", BINARY),
             STABILITY.field(true),
             NULL_HANDLING.field(true),
+            new Field("argument_monotonicity",
+                    new FieldType(true, new ArrowType.List(), null),
+                    List.of(nullable("item", UTF8))),
             nonNull("description", UTF8),
             listOf("examples", new Field("item",
                     new FieldType(true, new ArrowType.Struct(), null),
@@ -157,6 +161,7 @@ static void enableBadEnumNullHandling() {
                             nullable("secret_name", UTF8))))));
 
     static byte[] serialize(FunctionInfo info) {
+        validateArgumentMonotonicity(info);
         DictionaryProvider.MapDictionaryProvider provider = new DictionaryProvider.MapDictionaryProvider();
         for (EnumDict d : DICTS) d.register(provider);
 
@@ -171,6 +176,7 @@ static byte[] serialize(FunctionInfo info) {
             writeNullableVarBinary(v.get("parameter_default_values"), info.parameter_default_values());
             STABILITY.write(v.get("stability"), info.stability());
             NULL_HANDLING.write(v.get("null_handling"), info.null_handling());
+            writeNullableStringList(v.get("argument_monotonicity"), info.argument_monotonicity());
             writeVarChar(v.get("description"), info.description());
             writeStringList(v.get("examples"), List.of());
             writeStringList(v.get("categories"), info.categories());
@@ -204,6 +210,27 @@ static byte[] serialize(FunctionInfo info) {
         });
     }
 
+    private static void validateArgumentMonotonicity(FunctionInfo info) {
+        List<String> values = info.argument_monotonicity();
+        if (values == null) return;
+        if (!"scalar".equals(info.function_type())) {
+            throw new IllegalArgumentException("argument_monotonicity is only valid for scalar functions");
+        }
+        int expected = SchemaUtil.deserializeSchema(info.arguments()).getFields().size();
+        if (values.size() != expected) {
+            throw new IllegalArgumentException("argument_monotonicity has " + values.size()
+                    + " entries, expected " + expected + " declaration slots");
+        }
+        var allowed = java.util.Set.of("UNKNOWN", "CONSTANT", "NON_DECREASING",
+                "STRICTLY_INCREASING", "NON_INCREASING", "STRICTLY_DECREASING");
+        for (int i = 0; i < values.size(); i++) {
+            if (!allowed.contains(values.get(i))) {
+                throw new IllegalArgumentException("argument_monotonicity[" + i
+                        + "] has unknown value " + values.get(i));
+            }
+        }
+    }
+
     private static Field filterIdentities(String name) {
         return listOf(name, new Field("item",
                 new FieldType(true, new ArrowType.Struct(), null),

vgi/src/main/java/farm/query/vgi/internal/IpcStructBuilder.java

@@ -296,6 +296,17 @@ public static void writeStringList(FieldVector v, List<String> values) {
         w.setValueCount(1);
     }
 
+    /** Write a nullable list of non-null strings into row 0. */
+    public static void writeNullableStringList(FieldVector v, List<String> values) {
+        ListVector lv = (ListVector) v;
+        if (values == null) {
+            lv.setNull(0);
+            lv.setValueCount(1);
+            return;
+        }
+        writeStringList(v, values);
+    }
+
     /**
      * Write a list of ints into row 0 of a {@code ListVector}. Nulls in
      * {@code values} are skipped.

vgi/src/main/java/farm/query/vgi/internal/VgiServiceImpl.java

@@ -2613,7 +2613,7 @@ private FunctionInfo toTableInOutFunctionInfo(TableInOutFunction fn, String sche
         return new FunctionInfo(
                 base.comment(), base.tags(), base.name(), base.schema_path(), base.function_type(),
                 base.arguments(), base.output_schema(), base.parameter_default_values(),
-                base.stability(), base.null_handling(),
+                base.stability(), base.null_handling(), base.argument_monotonicity(),
                 base.description(), base.examples(), base.categories(), base.projection_pushdown(),
                 base.filter_pushdown(), base.sampling_pushdown(), base.late_materialization(),
                 base.filter_semantic_profiles(), base.additional_filter_functions(),
@@ -2640,7 +2640,7 @@ private FunctionInfo toAggregateFunctionInfo(AggregateFunction<?> fn, String sch
         return new FunctionInfo(
                 base.comment(), base.tags(), base.name(), base.schema_path(), base.function_type(),
                 base.arguments(), base.output_schema(), base.parameter_default_values(),
-                base.stability(), base.null_handling(),
+                base.stability(), base.null_handling(), base.argument_monotonicity(),
                 base.description(), base.examples(), base.categories(), base.projection_pushdown(),
                 base.filter_pushdown(), base.sampling_pushdown(), base.late_materialization(),
                 base.filter_semantic_profiles(), base.additional_filter_functions(),
@@ -2660,13 +2660,13 @@ private FunctionInfo toBufferingFunctionInfo(
         BindResponse r = fn.onBind(new TableInOutBindParams(fn.name(), Arguments.empty(), null, Map.of()));
         FunctionInfo base = baseFunctionInfo(fn.name(), fn.metadata(), schemaName, "table_buffering",
                 ArgumentSpecSerializer.toIpcBytes(fn.argumentSpecs()), bindOutput(r),
-                encodeParameterDefaults(fn), /*hasFinalize=*/true, 1);
+                encodeParameterDefaults(fn), /*hasFinalize=*/true, 1, null);
         // Re-stamp the buffering-specific ordering flags (baseFunctionInfo
         // hardcodes them false; they're only meaningful for TableBuffering).
         return new FunctionInfo(
                 base.comment(), base.tags(), base.name(), base.schema_path(), base.function_type(),
                 base.arguments(), base.output_schema(), base.parameter_default_values(),
-                base.stability(), base.null_handling(),
+                base.stability(), base.null_handling(), base.argument_monotonicity(),
                 base.description(), base.examples(), base.categories(), base.projection_pushdown(),
                 base.filter_pushdown(), base.sampling_pushdown(), base.late_materialization(),
                 base.filter_semantic_profiles(), base.additional_filter_functions(),
@@ -2714,16 +2714,38 @@ private static FunctionInfo baseFunctionInfo(farm.query.vgi.function.FunctionDes
         // Only TableFunction has a meaningful maxWorkers; everything else
         // is single-worker by definition.
         int maxWorkers = fn instanceof TableFunction tf ? (int) tf.maxWorkers() : 1;
+        List<String> argumentMonotonicity = null;
+        if (fn.argumentMonotonicity() != null) {
+            if (!"scalar".equals(type)) {
+                throw new IllegalArgumentException(
+                        "argumentMonotonicity is only valid for scalar functions");
+            }
+            if (fn.argumentMonotonicity().size() != fn.argumentSpecs().size()) {
+                throw new IllegalArgumentException("argumentMonotonicity has "
+                        + fn.argumentMonotonicity().size() + " entries, expected "
+                        + fn.argumentSpecs().size() + " declaration slots");
+            }
+            argumentMonotonicity = fn.argumentMonotonicity().stream()
+                    .map(value -> {
+                        if (value == null) {
+                            throw new IllegalArgumentException(
+                                    "argumentMonotonicity must not contain null entries");
+                        }
+                        return value.wireName();
+                    })
+                    .toList();
+        }
         return baseFunctionInfo(fn.name(), fn.metadata(), schemaName, type,
                 ArgumentSpecSerializer.toIpcBytes(fn.argumentSpecs()), outputSchema,
                 encodeParameterDefaults(fn), hasFinalize,
-                maxWorkers);
+                maxWorkers, argumentMonotonicity);
     }
 
     private static FunctionInfo baseFunctionInfo(String name, FunctionMetadata md, String schemaName,
                                            String type, byte[] arguments, byte[] outputSchema,
                                            byte[] parameterDefaultValues,
-                                           boolean hasFinalize, int maxWorkers) {
+                                           boolean hasFinalize, int maxWorkers,
+                                           List<String> argumentMonotonicity) {
         return new FunctionInfo(
                 null,
                 md.tags() == null ? Map.of() : md.tags(),
@@ -2736,6 +2758,7 @@ private static FunctionInfo baseFunctionInfo(String name, FunctionMetadata md, S
                 stabilityWire(md.stability()),
                 (BAD_ENUM_MODE && "scalar".equals(type) && "double".equals(name))
                         ? "WEIRD" : nullHandlingWire(md.nullHandling()),
+                argumentMonotonicity,
                 md.description(),
                 md.examples() == null ? List.of() : md.examples(),
                 md.categories() == null ? List.of() : md.categories(),

vgi/src/main/java/farm/query/vgi/protocol/FunctionInfo.java

@@ -26,6 +26,7 @@
  * @param output_schema                IPC-encoded output schema.
  * @param stability                    dictionary-encoded function stability, or {@code null}.
  * @param null_handling                dictionary-encoded null-handling policy, or {@code null}.
+ * @param argument_monotonicity        scalar-only claims in argument declaration order, or {@code null}.
  * @param description                  human-readable description.
  * @param examples                     usage examples.
  * @param categories                   classification categories.
@@ -87,6 +88,7 @@ public record FunctionInfo(
         @Nullable byte[] parameter_default_values,
         @ArrowField(ArrowFieldType.DICT_INT16_UTF8) @Nullable String stability,
         @ArrowField(ArrowFieldType.DICT_INT16_UTF8) @Nullable String null_handling,
+        @Nullable List<String> argument_monotonicity,
         String description,
         List<FunctionExample> examples,
         List<String> categories,

vgi/src/test/java/farm/query/vgi/generated/VgiProtocolSchemas.java

@@ -1,7 +1,7 @@
 // GENERATED by vgi.codegen.java_schemas. DO NOT EDIT BY HAND.
 //
 // Generator: python -m vgi.codegen.java_schemas v1
-// Content hash: f42952c0f44f
+// Content hash: 994c043d7a66
 //
 // To regenerate:
 //   uv run --project ~/Development/vgi-python python -m vgi.codegen.java_schemas \
@@ -227,6 +227,8 @@ private static Schema functionInfo() {
                         new DictionaryEncoding(0L, false, new ArrowType.Int(16, true))),
                 dict("null_handling", true, new ArrowType.Utf8(),
                         new DictionaryEncoding(0L, false, new ArrowType.Int(16, true))),
+                f("argument_monotonicity", true, new ArrowType.List(),
+                        f("item", true, new ArrowType.Utf8())),
                 f("description", false, new ArrowType.Utf8()),
                 f("examples", false, new ArrowType.List(),
                         f("item", true, new ArrowType.Struct(),

vgi/src/test/java/farm/query/vgi/internal/FunctionInfoArgumentMonotonicityTest.java

@@ -0,0 +1,70 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.internal;
+
+import farm.query.vgi.function.ArgSpec;
+import farm.query.vgi.function.ArgumentMonotonicity;
+import farm.query.vgi.protocol.FunctionInfo;
+import farm.query.vgi.scalar.ScalarFn;
+import farm.query.vgi.types.Schemas;
+import farm.query.vgirpc.wire.Allocators;
+import org.apache.arrow.vector.BigIntVector;
+import org.apache.arrow.vector.complex.ListVector;
+import org.junit.jupiter.api.Test;
+
+import java.util.List;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+class FunctionInfoArgumentMonotonicityTest {
+
+    static class Identity extends ScalarFn {
+        private final List<ArgumentMonotonicity> monotonicity;
+
+        Identity() {
+            this(List.of(
+                    ArgumentMonotonicity.STRICTLY_INCREASING,
+                    ArgumentMonotonicity.CONSTANT));
+        }
+
+        Identity(List<ArgumentMonotonicity> monotonicity) {
+            this.monotonicity = monotonicity;
+        }
+
+        @Override public String name() { return "identity"; }
+        @Override public String description() { return "identity"; }
+        @Override public List<ArgSpec> argumentSpecs() {
+            return List.of(
+                    ArgSpec.positional("value", 0, Schemas.INT64),
+                    ArgSpec.positional("offset", 1, Schemas.INT64));
+        }
+        @Override public List<ArgumentMonotonicity> argumentMonotonicity() {
+            return monotonicity;
+        }
+        public void compute(
+                @farm.query.vgi.scalar.Vector BigIntVector value,
+                @farm.query.vgi.scalar.Vector BigIntVector offset,
+                BigIntVector result) {}
+    }
+
+    @Test
+    void serializesClaimsInDeclarationOrder() {
+        FunctionInfo info = VgiServiceImpl.scalarFunctionInfo(new Identity(), "main");
+        assertEquals(List.of("STRICTLY_INCREASING", "CONSTANT"), info.argument_monotonicity());
+        try (var encoded = BatchUtil.readSingleBatch(
+                FunctionInfoSerializer.serialize(info), Allocators.root())) {
+            var values = (ListVector) encoded.getVector("argument_monotonicity");
+            assertEquals("STRICTLY_INCREASING", values.getObject(0).get(0).toString());
+            assertEquals("CONSTANT", values.getObject(0).get(1).toString());
+        }
+    }
+
+    @Test
+    void rejectsWrongDeclarationCount() {
+        var error = assertThrows(IllegalArgumentException.class,
+                () -> VgiServiceImpl.scalarFunctionInfo(new Identity(List.of()), "main"));
+        assertTrue(error.getMessage().contains("expected 2 declaration slots"));
+    }
+}