forge/

encounter_debug.rs

// #t(file: rust_alloc_in_loop) CLI report assembly is bounded by fixture targets and timeline events.
// #t(file: rust_clone_in_loop) report rows own resolver/dictionary labels after their sources drop.
// #t(file: rust_floating_point_eq) initial activation mirrors the canonical exact zero-time rules.

#![expect(
    clippy::cast_precision_loss,
    reason = "telemetry damage counters are converted to diagnostic display values"
)]

//! Deterministic encounter fixture inspection and telemetry debug rendering.

use std::collections::BTreeMap;

use anyhow::{Context, Result, ensure};
use tabled::Tabled;
use wowlab_common::output;
use wowlab_engine_application::{
    EnemyStatField, EnemyStatProvenanceStep, EnemyStatResolver, ProvenanceValue,
};
use wowlab_engine_ports::DynDataResolver;
use wowlab_types::{
    proto,
    sim::{EncounterDefinition, EnemyDefinition},
};

use crate::encounter_fixture::EncounterFixture;

const DAMAGE_SCALE: f64 = 10.0;

#[derive(Clone, Debug)]
pub(crate) struct EncounterDebugReport {
    pub(crate) fixture: EncounterFixture,
    pub(crate) definition: EncounterDefinition,
    pub(crate) targets: Vec<TargetDebug>,
    health_provenance: Vec<HealthProvenanceDebug>,
    timeline: Vec<EncounterTimelineDebug>,
    pub(crate) encounter_events: Vec<proto::EncounterTimelineEvent>,
}

#[derive(Clone, Debug)]
pub(crate) struct TargetDebug {
    pub(crate) id: u32,
    pub(crate) label: String,
    npc_id: Option<u32>,
    group: String,
    max_health: f64,
    initial_state: ActorState,
    final_state: ActorState,
    damage: f64,
}

#[derive(Clone, Debug)]
struct HealthProvenanceDebug {
    target_id: u32,
    source: String,
    row: String,
    operation: String,
    input: String,
    output: String,
}

#[derive(Clone, Copy, Debug)]
struct ActorState {
    active: bool,
    alive: bool,
    transform: wowlab_types::sim::SpatialTransform,
}

#[derive(Clone, Debug)]
struct EncounterTimelineDebug {
    time_ms: u32,
    sequence: u64,
    kind: String,
    source: String,
    target: String,
    pull: String,
    group: String,
    position: String,
    detail: String,
}

#[derive(Tabled)]
struct TargetRow {
    #[tabled(rename = "Target")]
    target: String,
    #[tabled(rename = "NPC ID")]
    npc_id: String,
    #[tabled(rename = "Group")]
    group: String,
    #[tabled(rename = "Resolved Health")]
    max_health: String,
    #[tabled(rename = "Start")]
    initial_state: String,
    #[tabled(rename = "End")]
    final_state: String,
    #[tabled(rename = "Position")]
    position: String,
    #[tabled(rename = "Damage")]
    damage: String,
}

#[derive(Tabled)]
struct ProvenanceRow {
    #[tabled(rename = "Target")]
    target: String,
    #[tabled(rename = "Source")]
    source: String,
    #[tabled(rename = "Row")]
    row: String,
    #[tabled(rename = "Operation")]
    operation: String,
    #[tabled(rename = "Input")]
    input: String,
    #[tabled(rename = "Output")]
    output: String,
}

#[derive(Tabled)]
struct TimelineRow {
    #[tabled(rename = "Time")]
    time: String,
    #[tabled(rename = "Event")]
    kind: String,
    #[tabled(rename = "Source")]
    source: String,
    #[tabled(rename = "Target")]
    target: String,
    #[tabled(rename = "Pull")]
    pull: String,
    #[tabled(rename = "Group")]
    group: String,
    #[tabled(rename = "Position")]
    position: String,
    #[tabled(rename = "Detail")]
    detail: String,
}

