wowlab_engine_combat/state/program/

aura_dependencies.rs

// #t(file: rust_duplicate_strings) finalization bound diagnostics deliberately share the same invariant wording across finalized plans.
// #t(file: rust_similar_fns) actor-range indexing intentionally mirrors the effect plan while retaining dependency-specific element types.
// #t(file: rust_similar_structs) graph entries and bound entries intentionally share semantic ranges across the explicit bind transition.

//! Finalized aura-to-consumer and aura-to-local-identity adjacency.

use std::ops::Range;

use wowlab_engine_domain::{
    dbc::{ResolvedGameDataSemanticExt as _, StatModifierKind},
    rotation::{AuraProjectionSlotHandle, AuraSlotHandle, ContextSchema, SpellSlotHandle},
};
use wowlab_types::{
    data::ResourceCostPercentBasis,
    game::Attribute,
    sim::{ActorId, AuraIdx, AuraKey, AuraOn, EnemyIdx, PetIdx, SpellIdx},
};

use super::{BufferBindings, ConcreteAuraBinding, ProgramConfig};
use crate::state::{
    AuraData, BuffEffect, LocalAuraIdx, LocalSpellIdx, SpellData, SpellEffectData, SpellGroupRule,
};

bitflags::bitflags! {
    /// Immediate non-projection work named by one finalized aura definition.
    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
    pub(crate) struct AuraDependencies: u16 {
        const GATES = 1 << 0;
        const PRIMARY_STAT = 1 << 1;
        const STAMINA = 1 << 2;
        const RECHARGE_RATE = 1 << 3;
        const MAXIMUM_CHARGES = 1 << 4;
        const AURA_TIME = 1 << 5;
        const PLAYER_SPEED = 1 << 6;
        const COMPANION_SPEED = 1 << 7;
        const MAXIMUM_RESOURCE = 1 << 8;
        const PET_STATS = 1 << 9;
        const RESOURCE_REGEN = 1 << 10;
        const PET_ACTIONS = 1 << 11;
        const TARGET_RANGE = 1 << 12;
    }
}

#[derive(Clone, Debug, Default)]
struct AuraDependencyEntry {
    consumers: AuraDependencies,
    costs: Range<usize>,
    recharge: Range<usize>,
    maximum_charges: Range<usize>,
    gates: Range<usize>,
    aura_timing: Range<usize>,
    projections: Range<usize>,
    exclusive_spells: Range<usize>,
}

#[derive(Clone, Debug, Default)]
struct AuraDependencyGraphEntry {
    consumers: AuraDependencies,
    costs: Range<usize>,
    recharge: Range<usize>,
    maximum_charges: Range<usize>,
    gates: Range<usize>,
    aura_timing: Range<usize>,
    exclusive_spells: Range<usize>,
}

#[derive(Clone, Copy, Debug)]
struct UnboundExclusiveSpellDependency {
    local: LocalSpellIdx,
    enabled: bool,
}

/// Layout-free flattened dependency adjacency compiled before rotation preparation.
#[derive(Debug)]
pub(crate) struct AuraDependencyGraph {
    entries: Box<[AuraDependencyGraphEntry]>,
    cost_spells: Box<[LocalSpellIdx]>,
    recharge_spells: Box<[LocalSpellIdx]>,
    maximum_charge_spells: Box<[LocalSpellIdx]>,
    gate_spells: Box<[LocalSpellIdx]>,
    aura_timing: Box<[LocalAuraIdx]>,
    exclusive_spells: Box<[UnboundExclusiveSpellDependency]>,
}

#[derive(Clone, Debug, Default)]
struct ConcreteAuraDependencyEntry {
    exclusive_peers: Range<usize>,
}

const FIXED_ACTOR_BUCKET_COUNT: usize = 2;

#[derive(Clone, Debug)]
struct ActorRanges<T> {
    entries: Box<[T]>,
    player: Range<usize>,
    external: Range<usize>,
    pets: Box<[Range<usize>]>,
    enemies: Box<[Range<usize>]>,
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct ControlPeerDependency {
    pub(crate) handle: AuraSlotHandle,
    pub(crate) matches_kind: bool,
    pub(crate) matches_group: bool,
    pub(crate) permanent: bool,
}

impl<T> ActorRanges<T> {
    fn for_actor(&self, actor: ActorId) -> &[T] {
        let range = match actor {
            ActorId::Player => Some(self.player.clone()),
            ActorId::External => Some(self.external.clone()),
            ActorId::Pet(pet) => self.pets.get(pet.as_usize()).cloned(),
            ActorId::Enemy(enemy) => self.enemies.get(enemy.as_usize()).cloned(),
        };

        range.map_or(&[], |range| {
            // BOUNDS: every actor range was assembled from this exact flattened element array.
            &self.entries[range]
        })
    }
}

impl<T> Default for ActorRanges<T> {
    fn default() -> Self {
        Self {
            entries: Box::default(),
            player: 0..0,
            external: 0..0,
            pets: Box::default(),
            enemies: Box::default(),
        }
    }
}

#[derive(Clone, Copy, Debug)]
pub(crate) struct ProjectionDependency {
    pub(crate) destination: AuraProjectionSlotHandle,
    source_offset: usize,
    index: AuraProjectionDependencyIdx,
}

/// Stable finalized identity for one aura projection dependency.
#[derive(Clone, Copy, Debug, Default, Eq, Ord, PartialEq, PartialOrd)]
pub(crate) struct AuraProjectionDependencyIdx(usize);

impl AuraProjectionDependencyIdx {
    #[expect(
        clippy::trivially_copy_pass_by_ref,
        reason = "C-CONV requires borrowed as_ receivers"
    )]
    pub(crate) const fn as_usize(&self) -> usize {
        self.0
    }
}

