wowlab_engine_combat/builder/

draft.rs

// #t(file: rust_too_many_lines_in_file) the construction draft owns the single cold freeze boundary and its invariants are kept together for auditability.

use wowlab_engine_domain::{
    encounter::EnemyActorDefinition,
    pool::PoolIndex,
    rotation::{BufferRequirements, CatalogHints},
};
use wowlab_engine_ports::EngineError;
use wowlab_types::{
    data::CooldownCategoryId,
    game::GearSlot,
    sim::{ActorId, AuraIdx, AuraKey, AuraOn, FastMap, IntMap, PetIdx, SimTime, SpellIdx},
};

use super::{
    BuilderError, BuiltCombatSystem,
    buffer_init::{InitialBufferConfig, populate_initial_buffer},
    compile::{
        CooldownBypass, CostBypass, RotationCompileInput, SpellGate, SpellOverride, bind_rotation,
        emit_rotation, prepare_rotation,
    },
};
use crate::{
    AccumulatingImpactProc, AuraBinding, CastHookFn, DriverSpellModifier, ImpactProc,
    LandedImpactProc, LocalAuraIdx, LocalSpellIdx, LocalThresholdIdx, PassiveDriverEffect,
    PeriodicDriver, ResourceGainProc, RppmBinding, RppmTracker, SpellBinding, SpellEffectData,
    SystemRppmBinding, ThresholdTracker, WeaponEnchantBinding,
    state::{
        AuraData, AutoAttackData, BaseStats, BuffEffect, BufferBindings, CombatInstance,
        CombatProgram, CombatRuntime, EmpowerReleaseHookFn, ImpactEffectProc, LocalRppmIdx,
        PetActionBar, ProgramConfig, ResolvedSystemRppmBinding, ScratchBuffers, SpellData,
        WeaponImbueBinding, try_push_effect,
    },
};

#[derive(Debug)]
pub(crate) struct DraftDefinitions {
    pub(crate) enemies: Vec<EnemyActorDefinition>,
    pub(crate) spells: Vec<SpellData>,
    pub(crate) empower_cast_times_ms: Vec<u32>,
    pub(crate) spell_effects: Vec<SpellEffectData>,
    pub(crate) auras: Vec<AuraData>,
    pub(crate) aura_bindings: Vec<(AuraBinding, u32)>,
    pub(crate) spell_bindings: Vec<(SpellBinding, u32)>,
    pub(crate) auto_attacks: Vec<AutoAttackData>,
    pub(crate) cast_hooks: Vec<Option<CastHookFn>>,
    pub(crate) empower_release_hooks: Vec<Option<EmpowerReleaseHookFn>>,
    pub(crate) tick_hooks: Vec<Option<CastHookFn>>,
    pub(crate) player_cast_hooks: Vec<CastHookFn>,
    pub(crate) resource_threshold_triggers: Vec<crate::state::ResourceThresholdTrigger>,
    pub(crate) impact_procs: Vec<ImpactProc>,
    pub(crate) landed_impact_procs: Vec<LandedImpactProc>,
    pub(crate) accumulating_impact_procs: Vec<AccumulatingImpactProc>,
    pub(crate) impact_effect_procs: Vec<ImpactEffectProc>,
    pub(crate) driver_spell_modifiers: Vec<DriverSpellModifier>,
    pub(crate) passive_driver_effects: Vec<PassiveDriverEffect>,
    pub(crate) periodic_drivers: Vec<PeriodicDriver>,
    pub(crate) talent_ranks: IntMap<u32, u8>,
    pub(crate) resource_gain_procs: Vec<ResourceGainProc>,
    pub(crate) item_use_spells: Vec<(GearSlot, u32)>,
    pub(crate) rppm_trackers: Vec<RppmTracker>,
    pub(crate) rppm_bindings: Vec<(RppmBinding, LocalRppmIdx)>,
    pub(crate) system_rppm_bindings: Vec<(SystemRppmBinding, ResolvedSystemRppmBinding)>,
    pub(crate) threshold_trackers: Vec<ThresholdTracker>,
    pub(crate) weapon_enchant_bindings: Vec<WeaponEnchantBinding>,
    pub(crate) weapon_imbue_bindings: Vec<WeaponImbueBinding>,
    pub(crate) precombat_auras: Vec<LocalAuraIdx>,
    pub(crate) talent_aura_stacks: Vec<(LocalAuraIdx, u8)>,
    pub(crate) stealth_aura_id: Option<u32>,
}

impl DraftDefinitions {
    pub(crate) fn new(enemies: Vec<EnemyActorDefinition>) -> Self {
        Self {
            enemies,
            spells: Vec::new(),
            empower_cast_times_ms: Vec::new(),
            spell_effects: Vec::new(),
            auras: Vec::new(),
            aura_bindings: Vec::new(),
            spell_bindings: Vec::new(),
            auto_attacks: Vec::new(),
            cast_hooks: Vec::new(),
            empower_release_hooks: Vec::new(),
            tick_hooks: Vec::new(),
            player_cast_hooks: Vec::new(),
            resource_threshold_triggers: Vec::new(),
            impact_procs: Vec::new(),
            landed_impact_procs: Vec::new(),
            accumulating_impact_procs: Vec::new(),
            impact_effect_procs: Vec::new(),
            driver_spell_modifiers: Vec::new(),
            passive_driver_effects: Vec::new(),
            periodic_drivers: Vec::new(),
            talent_ranks: IntMap::default(),
            resource_gain_procs: Vec::new(),
            item_use_spells: Vec::new(),
            rppm_trackers: Vec::new(),
            rppm_bindings: Vec::new(),
            system_rppm_bindings: Vec::new(),
            threshold_trackers: Vec::new(),
            weapon_enchant_bindings: Vec::new(),
            weapon_imbue_bindings: Vec::new(),
            precombat_auras: Vec::new(),
            talent_aura_stacks: Vec::new(),
            stealth_aura_id: None,
        }
    }
}

#[derive(Debug)]
pub(crate) struct DraftIndexes {
    pub(crate) spell_by_id: IntMap<u32, LocalSpellIdx>,
    pub(crate) aura_by_id: IntMap<u32, LocalAuraIdx>,
    pub(crate) aura_by_identity: FastMap<(u32, AuraOn), LocalAuraIdx>,
    pub(crate) cooldown_categories: PoolIndex<CooldownCategoryId, LocalSpellIdx>,
    pub(crate) charge_categories: PoolIndex<CooldownCategoryId, LocalSpellIdx>,
    pub(crate) item_rppm_indices: IntMap<u32, LocalRppmIdx>,
    pub(crate) system_rppm_indices: IntMap<u32, LocalRppmIdx>,
    pub(crate) enchant_rppm_indices: IntMap<u32, LocalRppmIdx>,
    pub(crate) enchant_buff_spell_ids: IntMap<u32, u32>,
}

#[derive(Debug)]
struct FrozenProgramBindings {
    scheduled_spells: wowlab_engine_event_authority::ScheduledSpellCatalog,
    runtime_events: wowlab_engine_event_authority::RuntimeEventCatalog,
    scheduled_spell_executions: Box<[crate::state::program::ScheduledSpellExecution]>,
    layout_fingerprint: wowlab_engine_domain::rotation::LayoutFingerprint,
    buffer_bindings: BufferBindings,
}

/// Mutable composition stage before combat-system finalization.
#[derive(Debug)]
#[must_use]
// docref:start spec-handlers-built-combat-system
pub struct CombatSystemDraft {
    pub(crate) spec_identity_brand: Option<u32>,
    pub(crate) definitions: DraftDefinitions,
    pub(crate) indexes: DraftIndexes,
    pub(crate) runtime: CombatRuntime,
    pub(crate) config: ProgramConfig,
    pub(crate) names: Vec<Box<str>>,
    pub(crate) spell_ids: FastMap<String, u32>,
    pub(crate) damage_spell_ids: Vec<u32>,
    pub(crate) effect_spell_ids: Vec<u32>,
    pub(crate) generated_damage_identities: Vec<crate::DamageActionId>,
    pub(crate) aura_ids: FastMap<String, u32>,
    pub(crate) hints: CatalogHints,
    pub(crate) gating: Vec<SpellGate>,
    pub(crate) cost_bypass: Vec<CostBypass>,
    pub(crate) cooldown_bypass: Vec<CooldownBypass>,
    pub(crate) overrides: Vec<SpellOverride>,
    pub(crate) resource_max: f64,
    pub(crate) talent_ranks: Vec<(String, u8)>,
    pub(crate) talent_spell_ids: Vec<u32>,
    pub(crate) selected_talent_spell_ids: Vec<u32>,
    pub(crate) selected_replaced_spell_ids: Vec<u32>,
    pub(crate) disabled_spell_ids: Vec<u32>,
    pub(crate) initial_weapon_imbues: Vec<(&'static str, bool)>,
    pub(crate) ground_effects: Vec<crate::GroundEffectDefinition>,
    pub(crate) hook_flat_damage: FastMap<u32, f64>,
    pub(crate) hook_scalars: FastMap<u32, f64>,
}
// docref:end spec-handlers-built-combat-system

impl CombatSystemDraft {
    /// Bind a codegen-owned semantic aura coordinate during late composition.
    pub fn bind_aura(&mut self, binding: AuraBinding, aura_id: u32) {
        self.definitions.aura_bindings.push((binding, aura_id));
    }

