feat: cover all advanced parameters

- ZstdCompressParameter now lists every stable ZSTD_cParameter (adds
  targetCBlockSize, the four LDM params, jobSize, overlapLog)
- ZstdDecompressParameter (ZSTD_dParameter: windowLogMax) + ZstdDecompressCtx
  .parameter()/.windowLogMax(); bind ZSTD_DCtx_setParameter
- bounds introspection: ZstdCompressParameter.bounds() /
  ZstdDecompressParameter.bounds() return ZstdBounds, via ZSTD_c/dParam_getBounds
  (a ZSTD_bounds struct returned by value through FFM)
- compatibility.md now 51/186

Tests: compression-level bounds match the library; every compression parameter
reports bounds; new params round-trip at their lower bound; windowLogMax is
accepted and rejects out-of-range.

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: **48** (~26%)
+- Bound so far: **51** (~27%)
 
 "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
@@ -27,7 +27,7 @@ low-level variants that an idiomatic Java API does not need.
 | Dictionary training (ZDICT) | 4 / 12 | `trainFromBuffer`; cover/fastCover optimizers not bound |
 | Streaming — compress | 3 / 22 | `ZstdOutputStream` (compressStream2 + buffer sizes) |
 | Streaming — decompress | 3 / 15 | `ZstdInputStream` (decompressStream + buffer sizes) |
-| Advanced parameters | 4 / 38 | `CCtx_setParameter` + `compress2` (level, checksum, LDM, windowLog) and `C/DCtx_loadDictionary` (dictionary streams); MT/getBounds not bound |
+| Advanced parameters | 7 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `loadDictionary`, `c/dParam_getBounds`; MT inert on single-thread build |
 | Frame inspection | 9 / 13 | `ZstdFrame`: isFrame, header, compressedSize, decompressedBound, dictId, skippable read/write; getFrameProgression/_advanced not bound |
 | Memory sizing | 0 / 14 | `sizeof_*` / `estimate*` accounting not bound |
 | Low-level block | 0 / 12 | expert block/continue API not bound |
@@ -54,15 +54,17 @@ low-level variants that an idiomatic Java API does not need.
 | `ZDICT_isError`, `ZDICT_getErrorName` | internal error mapping in `ZstdDictionary` |
 | `ZSTD_compressStream2`, `ZSTD_CStreamInSize`, `ZSTD_CStreamOutSize`, `ZSTD_CCtx_setParameter` | `ZstdOutputStream` |
 | `ZSTD_decompressStream`, `ZSTD_DStreamInSize`, `ZSTD_DStreamOutSize` | `ZstdInputStream` |
-| `ZSTD_compress2`, `ZSTD_CCtx_setParameter` | `ZstdCompressCtx.parameter` / `checksum` / `longDistanceMatching` / `windowLog` (+ `ZstdCompressParameter`) |
+| `ZSTD_compress2`, `ZSTD_CCtx_setParameter` | `ZstdCompressCtx.parameter` / `checksum` / `longDistanceMatching` / `windowLog` (all of `ZstdCompressParameter`) |
+| `ZSTD_DCtx_setParameter` | `ZstdDecompressCtx.parameter` / `windowLogMax` (`ZstdDecompressParameter`) |
+| `ZSTD_cParam_getBounds`, `ZSTD_dParam_getBounds` | `ZstdCompressParameter.bounds()` / `ZstdDecompressParameter.bounds()` (`ZstdBounds`) |
 | `ZSTD_CCtx_loadDictionary`, `ZSTD_DCtx_loadDictionary` | `ZstdOutputStream` / `ZstdInputStream` dictionary constructors |
 | `ZSTD_isFrame`, `ZSTD_findFrameCompressedSize`, `ZSTD_decompressBound`, `ZSTD_getDictID_fromFrame`, `ZSTD_getFrameHeader`, `ZSTD_isSkippableFrame`, `ZSTD_writeSkippableFrame`, `ZSTD_readSkippableFrame` | `ZstdFrame` (+ `ZstdFrameHeader`, `ZstdFrameType`, `ZstdSkippableContent`) |
 | `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).
+2. ~~**Advanced parameters**~~ — done: every `ZSTD_cParameter`/`ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter` (+ `bounds()`), on both contexts. Remaining: `pledgedSrcSize`; `nbWorkers` is settable but inert until the native build enables multithreading.
 3. ~~**Frame inspection**~~ — done: `ZstdFrame` (`isFrame`, `header`, `compressedSize`, `decompressedBound`, `dictId`, skippable read/write). Remaining: `getDictID_fromDict/CDict/DDict`, `getFrameProgression`.
 4. **Better dictionaries** — `ZDICT_optimizeTrainFromBuffer_cover` / `_fastCover`, `finalizeDictionary`.
 5. ~~**Typed errors**~~ — done: `ZstdException.code()` returns `ZstdErrorCode` (via `getErrorCode`).
@@ -204,7 +206,7 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_resetDStream` | — |
 | `ZSTD_sizeof_DStream` | — |
 
