PokeR/openspec/changes/archive/2026-05-17-fix-texas-holdem-rules/design.md

Context

The current PokeR app implements Texas Hold'em poker but contains 10 critical bugs in its game flow logic. The core issues stem from three architectural problems: (1) ambiguous currentBet semantics that conflate "player contribution" with "bet matched," (2) lack of last-aggressor tracking for betting round completion, and (3) no side pot support for all-in scenarios. The hand evaluator and card systems are solid; the game orchestration layer needs complete reconstruction.

Goals / Non-Goals

Goals:

• Implement correct Texas Hold'em betting mechanics per official rules
• Fix all identified bugs without introducing new ones
• Support side pots for multi-player all-in scenarios
• Prevent race conditions between human input and AI turns
• Maintain existing Svelte 5 runes-based architecture and component structure

Non-Goals:

• Adding new game variants (Omaha, Stud, etc.)
• Implementing GTO or strategic AI improvements
• Multiplayer networking
• Educational features (pot odds, hand ranges)
• UI/visual redesign

Decisions

Decision 1: Separate betMatched flag from currentBet

Current: PlayerSeat.currentBet serves dual purpose — tracks actual chips contributed AND whether player has matched the current bet level. This causes applyCheck to corrupt state by setting currentBet = state.currentBet.

Decision: Add explicit betMatched: boolean field to PlayerSeat. currentBet becomes purely "chips contributed this round." Check simply sets betMatched = true without modifying chip counts.

PlayerSeat {
  // ... existing fields
  currentBet: number    // actual chips contributed this round
  betMatched: boolean   // has player matched or checked this round?
}

Rationale: Eliminates the fundamental semantic confusion that causes cascading bugs. Call amount becomes state.currentBet - player.currentBet with no corruption from check actions.

Decision 2: Last-aggressor betting round completion

Current: completeBettingRound checks if all active players have currentBet >= currentMaxBet. This fails when all-in players are included and doesn't handle the "return to last aggressor" rule.

Decision: Track lastAggressorIndex in GameState. A betting round ends when:

• Action returns to lastAggressorIndex AND that player has matched, OR
• All active (non-all-in) players have betMatched = true, OR
• Only one active player remains

// Round completion logic
function isRoundComplete(state): boolean {
  const activePlayers = state.players.filter(p => p.status === 'active');
  
  // Single active player — round over
  if (activePlayers.length <= 1) return true;
  
  // No raises occurred — everyone checked/called
  if (state.lastAggressorIndex === -1) {
    return activePlayers.every(p => p.betMatched);
  }
  
  // Raises occurred — must return to last aggressor who matches
  const lastAgg = state.players[state.lastAggressorIndex];
  return lastAgg.status === 'active' && 
         state.currentTurn === state.lastAggressorIndex && 
         lastAgg.betMatched;
}

Rationale: Texas Hold'em rules require action to return to the last aggressor. This is the standard implementation pattern used by poker software.

Decision 3: Side pot algorithm

Current: No side pot support. All chips go into a single pot, causing incorrect distributions when players go all-in at different levels.

Decision: Implement standard side pot calculation:

1. Sort all-in players by their bet amount (ascending)
2. Create pots from bottom up — each pot contains chips above the next lower all-in level
3. Track which players are eligible for each pot (active or all-in at that level or above)

SidePot {
  amount: number
  eligiblePlayerIds: string[]
}

// Algorithm sketch:
function calculatePots(players, currentPot): { mainPot: number, sidePots: SidePot[] }
  // Sort players by bet amount
  // Create nested pots from smallest all-in to largest
  // Main pot = chips matched by all remaining active/all-in players

Rationale: Standard poker software approach. Keeps implementation clean and matches real-world rules exactly.

Decision 4: Unified game state machine in +page.svelte

Current: processGame() has complex branching logic with async AI turns, state discarding, and multiple exit paths. Race conditions occur when human actions interrupt AI chains.

Decision: Replace with a clear state machine pattern:

• aiActing: boolean flag disables controls during AI turns
• Single processTurn() function handles all post-action processing
• State transitions are always applied atomically (gameState = newState)
• AI turns use sequential promise chains, not nested timeouts

function processTurn() {
  // 1. Check for early win (single active player)
  // 2. Check if betting round is complete
  // 3. If complete: advance to next stage or showdown
  // 4. If not complete: check if next player is AI, schedule turn
}

// In handleAction:
if (aiActing) return;  // Guard against race conditions
gameState = applyAction(gameState, action);
processTurn();

Rationale: Eliminates race conditions and state discarding bugs. Single source of truth for game flow logic.

Decision 5: Validation enforcement

Current: validateAction exists but is never called by applyRaise, applyFold, etc. The AI and human actions bypass validation entirely.

Decision: All action functions call validateAction internally and return unchanged state on invalid actions. The UI layer also validates before rendering buttons.

function applyRaise(state, playerId, amount) {
  const validation = validateAction(playerId, 'raise', amount, state);
  if (!validation.valid) return state;
  // ... proceed with raise logic
}

Rationale: Defense in depth — both the action layer and UI layer enforce rules. Prevents illegal states from being created.

Risks / Trade-offs

[Side pot complexity] → Side pots add significant complexity to showdown logic. Mitigation: Thoroughly test with edge cases (2 all-ins, 3 all-ins, all-in on flop/turn/river).

[State expansion] → Adding betMatched, lastAggressorIndex, and sidePots to GameState increases mutation surface. Mitigation: Use immutable state updates consistently, reset all fields in startNewHand.

[AI timing changes] → Switching from nested timeouts to promise chains changes AI behavior timing. Mitigation: Keep 400ms delay per AI action for consistent feel.

[Performance] → Side pot calculation at showdown could be expensive with many players. Mitigation: 6-max table limits complexity; algorithm is O(n log n) with n ≤ 6.

[currentTurn deadlock] → completeBettingRound originally set currentTurn = dealerPosition + 1, which could land on a folded/all-in player, causing an infinite loop in the game state machine. Fixed by using findFirstActivePlayer() to always point to an active player.

Open Questions

• Should we implement burn cards (standard in real poker, currently not implemented)?
• How should all-in raises that don't constitute a full raise be handled (half-pot rule)?
• Should the BB option (BB can check pre-flop if no raise) be explicitly documented in the UI?