fix(reader): make vortex.sequence decode lazy

vortex.sequence is a closed-form encoding — A[i] = base + i * multiplier,
entirely in proto3 metadata, no buffers and no children. Every one of
SequenceEncodingDecoder's four paths nevertheless allocated
n * elemBytes and filled it.

Because the encoding is metadata-only, n was bounded by nothing on disk.
A buffer-backed encoding can at least be sanity-checked against its
mmapped segment; here a few bytes of metadata plus a large declared row
count named an arbitrary allocation, making the cheapest column in the
file the easiest one to turn into an OutOfMemoryError (ADR 0003/0004).

Adds the LazySequenceXxxArray family (Long/Int/Short/Byte/Float/Double/
Float16) mirroring LazyConstantXxxArray, and the decoder collapses to
metadata parsing. Value semantics are preserved exactly rather than
tidied, so decoded output stays bit-identical:

- integers compute in long and narrow on read, so they still wrap;
- fold zero-extends for U8/U16, matching Materialized{Byte,Short}Array;
- F32 keeps single-precision arithmetic — a double accumulator would
  sharpen steps that are not exactly representable;
- F16 round-trips through floatToFloat16 on every read, as the eager
  path did by storing half and widening on access.

Float16Array declares no default limited/materialize, so the F16 carrier
supplies both; materialize is now the only place the encoding can
allocate, and only on demand.

Also removes the per-element `switch (pt)` that sat inside decodeInteger's
loop — the non-uniform body CLAUDE.md's hot-loop rule prohibits. It
disappears with the loop itself.

docs/compatibility.md listed vortex.sequence as "Zero-copy — synthetic
(no data)", which was not true of the code; this makes the row accurate.

The decoder had no unit coverage at all. Adds SequenceEncodingDecoderTest
(all eight integer ptypes plus F32/F64/F16, asserting the concrete lazy
type since correct values alone also pass on the eager path) and
LazySequenceArrayTest (accessors, fold, unsigned widening, truncation,
half-precision round-trip).

Closes #335

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

