feat: COVER / fast-COVER dictionary training

ZstdDictionary.trainCover / trainFastCover auto-tune dictionary parameters for
higher quality than the default trainFromBuffer (fast-COVER is the recommended
optimiser — near-COVER quality, much faster). Optional compressionLevel overload
optimises for a target level.

- bind ZDICT_optimizeTrainFromBuffer_cover / _fastCover (params passed by
  pointer; a zeroed struct auto-tunes k/d/steps, single-threaded, target level)
- 58/186 symbols bound

Tests: fast-COVER dict round-trips and beats dictionaryless on a tiny record;
COVER round-trips (trained on a subset to stay quick).

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

Author: dfa1

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

@@ -261,6 +261,16 @@ final class Bindings {
     static final MethodHandle ZDICT_GET_DICT_ID =
             NativeLibrary.lookup("ZDICT_getDictID", FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_LONG));
 
+    // size_t ZDICT_optimizeTrainFromBuffer_cover(dictBuffer, dictCap, samples, sizes, nbSamples,
+    //                                            ZDICT_cover_params_t* parameters)  [params auto-tuned in place]
+    static final MethodHandle ZDICT_OPTIMIZE_COVER =
+            NativeLibrary.lookup("ZDICT_optimizeTrainFromBuffer_cover",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS, ADDRESS, JAVA_INT, ADDRESS));
+    // size_t ZDICT_optimizeTrainFromBuffer_fastCover(..., ZDICT_fastCover_params_t* parameters)
+    static final MethodHandle ZDICT_OPTIMIZE_FASTCOVER =
+            NativeLibrary.lookup("ZDICT_optimizeTrainFromBuffer_fastCover",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS, ADDRESS, JAVA_INT, ADDRESS));
+
     private Bindings() {
         // no instances
     }

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

@@ -2,10 +2,12 @@
 
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
+import java.lang.invoke.MethodHandle;
 import java.nio.charset.StandardCharsets;
 import java.util.List;
 
 import static java.lang.foreign.ValueLayout.JAVA_BYTE;
+import static java.lang.foreign.ValueLayout.JAVA_INT;
 import static java.lang.foreign.ValueLayout.JAVA_LONG;
 
 /// An immutable zstd dictionary — the feature that makes compressing many small,
@@ -86,6 +88,95 @@ public static ZstdDictionary train(List<byte[]> samples, int maxDictBytes) {
         }
     }
 
