feat(reader): lazy Sparse decode via top-level records

Replace the eager primitive Sparse expansion with six top-level record
types in reader.array: LazySparseLongArray, LazySparseIntArray,
LazySparseDoubleArray, LazySparseFloatArray, LazySparseShortArray,
LazySparseByteArray. Each holds (dtype, length, fillValue,
patchValues, patchIndices, offset) and resolves getXxx(i) via binary
search over patchIndices through the new package-private SparseArrays
helper. forEachXxx and fold walk the patches in order, emitting
fillValue for runs of unpatched positions — O(numPatches) work plus
length emissions, not O(length × allocation + patch scatter).

SparseArrays (package-private) centralises readPatchIdx (indices-type
switch) and two binary searches: findPatch (exact hit or -1 miss) for
scalar access and findFirstAtOrAfter for the forEach run-walker.

Bool and VarBin Sparse paths stay eager — Bool's bit-packing and
VarBin's offset rebasing don't trivially express as patch lookup on
read. The lazy switch only fires for I64/U64, I32/U32, F64, F32,
I16/U16, I8/U8.

SparseEncodingDecoder.decode now decodes patch children via decodeChild
(returning Arrays) instead of decodeChildSegment + manual scatter.
Dropped the dead fillSegment / applyPatches / readElem / writeElem
helpers.

LazySparseShortArray and LazySparseByteArray each carry both a raw
signed fill (for the typed getShort/getByte) and a widened int fill
(for the getInt path) so unsigned U16/U8 narrowing is preserved at
the lazy boundary.

10 new unit tests in LazySparseArrayTest cover fill vs patch dispatch,
ordered forEach iteration, fold reduction, offset slicing, and the
no-patches degenerate case. ./mvnw verify green (13 modules,
integration suite 41s).

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

Author: dfa1

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

@@ -0,0 +1,58 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.LongBinaryOperator;
+
+/// Lazy Sparse-encoded {@link ByteArray}. See {@link LazySparseLongArray} for semantics.
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position (raw signed byte)
+/// @param fillInt       value at every unpatched position widened to int (unsigned-aware for U8)
+/// @param patchValues   values for patched positions
+/// @param patchIndices  sorted absolute positions of patches
+/// @param offset        starting absolute position
+public record LazySparseByteArray(
+        DType dtype, long length, byte fillValue, int fillInt,
+        ByteArray patchValues, Array patchIndices, long offset)
+        implements ByteArray {
+
+    @Override
+    public byte getByte(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getByte(p) : fillValue;
+    }
+
+    @Override
+    public int getInt(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getInt(p) : fillInt;
+    }
+
+    @Override
+    public long fold(long identity, LongBinaryOperator op) {
+        long[] acc = {identity};
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                acc[0] = op.applyAsLong(acc[0], fillInt);
+            }
+            acc[0] = op.applyAsLong(acc[0], patchValues.getInt(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            acc[0] = op.applyAsLong(acc[0], fillInt);
+        }
+        return acc[0];
+    }
+}

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

@@ -0,0 +1,57 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.DoubleBinaryOperator;
+import java.util.function.DoubleConsumer;
+
+/// Lazy Sparse-encoded {@link DoubleArray}. See {@link LazySparseLongArray} for semantics.
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position
+/// @param patchValues   values for patched positions
+/// @param patchIndices  sorted absolute positions of patches
+/// @param offset        starting absolute position
+public record LazySparseDoubleArray(
+        DType dtype, long length, double fillValue,
+        DoubleArray patchValues, Array patchIndices, long offset)
+        implements DoubleArray {
+
+    @Override
+    public double getDouble(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getDouble(p) : fillValue;
+    }
+
+    @Override
+    public void forEachDouble(DoubleConsumer c) {
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                c.accept(fillValue);
+            }
+            c.accept(patchValues.getDouble(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            c.accept(fillValue);
+        }
+    }
+
+    @Override
+    public double fold(double identity, DoubleBinaryOperator op) {
+        double[] acc = {identity};
+        forEachDouble(v -> acc[0] = op.applyAsDouble(acc[0], v));
+        return acc[0];
+    }
+}

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

@@ -0,0 +1,51 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.DoubleBinaryOperator;
+
+/// Lazy Sparse-encoded {@link FloatArray}. See {@link LazySparseLongArray} for semantics.
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position
+/// @param patchValues   values for patched positions
+/// @param patchIndices  sorted absolute positions of patches
+/// @param offset        starting absolute position
+public record LazySparseFloatArray(
+        DType dtype, long length, float fillValue,
+        FloatArray patchValues, Array patchIndices, long offset)
+        implements FloatArray {
+
+    @Override
+    public float getFloat(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getFloat(p) : fillValue;
+    }
+
+    @Override
+    public double fold(double identity, DoubleBinaryOperator op) {
+        double[] acc = {identity};
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                acc[0] = op.applyAsDouble(acc[0], fillValue);
+            }
+            acc[0] = op.applyAsDouble(acc[0], patchValues.getFloat(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            acc[0] = op.applyAsDouble(acc[0], fillValue);
+        }
+        return acc[0];
+    }
+}

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

