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