feat: advanced compression parameters (checksum, LDM, windowLog)

ZstdCompressCtx now drives ZSTD_compress2 so the advanced parameters set via
ZSTD_CCtx_setParameter take effect:

- ZstdCompressParameter enum mirrors ZSTD_cParameter (values from the manual)
- ctx.parameter(p, v) generic setter (natively validated -> ZstdException on
  out-of-range), plus checksum(bool), longDistanceMatching(bool), windowLog(int)
- level() and the byte[]/MemorySegment compress paths route through compress2;
  dictionary overloads keep the legacy level-arg path
- nbWorkers is in the enum but a no-op on the bundled single-threaded build
- bind ZSTD_compress2; compatibility.md now 37/186

Tests: checksum adds its 4-byte trailer and round-trips; a corrupted checksummed
frame is rejected; LDM/windowLog round-trip; generic level matches level();
out-of-range value throws.

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: **36** (~19%)
+- Bound so far: **37** (~20%)
 
 "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 | 1 / 38 | only `CCtx_setParameter` (level), used by the streams; bounds/MT/LDM not bound |
+| Advanced parameters | 2 / 38 | `CCtx_setParameter` + `compress2` via `ZstdCompressCtx` (level, checksum, LDM, windowLog…); MT/getBounds not bound |
 | Frame inspection | 1 / 13 | only `getFrameContentSize`; header/skippable/dictID-from-frame not bound |
 | Memory sizing | 0 / 14 | `sizeof_*` / `estimate*` accounting not bound |
 | Low-level block | 0 / 12 | expert block/continue API not bound |
@@ -54,11 +54,12 @@ 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`) |
 
 ## Roadmap (priority order)
 
 1. ~~**Streaming**~~ — done: `ZstdOutputStream` / `ZstdInputStream` (`compressStream2`, `decompressStream`, bounded buffers). Remaining: dictionary-on-stream, `MemorySegment`-buffer driver, `pledgedSrcSize`.
-2. **Advanced parameters** — `ZSTD_CCtx_setParameter` (level is bound; expose the rest) + `cParam_getBounds`: checksums, `nbWorkers`, long-distance matching, window log, `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** — `getFrameHeader`, `isFrame`, `findFrameCompressedSize`, `decompressBound`, `getDictID_from*`, skippable frames.
 4. **Better dictionaries** — `ZDICT_optimizeTrainFromBuffer_cover` / `_fastCover`, `finalizeDictionary`.
 5. **Typed errors** — `ZSTD_getErrorCode` / `ZSTD_getErrorString`.
@@ -200,7 +201,7 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_resetDStream` | — |
 | `ZSTD_sizeof_DStream` | — |
 
-### Advanced parameters (1/38)
+### Advanced parameters (2/38)
 
 | Symbol | Bound |
 |---|:---:|
@@ -237,7 +238,7 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_DCtx_setMaxWindowSize` | — |
 | `ZSTD_DCtx_setParameter` | — |
 | `ZSTD_cParam_getBounds` | — |
-| `ZSTD_compress2` | — |
+| `ZSTD_compress2` | ✅ |
 | `ZSTD_createCCtxParams` | — |
 | `ZSTD_dParam_getBounds` | — |
 | `ZSTD_estimateCCtxSize_usingCCtxParams` | — |

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

@@ -91,6 +91,12 @@ final class Bindings {
             NativeLibrary.lookup("ZSTD_CCtx_setParameter",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_INT, JAVA_INT));
 
+    // size_t ZSTD_compress2(ZSTD_CCtx*, void* dst, size_t dstCap, const void* src, size_t srcSize)
+    // Uses the advanced parameters set on the context (unlike ZSTD_compressCCtx).
+    static final MethodHandle COMPRESS2 =
+            NativeLibrary.lookup("ZSTD_compress2",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG, ADDRESS, JAVA_LONG));
+
     // 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/zstdffm/ZstdCompressCtx.java

