wowlab_engine_combat/state/program/

rotation.rs

// #t(file: rust_too_many_lines_in_file) rotation binding finalization and its cold dependency proof share the same validated spell/profile coordinates.

//! Finalized rotation spell bindings and availability partitions.

#[cfg(feature = "rotation-optimizations")]
use wowlab_engine_domain::rotation::AuraProjectionSlotHandle;
#[cfg(feature = "rotation-optimizations")]
use wowlab_engine_domain::rotation::{
    PreparedActionDependencyPlan, PreparedRotationChangeDirection, PreparedRotationChangeKey,
};
use wowlab_engine_domain::{
    dbc::{ResolvedGameDataSemanticExt as _, SpellSchoolMask, SpellShapeshiftFormFlags},
    rotation::{
        AuraSlotHandle, ItemSlotHandle, PreparedRotation, ResourceSlotHandle, SpellProjectionUsage,
        SpellReferenceUsage, SpellSlotHandle,
    },
};
use wowlab_engine_gamedata::ResolvedGameData;
#[cfg(feature = "rotation-optimizations")]
use wowlab_types::sim::{AuraProjectionKey, SimTime};
use wowlab_types::{
    combat::ResourceType,
    game::GearSlot,
    sim::{ActorId, AuraIdx, AuraKey, AuraOn, EnemyIdx, IntMap, SpellIdx},
};

use super::BufferBindings;
#[cfg(feature = "rotation-optimizations")]
use super::{
    DECISION_ACTOR_STATE, DECISION_AURA_STATE, DECISION_AURA_TIMING, DECISION_ENCOUNTER_POPULATION,
    DECISION_EQUIPMENT_STATE, DECISION_HISTORY_STATE, DECISION_PLAYER_HEALTH, DECISION_SPATIAL,
    DECISION_SPELL_STATE, DECISION_TARGET_HEALTH, DECISION_TARGET_IDENTITY,
    EFFECTIVE_CANDIDATE_COUNT, ROTATION_DECISION_MODE_COUNT, ROTATION_DECISION_MODES,
    RotationDecisionMode, RotationDecisionSubscription,
};
use crate::state::{AuraData, LocalAuraIdx, LocalSpellIdx, SpellData};

#[derive(Debug, thiserror::Error)]
pub(crate) enum RotationPlanError {
    #[error("rotation plan contains {count} spells, exceeding local u8 capacity")]
    TooManySpells {
        count: usize,
        #[source]
        error: std::num::TryFromIntError,
    },
    #[error("rotation references unresolved spell {spell_id}")]
    UnresolvedSpell { spell_id: u32 },
    #[error(
        "rotation spell {spell_id} resolves to local index {local}, whose definition is spell {actual_spell_id}"
    )]
    InconsistentSpell {
        spell_id: u32,
        local: u8,
        actual_spell_id: u32,
    },
    #[error("rotation spell {spell_id} has inconsistent override coordinates")]
    InconsistentOverride { spell_id: u32 },
    #[error("rotation spell {spell_id} references unresolved override spell {override_spell_id}")]
    UnresolvedOverride {
        spell_id: u32,
        override_spell_id: u32,
    },
    #[error("rotation spell {spell_id} references unresolved override aura {aura_id}")]
    UnresolvedOverrideAura { spell_id: u32, aura_id: u32 },
    #[error("rotation spell {spell_id} override aura {aura_id} is not a player aura")]
    UnsupportedOverrideAura { spell_id: u32, aura_id: u32 },
    #[error("cast profile for spell {spell_id} references unresolved {kind} aura {aura_id}")]
    UnresolvedCastAura {
        spell_id: u32,
        kind: &'static str,
        aura_id: u32,
    },
    #[error(
        "cast profile for spell {spell_id} references {kind} aura {aura_id} with unsupported target {on:?}"
    )]
    UnsupportedCastAura {
        spell_id: u32,
        kind: &'static str,
        aura_id: u32,
        on: AuraOn,
    },
    #[error("cast profile for spell {spell_id} is missing concrete {kind} aura {aura_id} binding")]
    MissingCastAuraBinding {
        spell_id: u32,
        kind: &'static str,
        aura_id: u32,
    },
    #[error("cast profile target-aura handle range exceeds the supported finalized range")]
    CastAuraRangeOverflow,
    #[error("rotation spell references are not strictly ordered at spell {spell_id}")]
    InconsistentReferenceOrder { spell_id: u32 },
    #[error("cast reference for spell {spell_id} is missing its availability usage")]
    CastWithoutAvailability { spell_id: u32 },
    #[error("item-use slot {slot:?} references unresolved spell {spell_id}")]
    UnresolvedItemUse { slot: GearSlot, spell_id: u32 },
    #[error("item-use slot {slot:?} has no frozen item-slot binding")]
    MissingItemSlot { slot: GearSlot },
    #[error("item-use slot {slot:?} is registered more than once")]
    DuplicateItemSlot { slot: GearSlot },
    #[cfg(feature = "rotation-optimizations")]
    #[error("rotation decision dependencies are incomplete for {mode} mode: {reason}")]
    IncompleteDecisionMode {
        mode: RotationDecisionMode,
        reason: &'static str,
    },
    #[cfg(feature = "rotation-optimizations")]
    #[error(
        "rotation decision dependencies are incomplete for spell {spell_id} in {mode} mode: {reason}"
    )]
    IncompleteDecisionCandidate {
        mode: RotationDecisionMode,
        spell_id: u32,
        reason: &'static str,
    },
    #[cfg(feature = "rotation-optimizations")]
    #[error("rotation decision threshold references missing {on:?} aura projection {aura_id}")]
    MissingDecisionAuraProjection { aura_id: u32, on: AuraOn },
    #[cfg(feature = "rotation-optimizations")]
    #[error("rotation decision threshold references missing {resource:?} resource slot")]
    MissingDecisionResource { resource: ResourceType },
}

/// Prevalidated replacement coordinates for one rotation-referenced button.
#[derive(Clone, Copy, Debug)]
pub(crate) struct RotationOverrideBinding {
    pub(crate) aura_to_consume: Option<LocalAuraIdx>,
    pub(crate) aura_min_stacks: u8,
    pub(crate) aura_handle: AuraSlotHandle,
    pub(crate) effective_local: LocalSpellIdx,
    pub(crate) shares_base_cooldown: bool,
}

/// One finalized spell identity used by a rotation field or cast action.
#[derive(Clone, Copy, Debug)]
pub(crate) struct RotationSpellBinding {
    pub(crate) spell: SpellIdx,
    pub(crate) local: LocalSpellIdx,
    pub(crate) spell_slot: SpellSlotHandle,
    pub(crate) override_binding: Option<RotationOverrideBinding>,
}

const _: () = assert!(
    size_of::<RotationSpellBinding>() <= 64,
    "rotation spell bindings must remain compact finalized identities"
);

/// Exact concrete aura coordinate used by a finalized cast predicate.
#[derive(Clone, Copy, Debug)]
pub(crate) enum CastAuraCoordinate {
    Player(AuraSlotHandle),
    Target { offset: u32, len: u16 },
}

/// One finalized aura requirement, including the diagnostic identity and typed coordinate.
#[derive(Clone, Copy, Debug)]
pub(crate) struct CastAuraRequirement {
    pub(crate) aura_id: u32,
    pub(crate) local: LocalAuraIdx,
    pub(crate) coordinate: CastAuraCoordinate,
    pub(crate) min_stacks: u8,
}

/// Required and excluded aura-state coordinates for caster and selected target.
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct CastAuraStateProfile {
    pub(crate) required_caster: Option<crate::state::AuraState>,
    pub(crate) required_target: Option<crate::state::AuraState>,
    pub(crate) excluded_caster: Option<crate::state::AuraState>,
    pub(crate) excluded_target: Option<crate::state::AuraState>,
}

