From a740468c9f713188de2b024ee5e80648ab37f346 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 01:30:22 +0100
Subject: [PATCH 01/13] Bump version -> `1.0.0-SNAPSHOT-011`

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 version.gradle.kts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/version.gradle.kts b/version.gradle.kts
index 547e4a0..7970b0f 100644
--- a/version.gradle.kts
+++ b/version.gradle.kts
@@ -24,4 +24,4 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
-extra.set("versionToPublish", "1.0.0-SNAPSHOT-010")
+extra.set("versionToPublish", "1.0.0-SNAPSHOT-011")

From 486d3d03babd4f4e013bb5e918339e5c985aef92 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 18:23:18 +0100
Subject: [PATCH 02/13] Add the Phase 6 validation & benchmark matrix
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 6 (validation & release). Add the comparative JMH matrix in the raw-JMH
`benchmarks-jvm` tier — our `LongLongMap`/`IntIntMap` versus boxed `HashMap` and
the four specialist primitive-map libraries (fastutil, HPPC, Eclipse Collections,
Agrona) — over lookup/insert/churn across sizes and dense/adversarial key sets,
plus a load-factor sweep, a JOL retained-footprint report, a reproducibility
runner (env metadata + fixed seeds + JSON), and the benchmarking / release-runbook
docs.

Measured: our maps retain 19/10 bytes per entry — 4.68x/7.30x less than boxed
`HashMap` and ~1.9x/1.8x less than the specialist libraries — and stay flat from
dense to adversarial keys where the competitors degrade ~5-6x. Absolute time
numbers are deferred to a pinned-hardware run; Maven Central publication is
documented as a human-gated runbook (irreversible; needs signing keys, a Portal
token, and a non-SNAPSHOT version).

The competitor libraries are benchmark-only and JVM-only, confined to the `jmh`
source set and never a dependency of the published `elastic` module. A `@Setup`
correctness gate rejects any miswired adapter before a number is taken.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .agents/tasks/phase-6-validation-release.md   | 117 ++++++++
 README.md                                     |  19 +-
 benchmarks-jvm/build.gradle.kts               |  51 ++++
 benchmarks-jvm/capture-env.sh                 |  59 ++++
 benchmarks-jvm/results/README.md              |  30 ++
 .../results/m4max-indicative/environment.txt  |  10 +
 .../results/m4max-indicative/footprint.md     |  13 +
 .../results/m4max-indicative/footprint.tsv    |  13 +
 .../results/m4max-indicative/lookup-hit-1m.md |  25 ++
 benchmarks-jvm/run-matrix.sh                  |  43 +++
 .../benchmark/jmh/CompetitorAdapters.kt       | 264 ++++++++++++++++++
 .../elastic/benchmark/jmh/FootprintReport.kt  | 141 ++++++++++
 .../benchmark/jmh/IntIntMatrixBenchmark.kt    | 159 +++++++++++
 .../benchmark/jmh/LoadFactorBenchmark.kt      | 163 +++++++++++
 .../benchmark/jmh/LongLongMatrixBenchmark.kt  | 164 +++++++++++
 .../spine/elastic/benchmark/jmh/MatrixKeys.kt | 121 ++++++++
 docs/benchmarking.md                          | 194 +++++++++++++
 docs/performance-goals.md                     |  29 ++
 docs/project.md                               |  14 +-
 docs/publishing.md                            | 112 ++++++++
 20 files changed, 1737 insertions(+), 4 deletions(-)
 create mode 100644 .agents/tasks/phase-6-validation-release.md
 create mode 100755 benchmarks-jvm/capture-env.sh
 create mode 100644 benchmarks-jvm/results/README.md
 create mode 100644 benchmarks-jvm/results/m4max-indicative/environment.txt
 create mode 100644 benchmarks-jvm/results/m4max-indicative/footprint.md
 create mode 100644 benchmarks-jvm/results/m4max-indicative/footprint.tsv
 create mode 100644 benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
 create mode 100755 benchmarks-jvm/run-matrix.sh
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/CompetitorAdapters.kt
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
 create mode 100644 benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/MatrixKeys.kt
 create mode 100644 docs/benchmarking.md
 create mode 100644 docs/publishing.md

diff --git a/.agents/tasks/phase-6-validation-release.md b/.agents/tasks/phase-6-validation-release.md
new file mode 100644
index 0000000..a1538e1
--- /dev/null
+++ b/.agents/tasks/phase-6-validation-release.md
@@ -0,0 +1,117 @@
+# Phase 6 — Validation & release
+
+**Status: IMPLEMENTED (validation harness + docs); release is human-gated.**
+Branch `phase-6`. Green on JVM (the new benchmark module compiles and runs; the
+footprint report and JMH matrix produce results and JSON). Part of the phased
+[implementation plan](elastic-hashing-implementation-plan.md); see also
+[`docs/benchmarking.md`](../../docs/benchmarking.md) and
+[`docs/publishing.md`](../../docs/publishing.md).
+
+## Goal
+
+Publish with numbers that survive external scrutiny: the full comparative benchmark
+matrix versus the standard library and the specialist primitive-map libraries,
+memory footprint, reproducibility metadata, honest baseline-qualified positioning,
+and the Maven Central publication runbook.
+
+## What shipped
+
+### The comparative matrix (`benchmarks-jvm`, raw JMH — JVM-only)
+
+The four competitor libraries are JVM-only, so the matrix lives in the raw-JMH tier,
+never on the published `elastic` module. Verified coordinates, all on the Java 17
+toolchain: **fastutil 8.5.18**, **HPPC 0.10.0**, **Eclipse Collections 13.0.0**
+(`-api` + impl), **Agrona 2.5.0**.
+
+- `CompetitorAdapters.kt` — a `LongLongCell` / `IntIntCell` interface presenting our
+  map, boxed `HashMap`, and the four competitors behind one monomorphic type, each
+  pre-sized **in its own units** (the Phase 1 fairness rule). Handles the per-library
+  quirks: fastutil's settable `defaultReturnValue`, HPPC's fixed-0 absent value,
+  Eclipse's `void put` / `removeKey` / `java.util.Map`-free API, Agrona's mandatory
+  `missingValue` sentinel and its `java.util.Map`-implementing `size` **property**.
+- `LongLongMatrixBenchmark` / `IntIntMatrixBenchmark` — `@Param impl × size × dist`
+  over ops `lookupHit` (random-access), `lookupMiss`, `insertPresized`,
+  `insertGrowing`, `churn`. A **correctness gate in `@Setup`** (the hit-sum must equal
+  the key-sum) refuses to benchmark a miswired adapter. **No `iterate` op**: our
+  primitive-value maps expose no non-boxing traversal (DP-10 lean surface), so a fair
+  head-to-head cannot include it — the gap is a tracked follow-up.
+- `LoadFactorBenchmark` — lookup cost vs load factor `{0.50…0.99}` for the three
+  competitors with a **settable** load factor (fastutil, HPPC, Agrona). Ours (fixed
+  `7/8`) and `HashMap` (`0.75`) cannot be *held* at an arbitrary load and are fixed
+  reference points; the ≈0.99 regime belongs to the paper structures, gated by their
+  own probe-count specs. Capacity is pinned at `2^20` and the fill count chosen to hit
+  the target load; every invocation does the same `2^20` lookups, so scores are
+  load-comparable.
+- `MatrixKeys.kt` — the `DENSE` and `CLUSTERED` key sets (the latter mandated by the
+  fairness gate) and the fixed-seed shuffle. The `Int` `CLUSTERED` stride is milder
+  than the `Long` one because a hard-collision key set is not constructible in-range
+  for 32-bit keys at a million entries.
+
+### The footprint report (JOL)
+
+`FootprintReport.kt` (`main()` in the jmh source set, `./gradlew
+:benchmarks-jvm:footprintReport`) measures the exact retained heap of every map, built
+raw (no adapter wrapper), pre-sized in its own units at `n = 229_376` (the `7/8` load
+of a `2^18` table), and writes Markdown + TSV. Deterministic; the `Long→Long` figure
+reproduces the committed Phase 1 measurement exactly.
+
+### Reproducibility harness
+
+- `capture-env.sh` — JDK/OS/CPU/RAM and, critically, whether CPU frequency was pinned;
+  portable across macOS (dev) and Linux (CI).
+- `run-matrix.sh <label>` — captures the environment, runs the footprint report and
+  the authoritative JMH matrix (`@Fork 3`, `5×1s` + `5×1s`), and collects a
+  self-describing bundle under `benchmarks-jvm/results/<label>/`.
+- Seeds are fixed (seed 42) and shared across maps; documented.
+- Committed indicative bundle: `benchmarks-jvm/results/m4max-indicative/`.
+
+## Results (measured)
+
+- **Memory — decisive, and the strongest portable result.** Retained B/entry at
+  `n = 229_376`: `LongLongMap` **19** (**4.68×** smaller than `HashMap` 89, and
+  **~1.9×** smaller than the four competitors, all 36); `IntIntMap` **10** (**7.30×**
+  smaller than `HashMap` 73, **~1.8×** smaller than the competitors, all 18). Ours is
+  more compact than *even the specialist primitive libraries*, from packing
+  key+value+1 control byte at `7/8` load.
+- **Time — distribution robustness is the headline** (qualitative; absolute ms are
+  hardware-specific and deferred to a pinned run). `1M` `lookupHit`, M4 Max, indicative:
+  `OURS` is flat across `DENSE` (9.9 ms) → `CLUSTERED` (10.2 ms), while `FASTUTIL`
+  degrades ~5× (7.7 → 36 ms) and `ECLIPSE` ~6× (2.0 → 13 ms). On dense keys Eclipse's
+  weak spread wins (contiguous, cache-resident); on adversarial keys our `fmix64`
+  finalizer makes `OURS` the fastest. A dense-only view would have inverted the
+  conclusion — the fairness gate's adversarial mandate earned its keep.
+- **vs `HashMap` (the committed gate):** met — faster at scale on lookup and presized
+  insert, and far more compact, per `performance-goals.md`.
+
+## Release — human-gated (not done here)
+
+Maven Central publication is **deliberately not executed**: it is irreversible and
+needs a signing key, a Central Portal token, a claimed `io.spine` namespace, and a
+**non-SNAPSHOT** version (the project is on a `-SNAPSHOT` line). The full runbook,
+including wiring `kmp-publish` + `spinePublishing` and validating locally with
+`publishToMavenLocal`, is in [`docs/publishing.md`](../../docs/publishing.md). The
+`elastic` module currently registers no publication tasks; wiring them is the first
+release task and is safe to do + validate locally.
+
+## Decisions
+
+- **Competitors are a reference ceiling, not a success gate.** fastutil/HPPC are
+  co-fastest among classic open-addressing libs; we do not claim to beat them on raw
+  dense lookup. The committed baseline is the standard library. Differentiators:
+  memory, distribution robustness, multiplatform reach.
+- **Competitor libs confined to `benchmarks-jvm/jmh`** — benchmark-only, JVM-only,
+  never a dependency of the published module. Versions pinned inline (not the
+  `io.spine.dependency.*` catalog) as one-off measurement peers.
+- **Absolute time numbers are not committed as headline figures** — only the
+  ratios/robustness that survive the unpinned-hardware caveat. Authoritative absolute
+  numbers require a pinned-hardware `run-matrix.sh` run.
+
+## Open follow-ups
+
+- Non-boxing `forEach` on the primitive-value maps (closes the `iterate` gap; a chip
+  was spawned during this phase).
+- A pinned-hardware authoritative `run-matrix.sh` run (JVM + a Native tier), committed
+  under `benchmarks-jvm/results/<label>/`.
+- The actual Maven Central release, when a non-SNAPSHOT version and credentials exist.
+- Kotlin/KSP pin (2.3.21) no longer has a rationale (codegen is template-based); an
+  upgrade is a separate task.
diff --git a/README.md b/README.md
index c445cb3..bcafcdd 100644
--- a/README.md
+++ b/README.md
@@ -64,8 +64,23 @@ detail.
   - Opt-in boxed `MutableMap` views: `asMutableMap()` on the boxed-value maps
     (fail-fast iteration) and on `SingleWriterSwissLongMap` (weakly consistent
     snapshot iteration).
-- **Phase 6 — planned.** Validation and release: the full benchmark matrix on
-  pinned hardware, reproducibility metadata, and Maven Central publication.
+- **Phase 6 — validation harness complete; release is human-gated.** The
+  comparative benchmark matrix versus the standard library and the specialist
+  primitive-map libraries (fastutil, HPPC, Eclipse Collections, Agrona), the
+  exact-footprint report, and the reproducibility harness are in place; see
+  [`docs/benchmarking.md`](docs/benchmarking.md). Two measured headlines:
+  - **Memory:** `LongLongMap` retains **19 B/entry** — **4.68×** less than boxed
+    `HashMap<Long, Long>` and **~1.9× less than every primitive competitor** (36
+    B/entry each); `IntIntMap` is **10 B/entry** (**7.30×** vs `HashMap`, **~1.8×**
+    vs competitors at 18 B/entry).
+  - **Distribution robustness:** on out-of-cache random lookup our `fmix64`
+    finalizer keeps `LongLongMap` flat between dense and adversarial (clustered)
+    keys, where fastutil degrades ~5× and Eclipse ~6× — so ours is the *fastest*
+    under adversarial keys.
+
+  Maven Central publication is deliberately deferred (it is irreversible and needs
+  signing keys, a Portal token, and a non-SNAPSHOT version); the runbook is
+  [`docs/publishing.md`](docs/publishing.md).
 
 ## Modules
 
diff --git a/benchmarks-jvm/build.gradle.kts b/benchmarks-jvm/build.gradle.kts
index 91569c0..976b949 100644
--- a/benchmarks-jvm/build.gradle.kts
+++ b/benchmarks-jvm/build.gradle.kts
@@ -24,6 +24,7 @@
  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+import io.spine.dependency.test.Jol
 import io.spine.gradle.report.license.LicenseReporter
 
 // The raw-JMH second benchmark tier: JVM-only benchmarks written against JMH's
@@ -53,9 +54,59 @@ kotlin {
     jvmToolchain(17)
 }
 
