fix: ChunkedArrayCombiner.combineLists handles all-null NullArray chunks

An entirely-null chunk decodes to a NullArray rather than a typed array
(vortex.null flat, or vortex.constant with a null scalar). The sibling
#269 fix taught VarBinArray.ChunkedMode.of to materialize such a chunk as
an all-null run, but combineLists never got the equivalent treatment: it
hit its else branch and threw "chunk is not a ListArray: NullArray".

Treat a NullArray list chunk as n zero-length list rows: it contributes no
elements (skipped by the recursive element combine) and its outer offsets
repeat the running element count. Row-level nullability stays out-of-band
via the caller's validity bitmap / MaskedArray wrapping, same convention as
VarBinArray.allNull. An all-null column (every chunk a NullArray) yields a
zero-length elements placeholder since the elements array is never indexed.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: dfa1

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - A chunked `List` column spanning several flat chunks now decodes into a single stitched array instead of throwing a raw `ClassCastException`; any other unhandled dtype now fails with `VortexException`. ([#268](https://github.com/dfa1/vortex-java/issues/268))
 - A chunked `Utf8`/`Binary` column with an entirely-null chunk (`NullArray`) no longer throws `chunk is not a VarBinArray`; the chunk materializes as an all-null run. ([#269](https://github.com/dfa1/vortex-java/issues/269))
+- A chunked `List` column with an entirely-null chunk (`NullArray`) no longer throws `chunk is not a ListArray`; the chunk's rows become zero-length lists with out-of-band nulls. ([#269](https://github.com/dfa1/vortex-java/issues/269))
 - Nullable low-cardinality columns now share one global dictionary across chunks instead of re-emitting a per-chunk dictionary. ([5fe8b544](https://github.com/dfa1/vortex-java/commit/5fe8b544))
 - `MaskedEncodingEncoder` encodes an all-valid or all-invalid validity bitmap as `vortex.constant` instead of a raw per-row bitmap. ([ecd47ead](https://github.com/dfa1/vortex-java/commit/ecd47ead))
 - `MaskedEncodingEncoder` tries `vortex.sparse` for a mixed-validity bitmap and keeps it over the raw bitmap when smaller. ([506d036f](https://github.com/dfa1/vortex-java/commit/506d036f))

reader/src/main/java/io/github/dfa1/vortex/reader/array/ChunkedArrayCombiner.java

@@ -75,52 +75,76 @@ private static Array combinePrimitive(PType ptype, DType dtype, long totalRows,
     /// number of elements contributed by earlier chunks, since per-chunk offsets each restart at
     /// zero.
     ///
+    /// An entirely-null chunk decodes to a [NullArray] rather than a [ListArray] (e.g. a
+    /// `vortex.null` flat, or `vortex.constant` with a null scalar, #269). Mirroring the sibling
+    /// [VarBinArray.ChunkedMode] fix, such a chunk contributes `n` zero-length list rows: it adds no
+    /// elements, so it is skipped by the recursive element combine, and its `n` outer offsets simply
+    /// repeat the running element count. Row-level nullability is preserved separately by the
+    /// caller's validity bitmap.
+    ///
     /// @param dtype     the list's logical type
     /// @param totalRows the total outer-list row count across all chunks
-    /// @param chunks    the per-chunk list arrays (each a [ListArray], possibly wrapped [MaskedArray])
+    /// @param chunks    the per-chunk arrays (each a [ListArray] or [NullArray], possibly wrapped
+    ///                  [MaskedArray])
     /// @param arena     allocator for the rebuilt offsets segment
     /// @return a single [ListArray] over the combined chunks
+    /// @throws VortexException on a chunk that is neither a [ListArray] nor a [NullArray], or a
+    ///                         row-count mismatch
     private static ListArray combineLists(DType.List dtype, long totalRows, List<Array> chunks,
             SegmentAllocator arena) {
-        var listChunks = new ArrayList<ListArray>(chunks.size());
+        // A ListArray keeps its offsets/elements; a NullArray keeps only its row count (its outer
+        // rows are all zero-length lists, contributing no elements).
+        var listChunks = new ArrayList<Array>(chunks.size());
+        long outerRows = 0;
         for (Array chunk : chunks) {
             Array unwrapped = chunk instanceof MaskedArray m ? m.inner() : chunk;
-            if (unwrapped instanceof ListArray la) {
-                listChunks.add(la);
+            if (unwrapped instanceof ListArray || unwrapped instanceof NullArray) {
+                listChunks.add(unwrapped);
+                outerRows += unwrapped.length();
             } else {
                 throw new VortexException("chunked list: chunk is not a ListArray: "
                         + unwrapped.getClass().getSimpleName());
             }
         }
-        long outerRows = 0;
-        for (ListArray la : listChunks) {
-            outerRows += la.length();
-        }
         if (outerRows != totalRows) {
             throw new VortexException("chunked list: chunk rows sum to " + outerRows
                     + ", expected " + totalRows);
         }
 
         var elementChunks = new ArrayList<Array>(listChunks.size());
-        for (ListArray la : listChunks) {
-            elementChunks.add(la.elements());
+        for (Array chunk : listChunks) {
+            if (chunk instanceof ListArray la) {
+                elementChunks.add(la.elements());
+            }
         }
-        Array combinedElements = combine(dtype.elementType(), sumLengths(elementChunks),
-                elementChunks, arena);
+        // Every chunk all-null: no chunk contributes elements. All offsets are zero, so the
+        // elements array is never indexed; a zero-length placeholder of the element dtype suffices
+        // (combine() rejects an empty chunk list, so it cannot be called here).
+        Array combinedElements = elementChunks.isEmpty()
+                ? new NullArray(dtype.elementType(), 0)
+                : combine(dtype.elementType(), sumLengths(elementChunks), elementChunks, arena);
 
         MemorySegment offsets = arena.allocate((totalRows + 1) * Long.BYTES, Long.BYTES);
         offsets.setAtIndex(VortexFormat.LE_LONG, 0, 0L);
         long outRow = 0;
         long elementBase = 0;
-        for (ListArray la : listChunks) {
-            long localRows = la.length();
-            Array localOffsets = la.offsets();
-            for (long i = 0; i < localRows; i++) {
-                long localEnd = readOffset(localOffsets, i + 1);
-                offsets.setAtIndex(VortexFormat.LE_LONG, outRow + i + 1, elementBase + localEnd);
+        for (Array chunk : listChunks) {
+            long localRows = chunk.length();
+            if (chunk instanceof ListArray la) {
+                Array localOffsets = la.offsets();
+                for (long i = 0; i < localRows; i++) {
+                    long localEnd = readOffset(localOffsets, i + 1);
+                    offsets.setAtIndex(VortexFormat.LE_LONG, outRow + i + 1, elementBase + localEnd);
+                }
+                elementBase += readOffset(localOffsets, localRows);
+            } else {
+                // All-null chunk: every one of its rows is a zero-length list, so the offset never
+                // advances past the running element base.
+                for (long i = 0; i < localRows; i++) {
+                    offsets.setAtIndex(VortexFormat.LE_LONG, outRow + i + 1, elementBase);
+                }
             }
             outRow += localRows;
-            elementBase += readOffset(localOffsets, localRows);
         }
         Array offsetsArray = new MaterializedLongArray(DType.I64, totalRows + 1, offsets.asReadOnly());
         return new ListArray(dtype, totalRows, combinedElements, offsetsArray);

reader/src/test/java/io/github/dfa1/vortex/reader/array/ChunkedArrayCombinerTest.java

@@ -74,6 +74,48 @@ void nullableListChunksKeepTheirNulls() {
         }
     }
 
+    @Test
+    void allNullNullArrayChunkCombinesAsZeroLengthLists() {
+        // Given — a chunked list<int> column whose middle chunk decoded to a bare NullArray, not a
+        // ListArray (a vortex.null flat or vortex.constant null-scalar chunk, #269). Before the fix
+        // combineLists hit its else branch and threw "chunk is not a ListArray: NullArray"; the
+        // #269-parity fix must treat those rows as zero-length lists carrying out-of-band nulls.
+        ListArray chunk0 = new ListArray(LIST_OF_INT, 2, ints(10, 11, 12), longs(0L, 2L, 3L));
+        NullArray chunk1 = new NullArray(LIST_OF_INT, 2);
+        ListArray chunk2 = new ListArray(LIST_OF_INT, 1, ints(20, 21), longs(0L, 2L));
+
+        // When
+        try (Arena arena = Arena.ofConfined()) {
+            Array result = ChunkedArrayCombiner.combine(LIST_OF_INT, 5,
+                    List.of(chunk0, chunk1, chunk2), arena);
+
+            // Then — a NullArray chunk makes the whole column nullable, so the combiner wraps the
+            // stitched ListArray in a MaskedArray marking the null chunk's rows invalid while the
+            // real chunks' rows stay valid and their elements/offsets stay intact.
+            assertThat(result).isInstanceOf(MaskedArray.class);
+            MaskedArray masked = (MaskedArray) result;
+            assertThat(masked.inner()).isInstanceOf(ListArray.class);
+            assertThat(masked.isValid(0)).isTrue();
+            assertThat(masked.isValid(1)).isTrue();
+            assertThat(masked.isValid(2)).isFalse();
+            assertThat(masked.isValid(3)).isFalse();
+            assertThat(masked.isValid(4)).isTrue();
+
+            ListArray list = (ListArray) masked.inner();
+            assertThat(list.length()).isEqualTo(5);
+            LongArray offsets = (LongArray) list.offsets();
+            // Rows 0-1 span [0,2) and [2,3); the null rows 2-3 are zero-length (offset stays at 3);
+            // row 4 (chunk2) contributes 2 elements, shifted past chunk0's 3 to span [3,5).
+            assertThat(readAll(offsets, 6)).containsExactly(0L, 2L, 3L, 3L, 3L, 5L);
+
+            IntArray elements = (IntArray) list.elements();
+            assertThat(elements.length()).isEqualTo(5);
+            assertThat(elements.getInt(0)).isEqualTo(10);
+            assertThat(elements.getInt(3)).isEqualTo(20);
+            assertThat(elements.getInt(4)).isEqualTo(21);
+        }
+    }
+
     @Test
     void emptyChunkListThrowsVortexException() {
         // Given / When / Then