fix(engine): preflop State::initial honors config.initial_contributions (#67)

[amaster97]

Summary

Root cause documented in PR #159 and audited in PR #161. Both broken State::initial methods unconditionally hardcoded contributions=[SB+ante, BB+ante] regardless of config.initial_contributions; downstream leaves compute cs = contributions - initial_contributions, so a caller passing initial_contributions=[SB,BB]+initial_pot=0 (intending to declare posted blinds) produced cs=[0,0] and pot_total=0 at every leaf — collapsing the preflop Nash to fold-everywhere. This was HARD-BLOCKING the Premium-A blueprint.

What changed

1. PreflopRvrState::initial (crates/cfr_core/src/preflop_rvr.rs:229-251) honors config.initial_contributions: contribution[i] = max(blind_amount[i], initial_contributions[i]). Both well-formed config shapes — [0,0]+pot=0 (engine posts blinds) and [SB+ante,BB+ante]+pot=SB+BB+2*ante (caller declared blinds as dead money) — produce Nash-equivalent strategies (leaf payoffs differ by exact per-player constants).
2. HUNLState::initial_preflop (crates/cfr_core/src/hunl.rs:382-414) same fix. The postflop branch at hunl.rs:318 was already correct and is untouched.
3. HUNLConfig::validate() added in crates/cfr_core/src/hunl.rs. Mirrors Python's __post_init__ guard at poker_solver/hunl.py:124-176, plus accepts the caller-declared-blinds preflop shape. Defense-in-depth per feedback_silent_skip_hazard — PyO3 callers deserialize straight into HUNLConfig and skip Python's __post_init__.
4. Wired validate() into solve_hunl_preflop_rvr so the bug-triggering config ([50,100]+pot=0) HARD-FAILs at the entry point instead of silently producing a fold-everywhere equilibrium.

Tests added

• crates/cfr_core/tests/preflop_initial_contributions.rs — 11 new Rust tests covering AA-does-not-fold regression, identical-strategies diff-test, six HUNLConfig::validate() accept/reject cases, dead-money subgame acceptance, and entry-point rejection.
• tests/test_preflop_rvr_diff.py::test_engine_agnostic_to_blind_declaration — Python-side parametrized variant of the diff-test, exercising the PyO3 boundary.

Verification

• All 11 new Rust tests PASS.
• AA-vs-KK closed-form smoke (preflop_rvr_smoke::aa_vs_kk_closed_form_aa_does_not_fold) still PASSes — no regression on the engine-posts-blinds path.
• All 4 test_preflop_rvr_diff.py Python diff tests PASS (test_pushfold_equivalence_15bb, test_aa_only_vs_kk_only_closed_form, test_engine_agnostic_to_blind_declaration, test_aggregator_drift_premium_ranges).
• cargo test -p cfr_core --lib: 75 unit tests PASS.
• cargo clippy --lib --tests -p cfr_core -- -D warnings: clean.
• ruff check tests/test_preflop_rvr_diff.py: clean.

Diff-test result

engine_posts_vs_caller_declared_blinds_produces_identical_strategies: max_drift < 1e-4 between [0,0]+pot=0 and [SB+ante,BB+ante]+pot=SB+BB+2*ante (PASS). The engine is now agnostic to which way blinds are declared.

Constraints respected

• Postflop hunl.rs:318 untouched (was already correct).
• Leaf-payoff math untouched — only State::initial and the new validate().
• Pre-existing cfr_core benchmark formatting issues (benches/preflop_rvr_profile.rs, benches/rvr_profile.rs) are not in this PR's scope.

🤖 Generated with Claude Code