Merge pull request #34 from CurtisTechSolutions/feat/sudoku-reference-hints

feat(sudoku): add explained reference-solver recommendations

Author: nosam1998

README.md

@@ -41,3 +41,9 @@ variation, node count, depth and whether the budget was exhausted. Match analysi
 requires `assists.allow_analysis: true`. A standalone copy of an active position
 cannot bypass that policy. Searches run in four bounded workers and receive
 only the authorized observation and legal actions.
+
+Sudoku also advertises the `reference` opponent. Analysis returns its next
+placement and supporting candidate eliminations. Search-backed steps are marked
+`advice.is_guess: true`; an incorrect entered digit produces an explicit
+`solution_check` erasure recommendation. Ordinary state responses do not include
+these recommendations or the solution grid.

crates/apps/gfa-server/src/analysis_tests.rs

@@ -113,3 +113,75 @@ async fn real_analysis_finds_a_win_without_mutating_history_and_reports_uncalibr
     app.store.close().await;
     Ok(())
 }
+
+#[tokio::test]
+async fn sudoku_reference_solver_plays_only_through_generic_analysis_and_moves(
+) -> Result<(), ServerError> {
+    let directory = tempfile::tempdir()?;
+    let app = fixture(&config(&directory)).await?;
+    let (_, catalog) = call(
+        &app.router,
+        "GET",
+        "/v1/games/sudoku/opponents",
+        Value::Null,
+        None,
+    )
+    .await?;
+    assert!(catalog
+        .as_array()
+        .ok_or("catalog")?
+        .iter()
+        .any(|item| item["id"] == "reference"));
+    let (_, mut state) = call(
+        &app.router,
+        "POST",
+        "/v1/matches",
+        json!({
+            "game_id":"sudoku", "config":{"size":4}, "seed":42,
+            "assists":{"allow_analysis":true}
+        }),
+        None,
+    )
+    .await?;
+    let id = state["match_id"].as_str().ok_or("id")?.to_owned();
+    for _ in 0..16 {
+        if state["terminated"] == true {
+            break;
+        }
+        let (status, result) = call(
+            &app.router,
+            "POST",
+            "/v1/analysis",
+            json!({
+                "game_id":"sudoku","from":{"match_id":id,"seat":0},
+                "opponent":{"id":"reference"},"seed":7
+            }),
+            None,
+        )
+        .await?;
+        assert_eq!(status, StatusCode::OK, "{result}");
+        assert!(result["advice"]["summary"]
+            .as_str()
+            .is_some_and(|s| !s.is_empty()));
+        assert!(state["legal_actions"]
+            .as_array()
+            .ok_or("legal")?
+            .contains(&result["best_moves"][0]));
+        let (status, moved) = call(
+            &app.router,
+            "POST",
+            &format!("/v1/matches/{id}/actions"),
+            json!({
+                "seat":0,"turn":state["turn"],"action":result["best_moves"][0]["json"]
+            }),
+            None,
+        )
+        .await?;
+        assert_eq!(status, StatusCode::OK);
+        state = moved["state"].clone();
+    }
+    assert_eq!(state["returns"], json!([1.0]));
+    assert_eq!(state["observation"]["json"]["outcome"], "solved");
+    app.store.close().await;
+    Ok(())
+}

crates/core/gfa-core/src/dynamic.rs

@@ -43,6 +43,18 @@ pub trait DynGame: Send + Sync {
             "This engine cannot reconstruct planning states",
         ))
     }
+    /// Whether the engine exposes a reference solver through the generic hook.
+    fn supports_reference_advice(&self) -> bool {
+        false
+    }
+    /// Obtain a legal recommendation from an authorized planning state.
+    fn reference_advice(
+        &self,
+        _state: &Value,
+        _player: PlayerId,
+    ) -> Result<Option<crate::Advice<LegalAction>>, GameError> {
+        Ok(None)
+    }
     /// Validate a JSON state before accepting it from a caller.
     fn validate_state(&self, state: &Value) -> Result<(), GameError>;
     /// Seats currently allowed to act.
