feat(reader): lazy VarBinView decode via VarBinArray.ViewMode

Add ViewMode as a fourth sealed implementation of VarBinArray, alongside
OffsetMode, DictMode, and ChunkedMode. ViewMode holds the 16-byte-per-row
views buffer plus zero or more shared data buffers and resolves accessors
on demand:

  getBytes(i): inline-or-referenced view, byte[]-copy from views or dataBufs
  getString(i): UTF-8 over getBytes
  getByteLength(i): u32 size from the view header (no data read)
  forEachByteLength: iterate view sizes only (no string copies)
  truncate(rows): views.asSlice(0, rows*16); dataBufs unchanged

VarBinViewEncodingDecoder.decode now returns the lazy ViewMode directly
instead of walking views, allocating outBytes + outOffsets, and copying
every row into the flat OffsetMode shape.

Three other decoders treat the values child as VarBinArray.OffsetMode
and casted directly — DictEncodingDecoder.decodeUtf8DictProto for the
dict-values table, SparseEncodingDecoder.decodeVarBin for the per-patch
values list, and RunEndEncodingDecoder for Utf8/Binary run values. Add
a centralised VarBinArray.toOffsetMode(VarBinArray, SegmentAllocator)
that returns the input unchanged when it is already OffsetMode and
materialises any other shape (ViewMode) into a flat OffsetMode on the
fly. The cost is identical to the previous eager-VarBinView path; it
just shifts from "always materialise at scan output" to "materialise
only when a parent decoder demands the bytes-plus-offsets shape." Same
shape can pick up ChunkedMode / DictMode if those ever land as a child.

ScanIterator's expandDictStrings fallback path uses the same helper.

6 new unit tests in VarBinViewModeTest cover inline accessor, referenced
accessor, mixed inline+referenced, forEachByteLength, truncate prefix,
and the truncate-beyond-length identity. ./mvnw verify green (13
modules, integration suite 45s).

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

Author: dfa1

reader/src/main/java/io/github/dfa1/vortex/reader/ScanIterator.java

@@ -603,7 +603,8 @@ private Array decodeDictLayout(Layout dictLayout, DType dtype, SegmentAllocator
             throw new VortexException(EncodingId.VORTEX_DICT,
                     "dict codes: layout row_count=" + n + " exceeds buffer capacity=" + bufferCodesFallback);
         }
-        return expandDictStrings((VarBinArray.OffsetMode) values, codesSegFallback, codesPType, dtype, n, arena);
+        return expandDictStrings(VarBinArray.toOffsetMode((VarBinArray) values, arena),
+                codesSegFallback, codesPType, dtype, n, arena);
     }
 
     /// Lazy-path zip-bomb guard. Inspects {@code codes}'s primary segment when available

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

@@ -6,19 +6,21 @@
 import io.github.dfa1.vortex.encoding.PTypeIO;
 
 import java.lang.foreign.MemorySegment;
+import java.lang.foreign.SegmentAllocator;
 import java.lang.foreign.ValueLayout;
 import java.nio.charset.StandardCharsets;
 import java.util.function.IntConsumer;
 
 /// Sealed interface for variable-length binary / UTF-8 string columns.
 ///
-/// Three implementations: {@link OffsetMode} for standard offset-based layout,
-/// {@link DictMode} for dictionary-encoded strings, and {@link ChunkedMode} for
-/// multi-chunk columns. All accessors resolve transparently regardless of mode;
-/// only {@link OffsetMode} exposes {@link OffsetMode#offsetsSegment()} and
-/// {@link OffsetMode#offsetsPtype()}.
+/// Four implementations: {@link OffsetMode} for standard offset-based layout,
+/// {@link DictMode} for dictionary-encoded strings, {@link ChunkedMode} for
+/// multi-chunk columns, and {@link ViewMode} for Arrow StringView / BinaryView
+/// layout (16-byte view per row + zero or more shared data buffers). All
+/// accessors resolve transparently regardless of mode; only {@link OffsetMode}
+/// exposes {@link OffsetMode#offsetsSegment()} and {@link OffsetMode#offsetsPtype()}.
 public sealed interface VarBinArray extends Array
