feat: load/ref dictionaries on contexts (loadDictionary / refDictionary)

Bind ZSTD_CCtx/DCtx_loadDictionary on the one-shot contexts (previously
only on streams) and the new ZSTD_CCtx_refCDict / ZSTD_DCtx_refDDict.

A sticky dictionary on a context lets compression combine a dictionary
with the advanced parameters (checksum, window log, long-distance
matching) via the compress2 path — impossible through the per-call
compress(src, dict) overloads, which route the legacy dictionary path.
refDictionary attaches a pre-digested CDict/DDict by reference (no copy,
no per-call digest), the pooled-context hot path that pairs with reset.
A parameter reset clears either.

loadDictionary takes a ZstdDictionary or a native MemorySegment
(zero-copy); refDictionary borrows the digest, so the caller keeps it
alive. Tests cover dict+checksum combine, ref-across-session-reset,
reset/null clearing, segment load, and zstd-jni interop on both frames.

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

Author: dfa1

CHANGELOG.md

@@ -12,6 +12,15 @@ git tags, which trigger publication to Maven Central.
   it. `SESSION_ONLY` keeps the level, parameters, and dictionary; `PARAMETERS` /
   `SESSION_AND_PARAMETERS` restore the defaults. Binds `ZSTD_CCtx_reset` /
   `ZSTD_DCtx_reset`.
+- `ZstdCompressCtx.loadDictionary(...)` / `ZstdDecompressCtx.loadDictionary(...)`
+  (a `ZstdDictionary` or a native `MemorySegment`) and `refDictionary(...)` (a
+  pre-digested `ZstdCompressDict` / `ZstdDecompressDict`, attached by reference,
+  no copy). A sticky dictionary on the context lets compression combine a
+  dictionary with the advanced parameters (checksum, window log, long-distance
+  matching) — impossible through the per-call `compress(src, dict)` overloads,
+  which route the legacy dictionary path. A parameter `reset(...)` clears it.
+  Binds `ZSTD_CCtx_loadDictionary` / `ZSTD_DCtx_loadDictionary` (now on contexts,
+  not just streams), `ZSTD_CCtx_refCDict`, `ZSTD_DCtx_refDDict`.
 
 ### Changed
 - `NativeLibrary.classifier()` now throws a clear `UnsatisfiedLinkError` naming

docs/how-to.md

