fix: SET_BONUSES dropped the 2nd stat of multi-stat sets

Deep set-mechanics investigation (user flagged shallow understanding). IL2CPP
ArtifactSetInfo has a List<StatBonus> StatBonuses, but our extraction only kept
the singular StatBonus (first stat). So 8 multi-stat sets lost their 2nd stat in
SET_BONUSES: Perception (+40 ACC AND +5% SPD) kept only ACC; Lethal (ATK+CR),
CritDmg+Speed, Speed+Resistance, HpAndDefence, ResistAndDef, StaminaSpdAcc,
CritDmg+IgnoreDef all dropped a stat. The optimizer + fallback stat-calc
undercounted them (my Venom SPD opt was missing Perception/CritDmgSpeed +5% SPD).

Fix: gear_constants now merges the full plural stat_bonuses from
artifact_sets.json (which has it, from /artifact-sets-truth); refresh_artifact_
truth.py now emits stat_bonuses (plural) so artifact_rules.json carries it too.
Default calc_stats path (sim) unaffected — it uses the mod's artifact_bonus
column; only the optimizer (hypothetical) + fallback use SET_BONUSES. Regression
unchanged (same 2 pre-existing failures). Optimizer now uses Perception sets for
combined ACC+SPD builds.

Also documented full set taxonomy (single/multi-stat/proc/accessory sets,
stacking by complete-set count) in project_artifact_set_mechanics_gametruth.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: SnoopLawg

tools/gear_constants.py

@@ -4,10 +4,25 @@
 All slot IDs, stat IDs, set IDs, and mapping tables in ONE place.
 Import from here — do NOT hardcode these values in other files.
 
