wowlab_engine_event_authority/

lib.rs

// #t(file: rust_similar_structs) Opaque event token families deliberately remain distinct so equal-shaped coordinates cannot be interchanged.

//! Engine-owned authority for minting and validating opaque scheduled-event bindings.

use std::sync::atomic::{AtomicU64, Ordering};

use wowlab_types::sim::{ActorId, AuraKey, EnemyIdx, PullId, SpellIdx};

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct ScheduledSpellBinding {
    program: u64,
    local: u16,
    spell_id: SpellIdx,
}

/// Raw scheduled-spell inspection for engine implementation crates.
///
/// This trait is deliberately not re-exported by the public Ports boundary.
pub trait EngineScheduledSpellAccess {
    fn engine_coordinates(self) -> SpellIdx;
}

impl EngineScheduledSpellAccess for ScheduledSpellBinding {
    fn engine_coordinates(self) -> SpellIdx {
        self.spell_id
    }
}

#[derive(Debug)]
pub struct ScheduledSpellCatalog {
    program: u64,
    spell_ids: Box<[SpellIdx]>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct PendingImpactBinding {
    program: u64,
    slot: u32,
    generation: u32,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct HookTimerBinding {
    program: u64,
    slot: u32,
    generation: u32,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct AuraEventBinding {
    program: u64,
    local: u8,
    concrete: u32,
    key: AuraKey,
    target: Option<EnemyIdx>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct GuardianEventBinding {
    program: u64,
    slot: u32,
    generation: u32,
    ability: Option<u16>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct PetActionBinding {
    program: u64,
    plan: u16,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct RaidEventBinding {
    program: u64,
    plan: u16,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct ExternalBuffBinding {
    program: u64,
    plan: u16,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct ActorMovementBinding {
    program: u64,
    actor: ActorId,
    generation: u64,
}

#[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
    }
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[must_use]
pub struct RaidAddBinding {
    program: u64,
    target: EnemyIdx,
    activation_generation: u64,
    encounter_generation: PullLifecycleGeneration,
}

/// Diagnostic aura inspection available only to engine crates that depend on this authority.
pub trait DiagnosticEventBinding {
    type Coordinates;

    fn diagnostic_coordinates(self) -> Self::Coordinates;
}

impl DiagnosticEventBinding for AuraEventBinding {
    type Coordinates = (AuraKey, Option<EnemyIdx>);

    fn diagnostic_coordinates(self) -> Self::Coordinates {
        (self.key, self.target)
    }
}

/// Diagnostic guardian inspection available only to engine crates that depend on this authority.
impl DiagnosticEventBinding for GuardianEventBinding {
    type Coordinates = (u32, u32);

    fn diagnostic_coordinates(self) -> Self::Coordinates {
        (self.slot, self.generation)
    }
}

/// Diagnostic raid-add inspection available only to engine crates that depend on this authority.
impl DiagnosticEventBinding for RaidAddBinding {
    type Coordinates = u64;

    fn diagnostic_coordinates(self) -> Self::Coordinates {
        self.activation_generation
    }
}

#[derive(Debug)]
pub struct RuntimeEventCatalog {
    program: u64,
}

impl RuntimeEventCatalog {
    #[must_use]
    pub fn new() -> Self {
        // #t(rust_global_state) Copy event tokens require a process-unique monotonic program brand to reject cross-program delivery.
        static NEXT_PROGRAM: AtomicU64 = AtomicU64::new(1);

        Self {
            program: NEXT_PROGRAM.fetch_add(1, Ordering::Relaxed),
        }
    }

    pub const fn pending_impact(&self, slot: u32, generation: u32) -> PendingImpactBinding {
        PendingImpactBinding {
            program: self.program,
            slot,
            generation,
        }
    }

    #[must_use]
    pub const fn validate_pending_impact(
        &self,
        binding: PendingImpactBinding,
    ) -> Option<(u32, u32)> {
        if binding.program == self.program {
            Some((binding.slot, binding.generation))
        } else {
            None
        }
    }

    pub const fn hook_timer(&self, slot: u32, generation: u32) -> HookTimerBinding {
        HookTimerBinding {
            program: self.program,
            slot,
            generation,
        }
    }

    #[must_use]
    pub const fn validate_hook_timer(&self, binding: HookTimerBinding) -> Option<(u32, u32)> {
        if binding.program == self.program {
            Some((binding.slot, binding.generation))
        } else {
            None
        }
    }

    pub const fn aura(
        &self,
        local: u8,
        concrete: u32,
        key: AuraKey,
        target: Option<EnemyIdx>,
    ) -> AuraEventBinding {
        AuraEventBinding {
            program: self.program,
            local,
            concrete,
            key,
            target,
        }
    }

    #[must_use]
    pub const fn validate_aura(
        &self,
        binding: AuraEventBinding,
    ) -> Option<(u8, u32, AuraKey, Option<EnemyIdx>)> {
        if binding.program == self.program {
            Some((binding.local, binding.concrete, binding.key, binding.target))
        } else {
            None
        }
    }

    pub const fn guardian(
        &self,
        slot: u32,
        generation: u32,
        ability: Option<u16>,
    ) -> GuardianEventBinding {
        GuardianEventBinding {
            program: self.program,
            slot,
            generation,
            ability,
        }
    }

    #[must_use]
    pub const fn validate_guardian(
        &self,
        binding: GuardianEventBinding,
    ) -> Option<(u32, u32, Option<u16>)> {
        if binding.program == self.program {
            Some((binding.slot, binding.generation, binding.ability))
        } else {
            None
        }
    }

    pub const fn pet_action(&self, plan: u16) -> PetActionBinding {
        PetActionBinding {
            program: self.program,
            plan,
        }
    }

    #[must_use]
    pub const fn validate_pet_action(&self, binding: PetActionBinding) -> Option<u16> {
        if binding.program == self.program {
            Some(binding.plan)
        } else {
            None
        }
    }

    pub const fn raid_event(&self, plan: u16) -> RaidEventBinding {
        RaidEventBinding {
            program: self.program,
            plan,
        }
    }

    #[must_use]
    pub const fn validate_raid_event(&self, binding: RaidEventBinding) -> Option<u16> {
        if binding.program == self.program {
            Some(binding.plan)
        } else {
            None
        }
    }

    pub const fn external_buff(&self, plan: u16) -> ExternalBuffBinding {
        ExternalBuffBinding {
            program: self.program,
            plan,
        }
    }

    #[must_use]
    pub const fn validate_external_buff(&self, binding: ExternalBuffBinding) -> Option<u16> {
        if binding.program == self.program {
            Some(binding.plan)
        } else {
            None
        }
    }

    pub const fn actor_movement(&self, actor: ActorId, generation: u64) -> ActorMovementBinding {
        ActorMovementBinding {
            program: self.program,
            actor,
            generation,
        }
    }

    #[must_use]
    pub const fn validate_actor_movement(
        &self,
        binding: ActorMovementBinding,
    ) -> Option<(ActorId, u64)> {
        if binding.program == self.program {
            Some((binding.actor, binding.generation))
        } else {
            None
        }
    }

    pub const fn raid_add(
        &self,
        target: EnemyIdx,
        activation_generation: u64,
        encounter_generation: PullLifecycleGeneration,
    ) -> RaidAddBinding {
        RaidAddBinding {
            program: self.program,
            target,
            activation_generation,
            encounter_generation,
        }
    }

    #[must_use]
    pub const fn validate_raid_add(
        &self,
        binding: RaidAddBinding,
    ) -> Option<(EnemyIdx, u64, PullLifecycleGeneration)> {
        if binding.program == self.program {
            Some((
                binding.target,
                binding.activation_generation,
                binding.encounter_generation,
            ))
        } else {
            None
        }
    }
}

impl Default for RuntimeEventCatalog {
    fn default() -> Self {
        Self::new()
    }
}

impl ScheduledSpellCatalog {
    #[must_use]
    pub fn new(spell_ids: impl IntoIterator<Item = SpellIdx>) -> Self {
        // #t(rust_global_state) Copy event tokens require a process-unique monotonic program brand to reject cross-program delivery.
        static NEXT_PROGRAM: AtomicU64 = AtomicU64::new(1);

        Self {
            program: NEXT_PROGRAM.fetch_add(1, Ordering::Relaxed),
            spell_ids: spell_ids.into_iter().collect(),
        }
    }

    #[must_use]
    pub fn bind(&self, local: u16) -> Option<ScheduledSpellBinding> {
        let spell_id = self.spell_ids.get(usize::from(local)).copied()?;

        Some(ScheduledSpellBinding {
            program: self.program,
            local,
            spell_id,
        })
    }

    #[must_use]
    pub fn bind_spell_id(&self, spell_id: SpellIdx) -> Option<ScheduledSpellBinding> {
        let local = self
            .spell_ids
            .iter()
            .position(|candidate| *candidate == spell_id)
            .and_then(|index| u16::try_from(index).ok())?;

        self.bind(local)
    }

    #[must_use]
    pub fn validate(&self, binding: ScheduledSpellBinding) -> Option<u16> {
        (binding.program == self.program
            && self
                .spell_ids
                .get(usize::from(binding.local))
                .is_some_and(|spell| *spell == binding.spell_id))
        .then_some(binding.local)
    }
}