wowlab_engine_combat/systems/auras/

application_state.rs

// #t(file: rust_duplicate_strings) Aura binding invariant messages intentionally match the owning aura transaction diagnostics.

//! Aura instance projection, snapshot, refresh, and rolling-periodic state.

use wowlab_engine_domain::constants::AURA_PANDEMIC_THRESHOLD;
use wowlab_engine_ports::Event;
use wowlab_engine_telemetry::TelemetrySink;
use wowlab_types::{
    constants::MS_PER_SECOND,
    sim::{ActorId, AuraIdx, AuraKey, AuraOn, EnemyIdx, PetIdx, SimTime},
};

use super::{MAX_AURA_APPLICATION_ACTORS, PERMANENT_AURA_EXPIRES_AT_S};
#[cfg(test)]
use crate::systems::{
    refresh_maximum_charges_for, refresh_pet_actions_after_aura_change, refresh_pet_stat_snapshots,
    refresh_primary_resource_projection, refresh_recharge_rates_for, refresh_spell_costs_for,
    refresh_spell_gates_for, sync_player_health_from_stamina,
};
use crate::{
    context::HookCtx,
    state::{
        AuraActivation, AuraMutation, AuraRefresh, AuraSchedule, AuraSnapshot, CombatInstance,
        DamageEffectRef, LocalAuraIdx,
    },
    systems::{
        buffs::{self, buff_totals},
        damage_pipeline::{
            DamageFlags, DamageSnapshot, SpellModifierEffect, SpellModifierProfile,
            SpellModifierQuery, dynamic_base_powers, read_player_stats_for_damage,
            spell_scoped_mods_for, typed_attack_power_with,
        },
        mastery::MasteryCtx,
    },
};

#[cfg(test)]
pub(super) fn pandemic_carry(base_duration: f64, remaining: f64) -> f64 {
    remaining.min(base_duration * AURA_PANDEMIC_THRESHOLD)
}

pub(super) fn pandemic_carry_ms(base_duration_ms: u32, remaining_ms: u32) -> u32 {
    let carry_limit = wowlab_types::numeric::f64_to_u32_saturating_trunc(
        f64::from(base_duration_ms) * AURA_PANDEMIC_THRESHOLD,
    );

    remaining_ms.min(carry_limit)
}

#[derive(Clone, Copy)]
pub(super) struct AuraSlotRequest<'a> {
    pub aura: &'a crate::state::AuraData,
    pub local: LocalAuraIdx,
    pub key: AuraKey,
    pub base_dur_ms: u32,
    pub base_dur: SimTime,
    pub is_permanent: bool,
}

#[inline]
fn resolved_aura_key(aura: &crate::state::AuraData, source: ActorId, affected: ActorId) -> AuraKey {
    AuraKey::new(AuraIdx(aura.aura_id), source, affected, aura.on)
}

#[inline]
pub(crate) fn aura_key_for(
    program: &crate::state::CombatProgram,
    _state: &CombatInstance,
    local: LocalAuraIdx,
    source: ActorId,
    target: Option<EnemyIdx>,
) -> Option<AuraKey> {
    let aura = program.auras.get(local.as_usize()).copied()?;
    let affected = match aura.on {
        AuraOn::Player => ActorId::Player,
        AuraOn::Target => ActorId::Enemy(target?),
        AuraOn::Pet => ActorId::Pet(match source {
            ActorId::Player => PetIdx::PRIMARY,
            ActorId::Pet(pet) => pet,
            ActorId::External | ActorId::Enemy(_) => return None,
        }),
    };

    Some(resolved_aura_key(&aura, source, affected))
}

pub(crate) fn aura_keys_for_application(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    local: LocalAuraIdx,
    source: ActorId,
    target: Option<EnemyIdx>,
) -> [Option<AuraKey>; MAX_AURA_APPLICATION_ACTORS] {
    let primary = aura_key_for(program, state, local, source, target);
    let secondary = program
        .auras
        .get(local.as_usize())
        .filter(|aura| aura.propagates_to_pet)
        .map(|aura| {
            AuraKey::new(
                AuraIdx(aura.aura_id),
                source,
                ActorId::Pet(PetIdx::PRIMARY),
                AuraOn::Pet,
            )
        });

    [primary, secondary]
}

