refactor: remove Encoding.decodeSegment(), fix benchmark

Drop the default decodeSegment() method from Encoding — inline
ArraySegments.of(decode(ctx)) at the one call site in EncodingRegistry.
Fix RustWritesJavaReadsBigFileBenchmark using removed arr.buffer(0).
Add API design principle to CLAUDE.md.

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

Author: dfa1

CLAUDE.md

@@ -168,6 +168,11 @@ In every module `pom.xml`, dependencies are grouped with comments:
 
 Omit a section if empty (e.g. integration module has no production deps; performance has no test deps).
 
+## API design
+
+- Keep public interfaces as small as possible.
+- Don't expose internals. When in doubt, leave it out or make it private.
+
 ## Code style
 
 - indents are 4 spaces, enforced by checkstyle

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

@@ -55,10 +55,6 @@ public Array decodeChild(int i, DType dtype, long rowCount) {
 
     /// Recursively decode child {@code i} and return its primary backing segment.
     ///
-    /// <p>Equivalent to {@code decodeChild(i).segment()} but routes through
-    /// {@link Encoding#decodeSegment(DecodeContext)} to avoid the deprecated
-    /// {@link io.github.dfa1.vortex.core.array.Array#segment()} interface method.
-    ///
     /// @param i zero-based child index within this node's children array
     /// @return the primary {@link MemorySegment} of the decoded child
     public MemorySegment decodeChildSegment(int i) {
@@ -69,10 +65,6 @@ public MemorySegment decodeChildSegment(int i) {
 
     /// Recursively decode child {@code i} with an explicit dtype and row count, returning its primary segment.
     ///
-    /// <p>Equivalent to {@code decodeChild(i, dtype, rowCount).segment()} but routes through
-    /// {@link Encoding#decodeSegment(DecodeContext)} to avoid the deprecated
-    /// {@link io.github.dfa1.vortex.core.array.Array#segment()} interface method.
-    ///
     /// @param i        zero-based child index within this node's children array
     /// @param dtype    logical type to assign to the child context
     /// @param rowCount number of logical rows for the child

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

@@ -2,9 +2,6 @@
 
 import io.github.dfa1.vortex.core.DType;
 import io.github.dfa1.vortex.core.array.Array;
-import io.github.dfa1.vortex.core.array.ArraySegments;
-
-import java.lang.foreign.MemorySegment;
 
 /// Combines encode and decode for one encoding type.
 /// Register via [EncodingRegistry] — implementations are discoverable via ServiceLoader.
@@ -34,19 +31,6 @@ public interface Encoding {
     /// @return encode result containing the root node, buffers, and optional stats
     EncodeResult encode(DType dtype, Object data, EncodeContext ctx);
 
-    /// Decodes this encoding and returns the primary backing segment of the result.
-    ///
-    /// <p>Default implementation decodes via {@link #decode(DecodeContext)} and extracts
-    /// the segment via {@link ArraySegments#of(Array)}. Override for efficiency if the
-    /// internal decode can return the buffer directly.
-    ///
-    /// @param ctx decoding context
-    /// @return the primary {@link MemorySegment} of the decoded array
-    /// @throws io.github.dfa1.vortex.core.VortexException if this encoding produces no primary segment
-    default MemorySegment decodeSegment(DecodeContext ctx) {
-        return ArraySegments.of(decode(ctx));
-    }
-
     /// Cascade-aware encode: returns a partial step with open child slots.
     /// Default wraps the terminal {@link #encode} result; override to expose children.
     ///

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

@@ -2,6 +2,7 @@
 
 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 java.lang.foreign.MemorySegment;
@@ -129,7 +130,7 @@ MemorySegment decodeAsSegment(DecodeContext ctx) {
             case UnknownArrayNode _ -> null;
         };
         if (encoding != null) {
-            return encoding.decodeSegment(ctx);
+            return ArraySegments.of(encoding.decode(ctx));
         }
         String id = switch (node) {
             case KnownArrayNode k -> k.encodingId().id();

performance/src/main/java/io/github/dfa1/vortex/performance/RustWritesJavaReadsBigFileBenchmark.java

@@ -9,6 +9,7 @@
 import dev.vortex.arrow.ArrowAllocation;
 import dev.vortex.jni.NativeLoader;
 import io.github.dfa1.vortex.core.array.Array;
+import io.github.dfa1.vortex.core.array.ArraySegments;
 import io.github.dfa1.vortex.encoding.EncodingRegistry;
 import io.github.dfa1.vortex.io.VortexReader;
 import io.github.dfa1.vortex.scan.ScanResult;
@@ -178,7 +179,7 @@ private long scanJava() throws IOException {
             while (iter.hasNext()) {
                 ScanResult r = iter.next();
                 Array arr = r.columns().get("c0");
-                MemorySegment buf = arr.buffer(0);
+                MemorySegment buf = ArraySegments.of(arr);
                 long count = buf.byteSize() / Long.BYTES;
                 for (long i = 0; i < count; i++) {
                     sum += buf.getAtIndex(LE_LONG, i);