docs: add architecture decision records (ADR 0001-0014)

Bootstrap docs/adr/ in MADR 3.0 format (ADR.md index + template.md) and
record the project's foundational decisions retrospectively, so contributors
can see why the project is shaped the way it is.

Covers: FFM over JNI (0001), zig cc native build (0002), MemorySegment-first
API (0003), per-classifier native jars (0004), no lib-path override (0005),
native compile flags (0006), integration tests as ground truth (0007),
size_t/sentinel mapping (0008), NativeObject idempotent close (0009), bounded
native-context pool for virtual threads (0010, Proposed), JPMS module (0011,
Accepted - not yet on main), benchmark methodology (0012), binding coverage
scope (0013), single-threaded native build (0014).

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

Author: dfa1

docs/adr/0001-ffm-over-jni.md

@@ -0,0 +1,47 @@
+# ADR 0001: FFM bindings over JNI
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+Calling the zstd C library from Java needs a native bridge. The established
+option is JNI (what `zstd-jni` uses): hand-written or generated C glue compiled
+per platform. JDK 25 ships the stable Foreign Function & Memory API
+(`java.lang.foreign`), which calls C directly from Java with no C glue.
+
+## Decision
+
+Use the FFM API exclusively. No JNI, no hand-written C, no generated stubs.
+Native symbols bind to `MethodHandle`s in `Bindings`; the library targets JDK
+25+ where `java.lang.foreign` is stable.
+
+## Consequences
+
+### Positive
+- Zero C source to maintain, review, or compile for the *bindings* (only zstd
+  itself is compiled — see ADR 0002).
+- Enables the zero-copy `MemorySegment` path (ADR 0003) — JNI must copy across
+  the boundary; FFM can pass off-heap addresses directly.
+- Pure-Java artifact; native code is only the bundled `libzstd`.
+
+### Negative
+- Hard floor at JDK 25. No JDK 17/21 support.
+- FFM downcalls are a restricted operation: callers must pass
+  `--enable-native-access`.
+
+### Risks to manage
+- FFM is young; signatures/restrictions may evolve. Centralised in `Bindings`
+  and `NativeCall` so changes are localised.
+
+## Alternatives considered
+
+- **JNI (zstd-jni):** mature, but ships hand-written C and copies at the
+  boundary, foreclosing zero-copy.
+- **JNA / JNR:** reflection-based FFI, slower per call, also pre-FFM.
+
+## References
+
+- [Bindings.java], [NativeCall.java]
+- [ADR 0003 — segment-first API](0003-segment-first-api.md)

docs/adr/0002-zig-cc-native-build.md

@@ -0,0 +1,47 @@
+# ADR 0002: Build the native library with `zig cc`
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+The project bundles `libzstd` for six classifiers (`{osx,linux,windows}` ×
+`{x86_64,aarch64}`). zstd is pure C with no build-system dependency. The build
+must produce all six from CI without per-platform runners or system toolchains.
+
+## Decision
+
+Compile the zstd library sources directly with `zig cc`
+(`scripts/build-zstd.sh`). Zig bundles clang + libc + headers for every target,
+so any host cross-compiles any classifier hermetically. No zstd Makefile, no
+CMake, no sysroot. The Maven `exec` plugin runs it in `generate-resources`;
+it is idempotent (skips if the library exists).
+
+## Consequences
+
+### Positive
+- One CI host (`ubuntu-latest`) builds all six classifiers — including the ones
+  with no free CI runner (windows-aarch64, linux-aarch64).
+- Hermetic and reproducible: no dependence on the host's installed toolchain.
+- Compiles `.c` directly, bypassing zstd's own build entirely.
+
+### Negative
+- Adds a Zig toolchain dependency to the build.
+- `zig cc` is a clang wrapper, not the zstd-blessed build path.
+
+### Risks to manage
+- Zig is pre-1.0; `zig cc` flag behaviour can shift between versions. The Zig
+  version is **pinned** (0.16.0) in CI; upgrades require a re-test.
+
+## Alternatives considered
+
+- **GitHub matrix runners:** no free windows-aarch64 / fragmented, slow.
+- **CMake/Make + cross sysroots:** per-target toolchain setup, the misery this
+  decision exists to avoid.
+
+## References
+
+- [scripts/build-zstd.sh](../../scripts/build-zstd.sh)
+- [ADR 0006 — native compile flags](0006-native-compile-flags.md)
+- [ADR 0014 — single-threaded native build](0014-single-threaded-native-build.md)