pub(crate) fn aura_keys_for_actor_application(
    program: &crate::state::CombatProgram,
    _state: &CombatInstance,
    local: LocalAuraIdx,
    source: ActorId,
    affected: ActorId,
) -> [Option<AuraKey>; MAX_AURA_APPLICATION_ACTORS] {
    let Some(aura) = program.auras.get(local.as_usize()) else {
        return [None, None];
    };
    let primary = Some(resolved_aura_key(aura, source, affected));
    let secondary = aura.propagates_to_pet.then(|| {
        AuraKey::new(
            AuraIdx(aura.aura_id),
            source,
            ActorId::Pet(PetIdx::PRIMARY),
            AuraOn::Pet,
        )
    });

    [primary, secondary]
}

pub(super) fn aura_query_key_for(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    local: LocalAuraIdx,
    source: ActorId,
    target: Option<EnemyIdx>,
) -> Option<AuraKey> {
    let aura = program.auras.get(local.as_usize()).copied()?;
    let query_source = if aura.on == AuraOn::Player && matches!(source, ActorId::Pet(_)) {
        ActorId::Player
    } else {
        source
    };

    aura_key_for(program, state, local, query_source, target)
}

#[inline]
pub(super) fn context_aura_key(ctx: &HookCtx<'_>, local: LocalAuraIdx) -> Option<AuraKey> {
    if let Some(affected) = ctx.effect_target {
        let aura = ctx.program.auras.get(local.as_usize())?;

        return Some(resolved_aura_key(aura, ctx.source, affected));
    }

    aura_key_for(ctx.program, ctx.instance, local, ctx.source, ctx.target)
}

fn emit_aura_event(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    sink: &mut TelemetrySink,
    key: AuraKey,
    now: SimTime,
    emit: impl FnOnce(&mut TelemetrySink, u32, wowlab_engine_telemetry::AuraTelemetryScope),
) {
    emit(
        sink,
        now.as_millis(),
        program.aura_telemetry_scope(state, key),
    );
}

// #t(fn: rust_large_fn_params) program and instance are intentionally explicit lifecycle borrows alongside the complete typed telemetry event.
pub(crate) fn emit_aura_apply_event(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    sink: &mut TelemetrySink,
    key: AuraKey,
    aura_id: u32,
    stacks: u8,
    now: SimTime,
) {
    emit_aura_event(program, state, sink, key, now, |sink, at_ms, scope| {
        sink.emit_aura_apply(aura_id, stacks, at_ms, scope);
    });
}

// #t(fn: rust_large_fn_params) program and instance are intentionally explicit lifecycle borrows alongside the complete typed telemetry event.
pub(crate) fn emit_aura_refresh_event(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    sink: &mut TelemetrySink,
    key: AuraKey,
    aura_id: u32,
    stacks: u8,
    now: SimTime,
) {
    emit_aura_event(program, state, sink, key, now, |sink, at_ms, scope| {
        sink.emit_aura_refresh(aura_id, stacks, at_ms, scope);
    });
}

pub(super) fn emit_aura_expire_event(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    sink: &mut TelemetrySink,
    key: AuraKey,
    aura_id: u32,
    now: SimTime,
) {
    emit_aura_event(program, state, sink, key, now, |sink, at_ms, scope| {
        sink.emit_aura_expire(aura_id, at_ms, scope);
    });
}

fn refresh_projection(
    program: &crate::state::CombatProgram,
    instance: &mut CombatInstance,
    dependency: crate::state::program::ProjectionDependency,
) {
    let source = program
        .aura_dependencies
        .projection_source(dependency, instance.current_target());
    let exact = source.map_or_else(Default::default, |source| *instance.buffer.aura_at(source));

    *instance
        .buffer
        .aura_projection_mut_at(dependency.destination) = exact;
}

pub(crate) fn refresh_planned_aura_projection(
    program: &crate::state::CombatProgram,
    instance: &mut CombatInstance,
    index: crate::state::program::AuraProjectionDependencyIdx,
) {
    refresh_projection(
        program,
        instance,
        program.aura_dependencies.projection(index),
    );
}

