feat: typed errors — ZstdException.code()

Callers can branch on the kind of failure instead of matching message text.

- ZstdErrorCode enum mirrors ZSTD_ErrorCode; values read from the vendored
  zstd_errors.h (zstd calls these unstable across versions, but the source is
  pinned, so they are stable for a given release), with UNKNOWN for unmapped
- ZstdException gains code(); Zstd.call attaches it via ZSTD_getErrorCode
- bind ZSTD_getErrorCode; compatibility.md now 44/186

Tests: DST_SIZE_TOO_SMALL on undersized buffer; PARAMETER_OUT_OF_BOUND on a bad
windowLog; a real native category (not UNKNOWN) for garbage input; enum of()
maps known values and falls back to UNKNOWN.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dfa1

docs/compatibility.md

@@ -5,7 +5,7 @@ and semantics follow the [official manual](https://facebook.github.io/zstd/doc/a
 
 - zstd version: **1.6.0** (vendored `third_party/zstd`)
 - Public symbols exported by `libzstd`: **186**
-- Bound so far: **43** (~23%)
+- Bound so far: **44** (~24%)
 
 "Bound" means the symbol has a `MethodHandle` in `Bindings` and is reachable
 through the public Java API. The rest are reachable from native code but not yet
@@ -21,7 +21,7 @@ low-level variants that an idiomatic Java API does not need.
 |---|:---:|---|
 | Core one-shot | 6 / 7 | compress/decompress/bound/levels — complete for practical use |
 | Version | 2 / 2 | complete |
-| Errors | 2 / 4 | name-based; typed `getErrorCode`/`getErrorString` not bound |
+| Errors | 3 / 4 | name + typed `ZstdErrorCode` (via `getErrorCode`); `getErrorString` not bound |
 | Reusable contexts | 6 / 8 | CCtx/DCtx create/free/compress/decompress |
 | Dictionary — simple | 8 / 23 | raw + digested (CDict/DDict); `_advanced`/`_byReference` variants not bound |
 | Dictionary training (ZDICT) | 4 / 12 | `trainFromBuffer`; cover/fastCover optimizers not bound |
@@ -57,14 +57,15 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_compress2`, `ZSTD_CCtx_setParameter` | `ZstdCompressCtx.parameter` / `checksum` / `longDistanceMatching` / `windowLog` (+ `ZstdCompressParameter`) |
 | `ZSTD_CCtx_loadDictionary`, `ZSTD_DCtx_loadDictionary` | `ZstdOutputStream` / `ZstdInputStream` dictionary constructors |
 | `ZSTD_isFrame`, `ZSTD_findFrameCompressedSize`, `ZSTD_decompressBound`, `ZSTD_getDictID_fromFrame` | `ZstdFrame` |
+| `ZSTD_getErrorCode` | `ZstdException.code()` (+ `ZstdErrorCode`) |
 
 ## Roadmap (priority order)
 
 1. ~~**Streaming**~~ — done: `ZstdOutputStream` / `ZstdInputStream` (`compressStream2`, `decompressStream`, bounded buffers, dictionary constructors). Remaining: `MemorySegment`-buffer driver, `pledgedSrcSize`.
 2. **Advanced parameters** — done for compression: `CCtx_setParameter` + `compress2` via `ZstdCompressCtx` (`checksum`, `longDistanceMatching`, `windowLog`, generic `parameter`). Remaining: `cParam_getBounds`, `pledgedSrcSize`, and `nbWorkers` (needs a multithreaded native build).
 3. **Frame inspection** — done: `ZstdFrame` (`isFrame`, `compressedSize`, `decompressedBound`, `dictId`). Remaining: `getFrameHeader` (struct out-param), skippable frames, `getDictID_fromDict/CDict/DDict`.
 4. **Better dictionaries** — `ZDICT_optimizeTrainFromBuffer_cover` / `_fastCover`, `finalizeDictionary`.
-5. **Typed errors** — `ZSTD_getErrorCode` / `ZSTD_getErrorString`.
+5. ~~**Typed errors**~~ — done: `ZstdException.code()` returns `ZstdErrorCode` (via `getErrorCode`).
 
 ## Full symbol table
 
@@ -89,13 +90,13 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_versionNumber` | ✅ |
 | `ZSTD_versionString` | ✅ |
 
-### Errors (2/4)
+### Errors (3/4)
 
 | Symbol | Bound |
 |---|:---:|
 | `ZSTD_getErrorName` | ✅ |
 | `ZSTD_isError` | ✅ |
-| `ZSTD_getErrorCode` | — |
+| `ZSTD_getErrorCode` | ✅ |
 | `ZSTD_getErrorString` | — |
 
 ### Reusable contexts (6/8)

zstd/src/main/java/io/github/dfa1/zstdffm/Bindings.java

@@ -60,6 +60,10 @@ final class Bindings {
     static final MethodHandle GET_ERROR_NAME =
             NativeLibrary.lookup("ZSTD_getErrorName", FunctionDescriptor.of(ADDRESS, JAVA_LONG));
 
+    // ZSTD_ErrorCode ZSTD_getErrorCode(size_t functionResult)
+    static final MethodHandle GET_ERROR_CODE =
+            NativeLibrary.lookup("ZSTD_getErrorCode", FunctionDescriptor.of(JAVA_INT, JAVA_LONG));
+
     // int ZSTD_maxCLevel(void) / ZSTD_minCLevel(void) / ZSTD_defaultCLevel(void)
     static final MethodHandle MAX_C_LEVEL =
             NativeLibrary.lookup("ZSTD_maxCLevel", FunctionDescriptor.of(JAVA_INT));

zstd/src/main/java/io/github/dfa1/zstdffm/Zstd.java

@@ -193,7 +193,7 @@ static long call(SizeCall c) {
             throw sneaky(t);
         }
         if (isError(code)) {
-            throw new ZstdException(errorName(code));
+            throw new ZstdException(errorName(code), ZstdErrorCode.of(errorCode(code)));
         }
         return code;
     }
@@ -206,6 +206,14 @@ private static boolean isError(long code) {
         }
     }
 