/// Finalized range inside the exact active-aura handle table for one spell predicate.
#[derive(Clone, Copy, Debug, Default)]
pub(crate) struct CastAuraHandleRange {
    offset: u32,
    len: u16,
}

/// Finalized cast scalars and typed coordinates indexed directly by local spell identity.
#[derive(Clone, Copy, Debug)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "the cast profile stores independent finalized predicate flags for direct evaluation"
)]
pub(crate) struct CastProfile {
    pub(crate) local: LocalSpellIdx,
    pub(crate) spell_id: u32,
    pub(crate) hostile_min_range: f64,
    pub(crate) hostile_max_range: f64,
    pub(crate) requires_hostile_target: bool,
    pub(crate) ignores_line_of_sight: bool,
    pub(crate) school_mask: SpellSchoolMask,
    pub(crate) damage_pushback: bool,
    pub(crate) channel_duration_pushback: bool,
    pub(crate) main_hand_available: bool,
    pub(crate) off_hand_available: bool,
    pub(crate) equipped_item_matches: bool,
    pub(crate) primary_resource: Option<ResourceSlotHandle>,
    pub(crate) secondary_resource: Option<ResourceSlotHandle>,
    pub(crate) gating_aura: Option<CastAuraRequirement>,
    pub(crate) cost_bypass_aura: Option<CastAuraRequirement>,
    pub(crate) cooldown_bypass_aura: Option<CastAuraRequirement>,
    pub(crate) consume_aura_on_cast: Option<CastAuraRequirement>,
    pub(crate) max_empower_aura: Option<CastAuraRequirement>,
    pub(crate) instant_cast_aura: Option<CastAuraRequirement>,
    pub(crate) channel_tick_cost_aura: Option<CastAuraRequirement>,
    pub(crate) channel_tick_damage_aura: Option<CastAuraRequirement>,
    pub(crate) required_caster_aura: Option<CastAuraRequirement>,
    pub(crate) required_target_aura: Option<CastAuraRequirement>,
    pub(crate) excluded_caster_aura: Option<CastAuraRequirement>,
    pub(crate) excluded_target_aura: Option<CastAuraRequirement>,
    pub(crate) aura_states: CastAuraStateProfile,
    pub(crate) shapeshift_required_mask: u64,
    pub(crate) shapeshift_excluded_mask: u64,
    pub(crate) allow_while_unshifted: bool,
    pub(crate) requires_unshifted: bool,
    pub(crate) requires_stealth: bool,
    stance_exceptions: CastAuraHandleRange,
    passive_stance_exception: bool,
}

/// One exact typed spell slot whose target-dependent fields are observed by the rotation.
#[derive(Clone, Copy, Debug)]
pub(crate) struct RotationProjectionBinding {
    pub(crate) spell: RotationSpellBinding,
    pub(crate) usage: SpellProjectionUsage,
}

/// One finalized item slot and its directly executable cast action.
#[derive(Clone, Copy, Debug)]
pub(crate) struct ItemUseBinding {
    pub(crate) item_slot: ItemSlotHandle,
    pub(crate) action: RotationSpellBinding,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg(feature = "rotation-optimizations")]
enum RotationDecisionThreshold {
    ResourceRise(ResourceDecisionThreshold),
    TargetHealthFall {
        percent_bits: u64,
        strict: bool,
    },
    AuraRemainingFall {
        handle: AuraProjectionSlotHandle,
        seconds_bits: u64,
        strict: bool,
    },
    CooldownRemainingFall {
        local: LocalSpellIdx,
        seconds_bits: u64,
        strict: bool,
    },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg(feature = "rotation-optimizations")]
struct ResourceDecisionThreshold {
    handle: ResourceSlotHandle,
    resource: ResourceType,
    value_bits: u64,
    strict: bool,
}

#[cfg(feature = "rotation-optimizations")]
impl RotationDecisionThreshold {
    fn ready_at(
        self,
        program: &crate::state::CombatProgram,
        instance: &crate::state::CombatInstance,
        now: SimTime,
    ) -> Option<SimTime> {
        match self {
            Self::ResourceRise(threshold) => {
                resource_threshold_ready_at(program, instance, threshold, now)
            }
            Self::TargetHealthFall {
                percent_bits,
                strict,
            } => target_health_threshold_ready_at(instance, percent_bits, strict, now),
            Self::AuraRemainingFall {
                handle,
                seconds_bits,
                strict,
            } => aura_remaining_threshold_ready_at(instance, handle, seconds_bits, strict, now),
            Self::CooldownRemainingFall {
                local,
                seconds_bits,
                strict,
            } => cooldown_remaining_threshold_ready_at(
                program,
                instance,
                local,
                seconds_bits,
                strict,
                now,
            ),
        }
    }
}

#[cfg(feature = "rotation-optimizations")]
fn resource_threshold_ready_at(
    program: &crate::state::CombatProgram,
    instance: &crate::state::CombatInstance,
    threshold: ResourceDecisionThreshold,
    now: SimTime,
) -> Option<SimTime> {
    let value = f64::from_bits(threshold.value_bits);
    let state = instance.buffer.resource_at(threshold.handle);

    if value > state.max || (threshold.strict && value >= state.max) || state.regen_per_sec <= 0.0 {
        return None;
    }

    if threshold.resource == ResourceType::Runes {
        let required = if threshold.strict {
            value.floor() + 1.0
        } else {
            value.ceil()
        };
        let deficit = (required - state.current).max(0.0);
        let needed =
            usize::try_from(wowlab_types::numeric::f64_to_u32_saturating_ceil(deficit)).ok()?;
        let seconds = crate::systems::rune_time_to_regen(program, instance, needed)?;

        return decision_crossing_time(now.as_secs_f64() + seconds, false, now);
    }

    if state.current > value || (!threshold.strict && state.current >= value) {
        return None;
    }

    let seconds = (value - state.current) / state.regen_per_sec;

    decision_crossing_time(now.as_secs_f64() + seconds, threshold.strict, now)
}

#[cfg(feature = "rotation-optimizations")]
fn target_health_threshold_ready_at(
    instance: &crate::state::CombatInstance,
    percent_bits: u64,
    strict: bool,
    now: SimTime,
) -> Option<SimTime> {
    let target = instance.current_target()?;
    let enemy = instance.enemy(target)?;
    let seconds = enemy.scripted_health_threshold_seconds(f64::from_bits(percent_bits))?;

    decision_crossing_time(seconds, strict, now)
}

#[cfg(feature = "rotation-optimizations")]
fn aura_remaining_threshold_ready_at(
    instance: &crate::state::CombatInstance,
    handle: AuraProjectionSlotHandle,
    seconds_bits: u64,
    strict: bool,
    now: SimTime,
) -> Option<SimTime> {
    let aura = instance.buffer.aura_projection_at(handle);

    if !aura.is_occupied() {
        return None;
    }

    let seconds = aura.expires_at - f64::from_bits(seconds_bits).max(0.0);

    decision_crossing_time(seconds, strict, now)
}

#[cfg(feature = "rotation-optimizations")]
fn cooldown_remaining_threshold_ready_at(
    program: &crate::state::CombatProgram,
    instance: &crate::state::CombatInstance,
    local: LocalSpellIdx,
    seconds_bits: u64,
    strict: bool,
    now: SimTime,
) -> Option<SimTime> {
    let cooldown = program.buffer_cooldown(instance, local)?;
    let seconds = cooldown.ready_at - f64::from_bits(seconds_bits).max(0.0);

    decision_crossing_time(seconds, strict, now)
}

#[cfg(feature = "rotation-optimizations")]
fn decision_crossing_time(seconds: f64, strict: bool, now: SimTime) -> Option<SimTime> {
    let rounded = SimTime::from_secs_f64(seconds);
    let rounded_seconds = rounded.as_secs_f64();
    let ready_at = if rounded_seconds < seconds || (strict && rounded_seconds <= seconds) {
        rounded.saturating_add(SimTime::from_millis(1))
    } else {
        rounded
    };

    (ready_at > now).then_some(ready_at)
}

