feat: Supersonic evaluator, Cactus Kev hash, repo split cleanup

Evaluator overhaul:
- Add Supersonic LUT trie evaluator (32M-entry, O(n) hand evaluation)
- Add Cactus Kev perfect-hash 5-card evaluator (prime-product hashing)
- 3-tier evaluation priority: Supersonic → Cactus Kev → Algorithmic
- DashMap-cached 7-card evaluation for lock-free concurrent access
- Rewrite JumpTable around CactusKevEvaluator + DashMap cache

Bot framework:
- Add StrategyBot adapter (Strategy trait → HoldemPlayer)
- Add register_bot_type() for plugin-style bot registration
- Add strategy module with modular composable strategies

Repository split:
- Remove holdem_bots from workspace (moved to private super_marvin repo)
- Remove holdem_bots dependency from holdem_sim
- Update cash_game.toml to use built-in bots only
- Clean up .gitignore (remove stale holdem_bots exclusion)
- Delete plans/ directory (internal planning artifacts)

Documentation:
- Add ARCHITECTURE_SUPERSONIC_EVALUATOR.md
- Add REFERENCES.md
- Update ROADMAP.md and VISION.md
- Remove outdated docs (ACHIEVEMENTS, RAKE, TOURNAMENT_RAKE, meerkat-alignment)
This commit is contained in:
Jan-Peter von Hunnius 2026-05-25 11:10:52 +02:00
parent f81f0579d1
commit 09a0777f96
36 changed files with 6565 additions and 4934 deletions

68
docs/REFERENCES.md Normal file
View file

@ -0,0 +1,68 @@
# Reference Implementations
## Java Supersonic Evaluator
The Rust Supersonic evaluator is a port of a Java implementation that uses a pre-computed trie for O(7) hand evaluation.
### Source Location
- **Path**: `/home/jan/Development/poker/old_bot/SNG-Testbed/src/pokerai/pokerbots/common/supersonic/`
### Key Files
| File | Purpose |
|------|---------|
| `LookupHandEvaluator.java` | Runtime evaluator — singleton that loads `HandRanks.dat` and provides 5/6/7-card evaluation via chain lookups |
| `generator/StateTableGenerator.java` | Offline table generator — builds the 32.5M-entry `hand_ranks` trie using two-pass algorithm |
| `generator/Flushes.java` | Flush and straight-flush ranking table — pre-computed hand rank values for suited hands |
| `generator/Unique.java` | Straight and high-card ranking table — pre-computed hand rank values for non-flush unsuited hands |
| `generator/Products.java` | Sorted unique 5-prime products — used during key normalization for the trie |
| `generator/Values.java` | Hand rank values by product position — maps sorted prime products to hand rank encodings |
| `test/CorrectnessTest.java` | Correctness validation — tests 5M random hands against a reference evaluator |
### Algorithm Notes
- The Java implementation uses `int[]` for the trie (32,487,834 entries)
- Card encoding: `rank * 4 + suit` (same as Rust's `PackedCard` index)
- Hand rank encoding: `(category << 12) | sub_rank` (16-bit packed)
- Root node starts at index 53 (indices 1–52 reserved for initial card offsets)
- The generator uses the Cactus Kev 5-card evaluator during table population
### Porting Considerations
- Java `int` is 32-bit signed → Rust `u32` (hand ranks are never negative)
- Java array initialization to 0 → Rust `vec![0u32; 32_487_834]`
- Java singleton pattern → Rust `OnceLock` or `Arc<SupersonicEvaluator>`
- Java `ObjectOutputStream` → Rust custom binary serialization with checksum
---
## Cactus Kev Algorithm
The existing Rust Cactus Kev implementation in [`cactus_kev.rs`](holdem_core/src/evaluator/cactus_kev.rs) was based on the original Cactus Kev algorithm.
### Source References
- **Original**: http://suffe.coolpage.cash/poker/evaluator.html (archived)
- **Algorithm**: Uses prime number products to create perfect hashes for 5-card hand equivalence classes
- **Tables**: 1,287 flush entries + 6,175 unsuited entries = 7,462 total lookup entries
### Relationship to Supersonic
The Cactus Kev evaluator serves two roles in the Supersonic architecture:
1. **Build-time dependency**: Used by the table generator to evaluate 5-card hands
2. **Runtime fallback**: Used when the Supersonic LUT file is not available
---
## Other References
### Meerkat API (Java)
- **Purpose**: Reference API for bot interface design
### Algorithmic Evaluator
- **Location**: [`algorithmic_evaluator.rs`](holdem_core/src/evaluator/algorithmic_evaluator.rs)
- **Purpose**: Rule-based evaluator used as correctness oracle
- **Note**: Not ported from Java; implemented directly in Rust from poker hand ranking rules