overlord_event_system/mechanics/

artifacts.rs

//! Artifact combat runtime — the pure half.
//!
//! The data lives in [`essences::artifacts`] and the knobs in
//! [`configs::artifacts`]; this module is the arithmetic and the per-fight
//! bookkeeping keys that turn them into behaviour. The orchestration — which
//! event runs which rule — is [`crate::logic::artifacts`], and the Aspect rules
//! that ride on a trigger fire are woven into [`crate::logic::stones`].
//!
//! Like the stone runtime, **all per-fight artifact state lives in the player
//! entity's `attributes`**, namespaced `artifact.*`: it resets exactly when the
//! fight's entities are rebuilt, needs no schema or Unity change, and is reached
//! identically from the pure dispatch and from the monolith's merged arms. No
//! attribute code is named `artifact`, so the namespace cannot collide with a
//! stat (`crate::mechanics::fight::get_entity_stat` composes `<code>`,
//! `<code>.bonus` and `<code>.mod`).

use essences::artifacts::{ArtifactCollection, ArtifactSocketSlot};
use essences::cores::{LawBridgeCharges, LawTemplateId};
use essences::items::ItemType;

use configs::artifacts::{ArtifactStoneRule, ArtifactStoneTemplate, ArtifactWorldLaw};
use configs::game_config::GameConfig;

/// Flip revision (plus one) at which this slot's effect last took the
/// `VA-04 Opening Five` bonus. `0` means "not yet this fight" — hence the `+ 1`,
/// so revision 0 is distinguishable from "never".
pub fn opening_five_key(item_type: ItemType) -> String {
    format!("artifact.of.{item_type}")
}

/// Flip revision (plus one) at which this slot's effect last took its
/// `FA-03 Warm Start` repeat. Same shape as [`opening_five_key`], separate key:
/// the two rules live in different sockets and are worn together.
pub fn warm_start_key(item_type: ItemType) -> String {
    format!("artifact.ws.{item_type}")
}

/// Flip revision (plus one) the `FA-04 Afterimage` counter belongs to. A new
/// phase is a new count, and the marker is what tells the two apart.
pub const AFTERIMAGE_REVISION: &str = "artifact.ai.rev";

/// How many trigger procs `FA-04 Afterimage` has already accompanied in this
/// phase.
pub const AFTERIMAGE_COUNT: &str = "artifact.ai.n";

/// Tick at which «Теневой круг» (`HA-02 Shadow Round`) next fires.
pub const SHADOW_CIRCLE_DUE: &str = "artifact.sc.due";

/// Which slot «Теневой круг» visits next; it walks the two-sided slots in order
/// and wraps.
pub const SHADOW_CIRCLE_INDEX: &str = "artifact.sc.idx";

/// Flip revision (plus one) the Flip-Aspect rule last ran for. One flip runs one
/// volley even if the `GlobalFlip` event is dispatched more than once.
pub const FLIP_ASPECT_REVISION: &str = "artifact.flip.rev";

/// Which slot resolved last, as [`slot_order_marker`]. The two slot-order rules
/// (`VA-02 Alternator`, `VA-03 Focused Engine`) are defined against "the
/// previous slot", and up to five slots answer one Core event, so the answer has
/// to survive both the batch and the event boundary.
pub const LAST_RESOLVED_SLOT: &str = "artifact.slot.last";

/// How many times in a row the same slot has resolved, counting repeats only:
/// `0` on a fresh slot, `1` on its first repeat. `VA-03` turns this into its
/// stacking bonus.
pub const SLOT_REPEAT_STREAK: &str = "artifact.slot.n";

/// Position of `item_type` in the order the slot rules resolve in, plus one.
///
/// The order is `ItemType::iter()` filtered to the two-sided slots (Weapon →
/// Torso → Head → Gloves → Shoulders) — the same one `HA-03 Cross Relay` relays
/// along and the fire loop already walks, so "the next slot" and "the previous
/// slot" mean the same thing to every rule. The `+ 1` keeps `0` meaning "no slot
/// has resolved yet this fight", which is what an untouched attribute reads as.
pub fn slot_order_marker(item_type: ItemType) -> i64 {
    use strum::IntoEnumIterator;
    ItemType::iter()
        .filter(|slot| slot.supports_world_side())
        .position(|slot| slot == item_type)
        .map_or(0, |index| index as i64 + 1)
}