#[derive(Clone, Copy)]
pub(crate) struct RotationPlanInputs<'a> {
    pub(crate) spells: &'a [SpellData],
    pub(crate) spell_by_id: &'a IntMap<u32, LocalSpellIdx>,
    pub(crate) auras: &'a [AuraData],
    pub(crate) aura_by_id: &'a IntMap<u32, LocalAuraIdx>,
    pub(crate) bindings: &'a BufferBindings,
    pub(crate) passive_driver_effects: &'a [crate::state::PassiveDriverEffect],
    pub(crate) primary_resource_type: Option<ResourceType>,
    pub(crate) secondary_resource_type: Option<ResourceType>,
    pub(crate) enemy_count: usize,
    pub(crate) item_use_spells: &'a [(GearSlot, u32)],
}

fn gear_slot_index(slot: GearSlot) -> usize {
    // #t(rust_lossy_cast) `GearSlot` has a `u8` representation, so this conversion is exact.
    usize::from(slot as u8)
}

fn compile_item_uses(
    definitions: &[(GearSlot, u32)],
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    local_bindings: &[RotationSpellBinding],
    bindings: &BufferBindings,
) -> Result<Box<[Option<ItemUseBinding>]>, RotationPlanError> {
    let mut item_uses = vec![None; usize::from(u8::MAX) + 1];

    for &(slot, spell_id) in definitions {
        let local = spell_by_id
            .get(&spell_id)
            .copied()
            .ok_or(RotationPlanError::UnresolvedItemUse { slot, spell_id })?;
        let action = local_bindings
            .get(local.as_usize())
            .copied()
            .ok_or(RotationPlanError::UnresolvedItemUse { slot, spell_id })?;
        let item_slot = bindings
            .item(slot.slug())
            .ok_or(RotationPlanError::MissingItemSlot { slot })?;
        // BOUNDS: the table has one entry for every possible `u8` gear-slot discriminant.
        let entry = &mut item_uses[gear_slot_index(slot)];

        if entry.is_some() {
            return Err(RotationPlanError::DuplicateItemSlot { slot });
        }

        *entry = Some(ItemUseBinding { item_slot, action });
    }

    Ok(item_uses.into_boxed_slice())
}

/// Immutable rotation bindings derived from [`PreparedRotation`] reference metadata.
#[derive(Debug)]
pub(crate) struct RotationPlan {
    local_bindings: Box<[RotationSpellBinding]>,
    #[cfg(test)]
    bindings: Box<[RotationSpellBinding]>,
    availability: Box<[RotationSpellBinding]>,
    #[cfg(test)]
    cast_actions: Box<[RotationSpellBinding]>,
    cast_profiles: Box<[CastProfile]>,
    cast_target_aura_handles: Box<[AuraSlotHandle]>,
    stance_exception_handles: Box<[AuraSlotHandle]>,
    shapeshift_form_flags: Box<[i32]>,
    projections: Box<[RotationProjectionBinding]>,
    item_uses: Box<[Option<ItemUseBinding>]>,
    #[cfg(feature = "rotation-optimizations")]
    decision_subscriptions: [RotationDecisionSubscription; ROTATION_DECISION_MODE_COUNT],
    #[cfg(feature = "rotation-optimizations")]
    decision_thresholds: Box<[RotationDecisionThreshold]>,
    #[cfg(feature = "rotation-optimizations")]
    may_cast_off_gcd: bool,
}

impl RotationPlan {
    // #t(fn: rust_cyclomatic_complexity) cold finalization validates and partitions every prepared reference while preserving stable order.
    // #t(fn: rust_max_fn_lines) construction compiles the complete rotation relationship graph in one auditable pass.
    pub(crate) fn compile(
        prepared: &PreparedRotation,
        inputs: RotationPlanInputs<'_>,
        game_data: &ResolvedGameData,
    ) -> Result<Self, RotationPlanError> {
        let RotationPlanInputs {
            spells,
            spell_by_id,
            auras,
            aura_by_id,
            bindings,
            passive_driver_effects,
            primary_resource_type,
            secondary_resource_type,
            enemy_count,
            item_use_spells,
        } = inputs;

        let references = prepared.spell_references();
        let mut cast_target_aura_handles = Vec::new();
        let mut stance_exception_handles = Vec::new();
        let cast_profiles = spells
            .iter()
            .enumerate()
            .map(|(index, spell)| {
                let local =
                    u8::try_from(index).map_err(|error| RotationPlanError::TooManySpells {
                        count: index + 1,
                        error,
                    })?;

                compile_cast_profile(
                    LocalSpellIdx::new(local),
                    spell,
                    auras,
                    aura_by_id,
                    bindings,
                    passive_driver_effects,
                    primary_resource_type,
                    secondary_resource_type,
                    enemy_count,
                    game_data,
                    &mut cast_target_aura_handles,
                    &mut stance_exception_handles,
                )
            })
            .collect::<Result<Vec<_>, _>>()?;
        let local_bindings = spells
            .iter()
            .map(|spell| {
                bind_spell(
                    SpellIdx::from_raw(spell.spell_id),
                    spells,
                    spell_by_id,
                    auras,
                    aura_by_id,
                    bindings,
                )
            })
            .collect::<Result<Vec<_>, _>>()?;
        let item_uses = compile_item_uses(item_use_spells, spell_by_id, &local_bindings, bindings)?;
        #[cfg(test)]
        let mut all = Vec::with_capacity(references.len());
        let mut availability = Vec::with_capacity(references.len());
        #[cfg(test)]
        let mut cast_actions = Vec::with_capacity(references.len());
        let mut projections = Vec::with_capacity(references.len());
        let mut previous = None;
        #[cfg(feature = "rotation-optimizations")]
        let mut may_cast_off_gcd = false;

        for reference in references {
            let spell = reference.spell();

            if previous.is_some_and(|previous| previous >= spell.as_u32()) {
                return Err(RotationPlanError::InconsistentReferenceOrder {
                    spell_id: spell.as_u32(),
                });
            }

            previous = Some(spell.as_u32());
            let local =
                spell_by_id
                    .get(&spell.as_u32())
                    .ok_or(RotationPlanError::UnresolvedSpell {
                        spell_id: spell.as_u32(),
                    })?;
            let binding = local_bindings.get(local.as_usize()).copied().ok_or(
                RotationPlanError::UnresolvedSpell {
                    spell_id: spell.as_u32(),
                },
            )?;
            let usage = reference.usage();

            if usage.contains(SpellReferenceUsage::CAST)
                && !usage.contains(SpellReferenceUsage::AVAILABILITY)
            {
                return Err(RotationPlanError::CastWithoutAvailability {
                    spell_id: spell.as_u32(),
                });
            }

            #[cfg(test)]
            all.push(binding);

            if usage.contains(SpellReferenceUsage::AVAILABILITY) {
                availability.push(binding);
            }

            #[cfg(test)]
            if usage.contains(SpellReferenceUsage::CAST) {
                cast_actions.push(binding);
            }

            #[cfg(feature = "rotation-optimizations")]
            if usage.contains(SpellReferenceUsage::CAST) {
                let (off_gcd, _) = binding_lock_capabilities(binding, spells);

                may_cast_off_gcd |= off_gcd;
            }

            if !reference.projection_usage().is_empty() {
                projections.push(RotationProjectionBinding {
                    spell: binding,
                    usage: reference.projection_usage(),
                });
            }
        }

        let mut shapeshift_form_flags = vec![0_i32; usize::from(u8::MAX) + 1];

        for aura in auras {
            if aura.shapeshift_form == 0 {
                continue;
            }

            if let Ok(form) = usize::try_from(aura.shapeshift_form)
                && let Some(flags) = shapeshift_form_flags.get_mut(form)
            {
                *flags = aura.shapeshift_form_flags;
            }
        }

        #[cfg(feature = "rotation-optimizations")]
        for &slot in prepared.item_use_slots() {
            if let Some(item_use) = item_uses.get(gear_slot_index(slot)).copied().flatten() {
                let (off_gcd, _) = binding_lock_capabilities(item_use.action, spells);

                may_cast_off_gcd |= off_gcd;
            }
        }

        #[cfg(feature = "rotation-optimizations")]
        let decision_subscriptions = compile_decision_subscriptions(DecisionSubscriptionInputs {
            prepared,
            spells,
            spell_by_id,
            bindings: &local_bindings,
            profiles: &cast_profiles,
            primary_resource_type,
            secondary_resource_type,
        })?;
        #[cfg(feature = "rotation-optimizations")]
        let decision_thresholds =
            compile_decision_thresholds(prepared, spells, spell_by_id, &local_bindings)?;

        Ok(Self {
            local_bindings: local_bindings.into_boxed_slice(),
            #[cfg(test)]
            bindings: all.into_boxed_slice(),
            availability: availability.into_boxed_slice(),
            #[cfg(test)]
            cast_actions: cast_actions.into_boxed_slice(),
            cast_profiles: cast_profiles.into_boxed_slice(),
            cast_target_aura_handles: cast_target_aura_handles.into_boxed_slice(),
            stance_exception_handles: stance_exception_handles.into_boxed_slice(),
            shapeshift_form_flags: shapeshift_form_flags.into_boxed_slice(),
            projections: projections.into_boxed_slice(),
            item_uses,
            #[cfg(feature = "rotation-optimizations")]
            decision_subscriptions,
            #[cfg(feature = "rotation-optimizations")]
            decision_thresholds,
            #[cfg(feature = "rotation-optimizations")]
            may_cast_off_gcd,
        })
    }

