configs/

artifacts.rs

//! Artifact configuration — the two catalogs and every tunable the runtime
//! reads.
//!
//! Everything a designer can retune from the LiveOps panel lives here: the
//! ownership stat bonus per artifact level, the duplicate ladder, the socket
//! unlock schedule, the artifact-stone upgrade ladder, and the (placeholder)
//! acquisition sources.
//!
//! **Every number in this module is a placeholder.** The design doc leaves the
//! ownership percentages, the unlock chapters, the drop chances and the stone
//! upgrade step explicitly unassigned (§10), so they are config, not constants,
//! and the shipped values exist only so the system can be exercised end to end.

use essences::artifacts::{
    ArtifactSocketColumn, ArtifactSocketSlot, ArtifactStoneTemplateId, ArtifactTemplateId,
};
use essences::items::AttributeId;
use essences::stones::StoneTier;
use schema_loader::attribute_link_id_schema;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use tsify_next::Tsify;

/// The one-line rule welded into an artifact, active only while it is worn.
///
/// A World Law reclassifies what the build already produces; it never adds a
/// number (design §4). It is the only thing allowed to touch the gauge, the
/// Core/Proc boundary, the flip law or the socket limits — the Aspect stones
/// cannot.
///
/// The v0.2 pool is three artifacts: `ART-00 Plain Gate Key` (the starter
/// «Пустая оправа», no law at all), `ART-03 Halfway Bell` — the only law that
/// ships here — and `ART-02 Thin Mirror`, which reads hidden Laws and therefore
/// waits for the cores/laws vertical. «Отражение» (a dodge additionally reading
/// as a crit) was cut from the pool in v0.2: it is a rulebreaker, and those live
/// in a separate `Artifacts v2` wave.
///
/// Variant docs live here rather than on the variants themselves: a documented
/// variant makes the admin schema generate a `oneOf` of one-value enums instead
/// of a plain picker.
///
/// * `HalfwayBell` — «Колокол на полпути» (`ART-03`): the Global Flip happens at
///   a *share* of the configured threshold
///   ([`ArtifactsSettings::halfway_bell_threshold_share`], `60%`). No other
///   gauge source is amplified — the bar moves, the fill rate does not.
/// * `ThinMirror` — «Тонкое зеркало» (`ART-02`): EVERY slotted law of the side
///   that is currently down keeps evaluating its own Core conditions and, when
///   one is met, applies its Effect at
///   [`ArtifactsSettings::thin_mirror_share`] (`30%`) of Law Power. It is the
///   most expensive rule in the pool — it switches the other half of the build
///   back on — and the whole of its safety is the fourth clause of the
///   intersection rule (design §3): a hidden activation produces NO Resonance,
///   NO bridge charge and NO Flip Gauge, and its Effect is not a Core event.
///   Without that clause it would double both the bridge fill and the flip
///   tempo.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum ArtifactWorldLaw {
    HalfwayBell,
    ThinMirror,
}