/// One exact spell-slot update for an applied exclusive-group aura.
#[derive(Clone, Copy, Debug)]
pub(crate) struct ExclusiveSpellDependency {
    pub(crate) handle: SpellSlotHandle,
    pub(crate) enabled: bool,
}

/// One exact finalized spell consumer and its construction-validated slot.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub(crate) struct SpellConsumerBinding {
    pub(crate) local: LocalSpellIdx,
    pub(crate) handle: SpellSlotHandle,
}

/// Flattened finalized dependency graph indexed by stable local aura identity.
#[derive(Debug)]
pub(crate) struct AuraDependencyPlan {
    entries: Box<[AuraDependencyEntry]>,
    concrete_entries: Box<[ConcreteAuraDependencyEntry]>,
    cost_spells: Box<[SpellConsumerBinding]>,
    recharge_spells: Box<[LocalSpellIdx]>,
    maximum_charge_spells: Box<[LocalSpellIdx]>,
    gate_spells: Box<[SpellConsumerBinding]>,
    aura_timing: Box<[LocalAuraIdx]>,
    aura_timing_bindings: Box<[ActorRanges<ConcreteAuraBinding>]>,
    control_peers: Box<[ActorRanges<ControlPeerDependency>]>,
    projections: Box<[ProjectionDependency]>,
    projection_sources: Box<[Option<AuraSlotHandle>]>,
    projection_target_count: usize,
    exclusive_peers: Box<[ConcreteAuraBinding]>,
    exclusive_spells: Box<[ExclusiveSpellDependency]>,
}

impl AuraDependencyGraph {
    // #t(fn: rust_max_fn_lines) the finalizer assembles every semantic dependency family in one local-aura transaction before layout freeze.
    // #t(fn: rust_cyclomatic_complexity) every BuffEffect selector contributes to an explicit finalized consumer family.
    // #t(fn: rust_large_fn_params) compilation explicitly receives the finalized definition and effect inputs whose identities it joins.
    pub(crate) fn compile(
        auras: &[AuraData],
        spells: &[SpellData],
        spell_effects: &[SpellEffectData],
        config: &ProgramConfig,
    ) -> Self {
        let mut entries = Vec::with_capacity(auras.len());
        let mut cost_spells = Vec::new();
        let mut recharge_spells = Vec::new();
        let mut maximum_charge_spells = Vec::new();
        let mut gate_spells = Vec::new();
        let mut aura_timing = Vec::new();
        let mut exclusive_spells = Vec::new();

        for (raw_local, aura) in auras.iter().enumerate() {
            let local = LocalAuraIdx::new(
                u8::try_from(raw_local).expect("finalized aura count is validated below 256"),
            );
            let mut consumers = AuraDependencies::empty();
            let mut local_costs = Vec::new();
            let mut local_recharge = Vec::new();
            let mut local_maximum_charges = Vec::new();
            let mut local_gates = Vec::new();
            let mut local_timing = Vec::new();

            for effect in aura.effects.iter().flatten() {
                classify_consumers(effect, config, &mut consumers);
                collect_cost_spells(effect, spells, config, &mut local_costs);
                collect_recharge_spells(effect, spells, config, &mut local_recharge);
                collect_maximum_charge_spells(effect, spells, &mut local_maximum_charges);
                collect_gate_spells(effect, spells, &mut local_gates);
                collect_aura_timing(effect, auras, config, &mut local_timing);
            }

            if consumers.contains(AuraDependencies::MAXIMUM_RESOURCE) {
                local_costs.extend(
                    spells
                        .iter()
                        .enumerate()
                        .filter(|&(_index, spell)| spell_uses_maximum_resource_cost(spell))
                        .map(|(index, _spell)| local_spell(index)),
                );
            }

            normalize(&mut local_costs);
            normalize(&mut local_recharge);
            normalize(&mut local_maximum_charges);
            normalize(&mut local_gates);
            normalize(&mut local_timing);

            let costs = append_range(&mut cost_spells, local_costs);
            let recharge = append_range(&mut recharge_spells, local_recharge);
            let maximum_charges = append_range(&mut maximum_charge_spells, local_maximum_charges);
            let gates = append_range(&mut gate_spells, local_gates);
            let aura_timing = append_range(&mut aura_timing, local_timing);
            let local_exclusive_spells =
                collect_exclusive_spell_dependencies(local, aura, auras, spells, spell_effects);
            let exclusive_spells = append_range(&mut exclusive_spells, local_exclusive_spells);

            entries.push(AuraDependencyGraphEntry {
                consumers,
                costs,
                recharge,
                maximum_charges,
                gates,
                aura_timing,
                exclusive_spells,
            });
        }

        Self {
            entries: entries.into_boxed_slice(),
            cost_spells: cost_spells.into_boxed_slice(),
            recharge_spells: recharge_spells.into_boxed_slice(),
            maximum_charge_spells: maximum_charge_spells.into_boxed_slice(),
            gate_spells: gate_spells.into_boxed_slice(),
            aura_timing: aura_timing.into_boxed_slice(),
            exclusive_spells: exclusive_spells.into_boxed_slice(),
        }
    }
}

