overlord_event_system/logic/

stones.rs

//! Trigger/Effect Stones — inventory handlers and the combat runtime.
//!
//! The inventory half (insert, remove, upgrade, quick equip, upgrade all, the
//! temporary drop grant) is a set of pure state transitions; the monolith
//! persists whatever they produce.
//!
//! The combat half is [`OverlordLogic::apply_stone_triggers`], the single entry
//! point of the whole mechanic. It hangs off `apply_success_hooks`, so it runs
//! for every successfully handled event in both dispatch paths — the pure
//! dispatch and the monolith's merged arms — instead of being wired per event
//! arm, where a new arm would silently miss it.
//!
//! # The rules the design rests on
//!
//! * **One cooldown for the whole build.** A Core event checks every socketed
//!   trigger at once, every match fires and adds its tier weight to the gauge,
//!   then [`mech::GLOBAL_COOLDOWN`] is written once. Firing comes in bursts of
//!   up to five rather than five independent trickles.
//! * **A condition met on cooldown is lost, and its counter restarts.** No bank
//!   and no queue: [`mech::reset_sequence_counters`] takes the sequence back to
//!   zero, so "every 5th attack" starts counting from one again.
//! * **Nothing an effect produces is Core.** A trigger reacts to
//!   [`OverlordEvent::is_core_combat_event`] only, and every event this module
//!   emits carries [`CombatEventOrigin::Proc`], which makes "effect grants a
//!   crit → crit trigger → effect grants a crit" inexpressible. A real Basic
//!   Attack stays Core even when an effect changed its magnitude, because
//!   effects add derived damage beside the real hit instead of rewriting it.
//! * **No effect shortens the cooldown.** It is written *before* the effect
//!   loop dispatches anything, which holds under re-entrancy too.
//!
//! Its arithmetic and its per-fight bookkeeping keys live in
//! [`crate::mechanics::stones`].

use essences::abilities::AbilityId;
use essences::combat_origin::CombatEventOrigin;
use essences::entity::{Entity, EntityId};
use essences::fight_breakdown::CombatSource;
use essences::flip::FlipProgressSource;
use essences::items::ItemType;
use essences::stones::{
    StoneError, StoneKind, StoneSocketKey, StoneSocketSlot, StoneTemplateId, StoneTier,
    UpgradedStonesMap,
};

use configs::artifacts::ArtifactStoneRule;
use configs::stones::{EffectStoneAction, TriggerCondition, TriggerStoneTemplate};
use strum::IntoEnumIterator;

use crate::game_config_helpers::GameConfigLookup;
use crate::logic::combat_facts::{CastKind, CombatFact};
use crate::mechanics::{
    artifacts as art, balance, fight::get_entity_stat, pet_facets as pet_mech, stones as mech,
};
use crate::{
    EventHandleResult,
    event::OverlordEvent,
    logic::{EventPluginized, handler::OverlordLogic},
    state::OverlordState,
};

/// The Core facts a Trigger Stone may react to (design v0.2 §5).
///
/// Every variant is a Core combat outcome of the player's
/// (`is_core_combat_event`). There is deliberately no heartbeat variant any
/// more: v0.2's catalog has no interval trigger, and `FightProgress` is
/// reachable from a Proc cascade, so admitting it would have been the one hole
/// in the anti-loop boundary.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum CoreOutcome {
    /// The player swung a real Basic Attack — the swing, not the damage it goes
    /// on to deal. §4 makes Basic Attack the most frequent Core event in the
    /// game, which is why no common trigger reacts to a single one of them.
    BasicAttack,
    /// The player cast an original Skill. `slot` is its index among the equipped
    /// Skills; `None` for a cast that is not one of them (a pet ult, a summon's
    /// kit) — such a cast still counts as a Skill Cast, but cannot take part in
    /// the conditions that ask *which* Skill.
    SkillCast { slot: Option<usize> },
    /// A Core hit of the player's landed on an enemy. `damage` is what it took
    /// and `target` who took it — the Effect Stones that derive from the hit
    /// itself (`EF-E08`) need both.
    HitLanded {
        crit: bool,
        damage: u64,
        target: EntityId,
    },
    /// A Core hit landed on the player. `share` is what it took in permyriad of
    /// Max HP, `survived` whether the hero was still alive afterwards.
    HitTaken { share: i64, survived: bool },
    /// The player dodged a Core hit.
    Dodged,
    /// A Core action killed an enemy.
    Defeat,
    /// BAL-027 `Battle Rhythm`: the interval trigger in one socket came due
    /// while a living hostile exists. Carries the template so only that
    /// trigger matches — the uniqueness rule guarantees one socket per
    /// template.
    IntervalElapsed { template: StoneTemplateId },
}

/// Facts that only the event just handled can establish — memory alone cannot,
/// because each is about a transition rather than a total.
#[derive(Clone, Copy, Debug, Default)]
struct Facts {
    /// A Core crit landed straight after a Core non-crit (`TR-R06`).
    crit_after_non_crit: bool,
    /// This Basic Attack is the first one since an original Skill (`TR-C06`).
    first_attack_after_skill: bool,
    /// This original Skill is not the one cast before it (`TR-R05`).
    skill_differs: bool,
    /// This cast was the last equipped Skill still unused this phase (`TR-L03`).
    spellbook_completed: bool,
    /// This cast closed a Skill → Basic Attack → other Skill run (`TR-L04`).
    perfect_sequence: bool,
    /// Targets this Skill has reached so far inside its own tick (`TR-R04`).
    skill_targets: i64,
    /// HP as permyriad of Max HP, before and after this event.
    hp_before: i64,
    hp_now: i64,
}

impl Facts {
    /// Folds the facts of a later outcome of the SAME event into these.
    ///
    /// A killing blow is one event with two outcomes, and each is folded into
    /// the memory in turn; a condition must see everything the event
    /// established, not just whatever the last fold happened to report. The
    /// booleans are claims about the event, so any of them holding is enough.
    /// `hp_before` stays at the watermark from before the event and `hp_now`
    /// tracks the latest reading.
    fn absorb(&mut self, later: Facts) {
        self.crit_after_non_crit |= later.crit_after_non_crit;
        self.first_attack_after_skill |= later.first_attack_after_skill;
        self.skill_differs |= later.skill_differs;
        self.spellbook_completed |= later.spellbook_completed;
        self.perfect_sequence |= later.perfect_sequence;
        self.skill_targets = self.skill_targets.max(later.skill_targets);
        self.hp_now = later.hp_now;
    }
}

/// One extra Effect Stone an artifact rule runs alongside a trigger's own fire.
///
/// Everything an Aspect rule adds to a fire lands here — the paired hidden
/// effect of `HA-01` / `HA-04` / `HA-05`, the next slot's hidden effect of
/// `HA-03`, the repeat of `FA-03`, the departing effect of `FA-04`. One shape
/// for all of them, so a rule can never invent a second way to run an effect and
/// slip past the provenance and gauge guards that
/// [`OverlordLogic::run_stone_effect`] enforces.
#[derive(Clone, Copy)]
struct ExtraFire {
    template_id: StoneTemplateId,
    level: i64,
    /// Share of full strength, `0.3` for `30%`.
    share: f64,
}

/// One trigger that passed its condition, collected before anything is spent so
/// the whole build resolves against one consistent world.
struct Fire {
    /// Equipment slot whose Trigger socket held the fired stone — carried out
    /// to the client as [`OverlordEvent::StoneTriggerFired`], since the combat
    /// outcomes a fire produces are deliberately anonymous.
    item_type: ItemType,
    trigger_template: StoneTemplateId,
    /// The effect socketed on the side that is active *at this fire*, plus its
    /// upgrade level. `None` when that side's socket is empty — the trigger
    /// still fires (and still feeds the gauge), it just has nothing to run.
    effect: Option<(StoneTemplateId, i64)>,
    /// Strength multiplier the artifact's Visible-Aspect stone applies to this
    /// fire (`VA-01 Crescendo` / `VA-04 Opening Five`). `1.0` with no artifact —
    /// which is what makes "a player without an artifact plays exactly as
    /// before" an identity rather than a measurement.
    strength: f64,
    /// Extra effects the Hidden- and Flip-Aspect rules attach to this fire, in
    /// the order they were decided. Empty with no artifact.
    extras: Vec<ExtraFire>,
    /// The paired hidden effect `HA-05 Catch-Up` runs *instead*, and only when
    /// the active effect turns out to be wholly inapplicable. Kept apart from
    /// [`Fire::extras`] because that verdict is only known after the active
    /// effect has been attempted.
    catch_up: Option<ExtraFire>,
}

/// Turns the shared reading of a dispatched event
/// ([`crate::logic::combat_facts`]) into the trigger surface. Empty when the
/// event established nothing a trigger may react to.
///
/// What "hit", "kill" and "dodge" mean is not decided here — the laws runtime
/// reads the same facts, and the two definitions used to drift. What is left is
/// the stone-specific presentation: a hit taken as a share of Max HP, and which
/// equipped slot a Skill came from.
///
/// A killing blow establishes two outcomes at once — the hit landed AND the
/// enemy died — so this returns a list. They arrive in the order they happened,
/// and every socketed trigger is checked against all of them: the design's "a
/// Core event checks every trigger at once", applied to an event that settled
/// more than one thing.
fn classify(
    game_config: &configs::game_config::GameConfig,
    event: &OverlordEvent,
    player: &Entity,
    fight: &essences::fighting::ActiveFight,
    equipped_skills: &[AbilityId],
) -> Vec<CoreOutcome> {
    let classified = crate::logic::combat_facts::classify(game_config, fight, event);
    crate::logic::combat_facts::facts_for(&classified, player.id)
        .map(|fact| match fact {
            CombatFact::Cast {
                kind: CastKind::Basic,
                ..
            } => CoreOutcome::BasicAttack,
            CombatFact::Cast {
                kind: CastKind::Skill,
                ability_id,
            } => CoreOutcome::SkillCast {
                slot: equipped_skills.iter().position(|id| *id == ability_id),
            },
            CombatFact::HitLanded {
                crit,
                damage,
                victim,
            } => CoreOutcome::HitLanded {
                crit,
                damage,
                target: victim,
            },
            // The hook runs after the handler, so the hit is already off the
            // hero's HP: `survived` is simply whether anything is left.
            CombatFact::HitTaken { damage } => {
                let max_hp = player.max_hp.max(1) as i128;
                CoreOutcome::HitTaken {
                    share: (damage as i128 * 10_000 / max_hp) as i64,
                    survived: player.hp > 0,
                }
            }
            CombatFact::Dodged => CoreOutcome::Dodged,
            CombatFact::Kill { .. } => CoreOutcome::Defeat,
        })
        .collect()
}

