essences/

artifacts.rs

//! Artifacts — the container a player wears, its six sockets, and the stones
//! that sit in them.
//!
//! This is the data half of the feature (plan part A). Nothing here fires
//! anything: the ownership stat bonus, the World Law and the Aspect rules read
//! exactly these types plus [`configs::artifacts`], and live in
//! `overlord_event_system`.
//!
//! An artifact is its own collection: it is never an [`crate::items::Item`],
//! never occupies a gear slot, and never rolls attributes.
//!
//! Four facts shape everything below:
//!
//! * **One instance per catalog entry, plus a stock of raw copies.** Like
//!   Trigger/Effect Stones, an artifact is identified by its template. A
//!   duplicate drop banks a copy, including after the artifact reaches its
//!   maximum level. An explicit upgrade spends the configured rung; grants
//!   never change a level by themselves.
//! * **Exactly one artifact is worn; every owned artifact pays.** The ownership
//!   stat bonus sums over the whole collection ([`ArtifactCollection::artifacts`]),
//!   while the World Law is read from [`ArtifactCollection::equipped`] only.
//! * **The sockets belong to the player, not to the artifact.** The six
//!   [`ArtifactSocketSlot`]s and the stones in them live on the collection, so
//!   "stones transfer when the artifact is swapped" is true *by construction*:
//!   swapping only rewrites [`ArtifactCollection::equipped`] and cannot touch a
//!   stone.
//! * **Sockets are typed and non-interchangeable.** Which socket a stone fits is
//!   a property of its catalog entry, so a Law stone can never enter an Aspect
//!   socket and vice versa. The right-hand (Law) column exists structurally here
//!   even though its catalog ships empty — its stones need the cores/laws
//!   vertical, which is a separate branch.

use crate::cores::LawTemplateId;
use crate::prelude::*;

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

#[declare]
pub type ArtifactTemplateId = Uuid;

#[declare]
pub type ArtifactStoneTemplateId = Uuid;

/// Which half of the artifact a socket belongs to.
///
/// The two columns never overlap: `Aspect` sockets retune the Trigger/Effect
/// stones worn in gear, `Law` sockets retune the laws and bridges worn in cores.
/// This is a rule, not a coincidence — a stone declares one socket and fits
/// nothing else.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    Display,
    EnumString,
    EnumIter,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum ArtifactSocketColumn {
    /// Left column — acts on gear Effects.
    #[default]
    Aspect,
    /// Right column — acts on Core Laws. Structural in this branch: its stones
    /// need the cores/laws vertical, so its catalog ships empty and its sockets
    /// are scheduled past the end of the campaign.
    Law,
}

/// One of the artifact's six sockets.
///
/// Order is fixed and load-bearing: the whole left column opens before the right
/// one, because a Law stone has nothing to retune until the player owns cores.
/// [`ArtifactSocketSlot::unlock_order`] is that order, and
/// `GameConfig::validate_artifacts` holds the unlock schedule to it.
///
/// 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.
///
/// * `VisibleAspect` — how active gear effects behave.
/// * `HiddenAspect` — what hidden gear effects do.
/// * `FlipAspect` — what happens on the flip itself.
/// * `VisibleLaw` — how active core laws behave.
/// * `HiddenLaw` — what hidden core laws do.
/// * `BridgeLaw` — how bridges work.
#[derive(
    Clone,
    Copy,
    Debug,
    Default,
    Serialize,
    Deserialize,
    PartialEq,
    Eq,
    Hash,
    JsonSchema,
    Tsify,
    Display,
    EnumString,
    EnumIter,
)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum ArtifactSocketSlot {
    #[default]
    VisibleAspect,
    HiddenAspect,
    FlipAspect,
    VisibleLaw,
    HiddenLaw,
    BridgeLaw,
}

impl ArtifactSocketSlot {
    /// The column this socket belongs to. A stone of one column can never enter
    /// a socket of the other.
    pub const fn column(self) -> ArtifactSocketColumn {
        match self {
            Self::VisibleAspect | Self::HiddenAspect | Self::FlipAspect => {
                ArtifactSocketColumn::Aspect
            }
            Self::VisibleLaw | Self::HiddenLaw | Self::BridgeLaw => ArtifactSocketColumn::Law,
        }
    }

    /// Position in the fixed opening order — left column first, then right.
    /// Config may space the chapters however it likes, but never out of this
    /// order.
    pub const fn unlock_order(self) -> u8 {
        match self {
            Self::VisibleAspect => 0,
            Self::HiddenAspect => 1,
            Self::FlipAspect => 2,
            Self::VisibleLaw => 3,
            Self::HiddenLaw => 4,
            Self::BridgeLaw => 5,
        }
    }

