essences/

cores.rs

//! Twin cores, laws and bridges (OVT-2517), v0.2.
//!
//! Two cores — one per [`WorldSide`] — carry a level each. The level product
//! drives a stat multiplier (see `configs::cores::CoresSettings`) and each
//! core's own level drives how many law slots it offers.
//!
//! A law in v0.2 is `condition (Core event) → effect + Resonance into the
//! bridge`:
//!
//! * the **condition** is an existing Core combat occurrence or an already
//!   computed property of a cast ("every 5th Basic Attack", "Core Dodge",
//!   "original Skill touched ≥3 targets");
//! * the **effect** is ONE action — AoE damage, a cooldown cut, turning the
//!   next attack into an AoE, a derived skill repeat, a timed stat buff. It
//!   carries exactly one number ([`LawTemplate::effect_value`]); the old
//!   `enhanced_value` twin is gone;
//! * the **Resonance** is what the law puts into its bridge per fire.
//!
//! Only the laws of the ACTIVE side work — a hidden law's condition is not even
//! evaluated.
//!
//! A bridge is bidirectional and carries two independent charges, one per
//! direction ([`BridgeCharge`]). A phase's fires fill the charge that flows
//! AWAY from the active side; the flip delivers it to the receiving law, which
//! then runs amplified for the whole next phase. Amplification multiplies the
//! effect's numbers only — never the condition, never the Resonance, which is
//! what makes self-amplification inexpressible rather than merely bounded.
//!
//! This module holds the durable player-side shapes, the per-fight charge state
//! and the config template for one law; the arithmetic (slots, multiplier,
//! bridge limits, charge delivery) lives in
//! `overlord_event_system::mechanics::cores` and the combat runtime in
//! `overlord_event_system::logic::laws`.

use crate::abilities::AbilityTag;
use crate::flip::WorldSide;
use crate::items::AttributeId;
use crate::prelude::*;

#[declare]
pub type LawTemplateId = Uuid;

/// What makes a law fire. Every variant is a Core occurrence or a property of
/// one — nothing a law (or any other modifier) produced can satisfy any of
/// them, which is the anti-loop rule of the design (plan §8).
///
/// The numeric parameter of a condition lives in
/// [`LawTemplate::condition_value`] and its tag in
/// [`LawTemplate::condition_tag`], so retuning "every 5th" to "every 4th" is a
/// config edit.
///
/// * `NthBasicAttack` — every `condition_value`-th Core Basic Attack.
/// * `OriginalSkillCast` — one Core cast of a non-basic ability.
/// * `CriticalHit` — a Core critical hit landed by the owner.
/// * `Dodge` — a Core evasion by the owner.
/// * `NthHitTaken` — every `condition_value`-th Core hit landed on the owner.
/// * `SkillWithTag` — a Core original Skill carrying `condition_tag` resolved.
/// * `SkillMinTargets` — a Core original Skill that damaged at least
///   `condition_value` distinct targets.
/// * `SkillManaAtMost` / `SkillManaAtLeast` — per-cast mana cost bounds. Mana
///   does not exist on this branch, so laws using these ship INACTIVE
///   ([`LawTemplate::is_active`]) and are never evaluated.
/// * `KilledEnemy` — a Core action of the owner killed an enemy.
/// * `HpFellBelow` — the owner's HP crossed `condition_value` permyriad of max
///   HP downwards.
/// * `PhaseStarted` — the owner's own side just came up.
/// * `DistinctSkillsWithin` — `condition_value` DIFFERENT original Skills
///   resolved inside [`LawTemplate::condition_window_ticks`].
///
/// Variant docs live on the enum rather than on the variants so the admin
/// schema generates a plain picker instead of a `oneOf` of one-value enums.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    strum_macros::Display,
    strum_macros::EnumString,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum LawCondition {
    #[default]
    NthBasicAttack,
    OriginalSkillCast,
    CriticalHit,
    Dodge,
    NthHitTaken,
    SkillWithTag,
    SkillMinTargets,
    SkillManaAtMost,
    SkillManaAtLeast,
    KilledEnemy,
    HpFellBelow,
    PhaseStarted,
    DistinctSkillsWithin,
}

