refactor(encoding): split Encoding into Decoder + Encoder interfaces [Phase 1/6]

Encoding is now a marker that extends EncodingDecoder + EncodingEncoder.
The two narrower interfaces carry the read-side and write-side method
signatures (encodingId + accepts + decode for decoders; encodingId +
accepts + encode + encodeCascade for encoders).

Every existing Encoding implementation continues to satisfy both
contracts without code changes, so the migration is transparent at this
phase. Read-only call sites (ReadRegistry, FlatSegmentDecoder) can
already type-narrow to EncodingDecoder; write-only call sites
(VortexWriter, CascadingCompressor) can type-narrow to EncodingEncoder.

Later phases lift one encoding family at a time into separate
*EncodingDecoder and *EncodingEncoder implementations that live in
the reader and writer modules respectively; once the last family is
lifted, the bifunctional Encoding interface is removed.

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

Author: dfa1

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

@@ -1,44 +1,11 @@
 package io.github.dfa1.vortex.encoding;
 
-import io.github.dfa1.vortex.core.DType;
-import io.github.dfa1.vortex.core.array.Array;
-
-/// Combines encode and decode for one encoding type.
-/// Register via [Registry] — implementations are discoverable via ServiceLoader.
-public interface Encoding {
-    /// Returns the encoding id for this encoding.
-    ///
-    /// @return encoding id
-    EncodingId encodingId();
-
-    /// Decodes an array node from the file using the provided context.
-    ///
-    /// @param ctx decoding context containing buffers, dtype, row count, and child registry
-    /// @return decoded array
-    Array decode(DecodeContext ctx);
-
-    /// Returns `true` if this encoding can encode the given dtype.
-    ///
-    /// @param dtype the dtype to test
-    /// @return `true` if this encoding accepts `dtype`
-    boolean accepts(DType dtype);
-
-    /// Encodes {@code data} to bytes using the provided arena for output buffer allocation.
-    ///
-    /// @param dtype logical type of the data
-    /// @param data  the data to encode (type depends on encoding; typically a primitive array)
-    /// @param ctx   encoding context supplying the arena for output buffer allocation
-    /// @return encode result containing the root node, buffers, and optional stats
-    EncodeResult encode(DType dtype, Object data, EncodeContext ctx);
-
-    /// Cascade-aware encode: returns a partial step with open child slots.
-    /// Default wraps the terminal {@link #encode} result; override to expose children.
-    ///
-    /// @param dtype the logical type of the data
-    /// @param data  the data to encode
-    /// @param ctx   encoding context supplying the arena, registry, and cascade parameters
-    /// @return cascade step with optional open child slots
-    default CascadeStep encodeCascade(DType dtype, Object data, EncodeContext ctx) {
-        return CascadeStep.terminal(encode(dtype, data, ctx));
-    }
+/// Bifunctional encoding interface that combines the read-side {@link EncodingDecoder}
+/// surface and the write-side {@link EncodingEncoder} surface. Existing implementations
+/// satisfy both contracts on a single class; ADR 0001 progressively peels these apart
+/// so that a read-only deployment carries only decoders.
+///
+/// <p>Register via {@link Registry} — implementations are discoverable via
+/// {@link java.util.ServiceLoader}.
+public interface Encoding extends EncodingDecoder, EncodingEncoder {
 }

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

@@ -0,0 +1,28 @@
+package io.github.dfa1.vortex.encoding;
+
+import io.github.dfa1.vortex.core.DType;
+import io.github.dfa1.vortex.core.array.Array;
+
+/// Read-side surface of an encoding. Exposes only the metadata required to dispatch
+/// a decode and the {@link #decode(DecodeContext)} entry point itself.
+///
+/// <p>ADR 0001 Phase 1: {@link Encoding} now extends this interface for backward
+/// compatibility while encoding implementations are still bifunctional. Later phases
+/// peel encoder implementations into a separate write runtime, at which point
+/// {@code EncodingDecoder} becomes the canonical read-side type and lives in the
+/// {@code reader} module.
+public interface EncodingDecoder {
+
+    /// @return the wire identifier of this encoding
+    EncodingId encodingId();
+
+    /// @param dtype the dtype to test
+    /// @return {@code true} if this encoding can decode arrays of {@code dtype}
+    boolean accepts(DType dtype);
+
+    /// Decodes an array node from the file using the provided context.
+    ///
+    /// @param ctx decoding context containing buffers, dtype, row count, and child registry
+    /// @return decoded array
+    Array decode(DecodeContext ctx);
+}

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

@@ -0,0 +1,41 @@
+package io.github.dfa1.vortex.encoding;
+
+import io.github.dfa1.vortex.core.DType;
+
+/// Write-side surface of an encoding. Exposes only the metadata required to pick an
+/// encoder for a dtype and the {@link #encode(DType, Object, EncodeContext)} entry
+/// point itself.
+///
+/// <p>ADR 0001 Phase 1: {@link Encoding} now extends this interface for backward
+/// compatibility while encoding implementations are still bifunctional. Later phases
+/// peel encoder implementations into a separate write runtime, at which point
+/// {@code EncodingEncoder} becomes the canonical write-side type and lives in the
+/// {@code writer} module.
+public interface EncodingEncoder {
+
+    /// @return the wire identifier of this encoding
+    EncodingId encodingId();
+
+    /// @param dtype the dtype to test
+    /// @return {@code true} if this encoding can encode arrays of {@code dtype}
+    boolean accepts(DType dtype);
+
+    /// Encodes {@code data} to bytes using the provided arena for output buffer allocation.
+    ///
+    /// @param dtype logical type of the data
+    /// @param data  the data to encode (type depends on encoding; typically a primitive array)
+    /// @param ctx   encoding context supplying the arena for output buffer allocation
+    /// @return encode result containing the root node, buffers, and optional stats
+    EncodeResult encode(DType dtype, Object data, EncodeContext ctx);
+
+    /// Cascade-aware encode: returns a partial step with open child slots.
+    /// Default wraps the terminal {@link #encode} result; override to expose children.
+    ///
+    /// @param dtype the logical type of the data
+    /// @param data  the data to encode
+    /// @param ctx   encoding context supplying the arena, registry, and cascade parameters
+    /// @return cascade step with optional open child slots
+    default CascadeStep encodeCascade(DType dtype, Object data, EncodeContext ctx) {
+        return CascadeStep.terminal(encode(dtype, data, ctx));
+    }
+}