overlord_event_system/fight/

metrics.rs

//! Combat-feel metrics for the fight simulation.
//!
//! A pure observer. The collector samples fight state once per game tick and
//! inspects the event stream as it flows through the engine, but it never
//! mutates [`OverlordState`], never emits events, and never touches the RNG
//! stream. The metrics live on [`FightSim`](super::FightSim), *outside* the
//! simulated state, so a fight run with metrics on is byte-identical to one
//! run with them off — determinism of the sim and of live resume is preserved.
//!
//! What it measures (per entity, aggregated per team + for the hero):
//! - **idle-in-contact**: ticks where the entity's body is free (no
//!   `CastAbility`/`CastBasicAbility` queued) *and* it has a valid target in
//!   range — i.e. it could be attacking but isn't. Target metric `< 15%`.
//! - **body busy**: ticks where the entity has a `CastAbility`/`CastBasicAbility`
//!   in its queue. Target for the hero `40..=80%`.
//! - **whiffs**: `CastAbility` events whose target was already dead/absent.
//!   Target `0` (see plan §4 п.8, retarget-instead-of-whiff).
//! - **hits-while-casting**: `Damage` events landed on an entity while it was
//!   mid-cast.
//! - **dispersion**: a sliding 10 s window of idle-in-contact share; the max
//!   over all full windows must stay `<= 40%` — the primary criterion, since
//!   the residual bad feel correlated with bunched "cold" stretches that a
//!   fight-average hides.
//!
//! A2-BAL-001 calibration additions (per entity, boss rows are the ones that
//! matter):
//! - **alive ticks** (`sampled_ticks`): the card's `F`, the entity's lifetime
//!   from spawn to death. Dead entities are skipped by `sample`, so the count
//!   stops at death without needing a death hook.
//! - **stunned ticks**: the card's `S_actual`. Read off the `stun_until_tick`
//!   attribute the `EntityStun` handler stamps, compared against the sampled
//!   tick — so it counts real frozen time, not the nominal stun duration, and
//!   a stun truncated by death is counted only for the ticks it actually ran.
//! - **damage dealt**: the card's `D_old` when measured on the boss row.
//!   Credited from `Damage.by_entity_id`, the same attribution the end-of-fight
//!   breakdown uses.
//! - **casts started / completed**: `StartCastAbility` and `CastAbility`. Their
//!   difference is the cancelled count the card requires to be recorded before
//!   and after the change.
//!
//! A2-BAL-002 §2.5 survival-pressure additions:
//! - **min HP fraction**: the LOWEST `hp / max_hp` the entity reached at any
//!   sampled tick. The card mandates this instead of final HP because
//!   regeneration can return final HP to 100 % and hide every point of damage
//!   taken — a boss fight that looked comfortable and one that nearly killed the
//!   player are indistinguishable by final HP.
//! - **healing received and overheal**: without these, a sustain build's real
//!   incoming damage is invisible — it shows as "never dropped low" when in
//!   fact it absorbed and healed through a great deal.

use std::collections::{HashMap, VecDeque};

use essences::entity::{ActionPriority, Entity, EntityId};
use essences::fighting::{ActiveFight, EntityTeam};

use crate::event::OverlordEvent;
use crate::mechanics::content_lookups::ContentLookups;
use crate::state::OverlordState;

/// Game ticks per dispersion window: 10 s at 100 ms/tick.
const WINDOW_TICKS: usize = 100;

/// Dispersion criterion: no full 10 s window's idle-in-contact share may
/// exceed this percentage.
pub const DISPERSION_IDLE_SHARE_THRESHOLD_PCT: f64 = 40.0;

/// Absolute tick deadline stamped by the `EntityStun` handler. The single
/// source of the name — the handler reads it from here, so the observer can
/// never drift from the mechanic it observes.
pub const STUN_UNTIL_TICK_ATTR: &str = "stun_until_tick";