+// Competitor primitive-map libraries, benchmarked as a *reference ceiling* for the
+// Phase 6 matrix (see `docs/benchmarking.md`). These are JVM-only and benchmark-only:
+// they are on the `jmh` source set, never on the published `elastic` module. Versions
+// are pinned here (not in the `io.spine.dependency.*` catalog) because they are
+// one-off measurement peers, not project dependencies. All four run on the Java 17
+// toolchain. Verified coordinates (mid-2026):
+//   - fastutil          it.unimi.dsi:fastutil:8.5.18
+//   - HPPC              com.carrotsearch:hppc:0.10.0
+//   - Eclipse Collections org.eclipse.collections:eclipse-collections(-api):13.0.0
+//   - Agrona           org.agrona:agrona:2.5.0
+val fastutilVersion = "8.5.18"
+val hppcVersion = "0.10.0"
+val eclipseCollectionsVersion = "13.0.0"
+val agronaVersion = "2.5.0"
+
 dependencies {
     // The KMP project dependency resolves to its JVM variant here.
     jmh(project(":elastic"))
+
+    // Reference-ceiling competitors for the comparative matrix.
+    jmh("it.unimi.dsi:fastutil:$fastutilVersion")
+    jmh("com.carrotsearch:hppc:$hppcVersion")
+    jmh("org.eclipse.collections:eclipse-collections-api:$eclipseCollectionsVersion")
+    jmh("org.eclipse.collections:eclipse-collections:$eclipseCollectionsVersion")
+    jmh("org.agrona:agrona:$agronaVersion")
+
+    // JOL (Java Object Layout) for the exact retained-footprint report; see the
+    // `footprintReport` task below. Test/benchmark-scoped, never published.
+    jmh(Jol.lib)
+}
+
+// ---------------------------------------------------------------------------
+// Retained-footprint report (JOL).
+//
+// A plain `main()` in the `jmh` source set (so it shares the competitor
+// classpath) that measures the exact retained heap of every map in the matrix
+// with JOL and writes a Markdown + TSV table under `build/reports/footprint/`.
+// This is the authoritative *memory* half of the Phase 6 matrix — deterministic,
+// fast, and run with `./gradlew :benchmarks-jvm:footprintReport`. The time half
+// is the JMH benchmarks in this module.
+// ---------------------------------------------------------------------------
+val footprintReport by tasks.registering(JavaExec::class) {
+    group = "verification"
+    description = "Writes the retained-heap footprint matrix (ours vs stdlib + competitors)."
+    val jmhSourceSet = sourceSets["jmh"]
+    classpath = jmhSourceSet.runtimeClasspath
+    mainClass.set("io.spine.elastic.benchmark.jmh.FootprintReportKt")
+    argumentProviders.add(
+        CommandLineArgumentProvider {
+            val out = layout.buildDirectory.dir("reports/footprint").get().asFile
+            listOf(out.absolutePath)
+        },
+    )
 }
 
 jmh {
diff --git a/benchmarks-jvm/capture-env.sh b/benchmarks-jvm/capture-env.sh
new file mode 100755
index 0000000..f102dc5
--- /dev/null
+++ b/benchmarks-jvm/capture-env.sh
@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+#
+# Captures the machine + JDK identity that a benchmark number is meaningless
+# without: JDK vendor/version/VM, OS, CPU model and core counts, RAM, and — the
+# most-overlooked one — whether CPU frequency scaling / turbo was pinned. JMH
+# already embeds the JDK/VM per record in its JSON, but never the OS or CPU, so
+# this is the missing half of a reproducible result.
+#
+# Portable across macOS (dev) and Linux (CI). Non-destructive; safe to run
+# unattended. Writes `key=value` lines to stdout (redirect into the results dir).
+#
+# Usage: ./capture-env.sh > results/<label>/environment.txt
+set -euo pipefail
+
+emit() { printf '%s=%s\n' "$1" "$2"; }
+
+emit "captured_at" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+
+# --- JDK ---------------------------------------------------------------------
+if command -v java >/dev/null 2>&1; then
+    # `java -version` prints to stderr; first line is the version, second the VM.
+    java_version_raw="$(java -version 2>&1 | tr '\n' '|')"
+    emit "java_version" "${java_version_raw%|}"
+    emit "java_home" "${JAVA_HOME:-<unset>}"
+else
+    emit "java_version" "<java not on PATH>"
+fi
+
+# --- OS + CPU (branch on uname) ---------------------------------------------
+os="$(uname -s)"
+emit "os_kernel" "$(uname -srm)"
+
+case "$os" in
+    Darwin)
+        emit "os_product" "$(sw_vers -productName 2>/dev/null || echo macOS) $(sw_vers -productVersion 2>/dev/null) ($(sw_vers -buildVersion 2>/dev/null))"
+        # brand_string can be empty on some early Apple Silicon; fall back to hw.model.
+        cpu="$(sysctl -n machdep.cpu.brand_string 2>/dev/null || true)"
+        [ -z "$cpu" ] && cpu="$(sysctl -n hw.model 2>/dev/null || echo unknown)"
+        emit "cpu_model" "$cpu"
+        emit "cpu_physical_cores" "$(sysctl -n hw.physicalcpu 2>/dev/null || echo '?')"
+        emit "cpu_logical_cores" "$(sysctl -n hw.logicalcpu 2>/dev/null || echo '?')"
+        emit "ram_bytes" "$(sysctl -n hw.memsize 2>/dev/null || echo '?')"
+        # Apple Silicon exposes no fixed frequency and schedules opaque P/E cores.
+        emit "freq_pinned" "no (Apple Silicon: turbo/P-E scheduling not controllable)"
+        ;;
+    Linux)
+        [ -r /etc/os-release ] && emit "os_product" "$(. /etc/os-release; echo "$PRETTY_NAME")"
+        emit "cpu_model" "$(lscpu 2>/dev/null | sed -n 's/^Model name:[[:space:]]*//p' | head -1 || grep -m1 'model name' /proc/cpuinfo | cut -d: -f2- | sed 's/^ //')"
+        emit "cpu_logical_cores" "$(nproc 2>/dev/null || echo '?')"
+        emit "ram_bytes" "$(awk '/MemTotal/ {print $2*1024; exit}' /proc/meminfo 2>/dev/null || echo '?')"
+        gov="$(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo unknown)"
+        turbo="$(cat /sys/devices/system/cpu/intel_pstate/no_turbo 2>/dev/null || echo '?')"
+        emit "cpu_governor" "$gov"
+        emit "freq_pinned" "governor=$gov intel_pstate.no_turbo=$turbo (1 = turbo off)"
+        ;;
+    *)
+        emit "os_product" "$os (unrecognized — CPU/RAM not captured)"
+        ;;
+esac
diff --git a/benchmarks-jvm/results/README.md b/benchmarks-jvm/results/README.md
new file mode 100644
index 0000000..b96d44d
--- /dev/null
+++ b/benchmarks-jvm/results/README.md
@@ -0,0 +1,30 @@
+# Benchmark results
+
+Committed result bundles from the Phase 6 validation matrix. Each subdirectory is one
+run on one machine, self-described by its `environment.txt`. See
+[`docs/benchmarking.md`](../../docs/benchmarking.md) for the method and
+[`../run-matrix.sh`](../run-matrix.sh) for how a bundle is produced.
+
+## Layout
+
+```
+<label>/
+  environment.txt    JDK + OS + CPU + whether CPU frequency was pinned
+  footprint.md/tsv   exact retained-heap footprint (JOL), deterministic
+  jmh-results.json   the JMH time matrix (authoritative runs only)
+  *.md               human-readable summaries
+```
+
+## Bundles
+
+- **`m4max-indicative/`** — Apple M4 Max, Corretto 17, an **unpinned dev machine**.
+  The **footprint numbers are authoritative** (JOL is deterministic and
+  hardware-independent); the **time numbers are indicative only** (turbo / P-E
+  scheduling not controllable) and are kept for their *distribution-robustness ratio*,
+  not their absolute values.
+
+## Adding an authoritative run
+
+Run `../run-matrix.sh <label>` on a machine where you can pin CPU frequency and keep
+the box idle, then commit the resulting `benchmarks-jvm/results/<label>/`. State in
+`environment.txt` (it prompts for this) exactly what you could and could not control.
diff --git a/benchmarks-jvm/results/m4max-indicative/environment.txt b/benchmarks-jvm/results/m4max-indicative/environment.txt
new file mode 100644
index 0000000..b54a7fe
--- /dev/null
+++ b/benchmarks-jvm/results/m4max-indicative/environment.txt
@@ -0,0 +1,10 @@
+captured_at=2026-07-04T01:03:47Z
+java_version=openjdk version "17.0.14" 2025-01-21 LTS|OpenJDK Runtime Environment Corretto-17.0.14.7.1 (build 17.0.14+7-LTS)|OpenJDK 64-Bit Server VM Corretto-17.0.14.7.1 (build 17.0.14+7-LTS, mixed mode, sharing)
+java_home=/Library/Java/JavaVirtualMachines/amazon-corretto-17.jdk/Contents/Home
+os_kernel=Darwin 25.5.0 arm64
+os_product=macOS 26.5 (25F5058e)
+cpu_model=Apple M4 Max
+cpu_physical_cores=16
+cpu_logical_cores=16
+ram_bytes=137438953472
+freq_pinned=no (Apple Silicon: turbo/P-E scheduling not controllable)
diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.md b/benchmarks-jvm/results/m4max-indicative/footprint.md
new file mode 100644
index 0000000..726bd32
--- /dev/null
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.md
@@ -0,0 +1,13 @@
+# Retained-heap footprint (JOL), n = 229376 entries
+
+Bytes per entry, each map pre-sized in its own units at equal occupancy.
+Ratio is versus the boxed `HashMap` baseline (higher = more compact).
+
+| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
+|------|-------------------|-----------|-----------------|-----------|
+| OURS     |    19 | 4.68x |    10 | 7.30x |
+| HASH_MAP |    89 | 1.00x |    73 | 1.00x |
+| FASTUTIL |    36 | 2.47x |    18 | 4.06x |
+| HPPC     |    36 | 2.47x |    18 | 4.06x |
+| ECLIPSE  |    36 | 2.47x |    18 | 4.06x |
+| AGRONA   |    36 | 2.47x |    18 | 4.06x |
diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.tsv b/benchmarks-jvm/results/m4max-indicative/footprint.tsv
new file mode 100644
index 0000000..7abc84c
--- /dev/null
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.tsv
@@ -0,0 +1,13 @@
+impl	cell	totalBytes	bytesPerEntry
+OURS	LongLong	4456592	19
+HASH_MAP	LongLong	20444224	89
+FASTUTIL	LongLong	8388728	36
+HPPC	LongLong	8388704	36
+ECLIPSE	LongLong	8388688	36
+AGRONA	LongLong	8388680	36
+OURS	IntInt	2359432	10
+HASH_MAP	IntInt	16775232	73
+FASTUTIL	IntInt	4194416	18
+HPPC	IntInt	4194400	18
+ECLIPSE	IntInt	4194376	18
+AGRONA	IntInt	4194368	18
diff --git a/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md b/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
new file mode 100644
index 0000000..33563ef
--- /dev/null
+++ b/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
@@ -0,0 +1,25 @@
+# `lookupHit` at 1M — indicative (NOT authoritative)
+
+**Indicative single-machine numbers, unpinned hardware, 1–2 JMH forks.** Absolute
+values are not citable (Apple Silicon turbo / P-E scheduling is not controllable —
+see `environment.txt`). What is robust here is the **ratio between distributions**,
+whose effect dwarfs the run-to-run noise. Regenerate absolute numbers on pinned
+hardware with `../../run-matrix.sh`.
+
+`LongLongMatrixBenchmark.lookupHit`, `size=1000000`, `AverageTime` (ns per full sweep
+of 1M random-access lookups):
+
+| `dist` | `OURS` | `FASTUTIL` | `HPPC` | `ECLIPSE` | `AGRONA` | `HASH_MAP` |
+|--------|-------:|-----------:|-------:|----------:|---------:|-----------:|
+| `DENSE` | 9.9 ms | 7.7 ms | 8.7 ms | 2.0 ms | 8.4 ms | 14.3 ms |
+| `CLUSTERED` | 10.2 ms | 36 ms | — | 13 ms | — | — |
+
+**Reading it.** On dense keys Eclipse's weak spread keeps `0..n-1` contiguous and
+cache-resident, so it wins; on clustered keys (low bits zeroed) that same weak spread
+produces long probe chains and it degrades ~6×, and fastutil ~5×. `OURS` is flat
+across distributions (its `fmix64` finalizer scatters strided keys as well as dense
+ones) and becomes the **fastest** map under adversarial keys. A dense-only benchmark
+would have inverted this conclusion.
+
+The `—` cells were not run in this indicative slice; the full matrix
+(`run-matrix.sh`) sweeps every `impl × dist × op × size`.
diff --git a/benchmarks-jvm/run-matrix.sh b/benchmarks-jvm/run-matrix.sh
new file mode 100755
index 0000000..929b79c
--- /dev/null
+++ b/benchmarks-jvm/run-matrix.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Runs the Phase 6 validation matrix and collects a self-describing, reproducible
+# results bundle under `benchmarks-jvm/results/<label>/`:
+#
+#   environment.txt   the machine + JDK identity (see capture-env.sh)
+#   footprint.md/tsv  exact retained-heap footprint (JOL), ours vs competitors
+#   jmh-results.json  the authoritative JMH time matrix (fork 3, 5x1s + 5x1s)
+#
+# The JMH settings come from the `jmh {}` block in build.gradle.kts and match the
+# project methodology (@Fork 3, warmup 5x1s, measurement 5x1s, AverageTime).
+# Key sets are seeded deterministically (seed 42) and shared across maps, so a
+# rerun on the same hardware reproduces the numbers within noise.
+#
+# WARNING: the full matrix is long (roughly a few hours on a quiet machine). Pin
+# CPU frequency where you can, keep the machine otherwise idle, and record what
+# you could not control — `environment.txt` prompts for exactly that. For a quick
+# check, run a filtered slice from the jar directly (see docs/benchmarking.md).
+#
+# Usage: ./benchmarks-jvm/run-matrix.sh [label]
+set -euo pipefail
+
+LABEL="${1:-local}"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$HERE/.." && pwd)"
+OUT="$HERE/results/$LABEL"
+mkdir -p "$OUT"
+
+echo "==> Capturing environment into $OUT/environment.txt"
+"$HERE/capture-env.sh" > "$OUT/environment.txt"
+cat "$OUT/environment.txt"
+
+echo "==> Retained-heap footprint (JOL)"
+"$ROOT/gradlew" :benchmarks-jvm:footprintReport --console=plain
+cp "$HERE/build/reports/footprint/footprint.md" "$OUT/footprint.md"
+cp "$HERE/build/reports/footprint/footprint.tsv" "$OUT/footprint.tsv"
+
+echo "==> JMH time matrix (authoritative; this takes a while)"
+"$ROOT/gradlew" :benchmarks-jvm:jmh --console=plain
+cp "$HERE/build/reports/jmh/results.json" "$OUT/jmh-results.json"
+
+echo "==> Done. Results bundle: $OUT"
+ls -la "$OUT"
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/CompetitorAdapters.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/CompetitorAdapters.kt
new file mode 100644
index 0000000..2b1a8d2
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/CompetitorAdapters.kt
@@ -0,0 +1,264 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import io.spine.elastic.IntIntMap
+import io.spine.elastic.LongLongMap
+import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap
+import it.unimi.dsi.fastutil.longs.Long2LongOpenHashMap
+import org.agrona.collections.Hashing
+import org.agrona.collections.Int2IntHashMap
+import org.agrona.collections.Long2LongHashMap
+
+/**
+ * Adapters that present each benchmarked primitive map — ours, the boxed standard
+ * library, and the four reference-ceiling competitors — behind one monomorphic
+ * interface, so a JMH `@Param impl` can select between them without polluting the
+ * call site's type profile (each `impl` value runs in its own fork).
+ *
+ * ### The comparison is primitive-vs-primitive, each map in its own units
+ *
+ * Every adapter is pre-sized for the same target entry count `n`, but **in the
+ * map's own capacity units** (the Phase 1 fairness rule): our maps take an
+ * expected-entry hint; `HashMap` is pre-sized at its 0.75 load; the primitive
+ * competitors take their own expected-element or initial-capacity arguments. No
+ * map is forced onto another's load factor — each runs at its natural operating
+ * point. The boxed `HashMap` is the *baseline the project commits to beating*;
+ * the four primitive competitors are a *reference ceiling* (fastutil/HPPC are
+ * co-fastest among the classic open-addressing libraries), never a success gate.
+ *
+ * ### Absent-key conventions differ, and that is fine here
+ *
+ * `get` on a missing key returns each map's own "absent" marker — 0 for ours,
+ * fastutil (default return value), HPPC, and Eclipse; the configured
+ * `missingValue` for Agrona; `null`→0 for the boxed map. Lookup-miss benchmarks
+ * only consume the returned primitive through a sink, so the differing sentinels
+ * are immaterial to what is measured (the probe cost of proving absence).
+ */
+
+/** Selects our [LongLongMap] / [IntIntMap]. */
+internal const val OURS = "OURS"
+
+/** Selects the boxed `HashMap` baseline — the standard library, the bar to beat. */
+internal const val HASH_MAP = "HASH_MAP"
+
+/** Selects fastutil's `*2*OpenHashMap`. */
+internal const val FASTUTIL = "FASTUTIL"
+
+/** Selects HPPC's `**HashMap`. */
+internal const val HPPC = "HPPC"
+
+/** Selects Eclipse Collections' primitive `**HashMap`. */
+internal const val ECLIPSE = "ECLIPSE"
+
+/** Selects Agrona's `*2*HashMap`. */
+internal const val AGRONA = "AGRONA"
+
+/** All implementations in the matrix, in reporting order (ours first, baseline second). */
+internal val ALL_IMPLS = listOf(OURS, HASH_MAP, FASTUTIL, HPPC, ECLIPSE, AGRONA)
+
+/** The JDK default load factor; pre-sizes the boxed map in its own units. */
+private const val JDK_LOAD_FACTOR = 0.75
+
+/**
+ * Agrona reserves one value as the "absent" sentinel; it can never be stored. All
+ * benchmark values are non-negative (a key, or a shifted key), so the extreme
+ * negative sentinels are always outside the value domain.
+ */
+private const val AGRONA_MISSING_LONG = Long.MIN_VALUE
+private const val AGRONA_MISSING_INT = Int.MIN_VALUE
+
+/**
+ * Agrona's map constructors take a raw **slot capacity**, not an expected-entry count
+ * (unlike the other five maps here), and resize once `size` exceeds
+ * `capacity · loadFactor`. To hold [expectedSize] entries at Agrona's default load
+ * without a hidden resize, the slot count must be `expectedSize / loadFactor` — the
+ * same in-its-own-units pre-sizing the boxed `HashMap` gets. Sizing Agrona by
+ * `expectedSize` directly would force a rehash mid-`insertPresized` and measure its
+ * footprint at half occupancy.
+ */
+internal fun agronaSlots(expectedSize: Int): Int =
+    (expectedSize / Hashing.DEFAULT_LOAD_FACTOR).toInt() + 1
+
+/**
+ * A `Long`→`Long` map seen through the operations the matrix measures. `iterate`
+ * is intentionally absent: our primitive-value maps expose no non-boxing
+ * traversal (a lean-surface choice, DP-10), so a fair head-to-head cannot include
+ * it — the matrix compares lookup, insert, and churn.
+ */
+internal interface LongLongCell {
+    fun put(key: Long, value: Long)
+    fun get(key: Long): Long
+    fun remove(key: Long)
+    fun size(): Int
+}
+
+/** The `Int`→`Int` twin of [LongLongCell]. */
+internal interface IntIntCell {
+    fun put(key: Int, value: Int)
+    fun get(key: Int): Int
+    fun remove(key: Int)
+    fun size(): Int
+}
+
+/**
+ * Creates the `Long`→`Long` adapter selected by [impl], pre-sized for [expectedSize]
+ * entries in the map's own units. Passing `expectedSize <= 0` builds a
+ * default-capacity map — the growing-insert case.
+ */
+@Suppress("MagicNumber") // Fastutil/Agrona load-factor presets are named at the call site.
+internal fun createLongLong(impl: String, expectedSize: Int): LongLongCell {
+    val presized = expectedSize > 0
+    return when (impl) {
+        OURS -> object : LongLongCell {
+            private val map = if (presized) LongLongMap(expectedSize) else LongLongMap()
+            override fun put(key: Long, value: Long) { map.put(key, value) }
+            override fun get(key: Long): Long = map[key]
+            override fun remove(key: Long) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        HASH_MAP -> object : LongLongCell {
+            private val map =
+                if (presized) HashMap<Long, Long>((expectedSize / JDK_LOAD_FACTOR).toInt() + 1)
+                else HashMap()
+            override fun put(key: Long, value: Long) { map[key] = value }
+            override fun get(key: Long): Long = map[key] ?: 0L
+            override fun remove(key: Long) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        FASTUTIL -> object : LongLongCell {
+            private val map =
+                if (presized) Long2LongOpenHashMap(expectedSize) else Long2LongOpenHashMap()
+            override fun put(key: Long, value: Long) { map.put(key, value) }
+            override fun get(key: Long): Long = map.get(key)
+            override fun remove(key: Long) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        HPPC -> object : LongLongCell {
+            private val map =
+                if (presized) com.carrotsearch.hppc.LongLongHashMap(expectedSize)
+                else com.carrotsearch.hppc.LongLongHashMap()
+            override fun put(key: Long, value: Long) { map.put(key, value) }
+            override fun get(key: Long): Long = map.get(key)
+            override fun remove(key: Long) { map.remove(key) }
+            override fun size(): Int = map.size()
+        }
+        ECLIPSE -> object : LongLongCell {
+            private val map =
+                if (presized)
+                    org.eclipse.collections.impl.map.mutable.primitive.LongLongHashMap(expectedSize)
+                else org.eclipse.collections.impl.map.mutable.primitive.LongLongHashMap()
+            override fun put(key: Long, value: Long) { map.put(key, value) }
+            override fun get(key: Long): Long = map.get(key)
+            override fun remove(key: Long) { map.removeKey(key) }
+            override fun size(): Int = map.size()
+        }
+        AGRONA -> object : LongLongCell {
+            private val map =
+                if (presized)
+                    Long2LongHashMap(
+                        agronaSlots(expectedSize), Hashing.DEFAULT_LOAD_FACTOR, AGRONA_MISSING_LONG,
+                    )
+                else Long2LongHashMap(AGRONA_MISSING_LONG)
+            override fun put(key: Long, value: Long) { map.put(key, value) }
+            override fun get(key: Long): Long = map.get(key)
+            override fun remove(key: Long) { map.remove(key) }
+            // Agrona's maps implement `java.util.Map`, so `size` is a Kotlin property.
+            override fun size(): Int = map.size
+        }
+        else -> throw IllegalArgumentException("Unknown map implementation: `$impl`.")
+    }
+}
+
+/**
+ * Creates the `Int`→`Int` adapter selected by [impl], pre-sized for [expectedSize]
+ * entries in the map's own units. Passing `expectedSize <= 0` builds a
+ * default-capacity map — the growing-insert case.
+ */
+@Suppress("MagicNumber")
+internal fun createIntInt(impl: String, expectedSize: Int): IntIntCell {
+    val presized = expectedSize > 0
+    return when (impl) {
+        OURS -> object : IntIntCell {
+            private val map = if (presized) IntIntMap(expectedSize) else IntIntMap()
+            override fun put(key: Int, value: Int) { map.put(key, value) }
+            override fun get(key: Int): Int = map[key]
+            override fun remove(key: Int) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        HASH_MAP -> object : IntIntCell {
+            private val map =
+                if (presized) HashMap<Int, Int>((expectedSize / JDK_LOAD_FACTOR).toInt() + 1)
+                else HashMap()
+            override fun put(key: Int, value: Int) { map[key] = value }
+            override fun get(key: Int): Int = map[key] ?: 0
+            override fun remove(key: Int) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        FASTUTIL -> object : IntIntCell {
+            private val map =
+                if (presized) Int2IntOpenHashMap(expectedSize) else Int2IntOpenHashMap()
+            override fun put(key: Int, value: Int) { map.put(key, value) }
+            override fun get(key: Int): Int = map.get(key)
+            override fun remove(key: Int) { map.remove(key) }
+            override fun size(): Int = map.size
+        }
+        HPPC -> object : IntIntCell {
+            private val map =
+                if (presized) com.carrotsearch.hppc.IntIntHashMap(expectedSize)
+                else com.carrotsearch.hppc.IntIntHashMap()
+            override fun put(key: Int, value: Int) { map.put(key, value) }
+            override fun get(key: Int): Int = map.get(key)
+            override fun remove(key: Int) { map.remove(key) }
+            override fun size(): Int = map.size()
+        }
+        ECLIPSE -> object : IntIntCell {
+            private val map =
+                if (presized)
+                    org.eclipse.collections.impl.map.mutable.primitive.IntIntHashMap(expectedSize)
+                else org.eclipse.collections.impl.map.mutable.primitive.IntIntHashMap()
+            override fun put(key: Int, value: Int) { map.put(key, value) }
+            override fun get(key: Int): Int = map.get(key)
+            override fun remove(key: Int) { map.removeKey(key) }
+            override fun size(): Int = map.size()
+        }
+        AGRONA -> object : IntIntCell {
+            private val map =
+                if (presized)
+                    Int2IntHashMap(
+                        agronaSlots(expectedSize), Hashing.DEFAULT_LOAD_FACTOR, AGRONA_MISSING_INT,
+                    )
+                else Int2IntHashMap(AGRONA_MISSING_INT)
+            override fun put(key: Int, value: Int) { map.put(key, value) }
+            override fun get(key: Int): Int = map.get(key)
+            override fun remove(key: Int) { map.remove(key) }
+            // Agrona's maps implement `java.util.Map`, so `size` is a Kotlin property.
+            override fun size(): Int = map.size
+        }
+        else -> throw IllegalArgumentException("Unknown map implementation: `$impl`.")
+    }
+}
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
new file mode 100644
index 0000000..11b2bd5
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
@@ -0,0 +1,141 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import io.spine.elastic.IntIntMap
+import io.spine.elastic.LongLongMap
+import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap
+import it.unimi.dsi.fastutil.longs.Long2LongOpenHashMap
+import java.io.File
+import org.agrona.collections.Hashing
+import org.agrona.collections.Int2IntHashMap
+import org.agrona.collections.Long2LongHashMap
+import org.openjdk.jol.info.GraphLayout
+
+/**
+ * The **memory** half of the Phase 6 matrix: the exact retained heap of every map,
+ * measured with JOL (Java Object Layout) — deterministic, not a GC estimate —
+ * reported as bytes per entry and as a ratio against the boxed `HashMap` baseline.
+ *
+ * Each map is built raw (no adapter wrapper, so JOL measures only the map's own
+ * object graph), pre-sized in its own units for the same entry count, and filled
+ * with dense keys. The count `n` is the `7/8` load of a `2^18`-slot table, so our
+ * SwissTable-family maps sit exactly at capacity with no power-of-two slack — a
+ * realistic, equal-occupancy comparison point (the same `n` the library's own
+ * `MemoryFootprintSpec` guard uses).
+ *
+ * Run with `./gradlew :benchmarks-jvm:footprintReport`; the Markdown + TSV land in
+ * `benchmarks-jvm/build/reports/footprint/`.
+ */
+fun main(args: Array<String>) {
+    val outDir = File(args.firstOrNull() ?: "build/reports/footprint")
+    outDir.mkdirs()
+
+    val n = LOAD_NUMERATOR * (1 shl LOG2_CAPACITY) / LOAD_DENOMINATOR
+    val longLong = ALL_IMPLS.map { impl -> measure(impl, n) { buildLongLong(impl, n) } }
+    val intInt = ALL_IMPLS.map { impl -> measure(impl, n) { buildIntInt(impl, n) } }
+
+    val markdown = renderMarkdown(n, longLong, intInt)
+    val tsv = renderTsv(longLong, intInt)
+    File(outDir, "footprint.md").writeText(markdown)
+    File(outDir, "footprint.tsv").writeText(tsv)
+    println(markdown)
+    println("Wrote ${File(outDir, "footprint.md")} and ${File(outDir, "footprint.tsv")}")
+}
+
+/** One measured cell: retained bytes and bytes-per-entry for an implementation. */
+private data class Footprint(val impl: String, val totalBytes: Long, val bytesPerEntry: Long)
+
+private inline fun measure(impl: String, entries: Int, build: () -> Any): Footprint {
+    val map = build()
+    val total = GraphLayout.parseInstance(map).totalSize()
+    return Footprint(impl, total, total / entries)
+}
+
+private fun buildLongLong(impl: String, n: Int): Any = when (impl) {
+    OURS -> LongLongMap(n).apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    HASH_MAP -> HashMap<Long, Long>((n / JDK_LOAD).toInt() + 1)
+        .apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    FASTUTIL -> Long2LongOpenHashMap(n).apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    HPPC -> com.carrotsearch.hppc.LongLongHashMap(n)
+        .apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    ECLIPSE -> org.eclipse.collections.impl.map.mutable.primitive.LongLongHashMap(n)
+        .apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    AGRONA -> Long2LongHashMap(agronaSlots(n), Hashing.DEFAULT_LOAD_FACTOR, Long.MIN_VALUE)
+        .apply { for (i in 0 until n) put(i.toLong(), i.toLong()) }
+    else -> throw IllegalArgumentException("Unknown implementation: `$impl`.")
+}
+
+private fun buildIntInt(impl: String, n: Int): Any = when (impl) {
+    OURS -> IntIntMap(n).apply { for (i in 0 until n) put(i, i) }
+    HASH_MAP -> HashMap<Int, Int>((n / JDK_LOAD).toInt() + 1)
+        .apply { for (i in 0 until n) put(i, i) }
+    FASTUTIL -> Int2IntOpenHashMap(n).apply { for (i in 0 until n) put(i, i) }
+    HPPC -> com.carrotsearch.hppc.IntIntHashMap(n).apply { for (i in 0 until n) put(i, i) }
+    ECLIPSE -> org.eclipse.collections.impl.map.mutable.primitive.IntIntHashMap(n)
+        .apply { for (i in 0 until n) put(i, i) }
+    AGRONA -> Int2IntHashMap(agronaSlots(n), Hashing.DEFAULT_LOAD_FACTOR, Int.MIN_VALUE)
+        .apply { for (i in 0 until n) put(i, i) }
+    else -> throw IllegalArgumentException("Unknown implementation: `$impl`.")
+}
+
+private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footprint>): String {
+    val baselineLong = longLong.first { it.impl == HASH_MAP }.bytesPerEntry
+    val baselineInt = intInt.first { it.impl == HASH_MAP }.bytesPerEntry
+    val rows = ALL_IMPLS.joinToString("\n") { impl ->
+        val ll = longLong.first { it.impl == impl }
+        val ii = intInt.first { it.impl == impl }
+        "| %-8s | %5d | %s | %5d | %s |".format(
+            impl, ll.bytesPerEntry, ratio(baselineLong, ll.bytesPerEntry),
+            ii.bytesPerEntry, ratio(baselineInt, ii.bytesPerEntry),
+        )
+    }
+    return buildString {
+        appendLine("# Retained-heap footprint (JOL), n = $n entries")
+        appendLine()
+        appendLine("Bytes per entry, each map pre-sized in its own units at equal occupancy.")
+        appendLine("Ratio is versus the boxed `HashMap` baseline (higher = more compact).")
+        appendLine()
+        appendLine("| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |")
+        appendLine("|------|-------------------|-----------|-----------------|-----------|")
+        appendLine(rows)
+    }
+}
+
+private fun renderTsv(longLong: List<Footprint>, intInt: List<Footprint>): String = buildString {
+    appendLine("impl\tcell\ttotalBytes\tbytesPerEntry")
+    longLong.forEach { appendLine("${it.impl}\tLongLong\t${it.totalBytes}\t${it.bytesPerEntry}") }
+    intInt.forEach { appendLine("${it.impl}\tIntInt\t${it.totalBytes}\t${it.bytesPerEntry}") }
+}
+
+private fun ratio(baseline: Long, value: Long): String =
+    if (value == 0L) "n/a" else "%.2fx".format(baseline.toDouble() / value)
+
+private const val LOG2_CAPACITY = 18
+private const val LOAD_NUMERATOR = 7
+private const val LOAD_DENOMINATOR = 8
+private const val JDK_LOAD = 0.75
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
new file mode 100644
index 0000000..af63aa0
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
@@ -0,0 +1,159 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import java.util.concurrent.TimeUnit
+import org.openjdk.jmh.annotations.Benchmark
+import org.openjdk.jmh.annotations.BenchmarkMode
+import org.openjdk.jmh.annotations.Fork
+import org.openjdk.jmh.annotations.Measurement
+import org.openjdk.jmh.annotations.Mode
+import org.openjdk.jmh.annotations.OutputTimeUnit
+import org.openjdk.jmh.annotations.Param
+import org.openjdk.jmh.annotations.Scope
+import org.openjdk.jmh.annotations.Setup
+import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Warmup
+import org.openjdk.jmh.infra.Blackhole
+
+/**
+ * The `Int`→`Int` cell of the Phase 6 comparative matrix — the densest cell (8
+ * payload bytes per entry, half of `Long`→`Long`) — measuring our `IntIntMap`
+ * against boxed `HashMap<Int, Int>` and the four primitive competitors.
+ *
+ * Structure, fairness discipline, and reported unit (ns per full sweep of `size`
+ * entries) are identical to [LongLongMatrixBenchmark]; see its KDoc. The `Int`
+ * [CLUSTERED] set is milder than the `Long` one because a hard-collision key set
+ * cannot be built in-range for a million entries (see `docs/benchmarking.md`).
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(3)
+open class IntIntMatrixBenchmark {
+
+    @Param(OURS, HASH_MAP, FASTUTIL, HPPC, ECLIPSE, AGRONA)
+    lateinit var impl: String
+
+    @Param("10000", "1000000")
+    var size: Int = 0
+
+    @Param(DENSE, CLUSTERED)
+    lateinit var dist: String
+
+    private var keys: IntArray = IntArray(0)
+    private var shuffledKeys: IntArray = IntArray(0)
+    private var missKeys: IntArray = IntArray(0)
+    private lateinit var populated: IntIntCell
+
+    @Setup
+    fun setUp() {
+        val n = size
+        keys = intKeys(n, dist)
+        shuffledKeys = shuffledInt(keys)
+        missKeys = intMissKeys(n, dist)
+        val map = createIntInt(impl, n)
+        for (key in keys) {
+            map.put(key, key)
+        }
+        check(map.size() == n) { "Expected $n entries in `$impl`, got ${map.size()}." }
+        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key's
+        // value is the key, so the sum of all hit lookups must equal the sum of keys —
+        // this catches any silent get/put defect before a single number is measured.
+        // Widen to `Long` so a 1M-entry sum cannot overflow `Int`.
+        var hitSum = 0L
+        var expected = 0L
+        for (key in keys) {
+            hitSum += map.get(key).toLong()
+            expected += key.toLong()
+        }
+        check(hitSum == expected) {
+            "Adapter `$impl` returned wrong values: hit sum $hitSum != $expected."
+        }
+        populated = map
+    }
+
+    /** Random-access hit lookup — the fair lookup gate. */
+    @Benchmark
+    fun lookupHit(blackhole: Blackhole) {
+        val m = populated
+        var sink = 0
+        for (key in shuffledKeys) {
+            sink += m.get(key)
+        }
+        blackhole.consume(sink)
+    }
+
+    /** Lookup of keys guaranteed absent — the cost of proving a miss. */
+    @Benchmark
+    fun lookupMiss(blackhole: Blackhole) {
+        val m = populated
+        var sink = 0
+        for (key in missKeys) {
+            sink += m.get(key)
+        }
+        blackhole.consume(sink)
+    }
+
+    /** Build a fresh map pre-sized for `size`, then insert every key. */
+    @Benchmark
+    fun insertPresized(blackhole: Blackhole) {
+        val fresh = createIntInt(impl, size)
+        for (key in keys) {
+            fresh.put(key, key)
+        }
+        blackhole.consume(fresh)
+    }
+
+    /** Build a fresh default-capacity map and insert every key — folds in resize cost. */
+    @Benchmark
+    fun insertGrowing(blackhole: Blackhole) {
+        val fresh = createIntInt(impl, 0)
+        for (key in keys) {
+            fresh.put(key, key)
+        }
+        blackhole.consume(fresh)
+    }
+
+    /**
+     * Remove then re-insert every key — a size-stable churn cycle (remove + insert cost).
+     * Mutates the shared populated map in place; open-addressing maps accumulate tombstones
+     * across the iteration's invocations, so periodic tombstone-cleanup rebuilds are part of
+     * the measured churn cost (the same for all six impls) — intentional, not an oversight.
+     */
+    @Benchmark
+    fun churn(blackhole: Blackhole) {
+        val m = populated
+        for (key in shuffledKeys) {
+            m.remove(key)
+            m.put(key, key)
+        }
+        blackhole.consume(m)
+    }
+}
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
new file mode 100644
index 0000000..e05a096
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
@@ -0,0 +1,163 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import it.unimi.dsi.fastutil.longs.Long2LongOpenHashMap
+import java.util.concurrent.TimeUnit
+import kotlin.math.roundToInt
+import org.agrona.collections.Long2LongHashMap
+import org.openjdk.jmh.annotations.Benchmark
+import org.openjdk.jmh.annotations.BenchmarkMode
+import org.openjdk.jmh.annotations.Fork
+import org.openjdk.jmh.annotations.Measurement
+import org.openjdk.jmh.annotations.Mode
+import org.openjdk.jmh.annotations.OutputTimeUnit
+import org.openjdk.jmh.annotations.Param
+import org.openjdk.jmh.annotations.Scope
+import org.openjdk.jmh.annotations.Setup
+import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Warmup
+import org.openjdk.jmh.infra.Blackhole
+
+/**
+ * Lookup cost as a function of **load factor**, for the three competitors that
+ * expose a settable load factor (fastutil, HPPC, Agrona). This is the Phase 6
+ * answer to "how does probe cost grow as the table fills toward 0.99".
+ *
+ * ### Why only these three
+ *
+ * Our SwissTable-family maps run at a **fixed** maximum load (`7/8 = 0.875`, then
+ * they grow), and `HashMap` resizes at `0.75` — neither can be *held* at an
+ * arbitrary load, so they are fixed reference points (their 1M lookup numbers come
+ * from [LongLongMatrixBenchmark]), not sweepable here. The paper structures
+ * (`FunnelLongMap`, `ElasticLongMap`) are the ones designed for ≈0.99; their
+ * high-load behavior is covered by their own probe-bound specs, not this
+ * wall-clock sweep.
+ *
+ * ### Hitting a target load on a power-of-two table
+ *
+ * A power-of-two open-addressing table can only sit at loads in `(lf_max/2, lf_max]`
+ * — capacity doubles at each boundary. To land on a *chosen* load, the capacity is
+ * pinned at `2^20` and the number of inserted entries is set to
+ * `fill = round(loadFactor · 2^20)`; each map is constructed with the maximum load
+ * factor (`0.99`) so it does not resize before reaching `fill`. Every invocation
+ * then performs the **same** `2^20` random-access lookups (cycling through the
+ * present keys), so scores are directly comparable across the load-factor axis:
+ * the only thing changing is probe-chain length.
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(3)
+open class LoadFactorBenchmark {
+
+    @Param(FASTUTIL, HPPC, AGRONA)
+    lateinit var impl: String
+
+    @Param("0.50", "0.75", "0.90", "0.95", "0.99")
+    var loadFactor: Double = 0.0
+
+    private var shuffledKeys: LongArray = LongArray(0)
+    private var fill: Int = 0
+    private lateinit var populated: LongLongCell
+
+    @Setup
+    fun setUp() {
+        fill = (loadFactor * CAPACITY).roundToInt()
+        val keys = LongArray(fill) { it.toLong() }
+        shuffledKeys = shuffledLong(keys)
+        val map = createAtMaxLoad(impl, fill)
+        for (key in keys) {
+            map.put(key, key)
+        }
+        check(map.size() == fill) { "Expected $fill entries in `$impl`, got ${map.size()}." }
+        populated = map
+    }
+
+    /** Exactly `2^20` random-access hit lookups, cycling the present keys — load-comparable. */
+    @Benchmark
+    fun lookupHit(blackhole: Blackhole) {
+        val m = populated
+        val keys = shuffledKeys
+        val n = keys.size
+        var idx = 0
+        var sink = 0L
+        repeat(CAPACITY) {
+            sink += m.get(keys[idx])
+            idx++
+            if (idx == n) {
+                idx = 0
+            }
+        }
+        blackhole.consume(sink)
+    }
+
+    private companion object {
+
+        /** The pinned table capacity; entries fill it to the target load. */
+        const val CAPACITY = 1 shl 20
+    }
+}
+
+/**
+ * A [LongLongCell] for one of the load-factor-tunable competitors, constructed to
+ * hold [fill] entries in a `2^20`-slot table without resizing (capacity pinned via
+ * the maximum load factor). Only the three tunable maps are supported.
+ */
+private fun createAtMaxLoad(impl: String, fill: Int): LongLongCell = when (impl) {
+    FASTUTIL -> object : LongLongCell {
+        private val map = Long2LongOpenHashMap(fill, MAX_LOAD_F)
+        override fun put(key: Long, value: Long) { map.put(key, value) }
+        override fun get(key: Long): Long = map.get(key)
+        override fun remove(key: Long) { map.remove(key) }
+        override fun size(): Int = map.size
+    }
+    HPPC -> object : LongLongCell {
+        private val map = com.carrotsearch.hppc.LongLongHashMap(fill, MAX_LOAD_D)
+        override fun put(key: Long, value: Long) { map.put(key, value) }
+        override fun get(key: Long): Long = map.get(key)
+        override fun remove(key: Long) { map.remove(key) }
+        override fun size(): Int = map.size()
+    }
+    AGRONA -> object : LongLongCell {
+        private val map = Long2LongHashMap(1 shl 20, MAX_LOAD_F, Long.MIN_VALUE)
+        override fun put(key: Long, value: Long) { map.put(key, value) }
+        override fun get(key: Long): Long = map.get(key)
+        override fun remove(key: Long) { map.remove(key) }
+        // Agrona's maps implement `java.util.Map`, so `size` is a Kotlin property.
+        override fun size(): Int = map.size
+    }
+    else -> throw IllegalArgumentException("Load factor is not tunable for `$impl`.")
+}
+
+/** The maximum load factor as a `float` for fastutil/Agrona constructors. */
+private const val MAX_LOAD_F = 0.99f
+
+/** The maximum load factor as a `double` for the HPPC constructor. */
+private const val MAX_LOAD_D = 0.99
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
new file mode 100644
index 0000000..775cc29
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
@@ -0,0 +1,164 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import java.util.concurrent.TimeUnit
+import org.openjdk.jmh.annotations.Benchmark
+import org.openjdk.jmh.annotations.BenchmarkMode
+import org.openjdk.jmh.annotations.Fork
+import org.openjdk.jmh.annotations.Measurement
+import org.openjdk.jmh.annotations.Mode
+import org.openjdk.jmh.annotations.OutputTimeUnit
+import org.openjdk.jmh.annotations.Param
+import org.openjdk.jmh.annotations.Scope
+import org.openjdk.jmh.annotations.Setup
+import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Warmup
+import org.openjdk.jmh.infra.Blackhole
+
+/**
+ * The `Long`→`Long` cell of the Phase 6 comparative matrix: our fully-primitive
+ * `LongLongMap` against the boxed `HashMap<Long, Long>` baseline and the four
+ * reference-ceiling primitive competitors (fastutil, HPPC, Eclipse Collections,
+ * Agrona), swept over size and key distribution.
+ *
+ * `impl` runs in its own fork, so each measured call site sees exactly one adapter
+ * type and stays monomorphic — the boxed baseline never pollutes the primitive
+ * maps' type profile, nor vice versa. Every op processes the whole key set per
+ * invocation, so the reported figure is nanoseconds per full sweep of `size`
+ * entries (the same convention as the Phase 1/5 benchmarks); divide by `size` for
+ * per-operation cost.
+ *
+ * Fairness follows the project gate: each map is pre-sized in its own units,
+ * lookups run in a fixed random order, and both a dense and a [CLUSTERED] key set
+ * are swept. The primitive competitors are a *ceiling*, not a gate — the committed
+ * baseline to beat is `HashMap`.
+ */
+@State(Scope.Benchmark)
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.NANOSECONDS)
+@Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
+@Fork(3)
+open class LongLongMatrixBenchmark {
+
+    @Param(OURS, HASH_MAP, FASTUTIL, HPPC, ECLIPSE, AGRONA)
+    lateinit var impl: String
+
+    @Param("10000", "1000000")
+    var size: Int = 0
+
+    @Param(DENSE, CLUSTERED)
+    lateinit var dist: String
+
+    private var keys: LongArray = LongArray(0)
+    private var shuffledKeys: LongArray = LongArray(0)
+    private var missKeys: LongArray = LongArray(0)
+    private lateinit var populated: LongLongCell
+
+    @Setup
+    fun setUp() {
+        val n = size
+        keys = longKeys(n, dist)
+        shuffledKeys = shuffledLong(keys)
+        missKeys = longMissKeys(n, dist)
+        val map = createLongLong(impl, n)
+        for (key in keys) {
+            map.put(key, key)
+        }
+        check(map.size() == n) { "Expected $n entries in `$impl`, got ${map.size()}." }
+        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key's
+        // value is the key, so the sum of all hit lookups must equal the sum of keys —
+        // this catches any silent get/put defect before a single number is measured.
+        var hitSum = 0L
+        for (key in keys) {
+            hitSum += map.get(key)
+        }
+        check(hitSum == keys.sum()) {
+            "Adapter `$impl` returned wrong values: hit sum $hitSum != ${keys.sum()}."
+        }
+        populated = map
+    }
+
+    /** Random-access hit lookup — the fair lookup gate. */
+    @Benchmark
+    fun lookupHit(blackhole: Blackhole) {
+        val m = populated
+        var sink = 0L
+        for (key in shuffledKeys) {
+            sink += m.get(key)
+        }
+        blackhole.consume(sink)
+    }
+
+    /** Lookup of keys guaranteed absent — the cost of proving a miss. */
+    @Benchmark
+    fun lookupMiss(blackhole: Blackhole) {
+        val m = populated
+        var sink = 0L
+        for (key in missKeys) {
+            sink += m.get(key)
+        }
+        blackhole.consume(sink)
+    }
+
+    /** Build a fresh map pre-sized for `size`, then insert every key. */
+    @Benchmark
+    fun insertPresized(blackhole: Blackhole) {
+        val fresh = createLongLong(impl, size)
+        for (key in keys) {
+            fresh.put(key, key)
+        }
+        blackhole.consume(fresh)
+    }
+
+    /** Build a fresh default-capacity map and insert every key — folds in resize cost. */
+    @Benchmark
+    fun insertGrowing(blackhole: Blackhole) {
+        val fresh = createLongLong(impl, 0)
+        for (key in keys) {
+            fresh.put(key, key)
+        }
+        blackhole.consume(fresh)
+    }
+
+    /**
+     * Remove then re-insert every key — a size-stable churn cycle (remove + insert cost).
+     * Mutates the shared populated map in place; open-addressing maps accumulate tombstones
+     * across the iteration's invocations, so periodic tombstone-cleanup rebuilds are part of
+     * the measured churn cost (the same for all six impls) — intentional, not an oversight.
+     */
+    @Benchmark
+    fun churn(blackhole: Blackhole) {
+        val m = populated
+        for (key in shuffledKeys) {
+            m.remove(key)
+            m.put(key, key)
+        }
+        blackhole.consume(m)
+    }
+}
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/MatrixKeys.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/MatrixKeys.kt
new file mode 100644
index 0000000..b7c3378
--- /dev/null
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/MatrixKeys.kt
@@ -0,0 +1,121 @@
+/*
+ * Copyright 2026, TeamDev. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Redistribution and use in source and/or binary forms, with or without
+ * modification, must retain the above copyright notice and the following
+ * disclaimer.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package io.spine.elastic.benchmark.jmh
+
+import kotlin.random.Random
+
+/**
+ * Key-set generation for the comparative matrix, shared by the `Long` and `Int`
+ * benchmarks and the footprint report.
+ *
+ * Two distributions are provided per cell, both mandated by the project's fairness
+ * gate (an adversarial/clustered set must always accompany the friendly one):
+ *
+ * - [DENSE] — consecutive keys `0..n-1`. The easy, cache-friendly case.
+ * - [CLUSTERED] — strided keys with the low bits zeroed (`i shl k`). A
+ *   distribution-sensitivity check: a map whose hash finalizer under-mixes the low
+ *   bits pays for it here. It is *not* a hard-collision adversary — for `Int` keys,
+ *   a set that collides in a million-entry table cannot be built without overflow,
+ *   so the `Int` stride is necessarily milder than the `Long` one (documented in
+ *   `docs/benchmarking.md`).
+ *
+ * Lookup order is always randomized with [shuffledLong] / [shuffledInt] (fixed
+ * seed, identical across maps and runs), so no map is flattered by insertion-order
+ * locality.
+ */
+
+/** Consecutive keys `0..n-1`. */
+internal const val DENSE = "DENSE"
+
+/** Strided keys with low bits zeroed — the distribution-sensitivity set. */
+internal const val CLUSTERED = "CLUSTERED"
+
+/** All distributions in the matrix, in reporting order. */
+internal val ALL_DISTRIBUTIONS = listOf(DENSE, CLUSTERED)
+
+/** Fixed seed so the shuffled order is identical across maps and runs. */
+private const val SHUFFLE_SEED = 42L
+
+/** Low-bit shift for the clustered `Long` set — huge headroom, no overflow at `n ≤ 2^42`. */
+private const val LONG_CLUSTER_SHIFT = 21
+
+/** Low-bit shift for the clustered `Int` set — kept small so miss keys stay positive at 1M. */
+private const val INT_CLUSTER_SHIFT = 8
+
+/** The `n` present keys for the [dist] distribution. */
+internal fun longKeys(n: Int, dist: String): LongArray = when (dist) {
+    DENSE -> LongArray(n) { it.toLong() }
+    CLUSTERED -> LongArray(n) { it.toLong() shl LONG_CLUSTER_SHIFT }
+    else -> throw IllegalArgumentException("Unknown key distribution: `$dist`.")
+}
+
+/** `n` keys guaranteed absent from [longKeys], in the same distribution. */
+internal fun longMissKeys(n: Int, dist: String): LongArray = when (dist) {
+    DENSE -> LongArray(n) { (n + it).toLong() }
+    CLUSTERED -> LongArray(n) { (n + it).toLong() shl LONG_CLUSTER_SHIFT }
+    else -> throw IllegalArgumentException("Unknown key distribution: `$dist`.")
+}
+
+/** The `n` present keys for the [dist] distribution, `Int` cell. */
+internal fun intKeys(n: Int, dist: String): IntArray = when (dist) {
+    DENSE -> IntArray(n) { it }
+    CLUSTERED -> IntArray(n) { it shl INT_CLUSTER_SHIFT }
+    else -> throw IllegalArgumentException("Unknown key distribution: `$dist`.")
+}
+
+/** `n` keys guaranteed absent from [intKeys], in the same distribution. */
+internal fun intMissKeys(n: Int, dist: String): IntArray = when (dist) {
+    DENSE -> IntArray(n) { n + it }
+    CLUSTERED -> IntArray(n) { (n + it) shl INT_CLUSTER_SHIFT }
+    else -> throw IllegalArgumentException("Unknown key distribution: `$dist`.")
+}
+
+/** A deterministically shuffled copy of [keys] (Fisher–Yates, fixed seed). */
+internal fun shuffledLong(keys: LongArray): LongArray {
+    val out = keys.copyOf()
+    val random = Random(SHUFFLE_SEED)
+    for (i in out.indices.reversed()) {
+        val j = random.nextInt(i + 1)
+        val tmp = out[i]
+        out[i] = out[j]
+        out[j] = tmp
+    }
+    return out
+}
+
+/** The [IntArray] twin of [shuffledLong]; same seed, same order for the same size. */
+internal fun shuffledInt(keys: IntArray): IntArray {
+    val out = keys.copyOf()
+    val random = Random(SHUFFLE_SEED)
+    for (i in out.indices.reversed()) {
+        val j = random.nextInt(i + 1)
+        val tmp = out[i]
+        out[i] = out[j]
+        out[j] = tmp
+    }
+    return out
+}
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
new file mode 100644
index 0000000..aca35bd
--- /dev/null
+++ b/docs/benchmarking.md
@@ -0,0 +1,194 @@
+# Benchmarking & reproducibility
+
+This is the operational companion to [`performance-goals.md`](performance-goals.md):
+*how* the Phase 6 validation matrix is run, what it measures, and how to reproduce
+the numbers. `performance-goals.md` fixes the success criteria; this page fixes the
+method.
+
+## What is measured
+
+Two halves, both under `benchmarks-jvm` (the raw-JMH tier — JVM-only, which is where
+the competitor libraries live):
+
+1. **Time** — JMH benchmarks comparing our primitive maps against the boxed
+   standard library and four reference-ceiling competitors, across operation, size,
+   and key distribution. Reported as ns per full sweep of `size` entries.
+2. **Memory** — the exact retained heap of every map, measured with JOL
+   (deterministic, not a GC estimate), reported as bytes per entry.
+
+### The maps in the matrix
+
+| `impl` | Map | Role |
+|--------|-----|------|
+| `OURS` | `LongLongMap` / `IntIntMap` | the subject |
+| `HASH_MAP` | boxed `java.util.HashMap` | **the baseline the project commits to beating** |
+| `FASTUTIL` | `Long2LongOpenHashMap` / `Int2IntOpenHashMap` (8.5.18) | reference ceiling |
+| `HPPC` | `LongLongHashMap` / `IntIntHashMap` (0.10.0) | reference ceiling |
+| `ECLIPSE` | Eclipse Collections primitive `*HashMap` (13.0.0) | reference ceiling |
+| `AGRONA` | `Long2LongHashMap` / `Int2IntHashMap` (2.5.0) | reference ceiling |
+
+The four primitive competitors are a **ceiling, not a gate**: fastutil and HPPC are
+co-fastest among the classic open-addressing libraries, and we do not expect to beat
+them on raw single-thread JVM lookup. Our credible differentiators are **memory
+footprint**, **true Kotlin Multiplatform** (all four competitors are JVM-only), and
+Kotlin-idiomatic ergonomics. The committed win is against `HASH_MAP`.
+
+### Operations (`LongLongMatrixBenchmark`, `IntIntMatrixBenchmark`)
+
+`lookupHit` (random-access, the fair gate), `lookupMiss`, `insertPresized`,
+`insertGrowing` (folds in resize cost), and `churn` (remove + re-insert every key —
+size-stable). There is deliberately **no `iterate` op**: our primitive-value maps
+expose no non-boxing traversal (a lean-surface choice, DP-10), so a fair head-to-head
+cannot include it. Every competitor does offer non-boxing iteration; closing that gap
+is tracked as a follow-up.
+
+### Sizes and key distributions
+
+- **Sizes:** `10_000` (cache-resident) and `1_000_000` (out of cache) — the regimes
+  where the layout advantage is, respectively, marginal and decisive.
+- **Distributions** (`dist`): `DENSE` (consecutive `0..n-1`) and `CLUSTERED` (strided
+  keys, low bits zeroed — a distribution-sensitivity check for the hash finalizer).
+  The `CLUSTERED` `Int` set is necessarily milder than the `Long` one: a key set that
+  collides in a million-entry table cannot be built in-range for 32-bit keys without
+  overflow, so the `Int` stride zeroes only the low 8 bits versus 21 for `Long`.
+
+### Load-factor sweep (`LoadFactorBenchmark`)
+
+Lookup cost as a function of load factor `{0.50, 0.75, 0.90, 0.95, 0.99}`, for the
+three competitors that expose a **settable** load factor (fastutil, HPPC, Agrona).
+Our SwissTable-family maps run at a fixed maximum load (`7/8 = 0.875`, then they
+grow) and `HashMap` resizes at `0.75`, so neither can be *held* at an arbitrary load
+— they are fixed reference points, not sweepable. The high-load (≈0.99) regime is the
+home of the paper structures (`FunnelLongMap`, `ElasticLongMap`), whose bounds are
+asserted by their own probe-count specs rather than this wall-clock sweep.
+
+To land on a chosen load on a power-of-two table, capacity is pinned at `2^20` and the
+entry count is `round(loadFactor · 2^20)`; every invocation then does the same `2^20`
+random lookups, so scores are comparable across the load axis.
+
+## Fairness discipline
+
+Enforced in the harness, not left to convention:
+
+- **Primitive-vs-primitive**, each map **pre-sized in its own units** (ours by
+  expected entries; `HashMap` at its 0.75 load; the competitors by their own
+  expected-element or initial-capacity arguments). No map is forced onto another's
+  load factor.
+- **Random-access lookups** (Fisher–Yates, fixed seed `42`, identical order across
+  maps and runs), so no map is flattered by insertion-order locality.
+- **An adversarial/clustered key set** always accompanies the dense one.
+- **Monomorphic call sites:** JMH runs a separate fork per `impl`, so the measured
+  loop sees exactly one adapter type — the boxed baseline never pollutes the
+  primitive maps' type profile.
+- **A correctness gate in `@Setup`:** each map is verified to return the stored value
+  for every key (the hit-sum must equal the key-sum) before any number is taken — a
+  benchmark on a miswired adapter is worthless.
+
+## Running it
+
+### The full authoritative matrix
+
+```bash
+./benchmarks-jvm/run-matrix.sh <label>
+```
+
+This captures the environment, runs the JOL footprint report, runs the full JMH
+matrix (`@Fork 3`, warmup `5×1s`, measurement `5×1s`, `AverageTime` — the settings in
+`benchmarks-jvm/build.gradle.kts`), and collects a self-describing bundle under
+`benchmarks-jvm/results/<label>/`:
+
+```
+environment.txt   JDK + OS + CPU + whether frequency was pinned
+footprint.md/tsv  retained-heap footprint
+jmh-results.json  the JMH time matrix
+```
+
+The full matrix takes **a few hours** on a quiet machine. Pin CPU frequency where you
+can and keep the machine idle; `environment.txt` records what you could not control
+(on Apple Silicon, turbo and P/E scheduling are not controllable — say so).
+
+### A quick slice
+
+Compile the jar once, then filter with JMH's own CLI:
+
+```bash
+./gradlew :benchmarks-jvm:jmhJar
+JAR=$(ls -t benchmarks-jvm/build/libs/*-jmh.jar | head -1)
+java -jar "$JAR" "LongLongMatrixBenchmark.lookupHit" \
+    -p impl=OURS,HASH_MAP,FASTUTIL -p size=1000000 -p dist=DENSE \
+    -f 1 -wi 3 -i 5 -rf json -rff slice.json
+```
+
+Allocation profiling (`bytes/op`) is a JMH profiler flag, not extra code:
+
+```bash
+java -jar "$JAR" "IntIntMatrixBenchmark.insertGrowing" -prof gc -f 1
+```
+
+### Footprint only (fast, deterministic)
+
+```bash
+./gradlew :benchmarks-jvm:footprintReport
+# -> benchmarks-jvm/build/reports/footprint/footprint.{md,tsv}
+```
+
+JOL runs in reflection mode (no agent needed); the numbers match the library's own
+`MemoryFootprintSpec` guard.
+
+## Result: memory footprint
+
+Retained bytes per entry at `n = 229_376` (the `7/8` load of a `2^18` table), each
+map pre-sized in its own units. Measured with JOL on Apple M4 Max, Corretto 17.
+
+| impl | Long→Long B/entry | vs `HashMap` | Int→Int B/entry | vs `HashMap` |
+|------|------------------:|-------------:|----------------:|-------------:|
+| **`OURS`** | **19** | **4.68×** | **10** | **7.30×** |
+| `HASH_MAP` | 89 | 1.00× | 73 | 1.00× |
+| `FASTUTIL` | 36 | 2.47× | 18 | 4.06× |
+| `HPPC` | 36 | 2.47× | 18 | 4.06× |
+| `ECLIPSE` | 36 | 2.47× | 18 | 4.06× |
+| `AGRONA` | 36 | 2.47× | 18 | 4.06× |
+
+The memory win is decisive and, notably, holds **against the specialist primitive
+libraries too**, not only the boxed baseline: `LongLongMap` (19) is ~1.9× more compact
+than the competitors (36) and `IntIntMap` (10) is ~1.8× more compact than theirs (18).
+The competitors are themselves 2.5×/4.1× more compact than boxed `HashMap`, and we go
+further still — because of load factor and layout: our maps pack keys and values plus
+one control byte per entry at `7/8` load, where the competitors carry parallel
+key/value arrays at a lower occupancy. This is the project's strongest, most portable
+result.
+
+## Result: time
+
+Absolute time numbers are **hardware-specific and must be regenerated on pinned
+hardware** — they are not committed as headline figures (an unpinned laptop with turbo
+and opaque P/E scheduling is not a citable bench). Run `run-matrix.sh` on a controlled
+machine and read `jmh-results.json`. Two findings are *qualitative* and survive the
+hardware caveat, because they are ratios and their effects dwarf the run-to-run noise:
+
+- **vs `HashMap` (the gate):** `OURS` is faster on out-of-cache (`1M`) random-access
+  lookup and on presized insert; in-cache the margin narrows to near parity as the
+  SWAR + `fmix64` arithmetic offsets the saved indirection.
+- **Distribution robustness (the important one).** Our `fmix64` finalizer scatters
+  strided keys as well as dense ones, so `LongLongMap` barely moves between `DENSE`
+  and `CLUSTERED`, while the competitors' lighter mixers collapse on the adversarial
+  set. Indicative `1M` `lookupHit`, Apple M4 Max / Corretto 17 (single-machine, ×1–2
+  forks — the *ratios*, not the absolute ms, are the point):
+
+  | `dist` | `OURS` | `FASTUTIL` | `ECLIPSE` |
+  |--------|-------:|-----------:|----------:|
+  | `DENSE` | 9.9 ms | 7.7 ms | **2.0 ms** |
+  | `CLUSTERED` | **10.2 ms** | 36 ms | 13 ms |
+
+  On dense keys Eclipse's weak spread keeps `0..n-1` contiguous and cache-resident and
+  it wins; on clustered keys that same weak spread produces long probe chains and it
+  degrades ~6×, while fastutil degrades ~5×. `OURS` is essentially flat and becomes the
+  **fastest** map under adversarial keys. A `DENSE`-only benchmark would have inverted
+  this conclusion — which is why the fairness gate mandates the clustered set.
+
+On raw *dense* lookup we sit in the same band as fastutil/HPPC/Agrona, not ahead of
+them; the committed differentiators remain memory, distribution robustness, and
+multiplatform reach — not single-thread dense-key JVM speed.
+
+Report every number with its baseline named and its `environment.txt` alongside;
+never cross-compare JVM and Native as a single figure.
diff --git a/docs/performance-goals.md b/docs/performance-goals.md
index 10f01cb..abf9285 100644
--- a/docs/performance-goals.md
+++ b/docs/performance-goals.md
@@ -132,6 +132,35 @@ functional rather than speed-shaped):**
   entry object per iteration step, documented as interop surface, never the
   hot path.
 