@@ -43,10 +43,54 @@ private static MemorySegment create() {
     /// @return `this`, for chaining
     public ZstdCompressCtx level(int level) {
         this.level = level;
+        setParam(ZstdCompressParameter.COMPRESSION_LEVEL, level);
         return this;
     }
 
-    /// Compresses `src` into a new zstd frame using this context.
+    /// Sets an advanced compression parameter for subsequent
+    /// {@link #compress(byte[])} / {@link #compress(MemorySegment, MemorySegment)}
+    /// calls. The setting is sticky across calls until changed.
+    ///
+    /// Advanced parameters do not apply to the dictionary `compress` overloads.
+    ///
+    /// @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 ZstdCompressCtx parameter(ZstdCompressParameter parameter, int value) {
+        setParam(parameter, value);
+        return this;
+    }
+
+    /// Appends a 32-bit content checksum to each frame, which decompression
+    /// verifies and rejects on mismatch. Off by default.
+    ///
+    /// @param enabled whether to write a checksum
+    /// @return `this`, for chaining
+    public ZstdCompressCtx checksum(boolean enabled) {
+        return parameter(ZstdCompressParameter.CHECKSUM_FLAG, enabled ? 1 : 0);
+    }
+
+    /// Enables long-distance matching for a better ratio on large, repetitive inputs.
+    ///
+    /// @param enabled whether to enable long-distance matching
+    /// @return `this`, for chaining
+    public ZstdCompressCtx longDistanceMatching(boolean enabled) {
+        return parameter(ZstdCompressParameter.ENABLE_LONG_DISTANCE_MATCHING, enabled ? 1 : 0);
+    }
+
+    /// Sets the maximum back-reference distance as a power of two (larger window =
+    /// better ratio, more memory). Decompression of large windows may require
+    /// raising the decompressor's window limit.
+    ///
+    /// @param windowLog the base-2 log of the window size
+    /// @return `this`, for chaining
+    public ZstdCompressCtx windowLog(int windowLog) {
+        return parameter(ZstdCompressParameter.WINDOW_LOG, windowLog);
+    }
+
+    /// Compresses `src` into a new zstd frame using this context and its
+    /// advanced parameters.
     ///
     /// @param src the bytes to compress
     /// @return a self-describing zstd frame
@@ -55,12 +99,16 @@ public byte[] compress(byte[] src) {
             MemorySegment in = Zstd.copyIn(arena, src);
             long bound = Zstd.compressBound(src.length);
             MemorySegment out = arena.allocate(bound);
-            long written = Zstd.call(() -> (long) Bindings.COMPRESS_CCTX.invokeExact(
-                    ptr(), out, bound, in, (long) src.length, level));
+            long written = Zstd.call(() -> (long) Bindings.COMPRESS2.invokeExact(
+                    ptr(), out, bound, in, (long) src.length));
             return Zstd.copyOut(out, written);
         }
     }
 
+    private void setParam(ZstdCompressParameter parameter, int value) {
+        Zstd.call(() -> (long) Bindings.CCTX_SET_PARAMETER.invokeExact(ptr(), parameter.value(), value));
+    }
+
     /// Compresses `src` against `dict` at this context's level.
     ///
     /// The dictionary is re-digested on every call; for repeated compression
