wowlab_engine_combat/state/runtime/

auras.rs

//! Revision-aware semantic mutation of finalized aura instances.

#[cfg(feature = "rotation-optimizations")]
use std::num::NonZeroU64;

use wowlab_engine_domain::rotation::{AuraSlot, AuraTransferState as BufferAuraTransferState};
#[cfg(test)]
use wowlab_types::sim::AuraKey;
use wowlab_types::sim::{ActorId, PetIdx, SimTime};

use super::CombatInstance;
#[cfg(feature = "rotation-optimizations")]
use super::{RotationMutationDirection, RotationSemanticMutation};
use crate::state::{CombatProgram, program::ConcreteAuraBinding};

const AURA_SLOT_FLOAT_FIELDS: usize = 12;
const AURA_SLOT_INTEGER_FIELDS: usize = 4;
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_FIXED_ACTOR_COUNT: usize = 2;
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_PLAYER_INDEX: usize = 0;
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_EXTERNAL_INDEX: usize = 1;
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_PET_START: usize = ACTIVE_FIXED_ACTOR_COUNT;
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_SUMMARY_WORD: &str = "active aura summary points to its actor bitset";
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_NONEMPTY_WORD: &str = "active aura summary points to a nonempty actor word";
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_LOCAL_GROUP: &str = "active local bit belongs to the local-group lookup";
#[cfg(feature = "rotation-optimizations")]
const ACTIVE_CONCRETE_GROUP: &str = "active local lookup points to its concrete group";

#[derive(Debug)]
pub(super) struct AuraTotalsRevisions {
    player: u64,
    external: u64,
    pets: Box<[u64]>,
    enemies: Box<[u64]>,
    buff_cache_generation: u64,
    player_scaling: u64,
}

#[derive(Debug)]
#[cfg(feature = "rotation-optimizations")]
pub(super) struct ActiveAuraBindings {
    actors: Box<[ActiveAuraActor]>,
    coordinates: Box<[(usize, usize, usize)]>,
    enemy_count: usize,
}

#[derive(Debug)]
#[cfg(feature = "rotation-optimizations")]
struct ActiveAuraActor {
    groups: Box<[ActiveAuraSet]>,
    local_groups: Box<[ActiveAuraLocalGroup]>,
    active_locals: Box<[u64]>,
}

#[derive(Clone, Copy, Debug)]
#[cfg(feature = "rotation-optimizations")]
struct ActiveAuraLocalGroup {
    group_index: u16,
    static_totals_mask: u16,
}

#[cfg(feature = "rotation-optimizations")]
struct ActiveAuraCoordinateSink<'a> {
    coordinates: &'a mut [(usize, usize, usize)],
    actor_index: usize,
}

#[derive(Debug)]
#[cfg(feature = "rotation-optimizations")]
struct ActiveAuraSet {
    local: crate::state::LocalAuraIdx,
    bindings: Box<[ConcreteAuraBinding]>,
    words: Box<[u64]>,
    summary: Box<[u64]>,
}

#[cfg(feature = "rotation-optimizations")]
impl ActiveAuraSet {
    fn new(local: crate::state::LocalAuraIdx, bindings: Vec<ConcreteAuraBinding>) -> Self {
        let word_count = bindings.len().div_ceil(u64::BITS as usize);

        Self {
            local,
            bindings: bindings.into_boxed_slice(),
            words: vec![0; word_count].into_boxed_slice(),
            summary: vec![0; word_count.div_ceil(u64::BITS as usize)].into_boxed_slice(),
        }
    }

    fn set_occupied(&mut self, index: usize, occupied: bool) {
        let word_index = index / u64::BITS as usize;
        let word = self
            .words
            .get_mut(word_index)
            .expect("active aura binding index belongs to its actor bitset");
        let bit = 1_u64 << index % u64::BITS as usize;

        if occupied {
            *word |= bit;
        } else {
            *word &= !bit;
        }

        let summary_word = self
            .summary
            .get_mut(word_index / u64::BITS as usize)
            .expect("active aura word belongs to its summary bitset");
        let summary_bit = 1_u64 << word_index % u64::BITS as usize;

        if *word == 0 {
            *summary_word &= !summary_bit;
        } else {
            *summary_word |= summary_bit;
        }
    }

    fn is_empty(&self) -> bool {
        self.summary.iter().all(|word| *word == 0)
    }

    fn for_each(&self, mut visit: impl FnMut(ConcreteAuraBinding)) {
        for (summary_index, &summary) in self.summary.iter().enumerate() {
            let mut nonempty_words = summary;

            while nonempty_words != 0 {
                let word_bit = nonempty_words.trailing_zeros() as usize;
                let word_index = summary_index * u64::BITS as usize + word_bit;
                let mut occupied = self
                    .words
                    .get(word_index)
                    .copied()
                    .expect(ACTIVE_SUMMARY_WORD);

                nonempty_words &= nonempty_words - 1;

                while occupied != 0 {
                    let binding_bit = occupied.trailing_zeros() as usize;

                    occupied &= occupied - 1;
                    let index = word_index * u64::BITS as usize + binding_bit;

                    let binding = self
                        .bindings
                        .get(index)
                        .copied()
                        .expect("occupied active aura bit has a concrete binding");

                    visit(binding);
                }
            }
        }
    }