impl LawCondition {
    /// Whether this condition prices the cast off the per-cast mana cost the
    /// pool actually charged. Implemented since the mana wiring — kept as the
    /// explicit list of which conditions read the pool.
    pub const fn needs_mana(self) -> bool {
        matches!(self, Self::SkillManaAtMost | Self::SkillManaAtLeast)
    }

    /// Whether this condition is decided BEFORE the triggering cast resolves.
    /// Those laws are evaluated from the cast entry point so an effect that
    /// changes the cast itself (`RL-01` "this strike deals +100%") lands on the
    /// strike that triggered it.
    pub const fn is_pre_cast(self) -> bool {
        matches!(
            self,
            Self::NthBasicAttack
                | Self::OriginalSkillCast
                | Self::SkillWithTag
                | Self::SkillManaAtMost
                | Self::SkillManaAtLeast
                | Self::DistinctSkillsWithin
        )
    }
}

/// What a law does when it fires. One action, one number
/// ([`LawTemplate::effect_value`]) plus an optional duration.
///
/// * `ThisAttackDamageBonus` — the strike that triggered the law deals
///   `+value%` damage.
/// * `NextAttackDamageBonus` — the owner's next Basic Attack deals `+value%`.
/// * `NextAttackSplash` — the owner's next Basic Attack additionally strikes
///   every OTHER living enemy for `value%` of Attack.
/// * `ReduceLongestCooldown` — the largest remaining skill cooldown drops by
///   `value` ticks.
/// * `ReduceAllCooldowns` — every remaining skill cooldown drops by `value`
///   ticks.
/// * `ReadyShortestCooldown` — the skill with the smallest remaining cooldown
///   becomes ready now (`value` unused).
/// * `HealPercentMaxHp` — restore `value%` of max HP.
/// * `DamageBuff` — `+value%` damage for `effect_duration_ticks`.
/// * `AttackSpeedBuff` — `+value%` Basic Attack speed for
///   `effect_duration_ticks`.
/// * `DamageReduction` — `-value%` incoming damage for
///   `effect_duration_ticks`.
/// * `AoeDerivedDamage` — derived damage worth `value%` of Attack to every
///   living enemy.
/// * `NextSkillPayloadBonus` — the owner's next original Skill deals
///   `+value%`.
/// * `NextSkillEcho` — the owner's next original Skill echoes: its target
///   additionally takes `value%` of Attack as derived damage.
///
/// IMPLEMENTER'S NOTE on `NextSkillEcho` (`FL-06`, `FL-12`). The catalog words
/// it "the next original Skill gets a derived repeat at `value%`". A fractional
/// re-cast is not expressible on this branch: ability scripts take a level, not
/// a power scalar, so a "40% repeat" would have to be either a full second cast
/// or nothing. The echo is the honest form of the same beat — a derived,
/// non-Core strike worth `value%` of Attack landing with the skill — and it
/// keeps the anti-loop trivial, because nothing re-enters the cast path. When
/// abilities grow a power scalar this becomes a real scaled repeat without a
/// content change.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    strum_macros::Display,
    strum_macros::EnumString,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum LawEffect {
    #[default]
    ThisAttackDamageBonus,
    NextAttackDamageBonus,
    NextAttackSplash,
    ReduceLongestCooldown,
    ReduceAllCooldowns,
    ReadyShortestCooldown,
    HealPercentMaxHp,
    DamageBuff,
    AttackSpeedBuff,
    DamageReduction,
    AoeDerivedDamage,
    NextSkillPayloadBonus,
    NextSkillEcho,
    /// BAL-029 `Open with Magic`: cuts the SHORTEST remaining Skill cooldown
    /// by `effect_value` ticks, capped at ready. New variants append at the
    /// tail.
    ReduceShortestCooldown,
}

impl LawEffect {
    /// Whether the effect leaves a timed state behind and therefore needs a
    /// non-zero [`LawTemplate::effect_duration_ticks`].
    pub const fn is_timed(self) -> bool {
        matches!(
            self,
            Self::DamageBuff | Self::AttackSpeedBuff | Self::DamageReduction
        )
    }
}