+    /// Trains a dictionary with the COVER algorithm, auto-tuning its parameters
+    /// for the best dictionary it can find. Higher quality than {@link #train},
+    /// but slower; for a faster near-equal result use {@link #trainFastCover}.
+    ///
+    /// @param samples      representative payloads to learn from
+    /// @param maxDictBytes upper bound on the produced dictionary size
+    /// @return the trained dictionary
+    /// @throws ZstdException if training fails
+    public static ZstdDictionary trainCover(List<byte[]> samples, int maxDictBytes) {
+        return trainCover(samples, maxDictBytes, 0);
+    }
+
+    /// Trains a COVER dictionary optimised for a specific compression level.
+    ///
+    /// @param samples          representative payloads to learn from
+    /// @param maxDictBytes     upper bound on the produced dictionary size
+    /// @param compressionLevel the level the dictionary will be used at (0 = default)
+    /// @return the trained dictionary
+    /// @throws ZstdException if training fails
+    public static ZstdDictionary trainCover(List<byte[]> samples, int maxDictBytes, int compressionLevel) {
+        return optimize(samples, maxDictBytes, compressionLevel, false);
+    }
+
+    /// Trains a dictionary with the fast COVER algorithm, auto-tuning its
+    /// parameters. The recommended optimiser: nearly the quality of
+    /// {@link #trainCover} at a fraction of the time.
+    ///
+    /// @param samples      representative payloads to learn from
+    /// @param maxDictBytes upper bound on the produced dictionary size
+    /// @return the trained dictionary
+    /// @throws ZstdException if training fails
+    public static ZstdDictionary trainFastCover(List<byte[]> samples, int maxDictBytes) {
+        return trainFastCover(samples, maxDictBytes, 0);
+    }
+
+    /// Trains a fast COVER dictionary optimised for a specific compression level.
+    ///
+    /// @param samples          representative payloads to learn from
+    /// @param maxDictBytes     upper bound on the produced dictionary size
+    /// @param compressionLevel the level the dictionary will be used at (0 = default)
+    /// @return the trained dictionary
+    /// @throws ZstdException if training fails
+    public static ZstdDictionary trainFastCover(List<byte[]> samples, int maxDictBytes, int compressionLevel) {
+        return optimize(samples, maxDictBytes, compressionLevel, true);
+    }
+
+    private static ZstdDictionary optimize(List<byte[]> samples, int maxDictBytes,
+                                           int compressionLevel, boolean fast) {
+        if (samples.isEmpty()) {
+            throw new ZstdException("cannot train a dictionary from zero samples");
+        }
+        try (Arena arena = Arena.ofConfined()) {
+            long total = 0;
+            for (byte[] s : samples) {
+                total += s.length;
+            }
+            MemorySegment flat = arena.allocate(Math.max(total, 1));
+            MemorySegment sizes = arena.allocate(JAVA_LONG, samples.size());
+            long offset = 0;
+            for (int i = 0; i < samples.size(); i++) {
+                byte[] s = samples.get(i);
+                MemorySegment.copy(s, 0, flat, JAVA_BYTE, offset, s.length);
+                sizes.setAtIndex(JAVA_LONG, i, s.length);
+                offset += s.length;
+            }
+            // zeroed params (auto-tune k/d/steps); set single-threaded + target level.
+            // fastCover: nbThreads@16, compressionLevel@44, size 56.
+            // cover:     nbThreads@12, compressionLevel@32, size 48.
+            MemorySegment params = arena.allocate(fast ? 56 : 48);
+            params.set(JAVA_INT, fast ? 16 : 12, 1);
+            params.set(JAVA_INT, fast ? 44 : 32, compressionLevel);
+            MethodHandle handle = fast ? Bindings.ZDICT_OPTIMIZE_FASTCOVER : Bindings.ZDICT_OPTIMIZE_COVER;
+            MemorySegment dictBuf = arena.allocate(maxDictBytes);
+            long produced;
+            try {
+                produced = (long) handle.invokeExact(
+                        dictBuf, (long) maxDictBytes, flat, sizes, samples.size(), params);
+            } catch (Throwable t) {
+                throw rethrow(t);
+            }
+            if (zdictIsError(produced)) {
+                throw new ZstdException("dictionary training failed: " + zdictErrorName(produced));
+            }
+            byte[] out = new byte[Math.toIntExact(produced)];
+            MemorySegment.copy(dictBuf, JAVA_BYTE, 0, out, 0, out.length);
+            return new ZstdDictionary(out);
+        }
+    }
+
     /// The dictionary id zstd stamps into frames compressed with this dictionary,
     /// or `0` for a raw/content-only dictionary with no header.
     ///

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

@@ -30,6 +30,45 @@ void trainDictionary() {
         sut = ZstdDictionary.train(samples, 16 * 1024);
     }
 
+    @Nested
+    class CoverTraining {
+
+        @Test
+        void fastCoverRoundTrips() {
+            // Given a fast-COVER-trained dictionary
+            ZstdDictionary dict = ZstdDictionary.trainFastCover(samples, 16 * 1024);
+            assertThat(dict.size()).isGreaterThan(0);
+
+            // Then records round-trip and compress smaller than dictionaryless
+            byte[] record = samples.get(321);
+            byte[] plain;
+            byte[] withDict;
+            byte[] restored;
+            try (ZstdCompressCtx cctx = new ZstdCompressCtx();
+                 ZstdDecompressCtx dctx = new ZstdDecompressCtx()) {
+                plain = cctx.compress(record);
+                withDict = cctx.compress(record, dict);
+                restored = dctx.decompress(cctx.compress(record, dict), record.length, dict);
+            }
+            assertThat(withDict.length).isLessThan(plain.length);
+            assertThat(restored).isEqualTo(record);
+        }
+
+        @Test
+        void coverRoundTrips() {
+            // COVER is slower, so train on a subset to keep the test quick
+            ZstdDictionary dict = ZstdDictionary.trainCover(samples.subList(0, 1000), 8 * 1024);
+            assertThat(dict.size()).isGreaterThan(0);
+
+            byte[] record = samples.get(5);
+            try (ZstdCompressCtx cctx = new ZstdCompressCtx();
+                 ZstdDecompressCtx dctx = new ZstdDecompressCtx()) {
+                byte[] frame = cctx.compress(record, dict);
+                assertThat(dctx.decompress(frame, record.length, dict)).isEqualTo(record);
+            }
+        }
+    }
+
     @Nested
     class Training {