refactor(reader): ExtensionDecoder to extension pkg

Move the ExtensionDecoder interface from the reader root into
reader.extension next to its four implementations, mirroring
EncodingDecoder in reader.decode.

Also sync stale docs: ReadRegistry no longer manages extension
decoders (no register(ExtensionDecoder), no ServiceLoader
discovery) — the spec set is closed and dispatched in Chunk.as().

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

Author: dfa1

CLAUDE.md

@@ -28,12 +28,12 @@ core    — everything lives under `io.github.dfa1.vortex.core.*`:
           core.error    VortexException
           core.compute  FastLanes, PrimitiveArrays
           core.fbs / core.proto — generated wire codecs + their runtimes
-reader  — VortexReader, VortexHttpReader, VortexHandle, ReadRegistry, ExtensionDecoder,
-          Chunk, ArrayStats, ScanOptions, RowFilter; file internals (Footer, Layout, Trailer,
+reader  — VortexReader, VortexHttpReader, VortexHandle, ReadRegistry, Chunk, ArrayStats,
+          ScanOptions, RowFilter; file internals (Footer, Layout, Trailer,
           PostscriptParser, …)
           reader.array  — Array + all subtypes (decode outputs)
           reader.decode — EncodingDecoder, DecodeContext, ArrayNode + *EncodingDecoder impls
-          reader.extension — Date/Time/Timestamp/Uuid ExtensionDecoder
+          reader.extension — ExtensionDecoder + Date/Time/Timestamp/Uuid impls
 writer  — VortexWriter, WriteRegistry, WriteOptions, ExtensionEncoder
           writer.encode — EncodingEncoder, EncodeContext, NullableData + *EncodingEncoder impls,
           extension encoders
@@ -135,9 +135,9 @@ Add `EncodingId` enum constant `VORTEX_FOO("vortex.foo")`, then per side:
 ### Adding an extension type
 
 Add `ExtensionId` constant, then per side:
-- **Decode:** `FooExtensionDecoder implements ExtensionDecoder` in `reader.extension`; register via
-  `ReadRegistry.builder().register(new FooExtensionDecoder())` — **no service file**
-  (`registerServiceLoaded()` does not discover `ExtensionDecoder`).
+- **Decode:** singleton `FooExtensionDecoder implements ExtensionDecoder` in `reader.extension` +
+  a `case VORTEX_FOO` in `Chunk.as()` — not registry-managed, **no service file**
+  (`registerServiceLoaded()` only discovers `EncodingDecoder`).
 - **Encode:** `FooExtensionEncoder implements ExtensionEncoder` in `writer` + FQN in
   `writer/.../META-INF/services/io.github.dfa1.vortex.writer.ExtensionEncoder`
 

docs/reference.md

@@ -203,14 +203,14 @@ Immutable after construction. Build via `ReadRegistry.builder()` or the static c
 | Method                       | Notes                                                                                    |
 |------------------------------|------------------------------------------------------------------------------------------|
 | `register(EncodingDecoder)`  | Add a custom encoding decoder; throws if already registered                              |
-| `register(ExtensionDecoder)` | Add a custom extension decoder; throws if already registered                             |
-| `registerServiceLoaded()`    | Add every `EncodingDecoder` and `ExtensionDecoder` discovered via `ServiceLoader`        |
+| `registerServiceLoaded()`    | Add every `EncodingDecoder` discovered via `ServiceLoader`                               |
 | `allowUnknown()`             | Switch to passthrough mode — unknown nodes (and their children) decode as `UnknownArray` |
 | `build()`                    | Produce the immutable `ReadRegistry`                                                     |
 
-Register custom decoders via `ServiceLoader` by adding the fully qualified class name to
-`META-INF/services/io.github.dfa1.vortex.reader.decode.EncodingDecoder` or
-`META-INF/services/io.github.dfa1.vortex.reader.ExtensionDecoder`.
+Register custom encoding decoders via `ServiceLoader` by adding the fully qualified class name to
+`META-INF/services/io.github.dfa1.vortex.reader.decode.EncodingDecoder`. Extension decoders
+(`io.github.dfa1.vortex.reader.extension.ExtensionDecoder`) are not registry-managed: the built-in
+implementations are singletons invoked directly by their `ExtensionId`.
 
 ---
 

reader/src/main/java/io/github/dfa1/vortex/reader/extension/DateExtensionDecoder.java

@@ -8,7 +8,6 @@
 import io.github.dfa1.vortex.reader.array.MaskedArray;
 import io.github.dfa1.vortex.core.model.ExtensionId;
 
-import io.github.dfa1.vortex.reader.ExtensionDecoder;
 
 import java.time.LocalDate;
 import java.util.ArrayList;

…dfa1/vortex/reader/ExtensionDecoder.java …x/reader/extension/ExtensionDecoder.javareader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java renamed to reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionDecoder.java reader/src/main/java/io/github/dfa1/vortex/reader/ExtensionDecoder.java renamed to reader/src/main/java/io/github/dfa1/vortex/reader/extension/ExtensionDecoder.java

@@ -1,4 +1,4 @@
-package io.github.dfa1.vortex.reader;
+package io.github.dfa1.vortex.reader.extension;
 
 import io.github.dfa1.vortex.core.model.DType;
 import io.github.dfa1.vortex.core.model.ExtensionId;

reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimeExtensionDecoder.java

@@ -9,7 +9,6 @@
 import io.github.dfa1.vortex.core.model.ExtensionId;
 import io.github.dfa1.vortex.core.model.TimeDtype;
 
-import io.github.dfa1.vortex.reader.ExtensionDecoder;
 
 import java.time.LocalTime;
 import java.util.ArrayList;

reader/src/main/java/io/github/dfa1/vortex/reader/extension/TimestampExtensionDecoder.java

@@ -9,7 +9,6 @@
 import io.github.dfa1.vortex.core.model.ExtensionId;
 import io.github.dfa1.vortex.core.model.TimestampDtype;
 
-import io.github.dfa1.vortex.reader.ExtensionDecoder;
 
 import java.time.Instant;
 import java.time.ZoneId;

reader/src/main/java/io/github/dfa1/vortex/reader/extension/UuidExtensionDecoder.java

@@ -9,7 +9,6 @@
 import io.github.dfa1.vortex.reader.array.MaskedArray;
 import io.github.dfa1.vortex.core.model.ExtensionId;
 
-import io.github.dfa1.vortex.reader.ExtensionDecoder;
 
 import java.util.ArrayList;
 import java.util.List;