+**Phase 6 — validation matrix (ours vs stdlib + the specialist primitive libraries):**
+
+The competitive matrix (`benchmarks-jvm`) measures our maps against boxed `HashMap`
+*and* the four specialist libraries (fastutil, HPPC, Eclipse Collections, Agrona) —
+the specialists as a **reference ceiling**, not a gate. Method:
+[`benchmarking.md`](benchmarking.md).
+
+- **Memory — met decisively, against everyone.** Retained bytes/entry at
+  `n = 229_376` (JOL, each map pre-sized in its own units): `LongLongMap` **19**
+  (**4.68×** smaller than `HashMap` 89, and **~1.9×** smaller than the four
+  competitors, all **36**); `IntIntMap` **10** (**7.30×** smaller than `HashMap` 73,
+  **~1.8×** smaller than the competitors, all **18**).
+  Our maps are more compact than the specialist primitive libraries too — they pack
+  key + value + one control byte at `7/8` load where the competitors carry parallel
+  arrays at a lower occupancy.
+- **Distribution robustness — met, and the strongest time result.** On `1M`
+  out-of-cache random `lookupHit`, `LongLongMap` is flat from dense to clustered
+  (adversarial) keys, while fastutil degrades ~5× and Eclipse ~6× (Eclipse's weak
+  spread wins on dense, contiguous keys but collapses on strided ones). Our `fmix64`
+  finalizer makes ours the fastest under adversarial keys. Absolute ms are
+  hardware-specific and deferred to a pinned-hardware run; the *ratios* are robust.
+- **vs the specialists on raw dense lookup — as expected, not ahead.** We sit in the
+  same band as fastutil/HPPC/Agrona on dense-key lookup, not ahead of them. This was
+  never the claim; the differentiators are memory, distribution robustness, and true
+  Kotlin Multiplatform (the four competitors are JVM-only).
+- **Reproducibility.** `run-matrix.sh` bundles JDK/OS/CPU metadata (incl. whether CPU
+  frequency was pinned), the footprint report, and the JMH JSON under
+  `benchmarks-jvm/results/<label>/`. Seeds are fixed (42) and shared across maps.
+
 **Fairness gates (all phases):** equalize load factor across maps; pre-size each
 in its own units; always include an **adversarial/clustered key set**; lookup
 benchmarks must include a **random-access (shuffled) order**, not just sequential