pub(crate) async fn build_report(
    fixture: EncounterFixture,
    telemetry: &proto::ChunkTelemetry,
    resolver: &DynDataResolver<'_>,
) -> Result<EncounterDebugReport> {
    let definition = fixture.definition()?;
    let dictionary = telemetry
        .dictionary
        .as_ref()
        .context("fixture telemetry omitted the target dictionary")?;
    let target_entries: BTreeMap<_, _> = dictionary
        .targets
        .iter()
        .map(|target| (target.id, target))
        .collect();
    let damage_by_target: BTreeMap<_, _> = telemetry
        .damage_profile
        .as_ref()
        .map(|profile| {
            profile
                .by_target
                .iter()
                .map(|damage| {
                    (
                        damage.target_id,
                        damage.total_damage_x10 as f64 / DAMAGE_SCALE,
                    )
                })
                .collect()
        })
        .unwrap_or_default();
    let representative = telemetry
        .representative
        .as_ref()
        .context("fixture telemetry omitted the representative timeline")?;
    let initial_states = authored_initial_states(&definition);
    let mut states = initial_states.clone();

    for event in &representative.encounter_events {
        apply_lifecycle_state(event, &mut states);
        tokio::task::yield_now().await;
    }

    let stat_resolver = EnemyStatResolver::new(resolver);
    let mut targets = Vec::with_capacity(definition.enemies.len());
    let mut health_provenance = Vec::with_capacity(definition.enemies.len());

    for enemy in &definition.enemies {
        let target_id = u32::from(enemy.id.0);
        let resolved_stats = stat_resolver
            .resolve(enemy)
            .await
            .with_context(|| format!("failed to resolve fixture target {target_id}"))?;
        let dictionary_target = target_entries
            .get(&target_id)
            .with_context(|| format!("target dictionary omitted fixture target {target_id}"))?;

        ensure!(
            dictionary_target.label == resolved_stats.identity().display_name,
            "target {target_id} dictionary label disagrees with resolved identity"
        );
        ensure!(
            dictionary_target.npc_id == resolved_stats.identity().npc_id,
            "target {target_id} dictionary NPC ID disagrees with resolved identity"
        );
        let group = definition
            .groups
            .get(enemy.group_id.as_usize())
            .filter(|group| group.id == enemy.group_id)
            .with_context(|| format!("target {target_id} references a missing group"))?;
        let initial_state = *initial_states
            .get(&target_id)
            .with_context(|| format!("target {target_id} has no initial state"))?;
        let final_state = *states
            .get(&target_id)
            .with_context(|| format!("target {target_id} has no final state"))?;

        let target_health_provenance_start = health_provenance.len();

        for step in resolved_stats
            .provenance()
            .iter()
            .filter(|step| provenance_field(step) == Some(EnemyStatField::MaxHealth))
        {
            health_provenance.push(format_provenance(target_id, step));
            tokio::task::yield_now().await;
        }

        ensure!(
            health_provenance.len() > target_health_provenance_start,
            "resolved fixture target {target_id} omitted health provenance"
        );
        targets.push(TargetDebug {
            id: target_id,
            label: resolved_stats.identity().display_name.clone(),
            npc_id: resolved_stats.identity().npc_id,
            group: format!("{}:{}", group.id.0, group.slug),
            max_health: resolved_stats.max_health(),
            initial_state,
            final_state,
            damage: damage_by_target
                .get(&target_id)
                .copied()
                .unwrap_or_default(),
        });
    }

    let timeline = build_timeline(dictionary, representative);
    let encounter_events = representative.encounter_events.clone();

    Ok(EncounterDebugReport {
        fixture,
        definition,
        targets,
        health_provenance,
        timeline,
        encounter_events,
    })
}

fn authored_initial_states(definition: &EncounterDefinition) -> BTreeMap<u32, ActorState> {
    definition
        .enemies
        .iter()
        .map(|enemy| {
            (
                u32::from(enemy.id.0),
                ActorState {
                    active: starts_active_at_encounter_start(definition, enemy),
                    alive: true,
                    transform: enemy.initial_transform,
                },
            )
        })
        .collect()
}

