feat: frame header parsing + skippable frames

- ZstdFrame.header(): parse a frame header without decompressing, into a
  ZstdFrameHeader record (content size, window size, frame type, dict id,
  checksum flag) via ZSTD_getFrameHeader
- skippable frames: writeSkippableFrame / readSkippableFrame (ZstdSkippableContent)
  / isSkippableFrame — embed and read arbitrary metadata a decoder skips
- ZstdFrameType enum (STANDARD / SKIPPABLE)
- bind ZSTD_getFrameHeader, ZSTD_isSkippableFrame, ZSTD_writeSkippableFrame,
  ZSTD_readSkippableFrame; compatibility.md now 48/186

Tests: header reports content size / checksum flag / type; skippable frame
round-trips content + magic variant; standard frame is not skippable.

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: **44** (~24%)
+- Bound so far: **48** (~26%)
 
 "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
@@ -28,7 +28,7 @@ low-level variants that an idiomatic Java API does not need.
 | 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 |
-| Frame inspection | 5 / 13 | `ZstdFrame`: isFrame, compressedSize, decompressedBound, dictId, + getFrameContentSize; getFrameHeader/skippable not bound |
+| 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 |
 | Sequences | 0 / 5 | sequence producer API not bound |
@@ -56,14 +56,14 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_decompressStream`, `ZSTD_DStreamInSize`, `ZSTD_DStreamOutSize` | `ZstdInputStream` |
 | `ZSTD_compress2`, `ZSTD_CCtx_setParameter` | `ZstdCompressCtx.parameter` / `checksum` / `longDistanceMatching` / `windowLog` (+ `ZstdCompressParameter`) |
 | `ZSTD_CCtx_loadDictionary`, `ZSTD_DCtx_loadDictionary` | `ZstdOutputStream` / `ZstdInputStream` dictionary constructors |
-| `ZSTD_isFrame`, `ZSTD_findFrameCompressedSize`, `ZSTD_decompressBound`, `ZSTD_getDictID_fromFrame` | `ZstdFrame` |
+| `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).
-3. **Frame inspection** — done: `ZstdFrame` (`isFrame`, `compressedSize`, `decompressedBound`, `dictId`). Remaining: `getFrameHeader` (struct out-param), skippable frames, `getDictID_fromDict/CDict/DDict`.
+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`).
 
@@ -247,7 +247,7 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_estimateCCtxSize_usingCCtxParams` | — |
 | `ZSTD_freeCCtxParams` | — |
 
-### Frame inspection (5/13)
+### Frame inspection (9/13)
 
 | Symbol | Bound |
 |---|:---:|
@@ -257,13 +257,13 @@ low-level variants that an idiomatic Java API does not need.
 | `ZSTD_findFrameCompressedSize` | ✅ |
 | `ZSTD_frameHeaderSize` | — |
 | `ZSTD_getDecompressedSize` | — |
-| `ZSTD_getFrameHeader` | — |
+| `ZSTD_getFrameHeader` | ✅ |
 | `ZSTD_getFrameHeader_advanced` | — |
 | `ZSTD_getFrameProgression` | — |
 | `ZSTD_isFrame` | ✅ |
-| `ZSTD_isSkippableFrame` | — |
-| `ZSTD_readSkippableFrame` | — |
-| `ZSTD_writeSkippableFrame` | — |
+| `ZSTD_isSkippableFrame` | ✅ |
+| `ZSTD_readSkippableFrame` | ✅ |
+| `ZSTD_writeSkippableFrame` | ✅ |
 
 ### Memory sizing (0/14)
 

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

@@ -51,6 +51,22 @@ final class Bindings {
     static final MethodHandle GET_DICT_ID_FROM_FRAME =
             NativeLibrary.lookup("ZSTD_getDictID_fromFrame",
                     FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_LONG));
