wowlab_engine_domain/rotation/

prepared.rs

// #t(file: rust_similar_structs) rotation preparation and its bound successor intentionally share immutable lowering inputs across the state-machine transition.
// #t(file: rust_too_many_lines_in_file) preparation owns the feature-gated cold dependency metadata pass beside its immutable output.
// #t(file: rust_inline_test_module_size) dependency grammar tests require private collector state that is intentionally absent from the public API.

//! Validated rotation source, prepared schema, and complete resolved references.

use std::sync::Arc;

#[cfg(feature = "rotation-optimizations")]
use action_dependencies::collect_action_dependencies;
use bitflags::bitflags;
use wowlab_types::{
    game::GearSlot,
    sim::{Condition, Rotation, RotationAction, SpellIdx},
};

#[cfg(feature = "rotation-optimizations")]
use super::condition::ResolvedFieldRead;
use super::{
    backend::RotationBackend,
    buffer::{BufferRequirements, DescriptorTable, EvalKind},
    condition::{ResolvedKey, resolve_field_read},
    context::ContextSchema,
    error::Result,
    lower,
    resolver::SpecResolver,
};

#[cfg(feature = "rotation-optimizations")]
mod action_dependencies {
    //! Mutation dependencies that can make a cast action selectable at a decision boundary.

    use wowlab_types::{
        combat::ResourceType,
        sim::{AuraIdx, AuraOn, CompareOp, Condition, Rotation, RotationAction, SpellIdx},
    };

    use super::{
        DescriptorTable, EvalKind, ResolvedFieldRead, ResolvedKey, Result, SpecResolver,
        resolve_field_read,
    };
    use crate::rotation::condition::domain;

    /// Runtime field whose mutation can make a prepared cast action selectable.
    #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
    #[non_exhaustive]
    pub enum PreparedRotationChangeKey {
        /// The ready state of one resolved spell cooldown.
        SpellCooldownReady(SpellIdx),
        /// One exact current-resource threshold observed by the rotation.
        ResourceThreshold {
            resource: ResourceType,
            value_bits: u64,
            strict: bool,
        },
        /// One exact spell-cooldown remaining-time threshold observed by the rotation.
        CooldownRemainingThreshold {
            spell: SpellIdx,
            seconds_bits: u64,
            strict: bool,
        },
        /// Aura presence or stack state observed by the rotation.
        AuraState,
        /// One exact current-target health-percent threshold observed by the rotation.
        TargetHealthThreshold { percent_bits: u64, strict: bool },
        /// One exact aura-remaining threshold observed by the rotation.
        AuraRemainingThreshold {
            aura: AuraIdx,
            on: AuraOn,
            seconds_bits: u64,
            strict: bool,
        },
        /// Target distance underlying spatial eligibility observed by the rotation.
        Spatial,
        /// Current encounter population observed by the rotation.
        EncounterPopulation,
        /// Spell lifecycle state observed by the rotation.
        SpellState,
        /// Persistent equipped-item state observed by the rotation.
        EquipmentState,
        /// Previous player-cast history observed by the rotation.
        HistoryState,
    }

    /// Mutation direction that can make a prepared cast action selectable.
    #[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
    #[non_exhaustive]
    pub enum PreparedRotationChangeDirection {
        /// The semantic value represented by the key rises.
        Rise,
        /// The semantic value represented by the key falls.
        Fall,
    }

    /// One directional mutation that can enable a prepared cast action.
    #[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
    pub struct PreparedRotationChange {
        key: PreparedRotationChangeKey,
        direction: PreparedRotationChangeDirection,
    }

    impl PreparedRotationChange {
        /// Runtime field whose mutation can enable the action.
        #[must_use]
        pub const fn key(self) -> PreparedRotationChangeKey {
            self.key
        }

        /// Enabling direction for the runtime field.
        #[must_use]
        pub const fn direction(self) -> PreparedRotationChangeDirection {
            self.direction
        }
    }

    /// Dependency plan for one reachable terminal cast action.
    #[derive(Clone, Debug, Eq, PartialEq)]
    pub struct PreparedActionDependencyPlan {
        spell: SpellIdx,
        changes: Box<[PreparedRotationChange]>,
        complete: bool,
    }

    impl PreparedActionDependencyPlan {
        /// Spell selected by this terminal cast action.
        #[must_use]
        pub const fn spell(&self) -> SpellIdx {
            self.spell
        }

        /// Directional mutations that can make this action selectable.
        #[must_use]
        pub fn changes(&self) -> &[PreparedRotationChange] {
            &self.changes
        }

        /// Whether the v1 dependency grammar describes every enabling mutation.
        #[must_use]
        pub const fn complete(&self) -> bool {
            self.complete
        }
    }

    pub(super) struct CollectedActionDependencies {
        pub(super) plans: Box<[PreparedActionDependencyPlan]>,
        pub(super) complete: bool,
    }

    pub(super) fn collect_action_dependencies(
        rotation: &Rotation,
        resolver: &SpecResolver,
        table: &DescriptorTable,
    ) -> Result<CollectedActionDependencies> {
        let mut collector = DependencyCollector {
            rotation,
            resolver,
            table,
            plans: Vec::new(),
            complete: true,
        };

        collector.collect_actions(&rotation.actions, true)?;
        collector.complete &= collector
            .plans
            .iter()
            .all(PreparedActionDependencyPlan::complete);

        Ok(CollectedActionDependencies {
            plans: collector.plans.into_boxed_slice(),
            complete: collector.complete,
        })
    }