impl AuraDependencyPlan {
    // #t(fn: rust_max_fn_lines) the finalizer assembles every dependency family in one auditable local-aura transaction.
    // #t(fn: rust_cyclomatic_complexity) every BuffEffect selector contributes to an explicit finalized consumer family.
    // #t(fn: rust_large_fn_params) compilation explicitly receives the finalized definition, effect, layout, binding, and encounter inputs it joins.
    pub(crate) fn bind(
        graph: AuraDependencyGraph,
        auras: &[AuraData],
        schema: &ContextSchema,
        bindings: &BufferBindings,
        enemy_count: usize,
    ) -> Self {
        let mut entries = Vec::with_capacity(auras.len());
        let cost_spells = bind_spell_consumers(graph.cost_spells.iter().copied(), bindings);
        let gate_spells = bind_spell_consumers(graph.gate_spells.iter().copied(), bindings);
        let mut projections = Vec::new();
        let mut projection_sources = Vec::new();
        let exclusive_spells = graph
            .exclusive_spells
            .iter()
            .map(|dependency| ExclusiveSpellDependency {
                handle: bindings.spell(dependency.local),
                enabled: dependency.enabled,
            })
            .collect::<Vec<_>>();
        let projection_target_count = enemy_count.saturating_add(1);

        for (aura, graph_entry) in auras.iter().zip(graph.entries.iter()) {
            let projection_start = projections.len();

            schema
                .buffer_finalizer()
                .visit_aura_projections(|projection, destination| {
                    if projection.aura().as_u32() != aura.aura_id || projection.on() != aura.on {
                        return;
                    }

                    let source_offset = projection_sources.len();

                    for target_index in 0..projection_target_count {
                        let target = (target_index > 0).then(|| {
                            EnemyIdx(
                                u16::try_from(target_index - 1)
                                    .expect("finalized enemy count fits in EnemyIdx"),
                            )
                        });
                        let source =
                            exact_projection_key(projection.aura(), projection.on(), target)
                                .and_then(|key| schema.buffer_finalizer().bind_aura(key));

                        projection_sources.push(source);
                    }

                    projections.push(ProjectionDependency {
                        destination,
                        source_offset,
                        index: AuraProjectionDependencyIdx(projections.len()),
                    });
                });

            let projection_range = projection_start..projections.len();

            entries.push(AuraDependencyEntry {
                consumers: graph_entry.consumers,
                costs: graph_entry.costs.start..graph_entry.costs.end,
                recharge: graph_entry.recharge.start..graph_entry.recharge.end,
                maximum_charges: graph_entry.maximum_charges.start..graph_entry.maximum_charges.end,
                gates: graph_entry.gates.start..graph_entry.gates.end,
                aura_timing: graph_entry.aura_timing.start..graph_entry.aura_timing.end,
                projections: projection_range,
                exclusive_spells: graph_entry.exclusive_spells.start
                    ..graph_entry.exclusive_spells.end,
            });
        }

        let (concrete_entries, exclusive_peers) = compile_exclusive_peers(auras, bindings);
        let aura_timing_bindings = entries
            .iter()
            .map(|entry| {
                // BOUNDS: entry timing ranges were appended to this exact flattened local array.
                let locals = &graph.aura_timing[entry.aura_timing.clone()];
                let bucket_count = FIXED_ACTOR_BUCKET_COUNT + PetIdx::MAX + enemy_count;
                let mut buckets = vec![Vec::new(); bucket_count];
                let mut local_membership = vec![false; auras.len()];

                for &local in locals {
                    // BOUNDS: timing locals were compiled from this finalized aura slice.
                    local_membership[local.as_usize()] = true;
                }

                for binding in bindings.aura_bindings() {
                    // BOUNDS: concrete bindings contain locals from this finalized aura slice.
                    if !local_membership[binding.local.as_usize()] {
                        continue;
                    }

                    if let Some(bucket) = concrete_actor_bucket(binding.key.affected(), enemy_count)
                    {
                        // BOUNDS: concrete_actor_bucket validates the returned bucket.
                        buckets[bucket].push(binding);
                    }
                }

                flatten_actor_buckets(buckets)
            })
            .collect();
        let control_peers = auras
            .iter()
            .map(|aura| {
                let bucket_count = FIXED_ACTOR_BUCKET_COUNT + PetIdx::MAX + enemy_count;
                let mut buckets = vec![Vec::new(); bucket_count];

                if let Some(control) = aura.crowd_control {
                    for binding in bindings.aura_bindings() {
                        // BOUNDS: concrete bindings contain local identities from this finalized aura slice.
                        let candidate = &auras[binding.local.as_usize()];
                        let Some(candidate_control) = candidate.crowd_control else {
                            continue;
                        };
                        let matches_kind = candidate_control.kind == control.kind;
                        let matches_group = control.diminishing
                            != wowlab_engine_domain::dbc::DiminishingGroup::None
                            && candidate_control.diminishing == control.diminishing;

                        if !(matches_kind || matches_group) {
                            continue;
                        }

                        if let Some(bucket) =
                            concrete_actor_bucket(binding.key.affected(), enemy_count)
                        {
                            // BOUNDS: concrete_actor_bucket validates the returned bucket.
                            buckets[bucket].push(ControlPeerDependency {
                                handle: binding.handle,
                                matches_kind,
                                matches_group,
                                permanent: candidate.base_duration_ms == 0,
                            });
                        }
                    }
                }

                flatten_actor_buckets(buckets)
            })
            .collect();

        Self {
            entries: entries.into_boxed_slice(),
            concrete_entries,
            cost_spells: cost_spells.into_boxed_slice(),
            recharge_spells: graph.recharge_spells,
            maximum_charge_spells: graph.maximum_charge_spells,
            gate_spells: gate_spells.into_boxed_slice(),
            aura_timing: graph.aura_timing,
            aura_timing_bindings,
            control_peers,
            projections: projections.into_boxed_slice(),
            projection_sources: projection_sources.into_boxed_slice(),
            projection_target_count,
            exclusive_peers,
            exclusive_spells: exclusive_spells.into_boxed_slice(),
        }
    }