/// Which rule an artifact stone carries.
///
/// Five per socket (design §5) — a socket is a choice between readings of one
/// moment, never between a small number and a big one. Rank scales the number
/// and opens no new mechanic, which is why a level moves
/// [`ArtifactStoneTemplate::magnitude`] and nothing else.
///
/// **Twenty-nine rules, not thirty.** The left (Aspect) column has fifteen and
/// retunes the Trigger/Effect stones worn in gear; the right (Law) column has
/// **fourteen** and retunes the laws and bridges worn in cores. The Bridge Law
/// socket ships four: `BL-04 Priority Gate` was cut because it gave `+50%`
/// Resonance "from its own source", which is a law-shaped effect in a bridge
/// socket and double-covered the rewritten `BL-05` (post-merge plan §8). The
/// numbering keeps the hole — `BL-01`, `BL-02`, `BL-03`, `BL-05` — as the
/// catalog already does for the missing `ART-01`.
///
/// Variant docs live here rather than on the variants themselves: a documented
/// variant makes the admin schema generate a `oneOf` of one-value enums instead
/// of a plain picker.
///
/// Visible Aspect — how active gear effects behave:
///
/// * `Crescendo` (`VA-01`) — active effects ramp linearly with the gauge, from
///   `secondary_magnitude`% on an empty gauge to `magnitude`% just before the
///   flip (`85% → 130%`).
/// * `Alternator` (`VA-02`) — a proc of a *different* gear slot runs at
///   `magnitude`%, a repeat of the previous slot at `secondary_magnitude`%
///   (`125% / 90%`). "Previous" means the previously resolved slot, in the
///   `ItemType::iter()` order every slot rule shares.
/// * `FocusedEngine` (`VA-03`) — repeating one slot adds `magnitude`% per
///   repeat up to `secondary_magnitude`% (`+10%` per repeat, `+30%` cap);
///   a proc of another slot resets the streak.
/// * `OpeningFive` (`VA-04`) — the first proc of each of the five slots in a
///   phase runs at `magnitude`% (`150%`), the rest are plain.
/// * `SmallGears` (`VA-05`) — effects run at a share that depends on the tier of
///   the **trigger** that lit them
///   ([`ArtifactStoneTemplate::tier_magnitudes`]: `130 / 115 / 105 / 100`).
///
/// Hidden Aspect — what hidden gear effects do:
///
/// * `BackgroundVoice` (`HA-01`) — every trigger runs the active effect in full
///   and the paired hidden one at `magnitude`% (`30%`).
/// * `ShadowRound` (`HA-02`) — once every `rule_param` ticks the next hidden
///   effect in slot order fires by itself at `magnitude`% (`60%`).
/// * `CrossRelay` (`HA-03`) — a proc of slot `N` additionally runs the hidden
///   effect of slot `N+1` at `magnitude`% (`35%`).
/// * `SecondHalf` (`HA-04`) — past `secondary_magnitude`% of the gauge, the
///   paired hidden effect accompanies every proc at `magnitude`% (`50%`).
/// * `CatchUp` (`HA-05`) — when the active effect is wholly inapplicable, the
///   paired hidden one runs at `magnitude`% (`100%`) instead.
///
/// Flip Aspect — the transition itself:
///
/// * `IncomingSalvo` (`FA-01`) — after a flip the five newly active effects each
///   run once at `magnitude`% (`50%`), all on the flip tick.
/// * `LastWord` (`FA-02`) — the five *departing* active effects each run once at
///   `magnitude`% (`50%`) as the flip happens.
/// * `WarmStart` (`FA-03`) — the first ordinary fire of each newly active effect
///   is repeated at `magnitude`% (`60%`).
/// * `Afterimage` (`FA-04`) — the first `rule_param` trigger procs after a flip
///   are accompanied by the departing paired effect at `magnitude`% (`25%`).
/// * `StaggeredEntrance` (`FA-05`) — the same five new effects as
///   `IncomingSalvo`, at `magnitude`% (`70%`), spaced `rule_param` ticks apart
///   in slot order.
///
/// Visible Law — the laws of the side that is currently UP. Each of these but
/// `FirstArticle` acts on ONE law the player chose
/// ([`essences::artifacts::ArtifactStone::law_target`]); a stone with no chosen
/// law does nothing. Because the choice is a LAW and not a role, and a law's
/// side is fixed, `SourceFocus` / `ExportPower` / `FullConfidence` only speak in
/// their law's own phase and are silent for the other half of the fight — that
/// half is what pays for the size of the bonus (post-merge plan §8):
///
/// * `SourceFocus` (`VL-01`) — the chosen law's Resonance `+magnitude`%
///   (`+50%`), its Effect `secondary_magnitude`% (`−15%`). The catalog's "only
///   into its own bridge" is dropped: a law's Resonance has no other address.
/// * `CurrentPower` (`VL-02`) — the chosen law's Effect `+magnitude`% (`+35%`),
///   its Resonance `secondary_magnitude`% (`−25%`). The mirror of `VL-01`.
/// * `ExportPower` (`VL-03`) — the hard version of `VL-01`: Resonance
///   `+magnitude`% (`+75%`), Effect `secondary_magnitude`% (`−25%`). Kept beside
///   `VL-01` deliberately — same trade, two settings of it.
/// * `FullConfidence` (`VL-04`) — once the chosen law has filled its outgoing
///   bridge, that law runs at `+magnitude`% Effect (`+30%`) until the flip.
/// * `FirstArticle` (`VL-05`) — the one rule of the column that addresses the
///   whole build: the FIRST activation of EVERY law of the active side in a
///   phase applies its Effect at `magnitude`% (`150%`), Resonance untouched. It
///   changes the rhythm of a phase rather than the strength of one law, which is
///   why it takes no target.
///
/// Hidden Law — the laws of the side that is currently DOWN. A hidden
/// activation never produces Resonance, bridge charge or Flip Gauge, and its
/// Effect is not a Core event ([`crate::artifacts::ArtifactWorldLaw::ThinMirror`]
/// carries the same rule):
///
/// * `ProxyReader` (`HL-01`) — the chosen hidden law evaluates its own Core
///   conditions and applies its Effect at `magnitude`% (`30%`).
/// * `LinkedEcho` (`HL-02`) — when the chosen law activates, the law at the
///   far end of its bridge applies its Effect at `magnitude`% (`20%`) without
///   checking its own condition at all.
/// * `LateAwakening` (`HL-03`) — past `secondary_magnitude`% of the gauge
///   (`70%`) the chosen hidden law works at `magnitude`% (`50%`).
/// * `SingleLesson` (`HL-04`) — the first Core event of a phase that satisfies
///   the chosen hidden law wakes it at `magnitude`% (`100%`); the stone is then
///   silent until the flip.
/// * `ReadyTarget` (`HL-05`) — once the chosen law's bridge is full, the law at
///   its far end works at `magnitude`% (`35%`) until the flip.
///
/// Bridge Law — the bridges themselves. `BL-01`…`BL-03` move EVERY bridge;
/// `BL-05` is the only one that addresses a single bridge, through the law that
/// sits in it:
///
/// * `ExtraSpan` (`BL-01`) — `rule_param` extra bridges over the
///   `min(core level) − 1` budget, and every bridge's capacity `+magnitude`%
///   (`+20%`).
/// * `DeepSpan` (`BL-02`) — every bridge's capacity `+magnitude`% and its
///   recipient amplification `+secondary_magnitude`% (`+40% / +40%`): a deeper
///   bridge and a higher ceiling at the same price per unit.
/// * `ShortSpan` (`BL-03`) — capacity `magnitude`% and amplification
///   `secondary_magnitude`% (`−40% / −20%`). The minus signs are the design: a
///   shorter bridge with a lower ceiling makes each unit worth MORE
///   (`40% / 6 units` against `50% / 10`), so the cap arrives in three fires
///   instead of five.
/// * `ReciprocalGate` (`BL-05`) — `+magnitude`% Resonance (`+25%`) to BOTH
///   directions of the chosen law's bridge, unconditionally. The catalog's
///   original wording ("if both links A→B and B→A are chosen") describes a
///   choice no version of the model offers — a bridge is one object carrying two
///   directions — so it was rewritten (post-merge plan §8).
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum ArtifactStoneRule {
    Crescendo,
    Alternator,
    FocusedEngine,
    OpeningFive,
    SmallGears,
    BackgroundVoice,
    ShadowRound,
    CrossRelay,
    SecondHalf,
    CatchUp,
    IncomingSalvo,
    LastWord,
    WarmStart,
    Afterimage,
    StaggeredEntrance,
    SourceFocus,
    CurrentPower,
    ExportPower,
    FullConfidence,
    FirstArticle,
    ProxyReader,
    LinkedEcho,
    LateAwakening,
    SingleLesson,
    ReadyTarget,
    ExtraSpan,
    DeepSpan,
    ShortSpan,
    ReciprocalGate,
}