    /// Bind a codegen-owned semantic spell coordinate during late composition.
    pub fn bind_spell(&mut self, binding: SpellBinding, spell_id: u32) {
        self.definitions.spell_bindings.push((binding, spell_id));
    }

    /// Replace the immutable specialization configuration before finalization.
    pub fn set_spec_config<T>(&mut self, config: T)
    where
        T: wowlab_engine_ports::SpecConfig,
    {
        self.config.spec_config = Box::new(config);
    }

    /// Replace the resettable specialization runtime before finalization.
    pub fn set_spec_runtime<T>(&mut self, runtime: T)
    where
        T: wowlab_engine_ports::SpecRuntime,
    {
        self.runtime.set_spec_runtime(Box::new(runtime));
    }

    pub fn set_bug_toggles(&mut self, bugs: wowlab_engine_ports::BugToggles) {
        self.config.bugs = bugs;
    }

    pub fn set_cast_latency(&mut self, cast_latency: wowlab_engine_ports::CastLatency) {
        self.config.cast_latency = cast_latency;
    }

    pub fn set_raid_events(&mut self, raid_events: &[wowlab_engine_ports::RaidEventConfig]) {
        self.config.raid_events = raid_events.to_vec();
    }

    pub fn set_external_buffs(
        &mut self,
        external_buffs: &[wowlab_engine_ports::ExternalBuffConfig],
    ) {
        self.config.external_buffs = external_buffs.to_vec();
    }

    /// Attach an action bar to the persistent pet identified by its creature id.
    pub fn set_pet_action_bar(&mut self, npc_id: u32, action_bar: PetActionBar) -> bool {
        let Some(attack) = self
            .definitions
            .auto_attacks
            .iter_mut()
            .find(|attack| attack.is_pet && attack.npc_id == Some(npc_id))
        else {
            return false;
        };

        attack.pet_action_bar = Some(action_bar);

        true
    }

    pub fn disable_spell(&mut self, spell_id: u32) {
        if !self.disabled_spell_ids.contains(&spell_id) {
            self.disabled_spell_ids.push(spell_id);
        }
    }

    /// Declares a non-castable damage identity referenced by late composition wiring.
    pub fn register_damage_identity(
        &mut self,
        _name: impl Into<String>,
        identity: crate::DamageActionId,
    ) {
        let spell_id = identity.spell_id();

        if !self.damage_spell_ids.contains(&spell_id) {
            self.damage_spell_ids.push(spell_id);
        }

        if !self.generated_damage_identities.contains(&identity) {
            self.generated_damage_identities.push(identity);
        }
    }

    /// Registers the branded action owning one generated effect coordinate.
    pub fn register_damage_effect_identity(
        &mut self,
        name: impl Into<String>,
        effect: crate::DamageEffectId,
    ) {
        self.register_damage_identity(name, effect.action());
    }

    #[cfg(any(test, feature = "test-support"))]
    #[doc(hidden)]
    pub fn register_diagnostic_damage_identity(&mut self, name: impl Into<String>, spell_id: u32) {
        wowlab_types::bench_metrics::record_keyed_lookup();
        self.register_damage_identity(name, crate::DamageActionId::new(0, spell_id));
    }

    /// Apply a build-time spell patch and atomically refresh its buffer projections.
    pub fn patch_spell(
        &mut self,
        spell: LocalSpellIdx,
        patch: impl FnOnce(&mut SpellData),
    ) -> bool {
        let Some(data) = self.definitions.spells.get_mut(spell.as_usize()) else {
            return false;
        };
        let identity = (data.spell_id, data.name_idx);

        patch(data);
        (data.spell_id, data.name_idx) = identity;

        true
    }

    /// Apply a build-time patch to every finalized spell definition.
    pub fn patch_spells(&mut self, mut patch: impl FnMut(&mut SpellData)) {
        for spell in &mut self.definitions.spells {
            let identity = (spell.spell_id, spell.name_idx);

            patch(spell);
            (spell.spell_id, spell.name_idx) = identity;
        }
    }

    /// Apply a build-time aura patch to the authoritative definition.
    pub fn patch_aura(&mut self, aura: LocalAuraIdx, patch: impl FnOnce(&mut AuraData)) -> bool {
        let Some(data) = self.definitions.auras.get_mut(aura.as_usize()) else {
            return false;
        };
        let identity = (data.aura_id, data.name_idx, data.on, data.propagates_to_pet);

        patch(data);
        (data.aura_id, data.name_idx, data.on, data.propagates_to_pet) = identity;

        true
    }

    /// Register an aura added after the declarative combat system has been built.
    ///
    /// This synchronizes the name table, definition, aura-id index, and identity index.
    /// Persistent buffer slots are allocated by the consuming finalization transaction.
    ///
    /// # Errors
    ///
    /// Returns an error when the runtime aura registry exceeds its local-index capacity.
    pub fn register_aura(
        &mut self,
        name: impl Into<Box<str>>,
        mut aura: AuraData,
    ) -> Result<LocalAuraIdx, EngineError> {
        aura.name_idx = u16::try_from(self.names.len()).map_err(|error| {
            EngineError::spec_construction(format!(
                "combat definition name registry exceeds u16 capacity: {error}"
            ))
        })?;
        let local =
            LocalAuraIdx::new(u8::try_from(self.definitions.auras.len()).map_err(|error| {
                EngineError::spec_construction(format!(
                    "runtime aura registry exceeds u8 capacity: {error}"
                ))
            })?);
        let aura_id = aura.aura_id;
        let on = aura.on;
        let propagates_to_pet = aura.propagates_to_pet;

        self.names.push(name.into());
        self.definitions.auras.push(aura);
        self.indexes.aura_by_id.insert(aura_id, local);
        self.indexes
            .aura_by_identity
            .entry((aura_id, on))
            .or_insert(local);

        if propagates_to_pet {
            self.indexes
                .aura_by_identity
                .entry((aura_id, AuraOn::Pet))
                .or_insert(local);
        }

        Ok(local)
    }

    /// Registers an impact proc during composition.
    pub fn register_impact_proc(&mut self, proc: ImpactProc) {
        self.definitions.impact_procs.push(proc);
    }

    /// Registers a landed-impact proc during composition.
    pub fn register_landed_impact_proc(&mut self, proc: LandedImpactProc) {
        self.definitions.landed_impact_procs.push(proc);
    }

    /// Registers an accumulating impact proc during composition.
    pub fn register_accumulating_impact_proc(&mut self, proc: AccumulatingImpactProc) {
        self.definitions.accumulating_impact_procs.push(proc);
    }

    /// Registers a resource-gain proc during composition.
    pub fn register_resource_gain_proc(&mut self, proc: ResourceGainProc) {
        self.definitions.resource_gain_procs.push(proc);
    }

    /// Registers an RPPM tracker during composition.
    ///
    /// # Errors
    ///
    /// Returns an error when the local tracker-index capacity is exhausted.
    pub fn register_rppm_tracker(
        &mut self,
        tracker: RppmTracker,
    ) -> Result<LocalRppmIdx, EngineError> {
        let local = LocalRppmIdx::new(u8::try_from(self.definitions.rppm_trackers.len()).map_err(
            |error| {
                EngineError::spec_construction(format!(
                    "RPPM tracker registry exceeds u8 capacity: {error}"
                ))
            },
        )?);

        self.definitions.rppm_trackers.push(tracker);

        Ok(local)
    }