/// Refresh all projections only for initialization or a selected-target transition.
pub(crate) fn refresh_all_aura_projections(
    program: &crate::state::CombatProgram,
    instance: &mut CombatInstance,
) {
    for dependency in program.aura_dependencies.all_projections() {
        refresh_projection(program, instance, *dependency);
    }

    instance.clear_aura_projection_dirty();
}

/// Independent full-consumer recomputation used only as a dispatcher differential oracle.
#[cfg(test)]
pub(crate) fn reference_recompute_all_aura_consumers(
    program: &crate::state::CombatProgram,
    instance: &mut CombatInstance,
    now: SimTime,
) {
    wowlab_types::bench_metrics::record_scanned_aura_definitions(program.auras.len());
    wowlab_types::bench_metrics::record_scanned_aura_spells(program.spells.len());
    wowlab_types::bench_metrics::record_scanned_aura_projections(
        program.aura_dependencies.all_projections().len(),
    );

    let spell_locals = (0..program.spells.len())
        .map(|index| {
            crate::state::LocalSpellIdx::new(u8::try_from(index).expect("spell count fits"))
        })
        .collect::<Vec<_>>();
    let spell_consumers = spell_locals
        .iter()
        .copied()
        .map(|local| crate::state::program::SpellConsumerBinding {
            local,
            handle: program.buffer_bindings.spell(local),
        })
        .collect::<Vec<_>>();
    let aura_bindings = program
        .buffer_bindings
        .aura_bindings()
        .filter(|binding| binding.key.affected() == ActorId::Player)
        .collect::<Vec<_>>();

    refresh_all_aura_projections(program, instance);
    refresh_spell_gates_for(program, instance, &spell_consumers);
    refresh_spell_costs_for(program, instance, &spell_consumers);
    refresh_recharge_rates_for(program, instance, now, &spell_locals);
    refresh_maximum_charges_for(program, instance, now, &spell_locals);
    sync_player_health_from_stamina(program, instance);
    refresh_primary_resource_projection(program, instance, now);
    super::refresh_aura_time_rates_for(program, instance, now, &aura_bindings);
    super::super::auto_attack::reproject_player_auto_attack_speeds(program, instance, now);
    super::super::auto_attack::reproject_pet_auto_attack_speeds(program, instance, now);
    super::super::guardians::reproject_guardian_action_speeds(program, instance, now);
    refresh_pet_stat_snapshots(program, instance);
    refresh_pet_actions_after_aura_change(program, instance, now);
}

pub(super) fn apply_exclusive_group_dependencies(
    ctx: &mut HookCtx<'_>,
    applied: crate::state::program::ConcreteAuraBinding,
) {
    let peer_count = ctx.program.aura_dependencies.exclusive_peers(applied).len();
    let spell_count = ctx
        .program
        .aura_dependencies
        .exclusive_spells(applied.local)
        .len();

    wowlab_types::bench_metrics::record_planned_aura_bindings(peer_count);
    wowlab_types::bench_metrics::record_planned_aura_spell_bindings(spell_count);

    for index in 0..peer_count {
        // BOUNDS: index is bounded by this exact finalized peer slice's length.
        let peer = ctx.program.aura_dependencies.exclusive_peers(applied)[index];

        if ctx.instance.buffer.aura_at(peer.handle).is_occupied() {
            super::expire_aura_instance(ctx, peer.local, peer.key);
        }
    }

    for dependency in ctx
        .program
        .aura_dependencies
        .exclusive_spells(applied.local)
    {
        ctx.instance
            .buffer
            .spell_mut_at(dependency.handle)
            .is_enabled = i32::from(dependency.enabled);
    }
}

#[inline]
pub(super) fn refreshed_stacks(aura: &crate::state::AuraData, current: i32) -> i32 {
    let max = i32::from(aura.max_stacks);

    if aura.apply_at_max_stacks {
        max
    } else {
        (current + i32::from(aura.doses)).min(max)
    }
}