@@ -0,0 +1,57 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.IntBinaryOperator;
+import java.util.function.IntConsumer;
+
+/// Lazy Sparse-encoded {@link IntArray}. See {@link LazySparseLongArray} for semantics.
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position
+/// @param patchValues   values for patched positions
+/// @param patchIndices  sorted absolute positions of patches
+/// @param offset        starting absolute position
+public record LazySparseIntArray(
+        DType dtype, long length, int fillValue,
+        IntArray patchValues, Array patchIndices, long offset)
+        implements IntArray {
+
+    @Override
+    public int getInt(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getInt(p) : fillValue;
+    }
+
+    @Override
+    public void forEachInt(IntConsumer c) {
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                c.accept(fillValue);
+            }
+            c.accept(patchValues.getInt(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            c.accept(fillValue);
+        }
+    }
+
+    @Override
+    public int fold(int identity, IntBinaryOperator op) {
+        int[] acc = {identity};
+        forEachInt(v -> acc[0] = op.applyAsInt(acc[0], v));
+        return acc[0];
+    }
+}

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

@@ -0,0 +1,65 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.LongBinaryOperator;
+import java.util.function.LongConsumer;
+
+/// Lazy Sparse-encoded {@link LongArray}: {@code getLong(i) = patches[binSearch(i + offset)]
+/// or fillValue}. The {@code patchIndices} array is typed as {@link Array} because the
+/// indices ptype varies — backed by one of {@link ByteArray}, {@link ShortArray},
+/// {@link IntArray}, {@link LongArray}.
+///
+/// {@code forEachLong} / {@code fold} walk the patches in order, emitting {@code fillValue}
+/// for runs of unpatched positions — O(numPatches) binary-search-equivalent steps plus
+/// {@code length} emissions, not O(length × log(numPatches)).
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position
+/// @param patchValues   values for patched positions; length = {@code numPatches}
+/// @param patchIndices  sorted absolute positions of patches; length = {@code numPatches}
+/// @param offset        starting absolute position; logical row {@code i} maps to
+///                      absolute {@code i + offset}
+public record LazySparseLongArray(
+        DType dtype, long length, long fillValue,
+        LongArray patchValues, Array patchIndices, long offset)
+        implements LongArray {
+
+    @Override
+    public long getLong(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getLong(p) : fillValue;
+    }
+
+    @Override
+    public void forEachLong(LongConsumer c) {
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                c.accept(fillValue);
+            }
+            c.accept(patchValues.getLong(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            c.accept(fillValue);
+        }
+    }
+
+    @Override
+    public long fold(long identity, LongBinaryOperator op) {
+        long[] acc = {identity};
+        forEachLong(v -> acc[0] = op.applyAsLong(acc[0], v));
+        return acc[0];
+    }
+}

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

@@ -0,0 +1,58 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.DType;
+
+import java.util.function.LongBinaryOperator;
+
+/// Lazy Sparse-encoded {@link ShortArray}. See {@link LazySparseLongArray} for semantics.
+///
+/// @param dtype         logical element type
+/// @param length        total logical row count
+/// @param fillValue     value at every unpatched position (raw signed short)
+/// @param fillInt       value at every unpatched position widened to int (unsigned-aware for U16)
+/// @param patchValues   values for patched positions
+/// @param patchIndices  sorted absolute positions of patches
+/// @param offset        starting absolute position
+public record LazySparseShortArray(
+        DType dtype, long length, short fillValue, int fillInt,
+        ShortArray patchValues, Array patchIndices, long offset)
+        implements ShortArray {
+
+    @Override
+    public short getShort(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getShort(p) : fillValue;
+    }
+
+    @Override
+    public int getInt(long i) {
+        int p = SparseArrays.findPatch(patchIndices, patchValues.length(), i + offset);
+        return p >= 0 ? patchValues.getInt(p) : fillInt;
+    }
+
+    @Override
+    public long fold(long identity, LongBinaryOperator op) {
+        long[] acc = {identity};
+        long numPatches = patchValues.length();
+        long absStart = offset;
+        long absEnd = offset + length;
+        int p = SparseArrays.findFirstAtOrAfter(patchIndices, numPatches, absStart);
+        long pos = absStart;
+        while (pos < absEnd && p < numPatches) {
+            long patchAbs = SparseArrays.readPatchIdx(patchIndices, p);
+            if (patchAbs >= absEnd) {
+                break;
+            }
+            for (long r = pos; r < patchAbs; r++) {
+                acc[0] = op.applyAsLong(acc[0], fillInt);
+            }
+            acc[0] = op.applyAsLong(acc[0], patchValues.getInt(p));
+            pos = patchAbs + 1;
+            p++;
+        }
+        for (long r = pos; r < absEnd; r++) {
+            acc[0] = op.applyAsLong(acc[0], fillInt);
+        }
+        return acc[0];
+    }
+}