> ## Documentation Index
> Fetch the complete documentation index at: https://hedgeem-api.qeetoto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# F005 — Hand Evaluation

## Business Rule

At the RIVER stage, every hand is evaluated against the 5 community cards to produce a standard Texas Hold'em hand ranking. The hand with the highest ranking wins.

The 10 valid hand rankings (highest to lowest):

| Rank | Name            |
| ---- | --------------- |
| 1    | Royal Flush     |
| 2    | Straight Flush  |
| 3    | Four of a Kind  |
| 4    | Full House      |
| 5    | Flush           |
| 6    | Straight        |
| 7    | Three of a Kind |
| 8    | Two Pair        |
| 9    | Pair            |
| 10   | High Card       |

Evaluation is performed server-side by the poker hand evaluator (node-poker-odds-calculator / pokersolver). The client receives pre-computed `handName` and `handStatus` per hand in the API response at STATUS\_RIVER.

***

## Technical Design

### API response (STATUS\_RIVER)

Each entry in `handOdds[]` contains:

```json theme={null}
{
  "handName":   "Full House",
  "handStatus": "IN_PLAY_WINNER"
}
```

* `handName` — pokersolver hand classification string (one of the 10 rankings above)
* `handStatus` — `"IN_PLAY_WINNER"` for the winning hand, `"IN_PLAY"` for losers

### UMA client state bridge

`platform.js` builds a debug array at RIVER and exposes it for Playwright assertions:

```javascript theme={null}
window._winnerInfo = [
  {
    handIndex: 0,
    isWinner:  true,
    handName:  'Full House',   // from API handOdds[i].handName
    prizeId:   'full_house',   // mapped via HAND_NAME_TO_PRIZE_ID
    winAmount: 300,            // pence
    multiplier: 3.0,
  },
  // ... one entry per hand
];
```

### handName → prizeId mapping

| handName        | prizeId            |
| --------------- | ------------------ |
| Royal Flush     | royal\_flush       |
| Straight Flush  | straight\_flush    |
| Four of a Kind  | four\_of\_a\_kind  |
| Full House      | full\_house        |
| Flush           | flush              |
| Straight        | straight           |
| Three of a Kind | three\_of\_a\_kind |
| Two Pair        | two\_pairs         |
| Pair            | pair               |
| High Card       | high\_card         |

The GDK uses `prizeId` to trigger the win animation and display the hand name banner.

***

## Acceptance Criteria

* **AC1** — At RIVER, `_winnerInfo` is defined and contains exactly one entry per hand (length equals `_holeCards.length`)
* **AC2** — Every hand in `_winnerInfo` has a valid `handName` (one of the 10 standard poker rankings)
* **AC3** — Exactly one hand has `isWinner === true`
* **AC4** — The winning hand has the highest (or tied-highest) poker hand rank among all hands
* **AC5** — The winning hand's `prizeId` correctly maps to its `handName` (e.g. `'Full House'` → `'full_house'`)

***

## Version Parity

| Version    | Status            | Notes                                                                     |
| ---------- | ----------------- | ------------------------------------------------------------------------- |
| JavaScript | ⬜ Not yet audited | Evaluation server-side; client reads pre-computed values                  |
| TypeScript | ⬜ Not yet audited | `GameEngine` reads `handName` from coredata/API                           |
| UMA        | ✅ Verified        | `tests/features/F005-hand-evaluation.spec.ts` — AC1–AC5 pass (2026-04-15) |

***

## Known Discrepancies

None documented yet.

***

## Test Coverage

Playwright spec: `tests/features/F005-hand-evaluation.spec.ts` — AC1–AC5.

Run with:

```bash theme={null}
VERSION=uma npx playwright test tests/features/F005-hand-evaluation.spec.ts --project=features --workers=1
```