Add Omaha/PLO foundation: hand type, 2+3 evaluator, equity (Phase 1)

[testtest126]

Summary — Phase 1 of the variants/PLO track

• OmahaHoleCards: the 4-card hand type, added alongside HoleCards — no existing NLHE model (ChenScore, every range model, Equity, ICM, GameFormat) reads or is affected by this type's existence. Canonical (order-independent) storage; explicit per-card notation ("AsKsAhKh") rather than an invented Hold'em-style shorthand — Omaha has no standardized compact notation the way "AKs"/"AKo" is standardized, and inventing one would be exactly the kind of judgment call this phase avoided.
• OmahaHandEvaluator: enforces Omaha's defining rule — best 5-card hand uses exactly 2 of 4 hole cards + exactly 3 of 5 board cards. Enumerates all 60 legal combinations via the existing, unmodified HandEvaluator.bestHand(from:). Tests specifically prove the constraint is enforced (not just assumed): a four-aces hole hand that would look like quads/trips if the cap were ignored (must be exactly a pair), a four-spades hole hand that would look like a royal flush with only 1 board spade available (must be High Card), plus a positive counterpart proving a legal straight flush is still found when the split genuinely allows one.
• OmahaEquity: same exact/Monte Carlo shape as Equity, built on the legal evaluator. No preflop exact (≈2x Hold'em's already-slow preflop exact case — documented, never called).
• Minimal app screen (OmahaEquityCalculatorView, labeled "(Beta)"): explicit notation in/out, Fast/Precise modes, wired into StudyTool.

Validation — actual vs. published, and the hand-verifiable fallback

No single citable source with a precisely-stated PLO equity figure and fully-specified matchup was found (web search surfaced AAKK-vs-random figures ranging 64–73% depending on source, too wide a spread to validate a decimal against per this project's "a bad number is worse than none" rule). What was consistently repeated across independent sources (e.g. pokerlistings.com's "Pot-Limit Omaha: Top 30 Starting Hands"): AA-KK double-suited is only a 3-2 favorite (~60%) over a strong double-suited rundown like 8-7-6-5.

AAKKds ("AsKsAhKh") vs 8765ds ("8s7s6h5h"), 50,000 Monte Carlo iterations
  → win 61.96%, tie 0.00%, lose 38.04%

61.96% lands within 2 points of the cited ~60%.

Per this project's own fallback rule (pick a hand-verifiable spot when no solid citation exists), two exact tests carry the real correctness weight:

• Hero holds the board's missing pair (locked quad sevens) vs. a villain with none of that rank → winRate == 1.0 exactly, provable by hand.
• Mirrored-suit hands (same 4 ranks, different suits) on a suit-neutral board → tieRate == 1.0 exactly, a tie by symmetry, not coincidence.

What went wrong along the way (and got fixed at the root, not worked around)

• A UI test intermittently failed with "Finish setting the board" even after the board notation was correctly typed. Root-caused via a debug print showing the board field's value had gained a stray trailing character — the Calculate button's tap was actually landing on the still-open keyboard underneath it, not the button. Fixed by properly dismissing the keyboard (typing a newline) before the next interaction, not by padding timeouts.
• Separately found (and documented, not just tolerated): Omaha's flop-exact mode measured close to, and once over, a 30s timeout on a debug simulator build — meaningfully slower than Hold'em's own flop-exact (120 vs. 42 evaluations per board). The app's Precise mode still allows it (it does complete), but the UI test that proves Precise mode works uses a river-given board specifically so it isn't a flaky benchmark of that timing.

Test plan

• swift test (PokerKit): 263/263 green (235 baseline + 28 new Omaha tests).
• App build succeeds on simulator (iPhone 17, iOS 27.0, Xcode 27 beta).
• App UI test suite: 26/26 green (excludes BankrollTrackerUITests.testLogSessionUpdatesListAndSummary, previously confirmed pre-existing/flaky on a clean main checkout, unrelated to this branch).
• New OmahaHoleCardsTests, OmahaHandEvaluatorTests, OmahaEquityTests, OmahaEquityCalculatorUITests.

Proposed Phase 2 scope

PLO preflop hand-strength / starting-hand ranges — deliberately not started here. This is judgment-heavy in a way Phase 1 wasn't: Chen's heuristic doesn't extend to 4 cards, and the Omaha hand-strength heuristics that do exist in strategy literature are themselves competing/disputed, not an agreed standard the way Chen's is for Hold'em. Proposed approach (see ai-docs/OMAHA.md's "What Phase 2 should be" section): use OmahaEquity.monteCarlo equity-vs-random-hand itself as the ranking signal (this project's own exact math, not a second borrowed heuristic), validate it directionally against known strong/weak Omaha hands, then build push/fold-style thresholds on top with every percentage flagged as hand-tuned — same posture RANGES.md already takes for Hold'em.

🤖 Generated with Claude Code