    #[cfg(test)]
    pub(crate) fn bindings(&self) -> &[RotationSpellBinding] {
        &self.bindings
    }

    pub(crate) fn availability(&self) -> &[RotationSpellBinding] {
        &self.availability
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn availability_binding(&self, spell_id: u32) -> Option<RotationSpellBinding> {
        self.availability
            .binary_search_by_key(&spell_id, |binding| binding.spell.as_u32())
            .ok()
            .and_then(|index| self.availability.get(index).copied())
    }

    pub(crate) fn cast_profile(&self, local: LocalSpellIdx) -> CastProfile {
        *self.cast_profile_ref(local)
    }

    pub(crate) fn cast_profile_ref(&self, local: LocalSpellIdx) -> &CastProfile {
        // BOUNDS: finalization creates exactly one profile for every stable local spell index.
        &self.cast_profiles[local.as_usize()]
    }

    pub(crate) fn aura_stacks(
        &self,
        instance: &crate::state::CombatInstance,
        requirement: CastAuraRequirement,
        target: EnemyIdx,
    ) -> i32 {
        let handle = match requirement.coordinate {
            CastAuraCoordinate::Player(handle) => Some(handle),
            CastAuraCoordinate::Target { offset, len } => {
                let index = target.as_usize();

                (index < usize::from(len))
                    .then(|| usize::try_from(offset).ok()?.checked_add(index))
                    .flatten()
                    .and_then(|index| self.cast_target_aura_handles.get(index).copied())
            }
        };

        handle.map_or(0, |handle| {
            let aura = instance.buffer.aura_at(handle);

            if aura.is_occupied() { aura.stacks } else { 0 }
        })
    }

    pub(crate) fn aura_active(
        &self,
        instance: &crate::state::CombatInstance,
        requirement: CastAuraRequirement,
        target: EnemyIdx,
    ) -> bool {
        self.aura_stacks(instance, requirement, target) >= i32::from(requirement.min_stacks.max(1))
    }

    pub(crate) fn stance_exception_active(
        &self,
        instance: &crate::state::CombatInstance,
        profile: &CastProfile,
    ) -> bool {
        if profile.passive_stance_exception {
            return true;
        }

        let start = usize::try_from(profile.stance_exceptions.offset).unwrap_or(usize::MAX);
        let end = start.saturating_add(usize::from(profile.stance_exceptions.len));

        self.stance_exception_handles
            .get(start..end)
            .is_some_and(|handles| {
                handles
                    .iter()
                    .any(|&handle| instance.buffer.aura_at(handle).is_occupied())
            })
    }

    pub(crate) fn shapeshift_form_flags(&self, form: u8) -> SpellShapeshiftFormFlags {
        self.shapeshift_form_flags
            .get(usize::from(form))
            .copied()
            .map_or_else(SpellShapeshiftFormFlags::empty, |flags| {
                SpellShapeshiftFormFlags::from_bits_retain(flags)
            })
    }

    pub(crate) fn local_binding(&self, local: LocalSpellIdx) -> RotationSpellBinding {
        // BOUNDS: finalization creates exactly one binding for every stable local spell index.
        self.local_bindings[local.as_usize()]
    }

    pub(crate) fn projections(&self) -> &[RotationProjectionBinding] {
        &self.projections
    }

    pub(crate) fn item_use(&self, slot: GearSlot) -> Option<ItemUseBinding> {
        self.item_uses.get(gear_slot_index(slot)).copied().flatten()
    }

    pub(crate) fn item_uses(&self) -> impl Iterator<Item = ItemUseBinding> + '_ {
        self.item_uses.iter().copied().flatten()
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) const fn decision_subscription(
        &self,
        mode: RotationDecisionMode,
    ) -> &RotationDecisionSubscription {
        // BOUNDS: every decision-mode discriminant maps to its fixed subscription slot.
        &self.decision_subscriptions[mode.index()]
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn exact_decision_horizon(
        &self,
        program: &crate::state::CombatProgram,
        instance: &crate::state::CombatInstance,
        now: SimTime,
    ) -> Option<SimTime> {
        self.decision_thresholds
            .iter()
            .filter_map(|threshold| threshold.ready_at(program, instance, now))
            .min()
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) const fn may_cast_off_gcd(&self) -> bool {
        self.may_cast_off_gcd
    }

    #[cfg(test)]
    pub(crate) fn cast_actions(&self) -> &[RotationSpellBinding] {
        &self.cast_actions
    }

    #[cfg(test)]
    pub(crate) fn binding(&self, spell_id: u32) -> Option<RotationSpellBinding> {
        self.bindings
            .binary_search_by_key(&spell_id, |binding| binding.spell.as_u32())
            .ok()
            .and_then(|index| self.bindings.get(index).copied())
    }

    #[cfg(test)]
    pub(crate) fn cast_action(&self, spell_id: u32) -> Option<RotationSpellBinding> {
        self.cast_actions
            .binary_search_by_key(&spell_id, |binding| binding.spell.as_u32())
            .ok()
            .and_then(|index| self.cast_actions.get(index).copied())
    }
}

#[cfg(feature = "rotation-optimizations")]
fn binding_lock_capabilities(binding: RotationSpellBinding, spells: &[SpellData]) -> (bool, bool) {
    let mut off_gcd = false;
    let mut while_casting = false;
    let locals = std::iter::once(binding.local).chain(
        binding
            .override_binding
            .map(|override_binding| override_binding.effective_local),
    );

    for local in locals {
        let spell = spells
            .get(local.as_usize())
            .expect("finalized rotation binding has a registered local spell");

        off_gcd |= spell.behavior.off_gcd;
        while_casting |= spell.requirements.availability.usable_while_casting;
    }

    (off_gcd, while_casting)
}

#[cfg(feature = "rotation-optimizations")]
struct DecisionSubscriptionInputs<'a> {
    prepared: &'a PreparedRotation,
    spells: &'a [SpellData],
    spell_by_id: &'a IntMap<u32, LocalSpellIdx>,
    bindings: &'a [RotationSpellBinding],
    profiles: &'a [CastProfile],
    primary_resource_type: Option<ResourceType>,
    secondary_resource_type: Option<ResourceType>,
}

