refactor: drop ServiceLoader SPI from ReadRegistry and WriteRegistry (#255)

Both registries are now builder-only, consistent with LayoutRegistry.
Built-in decoders/encoders are registered explicitly via registerDefaults()
instead of META-INF/services discovery. loadAll() delegates to
builder().registerDefaults().build().

Also adds VarBinArrayTest coverage for all codes-ptype branches in
forEachI32OffsetByteLength (U8/U16/U32/I64/U64 + unsupported-ptype throw),
fixing the Sonar new_coverage gate.

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

Author: dfa1

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- `ReadRegistry` and `WriteRegistry` are now builder-only (no `ServiceLoader`), matching `LayoutRegistry`. `registerServiceLoaded()` is replaced by `registerDefaults()`, which registers all built-in encoders/decoders explicitly; `loadAll()` is unchanged. `ReadRegistry.decoderMap()` is added. Custom encodings register via `register(...)` on the builder instead of a `META-INF/services` file. ([#255](https://github.com/dfa1/vortex-java/issues/255))
+
 ### Fixed
 
 - `VarBinArray.DictMode` reads dict-value offsets in a ptype-uniform loop: the I32 fast path eliminates the per-row `switch(dictValOffPType)` that blocked C2 vectorization (introduced by #215). ([#243](https://github.com/dfa1/vortex-java/issues/243))

CLAUDE.md

@@ -124,25 +124,25 @@ Layout tree: `Struct → Zoned(Stats) → Chunked → [Flat, Flat, ...]`
 - **Zoned** (`vortex.stats`; reads also accept the newer Rust alias `vortex.zoned`) wraps a child with per-chunk min/max for zone-map pruning
 
 Encoding IDs are strings (`"vortex.primitive"`, `"fastlanes.bitpacked"`). `ReadRegistry` maps IDs →
-`EncodingDecoder` via `ServiceLoader`; immutable after construction — register custom decoders on
-the builder: `ReadRegistry.builder().registerServiceLoaded().register(myDecoder).build()`.
+`EncodingDecoder`; immutable after construction, built-in decoders are registered explicitly by
+`registerDefaults()` — register custom decoders on the builder:
+`ReadRegistry.builder().registerDefaults().register(myDecoder).build()`.
 
 ### Adding an encoding
 
 Add an `EncodingId.WellKnown` constant `VORTEX_FOO("vortex.foo")` (re-exported on the interface), then per side:
-- **Decode:** `FooEncodingDecoder implements EncodingDecoder` in `reader.decode` + FQN in
-  `reader/.../META-INF/services/io.github.dfa1.vortex.reader.decode.EncodingDecoder`
-- **Encode:** `FooEncodingEncoder implements EncodingEncoder` in `writer.encode` + FQN in
-  `writer/.../META-INF/services/io.github.dfa1.vortex.writer.encode.EncodingEncoder`
+- **Decode:** `FooEncodingDecoder implements EncodingDecoder` in `reader.decode` + a
+  `.register(new FooEncodingDecoder())` call in `ReadRegistry.Builder#registerDefaults()`
+- **Encode:** `FooEncodingEncoder implements EncodingEncoder` in `writer.encode` + a
+  `.register(new FooEncodingEncoder())` call in `WriteRegistry.Builder#registerDefaults()`
 
 ### Adding an extension type
 
 Add `ExtensionId` constant, then per side:
 - **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`
+  a `case VORTEX_FOO` in `Chunk.as()` — not registry-managed.
+- **Encode:** `FooExtensionEncoder implements ExtensionEncoder` in `writer` + a
+  `.register(FooExtensionEncoder.INSTANCE)` call in `WriteRegistry.Builder#registerDefaults()`
 
 ## Memory model
 
@@ -204,17 +204,18 @@ When stuck on encode/decode behavior, consult **in this order**:
 
 - **DType is pluggable only via `Extension`.** `DType` is a sealed interface; downstream code must
   not add variants. Use `new DType.Extension("ip.address", new DType.Primitive(PType.I32, false),
-  null, false)` and register decoders/encoders on the registries (or `ServiceLoader<ExtensionEncoder>`).
+  null, false)` and register decoders/encoders on the registries.
   Mirrors Rust (`vortex.date`, `vortex.uuid`, …). No SPI for DType variants planned.
-- **Layout decode is pluggable via `LayoutDecoder` + `LayoutRegistry`** (`reader.layout`) — the
-  Rust reference registers layouts at runtime, so ours are open too. Builder-registered only
-  (`LayoutRegistry.builder().registerDefaults().register(custom).build()`, pass to
-  `VortexReader.open(path, readRegistry, layoutRegistry)`) — **no service file**, by decision:
-  Rust registers layouts explicitly on the session (no auto-discovery exists there), and a
-  classpath jar must not silently change scan traversal — layout registration stays visible at
-  the open() call site. Encodings keep ServiceLoader because they are leaf codecs with a
-  plausible drop-in-jar ecosystem. Unknown layouts
-  fail loudly (`VortexException`, Rust default; no allowUnknown for layouts). Scope: the SPI covers
+- **Encoding and layout decode are both pluggable via builder-only registries** — no
+  `ServiceLoader`. Encodings register on `ReadRegistry`/`WriteRegistry`
+  (`ReadRegistry.builder().registerDefaults().register(custom).build()`); layouts register on
+  `LayoutRegistry` (`LayoutRegistry.builder().registerDefaults().register(custom).build()`, pass to
+  `VortexReader.open(path, readRegistry, layoutRegistry)`). Builder-registered only, by decision:
+  the Rust reference registers encodings and layouts explicitly on the session (no auto-discovery
+  exists there), and a classpath jar must not silently change decode/scan behavior — registration
+  stays visible at the `open()`/`create()` call site. Unknown encodings can be opted into an
+  allow-unknown passthrough (`ReadRegistry.Builder#allowUnknown()`); unknown layouts always fail
+  loudly (`VortexException`, Rust default; no allowUnknown for layouts). Scope: the layout SPI covers
   full-column subtree decode; zone-map pruning, filtered scans, and chunk planning recognize the
   built-in layouts only.
 - **Small public APIs.** Don't expose internals — when in doubt, leave it out or make it private.

README.md

@@ -66,7 +66,7 @@ line-by-line diff is zero.
 <dependency>
   <groupId>io.github.dfa1.vortex</groupId>
   <artifactId>vortex-reader</artifactId>
-  <version>0.11.0</version>
+  <version>0.12.1</version>
 </dependency>
 ```
 
@@ -99,7 +99,7 @@ try (VortexReader vf = VortexReader.open(Path.of("data/example.vortex"));
 <dependency>
   <groupId>io.github.dfa1.vortex</groupId>
   <artifactId>vortex-writer</artifactId>
-  <version>0.11.0</version>
+  <version>0.12.1</version>
 </dependency>
 ```
 

calcite/src/test/java/io/github/dfa1/vortex/calcite/UnsignedColumnTest.java

@@ -114,7 +114,7 @@ private static WriteOptions noZoneMaps() {
     }
 
     private static ReadRegistry registry() {
-        return ReadRegistry.builder().registerServiceLoaded().build();
+        return ReadRegistry.builder().registerDefaults().build();
     }
 
     private static List<Object[]> drain(VortexTable table) {

calcite/src/test/java/io/github/dfa1/vortex/calcite/VortexAdapterCoverageTest.java

@@ -74,7 +74,7 @@ static void write() throws Exception {
     }
 
     private static ReadRegistry registry() {
-        return ReadRegistry.builder().registerServiceLoaded().build();
+        return ReadRegistry.builder().registerDefaults().build();
     }
 
     @Test

docs/compatibility.md

@@ -12,14 +12,14 @@ A consumer that only needs to read Vortex files can depend on a strict subset:
 <dependency>
   <groupId>io.github.dfa1.vortex</groupId>
   <artifactId>vortex-reader</artifactId>
-  <version>0.11.0</version>
+  <version>0.12.1</version>
 </dependency>
 
 <!-- optional: inspector for layout-tree introspection -->
 <dependency>
   <groupId>io.github.dfa1.vortex</groupId>
   <artifactId>vortex-inspector</artifactId>
-  <version>0.11.0</version>
+  <version>0.12.1</version>
 </dependency>
 ```
 
@@ -29,8 +29,8 @@ pinned by the vortex BOM); without them, touching a `vortex.zstd` segment fails
 `VortexException` that names the two artifacts. All other encodings are pure Java.
 
 `./mvnw -pl core,reader,inspector verify` builds the read-only artifact set
-without the writer module on the classpath. `ServiceLoader<EncodingDecoder>`
-resolves only the standalone decoders in `reader`; no encoder class is loaded.
+without the writer module on the classpath. `ReadRegistry.loadAll()` registers
+only the built-in decoders in `reader`; no encoder class is loaded.
 
 ## Known wire-format gaps
 
@@ -172,7 +172,7 @@ passthrough mode to read such files without failing:
 
 ```java
 ReadRegistry registry = ReadRegistry.builder()
-        .registerServiceLoaded()
+        .registerDefaults()
         .allowUnknown()
         .build();
 try (VortexReader vf = VortexReader.open(path, registry)) {

docs/explanation.md

@@ -403,12 +403,11 @@ writer.close()
 
 ### How `ReadRegistry` resolves encodings
 
-`ReadRegistry.loadAll()` uses `ServiceLoader` to discover all `EncodingDecoder`
-implementations on the classpath. Each decoder declares its identity via `encodingId()`.
-At decode time the registry maps the typed id from the array node to the right
-`EncodingDecoder` instance and calls `decode(DecodeContext)`.
+`ReadRegistry.loadAll()` registers all built-in `EncodingDecoder` implementations. Each
+decoder declares its identity via `encodingId()`. At decode time the registry maps the typed
+id from the array node to the right `EncodingDecoder` instance and calls `decode(DecodeContext)`.
 
-Custom decoders can be added at build time: `ReadRegistry.builder().registerServiceLoaded().register(myDecoder).build()`.
+Custom decoders can be added at build time: `ReadRegistry.builder().registerDefaults().register(myDecoder).build()`.
 Files with unrecognized IDs throw `VortexException` unless the builder enabled `allowUnknown()`.
 
 ## Testing strategy

docs/how-to.md

@@ -304,7 +304,7 @@ import io.github.dfa1.vortex.reader.ReadRegistry;
 import io.github.dfa1.vortex.reader.array.UnknownArray;
 
 ReadRegistry registry = ReadRegistry.builder()
-        .registerServiceLoaded()
+        .registerDefaults()
         .allowUnknown()
         .build();
 

docs/reference.md

@@ -209,7 +209,7 @@ Immutable after construction. Build via `ReadRegistry.builder()` or the static c
 | Method                      | Notes                                                                        |
 |-----------------------------|------------------------------------------------------------------------------|
 | `static builder()`          | Returns a fresh `Builder`                                                    |
-| `static loadAll()`          | Immutable registry populated via `ServiceLoader`                             |
+| `static loadAll()`          | Immutable registry populated with all built-in decoders                      |
 | `static empty()`            | Immutable empty registry (strict mode)                                       |
 | `hasDecoder(EncodingId)`    | Lookup                                                                       |
 | `isAllowUnknown()`          | Predicate                                                                    |
@@ -219,12 +219,12 @@ Immutable after construction. Build via `ReadRegistry.builder()` or the static c
 | Method                       | Notes                                                                                    |
 |------------------------------|------------------------------------------------------------------------------------------|
 | `register(EncodingDecoder)`  | Add a custom encoding decoder; throws if already registered                              |
-| `registerServiceLoaded()`    | Add every `EncodingDecoder` discovered via `ServiceLoader`                               |
+| `registerDefaults()`         | Add every built-in `EncodingDecoder`                                                     |
 | `allowUnknown()`             | Switch to passthrough mode — unknown nodes (and their children) decode as `UnknownArray` |
 | `build()`                    | Produce the immutable `ReadRegistry`                                                     |
 
-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
+Register custom encoding decoders programmatically via `register(EncodingDecoder)` — there is no
+`ServiceLoader` discovery. Extension decoders
 (`io.github.dfa1.vortex.reader.extension.ExtensionDecoder`) are not registry-managed: the built-in
 implementations are singletons invoked directly by their `ExtensionId`.
 

docs/testing.md

@@ -190,8 +190,8 @@ Two [architectural fitness functions](https://www.thoughtworks.com/insights/book
 - `DocsConsistencyTest` — **accuracy**: FQNs resolve, method claims name real methods,
   `META-INF/services` mentions exist, relative links don't dangle.
 - `EncodingTableFitnessTest` — **completeness**: the encodings table in `docs/compatibility.md`
-  lists exactly the encodings the code registers via `ServiceLoader` (id, decoder/encoder class,
-  ✅/❌ flags), asserted not generated — on drift it prints the exact rows to add.
+  lists exactly the encodings the code registers in `ReadRegistry`/`WriteRegistry` (id,
+  decoder/encoder class, ✅/❌ flags), asserted not generated — on drift it prints the exact rows to add.
 
 ## Docs consistency gate