refactor: ADR 0001 Phase 1 — move decode types to reader

DecodeContext, ArrayNode (+ KnownArrayNode/UnknownArrayNode), EncodingDecoder,
and FlatSegmentDecoder move from core.encoding to reader.decode / reader.

ReadRegistry replaces Registry.decode() as the canonical read dispatcher.
Registry becomes pure metadata: Encoding descriptors + Extension lookup.

VortexReader, VortexHttpReader, VortexHandle, ScanIterator all take
ReadRegistry instead of Registry. The old decodeAsSegment() escape hatch
on Registry is deleted.

Test infra:
- TestRegistry.ofDecoders(), TestDecodeContexts, DecodeTestHelper move to
  reader/test (new test-jar). Writer/test gains vortex-reader:test-jar dep.
- ReadRegistryTest replaces the decode subset of RegistryTest.
- EncodeTestHelper.toDecodeContext() removed from core; callers use
  DecodeTestHelper.toDecodeContext() from reader/test.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: dfa1

core/src/main/java/io/github/dfa1/vortex/encoding/EncodeNode.java

@@ -3,7 +3,7 @@
 import java.nio.ByteBuffer;
 
 /// Describes the ArrayNode tree written into a flat segment's FlatBuffer.
-/// Mirrors [ArrayNode] for the encode path.
+/// Mirrors ArrayNode for the encode path.
 ///
 /// @param encodingId    encoding id for this node
 /// @param metadata      optional encoding-specific metadata bytes, or {@code null}

core/src/main/java/io/github/dfa1/vortex/encoding/Encoding.java

@@ -4,7 +4,7 @@
 
 /// Metadata-only encoding descriptor. Carries only the wire identifier and the dtype
 /// predicate. No encode or decode logic — those live in {@link EncodingEncoder}
-/// (writer module) and {@link EncodingDecoder} (reader module) respectively.
+/// (writer module) and EncodingDecoder (reader module) respectively.
 ///
 /// <p>Register via {@link Registry} — implementations are discoverable via
 /// {@link java.util.ServiceLoader}.

core/src/main/java/io/github/dfa1/vortex/encoding/EncodingDecoder.java

@@ -91,7 +91,7 @@ public enum EncodingId {
     }
 
     /// Parses a raw encoding id string into the matching constant.
-    /// Used by [Registry] to discriminate [KnownArrayNode] from [UnknownArrayNode];
+    /// Used by {@code ReadRegistry} to discriminate {@code KnownArrayNode} from {@code UnknownArrayNode};
     /// callers that demand a known id chain {@code .orElseThrow(...)}.
     ///
     /// @param id raw encoding id string (e.g. {@code "vortex.primitive"})

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

@@ -1,41 +1,33 @@
 package io.github.dfa1.vortex.encoding;
 
 import io.github.dfa1.vortex.core.VortexException;
-import io.github.dfa1.vortex.core.array.Array;
-import io.github.dfa1.vortex.core.array.ArraySegments;
-import io.github.dfa1.vortex.core.array.UnknownArray;
 import io.github.dfa1.vortex.extension.Extension;
 import io.github.dfa1.vortex.extension.ExtensionId;
 
-import java.lang.foreign.MemorySegment;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 import java.util.ServiceLoader;
 
-/// Registry mapping wire identifiers to their library implementations:
-/// [Encoding] keyed by [EncodingId], [Extension] keyed by [ExtensionId],
-/// and [EncodingDecoder] keyed by [EncodingId].
+/// Metadata registry for {@link Encoding} descriptors and {@link Extension} implementations.
 ///
