fix(reader): honor custom decoders under chunked; harden SPI edges

Review findings on the LayoutDecoder SPI:

- ChunkedLayoutDecoder decoded its leaves via a direct static
  FlatLayoutDecoder call, silently bypassing the registry — a custom
  decoder registered for a leaf id was not honored under a chunked
  parent, making the SPI partially decorative. Leaves now route
  through ctx.decodeChild; the end-to-end test asserts the flat
  delegator itself fires during a real scan. Integration oracle
  confirms identical behavior for built-ins (dict leaves under
  chunked included).
- ScanLayoutContext.segmentSpec and DictLayoutDecoder child access
  now guard malformed indexes/arity with VortexException instead of
  leaking IndexOutOfBoundsException from untrusted input.

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

Author: dfa1

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

@@ -824,7 +824,13 @@ public Array decodeFlatSegment(SegmentSpec spec, DType dtype, long rowCount) {
 
         @Override
         public SegmentSpec segmentSpec(int index) {
-            return file.footer().segmentSpecs().get(index);
+            List<SegmentSpec> specs = file.footer().segmentSpecs();
+            if (index < 0 || index >= specs.size()) {
+                // Untrusted input: a malformed flat layout may carry any segment index.
+                throw new VortexException("segment index " + index
+                        + " out of bounds (segmentSpecs.size=" + specs.size() + ")");
+            }
+            return specs.get(index);
         }
     }
 

reader/src/main/java/io/github/dfa1/vortex/reader/layout/ChunkedLayoutDecoder.java

@@ -70,13 +70,15 @@ private static Array decodeChunkedLayout(LayoutDecodeContext ctx, List<Layout> f
             throw new VortexException(EncodingId.VORTEX_CHUNKED, "no flat children");
         }
         if (flats.size() == 1) {
-            return FlatLayoutDecoder.decodeFlat(ctx, flats.getFirst(), dtype);
+            return ctx.decodeChild(flats.getFirst(), dtype);
         }
         // ADR 0012: every primitive ptype gets the zero-copy ChunkedXxxArray shape.
         // The concat path is gone.
         var chunkArrays = new ArrayList<Array>(flats.size());
         for (Layout flat : flats) {
-            chunkArrays.add(FlatLayoutDecoder.decodeFlat(ctx, flat, dtype));
+            // Registry dispatch, not a direct decodeFlat call — a custom decoder registered for
+            // a leaf's layout id must be honored under a chunked parent too.
+            chunkArrays.add(ctx.decodeChild(flat, dtype));
         }
         if (dtype instanceof DType.Bool) {
             return ChunkedBoolArray.of(dtype, totalRows, chunkArrays);

reader/src/main/java/io/github/dfa1/vortex/reader/layout/DictLayoutDecoder.java

@@ -45,6 +45,11 @@ public Array decode(LayoutDecodeContext ctx, Layout dictLayout, DType dtype) {
         PType codesPType = readDictLayoutCodesPType(rawMeta);
 
         // child[0] = values layout; child[1] = codes layout
+        if (dictLayout.children().size() < 2) {
+            // Untrusted input: a malformed dict layout may carry any child count.
+            throw new VortexException(EncodingId.VORTEX_DICT,
+                    "expected 2 children (values, codes), got " + dictLayout.children().size());
+        }
         Layout valuesLayout = dictLayout.children().get(0);
         Layout codesLayout = dictLayout.children().get(1);
         long n = codesLayout.rowCount();

reader/src/main/java/io/github/dfa1/vortex/reader/layout/FlatLayoutDecoder.java

@@ -17,23 +17,11 @@ public LayoutId layoutId() {
 
     @Override
     public Array decode(LayoutDecodeContext ctx, Layout layout, DType dtype) {
-        return decodeFlat(ctx, layout, dtype);
-    }
-
-    /// Decodes one flat leaf: resolves its single segment index to a [SegmentSpec] and delegates
-    /// to the file handle. Shared with [ChunkedLayoutDecoder], which decodes each of its collected
-    /// leaves through exactly this path (not registry dispatch), preserving the original behavior.
-    ///
-    /// @param ctx   the decode context
-    /// @param flat  the flat layout node
-    /// @param dtype logical type of the decoded array
-    /// @return the decoded [Array]
-    static Array decodeFlat(LayoutDecodeContext ctx, Layout flat, DType dtype) {
-        if (flat.segments().isEmpty()) {
+        if (layout.segments().isEmpty()) {
             throw new VortexException("no segments");
         }
-        int segIdx = flat.segments().getFirst();
+        int segIdx = layout.segments().getFirst();
         SegmentSpec spec = ctx.segmentSpec(segIdx);
-        return ctx.decodeFlatSegment(spec, dtype, flat.rowCount());
+        return ctx.decodeFlatSegment(spec, dtype, layout.rowCount());
     }
 }

reader/src/test/java/io/github/dfa1/vortex/reader/layout/LayoutRegistryTest.java

@@ -94,12 +94,13 @@ void openWithCustomRegistry_reachesTheCustomDecoderDuringScan() throws URISyntax
         // Given — a LayoutRegistry whose built-ins are wrapped in counting delegators, so any decode
         // dispatch during a real scan is observable. This proves the open(path, reg, layoutReg)
         // overload threads the custom registry all the way into ScanIterator's decode path.
-        AtomicInteger dispatches = new AtomicInteger();
+        AtomicInteger flatDispatches = new AtomicInteger();
+        AtomicInteger otherDispatches = new AtomicInteger();
         LayoutRegistry custom = LayoutRegistry.builder()
-                .register(new CountingLayoutDecoder(new FlatLayoutDecoder(), dispatches))
-                .register(new CountingLayoutDecoder(new ChunkedLayoutDecoder(), dispatches))
-                .register(new CountingLayoutDecoder(new ZonedLayoutDecoder(), dispatches))
-                .register(new CountingLayoutDecoder(new DictLayoutDecoder(), dispatches))
+                .register(new CountingLayoutDecoder(new FlatLayoutDecoder(), flatDispatches))
+                .register(new CountingLayoutDecoder(new ChunkedLayoutDecoder(), otherDispatches))
+                .register(new CountingLayoutDecoder(new ZonedLayoutDecoder(), otherDispatches))
+                .register(new CountingLayoutDecoder(new DictLayoutDecoder(), otherDispatches))
                 .build();
         Path fixture = fixtureFile("primitives.vortex");
 
@@ -114,9 +115,11 @@ void openWithCustomRegistry_reachesTheCustomDecoderDuringScan() throws URISyntax
             }
         }
 
-        // Then — the scan produced rows and routed every layout decode through the custom registry
+        // Then — the scan produced rows, and the FLAT delegator itself fired: leaf decode under a
+        // container layout goes through registry dispatch too (a custom flat decoder is honored),
+        // not through a direct built-in call that would bypass the registry.
         assertThat(rows).isPositive();
-        assertThat(dispatches.get()).isPositive();
+        assertThat(flatDispatches.get()).isPositive();
     }
 
     // ── helpers ───────────────────────────────────────────────────────────────