    struct DependencyCollector<'a> {
        rotation: &'a Rotation,
        resolver: &'a SpecResolver,
        table: &'a DescriptorTable,
        plans: Vec<PreparedActionDependencyPlan>,
        complete: bool,
    }

    impl DependencyCollector<'_> {
        fn collect_actions(
            &mut self,
            actions: &[RotationAction],
            inherited_complete: bool,
        ) -> Result<()> {
            for action in actions.iter().filter(|action| action.enabled()) {
                match action {
                    RotationAction::Cast {
                        spell, condition, ..
                    } => self.collect_cast(spell, condition.as_ref(), inherited_complete)?,
                    RotationAction::Call {
                        list, condition, ..
                    } => {
                        let call_complete = inherited_complete && condition.is_none();

                        if condition.is_some() {
                            self.complete = false;
                        }

                        if let Some(actions) = self.rotation.lists.get(list) {
                            self.collect_actions(actions, call_complete)?;
                        }
                    }
                    RotationAction::Wait {
                        condition: None, ..
                    } => {}
                    RotationAction::Run { .. }
                    | RotationAction::SetVar { .. }
                    | RotationAction::ModifyVar { .. }
                    | RotationAction::Wait { .. }
                    | RotationAction::WaitUntil { .. }
                    | RotationAction::Pool { .. }
                    | RotationAction::UseTrinket { .. }
                    | RotationAction::UseItem { .. }
                    | _ => self.complete = false,
                }
            }

            Ok(())
        }

        fn collect_cast(
            &mut self,
            spell_name: &str,
            condition: Option<&Condition>,
            inherited_complete: bool,
        ) -> Result<()> {
            let spell = self.resolver.resolve_spell(spell_name)?;
            let mut analysis = match condition {
                Some(condition) => self.analyze_condition(condition, spell, true)?,
                None => ConditionAnalysis::complete(),
            };

            analysis.complete &= inherited_complete;
            analysis.changes.sort_unstable_by_key(change_sort_key);
            analysis.changes.dedup();
            self.plans.push(PreparedActionDependencyPlan {
                spell,
                changes: analysis.changes.into_boxed_slice(),
                complete: analysis.complete,
            });

            Ok(())
        }

        fn analyze_condition(
            &self,
            condition: &Condition,
            action_spell: SpellIdx,
            positive: bool,
        ) -> Result<ConditionAnalysis> {
            match condition {
                Condition::Read { field } => self.analyze_read(field, action_spell, positive),
                Condition::Bool { .. } | Condition::Int { .. } | Condition::Float { .. } => {
                    Ok(ConditionAnalysis::complete())
                }
                Condition::Var { name } => match self.rotation.variables.get(name) {
                    Some(value) => self.analyze_condition(value, action_spell, positive),
                    None => Ok(ConditionAnalysis::incomplete()),
                },
                Condition::Compare { op, left, right } => {
                    self.analyze_compare(*op, left, right, positive)
                }
                Condition::And { operands } | Condition::Or { operands } => {
                    let mut analysis = ConditionAnalysis::complete();

                    for operand in operands {
                        analysis.merge(self.analyze_condition(operand, action_spell, positive)?);
                    }

                    Ok(analysis)
                }
                Condition::Not { operand } => {
                    self.analyze_condition(operand, action_spell, !positive)
                }
                Condition::Arith { .. }
                | Condition::UnaryMath { .. }
                | Condition::MinMax { .. }
                | Condition::IfThenElse { .. }
                | _ => Ok(ConditionAnalysis::incomplete()),
            }
        }

        fn analyze_read(
            &self,
            field: &wowlab_types::sim::FieldRead,
            action_spell: SpellIdx,
            positive: bool,
        ) -> Result<ConditionAnalysis> {
            let resolved = resolve_field_read(field, self.table, self.resolver)?;
            let descriptor = self.table.get(resolved.descriptor_id);

            if let Some(change) = cooldown_read_change(field, resolved.key.as_ref(), positive) {
                return Ok(ConditionAnalysis::change(change));
            }

            if let Some(change) = semantic_direct_change(field, positive) {
                return Ok(ConditionAnalysis::change(change));
            }

            if let Some(analysis) = spell_read_analysis(
                field,
                resolved.key.as_ref(),
                action_spell,
                descriptor.map(|descriptor| descriptor.eval_kind),
                positive,
            ) {
                return Ok(analysis);
            }

            if let Some(analysis) = other_read_analysis(field, resolved.key.as_ref(), positive) {
                return Ok(analysis);
            }

            Ok(ConditionAnalysis::incomplete())
        }

        fn analyze_compare(
            &self,
            op: CompareOp,
            left: &Condition,
            right: &Condition,
            positive: bool,
        ) -> Result<ConditionAnalysis> {
            let left = self.classify_comparison_operand(left)?;
            let right = self.classify_comparison_operand(right)?;

            match (left, right) {
                (ComparisonOperand::Dynamic(dynamic), ComparisonOperand::Static(threshold)) => {
                    Ok(dynamic_comparison(dynamic, threshold, op, positive))
                }
                (ComparisonOperand::Static(threshold), ComparisonOperand::Dynamic(dynamic)) => {
                    Ok(match transform_compare(op, CompareTransform::Reverse) {
                        Some(reversed) => {
                            dynamic_comparison(dynamic, threshold, reversed, positive)
                        }
                        None => ConditionAnalysis::incomplete(),
                    })
                }
                (ComparisonOperand::Static(_), ComparisonOperand::Static(_)) => {
                    Ok(ConditionAnalysis::complete())
                }
                (ComparisonOperand::Dynamic(_), ComparisonOperand::Dynamic(_))
                | (ComparisonOperand::Unknown, _)
                | (_, ComparisonOperand::Unknown) => Ok(ConditionAnalysis::incomplete()),
            }
        }

        fn classify_comparison_operand(&self, condition: &Condition) -> Result<ComparisonOperand> {
            match condition {
                Condition::Bool { .. } => Ok(ComparisonOperand::Static(None)),
                Condition::Int { value } => Ok(ComparisonOperand::Static(Some(
                    wowlab_types::numeric::i64_to_f64(*value),
                ))),
                Condition::Float { value } => Ok(ComparisonOperand::Static(Some(*value))),
                Condition::Var { name } => match self.rotation.variables.get(name) {
                    Some(value) => self.classify_comparison_operand(value),
                    None => Ok(ComparisonOperand::Unknown),
                },
                Condition::Read { field } => self.classify_read_operand(field),
                _ => Ok(ComparisonOperand::Unknown),
            }
        }

        fn classify_read_operand(
            &self,
            field: &wowlab_types::sim::FieldRead,
        ) -> Result<ComparisonOperand> {
            let resolved = resolve_field_read(field, self.table, self.resolver)?;

            Ok(classify_resolved_read(field, &resolved))
        }
    }

    fn cooldown_read_change(
        field: &wowlab_types::sim::FieldRead,
        key: Option<&ResolvedKey>,
        positive: bool,
    ) -> Option<PreparedRotationChange> {
        let Some(ResolvedKey::Spell(spell)) = key else {
            return None;
        };

        (field.domain == domain::COOLDOWN && field.name == "is_ready").then_some(
            PreparedRotationChange {
                key: PreparedRotationChangeKey::SpellCooldownReady(*spell),
                direction: polarity_direction(positive),
            },
        )
    }

    fn spell_read_analysis(
        field: &wowlab_types::sim::FieldRead,
        key: Option<&ResolvedKey>,
        action_spell: SpellIdx,
        eval_kind: Option<EvalKind>,
        positive: bool,
    ) -> Option<ConditionAnalysis> {
        let Some(ResolvedKey::Spell(spell)) = key else {
            return None;
        };

        if eval_kind == Some(EvalKind::SpellUsable) && *spell == action_spell {
            return Some(ConditionAnalysis::complete());
        }

        let dependency = match (field.domain.as_str(), field.name.as_str()) {
            (domain::SPELL, "is_enabled") => PreparedRotationChangeKey::AuraState,
            (domain::SPELL, "is_channeling" | "is_in_flight") => {
                PreparedRotationChangeKey::SpellState
            }
            _ => return None,
        };

        Some(ConditionAnalysis::change(PreparedRotationChange {
            key: dependency,
            direction: polarity_direction(positive),
        }))
    }

    fn other_read_analysis(
        field: &wowlab_types::sim::FieldRead,
        key: Option<&ResolvedKey>,
        positive: bool,
    ) -> Option<ConditionAnalysis> {
        if field.domain == domain::WEAPON_IMBUE
            && matches!(field.name.as_str(), "is_active" | "is_inactive")
        {
            let active = field.name == "is_active";

            return Some(ConditionAnalysis::change(PreparedRotationChange {
                key: PreparedRotationChangeKey::EquipmentState,
                direction: polarity_direction(positive == active),
            }));
        }

        if field.domain == domain::HISTORY
            && matches!(field.name.as_str(), "prev_gcd" | "prev_off_gcd")
            && matches!(key, Some(ResolvedKey::Spell(_)))
        {
            return Some(ConditionAnalysis::change(PreparedRotationChange {
                key: PreparedRotationChangeKey::HistoryState,
                direction: polarity_direction(positive),
            }));
        }

        (field.domain == domain::PET && field.name == "is_active"
            || is_static_domain(&field.domain))
        .then(ConditionAnalysis::complete)
    }

    fn classify_resolved_read(
        field: &wowlab_types::sim::FieldRead,
        resolved: &ResolvedFieldRead,
    ) -> ComparisonOperand {
        if let Some(dynamic) = keyed_dynamic_operand(field, resolved.key.as_ref()) {
            return ComparisonOperand::dynamic(dynamic);
        }

        if let Some(dynamic) =
            semantic_comparison_operand(field, resolved.key.as_ref(), resolved.on)
        {
            return ComparisonOperand::Dynamic(dynamic);
        }

        if field.domain == domain::PET && field.name == "is_active"
            || is_static_domain(&field.domain)
        {
            return ComparisonOperand::Static(None);
        }

        ComparisonOperand::Unknown
    }

    fn keyed_dynamic_operand(
        field: &wowlab_types::sim::FieldRead,
        resolved_key: Option<&ResolvedKey>,
    ) -> Option<DynamicField> {
        match (field.domain.as_str(), field.name.as_str(), resolved_key?) {
            (domain::RESOURCE, "current", ResolvedKey::Resource(resource)) => {
                Some(DynamicField::Resource(*resource))
            }
            (domain::COOLDOWN, "charges", ResolvedKey::Spell(spell)) => Some(DynamicField::Change(
                PreparedRotationChangeKey::SpellCooldownReady(*spell),
            )),
            (domain::COOLDOWN, "remaining", ResolvedKey::Spell(spell)) => {
                Some(DynamicField::CooldownRemaining { spell: *spell })
            }
            _ => None,
        }
    }

    #[derive(Clone, Copy)]
    enum ComparisonOperand {
        Dynamic(DynamicComparisonOperand),
        Static(Option<f64>),
        Unknown,
    }

    impl ComparisonOperand {
        const fn dynamic(field: DynamicField) -> Self {
            Self::Dynamic(DynamicComparisonOperand {
                field,
                direction: FieldDirection::Normal,
            })
        }
    }

    #[derive(Clone, Copy)]
    struct DynamicComparisonOperand {
        field: DynamicField,
        direction: FieldDirection,
    }

    #[derive(Clone, Copy)]
    enum DynamicField {
        Change(PreparedRotationChangeKey),
        Resource(ResourceType),
        TargetHealth,
        AuraRemaining { aura: AuraIdx, on: AuraOn },
        CooldownRemaining { spell: SpellIdx },
    }

    #[derive(Clone, Copy)]
    enum FieldDirection {
        Normal,
        Inverted,
    }

    struct ConditionAnalysis {
        changes: Vec<PreparedRotationChange>,
        complete: bool,
    }

    impl ConditionAnalysis {
        const fn complete() -> Self {
            Self {
                changes: Vec::new(),
                complete: true,
            }
        }

        const fn incomplete() -> Self {
            Self {
                changes: Vec::new(),
                complete: false,
            }
        }

        fn change(change: PreparedRotationChange) -> Self {
            Self {
                changes: vec![change],
                complete: true,
            }
        }

        fn merge(&mut self, mut other: Self) {
            self.changes.append(&mut other.changes);
            self.complete &= other.complete;
        }
    }

    fn dynamic_comparison(
        dynamic: DynamicComparisonOperand,
        threshold: Option<f64>,
        op: CompareOp,
        positive: bool,
    ) -> ConditionAnalysis {
        let mut analysis = ConditionAnalysis::complete();
        let effective_op = if positive {
            Some(op)
        } else {
            transform_compare(op, CompareTransform::Negate)
        };
        let (observed_direction, strict) = match effective_op {
            Some(CompareOp::Gt) => (Some(PreparedRotationChangeDirection::Rise), true),
            Some(CompareOp::Gte) => (Some(PreparedRotationChangeDirection::Rise), false),
            Some(CompareOp::Lt) => (Some(PreparedRotationChangeDirection::Fall), true),
            Some(CompareOp::Lte) => (Some(PreparedRotationChangeDirection::Fall), false),
            Some(CompareOp::Eq) => (None, false),
            Some(CompareOp::Ne) => (None, true),
            _ => return ConditionAnalysis::incomplete(),
        };
        let Some(key) = dynamic_change_key(dynamic.field, threshold, strict) else {
            return ConditionAnalysis::incomplete();
        };
        let direction = observed_direction.map(|direction| match dynamic.direction {
            FieldDirection::Normal => direction,
            FieldDirection::Inverted => reverse_direction(direction),
        });

        match direction {
            Some(direction) => analysis
                .changes
                .push(PreparedRotationChange { key, direction }),
            None => analysis.changes.extend([
                PreparedRotationChange {
                    key,
                    direction: PreparedRotationChangeDirection::Rise,
                },
                PreparedRotationChange {
                    key,
                    direction: PreparedRotationChangeDirection::Fall,
                },
            ]),
        }

        analysis
    }

    fn dynamic_change_key(
        field: DynamicField,
        threshold: Option<f64>,
        strict: bool,
    ) -> Option<PreparedRotationChangeKey> {
        match field {
            DynamicField::Change(key) => Some(key),
            DynamicField::Resource(resource) => {
                threshold.map(|value| PreparedRotationChangeKey::ResourceThreshold {
                    resource,
                    value_bits: value.to_bits(),
                    strict,
                })
            }
            DynamicField::TargetHealth => {
                threshold.map(|percent| PreparedRotationChangeKey::TargetHealthThreshold {
                    percent_bits: percent.to_bits(),
                    strict,
                })
            }
            DynamicField::AuraRemaining { aura, on } => {
                threshold.map(
                    |seconds| PreparedRotationChangeKey::AuraRemainingThreshold {
                        aura,
                        on,
                        seconds_bits: seconds.to_bits(),
                        strict,
                    },
                )
            }
            DynamicField::CooldownRemaining { spell } => {
                threshold.map(
                    |seconds| PreparedRotationChangeKey::CooldownRemainingThreshold {
                        spell,
                        seconds_bits: seconds.to_bits(),
                        strict,
                    },
                )
            }
        }
    }

    fn semantic_comparison_operand(
        field: &wowlab_types::sim::FieldRead,
        resolved_key: Option<&ResolvedKey>,
        resolved_on: Option<AuraOn>,
    ) -> Option<DynamicComparisonOperand> {
        let (field, direction) = match (field.domain.as_str(), field.name.as_str()) {
            (domain::AURA, "is_active" | "stacks") => (
                DynamicField::Change(PreparedRotationChangeKey::AuraState),
                FieldDirection::Normal,
            ),
            (domain::AURA, "is_inactive") => (
                DynamicField::Change(PreparedRotationChangeKey::AuraState),
                FieldDirection::Inverted,
            ),
            (domain::AURA, "remaining") => {
                let ResolvedKey::Aura(aura) = resolved_key? else {
                    return None;
                };

                (
                    DynamicField::AuraRemaining {
                        aura: *aura,
                        on: resolved_on.unwrap_or(AuraOn::Player),
                    },
                    FieldDirection::Normal,
                )
            }
            (domain::SPELL, "is_in_range") => (
                DynamicField::Change(PreparedRotationChangeKey::Spatial),
                FieldDirection::Inverted,
            ),
            (domain::UNIT, "distance") => (
                DynamicField::Change(PreparedRotationChangeKey::Spatial),
                FieldDirection::Normal,
            ),
            (domain::UNIT, "health_pct") => (DynamicField::TargetHealth, FieldDirection::Normal),
            (domain::COMBAT, "enemy_count") => (
                DynamicField::Change(PreparedRotationChangeKey::EncounterPopulation),
                FieldDirection::Normal,
            ),
            (domain::SPELL, "in_flight_count" | "last_used") => (
                DynamicField::Change(PreparedRotationChangeKey::SpellState),
                FieldDirection::Normal,
            ),
            (domain::WEAPON_IMBUE, "is_active") => (
                DynamicField::Change(PreparedRotationChangeKey::EquipmentState),
                FieldDirection::Normal,
            ),
            (domain::WEAPON_IMBUE, "is_inactive") => (
                DynamicField::Change(PreparedRotationChangeKey::EquipmentState),
                FieldDirection::Inverted,
            ),
            _ => return None,
        };

        Some(DynamicComparisonOperand { field, direction })
    }

    fn semantic_direct_change(
        field: &wowlab_types::sim::FieldRead,
        positive: bool,
    ) -> Option<PreparedRotationChange> {
        let (key, positive) = match (field.domain.as_str(), field.name.as_str()) {
            (domain::AURA, "is_active") => (PreparedRotationChangeKey::AuraState, positive),
            (domain::AURA, "is_inactive") => (PreparedRotationChangeKey::AuraState, !positive),
            (domain::SPELL, "is_in_range") => (PreparedRotationChangeKey::Spatial, !positive),
            _ => return None,
        };

        Some(PreparedRotationChange {
            key,
            direction: polarity_direction(positive),
        })
    }

    const fn polarity_direction(positive: bool) -> PreparedRotationChangeDirection {
        if positive {
            PreparedRotationChangeDirection::Rise
        } else {
            PreparedRotationChangeDirection::Fall
        }
    }

    const fn reverse_direction(
        direction: PreparedRotationChangeDirection,
    ) -> PreparedRotationChangeDirection {
        match direction {
            PreparedRotationChangeDirection::Rise => PreparedRotationChangeDirection::Fall,
            PreparedRotationChangeDirection::Fall => PreparedRotationChangeDirection::Rise,
        }
    }

    #[derive(Clone, Copy)]
    enum CompareTransform {
        Negate,
        Reverse,
    }

    const fn transform_compare(op: CompareOp, transform: CompareTransform) -> Option<CompareOp> {
        match transform {
            CompareTransform::Negate => match op {
                CompareOp::Gt => Some(CompareOp::Lte),
                CompareOp::Gte => Some(CompareOp::Lt),
                CompareOp::Lt => Some(CompareOp::Gte),
                CompareOp::Lte => Some(CompareOp::Gt),
                CompareOp::Eq => Some(CompareOp::Ne),
                CompareOp::Ne => Some(CompareOp::Eq),
                _ => None,
            },
            CompareTransform::Reverse => match op {
                CompareOp::Gt => Some(CompareOp::Lt),
                CompareOp::Gte => Some(CompareOp::Lte),
                CompareOp::Lt => Some(CompareOp::Gt),
                CompareOp::Lte => Some(CompareOp::Gte),
                CompareOp::Eq => Some(CompareOp::Eq),
                CompareOp::Ne => Some(CompareOp::Ne),
                _ => None,
            },
        }
    }

    fn is_static_domain(domain_name: &str) -> bool {
        matches!(
            domain_name,
            domain::TALENT | domain::HERO_TREE | domain::EQUIPMENT | domain::SET_BONUS
        )
    }

    // #t(fn: rust_magic_numbers) tuple ordinals define the stable public dependency ordering.
    fn change_sort_key(
        change: &PreparedRotationChange,
    ) -> (u8, u64, u64, PreparedRotationChangeDirection) {
        let (kind, identity, threshold) = match change.key {
            PreparedRotationChangeKey::SpellCooldownReady(spell) => (0, u64::from(spell.0), 0),
            PreparedRotationChangeKey::ResourceThreshold {
                resource,
                value_bits,
                strict,
            } => (
                1,
                (u64::from(u8::from(resource)) << 1) | u64::from(strict),
                value_bits,
            ),
            PreparedRotationChangeKey::CooldownRemainingThreshold {
                spell,
                seconds_bits,
                strict,
            } => (
                2,
                (u64::from(spell.0) << 1) | u64::from(strict),
                seconds_bits,
            ),
            PreparedRotationChangeKey::AuraState => (3, 0, 0),
            PreparedRotationChangeKey::TargetHealthThreshold {
                percent_bits,
                strict,
            } => (4, u64::from(strict), percent_bits),
            PreparedRotationChangeKey::AuraRemainingThreshold {
                aura,
                on,
                seconds_bits,
                strict,
            } => (
                5,
                (u64::from(aura.0) << (u8::BITS + 1))
                    | (u64::from(aura_on_rank(on)) << 1)
                    | u64::from(strict),
                seconds_bits,
            ),
            PreparedRotationChangeKey::Spatial => (6, 0, 0),
            PreparedRotationChangeKey::EncounterPopulation => (7, 0, 0),
            PreparedRotationChangeKey::SpellState => (8, 0, 0),
            PreparedRotationChangeKey::EquipmentState => (9, 0, 0),
            PreparedRotationChangeKey::HistoryState => (10, 0, 0),
        };

        (kind, identity, threshold, change.direction)
    }

    const PET_AURA_RANK: u8 = 2;

    const fn aura_on_rank(on: AuraOn) -> u8 {
        match on {
            AuraOn::Player => 0,
            AuraOn::Target => 1,
            AuraOn::Pet => PET_AURA_RANK,
        }
    }

    #[cfg(test)]
    mod tests {
        use googletest::{Result as GtestResult, prelude::*};

        use super::*;
        use crate::rotation::{RotationPreparation, parse_and_validate};

        fn preparation(json: &str) -> RotationPreparation {
            let rotation = parse_and_validate(json).expect("parse dependency fixture");
            let resolver = SpecResolver::new("dependencies")
                .spell("primary", 10)
                .spell("secondary", 20)
                .spell("foreign", 30)
                .aura("known_aura", 40)
                .talent("known_talent", true);

            RotationPreparation::prepare(&rotation, &resolver).expect("prepare dependency fixture")
        }

        fn expected(
            key: PreparedRotationChangeKey,
            direction: PreparedRotationChangeDirection,
        ) -> PreparedRotationChange {
            PreparedRotationChange { key, direction }
        }

        #[gtest]
        fn cooldown_polarity_maps_to_rise_and_fall_in_source_order() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"polarity","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"read","domain":"cooldown","key":"primary","name":"is_ready"}},{"type":"cast","spell":"secondary","condition":{"type":"not","operand":{"type":"read","domain":"cooldown","key":"secondary","name":"is_ready"}}}],"lists":{}}"#,
            );
            let plans = prepared.action_dependency_plans();

            verify_that!(plans[0].spell(), eq(SpellIdx(10)))?;
            verify_that!(
                plans[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::SpellCooldownReady(SpellIdx(10)),
                    PreparedRotationChangeDirection::Rise
                ))]
            )?;
            verify_that!(plans[1].spell(), eq(SpellIdx(20)))?;
            verify_that!(
                plans[1].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::SpellCooldownReady(SpellIdx(20)),
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn cooldown_charge_threshold_subscribes_to_the_exact_spell() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"charges","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"gte","left":{"type":"read","domain":"cooldown","key":"primary","name":"charges"},"right":{"type":"int","value":2}}}],"lists":{}}"#,
            );
            let plan = &prepared.action_dependency_plans()[0];

            verify_that!(
                plan.changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::SpellCooldownReady(SpellIdx(10)),
                    PreparedRotationChangeDirection::Rise
                ))]
            )?;

            verify_true!(plan.complete())
        }

        #[gtest]
        fn cooldown_remaining_threshold_tracks_time_falling_below_value() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"remaining","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"lte","left":{"type":"read","domain":"cooldown","key":"secondary","name":"remaining"},"right":{"type":"float","value":5.0}}}],"lists":{}}"#,
            );
            let plan = &prepared.action_dependency_plans()[0];

            verify_that!(
                plan.changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::CooldownRemainingThreshold {
                        spell: SpellIdx(20),
                        seconds_bits: 5.0_f64.to_bits(),
                        strict: false,
                    },
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;

            verify_true!(plan.complete())
        }

        #[gtest]
        fn recursive_combo_point_threshold_is_enabled_by_a_fall() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"resource","variables":{"points":{"type":"read","domain":"resource","key":"combo_points","name":"current"}},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"lte","left":{"type":"var","name":"points"},"right":{"type":"int","value":3}}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans()[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::ResourceThreshold {
                        resource: ResourceType::ComboPoints,
                        value_bits: 3.0_f64.to_bits(),
                        strict: false,
                    },
                    PreparedRotationChangeDirection::Fall
                ))]
            )
        }

        #[gtest]
        fn reversed_resource_comparison_reverses_direction() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"reversed","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"lt","left":{"type":"int","value":3},"right":{"type":"read","domain":"resource","key":"combo_points","name":"current"}}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans()[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::ResourceThreshold {
                        resource: ResourceType::ComboPoints,
                        value_bits: 3.0_f64.to_bits(),
                        strict: true,
                    },
                    PreparedRotationChangeDirection::Rise
                ))]
            )
        }

        #[gtest]
        fn static_reads_and_own_usability_add_no_changes() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"static","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"and","operands":[{"type":"read","domain":"talent","key":"known_talent","name":"is_enabled"},{"type":"read","domain":"hero_tree","key":"tree","name":"is_active"},{"type":"read","domain":"equipment","key":"item","name":"is_equipped"},{"type":"read","domain":"set_bonus","key":"set","name":"is_active"},{"type":"read","domain":"spell","key":"primary","name":"is_usable"}]}}],"lists":{}}"#,
            );

            verify_that!(prepared.action_dependency_plans()[0].changes(), is_empty())?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn direct_semantic_state_reads_preserve_enabling_polarity() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"semantic_reads","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"read","domain":"aura","key":"known_aura","name":"is_active"}},{"type":"cast","spell":"secondary","condition":{"type":"read","domain":"aura","key":"known_aura","name":"is_inactive"}},{"type":"cast","spell":"foreign","condition":{"type":"read","domain":"spell","key":"primary","name":"is_in_range"}},{"type":"cast","spell":"primary","condition":{"type":"not","operand":{"type":"read","domain":"pet","name":"is_active"}}}],"lists":{}}"#,
            );
            let plans = prepared.action_dependency_plans();

            verify_that!(
                plans[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::AuraState,
                    PreparedRotationChangeDirection::Rise
                ))]
            )?;
            verify_that!(
                plans[1].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::AuraState,
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;
            verify_that!(
                plans[2].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::Spatial,
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;
            verify_that!(plans[3].changes(), is_empty())?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn semantic_thresholds_cover_aura_health_spatial_and_population_changes() -> GtestResult<()>
        {
            let prepared = preparation(
                r#"{"version":1,"name":"semantic_thresholds","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"and","operands":[{"type":"compare","op":"gte","left":{"type":"read","domain":"aura","key":"known_aura","name":"stacks"},"right":{"type":"int","value":3}},{"type":"compare","op":"lte","left":{"type":"read","domain":"unit","key":"target","name":"health_pct"},"right":{"type":"int","value":20}},{"type":"compare","op":"lte","left":{"type":"read","domain":"unit","key":"target","name":"distance"},"right":{"type":"int","value":8}},{"type":"compare","op":"gte","left":{"type":"read","domain":"combat","name":"enemy_count"},"right":{"type":"int","value":3}}]}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans()[0].changes(),
                elements_are![
                    eq(&expected(
                        PreparedRotationChangeKey::AuraState,
                        PreparedRotationChangeDirection::Rise
                    )),
                    eq(&expected(
                        PreparedRotationChangeKey::TargetHealthThreshold {
                            percent_bits: 20.0_f64.to_bits(),
                            strict: false,
                        },
                        PreparedRotationChangeDirection::Fall
                    )),
                    eq(&expected(
                        PreparedRotationChangeKey::Spatial,
                        PreparedRotationChangeDirection::Fall
                    )),
                    eq(&expected(
                        PreparedRotationChangeKey::EncounterPopulation,
                        PreparedRotationChangeDirection::Rise
                    )),
                ]
            )?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn aura_presence_comparisons_map_active_and_inactive_to_presence_direction()
        -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"aura_presence","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"gt","left":{"type":"read","domain":"aura","key":"known_aura","name":"is_active"},"right":{"type":"float","value":0.0}}},{"type":"cast","spell":"secondary","condition":{"type":"compare","op":"gt","left":{"type":"read","domain":"aura","key":"known_aura","name":"is_inactive"},"right":{"type":"float","value":0.0}}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans()[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::AuraState,
                    PreparedRotationChangeDirection::Rise
                ))]
            )?;
            verify_that!(
                prepared.action_dependency_plans()[1].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::AuraState,
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn aura_remaining_preserves_its_exact_time_threshold() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"time_dependent","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"lte","left":{"type":"read","domain":"aura","key":"known_aura","name":"remaining"},"right":{"type":"float","value":2.0}}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans()[0].changes(),
                elements_are![eq(&expected(
                    PreparedRotationChangeKey::AuraRemainingThreshold {
                        aura: AuraIdx(40),
                        on: AuraOn::Player,
                        seconds_bits: 2.0_f64.to_bits(),
                        strict: false,
                    },
                    PreparedRotationChangeDirection::Fall
                ))]
            )?;

            verify_that!(prepared.action_dependencies_complete(), is_true())
        }

        #[gtest]
        fn arithmetic_and_foreign_usability_are_incomplete() -> GtestResult<()> {
            let prepared = preparation(
                r#"{"version":1,"name":"unknown","variables":{},"actions":[{"type":"cast","spell":"primary","condition":{"type":"compare","op":"gt","left":{"type":"arith","op":"add","left":{"type":"read","domain":"resource","key":"energy","name":"current"},"right":{"type":"int","value":1}},"right":{"type":"int","value":50}}},{"type":"cast","spell":"secondary","condition":{"type":"read","domain":"spell","key":"foreign","name":"is_usable"}}],"lists":{}}"#,
            );

            verify_that!(
                prepared.action_dependency_plans(),
                each(matches_pattern!(PreparedActionDependencyPlan {
                    complete: is_false(),
                    ..
                }))
            )?;

            verify_that!(prepared.action_dependencies_complete(), is_false())
        }

        #[gtest]
        fn conditioned_run_marks_rotation_incomplete() {
            let prepared = preparation(
                r#"{"version":1,"name":"run","variables":{},"actions":[{"type":"run","list":"nested","condition":{"type":"bool","value":true}},{"type":"cast","spell":"primary"}],"lists":{"nested":[{"type":"cast","spell":"secondary"}]}}"#,
            );

            expect_that!(prepared.action_dependency_plans(), len(eq(1)));
            expect_that!(prepared.action_dependencies_complete(), is_false());
        }
    }
}