-/// Instances are immutable after construction. Build one via [#builder()] or via the
-/// [#loadAll()], [#empty()], [#of(List)] convenience factories.
+/// <p>Holds only metadata-only {@link Encoding} objects and {@link Extension} impls.
+/// Decode dispatch lives in {@code ReadRegistry} (reader module); encode dispatch
+/// uses {@code Map<EncodingId, EncodingEncoder>} directly.
+///
+/// <p>Instances are immutable after construction. Build one via {@link #builder()} or via the
+/// {@link #loadAll()}, {@link #empty()}, {@link #of(List)} convenience factories.
 public final class Registry {
 
     private final Map<EncodingId, Encoding> encodings;
     private final Map<ExtensionId, Extension> extensions;
-    private final Map<EncodingId, EncodingDecoder> standaloneDecoders;
-    private final boolean allowUnknown;
 
     private Registry(
             Map<EncodingId, Encoding> encodings,
-            Map<ExtensionId, Extension> extensions,
-            Map<EncodingId, EncodingDecoder> standaloneDecoders,
-            boolean allowUnknown
+            Map<ExtensionId, Extension> extensions
     ) {
         this.encodings = Map.copyOf(encodings);
         this.extensions = Map.copyOf(extensions);
-        this.standaloneDecoders = Map.copyOf(standaloneDecoders);
-        this.allowUnknown = allowUnknown;
     }
 
     /// Returns a new {@link Builder}.
@@ -45,7 +37,7 @@ public static Builder builder() {
         return new Builder();
     }
 
-    /// Load all service-loaded [Encoding]s, [EncodingDecoder]s, and [Extension]s.
+    /// Load all service-loaded {@link Encoding}s and {@link Extension}s.
     ///
     /// @return an immutable {@link Registry} populated with all service-loaded entries
     public static Registry loadAll() {
@@ -71,45 +63,12 @@ public static Registry of(List<Encoding> encodings) {
         return b.build();
     }
 
-    /// Recursively wrap a node and its children as [UnknownArray]. Children of an unknown
-    /// parent are always wrapped unknown regardless of whether their own id is recognised —
-    /// matches Rust `decode_foreign` in `vortex-array/src/serde.rs`.
-    private static UnknownArray decodeUnknown(DecodeContext ctx, ArrayNode node) {
-        String rawId = switch (node) {
-            case KnownArrayNode k -> k.encodingId().id();
-            case UnknownArrayNode u -> u.rawEncodingId();
-        };
-        MemorySegment[] bufs = new MemorySegment[node.bufferIndices().length];
-        for (int i = 0; i < bufs.length; i++) {
-            bufs[i] = ctx.buffer(i);
-        }
-        Array[] children = new Array[node.children().length];
-        for (int i = 0; i < children.length; i++) {
-            ArrayNode childNode = node.children()[i];
-            DecodeContext childCtx = new DecodeContext(
-                    childNode, ctx.dtype(), ctx.rowCount(),
-                    ctx.segmentBuffers(), ctx.registry(), ctx.arena());
-            children[i] = decodeUnknown(childCtx, childNode);
-        }
-        return new UnknownArray(
-                rawId, ctx.dtype(), ctx.rowCount(),
-                node.metadata(), bufs, children);
-    }
-
-    /// Returns whether passthrough decode for unknown encoding ids is enabled.
-    ///
-    /// @return {@code true} if unknown encodings are silently wrapped as {@link io.github.dfa1.vortex.core.array.UnknownArray}
-    public boolean isAllowUnknown() {
-        return allowUnknown;
-    }
-
-    /// Returns {@code true} if an encoding or decoder is registered for the given id.
+    /// Returns {@code true} if a descriptor is registered for the given id.
     ///
     /// @param encodingId the encoding id to query
-    /// @return {@code true} if an {@link Encoding} or {@link EncodingDecoder} is registered
+    /// @return {@code true} if an {@link Encoding} descriptor is registered
     public boolean hasEncoding(EncodingId encodingId) {
-        return encodings.containsKey(encodingId)
-                || standaloneDecoders.containsKey(encodingId);
+        return encodings.containsKey(encodingId);
     }
 
     /// Returns the registered metadata-only encoding for {@code encodingId}, or {@code null}.
@@ -128,71 +87,17 @@ public Extension lookup(ExtensionId extensionId) {
         return extensions.get(extensionId);
     }
 
-    MemorySegment decodeAsSegment(DecodeContext ctx) {
-        ArrayNode node = ctx.node();
-        EncodingDecoder decoder = switch (node) {
-            case KnownArrayNode k -> standaloneDecoders.get(k.encodingId());
-            case UnknownArrayNode _ -> null;
-        };
-        if (decoder != null) {
-            return ArraySegments.of(decoder.decode(ctx));
-        }
-        String id = switch (node) {
-            case KnownArrayNode k -> k.encodingId().id();
-            case UnknownArrayNode u -> u.rawEncodingId();
-        };
-        throw new VortexException("no encoding registered for " + id + " (or encoding has no primary segment)");
-    }
-
-    /// Decodes the array described by {@code ctx}.
-    ///
-    /// @param ctx the decode context
-    /// @return the decoded {@link Array}
-    public Array decode(DecodeContext ctx) {
-        ArrayNode node = ctx.node();
-        EncodingDecoder decoder = switch (node) {
-            case KnownArrayNode k -> standaloneDecoders.get(k.encodingId());
-            case UnknownArrayNode _ -> null;
-        };
-        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 encoding registered for " + id);
-    }
-
-    /// Builder for [Registry].
+    /// Builder for {@link Registry}.
     ///
-    /// Not thread-safe. Build once, use everywhere — the produced [Registry] is immutable.
+    /// Not thread-safe. Build once, use everywhere — the produced {@link Registry} is immutable.
     public static final class Builder {
 
         private final Map<EncodingId, Encoding> encodings = new HashMap<>();
         private final Map<ExtensionId, Extension> extensions = new HashMap<>();
-        private final Map<EncodingId, EncodingDecoder> standaloneDecoders = new HashMap<>();
-        private boolean allowUnknown = false;
 
         private Builder() {
         }
 
-        /// Registers a standalone read-only decoder.
-        ///
-        /// @param decoder the {@link EncodingDecoder} to register
-        /// @return this builder, for chaining
-        /// @throws VortexException if a decoder for the same id is already registered
-        public Builder register(EncodingDecoder decoder) {
-            EncodingDecoder old = standaloneDecoders.put(decoder.encodingId(), decoder);
-            if (old != null) {
-                throw new VortexException("encoding decoder %s already registered".formatted(decoder.encodingId()));
-            }
-            return this;
-        }
-
         /// Registers a metadata-only encoding descriptor.
         ///
         /// @param encoding the {@link Encoding} to register
@@ -219,7 +124,7 @@ public Builder register(Extension extension) {
             return this;
         }
 
-        /// Registers every [Encoding], [EncodingDecoder], and [Extension] discovered via
+        /// Registers every {@link Encoding} and {@link Extension} discovered via
         /// {@link ServiceLoader}.
         ///
         /// @return this builder, for chaining
@@ -231,29 +136,14 @@ public Builder registerServiceLoaded() {
             for (Extension extension : ServiceLoader.load(Extension.class)) {
                 register(extension);
             }
-            for (EncodingDecoder decoder : ServiceLoader.load(EncodingDecoder.class)) {
-                register(decoder);
-            }
-            return this;
-        }
-
-        /// Enable passthrough decode for unknown encoding ids.
-        ///
-        /// Default is strict: unknown ids throw [VortexException]. When enabled, unknown nodes
-        /// (and all their children, recursively) are wrapped as [UnknownArray] preserving raw
-        /// metadata + buffers + stats. Mirrors Rust `VortexSession::allow_unknown()`.
-        ///
-        /// @return this builder, for chaining
-        public Builder allowUnknown() {
-            this.allowUnknown = true;
             return this;
         }
 
-        /// Builds an immutable [Registry].
+        /// Builds an immutable {@link Registry}.
         ///
         /// @return the immutable registry
         public Registry build() {
-            return new Registry(encodings, extensions, standaloneDecoders, allowUnknown);
+            return new Registry(encodings, extensions);
         }
     }
 }

core/src/main/java/io/github/dfa1/vortex/encoding/KnownArrayNode.java

@@ -4,7 +4,7 @@
 
 import java.lang.foreign.MemorySegment;
 
-/// Element-offset helper for child segments returned by [DecodeContext#decodeChildSegment].
+/// Element-offset helper for child segments returned by DecodeContext#decodeChildSegment.
 ///
 /// <p>{@link ConstantEncoding} deliberately stores a single element regardless of the array's
 /// declared {@code rowCount} (zip-bomb defense). Consumers that bulk-read child segments by
@@ -23,7 +23,7 @@ private SegmentBroadcast() {
     /// Returns the byte offset of logical element {@code i} in {@code seg}, broadcasting if
     /// {@code seg} holds fewer elements than {@code i}.
     ///
-    /// @param seg       segment returned by [DecodeContext#decodeChildSegment]
+    /// @param seg       segment returned by DecodeContext#decodeChildSegment
     /// @param i         logical element index in {@code [0, rowCount)}
     /// @param elemBytes element width in bytes (>= 1)
     /// @return byte offset suitable for {@link MemorySegment#get} or
@@ -43,7 +43,7 @@ public static long elementOffset(MemorySegment seg, long i, int elemBytes) {
     /// <p>Used by callers that want to detect the constant case explicitly — e.g. to hoist
     /// a single read out of a hot loop.
     ///
-    /// @param seg       segment returned by [DecodeContext#decodeChildSegment]
+    /// @param seg       segment returned by DecodeContext#decodeChildSegment
     /// @param elemBytes element width in bytes (>= 1)
     /// @return physical element count
     public static long capacity(MemorySegment seg, int elemBytes) {

core/src/main/java/io/github/dfa1/vortex/encoding/Registry.java

@@ -1,13 +1,11 @@
 package io.github.dfa1.vortex.encoding;
 
 import java.lang.foreign.Arena;
-import java.lang.foreign.MemorySegment;
 import java.util.HashMap;
-import java.util.List;
 import java.util.Map;
 import java.util.ServiceLoader;
 
-/// Converts an [EncodeResult] into a [DecodeContext] for roundtrip tests.
+/// Encode-side test utilities.
 ///
 /// Public so reader/ and writer/ test trees can reuse it via the core test-jar.
 public final class EncodeTestHelper {
@@ -27,29 +25,4 @@ public static EncodeContext testCtx() {
         }
         return EncodeContext.of(Arena.ofAuto(), Map.copyOf(encoders));
     }
-
-    /// Wraps a writer's {@link EncodeResult} into a {@link DecodeContext} for round-trip assertions.
-    ///
-    /// @param result   writer output
-    /// @param rowCount logical row count
-    /// @param dtype    decoded dtype
-    /// @param registry registry used for nested decode dispatch
-    /// @return decode context ready for {@link EncodingDecoder#decode}
-    public static DecodeContext toDecodeContext(
-            EncodeResult result, long rowCount, io.github.dfa1.vortex.core.DType dtype,
-            Registry registry
-    ) {
-        List<MemorySegment> buffers = result.buffers();
-        MemorySegment[] segments = buffers.toArray(new MemorySegment[0]);
-        ArrayNode root = toArrayNode(result.rootNode());
-        return new DecodeContext(root, dtype, rowCount, segments, registry, Arena.ofAuto());
-    }
-
-    private static ArrayNode toArrayNode(EncodeNode enc) {
-        ArrayNode[] children = new ArrayNode[enc.children().length];
-        for (int i = 0; i < children.length; i++) {
-            children[i] = toArrayNode(enc.children()[i]);
-        }
-        return ArrayNode.of(enc.encodingId(), enc.metadata(), children, enc.bufferIndices(), null);
-    }
 }