wowlab_engine_ports/

spec_handler.rs

use wowlab_engine_telemetry::TelemetrySink;
use wowlab_types::{
    data::WeaponStats,
    game::GearSlot,
    sim::{
        ActorId, AuraKey, EnemyIdx, GroupId, PositionedActorRef, PullId, SimTime, SpatialTransform,
        SpellIdx, WaveId,
    },
};

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

/// 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_id: SpellIdx,
        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 {
    pub key: AuraKey,
    pub target: Option<EnemyIdx>,
}

/// 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,
    },
}
}

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,
            },
        }
    }

    /// 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,
        }
    }
}

/// Pull-local encounter generation (pull epoch plus lifecycle epoch) so prior events cannot match a newly active actor with the same identity.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct PullLifecycleGeneration {
    pull: PullId,
    pull_epoch: u32,
    lifecycle_epoch: u64,
}

impl PullLifecycleGeneration {
    #[must_use]
    pub const fn new(pull: PullId, pull_epoch: u32, lifecycle_epoch: u64) -> Self {
        Self {
            pull,
            pull_epoch,
            lifecycle_epoch,
        }
    }

    #[must_use]
    pub const fn pull(self) -> PullId {
        self.pull
    }

    #[must_use]
    pub const fn pull_epoch(self) -> u32 {
        self.pull_epoch
    }

    #[must_use]
    pub const fn lifecycle_epoch(self) -> u64 {
        self.lifecycle_epoch
    }
}