#[cfg(feature = "rotation-optimizations")]
pub use action_dependencies::{
    PreparedActionDependencyPlan, PreparedRotationChange, PreparedRotationChangeDirection,
    PreparedRotationChangeKey,
};

bitflags! {
    /// How one resolved spell identity is consumed by the authored rotation.
    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
    pub struct SpellReferenceUsage: u8 {
        /// The spell is selected by an enabled cast action.
        const CAST = 1 << 0;
        /// An authored condition reads a field keyed by the spell.
        const FIELD_READ = 1 << 1;
        /// The spell participates in cast availability or an explicit usability/enabled read.
        const AVAILABILITY = 1 << 2;
    }
}

bitflags! {
    /// Target-dependent spell-slot fields observed by one resolved spell reference.
    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
    pub struct SpellProjectionUsage: u8 {
        /// Effective range or current in-range state is read.
        const RANGE = 1 << 0;
        /// Target-distance-derived travel time is read.
        const TRAVEL = 1 << 1;
    }
}

/// One resolved spell identity and all of its authored uses.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct ResolvedSpellReference {
    spell: SpellIdx,
    usage: SpellReferenceUsage,
    projection_usage: SpellProjectionUsage,
}

impl ResolvedSpellReference {
    #[must_use]
    pub const fn spell(self) -> SpellIdx {
        self.spell
    }

