feat(reader): route untrusted slices/sizes through IoBounds (ADR 0003 Phase E)

Migrate the file-structure and decode-side bounds operations that take
offsets/lengths from parsed file bytes so a malformed file throws
VortexException, not a raw JDK exception:

- asSlice → IoBounds.slice: VortexReader (trailer/postscript/stats/segment),
  VortexHttpReader, Trailer magic, ScanIterator stats, FlatSegmentDecoder
  buffer descriptors, PostscriptParser blob slice.
- FlatSegmentDecoder and ScanIterator stats now guard the trailing u32 fbLen
  read (checkRange) and segLen narrowing (toIntSize) — both were previously
  unguarded; a crafted fbLen leaked IndexOutOfBoundsException.
- Math.toIntExact(storage.length()) → IoBounds.toIntSize in the Date/Time/
  Timestamp/Uuid extension decoders (ArithmeticException → VortexException
  on a > 2 GB declared length).

reader.array .limited() re-slices are left raw: offset 0, rows < length,
bounded by construction — not untrusted input (ADR 0003 Phase E item 5).

Existing MalformedTrailer/Footer/ZipBomb security tests stay green (no
behaviour change on already-validated paths). Follow-ups: checkstyle ban on
raw asSlice, checkCount guards on new T[(int)n] alloc sites, and the
Objects.checkIndex sweep of consumer-access getters.

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

Author: dfa1

docs/adr/0003-vortex-exception-sanitization.md

@@ -365,9 +365,12 @@ widens the parse surface.
 4. Collapse the ~14 consumer-access `getX(i)` guards onto
    `Objects.checkIndex(i, length)` (separate commit — different error class,
    no `IoBounds`).
-5. Checkstyle `RegexpSingleline` rejecting raw `.asSlice(` in
-   `reader` / `reader.array` / `reader.decode` / `core.proto` packages
-   (mirrors the existing `<p>`-blocking rule), so new raw slices can't regress.
+5. Checkstyle `RegexpSingleline` rejecting raw `.asSlice(` in the
+   file-structure (`reader` root) and `reader.decode` packages — the layers
+   that slice on offsets parsed from file bytes. `reader.array` is excluded:
+   its only `asSlice` calls are inside `limited(rows)`, re-slicing an already
+   validated segment at offset 0 with `rows < length` (bounded by construction,
+   no untrusted offset), so wrapping them adds noise without closing a gap.
 6. `BoundsTypingSecurityTest`: crafted file with out-of-range slice offset,
    oversize declared length, and non-monotonic VarBin offsets each produce a
    `VortexException`, never a raw JDK exception.

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.encoding.EncodingId;
 import io.github.dfa1.vortex.fbs.Buffer;