@@ -43,6 +43,39 @@ try (ZstdCompressCtx cctx = new ZstdCompressCtx().level(19)) {
 allocation; reset lets a long-lived or pooled context return to a known state
 without churning native memory.
 
+## Compress with a dictionary *and* advanced parameters
+
+The per-call `compress(src, dict)` overloads take the legacy dictionary path,
+which ignores the advanced parameters (checksum, window log, long-distance
+matching) set on the context. To combine the two, make the dictionary *sticky*
+with `loadDictionary` — then the normal `compress` path honours both:
+
+```java
+try (ZstdCompressCtx cctx = new ZstdCompressCtx().level(19).checksum(true)) {
+    cctx.loadDictionary(dict);          // ZstdDictionary, or a native MemorySegment
+    byte[] frame = cctx.compress(record); // dictionary + checksum, together
+}
+```
+
+For a dictionary reused across a pool of contexts, digest it once and attach it
+by reference — no per-call digesting, no copy. It pairs with `reset` for a
+pooled, recycled context:
+
+```java
+try (ZstdCompressDict cdict = new ZstdCompressDict(dict, 19)) {
+    // one cctx per pooled worker, all sharing the one digested dictionary
+    try (ZstdCompressCtx cctx = new ZstdCompressCtx()) {
+        cctx.refDictionary(cdict);          // borrowed; cdict must outlive cctx
+        byte[] a = cctx.compress(first);
+        cctx.reset(ZstdResetDirective.SESSION_ONLY); // recycle, keep the dictionary
+        byte[] b = cctx.compress(second);
+    }
+}
+```
+
+A loaded or referenced dictionary stays until replaced, cleared with `null`, or
+dropped by a parameter `reset`. `ZstdDecompressCtx` mirrors all of this.
+
 ## Compress many small payloads with a dictionary
 
 For many small, similar payloads (log lines, JSON records, protobufs), a

docs/supported.md

@@ -33,7 +33,7 @@ rather than the deprecated `ZSTD_getDecompressedSize`.
 | Dictionary training (ZDICT) | 8 / 12 | trainFromBuffer, cover/fastCover optimizers, finalizeDictionary, getDictHeaderSize |
 | Streaming — compress | 3 / 22 | `ZstdOutputStream` (compressStream2 + buffer sizes) |
 | Streaming — decompress | 3 / 15 | `ZstdInputStream` (decompressStream + buffer sizes) |
-| Advanced parameters | 10 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `C/DCtx_reset`, `loadDictionary`, `c/dParam_getBounds`; MT inert on single-thread build |
+| Advanced parameters | 12 / 38 | all `ZSTD_cParameter` + `ZSTD_dParameter` via `ZstdCompressParameter`/`ZstdDecompressParameter`; `compress2`, `C/DCtx_setParameter`, `C/DCtx_reset`, `C/DCtx_loadDictionary`, `CCtx_refCDict`/`DCtx_refDDict`, `c/dParam_getBounds`; MT inert on single-thread build |
 | Frame inspection | 10 / 13 | `ZstdFrame` + getFrameProgression; `_advanced` not bound |
 | Memory sizing | 8 / 14 | sizeof_C/DCtx, sizeof_C/DDict, estimate C/DCtx + C/DDict size |
 | Low-level block | 0 / 12 | expert block/continue API not bound |
@@ -67,7 +67,8 @@ rather than the deprecated `ZSTD_getDecompressedSize`.
 | `ZSTD_getDictID_fromCDict`, `ZSTD_getDictID_fromDDict` | `ZstdCompressDict.id()` / `ZstdDecompressDict.id()` |
 | `ZSTD_getErrorString` | `ZstdErrorCode.description()` |
 | `ZSTD_cParam_getBounds`, `ZSTD_dParam_getBounds` | `ZstdCompressParameter.bounds()` / `ZstdDecompressParameter.bounds()` (`ZstdBounds`) |
-| `ZSTD_CCtx_loadDictionary`, `ZSTD_DCtx_loadDictionary` | `ZstdOutputStream` / `ZstdInputStream` dictionary constructors |
+| `ZSTD_CCtx_loadDictionary`, `ZSTD_DCtx_loadDictionary` | `ZstdCompressCtx.loadDictionary` / `ZstdDecompressCtx.loadDictionary`; `ZstdOutputStream` / `ZstdInputStream` dictionary constructors |
+| `ZSTD_CCtx_refCDict`, `ZSTD_DCtx_refDDict` | `ZstdCompressCtx.refDictionary` / `ZstdDecompressCtx.refDictionary` |
 | `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`) |
 | `ZSTD_getFrameProgression` | `ZstdCompressStream.progress()` (`ZstdFrameProgression`) |
@@ -91,7 +92,7 @@ zstd-jni's JNI sources (v1.5.7-11, `src/main/native/*.c`). The latter is
 symbol-exact, not functional equivalence: zstd-jni may expose an operation through
 a different symbol than this library — e.g. it routes one-shot compression through
 `ZSTD_compress2`, so `ZSTD_compress` reads `—` for it even though `Zstd.compress`
-works. zstd-jni references 53 of these symbols; this library binds 57. They
+works. zstd-jni references 53 of these symbols; this library binds 59. They
 overlap on the modern context/streaming API and diverge mainly on zstd-jni's
 sequence-producer hooks vs this library's frame-inspection and typed-error surface.
 