    fn pop_first(&mut self) -> Option<ConcreteAuraBinding> {
        let (summary_index, summary) = self
            .summary
            .iter()
            .copied()
            .enumerate()
            .find(|(_, word)| *word != 0)?;
        let word_index = summary_index * u64::BITS as usize + summary.trailing_zeros() as usize;
        let occupied = NonZeroU64::new(
            self.words
                .get(word_index)
                .copied()
                .expect(ACTIVE_SUMMARY_WORD),
        )
        .expect(ACTIVE_NONEMPTY_WORD);
        let index = word_index * u64::BITS as usize + occupied.trailing_zeros() as usize;
        let binding = self
            .bindings
            .get(index)
            .copied()
            .expect("occupied active aura bit has a concrete binding");

        self.set_occupied(index, false);

        Some(binding)
    }

    fn first(&self) -> Option<ConcreteAuraBinding> {
        let (summary_index, summary) = self
            .summary
            .iter()
            .copied()
            .enumerate()
            .find(|(_, word)| *word != 0)?;
        let word_index = summary_index * u64::BITS as usize + summary.trailing_zeros() as usize;
        let occupied = NonZeroU64::new(
            self.words
                .get(word_index)
                .copied()
                .expect(ACTIVE_SUMMARY_WORD),
        )
        .expect(ACTIVE_NONEMPTY_WORD);
        let index = word_index * u64::BITS as usize + occupied.trailing_zeros() as usize;

        self.bindings.get(index).copied()
    }
}

#[cfg(feature = "rotation-optimizations")]
impl ActiveAuraActor {
    fn new(
        local_bindings: Vec<Vec<ConcreteAuraBinding>>,
        coordinates: ActiveAuraCoordinateSink<'_>,
        static_total_plan: &crate::state::program::ActiveAuraEffectPlan,
    ) -> Self {
        let ActiveAuraCoordinateSink {
            coordinates,
            actor_index,
        } = coordinates;
        let aura_count = local_bindings.len();
        let mut groups = Vec::new();
        let mut local_groups = vec![
            ActiveAuraLocalGroup {
                group_index: u16::MAX,
                static_totals_mask: 0,
            };
            aura_count
        ];

        for (raw_local, bindings) in local_bindings.into_iter().enumerate() {
            if bindings.is_empty() {
                continue;
            }

            let local = crate::state::LocalAuraIdx::new(
                u8::try_from(raw_local).expect("finalized aura count fits the local identity"),
            );
            let group_index = groups.len();

            *local_groups
                .get_mut(raw_local)
                .expect("enumerated local belongs to the local-group lookup") =
                ActiveAuraLocalGroup {
                    group_index: u16::try_from(group_index)
                        .expect("active aura group count fits the finalized local identity"),
                    static_totals_mask: static_total_plan.mask(local),
                };

            for (binding_index, binding) in bindings.iter().copied().enumerate() {
                *coordinates
                    .get_mut(binding.index().as_usize())
                    .expect("concrete binding index belongs to this registry") =
                    (actor_index, group_index, binding_index);
            }

            groups.push(ActiveAuraSet::new(local, bindings));
        }

        Self {
            groups: groups.into_boxed_slice(),
            local_groups: local_groups.into_boxed_slice(),
            active_locals: vec![0; aura_count.div_ceil(u64::BITS as usize)].into_boxed_slice(),
        }
    }

    fn set_occupied(&mut self, group_index: usize, binding_index: usize, occupied: bool) {
        let group = self
            .groups
            .get_mut(group_index)
            .expect("active aura group belongs to its actor");

        group.set_occupied(binding_index, occupied);

        let local = group.local.as_usize();
        let word = self
            .active_locals
            .get_mut(local / u64::BITS as usize)
            .expect("active aura local belongs to the finalized local bitset");
        let bit = 1_u64 << local % u64::BITS as usize;

        if group.is_empty() {
            *word &= !bit;
        } else {
            *word |= bit;
        }
    }