/// Folds one Core outcome into the player's per-fight trigger memory and
/// reports what that fold established.
///
/// Runs **before** any condition is evaluated and regardless of whether anything
/// will fire, because the memory is the trigger's history, not a by-product of
/// firing: a crit streak that only advanced on fires could never reach three,
/// and a Basic Attack that fired nothing would still have to break the run.
fn advance_memory(
    player: &mut Entity,
    outcome: CoreOutcome,
    now: u64,
    equipped_skills: usize,
    perfect_sequence_window: u64,
) -> Facts {
    let mut facts = Facts {
        hp_before: mech::hp_low_water(player),
        hp_now: mech::hp_permyriad(player),
        ..Default::default()
    };

    match outcome {
        CoreOutcome::BasicAttack => {
            player.attributes.add(mech::SEQ_BASIC_ATTACK, 1);
            facts.first_attack_after_skill = mech::attr(player, mech::AFTER_SKILL) != 0;
            player.attributes.set(mech::AFTER_SKILL, 0);
            // Perfect Sequence, step two: a Skill opened the run, this is the
            // Basic Attack in the middle of it.
            if mech::attr(player, mech::SEQ_STAGE) == 1 {
                player.attributes.set(mech::SEQ_STAGE, 2);
            }
        }
        CoreOutcome::SkillCast { slot } => {
            player.attributes.add(mech::SEQ_SKILL_CAST, 1);
            player.attributes.add(mech::SKILLS_WITHOUT_DAMAGE, 1);
            player.attributes.set(mech::AFTER_SKILL, 1);

            let key = slot.map_or(0, |slot| slot as i64 + 1);
            // "Differs from the PREVIOUS Skill" needs a previous one: the first
            // cast of a fight changes nothing and must not read as a change.
            let previous = mech::attr(player, mech::LAST_SKILL);
            facts.skill_differs = key != 0 && previous != 0 && key != previous;

            // Wide Cast counts the targets of ONE cast: a multi-target Skill
            // arrives as one `CastAbility` per target inside the cast's own
            // animation window, so the run is "same Skill, still inside it".
            let opened_at = mech::attr(player, mech::CAST_RUN_TICK);
            let same_run = opened_at != 0
                && mech::attr(player, mech::CAST_RUN_SLOT) == key
                && now as i64 - (opened_at - 1) <= mech::CAST_RUN_WINDOW_TICKS;
            facts.skill_targets = if same_run {
                mech::attr(player, mech::CAST_RUN_COUNT) + 1
            } else {
                player.attributes.set(mech::CAST_RUN_TICK, now as i64 + 1);
                1
            };
            player.attributes.set(mech::CAST_RUN_SLOT, key);
            player
                .attributes
                .set(mech::CAST_RUN_COUNT, facts.skill_targets);

            if let Some(slot) = slot {
                player
                    .attributes
                    .set(&mech::skill_last_cast_key(slot), now as i64 + 1);
                // Full Spellbook is a latch: it fires on the cast that completed
                // the book, not on every cast after it.
                let cast_this_phase = (0..equipped_skills)
                    .filter(|index| mech::attr(player, &mech::skill_last_cast_key(*index)) != 0)
                    .count();
                if equipped_skills > 0
                    && cast_this_phase >= equipped_skills
                    && mech::attr(player, mech::SPELLBOOK_DONE) == 0
                {
                    facts.spellbook_completed = true;
                    player.attributes.set(mech::SPELLBOOK_DONE, 1);
                }
            }

            // Perfect Sequence, step three: a *different* Skill closes the run,
            // and only inside the window.
            let stage = mech::attr(player, mech::SEQ_STAGE);
            let opened_at = mech::attr(player, mech::SEQ_STAGE_TICK);
            let opened_with = mech::attr(player, mech::SEQ_STAGE_SKILL);
            let in_window = opened_at != 0
                && now as i64 - (opened_at - 1) <= perfect_sequence_window.max(1) as i64;
            if stage == 2 && in_window && key != 0 && key != opened_with {
                facts.perfect_sequence = true;
            }
            // Either way this Skill opens a fresh run: it is the most recent
            // "Skill" the sequence could be built from.
            player.attributes.set(mech::SEQ_STAGE, 1);
            player.attributes.set(mech::SEQ_STAGE_TICK, now as i64 + 1);
            player.attributes.set(mech::SEQ_STAGE_SKILL, key);
            player.attributes.set(mech::LAST_SKILL, key);
        }
        CoreOutcome::HitLanded { crit, .. } => {
            facts.crit_after_non_crit = crit && mech::attr(player, mech::PREV_HIT_CRIT) == 0;
            player.attributes.set(mech::PREV_HIT_CRIT, i64::from(crit));
            let streak = if crit {
                mech::attr(player, mech::CRIT_STREAK) + 1
            } else {
                0
            };
            player.attributes.set(mech::CRIT_STREAK, streak);
        }
        CoreOutcome::HitTaken { .. } => {
            player.attributes.add(mech::SEQ_HIT_TAKEN, 1);
            // Untouched Casting is about a run of Skills with nothing landing in
            // between, so any Core hit ends it.
            player.attributes.set(mech::SKILLS_WITHOUT_DAMAGE, 0);
            if facts.hp_now < facts.hp_before {
                player.attributes.set(mech::HP_LOW_WATER, facts.hp_now);
            }
        }
        CoreOutcome::Dodged => {
            for index in (1..mech::DODGE_RING).rev() {
                let previous = mech::attr(player, &mech::dodge_tick_key(index - 1));
                player
                    .attributes
                    .set(&mech::dodge_tick_key(index), previous);
            }
            player
                .attributes
                .set(&mech::dodge_tick_key(0), now as i64 + 1);
        }
        CoreOutcome::Defeat => {
            player.attributes.add(mech::SEQ_DEFEAT, 1);
        }
        // BAL-027 `Battle Rhythm`: a clock tick, not a combat act — it leaves
        // every sequence counter and streak untouched.
        CoreOutcome::IntervalElapsed { .. } => {}
    }

    facts
}

/// Whether `template`'s condition is satisfied by this outcome.
///
/// Reads the memory [`advance_memory`] has already folded the event into, so
/// "every 5th attack" sees the count *including* the attack being classified.
///
/// No artifact reaches this function. The v0.1 World Law «Отражение» used to —
/// it made a dodge additionally read as a crit — but that rulebreaker is not in
/// the v0.2 pool (plan §2), and the one law that ships (`ART-03 Halfway Bell`)
/// moves the flip bar rather than reclassifying an outcome. A trigger condition
/// is therefore a property of the Core event alone.
fn condition_met(
    template: &TriggerStoneTemplate,
    outcome: CoreOutcome,
    facts: &Facts,
    player: &Entity,
    now: u64,
) -> bool {
    // First, so no other clause can reach a stone the catalog switched off —
    // `active: false` is how content whose mechanic has not shipped waits.
    if !template.active {
        return false;
    }
    let value = template.condition_value;
    let window = template.condition_window_ticks;
    let threshold = value.saturating_mul(100);

    match (template.condition, outcome) {
        (TriggerCondition::EveryNthBasicAttack, CoreOutcome::BasicAttack) => {
            mech::counter_met(mech::attr(player, mech::SEQ_BASIC_ATTACK), value)
        }
        (TriggerCondition::EveryNthHitTaken, CoreOutcome::HitTaken { .. }) => {
            mech::counter_met(mech::attr(player, mech::SEQ_HIT_TAKEN), value)
        }
        (TriggerCondition::EveryNthSkillCast, CoreOutcome::SkillCast { .. }) => {
            mech::counter_met(mech::attr(player, mech::SEQ_SKILL_CAST), value)
        }
        (TriggerCondition::EveryNthDefeat, CoreOutcome::Defeat) => {
            mech::counter_met(mech::attr(player, mech::SEQ_DEFEAT), value)
        }
        (TriggerCondition::FirstAttackAfterSkill, CoreOutcome::BasicAttack) => {
            facts.first_attack_after_skill
        }
        (TriggerCondition::OnSkillCast, CoreOutcome::SkillCast { .. }) => true,
        (TriggerCondition::OnCrit, CoreOutcome::HitLanded { crit, .. }) => crit,
        (TriggerCondition::OnDefeat, CoreOutcome::Defeat) => true,
        (TriggerCondition::SkillHitsAtLeastTargets, CoreOutcome::SkillCast { .. }) => {
            facts.skill_targets >= value.max(1)
        }
        (TriggerCondition::SkillDiffersFromPrevious, CoreOutcome::SkillCast { .. }) => {
            facts.skill_differs
        }
        (TriggerCondition::CritAfterNonCrit, CoreOutcome::HitLanded { crit, .. }) => {
            crit && facts.crit_after_non_crit
        }
        (TriggerCondition::OnEvasion, CoreOutcome::Dodged) => true,
        // Once per phase for free: the low-water mark only ever falls, so the
        // line can only be crossed downwards once however much the hero heals.
        (TriggerCondition::HpCrossedBelowPercent, CoreOutcome::HitTaken { .. }) => {
            facts.hp_before >= threshold && facts.hp_now < threshold
        }
        (TriggerCondition::OnCritStreak, CoreOutcome::HitLanded { crit, .. }) => {
            crit && mech::crit_streak_met(mech::attr(player, mech::CRIT_STREAK), value)
        }
        (TriggerCondition::DistinctSkillsWithin, CoreOutcome::SkillCast { .. }) => {
            let live = (0..mech::SKILL_SLOTS)
                .map(|index| mech::attr(player, &mech::skill_last_cast_key(index)))
                .filter(|recorded| {
                    *recorded != 0 && now as i64 - (recorded - 1) <= window.max(1) as i64
                })
                .count() as i64;
            live >= value.max(1)
        }
        (TriggerCondition::SurvivedBigHitPercent, CoreOutcome::HitTaken { share, survived }) => {
            survived && share >= threshold
        }
        (TriggerCondition::DodgesWithin, CoreOutcome::Dodged) => {
            let needed = value.max(1) as usize;
            if needed > mech::DODGE_RING {
                return false;
            }
            let oldest = mech::attr(player, &mech::dodge_tick_key(needed - 1));
            oldest != 0 && now as i64 - (oldest - 1) <= window.max(1) as i64
        }
        (TriggerCondition::AllEquippedSkillsCastThisPhase, CoreOutcome::SkillCast { .. }) => {
            facts.spellbook_completed
        }
        (TriggerCondition::SkillAttackSkillWithin, CoreOutcome::SkillCast { .. }) => {
            facts.perfect_sequence
        }
        (TriggerCondition::SkillsWithoutDamageTaken, CoreOutcome::SkillCast { .. }) => {
            mech::counter_met(mech::attr(player, mech::SKILLS_WITHOUT_DAMAGE), value)
        }
        (TriggerCondition::SkillBelowHpPercent, CoreOutcome::SkillCast { .. }) => {
            facts.hp_now > 0 && facts.hp_now < threshold
        }
        // `TR-C03` / `TR-E02`: priced off what the mana gate actually charged
        // (`combat_facts::paid_mana_x100`, x100 like `threshold`), so a stone
        // discount or `Budget Plan` changes the verdict exactly as it changed
        // the bill. A cast that never paid satisfies neither bound.
        (TriggerCondition::SkillManaAtMost, CoreOutcome::SkillCast { .. }) => {
            crate::logic::combat_facts::paid_mana_x100(player).is_some_and(|paid| paid <= threshold)
        }
        (TriggerCondition::SkillManaAtLeast, CoreOutcome::SkillCast { .. }) => {
            crate::logic::combat_facts::paid_mana_x100(player).is_some_and(|paid| paid >= threshold)
        }
        // BAL-027 `Battle Rhythm`: the emission already checked the clock and
        // the living hostile; here only the identity matters.
        (TriggerCondition::OnInterval, CoreOutcome::IntervalElapsed { template: fired }) => {
            fired == template.id
        }
        _ => false,
    }
}