/// The World Law of the worn artifact, or `None` when nothing is worn.
///
/// Read from [`ArtifactCollection::equipped`] and nowhere else — that is the
/// whole of "the law works only while the artifact is worn, and drops the
/// moment another one is put on".
pub fn equipped_world_law(
    config: &GameConfig,
    collection: &ArtifactCollection,
) -> Option<ArtifactWorldLaw> {
    let equipped = collection.equipped?;
    config
        .artifacts
        .iter()
        .find(|artifact| artifact.id == equipped)
        .and_then(|artifact| artifact.world_law)
}

/// The stone in `socket` together with its upgrade level, or `None` when the
/// socket is empty.
///
/// A stone whose template vanished from the config (content pulled from under a
/// live collection) is skipped and logged, never fatal — same rule the stone
/// runtime uses.
pub fn socketed_aspect<'a>(
    config: &'a GameConfig,
    collection: &ArtifactCollection,
    socket: ArtifactSocketSlot,
) -> Option<(&'a ArtifactStoneTemplate, i64)> {
    let stone = collection.socketed(socket)?;
    let Some(template) = config
        .artifact_stones
        .iter()
        .find(|entry| entry.id == stone.template_id)
    else {
        tracing::warn!(
            template_id = %stone.template_id,
            "Skipping socketed artifact stone with no catalog entry"
        );
        return None;
    };
    Some((template, stone.level))
}

/// The ownership bonus of a whole collection, as `("<code>.mod", permyriad)`
/// pairs ready for `calculate_entity_stats_with_mods`.
///
/// Three rules, all of them design:
///
/// * it sums over **every owned artifact**, not just the worn one — an artifact
///   in the collection pays exactly as much as an artifact on the character;
/// * each artifact pays whatever ITS OWN `ownership_bonuses` list says, in any
///   set of attributes. Two artifacts naming the same attribute add up on that
///   attribute's key;
/// * the artifact's level scales each stat by
///   `percent + percent_per_level * (level - 1)`, so a duplicate that raised the
///   level raises the bonus.
///
/// Keyed by the attribute's CODE, because `<code>.mod` is what combat
/// (`fight::get_entity_stat`) and the power scalar
/// (`balance::get_attr_from_attrs`) compose. `GameConfig::validate_artifacts`
/// refuses a bonus on an attribute nothing composes, so every pair returned here
/// reaches a real stat.
///
/// Percentages become permyriad because that is the unit `.mod` is read in
/// (`+10000 == +1.0`): `1%` is `100`. Entries that round to zero are dropped —
/// an empty collection, or one whose artifacts pay nothing, returns nothing.
pub fn ownership_stat_mods(
    config: &GameConfig,
    collection: &ArtifactCollection,
) -> Vec<(String, i64)> {
    // BTreeMap, not HashMap: the pair order reaches an attribute map that tests
    // and logs compare, and a stable order costs nothing here.
    let mut percents: std::collections::BTreeMap<&str, f64> = std::collections::BTreeMap::new();

    for artifact in &collection.artifacts {
        let Some(template) = config
            .artifacts
            .iter()
            .find(|entry| entry.id == artifact.template_id)
        else {
            tracing::warn!(
                template_id = %artifact.template_id,
                "Owned artifact has no catalog entry — its ownership bonus is skipped"
            );
            continue;
        };

        for bonus in &template.ownership_bonuses {
            let Some(attribute) = config
                .attributes
                .iter()
                .find(|attr| attr.id == bonus.attribute_id)
            else {
                tracing::warn!(
                    template_id = %artifact.template_id,
                    attribute_id = %bonus.attribute_id,
                    "Artifact ownership bonus references an unknown attribute — skipped"
                );
                continue;
            };
            *percents.entry(attribute.code.as_str()).or_insert(0.0) +=
                bonus.percent_at_level(artifact.level);
        }
    }

    percents
        .into_iter()
        .filter_map(|(code, percent)| {
            let permyriad = (percent * 100.0).round() as i64;
            (permyriad != 0).then(|| (format!("{code}.mod"), permyriad))
        })
        .collect()
}

