release: 0.22.0 — VGI protocol 1.3.0, global functions, vgirpc 0.20.0

The community extension already serves protocol 1.3.0 (vgi commit e76ba86),
so a worker emitting the old 15-field catalog_attach result fails ATTACH
against what users install today. The new fields are non-nullable and the
field count is pinned, so there is no compatibility window.

Protocol 1.3.0:
- CatalogAttachResult gains global_functions and global_function_prefix,
  positioned between supports_column_statistics and resolved_data_version.
  The record IS the schema here -- vgirpc derives it reflectively -- so the
  work was in the two producers in VgiServiceImpl: the main path and the
  extra-catalog short-circuit. Updating only one would have left
  MetaWorker-style auxiliary attaches broken.
- VGI_PROTOCOL_VERSION 1.2.0 -> 1.3.0, enforced as an exact major+minor
  match at the dispatch boundary and required independently of the schema.

Global-function probes: global_scalar, global_table, global_agg,
global_buffered -- one per function kind, mirroring vgi-python's
_test_fixtures/global_functions.py. Registered inside Main's existing
example-catalog block, so the versioned/versioned_tables wrappers do not
advertise functions they do not own under a prefix naming another catalog.
Closes the three duckdb_functions() inventory tests.

Advertisement is wired for real: Worker.registerGlobalFunctions /
globalFunctionPrefix, and VgiServiceImpl.globalFunctionInfos(). Verified by
decoding the payload with the independent vgi-python client -- 4 entries,
kinds scalar/table/aggregate/table_buffering, all schema_name=main, names
unprefixed, prefix carried separately -- and by querying duckdb_functions()
per catalog: present on example, absent from both wrappers, with a guard
that the wrappers still return a non-empty function set so the zeros are
real absences rather than a dead ATTACH.

The C++ consuming side is not written yet: duckdb_functions() matching
vgi_example_global% is still 0 after ATTACH.

Also bumps the vgirpc floor 0.17.0 -> 0.20.0 and the two workflow refs that
build vgirpc from source, which would otherwise have tested 0.17 source
against a 0.20.0 floor.

Integration: launch 289/3 -> 292/0, http 287/3 -> 290/0. gradlew test holds
at 271 / 0 failures / 2 skipped; javadoc unchanged at its 23 pre-existing
warnings.

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

Author: rustyconover

.github/workflows/integration.yml

@@ -36,7 +36,7 @@ env:
   # The vgi-rpc-java commit built from source (composite include) for the worker's
   # HTTP features. Drop once a vgirpc release with these features is published and
   # pinned in vgi/build.gradle.kts.
-  VGI_RPC_JAVA_REF: v0.17.0
+  VGI_RPC_JAVA_REF: v0.20.0
 
 jobs:
   integration:

.github/workflows/landing.yml

@@ -29,7 +29,7 @@ env:
   # vgi-rpc-java commit built from source (composite include) for the worker's
   # HTTP landing surface. Keep in sync with integration.yml's VGI_RPC_JAVA_REF;
   # drop once a vgirpc release with the landing surface is published and pinned.
-  VGI_RPC_JAVA_REF: v0.17.0
+  VGI_RPC_JAVA_REF: v0.20.0
 
 jobs:
   landing:

build.gradle.kts

