feat(writer): accept boxed nullable arrays on the map writeChunk path

The map entry point writeChunk(Map) only accepted raw primitive arrays, so a
nullable column had to be supplied via the builder (writeChunk(c -> c.put(...,
new Long[]{...}))). Passing a boxed Long[]/Integer[]/… through the map threw
"unsupported data type". The two entry points now share ChunkImpl.validateAndAdapt:

- writeChunk(Map) adapts every column up front (boxed nullable array → NullableData,
  raw arrays pass through) before the row-count check and encoding, so the map form
  routes nullable columns through MaskedEncoding exactly like the builder.
- validateAndAdapt is now package-private and idempotent: an already-adapted
  NullableData passes through, since the builder pre-adapts before delegating to
  writeChunk(Map) (would otherwise double-adapt and reject NullableData).

Tests: VortexWriterTest gains map-path accept (boxed Long[] with null) + reject
(boxed on non-nullable) cases; the integration masked round-trip now drives the
map form, verifying null preservation end-to-end through the JNI reader.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

integration/src/test/java/io/github/dfa1/vortex/integration/JavaWritesRustReadsIntegrationTest.java

@@ -1031,8 +1031,8 @@ void javaWriter_rustReader_masked_nullableI64(@TempDir Path tmp) throws IOExcept
         Long[] data = {10L, null, 30L, null, 50L, 60L};
         try (var ch = FileChannel.open(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
              var sut = VortexWriter.create(ch, schema, WriteOptions.defaults())) {
-            // When — boxed Long[] via the builder routes through the nullable → masked path
-            sut.writeChunk(c -> c.put("v", data));
+            // When — boxed Long[] via the map entry point routes through the nullable → masked path
+            sut.writeChunk(Map.of("v", data));
         }
 
         // Then — Rust reads a nullable BigInt vector; null positions survive, values round-trip

writer/src/main/java/io/github/dfa1/vortex/writer/ChunkImpl.java

@@ -42,10 +42,25 @@ Map<String, Object> finish() {
         return data;
     }
 
-    private static Object validateAndAdapt(String column, DType dtype, Object value) {
+    /// Validates a column's raw data against its schema dtype and adapts boxed nullable arrays
+    /// (`Long[]`, `Integer[]`, `Boolean[]`, …) into the internal [NullableData] carrier. Shared by
+    /// the builder ([#put]) and the map-based [VortexWriter#writeChunk(Map)] entry points so both
+    /// accept the same shapes.
+    ///
+    /// @param column the column name, for error messages
+    /// @param dtype  the column's declared schema type
+    /// @param value  the raw column data
+    /// @return the adapted data: the original array for non-nullable primitives, a [NullableData]
+    ///         for boxed nullable arrays, or `value` unchanged for non-primitive carriers
+    static Object validateAndAdapt(String column, DType dtype, Object value) {
         if (value == null) {
             throw new IllegalArgumentException("null array for column: " + column);
         }
+        // Idempotent: an already-adapted NullableData (e.g. from the builder, which adapts before
+        // delegating to VortexWriter.writeChunk(Map)) passes through so a second call is a no-op.
+        if (value instanceof NullableData) {
+            return value;
+        }
         return switch (dtype) {
             case DType.Primitive p -> adaptPrimitive(column, p, value);
             case DType.Utf8 u -> adaptUtf8(column, u, value);

writer/src/main/java/io/github/dfa1/vortex/writer/VortexWriter.java

@@ -369,11 +369,29 @@ public void writeChunk(java.util.function.Consumer<Chunk> builder) throws IOExce
 
     /// Write one chunk. Each column is encoded by the first registered encoder that accepts its dtype.
     ///
+    /// A nullable column may be supplied as a boxed array (`Long[]`, `Integer[]`, `Double[]`,
+    /// `Boolean[]`, …) with `null` marking absent rows; it routes through `MaskedEncoding` just like
+    /// the builder form. Non-nullable columns take the raw primitive array (`long[]`, `int[]`, …).
+    ///
     /// @param columns map from column name to typed array data
     /// @throws IOException              if an I/O error occurs writing to the underlying channel
     /// @throws IllegalArgumentException if a schema column is missing from `columns`,
     ///         or if column arrays disagree on row count
     public void writeChunk(Map<String, Object> columns) throws IOException {
+        // Adapt each column up front so the map entry point accepts the same shapes as the
+        // builder: boxed nullable arrays (Long[], Integer[], Boolean[], …) become NullableData,
+        // raw primitive arrays pass through. Done before the row-count check so length validation
+        // and encoding both see the normalized carrier.
+        Map<String, Object> adapted = new LinkedHashMap<>();
+        for (int i = 0; i < schema.fieldNames().size(); i++) {
+            String colName = schema.fieldNames().get(i);
+            Object data = columns.get(colName);
+            if (data == null) {
+                throw new IllegalArgumentException("missing column: " + colName);
+            }
+            adapted.put(colName, ChunkImpl.validateAndAdapt(colName, schema.fieldTypes().get(i), data));
+        }
+
         // Pre-validate row counts so a length mismatch is rejected with a clear error
         // before any data is serialised. Without this check, the writer would produce a
         // file whose column chunks claim different row counts — readable but logically
@@ -382,11 +400,7 @@ public void writeChunk(Map<String, Object> columns) throws IOException {
         String expectedFrom = null;
         for (int i = 0; i < schema.fieldNames().size(); i++) {
             String colName = schema.fieldNames().get(i);
-            Object data = columns.get(colName);
-            if (data == null) {
-                throw new IllegalArgumentException("missing column: " + colName);
-            }
-            long len = rowCountForValidation(colName, columns.get(colName));
+            long len = rowCountForValidation(colName, adapted.get(colName));
             if (expectedLen < 0) {
                 expectedLen = len;
                 expectedFrom = colName;
@@ -400,7 +414,7 @@ public void writeChunk(Map<String, Object> columns) throws IOException {
         for (int i = 0; i < schema.fieldNames().size(); i++) {
             String colName = schema.fieldNames().get(i);
             DType colDtype = schema.fieldTypes().get(i);
-            Object data = columns.get(colName);
+            Object data = adapted.get(colName);
 
             // Auto-route extension columns: callers can pass List<LocalDate>, List<Instant>,
             // etc., and we route through the matching spec extension to produce the int[] /

writer/src/test/java/io/github/dfa1/vortex/writer/VortexWriterTest.java

@@ -12,6 +12,7 @@
 
 import java.io.IOException;
 import java.nio.channels.FileChannel;
+import java.nio.file.Files;
 import java.nio.file.Path;
 import java.nio.file.StandardOpenOption;
 import java.util.ArrayList;
@@ -85,6 +86,42 @@ void writeChunk_autoroutesExtensionCollectionViaSpecExtension(@TempDir Path tmp)
         }
     }
 
+    @Test
+    void writeChunk_map_nullablePrimitive_acceptsBoxedArray(@TempDir Path tmp) throws IOException {
+        // Given — nullable I64 column passed to the MAP entry point as a boxed Long[] with a null.
+        // Regression: the map path used to reject boxed arrays ("unsupported data type: Long[]");
+        // only the builder accepted them. Both now share ChunkImpl.validateAndAdapt, so the map
+        // form routes the column through nullable → MaskedEncoding. The null round-trip itself is
+        // asserted end-to-end (through the JNI reader) by the integration masked test.
+        var schema = new DType.Struct(List.of("v"),
+                List.of(new DType.Primitive(PType.I64, true)), false);
+        Path file = tmp.resolve("nullable_map.vtx");
+
+        // When
+        try (var ch = FileChannel.open(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
+             var sut = VortexWriter.create(ch, schema, WriteOptions.defaults())) {
+            sut.writeChunk(Map.of("v", new Long[]{10L, null, 30L}));
+        }
+
+        // Then — the masked file is well-formed
+        assertThat(Files.size(file)).isPositive();
+    }
+
+    @Test
+    void writeChunk_map_nonNullablePrimitive_rejectsBoxedArray(@TempDir Path tmp) throws IOException {
+        // Given — a non-nullable I64 column rejects a boxed array on the map path, same as the
+        // builder: boxed implies nullability, which the schema does not allow.
+        Path file = tmp.resolve("err.vtx");
+        try (var ch = FileChannel.open(file, StandardOpenOption.CREATE, StandardOpenOption.WRITE);
+             var sut = VortexWriter.create(ch, SCHEMA, WriteOptions.defaults())) {
+            // When / Then
+            assertThatThrownBy(() -> sut.writeChunk(Map.of("id", new Long[]{1L, 2L})))
+                    .isInstanceOf(IllegalArgumentException.class)
+                    .hasMessageContaining("non-nullable")
+                    .hasMessageContaining("id");
+        }
+    }
+
     @Test
     void writeChunk_roundTripsTimeExtension(@TempDir Path tmp) throws IOException {
         // Given — milliseconds resolution exercises the I32 storage branch of