    /// Register one equipped weapon-enchant source and its shared RPPM tracker.
    ///
    /// Duplicate enchantment IDs return `false`; the first binding installs the impact dispatcher.
    ///
    /// # Errors
    ///
    /// Returns an error when the local tracker-index capacity is exhausted.
    pub fn register_weapon_enchant_binding(
        &mut self,
        binding: WeaponEnchantBinding,
        tracker: RppmTracker,
    ) -> Result<bool, EngineError> {
        if self
            .indexes
            .enchant_rppm_indices
            .contains_key(&binding.enchantment_id)
        {
            return Ok(false);
        }

        let first = self.definitions.weapon_enchant_bindings.is_empty();
        let tracker = self.register_rppm_tracker(tracker)?;

        self.indexes
            .enchant_rppm_indices
            .insert(binding.enchantment_id, tracker);
        self.indexes
            .enchant_buff_spell_ids
            .insert(binding.enchantment_id, binding.buff_spell_id);
        self.definitions.weapon_enchant_bindings.push(binding);

        if first {
            self.register_impact_proc(ImpactProc::new(
                crate::systems::weapon_enchants_on_player_impact,
            ));
        }

        Ok(true)
    }

    /// Registers an accumulated-threshold tracker during composition.
    ///
    /// # Errors
    ///
    /// Returns an error when the local tracker-index capacity is exhausted.
    pub fn register_threshold_tracker(
        &mut self,
        tracker: ThresholdTracker,
    ) -> Result<LocalThresholdIdx, EngineError> {
        let local = LocalThresholdIdx::new(
            u8::try_from(self.definitions.threshold_trackers.len()).map_err(|error| {
                EngineError::spec_construction(format!(
                    "threshold tracker registry exceeds u8 capacity: {error}"
                ))
            })?,
        );

        self.definitions.threshold_trackers.push(tracker);

        Ok(local)
    }

    /// Appends an aura to the precombat application set.
    pub fn push_precombat_aura(&mut self, aura: LocalAuraIdx) {
        self.definitions.precombat_auras.push(aura);
    }

    /// Include or exclude an aura from the precombat application set.
    pub fn set_precombat_aura(&mut self, aura: LocalAuraIdx, enabled: bool) {
        if enabled {
            if !self.definitions.precombat_auras.contains(&aura) {
                self.definitions.precombat_auras.push(aura);
            }
        } else {
            self.definitions
                .precombat_auras
                .retain(|candidate| *candidate != aura);
        }
    }

    /// Removes an aura from every precombat talent projection.
    pub fn remove_precombat_aura(&mut self, aura: LocalAuraIdx) {
        self.definitions
            .precombat_auras
            .retain(|candidate| *candidate != aura);
        self.definitions
            .talent_aura_stacks
            .retain(|(candidate, _)| *candidate != aura);
    }

    /// Registers a hook fired after every player cast.
    pub fn register_player_cast_hook(&mut self, hook: CastHookFn) {
        self.definitions.player_cast_hooks.push(hook);
    }

    /// Returns a registered aura definition.
    #[must_use]
    pub fn aura(&self, aura: LocalAuraIdx) -> Option<&AuraData> {
        self.definitions.auras.get(aura.as_usize())
    }

    pub fn auras(&self) -> &[AuraData] {
        &self.definitions.auras
    }

    pub fn precombat_auras(&self) -> &[LocalAuraIdx] {
        &self.definitions.precombat_auras
    }

    /// Returns a registered RPPM tracker.
    #[must_use]
    pub fn rppm_tracker(&self, tracker: LocalRppmIdx) -> Option<&RppmTracker> {
        self.definitions.rppm_trackers.get(tracker.as_usize())
    }

    /// Returns a registered impact proc.
    #[must_use]
    pub fn impact_proc(&self, index: usize) -> Option<&ImpactProc> {
        self.definitions.impact_procs.get(index)
    }

    /// Returns the number of registered impact procs.
    #[must_use]
    pub fn impact_proc_count(&self) -> usize {
        self.definitions.impact_procs.len()
    }

    /// Returns a registered lowered impact-effect proc.
    #[must_use]
    pub fn impact_effect_proc(&self, index: usize) -> Option<&ImpactEffectProc> {
        self.definitions.impact_effect_procs.get(index)
    }

    /// Returns the number of registered lowered impact-effect procs.
    #[must_use]
    pub fn impact_effect_proc_count(&self) -> usize {
        self.definitions.impact_effect_procs.len()
    }

    /// Returns the lowered spell-effect program arena for read-only inspection.
    #[must_use]
    pub fn spell_effects(&self) -> &[SpellEffectData] {
        &self.definitions.spell_effects
    }

    /// Returns the selected rank of a talent spell.
    #[must_use]
    pub fn talent_rank(&self, spell_id: u32) -> Option<u8> {
        self.definitions.talent_ranks.get(&spell_id).copied()
    }

    /// Returns the number of registered RPPM trackers.
    #[must_use]
    pub fn rppm_tracker_count(&self) -> usize {
        self.definitions.rppm_trackers.len()
    }

    /// Returns the number of registered player-cast hooks.
    #[must_use]
    pub fn player_cast_hook_count(&self) -> usize {
        self.definitions.player_cast_hooks.len()
    }

    /// Returns the number of registered spells.
    #[must_use]
    pub fn spell_count(&self) -> usize {
        self.definitions.spells.len()
    }

    /// Returns the first auto-attack definition.
    #[must_use]
    pub fn first_auto_attack(&self) -> Option<&AutoAttackData> {
        self.definitions.auto_attacks.first()
    }

    /// Applies a build-time patch to the registered auto-attack definitions.
    pub fn patch_auto_attacks(&mut self, patch: impl FnOnce(&mut [AutoAttackData])) {
        patch(&mut self.definitions.auto_attacks);
    }

    /// Register a system-level RPPM source from its DBC driver spell.
    ///
    /// The definition and driver lookup are committed together.
    /// Re-registering the same driver is idempotent and returns its existing local index.
    ///
    /// # Errors
    ///
    /// Returns a typed spec-construction error when the driver has no finite positive RPPM rate.
    /// It also errors when the local tracker-index capacity is exhausted.
    pub fn register_system_rppm_from_data(
        &mut self,
        driver_spell_id: u32,
    ) -> Result<LocalRppmIdx, EngineError> {
        if let Some(local) = self
            .indexes
            .system_rppm_indices
            .get(&driver_spell_id)
            .copied()
        {
            return Ok(local);
        }

        let driver = SpellIdx::from_raw(driver_spell_id);
        let Some((rppm, _)) = self.config.game_data.rppm(driver) else {
            return Err(EngineError::spec_construction_source(
                BuilderError::missing_system_rppm_data(driver_spell_id),
            ));
        };

        if !rppm.is_finite() || rppm <= 0.0 {
            return Err(EngineError::spec_construction_source(
                BuilderError::invalid_system_rppm_data(driver_spell_id, rppm),
            ));
        }

        let tracker = RppmTracker {
            rppm,
            last_attempt_time: 0.0,
            last_proc_time: 0.0,
            accumulated_blp: 0.0,
            haste_scales: self
                .config
                .game_data
                .rppm_haste_scales(driver)
                .unwrap_or(false),
            crit_scales: self
                .config
                .game_data
                .rppm_crit_scales(driver)
                .unwrap_or(false),
            auto_attack_speed_scales: false,
            blp_enabled: true,
        };

        let tracker_count = self.definitions.rppm_trackers.len();

        if let Err(source) = u8::try_from(tracker_count) {
            return Err(EngineError::spec_construction_source(
                BuilderError::system_rppm_registry_full(driver_spell_id, tracker_count, source),
            ));
        }

        let local = self.register_rppm_tracker(tracker)?;

        self.indexes
            .system_rppm_indices
            .insert(driver_spell_id, local);

        Ok(local)
    }

    /// Freeze a system RPPM tracker and its category recovery behind a semantic token.
    ///
    /// # Errors
    ///
    /// Returns an error when the driver spell has no valid RPPM data or the tracker registry is full.
    pub fn bind_system_rppm(
        &mut self,
        binding: SystemRppmBinding,
        driver_spell_id: u32,
    ) -> Result<(), EngineError> {
        let tracker = self.register_system_rppm_from_data(driver_spell_id)?;
        let recovery_ms = self
            .config
            .game_data
            .proc_category_recovery_ms(SpellIdx::from_raw(driver_spell_id))
            .unwrap_or(0);

        self.definitions.system_rppm_bindings.push((
            binding,
            ResolvedSystemRppmBinding {
                tracker,
                recovery_ms,
            },
        ));

        Ok(())
    }

    /// Apply a build-time base-stat patch and refresh the primary resource projection.
    pub fn patch_base_stats(&mut self, patch: impl FnOnce(&mut BaseStats)) {
        patch(&mut self.config.base_stats);
        self.resource_max = self.config.base_stats.resource_max;
    }