impl ArtifactStoneRule {
    /// The socket this rule belongs in. A stone's template names its socket
    /// explicitly, and `GameConfig::validate_artifacts` checks the two agree —
    /// so a mistyped catalog entry cannot ship a Flip rule into a Visible
    /// socket.
    pub const fn socket(self) -> ArtifactSocketSlot {
        match self {
            Self::Crescendo
            | Self::Alternator
            | Self::FocusedEngine
            | Self::OpeningFive
            | Self::SmallGears => ArtifactSocketSlot::VisibleAspect,
            Self::BackgroundVoice
            | Self::ShadowRound
            | Self::CrossRelay
            | Self::SecondHalf
            | Self::CatchUp => ArtifactSocketSlot::HiddenAspect,
            Self::IncomingSalvo
            | Self::LastWord
            | Self::WarmStart
            | Self::Afterimage
            | Self::StaggeredEntrance => ArtifactSocketSlot::FlipAspect,
            Self::SourceFocus
            | Self::CurrentPower
            | Self::ExportPower
            | Self::FullConfidence
            | Self::FirstArticle => ArtifactSocketSlot::VisibleLaw,
            Self::ProxyReader
            | Self::LinkedEcho
            | Self::LateAwakening
            | Self::SingleLesson
            | Self::ReadyTarget => ArtifactSocketSlot::HiddenLaw,
            Self::ExtraSpan | Self::DeepSpan | Self::ShortSpan | Self::ReciprocalGate => {
                ArtifactSocketSlot::BridgeLaw
            }
        }
    }

    /// Whether this rule is worthless until the player points its stone at a
    /// law. Every Law-column rule but `VL-05 First Article` (which addresses the
    /// whole build) and `BL-01`…`BL-03` (which move every bridge) needs one.
    pub const fn needs_law_target(self) -> bool {
        matches!(
            self,
            Self::SourceFocus
                | Self::CurrentPower
                | Self::ExportPower
                | Self::FullConfidence
                | Self::ProxyReader
                | Self::LinkedEcho
                | Self::LateAwakening
                | Self::SingleLesson
                | Self::ReadyTarget
                | Self::ReciprocalGate
        )
    }

    /// Whether this rule can wake a law of the side that is currently DOWN.
    /// Those activations go through the intersection rule (design §3) and are
    /// the only law fires that produce no Resonance and no bridge charge.
    pub const fn wakes_hidden_law(self) -> bool {
        matches!(
            self,
            Self::ProxyReader
                | Self::LinkedEcho
                | Self::LateAwakening
                | Self::SingleLesson
                | Self::ReadyTarget
        )
    }

    /// Why this rule cannot run on this branch yet, or `None` when it can.
    ///
    /// Every rule now has the mechanic it reads, so nothing is blocked: the
    /// left column's last three dependencies landed with the stones v0.2 merge,
    /// and the whole right column's — laws, bridges, Resonance — landed with the
    /// cores vertical. How the left column's were settled is worth keeping,
    /// because the answers are the rules' semantics rather than incidental
    /// history:
    ///
    /// * `Alternator` and `FocusedEngine` both say "another slot" / "a repeat of
    ///   the previous slot", and the shared Trigger Cooldown lets up to five
    ///   slots answer one Core event at once. **Resolved**: slots resolve in the
    ///   fixed `ItemType::iter()` order (Weapon → Torso → Head → Gloves →
    ///   Shoulders), the order `HA-03 Cross Relay` already ships on, and "the
    ///   previous slot" is the previously *resolved* one, carried across event
    ///   boundaries. The two alternatives were rejected on their merits: "the
    ///   last slot of the previous batch" makes the bonus depend on batch
    ///   boundaries the player cannot see, and "only when exactly one slot fired"
    ///   switches both rules off for any five-socket build — the build they
    ///   exist for.
    /// * `SmallGears` keys off trigger tiers up to Legendary. **Resolved**: the
    ///   stones v0.2 catalog ships Legendary triggers.
    ///
    /// `GameConfig::validate_artifacts` refuses a catalog entry that ships a
    /// blocked rule with `active: true`. With nothing blocked the guard has no
    /// work to do, and it stays because the next rule to be entered ahead of its
    /// dependency will need it again.
    pub const fn unavailable_dependency(self) -> Option<&'static str> {
        None
    }
}