/// One attribute the law moves while its side is up. This is the law's PASSIVE
/// half; the active half is [`LawTemplate::effect`].
///
/// One number per modifier: the v0.1 `enhanced_value` twin is gone. Bridge
/// amplification is a percentage multiplier applied on top of this value, so a
/// law level and a bridge can never drift apart the way two authored numbers
/// could.
///
/// Values are in the attribute's own native units — the same units
/// `class_levels`, talents and statue grades use (`crit_chance` and every
/// `*.mod` are permyriad: `1500` = +15%, `10000` = ×1.0).
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
pub struct LawAttributeModifier {
    #[schemars(title = "Атрибут", schema_with = "attribute_link_id_schema")]
    pub attribute_id: AttributeId,

    #[schemars(title = "Базовое значение")]
    pub base_value: i64,
}

/// A law as authored in config.
///
/// Not `Eq`: the Power coefficients are floats (BAL-030).
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, JsonSchema, Tsify, i18n::Translate)]
pub struct LawTemplate {
    #[schemars(schema_with = "id_schema")]
    pub id: LawTemplateId,

    #[schemars(title = "Название")]
    #[translate]
    pub name: i18n::I18nString,

    #[schemars(title = "Описание")]
    #[translate]
    pub description: i18n::I18nString,

    #[schemars(
        title = "Сторона",
        description = "Закон ставится только в слот ядра своей стороны и работает только пока эта сторона активна."
    )]
    pub side: WorldSide,

    /// Deterministic unlock: raising the core of [`Self::side`] to this level
    /// grants the law outright, at level 1 with no copies. Random law-copy
    /// drops stay what they always were — copy income for LEVELLING an owned
    /// law, never the unlock path.
    ///
    /// `GameConfig::validate_cores_settings` requires every law to be reachable
    /// by `CoresSettings::max_slot_level()`, so "both cores at the last
    /// slot-opening level" always means "every law owned".
    #[schemars(
        title = "Уровень ядра, на котором закон выдаётся",
        description = "Прокачка ядра своей стороны до этого уровня выдаёт закон детерминированно (1 уровень, 0 копий). Должен укладываться в уровень, на котором открыт последний слот."
    )]
    pub unlock_core_level: i64,

    #[schemars(
        title = "Условие",
        description = "Core-событие, на котором закон срабатывает. Условие скрытого закона не считается."
    )]
    pub condition: LawCondition,

    #[schemars(
        title = "Параметр условия",
        description = "N для «каждый N-й», минимум целей, порог HP в перимириадах. 0 если условию параметр не нужен."
    )]
    pub condition_value: i64,

    #[schemars(
        title = "Тег абилки в условии",
        description = "Только для условия «Original Skill с тегом»; иначе пусто."
    )]
    pub condition_tag: Option<AbilityTag>,

    #[schemars(
        title = "Окно условия, тики",
        description = "Только для условия «N разных Skill за время»; иначе 0."
    )]
    pub condition_window_ticks: i64,

    #[schemars(
        title = "Раз за фазу",
        description = "Закон срабатывает не более одного раза за фазу своей стороны."
    )]
    pub once_per_phase: bool,

    #[schemars(title = "Эффект")]
    pub effect: LawEffect,

    #[schemars(
        title = "Величина эффекта",
        description = "Одно число в единицах эффекта: проценты (перимириады), тики кулдауна. Именно это число умножает усиление моста."
    )]
    pub effect_value: i64,

    #[schemars(
        title = "Длительность эффекта, тики",
        description = "0 для мгновенных эффектов."
    )]
    pub effect_duration_ticks: i64,

    #[schemars(
        title = "Резонанс",
        description = "Сколько закон кладёт в свой мост за срабатывание. Усилением моста НЕ умножается."
    )]
    pub resonance: i64,

    #[schemars(
        title = "Закон включён",
        description = "Выключенный закон лежит в каталоге, но его условие не считается и пассивные модификаторы не действуют. Так выключают контент, которому ещё рано."
    )]
    pub is_active: bool,

    #[schemars(
        title = "Модификаторы атрибутов",
        description = "Пассивная часть закона, действует пока его сторона активна. Усиление моста умножает и её."
    )]
    pub modifiers: Vec<LawAttributeModifier>,

    #[schemars(
        title = "Множитель Power на первом ранге",
        description = "Приблизительный вклад в displayed/matchmaking Power (BAL-030). 1.0 = не влияет. Промежуточные ранги интерполируются линейно по ln(q)."
    )]
    pub power_q_first_rank: f64,

    #[schemars(
        title = "Множитель Power на максимальном ранге",
        description = "Значение того же множителя на последнем ранге. Должен быть не меньше значения на первом."
    )]
    pub power_q_max_rank: f64,

    #[schemars(title = "Иконка", schema_with = "schema_loader::asset_law_icon_schema")]
    pub icon_path: String,
}