    /// All six sockets, in opening order.
    pub fn all() -> Vec<Self> {
        let mut slots: Vec<Self> = Self::iter().collect();
        slots.sort_by_key(|slot| slot.unlock_order());
        slots
    }
}

/// The player's one instance of an artifact template, plus the copies banked
/// against it.
///
/// `level` is 1..=`max_artifact_level`. Copies are banked by
/// [`ArtifactCollection::grant_artifact`] and spent only by an explicit
/// [`ArtifactCollection::upgrade_artifact`] call.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct Artifact {
    pub template_id: ArtifactTemplateId,
    pub level: i64,
    /// Raw copies banked for explicit upgrades. Copies continue accumulating at
    /// the cap so duplicate grants are never silently discarded.
    pub copies: i64,
}

impl Artifact {
    pub const fn new(template_id: ArtifactTemplateId) -> Self {
        Self {
            template_id,
            level: 1,
            copies: 0,
        }
    }
}

/// One artifact stone the player owns, and the socket it currently sits in.
///
/// The socket lives on the stone, exactly like [`crate::stones::Stone`], so a
/// socketed stone never leaves the collection and cannot be lost by any
/// operation — including swapping the worn artifact, which does not read this
/// list at all.
#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactStone {
    pub template_id: ArtifactStoneTemplateId,
    pub level: i64,
    /// Raw copies banked against this stone, spendable on the next level.
    pub copies: i64,
    /// `Some` while socketed. One instance means one socket.
    pub socket: Option<ArtifactSocketSlot>,
    /// The law a right-column (Law) stone acts on. `None` for every Aspect
    /// stone, and for a Law stone the player has not pointed anywhere yet — such
    /// a stone is inert, exactly like an empty socket.
    ///
    /// **The reference is to the LAW, never to a bridge or a link.** A bridge
    /// has no id of its own (`character_law_bridges` is keyed by the law pair)
    /// and v0.2 gives a law exactly one partner
    /// (`mechanics::cores::MAX_BRIDGES_PER_LAW`, `validate_new_bridge`), so "the
    /// bridge that law X is in" is an unambiguous address built out of one law
    /// id. The consequence is deliberate and load-bearing rather than an
    /// accident of the encoding: **if the player tears down the chosen law's
    /// bridge and builds it a new one, the stone follows onto the new bridge by
    /// itself.** Nothing points at the old link, so nothing has to be re-pointed.
    ///
    /// Cleared when the chosen law leaves its slot (the monolith's `unslot`),
    /// so a stone can never hold a reference to a law that is not on a core.
    pub law_target: Option<LawTemplateId>,
}

impl ArtifactStone {
    pub const fn new(template_id: ArtifactStoneTemplateId) -> Self {
        Self {
            template_id,
            level: 1,
            copies: 0,
            socket: None,
            law_target: None,
        }
    }

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

/// Everything a character owns in the artifact system.
#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub struct ArtifactCollection {
    pub artifacts: Vec<Artifact>,
    /// The single worn artifact. `None` before the vertical opens — that player
    /// plays exactly as before, because every artifact read starts here or at an
    /// empty `artifacts`.
    pub equipped: Option<ArtifactTemplateId>,
    /// Owned artifact stones, each carrying its own socket assignment. Not owned
    /// by any artifact: this is what makes the stones survive a swap.
    pub stones: Vec<ArtifactStone>,
}