#[cfg(feature = "rotation-optimizations")]
fn compile_decision_thresholds(
    prepared: &PreparedRotation,
    spells: &[SpellData],
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    bindings: &[RotationSpellBinding],
) -> Result<Box<[RotationDecisionThreshold]>, RotationPlanError> {
    let mut thresholds = Vec::new();

    compile_authored_decision_thresholds(prepared, spell_by_id, &mut thresholds)?;
    compile_execute_decision_thresholds(prepared, spells, spell_by_id, bindings, &mut thresholds)?;

    Ok(thresholds.into_boxed_slice())
}

#[cfg(feature = "rotation-optimizations")]
fn compile_authored_decision_thresholds(
    prepared: &PreparedRotation,
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    thresholds: &mut Vec<RotationDecisionThreshold>,
) -> Result<(), RotationPlanError> {
    for action in prepared.action_dependency_plans() {
        for change in action.changes() {
            let threshold = match (change.key(), change.direction()) {
                (
                    PreparedRotationChangeKey::ResourceThreshold {
                        resource,
                        value_bits,
                        strict,
                    },
                    PreparedRotationChangeDirection::Rise,
                ) => {
                    let handle = prepared
                        .schema()
                        .buffer_finalizer()
                        .bind_resource(resource)
                        .ok_or(RotationPlanError::MissingDecisionResource { resource })?;

                    Some(RotationDecisionThreshold::ResourceRise(
                        ResourceDecisionThreshold {
                            handle,
                            resource,
                            value_bits,
                            strict,
                        },
                    ))
                }
                (
                    PreparedRotationChangeKey::TargetHealthThreshold {
                        percent_bits,
                        strict,
                    },
                    PreparedRotationChangeDirection::Fall,
                ) => Some(RotationDecisionThreshold::TargetHealthFall {
                    percent_bits,
                    strict,
                }),
                (
                    PreparedRotationChangeKey::AuraRemainingThreshold {
                        aura,
                        on,
                        seconds_bits,
                        strict,
                    },
                    PreparedRotationChangeDirection::Fall,
                ) => {
                    let projection = AuraProjectionKey::new(aura, on);
                    let mut handle = None;

                    prepared.schema().buffer_finalizer().visit_aura_projections(
                        |candidate, candidate_handle| {
                            if candidate == projection {
                                handle = Some(candidate_handle);
                            }
                        },
                    );
                    let handle =
                        handle.ok_or(RotationPlanError::MissingDecisionAuraProjection {
                            aura_id: aura.as_u32(),
                            on,
                        })?;

                    Some(RotationDecisionThreshold::AuraRemainingFall {
                        handle,
                        seconds_bits,
                        strict,
                    })
                }
                (
                    PreparedRotationChangeKey::CooldownRemainingThreshold {
                        spell,
                        seconds_bits,
                        strict,
                    },
                    PreparedRotationChangeDirection::Fall,
                ) => {
                    let spell_id = spell.as_u32();
                    let local = spell_by_id
                        .get(&spell_id)
                        .copied()
                        .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;

                    Some(RotationDecisionThreshold::CooldownRemainingFall {
                        local,
                        seconds_bits,
                        strict,
                    })
                }
                _ => None,
            };

            if let Some(threshold) = threshold
                && !thresholds.contains(&threshold)
            {
                thresholds.push(threshold);
            }
        }
    }

    Ok(())
}

#[cfg(feature = "rotation-optimizations")]
fn compile_execute_decision_thresholds(
    prepared: &PreparedRotation,
    spells: &[SpellData],
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    bindings: &[RotationSpellBinding],
    thresholds: &mut Vec<RotationDecisionThreshold>,
) -> Result<(), RotationPlanError> {
    for action in prepared.action_dependency_plans() {
        let spell_id = action.spell().as_u32();
        let local = spell_by_id
            .get(&spell_id)
            .copied()
            .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
        let binding = bindings
            .get(local.as_usize())
            .copied()
            .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
        let candidates = std::iter::once(binding.local).chain(
            binding
                .override_binding
                .map(|override_binding| override_binding.effective_local),
        );

        for effective_local in candidates {
            let spell = spells
                .get(effective_local.as_usize())
                .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
            let percent = spell.requirements.execute_below_pct;

            if percent <= 0.0 {
                continue;
            }

            let threshold = RotationDecisionThreshold::TargetHealthFall {
                percent_bits: percent.to_bits(),
                strict: false,
            };

            if !thresholds.contains(&threshold) {
                thresholds.push(threshold);
            }
        }
    }

    Ok(())
}

#[cfg(feature = "rotation-optimizations")]
// #t(fn: rust_cyclomatic_complexity) cold compilation validates each exact lock mode and rejects every incomplete action before runtime.
fn compile_decision_subscriptions(
    inputs: DecisionSubscriptionInputs<'_>,
) -> Result<[RotationDecisionSubscription; ROTATION_DECISION_MODE_COUNT], RotationPlanError> {
    let DecisionSubscriptionInputs {
        prepared,
        spells,
        spell_by_id,
        bindings,
        profiles,
        primary_resource_type,
        secondary_resource_type,
    } = inputs;
    let mut subscriptions =
        [RotationDecisionSubscription::complete(); ROTATION_DECISION_MODE_COUNT];

    for mode in ROTATION_DECISION_MODES {
        let Some(subscription) = subscriptions.get_mut(mode.index()) else {
            return Err(RotationPlanError::IncompleteDecisionMode {
                mode,
                reason: "the fixed decision-mode subscription table is inconsistent",
            });
        };

        for action in prepared.action_dependency_plans() {
            let spell_id = action.spell().as_u32();
            let local = spell_by_id
                .get(&spell_id)
                .copied()
                .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
            let binding = bindings
                .get(local.as_usize())
                .copied()
                .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
            let candidates = eligible_effective_candidates(binding, spells, mode);

            if candidates.iter().all(Option::is_none) {
                continue;
            }

            subscription.has_eligible_actions = true;

            if !action.complete() {
                subscription.complete = false;

                return Err(RotationPlanError::IncompleteDecisionCandidate {
                    mode,
                    spell_id,
                    reason: "the action condition uses unsupported dynamic state",
                });
            }

            if binding.override_binding.is_some() {
                insert_semantic_both(subscription, DECISION_AURA_STATE);
            }

            insert_prepared_changes(subscription, action, spell_by_id, mode)?;

            for effective_local in candidates.into_iter().flatten() {
                let cooldown_local = binding
                    .override_binding
                    .filter(|override_binding| {
                        override_binding.effective_local == effective_local
                            && override_binding.shares_base_cooldown
                    })
                    .map_or(effective_local, |_| binding.local);
                let spell = spells
                    .get(effective_local.as_usize())
                    .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
                let profile = profiles
                    .get(effective_local.as_usize())
                    .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;

                insert_implicit_candidate_changes(
                    subscription,
                    cooldown_local,
                    spell,
                    profile,
                    primary_resource_type,
                    secondary_resource_type,
                );
            }
        }

        if subscription.has_eligible_actions && !prepared.action_dependencies_complete() {
            subscription.complete = false;

            return Err(RotationPlanError::IncompleteDecisionMode {
                mode,
                reason: "reachable control flow contains a non-cast or conditioned list action",
            });
        }
    }

    Ok(subscriptions)
}

#[cfg(feature = "rotation-optimizations")]
fn eligible_effective_candidates(
    binding: RotationSpellBinding,
    spells: &[SpellData],
    mode: RotationDecisionMode,
) -> [Option<LocalSpellIdx>; EFFECTIVE_CANDIDATE_COUNT] {
    let effective = binding
        .override_binding
        .map(|override_binding| override_binding.effective_local);
    let base = mode_allows_candidate(binding.local, spells, mode).then_some(binding.local);
    let effective = effective.filter(|&local| mode_allows_candidate(local, spells, mode));

    [base, effective.filter(|&local| Some(local) != base)]
}

