poker-flopsolve 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,464 @@
1
- # Temporary Holding Version
1
+ # poker-flopsolve
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A **postflop Texas Hold'em solver**. Give it a board, a pot, stacks, two ranges and a
4
+ betting scheme; it solves to showdown.
5
+
6
+ There is no preflop round. The ranges you supply already encode whatever spot you are in,
7
+ so the solver starts from a dead pot with both players even.
8
+
9
+ ```bash
10
+ npm install poker-flopsolve
11
+ ```
12
+
13
+ ```ts
14
+ import { defineSpot, solve } from 'poker-flopsolve';
15
+
16
+ const spot = defineSpot({
17
+ board: 'As Kh 7d 2c', // 3, 4 or 5 cards
18
+ pot: 60,
19
+ stack: 120, // effective, behind, per player
20
+ oop: '22+,A2s+,K9s+,AJo+', // acts first on every street
21
+ ip: '22+,A8s+,KTs+,ATo+',
22
+ betSizes: [[0.5, 1.0]], // pot fractions; one row per round, or one for all
23
+ maxRaises: 1,
24
+ });
25
+
26
+ const sol = solve(spot, { iterations: 500 });
27
+
28
+ sol.ev(0); // chips per hand, out of position
29
+ sol.exploitabilityPercent(); // distance from equilibrium, % of pot
30
+ sol.strategyAt(node, board); // per-combination action frequencies
31
+ ```
32
+
33
+ ## Command line
34
+
35
+ ```bash
36
+ npm run solve -- --board "As Kh 7d 2c" --pot 60 --stack 120 \
37
+ --oop "22+,A2s+,K9s+,AJo+" --ip "22+,A8s+,KTs+,ATo+" \
38
+ --bet "0.5,1.0" --iters 500
39
+ ```
40
+
41
+ `--help` lists every flag.
42
+
43
+ ## Browser UI
44
+
45
+ ```bash
46
+ npm run ui # -> http://localhost:5174
47
+ ```
48
+
49
+ Pick a preset or type a spot, solve, then walk the betting tree and read the strategy as a
50
+ 13x13 rank matrix. Each cell splits horizontally into one column per individual combination
51
+ — six for a pair, four suited, twelve offsuit — and each column fills vertically with that
52
+ combination's own action mix. Nothing is averaged.
53
+
54
+ Column height is how often that combination actually reaches the node, so the grid shows
55
+ the range narrowing as you descend a line. A combination the board has taken leaves its
56
+ column empty. Hovering gives the exact frequencies and reach.
57
+
58
+ Nodes past a deal get a runout picker: step rivers with the arrow keys, or jump to one by
59
+ number. The line reaching the selected node is spelled out above the grid —
60
+ `OOP check → IP check → deal → OOP check → IP to act`.
61
+
62
+ Solving runs in its own worker thread, so progress streams and **Stop** ends early while
63
+ keeping the partial answer.
64
+
65
+ ## Ranges
66
+
67
+ ```
68
+ AA KK-99 22+ pairs, spans, and "and better"
69
+ AKs A2s+ A5s-A2s suited
70
+ AKo KTo+ offsuit
71
+ AK both
72
+ AsKh one exact combination
73
+ Ax AXs AXo any second card, optionally constrained
74
+ random everything
75
+ AKo:0.5 QQ:25% partial weights
76
+ ```
77
+
78
+ Weights matter: a solver range is routinely partial, and a later segment overrides an
79
+ earlier one, so `random:0.1, AA:1` is a light range that always has aces. `Xo` forms
80
+ include the pair, because a pair is not suited; `Xs` forms do not.
81
+
82
+ Board cards are removed from both ranges automatically.
83
+
84
+ ## Raise sizes
85
+
86
+ `betSizes` also size raises unless `raiseSizes` is given. A raise size can be a multiple of
87
+ the bet being faced, measured from what both players had in when the round opened:
88
+
89
+ ```ts
90
+ defineSpot({ ..., betSizes: [[0.5]], raiseSizes: [{ times: 3 }], maxRaises: 2 });
91
+ // bet 40 into 80, raise to 120
92
+ ```
93
+
94
+ ## Betting per round
95
+
96
+ `raiseSizes`, `maxRaises` and `allowAllIn` can each be given once for every round, or one
97
+ per round like `betSizes`. A shove can also be a round's only bet size:
98
+
99
+ ```ts
100
+ // Flop: one size, no raise. Turn: two sizes, one raise. River: shove or check.
101
+ defineSpot({ ..., board: 'Qs Jh 4d',
102
+ betSizes: [[0.33], [0.5, 1], ['allin']],
103
+ maxRaises: [1, 2, 1],
104
+ raiseSizes: [{ times: 3 }],
105
+ });
106
+ ```
107
+
108
+ A subgame keeps the rounds from its own onwards.
109
+
110
+ ### Trimming the tree
111
+
112
+ Tree size multiplies everything else, so three switches cut the lines that cost the most
113
+ for the least strategic difference. They change the game being solved — a trimmed tree
114
+ is a smaller game, solved exactly — so its exploitability is measured within that game.
115
+
116
+ - `allInThreshold: 0.67` — a bet committing two thirds or more of the remaining stack
117
+ becomes all-in.
118
+ - `noDonk: true` — out of position only checks into the previous street's aggressor.
119
+ - `mergeSizes: 0.1` — pot-fraction sizes closer than 0.1 collapse to their mean.
120
+
121
+ Each takes a value per round too. On a turn spot with four sizes, two raises and a shove
122
+ (`AsKh7d2c`, the bench ranges):
123
+
124
+ | | Decisions | Storage |
125
+ |---|---|---|
126
+ | As given | 244 | 34.9 MB |
127
+ | `allInThreshold: 0.67` | 152 | 20.6 MB |
128
+ | `noDonk: true` | 212 | 28.8 MB |
129
+ | `mergeSizes: 0.1` | 104 | 13.4 MB |
130
+ | All three | 66 | 7.9 MB |
131
+
132
+ Raise caps per round (`maxRaises: [1, 2, 1]`) and a checked-down river (an empty
133
+ `betSizes` row) were already available and trim the same way.
134
+
135
+ `minWeight: 0.05` trims the ranges the same way: combinations weighted under 5% are
136
+ dropped from both, which suits imported ranges full of hands at a percent or two.
137
+
138
+ ## Reading a solved spot
139
+
140
+ `createRun` returns the solver itself as `run.solver`, for analysis after (or between)
141
+ iterations, without changing anything:
142
+
143
+ - `solver.valuesAt(node, board, traverser, reachMe, reachOpp, live, liveCount)` gives the
144
+ traverser's counterfactual values from any node under the average strategy, for reach
145
+ vectors you choose. Values are linear in `reachOpp`, so a one-hot opponent reach gives
146
+ each hand's value against one specific opposing hand.
147
+ - `solver.pairValuesAt(node, board, traverser, hands, handReach, live, liveCount)` gives
148
+ the same as `valuesAt` with a one-hot opponent reach, for many opposing hands in one
149
+ walk: a row of values against each hand alone. Sharing the walk, the strategy lookups
150
+ and kernel-free terminals makes it about 3× faster than one `valuesAt` per hand on turns
151
+ and flops.
152
+ - `solver.exploitability()` is the best-response measure for whatever strategy sums the
153
+ solver holds.
154
+
155
+ `createRun(spot, { analysisOnly: true })` allocates only the strategy sums (single
156
+ precision, one thread, no regrets). Fill `run.solver.ctx.strategySum` from a saved or
157
+ modified strategy, then analyse it the same way. Such a run must never be stepped.
158
+
159
+ ## Warm starts
160
+
161
+ Re-solving a spot you just changed — another pot or stack, a nudged bet size, a reweighted
162
+ range — can start from the previous solve instead of from nothing:
163
+
164
+ ```ts
165
+ const first = solve(defineSpot(config), { targetPercent: 0.3 });
166
+ const next = solve(defineSpot({ ...config, pot: 72 }), { targetPercent: 0.3, warmStart: first });
167
+ next.totalIterations; // the inherited iterations plus its own
168
+ ```
169
+
170
+ Nothing becomes approximate: CFR converges from any start, and this one is close. Nodes
171
+ match by the actions leading to them (bet sizes to the nearest pot fraction), hands by
172
+ combination, and anything without a match starts cold; `run.warmStart` reports how much
173
+ matched. Regrets carry over; the average strategy only when the spot is the same, which
174
+ resumes a solve exactly. Measured on a river spot to 0.1% of pot:
175
+
176
+ | Change | From scratch | Warm |
177
+ |---|---|---|
178
+ | Bet size 0.75 → 0.8 pot | 130 iterations | 15 |
179
+ | Range reweighted | 130 | 80 |
180
+ | Stack 120 → 100 | 125 | 75 |
181
+ | Pot 60 → 72 | 125 | 100 |
182
+
183
+ ## Re-solving from a node
184
+
185
+ Solve the whole spot with a coarse tree, then re-solve the street you are looking at
186
+ with a rich one:
187
+
188
+ ```ts
189
+ const coarse = solve(defineSpot({ ...spot, betSizes: [[0.66]] }), { targetPercent: 0.5 });
190
+ const turn = defineSpot(coarse.subgameAt(node, board, { betSizes: [[0.33, 0.75, 1.25]], maxRaises: 2 }));
191
+ const detailed = solve(turn, { targetPercent: 0.3 });
192
+ ```
193
+
194
+ `solution.subgameAt(node, board, betting?)` returns the spot that starts at a node that
195
+ opens a betting round. It carries the board dealt there, the pot and stacks as they stand,
196
+ and each player's range as their reach there (`solution.reachAt`). Ranges accept these
197
+ per-combination weights as well as notation. Measured on the bench flop: the coarse flop
198
+ took 27 s and 150 MB with 3 threads. Each turn, re-solved with three sizes, two raises and
199
+ a shove, took about 7 s and 15 MB. The same rich tree solved from the flop would need
200
+ 1.9 GB.
201
+
202
+ On lines the original solution plays, a re-solve with the same betting reproduces its
203
+ value to four decimals. On lines it barely plays, the original strategy was never pushed
204
+ to equilibrium, because exploitability weights each line by how often it is reached. The
205
+ re-solve is the better answer there.
206
+
207
+ This is *unsafe* re-solving. The subgame is solved for the ranges that arrive, so its
208
+ strategy can be exploitable in ways the original allowed for. It also does not make the
209
+ earlier streets any more accurate than their coarse model of the future.
210
+
211
+ ## In a browser
212
+
213
+ The package also runs in a browser, for the small solves a page wants: river spots and
214
+ narrow turn spots. Bundlers pick the browser build (`dist/browser.js`) automatically
215
+ through the `browser` export condition. It is the same solver, single-threaded:
216
+
217
+ - no worker threads, so `workers` resolves to 1 (asking for more logs one warning);
218
+ - no `SharedArrayBuffer`, so the page needs no cross-origin isolation headers;
219
+ - `maxBytes` defaults to 512 MiB rather than 6 GiB, so a spot too big for a tab is
220
+ refused up front by `defineSpot` instead of taking the tab down.
221
+
222
+ A solve blocks the thread it runs on, so host it in a Web Worker and step it in chunks;
223
+ [`examples/browser-worker.ts`](examples/browser-worker.ts) does that with progress and a
224
+ stop message in about sixty lines. Flop spots and wide turn spots belong in Node, where
225
+ `workers` splits the runouts across cores.
226
+
227
+ `npm test` checks the browser build in headless Chromium against Node (skipped where
228
+ Playwright is not installed), and `npm run bench:browser` times it beside Node.
229
+
230
+ ## Performance
231
+
232
+ Measured on an Apple M2, single threaded:
233
+
234
+ | Entry | Ranges | Slots | Memory | Solve |
235
+ |---|---|---|---|---|
236
+ | River | 7 vs 6 | 52 | < 1 MB | 3,000 iters in 0.4 s |
237
+ | Turn | 165 vs 160 | 455k | 3.8 MB | 500 iters in 8 s |
238
+ | Flop | 27 vs 36 | 3.0M | 41 MB | 120 iters in 21 s |
239
+ | Flop | 211 vs 203 | 35.3M | 287 MB | 60 iters in 80 s |
240
+
241
+ `defineSpot` reports the projected cost before anything is allocated, and refuses a spot
242
+ over `maxBytes` with concrete suggestions. `maxCombos` caps range width.
243
+
244
+ ### SIMD kernels
245
+
246
+ Regret matching and the average-strategy pass — the per-hand normalisation at every
247
+ decision, about a third of the solve — run as WebAssembly SIMD kernels, two doubles per
248
+ instruction, in Node and in the browser alike. They are written in AssemblyScript
249
+ (`assembly/kernels.ts`) and embedded in `src/wasm/kernels.ts`, so nothing is fetched at
250
+ run time and only changing a kernel needs `npm run build:wasm`. Results are identical to
251
+ the JavaScript kernels to the last bit; `simd: false` uses those instead, and platforms
252
+ without WebAssembly SIMD fall back to them on their own (`simdAvailable()` says which).
253
+ Measured interleaved on the bench turn spot: iterations ~18% faster in Node and 16% in
254
+ Chromium, exploitability checks ~8%.
255
+
256
+ ### Mirrored runouts
257
+
258
+ When swapping suits leaves the board and both ranges unchanged, a deal in one of those
259
+ suits is the mirror image of a deal in another, and only one is solved. On a two-tone flop
260
+ the two absent suits are interchangeable; on a monotone flop, all three. This is exact —
261
+ the solver keeps mirrored hands' strategies tied together, so a stored runout stands for
262
+ its mirrors with nothing lost — and it is on by default (`isomorphism: false` turns it off).
263
+
264
+ | Flop, 4 threads | Runouts stored | To 0.3% of pot |
265
+ |---|---|---|
266
+ | Ts9s4h, two-tone | 1,429 of 2,352 | 16.3 s → 10.3 s |
267
+ | Ks9s4s, monotone | 675 of 2,352 | 16.2 s → 5.6 s |
268
+ | AhKdQc, rainbow | 2,352 of 2,352 | unchanged |
269
+
270
+ Board indices (`strategyAt`, `reachAt`, `subgameAt`, the UI's runout picker) count stored
271
+ runouts. To read a mirrored one, `spot.resolveBoard('Ts9s4h 7c')` gives the stored board
272
+ and how hands relabel onto it. Ranges that differ between suits anywhere — an exact combo,
273
+ or a partial weight on one suit — have no symmetry to use, and solve as before.
274
+
275
+ ### Runout buckets (approximate)
276
+
277
+ `runoutBuckets: true` solves one turn or river card for several that play alike: two cards
278
+ of one suit, neither pairing the board, equally connected to its straights, whose rank
279
+ swap maps both ranges onto themselves. The stored card stands for the others with hands
280
+ relabelled by the swap. A number instead of `true` is the widest rank gap allowed in a
281
+ bucket (`true` is 1, the most cautious).
282
+
283
+ It is an approximation — 55 on a 6 river and 66 on a 5 river sit on opposite sides of the
284
+ board card, and no relabelling fixes that — so `exploitabilityPercent()` (and
285
+ `targetPercent`) measure the bucketed game, and `run.trueExploitabilityPercent()` measures
286
+ the strategy in the real one, every card dealt. How much it saves and costs depends on
287
+ the ranges; suited connectors keep ranks apart, pocket pairs near the merged ranks cost
288
+ accuracy. On AhKdQc, 4 threads, to 0.3% of pot in the bucketed game:
289
+
290
+ | Ranges | Gap | Runouts | Time | True exploitability |
291
+ |---|---|---|---|---|
292
+ | Bench (wide, connectors) | exact | 2,352 | 13.2 s | 0.271% |
293
+ | | 1 | 1,672 | 10.5 s | 0.278% |
294
+ | | 3 | 1,348 | 8.0 s | 0.302% |
295
+ | Pairs and broadway | exact | 2,352 | 9.3 s | 0.228% |
296
+ | | 1 | 1,396 | 4.9 s | 0.482% |
297
+ | | 3 | 1,088 | 4.2 s | 0.542% |
298
+
299
+ ### 16-bit storage
300
+
301
+ A spot too big for 32-bit storage under `maxBytes` is solved at 16 bits instead
302
+ (`precision: 'i16'` forces it). Regrets and strategy sums are stored as 16-bit integers with
303
+ one scale per node and board, about halving memory. `estimate.compressedBytes` reports
304
+ that size, and a spot is refused only if even that exceeds `maxBytes`. Measured on AsKh7d:
305
+
306
+ | Flop | Ranges | 32-bit | 16-bit |
307
+ |---|---|---|---|
308
+ | 1 size, 1 raise | 198 vs 165 | 150 MB | 85 MB |
309
+ | 2 sizes, 1 raise | 198 vs 165 | 824 MB | 425 MB |
310
+ | 2 sizes, 1 raise | 309 vs 424 | 1,645 MB | 836 MB |
311
+ | 2 sizes, 2 raises | 309 vs 424 | 3,344 MB | 1,689 MB |
312
+
313
+ The 309 vs 424, two-size flop solved with two threads at a peak RSS of about 1.1 GB, so it
314
+ fits a 2 GB machine. It reaches each accuracy target in the same number of iterations as
315
+ 32-bit, but each iteration costs about 15–20% more, because every update re-encodes its
316
+ block. Strategy sums round up or down at random, weighted by the remainder: rounded to
317
+ nearest, small sums lose most of each iteration's contribution and exploitability stalls
318
+ near 0.04% of pot. The randomness is a hash of the slot and iteration, so solves stay
319
+ deterministic at any thread count.
320
+
321
+ ### Algorithm and benchmark
322
+
323
+ The default update rule is Discounted CFR (`algorithm: 'dcfr'`, α 1.5, β 0, γ 3, with
324
+ positive regret counted from the second iteration so the uniform first iteration is
325
+ forgotten). CFR+ is still available as `algorithm: 'cfr+'`. The table below predates the
326
+ 0.2.0 schedule, which needs 10–15% fewer iterations on flop and turn spots. `npm run bench` times a fixed river, turn, flop
327
+ and two-tone flop. Measured in a 4-core cloud container, seconds of solving to reach each
328
+ target (exploitability checks excluded):
329
+
330
+ | Spot | Threads | CFR+ to 1% | DCFR to 1% | CFR+ to 0.3% | DCFR to 0.3% |
331
+ |---|---|---|---|---|---|
332
+ | Turn, 12 MB | 1 | 7.1 s (82 it) | 4.5 s (53 it) | 14.1 s (170 it) | 7.9 s (95 it) |
333
+ | Flop, 150 MB | 1 | 49 s (46 it) | 36 s (34 it) | 101 s (95 it) | 64 s (61 it) |
334
+ | Flop, 150 MB | 3 | 23 s | 17 s | 45 s | 29 s |
335
+ | Two-tone flop, 162 MB | 3 | 19 s (34 it) | 16 s (29 it) | 38 s (71 it) | 28 s (53 it) |
336
+
337
+ The solver is compute-bound rather than memory-bound — a 150 MB flop streams its
338
+ accumulators at about 0.25 GB/s — so the cost of an iteration tracks the work in it, not
339
+ its bytes.
340
+
341
+ ### Compared with postflop-solver
342
+
343
+ `npm run bench:compare` runs the same spots through this solver and
344
+ [b-inary/postflop-solver](https://github.com/b-inary/postflop-solver) (Rust, built
345
+ natively for the machine) at the same 32-bit precision, thread count and checking
346
+ schedule. It needs a Rust toolchain; postflop-solver is fetched at build time and never
347
+ bundled. Measured in a 4-core cloud container, time to 0.3% of pot:
348
+
349
+ | Spot | Threads | poker-flopsolve | postflop-solver | Ratio |
350
+ |---|---|---|---|---|
351
+ | Turn | 1 | 4.0 s | 0.9 s | 4.2× |
352
+ | Flop | 1 | 81.3 s | 18.5 s | 4.4× |
353
+ | Monotone flop | 1 | 25.1 s | 5.3 s | 4.7× |
354
+ | Flop | 4 | 25.5 s | 5.3 s | 4.8× |
355
+ | Monotone flop | 4 | 8.2 s | 1.4 s | 5.8× |
356
+
357
+ postflop-solver is roughly four to six times faster: native Rust over dense f32 vectors
358
+ against JavaScript. Closing more of the gap means moving the traversal itself into
359
+ WebAssembly, which is the next piece of work.
360
+
361
+ ### Accuracy targets
362
+
363
+ `solve(spot, { targetPercent })` stops as soon as exploitability reaches that percentage of
364
+ the pot, making `iterations` a cap rather than a plan. This is the cheapest way to cut solve
365
+ time, because the last decimal place of accuracy costs most of the run:
366
+
367
+ | Target | Iterations | Time |
368
+ |---|---|---|
369
+ | 2% | 20 | 0.28 s |
370
+ | 1% | 24 | 0.26 s |
371
+ | 0.5% | 39 | 0.29 s |
372
+ | 0.25% | 57 | 0.35 s |
373
+ | 0.1% | 127 | 0.57 s |
374
+ | 0.05% | 200 | 0.73 s |
375
+ | none (500 iterations) | 500 | 1.43 s |
376
+
377
+ As a guide, 1% of pot is a sketch, 0.5% is enough to read strategies off, and 0.1% is
378
+ publishable. On the flop preset in the browser UI, a 0.5% target finishes in 2 s against an
379
+ estimated 24 s for the full iteration count.
380
+
381
+ Checking is not free: it is a full best-response pass for both players, about one
382
+ iteration's work, spread across the same threads as the solve. Rather than pick a cadence, the solver predicts when the target will be met — CFR+
383
+ exploitability falls as roughly `C / T^p`, so two measurements pin the crossing — and checks
384
+ just short of it. On a 500-iteration run that is 7 checks and 4% overhead, against 50 checks
385
+ and 23% for a fixed cadence of 10.
386
+
387
+ `solution.stoppedAt` is `'target'` or `'iterations'`. The second with a target set means the
388
+ target was *not* reached and the answer is looser than asked for, which the CLI and the UI
389
+ both say out loud.
390
+
391
+ ### Workers
392
+
393
+ `solve(spot, { workers })` splits the runouts across threads, the calling thread included:
394
+ `workers: 2` is the caller and one worker thread. Storage is indexed runout-outermost, so
395
+ each thread owns a disjoint slice of shared memory and takes no locks. Only the round above
396
+ the split stays on the main thread alone, because CFR+ clamps regrets at zero and partial
397
+ sums cannot be added through a clamp. Exploitability and EV passes are split the same way.
398
+
399
+ Measured on a 133 vs 145 combo spot, 8 cores:
400
+
401
+ | Workers | Turn, 400 iters | Flop, 100 iters |
402
+ |---|---|---|
403
+ | 1 | 3.6 s | 82.1 s |
404
+ | 2 | 2.0 s | — |
405
+ | 4 | 1.3 s | 24.8 s |
406
+ | 7 (default) | 1.2 s | 18.6 s |
407
+ | 8 | 1.2 s | 19.3 s |
408
+
409
+ `workers: 'auto'` uses one less than the machine's parallelism, but never fewer than two, so
410
+ a 2-core machine still splits; `workers: 1` stays on one thread. A river spot has a single runout and silently stays single-threaded whatever is
411
+ asked for.
412
+
413
+ Results are bitwise deterministic at a fixed worker count, but agree with a different count
414
+ only to floating point: a worker sums its own slice before the totals are summed across
415
+ workers, which associates the same addition differently, and the non-linear CFR+ clamp
416
+ compounds that rounding. Measured, the gap sits at 1e-15 through 300 iterations and reaches
417
+ 1e-7 by 2,000 — always orders of magnitude below the exploitability at that point.
418
+
419
+ The single largest cost is the number of runouts: a river board has one, a turn 48, a flop
420
+ 2,352. Tree width matters nearly as much — a second bet size roughly quadruples the work.
421
+
422
+ **Suit isomorphism is deliberately absent.** Fixing the board is exactly what destroys the
423
+ symmetry: measured, a rainbow flop's stabiliser is trivial and gains **1.00×**, two-tone
424
+ **1.65×**, monotone **3.48×**. It is not worth the complexity here, which is the opposite
425
+ of the conclusion in the parameterised solver alongside this one, where the flop itself is
426
+ enumerated and can be canonicalised for a 12× win.
427
+
428
+ ## Verification
429
+
430
+ - **A known answer.** The clairvoyance game — nuts and air against pure bluffcatchers on a
431
+ dry board — has a closed-form equilibrium. At a bet of `f` times the pot the solver
432
+ defends `1/(1+f)` and bluffs `f/(1+2f)` of its betting range, and reaches the
433
+ hand-computed expected value. Asserted at three bet sizes.
434
+ - **The evaluator**, ported from `poker-bitvaljs`, is re-checked rather than trusted:
435
+ all 2,598,960 five-card hands against an independent classifier with exact textbook
436
+ frequencies, 200,000 seven-card hands against the best of their 21 five-card subsets, and
437
+ invariance under every suit relabelling.
438
+ - **Card removal** is checked against a brute-force O(K²) reference with weighted,
439
+ partially-zero reach, from flop through river.
440
+ - **Normalisation** is pinned at every entry point by a royal flush on the flop, which no
441
+ runout can beat or chop: the expected value must be exactly half the pot whether one, 48
442
+ or 2,352 completions remain. This caught a real bug where values were scaled by the
443
+ runout count — invisible on a river board, where that factor is 1.
444
+ - Zero-sum to 1e-9, exploitability non-negative and non-increasing, and every strategy a
445
+ probability distribution.
446
+
447
+ ```bash
448
+ npm test
449
+ ```
450
+
451
+ ## Releasing
452
+
453
+ `.github/workflows/publish.yml` publishes to npm from `main`. Every push to `main` is
454
+ type-checked, tested and built; if the `version` in `package.json` is not on npm yet, it
455
+ is published, with provenance. So a release is: bump `version`, merge to `main`. A push
456
+ that leaves the version alone publishes nothing.
457
+
458
+ It publishes by npm trusted publishing: npm trusts this repository's `publish.yml`
459
+ (set up under the package's settings on npmjs.com), the job proves who it is with GitHub's
460
+ OpenID Connect token, and no npm token is stored anywhere.
461
+
462
+ ## License
463
+
464
+ MIT