essences/

stones.rs

//! Trigger/Effect Stones — what a player owns, where it sits, how it levels.
//!
//! The data half of the feature — nothing here fires anything. Trigger
//! evaluation, the global cooldown and effect execution live in
//! `overlord_event_system::logic::stones`, which reads these types plus
//! `configs::stones`.
//!
//! Three facts shape everything below:
//!
//! * **One instance per catalog entry, plus a stock of raw copies.** A stone is
//!   identified by its [`Stone::template_id`] and carries a [`Stone::copies`]
//!   count, not N interchangeable rows. Template ids are unique across both
//!   catalogs (`GameConfig::validate_stones`). The consequence: one instance
//!   means one socket, so a second insert of the same template is refused with
//!   [`StoneError::AlreadySocketed`].
//! * **Triggers and Effects are separate collections.** Never socketable into
//!   each other's sockets and never sharing copies, so two `Vec`s keyed by
//!   [`StoneKind`] rather than one list with a flag.
//! * **A socketed stone never leaves the inventory.** Inserting sets
//!   [`Stone::socket`], removing clears it — there is no second home for a
//!   stone to be lost in.

use crate::flip::WorldSide;
use crate::items::ItemType;
use crate::prelude::*;

use strum::IntoEnumIterator;
use strum_macros::{Display, EnumCount, EnumIter, EnumString};

use std::collections::HashMap;

#[declare]
pub type StoneTemplateId = Uuid;

/// Rarity tier of a stone.
///
/// For a Trigger Stone the tier is the *shape of the condition* and its weight
/// in the flip gauge, not how hard it is to farm; for an Effect Stone it is the
/// shape of the action (instant / short state / schedule change).
///
/// The declaration order is the strength order and `Ord` is derived from it:
/// `Common < Rare < Epic < Legendary`. `QuickEquipStones` ranks candidates by
/// `(tier, level)` — tier first, because it drives both the gauge contribution
/// and the grammar of the effect, while level only scales a number.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    PartialOrd,
    Ord,
    Hash,
    JsonSchema,
    Tsify,
    Display,
    EnumString,
    EnumIter,
    EnumCount,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum StoneTier {
    #[default]
    Common,
    Rare,
    Epic,
    Legendary,
}

/// Which of the two collections a stone belongs to.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    Display,
    EnumString,
    EnumIter,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum StoneKind {
    /// "When X" — one per two-sided slot, shared by both sides.
    #[default]
    Trigger,
    /// "Do Y" — one per side of a two-sided slot.
    Effect,
}

/// One of the three sockets a two-sided equipment slot carries.
///
/// The trigger is shared: a slot has exactly one trigger driving both sides,
/// and only the effect it fires changes when the world flips.
///
/// * `Trigger` — the slot's single shared trigger.
/// * `RealEffect` — the effect fired while the Real side is active.
/// * `FantasyEffect` — the effect fired while the Fantasy side is active.
///
/// 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.
#[derive(
    Clone,
    Copy,
    Debug,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    Display,
    EnumString,
    EnumIter,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum StoneSocketSlot {
    Trigger,
    RealEffect,
    FantasyEffect,
}

impl StoneSocketSlot {
    /// The collection a stone must come from to fit this socket. A Trigger
    /// Stone never goes in an effect socket and vice versa.
    pub const fn accepts(self) -> StoneKind {
        match self {
            Self::Trigger => StoneKind::Trigger,
            Self::RealEffect | Self::FantasyEffect => StoneKind::Effect,
        }
    }

    /// The world side this socket answers for, or `None` for the shared
    /// trigger.
    pub const fn world_side(self) -> Option<WorldSide> {
        match self {
            Self::Trigger => None,
            Self::RealEffect => Some(WorldSide::Real),
            Self::FantasyEffect => Some(WorldSide::Fantasy),
        }
    }

    /// The effect socket that is live on `side`.
    pub const fn effect_for(side: WorldSide) -> Self {
        match side {
            WorldSide::Real => Self::RealEffect,
            WorldSide::Fantasy => Self::FantasyEffect,
        }
    }
}

/// Where one socketed stone sits: which equipment slot, which of its three
/// sockets.
///
/// Only the five two-sided equipment types have sockets — the same five that
/// answer [`ItemType::supports_world_side`]. Keying off that predicate instead
/// of a second hand-written list is deliberate: the two lists cannot drift.
#[derive(Clone, Copy, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct StoneSocketKey {
    pub item_type: ItemType,
    pub socket: StoneSocketSlot,
}

impl StoneSocketKey {
    /// `None` when `item_type` has no sockets (one of the five ordinary,
    /// one-sided slots).
    pub fn new(item_type: ItemType, socket: StoneSocketSlot) -> Option<Self> {
        item_type
            .supports_world_side()
            .then_some(Self { item_type, socket })
    }

    /// Every socket in the game: 5 two-sided slots × 3 sockets = 15.
    pub fn all() -> Vec<Self> {
        ItemType::iter()
            .filter(|item_type| item_type.supports_world_side())
            .flat_map(|item_type| {
                StoneSocketSlot::iter().map(move |socket| Self { item_type, socket })
            })
            .collect()
    }
}