    /// Return the resolved baseline combat stats used by content composition.
    #[must_use]
    pub fn base_combat_stats(&self) -> &wowlab_engine_ports::CombatStats {
        &self.config.base_stats.stats
    }

    #[must_use]
    pub fn base_stats(&self) -> &BaseStats {
        &self.config.base_stats
    }

    #[must_use]
    pub fn game_data(&self) -> &wowlab_engine_gamedata::ResolvedGameData {
        &self.config.game_data
    }

    #[must_use]
    pub fn spell_local(&self, spell_id: u32) -> Option<LocalSpellIdx> {
        self.indexes.spell_by_id.get(&spell_id).copied()
    }

    #[must_use]
    pub fn aura_local(&self, aura_id: u32) -> Option<LocalAuraIdx> {
        self.indexes.aura_by_id.get(&aura_id).copied()
    }

    #[must_use]
    pub fn bug_enabled(&self, bug: &wowlab_engine_ports::GameBug) -> bool {
        self.config.bugs.enabled(bug)
    }

    #[must_use]
    pub fn spec_config<T>(&self) -> Option<&T>
    where
        T: wowlab_engine_ports::SpecConfig,
    {
        self.config
            .spec_config
            .as_ref()
            .as_any()
            .downcast_ref::<T>()
    }

    /// Appends an effect to a draft aura before finalization.
    ///
    /// # Panics
    ///
    /// Panics in debug builds if `aura` is not registered, or in all builds if its fixed-capacity effect list is full.
    pub fn set_aura_effect(&mut self, aura: LocalAuraIdx, effect: BuffEffect) {
        let Some(data) = self.definitions.auras.get_mut(aura.as_usize()) else {
            debug_assert!(false, "aura index {} out of bounds", aura.raw());

            return;
        };
        let result = try_push_effect(&mut data.effects, effect);

        assert!(
            result.is_ok(),
            "no free effect slot for aura {}",
            aura.raw()
        );
    }

    /// Removes talent-dependent DBC-derived rows to prevent duplicate modifiers and returns the number cleared.
    pub fn mask_aura_dbc_effect(
        &mut self,
        aura: LocalAuraIdx,
        source_spell_id: u32,
        effect_index: u8,
    ) -> usize {
        let Some(data) = self.definitions.auras.get_mut(aura.as_usize()) else {
            debug_assert!(false, "aura index {} out of bounds", aura.raw());

            return 0;
        };
        let mut masked = 0;

        for slot in &mut data.effects {
            if slot
                .as_ref()
                .and_then(BuffEffect::dbc_source)
                .is_some_and(|source| source == (source_spell_id, effect_index))
            {
                *slot = None;
                masked += 1;
            }
        }

        masked
    }

    /// Duplicates rows lowered from one DBC effect while preserving their resolved payload.
    ///
    /// Intended for modeled live-game bugs where the server applies the same modifier twice.
    /// Content identifies only the source coordinate.
    pub fn duplicate_aura_dbc_effect(
        &mut self,
        aura: LocalAuraIdx,
        source_spell_id: u32,
        effect_index: u8,
    ) -> usize {
        let Some(data) = self.definitions.auras.get(aura.as_usize()) else {
            debug_assert!(false, "aura index {} out of bounds", aura.raw());

            return 0;
        };
        let effects: Vec<_> = data
            .effects
            .iter()
            .flatten()
            .copied()
            .filter(|effect| effect.dbc_source() == Some((source_spell_id, effect_index)))
            .collect();
        let duplicated = effects.len();

        for effect in effects {
            self.set_aura_effect(aura, effect);
        }

        duplicated
    }

    /// Register an always-present spell modifier under its real spell/passive driver.
    pub fn register_driver_spell_modifier(&mut self, modifier: DriverSpellModifier) {
        self.definitions.driver_spell_modifiers.push(modifier);
    }

    /// Register an always-present player effect under its real spell/passive driver.
    pub fn register_passive_driver_effect(&mut self, effect: PassiveDriverEffect) {
        self.definitions.passive_driver_effects.push(effect);
    }

    /// Register a real weapon-imbue action and initialize its persistent equipment state.
    pub fn register_weapon_imbue(
        &mut self,
        spell_id: u32,
        key: &'static str,
        initially_active: bool,
    ) {
        self.definitions
            .weapon_imbue_bindings
            .push(WeaponImbueBinding { spell_id, key });
        self.initial_weapon_imbues.push((key, initially_active));
    }

    /// Register encounter-lifetime periodic work under its real spell/passive driver.
    pub fn register_periodic_driver(&mut self, driver: PeriodicDriver) {
        self.definitions.periodic_drivers.push(driver);
    }

    /// Registers an authored ground effect for binding during finalization.
    ///
    /// # Errors
    ///
    /// Returns an error when the ground-effect registry exceeds its `u16` identity space.
    pub fn register_ground_effect(
        &mut self,
        definition: crate::GroundEffectDefinition,
    ) -> Result<crate::GroundEffectId, EngineError> {
        let local = u16::try_from(self.ground_effects.len()).map_err(|error| {
            EngineError::spec_construction(format!(
                "ground-effect registry exceeds u16 capacity: {error}"
            ))
        })?;

        self.ground_effects.push(definition);

        Ok(crate::GroundEffectId(local))
    }

    /// Freezes an authored flat-damage payload into the finalized action plan.
    pub fn set_hook_flat_damage(&mut self, action: crate::DamageActionId, amount: f64) {
        self.hook_flat_damage.insert(action.spell_id(), amount);
    }

    /// Freezes an authored scalar into the finalized action plan.
    pub fn set_hook_scalar(&mut self, action: crate::DamageActionId, value: f64) {
        self.hook_scalars.insert(action.spell_id(), value);
    }

