wowlab_common/sim/

intent.rs

// #t(file: rust_inline_test_module_size) tests cover private validation and JSON-to-TOML conversion boundaries

//! Sim config TOML: build from portal input, parse back for the engine.

use std::collections::BTreeMap;

use serde::{Deserialize, Serialize};
#[cfg(test)]
use wowlab_types::game::GearSlot;
use wowlab_types::{
    constants::{CURRENT_EXPANSION_ID, MAX_PLAYER_LEVEL},
    game::{GearEntry, SpecId},
    sim::{EncounterDefinition, EncounterValidationError},
};

/// Intent schema version stamped into every [`SimConfigIntent`] and checked by the engine validator.
pub const INTENT_VERSION: &str = "v2";
const OBSOLETE_ENCOUNTER_SETTINGS: [&str; 6] = [
    "duration_s",
    "enemy_count",
    "target_count",
    "fight_style",
    "level",
    "expansion_id",
];

/// Sim configuration as supplied by the portal.
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IntentInput {
    pub spec_id: u32,
    pub rotation_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub loadout: Option<String>,
    /// Named expansion progression systems and their selected trait entry slugs.
    #[serde(default)]
    pub expansion_talents: BTreeMap<String, Vec<String>>,
    #[serde(default)]
    // #t(rust_pub_api_foreign_types) JSON values are the portal wire-input contract
    pub settings: BTreeMap<String, serde_json::Value>,
    #[serde(default)]
    pub equipment: Vec<GearEntry>,
    pub player_level: u16,
    pub player_expansion_id: u32,
    pub encounter: EncounterDefinition,
}

/// Versioned TOML form of the sim intent shipped to the engine.
#[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
#[serde(deny_unknown_fields)]
pub struct SimConfigIntent {
    pub intent_version: String,
    pub spec: u32,
    pub rotation_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub loadout: Option<String>,
    /// Named expansion progression systems and their selected trait entry slugs.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub expansion_talents: BTreeMap<String, Vec<String>>,
    pub player_level: u16,
    pub player_expansion_id: u32,
    pub encounter: EncounterDefinition,
    // #t(rust_pub_api_foreign_types) TOML values are the persisted sim-config wire contract
    pub settings: BTreeMap<String, toml::Value>,
    pub gear: Vec<GearEntry>,
}

/// Operation being performed when an intent configuration failed.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum IntentConfigOperation {
    Build,
    Parse,
    Serialize,
}

