robinxx_map 0.1.0

# Requirements Specification: robinxx_map
**Role:** Architect Engineer → Senior Software Engineer
**Status:** Frozen for Implementation (v0.1.0)
**Target Registry:** crates.io, Codeberg, GitHub
**MSRV:** Rust 1.95.0 | Edition: 2024

## Architect Directives
- **Primary Objective:** High-performance, thread-safe open-addressing hash map using Robin Hood displacement & xxHash3, fully compatible with `no_std + alloc`.
- **Concurrency Model:** Internal synchronization via zero-dependency `SpinMutex` (`AtomicBool`), guaranteeing `Send + Sync` across all targets. Strategy finalized for v0.1.0.
- **Memory Safety:** Internal `unsafe` blocks strictly guarded by `# Safety` invariants. Public API is 100% safe. Relies on stable global allocator.
- **Portability:** `#![no_std]` compatible with `alloc`. Strict zero external dependencies except `xxhash-rust` (hashing) and `proptest`/`criterion` (dev/test).
- **Documentation Contract:** Strict `rustdoc` (EN standard), `-D warnings` in CI, 100% public API doctest coverage, ≥90% internal logic coverage. `cargo miri` validation mandatory.

## Functional Requirements (FR)
| ID | Requirement | Owner | Description |
|----|-------------|-------|-------------|
| FR-01 | Construction & Allocation | Eng | `new()`, `with_capacity(n)`. Power-of-two sizing, 64B alignment. Global allocator only. |
| FR-02 | Insert & Update | Eng | `insert(key, value)` → `bool`. Displaces higher DfH entries. Triggers resize at 80% LF. |
| FR-03 | Lookup (Closure Pattern) | Eng | `with_key(&K, Fn)` & `with_key_mut(&K, Fn)`. Safe access without returning refs in v0.1.0. |
| FR-04 | Erase & Backward Shift | Eng | `remove(&key)` → `bool`. Eliminates tombstones via DfH backward shift. |
| FR-05 | Capacity & State | Eng | `len()`, `capacity()`, `is_empty()`, `clear()`, `reserve(n)`. O(1) metadata access. |
| FR-06 | Entry API | Eng | `entry(key)` → `Entry`. `Vacant`/`Occupied` variants. Requires `K: Clone` bound in v0.1.0. |
| FR-07 | Iterators | Eng | `iter()`, `iter_mut()`, `keys()`, `values()`, `drain()`. Yield-safe traversal holding `MutexGuard`. |
| FR-08 | Custom Hash Trait | Eng | `pub trait RobinHoodKey`. Wraps `xxhash-rust` internally. Explicit impls for primitives & bytes. |

## Non-Functional Requirements (NFR)
| ID | Category | Constraint | Validation Method |
|----|----------|------------|-------------------|
| NFR-01 | Performance | Amortized O(1) ops. Resize ≤80% LF. Stable auto-vectorization hints. | `criterion` vs `std::HashMap` & `hashbrown` |
| NFR-02 | Safety | Zero UB in safe API. `unsafe` confined to allocation/probing. Miri clean. | `cargo miri test`, TSAN/ASAN, strict review |
| NFR-03 | Concurrency | `Send + Sync` guaranteed. `SpinMutex` prevents races. `pub(crate)` lock. | Multi-threaded `proptest` invariants |
| NFR-04 | Documentation | All `pub` items follow EN rustdoc template. `-D warnings` enforced. | `RUSTDOCFLAGS="-D warnings" cargo doc` |
| NFR-05 | Coverage | ≥90% internal logic, 100% public API & doctests. | `cargo llvm-cov --open` |

## v0.2.0 Roadmap Priorities
| Priority | Feature | Status | Description |
|----------|---------|--------|-------------|
| 1 | **API Parity** | Planned | Add `get()`, `get_mut()` returning `Option<&V>`/`Option<&mut V>`. Relax `Clone` bound on Entry. |
| 2 | **Concurrency Scaling** | Planned | Explore `ShardedMap` or `RwLock` optimization for read-heavy workloads. |
| 3 | **Performance Tuning** | Planned | Explicit prefetch hints, cache-line padding adjustments, branch prediction optimization. |
| 4 | **Ecosystem** | Planned | `serde` feature, `std::hash::Hash` bridge, panic-free mode. |
| x | **Generic Allocator** | Skipped | Deferred due to nightly/instability risks; maintain stable global allocator. |

## Performance Targets
| Component | Metric | Bound | Measurement |
|-----------|--------|-------|-------------|
| Insert (warm) | Throughput | ≥85% of `hashbrown` | `bench_insert_seq` |
| Find (90% hit) | Latency | ≤1.2x `std::HashMap` | `bench_find_hit` |
| Resize | Amortized Cost | ≤2.5x baseline insert | `bench_resize` |
| Memory Overhead | Per-entry | ≤25% (meta + SoA padding) | `bench_capacity_usage` |

## Out of Scope
- Cryptographic hashing (xxHash3 is non-cryptographic by design)
- Async I/O, serialization (Serde/JSON), or network transport
- Dynamic SIMD intrinsics (rely on stable auto-vectorization only)
- `parking_lot` or external lock implementations.
- Custom Allocator API (`Allocator` trait).

## Architect Sign-Off
- [x] MSRV set to **1.95.0** (Latest Stable).
- [x] `with_key` closure pattern locked for v0.1.0; ref-returning API planned for v0.2.0.
- [x] Global allocator only; generic allocator deferred.
- [x] `SpinMutex` strategy finalized; `pub(crate)` visibility.
- [x] Roadmap priorities: API → Concurrency → Perf → Ecosystem.
- [x] Miri integration added to validation suite.