wowlab_engine_ports/

spec_handler.rs

// #t(file: rust_similar_structs) Runtime event token families deliberately remain distinct so equivalent coordinates cannot be interchanged.

use wowlab_engine_telemetry::TelemetrySink;
#[cfg(test)]
use wowlab_types::sim::{AuraKey, SpellIdx};
use wowlab_types::{
    data::WeaponStats,
    game::GearSlot,
    sim::{
        ActorId, EnemyIdx, GroupId, PositionedActorRef, PullId, SimTime, SpatialTransform, WaveId,
    },
};

use crate::{
    combat_stats::CombatStats, decision_trace::DecisionTraceSink, sim_state::SimState,
    spatial::SpatialQueryError,
};

#[rustfmt::skip]
// #t(rust_foreign_reexports) Ports owns the public opaque event-token vocabulary but deliberately does not re-export the authority catalogs.
pub use wowlab_engine_event_authority::{
    ActorMovementBinding, AuraEventBinding, ExternalBuffBinding, GuardianEventBinding,
    HookTimerBinding, PendingImpactBinding, PetActionBinding, PullLifecycleGeneration,
    RaidAddBinding, RaidEventBinding, ScheduledSpellBinding,
};
/// Character sheet snapshot returned by [`SpecHandler::paperdoll`].
#[derive(Clone, Debug, serde::Serialize)]
#[non_exhaustive]
pub struct Paperdoll {
    pub stats: CombatStats,
    pub introspection: wowlab_types::game::SpecIntrospection,
    pub precombat_aura_ids: Vec<u32>,
    pub talent_ranks: Vec<(u32, u8)>,
    pub item_use_spells: Vec<(GearSlot, u32)>,
    pub weapon_main: WeaponStats,
    pub weapon_off: Option<WeaponStats>,
}

/// Loadout-derived fields in a character-sheet snapshot.
#[derive(Clone, Debug)]
// #t(rust_similar_structs) loadout input intentionally excludes computed paperdoll statistics and introspection
pub struct PaperdollLoadout {
    pub precombat_aura_ids: Vec<u32>,
    pub talent_ranks: Vec<(u32, u8)>,
    pub item_use_spells: Vec<(GearSlot, u32)>,
    pub weapon_main: WeaponStats,
    pub weapon_off: Option<WeaponStats>,
}

impl Paperdoll {
    #[must_use]
    pub fn new(
        stats: CombatStats,
        introspection: wowlab_types::game::SpecIntrospection,
        loadout: PaperdollLoadout,
    ) -> Self {
        Self {
            stats,
            introspection,
            precombat_aura_ids: loadout.precombat_aura_ids,
            talent_ranks: loadout.talent_ranks,
            item_use_spells: loadout.item_use_spells,
            weapon_main: loadout.weapon_main,
            weapon_off: loadout.weapon_off,
        }
    }
}

/// Action returned by a spec handler during rotation evaluation.
#[derive(Clone, Debug)]
// #t(block: rust_non_exhaustive_on_public) internal port enum matched exhaustively within workspace
// docref:start event-system-spec-action
pub enum SpecAction {
    Cast {
        spell: ScheduledSpellBinding,
        empower_rank: u8,
        source: ActorId,
        target: EnemyIdx,
    },
    Wait {
        until_ms: SimTime,
    },
}
// docref:end event-system-spec-action

/// Typed result of requesting the combat layer to despawn one exact enemy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum EnemyDespawnOutcome {
    Despawned,
    AlreadyInactive,
    UnknownEnemy,
}

/// Why a derived encounter despawn is being processed.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) internal port enum matched exhaustively within workspace
pub enum EncounterDespawnKind {
    Authored { counts_as_completion: bool },
    ForcedOptional,
}

/// The policy condition that ended an encounter iteration.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) internal port enum matched exhaustively within workspace
pub enum EncounterTerminationReason {
    FixedDuration,
    PrimaryRequiredEnemyDead,
    RequiredGroupsComplete,
    AllEnemiesInRequiredGroupsDead,
}

/// Aura identity and optional enemy target delivered to aura lifecycle handlers.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct AuraEventRef {
    binding: AuraEventBinding,
}

impl AuraEventRef {
    #[must_use]
    pub const fn from_binding(binding: AuraEventBinding) -> Self {
        Self { binding }
    }

    pub const fn binding(self) -> AuraEventBinding {
        self.binding
    }
}

