fix(reader,writer): actionable error when zstd binding is absent

The io.github.dfa1.zstd binding is optional; a file using
vortex.zstd read without it surfaced as NoClassDefFoundError from
the first binding call. Both codecs now probe availability once
(Class.forName, no Error catching) and fail with a VortexException
naming the two artifacts to add. Verified end-to-end: a real
vortex.zstd file written with the binding reads fine with it and
produces the actionable message without it; default write/read
paths never touch the binding (probed with the jars absent).

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

Author: dfa1

CHANGELOG.md

@@ -31,6 +31,7 @@ claim measured against the Rust (JNI) oracle; behavior divergences documented in
 
 ### Changed
 
+- The zstd binding stays a two-artifact opt-in (`io.github.dfa1.zstd:zstd` + `zstd-platform`, both `optional`; no JNI anywhere), and touching `vortex.zstd` without it now fails with an actionable `VortexException` naming the two artifacts to add, instead of a raw `NoClassDefFoundError`. Default write/read paths never touch the binding (measured). ([pending-zstd](https://github.com/dfa1/vortex-java/commits/main))
 - The little-endian `ValueLayout` constants moved from `PTypeIO.LE_*` to `VortexFormat.LE_*` — endianness is a property of the wire format, not of ptypes, and `VortexFormat` is where format facts live. Six classes that carried private copies (including reversed-name duplicates like `SHORT_LE`) now share the single source; nothing outside `VortexFormat` defines a `withOrder(LITTLE_ENDIAN)` layout. ([c060d34f](https://github.com/dfa1/vortex-java/commit/c060d34f))
 - `Chunk.columns()` returns an order-preserving `SequencedMap<ColumnName, Chunk.Column>` — one map instead of two parallel string-keyed maps, with each column's `Array` and `DType` traveling together in the `Column` carrier. `column(String)` stays as boundary sugar (plus a `column(ColumnName)` overload); iteration order is the schema/projection order, now guaranteed even for 1–2 column chunks. Typed names originate in `ScanIterator` from the file's already-certified schema. ([f8ad15d1](https://github.com/dfa1/vortex-java/commit/f8ad15d1))
 

docs/compatibility.md

@@ -23,6 +23,11 @@ A consumer that only needs to read Vortex files can depend on a strict subset:
 </dependency>
 ```
 
+The zstd binding is optional on both sides: files using `vortex.zstd` need
+`io.github.dfa1.zstd:zstd` plus `io.github.dfa1.zstd:zstd-platform` on the classpath (versions
+pinned by the vortex BOM); without them, touching a `vortex.zstd` segment fails with a
+`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.

reader/src/main/java/io/github/dfa1/vortex/reader/decode/ZstdEncodingDecoder.java

@@ -29,6 +29,21 @@
 /// Read-only decoder for `vortex.zstd`.
 public final class ZstdEncodingDecoder implements EncodingDecoder {
 
+    // The io.github.dfa1.zstd binding is an OPTIONAL dependency: probe once so a reader
+    // touching vortex.zstd without it gets an actionable message instead of a raw
+    // NoClassDefFoundError surfacing from the first binding call.
+    private static final boolean ZSTD_BINDING_PRESENT = zstdBindingPresent();
+
+    private static boolean zstdBindingPresent() {
+        try {
+            Class.forName("io.github.dfa1.zstd.ZstdDecompressContext", false,
+                    ZstdEncodingDecoder.class.getClassLoader());
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        }
+    }
+
     /// Public no-arg constructor required by [java.util.ServiceLoader].
     public ZstdEncodingDecoder() {
     }
@@ -40,6 +55,11 @@ public EncodingId encodingId() {
 
     @Override
     public Array decode(DecodeContext ctx) {
+        if (!ZSTD_BINDING_PRESENT) {
+            throw new VortexException(EncodingId.VORTEX_ZSTD, "this file uses vortex.zstd, but the "
+                    + "optional zstd binding is not on the classpath — add io.github.dfa1.zstd:zstd "
+                    + "and io.github.dfa1.zstd:zstd-platform (versions pinned by the vortex BOM)");
+        }
         MemorySegment rawMeta = ctx.metadata();
         if (rawMeta == null) {
             throw new VortexException(EncodingId.VORTEX_ZSTD, "missing metadata");

writer/src/main/java/io/github/dfa1/vortex/writer/encode/ZstdEncodingEncoder.java

@@ -26,6 +26,21 @@
 /// frames let a slice scan decompress only the frames overlapping its row range.
 public final class ZstdEncodingEncoder implements EncodingEncoder {
 
+    // The io.github.dfa1.zstd binding is an OPTIONAL dependency: probe once so a writer
+    // touching vortex.zstd without it gets an actionable message instead of a raw
+    // NoClassDefFoundError surfacing from the first binding call.
+    private static final boolean ZSTD_BINDING_PRESENT = zstdBindingPresent();
+
+    private static boolean zstdBindingPresent() {
+        try {
+            Class.forName("io.github.dfa1.zstd.ZstdCompressContext", false,
+                    ZstdEncodingEncoder.class.getClassLoader());
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        }
+    }
+
     /// Values per zstd frame; `0` (or any non-positive value) means a single frame for the whole array.
     private final long valuesPerFrame;
 
@@ -62,6 +77,11 @@ public boolean acceptsNullable(DType dtype) {
 
     @Override
     public EncodeResult encode(DType dtype, Object data, EncodeContext ctx) {
+        if (!ZSTD_BINDING_PRESENT) {
+            throw new VortexException(EncodingId.VORTEX_ZSTD, "vortex.zstd encoding requires the "
+                    + "optional zstd binding — add io.github.dfa1.zstd:zstd and "
+                    + "io.github.dfa1.zstd:zstd-platform (versions pinned by the vortex BOM)");
+        }
         if (data instanceof NullableData nd) {
             if (dtype instanceof DType.Primitive dt) {
                 return encodeNullablePrimitive(dt, nd, ctx);