pub(crate) fn capture_snapshot_for(
    program: &crate::state::CombatProgram,
    state: &CombatInstance,
    binding: crate::state::program::PeriodicDamageBinding,
    source: ActorId,
    target: Option<EnemyIdx>,
    now: SimTime,
) -> DamageSnapshot {
    let effect_plan = program.damage.effect_at(binding.snapshot_effect);
    let effect_action = program.damage.action_at(effect_plan.action);
    let effect = DamageEffectRef::new(effect_action.spell.as_u32(), effect_plan.effect_index);
    let spell_id = program
        .damage
        .action_at(binding.request.profile_action)
        .spell
        .as_u32();
    let (crit, vers) = read_player_stats_for_damage(&state.buffer);
    let totals = buff_totals(program, state, target);
    let spell_mods = spell_scoped_mods_for(
        program,
        state,
        source,
        SpellModifierQuery::new(
            SpellModifierProfile::new(spell_id, binding.request.profile_action),
            SpellModifierEffect::new(effect, binding.snapshot_effect),
            DamageFlags::PERIODIC,
        ),
        target,
        now,
    );
    let mastery_mult = target.map_or(1.0, |target| {
        (program.config.mastery_hook)(&MasteryCtx {
            program,
            instance: state,
            spell_id,
            spell_action: binding.request.profile_action,
            school: program
                .damage
                .action_at(binding.request.profile_action)
                .school,
            mastery: buffs::current_mastery_points(&crate::CombatView::new(program, state)),
            player_crit_pct: crit + totals.crit_pct,
            mastery_spell: program.config.mastery_spell,
            mastery_action: program.damage.mastery_action(),
            is_periodic: true,
            is_pet: matches!(source, ActorId::Pet(_)),
            source,
            target: Some(target),
            now,
        })
    });

    DamageSnapshot {
        ap: typed_attack_power_with(
            program,
            state,
            crate::state::WeaponApType::MainHand,
            &totals,
        ),
        sp: dynamic_base_powers(program, state, &totals).1,
        crit_pct: crit + totals.crit_pct + spell_mods.crit_chance_pct,
        vers_pct: vers + totals.vers_pct,
        mastery_mult,
        damage_mult: totals.damage_mult * spell_mods.damage_mult,
    }
}

#[cfg(test)]
pub(crate) fn capture_snapshot_fixture(
    view: crate::context::HookView<'_>,
    spell_id: u32,
    source: ActorId,
) -> DamageSnapshot {
    capture_snapshot_for(
        view.program,
        view.instance,
        {
            let effect = DamageEffectRef::new(spell_id, 0);
            let request = view
                .program
                .damage
                .diagnostic_bind_request(effect, effect, spell_id)
                .expect("snapshot fixture spell is finalized");

            crate::state::program::PeriodicDamageBinding {
                request,
                snapshot_effect: request.effect,
            }
        },
        source,
        view.target,
        view.now,
    )
}

pub(super) fn store_stronger_snapshot(
    program: &crate::state::CombatProgram,
    instance: &mut CombatInstance,
    local: LocalAuraIdx,
    key: AuraKey,
    snapshot: DamageSnapshot,
    now: SimTime,
) -> bool {
    let Some(binding) = program.aura_binding(local, key) else {
        return false;
    };
    let aura = instance.buffer.aura_at(binding.handle);

    if aura.snapshot_has != 0 && snapshot.damage_mult <= aura.snapshot_damage_mult {
        return false;
    }

    program.mutate_aura(
        instance,
        binding,
        AuraMutation::SetSnapshot(AuraSnapshot {
            has_snapshot: true,
            attack_power: snapshot.ap,
            spell_power: snapshot.sp,
            critical_chance: snapshot.crit_pct,
            versatility: snapshot.vers_pct,
            mastery_multiplier: snapshot.mastery_mult,
            damage_multiplier: snapshot.damage_mult,
        }),
        now,
    )
}