pub(crate) fn starts_active_at_encounter_start(
    definition: &EncounterDefinition,
    enemy: &EnemyDefinition,
) -> bool {
    if enemy.spawn_at_s != 0.0 {
        return false;
    }

    let Some(first_pull) = definition.pulls.first() else {
        return false;
    };
    let Some(group) = definition
        .groups
        .get(enemy.group_id.as_usize())
        .filter(|group| group.id == enemy.group_id)
    else {
        return false;
    };
    let Some(wave) = definition
        .waves
        .get(group.wave_id.as_usize())
        .filter(|wave| wave.id == group.wave_id)
    else {
        return false;
    };

    group.enemy_ids.contains(&enemy.id)
        && wave.group_ids.contains(&group.id)
        && first_pull.wave_ids.contains(&wave.id)
        && wave.pull_id == first_pull.id
        && wave.minimum_activation_s == 0.0
        && wave.depends_on_groups.is_empty()
}

fn provenance_field(step: &EnemyStatProvenanceStep) -> Option<EnemyStatField> {
    match step {
        EnemyStatProvenanceStep::Lookup { field, .. }
        | EnemyStatProvenanceStep::ExplicitOverride { field, .. } => Some(*field),
        _ => None,
    }
}

fn format_provenance(target_id: u32, step: &EnemyStatProvenanceStep) -> HealthProvenanceDebug {
    match step {
        EnemyStatProvenanceStep::Lookup {
            table,
            row_id,
            operation,
            input,
            output,
            ..
        } => HealthProvenanceDebug {
            target_id,
            source: (*table).to_string(),
            row: row_id.to_string(),
            operation: (*operation).to_string(),
            input: input.clone(),
            output: format_provenance_value(output),
        },
        EnemyStatProvenanceStep::ExplicitOverride { value, .. } => HealthProvenanceDebug {
            target_id,
            source: "authored input".to_string(),
            row: "-".to_string(),
            operation: "explicit override".to_string(),
            input: "-".to_string(),
            output: format_number(*value),
        },
        _ => HealthProvenanceDebug {
            target_id,
            source: "unknown".to_string(),
            row: "-".to_string(),
            operation: "unknown".to_string(),
            input: "-".to_string(),
            output: "-".to_string(),
        },
    }
}

fn format_provenance_value(value: &ProvenanceValue) -> String {
    match value {
        ProvenanceValue::Number(value) => format_number(*value),
        ProvenanceValue::Text(value) => value.clone(),
        _ => "-".to_string(),
    }
}

fn apply_lifecycle_state(
    event: &proto::EncounterTimelineEvent,
    states: &mut BTreeMap<u32, ActorState>,
) {
    if event.actor_kind != proto::ActorKind::Enemy as i32 {
        return;
    }

    let Some(state) = states.get_mut(&event.actor_id) else {
        return;
    };

    match proto::EncounterEventKind::try_from(event.kind) {
        Ok(proto::EncounterEventKind::Spawn) => {
            state.active = true;
            state.alive = true;
        }
        Ok(proto::EncounterEventKind::Death) => {
            state.active = false;
            state.alive = false;
        }
        Ok(proto::EncounterEventKind::Despawn) => state.active = false,
        Ok(
            proto::EncounterEventKind::Movement
            | proto::EncounterEventKind::TargetChange
            | proto::EncounterEventKind::PullTransition
            | proto::EncounterEventKind::Unspecified,
        )
        | Err(_) => {}
    }

    if let (Some(x), Some(y), Some(heading), Some(layer_id)) =
        (event.x, event.y, event.heading, event.layer_id)
    {
        let Ok(layer) = u16::try_from(layer_id) else {
            return;
        };

        state.transform = wowlab_types::sim::SpatialTransform {
            layer: wowlab_types::sim::SpatialLayerId(layer),
            position: wowlab_types::sim::Position2 { x, y },
            heading,
        };
    }
}

