swactor/CLAUDE/notes/progress.md

# Progress Log

## Current Stage: Cycle 20 — Hot-Path Performance (Identity Hashing)

### Status: COMPLETE

### Research
- **Stakker**: Closure-based dispatch. `call!` macro generates `FnOnce` closures pushed to a flat byte Vec queue. No HashMap, no Box<dyn Any>, no downcast. Direct method calls that the compiler can inline. Single-threaded only.
- **Actix**: Vtable dispatch via `Box<dyn EnvelopeProxy<A>>`. `Addr<A>` is a direct channel reference (no HashMap lookup). Custom Vyukov lock-free MPSC queue. Default mailbox capacity 16.
- **Key insight**: Both avoid HashMap entirely by using direct references. Swactor needs HashMaps for location-transparent 32-byte addresses (multi-worker routing + transport). The optimization is to minimize HashMap cost, not eliminate it.
- Full analysis: `CLAUDE/notes/dispatch_comparison.md`

### Implementation
1. **Custom `Hash` for ActorAddress** (`src/actor.rs`) — only hashes first 8 bytes instead of 32. All HashMaps using ActorAddress benefit automatically.
2. **Identity hasher** (`src/delivery.rs`) — `AddrHasher`/`AddrBuildHasher` that passes the 8-byte hash value through as the bucket index directly, skipping SipHash.
3. **Hot-path HashMap replacement** — `AddrMap<V>` type alias used in:
   - `AddressMap.inner` (delivery.rs) — on every send
   - `ActorPool.actors` (worker.rs) — on every deliver and tick_all
   - `InboxRegistry.senders` (delivery.rs)
   - `MonitorRegistry.monitors` (delivery.rs)
   - `NameRegistry.reverse` (delivery.rs)
   - `GroupRegistry.memberships` + `AddrSet` for group member sets (delivery.rs)
   - `TransportRouter.routes` (transport.rs)
4. **Stop-requests optimization** (worker.rs) — `is_empty()` short-circuit before linear scan in inner message loop

### Microbenchmark Results (reliable, same-process A/B)
| Operation | SipHash | Identity | Speedup |
|-----------|---------|----------|---------|
| Hash | 1.35 ns | 0.67 ns | 2.0x |
| Lookup/100 | 29.8 ns | 15.5 ns | 1.9x |
| Lookup/1000 | 38.0 ns | 8.2 ns | 4.6x |
| Insert 1000 | 48.2 µs | 21.1 µs | 2.3x |

Note: End-to-end benchmarks unreliable in sandbox (55% variation between identical runs). Microbenchmarks confirmed significant hash/lookup improvement.

### Tests
- 143 behavioral tests pass (140 existing + 3 new)
- 7 proptest pass
- New tests:
  - `many_actors_all_receive_correct_messages` — 200 actors, verifies no misrouting from identity hasher
  - `ring_routing_unchanged_after_hasher_optimization` — 100-actor chain, verifies address_map correctness
  - `stop_self_with_pending_messages_still_works` — verifies stop_requests optimization correctness

### Files Modified
- `src/actor.rs` — Custom Hash impl for ActorAddress (8-byte)
- `src/delivery.rs` — AddrHasher, AddrBuildHasher, AddrMap, AddrSet types; 5 HashMap replacements
- `src/worker.rs` — ActorPool.actors AddrMap; stop_requests optimization
- `src/transport.rs` — TransportRouter.routes AddrMap
- `Cargo.toml` — Added hasher_benchmarks bench entry
- `benches/hasher_benchmarks.rs` — New: component-level microbenchmarks
- `tests/runtime_api.rs` — 3 new behavioral tests
- `CLAUDE/notes/dispatch_comparison.md` — New: Stakker/Actix/Swactor analysis

## Next Steps
- Profile the `Box::new(msg)` allocation cost — SmallBox/inline storage could eliminate heap alloc for small messages
- Investigate VecDeque mailbox alternative (slab-allocated ring buffer)
- Consider `enum_dispatch` pattern for avoiding `dyn Any` downcast (would require API changes)
- Benchmark on dedicated hardware (sandbox too noisy for reliable end-to-end measurement)

## Open Questions
- Is 8 bytes sufficient for the identity hash? (Yes — 2^64 from crypto-random bytes)
- Should we provide a `with_hasher` public API for users? (No — internal optimization only)