/// Refreshes a snapshot with a persistent damage multiplier without compounding it.
// #t(fn: rust_cyclomatic_complexity) snapshot refresh is one ordered validation, capture, multiplier replacement, and write transaction.
pub(crate) fn refresh_aura_snapshot_multiplier(
    ctx: &mut HookCtx<'_>,
    local: LocalAuraIdx,
    multiplier: f64,
) -> bool {
    // BOUNDS: local indices are created from the registered aura definition table.
    let aura = ctx.program.auras[local.as_usize()];

    if aura.periodic.is_none() || multiplier <= 0.0 {
        return false;
    }

    let Some(key) = context_aura_key(ctx, local) else {
        return false;
    };

    if !ctx
        .program
        .buffer_aura(ctx.instance, local, key)
        .is_some_and(wowlab_engine_domain::rotation::AuraSlot::is_occupied)
    {
        return false;
    }

    if aura.is_snapshot {
        let binding = ctx
            .program
            .damage
            .periodic_request(local)
            .expect("snapshot aura has a finalized periodic damage binding");
        let mut snapshot = capture_snapshot_for(
            ctx.program,
            ctx.instance,
            binding,
            ctx.source,
            ctx.target,
            ctx.now,
        );

        snapshot.damage_mult *= multiplier;

        return store_stronger_snapshot(ctx.program, ctx.instance, local, key, snapshot, ctx.now);
    }

    let Some(slot) = ctx.program.buffer_aura(ctx.instance, local, key) else {
        return false;
    };

    if slot.snapshot_has != 0 && multiplier <= slot.snapshot_damage_mult {
        return false;
    }

    let snapshot = AuraSnapshot {
        has_snapshot: true,
        attack_power: slot.snapshot_ap,
        spell_power: slot.snapshot_sp,
        critical_chance: slot.snapshot_crit,
        versatility: slot.snapshot_vers,
        mastery_multiplier: slot.snapshot_mastery_mult,
        damage_multiplier: multiplier,
    };

    let Some(binding) = ctx.program.aura_binding(local, key) else {
        return false;
    };

    ctx.program.mutate_aura(
        ctx.instance,
        binding,
        AuraMutation::SetSnapshot(snapshot),
        ctx.now,
    )
}

pub(super) fn revive_tick_chain(
    ctx: &mut HookCtx<'_>,
    local: LocalAuraIdx,
    aura: &crate::state::AuraData,
    key: AuraKey,
    previous_expiry: Option<f64>,
) {
    if aura.periodic.is_none() {
        return;
    }

    let Some(a) = ctx.program.buffer_aura(ctx.instance, local, key) else {
        return;
    };

    let terminal_at_previous_expiry = previous_expiry.is_some_and(|expiry| a.next_tick >= expiry);

    if !a.is_occupied()
        || (a.next_tick > ctx.now.as_secs_f64() && !terminal_at_previous_expiry)
        || a.tick_interval <= 0.0
    {
        return;
    }

    let next_tick = SimTime::from_secs_f64(ctx.now.as_secs_f64() + a.tick_interval);

    if next_tick.as_secs_f64() <= a.expires_at {
        if let Some(binding) = ctx.program.aura_binding(local, key) {
            ctx.program.mutate_aura(
                ctx.instance,
                binding,
                AuraMutation::SetNextTick(next_tick.as_secs_f64()),
                ctx.now,
            );
        }

        ctx.instance.schedule(Event::AuraTick {
            t: next_tick,
            aura: ctx
                .program
                .aura_event(local, key, ctx.target)
                .expect("periodic aura has a finalized event binding"),
        });
    }
}

pub(super) fn update_aura_slot(
    ctx: &mut HookCtx<'_>,
    request: AuraSlotRequest<'_>,
) -> Option<bool> {
    let AuraSlotRequest { local, key, .. } = request;
    let is_fresh = !ctx
        .program
        .buffer_aura(ctx.instance, local, key)?
        .is_occupied();

    if is_fresh {
        initialize_aura_slot(ctx, request);
    } else {
        refresh_aura_slot(ctx, request);
    }

    Some(is_fresh)
}

pub(super) fn initialize_aura_slot(ctx: &mut HookCtx<'_>, request: AuraSlotRequest<'_>) {
    let AuraSlotRequest {
        aura,
        local,
        key,
        base_dur_ms,
        base_dur,
        is_permanent,
    } = request;
    let expires_at = if is_permanent {
        PERMANENT_AURA_EXPIRES_AT_S
    } else {
        ctx.now.saturating_add(base_dur).as_secs_f64()
    };
    let stacks = if aura.apply_at_max_stacks {
        i32::from(aura.max_stacks)
    } else {
        i32::from(aura.doses).min(i32::from(aura.max_stacks))
    };

    let Some(binding) = ctx.program.aura_binding(local, key) else {
        return;
    };

    if !ctx.program.mutate_aura(
        ctx.instance,
        binding,
        AuraMutation::Activate(AuraActivation {
            expires_at,
            base_duration: f64::from(base_dur_ms) / MS_PER_SECOND,
            stacks,
            max_stacks: i32::from(aura.max_stacks),
        }),
        ctx.now,
    ) {
        return;
    }

    let stacks = wowlab_types::numeric::i32_to_u8_saturating(stacks);

    emit_aura_apply_event(
        ctx.program,
        ctx.instance,
        ctx.sink,
        key,
        aura.aura_id,
        stacks,
        ctx.now,
    );
}