/// The flip threshold this collection actually plays against.
///
/// `ART-03 Halfway Bell` is the only artifact that moves it, and it moves it as
/// a **share** of whatever `FlipSettings::progress_threshold` is configured — so
/// a later rebalance of the threshold keeps meaning "at 60% of the bar". Every
/// other collection (and every player with nothing worn) gets the configured
/// threshold unchanged.
///
/// This is the single reader of the law: gauge accumulation, the `VA-01`
/// ramp, the `HA-04` half-gauge gate and the equip-time re-denomination all call
/// it, so there is exactly one definition of "the bar" per character.
pub fn flip_threshold(config: &GameConfig, collection: &ArtifactCollection) -> f64 {
    let base = config.flip_settings.progress_threshold;
    let share = config
        .artifacts_settings
        .flip_threshold_share(equipped_world_law(config, collection));
    base * share
}

/// How full the gauge is, in `[0, 1]`, against the bar this player plays
/// against. A nonsense bar reads as empty rather than dividing by zero.
pub fn gauge_fill(progress: f64, threshold: f64) -> f64 {
    if !threshold.is_finite() || threshold <= 0.0 || !progress.is_finite() || progress <= 0.0 {
        return 0.0;
    }
    (progress / threshold).clamp(0.0, 1.0)
}

/// Strength multiplier `VA-01 Crescendo` applies to an effect fired right now.
///
/// Ramps linearly from `floor_percent` on an empty gauge to `peak_percent` just
/// before the flip (`85% → 130%`), so the rule pays a build that lets the gauge
/// fill and *charges* one that flips the instant it can — both ends are the
/// stone's own numbers, not a bonus bolted onto plain strength.
pub fn crescendo_multiplier(
    peak_percent: f64,
    floor_percent: f64,
    progress: f64,
    threshold: f64,
) -> f64 {
    let filled = gauge_fill(progress, threshold);
    let strength = floor_percent + (peak_percent - floor_percent) * filled;
    (strength / 100.0).max(0.0)
}

/// Strength multiplier for a rule that states the effect's **total** strength as
/// a percentage (`VA-04 Opening Five` at `150%`): `100` is plain.
pub fn total_multiplier(magnitude_percent: f64) -> f64 {
    (magnitude_percent / 100.0).max(0.0)
}

/// Share of full strength a rule that rebroadcasts an effect fires it at
/// («Фоновый голос», «Теневой круг», the two Flip rules).
pub fn share_multiplier(magnitude_percent: f64) -> f64 {
    (magnitude_percent / 100.0).max(0.0)
}

/// A percentage stated as a DELTA (`+35`, `−15`) turned into a multiplier.
/// Floored at zero: a rule may cancel a number, never invert its sign.
fn delta_multiplier(percent: f64) -> f64 {
    (1.0 + percent / 100.0).max(0.0)
}

// ---------------------------------------------------------------------------
// The right (Law) column.
// ---------------------------------------------------------------------------

/// One socketed Law-column stone, flattened to the numbers its rule needs.
///
/// Flattened for the same reason as [`crate::logic::artifacts::AspectRuleInstance`]:
/// the callers read this before mutating the fight, and an owned `Copy` value
/// keeps the config borrow from outliving the read.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct LawRuleInstance {
    pub rule: ArtifactStoneRule,
    /// The rule's magnitude at the stone's current level, in percent.
    pub magnitude: f64,
    /// The rule's second percentage. Never scaled by level.
    pub secondary_magnitude: f64,
    /// The rule's own parameter (extra bridges for `BL-01`). Never scaled.
    pub rule_param: i64,
    /// The law the player pointed this stone at. Always `Some` for a rule that
    /// [`ArtifactStoneRule::needs_law_target`] — a stone with no choice is
    /// dropped at read time, so no rule site has to check.
    pub target: Option<LawTemplateId>,
}