/// The slot after `item_type` in the fixed two-sided slot order, wrapping at the
/// end.
///
/// `HA-03 Cross Relay` is the only caller: "slot `N+1`" needs *an* order, and the
/// one order the whole stone runtime already walks is `ItemType::iter()` filtered
/// to the two-sided slots — the same sequence the flip volley and the shadow
/// round use. A slot that has no sides at all answers with itself, so the rule
/// degrades to «Фоновый голос» rather than panicking on a config that removes
/// every socketed slot but one.
fn next_two_sided_slot(item_type: ItemType) -> ItemType {
    let slots: Vec<ItemType> = ItemType::iter()
        .filter(|t| t.supports_world_side())
        .collect();
    let Some(position) = slots.iter().position(|slot| *slot == item_type) else {
        return item_type;
    };
    slots[(position + 1) % slots.len()]
}

/// Nearest living opponent of `player`, for the effects that need a target.
pub(crate) fn nearest_enemy(entities: &[Entity], player: &Entity) -> Option<EntityId> {
    entities
        .iter()
        .filter(|e| e.team != player.team && e.hp > 0)
        .min_by_key(|e| {
            (e.coordinates.x - player.coordinates.x).abs()
                + (e.coordinates.y - player.coordinates.y).abs()
        })
        .map(|e| e.id)
}

/// Every living opponent, for the effects that hit the whole line.
pub(crate) fn living_enemies(entities: &[Entity], player: &Entity) -> Vec<EntityId> {
    entities
        .iter()
        .filter(|e| e.team != player.team && e.hp > 0)
        .map(|e| e.id)
        .collect()
}

