testsAndMisc/poker-stakes/src/ui/useGame.ts
Krzysztof kuhy Rudnicki 72a5e28456 Track poker-stakes so the file-length cap can reach it
The directory has existed on disk with 58 untracked files, four of them over
the 250-line cap. An untracked file is invisible to every pre-commit hook, so
those violations could not be fixed or gated while it stayed that way -- and
its CI workflow was untracked too, so nothing ran against it.

Landed with its already-written evidence artifact and a contract, since this
crosses the 4-file threshold.

Verified before staging: 58 plain text source/config files, no binaries, no
node_modules, no build output. npm run check passes -- typecheck, eslint
--max-warnings 0, and 220 tests at 100% statements/branches/functions/lines.

Splitting its four oversized files is deliberately a separate commit.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011w2Pj4Ek3ZNMQVYcFHgXDY
2026-08-16 15:19:07 +02:00

269 lines
12 KiB
TypeScript

import { useCallback, useReducer, useRef } from 'react'
import type { Action as PokerAction } from '../engine/bettingRound'
import type { HandResult, HandStep } from '../engine/handFlow'
import type { InteractiveHand } from '../engine/interactiveHand'
import { startInteractiveHand } from '../engine/interactiveHand'
import { createRng } from '../engine/rng'
import type { Rng } from '../engine/rng'
import { applyHandResult, cashOutSession, deriveBlindSize, startSession } from '../engine/session'
import type { SessionState } from '../engine/session'
import { settleSession } from '../stakes/settlement'
import { loadDebts, saveDebts } from '../stakes/storage'
import type { DebtLoad } from '../stakes/storage'
import type { BuyIn, SettledDebt } from '../stakes/types'
/** XORed into the deal seed for the opponent's independent policy RNG, per the spec's seam. */
const POLICY_SEED_SALT = 0x9e3779b9
const OPPONENT_ITERATIONS = 200
/**
* Only meaningful while `session !== null`. `betweenHands` is a real, UI-visible pause point — no
* hand is in progress, `session.stacks` is trustworthy, and `cashOut` is only ever legal here. A
* hand result stays visible (`lastResult`) until the next hand actually starts, so HandLog has
* something to render. This is deliberately NOT auto-advanced past by `submitPlayerAction` — see
* `dealHand` below for why cash-out mid-hand would be a settlement exploit if it were.
*/
export type HandPhase = { kind: 'awaiting'; step: HandStep } | { kind: 'betweenHands'; lastResult: HandResult | null }
export interface GameState {
debtLoad: DebtLoad
buyIn: BuyIn | null
session: SessionState | null
handPhase: HandPhase | null
}
type GameAction =
| { type: 'buyIn'; buyIn: BuyIn; session: SessionState }
| { type: 'handPhaseChanged'; session: SessionState; handPhase: HandPhase }
| { type: 'cashedOut'; session: SessionState }
| { type: 'debtSettled'; debts: SettledDebt[] }
| { type: 'debtProgressLogged'; debts: SettledDebt[] }
const initialGameState: GameState = {
debtLoad: { status: 'ok', debts: [] },
buyIn: null,
session: null,
handPhase: null,
}
/**
* Pure state transitions. All randomness/ids/clock reads happen in the hook, never in here.
* `GameAction` is exhaustively handled — TS errors on a missing case instead of a silent
* fallthrough, which is why there is no `default` branch.
*/
export const gameReducer = (state: GameState, action: GameAction): GameState => {
switch (action.type) {
case 'buyIn':
return { ...state, buyIn: action.buyIn, session: action.session, handPhase: null }
case 'handPhaseChanged':
return { ...state, session: action.session, handPhase: action.handPhase }
case 'cashedOut':
return { ...state, session: action.session }
case 'debtSettled':
return {
...state,
debtLoad: { status: 'ok', debts: action.debts },
buyIn: null,
session: null,
handPhase: null,
}
case 'debtProgressLogged':
return { ...state, debtLoad: { status: 'ok', debts: action.debts } }
}
}
/** An unpaid debt (owedUnits not yet fully paid) blocks starting a new session — a hard gate. */
export const hasOutstandingDebt = (debtLoad: DebtLoad): boolean =>
debtLoad.status === 'unreadable' || debtLoad.debts.some((d) => d.paidUnits < d.owedUnits)
export interface UseGameResult {
state: GameState
buyIn: (buyIn: BuyIn) => void
dealHand: () => void
submitPlayerAction: (action: PokerAction) => void
cashOut: () => void
logDebtProgress: (debtId: string, units: number) => void
}
/** Computed once via lazy init on both `useReducer` and `useRef` below — pure given `storage`. */
const readInitialDebts = (debtLoad: DebtLoad): SettledDebt[] => (debtLoad.status === 'ok' ? debtLoad.debts : [])
export const useGame = (storage: Storage, dealSeed: number): UseGameResult => {
const [state, dispatch] = useReducer(gameReducer, initialGameState, (): GameState => ({
...initialGameState,
debtLoad: loadDebts(storage),
}))
const handRef = useRef<InteractiveHand | null>(null)
const dealRngRef = useRef<Rng>(createRng(dealSeed))
const policyRngRef = useRef<Rng>(createRng(dealSeed ^ POLICY_SEED_SALT))
const sessionRef = useRef<SessionState | null>(null)
const buyInRef = useRef<BuyIn | null>(null)
// Authoritative debt list, independent of render state, so an unreadable-storage snapshot in
// `state.debtLoad` can never cause a settle to silently drop existing debts (fail-open bug).
// `useRef`'s initial-value argument is evaluated on every render (only the first is kept), so
// this and `storageUnreadableRef` below both see the same `loadDebts(storage)` read `state`'s
// own lazy initializer used — no separate read, no risk of the two disagreeing.
const debtsRef = useRef<SettledDebt[]>(readInitialDebts(loadDebts(storage)))
// Sticky: unreadable at load blocks buyIn for the lifetime of this hook instance, even though
// `debtsRef` itself only ever holds `SettledDebt[]` (never a nullable/unreadable marker) — this
// is what lets `buyIn`'s gate see 'unreadable' without a helper that collapses it to `[]` first
// (the exact bug this session's review caught: silently unblocking the gate).
const storageUnreadableRef = useRef<boolean>(loadDebts(storage).status !== 'ok')
const persistDebts = useCallback(
(debts: SettledDebt[]): SettledDebt[] => {
debtsRef.current = debts
saveDebts(storage, debts)
return debts
},
[storage],
)
const settleAndPersist = useCallback(
// Caller (dealHand / cashOut) guarantees `session.outcome` is non-null and `buyInSnapshot` is
// the live buy-in; not re-guarded here.
(session: SessionState & { outcome: NonNullable<SessionState['outcome']> }, buyInSnapshot: BuyIn): void => {
const debt = settleSession(buyInSnapshot, session.outcome, crypto.randomUUID(), Date.now())
const nextDebts = persistDebts([...debtsRef.current, debt])
handRef.current = null
buyInRef.current = null
sessionRef.current = null
dispatch({ type: 'debtSettled', debts: nextDebts })
},
[persistDebts],
)
/**
* Deals one hand. In the rare case a seat is already all-in from posting a blind (stack ≤
* blind size), the hand can complete with ZERO player decision points — `startInteractiveHand`
* resolves every opponent turn internally and returns already `complete`. That result is folded
* into the session immediately (not left for a UI round-trip that would never come), and either
* settles the session or lands in `betweenHands` so the caller can deal again.
*/
const dealHand = useCallback((): void => {
const session = sessionRef.current
const buyInSnapshot = buyInRef.current
// Reachable only if called with no live session (before any buy-in, or after settlement) —
// the UI only exposes this action while `handPhase.kind === 'betweenHands'`.
if (session === null || buyInSnapshot === null) {
return
}
const { bigBlind, smallBlind } = deriveBlindSize(buyInSnapshot.chips)
const hand = startInteractiveHand(
dealRngRef.current,
policyRngRef.current,
{ buttonSeat: session.buttonSeat, bigBlind, smallBlind, stacks: session.stacks },
OPPONENT_ITERATIONS,
)
const status = hand.status
if (status.kind === 'awaiting') {
handRef.current = hand
dispatch({ type: 'handPhaseChanged', session, handPhase: { kind: 'awaiting', step: status.step } })
return
}
const nextSession = applyHandResult(session, status.result)
sessionRef.current = nextSession
if (nextSession.outcome !== null) {
settleAndPersist({ ...nextSession, outcome: nextSession.outcome }, buyInSnapshot)
return
}
dispatch({
type: 'handPhaseChanged',
session: nextSession,
handPhase: { kind: 'betweenHands', lastResult: status.result },
})
}, [settleAndPersist])
const buyIn = useCallback(
(nextBuyIn: BuyIn): void => {
// Hard gate: an outstanding debt blocks starting a new session, per the confirmed stakes
// model — never just a UI-level warning. Chips are integers throughout (per the plan), so a
// non-positive or fractional buy-in is rejected here too, not just via an input `min`/`step`.
if (
storageUnreadableRef.current ||
hasOutstandingDebt({ status: 'ok', debts: debtsRef.current }) ||
!Number.isInteger(nextBuyIn.chips) ||
nextBuyIn.chips <= 0
) {
return
}
const session = startSession({ buyInChips: nextBuyIn.chips })
buyInRef.current = nextBuyIn
sessionRef.current = session
dispatch({ type: 'buyIn', buyIn: nextBuyIn, session })
dealHand()
},
[dealHand],
)
const submitPlayerAction = useCallback(
(action: PokerAction): void => {
const hand = handRef.current
const session = sessionRef.current
const buyInSnapshot = buyInRef.current
// Reachable only via a submit before any buy-in — `hand.submit` itself throws if no
// decision is pending, which per this session's review is otherwise unreachable: `dealHand`
// never leaves `handRef` holding an already-`complete` hand.
if (hand === null || session === null || buyInSnapshot === null) {
return
}
hand.submit(action)
const status = hand.status
if (status.kind === 'awaiting') {
dispatch({ type: 'handPhaseChanged', session, handPhase: { kind: 'awaiting', step: status.step } })
return
}
// Hand resolved. Land in `betweenHands` — do NOT auto-deal the next hand: `session.stacks`
// must reflect a just-completed hand so `cashOut` (only legal in `betweenHands`) settles
// against real chips, and mid-hand cash-out would let a player see a bad flop, cash out at
// the PRE-hand stack, and have the posted blinds/bets vanish with the discarded generator.
handRef.current = null
const nextSession = applyHandResult(session, status.result)
sessionRef.current = nextSession
if (nextSession.outcome !== null) {
settleAndPersist({ ...nextSession, outcome: nextSession.outcome }, buyInSnapshot)
return
}
dispatch({
type: 'handPhaseChanged',
session: nextSession,
handPhase: { kind: 'betweenHands', lastResult: status.result },
})
},
[settleAndPersist],
)
const cashOut = useCallback((): void => {
const session = sessionRef.current
const buyInSnapshot = buyInRef.current
// Only legal between hands: `handRef.current !== null` means a hand is in progress, and
// mid-hand `session.stacks` predates that hand's blinds/bets — cashing out then would settle
// against a stale stack and let a player see the deal before deciding to cash out. handRef is
// read (a synchronous ref) rather than `state.handPhase` (React state) because this guard is
// security-critical: it must reflect what actually happened, not what has rendered yet.
if (session?.outcome !== null || buyInSnapshot === null || handRef.current !== null) {
return
}
const nextSession = cashOutSession(session)
sessionRef.current = nextSession
dispatch({ type: 'cashedOut', session: nextSession })
// cashOutSession always sets outcome, so this cast just restates that fact for the type.
settleAndPersist(nextSession as SessionState & { outcome: NonNullable<SessionState['outcome']> }, buyInSnapshot)
}, [settleAndPersist])
const logDebtProgress = useCallback(
(debtId: string, units: number): void => {
const nextDebts = debtsRef.current.map((d) =>
d.id === debtId ? { ...d, paidUnits: Math.min(d.owedUnits, d.paidUnits + units) } : d,
)
persistDebts(nextDebts)
dispatch({ type: 'debtProgressLogged', debts: nextDebts })
},
[persistDebts],
)
return { state, buyIn, dealHand, submitPlayerAction, cashOut, logDebtProgress }
}