wowlab_common/sim/

sentinel_config.rs

//! Sentinel config TOML build/parse.

use serde::{Deserialize, Serialize};
#[cfg(feature = "wasm")]
use tsify::Tsify;

const DEFAULT_TARGET_ERROR: f64 = 0.05;
const DEFAULT_ITERATIONS: i32 = 10_000;
const DEFAULT_MIN_ITERATIONS: u32 = 100;
const DEFAULT_MAX_ITERATIONS: u32 = 50_000;

/// Operation being performed when Sentinel configuration handling failed.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum SentinelConfigOperation {
    Parse,
    Serialize,
}

/// Failure to parse or serialize Sentinel configuration TOML.
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
#[non_exhaustive]
pub struct SentinelConfigError {
    #[source]
    kind: SentinelConfigErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum SentinelConfigErrorKind {
    #[error("TOML parse error: {0}")]
    Deserialize(#[source] toml::de::Error),
    #[error("TOML serialization error: {0}")]
    Serialize(#[source] toml::ser::Error),
}

impl SentinelConfigError {
    fn deserialize(source: toml::de::Error) -> Self {
        Self {
            kind: SentinelConfigErrorKind::Deserialize(source),
        }
    }

    fn serialize(source: toml::ser::Error) -> Self {
        Self {
            kind: SentinelConfigErrorKind::Serialize(source),
        }
    }

    /// Return the operation that failed.
    #[must_use]
    pub const fn operation(&self) -> SentinelConfigOperation {
        match self.kind {
            SentinelConfigErrorKind::Deserialize(_) => SentinelConfigOperation::Parse,
            SentinelConfigErrorKind::Serialize(_) => SentinelConfigOperation::Serialize,
        }
    }
}

impl From<toml::de::Error> for SentinelConfigError {
    fn from(source: toml::de::Error) -> Self {
        Self::deserialize(source)
    }
}

impl From<toml::ser::Error> for SentinelConfigError {
    fn from(source: toml::ser::Error) -> Self {
        Self::serialize(source)
    }
}

/// Configuration consumed by the sentinel scheduler, stored as TOML in `jobs.sentinel_config`.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct SentinelConfig {
    #[serde(default = "default_strategy")]
    pub strategy: String,
    pub iterations: i32,
    #[serde(default)]
    pub max_chunks: i32,
    #[serde(default)]
    pub priority: i32,
    #[serde(default = "default_target_error")]
    pub target_error: f64,
    #[serde(default = "default_min_iterations")]
    pub min_iterations: u32,
    #[serde(default = "default_max_iterations")]
    pub max_iterations: u32,
    #[serde(default)]
    pub target_nodes: Vec<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub tournament: Option<TournamentConfig>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub factorial: Option<FactorialConfig>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub screening: Option<ScreeningConfig>,
}

/// Factorial-screening phase configuration.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct FactorialConfig {
    #[serde(default = "default_main_iters")]
    pub main_iters: u32,
    #[serde(default = "default_interaction_iters")]
    pub interaction_iters: u32,
    #[serde(default = "default_top_k_per_slot")]
    pub top_k_per_slot: u32,
}

impl Default for FactorialConfig {
    fn default() -> Self {
        Self {
            main_iters: default_main_iters(),
            interaction_iters: default_interaction_iters(),
            top_k_per_slot: default_top_k_per_slot(),
        }
    }
}

/// Screening phase configuration.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct ScreeningConfig {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub keep_pct: Option<f64>,
    #[serde(default = "default_keep_min")]
    pub keep_min: u32,
}

const DEFAULT_MAIN_ITERS: u32 = 2_000;
const DEFAULT_INTERACTION_ITERS: u32 = 1_500;
const DEFAULT_TOP_K_PER_SLOT: u32 = 4;
const DEFAULT_KEEP_MIN: u32 = 100;

const fn default_main_iters() -> u32 {
    DEFAULT_MAIN_ITERS
}

const fn default_interaction_iters() -> u32 {
    DEFAULT_INTERACTION_ITERS
}

const fn default_top_k_per_slot() -> u32 {
    DEFAULT_TOP_K_PER_SLOT
}

const fn default_keep_min() -> u32 {
    DEFAULT_KEEP_MIN
}

impl Default for ScreeningConfig {
    fn default() -> Self {
        Self {
            keep_pct: None,
            keep_min: default_keep_min(),
        }
    }
}