Author: dfa1

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed
 
 - A run-end-encoded Utf8/Binary column (`vortex.runend`) no longer expands every run into a fully materialized buffer on decode; rows now resolve through the runs lazily, removing an unbounded `sum(runLength * valueLength)` allocation that a crafted file could drive to `OutOfMemoryError`. ([#334](https://github.com/dfa1/vortex-java/issues/334))
+- A `vortex.sequence` column no longer materializes `base + i * multiplier` into a full buffer on decode; rows are computed on access, so the encoding allocates nothing regardless of row count — closing an `OutOfMemoryError` risk from a metadata-only encoding whose row count no buffer bounds. ([#335](https://github.com/dfa1/vortex-java/issues/335))
 
 ## [0.13.1] — 2026-08-06
 

docs/compatibility.md

@@ -145,7 +145,7 @@ decoder falls into one of three shapes:
 | `vortex.alprd`              | Lazy          | Lazy          | `LazyAlpRdDoubleArray`/`LazyAlpRdFloatArray` — left/right + patches on access |
 | `vortex.dict`               | Lazy          | Lazy          | `DictXxxArray` (numeric) + `VarBinDictArray` (string), ADR 0012          |
 | `vortex.sparse`             | Lazy          | Lazy          | `LazySparseXxxArray` (primitive + bool); Utf8/Binary stays Materialized, ADR 0015 |
-| `vortex.sequence`           | Zero-copy     | Zero-copy     | synthetic (no data)                                                      |
+| `vortex.sequence`           | Lazy          | Lazy          | `LazySequenceXxxArray`; `base + i * multiplier` per access, no buffer, ADR 0015 |
 | `vortex.struct`             | Zero-copy     | Zero-copy     | `StructArray` wraps fields                                               |
 | `vortex.chunked`            | Lazy          | Lazy          | `ChunkedXxxArray` (primitive/Bool) + `VarBinChunkedArray` (Utf8/Binary), ADR 0012 |
 | `vortex.fsst`               | Materialized  | Materialized  | symbol-table decompression                                               |

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

@@ -0,0 +1,64 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.PType;
+
+import java.util.Objects;
+import java.util.function.LongBinaryOperator;
+
+/// Metadata-only [ByteArray] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// The sum is computed in `long` and narrowed, matching the eager decode this replaces.
+/// [#fold(long, LongBinaryOperator)] zero-extends for U8 columns, like the buffer-backed
+/// `MaterializedByteArray`.
+///
+/// @param dtype      logical primitive type (I8 / U8)
+/// @param length     total logical row count
+/// @param base       value at row 0
+/// @param multiplier step added per row
+public record LazySequenceByteArray(DType dtype, long length, long base, long multiplier)
+        implements ByteArray {
+
+    @Override
+    public byte getByte(long i) {
+        Objects.checkIndex(i, length);
+        return (byte) (base + i * multiplier);
+    }
+
+    @Override
+    public void forEachByte(ByteConsumer c) {
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        for (long i = 0; i < n; i++) {
+            c.accept((byte) (b + i * m));
+        }
+    }
+
+    @Override
+    public long fold(long identity, LongBinaryOperator op) {
+        boolean unsigned = dtype instanceof DType.Primitive p && p.ptype() == PType.U8;
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        long acc = identity;
+        for (long i = 0; i < n; i++) {
+            byte raw = (byte) (b + i * m);
+            acc = op.applyAsLong(acc, unsigned ? Byte.toUnsignedLong(raw) : raw);
+        }
+        return acc;
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceByteArray(dtype, rows, base, multiplier);
+    }
+}

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

@@ -0,0 +1,61 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.model.DType;
+
+import java.util.Objects;
+import java.util.function.DoubleBinaryOperator;
+import java.util.function.DoubleConsumer;
+
+/// Metadata-only [DoubleArray] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// The row index is converted to `double` before the multiply, matching the eager decode this
+/// replaces — so results stay bit-identical, including the precision loss past 2^53 rows.
+///
+/// @param dtype      logical primitive type (F64)
+/// @param length     total logical row count
+/// @param base       value at row 0
+/// @param multiplier step added per row
+public record LazySequenceDoubleArray(DType dtype, long length, double base, double multiplier)
+        implements DoubleArray {
+
+    @Override
+    public double getDouble(long i) {
+        Objects.checkIndex(i, length);
+        return base + i * multiplier;
+    }
+
+    @Override
+    public void forEachDouble(DoubleConsumer c) {
+        long n = length;
+        double b = base;
+        double m = multiplier;
+        for (long i = 0; i < n; i++) {
+            c.accept(b + i * m);
+        }
+    }
+
+    @Override
+    public double fold(double identity, DoubleBinaryOperator op) {
+        long n = length;
+        double b = base;
+        double m = multiplier;
+        double acc = identity;
+        for (long i = 0; i < n; i++) {
+            acc = op.applyAsDouble(acc, b + i * m);
+        }
+        return acc;
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceDoubleArray(dtype, rows, base, multiplier);
+    }
+}

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

@@ -0,0 +1,59 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.io.VortexFormat;
+import io.github.dfa1.vortex.core.model.DType;
+
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.SegmentAllocator;
+import java.util.Objects;
+
+/// Metadata-only [Float16Array] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// The step is computed in `float` and round-tripped through half precision on every read, so
+/// values match the eager decode this replaces bit for bit: it wrote
+/// [Float#floatToFloat16(float)] into the buffer and widened again on access.
+///
+/// @param dtype      logical primitive type (F16)
+/// @param length     total logical row count
+/// @param base       value at row 0, already widened from half precision
+/// @param multiplier step added per row, already widened from half precision
+public record LazySequenceFloat16Array(DType dtype, long length, float base, float multiplier)
+        implements Float16Array {
+
+    @Override
+    public float getFloat(long i) {
+        Objects.checkIndex(i, length);
+        return Float.float16ToFloat(Float.floatToFloat16(base + i * multiplier));
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceFloat16Array(dtype, rows, base, multiplier);
+    }
+
+    /// Materializes the sequence into a fresh little-endian half-precision segment.
+    /// [Float16Array] declares no default, and this is the only allocation the encoding
+    /// performs — on demand, for consumers that need a contiguous buffer.
+    ///
+    /// @param arena allocator for the output segment
+    /// @return a little-endian `f16` segment of `length()` elements
+    @Override
+    public MemorySegment materialize(SegmentAllocator arena) {
+        long n = length;
+        float b = base;
+        float m = multiplier;
+        MemorySegment dst = arena.allocate(n * 2L, 2);
+        for (long i = 0; i < n; i++) {
+            dst.setAtIndex(VortexFormat.LE_SHORT, i, Float.floatToFloat16(b + i * m));
+        }
+        return dst;
+    }
+}

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

@@ -0,0 +1,50 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.model.DType;
+
+import java.util.Objects;
+import java.util.function.DoubleBinaryOperator;
+
+/// Metadata-only [FloatArray] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// The arithmetic stays in `float`, matching the eager decode this replaces — so results stay
+/// bit-identical rather than being sharpened by a wider accumulator.
+///
+/// @param dtype      logical primitive type (F32)
+/// @param length     total logical row count
+/// @param base       value at row 0
+/// @param multiplier step added per row
+public record LazySequenceFloatArray(DType dtype, long length, float base, float multiplier)
+        implements FloatArray {
+
+    @Override
+    public float getFloat(long i) {
+        Objects.checkIndex(i, length);
+        return base + i * multiplier;
+    }
+
+    @Override
+    public double fold(double identity, DoubleBinaryOperator op) {
+        long n = length;
+        float b = base;
+        float m = multiplier;
+        double acc = identity;
+        for (long i = 0; i < n; i++) {
+            acc = op.applyAsDouble(acc, b + i * m);
+        }
+        return acc;
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceFloatArray(dtype, rows, base, multiplier);
+    }
+}

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

@@ -0,0 +1,60 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.model.DType;
+
+import java.util.Objects;
+import java.util.function.IntBinaryOperator;
+import java.util.function.IntConsumer;
+
+/// Metadata-only [IntArray] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// The sum is computed in `long` and narrowed, matching the eager decode this replaces.
+///
+/// @param dtype      logical primitive type (I32 / U32)
+/// @param length     total logical row count
+/// @param base       value at row 0
+/// @param multiplier step added per row
+public record LazySequenceIntArray(DType dtype, long length, long base, long multiplier)
+        implements IntArray {
+
+    @Override
+    public int getInt(long i) {
+        Objects.checkIndex(i, length);
+        return (int) (base + i * multiplier);
+    }
+
+    @Override
+    public void forEachInt(IntConsumer c) {
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        for (long i = 0; i < n; i++) {
+            c.accept((int) (b + i * m));
+        }
+    }
+
+    @Override
+    public int fold(int identity, IntBinaryOperator op) {
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        int acc = identity;
+        for (long i = 0; i < n; i++) {
+            acc = op.applyAsInt(acc, (int) (b + i * m));
+        }
+        return acc;
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceIntArray(dtype, rows, base, multiplier);
+    }
+}

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

@@ -0,0 +1,60 @@
+package io.github.dfa1.vortex.reader.array;
+
+import io.github.dfa1.vortex.core.model.DType;
+
+import java.util.Objects;
+import java.util.function.LongBinaryOperator;
+import java.util.function.LongConsumer;
+
+/// Metadata-only [LongArray] for `vortex.sequence` columns: `A[i] = base + i * multiplier`.
+///
+/// The encoding carries no buffers at all — base and multiplier live in proto3 metadata — so
+/// every row is computable in O(1) and no allocation is needed regardless of row count.
+///
+/// Arithmetic is `long` and wraps on overflow, matching the eager decode this replaces.
+///
+/// @param dtype      logical primitive type (I64 / U64)
+/// @param length     total logical row count
+/// @param base       value at row 0
+/// @param multiplier step added per row
+public record LazySequenceLongArray(DType dtype, long length, long base, long multiplier)
+        implements LongArray {
+
+    @Override
+    public long getLong(long i) {
+        Objects.checkIndex(i, length);
+        return base + i * multiplier;
+    }
+
+    @Override
+    public void forEachLong(LongConsumer c) {
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        for (long i = 0; i < n; i++) {
+            c.accept(b + i * m);
+        }
+    }
+
+    @Override
+    public long fold(long identity, LongBinaryOperator op) {
+        long n = length;
+        long b = base;
+        long m = multiplier;
+        long acc = identity;
+        for (long i = 0; i < n; i++) {
+            acc = op.applyAsLong(acc, b + i * m);
+        }
+        return acc;
+    }
+
+    /// Zero-copy truncation: the formula is unchanged for the leading rows, so only the
+    /// row count shrinks.
+    ///
+    /// @param rows number of leading rows to keep
+    /// @return a length-`rows` sequence over the same base and multiplier
+    @Override
+    public Array limited(long rows) {
+        return rows >= length ? this : new LazySequenceLongArray(dtype, rows, base, multiplier);
+    }
+}