/// One rung of `VA-05 Small Gears`: how strongly effects run when the trigger
/// that fired them has this tier.
///
/// Carried on the template rather than hard-coded so the rule's whole content is
/// visible in the catalog while it waits for the Legendary tier to exist.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactTierMagnitude {
    #[schemars(title = "Тир триггера")]
    pub tier: StoneTier,

    #[schemars(
        title = "Сила эффекта, %",
        description = "100 — обычная сила. Используется только правилом «Мелкие шестерни»."
    )]
    pub magnitude: f64,
}

/// Attribute codes whose `.mod` key is actually COMPOSED by the runtime.
///
/// An ownership bonus is written as `<code>.mod`, and only these codes are read
/// back — combat composes them in `mechanics::fight::get_entity_stat` (plus `hp`
/// through `attributes::compose_max_hp`) and the honest power scalar in
/// `mechanics::balance::get_attr_from_attrs`. A bonus on any other attribute
/// would be written, stored, shown in no stat and read by nothing: silently
/// inert content. `GameConfig::validate_artifacts` refuses it instead.
///
/// This list lives here, not in `overlord_event_system`, because `configs` is
/// the lower crate — the dependency only runs one way, so it cannot be derived
/// from those functions and must be kept in sync with them by hand.
///
/// `game_config::tests::mod_capable_codes_cover_the_attributes_the_runtime_composes`
/// pins the three codes the shipped catalog actually uses for ownership bonuses
/// and the list's own shape (no duplicates, base codes rather than `.mod` keys).
/// It deliberately does not assert full coverage: the direction that hurts is a
/// code listed here that nothing reads (which would let inert content ship), and
/// a code read by the runtime but missing here only costs a designer the ability
/// to use it — a visible refusal, not a silent no-op.
pub const MOD_CAPABLE_ATTRIBUTE_CODES: [&str; 14] = [
    "armor",
    "attack",
    "block",
    "bravery",
    "counterattack_chance",
    "crit_chance",
    "crit_modifier",
    "deceit",
    "evasion",
    "hp",
    "multicast_chance",
    "received_damage",
    "regeneration_rate",
    "speed",
];

/// One stat an artifact pays for being OWNED, in percent of the composed stat.
///
/// Mirrors the `StoneStat` idiom (`value` + `value_per_level`) so the two
/// collections scale the same way and a reader who knows one knows the other.
/// The difference is the unit: a stone stat is a flat attribute delta, this is a
/// PERCENT written into `<code>.mod`.
///
/// An artifact carries a whole list of these, so "5% hp + 10% armor" is one
/// template — the shared three-column table this replaced could only ever
/// express one artifact-wide row per level.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactOwnershipBonusStat {
    #[schemars(title = "Id атрибута", schema_with = "attribute_link_id_schema")]
    pub attribute_id: AttributeId,

    #[schemars(
        title = "Прибавка на 1 уровне, %",
        description = "Проценты к атрибуту за владение артефактом 1 уровня."
    )]
    pub percent: f64,

    #[schemars(
        title = "Прибавка за каждый уровень выше первого, %",
        description = "Итог = процент + процент_за_уровень * (уровень - 1)."
    )]
    pub percent_per_level: f64,
}

impl ArtifactOwnershipBonusStat {
    /// The percent this stat pays on an artifact of `level`. Level 1 (and any
    /// nonsense below it) is the base percent.
    pub fn percent_at_level(&self, level: i64) -> f64 {
        let levels_above_first = if level > 1 { level - 1 } else { 0 };
        self.percent + self.percent_per_level * levels_above_first as f64
    }
}

/// One entry of the artifact catalog.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactTemplate {
    #[schemars(schema_with = "schema_loader::id_schema")]
    pub id: ArtifactTemplateId,

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

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

    /// The welded-in rule, or `None` for an artifact that is a bare frame.
    #[schemars(
        title = "World Law",
        description = "Правило, вшитое в артефакт. Работает только пока артефакт надет. Пусто — артефакт без правила (стартовая «Пустая оправа»)."
    )]
    pub world_law: Option<ArtifactWorldLaw>,

    /// What owning this artifact pays, per attribute. Empty = pays nothing.
    ///
    /// Fully per-template: any set of attributes, any values. Every owned
    /// artifact pays — worn or not — which is the one thing that makes a second
    /// artifact worth having once only one can be worn.
    #[schemars(
        title = "Бонусы за владение",
        description = "Список атрибутов и процентов, которые артефакт даёт за владение. Пусто — артефакт не даёт статов."
    )]
    pub ownership_bonuses: Vec<ArtifactOwnershipBonusStat>,

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

    #[schemars(
        title = "Множитель Power World Law",
        description = "Приблизительный вклад World Law этого артефакта в displayed Power, пока артефакт надет (BAL-030). От ранга не зависит; 1.0 у артефакта без правила."
    )]
    pub power_q: f64,
}

