poker-flopsolve 0.4.1 → 0.5.0-beta.1

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/dist/index.d.ts CHANGED
@@ -151,8 +151,8 @@ interface Runouts {
151
151
  /**
152
152
  * The symmetries each stored board still has, as a prefix into
153
153
  * `stabiliserMap`: map ids, identity first. A board with more than the
154
- * identity holds hands that mirror each other on it, whose strategies the
155
- * solver keeps tied together.
154
+ * identity holds hands that mirror each other on it, which the solver
155
+ * stores once per orbit.
156
156
  */
157
157
  readonly stabiliserStart: readonly Int32Array[];
158
158
  readonly stabiliserMap: readonly Int32Array[];
@@ -168,6 +168,8 @@ interface Runouts {
168
168
  /** The board as given. */
169
169
  readonly initial: readonly number[];
170
170
  }
171
+ /** The card map swapping two ranks in every suit. */
172
+ declare function rankSwap(a: number, b: number): Uint8Array;
171
173
  /** A real board, as the solver stores it. */
172
174
  interface ResolvedBoard {
173
175
  readonly round: number;
@@ -341,6 +343,9 @@ interface HandSpace {
341
343
  readonly same: Int32Array;
342
344
  }
343
345
 
346
+ /** Whether this platform runs the WebAssembly SIMD kernels; false means JavaScript throughout. */
347
+ declare function simdAvailable(): boolean;
348
+
344
349
  /**
345
350
  * Vector CFR+ over a fixed board.
346
351
  *
@@ -377,9 +382,13 @@ interface Layout {
377
382
  * Where each decision node's storage starts. Its block on a board is
378
383
  * `actions` rows of the owner's hands live there, in hand-list order —
379
384
  * entry `i` of their active list — so a row is as long as that list and
380
- * blocked hands take no room. See `blockBase`.
385
+ * blocked hands take no room. See `blockBase`. Int32 while every slot
386
+ * fits one, which keeps the traversal's indexing on integers; Float64,
387
+ * exact to 2^53, for a tree past 2^31 slots, where Int32 would wrap.
388
+ * With compact storage, a node of a compact round's offset is into its
389
+ * chunk of the compact arrays instead.
381
390
  */
382
- readonly offset: Int32Array;
391
+ readonly offset: Int32Array | Float64Array;
383
392
  /** For each list slot `(roundBase[r] + board) * 2 + p`: rows before this board's. */
384
393
  readonly rowStart: Int32Array;
385
394
  /** First list index of each round, as `ActiveLists.roundBase`. */
@@ -393,8 +402,66 @@ interface Layout {
393
402
  readonly blockOffset: Int32Array;
394
403
  readonly blocks: number;
395
404
  readonly totalSlots: number;
405
+ /** Slots one iteration walks: `totalSlots`, and with shared storage what it would be unshared. */
406
+ readonly walkedSlots: number;
396
407
  readonly maxActions: number;
397
408
  readonly bytes: number;
409
+ /**
410
+ * Whether some nodes share another's storage (`SpotConfig.shareHistories`):
411
+ * a block may then be visited more than once an iteration.
412
+ */
413
+ readonly shared: boolean;
414
+ /**
415
+ * Per node, 1 where regret updates are weighted by the actor's own reach:
416
+ * nodes whose storage more than one history shares, under
417
+ * `shareHistories`. Null otherwise.
418
+ */
419
+ readonly reachWeighted: Uint8Array | null;
420
+ /**
421
+ * The first round stored compactly (see `CompactStorage`); the round
422
+ * count when none is, so `round >= compactFrom` says whether a node is.
423
+ */
424
+ readonly compactFrom: number;
425
+ /** Slots of compactly stored regrets; 0 without compact storage. */
426
+ readonly compactSlots: number;
427
+ /** Per node of a compact round: where its hands' scales start in its chunk, else -1. */
428
+ readonly handOffset: Float64Array | null;
429
+ readonly compactHands: number;
430
+ /**
431
+ * Compact storage comes in chunks, each its own buffer, because browsers
432
+ * refuse an ArrayBuffer of 2 GiB or more. A node's storage is all in one
433
+ * chunk: per node of a compact round, which (else -1); its `offset` and
434
+ * `handOffset` count from that chunk's start.
435
+ */
436
+ readonly compactChunk: Int32Array | null;
437
+ /** Per chunk: its slots, its hands, and the slots of every chunk before it. */
438
+ readonly chunkSlots: readonly number[];
439
+ readonly chunkHands: readonly number[];
440
+ readonly chunkStart: readonly number[];
441
+ }
442
+ /**
443
+ * Compact storage, for `SpotConfig.compactStorage`: from round `from` on,
444
+ * regrets and (with `sums`) strategy sums as 8-bit integers; without sums,
445
+ * each hand's strategy there is read as the current profile.
446
+ */
447
+ interface CompactPlan {
448
+ /** First round stored compactly, counted from the spot's first. */
449
+ readonly from: number;
450
+ /** Largest magnitude stored: 127 for 8 bits. */
451
+ readonly steps: number;
452
+ /** One power-of-two scale per hand per block, else one float64 per block. */
453
+ readonly perHand: boolean;
454
+ /** Round at random, unbiased, rather than to nearest. */
455
+ readonly stochastic: boolean;
456
+ /** Keep the regrets as float32: only the sums are dropped. */
457
+ readonly float: boolean;
458
+ /** Largest buffer to allocate; compact storage is split in chunks no bigger. */
459
+ readonly chunkBytes: number;
460
+ /**
461
+ * Keep 8-bit strategy sums too, with their own per-hand scale, so these
462
+ * nodes keep the average strategy. Per-hand scale only.
463
+ */
464
+ readonly sums: boolean;
398
465
  }
399
466
  /** Accumulated regrets: float, or 16-bit integers scaled per block. */
400
467
  type RegretStore = Float64Array | Float32Array | Int16Array;
@@ -418,6 +485,27 @@ interface Context {
418
485
  */
419
486
  readonly regretScale: Float64Array | null;
420
487
  readonly sumScale: Float64Array | null;
488
+ /**
489
+ * Compact storage (`Approximations.compactStorage`), else unset: nodes of
490
+ * rounds from `compact.from` on keep only `compactRegret`, one array per
491
+ * chunk (`layout.compactChunk`) laid out by `layout.offset` as other
492
+ * nodes' regrets are, and each hand's scale in
493
+ * `handShift` — a stored integer `q` means `q * 2^(shift - SHIFT_BIAS)`,
494
+ * and a shift of 0 means the hand's regrets are all zero. With a block
495
+ * scale instead, `compactScale` holds it as `regretScale` does for 16-bit
496
+ * storage.
497
+ */
498
+ readonly compact?: CompactPlan | null;
499
+ readonly compactRegret?: readonly (Int8Array | Float32Array)[] | null;
500
+ readonly handShift?: readonly Uint8Array[] | null;
501
+ /**
502
+ * With `compact.sums`: 8-bit strategy sums, laid out as `compactRegret`,
503
+ * and their per-hand scales, as `handShift` is for regrets.
504
+ */
505
+ readonly compactSum?: readonly Uint8Array[] | null;
506
+ readonly sumShift?: readonly Uint8Array[] | null;
507
+ /** Compact storage's per-block scales, when it keeps one per block rather than per hand. */
508
+ readonly compactScale?: Float64Array | null;
421
509
  readonly scratch: TerminalScratch;
422
510
  readonly chipScale: number;
423
511
  /** Which combinations each player can hold on each board. */
@@ -461,6 +549,73 @@ interface Context {
461
549
  expandOrbits: boolean;
462
550
  /** Use the WebAssembly SIMD kernels where the platform has them. */
463
551
  readonly simd: boolean;
552
+ /**
553
+ * Chance sampling with baselines, for `Approximations.chanceSampling`;
554
+ * unset or null for the exact traversal.
555
+ */
556
+ sampling?: Sampling | null;
557
+ /**
558
+ * With shared storage (`Layout.shared`), per block the iteration DCFR
559
+ * last discounted it in. A shared block is visited once per history that
560
+ * reaches it, and only the first visit of an iteration discounts. Unset or
561
+ * null for unshared storage, where every block is visited once.
562
+ */
563
+ discounted?: Int32Array | null;
564
+ }
565
+ /** How chance sampling picks deals; see `Approximations.chanceSampling`. */
566
+ interface SamplingOptions {
567
+ /**
568
+ * Probability of walking each deal on a training iteration, chosen at
569
+ * random per deal and iteration. Default 0.35. Ignored with `every`.
570
+ */
571
+ readonly p?: number;
572
+ /**
573
+ * Walk every deal exactly once every this many iterations, in rotation,
574
+ * instead of at random. Measured, it converges worse than random at the
575
+ * same rate; kept for comparison.
576
+ */
577
+ readonly every?: number;
578
+ /**
579
+ * Betting rounds whose deals are sampled, counted from the spot's first:
580
+ * from a flop, 1 is the turn and 2 the river. Default every round after
581
+ * the first.
582
+ */
583
+ readonly rounds?: readonly number[];
584
+ /**
585
+ * How a walked deal's fresh value meets its baseline: 'unbiased' adds
586
+ * `(v - b) / p` to the baseline, the VR-MCCFR estimator; 'latest' uses
587
+ * `v` itself, the freshest value without the correction.
588
+ */
589
+ readonly estimator?: 'unbiased' | 'latest';
590
+ /** Apply the DCFR discounts a skipped subtree missed when it is next walked. Default true. */
591
+ readonly catchUp?: boolean;
592
+ }
593
+ /** Where sampling keeps what, for a spot; see `makeSampling`. */
594
+ interface SamplingPlan {
595
+ readonly rounds: Uint8Array;
596
+ readonly p: number;
597
+ readonly every: number;
598
+ readonly unbiased: boolean;
599
+ readonly catchUp: boolean;
600
+ /** Per chance node into a sampled round: where its baselines start, else -1. */
601
+ readonly baseOffset: Int32Array;
602
+ /** Per list slot of a sampled round: offset of that board and player's baseline within a node's. */
603
+ readonly boardOffset: Int32Array;
604
+ /** Per chance node: where its last-walk entries start, two per child board. */
605
+ readonly walkOffset: Int32Array;
606
+ /** Baseline values, last-walk entries and blocks the state holds. */
607
+ readonly values: number;
608
+ readonly walks: number;
609
+ readonly blocks: number;
610
+ }
611
+ /** Sampling state: baselines, when each was last walked, when each block was last updated. */
612
+ interface Sampling extends SamplingPlan {
613
+ readonly baseline: Float32Array;
614
+ readonly lastWalk: Int32Array;
615
+ /** Per block: the iteration it was last updated in, for DCFR catch-up. */
616
+ readonly lastUpdate: Int32Array;
617
+ /** Memory the state takes. */
618
+ readonly bytes: number;
464
619
  }
465
620
  /**
466
621
  * Which combinations each player can hold on each board.
@@ -481,15 +636,6 @@ interface ActiveLists {
481
636
  readonly slot: Uint16Array;
482
637
  /** First list index of each round. */
483
638
  readonly roundBase: Int32Array;
484
- /**
485
- * Hands that mirror each other on a board with symmetry left, whose
486
- * accumulators are kept equal, indexed by the same slot as `start`:
487
- * `ties[tieStart[slot]..tieStart[slot + 1]]` is a run of classes, each its
488
- * size then that many positions in the board's hand list. Empty almost
489
- * everywhere.
490
- */
491
- readonly tieStart: Int32Array;
492
- readonly ties: Int32Array;
493
639
  /** Each entry's two cards, beside `list`. */
494
640
  readonly cardA: Uint8Array;
495
641
  readonly cardB: Uint8Array;
@@ -498,13 +644,45 @@ interface ActiveLists {
498
644
  * lists are sorted by it. Zero elsewhere.
499
645
  */
500
646
  readonly strength: Int32Array;
647
+ /**
648
+ * On a board with symmetry left, a list holds one hand per mirror orbit —
649
+ * the lowest combination, see `orbitLeader` — standing for the whole
650
+ * orbit. Mirrored hands play alike, since the board and both ranges look
651
+ * the same after swapping suits, so one hand's strategy, reach and value
652
+ * are all of theirs; storing them once is exact, and shortens every vector
653
+ * there. Whether a list holds any orbit of more than one hand, beside
654
+ * `start`: only those need the weighted deal and terminal kernels.
655
+ */
656
+ readonly packed: Uint8Array;
657
+ /** How many hands each entry stands for, beside `list`: 1 unpacked. */
658
+ readonly multiplicity: Float64Array;
659
+ /**
660
+ * The hands each entry stands for, itself first: `memberCombo` and their
661
+ * cards from `memberStart[e]` to `memberStart[e + 1]`.
662
+ */
663
+ readonly memberStart: Int32Array;
664
+ readonly memberCombo: Uint16Array;
665
+ readonly memberA: Uint8Array;
666
+ readonly memberB: Uint8Array;
501
667
  }
668
+ /**
669
+ * What a traversal plays and does. Train plays the current (regret-matched)
670
+ * profile and updates the traverser's regrets and sums; Current plays that
671
+ * same profile and updates nothing, for reading its values; Average plays the
672
+ * average profile; BestResponse has the traverser best-respond to it.
673
+ */
502
674
  declare const Mode: {
503
675
  readonly Train: 0;
504
676
  readonly BestResponse: 1;
505
677
  readonly Average: 2;
678
+ readonly Current: 3;
506
679
  };
507
680
  type Mode = (typeof Mode)[keyof typeof Mode];
681
+ /** See `Solver.rootValues`. */
682
+ interface RootValues {
683
+ readonly totals: readonly [number, number];
684
+ readonly values: readonly [Float64Array, Float64Array];
685
+ }
508
686
  /** A whole-tree traversal, returning the root value vector. */
509
687
  type RootTraversal = (mode: Mode, traverser: 0 | 1, iterWeight: number) => Float64Array;
510
688
  /** A prepared solver. */
@@ -528,6 +706,25 @@ interface Solver {
528
706
  readonly rootCount: number;
529
707
  iterate(count: number, from: number): void;
530
708
  expectedValue(): [number, number];
709
+ /**
710
+ * One root pass per player under the average profile (`Mode.Average`) or
711
+ * the current one (`Mode.Current`): each player's chips per hand, as
712
+ * `expectedValue` gives them for the average, and a copy of their root
713
+ * counterfactual values, one per hand of their root active list. In chips
714
+ * against a baseline where each player owns half the pot, unlike
715
+ * `Solution.ev`'s share of the pot.
716
+ */
717
+ rootValues(mode: typeof Mode.Average | typeof Mode.Current): RootValues;
718
+ /**
719
+ * Root EV in chips for each combination, indexed like `COMBO_CARDS`, from
720
+ * root counterfactual values `rootValues` returned for `player`: each
721
+ * hand's value over the opponent mass it can be dealt against. Zero for a
722
+ * combination off the root list or with no opponent hand to face. Chips
723
+ * are on the traversal's baseline, each player owning half the pot;
724
+ * `unit` converts each hand that has an EV (as `Solution.handEvs` does to
725
+ * a share of the pot), and the zeros stay zero.
726
+ */
727
+ handEvs(player: 0 | 1, values: Float64Array, unit?: (chips: number) => number): Float64Array;
531
728
  exploitability(): number;
532
729
  averageStrategyAt(node: number, board: number): {
533
730
  actions: number;
@@ -535,18 +732,71 @@ interface Solver {
535
732
  };
536
733
  /**
537
734
  * Counterfactual values under the average strategy from any node, for
538
- * reach vectors the caller supplies. Returns a fresh copy.
735
+ * reach vectors the caller supplies. Returns a fresh copy. In chips,
736
+ * against a baseline where each player owns half the pot (folding is
737
+ * −pot/2), as the traversal and its regrets are; not `Solution.ev`'s
738
+ * share of the pot.
539
739
  */
540
740
  valuesAt(node: number, board: number, traverser: 0 | 1, reachMe: Float64Array, reachOpp: Float64Array, live: Uint16Array, liveCount: number): Float64Array;
741
+ /**
742
+ * The whole-tree traversal `iterate` and the other passes run now: this
743
+ * thread's own, or what `useRoot` routed them to. For wrapping it.
744
+ */
745
+ readonly root: RootTraversal;
541
746
  /**
542
747
  * Counterfactual values under the average strategy from any node against
543
748
  * each of `hands` alone, at the reach given for it: the same as `valuesAt`
544
749
  * with a one-hot opponent reach, for many opposing hands in one walk.
545
- * Returns `hands.length * COMBOS` values, one row per opposing hand.
750
+ * Returns `hands.length * COMBOS` values, one row per opposing hand. In
751
+ * chips on `valuesAt`'s half-pot baseline.
546
752
  */
547
753
  pairValuesAt(node: number, board: number, traverser: 0 | 1, hands: Uint16Array, handReach: Float64Array, live: Uint16Array, liveCount: number): Float64Array;
548
754
  }
549
755
 
756
+ /**
757
+ * Node platform.
758
+ *
759
+ * Purpose: the one place the solver touches Node-only APIs. A browser build
760
+ * swaps this module for `browser.ts`, which has the same exports; see
761
+ * `scripts/browser-platform.ts`.
762
+ */
763
+
764
+ /** Which build this is. */
765
+ declare const PLATFORM = "node";
766
+
767
+ /**
768
+ * The WebAssembly traversal engine, set up.
769
+ *
770
+ * Purpose: lay a prepared spot out in one WebAssembly memory for
771
+ * `assembly/engine.ts`, and give the solver its storage and a root traversal.
772
+ *
773
+ * The engine keeps the accumulators in its own memory as 32-bit floats; the
774
+ * solver's `regret` and `strategySum` are views onto them, so everything that
775
+ * reads storage from JavaScript — strategy queries, warm starts, `valuesAt` —
776
+ * sees the very same numbers. It runs where WebAssembly SIMD is available,
777
+ * on one thread or several; otherwise the JavaScript traversal in cfr.ts
778
+ * runs. A second build, which only `poker-flopsolve/wasm-storage` carries,
779
+ * keeps 16-bit and compact storage the same way (`EngineInput.storage`).
780
+ *
781
+ * WebAssembly memory is one buffer, but Chromium lets it reach wasm32's full
782
+ * 4 GiB, plain or shared, made at that size or grown to it, where it refuses
783
+ * any ArrayBuffer over 2 GiB less 2 MiB (measured in Chromium 153 by
784
+ * bin/memory-ceiling.ts; issue #84). So compact storage needs no chunks of
785
+ * its own in the engine: its chunks are regions of the one memory, laid out
786
+ * as the JavaScript engine's buffers are.
787
+ */
788
+
789
+ /**
790
+ * The engine with 16-bit and compact storage (issue #84), as base64 for plain
791
+ * and shared memory. Only `poker-flopsolve/wasm-storage` holds the bytes, so
792
+ * a build that never imports it carries none of them; a solve opts in by
793
+ * passing it as `SolveOptions.wasmStorage`.
794
+ */
795
+ interface WasmStorage {
796
+ readonly plain: string;
797
+ readonly shared: string;
798
+ }
799
+
550
800
  /**
551
801
  * Warm starts.
552
802
  *
@@ -569,6 +819,10 @@ interface Solver {
569
819
  * their real cards, so two spots may store different runouts (one folding
570
820
  * mirrored deals, the other not); hands match by combination, so a range may
571
821
  * have grown or shrunk.
822
+ *
823
+ * A solve of another board can seed this one through a card relabelling — a
824
+ * permutation of the deck taking one board onto the other, a rank swap for a
825
+ * nearby flop — through which its runouts and hands are read.
572
826
  */
573
827
 
574
828
  /** What a warm start carried over. */
@@ -586,6 +840,79 @@ interface WarmStartReport {
586
840
  readonly averages: boolean;
587
841
  }
588
842
 
843
+ /**
844
+ * A stopping rule for solves that never reach an exploitability target: stop
845
+ * once the root play stops moving (issue #100).
846
+ *
847
+ * Purpose: a blueprint with `shareHistories` plateaus several percent of the
848
+ * pot from equilibrium, so `targetPercent` cannot end it, yet its first
849
+ * decisions go on settling and are what a caller reads (issue #85). This
850
+ * reads them cheaply: the average strategy at two nodes, with no
851
+ * best-response pass, so a check costs a tiny fraction of an iteration.
852
+ *
853
+ * The root play is the decision opening the spot (out of position) and, after
854
+ * a check there, in position's: neither player has acted before them, so each
855
+ * decision is played by the whole range and is weighted by it. Its movement
856
+ * between two strategies is, per decision, the total variation of each hand's
857
+ * action mix (half the summed absolute change), averaged over the range by
858
+ * weight; the larger of the two decisions counts. 0.01 means the range's
859
+ * play moved by 1% of its mass. #85 called the root play still once both
860
+ * decisions moved under 1% between checks 20 iterations apart.
861
+ */
862
+
863
+ /** See `SolveOptions.settle`. */
864
+ interface SettleOptions {
865
+ /** Iterations between checks. Default 20. */
866
+ readonly every?: number;
867
+ /**
868
+ * Movement between consecutive checks, as a share of the range, under
869
+ * which the root play counts as still: see `rootPlayMovement`. Default
870
+ * 0.01.
871
+ */
872
+ readonly tolerance?: number;
873
+ /** Consecutive still checks before stopping. Default 2. */
874
+ readonly patience?: number;
875
+ /** Iterations before which no check counts toward `patience`. Default 0. */
876
+ readonly minIterations?: number;
877
+ }
878
+ /** The strategies `rootPlayMovement` compares; see `rootPlay`. */
879
+ interface RootPlay {
880
+ /** The root, then in position's decision after a check there, when there is one. */
881
+ readonly views: readonly StrategyView[];
882
+ /** Range weight per combination of each view's player, indexed like `COMBO_CARDS`. */
883
+ readonly weights: readonly Float64Array[];
884
+ }
885
+ /** The decisions that make up the root play of a solved spot. */
886
+ declare function rootPlayNodes(solution: Solution): number[];
887
+ /**
888
+ * The root play of a solution as it stands: the average strategy at the
889
+ * root and at in position's decision after a check. Cheap: two strategy
890
+ * reads, no best-response pass.
891
+ */
892
+ declare function rootPlay(solution: Solution): RootPlay;
893
+ /**
894
+ * How far the root play moved from `before` to `after`, two readings of the
895
+ * same spot: per decision, the range-weighted mean of each hand's total
896
+ * variation, and the larger over the decisions. 0 is unmoved, 1 is every
897
+ * hand switching to actions it never took.
898
+ */
899
+ declare function rootPlayMovement(before: RootPlay, after: RootPlay): number;
900
+ /**
901
+ * A running settle check for a caller that steps a run itself. Feed it a
902
+ * snapshot after each `every` iterations; it says when the root play has
903
+ * stayed still for `patience` checks in a row.
904
+ */
905
+ interface SettleTracker {
906
+ /** Record a snapshot taken after `iterations` in all; true once settled. */
907
+ check(solution: Solution, iterations: number): boolean;
908
+ /** Movement at the last check, or NaN before the second. */
909
+ readonly movement: number;
910
+ /** Whether the last check settled it. */
911
+ readonly settled: boolean;
912
+ }
913
+ /** Start a settle check; see `SettleTracker`. */
914
+ declare function trackSettle(options?: SettleOptions): SettleTracker;
915
+
589
916
  /**
590
917
  * Five-to-seven card hand evaluation.
591
918
  *
@@ -683,19 +1010,566 @@ declare function activeCombos(weights: Float64Array): number[];
683
1010
  /** Total weight, i.e. combinations counted with their weight. */
684
1011
  declare function rangeWeight(weights: Float64Array): number;
685
1012
 
686
- /** Whether this platform runs the WebAssembly SIMD kernels; false means JavaScript throughout. */
687
- declare function simdAvailable(): boolean;
1013
+ /**
1014
+ * Nested subgame re-solving (issue #47).
1015
+ *
1016
+ * Purpose: refine one player's strategy below a node of a solved spot — a
1017
+ * blueprint whose later streets were simplified to fit — by solving that
1018
+ * subgame again with a richer tree. Opt-in: nothing else in the solver calls
1019
+ * this.
1020
+ *
1021
+ * `Solution.subgameAt` already builds the subgame; this solves it with the
1022
+ * ranges the blueprint brings to the node held fixed (unsafe re-solving), and
1023
+ * can measure what each opponent hand gets against the result next to what it
1024
+ * had against the blueprint.
1025
+ *
1026
+ * Nested: a re-solved subgame is a `Solution` like any other, so a node below
1027
+ * it can be re-solved from it in turn.
1028
+ *
1029
+ * Measured (issue #47; Ks 9s 4s, a flop blueprint with three flop sizes and
1030
+ * one turn/river size, its turns re-solved at three sizes with raises,
1031
+ * against a full-tree reference): an opponent's best response under the
1032
+ * reference's ranges gained, weighted by how often each turn is reached,
1033
+ * about 3.5–4% of the subgame's pot against plain re-solving, and more
1034
+ * against every safe gadget tried (4.2–6.2%: Burch, Johanson & Bowling's
1035
+ * re-solve gadget and Moravčík et al.'s and Brown & Sandholm's maxmargin
1036
+ * ones). Most of what is left is the refined player's own range at the node,
1037
+ * which comes from the blueprint and which no gadget changes, so the gadgets
1038
+ * were removed before 0.5.0 (issue #125). To make re-solves from a shared
1039
+ * blueprint trustworthy, keep the busiest lines unshared
1040
+ * (`ShareHistories.keepLines` with `linesWithin`).
1041
+ */
688
1042
 
1043
+ /** Settings for {@link resolveSubgame}. */
1044
+ interface ResolveOptions {
1045
+ /** The player whose strategy is refined. */
1046
+ readonly player: 0 | 1;
1047
+ /** The subgame's betting; unset, the blueprint's carries over. */
1048
+ readonly betting?: SubgameBetting;
1049
+ /** Iterations to run. Default 200. */
1050
+ readonly iterations?: number;
1051
+ /**
1052
+ * Also report `alternative` and `entered`, at the cost of a best-response
1053
+ * pass over the blueprint below the node and one over the subgame.
1054
+ */
1055
+ readonly measure?: boolean;
1056
+ /** Solver settings for the subgame; `iterations` and warm starts are this function's. */
1057
+ readonly solve?: Pick<SolveOptions, 'workers' | 'precision' | 'algorithm' | 'engine' | 'simd' | 'wasmStorage'>;
1058
+ }
1059
+ /** A re-solved subgame. */
1060
+ interface ResolvedSubgame {
1061
+ /**
1062
+ * The subgame's solution. Its ranges are the ones the blueprint brings to
1063
+ * the node; read the refined player's strategy from it.
1064
+ */
1065
+ readonly solution: Solution;
1066
+ readonly player: 0 | 1;
1067
+ /**
1068
+ * Each opponent hand's best-response value at the node against the
1069
+ * blueprint, in chips on `Solver.valuesAt`'s half-pot baseline (not
1070
+ * `Solution.ev`'s share of the pot), indexed like `COMBO_CARDS`; NaN off
1071
+ * its range.
1072
+ * Null unless `measure`.
1073
+ */
1074
+ readonly alternative: Float64Array | null;
1075
+ /**
1076
+ * Each opponent hand's best-response value in the re-solved subgame
1077
+ * against the refined strategy, in chips; NaN off its range. Where it
1078
+ * exceeds `alternative` the re-solve gave that hand more than the
1079
+ * blueprint did. Null unless `measure`.
1080
+ */
1081
+ readonly entered: Float64Array | null;
1082
+ readonly iterations: number;
1083
+ }
689
1084
  /**
690
- * Node platform.
1085
+ * Re-solve the subgame at a node of `blueprint` for one player.
691
1086
  *
692
- * Purpose: the one place the solver touches Node-only APIs. A browser build
693
- * swaps this module for `browser.ts`, which has the same exports; see
694
- * `scripts/browser-platform.ts`.
1087
+ * @param blueprint a solved spot
1088
+ * @param node a decision opening a betting round (see `Solution.subgameAt`)
1089
+ * @param board the board index at that node's round
695
1090
  */
1091
+ declare function resolveSubgame(blueprint: Solution, node: number, board: number, options: ResolveOptions): ResolvedSubgame;
696
1092
 
697
- /** Which build this is. */
698
- declare const PLATFORM = "node";
1093
+ /**
1094
+ * Hybrid history sharing (issue #101): share later-street storage between
1095
+ * histories except along the lines most often played.
1096
+ *
1097
+ * Purpose: a solve with `shareHistories` keeps its flop play, but the ranges
1098
+ * it brings to a turn are trained against river values that several
1099
+ * histories share, so a turn re-solved from it starts from distorted ranges.
1100
+ * `ShareHistories.keepLines` gives named lines storage of their own, and
1101
+ * `turnLineReach` ranks the flop lines by how often they are reached, and
1102
+ * `linesWithin` picks the most-reached ones a storage budget allows.
1103
+ */
1104
+
1105
+ /** A flop line opening the turn, and its share of the root's hand pairs. */
1106
+ interface LineReach {
1107
+ /** The turn's first decision, as `Solution.path` names it, e.g. `"check check /"`. */
1108
+ readonly line: string;
1109
+ /** The turn's first decision node. */
1110
+ readonly node: number;
1111
+ /** Weighted hand pairs reaching the turn by this line over those at the root, 0 to 1. */
1112
+ readonly share: number;
1113
+ }
1114
+ /**
1115
+ * Every line from the spot's first round into the next, most reached first.
1116
+ * Reach comes from the average strategy, so take it from a solve that has
1117
+ * run a while; the order settles long before the strategy does.
1118
+ */
1119
+ declare function turnLineReach(solution: Solution): LineReach[];
1120
+ /**
1121
+ * The most-reached lines of `solution` (`turnLineReach`) that
1122
+ * `ShareHistories.keepLines` can keep in `options.config` with its storage
1123
+ * at `options.precision` (compact storage included) at most `maxBytes`: the
1124
+ * longest prefix of the ranking that fits, with any lines the config already
1125
+ * keeps. Throws if the spot is over budget keeping only those. Keeping a line never shrinks storage, so the
1126
+ * prefix is found by bisection.
1127
+ *
1128
+ * The spot the lines are for, `options.config`, defaults to the one
1129
+ * `solution` solved. The ranking can come from a cheaper spot with the same first
1130
+ * round: the reach of a flop line is the flop play alone, so a solve with
1131
+ * the river checked down ranks the lines much as the real one does, in a
1132
+ * fraction of its memory (see `ShareHistories.keepLines`).
1133
+ */
1134
+ declare function linesWithin(solution: Solution, maxBytes: number, options?: LinesWithinOptions): string[];
1135
+ /** Settings for {@link linesWithin}. */
1136
+ interface LinesWithinOptions {
1137
+ /** The spot the lines are kept in; unset, the one the ranking solution solved. */
1138
+ readonly config?: SpotConfig;
1139
+ /** The precision the spot will be solved at, which the budget is for; default 'f32'. */
1140
+ readonly precision?: Precision;
1141
+ }
1142
+
1143
+ /**
1144
+ * Range compression (issue #156): replace each player's range by a smaller,
1145
+ * re-weighted subset of its combinations that keeps the range's distribution
1146
+ * of equity on the flop, on every turn and on the river boards.
1147
+ *
1148
+ * Purpose: a solve's time and memory grow with the combinations in play, and
1149
+ * a range can lose a third to a half of them before the range as a whole
1150
+ * plays differently. The method is poker-rangecompress's, vendored in
1151
+ * `vendor/range-compress.js` (`scripts/vendor-range-compress.ts` copies it
1152
+ * in); what it costs under Lite is in `bench/range-compress`.
1153
+ *
1154
+ * What it keeps is how the range plays: how often it takes each action, and
1155
+ * how its strong, middling and weak parts act. What it does not keep is what
1156
+ * one combination does: a combination that is left out has no strategy, and
1157
+ * the ones kept carry the weight of those that were dropped.
1158
+ */
1159
+ /** How far {@link compressRanges} may go. */
1160
+ interface CompressRangesOptions {
1161
+ /**
1162
+ * The most mismatch allowed: each range keeps the fewest combinations
1163
+ * whose equity distributions stay this close to the original's, as a
1164
+ * fraction of it. Default 0.01, which measured about one percentage
1165
+ * point of difference in how often the range takes an action; 0.005 was
1166
+ * indistinguishable from solving the full range again, 0.02 about two
1167
+ * points.
1168
+ */
1169
+ readonly tolerance?: number;
1170
+ /** Keep this many combinations of each range (or `[oop, ip]`) instead of working to `tolerance`. */
1171
+ readonly size?: number | readonly [number, number];
1172
+ }
1173
+ /** What {@link compressRanges} did to one range. */
1174
+ interface RangeCompression {
1175
+ /** Combinations with weight before, off the board and at or over `minWeight`. */
1176
+ readonly from: number;
1177
+ /** Combinations kept. */
1178
+ readonly to: number;
1179
+ /** The mismatch reached: 0 is identical. */
1180
+ readonly mismatch: number;
1181
+ }
1182
+ /** The compressed ranges of a spot, and what changed. */
1183
+ interface CompressedRanges {
1184
+ /** A weight per combination, the largest 1, indexed like `COMBO_CARDS`. */
1185
+ readonly oop: Float64Array;
1186
+ readonly ip: Float64Array;
1187
+ /** Out of position's range, then in position's. */
1188
+ readonly report: readonly [RangeCompression, RangeCompression];
1189
+ }
1190
+ /**
1191
+ * Compress both ranges of a flop spot, each against the other's full range.
1192
+ *
1193
+ * Combinations on the board and those under `minWeight` are left out first,
1194
+ * as `defineSpot` would. Ranges that are the same in every suit the flop
1195
+ * treats alike stay so, so the solver's suit symmetry still applies.
1196
+ *
1197
+ * @throws if the board is not a flop, or a range is empty
1198
+ */
1199
+ declare function compressRanges(config: {
1200
+ readonly board: string;
1201
+ readonly oop: string | Float64Array;
1202
+ readonly ip: string | Float64Array;
1203
+ readonly minWeight?: number;
1204
+ }, options?: CompressRangesOptions): CompressedRanges;
1205
+
1206
+ /**
1207
+ * What a preset changed (issue #115).
1208
+ *
1209
+ * Purpose: `solveLite` and `largeTree` take any caller betting and turn it
1210
+ * into a cheaper game. Nothing they do may be silent, so each hands back a
1211
+ * `PresetChanges`: the bet, raise and shove sizes its tree no longer offers,
1212
+ * found by walking the caller's betting tree beside the preset's, the rounds
1213
+ * that lost any, and every other setting it set or dropped, each with a
1214
+ * sentence a page can show as it is.
1215
+ */
1216
+
1217
+ /** A betting round by name. */
1218
+ type Street = 'flop' | 'turn' | 'river';
1219
+ /** Sizes one player's decisions of one kind lost on one round. */
1220
+ interface SizesCut {
1221
+ readonly street: Street;
1222
+ readonly player: 'oop' | 'ip';
1223
+ /** 'bet' opens the round's betting; 'raise' answers a bet. */
1224
+ readonly facing: 'bet' | 'raise';
1225
+ /**
1226
+ * The sizes cut, ascending: each a fraction of the pot after a call, to
1227
+ * two places, as `betSizes` and `raiseSizes` give them, or 'allin'.
1228
+ * Where the caller's sizes resolve to different chips at different pots,
1229
+ * one caller size can show as neighbouring fractions.
1230
+ */
1231
+ readonly sizes: readonly (number | 'allin')[];
1232
+ /** The caller's decisions of this kind that lost at least one size. */
1233
+ readonly decisions: number;
1234
+ /**
1235
+ * The caller's decisions of this kind, offering any size, that the
1236
+ * preset's tree still reaches: those below a cut action are gone with
1237
+ * it and counted in neither number.
1238
+ */
1239
+ readonly of: number;
1240
+ }
1241
+ /** A setting a preset set, changed or dropped. */
1242
+ interface SettingChange {
1243
+ /** The setting's name: a `SpotConfig` field, or a `SolveOptions` one (`approximations.chanceSampling`, `precision`, ...). */
1244
+ readonly setting: string;
1245
+ /** The caller's value; undefined where it was unset. */
1246
+ readonly from: unknown;
1247
+ /** The preset's value; undefined where it dropped it. */
1248
+ readonly to: unknown;
1249
+ }
1250
+ /** Everything a preset changed against the caller's spot. */
1251
+ interface PresetChanges {
1252
+ /** Sizes the preset's tree no longer offers, by street, player and kind. */
1253
+ readonly sizesCut: readonly SizesCut[];
1254
+ /** Streets whose betting lost any size: the rounds simplified. */
1255
+ readonly roundsSimplified: readonly Street[];
1256
+ /** Every other setting set, changed or dropped, the approximations included. */
1257
+ readonly settings: readonly SettingChange[];
1258
+ /** One sentence per change, sizes first, in plain words. */
1259
+ readonly notes: readonly string[];
1260
+ }
1261
+
1262
+ /**
1263
+ * Lite mode (issue #100): one opt-in that turns the caller's betting into the
1264
+ * phone/laptop blueprint issue #85 measured, solves it until its root play
1265
+ * settles, and re-solves later streets at the caller's full betting on demand.
1266
+ *
1267
+ * Purpose: the recipe needs a dozen settings — the flop betting kept, one
1268
+ * size on the turn and river, `shareHistories`, `runoutBuckets`,
1269
+ * `chanceSampling`, a stop on the root play rather than on exploitability —
1270
+ * and callers should not have to assemble it. Nothing else in the package
1271
+ * calls this; unused, it changes nothing.
1272
+ *
1273
+ * What is measured, and what each default costs, is in `solveLite`'s notes.
1274
+ */
1275
+
1276
+ /** How `liteConfig` simplifies the caller's betting. */
1277
+ interface LiteOptions {
1278
+ /**
1279
+ * The turn and river keep one bet size: the caller's pot-fraction size
1280
+ * nearest this. Default 0.75.
1281
+ */
1282
+ readonly laterSize?: number;
1283
+ /**
1284
+ * Keep one raise on the turn and river, of the caller's raise size
1285
+ * nearest `laterSize`. Default false: a bet and no raise, as issue #85
1286
+ * measured. A raise nearly doubles the tree: on issue #47's rainbow
1287
+ * betting 707 MiB unshared became 1375 (173 shared became 261), an
1288
+ * iteration cost 1.74 times as much and Node peaked at 546 MiB.
1289
+ */
1290
+ readonly laterRaise?: boolean;
1291
+ /**
1292
+ * Cap the flop's aggressions, the opening bet the first. Default: the
1293
+ * caller's. A speed trim, off by default: see `solveLite`'s notes for
1294
+ * what it saved and cost.
1295
+ */
1296
+ readonly flopMaxRaises?: number;
1297
+ /**
1298
+ * Forbid donk bets on the turn and river (`SpotConfig.noDonk`). Default:
1299
+ * the caller's setting. A speed trim, off by default: see `solveLite`'s
1300
+ * notes for what it saved and cost.
1301
+ */
1302
+ readonly noDonk?: boolean;
1303
+ /** `SpotConfig.runoutBuckets` for the blueprint. Default 3. */
1304
+ readonly runoutBuckets?: number;
1305
+ /**
1306
+ * `SpotConfig.shareHistories` for the blueprint. Default true, the river.
1307
+ *
1308
+ * For better turn re-solves, keep the most-reached flop lines unshared
1309
+ * within a memory budget: `SolveLiteOptions.keepBudget` (issue #113),
1310
+ * which picks them with `linesWithin` for you. Lines given here in
1311
+ * `keepLines` are kept besides.
1312
+ */
1313
+ readonly shareHistories?: boolean | ShareHistories;
1314
+ /**
1315
+ * Compress both ranges before the blueprint is solved (`compressRanges`,
1316
+ * issue #156): each keeps the fewest of its combinations, re-weighted,
1317
+ * whose equity distributions on this flop's boards stay within
1318
+ * `tolerance` (default 0.01) of the full range's. Default off. True for
1319
+ * the defaults. A flop spot only.
1320
+ *
1321
+ * It keeps how the range plays, not what one combination does: the
1322
+ * blueprint and its re-solves hold a strategy only for the combinations
1323
+ * kept. `minWeight` is applied before compressing, not after.
1324
+ */
1325
+ readonly compressRanges?: boolean | CompressRangesOptions;
1326
+ }
1327
+ /** Settings for {@link solveLite}. */
1328
+ interface SolveLiteOptions extends LiteOptions, Pick<SolveOptions, 'workers' | 'precision' | 'wasmStorage' | 'algorithm' | 'onProgress' | 'targetPercent'> {
1329
+ /** Iteration cap. Default 2000; the solve normally settles well before. */
1330
+ readonly iterations?: number;
1331
+ /** The stop on the root play (`SolveOptions.settle`); false to run to `iterations`. Default {}, its own defaults; tolerance 0.005 unless given when `keepBudget` keeps lines. */
1332
+ readonly settle?: SettleOptions | false;
1333
+ /**
1334
+ * `Approximations.chanceSampling` for the blueprint, or false for none.
1335
+ * Default {}: sampled at p 0.35, on `workers` threads.
1336
+ */
1337
+ readonly sampling?: SamplingOptions | false;
1338
+ /**
1339
+ * Keep the most-reached first-round lines' later streets unshared
1340
+ * (`ShareHistories.keepLines`, issue #101), as many as this many bytes
1341
+ * of storage at `precision` (default 'f32') allow; `keepWithin` picks
1342
+ * them, and the blueprint with them kept is solved from cold. It is for
1343
+ * turn re-solves: on issue #47's flops it cut their gain by a third to a
1344
+ * half at the settle point, more when run longer, root play unchanged.
1345
+ * 150 MiB with `precision: 'i16'` and `wasmStorage` kept 3–19 lines and
1346
+ * peaked at 317–534 MiB in Chromium, re-solve included. When it keeps a
1347
+ * line, `settle` stops later: its tolerance defaults to 0.005, not 0.01, as the kept
1348
+ * lines' turn ranges go on improving after the root play settles (issue
1349
+ * #123); give `settle.tolerance` to choose. Throws if the shared
1350
+ * blueprint alone is over the budget, or if it shares nothing. Unset,
1351
+ * off. Measures are in `solveLite`'s notes.
1352
+ */
1353
+ readonly keepBudget?: number;
1354
+ /** Iterations of the picking solve under `keepBudget`. Default 80, as issue #101 measured. */
1355
+ readonly pickIterations?: number;
1356
+ }
1357
+ /** Settings for `LiteSolution.resolve`. */
1358
+ interface LiteResolveOptions extends Omit<ResolveOptions, 'betting'> {
1359
+ /** Overrides on the caller's own betting for the subgame. */
1360
+ readonly betting?: SubgameBetting;
1361
+ }
1362
+ /** What {@link litePreset} returns: the blueprint spot and the solve's settings, and what they changed. */
1363
+ interface LitePreset {
1364
+ /** The blueprint spot (`liteConfig`'s). */
1365
+ readonly config: SpotConfig;
1366
+ /** The blueprint solve's settings: `iterations`, `settle`, sampling and the solve options given. */
1367
+ readonly options: SolveOptions;
1368
+ /** Everything the preset changed against the caller's spot. */
1369
+ readonly changes: PresetChanges;
1370
+ }
1371
+ /** What {@link solveLite} returns. */
1372
+ interface LiteSolution {
1373
+ /** The blueprint's solution. */
1374
+ readonly solution: Solution;
1375
+ /** The blueprint spot that was solved (`liteConfig`'s, with `keepBudget` its kept lines). */
1376
+ readonly blueprint: SpotConfig;
1377
+ /** The lines kept unshared (`ShareHistories.keepLines`); empty without `keepBudget` or kept lines of the caller's. */
1378
+ readonly kept: readonly string[];
1379
+ /** The caller's spot, full betting. */
1380
+ readonly source: SpotConfig;
1381
+ /**
1382
+ * What the blueprint changed against `source`: the sizes cut on each
1383
+ * street (the flop's own only with `flopMaxRaises`), the streets
1384
+ * simplified, and the sharing, buckets, sampling and stop rule switched
1385
+ * on. `resolve` puts the cut sizes back below the node it re-solves.
1386
+ */
1387
+ readonly changes: PresetChanges;
1388
+ /**
1389
+ * Re-solve the subgame at a node opening the turn or river, at the
1390
+ * caller's full betting for the streets from there, the caller's cuts
1391
+ * below the node included: `resolveSubgame` with 200 iterations
1392
+ * unless `options` say otherwise, with the blueprint's `workers`,
1393
+ * `precision` and `wasmStorage`.
1394
+ */
1395
+ resolve(node: number, board: number, options: LiteResolveOptions): ResolvedSubgame;
1396
+ }
1397
+ /**
1398
+ * The blueprint of `config`: its first round's betting as given, every later
1399
+ * round one bet size (the given size nearest `laterSize`) and, with
1400
+ * `laterRaise`, one raise; no shove offered after the first round; and
1401
+ * `shareHistories` and `runoutBuckets: 3`. Ranges, pot, stacks and everything
1402
+ * else carry over, the ranges compressed first with `compressRanges`
1403
+ * (which takes `minWeight` with it). Per-player betting is simplified side
1404
+ * by side.
1405
+ *
1406
+ * Bet and raise cuts (`removeActions`) on the first round carry over, but
1407
+ * for those past `flopMaxRaises`; those below a deal are dropped, as the
1408
+ * later rounds' sizes no longer exist (`LiteSolution.resolve` puts them
1409
+ * back). The caller's own `shareHistories` stands unless `options` give one.
1410
+ */
1411
+ declare function liteConfig(config: SpotConfig, options?: LiteOptions): SpotConfig;
1412
+ /**
1413
+ * Solve `config`'s lite blueprint (`liteConfig`) until its root play settles,
1414
+ * and hand back a re-solver for later streets at the full betting.
1415
+ *
1416
+ * Defaults: `shareHistories` on the river, `runoutBuckets: 3`,
1417
+ * `chanceSampling` at p 0.35, and `settle` with its defaults (every 20
1418
+ * iterations, under 1% of the range moved, twice running).
1419
+ *
1420
+ * Measured (issue #100) on issue #47's betting (0.33 / 0.75 / 1.5 pot, a
1421
+ * 0.75 raise, all-in, three aggressions; pot 55, stack 975, the bench
1422
+ * ranges), so the blueprint plays 0.75 and no raise on the turn and river.
1423
+ * Headless Chromium, `poker-flopsolve/threads`; the clock counts solving
1424
+ * and the settle checks. Root play loss is the EV OOP's root mix and IP's
1425
+ * mix after a check lose at the unshared blueprint's per-action values
1426
+ * (solved to 0.05% of pot), % of pot, with that blueprint's own loss as the
1427
+ * floor; it measures what sharing, sampling and stopping early cost, not
1428
+ * distance to the full game. Re-solve gain is the opponent's best response
1429
+ * against a turn re-solved at the full betting (300 iterations),
1430
+ * under the unshared blueprint's ranges, % of the subgame's pot, weighted
1431
+ * over 3 lines × 3 turns by how often each is reached:
1432
+ *
1433
+ * | flop | settled | Chromium, 1 / 2 / 4 threads | peak RSS | root play loss (floor) | per-hand EV error | re-solve gain (unshared) | re-solve, 1 / 2 / 4 threads |
1434
+ * |---|---|---|---|---|---|---|---|
1435
+ * | As Kh 7d | 400 it | 103 / 59 / 35 s | 511 MiB | 0.023 / 0.014 (0.009 / 0.008) | 0.75 / 0.85 | 3.1 / 2.7 (0.67 / 0.50) | 38 / 22 / 14 s |
1436
+ * | Ts 9s 4h | 320 it | 64 / 38 / 21 s | 426 MiB | 0.118 / 0.076 (0.116 / 0.052) | 0.54 / 0.60 | 4.0 / 3.3 (0.48 / 0.55) | 42 / 23 / 13 s |
1437
+ * | Ks 9s 4s | 360 it | 31 / 19 / 12 s | 253 MiB | 0.059 / 0.037 (0.047 / 0.025) | 1.5 / 1.9 | 3.6 / 3.6 (0.44 / 0.47) | 28 / 17 / 10 s |
1438
+ *
1439
+ * Sampling runs on the threads (issue #99): the same iterations settle the
1440
+ * root on every count, within 0.002% of pot. Unsampled, the rainbow
1441
+ * blueprint took 473 ms an iteration on 4 threads in Node against 251
1442
+ * sampled on one, and settled later. Peak memory counts the page, the
1443
+ * blueprint and a re-solve; it is the most a phone must give. The rainbow root play's loss is
1444
+ * 0.014% of pot over its floor for OOP; `settle: { every: 40, tolerance:
1445
+ * 0.02, patience: 3 }` brings it to 0.009 in 120 s instead of 104 (Node).
1446
+ *
1447
+ * Against exact solves of the full game, which separate what the turn and
1448
+ * river simplification costs:
1449
+ * - issue #51's T₀ on As Kh 7d (0.33 / 0.75 / 1.5 on every street, all-in
1450
+ * raises, two aggressions, solved to 0.22% of pot): OOP's root play lost
1451
+ * 0.072% of pot at T₀'s per-action values, the simplified blueprint
1452
+ * unshared and solved to 0.04% lost 0.057; per-hand root EVs were 3.9 /
1453
+ * 2.9% of pot off, unshared 4.1 / 3.1. Simplifying is the cost; sharing,
1454
+ * sampling and the stop add 0.015. T₀ stores no strategy, so there is no
1455
+ * floor from its own play.
1456
+ * - napkinpoker's postflop-solver solves (issue #87; two flop sizes, 75% on
1457
+ * the turn and river with 3× raises and all-in, weighted BU/CO/SB ranges,
1458
+ * SRP and 3-bet pots, 0.3% of pot), 8 spots across textures, one thread in
1459
+ * Node: root play lost 0.034 / 0.135% of pot on average at the stored
1460
+ * per-action values, where the stored solve's own play lost 0.027 /
1461
+ * 0.131; settled in 38-176 s. Wide single-raised ranges took up to
1462
+ * 452 MiB of storage, near a browser's default `maxBytes` of 512: give it
1463
+ * room, or `compactStorage` with `wasmStorage` (on rainbow, 300 MiB peak
1464
+ * in Node against 411, 27% slower). `minWeight: 0.05` there cut 2-5% of
1465
+ * storage and up to 15% of the time, root play unchanged; it edits the
1466
+ * ranges, so it is the caller's to set.
1467
+ *
1468
+ * `laterRaise`'s cost is on it; the trims `flopMaxRaises` and `noDonk`, and
1469
+ * what was rejected, are in docs/APPROXIMATIONS.md.
1470
+ *
1471
+ * `keepBudget` (issue #113) recovers part of the re-solve gain above, and
1472
+ * stops later (issue #123): `settle`'s tolerance 0.005, not 0.01. With
1473
+ * `keepBudget: 150 * 2 ** 20, precision: 'i16', wasmStorage` (the recipe
1474
+ * issue #101 measured), the same measures, the pick included in the time,
1475
+ * on 4 threads (Chromium; the rest Node):
1476
+ *
1477
+ * | flop | kept, storage | settled | Chromium | peak RSS | root play loss | per-hand EV error | re-solve gain | at tolerance 0.01 |
1478
+ * |---|---|---|---|---|---|---|---|---|
1479
+ * | As Kh 7d | 3 lines, 150 MiB | 580 it | 45 s | 534 MiB | 0.022 / 0.008 | 0.44 / 0.52 | 1.78 / 1.42 | 440 it, 35 s, 2.46 / 1.70 |
1480
+ * | Ts 9s 4h | 6 lines, 141 MiB | 440 it | 29 s | 467 MiB | 0.104 / 0.047 | 0.28 / 0.27 | 1.51 / 1.20 | 320 it, 22 s, 1.78 / 1.24 |
1481
+ * | Ks 9s 4s | all 19, 97 MiB | 460 it | 13 s | 315 MiB | 0.056 / 0.031 | 0.50 / 0.63 | 1.80 / 1.24 | 360 it, 11 s, 2.51 / 1.88 |
1482
+ *
1483
+ * At the old stop, on 1 / 2 / 4 threads in Chromium, As Kh 7d took 123 / 61
1484
+ * / 35 s and peaked at 489 / 509 / 534 MiB, Ts 9s 4h 69 / 37 / 22 s and 437
1485
+ * / 463 / 469, Ks 9s 4s 32 / 19 / 11 s and 290 / 301 / 317; on 4 threads
1486
+ * the later stop adds 16–32% to the time in Chromium (25–31% in Node), the
1487
+ * same peak.
1488
+ *
1489
+ * Root play is as without it; the re-solve gain falls by a third to a half
1490
+ * at the old stop, and the later one takes off 15–28% more for out of
1491
+ * position, 3–34% for in position, still over the unshared blueprint's
1492
+ * 0.4–0.7. The rest is still the stop: the root play settles before the
1493
+ * ranges it brings to the turn do. A stop that also waited for the kept
1494
+ * lines' turn ranges stopped no better than a tighter root tolerance
1495
+ * (`bench/lite/turn-stop.ts`); 0.0035 stopped at 680 / 540 / 540 iterations,
1496
+ * re-solving at 1.57 / 1.30, 1.36 / 1.23 and 1.50 / 1.00 for 39–51% more
1497
+ * time than 0.01. Run to 800 iterations (`settle: false, iterations: 800`),
1498
+ * As Kh 7d re-solves at 1.33 / 1.14 in 59 s in Chromium, peaking at 533
1499
+ * MiB, where plain sharing gives 2.23 / 2.41. A re-solve times as without
1500
+ * it.
1501
+ *
1502
+ * Its memory: the picking solve's WebAssembly memory is freed only once the
1503
+ * caller yields to the event loop, so it stays resident beside the
1504
+ * blueprint's. The pick samples the turn but not the checked-down river,
1505
+ * whose baselines would be most of it (182 MiB resident on As Kh 7d sampled
1506
+ * on both, 56 on the turn alone, the same lines kept on all three flops);
1507
+ * sampling both, rainbow peaked at 661 MiB on 4 threads.
1508
+ */
1509
+ declare function solveLite(config: SpotConfig, options?: SolveLiteOptions): LiteSolution;
1510
+ /**
1511
+ * What {@link solveLite} solves, without solving it: `liteConfig`'s
1512
+ * blueprint, the solve's settings (`iterations` 2000, `settle` at its
1513
+ * defaults, or tolerance 0.005 when `keepBudget` keeps lines, `chanceSampling`
1514
+ * at p 0.35, and the solve options given), and a
1515
+ * report of everything changed against `config`. With `keepBudget` it
1516
+ * does solve: the short picking solve `keepWithin` ranks lines on, whose
1517
+ * kept lines are in the blueprint and the report. For a page that steps its
1518
+ * own run: `createRun(defineSpot(preset.config), preset.options)`, with
1519
+ * `trackSettle(preset.options.settle)` for the stop, and `resolveSubgame` with `bettingFrom(config,
1520
+ * round)` for the re-solves `LiteSolution.resolve` would make.
1521
+ */
1522
+ declare function litePreset(config: SpotConfig, options?: SolveLiteOptions): LitePreset;
1523
+ /**
1524
+ * `blueprint` keeping the lines `options.keepBudget` allows, picked with
1525
+ * `linesWithin` from `options.pickIterations` of `checkedDown(blueprint)`;
1526
+ * `blueprint` itself without a budget. What `solveLite` solves; exported so
1527
+ * a caller stepping its own run can do the same. The picking solve uses
1528
+ * `options`' `workers`, `precision`, `wasmStorage`, `algorithm` and
1529
+ * `sampling`, the last on every round but the checked-down one.
1530
+ */
1531
+ declare function keepWithin(blueprint: SpotConfig, options?: SolveLiteOptions): SpotConfig;
1532
+ /**
1533
+ * `config` with its last round checked down: no bet or all-in there, and
1534
+ * cuts naming that round's actions dropped. Its first rounds are the same
1535
+ * game tree, so how often each line reaches the next round
1536
+ * (`turnLineReach`) comes out much as the real spot's, at a fraction of its
1537
+ * storage: what `solveLite`'s `keepBudget` ranks lines on (issue #101: on
1538
+ * As Kh 7d the lite blueprint so cut stores 57 MiB, against 173, and ranked
1539
+ * the same top 3). `shareHistories.keepLines` is dropped, as it may name
1540
+ * nodes the cut removes.
1541
+ */
1542
+ declare function checkedDown(config: SpotConfig): SpotConfig;
1543
+ /**
1544
+ * `config`'s tree-shaping betting for a subgame opening round `round`: each
1545
+ * setting given per round loses the rounds before it, as
1546
+ * `Solution.subgameAt` does with the spot's own.
1547
+ */
1548
+ declare function bettingFrom(config: SpotConfig, round: number): SubgameBetting;
1549
+ /**
1550
+ * How exploitable a Lite solve's play is in the caller's full game, % of the
1551
+ * pot (issue #154). Lite cannot measure itself: its exploitability is that
1552
+ * of the simplified game, sizes cut, runouts bucketed, histories shared.
1553
+ *
1554
+ * `exact` is a run of the caller's own spot, solved as far as the caller
1555
+ * likes. Every decision of it that `lite` also has takes `lite`'s average
1556
+ * strategy, as a warm start copies it, so an action `lite` lacks there gets
1557
+ * none; the decisions only reachable through such an action (a size Lite
1558
+ * cut, a raise) keep `exact`'s play, the best answer at hand. The figure is
1559
+ * then the exploitability of that strategy: what Lite's own decisions cost,
1560
+ * with no penalty for the ones it never made. `exact`'s own exploitability
1561
+ * is its floor, since what Lite lacks is played no better than `exact`
1562
+ * plays it. A combination Lite left out (`compressRanges`) keeps `exact`'s
1563
+ * play too, so the figure covers only the combinations Lite solved.
1564
+ *
1565
+ * `exact` is spent: its strategy is overwritten, so read anything else from
1566
+ * it first and close it after.
1567
+ *
1568
+ * @param lite the Lite solve, or any solve of the same board
1569
+ * @param exact a run of the full game: same board, unshared histories
1570
+ * @throws if the boards differ or `exact` shares histories
1571
+ */
1572
+ declare function exploitabilityInExact(lite: Solution | SolveRun, exact: SolveRun): number;
699
1573
 
700
1574
  /**
701
1575
  * Postflop Texas Hold'em solver.
@@ -713,6 +1587,13 @@ interface SpotConfig {
713
1587
  readonly board: string;
714
1588
  /** Dead money already in the middle, in chips. */
715
1589
  readonly pot: number;
1590
+ /**
1591
+ * The pot `Solution.ev` and `Solution.handEvs` are percentages of, in
1592
+ * chips. Default `pot`. `Solution.subgameAt` sets it to the original
1593
+ * spot's, so a re-solved turn or river reports in the flop pot and its
1594
+ * values read the same way as the flop's down a hand.
1595
+ */
1596
+ readonly evPot?: number;
716
1597
  /** Effective stack behind, per player, in chips. */
717
1598
  readonly stack: number;
718
1599
  /**
@@ -765,6 +1646,42 @@ interface SpotConfig {
765
1646
  * with 0.1, sizes 0.33 and 0.4 become one 0.365. Default 0, none.
766
1647
  */
767
1648
  readonly mergeSizes?: number;
1649
+ /**
1650
+ * Bets, raises and shoves to cut from the tree, with everything below
1651
+ * them: each the readable path of the node the action leads to, exactly as
1652
+ * `Solution.path` writes it — `"check bet 18.15"`, `"bet 41.25 raise
1653
+ * 133.31"`, `"check check / bet 18.15"`, chips being the actor's total
1654
+ * investment after the action and `/` a deal. Only the line named goes; the
1655
+ * same size elsewhere stays. Checks, calls and folds cannot be cut, and a
1656
+ * path that names no such action in the tree is refused.
1657
+ *
1658
+ * For a budgeted tree: keep three sizes where they earn their memory, one
1659
+ * where they do not. A tree's memory is almost all on the river, and each
1660
+ * flop or turn action multiplies the river subtrees below it, so cutting a
1661
+ * line saves what its whole subtree stores. Default none; unset, the tree
1662
+ * is the one the other settings build, unchanged.
1663
+ */
1664
+ readonly removeActions?: readonly string[];
1665
+ /**
1666
+ * Thin the bet sizes to a shape that keeps most of what the full ones are
1667
+ * worth in a fraction of the memory. Every size stays at the root, where
1668
+ * out of position opens the first round. Everywhere else a decision keeps
1669
+ * one bet, raise or shove: the one nearest three quarters of the pot, a
1670
+ * shove where that would be one. Opening the last round after an earlier
1671
+ * round saw a bet, sizes above the pot and the shove stay as well.
1672
+ *
1673
+ * The shape is what growing sizes one at a time by their value per byte
1674
+ * picked on As Kh 7d and Ks 9s 4s (issue #51). Measured on As Kh 7d, pot
1675
+ * 55, stack 975, sizes 0.33 / 0.75 / 1.5 with shove-only raises and two
1676
+ * aggressions: see the #51 entry in docs/APPROXIMATIONS.md for its memory and error.
1677
+ * It is a fixed rule, so it costs nothing to apply. A subgame from
1678
+ * `Solution.subgameAt` gets the full sizes back unless its betting sets
1679
+ * this again, and then it is thinned as a tree of its own: bets on the
1680
+ * streets before it do not count, so a river after a bet on the flop
1681
+ * keeps only the 0.75 size, where the whole tree also kept its big sizes
1682
+ * and shove. Default false; unset, the tree is unchanged.
1683
+ */
1684
+ readonly thinSizes?: boolean;
768
1685
  /** Refuse a range wider than this many combinations. */
769
1686
  readonly maxCombos?: number;
770
1687
  /**
@@ -803,6 +1720,248 @@ interface SpotConfig {
803
1720
  * strategy in the real game, every card dealt. Default false.
804
1721
  */
805
1722
  readonly runoutBuckets?: boolean | number;
1723
+ /**
1724
+ * Share river storage between betting histories that reach the same pot,
1725
+ * a lossy approximation for fitting a spot in memory (issue #49). Off by
1726
+ * default.
1727
+ *
1728
+ * Every earlier line gets its own copy of the streets below it, yet with
1729
+ * pot-fraction sizes many lines meet: check, bet, call and bet, call
1730
+ * reach the same pot, and so does every raise line taken in either order.
1731
+ * Their subtrees are identical, so their nodes keep one set of regrets and
1732
+ * strategy sums. Each history is still walked with its own reach, so an
1733
+ * iteration costs exactly what it did; only storage shrinks. On the
1734
+ * three-size target spot (AsKh7d, pot 55, stack 975, sizes 33/75/150%, a
1735
+ * 75% raise and all-in, three aggressions) 173 river starts collapse to 23
1736
+ * and storage falls 5.9 times: 17.2 GiB to 2.9 at 32 bits, 8.7 to 1.5 at 16.
1737
+ * There, at 16 bits, a Node solve peaked at 1.6 GiB on one thread and 2.0
1738
+ * on four (30 s an iteration), and was 12% of pot exploitable after 150
1739
+ * iterations.
1740
+ *
1741
+ * What is lost is recall: a player plays one strategy for every line that
1742
+ * met, though the ranges each line brings differ. Each history's regret is
1743
+ * weighted by how often the acting hand plays into it, which cut the cost
1744
+ * fourfold against plain CFR's sum. Measured on AsKh7d, pot 55, stack
1745
+ * 975, against the exact solve, 4 threads: with sizes 33/75/150%, an
1746
+ * all-in raise and two aggressions, 5.8 GiB became 1.22 GiB, and after
1747
+ * 400 iterations the strategy was 8.0% of pot exploitable, with
1748
+ * per-combination root EVs 0.72% of pot off on average and 2.5% at worst
1749
+ * (the exact solve: 0.28%). With one 50% size, 4.0% exploitable after
1750
+ * 300 iterations, EVs 0.67% off on average and 6.8% at worst.
1751
+ * Exploitability is measured in the full game, which the strategy covers
1752
+ * node by node, so it is exact. Do not expect it to approach
1753
+ * equilibrium: expect a strategy several percent of the pot from it, in
1754
+ * a spot that otherwise does not fit.
1755
+ *
1756
+ * Two consequences of one block serving several histories, both part of
1757
+ * the approximation: within an iteration, a history visited later plays
1758
+ * the regrets an earlier one has already updated, so the result depends a
1759
+ * little on the order of the tree; and under `algorithm: 'cfr+'` each
1760
+ * history's update is clamped at zero on its own, rather than their sum.
1761
+ * A spot with it can warm-start only from a solve that shares too.
1762
+ *
1763
+ * On issue #47's blueprint (issue #85; T's flop betting, one 0.75 bet on
1764
+ * the turn and river with no raise, `runoutBuckets: 3`) it saves 4.1 times
1765
+ * on rainbow, two-tone and monotone flops alike, because the flop's sizes
1766
+ * and raises still meet at a few turn pots: 196 river decisions keep 44
1767
+ * blocks. On AsKh7d 707 MiB becomes 173 at 32 bits, so the blueprint stays
1768
+ * on the WebAssembly engine; in Chromium on 4 threads the tab peaked at
1769
+ * 327 MiB, against 860 unshared. An iteration costs what an unshared one
1770
+ * does (458 ms there). Exploitability stops falling near 2.7% of pot by
1771
+ * 160 iterations and never reaches 0.3%; the root play goes on settling.
1772
+ * Judged at the unshared blueprint's own per-action values (solved to
1773
+ * 0.045%), after 300 iterations (138 s) its root play lost 0.011% of pot
1774
+ * where the unshared blueprint's lost 0.008%, but at 60 s it was 0.054%:
1775
+ * the unshared one needs 115 s to reach 0.3% itself. Per-hand root EVs
1776
+ * came out 0.4–0.6% of pot from the unshared ones (2–3% at worst), and
1777
+ * turns re-solved from it with T's betting gave the opponent 2.2–3.0% of
1778
+ * their pot under the unshared ranges, against 0.5–0.7% from the unshared
1779
+ * blueprint. `chanceSampling` composes: on one thread 238 ms an iteration,
1780
+ * the root settled in 109 s, 453 MiB; on 4 threads (issue #99) 70 ms, the
1781
+ * root settled in 33 s at the same iteration, 452 MiB. `coarseStart` composes
1782
+ * but finds no coarser copy at a gap of 3. `bench/blueprint-share/` has
1783
+ * the scripts and figures.
1784
+ *
1785
+ * Where a shared solve stops depends on its first few iterations (issue
1786
+ * #105). A shared block plays one strategy for every history meeting in
1787
+ * it, so the game has many stable points, and which one the solve settles
1788
+ * on is decided early, when regret matching plays nearly pure. Any
1789
+ * randomness then picks another: chance sampling, 8-bit stochastic
1790
+ * rounding, even float rounding under CFR+. On #103's turn spot
1791
+ * (exploitability 5.8% of pot), sampling at p 0.9 ended at 0.3–1.6%
1792
+ * over six different sets of draws. On a second turn spot (0.7%) it
1793
+ * changed nothing. On the blueprint above, neither sampling at p 0.9
1794
+ * (2.9%) nor 8-bit stochastic storage (2.5%) moved the plateau beyond
1795
+ * that spread, against 2.6% shared alone. Do not count on noise to
1796
+ * lower it. Of the deterministic changes tried (other regret
1797
+ * weighting, discount start, uniform play mixed into the first
1798
+ * iterations), none was a reliable gain. `bench/share-noise/` has the
1799
+ * measurements.
1800
+ *
1801
+ * `true` shares the river. See `ShareHistories` for the turn and for
1802
+ * lossier buckets.
1803
+ */
1804
+ readonly shareHistories?: boolean | ShareHistories;
1805
+ /**
1806
+ * Store regrets and strategy sums at 8 bits — an approximation, off by
1807
+ * default. See `CompactStorage`. Set here rather than on the solve because it
1808
+ * decides how much memory the spot needs, which `maxBytes` is checked
1809
+ * against when the spot is defined.
1810
+ */
1811
+ readonly compactStorage?: CompactStorage;
1812
+ }
1813
+ /**
1814
+ * Compact storage (issue #50): accumulators as 8-bit integers, each hand on
1815
+ * each board scaled by its own power of two, instead of 32- or 16-bit
1816
+ * values. Regret matching and the average strategy both divide a hand's
1817
+ * values by their own total, so a per-hand scale cancels wherever a strategy
1818
+ * is read and costs only a byte per hand. Rounding is at random, with odds
1819
+ * set by the remainder, so every stored value is right on average; the
1820
+ * randomness is a hash of the slot and iteration, so a solve is deterministic
1821
+ * at any thread count.
1822
+ *
1823
+ * Two modes:
1824
+ *
1825
+ * - With strategy sums (the default): regrets and sums at 8 bits, about 2.75
1826
+ * bytes a slot against 16-bit storage's 4 and 32-bit's 8. Measured, it
1827
+ * converges like the full solve: on the bench flop (AsKh7d, one size) 0.18%
1828
+ * of pot at 80 iterations against 0.18%, 0.058% at 160 against 0.052%; on
1829
+ * the monotone flop with three sizes (Ks9s4s, issue #20's T₀) 1.87% at 160
1830
+ * against 1.85%. Rounding the sums leaves a floor, near 0.03% of pot on the
1831
+ * bench flop and 0.1% on a small, narrow-range spot. On issue #20's T₀
1832
+ * (AsKh7d, three sizes, all-in raise, SPR 18), at 320 iterations it was
1833
+ * 0.81% of pot exploitable where 32-bit storage was 0.69%, per-hand root
1834
+ * EVs 0.23% of pot off a 0.17% reference, every hand's preferred bet size
1835
+ * kept, in 1.75 GiB where 32-bit storage took 5.1 and 16-bit 2.6. T itself
1836
+ * takes 5.9 GiB, 16-bit storage 8.7.
1837
+ * - `sums: false`: no strategy sums, so each node's strategy, wherever one is
1838
+ * read (`strategyAt`, `reachAt`, EVs, exploitability), is the current
1839
+ * profile, the regret-matched strategy the next iteration plays. About 1.4
1840
+ * bytes a slot, 1.03 with `blockScale`: T in 2.2 GiB. Per-hand root EVs stay as close as
1841
+ * the average's, as `currentProfileEv` found, but the strategy is far more
1842
+ * exploitable: 2 times at equal iterations on the bench flop, 5 to 8 times
1843
+ * on deeper or narrower spots (T₀ monotone: 4.0% of pot at 320 iterations
1844
+ * against 0.71%), and the bet size each hand prefers at the root agreed with
1845
+ * the reference for 62-82% of the hands where it was clear, against all of
1846
+ * them for the average. `algorithm: 'cfr+'`, whose current profile swings
1847
+ * less, is the better rule for the strategy; DCFR's current profile gives
1848
+ * the closer EVs (on T₀ monotone 0.55% of pot against the average's 1.19%,
1849
+ * but 4.9% exploitable).
1850
+ *
1851
+ * Rounding regrets to 8 bits costs training almost nothing: with 32-bit
1852
+ * regrets and no sums (`float`) the same runs were no better.
1853
+ *
1854
+ * Training is otherwise the exact solve's; exploitability is measured
1855
+ * exactly, in the full tree. Storage is split in chunks under `chunkBytes`,
1856
+ * because browsers refuse a buffer of 2 GiB. Runs on the JavaScript engine
1857
+ * and its Node worker threads, where an iteration costs about 1.5 times a
1858
+ * 32-bit one, or on the WebAssembly engine, threads included, with
1859
+ * `SolveOptions.wasmStorage` (issue #84). Not with `analysisOnly`, which
1860
+ * loads float32 sums. `precision` sets the rounds before `from`; a warm
1861
+ * start, a coarse start or `runoutBuckets`' measure of the real game reads
1862
+ * and writes compact storage, rounded to nearest; `chanceSampling` applies
1863
+ * its DCFR catch-up to compact nodes too.
1864
+ *
1865
+ * With `shareHistories`, a node sharing another's storage shares its compact
1866
+ * storage too; together they fit issue #20's target T in 0.99 GiB (0.37
1867
+ * without sums). Measured on T₀ at 160 iterations, compact storage did not
1868
+ * add to sharing's own loss: 9.0% of pot exploitable against 9.5%, root EVs
1869
+ * 0.63% of pot off against 0.66%, and all clear bet-size choices kept
1870
+ * against 97%, in a third of the memory.
1871
+ *
1872
+ * What was measured and left out is with the other approximations, in the
1873
+ * comment inside `Approximations`.
1874
+ */
1875
+ interface CompactStorage {
1876
+ /**
1877
+ * Keep 8-bit strategy sums, and with them the average strategy. Default
1878
+ * true; false stores only regrets and plays the current profile.
1879
+ */
1880
+ readonly sums?: boolean;
1881
+ /**
1882
+ * With `sums: false`, one scale per node and board instead of one per
1883
+ * hand: about 1.03 bytes a slot instead of 1.4. Under CFR+ it measured
1884
+ * nearly as accurate (0.077% of pot against 0.064% on the bench flop at
1885
+ * 320 iterations); under DCFR, whose large negative regrets then crowd
1886
+ * the scale, clearly less (0.16% against 0.08%).
1887
+ */
1888
+ readonly blockScale?: boolean;
1889
+ /**
1890
+ * First round stored compactly, from the spot's first (0); earlier rounds
1891
+ * keep 32-bit regrets and sums. Default 0. With `sums: false`, an earlier
1892
+ * round's average above the current profile measured worse than the
1893
+ * current profile throughout (0.053% of pot against 0.035% on the bench
1894
+ * flop): the two come from different iterations.
1895
+ */
1896
+ readonly from?: number;
1897
+ /**
1898
+ * Largest single buffer to allocate, in bytes; storage is split in chunks
1899
+ * no bigger, a node never split. Default 1 GiB: Chromium refuses an
1900
+ * ArrayBuffer of 2 GiB, but gives several smaller ones.
1901
+ */
1902
+ readonly chunkBytes?: number;
1903
+ /** For measurement: the largest regret magnitude stored, at most 127. */
1904
+ readonly steps?: number;
1905
+ /** For measurement: round regrets to nearest instead of at random. */
1906
+ readonly nearest?: boolean;
1907
+ /** For measurement, with `sums: false`: keep 32-bit regrets, dropping only the sums. */
1908
+ readonly float?: boolean;
1909
+ }
1910
+ /** See `SpotConfig.shareHistories`. */
1911
+ interface ShareHistories {
1912
+ /**
1913
+ * Lines whose later streets keep storage of their own, each named as
1914
+ * `Solution.path` names a node (a flop line opening the turn reads like
1915
+ * `"check check /"`). Every node at or below a listed one is left out of
1916
+ * sharing, and so is any round root above one. The rest share as
1917
+ * before. Unset or empty, nothing is kept. A warm start into a spot that
1918
+ * differs only here, keeping at least the lines its source keeps,
1919
+ * carries the average strategy too, as for the same spot.
1920
+ *
1921
+ * What it is for (issue #101): a turn re-solved from a shared blueprint
1922
+ * (`resolveSubgame`) inherits only the ranges the blueprint brings to
1923
+ * it, and sharing distorts those. Its flop play is stored unshared, but
1924
+ * it learns from river values that several histories share. Keeping the
1925
+ * few most-reached flop lines unshared gives the flop exact values
1926
+ * where most of the play is, and that straightens the ranges on the
1927
+ * lines left shared too. Pick them with `linesWithin` (the most-reached
1928
+ * lines, `turnLineReach`, that a storage budget allows) from a short
1929
+ * solve, 80 iterations, of a cheap copy of the spot (below); close that
1930
+ * and solve the hybrid spot from cold. Continuing from the picking solve
1931
+ * instead is worse: its average lingers.
1932
+ *
1933
+ * Measured on issue #47's blueprint (`1size-b3`), 400 iterations, against
1934
+ * the unshared blueprint solved to 0.045% of pot. "Re-solve gain" is the
1935
+ * opponent's best response to an unsafe turn re-solve at the full
1936
+ * three-size betting, under the unshared blueprint's ranges, in % of the
1937
+ * subgame pot, weighted by line reach, refining OOP / IP; the unshared
1938
+ * blueprint's own re-solves give 0.67 / 0.50. On AsKh7d:
1939
+ *
1940
+ * | kept | storage, f32 | re-solve gain | root EV error, mean |
1941
+ * |---|---|---|---|
1942
+ * | none (plain sharing) | 173 MiB | 3.05 / 2.15 | 0.57 / 0.46 |
1943
+ * | top 1 | 201 MiB | 2.48 / 1.58 | 0.46 / 0.53 |
1944
+ * | top 3 | 285 MiB | 1.10 / 0.83 | 0.24 / 0.21 |
1945
+ * | top 6 | 383 MiB | 1.16 / 0.65 | 0.23 / 0.27 |
1946
+ * | all (unshared) | 707 MiB | 0.67 / 0.50 | 0 |
1947
+ *
1948
+ * On Ts9s4h and Ks9s4s plain sharing gives 4.10 / 3.69 and 4.23 /
1949
+ * 2.72 against 0.48 / 0.55 and 0.44 / 0.47 unshared. Kept by a 300 MiB
1950
+ * budget (`linesWithin`), two-tone keeps 6 lines in 282 MiB for 0.61 /
1951
+ * 0.72, and monotone all 19 in 187 MiB. The top 3 alone are not enough
1952
+ * on two-tone (1.82 / 1.96), so budget the storage, not the count.
1953
+ *
1954
+ * In Chromium the picking solve's WebAssembly memory stays resident
1955
+ * until it is collected, so it adds to the peak. Rank on a cheap copy
1956
+ * instead: the blueprint with its river checked down (57 MiB on AsKh7d)
1957
+ * ranked the same top 3 there. Within 512 MiB on AsKh7d, store the
1958
+ * hybrid at 16 bits (`precision: 'i16'` with `wasmStorage`) with a 150
1959
+ * MiB budget at that precision. It keeps the same 3 lines, re-solves at
1960
+ * 1.47 / 0.92, and peaked at 392 MiB on 4 threads, 592 ms an iteration
1961
+ * against 495 shared, its root play settled in 127 s. Two-tone the same
1962
+ * way: 0.88 / 0.85. `bench/blueprint-share/` has the scripts and figures.
1963
+ */
1964
+ readonly keepLines?: readonly string[];
806
1965
  }
807
1966
  /** Projected cost of solving a spot. */
808
1967
  interface Estimate {
@@ -822,6 +1981,8 @@ interface Estimate {
822
1981
  * that does not fit at 32 bits is solved with.
823
1982
  */
824
1983
  readonly compressedBytes: number;
1984
+ /** Storage with `compactStorage`, which `maxBytes` is then checked against; else null. */
1985
+ readonly compactBytes: number | null;
825
1986
  readonly secondsPerThousandIterations: number;
826
1987
  /** Whether the spot fits `maxBytes` at 16 bits or better. */
827
1988
  readonly fits: boolean;
@@ -844,6 +2005,8 @@ interface Spot {
844
2005
  readonly stackUnits: number;
845
2006
  /** The configuration this was built from, so a worker can rebuild it. */
846
2007
  readonly source: SpotConfig;
2008
+ /** Each node's storage owner under `shareHistories`; unset without it. */
2009
+ readonly historyAlias?: Int32Array;
847
2010
  /**
848
2011
  * Find the stored board standing for a real one, and how hands relabel
849
2012
  * onto it. Board indices everywhere else — `strategyAt`, `reachAt`,
@@ -889,10 +2052,29 @@ interface SolveOptions {
889
2052
  * `nextCheck`. Setting this forces a fixed cadence instead.
890
2053
  */
891
2054
  readonly exploitEvery?: number;
2055
+ /**
2056
+ * Stop once the root play stops moving (issue #100): every `every`
2057
+ * iterations (default 20) read the average strategy at the root and at in
2058
+ * position's decision after a check, and stop once it has moved less than
2059
+ * `tolerance` (default 0.01: 1% of the range's mass, total variation
2060
+ * weighted by range) at `patience` checks in a row (default 2).
2061
+ * `stoppedAt` is then 'settled'. `rootPlayMovement` defines the measure.
2062
+ *
2063
+ * For solves that never reach an exploitability target, such as a
2064
+ * blueprint with `shareHistories`, which plateaus several percent of the
2065
+ * pot out while its first decisions go on settling (issue #85). A check
2066
+ * reads two nodes' strategies and no best-response pass, so it costs
2067
+ * almost nothing; with it, `Progress.exploitability` is NaN unless
2068
+ * `targetPercent` is set too, which then measures at every check and
2069
+ * stops on whichever comes first. `exploitEvery` is ignored. Measured
2070
+ * costs are in `solveLite`'s notes. Unset, off.
2071
+ */
2072
+ readonly settle?: SettleOptions;
892
2073
  readonly onProgress?: (info: Progress) => void;
893
2074
  /**
894
2075
  * Accumulator storage. Unset, 'f32' — what the WebAssembly engine runs —
895
- * or 'i16' for a spot too big for it under `maxBytes`. 'f64' is there on
2076
+ * or 'i16' for a spot too big for it under `maxBytes` (beside chance
2077
+ * sampling's baselines, when `approximations.chanceSampling` is on). 'f64' is there on
896
2078
  * request and runs the JavaScript engine; measured, it buys no accuracy
897
2079
  * an exploitability target can see.
898
2080
  *
@@ -916,7 +2098,9 @@ interface SolveOptions {
916
2098
  * exploitability, so never the largest error in the answer, but do not
917
2099
  * expect two worker counts to agree bit for bit.
918
2100
  *
919
- * The browser build is single-threaded: any count resolves to 1 there.
2101
+ * The browser build is single-threaded unless `enableThreads` from
2102
+ * `poker-flopsolve/threads` has started its workers; any count above what
2103
+ * is available resolves to what is, with one warning.
920
2104
  */
921
2105
  readonly workers?: number | 'auto';
922
2106
  /**
@@ -955,6 +2139,24 @@ interface SolveOptions {
955
2139
  * instead of 125.
956
2140
  */
957
2141
  readonly warmStart?: Solution | SolveRun;
2142
+ /**
2143
+ * For a `warmStart` from a solve of a different board: each card of this
2144
+ * spot's deck to the card of the old spot's it plays as, a permutation of
2145
+ * the 52 cards taking this board onto the old one. A rank swap (`6` and
2146
+ * `7` in every suit, say) carries a solve of AsKh6d onto AsKh7d with every
2147
+ * hand keeping its role: 66 there is 77 here (`rankSwap` builds that map).
2148
+ * Hands and runouts relabel through it; whatever the old ranges lacked
2149
+ * starts cold. Unset, a warm start must come from the same board. The
2150
+ * average strategy never carries over through it, even for a relabelling
2151
+ * that leaves the game unchanged: only regrets do.
2152
+ *
2153
+ * Measured on the bench flop (AsKh7d, single-threaded, to 0.5% of pot):
2154
+ * 52 iterations cold, 8 warm from a 0.1% solve of AsKh6d, 20 from AsQh7d.
2155
+ * It pays only when the whole old solve is at hand: seeding the flop's
2156
+ * decisions alone, as a downloadable library could, saved at most 15%
2157
+ * (see `Approximations`).
2158
+ */
2159
+ readonly warmCards?: Uint8Array;
958
2160
  /**
959
2161
  * The iteration to carry on counting from, which sets how heavily DCFR
960
2162
  * discounts the inherited regrets and how CFR+ weights the averages. Unset,
@@ -976,13 +2178,147 @@ interface SolveOptions {
976
2178
  readonly simd?: boolean;
977
2179
  /**
978
2180
  * Which traversal runs. Unset, the WebAssembly engine wherever it applies
979
- * — one thread, 32-bit storage, WebAssembly SIMD available — and the
980
- * JavaScript one otherwise. 'js' forces JavaScript, to compare the two.
2181
+ * — 32-bit storage (or 16-bit and compact with `wasmStorage`), WebAssembly
2182
+ * SIMD available — and the JavaScript one otherwise. 'js' forces
2183
+ * JavaScript, to compare the two.
981
2184
  */
982
2185
  readonly engine?: 'js';
2186
+ /**
2187
+ * 16-bit and compact storage on the WebAssembly engine (issue #84): pass
2188
+ * `wasmStorage` from `poker-flopsolve/wasm-storage`. With it, a solve at
2189
+ * `precision: 'i16'` or of a `compactStorage` spot runs on the engine,
2190
+ * threads included, rather than on JavaScript. Its updates are the
2191
+ * JavaScript ones, step for step, worked in 32-bit floats rather than
2192
+ * 64-bit ones, so a stored value differs only where it lies within float32
2193
+ * precision of a rounding boundary; the random rounding hashes the same
2194
+ * slot and iteration, read to 24 bits rather than 32. Compact scales
2195
+ * below 2^-126 (regrets under 10^-35) are taken as 0. Unset, those solves run on
2196
+ * JavaScript as before; 32-bit solves run on the default engine either
2197
+ * way, and `precision: 'f64'` on JavaScript.
2198
+ */
2199
+ readonly wasmStorage?: WasmStorage;
983
2200
  }
984
2201
  /** See `SolveOptions.approximations`. */
985
2202
  interface Approximations {
2203
+ /**
2204
+ * Solve a coarser copy of the spot first and start the real one from its
2205
+ * regrets — coarse to fine, as multigrid methods do. The copy buckets
2206
+ * turn and river cards like `runoutBuckets`, so each of its iterations
2207
+ * is cheaper (a flop stores ~40% fewer runouts at a gap of 3), and its
2208
+ * equilibrium is close enough to the real one's that the real solve picks
2209
+ * up roughly where it left off. The answer is still the real spot's: the
2210
+ * coarse game only chooses where it starts, and exploitability and
2211
+ * `targetPercent` measure the real game. Unset, off.
2212
+ *
2213
+ * Measured on three flop spots in Chromium, one thread, stopped at 15 s,
2214
+ * with 40 coarse iterations (issue #24): root-EV error per combination
2215
+ * against a 0.1%-of-pot reference fell from 1.51% to 0.19% of pot on
2216
+ * AsKh7d (exploitability 0.94% to 0.40%), and 0.26% to 0.06% on the
2217
+ * wider bench flop. A monotone flop, which a cold solve already settles
2218
+ * within 15 s, reached 0.5% error in half the time but ended a little
2219
+ * looser, 0.11% against 0.04%. To an exploitability target in Node it
2220
+ * was faster on all three: 0.1% on the monotone flop in 14.5 s instead of
2221
+ * 15.3, 0.2% on the wide one in 15.5 instead of 19.3, 0.3% on AsKh7d in
2222
+ * 23.8 instead of 31.5. Around 40 iterations suits a flop; far fewer
2223
+ * leave the coarse solve too rough to help, far more spend the time
2224
+ * where the real solve would have spent it better.
2225
+ *
2226
+ * Carrying the coarse average strategy, restarting DCFR's count (a
2227
+ * `warmIteration` of 0 or 10), a bucket gap of 1, or forbidding donk bets
2228
+ * in the coarse spot were measured too, and were all worse.
2229
+ *
2230
+ * The coarse iterations count toward `totalIterations`, not `completed`
2231
+ * or `Solution.iterations`; DCFR carries on counting from them unless
2232
+ * `warmIteration` says otherwise. Both solves are in memory at the
2233
+ * switch, the coarse one about 60% the size of the real one on a flop.
2234
+ * Where bucketing folds no runouts together — a river spot, ranges with no rank symmetry — it does
2235
+ * nothing. Not with `warmStart`, which it already is. The coarse solve
2236
+ * runs inside `createRun`, all at once and without progress reports, so
2237
+ * a caller stepping a run to stay responsive should keep it short; it
2238
+ * must fit in what `maxBytes` leaves beside the real spot, at 16 bits if
2239
+ * not 32, or `createRun` refuses. With `precision` unset, a real spot
2240
+ * whose 32-bit storage leaves no room for the coarse one is solved at 16
2241
+ * bits, the coarse one too (issue #148; on the JavaScript engine unless
2242
+ * the solve passes `wasmStorage`).
2243
+ */
2244
+ readonly coarseStart?: CoarseStart;
2245
+ /**
2246
+ * Report `Solution.ev` and `Solution.handEvs` under the current profile —
2247
+ * the regret-matched strategy the next iteration would play — instead of
2248
+ * the average strategy. Default off. Measured under DCFR, the default
2249
+ * update rule; it applies to CFR+ alike.
2250
+ *
2251
+ * Measured against a solve to 0.045% of pot, after a 15 s single-threaded
2252
+ * browser budget, the current profile's per-hand root EVs had a mean error
2253
+ * of 1.23% of pot where the average's had 2.18% (flop As Kh 7d), 0.11%
2254
+ * against 0.37% (monotone Ks 9s 4s) and 1.40% against 2.02% (wide Qs Jh
2255
+ * 2c). Across those three spots it was the closer one at 62 of 65
2256
+ * checkpoints from 15 s down to 0.1% exploitability, often by 2–4 times.
2257
+ * It costs the same one pass per player as reading the average's EVs.
2258
+ *
2259
+ * Those EVs then belong to a different profile from the strategy
2260
+ * `strategyAt` and `reachAt` show, which stays the average: the average is
2261
+ * what converges to equilibrium and what exploitability measures, while
2262
+ * the current profile's values happen to settle sooner. Read them as the
2263
+ * better estimate of the equilibrium's EVs, not as the EVs of the strategy
2264
+ * on screen. A run with `analysisOnly` has no regrets and cannot use this.
2265
+ */
2266
+ readonly currentProfileEv?: boolean;
2267
+ /**
2268
+ * Chance sampling with baselines (VR-MCCFR; Schmid et al., 2019). Each
2269
+ * training iteration walks each turn and river deal with probability `p`
2270
+ * (default 0.35, both rounds). A deal left out adds the per-hand values it
2271
+ * returned when last walked, its baseline; a walked deal adds
2272
+ * `b + (v - b) / p` and its values become the new baseline. DCFR discounts
2273
+ * a skipped subtree missed are applied when it is next walked. This is
2274
+ * what made sampling pay where the plain 1/p weighting (docs/APPROXIMATIONS.md) did not:
2275
+ * the correction only carries how much a deal's values moved since its
2276
+ * last walk, which is small.
2277
+ *
2278
+ * Iterations get several times cheaper and take 2–5 times as many to a
2279
+ * target, so the net is about 1.2–1.5 times faster to 0.3% of pot, and
2280
+ * per-hand root EVs come out closer to the true ones at the same
2281
+ * exploitability. Measured single-threaded in Node against the exact
2282
+ * solve, time to 0.3% of pot (to 1%): AsKh7d 23.7 s → 15.9 s (13.3 → 9.0),
2283
+ * Ks9s4s 6.0 → 4.3 (3.4 → 2.3), the README's wide flop 13.4 → 9.3
2284
+ * (7.5 → 5.3), and pairs-and-broadway ranges on AsKh7d 16.7 → 12.9 and on
2285
+ * Ks9s4s 5.5 → 4.5. Exploitability is measured exactly, in the full game.
2286
+ *
2287
+ * Costs: one float per hand per stored deal per chance node, 6–31 MB on
2288
+ * those flops (about 12–20% beside their storage), counted against
2289
+ * `maxBytes`. Any storage: 32-, 64- or 16-bit, or `compactStorage`
2290
+ * over 32 or 16 bits (16-bit since issue #102, with the same DCFR
2291
+ * catch-up, in both engines).
2292
+ *
2293
+ * Threads (issue #99): it runs on `workers` threads, in the JavaScript
2294
+ * pool and on the WebAssembly engine's threads alike. Threads split the
2295
+ * runouts as for an exact solve, and the state sampling keeps (baselines,
2296
+ * when each deal was last walked, when each block was last updated for
2297
+ * the catch-up) lives in shared memory, each thread's runouts' entries
2298
+ * its own. There is no per-thread random stream: whether a deal is walked
2299
+ * on an iteration is a hash of its chance node, the deal and the
2300
+ * iteration, in both engines, so every thread count walks the same deals
2301
+ * on the same iterations. A fixed count is then bitwise repeatable, and
2302
+ * different counts differ only as unsampled ones do (see `workers`). A
2303
+ * spot sampling a round above the threads' split, which no flop or turn
2304
+ * spot has, runs on one thread. Measured in Chromium on issue #47's
2305
+ * blueprint, 4 threads ran 3.1–3.2 times faster than 1 on three flops,
2306
+ * and the shared AsKh7d blueprint's root play settled in 33 s against
2307
+ * 105 s (`bench/blueprint-share/README.md`). With `targetPercent`, a sampled solve runs more
2308
+ * iterations, so it makes a few more exploitability checks.
2309
+ * Off, nothing changes; at `p: 1` it is the exact solve, bit for bit.
2310
+ */
2311
+ readonly chanceSampling?: SamplingOptions;
2312
+ }
2313
+ /** See `Approximations.coarseStart`. */
2314
+ interface CoarseStart {
2315
+ /** Iterations of the coarse spot to run before the real one. */
2316
+ readonly iterations: number;
2317
+ /**
2318
+ * The coarse spot's `runoutBuckets`, at least the spot's own. Default 3;
2319
+ * a wider gap folds more runouts only where the ranges allow it.
2320
+ */
2321
+ readonly runoutBuckets?: number;
986
2322
  }
987
2323
  type Algorithm = 'cfr+' | 'dcfr';
988
2324
  type Precision = 'f64' | 'f32' | 'i16';
@@ -994,9 +2330,14 @@ declare const PRECISION_BYTES: {
994
2330
  };
995
2331
  interface Progress {
996
2332
  readonly iteration: number;
2333
+ /** In chips; NaN at a `settle` check made without `targetPercent`. */
997
2334
  readonly exploitability: number;
998
2335
  readonly elapsedMs: number;
2336
+ /** With `settle`: how far the root play moved since the last check (`rootPlayMovement`), NaN at the first. */
2337
+ readonly movement?: number;
999
2338
  }
2339
+ /** Which stopping rule ended a solve: see `Solution.stoppedAt`. */
2340
+ type StopReason = 'target' | 'iterations' | 'settled';
1000
2341
  /** A solved spot. */
1001
2342
  interface Solution {
1002
2343
  readonly spot: Spot;
@@ -1007,15 +2348,52 @@ interface Solution {
1007
2348
  /**
1008
2349
  * Which stopping rule ended the solve. 'iterations' with a `targetPercent`
1009
2350
  * set means the target was NOT reached and the answer is looser than asked
1010
- * for — worth surfacing rather than swallowing.
2351
+ * for — worth surfacing rather than swallowing. 'settled' is
2352
+ * `SolveOptions.settle`'s: the root play stopped moving.
1011
2353
  */
1012
- readonly stoppedAt: 'target' | 'iterations';
2354
+ readonly stoppedAt: StopReason;
1013
2355
  /** Worker threads the solve actually used, which 'auto' does not tell you. */
1014
2356
  readonly workers: number;
1015
2357
  /** The solver behind this solution, for analysis and warm starts. */
1016
2358
  readonly solver: Solver;
1017
- /** Chips per hand for a player, under the average strategy. */
2359
+ /**
2360
+ * The pot, in chips, that `ev` and `handEvs` are percentages of:
2361
+ * `SpotConfig.evPot`, which defaults to the spot's own `pot` (rounded to
2362
+ * chip units, as the tree holds it). A subgame
2363
+ * from `subgameAt` carries the original spot's.
2364
+ */
2365
+ readonly evPot: number;
2366
+ /**
2367
+ * A player's share of the pot, in percent of `evPot`: what they win on
2368
+ * average per hand, `100 × (evChips + evPot / 2) / evPot`. Folding, or
2369
+ * losing every showdown, is 0; winning the pot uncontested is 100; the
2370
+ * two players' values add up to 100. In a subgame, whose own pot holds
2371
+ * chips both players put in earlier, folding at its root reads below 0:
2372
+ * the earlier chips given up, as a share of `evPot`. Under the average
2373
+ * strategy, or the current profile with `approximations.currentProfileEv`.
2374
+ */
1018
2375
  ev(player: 0 | 1): number;
2376
+ /**
2377
+ * `ev` in chips per hand, against a baseline where each player already
2378
+ * owns half the pot: folding is worth −pot/2 and the players' values add
2379
+ * up to 0. The same baseline at every round, since a round opens with
2380
+ * both players level. `Solver.valuesAt` and the traversal use it.
2381
+ */
2382
+ evChips(player: 0 | 1): number;
2383
+ /** `handEvs` in chips on `evChips`'s half-pot baseline. Returns a fresh copy. */
2384
+ handEvsChips(player: 0 | 1): Float64Array;
2385
+ /**
2386
+ * Root EV for each combination a player can hold, in percent of `evPot`
2387
+ * as `ev` is, indexed like `COMBO_CARDS` (as `reachAt` is): what that hand
2388
+ * wins on average, over the opponent hands it can be dealt against. Zero
2389
+ * for combinations outside the range or blocked by the board, and for a
2390
+ * hand no opponent hand can be dealt against, which has no EV to give;
2391
+ * those carry no weight. Weighted by range weight times compatible
2392
+ * opponent mass, the mean is `ev(player)`, and the same pass serves both.
2393
+ * Under the average strategy, or the current profile with
2394
+ * `approximations.currentProfileEv`. Returns a fresh copy.
2395
+ */
2396
+ handEvs(player: 0 | 1): Float64Array;
1019
2397
  /** Distance from equilibrium, in chips per hand. */
1020
2398
  exploitability(): number;
1021
2399
  /**
@@ -1055,7 +2433,7 @@ interface Solution {
1055
2433
  readonly history: readonly Progress[];
1056
2434
  }
1057
2435
  /** Betting for a subgame; anything unset keeps the original spot's. */
1058
- type SubgameBetting = Partial<Pick<SpotConfig, 'betSizes' | 'raiseSizes' | 'maxRaises' | 'allowAllIn' | 'allInThreshold' | 'noDonk' | 'mergeSizes' | 'maxCombos' | 'maxBytes'>>;
2436
+ type SubgameBetting = Partial<Pick<SpotConfig, 'betSizes' | 'raiseSizes' | 'maxRaises' | 'allowAllIn' | 'allInThreshold' | 'noDonk' | 'mergeSizes' | 'removeActions' | 'thinSizes' | 'maxCombos' | 'maxBytes'>>;
1059
2437
  interface StrategyView {
1060
2438
  readonly node: number;
1061
2439
  readonly board: number;
@@ -1089,7 +2467,7 @@ interface SolveRun {
1089
2467
  */
1090
2468
  trueExploitabilityPercent(): number;
1091
2469
  /** A view of the strategy as it stands; cheap, take a fresh one each time. */
1092
- snapshot(history?: readonly Progress[], stoppedAt?: 'target' | 'iterations'): Solution;
2470
+ snapshot(history?: readonly Progress[], stoppedAt?: StopReason): Solution;
1093
2471
  /** Release worker threads. Snapshots taken before this stay usable. */
1094
2472
  close(): void;
1095
2473
  /** Worker threads actually in use; 1 when single-threaded. */
@@ -1108,6 +2486,8 @@ interface SolveRun {
1108
2486
  * @param options solver setup
1109
2487
  */
1110
2488
  declare function createRun(spot: Spot, options?: SolveOptions): SolveRun;
2489
+ /** Bytes `of` takes stored at `at`, compact storage included. */
2490
+ declare function storageCost(of: Spot, at: Precision): number;
1111
2491
  /** View a buffer as regret storage of the given precision. */
1112
2492
  declare function makeRegretStore(precision: Precision, buffer: ArrayBuffer | SharedArrayBuffer): RegretStore;
1113
2493
  /** View a buffer as strategy-sum storage of the given precision. */
@@ -1135,4 +2515,4 @@ declare function solve(spot: Spot, options?: SolveOptions): Solution;
1135
2515
  */
1136
2516
  declare function predictCrossing(t1: number, e1: number, t2: number, e2: number, target: number): number;
1137
2517
 
1138
- export { ACTION_LABELS, ActionKind, type Algorithm, type Approximations, type BetSize, CATEGORY, CATEGORY_NAMES, COMBOS, COMBO_CARDS, COMBO_LANES, DECK, type Estimate, NodeKind, PLATFORM, PRECISION_BYTES, type PerPlayer, type Precision, type Progress, RANKS, type RaiseSizes, type ResolvedBoard, SUITS, type Solution, type SolveOptions, type SolveRun, type Solver, type Spot, type SpotConfig, SpotTooLargeError, type StrategyView, type SubgameBetting, type WarmStartReport, activeCombos, cardOf, categoryOf, comboIndex, createRun, defineSpot, evaluate, evaluateCards, formatCard, formatCards, formatCombo, makeRegretStore, makeSumStore, parseCard, parseCards, parseRange, predictCrossing, rangeWeight, rankOf, simdAvailable, solve, suitLanes, suitOf };
2518
+ export { ACTION_LABELS, ActionKind, type Algorithm, type Approximations, type BetSize, CATEGORY, CATEGORY_NAMES, COMBOS, COMBO_CARDS, COMBO_LANES, type CoarseStart, type CompactStorage, type CompressRangesOptions, type CompressedRanges, DECK, type Estimate, type LineReach, type LinesWithinOptions, type LiteOptions, type LitePreset, type LiteResolveOptions, type LiteSolution, NodeKind, PLATFORM, PRECISION_BYTES, type PerPlayer, type Precision, type PresetChanges, type Progress, RANKS, type RaiseSizes, type RangeCompression, type ResolveOptions, type ResolvedBoard, type ResolvedSubgame, type RootPlay, SUITS, type SamplingOptions, type SettingChange, type SettleOptions, type SettleTracker, type ShareHistories, type SizesCut, type Solution, type SolveLiteOptions, type SolveOptions, type SolveRun, type Solver, type Spot, type SpotConfig, SpotTooLargeError, type StopReason, type StrategyView, type Street, type SubgameBetting, type WarmStartReport, type WasmStorage, activeCombos, bettingFrom, cardOf, categoryOf, checkedDown, comboIndex, compressRanges, createRun, defineSpot, evaluate, evaluateCards, exploitabilityInExact, formatCard, formatCards, formatCombo, keepWithin, linesWithin, liteConfig, litePreset, makeRegretStore, makeSumStore, parseCard, parseCards, parseRange, predictCrossing, rangeWeight, rankOf, rankSwap, resolveSubgame, rootPlay, rootPlayMovement, rootPlayNodes, simdAvailable, solve, solveLite, storageCost, suitLanes, suitOf, trackSettle, turnLineReach };