    /// Consume this composition draft and create the immutable program and mutable instance.
    ///
    /// # Errors
    ///
    /// Returns an error when validation, game-data resolution, rotation compilation, or final binding fails.
    // #t(fn: rust_map_err_pure_wrap) rotation compilation must retain the EngineError rotation category and its typed source.
    // #t(fn: rust_cyclomatic_complexity) finalization is one ordered validation, freeze, bind, and instance-construction transaction.
    // #t(fn: rust_max_fn_lines) finalization keeps the one-way draft-to-program freeze transaction auditable in construction order.
    pub fn finalize(
        mut self,
        rotation: &wowlab_types::sim::Rotation,
    ) -> Result<BuiltCombatSystem, EngineError> {
        self.validate_identities()?;
        let mut scheduled_spell_ids = self
            .definitions
            .spells
            .iter()
            .map(SpellData::idx)
            .collect::<Vec<_>>();

        let mut missing_health_trigger = None;

        for effect in self
            .definitions
            .auras
            .iter()
            .flat_map(|aura| aura.effects.iter().flatten())
        {
            if let BuffEffect::HealthThresholdTrigger { spell_id, .. } = effect {
                let spell = SpellIdx::from_raw(*spell_id);

                if !scheduled_spell_ids.contains(&spell) {
                    scheduled_spell_ids.push(spell);
                }
            }
        }

        let scheduled_spells = wowlab_engine_event_authority::ScheduledSpellCatalog::new(
            scheduled_spell_ids.iter().copied(),
        );

        for effect in self
            .definitions
            .auras
            .iter_mut()
            .flat_map(|aura| aura.effects.iter_mut().flatten())
        {
            if let BuffEffect::HealthThresholdTrigger {
                spell_id,
                scheduled,
                ..
            } = effect
            {
                *scheduled = scheduled_spells.bind_spell_id(SpellIdx::from_raw(*spell_id));

                if scheduled.is_none() {
                    missing_health_trigger = Some(*spell_id);
                }
            }
        }

        if let Some(spell_id) = missing_health_trigger {
            return Err(EngineError::spec_construction(format!(
                "health trigger {spell_id} is absent from the finalized event-spell catalog"
            )));
        }

        let mut effects = crate::state::program::EffectPlan::compile(
            &self.definitions.auras,
            &self.definitions.passive_driver_effects,
        );
        let aura_dependency_graph = crate::state::program::AuraDependencyGraph::compile(
            &self.definitions.auras,
            &self.definitions.spells,
            &self.definitions.spell_effects,
            &self.config,
        );

        self.size_scratch_buffers();
        let reachable_damage_spell_ids = self.reachable_damage_spell_ids();
        let damage = crate::state::program::DamagePlan::compile(
            &self.config,
            &self.definitions.spells,
            &self.definitions.auras,
            &self.definitions.passive_driver_effects,
            &self.definitions.spell_effects,
            &self.effect_spell_ids,
            &self.generated_damage_identities,
            &reachable_damage_spell_ids,
            &self.damage_spell_ids,
            &effects,
            &self.definitions.driver_spell_modifiers,
            &self.definitions.impact_effect_procs,
            &self.definitions.periodic_drivers,
            &self.definitions.landed_impact_procs,
            &self.definitions.auto_attacks,
            &self.hook_flat_damage,
            &self.hook_scalars,
        )
        .map_err(EngineError::spec_construction)?;
        let scheduled_spell_executions = scheduled_spell_ids
            .iter()
            .enumerate()
            .map(|(index, spell)| -> Result<_, EngineError> {
                if index < self.definitions.spells.len() {
                    Ok(crate::state::program::ScheduledSpellExecution::Registered(
                        LocalSpellIdx::new(u8::try_from(index).map_err(|error| {
                            EngineError::spec_construction(format!(
                                "scheduled spell registry exceeds local-spell capacity: {error}"
                            ))
                        })?),
                    ))
                } else {
                    Ok(damage.finalize_action_for_spell(spell.as_u32()).map_or(
                        crate::state::program::ScheduledSpellExecution::TriggerOnlyEmpty,
                        crate::state::program::ScheduledSpellExecution::TriggerOnly,
                    ))
                }
            })
            .collect::<Result<Box<[_]>, _>>()?;
        let ground_effects =
            crate::state::program::compile_ground_effect_plans(&self.ground_effects, &damage)
                .map_err(|error| EngineError::spec_construction(error.to_string()))?;

        let rotation_preparation = prepare_rotation(&RotationCompileInput {
            rotation,
            spell_ids: &self.spell_ids,
            aura_ids: &self.aura_ids,
            secondary_resource_name: self.config.base_stats.secondary_resource_name.as_deref(),
            primary_resource_type: self.config.base_stats.resource_type,
            secondary_resource_type: self.config.base_stats.secondary_resource_type,
            hints: &self.hints,
            gating: &self.gating,
            cost_bypass: &self.cost_bypass,
            cooldown_bypass: &self.cooldown_bypass,
            overrides: &self.overrides,
        })
        .map_err(EngineError::rotation_compile)?;
        let buffer_requirements = self.buffer_requirements();
        let prepared = bind_rotation(rotation_preparation, &buffer_requirements)
            .map_err(EngineError::rotation_compile)?;

        let disabled_spell_ids = std::mem::take(&mut self.disabled_spell_ids);
        let initial_weapon_imbues = std::mem::take(&mut self.initial_weapon_imbues);
        let resource_max = self.resource_max;
        let talent_ranks = std::mem::take(&mut self.talent_ranks);
        let talent_spell_ids = std::mem::take(&mut self.talent_spell_ids);
        let selected_talent_spell_ids = std::mem::take(&mut self.selected_talent_spell_ids);
        let selected_replaced_spell_ids = std::mem::take(&mut self.selected_replaced_spell_ids);
        let buffer_bindings = BufferBindings::build(
            prepared.schema(),
            &buffer_requirements,
            &self.definitions,
            &talent_ranks,
            &initial_weapon_imbues,
        )
        .map_err(EngineError::spec_construction_source)?;
        let (absorb_capacity, damage_transfer_capacity) = buffer_bindings
            .aura_bindings()
            .map(|binding| {
                // BOUNDS: concrete aura bindings are built from this finalized definition slice.
                self.definitions.auras[binding.local.as_usize()]
                    .effects
                    .iter()
                    .flatten()
                    .fold((0, 0), |(absorbs, transfers), effect| match effect {
                        BuffEffect::Absorb(_) => (absorbs + 1, transfers),
                        BuffEffect::DamageTransfer(_) => (absorbs, transfers + 1),
                        _ => (absorbs, transfers),
                    })
            })
            .fold((0, 0), |(absorbs, transfers), counts| {
                (absorbs + counts.0, transfers + counts.1)
            });

        self.runtime.scratch.size_absorb_scratch(absorb_capacity);
        self.runtime
            .scratch
            .size_damage_transfer_scratch(damage_transfer_capacity);
        self.runtime.health.active_absorbs = crate::state::BoundedVec::new(absorb_capacity);
        let rotation_plan = crate::state::program::RotationPlan::compile(
            &prepared,
            crate::state::program::RotationPlanInputs {
                spells: &self.definitions.spells,
                spell_by_id: &self.indexes.spell_by_id,
                auras: &self.definitions.auras,
                aura_by_id: &self.indexes.aura_by_id,
                bindings: &buffer_bindings,
                passive_driver_effects: &self.definitions.passive_driver_effects,
                primary_resource_type: self.config.base_stats.resource_type,
                secondary_resource_type: self.config.base_stats.secondary_resource_type,
                enemy_count: self.definitions.enemies.len(),
                item_use_spells: &self.definitions.item_use_spells,
            },
            &self.config.game_data,
        )
        .map_err(EngineError::spec_construction_source)?;

        self.runtime
            .scratch
            .size_rotation_masks(rotation_plan.availability().len());

        effects.bind_aura_slots(
            &buffer_bindings,
            &self.definitions.auras,
            &self.config.game_data,
            self.definitions.enemies.len(),
        );
        self.runtime.scratch.health_threshold_triggers =
            Vec::with_capacity(effects.health_threshold_capacity());
        effects.bind_spell_modifier_actions(
            &damage,
            &self.definitions.auras,
            &self.definitions.passive_driver_effects,
        );

        if !effects.validate(
            self.definitions.auras.len(),
            self.definitions.passive_driver_effects.len(),
        ) {
            return Err(EngineError::spec_construction(
                "finalized effect plan contains an out-of-range identity".to_string(),
            ));
        }

        let aura_dependencies = crate::state::program::AuraDependencyPlan::bind(
            aura_dependency_graph,
            &self.definitions.auras,
            prepared.schema(),
            &buffer_bindings,
            self.definitions.enemies.len(),
        );

        if !aura_dependencies.validate(self.definitions.auras.len(), self.definitions.spells.len())
        {
            return Err(EngineError::spec_construction(
                "finalized aura dependency plan contains an out-of-range identity".to_string(),
            ));
        }

        let engine = emit_rotation(prepared).map_err(EngineError::rotation_compile)?;
        let layout_fingerprint = engine.schema().layout_fingerprint();
        let buffer = engine.schema().new_bound_buffer();

        let (program, mut runtime) = self.into_program_and_runtime(
            FrozenProgramBindings {
                scheduled_spells,
                runtime_events: wowlab_engine_event_authority::RuntimeEventCatalog::new(),
                scheduled_spell_executions,
                layout_fingerprint,
                buffer_bindings,
            },
            effects,
            (damage, ground_effects),
            aura_dependencies,
            rotation_plan,
        );

        runtime.companions.pet_actions = vec![None; program.auto_attacks.len()];
        runtime.pools.resize_finalized(
            program.buffer_bindings.aura_binding_count(),
            program.spells.len(),
        );
        let mut instance = CombatInstance::new(&program, runtime, buffer)?;

        validate_layout_fingerprints(&program, &instance)?;

        populate_initial_buffer(
            &program,
            &mut instance,
            &InitialBufferConfig {
                resource_max,
                talent_ranks: &talent_ranks,
                talent_spell_ids: &talent_spell_ids,
                selected_talent_spell_ids: &selected_talent_spell_ids,
                selected_replaced_spell_ids: &selected_replaced_spell_ids,
            },
        );

        #[cfg(feature = "rotation-optimizations")]
        crate::systems::initialize_cooldown_projections(&program, &mut instance);

        for spell_id in disabled_spell_ids {
            if let Some(local) = program.spell_local(spell_id) {
                let slot = instance
                    .buffer
                    .spell_mut_at(program.buffer_bindings.spell(local));

                slot.is_enabled = 0;
            }
        }

        for (key, active) in initial_weapon_imbues {
            if let Some(slot) = program.buffer_weapon_imbue_mut(&mut instance, key) {
                slot.is_active = i32::from(active);
                slot.is_inactive = i32::from(!active);
            }
        }

        Ok(BuiltCombatSystem {
            program,
            instance,
            rotation: engine,
        })
    }