/// Optional tournament-specific settings.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct TournamentConfig {
    #[serde(default)]
    pub phases: Vec<TournamentPhaseConfig>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub slot_candidates: Vec<SlotCandidatesConfig>,
}

/// One elimination phase for the tournament strategy.
#[derive(Clone, Debug, Deserialize, Serialize)]
pub struct TournamentPhaseConfig {
    pub iterations: u32,
    pub keep_fraction_x100: u32,
}

/// Candidate items for a single gear slot in a tournament job.
#[derive(Clone, Debug, Deserialize, Serialize)]
#[cfg_attr(feature = "wasm", derive(Tsify))]
pub struct SlotCandidatesConfig {
    pub slot: String,
    #[serde(default)]
    pub items: Vec<CandidateItemConfig>,
}

/// One candidate item for a slot.
#[derive(Clone, Debug, Deserialize, Serialize)]
#[cfg_attr(feature = "wasm", derive(Tsify))]
pub struct CandidateItemConfig {
    pub item_id: u32,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub bonus_ids: Vec<u32>,
    #[serde(default, skip_serializing_if = "is_zero_u32")]
    pub enchant_id: u32,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub gem_ids: Vec<u32>,
}

#[expect(
    clippy::trivially_copy_pass_by_ref,
    reason = "serde skip_serializing_if predicates receive field references"
)]
const fn is_zero_u32(v: &u32) -> bool {
    *v == 0
}

fn default_strategy() -> String {
    "single".to_owned()
}

const fn default_target_error() -> f64 {
    DEFAULT_TARGET_ERROR
}

const fn default_min_iterations() -> u32 {
    DEFAULT_MIN_ITERATIONS
}

const fn default_max_iterations() -> u32 {
    DEFAULT_MAX_ITERATIONS
}

impl Default for SentinelConfig {
    fn default() -> Self {
        Self {
            strategy: default_strategy(),
            iterations: DEFAULT_ITERATIONS,
            max_chunks: 0,
            priority: 0,
            target_error: default_target_error(),
            min_iterations: default_min_iterations(),
            max_iterations: default_max_iterations(),
            target_nodes: Vec::new(),
            tournament: None,
            factorial: None,
            screening: None,
        }
    }
}

/// Serialize a [`SentinelConfig`] to its canonical pretty-printed TOML form.
///
/// # Errors
///
/// Returns an error when TOML serialization fails.
pub fn build_sentinel_config(config: &SentinelConfig) -> Result<String, SentinelConfigError> {
    Ok(toml::to_string_pretty(config)?)
}

/// Deserialize a [`SentinelConfig`] from its TOML representation.
///
/// # Errors
///
/// Returns an error when the TOML does not satisfy the [`SentinelConfig`] schema.
pub fn parse_sentinel_config(toml_str: &str) -> Result<SentinelConfig, SentinelConfigError> {
    Ok(toml::from_str(toml_str)?)
}

#[cfg(test)]
mod tests {
    use std::error::Error as _;

    use googletest::prelude::*;

    use super::*;

    #[gtest]
    fn test_roundtrip() -> Result<()> {
        let config = SentinelConfig {
            strategy: "single".into(),
            iterations: 100_000,
            max_chunks: 10,
            priority: 2,
            target_error: 0.01,
            min_iterations: 100,
            max_iterations: 50_000,
            target_nodes: vec!["node-abc".into()],
            tournament: None,
            factorial: None,
            screening: None,
        };
        let toml_str = build_sentinel_config(&config).or_fail()?;
        let parsed = parse_sentinel_config(&toml_str).or_fail()?;

        verify_that!(
            parsed,
            matches_pattern!(SentinelConfig {
                iterations: eq(&100_000),
                max_chunks: eq(&10),
                priority: eq(&2),
                target_error: near(0.01, f64::EPSILON),
                target_nodes: elements_are!["node-abc"],
                tournament: none(),
                ..
            })
        )
    }

    #[gtest]
    fn test_defaults() -> Result<()> {
        let toml_str = "iterations = 50000\n";
        let parsed = parse_sentinel_config(toml_str).or_fail()?;

        verify_that!(
            parsed,
            matches_pattern!(SentinelConfig {
                iterations: eq(&50_000),
                max_chunks: eq(&0),
                priority: eq(&0),
                target_error: near(0.05, f64::EPSILON),
                min_iterations: eq(&100),
                max_iterations: eq(&50_000),
                target_nodes: is_empty(),
                tournament: none(),
                ..
            })
        )
    }