/// The one instance a player owns of a catalog entry, plus its stock of raw
/// copies.
///
/// `template_id` is the identity: at most one `Stone` per template per
/// collection, so there is no separate instance id. The database key is
/// `(character_id, template_id)` for the same reason.
///
/// `level` is the upgrade level and `copies` is the currency that buys it. The
/// first copy becomes the instance at level 1 with zero copies banked; every
/// later copy increments `copies`. The ladder in
/// `configs::stones::StonesSettings::upgrade_ladder` says what each level costs.
/// The first copy already carries the full mechanic — an upgrade only scales the
/// number it applies.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct Stone {
    /// The catalog entry this is the player's instance of, and its identity.
    pub template_id: StoneTemplateId,
    pub tier: StoneTier,
    pub level: i64,
    /// Raw copies banked against this stone, spendable on the next level. Never
    /// negative: a refused upgrade spends nothing.
    pub copies: i64,
    /// `Some` while socketed. The stone stays in its collection either way —
    /// this is the whole of "inserted" and "removed". One instance means one
    /// socket: the same template cannot sit in two slots.
    pub socket: Option<StoneSocketKey>,
}

impl Stone {
    /// The player's first copy of `template_id`: level 1, nothing banked.
    pub fn new(template_id: StoneTemplateId, tier: StoneTier) -> Self {
        Self {
            template_id,
            tier,
            level: 1,
            copies: 0,
            socket: None,
        }
    }

    pub const fn is_socketed(&self) -> bool {
        self.socket.is_some()
    }

    /// Ranking key for "the best stone I own": **tier first, then level**.
    ///
    /// The two axes are not comparable on their own — a level-3 Common against
    /// a level-1 Legendary has no arithmetic answer — so the design picks one.
    /// Tier wins because it decides the stone's gauge contribution and the
    /// shape of what it does; level only scales a magnitude inside that shape.
    pub const fn quality(&self) -> (StoneTier, i64) {
        (self.tier, self.level)
    }
}

/// What one `UpgradeAllStones` call actually changed: template id -> (from, to)
/// level. Modelled on `UpgradedAbilitiesMap` and used the same way — the client
/// shows the result window from this, and quests read it for progress.
///
/// Only stones that actually gained a level appear; a stone whose bank was too
/// short is simply absent rather than present with an unchanged pair.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, Tsify, JsonSchema)]
pub struct UpgradedStonesMap(pub HashMap<StoneTemplateId, (i64, i64)>);

impl UpgradedStonesMap {
    pub fn insert(&mut self, id: StoneTemplateId, levels: (i64, i64)) {
        self.0.insert(id, levels);
    }

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

/// Everything a character owns in the stone system: the two collections, kept
/// apart, plus the socket assignments carried by the stones themselves.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct StoneInventory {
    pub trigger_stones: Vec<Stone>,
    pub effect_stones: Vec<Stone>,
}

/// Why an insert/remove/upgrade was refused. Every variant is a rule from the
/// design doc, so the caller can report the actual reason instead of a generic
/// failure.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum StoneError {
    #[error("the player owns no stone of template {0}")]
    UnknownStone(StoneTemplateId),
    #[error("{item_type:?} has no stone sockets — only the five two-sided slots do")]
    SlotHasNoSockets { item_type: ItemType },
    #[error("socket {socket} takes a {expected} stone, not a {actual} one")]
    WrongCollection {
        socket: StoneSocketSlot,
        expected: StoneKind,
        actual: StoneKind,
    },
    #[error("socket {socket:?} on {item_type:?} is not unlocked yet")]
    SocketLocked {
        item_type: ItemType,
        socket: StoneSocketSlot,
    },
    /// One instance per template means one socket per template: this is also
    /// how "the same stone in two slots" is refused.
    #[error("stone {0} is already socketed — a template holds at most one socket")]
    AlreadySocketed(StoneTemplateId),
    #[error("stone {0} is not socketed")]
    NotSocketed(StoneTemplateId),
    #[error("upgrading stone {stone} to level {level} needs {required} copies, {held} banked")]
    NotEnoughCopies {
        stone: StoneTemplateId,
        level: i64,
        required: i64,
        held: i64,
    },
    #[error("stone {0} is already at the maximum level {1}")]
    AlreadyMaxLevel(StoneTemplateId, i64),
    /// The upgrade ladder has no rung for the level being bought.
    /// `GameConfig::validate_stones` rules this out at load time, so it means a
    /// config loaded past validation — refuse rather than guess a cost.
    #[error("the upgrade ladder has no cost for level {0}")]
    NoUpgradeStep(i64),
}

impl StoneInventory {
    pub fn collection(&self, kind: StoneKind) -> &Vec<Stone> {
        match kind {
            StoneKind::Trigger => &self.trigger_stones,
            StoneKind::Effect => &self.effect_stones,
        }
    }

    pub fn collection_mut(&mut self, kind: StoneKind) -> &mut Vec<Stone> {
        match kind {
            StoneKind::Trigger => &mut self.trigger_stones,
            StoneKind::Effect => &mut self.effect_stones,
        }
    }