    pub(crate) fn size_scratch_buffers(&mut self) {
        self.runtime.scratch = ScratchBuffers {
            absorb_indices: crate::state::BoundedVec::default(),
            active_damage_transfers: Vec::new(),
            hooks: Vec::with_capacity(self.definitions.player_cast_hooks.len()),
            impacts: Vec::with_capacity(self.definitions.impact_procs.len()),
            landed_impacts: Vec::with_capacity(self.definitions.landed_impact_procs.len()),
            landed_impact_events: Vec::with_capacity(u8::MAX as usize + 1),
            accumulating_impacts: Vec::with_capacity(
                self.definitions.accumulating_impact_procs.len(),
            ),
            impact_effects: Vec::with_capacity(self.definitions.impact_effect_procs.len()),
            resource_gains: Vec::with_capacity(self.definitions.resource_gain_procs.len()),
            rotation_masks: Vec::new(),
            locked_action_masks: Vec::new(),
            rotation_candidates: Vec::new(),
            rotation_trace_reasons: None,
            effect_program_frames: Vec::new(),
            effect_program_frame_count: 0,
            target_workspaces: Vec::new(),
            health_threshold_triggers: Vec::new(),
        };
        self.runtime.scratch.size_execution_scratch(
            self.definitions.spell_effects.len(),
            self.definitions.spells.len(),
            self.definitions.enemies.len(),
        );

        for (capacity, required) in [
            (
                self.runtime.scratch.hooks.capacity(),
                self.definitions.player_cast_hooks.len(),
            ),
            (
                self.runtime.scratch.impacts.capacity(),
                self.definitions.impact_procs.len(),
            ),
            (
                self.runtime.scratch.landed_impacts.capacity(),
                self.definitions.landed_impact_procs.len(),
            ),
            (
                self.runtime.scratch.accumulating_impacts.capacity(),
                self.definitions.accumulating_impact_procs.len(),
            ),
            (
                self.runtime.scratch.impact_effects.capacity(),
                self.definitions.impact_effect_procs.len(),
            ),
            (
                self.runtime.scratch.resource_gains.capacity(),
                self.definitions.resource_gain_procs.len(),
            ),
        ] {
            debug_assert!(
                capacity >= required,
                "scratch capacity must cover its finalized plan"
            );
        }
    }

    // #t(fn: rust_cyclomatic_complexity) cold reachability exhaustively visits each distinct finalized definition family.
    fn reachable_damage_spell_ids(&self) -> Vec<u32> {
        let mut spell_ids = self.spell_ids.values().copied().collect::<Vec<_>>();

        spell_ids.extend_from_slice(&self.damage_spell_ids);
        spell_ids.extend_from_slice(&self.effect_spell_ids);

        for spell in &self.definitions.spells {
            spell_ids.extend([
                spell.spell_id,
                spell.damage_effect.spell_id,
                spell.channel.tick_spell_id,
                spell.channel.tick_damage_alt_spell_id,
            ]);
        }

        for attack in &self.definitions.auto_attacks {
            spell_ids.push(attack.spell_id);
        }

        for effect in &self.definitions.spell_effects {
            match effect {
                SpellEffectData::Damage { effect, .. } => spell_ids.push(effect.spell_id),
                SpellEffectData::Heal { effect, .. } | SpellEffectData::Energize { effect, .. } => {
                    if let Some(effect) = effect {
                        spell_ids.push(effect.spell_id);
                    }
                }
                SpellEffectData::Delayed {
                    profile_spell_id, ..
                } => spell_ids.push(*profile_spell_id),
                SpellEffectData::Conditional { .. }
                | SpellEffectData::ApplyAura { .. }
                | SpellEffectData::AddAuraStack { .. }
                | SpellEffectData::RemoveAura { .. }
                | SpellEffectData::InterruptCast { .. }
                | SpellEffectData::Dispel { .. }
                | SpellEffectData::EnergizePercent { .. }
                | SpellEffectData::ExtendAura { .. }
                | SpellEffectData::MutateCooldown { .. } => {}
            }
        }

        for aura in &self.definitions.auras {
            spell_ids.extend([
                aura.aura_id,
                aura.apply_profile_spell_id,
                aura.tick_profile_spell_id,
                aura.expire_trigger_spell_id,
            ]);

            if let Some(periodic) = aura.periodic {
                spell_ids.push(periodic.damage_spell_id_or(aura.aura_id));

                if let Some(effect) = periodic.effect_ref {
                    spell_ids.push(effect.spell_id);
                }
            }

            for effect in aura.effects.iter().flatten() {
                if let Some((spell_id, _)) = effect.dbc_source() {
                    spell_ids.push(spell_id);
                }

                if let BuffEffect::DamageReplication(replication) = effect {
                    spell_ids.push(replication.effect.spell_id);
                    spell_ids.extend_from_slice(replication.source_spells);
                }
            }
        }

        for modifier in &self.definitions.driver_spell_modifiers {
            spell_ids.push(modifier.driver_spell_id);
            spell_ids.extend_from_slice(modifier.spells);
        }

        for driver in &self.definitions.passive_driver_effects {
            spell_ids.push(driver.driver_spell_id);

            if let Some((spell_id, _)) = driver.effect.dbc_source() {
                spell_ids.push(spell_id);
            }

            if let BuffEffect::DamageReplication(replication) = driver.effect {
                spell_ids.push(replication.effect.spell_id);
                spell_ids.extend_from_slice(replication.source_spells);
            }
        }

        for driver in &self.definitions.periodic_drivers {
            spell_ids.push(driver.driver_spell_id);
        }

        for proc in &self.definitions.impact_effect_procs {
            spell_ids.extend([proc.driver_spell_id, proc.profile_spell_id]);

            if let crate::state::ImpactSource::Spell(spell_id) = proc.source {
                spell_ids.push(spell_id);
            }
        }

        spell_ids.retain(|spell_id| *spell_id != 0);
        spell_ids.sort_unstable();
        spell_ids.dedup();

        spell_ids
    }

    // #t(fn: rust_cyclomatic_complexity) construction exhaustively binds each typed runtime identity and supported actor-source shape before freeze.
    fn buffer_requirements(&self) -> BufferRequirements {
        let mut requirements = BufferRequirements::new();

        for spell in &self.definitions.spells {
            let spell = SpellIdx::from_raw(spell.spell_id);

            requirements.spell(spell);
            requirements.cooldown(spell);
            requirements.history(spell);
        }

        if let Some(resource) = self.config.base_stats.resource_type {
            requirements.resource(resource);
        }

        if let Some(resource) = self.config.base_stats.secondary_resource_type {
            requirements.resource(resource);
        }

        let pets = PetIdx::iter(PetIdx::MAX)
            .map(ActorId::Pet)
            .collect::<Vec<_>>();
        let base_actors = [ActorId::Player, ActorId::External];
        let mut actors =
            Vec::with_capacity(base_actors.len() + pets.len() + self.definitions.enemies.len());

        actors.extend(base_actors);

        actors.extend(pets.iter().copied());

        actors.extend(
            self.definitions
                .enemies
                .iter()
                .map(|enemy| ActorId::Enemy(enemy.id())),
        );

        for aura in &self.definitions.auras {
            let aura_idx = AuraIdx(aura.aura_id);

            match aura.on {
                AuraOn::Player => {
                    for &source in &actors {
                        requirements.aura(AuraKey::new(
                            aura_idx,
                            source,
                            ActorId::Player,
                            AuraOn::Player,
                        ));
                    }
                }
                AuraOn::Target => {
                    for enemy in &self.definitions.enemies {
                        for &source in &actors {
                            requirements.aura(AuraKey::new(
                                aura_idx,
                                source,
                                ActorId::Enemy(enemy.id()),
                                AuraOn::Target,
                            ));
                        }
                    }
                }
                AuraOn::Pet => {
                    requirements.aura(AuraKey::new(
                        aura_idx,
                        ActorId::Player,
                        ActorId::Pet(PetIdx::PRIMARY),
                        AuraOn::Pet,
                    ));

                    for &pet in &pets {
                        requirements.aura(AuraKey::new(aura_idx, pet, pet, AuraOn::Pet));
                    }
                }
            }

            // Actor-directed effects can override the aura's ordinary affected actor while
            // retaining its projection family. Pre-bind the supported combat-source shapes.

            for &affected in &actors {
                requirements.aura(AuraKey::new(aura_idx, ActorId::Player, affected, aura.on));
            }

            for &affected in &actors {
                requirements.aura(AuraKey::new(aura_idx, ActorId::External, affected, aura.on));
            }

            for &pet in &pets {
                requirements.aura(AuraKey::new(aura_idx, pet, pet, aura.on));
                requirements.aura(AuraKey::new(aura_idx, pet, ActorId::Player, aura.on));

                for enemy in &self.definitions.enemies {
                    requirements.aura(AuraKey::new(
                        aura_idx,
                        pet,
                        ActorId::Enemy(enemy.id()),
                        aura.on,
                    ));
                }
            }

            for enemy in &self.definitions.enemies {
                let source = ActorId::Enemy(enemy.id());

                for &affected in &actors {
                    requirements.aura(AuraKey::new(aura_idx, source, affected, aura.on));
                }
            }

            // Spellsteal transfers the concrete value into the player's projection family.

            requirements.aura(AuraKey::new(
                aura_idx,
                ActorId::Player,
                ActorId::Player,
                AuraOn::Player,
            ));

            if aura.propagates_to_pet {
                for &source in &actors {
                    requirements.aura(AuraKey::new(
                        aura_idx,
                        source,
                        ActorId::Pet(PetIdx::PRIMARY),
                        AuraOn::Pet,
                    ));
                }
            }
        }

        for (name, _) in &self.talent_ranks {
            requirements.talent(name.as_str());
        }

        for (index, _) in self.definitions.auto_attacks.iter().enumerate() {
            requirements.swing(crate::keys::auto_attack_key(index));
        }

        for &(slot, _) in &self.definitions.item_use_spells {
            requirements.item(slot.slug());
        }

        for &(key, _) in &self.initial_weapon_imbues {
            requirements.weapon_imbue(key);
        }

        requirements.unit(crate::keys::UnitKey::TARGET);

        requirements
    }