    fn for_each_intersection(
        &self,
        relevant: (&[u64], &[u64]),
        mut visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding),
    ) {
        let (left_relevant, right_relevant) = relevant;

        for (word_index, &active) in self.active_locals.iter().enumerate() {
            let relevant = left_relevant.get(word_index).copied().unwrap_or(0)
                | right_relevant.get(word_index).copied().unwrap_or(0);
            let mut matching = active & relevant;

            while matching != 0 {
                let bit = matching.trailing_zeros() as usize;
                let raw_local = word_index * u64::BITS as usize + bit;
                let local_group = self.local_groups.get(raw_local).expect(ACTIVE_LOCAL_GROUP);
                let group = self
                    .groups
                    .get(usize::from(local_group.group_index))
                    .expect(ACTIVE_CONCRETE_GROUP);

                matching &= matching - 1;
                group.for_each(|binding| visit(group.local, binding));
            }
        }
    }

    fn for_each_static_total(
        &self,
        relevant: &[u64],
        mut visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding, u16),
    ) {
        for (word_index, &active) in self.active_locals.iter().enumerate() {
            let mut matching = active & relevant.get(word_index).copied().unwrap_or(0);

            while matching != 0 {
                let bit = matching.trailing_zeros() as usize;
                let raw_local = word_index * u64::BITS as usize + bit;
                let local_group = self.local_groups.get(raw_local).expect(ACTIVE_LOCAL_GROUP);
                let group = self
                    .groups
                    .get(usize::from(local_group.group_index))
                    .expect(ACTIVE_CONCRETE_GROUP);

                matching &= matching - 1;
                debug_assert_ne!(
                    local_group.static_totals_mask, 0,
                    "static-total relevant local carries a nonzero prebound effect mask"
                );
                group.for_each(|binding| {
                    visit(group.local, binding, local_group.static_totals_mask);
                });
            }
        }
    }

    fn for_each_local(
        &self,
        local: crate::state::LocalAuraIdx,
        visit: impl FnMut(ConcreteAuraBinding),
    ) {
        let raw_local = local.as_usize();
        let active = self
            .active_locals
            .get(raw_local / u64::BITS as usize)
            .copied()
            .unwrap_or(0);

        if active & (1_u64 << raw_local % u64::BITS as usize) == 0 {
            return;
        }

        let local_group = self.local_groups.get(raw_local).expect(ACTIVE_LOCAL_GROUP);

        self.groups
            .get(usize::from(local_group.group_index))
            .expect(ACTIVE_CONCRETE_GROUP)
            .for_each(visit);
    }

    #[cfg(test)]
    fn for_each(&self, mut visit: impl FnMut(ConcreteAuraBinding)) {
        for group in &self.groups {
            group.for_each(&mut visit);
        }
    }

    fn pop_first(&mut self) -> Option<ConcreteAuraBinding> {
        let (word_index, word) = self
            .active_locals
            .iter()
            .copied()
            .enumerate()
            .find(|(_, word)| *word != 0)?;
        let raw_local = word_index * u64::BITS as usize + word.trailing_zeros() as usize;
        let local_group = self.local_groups.get(raw_local).expect(ACTIVE_LOCAL_GROUP);
        let group = self
            .groups
            .get_mut(usize::from(local_group.group_index))
            .expect(ACTIVE_CONCRETE_GROUP);
        let binding = group
            .pop_first()
            .expect("active aura local points to a nonempty concrete group");

        if group.is_empty() {
            *self
                .active_locals
                .get_mut(word_index)
                .expect("active local word was selected from this exact bitset") &=
                !(1_u64 << raw_local % u64::BITS as usize);
        }

        Some(binding)
    }

    fn first_intersection(&self, relevant: &[u64]) -> Option<ConcreteAuraBinding> {
        for (word_index, &active) in self.active_locals.iter().enumerate() {
            let matching = active & relevant.get(word_index).copied().unwrap_or(0);

            if matching == 0 {
                continue;
            }

            let raw_local = word_index * u64::BITS as usize + matching.trailing_zeros() as usize;
            let local_group = self.local_groups.get(raw_local).expect(ACTIVE_LOCAL_GROUP);

            return self
                .groups
                .get(usize::from(local_group.group_index))
                .expect(ACTIVE_CONCRETE_GROUP)
                .first();
        }

        None
    }
}

#[cfg(feature = "rotation-optimizations")]
impl ActiveAuraBindings {
    pub(super) fn new(
        bindings: &crate::state::BufferBindings,
        static_total_plan: &crate::state::program::ActiveAuraEffectPlan,
        enemy_count: usize,
    ) -> Self {
        let actor_count = ACTIVE_FIXED_ACTOR_COUNT + PetIdx::MAX + enemy_count;
        let aura_count = bindings.aura_local_count();
        let mut actor_bindings = vec![vec![Vec::new(); aura_count]; actor_count];
        let mut coordinates =
            vec![(usize::MAX, usize::MAX, usize::MAX); bindings.aura_binding_count()];

        for binding in bindings.aura_bindings() {
            let actor_index = active_actor_index(binding.key.affected(), enemy_count)
                .expect("concrete aura binding affected actor belongs to the finalized encounter");
            let bucket = actor_bindings
                .get_mut(actor_index)
                .and_then(|locals| locals.get_mut(binding.local.as_usize()))
                .expect("validated active aura actor and local indexes");

            bucket.push(binding);
        }

        let actors = actor_bindings
            .into_iter()
            .enumerate()
            .map(|(actor_index, locals)| {
                ActiveAuraActor::new(
                    locals,
                    ActiveAuraCoordinateSink {
                        coordinates: &mut coordinates,
                        actor_index,
                    },
                    static_total_plan,
                )
            })
            .collect();

        Self {
            actors,
            coordinates: coordinates.into_boxed_slice(),
            enemy_count,
        }
    }

    fn set_occupied(&mut self, binding: ConcreteAuraBinding, occupied: bool) {
        let &(actor_index, group_index, binding_index) = self
            .coordinates
            .get(binding.index().as_usize())
            .expect("concrete aura binding index belongs to the active registry");
        let actor = self
            .actors
            .get_mut(actor_index)
            .expect("concrete aura binding actor belongs to the active registry");

        actor.set_occupied(group_index, binding_index, occupied);
    }

    #[cfg(test)]
    fn for_each(&self, actor: ActorId, visit: impl FnMut(ConcreteAuraBinding)) {
        if let Some(index) = active_actor_index(actor, self.enemy_count)
            && let Some(bindings) = self.actors.get(index)
        {
            bindings.for_each(visit);
        }
    }