/// One law the character owns. There is at most one row per law template: the
/// first copy becomes the working instance, every further copy is stock for the
/// upgrade ladder (raw copies, their own level irrelevant).
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct OwnedLaw {
    pub template_id: LawTemplateId,
    /// 1-based; raised by spending `copies` against the upgrade ladder.
    pub level: i64,
    /// Raw copies in stock, not yet spent on the ladder.
    pub copies: i64,
    /// Slot on the core of this law's own side, `None` when unslotted.
    pub slot_index: Option<i64>,
}

/// One bridge. Always stored side-normalized, so "exactly two laws from
/// different cores" is structural rather than a runtime check that could rot.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct LawBridge {
    pub real_law_id: LawTemplateId,
    pub fantasy_law_id: LawTemplateId,
}

impl LawBridge {
    /// The far end of the bridge for `law_id`, or `None` when `law_id` is not
    /// part of this bridge.
    pub fn other_end(&self, law_id: LawTemplateId) -> Option<LawTemplateId> {
        if law_id == self.real_law_id {
            Some(self.fantasy_law_id)
        } else if law_id == self.fantasy_law_id {
            Some(self.real_law_id)
        } else {
            None
        }
    }

    pub fn contains(&self, law_id: LawTemplateId) -> bool {
        law_id == self.real_law_id || law_id == self.fantasy_law_id
    }
}

/// Durable cores/laws/bridges state of one character. The all-zero default is
/// the pre-feature character: no cores, no laws, no bridges, multiplier ×1.0.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct CoresState {
    pub real_level: i64,
    pub fantasy_level: i64,
    pub laws: Vec<OwnedLaw>,
    pub bridges: Vec<LawBridge>,
    /// Out-of-combat Law pre-selections for the three Pet Facets that act on
    /// "one chosen Law" (`LeadReading`, `WildReading`, `DreamReader`). Kept with
    /// the laws because that is what they select; the all-`None` default is a
    /// character who has never opened the picker.
    pub pet_facet_law_choices: crate::pet_facets::PetFacetLawChoices,
}

impl CoresState {
    pub fn level_of(&self, side: WorldSide) -> i64 {
        match side {
            WorldSide::Real => self.real_level,
            WorldSide::Fantasy => self.fantasy_level,
        }
    }

    pub fn set_level(&mut self, side: WorldSide, level: i64) {
        match side {
            WorldSide::Real => self.real_level = level,
            WorldSide::Fantasy => self.fantasy_level = level,
        }
    }

    pub fn law(&self, template_id: LawTemplateId) -> Option<&OwnedLaw> {
        self.laws.iter().find(|law| law.template_id == template_id)
    }

    pub fn law_mut(&mut self, template_id: LawTemplateId) -> Option<&mut OwnedLaw> {
        self.laws
            .iter_mut()
            .find(|law| law.template_id == template_id)
    }

    /// How many bridges `law_id` currently participates in. v0.2 caps this at
    /// one (`mechanics::cores::MAX_BRIDGES_PER_LAW`): a law has exactly one
    /// partner, and the interesting choice is who it is.
    pub fn bridge_count_for_law(&self, law_id: LawTemplateId) -> usize {
        self.bridges
            .iter()
            .filter(|bridge| bridge.contains(law_id))
            .count()
    }

    /// The bridge `law_id` belongs to, if any.
    pub fn bridge_of(&self, law_id: LawTemplateId) -> Option<&LawBridge> {
        self.bridges.iter().find(|bridge| bridge.contains(law_id))
    }

    /// Laws currently sitting in a slot, in slot order.
    pub fn slotted_laws(&self) -> impl Iterator<Item = &OwnedLaw> {
        self.laws.iter().filter(|law| law.slot_index.is_some())
    }
}

