feat: memory accounting — sizeOf() + estimate*Size

- live memory: sizeOf() on ZstdCompressCtx/DecompressCtx, ZstdCompressDict/
  DecompressDict, ZstdCompressStream/DecompressStream (ZSTD_sizeof_C/DCtx,
  ZSTD_sizeof_C/DDict)
- static estimates for budgeting before allocation: Zstd.estimateCompress/
  DecompressContextSize, estimateCompress/DecompressDictSize (ZSTD_estimate*Size)
- 68/186 symbols bound

Tests: estimates positive and monotonic in level; context size grows after use;
contexts/dicts/streams all report a positive live size.

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

Author: dfa1

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

@@ -285,6 +285,30 @@ final class Bindings {
             NativeLibrary.lookup("ZDICT_getDictHeaderSize",
                     FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_LONG));
 
+    // --- memory accounting ---
+
+    // size_t ZSTD_sizeof_CCtx / DCtx / CDict / DDict (live memory of an object)
+    static final MethodHandle SIZEOF_CCTX =
+            NativeLibrary.lookup("ZSTD_sizeof_CCtx", FunctionDescriptor.of(JAVA_LONG, ADDRESS));
+    static final MethodHandle SIZEOF_DCTX =
+            NativeLibrary.lookup("ZSTD_sizeof_DCtx", FunctionDescriptor.of(JAVA_LONG, ADDRESS));
+    static final MethodHandle SIZEOF_CDICT =
+            NativeLibrary.lookup("ZSTD_sizeof_CDict", FunctionDescriptor.of(JAVA_LONG, ADDRESS));
+    static final MethodHandle SIZEOF_DDICT =
+            NativeLibrary.lookup("ZSTD_sizeof_DDict", FunctionDescriptor.of(JAVA_LONG, ADDRESS));
+
+    // size_t ZSTD_estimateCCtxSize(int level) / ZSTD_estimateDCtxSize(void)
+    static final MethodHandle ESTIMATE_CCTX_SIZE =
+            NativeLibrary.lookup("ZSTD_estimateCCtxSize", FunctionDescriptor.of(JAVA_LONG, JAVA_INT));
+    static final MethodHandle ESTIMATE_DCTX_SIZE =
+            NativeLibrary.lookup("ZSTD_estimateDCtxSize", FunctionDescriptor.of(JAVA_LONG));
+    // size_t ZSTD_estimateCDictSize(size_t dictSize, int level)
+    static final MethodHandle ESTIMATE_CDICT_SIZE =
+            NativeLibrary.lookup("ZSTD_estimateCDictSize", FunctionDescriptor.of(JAVA_LONG, JAVA_LONG, JAVA_INT));
+    // size_t ZSTD_estimateDDictSize(size_t dictSize, ZSTD_dictLoadMethod_e dlm)
+    static final MethodHandle ESTIMATE_DDICT_SIZE =
+            NativeLibrary.lookup("ZSTD_estimateDDictSize", FunctionDescriptor.of(JAVA_LONG, JAVA_LONG, JAVA_INT));
+
     private Bindings() {
         // no instances
     }

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

@@ -162,6 +162,57 @@ public static int defaultCompressionLevel() {
         }
     }
 
+    /// Estimates the memory a compression context will use at `level`, before
+    /// creating one — useful for budgeting.
+    ///
+    /// @param level the compression level
+    /// @return the estimated context size in bytes
+    public static long estimateCompressContextSize(int level) {
+        try {
+            return (long) Bindings.ESTIMATE_CCTX_SIZE.invokeExact(level);
+        } catch (Throwable t) {
+            throw sneaky(t);
+        }
+    }
+
+    /// Estimates the memory a decompression context will use.
+    ///
+    /// @return the estimated context size in bytes
+    public static long estimateDecompressContextSize() {
+        try {
+            return (long) Bindings.ESTIMATE_DCTX_SIZE.invokeExact();
+        } catch (Throwable t) {
+            throw sneaky(t);
+        }
+    }
+
+    /// Estimates the memory a digested compression dictionary of `dictSize` bytes
+    /// will use at `level`.
+    ///
+    /// @param dictSize the raw dictionary size in bytes
+    /// @param level    the compression level
+    /// @return the estimated digested-dictionary size in bytes
+    public static long estimateCompressDictSize(long dictSize, int level) {
+        try {
+            return (long) Bindings.ESTIMATE_CDICT_SIZE.invokeExact(dictSize, level);
+        } catch (Throwable t) {
+            throw sneaky(t);
+        }
+    }
+
+    /// Estimates the memory a digested decompression dictionary of `dictSize`
+    /// bytes will use.
+    ///
+    /// @param dictSize the raw dictionary size in bytes
+    /// @return the estimated digested-dictionary size in bytes
+    public static long estimateDecompressDictSize(long dictSize) {
+        try {
+            return (long) Bindings.ESTIMATE_DDICT_SIZE.invokeExact(dictSize, 0); // ZSTD_dlm_byCopy
+        } catch (Throwable t) {
+            throw sneaky(t);
+        }
+    }
+
     /// Runtime zstd version, e.g. `"1.6.0"`.
     ///
     /// @return the linked zstd library version as an `x.y.z` string

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