/// Per-entity accumulators. Kept out of `OverlordState`, so purely observational.
#[derive(Debug, Clone, Default)]
struct EntityCounters {
    team: EntityTeam,
    sampled_ticks: u64,
    idle_in_contact_ticks: u64,
    body_busy_ticks: u64,
    whiffs: u64,
    hits_while_casting: u64,
    /// Rolling last-`WINDOW_TICKS` idle-in-contact flags for the dispersion
    /// window, plus a running true-count so the share is O(1) per sample.
    idle_window: VecDeque<bool>,
    window_idle_count: usize,
    /// Max idle-in-contact share (0..=1) over any *full* window seen so far.
    /// `None` until the entity has been sampled for a whole window.
    max_window_idle_share: Option<f64>,
    /// A2-BAL-001: does this entity carry the big HP bar (`is_boss` on its
    /// template)? The stagger mechanic keys off exactly this flag, so it is
    /// also what selects the boss row for calibration.
    is_boss: bool,
    /// A2-BAL-001 `S_actual`: sampled ticks where the entity was frozen.
    stunned_ticks: u64,
    /// A2-BAL-001 `D_old` on the boss row: damage this entity dealt.
    damage_dealt: u64,
    casts_started: u64,
    casts_completed: u64,
    /// `EntityStun` events applied to this entity. The card's acceptance check
    /// is that ordinary damage produces strictly zero of these, so it needs a
    /// direct count and not an inference from `stunned_ticks` (a sub-tick stun
    /// would leave no sampled tick behind).
    stuns_applied: u64,
    /// Lowest `hp / max_hp` seen at any sampled tick. `None` until first sample.
    min_hp_fraction: Option<f64>,
    /// Healing that landed on this entity, and the part of it that was wasted
    /// because the entity was already at full HP.
    healing_received: u64,
    overheal: u64,
}

impl EntityCounters {
    fn record_sample(
        &mut self,
        idle_in_contact: bool,
        body_busy: bool,
        stunned: bool,
        hp_fraction: f64,
    ) {
        self.sampled_ticks += 1;
        self.min_hp_fraction = Some(
            self.min_hp_fraction
                .map_or(hp_fraction, |m: f64| m.min(hp_fraction)),
        );
        if stunned {
            self.stunned_ticks += 1;
        }
        if idle_in_contact {
            self.idle_in_contact_ticks += 1;
        }
        if body_busy {
            self.body_busy_ticks += 1;
        }

        self.idle_window.push_back(idle_in_contact);
        if idle_in_contact {
            self.window_idle_count += 1;
        }
        if self.idle_window.len() > WINDOW_TICKS
            && let Some(true) = self.idle_window.pop_front()
        {
            self.window_idle_count -= 1;
        }
        if self.idle_window.len() == WINDOW_TICKS {
            let share = self.window_idle_count as f64 / WINDOW_TICKS as f64;
            self.max_window_idle_share =
                Some(self.max_window_idle_share.map_or(share, |m| m.max(share)));
        }
    }
}

/// The collector. One instance per [`FightSim`](super::FightSim).
#[derive(Debug, Clone, Default)]
pub struct FightMetrics {
    entities: HashMap<EntityId, EntityCounters>,
    total_sampled_ticks: u64,
}

impl FightMetrics {
    /// Sample the live fight once, at a game-tick boundary. Called by the
    /// engine after a tick's events have settled, only while the fight is
    /// ongoing. Read-only over `state`.
    pub(super) fn sample(
        &mut self,
        state: &OverlordState,
        lookups: &ContentLookups,
        current_tick: u64,
    ) {
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        self.total_sampled_ticks += 1;

        for entity in &fight.entities {
            // Dead entities are removed from the fight on death; guard anyway so
            // a marked-dead-but-not-yet-swept unit never counts as idle.
            if entity.hp == 0 {
                continue;
            }
            let body_busy = is_body_busy(entity);
            let idle_in_contact = !body_busy && has_valid_target_in_range(entity, fight, lookups);
            // Real frozen time, not nominal stun duration: the handler stamps
            // an absolute deadline, so a stun cut short by death contributes
            // only the ticks it actually covered.
            let stunned = entity
                .attributes
                .0
                .get(STUN_UNTIL_TICK_ATTR)
                .is_some_and(|until| *until > current_tick as i64);

            let counters = self.entities.entry(entity.id).or_default();
            counters.team = entity.team.clone();
            counters.is_boss = entity.has_big_hp_bar;
            let hp_fraction = if entity.max_hp > 0 {
                entity.hp as f64 / entity.max_hp as f64
            } else {
                0.0
            };
            counters.record_sample(idle_in_contact, body_busy, stunned, hp_fraction);
        }
    }

