refactor(reader): rename Array.truncate -> limited

"truncate" reads as "empty the array" (SQL TRUNCATE, file truncate-to-0);
the operation keeps the first N rows. Rename to limited(rows) across the
hierarchy and unify the prior naming drift:
- Array.truncate -> limited; static guard Array.truncated -> Array.limited
- all family-interface defaults + Chunked/Null/Masked/Decimal overrides
- VarBinArray.truncate -> limited
- GenericArray.withLength folded into limited (single method)
- ChunkedArrays.truncateChildren -> limitedChildren
- ScanIterator.truncateColumns -> limitedColumns
- tests updated

Pure rename; no behaviour change.

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

Author: dfa1

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

@@ -257,10 +257,10 @@ private static long readUnsigned(MemorySegment seg, long idx, PType ptype) {
 
     // ── Zone-map pruning ──────────────────────────────────────────────────────
 
-    private static Map<String, Array> truncateColumns(Map<String, Array> columns, long rows) {
+    private static Map<String, Array> limitedColumns(Map<String, Array> columns, long rows) {
         var result = new LinkedHashMap<String, Array>(columns.size());
         for (var entry : columns.entrySet()) {
-            result.put(entry.getKey(), Array.truncated(entry.getValue(), rows));
+            result.put(entry.getKey(), Array.limited(entry.getValue(), rows));
         }
         return Map.copyOf(result);
     }
@@ -312,7 +312,7 @@ public Chunk next() {
         try {
             Map<String, Array> columns = buildColumnMap(spec, arena);
             if (chunkRows < spec.rowCount()) {
-                columns = truncateColumns(columns, chunkRows);
+                columns = limitedColumns(columns, chunkRows);
             }
             rowsReturned += chunkRows;
             Map<String, DType> chunkDtypes = new java.util.LinkedHashMap<>();

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

@@ -28,19 +28,19 @@ public sealed interface Array
     ///
     /// Used by the scan layer to honour [io.github.dfa1.vortex.reader.ScanOptions]
     /// row limits. Callers must guarantee `rows < length()` — use the
-    /// [#truncated(Array, long)] guard, which short-circuits the no-op case.
+    /// [#limited(Array, long)] guard, which short-circuits the no-op case.
     ///
     /// The primitive family interfaces ([LongArray], [IntArray], …) provide a
     /// zero-copy default: a length-capping view over `this` (no buffer is copied).
     /// Subtypes that can do better override it — chunked arrays keep their whole
-    /// prefix children and only truncate the boundary child, preserving batch
+    /// prefix children and only limited the boundary child, preserving batch
     /// iteration. The base default fails fast for types with no truncation support
     /// (struct, list, …).
     ///
     /// @param rows number of leading elements to keep; must be `< length()`
     /// @return a new array of length `rows`
     /// @throws VortexException if truncation is not supported for this array type
-    default Array truncate(long rows) {
+    default Array limited(long rows) {
         throw new VortexException("limit: truncation not supported for " + getClass().getSimpleName());
     }
 
@@ -49,10 +49,10 @@ default Array truncate(long rows) {
     /// recurse into children, so the `rows >= length()` no-op is handled in exactly
     /// one place.
     ///
-    /// @param arr  array to truncate
+    /// @param arr  array to limited
     /// @param rows desired length
-    /// @return `arr` when `arr.length() <= rows`, otherwise `arr.truncate(rows)`
-    static Array truncated(Array arr, long rows) {
-        return arr.length() <= rows ? arr : arr.truncate(rows);
+    /// @return `arr` when `arr.length() <= rows`, otherwise `arr.limited(rows)`
+    static Array limited(Array arr, long rows) {
+        return arr.length() <= rows ? arr : arr.limited(rows);
     }
 }

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

@@ -29,7 +29,7 @@ default void forEachBoolean(BooleanConsumer c) {
     /// @param rows number of leading elements to keep
     /// @return a length-`rows` bool array view
     @Override
-    default Array truncate(long rows) {
+    default Array limited(long rows) {
         return new OffsetBoolArray(dtype(), rows, this, 0);
     }
 }

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

@@ -50,7 +50,7 @@ default void forEachByte(ByteConsumer c) {
     /// @param rows number of leading elements to keep
     /// @return a length-`rows` byte array view
     @Override
-    default Array truncate(long rows) {
+    default Array limited(long rows) {
         return new OffsetByteArray(dtype(), rows, this, 0);
     }
 }

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

@@ -3,8 +3,8 @@
 import java.util.ArrayList;
 import java.util.List;
 
-/// Shared helper for the `ChunkedXxxArray.truncate` overrides. Keeps whole prefix
-/// children that fit within `rows` and recursively truncates the single boundary
+/// Shared helper for the `ChunkedXxxArray.limited` overrides. Keeps whole prefix
+/// children that fit within `rows` and recursively limits the single boundary
 /// child — preserving each chunk's batch iteration / zero-copy backing instead of
 /// the per-element view a plain length-cap would impose.
 final class ChunkedArrays {
@@ -17,8 +17,8 @@ private ChunkedArrays() {
     /// @param children chunk arrays in scan order
     /// @param offsets  cumulative row offsets (length = `children.length + 1`)
     /// @param rows     number of leading rows to keep
-    /// @return prefix children unchanged, with the boundary child truncated
-    static List<Array> truncateChildren(Array[] children, long[] offsets, long rows) {
+    /// @return prefix children unchanged, with the boundary child limited
+    static List<Array> limitedChildren(Array[] children, long[] offsets, long rows) {
         var kept = new ArrayList<Array>(children.length);
         for (int i = 0; i < children.length; i++) {
             long start = offsets[i];
@@ -29,7 +29,7 @@ static List<Array> truncateChildren(Array[] children, long[] offsets, long rows)
             if (end <= rows) {
                 kept.add(children[i]);
             } else {
-                kept.add(Array.truncated(children[i], rows - start));
+                kept.add(Array.limited(children[i], rows - start));
             }
         }
         return kept;

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

@@ -72,7 +72,7 @@ public void forEachBoolean(BooleanConsumer c) {
     }
 
     @Override
-    public Array truncate(long rows) {
-        return ChunkedBoolArray.of(dtype, rows, ChunkedArrays.truncateChildren(children, offsets, rows));
+    public Array limited(long rows) {
+        return ChunkedBoolArray.of(dtype, rows, ChunkedArrays.limitedChildren(children, offsets, rows));
     }
 }

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

@@ -84,7 +84,7 @@ public void forEachByte(ByteConsumer c) {
     }
 
     @Override
-    public Array truncate(long rows) {
-        return ChunkedByteArray.of(dtype, rows, ChunkedArrays.truncateChildren(children, offsets, rows));
+    public Array limited(long rows) {
+        return ChunkedByteArray.of(dtype, rows, ChunkedArrays.limitedChildren(children, offsets, rows));
     }
 }

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

@@ -81,7 +81,7 @@ public double fold(double identity, DoubleBinaryOperator op) {
     }
 
     @Override
-    public Array truncate(long rows) {
-        return ChunkedDoubleArray.of(dtype, rows, ChunkedArrays.truncateChildren(children, offsets, rows));
+    public Array limited(long rows) {
+        return ChunkedDoubleArray.of(dtype, rows, ChunkedArrays.limitedChildren(children, offsets, rows));
     }
 }

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

@@ -71,7 +71,7 @@ public double fold(double identity, DoubleBinaryOperator op) {
     }
 
     @Override
-    public Array truncate(long rows) {
-        return ChunkedFloatArray.of(dtype, rows, ChunkedArrays.truncateChildren(children, offsets, rows));
+    public Array limited(long rows) {
+        return ChunkedFloatArray.of(dtype, rows, ChunkedArrays.limitedChildren(children, offsets, rows));
     }
 }

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

@@ -79,7 +79,7 @@ public int fold(int identity, IntBinaryOperator op) {
     }
 
     @Override
-    public Array truncate(long rows) {
-        return ChunkedIntArray.of(dtype, rows, ChunkedArrays.truncateChildren(children, offsets, rows));
+    public Array limited(long rows) {
+        return ChunkedIntArray.of(dtype, rows, ChunkedArrays.limitedChildren(children, offsets, rows));
     }
 }