impl LawRuleInstance {
    fn targets(&self, law_id: LawTemplateId) -> bool {
        self.target == Some(law_id)
    }
}

/// How a hidden law may be woken on this event, by whichever source offers the
/// most (design §3.3: the largest available multiplier, never the sum).
///
/// Two numbers rather than one because the strongest source may be spent:
/// `HL-04 Single Lesson` offers `100%` but only once per phase, and once its
/// latch is taken the law must fall back to whatever is still free rather than
/// stop waking. The caller claims the latch only when it actually uses
/// `once_share`.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct HiddenWake {
    /// Largest share offered by a source with no per-phase limit.
    pub free_share: f64,
    /// Share offered by `HL-04`, or `0.0` when it is not offering one here.
    pub once_share: f64,
}

impl HiddenWake {
    pub fn is_silent(&self) -> bool {
        self.free_share <= 0.0 && self.once_share <= 0.0
    }
}

/// Everything the right column does to the law runtime, resolved in ONE read.
///
/// One value, three sockets plus the World Law — read once per hook, exactly
/// like `live_aspect_in_socket` does for the left column. The all-neutral
/// [`LawColumnMods::NONE`] is what a player with no artifact gets, and every
/// method below answers `1.0` / `None` / the untouched base for it, so that
/// player's path through `logic::laws` is byte-identical to the one before this
/// feature.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct LawColumnMods {
    visible: Option<LawRuleInstance>,
    hidden: Option<LawRuleInstance>,
    bridge: Option<LawRuleInstance>,
    /// `ART-02 Thin Mirror`'s share, or `0.0` when it is not worn.
    thin_mirror_share: f64,
}

impl LawColumnMods {
    /// A player with no artifact, no Law stones and no World Law.
    pub const NONE: Self = Self {
        visible: None,
        hidden: None,
        bridge: None,
        thin_mirror_share: 0.0,
    };

    /// Whether nothing here can change anything. The hot hooks check this first.
    pub fn is_inert(&self) -> bool {
        *self == Self::NONE
    }

    /// Whether any source can wake a law of the side that is down. Gating the
    /// whole hidden-evaluation path on this is what keeps hidden counters from
    /// advancing for a player who has no way to use them.
    pub fn wakes_hidden_laws(&self) -> bool {
        self.thin_mirror_share > 0.0
            || self
                .hidden
                .is_some_and(|stone| stone.rule.wakes_hidden_law())
    }

    /// Multiplier on the numbers of `law_id`'s effect, from the Visible Law
    /// socket alone. Bridge amplification is priced separately and multiplies
    /// on top.
    ///
    /// `charges` and `capacity` are needed by `VL-04 Full Confidence`, whose
    /// gate is "the chosen law has filled its outgoing bridge". The charge only
    /// grows inside a phase and the flip zeroes it, so reading it live is
    /// already "until the Flip" — no latch needed.
    pub fn effect_multiplier(
        &self,
        law_id: LawTemplateId,
        charges: &LawBridgeCharges,
        capacity_hundredths: i64,
    ) -> f64 {
        let Some(stone) = self.visible.filter(|stone| stone.targets(law_id)) else {
            return 1.0;
        };
        match stone.rule {
            // The Resonance-for-Effect trades: the effect side is the SECOND
            // number and it is negative.
            ArtifactStoneRule::SourceFocus | ArtifactStoneRule::ExportPower => {
                delta_multiplier(stone.secondary_magnitude)
            }
            // The mirror trade: the effect side is the first number.
            ArtifactStoneRule::CurrentPower => delta_multiplier(stone.magnitude),
            ArtifactStoneRule::FullConfidence
                if charges.pending_from(law_id) >= capacity_hundredths =>
            {
                delta_multiplier(stone.magnitude)
            }
            _ => 1.0,
        }
    }