/// Pull identity and activation epoch shared by encounter lifecycle events.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PullScope {
    pub pull: PullId,
    pub epoch: u32,
}

wowlab_engine_macros::define_error! {
/// Fatal typed failure raised by a spec handler while processing one simulation event.
#[derive(Debug)]
pub struct SpecRuntimeError {
    #[source]
    kind: SpecRuntimeErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum SpecRuntimeErrorKind {
    #[error("enemy {enemy:?} is absent from canonical encounter state")]
    MissingEnemy { enemy: EnemyIdx },
    #[error("failed to remove dying enemy {enemy:?} from the spatial index")]
    EnemyDeathSpatialRemoval {
        enemy: EnemyIdx,
        #[source]
        source: SpatialQueryError,
    },
    #[error(
        "encounter stalled in pull {pull:?}: incomplete required groups {incomplete_required_groups:?}, inactive/live enemies {inactive_live_enemies:?}"
    )]
    EncounterStalled {
        pull: PullId,
        incomplete_required_groups: Vec<GroupId>,
        inactive_live_enemies: Vec<EnemyIdx>,
    },
    #[error("invalid encounter script event in pull {pull:?}: {message}")]
    EncounterScript { pull: PullId, message: String },
    #[error(
        "spell {spell_id} requested empower rank {requested_rank}, but its structured stage data supports ranks 1 through {max_rank}"
    )]
    InvalidEmpowerRank {
        spell_id: u32,
        requested_rank: u8,
        max_rank: u8,
    },
    #[error("rotation selected spell {spell_id}, but its finalized cast binding is absent")]
    UnresolvedRotationCastIdentity { spell_id: u32 },
    #[error("damage identity {spell_id}:{effect_index} is absent from the finalized combat program")]
    UnresolvedDamageIdentity { spell_id: u32, effect_index: u8 },
    #[error("runtime target resolution failed for damage identity {spell_id}:{effect_index}: {message}")]
    DamageTargetResolution {
        spell_id: u32,
        effect_index: u8,
        message: String,
    },
}
}

impl SpecRuntimeError {
    /// Reports an enemy absent from canonical encounter state.
    #[must_use]
    pub const fn missing_enemy(enemy: EnemyIdx) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::MissingEnemy { enemy },
        }
    }

    /// Wraps a spatial removal failure during enemy death.
    #[must_use]
    pub const fn enemy_death_spatial_removal(enemy: EnemyIdx, source: SpatialQueryError) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::EnemyDeathSpatialRemoval { enemy, source },
        }
    }

    /// Reports a pull that cannot make further progress.
    #[must_use]
    pub fn encounter_stalled(
        pull: PullId,
        incomplete_required_groups: Vec<GroupId>,
        inactive_live_enemies: Vec<EnemyIdx>,
    ) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::EncounterStalled {
                pull,
                incomplete_required_groups,
                inactive_live_enemies,
            },
        }
    }

    /// Reports an invalid authored encounter script event.
    #[must_use]
    pub fn encounter_script(pull: PullId, message: impl Into<String>) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::EncounterScript {
                pull,
                message: message.into(),
            },
        }
    }

    /// Reports a cast action whose selected empower rank is outside the spell's stage data.
    #[must_use]
    pub const fn invalid_empower_rank(spell_id: u32, requested_rank: u8, max_rank: u8) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::InvalidEmpowerRank {
                spell_id,
                requested_rank,
                max_rank,
            },
        }
    }

    /// Reports a rotation result absent from the finalized cast-binding universe.
    #[must_use]
    pub const fn unresolved_rotation_cast_identity(spell_id: u32) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::UnresolvedRotationCastIdentity { spell_id },
        }
    }

    /// Reports a damage action/effect absent from the finalized combat-local universe.
    #[must_use]
    pub const fn unresolved_damage_identity(spell_id: u32, effect_index: u8) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::UnresolvedDamageIdentity {
                spell_id,
                effect_index,
            },
        }
    }

    /// Reports a spatial-state failure while executing a finalized target program.
    #[must_use]
    pub fn damage_target_resolution(
        spell_id: u32,
        effect_index: u8,
        message: impl Into<String>,
    ) -> Self {
        Self {
            kind: SpecRuntimeErrorKind::DamageTargetResolution {
                spell_id,
                effect_index,
                message: message.into(),
            },
        }
    }

    /// Returns the enemy and spatial cause for a death-removal failure.
    #[must_use]
    pub const fn enemy_death_spatial_removal_details(
        &self,
    ) -> Option<(EnemyIdx, SpatialQueryError)> {
        match self.kind {
            SpecRuntimeErrorKind::EnemyDeathSpatialRemoval { enemy, source } => {
                Some((enemy, source))
            }
            _ => None,
        }
    }

    /// Returns the authored pull and incomplete encounter state for a stall failure.
    #[must_use]
    pub fn encounter_stalled_details(&self) -> Option<(PullId, &[GroupId], &[EnemyIdx])> {
        match &self.kind {
            SpecRuntimeErrorKind::EncounterStalled {
                pull,
                incomplete_required_groups,
                inactive_live_enemies,
            } => Some((
                *pull,
                incomplete_required_groups.as_slice(),
                inactive_live_enemies.as_slice(),
            )),
            _ => None,
        }
    }
}