diff --git a/docs/project.md b/docs/project.md
index aed121d..1f0cd9c 100644
--- a/docs/project.md
+++ b/docs/project.md
@@ -37,8 +37,10 @@ deferred until there is demand, as the speed win is not credible there.
 - `benchmarks` — the portable tier of the benchmark harness:
   `kotlinx-benchmark` driving real JMH on the JVM and host-native runs.
 - `benchmarks-jvm` — the raw-JMH JVM tier: multi-threaded read-scaling and
-  mixed-load benchmarks that the `kotlinx-benchmark` facade cannot express,
-  and the home for `-prof gc` runs.
+  mixed-load benchmarks that the `kotlinx-benchmark` facade cannot express, the
+  Phase 6 comparative matrix versus the specialist primitive-map libraries
+  (fastutil, HPPC, Eclipse Collections, Agrona) and the JOL footprint report, and
+  the home for `-prof gc` runs.
 - `codegen` — the template-substitution generator behind the Swiss
   specialization matrix; `./gradlew :elastic:generateSwissMaps` regenerates
   the checked-in sources, and `:elastic:verifyGeneratedSwissMaps` (part of
@@ -91,6 +93,14 @@ the `codegen` module (a drift gate in `check` re-renders and byte-compares the
 checked-in sources on every build) — plus opt-in boxed `MutableMap` views:
 fail-fast on the single-threaded maps, weakly consistent snapshot iteration on
 `SingleWriterSwissLongMap` (discharging the Phase-4 phantom-null obligation).
+Phase 6 adds the validation harness — a comparative JMH matrix and JOL footprint
+report versus the standard library and the four specialist primitive-map libraries,
+plus a reproducibility runner — and the release runbook; publication itself is
+human-gated. Measured: our maps are **4.7×/7.3×** more compact than boxed `HashMap`
+(and ~1.9×/1.8× more compact than the specialist primitive libraries), and
+distribution-robust —
+flat from dense to adversarial keys where the competitors degrade ~5–6×. See
+[`benchmarking.md`](benchmarking.md) and [`publishing.md`](publishing.md).
 
 Read [`.agents/guidelines/jvm-project.md`](../.agents/guidelines/jvm-project.md)
 for the shared build stack, coding style, tests, and versioning policy that
diff --git a/docs/publishing.md b/docs/publishing.md
new file mode 100644
index 0000000..0bb3725
--- /dev/null
+++ b/docs/publishing.md
@@ -0,0 +1,112 @@
+# Publishing & release runbook
+
+The Phase 6 release step. It is **deliberately not automated**: publishing a
+released version to Maven Central is **irreversible** (an accepted version can never
+be re-uploaded or deleted) and requires **secret credentials** (a signing key and a
+Central Portal token). This page is the checklist a human follows; the safe local
+half can be run any time.
+
+## What a KMP library publishes
+
+The Kotlin Multiplatform plugin produces **one Maven publication per target plus an
+umbrella**, not a single artifact:
+
+| Publication | Coordinates (example) | Role |
+|-------------|-----------------------|------|
+| `kotlinMultiplatform` (root) | `io.spine:elastic:<v>` | umbrella; carries Gradle Module Metadata (`.module`) that redirects common consumers to the right per-target artifact |
+| `jvm` | `io.spine:elastic-jvm:<v>` | JVM jar + POM |
+| `macosArm64` | `io.spine:elastic-macosarm64:<v>` | Apple-silicon klib |
+| `linuxX64`, `linuxArm64`, `mingwX64`, `iosArm64`, `iosSimulatorArm64` | `elastic-<target>` | one klib each |
+
+Each set is the primary artifact + `-sources.jar` + `-javadoc.jar` + `.pom` (+ the
+root `.module`), **each signed (`.asc`) with checksums**. The coordinate suffix is
+the **lowercased** target name (`-macosarm64`, not `-macosArm64`).
+
+**Host constraint:** the Apple-silicon klibs can only be built on **macOS**. Publish
+the whole set **from one macOS host in one shot** — splitting the publication across
+hosts causes Central to reject the deployment. This is why a KMP release runs on a
+Mac (it can build everything a Linux runner can, plus the Apple klibs).
+
+## Safe, local, reversible — do this any time
+
+`publishToMavenLocal` needs **no credentials and no network**, writes only to
+`~/.m2/repository`, and is fully reversible (delete the directory). It is the correct
+smoke test of the publication wiring, POM contents, and artifact set.
+
+```bash
+# The version gate first: a stale version would clobber the Maven-Local artifact
+# that consumer integration tests rely on. (This repo enforces it via a hook.)
+./gradlew :elastic:publishToMavenLocal
+ls -R ~/.m2/repository/io/spine/elastic*/   # inspect the full artifact set
+```
+
+> As of this writing the `elastic` module applies `kmp-module` but **not**
+> `kmp-publish`, so it registers no publication tasks yet. Wiring publication is the
+> first release task below; until then, `publishToMavenLocal` produces only the
+> default KMP publications (no docs/sources jars, no signing).
+
+## Wiring publication (one-time, in the build)
+
+The repo already ships the Spine convention for KMP publishing — apply it on
+`elastic`:
+
+```kotlin
+// elastic/build.gradle.kts
+plugins {
+    `kmp-module`
+    `kmp-publish`          // adds maven-publish + attaches the docs jars
+}
+
+spinePublishing {
+    destinations = setOf(/* the Spine remote(s), or Central — see below */)
+    customPublishing = true   // required: spinePublishing delegates KMP to kmp-publish
+}
+```
+
+`kmp-publish` attaches the HTML-docs jar to the `kotlinMultiplatform` and `jvm`
+publications; `spinePublishing` fills in the POM (name, description, url, licenses,
+developers, scm) and the destination repositories. Validate with
+`publishToMavenLocal` before configuring any remote destination.
+
+## Maven Central (Central Portal) — the irreversible step
+
+**Prerequisites (all must hold):**
+
+1. **A non-SNAPSHOT version.** Central rejects `-SNAPSHOT`. The project is currently
+   on a `1.0.0-SNAPSHOT-NNN` line; a Central release needs a real `1.0.0`-class
+   version (a separate, deliberate version decision — not this phase's snapshot bump).
+2. **A claimed/verified namespace** for `io.spine` on the Central Portal
+   (`central.sonatype.com` — the legacy OSSRH / `oss.sonatype.org` path reached
+   end-of-life on 2025-06-30; new deployments use the Portal).
+3. **A Portal token** (a generated token, *not* the login password):
+   `ORG_GRADLE_PROJECT_mavenCentralUsername` / `...Password`.
+4. **A PGP signing key**, published to a public keyserver, provided in memory:
+   `ORG_GRADLE_PROJECT_signingInMemoryKey` (+ `...KeyPassword`, + `...KeyId` for a
+   subkey). Every artifact must carry a `.asc` signature.
+5. **A complete POM:** name, description, url, licenses, developers, scm — filled by
+   `spinePublishing`.
+
+**Release:**
+
+```bash
+# Build + sign all publications and stage them to the Portal. Still requires a
+# manual "release" click in the Portal UI (or use the auto-release variant, which
+# is one-way). Some plugin versions need --no-configuration-cache.
+./gradlew publishAllPublicationsToMavenCentralRepository
+```
+
+Then verify the full artifact set (root `.module`, every per-target jar,
+`-sources`/`-javadoc`, `.pom`, `.asc`, checksums) appears before releasing.
+
+## Boundary
+
+| Step | Class |
+|------|-------|
+| `publishToMavenLocal`, footprint/JMH runs, POM generation | **safe / local / reversible** |
+| Wiring `kmp-publish` + `spinePublishing` in the build | safe (a build change; validate locally) |
+| Signing locally (needs the private key) | local, but **touches a secret** |
+| Claiming the namespace, generating a Portal token | one-time, needs Portal login |
+| `publish...ToMavenCentral...` | **needs secret credentials; released versions are permanent and immutable** |
+
+The last row is the human-gated action. Everything above it is reproducible without
+secrets and is what this phase delivers and validates.

From 2b9849b366c163b82bd4f221a85df97034862c13 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 21:24:41 +0100
Subject: [PATCH 03/13] Update dependency reports

Regenerated for the version bump and the Phase 6 benchmark-only competitor
dependencies (fastutil, HPPC, Eclipse Collections, Agrona, JOL) on the
`benchmarks-jvm` `jmh` source set.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/dependencies/dependencies.md | 42 +++++++++++++++++++++++++------
 docs/dependencies/pom.xml         | 27 +++++++++++++++++++-
 2 files changed, 60 insertions(+), 9 deletions(-)

diff --git a/docs/dependencies/dependencies.md b/docs/dependencies/dependencies.md
index cbbfe39..2b837cc 100644
--- a/docs/dependencies/dependencies.md
+++ b/docs/dependencies/dependencies.md
@@ -1,6 +1,6 @@
 
 
-# Dependencies of `io.spine:benchmarks:1.0.0-SNAPSHOT-010`
+# Dependencies of `io.spine:benchmarks:1.0.0-SNAPSHOT-011`
 
 ## Runtime
 ## Compile, tests, and tooling
@@ -298,14 +298,14 @@
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using 
+This report was generated on **Sat Jul 04 01:56:14 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:benchmarks-jvm:1.0.0-SNAPSHOT-010`
+# Dependencies of `io.spine:benchmarks-jvm:1.0.0-SNAPSHOT-011`
 
 ## Runtime
 1.  **Group** : org.jetbrains. **Name** : annotations. **Version** : 13.0.
@@ -317,6 +317,10 @@ This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using
      * **License:** [Apache-2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
 
 ## Compile, tests, and tooling
+1.  **Group** : com.carrotsearch. **Name** : hppc. **Version** : 0.10.0.
+     * **Project URL:** [https://github.com/carrotsearch/hppc](https://github.com/carrotsearch/hppc)
+     * **License:** [Apache 2](https://www.apache.org/licenses/LICENSE-2.0.txt)
+
 1.  **Group** : com.fasterxml.jackson. **Name** : jackson-bom. **Version** : 2.15.3.
      * **Project URL:** [https://github.com/FasterXML/jackson-bom](https://github.com/FasterXML/jackson-bom)
      * **License:** [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
@@ -354,10 +358,18 @@ This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using
 1.  **Group** : io.github.java-diff-utils. **Name** : java-diff-utils. **Version** : 4.12.
      * **License:** [The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
 
+1.  **Group** : it.unimi.dsi. **Name** : fastutil. **Version** : 8.5.18.
+     * **Project URL:** [http://fastutil.di.unimi.it/](http://fastutil.di.unimi.it/)
+     * **License:** [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html)
+
 1.  **Group** : net.sf.jopt-simple. **Name** : jopt-simple. **Version** : 5.0.4.
      * **Project URL:** [http://jopt-simple.github.io/jopt-simple](http://jopt-simple.github.io/jopt-simple)
      * **License:** [The MIT License](http://www.opensource.org/licenses/mit-license.php)
 
+1.  **Group** : org.agrona. **Name** : agrona. **Version** : 2.5.0.
+     * **Project URL:** [https://github.com/aeron-io/agrona](https://github.com/aeron-io/agrona)
+     * **License:** [The Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt)
+
 1.  **Group** : org.apache.commons. **Name** : commons-math3. **Version** : 3.2.
      * **Project URL:** [http://commons.apache.org/proper/commons-math/](http://commons.apache.org/proper/commons-math/)
      * **License:** [The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
@@ -367,6 +379,16 @@ This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using
      * **License:** [The Apache Software License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
      * **License:** [The BSD License](http://www.opensource.org/licenses/bsd-license.php)
 
+1.  **Group** : org.eclipse.collections. **Name** : eclipse-collections. **Version** : 13.0.0.
+     * **Project URL:** [https://github.com/eclipse/eclipse-collections/eclipse-collections](https://github.com/eclipse/eclipse-collections/eclipse-collections)
+     * **License:** [Eclipse Distribution License - v 1.0](https://www.eclipse.org/licenses/edl-v10.html)
+     * **License:** [Eclipse Public License - v 1.0](https://www.eclipse.org/legal/epl-v10.html)
+
+1.  **Group** : org.eclipse.collections. **Name** : eclipse-collections-api. **Version** : 13.0.0.
+     * **Project URL:** [https://github.com/eclipse/eclipse-collections/eclipse-collections-api](https://github.com/eclipse/eclipse-collections/eclipse-collections-api)
+     * **License:** [Eclipse Distribution License - v 1.0](https://www.eclipse.org/licenses/edl-v10.html)
+     * **License:** [Eclipse Public License - v 1.0](https://www.eclipse.org/legal/epl-v10.html)
+
 1.  **Group** : org.freemarker. **Name** : freemarker. **Version** : 2.3.32.
      * **Project URL:** [https://freemarker.apache.org/](https://freemarker.apache.org/)
      * **License:** [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)
@@ -551,6 +573,10 @@ This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using
 1.  **Group** : org.openjdk.jmh. **Name** : jmh-generator-reflection. **Version** : 1.36.
      * **License:** [GNU General Public License (GPL), version 2, with the Classpath exception](http://openjdk.java.net/legal/gplv2+ce.html)
 
+1.  **Group** : org.openjdk.jol. **Name** : jol-core. **Version** : 0.17.
+     * **Project URL:** [http://maven.apache.org](http://maven.apache.org)
+     * **License:** [GNU General Public License (GPL), version 2, with the Classpath exception](http://openjdk.java.net/legal/gplv2+ce.html)
+
 1.  **Group** : org.ow2.asm. **Name** : asm. **Version** : 9.0.
      * **Project URL:** [http://asm.ow2.io/](http://asm.ow2.io/)
      * **License:** [BSD-3-Clause](https://asm.ow2.io/license.html)
@@ -559,14 +585,14 @@ This report was generated on **Fri Jul 03 04:23:38 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jul 03 04:17:56 WEST 2026** using 
+This report was generated on **Sat Jul 04 01:55:23 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:codegen:1.0.0-SNAPSHOT-010`
+# Dependencies of `io.spine:codegen:1.0.0-SNAPSHOT-011`
 
 ## Runtime
 1.  **Group** : org.jetbrains. **Name** : annotations. **Version** : 13.0.
@@ -1058,14 +1084,14 @@ This report was generated on **Fri Jul 03 04:17:56 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jul 03 04:17:56 WEST 2026** using 
+This report was generated on **Sat Jul 04 01:55:23 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
 
 
 
 
-# Dependencies of `io.spine:elastic:1.0.0-SNAPSHOT-010`
+# Dependencies of `io.spine:elastic:1.0.0-SNAPSHOT-011`
 
 ## Runtime
 ## Compile, tests, and tooling
@@ -2303,6 +2329,6 @@ This report was generated on **Fri Jul 03 04:17:56 WEST 2026** using
 
 The dependencies distributed under several licenses, are used according their commercial-use-friendly license.
 
-This report was generated on **Fri Jul 03 04:17:56 WEST 2026** using 
+This report was generated on **Sat Jul 04 01:55:23 WEST 2026** using 
 [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under 
 [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE).
\ No newline at end of file
diff --git a/docs/dependencies/pom.xml b/docs/dependencies/pom.xml
index 9044c2a..3d43bcc 100644
--- a/docs/dependencies/pom.xml
+++ b/docs/dependencies/pom.xml
@@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject.
  -->
 <groupId>io.spine</groupId>
 <artifactId>elastic</artifactId>
-<version>1.0.0-SNAPSHOT-010</version>
+<version>1.0.0-SNAPSHOT-011</version>
 
 <inceptionYear>2015</inceptionYear>
 
@@ -51,6 +51,11 @@ all modules and does not describe the project structure per-subproject.
     <artifactId>junit-jupiter-engine</artifactId>
     <scope>test</scope>
   </dependency>
+  <dependency>
+    <groupId>com.carrotsearch</groupId>
+    <artifactId>hppc</artifactId>
+    <version>0.10.0</version>
+  </dependency>
   <dependency>
     <groupId>com.puppycrawl.tools</groupId>
     <artifactId>checkstyle</artifactId>
@@ -81,6 +86,26 @@ all modules and does not describe the project structure per-subproject.
     <artifactId>base-testlib</artifactId>
     <version>2.0.0-SNAPSHOT.213</version>
   </dependency>
+  <dependency>
+    <groupId>it.unimi.dsi</groupId>
+    <artifactId>fastutil</artifactId>
+    <version>8.5.18</version>
+  </dependency>
+  <dependency>
+    <groupId>org.agrona</groupId>
+    <artifactId>agrona</artifactId>
+    <version>2.5.0</version>
+  </dependency>
+  <dependency>
+    <groupId>org.eclipse.collections</groupId>
+    <artifactId>eclipse-collections</artifactId>
+    <version>13.0.0</version>
+  </dependency>
+  <dependency>
+    <groupId>org.eclipse.collections</groupId>
+    <artifactId>eclipse-collections-api</artifactId>
+    <version>13.0.0</version>
+  </dependency>
   <dependency>
     <groupId>org.jacoco</groupId>
     <artifactId>org.jacoco.agent</artifactId>

From 9865f8fe022dfbb39c711cc6a174ecb5f1797843 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 21:39:09 +0100
Subject: [PATCH 04/13] Address PR review: pin threads, gate
 LoadFactorBenchmark, drop Agrona from the LF sweep
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `@Threads(1)` on all three benchmarks — `churn` mutates the shared
  `Scope.Benchmark` map, so a CLI `-t` override would be a data race with invalid
  results.
- Correctness gate in `LoadFactorBenchmark`'s `@Setup` (hit-sum == key-sum),
  matching the matrix benchmarks, so a miswired adapter fails fast.
- Drop Agrona from the load-factor sweep: its load factor is capped at 0.9 (the
  constructor rejects 0.99), so it cannot reach the >=0.95 points this benchmark
  targets — a pre-merge smoke run caught the exception. Its lookup at its own load
  stays in the main matrix.
- `capture-env.sh`: on Linux, fall back to `/proc/cpuinfo` when `lscpu` has no
  "Model name:" line (an empty `cpu_model` otherwise slipped through), and always
  emit `os_product`.
- `FootprintReport`: reword "equal occupancy" to "same entry count, each map
  pre-sized in its own units" (loads differ by each map's policy; capacity slack is
  included); regenerate the committed `footprint.md`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .agents/tasks/phase-6-validation-release.md   | 15 ++---
 benchmarks-jvm/capture-env.sh                 | 13 ++++-
 .../results/m4max-indicative/footprint.md     |  2 +-
 .../elastic/benchmark/jmh/FootprintReport.kt  | 18 ++++--
 .../benchmark/jmh/IntIntMatrixBenchmark.kt    |  5 ++
 .../benchmark/jmh/LoadFactorBenchmark.kt      | 55 +++++++++++--------
 .../benchmark/jmh/LongLongMatrixBenchmark.kt  |  5 ++
 docs/benchmarking.md                          | 17 +++---
 8 files changed, 84 insertions(+), 46 deletions(-)

diff --git a/.agents/tasks/phase-6-validation-release.md b/.agents/tasks/phase-6-validation-release.md
index a1538e1..8cc3542 100644
--- a/.agents/tasks/phase-6-validation-release.md
+++ b/.agents/tasks/phase-6-validation-release.md
@@ -35,13 +35,14 @@ toolchain: **fastutil 8.5.18**, **HPPC 0.10.0**, **Eclipse Collections 13.0.0**
   the key-sum) refuses to benchmark a miswired adapter. **No `iterate` op**: our
   primitive-value maps expose no non-boxing traversal (DP-10 lean surface), so a fair
   head-to-head cannot include it — the gap is a tracked follow-up.
-- `LoadFactorBenchmark` — lookup cost vs load factor `{0.50…0.99}` for the three
-  competitors with a **settable** load factor (fastutil, HPPC, Agrona). Ours (fixed
-  `7/8`) and `HashMap` (`0.75`) cannot be *held* at an arbitrary load and are fixed
-  reference points; the ≈0.99 regime belongs to the paper structures, gated by their
-  own probe-count specs. Capacity is pinned at `2^20` and the fill count chosen to hit
-  the target load; every invocation does the same `2^20` lookups, so scores are
-  load-comparable.
+- `LoadFactorBenchmark` — lookup cost vs load factor `{0.50…0.99}` for the two
+  competitors that can be *held* at a high load (fastutil, HPPC; their LF tunes to
+  0.99). Ours (fixed `7/8`) and `HashMap` (`0.75`) cannot be held at an arbitrary load
+  and are fixed reference points; Agrona is excluded (its LF is capped at 0.9, so it
+  cannot reach the ≥0.95 points — a limitation the pre-merge smoke caught). The ≈0.99
+  regime belongs to the paper structures, gated by their own probe-count specs.
+  Capacity is pinned at `2^20` and the fill count chosen to hit the target load; every
+  invocation does the same `2^20` lookups, so scores are load-comparable.
 - `MatrixKeys.kt` — the `DENSE` and `CLUSTERED` key sets (the latter mandated by the
   fairness gate) and the fixed-seed shuffle. The `Int` `CLUSTERED` stride is milder
   than the `Long` one because a hard-collision key set is not constructible in-range
diff --git a/benchmarks-jvm/capture-env.sh b/benchmarks-jvm/capture-env.sh
index f102dc5..8d374d2 100755
--- a/benchmarks-jvm/capture-env.sh
+++ b/benchmarks-jvm/capture-env.sh
@@ -44,8 +44,17 @@ case "$os" in
         emit "freq_pinned" "no (Apple Silicon: turbo/P-E scheduling not controllable)"
         ;;
     Linux)
