wowlab_engine_combat/handler/

mod.rs

// #t(file: rust_pub_api_docs) docs will be added after stabilization

//! [`wowlab_engine_ports::SpecHandler`] implementation backed by `CombatInstance` + `DenseBuffer`.

pub(crate) mod can_cast;
mod introspection;
mod orchestration;
mod reset;
mod spec_handler;

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

#[cfg(not(feature = "rotation-optimizations"))]
use can_cast::pool_wait;
use can_cast::{CastCandidate, CastReject, candidate_rejection, reject_to_wait};
#[cfg(feature = "rotation-optimizations")]
use can_cast::{candidate_time_horizon, rejection_ready_at};
use wowlab_engine_domain::rotation::{EvalResult, RotationEngine};
use wowlab_engine_ports::{SpecAction, SpecRuntimeError};
use wowlab_engine_rng::SimRng;
use wowlab_engine_telemetry::TelemetrySink;
use wowlab_types::sim::SimTime;

use crate::{
    context::{CombatCtx, CombatCtxRequest, HookCtx, HookCtxRequest},
    state::{CombatInstance, CombatProgram},
};

/// Placeholder seed replaced with the real per-iteration seed in `on_sim_start` before any roll; never used to sample.
const PLACEHOLDER_RNG: (u64, u32) = (0, 0);

#[derive(Clone, Copy)]
pub(crate) enum AuraResetScope {
    All,
    Player,
}

#[derive(Clone, Copy)]
pub(crate) enum LockMode {
    Unlocked,
    Casting,
    Gcd,
    Both,
}

/// Capability token whose private constructor confines raw aura clearing to reset orchestration.
pub(crate) struct AuraResetToken(AuraResetScope);

impl AuraResetToken {
    #[cfg(test)]
    pub(crate) const fn test_only(scope: AuraResetScope) -> Self {
        Self(scope)
    }

    pub(crate) fn scope(self) -> AuraResetScope {
        self.0
    }
}

// docref:start spec-handlers-combat-handler
#[derive(Debug)]
pub struct CombatHandler {
    pub(super) program: CombatProgram,
    pub(super) instance: CombatInstance,
    pub(super) engine: RotationEngine,
    pub(super) rng: SimRng,
    /// Guards against a roll reaching the placeholder RNG before `on_sim_start` installs the real seed.
    pub(super) rng_seeded: bool,
    pub(super) last_resource_sync: SimTime,
}
// docref:end spec-handlers-combat-handler

impl CombatHandler {
    #[must_use]
    pub fn from_built(built: crate::BuiltCombatSystem) -> Self {
        let (program, instance, rotation) = built.into_parts();

        Self {
            program,
            instance,
            engine: rotation,
            rng: SimRng::from_prefix(PLACEHOLDER_RNG.0, PLACEHOLDER_RNG.1),
            rng_seeded: false,
            last_resource_sync: SimTime::ZERO,
        }
    }

    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    pub fn instance(&self) -> &CombatInstance {
        &self.instance
    }

    #[cfg(feature = "test-support")]
    #[doc(hidden)]
    pub fn instance_mut(&mut self) -> &mut CombatInstance {
        &mut self.instance
    }

    #[cfg(feature = "test-support")]
    #[doc(hidden)]
    pub fn program_and_instance_mut(&mut self) -> (&CombatProgram, &mut CombatInstance) {
        (&self.program, &mut self.instance)
    }

    /// Test-support-only access to the program-branded event coordinate.
    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    pub fn __test_scheduled_spell(
        &self,
        spell: wowlab_types::sim::SpellIdx,
    ) -> wowlab_engine_ports::ScheduledSpellBinding {
        let local = self
            .program
            .spell_local(spell.as_u32())
            .expect("test spell belongs to the finalized program");

        self.program.scheduled_spell(local)
    }

    /// Test-support-only diagnostic conversion for legacy port event fixtures.
    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    #[must_use]
    pub fn __test_aura_local_raw(&self, aura_id: u32) -> u8 {
        self.program
            .aura_local(aura_id)
            .expect("test aura belongs to the finalized program")
            .raw()
    }