@@ -8,7 +8,7 @@ plugins {
 
 allprojects {
     group = "farm.query"
-    version = "0.21.0"
+    version = "0.22.0"
 
     repositories {
         mavenCentral()

vgi-example-worker/src/main/java/farm/query/vgi/example/Main.java

@@ -67,6 +67,7 @@
 import farm.query.vgi.example.aggregate.AvgFunction;
 import farm.query.vgi.example.aggregate.CountFunction;
 import farm.query.vgi.example.aggregate.GenericSumFunction;
+import farm.query.vgi.example.aggregate.GlobalAggFunction;
 import farm.query.vgi.example.aggregate.ListAggFunction;
 import farm.query.vgi.example.aggregate.PercentileFunction;
 import farm.query.vgi.example.aggregate.SecretTypedSumFunction;
@@ -331,6 +332,7 @@ public static void main(String[] args) {
             // The accumulate catalog rides only the default fixture worker —
             // the versioned/versioned_tables wrappers reuse this binary and
             // their vgi_catalogs() output must stay single-row.
+            registerGlobalProbes(w);
             registerAccumulate(w);
             registerNarrowBind(w);
             registerTwinCatalogs(w);
@@ -1258,6 +1260,35 @@ private static void registerCopyTo(Worker w) {
                 new farm.query.vgi.example.copyto.SecretLinesCopyToFunction()));
     }
 
+    /**
+     * Global-registration probes: one fixture per function kind, registered in
+     * {@code main} like any other AND advertised on the {@code catalog_attach}
+     * result so the client publishes them into its global namespace as
+     * {@code vgi_example_global_*}. Dedicated classes rather than reused
+     * fixtures — this catalog is a cross-language contract, so making e.g.
+     * {@code double} globally published would force the same semantic change on
+     * every other SDK's copy of it. See {@code scalar/GlobalScalarFunction}.
+     *
+     * <p>Scoped to the {@code example} catalog, unlike the four kind lists this
+     * binary shares with the versioned / versioned_tables wrappers. The probes
+     * belong to the cross-language example contract (vgi-python declares them on
+     * that catalog alone, as do the Go / TypeScript / Rust ports), and
+     * {@code vgi_example} names it — a wrapper catalog advertising them under
+     * that prefix would be claiming functions it does not own.
+     */
+    private static void registerGlobalProbes(Worker w) {
+        var scalar = new farm.query.vgi.example.scalar.GlobalScalarFunction();
+        var table = new farm.query.vgi.example.table.GlobalTableFunction();
+        var agg = new GlobalAggFunction();
+        var buffered = new farm.query.vgi.example.buffering.GlobalBufferedFunction();
+        w.registerScalar(scalar)
+                .registerTable(table)
+                .registerAggregate(agg)
+                .registerTableBuffering(buffered)
+                .globalFunctionPrefix("vgi_example")
+                .registerGlobalFunctions(List.of(scalar, table, agg, buffered));
+    }
+
     private static void registerBuffering(Worker w) {
         w.registerTableBufferings(List.of(
                 new farm.query.vgi.example.buffering.BufferInputFunction(),

vgi-example-worker/src/main/java/farm/query/vgi/example/aggregate/GlobalAggFunction.java

@@ -0,0 +1,71 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.example.aggregate;
+
+import farm.query.vgi.aggregate.AggregateFunction;
+import farm.query.vgi.function.FunctionMetadata;
+import farm.query.vgi.function.FunctionSpec;
+import farm.query.vgi.types.Schemas;
+import org.apache.arrow.vector.BigIntVector;
+import org.apache.arrow.vector.FieldVector;
+import org.apache.arrow.vector.VectorSchemaRoot;
+import org.apache.arrow.vector.types.pojo.Schema;
+
+import java.io.Serializable;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * {@code global_agg(value: int64) -> int64} — the aggregate member of the
+ * global-registration probe family (see
+ * {@code farm.query.vgi.example.scalar.GlobalScalarFunction} for the family's
+ * rationale).
+ *
+ * <p>Sums its input per group; a group with no accumulated state finalizes to
+ * NULL (the framework's {@code finalizeEmpty} default). Mirrors vgi-python's
+ * {@code GlobalAggFunction}.
+ */
+public final class GlobalAggFunction implements AggregateFunction<GlobalAggFunction.State> {
+
+    /** Running total for one group. */
+    public static final class State implements Serializable {
+        private static final long serialVersionUID = 1L;
+        long total;
+    }
+
+    private static final Schema OUTPUT_SCHEMA = new Schema(List.of(
+            Schemas.nullable("result", Schemas.INT64)));
+
+    private static final FunctionSpec SPEC = FunctionSpec.builder("global_agg")
+            .metadata(FunctionMetadata.describe("Global-registration probe (aggregate)")
+                    .withCategories("test", "global"))
+            .arg("value", Schemas.INT64)
+            .build();
+
+    @Override public FunctionSpec spec() { return SPEC; }
+
+    @Override public Schema outputSchema() { return OUTPUT_SCHEMA; }
+
+    @Override public State newState() { return new State(); }
+
+    @Override
+    public void update(Map<Long, State> states, long[] groupIds, VectorSchemaRoot input) {
+        FieldVector v = input.getFieldVectors().get(0);
+        if (!(v instanceof BigIntVector b)) return;
+        int rows = input.getRowCount();
+        for (int i = 0; i < rows; i++) {
+            if (b.isNull(i)) continue;
+            states.computeIfAbsent(groupIds[i], k -> new State()).total += b.get(i);
+        }
+    }
+
+    @Override
+    public void combine(State target, State source) {
+        target.total += source.total;
+    }
+
+    @Override
+    public void finalize(FieldVector result, int rowIndex, State state) {
+        ((BigIntVector) result).setSafe(rowIndex, state.total);
+    }
+}

vgi-example-worker/src/main/java/farm/query/vgi/example/buffering/GlobalBufferedFunction.java

@@ -0,0 +1,32 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.example.buffering;
+
+import farm.query.vgi.function.FunctionMetadata;
+import farm.query.vgi.function.FunctionSpec;
+import farm.query.vgi.protocol.FunctionExample;
+
+import java.util.List;
+
+/**
+ * {@code global_buffered(data TABLE) -> *} — the table-buffering member of the
+ * global-registration probe family (see
+ * {@code farm.query.vgi.example.scalar.GlobalScalarFunction} for the family's
+ * rationale).
+ *
+ * <p>Buffers every input batch and replays them on finalize; the output schema
+ * is the input schema. Mirrors vgi-python's {@code GlobalBufferedFunction}.
+ */
+public final class GlobalBufferedFunction extends AbstractBufferAndDrain {
+
+    private static final FunctionSpec SPEC = FunctionSpec.builder("global_buffered")
+            .metadata(FunctionMetadata.describe("Global-registration probe (table-buffering)")
+                    .withCategories("test", "global")
+                    .withExamples(List.of(new FunctionExample(
+                            "SELECT * FROM vgi_example_global_buffered((SELECT 1 AS x))",
+                            "Buffering probe published into system.main", null))))
+            .table("data")
+            .build();
+
+    @Override public FunctionSpec spec() { return SPEC; }
+}

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

@@ -0,0 +1,63 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.example.scalar;
+
+import farm.query.vgi.function.FunctionMetadata;
+import farm.query.vgi.protocol.FunctionExample;
+import farm.query.vgi.scalar.ScalarFn;
+import farm.query.vgi.scalar.Vector;
+import org.apache.arrow.vector.BigIntVector;
+import org.apache.arrow.vector.VarCharVector;
+import org.apache.arrow.vector.util.Text;
+
+import java.util.List;
+
+/**
+ * {@code global_scalar(value: int64) -> utf8} — the scalar member of the
+ * global-registration probe family (the others are
+ * {@code table/GlobalTableFunction}, {@code aggregate/GlobalAggFunction} and
+ * {@code buffering/GlobalBufferedFunction}).
+ *
+ * <p>One probe per function kind, so a client publishing a worker's functions
+ * into its <em>global</em> namespace exercises every registration path. They are
+ * deliberately new rather than reused fixtures: the example catalog is a
+ * cross-language contract, and reusing {@code double} / {@code ten_thousand} /
+ * {@code vgi_sum} / {@code echo_buffering} would force the same semantic change
+ * on every SDK's existing functions.
+ *
+ * <p>Each returns a value tagged with its own name, so a test can prove the
+ * globally published name reached the function it was supposed to rather than a
+ * same-named function belonging to another catalog. Mirrors vgi-python's
+ * {@code _test_fixtures/global_functions.py}.
+ */
+public final class GlobalScalarFunction extends ScalarFn {
+
+    @Override public String name() { return "global_scalar"; }
+
+    @Override public String description() { return "Global-registration probe (scalar)"; }
+
+    @Override public FunctionMetadata metadata() {
+        return FunctionMetadata.describe(description())
+                .withCategories("test", "global")
+                .withExamples(List.of(new FunctionExample(
+                        "SELECT vgi_example_global_scalar(7)",
+                        "Scalar probe published into system.main", null)));
+    }
+
+    /**
+     * Labels each row {@code global_scalar:<value>}; NULL in, NULL out.
+     *
+     * @param value the values to label
+     * @param result framework-allocated output column
+     */
+    public void compute(@Vector BigIntVector value, VarCharVector result) {
+        int rows = value.getValueCount();
+        for (int i = 0; i < rows; i++) {
+            if (value.isNull(i)) {
+                result.setNull(i);
+                continue;
+            }
+            result.setSafe(i, new Text("global_scalar:" + value.get(i)));
+        }
+    }
+}

vgi-example-worker/src/main/java/farm/query/vgi/example/table/GlobalTableFunction.java

@@ -0,0 +1,83 @@
+// Copyright 2026 Query Farm LLC - https://query.farm
+
+package farm.query.vgi.example.table;
+
+import farm.query.vgi.function.FunctionMetadata;
+import farm.query.vgi.function.FunctionSpec;
+import farm.query.vgi.internal.BatchUtil;
+import farm.query.vgi.protocol.FunctionExample;
+import farm.query.vgi.table.SimpleTableFunction;
+import farm.query.vgi.table.TableBindParams;
+import farm.query.vgi.table.TableInitParams;
+import farm.query.vgi.table.TableProducerState;
+import farm.query.vgi.types.Schemas;
+import farm.query.vgirpc.CallContext;
+import farm.query.vgirpc.OutputCollector;
+import org.apache.arrow.vector.BigIntVector;
+import org.apache.arrow.vector.VarCharVector;
+import org.apache.arrow.vector.types.pojo.Schema;
+import org.apache.arrow.vector.util.Text;
+
+import java.util.List;
+
+/**
+ * {@code global_table() -> (n int64, label utf8)} — the table member of the
+ * global-registration probe family (see {@code scalar/GlobalScalarFunction} for
+ * the family's rationale).
+ *
+ * <p>A fixed generator taking no arguments: three labelled rows, emitted once.
+ * Mirrors vgi-python's {@code GlobalTableFunction}.
+ */
+public final class GlobalTableFunction extends SimpleTableFunction {
+
+    private static final Schema OUTPUT = Schemas.of(
+            Schemas.nullable("n", Schemas.INT64),
+            Schemas.nullable("label", Schemas.UTF8));
+
+    /** Exactly three rows, always. */
+    private static final long ROWS = 3L;
+
+    private static final FunctionSpec SPEC = FunctionSpec.builder("global_table")
+            .metadata(FunctionMetadata.describe("Global-registration probe (table)")
+                    .withCategories("test", "global")
+                    .withExamples(List.of(new FunctionExample(
+                            "SELECT * FROM vgi_example_global_table()",
+                            "Table probe published into system.main", null))))
+            .build();
+
+    @Override public FunctionSpec spec() { return SPEC; }
+
+    @Override protected Schema outputSchema() { return OUTPUT; }
+
+    @Override public long cardinality(TableBindParams params) { return ROWS; }
+
+    @Override public TableProducerState createProducer(TableInitParams params) {
+        return new State();
+    }
+
+    /** One-shot emit latch for the three probe rows. */
+    public static final class State extends TableProducerState {
+
+        /** Whether the single batch has been emitted. */
+        public boolean emitted;
+
+        /** Required no-arg constructor for state deserialization. */
+        public State() {}
+
+        @Override public void produceTick(OutputCollector out, CallContext ctx) {
+            if (emitted) {
+                out.finish();
+                return;
+            }
+            emitted = true;
+            BatchUtil.emit(OUTPUT, (int) ROWS, out, (root, rows, ignored) -> {
+                BigIntVector n = (BigIntVector) root.getVector("n");
+                VarCharVector label = (VarCharVector) root.getVector("label");
+                for (int i = 0; i < rows; i++) {
+                    n.setSafe(i, i);
+                    label.setSafe(i, new Text("global_table:" + i));
+                }
+            });
+        }
+    }
+}

vgi/build.gradle.kts

@@ -5,7 +5,7 @@ plugins {
 
 dependencies {
     // farm.query is the published group (see ../build.gradle.kts allprojects).
-    api("farm.query:vgirpc:0.17.0")
+    api("farm.query:vgirpc:0.20.0")
     implementation("org.slf4j:slf4j-api:2.0.16")
     // Cross-process aggregate state store. DuckDB spawns multiple worker
     // subprocesses for parallel aggregation; SQLite's file locking gives us