/// One entry of the artifact-stone catalog.
///
/// The first copy carries the whole rule; `magnitude_per_level` is the only
/// thing an upgrade moves (design §3), which is why the rule and `rule_param`
/// are level-independent.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactStoneTemplate {
    #[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(schema_with = "schema_loader::id_schema")]
    pub id: ArtifactStoneTemplateId,

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

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

    #[schemars(title = "Сокет")]
    pub socket: ArtifactSocketSlot,

    #[schemars(title = "Правило")]
    pub rule: ArtifactStoneRule,

    #[schemars(
        title = "Базовая величина, %",
        description = "Величина правила на 1-м уровне, в процентах. Правило целиком даётся первой копией; уровень двигает только это число."
    )]
    pub magnitude: f64,

    #[schemars(title = "Прибавка величины за уровень прокачки, %")]
    pub magnitude_per_level: f64,

    #[schemars(
        title = "Вторая величина правила, %",
        description = "Второй процент правила: нижняя точка разгона у «Крещендо», сила повтора у «Чередования», потолок у «Сфокусированного мотора», доля шкалы у «Второй половины». Остальным правилам не нужна (0). Прокачкой не меняется."
    )]
    pub secondary_magnitude: f64,

    #[schemars(
        title = "Параметр правила",
        description = "Период в тиках для «Теневого круга» и «Поочерёдного входа», число срабатываний для «Послеобраза»; для остальных правил не используется (0). Прокачкой не меняется."
    )]
    pub rule_param: i64,

    #[schemars(
        title = "Сила по тирам триггера",
        description = "Только для «Мелких шестерён» (VA-05). У остальных камней список пустой."
    )]
    pub tier_magnitudes: Vec<ArtifactTierMagnitude>,

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

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

impl ArtifactStoneTemplate {
    /// The rule's magnitude on a stone of upgrade level `level`, in percent.
    /// Same shape as `configs::stones::StoneStat::value_at_level`, so both
    /// systems scale with a level identically.
    pub fn magnitude_at_level(&self, level: i64) -> f64 {
        let levels_above_first = (level - 1).max(0) as f64;
        self.magnitude + self.magnitude_per_level * levels_above_first
    }

    /// `VA-05 Small Gears` only: the share effects run at when the trigger that
    /// fired them had `tier`. An unlisted tier reads as plain strength rather
    /// than as zero, so a half-filled table can never silence a build.
    pub fn tier_magnitude(&self, tier: StoneTier) -> f64 {
        self.tier_magnitudes
            .iter()
            .find(|entry| entry.tier == tier)
            .map_or(100.0, |entry| entry.magnitude)
    }
}

/// Ownership stat bonus of ONE artifact at a given level, in percent.
///
/// One rung of an upgrade ladder: how many raw copies buy `level`.
///
/// Used by both ladders — artifacts and artifact stones. In both cases a
/// duplicate banks a raw copy and an explicit player action spends the rung.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactUpgradeStep {
    #[schemars(
        title = "Уровень, который покупается",
        description = "Лестница начинается со 2-го уровня и должна доходить до максимального без пропусков."
    )]
    pub level: i64,

    #[schemars(
        title = "Сколько сырых копий нужно",
        description = "Сам предмет в это число не входит. Копии считаются штуками."
    )]
    pub copies: i64,
}

/// When one artifact socket opens.
///
/// The order is fixed by design — the whole Aspect column before the Law column
/// — and `GameConfig::validate_artifacts` enforces it.
///
/// The three Law sockets used to be scheduled past the end of the campaign,
/// because their stones had no laws to retune. The cores vertical shipped, so
/// they carry real chapters now; the shipped schedule continues the left
/// column's four-chapter cadence (see `artifacts_settings/_data.yaml` for the
/// numbers and the reasoning).
#[derive(Clone, Copy, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactSocketUnlock {
    #[schemars(title = "Сокет")]
    pub socket: ArtifactSocketSlot,

    #[schemars(
        title = "Глава разблокировки",
        description = "BAL-007: подписанные главы 91/111/131/151/171/191. Порядок фиксирован: сначала вся левая колонка (Aspect), потом правая (Law)."
    )]
    pub unlock_chapter: i64,
}

/// BAL-031 source: where artifact stones drop from (signed rates).
///
/// Deliberately a different faucet from the artifacts themselves (design §5), so
/// the two collections never compete for the same drop.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactStoneDropSettings {
    #[schemars(
        title = "Шанс камня артефакта с босса главы",
        description = "Доля в [0,1]. BAL-031: подписанное значение 0.02."
    )]
    pub chapter_boss_chance: f64,

    #[schemars(
        title = "Шанс камня артефакта за пройденное подземелье",
        description = "Доля в [0,1]. BAL-031: подписанное значение 0.15."
    )]
    pub dungeon_chance: f64,

    /// The third faucet, added by the acquisition pass: a small per-kill
    /// chance alongside the boss and dungeon drops, so the collection has a
    /// steady trickle instead of moving only on gate events. Scaled by the
    /// dead mob's `wave_share` like every other per-kill payout.
    #[schemars(
        title = "Шанс камня артефакта с убийства моба",
        description = "Доля в [0,1], домножается на wave_share убитого моба. Дополняет дроп с босса и подземелья, а не заменяет его."
    )]
    pub mob_kill_chance: f64,
}