    pub(crate) fn consumers(&self, aura: LocalAuraIdx) -> AuraDependencies {
        self.entry(aura).consumers
    }

    pub(crate) fn cost_spells(&self, aura: LocalAuraIdx) -> &[SpellConsumerBinding] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.cost_spells[self.entry(aura).costs.clone()]
    }

    pub(crate) fn recharge_spells(&self, aura: LocalAuraIdx) -> &[LocalSpellIdx] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.recharge_spells[self.entry(aura).recharge.clone()]
    }

    pub(crate) fn maximum_charge_spells(&self, aura: LocalAuraIdx) -> &[LocalSpellIdx] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.maximum_charge_spells[self.entry(aura).maximum_charges.clone()]
    }

    pub(crate) fn gate_spells(&self, aura: LocalAuraIdx) -> &[SpellConsumerBinding] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.gate_spells[self.entry(aura).gates.clone()]
    }

    pub(crate) fn aura_timing(&self, aura: LocalAuraIdx) -> &[LocalAuraIdx] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.aura_timing[self.entry(aura).aura_timing.clone()]
    }

    pub(crate) fn aura_timing_bindings(
        &self,
        aura: LocalAuraIdx,
        actor: ActorId,
    ) -> &[ConcreteAuraBinding] {
        // BOUNDS: local aura identities and concrete timing ranges share the finalized aura count.
        self.aura_timing_bindings[aura.as_usize()].for_actor(actor)
    }

    pub(crate) fn control_peers(
        &self,
        aura: LocalAuraIdx,
        actor: ActorId,
    ) -> &[ControlPeerDependency] {
        // BOUNDS: local aura identities and control-peer ranges share the finalized aura count.
        self.control_peers[aura.as_usize()].for_actor(actor)
    }

    pub(crate) fn projections(&self, aura: LocalAuraIdx) -> &[ProjectionDependency] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.projections[self.entry(aura).projections.clone()]
    }

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

    pub(crate) fn projection(&self, index: AuraProjectionDependencyIdx) -> ProjectionDependency {
        // BOUNDS: projection identities are created from this exact finalized slice.
        self.projections[index.as_usize()]
    }

    pub(crate) const fn projection_count(&self) -> usize {
        self.projections.len()
    }

    #[expect(
        clippy::unused_self,
        reason = "the plan retains authority over extracting its private dependency identity"
    )]
    pub(crate) fn projection_index(
        &self,
        dependency: ProjectionDependency,
    ) -> AuraProjectionDependencyIdx {
        dependency.index
    }

    pub(crate) fn exclusive_peers(&self, binding: ConcreteAuraBinding) -> &[ConcreteAuraBinding] {
        // BOUNDS: concrete binding ordinals and entries are finalized in the same stable order.
        let entry = &self.concrete_entries[binding.index().as_usize()];

        // BOUNDS: each range was appended to this exact flattened array during finalization.

        &self.exclusive_peers[entry.exclusive_peers.clone()]
    }

    pub(crate) fn exclusive_spells(&self, aura: LocalAuraIdx) -> &[ExclusiveSpellDependency] {
        // BOUNDS: each range was appended to this exact flattened array during finalization.
        &self.exclusive_spells[self.entry(aura).exclusive_spells.clone()]
    }

    pub(crate) fn projection_source(
        &self,
        dependency: ProjectionDependency,
        target: Option<EnemyIdx>,
    ) -> Option<AuraSlotHandle> {
        let target_index = target.map_or(0, |enemy| enemy.as_usize().saturating_add(1));

        if target_index >= self.projection_target_count {
            return None;
        }

        self.projection_sources
            .get(dependency.source_offset + target_index)
            .copied()
            .flatten()
    }

    pub(crate) fn validate(&self, aura_count: usize, spell_count: usize) -> bool {
        self.entries.len() == aura_count
            && self
                .concrete_entries
                .iter()
                .all(|entry| entry.exclusive_peers.end <= self.exclusive_peers.len())
            && self
                .cost_spells
                .iter()
                .all(|binding| binding.local.as_usize() < spell_count)
            && self
                .recharge_spells
                .iter()
                .all(|local| local.as_usize() < spell_count)
            && self
                .maximum_charge_spells
                .iter()
                .all(|local| local.as_usize() < spell_count)
            && self
                .gate_spells
                .iter()
                .all(|binding| binding.local.as_usize() < spell_count)
            && self
                .aura_timing
                .iter()
                .all(|local| local.as_usize() < aura_count)
            && self.aura_timing_bindings.len() == aura_count
            && self.control_peers.len() == aura_count
    }

    fn entry(&self, aura: LocalAuraIdx) -> &AuraDependencyEntry {
        // BOUNDS: local aura identities and dependency entries come from the same finalized slice.
        &self.entries[aura.as_usize()]
    }
}