-### Advanced parameters (4/38)
+### Advanced parameters (7/38)
 
 | Symbol | Bound |
 |---|:---:|
@@ -239,11 +241,11 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_DCtx_reset` | — |
 | `ZSTD_DCtx_setFormat` | — |
 | `ZSTD_DCtx_setMaxWindowSize` | — |
-| `ZSTD_DCtx_setParameter` | — |
-| `ZSTD_cParam_getBounds` | — |
+| `ZSTD_DCtx_setParameter` | ✅ |
+| `ZSTD_cParam_getBounds` | ✅ |
 | `ZSTD_compress2` | ✅ |
 | `ZSTD_createCCtxParams` | — |
-| `ZSTD_dParam_getBounds` | — |
+| `ZSTD_dParam_getBounds` | ✅ |
 | `ZSTD_estimateCCtxSize_usingCCtxParams` | — |
 | `ZSTD_freeCCtxParams` | — |
 

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.zstd;
 
 import java.lang.foreign.FunctionDescriptor;
+import java.lang.foreign.MemoryLayout;
 import java.lang.invoke.MethodHandle;
 
 import static java.lang.foreign.ValueLayout.ADDRESS;
@@ -133,6 +134,20 @@ final class Bindings {
             NativeLibrary.lookup("ZSTD_compress2",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG, ADDRESS, JAVA_LONG));
 
+    // size_t ZSTD_DCtx_setParameter(ZSTD_DCtx*, ZSTD_dParameter, int value)
+    static final MethodHandle DCTX_SET_PARAMETER =
+            NativeLibrary.lookup("ZSTD_DCtx_setParameter",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT, JAVA_INT));
+
+    // ZSTD_bounds { size_t error; int lowerBound; int upperBound; } — returned by value
+    private static final MemoryLayout BOUNDS_LAYOUT =
+            MemoryLayout.structLayout(JAVA_LONG, JAVA_INT, JAVA_INT);
+    // ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter) / ZSTD_dParam_getBounds(ZSTD_dParameter)
+    static final MethodHandle CPARAM_GET_BOUNDS =
+            NativeLibrary.lookup("ZSTD_cParam_getBounds", FunctionDescriptor.of(BOUNDS_LAYOUT, JAVA_INT));
+    static final MethodHandle DPARAM_GET_BOUNDS =
+            NativeLibrary.lookup("ZSTD_dParam_getBounds", FunctionDescriptor.of(BOUNDS_LAYOUT, JAVA_INT));
+
     // size_t ZSTD_compressStream2(ZSTD_CCtx*, ZSTD_outBuffer*, ZSTD_inBuffer*, ZSTD_EndDirective)
     static final MethodHandle COMPRESS_STREAM2 =
             NativeLibrary.lookup("ZSTD_compressStream2",

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

@@ -198,7 +198,7 @@ static long call(SizeCall c) {
         return code;
     }
 
-    private static boolean isError(long code) {
+    static boolean isError(long code) {
         try {
             return ((int) Bindings.IS_ERROR.invokeExact(code)) != 0;
         } catch (Throwable t) {

zstd/src/main/java/io/github/dfa1/zstd/ZstdBounds.java

@@ -0,0 +1,37 @@
+package io.github.dfa1.zstd;
+
+import java.lang.foreign.Arena;
+import java.lang.foreign.MemorySegment;
+import java.lang.foreign.SegmentAllocator;
+import java.lang.invoke.MethodHandle;
+
+import static java.lang.foreign.ValueLayout.JAVA_INT;
+import static java.lang.foreign.ValueLayout.JAVA_LONG;
+
+/// The inclusive range of values a compression or decompression parameter
+/// accepts, from `ZSTD_cParam_getBounds` / `ZSTD_dParam_getBounds`.
+///
+/// @param lowerBound the smallest accepted value, inclusive
+/// @param upperBound the largest accepted value, inclusive
+public record ZstdBounds(int lowerBound, int upperBound) {
+
+    /// Calls a `*_getBounds` function (which returns a `ZSTD_bounds` struct by
+    /// value: `{ size_t error; int lowerBound; int upperBound; }`).
+    static ZstdBounds query(MethodHandle getBounds, int parameter) {
+        try (Arena arena = Arena.ofConfined()) {
+            MemorySegment bounds = (MemorySegment) getBounds.invokeExact((SegmentAllocator) arena, parameter);
+            long error = bounds.get(JAVA_LONG, 0);
+            if (Zstd.isError(error)) {
+                throw new ZstdException("parameter has no queryable bounds");
+            }
+            return new ZstdBounds(bounds.get(JAVA_INT, 8), bounds.get(JAVA_INT, 12));
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
+    @SuppressWarnings("unchecked")
+    private static <E extends Throwable> RuntimeException rethrow(Throwable t) throws E {
+        throw (E) t;
+    }
+}

zstd/src/main/java/io/github/dfa1/zstd/ZstdCompressParameter.java

@@ -25,8 +25,18 @@ public enum ZstdCompressParameter {
     TARGET_LENGTH(106),
     /// Compression strategy (1..9: fast … btultra2).
     STRATEGY(107),
+    /// Target uncompressed block size, in bytes (0 = no target); trades ratio for latency.
+    TARGET_C_BLOCK_SIZE(130),
     /// Enable long-distance matching (1) for better ratio on large inputs.
     ENABLE_LONG_DISTANCE_MATCHING(160),
+    /// Long-distance matching hash table size, as a power of two.
+    LDM_HASH_LOG(161),
+    /// Minimum match length for the long-distance matcher, in bytes.
+    LDM_MIN_MATCH(162),
+    /// Log size of each bucket in the long-distance matcher's hash table.
+    LDM_BUCKET_SIZE_LOG(163),
+    /// How often to insert entries into the long-distance matcher's hash table, as a log.
+    LDM_HASH_RATE_LOG(164),
     /// Write the decompressed size into the frame header (1, the default) or not (0).
     CONTENT_SIZE_FLAG(200),
     /// Append a 32-bit content checksum to the frame (1) for integrity, or not (0, the default).
@@ -36,7 +46,11 @@ public enum ZstdCompressParameter {
     /// Number of worker threads (0 = single-threaded). Requires a multithreaded
     /// build of the native library; the bundled library is single-threaded, so a
     /// non-zero value has no effect.
-    NB_WORKERS(400);
+    NB_WORKERS(400),
+    /// Size of a compression job, in bytes, when multithreading (0 = automatic).
+    JOB_SIZE(401),
+    /// Overlap between consecutive multithreading jobs, as a log fraction of the window.
+    OVERLAP_LOG(402);
 
     private final int value;
 
@@ -50,4 +64,13 @@ public enum ZstdCompressParameter {
     int value() {
         return value;
     }
+
+    /// The inclusive `[lower, upper]` range of values this parameter accepts,
+    /// queried from zstd via `ZSTD_cParam_getBounds`.
+    ///
+    /// @return the valid bounds for this parameter
+    /// @throws ZstdException if zstd reports no bounds for this parameter
+    public ZstdBounds bounds() {
+        return ZstdBounds.query(Bindings.CPARAM_GET_BOUNDS, value);
+    }
 }

zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressCtx.java

@@ -26,6 +26,26 @@ private static MemorySegment create() {
         }
     }
 
+    /// Sets an advanced decompression parameter, sticky across subsequent calls.
+    ///
+    /// @param parameter the parameter to set
+    /// @param value     the value, validated natively against the parameter's bounds
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the value is out of range for the parameter
+    public ZstdDecompressCtx parameter(ZstdDecompressParameter parameter, int value) {
+        Zstd.call(() -> (long) Bindings.DCTX_SET_PARAMETER.invokeExact(ptr(), parameter.value(), value));
+        return this;
+    }
+
+    /// Sets the largest back-reference window the decoder will accept, as a
+    /// power of two. Raise it to decode frames built with a large `windowLog`.
+    ///
+    /// @param windowLogMax the base-2 log of the maximum accepted window size
+    /// @return `this`, for chaining
+    public ZstdDecompressCtx windowLogMax(int windowLogMax) {
+        return parameter(ZstdDecompressParameter.WINDOW_LOG_MAX, windowLogMax);
+    }
+
     /// Decompresses a frame into a buffer of at most `maxSize` bytes.
     ///
     /// @param compressed a complete zstd frame

zstd/src/main/java/io/github/dfa1/zstd/ZstdDecompressParameter.java

@@ -0,0 +1,35 @@
+package io.github.dfa1.zstd;
+
+/// Advanced decompression parameters settable on a [ZstdDecompressCtx], mirroring
+/// `ZSTD_dParameter` from the
+/// [official manual](https://facebook.github.io/zstd/doc/api_manual_latest.html).
+///
+/// Set them with [ZstdDecompressCtx#parameter(ZstdDecompressParameter, int)].
+public enum ZstdDecompressParameter {
+
+    /// Largest back-reference window the decoder will accept, as a power of two.
+    /// Frames needing a larger window are rejected; raise this to decode them.
+    WINDOW_LOG_MAX(100);
+
+    private final int value;
+
+    ZstdDecompressParameter(int value) {
+        this.value = value;
+    }
+
+    /// The native `ZSTD_dParameter` integer value.
+    ///
+    /// @return the enum value as defined by zstd
+    int value() {
+        return value;
+    }
+
+    /// The inclusive `[lower, upper]` range of values this parameter accepts,
+    /// queried from zstd via `ZSTD_dParam_getBounds`.
+    ///
+    /// @return the valid bounds for this parameter
+    /// @throws ZstdException if zstd reports no bounds for this parameter
+    public ZstdBounds bounds() {
+        return ZstdBounds.query(Bindings.DPARAM_GET_BOUNDS, value);
+    }
+}

zstd/src/test/java/io/github/dfa1/zstd/ZstdParameterTest.java

@@ -2,6 +2,8 @@
 
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 
 import java.nio.charset.StandardCharsets;
 
@@ -69,6 +71,71 @@ void explicitWindowLogRoundTrips() {
         }
     }
 
+    @Nested
+    class Bounds {
+
+        @Test
+        void compressionLevelBoundsMatchTheLibrary() {
+            ZstdBounds bounds = ZstdCompressParameter.COMPRESSION_LEVEL.bounds();
+            assertThat(bounds.lowerBound()).isEqualTo(Zstd.minCompressionLevel());
+            assertThat(bounds.upperBound()).isEqualTo(Zstd.maxCompressionLevel());
+        }
+
+        @ParameterizedTest
+        @EnumSource(ZstdCompressParameter.class)
+        void everyCompressionParameterReportsBounds(ZstdCompressParameter parameter) {
+            ZstdBounds bounds = parameter.bounds();
+            assertThat(bounds.upperBound()).isGreaterThanOrEqualTo(bounds.lowerBound());
+        }
+
+        @Test
+        void decompressionParameterReportsBounds() {
+            ZstdBounds bounds = ZstdDecompressParameter.WINDOW_LOG_MAX.bounds();
+            assertThat(bounds.upperBound()).isGreaterThan(bounds.lowerBound());
+        }
+    }
+
+    @Nested
+    class MoreParameters {
+
+        @ParameterizedTest
+        @EnumSource(value = ZstdCompressParameter.class,
+                names = {"TARGET_C_BLOCK_SIZE", "LDM_HASH_LOG", "LDM_MIN_MATCH",
+                        "LDM_BUCKET_SIZE_LOG", "STRATEGY"})
+        void settingAParameterAtItsLowerBoundRoundTrips(ZstdCompressParameter parameter) {
+            // Given a parameter set to a valid in-range value
+            int value = Math.max(parameter.bounds().lowerBound(), 1);
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().parameter(parameter, value)) {
+                frame = ctx.compress(PAYLOAD);
+            }
+            // Then the frame still decompresses
+            assertThat(Zstd.decompress(frame)).isEqualTo(PAYLOAD);
+        }
+    }
+
+    @Nested
+    class Decompress {
+
+        @Test
+        void windowLogMaxIsAccepted() {
+            // Given a decompressor configured with a raised window limit
+            byte[] frame = Zstd.compress(PAYLOAD);
+            try (ZstdDecompressCtx ctx = new ZstdDecompressCtx().windowLogMax(31)) {
+                // Then normal frames still decode
+                assertThat(ctx.decompress(frame, PAYLOAD.length)).isEqualTo(PAYLOAD);
+            }
+        }
+
+        @Test
+        void rejectsOutOfRangeValue() {
+            try (ZstdDecompressCtx ctx = new ZstdDecompressCtx()) {
+                assertThatThrownBy(() -> ctx.parameter(ZstdDecompressParameter.WINDOW_LOG_MAX, 99))
+                        .isInstanceOf(ZstdException.class);
+            }
+        }
+    }
+
     @Nested
     class GenericSetter {