    #[must_use]
    pub const fn usage(self) -> SpellReferenceUsage {
        self.usage
    }

    #[must_use]
    pub const fn projection_usage(self) -> SpellProjectionUsage {
        self.projection_usage
    }
}

/// Layout-free validated rotation preparation that cannot be emitted.
///
/// Backend emission accepts only [`PreparedRotation`].
/// Binding this artifact to the complete finalized buffer requirements produces it.
#[derive(Debug)]
pub struct RotationPreparation {
    rotation: Rotation,
    resolver: SpecResolver,
    table: DescriptorTable,
    spell_references: Box<[ResolvedSpellReference]>,
    item_use_slots: Box<[GearSlot]>,
    lazy_cast_validation_safe: bool,
    #[cfg(feature = "rotation-optimizations")]
    action_dependency_plans: Box<[PreparedActionDependencyPlan]>,
    #[cfg(feature = "rotation-optimizations")]
    action_dependencies_complete: bool,
}

/// Canonical lowering input shared by portable bytecode, JIT, and explicit trace evaluation.
#[derive(Debug)]
pub struct PreparedRotation {
    rotation: Rotation,
    resolver: SpecResolver,
    schema: Arc<ContextSchema>,
    table: DescriptorTable,
    spell_references: Box<[ResolvedSpellReference]>,
    item_use_slots: Box<[GearSlot]>,
    lazy_cast_validation_safe: bool,
    spell_usability_prevalidated: bool,
    #[cfg(feature = "rotation-optimizations")]
    action_dependency_plans: Box<[PreparedActionDependencyPlan]>,
    #[cfg(feature = "rotation-optimizations")]
    action_dependencies_complete: bool,
}

