overlord_event_system/mechanics/

fight.rs

//! Native Rust fight logic.
//!
//! These are the pure-Rust fight primitives (`attack`, `try_cast`,
//! `spawn_wave`, ...) used by the native combat ports in
//! [`crate::behaviors`]. Results are emitted through the [`FightSink`]
//! abstraction and effect reactions through the [`EffectCb`] abstraction; the
//! shipped reactions live in [`crate::mechanics::effect_cb::OverlordEffectCb`].
//!

use std::sync::Arc;

use configs::game_config::GameConfig;
use essences::abilities::Ability;
use essences::combat_origin::CombatEventOrigin;
use essences::entity::{Coordinates, Entity, EntityAttributes, EntityId};
use essences::fight_breakdown::CombatSource;
use essences::fighting::{ActiveFight, EntityTeam};
use event_system::script::random::GameRng;
use uuid::Uuid;

use crate::event::CustomEventData;
use crate::event::*;
use crate::game_config_helpers::GameConfigLookup;
use crate::mechanics::balance;
use crate::mechanics::content_lookups::{ContentLookups, EffectTpl};
use crate::state::OverlordState;

pub const BATTLEFIELD_HEIGHT: i64 = 3;
const DOT_EFFECT_ID: &str = "019589cb-7adf-7466-8c46-92ac45032880";
const HOT_EFFECT_ID: &str = "01958c0a-329e-744d-a5eb-0369e3f4c024";
const REGEN_EFFECT_ID: &str = "01978d0c-5a8a-7b50-aaa8-e4cd7782f8bc";
/// Effect applied to the player below `LOW_CHAPTER_EFFECT_MAX_CHAPTER`.
const LOW_CHAPTER_EFFECT_ID: &str = "019e27f4-f16b-7881-87cf-bc55605cb80b";
/// Inclusive chapter ceiling for applying `LOW_CHAPTER_EFFECT_ID`.
/// Matches `init_fight` in fight.yaml (raised from 10 to 16 in OVT-2405).
const LOW_CHAPTER_EFFECT_MAX_CHAPTER: i64 = 16;
const DUNGEON_TALENT_ID: &str = "019d1c47-5a66-76e5-bb18-6d115e5c6942";
const BOSS_TALENT_ID: &str = "019d1c47-8cc2-7136-b95b-68e15d7efd0c";
pub const COUNTERATTACK_PROJECTILE: &str = "019aeeed-5bcc-7dcc-a74f-589031a6b8f2";

// ---------------------------------------------------------------------------
// Output sink — abstracts how a fight method emits its results.
// ---------------------------------------------------------------------------

// Wave-entrance geometry and paces (offset cells, rush/walk ms-per-cell) live in
// `fight_settings.wave_entrance_*` since the grid-migration фаза 1 — the former
// WAVE_ENTRANCE_* constants, now tunable per deploy. Spawn placement and the
// entrance run scheduling in `handle_spawn_entity` must read the SAME config
// field, or spawn and entrance stop mirroring each other.

// Slot model (docs/combat-grid-migration-plan.md §2.1): the sliding window of
// enemy columns hangs off the player's CURRENT column P — melee enemies fight
// from P+1 (in the hero's range-1 contact), pure-ranged from P+2 (their range 2
// reaches the hero, his melee doesn't reach them until the promotion step).
// The offsets are the load-bearing halves of the |Δx| range math and must not
// drift apart from it; the WORLD spacing between the columns is the Unity
// ScriptableObject's business (фаза 3), not the server's.
pub const MELEE_COL_OFFSET: i64 = 1;
pub const RANGED_COL_OFFSET: i64 = 2;

/// Damage-payload key marking a hit as a DERIVED copy of a cast (support-stone
/// Split / Chain / Pierce / Repeat / Pulse) rather than an original Core hit.
/// Anything that reacts to combat events (laws, resonance, mastery, triggers)
/// must skip a payload carrying this key.
pub const DERIVED_DAMAGE_KEY: &str = "derived";

/// Entity attributes behind the two defensive supports. `guard_charges` counts
/// pending Fortify charges, `guard_reduction` is the reduction of the next hit
/// in ×10000 units (3000 = −30%). Shelter needs no attribute of its own: it is a
/// plain timed `received_damage.mod`.
pub const GUARD_CHARGES_ATTR: &str = "guard_charges";
pub const GUARD_REDUCTION_ATTR: &str = "guard_reduction";
/// Parts-per-million multiplier preserving A2-BAL-001's measured, previously
/// shipped boss outgoing budget after the hidden automatic stun was removed.
/// Read only by [`attack`] after the full hit payload is composed.
pub const BOSS_OUTGOING_EQUIVALENCE_PPM_ATTR: &str = "boss_outgoing_equivalence_ppm";
/// Between-wave formation dash distance in logical cells. Advancing fights
/// assign waves 2+ against the player's landing column (current + this).
pub const FORMATION_ADVANCE_CELLS: i64 = 4;
const DEFAULT_BETWEEN_WAVE_SPAWN_DELAY_TICKS: u64 = 500;

/// Per-fight behavior selected for a normal wave transition. Dungeon overrides
/// are independent: omitting either field preserves that standard behavior.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct BetweenWaveBehavior {
    pub spawn_delay_ticks: u64,
    pub advance_formation: bool,
}

/// Resolves per-dungeon wave behavior without adding state to
/// [`ActiveFight`]. Campaign fights and dungeons without overrides keep the
/// shipped 500 ms spawn pause and formation advance.
pub fn between_wave_behavior(config: &GameConfig, fight: &ActiveFight) -> BetweenWaveBehavior {
    let dungeon_template = fight
        .dungeon
        .as_ref()
        .and_then(|dungeon| config.dungeon_template(dungeon.id));

    BetweenWaveBehavior {
        spawn_delay_ticks: dungeon_template
            .and_then(|dungeon| dungeon.between_wave_spawn_delay_ticks)
            .unwrap_or(DEFAULT_BETWEEN_WAVE_SPAWN_DELAY_TICKS),
        advance_formation: dungeon_template
            .and_then(|dungeon| dungeon.advance_formation_between_waves)
            .unwrap_or(true),
    }
}

/// Entrance floor shared by the live slot scheduler and the balance mini-sim.
/// Stationary dungeons have no artificial formation wait.
pub fn later_wave_entrance_floor_ticks(config: &GameConfig, fight: &ActiveFight) -> u64 {
    if between_wave_behavior(config, fight).advance_formation {
        config.fight_settings.formation_advance_ticks
    } else {
        0
    }
}

/// Base run pace, ms per cell, before the ally speed multiplier.
const DEFAULT_TIME_PER_CELL: f64 = 500.0;

/// Duration of an ally formation run over `cells` logical cells (the promotion
/// step, the between-wave dash fallback) at the standard ally pace.
pub fn formation_step_duration_ticks(lookups: &ContentLookups, cells: f64) -> u64 {
    let mult = if lookups.ally_run_speed_mult > 0.0 {
        lookups.ally_run_speed_mult
    } else {
        1.0
    };
    ((DEFAULT_TIME_PER_CELL / mult) * cells).floor() as u64
}

/// Where a fight method emits its results.
///
/// Every method takes the provenance of the work it is emitting. The fight
/// primitives always pass [`CombatEventOrigin::Core`] — they *are* genuine
/// combat — and [`OriginSink`] merges its own scope on top, so a modifier's
/// output is marked without a single primitive knowing about modifiers.
pub trait FightSink {
    fn push_event(&mut self, event: OverlordEvent) -> Result<(), anyhow::Error>;
    fn push_attack(
        &mut self,
        delay: u64,
        duration: u64,
        target: Uuid,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error>;
    fn push_run(
        &mut self,
        coords: Coordinates,
        duration: u64,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error>;

    /// Claims one of the dispatch's one-shot budgets: returns `armed` the first
    /// time `slot` is claimed and `0` on every later call for that same slot.
    ///
    /// Exists because [`attack`] only sees `&Entity` — a snapshot taken before
    /// the dispatch began — so it cannot tell its second call apart from its
    /// first. A multi-target ability calls `attack` once per target against
    /// that same snapshot, so a "next attack only" bonus read straight off the
    /// entity would boost every target.
    ///
    /// Exactly one sink is built per dispatch, so "once per sink" is "once per
    /// cast". The budgets are independent — a swing can be the first to claim
    /// the crit chance AND the first to claim the damage bonus — which is why
    /// the latch is per slot rather than one for the sink.
    fn claim_once(&mut self, slot: OnceSlot, armed: i64) -> i64;
}

/// The independent one-shot budgets a single dispatch can claim.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum OnceSlot {
    /// Effect Stone `NextAttackCritChance` (`EF-C06`).
    CritChance,
    /// Effect Stone `NextAttackDamageBonus` (`EF-C05`, `EF-R06`, `EF-E07`).
    DamageBonus,
    /// The law arm for the family of the cast being resolved (`RL-02`, `FL-02`).
    LawArm,
    /// The law arm for the strike being resolved right now (`RL-01`).
    ///
    /// Separate from [`OnceSlot::LawArm`] because a "this attack" law and a
    /// "next attack" law can be armed at the same time, and one shared latch
    /// would silently swallow the second.
    LawThisArm,
}

impl OnceSlot {
    const COUNT: usize = 4;

    fn index(self) -> usize {
        match self {
            Self::CritChance => 0,
            Self::DamageBonus => 1,
            Self::LawArm => 2,
            Self::LawThisArm => 3,
        }
    }
}

/// Sink that collects fight results as typed values for native callers. Mirrors
/// `start_behavior`s fill `casts`.
#[derive(Default)]
pub struct NativeSink {
    pub events: Vec<OverlordEvent>,
    pub casts: Vec<crate::behaviors::combat::start_cast::StartCastAbilityScriptResult>,
    /// Which of this dispatch's one-shot budgets have already been taken — see
    /// [`FightSink::claim_once`].
    once_claimed: [bool; OnceSlot::COUNT],
}

impl FightSink for NativeSink {
    fn push_event(&mut self, event: OverlordEvent) -> Result<(), anyhow::Error> {
        self.events.push(event);
        Ok(())
    }

    fn push_attack(
        &mut self,
        delay: u64,
        duration: u64,
        target: Uuid,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error> {
        self.casts.push(
            crate::behaviors::combat::start_cast::StartCastAbilityScriptResult {
                delay_ticks: Some(delay),
                animation_duration_ticks: Some(duration),
                target_entity_id: Some(target),
                origin,
                ..Default::default()
            },
        );
        Ok(())
    }

    fn push_run(
        &mut self,
        coords: Coordinates,
        duration: u64,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error> {
        self.casts.push(
            crate::behaviors::combat::start_cast::StartCastAbilityScriptResult {
                coordinates: Some(coords),
                run_duration_ticks: Some(duration),
                origin,
                ..Default::default()
            },
        );
        Ok(())
    }

    fn claim_once(&mut self, slot: OnceSlot, armed: i64) -> i64 {
        let claimed = &mut self.once_claimed[slot.index()];
        if *claimed {
            return 0;
        }
        *claimed = true;
        armed
    }
}

/// Generic event push: converts any `EventStruct<OverlordEvent>` to the enum and
/// emits it through the sink.
fn push_event<ES>(sink: &mut dyn FightSink, event: ES) -> Result<(), anyhow::Error>
where
    ES: event_system::event::EventStruct<OverlordEvent> + 'static,
{
    sink.push_event(event.to_enum())
}

/// Sink decorator that stamps the provenance of everything a producer emits,
/// and refuses whatever it cannot stamp.
///
/// The fight primitives below always build `CombatEventOrigin::Core` and know
/// nothing about modifiers. A modifier runs its work against
/// `OriginSink::proc(real_sink)` instead, so everything it emits — directly or
/// through a nested primitive — comes out `Proc` without any call site
/// threading the marker.
///
/// Casts and runs are carried, not refused: `push_attack` / `push_run` write the
/// scope's provenance into the queued cast, which reaches
/// [`essences::entity::ActionWithDeadline`], so the damage it lands ticks later
/// still resolves under this scope's mark.
///
/// The sink fails closed for events it cannot mark: a non-Core scope may only
/// emit events [`OverlordEvent::set_origin`] accepts. `CastEffectFromEvent` has
/// no field of its own to stamp and `SpawnEntity` would hand a producer a
/// combatant fighting with its own Core actions, so both are refused. A Core
/// scope is unrestricted — Core is what every emit site already builds.
pub struct OriginSink<'a> {
    inner: &'a mut dyn FightSink,
    origin: CombatEventOrigin,
}

impl<'a> OriginSink<'a> {
    /// Wraps `inner` so that every event it receives is stamped with `origin`.
    pub fn new(inner: &'a mut dyn FightSink, origin: CombatEventOrigin) -> Self {
        Self { inner, origin }
    }

    /// The modifier scope: everything emitted through this sink is `Proc`.
    pub fn proc(inner: &'a mut dyn FightSink) -> Self {
        Self::new(inner, CombatEventOrigin::Proc)
    }

    /// Whether this scope is allowed to emit things it cannot mark.
    fn unrestricted(&self) -> bool {
        self.origin.is_core()
    }
}

impl FightSink for OriginSink<'_> {
    fn push_event(&mut self, mut event: OverlordEvent) -> Result<(), anyhow::Error> {
        // Marking only ever upgrades: a Core scope leaves the event alone, so an
        // already-Proc event cannot be reset by being emitted through one. The
        // stamp is what the refusal below is keyed on, hence the explicit
        // Core short-circuit rather than an unconditional `set_origin`.
        if self.unrestricted() {
            return self.inner.push_event(event);
        }
        if !event.set_origin(self.origin) {
            anyhow::bail!(
                "a {} producer may not emit {event}: it carries no provenance of its own, \
                 so its combat output would surface as Core",
                self.origin
            );
        }
        self.inner.push_event(event)
    }

    fn push_attack(
        &mut self,
        delay: u64,
        duration: u64,
        target: Uuid,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error> {
        self.inner
            .push_attack(delay, duration, target, origin.merge(self.origin))
    }

    fn push_run(
        &mut self,
        coords: Coordinates,
        duration: u64,
        origin: CombatEventOrigin,
    ) -> Result<(), anyhow::Error> {
        self.inner
            .push_run(coords, duration, origin.merge(self.origin))
    }

    /// Forwarded, not re-latched: the budget belongs to the dispatch, and a
    /// producer scope running inside one is part of that same dispatch.
    fn claim_once(&mut self, slot: OnceSlot, armed: i64) -> i64 {
        self.inner.claim_once(slot, armed)
    }
}

// ---------------------------------------------------------------------------
// Effect callbacks.
//
// Effect reactions (`on_apply` / `on_change`) are abstracted behind this trait
// so the native fns call `effects.on_apply(...)` without knowing the concrete
// dispatcher. The shipped reactions are native, keyed by effect `code`, in
// [`crate::mechanics::effect_cb::OverlordEffectCb`]. Callers that don't
// want reactions pass [`NoopEffectCb`].
// ---------------------------------------------------------------------------

/// Invokes an effect's `on_apply` / `on_change` reaction.
pub trait EffectCb {
    /// Called after an effect's duration is (re)applied, when the effect has an
    /// `on_apply` reaction.
    fn on_apply(
        &mut self,
        sink: &mut dyn FightSink,
        effect: &EffectTpl,
        target: &Entity,
    ) -> Result<(), anyhow::Error>;

    /// Called when an effect's stack count changes, when the effect has an
    /// `on_change` reaction.
    fn on_change(
        &mut self,
        sink: &mut dyn FightSink,
        effect: &EffectTpl,
        target: &Entity,
        new_stacks: i64,
        old_stacks: i64,
    ) -> Result<(), anyhow::Error>;
}

/// Effect callback that does nothing — for callers that don't want effect
/// reactions dispatched.
pub struct NoopEffectCb;

impl EffectCb for NoopEffectCb {
    fn on_apply(
        &mut self,
        _sink: &mut dyn FightSink,
        _effect: &EffectTpl,
        _target: &Entity,
    ) -> Result<(), anyhow::Error> {
        Ok(())
    }

    fn on_change(
        &mut self,
        _sink: &mut dyn FightSink,
        _effect: &EffectTpl,
        _target: &Entity,
        _new_stacks: i64,
        _old_stacks: i64,
    ) -> Result<(), anyhow::Error> {
        Ok(())
    }
}

// ---------------------------------------------------------------------------
// Attribute helpers
// ---------------------------------------------------------------------------

fn attr_get(entity: &Entity, attr_code: &str) -> f64 {
    entity.attributes.0.get(attr_code).copied().unwrap_or(0) as f64
}

fn attr_present(entity: &Entity, attr_code: &str) -> bool {
    entity.attributes.0.contains_key(attr_code)
}

/// Push an `EntityIncrAttribute` event. Rounds f64 deltas to the nearest int.
fn incr_attr(
    sink: &mut dyn FightSink,
    entity_id: Uuid,
    attr: &str,
    delta: i64,
) -> Result<(), anyhow::Error> {
    push_event(
        sink,
        OverlordEventEntityIncrAttribute {
            entity_id,
            attribute: attr.to_string(),
            delta,
        },
    )
}

/// `ctx.get_entity_stat(entity, "armor")` — applies attribute base value (from
/// content_raw), additive `bonus`, and multiplicative `mod` (`+10000 == +1.0`).
pub fn get_entity_stat(lookups: &ContentLookups, entity: &Entity, stat_code: &str) -> f64 {
    let mut stat = attr_get(entity, stat_code);
    if let Some(attr_id) = lookups.attribute_by_code.get(stat_code)
        && let Some(base) = lookups.attribute_base_value.get(attr_id)
    {
        stat += base;
    }
    let bonus = attr_get(entity, &format!("{stat_code}.bonus"));
    // Balance v2: floor the `.mod` multiplier so a stacking debuff (weakness on
    // attack, protection on received_damage, …) can't drive a stat to ≤0
    // (zero-damage / unkillable). Only bites at mod ≤ −9500; buffs unaffected.
    let mod_v = (attr_get(entity, &format!("{stat_code}.mod")) / 10000.0 + 1.0)
        .max(balance::MIN_STAT_MOD_MULT);
    (stat + bonus) * mod_v
}

/// True iff `stat_code` resolves to a promoted base value in
/// `attribute_base_value`. Lets combat tell a genuine "base missing" content
/// regression (the whole `attribute_base_value` lookup empty — see
/// `content_raw_extract`) apart from a stat that merely composed low via mods.
fn has_attribute_base(lookups: &ContentLookups, stat_code: &str) -> bool {
    lookups
        .attribute_by_code
        .get(stat_code)
        .is_some_and(|id| lookups.attribute_base_value.contains_key(id))
}

pub fn stat_throw(
    random: &GameRng,
    lookups: &ContentLookups,
    entity: &Entity,
    stat_code: &str,
    bonus: f64,
) -> bool {
    stat_throw_scaled(random, lookups, entity, stat_code, bonus, 1.0)
}

/// Entropy-based proc check (PoE-style).
/// Instead of an independent roll per check, each (entity, stat) keeps an
/// accumulator seeded 0..9999 from the fight RNG on first use; every check
/// adds the chance (permyriad) and the proc fires exactly when the
/// accumulator crosses 10000. The expected proc RATE is identical to
/// independent rolls; streaks — lucky and unlucky — are eliminated, which is
/// the variance compensation that makes proc stats (crit/dodge/multicast/
/// block/counter) safe to value at full expected-value price in the honest
/// scalar (research: PoE entropy, verified 3-0).
pub fn entropy_throw(
    random: &GameRng,
    lookups: &ContentLookups,
    entity: &Entity,
    stat_code: &str,
    bonus: f64,
    scale: f64,
) -> bool {
    let stat_value = (get_entity_stat(lookups, entity, stat_code) + bonus) * scale;
    if stat_value <= 0.0 {
        return false;
    }
    let add = stat_value.min(10000.0) as i64;
    if add >= 10000 {
        return true;
    }
    entity
        .proc_entropy
        .bump(stat_code, add, || (random.random_f64() * 10000.0) as i64)
}

/// Entropy variant for a probability that is already a fraction (0..1) rather
/// than a permyriad stat — the dodge DR curve's output.
pub fn entropy_throw_p(random: &GameRng, entity: &Entity, key: &str, p: f64) -> bool {
    if p <= 0.0 {
        return false;
    }
    if p >= 1.0 {
        return true;
    }
    entity.proc_entropy.bump(key, (p * 10000.0) as i64, || {
        (random.random_f64() * 10000.0) as i64
    })
}

/// [`stat_throw`] with the success probability multiplied by `scale` —
/// the sigmoid-steepening experiments dial down binary per-hit RNG (crit)
/// without touching entity stats. `scale = 1.0` is byte-identical to the
/// unscaled throw (same single RNG draw for any positive stat).
pub fn stat_throw_scaled(
    random: &GameRng,
    lookups: &ContentLookups,
    entity: &Entity,
    stat_code: &str,
    bonus: f64,
    scale: f64,
) -> bool {
    let stat_value = get_entity_stat(lookups, entity, stat_code) + bonus;
    if stat_value > 0.0 {
        let success = stat_value / 10000.0 * scale;
        return random.random_f64() < success;
    }
    false
}

// ---------------------------------------------------------------------------
// Entity geometry / target selection
// ---------------------------------------------------------------------------

/// True when a mover of `width` can place its front on `c` without overlapping
/// any other entity's current cell or reserved `move_target`. The body extends
/// behind the front (left for +x movers, right for -x). `mover_id` is skipped.
fn entity_get_tpl_cast_time(config: &GameConfig, entity: &Entity) -> i64 {
    if let Some(tpl_id) = entity.entity_template_id
        && let Some(tpl) = config.entity_template(tpl_id)
    {
        return tpl.cast_time as i64;
    }
    if let Some(class_id) = entity.class_id
        && let Some(class) = config.class(class_id)
    {
        return class.cast_time as i64;
    }
    0
}

fn get_distance_to(a: &Entity, b: &Entity) -> i64 {
    (b.coordinates.x - a.coordinates.x).abs()
}

fn get_target_with_lowest_hp(targets: &[Entity]) -> Option<&Entity> {
    targets.iter().min_by_key(|e| e.hp)
}

fn get_closest_target<'a>(caster: &Entity, targets: &'a [Entity]) -> Option<&'a Entity> {
    targets.iter().min_by_key(|t| {
        (t.coordinates.x - caster.coordinates.x).abs()
            + (t.coordinates.y - caster.coordinates.y).abs()
    })
}