/// Fixed-point scale of every bridge charge: charges are stored in HUNDREDTHS
/// of a unit and read back floored to whole units.
///
/// Why the accumulator is fractional (post-merge plan §8). Resonance is a small
/// integer 1..5 — eleven of the twenty-four laws sit at 2 — and the right-column
/// artifact stones state their effect as a percentage of it (`VL-01` `+50%`,
/// `BL-05` `+25%`). `+25%` of 2 is 2.5, so rounding at every fire would decide
/// the stone instead of the design: rounding down makes it do nothing, rounding
/// up reaches a capacity-10 bridge in four fires instead of five and turns
/// `+25%` into `+50%`. Keeping the exact value and flooring only at READ time
/// makes two fires of 2.5 worth 5 and one fire worth 2 — the remainder is not
/// lost, it just does not count until it completes a unit.
///
/// Integer hundredths rather than `f64`: this state lives between ticks on a
/// deterministic server, and floating point would accumulate divergence.
///
/// A fractional remainder alive at a flip is DELIVERED with the rest of the
/// charge and then floored by the reader, so half a unit simply never counts —
/// the same rule as "charge above capacity burns".
pub const CHARGE_SCALE: i64 = 100;

/// One live bridge of ONE combatant, with its two independent charges, in
/// hundredths of a unit ([`CHARGE_SCALE`]).
///
/// `toward_*` is the charge being FILLED by the law on the opposite side while
/// that side is up; `delivered_to_*` is what a law received at the last flip
/// and is what amplifies it for the whole current phase.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct BridgeCharge {
    pub real_law_id: LawTemplateId,
    pub fantasy_law_id: LawTemplateId,
    /// Resonance put in by the Real law, waiting for the flip that hands it to
    /// the Fantasy law.
    pub toward_fantasy: i64,
    /// Resonance put in by the Fantasy law, waiting for the Real law.
    pub toward_real: i64,
    /// Units delivered to the Real law at the last flip.
    pub delivered_to_real: i64,
    /// Units delivered to the Fantasy law at the last flip.
    pub delivered_to_fantasy: i64,
}

impl BridgeCharge {
    pub fn new(real_law_id: LawTemplateId, fantasy_law_id: LawTemplateId) -> Self {
        Self {
            real_law_id,
            fantasy_law_id,
            toward_fantasy: 0,
            toward_real: 0,
            delivered_to_real: 0,
            delivered_to_fantasy: 0,
        }
    }

    pub fn contains(&self, law_id: LawTemplateId) -> bool {
        law_id == self.real_law_id || law_id == self.fantasy_law_id
    }

    /// The far end of this bridge for `law_id`, or `None` when `law_id` is not
    /// part of it.
    pub fn other_end(&self, law_id: LawTemplateId) -> Option<LawTemplateId> {
        if law_id == self.real_law_id {
            Some(self.fantasy_law_id)
        } else if law_id == self.fantasy_law_id {
            Some(self.real_law_id)
        } else {
            None
        }
    }

    /// Which side of this bridge `law_id` sits on.
    pub fn side_of(&self, law_id: LawTemplateId) -> Option<WorldSide> {
        if law_id == self.real_law_id {
            Some(WorldSide::Real)
        } else if law_id == self.fantasy_law_id {
            Some(WorldSide::Fantasy)
        } else {
            None
        }
    }
}

/// Per-fight bridge state of ONE combatant. Lives on the combat entity rather
/// than on the fight because PvP and party fights hold several heroes, each
/// with an independent active side and independent charges.
///
/// Combat-runtime only, exactly like `Entity::proc_entropy`: it is
/// `serde(skip)`ped off the wire and the client state patch. `active_fight` is
/// never persisted (`storage::state` always hydrates it as `None`), so there is
/// no durable copy that could drift.
/// Carries the capacity and the amplification ceiling this combatant's bridges
/// play against, rather than reading them from config at every call. They are
/// fixed for the whole fight (artifact stones only change out of combat) and
/// the artifact's Bridge Law socket moves them per player, so keeping them here
/// is what lets the strip-and-refold of the passive law contribution
/// (`entities::refresh_law_attributes`) use the same numbers coming and going —
/// a config lookup could not, because it has no idea whose bridges these are.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct LawBridgeCharges {
    pub bridges: Vec<BridgeCharge>,
    /// Charge ONE direction can hold, in hundredths ([`CHARGE_SCALE`]).
    /// Everything above it burns.
    pub capacity_hundredths: i64,
    /// Law Power a completely full bridge is worth, in permyriad.
    pub amplification_cap_permyriad: i64,
}