wowlab_engine_macros::define_error! {
/// Failure to build, parse, validate, or serialize a simulation intent.
#[derive(Debug)]
#[non_exhaustive]
pub struct IntentConfigError {
    #[source]
    kind: IntentConfigErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum IntentConfigErrorKind {
    #[error("TOML parse error: {source}")]
    TomlDeserialize {
        operation: IntentConfigOperation,
        #[source]
        source: toml::de::Error,
    },
    #[error("TOML serialization error: {source}")]
    TomlSerialize {
        operation: IntentConfigOperation,
        #[source]
        source: toml::ser::Error,
    },
    #[error("unknown wow spec id: {spec_id}")]
    UnknownSpec { spec_id: u32 },
    #[error("unsupported number: {number}")]
    UnsupportedSettingNumber {
        setting: String,
        number: serde_json::Number,
    },
    #[error("null values are not supported in TOML")]
    NullSetting { setting: String },
    #[error("unsupported intent version {found:?}; only {supported:?} is accepted")]
    UnsupportedIntentVersion {
        operation: IntentConfigOperation,
        found: String,
        supported: &'static str,
    },
    #[error("obsolete aggregate encounter setting {key:?}; author the typed encounter instead")]
    ObsoleteEncounterSetting {
        operation: IntentConfigOperation,
        key: &'static str,
    },
    #[error("invalid player_level {player_level}: must be non-zero")]
    InvalidPlayerLevel {
        operation: IntentConfigOperation,
        player_level: u16,
    },
    #[error("invalid player_expansion_id {player_expansion_id}: must be non-zero")]
    InvalidPlayerExpansionId {
        operation: IntentConfigOperation,
        player_expansion_id: u32,
    },
    #[error("invalid encounter: {source}")]
    InvalidEncounter {
        operation: IntentConfigOperation,
        #[source]
        source: EncounterValidationError,
    },
}
}

impl IntentConfigError {
    fn toml_deserialize(operation: IntentConfigOperation, source: toml::de::Error) -> Self {
        Self {
            kind: IntentConfigErrorKind::TomlDeserialize { operation, source },
        }
    }

    fn toml_serialize(operation: IntentConfigOperation, source: toml::ser::Error) -> Self {
        Self {
            kind: IntentConfigErrorKind::TomlSerialize { operation, source },
        }
    }

    const fn unknown_spec(spec_id: u32) -> Self {
        Self {
            kind: IntentConfigErrorKind::UnknownSpec { spec_id },
        }
    }

    fn unsupported_setting_number(setting: String, number: serde_json::Number) -> Self {
        Self {
            kind: IntentConfigErrorKind::UnsupportedSettingNumber { setting, number },
        }
    }

    fn null_setting(setting: String) -> Self {
        Self {
            kind: IntentConfigErrorKind::NullSetting { setting },
        }
    }

    fn unsupported_version(operation: IntentConfigOperation, found: String) -> Self {
        Self {
            kind: IntentConfigErrorKind::UnsupportedIntentVersion {
                operation,
                found,
                supported: INTENT_VERSION,
            },
        }
    }

    const fn obsolete_encounter_setting(
        operation: IntentConfigOperation,
        key: &'static str,
    ) -> Self {
        Self {
            kind: IntentConfigErrorKind::ObsoleteEncounterSetting { operation, key },
        }
    }

    const fn invalid_player_level(operation: IntentConfigOperation, player_level: u16) -> Self {
        Self {
            kind: IntentConfigErrorKind::InvalidPlayerLevel {
                operation,
                player_level,
            },
        }
    }

    const fn invalid_player_expansion_id(
        operation: IntentConfigOperation,
        player_expansion_id: u32,
    ) -> Self {
        Self {
            kind: IntentConfigErrorKind::InvalidPlayerExpansionId {
                operation,
                player_expansion_id,
            },
        }
    }

    fn invalid_encounter(
        operation: IntentConfigOperation,
        source: EncounterValidationError,
    ) -> Self {
        Self {
            kind: IntentConfigErrorKind::InvalidEncounter { operation, source },
        }
    }

    /// Return the operation that failed.
    #[must_use]
    pub const fn operation(&self) -> IntentConfigOperation {
        match self.kind {
            IntentConfigErrorKind::TomlDeserialize { operation, .. }
            | IntentConfigErrorKind::TomlSerialize { operation, .. }
            | IntentConfigErrorKind::UnsupportedIntentVersion { operation, .. }
            | IntentConfigErrorKind::ObsoleteEncounterSetting { operation, .. }
            | IntentConfigErrorKind::InvalidPlayerLevel { operation, .. }
            | IntentConfigErrorKind::InvalidPlayerExpansionId { operation, .. }
            | IntentConfigErrorKind::InvalidEncounter { operation, .. } => operation,
            IntentConfigErrorKind::UnknownSpec { .. }
            | IntentConfigErrorKind::UnsupportedSettingNumber { .. }
            | IntentConfigErrorKind::NullSetting { .. } => IntentConfigOperation::Build,
        }
    }

    /// Return the unknown `WoW` specialization ID, when applicable.
    #[must_use]
    pub const fn unknown_spec_id(&self) -> Option<u32> {
        match self.kind {
            IntentConfigErrorKind::UnknownSpec { spec_id } => Some(spec_id),
            _ => None,
        }
    }

    /// Return the top-level setting key whose JSON value cannot be represented in TOML.
    #[must_use]
    pub fn setting_key(&self) -> Option<&str> {
        match &self.kind {
            IntentConfigErrorKind::UnsupportedSettingNumber { setting, .. }
            | IntentConfigErrorKind::NullSetting { setting } => Some(setting),
            _ => None,
        }
    }

    /// Return the unsupported version string, when applicable.
    #[must_use]
    pub fn unsupported_version_value(&self) -> Option<&str> {
        match &self.kind {
            IntentConfigErrorKind::UnsupportedIntentVersion { found, .. } => Some(found),
            _ => None,
        }
    }

    /// Return the invalid player level, when applicable.
    #[must_use]
    pub const fn invalid_player_level_value(&self) -> Option<u16> {
        match self.kind {
            IntentConfigErrorKind::InvalidPlayerLevel { player_level, .. } => Some(player_level),
            _ => None,
        }
    }

    /// Return the invalid expansion identifier, when applicable.
    #[must_use]
    pub const fn invalid_player_expansion_id_value(&self) -> Option<u32> {
        match self.kind {
            IntentConfigErrorKind::InvalidPlayerExpansionId {
                player_expansion_id,
                ..
            } => Some(player_expansion_id),
            _ => None,
        }
    }
}

impl SimConfigIntent {
    /// Build the canonical single-target (Patchwerk) intent.
    ///
    /// # Panics
    ///
    /// Panics if the compile-time default encounter context is invalid.
    #[must_use]
    pub fn patchwerk(spec: SpecId, duration_s: f64, rotation_id: impl Into<String>) -> Self {
        Self {
            intent_version: INTENT_VERSION.to_string(),
            spec: spec.wow_spec_id(),
            rotation_id: rotation_id.into(),
            loadout: None,
            expansion_talents: BTreeMap::new(),
            player_level: MAX_PLAYER_LEVEL,
            player_expansion_id: CURRENT_EXPANSION_ID,
            encounter: EncounterDefinition::patchwerk(
                duration_s,
                MAX_PLAYER_LEVEL,
                CURRENT_EXPANSION_ID,
            )
            .expect("default Patchwerk context is valid"),
            settings: BTreeMap::new(),
            gear: Vec::new(),
        }
    }
}

/// Build a TOML sim config from an [`IntentInput`] (`spec_id` is the `WoW` API spec ID).
///
/// # Errors
///
/// Returns an error when the spec, settings, encounter, or TOML serialization is invalid.
pub fn build_sim_config(input: IntentInput) -> Result<String, IntentConfigError> {
    let spec = SpecId::from_wow_spec_id(input.spec_id)
        .ok_or_else(|| IntentConfigError::unknown_spec(input.spec_id))?;
    let spec_id = spec.wow_spec_id();

    let mut settings = BTreeMap::new();

    for (k, v) in input.settings {
        let tv = json_to_toml(v, &k)?;

        settings.insert(k, tv);
    }

    let intent = SimConfigIntent {
        intent_version: INTENT_VERSION.to_string(),
        spec: spec_id,
        rotation_id: input.rotation_id,
        loadout: input.loadout,
        expansion_talents: input.expansion_talents,
        player_level: input.player_level,
        player_expansion_id: input.player_expansion_id,
        encounter: input.encounter,
        settings,
        gear: input.equipment,
    };

    validate_intent(&intent, IntentConfigOperation::Build)?;

    toml::to_string_pretty(&intent)
        .map_err(|source| IntentConfigError::toml_serialize(IntentConfigOperation::Build, source))
}

/// Parse and validate the sole current sim-intent contract.
///
/// # Errors
///
/// Returns [`IntentConfigError`] when TOML decoding, version checks, or intent validation fails.
pub fn parse_sim_config(toml_str: &str) -> Result<SimConfigIntent, IntentConfigError> {
    let value: toml::Value = toml::from_str(toml_str).map_err(|source| {
        IntentConfigError::toml_deserialize(IntentConfigOperation::Parse, source)
    })?;
    let found = value
        .get("intent_version")
        .and_then(toml::Value::as_str)
        .unwrap_or_default();

    if found != INTENT_VERSION {
        return Err(IntentConfigError::unsupported_version(
            IntentConfigOperation::Parse,
            found.to_string(),
        ));
    }

    let intent: SimConfigIntent = toml::from_str(toml_str).map_err(|source| {
        IntentConfigError::toml_deserialize(IntentConfigOperation::Parse, source)
    })?;

    validate_intent(&intent, IntentConfigOperation::Parse)?;

    Ok(intent)
}

fn validate_intent(
    intent: &SimConfigIntent,
    operation: IntentConfigOperation,
) -> Result<(), IntentConfigError> {
    if intent.intent_version != INTENT_VERSION {
        return Err(IntentConfigError::unsupported_version(
            operation,
            intent.intent_version.clone(),
        ));
    }

    if intent.player_level == 0 {
        return Err(IntentConfigError::invalid_player_level(
            operation,
            intent.player_level,
        ));
    }

    if intent.player_expansion_id == 0 {
        return Err(IntentConfigError::invalid_player_expansion_id(
            operation,
            intent.player_expansion_id,
        ));
    }

    for key in OBSOLETE_ENCOUNTER_SETTINGS {
        if intent.settings.contains_key(key) {
            return Err(IntentConfigError::obsolete_encounter_setting(
                operation, key,
            ));
        }
    }

    intent
        .encounter
        .validate()
        .map_err(|source| IntentConfigError::invalid_encounter(operation, source))?;

    Ok(())
}

/// Serialize a [`SimConfigIntent`] back to canonical pretty-printed TOML.
///
/// # Errors
///
/// Returns an error when the intent is invalid or TOML serialization fails.
pub fn serialize_sim_config(intent: &SimConfigIntent) -> Result<String, IntentConfigError> {
    validate_intent(intent, IntentConfigOperation::Serialize)?;

    toml::to_string_pretty(intent).map_err(|source| {
        IntentConfigError::toml_serialize(IntentConfigOperation::Serialize, source)
    })
}

// #t(fn: rust_recursive_fn) bounded tree mapping over JSON value - depth limited by input
fn json_to_toml(v: serde_json::Value, setting: &str) -> Result<toml::Value, IntentConfigError> {
    match v {
        serde_json::Value::Bool(b) => Ok(toml::Value::Boolean(b)),
        serde_json::Value::Number(n) => {
            if let Some(i) = n.as_i64() {
                Ok(toml::Value::Integer(i))
            } else if let Some(f) = n.as_f64() {
                Ok(toml::Value::Float(f))
            } else {
                Err(IntentConfigError::unsupported_setting_number(
                    setting.to_string(),
                    n,
                ))
            }
        }
        serde_json::Value::String(s) => Ok(toml::Value::String(s)),
        serde_json::Value::Array(arr) => {
            let values = arr
                .into_iter()
                .map(|value| json_to_toml(value, setting))
                .collect::<Result<Vec<_>, _>>()?;

            Ok(toml::Value::Array(values))
        }
        serde_json::Value::Object(map) => {
            let mut table = toml::map::Map::new();
            let mut sorted = BTreeMap::new();

            for (k, val) in map {
                sorted.insert(k, val);
            }

            for (k, val) in sorted {
                table.insert(k, json_to_toml(val, setting)?);
            }

            Ok(toml::Value::Table(table))
        }
        serde_json::Value::Null => Err(IntentConfigError::null_setting(setting.to_string())),
    }
}

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

    use googletest::prelude::*;
    use rstest::rstest;

    use super::*;

    fn patchwerk_input(spec_id: u32, rotation_id: &str) -> IntentInput {
        IntentInput {
            spec_id,
            rotation_id: rotation_id.to_string(),
            loadout: None,
            expansion_talents: BTreeMap::new(),
            settings: BTreeMap::new(),
            equipment: Vec::new(),
            player_level: MAX_PLAYER_LEVEL,
            player_expansion_id: CURRENT_EXPANSION_ID,
            encounter: EncounterDefinition::patchwerk(
                300.0,
                MAX_PLAYER_LEVEL,
                CURRENT_EXPANSION_ID,
            )
            .expect("current Patchwerk input is valid"),
        }
    }

    #[gtest]
    fn test_build_sim_config_beast_mastery() -> Result<()> {
        let input = IntentInput {
            equipment: vec![GearEntry {
                slot: GearSlot::Head,
                id: 12345,
                bonus_ids: Some(vec![1, 2, 3]),
                enchant_id: None,
                gem_ids: None,
                crafted_stats: None,
                crafting_quality: None,
                drop_level: None,
                ilevel: None,
            }],
            ..patchwerk_input(253, "rot-123")
        };

        let toml_str = build_sim_config(input).or_fail()?;

        verify_that!(toml_str, contains_substring("intent_version = \"v2\""))?;
        verify_that!(toml_str, contains_substring("spec = 253"))?;
        verify_that!(toml_str, contains_substring("rotation_id = \"rot-123\""))?;
        verify_that!(toml_str, contains_substring("id = 12345"))?;
        verify_that!(toml_str, contains_substring("fixed_duration_s = 300.0"))?;
        verify_that!(
            toml_str,
            contains_substring("display_name = \"Training Dummy\"")
        )?;

        Ok(())
    }

    #[gtest]
    fn test_build_sim_config_unknown_spec() -> Result<()> {
        let input = patchwerk_input(9999, "rot-123");

        let error = build_sim_config(input).err().or_fail()?;

        verify_that!(error.to_string(), eq("unknown wow spec id: 9999"))?;
        verify_that!(error.operation(), eq(IntentConfigOperation::Build))?;
        verify_that!(error.unknown_spec_id(), some(eq(9999)))?;

        Ok(())
    }

    #[gtest]
    fn test_build_sim_config_accepts_all_valid_specs() -> Result<()> {
        let input = patchwerk_input(65, "rot-123");

        let toml_str = build_sim_config(input).or_fail()?;

        verify_that!(toml_str, contains_substring("spec = 65"))?;

        Ok(())
    }

    #[gtest]
    fn test_build_sim_config_uses_explicit_current_encounter() -> Result<()> {
        let mut settings = BTreeMap::new();

        settings.insert("bloodlust".into(), serde_json::Value::Bool(true));

        let input = IntentInput {
            settings,
            player_level: 70,
            player_expansion_id: 10,
            encounter: EncounterDefinition::patchwerk(120.0, 70, 10).or_fail()?,
            ..patchwerk_input(254, "rot-456")
        };

        let toml_str = build_sim_config(input).or_fail()?;

        verify_that!(toml_str, contains_substring("spec = 254"))?;
        verify_that!(toml_str, contains_substring("bloodlust = true"))?;
        let parsed = parse_sim_config(&toml_str).or_fail()?;

        verify_that!(parsed.encounter.fixed_duration_s, some(near(120.0, 1e-9)))?;
        verify_that!(parsed.encounter.enemies[0].level, eq(70))?;
        verify_that!(parsed.player_level, eq(70))?;
        verify_that!(parsed.player_expansion_id, eq(10))?;
        verify_that!(parsed.settings.len(), eq(1))?;

        Ok(())
    }

    #[gtest]
    fn test_parse_sim_config_roundtrip() -> Result<()> {
        let input = patchwerk_input(253, "rot-1");
        let toml_str = build_sim_config(input).or_fail()?;
        let parsed = parse_sim_config(&toml_str).or_fail()?;

        verify_that!(
            parsed,
            matches_pattern!(SimConfigIntent {
                intent_version: "v2",
                spec: eq(&253),
                rotation_id: "rot-1",
                ..
            })
        )?;

        Ok(())
    }

    #[gtest]
    fn test_build_sim_config_passes_loadout() -> Result<()> {
        let input = IntentInput {
            loadout: Some("ABCDEF".into()),
            ..patchwerk_input(260, "rot-1")
        };
        let toml_str = build_sim_config(input).or_fail()?;

        verify_that!(toml_str, contains_substring("loadout = \"ABCDEF\""))?;
        let parsed = parse_sim_config(&toml_str).or_fail()?;

        verify_that!(parsed.loadout.as_deref(), some(eq("ABCDEF")))?;

        Ok(())
    }

    #[gtest]
    fn test_json_to_toml_null_rejected() -> Result<()> {
        let error = json_to_toml(serde_json::Value::Null, "optional_feature")
            .err()
            .or_fail()?;

        verify_that!(
            error.to_string(),
            eq("null values are not supported in TOML")
        )?;
        verify_that!(error.operation(), eq(IntentConfigOperation::Build))?;
        verify_that!(error.setting_key(), some(eq("optional_feature")))?;

        Ok(())
    }

    // The `"unsupported number"` Err arm is dead-in-practice: any JSON number that
    // fails `as_i64` still yields `as_f64 = Some(_)` (even `u64::MAX`), so the Float
    // branch always wins. No test targets it because it is unreachable.
    #[gtest]
    #[rstest]
    #[case::boolean(serde_json::Value::Bool(true), toml::Value::Boolean(true))]
    #[case::integer(serde_json::json!(42), toml::Value::Integer(42))]
    #[case::string(serde_json::Value::String("x".to_string()), toml::Value::String("x".to_string()))]
    #[case::array(
        serde_json::json!([1, 2]),
        toml::Value::Array(vec![toml::Value::Integer(1), toml::Value::Integer(2)])
    )]
    fn json_to_toml_arms(
        #[case] input: serde_json::Value,
        #[case] expected: toml::Value,
    ) -> Result<()> {
        verify_that!(json_to_toml(input, "fixture"), ok(eq(&expected)))
    }

    #[gtest]
    fn json_to_toml_float() -> Result<()> {
        let value = json_to_toml(serde_json::json!(1.5), "fixture").or_fail()?;

        verify_that!(value.as_float(), some(near(1.5, 1e-9)))?;

        Ok(())
    }

    #[gtest]
    fn json_to_toml_object_sorts_keys() -> Result<()> {
        let value = json_to_toml(serde_json::json!({ "b": 1, "a": 2 }), "fixture").or_fail()?;
        let keys: Vec<&str> = value
            .as_table()
            .or_fail()?
            .keys()
            .map(String::as_str)
            .collect();

        verify_that!(keys, container_eq(["a", "b"]))?;

        Ok(())
    }

    #[gtest]
    fn patchwerk_known_answer() -> Result<()> {
        let intent = SimConfigIntent::patchwerk(SpecId::BeastMastery, 240.0, "rot-x");

        verify_that!(
            intent,
            matches_pattern!(SimConfigIntent {
                intent_version: "v2",
                rotation_id: "rot-x",
                spec: eq(&SpecId::BeastMastery.wow_spec_id()),
                loadout: none(),
                gear: is_empty(),
                settings: is_empty(),
                player_level: eq(&MAX_PLAYER_LEVEL),
                player_expansion_id: eq(&CURRENT_EXPANSION_ID),
                ..
            })
        )?;
        verify_that!(intent.encounter.fixed_duration_s, some(near(240.0, 1e-9)))?;

        Ok(())
    }

    #[gtest]
    fn serialize_sim_config_roundtrip() -> Result<()> {
        let intent = SimConfigIntent::patchwerk(SpecId::BeastMastery, 300.0, "rot-y");
        let serialized = serialize_sim_config(&intent);

        verify_that!(&serialized, ok(anything()))?;

        let serialized = serialized.or_fail()?;
        let parsed = parse_sim_config(&serialized).or_fail()?;

        verify_that!(
            parsed,
            matches_pattern!(SimConfigIntent {
                intent_version: "v2",
                rotation_id: "rot-y",
                spec: eq(&SpecId::BeastMastery.wow_spec_id()),
                ..
            })
        )?;

        Ok(())
    }

    #[gtest]
    fn obsolete_v1_intent_is_rejected_without_migration() -> Result<()> {
        let source = r#"
intent_version = "v1"
spec = 253
rotation_id = "obsolete"
gear = []
"#;
        let error = parse_sim_config(source).err().or_fail()?;

        verify_that!(error.unsupported_version_value(), some(eq("v1")))
    }

    #[gtest]
    fn malformed_toml_preserves_parse_operation_and_source() -> Result<()> {
        let error = parse_sim_config("[").err().or_fail()?;

        verify_that!(error.operation(), eq(IntentConfigOperation::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>)
        )
    }

    #[gtest]
    fn empty_toml_is_an_unsupported_version_without_a_source() -> Result<()> {
        let error = parse_sim_config("").err().or_fail()?;

        verify_that!(error.operation(), eq(IntentConfigOperation::Parse))?;
        verify_that!(error.unsupported_version_value(), some(eq("")))?;

        let kind = error.source().or_fail()?;

        verify_that!(kind.source(), none())
    }

    #[gtest]
    fn unicode_values_roundtrip_unchanged() -> Result<()> {
        let mut intent = SimConfigIntent::patchwerk(SpecId::BeastMastery, 300.0, "旋转-🦊");

        intent.settings.insert(
            "greeting".to_string(),
            toml::Value::String("Grüße 世界".to_string()),
        );

        let serialized = serialize_sim_config(&intent).or_fail()?;
        let parsed = parse_sim_config(&serialized).or_fail()?;

        verify_that!(parsed.rotation_id, eq("旋转-🦊"))?;

        verify_that!(
            parsed
                .settings
                .get("greeting")
                .and_then(toml::Value::as_str),
            some(eq("Grüße 世界"))
        )
    }

    #[gtest]
    fn unknown_intent_version_is_typed_error() -> Result<()> {
        let source = r#"intent_version = "v9""#;
        let error = parse_sim_config(source).err().or_fail()?;

        verify_that!(error.unsupported_version_value(), some(eq("v9")))
    }

    #[gtest]
    fn current_intent_rejects_zero_player_game_data_context() -> Result<()> {
        let mut intent = SimConfigIntent::patchwerk(SpecId::BeastMastery, 300.0, "rotation");

        intent.player_level = 0;
        let serialized = toml::to_string_pretty(&intent).or_fail()?;
        let error = parse_sim_config(&serialized).err().or_fail()?;

        verify_that!(error.invalid_player_level_value(), some(eq(0)))?;

        intent.player_level = 80;
        intent.player_expansion_id = 0;
        let serialized = toml::to_string_pretty(&intent).or_fail()?;
        let error = parse_sim_config(&serialized).err().or_fail()?;

        verify_that!(error.invalid_player_expansion_id_value(), some(eq(0)))
    }

    #[gtest]
    fn current_intent_rejects_obsolete_aggregate_settings() -> Result<()> {
        let mut intent = SimConfigIntent::patchwerk(SpecId::BeastMastery, 300.0, "rotation");

        intent.player_level = 90;
        intent.player_expansion_id = 11;
        intent
            .settings
            .insert("level".to_string(), toml::Value::Integer(70));
        intent
            .settings
            .insert("expansion_id".to_string(), toml::Value::Integer(10));

        verify_that!(
            serialize_sim_config(&intent),
            err(displays_as(contains_substring(
                "obsolete aggregate encounter setting \"level\""
            )))
        )
    }

    #[gtest]
    fn build_sim_config_nested_settings() -> Result<()> {
        let mut settings = BTreeMap::new();

        settings.insert("tags".to_string(), serde_json::json!(["a", "b"]));
        settings.insert("nested".to_string(), serde_json::json!({ "x": 1, "y": 2 }));

        let input = IntentInput {
            settings,
            ..patchwerk_input(253, "rot-nested")
        };

        let toml_str = build_sim_config(input).or_fail()?;

        verify_that!(
            toml_str,
            contains_substring("tags = [\n    \"a\",\n    \"b\",\n]")
        )?;
        verify_that!(toml_str, contains_substring("[settings.nested]"))?;
        verify_that!(toml_str, contains_substring("x = 1"))?;
        verify_that!(toml_str, contains_substring("y = 2"))?;

        Ok(())
    }

    #[gtest]
    fn test_all_specs_have_snake_case() -> Result<()> {
        use strum::IntoEnumIterator;

        for spec in SpecId::iter() {
            let snake = spec.toml_key().to_string();

            verify_that!(snake.as_bytes(), not(is_empty()))?;
            verify_that!(
                snake.chars().all(|c| c.is_ascii_lowercase() || c == '_'),
                eq(true)
            )?;
        }

        Ok(())
    }

    #[gtest]
    fn test_settings_serialization_is_deterministic() -> Result<()> {
        let encounter = serde_json::to_value(
            EncounterDefinition::patchwerk(300.0, MAX_PLAYER_LEVEL, CURRENT_EXPANSION_ID)
                .or_fail()?,
        )
        .or_fail()?;
        let input_a: IntentInput = serde_json::from_value(serde_json::json!({
            "spec_id": 253,
            "rotation_id": "rot-1",
            "player_level": MAX_PLAYER_LEVEL,
            "player_expansion_id": CURRENT_EXPANSION_ID,
            "encounter": encounter,
            "settings": {
                "zeta": true,
                "alpha": 1
            },
            "equipment": []
        }))
        .or_fail()?;

        let input_b: IntentInput = serde_json::from_value(serde_json::json!({
            "spec_id": 253,
            "rotation_id": "rot-1",
            "player_level": MAX_PLAYER_LEVEL,
            "player_expansion_id": CURRENT_EXPANSION_ID,
            "encounter": serde_json::to_value(
                EncounterDefinition::patchwerk(
                    300.0,
                    MAX_PLAYER_LEVEL,
                    CURRENT_EXPANSION_ID,
                )
                .or_fail()?,
            )
            .or_fail()?,
            "settings": {
                "alpha": 1,
                "zeta": true
            },
            "equipment": []
        }))
        .or_fail()?;

        let a = build_sim_config(input_a).or_fail()?;
        let b = build_sim_config(input_b).or_fail()?;

        verify_that!(a, eq(&b))?;

        Ok(())
    }
}