    fn for_each_intersection(
        &self,
        actor: ActorId,
        relevant: (&[u64], &[u64]),
        visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding),
    ) {
        if let Some(index) = active_actor_index(actor, self.enemy_count)
            && let Some(bindings) = self.actors.get(index)
        {
            bindings.for_each_intersection(relevant, visit);
        }
    }

    fn for_each_static_total(
        &self,
        actor: ActorId,
        relevant: &[u64],
        visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding, u16),
    ) {
        if let Some(index) = active_actor_index(actor, self.enemy_count)
            && let Some(bindings) = self.actors.get(index)
        {
            bindings.for_each_static_total(relevant, visit);
        }
    }

    fn for_each_local(
        &self,
        actor: ActorId,
        local: crate::state::LocalAuraIdx,
        visit: impl FnMut(ConcreteAuraBinding),
    ) {
        if let Some(index) = active_actor_index(actor, self.enemy_count)
            && let Some(bindings) = self.actors.get(index)
        {
            bindings.for_each_local(local, visit);
        }
    }

    fn pop_first(&mut self, actor: ActorId) -> Option<ConcreteAuraBinding> {
        let index = active_actor_index(actor, self.enemy_count)?;

        self.actors
            .get_mut(index)
            .expect("validated active aura actor index")
            .pop_first()
    }

    fn first_intersection(&self, actor: ActorId, relevant: &[u64]) -> Option<ConcreteAuraBinding> {
        let index = active_actor_index(actor, self.enemy_count)?;

        self.actors
            .get(index)
            .expect("validated active aura actor index")
            .first_intersection(relevant)
    }

    fn drain_actor(&mut self, actor: ActorId, mut visit: impl FnMut(ConcreteAuraBinding)) {
        while let Some(binding) = self.pop_first(actor) {
            visit(binding);
        }
    }

    fn drain_all(&mut self, mut visit: impl FnMut(ConcreteAuraBinding)) {
        for actor in &mut self.actors {
            while let Some(binding) = actor.pop_first() {
                visit(binding);
            }
        }
    }
}

#[cfg(feature = "rotation-optimizations")]
fn active_actor_index(actor: ActorId, enemy_count: usize) -> Option<usize> {
    match actor {
        ActorId::Player => Some(ACTIVE_PLAYER_INDEX),
        ActorId::External => Some(ACTIVE_EXTERNAL_INDEX),
        ActorId::Pet(pet) => {
            (pet.as_usize() < PetIdx::MAX).then_some(ACTIVE_PET_START + pet.as_usize())
        }
        ActorId::Enemy(enemy) => (enemy.as_usize() < enemy_count)
            .then_some(ACTIVE_PET_START + PetIdx::MAX + enemy.as_usize()),
    }
}

impl AuraTotalsRevisions {
    pub(super) fn new(enemy_count: usize) -> Self {
        Self {
            player: 0,
            external: 0,
            pets: vec![0; PetIdx::MAX].into_boxed_slice(),
            enemies: vec![0; enemy_count].into_boxed_slice(),
            buff_cache_generation: 0,
            player_scaling: 0,
        }
    }

    fn get(&self, actor: ActorId) -> Option<u64> {
        match actor {
            ActorId::Player => Some(self.player),
            ActorId::External => Some(self.external),
            ActorId::Pet(pet) => self.pets.get(pet.as_usize()).copied(),
            ActorId::Enemy(enemy) => self.enemies.get(enemy.as_usize()).copied(),
        }
    }

    fn get_mut(&mut self, actor: ActorId) -> Option<&mut u64> {
        match actor {
            ActorId::Player => Some(&mut self.player),
            ActorId::External => Some(&mut self.external),
            ActorId::Pet(pet) => self.pets.get_mut(pet.as_usize()),
            ActorId::Enemy(enemy) => self.enemies.get_mut(enemy.as_usize()),
        }
    }

    fn bump(&mut self, actor: ActorId) -> bool {
        let Some(revision) = self.get_mut(actor) else {
            return false;
        };

        *revision = revision.wrapping_add(1);

        if *revision == 0 {
            self.invalidate_all_buff_caches();

            return true;
        }

        false
    }

    fn invalidate_all_buff_caches(&mut self) {
        // Phase 4 installs the caches. The generation is already advanced here so a u64
        // actor-revision wrap can never make a future cached value appear current.
        self.buff_cache_generation = self.buff_cache_generation.wrapping_add(1);
    }

    fn bump_player_scaling(&mut self) -> bool {
        self.player_scaling = self.player_scaling.wrapping_add(1);

        self.player_scaling == 0
    }

    fn reset(&mut self) {
        self.player = 0;
        self.external = 0;
        self.pets.fill(0);
        self.enemies.fill(0);
        self.invalidate_all_buff_caches();
        self.bump_player_scaling();
    }

    fn reset_actor(&mut self, actor: ActorId) {
        if let Some(revision) = self.get_mut(actor) {
            *revision = 0;
        }

        self.invalidate_all_buff_caches();

        if actor == ActorId::Player {
            self.bump_player_scaling();
        }
    }
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct AuraActivation {
    pub(crate) expires_at: f64,
    pub(crate) base_duration: f64,
    pub(crate) stacks: i32,
    pub(crate) max_stacks: i32,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct AuraRefresh {
    pub(crate) expires_at: Option<f64>,
    pub(crate) stacks: i32,
}

#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(crate) struct AuraSchedule {
    pub(crate) next_tick: f64,
    pub(crate) tick_interval: f64,
    pub(crate) base_tick_interval: f64,
    pub(crate) time_rate_multiplier: f64,
    pub(crate) remaining_ticks: i32,
}

#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub(crate) struct AuraSnapshot {
    pub(crate) has_snapshot: bool,
    pub(crate) attack_power: f64,
    pub(crate) spell_power: f64,
    pub(crate) critical_chance: f64,
    pub(crate) versatility: f64,
    pub(crate) mastery_multiplier: f64,
    pub(crate) damage_multiplier: f64,
}

pub(crate) type AuraTransferState = BufferAuraTransferState;