@@ -181,6 +193,34 @@ impl<G: Game> DynGame for GameAdapter<G> {
         Ok(serde_json::to_value(state)?)
     }
 
+    fn supports_reference_advice(&self) -> bool {
+        G::supports_reference_advice()
+    }
+
+    fn reference_advice(
+        &self,
+        state: &Value,
+        player: PlayerId,
+    ) -> Result<Option<crate::Advice<LegalAction>>, GameError> {
+        let state = Self::state(state)?;
+        let Some(advice) = G::reference_advice(&state, player)? else {
+            return Ok(None);
+        };
+        if !G::legal_actions(&state, player).contains(&advice.action) {
+            return Err(GameError::illegal(
+                "Reference solver returned an illegal action",
+            ));
+        }
+        Ok(Some(crate::Advice {
+            action: LegalAction {
+                string: G::action_to_string(&state, &advice.action),
+                index: G::action_to_index(&advice.action),
+                json: serde_json::to_value(advice.action)?,
+            },
+            info: advice.info,
+        }))
+    }
+
     fn validate_state(&self, state: &Value) -> Result<(), GameError> {
         Self::state(state).map(|_| ())
     }

crates/core/gfa-core/src/game.rs

@@ -50,6 +50,22 @@ pub trait Game: Send + Sync + 'static {
         ))
     }
 
+    /// Whether this engine provides a reference solver or hint policy.
+    fn supports_reference_advice() -> bool {
+        false
+    }
+
+    /// Recommend a legal action from a caller-owned planning state.
+    ///
+    /// Hosts must enforce assist permissions and reconstruct player observations
+    /// before invoking this hook. The default preserves existing game behavior.
+    fn reference_advice(
+        _state: &Self::State,
+        _player: PlayerId,
+    ) -> Result<Option<crate::Advice<Self::Action>>, GameError> {
+        Ok(None)
+    }
+
     /// Validate state received through a persistence or API boundary.
     fn validate_state(state: &Self::State) -> Result<(), GameError>;
     /// Seats that can act; empty after a terminal or truncated transition.

crates/core/gfa-core/src/types.rs

@@ -203,3 +203,26 @@ impl PlayGuide {
         Ok(())
     }
 }
+
+/// Explanation attached to a game-provided reference recommendation.
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
+pub struct AdviceInfo {
+    /// Human-readable next step.
+    pub summary: String,
+    /// Stable technique or solver identifier.
+    pub technique: String,
+    /// True when the recommendation uses search beyond the supported logical rules.
+    pub is_guess: bool,
+    /// Game-specific evidence, such as candidate eliminations leading to a placement.
+    pub details: Value,
+}
+
+/// One game-provided reference action and its explanation.
+#[derive(Clone, Debug, PartialEq)]
+pub struct Advice<A> {
+    /// Legal next action.
+    pub action: A,
+    /// Explanation derived from the supplied planning state.
+    pub info: AdviceInfo,
+}

crates/domain/gfa-api-types/src/opponents.rs