impl PreparedRotation {
    #[must_use]
    pub fn schema(&self) -> &Arc<ContextSchema> {
        &self.schema
    }

    #[must_use]
    pub fn spell_references(&self) -> &[ResolvedSpellReference] {
        &self.spell_references
    }

    /// Enabled equipment actions authored by the rotation.
    #[must_use]
    pub fn item_use_slots(&self) -> &[GearSlot] {
        &self.item_use_slots
    }

    /// Whether cast availability may be validated only when that cast is selected.
    #[must_use]
    pub const fn lazy_cast_validation_safe(&self) -> bool {
        self.lazy_cast_validation_safe
    }

    /// Dependency plans for reachable terminal cast actions in source order.
    #[cfg(feature = "rotation-optimizations")]
    #[must_use]
    pub fn action_dependency_plans(&self) -> &[PreparedActionDependencyPlan] {
        &self.action_dependency_plans
    }

    /// Whether dependency plans cover every reachable decision behavior.
    #[cfg(feature = "rotation-optimizations")]
    #[must_use]
    pub const fn action_dependencies_complete(&self) -> bool {
        self.action_dependencies_complete
    }

    /// Use the externally maintained eligibility bit for `spell.is_usable` reads.
    ///
    /// The caller must fully validate every availability binding before evaluation.
    /// Alternatively, it must validate selected casts and retry with rejected slots disabled.
    #[cfg(feature = "rotation-optimizations")]
    #[must_use]
    pub fn with_prevalidated_spell_usability(mut self) -> Self {
        self.spell_usability_prevalidated = true;

        self
    }