fn get_target<'a>(caster: &Entity, targets: &'a [Entity]) -> Option<&'a Entity> {
    if caster.entity_template_id.is_some() {
        get_closest_target(caster, targets)
    } else {
        get_target_with_lowest_hp(targets)
    }
}

// ---------------------------------------------------------------------------
// Top-level fight methods
// ---------------------------------------------------------------------------

/// Native: `ctx.add_entity_attr(entity, attr, value)` — push an `IncrAttribute`
pub fn add_entity_attr(
    sink: &mut dyn FightSink,
    entity: &Entity,
    attr_code: &str,
    value: i64,
) -> Result<(), anyhow::Error> {
    incr_attr(sink, entity.id, attr_code, value)
}

/// Native: `ctx.add_entity_stat_mod(entity, stat, value)` — push an
/// `IncrAttribute` on `"{stat}.mod"` by `value`. Mirrors the engine's
/// `add_entity_stat_mod` (which lowers to `add_entity_attr(entity, "{stat}.mod",
/// value)`); used by the native effect-callback dispatcher to replicate the
pub fn add_entity_stat_mod(
    sink: &mut dyn FightSink,
    entity: &Entity,
    stat: &str,
    value: i64,
) -> Result<(), anyhow::Error> {
    add_entity_attr(sink, entity, &format!("{stat}.mod"), value)
}

/// Native: `ctx.set_entity_attr(entity, attr, value)` — push an `IncrAttribute`
/// that moves the attr TO `value` (delta = `round(value - current)`). Emitted
pub fn set_entity_attr(
    sink: &mut dyn FightSink,
    entity: &Entity,
    attr_code: &str,
    value: f64,
) -> Result<(), anyhow::Error> {
    let current = attr_get(entity, attr_code);
    incr_attr(sink, entity.id, attr_code, (value - current).round() as i64)
}

/// Native: returns whether `target` is touched (i.e. did NOT evade). Balance
/// v2: dodge probability follows the DR curve `ev/(ev+K_DODGE)` (asymptote
/// < 100%, no 100%-dodge cliff). Attribute-balance track: the dodge OUTCOME is
/// resolved through the entropy accumulator, not an independent roll — a 20%
/// dodge evades exactly every 5th incoming touch, never streaks (the variance
/// compensation that makes evasion safe to grant as a live stat).
pub fn touch_enemy(rng: &GameRng, lookups: &ContentLookups, target: &Entity) -> bool {
    let evasion = get_entity_stat(lookups, target, "evasion");
    if evasion <= 0.0 {
        return true;
    }
    let dodge = evasion / (evasion + balance::tuning().k_dodge);
    !entropy_throw_p(rng, target, "evasion.dodge", dodge)
}

/// Native: emit a `screen_shake` visual event.
pub fn screen_shake(sink: &mut dyn FightSink, power: i64) -> Result<(), anyhow::Error> {
    let mut data = CustomEventData::default();
    data.add("screen_shake_power", power);
    push_event(
        sink,
        OverlordEventFightVisualEvent {
            effect_type: "screen_shake".to_string(),
            effect_data: data,
        },
    )
}

/// Native: heal `entity`, capping at its missing HP. Returns the applied heal
/// (`None` if no heal was applied). `by_entity_id` and `source` are the
/// breakdown attribution — who healed, and with what.
pub fn heal_entity(
    sink: &mut dyn FightSink,
    by_entity_id: Option<EntityId>,
    entity: &Entity,
    amount: f64,
    source: CombatSource,
) -> Result<Option<i64>, anyhow::Error> {
    let max_heal = entity.max_hp as i64 - entity.hp as i64;
    let heal = max_heal.min(amount.floor() as i64);
    if heal <= 0 {
        return Ok(None);
    }
    push_event(
        sink,
        OverlordEventHeal {
            by_entity_id,
            entity_id: entity.id,
            heal: heal as u64,
            origin: CombatEventOrigin::Core,
            source,
        },
    )?;
    Ok(Some(heal))
}

/// Native: apply `raw_dmg` to `entity` (armor, shield, block roll, received
/// damage multiplier). Returns the floored post-mitigation damage value; `None`
/// only for the no-damage early-outs (`godmode` / a missing `received_damage`
/// base value — a content-extraction regression), which short-circuit before
/// the block roll. When a shield fully absorbs the
/// hit the function still returns `Some(floored_damage)` (and emits the shield
/// decrement) — this value drives `attack`'s return / lifesteal, so it
/// must not be `None` or the caller would discard the shield event.
/// Consumes one `block` `stat_throw` from `rng` when it is reached.
#[allow(clippy::too_many_arguments)]
pub fn damage_entity(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    by_entity_id: Option<EntityId>,
    entity: &Entity,
    raw_dmg: f64,
    mut custom_data: CustomEventData,
    source: CombatSource,
) -> Result<Option<i64>, anyhow::Error> {
    if attr_present(entity, "godmode") {
        return Ok(None);
    }
    let armor = get_entity_stat(lookups, entity, "armor");
    let shield = attr_get(entity, "shield");
    // `received_damage` is a ×10000 multiplier whose base value (10000 == 100%
    // taken) lives in `attribute_base_value`. If that lookup is *entirely absent*
    // the content pipeline failed to promote it (see `content_raw_extract`) —
    // keep the loud legacy behaviour (cancel all damage → fights visibly stall)
    // so a content/extraction regression still surfaces, instead of silently
    // degrading to the floor below (~1% damage, a 100×-slower near-stalemate).
    if !has_attribute_base(lookups, "received_damage") {
        return Ok(None);
    }

    // Effect Stone defensive states. All three keys are only ever written on the
    // hero, so for a mob — and for a hero with no stones — this block reads three
    // absent attributes and changes nothing.
    //
    // They live here rather than in the stone runtime because they must act
    // BEFORE the hit is applied: a post-hoc heal cannot un-kill anybody, and a
    // blocked hit has to not land at all.
    let mut raw_dmg = raw_dmg;
    {
        use crate::mechanics::stones as stone;

        // `EF-E06` Perfect Guard: the hit is blocked outright and answered.
        if stone::attr(entity, stone::GUARD_CHARGES) > 0 {
            let charges = stone::attr(entity, stone::GUARD_CHARGES);
            incr_attr(sink, entity.id, stone::GUARD_CHARGES, -1)?;
            let retaliation = stone::attr(entity, stone::GUARD_RETALIATION);
            if charges <= 1 {
                incr_attr(sink, entity.id, stone::GUARD_RETALIATION, -retaliation)?;
            }
            if let (Some(attacker), true) = (by_entity_id, retaliation > 0) {
                // `Proc`: a retaliation is the effect's output, not the hero's
                // own action, so it must not fire a trigger.
                push_event(
                    sink,
                    OverlordEventDamage {
                        by_entity_id: Some(entity.id),
                        entity_id: attacker,
                        damage: retaliation as u64,
                        damage_data: CustomEventData::default(),
                        origin: CombatEventOrigin::Proc,
                        source: CombatSource::Retaliation,
                    },
                )?;
            }
            return Ok(Some(0));
        }

        // `EF-C04` Brace Impact (charge-based) and `EF-R04` Fortress Window
        // (timed) compose multiplicatively — two independent mitigations should
        // not be able to add up past total immunity.
        let mut reduction = stone::attr(entity, stone::INCOMING_REDUCTION).clamp(0, 10_000);
        let charged = stone::attr(entity, stone::HIT_REDUCTION_CHARGES);
        if charged > 0 {
            let one_shot = stone::attr(entity, stone::HIT_REDUCTION).clamp(0, 10_000);
            incr_attr(sink, entity.id, stone::HIT_REDUCTION_CHARGES, -1)?;
            if charged <= 1 {
                incr_attr(
                    sink,
                    entity.id,
                    stone::HIT_REDUCTION,
                    -stone::attr(entity, stone::HIT_REDUCTION),
                )?;
            }
            reduction = 10_000 - ((10_000 - reduction) * (10_000 - one_shot)) / 10_000;
        }
        if reduction > 0 {
            raw_dmg *= (10_000 - reduction) as f64 / 10_000.0;
        }
    }
    // Balance v2: with the base present, floor received-damage at a small
    // positive instead of treating `≤0` as full invuln — a negative
    // `received_damage.mod` (e.g. stacked `protection`, −50%/stack) would
    // otherwise cancel ALL damage forever and make the entity unkillable.
    // `godmode` above remains the only true invuln.
    let mut received_damage_k =
        get_entity_stat(lookups, entity, "received_damage").max(balance::MIN_RECEIVED_DAMAGE_K);

    if entropy_throw(rng, lookups, entity, "block", 0.0, 1.0) {
        received_damage_k *= 0.5;
        custom_data.add("block", 1);
        // BAL-033: the Warrior passive turns a block into sustain. No ICD —
        // the block roll is the rate limit, and a blocked hit stays a hit
        // event, so hit-taken counters and triggers see it either way.
        let heal = crate::mechanics::class_passives::block_heal(entity);
        if heal > 0.0 {
            // Class-passive sustain: no producing catalog id exists at this
            // site, so it lands in the passive-regeneration bucket.
            heal_entity(
                sink,
                Some(entity.id),
                entity,
                heal,
                CombatSource::Regeneration,
            )?;
        }
    }

    // Fortify (support stone): the cast left a guard charge that softens the
    // NEXT incoming hit and is spent doing so.
    if attr_get(entity, GUARD_CHARGES_ATTR) >= 1.0 {
        let reduction = (attr_get(entity, GUARD_REDUCTION_ATTR) / 10000.0).clamp(0.0, 0.95);
        if reduction > 0.0 {
            received_damage_k *= 1.0 - reduction;
            custom_data.add("guard", 1);
        }
        incr_attr(sink, entity.id, GUARD_CHARGES_ATTR, -1)?;
    }

    let dmg_k = balance::armor_k(armor) * received_damage_k / 10000.0;
    let mut dmg = raw_dmg * dmg_k;

    // `EF-L05` Last Light: while the guard is up, a hit may take the hero to
    // 1 HP but never past it. Clamped on the post-mitigation number, so the
    // client still sees a real (if truncated) hit rather than a silent no-op.
    if crate::mechanics::stones::attr(entity, crate::mechanics::stones::DAMAGE_FLOOR) > 0 {
        let survivable = entity.hp.saturating_sub(1) as f64;
        dmg = dmg.min(survivable);
        // At exactly 1 HP there is nothing left to take. Returning here rather
        // than falling through matters: the `.max(1)` floor below exists so a
        // landed hit never renders as a phantom dodge, and it would otherwise
        // turn a fully-guarded hit into the killing blow.
        if dmg <= 0.0 {
            return Ok(Some(0));
        }
    }
    // A landed hit deals at least 1: sub-1 values (tiny early-game attacks ×
    // the wave damage skew) otherwise floor to 0, which the client renders as
    // "Dodge" — a phantom miss. True negation stays possible via godmode and
    // evasion only.
    let res = (dmg.floor() as i64).max(1);
    if shield == 0.0 {
        push_event(
            sink,
            OverlordEventDamage {
                by_entity_id,
                entity_id: entity.id,
                damage: res.max(0) as u64,
                damage_data: custom_data,
                origin: CombatEventOrigin::Core,
                source,
            },
        )?;
    } else if dmg > shield {
        incr_attr(sink, entity.id, "shield", -(shield as i64))?;
        let dmg_hp = (dmg - shield).floor() as i64;
        custom_data.add("shield_damage", shield as i64);
        push_event(
            sink,
            OverlordEventDamage {
                by_entity_id,
                entity_id: entity.id,
                damage: dmg_hp.max(0) as u64,
                damage_data: custom_data,
                origin: CombatEventOrigin::Core,
                source,
            },
        )?;
    } else {
        incr_attr(sink, entity.id, "shield", -(dmg.round() as i64))?;
    }
    Ok(Some(res))
}

/// Typed form of the `attack` params.
#[derive(Clone, Debug, Default)]
pub struct AttackParams {
    pub no_counterattack: bool,
    pub crit_chance_bonus: f64,
    /// Forced crit value; `None` => roll `crit_chance`.
    pub is_crit: Option<bool>,
    pub power: Option<f64>,
    pub dot_power: Option<f64>,
    /// This hit is a DERIVED copy produced by a support stone, not the original
    /// cast. It is tagged `derived` in the damage payload so no Core-event
    /// reader (laws, resonance, mastery, triggers) counts it, and it never
    /// shakes the screen like an original cast.
    pub derived: bool,
}

impl AttackParams {
    /// The default `attack(caster, target)` overload uses `power = 1.0`.
    pub fn default_power() -> Self {
        Self {
            power: Some(1.0),
            ..Default::default()
        }
    }
}

/// Native: perform an attack from `caster` on `target`. Returns the floored
/// damage dealt (`None` => the no-damage paths: evasion, or no `power` given).
/// RNG is consumed in the exact original order: evasion, counterattack_chance,
/// deceit (+ `randint(0,2)` if it lands), crit_chance, then `damage_entity`'s
/// block roll.
#[allow(clippy::too_many_arguments)]
pub fn attack(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    player_id: Uuid,
    caster: &Entity,
    target: &Entity,
    params: &AttackParams,
    source: CombatSource,
) -> Result<Option<i64>, anyhow::Error> {
    if !touch_enemy(rng, lookups, target) {
        push_event(
            sink,
            OverlordEventEvasion {
                entity_id: target.id,
                origin: CombatEventOrigin::Core,
            },
        )?;
        return Ok(None);
    }
    // §2 consumer 3: scale the counter proc probability by the ATTACKER's
    // (caster's) wave_share so N weak hits yield ~N×(1/N) = the original counter
    // rate. Legacy content (share 1.0) is byte-identical. The entropy accumulator
    // handles the fractional chance rhythmically; no extra RNG draw.
    if !params.no_counterattack
        && entropy_throw(
            rng,
            lookups,
            target,
            "counterattack_chance",
            0.0,
            caster.attributes.wave_share(),
        )
    {
        push_event(
            sink,
            OverlordEventCounterAttack {
                by_entity_id: target.id,
                to_entity_id: caster.id,
                duration_ticks: 200,
                origin: CombatEventOrigin::Core,
            },
        )?;
        push_event(
            sink,
            OverlordEventStartCastProjectile {
                by_entity_id: target.id,
                to_entity_id: caster.id,
                projectile_id: Uuid::parse_str(COUNTERATTACK_PROJECTILE).unwrap(),
                level: 1,
                delay: 0,
                origin: CombatEventOrigin::Core,
                source: CombatSource::Counterattack,
            },
        )?;
    }

    if entropy_throw(rng, lookups, caster, "deceit", 0.0, 1.0) {
        let pool = ["vulnerability", "weakness"];
        let idx = rng.random_index(pool.len());
        let code = pool[idx];
        change_entity_effect_duration(
            sink,
            lookups,
            effects,
            target,
            code,
            (balance::DECEIT_DEBUFF_DURATION * 1000.0).floor() as i64,
        )?;
    }

    let attack = get_entity_stat(lookups, caster, "attack");

    // Effect Stone `NextAttackCritChance` (`EF-C06`): a one-shot crit-chance
    // bonus armed by a trigger fire, spent by the FIRST swing of this dispatch
    // that actually rolls a crit. Same `claim_once` discipline as the damage
    // bonus below, and for the same reason — `caster` is a snapshot shared by
    // every target of an AoE dispatch.
    let mut crit_chance_bonus = params.crit_chance_bonus;
    if params.is_crit.is_none() {
        let armed = crate::mechanics::stones::armed_magnitude(
            caster,
            crate::mechanics::stones::NEXT_ATTACK_CRIT,
            crate::mechanics::stones::NEXT_ATTACK_CRIT_CHARGES,
        )
        .unwrap_or(0);
        let bonus = if armed > 0 {
            sink.claim_once(OnceSlot::CritChance, armed)
        } else {
            0
        };
        if bonus > 0 {
            crit_chance_bonus += bonus as f64 / 10_000.0;
            incr_attr(
                sink,
                caster.id,
                crate::mechanics::stones::NEXT_ATTACK_CRIT_CHARGES,
                -1,
            )?;
            if attr_get(caster, crate::mechanics::stones::NEXT_ATTACK_CRIT_CHARGES) <= 1.0 {
                incr_attr(
                    sink,
                    caster.id,
                    crate::mechanics::stones::NEXT_ATTACK_CRIT,
                    -bonus,
                )?;
            }
        }
    }

    let mut dmg_mod = 1.0;
    let is_crit = match params.is_crit {
        Some(v) => v,
        // Crit is the largest binary per-hit RNG (a ×2+ damage coin-flip);
        // `crit_chance_scale` (env `OVERLORD_BAL_CRIT_SCALE`) dials it for the
        // sigmoid-steepening experiments. 1.0 = shipped behavior.
        None => entropy_throw(
            rng,
            lookups,
            caster,
            "crit_chance",
            crit_chance_bonus,
            balance::tuning().crit_chance_scale,
        ),
    };
    if is_crit {
        dmg_mod = 2.0 + get_entity_stat(lookups, caster, "crit_modifier") / 10000.0;
    }

    // Effect Stone `NextAttackDamageBonus`: a bonus armed by a trigger fire and
    // spent one charge at a time by the FIRST swing of each dispatch that
    // actually deals damage — the design is "the next N attacks +X%", counted in
    // attacks, so a multi-target ability boosts one target and not the whole
    // cone. `EF-C05` arms one charge, `EF-R06` three, `EF-E07` five.
    //
    // `claim_once` is what enforces the "first" (see its doc): `caster` is a
    // snapshot shared by every target of an AoE dispatch, so the read alone
    // cannot. This is also what keeps the charge count from being driven
    // negative by one consume per target, which would have swallowed the next
    // arms.
    //
    // Consumed through the sink (an `EntityIncrAttribute` — bookkeeping, no
    // provenance, no trigger surface) rather than by mutating the caster,
    // because the fight primitives only ever see `&Entity`. Placed after the
    // evasion gate so a dodged swing never spends a charge.
    if params.power.is_some() {
        // The stone bonus: charge-gated, one charge per dispatch.
        let stone_armed = crate::mechanics::stones::armed_magnitude(
            caster,
            crate::mechanics::stones::NEXT_ATTACK_BONUS,
            crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES,
        )
        .unwrap_or(0)
        .max(0);
        let stone_bonus = if stone_armed > 0 {
            sink.claim_once(OnceSlot::DamageBonus, stone_armed)
        } else {
            0
        };
        if stone_bonus > 0 {
            incr_attr(
                sink,
                caster.id,
                crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES,
                -1,
            )?;
            // Last charge: clear the magnitude too, so a stale bonus can never
            // apply for free once the charges run out.
            if attr_get(caster, crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES) <= 1.0 {
                incr_attr(
                    sink,
                    caster.id,
                    crate::mechanics::stones::NEXT_ATTACK_BONUS,
                    -stone_bonus,
                )?;
            }
        }

        // The law arm for the family of THIS cast — `RL-02` ("next Basic
        // Attack") and `FL-02` ("next original Skill") keep their own keys and
        // the cast kind picks between them. One-shot, no charges: the first
        // swing of the dispatch that gets this far spends it whole.
        //
        // Two keys read through the cast kind, rather than one shared key the
        // families take turns borrowing: the borrow could only tell them apart
        // by the window it was open for, and a change on the stones side to
        // the shared key silently broke it once already.
        let law_arm_key = crate::logic::combat_facts::current_cast_kind(caster)
            .map(crate::mechanics::cores::law_arm_key);
        let law_armed = law_arm_key
            .map(|key| attr_get(caster, key) as i64)
            .unwrap_or(0)
            .max(0);
        let law_bonus = if law_armed > 0 {
            sink.claim_once(OnceSlot::LawArm, law_armed)
        } else {
            0
        };
        if let Some(key) = law_arm_key
            && law_bonus > 0
        {
            incr_attr(sink, caster.id, key, -law_bonus)?;
        }

        // The "this strike" arm (`RL-01`). Deliberately NOT filtered by cast
        // kind: the law boosts whatever swing triggered it, basic or skill. Its
        // own latch, so a build carrying both a "this attack" and a "next
        // attack" law spends both.
        let this_armed = attr_get(caster, crate::mechanics::cores::ARM_THIS) as i64;
        let this_bonus = if this_armed > 0 {
            sink.claim_once(OnceSlot::LawThisArm, this_armed)
        } else {
            0
        };
        if this_bonus > 0 {
            incr_attr(
                sink,
                caster.id,
                crate::mechanics::cores::ARM_THIS,
                -this_bonus,
            )?;
        }

        // Summed into one multiplier, which is what the borrow produced when it
        // moved the law value into the stone key.
        let bonus = stone_bonus + law_bonus + this_bonus;
        if bonus > 0 {
            dmg_mod *= 1.0 + bonus as f64 / 10000.0;
        }
    }

    // BAL-033 removed the hidden 3-cycle class counter: a matchup modifier the
    // player could neither see nor plan around decided PvP fights on class
    // choice alone. Class identity now lives entirely in visible stats,
    // passives and kits.

    let mut dmg_dealt = None;
    // A2-BAL-001: restore the measured pre-removal boss output after ALL
    // Attack/power/crit/law/stone composition. Stamping only real boss entities
    // makes every non-boss path byte-identical. The same multiplier is also
    // used for DoT below, so flat and over-time payload shares are not silently
    // omitted as they would be by scaling the base `attack` attribute.
    let outgoing_equivalence = match attr_get(caster, BOSS_OUTGOING_EQUIVALENCE_PPM_ATTR) {
        ppm if ppm > 0.0 => ppm / 1_000_000.0,
        _ => 1.0,
    };

    if let Some(power) = params.power {
        let dmg = attack * power * dmg_mod * outgoing_equivalence;
        let mut data = CustomEventData::default();
        if is_crit {
            data.add("crit", 1);
        }
        if params.derived {
            data.add(DERIVED_DAMAGE_KEY, 1);
        }
        dmg_dealt = damage_entity(
            sink,
            rng,
            lookups,
            Some(caster.id),
            target,
            dmg * balance::DMG_K,
            data,
            source,
        )?;
    }
    if let Some(dot_power) = params.dot_power {
        apply_entity_over_time_effect(
            sink,
            target,
            attack * dot_power * dmg_mod * outgoing_equivalence * balance::DMG_K,
            "dot",
            source,
        )?;
    }

    if caster.id == player_id && !params.derived {
        let power = params.power.unwrap_or(0.0);
        if is_crit || power > 3.5 {
            let _ = screen_shake(sink, 25);
        }
    }
    Ok(dmg_dealt)
}