    /// Multiplier on `law_id`'s Resonance. The Visible Law and Bridge Law
    /// sockets are different sockets, so a build may wear one of each and both
    /// apply.
    pub fn resonance_multiplier(&self, law_id: LawTemplateId, charges: &LawBridgeCharges) -> f64 {
        let mut multiplier = 1.0;
        if let Some(stone) = self.visible.filter(|stone| stone.targets(law_id)) {
            multiplier *= match stone.rule {
                ArtifactStoneRule::SourceFocus | ArtifactStoneRule::ExportPower => {
                    delta_multiplier(stone.magnitude)
                }
                ArtifactStoneRule::CurrentPower => delta_multiplier(stone.secondary_magnitude),
                _ => 1.0,
            };
        }
        // `BL-01 Extra Span` pays the whole build, not one chosen law: every
        // bridge banks more Resonance per proc. Its rank raises that gain
        // instead of raising capacity, so a wider build never makes a single
        // unit of Resonance worth less (BAL-028).
        if let Some(stone) = self
            .bridge
            .filter(|stone| stone.rule == ArtifactStoneRule::ExtraSpan)
        {
            multiplier *= delta_multiplier(stone.magnitude);
        }
        // `BL-05 Reciprocal Gate` addresses a BRIDGE through one of its laws,
        // and pays BOTH directions — so any law sharing a bridge with the
        // chosen one is covered, including the chosen one itself.
        if let Some(stone) = self
            .bridge
            .filter(|stone| stone.rule == ArtifactStoneRule::ReciprocalGate)
            && let Some(target) = stone.target
            && charges
                .bridges
                .iter()
                .any(|bridge| bridge.contains(target) && bridge.contains(law_id))
        {
            multiplier *= delta_multiplier(stone.magnitude);
        }
        multiplier
    }

    /// `VL-05 First Article`: the share the FIRST activation of every
    /// active-side law in a phase applies its effect at, or `None` when the
    /// stone is not worn. Resonance is deliberately untouched — without that
    /// clause the stone would also speed up bridges and simply be stronger than
    /// its socket neighbours instead of different.
    pub fn first_activation_multiplier(&self) -> Option<f64> {
        self.visible
            .filter(|stone| stone.rule == ArtifactStoneRule::FirstArticle)
            .map(|stone| total_multiplier(stone.magnitude))
    }

    /// Bridge capacity after the Bridge Law socket, in the same units as the
    /// base. Floored at one unit: a stone may shorten a bridge, never delete it.
    ///
    /// `BL-01 Extra Span` is deliberately absent: it buys an extra bridge and a
    /// richer Resonance gain, and leaves capacity at the base (BAL-028).
    pub fn bridge_capacity(&self, base: i64) -> i64 {
        let Some(stone) = self.bridge else {
            return base;
        };
        let scaled = match stone.rule {
            ArtifactStoneRule::DeepSpan | ArtifactStoneRule::ShortSpan => {
                base as f64 * delta_multiplier(stone.magnitude)
            }
            _ => return base,
        };
        (scaled.round() as i64).max(1)
    }

    /// Recipient amplification cap after the Bridge Law socket, in permyriad.
    ///
    /// `BL-02 Deep Span` moves capacity and ceiling on the SAME rank ladder, so
    /// each rank keeps the value of one unit of Resonance while raising the
    /// ceiling (BAL-028); `BL-03 Short Span` keeps its own authored trade in
    /// `secondary_magnitude`.
    pub fn bridge_amplification_cap(&self, base: i64) -> i64 {
        let Some(stone) = self.bridge else {
            return base;
        };
        let scaled = match stone.rule {
            ArtifactStoneRule::DeepSpan => base as f64 * delta_multiplier(stone.magnitude),
            ArtifactStoneRule::ShortSpan => {
                base as f64 * delta_multiplier(stone.secondary_magnitude)
            }
            _ => return base,
        };
        (scaled.round() as i64).max(0)
    }

    /// Extra bridges allowed over the `min(core level) − 1` budget (`BL-01`).
    pub fn extra_bridges(&self) -> i64 {
        self.bridge
            .filter(|stone| stone.rule == ArtifactStoneRule::ExtraSpan)
            .map_or(0, |stone| stone.rule_param.max(0))
    }