    pub fn all(&self) -> impl Iterator<Item = (StoneKind, &Stone)> {
        self.trigger_stones
            .iter()
            .map(|s| (StoneKind::Trigger, s))
            .chain(self.effect_stones.iter().map(|s| (StoneKind::Effect, s)))
    }

    /// Which collection holds `template_id`, if any. The lookup runs across
    /// both collections precisely so a caller cannot address a Trigger Stone as
    /// if it were an Effect Stone; the two catalogs share no template id, so
    /// the answer is unambiguous.
    pub fn kind_of(&self, template_id: StoneTemplateId) -> Option<StoneKind> {
        self.all()
            .find(|(_, stone)| stone.template_id == template_id)
            .map(|(kind, _)| kind)
    }

    pub fn get(&self, template_id: StoneTemplateId) -> Option<&Stone> {
        self.all()
            .find(|(_, s)| s.template_id == template_id)
            .map(|(_, s)| s)
    }

    fn get_mut(&mut self, template_id: StoneTemplateId) -> Option<&mut Stone> {
        self.trigger_stones
            .iter_mut()
            .chain(self.effect_stones.iter_mut())
            .find(|s| s.template_id == template_id)
    }

    /// Banks one raw copy of `template_id` in `kind`'s collection.
    ///
    /// The first copy becomes the instance (level 1, nothing banked); every
    /// later one increments [`Stone::copies`]. This is the only way a stone
    /// enters the inventory, which is what keeps "one instance per template"
    /// an invariant rather than a convention — a second row for a template the
    /// player already owns is unreachable.
    pub fn grant(&mut self, kind: StoneKind, template_id: StoneTemplateId, tier: StoneTier) {
        if let Some(stone) = self.get_mut(template_id) {
            stone.copies += 1;
            return;
        }
        self.collection_mut(kind)
            .push(Stone::new(template_id, tier));
    }

    /// The stone currently sitting in `key`, if any.
    pub fn socketed(&self, key: StoneSocketKey) -> Option<&Stone> {
        self.all()
            .find(|(_, stone)| stone.socket == Some(key))
            .map(|(_, stone)| stone)
    }

    /// Inserts the player's instance of `template_id` into a socket.
    /// `unlocked` decides whether the socket is available yet — the schedule
    /// itself lives in config, so this type stays free of chapter arithmetic.
    ///
    /// A template has exactly one instance, so socketing it twice is refused
    /// with [`StoneError::AlreadySocketed`]. An occupied socket is swapped, not
    /// refused: the sitting stone returns whole to the collection.
    ///
    /// Stones may be changed at any time, including mid-fight, so there is no
    /// combat gate here or in the callers.
    pub fn insert(
        &mut self,
        template_id: StoneTemplateId,
        key: StoneSocketKey,
        unlocked: bool,
    ) -> Result<(), StoneError> {
        if !key.item_type.supports_world_side() {
            return Err(StoneError::SlotHasNoSockets {
                item_type: key.item_type,
            });
        }
        if !unlocked {
            return Err(StoneError::SocketLocked {
                item_type: key.item_type,
                socket: key.socket,
            });
        }
        let kind = self
            .kind_of(template_id)
            .ok_or(StoneError::UnknownStone(template_id))?;
        if kind != key.socket.accepts() {
            return Err(StoneError::WrongCollection {
                socket: key.socket,
                expected: key.socket.accepts(),
                actual: kind,
            });
        }
        // Validated before anything is displaced: a refusal after the swap
        // would leave the socket empty and the player worse off than they
        // started.
        match self.get(template_id) {
            None => return Err(StoneError::UnknownStone(template_id)),
            Some(stone) if stone.is_socketed() => {
                return Err(StoneError::AlreadySocketed(template_id));
            }
            Some(_) => {}
        }

        // Fitting onto an occupied socket swaps, and the displaced stone
        // returns whole — nothing is consumed by fitting. Without this there is
        // no way to upgrade a socket at all: one trigger socket per item means
        // a Common fitted early would block every better stone forever.
        if let Some(displaced) = self.socketed(key).map(|stone| stone.template_id)
            && let Some(stone) = self.get_mut(displaced)
        {
            stone.socket = None;
        }

        let stone = self
            .get_mut(template_id)
            .ok_or(StoneError::UnknownStone(template_id))?;
        stone.socket = Some(key);
        Ok(())
    }

    /// Clears a stone's socket. The stone is not moved, copied or re-created —
    /// it was in its collection all along — so nothing about it can be lost.
    /// Returns the socket it was freed from.
    pub fn remove(&mut self, template_id: StoneTemplateId) -> Result<StoneSocketKey, StoneError> {
        let stone = self
            .get_mut(template_id)
            .ok_or(StoneError::UnknownStone(template_id))?;
        stone
            .socket
            .take()
            .ok_or(StoneError::NotSocketed(template_id))
    }