/// Typed form of the `spell_heal` params.
#[derive(Clone, Debug, Default)]
pub struct SpellHealParams {
    pub is_crit: Option<bool>,
    pub power: Option<f64>,
    pub hot_power: Option<f64>,
}

impl SpellHealParams {
    pub fn default_power() -> Self {
        Self {
            power: Some(1.0),
            ..Default::default()
        }
    }
}

/// Native: heal `target` from `caster`'s attack stat. Returns the applied heal
/// (`None` when no heal). Consumes `crit_chance` from `rng` (unless `is_crit` is
/// forced), then `heal_entity`'s path (no RNG).
pub fn spell_heal(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    caster: &Entity,
    target: &Entity,
    params: &SpellHealParams,
    source: CombatSource,
) -> Result<Option<i64>, anyhow::Error> {
    let attack = get_entity_stat(lookups, caster, "attack");
    let mut heal_mod = 1.0;
    let is_crit = match params.is_crit {
        Some(v) => v,
        None => entropy_throw(
            rng,
            lookups,
            caster,
            "crit_chance",
            0.0,
            balance::tuning().crit_chance_scale,
        ),
    };
    if is_crit {
        heal_mod = 2.0 + get_entity_stat(lookups, caster, "crit_modifier") / 10000.0;
    }
    let mut heal_event = None;
    if let Some(power) = params.power {
        heal_event = heal_entity(
            sink,
            Some(caster.id),
            target,
            attack * power * heal_mod * balance::DMG_K,
            source,
        )?;
    }
    if let Some(hot_power) = params.hot_power {
        apply_entity_over_time_effect(
            sink,
            target,
            attack * hot_power * heal_mod * balance::DMG_K,
            "hot",
            source,
        )?;
    }
    Ok(heal_event)
}

/// Native: apply `effect_code` to `target` for `duration_seconds` (converted to
/// ticks). Effect `on_apply` reactions are dispatched through `effects`.
pub fn apply_entity_effect(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
    duration_seconds: f64,
) -> Result<(), anyhow::Error> {
    change_entity_effect_duration(
        sink,
        lookups,
        effects,
        target,
        effect_code,
        (duration_seconds * 1000.0).floor() as i64,
    )
}

/// Native: add `duration` ticks of `effect_code` to `target` (capped at the
/// effect's `max_duration_ticks`), emitting `EntityApplyEffect` on first
/// application and dispatching the effect's `on_apply` reaction.
pub fn change_entity_effect_duration(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
    duration: i64,
) -> Result<(), anyhow::Error> {
    let effect_tpl: Arc<EffectTpl> = match lookups.effects_by_code.get(effect_code) {
        Some(t) => t.clone(),
        None => {
            return Err(anyhow::anyhow!(
                "apply_entity_effect: unknown effect code {effect_code}"
            ));
        }
    };

    let duration_attr = format!("effect.{effect_code}.duration");
    let current_duration_ticks = attr_get(target, &duration_attr) as i64;
    let max_duration = effect_tpl.max_duration_ticks.unwrap_or(5000);
    let new_duration = (current_duration_ticks + duration).min(max_duration);
    incr_attr(
        sink,
        target.id,
        &duration_attr,
        new_duration - current_duration_ticks,
    )?;
    if current_duration_ticks == 0 {
        push_event(
            sink,
            OverlordEventEntityApplyEffect {
                entity_id: target.id,
                effect_id: effect_tpl.id,
                origin: CombatEventOrigin::Core,
            },
        )?;
    }
    effects.on_apply(sink, &effect_tpl, target)?;
    Ok(())
}

/// The ability a `CombatSource` names, if any.
fn source_ability(source: CombatSource) -> Option<Uuid> {
    match source {
        CombatSource::AbilityCast { ability_id }
        | CombatSource::AbilityDerived { ability_id }
        | CombatSource::PetUlt { ability_id } => Some(ability_id),
        _ => None,
    }
}

/// Width of one chunk of the ability id an over-time schedule records. An
/// attribute is an `i64` that other code freely adds to, and the client reads
/// it back through JSON, so a chunk must stay both far from `i64::MAX` (a
/// rewrite is applied as a delta — full-width halves overflow the add) and
/// under 2^53 (exact as a double). 43 bits satisfies both and covers a 128-bit
/// UUID in three chunks.
const OVER_TIME_SRC_BITS: u32 = 43;
const OVER_TIME_SRC_CHUNKS: u32 = 3;

/// Attributes carrying the ability that applied an over-time effect: the id's
/// [`OVER_TIME_SRC_CHUNKS`] chunks, all zero when no ability was named — the
/// tick then falls back to the generic [`CombatSource::Dot`] /
/// [`CombatSource::Hot`].
///
/// One set per kind, not per slot: the five slots accumulate every applier's
/// amounts into shared totals, so the last applier owns the whole schedule.
fn over_time_source_attr(kind: &str, chunk: u32) -> String {
    format!("effect.{kind}.src.{chunk}")
}

/// Shift and value mask of one chunk. The last chunk is narrower than the rest
/// — 128 is not a multiple of [`OVER_TIME_SRC_BITS`] — and shifting a full-width
/// value into it would overflow the `u128`.
fn over_time_source_chunk(chunk: u32) -> (u32, u128) {
    let shift = OVER_TIME_SRC_BITS * chunk;
    let width = OVER_TIME_SRC_BITS.min(128 - shift);
    (shift, (1u128 << width) - 1)
}

/// Record `source` as the owner of `target`'s `kind` schedule, clearing the
/// attribution when the applier names no ability.
fn set_over_time_source(
    sink: &mut dyn FightSink,
    target: &Entity,
    kind: &str,
    source: CombatSource,
) -> Result<(), anyhow::Error> {
    let bits = source_ability(source).map_or(0u128, |id| id.as_u128());
    for chunk in 0..OVER_TIME_SRC_CHUNKS {
        let (shift, mask) = over_time_source_chunk(chunk);
        let attr = over_time_source_attr(kind, chunk);
        let value = ((bits >> shift) & mask) as i64;
        let current = target.attributes.0.get(&attr).copied().unwrap_or(0);
        if current != value {
            incr_attr(sink, target.id, &attr, value - current)?;
        }
    }
    Ok(())
}

/// The source an over-time tick of `kind` carries: the ability recorded by the
/// last applier, or `fallback` when none was.
pub fn over_time_tick_source(entity: &Entity, kind: &str, fallback: CombatSource) -> CombatSource {
    let mut bits = 0u128;
    for chunk in 0..OVER_TIME_SRC_CHUNKS {
        let (shift, mask) = over_time_source_chunk(chunk);
        let attr = over_time_source_attr(kind, chunk);
        // Masked, not trusted: an out-of-range chunk would overflow the shift.
        let value = entity.attributes.0.get(&attr).copied().unwrap_or(0).max(0) as u128 & mask;
        bits |= value << shift;
    }
    if bits == 0 {
        return fallback;
    }
    // An over-time tick is an extra hit produced out of the cast that applied
    // it, which is what `AbilityDerived` marks — it names the ability without
    // claiming the tick was a cast of its own.
    CombatSource::AbilityDerived {
        ability_id: Uuid::from_u128(bits),
    }
}

/// Native: apply a damage-/heal-over-time effect (`kind` = `"dot"` / `"hot"`),
/// splitting `amount` over 5 ticks. No effect callbacks, no RNG.
pub fn apply_entity_over_time_effect(
    sink: &mut dyn FightSink,
    target: &Entity,
    amount: f64,
    kind: &str,
    source: CombatSource,
) -> Result<(), anyhow::Error> {
    let effect_id = if kind == "dot" {
        Uuid::parse_str(DOT_EFFECT_ID).unwrap()
    } else {
        Uuid::parse_str(HOT_EFFECT_ID).unwrap()
    };
    let per_tick = (amount / 5.0).floor() as i64;
    for i in 1..=5 {
        let tick_attr = format!("effect.{kind}.tick.{i}");
        incr_attr(sink, target.id, &tick_attr, per_tick)?;
    }
    set_over_time_source(sink, target, kind, source)?;
    let next_attr = format!("effect.{kind}.next");
    if !attr_present(target, &next_attr) {
        // set to 1 (current is 0)
        incr_attr(sink, target.id, &next_attr, 1)?;
        push_event(
            sink,
            OverlordEventEntityApplyEffect {
                entity_id: target.id,
                effect_id,
                origin: CombatEventOrigin::Core,
            },
        )?;
    }
    Ok(())
}

/// Native: remove all stacks of `effect_code` from `target`, dispatching the
/// effect's `on_change` reaction with `(new_stacks=0, old_stacks=current)`.
pub fn remove_entity_effect(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    target: &Entity,
    effect_code: &str,
) -> Result<(), anyhow::Error> {
    let effect_tpl: Arc<EffectTpl> = match lookups.effects_by_code.get(effect_code) {
        Some(t) => t.clone(),
        None => {
            return Err(anyhow::anyhow!(
                "remove_entity_effect: unknown effect code {effect_code}"
            ));
        }
    };
    let stacks_attr = format!("effect.{effect_code}.stacks");
    let current_stacks = attr_get(target, &stacks_attr) as i64;
    incr_attr(sink, target.id, &stacks_attr, -current_stacks)?;
    effects.on_change(sink, &effect_tpl, target, 0, current_stacks)?;
    Ok(())
}

/// Native: emit the per-entity init events for a fight (regen effect, low-chapter
/// effect, party power adjustment, dungeon/boss talent attack mods). No RNG, no
/// effect callbacks. `fight` supplies player/party ids + the entity roster +
/// `party_adjusted_power`; reads talent levels / chapter from `state`.
#[allow(clippy::too_many_arguments)]
pub fn init_fight(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    state: &OverlordState,
    fight_template_id: Uuid,
) -> Result<(), anyhow::Error> {
    let is_dungeon = lookups
        .fight_template_is_dungeon
        .get(&fight_template_id)
        .copied()
        .unwrap_or(false);
    let is_bossfight = lookups
        .fight_template_is_bossfight
        .get(&fight_template_id)
        .copied()
        .unwrap_or(false);

    let player_id = fight.player_id;
    let party_player_id = fight.party_player_id;
    let entities = fight.entities.clone();
    let regen_effect = Uuid::parse_str(REGEN_EFFECT_ID).unwrap();
    let low_chapter_effect = Uuid::parse_str(LOW_CHAPTER_EFFECT_ID).unwrap();
    let dungeon_talent = Uuid::parse_str(DUNGEON_TALENT_ID).unwrap();
    let boss_talent = Uuid::parse_str(BOSS_TALENT_ID).unwrap();

    for entity in &entities {
        if attr_present(entity, "regeneration_rate") {
            push_event(
                sink,
                OverlordEventEntityApplyEffect {
                    entity_id: entity.id,
                    effect_id: regen_effect,
                    origin: CombatEventOrigin::Core,
                },
            )?;
        }

        let mut dungeon_level: Option<i64> = None;
        let mut boss_level: Option<i64> = None;

        if entity.id == player_id {
            dungeon_level = state
                .character_state
                .talent_levels
                .get(&dungeon_talent)
                .copied();
            boss_level = state
                .character_state
                .talent_levels
                .get(&boss_talent)
                .copied();
            if state.character_state.character.current_chapter_level
                <= LOW_CHAPTER_EFFECT_MAX_CHAPTER
            {
                push_event(
                    sink,
                    OverlordEventEntityApplyEffect {
                        entity_id: entity.id,
                        effect_id: low_chapter_effect,
                        origin: CombatEventOrigin::Core,
                    },
                )?;
            }
        }
        if Some(entity.id) == party_player_id {
            let party = &state.party;
            if let Some(party_state) = &party.party_state {
                dungeon_level = party_state.talent_levels.get(&dungeon_talent).copied();
                boss_level = party_state.talent_levels.get(&boss_talent).copied();
                if let Some(adjusted) = party.party_adjusted_power {
                    let raw = party_state.character.power as f64;
                    if raw > 0.0 {
                        let adjust_k = adjusted as f64 / raw;
                        let stat_k = adjust_k.sqrt();
                        let current_attack = attr_get(entity, "attack");
                        let delta =
                            (current_attack * stat_k).floor() as i64 - current_attack as i64;
                        incr_attr(sink, entity.id, "attack", delta)?;
                        let new_max_hp = ((entity.hp as f64) * stat_k).floor() as u64;
                        push_event(
                            sink,
                            OverlordEventSetMaxHp {
                                entity_id: entity.id,
                                new_max_hp,
                                new_hp: new_max_hp,
                            },
                        )?;
                    }
                }
            }
        }

        // Dungeon/boss talents grant +2%/talent-level attack. The bonus is
        // additive on top of the entity's other `attack.mod` sources (class
        // levels, the Strength talent, …) — a set-to-target write here would
        // wipe them for the whole fight. Both talents stack in a fight that is
        // simultaneously a dungeon and a bossfight. `init_fight` runs once per
        // fight, so the increment cannot double-apply.
        let mut talent_attack_mod = 0;
        if is_dungeon && let Some(level) = dungeon_level {
            talent_attack_mod += 200 * level;
        }
        if is_bossfight && let Some(level) = boss_level {
            talent_attack_mod += 200 * level;
        }
        if talent_attack_mod != 0 {
            incr_attr(sink, entity.id, "attack.mod", talent_attack_mod)?;
        }
    }
    Ok(())
}

// ---------------------------------------------------------------------------
// spawn_wave & simulated_wave helpers
// ---------------------------------------------------------------------------

/// Typed form of the `fight_data` prepare-fight blob fed to `spawn_wave`.
#[derive(Clone, Debug, Default, PartialEq, serde::Serialize)]
pub struct WaveFightData {
    /// `entities[].{ entity_id, power }` — the per-template relative powers.
    pub entities: Vec<WaveEntityPower>,
    /// `waves[][].{ data: { entity_id, delay }, position }`.
    pub waves: Vec<Vec<WaveSpawn>>,
    /// `time` — the fight time budget used to normalise mob HP.
    pub time: f64,
    /// The per-fight reference power (`base_power` for `spawn_wave`).
    /// `None` mirrors a missing/unconfigured value (treated as 0.0 by callers).
    pub power: Option<f64>,
    /// Max enemies on the field at once (the death-gated exit cap, revived under
    /// the slot model — docs/growing-enemy-waves-plan.md). The first `cap` mobs
    /// of a wave exit on their timers; the rest park off-screen (`exit_gated`)
    /// and are released one per enemy kill, lowest queue position first.
    /// `None` (or cap ≥ wave size) = all exits on timers, previous behaviour
    /// bit-for-bit.
    pub stream_active_count: Option<u64>,
    /// Reward/weight budget (growing-enemy-waves plan §2): the fight's ORIGINAL
    /// total mob count. `spawn_wave` stamps `wave_share = reward_mob_budget /
    /// actual_total_mob_count` on every mob so per-kill drops / pet-ult charge /
    /// counters stay count-invariant. `None` ⇒ share 1.0 (legacy, bit-identical).
    pub reward_mob_budget: Option<u64>,
    /// Boss summon: when set, the LAST wave is a summon wave — spawned by the
    /// damage handler when a boss drops below this HP fraction, never by wave
    /// clear (see `PrepareFightWaves::summon_wave_at_hp_fraction`). Its slots
    /// anchor at the player's CURRENT column (no formation dash precedes it).
    pub summon_wave_at_hp_fraction: Option<f64>,
    /// Per-fight enemy damage multiplier: scales the fight's damage budget
    /// (`eff_hp`) only — HP, fight length and loot pacing unchanged.
    /// `None` ⇒ 1.0 (see `PrepareFightWaves::enemy_damage_mult`).
    pub enemy_damage_mult: Option<f64>,
}

#[derive(Clone, Debug, PartialEq, serde::Serialize)]
pub struct WaveEntityPower {
    /// `None` mirrors an entry with no readable `entity_id`. The original
    /// `min_power` pass ignores `entity_id` entirely (so such an entry can still
    /// lower `min_power`), while the `entity_powers` pass skips it — both
    /// behaviours are preserved by keeping this optional.
    pub entity_id: Option<String>,
    /// `None` mirrors a missing/unreadable `power`. The original `min_power`
    /// pass skips a missing power; the `entity_powers` pass defaults it to 1.0.
    pub power: Option<f64>,
}

#[derive(Clone, Debug, PartialEq, serde::Serialize)]
pub struct WaveSpawn {
    pub entity_id: String,
    /// Legacy stagger in SECONDS. Fully dead since the slot model: the exit
    /// director AND the balance mini-sim both run on `cooldown_seconds`
    /// (see `slot_arrival_delay_seconds`). Kept only to deserialize old
    /// config blobs.
    pub delay: Option<f64>,
    /// Legacy template position. The slot director only uses `y` as the row
    /// fallback for unmigrated content; `x` is dead since the slot model.
    pub position: Option<Coordinates>,
    /// Slot model: exit cooldown from wave start, seconds. `None` ⇒ 0.0 (the
    /// admin build drops zero optionals — see the config-side doc).
    pub cooldown_seconds: Option<f64>,
    /// Slot model: landing row (0..BATTLEFIELD_HEIGHT). `None` → position.y → 1.
    pub row: Option<i64>,
}

#[derive(Clone, Debug)]
struct SimEnemy {
    eff_damage: f64,
    ttk: f64,
    delay: f64,
    /// Death-gated exit queue position (`Some` = parked until a kill releases
    /// it, lowest first). Mirrors the live `exit_gated` mechanic so the budget
    /// mini-sim models the closed loop instead of guessing a kill rate.
    gated_pos: Option<i64>,
    /// Marks the fight's boss so the summon-overlap path can watch its
    /// remaining ttk (the HP proxy) for the summon trigger.
    is_boss: bool,
}

/// Death-gated exit plan for one wave under `stream_active_count` (the revived
/// streaming cap — docs/growing-enemy-waves-plan.md): the first `cap` mobs (by
/// exit cooldown, ties by config order) exit on their timers; every mob beyond
/// the cap waits parked and is released one-per-enemy-death in this order.
/// Returns, per spawn in CONFIG order, `None` for a timer exit or
/// `Some(queue_pos)` (1-based — attribute zero-drop safe) for a gated one.
/// `None` cap or `cap >= N` ⇒ all timers (previous behaviour bit-for-bit).
fn wave_exit_gate_plan(wave: &[WaveSpawn], cap: Option<u64>) -> Vec<Option<i64>> {
    let mut plan = vec![None; wave.len()];
    let Some(cap) = cap else {
        return plan;
    };
    let cap = cap.max(1) as usize;
    if wave.len() <= cap {
        return plan;
    }
    let mut order: Vec<usize> = (0..wave.len()).collect();
    order.sort_by_key(|&i| (spawn_exit_cooldown_ms(&wave[i]), i));
    for (queue_idx, &spawn_idx) in order[cap..].iter().enumerate() {
        plan[spawn_idx] = Some(queue_idx as i64 + 1);
    }
    plan
}

/// The wave spawn's authored landing row (migrated `row`, legacy `position.y`,
/// default the middle), clamped to the battlefield.
fn spawn_authored_row(spawn: &WaveSpawn) -> i64 {
    spawn
        .row
        .or(spawn.position.as_ref().map(|p| p.y))
        .unwrap_or(1)
        .clamp(0, BATTLEFIELD_HEIGHT - 1)
}

/// Balanced landing rows for a wave: the ACTIVE (non-gated) spawns are spread
/// across their column's rows in exit order so the opening group doesn't pile
/// onto one tile. Each mob keeps its authored row unless that row is already
/// busier than another (so a lone mob — a boss — never moves); ties prefer the
/// authored row, then the middle. Gated spawns keep their authored row as the
/// park row — their real row is picked at release time from live occupancy
/// (`gated_release_row`).
///
/// `live_enemy_cells` seeds the occupancy with enemies already alive — a summon
/// wave fires mid-fight, so reinforcements must spread AROUND the summoner
/// instead of landing on its tile (normal transitions fire on wave clear: no
/// survivors, the seed is a no-op). `is_summon_wave` also flips the row
/// preference to top → bottom → middle: summoned creeps flank, the middle stays
/// the summoner's stage.
fn wave_row_plan(
    wave: &[WaveSpawn],
    gate_plan: &[Option<i64>],
    config: &GameConfig,
    lookups: &ContentLookups,
    live_enemy_cells: &[(i64, i64)],
    anchor_x: i64,
    is_summon_wave: bool,
) -> Vec<i64> {
    let mut plan: Vec<i64> = wave.iter().map(spawn_authored_row).collect();
    let mut occupancy: std::collections::HashMap<i64, [i64; BATTLEFIELD_HEIGHT as usize]> =
        std::collections::HashMap::new();
    for &(x, y) in live_enemy_cells {
        let col = x - anchor_x;
        if (col == MELEE_COL_OFFSET || col == RANGED_COL_OFFSET)
            && (0..BATTLEFIELD_HEIGHT).contains(&y)
        {
            occupancy
                .entry(col)
                .or_insert([0; BATTLEFIELD_HEIGHT as usize])[y as usize] += 1;
        }
    }
    let mut order: Vec<usize> = (0..wave.len())
        .filter(|&i| gate_plan[i].is_none())
        .collect();
    order.sort_by_key(|&i| (spawn_exit_cooldown_ms(&wave[i]), i));
    for i in order {
        let col = match Uuid::parse_str(&wave[i].entity_id) {
            Ok(tpl) if template_has_melee_ability(config, lookups, tpl) => MELEE_COL_OFFSET,
            Ok(_) => RANGED_COL_OFFSET,
            Err(_) => continue,
        };
        let counts = occupancy
            .entry(col)
            .or_insert([0; BATTLEFIELD_HEIGHT as usize]);
        let cands: [i64; 4] = if is_summon_wave {
            [0, 2, plan[i], 1]
        } else {
            [plan[i], 1, 0, 2]
        };
        let mut best = cands[0];
        for cand in cands {
            if counts[cand as usize] < counts[best as usize] {
                best = cand;
            }
        }
        plan[i] = best;
        counts[best as usize] += 1;
    }
    plan
}