-        [ -r /etc/os-release ] && emit "os_product" "$(. /etc/os-release; echo "$PRETTY_NAME")"
-        emit "cpu_model" "$(lscpu 2>/dev/null | sed -n 's/^Model name:[[:space:]]*//p' | head -1 || grep -m1 'model name' /proc/cpuinfo | cut -d: -f2- | sed 's/^ //')"
+        if [ -r /etc/os-release ]; then
+            emit "os_product" "$(. /etc/os-release; echo "$PRETTY_NAME")"
+        else
+            emit "os_product" "Linux (no /etc/os-release)"
+        fi
+        # `lscpu`/`sed` exit 0 even with no "Model name:" line, so an empty result
+        # would silently pass a naive `||`; check emptiness explicitly and fall back.
+        cpu="$(lscpu 2>/dev/null | sed -n 's/^Model name:[[:space:]]*//p' | head -1)"
+        [ -z "$cpu" ] && cpu="$(grep -m1 'model name' /proc/cpuinfo 2>/dev/null | cut -d: -f2- | sed 's/^ //')"
+        [ -z "$cpu" ] && cpu="unknown"
+        emit "cpu_model" "$cpu"
         emit "cpu_logical_cores" "$(nproc 2>/dev/null || echo '?')"
         emit "ram_bytes" "$(awk '/MemTotal/ {print $2*1024; exit}' /proc/meminfo 2>/dev/null || echo '?')"
         gov="$(cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor 2>/dev/null || echo unknown)"
diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.md b/benchmarks-jvm/results/m4max-indicative/footprint.md
index 726bd32..016e502 100644
--- a/benchmarks-jvm/results/m4max-indicative/footprint.md
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.md
@@ -1,6 +1,6 @@
 # Retained-heap footprint (JOL), n = 229376 entries
 
-Bytes per entry, each map pre-sized in its own units at equal occupancy.
+Bytes per entry — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
 Ratio is versus the boxed `HashMap` baseline (higher = more compact).
 
 | impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
index 11b2bd5..a6a5bf5 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
@@ -42,11 +42,13 @@ import org.openjdk.jol.info.GraphLayout
  * reported as bytes per entry and as a ratio against the boxed `HashMap` baseline.
  *
  * Each map is built raw (no adapter wrapper, so JOL measures only the map's own
- * object graph), pre-sized in its own units for the same entry count, and filled
- * with dense keys. The count `n` is the `7/8` load of a `2^18`-slot table, so our
- * SwissTable-family maps sit exactly at capacity with no power-of-two slack — a
- * realistic, equal-occupancy comparison point (the same `n` the library's own
- * `MemoryFootprintSpec` guard uses).
+ * object graph), pre-sized **in its own units** for the same entry count `n`, and
+ * filled with dense keys. `n` is the `7/8` load of a `2^18`-slot table, so our
+ * SwissTable-family maps sit exactly at capacity with no power-of-two slack; the
+ * other maps hold the same `n` entries but land at whatever load their own resize
+ * policy dictates, and that capacity slack is part of the measured footprint. This
+ * is the same-entry-count, own-units comparison — not a matched load factor — and
+ * uses the same `n` as the library's own `MemoryFootprintSpec` guard.
  *
  * Run with `./gradlew :benchmarks-jvm:footprintReport`; the Markdown + TSV land in
  * `benchmarks-jvm/build/reports/footprint/`.