-        permits VarBinArray.OffsetMode, VarBinArray.DictMode, VarBinArray.ChunkedMode {
+        permits VarBinArray.OffsetMode, VarBinArray.DictMode, VarBinArray.ChunkedMode, VarBinArray.ViewMode {
 
     /// Returns the concatenated raw bytes segment backing all elements.
     ///
@@ -54,6 +56,38 @@ public sealed interface VarBinArray extends Array
     /// @return a {@code VarBinArray} containing the first {@code rows} elements
     VarBinArray truncate(long rows);
 
+    /// Materialises any {@code VarBinArray} into a flat {@link OffsetMode}. The fast path
+    /// returns {@code src} unchanged when it is already an {@link OffsetMode}. Other modes
+    /// (ViewMode in particular) walk every row through the typed accessors, copy the bytes
+    /// into a fresh contiguous segment allocated from {@code arena}, and build an I64
+    /// offsets table. Used by parent decoders (dict, sparse, runend) whose downstream code
+    /// depends on the bytes-plus-offsets shape.
+    ///
+    /// @param src   any VarBinArray
+    /// @param arena allocator for the materialised bytes and offsets segments
+    /// @return an OffsetMode view over the same logical content
+    static OffsetMode toOffsetMode(VarBinArray src, SegmentAllocator arena) {
+        if (src instanceof OffsetMode om) {
+            return om;
+        }
+        long n = src.length();
+        long totalBytes = 0;
+        for (long i = 0; i < n; i++) {
+            totalBytes += src.getByteLength(i);
+        }
+        MemorySegment outBytes = arena.allocate(totalBytes > 0 ? totalBytes : 1);
+        MemorySegment outOffsets = arena.allocate((n + 1) * Long.BYTES, Long.BYTES);
+        outOffsets.setAtIndex(PTypeIO.LE_LONG, 0, 0L);
+        long bytePos = 0;
+        for (long i = 0; i < n; i++) {
+            byte[] b = src.getBytes(i);
+            MemorySegment.copy(MemorySegment.ofArray(b), 0, outBytes, bytePos, b.length);
+            bytePos += b.length;
+            outOffsets.setAtIndex(PTypeIO.LE_LONG, i + 1, bytePos);
+        }
+        return new OffsetMode(src.dtype(), n, outBytes.asReadOnly(), outOffsets, PType.I64);
+    }
+
     /// Creates a dict-mode {@code VarBinArray}. Lengths and bytes are resolved via the
     /// dictionary on each access; no string materialization occurs at construction time.
     ///
@@ -332,4 +366,75 @@ public VarBinArray truncate(long rows) {
             return ChunkedMode.of(dtype, rows, kept);
         }
     }
+
+    /// Arrow StringView / BinaryView {@code VarBinArray}.
+    ///
+    /// Each row is a 16-byte view in {@code views}: bytes 0-3 are the u32 size; for
+    /// sizes ≤ 12 bytes the data is inlined in bytes 4..15; for sizes > 12 bytes
+    /// bytes 4-7 hold a 4-byte prefix (ignored on read), bytes 8-11 the u32 buffer
+    /// index into {@code dataBufs}, and bytes 12-15 the u32 offset within that
+    /// buffer. Per-row accessors resolve the view on demand — no concat or
+    /// materialisation at construction time.
+    ///
+    /// {@link #bytesSegment()} returns {@link MemorySegment#NULL} because there is
+    /// no single contiguous bytes segment; callers needing one must materialise via
+    /// the typed accessors.
+    ///
+    /// @param dtype    logical element type (Utf8 or Binary)
+    /// @param length   total logical row count
+    /// @param views    16-byte view per row; length must be ≥ {@code length * 16}
+    /// @param dataBufs zero or more shared data buffers referenced by long views
+    @SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable refs that flow through pipelines without ever being compared.
+    record ViewMode(DType dtype, long length, MemorySegment views, MemorySegment[] dataBufs)
+            implements VarBinArray {
+
+        private static final int VIEW_SIZE = 16;
+        private static final int MAX_INLINED_SIZE = 12;
+
+        @Override
+        public MemorySegment bytesSegment() {
+            return MemorySegment.NULL;
+        }
+
+        @Override
+        public int getByteLength(long i) {
+            return views.get(PTypeIO.LE_INT, i * VIEW_SIZE);
+        }
+
+        @Override
+        public byte[] getBytes(long i) {
+            long viewOff = i * VIEW_SIZE;
+            int size = views.get(PTypeIO.LE_INT, viewOff);
+            byte[] out = new byte[size];
+            if (size <= MAX_INLINED_SIZE) {
+                MemorySegment.copy(views, viewOff + 4, MemorySegment.ofArray(out), 0, size);
+            } else {
+                int bufferIndex = views.get(PTypeIO.LE_INT, viewOff + 8);
+                long srcOffset = Integer.toUnsignedLong(views.get(PTypeIO.LE_INT, viewOff + 12));
+                MemorySegment.copy(dataBufs[bufferIndex], srcOffset, MemorySegment.ofArray(out), 0, size);
+            }
+            return out;
+        }
+
+        @Override
+        public String getString(long i) {
+            return new String(getBytes(i), StandardCharsets.UTF_8);
+        }
+
+        @Override
+        public void forEachByteLength(IntConsumer c) {
+            long n = length;
+            for (long i = 0; i < n; i++) {
+                c.accept(views.get(PTypeIO.LE_INT, i * VIEW_SIZE));
+            }
+        }
+
+        @Override
+        public VarBinArray truncate(long rows) {
+            if (rows >= length) {
+                return this;
+            }
+            return new ViewMode(dtype, rows, views.asSlice(0, rows * VIEW_SIZE), dataBufs);
+        }
+    }
 }