/// Scheduling scope for the shared target-aware death event.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) internal port enum matched exhaustively within workspace
pub enum DeathEventScope {
    Unscoped,
    ScriptedLifetime(PullLifecycleGeneration),
}

/// Unified simulation event type.
#[derive(Clone, Copy, Debug)]
// #t(rust_non_exhaustive_on_public) internal port enum matched exhaustively within workspace
pub enum Event {
    PlayerReady {
        t: SimTime,
    },
    OffGcdReady {
        t: SimTime,
    },
    CastStart {
        t: SimTime,
        spell: ScheduledSpellBinding,
        empower_rank: u8,
        source: ActorId,
        target: EnemyIdx,
    },
    CastComplete {
        t: SimTime,
        spell: ScheduledSpellBinding,
        empower_rank: u8,
        source: ActorId,
        target: EnemyIdx,
    },
    /// Server-triggered cast retaining the exact affected actor identity.
    TriggeredSpell {
        t: SimTime,
        spell: ScheduledSpellBinding,
        source: ActorId,
        target: ActorId,
    },
    SpellLaunch {
        t: SimTime,
        impact: PendingImpactBinding,
        source: ActorId,
        target: EnemyIdx,
    },
    SpellImpact {
        t: SimTime,
        impact: PendingImpactBinding,
        source: ActorId,
        target: EnemyIdx,
    },
    GuardianAction {
        t: SimTime,
        guardian: GuardianEventBinding,
        source: ActorId,
        target: EnemyIdx,
    },
    GuardianExpire {
        t: SimTime,
        guardian: GuardianEventBinding,
    },
    PetAction {
        t: SimTime,
        action: PetActionBinding,
        source: ActorId,
        target: EnemyIdx,
    },
    AuraTick {
        t: SimTime,
        aura: AuraEventBinding,
    },
    ChannelTick {
        t: SimTime,
        spell: ScheduledSpellBinding,
        source: ActorId,
        target: EnemyIdx,
        generation: u64,
    },
    AuraExpire {
        t: SimTime,
        aura: AuraEventBinding,
    },
    ProcHeartbeat {
        t: SimTime,
    },
    Death {
        t: SimTime,
        target: EnemyIdx,
        scope: DeathEventScope,
    },
    EncounterDespawn {
        t: SimTime,
        scope: PullScope,
        target: EnemyIdx,
        kind: EncounterDespawnKind,
    },
    GroupComplete {
        t: SimTime,
        scope: PullScope,
        group: GroupId,
    },
    PullComplete {
        t: SimTime,
        scope: PullScope,
        finalize: bool,
    },
    EncounterTerminate {
        t: SimTime,
        reason: EncounterTerminationReason,
    },
    WaveActivate {
        t: SimTime,
        scope: PullScope,
        wave: WaveId,
    },
    EnemyActivate {
        t: SimTime,
        scope: PullScope,
        target: EnemyIdx,
    },
    Retarget {
        t: SimTime,
        scope: PullScope,
    },
    EncounterMove {
        t: SimTime,
        scope: PullScope,
        actor: PositionedActorRef,
        transform: SpatialTransform,
    },
    ActorMovement {
        t: SimTime,
        movement: ActorMovementBinding,
        moving: bool,
    },
    RaidEvent {
        t: SimTime,
        event: RaidEventBinding,
    },
    RaidAddDespawn {
        t: SimTime,
        add: RaidAddBinding,
    },
    ExternalBuff {
        t: SimTime,
        buff: ExternalBuffBinding,
    },
    HookTimer {
        t: SimTime,
        timer: HookTimerBinding,
        source: ActorId,
        target: Option<EnemyIdx>,
    },
    CooldownReady {
        t: SimTime,
        spell: ScheduledSpellBinding,
    },
    AutoAttack {
        t: SimTime,
        source: ActorId,
        target: EnemyIdx,
    },
    EnemyAutoAttack {
        t: SimTime,
        source: EnemyIdx,
        target: ActorId,
    },
}

