refactor(core): ADR 0001 Phase 5 — split Extension write surface

Extension no longer extends ExtensionEncoder. Four *ExtensionEncoder
impls in writer/encode/ carry encodeAll; WriteRegistry and VortexWriter
updated to load ExtensionEncoder via ServiceLoader. ExtensionStorage
made public for cross-module access.

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

Author: dfa1

core/src/main/java/io/github/dfa1/vortex/extension/DateExtension.java

@@ -2,13 +2,10 @@
 
 import io.github.dfa1.vortex.core.DType;
 import io.github.dfa1.vortex.core.PType;
-import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.array.Array;
-import io.github.dfa1.vortex.core.array.NullableData;
 
 import java.time.LocalDate;
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.List;
 
 /// {@code vortex.date} — days since the Unix epoch, signed integer storage.
@@ -77,45 +74,4 @@ public int encode(LocalDate value) {
         return Math.toIntExact(value.toEpochDay());
     }
 
-    /// Encodes a collection of dates into the storage layout the writer accepts
-    /// for an I32 column (a primitive {@code int[]} in row order).
-    ///
-    /// @param values dates to encode
-    /// @return packed {@code int[]} suitable for {@code writer.writeChunk}
-    /// @throws ArithmeticException if any date is too far from the epoch to fit in I32
-    public int[] encodeAll(Collection<LocalDate> values) {
-        int[] out = new int[values.size()];
-        int i = 0;
-        for (LocalDate v : values) {
-            out[i++] = encode(v);
-        }
-        return out;
-    }
-
-    @Override
-    @SuppressWarnings("unchecked")
-    public Object encodeAll(DType.Extension dtype, Collection<?> values) {
-        Collection<LocalDate> typed = (Collection<LocalDate>) values;
-        int n = typed.size();
-        int[] out = new int[n];
-        boolean[] validity = new boolean[n];
-        boolean anyNull = false;
-        int i = 0;
-        for (LocalDate v : typed) {
-            if (v == null) {
-                anyNull = true;
-            } else {
-                out[i] = encode(v);
-                validity[i] = true;
-            }
-            i++;
-        }
-        if (!anyNull) {
-            return out;
-        }
-        if (!dtype.nullable()) {
-            throw new VortexException("null element in non-nullable vortex.date column");
-        }
-        return new NullableData(out, validity);
-    }
 }

core/src/main/java/io/github/dfa1/vortex/extension/Extension.java

@@ -2,21 +2,24 @@
 
 import io.github.dfa1.vortex.core.DType;
 
-/// Contract for a Vortex extension type — pairs the wire-format identity
-/// (an [ExtensionId]) with a factory for the matching [DType.Extension]
-/// dtype. Behaviour-specific decode methods live on each concrete
-/// implementation, not on this interface, so read callers get typed
-/// return values without casting through {@code Object}.
+/// Read-side contract for a Vortex extension type — pairs the wire-format
+/// identity (an [ExtensionId]) with a factory for the matching [DType.Extension]
+/// dtype. Behaviour-specific decode methods live on each concrete implementation,
+/// not on this interface, so read callers get typed return values without casting
+/// through {@code Object}.
 ///
