refactor: slim solver to card_game-native types

Per Rhys: card_game's solver is the real engine, so drop the redundant
adapter types in solitaire_data::solver rather than maintain a parallel
verdict/config/move vocabulary.

- Delete SolverResult, SolverConfig, SolverMove, and snapshot_to_solver_move.
  The verdict now reads straight off card_game's return:
    Ok(Some(instr)) = winnable (first move on the path)
    Ok(None)        = provably unwinnable
    Err(_)          = inconclusive (budget exceeded)
- SolveOutcome is now Result<Option<KlondikeInstruction>, SolveError>.
- try_solve / try_solve_from_state take plain (moves_budget, states_budget)
  u64s; add DEFAULT_SOLVE_{MOVES,STATES}_BUDGET consts.
- snapshot_to_solver_move duplicated core's GameState::instruction_to_move,
  so make that pub and have the hint convert the first-move instruction to
  highlighted (from, to) piles through it. Re-export KlondikeInstruction
  from solitaire_core.
- HintSolverConfig now holds { moves_budget, states_budget } instead of
  wrapping the deleted SolverConfig.
- Update consumers: pending_hint, play_by_seed (verdict badge), game_plugin
  (choose_winnable_seed), input_plugin, hud_plugin, and the gen_seeds /
  gen_difficulty_seeds asset tools.

solver.rs drops 274 -> 140 lines. cargo test --workspace and
cargo clippy --workspace --all-targets -- -D warnings pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

solitaire_data/src/lib.rs

@@ -101,8 +101,8 @@ impl SyncProvider for Box<dyn SyncProvider + Send + Sync> {
 
 pub mod solver;
 pub use solver::{
-    SolveOutcome, SolverConfig, SolverMove, SolverResult, try_solve, try_solve_from_state,
-    try_solve_with_first_move,
+    DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET, SolveOutcome, try_solve,
+    try_solve_from_state,
 };
 
 pub mod stats;

solitaire_data/src/settings.rs

@@ -381,9 +381,9 @@ pub const REPLAY_MOVE_INTERVAL_STEP_SECS: f32 = 0.05;
 /// Maximum number of seed retries [`solitaire_engine::handle_new_game`]
 /// is willing to attempt before giving up and accepting the latest
 /// candidate seed when [`Settings::winnable_deals_only`] is on. If
-/// every retry comes back [`SolverResult::Unwinnable`] (which would
-/// be very unusual) we'd rather hand the player a possibly-unwinnable
-/// deal than spin forever on the main thread.
+/// every retry comes back provably unwinnable (`Ok(None)` from the
+/// solver, which would be very unusual) we'd rather hand the player a
+/// possibly-unwinnable deal than spin forever on the main thread.
 ///
 /// 50 attempts × ~50 ms median per solve = ~2.5 s worst-case stall —
 /// the upper bound on UI freeze when the toggle is on.

solitaire_data/src/solver.rs

@@ -1,215 +1,103 @@
-//! Klondike solvability checker using upstream `card_game::Session::solve()`.
+//! Klondike solvability check using upstream `card_game::Session::solve()`.
 //!
-//! Used by the engine to back the **Settings → Gameplay → "Winnable deals only"**
-//! toggle and by the hint system when it wants the first move on a winning path.
+//! Backs the **Settings → Gameplay → "Winnable deals only"** toggle, the
+//! Play-by-seed verdict badge, and the hint system (which wants the first
+//! move on a winning path). All search is delegated to `card_game`; this
+//! module only adapts the inputs (a seed or a live [`GameState`]) and extracts
+//! the first move from the returned solution.
 
-use card_game::{Session, SessionConfig, SolveError, StateSnapshot};
-use klondike::{Klondike, KlondikeInstruction, KlondikePile, KlondikePileStack};
+use card_game::{Session, SessionConfig, SolveError};
+use klondike::KlondikeInstruction;
 use solitaire_core::DrawMode;
 use solitaire_core::game_state::GameState;
 use solitaire_core::klondike_adapter::KlondikeAdapter;
 
-/// Verdict returned by [`try_solve`].
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub enum SolverResult {
-    /// The solver found a sequence of moves that wins the deal.
-    Winnable,
-    /// The solver exhaustively searched and confirmed no win exists.
-    Unwinnable,
-    /// The move / state budget was exceeded before a verdict could be reached.
-    Inconclusive,
-}
+/// Default move budget for a solve. Matches the winnable-deal retry loop.
+pub const DEFAULT_SOLVE_MOVES_BUDGET: u64 = 100_000;
+/// Default unique-state budget for a solve.
+pub const DEFAULT_SOLVE_STATES_BUDGET: u64 = 200_000;
 
-/// Tunable budgets controlling how long [`try_solve`] is willing to search.
-#[derive(Debug, Clone, Copy, PartialEq, Eq)]
-pub struct SolverConfig {
-    /// Maximum total moves to consider across the entire search tree.
-    pub move_budget: u64,
-    /// Maximum unique states to visit.
-    pub state_budget: usize,
-}
+/// Outcome of a solvability check:
+///
+/// * `Ok(Some(instruction))` — winnable; `instruction` is the first move on a
+///   winning path (used by the hint system).
+/// * `Ok(None)` — provably unwinnable (search exhausted with no solution, or
+///   the game is already won so no next move exists).
+/// * `Err(SolveError)` — inconclusive; the move/state budget was exceeded
+///   before a verdict was reached.
+pub type SolveOutcome = Result<Option<KlondikeInstruction>, SolveError>;
 
-impl Default for SolverConfig {
-    fn default() -> Self {
-        Self {
-            move_budget: 100_000,
-            state_budget: 200_000,
-        }
-    }
-}
-
-/// A single move the solver can recommend, expressed in engine-level pile terms.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SolverMove {
-    /// Pile the move originates from.
-    pub source: KlondikePile,
-    /// Pile the move lands on.
-    pub dest: KlondikePile,
-    /// Number of cards in the move (1 for non-tableau-to-tableau moves).
-    pub count: usize,
-}
-
-/// Solver verdict plus, when winnable, the first move on a winning path.
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct SolveOutcome {
-    /// The high-level verdict (Winnable / Unwinnable / Inconclusive).
-    pub result: SolverResult,
-    /// First move on the solution path when `result == Winnable`.
-    pub first_move: Option<SolverMove>,
-}
-
-/// Tries to solve a fresh Classic-mode game from `seed` + `draw_mode`.
-pub fn try_solve(seed: u64, draw_mode: DrawMode, config: &SolverConfig) -> SolverResult {
-    try_solve_with_first_move(seed, draw_mode, config).result
-}
-
-/// Tries to solve a fresh Classic-mode game and, when winnable, returns the
-/// first move on a winning path.
+/// Solves a fresh Classic-mode game dealt from `seed` + `draw_mode`.
 ///
 /// Fresh-deal solving models standard Klondike rules, so the non-standard
 /// take-from-foundation house rule stays disabled here.