    /// Fills every **open and empty** socket of `item_type` with the best stone
    /// the player is not already wearing, and returns the sockets it filled.
    ///
    /// The caller supplies `is_unlocked` because the unlock schedule lives in
    /// config and this type stays free of chapter arithmetic.
    ///
    /// Locked sockets are skipped and occupied ones are left alone — quick
    /// equip fills gaps, it does not re-shuffle a build. Only unsocketed stones
    /// are candidates, so quick-equipping one item never strips another, and
    /// the pool comes from [`StoneSocketSlot::accepts`], which makes a
    /// wrong-collection pick inexpressible. An empty pool leaves the socket
    /// empty and is not an error.
    ///
    /// Only EMPTY open sockets are filled, each with the BEST usable stone the
    /// player owns loose: highest [`Stone::quality`] — tier first, then level.
    /// `catalog_order` is the canonical catalog sequence, pre-filtered to active
    /// templates by the caller; it decides which templates are eligible at all
    /// and breaks ties between two stones of identical quality, so the pick is
    /// deterministic. An instance already socketed elsewhere is never taken.
    pub fn quick_equip(
        &mut self,
        item_type: ItemType,
        is_unlocked: &dyn Fn(StoneSocketSlot) -> bool,
        catalog_order: &dyn Fn(StoneKind) -> Vec<StoneTemplateId>,
    ) -> Vec<(StoneSocketSlot, StoneTemplateId)> {
        let mut filled = Vec::new();
        if !item_type.supports_world_side() {
            return filled;
        }
        for socket in StoneSocketSlot::iter() {
            let Some(key) = StoneSocketKey::new(item_type, socket) else {
                continue;
            };
            if !is_unlocked(socket) {
                continue;
            }
            if self.socketed(key).is_some() {
                continue;
            }
            let kind = socket.accepts();
            let catalog = catalog_order(kind);
            // `Reverse(rank)` so an earlier catalog position wins a quality tie;
            // `template_id` last makes the maximum unique and the pick stable.
            let Some(template_id) = self
                .collection(kind)
                .iter()
                .filter(|stone| !stone.is_socketed())
                .filter_map(|stone| {
                    let rank = catalog.iter().position(|id| *id == stone.template_id)?;
                    Some((stone.quality(), std::cmp::Reverse(rank), stone.template_id))
                })
                .max()
                .map(|(_, _, template_id)| template_id)
            else {
                continue;
            };
            // `insert` re-checks every rule; a refusal here would be a bug in
            // the selection above, so it is reported rather than swallowed.
            match self.insert(template_id, key, true) {
                Ok(()) => filled.push((socket, template_id)),
                Err(err) => tracing::error!("QuickEquipStones picked an illegal stone: {err}"),
            }
        }
        filled
    }

    /// Raises every stone of `kind` as far as its banked copies reach, and
    /// returns `(template, level before, level after)` for each stone that moved.
    ///
    /// This is the whole of `UpgradeAllTriggerStones` /
    /// `UpgradeAllEffectStones` (design v0.2 §9). `cost` is the ladder rung for
    /// a level (`None` past the cap), supplied by the caller for the same reason
    /// as `quick_equip`'s `is_unlocked`.
    ///
    /// One catalog per call: the screen's button raises the tab the player is
    /// looking at, so a Trigger upgrade must not quietly spend the copies banked
    /// against Effect stones.
    ///
    /// One stone is taken up **as many levels as it can afford in one call** —
    /// the ladder is cheap at the bottom, so a fresh pile of copies is often
    /// worth several levels and stopping after one would make the button lie.
    /// Socketed and loose stones are treated identically: an upgrade never
    /// touches the socket.
    pub fn upgrade_all(
        &mut self,
        kind: StoneKind,
        max_level: i64,
        cost: &dyn Fn(i64) -> Option<i64>,
    ) -> Vec<(StoneTemplateId, i64, i64)> {
        let templates: Vec<StoneTemplateId> = self
            .all()
            .filter(|(stone_kind, _)| *stone_kind == kind)
            .map(|(_, s)| s.template_id)
            .collect();
        let mut upgraded = Vec::new();
        for template_id in templates {
            // The level it started at, so the caller can report "3 -> 5" rather
            // than just where it landed.
            let Some(started_at) = self.get(template_id).map(|stone| stone.level) else {
                continue;
            };
            let mut reached = None;
            // Loop, not one step: level 2 may cost 2 copies and level 3 three,
            // so a bank of 5 is worth two levels at once.
            while let Some(stone) = self.get(template_id) {
                let Some(required) = cost(stone.level + 1) else {
                    break;
                };
                match self.upgrade(template_id, required, max_level) {
                    Ok(level) => reached = Some(level),
                    Err(_) => break,
                }
            }
            if let Some(level) = reached {
                upgraded.push((template_id, started_at, level));
            }
        }
        upgraded
    }