/// One requested semantic or focused metadata mutation for a finalized aura binding.
#[derive(Clone, Copy, Debug)]
pub(crate) enum AuraMutation {
    Activate(AuraActivation),
    Refresh(AuraRefresh),
    Expire,
    SetStacks(i32),
    SetExpiry(f64),
    SetSchedule(AuraSchedule),
    SetNextTick(f64),
    SetTimeRate(f64),
    SetSnapshot(AuraSnapshot),
    Transfer(AuraTransferState),
    SetTiming {
        expires_at: f64,
        schedule: AuraSchedule,
    },
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct SlotState {
    floats: [u64; AURA_SLOT_FLOAT_FIELDS],
    integers: [i32; AURA_SLOT_INTEGER_FIELDS],
}

impl SlotState {
    fn capture(slot: &AuraSlot) -> Self {
        Self {
            floats: [
                slot.expires_at.to_bits(),
                slot.base_duration.to_bits(),
                slot.next_tick.to_bits(),
                slot.tick_interval.to_bits(),
                slot.base_tick_interval.to_bits(),
                slot.time_rate_multiplier.to_bits(),
                slot.snapshot_ap.to_bits(),
                slot.snapshot_sp.to_bits(),
                slot.snapshot_crit.to_bits(),
                slot.snapshot_vers.to_bits(),
                slot.snapshot_mastery_mult.to_bits(),
                slot.snapshot_damage_mult.to_bits(),
            ],
            integers: [
                slot.stacks,
                slot.max_stacks,
                slot.remaining_ticks,
                slot.snapshot_has,
            ],
        }
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
struct TotalsState {
    occupied: bool,
    stacks: i32,
    snapshot_has: i32,
    snapshot_ap: u64,
    snapshot_sp: u64,
    snapshot_crit: u64,
    snapshot_vers: u64,
    snapshot_mastery_mult: u64,
    snapshot_damage_mult: u64,
}

impl TotalsState {
    fn capture(slot: &AuraSlot) -> Self {
        Self {
            occupied: slot.is_occupied(),
            stacks: slot.stacks,
            snapshot_has: slot.snapshot_has,
            snapshot_ap: slot.snapshot_ap.to_bits(),
            snapshot_sp: slot.snapshot_sp.to_bits(),
            snapshot_crit: slot.snapshot_crit.to_bits(),
            snapshot_vers: slot.snapshot_vers.to_bits(),
            snapshot_mastery_mult: slot.snapshot_mastery_mult.to_bits(),
            snapshot_damage_mult: slot.snapshot_damage_mult.to_bits(),
        }
    }

    fn totals_changed(self, after: Self, snapshot_relevant: bool) -> bool {
        self.occupied != after.occupied
            || (after.occupied && self.stacks != after.stacks)
            || (after.occupied
                && snapshot_relevant
                && (self.snapshot_has != after.snapshot_has
                    || self.snapshot_ap != after.snapshot_ap
                    || self.snapshot_sp != after.snapshot_sp
                    || self.snapshot_crit != after.snapshot_crit
                    || self.snapshot_vers != after.snapshot_vers
                    || self.snapshot_mastery_mult != after.snapshot_mastery_mult
                    || self.snapshot_damage_mult != after.snapshot_damage_mult))
    }

    #[cfg(feature = "rotation-optimizations")]
    fn rotation_direction(self, after: Self) -> Option<RotationMutationDirection> {
        if self.occupied != after.occupied {
            return Some(if after.occupied {
                RotationMutationDirection::Rise
            } else {
                RotationMutationDirection::Fall
            });
        }

        if !after.occupied || self.stacks == after.stacks {
            return None;
        }

        Some(if after.stacks > self.stacks {
            RotationMutationDirection::Rise
        } else {
            RotationMutationDirection::Fall
        })
    }
}

#[cfg(feature = "rotation-optimizations")]
fn record_rotation_aura_state(
    instance: &mut CombatInstance,
    before: TotalsState,
    after: TotalsState,
    now: SimTime,
) {
    if let Some(direction) = before.rotation_direction(after) {
        instance.runtime.rotation_mutations.record_semantic(
            RotationSemanticMutation::AuraState,
            direction,
            now,
        );
    }
}

#[cfg(feature = "rotation-optimizations")]
fn record_rotation_aura_mutations(
    instance: &mut CombatInstance,
    before_slot: AuraSlot,
    after_slot: AuraSlot,
    before_totals: TotalsState,
    after_totals: TotalsState,
    now: SimTime,
) {
    record_rotation_aura_state(instance, before_totals, after_totals, now);

    if !before_slot.is_occupied()
        || !after_slot.is_occupied()
        || before_slot.expires_at.to_bits() == after_slot.expires_at.to_bits()
    {
        return;
    }

    let direction = if after_slot.expires_at > before_slot.expires_at {
        RotationMutationDirection::Rise
    } else {
        RotationMutationDirection::Fall
    };

    instance.runtime.rotation_mutations.record_semantic(
        RotationSemanticMutation::AuraTiming,
        direction,
        now,
    );
}

impl CombatProgram {
    #[expect(
        clippy::unused_self,
        reason = "the program method preserves provenance for program-bound aura bindings"
    )]
    pub(crate) fn capture_aura_transfer(
        &self,
        instance: &CombatInstance,
        binding: ConcreteAuraBinding,
    ) -> Option<AuraTransferState> {
        BufferAuraTransferState::capture(instance.buffer.aura_at(binding.handle))
    }