/// All artifact tunables.
#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactsSettings {
    /// Chapter at which the artifact navigation vertical becomes visible.
    ///
    /// UI only — it gates NOTHING about ownership. Since the acquisition pass
    /// there is no per-template chapter gate at all: the starter is granted at
    /// character creation, and every other artifact is a bundle reward (today,
    /// the top-1 weekly rating bundles).
    #[schemars(
        title = "Глава открытия вертикали",
        description = "Глава открытия навигации артефактов. Только UI: владение артефактами от неё не зависит."
    )]
    pub unlock_chapter: i64,

    /// The guaranteed freebie. It exists so the stone system does not depend on
    /// a rare drop, so it must always resolve to a real catalog entry —
    /// `GameConfig::validate_artifacts` checks that.
    #[schemars(
        title = "Стартовый артефакт",
        schema_with = "schema_loader::artifact_link_id_schema"
    )]
    pub starter_artifact_id: ArtifactTemplateId,

    #[schemars(title = "Максимальный уровень артефакта")]
    pub max_artifact_level: i64,

    #[schemars(
        title = "Лестница уровней артефакта: сырых копий за уровень",
        description = "Явное улучшение тратит ровно стоимость следующего уровня. Получение дубликата только добавляет сырую копию, в том числе на максимальном уровне."
    )]
    pub upgrade_ladder: Vec<ArtifactUpgradeStep>,

    #[schemars(title = "Расписание открытия сокетов")]
    pub socket_unlocks: Vec<ArtifactSocketUnlock>,

    #[schemars(title = "Максимальный уровень камня артефакта")]
    pub max_stone_level: i64,

    #[schemars(title = "Лестница прокачки камня артефакта: сырых копий за уровень")]
    pub stone_upgrade_ladder: Vec<ArtifactUpgradeStep>,

    /// `ART-03 Halfway Bell`'s only number, and deliberately a **share** rather
    /// than an absolute threshold: `FlipSettings::progress_threshold` is a
    /// balance knob that moves (the stones vertical rescales it), and a hard
    /// number here would silently stop meaning "halfway" the moment it did.
    #[schemars(
        title = "Доля порога флипа под «Колоколом на полпути»",
        description = "Доля обычного порога, на которой происходит Global Flip у носителя ART-03. 0.6 — «на 60% порога». Остальные источники Gauge не меняются."
    )]
    pub halfway_bell_threshold_share: f64,

    /// `ART-02 Thin Mirror`'s only number: the share of Law Power a hidden law
    /// woken by the World Law applies its effect at.
    #[schemars(
        title = "Доля силы скрытых законов под «Тонким зеркалом»",
        description = "0.3 — скрытые законы применяют эффект на 30% силы. Скрытая активация не создаёт ни резонанс, ни заряд моста, ни шкалу флипа."
    )]
    pub thin_mirror_share: f64,

    #[schemars(title = "ЗАГЛУШКА: источники камней артефакта")]
    pub stone_drop: ArtifactStoneDropSettings,
}

impl ArtifactsSettings {
    /// Whether `socket` is open at `chapter_level`. An unscheduled socket never
    /// opens; `GameConfig::validate_artifacts` requires all six to be scheduled,
    /// so this is a safety net rather than a reachable state.
    pub fn is_socket_unlocked(&self, socket: ArtifactSocketSlot, chapter_level: i64) -> bool {
        self.socket_unlocks
            .iter()
            .find(|unlock| unlock.socket == socket)
            .is_some_and(|unlock| chapter_level >= unlock.unlock_chapter)
    }

    /// The share of the configured flip threshold `law` moves the bar to.
    ///
    /// `1.0` for every law but `ART-03`, so the caller never has to know which
    /// law is which — and a nonsense configured share reads as "no change"
    /// rather than as an instant or unreachable flip.
    pub fn flip_threshold_share(&self, law: Option<ArtifactWorldLaw>) -> f64 {
        match law {
            Some(ArtifactWorldLaw::HalfwayBell) => {
                let share = self.halfway_bell_threshold_share;
                if share.is_finite() && share > 0.0 && share <= 1.0 {
                    share
                } else {
                    1.0
                }
            }
            Some(ArtifactWorldLaw::ThinMirror) | None => 1.0,
        }
    }

    /// The share of Law Power hidden laws run at under `ART-02 Thin Mirror`, or
    /// `0.0` for every other worn artifact (and for nothing worn).
    ///
    /// A nonsense configured share reads as "no wake" rather than as a free
    /// full-strength second build — the conservative direction, since this rule
    /// switches on half the build.
    pub fn thin_mirror_share(&self, law: Option<ArtifactWorldLaw>) -> f64 {
        match law {
            Some(ArtifactWorldLaw::ThinMirror) => {
                let share = self.thin_mirror_share;
                if share.is_finite() && share > 0.0 && share <= 1.0 {
                    share
                } else {
                    0.0
                }
            }
            Some(ArtifactWorldLaw::HalfwayBell) | None => 0.0,
        }
    }

    /// Raw copies needed to take an artifact **to** `target_level`. `None` means
    /// the ladder has no such rung — at the cap, or a config gap that
    /// validation rules out at load time.
    pub fn upgrade_copies_required(&self, target_level: i64) -> Option<i64> {
        self.upgrade_ladder
            .iter()
            .find(|step| step.level == target_level)
            .map(|step| step.copies)
    }

    /// Same, for an artifact stone.
    pub fn stone_upgrade_copies_required(&self, target_level: i64) -> Option<i64> {
        self.stone_upgrade_ladder
            .iter()
            .find(|step| step.level == target_level)
            .map(|step| step.copies)
    }