pub(super) fn refresh_aura_slot(ctx: &mut HookCtx<'_>, request: AuraSlotRequest<'_>) {
    let AuraSlotRequest {
        aura,
        local,
        key,
        base_dur_ms,
        base_dur,
        is_permanent,
    } = request;
    let Some(a) = ctx.program.buffer_aura(ctx.instance, local, key) else {
        return;
    };
    let expires_at = (!is_permanent).then(|| {
        let expires_ms =
            wowlab_types::numeric::f64_to_u32_saturating_trunc(a.expires_at * MS_PER_SECOND);
        let remaining_ms = expires_ms.saturating_sub(ctx.now.as_millis());
        let carry_ms = match aura.refresh_behavior {
            wowlab_types::data::RefreshBehavior::Pandemic => {
                pandemic_carry_ms(base_dur_ms, remaining_ms)
            }
            wowlab_types::data::RefreshBehavior::Extend => remaining_ms,
            wowlab_types::data::RefreshBehavior::Tick => {
                let interval_ms = wowlab_types::numeric::f64_to_u32_saturating_round(
                    a.tick_interval * MS_PER_SECOND,
                );

                if interval_ms == 0 {
                    0
                } else {
                    remaining_ms % interval_ms
                }
            }
            wowlab_types::data::RefreshBehavior::Clip
            | wowlab_types::data::RefreshBehavior::None
            | wowlab_types::data::RefreshBehavior::Duration => 0,
        };
        // docref:start auras-pandemic-carry
        ctx.now
            .saturating_add(base_dur)
            .saturating_add(SimTime::from_millis(carry_ms))
            .as_secs_f64()
        // docref:end auras-pandemic-carry
    });

    let stacks = refreshed_stacks(aura, a.stacks);

    if let Some(binding) = ctx.program.aura_binding(local, key) {
        ctx.program.mutate_aura(
            ctx.instance,
            binding,
            AuraMutation::Refresh(AuraRefresh { expires_at, stacks }),
            ctx.now,
        );
    }

    let stacks = wowlab_types::numeric::i32_to_u8_saturating(stacks);

    emit_aura_refresh_event(
        ctx.program,
        ctx.instance,
        ctx.sink,
        key,
        aura.aura_id,
        stacks,
        ctx.now,
    );
}

pub(super) fn initialize_or_revive_periodic(
    ctx: &mut HookCtx<'_>,
    request: AuraSlotRequest<'_>,
    is_fresh: bool,
    previous_expiry: Option<f64>,
) {
    let AuraSlotRequest {
        aura,
        local,
        key,
        base_dur_ms,
        ..
    } = request;

    let Some(periodic) = aura.periodic.as_ref() else {
        return;
    };

    if !is_fresh {
        revive_tick_chain(ctx, local, aura, key, previous_expiry);

        return;
    }

    let effective_tick_ms =
        buffs::effective_periodic_tick_ms(&ctx.view().combat(), local, periodic.tick_interval_ms);
    let base_interval_s = f64::from(effective_tick_ms) / MS_PER_SECOND;
    let tick_interval_ms = buffs::effective_periodic_interval_ms(
        &ctx.view().combat(),
        local,
        periodic.tick_interval_ms,
        periodic.hasted_ticks,
    );
    let tick_interval_now = f64::from(tick_interval_ms) / MS_PER_SECOND;

    if let Some(a) = ctx.program.buffer_aura(ctx.instance, local, key) {
        let time_rate = if a.time_rate_multiplier > 0.0 {
            a.time_rate_multiplier
        } else {
            1.0
        };

        let next_tick = if periodic.tick_on_application {
            ctx.now.as_secs_f64()
        } else {
            ctx.now.as_secs_f64() + tick_interval_now * time_rate
        };

        if let Some(binding) = ctx.program.aura_binding(local, key) {
            ctx.program.mutate_aura(
                ctx.instance,
                binding,
                AuraMutation::SetSchedule(AuraSchedule {
                    base_tick_interval: base_interval_s,
                    tick_interval: tick_interval_now * time_rate,
                    next_tick,
                    time_rate_multiplier: time_rate,
                    remaining_ticks: wowlab_types::numeric::f64_to_i32_saturating_ceil(
                        f64::from(base_dur_ms) / MS_PER_SECOND / tick_interval_now,
                    ),
                }),
                ctx.now,
            );
        }
    }

    if let Some(a) = ctx.program.buffer_aura(ctx.instance, local, key) {
        ctx.instance.schedule(Event::AuraTick {
            t: SimTime::from_secs_f64(a.next_tick),
            aura: ctx
                .program
                .aura_event(local, key, ctx.target)
                .expect("periodic aura has a finalized event binding"),
        });
    }
}