    /// Atomically mutates one concrete aura and dispatches all finalized consumers.
    pub(crate) fn mutate_aura(
        &self,
        instance: &mut CombatInstance,
        binding: ConcreteAuraBinding,
        mutation: AuraMutation,
        now: SimTime,
    ) -> bool {
        let masks = self.effects.aura(binding.local);
        let before_slot = *instance.buffer.aura_at(binding.handle);
        let before = SlotState::capture(&before_slot);
        let before_totals = TotalsState::capture(&before_slot);

        apply_mutation(instance, binding, mutation);

        let after_slot = *instance.buffer.aura_at(binding.handle);
        let after = SlotState::capture(&after_slot);

        if before == after {
            return false;
        }

        let after_totals = TotalsState::capture(&after_slot);

        #[cfg(feature = "rotation-optimizations")]
        record_rotation_aura_mutations(
            instance,
            before_slot,
            after_slot,
            before_totals,
            after_totals,
            now,
        );

        wowlab_types::bench_metrics::record_planned_aura_bindings(1);

        #[cfg(feature = "rotation-optimizations")]
        if before_totals.occupied != after_totals.occupied {
            instance
                .active_aura_bindings
                .set_occupied(binding, after_totals.occupied);
        }

        let classified_totals_change = masks.totals_relevant()
            && before_totals.totals_changed(after_totals, masks.snapshot_totals_relevant());

        if classified_totals_change && instance.aura_totals_revisions.bump(binding.key.affected()) {
            instance.buff_totals_caches.clear();
        }

        if classified_totals_change
            && binding.key.affected() == ActorId::Player
            && masks.player_scaling_relevant()
            && instance.aura_totals_revisions.bump_player_scaling()
        {
            instance.buff_totals_caches.clear_player_scaling();
        }

        self.mark_changed_aura_projections(instance, binding);

        if before_totals.occupied != after_totals.occupied
            || (after_totals.occupied && before_totals.stacks != after_totals.stacks)
            || classified_totals_change
        {
            self.dispatch_aura_consumers(instance, binding, now);
        }

        true
    }

    #[cfg(test)]
    #[expect(
        clippy::unused_self,
        reason = "the test query stays on the program API that owns aura revision semantics"
    )]
    pub(crate) fn aura_totals_revision(
        &self,
        instance: &CombatInstance,
        actor: ActorId,
    ) -> Option<u64> {
        instance.aura_totals_revisions.get(actor)
    }

    pub(crate) fn reset_aura_slots(
        &self,
        instance: &mut CombatInstance,
        token: crate::handler::AuraResetToken,
    ) {
        let scope = token.scope();

        #[cfg(feature = "rotation-optimizations")]
        {
            let active = &mut instance.active_aura_bindings;
            let buffer = &mut instance.buffer;
            let expire = |binding: ConcreteAuraBinding| {
                buffer
                    .aura_at(binding.handle)
                    .is_occupied()
                    .then_some(())
                    .expect("active aura registry contains only occupied concrete bindings");
                buffer.expire_aura_at(binding.handle);
            };

            match scope {
                crate::handler::AuraResetScope::All => active.drain_all(expire),
                crate::handler::AuraResetScope::Player => {
                    active.drain_actor(ActorId::Player, expire);
                }
            }
        }

        #[cfg(not(feature = "rotation-optimizations"))]
        for binding in self.buffer_bindings.aura_bindings() {
            let key = binding.key;
            let selected = match scope {
                crate::handler::AuraResetScope::All => true,
                crate::handler::AuraResetScope::Player => key.affected() == ActorId::Player,
            };

            if selected {
                instance.buffer.expire_aura_at(binding.handle);
            }
        }

        match scope {
            crate::handler::AuraResetScope::All => {
                instance.aura_totals_revisions.reset();
            }
            crate::handler::AuraResetScope::Player => {
                instance.aura_totals_revisions.reset_actor(ActorId::Player);
            }
        }

        instance.buff_totals_caches.clear();
        instance.buff_totals_caches.clear_player_scaling();
    }

    fn mark_changed_aura_projections(
        &self,
        instance: &mut CombatInstance,
        binding: ConcreteAuraBinding,
    ) {
        wowlab_types::bench_metrics::record_planned_aura_projection_bindings(
            self.aura_dependencies.projections(binding.local).len(),
        );

        for dependency in self.aura_dependencies.projections(binding.local) {
            let selected = self
                .aura_dependencies
                .projection_source(*dependency, instance.current_target());

            if selected == Some(binding.handle) {
                instance.mark_aura_projection_dirty(
                    self.aura_dependencies.projection_index(*dependency),
                );
            }
        }
    }

    fn dispatch_aura_consumers(
        &self,
        instance: &mut CombatInstance,
        binding: ConcreteAuraBinding,
        now: SimTime,
    ) {
        use crate::state::program::AuraDependencies as Dependency;

        let local = binding.local;
        let key = binding.key;
        let consumers = self.aura_dependencies.consumers(local);
        let planned_spell_bindings = self
            .aura_dependencies
            .gate_spells(local)
            .len()
            .saturating_add(self.aura_dependencies.cost_spells(local).len())
            .saturating_add(self.aura_dependencies.recharge_spells(local).len())
            .saturating_add(self.aura_dependencies.maximum_charge_spells(local).len());

        wowlab_types::bench_metrics::record_planned_aura_spell_bindings(planned_spell_bindings);

        crate::systems::refresh_spell_gates_for(
            self,
            instance,
            self.aura_dependencies.gate_spells(local),
        );
        crate::systems::refresh_spell_costs_for(
            self,
            instance,
            self.aura_dependencies.cost_spells(local),
        );
        crate::systems::refresh_recharge_rates_for(
            self,
            instance,
            now,
            self.aura_dependencies.recharge_spells(local),
        );
        crate::systems::refresh_maximum_charges_for(
            self,
            instance,
            now,
            self.aura_dependencies.maximum_charge_spells(local),
        );

        if consumers.contains(Dependency::STAMINA) {
            crate::systems::sync_player_health_from_stamina(self, instance);
        }

        if consumers.intersects(Dependency::MAXIMUM_RESOURCE | Dependency::RESOURCE_REGEN) {
            crate::systems::refresh_primary_resource_projection(self, instance, now);
        }

        if consumers.contains(Dependency::AURA_TIME) {
            crate::systems::refresh_aura_time_rates_for(
                self,
                instance,
                now,
                self.aura_dependencies
                    .aura_timing_bindings(local, key.affected()),
            );
        }

        if consumers.contains(Dependency::PLAYER_SPEED) && key.affected() == ActorId::Player {
            crate::systems::reproject_player_auto_attack_speeds(self, instance, now);
        }

        if consumers.intersects(Dependency::PET_STATS | Dependency::PRIMARY_STAT) {
            crate::systems::refresh_pet_stat_snapshots(self, instance);
        }

        if consumers.intersects(
            Dependency::PET_ACTIONS | Dependency::RESOURCE_REGEN | Dependency::COMPANION_SPEED,
        ) {
            crate::systems::refresh_pet_actions_after_aura_change(self, instance, now);
        }

        if consumers.contains(Dependency::COMPANION_SPEED) {
            crate::systems::reproject_pet_auto_attack_speeds(self, instance, now);
            crate::systems::reproject_guardian_action_speeds(self, instance, now);
        }

        if consumers.contains(Dependency::TARGET_RANGE) && key.affected() == ActorId::Player {
            instance.mark_projection_dirty(
                crate::state::ProjectionDirty::TARGET_IDENTITY_RANGE_TRAVEL,
                now,
            );
        }

        tracing::trace!(
            aura_id = key.aura().0,
            source = ?key.source(),
            affected = ?key.affected(),
            ?consumers,
            costs = self.aura_dependencies.cost_spells(local).len(),
            recharge = self.aura_dependencies.recharge_spells(local).len(),
            maximum_charges = self.aura_dependencies.maximum_charge_spells(local).len(),
            gates = self.aura_dependencies.gate_spells(local).len(),
            aura_timing = self.aura_dependencies.aura_timing(local).len(),
            projections = self.aura_dependencies.projections(local).len(),
            "AURA_MUTATION_DISPATCH"
        );
    }
}