/// Why an artifact operation was refused. Every variant is a rule from the
/// design doc.
#[derive(Debug, thiserror::Error, PartialEq, Eq)]
pub enum ArtifactError {
    #[error("the player owns no artifact of template {0}")]
    UnknownArtifact(ArtifactTemplateId),
    #[error("the player owns no artifact stone of template {0}")]
    UnknownStone(ArtifactStoneTemplateId),
    #[error("socket {socket} takes a {expected} stone")]
    WrongSocket {
        socket: ArtifactSocketSlot,
        expected: ArtifactSocketSlot,
    },
    #[error("socket {0} is not unlocked yet")]
    SocketLocked(ArtifactSocketSlot),
    #[error("socket {0} already holds a stone")]
    SocketOccupied(ArtifactSocketSlot),
    #[error("artifact stone {0} is already socketed — a template holds at most one socket")]
    AlreadySocketed(ArtifactStoneTemplateId),
    #[error("artifact stone {0} is not socketed")]
    NotSocketed(ArtifactStoneTemplateId),
    #[error("artifact stone {0} sits in an Aspect socket and has no law to choose")]
    NotALawStone(ArtifactStoneTemplateId),
    #[error("law {0} is not slotted on a core, so no artifact stone may point at it")]
    LawNotSlotted(LawTemplateId),
    #[error(
        "upgrading artifact stone {stone} to level {level} needs {required} copies, {held} banked"
    )]
    NotEnoughCopies {
        stone: ArtifactStoneTemplateId,
        level: i64,
        required: i64,
        held: i64,
    },
    #[error("artifact stone {0} is already at the maximum level {1}")]
    AlreadyMaxLevel(ArtifactStoneTemplateId, i64),
    #[error(
        "upgrading artifact {artifact} to level {level} needs {required} copies, {held} banked"
    )]
    NotEnoughArtifactCopies {
        artifact: ArtifactTemplateId,
        level: i64,
        required: i64,
        held: i64,
    },
    #[error("artifact {0} is already at the maximum level {1}")]
    ArtifactAlreadyMaxLevel(ArtifactTemplateId, i64),
    /// The upgrade ladder has no rung for the level being bought.
    /// `GameConfig::validate_artifacts` rules this out at load time.
    #[error("the artifact stone upgrade ladder has no cost for level {0}")]
    NoUpgradeStep(i64),
    #[error("artifacts and their stones may only be changed out of combat")]
    InCombat,
}

impl ArtifactCollection {
    pub fn get(&self, template_id: ArtifactTemplateId) -> Option<&Artifact> {
        self.artifacts
            .iter()
            .find(|artifact| artifact.template_id == template_id)
    }

    fn get_mut(&mut self, template_id: ArtifactTemplateId) -> Option<&mut Artifact> {
        self.artifacts
            .iter_mut()
            .find(|artifact| artifact.template_id == template_id)
    }

    pub fn stone(&self, template_id: ArtifactStoneTemplateId) -> Option<&ArtifactStone> {
        self.stones
            .iter()
            .find(|stone| stone.template_id == template_id)
    }

    fn stone_mut(&mut self, template_id: ArtifactStoneTemplateId) -> Option<&mut ArtifactStone> {
        self.stones
            .iter_mut()
            .find(|stone| stone.template_id == template_id)
    }

    /// The stone sitting in `socket`, if any.
    pub fn socketed(&self, socket: ArtifactSocketSlot) -> Option<&ArtifactStone> {
        self.stones
            .iter()
            .find(|stone| stone.socket == Some(socket))
    }

    /// Grants one artifact copy without performing an upgrade.
    ///
    /// The first grant creates the level-1 instance. Every duplicate only
    /// increments its raw-copy bank, including when the artifact is already at
    /// the level cap.
    ///
    /// The very first artifact a player owns is also WORN. Exactly one artifact
    /// is worn at a time, so a collection that owns something and wears nothing
    /// is not a state the player can produce — [`Self::equip`] has no "take off"
    /// counterpart. Leaving the slot empty read as a bug on the artifact screen,
    /// which then had no worn artifact to open on. This never overrides a
    /// choice: it fires only while [`Self::equipped`] is `None`.
    pub fn grant_artifact(&mut self, template_id: ArtifactTemplateId) {
        if self.equipped.is_none() {
            self.equipped = Some(template_id);
        }

        let Some(artifact) = self.get_mut(template_id) else {
            self.artifacts.push(Artifact::new(template_id));
            return;
        };
        artifact.copies += 1;
    }