@@ -232,7 +233,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_resetDStream` | — ᵈ | — |
 | `ZSTD_sizeof_DStream` | — | — |
 
-### Advanced parameters (10/38)
+### Advanced parameters (12/38)
 
 | Symbol | Bound | zstd-jni |
 |---|:---:|:---:|
@@ -246,7 +247,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_CCtx_loadDictionary` | ✅ | ✅ |
 | `ZSTD_CCtx_loadDictionary_advanced` | — | — |
 | `ZSTD_CCtx_loadDictionary_byReference` | — | — |
-| `ZSTD_CCtx_refCDict` | — | ✅ |
+| `ZSTD_CCtx_refCDict` | ✅ | ✅ |
 | `ZSTD_CCtx_refPrefix` | — | — |
 | `ZSTD_CCtx_refPrefix_advanced` | — | — |
 | `ZSTD_CCtx_refThreadPool` | — | — |
@@ -261,7 +262,7 @@ sequence-producer hooks vs this library's frame-inspection and typed-error surfa
 | `ZSTD_DCtx_loadDictionary` | ✅ | ✅ |
 | `ZSTD_DCtx_loadDictionary_advanced` | — | — |
 | `ZSTD_DCtx_loadDictionary_byReference` | — | — |
-| `ZSTD_DCtx_refDDict` | — | ✅ |
+| `ZSTD_DCtx_refDDict` | ✅ | ✅ |
 | `ZSTD_DCtx_refPrefix` | — | — |
 | `ZSTD_DCtx_refPrefix_advanced` | — | — |
 | `ZSTD_DCtx_reset` | ✅ | ✅ |

integration-tests/src/test/java/io/github/dfa1/zstd/it/ZstdJniInteropTest.java

@@ -4,6 +4,7 @@
 import com.github.luben.zstd.ZstdDictDecompress;
 import io.github.dfa1.zstd.Zstd;
 import io.github.dfa1.zstd.ZstdCompressCtx;
+import io.github.dfa1.zstd.ZstdCompressDict;
 import io.github.dfa1.zstd.ZstdDecompressCtx;
 import io.github.dfa1.zstd.ZstdDictionary;
 import io.github.dfa1.zstd.ZstdInputStream;
@@ -124,6 +125,39 @@ void jniDictCompressJavaDictDecompress() {
             assertThat(restored).isEqualTo(record);
         }
 
+        @Test
+        void javaLoadedDictWithChecksumJniDictDecompress() {
+            // A sticky loaded dictionary combined with an advanced parameter
+            // (checksum) — the COMPRESS2 path — must still produce a frame zstd-jni
+            // decodes against the same dictionary.
+            ZstdDictionary dict = trainDict();
+            byte[] record = record(33);
+
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().checksum(true)) {
+                ctx.loadDictionary(dict);
+                frame = ctx.compress(record);
+            }
+            ZstdDictDecompress jniDict = new ZstdDictDecompress(dict.toByteArray());
+            assertThat(com.github.luben.zstd.Zstd.decompress(frame, jniDict, record.length)).isEqualTo(record);
+        }
+
+        @Test
+        void javaReferencedDigestedDictJniDictDecompress() {
+            // A frame from a context referencing a digested CDict must decode in zstd-jni.
+            ZstdDictionary dict = trainDict();
+            byte[] record = record(44);
+
+            byte[] frame;
+            try (ZstdCompressDict cdict = new ZstdCompressDict(dict, Zstd.defaultCompressionLevel());
+                 ZstdCompressCtx ctx = new ZstdCompressCtx()) {
+                ctx.refDictionary(cdict);
+                frame = ctx.compress(record);
+            }
+            ZstdDictDecompress jniDict = new ZstdDictDecompress(dict.toByteArray());
+            assertThat(com.github.luben.zstd.Zstd.decompress(frame, jniDict, record.length)).isEqualTo(record);
+        }
+
         private ZstdDictionary trainDict() {
             List<byte[]> samples = new ArrayList<>();
             for (int i = 0; i < 3000; i++) {

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

@@ -248,6 +248,10 @@ final class Bindings {
     static final MethodHandle COMPRESS_USING_CDICT =
             NativeLibrary.lookup("ZSTD_compress_usingCDict",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS));
+    // size_t ZSTD_CCtx_refCDict(ZSTD_CCtx*, const ZSTD_CDict*)
+    static final MethodHandle CCTX_REF_CDICT =
+            NativeLibrary.lookup("ZSTD_CCtx_refCDict",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS));
 
     // ZSTD_DDict* ZSTD_createDDict(const void* dict, size_t dictSize)
     static final MethodHandle CREATE_DDICT =
@@ -260,6 +264,10 @@ final class Bindings {
     static final MethodHandle DECOMPRESS_USING_DDICT =
             NativeLibrary.lookup("ZSTD_decompress_usingDDict",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS));
+    // size_t ZSTD_DCtx_refDDict(ZSTD_DCtx*, const ZSTD_DDict*)
+    static final MethodHandle DCTX_REF_DDICT =
+            NativeLibrary.lookup("ZSTD_DCtx_refDDict",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS));
 
     // --- dictionary training (ZDICT, from dictBuilder) ---
 

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