impl LawBridgeCharges {
    pub fn new(
        bridges: Vec<BridgeCharge>,
        capacity_hundredths: i64,
        amplification_cap_permyriad: i64,
    ) -> Self {
        Self {
            bridges,
            capacity_hundredths,
            amplification_cap_permyriad,
        }
    }

    pub fn is_empty(&self) -> bool {
        self.bridges.is_empty()
    }

    /// Puts `amount` of Resonance in on behalf of `law_id`, i.e. into the
    /// charge that flows AWAY from it. Everything above `capacity` burns, like
    /// Flip Gauge overflow. Returns how much actually landed.
    ///
    /// `amount` is in hundredths ([`CHARGE_SCALE`]); the ceiling is this
    /// combatant's own [`Self::capacity_hundredths`].
    pub fn add_resonance(&mut self, law_id: LawTemplateId, amount: i64) -> i64 {
        if amount <= 0 {
            return 0;
        }
        let capacity = self.capacity_hundredths.max(0);
        let Some(bridge) = self
            .bridges
            .iter_mut()
            .find(|bridge| bridge.contains(law_id))
        else {
            return 0;
        };
        let charge = if law_id == bridge.real_law_id {
            &mut bridge.toward_fantasy
        } else {
            &mut bridge.toward_real
        };
        let before = *charge;
        *charge = (before + amount).min(capacity);
        *charge - before
    }

    /// Charge currently sitting in the direction `law_id` fills, in hundredths.
    pub fn pending_from(&self, law_id: LawTemplateId) -> i64 {
        self.bridges
            .iter()
            .find(|bridge| bridge.contains(law_id))
            .map_or(0, |bridge| {
                if law_id == bridge.real_law_id {
                    bridge.toward_fantasy
                } else {
                    bridge.toward_real
                }
            })
    }

    /// WHOLE units `law_id` received at the last flip — the floor of the exact
    /// charge. This is the only number amplification is ever priced from; the
    /// fractional remainder is kept by [`Self::delivered_hundredths`] but never
    /// counts until it completes a unit.
    ///
    /// Zero when the law is in no bridge, which is what makes an unbridged law
    /// run unamplified.
    pub fn delivered_units(&self, law_id: LawTemplateId) -> i64 {
        self.delivered_hundredths(law_id).div_euclid(CHARGE_SCALE)
    }

    /// Exact charge `law_id` received at the last flip, in hundredths.
    pub fn delivered_hundredths(&self, law_id: LawTemplateId) -> i64 {
        self.bridges
            .iter()
            .find(|bridge| bridge.contains(law_id))
            .map_or(0, |bridge| {
                if law_id == bridge.real_law_id {
                    bridge.delivered_to_real
                } else {
                    bridge.delivered_to_fantasy
                }
            })
    }

    /// Flip step 1+2 (plan §3): every accumulated charge is handed to the law
    /// at the far end and the charge is zeroed.
    ///
    /// Both directions are delivered, not just the one the outgoing phase
    /// filled: the other direction was zeroed by the previous flip and has had
    /// no active law to fill it since, so delivering it is a no-op that keeps
    /// the step free of "which side was up" bookkeeping.
    pub fn deliver(&mut self) {
        for bridge in &mut self.bridges {
            bridge.delivered_to_fantasy = bridge.toward_fantasy;
            bridge.delivered_to_real = bridge.toward_real;
            bridge.toward_fantasy = 0;
            bridge.toward_real = 0;
        }
    }

