@@ -103,10 +103,7 @@ async fn stockfish_http_seats_analysis_and_idempotency() -> Result<(), ServerErr
         .contains(&analysis["best_moves"][0]));
     assert!(analysis["evaluation"].is_null());
     assert_eq!(
-        analysis["advice"]["details"]["variations"]
-            .as_array()
-            .ok_or("variations")?
-            .len(),
+        analysis["variations"].as_array().ok_or("variations")?.len(),
         2
     );
     let (_, after) = call(&app.router, "GET", &replay_path, Value::Null, None).await?;
 
@@ -141,3 +141,55 @@ fn multipv_retains_only_legal_lines_and_selected_move_diagnostics() -> TestResul
     );
     Ok(())
 }
+
+#[test]
+fn analysis_ranks_all_variations_and_rejects_duplicate_roots() -> TestResult {
+    let game = game()?;
+    let state = game.initial_state(&json!({}), 7)?;
+    let observation = game.observe(&state, Viewer::Player(0))?;
+    let legal = game.legal_actions(&state, 0)?;
+    let turn = PlayerTurn {
+        seat: 0,
+        observation: &observation,
+        legal_actions: &legal,
+    };
+    let limits = SearchLimits {
+        nodes: 1000,
+        depth: 8,
+        time_ms: 5000,
+        seed: 7,
+    };
+    let mut output = result();
+    let mut second = output.variations[0].clone();
+    second.multipv = Some(2);
+    second.pv = vec!["d2d4".into(), "d7d5".into()];
+    output.variations.insert(0, second);
+    let choices =
+        gfa_engine_uci::validate_analysis(game.as_ref(), &json!({}), &turn, limits, &output)?;
+    assert_eq!(
+        choices
+            .iter()
+            .map(|choice| choice.action.string.as_str())
+            .collect::<Vec<_>>(),
+        ["e2e4", "d2d4"]
+    );
+    for choice in choices {
+        assert_eq!(
+            choice.info.principal_variation.first(),
+            Some(&choice.action.string)
+        );
+        assert_eq!(
+            choice.info.advice.ok_or("diagnostics")?.details["variations"]
+                .as_array()
+                .ok_or("line")?
+                .len(),
+            1
+        );
+    }
+    output.variations[0].pv = output.variations[1].pv.clone();
+    assert_eq!(
+        gfa_engine_uci::validate_analysis(game.as_ref(), &json!({}), &turn, limits, &output),
+        Err(OpponentError::InvalidResponse)
+    );
+    Ok(())
+}
@@ -36,8 +36,13 @@ impl gfa_opponents::Clock for SearchClock {
     }
 }
 
