wowlab_types/

proto.rs

//! Protobuf-generated types for binary result encoding.

mod generated {
    #![expect(
        clippy::doc_markdown,
        clippy::must_use_candidate,
        clippy::struct_excessive_bools,
        reason = "prost-build owns these generated declarations and methods"
    )]

    include!(concat!(env!("OUT_DIR"), "/wowlab.sim.rs"));
}

use crate::constants::{PROTO_DPS_SCALE, PROTO_RESOURCE_SCALE};

#[rustfmt::skip]
pub use generated::{
    ActionRow, ActionSource, ActionTelemetry, ActorKind, AuraIntervalProto, AuraRow, AuraTelemetry,
    AuraWindow, BatchChunkCompletion, BatchWorkResult, CandidateItem, ChunkTelemetry, CooldownRow,
    CooldownTelemetry, CooldownWindow, DamageByTarget, DamageProfileData, DictionaryView,
    DistributionTelemetry, EncounterEventKind, EncounterTimelineEvent, ExecutionData,
    HistogramData, InstrumentationCoverage, JobResult, JobTimeline, MarkerKind, Percentiles,
    PermutationSummary, PhaseMarker, RepresentativeMeta, ResourceRow, ResourceSampleProto,
    ResourceSourceRow, ResourceTelemetry, ResultCoreV1, ResultFidelity, ResultViewV1,
    RunningAggregateStateV1, SingleResult, SingleTimeline, SlotCandidates, SlotDiff, SlotItemEntry,
    SlotRanking, TargetEntry, TimelineMarker, TimelineSnapshot, TimelineViewV1, TournamentPayload,
    TournamentResult, TournamentStats, TournamentTimeline, UnitEntry, job_result, job_timeline,
};

impl MarkerKind {
    /// Stable lower-case slug for a timeline marker kind, used by view-model DTOs.
    #[must_use]
    pub fn slug(self) -> &'static str {
        match self {
            MarkerKind::Damage => "damage",
            MarkerKind::Cast => "cast",
            MarkerKind::Resource => "resource",
            MarkerKind::Proc => "proc",
            MarkerKind::Unspecified => "unknown",
        }
    }
}

impl ChunkTelemetry {
    /// Mean DPS in real units.
    #[must_use]
    pub fn mean_dps(&self) -> f64 {
        f64::from(self.mean_dps_x10) / PROTO_DPS_SCALE
    }

    /// Minimum per-iteration DPS in real units.
    #[must_use]
    pub fn min_dps(&self) -> f64 {
        f64::from(self.min_dps_x10) / PROTO_DPS_SCALE
    }

    /// Maximum per-iteration DPS in real units.
    #[must_use]
    pub fn max_dps(&self) -> f64 {
        f64::from(self.max_dps_x10) / PROTO_DPS_SCALE
    }

    /// Standard deviation of per-iteration DPS, derived from the streaming M2 accumulator.
    #[must_use]
    pub fn std_dps(&self) -> f64 {
        let m2 = f64::from_bits(self.m2_dps_bits);
        let n = f64::from(self.iterations);

        if n > 0.0 {
            (m2 / n).max(0.0).sqrt()
        } else {
            0.0
        }
    }
}

impl ActionRow {
    /// Total damage attributed to this action in real units.
    #[must_use]
    #[expect(
        clippy::cast_precision_loss,
        reason = "fixed-point telemetry is intentionally decoded into f64 display units"
    )]
    pub fn total_damage(&self) -> f64 {
        self.total_damage_x10 as f64 / PROTO_DPS_SCALE
    }
}