    /// The unlock chapter of the first socket of `column`, used by validation
    /// and by tests to state the "left column first" rule without repeating the
    /// slot list.
    pub fn earliest_unlock_of(&self, column: ArtifactSocketColumn) -> Option<i64> {
        self.socket_unlocks
            .iter()
            .filter(|unlock| unlock.socket.column() == column)
            .map(|unlock| unlock.unlock_chapter)
            .min()
    }
}

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

    fn settings() -> ArtifactsSettings {
        ArtifactsSettings {
            unlock_chapter: 30,
            starter_artifact_id: uuid::Uuid::from_u128(1),
            max_artifact_level: 3,
            upgrade_ladder: vec![
                ArtifactUpgradeStep {
                    level: 2,
                    copies: 1,
                },
                ArtifactUpgradeStep {
                    level: 3,
                    copies: 2,
                },
            ],
            socket_unlocks: vec![
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::VisibleAspect,
                    unlock_chapter: 30,
                },
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::HiddenAspect,
                    unlock_chapter: 34,
                },
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::FlipAspect,
                    unlock_chapter: 38,
                },
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::VisibleLaw,
                    unlock_chapter: 42,
                },
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::HiddenLaw,
                    unlock_chapter: 46,
                },
                ArtifactSocketUnlock {
                    socket: ArtifactSocketSlot::BridgeLaw,
                    unlock_chapter: 50,
                },
            ],
            max_stone_level: 5,
            stone_upgrade_ladder: vec![ArtifactUpgradeStep {
                level: 2,
                copies: 2,
            }],
            halfway_bell_threshold_share: 0.6,
            thin_mirror_share: 0.3,
            stone_drop: ArtifactStoneDropSettings {
                chapter_boss_chance: 0.1,
                dungeon_chance: 0.2,
                mob_kill_chance: 0.0,
            },
        }
    }

    /// The whole Aspect column opens before the first Law socket does, and every
    /// Law socket now opens at a chapter a player can actually reach.
    #[test]
    fn the_aspect_column_opens_before_the_law_column() {
        let settings = settings();
        assert!(settings.is_socket_unlocked(ArtifactSocketSlot::VisibleAspect, 30));
        assert!(!settings.is_socket_unlocked(ArtifactSocketSlot::FlipAspect, 30));
        assert!(settings.is_socket_unlocked(ArtifactSocketSlot::FlipAspect, 38));

        for law in [
            ArtifactSocketSlot::VisibleLaw,
            ArtifactSocketSlot::HiddenLaw,
            ArtifactSocketSlot::BridgeLaw,
        ] {
            assert!(
                !settings.is_socket_unlocked(law, 38),
                "{law} must not open before the last Aspect socket"
            );
            assert!(
                settings.is_socket_unlocked(law, 50),
                "{law} must be reachable"
            );
        }
        assert_eq!(
            settings.earliest_unlock_of(ArtifactSocketColumn::Law),
            Some(42)
        );
    }

    #[test]
    fn each_ladder_prices_its_own_levels() {
        let settings = settings();
        assert_eq!(settings.upgrade_copies_required(2), Some(1));
        assert_eq!(settings.upgrade_copies_required(3), Some(2));
        assert_eq!(settings.upgrade_copies_required(4), None);
        assert_eq!(settings.stone_upgrade_copies_required(2), Some(2));
    }

    /// Acceptance criterion 9: a level moves the magnitude and nothing else.
    #[test]
    fn a_stone_level_scales_only_the_magnitude() {
        let template = ArtifactStoneTemplate {
            id: uuid::Uuid::from_u128(2),
            name: i18n::I18nString::Translated(String::new()),
            description: i18n::I18nString::Translated(String::new()),
            socket: ArtifactSocketSlot::FlipAspect,
            rule: ArtifactStoneRule::StaggeredEntrance,
            magnitude: 70.0,
            magnitude_per_level: 10.0,
            secondary_magnitude: 0.0,
            rule_param: 500,
            tier_magnitudes: Vec::new(),
            power_q_first_rank: 1.03,
            power_q_max_rank: 1.06,
            active: true,
            icon_path: String::new(),
        };

        assert_eq!(template.magnitude_at_level(1), 70.0);
        assert_eq!(template.magnitude_at_level(3), 90.0);
        assert_eq!(template.magnitude_at_level(0), 70.0);
        assert_eq!(
            template.rule_param, 500,
            "the rule's own parameter is level-independent"
        );
        assert_eq!(
            template.secondary_magnitude, 0.0,
            "and so is the second percentage"
        );
    }

    /// `VA-05` carries its whole tier table in the catalog even while switched
    /// off, and an unlisted tier reads as plain strength.
    #[test]
    fn the_tier_table_is_read_per_tier_and_defaults_to_plain() {
        let template = ArtifactStoneTemplate {
            id: uuid::Uuid::from_u128(3),
            name: i18n::I18nString::Translated(String::new()),
            description: i18n::I18nString::Translated(String::new()),
            socket: ArtifactSocketSlot::VisibleAspect,
            rule: ArtifactStoneRule::SmallGears,
            magnitude: 130.0,
            magnitude_per_level: 5.0,
            secondary_magnitude: 0.0,
            rule_param: 0,
            tier_magnitudes: vec![
                ArtifactTierMagnitude {
                    tier: StoneTier::Common,
                    magnitude: 130.0,
                },
                ArtifactTierMagnitude {
                    tier: StoneTier::Rare,
                    magnitude: 115.0,
                },
            ],
            power_q_first_rank: 1.03,
            power_q_max_rank: 1.06,
            active: false,
            icon_path: String::new(),
        };

        assert_eq!(template.tier_magnitude(StoneTier::Common), 130.0);
        assert_eq!(template.tier_magnitude(StoneTier::Rare), 115.0);
        assert_eq!(
            template.tier_magnitude(StoneTier::Legendary),
            100.0,
            "an unlisted tier is plain strength, never silence"
        );
    }

    #[test]
    fn every_rule_declares_the_socket_it_belongs_to() {
        use ArtifactStoneRule::*;
        for rule in [
            Crescendo,
            Alternator,
            FocusedEngine,
            OpeningFive,
            SmallGears,
        ] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::VisibleAspect);
        }
        for rule in [
            BackgroundVoice,
            ShadowRound,
            CrossRelay,
            SecondHalf,
            CatchUp,
        ] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::HiddenAspect);
        }
        for rule in [
            IncomingSalvo,
            LastWord,
            WarmStart,
            Afterimage,
            StaggeredEntrance,
        ] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::FlipAspect);
        }
        for rule in [
            SourceFocus,
            CurrentPower,
            ExportPower,
            FullConfidence,
            FirstArticle,
        ] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::VisibleLaw);
        }
        for rule in [
            ProxyReader,
            LinkedEcho,
            LateAwakening,
            SingleLesson,
            ReadyTarget,
        ] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::HiddenLaw);
        }
        for rule in [ExtraSpan, DeepSpan, ShortSpan, ReciprocalGate] {
            assert_eq!(rule.socket(), ArtifactSocketSlot::BridgeLaw);
        }
    }

    /// Nothing ships blocked any more: every left-column dependency landed with
    /// the stones v0.2 merge, and the right column's landed with the cores
    /// vertical. The guard itself stays for the next rule entered ahead of its
    /// mechanic.
    #[test]
    fn no_rule_declares_a_missing_dependency() {
        use ArtifactStoneRule::*;
        for rule in [
            Crescendo,
            Alternator,
            FocusedEngine,
            OpeningFive,
            SmallGears,
            BackgroundVoice,
            ShadowRound,
            CrossRelay,
            SecondHalf,
            CatchUp,
            IncomingSalvo,
            LastWord,
            WarmStart,
            Afterimage,
            StaggeredEntrance,
            SourceFocus,
            CurrentPower,
            ExportPower,
            FullConfidence,
            FirstArticle,
            ProxyReader,
            LinkedEcho,
            LateAwakening,
            SingleLesson,
            ReadyTarget,
            ExtraSpan,
            DeepSpan,
            ShortSpan,
            ReciprocalGate,
        ] {
            assert_eq!(rule.unavailable_dependency(), None, "{rule:?} runs today");
        }
    }

    /// Which rules are worthless without a chosen law, and which wake a law of
    /// the side that is down. Both predicates gate real behaviour, so a rule
    /// added to the wrong list is a silently dead or a silently doubled stone.
    #[test]
    fn the_law_column_declares_which_rules_need_a_target_and_which_wake_hidden_laws() {
        use ArtifactStoneRule::*;
        for rule in [
            SourceFocus,
            CurrentPower,
            ExportPower,
            FullConfidence,
            ProxyReader,
            LinkedEcho,
            LateAwakening,
            SingleLesson,
            ReadyTarget,
            ReciprocalGate,
        ] {
            assert!(rule.needs_law_target(), "{rule:?} addresses one law");
        }
        // The build-wide rules: VL-05 changes the rhythm of a phase, BL-01..03
        // move every bridge.
        for rule in [FirstArticle, ExtraSpan, DeepSpan, ShortSpan, Crescendo] {
            assert!(!rule.needs_law_target(), "{rule:?} addresses no single law");
        }

        for rule in [
            ProxyReader,
            LinkedEcho,
            LateAwakening,
            SingleLesson,
            ReadyTarget,
        ] {
            assert!(rule.wakes_hidden_law(), "{rule:?} is a Hidden Law rule");
        }
        for rule in [
            SourceFocus,
            CurrentPower,
            ExportPower,
            FullConfidence,
            FirstArticle,
            ExtraSpan,
            DeepSpan,
            ShortSpan,
            ReciprocalGate,
            BackgroundVoice,
        ] {
            assert!(
                !rule.wakes_hidden_law(),
                "{rule:?} must never produce a hidden law activation"
            );
        }
    }

    /// `ART-03` moves the bar by a share of whatever threshold is configured;
    /// every other worn artifact leaves it alone, and a nonsense share is
    /// ignored rather than turned into an instant flip.
    #[test]
    fn the_halfway_bell_share_applies_only_to_its_own_law() {
        let mut settings = settings();
        assert_eq!(settings.flip_threshold_share(None), 1.0);
        assert_eq!(
            settings.flip_threshold_share(Some(ArtifactWorldLaw::ThinMirror)),
            1.0,
            "the other artifact does not touch the bar"
        );
        assert_eq!(
            settings.flip_threshold_share(Some(ArtifactWorldLaw::HalfwayBell)),
            0.6
        );

        for broken in [0.0, -1.0, 1.5, f64::NAN] {
            settings.halfway_bell_threshold_share = broken;
            assert_eq!(
                settings.flip_threshold_share(Some(ArtifactWorldLaw::HalfwayBell)),
                1.0,
                "a broken share must read as 'no change'"
            );
        }
    }

    /// `ART-02` wakes hidden laws only for its own wearer, and a nonsense share
    /// switches the rule OFF rather than granting a free second build.
    #[test]
    fn the_thin_mirror_share_applies_only_to_its_own_law() {
        let mut settings = settings();
        assert_eq!(settings.thin_mirror_share(None), 0.0);
        assert_eq!(
            settings.thin_mirror_share(Some(ArtifactWorldLaw::HalfwayBell)),
            0.0
        );
        assert_eq!(
            settings.thin_mirror_share(Some(ArtifactWorldLaw::ThinMirror)),
            0.3
        );

        for broken in [0.0, -1.0, 1.5, f64::NAN] {
            settings.thin_mirror_share = broken;
            assert_eq!(
                settings.thin_mirror_share(Some(ArtifactWorldLaw::ThinMirror)),
                0.0,
                "a broken share must switch the rule off, never open it up"
            );
        }
    }
}