    // #t(fn: rust_alloc_in_loop) duplicate and unresolved construction diagnostics include the concrete conflicting identity and local indexes.
    fn validate_identities(&self) -> Result<(), EngineError> {
        let mut spell_ids = IntMap::<u32, LocalSpellIdx>::default();

        for (raw, spell) in self.definitions.spells.iter().enumerate() {
            let local = LocalSpellIdx::new(u8::try_from(raw).map_err(|error| {
                EngineError::spec_construction(format!("spell index {raw} exceeds u8: {error}"))
            })?);

            if let Some(previous) = spell_ids.insert(spell.spell_id, local) {
                return Err(EngineError::spec_construction(format!(
                    "duplicate spell identity {} at local indexes {} and {}",
                    spell.spell_id,
                    previous.raw(),
                    local.raw()
                )));
            }
        }

        let mut aura_ids = FastMap::<(u32, AuraOn), LocalAuraIdx>::default();

        for (raw, aura) in self.definitions.auras.iter().enumerate() {
            let local = LocalAuraIdx::new(u8::try_from(raw).map_err(|error| {
                EngineError::spec_construction(format!("aura index {raw} exceeds u8: {error}"))
            })?);

            if let Some(previous) = aura_ids.insert((aura.aura_id, aura.on), local) {
                return Err(EngineError::spec_construction(format!(
                    "duplicate aura identity ({}, {:?}) at local indexes {} and {}",
                    aura.aura_id,
                    aura.on,
                    previous.raw(),
                    local.raw()
                )));
            }
        }

        for (&spell_id, &local) in &self.indexes.spell_by_id {
            if self
                .definitions
                .spells
                .get(local.as_usize())
                .is_none_or(|spell| spell.spell_id != spell_id)
            {
                return Err(EngineError::spec_construction(format!(
                    "unresolved spell index binding {spell_id} -> {}",
                    local.raw()
                )));
            }
        }

        Ok(())
    }

