refactor(reader): ArrayNode carries the typed EncodingId

Collapse the KnownArrayNode/UnknownArrayNode sealed pair into a
single ArrayNode record: with EncodingId sealed, the Known/Unknown
bit lives in the id type (WellKnown vs Custom), so the parallel
node hierarchy and its switch dances at every dispatch site encode
nothing. ReadRegistry returns to the single string-keyed map hit;
the allowUnknown passthrough and error messages are unchanged for
both former variants. The redundant ArrayNode.of factory is gone —
the canonical constructor takes the typed id.

Hardening from review: a crafted file with a blank encoding id in
the spec table now fails as VortexException in FlatSegmentDecoder
(EncodingId.parse rejects blank with IllegalArgumentException,
which must not escape the untrusted read path — previously "" flowed
to the unknown-id path and could pass through allowUnknown);
WriteRegistry's builder TreeMap orders by wire string instead of
natural ordering, which a Custom-keyed registration would break.

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

Author: dfa1

core/src/main/java/io/github/dfa1/vortex/core/model/EncodingId.java

@@ -22,11 +22,15 @@ public sealed interface EncodingId extends Serializable permits EncodingId.WellK
     /// @return the wire string of this encoding id
     String id();
 
-    /// Total parse: every non-null string has a typed representation.
-    /// Returns the matching [WellKnown] constant, else a [Custom] wrapping the raw string.
+    /// Parses a wire string into its typed representation: the matching [WellKnown] constant,
+    /// else a [Custom] wrapping the raw string. Total over every non-blank string; blank input
+    /// is not a valid encoding id and is rejected by the [Custom] constructor — callers parsing
+    /// untrusted input must guard blank ids and raise their own domain error.
     ///
     /// @param raw the raw encoding id string (e.g. `"vortex.primitive"`)
     /// @return the matching [WellKnown] constant, or a [Custom] wrapping `raw` if none matches
+    /// @throws NullPointerException if `raw` is `null`
+    /// @throws IllegalArgumentException if `raw` is blank
     static EncodingId parse(String raw) {
         WellKnown known = WellKnown.byId(raw);
         return known != null ? known : new Custom(raw);

core/src/test/java/io/github/dfa1/vortex/core/model/EncodingIdTest.java

@@ -4,6 +4,7 @@
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.EnumSource;
+import org.junit.jupiter.params.provider.ValueSource;
 
 import static org.assertj.core.api.Assertions.assertThat;
 import static org.assertj.core.api.Assertions.assertThatThrownBy;
@@ -33,6 +34,15 @@ void parse_unknownId_returnsCustomWrappingRawId() {
             assertThat(result).isEqualTo(new EncodingId.Custom(raw));
             assertThat(result.id()).isEqualTo(raw);
         }
+
+        @ParameterizedTest
+        @ValueSource(strings = {"", " ", "   "})
+        void parse_blankId_throwsIllegalArgumentException(String blank) {
+            // Given / When / Then — blank is not a valid id; parse must not silently wrap it,
+            // so untrusted-input callers are forced to guard it into their own domain error
+            assertThatThrownBy(() -> EncodingId.parse(blank))
+                    .isInstanceOf(IllegalArgumentException.class);
+        }
     }
 
     @Nested

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

@@ -10,8 +10,6 @@
 import io.github.dfa1.vortex.core.fbs.FbsBuffer;
 import io.github.dfa1.vortex.reader.decode.ArrayNode;
 import io.github.dfa1.vortex.reader.decode.DecodeContext;
-import io.github.dfa1.vortex.reader.decode.KnownArrayNode;
-import io.github.dfa1.vortex.reader.decode.UnknownArrayNode;
 
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.SegmentAllocator;
@@ -87,6 +85,11 @@ private static ArrayNode convertArrayNode(
                     "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());
+        }
 
         ArrayNode[] children = new ArrayNode[fbs.childrenLength()];
         for (int i = 0; i < children.length; i++) {
@@ -99,11 +102,6 @@ private static ArrayNode convertArrayNode(
         }
 
         MemorySegment meta = fbs.metadataAsSegment();
-        return switch (EncodingId.parse(rawEncodingId)) {
-            case EncodingId.WellKnown wellKnown ->
-                    new KnownArrayNode(wellKnown, meta, children, bufferIndices);
-            case EncodingId.Custom custom ->
-                    new UnknownArrayNode(custom.id(), meta, children, bufferIndices);
-        };
+        return new ArrayNode(EncodingId.parse(rawEncodingId), meta, children, bufferIndices);
     }
 }

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

@@ -7,8 +7,6 @@
 import io.github.dfa1.vortex.reader.decode.ArrayNode;
 import io.github.dfa1.vortex.reader.decode.DecodeContext;
 import io.github.dfa1.vortex.reader.decode.EncodingDecoder;