    /// Inspect one event against the pre-handler state. Counts whiffs (a
    /// `CastAbility` with no live target) and hits landed on a mid-cast body.
    /// Read-only over `pre_state`.
    pub(super) fn observe_event(&mut self, event: &OverlordEvent, pre_state: &OverlordState) {
        let Some(fight) = pre_state.active_fight.as_ref() else {
            return;
        };
        match event {
            OverlordEvent::CastAbility {
                by_entity_id,
                to_entity_id,
                ..
            } => {
                let has_live_target = fight
                    .entities
                    .iter()
                    .any(|e| e.id == *to_entity_id && e.hp > 0);
                if !has_live_target {
                    self.counters_for(*by_entity_id, fight).whiffs += 1;
                }
                self.counters_for(*by_entity_id, fight).casts_completed += 1;
            }
            OverlordEvent::Damage {
                entity_id,
                by_entity_id,
                damage,
                ..
            } => {
                if let Some(victim) = fight.entities.iter().find(|e| e.id == *entity_id)
                    && is_body_busy(victim)
                {
                    let team = victim.team.clone();
                    let counters = self.entities.entry(*entity_id).or_default();
                    counters.team = team;
                    counters.hits_while_casting += 1;
                }
                // A2-BAL-001 `D_old`: credited to the dealer, matching the
                // end-of-fight breakdown's attribution. Ownerless environment
                // damage (`None`) belongs to no combatant and is skipped.
                if let Some(dealer) = by_entity_id {
                    self.counters_for(*dealer, fight).damage_dealt += damage;
                }
            }
            OverlordEvent::StartCastAbility { by_entity_id, .. } => {
                self.counters_for(*by_entity_id, fight).casts_started += 1;
            }
            OverlordEvent::EntityStun { entity_id, .. } => {
                self.counters_for(*entity_id, fight).stuns_applied += 1;
            }
            OverlordEvent::Heal {
                entity_id, heal, ..
            } => {
                // Overheal is computed against the PRE-handler state, which is
                // what `observe_event` is handed: the headroom the target still
                // had when the heal landed.
                let headroom = fight
                    .entities
                    .iter()
                    .find(|e| e.id == *entity_id)
                    .map(|e| e.max_hp.saturating_sub(e.hp))
                    .unwrap_or(0);
                let counters = self.counters_for(*entity_id, fight);
                counters.healing_received += heal;
                counters.overheal += heal.saturating_sub(headroom);
            }
            _ => {}
        }
    }

    /// Fetch (or create) the counters for `id`, keeping the team label in sync
    /// with the fight if the entity is present.
    fn counters_for(&mut self, id: EntityId, fight: &ActiveFight) -> &mut EntityCounters {
        let team = fight
            .entities
            .iter()
            .find(|e| e.id == id)
            .map(|e| e.team.clone());
        let counters = self.entities.entry(id).or_default();
        if let Some(team) = team {
            counters.team = team;
        }
        counters
    }

    /// Structured, serde-serializable snapshot for the sim harness / tests.
    /// `player_id` selects the hero breakout.
    pub fn summary(&self, player_id: Option<EntityId>) -> FightMetricsSummary {
        let mut entities: Vec<EntityMetrics> = self
            .entities
            .iter()
            .map(|(id, c)| EntityMetrics::new(*id, c))
            .collect();
        // Deterministic ordering for stable logs/snapshots.
        entities.sort_by_key(|e| *e.entity_id.as_bytes());

        let hero =
            player_id.and_then(|id| self.entities.get(&id).map(|c| EntityMetrics::new(id, c)));

        let ally = self.team_metrics(EntityTeam::Ally);
        let enemy = self.team_metrics(EntityTeam::Enemy);

        let max_window_idle_share_pct = entities
            .iter()
            .filter_map(|e| e.max_window_idle_share_pct)
            .fold(None, |acc: Option<f64>, v| {
                Some(acc.map_or(v, |m| m.max(v)))
            });
        let dispersion_ok =
            max_window_idle_share_pct.is_none_or(|m| m <= DISPERSION_IDLE_SHARE_THRESHOLD_PCT);

        let bosses: Vec<EntityMetrics> = entities.iter().filter(|e| e.is_boss).cloned().collect();

        FightMetricsSummary {
            total_sampled_ticks: self.total_sampled_ticks,
            total_whiffs: self.entities.values().map(|c| c.whiffs).sum(),
            hero,
            ally,
            enemy,
            bosses,
            entities,
            max_window_idle_share_pct,
            dispersion_ok,
        }
    }

