wowlab_engine_combat/builder/combat_builder/

trigger_program.rs

//! DBC trigger-program lowering and automatic registration.

use wowlab_engine_domain::{
    constants::OFF_HAND_DAMAGE_MULT,
    dbc::{AuraSubtypeKind, SpellEffectKind, spell_effect_is},
};

use super::{TriggerProgramLowering, TriggerProgramRegistration};
use crate::builder::def::{BuilderDamageDef, BuilderSpellEffect, PeriodicEffectDef};

#[derive(Debug, thiserror::Error)]
pub(super) enum TriggerProgramLowerError {
    #[error("trigger program references unregistered aura {aura_id}")]
    UnregisteredAura { aura_id: u32 },
    #[error("trigger program references unregistered cooldown category {category}")]
    UnregisteredCooldownCategory { category: i32 },
    #[error("trigger program references unregistered cooldown spell {spell_id}")]
    UnregisteredCooldownSpell { spell_id: u32 },
    #[error("trigger program damage uses an unsupported damage kind")]
    UnsupportedDamageKind,
}

wowlab_engine_macros::define_error! {
#[derive(Debug)]
struct TriggerProgramError {
    #[source]
    kind: TriggerProgramErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum TriggerProgramErrorKind {
    #[error("{0}")]
    Resolve(#[source] wowlab_engine_domain::dbc::TriggerResolveError),
    #[error("{0}")]
    Lower(#[source] TriggerProgramLowerError),
}
}

#[cfg(test)]
impl TriggerProgramError {
    const fn is_resolve(&self) -> bool {
        matches!(self.kind, TriggerProgramErrorKind::Resolve(_))
    }

    const fn is_lower(&self) -> bool {
        matches!(self.kind, TriggerProgramErrorKind::Lower(_))
    }
}

impl From<TriggerProgramLowerError> for TriggerProgramError {
    fn from(source: TriggerProgramLowerError) -> Self {
        Self {
            kind: TriggerProgramErrorKind::Lower(source),
        }
    }
}

impl From<wowlab_engine_domain::dbc::TriggerResolveError> for TriggerProgramError {
    fn from(source: wowlab_engine_domain::dbc::TriggerResolveError) -> Self {
        Self {
            kind: TriggerProgramErrorKind::Resolve(source),
        }
    }
}

fn lower_trigger_damage(
    triggered: wowlab_engine_domain::dbc::TriggeredDamage,
) -> Result<(BuilderDamageDef, f64), TriggerProgramLowerError> {
    let damage = BuilderDamageDef::from_resolved(triggered.damage, OFF_HAND_DAMAGE_MULT)
        .ok_or(TriggerProgramLowerError::UnsupportedDamageKind)?;
    let base_points = crate::state::resolved_damage_base_points(triggered.damage, 1.0);

    Ok((damage, base_points))
}

impl TriggerProgramLowering<'_> {
    pub(super) fn lower_trigger_program(
        &self,
        program: &wowlab_engine_domain::dbc::TriggerProgram,
    ) -> Result<Vec<BuilderSpellEffect>, TriggerProgramLowerError> {
        self.lower_trigger_operations(&program.operations)
    }

    // #t(fn: rust_cyclomatic_complexity) exhaustive lowering over the typed trigger-operation vocabulary
    fn lower_trigger_operations(
        &self,
        operations: &[wowlab_engine_domain::dbc::TriggerOperation],
    ) -> Result<Vec<BuilderSpellEffect>, TriggerProgramLowerError> {
        let mut effects = Vec::with_capacity(operations.len());

        for operation in operations {
            match operation {
                wowlab_engine_domain::dbc::TriggerOperation::Damage(triggered) => {
                    let (damage, base_points) = lower_trigger_damage(*triggered)?;

                    effects.push(BuilderSpellEffect::Damage {
                        effect: crate::state::DamageEffectRef::new(
                            triggered.spell_id.as_u32(),
                            triggered.damage.effect_index,
                        ),
                        damage,
                        base_points,
                        may_crit: !self
                            .definition
                            .game_data
                            .cannot_crit(triggered.spell_id)
                            .unwrap_or(false),
                        attribute_flags: crate::systems::damage_flags_from_data(
                            &self.definition.game_data,
                            triggered.spell_id,
                            triggered.damage.is_physical,
                        ),
                        requires_main_hand: triggered.requires_main_hand,
                        requires_off_hand: triggered.requires_off_hand,
                        equipped_item_requirement: triggered.equipped_item_requirement,
                    });
                }
                wowlab_engine_domain::dbc::TriggerOperation::Delayed {
                    delay_ms,
                    profile_spell_id,
                    operations,
                } => effects.push(BuilderSpellEffect::Delayed {
                    delay_ms: *delay_ms,
                    profile_spell_id: profile_spell_id.as_u32(),
                    effects: self.lower_trigger_operations(operations)?,
                }),
                wowlab_engine_domain::dbc::TriggerOperation::ApplyAura { aura_id } => {
                    let index = self
                        .definition
                        .aura_defs
                        .iter()
                        .position(|aura| aura.aura_id == aura_id.as_u32())
                        .ok_or(TriggerProgramLowerError::UnregisteredAura {
                            aura_id: aura_id.as_u32(),
                        })?;
                    let local = u8::try_from(index)
                        .map(crate::LocalAuraIdx::new)
                        .ok()
                        .ok_or(TriggerProgramLowerError::UnregisteredAura {
                            aura_id: aura_id.as_u32(),
                        })?;

                    effects.push(BuilderSpellEffect::ApplyAura { aura_local: local });
                }
                wowlab_engine_domain::dbc::TriggerOperation::RemoveAura { aura_id } => {
                    let index = self
                        .definition
                        .aura_defs
                        .iter()
                        .position(|aura| aura.aura_id == aura_id.as_u32())
                        .ok_or(TriggerProgramLowerError::UnregisteredAura {
                            aura_id: aura_id.as_u32(),
                        })?;
                    let local = u8::try_from(index)
                        .map(crate::LocalAuraIdx::new)
                        .ok()
                        .ok_or(TriggerProgramLowerError::UnregisteredAura {
                            aura_id: aura_id.as_u32(),
                        })?;

                    effects.push(BuilderSpellEffect::RemoveAura { aura_local: local });
                }
                wowlab_engine_domain::dbc::TriggerOperation::EnergizePrimary { amount } => {
                    effects.push(BuilderSpellEffect::Energize {
                        effect: None,
                        pool: crate::state::ResourcePool::Primary,
                        amount: *amount,
                    });
                }
                wowlab_engine_domain::dbc::TriggerOperation::EnergizeSecondary { amount } => {
                    effects.push(BuilderSpellEffect::Energize {
                        effect: None,
                        pool: crate::state::ResourcePool::Secondary,
                        amount: *amount,
                    });
                }
                wowlab_engine_domain::dbc::TriggerOperation::EnergizePercent {
                    resource_type,
                    percent,
                    effect_index,
                } => effects.push(BuilderSpellEffect::EnergizePercent {
                    resource_type: *resource_type,
                    percent: *percent,
                    effect_index: *effect_index,
                }),
                wowlab_engine_domain::dbc::TriggerOperation::MutateCooldown {
                    target,
                    operation,
                } => {
                    let (index, error) = match target {
                        wowlab_engine_domain::dbc::TriggerCooldownTarget::Spell(spell_id) => (
                            self.definition
                                .spells
                                .iter()
                                .position(|spell| spell.spell_id == spell_id.as_u32()),
                            TriggerProgramLowerError::UnregisteredCooldownSpell {
                                spell_id: spell_id.as_u32(),
                            },
                        ),
                        wowlab_engine_domain::dbc::TriggerCooldownTarget::ChargeCategory(
                            category,
                        ) => (
                            self.definition.spells.iter().position(|spell| {
                                spell
                                    .cooldown
                                    .as_ref()
                                    .and_then(|cooldown| cooldown.charge_category)
                                    == Some(*category)
                            }),
                            TriggerProgramLowerError::UnregisteredCooldownCategory {
                                category: category.raw(),
                            },
                        ),
                    };
                    let local = index
                        .and_then(|index| u8::try_from(index).ok())
                        .map(crate::state::LocalSpellIdx::new)
                        .ok_or(error)?;

                    effects.push(BuilderSpellEffect::MutateCooldown {
                        spell_local: local,
                        operation: *operation,
                    });
                }
                _ => return Err(TriggerProgramLowerError::UnsupportedDamageKind),
            }
        }

        Ok(effects)
    }
    fn lower_dbc_effect_program(
        &self,
        source: wowlab_types::sim::SpellIdx,
        effect_index: u8,
    ) -> Result<Option<(u32, Vec<BuilderSpellEffect>)>, TriggerProgramError> {
        let Some(program) = wowlab_engine_domain::dbc::resolve_effect_program(
            wowlab_engine_domain::dbc::EffectLookup::new(
                &self.definition.game_data,
                wowlab_types::sim::EffectRef::new(source, effect_index),
            ),
            None,
        )?
        else {
            return Ok(None);
        };
        let child_spell_id = program.child_spell_id.as_u32();
        let effects = self.lower_trigger_program(&program)?;

        Ok(Some((child_spell_id, effects)))
    }
}

// #t(fn: rust_recursive_fn) delayed effects come from the cycle-checked, depth-bounded DBC trigger resolver
fn effect_matches(left: &BuilderSpellEffect, right: &BuilderSpellEffect) -> bool {
    match (left, right) {
        (
            BuilderSpellEffect::Conditional {
                predicate: left_predicate,
                effects: left_effects,
            },
            BuilderSpellEffect::Conditional {
                predicate: right_predicate,
                effects: right_effects,
            },
        ) => {
            std::ptr::fn_addr_eq(*left_predicate, *right_predicate)
                && left_effects.len() == right_effects.len()
                && left_effects
                    .iter()
                    .zip(right_effects)
                    .all(|(left, right)| effect_matches(left, right))
        }
        (
            BuilderSpellEffect::Damage { effect: left, .. },
            BuilderSpellEffect::Damage { effect: right, .. },
        ) => left == right,
        (
            BuilderSpellEffect::ApplyAura { aura_local: left },
            BuilderSpellEffect::ApplyAura { aura_local: right },
        )
        | (
            BuilderSpellEffect::RemoveAura { aura_local: left },
            BuilderSpellEffect::RemoveAura { aura_local: right },
        ) => left == right,
        (
            BuilderSpellEffect::MutateCooldown {
                spell_local: left_spell,
                operation: left_operation,
            },
            BuilderSpellEffect::MutateCooldown {
                spell_local: right_spell,
                operation: right_operation,
            },
        ) => left_spell == right_spell && left_operation == right_operation,
        (
            BuilderSpellEffect::Delayed {
                delay_ms: left_delay,
                profile_spell_id: left_profile,
                effects: left_effects,
            },
            BuilderSpellEffect::Delayed {
                delay_ms: right_delay,
                profile_spell_id: right_profile,
                effects: right_effects,
            },
        ) => {
            left_delay == right_delay
                && left_profile == right_profile
                && left_effects.len() == right_effects.len()
                && left_effects
                    .iter()
                    .zip(right_effects)
                    .all(|(left, right)| effect_matches(left, right))
        }
        (BuilderSpellEffect::Delayed { effects, .. }, right) if effects.len() == 1 => {
            effect_matches(
                effects
                    .first()
                    .expect("single-effect delayed program contains one effect"),
                right,
            )
        }
        _ => false,
    }
}

// #t(fn: rust_recursive_fn) nested delays come from the cycle-checked, depth-bounded DBC trigger resolver
fn retain_inferred_delay(authored: &mut BuilderSpellEffect, inferred: &BuilderSpellEffect) -> bool {
    let BuilderSpellEffect::Delayed {
        delay_ms,
        profile_spell_id,
        effects,
    } = inferred
    else {
        return false;
    };
    let [inferred_child] = effects.as_slice() else {
        return false;
    };
    let mut authored_child = authored.clone();

    if !effect_matches(&authored_child, inferred_child)
        && !retain_inferred_delay(&mut authored_child, inferred_child)
    {
        return false;
    }

    *authored = BuilderSpellEffect::Delayed {
        delay_ms: *delay_ms,
        profile_spell_id: *profile_spell_id,
        effects: vec![authored_child],
    };

    true
}

fn extend_missing_occurrences(
    destination: &mut Vec<BuilderSpellEffect>,
    source: Vec<BuilderSpellEffect>,
) {
    let existing_len = destination.len();
    let mut matched = vec![false; existing_len];

    for effect in source {
        let mut existing = destination
            .iter()
            .take(existing_len)
            .enumerate()
            .find(|(index, candidate)| {
                !matched.get(*index).copied().unwrap_or(false) && effect_matches(candidate, &effect)
            })
            .map(|(index, _)| index);

        if existing.is_none() {
            existing = destination
                .iter_mut()
                .take(existing_len)
                .enumerate()
                .find_map(|(index, candidate)| {
                    (!matched.get(index).copied().unwrap_or(false)
                        && retain_inferred_delay(candidate, &effect))
                    .then_some(index)
                });
        }

        if let Some(index) = existing {
            let slot = matched
                .get_mut(index)
                .expect("matched indices originate from destination iteration");

            *slot = true;
        } else {
            destination.push(effect);
        }
    }
}

/// The parent `damage_def` absorbed this trigger child; dealing it again would double it.
fn should_strip_program_damage(
    spell: &crate::builder::def::BuilderSpellDef,
    lookup: wowlab_engine_domain::dbc::EffectLookup<'_>,
) -> bool {
    let spell_id = lookup.effect.spell.as_u32();
    let effect_index = lookup.effect.effect_index;

    if !spell.infer_data_damage {
        return true;
    }

    if matches!(spell.damage, BuilderDamageDef::None) {
        return false;
    }

    if spell.damage_effect == crate::state::DamageEffectRef::new(spell_id, effect_index) {
        return true;
    }

    wowlab_engine_domain::dbc::resolve_triggered_damage(lookup).is_ok_and(|triggered| {
        spell.damage_effect
            == crate::state::DamageEffectRef::new(
                triggered.spell_id.as_u32(),
                triggered.damage.effect_index,
            )
    })
}

// #t(fn: rust_recursive_fn) delayed effects come from the cycle-checked, depth-bounded DBC trigger resolver
fn retain_non_damage_operations(effects: &mut Vec<BuilderSpellEffect>) {
    effects.retain_mut(|effect| match effect {
        BuilderSpellEffect::Damage { .. } => false,
        BuilderSpellEffect::Conditional { effects, .. }
        | BuilderSpellEffect::Delayed { effects, .. } => {
            retain_non_damage_operations(effects);

            !effects.is_empty()
        }
        _ => true,
    });
}

impl TriggerProgramRegistration<'_> {
    pub(super) fn auto_register_dbc_trigger_programs(&mut self) {
        self.auto_register_dbc_spell_trigger_programs();
        let aura_ids: Vec<_> = self
            .definition
            .aura_defs
            .iter()
            .map(|aura| aura.aura_id)
            .collect();
        let mut tick_programs = Vec::new();
        let mut apply_programs = vec![Vec::new(); aura_ids.len()];
        let mut apply_children = vec![Vec::new(); aura_ids.len()];

        for (aura_index, aura_id) in aura_ids.into_iter().enumerate() {
            let has_periodic_hook = matches!(
                self.definition
                    .aura_defs
                    .get(aura_index)
                    .expect("aura index originates from aura_ids")
                    .periodic
                    .as_ref()
                    .map(|periodic| &periodic.effect),
                Some(PeriodicEffectDef::Hook)
            );
            let source = wowlab_types::sim::SpellIdx::from_raw(aura_id);

            for effect_index in 1..=self.definition.game_data.max_effect_index(source) {
                let effect_type = self.definition.game_data.effect_type(source, effect_index);

                if !spell_effect_is(effect_type, SpellEffectKind::ApplyAura) {
                    match self
                        .lowering()
                        .lower_dbc_effect_program(source, effect_index)
                    {
                        Ok(Some((child_spell_id, effects))) => {
                            apply_programs
                                .get_mut(aura_index)
                                .expect("program slots mirror aura_ids")
                                .extend(effects);
                            apply_children
                                .get_mut(aura_index)
                                .expect("child slots mirror aura_ids")
                                .push(child_spell_id);
                            continue;
                        }
                        Ok(None) => {}
                        // #t(rust_log_in_loop) construction-time gap diagnostics retain the exact aura/effect edge
                        Err(error) => tracing::debug!(
                            aura_id,
                            effect_index,
                            %error,
                            "DBC_AURA_EFFECT_PROGRAM_GAP"
                        ),
                    }
                }

                let aura_subtype = self.definition.game_data.effect_aura(source, effect_index);
                let is_periodic = has_periodic_hook
                    && aura_subtype == AuraSubtypeKind::PeriodicTriggerSpell as i32;
                let is_apply = aura_subtype == AuraSubtypeKind::CastLinkedSpellWithValue as i32;

                if !is_periodic && !is_apply {
                    continue;
                }

                let forwarded_value =
                    is_apply.then(|| self.definition.game_data.base_points(source, effect_index));
                let result = self.lower_dbc_trigger_program(source, effect_index, forwarded_value);

                match result {
                    Ok((child_spell_id, effects)) if !effects.is_empty() => {
                        if is_apply {
                            apply_programs
                                .get_mut(aura_index)
                                .expect("program slots mirror aura_ids")
                                .extend(effects);
                            apply_children
                                .get_mut(aura_index)
                                .expect("child slots mirror aura_ids")
                                .push(child_spell_id);
                        } else {
                            tick_programs.push((aura_index, child_spell_id, effects));
                        }
                    }
                    Ok(_) => {}
                    // #t(rust_log_in_loop) construction-time gap diagnostics retain the exact aura/effect edge
                    Err(error) => tracing::debug!(
                        aura_id,
                        effect_index,
                        %error,
                        "DBC_AURA_TRIGGER_PROGRAM_GAP"
                    ),
                }
            }
        }

        for (aura_index, child_spell_id, effects) in tick_programs {
            let aura = self
                .definition
                .aura_defs
                .get_mut(aura_index)
                .expect("tick programs retain an index from aura_ids");

            extend_missing_occurrences(&mut aura.tick_effects, effects);
            aura.tick_profile_spell_id = child_spell_id;
            // #t(rust_log_in_loop) one construction-time summary is emitted per registered periodic program
            tracing::debug!(
                aura_id = aura.aura_id,
                child_spell_id,
                "registered periodic DBC trigger program"
            );
        }

        for (aura_index, effects) in apply_programs.into_iter().enumerate() {
            if effects.is_empty() {
                continue;
            }

            let aura = self
                .definition
                .aura_defs
                .get_mut(aura_index)
                .expect("application programs mirror registered auras");

            extend_missing_occurrences(&mut aura.apply_effects, effects);
            let child_spell_ids = apply_children
                .get(aura_index)
                .expect("child slots mirror registered auras");

            aura.apply_profile_spell_id = *child_spell_ids
                .first()
                .expect("non-empty application effects retain a child spell");
            // #t(rust_log_in_loop) one construction-time summary is emitted per registered application program
            tracing::debug!(
                aura_id = aura.aura_id,
                ?child_spell_ids,
                "registered aura-application DBC trigger program"
            );
        }
    }

    fn lowering(&self) -> TriggerProgramLowering<'_> {
        TriggerProgramLowering {
            definition: &*self.definition,
        }
    }

    fn lower_dbc_trigger_program(
        &self,
        source: wowlab_types::sim::SpellIdx,
        effect_index: u8,
        forwarded_value: Option<f64>,
    ) -> Result<(u32, Vec<BuilderSpellEffect>), TriggerProgramError> {
        let program = wowlab_engine_domain::dbc::resolve_trigger_program(
            wowlab_engine_domain::dbc::EffectLookup::new(
                &self.definition.game_data,
                wowlab_types::sim::EffectRef::new(source, effect_index),
            ),
            forwarded_value,
        )?;
        let child_spell_id = program.child_spell_id.as_u32();
        let effects = self.lowering().lower_trigger_program(&program)?;

        Ok((child_spell_id, effects))
    }
    // #t(fn: rust_max_fn_lines) two ordered passes preserve per-effect registration and final per-spell merge semantics
    // #t(fn: rust_cyclomatic_complexity) one DBC trigger walk keeps duplicate suppression, conditional grouping, and diagnostics on the same effect coordinate
    fn auto_register_dbc_spell_trigger_programs(&mut self) {
        let spell_ids: Vec<_> = self
            .definition
            .spells
            .iter()
            .map(|spell| spell.spell_id)
            .collect();
        let mut spell_programs = vec![Vec::new(); spell_ids.len()];
        let mut spell_children = vec![Vec::new(); spell_ids.len()];

        for (spell_index, spell_id) in spell_ids.into_iter().enumerate() {
            let source = wowlab_types::sim::SpellIdx::from_raw(spell_id);

            for effect_index in 1..=self.definition.game_data.max_effect_index(source) {
                let predicate = self
                    .definition
                    .spells
                    .get(spell_index)
                    .expect("spell index originates from spell_ids")
                    .trigger_program_predicates
                    .iter()
                    .rev()
                    .find(|entry| entry.effect_index == effect_index)
                    .map(|entry| entry.predicate);

                match self
                    .lowering()
                    .lower_dbc_effect_program(source, effect_index)
                {
                    Ok(Some((child_spell_id, effects))) => {
                        let mut accepted = Vec::new();

                        for effect in effects {
                            let duplicate_primary_aura = matches!(
                                effect,
                                BuilderSpellEffect::ApplyAura { aura_local }
                                    if self
                                        .definition
                                        .spells
                                        .get(spell_index)
                                        .expect("spell index originates from spell_ids")
                                        .applies_aura
                                        == Some(aura_local)
                            );
                            let duplicate_program_aura = matches!(
                                effect,
                                BuilderSpellEffect::ApplyAura { aura_local }
                                    if spell_programs
                                        .get(spell_index)
                                        .expect("program slots mirror spell_ids")
                                        .iter()
                                        .any(|existing| matches!(
                                            existing,
                                            BuilderSpellEffect::ApplyAura { aura_local: existing_local }
                                                if *existing_local == aura_local
                                        ))
                                        || accepted.iter().any(|existing| matches!(
                                            existing,
                                            BuilderSpellEffect::ApplyAura { aura_local: existing_local }
                                                if *existing_local == aura_local
                                        ))
                            );

                            if !duplicate_primary_aura && !duplicate_program_aura {
                                accepted.push(effect);
                            }
                        }

                        if !accepted.is_empty() {
                            let programs = spell_programs
                                .get_mut(spell_index)
                                .expect("program slots mirror spell_ids");

                            if let Some(predicate) = predicate {
                                programs.push(BuilderSpellEffect::Conditional {
                                    predicate,
                                    effects: accepted,
                                });
                            } else {
                                programs.extend(accepted);
                            }
                        }

                        spell_children
                            .get_mut(spell_index)
                            .expect("child slots mirror spell_ids")
                            .push(child_spell_id);
                        continue;
                    }
                    Ok(None) => {}
                    // #t(rust_log_in_loop) construction-time gap diagnostics retain the exact spell/effect edge
                    Err(error) => tracing::debug!(
                        spell_id,
                        effect_index,
                        %error,
                        "DBC_EFFECT_PROGRAM_GAP"
                    ),
                }

                let effect_type = self.definition.game_data.effect_type(source, effect_index);
                let is_trigger_effect = wowlab_engine_domain::dbc::spell_effect_is_any(
                    effect_type,
                    &[
                        SpellEffectKind::TriggerMissile,
                        SpellEffectKind::TriggerSpell,
                        SpellEffectKind::TriggerSpellWithValue,
                        SpellEffectKind::TriggerSpell2,
                    ],
                );

                if !is_trigger_effect {
                    continue;
                }

                let forwarded_value =
                    spell_effect_is(effect_type, SpellEffectKind::TriggerSpellWithValue)
                        .then(|| self.definition.game_data.base_points(source, effect_index));
                let result = self.lower_dbc_trigger_program(source, effect_index, forwarded_value);

                match result {
                    Ok((child_spell_id, mut effects)) => {
                        let spell = self
                            .definition
                            .spells
                            .get(spell_index)
                            .expect("spell index originates from spell_ids");

                        if should_strip_program_damage(
                            spell,
                            wowlab_engine_domain::dbc::EffectLookup::new(
                                &self.definition.game_data,
                                wowlab_types::sim::EffectRef::new(source, effect_index),
                            ),
                        ) {
                            retain_non_damage_operations(&mut effects);
                        }

                        if effects.is_empty() {
                            continue;
                        }

                        let delay_ms = u32::try_from(
                            self.definition
                                .game_data
                                .effect_misc_value_0(source, effect_index),
                        )
                        .unwrap_or(0);

                        let effects = vec![BuilderSpellEffect::Delayed {
                            delay_ms,
                            profile_spell_id: child_spell_id,
                            effects,
                        }];
                        let programs = spell_programs
                            .get_mut(spell_index)
                            .expect("program slots mirror spell_ids");

                        if let Some(predicate) = predicate {
                            programs.push(BuilderSpellEffect::Conditional { predicate, effects });
                        } else {
                            programs.extend(effects);
                        }

                        spell_children
                            .get_mut(spell_index)
                            .expect("child slots mirror spell_ids")
                            .push(child_spell_id);
                    }
                    // #t(rust_log_in_loop) construction-time gap diagnostics retain the exact spell/effect edge
                    Err(error) => tracing::debug!(
                        spell_id,
                        effect_index,
                        %error,
                        "DBC_TRIGGER_PROGRAM_GAP"
                    ),
                }
            }
        }

        for (spell_index, effects) in spell_programs.into_iter().enumerate() {
            if effects.is_empty() {
                continue;
            }

            let spell = self
                .definition
                .spells
                .get_mut(spell_index)
                .expect("program slots mirror registered spells");

            extend_missing_occurrences(&mut spell.followup_effects, effects);
            let child_spell_ids = spell_children
                .get(spell_index)
                .expect("child slots mirror registered spells");

            // #t(rust_log_in_loop) one construction-time summary is emitted per registered spell program
            tracing::debug!(
                spell_id = spell.spell_id,
                ?child_spell_ids,
                "registered immediate DBC trigger program"
            );
        }
    }
}

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

    use googletest::prelude::*;
    use wowlab_engine_gamedata::ResolvedGameData;
    use wowlab_engine_ports::CombatStats;
    use wowlab_types::sim::SpellIdx;

    use super::*;
    use crate::{CombatSystemBuilder, DamageFlags, state::DamageEffectRef};

    fn damage_effect(spell_id: u32) -> BuilderSpellEffect {
        BuilderSpellEffect::Damage {
            effect: DamageEffectRef::new(spell_id, 1),
            damage: BuilderDamageDef::Flat(1.0),
            base_points: 1.0,
            may_crit: true,
            attribute_flags: DamageFlags::empty(),
            requires_main_hand: false,
            requires_off_hand: false,
            equipped_item_requirement: None,
        }
    }

    fn lowering(data: ResolvedGameData) -> CombatSystemBuilder {
        CombatSystemBuilder::new_for_test(CombatStats::default()).game_data(data)
    }

    #[gtest]
    fn effect_program_resolution_failure_retains_trigger_source_and_edge_context() -> Result<()> {
        const SOURCE: SpellIdx = SpellIdx(91_001);
        let mut data = ResolvedGameData::builder();

        data.insert_effect_type(
            wowlab_types::sim::EffectRef::new(SOURCE, 1),
            SpellEffectKind::RemoveAura as i32,
        );
        let definition = lowering(data.build());

        let error = TriggerProgramLowering {
            definition: &definition,
        }
        .lower_dbc_effect_program(SOURCE, 1)
        .expect_err("missing trigger edge must fail resolution");

        verify_true!(error.is_resolve())?;
        verify_that!(
            error.to_string(),
            eq("trigger child spell 91001 effect 1 names no aura to remove")
        )?;
        verify_true!(
            error
                .source()
                .and_then(std::error::Error::source)
                .is_some_and(
                    <dyn std::error::Error>::is::<wowlab_engine_domain::dbc::TriggerResolveError>
                )
        )?;

        Ok(())
    }

    #[gtest]
    fn authored_child_damage_retains_inferred_nested_delay_and_profile() -> Result<()> {
        let mut authored = damage_effect(93_001);
        let BuilderSpellEffect::Damage { base_points, .. } = &mut authored else {
            unreachable!("fixture is damage");
        };

        *base_points = 7.0;
        let mut effects = vec![authored];

        extend_missing_occurrences(
            &mut effects,
            vec![BuilderSpellEffect::Delayed {
                delay_ms: 300,
                profile_spell_id: 93_001,
                effects: vec![BuilderSpellEffect::Delayed {
                    delay_ms: 700,
                    profile_spell_id: 93_002,
                    effects: vec![damage_effect(93_001)],
                }],
            }],
        );

        let [
            BuilderSpellEffect::Delayed {
                delay_ms: outer_delay,
                profile_spell_id: outer_profile,
                effects: outer_effects,
            },
        ] = effects.as_slice()
        else {
            unreachable!("expected one outer delayed effect");
        };
        let [
            BuilderSpellEffect::Delayed {
                delay_ms: inner_delay,
                profile_spell_id: inner_profile,
                effects: inner_effects,
            },
        ] = outer_effects.as_slice()
        else {
            unreachable!("expected one inner delayed effect");
        };
        let [BuilderSpellEffect::Damage { base_points, .. }] = inner_effects.as_slice() else {
            unreachable!("expected authored damage payload");
        };

        verify_that!(
            (
                *outer_delay,
                *outer_profile,
                *inner_delay,
                *inner_profile,
                *base_points,
            ),
            eq((300, 93_001, 700, 93_002, 7.0))
        )
    }

    #[gtest]
    fn effect_program_lowering_failure_retains_typed_unregistered_aura_source() -> Result<()> {
        const SOURCE: SpellIdx = SpellIdx(92_001);
        let mut data = ResolvedGameData::builder();

        data.insert_effect_type(
            wowlab_types::sim::EffectRef::new(SOURCE, 1),
            SpellEffectKind::ApplyAura as i32,
        );
        let definition = lowering(data.build());

        let error = TriggerProgramLowering {
            definition: &definition,
        }
        .lower_dbc_effect_program(SOURCE, 1)
        .expect_err("unregistered child aura must fail lowering");

        verify_true!(error.is_lower())?;
        verify_that!(
            error.to_string(),
            eq("trigger program references unregistered aura 92001")
        )?;
        verify_true!(
            error
                .source()
                .and_then(std::error::Error::source)
                .is_some_and(<dyn std::error::Error>::is::<TriggerProgramLowerError>)
        )?;

        Ok(())
    }
}