docs/adr/0003-segment-first-api.md

@@ -0,0 +1,46 @@
+# ADR 0003: MemorySegment-first API with thin `byte[]` overloads
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+Callers fall into two camps: heap callers holding `byte[]`, and zero-copy
+callers whose bytes are already off-heap (an mmap slice in, an arena buffer
+out). A `byte[]`-only API forces the second camp to copy on and off heap on
+every call — the dominant per-op cost for native compression.
+
+## Decision
+
+Make the `MemorySegment` path primary and add **thin** `byte[]` overloads for
+heap callers. The segment path never allocates a `byte[]` for decode output.
+`NativeCall.requireNative` guards zero-copy entry points so a stray heap
+segment fails fast with a clear message.
+
+## Consequences
+
+### Positive
+- Zero-copy callers get an allocation-free path (~0 B/op in benchmarks) —
+  the project's differentiator over `byte[]`-only bindings.
+- Heap callers keep an ergonomic `byte[]` API.
+
+### Negative
+- Two overload families to document and test.
+- Segment correctness rules (native vs heap, capacity) are on the caller.
+
+### Risks to manage
+- Misuse: passing a heap segment to a zero-copy method. Mitigated by
+  `requireNative`.
+
+## Alternatives considered
+
+- **`byte[]`-only (aircompressor-style):** simplest, but forecloses zero-copy —
+  the reason this library exists.
+- **`ByteBuffer`-first:** weaker lifetime/ownership model than `Arena` +
+  `MemorySegment`.
+
+## References
+
+- [docs/zero-copy.md](../zero-copy.md), [docs/benchmarks.md](../benchmarks.md)
+- [ADR 0001 — FFM over JNI](0001-ffm-over-jni.md)

docs/adr/0004-per-classifier-native-jars.md

@@ -0,0 +1,46 @@
+# ADR 0004: Per-classifier native JARs
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+The bundled `libzstd` must reach the JVM at runtime. A single fat jar carrying
+all six platform libraries bloats every download ~6x. The library also has to
+load correctly both on the classpath and as a named JPMS module (ADR 0011).
+
+## Decision
+
+Ship one `zstd-native-<classifier>` artifact per platform, each packaging only
+its own `libzstd.{so,dylib,dll}` under `native/<classifier>/`. At runtime
+`NativeLibrary` computes the classifier from `os.name`/`os.arch`, loads the
+resource via the class loader, extracts it to an owner-only temp dir, and
+`dlopen`s it once at class-init. Callers depend on the library jar plus the one
+native jar for their platform (or via the BOM).
+
+## Consequences
+
+### Positive
+- A consumer downloads ~one platform's library, not six.
+- The classifier directory name contains a dash, so it is not a valid package
+  and the resource escapes module encapsulation — readable across modules and
+  on the classpath alike.
+
+### Negative
+- Consumers must select the right native artifact (eased by the BOM).
+- Six native modules to build and publish.
+
+### Risks to manage
+- New CPU arch silently mis-resolving: `classifier()` throws a clear
+  `UnsatisfiedLinkError` for unsupported arches rather than guessing.
+
+## Alternatives considered
+
+- **Fat jar (all platforms):** simplest for consumers, 6x bloat for everyone.
+- **System-installed libzstd:** version drift, no hermetic guarantee.
+
+## References
+
+- [NativeLibrary.java], [bom/](../../bom)
+- [ADR 0005 — no lib-path override](0005-no-lib-path-override.md)