    #[gtest]
    fn malformed_and_empty_toml_preserve_parse_sources() -> Result<()> {
        for source in ["[", ""] {
            let error = parse_sentinel_config(source).err().or_fail()?;

            verify_that!(error.operation(), eq(SentinelConfigOperation::Parse))?;
            verify_that!(error.to_string(), starts_with("TOML parse error:"))?;
            verify_true!(
                error
                    .source()
                    .and_then(std::error::Error::source)
                    .is_some_and(<dyn std::error::Error>::is::<toml::de::Error>)
            )?;
        }

        Ok(())
    }

    #[gtest]
    fn unicode_values_roundtrip_unchanged() -> Result<()> {
        let config = SentinelConfig {
            strategy: "épreuve-世界".to_string(),
            target_nodes: vec!["nœud-🦊".to_string()],
            ..SentinelConfig::default()
        };

        let serialized = build_sentinel_config(&config).or_fail()?;
        let parsed = parse_sentinel_config(&serialized).or_fail()?;

        verify_that!(parsed.strategy, eq(&config.strategy))?;

        verify_that!(parsed.target_nodes, eq(&config.target_nodes))
    }

    #[gtest]
    fn test_tournament_section_roundtrip() -> Result<()> {
        let config = SentinelConfig {
            strategy: "tournament".into(),
            iterations: 250_000,
            priority: 1,
            tournament: Some(TournamentConfig {
                phases: vec![
                    TournamentPhaseConfig {
                        iterations: 2_000,
                        keep_fraction_x100: 25,
                    },
                    TournamentPhaseConfig {
                        iterations: 10_000,
                        keep_fraction_x100: 0,
                    },
                ],
                slot_candidates: vec![],
            }),
            ..SentinelConfig::default()
        };

        let toml_str = build_sentinel_config(&config).or_fail()?;
        let parsed = parse_sentinel_config(&toml_str).or_fail()?;
        let tournament = parsed.tournament.or_fail()?;

        verify_that!(
            tournament.phases,
            elements_are![
                pat!(TournamentPhaseConfig {
                    iterations: eq(&2_000),
                    keep_fraction_x100: eq(&25),
                }),
                pat!(TournamentPhaseConfig {
                    iterations: eq(&10_000),
                    keep_fraction_x100: eq(&0),
                })
            ]
        )
    }

    #[gtest]
    fn test_factorial_section_roundtrip() -> Result<()> {
        let config = SentinelConfig {
            strategy: "tournament".into(),
            factorial: Some(FactorialConfig {
                main_iters: 3_000,
                interaction_iters: 1_750,
                top_k_per_slot: 5,
            }),
            screening: Some(ScreeningConfig {
                keep_pct: Some(2.5),
                keep_min: 250,
            }),
            ..SentinelConfig::default()
        };

        let toml_str = build_sentinel_config(&config).or_fail()?;
        let parsed = parse_sentinel_config(&toml_str).or_fail()?;
        let factorial = parsed.factorial.or_fail()?;

        verify_that!(
            factorial,
            matches_pattern!(FactorialConfig {
                main_iters: eq(&3_000),
                interaction_iters: eq(&1_750),
                top_k_per_slot: eq(&5),
            })
        )?;
        let screening = parsed.screening.or_fail()?;

        verify_that!(
            screening,
            matches_pattern!(ScreeningConfig {
                keep_pct: some(eq(&2.5)),
                keep_min: eq(&250),
            })
        )
    }

    #[gtest]
    fn test_factorial_defaults() -> Result<()> {
        let fc = FactorialConfig::default();

        verify_that!(
            fc,
            matches_pattern!(FactorialConfig {
                main_iters: eq(&2_000),
                interaction_iters: eq(&1_500),
                top_k_per_slot: eq(&4),
            })
        )
    }

    #[gtest]
    fn test_screening_defaults_match_serde_defaults() -> Result<()> {
        let default = ScreeningConfig::default();
        let parsed: ScreeningConfig = toml::from_str("").or_fail()?;

        verify_that!(parsed.keep_pct, eq(default.keep_pct))?;
        verify_that!(parsed.keep_min, eq(default.keep_min))?;

        verify_that!(default.keep_min, eq(DEFAULT_KEEP_MIN))
    }
}