    pub(super) fn lower<B>(&self, backend: &mut B)
    where
        B: RotationBackend,
    {
        lower::lower_rotation(
            backend,
            &self.rotation,
            &self.schema,
            &self.resolver,
            &self.table,
            self.spell_usability_prevalidated,
        );
    }

    pub(super) const fn rotation(&self) -> &Rotation {
        &self.rotation
    }

    pub(super) const fn resolver(&self) -> &SpecResolver {
        &self.resolver
    }

    pub(super) const fn table(&self) -> &DescriptorTable {
        &self.table
    }
}

impl RotationPreparation {
    /// Validate and resolve one canonical rotation without freezing a buffer layout.
    ///
    /// # Errors
    /// Returns an error for invalid structure or unresolved semantic identities.
    pub fn prepare(rotation: &Rotation, resolver: &SpecResolver) -> Result<Self> {
        if !rotation.is_empty() {
            super::ast::validate(rotation)?;
        }

        let table = DescriptorTable::build();
        let spell_references = collect_spell_references(rotation, resolver, &table)?;
        let item_use_slots = collect_item_use_slots(rotation);
        let lazy_cast_validation_safe = lazy_cast_validation_safe(rotation, resolver, &table)?;
        #[cfg(feature = "rotation-optimizations")]
        let action_dependencies = collect_action_dependencies(rotation, resolver, &table)?;

        Ok(Self {
            rotation: rotation.clone(),
            resolver: resolver.clone(),
            table,
            spell_references,
            item_use_slots,
            lazy_cast_validation_safe,
            #[cfg(feature = "rotation-optimizations")]
            action_dependency_plans: action_dependencies.plans,
            #[cfg(feature = "rotation-optimizations")]
            action_dependencies_complete: action_dependencies.complete,
        })
    }