@@ -44,12 +45,15 @@ public FlatSegmentDecoder(ReadRegistry registry) {
     /// @return the decoded [Array] for this segment
     public Array decode(MemorySegment seg, List<String> encodingSpecs,
             DType dtype, long rowCount, SegmentAllocator arena) {
-        int segLen = (int) seg.byteSize();
+        int segLen = IoBounds.toIntSize(seg.byteSize());
         ByteBuffer bb = seg.asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
 
+        // The trailing u32 length field must itself be in range before we read it.
+        IoBounds.checkRange(segLen - 4L, 4, segLen);
         int fbLen = bb.getInt(segLen - 4);
-        int fbStart = segLen - 4 - fbLen;
-        ByteBuffer fbBuf = bb.slice(fbStart, fbLen).order(ByteOrder.LITTLE_ENDIAN);
+        long fbStart = segLen - 4L - fbLen;
+        IoBounds.checkRange(fbStart, fbLen, segLen);
+        ByteBuffer fbBuf = bb.slice((int) fbStart, fbLen).order(ByteOrder.LITTLE_ENDIAN);
         var fbArray = io.github.dfa1.vortex.fbs.Array.getRootAsArray(fbBuf);
 
         int numBuffers = fbArray.buffersLength();
@@ -58,7 +62,7 @@ public Array decode(MemorySegment seg, List<String> encodingSpecs,
         for (int i = 0; i < numBuffers; i++) {
             Buffer bufDesc = fbArray.buffers(i);
             dataOffset += bufDesc.padding();
-            bufs[i] = seg.asSlice(dataOffset, bufDesc.length());
+            bufs[i] = IoBounds.slice(seg, dataOffset, bufDesc.length());
             dataOffset += bufDesc.length();
         }
 

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.PType;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.fbs.Binary;
@@ -115,7 +116,7 @@ static ParsedFile parseBlobs(ByteBuffer footerBuf, ByteBuffer layoutBuf, ByteBuf
     }
 
     private static ByteBuffer slice(MemorySegment seg, long offset, long length) {
-        return seg.asSlice(offset, length).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
+        return IoBounds.slice(seg, offset, length).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
     }
 
     static Footer convertFooter(io.github.dfa1.vortex.fbs.Footer f) {

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.PType;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.encoding.EncodingId;
@@ -788,9 +789,10 @@ private ArrayStats readFlatStats(Layout flat) {
 
         // Stats FlatBuffer lives in the segment's last 4+fbLen bytes; reading the whole
         // segment as a ByteBuffer would fail for segments larger than 2 GB (ByteBuffer cap).
+        IoBounds.checkRange(segLen - 4L, 4, segLen);
         int fbLen = seg.get(LE_INT, segLen - 4);
         long fbStart = segLen - 4L - fbLen;
-        ByteBuffer fbBuf = seg.asSlice(fbStart, fbLen).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
+        ByteBuffer fbBuf = IoBounds.slice(seg, fbStart, fbLen).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
         var fbArray = io.github.dfa1.vortex.fbs.Array.getRootAsArray(fbBuf);
 
         io.github.dfa1.vortex.fbs.ArrayNode root = fbArray.root();

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

@@ -1,5 +1,6 @@
 package io.github.dfa1.vortex.reader;
 
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.VortexFormat;
 
@@ -32,7 +33,7 @@ static Trailer parse(MemorySegment trailerSeg, long bodyBytes) {
         int version = Short.toUnsignedInt(trailerSeg.get(LE_SHORT, 0));
         int postscriptLen = Short.toUnsignedInt(trailerSeg.get(LE_SHORT, 2));
 
-        MemorySegment magicSlice = trailerSeg.asSlice(4, VortexFormat.MAGIC_SIZE);
+        MemorySegment magicSlice = IoBounds.slice(trailerSeg, 4, VortexFormat.MAGIC_SIZE);
         if (magicSlice.mismatch(VortexFormat.MAGIC) != -1) {
             throw new VortexException(
                 "invalid magic bytes [%02x %02x %02x %02x]".formatted(

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.VortexFormat;
 import io.github.dfa1.vortex.fbs.Postscript;
@@ -90,7 +91,7 @@ public static VortexHttpReader open(URI uri, ReadRegistry registry, HttpClient c
         MemorySegment tailSeg = MemorySegment.ofArray(tail);
         long trailerOff = tailLen - VortexFormat.TRAILER_SIZE;
         long bodyBytes = fileSize - VortexFormat.TRAILER_SIZE;
-        Trailer trailer = Trailer.parse(tailSeg.asSlice(trailerOff, VortexFormat.TRAILER_SIZE), bodyBytes);
+        Trailer trailer = Trailer.parse(IoBounds.slice(tailSeg, trailerOff, VortexFormat.TRAILER_SIZE), bodyBytes);
 
         // HTTP-specific: postscript may extend past the prefetched tail and need a larger fetch.
         long psOffInTail = trailerOff - trailer.postscriptLen();
@@ -100,7 +101,7 @@ public static VortexHttpReader open(URI uri, ReadRegistry registry, HttpClient c
                     .formatted(trailer.postscriptLen(), TAIL_SIZE));
         }
 
-        ByteBuffer postscriptBuf = tailSeg.asSlice(psOffInTail, trailer.postscriptLen())
+        ByteBuffer postscriptBuf = IoBounds.slice(tailSeg, psOffInTail, trailer.postscriptLen())
                                        .asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
 
         var ps = Postscript.getRootAsPostscript(postscriptBuf);

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.VortexFormat;
 
@@ -78,11 +79,11 @@ private static VortexReader parse(
             MemorySegment seg, long size, Arena arena, ReadRegistry registry
     ) {
         long bodyBytes = size - VortexFormat.TRAILER_SIZE;
-        var trailerSeg = seg.asSlice(bodyBytes, VortexFormat.TRAILER_SIZE);
+        var trailerSeg = IoBounds.slice(seg, bodyBytes, VortexFormat.TRAILER_SIZE);
         Trailer trailer = Trailer.parse(trailerSeg, bodyBytes);
 
         long postscriptOffset = bodyBytes - trailer.postscriptLen();
-        var postscriptBuf = seg.asSlice(postscriptOffset, trailer.postscriptLen())
+        var postscriptBuf = IoBounds.slice(seg, postscriptOffset, trailer.postscriptLen())
                                     .asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
 
         PostscriptParser.ParsedFile parsed;
@@ -211,15 +212,15 @@ private ArrayStats readFlatStats(Layout flat) {
         if (segLen < 4) {
             return ArrayStats.empty();
         }
-        MemorySegment seg = fileSegment.asSlice(spec.offset(), segLen);
+        MemorySegment seg = IoBounds.slice(fileSegment, spec.offset(), segLen);
         int fbLen = seg.get(LE_INT, segLen - 4);
         // Reject negative fbLen (signed int from untrusted bytes) or any value that would push
         // fbStart below 0 → asSlice(negative, ...) throws IndexOutOfBoundsException without this guard.
         if (fbLen < 0 || fbLen > segLen - 4) {
             return ArrayStats.empty();
         }
         long fbStart = segLen - 4L - fbLen;
-        var fbBuf = seg.asSlice(fbStart, fbLen).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
+        var fbBuf = IoBounds.slice(seg, fbStart, fbLen).asByteBuffer().order(ByteOrder.LITTLE_ENDIAN);
         var fbArray = io.github.dfa1.vortex.fbs.Array.getRootAsArray(fbBuf);
         var root = fbArray.root();
         if (root == null) {
@@ -234,15 +235,15 @@ public io.github.dfa1.vortex.reader.array.Array decodeFlatSegment(
             DType dtype, long rowCount,
             java.lang.foreign.SegmentAllocator arena
     ) {
-        MemorySegment seg = fileSegment.asSlice(spec.offset(), spec.length()).asReadOnly();
+        MemorySegment seg = IoBounds.slice(fileSegment, spec.offset(), spec.length()).asReadOnly();
         return new FlatSegmentDecoder(registry)
                 .decode(seg, footer.arraySpecs(), dtype, rowCount, arena);
     }
 
     /// Zero-copy read-only slice of the memory-mapped file covering the given spec.
     @Override
     public MemorySegment rawSegment(SegmentSpec spec) {
-        return fileSegment.asSlice(spec.offset(), spec.length()).asReadOnly();
+        return IoBounds.slice(fileSegment, spec.offset(), spec.length()).asReadOnly();
     }
 
     @Override

reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader.extension;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.PType;
 import io.github.dfa1.vortex.encoding.TimeUnit;
 import io.github.dfa1.vortex.reader.array.Array;
@@ -60,7 +61,7 @@ public LocalDate decode(Array storage, long i) {
     /// @param storage signed-integer storage array (optionally wrapped in `MaskedArray`)
     /// @return list of decoded dates in row order; `null` entries mark invalid rows
     public List<LocalDate> decodeAll(Array storage) {
-        int n = Math.toIntExact(storage.length());
+        int n = IoBounds.toIntSize(storage.length());
         List<LocalDate> out = new ArrayList<>(n);
         if (storage instanceof MaskedArray masked) {
             for (long i = 0; i < n; i++) {

reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader.extension;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.reader.array.MaskedArray;
@@ -72,7 +73,7 @@ public LocalTime decode(DType.Extension ext, Array storage, long i) {
     /// @param storage signed-integer storage array (optionally wrapped in `MaskedArray`)
     /// @return list of decoded times in row order; `null` entries mark invalid rows
     public List<LocalTime> decodeAll(DType.Extension ext, Array storage) {
-        int n = Math.toIntExact(storage.length());
+        int n = IoBounds.toIntSize(storage.length());
         List<LocalTime> out = new ArrayList<>(n);
         if (storage instanceof MaskedArray masked) {
             for (long i = 0; i < n; i++) {

reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java

@@ -1,6 +1,7 @@
 package io.github.dfa1.vortex.reader.extension;
 
 import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.IoBounds;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.reader.array.MaskedArray;
@@ -95,7 +96,7 @@ public Optional<ZoneId> timezone(DType.Extension ext) {
     /// @param storage signed-integer storage array (optionally wrapped in `MaskedArray`)
     /// @return list of decoded instants in row order; `null` entries mark invalid rows
     public List<Instant> decodeAll(DType.Extension ext, Array storage) {
-        int n = Math.toIntExact(storage.length());
+        int n = IoBounds.toIntSize(storage.length());
         List<Instant> out = new ArrayList<>(n);
         if (storage instanceof MaskedArray masked) {
             for (long i = 0; i < n; i++) {