/// Row for a death-gated mob at RELEASE time: the least-occupied row of its
/// own column, counting living enemies standing on it, running to it, or
/// parked pending arrival at the same park column (exit-cooldown waiters and
/// same-tick earlier releases — their park `y` IS their landing row). Ties
/// prefer the mob's authored row, then the middle — so the freed space is
/// taken instead of stacking onto survivors.
pub fn gated_release_row(fight: &ActiveFight, released_id: Uuid, entrance_offset: i64) -> i64 {
    let Some(released) = fight.entities.iter().find(|e| e.id == released_id) else {
        return 1;
    };
    let park_x = released.coordinates.x;
    let target_x = park_x - entrance_offset;
    let authored_row = released.coordinates.y.clamp(0, BATTLEFIELD_HEIGHT - 1);
    let mut counts = [0i64; BATTLEFIELD_HEIGHT as usize];
    for e in &fight.entities {
        if e.id == released_id
            || e.team != EntityTeam::Enemy
            || e.hp == 0
            || e.attributes.0.contains_key("exit_gated")
        {
            continue;
        }
        let (ex, ey) = e
            .move_target
            .as_ref()
            .map(|t| (t.x, t.y))
            .unwrap_or((e.coordinates.x, e.coordinates.y));
        if (ex == target_x || ex == park_x) && (0..BATTLEFIELD_HEIGHT).contains(&ey) {
            counts[ey as usize] += 1;
        }
    }
    let mut best = authored_row;
    for cand in [authored_row, 1, 0, 2] {
        if counts[cand as usize] < counts[best as usize] {
            best = cand;
        }
    }
    best
}

/// A spawn's exit cooldown in ms (`None` ⇒ 0: the admin build drops zero
/// optionals, absent IS the zero cooldown). Single source for the balance
/// mini-sim and the spawn emission below — they must agree on the opening
/// (min-cooldown) group.
fn spawn_exit_cooldown_ms(spawn: &WaveSpawn) -> i64 {
    (spawn.cooldown_seconds.unwrap_or(0.0).max(0.0) * 1000.0) as i64
}

/// When a mob actually starts fighting, in SECONDS, relative to the moment the
/// ally side is ready — the input the balance mini-sim needs under the slot
/// model. Mirrors `handle_spawn_entity`'s exit scheduling exactly:
/// exit = `max(exit_cooldown_ms, floor)` counted from the spawn batch, where
/// `floor` is `start_fight_delay_ticks` for wave 1 (the hero plants at
/// StartFight) and `formation_advance_ticks` for waves 2+ (the formation dash
/// lands) — i.e. the ally side becomes ready exactly at `floor`, so relative
/// arrival = `max(cooldown − floor, 0)` + the entrance run
/// (`wave_entrance_offset_cells` × rush/walk tempo; the wave's min-cooldown
/// group rushes, everyone else walks). During the run the mob cannot act
/// (movement gates casting), so its fighting window opens at landing.
fn slot_arrival_delay_seconds(
    fight_settings: &configs::fighting::FightSettings,
    cooldown_ms: i64,
    wave_min_cooldown_ms: i64,
    floor_ms: i64,
) -> f64 {
    let ms_per_cell = if cooldown_ms == wave_min_cooldown_ms {
        fight_settings.wave_entrance_rush_ms_per_cell
    } else {
        fight_settings.wave_entrance_walk_ms_per_cell
    };
    let run_ms = fight_settings.wave_entrance_offset_cells.max(0) * ms_per_cell as i64;
    ((cooldown_ms - floor_ms).max(0) + run_ms) as f64 / 1000.0
}

fn sim_wave_choose_next_target(enemies: &[SimEnemy]) -> Option<usize> {
    let mut fastest = 1800.0f64;
    let mut idx = None;
    for (i, e) in enemies.iter().enumerate() {
        if e.gated_pos.is_some() {
            continue; // parked behind the death gate: not arrived, not targetable
        }
        if e.delay <= 0.0 && e.ttk < fastest {
            idx = Some(i);
            // Track the lowest time-to-kill among the arrived enemies so we
            // pick the fastest-dying target. (The original legacy script stored
            // `enemy.delay` here — always 0 for arrived enemies — which pinned
            // `fastest` to 0 and made the loop always keep the FIRST arrived
            // enemy regardless of ttk; corrected to `e.ttk`.)
            fastest = e.ttk;
        }
    }
    idx
}

fn sim_wave_choose_sim_time(enemies: &[SimEnemy], current_target: Option<usize>) -> f64 {
    let mut next_step = 1800.0f64;
    for e in enemies {
        if e.gated_pos.is_none() && e.delay > 0.0 && e.delay < next_step {
            next_step = e.delay;
        }
    }
    if let Some(idx) = current_target
        && let Some(t) = enemies.get(idx)
        && t.ttk < next_step
    {
        next_step = t.ttk;
    }
    next_step
}

fn sim_wave_advance(
    enemies: &mut Vec<SimEnemy>,
    mob_damage: &mut f64,
    gated_release_run: f64,
    step_cap: Option<f64>,
) {
    let target = sim_wave_choose_next_target(enemies);
    let mut time = sim_wave_choose_sim_time(enemies, target);
    // The summon-overlap path caps the step at the boss's trigger crossing so
    // the splice lands mid-kill instead of after the boss's one-step death.
    if let Some(cap) = step_cap {
        time = time.min(cap);
    }
    let mut killed = false;
    if let Some(t) = target {
        // Total per-second damage of the arrived enemies. Matches the shipped
        // legacy `reduce(|sum| sum + this.eff_damage, 0)` script — in that
        // language's array closures `this` binds to the CURRENT ELEMENT, so the
        // original did compute this exact per-enemy sum (the #2046 note calling
        // it broken misread that binding; the code below was already parity).
        let dmg: f64 = enemies
            .iter()
            .filter(|e| e.delay <= 0.0 && e.gated_pos.is_none())
            .map(|e| e.eff_damage)
            .sum();
        *mob_damage += dmg * time;
        enemies[t].ttk -= time;
        if enemies[t].ttk <= 0.0 {
            enemies.remove(t);
            killed = true;
        }
    }
    for e in enemies.iter_mut() {
        if e.gated_pos.is_none() && e.delay > 0.0 {
            e.delay = (e.delay - time).max(0.0);
        }
    }
    // Mirror the live death-gated release: a kill frees the lowest queue
    // position, which then runs in (walk tempo) before fighting. Released
    // AFTER this step's delay decrement: the kill lands at the END of the
    // step, so the walk-in must consume time in the FOLLOWING steps.
    // (Releasing before the decrement swallowed up to a whole run per kill,
    // modeling gated waves as overlapping more than they do → under-tuned.)
    if killed
        && let Some(next) = enemies
            .iter_mut()
            .filter(|e| e.gated_pos.is_some())
            .min_by_key(|e| e.gated_pos)
    {
        next.gated_pos = None;
        next.delay = gated_release_run;
    }
}

/// Native: the `prepare_fight` interpreter. Computes normalised enemy stats from
/// the chapter power curve + the typed wave blob, then emits spawn events for the
/// current wave. RNG is consumed once per spawned enemy (the spawn-entity uuid),
/// in iteration order — identical to the original. `fight` supplies
/// `current_wave` + the live `entities` (for the multi-wave x-offset).
#[allow(clippy::too_many_arguments)]
pub fn spawn_wave(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    fight_data: &WaveFightData,
    base_power: f64,
    current_chapter: i64,
    fight_type: &str,
) -> Result<(), anyhow::Error> {
    const POWER_EFF_HP: f64 = 0.75;
    const POWER_ATTACK: f64 = 1.0 - POWER_EFF_HP;
    // Summoned reinforcements keep only this fraction of their power-law
    // attack weight (HP untouched — the detour to kill them is real). The
    // `power^0.25` law makes even 0.05-power adds hit at ~half the boss's
    // rate, so an un-carved summon phase nearly DOUBLES concurrent DPS at
    // the tail of an on-the-edge fight — same total budget, unsurvivable
    // shape. Carving keeps the post-summon phase's rate near the boss-alone
    // steady rate; the normalization redistributes the carved share.
    const SUMMON_ATTACK_SHARE: f64 = 0.15;

    // Campaign enemy power follows the geometric curve past the hand-made
    // chapters, via `balance::enemy_power_scalar` — shared with the battle-end
    // analytics so the report stamps exactly what spawned. The `eff` divide below
    // is float (no integer truncation).
    let is_dungeon = lookups
        .fight_template_is_dungeon
        .get(&fight.fight_id)
        .copied()
        .unwrap_or(false);
    let power = balance::enemy_power_scalar(base_power, current_chapter, fight_type, is_dungeon);

    let hp_k = balance::hp_k_for_chapter(config, current_chapter);
    let eff = power / balance::BASE_POWER as f64;
    let mut eff_hp = balance::BASE_HP * (eff * hp_k).powf(0.5);
    let mut eff_attack = balance::BASE_ATTACK * (eff / hp_k).powf(0.5);

    // Two independent wave-budget knobs: `wave_damage_skew` scales the wave's
    // damage normalization (lethality / hp_end pressure); `wave_hp_skew`
    // shrinks the wave's HP budget (kill-time / DPS check). See the field docs
    // on `BalanceTuning` for the break-even/tempo law.
    eff_hp *= balance::tuning().wave_damage_skew;
    eff_attack /= balance::tuning().wave_hp_skew;
    // Per-fight damage-budget multiplier (`enemy_damage_mult` on the template):
    // compensates fight shapes whose sustained concurrency makes the same
    // total damage less survivable. Damage only — HP/length/loot unchanged.
    eff_hp *= fight_data.enemy_damage_mult.unwrap_or(1.0);

    let player_dps = eff_attack * balance::BASE_SPELL_EFF * balance::DMG_K;

    // `min_power` over all readable powers (the original ignored `entity_id`
    // here, so an entry with a power but no id can still lower the minimum).
    let mut min_power: Option<f64> = None;
    for ent in &fight_data.entities {
        if let Some(p) = ent.power {
            min_power = Some(min_power.map(|mp| mp.min(p)).unwrap_or(p));
        }
    }
    let min_power = min_power.unwrap_or(1.0);

    // `entity_powers` keyed by id (entries with no id are skipped); a missing
    // power defaults to 1.0.
    let mut entity_powers: std::collections::HashMap<String, f64> =
        std::collections::HashMap::new();
    for ent in &fight_data.entities {
        let Some(id) = &ent.entity_id else {
            continue;
        };
        let p = ent.power.unwrap_or(1.0);
        entity_powers.insert(id.clone(), p / min_power);
    }

    let mut mobs_eff_hp = 0.0f64;
    for wave in &fight_data.waves {
        for spawn in wave {
            let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
            mobs_eff_hp += enemy_power.powf(POWER_EFF_HP);
        }
    }

    let time = fight_data.time;
    let player_damage = player_dps * time;
    let mob_hp_norm = if mobs_eff_hp > 0.0 {
        player_damage / mobs_eff_hp
    } else {
        0.0
    };
    let mob_norm_ttk = if player_dps > 0.0 {
        mob_hp_norm / player_dps
    } else {
        0.0
    };

    // The mini-sim's join times come from the SLOT-MODEL timeline (exit
    // cooldowns + floors + entrance runs), not the legacy `delay` field — the
    // slot director retired `delay` as a timing input, and budgeting from it
    // made real mob damage start later than the sim assumed (waves easier
    // than their `time` budget). Floors mirror `handle_spawn_entity`.
    let wave1_floor_ms = config
        .require_fight_template(fight.fight_id)
        .ok()
        .and_then(|t| t.start_fight_delay_ticks)
        .unwrap_or(config.fight_settings.start_fight_delay_ticks_default)
        as i64;
    let later_floor_ms = later_wave_entrance_floor_ticks(config, fight) as i64;

    let mut overall_damage = 0.0f64;
    // A death-released mob walks in (never rushes) — its fighting window
    // opens one walk-run after the kill that freed it.
    let gated_release_run = (config.fight_settings.wave_entrance_offset_cells.max(0)
        * config.fight_settings.wave_entrance_walk_ms_per_cell as i64)
        as f64
        / 1000.0;
    // NOTE: the roster keeps FULL power-law attack weights even for summon
    // waves. The `SUMMON_ATTACK_SHARE` carve applies ONLY to the spawned
    // stats below — if it were modeled here too, the normalization would
    // compensate by raising the whole wave's (incl. the boss's) attack to
    // still meet the budget, transferring the carved damage INTO the boss
    // (observed: Ch1-09 Boss 34/35 lost). Keeping the model at full weight
    // means real total damage lands slightly UNDER budget for summon
    // fights — that under-run is the survivability the carve buys.
    let build_wave_roster = |wave: &[WaveSpawn], floor_ms: i64| -> Vec<SimEnemy> {
        let wave_min_cooldown_ms = wave.iter().map(spawn_exit_cooldown_ms).min().unwrap_or(0);
        let gate_plan = wave_exit_gate_plan(wave, fight_data.stream_active_count);
        let mut sim_enemies: Vec<SimEnemy> = Vec::new();
        for (spawn_idx, spawn) in wave.iter().enumerate() {
            let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
            let gated_pos = gate_plan[spawn_idx];
            let delay = if gated_pos.is_some() {
                0.0 // unused while gated; set to the release run on release
            } else {
                slot_arrival_delay_seconds(
                    &config.fight_settings,
                    spawn_exit_cooldown_ms(spawn),
                    wave_min_cooldown_ms,
                    floor_ms,
                )
            };
            let is_boss = Uuid::parse_str(&spawn.entity_id)
                .ok()
                .and_then(|u| lookups.entity_template_is_boss.get(&u).copied())
                .unwrap_or(false);
            sim_enemies.push(SimEnemy {
                eff_damage: enemy_power.powf(POWER_ATTACK),
                ttk: mob_norm_ttk * enemy_power.powf(POWER_EFF_HP),
                delay,
                gated_pos,
                is_boss,
            });
        }
        sim_enemies
    };

    // Boss-summon fights: the LAST wave really spawns the moment the boss drops
    // below `summon_wave_at_hp_fraction` of max HP (`logic/fighting.rs`),
    // OVERLAPPING the boss — while the player detours to kill the
    // reinforcements, the boss keeps attacking. Modeling it as a sequential
    // wave (the pre-fix behaviour) omitted that extended boss uptime from the
    // damage budget, over-tuning exactly the on-the-edge stage bosses. Here the
    // boss wave's sim is capped at the trigger point and the summon roster is
    // spliced in, so the normalization sees the true timeline.
    let summon_frac = fight_data.summon_wave_at_hp_fraction;
    let n_waves = fight_data.waves.len();
    let summon_overlap = summon_frac.filter(|_| {
        n_waves >= 2
            && fight_data.waves[..n_waves - 1]
                .iter()
                .any(|w| build_wave_roster(w, 0).iter().any(|e| e.is_boss))
    });

    if let Some(frac) = summon_overlap {
        for (sim_wave_idx, wave) in fight_data.waves[..n_waves - 1].iter().enumerate() {
            let floor_ms = if sim_wave_idx == 0 {
                wave1_floor_ms
            } else {
                later_floor_ms
            };
            let mut sim_enemies = build_wave_roster(wave, floor_ms);
            let boss_orig_ttk = sim_enemies
                .iter()
                .find(|e| e.is_boss)
                .map(|e| e.ttk)
                .unwrap_or(0.0);
            // Only the wave that hosts the boss receives the summon splice.
            let mut summon_pending = boss_orig_ttk > 0.0;
            let mut mob_damage = 0.0f64;
            let mut iter = 0;
            while !sim_enemies.is_empty() && iter < 800 {
                iter += 1;
                // Remaining boss ttk is an exact HP proxy (ttk ∝ hp at the
                // reference DPS). Cap the step at the trigger crossing so the
                // splice lands mid-kill, not after the boss's one-step death.
                let boss_margin = sim_enemies
                    .iter()
                    .find(|e| e.is_boss)
                    .map(|b| b.ttk - frac * boss_orig_ttk);
                if summon_pending {
                    match boss_margin {
                        Some(margin) if margin <= 1e-9 => {
                            summon_pending = false;
                            // Summon entrances have no formation floor — they
                            // fire mid-fight at the player's current column.
                            sim_enemies
                                .extend(build_wave_roster(&fight_data.waves[n_waves - 1], 0));
                        }
                        // In-model boss death without crossing can't happen
                        // (the crossing precedes ttk 0); guard for safety.
                        None => summon_pending = false,
                        _ => {}
                    }
                }
                let step_cap = if summon_pending {
                    boss_margin.map(|m| m.max(1e-6))
                } else {
                    None
                };
                sim_wave_advance(
                    &mut sim_enemies,
                    &mut mob_damage,
                    gated_release_run,
                    step_cap,
                );
            }
            overall_damage += mob_damage;
        }
    } else {
        for (sim_wave_idx, wave) in fight_data.waves.iter().enumerate() {
            let floor_ms = if sim_wave_idx == 0 {
                wave1_floor_ms
            } else {
                later_floor_ms
            };
            let mut sim_enemies = build_wave_roster(wave, floor_ms);
            let mut mob_damage = 0.0f64;
            let mut iter = 0;
            while !sim_enemies.is_empty() && iter < 400 {
                iter += 1;
                sim_wave_advance(&mut sim_enemies, &mut mob_damage, gated_release_run, None);
            }
            overall_damage += mob_damage;
        }
    }

    let mob_dps_norm = if overall_damage > 0.0 {
        eff_hp / overall_damage
    } else {
        0.0
    };
    let mob_attack_norm = mob_dps_norm / balance::BASE_SPELL_EFF / balance::DMG_K;

    let wave_idx = (fight.current_wave - 1) as usize;

    let Some(current_wave) = fight_data.waves.get(wave_idx) else {
        return Ok(());
    };

    // Slot-model anchor (docs/combat-grid-migration-plan.md §2.1): the enemy
    // columns hang off the player's column. Advancing waves 2+ use the player's
    // landing column; stationary dungeons keep the current column.
    let player_x = fight
        .entities
        .iter()
        .find(|e| e.id == fight.player_id)
        .map(|e| e.coordinates.x)
        .unwrap_or(0);
    // A summon wave (the LAST wave when `summon_wave_at_hp_fraction` is set)
    // anchors at the player's CURRENT column: it fires mid-boss-fight with no
    // formation dash preceding it, so the +FORMATION_ADVANCE_CELLS anchor of a
    // normal wave transition would land its slots out of everyone's reach.
    let is_summon_wave =
        fight_data.summon_wave_at_hp_fraction.is_some() && wave_idx + 1 == fight_data.waves.len();
    let advances_formation = between_wave_behavior(config, fight).advance_formation;
    let anchor_x = if wave_idx > 0 && !is_summon_wave && advances_formation {
        player_x + FORMATION_ADVANCE_CELLS
    } else {
        player_x
    };

    // Opening group = the wave's minimum exit cooldown; it keeps the rush
    // entrance pace (the lab opening-echelon feel), later exits walk.
    let min_cooldown_ms = current_wave
        .iter()
        .map(spawn_exit_cooldown_ms)
        .min()
        .unwrap_or(0);

    // Death-gated exits (revived streaming cap): everyone beyond
    // `stream_active_count` parks with a queue position instead of a timer;
    // `handle_entity_death` releases them one per enemy kill.
    let gate_plan = wave_exit_gate_plan(current_wave, fight_data.stream_active_count);

    // Balanced landing rows for the opening group (gated mobs re-pick theirs
    // from live occupancy at release). Living survivors (summon waves fire
    // mid-fight) seed the plan so reinforcements never land on the summoner.
    let live: Vec<(i64, i64)> = fight
        .entities
        .iter()
        .filter(|e| e.team == EntityTeam::Enemy && e.hp > 0)
        .map(|e| {
            let c = e.move_target.as_ref().unwrap_or(&e.coordinates);
            (c.x, c.y)
        })
        .collect();
    let row_plan = wave_row_plan(
        current_wave,
        &gate_plan,
        config,
        lookups,
        &live,
        anchor_x,
        is_summon_wave,
    );

    // §2 wave_share: reward/weight per mob = reward_mob_budget / actual total
    // mob count of the fight (all waves), stored per-10000 (like crit_chance).
    // Stamped on every mob so per-kill drops / pet-ult charge / counter procs
    // stay count-invariant when the migrator inflates concurrency. `None`
    // budget ⇒ no attribute (absent = 1.0, legacy content bit-identical). No
    // RNG draws.
    let total_mob_count: usize = fight_data.waves.iter().map(|w| w.len()).sum();
    let wave_share_per10000: Option<i64> = fight_data.reward_mob_budget.map(|budget| {
        if total_mob_count == 0 {
            10000
        } else {
            ((budget as f64 / total_mob_count as f64) * 10000.0).round() as i64
        }
    });

    let mut spawn_evts = Vec::new();
    for (spawn_idx, spawn) in current_wave.iter().enumerate() {
        let enemy_tpl_id = match Uuid::parse_str(&spawn.entity_id) {
            Ok(u) => u,
            Err(_) => continue,
        };
        let enemy_power = entity_powers.get(&spawn.entity_id).copied().unwrap_or(1.0);
        let enemy_hp_norm = enemy_power.powf(POWER_EFF_HP);
        // Mirror of the mini-sim's summon carve (`SUMMON_ATTACK_SHARE`) —
        // model and spawned stats must agree or the budget drifts. Gated on
        // `summon_overlap` (boss-hosted summon fights), the exact condition
        // under which the model carved.
        let enemy_attack_norm = enemy_power.powf(POWER_ATTACK)
            * if is_summon_wave && summon_overlap.is_some() {
                SUMMON_ATTACK_SHARE
            } else {
                1.0
            };
        // A2-BAL-002 §2.5: the two difficulty axes are steered independently.
        //
        // Above, one scalar becomes both HP and Attack through fixed exponents.
        // These two curves are what let a refit move encounter HP without
        // touching outgoing damage, or the reverse — the correction matrix in
        // §2.7 is written entirely in terms of that separation. Both remain
        // identity through the chapter-21 gate; the all-free refit authors
        // independent HP/outgoing knots only after that seam.
        let mut enemy_hp = enemy_hp_norm * mob_hp_norm * balance::k_hp(current_chapter);
        let mut enemy_attack =
            enemy_attack_norm * mob_attack_norm * balance::k_out(current_chapter);

        let has_big_hp_bar = lookups
            .entity_template_is_boss
            .get(&enemy_tpl_id)
            .copied()
            .unwrap_or(false);

        let mut attrs = EntityAttributes::default();
        // Bosses carry crit + armor for
        // combat TEXTURE, budget-neutrally — the scalar factors these stats
        // multiply are carved back out of attack/hp, so boss power (and the
        // co-derived E-curve calibration) is unchanged: crit spikes come out
        // of steady attack (same DPS), armor mitigation comes out of the HP
        // bar (same EHP, same TTK both ways). Entropy resolution makes boss
        // crits RHYTHMIC (one per 1/chance hits) — a telegraphed spike, not a
        // streak lottery.
        if has_big_hp_bar {
            let t = balance::tuning();
            let crit = t.boss_crit_chance;
            if crit > 0.0 {
                attrs.add("crit_chance", crit as i64);
                enemy_attack /= 1.0 + (crit / 10000.0).clamp(0.0, 1.0);
            }
            let armor = t.boss_armor;
            if armor > 0.0 {
                attrs.add("armor", armor as i64);
                enemy_hp *= balance::armor_k(armor);
            }
            // A2-BAL-001: hidden automatic stun remains removed. Preserve the
            // actual previously shipped outgoing budget independently by
            // stamping the frozen trace ratio. `attack` consumes it only after
            // composing the hit, which covers Attack-derived, flat and DoT
            // payload shares without restoring any control mechanic.
            attrs.add(
                BOSS_OUTGOING_EQUIVALENCE_PPM_ATTR,
                (balance::boss_outgoing_equivalence(current_chapter) * 1_000_000.0).round() as i64,
            );
        }
        attrs.add("attack", enemy_attack.floor() as i64);
        attrs.add("hp", enemy_hp.floor() as i64);
        attrs.add("speed", 10000);

        let cooldown_ms = spawn_exit_cooldown_ms(spawn);
        // Column by attack type (§2.1/§2.6): melee (any range ≤ 1 ability)
        // fights from the near column, pure-ranged from the far one. Row from
        // the balanced plan (authored row, spread within the column so the
        // opening group doesn't stack on one tile); stacking is still legal —
        // the client scatters whatever remains.
        let col_offset = if template_has_melee_ability(config, lookups, enemy_tpl_id) {
            MELEE_COL_OFFSET
        } else {
            RANGED_COL_OFFSET
        };
        let row = row_plan[spawn_idx];
        // Spawn beyond the battle slot (off-screen edge): handle_spawn_entity
        // schedules the exit run back onto the slot at the unit's cooldown.
        let position = Coordinates {
            x: anchor_x + col_offset + config.fight_settings.wave_entrance_offset_cells,
            y: row,
        };
        // NB: a zero value never materializes as an attribute
        // (EntityAttributes::add drops zeros) — absent IS the zero cooldown,
        // and handle_spawn_entity reads it via unwrap_or(0).
        if let Some(queue_pos) = gate_plan[spawn_idx] {
            // Death-gated: no timer, no rush — the mob parks off-screen and
            // `handle_entity_death` schedules its (walk-tempo) entrance when a
            // kill frees its queue position (1-based, zero-drop safe).
            attrs.add("exit_gated", queue_pos);
        } else {
            attrs.add("exit_cooldown_ms", cooldown_ms);
            if cooldown_ms == min_cooldown_ms {
                attrs.add("entrance_rush", 1);
            }
        }
        // §2: stamp reward/weight share (drop-zero pattern; absent ⇒ 1.0).
        if let Some(ws) = wave_share_per10000 {
            attrs.add("wave_share", ws);
        }
        // Boss-summon: reinforcements from a summon wave carry NO economy weight
        // (drops, pet-ult charge, counters — all keyed off `wave_share()`, which
        // returns 0 for a `summoned` mob — plus kill-quest ticks). The boss keeps
        // its own full, unscaled payout, so the boss fight's faucet stays flat.
        if is_summon_wave {
            attrs.add("summoned", 1);
        }

        // The spawn id is drawn from the RNG stream in config order — the
        // stream must stay stable across content edits that only touch timing.
        let spawn_id = uuid::Builder::from_random_bytes(rng.random_bytes()).into_uuid();

        let spawn_evt = OverlordEventSpawnEntity {
            id: spawn_id,
            entity_template_id: enemy_tpl_id,
            position,
            entity_team: EntityTeam::Enemy,
            has_big_hp_bar,
            entity_attributes: attrs,
        };
        spawn_evts.push(spawn_evt);
    }

    // BAL-026: stamp each mob's share of the wave's initial HP budget — the
    // outgoing damage gauge's normalizer. The denominator is fixed at this
    // spawn snapshot and never re-normalized by deaths. A summon wave stays
    // unstamped: `summoned` already reads as share 0.
    if !is_summon_wave {
        let total_hp: i64 = spawn_evts
            .iter()
            .map(|evt| {
                evt.entity_attributes
                    .0
                    .get("hp")
                    .copied()
                    .unwrap_or(0)
                    .max(0)
            })
            .sum();
        if total_hp > 0 {
            for evt in &mut spawn_evts {
                let hp = evt.entity_attributes.0.get("hp").copied().unwrap_or(0);
                let share = (hp.max(0) as f64 / total_hp as f64 * 10_000.0).round() as i64;
                evt.entity_attributes.add("gauge_hp_share", share);
            }
        } else {
            // BAL-026: a wave with no HP budget is an invalid fixture and must
            // be worth ZERO outgoing gauge. Stamp explicit zeros — unstamped
            // entities would fall back to `gauge_hp_share()`'s full-share
            // default.
            for evt in &mut spawn_evts {
                // -1 is the explicit zero-share marker: the attribute map
                // drops literal zeros, and absent reads as full share.
                evt.entity_attributes.add("gauge_hp_share", -1);
            }
            tracing::error!(
                fight_id = %fight.fight_id,
                "spawn_wave: wave has no HP budget — gauge shares stamped to zero"
            );
        }
    }
    for spawn_evt in spawn_evts {
        push_event(sink, spawn_evt)?;
    }
    Ok(())
}

