v2.2.0: add blackjack with reserved bets and hit/stand/double

2 files changed, 46 insertions, 9 deletions

diff --git a/docs/GAMES.md b/docs/GAMES.md
index 12b0e7c..4c42369 100644
--- a/docs/GAMES.md
+++ b/docs/GAMES.md
@@ -6,17 +6,36 @@
 | --- | --- | --- |
 | Slots | Done | 5 reels x 3 rows, 5 paylines, 98.6% RTP |
 | Roulette | Done | European wheel, split bets, 97.3% RTP |
+| Blackjack | Done | Six-deck shoe per hand, S17, 3:2, hit/stand/double |
 
 ## Planned
 
 | Game | Shape | Main open decisions |
 | --- | --- | --- |
-| Blackjack | Multi-step hand | Dealer hits/stands soft 17; double/split/insurance; blackjack payout; shoe persistence |
 | Crash | Real-time round | Crash-point distribution; cashout latency; provable fairness |
 
-Blackjack needs server-side hand state and player actions. Crash needs a timed
-round loop and a cashout action, so it should come after blackjack unless we
-redesign the loop first.
+Crash needs a timed round loop and a cashout action, so it should be its own
+protocol/loop change.
+
+## Blackjack
+
+- Six-deck shoe, shuffled fresh for every hand and discarded afterwards.
+- Dealer stands on all 17s (including soft 17).
+- Blackjack pays 3:2, rounded down to whole PLN.
+- Hit, stand, and double; no split, insurance, or surrender.
+- The bet is reserved when the hand starts. Cancel or disconnect refunds it.
+- A natural or dealer blackjack settles immediately.
+
+Client controls:
+
+```
+H       hit
+S       stand
+D       double (on the first two cards)
+SPACE   deal the next hand
++ or = / -  change the next hand's bet
+Q       leave the table (active hand is cancelled and refunded)
+```
 
 ## Roulette
 
@@ -68,6 +87,9 @@ plays (
 
 // roulette
 {"number":"17","color":"black","bets":"{\"red\":10,\"black\":10,\"even\":10,\"odd\":10,\"numbers\":[{\"number\":17,\"amount\":5}]}"}
+
+// blackjack
+{"player":["10S","6H","5D"],"dealer":["9D","8C"],"player_total":21,"dealer_total":17,"bet":10,"result":"win","winnings":20}
 ```
 
 The balance update and the `plays` insert happen in one transaction
@@ -89,12 +111,14 @@ PLAY_START roulette <total> <bets-json>
 ROULETTE_RESULT <session> <winnings> <bet> <balance> <number> <color> <bets-json>
 ```
 
-Blackjack and crash still need a generic state/action exchange, for example:
+Blackjack is a multi-step session:
 
 ```
-GAME_START <game> <bet>
-GAME_ACTION <action> [json]
-GAME_STATE <json>          # cards, bets, multiplier, legal actions, result
+PLAY_START blackjack <bet>
+BLACKJACK_STATE <json>
+BLACKJACK_ACTION <session> hit|stand|double|cancel
+BLACKJACK_STATE <json>
 ```
 
-That will be its own protocol change.
+`BLACKJACK_STATE` carries the player/dealer cards, totals, actions, balance,
+result and winnings. The dealer's hole card is `?` until the hand is done.
diff --git a/docs/TESTING.md b/docs/TESTING.md
index d944b42..ed2f746 100644
--- a/docs/TESTING.md
+++ b/docs/TESTING.md
@@ -13,6 +13,7 @@ shared global database. Each test owns its state.
 | --- | --- |
 | `tests/client_core.rs` | Client command/game flows via a headless screen applying logical effects. |
 | `tests/client_ui.rs` | Help, history, completion, bet parsing, display width, cursor math. |
+| `tests/blackjack.rs` | Card totals, naturals, hit/stand/double, dealer bust, S17, state parsing. |
 | `tests/protocol.rs` | Newline buffering and timeout/error classification. |
 | `tests/roulette.rs` | European wheel, split-bet payouts, zero handling, result parser. |
 | `tests/server_core.rs` | Handler, bcrypt migration, SQL injection, transaction rollback, `plays` audit, sessions. |
@@ -79,6 +80,18 @@ Use an 80-column terminal because several output lines are width-sensitive.
 6. The result board shows the winning number/color/parity, the payout, and the
    new balance. The next spin reuses the placed bets.
 
+## Manual blackjack checklist
+
+1. `play blackjack` shows the ready board; Space deals.
+2. The dealer's hole card is hidden while it is the player's turn. H/S/D work;
+   D is only offered on the first two cards and reserves the extra bet.
+3. Stand and check the dealer stands on all 17s. Check a dealer bust pays the
+   player, and a natural blackjack pays 3:2.
+4. Q during a hand sends cancel and refunds the reserved bet; Q after a hand
+   just leaves. Disconnecting mid-hand also refunds it.
+5. Check the audit row: `game_type = blackjack`, the total bet (including a
+   double), winnings, and the final cards/result in `details`.
+
 ## Manual server checks
 
 - Register, log out, log in again (bcrypt path).