fn concrete_actor_bucket(actor: ActorId, enemy_count: usize) -> Option<usize> {
    match actor {
        ActorId::Player => Some(0),
        ActorId::External => Some(1),
        ActorId::Pet(pet) => {
            (pet.as_usize() < PetIdx::MAX).then_some(FIXED_ACTOR_BUCKET_COUNT + pet.as_usize())
        }
        ActorId::Enemy(enemy) => (enemy.as_usize() < enemy_count)
            .then_some(FIXED_ACTOR_BUCKET_COUNT + PetIdx::MAX + enemy.as_usize()),
    }
}

fn flatten_actor_buckets<T>(buckets: Vec<Vec<T>>) -> ActorRanges<T> {
    let mut entries = Vec::new();
    let mut ranges = Vec::with_capacity(buckets.len());

    for bucket in buckets {
        let start = entries.len();

        entries.extend(bucket);
        ranges.push(start..entries.len());
    }

    // BOUNDS: the two fixed actor buckets always prefix the pet/enemy buckets.

    let player = ranges[0].clone();
    // BOUNDS: the two fixed actor buckets always prefix the pet/enemy buckets.
    let external = ranges[1].clone();
    let enemies_start = FIXED_ACTOR_BUCKET_COUNT + PetIdx::MAX;
    // BOUNDS: the bucket vector contains every fixed pet bucket.
    let pets = ranges[FIXED_ACTOR_BUCKET_COUNT..enemies_start]
        .to_vec()
        .into_boxed_slice();
    // BOUNDS: all remaining buckets belong to finalized enemies.
    let enemies = ranges[enemies_start..].to_vec().into_boxed_slice();

    ActorRanges {
        entries: entries.into_boxed_slice(),
        player,
        external,
        pets,
        enemies,
    }
}

fn append_range<T>(target: &mut Vec<T>, values: Vec<T>) -> Range<usize> {
    let start = target.len();

    target.extend(values);

    start..target.len()
}

fn bind_spell_consumers(
    locals: impl IntoIterator<Item = LocalSpellIdx>,
    bindings: &BufferBindings,
) -> Vec<SpellConsumerBinding> {
    locals
        .into_iter()
        .map(|local| SpellConsumerBinding {
            local,
            handle: bindings.spell(local),
        })
        .collect()
}

fn normalize<T>(values: &mut Vec<T>)
where
    T: Ord,
{
    values.sort_unstable();
    values.dedup();
}

