docs: zero-copy mmap-vs-jni story, JMH-backed

[dfa1]

Summary

• Adds benchmark/.../LargeFileBenchmark, a JMH benchmark comparing this library's mmap+MemorySegment path (with/without posix_madvise(WILLNEED)) against zstd-jni's classic streaming API, at sizes from 4 MiB to 10 GiB — replacing the ad hoc System.nanoTime scratch harnesses that produced the previously-committed numbers in docs/zero-copy.md.
• Fixes a real bug the switch to JMH surfaced: the mmap path bounced compressed output through a heap byte[] before handing it to the sink, defeating the zero-copy point. Now uses a direct ByteBuffer view over the native dst segment + a WritableByteChannel sink. Verified byte-for-byte round-trip against the independent zstd CLI.
• Adds integration-tests/.../LargeMemoryMappedFileTest, a disabled-by-default test proving the library's >2 GiB memory-mapping capability claim (gated behind -Dzstd.test.large=true, too heavy for CI).
• Rewrites docs/zero-copy.md with the corrected, JMH-backed numbers (time + -prof gc allocation, full reference table with min–max ranges since JMH's 99.9% CI is unstable at n=3, machine specs, reproduce command), an honest account of what the ad hoc harness got wrong, and a new "Is the extra code worth it?" section.

Closes #95.

What the real numbers show (vs. the ad hoc ones they replace)

The corrected data confirms the shape of the earlier finding — mmap ahead at medium sizes, the madvise hint mattering more at 10 GiB — but at roughly a tenth the magnitude the ad hoc timing loops reported (4–5% swings at 10 GiB, not 24–45%). It also surfaces something the ad hoc numbers missed entirely: at 2.25–4 GiB, the WILLNEED hint is measurably slower than no hint at all, only becoming a net win again at 10 GiB. The one clean, decisive result across the board: at 4 MiB, mmap beats zstd-jni by ~2x — every measured iteration faster than every zstd-jni iteration — driven by fixed per-call overhead, not throughput.

Net conclusion for the new "Is the extra code worth it?" section: the zero-copy path is ~4x the code of the simple ZstdOutputStream API, and its throughput edge is decisive only at small files — at large scale it's a few percent either way. The real argument for the extra code at scale is the unconditional >2 GiB capability claim, not throughput.

Test plan

• ./mvnw -pl zstd,integration-tests,benchmark -am clean verify — builds and tests clean
• ./mvnw -pl benchmark validate / ./mvnw -pl zstd validate javadoc:javadoc — checkstyle/javadoc clean
• Smoke-tested all 3 LargeFileBenchmark variants at small size (-p size=4194304 -wi 1 -i 1 -f 1)
• Verified the zero-copy-output-fix round-trips byte-for-byte via the independent zstd CLI
• Ran the full suite (all 5 sizes × 3 variants, with -prof gc) to completion; numbers written into the docs are from that real run, not fabricated

🤖 Generated with Claude Code

[dfa1]

Ran an independent review over the full diff and applied the findings that survived verification:

• Fixed a real 3x-redundant-write inefficiency: LargeFileBenchmark's @Setup(Level.Trial) was regenerating an identical source file for every (benchmark method × size) combination, since each of the 3 variants runs in its own JMH fork — 30 GiB of redundant setup writes at the 10 GiB point alone. Now cached under the system temp directory keyed by size, generated once and reused across all three variants. (Smoke-testing the fix itself caught a real bug in the fix: the cache path needed CREATE added to writeCompressibleFile's FileChannel.open — TRUNCATE_EXISTING alone requires the file to already exist, which the old code got away with because Files.createTempFile always pre-created it first. Verified the cache is actually reused via mtime staying unchanged across a full re-run.)
• Tightened docs/zero-copy.md's "Is the extra code worth it?" recommendation — the n=3/single-machine qualifier was one sentence upstream of the actual recommendation; pulled it directly into that sentence.

Also verified two other candidates that came back clean (no change needed):

• A claimed resource-leak in mmapCompress's try-with-resources — refuted; Java guarantees all four resources close regardless of where in the try block an exception originates.
• Whether the benchmark's repeated-8-MiB-chunk source data (a shortcut vs. regenerating fresh content) inflates the measured compression ratio — refuted empirically, twice independently: reproduced the exact generator and compressed both the repeated-chunk and a continuously-varying control at the same size through both this library and the real zstd CLI; ratios matched within ~0.01%. At level 3, zstd's window (2 MiB) is smaller than the repeated chunk (8 MiB), so the compressor never gets to exploit the repeat.

Full build/tests/checkstyle/javadoc all green. Pushed as a3a722a.