robinxx_map 0.1.0

# Architecture & Design Specification: robinxx_map
**Role:** Architect Directive → Senior Engineer Blueprint
**Revision:** 0.1.0 | **Toolchain:** Rust 1.95.0 (Edition 2024)

## Architect Directives
- **Decoupling Rule:** Safe API (`map.rs`) strictly wraps `RawTable` (`table.rs`). Concurrency (`sync.rs`) and hashing (`hash.rs`) are isolated modules.
- **Memory Ownership Constraint:** Keys/Values follow Rust move semantics. `Drop` is respected during `erase`/`resize`. No implicit clones.
- **Thread Model Requirement:** Internal `SpinMutex` using `core::sync::atomic::AtomicBool`. Guarantees `Send + Sync` without `std`. Critical sections kept minimal. Strategy final for v0.1.0.

## Senior Engineer Specification
### 1. System Architecture
```
[User/Client]
     │
     ▼
┌─────────────────────┐
│  RobinHoodMap<K,V,A)│ ◄── Safe Public API (map.rs, entry.rs, iter.rs)
└─────────┬───────────┘
          │ MutexGuard
          ▼
┌─────────────────────┐
│    InnerState<K,V>  │ ◄── Raw Unsafe Table (table.rs)
└─────────┬───────────┘
          │ Allocator (alloc::alloc::Allocator)
          ▼
┌─────────────────────┐
│   SoA Memory Block  │ ◄── [Meta(u8)] [Keys(K)] [Values(V)] @ 64B align
└─────────────────────┘
```

- **Pipeline:** Hash → Probing → DfH Displacement → Atomic Lock Guard → Allocation/Resize → Drop/Return
- **Concurrency:** Exclusive `SpinMutex` wraps `RawTable`. Iterators & Entry API retain guard to ensure isolation.

### 2. Module Structure & Responsibilities
| Module | Path | Responsibility | Architect Constraint |
|--------|------|----------------|----------------------|
| `lib` | `src/lib.rs` | Crate root, `no_std` setup, `extern crate alloc`, re-exports | `#![no_std]`, MSRV 1.95.0 |
| `hash` | `src/hash.rs` | `RobinHoodKey` trait, `xxhash_rust` wrapper, explicit impls | Zero-dep, stable `xxh3` binding |
| `memory` | `src/memory.rs` | SoA layout calculation, aligned allocation via global allocator | 64B alignment, power-of-two caps |
| `table` | `src/table.rs` | `RawTable`: probing, insert, erase, resize, DfH logic | `unsafe` confined, auto-vec friendly |
| `sync` | `src/sync.rs` | `SpinMutex`, `MutexGuard` for `no_std` thread-safety | `AtomicBool` + `spin_loop()`, `pub(crate)` |
| `map` | `src/map.rs` | `RobinHoodMap` safe wrapper, `with_key` closure API | Lifetime bounds, ergonomic `&self` |
| `entry` | `src/entry.rs` | `Entry`, `OccupiedEntry`, `VacantEntry` API | Requires `K: Clone` in v0.1.0 |
| `iter` | `src/iter.rs` | `Iter`, `IterMut`, `Keys`, `Values`, `Drain` | Safe yielding, invariant-checked |

### 3. Concurrency & Memory Model
- **Read Path:** `with_key()` acquires `SpinMutex` → probes `RawTable` → executes closure. Lock held during closure.
- **Write Path:** `insert()`/`remove()`/`reserve()` acquire exclusive lock → mutate DfH/move data → release. Resize rehashes under lock.
- **Reclamation:** `Drop` called explicitly during `erase` and `clear`. `resize()` drops old block after successful migration.
- **Ownership:** Caller retains key/value ownership until inserted. `insert()` takes `K`/`V` by value.

### 4. API Surface Contract (v0.1.0)
```rust
pub struct RobinHoodMap<K, V> { /* private */ }

impl<K: RobinHoodKey + PartialEq, V> RobinHoodMap<K, V> {
    pub fn new() -> Self;
    pub fn with_capacity(capacity: usize) -> Self;
    
    // Closure-based access (v0.1.0)
    pub fn with_key<F, R>(&self, key: &K, f: F) -> Option<R> where F: FnOnce(&V) -> R;
    pub fn with_key_mut<F, R>(&self, key: &K, f: F) -> Option<R> where F: FnOnce(&mut V) -> R;
    
    pub fn insert(&self, key: K, value: V) -> bool;
    pub fn remove(&self, key: &K) -> bool;
    
    // Entry API (requires K: Clone)
    pub fn entry(&self, key: K) -> Entry<'_, K, V> where K: Clone;
    
    pub fn len(&self) -> usize;
    pub fn capacity(&self) -> usize;
    pub fn is_empty(&self) -> bool;
    pub fn clear(&self);
    pub fn reserve(&self, additional: usize);
    
    // Iterators
    pub fn iter(&self) -> Iter<'_, K, V>;
    pub fn iter_mut(&self) -> IterMut<'_, K, V>;
    pub fn keys(&self) -> Keys<'_, K, V>;
    pub fn values(&self) -> Values<'_, K, V>;
    pub fn drain(&self) -> Drain<'_, K, V>;
}
```
- **Thread Safety:** `RobinHoodMap: Send + Sync` (guarded by atomic spinlock).
- **Error Policy:** Infallible public API. Panics only on allocator OOM (documented) or invariant violation.

### 5. Documentation & Testing Strategy
- **Strict rustdoc:** All `pub` items follow Summary → Description → Examples → Panics → Errors → Safety → See Also. CI enforces `-D warnings`.
- **Benchmarking:** `criterion 0.8.2` groups: `insert`, `find`, `erase`, `resize`. Baselines: `std::collections::HashMap`, `hashbrown`.
- **Coverage:** `cargo-llvm-cov` target ≥90% internal, 100% public API. `proptest` for collision/resize invariants. Doctests mandatory.

### 6. Engineering Implementation Notes
- **MSRV:** Rust 1.95.0 enables latest edition features and stable API improvements.
- `#![no_std]` with `extern crate alloc`. Global allocator used exclusively.
- Auto-vectorization relies on `#[inline]` hints and contiguous SoA memory. No `std::simd`.
- `unsafe` blocks explicitly document: alignment guarantees, index masking invariants, and DfH bounds.
- Publish workflow remains **manual** for strict release control.

## Senior Engineer Sign-Off
- [x] Architecture mapped to modules
- [x] Concurrency model formally specified (`SpinMutex` final for v0.1.0)
- [x] API contracts & safety boundaries defined (Closure pattern v0.1.0)
- [x] Validation pipeline aligned with NFRs (Miri added, MSRV 1.95.0)