    /// Spends `required` banked copies to take `template_id` up one level.
    ///
    /// `required` is the rung of the config ladder for the level being bought
    /// (`StonesSettings::upgrade_copies_required`) — the cost is per level and
    /// this type never guesses it.
    ///
    /// Copies are a count, so a copy earned at level 1 pays for level 4 like
    /// any other. Only `level` and `copies` move, leaving `template_id`, `tier`
    /// and `socket` untouched, so a socketed stone upgrades in place. Every
    /// refusal returns before the first mutation, so a short bank is left
    /// exactly as it was.
    pub fn upgrade(
        &mut self,
        template_id: StoneTemplateId,
        required: i64,
        max_level: i64,
    ) -> Result<i64, StoneError> {
        let stone = self
            .get_mut(template_id)
            .ok_or(StoneError::UnknownStone(template_id))?;

        if stone.level >= max_level {
            return Err(StoneError::AlreadyMaxLevel(template_id, max_level));
        }
        let next_level = stone.level + 1;
        if stone.copies < required {
            return Err(StoneError::NotEnoughCopies {
                stone: template_id,
                level: next_level,
                required,
                held: stone.copies,
            });
        }

        stone.copies -= required;
        stone.level = next_level;
        Ok(next_level)
    }
}

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

    const TRIGGER: u128 = 100;
    const OTHER_TRIGGER: u128 = 101;
    const EFFECT: u128 = 200;

    fn template(n: u128) -> StoneTemplateId {
        Uuid::from_u128(n)
    }

    fn stone(template_id: u128, copies: i64) -> Stone {
        let mut stone = Stone::new(template(template_id), StoneTier::Common);
        stone.copies = copies;
        stone
    }

    /// One trigger and one effect stone, each with copies banked — the shape
    /// the design describes: one instance, a warehouse of copies next to it.
    fn inventory() -> StoneInventory {
        StoneInventory {
            trigger_stones: vec![stone(TRIGGER, 2)],
            effect_stones: vec![stone(EFFECT, 2)],
        }
    }

    #[test]
    fn only_the_five_two_sided_slots_have_sockets() {
        let sockets = StoneSocketKey::all();
        assert_eq!(sockets.len(), 15, "5 two-sided slots × 3 sockets");
        for socket in &sockets {
            assert!(socket.item_type.supports_world_side());
        }
        assert!(StoneSocketKey::new(ItemType::Ring, StoneSocketSlot::Trigger).is_none());
    }

    #[test]
    fn the_trigger_is_shared_and_the_two_effect_sides_are_separate() {
        assert_eq!(StoneSocketSlot::Trigger.world_side(), None);
        assert_eq!(
            StoneSocketSlot::effect_for(WorldSide::Real),
            StoneSocketSlot::RealEffect
        );
        assert_eq!(
            StoneSocketSlot::effect_for(WorldSide::Fantasy),
            StoneSocketSlot::FantasyEffect
        );
        assert_ne!(
            StoneSocketSlot::RealEffect,
            StoneSocketSlot::FantasyEffect,
            "each side keeps its own effect"
        );
    }

    #[test]
    fn a_trigger_stone_does_not_fit_an_effect_socket() {
        let mut inv = inventory();
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::RealEffect).unwrap();
        let err = inv.insert(template(TRIGGER), key, true).unwrap_err();
        assert!(matches!(err, StoneError::WrongCollection { .. }));

        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        let err = inv.insert(template(EFFECT), key, true).unwrap_err();
        assert!(matches!(err, StoneError::WrongCollection { .. }));
    }

    #[test]
    fn a_locked_socket_refuses_the_stone() {
        let mut inv = inventory();
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        assert!(matches!(
            inv.insert(template(TRIGGER), key, false),
            Err(StoneError::SocketLocked { .. })
        ));
        assert!(inv.get(template(TRIGGER)).unwrap().socket.is_none());
    }

    #[test]
    fn a_removed_stone_returns_to_inventory_intact() {
        let mut inv = inventory();
        let before = inv.get(template(TRIGGER)).unwrap().clone();
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();

        inv.insert(template(TRIGGER), key, true).unwrap();
        assert_eq!(
            inv.socketed(key).map(|s| s.template_id),
            Some(template(TRIGGER))
        );

        assert_eq!(inv.remove(template(TRIGGER)).unwrap(), key);
        assert_eq!(inv.trigger_stones.len(), 1, "nothing was consumed");
        assert_eq!(
            inv.get(template(TRIGGER)).unwrap(),
            &before,
            "the stone comes back exactly as it went in, copies included"
        );
        assert!(inv.socketed(key).is_none());
    }

    #[test]
    fn a_socket_holds_one_stone_at_a_time() {
        let mut inv = inventory();
        inv.grant(StoneKind::Trigger, template(OTHER_TRIGGER), StoneTier::Rare);
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(TRIGGER), key, true).unwrap();

        // The socket still holds exactly one stone — the newcomer — and the
        // one it displaced is back in the collection, unsocketed and whole.
        inv.insert(template(OTHER_TRIGGER), key, true).unwrap();

        assert_eq!(
            inv.socketed(key).unwrap().template_id,
            template(OTHER_TRIGGER)
        );
        assert_eq!(inv.get(template(TRIGGER)).unwrap().socket, None);
        assert_eq!(
            inv.all().filter(|(_, s)| s.socket == Some(key)).count(),
            1,
            "a swap must not leave two stones claiming the same socket"
        );
    }

    /// One instance per template means one socket per template. The designer
    /// accepted this when choosing the copy-count model: the same stone cannot
    /// be worn on two pieces of gear.
    #[test]
    fn one_template_cannot_be_socketed_in_two_slots() {
        let mut inv = inventory();
        let weapon = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        let gloves = StoneSocketKey::new(ItemType::Gloves, StoneSocketSlot::Trigger).unwrap();

        inv.insert(template(TRIGGER), weapon, true).unwrap();
        assert_eq!(
            inv.insert(template(TRIGGER), gloves, true),
            Err(StoneError::AlreadySocketed(template(TRIGGER))),
        );
        assert_eq!(
            inv.get(template(TRIGGER)).unwrap().socket,
            Some(weapon),
            "the refused second insert left the first socket alone"
        );
        assert!(inv.socketed(gloves).is_none());
    }

    /// A copy of a template the player already owns raises the count instead of
    /// creating a second instance.
    #[test]
    fn a_repeat_drop_banks_a_copy_instead_of_a_second_instance() {
        let mut inv = StoneInventory::default();

        inv.grant(StoneKind::Trigger, template(TRIGGER), StoneTier::Common);
        assert_eq!(inv.trigger_stones.len(), 1);
        assert_eq!(inv.trigger_stones[0].level, 1);
        assert_eq!(
            inv.trigger_stones[0].copies, 0,
            "the first copy IS the instance"
        );

        inv.grant(StoneKind::Trigger, template(TRIGGER), StoneTier::Common);
        inv.grant(StoneKind::Trigger, template(TRIGGER), StoneTier::Common);
        assert_eq!(inv.trigger_stones.len(), 1, "still one instance");
        assert_eq!(inv.trigger_stones[0].copies, 2);

        // A different template is a different instance, in its own collection.
        inv.grant(StoneKind::Effect, template(EFFECT), StoneTier::Rare);
        assert_eq!(inv.trigger_stones.len(), 1);
        assert_eq!(inv.effect_stones.len(), 1);
    }

    /// A drop of a socketed stone banks a copy without touching the socket.
    #[test]
    fn a_repeat_drop_leaves_the_socket_alone() {
        let mut inv = inventory();
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(TRIGGER), key, true).unwrap();

        inv.grant(StoneKind::Trigger, template(TRIGGER), StoneTier::Common);

        let stone = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(stone.socket, Some(key));
        assert_eq!(stone.copies, 3);
    }

    /// The whole point of the raw-copies rule: the cost is per level and comes
    /// from the caller's ladder, and the stone keeps everything but its level.
    #[test]
    fn an_upgrade_spends_copies_and_keeps_the_stone() {
        let mut inv = inventory();
        inv.trigger_stones[0].copies = 5;

        assert_eq!(inv.upgrade(template(TRIGGER), 2, 10), Ok(2));
        let stone = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(stone.level, 2);
        assert_eq!(stone.copies, 3, "exactly the rung's cost was spent");
        assert_eq!(stone.template_id, template(TRIGGER));
        assert_eq!(stone.tier, StoneTier::Common);

        // The next rung costs something different — the ladder, not a constant.
        assert_eq!(inv.upgrade(template(TRIGGER), 3, 10), Ok(3));
        assert_eq!(inv.get(template(TRIGGER)).unwrap().copies, 0);
        assert_eq!(
            inv.effect_stones[0].copies, 2,
            "the other collection is untouched"
        );
    }

    /// A socketed stone upgrades in place — the socket is not disturbed and the
    /// player does not have to unequip first.
    #[test]
    fn a_socketed_stone_upgrades_in_place() {
        let mut inv = inventory();
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(TRIGGER), key, true).unwrap();

        assert_eq!(inv.upgrade(template(TRIGGER), 2, 10), Ok(2));

        let stone = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(stone.level, 2);
        assert_eq!(stone.socket, Some(key), "the socket survived the upgrade");
        assert_eq!(inv.socketed(key).map(|s| s.level), Some(2));
    }

    /// A short bank is refused and spends nothing — no partial deduction.
    #[test]
    fn a_short_bank_is_refused_without_spending_anything() {
        let mut inv = inventory();
        assert_eq!(
            inv.upgrade(template(TRIGGER), 3, 10),
            Err(StoneError::NotEnoughCopies {
                stone: template(TRIGGER),
                level: 2,
                required: 3,
                held: 2,
            })
        );

        let stone = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(stone.copies, 2, "nothing was spent");
        assert_eq!(stone.level, 1);
    }

    #[test]
    fn an_upgrade_stops_at_the_maximum_level() {
        let mut inv = inventory();
        inv.trigger_stones[0].level = 10;
        inv.trigger_stones[0].copies = 99;

        assert_eq!(
            inv.upgrade(template(TRIGGER), 2, 10),
            Err(StoneError::AlreadyMaxLevel(template(TRIGGER), 10))
        );
        assert_eq!(inv.trigger_stones[0].copies, 99, "nothing was spent");
    }

    #[test]
    fn upgrading_a_stone_the_player_does_not_own_is_refused() {
        let mut inv = inventory();
        assert_eq!(
            inv.upgrade(template(OTHER_TRIGGER), 2, 10),
            Err(StoneError::UnknownStone(template(OTHER_TRIGGER)))
        );
    }

    /// Copies belong to one stone of one template, so the two collections can
    /// never fund each other's upgrades.
    #[test]
    fn copies_never_cross_between_the_two_collections() {
        let mut inv = StoneInventory::default();
        inv.grant(StoneKind::Trigger, template(TRIGGER), StoneTier::Common);
        for _ in 0..5 {
            inv.grant(StoneKind::Effect, template(EFFECT), StoneTier::Rare);
        }

        // The effect stone's bank cannot pay for a trigger level.
        assert!(matches!(
            inv.upgrade(template(TRIGGER), 2, 10),
            Err(StoneError::NotEnoughCopies { held: 0, .. })
        ));
        assert_eq!(inv.effect_stones[0].copies, 4, "the effect bank is intact");

        // And the effect stone spends only its own.
        assert_eq!(inv.upgrade(template(EFFECT), 2, 10), Ok(2));
        assert_eq!(inv.effect_stones[0].copies, 2);
        assert_eq!(inv.trigger_stones[0].level, 1);
    }

    /// Design v0.2 §8: "best" is tier first, then level. A level-10 Common
    /// loses to a level-1 Legendary.
    #[test]
    fn quality_ranks_tier_above_level() {
        let mut common = Stone::new(template(1), StoneTier::Common);
        common.level = 10;
        let legendary = Stone::new(template(2), StoneTier::Legendary);
        assert!(legendary.quality() > common.quality());

        // Within one tier, level decides.
        let mut rare_low = Stone::new(template(3), StoneTier::Rare);
        rare_low.level = 2;
        let mut rare_high = Stone::new(template(4), StoneTier::Rare);
        rare_high.level = 3;
        assert!(rare_high.quality() > rare_low.quality());
    }

    fn tiered(template_id: u128, kind: StoneKind, tier: StoneTier) -> Stone {
        let _ = kind;
        Stone::new(template(template_id), tier)
    }

    /// Acceptance criterion #10: only the open sockets of the named item are
    /// filled, and a stone worn on other gear is never taken.
    #[test]
    fn quick_equip_fills_open_sockets_of_one_item_only() {
        let mut inv = StoneInventory {
            trigger_stones: vec![
                tiered(1, StoneKind::Trigger, StoneTier::Common),
                tiered(2, StoneKind::Trigger, StoneTier::Legendary),
            ],
            effect_stones: vec![
                tiered(10, StoneKind::Effect, StoneTier::Rare),
                tiered(11, StoneKind::Effect, StoneTier::Epic),
                tiered(12, StoneKind::Effect, StoneTier::Common),
            ],
        };
        // The epic effect is already worn on another item and must stay there.
        let gloves = StoneSocketKey::new(ItemType::Gloves, StoneSocketSlot::RealEffect).unwrap();
        inv.insert(template(11), gloves, true).unwrap();

        // Only the trigger and the Real effect socket of the weapon are open.
        // The pick is the BEST usable stone: the Legendary trigger wins even
        // though the Common one comes first in the catalog, and the Epic effect
        // is unavailable, so the Rare beats the Common.
        let order = |kind: StoneKind| -> Vec<StoneTemplateId> {
            match kind {
                StoneKind::Trigger => vec![template(1), template(2)],
                StoneKind::Effect => vec![template(10), template(11), template(12)],
            }
        };
        let filled = inv.quick_equip(
            ItemType::Weapon,
            &|socket| socket != StoneSocketSlot::FantasyEffect,
            &order,
        );

        assert_eq!(
            filled,
            vec![
                (StoneSocketSlot::Trigger, template(2)),
                (StoneSocketSlot::RealEffect, template(10)),
            ],
            "highest-tier trigger, highest-tier FREE effect"
        );
        assert!(
            inv.socketed(
                StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::FantasyEffect).unwrap()
            )
            .is_none(),
            "a locked socket is never filled"
        );
        assert_eq!(
            inv.get(template(11)).unwrap().socket,
            Some(gloves),
            "a stone worn on other gear is not moved"
        );
    }

    /// Acceptance criterion #11: nothing to equip is a quiet no-op, and an
    /// occupied socket is left as the player arranged it.
    #[test]
    fn quick_equip_leaves_a_socket_empty_when_nothing_fits() {
        let mut inv = StoneInventory {
            trigger_stones: vec![tiered(1, StoneKind::Trigger, StoneTier::Common)],
            effect_stones: Vec::new(),
        };
        let trigger_key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(1), trigger_key, true).unwrap();

        // Every socket open, but the only trigger is already in place and there
        // are no effect stones at all.
        let order = |kind: StoneKind| -> Vec<StoneTemplateId> {
            match kind {
                StoneKind::Trigger => vec![template(1)],
                StoneKind::Effect => Vec::new(),
            }
        };
        let filled = inv.quick_equip(ItemType::Weapon, &|_| true, &order);

        assert!(filled.is_empty(), "nothing to do, and nothing broke");
        assert_eq!(inv.get(template(1)).unwrap().socket, Some(trigger_key));

        // An item type with no sockets at all is also a no-op.
        assert!(
            inv.quick_equip(ItemType::Ring, &|_| true, &order)
                .is_empty()
        );
    }

    /// Two fitted stones trading sockets. The client sends remove/remove then
    /// insert/insert, because an insert onto a stone that is still socketed
    /// anywhere is refused — this pins that the sequence really does exchange
    /// them rather than emptying one side.
    #[test]
    fn two_socketed_stones_can_trade_places() {
        let mut inv = StoneInventory {
            trigger_stones: Vec::new(),
            effect_stones: vec![
                tiered(1, StoneKind::Effect, StoneTier::Rare),
                tiered(2, StoneKind::Effect, StoneTier::Epic),
            ],
        };
        let left = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::RealEffect).unwrap();
        let right = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::FantasyEffect).unwrap();
        inv.insert(template(1), left, true).unwrap();
        inv.insert(template(2), right, true).unwrap();

        // exactly what dragging left onto right sends
        inv.remove(template(1)).unwrap();
        inv.remove(template(2)).unwrap();
        inv.insert(template(1), right, true).unwrap();
        inv.insert(template(2), left, true).unwrap();

        assert_eq!(inv.socketed(right).unwrap().template_id, template(1));
        assert_eq!(
            inv.socketed(left).unwrap().template_id,
            template(2),
            "the displaced stone takes the vacated socket, it does not fall out"
        );
    }

    /// BAL-018: Quick Equip never touches an occupied socket — the player's
    /// arrangement stands, and no tier ranking exists to "upgrade" against.
    #[test]
    fn quick_equip_leaves_an_occupied_socket_alone() {
        let mut inv = StoneInventory {
            trigger_stones: vec![
                tiered(1, StoneKind::Trigger, StoneTier::Common),
                tiered(2, StoneKind::Trigger, StoneTier::Legendary),
            ],
            effect_stones: Vec::new(),
        };
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(1), key, true).unwrap();

        let order = |kind: StoneKind| -> Vec<StoneTemplateId> {
            match kind {
                StoneKind::Trigger => vec![template(2), template(1)],
                StoneKind::Effect => Vec::new(),
            }
        };
        let filled = inv.quick_equip(
            ItemType::Weapon,
            &|socket| socket == StoneSocketSlot::Trigger,
            &order,
        );

        assert!(
            filled.is_empty(),
            "an occupied socket is left as the player arranged it"
        );
        assert_eq!(inv.socketed(key).unwrap().template_id, template(1));
        assert_eq!(
            inv.get(template(2)).unwrap().socket,
            None,
            "the Legendary spare stays in the collection"
        );
    }

    /// Acceptance criterion #12: one call climbs several rungs when the bank
    /// allows, and stops exactly where it runs out.
    #[test]
    fn upgrade_all_climbs_several_levels_in_one_call() {
        let ladder = |level: i64| match level {
            2 => Some(2),
            3 => Some(3),
            4 => Some(5),
            _ => None,
        };
        let mut inv = StoneInventory {
            // 5 copies pay for level 2 (2) and level 3 (3), then stop.
            trigger_stones: vec![stone(TRIGGER, 5)],
            // 1 copy is not enough for level 2 at all.
            effect_stones: vec![stone(EFFECT, 1)],
        };

        let upgraded = inv.upgrade_all(StoneKind::Trigger, 4, &ladder);

        assert_eq!(
            upgraded,
            vec![(template(TRIGGER), 1, 3)],
            "reported as from-level 1 to level 3, not just where it landed"
        );
        let trigger = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(trigger.level, 3);
        assert_eq!(trigger.copies, 0);
        let effect = inv.get(template(EFFECT)).unwrap();
        assert_eq!(effect.level, 1, "a short bank buys nothing");
        assert_eq!(effect.copies, 1, "and spends nothing");
    }

    /// One call raises one catalog: the screen's button acts on the open tab, so
    /// a Trigger upgrade must not spend what is banked against Effect stones.
    #[test]
    fn upgrade_all_touches_only_the_requested_kind() {
        let mut inv = inventory();
        inv.trigger_stones[0].copies = 1_000;
        inv.effect_stones[0].copies = 1_000;

        let upgraded = inv.upgrade_all(StoneKind::Trigger, 3, &|_| Some(1));

        assert_eq!(
            upgraded,
            vec![(template(TRIGGER), 1, 3)],
            "only the Trigger catalog is reported"
        );
        let effect = inv.get(template(EFFECT)).unwrap();
        assert_eq!(effect.level, 1, "the Effect stone did not move");
        assert_eq!(effect.copies, 1_000, "and its bank is untouched");

        let upgraded = inv.upgrade_all(StoneKind::Effect, 3, &|_| Some(1));

        assert_eq!(upgraded, vec![(template(EFFECT), 1, 3)]);
        assert_eq!(
            inv.get(template(TRIGGER)).unwrap().level,
            3,
            "the Trigger stone kept the level the first call gave it"
        );
    }

    /// The cap and the socket both survive an upgrade-all.
    #[test]
    fn upgrade_all_respects_the_cap_and_keeps_sockets() {
        let mut inv = inventory();
        inv.trigger_stones[0].copies = 1_000;
        let key = StoneSocketKey::new(ItemType::Weapon, StoneSocketSlot::Trigger).unwrap();
        inv.insert(template(TRIGGER), key, true).unwrap();

        let upgraded = inv.upgrade_all(StoneKind::Trigger, 3, &|_| Some(1));

        assert_eq!(upgraded, vec![(template(TRIGGER), 1, 3)]);
        let trigger = inv.get(template(TRIGGER)).unwrap();
        assert_eq!(trigger.level, 3, "stops at the cap, not at the bank");
        assert_eq!(trigger.socket, Some(key), "the socket survived");
    }
}