reader/src/main/java/io/github/dfa1/vortex/reader/decode/DictEncodingDecoder.java

@@ -158,13 +158,11 @@ private static Array decodeUtf8DictProto(DecodeContext ctx, ByteBuffer metaBuf)
         DType codesDtype = new DType.Primitive(codePType, false);
         MemorySegment codesBuf = ctx.decodeChildSegment(0, codesDtype, n);
 
-        Array valuesArr = ctx.decodeChild(1, ctx.dtype(), dictSize);
-        VarBinArray.OffsetMode varBinValues = (VarBinArray.OffsetMode) valuesArr;
-        MemorySegment dictBytes = varBinValues.bytesSegment();
-        MemorySegment dictOffsets = varBinValues.offsetsSegment();
+        VarBinArray valuesArr = (VarBinArray) ctx.decodeChild(1, ctx.dtype(), dictSize);
+        VarBinArray.OffsetMode dictValues = VarBinArray.toOffsetMode(valuesArr, ctx.arena());
 
         return VarBinArray.ofDict(ctx.dtype(), n,
-                dictBytes, dictOffsets, PType.I64,
+                dictValues.bytesSegment(), dictValues.offsetsSegment(), PType.I64,
                 codesBuf, codePType);
     }
 

reader/src/main/java/io/github/dfa1/vortex/reader/decode/RunEndEncodingDecoder.java