+    // size_t ZSTD_getFrameHeader(ZSTD_FrameHeader* zfh, const void* src, size_t srcSize)
+    static final MethodHandle GET_FRAME_HEADER =
+            NativeLibrary.lookup("ZSTD_getFrameHeader",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG));
+    // unsigned ZSTD_isSkippableFrame(const void* buffer, size_t size)
+    static final MethodHandle IS_SKIPPABLE_FRAME =
+            NativeLibrary.lookup("ZSTD_isSkippableFrame",
+                    FunctionDescriptor.of(JAVA_INT, ADDRESS, JAVA_LONG));
+    // size_t ZSTD_writeSkippableFrame(void* dst, size_t dstCap, const void* src, size_t srcSize, unsigned magicVariant)
+    static final MethodHandle WRITE_SKIPPABLE_FRAME =
+            NativeLibrary.lookup("ZSTD_writeSkippableFrame",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS, JAVA_LONG, JAVA_INT));
+    // size_t ZSTD_readSkippableFrame(void* dst, size_t dstCap, unsigned* magicVariant, const void* src, size_t srcSize)
+    static final MethodHandle READ_SKIPPABLE_FRAME =
+            NativeLibrary.lookup("ZSTD_readSkippableFrame",
+                    FunctionDescriptor.of(JAVA_LONG, ADDRESS, JAVA_LONG, ADDRESS, ADDRESS, JAVA_LONG));
 
     // unsigned ZSTD_isError(size_t code)
     static final MethodHandle IS_ERROR =

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

@@ -3,6 +3,9 @@
 import java.lang.foreign.Arena;
 import java.lang.foreign.MemorySegment;
 
+import static java.lang.foreign.ValueLayout.JAVA_INT;
+import static java.lang.foreign.ValueLayout.JAVA_LONG;
+
 /// Inspection of zstd frames without decompressing them — useful for parsing a
 /// stream of concatenated frames, sizing buffers, or routing by dictionary id.
 ///
@@ -92,6 +95,105 @@ public static int dictId(MemorySegment data) {
         return dictId(data, data.byteSize());
     }
 