-pub fn try_solve_with_first_move(
+pub fn try_solve(
     seed: u64,
     draw_mode: DrawMode,
-    config: &SolverConfig,
+    moves_budget: u64,
+    states_budget: u64,
 ) -> SolveOutcome {
     let mut game = GameState::new(seed, draw_mode);
     game.take_from_foundation = false;
-    solve_game_state(&game, config)
+    try_solve_from_state(&game, moves_budget, states_budget)
 }
 
-/// Tries to solve from an existing in-progress [`GameState`].
-pub fn try_solve_from_state(state: &GameState, config: &SolverConfig) -> SolveOutcome {
-    solve_game_state(state, config)
-}
-
-fn solve_game_state(initial: &GameState, config: &SolverConfig) -> SolveOutcome {
-    if config.state_budget == 0 {
-        return SolveOutcome {
-            result: SolverResult::Inconclusive,
-            first_move: None,
-        };
+/// Solves from an existing in-progress [`GameState`], returning the first move
+/// on a winning path when one exists.
+pub fn try_solve_from_state(
+    state: &GameState,
+    moves_budget: u64,
+    states_budget: u64,
+) -> SolveOutcome {
+    // An already-won game has no "next move"; report it as unwinnable so the
+    // winnable contract (`Some(_)` ⇒ a real move exists) holds.
+    if state.is_won() {
+        return Ok(None);
     }
 
-    // Preserve the historical payload contract: winnable verdicts always carry
-    // a first move. An already-won state therefore returns no recommendation.
-    if initial.is_won() {
-        return SolveOutcome {
-            result: SolverResult::Unwinnable,
-            first_move: None,
-        };
-    }
-
-    let solver_config = SessionConfig {
-        inner: KlondikeAdapter::config_for(initial.draw_mode(), initial.take_from_foundation),
+    let config = SessionConfig {
+        inner: KlondikeAdapter::config_for(state.draw_mode(), state.take_from_foundation),
         undo_penalty: 0,
-        solve_moves_budget: config.move_budget,
-        solve_states_budget: config.state_budget as u64,
+        solve_moves_budget: moves_budget,
+        solve_states_budget: states_budget,
     };
-    let solver_session = Session::new(initial.session().state().state().clone(), solver_config);
+    let session = Session::new(state.session().state().state().clone(), config);
 
-    match solver_session.solve() {
-        Ok(Some(solution)) => {
-            let first_move = solution
+    session.solve().map(|solution| {
+        solution.and_then(|solution| {
+            solution
                 .raw_solution()
                 .iter()
-                .find_map(snapshot_to_solver_move);
-            if let Some(first_move) = first_move {
-                SolveOutcome {
-                    result: SolverResult::Winnable,
-                    first_move: Some(first_move),
-                }
-            } else {
-                SolveOutcome {
-                    result: SolverResult::Inconclusive,
-                    first_move: None,
-                }
-            }
-        }
-        Ok(None) => SolveOutcome {
-            result: SolverResult::Unwinnable,
-            first_move: None,
-        },
-        Err(SolveError::MovesBudgetExceeded | SolveError::StatesBudgetExceeded) => SolveOutcome {
-            result: SolverResult::Inconclusive,
-            first_move: None,
-        },
-    }
-}
-
-fn snapshot_to_solver_move(snapshot: &StateSnapshot<Klondike>) -> Option<SolverMove> {
-    let source_state = snapshot.state().state();
-    match *snapshot.instruction() {
-        KlondikeInstruction::RotateStock => Some(SolverMove {
-            source: KlondikePile::Stock,
-            dest: KlondikePile::Stock,
-            count: 1,
-        }),
-        KlondikeInstruction::DstFoundation(dst_foundation) => {
-            let source = match dst_foundation.src {
-                KlondikePile::Tableau(tableau) => KlondikePile::Tableau(tableau),
-                KlondikePile::Stock => KlondikePile::Stock,
-                KlondikePile::Foundation(_) => return None,
-            };
-            Some(SolverMove {
-                source,
-                dest: KlondikePile::Foundation(dst_foundation.foundation),
-                count: 1,
-            })
-        }
-        KlondikeInstruction::DstTableau(dst_tableau) => {
-            let (source, count) = match dst_tableau.src {
-                KlondikePileStack::Tableau(tableau_stack) => {
-                    let face_up_count =
-                        source_state.tableau_face_up_cards(tableau_stack.tableau).len();
-                    let count = face_up_count.checked_sub(tableau_stack.skip_cards as usize)?;
-                    if count == 0 {
-                        return None;
-                    }
-                    (KlondikePile::Tableau(tableau_stack.tableau), count)
-                }
-                KlondikePileStack::Stock => (KlondikePile::Stock, 1),
-                KlondikePileStack::Foundation(foundation) => {
-                    (KlondikePile::Foundation(foundation), 1)
-                }
-            };
-
-            Some(SolverMove {
-                source,
-                dest: KlondikePile::Tableau(dst_tableau.tableau),
-                count,
-            })
-        }
-    }
+                .map(|snapshot| *snapshot.instruction())
+                .find(|instruction| !instruction.is_useless())
+        })
+    })
 }
 
 #[cfg(test)]
 mod tests {
     use super::*;
 
-    #[test]
-    fn try_solve_with_first_move_is_deterministic() {
-        let config = SolverConfig::default();
-        let a = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        let b = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        let c = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        assert_eq!(a, b);
-        assert_eq!(b, c);
+    /// `SolveError` has no `PartialEq`, so compare the winnable verdict and the
+    /// extracted first move (both `Eq`) rather than the whole `Result`.
+    fn verdict_key(outcome: &SolveOutcome) -> (bool, Option<KlondikeInstruction>) {
+        (outcome.is_err(), outcome.clone().ok().flatten())
     }
 
     #[test]
-    fn try_solve_with_first_move_returns_consistent_payload() {
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 5_000,
-        };
-        let outcome = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        match outcome.result {
-            SolverResult::Winnable => assert!(outcome.first_move.is_some()),
-            SolverResult::Unwinnable | SolverResult::Inconclusive => {
-                assert!(outcome.first_move.is_none())
-            }
-        }
+    fn try_solve_is_deterministic() {
+        let a = try_solve(7, DrawMode::DrawOne, DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET);
+        let b = try_solve(7, DrawMode::DrawOne, DEFAULT_SOLVE_MOVES_BUDGET, DEFAULT_SOLVE_STATES_BUDGET);
+        assert_eq!(verdict_key(&a), verdict_key(&b));
+    }
+
+    #[test]
+    fn winnable_verdict_carries_a_first_move() {
+        // Contract: a first move is present iff the verdict is winnable.
+        let outcome = try_solve(7, DrawMode::DrawOne, 5_000, 5_000);
+        let winnable = matches!(outcome, Ok(Some(_)));
+        let has_move = outcome.ok().flatten().is_some();
+        assert_eq!(winnable, has_move);
     }
 
     #[test]
@@ -217,57 +105,36 @@ mod tests {
         let mut game = GameState::new(42, DrawMode::DrawOne);
         game.draw().expect("draw must succeed");
 
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 5_000,
-        };
-        let outcome = try_solve_from_state(&game, &config);
-        match outcome.result {
-            SolverResult::Winnable => assert!(outcome.first_move.is_some()),
-            SolverResult::Unwinnable | SolverResult::Inconclusive => {
-                assert!(outcome.first_move.is_none())
-            }
-        }
+        let outcome = try_solve_from_state(&game, 5_000, 5_000);
+        let winnable = matches!(outcome, Ok(Some(_)));
+        let has_move = outcome.ok().flatten().is_some();
+        assert_eq!(winnable, has_move);
     }
 
     #[test]
     fn zero_state_budget_is_inconclusive() {
-        let config = SolverConfig {
-            move_budget: 5_000,
-            state_budget: 0,
-        };
-        let outcome = try_solve_with_first_move(7, DrawMode::DrawOne, &config);
-        assert_eq!(outcome.result, SolverResult::Inconclusive);
-        assert!(outcome.first_move.is_none());
+        let outcome = try_solve(7, DrawMode::DrawOne, 5_000, 0);
+        assert!(matches!(outcome, Err(SolveError::StatesBudgetExceeded)));
     }
 
     #[test]
     fn budget_is_passed_through_not_clamped() {
-        let easy = SolverConfig { move_budget: 1_000, state_budget: 1_000 };
-        let medium = SolverConfig { move_budget: 5_000, state_budget: 5_000 };
-        assert_eq!(
-            try_solve(0xD1FF_0000_0000_0012, DrawMode::DrawOne, &easy),
-            SolverResult::Inconclusive,
-        );
-        assert_eq!(
-            try_solve(0xD1FF_0000_0000_0012, DrawMode::DrawOne, &medium),
-            SolverResult::Winnable,
-        );
+        // This seed is Inconclusive at 1k states but Winnable at 5k — proving
+        // the budget reaches the solver unchanged.
+        let easy = try_solve(0xD1FF_0000_0000_0012, DrawMode::DrawOne, 1_000, 1_000);
+        let medium = try_solve(0xD1FF_0000_0000_0012, DrawMode::DrawOne, 5_000, 5_000);
+        assert!(easy.is_err());
+        assert!(matches!(medium, Ok(Some(_))));
     }
 
     #[test]
     fn budget_above_five_thousand_is_not_clamped() {
-        let below_cap = SolverConfig { move_budget: 5_000, state_budget: 5_000 };
-        let above_cap = SolverConfig { move_budget: 50_000, state_budget: 50_000 };
-        assert_eq!(
-            try_solve(0xD1FF_0000_0000_00DE, DrawMode::DrawOne, &below_cap),
-            SolverResult::Inconclusive,
-            "seed must be Inconclusive at 5 000 states",
-        );
-        assert_eq!(
-            try_solve(0xD1FF_0000_0000_00DE, DrawMode::DrawOne, &above_cap),
-            SolverResult::Winnable,
-            "seed must be Winnable at 50 000 states — re-introducing the 5k cap would break this",
+        let below_cap = try_solve(0xD1FF_0000_0000_00DE, DrawMode::DrawOne, 5_000, 5_000);
+        let above_cap = try_solve(0xD1FF_0000_0000_00DE, DrawMode::DrawOne, 50_000, 50_000);
+        assert!(below_cap.is_err(), "seed must be Inconclusive at 5 000 states");
+        assert!(
+            matches!(above_cap, Ok(Some(_))),
+            "seed must be Winnable at 50 000 states — re-introducing the 5k cap would break this"
         );
     }
 }