-Source: IL2CPP dump (ArtifactKindId, ArtifactStatKindId, StatKindId, ArtifactSetKindId)
-Verified: 2026-04-11 against Teodor the Savant's in-game artifacts.
+Source of truth:
+  - data/static/artifact_rules.json (live game data via mod static-export)
+  - regenerated by `python3 tools/refresh_artifact_truth.py`
+  - falls back to embedded constants if the JSON is missing/stale
+
+What's tracked here (game-truth, not handmade):
+  - SLOT_*: integer enum (1..9 incl. Cloak/Banner)
+  - VALID_PRIMARIES: per-slot primary stats allowed by the game
+  - VALID_SUBSTATS: per-slot substats allowed by the game
+  - SET_NAMES: id → in-game UI name (Speed, Lifesteal, Toxic, Frenzied, etc.)
+  - SET_INTERNAL_NAMES: id → Plarium internal enum name (AttackSpeed, LifeDrain, …)
+
+Slot naming note: the game's static data uses "Cloak" for slot 8;
+some legacy code refers to it as "Amulet". Both names work via alias.
 """
 
+from pathlib import Path
+import json as _json
+
 # =============================================================================
 # Artifact Slot (ArtifactKindId enum from dump line 335xxx)
 # =============================================================================
@@ -18,13 +33,18 @@
 SLOT_WEAPON = 5
 SLOT_SHIELD = 6
 SLOT_RING = 7
-SLOT_AMULET = 8  # "Cloak" in game code
+SLOT_AMULET = 8    # canonical name (in-game UI shows "Amulet")
+SLOT_CLOAK = 8     # alias for the Plarium-internal "Cloak" enum (same slot)
 SLOT_BANNER = 9
 
 SLOT_NAMES = {
     1: "Helmet", 2: "Chest", 3: "Gloves", 4: "Boots",
     5: "Weapon", 6: "Shield", 7: "Ring", 8: "Amulet", 9: "Banner",
 }
+# Reverse lookup (handles both the in-game UI name "Amulet" AND Plarium's
+# internal static-data name "Cloak" — both map to slot 8).
+SLOT_BY_NAME = {v: k for k, v in SLOT_NAMES.items()}
+SLOT_BY_NAME["Cloak"] = SLOT_AMULET  # static export uses "Cloak"; game UI says "Amulet"
 
 SLOT_NAMES_SHORT = {
     1: "Hlm", 2: "Cht", 3: "Glv", 4: "Bts",
@@ -36,19 +56,67 @@
 # Accessory slots (faction-locked)
 ACCESSORY_SLOTS = {SLOT_RING, SLOT_AMULET, SLOT_BANNER}
 
-# Which primary stat types are valid per slot
-# Source: Raid game rules
-VALID_PRIMARIES = {
-    SLOT_WEAPON: ["ATK_flat"],                                        # always ATK flat
-    SLOT_HELMET: ["HP_flat"],                                         # always HP flat
-    SLOT_SHIELD: ["DEF_flat", "HP%", "DEF%", "ATK%", "CR%", "CD%"],  # DEF flat base + ascension options
-    SLOT_GLOVES: ["HP%", "ATK%", "DEF%", "CD%", "HP_flat", "ATK_flat", "DEF_flat"],
-    SLOT_CHEST: ["HP%", "ATK%", "DEF%", "ACC", "RES", "HP_flat", "ATK_flat", "DEF_flat"],
-    SLOT_BOOTS: ["SPD", "HP%", "ATK%", "DEF%", "HP_flat", "ATK_flat", "DEF_flat"],
-    SLOT_RING: ["HP_flat", "ATK_flat", "DEF_flat"],
-    SLOT_AMULET: ["HP_flat", "ATK_flat", "DEF_flat", "CD%"],
-    SLOT_BANNER: ["ACC", "RES", "HP_flat", "ATK_flat", "DEF_flat"],
-}
+
+# Stat name encoded as "<STAT>" for flat or "<STAT>%" for percent.
+# We use these strings in VALID_PRIMARIES / VALID_SUBSTATS for clarity.
+def _stat_label(stat_kind_id: str, is_flat: bool) -> str:
+    base = {"Health": "HP", "Attack": "ATK", "Defence": "DEF",
+            "Speed": "SPD", "Resistance": "RES", "Accuracy": "ACC",
+            "CriticalChance": "CR", "CriticalDamage": "CD"}.get(stat_kind_id, stat_kind_id)
+    # Speed/ACC/RES are always flat in Raid; CR/CD are always %.
+    if base in ("SPD", "RES", "ACC"):
+        return base
+    if base in ("CR", "CD"):
+        return base + "%"
+    return base + ("" if is_flat else "%")
+
+
+# Load primary + substat rules from the artifact_rules.json file (game truth).
+# Schema: list of {stat, is_flat, slots: [SlotName, ...]}.
+# Fall back to a hand-written table if the file is missing.
+VALID_PRIMARIES: dict[int, list[str]] = {s: [] for s in SLOT_NAMES}
+VALID_SUBSTATS: dict[int, list[str]] = {s: [] for s in SLOT_NAMES}
+
+_RULES_PATH = Path(__file__).resolve().parent.parent / "data" / "static" / "artifact_rules.json"
+_rules_loaded = False
+if _RULES_PATH.exists():
+    try:
+        _rules = _json.loads(_RULES_PATH.read_text(encoding="utf-8"))
+        for entry in _rules.get("primary_rules", []):
+            label = _stat_label(entry["stat"], entry["is_flat"])
+            for slot_name in entry.get("slots", []):
+                slot_id = SLOT_BY_NAME.get(slot_name)
+                if slot_id and label not in VALID_PRIMARIES[slot_id]:
+                    VALID_PRIMARIES[slot_id].append(label)
+        for entry in _rules.get("substat_rules", []):
+            label = _stat_label(entry["stat"], entry["is_flat"])
+            for slot_name in entry.get("slots", []):
+                slot_id = SLOT_BY_NAME.get(slot_name)
+                if slot_id and label not in VALID_SUBSTATS[slot_id]:
+                    VALID_SUBSTATS[slot_id].append(label)
+        _rules_loaded = True
+    except Exception as _e:
+        # Don't crash the import; fall back below
+        import sys as _sys
+        print(f"[gear_constants] WARN: failed to load {_RULES_PATH.name}: {_e}",
+              file=_sys.stderr)
+
+if not _rules_loaded:
+    # Fallback: hand-coded primary rules. Substats stay empty so callers
+    # can detect the stale state. Run `python3 tools/refresh_artifact_truth.py`
+    # to populate from live game data.
+    VALID_PRIMARIES = {
+        SLOT_HELMET: ["HP"],
+        SLOT_CHEST:  ["HP", "HP%", "ATK", "ATK%", "DEF", "DEF%", "RES", "ACC"],
+        SLOT_GLOVES: ["HP", "HP%", "ATK", "ATK%", "DEF", "DEF%", "CR%", "CD%"],
+        SLOT_BOOTS:  ["HP", "HP%", "ATK", "ATK%", "DEF", "DEF%", "SPD"],
+        SLOT_WEAPON: ["ATK"],
+        SLOT_SHIELD: ["DEF"],
+        SLOT_RING:   ["HP", "ATK", "DEF"],
+        SLOT_CLOAK:  ["HP", "ATK", "DEF", "CD%"],
+        SLOT_BANNER: ["HP", "ATK", "DEF", "RES", "ACC"],
+    }
+    VALID_SUBSTATS = {s: [] for s in SLOT_NAMES}
 
 # =============================================================================
 # Stat IDs (StatKindId — the mod outputs these)
@@ -115,51 +183,101 @@ def to_artifact_stat_kind_id(stat_id, is_flat):
 # SET_BONUSES — derived from static_data so the values are always live-game
 # correct (e.g. Speed = 2-piece +12%, AccuracyAndSpeed = +40 ACC + 5% SPD).
 # =============================================================================
-SET_NAMES = {
-    0: "None",
-    1: "HP", 2: "ATK", 3: "DEF", 4: "Speed", 5: "CritRate", 6: "CritDmg",
-    7: "Accuracy", 8: "Resistance",
-    9: "Lifesteal", 10: "Fury", 11: "Daze", 12: "Cursed", 13: "Frost",
-    14: "Frenzy", 15: "Regeneration", 16: "Toxic", 17: "Shield",
-    18: "Relentless", 19: "Savage", 20: "Destroy", 21: "Stun",
-    22: "Cruel", 23: "Immortal", 24: "DivineSpeed", 25: "DivineCritRate",
-    26: "Stalwart", 27: "DivineLife", 28: "Swift Parry", 29: "Cruel",
-    30: "Regeneration", 33: "Reflex", 34: "Deflection",
-    35: "Resilience", 36: "Deflection", 37: "Immunity", 38: "Perception",
-    40: "Guardian", 41: "Untouchable", 43: "Cruel",
-    44: "Guardian", 46: "Lethal", 47: "Bolster",
-    48: "Bloodthirst", 50: "Curing", 51: "Reaction",
-    53: "Stoneskin", 54: "Protection", 56: "Prowess",
-    57: "Forsaken", 58: "Frostbite", 59: "Affinitybreaker",
-    60: "Bloodshield", 61: "Divine Offense", 62: "Vigor",
-    63: "Fortitude",
-}
-
-SET_KIND_IDS: dict[int, str] = {}     # numeric id → Plarium enum name (e.g. "Hp", "AttackSpeed")
+SET_NAMES: dict[int, str] = {0: "None"}             # id → in-game UI name (Speed, Lifesteal, ...)
+SET_INTERNAL_NAMES: dict[int, str] = {}              # id → Plarium internal enum (Hp, AttackPower, ...)
+SET_PIECES: dict[int, int] = {}                      # id → 2 / 4 (or 0 for special)
+SET_KIND_IDS: dict[int, str] = SET_INTERNAL_NAMES    # legacy alias for existing consumers
 SET_BONUSES: dict[int, tuple[int, dict[int, float]]] = {}
 
+# Prefer the live game-truth file (data/static/artifact_rules.json) which is
+# generated by `tools/refresh_artifact_truth.py`. Falls back to the older
+# static_data module, then to the embedded base-set list.
+if _rules_loaded:
+    for _s in _rules.get("sets", []):
+        _id = _s.get("id")
+        if _id is None: continue
+        SET_NAMES[_id] = _s.get("display_name") or _s.get("internal_name") or "?"
+        SET_INTERNAL_NAMES[_id] = _s.get("internal_name") or ""
+        SET_PIECES[_id] = _s.get("pieces") or 0
+        # Build SET_BONUSES (stat-bonus sets) from the parsed entries.
+        sb = _s.get("stat_bonus")
+        if sb and sb.get("stat"):
+            _stat_id = {"Health": STAT_HP, "Attack": STAT_ATK, "Defence": STAT_DEF,
+                        "Speed": STAT_SPD, "Resistance": STAT_RES, "Accuracy": STAT_ACC,
+                        "CriticalChance": STAT_CR, "CriticalDamage": STAT_CD}.get(sb["stat"])
+            if _stat_id:
+                _val = sb.get("value", 0)
+                if not sb.get("absolute"):
+                    _val = int(round(_val * 100))  # 0.12 → 12
+                SET_BONUSES[_id] = (_s.get("pieces") or 2, {_stat_id: _val})
+
+# MULTI-STAT SET FIX (2026-06-23): artifact_rules.json only carries the SINGULAR
+# `stat_bonus` (the first StatBonus), but the game model (IL2CPP ArtifactSetInfo)
+# has a `List<StatBonus> StatBonuses` — several sets grant TWO stats
+# (Perception = +40 ACC AND +5% SPD, Lethal = +15% ATK AND +5% C.RATE,
+# CritDmg+Speed, Speed+Resistance, HpAndDefence, ResistAndDef, etc.). The full
+# plural list lives in data/static/artifact_sets.json (from /artifact-sets-truth).
+# Merge any missing stats in so SET_BONUSES is the complete game-truth — the
+# gear optimizer + fallback stat calc were silently dropping the 2nd stat.
 try:
-    try:
-        from tools.static_data import default as _sd
-    except ImportError:
-        from static_data import default as _sd  # called from tools/ cwd
-    _static = _sd()
-    for _id, _set in _static.artifact_sets_by_id.items():
-        SET_KIND_IDS[_id] = _set.set
-    SET_BONUSES.update(_static.set_bonus_table())
+    import json as _json
+    from pathlib import Path as _Path
+    _sets_path = _Path(__file__).resolve().parent.parent / "data" / "static" / "artifact_sets.json"
+    if _sets_path.exists():
+        _af = _json.loads(_sets_path.read_text(encoding="utf-8"))
+        _rows = next((v for k, v in _af.items() if k != "_meta" and isinstance(v, list)), [])
+        _name_to_stat = {"Health": STAT_HP, "Attack": STAT_ATK, "Defence": STAT_DEF,
+                         "Speed": STAT_SPD, "Resistance": STAT_RES, "Accuracy": STAT_ACC,
+                         "CriticalChance": STAT_CR, "CriticalDamage": STAT_CD}
+        for _row in _rows:
+            _id = _row.get("id")
+            _full = _row.get("stat_bonuses") or []
+            if _id is None or len(_full) < 1:
+                continue
+            _pieces = _row.get("pieces") or SET_PIECES.get(_id) or 2
+            _stat_map = dict(SET_BONUSES.get(_id, (_pieces, {}))[1])
+            for _b in _full:
+                _sid = _name_to_stat.get(_b.get("stat"))
+                if _sid is None:
+                    continue  # e.g. IgnoreDefence — not a base stat, handled as proc
+                _v = _b.get("value", 0)
+                if not _b.get("absolute"):
+                    _v = round(_v * 100, 2)   # 0.05 -> 5  (percent)
+                _stat_map[_sid] = _v          # game-truth value (overwrites/augments)
+            if _stat_map:
+                SET_BONUSES[_id] = (_pieces, _stat_map)
 except Exception:
-    # Fallback when data/static/artifact_sets.json is missing. Covers the
-    # 8 base stat sets only; proc/combo sets need a static refresh.
-    SET_KIND_IDS.update({
-        1: "Hp", 2: "AttackPower", 3: "Defense", 4: "AttackSpeed",
-        5: "CriticalChance", 6: "CriticalDamage", 7: "Accuracy", 8: "Resistance",
-    })
-    SET_BONUSES.update({
-        1: (2, {STAT_HP: 15}),    2: (2, {STAT_ATK: 15}),
-        3: (2, {STAT_DEF: 15}),   4: (2, {STAT_SPD: 12}),
-        5: (2, {STAT_CR: 12}),    6: (2, {STAT_CD: 20}),
-        7: (2, {STAT_ACC: 40}),   8: (2, {STAT_RES: 40}),
-    })
+    pass  # keep the singular-stat table if the plural file is unavailable
+
+if not SET_BONUSES:
+    # No rules file present — fall back to legacy static_data module.
+    try:
+        try:
+            from tools.static_data import default as _sd
+        except ImportError:
+            from static_data import default as _sd  # called from tools/ cwd
+        _static = _sd()
+        for _id, _set in _static.artifact_sets_by_id.items():
+            SET_INTERNAL_NAMES[_id] = _set.set
+            SET_NAMES.setdefault(_id, _set.set)
+        SET_BONUSES.update(_static.set_bonus_table())
+    except Exception:
+        # Last-resort: the 8 base stat sets only.
+        SET_INTERNAL_NAMES.update({
+            1: "Hp", 2: "AttackPower", 3: "Defense", 4: "AttackSpeed",
+            5: "CriticalChance", 6: "CriticalDamage", 7: "Accuracy", 8: "Resistance",
+        })
+        SET_NAMES.update({
+            1: "Life", 2: "Offense", 3: "Defense", 4: "Speed",
+            5: "Critical Rate", 6: "Critical Damage",
+            7: "Accuracy", 8: "Resistance",
+        })
+        SET_BONUSES.update({
+            1: (2, {STAT_HP: 15}),    2: (2, {STAT_ATK: 15}),
+            3: (2, {STAT_DEF: 15}),   4: (2, {STAT_SPD: 12}),
+            5: (2, {STAT_CR: 12}),    6: (2, {STAT_CD: 20}),
+            7: (2, {STAT_ACC: 40}),   8: (2, {STAT_RES: 40}),
+        })
 
 # Special set flags (tracked but bonuses applied in sim, not stat calc)
 SPECIAL_SETS = {