-impl OpponentExecutor for Workers {
-    fn execute(&self, job: OpponentJob) -> OpponentFuture<'_> {
+impl Workers {
+    fn schedule<T: Send + 'static>(
+        &self,
+        job: impl FnOnce(&SearchClock) -> Result<T, gfa_api_types::ApiError> + Send + 'static,
+    ) -> std::pin::Pin<
+        Box<dyn std::future::Future<Output = Result<T, gfa_api_types::ApiError>> + Send>,
+    > {
         let capacity = self.0.clone();
         Box::pin(async move {
             let permit = capacity.try_acquire_owned().map_err(|_| {
@@ -50,9 +55,9 @@ impl OpponentExecutor for Workers {
             let cancelled = Arc::new(AtomicBool::new(false));
             let _cancel_on_drop = CancelOnDrop(cancelled.clone());
             tokio::task::spawn_blocking(move || {
-                // A dropped HTTP request must not release capacity while CPU work continues.
+                // Capacity remains leased until CPU work responds to cancellation and exits.
                 let _permit = permit;
-                job.run(&SearchClock {
+                job(&SearchClock {
                     cancelled,
                     clock: gfa_opponents::SystemClock::default(),
                 })
@@ -68,6 +73,14 @@ impl OpponentExecutor for Workers {
         })
     }
 }
+impl OpponentExecutor for Workers {
+    fn execute(&self, job: OpponentJob) -> OpponentFuture<'_> {
+        self.schedule(move |clock| job.run(clock))
+    }
+    fn analyze(&self, job: OpponentJob) -> gfa_service::AnalysisFuture<'_> {
+        self.schedule(move |clock| job.analyze(clock))
+    }
+}
 
 #[cfg(test)]
 mod tests {
 
@@ -63,7 +63,8 @@ impl SearchLimits {
 }
 
 /// Search diagnostics accompanying a chosen move.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, crate::schemars::JsonSchema)]
 
 pub struct ChoiceInfo {
     /// Optional engine-provided solving explanation.
@@ -84,7 +85,8 @@ pub struct ChoiceInfo {
 }
 
 /// One legal move and optional explanatory diagnostics.
-#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
+#[cfg_attr(feature = "openapi", derive(utoipa::ToSchema))]
+#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, crate::schemars::JsonSchema)]
 
 pub struct ActionChoice {
     /// Canonical action selected from the supplied legal list.
@@ -141,6 +143,17 @@ pub trait Opponent: Send + Sync {
         self.choose_action(turn, limits, clock)
             .map_err(OpponentError::Game)
     }
+
+    /// Ranked legal analysis recommendations. Existing players return their single decision.
+    /// Hosts validate the returned list and enforce a maximum of sixteen alternatives.
+    fn analyze(
+        &self,
+        turn: &PlayerTurn<'_>,
+        limits: SearchLimits,
+        clock: &dyn Clock,
+    ) -> Result<Vec<ActionChoice>, OpponentError> {
+        self.decide(turn, limits, clock).map(|choice| vec![choice])
+    }
 }
 
 fn invalid(message: &str) -> GameError {
 
@@ -116,6 +116,9 @@ pub struct AnalysisResult {
     pub seed: u64,
     /// Recommended legal actions in order of preference.
     pub best_moves: Vec<LegalAction>,
+    /// Per-move analysis in the same preference order as best_moves.
+    #[serde(default)]
+    pub variations: Vec<gfa_core::ActionChoice>,
     /// Expected return for the requesting seat, absent without completed search.
     pub evaluation: Option<f64>,
     /// Canonical continuation, beginning with the recommended action.
 
@@ -27,7 +27,8 @@ mod fork;
 mod opponents;
 mod planning;
 pub use opponents::{
-    BuiltinOpponentFactory, OpponentExecutor, OpponentFactory, OpponentFuture, OpponentJob,
+    AnalysisFuture, BuiltinOpponentFactory, OpponentExecutor, OpponentFactory, OpponentFuture,
+    OpponentJob,
 };
 
 mod seats;
 
@@ -15,6 +15,10 @@ use std::{future::Future, pin::Pin, sync::Arc};
 pub type OpponentFuture<'a> =
     Pin<Box<dyn Future<Output = Result<ActionChoice, ApiError>> + Send + 'a>>;
 
+/// Bounded recommendations returned by an analysis worker.
+pub type AnalysisFuture<'a> =
+    Pin<Box<dyn Future<Output = Result<Vec<ActionChoice>, ApiError>> + Send + 'a>>;
+
 /// Select installed players without exposing live state or transport details.
 pub trait OpponentFactory: Send + Sync {
     /// Stable catalog for this game.
@@ -33,6 +37,10 @@ pub trait OpponentFactory: Send + Sync {
 pub trait OpponentExecutor: Send + Sync {
     /// Run outside the request executor, rejecting excess work instead of queueing without bounds.
     fn execute(&self, job: OpponentJob) -> OpponentFuture<'_>;
+    /// Analyze on the host's bounded executor. Legacy executors retain single-choice behavior.
+    fn analyze(&self, job: OpponentJob) -> AnalysisFuture<'_> {
+        Box::pin(async move { self.execute(job).await.map(|choice| vec![choice]) })
+    }
 }
 
 /// Owned planning input. No raw match state or match RNG is passed to the worker.
@@ -45,6 +53,21 @@ pub struct OpponentJob {
 }
 
 impl OpponentJob {
+    /// Request ranked analysis recommendations with the same observation-only input.
+    pub fn analyze(self, clock: &dyn Clock) -> Result<Vec<ActionChoice>, ApiError> {
+        self.opponent
+            .analyze(
+                &PlayerTurn {
+                    seat: self.seat,
+                    observation: &self.observation,
+                    legal_actions: &self.legal_actions,
+                },
+                self.limits,
+                clock,
+            )
+            .map_err(error::opponent)
+    }
+
     /// Execute with an injected monotonic clock. The host supplies the runtime.
     pub fn run(self, clock: &dyn Clock) -> Result<ActionChoice, ApiError> {
         self.opponent
@@ -267,27 +290,42 @@ impl GameService {
                 "Select the current player or an earlier turn.",
             ));
         }
-        let choice = self
-            .choose_opponent(
-                planning.game,
-                planning.config,
-                &request.opponent,
-                seed,
-                seat,
-                visible,
+        let (factory, executor) = self.opponents.as_ref().ok_or_else(|| {
+            ApiError::new(
+                "ENGINE_UNAVAILABLE",
+                "No opponent executor is installed",
+                "Configure an opponent worker pool on the host.",
             )
+        })?;
+        let (opponent, limits) =
+            factory.create(planning.game, planning.config, &request.opponent, seed)?;
+        let choices = executor
+            .analyze(OpponentJob {
+                opponent,
+                seat,
+                observation: visible.observation,
+                legal_actions: visible.legal_actions.clone(),
+                limits,
+            })
             .await?;
+        validate_analysis_choices(&choices, &visible.legal_actions)?;
+        let choice = choices.first().ok_or_else(invalid_analysis)?;
         Ok(AnalysisResult {
-            advice: choice.info.advice,
+            advice: choice.info.advice.clone(),
             game_id: request.game_id,
             opponent: request.opponent.id,
             seed,
-            best_moves: vec![choice.action],
+            best_moves: choices.iter().map(|choice| choice.action.clone()).collect(),
             evaluation: choice.info.evaluation,
-            principal_variation: choice.info.principal_variation,
-            nodes: choice.info.nodes,
+            principal_variation: choice.info.principal_variation.clone(),
+            nodes: choices
+                .iter()
+                .map(|choice| choice.info.nodes)
+                .max()
+                .unwrap_or(0),
             depth: choice.info.depth,
-            budget_exhausted: choice.info.budget_exhausted,
+            budget_exhausted: choices.iter().any(|choice| choice.info.budget_exhausted),
+            variations: choices,
         })
     }
 }
@@ -339,3 +377,79 @@ mod failure_tests {
         Ok(())
     }
 }
+
+fn invalid_analysis() -> ApiError {
+    ApiError::new(
+        "ENGINE_INVALID_RESPONSE",
+        "Opponent returned invalid analysis recommendations",
+        "Select another opponent and report the provider failure.",
+    )
+}
+fn validate_analysis_choices(
+    choices: &[ActionChoice],
+    legal: &[LegalAction],
+) -> Result<(), ApiError> {
+    if choices.is_empty() || choices.len() > 16 {
+        return Err(invalid_analysis());
+    }
+    let mut seen = std::collections::BTreeSet::new();
+    for choice in choices {
+        if !legal.contains(&choice.action)
+            || !seen.insert(choice.action.index)
+            || choice
+                .info
+                .evaluation
+                .is_some_and(|score| !score.is_finite())
+            || choice.info.principal_variation.len() > 128
+            || choice
+                .info
+                .principal_variation
+                .first()
+                .is_some_and(|first| first != &choice.action.string)
+        {
+            return Err(invalid_analysis());
+        }
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod analysis_validation_tests {
+    use super::*;
+    fn choice() -> ActionChoice {
+        ActionChoice {
+            action: LegalAction {
+                string: "a".into(),
+                json: serde_json::json!("a"),
+                index: 0,
+            },
+            info: gfa_core::ChoiceInfo {
+                advice: None,
+                algorithm: "test".into(),
+                nodes: 1,
+                depth: 1,
+                evaluation: Some(0.0),
+                principal_variation: vec!["a".into()],
+                budget_exhausted: false,
+            },
+        }
+    }
+    #[test]
+    fn rejects_empty_duplicate_nonfinite_illegal_and_mismatched_analysis() {
+        let first = choice();
+        let legal = vec![first.action.clone()];
+        assert!(validate_analysis_choices(std::slice::from_ref(&first), &legal).is_ok());
+        assert!(validate_analysis_choices(&[], &legal).is_err());
+        assert!(validate_analysis_choices(&vec![first.clone(); 17], &legal).is_err());
+        assert!(validate_analysis_choices(&[first.clone(), first.clone()], &legal).is_err());
+        let mut bad = first.clone();
+        bad.info.evaluation = Some(f64::NAN);
+        assert!(validate_analysis_choices(&[bad], &legal).is_err());
+        let mut bad = first.clone();
+        bad.action.string = "b".into();
+        assert!(validate_analysis_choices(&[bad], &legal).is_err());
+        let mut bad = first;
+        bad.info.principal_variation[0] = "b".into();
+        assert!(validate_analysis_choices(&[bad], &legal).is_err());
+    }
+}
@@ -45,3 +45,11 @@ a result escapes the adapter. PVs expose at most 32 validated plies and mark
 truncation. Engine scores retain their units and root-seat perspective in
 advice.details; ChoiceInfo.evaluation remains absent because a centipawn or mate
 score is not an expected game return. All MultiPV lines are retained there.
+
+
+The shared Opponent::analyze path returns a ranked ActionChoice for each validated
+MultiPV line. The HTTP response includes these in variations and mirrors their
+actions in best_moves. Each variation carries its own depth, continuation and
+typed score metadata. The default implementation keeps single-choice players
+compatible. Analysis uses the same bounded worker capacity and cancellation
+policy as automatic moves.
@@ -197,4 +197,4 @@ pub(crate) fn invalid(message: &str) -> GameError {
 mod tests;
 
 mod player;
-pub use player::{validate_recommendation, UciOpponent};
+pub use player::{validate_analysis, validate_recommendation, UciOpponent};