-/// <p>Extends {@link ExtensionEncoder} so existing bifunctional implementations
-/// satisfy both contracts unchanged; ADR 0001 Phase 5 progressively peels the
-/// write-side {@code encodeAll} surface into standalone {@link ExtensionEncoder}
-/// implementations living in the writer module.
-public interface Extension extends ExtensionEncoder {
+/// <p>The write-side surface ({@code encodeAll}) lives on
+/// {@link ExtensionEncoder} implementations in the {@code writer} module.
+public interface Extension {
+
+    /// @return the spec identity of this extension
+    ExtensionId extensionId();
+
+    /// @param nullable whether the column allows nulls
+    /// @return matching {@link DType.Extension} (storage dtype + default metadata)
+    DType.Extension dtype(boolean nullable);
 
     /// Resolves a {@link DType.Extension} to its spec-defined singleton.
-    /// Closes over the closed-set spec impls; third-party extensions go
-    /// through {@link io.github.dfa1.vortex.encoding.Registry#lookup(ExtensionId)}.
     ///
     /// @param dtype declared extension dtype
     /// @return matching spec extension singleton, or empty when the wire id

core/src/main/java/io/github/dfa1/vortex/extension/ExtensionStorage.java

@@ -13,8 +13,8 @@
 import java.nio.ByteBuffer;
 import java.time.Instant;
 
-/// Shared decode helpers for the {@link Extension} implementations in this package.
-final class ExtensionStorage {
+/// Low-level storage helpers shared by extension decode and encode paths.
+public final class ExtensionStorage {
 
     private ExtensionStorage() {
     }
@@ -27,7 +27,7 @@ private ExtensionStorage() {
     /// @param i       row index
     /// @return cell value as long
     /// @throws VortexException if storage isn't an integer primitive or the cell is null
-    static long epochInteger(Array storage, long i) {
+    public static long epochInteger(Array storage, long i) {
         return switch (storage) {
             case ByteArray a -> a.getByte(i);
             case ShortArray a -> a.getShort(i);
@@ -50,7 +50,7 @@ static long epochInteger(Array storage, long i) {
     /// @param ext declared extension dtype
     /// @return decoded time unit
     /// @throws VortexException if the metadata is missing
-    static TimeUnit readUnit(DType.Extension ext) {
+    public static TimeUnit readUnit(DType.Extension ext) {
         ByteBuffer meta = ext.metadata();
         if (meta == null || !meta.hasRemaining()) {
             throw new VortexException("missing TimeUnit metadata byte for " + ext.extensionId());
@@ -64,7 +64,7 @@ static TimeUnit readUnit(DType.Extension ext) {
     /// @param unit time resolution; must not be {@link TimeUnit#Days}
     /// @return matching {@link Instant}
     /// @throws VortexException if {@code unit} is {@link TimeUnit#Days}
-    static Instant instantFromRaw(long raw, TimeUnit unit) {
+    public static Instant instantFromRaw(long raw, TimeUnit unit) {
         return switch (unit) {
             case Seconds -> Instant.ofEpochSecond(raw);
             case Milliseconds -> Instant.ofEpochMilli(raw);
@@ -86,7 +86,7 @@ static Instant instantFromRaw(long raw, TimeUnit unit) {
     ///
     /// @param i      row index to check
     /// @param length array length
-    static void checkBounds(long i, long length) {
+    public static void checkBounds(long i, long length) {
         if (i < 0 || i >= length) {
             throw new IndexOutOfBoundsException("index " + i + " out of bounds for length " + length);
         }

core/src/main/java/io/github/dfa1/vortex/extension/TimeExtension.java

@@ -4,13 +4,11 @@
 import io.github.dfa1.vortex.core.PType;
 import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.array.Array;
-import io.github.dfa1.vortex.core.array.NullableData;
 import io.github.dfa1.vortex.encoding.TimeUnit;
 
 import java.nio.ByteBuffer;
 import java.time.LocalTime;
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.List;
 
 /// {@code vortex.time} — sub-day count in the {@link TimeUnit} recorded in the metadata byte.
@@ -110,83 +108,4 @@ public long encode(LocalTime value, TimeUnit unit) {
         return value.toNanoOfDay() / divisor;
     }
 
-    /// Encodes a collection of times into the storage layout matching the unit:
-    /// {@code int[]} for {@link TimeUnit#Seconds}/{@link TimeUnit#Milliseconds},
-    /// {@code long[]} for {@link TimeUnit#Microseconds}/{@link TimeUnit#Nanoseconds}.
-    /// Return type is {@code Object} so the writer can switch on the array type.
-    ///
-    /// @param values times to encode
-    /// @param unit   resolution; controls storage width
-    /// @return {@code int[]} or {@code long[]} suitable for {@code writer.writeChunk}
-    /// @throws VortexException if {@code unit} is {@link TimeUnit#Days}
-    public Object encodeAll(Collection<LocalTime> values, TimeUnit unit) {
-        return switch (unit) {
-            case Seconds, Milliseconds -> {
-                int[] out = new int[values.size()];
-                int i = 0;
-                for (LocalTime v : values) {
-                    out[i++] = Math.toIntExact(encode(v, unit));
-                }
-                yield out;
-            }
-            case Microseconds, Nanoseconds -> {
-                long[] out = new long[values.size()];
-                int i = 0;
-                for (LocalTime v : values) {
-                    out[i++] = encode(v, unit);
-                }
-                yield out;
-            }
-            case Days -> throw new VortexException("Time.encodeAll: Days unit not valid for vortex.time");
-        };
-    }
-
-    @Override
-    @SuppressWarnings("unchecked")
-    public Object encodeAll(DType.Extension dtype, Collection<?> values) {
-        TimeUnit unit = ExtensionStorage.readUnit(dtype);
-        Collection<LocalTime> typed = (Collection<LocalTime>) values;
-        int n = typed.size();
-        boolean[] validity = new boolean[n];
-        boolean anyNull = false;
-        Object out;
-        int i = 0;
-        switch (unit) {
-            case Seconds, Milliseconds -> {
-                int[] arr = new int[n];
-                for (LocalTime v : typed) {
-                    if (v == null) {
-                        anyNull = true;
-                    } else {
-                        arr[i] = Math.toIntExact(encode(v, unit));
-                        validity[i] = true;
-                    }
-                    i++;
-                }
-                out = arr;
-            }
-            case Microseconds, Nanoseconds -> {
-                long[] arr = new long[n];
-                for (LocalTime v : typed) {
-                    if (v == null) {
-                        anyNull = true;
-                    } else {
-                        arr[i] = encode(v, unit);
-                        validity[i] = true;
-                    }
-                    i++;
-                }
-                out = arr;
-            }
-            case Days -> throw new VortexException("Time.encodeAll: Days unit not valid for vortex.time");
-            default -> throw new VortexException("unknown TimeUnit: " + unit);
-        }
-        if (!anyNull) {
-            return out;
-        }
-        if (!dtype.nullable()) {
-            throw new VortexException("null element in non-nullable vortex.time column");
-        }
-        return new NullableData(out, validity);
-    }
 }

core/src/main/java/io/github/dfa1/vortex/extension/TimestampExtension.java

@@ -2,9 +2,7 @@
 
 import io.github.dfa1.vortex.core.DType;
 import io.github.dfa1.vortex.core.PType;
-import io.github.dfa1.vortex.core.VortexException;
 import io.github.dfa1.vortex.core.array.Array;
-import io.github.dfa1.vortex.core.array.NullableData;
 import io.github.dfa1.vortex.encoding.TimeUnit;
 
 import java.nio.ByteBuffer;
@@ -14,7 +12,6 @@
 import java.time.ZoneId;
 import java.time.ZonedDateTime;
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
 
@@ -160,46 +157,4 @@ public long encode(Instant value, TimeUnit unit) {
         };
     }
 
-    /// Encodes a collection of instants into a packed {@code long[]} matching
-    /// the I64 storage layout the writer accepts.
-    ///
-    /// @param values instants to encode
-    /// @param unit   resolution
-    /// @return packed {@code long[]} suitable for {@code writer.writeChunk}
-    public long[] encodeAll(Collection<Instant> values, TimeUnit unit) {
-        long[] out = new long[values.size()];
-        int i = 0;
-        for (Instant v : values) {
-            out[i++] = encode(v, unit);
-        }
-        return out;
-    }
-
-    @Override
-    @SuppressWarnings("unchecked")
-    public Object encodeAll(DType.Extension dtype, Collection<?> values) {
-        TimeUnit unit = ExtensionStorage.readUnit(dtype);
-        Collection<Instant> typed = (Collection<Instant>) values;
-        int n = typed.size();
-        long[] out = new long[n];
-        boolean[] validity = new boolean[n];
-        boolean anyNull = false;
-        int i = 0;
-        for (Instant v : typed) {
-            if (v == null) {
-                anyNull = true;
-            } else {
-                out[i] = encode(v, unit);
-                validity[i] = true;
-            }
-            i++;
-        }
-        if (!anyNull) {
-            return out;
-        }
-        if (!dtype.nullable()) {
-            throw new VortexException("null element in non-nullable vortex.timestamp column");
-        }
-        return new NullableData(out, validity);
-    }
 }

core/src/main/java/io/github/dfa1/vortex/extension/UuidExtension.java

@@ -8,7 +8,6 @@
 import io.github.dfa1.vortex.core.array.FixedSizeListArray;
 
 import java.util.ArrayList;
-import java.util.Collection;
 import java.util.List;
 import java.util.UUID;
 
@@ -110,59 +109,4 @@ public byte[] encode(UUID value) {
         return out;
     }
 
-    /// Encodes a collection of UUIDs into a flat {@code byte[]} of size {@code 16 * n},
-    /// matching the {@code FixedSizeList(U8, 16)} storage layout.
-    ///
-    /// @param values UUIDs to encode
-    /// @return packed bytes; the writer slices it into 16-byte rows
-    public byte[] encodeAll(Collection<UUID> values) {
-        byte[] out = new byte[16 * values.size()];
-        int off = 0;
-        for (UUID v : values) {
-            long msb = v.getMostSignificantBits();
-            long lsb = v.getLeastSignificantBits();
-            for (int k = 0; k < 8; k++) {
-                out[off + k] = (byte) ((msb >> (56 - 8 * k)) & 0xff);
-                out[off + 8 + k] = (byte) ((lsb >> (56 - 8 * k)) & 0xff);
-            }
-            off += 16;
-        }
-        return out;
-    }
-
-    @Override
-    @SuppressWarnings("unchecked")
-    public Object encodeAll(DType.Extension dtype, Collection<?> values) {
-        Collection<UUID> typed = (Collection<UUID>) values;
-        int n = typed.size();
-        byte[] flat = new byte[16 * n];
-        boolean[] validity = new boolean[n];
-        boolean anyNull = false;
-        int row = 0;
-        for (UUID v : typed) {
-            if (v == null) {
-                anyNull = true;
-            } else {
-                long msb = v.getMostSignificantBits();
-                long lsb = v.getLeastSignificantBits();
-                int off = row * 16;
-                for (int k = 0; k < 8; k++) {
-                    flat[off + k] = (byte) ((msb >> (56 - 8 * k)) & 0xff);
-                    flat[off + 8 + k] = (byte) ((lsb >> (56 - 8 * k)) & 0xff);
-                }
-                validity[row] = true;
-            }
-            row++;
-        }
-        io.github.dfa1.vortex.encoding.FixedSizeListData storage =
-                new io.github.dfa1.vortex.encoding.FixedSizeListData(flat, n);
-        if (!anyNull) {
-            return storage;
-        }
-        if (!dtype.nullable()) {
-            throw new io.github.dfa1.vortex.core.VortexException(
-                    "null element in non-nullable vortex.uuid column");
-        }
-        return new io.github.dfa1.vortex.core.array.NullableData(storage, validity);
-    }
 }