    /// Complete referenced-spell inventory available before layout freeze.
    #[must_use]
    pub fn spell_references(&self) -> &[ResolvedSpellReference] {
        &self.spell_references
    }

    /// Dependency plans for reachable terminal cast actions in source order.
    #[cfg(feature = "rotation-optimizations")]
    #[must_use]
    pub fn action_dependency_plans(&self) -> &[PreparedActionDependencyPlan] {
        &self.action_dependency_plans
    }

    /// Whether dependency plans cover every reachable decision behavior.
    #[cfg(feature = "rotation-optimizations")]
    #[must_use]
    pub const fn action_dependencies_complete(&self) -> bool {
        self.action_dependencies_complete
    }

    /// Freeze one complete buffer layout and produce the sole backend-lowering input.
    ///
    /// # Errors
    /// Returns an error for invalid resources, fields, or buffer coordinates.
    pub fn bind(self, requirements: &BufferRequirements) -> Result<PreparedRotation> {
        let schema = lower::prepare(&self.rotation, &self.resolver, &self.table, requirements)?;

        schema.validate(&self.table)?;

        Ok(PreparedRotation {
            rotation: self.rotation,
            resolver: self.resolver,
            schema: Arc::new(schema),
            table: self.table,
            spell_references: self.spell_references,
            item_use_slots: self.item_use_slots,
            lazy_cast_validation_safe: self.lazy_cast_validation_safe,
            spell_usability_prevalidated: false,
            #[cfg(feature = "rotation-optimizations")]
            action_dependency_plans: self.action_dependency_plans,
            #[cfg(feature = "rotation-optimizations")]
            action_dependencies_complete: self.action_dependencies_complete,
        })
    }
}

fn collect_item_use_slots(rotation: &Rotation) -> Box<[GearSlot]> {
    let mut slots = Vec::new();

    for actions in std::iter::once(rotation.actions.as_slice())
        .chain(rotation.lists.values().map(Vec::as_slice))
    {
        for action in actions.iter().filter(|action| action.enabled()) {
            let slot = match action {
                RotationAction::UseTrinket { slot, .. } => GearSlot::trinket_from_index(*slot),
                RotationAction::UseItem { name, .. } => GearSlot::from_slug(name),
                _ => None,
            };

            if let Some(slot) = slot {
                slots.push(slot);
            }
        }
    }

    // #t(rust_lossy_cast) `GearSlot` is `repr(u8)`; this ordering conversion is exact.
    slots.sort_unstable_by_key(|slot| *slot as u8);
    slots.dedup();

    slots.into_boxed_slice()
}

// #t(fn: rust_cyclomatic_complexity) cold validation deliberately enumerates every action shape whose availability reads affect retry semantics.
fn lazy_cast_validation_safe(
    rotation: &Rotation,
    resolver: &SpecResolver,
    table: &DescriptorTable,
) -> Result<bool> {
    for condition in rotation.variables.values() {
        if condition_contains_availability(condition, resolver, table)? {
            return Ok(false);
        }
    }

    for actions in std::iter::once(rotation.actions.as_slice())
        .chain(rotation.lists.values().map(Vec::as_slice))
    {
        for action in actions.iter().filter(|action| action.enabled()) {
            match action {
                RotationAction::Cast {
                    spell,
                    condition,
                    target_if,
                    ..
                } => {
                    let own_spell = resolver.resolve_spell(spell)?;

                    if let Some(condition) = condition
                        && !condition_availability_is_positive_for_spell(
                            condition, own_spell, resolver, table,
                        )?
                    {
                        return Ok(false);
                    }

                    if let Some(target) = target_if
                        && condition_contains_availability(&target.expr, resolver, table)?
                    {
                        return Ok(false);
                    }
                }
                RotationAction::SetVar { .. } | RotationAction::ModifyVar { .. } => {
                    return Ok(false);
                }
                _ => {
                    for condition in action.conditions() {
                        if condition_contains_availability(condition, resolver, table)? {
                            return Ok(false);
                        }
                    }
                }
            }
        }
    }

    Ok(true)
}

fn condition_availability_is_positive_for_spell(
    condition: &Condition,
    own_spell: SpellIdx,
    resolver: &SpecResolver,
    table: &DescriptorTable,
) -> Result<bool> {
    let mut pending = vec![condition];

    while let Some(condition) = pending.pop() {
        match condition {
            Condition::Read { field } => {
                let resolved_read = resolve_field_read(field, table, resolver)?;
                let descriptor = table.get(resolved_read.descriptor_id).ok_or_else(|| {
                    super::error::Error::validation("resolved spell field has no descriptor")
                })?;

                if field_is_availability(field, descriptor.eval_kind)
                    && resolved_read.key != Some(ResolvedKey::Spell(own_spell))
                {
                    return Ok(false);
                }
            }
            Condition::And { operands } | Condition::Or { operands } => {
                pending.extend(operands);
            }
            _ if condition_contains_availability(condition, resolver, table)? => {
                return Ok(false);
            }
            _ => {}
        }
    }

    Ok(true)
}

fn condition_contains_availability(
    condition: &Condition,
    resolver: &SpecResolver,
    table: &DescriptorTable,
) -> Result<bool> {
    for field in condition.field_reads() {
        let resolved_read = resolve_field_read(field, table, resolver)?;
        let descriptor = table.get(resolved_read.descriptor_id).ok_or_else(|| {
            super::error::Error::validation("resolved spell field has no descriptor")
        })?;

        if field_is_availability(field, descriptor.eval_kind) {
            return Ok(true);
        }
    }

    Ok(false)
}

// #t(fn: rust_const_fn_candidate) equality for owned field-name strings is not const-compatible
fn field_is_availability(field: &wowlab_types::sim::FieldRead, eval_kind: EvalKind) -> bool {
    eval_kind == EvalKind::SpellUsable
        || (field.domain == super::condition::domain::SPELL && field.name == "is_enabled")
}

fn collect_spell_references(
    rotation: &Rotation,
    resolver: &SpecResolver,
    table: &DescriptorTable,
) -> Result<Box<[ResolvedSpellReference]>> {
    let mut references = Vec::new();

    for condition in rotation.variables.values() {
        collect_condition_references(condition, resolver, table, &mut references)?;
    }

    collect_action_references(&rotation.actions, resolver, table, &mut references)?;

    for actions in rotation.lists.values() {
        collect_action_references(actions, resolver, table, &mut references)?;
    }

    references.sort_unstable_by_key(|reference| reference.spell.0);

    Ok(references.into_boxed_slice())
}

fn collect_action_references(
    actions: &[RotationAction],
    resolver: &SpecResolver,
    table: &DescriptorTable,
    references: &mut Vec<ResolvedSpellReference>,
) -> Result<()> {
    for action in actions.iter().filter(|action| action.enabled()) {
        if let RotationAction::Cast { spell, .. } = action {
            merge_reference(
                references,
                resolver.resolve_spell(spell)?,
                SpellReferenceUsage::CAST | SpellReferenceUsage::AVAILABILITY,
                SpellProjectionUsage::empty(),
            );
        }

        for condition in action.conditions() {
            collect_condition_references(condition, resolver, table, references)?;
        }
    }

    Ok(())
}