fn build_timeline(
    dictionary: &proto::DictionaryView,
    representative: &proto::TimelineSnapshot,
) -> Vec<EncounterTimelineDebug> {
    let mut rows = Vec::new();
    let mut absolute_ms = 0_u32;
    let has_causal_sequence = representative
        .markers
        .iter()
        .any(|marker| marker.sequence != 0)
        || representative
            .encounter_events
            .iter()
            .any(|event| event.sequence != 0);

    for (offset, marker) in representative.markers.iter().enumerate() {
        absolute_ms = absolute_ms.saturating_add(marker.delta_time_ms);
        let kind =
            proto::MarkerKind::try_from(marker.kind).unwrap_or(proto::MarkerKind::Unspecified);

        if !matches!(kind, proto::MarkerKind::Cast | proto::MarkerKind::Damage) {
            continue;
        }

        rows.push(EncounterTimelineDebug {
            time_ms: absolute_ms,
            sequence: if has_causal_sequence {
                marker.sequence
            } else {
                u64::try_from(offset).expect("timeline marker count fits u64")
            },
            kind: marker_kind_label(kind).to_string(),
            source: actor_label(dictionary, marker.source_kind, marker.source_id),
            target: target_label(dictionary, marker.target_id),
            pull: marker
                .pull_id
                .map_or_else(|| "-".to_string(), |id| id.to_string()),
            group: marker
                .group_id
                .map_or_else(|| "-".to_string(), |id| id.to_string()),
            position: "-".to_string(),
            detail: if kind == proto::MarkerKind::Damage {
                format!(
                    "spell={} amount={}{}",
                    marker.spell_or_aura_id,
                    marker.amount,
                    if marker.is_crit { " crit" } else { "" }
                )
            } else {
                format!("spell={}", marker.spell_or_aura_id)
            },
        });
    }

    let marker_count =
        u64::try_from(representative.markers.len()).expect("timeline marker count fits u64");

    for (offset, event) in representative.encounter_events.iter().enumerate() {
        let kind = proto::EncounterEventKind::try_from(event.kind)
            .unwrap_or(proto::EncounterEventKind::Unspecified);

        rows.push(EncounterTimelineDebug {
            time_ms: event.time_ms,
            sequence: if has_causal_sequence {
                event.sequence
            } else {
                marker_count + u64::try_from(offset).expect("encounter event count fits u64")
            },
            kind: encounter_kind_label(kind).to_string(),
            source: actor_label(dictionary, event.actor_kind, event.actor_id),
            target: event.target_id.map_or_else(
                || "-".to_string(),
                |target| target_label(dictionary, target),
            ),
            pull: event.pull_id.to_string(),
            group: event
                .group_id
                .map_or_else(|| "-".to_string(), |id| id.to_string()),
            position: event_position(event),
            detail: event.previous_target_id.map_or_else(
                || "-".to_string(),
                |target| format!("previous={}", target_label(dictionary, target)),
            ),
        });
    }

    rows.sort_by_key(|row| (row.time_ms, row.sequence));

    rows
}

const fn marker_kind_label(kind: proto::MarkerKind) -> &'static str {
    match kind {
        proto::MarkerKind::Cast => "cast",
        proto::MarkerKind::Damage => "damage",
        proto::MarkerKind::Resource => "resource",
        proto::MarkerKind::Proc => "proc",
        proto::MarkerKind::Unspecified => "unspecified",
    }
}

const fn encounter_kind_label(kind: proto::EncounterEventKind) -> &'static str {
    match kind {
        proto::EncounterEventKind::Spawn => "spawn",
        proto::EncounterEventKind::Movement => "movement",
        proto::EncounterEventKind::Death => "death",
        proto::EncounterEventKind::Despawn => "despawn",
        proto::EncounterEventKind::TargetChange => "target_change",
        proto::EncounterEventKind::PullTransition => "pull_transition",
        proto::EncounterEventKind::Unspecified => "unspecified",
    }
}