    /// The strongest wake available to `law_id`, a law of the side that is
    /// currently DOWN.
    ///
    /// Design §3.3: several sources may name one law, and the answer is the
    /// LARGEST multiplier, never the sum. The two shares are kept apart so a
    /// spent once-per-phase source falls back instead of silencing the law.
    pub fn hidden_wake(
        &self,
        law_id: LawTemplateId,
        gauge_fill: f64,
        charges: &LawBridgeCharges,
        capacity_hundredths: i64,
    ) -> HiddenWake {
        let mut wake = HiddenWake {
            // `ART-02` names every hidden law at once and has no limit.
            free_share: self.thin_mirror_share,
            once_share: 0.0,
        };
        let Some(stone) = self.hidden else {
            return wake;
        };
        match stone.rule {
            ArtifactStoneRule::ProxyReader if stone.targets(law_id) => {
                wake.free_share = wake.free_share.max(share_multiplier(stone.magnitude));
            }
            ArtifactStoneRule::LateAwakening
                if stone.targets(law_id) && gauge_fill >= stone.secondary_magnitude / 100.0 =>
            {
                wake.free_share = wake.free_share.max(share_multiplier(stone.magnitude));
            }
            ArtifactStoneRule::SingleLesson if stone.targets(law_id) => {
                wake.once_share = share_multiplier(stone.magnitude);
            }
            // `HL-05` names a BRIDGE through one of its laws and pays the end
            // that is currently down — which is `law_id` whenever it shares the
            // chosen law's bridge and the charge flowing toward it is full.
            ArtifactStoneRule::ReadyTarget => {
                if let Some(target) = stone.target
                    && let Some(bridge) = charges
                        .bridges
                        .iter()
                        .find(|bridge| bridge.contains(target) && bridge.contains(law_id))
                    && let Some(source) = bridge.other_end(law_id)
                    && charges.pending_from(source) >= capacity_hundredths
                {
                    wake.free_share = wake.free_share.max(share_multiplier(stone.magnitude));
                }
            }
            _ => {}
        }
        wake
    }

    /// `HL-02 Linked Echo`: the law at the far end of the chosen law's bridge,
    /// and the share it applies its effect at, when `fired_law` is the chosen
    /// one.
    ///
    /// The only wake that does NOT evaluate the woken law's own condition —
    /// that is the whole rule, and it is why it lives outside
    /// [`Self::hidden_wake`].
    pub fn linked_echo(
        &self,
        fired_law: LawTemplateId,
        charges: &LawBridgeCharges,
    ) -> Option<(LawTemplateId, f64)> {
        let stone = self
            .hidden
            .filter(|stone| stone.rule == ArtifactStoneRule::LinkedEcho)?;
        if !stone.targets(fired_law) {
            return None;
        }
        let partner = charges
            .bridges
            .iter()
            .find(|bridge| bridge.contains(fired_law))?
            .other_end(fired_law)?;
        Some((partner, share_multiplier(stone.magnitude)))
    }
}