fn compile_exclusive_peers(
    auras: &[AuraData],
    bindings: &BufferBindings,
) -> (
    Box<[ConcreteAuraDependencyEntry]>,
    Box<[ConcreteAuraBinding]>,
) {
    let mut entries = Vec::with_capacity(bindings.aura_bindings().count());
    let mut peers = Vec::new();

    for binding in bindings.aura_bindings() {
        let start = peers.len();
        // BOUNDS: concrete bindings contain local identities from this finalized aura slice.
        let group = auras[binding.local.as_usize()]
            .spell_group
            .filter(|group| group.rule == SpellGroupRule::Exclusive)
            .map(|group| group.group_idx);

        if let Some(group) = group {
            peers.extend(bindings.aura_bindings().filter(|candidate| {
                candidate.local != binding.local
                    && candidate.key.source() == binding.key.source()
                    && candidate.key.affected() == binding.key.affected()
                    // BOUNDS: concrete bindings contain local identities from this finalized aura slice.
                    && auras[candidate.local.as_usize()]
                        .spell_group
                        .is_some_and(|peer| {
                            peer.rule == SpellGroupRule::Exclusive && peer.group_idx == group
                        })
            }));
        }

        // BOUNDS: start was captured from this vector before only extending it.

        peers[start..].sort_unstable_by_key(|peer| peer.local);
        entries.push(ConcreteAuraDependencyEntry {
            exclusive_peers: start..peers.len(),
        });
    }

    (entries.into_boxed_slice(), peers.into_boxed_slice())
}

fn collect_exclusive_spell_dependencies(
    applied: LocalAuraIdx,
    aura: &AuraData,
    auras: &[AuraData],
    spells: &[SpellData],
    spell_effects: &[SpellEffectData],
) -> Vec<UnboundExclusiveSpellDependency> {
    let Some(group) = aura
        .spell_group
        .filter(|group| group.rule == SpellGroupRule::Exclusive)
        .map(|group| group.group_idx)
    else {
        return Vec::new();
    };
    let mut dependencies = Vec::new();

    for (index, spell) in spells.iter().enumerate() {
        let start = spell.followup_effects.start as usize;
        let len = usize::from(spell.followup_effects.len);
        let followups = (start..start.saturating_add(len)).filter_map(|effect_index| {
            match spell_effects.get(effect_index) {
                Some(SpellEffectData::ApplyAura { aura_local }) => Some(*aura_local),
                _ => None,
            }
        });
        let mut belongs_to_group = false;
        let mut enables_applied = false;

        for local in spell.applies_aura.into_iter().chain(followups) {
            // BOUNDS: applied-aura locals are finalized against this exact aura definition slice.
            let same_group = auras[local.as_usize()]
                .spell_group
                .is_some_and(|candidate| {
                    candidate.rule == SpellGroupRule::Exclusive && candidate.group_idx == group
                });

            belongs_to_group |= same_group;
            enables_applied |= same_group && local == applied;
        }

        if belongs_to_group {
            dependencies.push(UnboundExclusiveSpellDependency {
                local: local_spell(index),
                enabled: enables_applied,
            });
        }
    }

    dependencies
}

fn local_spell(index: usize) -> LocalSpellIdx {
    LocalSpellIdx::new(u8::try_from(index).expect("finalized spell count is validated below 256"))
}

// #t(fn: rust_cyclomatic_complexity) this exhaustive family classification is the auditable source for selective derived-state dispatch.
fn classify_consumers(
    effect: &BuffEffect,
    config: &ProgramConfig,
    consumers: &mut AuraDependencies,
) {
    use AuraDependencies as Dependency;

    match effect {
        BuffEffect::SpellGateFromEffect { .. } => *consumers |= Dependency::GATES,
        BuffEffect::PrimaryStat(..) | BuffEffect::PrimaryStatPercent(..) => {
            *consumers |= Dependency::PRIMARY_STAT | Dependency::PET_STATS;
        }
        BuffEffect::BonusStatPercent { stat, .. } => {
            let primary_matches = match config.base_stats.primary_attribute {
                Some(Attribute::Strength) => *stat == StatModifierKind::Strength,
                Some(Attribute::Agility) => *stat == StatModifierKind::Agility,
                Some(Attribute::Intellect) => *stat == StatModifierKind::Intellect,
                _ => false,
            };

            if primary_matches || matches!(stat, StatModifierKind::Primary | StatModifierKind::All)
            {
                *consumers |= Dependency::PRIMARY_STAT | Dependency::PET_STATS;
            }

            if matches!(stat, StatModifierKind::Stamina | StatModifierKind::All) {
                *consumers |= Dependency::STAMINA | Dependency::PET_STATS;
            }
        }
        BuffEffect::OverrideSpellPowerByAttackPowerPercent(..)
        | BuffEffect::OverrideAttackPowerBySpellPowerPercent(..)
        | BuffEffect::AttackPowerPercent(..) => *consumers |= Dependency::PET_STATS,
        BuffEffect::RechargeRatePercent(..)
        | BuffEffect::CooldownRechargeRateFromEffect { .. }
        | BuffEffect::ChargeRechargeRateCategory { .. }
        | BuffEffect::CooldownDurationPercent { .. } => {
            *consumers |= Dependency::RECHARGE_RATE;
        }
        BuffEffect::MaxChargesCategory(..) => *consumers |= Dependency::MAXIMUM_CHARGES,
        BuffEffect::AuraTimeRateFromEffect { .. } => *consumers |= Dependency::AURA_TIME,
        BuffEffect::Haste(..)
        | BuffEffect::HasteMult(..)
        | BuffEffect::HasteMultFromEffect { .. } => {
            *consumers |= Dependency::PLAYER_SPEED | Dependency::COMPANION_SPEED;

            if config.haste_regen {
                *consumers |= Dependency::RESOURCE_REGEN;
            }
        }
        BuffEffect::SpellCastSpeed(..) | BuffEffect::AttackSpeed(..) => {
            *consumers |= Dependency::COMPANION_SPEED;

            if matches!(effect, BuffEffect::AttackSpeed(..)) {
                *consumers |= Dependency::PLAYER_SPEED;
            }
        }
        BuffEffect::MaxResourceFlat(..) => *consumers |= Dependency::MAXIMUM_RESOURCE,
        BuffEffect::SpellTargetingFromEffect { property, .. }
            if *property == wowlab_engine_domain::dbc::ModifierPropertyKind::Range =>
        {
            *consumers |= Dependency::TARGET_RANGE;
        }
        BuffEffect::RegenPercent(..)
        | BuffEffect::DynamicRegenPercent(..)
        | BuffEffect::ResourceRegenPerFiveSeconds(..)
        | BuffEffect::InterruptRegen
        | BuffEffect::InterruptedRegenPercent(..)
        | BuffEffect::PreventResourceRegen(..) => {
            *consumers |= Dependency::RESOURCE_REGEN | Dependency::PET_ACTIONS;
        }
        _ => {}
    }
}