docs/adr/0005-no-lib-path-override.md

@@ -0,0 +1,53 @@
+# ADR 0005: No `-Dzstd.lib.path` override
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+A common convenience in native-binding libraries is a system property pointing
+at an alternative shared library (`-Dzstd.lib.path=/path/to/libzstd`). It is
+handy for testing a self-built library — but loading a caller-supplied native
+library is arbitrary native-code execution in the JVM process.
+
+## Decision
+
+Provide **no** path override. `NativeLibrary` loads only the bundled artifact
+from the classpath, extracts it into a private owner-only (`0700`) temp
+directory created atomically, and `dlopen`s that. To run a self-built
+`libzstd`, the user repackages the native resource jar — documented in
+`docs/how-to.md`.
+
+## Consequences
+
+### Positive
+- No code path turns an attacker-controlled string into `dlopen` of an
+  arbitrary library.
+- Owner-only temp dir prevents a local user swapping the library between
+  extraction and load (TOCTOU).
+
+### Negative
+- Less convenient for ad-hoc library swaps; requires repackaging.
+
+### Risks to manage
+- Temp-dir permissions are POSIX-only; on Windows the per-user temp root
+  provides the equivalent isolation.
+
+## Alternatives considered
+
+- **`-Dzstd.lib.path` override:** convenient, but an RCE-shaped foot-gun.
+- **Allow override only when a flag is set:** still ships the dangerous path.
+
+## Implementation
+
+- `9e505c6` / `8d0ea6a` (#8) — bundled-only native loader; removed any path
+  override, load solely from the classpath artifact.
+- `b2ed28b` — set owner-only (`0700`) temp dir permissions atomically (Sonar
+  S5443).
+- `c9929b9` (#20) — follow-up Sonar SECURITY-category fixes.
+
+## References
+
+- [NativeLibrary.java], [docs/how-to.md](../how-to.md)
+- [ADR 0004 — per-classifier native jars](0004-per-classifier-native-jars.md)

docs/adr/0006-native-compile-flags.md

@@ -0,0 +1,55 @@
+# ADR 0006: Native compile flags
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+Compiling zstd directly (ADR 0002) means owning the compile/link flags that the
+zstd build system would otherwise set. The flags must produce identical codegen
+across six targets and keep the exported symbol surface minimal.
+
+## Decision
+
+Compile with:
+
+- `-O3 -DNDEBUG` — release codegen.
+- `-DZSTD_DISABLE_ASM=1` — drop the x86-only `.S` files, giving identical C
+  codegen on every target.
+- `-DXXH_NAMESPACE=ZSTD_` — matches zstd's own build, avoids xxhash symbol
+  clashes.
+- `-fPIC`.
+
+Visibility differs by platform:
+
+- **ELF / Mach-O:** `-fvisibility=hidden`; zstd's `ZSTDLIB_VISIBLE` keeps only
+  the public API exported.
+- **Windows / MinGW:** *no* hidden visibility (it suppresses PE exports);
+  instead `-Wl,--export-all-symbols` lets lld populate the PE export table.
+
+Symbol/debug tables are stripped at link (`-s` on ELF); the lld-emitted `.pdb`
+and import `.lib` on Windows are deleted after link so they are not bundled.
+
+## Consequences
+
+### Positive
+- Deterministic, minimal-surface libraries; stripped ELF is ~6x smaller.
+
+### Negative
+- `DISABLE_ASM` may leave marginal x86 performance on the table vs the
+  assembly paths (not measured to matter at level 3).
+
+### Risks to manage
+- The Windows-vs-ELF visibility split is non-obvious; a wrong flag silently
+  empties the Windows export table. Documented inline in the build script.
+
+## Alternatives considered
+
+- **Keep `.S` asm per target:** divergent codegen, x86-only, build complexity.
+- **Hidden visibility on Windows too:** breaks PE exports — rejected.
+
+## References
+
+- [scripts/build-zstd.sh](../../scripts/build-zstd.sh)
+- [ADR 0002 — zig cc native build](0002-zig-cc-native-build.md)

docs/adr/0007-integration-tests-ground-truth.md

@@ -0,0 +1,50 @@
+# ADR 0007: Integration tests as ground truth
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+There is no machine-checkable formal spec for the zstd frame format that a
+binding can assert against. Unit tests prove internal consistency but not that
+output is *correct zstd* that other tools accept.
+
+## Decision
+
+Treat integration tests as ground truth, on two pillars:
+
+1. **Interop with `zstd-jni`** (luben — the zstd C library via JNI): every
+   encoding round-trip is cross-checked — what we compress, JNI decompresses,
+   and vice versa.
+2. **The vendored golden corpus** under `third_party/zstd/tests/`
+   (`golden-compression`, `golden-decompression`,
+   `golden-decompression-errors`, `golden-dictionaries`) — the canonical,
+   version-matched fixtures the C project itself ships.
+
+Unit tests stay fast and pure (no I/O, network, sleep). Every encoding
+round-trip and file-format boundary gets an integration test.
+
+## Consequences
+
+### Positive
+- Correctness defined against an independent implementation and the upstream
+  corpus, not our own assumptions.
+- Error-case fixtures pin our handling of malformed frames.
+
+### Negative
+- Integration tests need the git submodule and the `zstd-jni` dependency.
+- Slower than the unit suite; kept in a separate module.
+
+### Risks to manage
+- Corpus drifts with the submodule version; pinned via the submodule SHA.
+
+## Alternatives considered
+
+- **Unit tests only:** cannot prove cross-tool correctness.
+- **Round-trip against ourselves only:** a self-consistent bug stays invisible.
+
+## References
+
+- [integration-tests/](../../integration-tests)
+- [third_party/zstd/tests/](../../third_party/zstd/tests)

docs/adr/0008-size-t-mapping-and-sentinels.md

@@ -0,0 +1,45 @@
+# ADR 0008: `size_t` maps to `JAVA_LONG`, guard sentinels
+
+- **Status:** Completed
+- **Date:** 2026-06-27
+- **Deciders:** project maintainer
+
+## Context
+
+zstd's C API uses `size_t` and `unsigned long long` pervasively, and encodes
+errors as `size_t` values near `SIZE_MAX` (checked via `ZSTD_isError`). Java has
+no unsigned types. The binding must map these consistently and not mistake an
+error sentinel for a huge valid size.
+
+## Decision
+
+Model `size_t` and `unsigned long long` as `ValueLayout.JAVA_LONG` (LP64). All
+native handles live in `Bindings`. Every public method that returns a
+size-typed value routes through `NativeCall.checkReturnValue`, which calls
+`ZSTD_isError` and throws `ZstdException` (carrying the decoded `ZstdErrorCode`)
+before the value is interpreted as a length. Negative-interpreted sentinels are
+guarded at the public boundary.
+
+## Consequences
+
+### Positive
+- One place (`NativeCall`) owns the error convention; binding classes stay
+  uniform.
+- Sentinels become typed Java exceptions, not silent giant lengths.
+
+### Negative
+- Values above `Long.MAX_VALUE` are not representable — acceptable: such sizes
+  exceed any realistic JVM allocation and zstd's own limits.
+
+### Risks to manage
+- A new binding that skips `checkReturnValue` would leak raw sentinels — the
+  convention is documented and shared.
+
+## Alternatives considered
+
+- **`JAVA_INT` for sizes:** overflows on payloads >2 GB.
+- **Per-call ad-hoc error checks:** duplicated, easy to forget.
+
+## References
+
+- [Bindings.java], [NativeCall.java], [ZstdException.java], [ZstdErrorCode.java]