#[cfg(feature = "rotation-optimizations")]
fn mode_allows_candidate(
    local: LocalSpellIdx,
    spells: &[SpellData],
    mode: RotationDecisionMode,
) -> bool {
    let spell = spells
        .get(local.as_usize())
        .expect("finalized rotation binding has a registered local spell");
    let off_gcd = spell.behavior.off_gcd;
    let while_casting = spell.requirements.availability.usable_while_casting;

    match mode {
        RotationDecisionMode::Unlocked => true,
        RotationDecisionMode::Gcd => off_gcd,
        RotationDecisionMode::Casting => while_casting,
        RotationDecisionMode::Both => off_gcd && while_casting,
    }
}

#[cfg(feature = "rotation-optimizations")]
fn insert_prepared_changes(
    subscription: &mut RotationDecisionSubscription,
    action: &PreparedActionDependencyPlan,
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    mode: RotationDecisionMode,
) -> Result<(), RotationPlanError> {
    for change in action.changes() {
        let direction = change.direction();

        if !matches!(
            direction,
            PreparedRotationChangeDirection::Rise | PreparedRotationChangeDirection::Fall
        ) {
            subscription.complete = false;

            return Err(RotationPlanError::IncompleteDecisionCandidate {
                mode,
                spell_id: action.spell().as_u32(),
                reason: "the prepared dependency direction is not supported by combat",
            });
        }

        if insert_prepared_cooldown_change(subscription, change.key(), spell_by_id, direction)? {
            continue;
        }

        match change.key() {
            PreparedRotationChangeKey::ResourceThreshold { resource, .. } => {
                subscription.insert_resource(resource, direction);
            }
            PreparedRotationChangeKey::AuraState => {
                subscription.insert_semantic(DECISION_AURA_STATE, direction);
            }
            PreparedRotationChangeKey::TargetHealthThreshold { .. } => {
                subscription.insert_semantic(DECISION_TARGET_HEALTH, direction);
            }
            PreparedRotationChangeKey::AuraRemainingThreshold { .. } => {
                subscription.insert_semantic(DECISION_AURA_STATE, direction);
                subscription.insert_semantic(DECISION_AURA_TIMING, direction);
            }
            PreparedRotationChangeKey::Spatial => {
                subscription.insert_semantic(DECISION_SPATIAL, direction);
            }
            PreparedRotationChangeKey::EncounterPopulation => {
                subscription.insert_semantic(DECISION_ENCOUNTER_POPULATION, direction);
            }
            PreparedRotationChangeKey::SpellState => {
                subscription.insert_semantic(DECISION_SPELL_STATE, direction);
            }
            PreparedRotationChangeKey::EquipmentState => {
                subscription.insert_semantic(DECISION_EQUIPMENT_STATE, direction);
            }
            PreparedRotationChangeKey::HistoryState => {
                subscription.insert_semantic(DECISION_HISTORY_STATE, direction);
            }
            _ => {
                subscription.complete = false;

                return Err(RotationPlanError::IncompleteDecisionCandidate {
                    mode,
                    spell_id: action.spell().as_u32(),
                    reason: "the prepared dependency kind is not supported by combat",
                });
            }
        }
    }

    Ok(())
}

#[cfg(feature = "rotation-optimizations")]
fn insert_prepared_cooldown_change(
    subscription: &mut RotationDecisionSubscription,
    key: PreparedRotationChangeKey,
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    direction: PreparedRotationChangeDirection,
) -> Result<bool, RotationPlanError> {
    let (spell, direction) = match key {
        PreparedRotationChangeKey::SpellCooldownReady(spell) => (spell, direction),
        PreparedRotationChangeKey::CooldownRemainingThreshold { spell, .. } => {
            let reversed = match direction {
                PreparedRotationChangeDirection::Rise => PreparedRotationChangeDirection::Fall,
                PreparedRotationChangeDirection::Fall => PreparedRotationChangeDirection::Rise,
                _ => direction,
            };

            (spell, reversed)
        }
        _ => return Ok(false),
    };
    let spell_id = spell.as_u32();
    let local = spell_by_id
        .get(&spell_id)
        .copied()
        .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;

    subscription.insert_cooldown(local, direction);

    Ok(true)
}

#[cfg(feature = "rotation-optimizations")]
fn insert_implicit_candidate_changes(
    subscription: &mut RotationDecisionSubscription,
    cooldown_local: LocalSpellIdx,
    spell: &SpellData,
    profile: &CastProfile,
    primary_resource_type: Option<ResourceType>,
    secondary_resource_type: Option<ResourceType>,
) {
    // Every candidate observes requested/effective spell gates, the current target,
    // actor control/movement state, and range. These coarse semantic families are
    // transaction-local fixed bits; they do not restore source-based wakeups.
    insert_semantic_both(subscription, DECISION_AURA_STATE);
    insert_semantic_both(subscription, DECISION_ACTOR_STATE);
    insert_semantic_both(subscription, DECISION_SPATIAL);
    insert_semantic_both(subscription, DECISION_ENCOUNTER_POPULATION);
    insert_semantic_both(subscription, DECISION_TARGET_IDENTITY);
    subscription.insert_cooldown(cooldown_local, PreparedRotationChangeDirection::Rise);

    if spell.requirements.execute_below_pct > 0.0 {
        subscription.insert_semantic(
            DECISION_TARGET_HEALTH,
            PreparedRotationChangeDirection::Fall,
        );
    }

    if spell.cost.health_cost > 0.0 || spell.cost.health_cost_pct > 0.0 {
        subscription.insert_semantic(
            DECISION_PLAYER_HEALTH,
            PreparedRotationChangeDirection::Rise,
        );
    }

    // #t(rust_floating_point_eq) finalized cost fields use exact zero as the absent sentinel.
    if (spell.cost.resource_cost != 0.0 || spell.cost.resource_cost_pct.percent != 0.0)
        && profile.primary_resource.is_some()
        && let Some(resource) = primary_resource_type
    {
        subscription.insert_resource(resource, PreparedRotationChangeDirection::Rise);
    }

    // #t(rust_floating_point_eq) finalized cost fields use exact zero as the absent sentinel.
    if spell.cost.secondary_resource_cost != 0.0
        && profile.secondary_resource.is_some()
        && let Some(resource) = secondary_resource_type
    {
        subscription.insert_resource(resource, PreparedRotationChangeDirection::Rise);
    }
}

#[cfg(feature = "rotation-optimizations")]
fn insert_semantic_both(subscription: &mut RotationDecisionSubscription, semantic: u16) {
    subscription.insert_semantic(semantic, PreparedRotationChangeDirection::Rise);
    subscription.insert_semantic(semantic, PreparedRotationChangeDirection::Fall);
}