    /// Test-support-only mint for a program-owned aura lifecycle event.
    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    #[must_use]
    pub fn __test_aura_event(
        &self,
        aura_id: u32,
        key: wowlab_types::sim::AuraKey,
        target: Option<wowlab_types::sim::EnemyIdx>,
    ) -> wowlab_engine_ports::AuraEventRef {
        let local = self
            .program
            .aura_local(aura_id)
            .expect("test aura belongs to the finalized program");
        let binding = self
            .program
            .aura_event(local, key, target)
            .expect("test aura key belongs to the finalized program");

        wowlab_engine_ports::AuraEventRef::from_binding(binding)
    }

    /// Test-support-only mint for a program-owned guardian callback event.
    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    pub fn __test_guardian_event(
        &self,
        guardian: crate::GuardianHandle,
        ability: Option<u16>,
    ) -> wowlab_engine_ports::GuardianEventBinding {
        self.program
            .runtime_events
            .guardian(guardian.as_u32(), guardian.generation(), ability)
    }

    #[must_use]
    pub fn program(&self) -> crate::HookProgramView<'_> {
        crate::HookProgramView::new(&self.program)
    }

    /// Current selected enemy, if the encounter has an eligible target.
    #[must_use]
    pub fn current_target(&self) -> Option<wowlab_types::sim::EnemyIdx> {
        self.instance.current_target()
    }

    /// Read the specialization-owned runtime without exposing the combat instance.
    #[must_use]
    pub fn spec_runtime<T>(&self) -> Option<&T>
    where
        T: wowlab_engine_ports::SpecRuntime,
    {
        self.instance.spec_runtime::<T>()
    }

    /// Runs an operation with a combat context borrowing this handler's runtime state.
    pub fn with_combat_ctx<R>(
        &mut self,
        sink: &mut TelemetrySink,
        request: CombatCtxRequest,
        apply: impl FnOnce(&mut CombatCtx<'_>) -> R,
    ) -> R {
        self.assert_rng_seeded();
        let rng = &mut self.rng;
        let mut rng_fn = || rng.next_f64();
        let mut ctx = CombatCtx {
            program: &self.program,
            instance: &mut self.instance,
            sink,
            now: request.now,
            rng: &mut rng_fn,
            source: request.source,
            target: request.target,
        };

        apply(&mut ctx)
    }

    /// Runs an operation with a hook context borrowing this handler's runtime state.
    pub fn with_hook_ctx<R>(
        &mut self,
        sink: &mut TelemetrySink,
        request: HookCtxRequest,
        apply: impl FnOnce(&mut HookCtx<'_>) -> R,
    ) -> R {
        self.assert_rng_seeded();
        let rng = &mut self.rng;
        let mut rng_fn = || rng.next_f64();
        let mut ctx = HookCtx::new(
            crate::context::HookCtxServices {
                program: &self.program,
                instance: &mut self.instance,
                sink,
                rng: &mut rng_fn,
            },
            request,
        );

        apply(&mut ctx)
    }

    pub(super) fn assert_rng_seeded(&self) {
        debug_assert!(
            self.rng_seeded,
            "CombatHandler RNG used before on_sim_start installed the per-iteration seed"
        );
    }

    pub(super) fn evaluate_rotation(&mut self, now: SimTime) -> Option<SpecAction> {
        let trace_enabled = tracing::enabled!(tracing::Level::TRACE);

        self.evaluate_rotation_with_trace(now, trace_enabled)
    }

    // #t(fn: rust_cyclomatic_complexity) the diagnostic eager path and guarded lazy experiment share one public decision boundary.
    pub(super) fn evaluate_rotation_with_trace(
        &mut self,
        now: SimTime,
        trace_enabled: bool,
    ) -> Option<SpecAction> {
        #[cfg(feature = "rotation-optimizations")]
        if !trace_enabled
            && !self.engine.has_decision_trace()
            && self.engine.prepared().lazy_cast_validation_safe()
            && self.actor_is_ready_for_lazy_rotation(now)
        {
            return self.evaluate_rotation_lazily(now);
        }

        let target = self.instance.current_target();
        let mut masked = std::mem::take(&mut self.instance.runtime.scratch.rotation_masks);
        let mut candidates = std::mem::take(&mut self.instance.runtime.scratch.rotation_candidates);
        let mut trace_reasons =
            std::mem::take(&mut self.instance.runtime.scratch.rotation_trace_reasons);

        masked.clear();
        candidates.clear();
        #[cfg(feature = "rotation-optimizations")]
        let mut decision_horizon =
            self.program
                .rotation
                .exact_decision_horizon(&self.program, &self.instance, now);

        if trace_enabled {
            trace_reasons
                .get_or_insert_with(|| {
                    Vec::with_capacity(self.program.rotation.availability().len())
                })
                .clear();
        }

        for binding in self.program.rotation.availability().iter().copied() {
            #[cfg(test)]
            {
                self.instance.runtime.rotation_spells_scanned += 1;
            };

            let candidate = target
                .map(|target| CastCandidate::resolve_planned(&self.instance, binding, target));
            let reason = match candidate {
                Some(candidate) => match candidate_rejection(
                    &crate::context::CombatView::new(&self.program, &self.instance),
                    candidate,
                    now,
                ) {
                    Ok(()) => {
                        debug_assert!(
                            candidates.len() < candidates.capacity(),
                            "candidate scratch capacity is smaller than the finalized availability plan"
                        );
                        candidates.push(candidate);

                        continue;
                    }
                    Err(reason) => reason,
                },
                None => CastReject::NoTarget,
            };

            #[cfg(feature = "rotation-optimizations")]
            if let Some(candidate) = candidate
                && let Some(ready_at) = rejection_ready_at(
                    &crate::context::CombatView::new(&self.program, &self.instance),
                    candidate,
                    reason,
                    now,
                )
            {
                decision_horizon = Some(
                    decision_horizon.map_or(ready_at, |current: SimTime| current.min(ready_at)),
                );
            }

            let slot = self.instance.buffer.spell_mut_at(binding.spell_slot);

            if slot.is_enabled == 0 {
                continue;
            }

            debug_assert!(
                masked.len() < masked.capacity(),
                "ordinary rotation mask scratch capacity is smaller than the finalized availability plan"
            );
            masked.push((binding.spell_slot, slot.is_enabled));

            if trace_enabled && let Some(reasons) = trace_reasons.as_mut() {
                debug_assert!(
                    reasons.len() < reasons.capacity(),
                    "rotation trace-reason scratch capacity is smaller than the finalized availability plan"
                );
                reasons.push((binding.spell.as_u32(), reason));
            }

            slot.is_enabled = 0;
        }

        self.log_mask_transitions(now, trace_reasons.as_deref(), trace_enabled);
        let result = self.evaluate_compiled_rotation(now);

        for &(handle, enabled) in &masked {
            self.instance.buffer.spell_mut_at(handle).is_enabled = enabled;
        }

        self.instance.runtime.scratch.rotation_masks = masked;
        self.instance.runtime.scratch.rotation_candidates = candidates;
        self.instance.runtime.scratch.rotation_trace_reasons = trace_reasons;

        #[cfg(not(feature = "rotation-optimizations"))]
        let decision_horizon = None;

        self.resolve_rotation_result(now, result, decision_horizon)
    }

    /// Evaluate a locked actor's APL with actions that cannot execute through every active lock masked.
    pub(super) fn evaluate_rotation_while_locked(
        &mut self,
        lock_mode: LockMode,
        now: SimTime,
    ) -> Option<SpecAction> {
        let target = self.instance.current_target();
        let mut disabled = std::mem::take(&mut self.instance.runtime.scratch.locked_action_masks);

        disabled.clear();

        for binding in self.program.rotation.availability().iter().copied() {
            #[cfg(test)]
            {
                self.instance.runtime.rotation_spells_scanned += 1;
            };

            let executable_while_locked = target
                .map(|target| CastCandidate::resolve_planned(&self.instance, binding, target))
                .is_some_and(|candidate| {
                    let spell = candidate.effective(&self.program);

                    match lock_mode {
                        LockMode::Unlocked => true,
                        LockMode::Casting => spell.requirements.availability.usable_while_casting,
                        LockMode::Gcd => spell.behavior.off_gcd,
                        LockMode::Both => {
                            spell.requirements.availability.usable_while_casting
                                && spell.behavior.off_gcd
                        }
                    }
                });

            if executable_while_locked {
                continue;
            }

            let slot = self.instance.buffer.spell_mut_at(binding.spell_slot);

            if slot.is_enabled == 0 {
                continue;
            }

            debug_assert!(
                disabled.len() < disabled.capacity(),
                "locked-action mask scratch capacity is smaller than the finalized availability plan"
            );
            disabled.push((binding.spell_slot, slot.is_enabled));
            slot.is_enabled = 0;
        }

        #[cfg(feature = "rotation-optimizations")]
        let action = {
            let trace_enabled = tracing::enabled!(tracing::Level::TRACE);

            if !trace_enabled
                && !self.engine.has_decision_trace()
                && self.engine.prepared().lazy_cast_validation_safe()
            {
                self.evaluate_rotation_lazily(now)
            } else {
                self.evaluate_rotation_with_trace(now, trace_enabled)
            }
        };

        #[cfg(not(feature = "rotation-optimizations"))]
        let action = self.evaluate_rotation(now);

        for &(handle, enabled) in &disabled {
            self.instance.buffer.spell_mut_at(handle).is_enabled = enabled;
        }

        self.instance.runtime.scratch.locked_action_masks = disabled;

        action
    }

    #[cfg(feature = "rotation-optimizations")]
    fn actor_is_ready_for_lazy_rotation(&self, now: SimTime) -> bool {
        let player = self.instance.buffer.player();
        let ready_at = SimTime::from_secs_f64(player.gcd_end)
            .max(SimTime::from_secs_f64(player.cast_end))
            .max(SimTime::from_secs_f64(player.channel_end));

        now >= ready_at
    }

    #[cfg(feature = "rotation-optimizations")]
    fn evaluate_rotation_lazily(&mut self, now: SimTime) -> Option<SpecAction> {
        let target = self.instance.current_target();
        let mut masked = std::mem::take(&mut self.instance.runtime.scratch.rotation_masks);
        let mut candidates = std::mem::take(&mut self.instance.runtime.scratch.rotation_candidates);

        masked.clear();
        candidates.clear();

        let result = loop {
            let result = self.evaluate_compiled_rotation(now);

            if !result.is_cast() {
                break result;
            }

            let Some(binding) = self.program.rotation.availability_binding(result.spell_id) else {
                break result;
            };

            #[cfg(test)]
            {
                self.instance.runtime.rotation_spells_scanned += 1;
            }

            let Some(target) = target else {
                if !self.mask_lazy_candidate(binding, &mut masked) {
                    break result;
                }

                continue;
            };
            let candidate = CastCandidate::resolve_planned(&self.instance, binding, target);

            match candidate_rejection(
                &crate::context::CombatView::new(&self.program, &self.instance),
                candidate,
                now,
            ) {
                Ok(()) => {
                    debug_assert!(
                        candidates.len() < candidates.capacity(),
                        "candidate scratch capacity is smaller than the finalized availability plan"
                    );
                    candidates.push(candidate);

                    break result;
                }
                Err(_) if self.mask_lazy_candidate(binding, &mut masked) => {}
                Err(_) => break result,
            }
        };

        for &(handle, enabled) in &masked {
            self.instance.buffer.spell_mut_at(handle).is_enabled = enabled;
        }

        let selected_cast = result.is_cast() && !candidates.is_empty();
        let needs_horizon = !result.is_wait() && !result.is_use_item() && !selected_cast;
        let decision_horizon = needs_horizon
            .then(|| self.exact_rotation_decision_horizon(now))
            .flatten();

        self.instance.runtime.scratch.rotation_masks = masked;
        self.instance.runtime.scratch.rotation_candidates = candidates;

        self.resolve_rotation_result(now, result, decision_horizon)
    }

    #[cfg(feature = "rotation-optimizations")]
    fn mask_lazy_candidate(
        &mut self,
        binding: crate::state::RotationSpellBinding,
        masked: &mut Vec<(wowlab_engine_domain::rotation::SpellSlotHandle, i32)>,
    ) -> bool {
        let slot = self.instance.buffer.spell_mut_at(binding.spell_slot);

        if slot.is_enabled == 0 {
            return false;
        }

        debug_assert!(
            masked.len() < masked.capacity(),
            "ordinary rotation mask scratch capacity is smaller than the finalized availability plan"
        );
        masked.push((binding.spell_slot, slot.is_enabled));
        slot.is_enabled = 0;

        true
    }

    #[cfg(feature = "rotation-optimizations")]
    fn exact_rotation_decision_horizon(&mut self, now: SimTime) -> Option<SimTime> {
        let target = self.instance.current_target();
        let control_ready_at = self
            .instance
            .actor_control_ready_at(wowlab_types::sim::ActorId::Player, now);
        let has_school_lockout = self
            .instance
            .runtime
            .control
            .school_lockouts
            .contains_key(wowlab_types::sim::ActorId::Player);
        let mut horizon =
            self.program
                .rotation
                .exact_decision_horizon(&self.program, &self.instance, now);

        for binding in self.program.rotation.availability().iter().copied() {
            #[cfg(test)]
            {
                self.instance.runtime.rotation_spells_scanned += 1;
            }

            let Some(target) = target else {
                continue;
            };
            let candidate = CastCandidate::resolve_planned(&self.instance, binding, target);
            let view = crate::context::CombatView::new(&self.program, &self.instance);
            let Some(ready_at) =
                candidate_time_horizon(&view, candidate, now, control_ready_at, has_school_lockout)
            else {
                continue;
            };

            horizon = Some(horizon.map_or(ready_at, |current: SimTime| current.min(ready_at)));
        }

        horizon
    }

    /// Trace each change in why a spell is masked out of rotation evaluation.
    ///
    /// `REJECT_CANCAST` only fires for the spell the rotation actually selected.
    /// A spell that is unavailable all fight therefore never appears in a trace.
    /// A `BUFFER_STATE` dump reads `is_enabled = 0` for it, because it is taken after this pre-pass.
    /// This is the only place the real mask reason is observable.
    fn log_mask_transitions(
        &mut self,
        now: SimTime,
        masked_reasons: Option<&[(u32, CastReject)]>,
        trace_enabled: bool,
    ) {
        if !trace_enabled {
            return;
        }

        let masked_reasons = masked_reasons.unwrap_or_default();
        let previous_reasons = self.instance.runtime.mask_reasons.get_or_insert_default();

        for &(spell_id, reason) in masked_reasons {
            let discriminant = std::mem::discriminant(&reason);

            if previous_reasons.insert(spell_id, discriminant) == Some(discriminant) {
                continue;
            }

            // #t(rust_log_in_loop) one line per mask-reason change is the whole point of the signal.
            tracing::trace!(
                t = %now.as_secs_f64(),
                spell_id,
                reason = %reason,
                "SPELL_MASKED"
            );
        }

        previous_reasons
            .retain(|spell_id, _| masked_reasons.iter().any(|(masked, _)| masked == spell_id));
    }

    fn evaluate_compiled_rotation(&mut self, now: SimTime) -> EvalResult {
        wowlab_types::bench_metrics::record_rotation_evaluation();
        tracing::trace!(t = %now.as_secs_f64(), buffer = %self.instance.buffer.dump(), "BUFFER_STATE");
        let result = self
            .engine
            .evaluate(&mut self.instance.buffer, now.as_secs_f64());

        tracing::trace!(t = %now.as_secs_f64(), kind = result.kind, spell_id = result.spell_id, "EVAL_RESULT");

        result
    }

    // #t(fn: rust_cyclomatic_complexity) sequential rotation result handling with multiple action kinds
    fn resolve_rotation_result(
        &mut self,
        now: SimTime,
        result: EvalResult,
        decision_horizon: Option<SimTime>,
    ) -> Option<SpecAction> {
        if result.is_cast() {
            return self.resolve_cast_result(now, result, decision_horizon);
        }

        if result.is_wait() {
            let wait_until =
                now.saturating_add(SimTime::from_secs_f64(f64::from(result.wait_time)));

            return Some(SpecAction::Wait {
                until_ms: wait_until,
            });
        }

        if result.is_pool() {
            return self.rotation_fallthrough(now, decision_horizon);
        }

        if result.is_use_item() {
            if let Some(gear_slot) = result.item_slot() {
                if let Some(item_use) = self.program.rotation.item_use(gear_slot) {
                    let spell_id = item_use.action.spell.as_u32();
                    let Some(target) = self.instance.current_target() else {
                        return self.rotation_fallthrough(now, decision_horizon);
                    };
                    let candidate =
                        CastCandidate::resolve_planned(&self.instance, item_use.action, target);

                    match candidate_rejection(
                        &crate::context::CombatView::new(&self.program, &self.instance),
                        candidate,
                        now,
                    ) {
                        Ok(()) => {
                            self.instance.runtime.casting.selected_candidate = Some(candidate);
                            tracing::trace!(t = %now.as_secs_f64(), spell_id, slot = ?gear_slot, "USE_ITEM_CAST");

                            return Some(SpecAction::Cast {
                                spell: self.program.scheduled_spell(candidate.requested_local),
                                empower_rank: resolved_empower_rank(
                                    candidate.requested(&self.program),
                                    result.empower_rank,
                                )?,
                                source: wowlab_types::sim::ActorId::Player,
                                target,
                            });
                        }
                        Err(reason) => {
                            tracing::trace!(spell_id, slot = ?gear_slot, reason = %reason, "USE_ITEM_REJECT_CANCAST");

                            return reject_to_wait(
                                &crate::context::CombatView::new(&self.program, &self.instance),
                                candidate,
                                Some(reason),
                                now,
                            );
                        }
                    }
                }

                tracing::trace!(slot = ?gear_slot, "use_item: no spell mapped");
            } else {
                tracing::warn!(raw = result.spell_id, "use_item: invalid slot");
            }
        }

        tracing::trace!(t = %now.as_secs_f64(), "ROTATION_NONE");

        self.rotation_fallthrough(now, decision_horizon)
    }

    fn resolve_cast_result(
        &mut self,
        now: SimTime,
        result: EvalResult,
        decision_horizon: Option<SimTime>,
    ) -> Option<SpecAction> {
        let spell_id = result.spell_id;
        let Some(candidate) = self
            .instance
            .runtime
            .scratch
            .rotation_candidates
            .binary_search_by_key(&spell_id, |candidate| {
                candidate.requested_spell_id(&self.program)
            })
            .ok()
            .and_then(|index| {
                self.instance
                    .runtime
                    .scratch
                    .rotation_candidates
                    .get(index)
                    .copied()
            })
        else {
            tracing::trace!(
                t = %now.as_secs_f64(),
                spell_id,
                reason = %CastReject::UnknownSpell,
                "REJECT_CANCAST"
            );

            return self.rotation_fallthrough(now, decision_horizon);
        };
        let requested = candidate.requested(&self.program);
        let Some(empower_rank) = resolved_empower_rank(requested, result.empower_rank) else {
            self.instance
                .record_runtime_error(SpecRuntimeError::invalid_empower_rank(
                    spell_id,
                    result.empower_rank,
                    requested.empower_rank_count,
                ));

            return None;
        };

        self.instance.runtime.casting.selected_candidate = Some(candidate);
        tracing::trace!(t = %now.as_secs_f64(), spell_id, "CAST");

        Some(SpecAction::Cast {
            spell: self.program.scheduled_spell(candidate.requested_local),
            empower_rank,
            source: wowlab_types::sim::ActorId::Player,
            target: candidate.target,
        })
    }

    #[cfg(feature = "rotation-optimizations")]
    fn rotation_fallthrough(
        &self,
        _now: SimTime,
        decision_horizon: Option<SimTime>,
    ) -> Option<SpecAction> {
        decision_horizon.map(|until_ms| SpecAction::Wait { until_ms })
    }

    #[cfg(not(feature = "rotation-optimizations"))]
    #[expect(
        clippy::unnecessary_wraps,
        reason = "both optimization configurations expose the same optional fallthrough contract"
    )]
    fn rotation_fallthrough(
        &self,
        now: SimTime,
        _decision_horizon: Option<SimTime>,
    ) -> Option<SpecAction> {
        Some(pool_wait(&self.program, &self.instance, now))
    }
}

fn resolved_empower_rank(spell: &crate::state::SpellData, requested_rank: u8) -> Option<u8> {
    if spell.empower_rank_count == 0 {
        return (requested_rank == 0 || spell.max_empower_aura_id != 0).then_some(0);
    }

    let rank = requested_rank.max(1);

    (rank <= spell.empower_rank_count).then_some(rank)
}