const EVENT_PRIORITY_FINALIZATION: u8 = 0;
const EVENT_PRIORITY_GROUP_COMPLETION: u8 = 1;
const EVENT_PRIORITY_PULL_COMPLETION: u8 = 2;
const EVENT_PRIORITY_TERMINATION: u8 = 3;
const EVENT_PRIORITY_ACTIVATION: u8 = 4;
const EVENT_PRIORITY_RETARGET: u8 = 5;
const EVENT_PRIORITY_MOVEMENT: u8 = 6;
const EVENT_PRIORITY_CAST: u8 = 7;
const EVENT_PRIORITY_IMPACT: u8 = 8;
const EVENT_PRIORITY_AURA_EXPIRE: u8 = 9;
const EVENT_PRIORITY_READY: u8 = 10;

impl Event {
    /// Returns the stable same-timestamp priority, lower first; insertion order breaks ties within a priority.
    #[inline]
    #[must_use]
    pub const fn priority(&self) -> u8 {
        match self {
            Event::Death { .. }
            | Event::EncounterDespawn { .. }
            | Event::RaidAddDespawn { .. }
            | Event::GuardianExpire { .. } => EVENT_PRIORITY_FINALIZATION,
            Event::GroupComplete { .. } => EVENT_PRIORITY_GROUP_COMPLETION,
            Event::PullComplete { .. } => EVENT_PRIORITY_PULL_COMPLETION,
            Event::EncounterTerminate { .. } => EVENT_PRIORITY_TERMINATION,
            Event::WaveActivate { .. } | Event::EnemyActivate { .. } => EVENT_PRIORITY_ACTIVATION,
            Event::Retarget { .. } => EVENT_PRIORITY_RETARGET,
            Event::EncounterMove { .. } | Event::ActorMovement { .. } | Event::RaidEvent { .. } => {
                EVENT_PRIORITY_MOVEMENT
            }
            Event::CastComplete { .. }
            | Event::TriggeredSpell { .. }
            | Event::SpellLaunch { .. } => EVENT_PRIORITY_CAST,
            Event::SpellImpact { .. }
            | Event::GuardianAction { .. }
            | Event::PetAction { .. }
            | Event::AuraTick { .. }
            | Event::ChannelTick { .. }
            | Event::ProcHeartbeat { .. }
            | Event::HookTimer { .. }
            | Event::AutoAttack { .. }
            | Event::EnemyAutoAttack { .. }
            | Event::ExternalBuff { .. } => EVENT_PRIORITY_IMPACT,
            Event::AuraExpire { .. } => EVENT_PRIORITY_AURA_EXPIRE,
            Event::PlayerReady { .. }
            | Event::OffGcdReady { .. }
            | Event::CastStart { .. }
            | Event::CooldownReady { .. } => EVENT_PRIORITY_READY,
        }
    }

    #[inline]
    // docref:start event-system-timestamp
    #[must_use]
    pub fn timestamp(&self) -> SimTime {
        match self {
            Event::PlayerReady { t }
            | Event::OffGcdReady { t }
            | Event::CastStart { t, .. }
            | Event::CastComplete { t, .. }
            | Event::TriggeredSpell { t, .. }
            | Event::SpellLaunch { t, .. }
            | Event::SpellImpact { t, .. }
            | Event::GuardianAction { t, .. }
            | Event::GuardianExpire { t, .. }
            | Event::PetAction { t, .. }
            | Event::AuraTick { t, .. }
            | Event::ChannelTick { t, .. }
            | Event::AuraExpire { t, .. }
            | Event::ProcHeartbeat { t }
            | Event::Death { t, .. }
            | Event::EncounterDespawn { t, .. }
            | Event::GroupComplete { t, .. }
            | Event::PullComplete { t, .. }
            | Event::EncounterTerminate { t, .. }
            | Event::WaveActivate { t, .. }
            | Event::EnemyActivate { t, .. }
            | Event::Retarget { t, .. }
            | Event::EncounterMove { t, .. }
            | Event::ActorMovement { t, .. }
            | Event::RaidEvent { t, .. }
            | Event::RaidAddDespawn { t, .. }
            | Event::ExternalBuff { t, .. }
            | Event::HookTimer { t, .. }
            | Event::CooldownReady { t, .. }
            | Event::AutoAttack { t, .. }
            | Event::EnemyAutoAttack { t, .. } => *t,
        }
    }
    // docref:end event-system-timestamp
}

