refactor: read ZSTD_bounds via the named layout, not magic offsets

Name BOUNDS_LAYOUT's fields (error/lowerBound/upperBound) and derive the
read offsets from it with byteOffset(groupElement(...)), so the struct
reads track the definition instead of hand-counted 0/8/12. Document how
the struct-by-value return allocates through the arena SegmentAllocator.

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

Author: dfa1

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

@@ -158,8 +158,11 @@ final class Bindings {
             NativeLibrary.lookup("ZSTD_getDictID_fromDDict", FunctionDescriptor.of(JAVA_INT, ADDRESS));
 
     // ZSTD_bounds { size_t error; int lowerBound; int upperBound; } — returned by value
-    private static final MemoryLayout BOUNDS_LAYOUT =
-            MemoryLayout.structLayout(JAVA_LONG, JAVA_INT, JAVA_INT);
+    static final MemoryLayout BOUNDS_LAYOUT =
+            MemoryLayout.structLayout(
+                    JAVA_LONG.withName("error"),
+                    JAVA_INT.withName("lowerBound"),
+                    JAVA_INT.withName("upperBound"));
     // ZSTD_bounds ZSTD_cParam_getBounds(ZSTD_cParameter) / ZSTD_dParam_getBounds(ZSTD_dParameter)
     static final MethodHandle CPARAM_GET_BOUNDS =
             NativeLibrary.lookup("ZSTD_cParam_getBounds", FunctionDescriptor.of(BOUNDS_LAYOUT, JAVA_INT));

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

@@ -1,6 +1,7 @@
 package io.github.dfa1.zstd;
 
 import java.lang.foreign.Arena;
+import java.lang.foreign.MemoryLayout.PathElement;
 import java.lang.foreign.MemorySegment;
 import java.lang.foreign.SegmentAllocator;
 import java.lang.invoke.MethodHandle;
@@ -15,16 +16,28 @@
 /// @param upperBound the largest accepted value, inclusive
 public record ZstdBounds(int lowerBound, int upperBound) {
 
+    // Offsets into the returned ZSTD_bounds struct, derived from the named layout
+    // rather than hand-counted, so they track the struct definition.
+    private static final long ERROR_OFFSET = Bindings.BOUNDS_LAYOUT.byteOffset(PathElement.groupElement("error"));
+    private static final long LOWER_OFFSET = Bindings.BOUNDS_LAYOUT.byteOffset(PathElement.groupElement("lowerBound"));
+    private static final long UPPER_OFFSET = Bindings.BOUNDS_LAYOUT.byteOffset(PathElement.groupElement("upperBound"));
+
     /// Calls a `*_getBounds` function (which returns a `ZSTD_bounds` struct by
     /// value: `{ size_t error; int lowerBound; int upperBound; }`).
     static ZstdBounds query(MethodHandle getBounds, int parameter) {
         try (Arena arena = Arena.ofConfined()) {
+            // getBounds returns a ZSTD_bounds struct by value. For a struct return,
+            // the FFM linker prepends a SegmentAllocator parameter to the handle:
+            // it allocates BOUNDS_LAYOUT.byteSize() bytes from that allocator, the
+            // native call writes the struct there, and the handle returns a segment
+            // viewing it. Passing the arena makes the struct arena-owned (freed on
+            // close); the cast satisfies invokeExact's exact-type requirement.
             MemorySegment bounds = (MemorySegment) getBounds.invokeExact((SegmentAllocator) arena, parameter);
-            long error = bounds.get(JAVA_LONG, 0);
+            long error = bounds.get(JAVA_LONG, ERROR_OFFSET);
             if (NativeCall.isError(error)) {
                 throw new ZstdException("parameter has no queryable bounds");
             }
-            return new ZstdBounds(bounds.get(JAVA_INT, 8), bounds.get(JAVA_INT, 12));
+            return new ZstdBounds(bounds.get(JAVA_INT, LOWER_OFFSET), bounds.get(JAVA_INT, UPPER_OFFSET));
         } catch (Throwable t) {
             throw NativeCall.rethrow(t);
         }