refactor(reader): Footer carries typed EncodingId/LayoutId specs

Footer.arraySpecs()/layoutSpecs() become List<EncodingId>/
List<LayoutId>. Total parse (unknown id -> Custom) removed the
blocker that kept these stringly-typed; now the wire strings are
parsed once at the footer boundary — with the blank-id guard — and
array/layout nodes index directly into typed dictionaries.

The two scattered per-node parse+blank-guard sites (SerializedArray-
Decoder.convertArrayNode, PostscriptParser.convertLayout) collapse
into two footer-level helpers; a blank encoding id is now
unrepresentable below the boundary by construction, so its test
moves to the footer parser. Inspector/Pco-diagnostic keep String
display DTOs, converting at their own text-output boundary.

Completes the typed-id arc: the spec dictionaries were the last
stringly-typed holdout under ArrayNode/Layout.

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

Author: dfa1

CHANGELOG.md

@@ -31,6 +31,8 @@ claim measured against the Rust (JNI) oracle; behavior divergences documented in
 
 ### Changed
 
+- `Footer.arraySpecs()` / `Footer.layoutSpecs()` return typed `List<EncodingId>` / `List<LayoutId>` instead of `List<String>`. The wire strings are parsed to their typed ids once at the footer boundary (with the blank-id guard), so array and layout nodes index directly into typed dictionaries — completing "strings at the boundary, types inside": the two scattered per-node `parse` calls in `SerializedArrayDecoder` and the layout converter are gone. ([pending-footer](https://github.com/dfa1/vortex-java/commits/main))
+
 - The CLI uber-jar is now fully self-contained for `vortex.zstd` files: it bundles the FFM binding's native `libzstd` for all six platforms (osx/linux/windows × x86_64/aarch64) via `zstd-platform` — previously it shipped the binding's classes but relied on a system libzstd. The library modules keep zstd optional. ([1983656b](https://github.com/dfa1/vortex-java/commit/1983656b))
 - The zstd binding stays a two-artifact opt-in (`io.github.dfa1.zstd:zstd` + `zstd-platform`, both `optional`; no JNI anywhere), and touching `vortex.zstd` without it now fails with an actionable `VortexException` naming the two artifacts to add, instead of a raw `NoClassDefFoundError`. Default write/read paths never touch the binding (measured). ([ae9f95cc](https://github.com/dfa1/vortex-java/commit/ae9f95cc))
 - The little-endian `ValueLayout` constants moved from `PTypeIO.LE_*` to `VortexFormat.LE_*` — endianness is a property of the wire format, not of ptypes, and `VortexFormat` is where format facts live. Six classes that carried private copies (including reversed-name duplicates like `SHORT_LE`) now share the single source; nothing outside `VortexFormat` defines a `withOrder(LITTLE_ENDIAN)` layout. ([c060d34f](https://github.com/dfa1/vortex-java/commit/c060d34f))

inspector/src/main/java/io/github/dfa1/vortex/inspect/InspectorTree.java

@@ -3,6 +3,7 @@
 import static io.github.dfa1.vortex.core.io.VortexFormat.LE_INT;
 
 import io.github.dfa1.vortex.reader.ArrayStats;
+import io.github.dfa1.vortex.core.model.EncodingId;
 import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.reader.Footer;
 import io.github.dfa1.vortex.reader.layout.Layout;
@@ -112,7 +113,7 @@ public static InspectorTree buildShallow(VortexHandle handle) {
                 handle.version(),
                 handle.fileSize(),
                 dtype,
-                footer.arraySpecs(),
+                footer.arraySpecs().stream().map(EncodingId::id).toList(),
                 Set.of(),
                 footer.segmentSpecs(),
                 layout.rowCount(),
@@ -186,15 +187,15 @@ public static InspectorTree build(VortexHandle handle, Progress progress) {
                 handle.version(),
                 handle.fileSize(),
                 dtype,
-                footer.arraySpecs(),
+                footer.arraySpecs().stream().map(EncodingId::id).toList(),
                 Set.copyOf(overallUsed),
                 footer.segmentSpecs(),
                 layout.rowCount(),
                 root);
     }
 
     private static Node buildNode(Layout layout, Optional<String> fieldName, VortexHandle handle,
-            List<String> arraySpecs, Set<String> overallUsed,
+            List<EncodingId> arraySpecs, Set<String> overallUsed,
             Progress progress, int[] counter, int total) {
         Set<String> localUsed = new LinkedHashSet<>();
         ArrayStats stats = ArrayStats.empty();
@@ -253,7 +254,7 @@ public interface Progress {
         void update(int current, int total);
     }
 
-    private static Peek peekFlatRoot(MemorySegment seg, List<String> arraySpecs) {
+    private static Peek peekFlatRoot(MemorySegment seg, List<EncodingId> arraySpecs) {
         int segLen = (int) seg.byteSize();
         int fbLen = seg.get(LE_INT, segLen - 4L);
         long fbStart = segLen - 4L - fbLen;
@@ -262,7 +263,7 @@ private static Peek peekFlatRoot(MemorySegment seg, List<String> arraySpecs) {
         if (root == null) {
             return new Peek(null, ArrayStats.empty());
         }
-        return new Peek(arraySpecs.get(root.encoding()), ArrayStats.fromFbs(root.stats()));
+        return new Peek(arraySpecs.get(root.encoding()).id(), ArrayStats.fromFbs(root.stats()));
     }
 
     /// Result of a single Flat segment peek - the resolved encoding id (or

inspector/src/test/java/io/github/dfa1/vortex/inspect/InspectorTreeTest.java

@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.reader.CompressionScheme;
 import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.EncodingId;
 import io.github.dfa1.vortex.core.model.LayoutId;
 import io.github.dfa1.vortex.reader.Footer;
 import io.github.dfa1.vortex.reader.layout.Layout;
@@ -122,7 +123,7 @@ void build_carriesVersionAndFileSize() {
         given(handle.fileSize()).willReturn(123_456L);
         given(handle.dtype()).willReturn(dtype);
         given(handle.layout()).willReturn(root);
-        given(handle.footer()).willReturn(new Footer(List.of("vortex.flat"), List.of(), List.of(), List.of()));
+        given(handle.footer()).willReturn(new Footer(List.of(EncodingId.parse("vortex.flat")), List.of(), List.of(), List.of()));
 
         // When
         InspectorTree sut = InspectorTree.build(handle);
@@ -231,7 +232,7 @@ void peek_compressedFlatSegment_returnsEmptyWithoutSlicing() {
         InspectorTree.Node node = new InspectorTree.Node(flat, java.util.Optional.empty(),
                 Set.of(), io.github.dfa1.vortex.reader.ArrayStats.empty(), List.of());
         given(handle.footer()).willReturn(new io.github.dfa1.vortex.reader.Footer(
-                List.of("vortex.flat"), List.of(),
+                List.of(EncodingId.parse("vortex.flat")), List.of(),
                 List.of(new SegmentSpec(0, 100, (byte) 0, CompressionScheme.ZSTD)),
                 List.of()));
 
@@ -265,7 +266,8 @@ void build_flatChildWithCompressedSegment_skipsRootEncodingPeek() {
     private void givenHandle(DType dtype, Layout layout, List<String> arraySpecs, List<SegmentSpec> segs) {
         given(handle.dtype()).willReturn(dtype);
         given(handle.layout()).willReturn(layout);
-        given(handle.footer()).willReturn(new Footer(arraySpecs, List.of(), segs, List.of()));
+        given(handle.footer()).willReturn(new Footer(
+                arraySpecs.stream().map(EncodingId::parse).toList(), List.of(), segs, List.of()));
     }
 
     private static Layout struct(long rows, List<Layout> children) {

integration/src/test/java/io/github/dfa1/vortex/integration/PcoFixtureInspectionIntegrationTest.java

@@ -53,7 +53,8 @@ private static void inspect(Path file, StringBuilder out) throws Exception {
             out.append("dtype: ").append(formatDType(vf.dtype())).append('\n');
             out.append("size: ").append(vf.fileSize()).append(" bytes\n");
 
-            List<String> arraySpecs = vf.footer().arraySpecs();
+            List<String> arraySpecs = vf.footer().arraySpecs().stream()
+                    .map(io.github.dfa1.vortex.core.model.EncodingId::id).toList();
             List<SegmentSpec> segmentSpecs = vf.footer().segmentSpecs();
 
             PcoStats stats = new PcoStats();

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

@@ -1,19 +1,23 @@
 package io.github.dfa1.vortex.reader;
 
+import io.github.dfa1.vortex.core.model.EncodingId;
+import io.github.dfa1.vortex.core.model.LayoutId;
+
 import java.util.List;
 
 /// Parsed file footer. Contains the dictionaries needed to resolve indices in the layout tree.
 ///
 /// All spec lists are index-stable: array/layout/segment indices in the tree refer
-/// into these lists by position.
+/// into these lists by position. The wire strings are parsed to their typed ids once here,
+/// at the parse boundary, so array/layout nodes index directly into typed dictionaries.
 ///
-/// @param arraySpecs       encoding id strings indexed by array spec index
-/// @param layoutSpecs      layout type strings indexed by layout spec index
+/// @param arraySpecs       [EncodingId] indexed by array spec index
+/// @param layoutSpecs      [LayoutId] indexed by layout spec index
 /// @param segmentSpecs     segment byte ranges indexed by segment index
 /// @param compressionSpecs compression schemes indexed by compression spec index
 public record Footer(
-        List<String> arraySpecs,
-        List<String> layoutSpecs,
+        List<EncodingId> arraySpecs,
+        List<LayoutId> layoutSpecs,
         List<SegmentSpec> segmentSpecs,
         List<CompressionScheme> compressionSpecs
 ) {

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

@@ -2,6 +2,7 @@
 
 import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.core.io.IoBounds;
+import io.github.dfa1.vortex.core.model.EncodingId;
 import io.github.dfa1.vortex.core.model.LayoutId;
 import io.github.dfa1.vortex.core.model.PType;
 import io.github.dfa1.vortex.core.error.VortexException;
@@ -136,15 +137,43 @@ private static MemorySegment slice(MemorySegment seg, long offset, long length)
         return IoBounds.slice(seg, offset, length);
     }
 
+    /// Parses one array-spec wire string to its [EncodingId] at the footer boundary. A blank id
+    /// is untrusted-input corruption; [EncodingId#parse] would reject it with an
+    /// [IllegalArgumentException], so surface it as a [VortexException] with the spec index.
+    ///
+    /// @param raw   the wire string from the array spec dictionary
+    /// @param index the array spec index, for the error message
+    /// @return the typed [EncodingId]
+    private static EncodingId parseEncodingSpec(String raw, int index) {
+        if (raw.isBlank()) {
+            throw new VortexException("blank encoding id at array spec index " + index);
+        }
+        return EncodingId.parse(raw);
+    }
+
+    /// Parses one layout-spec wire string to its [LayoutId] at the footer boundary. A blank id
+    /// is untrusted-input corruption; [LayoutId#parse] would reject it with an
+    /// [IllegalArgumentException], so surface it as a [VortexException] with the spec index.
+    ///
+    /// @param raw   the wire string from the layout spec dictionary
+    /// @param index the layout spec index, for the error message
+    /// @return the typed [LayoutId]
+    private static LayoutId parseLayoutSpec(String raw, int index) {
+        if (raw.isBlank()) {
+            throw new VortexException("blank layout id at layout spec index " + index);
+        }
+        return LayoutId.parse(raw);
+    }
+
     static Footer convertFooter(io.github.dfa1.vortex.core.fbs.FbsFooter f) {
-        var arraySpecs = new ArrayList<String>(f.arraySpecsLength());
+        var arraySpecs = new ArrayList<EncodingId>(f.arraySpecsLength());
         for (int i = 0; i < f.arraySpecsLength(); i++) {
-            arraySpecs.add(f.arraySpecs(i).id());
+            arraySpecs.add(parseEncodingSpec(f.arraySpecs(i).id(), i));
         }
 
-        var layoutSpecs = new ArrayList<String>(f.layoutSpecsLength());
+        var layoutSpecs = new ArrayList<LayoutId>(f.layoutSpecsLength());
         for (int i = 0; i < f.layoutSpecsLength(); i++) {
-            layoutSpecs.add(f.layoutSpecs(i).id());
+            layoutSpecs.add(parseLayoutSpec(f.layoutSpecs(i).id(), i));
         }
 
         var segmentSpecs = new ArrayList<SegmentSpec>(f.segmentSpecsLength());
@@ -166,7 +195,7 @@ static Footer convertFooter(io.github.dfa1.vortex.core.fbs.FbsFooter f) {
                 List.copyOf(segmentSpecs), List.copyOf(compressionSpecs));
     }
 
-    private static Layout convertLayout(io.github.dfa1.vortex.core.fbs.FbsLayout l, List<String> layoutSpecs, int depth) {
+    private static Layout convertLayout(io.github.dfa1.vortex.core.fbs.FbsLayout l, List<LayoutId> layoutSpecs, int depth) {
         if (depth > MAX_LAYOUT_DEPTH) {
             throw new VortexException(
                     "layout tree depth exceeds limit (" + MAX_LAYOUT_DEPTH + ")");
@@ -177,13 +206,8 @@ private static Layout convertLayout(io.github.dfa1.vortex.core.fbs.FbsLayout l,
                     "layout encoding index " + encIdx
                             + " out of bounds (layoutSpecs.size=" + layoutSpecs.size() + ")");
         }
-        String rawLayoutId = layoutSpecs.get(encIdx);
-        if (rawLayoutId.isBlank()) {
-            // LayoutId.parse rejects blank ids with IllegalArgumentException; the file is
-            // untrusted input, so a blank spec entry must surface as VortexException instead.
-            throw new VortexException("blank layout id at layout spec index " + encIdx);
-        }
-        LayoutId layoutId = LayoutId.parse(rawLayoutId);
+        // Already parsed (and blank-guarded) at the footer boundary.
+        LayoutId layoutId = layoutSpecs.get(encIdx);
 
         MemorySegment metadata = l.metadataAsSegment();
         if (metadata != null && metadata.byteSize() > MAX_LAYOUT_METADATA_BYTES) {

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

@@ -49,12 +49,12 @@ public SerializedArrayDecoder(ReadRegistry registry) {
     /// Decodes a flat segment from a memory-mapped region.
     ///
     /// @param seg           memory-mapped region for the flat segment
-    /// @param encodingSpecs ordered list of encoding id strings from the file's encoding table
+    /// @param encodingSpecs ordered list of [EncodingId] from the file's encoding table
     /// @param dtype         expected logical type for the decoded array
     /// @param rowCount      number of logical rows in this segment
     /// @param arena         allocator for decode output; lifetime matches the current chunk epoch
     /// @return the decoded [Array] for this segment
-    public Array decode(MemorySegment seg, List<String> encodingSpecs,
+    public Array decode(MemorySegment seg, List<EncodingId> encodingSpecs,
             DType dtype, long rowCount, SegmentAllocator arena) {
         int segLen = IoBounds.toIntSize(seg.byteSize());
 
@@ -82,19 +82,15 @@ public Array decode(MemorySegment seg, List<String> encodingSpecs,
 
     private static ArrayNode convertArrayNode(
             io.github.dfa1.vortex.core.fbs.FbsArrayNode fbs,
-            List<String> encodingSpecs,
+            List<EncodingId> encodingSpecs,
             int depth
     ) {
         if (depth > MAX_ARRAY_TREE_DEPTH) {
             throw new VortexException(
                     "array tree depth exceeds limit (" + MAX_ARRAY_TREE_DEPTH + ")");
         }
-        String rawEncodingId = encodingSpecs.get(fbs.encoding());
-        if (rawEncodingId.isBlank()) {
-            // EncodingId.parse rejects blank ids with IllegalArgumentException; the file is
-            // untrusted input, so a blank spec entry must surface as VortexException instead.
-            throw new VortexException("blank encoding id at array spec index " + fbs.encoding());
-        }
+        // Already parsed (and blank-guarded) at the footer boundary.
+        EncodingId encodingId = encodingSpecs.get(fbs.encoding());
 
         ArrayNode[] children = new ArrayNode[fbs.childrenLength()];
         for (int i = 0; i < children.length; i++) {
@@ -107,6 +103,6 @@ private static ArrayNode convertArrayNode(
         }
 
         MemorySegment meta = fbs.metadataAsSegment();
-        return new ArrayNode(EncodingId.parse(rawEncodingId), meta, children, bufferIndices);
+        return new ArrayNode(encodingId, meta, children, bufferIndices);
     }
 }

reader/src/test/java/io/github/dfa1/vortex/reader/ArrayNodeDepthBombSecurityTest.java

@@ -6,6 +6,7 @@
 import io.github.dfa1.vortex.core.fbs.FbsBuilder;
 import io.github.dfa1.vortex.core.io.VortexFormat;
 import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.EncodingId;
 import org.junit.jupiter.api.Test;
 
 import java.lang.foreign.Arena;
@@ -42,7 +43,7 @@ void arrayTreeAtDepthLimit_clearsGuard() {
             MemorySegment seg = wrapAsSegment(fb, arena);
 
             // When / Then
-            assertThatThrownBy(() -> sut.decode(seg, List.of("vortex.flat"), DTYPE, 1, arena))
+            assertThatThrownBy(() -> sut.decode(seg, List.of(EncodingId.parse("vortex.flat")), DTYPE, 1, arena))
                     .isInstanceOf(VortexException.class)
                     .hasMessageContaining("no decoder");
         }
@@ -57,7 +58,7 @@ void arrayTreeOneOverDepthLimit_throwsVortexException() {
             MemorySegment seg = wrapAsSegment(fb, arena);
 
             // When / Then — must surface as VortexException, not StackOverflowError
-            assertThatThrownBy(() -> sut.decode(seg, List.of("vortex.flat"), DTYPE, 1, arena))
+            assertThatThrownBy(() -> sut.decode(seg, List.of(EncodingId.parse("vortex.flat")), DTYPE, 1, arena))
                     .isInstanceOf(VortexException.class)
                     .hasMessageContaining("depth");
         }

reader/src/test/java/io/github/dfa1/vortex/reader/PostscriptParserDTypeGuardsTest.java

@@ -81,8 +81,36 @@ void convertDType_controlCharacterFieldName_throwsVortexException() {
                 .hasMessageContaining("control character U+000A");
     }
 
+    @Test
+    void convertFooter_blankArraySpec_throwsVortexException() {
+        // Given — a footer whose array spec dictionary carries a blank encoding id (a zero-length
+        // FlatBuffer string). Parsing now happens once at the footer boundary, so the blank guard
+        // that used to live in the per-node decoder is exercised here.
+        MemorySegment footer = footerWithArraySpec("");
+        MemorySegment layout = flatLayout();
+        MemorySegment dtype = structDType(new String[]{"a"}, 1);
+
+        // When / Then
+        assertThatThrownBy(() -> PostscriptParser.parseBlobs(footer, layout, dtype))
+                .isInstanceOf(VortexException.class)
+                .hasMessageContaining("blank encoding id at array spec index 0");
+    }
+
     // ── FlatBuffer builders ─────────────────────────────────────────────────────
 
+    private static MemorySegment footerWithArraySpec(String arraySpec) {
+        var fbb = new FbsBuilder(256);
+        int asv = FbsFooter.createArraySpecsVector(fbb, new int[]{
+                FbsArraySpec.createFbsArraySpec(fbb, fbb.createString(arraySpec))});
+        int lsv = FbsFooter.createLayoutSpecsVector(fbb, new int[]{
+                FbsLayoutSpec.createFbsLayoutSpec(fbb, fbb.createString("vortex.flat"))});
+        FbsFooter.startSegmentSpecsVector(fbb, 0);
+        int ssv = fbb.endVector();
+        int footOff = FbsFooter.createFbsFooter(fbb, asv, lsv, ssv, 0, 0);
+        fbb.finish(footOff);
+        return fbb.dataSegment();
+    }
+
     /// Builds a struct dtype blob with the given field names and `dtypeCount` null-typed fields.
     private static MemorySegment structDType(String[] names, int dtypeCount) {
         var fbb = new FbsBuilder(256);

reader/src/test/java/io/github/dfa1/vortex/reader/SerializedArrayBoundsSecurityTest.java

@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.core.io.VortexFormat;
 import io.github.dfa1.vortex.core.fbs.FbsBuilder;
 import io.github.dfa1.vortex.core.model.DType;
+import io.github.dfa1.vortex.core.model.EncodingId;
 import io.github.dfa1.vortex.core.error.VortexException;
 import io.github.dfa1.vortex.core.fbs.FbsArray;
 import io.github.dfa1.vortex.core.fbs.FbsArrayNode;
@@ -25,7 +26,7 @@ class SerializedArrayBoundsSecurityTest {
 
 
     private static final DType DTYPE = DType.I32;
-    private static final List<String> FLAT_SPEC = List.of("vortex.flat");
+    private static final List<EncodingId> FLAT_SPEC = List.of(EncodingId.parse("vortex.flat"));
 
     private final SerializedArrayDecoder sut = new SerializedArrayDecoder(ReadRegistry.empty());