-import io.github.dfa1.vortex.reader.decode.KnownArrayNode;
-import io.github.dfa1.vortex.reader.decode.UnknownArrayNode;
 
 import java.lang.foreign.MemorySegment;
 import java.util.Collections;
@@ -76,21 +74,14 @@ public boolean hasDecoder(EncodingId encodingId) {
     /// @return the decoded [Array]
     public Array decode(DecodeContext ctx) {
         ArrayNode node = ctx.node();
-        EncodingDecoder decoder = switch (node) {
-            case KnownArrayNode k -> decoders.get(k.encodingId().id());
-            case UnknownArrayNode _ -> null;
-        };
+        EncodingDecoder decoder = decoders.get(node.encodingId().id());
         if (decoder != null) {
             return decoder.decode(ctx);
         }
         if (allowUnknown) {
             return decodeUnknown(ctx, node);
         }
-        String id = switch (node) {
-            case KnownArrayNode k -> k.encodingId().id();
-            case UnknownArrayNode u -> u.rawEncodingId();
-        };
-        throw new VortexException("no decoder registered for " + id);
+        throw new VortexException("no decoder registered for " + node.encodingId().id());
     }
 
     /// Decodes the array described by `ctx` and returns its primary backing segment.
@@ -99,25 +90,16 @@ public Array decode(DecodeContext ctx) {
     /// @return the primary [MemorySegment] of the decoded array
     public MemorySegment decodeAsSegment(DecodeContext ctx) {
         ArrayNode node = ctx.node();
-        EncodingDecoder decoder = switch (node) {
-            case KnownArrayNode k -> decoders.get(k.encodingId().id());
-            case UnknownArrayNode _ -> null;
-        };
+        EncodingDecoder decoder = decoders.get(node.encodingId().id());
         if (decoder != null) {
             return decoder.decode(ctx).materialize(ctx.arena());
         }
-        String id = switch (node) {
-            case KnownArrayNode k -> k.encodingId().id();
-            case UnknownArrayNode u -> u.rawEncodingId();
-        };
-        throw new VortexException("no decoder registered for " + id + " (or encoding has no primary segment)");
+        throw new VortexException("no decoder registered for " + node.encodingId().id()
+                + " (or encoding has no primary segment)");
     }
 
     private static UnknownArray decodeUnknown(DecodeContext ctx, ArrayNode node) {
-        String rawId = switch (node) {
-            case KnownArrayNode k -> k.encodingId().id();
-            case UnknownArrayNode u -> u.rawEncodingId();
-        };
+        String rawId = node.encodingId().id();
         MemorySegment[] bufs = new MemorySegment[node.bufferIndices().length];
         for (int i = 0; i < bufs.length; i++) {
             bufs[i] = ctx.buffer(i);

reader/src/main/java/io/github/dfa1/vortex/reader/decode/ArrayNode.java

@@ -4,40 +4,26 @@
 
 import java.lang.foreign.MemorySegment;
 
-/// Encoded array node as stored in a Flat layout segment.
-/// In-file representation before decoding; mirrors the Go ArrayNode struct.
+/// Encoded array node as stored in a Flat layout segment — the in-file representation before
+/// decoding.
 ///
-/// Sealed: a node is either [KnownArrayNode] (id resolves to an [EncodingId.WellKnown]) or
-/// [UnknownArrayNode] (id is an arbitrary string only meaningful for
-/// [io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()] passthrough decode).
-public sealed interface ArrayNode permits KnownArrayNode, UnknownArrayNode {
-
-    /// Factory that builds the right node kind for `encodingId`: a [KnownArrayNode] for a
-    /// well-known id, or an [UnknownArrayNode] for a [EncodingId.Custom] one.
-    /// Mostly used by tests and helper code that converts an `EncodeNode` tree back into
-    /// an `ArrayNode` tree.
-    ///
-    /// @param encodingId    the encoding identifier
-    /// @param metadata      encoding-specific metadata bytes, or `null`
-    /// @param children      child nodes
-    /// @param bufferIndices segment buffer indices for this node
-    /// @return a [KnownArrayNode] for a well-known id, else an [UnknownArrayNode]
-    static ArrayNode of(EncodingId encodingId, MemorySegment metadata, ArrayNode[] children,
-            int[] bufferIndices) {
-        return switch (encodingId) {
-            case EncodingId.WellKnown wellKnown ->
-                    new KnownArrayNode(wellKnown, metadata, children, bufferIndices);
-            case EncodingId.Custom custom ->
-                    new UnknownArrayNode(custom.id(), metadata, children, bufferIndices);
-        };
-    }
-
-    /// @return encoding-specific metadata bytes, or `null`
-    MemorySegment metadata();
-
-    /// @return child nodes
-    ArrayNode[] children();
-
-    /// @return segment buffer indices for this node
-    int[] bufferIndices();
+/// The encoding id is carried typed, as either an [EncodingId.WellKnown] constant or an
+/// [EncodingId.Custom] wrapping a raw wire string, so the Known/Unknown distinction lives in the id
+/// itself rather than in a node subtype. Whether an id is decodable is a separate,
+/// decode-time question owned by the [io.github.dfa1.vortex.reader.ReadRegistry], not a property of
+/// the node: an [EncodingId.Custom] id, or a [EncodingId.WellKnown] id no registered decoder
+/// claims, either decodes as a passthrough [io.github.dfa1.vortex.reader.array.UnknownArray] (when
+/// [io.github.dfa1.vortex.reader.ReadRegistry#isAllowUnknown()] is set) or fails the decode.
+///
+/// @param encodingId    the encoding identifier, [EncodingId.WellKnown] or [EncodingId.Custom]
+/// @param metadata      encoding-specific metadata bytes, or `null`
+/// @param children      child nodes
+/// @param bufferIndices segment buffer indices for this node
+@SuppressWarnings("java:S6218") // internal data carrier; record components are arrays of immutable primitives or refs that flow through pipelines without ever being compared.
+public record ArrayNode(
+        EncodingId encodingId,
+        MemorySegment metadata,
+        ArrayNode[] children,
+        int[] bufferIndices
+) {
 }

reader/src/main/java/io/github/dfa1/vortex/reader/decode/KnownArrayNode.java

@@ -3,6 +3,7 @@
 import io.github.dfa1.vortex.core.fbs.FbsArrayNode;
 import io.github.dfa1.vortex.core.fbs.FbsBuffer;
 import io.github.dfa1.vortex.core.fbs.FbsBuilder;
+import io.github.dfa1.vortex.core.error.VortexException;
 import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.reader.array.Array;
 import io.github.dfa1.vortex.reader.array.UnknownArray;
@@ -14,15 +15,16 @@
 
 import static io.github.dfa1.vortex.core.io.PTypeIO.LE_INT;
 import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.catchThrowable;
 
 /// Successful flat-segment decode path — complements [FlatSegmentBoundsSecurityTest] (which only
 /// drives the rejection paths). A buffer descriptor with non-zero padding exercises the offset
-/// walk, and an unknown encoding id exercises the `UnknownArrayNode` fallback through an
+/// walk, and an unknown encoding id exercises the unknown-id passthrough through an
 /// allow-unknown registry. Together these pin two otherwise-untested spots:
 /// - the `dataOffset += padding` accumulation: with padding > 0, flipping `+=` to `-=` slices at a
 ///   negative offset and fails, so a clean decode proves the addition.
-/// - the `orElseGet(() -> new UnknownArrayNode(...))` fallback: returning `null` there yields a
-///   null node and the decode would not produce an `UnknownArray`.
+/// - the unknown-id node construction: mishandling an unresolvable id there yields a
+///   node the decode would not turn into an `UnknownArray`.
 class FlatSegmentDecoderDecodeTest {
 
     @Test
@@ -46,11 +48,36 @@ void decode_unknownEncodingWithBufferPadding_returnsUnknownArray() {
                     DType.I32, 0, arena);
 
             // Then — the allow-unknown path produced an UnknownArray (proves both the +padding
-            // walk and the UnknownArrayNode fallback ran)
+            // walk and the unknown-id passthrough ran)
             assertThat(result).isInstanceOf(UnknownArray.class);
         }
     }
 
+    @Test
+    void decode_blankEncodingId_throwsVortexException() {
+        ReadRegistry registry = ReadRegistry.builder().allowUnknown().build();
+        FlatSegmentDecoder sut = new FlatSegmentDecoder(registry);
+
+        try (Arena arena = Arena.ofConfined()) {
+            // Given — a zero-length FlatBuffer string in the spec table decodes to "", which
+            // EncodingId.parse rejects with IllegalArgumentException; untrusted input must
+            // surface as VortexException instead, even under allowUnknown
+            byte[] fb = arrayFlatBufferOneBuffer(0, 0L);
+            MemorySegment seg = arena.allocate((long) fb.length + 4);
+            MemorySegment.copy(MemorySegment.ofArray(fb), 0, seg, 0, fb.length);
+            seg.set(LE_INT, fb.length, fb.length);
+
+            // When
+            Throwable result = catchThrowable(() -> sut.decode(seg, List.of(""),
+                    DType.I32, 0, arena));
+
+            // Then
+            assertThat(result)
+                    .isInstanceOf(VortexException.class)
+                    .hasMessageContaining("blank encoding id");
+        }
+    }
+
     /// Builds an `Array` FlatBuffer with a single buffer descriptor of the given padding/length.
     private static byte[] arrayFlatBufferOneBuffer(int padding, long length) {
         FbsBuilder b = new FbsBuilder();

reader/src/main/java/io/github/dfa1/vortex/reader/decode/UnknownArrayNode.java

@@ -8,7 +8,6 @@
 import io.github.dfa1.vortex.reader.decode.ArrayNode;
 import io.github.dfa1.vortex.reader.decode.DecodeContext;
 import io.github.dfa1.vortex.reader.decode.EncodingDecoder;
-import io.github.dfa1.vortex.reader.decode.UnknownArrayNode;
 import org.junit.jupiter.api.Test;
 
 import java.lang.foreign.Arena;
@@ -25,7 +24,7 @@ class ReadRegistryTest {
     void decodeUnknownEncodingThrowsByDefault() {
         // Given
         ReadRegistry sut = ReadRegistry.empty();
-        ArrayNode node = new UnknownArrayNode("some.unknown",
+        ArrayNode node = new ArrayNode(EncodingId.parse("some.unknown"),
                 MemorySegment.ofArray(new byte[0]), new ArrayNode[0], new int[0]);
         DecodeContext ctx = new DecodeContext(node, DTypes.I32, 0L,
                 new MemorySegment[0], sut, Arena.ofAuto());
@@ -40,7 +39,7 @@ void decodeUnknownEncodingThrowsByDefault() {
     void decodeKnownEncodingWithoutDecoderThrowsByDefault() {
         // Given — EncodingId is known but no decoder registered for it
         ReadRegistry sut = ReadRegistry.empty();
-        ArrayNode node = ArrayNode.of(EncodingId.VORTEX_PRIMITIVE,
+        ArrayNode node = new ArrayNode(EncodingId.VORTEX_PRIMITIVE,
                 MemorySegment.ofArray(new byte[0]), new ArrayNode[0], new int[0]);
         DecodeContext ctx = new DecodeContext(node, DTypes.I32, 0L,
                 new MemorySegment[0], sut, Arena.ofAuto());
@@ -55,7 +54,7 @@ void decodeKnownEncodingWithoutDecoderThrowsByDefault() {
     void decodeKnownEncodingWithoutDecoderReturnsUnknownArrayWhenAllowed() {
         // Given
         ReadRegistry sut = ReadRegistry.builder().allowUnknown().build();
-        ArrayNode node = ArrayNode.of(EncodingId.VORTEX_PRIMITIVE,
+        ArrayNode node = new ArrayNode(EncodingId.VORTEX_PRIMITIVE,
                 MemorySegment.ofArray(new byte[0]), new ArrayNode[0], new int[0]);
         DecodeContext ctx = new DecodeContext(node, DTypes.I32, 0L,
                 new MemorySegment[0], sut, Arena.ofAuto());
@@ -75,7 +74,7 @@ void decodeUnknownEncodingReturnsUnknownArrayWhenAllowed() {
         MemorySegment metadata = MemorySegment.ofArray(new byte[]{1, 2, 3});
         MemorySegment buf = Arena.ofAuto().allocate(4);
         buf.set(java.lang.foreign.ValueLayout.JAVA_INT, 0, 42);
-        ArrayNode node = new UnknownArrayNode("some.unknown",
+        ArrayNode node = new ArrayNode(EncodingId.parse("some.unknown"),
                 metadata, new ArrayNode[0], new int[]{0});
         DecodeContext ctx = new DecodeContext(node, DTypes.I32, 5L,
                 new MemorySegment[]{buf}, sut, Arena.ofAuto());
@@ -101,9 +100,9 @@ void decodeUnknownEncodingWrapsChildrenAsUnknown() {
         ReadRegistry sut = ReadRegistry.builder().allowUnknown().build();
         // Child uses a known id; allow-unknown still wraps it unknown because
         // its parent is unknown — mirrors Rust decode_foreign in vortex-array/src/serde.rs:380.
-        ArrayNode child = ArrayNode.of(EncodingId.VORTEX_PRIMITIVE,
+        ArrayNode child = new ArrayNode(EncodingId.VORTEX_PRIMITIVE,
                 MemorySegment.ofArray(new byte[0]), new ArrayNode[0], new int[0]);
-        ArrayNode parent = new UnknownArrayNode("some.unknown",
+        ArrayNode parent = new ArrayNode(EncodingId.parse("some.unknown"),
                 MemorySegment.ofArray(new byte[0]), new ArrayNode[]{child}, new int[0]);
         DecodeContext ctx = new DecodeContext(parent, DTypes.I32, 0L,
                 new MemorySegment[0], sut, Arena.ofAuto());