/// Executor contract: all spec interaction goes through this trait.
#[wowlab_engine_macros::spec_handler_delegation]
pub trait SpecHandler: Send {
    /// Install immutable encounter target metadata into a newly constructed telemetry sink.
    fn install_target_metadata(&self, _sink: &mut TelemetrySink) {}

    fn on_player_ready(&mut self, ctx: &mut SimContext) -> Option<SpecAction>;

    fn on_cast_complete(&mut self, event: Event, ctx: &mut SimContext);

    fn on_triggered_spell(
        &mut self,
        _spell: ScheduledSpellBinding,
        _source: ActorId,
        _target: ActorId,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_spell_impact(&mut self, _impact: PendingImpactBinding, _ctx: &mut SimContext) {}

    fn on_spell_launch(&mut self, _impact: PendingImpactBinding, _ctx: &mut SimContext) {}

    fn on_guardian_action(&mut self, _guardian: GuardianEventBinding, _ctx: &mut SimContext) {}

    fn on_guardian_expire(&mut self, _guardian: GuardianEventBinding, _ctx: &mut SimContext) {}

    fn on_pet_action(&mut self, _action: PetActionBinding, _ctx: &mut SimContext) {}

    fn on_aura_tick(&mut self, _event: AuraEventRef, _ctx: &mut SimContext) {}

    fn on_channel_tick(
        &mut self,
        _spell: ScheduledSpellBinding,
        _source: ActorId,
        _target: EnemyIdx,
        _generation: u64,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_aura_expire(&mut self, _event: AuraEventRef, _ctx: &mut SimContext) {}

    fn on_proc_heartbeat(&mut self, _ctx: &mut SimContext) {}

    fn on_death(&mut self, _target: EnemyIdx, _scope: DeathEventScope, _ctx: &mut SimContext) {}

    fn on_encounter_despawn(
        &mut self,
        _scope: PullScope,
        _target: EnemyIdx,
        _kind: EncounterDespawnKind,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_group_complete(&mut self, _scope: PullScope, _group: GroupId, _ctx: &mut SimContext) {}

    fn on_pull_complete(&mut self, _scope: PullScope, _finalize: bool, _ctx: &mut SimContext) {}

    fn on_encounter_terminate(
        &mut self,
        _reason: EncounterTerminationReason,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_wave_activate(&mut self, _scope: PullScope, _wave: WaveId, _ctx: &mut SimContext) {}

    fn on_enemy_activate(&mut self, _scope: PullScope, _target: EnemyIdx, _ctx: &mut SimContext) {}

    fn on_retarget(&mut self, _scope: PullScope, _ctx: &mut SimContext) {}

    fn on_encounter_move(
        &mut self,
        _scope: PullScope,
        _actor: PositionedActorRef,
        _transform: SpatialTransform,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_actor_movement(
        &mut self,
        _movement: ActorMovementBinding,
        _moving: bool,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_raid_event(&mut self, _event: RaidEventBinding, _ctx: &mut SimContext) {}

    fn on_raid_add_despawn(&mut self, _add: RaidAddBinding, _ctx: &mut SimContext) {}

    fn on_external_buff(&mut self, _buff: ExternalBuffBinding, _ctx: &mut SimContext) {}

    /// Called only when the shared event queue is empty.
    fn on_event_queue_empty(&mut self, _ctx: &mut SimContext) {}

    /// Exact termination timestamp once the encounter policy is satisfied.
    fn encounter_termination_time(&self) -> Option<SimTime> {
        None
    }

    /// Despawn an enemy through the canonical combat cleanup boundary.
    fn on_despawn(&mut self, _target: EnemyIdx, _ctx: &mut SimContext) -> EnemyDespawnOutcome {
        EnemyDespawnOutcome::UnknownEnemy
    }

    /// A `HookTimer` scheduled via the combat layer's `schedule_hook` came due.
    fn on_hook_timer(
        &mut self,
        _timer: HookTimerBinding,
        _source: ActorId,
        _target: Option<EnemyIdx>,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_auto_attack(&mut self, _source: ActorId, _target: EnemyIdx, _ctx: &mut SimContext) {}

    fn on_enemy_auto_attack(&mut self, _source: EnemyIdx, _target: ActorId, _ctx: &mut SimContext) {
    }

    fn on_cooldown_ready(&mut self, _spell: ScheduledSpellBinding, _ctx: &mut SimContext) {}

    fn on_sim_start(&mut self, ctx: &mut SimContext);

    /// Reset mutable per-iteration state without reallocating.
    fn reset(&mut self) {}

    fn flush_scheduled(&mut self, _push: &mut dyn FnMut(Event)) {}

    /// Take a fatal event-processing failure, if the handler recorded one.
    fn take_runtime_error(&mut self) -> Option<SpecRuntimeError> {
        None
    }

    fn total_damage(&self) -> f64;

    /// Cast time in milliseconds; 0 for instants.
    fn cast_time_ms(&self, spell: ScheduledSpellBinding, empower_rank: u8) -> u32;

    fn paperdoll(&self) -> Option<Paperdoll> {
        None
    }

    fn introspect(&self) -> wowlab_types::game::SpecIntrospection {
        wowlab_types::game::SpecIntrospection::default()
    }

    fn attach_decision_trace(&mut self, _sink: std::sync::Arc<dyn DecisionTraceSink>) {}
}

/// Simulation state and telemetry sink passed to spec handler callbacks.
#[derive(Debug)]
pub struct SimContext<'a> {
    pub state: &'a SimState,
    pub telemetry: &'a mut TelemetrySink,
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use rstest::rstest;
    use wowlab_engine_event_authority::{RuntimeEventCatalog, ScheduledSpellCatalog};

    use super::*;

    fn spell(id: u32) -> SpellIdx {
        SpellIdx::from_raw(id)
    }

    fn scheduled(id: u32) -> ScheduledSpellBinding {
        ScheduledSpellCatalog::new([spell(id)])
            .bind(0)
            .expect("single-spell catalog binds its only spell")
    }

    fn impact(slot: u32) -> PendingImpactBinding {
        RuntimeEventCatalog::new().pending_impact(slot, 1)
    }

    fn timer(slot: u32) -> HookTimerBinding {
        RuntimeEventCatalog::new().hook_timer(slot, 1)
    }

    fn guardian(ability: Option<u16>) -> GuardianEventBinding {
        RuntimeEventCatalog::new().guardian(1, 1, ability)
    }

    fn aura(local: u8, aura_key: AuraKey, target: Option<EnemyIdx>) -> AuraEventBinding {
        RuntimeEventCatalog::new().aura(local, 0, aura_key, target)
    }

    #[gtest]
    fn scheduled_spell_bindings_are_program_branded() -> Result<()> {
        let first = ScheduledSpellCatalog::new([spell(10)]);
        let second = ScheduledSpellCatalog::new([spell(10)]);
        let binding = first.bind(0).or_fail()?;

        verify_that!(first.validate(binding), eq(Some(0)))?;

        verify_that!(second.validate(binding), none())
    }

    #[gtest]
    fn scheduled_spell_catalog_binds_frozen_semantic_identity() -> Result<()> {
        let catalog = ScheduledSpellCatalog::new([spell(10), spell(20)]);
        let binding = catalog.bind_spell_id(spell(20)).or_fail()?;

        verify_that!(catalog.validate(binding), eq(Some(1)))?;

        verify_that!(catalog.bind_spell_id(spell(30)), none())
    }

    #[gtest]
    fn runtime_event_bindings_reject_foreign_programs() -> Result<()> {
        let first = RuntimeEventCatalog::new();
        let second = RuntimeEventCatalog::new();
        let aura_key = key(20);

        verify_that!(
            second.validate_pending_impact(first.pending_impact(0, 1)),
            none()
        )?;
        verify_that!(second.validate_hook_timer(first.hook_timer(0, 1)), none())?;
        verify_that!(
            second.validate_aura(first.aura(0, 0, aura_key, None)),
            none()
        )?;
        verify_that!(
            second.validate_guardian(first.guardian(0, 1, Some(0))),
            none()
        )?;
        verify_that!(second.validate_pet_action(first.pet_action(0)), none())?;
        verify_that!(second.validate_raid_event(first.raid_event(0)), none())?;
        verify_that!(
            second.validate_external_buff(first.external_buff(0)),
            none()
        )?;

        verify_that!(
            second.validate_actor_movement(first.actor_movement(ActorId::Player, 1)),
            none()
        )
    }

    fn key(id: u32) -> AuraKey {
        AuraKey::new(
            wowlab_types::sim::AuraIdx(id),
            ActorId::Player,
            ActorId::Enemy(EnemyIdx::PRIMARY),
            wowlab_types::sim::AuraOn::Target,
        )
    }

    fn transform() -> SpatialTransform {
        SpatialTransform {
            layer: wowlab_types::sim::SpatialLayerId(0),
            position: wowlab_types::sim::Position2::new(1.0, 2.0),
            heading: 0.5,
        }
    }

    #[gtest]
    #[rstest]
    #[case::player_ready(Event::PlayerReady { t: SimTime::from_millis(1) }, 1)]
    #[case::off_gcd_ready(Event::OffGcdReady { t: SimTime::from_millis(2) }, 2)]
    #[case::cast_start(Event::CastStart { t: SimTime::from_millis(3), spell: scheduled(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 3)]
    #[case::cast_complete(Event::CastComplete { t: SimTime::from_millis(4), spell: scheduled(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 4)]
    #[case::spell_launch(Event::SpellLaunch { t: SimTime::from_millis(14), impact: impact(6), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 14)]
    #[case::spell_impact(Event::SpellImpact { t: SimTime::from_millis(5), impact: impact(7), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 5)]
    #[case::guardian_action(Event::GuardianAction { t: SimTime::from_millis(10), guardian: guardian(Some(0)), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 10)]
    #[case::guardian_expire(Event::GuardianExpire { t: SimTime::from_millis(11), guardian: guardian(None) }, 11)]
    #[case::aura_tick(Event::AuraTick { t: SimTime::from_millis(6), aura: aura(0, key(20), Some(EnemyIdx::PRIMARY)) }, 6)]
    #[case::channel_tick(Event::ChannelTick { t: SimTime::from_millis(23), spell: scheduled(20), source: ActorId::Player, target: EnemyIdx::PRIMARY, generation: 1 }, 23)]
    #[case::aura_expire(Event::AuraExpire { t: SimTime::from_millis(7), aura: aura(0, key(20), Some(EnemyIdx::PRIMARY)) }, 7)]
    #[case::death(Event::Death { t: SimTime::from_millis(13), target: EnemyIdx::PRIMARY, scope: DeathEventScope::Unscoped }, 13)]
    #[case::encounter_despawn(Event::EncounterDespawn { t: SimTime::from_millis(15), scope: PullScope { pull: PullId(0), epoch: 1 }, target: EnemyIdx::PRIMARY, kind: EncounterDespawnKind::ForcedOptional }, 15)]
    #[case::group_complete(Event::GroupComplete { t: SimTime::from_millis(16), scope: PullScope { pull: PullId(0), epoch: 1 }, group: GroupId(0) }, 16)]
    #[case::pull_complete(Event::PullComplete { t: SimTime::from_millis(17), scope: PullScope { pull: PullId(0), epoch: 1 }, finalize: false }, 17)]
    #[case::encounter_terminate(Event::EncounterTerminate { t: SimTime::from_millis(18), reason: EncounterTerminationReason::RequiredGroupsComplete }, 18)]
    #[case::wave_activate(Event::WaveActivate { t: SimTime::from_millis(19), scope: PullScope { pull: PullId(0), epoch: 1 }, wave: WaveId(0) }, 19)]
    #[case::enemy_activate(Event::EnemyActivate { t: SimTime::from_millis(20), scope: PullScope { pull: PullId(0), epoch: 1 }, target: EnemyIdx::PRIMARY }, 20)]
    #[case::retarget(Event::Retarget { t: SimTime::from_millis(21), scope: PullScope { pull: PullId(0), epoch: 1 } }, 21)]
    #[case::encounter_move(Event::EncounterMove { t: SimTime::from_millis(22), scope: PullScope { pull: PullId(0), epoch: 1 }, actor: PositionedActorRef::Player, transform: transform() }, 22)]
    #[case::hook_timer(Event::HookTimer {
        t: SimTime::from_millis(12),
        timer: timer(3),
        source: ActorId::Player,
        target: Some(EnemyIdx::PRIMARY),
    }, 12)]
    #[case::cooldown_ready(Event::CooldownReady { t: SimTime::from_millis(8), spell: scheduled(30) }, 8)]
    #[case::auto_attack(Event::AutoAttack { t: SimTime::from_millis(9), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 9)]
    fn event_timestamp_reads_every_variant(
        #[case] event: Event,
        #[case] expected_ms: u32,
    ) -> Result<()> {
        verify_that!(event.timestamp(), eq(SimTime::from_millis(expected_ms)))
    }

    #[gtest]
    #[rstest]
    #[case::player_ready(Event::PlayerReady { t: SimTime::ZERO }, 10)]
    #[case::off_gcd_ready(Event::OffGcdReady { t: SimTime::ZERO }, 10)]
    #[case::cast_start(Event::CastStart { t: SimTime::ZERO, spell: scheduled(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 10)]
    #[case::cast_complete(Event::CastComplete { t: SimTime::ZERO, spell: scheduled(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 7)]
    #[case::spell_launch(Event::SpellLaunch { t: SimTime::ZERO, impact: impact(6), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 7)]
    #[case::spell_impact(Event::SpellImpact { t: SimTime::ZERO, impact: impact(7), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 8)]
    #[case::guardian_action(Event::GuardianAction { t: SimTime::ZERO, guardian: guardian(Some(0)), source: ActorId::Player, target: EnemyIdx::PRIMARY }, 8)]
    #[case::guardian_expire(Event::GuardianExpire { t: SimTime::ZERO, guardian: guardian(None) }, 0)]
    #[case::aura_tick(Event::AuraTick { t: SimTime::ZERO, aura: aura(0, key(20), Some(EnemyIdx::PRIMARY)) }, 8)]
    #[case::channel_tick(Event::ChannelTick { t: SimTime::ZERO, spell: scheduled(20), source: ActorId::Player, target: EnemyIdx::PRIMARY, generation: 1 }, 8)]
    #[case::aura_expire(Event::AuraExpire { t: SimTime::ZERO, aura: aura(0, key(20), Some(EnemyIdx::PRIMARY)) }, 9)]
    #[case::death(Event::Death { t: SimTime::ZERO, target: EnemyIdx::PRIMARY, scope: DeathEventScope::Unscoped }, 0)]
    #[case::encounter_despawn(Event::EncounterDespawn { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, target: EnemyIdx::PRIMARY, kind: EncounterDespawnKind::ForcedOptional }, 0)]
    #[case::group_complete(Event::GroupComplete { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, group: GroupId(0) }, 1)]
    #[case::pull_complete(Event::PullComplete { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, finalize: false }, 2)]
    #[case::encounter_terminate(Event::EncounterTerminate { t: SimTime::ZERO, reason: EncounterTerminationReason::RequiredGroupsComplete }, 3)]
    #[case::wave_activate(Event::WaveActivate { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, wave: WaveId(0) }, 4)]
    #[case::enemy_activate(Event::EnemyActivate { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, target: EnemyIdx::PRIMARY }, 4)]
    #[case::retarget(Event::Retarget { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 } }, 5)]
    #[case::encounter_move(Event::EncounterMove { t: SimTime::ZERO, scope: PullScope { pull: PullId(0), epoch: 1 }, actor: PositionedActorRef::Player, transform: transform() }, 6)]
    #[case::hook_timer(Event::HookTimer {
        t: SimTime::ZERO,
        timer: timer(3),
        source: ActorId::Player,
        target: Some(EnemyIdx::PRIMARY),
    }, 8)]
    #[case::cooldown_ready(Event::CooldownReady { t: SimTime::ZERO, spell: scheduled(30) }, 10)]
    #[case::auto_attack(Event::AutoAttack { t: SimTime::ZERO, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 8)]
    fn event_priority_matches_same_timestamp_contract(
        #[case] event: Event,
        #[case] expected_priority: u8,
    ) -> Result<()> {
        verify_that!(event.priority(), eq(expected_priority))
    }

    #[gtest]
    fn event_reference_value_types_preserve_fields() -> Result<()> {
        let aura = AuraEventRef::from_binding(aura(3, key(44), Some(EnemyIdx(3))));
        let scope = PullScope {
            pull: PullId(7),
            epoch: 11,
        };

        verify_that!(aura, eq(aura))?;

        verify_that!(
            scope,
            eq(PullScope {
                pull: PullId(7),
                epoch: 11,
            })
        )
    }
}