Java Bot Analysis — Supersonic Framework

Maps every Java bot generation, utility class, and data file to the current Rust port status.

---

## 1. Java Bot Architecture Overview

### 1.1 Composite Pattern — `ModularStrategy`

The Java Supersonic framework uses a **composite strategy pattern** as its core abstraction. Every bot is a tree of `ModularStrategy` nodes, each containing zero or more sub-strategies. The root delegates to children according to a voting mode:

| Voting Mode | Behaviour |
|-------------|-----------|
| `FirstApplicable` | Returns the first child whose `isApplicable()` is `true` |
| `Democratic` | Majority vote among applicable children (weighted) |
| `Random` | Weighted random selection among applicable children |

### 1.2 Strategy Composition Hierarchy

```
CustomModNGV2 (Root ModularStrategy)
├── StealFromInactive
├── FoldMicroStack
├── ModNashICMv7
├── PushOrFoldStrategyV3
├── KEHU20BBNeqV3
├── NGPreFlopStrategyV3
├── NGPostFlopStrategyV3
│   ├── BluffModule
│   ├── LureModule
│   └── EHSDecision
└── EmergencyStrategy
```

The root uses `FirstApplicable` voting — strategies are ordered by priority. If a higher-priority strategy applies (e.g., Nash ICM in endgame), it short-circuits and lower strategies are never consulted.

### 1.3 Rust Equivalent

| Java | Rust | Status |
|------|------|--------|
| `Strategy` interface | `Strategy` trait | ✅ Ported |
| `ModularStrategy` | `ModularStrategy` struct | ✅ Ported |
| `VotingMode` enum | `VotingMode` enum | ✅ Ported |
| `StrategyBot` adapter | `StrategyBot` struct | ✅ Ported |
| Game state fields | `StrategyContext` struct | ✅ Ported |

---

## 2. Generation 1: Static Rules

### 2.1 BigStackStrategy — Cash NL, stack > 25 BB
- Preflop: Hand grouping system (groups 1–8)
- Postflop: Static hand classification → action mapping
- **Rust status:** ✅ Ported as `BigStackBot`

### 2.2 ShortStackStrategy — Cash NL, stack ≤ 25 BB
- Preflop: Push/fold based on Sklansky-Chubukov rankings
- Postflop: Commit or fold approach
- **Rust status:** ✅ Ported as `ShortStackBot`

---

## 3. Generation 2: Mathematical Rules

### 3.1 RingNLStrategyV1 — Cash NL EHS-based
- Replaced static hand grouping with **Effective Hand Strength (EHS)**
- `ehs = hs × (1 − npot) + (1 − hs) × ppot`
- Threshold system per street (strong/good/marginal/weak)
- **Rust status:** ⚠️ Partially ported — uses `approximate_win_prob()` instead of EHS from `HandPotential`

### 3.2 RingFLStrategyV1 — Cash FL
- Fixed-limit specific thresholds, more calling, BB defense
- **Rust status:** ❌ Not ported

---

## 4. Generation 3: Nash/ICM

### 4.1 ModNashICMv7 — SNG endgame
- ICM equity + simplified Nash equilibrium for push/fold
- Iterative best-response computation
- **Rust status:** ❌ Not ported

### 4.2 KEHU20BBNeqV3 — HU precomputed Nash tables
- 20BB and 15BB depth Nash solutions in CSV
- **Rust status:** ❌ Not ported (tables not converted)

### 4.3 PushOrFoldStrategyV3 — SNG/MTT endgame
- Chart-based push/fold, position × hand range
- **Rust status:** ❌ Not ported

---

## 5. Generation 4: Opponent Modelling

### 5.1 PlayerModelV3
- DB-backed opponent statistics (VPIP, PFR, AF, etc.)
- **Rust plan:** In-memory `HashMap<PlayerId, OpponentStats>`
- **Rust status:** ❌ Not ported

### 5.2 RangePredictor
- Predicts opponent hand range from observed actions
- **Rust status:** ❌ Not ported

### 5.3 CustomModNGV2 — Most advanced Java bot
- 10 sub-strategies in FirstApplicable order
- **Rust status:** ❌ Not ported (the assembly mechanism)

---

## 6. Configuration via Preferences

Java uses `java.util.prefs.Preferences` — hierarchical key-value store.
Rust replacement: **TOML configuration files**.

### Key Thresholds (Java defaults):

**RingNLStrategyV1:**
| Key | Default |
|-----|---------|
| `flop.strong_threshold` | 0.80 |
| `flop.good_threshold` | 0.60 |
| `flop.marginal_threshold` | 0.40 |
| `turn.strong_threshold` | 0.75 |
| `aggression.ip_bonus` | 0.03 |
| `aggression.cbet_threshold` | 0.35 |
| `aggression.multiway_penalty` | 0.05 |

**ModNashICMv7:**
| Key | Default |
|-----|---------|
| `maxOpponents` | 8 |
| `icmSteps` | 100 |
| `nashIterations` | 50 |
| `stackThreshold` | 15 |

---

## 7. Data Files (Not Converted)

| Java File | Description | Rust Plan |
|-----------|-------------|-----------|
| `math/hand_equity_169.dat` | 169×169 equity matrix | `include_bytes!()` or generated const |
| `math/huneq/hu_20bb_sb.csv` | HU Nash 20BB SB | Parse with `csv` crate |
| `math/huneq/hu_20bb_bb.csv` | HU Nash 20BB BB | Parse with `csv` crate |
| `math/huneq/hu_15bb_sb.csv` | HU Nash 15BB SB | Parse with `csv` crate |
| `math/huneq/hu_15bb_bb.csv` | HU Nash 15BB BB | Parse with `csv` crate |
| `math/push_fold_charts.dat` | Position push/fold ranges | Compile-time const or TOML |

---

## 8. Key Gaps Summary

1. **HandPotential not wired** — single highest-impact fix (upgrades Gen 1 → Gen 2)
2. **No tournament support** — no SNG, MTT, or ICM strategies
3. **No heads-up support** — no HU strategies or Nash tables
4. **No FL cash support** — no fixed-limit strategies
5. **No opponent modelling** — no PlayerModel, RangePredictor, or HandRange
6. **No configuration-driven assembly** — bots are hardcoded
7. **No bluff/lure modules** — no deceptive play capabilities

id: 77877dc0a2944e6c987df4d564393500
parent_id: 2c8da247905946c3aa19eb4936e16323
created_time: 2026-05-31T10:37:47.607Z
updated_time: 2026-05-31T10:54:50.073Z
is_conflict: 0
latitude: 0.00000000
longitude: 0.00000000
altitude: 0.0000
author: 
source_url: 
is_todo: 0
todo_due: 0
todo_completed: 0
source: joplin-desktop
source_application: net.cozic.joplin-desktop
application_data: 
order: 1780223867607
user_created_time: 2026-05-31T10:37:47.607Z
user_updated_time: 2026-05-31T10:54:50.073Z
encryption_cipher_text: 
encryption_applied: 0
markup_language: 1
is_shared: 0
share_id: 
conflict_original_id: 
master_key_id: 
user_data: 
deleted_time: 0
type_: 1