fn actor_label(dictionary: &proto::DictionaryView, kind: i32, id: u32) -> String {
    let unit = dictionary
        .units
        .iter()
        .find(|unit| unit.kind == kind && unit.id == id);

    unit.map_or_else(
        || match proto::ActorKind::try_from(kind) {
            Ok(proto::ActorKind::Player) => "Player".to_string(),
            Ok(proto::ActorKind::Pet) => format!("pet {id}"),
            Ok(proto::ActorKind::Enemy) => target_label(dictionary, id),
            Ok(proto::ActorKind::Unspecified) | Err(_) => format!("unknown {id}"),
        },
        |unit| match proto::ActorKind::try_from(kind) {
            Ok(proto::ActorKind::Player) => unit.label.clone(),
            Ok(proto::ActorKind::Pet) => format!("pet {id}:{}", unit.label),
            Ok(proto::ActorKind::Enemy) => format!("target {id}:{}", unit.label),
            Ok(proto::ActorKind::Unspecified) | Err(_) => {
                format!("unknown {id}:{}", unit.label)
            }
        },
    )
}

fn target_label(dictionary: &proto::DictionaryView, id: u32) -> String {
    let target = dictionary.targets.iter().find(|target| target.id == id);

    target.map_or_else(
        || format!("target {id}"),
        |target| format!("{id}:{}", target.label),
    )
}

fn event_position(event: &proto::EncounterTimelineEvent) -> String {
    match (event.layer_id, event.x, event.y, event.heading) {
        (Some(layer), Some(x), Some(y), Some(heading)) => {
            format!("L{layer} ({x:.3}, {y:.3}) h={heading:.3}")
        }
        _ => "-".to_string(),
    }
}

fn format_transform(transform: wowlab_types::sim::SpatialTransform) -> String {
    format!(
        "L{} ({:.3}, {:.3}) h={:.3}",
        transform.layer.0, transform.position.x, transform.position.y, transform.heading
    )
}

const fn state_label(state: ActorState) -> &'static str {
    match (state.active, state.alive) {
        (true, true) => "active/alive",
        (false, true) => "inactive/alive",
        (false, false) => "inactive/dead",
        (true, false) => "active/dead",
    }
}

fn format_number(value: f64) -> String {
    if value.fract().abs() <= f64::EPSILON {
        format!("{value:.0}")
    } else {
        format!("{value:.6}")
    }
}

pub(crate) fn print_report(report: &EncounterDebugReport) {
    output::blank();
    output::header(&format!("Encounter Fixture: {}", report.fixture.slug()));
    output::subheader("Resolved Targets and Runtime State");
    output::table(report.targets.iter().map(|target| {
        TargetRow {
            target: format!("{}:{}", target.id, target.label),
            npc_id: target
                .npc_id
                .map_or_else(|| "-".to_string(), |id| id.to_string()),
            group: target.group.clone(),
            max_health: format_number(target.max_health),
            initial_state: state_label(target.initial_state).to_string(),
            final_state: state_label(target.final_state).to_string(),
            position: format_transform(target.final_state.transform),
            damage: format!("{:.1}", target.damage),
        }
    }));

    output::blank();
    output::subheader("Resolved Health Provenance");
    output::table(report.health_provenance.iter().map(|step| ProvenanceRow {
        target: target_name(report, step.target_id),
        source: step.source.clone(),
        row: step.row.clone(),
        operation: step.operation.clone(),
        input: step.input.clone(),
        output: step.output.clone(),
    }));

    output::blank();
    output::subheader("Spatial / Target Timeline");
    output::table(timeline_rows(&report.timeline));
}

fn timeline_rows(timeline: &[EncounterTimelineDebug]) -> Vec<TimelineRow> {
    timeline
        .iter()
        .map(|event| TimelineRow {
            time: format!("{:.3}", f64::from(event.time_ms) / 1000.0),
            kind: event.kind.clone(),
            source: event.source.clone(),
            target: event.target.clone(),
            pull: event.pull.clone(),
            group: event.group.clone(),
            position: event.position.clone(),
            detail: event.detail.clone(),
        })
        .collect()
}

fn target_name(report: &EncounterDebugReport, id: u32) -> String {
    let target = report.targets.iter().find(|target| target.id == id);

    target.map_or_else(
        || id.to_string(),
        |target| format!("{}:{}", id, target.label),
    )
}

#[cfg(test)]
mod tests;

#[cfg(test)]
mod timeline_tests;