    fn team_metrics(&self, team: EntityTeam) -> TeamMetrics {
        let members: Vec<&EntityCounters> =
            self.entities.values().filter(|c| c.team == team).collect();

        let sampled_ticks: u64 = members.iter().map(|c| c.sampled_ticks).sum();
        let idle_ticks: u64 = members.iter().map(|c| c.idle_in_contact_ticks).sum();
        let body_ticks: u64 = members.iter().map(|c| c.body_busy_ticks).sum();
        let max_window_idle_share_pct = members
            .iter()
            .filter_map(|c| c.max_window_idle_share.map(|s| s * 100.0))
            .fold(None, |acc: Option<f64>, v| {
                Some(acc.map_or(v, |m| m.max(v)))
            });

        TeamMetrics {
            team,
            sampled_ticks,
            idle_share_pct: pct(idle_ticks, sampled_ticks),
            body_busy_share_pct: pct(body_ticks, sampled_ticks),
            whiffs: members.iter().map(|c| c.whiffs).sum(),
            hits_while_casting: members.iter().map(|c| c.hits_while_casting).sum(),
            max_window_idle_share_pct,
            dispersion_ok: max_window_idle_share_pct
                .is_none_or(|m| m <= DISPERSION_IDLE_SHARE_THRESHOLD_PCT),
        }
    }
}

/// A body is "busy" when a `CastAbility` (Second) or `CastBasicAbility` (Third)
/// action is queued — the same notion the queue uses to block a new
/// `StartCastAbility` (`is_casting_spell`).
fn is_body_busy(entity: &Entity) -> bool {
    let queues = entity.actions_queue.view();
    [ActionPriority::Second, ActionPriority::Third]
        .iter()
        .any(|p| queues.get(p).is_some_and(|q| !q.is_empty()))
}

/// Mirrors `mechanics::fight::is_valid_target` over every equipped ability:
/// does the entity have at least one ability whose target-type + range yields a
/// live opposing/allied target in range? Read-only; uses only public lookups.
fn has_valid_target_in_range(
    entity: &Entity,
    fight: &ActiveFight,
    lookups: &ContentLookups,
) -> bool {
    for active in &entity.abilities {
        let ability_id = active.ability.template_id;
        let target_type = lookups
            .ability_target_type
            .get(&ability_id)
            .map(|s| s.as_str())
            .unwrap_or("");
        let range = lookups.ability_range.get(&ability_id).copied().unwrap_or(0);
        for other in &fight.entities {
            if other.hp == 0 {
                continue;
            }
            let by_team = match target_type {
                "Enemy" => other.team != entity.team,
                "Ally" => other.team == entity.team,
                _ => false,
            };
            if by_team && (other.coordinates.x - entity.coordinates.x).abs() <= range {
                return true;
            }
        }
    }
    false
}

fn pct(num: u64, den: u64) -> f64 {
    if den == 0 {
        0.0
    } else {
        num as f64 / den as f64 * 100.0
    }
}

/// Per-entity summary line.
#[derive(Debug, Clone, serde::Serialize)]
pub struct EntityMetrics {
    pub entity_id: EntityId,
    pub team: EntityTeam,
    pub sampled_ticks: u64,
    pub idle_in_contact_ticks: u64,
    pub body_busy_ticks: u64,
    pub whiffs: u64,
    pub hits_while_casting: u64,
    pub idle_share_pct: f64,
    pub body_busy_share_pct: f64,
    pub max_window_idle_share_pct: Option<f64>,
    /// A2-BAL-001. `sampled_ticks` is the entity's lifetime `F` in game ticks;
    /// `stunned_ticks` is `S_actual` in the same unit, so `stun_share_pct` is
    /// `100 × S_actual / F` directly.
    pub is_boss: bool,
    pub stunned_ticks: u64,
    pub stun_share_pct: f64,
    pub damage_dealt: u64,
    pub casts_started: u64,
    pub casts_completed: u64,
    /// Started but never completed — the casts the stun ate. Saturating: a cast
    /// still in flight when the fight ends would otherwise underflow.
    pub casts_cancelled: u64,
    pub stuns_applied: u64,
    /// A2-BAL-002 §2.5. `None` if the entity was never sampled alive.
    pub min_hp_fraction: Option<f64>,
    pub healing_received: u64,
    pub overheal: u64,
}