+    /// Parses the header of the first frame in `data` without decompressing it.
+    ///
+    /// @param data a complete zstd frame (or at least its header)
+    /// @return the parsed frame header
+    /// @throws ZstdException if the input is not a valid frame or the header is incomplete
+    public static ZstdFrameHeader header(byte[] data) {
+        try (Arena arena = Arena.ofConfined()) {
+            return header(Zstd.copyIn(arena, data), data.length);
+        }
+    }
+
+    /// Parses the header of the first frame in native `data`.
+    ///
+    /// @param data a complete zstd frame (or at least its header)
+    /// @return the parsed frame header
+    /// @throws ZstdException if the input is not a valid frame or the header is incomplete
+    public static ZstdFrameHeader header(MemorySegment data) {
+        return header(data, data.byteSize());
+    }
+
+    /// Tests whether `data` begins with a skippable frame (user data a decoder ignores).
+    ///
+    /// @param data the bytes to inspect
+    /// @return `true` if `data` starts with a skippable frame
+    public static boolean isSkippableFrame(byte[] data) {
+        try (Arena arena = Arena.ofConfined()) {
+            return isSkippableFrame(Zstd.copyIn(arena, data), data.length);
+        }
+    }
+
+    /// Tests whether native `data` begins with a skippable frame.
+    ///
+    /// @param data the native bytes to inspect
+    /// @return `true` if `data` starts with a skippable frame
+    public static boolean isSkippableFrame(MemorySegment data) {
+        return isSkippableFrame(data, data.byteSize());
+    }
+
+    /// Wraps `content` in a skippable frame — arbitrary metadata that a zstd
+    /// decoder skips over, letting you interleave it with compressed frames.
+    ///
+    /// @param content      the user bytes to embed
+    /// @param magicVariant the variant 0..15 selecting one of the skippable magic numbers
+    /// @return the skippable frame bytes
+    /// @throws ZstdException if `magicVariant` is out of range
+    public static byte[] writeSkippableFrame(byte[] content, int magicVariant) {
+        try (Arena arena = Arena.ofConfined()) {
+            MemorySegment src = Zstd.copyIn(arena, content);
+            long cap = content.length + 8L;
+            MemorySegment dst = arena.allocate(cap);
+            long written = Zstd.call(() -> (long) Bindings.WRITE_SKIPPABLE_FRAME.invokeExact(
+                    dst, cap, src, (long) content.length, magicVariant));
+            return Zstd.copyOut(dst, written);
+        }
+    }
+
+    /// Reads the content of a skippable frame produced by
+    /// [#writeSkippableFrame(byte[], int)].
+    ///
+    /// @param frame a skippable frame
+    /// @return the embedded content and its magic variant
+    /// @throws ZstdException if `frame` is not a skippable frame
+    public static ZstdSkippableContent readSkippableFrame(byte[] frame) {
+        try (Arena arena = Arena.ofConfined()) {
+            MemorySegment src = Zstd.copyIn(arena, frame);
+            MemorySegment magic = arena.allocate(JAVA_INT);
+            MemorySegment dst = arena.allocate(Math.max(frame.length, 1));
+            long written = Zstd.call(() -> (long) Bindings.READ_SKIPPABLE_FRAME.invokeExact(
+                    dst, (long) frame.length, magic, src, (long) frame.length));
+            return new ZstdSkippableContent(Zstd.copyOut(dst, written), magic.get(JAVA_INT, 0));
+        }
+    }
+
+    private static ZstdFrameHeader header(MemorySegment data, long size) {
+        try (Arena arena = Arena.ofConfined()) {
+            MemorySegment zfh = arena.allocate(48);
+            long remaining = Zstd.call(() -> (long) Bindings.GET_FRAME_HEADER.invokeExact(zfh, data, size));
+            if (remaining != 0) {
+                throw new ZstdException("incomplete frame header: need " + remaining + " more bytes");
+            }
+            return new ZstdFrameHeader(
+                    zfh.get(JAVA_LONG, 0),                       // frameContentSize
+                    zfh.get(JAVA_LONG, 8),                       // windowSize
+                    zfh.get(JAVA_INT, 16) & 0xFFFFFFFFL,         // blockSizeMax
+                    ZstdFrameType.of(zfh.get(JAVA_INT, 20)),     // frameType
+                    zfh.get(JAVA_INT, 24),                       // headerSize
+                    zfh.get(JAVA_INT, 28),                       // dictID
+                    zfh.get(JAVA_INT, 32) != 0);                 // checksumFlag
+        }
+    }
+
+    private static boolean isSkippableFrame(MemorySegment data, long size) {
+        try {
+            return ((int) Bindings.IS_SKIPPABLE_FRAME.invokeExact(data, size)) != 0;
+        } catch (Throwable t) {
+            throw rethrow(t);
+        }
+    }
+
     private static boolean isZstdFrame(MemorySegment data, long size) {
         try {
             return ((int) Bindings.IS_FRAME.invokeExact(data, size)) != 0;

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

@@ -0,0 +1,36 @@
+package io.github.dfa1.zstdffm;
+
+import java.util.OptionalLong;
+
+/// Parsed contents of a zstd frame header, from `ZSTD_getFrameHeader`.
+///
+/// @param frameContentSize the stored decompressed size, or a sentinel if unknown;
+///                         prefer [#contentSize()]
+/// @param windowSize       the back-reference window size needed to decode the frame
+/// @param blockSizeMax     the maximum block size used in the frame
+/// @param frameType        whether this is a standard or skippable frame
+/// @param headerSize       the size of the frame header in bytes
+/// @param dictId           the dictionary id, or `0` if none (for a skippable frame,
+///                         the magic variant 0..15)
+/// @param hasChecksum      whether a 4-byte content checksum follows the frame
+public record ZstdFrameHeader(
+        long frameContentSize,
+        long windowSize,
+        long blockSizeMax,
+        ZstdFrameType frameType,
+        int headerSize,
+        int dictId,
+        boolean hasChecksum) {
+
+    /// Sentinel meaning the decompressed size is not recorded in the frame.
+    private static final long CONTENTSIZE_UNKNOWN = -1L;
+
+    /// The decompressed size, if the frame records it.
+    ///
+    /// @return the content size, or empty if the frame does not store it
+    public OptionalLong contentSize() {
+        return frameContentSize == CONTENTSIZE_UNKNOWN
+                ? OptionalLong.empty()
+                : OptionalLong.of(frameContentSize);
+    }
+}

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

@@ -0,0 +1,14 @@
+package io.github.dfa1.zstdffm;
+
+/// The kind of a zstd frame, from `ZSTD_FrameType_e`.
+public enum ZstdFrameType {
+
+    /// A normal compressed zstd frame.
+    STANDARD,
+    /// A skippable frame: arbitrary user data a zstd decoder ignores.
+    SKIPPABLE;
+
+    static ZstdFrameType of(int value) {
+        return value == 1 ? SKIPPABLE : STANDARD;
+    }
+}

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

@@ -0,0 +1,9 @@
+package io.github.dfa1.zstdffm;
+
+/// The decoded payload of a skippable frame, returned by
+/// [ZstdFrame#readSkippableFrame(byte[])].
+///
+/// @param content      the user bytes carried by the skippable frame
+/// @param magicVariant the variant 0..15 the frame was written with
+public record ZstdSkippableContent(byte[] content, int magicVariant) {
+}

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

@@ -78,6 +78,56 @@ void rejectsGarbage() {
         }
     }
 
+    @Nested
+    class Header {
+
+        @Test
+        void reportsContentSizeAndNoChecksumByDefault() {
+            // Given a default frame
+            ZstdFrameHeader header = ZstdFrame.header(Zstd.compress(PAYLOAD));
+
+            // Then it is a standard frame storing the content size, no checksum, no dict
+            assertThat(header.frameType()).isEqualTo(ZstdFrameType.STANDARD);
+            assertThat(header.contentSize()).hasValue(PAYLOAD.length);
+            assertThat(header.hasChecksum()).isFalse();
+            assertThat(header.dictId()).isZero();
+            assertThat(header.windowSize()).isPositive();
+        }
+
+        @Test
+        void reflectsChecksumFlag() {
+            byte[] frame;
+            try (ZstdCompressCtx ctx = new ZstdCompressCtx().checksum(true)) {
+                frame = ctx.compress(PAYLOAD);
+            }
+            assertThat(ZstdFrame.header(frame).hasChecksum()).isTrue();
+        }
+    }
+
+    @Nested
+    class Skippable {
+
+        @Test
+        void roundTripsContentAndMagicVariant() {
+            // Given user metadata wrapped in a skippable frame
+            byte[] meta = "sidecar metadata".getBytes(StandardCharsets.UTF_8);
+            byte[] frame = ZstdFrame.writeSkippableFrame(meta, 7);
+
+            // Then it is recognised as skippable and decodes back with its variant
+            assertThat(ZstdFrame.isSkippableFrame(frame)).isTrue();
+            assertThat(ZstdFrame.header(frame).frameType()).isEqualTo(ZstdFrameType.SKIPPABLE);
+
+            ZstdSkippableContent read = ZstdFrame.readSkippableFrame(frame);
+            assertThat(read.content()).isEqualTo(meta);
+            assertThat(read.magicVariant()).isEqualTo(7);
+        }
+
+        @Test
+        void standardFrameIsNotSkippable() {
+            assertThat(ZstdFrame.isSkippableFrame(Zstd.compress(PAYLOAD))).isFalse();
+        }
+    }
+
     @Nested
     class DictId {