/// Slot-model promotion predicate (docs/combat-grid-migration-plan.md §2.2):
/// the ally formation steps one column forward when the near (melee) column
/// holds no living enemy while the far column does. An enemy's effective
/// column is where it stands or is running to (`move_target`); units still
/// parked beyond the far column (waiting out their exit cooldown behind the
/// screen edge) do not count — stepping toward them would drag the hero to
/// the spawn edge. Recursion needs no special code: after a step the old far
/// column IS the near column, and the next death/landing re-checks.
pub fn slot_promotion_needed(fight: &ActiveFight) -> bool {
    let Some(player) = fight.entities.iter().find(|e| e.id == fight.player_id) else {
        return false;
    };
    if player.hp == 0 || player.move_target.is_some() {
        return false;
    }
    let p = player.coordinates.x;
    let mut far_occupied = false;
    for e in &fight.entities {
        if e.team != EntityTeam::Enemy || e.hp == 0 {
            continue;
        }
        let col = e
            .move_target
            .as_ref()
            .map(|t| t.x)
            .unwrap_or(e.coordinates.x);
        if col <= p + MELEE_COL_OFFSET {
            return false;
        }
        if col == p + RANGED_COL_OFFSET {
            far_occupied = true;
        }
    }
    far_occupied
}

/// A TEMPLATE has a melee ability if any of its abilities has range ≤ 1 —
/// the slot director's column choice (§2.6). Unknown template/range counts as
/// melee: the near column is the conservative slot (the unit can always act
/// from contact).
fn template_has_melee_ability(config: &GameConfig, lookups: &ContentLookups, tpl_id: Uuid) -> bool {
    config
        .entity_template(tpl_id)
        .map(|tpl| {
            tpl.ability_ids
                .iter()
                .any(|ability_id| lookups.ability_range.get(ability_id).copied().unwrap_or(0) <= 1)
        })
        .unwrap_or(true)
}

/// Convert the typed config mirror (`prepare_fight_waves`) into the runtime
/// [`WaveFightData`] consumed by [`spawn_wave`]. This is the native data
/// source for the prepare_fight interpreter.
pub fn wave_data_from_config(cfg: &essences::fighting::PrepareFightWaves) -> WaveFightData {
    WaveFightData {
        entities: cfg
            .entities
            .iter()
            .map(|e| WaveEntityPower {
                entity_id: e.entity_id.clone(),
                power: e.power,
            })
            .collect(),
        waves: cfg
            .waves
            .iter()
            .map(|wave| {
                wave.iter()
                    .map(|s| WaveSpawn {
                        entity_id: s.entity_id.clone(),
                        // The deployed prepare_fight always carried an explicit
                        // `delay: 0` for spawns that omit it; mirror that default
                        // here (the typed config omits the 0s).
                        delay: Some(s.delay.unwrap_or(0.0)),
                        position: s.position.clone(),
                        cooldown_seconds: s.cooldown_seconds,
                        row: s.row,
                    })
                    .collect()
            })
            .collect(),
        time: cfg.time,
        power: Some(cfg.power),
        stream_active_count: cfg.stream_active_count,
        reward_mob_budget: cfg.reward_mob_budget,
        summon_wave_at_hp_fraction: cfg.summon_wave_at_hp_fraction,
        enemy_damage_mult: cfg.enemy_damage_mult,
    }
}

// ---------------------------------------------------------------------------
// Casts and movement
// ---------------------------------------------------------------------------

fn is_valid_target(
    lookups: &ContentLookups,
    target: &Entity,
    ability: &Ability,
    caster: &Entity,
) -> bool {
    let target_type = lookups
        .ability_target_type
        .get(&ability.template_id)
        .map(|s| s.as_str())
        .unwrap_or("");
    let by_team = match target_type {
        "Enemy" => target.team != caster.team,
        "Ally" => target.team == caster.team,
        _ => false,
    };
    let range = lookups
        .ability_range
        .get(&ability.template_id)
        .copied()
        .unwrap_or(0);
    by_team && get_distance_to(caster, target) <= range
}

/// Native: queue `casts` attack actions for `caster` against `valid_targets`.
/// Consumes `multicast_chance` from `rng`, then (per cast after the first, when
/// there are multiple targets) a `randint` for target selection. `_ability` is
/// unused, matching the original signature.
#[allow(clippy::too_many_arguments)]
pub fn cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    caster: &Entity,
    _ability: &Ability,
    valid_targets: &[Entity],
    natural_casts_number: i64,
) -> Result<(), anyhow::Error> {
    let mut casts_number = natural_casts_number;
    let is_multicast = entropy_throw(rng, lookups, caster, "multicast_chance", 0.0, 1.0);
    if is_multicast {
        casts_number *= 2;
    }

    // Effect Stone `NextAttackDoubleHit`: extra swings armed by a trigger fire.
    //
    // They ride this cast's own swing list — NOT a re-dispatched
    // `StartCastAbility`, which would go through
    // `push_start_cast_replacing`'s `max(existing, now + cooldown)` and *delay*
    // the entity's next natural swing instead of adding one. They are queued
    // through `OriginSink::proc` so the damage they land one or more ticks later
    // is `Proc` and cannot re-enter the trigger that granted them.
    let extra_swings = attr_get(caster, crate::mechanics::stones::NEXT_ATTACK_EXTRA_HITS) as i64;
    let extra_swings = extra_swings.max(0);
    if extra_swings > 0 {
        incr_attr(
            sink,
            caster.id,
            crate::mechanics::stones::NEXT_ATTACK_EXTRA_HITS,
            -extra_swings,
        )?;
    }

    let total_swings = casts_number + extra_swings;
    let base_cast_time = entity_get_tpl_cast_time(config, caster) as f64;
    // Divided over ALL swings, so an extra swing lands inside the cast window
    // instead of extending it past the entity's next natural swing.
    let cast_time = (base_cast_time / total_swings as f64).floor() as i64;
    for i in 0..total_swings {
        let target = if valid_targets.len() > 1 {
            if i == 0 {
                get_target(caster, valid_targets)
                    .cloned()
                    .unwrap_or_else(|| valid_targets[0].clone())
            } else {
                let idx = rng.random_index(valid_targets.len());
                valid_targets[idx].clone()
            }
        } else {
            valid_targets[0].clone()
        };
        let delay = (i * cast_time).max(0) as u64;
        let duration = cast_time.max(0) as u64;
        if i < casts_number {
            sink.push_attack(delay, duration, target.id, CombatEventOrigin::Core)?;
        } else {
            OriginSink::proc(sink).push_attack(
                delay,
                duration,
                target.id,
                CombatEventOrigin::Core,
            )?;
        }
    }
    Ok(())
}

/// Native: the ability `on_cast` hook. Rolls `bravery`; on success applies a
/// random buff (`protection`/`empower`). Consumes `bravery` then (if it lands)
/// a `randint(0,2)` from `rng`. Effect `on_apply` reactions dispatch via
/// `effects`.
pub fn on_cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    lookups: &ContentLookups,
    effects: &mut dyn EffectCb,
    caster: &Entity,
) -> Result<(), anyhow::Error> {
    if entropy_throw(rng, lookups, caster, "bravery", 0.0, 1.0) {
        let pool = ["protection", "empower"];
        let idx = rng.random_index(pool.len());
        let code = pool[idx];
        apply_entity_effect(
            sink,
            lookups,
            effects,
            caster,
            code,
            balance::BRAVERY_BUFF_DURATION,
        )?;
    }
    Ok(())
}

/// Native: move `entity` toward the enemy line in a single multi-cell run
/// (one `StartMove` instead of one per cell — every per-cell seam quantizes
/// to the 100ms game tick and gives the client a chance to stutter).
///
/// Movement is fixed-direction (allies always advance +x, enemies −x), so we
/// only ever advance toward the nearest opponent *ahead* — never chase one we
/// have already reached or passed, which would march us away from the fight
/// forever. We cover the **whole gap** toward the opponent (one column short)
/// in one `StartMove`, so an approach is a single smooth run, not one per cell.
///
/// In the two-phase anchor model exactly one side moves at any moment (enemies
/// charge the stationary hero-anchor; in phase 2 the Ally team charges the
/// stationary casting ranged enemies), so there is no "meet in the middle" —
/// the mover simply closes the whole distance. Two same-team runners planning
/// on the same tick still can't land on or cross each other: a `Run` lowers to
/// an *immediate* `StartMove` and the event loop is depth-first LIFO, so the
/// first planner's `handle_start_move` sets its `move_target` reservation
/// BEFORE the second plans this tick; the second's probe routes every cell
/// through `cell_exists_and_free` (checks coordinates AND reserved
/// `move_target`), so it sidesteps around the reservation.
///
/// (The entrance "run onto the screen → run in the fight" seam is a separate,
/// client-side concern — Unity's run-in tween must flow into the first
/// `StartMove` instead of force-settling to Idle; no server distance can cover
/// it.)
///
/// The walk also stops on the first cell where `ability` gains a valid target,
/// and never steps onto a cell occupied or reserved by another entity.
///
/// Neither team may cross the other's front line. A mover advances at most to
/// the column directly in front of the opposing team's frontmost LIVING unit and
/// never onto or past it, so the two sides meet exactly one column apart instead
/// of stacking on the same column (an enemy standing right under the hero). The
/// opposing front is taken over both current cells AND reserved `move_target`s,
/// so two mutual approachers don't both land on the same midpoint column on an
/// even gap: the depth-first / LIFO second planner sees the first's reservation
/// and stops one column short. This is the hard guarantee layered on top of the
/// full-gap `max_steps` walk and the in-range stop.
/// Native: emit a run action moving `entity` to `to` (no-op if speed is 0 or
/// the move covers no distance).
pub fn entity_run(
    sink: &mut dyn FightSink,
    lookups: &ContentLookups,
    entity: &Entity,
    to: Coordinates,
) -> Result<(), anyhow::Error> {
    const DEFAULT_TIME_PER_CELL: f64 = 500.0;
    let speed = get_entity_stat(lookups, entity, "speed");
    if speed == 0.0 {
        return Ok(());
    }
    let speed_norm = speed / 10000.0;
    // Euclidean, not |dx|: a diagonal sidestep covers √2 cells and must take
    // √2× the time, otherwise the unit visibly speeds up on lane changes.
    let dx = (to.x - entity.coordinates.x) as f64;
    let dy = (to.y - entity.coordinates.y) as f64;
    let distance = (dx * dx + dy * dy).sqrt();
    if distance == 0.0 {
        return Ok(());
    }
    let mut time_per_cell = DEFAULT_TIME_PER_CELL / speed_norm;
    // Ally runs (advance dash, in-fight repositioning) are sped up by the config multiplier
    // (docs/combat-feel-porting-plan.md [3.4]) — NOT via the `speed` attribute, which would
    // also scale ability cooldowns. A non-positive value (Default-built lookups) means 1.0.
    if entity.team == EntityTeam::Ally && lookups.ally_run_speed_mult > 0.0 {
        time_per_cell /= lookups.ally_run_speed_mult;
    }
    let duration = (time_per_cell * distance).floor() as u64;
    sink.push_run(to, duration, CombatEventOrigin::Core)
}