fn apply_mutation(
    instance: &mut CombatInstance,
    binding: ConcreteAuraBinding,
    mutation: AuraMutation,
) {
    let handle = binding.handle;

    match mutation {
        AuraMutation::Activate(activation) => instance.buffer.activate_aura_at(
            handle,
            activation.expires_at,
            activation.base_duration,
            activation.stacks,
            activation.max_stacks,
        ),
        AuraMutation::Refresh(refresh) => {
            instance
                .buffer
                .refresh_aura_at(handle, refresh.expires_at, refresh.stacks);
        }
        AuraMutation::Expire => instance.buffer.expire_aura_at(handle),
        AuraMutation::SetStacks(stacks) => instance.buffer.set_aura_stacks_at(handle, stacks),
        AuraMutation::SetExpiry(expires_at) => {
            instance.buffer.set_aura_expiry_at(handle, expires_at);
        }
        AuraMutation::SetSchedule(schedule) => set_schedule(instance, handle, schedule),
        AuraMutation::SetNextTick(next_tick) => {
            instance.buffer.set_aura_next_tick_at(handle, next_tick);
        }
        AuraMutation::SetTimeRate(multiplier) => {
            instance.buffer.set_aura_time_rate_at(handle, multiplier);
        }
        AuraMutation::SetSnapshot(snapshot) => instance.buffer.set_aura_snapshot_at(
            handle,
            i32::from(snapshot.has_snapshot),
            snapshot.attack_power,
            snapshot.spell_power,
            snapshot.critical_chance,
            snapshot.versatility,
            snapshot.mastery_multiplier,
            snapshot.damage_multiplier,
        ),
        AuraMutation::Transfer(state) => instance.buffer.transfer_aura_at(handle, state),
        AuraMutation::SetTiming {
            expires_at,
            schedule,
        } => {
            instance.buffer.set_aura_expiry_at(handle, expires_at);
            set_schedule(instance, handle, schedule);
        }
    }
}

fn set_schedule(
    instance: &mut CombatInstance,
    handle: wowlab_engine_domain::rotation::AuraSlotHandle,
    schedule: AuraSchedule,
) {
    instance.buffer.set_aura_schedule_at(
        handle,
        schedule.next_tick,
        schedule.tick_interval,
        schedule.base_tick_interval,
        schedule.time_rate_multiplier,
        schedule.remaining_ticks,
    );
}

impl CombatInstance {
    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn pop_first_active_aura_binding(
        &mut self,
        actor: ActorId,
    ) -> Option<ConcreteAuraBinding> {
        self.active_aura_bindings.pop_first(actor)
    }