/// Reads the three Law sockets and the worn World Law into one value.
///
/// A stone is dropped here, once, when it cannot do anything: its template is
/// gone from the catalog, it ships `active: false`, or its rule needs a chosen
/// law and the player has not chosen one. That last case is the whole of "a
/// stone with no target does nothing" — no rule site repeats the check.
pub fn law_column_mods(config: &GameConfig, collection: &ArtifactCollection) -> LawColumnMods {
    if collection.stones.is_empty() && collection.equipped.is_none() {
        return LawColumnMods::NONE;
    }
    let read = |socket: ArtifactSocketSlot| -> Option<LawRuleInstance> {
        let (template, level) = socketed_aspect(config, collection, socket)?;
        if !template.active {
            return None;
        }
        let target = collection
            .socketed(socket)
            .and_then(|stone| stone.law_target);
        if template.rule.needs_law_target() && target.is_none() {
            return None;
        }
        Some(LawRuleInstance {
            rule: template.rule,
            magnitude: template.magnitude_at_level(level),
            secondary_magnitude: template.secondary_magnitude,
            rule_param: template.rule_param,
            target,
        })
    };

    LawColumnMods {
        visible: read(ArtifactSocketSlot::VisibleLaw),
        hidden: read(ArtifactSocketSlot::HiddenLaw),
        bridge: read(ArtifactSocketSlot::BridgeLaw),
        thin_mirror_share: config
            .artifacts_settings
            .thin_mirror_share(equipped_world_law(config, collection)),
    }
}

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

    #[test]
    fn bookkeeping_keys_are_per_slot_and_namespaced() {
        assert_ne!(
            opening_five_key(ItemType::Weapon),
            opening_five_key(ItemType::Gloves),
            "each slot tracks its own phase"
        );
        assert_ne!(
            opening_five_key(ItemType::Weapon),
            warm_start_key(ItemType::Weapon),
            "two rules worn together must not share one marker"
        );
        for key in [
            opening_five_key(ItemType::Weapon),
            warm_start_key(ItemType::Weapon),
            SHADOW_CIRCLE_DUE.to_string(),
            SHADOW_CIRCLE_INDEX.to_string(),
            FLIP_ASPECT_REVISION.to_string(),
            AFTERIMAGE_REVISION.to_string(),
            AFTERIMAGE_COUNT.to_string(),
            LAST_RESOLVED_SLOT.to_string(),
            SLOT_REPEAT_STREAK.to_string(),
        ] {
            assert!(
                key.starts_with("artifact."),
                "{key} may collide with a stat"
            );
        }
    }

    /// The slot order the two slot-rules resolve in: dense, one-based, and the
    /// same `ItemType::iter()` order `HA-03 Cross Relay` relays along. `0` is
    /// reserved for "nothing has resolved yet", which is what an untouched
    /// attribute reads as — so no real slot may take it.
    #[test]
    fn the_slot_order_is_one_based_and_gapless() {
        use strum::IntoEnumIterator;
        let markers: Vec<i64> = ItemType::iter()
            .filter(|slot| slot.supports_world_side())
            .map(slot_order_marker)
            .collect();
        assert_eq!(markers, (1..=markers.len() as i64).collect::<Vec<_>>());
        for slot in ItemType::iter().filter(|slot| !slot.supports_world_side()) {
            assert_eq!(
                slot_order_marker(slot),
                0,
                "{slot:?} has no two-sided socket and must not occupy a position"
            );
        }
    }

    /// `VA-01` is a ramp between two of its own numbers: below plain strength on
    /// an empty gauge, above it at the bar.
    #[test]
    fn crescendo_ramps_between_its_floor_and_its_peak() {
        assert_eq!(crescendo_multiplier(130.0, 85.0, 0.0, 1_000.0), 0.85);
        assert!(
            (crescendo_multiplier(130.0, 85.0, 500.0, 1_000.0) - 1.075).abs() < 1e-9,
            "halfway is halfway between the two ends"
        );
        assert!((crescendo_multiplier(130.0, 85.0, 1_000.0, 1_000.0) - 1.3).abs() < 1e-9);
        // Past the bar the gauge has already flipped; clamp rather than
        // extrapolate.
        assert!((crescendo_multiplier(130.0, 85.0, 5_000.0, 1_000.0) - 1.3).abs() < 1e-9);
    }

    #[test]
    fn a_broken_threshold_reads_as_an_empty_gauge() {
        assert_eq!(gauge_fill(100.0, 0.0), 0.0);
        assert_eq!(gauge_fill(f64::NAN, 1_000.0), 0.0);
        assert_eq!(
            crescendo_multiplier(130.0, 85.0, 100.0, 0.0),
            0.85,
            "an unreadable bar is the empty-gauge end of the ramp, never a guess"
        );
    }

    #[test]
    fn the_strength_multipliers_read_their_percentages() {
        assert_eq!(total_multiplier(150.0), 1.5);
        assert_eq!(total_multiplier(100.0), 1.0);
        assert_eq!(total_multiplier(-5.0), 0.0);
        assert_eq!(share_multiplier(30.0), 0.3);
        assert_eq!(share_multiplier(-5.0), 0.0);
    }
}