    // #t(fn: rust_max_fn_lines) finalization freezes every related runtime coordinate in one ordered construction transaction.
    // #t(fn: rust_fallible_in_iterator) finalized registries guarantee the coordinates consumed by these cold construction iterators.
    fn into_program_and_runtime(
        self,
        bindings: FrozenProgramBindings,
        effects: crate::state::program::EffectPlan,
        damage_plans: (
            crate::state::program::DamagePlan,
            Box<[crate::state::program::GroundEffectPlan]>,
        ),
        aura_dependencies: crate::state::program::AuraDependencyPlan,
        rotation: crate::state::program::RotationPlan,
    ) -> (CombatProgram, CombatRuntime) {
        let (damage, ground_effects) = damage_plans;
        let spec_identity_brand = self.spec_identity_brand;
        let FrozenProgramBindings {
            scheduled_spells,
            runtime_events,
            scheduled_spell_executions,
            layout_fingerprint,
            buffer_bindings,
        } = bindings;

        let DraftDefinitions {
            enemies,
            spells,
            empower_cast_times_ms,
            spell_effects,
            auras,
            aura_bindings,
            spell_bindings,
            auto_attacks,
            cast_hooks,
            empower_release_hooks,
            tick_hooks,
            player_cast_hooks,
            resource_threshold_triggers,
            impact_procs,
            landed_impact_procs,
            accumulating_impact_procs,
            impact_effect_procs,
            driver_spell_modifiers,
            passive_driver_effects,
            periodic_drivers,
            talent_ranks,
            resource_gain_procs,
            item_use_spells,
            rppm_trackers,
            rppm_bindings,
            system_rppm_bindings,
            threshold_trackers,
            weapon_enchant_bindings,
            weapon_imbue_bindings,
            precombat_auras,
            talent_aura_stacks,
            stealth_aura_id,
        } = self.definitions;
        let DraftIndexes {
            spell_by_id,
            aura_by_id,
            cooldown_categories,
            charge_categories,
            item_rppm_indices,
            system_rppm_indices,
            enchant_rppm_indices,
            enchant_buff_spell_ids,
            ..
        } = self.indexes;

        let mut runtime = self.runtime;

        runtime.procs.rppm_trackers = rppm_trackers;
        runtime.procs.threshold_trackers = threshold_trackers;
        runtime.procs.accumulating_impact_accumulators = accumulating_impact_procs
            .iter()
            .map(|proc| proc.accumulator)
            .collect();
        runtime.procs.resource_gain_attempts = resource_gain_procs
            .iter()
            .map(|proc| proc.attempts)
            .collect();
        runtime.procs.impact_effect_ready_at = vec![0.0; impact_effect_procs.len()];
        runtime
            .procs
            .resize_target_icds_for_known_targets(impact_effect_procs.len());
        runtime.procs.impact_effect_charges = impact_effect_procs
            .iter()
            .map(|proc| {
                if proc.uses_stacks_for_charges {
                    0
                } else {
                    proc.charges
                }
            })
            .collect();
        runtime.procs.impact_effect_rng = impact_effect_procs
            .iter()
            .map(crate::state::ImpactEffectRngState::from_proc)
            .collect();

        let telemetry_targets = crate::state::program::finalize_target_metadata(&enemies);
        let talent_ranks = damage.dense_talent_ranks(&talent_ranks);
        let weapon_enchant_bindings = weapon_enchant_bindings
            .into_iter()
            .map(|binding| crate::state::ResolvedWeaponEnchantBinding {
                rppm: *enchant_rppm_indices
                    .get(&binding.enchantment_id)
                    .expect("registered weapon enchant has a finalized RPPM coordinate"),
                buff_aura: *aura_by_id
                    .get(&binding.buff_spell_id)
                    .expect("registered weapon enchant has a finalized buff-aura coordinate"),
            })
            .collect();
        let aura_bindings = {
            let len = aura_bindings
                .iter()
                .map(|(binding, _)| binding.as_usize() + 1)
                .max()
                .unwrap_or(0);
            let mut resolved = vec![None; len];

            for (binding, aura_id) in aura_bindings {
                // BOUNDS: len is derived from the maximum binding in this exact input collection.
                resolved[binding.as_usize()] = aura_by_id.get(&aura_id).copied();
            }

            resolved.into_boxed_slice()
        };
        let spell_bindings = {
            let len = spell_bindings
                .iter()
                .map(|(binding, _)| binding.as_usize() + 1)
                .max()
                .unwrap_or(0);
            let mut resolved = vec![None; len];

            for (binding, spell_id) in spell_bindings {
                // BOUNDS: len is derived from the maximum binding in this exact input collection.
                resolved[binding.as_usize()] = spell_by_id.get(&spell_id).copied();
            }

            resolved.into_boxed_slice()
        };
        let rppm_bindings = {
            let len = rppm_bindings
                .iter()
                .map(|(binding, _)| binding.as_usize() + 1)
                .max()
                .unwrap_or(0);
            let mut resolved = vec![None; len];

            for (binding, local) in rppm_bindings {
                // BOUNDS: len is derived from the maximum binding in this exact input collection.
                resolved[binding.as_usize()] = Some(local);
            }

            resolved.into_boxed_slice()
        };
        let system_rppm_bindings = {
            let len = system_rppm_bindings
                .iter()
                .map(|(binding, _)| binding.as_usize() + 1)
                .max()
                .unwrap_or(0);
            let mut resolved = vec![None; len];

            for (binding, value) in system_rppm_bindings {
                // BOUNDS: len is derived from the maximum binding in this exact input collection.
                resolved[binding.as_usize()] = Some(value);
            }

            resolved.into_boxed_slice()
        };
        let weapon_imbue_bindings = weapon_imbue_bindings
            .into_iter()
            .map(|binding| crate::state::ResolvedWeaponImbueBinding {
                spell_local: *spell_by_id
                    .get(&binding.spell_id)
                    .expect("registered weapon imbue has a finalized spell coordinate"),
                slot: buffer_bindings
                    .weapon_imbue(binding.key)
                    .expect("registered weapon imbue has a finalized buffer coordinate"),
            })
            .collect::<Box<[_]>>();
        let mut weapon_imbue_by_spell = vec![None; spells.len()];

        for binding in &weapon_imbue_bindings {
            // BOUNDS: spell_local is compiled from this exact finalized spell table.
            weapon_imbue_by_spell[binding.spell_local.as_usize()] = Some(binding.slot);
        }

        let weapon_imbue_by_spell = weapon_imbue_by_spell.into_boxed_slice();

        runtime.procs.system_rppm_ready_at = vec![SimTime::ZERO; system_rppm_bindings.len()];
        let aura_followups = auras
            .iter()
            .map(|aura| {
                (aura.application_followup_aura_id != 0)
                    .then(|| aura_by_id.get(&aura.application_followup_aura_id).copied())
                    .flatten()
            })
            .collect::<Vec<_>>()
            .into_boxed_slice();
        let aura_exclusions = auras
            .iter()
            .map(|aura| {
                std::array::from_fn(|index| {
                    // BOUNDS: from_fn supplies indices within application_excluded_auras.
                    let aura_id = aura.application_excluded_auras[index];

                    (aura_id != 0)
                        .then(|| aura_by_id.get(&aura_id).copied())
                        .flatten()
                })
            })
            .collect::<Vec<_>>()
            .into_boxed_slice();
        let stealth_aura = stealth_aura_id.and_then(|aura_id| aura_by_id.get(&aura_id).copied());
        let external_buff_auras = self
            .config
            .external_buffs
            .iter()
            .map(|config| aura_by_id.get(&config.spell_id).copied())
            .collect::<Vec<_>>()
            .into_boxed_slice();
        let proc_category_recovery_ms = crate::generated_identities::proc_category::ALL
            .iter()
            .map(|(_, driver)| {
                self.config
                    .game_data
                    .proc_category_recovery_ms(SpellIdx::from_raw(*driver))
                    .unwrap_or(0)
            })
            .collect::<Vec<_>>()
            .into_boxed_slice();

        runtime.procs.proc_category_ready_at_dense =
            vec![SimTime::ZERO; proc_category_recovery_ms.len()];
        let periodic_driver_bindings = crate::generated_identities::periodic_driver::ALL
            .iter()
            .map(|driver_spell_id| {
                periodic_drivers
                    .iter()
                    .position(|driver| driver.driver_spell_id == *driver_spell_id)
            })
            .collect::<Vec<_>>()
            .into_boxed_slice();
        let empty_category_members: &[LocalSpellIdx] = &[];
        let cooldown_category_members = spells
            .iter()
            .map(|spell| {
                spell
                    .cooldown
                    .cooldown_category
                    .map_or(empty_category_members, |category| {
                        cooldown_categories.members(&category)
                    })
                    .to_vec()
                    .into_boxed_slice()
            })
            .collect();
        let charge_category_members = spells
            .iter()
            .map(|spell| {
                spell
                    .cooldown
                    .charge_category
                    .map_or(empty_category_members, |category| {
                        charge_categories.members(&category)
                    })
                    .to_vec()
                    .into_boxed_slice()
            })
            .collect();
        let charge_category_owners = spells
            .iter()
            .enumerate()
            .map(|(index, spell)| {
                spell
                    .cooldown
                    .charge_category
                    .and_then(|category| charge_categories.owner(&category).copied())
                    .unwrap_or_else(|| {
                        LocalSpellIdx::new(
                            u8::try_from(index).expect("finalized spell count fits local identity"),
                        )
                    })
            })
            .collect();
        let start_recovery_category_owners = spells
            .iter()
            .enumerate()
            .map(|(index, spell)| {
                let owner = spell.cooldown.start_recovery_category.and_then(|category| {
                    spells.iter().position(|candidate| {
                        candidate.cooldown.start_recovery_category == Some(category)
                    })
                });
                let owner = owner.unwrap_or(index);

                LocalSpellIdx::new(
                    u8::try_from(owner).expect("finalized spell count fits local identity"),
                )
            })
            .collect();
        let aura_expire_trigger_spells = auras
            .iter()
            .map(|aura| {
                (aura.expire_trigger_spell_id != 0)
                    .then(|| spell_by_id.get(&aura.expire_trigger_spell_id).copied())
                    .flatten()
            })
            .collect();
        let pet_action_plans: Box<[u16]> = auto_attacks
            .iter()
            .enumerate()
            .filter(|(_, attack)| attack.pet_action_bar.is_some())
            .map(|(index, _)| u16::try_from(index).expect("finalized auto-attack count fits u16"))
            .collect();
        let primary_pet_action_auto = pet_action_plans.first().copied();
        let pet_auto_attacks = auto_attacks
            .iter()
            .enumerate()
            .filter(|(_, attack)| attack.is_pet && attack.swing_ms > 0)
            .map(|(index, _)| u16::try_from(index).expect("finalized auto-attack count fits u16"))
            .collect();
        let mut pet_action_plan_by_auto = vec![None; auto_attacks.len()];

        for (plan, auto) in pet_action_plans.iter().copied().enumerate() {
            // #t(rust_unchecked_indexing) auto comes from this exact finalized auto-attacks enumeration.
            pet_action_plan_by_auto[usize::from(auto)] =
                Some(u16::try_from(plan).expect("finalized pet plan count fits u16"));
        }

        let program = CombatProgram {
            spec_identity_brand,
            enemies,
            telemetry_targets,
            spells,
            scheduled_spells,
            runtime_events,
            scheduled_spell_executions,
            empower_cast_times_ms,
            spell_effects,
            auras,
            aura_bindings,
            spell_bindings,
            rppm_bindings,
            system_rppm_bindings,
            aura_followups,
            aura_exclusions,
            aura_expire_trigger_spells,
            external_buff_auras,
            proc_category_recovery_ms,
            auto_attacks,
            pet_action_plans,
            pet_action_plan_by_auto: pet_action_plan_by_auto.into_boxed_slice(),
            primary_pet_action_auto,
            pet_auto_attacks,
            cast_hooks,
            empower_release_hooks,
            tick_hooks,
            player_cast_hooks,
            resource_threshold_triggers,
            impact_procs,
            landed_impact_procs,
            accumulating_impact_procs,
            impact_effect_procs,
            driver_spell_modifiers,
            passive_driver_effects,
            effects,
            damage,
            ground_effects,
            aura_dependencies,
            rotation,
            periodic_drivers,
            periodic_driver_bindings,
            talent_ranks,
            resource_gain_procs,
            item_use_spells,
            weapon_enchant_bindings,
            weapon_imbue_bindings,
            weapon_imbue_by_spell,
            precombat_auras,
            talent_aura_stacks,
            stealth_aura,
            spell_by_id,
            #[cfg(any(test, feature = "test-support"))]
            aura_by_id,
            cooldown_category_members,
            charge_category_members,
            charge_category_owners,
            start_recovery_category_owners,
            item_rppm_indices,
            system_rppm_indices,
            enchant_rppm_indices,
            enchant_buff_spell_ids,
            config: self.config,
            names: self.names,
            layout_fingerprint,
            buffer_bindings,
        };

        (program, runtime)
    }
}

fn validate_layout_fingerprints(
    program: &CombatProgram,
    instance: &CombatInstance,
) -> Result<(), EngineError> {
    if program.layout_fingerprint == instance.buffer.layout_fingerprint() {
        return Ok(());
    }

    Err(EngineError::spec_construction(format!(
        "program/buffer layout fingerprint mismatch: program={}, buffer={}",
        program.layout_fingerprint.as_u64(),
        instance.buffer.layout_fingerprint().as_u64(),
    )))
}

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