    #[cfg(all(test, feature = "rotation-optimizations"))]
    pub(crate) fn for_each_active_aura_binding(
        &self,
        actor: ActorId,
        visit: impl FnMut(ConcreteAuraBinding),
    ) {
        self.active_aura_bindings.for_each(actor, visit);
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn for_each_active_aura_intersection(
        &self,
        actor: ActorId,
        relevant: (&[u64], &[u64]),
        visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding),
    ) {
        self.active_aura_bindings
            .for_each_intersection(actor, relevant, visit);
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn for_each_active_static_total_aura(
        &self,
        actor: ActorId,
        relevant: &[u64],
        visit: impl FnMut(crate::state::LocalAuraIdx, ConcreteAuraBinding, u16),
    ) {
        self.active_aura_bindings
            .for_each_static_total(actor, relevant, visit);
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn for_each_active_aura_local(
        &self,
        actor: ActorId,
        local: crate::state::LocalAuraIdx,
        visit: impl FnMut(ConcreteAuraBinding),
    ) {
        self.active_aura_bindings
            .for_each_local(actor, local, visit);
    }

    #[cfg(feature = "rotation-optimizations")]
    pub(crate) fn first_active_aura_intersection(
        &self,
        actor: ActorId,
        relevant: &[u64],
    ) -> Option<ConcreteAuraBinding> {
        if relevant.is_empty() {
            return None;
        }

        self.active_aura_bindings
            .first_intersection(actor, relevant)
    }

    #[cfg(all(test, feature = "rotation-optimizations"))]
    pub(crate) fn test_only_active_static_total_auras(
        &self,
        actor: ActorId,
        relevant: &[u64],
    ) -> Vec<(crate::state::LocalAuraIdx, ConcreteAuraBinding, u16)> {
        let mut entries = Vec::new();

        self.for_each_active_static_total_aura(actor, relevant, |local, binding, mask| {
            entries.push((local, binding, mask));
        });

        entries
    }

    pub(crate) fn actor_aura_revision(&self, actor: ActorId) -> Option<u64> {
        self.aura_totals_revisions.get(actor)
    }

    #[cfg(all(test, feature = "rotation-optimizations"))]
    pub(crate) fn test_only_active_aura_locals(
        &self,
        actor: ActorId,
    ) -> Vec<crate::state::LocalAuraIdx> {
        let mut locals = Vec::new();

        self.for_each_active_aura_binding(actor, |binding| locals.push(binding.local));

        locals
    }

    pub(crate) fn player_scaling_revision(&self) -> u64 {
        self.aura_totals_revisions.player_scaling
    }

    pub(crate) fn cached_player_scaling_buffs(
        &self,
        revision: u64,
    ) -> Option<crate::state::buff_effect::PlayerScalingBuffs> {
        self.buff_totals_caches.player_scaling(revision)
    }

    pub(crate) fn cache_player_scaling_buffs(
        &self,
        revision: u64,
        buffs: crate::state::buff_effect::PlayerScalingBuffs,
    ) {
        self.buff_totals_caches
            .store_player_scaling(revision, buffs);
    }

    pub(crate) fn cached_actor_buff_totals(
        &self,
        actor: ActorId,
        revision: u64,
    ) -> Option<crate::state::BuffTotals> {
        self.buff_totals_caches.actor(actor, revision)
    }

    pub(crate) fn cache_actor_buff_totals(
        &self,
        actor: ActorId,
        revision: u64,
        totals: &crate::state::BuffTotals,
    ) {
        self.buff_totals_caches.store_actor(actor, revision, totals);
    }

    pub(crate) fn cached_actor_only_buff_totals(
        &self,
        actor: ActorId,
        revision: u64,
        owner_revision: u64,
    ) -> Option<crate::state::BuffTotals> {
        self.buff_totals_caches
            .actor_only(actor, revision, owner_revision)
    }

    pub(crate) fn cache_actor_only_buff_totals(
        &self,
        actor: ActorId,
        revision: u64,
        owner_revision: u64,
        totals: &crate::state::BuffTotals,
    ) {
        self.buff_totals_caches
            .store_actor_only(actor, revision, owner_revision, totals);
    }
}

#[cfg(test)]
impl CombatInstance {
    pub(crate) fn test_only_set_aura_revision(&mut self, actor: ActorId, revision: u64) {
        if let Some(current) = self.aura_totals_revisions.get_mut(actor) {
            *current = revision;
        }
    }

    pub(crate) fn test_only_buff_cache_generation(&self) -> u64 {
        self.aura_totals_revisions.buff_cache_generation
    }
}

/// Independent full-scan oracle for tests of the incremental actor revision contract.
#[cfg(test)]
fn reference_recompute_actor_totals_state(
    program: &CombatProgram,
    instance: &CombatInstance,
    actor: ActorId,
) -> Vec<(AuraKey, i32, Option<[u64; 7]>)> {
    program
        .buffer_bindings
        .aura_bindings()
        .filter(|binding| binding.key.affected() == actor)
        .filter_map(|binding| {
            let masks = program.effects.aura(binding.local);
            let slot = instance.buffer.aura_at(binding.handle);

            if !masks.totals_relevant() || !slot.is_occupied() {
                return None;
            }

            let snapshot = masks.snapshot_totals_relevant().then(|| {
                [
                    u64::from(slot.snapshot_has != 0),
                    slot.snapshot_ap.to_bits(),
                    slot.snapshot_sp.to_bits(),
                    slot.snapshot_crit.to_bits(),
                    slot.snapshot_vers.to_bits(),
                    slot.snapshot_mastery_mult.to_bits(),
                    slot.snapshot_damage_mult.to_bits(),
                ]
            });

            Some((binding.key, slot.stacks, snapshot))
        })
        .collect()
}

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