fn collect_condition_references(
    condition: &Condition,
    resolver: &SpecResolver,
    table: &DescriptorTable,
    references: &mut Vec<ResolvedSpellReference>,
) -> Result<()> {
    for field in condition.field_reads() {
        let resolved_read = resolve_field_read(field, table, resolver)?;

        let Some(ResolvedKey::Spell(spell)) = resolved_read.key else {
            continue;
        };
        let descriptor = table.get(resolved_read.descriptor_id).ok_or_else(|| {
            super::error::Error::validation("resolved spell field has no descriptor")
        })?;
        let mut usage = SpellReferenceUsage::FIELD_READ;
        let mut spell_projection_usage = SpellProjectionUsage::empty();

        if descriptor.eval_kind == EvalKind::SpellUsable
            || (field.domain == super::condition::domain::SPELL && field.name == "is_enabled")
        {
            usage |= SpellReferenceUsage::AVAILABILITY;
        }

        match field.name.as_str() {
            "range" | "is_in_range" => spell_projection_usage |= SpellProjectionUsage::RANGE,
            "travel_time" => spell_projection_usage |= SpellProjectionUsage::TRAVEL,
            _ => {}
        }

        if descriptor.eval_kind == EvalKind::SpellUsable {
            spell_projection_usage |= SpellProjectionUsage::RANGE;
        }

        merge_reference(references, spell, usage, spell_projection_usage);
    }

    Ok(())
}

fn merge_reference(
    references: &mut Vec<ResolvedSpellReference>,
    spell: SpellIdx,
    usage: SpellReferenceUsage,
    projection_usage: SpellProjectionUsage,
) {
    if let Some(reference) = references
        .iter_mut()
        .find(|reference| reference.spell == spell)
    {
        reference.usage |= usage;
        reference.projection_usage |= projection_usage;
    } else {
        references.push(ResolvedSpellReference {
            spell,
            usage,
            projection_usage,
        });
    }
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;

    use super::*;
    use crate::rotation::parse_and_validate;

    fn prepared_rotation(json: &str) -> PreparedRotation {
        let rotation = parse_and_validate(json).expect("parse lazy-validation fixture");
        let resolver = SpecResolver::new("lazy-validation")
            .spell("primary", 20)
            .spell("secondary", 10);

        RotationPreparation::prepare(&rotation, &resolver)
            .expect("prepare lazy-validation fixture")
            .bind(&BufferRequirements::new())
            .expect("bind lazy-validation fixture")
    }

    #[gtest]
    fn own_spell_availability_in_positive_boolean_positions_is_lazy_safe() {
        let prepared = prepared_rotation(
            r#"{
                "version":1,
                "name":"lazy-positive-own-spell",
                "variables":{},
                "actions":[{
                    "type":"cast",
                    "spell":"primary",
                    "condition":{
                        "type":"and",
                        "operands":[
                            {"type":"read","domain":"spell","key":"primary","name":"is_enabled"},
                            {"type":"read","domain":"spell","key":"primary","name":"is_usable"}
                        ]
                    }
                }],
                "lists":{}
            }"#,
        );

        expect_that!(prepared.lazy_cast_validation_safe(), is_true());
    }

    #[gtest]
    fn cross_spell_availability_read_disables_lazy_validation() {
        let prepared = prepared_rotation(
            r#"{
                "version":1,
                "name":"lazy-cross-spell",
                "variables":{},
                "actions":[{
                    "type":"cast",
                    "spell":"primary",
                    "condition":{"type":"read","domain":"spell","key":"secondary","name":"is_enabled"}
                }],
                "lists":{}
            }"#,
        );

        expect_that!(prepared.lazy_cast_validation_safe(), is_false());
    }

    #[gtest]
    fn nonpositive_availability_read_disables_lazy_validation() {
        let prepared = prepared_rotation(
            r#"{
                "version":1,
                "name":"lazy-negated-availability",
                "variables":{},
                "actions":[{
                    "type":"cast",
                    "spell":"primary",
                    "condition":{
                        "type":"not",
                        "operand":{"type":"read","domain":"spell","key":"primary","name":"is_enabled"}
                    }
                }],
                "lists":{}
            }"#,
        );

        expect_that!(prepared.lazy_cast_validation_safe(), is_false());
    }

    #[gtest]
    fn availability_dependent_variables_and_action_side_effects_disable_lazy_validation() {
        let availability_variable = prepared_rotation(
            r#"{
                "version":1,
                "name":"lazy-variable-availability",
                "variables":{
                    "ready":{"type":"read","domain":"spell","key":"primary","name":"is_enabled"}
                },
                "actions":[{"type":"cast","spell":"primary"}],
                "lists":{}
            }"#,
        );
        let side_effect = prepared_rotation(
            r#"{
                "version":1,
                "name":"lazy-side-effect",
                "variables":{"counter":{"type":"int","value":0}},
                "actions":[
                    {"type":"set_var","name":"counter","value":{"type":"int","value":1}},
                    {"type":"cast","spell":"primary"}
                ],
                "lists":{}
            }"#,
        );

        expect_that!(
            availability_variable.lazy_cast_validation_safe(),
            is_false()
        );
        expect_that!(side_effect.lazy_cast_validation_safe(), is_false());
    }

    #[gtest]
    fn item_action_metadata_tracks_authored_equipment_slots() {
        let prepared = prepared_rotation(
            r#"{
                "version":1,
                "name":"locked-action-metadata",
                "variables":{},
                "actions":[
                    {"type":"use_trinket","slot":2},
                    {"type":"use_item","name":"trinket_1"},
                    {"type":"use_item","name":"trinket_1"},
                    {"type":"use_item","name":"main_hand","enabled":false},
                    {"type":"cast","spell":"primary"}
                ],
                "lists":{}
            }"#,
        );

        expect_that!(
            prepared.item_use_slots(),
            eq([GearSlot::Trinket1, GearSlot::Trinket2].as_slice())
        );
    }

    #[gtest]
    fn resolved_spell_inventory_is_complete_sorted_and_usage_aware() {
        let rotation = parse_and_validate(
            r#"{
                "version":1,
                "name":"reference-inventory",
                "variables":{"ready":{"type":"read","domain":"spell","key":"secondary","name":"is_enabled"}},
                "actions":[
                    {"type":"cast","spell":"primary"},
                    {"type":"cast","spell":"disabled","enabled":false}
                ],
                "lists":{}
            }"#,
        )
        .expect("parse reference fixture");
        let resolver = SpecResolver::new("reference-inventory")
            .spell("primary", 20)
            .spell("secondary", 10)
            .spell("disabled", 30);
        let prepared = RotationPreparation::prepare(&rotation, &resolver)
            .expect("prepare reference fixture")
            .bind(&BufferRequirements::new())
            .expect("bind reference fixture");

        expect_that!(
            prepared.spell_references(),
            eq([
                ResolvedSpellReference {
                    spell: SpellIdx(10),
                    usage: SpellReferenceUsage::FIELD_READ | SpellReferenceUsage::AVAILABILITY,
                    projection_usage: SpellProjectionUsage::empty(),
                },
                ResolvedSpellReference {
                    spell: SpellIdx(20),
                    usage: SpellReferenceUsage::CAST | SpellReferenceUsage::AVAILABILITY,
                    projection_usage: SpellProjectionUsage::empty(),
                },
            ]
            .as_slice())
        );
    }
}