@@ -84,6 +84,9 @@ pub struct AnalysisRequest {
 #[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
 #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
 pub struct AnalysisResult {
+    /// Optional reference-solver explanation and technique evidence.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub advice: Option<gfa_core::AdviceInfo>,
     /// Registered game.
     pub game_id: String,
     /// Opponent identifier.

crates/domain/gfa-service/src/opponents.rs

@@ -3,9 +3,10 @@ use crate::{error, planning::AssistKind, GameService};
 use gfa_api_types::{
     AnalysisRequest, AnalysisResult, ApiError, OpponentConfig, OpponentLevel, OpponentSpec,
 };
-use gfa_core::{DynGame, GameSpec, Information, LegalAction, Observation, TurnStructure, Viewer};
+use gfa_core::{DynGame, Information, LegalAction, Observation, TurnStructure, Viewer};
 use gfa_opponents::{
-    ActionChoice, Algorithm, Clock, Opponent, PlayerTurn, Random, SearchLimits, SearchOpponent,
+    ActionChoice, Algorithm, Clock, Opponent, PlayerTurn, Random, ReferenceOpponent, SearchLimits,
+    SearchOpponent,
 };
 use serde_json::Value;
 use std::{future::Future, pin::Pin, sync::Arc};
@@ -17,7 +18,7 @@ pub type OpponentFuture<'a> =
 /// Select installed players without exposing live state or transport details.
 pub trait OpponentFactory: Send + Sync {
     /// Stable catalog for this game.
-    fn catalog(&self, game: &GameSpec) -> Vec<OpponentSpec>;
+    fn catalog(&self, game: &dyn DynGame) -> Vec<OpponentSpec>;
     /// Construct one player with validated options and limits.
     fn create(
         &self,
@@ -82,8 +83,12 @@ fn spec(id: &str, name: &str, levels: bool) -> OpponentSpec {
 }
 
 impl OpponentFactory for BuiltinOpponentFactory {
-    fn catalog(&self, game: &GameSpec) -> Vec<OpponentSpec> {
+    fn catalog(&self, game: &dyn DynGame) -> Vec<OpponentSpec> {
         let mut catalog = vec![spec("random", "Uniform random", false)];
+        if game.supports_reference_advice() {
+            catalog.push(spec("reference", "Reference solver", false));
+        }
+        let game = game.spec();
         if game.information == Information::Perfect
             && !game.stochastic
             && game.turn_structure == TurnStructure::Sequential
@@ -105,7 +110,7 @@ impl OpponentFactory for BuiltinOpponentFactory {
         seed: u64,
     ) -> Result<(Arc<dyn Opponent>, SearchLimits), ApiError> {
         if !self
-            .catalog(&game.spec())
+            .catalog(game.as_ref())
             .iter()
             .any(|spec| spec.id == opponent.id)
         {
@@ -115,11 +120,11 @@ impl OpponentFactory for BuiltinOpponentFactory {
                 "Select an installed opponent from the game's catalog.",
             ));
         }
-        if opponent.id == "random" && opponent.level.is_some() {
+        if matches!(opponent.id.as_str(), "random" | "reference") && opponent.level.is_some() {
             return Err(ApiError::new(
                 "INVALID_CONFIG",
-                "Random has no difficulty levels",
-                "Omit level for the random opponent.",
+                "This opponent has no difficulty levels",
+                "Omit level for random and reference opponents.",
             ));
         }
         let mut limits =
@@ -136,6 +141,7 @@ impl OpponentFactory for BuiltinOpponentFactory {
         limits.validate().map_err(error::engine)?;
         let player: Arc<dyn Opponent> = match opponent.id.as_str() {
             "random" => Arc::new(Random),
+            "reference" => Arc::new(ReferenceOpponent::new(game, config).map_err(error::engine)?),
             "minimax" => Arc::new(
                 SearchOpponent::new(game, config, Algorithm::Minimax).map_err(error::engine)?,
             ),
@@ -171,7 +177,7 @@ impl GameService {
         Ok(self
             .opponents
             .as_ref()
-            .map_or_else(Vec::new, |(factory, _)| factory.catalog(&game.spec())))
+            .map_or_else(Vec::new, |(factory, _)| factory.catalog(game.as_ref())))
     }
 
     /// Recommend legal moves without modifying events, clocks, or idempotency receipts.
@@ -244,6 +250,7 @@ impl GameService {
             ));
         }
         Ok(AnalysisResult {
+            advice: choice.info.advice,
             game_id: request.game_id,
             opponent: request.opponent.id,
             seed,

crates/domain/gfa-service/src/tests.rs

@@ -1126,7 +1126,7 @@ impl OpponentExecutor for ImmediateOpponentExecutor {
 
 struct ObservingFactory;
 impl OpponentFactory for ObservingFactory {
-    fn catalog(&self, game: &GameSpec) -> Vec<gfa_api_types::OpponentSpec> {
+    fn catalog(&self, game: &dyn gfa_core::DynGame) -> Vec<gfa_api_types::OpponentSpec> {
         BuiltinOpponentFactory.catalog(game)
     }
     fn create(

crates/games/gfa-game-sudoku/src/engine.rs

@@ -1,4 +1,5 @@
 mod actions;
+mod advice;
 mod view;
 
 use crate::{
@@ -106,6 +107,18 @@ impl Game for Sudoku {
         }
     }
 
+    fn supports_reference_advice() -> bool {
+        true
+    }
+
+    fn reference_advice(
+        state: &State,
+        player: PlayerId,
+    ) -> Result<Option<gfa_core::Advice<Action>>, GameError> {
+        Self::validate_state(state)?;
+        advice::recommend(state, player)
+    }
+
     fn play_guide() -> Option<gfa_core::PlayGuide> {
         Some(gfa_core::PlayGuide {
             objective: "Complete every row, column and box with digits 1..size. Givens are fixed. Only seat 0 acts; no opponent.".into(),

crates/games/gfa-game-sudoku/src/engine/advice.rs

@@ -0,0 +1,75 @@
+use super::{outcome, puzzle_solution};
+use crate::{hint, Action, Grid, State, Technique};
+use gfa_core::{serde_json, Advice, AdviceInfo, ErrorCode, GameError, PlayerId};
+
+pub(super) fn recommend(
+    state: &State,
+    player: PlayerId,
+) -> Result<Option<Advice<Action>>, GameError> {
+    if player != 0 {
+        return Err(GameError::new(
+            ErrorCode::NotYourTurn,
+            "Only the solver seat may request a hint",
+            "Use seat 0.",
+        ));
+    }
+    if outcome(state).is_some() {
+        return Ok(None);
+    }
+    let size = usize::from(state.config.size);
+    let solution = puzzle_solution(state)?;
+    if let Some(cell) = state
+        .grid
+        .iter()
+        .zip(solution)
+        .position(|(&digit, &correct)| digit != 0 && digit != correct)
+    {
+        let row = (cell / size + 1) as u8;
+        let col = (cell % size + 1) as u8;
+        return Ok(Some(Advice {
+            action: Action::Erase { row, col },
+            info: AdviceInfo {
+                summary: format!("Erase r{row}c{col}: its value differs from the puzzle's verified unique solution."),
+                technique: "solution_check".into(),
+                is_guess: false,
+                details: serde_json::json!({"cell":cell,"row":row,"col":col}),
+            },
+        }));
+    }
+    let grid = Grid::from_cells(state.config.size, state.grid.clone())?;
+    let Some(steps) = hint(&grid)? else {
+        return Ok(None);
+    };
+    let step = steps
+        .last()
+        .ok_or_else(|| GameError::position("Hint has no steps"))?;
+    let placement = step
+        .placements
+        .first()
+        .ok_or_else(|| GameError::position("Hint has no placement"))?;
+    let row = (placement.cell / size + 1) as u8;
+    let col = (placement.cell % size + 1) as u8;
+    let digit = placement.digit;
+    let technique = serde_json::to_value(step.technique)?
+        .as_str()
+        .ok_or_else(|| GameError::position("Hint technique is invalid"))?
+        .to_owned();
+    let is_guess = step.technique == Technique::Guess;
+    let summary = if is_guess {
+        format!("Search-backed guess: place {digit} at r{row}c{col}. No supported logical placement remains.")
+    } else {
+        format!(
+            "Use {} to place {digit} at r{row}c{col}.",
+            technique.replace('_', " ")
+        )
+    };
+    Ok(Some(Advice {
+        action: Action::Place { row, col, digit },
+        info: AdviceInfo {
+            summary,
+            technique,
+            is_guess,
+            details: serde_json::json!({"steps":steps}),
+        },
+    }))
+}