// #t(fn: rust_large_fn_params) cold profile compilation joins independent spell, aura, binding, resource, encounter, and game-data inputs.
// #t(fn: rust_max_fn_lines) the profile is the single auditable inventory of every cast predicate coordinate.
// #t(fn: rust_cyclomatic_complexity) each independent authored cast requirement contributes one explicit finalized coordinate.
#[expect(
    clippy::too_many_arguments,
    reason = "cold profile compilation keeps independent binding inputs explicit"
)]
fn compile_cast_profile(
    local: LocalSpellIdx,
    spell: &SpellData,
    auras: &[AuraData],
    aura_by_id: &IntMap<u32, LocalAuraIdx>,
    bindings: &BufferBindings,
    passive_driver_effects: &[crate::state::PassiveDriverEffect],
    primary_resource_type: Option<ResourceType>,
    secondary_resource_type: Option<ResourceType>,
    enemy_count: usize,
    data: &ResolvedGameData,
    target_aura_handles: &mut Vec<AuraSlotHandle>,
    stance_exception_handles: &mut Vec<AuraSlotHandle>,
) -> Result<CastProfile, RotationPlanError> {
    let spell_id = SpellIdx::from_raw(spell.spell_id);
    let requirement = spell.requirements.equipped_item_requirement;
    let hand = if spell.requirements.equipment.requires_off_hand {
        wowlab_engine_gamedata::ResolvedDamageWeapon::OffHand
    } else {
        wowlab_engine_gamedata::ResolvedDamageWeapon::MainHand
    };
    let equipped_item_matches = requirement.is_none_or(|requirement| {
        wowlab_engine_domain::dbc::equipped_weapon_matches(data, hand, requirement)
    });

    let gating_aura = bind_cast_aura(
        spell,
        "gating",
        spell.requirements.gating_aura_id,
        spell.requirements.gating_aura_min_stacks,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let cost_bypass_aura = bind_cast_aura(
        spell,
        "cost bypass",
        spell.requirements.cost_bypass_aura_id,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let cooldown_bypass_aura = bind_cast_aura(
        spell,
        "cooldown bypass",
        spell.requirements.cooldown_bypass_aura_id,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let consume_aura_on_cast = bind_cast_aura(
        spell,
        "consume on cast",
        spell.requirements.consume_aura_on_cast_id,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let max_empower_aura = bind_cast_aura(
        spell,
        "max empower",
        spell.max_empower_aura_id,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let instant_cast_aura = bind_cast_aura(
        spell,
        "instant cast",
        spell.requirements.instant_cast_aura_id,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let channel_tick_cost_aura = bind_cast_aura(
        spell,
        "channel tick cost",
        spell.channel.tick_cost_aura,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let channel_tick_damage_aura = bind_cast_aura(
        spell,
        "channel tick damage",
        spell.channel.tick_damage_aura,
        1,
        None,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let required_caster_aura = bind_signed_cast_aura(
        spell,
        "required caster",
        spell.requirements.caster_aura_spell,
        AuraOn::Player,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let required_target_aura = bind_signed_cast_aura(
        spell,
        "required target",
        spell.requirements.target_aura_spell,
        AuraOn::Target,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let excluded_caster_aura = bind_signed_cast_aura(
        spell,
        "excluded caster",
        spell.requirements.exclude_caster_aura_spell,
        AuraOn::Player,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let excluded_target_aura = bind_signed_cast_aura(
        spell,
        "excluded target",
        spell.requirements.exclude_target_aura_spell,
        AuraOn::Target,
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )?;
    let stance_start = stance_exception_handles.len();
    let mut passive_stance_exception = false;

    for aura in auras {
        let affects = aura.effects.iter().flatten().any(|effect| {
            let crate::state::BuffEffect::SpellStanceMaskFromEffect {
                source_spell_id,
                effect_index,
            } = effect
            else {
                return false;
            };

            data.effect_affects_spell(
                SpellIdx::from_raw(*source_spell_id),
                *effect_index,
                spell_id,
            )
        });

        if !affects || aura.on != AuraOn::Player {
            continue;
        }

        let &local =
            aura_by_id
                .get(&aura.aura_id)
                .ok_or(RotationPlanError::UnresolvedCastAura {
                    spell_id: spell.spell_id,
                    kind: "stance exception",
                    aura_id: aura.aura_id,
                })?;
        let key = AuraKey::new(
            AuraIdx(aura.aura_id),
            ActorId::Player,
            ActorId::Player,
            AuraOn::Player,
        );

        if let Some(binding) = bindings.aura(local, key) {
            stance_exception_handles.push(binding.handle);
        }
    }

    for driver in passive_driver_effects {
        let crate::state::BuffEffect::SpellStanceMaskFromEffect {
            source_spell_id,
            effect_index,
        } = &driver.effect
        else {
            continue;
        };

        passive_stance_exception |= data.effect_affects_spell(
            SpellIdx::from_raw(*source_spell_id),
            *effect_index,
            spell_id,
        );
    }

    let stance_exceptions = cast_handle_range(stance_start, stance_exception_handles.len())?;
    let interrupt_flags = wowlab_engine_domain::dbc::SpellInterruptFlags::from_dbc(
        data.spell_interrupt_flags(spell_id).unwrap_or_default(),
    );
    let channel_interrupt_flags = wowlab_engine_domain::dbc::SpellAuraInterruptFlags::from_dbc(
        data.channel_interrupt_flags(spell_id).unwrap_or_default(),
    );

    Ok(CastProfile {
        local,
        spell_id: spell.spell_id,
        hostile_min_range: data.hostile_min_range(spell_id).unwrap_or(0.0),
        hostile_max_range: data.hostile_max_range(spell_id).unwrap_or(0.0),
        requires_hostile_target: wowlab_engine_domain::dbc::SpellCastTargetFlags::from_bits_retain(
            spell.targeting.required_explicit_target_mask,
        )
        .requires_hostile_unit(),
        ignores_line_of_sight: data.ignores_line_of_sight(spell_id).unwrap_or(false),
        school_mask: SpellSchoolMask::from_dbc(data.school_mask(spell_id).unwrap_or_default()),
        damage_pushback: interrupt_flags
            .contains(wowlab_engine_domain::dbc::SpellInterruptFlags::DAMAGE_PUSHBACK)
            || interrupt_flags.contains(
                wowlab_engine_domain::dbc::SpellInterruptFlags::DAMAGE_PUSHBACK_PLAYER_ONLY,
            ),
        channel_duration_pushback: channel_interrupt_flags
            .contains(wowlab_engine_domain::dbc::SpellAuraInterruptFlags::DAMAGE_CHANNEL_DURATION),
        main_hand_available: data.main_hand().speed_ms != 0,
        off_hand_available: data.off_hand().is_some(),
        equipped_item_matches,
        primary_resource: primary_resource_type.and_then(|resource| bindings.resource(resource)),
        secondary_resource: secondary_resource_type
            .and_then(|resource| bindings.resource(resource)),
        gating_aura,
        cost_bypass_aura,
        cooldown_bypass_aura,
        consume_aura_on_cast,
        max_empower_aura,
        instant_cast_aura,
        channel_tick_cost_aura,
        channel_tick_damage_aura,
        required_caster_aura,
        required_target_aura,
        excluded_caster_aura,
        excluded_target_aura,
        aura_states: CastAuraStateProfile {
            required_caster: spell.requirements.caster_aura_state,
            required_target: spell.requirements.target_aura_state,
            excluded_caster: spell.requirements.exclude_caster_aura_state,
            excluded_target: spell.requirements.exclude_target_aura_state,
        },
        shapeshift_required_mask: spell.requirements.shapeshift_required_mask,
        shapeshift_excluded_mask: spell.requirements.shapeshift_excluded_mask,
        allow_while_unshifted: spell.requirements.form.allow_while_unshifted,
        requires_unshifted: spell.requirements.availability.requires_unshifted,
        requires_stealth: spell.requirements.form.requires_stealth,
        stance_exceptions,
        passive_stance_exception,
    })
}

// #t(fn: rust_large_fn_params) cold aura binding keeps the diagnostic identity and every finalized binding input explicit.
#[expect(
    clippy::too_many_arguments,
    reason = "cold aura binding keeps validation and destination inputs explicit"
)]
fn bind_signed_cast_aura(
    spell: &SpellData,
    kind: &'static str,
    raw_aura_id: i32,
    expected_on: AuraOn,
    auras: &[AuraData],
    aura_by_id: &IntMap<u32, LocalAuraIdx>,
    bindings: &BufferBindings,
    enemy_count: usize,
    target_aura_handles: &mut Vec<AuraSlotHandle>,
) -> Result<Option<CastAuraRequirement>, RotationPlanError> {
    if raw_aura_id <= 0 {
        return Ok(None);
    }

    let aura_id = u32::try_from(raw_aura_id)
        .ok()
        .ok_or(RotationPlanError::UnresolvedCastAura {
            spell_id: spell.spell_id,
            kind,
            aura_id: 0,
        })?;

    bind_cast_aura(
        spell,
        kind,
        aura_id,
        1,
        Some(expected_on),
        auras,
        aura_by_id,
        bindings,
        enemy_count,
        target_aura_handles,
    )
}

// #t(fn: rust_large_fn_params) cold aura binding keeps definition, actor, encounter, binding, and destination inputs explicit.
#[expect(
    clippy::too_many_arguments,
    reason = "cold aura binding keeps validation and destination inputs explicit"
)]
fn bind_cast_aura(
    spell: &SpellData,
    kind: &'static str,
    aura_id: u32,
    min_stacks: u8,
    expected_on: Option<AuraOn>,
    auras: &[AuraData],
    aura_by_id: &IntMap<u32, LocalAuraIdx>,
    bindings: &BufferBindings,
    enemy_count: usize,
    target_aura_handles: &mut Vec<AuraSlotHandle>,
) -> Result<Option<CastAuraRequirement>, RotationPlanError> {
    if aura_id == 0 {
        return Ok(None);
    }

    let &local = aura_by_id
        .get(&aura_id)
        .ok_or(RotationPlanError::UnresolvedCastAura {
            spell_id: spell.spell_id,
            kind,
            aura_id,
        })?;
    let aura = auras
        .get(local.as_usize())
        .ok_or(RotationPlanError::UnresolvedCastAura {
            spell_id: spell.spell_id,
            kind,
            aura_id,
        })?;

    if expected_on.is_some_and(|expected| aura.on != expected)
        || !matches!(aura.on, AuraOn::Player | AuraOn::Target)
    {
        return Err(RotationPlanError::UnsupportedCastAura {
            spell_id: spell.spell_id,
            kind,
            aura_id,
            on: aura.on,
        });
    }

    let coordinate = match aura.on {
        AuraOn::Player => {
            let key = AuraKey::new(
                AuraIdx(aura_id),
                ActorId::Player,
                ActorId::Player,
                AuraOn::Player,
            );
            let handle = bindings
                .aura(local, key)
                .ok_or(RotationPlanError::MissingCastAuraBinding {
                    spell_id: spell.spell_id,
                    kind,
                    aura_id,
                })?
                .handle;

            CastAuraCoordinate::Player(handle)
        }
        AuraOn::Target => {
            let offset = target_aura_handles.len();

            for index in 0..enemy_count {
                let enemy = EnemyIdx::from_raw(
                    u16::try_from(index)
                        .ok()
                        .ok_or(RotationPlanError::CastAuraRangeOverflow)?,
                );
                let key = AuraKey::new(
                    AuraIdx(aura_id),
                    ActorId::Player,
                    ActorId::Enemy(enemy),
                    AuraOn::Target,
                );
                let handle = bindings
                    .aura(local, key)
                    .ok_or(RotationPlanError::MissingCastAuraBinding {
                        spell_id: spell.spell_id,
                        kind,
                        aura_id,
                    })?
                    .handle;

                target_aura_handles.push(handle);
            }

            CastAuraCoordinate::Target {
                offset: u32::try_from(offset)
                    .ok()
                    .ok_or(RotationPlanError::CastAuraRangeOverflow)?,
                len: u16::try_from(enemy_count)
                    .ok()
                    .ok_or(RotationPlanError::CastAuraRangeOverflow)?,
            }
        }
        AuraOn::Pet => unreachable!("unsupported pet cast aura was rejected before binding"),
    };

    Ok(Some(CastAuraRequirement {
        aura_id,
        local,
        coordinate,
        min_stacks,
    }))
}

fn cast_handle_range(start: usize, end: usize) -> Result<CastAuraHandleRange, RotationPlanError> {
    Ok(CastAuraHandleRange {
        offset: u32::try_from(start)
            .ok()
            .ok_or(RotationPlanError::CastAuraRangeOverflow)?,
        len: u16::try_from(end.saturating_sub(start))
            .ok()
            .ok_or(RotationPlanError::CastAuraRangeOverflow)?,
    })
}

// #t(fn: rust_large_fn_params) cold spell binding joins stable definition, profile, aura, and buffer-coordinate tables.
fn bind_spell(
    spell: SpellIdx,
    spells: &[SpellData],
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    auras: &[AuraData],
    aura_by_id: &IntMap<u32, LocalAuraIdx>,
    bindings: &BufferBindings,
) -> Result<RotationSpellBinding, RotationPlanError> {
    let spell_id = spell.as_u32();
    let &local = spell_by_id
        .get(&spell_id)
        .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;
    let data = spells
        .get(local.as_usize())
        .ok_or(RotationPlanError::UnresolvedSpell { spell_id })?;

    if data.spell_id != spell_id {
        return Err(RotationPlanError::InconsistentSpell {
            spell_id,
            local: local.raw(),
            actual_spell_id: data.spell_id,
        });
    }

    let spell_slot = bindings.spell(local);
    let override_binding = bind_override(data, spells, spell_by_id, auras, aura_by_id, bindings)?;

    Ok(RotationSpellBinding {
        spell,
        local,
        spell_slot,
        override_binding,
    })
}

// #t(fn: rust_large_fn_params) cold override binding joins the base and replacement definition/profile/aura coordinate tables.
fn bind_override(
    data: &SpellData,
    spells: &[SpellData],
    spell_by_id: &IntMap<u32, LocalSpellIdx>,
    auras: &[AuraData],
    aura_by_id: &IntMap<u32, LocalAuraIdx>,
    bindings: &BufferBindings,
) -> Result<Option<RotationOverrideBinding>, RotationPlanError> {
    let spell_id = data.spell_id;
    let has_override_aura = data.overrides.aura_id != 0;
    let has_override_spell = data.overrides.spell_id != 0;

    if has_override_aura != has_override_spell {
        return Err(RotationPlanError::InconsistentOverride { spell_id });
    }

    if !has_override_spell {
        return Ok(None);
    }

    let override_spell_id = data.overrides.spell_id;
    let aura_id = data.overrides.aura_id;
    let &aura_local = aura_by_id
        .get(&aura_id)
        .ok_or(RotationPlanError::UnresolvedOverrideAura { spell_id, aura_id })?;
    let aura = auras
        .get(aura_local.as_usize())
        .ok_or(RotationPlanError::UnresolvedOverrideAura { spell_id, aura_id })?;

    if aura.aura_id != aura_id || aura.on != AuraOn::Player {
        return Err(RotationPlanError::UnsupportedOverrideAura { spell_id, aura_id });
    }

    let aura_key = AuraKey::new(
        AuraIdx(aura_id),
        ActorId::Player,
        ActorId::Player,
        AuraOn::Player,
    );
    let aura_handle = bindings
        .aura(aura_local, aura_key)
        .ok_or(RotationPlanError::UnresolvedOverrideAura { spell_id, aura_id })?
        .handle;
    let &effective_local =
        spell_by_id
            .get(&override_spell_id)
            .ok_or(RotationPlanError::UnresolvedOverride {
                spell_id,
                override_spell_id,
            })?;
    let effective =
        spells
            .get(effective_local.as_usize())
            .ok_or(RotationPlanError::UnresolvedOverride {
                spell_id,
                override_spell_id,
            })?;

    if effective.spell_id != override_spell_id {
        return Err(RotationPlanError::InconsistentSpell {
            spell_id: override_spell_id,
            local: effective_local.raw(),
            actual_spell_id: effective.spell_id,
        });
    }

    Ok(Some(RotationOverrideBinding {
        aura_to_consume: (!data.overrides.preserves_aura).then_some(aura_local),
        aura_min_stacks: data.overrides.aura_min_stacks,
        aura_handle,
        effective_local,
        shares_base_cooldown: data.overrides.shares_base_cooldown,
    }))
}

#[cfg(test)]
#[path = "rotation/tests.rs"]
mod tests;