@@ -205,6 +205,17 @@ public MemorySegment compress(Arena arena, MemorySegment src, ZstdCompressDict d
         return dst.asSlice(0, written);
     }
 
+    /// Current native memory used by this context, in bytes.
+    ///
+    /// @return the live context size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_CCTX.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         long ignored = (long) Bindings.FREE_CCTX.invokeExact(ptr);

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

@@ -62,6 +62,17 @@ public int id() {
         }
     }
 
+    /// Current native memory used by this digested dictionary, in bytes.
+    ///
+    /// @return the live dictionary size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_CDICT.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         long ignored = (long) Bindings.FREE_CDICT.invokeExact(ptr);

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

@@ -113,6 +113,17 @@ public ZstdFrameProgression progress() {
         }
     }
 
+    /// Current native memory used by this stream's context, in bytes.
+    ///
+    /// @return the live context size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_CCTX.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         try {

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

@@ -165,6 +165,17 @@ public MemorySegment decompress(Arena arena, MemorySegment frame, ZstdDecompress
         return out;
     }
 
+    /// Current native memory used by this context, in bytes.
+    ///
+    /// @return the live context size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_DCTX.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         long ignored = (long) Bindings.FREE_DCTX.invokeExact(ptr);

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

@@ -43,6 +43,17 @@ public int id() {
         }
     }
 
+    /// Current native memory used by this digested dictionary, in bytes.
+    ///
+    /// @return the live dictionary size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_DDICT.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         long ignored = (long) Bindings.FREE_DDICT.invokeExact(ptr);

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

@@ -66,6 +66,17 @@ public ZstdStreamResult decompress(MemorySegment dst, MemorySegment src) {
         return new ZstdStreamResult(in.pos(), out.pos(), remaining);
     }
 
+    /// Current native memory used by this stream's context, in bytes.
+    ///
+    /// @return the live context size
+    public long sizeOf() {
+        try {
+            return (long) Bindings.SIZEOF_DCTX.invokeExact(ptr());
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     @Override
     protected void tryClose(MemorySegment ptr) throws Throwable {
         try {

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

@@ -0,0 +1,86 @@
+package io.github.dfa1.zstd;
+
+import org.junit.jupiter.api.Nested;
+import org.junit.jupiter.api.Test;
+
+import java.nio.charset.StandardCharsets;
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class ZstdMemoryTest {
+
+    private static final byte[] PAYLOAD = "memory accounting ".repeat(500).getBytes(StandardCharsets.UTF_8);
+
+    @Nested
+    class Estimates {
+
+        @Test
+        void contextEstimatesArePositive() {
+            assertThat(Zstd.estimateCompressContextSize(3)).isPositive();
+            assertThat(Zstd.estimateDecompressContextSize()).isPositive();
+        }
+
+        @Test
+        void higherLevelEstimatesAtLeastAsLarge() {
+            assertThat(Zstd.estimateCompressContextSize(19))
+                    .isGreaterThanOrEqualTo(Zstd.estimateCompressContextSize(1));
+        }
+
+        @Test
+        void dictionaryEstimatesArePositive() {
+            assertThat(Zstd.estimateCompressDictSize(64 * 1024, 3)).isPositive();
+            assertThat(Zstd.estimateDecompressDictSize(64 * 1024)).isPositive();
+        }
+    }
+
+    @Nested
+    class LiveSizes {
+
+        @Test
+        void contextSizeGrowsAfterUse() {
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx()) {
+                long before = ctx.sizeOf();
+                ctx.compress(PAYLOAD);
+                long after = ctx.sizeOf();
+                assertThat(before).isPositive();
+                assertThat(after).isGreaterThanOrEqualTo(before);
+            }
+        }
+
+        @Test
+        void decompressContextHasSize() {
+            try (ZstdDecompressCtx ctx = new ZstdDecompressCtx()) {
+                assertThat(ctx.sizeOf()).isPositive();
+            }
+        }
+
+        @Test
+        void digestedDictionariesHaveSize() {
+            ZstdDictionary dict = trainDict();
+            try (ZstdCompressDict cdict = new ZstdCompressDict(dict);
+                 ZstdDecompressDict ddict = new ZstdDecompressDict(dict)) {
+                assertThat(cdict.sizeOf()).isPositive();
+                assertThat(ddict.sizeOf()).isPositive();
+            }
+        }
+
+        @Test
+        void streamsReportContextSize() {
+            try (ZstdCompressStream cs = new ZstdCompressStream();
+                 ZstdDecompressStream ds = new ZstdDecompressStream()) {
+                assertThat(cs.sizeOf()).isPositive();
+                assertThat(ds.sizeOf()).isPositive();
+            }
+        }
+
+        private ZstdDictionary trainDict() {
+            List<byte[]> samples = new ArrayList<>();
+            for (int i = 0; i < 2000; i++) {
+                samples.add(("{\"id\":" + i + ",\"k\":\"v" + (i % 20) + "\"}").getBytes(StandardCharsets.UTF_8));
+            }
+            return ZstdDictionary.train(samples, 8 * 1024);
+        }
+    }
+}