refactor: ZstdByteSize for ZstdFrameHeader's bounded size fields

Continues the value-object stabilization into ZstdFrameHeader:
- blockSizeMax(): int-masked long -> ZstdByteSize (masked, always non-negative)
- headerSize(): int -> ZstdByteSize (now matches ZstdFrame.headerSize())

frameContentSize() and windowSize() deliberately stay raw long: a hostile
header can make either read back as an unsigned value at or above 2^63 (zstd
copies the content-size field verbatim, and for a single-segment frame sets
windowSize equal to it), which wraps negative in a signed long. Wrapping those
in a non-negative ZstdByteSize would turn ZstdFrame.header() parsing into a
thrown exception on hostile input — a regression the sign-bit test catches.
The typed contentSize() remains the safe view of the content size.

Also resolves the headerSize() asymmetry from the previous PR: ZstdFrame.headerSize()
and ZstdFrameHeader.headerSize() now both return ZstdByteSize and compare directly.

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

Author: dfa1

.github/smoke/src/test/java/SmokeTest.java

@@ -184,7 +184,7 @@ void frameIntrospection() {
         check(header.contentSize().isPresent() && header.contentSize().get().value() == original.length,
                 "header(byte[]).contentSize() mismatch");
         check(header.frameType() == ZstdFrameType.STANDARD, "header(byte[]).frameType() expected STANDARD");
-        check(header.headerSize() == headerSize, "header(byte[]).headerSize() disagreed with headerSize(byte[])");
+        check(header.headerSize().value() == headerSize, "header(byte[]).headerSize() disagreed with headerSize(byte[])");
         check(!header.hasChecksum(), "header(byte[]).hasChecksum() expected false (checksum not enabled)");
     }
 

CHANGELOG.md

@@ -49,6 +49,12 @@ git tags, which trigger publication to Maven Central.
   `String`, and `Zstd.versionNumber()` is removed. Use
   `Zstd.version().toString()` for the `x.y.z` string and
   `Zstd.version().number()` for the packed number.
+- **Breaking:** `ZstdFrameHeader.blockSizeMax()` and `headerSize()` now return
+  `ZstdByteSize` (were `long`/`int`); call `.value()` for the raw number.
+  `frameContentSize()` and `windowSize()` stay raw `long` — a hostile header can
+  make either read back as an unrepresentable value at or above `2^63`, so
+  wrapping them in a non-negative `ZstdByteSize` would turn a parse into a thrown
+  exception; use the typed `contentSize()` for the content size.
 
 ## [0.11] - 2026-07-24
 

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

@@ -259,13 +259,13 @@ private static ZstdFrameHeader header(MemorySegment data, long size) {
                 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_LONG, 0),                                 // frameContentSize
+                    zfh.get(JAVA_LONG, 8),                                 // windowSize
+                    new ZstdByteSize(zfh.get(JAVA_INT, 16) & 0xFFFFFFFFL), // blockSizeMax
+                    ZstdFrameType.of(zfh.get(JAVA_INT, 20)),               // frameType
+                    new ZstdByteSize(zfh.get(JAVA_INT, 24)),               // headerSize
                     ZstdDictionaryId.of(zfh.get(JAVA_INT, 28)),            // dictID
-                    zfh.get(JAVA_INT, 32) != 0);                 // checksumFlag
+                    zfh.get(JAVA_INT, 32) != 0);                           // checksumFlag
         }
     }
 

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

@@ -4,8 +4,16 @@
 
 /// Parsed contents of a zstd frame header, from `ZSTD_getFrameHeader`.
 ///
-/// @param frameContentSize the stored decompressed size, or a sentinel if unknown;
-///                         prefer [#contentSize()]
+/// `frameContentSize` and `windowSize` stay raw `long`s rather than
+/// [ZstdByteSize]: both can read back as an unrepresentable value on a hostile
+/// header (zstd copies the 8-byte content-size field verbatim, and for a
+/// single-segment frame sets `windowSize` equal to it), so an unsigned value at
+/// or above `2^63` wraps negative in a signed `long`. Wrapping either in a
+/// non-negative [ZstdByteSize] here would turn a parse into a thrown exception —
+/// use the typed [#contentSize()] for the safe view of the content size.
+///
+/// @param frameContentSize the raw stored decompressed size, or a sentinel if
+///                         unknown — prefer the typed [#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
@@ -16,9 +24,9 @@
 public record ZstdFrameHeader(
         long frameContentSize,
         long windowSize,
-        long blockSizeMax,
+        ZstdByteSize blockSizeMax,
         ZstdFrameType frameType,
-        int headerSize,
+        ZstdByteSize headerSize,
         ZstdDictionaryId dictId,
         boolean hasChecksum) {
 

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

@@ -172,7 +172,7 @@ void matchesTheParsedHeaderSize() {
             byte[] frame = Zstd.compress(PAYLOAD);
 
             // Then the light probe agrees with the fully parsed header
-            assertThat(ZstdFrame.headerSize(frame)).isEqualTo(new ZstdByteSize(ZstdFrame.header(frame).headerSize()));
+            assertThat(ZstdFrame.headerSize(frame)).isEqualTo(ZstdFrame.header(frame).headerSize());
         }
 
         @Test
@@ -297,7 +297,7 @@ void reportsASaneBlockSizeMax() {
 
             // Then blockSizeMax is the masked 32-bit field — a real block size, never
             // the all-ones value a sign-extension or wrong mask would produce
-            assertThat(header.blockSizeMax()).isPositive().isLessThanOrEqualTo(128 * 1024L);
+            assertThat(header.blockSizeMax().value()).isPositive().isLessThanOrEqualTo(128 * 1024L);
         }
 
         @Test