impl ResourceRow {
    /// Total resource gained in real units.
    #[must_use]
    #[expect(
        clippy::cast_precision_loss,
        // #t(rust_duplicate_strings) Rust attributes require a literal reason at the declaration they govern.
        reason = "fixed-point telemetry is intentionally decoded into f64 display units"
    )]
    pub fn gained(&self) -> f64 {
        self.gained_x100 as f64 / PROTO_RESOURCE_SCALE
    }

    /// Total resource spent in real units.
    #[must_use]
    #[expect(
        clippy::cast_precision_loss,
        // #t(rust_duplicate_strings) Rust attributes require a literal reason at the declaration they govern.
        reason = "fixed-point telemetry is intentionally decoded into f64 display units"
    )]
    pub fn spent(&self) -> f64 {
        self.spent_x100 as f64 / PROTO_RESOURCE_SCALE
    }

    /// Total resource wasted (overcapped) in real units.
    #[must_use]
    #[expect(
        clippy::cast_precision_loss,
        // #t(rust_duplicate_strings) Rust attributes require a literal reason at the declaration they govern.
        reason = "fixed-point telemetry is intentionally decoded into f64 display units"
    )]
    pub fn wasted(&self) -> f64 {
        self.wasted_x100 as f64 / PROTO_RESOURCE_SCALE
    }
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use prost::Message;
    use rstest::rstest;

    use super::*;

    #[derive(Clone, Message, PartialEq)]
    struct LegacyActionRow {
        #[prost(uint32, tag = "1")]
        spell_id: u32,
        #[prost(uint32, tag = "2")]
        target_id: u32,
        #[prost(enumeration = "ActionSource", tag = "3")]
        source: i32,
        #[prost(uint64, tag = "10")]
        casts: u64,
        #[prost(uint64, tag = "20")]
        total_damage_x10: u64,
    }

    #[gtest]
    #[rstest]
    #[case::damage(MarkerKind::Damage, "damage")]
    #[case::cast(MarkerKind::Cast, "cast")]
    #[case::resource(MarkerKind::Resource, "resource")]
    #[case::proc(MarkerKind::Proc, "proc")]
    #[case::unspecified(MarkerKind::Unspecified, "unknown")]
    fn marker_kind_slug(#[case] kind: MarkerKind, #[case] expected: &str) -> Result<()> {
        verify_that!(kind.slug(), eq(expected))
    }

    #[gtest]
    fn chunk_telemetry_scaled_dps() -> Result<()> {
        let ct = ChunkTelemetry {
            mean_dps_x10: 12345,
            min_dps_x10: 12345,
            max_dps_x10: 12345,
            ..Default::default()
        };

        verify_that!(ct.mean_dps(), near(1234.5, 1e-9))?;
        verify_that!(ct.min_dps(), near(1234.5, 1e-9))?;

        verify_that!(ct.max_dps(), near(1234.5, 1e-9))
    }

    #[gtest]
    #[rstest]
    #[case::zero_iters(0, 16.0f64.to_bits(), 0.0)]
    #[case::known(4, 16.0f64.to_bits(), 2.0)]
    #[case::neg_m2_clamped(1, (-1.0f64).to_bits(), 0.0)]
    fn chunk_telemetry_std_dps(
        #[case] iterations: u32,
        #[case] m2_dps_bits: u64,
        #[case] expected: f64,
    ) -> Result<()> {
        let ct = ChunkTelemetry {
            iterations,
            m2_dps_bits,
            ..Default::default()
        };

        verify_that!(ct.std_dps(), near(expected, 1e-9))
    }

    #[gtest]
    fn action_row_total_damage() -> Result<()> {
        let row = ActionRow {
            total_damage_x10: 500,
            ..Default::default()
        };

        verify_that!(row.total_damage(), near(50.0, 1e-9))
    }

    #[gtest]
    fn additive_action_identity_fields_decode_legacy_wire_bytes() -> Result<()> {
        let legacy = LegacyActionRow {
            spell_id: 42,
            target_id: 7,
            source: ActionSource::Pet as i32,
            casts: 3,
            total_damage_x10: 125,
        };
        let decoded = ActionRow::decode(legacy.encode_to_vec().as_slice()).or_fail()?;

        verify_that!(decoded.spell_id, eq(42))?;
        verify_that!(decoded.target_id, eq(7))?;
        verify_that!(decoded.source, eq(ActionSource::Pet as i32))?;
        verify_that!(decoded.casts, eq(3))?;
        verify_that!(decoded.total_damage_x10, eq(125))?;
        verify_that!(decoded.source_kind, eq(ActorKind::Unspecified as i32))?;
        verify_that!(decoded.source_id, eq(0))?;
        verify_that!(decoded.pull_id, none())?;

        verify_that!(decoded.group_id, none())
    }

    #[gtest]
    #[rstest]
    #[case::gained(250, 0, 0, 2.5, 0.0, 0.0)]
    #[case::spent(0, 250, 0, 0.0, 2.5, 0.0)]
    #[case::wasted(0, 0, 250, 0.0, 0.0, 2.5)]
    fn resource_row_scaled(
        #[case] gained_x100: u64,
        #[case] spent_x100: u64,
        #[case] wasted_x100: u64,
        #[case] gained: f64,
        #[case] spent: f64,
        #[case] wasted: f64,
    ) -> Result<()> {
        let row = ResourceRow {
            gained_x100,
            spent_x100,
            wasted_x100,
            ..Default::default()
        };

        verify_that!(row.gained(), near(gained, 1e-9))?;
        verify_that!(row.spent(), near(spent, 1e-9))?;

        verify_that!(row.wasted(), near(wasted, 1e-9))
    }
}