+    private static int errorCode(long code) {
+        try {
+            return (int) Bindings.GET_ERROR_CODE.invokeExact(code);
+        } catch (Throwable t) {
+            throw sneaky(t);
+        }
+    }
+
     @SuppressWarnings("restricted") // reinterpret needed to read a C string of unknown length
     private static String errorName(long code) {
         try {

zstd/src/main/java/io/github/dfa1/zstdffm/ZstdErrorCode.java

@@ -0,0 +1,111 @@
+package io.github.dfa1.zstdffm;
+
+/// Categories of zstd error, exposed by [ZstdException#code()] so callers can
+/// branch on the kind of failure (e.g. distinguish [#CHECKSUM_WRONG] from
+/// [#DST_SIZE_TOO_SMALL]) instead of matching on message text.
+///
+/// The numeric values mirror `ZSTD_ErrorCode` in the vendored zstd header. zstd
+/// does not guarantee these values across versions, but this library pins a
+/// specific zstd source, so they are stable for a given release. An unrecognised
+/// code maps to [#UNKNOWN].
+public enum ZstdErrorCode {
+
+    /// Not from a zstd error code (e.g. a NULL context or a training failure).
+    UNKNOWN(-1),
+    /// No error.
+    NO_ERROR(0),
+    /// Unspecified error.
+    GENERIC(1),
+    /// Input does not start with a recognised zstd frame prefix.
+    PREFIX_UNKNOWN(10),
+    /// Frame requires an unsupported zstd version.
+    VERSION_UNSUPPORTED(12),
+    /// Frame uses an unsupported parameter.
+    FRAME_PARAMETER_UNSUPPORTED(14),
+    /// Frame's window size exceeds the decoder's limit.
+    FRAME_PARAMETER_WINDOW_TOO_LARGE(16),
+    /// Compressed data is corrupt.
+    CORRUPTION_DETECTED(20),
+    /// Frame's content checksum did not match.
+    CHECKSUM_WRONG(22),
+    /// Literals section header is malformed.
+    LITERALS_HEADER_WRONG(24),
+    /// Dictionary content is corrupt.
+    DICTIONARY_CORRUPTED(30),
+    /// Frame was compressed with a different dictionary.
+    DICTIONARY_WRONG(32),
+    /// Dictionary could not be built.
+    DICTIONARY_CREATION_FAILED(34),
+    /// The given parameter is not supported.
+    PARAMETER_UNSUPPORTED(40),
+    /// The combination of parameters is not supported.
+    PARAMETER_COMBINATION_UNSUPPORTED(41),
+    /// A parameter value is outside its valid range.
+    PARAMETER_OUT_OF_BOUND(42),
+    /// Table log is too large.
+    TABLE_LOG_TOO_LARGE(44),
+    /// Maximum symbol value is too large.
+    MAX_SYMBOL_VALUE_TOO_LARGE(46),
+    /// Maximum symbol value is too small.
+    MAX_SYMBOL_VALUE_TOO_SMALL(48),
+    /// An uncompressed block could not be produced.
+    CANNOT_PRODUCE_UNCOMPRESSED_BLOCK(49),
+    /// A required stability condition was not respected.
+    STABILITY_CONDITION_NOT_RESPECTED(50),
+    /// Operation called at the wrong stage of the context lifecycle.
+    STAGE_WRONG(60),
+    /// Context was not initialised before use.
+    INIT_MISSING(62),
+    /// A memory allocation failed.
+    MEMORY_ALLOCATION(64),
+    /// The provided workspace is too small.
+    WORKSPACE_TOO_SMALL(66),
+    /// Destination buffer is too small to hold the result.
+    DST_SIZE_TOO_SMALL(70),
+    /// Declared source size does not match the data.
+    SRC_SIZE_WRONG(72),
+    /// Destination buffer pointer is NULL.
+    DST_BUFFER_NULL(74),
+    /// Streaming made no progress because the destination is full.
+    NO_FORWARD_PROGRESS_DEST_FULL(80),
+    /// Streaming made no progress because the input is empty.
+    NO_FORWARD_PROGRESS_INPUT_EMPTY(82),
+    /// Requested frame index is out of range (seekable format).
+    FRAME_INDEX_TOO_LARGE(100),
+    /// Seekable-format I/O error.
+    SEEKABLE_IO(102),
+    /// Destination buffer is otherwise invalid.
+    DST_BUFFER_WRONG(104),
+    /// Source buffer is otherwise invalid.
+    SRC_BUFFER_WRONG(105),
+    /// An external sequence producer failed.
+    SEQUENCE_PRODUCER_FAILED(106),
+    /// Externally supplied sequences are invalid.
+    EXTERNAL_SEQUENCES_INVALID(107);
+
+    private final int value;
+
+    ZstdErrorCode(int value) {
+        this.value = value;
+    }
+
+    /// The native `ZSTD_ErrorCode` integer for this category.
+    ///
+    /// @return the zstd error code value
+    public int value() {
+        return value;
+    }
+
+    /// Maps a native `ZSTD_ErrorCode` integer to its category.
+    ///
+    /// @param value the native error code
+    /// @return the matching category, or [#UNKNOWN] if unrecognised
+    static ZstdErrorCode of(int value) {
+        for (ZstdErrorCode code : values()) {
+            if (code.value == value) {
+                return code;
+            }
+        }
+        return UNKNOWN;
+    }
+}

zstd/src/main/java/io/github/dfa1/zstdffm/ZstdException.java

@@ -9,7 +9,23 @@ public final class ZstdException extends RuntimeException {
 
     private static final long serialVersionUID = 1L;
 
+    /// The zstd error category for this failure.
+    private final ZstdErrorCode code;
+
     ZstdException(String message) {
+        this(message, ZstdErrorCode.UNKNOWN);
+    }
+
+    ZstdException(String message, ZstdErrorCode code) {
         super(message);
+        this.code = code;
+    }
+
+    /// The category of this error, for programmatic branching.
+    ///
+    /// @return the zstd error category, or [ZstdErrorCode#UNKNOWN] if the failure
+    ///         did not originate from a zstd error code
+    public ZstdErrorCode code() {
+        return code;
     }
 }

zstd/src/test/java/io/github/dfa1/zstdffm/ZstdErrorTest.java

@@ -0,0 +1,63 @@
+package io.github.dfa1.zstdffm;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.catchThrowableOfType;
+
+class ZstdErrorTest {
+
+    private static final byte[] PAYLOAD = "typed error payload ".repeat(200).getBytes(StandardCharsets.UTF_8);
+
+    @Nested
+    class Code {
+
+        @Test
+        void reportsDstSizeTooSmall() {
+            // Given a frame decompressed into too small a buffer
+            byte[] frame = Zstd.compress(PAYLOAD);
+
+            // When it fails / Then the category is DST_SIZE_TOO_SMALL
+            ZstdException ex = catchThrowableOfType(ZstdException.class, () -> Zstd.decompress(frame, 1));
+            assertThat(ex.code()).isEqualTo(ZstdErrorCode.DST_SIZE_TOO_SMALL);
+        }
+
+        @Test
+        void reportsParameterOutOfBound() {
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx()) {
+                ZstdException ex = catchThrowableOfType(ZstdException.class,
+                        () -> ctx.parameter(ZstdCompressParameter.WINDOW_LOG, 99));
+                assertThat(ex.code()).isEqualTo(ZstdErrorCode.PARAMETER_OUT_OF_BOUND);
+            }
+        }
+
+        @Test
+        void reportsANativeCategoryForGarbage() {
+            // Given non-zstd input decompressed with a generous buffer
+            byte[] garbage = "definitely not a zstd frame at all".getBytes(StandardCharsets.UTF_8);
+
+            // Then the error carries a real native category, not UNKNOWN
+            ZstdException ex = catchThrowableOfType(ZstdException.class, () -> Zstd.decompress(garbage, 1024));
+            assertThat(ex.code()).isNotIn(ZstdErrorCode.UNKNOWN, ZstdErrorCode.NO_ERROR);
+        }
+    }
+
+    @Nested
+    class Mapping {
+
+        @Test
+        void mapsKnownValues() {
+            assertThat(ZstdErrorCode.of(22)).isEqualTo(ZstdErrorCode.CHECKSUM_WRONG);
+            assertThat(ZstdErrorCode.of(70)).isEqualTo(ZstdErrorCode.DST_SIZE_TOO_SMALL);
+            assertThat(ZstdErrorCode.CHECKSUM_WRONG.value()).isEqualTo(22);
+        }
+
+        @Test
+        void mapsUnknownValueToUnknown() {
+            assertThat(ZstdErrorCode.of(999_999)).isEqualTo(ZstdErrorCode.UNKNOWN);
+        }
+    }
+}