// #t(fn: rust_cyclomatic_complexity) exact cost dependency union intentionally keeps every resource, entry, label, class-mask, and additional-power selector visible.
fn collect_cost_spells(
    effect: &BuffEffect,
    spells: &[SpellData],
    config: &ProgramConfig,
    target: &mut Vec<LocalSpellIdx>,
) {
    match effect {
        BuffEffect::ResourceCostPercent(_, resource) => {
            for (index, spell) in spells.iter().enumerate() {
                if (config.base_stats.resource_type == Some(*resource)
                    && spell_has_primary_cost(spell, config))
                    || (config.base_stats.secondary_resource_type == Some(*resource)
                        && spell_has_secondary_cost(spell, config))
                {
                    target.push(local_spell(index));
                }
            }
        }
        BuffEffect::SpellCostPercent(_, spell_ids, _)
        | BuffEffect::SpellCostFlat(_, spell_ids, _) => {
            for (index, spell) in spells.iter().enumerate() {
                if spell_ids.contains(&spell.spell_id) {
                    target.push(local_spell(index));
                }
            }
        }
        BuffEffect::SpellCostFromEffect {
            source_spell_id,
            effect_index,
            cost_entry,
            ..
        } => {
            for (index, spell) in spells.iter().enumerate() {
                let spell_idx = spell.idx();
                let matching_entry = config.game_data.cost_entry(spell_idx, false) == *cost_entry
                    || config.game_data.cost_entry(spell_idx, true) == *cost_entry;

                if matching_entry
                    && config.game_data.effect_affects_spell(
                        SpellIdx::from_raw(*source_spell_id),
                        *effect_index,
                        spell_idx,
                    )
                {
                    target.push(local_spell(index));
                }
            }
        }
        BuffEffect::AdditionalPowerCostFromEffect {
            source_spell_id,
            effect_index,
            resource_type,
            ..
        } => {
            let matching_resource = config
                .base_stats
                .resource_type
                .is_some_and(|resource| i32::from(u8::from(resource)) == *resource_type)
                || config
                    .base_stats
                    .secondary_resource_type
                    .is_some_and(|resource| i32::from(u8::from(resource)) == *resource_type);

            if matching_resource {
                for (index, spell) in spells.iter().enumerate() {
                    if config.game_data.effect_affects_spell(
                        SpellIdx::from_raw(*source_spell_id),
                        *effect_index,
                        spell.idx(),
                    ) {
                        target.push(local_spell(index));
                    }
                }
            }
        }
        _ => {}
    }
}

