feat(engine): true 169-class abstraction mode (Premium-A Phase 1.5 unblock, #68)

[amaster97]

Summary

True Path B follow-up to PR #167 — Rust engine now operates on
169-element strategy/regret/reach vectors directly instead of 1326-combo.
Pre-bakes per-(combo_a, combo_b) blocker mass into the (class_i, class_j)
leaf payoff cells so the inner CFR kernel is dimension-169 not
dimension-1326.

HOLD FOR USER REVIEW per task brief — engine refactors flagged as
high-risk. Diff test result locks in lane-for-lane equivalence with the
hybrid path.

Measured speedup (matched iter count, M4 Pro arm64)

Stack	Iters	1326-combo	169-class	Speedup
15 BB	1000	312.7 s	1.75 s	178×
40 BB	200	410.6 s	1.01 s	406×
100 BB	100	445.4 s	0.99 s	448×

Phase 1.5 projection for 25k-iter blueprints (27 cells):

• 1326-combo hybrid: ~17-40h (matches task brief)
• 169-class true Path B: ~1.5-2h total

Convergence equivalence

test_class169_matches_hybrid_within_l1_tolerance (15 BB, 1000 iters,
6084 cells compared): max L1 = 0.0000 between 169-class engine and
aggregate_to_169_classes(1326-combo engine). Lane-for-lane match
modulo FP precision when the default reach is combo-weighted (the
natural full-deck interpretation; [6, 4, 12, ...] for
pairs / suited / offsuit). Test brief target: L1 ≤ 0.05.

Memory footprint

7.85× reduction in strategy storage (1326 → 169 per infoset per
action), matches theoretical 1326/169 ratio.

What ships

• crates/cfr_core/src/preflop_rvr.rs (+1024 LOC) — HandResolution
  enum, Class169Combos enumerator, Class169TerminalCache with
  pre-baked blocker-mass-weighted leaf payoffs, Class169VectorDCFR
  traversal, solve_hunl_preflop_rvr_class169() entry point + 5 new
  Rust unit tests.
• crates/cfr_core/src/lib.rs (+85 LOC) — Python binding
  _rust.solve_hunl_preflop_rvr_class169.
• poker_solver/blueprint.py (+99 LOC, -10 LOC) —
  generate_blueprint(hand_resolution=...) defaults to CLASS_169 for
  the perf win; COMBO_1326 hybrid path preserved unchanged.
• tests/test_true_path_b_diff.py (+440 LOC) — 6 differential tests:
  closed-form AA-vs-KK, cross-resolution L1 drift, monotone-convergence,
  speedup ≥ 2× gate, memory footprint ≥ 5× gate, pushfold-equivalence.

Test plan

• cargo test --release --lib — 81 passed (9 preflop_rvr + 5 new
  169-class tests inline)
• cargo test --release --test preflop_rvr_smoke — 4 passed
• cargo clippy --lib --tests --release -- -D warnings — clean
• pytest tests/test_true_path_b_diff.py — 6 passed
  • AA-vs-KK closed-form: AA fold < 1%, commit > 99% ✓
  • Cross-resolution L1 drift: max L1 = 0.0000 (lane-for-lane) ✓
  • Monotone convergence: d(100→500)=0.0208, d(500→2000)=0.0063 ✓
  • Speedup ≥ 2×: measured 11.6× at 40 BB / 30 iters ✓
  • Memory footprint ≥ 5×: 7.85× ✓
  • Pushfold equivalence at 15 BB ✓
• pytest tests/test_blueprint_pipeline.py — 24 passed
  (stub-solver test updated to opt-in COMBO_1326)
• pytest tests/test_preflop_rvr_diff.py — 4 passed (existing
  1326-combo path unchanged)
• pytest tests/test_kuhn_dcfr tests/test_leduc_dcfr tests/test_dcfr_diff — passed (no regression on small-game
  diff tests)
• ruff check poker_solver/blueprint.py tests/test_true_path_b_diff.py — clean
• mypy poker_solver/blueprint.py — clean

Backwards compatibility

• solve_hunl_preflop_rvr (1326-combo) untouched.
• aggregate_to_169_classes wrapper untouched (still works for
  exact per-combo strategies + legacy callers).
• _stub_rust_solver test path: opt-in to COMBO_1326 (one-line change
  to tests/test_blueprint_pipeline.py:397).

Risks identified

• R1 (Nash multiplicity): 169-class engine could in principle drift
  from hybrid at indifference manifolds (deep all-in spots). Empirically
  the diff test shows max L1 = 0.0000 at 15 BB / 1000 iters; should
  hold for deeper stacks too because the equivalence is mechanical
  (lane-for-lane reach algebra).
• R2 (Reach semantics): caller-supplied root_reach_p0 /
  root_reach_p1 defaults to combo-weighted [6, 4, 12, ...]. Callers
  passing [1, 1, 1, ...] (uniform-over-classes) get a different
  equilibrium — documented in the docstring.
• R3 (Leaf-table build cost): building the 169x169 leaf table costs
  ~25 ms per leaf (vs 0.4 ms for 1326x1326). At 30 iters / 100 leaves
  this is ~750 ms one-time cost. At 25k iters the cost is amortized;
  at < 1k iters the hybrid path may be faster on tiny configs.

Out of scope

• Postflop solver — preflop-only refactor per task brief.
• 169-class abstraction for the chained orchestrator / RvR aggregator.
• Engine kernel SIMD tuning for the 169-dim slices (LLVM -O3
  autovectorizes; measured speedup is already 100-400× so no headroom
  push needed).

References

• Task brief: True Path B 169-class engine refactor (feat: A83 Nash multiplicity EMPIRICALLY CONFIRMED via corrected probe #68 follow-up)
• Prerequisite (merged): PR feat(engine): 169-class abstraction mode + blueprint generation pipeline (Phase 1, #68) #167 (hybrid path + asset format)
• Engine: crates/cfr_core/src/preflop_rvr.rs
• Equity table: assets/preflop_equity_169x169.npz

Generated with Claude Code