fix: validate row arity in MetadataResultSets.of

Previously a row with the wrong number of elements would silently leave
the trailing columns as Arrow null (interpreted as missing values).
Today every caller routes through MetadataSchemas so the sizes match by
construction, but a future caller bug would surface only inside vector
population, far from the boundary.

Add an explicit arity check at the of(...) entrypoint: each non-null
row must have exactly columns.size() elements. Null rows are accepted
as the all-nulls row (matching the legacy coerceRows convention of
turning null into emptyList). Empty rows are accepted only when the
schema is also empty.

Pin behavior with MetadataResultSetsTest covering short, long,
correct-arity, null-row, and empty-rows cases.

Author: mkaufmann

jdbc-core/src/main/java/com/salesforce/datacloud/jdbc/core/metadata/MetadataResultSets.java

@@ -50,9 +50,14 @@ public static StreamingResultSet emptyNoColumns() throws SQLException {
 
     /**
      * Build a result set whose schema is {@code columns} and whose rows are {@code rows}. Each
-     * inner list in {@code rows} supplies values in column order.
+     * inner list in {@code rows} supplies values in column order, and must have exactly
+     * {@code columns.size()} elements — a short row would silently leave the trailing columns
+     * unset (interpreted as Arrow null), which is almost always a caller bug. Today every caller
+     * goes through {@link MetadataSchemas} so the sizes match by construction; the precondition
+     * here makes a future caller bug surface at the boundary instead of in vector population.
      */
     public static StreamingResultSet of(List<ColumnMetadata> columns, List<List<Object>> rows) throws SQLException {
+        validateRowArity(columns, rows);
         byte[] ipcBytes = writeArrowStream(columns, rows);
         // Allocator is handed to StreamingResultSet along with the reader; the result set owns
         // its lifecycle and closes it when close() is called.
@@ -105,6 +110,31 @@ private static byte[] writeArrowStream(List<ColumnMetadata> columns, List<List<O
         }
     }
 
+    /**
+     * Verify that every supplied row has exactly {@code columns.size()} elements. A {@code null}
+     * row is allowed and is interpreted as a row of all-nulls (matching the old
+     * {@code coerceRows} convention of converting null rows to empty lists, which is the only
+     * shape with no positional values to populate). Anything else is a caller bug.
+     */
+    private static void validateRowArity(List<ColumnMetadata> columns, List<List<Object>> rows) throws SQLException {
+        int expected = columns.size();
+        for (int i = 0; i < rows.size(); i++) {
+            List<Object> row = rows.get(i);
+            if (row == null) {
+                continue;
+            }
+            // The legacy coerceRows path turns a null-row into Collections.emptyList(); accept
+            // empty as the "all nulls" shape here too.
+            if (row.isEmpty() && expected > 0) {
+                continue;
+            }
+            if (row.size() != expected) {
+                throw new SQLException("Metadata row " + i + " has " + row.size() + " elements but schema has "
+                        + expected + " columns");
+            }
+        }
+    }
+
     @SuppressWarnings("unchecked")
     private static List<List<Object>> coerceRows(List<Object> rawRows) throws SQLException {
         if (rawRows == null || rawRows.isEmpty()) {

jdbc-core/src/test/java/com/salesforce/datacloud/jdbc/core/metadata/MetadataResultSetsTest.java

@@ -0,0 +1,77 @@
+/**
+ * This file is part of https://github.com/forcedotcom/datacloud-jdbc which is released under the
+ * Apache 2.0 license. See https://github.com/forcedotcom/datacloud-jdbc/blob/main/LICENSE.txt
+ */
+package com.salesforce.datacloud.jdbc.core.metadata;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+import com.salesforce.datacloud.jdbc.protocol.data.ColumnMetadata;
+import com.salesforce.datacloud.jdbc.protocol.data.HyperType;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.List;
+import lombok.val;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Pin the {@link MetadataResultSets#of(List, List)} arity contract: rows must match the schema
+ * column count, otherwise a short row would silently produce trailing Arrow-null cells (almost
+ * always a caller bug). A {@code null} row is allowed and is interpreted as an all-nulls row,
+ * matching the legacy {@code coerceRows} convention.
+ */
+class MetadataResultSetsTest {
+
+    private static final List<ColumnMetadata> THREE_COLUMNS = Arrays.asList(
+            new ColumnMetadata("a", HyperType.varcharUnlimited(true)),
+            new ColumnMetadata("b", HyperType.int32(true)),
+            new ColumnMetadata("c", HyperType.bool(true)));
+
+    @Test
+    void shortRowRejected() {
+        val rows = Collections.singletonList(Arrays.<Object>asList("only-one"));
+        assertThatThrownBy(() -> MetadataResultSets.of(THREE_COLUMNS, rows))
+                .hasMessageContaining("3 columns")
+                .hasMessageContaining("1 elements");
+    }
+
+    @Test
+    void longRowRejected() {
+        val rows = Collections.singletonList(Arrays.<Object>asList("a", 1, true, "extra"));
+        assertThatThrownBy(() -> MetadataResultSets.of(THREE_COLUMNS, rows))
+                .hasMessageContaining("3 columns")
+                .hasMessageContaining("4 elements");
+    }
+
+    @Test
+    void rightArityAccepted() throws Exception {
+        val rows = Collections.singletonList(Arrays.<Object>asList("a", 1, true));
+        try (val rs = MetadataResultSets.of(THREE_COLUMNS, rows)) {
+            assertThat(rs.next()).isTrue();
+            assertThat(rs.getString(1)).isEqualTo("a");
+            assertThat(rs.getInt(2)).isEqualTo(1);
+            assertThat(rs.getBoolean(3)).isTrue();
+        }
+    }
+
+    @Test
+    void nullRowAcceptedAsAllNulls() throws Exception {
+        val rows = Collections.<List<Object>>singletonList(null);
+        try (val rs = MetadataResultSets.of(THREE_COLUMNS, rows)) {
+            assertThat(rs.next()).isTrue();
+            assertThat(rs.getString(1)).isNull();
+            rs.getInt(2);
+            assertThat(rs.wasNull()).isTrue();
+            rs.getBoolean(3);
+            assertThat(rs.wasNull()).isTrue();
+        }
+    }
+
+    @Test
+    void emptyRowsAccepted() throws Exception {
+        try (val rs = MetadataResultSets.of(THREE_COLUMNS, Collections.emptyList())) {
+            assertThat(rs.next()).isFalse();
+        }
+    }
+}