    /// Spends exactly one configured rung and raises an artifact one level.
    ///
    /// All refusal checks happen before either field changes, so an unknown
    /// artifact, a capped artifact or a short copy bank is atomic.
    pub fn upgrade_artifact(
        &mut self,
        template_id: ArtifactTemplateId,
        required: i64,
        max_level: i64,
    ) -> Result<i64, ArtifactError> {
        let artifact = self
            .get_mut(template_id)
            .ok_or(ArtifactError::UnknownArtifact(template_id))?;

        if artifact.level >= max_level {
            return Err(ArtifactError::ArtifactAlreadyMaxLevel(
                template_id,
                max_level,
            ));
        }
        let next_level = artifact.level + 1;
        if artifact.copies < required {
            return Err(ArtifactError::NotEnoughArtifactCopies {
                artifact: template_id,
                level: next_level,
                required,
                held: artifact.copies,
            });
        }

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

    /// Wears `template_id`. Exactly one artifact is worn at a time, so this
    /// replaces whatever was worn before; the previous one keeps paying its
    /// ownership bonus and loses only its World Law.
    ///
    /// Socketed stones are deliberately not read here — that is the whole of
    /// "stones transfer to the new artifact".
    pub fn equip(&mut self, template_id: ArtifactTemplateId) -> Result<(), ArtifactError> {
        if self.get(template_id).is_none() {
            return Err(ArtifactError::UnknownArtifact(template_id));
        }
        self.equipped = Some(template_id);
        Ok(())
    }

    /// Banks one raw copy of an artifact stone. The first copy becomes the
    /// instance at level 1; later copies raise [`ArtifactStone::copies`], which
    /// the player spends through an explicit upgrade — same shape as
    /// [`crate::stones::StoneInventory::grant`].
    pub fn grant_stone(&mut self, template_id: ArtifactStoneTemplateId) {
        if let Some(stone) = self.stone_mut(template_id) {
            stone.copies += 1;
            return;
        }
        self.stones.push(ArtifactStone::new(template_id));
        // Keep the collection in template-id order — the order the storage
        // fetch loads it back in — so the in-memory state and a fresh load are
        // byte-identical. Sockets reference stones by template id, so the
        // position of a row is not semantic.
        self.stones.sort_by_key(|stone| stone.template_id);
    }

    /// Puts the player's instance of `template_id` into `socket`.
    ///
    /// `expected` is the socket the stone's catalog entry declares — a stone
    /// fits one socket and no other, which is how the two columns are kept
    /// apart. `unlocked` is the chapter gate; the schedule itself is config, so
    /// this type stays free of chapter arithmetic.
    pub fn insert_stone(
        &mut self,
        template_id: ArtifactStoneTemplateId,
        socket: ArtifactSocketSlot,
        expected: ArtifactSocketSlot,
        unlocked: bool,
    ) -> Result<(), ArtifactError> {
        if socket != expected {
            return Err(ArtifactError::WrongSocket { socket, expected });
        }
        if !unlocked {
            return Err(ArtifactError::SocketLocked(socket));
        }
        if self.stone(template_id).is_none() {
            return Err(ArtifactError::UnknownStone(template_id));
        }
        if self.socketed(socket).is_some() {
            return Err(ArtifactError::SocketOccupied(socket));
        }
        let stone = self
            .stone_mut(template_id)
            .ok_or(ArtifactError::UnknownStone(template_id))?;
        if stone.is_socketed() {
            return Err(ArtifactError::AlreadySocketed(template_id));
        }
        stone.socket = Some(socket);
        Ok(())
    }

    /// Points a right-column stone at one law, or clears its choice (`None`).
    ///
    /// `slotted` is "this law is owned and currently sitting in a core slot",
    /// decided by the caller: the law lives in `CoresState`, which this type
    /// deliberately knows nothing about. `is_law_socket` is the stone's own
    /// column, read from its catalog entry.
    ///
    /// The one check that is NOT made here is a Real/Fantasy match against the
    /// socket. The three Law sockets are Visible / Hidden / Bridge, and
    /// "visible" is a *phase*, not a side: the same law is the visible one while
    /// its side is up and the hidden one while it is down (post-merge plan §8).
    /// So every slotted law is a legal target for every Law socket, and which
    /// half of the fight the stone speaks in is decided by the flip, not by
    /// validation.
    pub fn set_law_target(
        &mut self,
        template_id: ArtifactStoneTemplateId,
        law: Option<LawTemplateId>,
        is_law_socket: bool,
        slotted: bool,
    ) -> Result<(), ArtifactError> {
        if !is_law_socket {
            return Err(ArtifactError::NotALawStone(template_id));
        }
        if let Some(law) = law
            && !slotted
        {
            return Err(ArtifactError::LawNotSlotted(law));
        }
        let stone = self
            .stone_mut(template_id)
            .ok_or(ArtifactError::UnknownStone(template_id))?;
        stone.law_target = law;
        Ok(())
    }

    /// Drops every stone's choice of `law`. Called when the law leaves its slot,
    /// so no stone is ever left pointing at a law that is not on a core.
    ///
    /// Returns whether anything changed, so the caller can skip a write.
    pub fn forget_law_target(&mut self, law: LawTemplateId) -> bool {
        let mut changed = false;
        for stone in &mut self.stones {
            if stone.law_target == Some(law) {
                stone.law_target = None;
                changed = true;
            }
        }
        changed
    }

    /// Clears a stone's socket. The stone stays in the collection with its level
    /// and copies intact.
    pub fn remove_stone(
        &mut self,
        template_id: ArtifactStoneTemplateId,
    ) -> Result<ArtifactSocketSlot, ArtifactError> {
        let stone = self
            .stone_mut(template_id)
            .ok_or(ArtifactError::UnknownStone(template_id))?;
        stone
            .socket
            .take()
            .ok_or(ArtifactError::NotSocketed(template_id))
    }

    /// Spends `required` banked copies to take an artifact stone up one level.
    ///
    /// An upgrade only scales the rule's magnitude — the rule itself came whole
    /// with the first copy (design §3), so nothing here touches the socket, the
    /// template or anything a rule reads besides `level`.
    pub fn upgrade_stone(
        &mut self,
        template_id: ArtifactStoneTemplateId,
        required: i64,
        max_level: i64,
    ) -> Result<i64, ArtifactError> {
        let stone = self
            .stone_mut(template_id)
            .ok_or(ArtifactError::UnknownStone(template_id))?;

        if stone.level >= max_level {
            return Err(ArtifactError::AlreadyMaxLevel(template_id, max_level));
        }
        let next_level = stone.level + 1;
        if stone.copies < required {
            return Err(ArtifactError::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 EMPTY_FRAME: u128 = 900;
    const SECOND_ARTIFACT: u128 = 901;
    const ASPECT_STONE: u128 = 910;
    const OTHER_ASPECT_STONE: u128 = 911;
    const LAW_STONE: u128 = 920;
    const OTHER_LAW_STONE: u128 = 921;
    const CHOSEN_LAW: u128 = 930;
    const OTHER_LAW: u128 = 931;

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

    /// The shipped ladder: level 2 costs one copy, level 3 costs two.
    fn ladder(level: i64) -> Option<i64> {
        match level {
            2 => Some(1),
            3 => Some(2),
            _ => None,
        }
    }

    #[test]
    fn the_six_sockets_open_left_column_first() {
        let all = ArtifactSocketSlot::all();
        assert_eq!(all.len(), 6);
        let columns: Vec<_> = all.iter().map(|slot| slot.column()).collect();
        assert_eq!(
            columns,
            vec![
                ArtifactSocketColumn::Aspect,
                ArtifactSocketColumn::Aspect,
                ArtifactSocketColumn::Aspect,
                ArtifactSocketColumn::Law,
                ArtifactSocketColumn::Law,
                ArtifactSocketColumn::Law,
            ],
            "the whole Aspect column comes before the Law column"
        );
    }

    /// Acceptance criterion 1: many owned, exactly one worn.
    #[test]
    fn exactly_one_artifact_is_worn_while_many_are_owned() {
        let mut collection = ArtifactCollection::default();
        collection.grant_artifact(id(EMPTY_FRAME));
        collection.grant_artifact(id(SECOND_ARTIFACT));
        assert_eq!(collection.artifacts.len(), 2);
        assert_eq!(
            collection.equipped,
            Some(id(EMPTY_FRAME)),
            "the first artifact owned is worn; the second does not take over"
        );

        collection.equip(id(EMPTY_FRAME)).unwrap();
        assert_eq!(collection.equipped, Some(id(EMPTY_FRAME)));

        collection.equip(id(SECOND_ARTIFACT)).unwrap();
        assert_eq!(
            collection.equipped,
            Some(id(SECOND_ARTIFACT)),
            "wearing a second artifact replaces the first, never adds to it"
        );
        assert_eq!(collection.artifacts.len(), 2, "both are still owned");
    }

    /// The worn slot is never empty once the player owns something: the first
    /// grant wears itself, later grants leave the choice alone, and a duplicate
    /// of the worn artifact does not disturb it.
    #[test]
    fn the_first_granted_artifact_is_worn_and_later_grants_do_not_take_over() {
        let mut collection = ArtifactCollection::default();

        collection.grant_artifact(id(SECOND_ARTIFACT));
        assert_eq!(collection.equipped, Some(id(SECOND_ARTIFACT)));

        collection.grant_artifact(id(EMPTY_FRAME));
        assert_eq!(
            collection.equipped,
            Some(id(SECOND_ARTIFACT)),
            "a later grant does not silently swap what the player wears"
        );

        collection.equip(id(EMPTY_FRAME)).unwrap();
        collection.grant_artifact(id(SECOND_ARTIFACT));
        assert_eq!(
            collection.equipped,
            Some(id(EMPTY_FRAME)),
            "a duplicate never overrides an explicit choice"
        );
    }

    #[test]
    fn an_unowned_artifact_cannot_be_worn() {
        let mut collection = ArtifactCollection::default();
        assert_eq!(
            collection.equip(id(SECOND_ARTIFACT)),
            Err(ArtifactError::UnknownArtifact(id(SECOND_ARTIFACT)))
        );
        assert_eq!(collection.equipped, None);
    }

    /// Artifact grants only bank copies. Levels move through the explicit
    /// upgrade path, and a duplicate at the cap is retained.
    #[test]
    fn duplicates_bank_until_explicit_upgrade_including_at_the_cap() {
        let mut collection = ArtifactCollection::default();

        collection.grant_artifact(id(SECOND_ARTIFACT));
        let artifact = collection.get(id(SECOND_ARTIFACT)).unwrap();
        assert_eq!((artifact.level, artifact.copies), (1, 0));

        collection.grant_artifact(id(SECOND_ARTIFACT));
        let artifact = collection.get(id(SECOND_ARTIFACT)).unwrap();
        assert_eq!((artifact.level, artifact.copies), (1, 1));
        assert_eq!(
            collection.upgrade_artifact(id(SECOND_ARTIFACT), ladder(2).unwrap(), 3),
            Ok(2)
        );
        assert_eq!(
            (
                collection.get(id(SECOND_ARTIFACT)).unwrap().level,
                collection.get(id(SECOND_ARTIFACT)).unwrap().copies
            ),
            (2, 0)
        );

        collection.grant_artifact(id(SECOND_ARTIFACT));
        collection.grant_artifact(id(SECOND_ARTIFACT));
        assert_eq!(
            collection.upgrade_artifact(id(SECOND_ARTIFACT), ladder(3).unwrap(), 3),
            Ok(3)
        );

        collection.grant_artifact(id(SECOND_ARTIFACT));
        let artifact = collection.get(id(SECOND_ARTIFACT)).unwrap();
        assert_eq!((artifact.level, artifact.copies), (3, 1));
        assert_eq!(collection.artifacts.len(), 1, "still one instance");
    }

    #[test]
    fn refused_artifact_upgrades_are_atomic() {
        let mut collection = ArtifactCollection::default();
        assert_eq!(
            collection.upgrade_artifact(id(SECOND_ARTIFACT), 1, 3),
            Err(ArtifactError::UnknownArtifact(id(SECOND_ARTIFACT)))
        );

        collection.grant_artifact(id(SECOND_ARTIFACT));
        let before = collection.clone();
        assert_eq!(
            collection.upgrade_artifact(id(SECOND_ARTIFACT), 1, 3),
            Err(ArtifactError::NotEnoughArtifactCopies {
                artifact: id(SECOND_ARTIFACT),
                level: 2,
                required: 1,
                held: 0,
            })
        );
        assert_eq!(collection, before);

        let artifact = collection.get_mut(id(SECOND_ARTIFACT)).unwrap();
        artifact.level = 3;
        artifact.copies = 4;
        let before = collection.clone();
        assert_eq!(
            collection.upgrade_artifact(id(SECOND_ARTIFACT), 2, 3),
            Err(ArtifactError::ArtifactAlreadyMaxLevel(
                id(SECOND_ARTIFACT),
                3
            ))
        );
        assert_eq!(collection, before);
    }

    /// Acceptance criterion 5: a stone fits its own socket and no other.
    #[test]
    fn a_stone_only_fits_the_socket_its_catalog_entry_names() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));

        let err = collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::HiddenAspect,
                ArtifactSocketSlot::VisibleAspect,
                true,
            )
            .unwrap_err();
        assert_eq!(
            err,
            ArtifactError::WrongSocket {
                socket: ArtifactSocketSlot::HiddenAspect,
                expected: ArtifactSocketSlot::VisibleAspect,
            }
        );

        // The whole right column is refused the same way, by the same rule.
        let err = collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::VisibleLaw,
                ArtifactSocketSlot::VisibleAspect,
                true,
            )
            .unwrap_err();
        assert!(matches!(err, ArtifactError::WrongSocket { .. }));
        assert!(collection.stone(id(ASPECT_STONE)).unwrap().socket.is_none());

        collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::VisibleAspect,
                ArtifactSocketSlot::VisibleAspect,
                true,
            )
            .unwrap();
        assert_eq!(
            collection
                .socketed(ArtifactSocketSlot::VisibleAspect)
                .map(|stone| stone.template_id),
            Some(id(ASPECT_STONE))
        );
    }

    /// Acceptance criterion 7: a socket the chapter gate has not opened refuses
    /// the stone and changes nothing.
    #[test]
    fn a_locked_socket_refuses_the_stone() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));

        assert_eq!(
            collection.insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::VisibleAspect,
                ArtifactSocketSlot::VisibleAspect,
                false,
            ),
            Err(ArtifactError::SocketLocked(
                ArtifactSocketSlot::VisibleAspect
            ))
        );
        assert!(collection.stone(id(ASPECT_STONE)).unwrap().socket.is_none());
    }

    #[test]
    fn a_socket_holds_one_stone_at_a_time() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));
        collection.grant_stone(id(OTHER_ASPECT_STONE));

        collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::VisibleAspect,
                ArtifactSocketSlot::VisibleAspect,
                true,
            )
            .unwrap();
        assert_eq!(
            collection.insert_stone(
                id(OTHER_ASPECT_STONE),
                ArtifactSocketSlot::VisibleAspect,
                ArtifactSocketSlot::VisibleAspect,
                true,
            ),
            Err(ArtifactError::SocketOccupied(
                ArtifactSocketSlot::VisibleAspect
            ))
        );
    }

    /// Acceptance criterion 6: swapping the worn artifact leaves every socketed
    /// stone exactly where it was — the swap cannot reach them.
    #[test]
    fn stones_survive_an_artifact_swap() {
        let mut collection = ArtifactCollection::default();
        collection.grant_artifact(id(EMPTY_FRAME));
        collection.grant_artifact(id(SECOND_ARTIFACT));
        collection.grant_stone(id(ASPECT_STONE));
        collection.grant_stone(id(ASPECT_STONE)); // one banked copy
        collection.equip(id(EMPTY_FRAME)).unwrap();
        collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::FlipAspect,
                ArtifactSocketSlot::FlipAspect,
                true,
            )
            .unwrap();
        let before = collection.stone(id(ASPECT_STONE)).unwrap().clone();

        collection.equip(id(SECOND_ARTIFACT)).unwrap();

        assert_eq!(collection.stones.len(), 1);
        assert_eq!(
            collection.stone(id(ASPECT_STONE)).unwrap(),
            &before,
            "level, copies and socket all carried over to the new artifact"
        );
        assert_eq!(
            collection
                .socketed(ArtifactSocketSlot::FlipAspect)
                .map(|stone| stone.template_id),
            Some(id(ASPECT_STONE))
        );
    }

    #[test]
    fn a_removed_stone_keeps_its_level_and_copies() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));
        collection.grant_stone(id(ASPECT_STONE));
        collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::HiddenAspect,
                ArtifactSocketSlot::HiddenAspect,
                true,
            )
            .unwrap();

        assert_eq!(
            collection.remove_stone(id(ASPECT_STONE)).unwrap(),
            ArtifactSocketSlot::HiddenAspect
        );
        let stone = collection.stone(id(ASPECT_STONE)).unwrap();
        assert_eq!((stone.level, stone.copies, stone.socket), (1, 1, None));
    }

    /// Acceptance criterion 9, data half: an upgrade moves the level and
    /// nothing else — the rule and the socket are untouched.
    #[test]
    fn upgrading_a_stone_only_moves_its_level() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));
        for _ in 0..3 {
            collection.grant_stone(id(ASPECT_STONE));
        }
        collection
            .insert_stone(
                id(ASPECT_STONE),
                ArtifactSocketSlot::VisibleAspect,
                ArtifactSocketSlot::VisibleAspect,
                true,
            )
            .unwrap();

        assert_eq!(collection.upgrade_stone(id(ASPECT_STONE), 2, 5), Ok(2));
        let stone = collection.stone(id(ASPECT_STONE)).unwrap();
        assert_eq!(stone.level, 2);
        assert_eq!(stone.copies, 1);
        assert_eq!(
            stone.socket,
            Some(ArtifactSocketSlot::VisibleAspect),
            "an upgrade never disturbs the socket"
        );
    }

    #[test]
    fn a_short_bank_or_a_capped_stone_spends_nothing() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));

        assert_eq!(
            collection.upgrade_stone(id(ASPECT_STONE), 2, 5),
            Err(ArtifactError::NotEnoughCopies {
                stone: id(ASPECT_STONE),
                level: 2,
                required: 2,
                held: 0,
            })
        );
        assert_eq!(collection.stone(id(ASPECT_STONE)).unwrap().copies, 0);

        collection.stone_mut(id(ASPECT_STONE)).unwrap().level = 5;
        collection.stone_mut(id(ASPECT_STONE)).unwrap().copies = 9;
        assert_eq!(
            collection.upgrade_stone(id(ASPECT_STONE), 2, 5),
            Err(ArtifactError::AlreadyMaxLevel(id(ASPECT_STONE), 5))
        );
        assert_eq!(collection.stone(id(ASPECT_STONE)).unwrap().copies, 9);
    }

    /// Right column, data half: the choice is one law id, it only exists on a
    /// Law-column stone, and it must name a law that is actually on a core.
    #[test]
    fn only_a_law_stone_carries_a_chosen_law_and_only_a_slotted_one() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(ASPECT_STONE));
        collection.grant_stone(id(LAW_STONE));
        let law = id(CHOSEN_LAW);

        assert_eq!(
            collection.set_law_target(id(ASPECT_STONE), Some(law), false, true),
            Err(ArtifactError::NotALawStone(id(ASPECT_STONE))),
            "an Aspect stone has no law to choose"
        );
        assert_eq!(
            collection.set_law_target(id(LAW_STONE), Some(law), true, false),
            Err(ArtifactError::LawNotSlotted(law)),
            "a law off the core is not a legal target"
        );
        assert_eq!(collection.stone(id(LAW_STONE)).unwrap().law_target, None);

        collection
            .set_law_target(id(LAW_STONE), Some(law), true, true)
            .unwrap();
        assert_eq!(
            collection.stone(id(LAW_STONE)).unwrap().law_target,
            Some(law)
        );

        // Clearing needs no slotted law: the point is to have none.
        collection
            .set_law_target(id(LAW_STONE), None, true, false)
            .unwrap();
        assert_eq!(collection.stone(id(LAW_STONE)).unwrap().law_target, None);
    }

    /// Taking the chosen law off its core leaves no stone pointing at it — the
    /// "no dangling reference" half of plan §6.1.
    #[test]
    fn forgetting_a_law_clears_every_stone_that_chose_it() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(LAW_STONE));
        collection.grant_stone(id(OTHER_LAW_STONE));
        let law = id(CHOSEN_LAW);
        let other = id(OTHER_LAW);

        collection
            .set_law_target(id(LAW_STONE), Some(law), true, true)
            .unwrap();
        collection
            .set_law_target(id(OTHER_LAW_STONE), Some(other), true, true)
            .unwrap();

        assert!(collection.forget_law_target(law));
        assert_eq!(collection.stone(id(LAW_STONE)).unwrap().law_target, None);
        assert_eq!(
            collection.stone(id(OTHER_LAW_STONE)).unwrap().law_target,
            Some(other),
            "only the unslotted law is forgotten"
        );
        assert!(
            !collection.forget_law_target(law),
            "a second pass has nothing to clear and reports so"
        );
    }

    /// The socket is not part of the choice: unsocketing a stone keeps its law,
    /// exactly as it keeps its level and copies.
    #[test]
    fn unsocketing_a_law_stone_keeps_its_chosen_law() {
        let mut collection = ArtifactCollection::default();
        collection.grant_stone(id(LAW_STONE));
        collection
            .insert_stone(
                id(LAW_STONE),
                ArtifactSocketSlot::VisibleLaw,
                ArtifactSocketSlot::VisibleLaw,
                true,
            )
            .unwrap();
        collection
            .set_law_target(id(LAW_STONE), Some(id(CHOSEN_LAW)), true, true)
            .unwrap();

        collection.remove_stone(id(LAW_STONE)).unwrap();
        let stone = collection.stone(id(LAW_STONE)).unwrap();
        assert_eq!(stone.socket, None);
        assert_eq!(stone.law_target, Some(id(CHOSEN_LAW)));
    }

    /// Acceptance criterion 10, data half: a player who owns nothing has an
    /// empty collection with no worn artifact — every read below starts there
    /// and returns nothing.
    #[test]
    fn a_player_without_artifacts_has_an_inert_collection() {
        let collection = ArtifactCollection::default();
        assert!(collection.artifacts.is_empty());
        assert!(collection.stones.is_empty());
        assert_eq!(collection.equipped, None);
        for socket in ArtifactSocketSlot::all() {
            assert!(collection.socketed(socket).is_none());
        }
    }
}