@@ -114,6 +114,71 @@ public ZstdCompressCtx reset(ZstdResetDirective directive) {
         return this;
     }
 
+    /// Loads `dict` as the sticky dictionary for this context, so subsequent
+    /// [#compress(byte[])] / [#compress(MemorySegment, MemorySegment)] calls
+    /// compress against it **while still honouring the advanced parameters**
+    /// (checksum, window log, long-distance matching) set on this context — the
+    /// combination the per-call `compress(src, dict)` overloads cannot give you,
+    /// since they route through the legacy dictionary path.
+    ///
+    /// The dictionary is digested using this context's current level and
+    /// parameters and copied internally, so `dict` may be discarded afterwards.
+    /// It stays loaded until replaced, cleared with [#loadDictionary(ZstdDictionary)]
+    /// passing `null`, or dropped by a parameter [#reset(ZstdResetDirective)]. For
+    /// a dictionary reused across many contexts, digest it once and attach it with
+    /// [#refDictionary(ZstdCompressDict)] instead.
+    ///
+    /// @param dict the dictionary to load, or `null` to clear the loaded dictionary
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be loaded
+    public ZstdCompressCtx loadDictionary(ZstdDictionary dict) {
+        if (dict == null) {
+            return loadDictionary(MemorySegment.NULL, 0L);
+        }
+        try (Arena arena = Arena.ofConfined()) {
+            byte[] raw = dict.raw();
+            return loadDictionary(Zstd.copyIn(arena, raw), raw.length);
+        }
+    }
+
+    /// Loads dictionary content straight from a native [MemorySegment], without a
+    /// heap copy — the zero-copy path when your dictionary is already off-heap
+    /// (e.g. an mmap slice). Otherwise identical to
+    /// [#loadDictionary(ZstdDictionary)].
+    ///
+    /// @param dict native dictionary content; its bytes are copied into the context
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be loaded
+    public ZstdCompressCtx loadDictionary(MemorySegment dict) {
+        NativeCall.requireNative(dict, "dict");
+        return loadDictionary(dict, dict.byteSize());
+    }
+
+    private ZstdCompressCtx loadDictionary(MemorySegment dict, long size) {
+        NativeCall.checkReturnValue(() -> (long) Bindings.CCTX_LOAD_DICTIONARY.invokeExact(ptr(), dict, size));
+        return this;
+    }
+
+    /// Attaches a pre-digested `dict` to this context by reference — no per-call
+    /// digesting and no copy. Subsequent [#compress(byte[])] /
+    /// [#compress(MemorySegment, MemorySegment)] calls compress against it while
+    /// honouring this context's advanced parameters; the compression level comes
+    /// from the [ZstdCompressDict]. This is the hot path for a pooled context
+    /// recycled with [#reset(ZstdResetDirective)] between frames.
+    ///
+    /// The reference is borrowed: `dict` must stay open for as long as this
+    /// context uses it. The reference is dropped by a parameter
+    /// [#reset(ZstdResetDirective)] or by passing `null`.
+    ///
+    /// @param dict the digested dictionary to reference, or `null` to clear it
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be referenced
+    public ZstdCompressCtx refDictionary(ZstdCompressDict dict) {
+        MemorySegment cdict = dict == null ? MemorySegment.NULL : dict.ptr();
+        NativeCall.checkReturnValue(() -> (long) Bindings.CCTX_REF_CDICT.invokeExact(ptr(), cdict));
+        return this;
+    }
+
     /// Compresses `src` into a new zstd frame using this context and its
     /// advanced parameters.
     ///

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