pub(super) fn refresh_snapshot(ctx: &mut HookCtx<'_>, request: AuraSlotRequest<'_>) {
    let AuraSlotRequest {
        aura, local, key, ..
    } = request;

    if !aura.is_snapshot || aura.periodic.is_none() {
        return;
    }

    let Some(binding) = ctx.program.damage.periodic_request(local) else {
        return;
    };
    let snapshot = capture_snapshot_for(
        ctx.program,
        ctx.instance,
        binding,
        ctx.source,
        ctx.target,
        ctx.now,
    );

    store_stronger_snapshot(ctx.program, ctx.instance, local, key, snapshot, ctx.now);
}

pub(super) fn is_rolling_periodic(aura: &crate::state::AuraData) -> bool {
    aura.periodic.is_some_and(|periodic| {
        matches!(
            periodic.effect,
            crate::state::PeriodicKind::RollingDamageAp { .. }
                | crate::state::PeriodicKind::RollingDamageSp { .. }
        )
    })
}

/// Ticks left on the aura slot at `now`; `0.0` when absent or expired.
pub(super) fn rolling_ticks_left(ctx: &HookCtx<'_>, local: LocalAuraIdx, key: AuraKey) -> f64 {
    ctx.program
        .buffer_aura(ctx.instance, local, key)
        .map_or(0.0, |slot| {
            if slot.tick_interval <= 0.0 {
                return 0.0;
            }

            ((slot.expires_at - ctx.now.as_secs_f64()) / slot.tick_interval).max(0.0)
        })
}

/// Blends this application into the rolling per-tick multiplier so total damage is preserved without diluting tick value.
pub(super) fn combine_rolling_multiplier(
    ctx: &mut HookCtx<'_>,
    request: AuraSlotRequest<'_>,
    old_ticks_left: f64,
    new_multiplier: f64,
) {
    let AuraSlotRequest {
        aura,
        local,
        key,
        base_dur_ms,
        ..
    } = request;

    if !is_rolling_periodic(aura) {
        return;
    }
    // The slot's tick_interval is the cadence ticks actually fire at (haste
    // and cadence modifiers applied) — the same units rolling_ticks_left uses.

    let Some(tick_interval) = ctx
        .program
        .buffer_aura(ctx.instance, local, key)
        .map(|slot| slot.tick_interval)
        .filter(|interval| *interval > 0.0)
    else {
        return;
    };
    let new_base_ticks = f64::from(base_dur_ms) / MS_PER_SECOND / tick_interval;
    let new_ticks_left = rolling_ticks_left(ctx, local, key);
    let Some(pool) = ctx.program.aura_pool_index(local, key) else {
        return;
    };

    ctx.instance.runtime.pools.rolling_tick_mult.combine(
        pool,
        old_ticks_left,
        new_base_ticks,
        new_ticks_left,
        new_multiplier,
    );
}

pub(super) fn restore_active_shapeshift_form(ctx: &mut HookCtx<'_>) {
    let restored = ctx
        .program
        .effects
        .shapeshift_auras()
        .iter()
        .rev()
        .find_map(|entry| {
            let aura = ctx.program.aura(entry.local);

            ctx.instance
                .buffer
                .aura_at(entry.handle)
                .is_occupied()
                .then_some(aura.shapeshift_form)
        })
        .unwrap_or(0);

    ctx.instance.buffer.player_mut().shapeshift_form = restored;
    tracing::trace!(form = restored, "restored active shapeshift form");
}