@@ -114,8 +162,8 @@ public byte[] compress(byte[] src, ZstdCompressDict dict) {
     /// @return the number of bytes written into `dst`
     /// @throws ZstdException if `dst` is too small or compression fails
     public long compress(MemorySegment dst, MemorySegment src) {
-        return Zstd.call(() -> (long) Bindings.COMPRESS_CCTX.invokeExact(
-                ptr(), dst, dst.byteSize(), src, src.byteSize(), level));
+        return Zstd.call(() -> (long) Bindings.COMPRESS2.invokeExact(
+                ptr(), dst, dst.byteSize(), src, src.byteSize()));
     }
 
     /// Zero-copy compression against a pre-digested `dict`, segment to segment.

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

@@ -0,0 +1,53 @@
+package io.github.dfa1.zstdffm;
+
+/// Advanced compression parameters settable on a [ZstdCompressCtx], mirroring
+/// `ZSTD_cParameter` from the
+/// [official manual](https://facebook.github.io/zstd/doc/api_manual_latest.html).
+///
+/// Set them with [ZstdCompressCtx#parameter(ZstdCompressParameter, int)]; the
+/// context applies them on its next [ZstdCompressCtx#compress(byte[])]. Values
+/// are validated natively — an out-of-range value raises a [ZstdException].
+public enum ZstdCompressParameter {
+
+    /// Compression level. Prefer [ZstdCompressCtx#level(int)].
+    COMPRESSION_LEVEL(100),
+    /// Maximum back-reference distance, as a power of two (larger = better ratio, more memory).
+    WINDOW_LOG(101),
+    /// Size of the initial probe table, as a power of two.
+    HASH_LOG(102),
+    /// Size of the multi-probe search table, as a power of two.
+    CHAIN_LOG(103),
+    /// Number of search attempts, as a power of two.
+    SEARCH_LOG(104),
+    /// Minimum match length, in bytes.
+    MIN_MATCH(105),
+    /// Target match length; impact depends on the strategy.
+    TARGET_LENGTH(106),
+    /// Compression strategy (1..9: fast … btultra2).
+    STRATEGY(107),
+    /// Enable long-distance matching (1) for better ratio on large inputs.
+    ENABLE_LONG_DISTANCE_MATCHING(160),
+    /// 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).
+    CHECKSUM_FLAG(201),
+    /// Write the dictionary id into the frame header (1, the default) or not (0).
+    DICT_ID_FLAG(202),
+    /// 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);
+
+    private final int value;
+
+    ZstdCompressParameter(int value) {
+        this.value = value;
+    }
+
+    /// The native `ZSTD_cParameter` integer value.
+    ///
+    /// @return the enum value as defined by zstd
+    int value() {
+        return value;
+    }
+}

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

@@ -0,0 +1,100 @@
+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.assertThatThrownBy;
+
+class ZstdParameterTest {
+
+    private static final byte[] PAYLOAD =
+            "advanced-parameter payload ".repeat(2000).getBytes(StandardCharsets.UTF_8);
+
+    @Nested
+    class Checksum {
+
+        @Test
+        void addsFourByteTrailerAndStillRoundTrips() {
+            // Given the same input compressed at the same level with and without a checksum
+            byte[] plain;
+            byte[] checksummed;
+            try (ZstdCompressCtx noSum = new ZstdCompressCtx().level(9);
+                 ZstdCompressCtx withSum = new ZstdCompressCtx().level(9).checksum(true)) {
+                plain = noSum.compress(PAYLOAD);
+                checksummed = withSum.compress(PAYLOAD);
+            }
+
+            // Then the checksum adds exactly its 4-byte trailer, and the frame still decodes
+            assertThat(checksummed.length).isEqualTo(plain.length + 4);
+            assertThat(Zstd.decompress(checksummed)).isEqualTo(PAYLOAD);
+        }
+
+        @Test
+        void rejectsCorruptedChecksummedFrame() {
+            // Given a checksummed frame with one body byte flipped
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().checksum(true)) {
+                frame = ctx.compress(PAYLOAD);
+            }
+            frame[frame.length / 2] ^= 0x01;
+
+            // When decompressed / Then the integrity check fails
+            assertThatThrownBy(() -> Zstd.decompress(frame, PAYLOAD.length))
+                    .isInstanceOf(ZstdException.class);
+        }
+    }
+
+    @Nested
+    class Ratio {
+
+        @Test
+        void longDistanceMatchingRoundTrips() {
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().level(3).longDistanceMatching(true)) {
+                frame = ctx.compress(PAYLOAD);
+            }
+            assertThat(Zstd.decompress(frame)).isEqualTo(PAYLOAD);
+        }
+
+        @Test
+        void explicitWindowLogRoundTrips() {
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().windowLog(24)) {
+                frame = ctx.compress(PAYLOAD);
+            }
+            assertThat(Zstd.decompress(frame)).isEqualTo(PAYLOAD);
+        }
+    }
+
+    @Nested
+    class GenericSetter {
+
+        @Test
+        void levelViaParameterMatchesLevelMethod() {
+            // Given the level set generically vs via level()
+            byte[] viaParam;
+            byte[] viaMethod;
+            try (ZstdCompressCtx a = new ZstdCompressCtx().parameter(ZstdCompressParameter.COMPRESSION_LEVEL, 17);
+                 ZstdCompressCtx b = new ZstdCompressCtx().level(17)) {
+                viaParam = a.compress(PAYLOAD);
+                viaMethod = b.compress(PAYLOAD);
+            }
+
+            // Then both produce the same frame
+            assertThat(viaParam).isEqualTo(viaMethod);
+        }
+
+        @Test
+        void rejectsOutOfRangeValue() {
+            // Given an absurd window log
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx()) {
+                // When set / Then it is rejected natively
+                assertThatThrownBy(() -> ctx.parameter(ZstdCompressParameter.WINDOW_LOG, 99))
+                        .isInstanceOf(ZstdException.class);
+            }
+        }
+    }
+}