fn collect_recharge_spells(
    effect: &BuffEffect,
    spells: &[SpellData],
    config: &ProgramConfig,
    target: &mut Vec<LocalSpellIdx>,
) {
    match effect {
        BuffEffect::Haste(..)
        | BuffEffect::HasteMult(..)
        | BuffEffect::HasteMultFromEffect { .. } => {
            target.extend(
                spells
                    .iter()
                    .enumerate()
                    .filter(|&(_index, spell)| {
                        spell.cooldown.has_cooldown && spell.cooldown.cooldown_hasted
                    })
                    .map(|(index, _spell)| local_spell(index)),
            );
        }
        BuffEffect::RechargeRatePercent(_, spell_ids) => {
            target.extend(
                spells
                    .iter()
                    .enumerate()
                    .filter(|&(_index, spell)| {
                        spell.cooldown.has_cooldown && spell_ids.contains(&spell.spell_id)
                    })
                    .map(|(index, _spell)| local_spell(index)),
            );
        }
        BuffEffect::CooldownRechargeRateFromEffect {
            source_spell_id,
            effect_index,
            ..
        }
        | BuffEffect::CooldownDurationPercent {
            source_spell_id,
            effect_index,
            ..
        } => {
            target.extend(
                spells
                    .iter()
                    .enumerate()
                    .filter(|&(_index, spell)| {
                        spell.cooldown.has_cooldown
                            && config.game_data.effect_affects_spell(
                                SpellIdx::from_raw(*source_spell_id),
                                *effect_index,
                                spell.idx(),
                            )
                    })
                    .map(|(index, _spell)| local_spell(index)),
            );
        }
        BuffEffect::ChargeRechargeRateCategory { category, .. } => {
            target.extend(
                spells
                    .iter()
                    .enumerate()
                    .filter(|&(_index, spell)| {
                        spell.cooldown.has_cooldown
                            && spell
                                .cooldown
                                .charge_category
                                .is_some_and(|value| value.raw() == *category)
                    })
                    .map(|(index, _spell)| local_spell(index)),
            );
        }
        _ => {}
    }
}

fn collect_maximum_charge_spells(
    effect: &BuffEffect,
    spells: &[SpellData],
    target: &mut Vec<LocalSpellIdx>,
) {
    let BuffEffect::MaxChargesCategory(_, category) = effect else {
        return;
    };

    target.extend(
        spells
            .iter()
            .enumerate()
            .filter(|&(_index, spell)| {
                spell.is_charged()
                    && spell
                        .cooldown
                        .charge_category
                        .is_some_and(|value| value.raw() == *category)
            })
            .map(|(index, _spell)| local_spell(index)),
    );
}

fn collect_gate_spells(effect: &BuffEffect, spells: &[SpellData], target: &mut Vec<LocalSpellIdx>) {
    if matches!(effect, BuffEffect::SpellGateFromEffect { .. }) {
        target.extend((0..spells.len()).map(local_spell));
    }
}

fn collect_aura_timing(
    effect: &BuffEffect,
    auras: &[AuraData],
    config: &ProgramConfig,
    target: &mut Vec<LocalAuraIdx>,
) {
    let BuffEffect::AuraTimeRateFromEffect {
        source_spell_id,
        effect_index,
        ..
    } = effect
    else {
        return;
    };

    target.extend(
        auras
            .iter()
            .enumerate()
            .filter(|&(_, aura)| {
                config.game_data.effect_affects_spell(
                    SpellIdx::from_raw(*source_spell_id),
                    *effect_index,
                    SpellIdx::from_raw(aura.aura_id),
                )
            })
            .map(|(index, _)| local_aura(index)),
    );
}

fn local_aura(index: usize) -> LocalAuraIdx {
    LocalAuraIdx::new(u8::try_from(index).expect("finalized aura count is validated below 256"))
}

fn spell_has_primary_cost(spell: &SpellData, config: &ProgramConfig) -> bool {
    // #t(fn: rust_floating_point_eq) finalized cost fields use exact zero as the absent sentinel.
    spell.cost.resource_cost != 0.0
        || spell.cost.optional_resource_cost != 0.0
        || spell.cost.resource_cost_pct.percent != 0.0
        || spell.cost.optional_resource_cost_pct.percent != 0.0
        || spell.cost.maximum_resource_cost_pct.percent != 0.0
        || config.game_data.cost_entry(spell.idx(), false) != 0
}

fn spell_has_secondary_cost(spell: &SpellData, config: &ProgramConfig) -> bool {
    // #t(fn: rust_floating_point_eq) finalized cost fields use exact zero as the absent sentinel.
    spell.cost.secondary_resource_cost != 0.0
        || spell.cost.secondary_optional_resource_cost != 0.0
        || config.game_data.cost_entry(spell.idx(), true) != 0
}

fn spell_uses_maximum_resource_cost(spell: &SpellData) -> bool {
    // #t(fn: rust_floating_point_eq) finalized percentage cost fields use exact zero as the absent sentinel.
    [
        spell.cost.resource_cost_pct,
        spell.cost.optional_resource_cost_pct,
        spell.cost.maximum_resource_cost_pct,
    ]
    .into_iter()
    .any(|cost| cost.percent != 0.0 && cost.basis == ResourceCostPercentBasis::Maximum)
}

fn exact_projection_key(
    aura: AuraIdx,
    on: AuraOn,
    current_target: Option<EnemyIdx>,
) -> Option<AuraKey> {
    let (source, affected) = match on {
        AuraOn::Player => (ActorId::Player, ActorId::Player),
        AuraOn::Target => (ActorId::Player, ActorId::Enemy(current_target?)),
        AuraOn::Pet => {
            let pet = ActorId::Pet(PetIdx::PRIMARY);

            (pet, pet)
        }
    };

    Some(AuraKey::new(aura, source, affected, on))
}