impl EntityMetrics {
    fn new(entity_id: EntityId, c: &EntityCounters) -> Self {
        Self {
            entity_id,
            team: c.team.clone(),
            sampled_ticks: c.sampled_ticks,
            idle_in_contact_ticks: c.idle_in_contact_ticks,
            body_busy_ticks: c.body_busy_ticks,
            whiffs: c.whiffs,
            hits_while_casting: c.hits_while_casting,
            idle_share_pct: pct(c.idle_in_contact_ticks, c.sampled_ticks),
            body_busy_share_pct: pct(c.body_busy_ticks, c.sampled_ticks),
            max_window_idle_share_pct: c.max_window_idle_share.map(|s| s * 100.0),
            is_boss: c.is_boss,
            stunned_ticks: c.stunned_ticks,
            stun_share_pct: pct(c.stunned_ticks, c.sampled_ticks),
            damage_dealt: c.damage_dealt,
            casts_started: c.casts_started,
            casts_completed: c.casts_completed,
            casts_cancelled: c.casts_started.saturating_sub(c.casts_completed),
            stuns_applied: c.stuns_applied,
            min_hp_fraction: c.min_hp_fraction,
            healing_received: c.healing_received,
            overheal: c.overheal,
        }
    }
}

/// Per-team aggregate.
#[derive(Debug, Clone, serde::Serialize)]
pub struct TeamMetrics {
    pub team: EntityTeam,
    pub sampled_ticks: u64,
    pub idle_share_pct: f64,
    pub body_busy_share_pct: f64,
    pub whiffs: u64,
    pub hits_while_casting: u64,
    pub max_window_idle_share_pct: Option<f64>,
    pub dispersion_ok: bool,
}

/// Whole-fight structured summary. Serialize to JSON for the sim harness, or
/// read the fields directly in tests.
#[derive(Debug, Clone, serde::Serialize)]
pub struct FightMetricsSummary {
    pub total_sampled_ticks: u64,
    pub total_whiffs: u64,
    pub hero: Option<EntityMetrics>,
    pub ally: TeamMetrics,
    pub enemy: TeamMetrics,
    pub entities: Vec<EntityMetrics>,
    /// Max idle-in-contact share over any full 10 s window, any entity.
    pub max_window_idle_share_pct: Option<f64>,
    /// The primary criterion: no full window exceeded the dispersion threshold.
    pub dispersion_ok: bool,
    /// A2-BAL-001 calibration row: the big-HP-bar entities in this fight, in
    /// the same deterministic order as `entities`. A campaign or dungeon boss
    /// fight has exactly one; every other production mode has none, which is
    /// the card's negative contract.
    pub bosses: Vec<EntityMetrics>,
}

#[cfg(test)]
mod tests {
    use super::*;

    use essences::abilities::{Ability, ActiveAbility};
    use essences::combat_origin::CombatEventOrigin;
    use essences::entity::{ActionWithDeadline, Coordinates, EntityAction};
    use essences::fight_breakdown::CombatSource;
    use uuid::Uuid;

    fn ability(id: Uuid) -> ActiveAbility {
        ActiveAbility {
            ability: Ability {
                template_id: id,
                level: 1,
                shards_amount: 0,
            },
            deadline: None,
            slot_id: None,
        }
    }

    fn entity(id: Uuid, team: EntityTeam, x: i64, ability_id: Uuid) -> Entity {
        Entity {
            id,
            hp: 100,
            max_hp: 100,
            team,
            coordinates: Coordinates { x, y: 0 },
            abilities: vec![ability(ability_id)],
            ..Default::default()
        }
    }

    /// Enemy-targeting ability `id` with the given melee range.
    fn lookups(id: Uuid, range: i64) -> ContentLookups {
        let mut l = ContentLookups::default();
        l.ability_target_type.insert(id, "Enemy".to_string());
        l.ability_range.insert(id, range);
        l
    }

    fn state_with(fight: ActiveFight) -> OverlordState {
        OverlordState {
            active_fight: Some(fight),
            ..Default::default()
        }
    }

    fn push_cast(e: &mut Entity, ability_id: Uuid, target: Uuid) {
        e.actions_queue.push(&ActionWithDeadline {
            action: EntityAction::CastAbility {
                ability_id,
                target_entity_id: target,
            },
            deadline_tick: 0,
            origin: CombatEventOrigin::Core,
        });
    }