/// Native: attempt to cast `ability_id` from `caster`. Picks valid targets and
/// delegates to `cast`; if there are none and the caster is not `static`,
/// advances toward the enemy. `casts` is the natural cast count (default 1).
/// Consumes RNG only via `cast` / `advance_entity`.
#[allow(clippy::too_many_arguments)]
pub fn try_cast(
    sink: &mut dyn FightSink,
    rng: &GameRng,
    config: &GameConfig,
    lookups: &ContentLookups,
    fight: &ActiveFight,
    caster: &Entity,
    ability_id: Uuid,
    casts: i64,
) -> Result<(), anyhow::Error> {
    if attr_present(caster, "sleep") {
        return Ok(());
    }
    if config.ability_template(ability_id).is_none() {
        return Err(anyhow::anyhow!("try_cast: unknown ability {ability_id}"));
    }
    let target_type = lookups
        .ability_target_type
        .get(&ability_id)
        .cloned()
        .unwrap_or_default();
    let ability_val = Ability {
        template_id: ability_id,
        level: 1,
        shards_amount: 0,
    };
    if target_type == "Self" {
        cast(
            sink,
            rng,
            config,
            lookups,
            caster,
            &ability_val,
            std::slice::from_ref(caster),
            casts,
        )?;
        return Ok(());
    }
    let mut valid_targets = Vec::new();
    for ent in &fight.entities {
        if is_valid_target(lookups, ent, &ability_val, caster) {
            valid_targets.push(ent.clone());
        }
    }
    if !valid_targets.is_empty() {
        cast(
            sink,
            rng,
            config,
            lookups,
            caster,
            &ability_val,
            &valid_targets,
            casts,
        )?;
        return Ok(());
    }
    // Slot model: no in-combat approach. Units fight from their slots; the
    // formation promotion step (logic::fighting::slot_promotion_events) closes
    // the gap when the near column empties. A caster with no target in range
    // simply re-arms and retries on its next cadence tick.
    Ok(())
}

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

    fn entity_at(team: EntityTeam, x: i64) -> Entity {
        Entity {
            id: uuid::Uuid::new_v4(),
            team,
            coordinates: Coordinates { x, y: 1 },
            ..Default::default()
        }
    }

    /// `target_type` / `range` must reach `ContentLookups`. When they are absent
    /// (the bug), `target_type` resolves to "" → `by_team` is always false → no
    /// ability ever has a valid target → entities advance every tick and run
    /// through the enemy line without attacking.
    #[test]
    fn is_valid_target_requires_populated_target_type_and_range() {
        let ability_id = uuid::Uuid::new_v4();
        let ability = Ability {
            template_id: ability_id,
            level: 1,
            shards_amount: 0,
        };
        let caster = entity_at(EntityTeam::Ally, 0);
        let enemy_in_range = entity_at(EntityTeam::Enemy, 1);
        let enemy_out_of_range = entity_at(EntityTeam::Enemy, 5);
        let ally = entity_at(EntityTeam::Ally, 1);

        // The bug: empty lookups (target_type "" → by_team false) — never valid.
        let empty = ContentLookups::default();
        assert!(
            !is_valid_target(&empty, &enemy_in_range, &ability, &caster),
            "empty lookups must yield no valid target (this was the run-through bug)"
        );

        // Fixed: target_type "Enemy" + range 1 sourced from the typed config.
        let mut populated = ContentLookups::default();
        populated
            .ability_target_type
            .insert(ability_id, "Enemy".to_string());
        populated.ability_range.insert(ability_id, 1);

        assert!(
            is_valid_target(&populated, &enemy_in_range, &ability, &caster),
            "an in-range enemy must be a valid target once lookups are populated"
        );
        assert!(
            !is_valid_target(&populated, &enemy_out_of_range, &ability, &caster),
            "an out-of-range enemy must not be targetable (caster should advance)"
        );
        assert!(
            !is_valid_target(&populated, &ally, &ability, &caster),
            "an ally must not be a valid target for an Enemy-typed ability"
        );
    }

    /// Baseline: the fight primitives themselves emit Core. Every combat event
    /// the game produces today comes from this path, so nothing in the live
    /// game is Proc until a modifier exists.
    #[test]
    fn fight_primitives_emit_core() {
        let mut target = entity_at(EntityTeam::Enemy, 1);
        target.hp = 10;
        target.max_hp = 100;

        let mut sink = NativeSink::default();
        heal_entity(&mut sink, None, &target, 5.0, CombatSource::Other).unwrap();

        assert_eq!(sink.events.len(), 1);
        assert_eq!(
            sink.events[0].combat_origin(),
            Some(CombatEventOrigin::Core)
        );
        assert!(sink.events[0].is_core_combat_event());
    }

    /// Acceptance criterion #2 (plumbing half): an Effect-Stone-style modifier
    /// runs the very same primitives against an `OriginSink::proc`, and every
    /// combat event it produces comes out Proc — so no trigger can react to it.
    /// No stones exist yet, hence the synthetic modifier.
    #[test]
    fn modifier_scope_marks_emitted_events_proc() {
        let mut target = entity_at(EntityTeam::Enemy, 1);
        target.hp = 10;
        target.max_hp = 100;

        let mut sink = NativeSink::default();
        {
            // Stand-in for an Effect Stone's execution scope.
            let mut modifier_sink = OriginSink::proc(&mut sink);
            heal_entity(&mut modifier_sink, None, &target, 5.0, CombatSource::Other).unwrap();
        }

        assert_eq!(sink.events.len(), 1);
        assert_eq!(
            sink.events[0].combat_origin(),
            Some(CombatEventOrigin::Proc)
        );
        assert!(
            !sink.events[0].is_core_combat_event(),
            "a modifier-produced event must never read as Core"
        );
    }

    /// The decorator only restamps provenance: the payload the primitive built
    /// is forwarded untouched, so a modifier's heal heals exactly as much.
    #[test]
    fn modifier_scope_changes_nothing_but_provenance() {
        let mut target = entity_at(EntityTeam::Enemy, 1);
        target.hp = 10;
        target.max_hp = 100;

        let mut core_sink = NativeSink::default();
        let core_applied =
            heal_entity(&mut core_sink, None, &target, 5.0, CombatSource::Other).unwrap();

        let mut proc_sink = NativeSink::default();
        let proc_applied = {
            let mut modifier_sink = OriginSink::proc(&mut proc_sink);
            heal_entity(&mut modifier_sink, None, &target, 5.0, CombatSource::Other).unwrap()
        };

        assert_eq!(core_applied, proc_applied);
        assert_eq!(
            core_sink.events[0]
                .clone()
                .with_origin(CombatEventOrigin::Proc),
            proc_sink.events[0]
        );
    }

    /// B1 lift: a producer scope may now schedule casts and runs, because the
    /// queued cast carries the scope's provenance all the way to
    /// `ActionWithDeadline` — the damage it lands a tick later can no longer
    /// surface as Core.
    #[test]
    fn modifier_scope_carries_provenance_onto_scheduled_casts_and_runs() {
        let mut sink = NativeSink::default();
        {
            let mut modifier_sink = OriginSink::proc(&mut sink);
            modifier_sink
                .push_attack(0, 100, uuid::Uuid::from_u128(1), CombatEventOrigin::Core)
                .unwrap();
            modifier_sink
                .push_run(Coordinates { x: 1, y: 1 }, 100, CombatEventOrigin::Core)
                .unwrap();
        }
        assert_eq!(sink.casts.len(), 2);
        for cast in &sink.casts {
            assert_eq!(cast.origin, CombatEventOrigin::Proc);
        }

        // A Core scope is the ambient case: the primitive's own mark stands.
        let mut core_sink = NativeSink::default();
        {
            let mut scope = OriginSink::new(&mut core_sink, CombatEventOrigin::Core);
            scope
                .push_attack(0, 100, uuid::Uuid::from_u128(1), CombatEventOrigin::Core)
                .unwrap();
            scope
                .push_run(Coordinates { x: 1, y: 1 }, 100, CombatEventOrigin::Core)
                .unwrap();
        }
        assert_eq!(core_sink.casts.len(), 2);
        for cast in &core_sink.casts {
            assert_eq!(cast.origin, CombatEventOrigin::Core);
        }
    }

    /// Same rule for events: what a producer scope cannot stamp, it cannot
    /// emit. `SpawnEntity` carries no provenance by design — a spawned
    /// combatant fights with its own Core actions — so a producer may not
    /// reach for it and get Core work for free.
    #[test]
    fn modifier_scope_refuses_events_it_cannot_mark() {
        let spawn = || OverlordEvent::SpawnEntity {
            id: uuid::Uuid::from_u128(1),
            entity_template_id: uuid::Uuid::from_u128(2),
            position: Coordinates { x: 1, y: 1 },
            entity_team: EntityTeam::Enemy,
            has_big_hp_bar: false,
            entity_attributes: EntityAttributes::default(),
        };

        let mut sink = NativeSink::default();
        {
            let mut modifier_sink = OriginSink::proc(&mut sink);
            assert!(modifier_sink.push_event(spawn()).is_err());
        }
        assert!(sink.events.is_empty());

        let mut core_sink = NativeSink::default();
        {
            let mut scope = OriginSink::new(&mut core_sink, CombatEventOrigin::Core);
            scope.push_event(spawn()).unwrap();
        }
        assert_eq!(core_sink.events.len(), 1, "Core scope stays unrestricted");
    }

    /// Marking only upgrades — the rule `CombatEventOrigin::merge` states and the
    /// clock and `post_event` already follow. A Core scope must not reset an
    /// event a modifier already marked, or a producer that nests a plain sink
    /// would launder its own output back to Core.
    #[test]
    fn a_core_scope_never_downgrades_an_already_marked_event() {
        let mut sink = NativeSink::default();
        {
            let mut scope = OriginSink::new(&mut sink, CombatEventOrigin::Core);
            scope
                .push_event(OverlordEvent::Heal {
                    entity_id: uuid::Uuid::from_u128(1),
                    heal: 1,
                    origin: CombatEventOrigin::Proc,
                    by_entity_id: None,
                    source: essences::fight_breakdown::CombatSource::Other,
                })
                .unwrap();
        }
        assert_eq!(
            sink.events[0].combat_origin(),
            Some(CombatEventOrigin::Proc)
        );

        // And a Core scope still stamps nothing onto genuinely Core work.
        let mut sink = NativeSink::default();
        {
            let mut scope = OriginSink::new(&mut sink, CombatEventOrigin::Core);
            scope
                .push_event(OverlordEvent::Heal {
                    entity_id: uuid::Uuid::from_u128(1),
                    heal: 1,
                    origin: CombatEventOrigin::Core,
                    by_entity_id: None,
                    source: essences::fight_breakdown::CombatSource::Other,
                })
                .unwrap();
        }
        assert_eq!(
            sink.events[0].combat_origin(),
            Some(CombatEventOrigin::Core)
        );
    }

    /// B1 laundering fix. `CastEffectFromEvent` answers `carries_origin()` from
    /// its boxed caller, but `set_origin` is a no-op on it — so a guard keyed on
    /// the predicate let a producer push one wrapping a Core caller and have it
    /// come out Core. The guard is keyed on the stamp actually landing.
    #[test]
    fn modifier_scope_refuses_to_launder_through_cast_effect_from_event() {
        let core_caller = OverlordEvent::Damage {
            by_entity_id: None,
            entity_id: uuid::Uuid::from_u128(1),
            damage: 1,
            damage_data: Default::default(),
            origin: CombatEventOrigin::Core,
            source: essences::fight_breakdown::CombatSource::Other,
        };
        let laundered = OverlordEvent::CastEffectFromEvent {
            entity_id: uuid::Uuid::from_u128(1),
            effect_id: uuid::Uuid::from_u128(2),
            caller_event: Box::new(core_caller),
        };
        assert!(
            laundered.carries_origin(),
            "the predicate is satisfied — that is exactly the trap"
        );

        let mut sink = NativeSink::default();
        {
            let mut modifier_sink = OriginSink::proc(&mut sink);
            assert!(modifier_sink.push_event(laundered).is_err());
        }
        assert!(sink.events.is_empty());
    }

    /// A carrier passes through a producer scope marked, so the work it goes on
    /// to do inherits the mark instead of resetting to Core.
    #[test]
    fn modifier_scope_marks_carriers_too() {
        let mut sink = NativeSink::default();
        {
            let mut modifier_sink = OriginSink::proc(&mut sink);
            modifier_sink
                .push_event(OverlordEvent::CastEffect {
                    entity_id: uuid::Uuid::from_u128(1),
                    effect_id: uuid::Uuid::from_u128(2),
                    origin: CombatEventOrigin::Core,
                })
                .unwrap();
        }
        assert_eq!(
            sink.events[0].carried_origin(),
            Some(CombatEventOrigin::Proc)
        );
        assert_eq!(
            sink.events[0].combat_origin(),
            None,
            "a carrier is not trigger surface"
        );
    }

    fn lookups_with_speed(speed: f64) -> ContentLookups {
        let speed_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("speed".to_string(), speed_id);
        lookups.attribute_base_value.insert(speed_id, speed);
        lookups
    }

    fn advance_lookups(ability_id: uuid::Uuid, range: i64) -> ContentLookups {
        let mut lookups = lookups_with_speed(10000.0);
        lookups
            .ability_target_type
            .insert(ability_id, "Enemy".to_string());
        lookups.ability_range.insert(ability_id, range);
        lookups
    }

    /// A real ability template present in the test game config (range 1). Used as
    /// the hero's own attack in `try_cast` tests, where the caster's `ability_id`
    /// must resolve through `config.ability_template`.
    fn hero_ability_id() -> Uuid {
        Uuid::parse_str("da6c582b-7364-40bd-9b2d-946d8e20eaac").unwrap()
    }

    /// Drive `try_cast` for `caster` (using the hero's real config ability) with
    /// `others` in the fight, returning the emitted sink. The two-phase gate reads
    /// the enemies' `abilities` + `lookups.ability_range`, so tests set those up.
    fn run_try_cast(caster: &Entity, others: Vec<Entity>, lookups: &ContentLookups) -> NativeSink {
        use rand::SeedableRng;
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut entities = vec![caster.clone()];
        entities.extend(others);
        let fight = ActiveFight {
            entities,
            ..Default::default()
        };
        let mut sink = NativeSink::default();
        try_cast(
            &mut sink,
            &rng,
            &config,
            lookups,
            &fight,
            caster,
            hero_ability_id(),
            1,
        )
        .unwrap();
        sink
    }

    /// Slot model: a caster with no target in range emits NOTHING — no cast,
    /// no run. The formation promotion step (logic::fighting) is the only
    /// approach mechanism left.
    #[test]
    fn try_cast_without_target_in_range_stands_still() {
        let mut hero = entity_at(EntityTeam::Ally, 1);
        hero.hp = 100;
        let mut enemy = entity_at(EntityTeam::Enemy, 5);
        enemy.hp = 100;
        let lookups = advance_lookups(hero_ability_id(), 1);
        let sink = run_try_cast(&hero, vec![enemy], &lookups);
        assert!(sink.casts.is_empty(), "out of range: no cast and no run");
        assert!(sink.events.is_empty(), "out of range: no events either");
    }

    fn living_enemy_at(x: i64) -> Entity {
        let mut e = entity_at(EntityTeam::Enemy, x);
        e.hp = 100;
        e
    }

    fn promo_fight(player_x: i64, enemies: Vec<Entity>) -> ActiveFight {
        let mut player = entity_at(EntityTeam::Ally, player_x);
        player.hp = 100;
        let player_id = player.id;
        let mut entities = vec![player];
        entities.extend(enemies);
        ActiveFight {
            player_id,
            entities,
            ..Default::default()
        }
    }

    /// §2.2: near column empty, far column held → the formation steps forward.
    #[test]
    fn promotion_fires_when_near_empty_and_far_occupied() {
        let fight = promo_fight(5, vec![living_enemy_at(5 + RANGED_COL_OFFSET)]);
        assert!(slot_promotion_needed(&fight));
    }

    /// A living enemy standing in — or running into — the near column keeps
    /// the formation planted.
    #[test]
    fn promotion_blocked_by_near_column() {
        let fight = promo_fight(5, vec![living_enemy_at(5 + MELEE_COL_OFFSET)]);
        assert!(!slot_promotion_needed(&fight));

        let mut runner = living_enemy_at(9);
        runner.move_target = Some(Coordinates {
            x: 5 + MELEE_COL_OFFSET,
            y: 1,
        });
        let fight = promo_fight(5, vec![runner, living_enemy_at(5 + RANGED_COL_OFFSET)]);
        assert!(!slot_promotion_needed(&fight));
    }

    /// Units still parked behind the screen edge (their exit cooldown pending)
    /// must not drag the formation toward the spawn edge.
    #[test]
    fn promotion_ignores_parked_spawns_beyond_far_column() {
        let fight = promo_fight(5, vec![living_enemy_at(5 + RANGED_COL_OFFSET + 4)]);
        assert!(!slot_promotion_needed(&fight));
    }

    /// No step while the player is missing, dead or already running — and dead
    /// enemies hold no column.
    #[test]
    fn promotion_requires_standing_living_player() {
        let mut fight = promo_fight(5, vec![living_enemy_at(5 + RANGED_COL_OFFSET)]);
        fight.entities[0].move_target = Some(Coordinates { x: 6, y: 1 });
        assert!(!slot_promotion_needed(&fight));

        fight.entities[0].move_target = None;
        fight.entities[0].hp = 0;
        assert!(!slot_promotion_needed(&fight));

        let mut corpse = living_enemy_at(5 + RANGED_COL_OFFSET);
        corpse.hp = 0;
        let fight = promo_fight(5, vec![corpse]);
        assert!(!slot_promotion_needed(&fight));
    }

    /// Diagonal sidesteps must take √2× a straight step — duration comes from
    /// the euclidean distance, not |Δx| (which made lane changes visibly fast).
    #[test]
    fn entity_run_duration_uses_euclidean_distance() {
        let entity = entity_at(EntityTeam::Ally, 0); // at (0, 1)
        let lookups = lookups_with_speed(10000.0);

        let mut sink = NativeSink::default();
        entity_run(&mut sink, &lookups, &entity, Coordinates { x: 1, y: 2 }).unwrap();

        assert_eq!(sink.casts.len(), 1);
        assert_eq!(
            sink.casts[0].run_duration_ticks,
            Some(707),
            "√2 cells × 500ms, floored"
        );
    }

    /// TC-2: `get_entity_stat` floors the `.mod` multiplier at
    /// `MIN_STAT_MOD_MULT`, so a stacking debuff (weakness on attack, protection
    /// on received_damage) can't drive a stat to ≤0 (zero-damage / unkillable).
    #[test]
    fn get_entity_stat_mod_floor_prevents_zeroing() {
        let attack_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("attack".to_string(), attack_id);
        lookups.attribute_base_value.insert(attack_id, 600.0);

        // −500% `.mod` would be ×(−4) pre-floor → must clamp to ×0.05.
        let mut weak = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        weak.attributes.add("attack.mod", -50_000);
        let v = get_entity_stat(&lookups, &weak, "attack");
        assert!(v > 0.0, "floored stat must stay positive, got {v}");
        assert!(
            (v - 600.0 * balance::MIN_STAT_MOD_MULT).abs() < 1e-9,
            "attack.mod must floor at MIN_STAT_MOD_MULT (×0.05), got {v}"
        );

        // No mod → unaffected (base, mult 1.0).
        let neutral = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        assert!((get_entity_stat(&lookups, &neutral, "attack") - 600.0).abs() < 1e-9);
    }

    /// TC-6 / CM-2 (entropy rev): dodge resolves through the ENTROPY
    /// accumulator — at evasion == K (dodge prob 0.5) exactly every 2nd
    /// incoming touch is dodged, deterministically, no streaks; and the DR
    /// asymptote still holds (any finite evasion keeps letting SOME touches
    /// through at the exact DR rate).
    #[test]
    fn touch_enemy_dodge_entropy_rate_and_asymptote() {
        let k = balance::tuning().k_dodge;
        let mut target = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        target.attributes.add("evasion", k as i64);

        // Seed the accumulator at 0 → add 5000/check: touched, dodged, touched…
        let rng = GameRng::from_values(vec![0.0]);
        let touched: Vec<bool> = (0..10)
            .map(|_| touch_enemy(&rng, &ContentLookups::default(), &target))
            .collect();
        let dodges = touched.iter().filter(|t| !**t).count();
        assert_eq!(dodges, 5, "dodge 0.5 ⇒ exactly every 2nd touch dodged");
        for w in touched.windows(2) {
            assert_ne!(w[0], w[1], "50% entropy dodge must strictly alternate");
        }

        // Asymptote < 100%: enormous evasion (dodge ≈ 0.99985) still lets
        // touches through at the exact DR rate — never a permanent immunity.
        let mut glass = Entity {
            id: uuid::Uuid::new_v4(),
            ..Default::default()
        };
        glass.attributes.add("evasion", 10_000_000);
        let rng = GameRng::from_values(vec![0.0]);
        let touched_count = (0..10_000)
            .filter(|_| touch_enemy(&rng, &ContentLookups::default(), &glass))
            .count();
        assert!(
            touched_count >= 1,
            "even huge evasion must not become full immunity (got {touched_count} touches)"
        );
    }

    /// Regression guard for the "fight works but no damage" break AND the v2
    /// anti-unkillable floor. `received_damage` is a ×10000 multiplier whose base
    /// value (10000 == 100% taken) lives in `attribute_base_value`:
    /// * base lookup ENTIRELY ABSENT (content-extraction regression) →
    ///   `damage_entity` returns `None` (loud: fights visibly stall) — preserved
    ///   so the missing-base bug still surfaces.
    /// * base PRESENT but mitigated to ≤0 by a huge negative `received_damage.mod`
    ///   (e.g. stacked `protection`) → floored at `MIN_RECEIVED_DAMAGE_K`, so the
    ///   entity stays killable (`godmode` is the only true invuln).
    #[test]
    fn damage_requires_received_damage_base_value() {
        use rand::SeedableRng;

        let target = Entity {
            id: uuid::Uuid::new_v4(),
            hp: 1000,
            max_hp: 1000,
            ..Default::default()
        };
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));

        // Missing base: empty lookups → no received_damage base → all damage
        // cancelled (the loud content-regression guard).
        let empty = ContentLookups::default();
        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &empty,
            None,
            &target,
            100.0,
            CustomEventData::default(),
            CombatSource::Other,
        )
        .unwrap();
        assert!(
            res.is_none(),
            "missing attribute_base_value cancels all damage (loud no-damage guard)"
        );

        // Base present (10000 = 100% taken, sourced from config) → a hit lands.
        let rd_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("received_damage".to_string(), rd_id);
        lookups.attribute_base_value.insert(rd_id, 10000.0);

        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &lookups,
            None,
            &target,
            100.0,
            CustomEventData::default(),
            CombatSource::Other,
        )
        .unwrap();
        assert!(
            res.is_some_and(|d| d > 0),
            "with received_damage base populated, a hit must deal damage"
        );

        // Anti-unkillable (TC-1): base present but stacked `protection` drives
        // `received_damage.mod` hugely negative — the entity must STILL take
        // positive damage (floored), never become invulnerable.
        let mut tank = target.clone();
        tank.attributes.add("received_damage.mod", -50_000); // −500% ⇒ ≤0 pre-floor
        let mut sink = NativeSink::default();
        let res = damage_entity(
            &mut sink,
            &rng,
            &lookups,
            None,
            &tank,
            100.0,
            CustomEventData::default(),
            CombatSource::Other,
        )
        .unwrap();
        assert!(
            res.is_some_and(|d| d > 0),
            "stacked protection must not make an entity unkillable (received_damage floor)"
        );
    }

    /// Builds a minimal single-wave / single-spawn [`WaveFightData`] with the
    /// given reference `power`, runs [`spawn_wave`], and returns the `hp`
    /// attribute of the emitted `SpawnEntity` (the enemy that wave produced).
    fn spawn_wave_enemy_hp(power: Option<f64>, is_dungeon: bool) -> i64 {
        use rand::SeedableRng;

        let enemy_id = uuid::Uuid::new_v4();
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![vec![WaveSpawn {
                entity_id: enemy_id.to_string(),
                delay: Some(0.0),
                position: Some(Coordinates { x: 3, y: 3 }),
                cooldown_seconds: None,
                row: None,
            }]],
            time: 1.0,
            power,
            stream_active_count: None,
            reward_mob_budget: None,
            summon_wave_at_hp_fraction: None,
            enemy_damage_mult: None,
        };

        // `spawn_wave` reads only `current_wave` + `entities` off the
        // fight; the fight kind is supplied separately via the `fight_type` arg.
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };

        let config = configs::tests_game_config::generate_game_config_for_tests();
        let mut lookups = ContentLookups::default();
        lookups
            .fight_template_is_dungeon
            .insert(fight.fight_id, is_dungeon);
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();

        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            fight_data.power.unwrap_or(0.0),
            1,
            "CampaignFight",
        )
        .unwrap();

        let spawn = sink
            .events
            .iter()
            .find_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes),
                _ => None,
            })
            .expect("spawn_wave must emit a SpawnEntity for the current wave");

        // `hp == 0` is stored as an absent key by `EntityAttributes::add`.
        spawn.0.get("hp").copied().unwrap_or(0)
    }

    /// Regression guard for the "wave enemies spawn with 0 HP" bug: the typed
    /// config extraction dropped the per-fight reference `power`, so both
    /// `spawn_wave` call sites passed `base_power = 0.0`. With `base_power
    /// = 0`, `eff = 0` → `player_dps = 0` → `mob_hp_norm = 0` → every spawned
    /// enemy got `hp: 0` (instant death, no HP bar).
    ///
    /// Since BAL-037 the campaign path takes its power from the signed chapter
    /// curve and ignores `base_power` entirely, so the bug is only reproducible
    /// on the DUNGEON path, which still spawns from the authored per-difficulty
    /// `FightTemplate.power`.
    #[test]
    fn spawn_wave_enemy_hp_requires_nonzero_base_power() {
        // The bug: base_power 0 → zero player DPS → zero-HP dungeon enemies.
        assert_eq!(
            spawn_wave_enemy_hp(Some(0.0), true),
            0,
            "base_power 0 must reproduce the zero-HP bug on the dungeon path"
        );

        // Fixed: a non-zero reference power yields a positive enemy HP / HP bar.
        assert!(
            spawn_wave_enemy_hp(Some(100.0), true) > 0,
            "a non-zero reference power must produce wave enemies with positive HP"
        );

        // Campaign waves read the signed BAL-037 curve, so a dropped reference
        // power can no longer zero their HP.
        assert!(
            spawn_wave_enemy_hp(Some(0.0), false) > 0,
            "campaign waves take power from the signed chapter curve, not base_power"
        );
    }

    /// Shared harness: one wave of `(cooldown_seconds, legacy delay)` spawns of
    /// equal power; returns the normalized `attack` attr of the first emitted
    /// spawn (equal powers → identical attack on every spawn).
    fn spawn_wave_attack_for(spawns: &[(Option<f64>, Option<f64>)]) -> i64 {
        spawn_wave_attack_capped(spawns, None)
    }

    fn spawn_wave_attack_capped(spawns: &[(Option<f64>, Option<f64>)], cap: Option<u64>) -> i64 {
        use rand::SeedableRng;
        let enemy_id = uuid::Uuid::from_u128(7);
        let wave: Vec<WaveSpawn> = spawns
            .iter()
            .map(|(cooldown, delay)| WaveSpawn {
                entity_id: enemy_id.to_string(),
                delay: *delay,
                position: Some(Coordinates { x: 3, y: 1 }),
                cooldown_seconds: *cooldown,
                row: None,
            })
            .collect();
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![wave],
            time: 30.0,
            power: Some(100.0),
            stream_active_count: cap,
            reward_mob_budget: None,
            summon_wave_at_hp_fraction: None,
            enemy_damage_mult: None,
        };
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();
        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            100.0,
            1,
            "CampaignFight",
        )
        .unwrap();
        sink.events
            .iter()
            .find_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes.0.get("attack").copied().unwrap_or(0)),
                _ => None,
            })
            .expect("spawn_wave must emit spawns")
    }

    /// The balance mini-sim budgets mob damage from the SLOT timeline: a mob
    /// arriving later overlaps less with its wave (less total incoming damage
    /// against the same survivability budget), so the normalization
    /// compensates with a higher per-hit attack. With the legacy `delay`
    /// input this was invisible — cooldown-staggered waves were budgeted as
    /// if fully overlapped (the "waves easier than budgeted" drift).
    #[test]
    fn mini_sim_budgets_from_exit_cooldowns_not_legacy_delay() {
        let overlapped = spawn_wave_attack_for(&[(None, None), (None, None)]);
        let staggered = spawn_wave_attack_for(&[(None, None), (Some(10.0), None)]);
        assert!(overlapped > 0);
        assert!(
            staggered > overlapped,
            "a cooldown-staggered wave overlaps less and must normalize to a \
             higher attack (staggered {staggered} vs overlapped {overlapped})"
        );

        // The legacy `delay` field no longer moves the budget at all.
        let legacy_delay_only = spawn_wave_attack_for(&[(None, None), (None, Some(10.0))]);
        assert_eq!(
            legacy_delay_only, overlapped,
            "legacy `delay` must be dead as a balance input"
        );
    }

    /// Returns the `wave_share` attribute of every emitted `SpawnEntity` for a
    /// single wave of `n` identical spawns under `reward_mob_budget = budget`.
    fn spawn_wave_shares(budget: Option<u64>, n: usize) -> Vec<Option<i64>> {
        use rand::SeedableRng;
        let enemy_id = uuid::Uuid::from_u128(13);
        let wave: Vec<WaveSpawn> = (0..n)
            .map(|_| WaveSpawn {
                entity_id: enemy_id.to_string(),
                delay: Some(0.0),
                position: Some(Coordinates { x: 3, y: 1 }),
                cooldown_seconds: None,
                row: None,
            })
            .collect();
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![wave],
            time: 30.0,
            power: Some(100.0),
            stream_active_count: None,
            reward_mob_budget: budget,
            summon_wave_at_hp_fraction: None,
            enemy_damage_mult: None,
        };
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();
        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            100.0,
            1,
            "CampaignFight",
        )
        .unwrap();
        sink.events
            .iter()
            .filter_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes.0.get("wave_share").copied()),
                _ => None,
            })
            .collect()
    }

    /// §2: `spawn_wave` stamps `wave_share = reward_mob_budget / total mob count`
    /// (per-10000) on EVERY mob, so per-kill drops / pet-ult charge / counters
    /// stay count-invariant. Absent budget ⇒ no attribute (legacy bit-identical).
    #[test]
    fn spawn_wave_stamps_wave_share_per_mob() {
        // 4 mobs on field paying out as if 2 ⇒ share 0.5 ⇒ 5000 per-10000, on all.
        let shares = spawn_wave_shares(Some(2), 4);
        assert_eq!(shares.len(), 4);
        assert!(
            shares.iter().all(|s| *s == Some(5000)),
            "each mob must carry wave_share 5000, got {shares:?}"
        );

        // Budget == count ⇒ share 1.0 ⇒ 10000.
        let unit = spawn_wave_shares(Some(3), 3);
        assert!(unit.iter().all(|s| *s == Some(10000)), "got {unit:?}");

        // Legacy content (no budget) ⇒ NO wave_share attribute (bit-identical).
        let legacy = spawn_wave_shares(None, 4);
        assert_eq!(legacy.len(), 4);
        assert!(
            legacy.iter().all(|s| s.is_none()),
            "legacy content must not stamp wave_share, got {legacy:?}"
        );
    }

    /// §2 consumer 3: scaling the counter proc probability by the attacker's
    /// wave_share keeps the TOTAL counter rate per fight count-invariant — 3×
    /// more incoming hits, each at 1/3 the proc chance, yields the same number
    /// of counters as the single-mob baseline. Legacy (scale 1.0) is unchanged.
    #[test]
    fn wave_share_makes_counter_proc_count_invariant() {
        use rand::SeedableRng;
        let lookups = ContentLookups::default();
        let counter_entity = || {
            let mut e = essences::entity::Entity::default();
            e.attributes.add("counterattack_chance", 2000); // 20% (permyriad)
            e
        };

        // Baseline: 1 mob ⇒ 90 incoming hits at full share.
        let base = counter_entity();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(1));
        let base_procs = (0..90)
            .filter(|_| entropy_throw(&rng, &lookups, &base, "counterattack_chance", 0.0, 1.0))
            .count() as i64;

        // Feature: 3 weak mobs ⇒ 270 incoming hits, each scaled by share 1/3.
        let weak = counter_entity();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(1));
        let weak_procs = (0..270)
            .filter(|_| {
                entropy_throw(
                    &rng,
                    &lookups,
                    &weak,
                    "counterattack_chance",
                    0.0,
                    1.0 / 3.0,
                )
            })
            .count() as i64;

        assert!(
            (base_procs - weak_procs).abs() <= 2,
            "counter procs must stay count-invariant: base {base_procs} vs 3x-weak {weak_procs}"
        );
    }

    /// Arrival math mirrors `handle_spawn_entity`'s exit scheduling: exits are
    /// floored (wave-1 floor here = 2000), the min-cooldown group rushes
    /// (4 cells × 200ms), the rest walk (× 500ms), and the run itself delays
    /// the first hit.
    #[test]
    fn slot_arrival_matches_exit_scheduling() {
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let fs = &config.fight_settings;
        // Opening group under the floor: exits AT the floor, rush run only.
        assert_eq!(slot_arrival_delay_seconds(fs, 0, 0, 2000), 0.8);
        // Opening group with a shared cooldown above the floor: remainder + rush.
        assert_eq!(slot_arrival_delay_seconds(fs, 3000, 3000, 1150), 2.65);
        // A later echelon below the floor still walks in right at the floor.
        assert_eq!(slot_arrival_delay_seconds(fs, 500, 0, 2000), 2.0);
        // A later echelon above the floor: its remainder + walk run.
        assert_eq!(slot_arrival_delay_seconds(fs, 10_000, 0, 2000), 10.0);
    }

    /// The gate plan keeps the first `cap` exits (by cooldown, ties by config
    /// order) on timers and queues the rest 1-based in the same order. No cap
    /// or cap ≥ N ⇒ all timers.
    #[test]
    fn wave_exit_gate_plan_caps_by_cooldown_order() {
        let mk = |cd: Option<f64>| WaveSpawn {
            entity_id: "e".into(),
            delay: None,
            position: None,
            cooldown_seconds: cd,
            row: None,
        };
        let wave = vec![mk(Some(1.0)), mk(None), mk(Some(0.5)), mk(None)];

        assert_eq!(wave_exit_gate_plan(&wave, None), vec![None; 4]);
        assert_eq!(wave_exit_gate_plan(&wave, Some(4)), vec![None; 4]);
        assert_eq!(wave_exit_gate_plan(&wave, Some(9)), vec![None; 4]);

        // cap 2: exit order is idx1(0ms), idx3(0ms), idx2(500ms), idx0(1000ms)
        // → timers {1, 3}; gated: idx2 = queue 1, idx0 = queue 2.
        assert_eq!(
            wave_exit_gate_plan(&wave, Some(2)),
            vec![Some(2), None, Some(1), None]
        );
    }

    /// Spawns beyond the cap are stamped `exit_gated` (queue position) and get
    /// NEITHER an exit timer NOR the rush marker; the timer group is unchanged.
    #[test]
    fn spawn_stamps_death_gated_exits_beyond_cap() {
        use rand::SeedableRng;
        let enemy_id = uuid::Uuid::new_v4();
        let mk = |cd: Option<f64>| WaveSpawn {
            entity_id: enemy_id.to_string(),
            delay: None,
            position: Some(Coordinates { x: 3, y: 1 }),
            cooldown_seconds: cd,
            row: Some(1),
        };
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![vec![mk(None), mk(Some(2.5)), mk(Some(5.0))]],
            time: 30.0,
            power: Some(100.0),
            stream_active_count: Some(1),
            reward_mob_budget: None,
            summon_wave_at_hp_fraction: None,
            enemy_damage_mult: None,
        };
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();
        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            100.0,
            1,
            "CampaignFight",
        )
        .unwrap();

        let attrs: Vec<_> = sink
            .events
            .iter()
            .filter_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    entity_attributes, ..
                } => Some(entity_attributes.clone()),
                _ => None,
            })
            .collect();
        assert_eq!(attrs.len(), 3);

        // Timer group (cap 1 = the min-cooldown spawn): rush, no gate.
        assert!(attrs[0].0.contains_key("entrance_rush"));
        assert!(!attrs[0].0.contains_key("exit_gated"));

        // Gated: queue positions in cooldown order, no timer, no rush.
        assert_eq!(attrs[1].0.get("exit_gated").copied(), Some(1));
        assert_eq!(attrs[2].0.get("exit_gated").copied(), Some(2));
        for a in &attrs[1..] {
            assert!(!a.0.contains_key("exit_cooldown_ms"));
            assert!(!a.0.contains_key("entrance_rush"));
        }
    }

    /// The mini-sim models the death gate as the closed loop it is: a capped
    /// wave arrives serially (each kill releases the next), overlapping less
    /// than the same wave uncapped → higher normalized attack. A cap that
    /// never binds is budget-identical to no cap.
    #[test]
    fn mini_sim_models_death_gated_releases() {
        let overlapped =
            spawn_wave_attack_capped(&[(None, None), (None, None), (None, None)], None);
        let capped = spawn_wave_attack_capped(&[(None, None), (None, None), (None, None)], Some(1));
        let cap_unbound =
            spawn_wave_attack_capped(&[(None, None), (None, None), (None, None)], Some(3));
        assert!(overlapped > 0);
        assert!(
            capped > overlapped,
            "a death-gated wave overlaps less and must normalize to a higher \
             attack (capped {capped} vs overlapped {overlapped})"
        );
        assert_eq!(
            cap_unbound, overlapped,
            "a cap that never binds must be budget-identical to no cap"
        );
    }

    /// Slot director (§2.6): every spawn carries `exit_cooldown_ms`
    /// (= cooldown_seconds × 1000); ONLY the wave's min-cooldown group is
    /// marked `entrance_rush`; nobody sleeps — the |Δx| range gate replaces
    /// the wake machinery. Slots: unknown templates count as melee (near
    /// column), the row comes from the migrated field, and the spawn parks
    /// entrance-offset cells beyond the slot.
    #[test]
    fn spawn_sets_exit_cooldown_rush_and_slots() {
        use rand::SeedableRng;

        let enemy_id = uuid::Uuid::new_v4();
        let mk = |cooldown: Option<f64>, row: i64| WaveSpawn {
            entity_id: enemy_id.to_string(),
            delay: Some(0.0),
            position: Some(Coordinates { x: 3, y: 3 }),
            cooldown_seconds: cooldown,
            row: Some(row),
        };
        let fight_data = WaveFightData {
            entities: vec![WaveEntityPower {
                entity_id: Some(enemy_id.to_string()),
                power: Some(1.0),
            }],
            waves: vec![vec![mk(None, 0), mk(Some(2.5), 2)]],
            time: 1.0,
            power: Some(100.0),
            stream_active_count: None,
            reward_mob_budget: None,
            summon_wave_at_hp_fraction: None,
            enemy_damage_mult: None,
        };
        let fight = ActiveFight {
            current_wave: 1,
            ..Default::default()
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let mut sink = NativeSink::default();
        spawn_wave(
            &mut sink,
            &rng,
            &config,
            &lookups,
            &fight,
            &fight_data,
            100.0,
            1,
            "CampaignFight",
        )
        .unwrap();

        let spawns: Vec<_> = sink
            .events
            .iter()
            .filter_map(|ev| match ev {
                OverlordEvent::SpawnEntity {
                    position,
                    entity_attributes,
                    ..
                } => Some((position.clone(), entity_attributes.clone())),
                _ => None,
            })
            .collect();
        assert_eq!(spawns.len(), 2);

        // No player entity in the fight → anchor x = 0; unknown template →
        // melee column (+1); entrance offset 4 → spawn x = 5, y = row.
        assert_eq!(spawns[0].0, Coordinates { x: 5, y: 0 });
        assert_eq!(spawns[1].0, Coordinates { x: 5, y: 2 });

        // A zero attr is never materialized (EntityAttributes::add drops
        // zeros) — absent IS the zero cooldown, mirroring the config rule.
        assert_eq!(spawns[0].1.0.get("exit_cooldown_ms").copied(), None);
        assert_eq!(spawns[1].1.0.get("exit_cooldown_ms").copied(), Some(2500));
        assert!(spawns[0].1.0.contains_key("entrance_rush"));
        assert!(!spawns[1].1.0.contains_key("entrance_rush"));
        for (_, attrs) in &spawns {
            assert!(
                !attrs.0.contains_key("wake_up_delay"),
                "slot model spawns never sleep"
            );
        }
    }

    /// The row plan spreads a stacked opening group across the column's rows
    /// in exit order (authored row → middle → top → bottom rotation via
    /// least-occupancy), leaves an unstacked wave untouched, and never
    /// re-rows gated spawns (their row is picked live at release).
    #[test]
    fn wave_row_plan_spreads_stacked_opening_rows() {
        let mk = |row: i64| WaveSpawn {
            entity_id: uuid::Uuid::nil().to_string(),
            delay: None,
            position: None,
            cooldown_seconds: None,
            row: Some(row),
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();

        // Five mobs all authored onto the middle tile → 2/2/1 spread:
        // 1 (authored), 0, 2, back to 1, back to 0.
        let wave: Vec<_> = (0..5).map(|_| mk(1)).collect();
        let plan = wave_row_plan(&wave, &[None; 5], &config, &lookups, &[], 0, false);
        assert_eq!(plan, vec![1, 0, 2, 1, 0]);

        // Already-distinct rows stay authored.
        let wave = vec![mk(0), mk(2)];
        let plan = wave_row_plan(&wave, &[None; 2], &config, &lookups, &[], 0, false);
        assert_eq!(plan, vec![0, 2]);

        // A lone spawn (boss) never moves off its authored row.
        let wave = vec![mk(1)];
        assert_eq!(
            wave_row_plan(&wave, &[None], &config, &lookups, &[], 0, false),
            vec![1]
        );

        // Gated spawns keep the authored row; only the two active ones spread.
        let wave: Vec<_> = (0..4).map(|_| mk(1)).collect();
        let gate = vec![None, None, Some(1), Some(2)];
        let plan = wave_row_plan(&wave, &gate, &config, &lookups, &[], 0, false);
        assert_eq!(plan, vec![1, 0, 1, 1]);
    }

    /// A summon wave flanks the summoner: reinforcements take the top and
    /// bottom rows first and the middle last, and never land on a living
    /// enemy's tile while a freer row exists (live cells seed the occupancy).
    #[test]
    fn summon_wave_flanks_top_and_bottom_first() {
        let mk = |row: i64| WaveSpawn {
            entity_id: uuid::Uuid::nil().to_string(),
            delay: None,
            position: None,
            cooldown_seconds: None,
            row: Some(row),
        };
        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let anchor = 7;
        // The summoner boss stands mid-row of the melee column.
        let boss = [(anchor + MELEE_COL_OFFSET, 1)];

        // Two summoned creeps (authored 0 and 1, like the shipped slime pair)
        // flank top and bottom — the middle (the boss's tile) stays clear.
        let wave = vec![mk(0), mk(1)];
        let plan = wave_row_plan(&wave, &[None; 2], &config, &lookups, &boss, anchor, true);
        assert_eq!(plan, vec![0, 2]);

        // Boss standing on the TOP row: first creep skips it (bottom), the
        // second takes the now-least-occupied middle.
        let boss_top = [(anchor + MELEE_COL_OFFSET, 0)];
        let plan = wave_row_plan(
            &wave, &[None; 2], &config, &lookups, &boss_top, anchor, true,
        );
        assert_eq!(plan, vec![2, 1]);
    }

    /// A death-released mob lands on the least-occupied row of its own column,
    /// counting standers, runners, and pending park-column arrivals; ties keep
    /// the authored row. Parked still-gated queue mates never count.
    #[test]
    fn gated_release_row_targets_the_empty_tile() {
        let offset = 4;
        let park_x = 5; // battle column x = 1
        let row_enemy = |x: i64, y: i64| {
            let mut e = living_enemy_at(x);
            e.coordinates.y = y;
            e
        };
        let mut released = row_enemy(park_x, 1);
        released.attributes.add("exit_gated", 1);
        let released_id = released.id;

        // Rows 0 and 1 held, row 2 free → land on 2.
        let fight = promo_fight(0, vec![released.clone(), row_enemy(1, 0), row_enemy(1, 1)]);
        assert_eq!(gated_release_row(&fight, released_id, offset), 2);

        // Authored row free → tie resolves to it, not the middle.
        let fight = promo_fight(0, vec![released.clone(), row_enemy(1, 0), row_enemy(1, 2)]);
        assert_eq!(gated_release_row(&fight, released_id, offset), 1);

        // A runner heading to (1, 1) occupies its DESTINATION row; a parked
        // queue mate (still gated) at the same park column does not count.
        let mut runner = row_enemy(9, 0);
        runner.move_target = Some(Coordinates { x: 1, y: 1 });
        let mut queued = row_enemy(park_x, 0);
        queued.attributes.add("exit_gated", 2);
        let fight = promo_fight(0, vec![released.clone(), runner, queued]);
        assert_eq!(gated_release_row(&fight, released_id, offset), 0);

        // A same-tick earlier release still parked (gate cleared, park y set)
        // counts on its landing row: rows 0+1 taken → 2.
        let earlier = row_enemy(park_x, 0);
        let fight = promo_fight(0, vec![released, earlier, row_enemy(1, 1)]);
        assert_eq!(gated_release_row(&fight, released_id, offset), 2);
    }

    /// Drive `init_fight` for a lone player entity and collect the emitted
    /// `attack.mod` deltas.
    fn init_fight_attack_mod_deltas(
        is_dungeon: bool,
        is_bossfight: bool,
        dungeon_talent_level: Option<i64>,
        boss_talent_level: Option<i64>,
        existing_attack_mod: i64,
    ) -> Vec<i64> {
        let fight_template_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .fight_template_is_dungeon
            .insert(fight_template_id, is_dungeon);
        lookups
            .fight_template_is_bossfight
            .insert(fight_template_id, is_bossfight);

        let mut player = entity_at(EntityTeam::Ally, 0);
        player.attributes.add("attack.mod", existing_attack_mod);

        let fight = ActiveFight {
            player_id: player.id,
            entities: vec![player.clone()],
            ..Default::default()
        };

        let mut state = crate::state::OverlordState::default();
        if let Some(level) = dungeon_talent_level {
            state
                .character_state
                .talent_levels
                .0
                .insert(Uuid::parse_str(DUNGEON_TALENT_ID).unwrap(), level);
        }
        if let Some(level) = boss_talent_level {
            state
                .character_state
                .talent_levels
                .0
                .insert(Uuid::parse_str(BOSS_TALENT_ID).unwrap(), level);
        }

        let mut sink = NativeSink::default();
        init_fight(&mut sink, &lookups, &fight, &state, fight_template_id).unwrap();

        sink.events
            .iter()
            .filter_map(|e| match e {
                OverlordEvent::EntityIncrAttribute {
                    entity_id,
                    attribute,
                    delta,
                } if *entity_id == player.id && attribute == "attack.mod" => Some(*delta),
                _ => None,
            })
            .collect()
    }

    /// The dungeon/boss talent attack bonus is +200/talent-level ADDED to the
    /// entity's existing `attack.mod` (class levels, Strength talent). A
    /// set-to-target write would emit `200·level − existing` and wipe those
    /// sources for the fight.
    #[test]
    fn init_fight_talent_attack_mod_adds_on_top_of_existing_sources() {
        // Dungeon talent 3 on top of an existing +3000 (e.g. class levels).
        assert_eq!(
            init_fight_attack_mod_deltas(true, false, Some(3), None, 3000),
            vec![600]
        );
        // Boss talent alone behaves the same.
        assert_eq!(
            init_fight_attack_mod_deltas(false, true, None, Some(2), 3000),
            vec![400]
        );
        // A dungeon bossfight stacks both talents in a single increment.
        assert_eq!(
            init_fight_attack_mod_deltas(true, true, Some(3), Some(2), 3000),
            vec![1000]
        );
        // No talents → no attack.mod events at all.
        assert_eq!(
            init_fight_attack_mod_deltas(true, true, None, None, 3000),
            Vec::<i64>::new()
        );
    }

    // -----------------------------------------------------------------------
    // Effect Stone consumption sites (B2).
    //
    // A trigger fire arms these two attributes on the player; the fight
    // primitives are what spend them, because "the NEXT attack" is only
    // knowable here. Both sites read `&Entity` and consume through the sink, in
    // the same style as the shield pool.
    // -----------------------------------------------------------------------

    /// Drives `attack` `swings` times against ONE caster snapshot and ONE sink,
    /// which is exactly the shape of a multi-target dispatch (`cone_strike`,
    /// Rewind, War Cry, Holy Nova, the projectile band all call `run_attack` in
    /// a loop over `band_targets` inside a single dispatch).
    fn aoe_dispatch(bonus_permyriad: i64, swings: usize) -> (Vec<i64>, Vec<OverlordEvent>) {
        use rand::SeedableRng;

        let lookups = damaging_lookups();
        let mut caster = entity_at(EntityTeam::Ally, 1);
        caster.hp = 100;
        caster.max_hp = 100;
        caster.attributes.add("attack", 1_000);
        if bonus_permyriad != 0 {
            caster
                .attributes
                .add(crate::mechanics::stones::NEXT_ATTACK_BONUS, bonus_permyriad);
            // v0.2: the bonus is charge-based (`EF-C05` arms one charge,
            // `EF-R06` three, `EF-E07` five), so arming a magnitude alone is
            // not an armed bonus any more.
            caster
                .attributes
                .add(crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES, 1);
        }

        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(7));
        let mut sink = NativeSink::default();
        let mut dealt = Vec::new();
        for i in 0..swings {
            let mut target = entity_at(EntityTeam::Enemy, 2 + i as i64);
            target.hp = 1_000_000;
            target.max_hp = 1_000_000;
            dealt.push(
                attack(
                    &mut sink,
                    &rng,
                    &lookups,
                    &mut NoopEffectCb,
                    caster.id,
                    &caster,
                    &target,
                    &AttackParams {
                        is_crit: Some(false),
                        ..AttackParams::default_power()
                    },
                    CombatSource::Other,
                )
                .unwrap()
                .expect("every swing must land"),
            );
        }
        (dealt, sink.events)
    }

    /// The design is "следующая атака +20%" — ONE attack. A multi-target
    /// ability calls `attack` once per target against the same `&Entity`
    /// snapshot inside one dispatch, so without the per-dispatch claim the read
    /// would boost the whole cone and emit one consume per target, driving the
    /// attribute to −4000 and silently swallowing the next two arms.
    #[test]
    fn a_next_attack_bonus_boosts_only_the_first_swing_of_an_aoe_dispatch() {
        let (plain, _) = aoe_dispatch(0, 3);
        let (boosted, events) = aoe_dispatch(2_000, 3);

        assert!(
            (boosted[0] as f64 - plain[0] as f64 * 1.2).abs() <= 1.0,
            "the first target takes the +20%: {} -> {}",
            plain[0],
            boosted[0]
        );
        assert_eq!(
            &boosted[1..],
            &plain[1..],
            "every later target of the same cast must be unboosted"
        );

        let consumed: Vec<i64> = events
            .iter()
            .filter_map(|event| match event {
                OverlordEvent::EntityIncrAttribute {
                    attribute, delta, ..
                } if attribute == crate::mechanics::stones::NEXT_ATTACK_BONUS => Some(*delta),
                _ => None,
            })
            .collect();
        assert_eq!(
            consumed,
            vec![-2_000],
            "exactly one consume per dispatch — never one per target"
        );
    }

    /// The claim belongs to the dispatch, not to the scope: a producer running
    /// inside one may not mint itself a second copy of the same one-shot.
    #[test]
    fn a_producer_scope_cannot_reclaim_the_dispatchs_one_shot() {
        let mut sink = NativeSink::default();
        assert_eq!(
            sink.claim_once(OnceSlot::DamageBonus, 2_000),
            2_000,
            "the first claim wins"
        );
        assert_eq!(
            OriginSink::proc(&mut sink).claim_once(OnceSlot::DamageBonus, 2_000),
            0,
            "a Proc scope inside the same dispatch must find it already spent"
        );
        assert_eq!(sink.claim_once(OnceSlot::DamageBonus, 2_000), 0);

        // A fresh dispatch gets a fresh budget.
        let mut next = NativeSink::default();
        assert_eq!(next.claim_once(OnceSlot::DamageBonus, 2_000), 2_000);
    }

    /// The budgets are independent. One shared latch meant a swing that claimed
    /// the crit chance handed the damage bonus a silent zero — a player with
    /// both `EF-C06` and `EF-C05` armed lost the one they armed second.
    #[test]
    fn the_one_shot_budgets_do_not_take_each_others_latch() {
        let mut sink = NativeSink::default();
        assert_eq!(sink.claim_once(OnceSlot::CritChance, 1_500), 1_500);
        assert_eq!(
            sink.claim_once(OnceSlot::DamageBonus, 2_000),
            2_000,
            "the crit claim must not have spent the damage budget"
        );
        assert_eq!(
            sink.claim_once(OnceSlot::LawArm, 3_000),
            3_000,
            "nor the law arm's"
        );
        assert_eq!(
            sink.claim_once(OnceSlot::LawThisArm, 4_000),
            4_000,
            "nor the this-strike arm's — `RL-01` and `RL-02` can be armed together"
        );

        // Each is still one-shot in its own right.
        assert_eq!(sink.claim_once(OnceSlot::CritChance, 1_500), 0);
        assert_eq!(sink.claim_once(OnceSlot::DamageBonus, 2_000), 0);
        assert_eq!(sink.claim_once(OnceSlot::LawArm, 3_000), 0);
        assert_eq!(sink.claim_once(OnceSlot::LawThisArm, 4_000), 0);
    }

    /// Lookups with a `received_damage` base, so `damage_entity` actually lands
    /// a hit instead of taking the loud missing-base path.
    fn damaging_lookups() -> ContentLookups {
        let rd_id = uuid::Uuid::new_v4();
        let mut lookups = ContentLookups::default();
        lookups
            .attribute_by_code
            .insert("received_damage".to_string(), rd_id);
        lookups.attribute_base_value.insert(rd_id, 10000.0);
        lookups
    }

    /// One attack from a caster carrying `bonus_permyriad` of armed stone bonus.
    /// Returns the damage dealt plus every event the swing emitted.
    fn attack_with_armed_bonus(bonus_permyriad: i64) -> (Option<i64>, Vec<OverlordEvent>) {
        use rand::SeedableRng;

        let lookups = damaging_lookups();
        let mut caster = entity_at(EntityTeam::Ally, 1);
        caster.hp = 100;
        caster.max_hp = 100;
        caster.attributes.add("attack", 1_000);
        if bonus_permyriad != 0 {
            caster
                .attributes
                .add(crate::mechanics::stones::NEXT_ATTACK_BONUS, bonus_permyriad);
            // v0.2: the bonus is charge-based (`EF-C05` arms one charge,
            // `EF-R06` three, `EF-E07` five), so arming a magnitude alone is
            // not an armed bonus any more.
            caster
                .attributes
                .add(crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES, 1);
        }
        let mut target = entity_at(EntityTeam::Enemy, 2);
        target.hp = 1_000_000;
        target.max_hp = 1_000_000;

        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(7));
        let mut sink = NativeSink::default();
        let dealt = attack(
            &mut sink,
            &rng,
            &lookups,
            &mut NoopEffectCb,
            caster.id,
            &caster,
            &target,
            &AttackParams {
                // Crit forced off: the bonus must be measurable against a fixed
                // baseline, not against a coin flip.
                is_crit: Some(false),
                ..AttackParams::default_power()
            },
            CombatSource::Other,
        )
        .unwrap();
        (dealt, sink.events)
    }

    /// The armed bonus scales the swing and is spent by it — exactly once.
    #[test]
    fn a_next_attack_bonus_scales_the_swing_and_is_consumed() {
        let (plain, plain_events) = attack_with_armed_bonus(0);
        let (boosted, boosted_events) = attack_with_armed_bonus(2_000);

        let plain = plain.expect("the baseline swing must land");
        let boosted = boosted.expect("the boosted swing must land");
        assert!(
            (boosted as f64 - plain as f64 * 1.2).abs() <= 1.0,
            "+20% armed must deal ~20% more: {plain} -> {boosted}"
        );

        let consumed: Vec<i64> = boosted_events
            .iter()
            .filter_map(|event| match event {
                OverlordEvent::EntityIncrAttribute {
                    attribute, delta, ..
                } if attribute == crate::mechanics::stones::NEXT_ATTACK_BONUS => Some(*delta),
                _ => None,
            })
            .collect();
        assert_eq!(
            consumed,
            vec![-2_000],
            "the armed bonus must be spent by the swing that used it"
        );
        assert!(
            !plain_events.iter().any(|event| matches!(
                event,
                OverlordEvent::EntityIncrAttribute { attribute, .. }
                    if attribute == crate::mechanics::stones::NEXT_ATTACK_BONUS
            )),
            "an unarmed swing must not touch the bonus at all"
        );
    }

    /// All three one-shot damage budgets on ONE swing: the stone's charge-gated
    /// bonus, the law's family arm, and the law's this-strike arm.
    ///
    /// They are owned by two subsystems and each has its own latch and its own
    /// sink decrement, but they meet here and are summed into a single
    /// `dmg_mod`. Every other test arms exactly one of the three, which is how a
    /// shared `claim_once` latch — where the crit claim silently swallowed the
    /// damage claim — stayed invisible.
    #[test]
    fn the_three_armed_budgets_stack_on_one_swing_and_each_is_spent_once() {
        use rand::SeedableRng;

        let swing = |arm_all: bool| {
            let lookups = damaging_lookups();
            let mut caster = entity_at(EntityTeam::Ally, 1);
            caster.hp = 100;
            caster.max_hp = 100;
            caster.attributes.add("attack", 1_000);
            if arm_all {
                // Stone side: magnitude + charge, +20%.
                caster
                    .attributes
                    .add(crate::mechanics::stones::NEXT_ATTACK_BONUS, 2_000);
                caster
                    .attributes
                    .add(crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES, 1);
                // Law side: the Basic-family arm (+30%) and the this-strike arm
                // (+50%). The cast kind is what selects the family arm.
                crate::logic::combat_facts::record_cast_kind(
                    &mut caster,
                    crate::logic::combat_facts::CastKind::Basic,
                );
                caster
                    .attributes
                    .add(crate::mechanics::cores::ARM_BASIC, 3_000);
                caster
                    .attributes
                    .add(crate::mechanics::cores::ARM_THIS, 5_000);
            }
            let mut target = entity_at(EntityTeam::Enemy, 2);
            target.hp = 1_000_000;
            target.max_hp = 1_000_000;

            let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(7));
            let mut sink = NativeSink::default();
            let dealt = attack(
                &mut sink,
                &rng,
                &lookups,
                &mut NoopEffectCb,
                caster.id,
                &caster,
                &target,
                &AttackParams {
                    is_crit: Some(false),
                    ..AttackParams::default_power()
                },
                CombatSource::Other,
            )
            .unwrap();
            (dealt, sink.events)
        };

        let (plain, _) = swing(false);
        let (boosted, events) = swing(true);
        let plain = plain.expect("the baseline swing must land");
        let boosted = boosted.expect("the boosted swing must land");

        // 20% + 30% + 50% is one +100% multiplier, not three multiplications.
        assert!(
            (boosted as f64 - plain as f64 * 2.0).abs() <= 1.0,
            "the three arms must sum into one multiplier: {plain} -> {boosted}"
        );

        let spent = |key: &str| -> Vec<i64> {
            events
                .iter()
                .filter_map(|event| match event {
                    OverlordEvent::EntityIncrAttribute {
                        attribute, delta, ..
                    } if attribute == key => Some(*delta),
                    _ => None,
                })
                .collect()
        };
        assert_eq!(
            spent(crate::mechanics::stones::NEXT_ATTACK_BONUS),
            vec![-2_000],
            "the stone bonus is spent once"
        );
        assert_eq!(
            spent(crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES),
            vec![-1],
            "and gives up exactly one charge"
        );
        assert_eq!(
            spent(crate::mechanics::cores::ARM_BASIC),
            vec![-3_000],
            "the law's family arm is spent once"
        );
        assert_eq!(
            spent(crate::mechanics::cores::ARM_THIS),
            vec![-5_000],
            "and so is the this-strike arm"
        );
    }

    /// The family arm the cast kind does NOT select stays untouched, even while
    /// the other two budgets are being spent around it.
    #[test]
    fn a_basic_swing_leaves_the_skill_arm_alone_while_spending_the_others() {
        use rand::SeedableRng;

        let lookups = damaging_lookups();
        let mut caster = entity_at(EntityTeam::Ally, 1);
        caster.hp = 100;
        caster.max_hp = 100;
        caster.attributes.add("attack", 1_000);
        crate::logic::combat_facts::record_cast_kind(
            &mut caster,
            crate::logic::combat_facts::CastKind::Basic,
        );
        caster
            .attributes
            .add(crate::mechanics::cores::ARM_BASIC, 3_000);
        caster
            .attributes
            .add(crate::mechanics::cores::ARM_SKILL, 9_000);

        let mut target = entity_at(EntityTeam::Enemy, 2);
        target.hp = 1_000_000;
        target.max_hp = 1_000_000;

        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(7));
        let mut sink = NativeSink::default();
        attack(
            &mut sink,
            &rng,
            &lookups,
            &mut NoopEffectCb,
            caster.id,
            &caster,
            &target,
            &AttackParams {
                is_crit: Some(false),
                ..AttackParams::default_power()
            },
            CombatSource::Other,
        )
        .unwrap();

        assert!(
            sink.events.iter().any(|event| matches!(
                event,
                OverlordEvent::EntityIncrAttribute { attribute, delta, .. }
                    if attribute == crate::mechanics::cores::ARM_BASIC && *delta == -3_000
            )),
            "the Basic arm belongs to this swing"
        );
        assert!(
            !sink.events.iter().any(|event| matches!(
                event,
                OverlordEvent::EntityIncrAttribute { attribute, .. }
                    if attribute == crate::mechanics::cores::ARM_SKILL
            )),
            "the Skill arm must be untouched by a Basic Attack"
        );
    }

    /// A magnitude with no charge behind it is NOT an armed bonus.
    ///
    /// This is the gate every producer writing into the shared key has to
    /// satisfy — including `logic::laws`, which lends its own arm in here for
    /// the duration of one cast. Writing the magnitude alone leaves the swing
    /// unchanged and the value stranded, which is exactly how the law-side
    /// `NextAttackDamageBonus` went silently dead when the key became
    /// charge-gated.
    #[test]
    fn a_magnitude_without_a_charge_does_not_scale_the_swing() {
        use rand::SeedableRng;

        let swing = |with_charge: bool| {
            let lookups = damaging_lookups();
            let mut caster = entity_at(EntityTeam::Ally, 1);
            caster.hp = 100;
            caster.max_hp = 100;
            caster.attributes.add("attack", 1_000);
            caster
                .attributes
                .add(crate::mechanics::stones::NEXT_ATTACK_BONUS, 5_000);
            if with_charge {
                caster
                    .attributes
                    .add(crate::mechanics::stones::NEXT_ATTACK_BONUS_CHARGES, 1);
            }
            let mut target = entity_at(EntityTeam::Enemy, 2);
            target.hp = 1_000_000;
            target.max_hp = 1_000_000;

            let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(7));
            let mut sink = NativeSink::default();
            attack(
                &mut sink,
                &rng,
                &lookups,
                &mut NoopEffectCb,
                caster.id,
                &caster,
                &target,
                &AttackParams {
                    is_crit: Some(false),
                    ..AttackParams::default_power()
                },
                CombatSource::Other,
            )
            .unwrap()
            .expect("the swing must land")
        };

        let (plain, _) = attack_with_armed_bonus(0);
        let plain = plain.expect("the baseline swing must land");
        assert_eq!(
            swing(false),
            plain,
            "a magnitude with no charge must leave the swing at its baseline"
        );
        assert!(
            (swing(true) as f64 - plain as f64 * 1.5).abs() <= 1.0,
            "the same magnitude WITH a charge must be worth +50%"
        );
    }

    /// Extra swings from `NextAttackDoubleHit`.
    ///
    /// They are queued onto THIS cast rather than re-dispatched as another
    /// `StartCastAbility`: that path goes through `push_start_cast_replacing`'s
    /// `max(existing, now + cooldown)` and would push the entity's next natural
    /// swing back instead of adding one. And they are queued `Proc`, so the
    /// damage they land later cannot re-enter the trigger that granted them.
    #[test]
    fn an_armed_extra_swing_is_added_to_this_cast_as_proc_and_is_consumed() {
        use rand::SeedableRng;

        let config = configs::tests_game_config::generate_game_config_for_tests();
        let lookups = ContentLookups::default();
        let rng = GameRng::new(rand::rngs::StdRng::seed_from_u64(0));
        let ability = Ability {
            template_id: hero_ability_id(),
            level: 1,
            shards_amount: 0,
        };
        let mut target = entity_at(EntityTeam::Enemy, 2);
        target.hp = 100;

        let swing_origins = |caster: &Entity| -> (Vec<CombatEventOrigin>, Vec<i64>) {
            let mut sink = NativeSink::default();
            cast(
                &mut sink,
                &rng,
                &config,
                &lookups,
                caster,
                &ability,
                std::slice::from_ref(&target),
                1,
            )
            .unwrap();
            let consumed = sink
                .events
                .iter()
                .filter_map(|event| match event {
                    OverlordEvent::EntityIncrAttribute {
                        attribute, delta, ..
                    } if attribute == crate::mechanics::stones::NEXT_ATTACK_EXTRA_HITS => {
                        Some(*delta)
                    }
                    _ => None,
                })
                .collect();
            (sink.casts.iter().map(|c| c.origin).collect(), consumed)
        };

        let mut plain = entity_at(EntityTeam::Ally, 1);
        plain.hp = 100;
        let (origins, consumed) = swing_origins(&plain);
        assert_eq!(
            origins,
            vec![CombatEventOrigin::Core],
            "an unarmed cast is one Core swing, exactly as before"
        );
        assert!(consumed.is_empty(), "nothing to consume");

        let mut armed = plain.clone();
        armed
            .attributes
            .add(crate::mechanics::stones::NEXT_ATTACK_EXTRA_HITS, 1);
        let (origins, consumed) = swing_origins(&armed);
        assert_eq!(
            origins,
            vec![CombatEventOrigin::Core, CombatEventOrigin::Proc],
            "the natural swing stays Core and the granted one is Proc"
        );
        assert_eq!(
            consumed,
            vec![-1],
            "the arm is spent by the cast that used it"
        );
    }

    /// `armor.mod` composes exactly like `hp.mod` / `attack.mod`: permyriad
    /// (`+1000 == +10%`), multiplicative over `(armor + armor.bonus)`, and
    /// floored at `MIN_STAT_MOD_MULT`. The point of the attribute is that a
    /// "+10% defense" grant SCALES with the wearer's armor rating instead of
    /// adding a fixed number of points — so the same `armor.mod` is worth ten
    /// times as much on a character with ten times the rating.
    #[test]
    fn armor_mod_composes_as_a_percentage_of_the_armor_rating() {
        let lookups = ContentLookups::default();
        let armored = |rating: i64, armor_mod: i64, bonus: i64| {
            let mut entity = Entity {
                id: uuid::Uuid::new_v4(),
                ..Default::default()
            };
            entity.attributes.add("armor", rating);
            entity.attributes.add("armor.bonus", bonus);
            entity.attributes.add("armor.mod", armor_mod);
            get_entity_stat(&lookups, &entity, "armor")
        };

        // Stone Skin's shape: +1000 permyriad == +10% of the rating.
        assert!((armored(2_000, 1_000, 0) - 2_200.0).abs() < 1e-9);
        // Enhanced: +1600 == +16%.
        assert!((armored(2_000, 1_600, 0) - 2_320.0).abs() < 1e-9);
        // It SCALES: ten times the rating, ten times the gain (200 -> 2000),
        // which is precisely what a flat +1000 armor rating could not do.
        assert!((armored(20_000, 1_000, 0) - 22_000.0).abs() < 1e-9);
        // `.bonus` is additive first, then the multiplier — same order as hp.
        assert!((armored(2_000, 1_000, 500) - 2_750.0).abs() < 1e-9);
        // Floor: a −500% stack clamps to MIN_STAT_MOD_MULT rather than going ≤0.
        let floored = armored(2_000, -50_000, 0);
        assert!(
            (floored - 2_000.0 * balance::MIN_STAT_MOD_MULT).abs() < 1e-9,
            "armor.mod must floor at MIN_STAT_MOD_MULT (×0.05), got {floored}"
        );
        // No mod → unchanged.
        assert!((armored(2_000, 0, 0) - 2_000.0).abs() < 1e-9);
    }
}