    /// Wipes every charge and every live amplification. Called at the start of
    /// a new fight.
    pub fn reset(&mut self) {
        for bridge in &mut self.bridges {
            bridge.toward_fantasy = 0;
            bridge.toward_real = 0;
            bridge.delivered_to_real = 0;
            bridge.delivered_to_fantasy = 0;
        }
    }
}

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

    /// Everything below is stated in hundredths, the unit the accumulator
    /// actually holds.
    const CAP_10: i64 = 10 * CHARGE_SCALE;

    fn charges(real: LawTemplateId, fantasy: LawTemplateId) -> LawBridgeCharges {
        LawBridgeCharges::new(vec![BridgeCharge::new(real, fantasy)], CAP_10, 5_000)
    }

    #[test]
    fn bridge_other_end_is_symmetric() {
        let real = Uuid::now_v7();
        let fantasy = Uuid::now_v7();
        let bridge = LawBridge {
            real_law_id: real,
            fantasy_law_id: fantasy,
        };

        assert_eq!(bridge.other_end(real), Some(fantasy));
        assert_eq!(bridge.other_end(fantasy), Some(real));
        assert_eq!(bridge.other_end(Uuid::now_v7()), None);
    }

    /// Acceptance criterion #5: charge accumulates up to capacity and anything
    /// above it burns rather than banking.
    #[test]
    fn charge_above_capacity_burns() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let mut charges = charges(real, fantasy);

        assert_eq!(charges.add_resonance(real, 4 * CHARGE_SCALE), 400);
        assert_eq!(charges.add_resonance(real, 4 * CHARGE_SCALE), 400);
        // Only 2 of the 5 fit; the rest burns.
        assert_eq!(charges.add_resonance(real, 5 * CHARGE_SCALE), 200);
        assert_eq!(charges.pending_from(real), CAP_10);
        assert_eq!(charges.add_resonance(real, 5 * CHARGE_SCALE), 0);
    }

    /// Post-merge plan §8: the accumulator keeps the exact value, the reader
    /// floors it. Two fires worth 2.5 make 5; one fire worth 2.5 reads as 2 and
    /// the half is remembered, not dropped.
    #[test]
    fn a_fractional_resonance_accumulates_exactly_and_reads_floored() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let mut charges = charges(real, fantasy);

        charges.add_resonance(real, 250);
        charges.deliver();
        assert_eq!(charges.delivered_hundredths(fantasy), 250);
        assert_eq!(
            charges.delivered_units(fantasy),
            2,
            "half a unit does not count yet"
        );

        charges.add_resonance(real, 250);
        charges.add_resonance(real, 250);
        charges.deliver();
        assert_eq!(
            charges.delivered_units(fantasy),
            5,
            "the two halves completed a whole unit"
        );
    }

    /// The two directions are independent: what the Real law puts in never
    /// shows up as what the Real law received.
    #[test]
    fn the_two_directions_are_independent() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let mut charges = charges(real, fantasy);

        charges.add_resonance(real, 6 * CHARGE_SCALE);
        assert_eq!(charges.pending_from(real), 6 * CHARGE_SCALE);
        assert_eq!(charges.pending_from(fantasy), 0);
        assert_eq!(charges.delivered_units(real), 0);
        assert_eq!(charges.delivered_units(fantasy), 0);
    }

    /// Acceptance criterion #6: a flip hands the charge to the RECEIVER and
    /// zeroes it.
    #[test]
    fn a_flip_delivers_to_the_far_end_and_zeroes() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let mut charges = charges(real, fantasy);

        charges.add_resonance(real, 7 * CHARGE_SCALE);
        charges.deliver();

        assert_eq!(charges.delivered_units(fantasy), 7, "far end receives");
        assert_eq!(charges.delivered_units(real), 0, "filler receives nothing");
        assert_eq!(charges.pending_from(real), 0, "charge is spent");
    }

    /// A law with no bridge is never amplified and never banks Resonance.
    #[test]
    fn an_unbridged_law_neither_fills_nor_receives() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let lonely = Uuid::now_v7();
        let mut charges = charges(real, fantasy);

        assert_eq!(charges.add_resonance(lonely, 5 * CHARGE_SCALE), 0);
        charges.deliver();
        assert_eq!(charges.delivered_units(lonely), 0);
    }

    #[test]
    fn reset_clears_charges_and_amplification() {
        let (real, fantasy) = (Uuid::now_v7(), Uuid::now_v7());
        let mut charges = charges(real, fantasy);

        charges.add_resonance(real, 5 * CHARGE_SCALE);
        charges.deliver();
        charges.add_resonance(fantasy, 3 * CHARGE_SCALE);
        charges.reset();

        assert_eq!(charges.delivered_units(fantasy), 0);
        assert_eq!(charges.pending_from(fantasy), 0);
    }
}