impl OverlordLogic {
    pub fn handle_insert_stone(
        &self,
        template_id: StoneTemplateId,
        item_type: ItemType,
        socket: StoneSocketSlot,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let Some(key) = StoneSocketKey::new(item_type, socket) else {
            tracing::error!("InsertStone: {item_type:?} has no stone sockets");
            return EventHandleResult::fail(state);
        };

        let game_config = self.game_config.get();
        let unlocked = game_config.stones_settings.is_socket_unlocked(
            item_type,
            socket,
            state.character_state.character.current_chapter_level,
        );

        // A template the player already wears elsewhere is refused here
        // (`AlreadySocketed`): one instance per template means one socket.
        if let Err(err) = state
            .character_state
            .stones
            .insert(template_id, key, unlocked)
        {
            tracing::error!("InsertStone refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    pub fn handle_remove_stone(
        &self,
        template_id: StoneTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        // The stone is never taken out of its collection — only its socket
        // assignment is cleared — so there is nothing here that could lose it,
        // and its banked copies come back with it.
        if let Err(err) = state.character_state.stones.remove(template_id) {
            tracing::error!("RemoveStone refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    /// Raises one stone by one level, paid for in raw copies.
    ///
    /// The client names the stone only; the cost and the spend are the
    /// server's, so a UI cannot spend more than the rung asks. The cost comes
    /// from the per-level ladder in `stones_settings.upgrade_ladder`, never a
    /// constant. A level with no rung is refused rather than guessed —
    /// `GameConfig::validate_stones` makes that unreachable in a deployed
    /// config.
    pub fn handle_upgrade_stone(
        &self,
        template_id: StoneTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let settings = &self.game_config.get().stones_settings;
        let Some(stone) = state.character_state.stones.get(template_id) else {
            tracing::error!(
                "UpgradeStone refused: {}",
                StoneError::UnknownStone(template_id)
            );
            return EventHandleResult::fail(state);
        };

        let next_level = stone.level + 1;
        if stone.level >= settings.max_stone_level {
            tracing::error!(
                "UpgradeStone refused: {}",
                StoneError::AlreadyMaxLevel(template_id, settings.max_stone_level)
            );
            return EventHandleResult::fail(state);
        }
        let Some(required) = settings.upgrade_copies_required(next_level) else {
            tracing::error!(
                "UpgradeStone refused: {}",
                StoneError::NoUpgradeStep(next_level)
            );
            return EventHandleResult::fail(state);
        };

        if let Err(err) =
            state
                .character_state
                .stones
                .upgrade(template_id, required, settings.max_stone_level)
        {
            tracing::error!("UpgradeStone refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    /// BAL-024/BAL-025: the guaranteed milestone stones the character should
    /// own at their chapter but does not. Granting the result converges — an
    /// owned template is never listed — so the check is safe to run on every
    /// chapter advance and on connect.
    pub fn missing_milestone_stones(
        game_config: &configs::game_config::GameConfig,
        chapter: i64,
        stones: &essences::stones::StoneInventory,
    ) -> (Vec<StoneTemplateId>, Vec<StoneTemplateId>) {
        let mut trigger_stones = Vec::new();
        let mut effect_stones = Vec::new();
        for grant in &game_config.stones_settings.milestone_grants {
            if grant.chapter > chapter {
                continue;
            }
            for id in &grant.trigger_stones {
                if stones.get(*id).is_none() {
                    trigger_stones.push(*id);
                }
            }
            for id in &grant.effect_stones {
                if stones.get(*id).is_none() {
                    effect_stones.push(*id);
                }
            }
        }
        (trigger_stones, effect_stones)
    }

    /// Banks granted copies in their collections. Kept separate from the grant
    /// roll so the sole writer of the inventory is one function.
    ///
    /// A copy of a template the player already owns raises that stone's
    /// `copies` count; only the first copy of a template creates an instance.
    /// The tier comes from the catalog, so a template missing from config is
    /// skipped and logged rather than banked with a guessed tier.
    pub fn handle_player_new_stones(
        &self,
        trigger_stones: &[StoneTemplateId],
        effect_stones: &[StoneTemplateId],
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let game_config = self.game_config.get();
        for (kind, template_id) in trigger_stones
            .iter()
            .map(|id| (StoneKind::Trigger, *id))
            .chain(effect_stones.iter().map(|id| (StoneKind::Effect, *id)))
        {
            let tier = match kind {
                StoneKind::Trigger => game_config
                    .trigger_stone_template(template_id)
                    .map(|t| t.tier),
                StoneKind::Effect => game_config
                    .effect_stone_template(template_id)
                    .map(|t| t.tier),
            };
            let Some(tier) = tier else {
                tracing::warn!("Granted {kind} stone {template_id} has no catalog entry — skipped");
                continue;
            };
            state.character_state.stones.grant(kind, template_id, tier);
        }
        EventHandleResult::ok(state)
    }

    /// The stone faucet: `rolls` independent draws at
    /// `stones_settings.kill_drop.chance × chance_scale`, split between the two
    /// collections by `kill_drop.trigger_share`.
    ///
    /// It hangs off ENEMY KILLS ([`Self::roll_stone_kill_drop`]). It used to
    /// hang off the item-chest open, which tied the whole faucet to a purchased
    /// channel: a whale opening ~26k chests a day drew two orders of magnitude
    /// more stones than a player who fought for them.
    ///
    /// A copy of a template the player already owns is banked as a copy by the
    /// handler, not as a second instance. Draws from the caller's stream (like
    /// every other handler) rather than the global RNG, so a test can seed the
    /// drop.
    pub fn roll_stone_drop(
        &self,
        rng: &mut rand::rngs::StdRng,
        rolls: i64,
        chance_scale: f64,
    ) -> Option<EventPluginized<OverlordEvent, OverlordState>> {
        let game_config = self.game_config.get();
        let settings = &game_config.stones_settings;
        let chance = settings.kill_drop.chance * chance_scale;
        if chance <= 0.0 {
            return None;
        }

        let mut trigger_stones = Vec::new();
        let mut effect_stones = Vec::new();
        for _ in 0..rolls.max(0) {
            if rand::RngExt::random::<f64>(rng) >= chance {
                continue;
            }
            let kind = settings.dropped_kind(rand::RngExt::random::<f64>(rng));
            let Some(template_id) = pick_stone_template(rng, &game_config, kind) else {
                continue;
            };
            match kind {
                StoneKind::Trigger => trigger_stones.push(template_id),
                StoneKind::Effect => effect_stones.push(template_id),
            }
        }

        if trigger_stones.is_empty() && effect_stones.is_empty() {
            return None;
        }
        Some(EventPluginized::now(OverlordEvent::PlayerNewStones {
            trigger_stones,
            effect_stones,
        }))
    }

    /// One stone roll for one dead enemy, scaled by that mob's `wave_share`.
    ///
    /// The `wave_share` scaling is the same rule the cores currency and the law
    /// copies already follow on this path: an inflated wave is more mobs of less
    /// weight each, and without the scaling it would inflate every per-kill
    /// faucet with it.
    pub fn roll_stone_kill_drop(
        &self,
        rng: &mut rand::rngs::StdRng,
        wave_share: f64,
    ) -> Option<EventPluginized<OverlordEvent, OverlordState>> {
        self.roll_stone_drop(rng, 1, wave_share)
    }

    /// Fills the open, empty sockets of one item with the BEST usable stones
    /// the player is not already wearing.
    ///
    /// Modelled on `FastEquipAbilities` but kept pure: a stone inventory lives
    /// in `character_state`, not a side table, so the whole decision is a state
    /// transition and the same code runs in both dispatch paths.
    ///
    /// "Best" is `Stone::quality` — tier first, then level — with the canonical
    /// catalog order breaking ties. Locked sockets are skipped, occupied sockets
    /// are left alone, stones worn on other gear are never taken, and a socket
    /// with nothing to put in it stays empty without an error.
    pub fn handle_quick_equip_stones(
        &self,
        item_type: ItemType,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        if !item_type.supports_world_side() {
            tracing::error!(
                "QuickEquipStones refused: {}",
                StoneError::SlotHasNoSockets { item_type }
            );
            return EventHandleResult::fail(state);
        }

        let game_config = self.game_config.get();
        let chapter_level = state.character_state.character.current_chapter_level;
        let settings = &game_config.stones_settings;
        let filled = state.character_state.stones.quick_equip(
            item_type,
            &|socket| settings.is_socket_unlocked(item_type, socket, chapter_level),
            &|kind| match kind {
                StoneKind::Trigger => game_config
                    .trigger_stones
                    .iter()
                    .filter(|t| t.active)
                    .map(|t| t.id)
                    .collect(),
                StoneKind::Effect => game_config.effect_stones.iter().map(|t| t.id).collect(),
            },
        );

        tracing::debug!(?item_type, sockets = filled.len(), "QuickEquipStones");
        EventHandleResult::ok(state)
    }

    /// Raises every stone of one catalog that the player can currently afford to
    /// raise, as far as its banked copies reach (design v0.2 §9).
    ///
    /// Modelled on `UpgradeAllAbilities` and named for it — the codebase says
    /// `UpgradeAll*`, and §9 sanctions matching it. Like
    /// [`Self::handle_upgrade_stone`] the cost is the server's business: the
    /// client asks for "everything of this kind", the ladder decides what that
    /// costs, and a stone that cannot pay for its next level is skipped rather
    /// than failing the whole call.
    ///
    /// `kind` comes from which of the two catalogs the caller asked for — the
    /// screen has a Trigger tab and an Effect tab and its button raises the open
    /// one, so the two arrive as separate events.
    pub fn handle_upgrade_all_stones(
        &self,
        kind: StoneKind,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let game_config = self.game_config.get();
        let settings = &game_config.stones_settings;
        let upgraded =
            state
                .character_state
                .stones
                .upgrade_all(kind, settings.max_stone_level, &|level| {
                    settings.upgrade_copies_required(level)
                });

        tracing::debug!(?kind, stones = upgraded.len(), "UpgradeAll*Stones");

        // Nothing rose: stay silent rather than popping an empty result window.
        if upgraded.is_empty() {
            return EventHandleResult::ok(state);
        }

        let mut map = UpgradedStonesMap::default();
        for (template_id, from, to) in upgraded {
            map.insert(template_id, (from, to));
        }

        EventHandleResult::ok_events(
            state,
            vec![EventPluginized::now(OverlordEvent::UpgradedStones {
                upgraded_stones: map,
            })],
        )
    }

    /// Fire every socketed trigger whose condition `event` satisfies: run the
    /// globally active side's effect, feed the flip gauge by the trigger's tier,
    /// then put the whole build on one cooldown.
    ///
    /// Runs from `apply_success_hooks`, after the event's own handler has
    /// mutated the state, so a trigger reacts to the world the hit produced.
    ///
    /// The order inside is load-bearing:
    ///
    /// 1. classify the event — anything non-Core leaves here;
    /// 2. fold it into the trigger memory, whether or not anything will fire;
    /// 3. spend whatever effect state this event consumes — independent of the
    ///    cooldown;
    /// 4. collect the triggers whose condition matched;
    /// 5. if the cooldown is still running, drop them and restart the sequence
    ///    counters;
    /// 6. otherwise write the global cooldown, **then** run the effects.
    ///
    /// Step 6's order makes the hook re-entrancy-safe: an effect can dispatch
    /// work that comes back through here, and it finds the build already spent.
    ///
    /// A build with nothing socketed leaves through the first early return
    /// having touched no state at all.
    pub fn apply_stone_triggers(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
    ) {
        // Cheap gates first: this hook runs on every successfully handled
        // event of the session, most of which are not combat at all.
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        if fight.fight_ended || fight.fight_stopped {
            return;
        }
        // Every character combatant fires their OWN socketed triggers: the
        // local hero, the party ally, and a human PvP opponent. Mobs and arena
        // filler bots carry no CharacterState and are skipped inside.
        let mut combatants = vec![fight.player_id];
        combatants.extend(fight.party_player_id);
        if let Some(pvp) = &state.pvp_state {
            let opponent_id = pvp.opponent_state.id();
            if fight.entities.iter().any(|e| e.id == opponent_id) {
                combatants.push(opponent_id);
            }
        }
        for combatant_id in combatants {
            self.apply_stone_triggers_for(state, events, event, combatant_id);
        }
    }

    /// One combatant's pass of [`Self::apply_stone_triggers`].
    fn apply_stone_triggers_for(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
        combatant_id: EntityId,
    ) {
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        let Some(build) = crate::entities::combatant_character_state(
            &state.character_state,
            &state.party,
            &state.pvp_state,
            fight,
            combatant_id,
        ) else {
            return;
        };
        if build.stones.all().all(|(_, stone)| !stone.is_socketed()) {
            return;
        }
        // Clones, not borrows: the engine below interleaves mutable fight
        // borrows, and the build may live in `state.party` / `state.pvp_state`.
        // Both collections are a handful of stones.
        let stones = build.stones.clone();
        let artifacts = build.artifacts.clone();
        let combatant_class = build.character.class;
        let equipped_abilities = build.equipped_abilities.clone();

        let player_id = combatant_id;
        let Some(player) = fight.entities.iter().find(|e| e.id == player_id) else {
            return;
        };

        let game_config = self.game_config.get();
        let basic_abilities = game_config
            .class(combatant_class)
            .map(|class| class.basic_abilities.clone())
            .unwrap_or_default();
        let equipped_skills: Vec<AbilityId> = equipped_abilities
            .slotted
            .values()
            .map(|ability| ability.template_id)
            .filter(|id| !basic_abilities.contains(id))
            .take(mech::SKILL_SLOTS)
            .collect();

        let mut outcomes = classify(&game_config, event, player, fight, &equipped_skills);

        // BAL-027 `Battle Rhythm`: the interval condition is clock-driven, so
        // it is checked on EVERY handled event (the per-tick `FightProgress`
        // included) rather than classified from combat facts. The due tick per
        // socket is entity state; a first sighting arms it without firing, and
        // a due that elapses advances whether or not the match survives the
        // global cooldown — a burned match is lost, not queued.
        let now = self.fight_clock.now();
        let mut interval_due_updates: Vec<(String, i64)> = Vec::new();
        let hostile_alive = fight
            .entities
            .iter()
            .any(|e| e.team != player.team && e.hp > 0);
        for item_type in ItemType::iter().filter(|t| t.supports_world_side()) {
            let Some(key) = StoneSocketKey::new(item_type, StoneSocketSlot::Trigger) else {
                continue;
            };
            let Some(stone) = stones.socketed(key) else {
                continue;
            };
            let Some(template) = game_config.trigger_stone_template(stone.template_id) else {
                continue;
            };
            if template.condition != TriggerCondition::OnInterval || !template.active {
                continue;
            }
            let interval = template.condition_value.max(1);
            let due_key = mech::interval_due_key(item_type);
            let due = player.attributes.0.get(&due_key).copied().unwrap_or(0);
            if due == 0 {
                interval_due_updates.push((due_key, now as i64 + interval));
                continue;
            }
            if hostile_alive && now as i64 >= due {
                outcomes.push(CoreOutcome::IntervalElapsed {
                    template: template.id,
                });
                interval_due_updates.push((due_key, now as i64 + interval));
            }
        }

        if outcomes.is_empty() {
            // The armed metronome must still be written, or it never starts.
            if !interval_due_updates.is_empty() {
                Self::with_player(state, player_id, |player| {
                    for (key, due) in &interval_due_updates {
                        player.attributes.set(key, *due);
                    }
                });
            }
            return;
        }

        let settings = &game_config.stones_settings;
        // The three Aspect stones that can ride on a trigger fire. All three are
        // `None` for a player with no artifact, and every use below is guarded —
        // so the no-artifact path is byte-for-byte the old one.
        //
        // The Flip socket is read here as well as on `GlobalFlip`: two of its
        // five rules (`FA-03 Warm Start`, `FA-04 Afterimage`) describe what
        // happens on the ordinary procs *after* a flip, not on the flip tick.
        let visible_aspect = crate::logic::artifacts::live_aspect_in_socket(
            &game_config,
            &artifacts,
            essences::artifacts::ArtifactSocketSlot::VisibleAspect,
        );
        let hidden_aspect = crate::logic::artifacts::live_aspect_in_socket(
            &game_config,
            &artifacts,
            essences::artifacts::ArtifactSocketSlot::HiddenAspect,
        );
        let flip_aspect = crate::logic::artifacts::live_aspect_in_socket(
            &game_config,
            &artifacts,
            essences::artifacts::ArtifactSocketSlot::FlipAspect,
        );

        // Everything the effects need, read before any mutation so the immutable
        // borrow of the fight ends here.
        let player_attack = get_entity_stat(self.behaviors.lookups(), player, "attack");
        let player_max_hp = player.max_hp;
        let baseline_speed = game_config.game_settings.baseline_speed;
        let player_speed = player.attributes.speed_or_baseline(baseline_speed);
        let target_id = nearest_enemy(&fight.entities, player);
        let enemy_ids = living_enemies(&fight.entities, player);
        // The side is read once, so every slot firing on THIS event resolves
        // against one consistent world: if one fire's gauge contribution happens
        // to cross the threshold, the slots that fired alongside it still run the
        // side that was active when the event happened. The next Core event sees
        // the new side.
        // A combatant whose flip is still locked carries no fight-local
        // FlipState; the default (Fantasy, empty gauge) is exactly their
        // durable state in that case.
        let active_side = player
            .flip_state
            .map_or_else(essences::flip::WorldSide::default, |flip| flip.active_side);
        // Gauge fill and phase identity, for the rules that read them.
        // `VA-01 Crescendo` and `HA-04 Second Half` ramp/gate on the fill;
        // `VA-04 Opening Five` and `FA-03 Warm Start` key their once-per-phase
        // markers off the revision, which is what "phase" means — the stretch
        // between two flips.
        let (flip_progress, flip_revision) = player
            .flip_state
            .map_or((0.0, 0), |flip| (flip.progress, flip.revision));
        // The bar this combatant plays against: `ART-03 Halfway Bell` lowers it
        // to a share of the configured threshold, and every reader of "how full
        // is the gauge" has to agree with the accumulator about where full is.
        let flip_threshold = art::flip_threshold(&game_config, &artifacts);
        let gauge_fill = art::gauge_fill(flip_progress, flip_threshold);
        // `FA-04 Afterimage` counts procs within one phase; the marker keeps a
        // stale count from a previous phase out.
        let afterimage_seen =
            if mech::attr(player, art::AFTERIMAGE_REVISION) == flip_revision as i64 + 1 {
                mech::attr(player, art::AFTERIMAGE_COUNT)
            } else {
                0
            };

        // The Perfect Sequence window is a property of the trigger that uses it;
        // the memory needs it one step earlier, so take the widest one socketed.
        let sequence_window = ItemType::iter()
            .filter(|t| t.supports_world_side())
            .filter_map(|item_type| StoneSocketKey::new(item_type, StoneSocketSlot::Trigger))
            .filter_map(|key| stones.socketed(key))
            .filter_map(|stone| game_config.trigger_stone_template(stone.template_id))
            .filter(|template| template.condition == TriggerCondition::SkillAttackSkillWithin)
            .map(|template| template.condition_window_ticks)
            .max()
            .unwrap_or(0);

        let Some(player) = state
            .active_fight
            .as_mut()
            .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
        else {
            return;
        };
        let mut facts: Option<Facts> = None;
        let mut spent = Vec::new();
        for outcome in &outcomes {
            let folded = advance_memory(
                player,
                *outcome,
                now,
                equipped_skills.len(),
                sequence_window,
            );
            match &mut facts {
                Some(facts) => facts.absorb(folded),
                None => facts = Some(folded),
            }
            // Effect state this event spends. Deliberately outside the cooldown
            // gate: a charge armed by an earlier fire belongs to the player, not
            // to the trigger's rate limit.
            spent.extend(spend_effect_state(
                player,
                *outcome,
                player_attack,
                &enemy_ids,
                target_id,
            ));
        }
        let facts = facts.unwrap_or_default();
        let cooldown_ready = now >= mech::attr(player, mech::GLOBAL_COOLDOWN).max(0) as u64;

        let mut fires = Vec::new();
        let mut matched = false;
        let mut opening_five_arms: Vec<(ItemType, i64)> = Vec::new();
        let mut warm_start_arms: Vec<(ItemType, i64)> = Vec::new();
        let mut afterimage_used = 0_i64;
        // Pet Facet bookkeeping, collected here and written back in the same
        // block as the artifact markers — i.e. BEFORE the effect loop, so a
        // re-entrant fire finds the charges already spent.
        let mut pet_prepared_arms: Vec<(String, i64)> = Vec::new();
        let mut pet_rising_gate_fires = 0_i64;
        let mut pet_rising_gate_mult = 1.0_f64;
        let mut pet_first_spell_used = 0_i64;
        // Up to five slots resolve in ONE batch and none of their charges is
        // written back until after the loop, so every charge a facet spends
        // per slot needs a local counter — re-reading the entity would hand the
        // same charge to every firing slot.
        let mut pet_first_spell_left = pet_mech::attr(player, pet_mech::FIRST_SPELL_CHARGES);
        let mut pet_souvenir_used = 0_i64;
        let mut pet_souvenir_left = pet_mech::attr(player, pet_mech::SOUVENIR_CHARGES);
        // Slot-order memory for `VA-02` / `VA-03`, carried in from the previous
        // event and advanced once per slot that actually resolves. Local until
        // the bookkeeping block writes it back, so the whole batch reads one
        // consistent "previous slot" rather than each slot seeing the last
        // write.
        let mut last_slot = mech::attr(player, art::LAST_RESOLVED_SLOT);
        let mut repeat_streak = mech::attr(player, art::SLOT_REPEAT_STREAK);
        for item_type in ItemType::iter().filter(|t| t.supports_world_side()) {
            let Some(key) = StoneSocketKey::new(item_type, StoneSocketSlot::Trigger) else {
                continue;
            };
            let Some(stone) = stones.socketed(key) else {
                continue;
            };
            // A template deleted from config while players own copies leaves a
            // dangling id: `character_stones.template_id` is registered with
            // `collection: none`, so nothing validates it at deploy or at load.
            // Skip the stone and keep the session alive.
            let Some(template) = game_config.trigger_stone_template(stone.template_id) else {
                tracing::warn!(
                    template_id = %stone.template_id,
                    "Skipping socketed Trigger Stone with no catalog entry"
                );
                continue;
            };

            let player = state
                .active_fight
                .as_ref()
                .and_then(|fight| fight.entities.iter().find(|e| e.id == player_id));
            let Some(player) = player else { return };
            // Any outcome of this event may satisfy the condition: a killing
            // blow is both a hit and a defeat.
            if !outcomes
                .iter()
                .any(|outcome| condition_met(template, *outcome, &facts, player, now))
            {
                continue;
            }
            matched = true;
            // Met while the build is on cooldown: lost, not queued.
            if !cooldown_ready {
                continue;
            }

            let effect_key =
                StoneSocketKey::new(item_type, StoneSocketSlot::effect_for(active_side))
                    .and_then(|key| stones.socketed(key))
                    .map(|stone| (stone.template_id, stone.level));
            // The effect socketed on the side that is NOT active right now. Four
            // rules speak through it, and none of them can reach the active side
            // — that is what keeps "hidden" meaningful.
            let paired_hidden = |slot: ItemType| {
                StoneSocketKey::new(slot, StoneSocketSlot::effect_for(active_side.flipped()))
                    .and_then(|key| stones.socketed(key))
                    .map(|stone| (stone.template_id, stone.level))
            };

            // This slot has resolved: advance the shared slot-order memory before
            // any rule reads it, so `VA-02` and `VA-03` agree on what "the
            // previous slot" was and on how long the streak is.
            let this_slot = art::slot_order_marker(item_type);
            let is_repeat = last_slot == this_slot;
            repeat_streak = if is_repeat { repeat_streak + 1 } else { 0 };
            last_slot = this_slot;

            // Visible Aspect: one of five readings of "how do active effects
            // behave". Every one of them only scales the number the effect
            // already produces — none changes what it does.
            let mut strength = 1.0;
            if let Some(aspect) = visible_aspect {
                match aspect.rule {
                    ArtifactStoneRule::Crescendo => {
                        strength *= art::crescendo_multiplier(
                            aspect.magnitude,
                            aspect.secondary_magnitude,
                            flip_progress,
                            flip_threshold,
                        );
                    }
                    ArtifactStoneRule::OpeningFive => {
                        // One bonus per slot per phase. The marker stores
                        // `revision + 1`, so an untouched attribute (`0`) reads
                        // as "not yet this phase" even at revision 0.
                        let marker = mech::attr(player, &art::opening_five_key(item_type));
                        let this_phase = flip_revision as i64 + 1;
                        if marker != this_phase {
                            strength *= art::total_multiplier(aspect.magnitude);
                            opening_five_arms.push((item_type, this_phase));
                        }
                    }
                    // `VA-02`: alternating slots is the point, so a fresh slot
                    // pays and a repeat is taxed. Both numbers are absolute
                    // shares of the effect, not deltas.
                    ArtifactStoneRule::Alternator => {
                        strength *= art::total_multiplier(if is_repeat {
                            aspect.secondary_magnitude
                        } else {
                            aspect.magnitude
                        });
                    }
                    // `VA-03`: the mirror of `VA-02` — staying on one slot is
                    // what pays, and the streak caps at `secondary_magnitude`.
                    // A fresh slot has a streak of zero and so runs plain.
                    ArtifactStoneRule::FocusedEngine => {
                        let bonus = (repeat_streak as f64 * aspect.magnitude)
                            .min(aspect.secondary_magnitude);
                        strength *= art::total_multiplier(100.0 + bonus);
                    }
                    // `VA-05`: the share comes from the tier of the TRIGGER that
                    // lit the effect, not of the effect itself — the rule pays
                    // builds that fire cheap triggers often.
                    ArtifactStoneRule::SmallGears => {
                        strength *= aspect.tier_share(template.tier);
                    }
                    _ => {}
                }
            }

            let mut extras: Vec<ExtraFire> = Vec::new();
            let mut catch_up = None;

            // Hidden Aspect: five readings of "what do the hidden effects do".
            // All of them speak through the paired hidden side and never through
            // the active one.
            if let Some(aspect) = hidden_aspect {
                let share = art::share_multiplier(aspect.magnitude);
                match aspect.rule {
                    // `HA-01`: every trigger runs the paired hidden effect too.
                    ArtifactStoneRule::BackgroundVoice => {
                        extras.extend(paired_hidden(item_type).map(|(template_id, level)| {
                            ExtraFire {
                                template_id,
                                level,
                                share,
                            }
                        }));
                    }
                    // `HA-03`: the *next* slot's hidden effect answers instead of
                    // this slot's, so the rule relays across the build rather
                    // than doubling one slot.
                    ArtifactStoneRule::CrossRelay => {
                        extras.extend(paired_hidden(next_two_sided_slot(item_type)).map(
                            |(template_id, level)| ExtraFire {
                                template_id,
                                level,
                                share,
                            },
                        ));
                    }
                    // `HA-04`: the same fire as `HA-01`, but only once the gauge
                    // is past its own share of the bar — a late-phase rule rather
                    // than an always-on one.
                    ArtifactStoneRule::SecondHalf
                        if gauge_fill >= (aspect.secondary_magnitude / 100.0) =>
                    {
                        extras.extend(paired_hidden(item_type).map(|(template_id, level)| {
                            ExtraFire {
                                template_id,
                                level,
                                share,
                            }
                        }));
                    }
                    // `HA-05`: decided after the active effect has been tried —
                    // "wholly inapplicable" is a fact about the run, not about
                    // the socket.
                    ArtifactStoneRule::CatchUp => {
                        catch_up = paired_hidden(item_type).map(|(template_id, level)| ExtraFire {
                            template_id,
                            level,
                            share,
                        });
                    }
                    _ => {}
                }
            }

            // Flip Aspect: three of its five rules land on the flip tick
            // (`crate::logic::artifacts`); these two describe the ordinary procs
            // that follow one.
            if let Some(aspect) = flip_aspect {
                let share = art::share_multiplier(aspect.magnitude);
                match aspect.rule {
                    // `FA-03`: the first ordinary fire of each newly active
                    // effect is echoed once, at a share — a warm-up, so the same
                    // marker shape as `VA-04` and a key of its own.
                    ArtifactStoneRule::WarmStart => {
                        let marker = mech::attr(player, &art::warm_start_key(item_type));
                        let this_phase = flip_revision as i64 + 1;
                        if marker != this_phase
                            && let Some((template_id, level)) = effect_key
                        {
                            extras.push(ExtraFire {
                                template_id,
                                level,
                                share,
                            });
                            warm_start_arms.push((item_type, this_phase));
                        }
                    }
                    // `FA-04`: the departing side keeps speaking for the first
                    // few procs of the new phase. The count is per phase and
                    // shared across slots — the catalog says "the first five
                    // trigger procs", not "five per slot".
                    ArtifactStoneRule::Afterimage => {
                        let allowance = aspect.rule_param.max(0);
                        if afterimage_seen + afterimage_used < allowance
                            && let Some((template_id, level)) = paired_hidden(item_type)
                        {
                            extras.push(ExtraFire {
                                template_id,
                                level,
                                share,
                            });
                            afterimage_used += 1;
                        }
                    }
                    _ => {}
                }
            }

            // Pet Facets that ride on an ORDINARY gear proc. All three read
            // state armed by the Team Die and are inert for a player who has
            // not rolled them, so the no-facet path is the old one exactly.
            //
            // Everything they add runs through the same `ExtraFire` shape the
            // artifact rules use, which is what keeps them inside the existing
            // provenance and gauge guards: an extra fire is `Proc` and its gauge
            // contribution is dropped.
            {
                // `PET-09 Prepared Slots`: the first ordinary proc of EACH gear
                // slot in the phase runs stronger. Same marker shape as
                // `VA-04 Opening Five` — `revision + 1`, so an untouched
                // attribute reads as "not yet this phase" at revision 0.
                let prepared = pet_mech::attr(player, pet_mech::PREPARED_SLOTS);
                if prepared > 0 {
                    let key = pet_mech::prepared_slot_key(item_type);
                    let this_phase = flip_revision as i64 + 1;
                    if pet_mech::attr(player, &key) != this_phase {
                        strength *= prepared as f64 / 10_000.0;
                        pet_prepared_arms.push((key, this_phase));
                    }
                }
                // `PET-09 First Spell`: the FIRST ordinary gear Effect of the
                // phase executes a second time. ONE repeat for the whole phase,
                // not one per slot — `pet_first_spell_left` is what makes that
                // true when several slots fire on the same event.
                if pet_first_spell_left > 0
                    && let Some(share) = pet_mech::armed(
                        player,
                        pet_mech::FIRST_SPELL,
                        pet_mech::FIRST_SPELL_CHARGES,
                    )
                    && let Some((template_id, level)) = effect_key
                {
                    extras.push(ExtraFire {
                        template_id,
                        level,
                        share: share as f64 / 10_000.0,
                    });
                    pet_first_spell_used += 1;
                    pet_first_spell_left -= 1;
                }
                // `PET-10 Souvenir`: the next N Trigger procs are each
                // accompanied by the paired HIDDEN effect at a share — the same
                // reading of the hidden side as `HA-01 Background Voice`.
                if pet_souvenir_left > 0
                    && let Some(share) = pet_mech::armed(
                        player,
                        pet_mech::SOUVENIR_SHARE,
                        pet_mech::SOUVENIR_CHARGES,
                    )
                    && let Some((template_id, level)) = paired_hidden(item_type)
                {
                    extras.push(ExtraFire {
                        template_id,
                        level,
                        share: share as f64 / 10_000.0,
                    });
                    pet_souvenir_used += 1;
                    pet_souvenir_left -= 1;
                }
            }

            fires.push(Fire {
                item_type,
                trigger_template: template.id,
                effect: effect_key,
                strength,
                extras,
                catch_up,
            });
        }

        // Bookkeeping, in one borrow and — critically — BEFORE the effect loop.
        {
            let Some(player) = state
                .active_fight
                .as_mut()
                .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
            else {
                return;
            };
            // Same reason as the cooldown: the markers are spent before the
            // effects run, so a re-entrant fire in the same phase cannot take a
            // once-per-phase bonus twice.
            for (item_type, phase) in opening_five_arms {
                player
                    .attributes
                    .set(&art::opening_five_key(item_type), phase);
            }
            for (item_type, phase) in warm_start_arms {
                player
                    .attributes
                    .set(&art::warm_start_key(item_type), phase);
            }
            if afterimage_used > 0 {
                player
                    .attributes
                    .set(art::AFTERIMAGE_REVISION, flip_revision as i64 + 1);
                player
                    .attributes
                    .set(art::AFTERIMAGE_COUNT, afterimage_seen + afterimage_used);
            }
            // The slot-order memory is written whether or not an Aspect stone is
            // worn: a rule socketed mid-fight must read a real history, not one
            // that starts the moment it is inserted.
            player.attributes.set(art::LAST_RESOLVED_SLOT, last_slot);
            player
                .attributes
                .set(art::SLOT_REPEAT_STREAK, repeat_streak);
            if matched && !cooldown_ready {
                // Acceptance criterion #5: the activation is lost AND the
                // sequence behind it starts over, so "every 5th attack" does not
                // fire on the very next attack the moment the cooldown lapses.
                mech::reset_sequence_counters(player);
            }
            if !fires.is_empty() {
                player.attributes.set(
                    mech::GLOBAL_COOLDOWN,
                    (now + settings.global_trigger_cooldown_ticks) as i64,
                );
            }
            // BAL-027: the metronome advances whether its match fired or
            // burned on the global cooldown.
            for (key, due) in &interval_due_updates {
                player.attributes.set(key, *due);
            }

            // Pet Facet charges, spent here for the same reason as the artifact
            // markers: before the effect loop dispatches anything.
            for (key, phase) in pet_prepared_arms {
                player.attributes.set(&key, phase);
            }
            for _ in 0..pet_first_spell_used {
                pet_mech::spend_charge(
                    player,
                    pet_mech::FIRST_SPELL,
                    pet_mech::FIRST_SPELL_CHARGES,
                );
            }
            for _ in 0..pet_souvenir_used {
                pet_mech::spend_charge(
                    player,
                    pet_mech::SOUVENIR_SHARE,
                    pet_mech::SOUVENIR_CHARGES,
                );
            }
            // `PET-08 Rising Gate` MODIFIES the gauge an ordinary Trigger proc
            // was already going to feed — one of the two Clock Crow facets the
            // design doc exempts from "a facet creates no Gauge". The charges
            // are claimed here; each claimed fire below has its own award
            // MULTIPLIED (BAL-014), never added to.
            if !fires.is_empty() {
                let mult = pet_mech::attr(player, pet_mech::RISING_GATE_MULT);
                let left = pet_mech::attr(player, pet_mech::RISING_GATE_PROCS);
                if mult != 0 && left > 0 {
                    pet_rising_gate_fires = (fires.len() as i64).min(left);
                    pet_rising_gate_mult = mult as f64 / 100.0;
                    player
                        .attributes
                        .set(pet_mech::RISING_GATE_PROCS, left - pet_rising_gate_fires);
                    if left - pet_rising_gate_fires <= 0 {
                        player.attributes.set(pet_mech::RISING_GATE_MULT, 0);
                    }
                }
            }
        }

        for event in spent {
            events.push(EventPluginized::now(event));
        }

        // BAL-027/BAL-018: every match of one event sums into ONE aggregate
        // batch gain, applied once after the loop — so the whole batch can
        // cross the bar at most once and the overflow burns together.
        let mut batch_gauge = 0.0_f64;
        for fire in fires {
            let Some(trigger) = game_config.trigger_stone_template(fire.trigger_template) else {
                continue;
            };
            // The fire's identity, before its outcomes: the outcomes are
            // emitted `Proc` with no source, so this event is the only place
            // the client learns WHICH slot's trigger fired.
            events.push(EventPluginized::now(OverlordEvent::StoneTriggerFired {
                entity_id: player_id,
                item_type: fire.item_type,
                trigger_stone_id: fire.trigger_template,
            }));
            // BAL-027: the trigger's own authored award — tier grants nothing.
            let mut gauge_gain = trigger.gauge_gain;
            if pet_rising_gate_fires > 0 {
                gauge_gain *= pet_rising_gate_mult;
                pet_rising_gate_fires -= 1;
            }

            let ctx = StoneEffectCtx {
                // Replaced per fire below: the ctx is built before the effect
                // is resolved, and every run stamps the stone it actually ran.
                source: CombatSource::Other,
                target_id,
                enemy_ids: &enemy_ids,
                player_attack,
                player_max_hp,
                player_speed,
                now,
            };

            // Whether the active side had anything to say at all. An empty
            // socket, a template pulled from under the player, and an action that
            // produced nothing all read the same way — which is what `HA-05
            // Catch-Up` means by "wholly inapplicable".
            let mut active_applied = false;
            if let Some((effect_template_id, effect_level)) = fire.effect {
                match game_config.effect_stone_template(effect_template_id) {
                    Some(effect) => {
                        let magnitude =
                            mech::effect_magnitude(settings, trigger, effect, effect_level)
                                * fire.strength;
                        let outcome = self.run_stone_effect(
                            state,
                            events,
                            player_id,
                            effect,
                            magnitude,
                            StoneEffectCtx {
                                source: CombatSource::StoneProc {
                                    stone_template_id: effect_template_id,
                                },
                                ..ctx
                            },
                        );
                        gauge_gain += outcome.gauge;
                        active_applied = outcome.applied;
                    }
                    None => tracing::warn!(
                        template_id = %effect_template_id,
                        "Skipping socketed Effect Stone with no catalog entry"
                    ),
                }
            }

            // Everything the Aspect rules attached to this fire. Their gauge
            // contribution is deliberately **dropped** — an artifact rule that
            // rebroadcasts an effect must not also feed the gauge, or a build
            // could flip itself faster the more it rebroadcasts. See the same
            // rule in `crate::logic::artifacts`.
            let catch_up = fire.catch_up.filter(|_| !active_applied);
            for extra in fire.extras.iter().copied().chain(catch_up) {
                if extra.share <= 0.0 {
                    continue;
                }
                match game_config.effect_stone_template(extra.template_id) {
                    Some(effect) => {
                        let magnitude =
                            mech::effect_magnitude(settings, trigger, effect, extra.level)
                                * extra.share;
                        let _ = self.run_stone_effect(
                            state,
                            events,
                            player_id,
                            effect,
                            magnitude,
                            StoneEffectCtx {
                                source: CombatSource::StoneProc {
                                    stone_template_id: extra.template_id,
                                },
                                ..ctx
                            },
                        );
                    }
                    None => tracing::warn!(
                        template_id = %extra.template_id,
                        "Skipping artifact-attached Effect Stone with no catalog entry"
                    ),
                }
            }

            batch_gauge += gauge_gain;
        }

        if let Some(flip) = accumulate_flip_gauge(
            state,
            player_id,
            batch_gauge,
            FlipProgressSource::TriggerFired,
            &game_config,
        ) {
            events.push(EventPluginized::now(flip));
        }
    }

    /// Runs one Effect Stone action. Returns whatever it contributes to the flip
    /// gauge on top of the trigger's own tier weight (only `GaugeFill` does).
    ///
    /// Everything that lands as a combat outcome is emitted `Proc` — derived
    /// copies, splash, retaliation, scheduled repeats — so it can never
    /// re-enter a trigger. Bookkeeping is written straight onto the player
    /// entity and is not trigger surface either way.
    ///
    /// Timed actions apply their delta now and schedule the exact inverse on the
    /// fight clock. Deltas compose, so re-applying a buff before the first one
    /// expires is additive in both directions and cannot strand a permanent
    /// bonus; the clock is cleared with the fight.
    ///
    /// Known and accepted: the attack-speed actions are a rate-limited
    /// amplification loop. They raise `speed`, which shortens ability cooldowns,
    /// which raises the Core swing rate, which fires more triggers. Not a
    /// provenance leak — an ability's cooldown re-arm is deliberately Core
    /// (`push_start_cast_replacing`), since marking it would switch triggers off
    /// for the rest of the fight. The loop is bounded by
    /// `global_trigger_cooldown_ticks`.
    ///
    /// Always runs **now**. `FA-05 Staggered Entrance` is the one rule that
    /// spaces its effects out, and it defers the whole run through
    /// [`OverlordEvent::FireArtifactEffect`] rather than delaying the events a
    /// run produces: arming is a direct write under v0.2, not an event, so there
    /// is nothing to put on the fight clock. Deferring the run instead leaves
    /// both semantics untouched — a spaced-out fire differs from an immediate one
    /// only in when it happens.
    pub(crate) fn run_stone_effect(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        player_id: EntityId,
        effect: &configs::stones::EffectStoneTemplate,
        magnitude: f64,
        ctx: StoneEffectCtx<'_>,
    ) -> StoneEffectOutcome {
        // Percentages arrive as whole percent (20.0 = +20%); entity attributes
        // that express a fraction are permyriad.
        let permyriad = (magnitude * 100.0).round() as i64;
        let fraction = magnitude / 100.0;
        let charges = effect.charges.max(0);
        let duration_ticks = effect.duration_ticks;
        let derived = |ratio: f64| {
            (ctx.player_attack * ratio * balance::DMG_K)
                .floor()
                .max(0.0) as u64
        };

        // Arming is written straight onto the player entity rather than emitted
        // as an increment: a magnitude is a *value*, and re-arming an effect must
        // overwrite it rather than stack it into nonsense.
        //
        // Answers whether anything was written — a fight that ended under the
        // effect has no player entity left to arm.
        let arm = |state: &mut OverlordState, pairs: &[(&str, i64)]| {
            let Some(player) = state
                .active_fight
                .as_mut()
                .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
            else {
                return false;
            };
            for (key, value) in pairs {
                player.attributes.set(key, *value);
            }
            true
        };

        // Whether the action had anywhere to land. This is what `HA-05 Catch-Up`
        // reads: an effect that emitted nothing — no living target, a magnitude
        // that floors to zero, a duration-less timed action — is "wholly
        // inapplicable", and the paired hidden effect answers instead. An effect
        // that landed for very little still counts as applied.
        let applied = match effect.action {
            EffectStoneAction::GaugeFill => {
                return StoneEffectOutcome {
                    gauge: magnitude.max(0.0),
                    applied: magnitude > 0.0,
                };
            }
            EffectStoneAction::NextAttackDamageBonus => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_ATTACK_BONUS, permyriad),
                            (mech::NEXT_ATTACK_BONUS_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextAttackCritChance => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_ATTACK_CRIT, permyriad),
                            (mech::NEXT_ATTACK_CRIT_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextAttackDoubleHit => {
                // `magnitude` is the total number of hits the next attack makes,
                // so the stone grants one fewer extra swing than that.
                let extra = (magnitude.round() as i64 - 1).max(0);
                if extra > 0 {
                    events.push(EventPluginized::now(OverlordEvent::EntityIncrAttribute {
                        entity_id: player_id,
                        attribute: mech::NEXT_ATTACK_EXTRA_HITS.to_string(),
                        delta: extra,
                    }));
                }
                extra > 0
            }
            EffectStoneAction::NextAttackDerivedHits => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_ATTACK_DERIVED, permyriad),
                            (mech::NEXT_ATTACK_DERIVED_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextAttacksSplash => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_ATTACK_SPLASH, permyriad),
                            (mech::NEXT_ATTACK_SPLASH_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextSkillSplash => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_SKILL_SPLASH, permyriad),
                            (mech::NEXT_SKILL_SPLASH_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextSkillSplitCopies => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_SKILL_SPLIT, permyriad),
                            // `charges` is the §6 cap — "at most 3 additional
                            // targets" — not a number of Skills. One armed Skill,
                            // N extra targets.
                            (mech::NEXT_SKILL_SPLIT_TARGETS, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextSkillPayloadBonus => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_SKILL_BONUS, permyriad),
                            (mech::NEXT_SKILL_BONUS_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextSkillEchoCopies => {
                permyriad != 0
                    && arm(
                        state,
                        &[
                            (mech::NEXT_SKILL_ECHO, permyriad),
                            (
                                mech::NEXT_SKILL_ECHO_WEAK,
                                (effect.secondary_magnitude * 100.0).round() as i64,
                            ),
                            (mech::NEXT_SKILL_ECHO_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextHitTakenReduction => {
                let reduction = permyriad.clamp(0, 10_000);
                reduction != 0
                    && arm(
                        state,
                        &[
                            (mech::HIT_REDUCTION, reduction),
                            (mech::HIT_REDUCTION_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::NextHitBlockedRetaliation => {
                let retaliation = derived(fraction) as i64;
                retaliation != 0
                    && arm(
                        state,
                        &[
                            (mech::GUARD_RETALIATION, retaliation),
                            (mech::GUARD_CHARGES, charges.max(1)),
                        ],
                    )
            }
            EffectStoneAction::InstantDamage => {
                // No living target, or a magnitude that floors to nothing: the
                // effect had nowhere to land. This is the case `HA-05 Catch-Up`
                // exists for.
                let Some(target_id) = ctx.target_id else {
                    return StoneEffectOutcome::inapplicable();
                };
                push_derived_damage(events, player_id, target_id, derived(fraction), ctx.source)
            }
            EffectStoneAction::InstantDamageAll => {
                let damage = derived(fraction);
                let mut landed = false;
                for target_id in ctx.enemy_ids {
                    landed |=
                        push_derived_damage(events, player_id, *target_id, damage, ctx.source);
                }
                landed
            }
            EffectStoneAction::HealMaxHpPercent => {
                let heal = (ctx.player_max_hp as f64 * fraction).round() as u64;
                if heal > 0 {
                    events.push(EventPluginized::now(OverlordEvent::Heal {
                        by_entity_id: Some(player_id),
                        entity_id: player_id,
                        heal,
                        origin: CombatEventOrigin::Proc,
                        source: ctx.source,
                    }));
                }
                heal > 0
            }
            EffectStoneAction::OrbitingProjectiles => {
                // Spread over the window rather than fired at once: the design
                // calls them orbiting blades, and a burst would also let one
                // effect land its whole payload inside a single tick.
                let damage = derived(fraction);
                let count = charges.max(1);
                let step = (duration_ticks / count.max(1) as u64).max(1);
                let mut launched = false;
                for index in 0..count {
                    let Some(target_id) = ctx.target_id else {
                        break;
                    };
                    if damage == 0 {
                        break;
                    }
                    self.fight_clock.schedule(
                        OverlordEvent::Damage {
                            by_entity_id: Some(player_id),
                            entity_id: target_id,
                            damage,
                            damage_data: Default::default(),
                            origin: CombatEventOrigin::Proc,
                            source: ctx.source,
                        },
                        step * (index as u64 + 1),
                    );
                    launched = true;
                }
                launched
            }
            EffectStoneAction::DelayedRepeat => {
                // The repeat is a plain scheduled hit, not a re-run of the
                // effect, which is exactly why "the repeat does not create a new
                // Twin" holds without a guard.
                let Some(target_id) = ctx.target_id else {
                    return StoneEffectOutcome::inapplicable();
                };
                let damage = derived(fraction);
                if damage == 0 {
                    return StoneEffectOutcome::inapplicable();
                }
                self.fight_clock.schedule(
                    OverlordEvent::Damage {
                        by_entity_id: Some(player_id),
                        entity_id: target_id,
                        damage,
                        damage_data: Default::default(),
                        origin: CombatEventOrigin::Proc,
                        source: ctx.source,
                    },
                    duration_ticks.max(1),
                );
                true
            }
            EffectStoneAction::SkillCooldownReduction => {
                // `magnitude` is in ticks here, not percent — the design says
                // "the longest cooldown loses 0.8 s".
                let by_ticks = magnitude.round().max(0.0) as u64;
                by_ticks > 0
                    && Self::with_player(state, player_id, |player| {
                        player.actions_queue.shorten_longest_cooldowns(
                            ctx.now,
                            charges.max(1) as usize,
                            by_ticks,
                        );
                    })
            }
            EffectStoneAction::ResetSkillCooldowns => {
                Self::with_player(state, player_id, |player| {
                    player.actions_queue.clear_ability_cooldowns(ctx.now);
                })
            }
            EffectStoneAction::CooldownRecoveryBuff => {
                // "+X% recovery for D ticks" integrates to exactly `D * X%` of
                // extra recovery, so it is applied once, up front, instead of
                // carrying a rate the cooldown queue has no way to express.
                let by_ticks = (duration_ticks as f64 * fraction).round().max(0.0) as u64;
                by_ticks > 0
                    && Self::with_player(state, player_id, |player| {
                        player.actions_queue.shorten_longest_cooldowns(
                            ctx.now,
                            mech::SKILL_SLOTS,
                            by_ticks,
                        );
                    })
            }
            EffectStoneAction::CritChanceBuff => self.apply_timed_attribute(
                events,
                player_id,
                "crit_chance",
                permyriad,
                duration_ticks,
            ),
            EffectStoneAction::Shield => {
                let shield = (ctx.player_max_hp as f64 * fraction).round() as i64;
                self.apply_timed_attribute(events, player_id, "shield", shield, duration_ticks)
            }
            EffectStoneAction::AttackSpeedBuff => {
                let delta = (ctx.player_speed as f64 * fraction).round() as i64;
                self.apply_timed_attribute(events, player_id, "speed", delta, duration_ticks)
            }
            EffectStoneAction::AttackSpeedMultiplier => {
                // `magnitude` is the multiplier (2.0 = double), so the delta is
                // what it adds on top of the current speed.
                let delta = (ctx.player_speed as f64 * (magnitude - 1.0)).round() as i64;
                self.apply_timed_attribute(events, player_id, "speed", delta, duration_ticks)
            }
            EffectStoneAction::IncomingDamageReduction => self.apply_timed_attribute(
                events,
                player_id,
                mech::INCOMING_REDUCTION,
                permyriad.clamp(0, 10_000),
                duration_ticks,
            ),
            EffectStoneAction::LifestealBuff => self.apply_timed_attribute(
                events,
                player_id,
                mech::LIFESTEAL,
                permyriad,
                duration_ticks,
            ),
            EffectStoneAction::DamageDealtBuff => self.apply_timed_attribute(
                events,
                player_id,
                mech::DAMAGE_BUFF,
                permyriad,
                duration_ticks,
            ),
            EffectStoneAction::SkillPayloadBuff => self.apply_timed_attribute(
                events,
                player_id,
                mech::SKILL_BUFF,
                permyriad,
                duration_ticks,
            ),
            EffectStoneAction::DamageFloorGuard => {
                self.apply_timed_attribute(events, player_id, mech::DAMAGE_FLOOR, 1, duration_ticks)
            }
        };
        StoneEffectOutcome {
            gauge: 0.0,
            applied,
        }
    }

    /// Runs `edit` against the player's fight entity. Answers whether the fight
    /// still had one — a caller that reports `applied` needs to tell "did the
    /// work" from "there was nobody left to do it to".
    pub(crate) fn with_player(
        state: &mut OverlordState,
        player_id: EntityId,
        edit: impl FnOnce(&mut Entity),
    ) -> bool {
        if let Some(player) = state
            .active_fight
            .as_mut()
            .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
        {
            edit(player);
            return true;
        }
        false
    }

    /// Applies `delta` to `attribute` now and schedules the exact inverse
    /// `duration_ticks` later. Returns whether anything was actually applied.
    ///
    /// A zero duration is refused rather than applied: a timed buff with no
    /// expiry would last the whole fight, which is a content error the runtime
    /// must not turn into a permanent stat.
    pub(crate) fn apply_timed_attribute(
        &mut self,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        player_id: EntityId,
        attribute: &str,
        delta: i64,
        duration_ticks: u64,
    ) -> bool {
        if delta == 0 {
            return false;
        }
        if duration_ticks == 0 {
            tracing::warn!(
                attribute,
                "Skipping timed Effect Stone action with duration_ticks = 0 — it would never \
                 expire"
            );
            return false;
        }
        events.push(EventPluginized::now(OverlordEvent::EntityIncrAttribute {
            entity_id: player_id,
            attribute: attribute.to_string(),
            delta,
        }));
        self.fight_clock.schedule(
            OverlordEvent::EntityIncrAttribute {
                entity_id: player_id,
                attribute: attribute.to_string(),
                delta: -delta,
            },
            duration_ticks,
        );
        true
    }
}

/// What running one Effect Stone action produced.
///
/// `applied` is what `HA-05 Catch-Up` reads: an action that emitted nothing —
/// instant damage with no living target or a magnitude that floors to zero, a
/// buff whose delta rounds to zero, a duration-less timed action — is "wholly
/// inapplicable", and the rule lets the paired hidden effect answer instead.
/// Everything else, including an effect that landed for very little, counts as
/// applied.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct StoneEffectOutcome {
    /// Contribution to the flip gauge on top of the trigger's tier weight (only
    /// `GaugeFill` produces one).
    pub(crate) gauge: f64,
    pub(crate) applied: bool,
}

impl StoneEffectOutcome {
    pub(crate) const fn inapplicable() -> Self {
        Self {
            gauge: 0.0,
            applied: false,
        }
    }
}

/// Combat readings one Effect Stone action may need, taken once before any
/// mutation.
///
/// `Copy`, because an artifact rebroadcast hands the same readings to five
/// effects in a row — which is why `enemy_ids` is borrowed rather than owned.
#[derive(Clone, Copy)]
pub(crate) struct StoneEffectCtx<'a> {
    /// Breakdown attribution of everything this run emits: the fired Effect
    /// Stone, or the Aspect stone when an artifact is what rebroadcast it.
    pub(crate) source: CombatSource,
    pub(crate) target_id: Option<EntityId>,
    pub(crate) enemy_ids: &'a [EntityId],
    pub(crate) player_attack: f64,
    pub(crate) player_max_hp: u64,
    pub(crate) player_speed: i64,
    pub(crate) now: u64,
}

/// One derived hit: `Proc`, so it feeds no trigger and starts no cascade.
/// Answers whether anything was emitted.
fn push_derived_damage(
    events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
    player_id: EntityId,
    target_id: EntityId,
    damage: u64,
    source: CombatSource,
) -> bool {
    if damage == 0 {
        return false;
    }
    events.push(EventPluginized::now(OverlordEvent::Damage {
        by_entity_id: Some(player_id),
        entity_id: target_id,
        damage,
        damage_data: Default::default(),
        origin: CombatEventOrigin::Proc,
        source,
    }));
    true
}

/// Spends the armed effect state this Core outcome consumes, and returns the
/// derived events it produced.
///
/// The second half of the Effect Stones: a trigger arms a state, this spends it
/// on the real action it was armed for. Kept out of the fight primitives on
/// purpose — an outgoing bonus lands as a derived hit *beside* the real one
/// rather than rewriting it, which is what keeps the real Basic Attack or
/// original Skill Core even when an effect changed its total damage.
///
/// Timing, uniform across every `NEXT_*` state spent here: a cast arrives as
/// `CastAbility` first and its landed `Damage` after, and this hook runs on
/// both, so a state armed on the cast is spent by *that cast's own* payload
/// rather than the following one. One dispatch early against the literal
/// wording of the design, and deliberate — the alternative is a "which cast
/// armed me" stamp on every key, and the effect lands on exactly one Skill
/// either way. The states consumed inside the fight primitives
/// (`NEXT_ATTACK_BONUS`, `NEXT_ATTACK_CRIT`) do not have this property: the
/// swing they modify is already resolved when the trigger arms them.
fn spend_effect_state(
    player: &mut Entity,
    outcome: CoreOutcome,
    player_attack: f64,
    enemy_ids: &[EntityId],
    target_id: Option<EntityId>,
) -> Vec<OverlordEvent> {
    let mut produced = Vec::new();
    let CoreOutcome::HitLanded {
        damage: landed,
        target: struck,
        ..
    } = outcome
    else {
        return produced;
    };
    let player_id = player.id;
    let derived = |permyriad: i64| {
        (player_attack * (permyriad as f64 / 10_000.0) * balance::DMG_K)
            .floor()
            .max(0.0) as u64
    };
    let mut hit = |target: EntityId, damage: u64| {
        if damage > 0 {
            produced.push(OverlordEvent::Damage {
                by_entity_id: Some(player_id),
                entity_id: target,
                damage,
                damage_data: Default::default(),
                origin: CombatEventOrigin::Proc,
                source: CombatSource::ArmedBonus,
            });
        }
    };

    let is_skill = mech::attr(player, mech::CAST_KIND) == mech::CAST_KIND_SKILL;
    let mut spend = Vec::new();

    // Timed outgoing bonuses: all damage, plus original Skills only.
    let mut bonus = mech::attr(player, mech::DAMAGE_BUFF);
    if is_skill {
        bonus += mech::attr(player, mech::SKILL_BUFF);
    }

    if is_skill {
        if let Some(one_shot) = mech::armed_magnitude(
            player,
            mech::NEXT_SKILL_BONUS,
            mech::NEXT_SKILL_BONUS_CHARGES,
        ) {
            bonus += one_shot;
            spend.push((mech::NEXT_SKILL_BONUS, mech::NEXT_SKILL_BONUS_CHARGES));
        }
        if let Some(echo) =
            mech::armed_magnitude(player, mech::NEXT_SKILL_ECHO, mech::NEXT_SKILL_ECHO_CHARGES)
        {
            if let Some(target) = target_id {
                hit(target, derived(echo));
                let weak = mech::attr(player, mech::NEXT_SKILL_ECHO_WEAK);
                if mech::attr(player, mech::NEXT_SKILL_ECHO_CHARGES) > 1 && weak > 0 {
                    hit(target, derived(weak));
                }
            }
            spend.push((mech::NEXT_SKILL_ECHO, mech::NEXT_SKILL_ECHO_CHARGES));
        }
        // `EF-E08` Prismatic Cast — §6: derived copies of the Skill worth
        // `magnitude`% of what it just landed, onto **at most N additional**
        // targets. The cap is the mechanic: it is what separates this Epic from
        // the Rare splash (a flat share of Attack against the whole line), and
        // the deployed waves stream 5-6 mobs, so "every enemy" would be twice
        // the reach the design asks for.
        if let Some(share) = mech::armed_magnitude(
            player,
            mech::NEXT_SKILL_SPLIT,
            mech::NEXT_SKILL_SPLIT_TARGETS,
        ) {
            let copy = (landed as f64 * (share as f64 / 10_000.0)).floor().max(0.0) as u64;
            let cap = mech::attr(player, mech::NEXT_SKILL_SPLIT_TARGETS).max(0) as usize;
            for target in enemy_ids
                .iter()
                .filter(|id| **id != struck)
                .take(cap)
                .copied()
                .collect::<Vec<_>>()
            {
                hit(target, copy);
            }
            // Spent whole: the count is a target cap for ONE Skill, not a
            // number of Skills, so both keys clear together.
            player.attributes.set(mech::NEXT_SKILL_SPLIT, 0);
            player.attributes.set(mech::NEXT_SKILL_SPLIT_TARGETS, 0);
        }
        if let Some(splash) = mech::armed_magnitude(
            player,
            mech::NEXT_SKILL_SPLASH,
            mech::NEXT_SKILL_SPLASH_CHARGES,
        ) {
            let damage = derived(splash);
            for target in enemy_ids {
                hit(*target, damage);
            }
            spend.push((mech::NEXT_SKILL_SPLASH, mech::NEXT_SKILL_SPLASH_CHARGES));
        }
    } else {
        if let Some(extra) = mech::armed_magnitude(
            player,
            mech::NEXT_ATTACK_DERIVED,
            mech::NEXT_ATTACK_DERIVED_CHARGES,
        ) {
            let damage = derived(extra);
            let hits = mech::attr(player, mech::NEXT_ATTACK_DERIVED_CHARGES).max(0);
            for _ in 0..hits {
                if let Some(target) = target_id {
                    hit(target, damage);
                }
            }
            // Spent whole: the charges ARE the hits, not a number of attacks.
            player.attributes.set(mech::NEXT_ATTACK_DERIVED, 0);
            player.attributes.set(mech::NEXT_ATTACK_DERIVED_CHARGES, 0);
        }
        if let Some(splash) = mech::armed_magnitude(
            player,
            mech::NEXT_ATTACK_SPLASH,
            mech::NEXT_ATTACK_SPLASH_CHARGES,
        ) {
            let damage = derived(splash);
            for target in enemy_ids {
                hit(*target, damage);
            }
            spend.push((mech::NEXT_ATTACK_SPLASH, mech::NEXT_ATTACK_SPLASH_CHARGES));
        }
    }

    if bonus > 0
        && let Some(target) = target_id
    {
        hit(target, derived(bonus));
    }

    let lifesteal = mech::attr(player, mech::LIFESTEAL);
    if lifesteal > 0 {
        let heal = (player_attack * (lifesteal as f64 / 10_000.0) * balance::DMG_K).round() as u64;
        if heal > 0 {
            produced.push(OverlordEvent::Heal {
                by_entity_id: Some(player_id),
                entity_id: player_id,
                heal,
                origin: CombatEventOrigin::Proc,
                source: CombatSource::ArmedBonus,
            });
        }
    }

    for (magnitude_key, charges_key) in spend {
        let left = mech::attr(player, charges_key) - 1;
        player.attributes.set(charges_key, left.max(0));
        if left <= 0 {
            player.attributes.set(magnitude_key, 0);
        }
    }

    produced
}

/// Adds one fire's contribution to the shared gauge and returns the `GlobalFlip`
/// it crossed, if any.
///
/// The gauge rules are unchanged and not re-implemented here: one gauge for the
/// whole build, the flip is global, overflow above the threshold burns — all of
/// that is [`essences::flip::FlipState::accumulate`], the same call the damage
/// source makes. A player whose flip is still locked carries no
/// `Entity::flip_state`, so the trigger simply adds nothing.
pub(crate) fn accumulate_flip_gauge(
    state: &mut OverlordState,
    player_id: EntityId,
    gain: f64,
    source: FlipProgressSource,
    game_config: &configs::game_config::GameConfig,
) -> Option<OverlordEvent> {
    if gain <= 0.0 {
        return None;
    }
    // The bar, not the raw setting: `ART-03 Halfway Bell` lowers it to a share
    // of the configured threshold — read from the GAUGE OWNER's own artifacts
    // through the same helper the ramp uses, so one combatant never has two
    // ideas of where full is. Read before the fight is borrowed mutably.
    let threshold = crate::entities::combatant_flip_threshold(state, player_id, game_config);
    let fight = state.active_fight.as_mut()?;
    let is_local_player = fight.player_id == player_id;
    let is_party_ally = fight.party_player_id == Some(player_id);
    let player = fight.entities.iter_mut().find(|e| e.id == player_id)?;
    let flip_state = player.flip_state.as_mut()?;

    // The three shared gauge recordings, with this producer's `source` label —
    // without them a producer is invisible on the source-labelled flip
    // dashboard even while it drives every flip.
    let attrs = [opentelemetry::KeyValue::new("source", source.to_string())];
    let metrics = crate::logic::fighting::flip_progress_metrics();
    metrics.gains.add(1, &attrs);
    metrics.amount.record(gain, &attrs);

    let transition = flip_state.accumulate(source, gain, threshold);
    match transition {
        Ok(outcome) => {
            // Mirror the fight-local gauge into the matching durable copy: the
            // session's own for the hero, the party/PvP snapshots for the
            // others (those never persist past the viewer's fight).
            let snapshot = *flip_state;
            if is_local_player {
                state.flip_state = snapshot;
            } else if is_party_ally {
                state.party.party_flip_state = Some(snapshot);
            } else if let Some(pvp) = state.pvp_state.as_mut()
                && pvp.opponent_state.id() == player_id
            {
                pvp.opponent_flip_state = snapshot;
            }
            let transition = outcome?;
            metrics.flips.add(1, &attrs);
            Some(OverlordEvent::GlobalFlip {
                entity_id: player_id,
                source: transition.source,
                from_side: transition.from_side,
                to_side: transition.to_side,
                revision: transition.revision,
            })
        }
        Err(err) => {
            tracing::warn!(gain, %source, "Skipping invalid flip gauge gain: {err}");
            None
        }
    }
}

/// The signed drop order is `50/50` kind → `55/25/15/5` rarity → uniform inside
/// the drawn tier (BAL-012, released with BAL-031's roll order).
///
/// If the drawn tier holds no catalog entry the roll falls back to the whole
/// `kind` catalog rather than dropping nothing: an unpopulated tier is a
/// content gap, and swallowing the drop would silently cut the faucet that
/// BAL-031's rates were fitted against.
fn pick_stone_template(
    rng: &mut rand::rngs::StdRng,
    game_config: &configs::game_config::GameConfig,
    kind: StoneKind,
) -> Option<StoneTemplateId> {
    let catalog: Vec<(StoneTemplateId, StoneTier)> = match kind {
        StoneKind::Trigger => game_config
            .trigger_stones
            .iter()
            .map(|t| (t.id, t.tier))
            .collect(),
        StoneKind::Effect => game_config
            .effect_stones
            .iter()
            .map(|t| (t.id, t.tier))
            .collect(),
    };
    if catalog.is_empty() {
        return None;
    }

    let tier = game_config
        .stones_settings
        .dropped_tier(rand::RngExt::random::<f64>(rng));
    let in_tier: Vec<StoneTemplateId> = catalog
        .iter()
        .filter(|(_, t)| *t == tier)
        .map(|(id, _)| *id)
        .collect();

    let pool: Vec<StoneTemplateId> = if in_tier.is_empty() {
        catalog.iter().map(|(id, _)| *id).collect()
    } else {
        in_tier
    };
    let index = rand::RngExt::random_range(rng, 0..pool.len());
    pool.get(index).copied()
}