Jan-Peter v. Hunnius 09a0777f96 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)

2026-05-25 11:10:52 +02:00

3 KiB

Raw Blame History

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 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:

Build-time dependency: Used by the table generator to evaluate 5-card hands
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
Purpose: Rule-based evaluator used as correctness oracle
Note: Not ported from Java; implemented directly in Rust from poker hand ranking rules

3 KiB Raw Blame History Unescape Escape