    /// Idle-in-contact: an empty body with a valid target in range counts as
    /// idle; a busy body does not; and body-busy is tracked independently.
    #[test]
    fn idle_and_body_busy_sampling() {
        let (hero_id, enemy_id) = (Uuid::new_v4(), Uuid::new_v4());
        let ab = Uuid::new_v4();
        let hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let enemy = entity(enemy_id, EntityTeam::Enemy, 1, ab); // distance 1 <= range 1
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![hero, enemy],
            ..Default::default()
        };
        let lookups = lookups(ab, 1);

        let mut m = FightMetrics::default();

        // Tick 1: hero body empty, enemy in range -> hero idle-in-contact.
        m.sample(&state_with(fight.clone()), &lookups, 0);

        // Tick 2: hero mid-cast -> body busy, not idle.
        let mut fight2 = fight.clone();
        push_cast(&mut fight2.entities[0], ab, enemy_id);
        m.sample(&state_with(fight2), &lookups, 0);

        let s = m.summary(Some(hero_id));
        let hero = s.hero.expect("hero present");
        assert_eq!(hero.sampled_ticks, 2);
        assert_eq!(
            hero.idle_in_contact_ticks, 1,
            "only tick 1 was idle-in-contact"
        );
        assert_eq!(hero.body_busy_ticks, 1, "only tick 2 had a queued cast");
        assert_eq!(hero.idle_share_pct, 50.0);
        assert_eq!(hero.body_busy_share_pct, 50.0);
        assert_eq!(s.total_sampled_ticks, 2);
    }

    /// No valid target in range -> not idle-in-contact (legitimate waiting).
    #[test]
    fn out_of_range_is_not_idle_in_contact() {
        let (hero_id, enemy_id) = (Uuid::new_v4(), Uuid::new_v4());
        let ab = Uuid::new_v4();
        let hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let enemy = entity(enemy_id, EntityTeam::Enemy, 5, ab); // distance 5 > range 1
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![hero, enemy],
            ..Default::default()
        };
        m_sample_once_and_assert_not_idle(fight, hero_id, ab);
    }

    fn m_sample_once_and_assert_not_idle(fight: ActiveFight, hero_id: Uuid, ab: Uuid) {
        let mut m = FightMetrics::default();
        m.sample(&state_with(fight), &lookups(ab, 1), 0);
        let hero = m.summary(Some(hero_id)).hero.expect("hero");
        assert_eq!(hero.sampled_ticks, 1);
        assert_eq!(hero.idle_in_contact_ticks, 0);
    }

    /// A `CastAbility` at a missing/dead target is a whiff; a live target is not.
    #[test]
    fn whiff_counting() {
        let (hero_id, enemy_id) = (Uuid::new_v4(), Uuid::new_v4());
        let ab = Uuid::new_v4();
        let hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let enemy = entity(enemy_id, EntityTeam::Enemy, 1, ab);
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![hero, enemy],
            ..Default::default()
        };
        let state = state_with(fight);
        let mut m = FightMetrics::default();

        // Live target -> no whiff.
        m.observe_event(
            &OverlordEvent::CastAbility {
                by_entity_id: hero_id,
                to_entity_id: enemy_id,
                ability_id: ab,
                origin: CombatEventOrigin::Core,
            },
            &state,
        );
        // Absent target -> whiff.
        m.observe_event(
            &OverlordEvent::CastAbility {
                by_entity_id: hero_id,
                to_entity_id: Uuid::new_v4(),
                ability_id: ab,
                origin: CombatEventOrigin::Core,
            },
            &state,
        );

        let s = m.summary(Some(hero_id));
        assert_eq!(s.total_whiffs, 1);
        assert_eq!(s.hero.unwrap().whiffs, 1);
    }

    /// `Damage` on a mid-cast body counts as a hit-while-casting; on an idle
    /// body it does not.
    #[test]
    fn hit_while_casting_counting() {
        let (hero_id, enemy_id) = (Uuid::new_v4(), Uuid::new_v4());
        let ab = Uuid::new_v4();
        let mut hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let enemy = entity(enemy_id, EntityTeam::Enemy, 1, ab);

        // Idle hero takes a hit -> not counted.
        let idle_state = state_with(ActiveFight {
            player_id: hero_id,
            entities: vec![hero.clone(), enemy.clone()],
            ..Default::default()
        });
        let mut m = FightMetrics::default();
        m.observe_event(
            &OverlordEvent::Damage {
                by_entity_id: None,
                entity_id: hero_id,
                damage: 5,
                damage_data: Default::default(),
                origin: CombatEventOrigin::Core,
                source: essences::fight_breakdown::CombatSource::Other,
            },
            &idle_state,
        );
        // An idle-body hit records nothing, so no hero counter exists yet.
        assert!(m.summary(Some(hero_id)).hero.is_none());

        // Casting hero takes a hit -> counted.
        push_cast(&mut hero, ab, enemy_id);
        let casting_state = state_with(ActiveFight {
            player_id: hero_id,
            entities: vec![hero, enemy],
            ..Default::default()
        });
        m.observe_event(
            &OverlordEvent::Damage {
                by_entity_id: None,
                entity_id: hero_id,
                damage: 5,
                damage_data: Default::default(),
                origin: CombatEventOrigin::Core,
                source: essences::fight_breakdown::CombatSource::Other,
            },
            &casting_state,
        );
        assert_eq!(m.summary(Some(hero_id)).hero.unwrap().hits_while_casting, 1);
    }

    /// The dispersion window: a full 10 s window of idle-in-contact ticks trips
    /// the criterion (max window share 100% > 40%).
    #[test]
    fn dispersion_window_flags_a_cold_stretch() {
        let (hero_id, enemy_id) = (Uuid::new_v4(), Uuid::new_v4());
        let ab = Uuid::new_v4();
        let hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let enemy = entity(enemy_id, EntityTeam::Enemy, 1, ab);
        let state = state_with(ActiveFight {
            player_id: hero_id,
            entities: vec![hero, enemy],
            ..Default::default()
        });
        let lookups = lookups(ab, 1);
        let mut m = FightMetrics::default();

        // Fewer than a full window -> no window verdict yet.
        for _ in 0..(WINDOW_TICKS - 1) {
            m.sample(&state, &lookups, 0);
        }
        assert!(m.summary(Some(hero_id)).max_window_idle_share_pct.is_none());
        assert!(m.summary(Some(hero_id)).dispersion_ok);

        // Complete the window: 100 idle-in-contact ticks -> 100% share.
        m.sample(&state, &lookups, 0);
        let s = m.summary(Some(hero_id));
        assert_eq!(s.max_window_idle_share_pct, Some(100.0));
        assert!(!s.dispersion_ok, "an all-idle window must fail dispersion");
        assert!(!s.ally.dispersion_ok);
    }

    /// A2-BAL-001: `S_actual` counts only the ticks the boss was *actually*
    /// frozen. The handler stamps an absolute deadline, so a stun that death or
    /// fight end cuts short must contribute the ticks it covered and no more —
    /// the nominal 3 s duration is not what the calibration divides by.
    #[test]
    fn stun_ticks_count_real_frozen_time_not_nominal_duration() {
        let hero_id = Uuid::now_v7();
        let boss_id = Uuid::now_v7();
        let ab = Uuid::now_v7();
        let hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        let mut boss = entity(boss_id, EntityTeam::Enemy, 1, ab);
        boss.has_big_hp_bar = true;
        // Frozen until tick 250: covers samples at 0 and 100, not 300.
        boss.attributes.set(STUN_UNTIL_TICK_ATTR, 250);

        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![hero, boss],
            ..Default::default()
        };
        let state = state_with(fight);
        let lk = lookups(ab, 1);

        let mut m = FightMetrics::default();
        for tick in [0, 100, 300] {
            m.sample(&state, &lk, tick);
        }

        let s = m.summary(Some(hero_id));
        let boss_row = s
            .bosses
            .first()
            .expect("the big-HP-bar entity is a boss row");
        assert_eq!(boss_row.entity_id, boss_id);
        assert_eq!(boss_row.sampled_ticks, 3, "F counts every living tick");
        assert_eq!(boss_row.stunned_ticks, 2, "only ticks before the deadline");
        assert!((boss_row.stun_share_pct - 200.0 / 3.0).abs() < 1e-9);
    }

    /// The hero has no big HP bar, so it never appears as a boss row. This is
    /// the negative half of the card's contract: every mode without a
    /// boss-flagged template must report zero boss rows.
    #[test]
    fn a_fight_without_a_boss_flagged_entity_reports_no_boss_rows() {
        let hero_id = Uuid::now_v7();
        let enemy_id = Uuid::now_v7();
        let ab = Uuid::now_v7();
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![
                entity(hero_id, EntityTeam::Ally, 0, ab),
                entity(enemy_id, EntityTeam::Enemy, 1, ab),
            ],
            ..Default::default()
        };
        let mut m = FightMetrics::default();
        m.sample(&state_with(fight), &lookups(ab, 1), 0);
        assert!(m.summary(Some(hero_id)).bosses.is_empty());
    }

    /// `D_old` is credited to the dealer, and ownerless environment damage
    /// (`by_entity_id: None`) belongs to nobody — counting it against a
    /// combatant would inflate the boss's outgoing total.
    #[test]
    fn damage_is_credited_to_its_dealer_and_ownerless_damage_to_nobody() {
        let hero_id = Uuid::now_v7();
        let boss_id = Uuid::now_v7();
        let ab = Uuid::now_v7();
        let mut boss = entity(boss_id, EntityTeam::Enemy, 1, ab);
        boss.has_big_hp_bar = true;
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![entity(hero_id, EntityTeam::Ally, 0, ab), boss],
            ..Default::default()
        };
        let state = state_with(fight);

        let mut m = FightMetrics::default();
        let hit = |by: Option<Uuid>, damage: u64| OverlordEvent::Damage {
            by_entity_id: by,
            entity_id: hero_id,
            damage,
            damage_data: Default::default(),
            origin: CombatEventOrigin::default(),
            source: CombatSource::ArmedBonus,
        };
        m.observe_event(&hit(Some(boss_id), 30), &state);
        m.observe_event(&hit(Some(boss_id), 12), &state);
        m.observe_event(&hit(None, 999), &state);

        let by_id: HashMap<_, _> = m
            .summary(Some(hero_id))
            .entities
            .into_iter()
            .map(|e| (e.entity_id, e))
            .collect();
        assert_eq!(by_id[&boss_id].damage_dealt, 42);
        assert_eq!(by_id.get(&hero_id).map_or(0, |e| e.damage_dealt), 0);
    }

    /// A2-BAL-002 §2.5: the card mandates `min_hp_fraction` over final HP
    /// precisely because regeneration can hide the whole fight. A run that dips
    /// to 30 % and heals back to full must not read as untouched.
    #[test]
    fn min_hp_fraction_records_the_dip_not_the_recovery() {
        let hero_id = Uuid::now_v7();
        let ab = Uuid::now_v7();
        let lk = lookups(ab, 1);

        let mut m = FightMetrics::default();
        for hp in [100u64, 30, 100] {
            let mut hero = entity(hero_id, EntityTeam::Ally, 0, ab);
            hero.hp = hp;
            let fight = ActiveFight {
                player_id: hero_id,
                entities: vec![hero],
                ..Default::default()
            };
            m.sample(&state_with(fight), &lk, 0);
        }

        let hero = m.summary(Some(hero_id)).hero.expect("hero");
        assert_eq!(hero.min_hp_fraction, Some(0.3));
    }

    /// Healing past full is wasted, and the waste is what tells a sustain build
    /// apart from one that simply was not hit.
    #[test]
    fn overheal_is_the_part_of_a_heal_with_no_headroom_left() {
        let hero_id = Uuid::now_v7();
        let ab = Uuid::now_v7();
        let mut hero = entity(hero_id, EntityTeam::Ally, 0, ab);
        hero.hp = 90; // 10 headroom against max_hp 100
        let fight = ActiveFight {
            player_id: hero_id,
            entities: vec![hero],
            ..Default::default()
        };
        let state = state_with(fight);

        let mut m = FightMetrics::default();
        m.observe_event(
            &OverlordEvent::Heal {
                by_entity_id: None,
                entity_id: hero_id,
                heal: 25,
                origin: CombatEventOrigin::default(),
                source: CombatSource::ArmedBonus,
            },
            &state,
        );

        let hero = m.summary(Some(hero_id)).hero.expect("hero");
        assert_eq!(hero.healing_received, 25);
        assert_eq!(hero.overheal, 15, "25 healed into 10 headroom wastes 15");
    }
}