@@ -69,6 +69,67 @@ public ZstdDecompressCtx reset(ZstdResetDirective directive) {
         return this;
     }
 
+    /// Loads `dict` as the sticky dictionary for this context, so subsequent
+    /// [#decompress(byte[], int)] / [#decompress(MemorySegment, MemorySegment)]
+    /// calls decode frames compressed against it while still honouring the
+    /// advanced parameters (e.g. window-log max) set on this context.
+    ///
+    /// The dictionary is copied internally, so `dict` may be discarded afterwards.
+    /// It stays loaded until replaced, cleared with [#loadDictionary(ZstdDictionary)]
+    /// passing `null`, or dropped by a parameter [#reset(ZstdResetDirective)]. For
+    /// a dictionary reused across many contexts, digest it once and attach it with
+    /// [#refDictionary(ZstdDecompressDict)] instead.
+    ///
+    /// @param dict the dictionary to load, or `null` to clear the loaded dictionary
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be loaded
+    public ZstdDecompressCtx loadDictionary(ZstdDictionary dict) {
+        if (dict == null) {
+            return loadDictionary(MemorySegment.NULL, 0L);
+        }
+        try (Arena arena = Arena.ofConfined()) {
+            byte[] raw = dict.raw();
+            return loadDictionary(Zstd.copyIn(arena, raw), raw.length);
+        }
+    }
+
+    /// Loads dictionary content straight from a native [MemorySegment], without a
+    /// heap copy — the zero-copy path when your dictionary is already off-heap
+    /// (e.g. an mmap slice). Otherwise identical to
+    /// [#loadDictionary(ZstdDictionary)].
+    ///
+    /// @param dict native dictionary content; its bytes are copied into the context
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be loaded
+    public ZstdDecompressCtx loadDictionary(MemorySegment dict) {
+        NativeCall.requireNative(dict, "dict");
+        return loadDictionary(dict, dict.byteSize());
+    }
+
+    private ZstdDecompressCtx loadDictionary(MemorySegment dict, long size) {
+        NativeCall.checkReturnValue(() -> (long) Bindings.DCTX_LOAD_DICTIONARY.invokeExact(ptr(), dict, size));
+        return this;
+    }
+
+    /// Attaches a pre-digested `dict` to this context by reference — no per-call
+    /// digesting and no copy. Subsequent [#decompress(byte[], int)] /
+    /// [#decompress(MemorySegment, MemorySegment)] calls decode against it while
+    /// honouring this context's advanced parameters. This is the hot path for a
+    /// pooled context recycled with [#reset(ZstdResetDirective)] between frames.
+    ///
+    /// The reference is borrowed: `dict` must stay open for as long as this
+    /// context uses it. The reference is dropped by a parameter
+    /// [#reset(ZstdResetDirective)] or by passing `null`.
+    ///
+    /// @param dict the digested dictionary to reference, or `null` to clear it
+    /// @return `this`, for chaining
+    /// @throws ZstdException if the dictionary cannot be referenced
+    public ZstdDecompressCtx refDictionary(ZstdDecompressDict dict) {
+        MemorySegment ddict = dict == null ? MemorySegment.NULL : dict.ptr();
+        NativeCall.checkReturnValue(() -> (long) Bindings.DCTX_REF_DDICT.invokeExact(ptr(), ddict));
+        return this;
+    }
+
     /// Decompresses a frame into a buffer of at most `maxSize` bytes.
     ///
     /// @param compressed a complete zstd frame