/// 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_id: SpellIdx,
        empower_rank: u8,
        source: ActorId,
        target: EnemyIdx,
    },
    CastComplete {
        t: SimTime,
        spell_id: SpellIdx,
        empower_rank: u8,
        source: ActorId,
        target: EnemyIdx,
    },
    /// Server-triggered cast retaining the exact affected actor identity.
    TriggeredSpell {
        t: SimTime,
        spell_id: SpellIdx,
        source: ActorId,
        target: ActorId,
    },
    SpellLaunch {
        t: SimTime,
        impact_id: u32,
        source: ActorId,
        target: EnemyIdx,
    },
    SpellImpact {
        t: SimTime,
        impact_id: u32,
        source: ActorId,
        target: EnemyIdx,
    },
    GuardianAction {
        t: SimTime,
        guardian_id: u32,
        guardian_generation: u32,
        ability_index: usize,
        source: ActorId,
        target: EnemyIdx,
    },
    GuardianExpire {
        t: SimTime,
        guardian_id: u32,
        guardian_generation: u32,
    },
    PetAction {
        t: SimTime,
        auto_attack_index: usize,
        source: ActorId,
        target: EnemyIdx,
    },
    AuraTick {
        t: SimTime,
        key: AuraKey,
        target: Option<EnemyIdx>,
    },
    ChannelTick {
        t: SimTime,
        spell_id: SpellIdx,
        source: ActorId,
        target: EnemyIdx,
        generation: u64,
    },
    AuraExpire {
        t: SimTime,
        key: AuraKey,
        target: Option<EnemyIdx>,
    },
    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,
        actor: ActorId,
        moving: bool,
        generation: u64,
    },
    RaidEvent {
        t: SimTime,
        index: usize,
    },
    RaidAddDespawn {
        t: SimTime,
        target: EnemyIdx,
        activation_generation: u64,
        encounter_generation: PullLifecycleGeneration,
    },
    ExternalBuff {
        t: SimTime,
        index: usize,
    },
    HookTimer {
        t: SimTime,
        timer_id: u32,
        source: ActorId,
        target: Option<EnemyIdx>,
    },
    CooldownReady {
        t: SimTime,
        cooldown_key: SpellIdx,
    },
    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 {
    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_id: SpellIdx,
        _source: ActorId,
        _target: ActorId,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_spell_impact(&mut self, _impact_id: u32, _ctx: &mut SimContext) {}

    fn on_spell_launch(&mut self, _impact_id: u32, _ctx: &mut SimContext) {}

    fn on_guardian_action(
        &mut self,
        _guardian_id: u32,
        _guardian_generation: u32,
        _ability_index: usize,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_guardian_expire(
        &mut self,
        _guardian_id: u32,
        _guardian_generation: u32,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_pet_action(&mut self, _auto_attack_index: usize, _ctx: &mut SimContext) {}

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

    fn on_channel_tick(
        &mut self,
        _spell_id: SpellIdx,
        _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,
        _actor: ActorId,
        _moving: bool,
        _generation: u64,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_raid_event(&mut self, _index: usize, _ctx: &mut SimContext) {}

    fn on_raid_add_despawn(
        &mut self,
        _target: EnemyIdx,
        _activation_generation: u64,
        _encounter_generation: PullLifecycleGeneration,
        _ctx: &mut SimContext,
    ) {
    }

    fn on_external_buff(&mut self, _index: usize, _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_id: u32,
        _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, _cooldown_key: SpellIdx, _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_id: SpellIdx, 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 super::*;

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

    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_id: spell(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 3)]
    #[case::cast_complete(Event::CastComplete { t: SimTime::from_millis(4), spell_id: spell(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 4)]
    #[case::spell_launch(Event::SpellLaunch { t: SimTime::from_millis(14), impact_id: 6, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 14)]
    #[case::spell_impact(Event::SpellImpact { t: SimTime::from_millis(5), impact_id: 7, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 5)]
    #[case::guardian_action(Event::GuardianAction { t: SimTime::from_millis(10), guardian_id: 1, guardian_generation: 1, ability_index: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 10)]
    #[case::guardian_expire(Event::GuardianExpire { t: SimTime::from_millis(11), guardian_id: 1, guardian_generation: 1 }, 11)]
    #[case::aura_tick(Event::AuraTick { t: SimTime::from_millis(6), key: key(20), target: Some(EnemyIdx::PRIMARY) }, 6)]
    #[case::channel_tick(Event::ChannelTick { t: SimTime::from_millis(23), spell_id: spell(20), source: ActorId::Player, target: EnemyIdx::PRIMARY, generation: 1 }, 23)]
    #[case::aura_expire(Event::AuraExpire { t: SimTime::from_millis(7), key: key(20), target: 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_id: 3,
        source: ActorId::Player,
        target: Some(EnemyIdx::PRIMARY),
    }, 12)]
    #[case::cooldown_ready(Event::CooldownReady { t: SimTime::from_millis(8), cooldown_key: spell(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_id: spell(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 10)]
    #[case::cast_complete(Event::CastComplete { t: SimTime::ZERO, spell_id: spell(10), empower_rank: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 7)]
    #[case::spell_launch(Event::SpellLaunch { t: SimTime::ZERO, impact_id: 6, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 7)]
    #[case::spell_impact(Event::SpellImpact { t: SimTime::ZERO, impact_id: 7, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 8)]
    #[case::guardian_action(Event::GuardianAction { t: SimTime::ZERO, guardian_id: 1, guardian_generation: 1, ability_index: 0, source: ActorId::Player, target: EnemyIdx::PRIMARY }, 8)]
    #[case::guardian_expire(Event::GuardianExpire { t: SimTime::ZERO, guardian_id: 1, guardian_generation: 1 }, 0)]
    #[case::aura_tick(Event::AuraTick { t: SimTime::ZERO, key: key(20), target: Some(EnemyIdx::PRIMARY) }, 8)]
    #[case::channel_tick(Event::ChannelTick { t: SimTime::ZERO, spell_id: spell(20), source: ActorId::Player, target: EnemyIdx::PRIMARY, generation: 1 }, 8)]
    #[case::aura_expire(Event::AuraExpire { t: SimTime::ZERO, key: key(20), target: 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_id: 3,
        source: ActorId::Player,
        target: Some(EnemyIdx::PRIMARY),
    }, 8)]
    #[case::cooldown_ready(Event::CooldownReady { t: SimTime::ZERO, cooldown_key: spell(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 {
            key: key(44),
            target: Some(EnemyIdx(3)),
        };
        let scope = PullScope {
            pull: PullId(7),
            epoch: 11,
        };

        verify_that!(
            aura,
            eq(AuraEventRef {
                key: key(44),
                target: Some(EnemyIdx(3)),
            })
        )?;

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