@@ -68,8 +68,8 @@ public Array decode(DecodeContext ctx) {
         Array endsArr = ctx.decodeChild(0, endsDtype, numRuns);
 
         if (ctx.dtype() instanceof DType.Utf8 || ctx.dtype() instanceof DType.Binary) {
-            Array valuesArr = ctx.decodeChild(1, ctx.dtype(), numRuns);
-            return expandStrings(endsArr, (VarBinArray.OffsetMode) valuesArr, endsPtype, numRuns, offset, n, ctx.dtype(), ctx.arena());
+            VarBinArray valuesArr = (VarBinArray) ctx.decodeChild(1, ctx.dtype(), numRuns);
+            return expandStrings(endsArr, VarBinArray.toOffsetMode(valuesArr, ctx.arena()), endsPtype, numRuns, offset, n, ctx.dtype(), ctx.arena());
         }
 
         if (ctx.dtype() instanceof DType.Bool) {

reader/src/main/java/io/github/dfa1/vortex/reader/decode/SparseEncodingDecoder.java

@@ -154,7 +154,8 @@ private static Array decodeVarBin(
 
         DType indicesDtype = new DType.Primitive(indicesPtype, false);
         MemorySegment idxSeg = ctx.decodeChildSegment(0, indicesDtype, numPatches);
-        VarBinArray.OffsetMode varBin = (VarBinArray.OffsetMode) ctx.decodeChild(1, ctx.dtype(), numPatches);
+        VarBinArray rawValues = (VarBinArray) ctx.decodeChild(1, ctx.dtype(), numPatches);
+        VarBinArray.OffsetMode varBin = VarBinArray.toOffsetMode(rawValues, ctx.arena());
         MemorySegment valBytes = varBin.bytesSegment();
         MemorySegment valOffsets = varBin.offsetsSegment();
         PType valOffPtype = varBin.offsetsPtype();
@@ -222,4 +223,5 @@ private static long scalarToLong(ScalarValue scalar) {
         }
         return 0L;
     }
+
 }

reader/src/main/java/io/github/dfa1/vortex/reader/decode/VarBinViewEncodingDecoder.java

@@ -1,21 +1,16 @@
 package io.github.dfa1.vortex.reader.decode;
 
 import io.github.dfa1.vortex.core.DType;
-import io.github.dfa1.vortex.core.PType;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.reader.array.VarBinArray;
 import io.github.dfa1.vortex.encoding.EncodingId;
-import io.github.dfa1.vortex.encoding.PTypeIO;
 
 import java.lang.foreign.MemorySegment;
 
 /// Read-only decoder for {@code vortex.varbinview} (Apache Arrow StringView/BinaryView).
 public final class VarBinViewEncodingDecoder implements EncodingDecoder {
 
-    private static final int MAX_INLINED_SIZE = 12;
-    private static final int VIEW_SIZE = 16;
-
     /// Public no-arg constructor required by {@link java.util.ServiceLoader}.
     public VarBinViewEncodingDecoder() {
     }
@@ -43,39 +38,14 @@ public Array decode(DecodeContext ctx) {
                     "expected at least 1 buffer (views), got 0");
         }
 
+        // Lazy path: keep views + data buffers as MemorySegment slices; per-row
+        // accessors resolve on demand via VarBinArray.ViewMode. No copy, no concat,
+        // no flat byte buffer allocation.
         MemorySegment viewsBuf = ctx.buffer(numBufs - 1);
         MemorySegment[] dataBufs = new MemorySegment[numBufs - 1];
         for (int i = 0; i < dataBufs.length; i++) {
             dataBufs[i] = ctx.buffer(i);
         }
-
-        long n = ctx.rowCount();
-
-        long totalBytes = 0;
-        for (long i = 0; i < n; i++) {
-            long size = Integer.toUnsignedLong(viewsBuf.get(PTypeIO.LE_INT, i * VIEW_SIZE));
-            totalBytes += size;
-        }
-
-        MemorySegment outBytes = ctx.arena().allocate(totalBytes > 0 ? totalBytes : 1);
-        MemorySegment outOffsets = ctx.arena().allocate((n + 1) * Long.BYTES, Long.BYTES);
-
-        long bytePos = 0;
-        outOffsets.setAtIndex(PTypeIO.LE_LONG, 0, 0L);
-        for (long i = 0; i < n; i++) {
-            long viewOff = i * VIEW_SIZE;
-            long size = Integer.toUnsignedLong(viewsBuf.get(PTypeIO.LE_INT, viewOff));
-            if (size <= MAX_INLINED_SIZE) {
-                MemorySegment.copy(viewsBuf, viewOff + 4, outBytes, bytePos, size);
-            } else {
-                int bufferIndex = viewsBuf.get(PTypeIO.LE_INT, viewOff + 8);
-                long srcOffset = Integer.toUnsignedLong(viewsBuf.get(PTypeIO.LE_INT, viewOff + 12));
-                MemorySegment.copy(dataBufs[bufferIndex], srcOffset, outBytes, bytePos, size);
-            }
-            bytePos += size;
-            outOffsets.setAtIndex(PTypeIO.LE_LONG, i + 1, bytePos);
-        }
-
-        return new VarBinArray.OffsetMode(ctx.dtype(), n, outBytes.asReadOnly(), outOffsets, PType.I64);
+        return new VarBinArray.ViewMode(ctx.dtype(), ctx.rowCount(), viewsBuf, dataBufs);
     }
 }