@@ -117,7 +119,11 @@ private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footp
     return buildString {
         appendLine("# Retained-heap footprint (JOL), n = $n entries")
         appendLine()
-        appendLine("Bytes per entry, each map pre-sized in its own units at equal occupancy.")
+        appendLine(
+            "Bytes per entry — each map pre-sized in its own units for the same entry " +
+                "count `n` (loads differ by each map's resize policy; capacity slack is " +
+                "included in the footprint).",
+        )
         appendLine("Ratio is versus the boxed `HashMap` baseline (higher = more compact).")
         appendLine()
         appendLine("| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |")
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
index af63aa0..0b2f19d 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
@@ -37,6 +37,7 @@ import org.openjdk.jmh.annotations.Param
 import org.openjdk.jmh.annotations.Scope
 import org.openjdk.jmh.annotations.Setup
 import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Threads
 import org.openjdk.jmh.annotations.Warmup
 import org.openjdk.jmh.infra.Blackhole
 
@@ -56,6 +57,10 @@ import org.openjdk.jmh.infra.Blackhole
 @Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Fork(3)
+// `churn` mutates the shared `Scope.Benchmark` map, so these benchmarks are
+// single-threaded by design; pin the thread count so a CLI `-t` override cannot
+// turn them into a data race with invalid results.
+@Threads(1)
 open class IntIntMatrixBenchmark {
 
     @Param(OURS, HASH_MAP, FASTUTIL, HPPC, ECLIPSE, AGRONA)
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
index e05a096..686952c 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
@@ -29,7 +29,6 @@ package io.spine.elastic.benchmark.jmh
 import it.unimi.dsi.fastutil.longs.Long2LongOpenHashMap
 import java.util.concurrent.TimeUnit
 import kotlin.math.roundToInt
-import org.agrona.collections.Long2LongHashMap
 import org.openjdk.jmh.annotations.Benchmark
 import org.openjdk.jmh.annotations.BenchmarkMode
 import org.openjdk.jmh.annotations.Fork
@@ -40,23 +39,27 @@ import org.openjdk.jmh.annotations.Param
 import org.openjdk.jmh.annotations.Scope
 import org.openjdk.jmh.annotations.Setup
 import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Threads
 import org.openjdk.jmh.annotations.Warmup
 import org.openjdk.jmh.infra.Blackhole
 
 /**
- * Lookup cost as a function of **load factor**, for the three competitors that
- * expose a settable load factor (fastutil, HPPC, Agrona). This is the Phase 6
- * answer to "how does probe cost grow as the table fills toward 0.99".
+ * Lookup cost as a function of **load factor**, for the two competitors that can be
+ * *held* at a high load — fastutil and HPPC, whose load factor tunes up to 0.99.
+ * This is the Phase 6 answer to "how does probe cost grow as the table fills toward
+ * 0.99".
  *
- * ### Why only these three
+ * ### Why only these two
  *
  * Our SwissTable-family maps run at a **fixed** maximum load (`7/8 = 0.875`, then
  * they grow), and `HashMap` resizes at `0.75` — neither can be *held* at an
  * arbitrary load, so they are fixed reference points (their 1M lookup numbers come
- * from [LongLongMatrixBenchmark]), not sweepable here. The paper structures
- * (`FunnelLongMap`, `ElasticLongMap`) are the ones designed for ≈0.99; their
- * high-load behavior is covered by their own probe-bound specs, not this
- * wall-clock sweep.
+ * from [LongLongMatrixBenchmark]), not sweepable here. **Agrona is excluded too: its
+ * load factor is capped at 0.9** (its constructor rejects a higher value), so it
+ * cannot reach the ≥0.95 points this sweep targets — its lookup at its own load is
+ * covered by the main matrix. The paper structures (`FunnelLongMap`,
+ * `ElasticLongMap`) are the ones designed for ≈0.99; their high-load behavior is
+ * covered by their own probe-bound specs, not this wall-clock sweep.
  *
  * ### Hitting a target load on a power-of-two table
  *
@@ -75,9 +78,12 @@ import org.openjdk.jmh.infra.Blackhole
 @Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Fork(3)
+// Single-threaded by design (shared setup state, no synchronization); pin the
+// thread count so a CLI `-t` override cannot invalidate the sweep.
+@Threads(1)
 open class LoadFactorBenchmark {
 
-    @Param(FASTUTIL, HPPC, AGRONA)
+    @Param(FASTUTIL, HPPC)
     lateinit var impl: String
 
     @Param("0.50", "0.75", "0.90", "0.95", "0.99")
@@ -97,6 +103,16 @@ open class LoadFactorBenchmark {
             map.put(key, key)
         }
         check(map.size() == fill) { "Expected $fill entries in `$impl`, got ${map.size()}." }
+        // Correctness gate (mirrors the matrix benchmarks): each key's value is the key,
+        // so the sum of all hit lookups must equal the sum of keys — fail fast on any
+        // mis-constructed or miswired adapter rather than measuring wrong behavior.
+        var hitSum = 0L
+        for (key in keys) {
+            hitSum += map.get(key)
+        }
+        check(hitSum == keys.sum()) {
+            "Adapter `$impl` returned wrong values: hit sum $hitSum != ${keys.sum()}."
+        }
         populated = map
     }
 
@@ -126,9 +142,10 @@ open class LoadFactorBenchmark {
 }
 
 /**
- * A [LongLongCell] for one of the load-factor-tunable competitors, constructed to
- * hold [fill] entries in a `2^20`-slot table without resizing (capacity pinned via
- * the maximum load factor). Only the three tunable maps are supported.
+ * A [LongLongCell] for one of the high-load-capable competitors, constructed to hold
+ * [fill] entries in a `2^20`-slot table without resizing (capacity pinned via the
+ * maximum load factor). Only fastutil and HPPC are supported — Agrona's load factor
+ * is capped at 0.9, so it cannot be held at this benchmark's high-load points.
  */
 private fun createAtMaxLoad(impl: String, fill: Int): LongLongCell = when (impl) {
     FASTUTIL -> object : LongLongCell {
@@ -145,18 +162,10 @@ private fun createAtMaxLoad(impl: String, fill: Int): LongLongCell = when (impl)
         override fun remove(key: Long) { map.remove(key) }
         override fun size(): Int = map.size()
     }
-    AGRONA -> object : LongLongCell {
-        private val map = Long2LongHashMap(1 shl 20, MAX_LOAD_F, Long.MIN_VALUE)
-        override fun put(key: Long, value: Long) { map.put(key, value) }
-        override fun get(key: Long): Long = map.get(key)
-        override fun remove(key: Long) { map.remove(key) }
-        // Agrona's maps implement `java.util.Map`, so `size` is a Kotlin property.
-        override fun size(): Int = map.size
-    }
-    else -> throw IllegalArgumentException("Load factor is not tunable for `$impl`.")
+    else -> throw IllegalArgumentException("Load factor is not sweepable for `$impl`.")
 }
 
-/** The maximum load factor as a `float` for fastutil/Agrona constructors. */
+/** The maximum load factor as a `float` for the fastutil constructor. */
 private const val MAX_LOAD_F = 0.99f
 
 /** The maximum load factor as a `double` for the HPPC constructor. */
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
index 775cc29..de6da9d 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
@@ -37,6 +37,7 @@ import org.openjdk.jmh.annotations.Param
 import org.openjdk.jmh.annotations.Scope
 import org.openjdk.jmh.annotations.Setup
 import org.openjdk.jmh.annotations.State
+import org.openjdk.jmh.annotations.Threads
 import org.openjdk.jmh.annotations.Warmup
 import org.openjdk.jmh.infra.Blackhole
 
@@ -64,6 +65,10 @@ import org.openjdk.jmh.infra.Blackhole
 @Warmup(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Measurement(iterations = 5, time = 1, timeUnit = TimeUnit.SECONDS)
 @Fork(3)
+// `churn` mutates the shared `Scope.Benchmark` map, so these benchmarks are
+// single-threaded by design; pin the thread count so a CLI `-t` override cannot
+// turn them into a data race with invalid results.
+@Threads(1)
 open class LongLongMatrixBenchmark {
 
     @Param(OURS, HASH_MAP, FASTUTIL, HPPC, ECLIPSE, AGRONA)
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index aca35bd..1a40288 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -54,13 +54,16 @@ is tracked as a follow-up.
 
 ### Load-factor sweep (`LoadFactorBenchmark`)
 
-Lookup cost as a function of load factor `{0.50, 0.75, 0.90, 0.95, 0.99}`, for the
-three competitors that expose a **settable** load factor (fastutil, HPPC, Agrona).
-Our SwissTable-family maps run at a fixed maximum load (`7/8 = 0.875`, then they
-grow) and `HashMap` resizes at `0.75`, so neither can be *held* at an arbitrary load
-— they are fixed reference points, not sweepable. The high-load (≈0.99) regime is the
-home of the paper structures (`FunnelLongMap`, `ElasticLongMap`), whose bounds are
-asserted by their own probe-count specs rather than this wall-clock sweep.
+Lookup cost as a function of load factor `{0.50, 0.75, 0.90, 0.95, 0.99}`, for the two
+competitors that can be *held* at a high load — fastutil and HPPC, whose load factor
+tunes up to 0.99. Our SwissTable-family maps run at a fixed maximum load
+(`7/8 = 0.875`, then they grow) and `HashMap` resizes at `0.75`, so neither can be
+held at an arbitrary load — they are fixed reference points, not sweepable. **Agrona
+is excluded too:** its load factor is capped at 0.9 (its constructor rejects a higher
+value), so it cannot reach the ≥0.95 points — its lookup at its own load is in the
+main matrix instead. The high-load (≈0.99) regime is the home of the paper structures
+(`FunnelLongMap`, `ElasticLongMap`), whose bounds are asserted by their own
+probe-count specs rather than this wall-clock sweep.
 
 To land on a chosen load on a power-of-two table, capacity is pinned at `2^20` and the
 entry count is `round(loadFactor · 2^20)`; every invocation then does the same `2^20`

From 481f7f732142ab3e1f4d12ecaa696ce5b04c06cf Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 21:54:57 +0100
Subject: [PATCH 05/13] Compute footprint ratios from exact retained totals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`FootprintReport` floored bytes-per-entry with integer division before computing
the compactness ratios, so the report — and the docs citing it as exact JOL
results — overstated the memory win: it printed `89 / 19 = 4.68x` where the true
`LongLongMap`-vs-`HashMap` retained-total ratio is 4.59x. Keep bytes-per-entry as
an exact `Double` and compute every ratio from `totalBytes`.

Corrected numbers propagated to README, benchmarking.md, performance-goals.md,
project.md, the phase-6 task doc, and the committed footprint bundle:
`LongLongMap` 19.4 B/entry (4.59x vs `HashMap` 89.1); `IntIntMap` 10.3 (7.11x vs
73.1); competitors 36.6 / 18.3 (2.44x / 4.00x vs `HashMap`). The ours-vs-competitor
factor (~1.9x / ~1.8x) is unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .agents/tasks/phase-6-validation-release.md   | 10 ++---
 README.md                                     |  9 ++--
 .../results/m4max-indicative/footprint.md     | 16 +++----
 .../results/m4max-indicative/footprint.tsv    | 24 +++++------
 .../elastic/benchmark/jmh/FootprintReport.kt  | 42 ++++++++++++-------
 docs/benchmarking.md                          | 27 ++++++------
 docs/performance-goals.md                     |  8 ++--
 docs/project.md                               |  2 +-
 8 files changed, 76 insertions(+), 62 deletions(-)

diff --git a/.agents/tasks/phase-6-validation-release.md b/.agents/tasks/phase-6-validation-release.md
index 8cc3542..9c7cb18 100644
--- a/.agents/tasks/phase-6-validation-release.md
+++ b/.agents/tasks/phase-6-validation-release.md
@@ -69,11 +69,11 @@ reproduces the committed Phase 1 measurement exactly.
 ## Results (measured)
 
 - **Memory — decisive, and the strongest portable result.** Retained B/entry at
-  `n = 229_376`: `LongLongMap` **19** (**4.68×** smaller than `HashMap` 89, and
-  **~1.9×** smaller than the four competitors, all 36); `IntIntMap` **10** (**7.30×**
-  smaller than `HashMap` 73, **~1.8×** smaller than the competitors, all 18). Ours is
-  more compact than *even the specialist primitive libraries*, from packing
-  key+value+1 control byte at `7/8` load.
+  `n = 229_376` (ratios from exact retained totals): `LongLongMap` **19.4** (**4.59×**
+  smaller than `HashMap` 89.1, and **~1.9×** smaller than the four competitors, all
+  36.6); `IntIntMap` **10.3** (**7.11×** smaller than `HashMap` 73.1, **~1.8×** smaller
+  than the competitors, all 18.3). Ours is more compact than *even the specialist
+  primitive libraries*, from packing key+value+1 control byte at `7/8` load.
 - **Time — distribution robustness is the headline** (qualitative; absolute ms are
   hardware-specific and deferred to a pinned run). `1M` `lookupHit`, M4 Max, indicative:
   `OURS` is flat across `DENSE` (9.9 ms) → `CLUSTERED` (10.2 ms), while `FASTUTIL`
diff --git a/README.md b/README.md
index bcafcdd..4e3391a 100644
--- a/README.md
+++ b/README.md
@@ -69,10 +69,11 @@ detail.
   primitive-map libraries (fastutil, HPPC, Eclipse Collections, Agrona), the
   exact-footprint report, and the reproducibility harness are in place; see
   [`docs/benchmarking.md`](docs/benchmarking.md). Two measured headlines:
-  - **Memory:** `LongLongMap` retains **19 B/entry** — **4.68×** less than boxed
-    `HashMap<Long, Long>` and **~1.9× less than every primitive competitor** (36
-    B/entry each); `IntIntMap` is **10 B/entry** (**7.30×** vs `HashMap`, **~1.8×**
-    vs competitors at 18 B/entry).
+  - **Memory:** `LongLongMap` retains **19.4 B/entry** — **4.59×** less than boxed
+    `HashMap<Long, Long>` (89.1) and **~1.9× less than every primitive competitor**
+    (36.6 B/entry each); `IntIntMap` is **10.3 B/entry** (**7.11×** vs `HashMap`,
+    **~1.8×** vs competitors at 18.3 B/entry). Ratios are from exact JOL retained
+    totals.
   - **Distribution robustness:** on out-of-cache random lookup our `fmix64`
     finalizer keeps `LongLongMap` flat between dense and adversarial (clustered)
     keys, where fastutil degrades ~5× and Eclipse ~6× — so ours is the *fastest*
diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.md b/benchmarks-jvm/results/m4max-indicative/footprint.md
index 016e502..2b07434 100644
--- a/benchmarks-jvm/results/m4max-indicative/footprint.md
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.md
@@ -1,13 +1,13 @@
 # Retained-heap footprint (JOL), n = 229376 entries
 
-Bytes per entry — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
-Ratio is versus the boxed `HashMap` baseline (higher = more compact).
+Bytes per entry (exact) — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
+Ratio is versus the boxed `HashMap` baseline, computed from the retained byte totals (higher = more compact).
 
 | impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
 |------|-------------------|-----------|-----------------|-----------|
-| OURS     |    19 | 4.68x |    10 | 7.30x |
-| HASH_MAP |    89 | 1.00x |    73 | 1.00x |
-| FASTUTIL |    36 | 2.47x |    18 | 4.06x |
-| HPPC     |    36 | 2.47x |    18 | 4.06x |
-| ECLIPSE  |    36 | 2.47x |    18 | 4.06x |
-| AGRONA   |    36 | 2.47x |    18 | 4.06x |
+| OURS     |   19.4 | 4.59x |   10.3 | 7.11x |
+| HASH_MAP |   89.1 | 1.00x |   73.1 | 1.00x |
+| FASTUTIL |   36.6 | 2.44x |   18.3 | 4.00x |
+| HPPC     |   36.6 | 2.44x |   18.3 | 4.00x |
+| ECLIPSE  |   36.6 | 2.44x |   18.3 | 4.00x |
+| AGRONA   |   36.6 | 2.44x |   18.3 | 4.00x |
diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.tsv b/benchmarks-jvm/results/m4max-indicative/footprint.tsv
index 7abc84c..676c3cb 100644
--- a/benchmarks-jvm/results/m4max-indicative/footprint.tsv
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.tsv
@@ -1,13 +1,13 @@
 impl	cell	totalBytes	bytesPerEntry
-OURS	LongLong	4456592	19
-HASH_MAP	LongLong	20444224	89
-FASTUTIL	LongLong	8388728	36
-HPPC	LongLong	8388704	36
-ECLIPSE	LongLong	8388688	36
-AGRONA	LongLong	8388680	36
-OURS	IntInt	2359432	10
-HASH_MAP	IntInt	16775232	73
-FASTUTIL	IntInt	4194416	18
-HPPC	IntInt	4194400	18
-ECLIPSE	IntInt	4194376	18
-AGRONA	IntInt	4194368	18
+OURS	LongLong	4456592	19.43
+HASH_MAP	LongLong	20444224	89.13
+FASTUTIL	LongLong	8388728	36.57
+HPPC	LongLong	8388704	36.57
+ECLIPSE	LongLong	8388688	36.57
+AGRONA	LongLong	8388680	36.57
+OURS	IntInt	2359432	10.29
+HASH_MAP	IntInt	16775232	73.13
+FASTUTIL	IntInt	4194416	18.29
+HPPC	IntInt	4194400	18.29
+ECLIPSE	IntInt	4194376	18.29
+AGRONA	IntInt	4194368	18.29
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
index a6a5bf5..81dd112 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
@@ -69,13 +69,13 @@ fun main(args: Array<String>) {
     println("Wrote ${File(outDir, "footprint.md")} and ${File(outDir, "footprint.tsv")}")
 }
 
-/** One measured cell: retained bytes and bytes-per-entry for an implementation. */
-private data class Footprint(val impl: String, val totalBytes: Long, val bytesPerEntry: Long)
+/** One measured cell: the exact retained total and the (unrounded) bytes per entry. */
+private data class Footprint(val impl: String, val totalBytes: Long, val bytesPerEntry: Double)
 
 private inline fun measure(impl: String, entries: Int, build: () -> Any): Footprint {
     val map = build()
     val total = GraphLayout.parseInstance(map).totalSize()
-    return Footprint(impl, total, total / entries)
+    return Footprint(impl, total, total.toDouble() / entries)
 }
 
 private fun buildLongLong(impl: String, n: Int): Any = when (impl) {
@@ -106,25 +106,30 @@ private fun buildIntInt(impl: String, n: Int): Any = when (impl) {
 }
 
 private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footprint>): String {
-    val baselineLong = longLong.first { it.impl == HASH_MAP }.bytesPerEntry
-    val baselineInt = intInt.first { it.impl == HASH_MAP }.bytesPerEntry
+    val baselineLong = longLong.first { it.impl == HASH_MAP }.totalBytes
+    val baselineInt = intInt.first { it.impl == HASH_MAP }.totalBytes
     val rows = ALL_IMPLS.joinToString("\n") { impl ->
         val ll = longLong.first { it.impl == impl }
         val ii = intInt.first { it.impl == impl }
-        "| %-8s | %5d | %s | %5d | %s |".format(
-            impl, ll.bytesPerEntry, ratio(baselineLong, ll.bytesPerEntry),
-            ii.bytesPerEntry, ratio(baselineInt, ii.bytesPerEntry),
+        // Ratios are computed from the exact retained totals, not the displayed
+        // (rounded) bytes-per-entry, so they never overstate the win.
+        "| %-8s | %6.1f | %s | %6.1f | %s |".format(
+            impl, ll.bytesPerEntry, ratio(baselineLong, ll.totalBytes),
+            ii.bytesPerEntry, ratio(baselineInt, ii.totalBytes),
         )
     }
     return buildString {
         appendLine("# Retained-heap footprint (JOL), n = $n entries")
         appendLine()
         appendLine(
-            "Bytes per entry — each map pre-sized in its own units for the same entry " +
-                "count `n` (loads differ by each map's resize policy; capacity slack is " +
-                "included in the footprint).",
+            "Bytes per entry (exact) — each map pre-sized in its own units for the same " +
+                "entry count `n` (loads differ by each map's resize policy; capacity slack " +
+                "is included in the footprint).",
+        )
+        appendLine(
+            "Ratio is versus the boxed `HashMap` baseline, computed from the retained byte " +
+                "totals (higher = more compact).",
         )
-        appendLine("Ratio is versus the boxed `HashMap` baseline (higher = more compact).")
         appendLine()
         appendLine("| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |")
         appendLine("|------|-------------------|-----------|-----------------|-----------|")
@@ -134,12 +139,17 @@ private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footp
 
 private fun renderTsv(longLong: List<Footprint>, intInt: List<Footprint>): String = buildString {
     appendLine("impl\tcell\ttotalBytes\tbytesPerEntry")
-    longLong.forEach { appendLine("${it.impl}\tLongLong\t${it.totalBytes}\t${it.bytesPerEntry}") }
-    intInt.forEach { appendLine("${it.impl}\tIntInt\t${it.totalBytes}\t${it.bytesPerEntry}") }
+    longLong.forEach {
+        appendLine("${it.impl}\tLongLong\t${it.totalBytes}\t${"%.2f".format(it.bytesPerEntry)}")
+    }
+    intInt.forEach {
+        appendLine("${it.impl}\tIntInt\t${it.totalBytes}\t${"%.2f".format(it.bytesPerEntry)}")
+    }
 }
 
-private fun ratio(baseline: Long, value: Long): String =
-    if (value == 0L) "n/a" else "%.2fx".format(baseline.toDouble() / value)
+/** The compactness ratio from exact retained totals: how many times smaller than the baseline. */
+private fun ratio(baselineTotal: Long, valueTotal: Long): String =
+    if (valueTotal == 0L) "n/a" else "%.2fx".format(baselineTotal.toDouble() / valueTotal)
 
 private const val LOG2_CAPACITY = 18
 private const val LOAD_NUMERATOR = 7
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index 1a40288..4b12828 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -142,23 +142,26 @@ JOL runs in reflection mode (no agent needed); the numbers match the library's o
 
 Retained bytes per entry at `n = 229_376` (the `7/8` load of a `2^18` table), each
 map pre-sized in its own units. Measured with JOL on Apple M4 Max, Corretto 17.
+Bytes/entry are exact; ratios are computed from the retained byte totals (so a floored
+bytes/entry never inflates them).
 
 | impl | Long→Long B/entry | vs `HashMap` | Int→Int B/entry | vs `HashMap` |
 |------|------------------:|-------------:|----------------:|-------------:|
-| **`OURS`** | **19** | **4.68×** | **10** | **7.30×** |
-| `HASH_MAP` | 89 | 1.00× | 73 | 1.00× |
-| `FASTUTIL` | 36 | 2.47× | 18 | 4.06× |
-| `HPPC` | 36 | 2.47× | 18 | 4.06× |
-| `ECLIPSE` | 36 | 2.47× | 18 | 4.06× |
-| `AGRONA` | 36 | 2.47× | 18 | 4.06× |
+| **`OURS`** | **19.4** | **4.59×** | **10.3** | **7.11×** |
+| `HASH_MAP` | 89.1 | 1.00× | 73.1 | 1.00× |
+| `FASTUTIL` | 36.6 | 2.44× | 18.3 | 4.00× |
+| `HPPC` | 36.6 | 2.44× | 18.3 | 4.00× |
+| `ECLIPSE` | 36.6 | 2.44× | 18.3 | 4.00× |
+| `AGRONA` | 36.6 | 2.44× | 18.3 | 4.00× |
 
 The memory win is decisive and, notably, holds **against the specialist primitive
-libraries too**, not only the boxed baseline: `LongLongMap` (19) is ~1.9× more compact
-than the competitors (36) and `IntIntMap` (10) is ~1.8× more compact than theirs (18).
-The competitors are themselves 2.5×/4.1× more compact than boxed `HashMap`, and we go
-further still — because of load factor and layout: our maps pack keys and values plus
-one control byte per entry at `7/8` load, where the competitors carry parallel
-key/value arrays at a lower occupancy. This is the project's strongest, most portable
+libraries too**, not only the boxed baseline: `LongLongMap` (19.4) is ~1.9× more
+compact than the competitors (36.6) and `IntIntMap` (10.3) is ~1.8× more compact than
+theirs (18.3). The competitors are themselves 2.4×/4.0× more compact than boxed
+`HashMap`, and we go further still — because of load factor and layout: our maps pack
+keys and values plus one control byte per entry at `7/8` load, where the competitors
+carry parallel key/value arrays at a lower occupancy. This is the project's strongest,
+most portable
 result.
 
 ## Result: time
diff --git a/docs/performance-goals.md b/docs/performance-goals.md
index abf9285..007ae6b 100644
--- a/docs/performance-goals.md
+++ b/docs/performance-goals.md
@@ -140,10 +140,10 @@ the specialists as a **reference ceiling**, not a gate. Method:
 [`benchmarking.md`](benchmarking.md).
 
 - **Memory — met decisively, against everyone.** Retained bytes/entry at
-  `n = 229_376` (JOL, each map pre-sized in its own units): `LongLongMap` **19**
-  (**4.68×** smaller than `HashMap` 89, and **~1.9×** smaller than the four
-  competitors, all **36**); `IntIntMap` **10** (**7.30×** smaller than `HashMap` 73,
-  **~1.8×** smaller than the competitors, all **18**).
+  `n = 229_376` (JOL, each map pre-sized in its own units; ratios from exact retained
+  totals): `LongLongMap` **19.4** (**4.59×** smaller than `HashMap` 89.1, and **~1.9×**
+  smaller than the four competitors, all **36.6**); `IntIntMap` **10.3** (**7.11×**
+  smaller than `HashMap` 73.1, **~1.8×** smaller than the competitors, all **18.3**).
   Our maps are more compact than the specialist primitive libraries too — they pack
   key + value + one control byte at `7/8` load where the competitors carry parallel
   arrays at a lower occupancy.
diff --git a/docs/project.md b/docs/project.md
index 1f0cd9c..e454e7b 100644
--- a/docs/project.md
+++ b/docs/project.md
@@ -96,7 +96,7 @@ fail-fast on the single-threaded maps, weakly consistent snapshot iteration on
 Phase 6 adds the validation harness — a comparative JMH matrix and JOL footprint
 report versus the standard library and the four specialist primitive-map libraries,
 plus a reproducibility runner — and the release runbook; publication itself is
-human-gated. Measured: our maps are **4.7×/7.3×** more compact than boxed `HashMap`
+human-gated. Measured: our maps are **4.6×/7.1×** more compact than boxed `HashMap`
 (and ~1.9×/1.8× more compact than the specialist primitive libraries), and
 distribution-robust —
 flat from dense to adversarial keys where the competitors degrade ~5–6×. See

From 529bba5118534b3cf321fce9c9ae12ab8fdc0f2a Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sat, 4 Jul 2026 22:03:19 +0100
Subject: [PATCH 06/13] Clarify footprint precision wording and Maven Central
 task naming
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Footprint report + docs: the displayed bytes-per-entry are rounded to 0.1, only
  the retained totals (and the ratios derived from them) are exact. Reword the
  report header and `benchmarking.md` so "exact" attaches to the totals, not the
  rounded per-entry display.
- `publishing.md`: Maven Central is not a Spine-convention destination —
  `PublishingRepos` defines only Cloud Artifact Registry and GitHub Packages — so
  there is no built-in `...ToMavenCentralRepository` task. Document wiring a Central
  destination as an explicit prerequisite and note the task name follows the
  configured repository/plugin rather than hard-coding one.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../results/m4max-indicative/footprint.md     |  4 +-
 .../elastic/benchmark/jmh/FootprintReport.kt  | 11 ++---
 docs/benchmarking.md                          |  7 +--
 docs/publishing.md                            | 45 +++++++++++++------
 4 files changed, 44 insertions(+), 23 deletions(-)

diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.md b/benchmarks-jvm/results/m4max-indicative/footprint.md
index 2b07434..64de945 100644
--- a/benchmarks-jvm/results/m4max-indicative/footprint.md
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.md
@@ -1,7 +1,7 @@
 # Retained-heap footprint (JOL), n = 229376 entries
 
-Bytes per entry (exact) — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
-Ratio is versus the boxed `HashMap` baseline, computed from the retained byte totals (higher = more compact).
+Bytes per entry (rounded to 0.1 for display) — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
+Ratio is versus the boxed `HashMap` baseline, computed from the **exact** retained byte totals (higher = more compact), so display rounding never inflates it.
 
 | impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
 |------|-------------------|-----------|-----------------|-----------|
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
index 81dd112..93bdc22 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
@@ -122,13 +122,14 @@ private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footp
         appendLine("# Retained-heap footprint (JOL), n = $n entries")
         appendLine()
         appendLine(
-            "Bytes per entry (exact) — each map pre-sized in its own units for the same " +
-                "entry count `n` (loads differ by each map's resize policy; capacity slack " +
-                "is included in the footprint).",
+            "Bytes per entry (rounded to 0.1 for display) — each map pre-sized in its own " +
+                "units for the same entry count `n` (loads differ by each map's resize " +
+                "policy; capacity slack is included in the footprint).",
         )
         appendLine(
-            "Ratio is versus the boxed `HashMap` baseline, computed from the retained byte " +
-                "totals (higher = more compact).",
+            "Ratio is versus the boxed `HashMap` baseline, computed from the **exact** " +
+                "retained byte totals (higher = more compact), so display rounding never " +
+                "inflates it.",
         )
         appendLine()
         appendLine("| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |")
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index 4b12828..fd2fc70 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -141,9 +141,10 @@ JOL runs in reflection mode (no agent needed); the numbers match the library's o
 ## Result: memory footprint
 
 Retained bytes per entry at `n = 229_376` (the `7/8` load of a `2^18` table), each
-map pre-sized in its own units. Measured with JOL on Apple M4 Max, Corretto 17.
-Bytes/entry are exact; ratios are computed from the retained byte totals (so a floored
-bytes/entry never inflates them).
+map pre-sized in its own units. Measured with JOL on Apple M4 Max, Corretto 17. The
+retained **totals** are exact; bytes/entry are derived and rounded to 0.1 for display,
+and the ratios are computed from the exact totals (so display rounding never inflates
+them).
 
 | impl | Long→Long B/entry | vs `HashMap` | Int→Int B/entry | vs `HashMap` |
 |------|------------------:|-------------:|----------------:|-------------:|
diff --git a/docs/publishing.md b/docs/publishing.md
index 0bb3725..d711d7c 100644
--- a/docs/publishing.md
+++ b/docs/publishing.md
@@ -58,7 +58,10 @@ plugins {
 }
 
 spinePublishing {
-    destinations = setOf(/* the Spine remote(s), or Central — see below */)
+    // The Spine convention (io.spine.gradle.publish.PublishingRepos) ships exactly two
+    // remote destinations: Cloud Artifact Registry and GitHub Packages. Maven Central is
+    // NOT one of them — see the section below to add it.
+    destinations = PublishingRepos.run { setOf(cloudArtifactRegistry, gitHub("elastic")) }
     customPublishing = true   // required: spinePublishing delegates KMP to kmp-publish
 }
 ```
@@ -66,33 +69,48 @@ spinePublishing {
 `kmp-publish` attaches the HTML-docs jar to the `kotlinMultiplatform` and `jvm`
 publications; `spinePublishing` fills in the POM (name, description, url, licenses,
 developers, scm) and the destination repositories. Validate with
-`publishToMavenLocal` before configuring any remote destination.
+`publishToMavenLocal` before configuring any remote destination. Publishing to the
+configured Spine remotes uses the per-repository task Gradle derives from the
+destination name, e.g. `publishAllPublicationsToCloudArtifactRegistryRepository`.
 
 ## Maven Central (Central Portal) — the irreversible step
 
+Maven Central is **not** a Spine-convention destination — `PublishingRepos` defines
+only Cloud Artifact Registry and GitHub Packages. Releasing to Central therefore
+requires wiring it explicitly first, and the exact Gradle task name follows the
+repository you configure (there is no built-in `...ToMavenCentralRepository` task).
+
 **Prerequisites (all must hold):**
 
-1. **A non-SNAPSHOT version.** Central rejects `-SNAPSHOT`. The project is currently
+1. **A configured Maven Central destination.** Add a Central Portal repository to the
+   build — either a `publishing.repositories { maven { name = "..."; url = ... } }`
+   block (its `name` determines the task) or a Central-publishing plugin such as
+   `com.vanniktech.maven.publish` (which registers its own `publishToMavenCentral`
+   task). Nothing in the current build wires this.
+2. **A non-SNAPSHOT version.** Central rejects `-SNAPSHOT`. The project is currently
    on a `1.0.0-SNAPSHOT-NNN` line; a Central release needs a real `1.0.0`-class
    version (a separate, deliberate version decision — not this phase's snapshot bump).
-2. **A claimed/verified namespace** for `io.spine` on the Central Portal
+3. **A claimed/verified namespace** for `io.spine` on the Central Portal
    (`central.sonatype.com` — the legacy OSSRH / `oss.sonatype.org` path reached
    end-of-life on 2025-06-30; new deployments use the Portal).
-3. **A Portal token** (a generated token, *not* the login password):
+4. **A Portal token** (a generated token, *not* the login password):
    `ORG_GRADLE_PROJECT_mavenCentralUsername` / `...Password`.
-4. **A PGP signing key**, published to a public keyserver, provided in memory:
+5. **A PGP signing key**, published to a public keyserver, provided in memory:
    `ORG_GRADLE_PROJECT_signingInMemoryKey` (+ `...KeyPassword`, + `...KeyId` for a
    subkey). Every artifact must carry a `.asc` signature.
-5. **A complete POM:** name, description, url, licenses, developers, scm — filled by
+6. **A complete POM:** name, description, url, licenses, developers, scm — filled by
    `spinePublishing`.
 
-**Release:**
+**Release** (once prerequisite 1 is wired — substitute your configured repository /
+plugin task name; do not assume a fixed one):
 
 ```bash
-# Build + sign all publications and stage them to the Portal. Still requires a
-# manual "release" click in the Portal UI (or use the auto-release variant, which
-# is one-way). Some plugin versions need --no-configuration-cache.
-./gradlew publishAllPublicationsToMavenCentralRepository
+# Build + sign all publications and stage them to the Portal. Still requires a manual
+# "release" click in the Portal UI (or an auto-release variant, which is one-way).
+# Some plugin versions need --no-configuration-cache.
+#   ./gradlew publishAllPublicationsTo<YourCentralRepoName>Repository
+# or, with the vanniktech plugin:
+#   ./gradlew publishToMavenCentral
 ```
 
 Then verify the full artifact set (root `.module`, every per-target jar,
@@ -106,7 +124,8 @@ Then verify the full artifact set (root `.module`, every per-target jar,
 | Wiring `kmp-publish` + `spinePublishing` in the build | safe (a build change; validate locally) |
 | Signing locally (needs the private key) | local, but **touches a secret** |
 | Claiming the namespace, generating a Portal token | one-time, needs Portal login |
-| `publish...ToMavenCentral...` | **needs secret credentials; released versions are permanent and immutable** |
+| Wiring a Maven Central destination (repository or plugin) | safe (a build change; not a default Spine destination) |
+| The configured Central-publish task (name follows your repo/plugin) | **needs secret credentials; released versions are permanent and immutable** |
 
 The last row is the human-gated action. Everything above it is reproducible without
 secrets and is what this phase delivers and validates.

From d943c57bf7ef7ca59172593afcd131edd29ad89c Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sun, 5 Jul 2026 18:16:18 +0100
Subject: [PATCH 07/13] Add taskset pinned mode to the benchmark runner; track
 the pinned run in #12
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- `run-matrix.sh`: an optional core-list argument runs the single-threaded
  comparison matrix (LongLong/IntInt/LoadFactor) as the JMH jar directly under
  `taskset`, so no Gradle daemon shares the isolated cores; the pinned cores are
  recorded in `environment.txt`. The multi-threaded read-scaling / mixed-load
  benchmarks stay excluded from the pinned run (they need all cores).
- `docs/benchmarking.md`: the Linux governor / turbo / isolcpus prep recipe.
- Phase 6 task doc: reference issue #12 — the step-by-step runbook for configuring
  a pinned Linux box and handing the results back to Claude Code.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .agents/tasks/phase-6-validation-release.md |  9 +++-
 benchmarks-jvm/run-matrix.sh                | 56 ++++++++++++++++-----
 docs/benchmarking.md                        | 22 ++++++++
 3 files changed, 73 insertions(+), 14 deletions(-)

diff --git a/.agents/tasks/phase-6-validation-release.md b/.agents/tasks/phase-6-validation-release.md
index 9c7cb18..82e7cba 100644
--- a/.agents/tasks/phase-6-validation-release.md
+++ b/.agents/tasks/phase-6-validation-release.md
@@ -112,7 +112,12 @@ release task and is safe to do + validate locally.
 - Non-boxing `forEach` on the primitive-value maps (closes the `iterate` gap; a chip
   was spawned during this phase).
 - A pinned-hardware authoritative `run-matrix.sh` run (JVM + a Native tier), committed
-  under `benchmarks-jvm/results/<label>/`.
-- The actual Maven Central release, when a non-SNAPSHOT version and credentials exist.
+  under `benchmarks-jvm/results/<label>/`. **Tracked in
+  [issue #12](https://github.com/SpineEventEngine/elastic/issues/12)** — a step-by-step
+  runbook for configuring a pinned Linux box and handing the results back to Claude
+  Code. `run-matrix.sh` gained a `taskset`-based pinned mode for this
+  (`run-matrix.sh <label> <cores>`).
+- The actual Maven Central release, when a non-SNAPSHOT version and credentials exist
+  (postponed; runbook in [`docs/publishing.md`](../../docs/publishing.md)).
 - Kotlin/KSP pin (2.3.21) no longer has a rationale (codegen is template-based); an
   upgrade is a separate task.
diff --git a/benchmarks-jvm/run-matrix.sh b/benchmarks-jvm/run-matrix.sh
index 929b79c..f00a968 100755
--- a/benchmarks-jvm/run-matrix.sh
+++ b/benchmarks-jvm/run-matrix.sh
@@ -7,20 +7,38 @@
 #   footprint.md/tsv  exact retained-heap footprint (JOL), ours vs competitors
 #   jmh-results.json  the authoritative JMH time matrix (fork 3, 5x1s + 5x1s)
 #
-# The JMH settings come from the `jmh {}` block in build.gradle.kts and match the
-# project methodology (@Fork 3, warmup 5x1s, measurement 5x1s, AverageTime).
-# Key sets are seeded deterministically (seed 42) and shared across maps, so a
-# rerun on the same hardware reproduces the numbers within noise.
+# The JMH settings match the project methodology (@Fork 3, warmup 5x1s, measurement
+# 5x1s, AverageTime). Key sets are seeded deterministically (seed 42) and shared
+# across maps, so a rerun on the same hardware reproduces the numbers within noise.
 #
-# WARNING: the full matrix is long (roughly a few hours on a quiet machine). Pin
-# CPU frequency where you can, keep the machine otherwise idle, and record what
-# you could not control — `environment.txt` prompts for exactly that. For a quick
-# check, run a filtered slice from the jar directly (see docs/benchmarking.md).
+# ## Pinned mode (Linux) — for citable numbers
 #
-# Usage: ./benchmarks-jvm/run-matrix.sh [label]
+# Pass a CPU core list as the second argument to pin the single-threaded comparison
+# matrix (LongLong / IntInt / LoadFactor) to isolated cores with `taskset`, running
+# the JMH jar directly so no Gradle daemon shares the cores. Prep the box first:
+#
+#   sudo cpupower frequency-set -g performance           # fix the governor
+#   echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo   # Intel: turbo off
+#   # AMD: echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost
+#   # (ideally also boot with isolcpus=<cores> so nothing else is scheduled there)
+#
+# Then, e.g. pin to cores 2,3 (one for the benchmark thread, one for GC/JIT):
+#
+#   ./benchmarks-jvm/run-matrix.sh linux-pinned 2,3
+#
+# `environment.txt` records the governor, turbo state, and the pinned cores, so the
+# bundle self-documents whether it was actually pinned. The multi-threaded
+# read-scaling / mixed-load benchmarks are deliberately NOT part of the pinned run
+# (they measure scaling and need all cores) — run those separately, unpinned.
+#
+# WARNING: the full matrix is long (roughly a few hours). For a quick check, run a
+# filtered slice from the jar directly (see docs/benchmarking.md).
+#
+# Usage: ./benchmarks-jvm/run-matrix.sh [label] [cores]
 set -euo pipefail
 
 LABEL="${1:-local}"
+CORES="${2:-}"
 HERE="$(cd "$(dirname "$0")" && pwd)"
 ROOT="$(cd "$HERE/.." && pwd)"
 OUT="$HERE/results/$LABEL"
@@ -28,6 +46,7 @@ mkdir -p "$OUT"
 
 echo "==> Capturing environment into $OUT/environment.txt"
 "$HERE/capture-env.sh" > "$OUT/environment.txt"
+[ -n "$CORES" ] && printf 'benchmark_pinned_cores=%s\n' "$CORES" >> "$OUT/environment.txt"
 cat "$OUT/environment.txt"
 
 echo "==> Retained-heap footprint (JOL)"
@@ -35,9 +54,22 @@ echo "==> Retained-heap footprint (JOL)"
 cp "$HERE/build/reports/footprint/footprint.md" "$OUT/footprint.md"
 cp "$HERE/build/reports/footprint/footprint.tsv" "$OUT/footprint.tsv"
 
-echo "==> JMH time matrix (authoritative; this takes a while)"
-"$ROOT/gradlew" :benchmarks-jvm:jmh --console=plain
-cp "$HERE/build/reports/jmh/results.json" "$OUT/jmh-results.json"
+if [ -n "$CORES" ] && command -v taskset >/dev/null 2>&1; then
+    echo "==> JMH single-threaded matrix, PINNED to cores $CORES (this takes a while)"
+    "$ROOT/gradlew" :benchmarks-jvm:jmhJar --console=plain
+    jar="$(ls -t "$HERE"/build/libs/*-jmh.jar | head -1)"
+    # The single-threaded comparison matrix only; JMH settings mirror the `jmh {}` block.
+    taskset -c "$CORES" java -jar "$jar" "Matrix|LoadFactor" \
+        -f 3 -wi 5 -i 5 -w 1s -r 1s \
+        -rf json -rff "$OUT/jmh-results.json"
+else
+    if [ -n "$CORES" ]; then
+        echo "==> 'taskset' not found; running UNPINNED via Gradle instead."
+    fi
+    echo "==> JMH time matrix via Gradle (authoritative; this takes a while)"
+    "$ROOT/gradlew" :benchmarks-jvm:jmh --console=plain
+    cp "$HERE/build/reports/jmh/results.json" "$OUT/jmh-results.json"
+fi
 
 echo "==> Done. Results bundle: $OUT"
 ls -la "$OUT"
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index fd2fc70..f4cbfe4 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -110,6 +110,28 @@ The full matrix takes **a few hours** on a quiet machine. Pin CPU frequency wher
 can and keep the machine idle; `environment.txt` records what you could not control
 (on Apple Silicon, turbo and P/E scheduling are not controllable — say so).
 
+### Pinned Linux run (citable numbers)
+
+Absolute time numbers are only citable when the machine is *pinned* — a Linux box is
+the right tool (Apple Silicon exposes none of these knobs). Prep the box, then pass a
+core list as the second argument to run the single-threaded matrix under `taskset`
+(the JMH jar runs directly, so no Gradle daemon shares the cores):
+
+```bash
+sudo cpupower frequency-set -g performance                       # fix the governor
+echo 1 | sudo tee /sys/devices/system/cpu/intel_pstate/no_turbo  # Intel: turbo off
+# AMD instead: echo 0 | sudo tee /sys/devices/system/cpu/cpufreq/boost
+# best: also boot with isolcpus=<cores> so nothing else is scheduled there
+
+./benchmarks-jvm/run-matrix.sh linux-pinned 2,3   # pin to 2 cores (bench + GC/JIT)
+```
+
+`environment.txt` then records the governor, turbo state, and pinned cores, so the
+bundle proves it was pinned. Pin to **two** cores for these `@Threads(1)` benchmarks —
+one runs the measured thread, the other absorbs GC/JIT so they don't perturb it. The
+multi-threaded read-scaling / mixed-load benchmarks are deliberately excluded from the
+pinned run (they measure scaling and need all cores); run them separately, unpinned.
+
 ### A quick slice
 
 Compile the jar once, then filter with JMH's own CLI:

From 130c6dc59ad5f55c724db01cc478b34aab4ab2b3 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sun, 5 Jul 2026 20:07:22 +0100
Subject: [PATCH 08/13] Split the authoritative benchmark and release into
 Phase 7
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 6 is now scoped to the validation work that shipped in PR #11 — the
comparative matrix, the JOL footprint report, the reproducibility harness, and the
honest docs. The two human-gated jobs move to a new Phase 7: the pinned-hardware
authoritative benchmark run (issue #12) and Maven Central publication. Configuring
a pinned box and publishing are separate jobs from writing the harness, so they no
longer block this branch.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../elastic-hashing-implementation-plan.md    | 66 +++++++++++++++++--
 .agents/tasks/phase-6-validation-release.md   | 38 ++++++-----
 2 files changed, 80 insertions(+), 24 deletions(-)

diff --git a/.agents/tasks/elastic-hashing-implementation-plan.md b/.agents/tasks/elastic-hashing-implementation-plan.md
index c5ef6e8..eec76a8 100644
--- a/.agents/tasks/elastic-hashing-implementation-plan.md
+++ b/.agents/tasks/elastic-hashing-implementation-plan.md
@@ -632,14 +632,66 @@ via the KSP pipeline (DP-7); pluggable hashers + good default finalizer + per-le
 optional JVM-actual SIMD scan behind a capability flag + feature test (authoritative path
 stays SWAR); call-site-`equals` JVM optimization.
 
-### Phase 6 — Validation & release
+### Phase 6 — Validation (the comparative matrix)
+
+**Goal:** prove the memory/speed story against the standard library *and* the
+specialist primitive-map libraries, with reproducible, honestly-framed numbers.
+
+**Status — IMPLEMENTED** (branch `phase-6`, PR #11); details in
+[`phase-6-validation-release.md`](phase-6-validation-release.md). Green on JVM (build +
+Dokka + the jmh compile); reviewed by `kotlin-engineer`, `spine-code-review`,
+`review-docs`, plus two CI review rounds (Copilot, Codex) — all findings resolved.
+- The comparative JMH matrix in the raw-JMH `benchmarks-jvm` tier (JVM-only, where the
+  competitors live): `LongLongMap`/`IntIntMap` vs boxed `HashMap` and **fastutil
+  8.5.18 / HPPC 0.10.0 / Eclipse Collections 13.0.0 / Agrona 2.5.0**, over
+  lookup(hit/miss)/insert(presized/growing)/churn × sizes × dense/clustered keys, plus
+  a load-factor sweep (`LoadFactorBenchmark`, the two load-factor-tunable competitors).
+  Monomorphic adapters keep call sites clean; a `@Setup` correctness gate rejects any
+  miswired adapter.
+- The JOL retained-footprint report (ratios from exact totals) and a reproducibility
+  runner (`run-matrix.sh`, `capture-env.sh`) bundling env metadata + fixed seeds + JSON.
+- **Measured — memory is decisive and portable:** `LongLongMap` 19.4 B/entry
+  (**4.59×** vs `HashMap`, ~1.9× vs the competitors), `IntIntMap` 10.3 (**7.11×** /
+  ~1.8×) — more compact than *even the specialist libraries*. **Distribution
+  robustness:** ours stays flat dense→clustered while fastutil/Eclipse degrade ~5–6×,
+  so ours is the *fastest* under adversarial keys (`fmix64` finalizer).
+- **Split out to Phase 7:** the authoritative *absolute* time numbers (need pinned
+  hardware) and Maven Central publication — both human-gated separate jobs, so
+  validation lands without waiting on hardware or credentials.
 
-**Goal:** publish with numbers that survive external scrutiny.
-
-**Deliverables:** full benchmark matrix (the §1.4 grid) vs `HashMap` + fastutil/HPPC +
-Eclipse + Agrona at LF 0.5/0.75/0.9/0.95/0.99; memory footprint; reproducibility
-metadata (JDK/OS/CPU pinned, seeds committed, JSON outputs); README with the honest,
-baseline-qualified positioning; Maven Central publication.
+**Deliverables**
+- The §1.4 comparative grid vs `HashMap` + fastutil/HPPC/Eclipse/Agrona; memory
+  footprint; reproducibility metadata (seeds committed, JSON outputs); README with the
+  honest, baseline-qualified positioning.
+
+**Decision points:** none open. Absolute-number authority and publication moved to
+Phase 7.
+
+### Phase 7 — Authoritative benchmarks & release
+
+**Goal:** publish numbers that survive external scrutiny, and ship the artifacts.
+
+**Status — PLANNED.** Two human-gated jobs, intentionally split out of the Phase 6 PR
+(configuring a pinned box and publishing are separate jobs from writing the harness):
+- **Authoritative pinned-hardware benchmark run** — the full time matrix on a *pinned*
+  Linux box (performance governor, turbo off, `taskset`-isolated cores; Apple Silicon
+  cannot be pinned, so its numbers stay "indicative"). `run-matrix.sh <label> <cores>`
+  already has the pinned mode; the step-by-step runbook — configuring the box and
+  handing results back to Claude Code — is
+  **[issue #12](https://github.com/SpineEventEngine/elastic/issues/12)**. Folds the
+  pinned ns/op numbers into the README, replacing the "indicative" caveat. Memory is
+  already authoritative (JOL is deterministic) and needs no rerun.
+- **Maven Central publication** — irreversible; needs a non-SNAPSHOT version, a claimed
+  namespace, a Portal token, and a signing key, and is *not* a Spine-convention
+  destination (so it needs explicit wiring first). Runbook:
+  [`../../docs/publishing.md`](../../docs/publishing.md).
+
+**Deliverables:** the pinned-hardware benchmark matrix committed under
+`benchmarks-jvm/results/<label>/` with governor/turbo/pinned-cores provenance; README
+updated to the authoritative absolute numbers; Maven Central publication.
+
+**Decision points:** whether the authoritative run also covers a Kotlin/Native tier
+(DP-2) — decided when the run is scheduled.
 
 ---
 
diff --git a/.agents/tasks/phase-6-validation-release.md b/.agents/tasks/phase-6-validation-release.md
index 82e7cba..d22b535 100644
--- a/.agents/tasks/phase-6-validation-release.md
+++ b/.agents/tasks/phase-6-validation-release.md
@@ -84,15 +84,23 @@ reproduces the committed Phase 1 measurement exactly.
 - **vs `HashMap` (the committed gate):** met — faster at scale on lookup and presized
   insert, and far more compact, per `performance-goals.md`.
 
-## Release — human-gated (not done here)
-
-Maven Central publication is **deliberately not executed**: it is irreversible and
-needs a signing key, a Central Portal token, a claimed `io.spine` namespace, and a
-**non-SNAPSHOT** version (the project is on a `-SNAPSHOT` line). The full runbook,
-including wiring `kmp-publish` + `spinePublishing` and validating locally with
-`publishToMavenLocal`, is in [`docs/publishing.md`](../../docs/publishing.md). The
-`elastic` module currently registers no publication tasks; wiring them is the first
-release task and is safe to do + validate locally.
+## Split out to Phase 7 (authoritative benchmarks & release)
+
+Two human-gated jobs were moved out of this phase so the validation work could land
+without waiting on hardware or credentials — they are separate jobs (configuring a
+pinned box, publishing) from writing the harness. See the plan's **Phase 7**.
+
+- **Authoritative pinned-hardware benchmark run** — the absolute time numbers need a
+  *pinned* Linux box (Apple Silicon cannot be pinned). `run-matrix.sh <label> <cores>`
+  has the `taskset` pinned mode; the step-by-step runbook is
+  **[issue #12](https://github.com/SpineEventEngine/elastic/issues/12)**. Memory is
+  already authoritative and needs no rerun.
+- **Maven Central publication** — deliberately not executed: irreversible, and needs a
+  signing key, a Portal token, a claimed `io.spine` namespace, a **non-SNAPSHOT**
+  version, and explicit wiring (it is not a Spine-convention destination). Runbook:
+  [`docs/publishing.md`](../../docs/publishing.md); the `elastic` module registers no
+  publication tasks yet, so wiring them (safe to validate locally with
+  `publishToMavenLocal`) is the first release task.
 
 ## Decisions
 
@@ -111,13 +119,9 @@ release task and is safe to do + validate locally.
 
 - Non-boxing `forEach` on the primitive-value maps (closes the `iterate` gap; a chip
   was spawned during this phase).
-- A pinned-hardware authoritative `run-matrix.sh` run (JVM + a Native tier), committed
-  under `benchmarks-jvm/results/<label>/`. **Tracked in
-  [issue #12](https://github.com/SpineEventEngine/elastic/issues/12)** — a step-by-step
-  runbook for configuring a pinned Linux box and handing the results back to Claude
-  Code. `run-matrix.sh` gained a `taskset`-based pinned mode for this
-  (`run-matrix.sh <label> <cores>`).
-- The actual Maven Central release, when a non-SNAPSHOT version and credentials exist
-  (postponed; runbook in [`docs/publishing.md`](../../docs/publishing.md)).
 - Kotlin/KSP pin (2.3.21) no longer has a rationale (codegen is template-based); an
   upgrade is a separate task.
+
+The two release-gated jobs — the pinned-hardware authoritative run
+([issue #12](https://github.com/SpineEventEngine/elastic/issues/12)) and Maven Central
+publication — are **Phase 7**, covered in *Split out to Phase 7* above.

From 4944477683a154321245f5908ac6ff928847340e Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sun, 5 Jul 2026 20:12:14 +0100
Subject: [PATCH 09/13] Strengthen the benchmark correctness gate: store key +
 1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Storing `value == key` left the `@Setup` gate blind to a key/value swap and let 0 be
a valid stored value (indistinguishable from the common absent=0 convention). Store
`key + 1` at every put site (setup, presized/growing insert, churn, and the
load-factor sweep) so the gate — sum of hits == Σ(key + 1) — additionally catches a
key/value swap and a key-0-reads-absent bug. Measurement is unchanged: the value is
inert payload read into a sink, and `key + 1` never collides with Agrona's MIN_VALUE
sentinel.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../benchmark/jmh/IntIntMatrixBenchmark.kt    | 17 ++++++++--------
 .../benchmark/jmh/LoadFactorBenchmark.kt      | 14 +++++++------
 .../benchmark/jmh/LongLongMatrixBenchmark.kt  | 20 ++++++++++---------
 3 files changed, 28 insertions(+), 23 deletions(-)

diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
index 0b2f19d..a74e8b4 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/IntIntMatrixBenchmark.kt
@@ -85,18 +85,19 @@ open class IntIntMatrixBenchmark {
         missKeys = intMissKeys(n, dist)
         val map = createIntInt(impl, n)
         for (key in keys) {
-            map.put(key, key)
+            map.put(key, key + 1)
         }
         check(map.size() == n) { "Expected $n entries in `$impl`, got ${map.size()}." }
-        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key's
-        // value is the key, so the sum of all hit lookups must equal the sum of keys —
-        // this catches any silent get/put defect before a single number is measured.
+        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key
+        // stores `key + 1` — never 0, and distinct from the key — so the sum of all hit
+        // lookups must equal Σ(key + 1). This catches a silent get/put defect, a
+        // key/value swap, or a key-0-reads-absent bug before a number is measured.
         // Widen to `Long` so a 1M-entry sum cannot overflow `Int`.
         var hitSum = 0L
         var expected = 0L
         for (key in keys) {
             hitSum += map.get(key).toLong()
-            expected += key.toLong()
+            expected += (key + 1).toLong()
         }
         check(hitSum == expected) {
             "Adapter `$impl` returned wrong values: hit sum $hitSum != $expected."
@@ -131,7 +132,7 @@ open class IntIntMatrixBenchmark {
     fun insertPresized(blackhole: Blackhole) {
         val fresh = createIntInt(impl, size)
         for (key in keys) {
-            fresh.put(key, key)
+            fresh.put(key, key + 1)
         }
         blackhole.consume(fresh)
     }
@@ -141,7 +142,7 @@ open class IntIntMatrixBenchmark {
     fun insertGrowing(blackhole: Blackhole) {
         val fresh = createIntInt(impl, 0)
         for (key in keys) {
-            fresh.put(key, key)
+            fresh.put(key, key + 1)
         }
         blackhole.consume(fresh)
     }
@@ -157,7 +158,7 @@ open class IntIntMatrixBenchmark {
         val m = populated
         for (key in shuffledKeys) {
             m.remove(key)
-            m.put(key, key)
+            m.put(key, key + 1)
         }
         blackhole.consume(m)
     }
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
index 686952c..bb34869 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
@@ -100,18 +100,20 @@ open class LoadFactorBenchmark {
         shuffledKeys = shuffledLong(keys)
         val map = createAtMaxLoad(impl, fill)
         for (key in keys) {
-            map.put(key, key)
+            map.put(key, key + 1)
         }
         check(map.size() == fill) { "Expected $fill entries in `$impl`, got ${map.size()}." }
-        // Correctness gate (mirrors the matrix benchmarks): each key's value is the key,
-        // so the sum of all hit lookups must equal the sum of keys — fail fast on any
-        // mis-constructed or miswired adapter rather than measuring wrong behavior.
+        // Correctness gate (mirrors the matrix benchmarks): each key stores `key + 1`
+        // (never 0, distinct from the key), so the sum of all hit lookups must equal
+        // Σ(key + 1) — fail fast on any mis-constructed or miswired adapter rather than
+        // measuring wrong behavior.
         var hitSum = 0L
         for (key in keys) {
             hitSum += map.get(key)
         }
-        check(hitSum == keys.sum()) {
-            "Adapter `$impl` returned wrong values: hit sum $hitSum != ${keys.sum()}."
+        val expected = keys.sum() + keys.size // Σ(key + 1)
+        check(hitSum == expected) {
+            "Adapter `$impl` returned wrong values: hit sum $hitSum != $expected."
         }
         populated = map
     }
diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
index de6da9d..6b5f69e 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LongLongMatrixBenchmark.kt
@@ -93,18 +93,20 @@ open class LongLongMatrixBenchmark {
         missKeys = longMissKeys(n, dist)
         val map = createLongLong(impl, n)
         for (key in keys) {
-            map.put(key, key)
+            map.put(key, key + 1)
         }
         check(map.size() == n) { "Expected $n entries in `$impl`, got ${map.size()}." }
-        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key's
-        // value is the key, so the sum of all hit lookups must equal the sum of keys —
-        // this catches any silent get/put defect before a single number is measured.
+        // Correctness gate: a benchmark on a miswired adapter is worthless. Each key
+        // stores `key + 1` — never 0, and distinct from the key — so the sum of all hit
+        // lookups must equal Σ(key + 1). This catches a silent get/put defect, a
+        // key/value swap, or a key-0-reads-absent bug before a number is measured.
         var hitSum = 0L
         for (key in keys) {
             hitSum += map.get(key)
         }
-        check(hitSum == keys.sum()) {
-            "Adapter `$impl` returned wrong values: hit sum $hitSum != ${keys.sum()}."
+        val expected = keys.sum() + keys.size // Σ(key + 1)
+        check(hitSum == expected) {
+            "Adapter `$impl` returned wrong values: hit sum $hitSum != $expected."
         }
         populated = map
     }
@@ -136,7 +138,7 @@ open class LongLongMatrixBenchmark {
     fun insertPresized(blackhole: Blackhole) {
         val fresh = createLongLong(impl, size)
         for (key in keys) {
-            fresh.put(key, key)
+            fresh.put(key, key + 1)
         }
         blackhole.consume(fresh)
     }
@@ -146,7 +148,7 @@ open class LongLongMatrixBenchmark {
     fun insertGrowing(blackhole: Blackhole) {
         val fresh = createLongLong(impl, 0)
         for (key in keys) {
-            fresh.put(key, key)
+            fresh.put(key, key + 1)
         }
         blackhole.consume(fresh)
     }
@@ -162,7 +164,7 @@ open class LongLongMatrixBenchmark {
         val m = populated
         for (key in shuffledKeys) {
             m.remove(key)
-            m.put(key, key)
+            m.put(key, key + 1)
         }
         blackhole.consume(m)
     }

From 7f2882846e1da7af772bcb6f86ce1e86ef5faa67 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Sun, 5 Jul 2026 20:19:12 +0100
Subject: [PATCH 10/13] Format the footprint report with Locale.ROOT for
 cross-locale reproducibility
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`String.format` used the default JVM locale, so on a comma-decimal locale (e.g.
de-DE) the generated `footprint.md`/`.tsv` would render "19,4" / "4,59x" —
non-reproducible and breaking stable TSV parsing. Pin `Locale.ROOT` on every format
call (the Markdown row, both TSV rows, and the ratio) so the '.' decimal separator is
stable everywhere. Verified: byte-identical output on en-US (committed bundle
unchanged) and correct '.' output under `-Duser.language=de`.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../spine/elastic/benchmark/jmh/FootprintReport.kt | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
index 93bdc22..5b2d468 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/FootprintReport.kt
@@ -31,6 +31,7 @@ import io.spine.elastic.LongLongMap
 import it.unimi.dsi.fastutil.ints.Int2IntOpenHashMap
 import it.unimi.dsi.fastutil.longs.Long2LongOpenHashMap
 import java.io.File
+import java.util.Locale
 import org.agrona.collections.Hashing
 import org.agrona.collections.Int2IntHashMap
 import org.agrona.collections.Long2LongHashMap
@@ -112,9 +113,11 @@ private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footp
         val ll = longLong.first { it.impl == impl }
         val ii = intInt.first { it.impl == impl }
         // Ratios are computed from the exact retained totals, not the displayed
-        // (rounded) bytes-per-entry, so they never overstate the win.
+        // (rounded) bytes-per-entry, so they never overstate the win. `Locale.ROOT`
+        // keeps the '.' decimal separator on every machine (a comma locale would
+        // otherwise make the committed report non-reproducible).
         "| %-8s | %6.1f | %s | %6.1f | %s |".format(
-            impl, ll.bytesPerEntry, ratio(baselineLong, ll.totalBytes),
+            Locale.ROOT, impl, ll.bytesPerEntry, ratio(baselineLong, ll.totalBytes),
             ii.bytesPerEntry, ratio(baselineInt, ii.totalBytes),
         )
     }
@@ -141,16 +144,17 @@ private fun renderMarkdown(n: Int, longLong: List<Footprint>, intInt: List<Footp
 private fun renderTsv(longLong: List<Footprint>, intInt: List<Footprint>): String = buildString {
     appendLine("impl\tcell\ttotalBytes\tbytesPerEntry")
     longLong.forEach {
-        appendLine("${it.impl}\tLongLong\t${it.totalBytes}\t${"%.2f".format(it.bytesPerEntry)}")
+        appendLine("${it.impl}\tLongLong\t${it.totalBytes}\t${"%.2f".format(Locale.ROOT, it.bytesPerEntry)}")
     }
     intInt.forEach {
-        appendLine("${it.impl}\tIntInt\t${it.totalBytes}\t${"%.2f".format(it.bytesPerEntry)}")
+        appendLine("${it.impl}\tIntInt\t${it.totalBytes}\t${"%.2f".format(Locale.ROOT, it.bytesPerEntry)}")
     }
 }
 
 /** The compactness ratio from exact retained totals: how many times smaller than the baseline. */
 private fun ratio(baselineTotal: Long, valueTotal: Long): String =
-    if (valueTotal == 0L) "n/a" else "%.2fx".format(baselineTotal.toDouble() / valueTotal)
+    if (valueTotal == 0L) "n/a"
+    else "%.2fx".format(Locale.ROOT, baselineTotal.toDouble() / valueTotal)
 
 private const val LOG2_CAPACITY = 18
 private const val LOAD_NUMERATOR = 7

From 6f42f220f575ec28163372c6bee103d77a06022f Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Mon, 6 Jul 2026 01:08:27 +0100
Subject: [PATCH 11/13] Align Markdown tables

---
 .../results/m4max-indicative/footprint.md        | 16 ++++++++--------
 .../results/m4max-indicative/lookup-hit-1m.md    |  8 ++++----
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/benchmarks-jvm/results/m4max-indicative/footprint.md b/benchmarks-jvm/results/m4max-indicative/footprint.md
index 64de945..2df8241 100644
--- a/benchmarks-jvm/results/m4max-indicative/footprint.md
+++ b/benchmarks-jvm/results/m4max-indicative/footprint.md
@@ -3,11 +3,11 @@
 Bytes per entry (rounded to 0.1 for display) — each map pre-sized in its own units for the same entry count `n` (loads differ by each map's resize policy; capacity slack is included in the footprint).
 Ratio is versus the boxed `HashMap` baseline, computed from the **exact** retained byte totals (higher = more compact), so display rounding never inflates it.
 
-| impl | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
-|------|-------------------|-----------|-----------------|-----------|
-| OURS     |   19.4 | 4.59x |   10.3 | 7.11x |
-| HASH_MAP |   89.1 | 1.00x |   73.1 | 1.00x |
-| FASTUTIL |   36.6 | 2.44x |   18.3 | 4.00x |
-| HPPC     |   36.6 | 2.44x |   18.3 | 4.00x |
-| ECLIPSE  |   36.6 | 2.44x |   18.3 | 4.00x |
-| AGRONA   |   36.6 | 2.44x |   18.3 | 4.00x |
+| impl     | Long→Long B/entry | vs HashMap | Int→Int B/entry | vs HashMap |
+|----------|-------------------|------------|-----------------|------------|
+| OURS     | 19.4              | 4.59x      | 10.3            | 7.11x      |
+| HASH_MAP | 89.1              | 1.00x      | 73.1            | 1.00x      |
+| FASTUTIL | 36.6              | 2.44x      | 18.3            | 4.00x      |
+| HPPC     | 36.6              | 2.44x      | 18.3            | 4.00x      |
+| ECLIPSE  | 36.6              | 2.44x      | 18.3            | 4.00x      |
+| AGRONA   | 36.6              | 2.44x      | 18.3            | 4.00x      |
diff --git a/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md b/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
index 33563ef..5cd262e 100644
--- a/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
+++ b/benchmarks-jvm/results/m4max-indicative/lookup-hit-1m.md
@@ -9,10 +9,10 @@ hardware with `../../run-matrix.sh`.
 `LongLongMatrixBenchmark.lookupHit`, `size=1000000`, `AverageTime` (ns per full sweep
 of 1M random-access lookups):
 
-| `dist` | `OURS` | `FASTUTIL` | `HPPC` | `ECLIPSE` | `AGRONA` | `HASH_MAP` |
-|--------|-------:|-----------:|-------:|----------:|---------:|-----------:|
-| `DENSE` | 9.9 ms | 7.7 ms | 8.7 ms | 2.0 ms | 8.4 ms | 14.3 ms |
-| `CLUSTERED` | 10.2 ms | 36 ms | — | 13 ms | — | — |
+| `dist`      |  `OURS` | `FASTUTIL` | `HPPC` | `ECLIPSE` | `AGRONA` | `HASH_MAP` |
+|-------------|--------:|-----------:|-------:|----------:|---------:|-----------:|
+| `DENSE`     |  9.9 ms |     7.7 ms | 8.7 ms |    2.0 ms |   8.4 ms |    14.3 ms |
+| `CLUSTERED` | 10.2 ms |      36 ms |      — |     13 ms |        — |          — |
 
 **Reading it.** On dense keys Eclipse's weak spread keeps `0..n-1` contiguous and
 cache-resident, so it wins; on clustered keys (low bits zeroed) that same weak spread

From adc2c6535caf47d4d12c59746af446ac4cdb1895 Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Mon, 6 Jul 2026 01:08:57 +0100
Subject: [PATCH 12/13] Update `config`

---
 .../kotlin/io/spine/dependency/local/Compiler.kt     |  6 ++----
 buildSrc/src/main/kotlin/kmp-module.gradle.kts       | 12 ++++++++++++
 config                                               |  2 +-
 3 files changed, 15 insertions(+), 5 deletions(-)

diff --git a/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt b/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt
index e3b4d0a..8dbffcd 100644
--- a/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt
+++ b/buildSrc/src/main/kotlin/io/spine/dependency/local/Compiler.kt
@@ -27,8 +27,6 @@
 package io.spine.dependency.local
 
 import io.spine.dependency.Dependency
-import io.spine.dependency.local.Compiler.DF_VERSION_ENV
-import io.spine.dependency.local.Compiler.VERSION_ENV
 
 /**
  * Dependencies on the Spine Compiler modules.
@@ -74,7 +72,7 @@ object Compiler : Dependency() {
      * The version of the Compiler dependencies.
      */
     override val version: String
-    private const val fallbackVersion = "2.0.0-SNAPSHOT.057"
+    private const val fallbackVersion = "2.0.0-SNAPSHOT.059"
 
     /**
      * The distinct version of the Compiler used by other build tools.
@@ -83,7 +81,7 @@ object Compiler : Dependency() {
      * transitive dependencies, this is the version used to build the project itself.
      */
     val dogfoodingVersion: String
-    private const val fallbackDfVersion = "2.0.0-SNAPSHOT.057"
+    private const val fallbackDfVersion = "2.0.0-SNAPSHOT.059"
 
     /**
      * The artifact for the Compiler Gradle plugin.
diff --git a/buildSrc/src/main/kotlin/kmp-module.gradle.kts b/buildSrc/src/main/kotlin/kmp-module.gradle.kts
index 089722e..4db37f1 100644
--- a/buildSrc/src/main/kotlin/kmp-module.gradle.kts
+++ b/buildSrc/src/main/kotlin/kmp-module.gradle.kts
@@ -38,6 +38,7 @@ import io.spine.gradle.javac.configureJavac
 import io.spine.gradle.kotlin.setFreeCompilerArgs
 import io.spine.gradle.publish.IncrementGuard
 import io.spine.gradle.report.license.LicenseReporter
+import io.spine.gradle.testing.configureLogging
 
 /**
  * Configures this [Project] as a Kotlin Multiplatform module.
@@ -161,11 +162,22 @@ java {
  *
  * Also, Kotlin and Java share the same test executor (JUnit), so tests
  * configuration is for both.
+ *
+ * The `jvmTest` task mirrors the setup made by `module-testing` for
+ * the `test` task of a `jvm-module` (`module-testing` itself cannot be
+ * applied here because it brings `java-library`, which conflicts with
+ * the Kotlin Multiplatform plugin). Unlike `module-testing`, no engine
+ * filter is imposed: `jvmTest` dependencies include the Kotest runner,
+ * which is a JUnit Platform engine of its own.
  */
 tasks {
     withType<JavaCompile>().configureEach {
         configureJavac()
     }
+    named<Test>("jvmTest") {
+        useJUnitPlatform()
+        configureLogging()
+    }
 }
 
 /**
diff --git a/config b/config
index 997f02a..c2aae6e 160000
--- a/config
+++ b/config
@@ -1 +1 @@
-Subproject commit 997f02abd302cdaec346daf997b8cfe4bfbc6318
+Subproject commit c2aae6e74662ddbe60e3e8695cc6a1b8b104f0a3

From 24fa6cd2b1db656d6cc555978cbbd35c7fe9599d Mon Sep 17 00:00:00 2001
From: Alexander Yevsyukov <alexander.yevsyukov@teamdev.com>
Date: Mon, 6 Jul 2026 01:38:30 +0100
Subject: [PATCH 13/13] Pin the load-factor sweep's capacity with a
 load-independent hint
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

LoadFactorBenchmark sized fastutil/HPPC by `fill`, which relied on the non-obvious
fact that nextPow2(ceil(fill / 0.99)) lands on 2^20 for every swept load — correct
for the current values (and confirmed by the rising lookup curve), but fragile and
hard to verify, and it would silently break if a load below 0.5 were ever added.

Construct instead with a CONSTANT hint (PINNED_HINT, sized for the top load in a
2^20 table), so the backing table is manifestly 2^20 slots at every point on the
axis and the achieved load is exactly fill / 2^20 = loadFactor. Verified: lookup cost
still rises ~5.5x from load 0.50 to 0.99 (fastutil 7.0->38.5 ms, HPPC 8.4->44.4 ms),
confirming the load tracks the parameter and no resize occurs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../benchmark/jmh/LoadFactorBenchmark.kt      | 57 +++++++++++--------
 1 file changed, 34 insertions(+), 23 deletions(-)

diff --git a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
index bb34869..0372094 100644
--- a/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
+++ b/benchmarks-jvm/src/jmh/kotlin/io/spine/elastic/benchmark/jmh/LoadFactorBenchmark.kt
@@ -64,13 +64,15 @@ import org.openjdk.jmh.infra.Blackhole
  * ### Hitting a target load on a power-of-two table
  *
  * A power-of-two open-addressing table can only sit at loads in `(lf_max/2, lf_max]`
- * — capacity doubles at each boundary. To land on a *chosen* load, the capacity is
- * pinned at `2^20` and the number of inserted entries is set to
- * `fill = round(loadFactor · 2^20)`; each map is constructed with the maximum load
- * factor (`0.99`) so it does not resize before reaching `fill`. Every invocation
- * then performs the **same** `2^20` random-access lookups (cycling through the
- * present keys), so scores are directly comparable across the load-factor axis:
- * the only thing changing is probe-chain length.
+ * — capacity doubles at each boundary. So the backing table is pinned at `2^20` slots
+ * by a **constant** construction hint (`PINNED_HINT`, sized for the top load in a
+ * `2^20` table at construction factor `0.99`) that does **not** depend on the swept
+ * `loadFactor` — every point on the axis builds the *same* `2^20`-slot table. Each
+ * point then inserts `fill = round(loadFactor · 2^20)` entries (always below the
+ * table's resize threshold), so the achieved load is exactly `fill / 2^20 =
+ * loadFactor` and cannot vary with capacity. Every invocation performs the **same**
+ * `2^20` random-access lookups (cycling the present keys), so scores are directly
+ * comparable across the axis: the only thing changing is probe-chain length.
  */
 @State(Scope.Benchmark)
 @BenchmarkMode(Mode.AverageTime)
@@ -95,10 +97,12 @@ open class LoadFactorBenchmark {
 
     @Setup
     fun setUp() {
-        fill = (loadFactor * CAPACITY).roundToInt()
+        fill = (loadFactor * PINNED_CAPACITY).roundToInt()
         val keys = LongArray(fill) { it.toLong() }
         shuffledKeys = shuffledLong(keys)
-        val map = createAtMaxLoad(impl, fill)
+        // Capacity is fixed at 2^20 by a load-factor-independent hint, so the achieved
+        // load is exactly `fill / 2^20 = loadFactor`.
+        val map = createAtMaxLoad(impl)
         for (key in keys) {
             map.put(key, key + 1)
         }
@@ -126,7 +130,7 @@ open class LoadFactorBenchmark {
         val n = keys.size
         var idx = 0
         var sink = 0L
-        repeat(CAPACITY) {
+        repeat(PINNED_CAPACITY) {
             sink += m.get(keys[idx])
             idx++
             if (idx == n) {
@@ -135,30 +139,25 @@ open class LoadFactorBenchmark {
         }
         blackhole.consume(sink)
     }
-
-    private companion object {
-
-        /** The pinned table capacity; entries fill it to the target load. */
-        const val CAPACITY = 1 shl 20
-    }
 }
 
 /**
- * A [LongLongCell] for one of the high-load-capable competitors, constructed to hold
- * [fill] entries in a `2^20`-slot table without resizing (capacity pinned via the
- * maximum load factor). Only fastutil and HPPC are supported — Agrona's load factor
- * is capped at 0.9, so it cannot be held at this benchmark's high-load points.
+ * A [LongLongCell] for one of the high-load-capable competitors, whose backing table
+ * is pinned at `2^20` slots by a constant [PINNED_HINT] (expected-elements sizing at
+ * factor `0.99`) — independent of the swept load factor. Only fastutil and HPPC are
+ * supported — Agrona's load factor is capped at 0.9, so it cannot be held at this
+ * benchmark's high-load points.
  */
-private fun createAtMaxLoad(impl: String, fill: Int): LongLongCell = when (impl) {
+private fun createAtMaxLoad(impl: String): LongLongCell = when (impl) {
     FASTUTIL -> object : LongLongCell {
-        private val map = Long2LongOpenHashMap(fill, MAX_LOAD_F)
+        private val map = Long2LongOpenHashMap(PINNED_HINT, MAX_LOAD_F)
         override fun put(key: Long, value: Long) { map.put(key, value) }
         override fun get(key: Long): Long = map.get(key)
         override fun remove(key: Long) { map.remove(key) }
         override fun size(): Int = map.size
     }
     HPPC -> object : LongLongCell {
-        private val map = com.carrotsearch.hppc.LongLongHashMap(fill, MAX_LOAD_D)
+        private val map = com.carrotsearch.hppc.LongLongHashMap(PINNED_HINT, MAX_LOAD_D)
         override fun put(key: Long, value: Long) { map.put(key, value) }
         override fun get(key: Long): Long = map.get(key)
         override fun remove(key: Long) { map.remove(key) }
@@ -167,8 +166,20 @@ private fun createAtMaxLoad(impl: String, fill: Int): LongLongCell = when (impl)
     else -> throw IllegalArgumentException("Load factor is not sweepable for `$impl`.")
 }
 
+/** The pinned table capacity — the same `2^20` slots at every point on the sweep. */
+private const val PINNED_CAPACITY = 1 shl 20
+
 /** The maximum load factor as a `float` for the fastutil constructor. */
 private const val MAX_LOAD_F = 0.99f
 
 /** The maximum load factor as a `double` for the HPPC constructor. */
 private const val MAX_LOAD_D = 0.99
+
+/**
+ * The constant expected-elements hint. Both fastutil and HPPC size their table to
+ * `nextPow2(ceil(hint / loadFactor))`; `ceil(1038090 / 0.99) = 2^20`, so this hint
+ * (the top load in a `2^20` table) always yields a `2^20`-slot table — and, being a
+ * constant, the same table for every swept load factor. Every `fill ≤ PINNED_HINT`
+ * then sits below the resize threshold, so the achieved load is `fill / 2^20`.
+ */
+private val PINNED_HINT = (MAX_LOAD_D * PINNED_CAPACITY).roundToInt()