rakata_generics/decoded/

uti.rs

//! Table-backed decoded views over typed generic models.
//!
//! Typed generic structs (`Uti`, `Utc`, ...) expose engine integers
//! verbatim because the on-disk format does. This module layers a
//! decoded view on top: callers hand in a [`TwoDaSource`] and ask
//! for `view = thing.resolve(&mut tables)`, then query the view with
//! semantics-bearing methods (e.g. `view.is_weapon()`,
//! `view.damage_bonuses()`). The resolved view is built by composing a
//! cheap projection with a per-scope resolution step; see
//! [`UtiProjection`] / [`UtiResolved`] and [`Uti::project`] for the
//! multi-scope path.
//!
//! ## Mod-friendliness
//!
//! Decoding reads against whatever tables the caller hands in, which
//! against a live install means the user's actually-loaded 2DAs.
//! Properties whose `PropertyName` does not resolve in
//! `itempropdef.2da` round-trip into [`DecodedProperty::Unknown`]
//! with `property_label = None`; properties whose row exists but
//! whose label is not yet typed surface as `Unknown` carrying the
//! resolved label so consumers can still display something useful.
//! Subtype `u16` ids stay raw on every variant so mods that extend
//! an existing property's `iprp_*.2da` subtype range do not get
//! downgraded to `Unknown`.

use rakata_core::tables;
use rakata_formats::twoda::{TwoDa, TwoDaSource};

use crate::uti::{Uti, UtiProperty};

/// One decoded item-property entry.
///
/// The shape grows variants as more property kinds get typed; until
/// a variant exists for a given engine kind, callers receive
/// [`DecodedProperty::Unknown`] carrying every raw field plus the
/// human-readable property label resolved from `itempropdef.2da`
/// when reachable.
///
/// ## Subtype dispatch
///
/// The per-property subtype id is preserved as a raw `u16` on every
/// variant. To resolve it to a human-readable label, call
/// [`DecodedProperty::subtype_label`], which walks the dispatch
/// chain documented under "Property Table Dispatch" in the UTI
/// engine audit (`itempropdef.SubTypeResRef` -> per-property
/// `iprp_*.2da` -> `label` column at the subtype row).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DecodedProperty {
    /// Ability-score bonus property (vanilla `itempropdef.2da` label
    /// `Ability`, row 0). The subtype identifies which ability score
    /// the bonus targets; the cost fields carry the magnitude
    /// reference into the cost-table dispatch chain.
    AbilityBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Ability` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_abilities.2da`).
        /// Vanilla rows: 0=STR, 1=DEX, 2=CON, 3=INT, 4=WIS, 5=CHA.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Universal saving-throw bonus property (vanilla
    /// `itempropdef.2da` label `ImprovedSavingThrows`, row 26). The
    /// subtype identifies which save element (Universal, Acid, Cold,
    /// ...) the bonus applies to; the cost fields carry the magnitude
    /// reference into the cost-table dispatch chain.
    ///
    /// This variant covers `ImprovedSavingThrows` only. The narrower
    /// `ImprovedSavingThrowsSpecific` (Fortitude/Reflex/Will) and the
    /// matching `ReducedSavingThrows` / `ReducedSpecificSavingThrow`
    /// kinds remain in `Unknown` until they get their own typed
    /// variants.
    SaveBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ImprovedSavingThrows` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_saveelement.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Specific saving-throw bonus property (vanilla
    /// `itempropdef.2da` label `ImprovedSavingThrowsSpecific`, row
    /// 27). Narrower sibling of [`Self::SaveBonus`]: the subtype
    /// identifies which specific saving throw (Fortitude, Reflex,
    /// Will) the bonus applies to, indexed into
    /// `iprp_savingthrow.2da` rather than the element-based
    /// `iprp_saveelement.2da`.
    SaveBonusSpecific {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ImprovedSavingThrowsSpecific` at decode
        /// time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_savingthrow.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Universal saving-throw penalty property (vanilla
    /// `itempropdef.2da` label `ReducedSavingThrows`, row 33).
    /// Negative mirror of [`Self::SaveBonus`]: same subtype 2DA
    /// (`iprp_saveelement`) but the cost fields carry a penalty
    /// magnitude rather than a bonus.
    SavePenalty {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ReducedSavingThrows` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_saveelement.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Specific saving-throw penalty property (vanilla
    /// `itempropdef.2da` label `ReducedSpecificSavingThrow`, row 34).
    /// Negative mirror of [`Self::SaveBonusSpecific`]: same subtype
    /// 2DA (`iprp_savingthrow`) but the cost fields carry a penalty
    /// magnitude rather than a bonus.
    ///
    /// The vanilla label uses singular `Throw` (where the bonus
    /// counterpart uses plural `Throws`); the dispatch matches the
    /// exact vanilla spelling.
    SavePenaltySpecific {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ReducedSpecificSavingThrow` at decode
        /// time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_savingthrow.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Damage bonus property (vanilla `itempropdef.2da` label
    /// `Damage`, row 11). The subtype identifies which damage type
    /// (Bludgeoning, Slashing, Acid, Cold, ...) the bonus applies to;
    /// the cost fields carry the magnitude reference into the
    /// cost-table dispatch chain.
    ///
    /// Distinct from `Damage_Vulnerability` (row 18) and the
    /// alignment/race-conditional `DamageAlignmentGroup` /
    /// `DamageRacialGroup` kinds, which remain in `Unknown`.
    DamageBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Damage` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_damagetype.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Damage immunity property (vanilla `itempropdef.2da` label
    /// `DamageImmunity`, row 14). The subtype identifies which damage
    /// type the immunity applies to; the cost fields carry the
    /// percentage reference into the cost-table dispatch chain.
    DamageImmunity {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamageImmunity` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_damagetype.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Damage resistance property (vanilla `itempropdef.2da` label
    /// `DamageResist`, row 17). The subtype identifies which damage
    /// type the resistance applies to; the cost fields carry the
    /// soak-amount reference into the cost-table dispatch chain.
    ///
    /// Distinct from `DamageReduced` (row 16, backed by
    /// `iprp_protection.2da` rather than `iprp_damagetype.2da`),
    /// which remains in `Unknown`.
    DamageResistance {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamageResist` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_damagetype.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Conditional damage bonus against a racial group (vanilla
    /// `itempropdef.2da` label `DamageRacialGroup`, row 13). The
    /// subtype identifies which row of `racialtypes.2da` the bonus
    /// applies against; the cost fields carry the magnitude.
    DamageRacialGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamageRacialGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `racialtypes.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Conditional damage bonus against an alignment group (vanilla
    /// `itempropdef.2da` label `DamageAlignmentGroup`, row 12). The
    /// subtype identifies which row of `iprp_aligngrp.2da` the bonus
    /// applies against; the cost fields carry the magnitude.
    DamageAlignmentGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamageAlignmentGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_aligngrp.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Conditional enhancement bonus against a racial group (vanilla
    /// `itempropdef.2da` label `EnhancementRacialGroup`, row 7). The
    /// subtype identifies which row of `racialtypes.2da` the bonus
    /// applies against; the cost fields carry the magnitude.
    ///
    /// Sibling of `DamageRacialGroup` and shares the `racialtypes.2da`
    /// dispatch chain. The alignment-group equivalent is
    /// [`Self::EnhancementAlignmentGroup`].
    EnhancementRacialGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `EnhancementRacialGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `racialtypes.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Conditional enhancement bonus against an alignment group
    /// (vanilla `itempropdef.2da` label `EnhancementAlignmentGroup`,
    /// row 6). The subtype identifies which row of
    /// `iprp_aligngrp.2da` the bonus applies against; the cost
    /// fields carry the magnitude. Sibling of
    /// [`Self::EnhancementRacialGroup`] and [`Self::DamageAlignmentGroup`].
    EnhancementAlignmentGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `EnhancementAlignmentGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_aligngrp.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Conditional attack-bonus against an alignment group (vanilla
    /// `itempropdef.2da` label `AttackBonusAlignmentGroup`, row 39).
    /// The subtype identifies which row of `iprp_aligngrp.2da` the
    /// bonus applies against; the cost fields carry the magnitude.
    AttackBonusAlignmentGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `AttackBonusAlignmentGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_aligngrp.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// True-seeing property (vanilla `itempropdef.2da` label
    /// `True_Seeing`, row 47). Grants the wearer the ability to see
    /// through invisibility / stealth. No subtype dimension; the
    /// cost fields carry the engine-side magnitude reference.
    TrueSeeing {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `True_Seeing` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Light-source property (vanilla `itempropdef.2da` label
    /// `Light`, row 29). Makes the item emit light when equipped or
    /// dropped. No subtype dimension, but row 29 in `itempropdef.2da`
    /// declares a `param1resref`, so the engine consumes `param1` /
    /// `param1_value` to convey brightness or colour parameters.
    /// Both param fields are preserved on the typed variant so
    /// consumers do not have to fall back to the raw `UtiProperty`
    /// to read them.
    Light {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Light` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Raw `Param1` id (row index into `iprp_paramtable.2da`).
        param1: u8,
        /// Raw `Param1Value` id (row index into the param-table's
        /// `iprp_*.2da`).
        param1_value: u8,
    },
    /// Armour-class bonus property (vanilla `itempropdef.2da` label
    /// `Armor`, row 1). No subtype dimension; the cost fields carry
    /// the bonus magnitude reference.
    ///
    /// `subtype_id` is preserved for shape parity across variants
    /// even though the engine ignores it for this kind. Vanilla
    /// content writes 0 here.
    AcBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Armor` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Enhancement bonus property (vanilla `itempropdef.2da` label
    /// `Enhancement`, row 5). No subtype dimension; the cost fields
    /// carry the bonus magnitude reference.
    EnhancementBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Enhancement` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Flat attack bonus property (vanilla `itempropdef.2da` label
    /// `AttackBonus`, row 38). No subtype dimension; the cost fields
    /// carry the bonus magnitude reference. Heavily used in vanilla
    /// across weapons and accessories.
    AttackBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `AttackBonus` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Keen property (vanilla `itempropdef.2da` label `Keen`, row
    /// 28). Widens the critical-hit threat range on the weapon. No
    /// subtype dimension; the cost fields carry the magnitude.
    Keen {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Keen` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Massive criticals property (vanilla `itempropdef.2da` label
    /// `Massive_Criticals`, row 49). Adds extra damage on a critical
    /// hit. No subtype dimension; the cost fields carry the damage
    /// magnitude.
    MassiveCriticals {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Massive_Criticals` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Blaster-bolt deflection bonus (vanilla `itempropdef.2da` label
    /// `Blaster_Bolt_Deflect_Increase`, row 55). Improves the deflect
    /// chance on a lightsaber. No subtype dimension; the cost fields
    /// carry the magnitude.
    ///
    /// Distinct from `Blaster_Bolt_Defect_Decrease` (row 56, vanilla
    /// typo with `Defect`), which has near-zero corpus usage and
    /// stays in `Unknown`.
    BlasterBoltDeflectIncrease {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Blaster_Bolt_Deflect_Increase` at decode
        /// time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Monster damage property (vanilla `itempropdef.2da` label
    /// `Monster_damage`, row 51). Engine uses this on monster claws,
    /// bites, and similar natural weapons. No subtype dimension; the
    /// cost fields carry the damage magnitude.
    ///
    /// The vanilla label uses lowercase `d` in `damage`; the dispatch
    /// match arm matches that spelling verbatim.
    MonsterDamage {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Monster_damage` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Bonus-feat property (vanilla `itempropdef.2da` label
    /// `BonusFeats`, row 9). The subtype identifies which row of
    /// `feat.2da` the item grants while equipped. The cost fields
    /// are usually unused for this property kind (the engine grants
    /// the feat directly rather than scaling by magnitude).
    BonusFeats {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `BonusFeats` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `feat.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Immunity property (vanilla `itempropdef.2da` label `Immunity`,
    /// row 24). The subtype identifies which row of `iprp_immunity.2da`
    /// the item grants immunity to (e.g. Mind-Affecting, Paralysis).
    /// The cost fields carry the immunity strength reference.
    Immunity {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Immunity` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_immunity.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Skill bonus property (vanilla `itempropdef.2da` label `Skill`,
    /// row 36). The subtype identifies which row of `skills.2da`
    /// (Persuade, Demolitions, ...) gets the bonus; the cost fields
    /// carry the magnitude.
    ///
    /// Distinct from `DecreasedSkill` (row 21, also backed by
    /// `skills.2da`), which has zero corpus usage in vanilla items
    /// and stays in `Unknown`.
    Skill {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Skill` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `skills.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Flat attack penalty property (vanilla `itempropdef.2da` label
    /// `AttackPenalty`, row 8). Mirror of [`Self::AttackBonus`]: same
    /// subtypeless shape, cost fields carry the magnitude of the
    /// penalty rather than the bonus.
    AttackPenalty {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `AttackPenalty` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Flat damage penalty property (vanilla `itempropdef.2da` label
    /// `DamagePenalty`, row 15). Subtypeless mirror of
    /// [`Self::DamageBonus`]: cost fields carry the penalty
    /// magnitude.
    DamagePenalty {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamagePenalty` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Magic-resistance bonus (vanilla `itempropdef.2da` label
    /// `ImprovedMagicResist`, row 25). No subtype dimension; the cost
    /// fields carry the resist magnitude.
    MagicResistBonus {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ImprovedMagicResist` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// No-damage marker property (vanilla `itempropdef.2da` label
    /// `DamageNone`, row 31). Flags a weapon as dealing no
    /// damage on hit (used on unarmed strikes, training weapons,
    /// and similar). No subtype dimension and no meaningful cost
    /// payload; the fields are preserved for round-trip fidelity.
    DamageNone {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `DamageNone` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Hit-point regeneration property (vanilla `itempropdef.2da`
    /// label `Regeneration`, row 35). Restores HP per round while
    /// equipped. No subtype dimension; the cost fields carry the
    /// magnitude.
    ///
    /// The force-points counterpart [`Self::RegenerationForcePoints`]
    /// applies to FP rather than HP.
    Regeneration {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Regeneration` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Force-point regeneration property (vanilla `itempropdef.2da`
    /// label `Regeneration_Force_Points`, row 54). Restores FP per
    /// round while equipped. No subtype dimension; the cost fields
    /// carry the magnitude.
    RegenerationForcePoints {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Regeneration_Force_Points` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Disguise property (vanilla `itempropdef.2da` label `Disguise`,
    /// row 59). The subtype identifies which row of `appearance.2da`
    /// the wearer takes on while the item is equipped (used by mask
    /// items that change the player's apparent species).
    Disguise {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Disguise` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `appearance.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Feat-restricted use property (vanilla `itempropdef.2da` label
    /// `Use_Limitation_Feat`, row 57). The subtype identifies which
    /// feat from `feat.2da` the wielder must possess to equip or
    /// activate the item.
    ///
    /// Passive property: the engine consults the subtype at equip
    /// time and rejects use if the wielder lacks the feat. `useable`
    /// and `uses_per_day` are not consumed for this kind.
    UseLimitationFeat {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Use_Limitation_Feat` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `feat.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Race-restricted use property (vanilla `itempropdef.2da` label
    /// `UseLimitationRacial`, row 45). The subtype identifies which
    /// row of `racialtypes.2da` the wielder must match.
    UseLimitationRacial {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `UseLimitationRacial` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `racialtypes.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Alignment-restricted use property (vanilla `itempropdef.2da`
    /// label `UseLimitationAlignmentGroup`, row 43). The subtype
    /// identifies which row of `iprp_aligngrp.2da` the wielder's
    /// alignment must satisfy.
    UseLimitationAlignmentGroup {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `UseLimitationAlignmentGroup` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_aligngrp.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
    },
    /// Cast-spell active property (vanilla `itempropdef.2da` label
    /// `CastSpell`, row 10). The engine routes this property into
    /// the per-character usable-ability table (one of four
    /// hardcoded "active" rows alongside `ThievesTools`, `Trap`, and
    /// `Computer_Spike`). The subtype identifies which spell from
    /// `spells.2da` the item casts.
    ///
    /// Active properties differ from passive ones in that the
    /// `useable` and `uses_per_day` fields are load-bearing rather
    /// than ignored. Both are decoded with the engine's defaults
    /// applied:
    /// - `useable` defaults to `true` for active properties when
    ///   absent from the GFF; `false` only when explicitly set.
    /// - `uses_per_day` decodes the `0xFF` engine sentinel into
    ///   `None` (meaning "unlimited / not constrained"); explicit
    ///   non-sentinel values come through as `Some(N)`.
    CastSpell {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `CastSpell` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `spells.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Whether the item can be activated. `true` when the GFF
        /// omits `Useable` (engine default for active properties)
        /// or sets it to a non-zero value; `false` when explicitly
        /// disabled.
        useable: bool,
        /// Daily-use cap. `None` when the GFF omits `UsesPerDay`
        /// or stores the engine sentinel `0xFF` ("not set / no
        /// limit"); `Some(N)` for explicit caps.
        uses_per_day: Option<u8>,
    },
    /// Trap active property (vanilla `itempropdef.2da` label
    /// `Trap`, row 46). Routed into the active-property table
    /// alongside `CastSpell`. The subtype identifies which trap
    /// from `traps.2da` deploys.
    ///
    /// `useable` and `uses_per_day` follow the same active-property
    /// decoding rules documented on [`Self::CastSpell`].
    Trap {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Trap` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `traps.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Whether the item can be activated. See [`Self::CastSpell`].
        useable: bool,
        /// Daily-use cap. See [`Self::CastSpell`].
        uses_per_day: Option<u8>,
    },
    /// Thieves-tools active property (vanilla `itempropdef.2da`
    /// label `ThievesTools`, row 37). Routed into the active-property
    /// table alongside `CastSpell`. No subtype dimension; the cost
    /// fields carry the magnitude (the security-skill bonus the
    /// tool grants while equipped).
    ///
    /// `subtype_id` is preserved for shape parity even though the
    /// engine ignores it. `useable` and `uses_per_day` follow the
    /// same active-property decoding rules documented on
    /// [`Self::CastSpell`].
    ThievesTools {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `ThievesTools` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Whether the item can be activated. See [`Self::CastSpell`].
        useable: bool,
        /// Daily-use cap. See [`Self::CastSpell`].
        uses_per_day: Option<u8>,
    },
    /// Computer-spike active property (vanilla `itempropdef.2da`
    /// label `Computer_Spike`, row 53). Routed into the
    /// active-property table alongside `CastSpell`. No subtype
    /// dimension; the cost fields carry the magnitude (the
    /// computer-use skill bonus the spike grants).
    ///
    /// `subtype_id` is preserved for shape parity even though the
    /// engine ignores it. `useable` and `uses_per_day` follow the
    /// same active-property decoding rules documented on
    /// [`Self::CastSpell`].
    ComputerSpike {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `Computer_Spike` at decode time).
        property_id: u16,
        /// Raw `Subtype` id. Not consumed by the engine for this
        /// property kind; surfaced for round-trip fidelity.
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Whether the item can be activated. See [`Self::CastSpell`].
        useable: bool,
        /// Daily-use cap. See [`Self::CastSpell`].
        uses_per_day: Option<u8>,
    },
    /// On-hit effect property (vanilla `itempropdef.2da` label
    /// `OnHit`, row 32). The subtype identifies which on-hit effect
    /// (Daze, Stun, Wound, ...) fires when the weapon connects.
    ///
    /// Unlike the other passive variants, OnHit's `param1` /
    /// `param1_value` fields are load-bearing: they convey the
    /// effect's magnitude / DC / duration through the
    /// `iprp_paramtable.2da` dispatch chain. Both fields are
    /// preserved on the typed variant so consumers do not have to
    /// fall back to the raw `UtiProperty` to read them.
    OnHit {
        /// Raw `PropertyName` (the row in `itempropdef.2da` whose
        /// `label` matched `OnHit` at decode time).
        property_id: u16,
        /// Raw `Subtype` id (row index into `iprp_onhit.2da`).
        subtype_id: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// per-property `iprp_*.2da`).
        cost_value: u16,
        /// Raw `Param1` id (row index into `iprp_paramtable.2da`).
        /// Conveys the effect's parameter dimension (DC, magnitude,
        /// duration depending on the on-hit kind).
        param1: u8,
        /// Raw `Param1Value` id (row index into the param-table's
        /// `iprp_*.2da`).
        param1_value: u8,
    },
    /// Property kind for which no typed variant exists yet, or whose
    /// `PropertyName` does not resolve in `itempropdef.2da`. Carries
    /// every raw field so consumers can still introspect or
    /// round-trip.
    Unknown {
        /// Raw `PropertyName` (engine row index into
        /// `itempropdef.2da`).
        property_id: u16,
        /// Human-readable label from `itempropdef.2da`'s `label`
        /// column when the row resolves; `None` when the row is
        /// absent or the table cannot be loaded.
        property_label: Option<String>,
        /// Raw `Subtype` id (row index into the property kind's
        /// `iprp_*.2da` subtype table).
        subtype: u16,
        /// Raw `CostTable` id (row index into `iprp_costtable.2da`).
        cost_table: u8,
        /// Raw `CostValue` id (row index into the cost-table's
        /// `iprp_*.2da`).
        cost_value: u16,
        /// Raw `Param1` id (row index into `iprp_paramtable.2da`).
        param1: u8,
        /// Raw `Param1Value` id (row index into the param-table's
        /// `iprp_*.2da`).
        param1_value: u8,
    },
}

impl DecodedProperty {
    /// Resolves a developer-readable label for this property's
    /// subtype by walking the engine's per-property subtype dispatch
    /// chain.
    ///
    /// Returns `None` when any step of the chain fails to resolve:
    /// - the source `PropertyName` row is absent from
    ///   `itempropdef.2da`,
    /// - the row's `SubTypeResRef` cell is empty (the property has
    ///   no subtype dimension at all),
    /// - the per-property subtype 2DA cannot be loaded,
    /// - the `Subtype` row is past the loaded subtype 2DA's row
    ///   count, or
    /// - any 2DA in the chain is missing or malformed.
    ///
    /// The returned string is the developer-readable `label` column
    /// (e.g. `"Acid"` from `iprp_damagecost.2da`), not a TLK-resolved
    /// display name. Tooling that needs the localized display name
    /// must resolve the `Name` column against a talktable separately.
    pub fn subtype_label(&self, cache: &mut impl TwoDaSource) -> Option<String> {
        let (property_id, subtype) = match self {
            DecodedProperty::AbilityBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::SaveBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::SaveBonusSpecific {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::SavePenalty {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::SavePenaltySpecific {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageImmunity {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageResistance {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::AcBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::EnhancementBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::OnHit {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::CastSpell {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Trap {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::ThievesTools {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::ComputerSpike {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::UseLimitationFeat {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::UseLimitationRacial {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::UseLimitationAlignmentGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageRacialGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageAlignmentGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::EnhancementRacialGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::EnhancementAlignmentGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::AttackBonusAlignmentGroup {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::TrueSeeing {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Light {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::AttackBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Keen {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::MassiveCriticals {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::BlasterBoltDeflectIncrease {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::MonsterDamage {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::BonusFeats {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Immunity {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Skill {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::AttackPenalty {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamagePenalty {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::MagicResistBonus {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::DamageNone {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Regeneration {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::RegenerationForcePoints {
                property_id,
                subtype_id,
                ..
            }
            | DecodedProperty::Disguise {
                property_id,
                subtype_id,
                ..
            } => (*property_id, *subtype_id),
            DecodedProperty::Unknown {
                property_id,
                subtype,
                ..
            } => (*property_id, *subtype),
        };
        let subtype_resref = {
            let propdef = cache.twoda(tables::ITEMPROPDEF)?;
            propdef
                .cell(usize::from(property_id), "SubTypeResRef")?
                .to_string()
        };
        if subtype_resref.is_empty() {
            return None;
        }
        let subtype_table = cache.twoda(&subtype_resref)?;
        subtype_table
            .cell(usize::from(subtype), "label")
            .map(str::to_string)
    }
}

/// File-native projection of a [`Uti`].
///
/// Each `UtiProperty` is routed to a typed [`DecodedProperty`]
/// variant by matching on the `itempropdef.2da` `label` value at
/// projection time. No further 2DA resolution happens at this stage;
/// the projection is the cheap, scope-free intermediate from which
/// one or more [`UtiResolved`]s are built.
///
/// Construct via [`Uti::project`]. Multiple resolutions from one
/// projection share typed-variant dispatch but each captures its own
/// per-scope resolved data (baseitems cells, cost-table magnitudes,
/// etc.). This is the projection-stage type referenced by the
/// "typed views are honest projections" rule: file-native dispatch
/// only, never resolved cross-resource data.
#[derive(Debug, Clone)]
pub struct UtiProjection<'a> {
    uti: &'a Uti,
    decoded_properties: Vec<DecodedProperty>,
}

/// Snapshot view over a [`Uti`], resolved against a per-scope context.
///
/// Built by [`UtiProjection::resolve`] (or [`Uti::resolve`] as a
/// single-scope shortcut). Holds the projection's typed
/// [`DecodedProperty`] variants plus the cached resolutions the
/// view's query methods need.
///
/// All query methods take `&self` and read from this cached resolution.
/// The resolved view does not retain the [`TwoDaSource`] borrow
/// once constructed; to query under a different scope, build a
/// fresh resolve again from the same projection.
///
/// Combat / equip queries (`is_weapon`, `is_consumable`,
/// `equip_slot_mask`, `model_type`) read against a cached
/// `baseitems.2da` row taken at resolve time. When that 2DA is
/// unavailable or the item's `base_item` does not resolve to a row,
/// those queries return `false` / `None` as appropriate.
#[derive(Debug)]
pub struct UtiResolved<'a> {
    uti: &'a Uti,
    decoded_properties: Vec<DecodedProperty>,
    base_item_info: Option<BaseItemInfo>,
    /// Per-property resolved magnitudes, indexed in lockstep with
    /// `decoded_properties`. `None` for properties whose kind has no
    /// magnitude semantics (most current variants) or whose
    /// resolution failed at resolve time. Populated via
    /// [`resolve_magnitude`]; the cost-table magnitude resolution
    /// subsection of `docs/src/formats/gff/uti.md` documents the
    /// recipe per property kind.
    resolved_magnitudes: Vec<Option<i32>>,
}

/// Cached subset of a `baseitems.2da` row, taken once at resolve
/// time so the combat / equip queries on [`UtiResolved`] can answer
/// without holding a 2DA cache borrow.
#[derive(Debug, Clone, Copy, Default)]
struct BaseItemInfo {
    /// `baseitems.2da#weaponwield` column. `0` means the item is
    /// not a wielded weapon.
    weapon_wield: u8,
    /// `baseitems.2da#stacking` column. Values greater than 1 mark
    /// the item as stackable (the engine's signal for consumables
    /// such as stim packs, grenades, and med kits).
    stacking: u8,
    /// `baseitems.2da#equipableslots` column, parsed from the
    /// hex-string form (e.g. `0x00010`). `None` when the cell is
    /// absent or unparseable.
    equip_slot_mask: Option<u32>,
    /// `baseitems.2da#modeltype` column. `None` when the cell is
    /// absent or unparseable. Vanilla content uses `0`, `1`, or
    /// `2`.
    model_type: Option<u8>,
}

impl BaseItemInfo {
    /// Reads the row at `base_item` from a parsed `baseitems.2da`.
    /// Returns `None` if the row does not exist; missing per-cell
    /// values fall back to the type defaults.
    fn from_row(table: &TwoDa, base_item: i32) -> Option<Self> {
        let row = usize::try_from(base_item).ok()?;
        if row >= table.rows.len() {
            return None;
        }
        Some(Self {
            weapon_wield: parse_u8_cell(table, row, "weaponwield").unwrap_or(0),
            stacking: parse_u8_cell(table, row, "stacking").unwrap_or(0),
            equip_slot_mask: parse_hex_u32_cell(table, row, "equipableslots"),
            model_type: parse_u8_cell(table, row, "modeltype"),
        })
    }
}

fn parse_u8_cell(table: &TwoDa, row: usize, column: &str) -> Option<u8> {
    table.cell(row, column).and_then(|s| s.trim().parse().ok())
}

fn parse_i32_cell(table: &TwoDa, row: usize, column: &str) -> Option<i32> {
    table.cell(row, column).and_then(|s| s.trim().parse().ok())
}

fn parse_hex_u32_cell(table: &TwoDa, row: usize, column: &str) -> Option<u32> {
    let raw = table.cell(row, column)?.trim();
    let stripped = raw
        .strip_prefix("0x")
        .or_else(|| raw.strip_prefix("0X"))
        .unwrap_or(raw);
    u32::from_str_radix(stripped, 16).ok()
}

/// Resolves a single property's runtime magnitude in engine units.
///
/// Returns `None` for property kinds with no magnitude semantics
/// (subtype-only kinds, active uses-per-day kinds, etc.) and for
/// failed lookups (missing 2DA, out-of-range row, unparseable cell).
/// The per-kind recipe follows the "Cost-Table Magnitude Resolution"
/// subsection of `docs/src/formats/gff/uti.md`.
fn resolve_magnitude(prop: &DecodedProperty, cache: &mut impl TwoDaSource) -> Option<i32> {
    match prop {
        // Bypass handler per the audit: ApplyDamageBonus reads
        // CostValue directly as the damage amount with no per-cost
        // 2DA lookup. The iprp_damagecost.2da table is used for cost
        // calculation (GetCost), not for damage-magnitude resolution.
        DecodedProperty::DamageBonus { cost_value, .. } => Some(i32::from(*cost_value)),
        // ApplyAbilityBonus calls GetIPRPCostTable(1) -> iprp_bonuscost
        // with a hardcoded index. The property's cost_table field is
        // ignored by the handler, so the lookup table is fixed here
        // too.
        DecodedProperty::AbilityBonus { cost_value, .. } => {
            let table = cache.twoda("iprp_bonuscost")?;
            parse_i32_cell(table, usize::from(*cost_value), "Value")
        }
        // ApplyDamageImmunity reads the cost-table index from each
        // property's cost_table field (dynamic), then walks
        // iprp_costtable -> per-cost 2DA. Mod-extended cost tables
        // resolve through the same path.
        DecodedProperty::DamageImmunity {
            cost_table,
            cost_value,
            ..
        } => resolve_dynamic_magnitude(cache, *cost_table, *cost_value, "Value"),
        _ => None,
    }
}

/// Walks the cost-table dispatch chain for property kinds whose
/// per-cost 2DA is read from the property's own `cost_table` field
/// rather than hardcoded by the engine handler.
///
/// `iprp_costtable.2da[cost_table]#Name` resolves to a per-cost 2DA
/// resref; that table's row at `cost_value`, column `column`, holds
/// the magnitude. Any missing link in the chain surfaces as `None`.
fn resolve_dynamic_magnitude(
    cache: &mut impl TwoDaSource,
    cost_table: u8,
    cost_value: u16,
    column: &str,
) -> Option<i32> {
    // The cost 2DA name has to be cloned out before re-borrowing the
    // cache for the second lookup; the borrow into iprp_costtable
    // would otherwise alias the cache mutation that loads the
    // per-cost table.
    let cost_2da_name = {
        let costtable = cache.twoda("iprp_costtable")?;
        costtable
            .cell(usize::from(cost_table), "Name")?
            .trim()
            .to_lowercase()
    };
    if cost_2da_name.is_empty() {
        return None;
    }
    let table = cache.twoda(&cost_2da_name)?;
    parse_i32_cell(table, usize::from(cost_value), column)
}

impl<'a> UtiProjection<'a> {
    /// Returns the typed-variant decoded properties as a borrowed
    /// slice.
    ///
    /// The order matches the source [`Uti::properties`] ordering;
    /// callers that need a particular property look it up by index
    /// or filter the slice.
    pub fn properties(&self) -> &[DecodedProperty] {
        &self.decoded_properties
    }

    /// Returns `true` when the source UTI's `BaseItem` belongs to
    /// the canonical armor base-item set.
    ///
    /// Pure delegation to [`Uti::is_armor`] -- the underlying check
    /// is a const lookup against the hardcoded armor base-item id
    /// set and needs no 2DA cache. Re-exposed here so callers that
    /// only hold a [`UtiProjection`] do not have to reach back to
    /// the source `Uti`.
    pub fn is_armor(&self) -> bool {
        self.uti.is_armor()
    }

    /// Resolves this projection against the given context, building
    /// a [`UtiResolved`] whose query methods read from a cached
    /// resolution of every table the resolved view will be asked about.
    ///
    /// Multiple resolutions can be built from one projection, each
    /// capturing its own per-scope resolved data. The projection
    /// itself is unchanged and remains reusable across calls.
    pub fn resolve(&self, cache: &mut impl TwoDaSource) -> UtiResolved<'a> {
        let base_item_info = cache
            .twoda(tables::BASEITEMS)
            .and_then(|table| BaseItemInfo::from_row(table, self.uti.base_item));
        let resolved_magnitudes = self
            .decoded_properties
            .iter()
            .map(|prop| resolve_magnitude(prop, cache))
            .collect();
        UtiResolved {
            uti: self.uti,
            decoded_properties: self.decoded_properties.clone(),
            base_item_info,
            resolved_magnitudes,
        }
    }
}

impl<'a> UtiResolved<'a> {
    /// Returns the typed-variant decoded properties as a borrowed
    /// slice.
    ///
    /// The order matches the source [`Uti::properties`] ordering;
    /// callers that need a particular property look it up by index
    /// or filter the slice.
    pub fn properties(&self) -> &[DecodedProperty] {
        &self.decoded_properties
    }

    /// Returns `true` when the source UTI's `BaseItem` belongs to
    /// the canonical armor base-item set.
    ///
    /// Pure delegation to [`Uti::is_armor`] -- the underlying check
    /// is a const lookup against the hardcoded armor base-item id
    /// set and needs no 2DA cache. Re-exposed here so callers that
    /// only hold a [`UtiResolved`] do not have to reach back to the
    /// source `Uti`.
    pub fn is_armor(&self) -> bool {
        self.uti.is_armor()
    }

    /// Returns `true` when the item's `baseitems.2da` row marks it
    /// as a wielded weapon (`weaponwield > 0`).
    ///
    /// Returns `false` when `baseitems.2da` is unavailable, the
    /// `base_item` does not resolve to a row, or the cell is
    /// missing / unparseable.
    pub fn is_weapon(&self) -> bool {
        self.base_item_info
            .as_ref()
            .is_some_and(|b| b.weapon_wield > 0)
    }

    /// Returns `true` when the item is consumable, defined by the
    /// engine's signal `stacking > 1` (stim packs, grenades, med
    /// kits all stack; equipment does not).
    ///
    /// Returns `false` when `baseitems.2da` is unavailable, the
    /// `base_item` does not resolve to a row, or the cell is
    /// missing / unparseable.
    pub fn is_consumable(&self) -> bool {
        self.base_item_info.as_ref().is_some_and(|b| b.stacking > 1)
    }

    /// Returns the item's equipable-slot bitmask from
    /// `baseitems.2da#equipableslots`, parsed from its hex-string
    /// form.
    ///
    /// Returns `None` when `baseitems.2da` is unavailable, the
    /// `base_item` does not resolve to a row, or the cell is
    /// missing / unparseable.
    pub fn equip_slot_mask(&self) -> Option<u32> {
        self.base_item_info.as_ref().and_then(|b| b.equip_slot_mask)
    }

    /// Returns the item's model-type id from
    /// `baseitems.2da#modeltype`.
    ///
    /// The value gates whether the engine consults the UTI's
    /// `TextureVar` field (only when `model_type == 1` per the
    /// UTI engine audit). Returns `None` when `baseitems.2da` is
    /// unavailable, the `base_item` does not resolve to a row, or
    /// the cell is missing / unparseable.
    pub fn model_type(&self) -> Option<u8> {
        self.base_item_info.as_ref().and_then(|b| b.model_type)
    }

    /// Returns `true` when any decoded property on this item falls
    /// into the given [`PropertyKindFilter`] family.
    ///
    /// `Unknown` variants never match any filter; consumers wanting
    /// to inspect unknown property kinds should walk
    /// [`Self::properties`] directly. For exact-variant queries (a
    /// specific kind rather than a family), pattern-match against
    /// the typed [`DecodedProperty`] variants directly.
    pub fn has_property_kind(&self, filter: PropertyKindFilter) -> bool {
        self.decoded_properties
            .iter()
            .any(|prop| filter.matches(prop))
    }

    /// Iterates this item's [`DecodedProperty::AbilityBonus`]
    /// properties, yielding `(subtype_id, magnitude)` pairs.
    ///
    /// `subtype_id` indexes into `iprp_abilities.2da` (vanilla rows
    /// 0..=5 cover STR/DEX/CON/INT/WIS/CHA). `magnitude` is the
    /// resolved bonus value from `iprp_bonuscost.2da#Value` at row
    /// `cost_value`, per the cost-table magnitude resolution
    /// subsection of `docs/src/formats/gff/uti.md`. The cost-table
    /// index is hardcoded by the engine handler for this kind, so the
    /// property's `cost_table` field is ignored.
    ///
    /// Properties whose magnitude could not be resolved at resolve
    /// time are silently skipped.
    pub fn ability_bonuses(&self) -> impl Iterator<Item = (u16, i32)> + '_ {
        self.iter_resolved_magnitudes(|prop| match prop {
            DecodedProperty::AbilityBonus { subtype_id, .. } => Some(*subtype_id),
            _ => None,
        })
    }

    /// Iterates this item's [`DecodedProperty::DamageBonus`]
    /// properties, yielding `(subtype_id, magnitude)` pairs.
    ///
    /// `subtype_id` indexes into `iprp_damagetype.2da`. `magnitude`
    /// is `cost_value` taken directly: per the audit, the engine's
    /// `ApplyDamageBonus` handler bypasses cost-table dispatch and
    /// reads `CostValue` as the damage amount.
    ///
    /// Properties whose magnitude could not be resolved at resolve
    /// time are silently skipped.
    pub fn damage_bonuses(&self) -> impl Iterator<Item = (u16, i32)> + '_ {
        self.iter_resolved_magnitudes(|prop| match prop {
            DecodedProperty::DamageBonus { subtype_id, .. } => Some(*subtype_id),
            _ => None,
        })
    }

    /// Iterates this item's [`DecodedProperty::DamageImmunity`]
    /// properties, yielding `(subtype_id, magnitude)` pairs.
    ///
    /// `subtype_id` indexes into `iprp_damagetype.2da` (which damage
    /// type the immunity applies to). `magnitude` is read by walking
    /// the dynamic cost-table dispatch chain
    /// (`iprp_costtable.2da[cost_table]#Name` -> per-cost 2DA at row
    /// `cost_value`, column `Value`), per the cost-table magnitude
    /// resolution subsection of `docs/src/formats/gff/uti.md`. The
    /// cost-table index is read from each property's `cost_table`
    /// field, so mod-extended cost tables resolve through the same
    /// path.
    ///
    /// Properties whose magnitude could not be resolved at resolve
    /// time are silently skipped.
    pub fn damage_immunities(&self) -> impl Iterator<Item = (u16, i32)> + '_ {
        self.iter_resolved_magnitudes(|prop| match prop {
            DecodedProperty::DamageImmunity { subtype_id, .. } => Some(*subtype_id),
            _ => None,
        })
    }

    /// Shared iterator skeleton for the per-kind magnitude iterators.
    /// `pick_subtype` returns `Some(subtype_id)` for properties of
    /// the kind the caller wants, `None` otherwise. The combined
    /// iterator yields `(subtype_id, magnitude)` only when the kind
    /// matches and the resolved view has a magnitude for that
    /// property.
    fn iter_resolved_magnitudes<F>(&self, pick_subtype: F) -> impl Iterator<Item = (u16, i32)> + '_
    where
        F: Fn(&DecodedProperty) -> Option<u16> + 'static,
    {
        self.decoded_properties
            .iter()
            .zip(self.resolved_magnitudes.iter())
            .filter_map(move |(prop, magnitude)| {
                let subtype = pick_subtype(prop)?;
                let value = (*magnitude)?;
                Some((subtype, value))
            })
    }
}

/// Categorical filter for [`UtiResolved::has_property_kind`].
///
/// Each variant maps to a family of typed [`DecodedProperty`]
/// variants that share a semantic theme (damage modification,
/// wielder restriction, active-use, etc.). The filters are not
/// exclusive: `DamageImmunity` and `DamageResistance` count under
/// [`PropertyKindFilter::Damage`], so an item with one or the other
/// matches the `Damage` filter.
///
/// Property kinds that do not naturally cluster with a family
/// (`OnHit`, `Light`, `BonusFeats`, `Skill`, `Immunity`,
/// `Regeneration*`, `Disguise`, `MagicResistBonus`, `Keen`,
/// `MassiveCriticals`, `BlasterBoltDeflectIncrease`,
/// `MonsterDamage`, `DamageNone`, `TrueSeeing`) are not surfaced by
/// any filter; callers needing them pattern-match the typed
/// variants directly via [`UtiResolved::properties`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PropertyKindFilter {
    /// Any damage-family property: `DamageBonus`, `DamageImmunity`,
    /// `DamageResistance`, `DamageRacialGroup`,
    /// `DamageAlignmentGroup`, or `DamagePenalty`.
    Damage,
    /// Ability-score bonus (`AbilityBonus`).
    Ability,
    /// Saving-throw bonus or penalty, universal or specific:
    /// `SaveBonus`, `SaveBonusSpecific`, `SavePenalty`,
    /// `SavePenaltySpecific`.
    Save,
    /// Attack bonus or penalty: `AttackBonus`,
    /// `AttackBonusAlignmentGroup`, `AttackPenalty`.
    Attack,
    /// Enhancement bonus, flat or conditional: `EnhancementBonus`,
    /// `EnhancementRacialGroup`, `EnhancementAlignmentGroup`.
    Enhancement,
    /// Wielder-restriction property: `UseLimitationFeat`,
    /// `UseLimitationRacial`, `UseLimitationAlignmentGroup`.
    UseLimitation,
    /// Engine-active property routed into the per-character
    /// usable-ability table: `CastSpell`, `Trap`, `ThievesTools`,
    /// `ComputerSpike`.
    Active,
}

impl PropertyKindFilter {
    fn matches(self, prop: &DecodedProperty) -> bool {
        match self {
            Self::Damage => matches!(
                prop,
                DecodedProperty::DamageBonus { .. }
                    | DecodedProperty::DamageImmunity { .. }
                    | DecodedProperty::DamageResistance { .. }
                    | DecodedProperty::DamageRacialGroup { .. }
                    | DecodedProperty::DamageAlignmentGroup { .. }
                    | DecodedProperty::DamagePenalty { .. }
            ),
            Self::Ability => matches!(prop, DecodedProperty::AbilityBonus { .. }),
            Self::Save => matches!(
                prop,
                DecodedProperty::SaveBonus { .. }
                    | DecodedProperty::SaveBonusSpecific { .. }
                    | DecodedProperty::SavePenalty { .. }
                    | DecodedProperty::SavePenaltySpecific { .. }
            ),
            Self::Attack => matches!(
                prop,
                DecodedProperty::AttackBonus { .. }
                    | DecodedProperty::AttackBonusAlignmentGroup { .. }
                    | DecodedProperty::AttackPenalty { .. }
            ),
            Self::Enhancement => matches!(
                prop,
                DecodedProperty::EnhancementBonus { .. }
                    | DecodedProperty::EnhancementRacialGroup { .. }
                    | DecodedProperty::EnhancementAlignmentGroup { .. }
            ),
            Self::UseLimitation => matches!(
                prop,
                DecodedProperty::UseLimitationFeat { .. }
                    | DecodedProperty::UseLimitationRacial { .. }
                    | DecodedProperty::UseLimitationAlignmentGroup { .. }
            ),
            Self::Active => matches!(
                prop,
                DecodedProperty::CastSpell { .. }
                    | DecodedProperty::Trap { .. }
                    | DecodedProperty::ThievesTools { .. }
                    | DecodedProperty::ComputerSpike { .. }
            ),
        }
    }
}

impl Uti {
    /// Builds a [`UtiProjection`] of this UTI's properties using the
    /// supplied `itempropdef.2da`.
    ///
    /// Each `UtiProperty` is routed by its `itempropdef.2da` `label`
    /// to a typed [`DecodedProperty`] variant where one exists, or to
    /// [`DecodedProperty::Unknown`] otherwise. Pass `None` for
    /// `itempropdef` to surface every property as `Unknown` with
    /// `property_label = None`; the engine itself tolerates a
    /// missing table the same way.
    ///
    /// The projection is the cheap, scope-free intermediate. Use
    /// [`UtiProjection::resolve`] (or [`Uti::resolve`] for the
    /// single-scope shortcut) to resolve it against a per-scope
    /// context.
    pub fn project(&self, itempropdef: Option<&TwoDa>) -> UtiProjection<'_> {
        let decoded_properties = self
            .properties
            .iter()
            .map(|p| {
                let label = itempropdef
                    .and_then(|table| table.cell(usize::from(p.property_name), "label"))
                    .map(str::to_string);
                decode_property(p, label)
            })
            .collect();
        UtiProjection {
            uti: self,
            decoded_properties,
        }
    }

    /// Builds a [`UtiResolved`] of this UTI against the given 2DA
    /// cache. Single-scope shortcut equivalent to
    /// `self.project(itempropdef).resolve(cache)`, where
    /// `itempropdef` comes from `cache`.
    ///
    /// Missing or malformed `itempropdef.2da` / `baseitems.2da` is
    /// tolerated -- the corresponding resolved state degrades
    /// gracefully (all properties land in `Unknown`; combat / equip
    /// queries return `false` / `None`).
    ///
    /// For multi-scope workflows (mod conflict analysis, vanilla vs
    /// modded diffs), call [`Uti::project`] once and
    /// [`UtiProjection::resolve`] per scope so the typed-variant
    /// dispatch is not redone for each context.
    pub fn resolve(&self, cache: &mut impl TwoDaSource) -> UtiResolved<'_> {
        // Inner block releases the itempropdef borrow before
        // `UtiProjection::resolve` re-borrows the cache for
        // baseitems.
        let projection = {
            let propdef = cache.twoda(tables::ITEMPROPDEF);
            self.project(propdef)
        };
        projection.resolve(cache)
    }
}

/// Routes a single [`UtiProperty`] to a typed [`DecodedProperty`]
/// variant by matching on the `itempropdef.2da` `label` value
/// resolved at decode time.
///
/// Properties without a matching typed arm fall through to
/// [`DecodedProperty::Unknown`] carrying the raw fields plus the
/// resolved label.
fn decode_property(p: &UtiProperty, label: Option<String>) -> DecodedProperty {
    match label.as_deref() {
        Some("Ability") => DecodedProperty::AbilityBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("ImprovedSavingThrows") => DecodedProperty::SaveBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("ImprovedSavingThrowsSpecific") => DecodedProperty::SaveBonusSpecific {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("ReducedSavingThrows") => DecodedProperty::SavePenalty {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("ReducedSpecificSavingThrow") => DecodedProperty::SavePenaltySpecific {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Damage") => DecodedProperty::DamageBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamageImmunity") => DecodedProperty::DamageImmunity {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamageResist") => DecodedProperty::DamageResistance {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Armor") => DecodedProperty::AcBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Enhancement") => DecodedProperty::EnhancementBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("OnHit") => DecodedProperty::OnHit {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            param1: p.param1,
            param1_value: p.param1_value,
        },
        Some("CastSpell") => DecodedProperty::CastSpell {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            useable: active_useable(p.useable),
            uses_per_day: active_uses_per_day(p.uses_per_day),
        },
        Some("Trap") => DecodedProperty::Trap {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            useable: active_useable(p.useable),
            uses_per_day: active_uses_per_day(p.uses_per_day),
        },
        Some("ThievesTools") => DecodedProperty::ThievesTools {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            useable: active_useable(p.useable),
            uses_per_day: active_uses_per_day(p.uses_per_day),
        },
        Some("Computer_Spike") => DecodedProperty::ComputerSpike {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            useable: active_useable(p.useable),
            uses_per_day: active_uses_per_day(p.uses_per_day),
        },
        Some("Use_Limitation_Feat") => DecodedProperty::UseLimitationFeat {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("UseLimitationRacial") => DecodedProperty::UseLimitationRacial {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("UseLimitationAlignmentGroup") => DecodedProperty::UseLimitationAlignmentGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamageRacialGroup") => DecodedProperty::DamageRacialGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamageAlignmentGroup") => DecodedProperty::DamageAlignmentGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("EnhancementRacialGroup") => DecodedProperty::EnhancementRacialGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("EnhancementAlignmentGroup") => DecodedProperty::EnhancementAlignmentGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("AttackBonusAlignmentGroup") => DecodedProperty::AttackBonusAlignmentGroup {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("True_Seeing") => DecodedProperty::TrueSeeing {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Light") => DecodedProperty::Light {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            param1: p.param1,
            param1_value: p.param1_value,
        },
        Some("AttackBonus") => DecodedProperty::AttackBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Keen") => DecodedProperty::Keen {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Massive_Criticals") => DecodedProperty::MassiveCriticals {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Blaster_Bolt_Deflect_Increase") => DecodedProperty::BlasterBoltDeflectIncrease {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Monster_damage") => DecodedProperty::MonsterDamage {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("BonusFeats") => DecodedProperty::BonusFeats {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Immunity") => DecodedProperty::Immunity {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Skill") => DecodedProperty::Skill {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("AttackPenalty") => DecodedProperty::AttackPenalty {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamagePenalty") => DecodedProperty::DamagePenalty {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("ImprovedMagicResist") => DecodedProperty::MagicResistBonus {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("DamageNone") => DecodedProperty::DamageNone {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Regeneration") => DecodedProperty::Regeneration {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Regeneration_Force_Points") => DecodedProperty::RegenerationForcePoints {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        Some("Disguise") => DecodedProperty::Disguise {
            property_id: p.property_name,
            subtype_id: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
        },
        // The itempropdef.2da rows below have no vanilla .uti
        // references per `vanilla-inspector uti property-stats` and
        // fall through to Unknown by design. Anyone needing one can
        // add a typed variant in minutes: the uti.md reference table
        // names each row's label and subtype 2DA.
        //
        // Grouped by family for promotion convenience:
        //   Armor-conditional        : rows 2, 3, 4
        //   AttackBonus-conditional  : row 40
        //   Damage extensions        : rows 16, 18, 22, 23
        //   Negative/decrease mirrors: rows 19, 20, 21, 41
        //   Use-limitation extras    : row 44
        //   Special properties       : 30, 42, 48, 50, 52, 56, 58
        //
        // Re-run `vanilla-inspector uti property-stats` before
        // promoting any row to confirm this list is still current.
        _ => DecodedProperty::Unknown {
            property_id: p.property_name,
            property_label: label,
            subtype: p.subtype,
            cost_table: p.cost_table,
            cost_value: p.cost_value,
            param1: p.param1,
            param1_value: p.param1_value,
        },
    }
}

/// Coalesces the engine's "missing GFF field" default for active
/// properties. Per the Ghidra audit, when an active-property entry
/// omits `Useable`, the engine defaults the flag to `1` (active);
/// passive entries default it to `0`. Active variants carry that
/// default into the decoded model so consumers do not have to know
/// the kind-specific rule.
fn active_useable(raw: Option<bool>) -> bool {
    raw.unwrap_or(true)
}

/// Coalesces the engine's `0xFF` "not set" sentinel on `UsesPerDay`
/// into `None`. Both an absent GFF field and an explicit `0xFF`
/// decode the same way; explicit non-sentinel values pass through
/// unchanged.
fn active_uses_per_day(raw: Option<u8>) -> Option<u8> {
    match raw {
        Some(0xFF) | None => None,
        Some(value) => Some(value),
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::decoded::test_tables::TestTables;
    use crate::uti::UtiProperty;
    use rakata_formats::twoda::{TwoDa, TwoDaRow};

    fn property(property_name: u16, subtype: u16) -> UtiProperty {
        UtiProperty {
            cost_table: 1,
            cost_value: 5,
            param1: 0xFF,
            param1_value: 0,
            property_name,
            subtype,
            chance_appear: 100,
            useable: None,
            uses_per_day: None,
            upgrade_type: None,
        }
    }

    fn itempropdef_with_labels(labels: &[(usize, &str)]) -> TwoDa {
        let max_row = labels.iter().map(|(idx, _)| *idx).max().unwrap_or(0);
        let mut rows = Vec::with_capacity(max_row + 1);
        for row_index in 0..=max_row {
            let label = labels
                .iter()
                .find(|(idx, _)| *idx == row_index)
                .map(|(_, label)| (*label).to_string())
                .unwrap_or_default();
            rows.push(TwoDaRow {
                label: row_index.to_string(),
                cells: vec![label],
            });
        }
        TwoDa {
            headers: vec!["label".to_string()],
            rows,
        }
    }

    #[test]
    fn decodes_every_property_into_unknown_variant() {
        let uti = Uti {
            properties: vec![property(0, 1), property(7, 12), property(45, 0)],
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        assert_eq!(view.properties().len(), 3);
        assert!(view
            .decoded_properties
            .iter()
            .all(|p| matches!(p, DecodedProperty::Unknown { .. })));
    }

    #[test]
    fn unknown_carries_raw_fields_through_unchanged() {
        let raw = property(0, 0);
        let mut shaped = raw.clone();
        shaped.property_name = 7;
        shaped.subtype = 12;
        shaped.cost_table = 3;
        shaped.cost_value = 99;
        shaped.param1 = 4;
        shaped.param1_value = 200;
        let uti = Uti {
            properties: vec![shaped.clone()],
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        let DecodedProperty::Unknown {
            property_id,
            subtype,
            cost_table,
            cost_value,
            param1,
            param1_value,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected Unknown variant for unloaded itempropdef");
        };
        assert_eq!(*property_id, 7);
        assert_eq!(*subtype, 12);
        assert_eq!(*cost_table, 3);
        assert_eq!(*cost_value, 99);
        assert_eq!(*param1, 4);
        assert_eq!(*param1_value, 200);
    }

    #[test]
    fn property_label_resolves_into_unknown_for_untyped_kinds() {
        // Synthetic labels with no matching typed routing arm; both
        // properties end up in `Unknown` carrying the resolved label.
        let table = itempropdef_with_labels(&[(0, "Test_Kind_A"), (7, "Test_Kind_B")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(7, 0), property(0, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for synthetic label");
        };
        assert_eq!(property_label.as_deref(), Some("Test_Kind_B"));
        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[1] else {
            panic!("expected Unknown variant for synthetic label");
        };
        assert_eq!(property_label.as_deref(), Some("Test_Kind_A"));
    }

    #[test]
    fn property_label_is_none_when_row_is_absent() {
        // itempropdef has rows 0, 1 only; PropertyName 99 is past
        // the last row, so the label resolves to None and decode
        // routes to Unknown.
        let table = itempropdef_with_labels(&[(0, "Test_Kind_A"), (1, "Test_Kind_B")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(99, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for absent row");
        };
        assert!(property_label.is_none());
    }

    #[test]
    fn property_label_is_none_when_itempropdef_is_missing() {
        // No source contains itempropdef.2da. Decode succeeds, every
        // property routes to Unknown with label = None.
        let mut tables = TestTables::new();

        let uti = Uti {
            properties: vec![property(0, 0), property(7, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        for prop in view.properties() {
            let DecodedProperty::Unknown { property_label, .. } = prop else {
                panic!("expected Unknown variant when itempropdef is missing");
            };
            assert!(property_label.is_none());
        }
    }

    #[test]
    fn mod_added_property_label_surfaces_via_unknown() {
        // A mod adds row 200 to itempropdef with a custom label that
        // matches no typed routing arm. Decode produces Unknown with
        // the mod's label preserved.
        let table = itempropdef_with_labels(&[(200, "FakeMod_GrantsCookies")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(200, 5)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown {
            property_id,
            property_label,
            subtype,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected Unknown variant for mod-added label");
        };
        assert_eq!(*property_id, 200);
        assert_eq!(property_label.as_deref(), Some("FakeMod_GrantsCookies"));
        assert_eq!(*subtype, 5);
    }

    #[test]
    fn empty_property_list_decodes_to_empty_view() {
        let uti = Uti::default();
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        assert!(view.properties().is_empty());
    }

    #[test]
    fn ability_bonus_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 0 carries the label `Ability`. The
        // decoder routes that property to the typed AbilityBonus
        // variant rather than Unknown.
        let table = itempropdef_with_labels(&[(0, "Ability")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(0, 2);
        shaped.cost_table = 1;
        shaped.cost_value = 4;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::AbilityBonus {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
        } = &view.properties()[0]
        else {
            panic!("expected AbilityBonus variant for `Ability` label");
        };
        assert_eq!(*property_id, 0);
        assert_eq!(*subtype_id, 2); // CON in vanilla iprp_abilities ordering
        assert_eq!(*cost_table, 1);
        assert_eq!(*cost_value, 4);
    }

    #[test]
    fn ability_bonus_preserves_raw_subtype_for_mod_extended_rows() {
        // A mod adds a new ability subtype past the vanilla 0..=5
        // range. The decode still routes to AbilityBonus and the raw
        // subtype id passes through.
        let table = itempropdef_with_labels(&[(0, "Ability")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(0, 99)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::AbilityBonus { subtype_id, .. } = &view.properties()[0] else {
            panic!("expected AbilityBonus variant for mod-extended subtype");
        };
        assert_eq!(*subtype_id, 99);
    }

    #[test]
    fn ability_bonus_subtype_label_resolves_via_iprp_abilities() {
        // The subtype_label helper walks itempropdef.SubTypeResRef ->
        // iprp_abilities.label for an AbilityBonus variant.
        let propdef = itempropdef_with_subtypes(&[(0, "Ability", "iprp_abilities")]);
        let abilities = subtype_2da(&[
            (0, "STR"),
            (1, "DEX"),
            (2, "CON"),
            (3, "INT"),
            (4, "WIS"),
            (5, "CHA"),
        ]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_abilities", &abilities);

        let prop = DecodedProperty::AbilityBonus {
            property_id: 0,
            subtype_id: 3,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(prop.subtype_label(&mut tables).as_deref(), Some("INT"));
    }

    #[test]
    fn save_bonus_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 26 carries the label
        // `ImprovedSavingThrows`. The decoder routes that property to
        // the typed SaveBonus variant rather than Unknown.
        let table = itempropdef_with_labels(&[(26, "ImprovedSavingThrows")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(26, 1);
        shaped.cost_table = 2;
        shaped.cost_value = 3;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::SaveBonus {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
        } = &view.properties()[0]
        else {
            panic!("expected SaveBonus variant for `ImprovedSavingThrows` label");
        };
        assert_eq!(*property_id, 26);
        assert_eq!(*subtype_id, 1);
        assert_eq!(*cost_table, 2);
        assert_eq!(*cost_value, 3);
    }

    #[test]
    fn save_bonus_preserves_raw_subtype_for_mod_extended_rows() {
        // A mod adds a save element past the vanilla iprp_saveelement
        // range. The decode still routes to SaveBonus and the raw
        // subtype id passes through.
        let table = itempropdef_with_labels(&[(26, "ImprovedSavingThrows")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(26, 200)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::SaveBonus { subtype_id, .. } = &view.properties()[0] else {
            panic!("expected SaveBonus variant for mod-extended subtype");
        };
        assert_eq!(*subtype_id, 200);
    }

    #[test]
    fn save_bonus_does_not_match_save_penalty_or_specific_kinds() {
        // The four save-throw labels split into four distinct typed
        // variants: SaveBonus (universal positive), SaveBonusSpecific
        // (per-throw positive), SavePenalty (universal negative),
        // SavePenaltySpecific (per-throw negative). This test pins
        // the routing for all four to catch any future regression
        // that collapses them or mis-routes one into another.
        let table = itempropdef_with_labels(&[
            (26, "ImprovedSavingThrows"),
            (27, "ImprovedSavingThrowsSpecific"),
            (33, "ReducedSavingThrows"),
            (34, "ReducedSpecificSavingThrow"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![
                property(26, 0),
                property(27, 0),
                property(33, 0),
                property(34, 0),
            ],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(matches!(
            view.properties()[0],
            DecodedProperty::SaveBonus { .. }
        ));
        assert!(matches!(
            view.properties()[1],
            DecodedProperty::SaveBonusSpecific { .. }
        ));
        assert!(matches!(
            view.properties()[2],
            DecodedProperty::SavePenalty { .. }
        ));
        assert!(matches!(
            view.properties()[3],
            DecodedProperty::SavePenaltySpecific { .. }
        ));
    }

    #[test]
    fn save_bonus_subtype_label_resolves_via_iprp_saveelement() {
        // The subtype_label helper walks itempropdef.SubTypeResRef ->
        // iprp_saveelement.label for a SaveBonus variant.
        let propdef =
            itempropdef_with_subtypes(&[(26, "ImprovedSavingThrows", "iprp_saveelement")]);
        let saveelement = subtype_2da(&[(0, "Universal"), (1, "Acid"), (2, "Cold")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_saveelement", &saveelement);

        let prop = DecodedProperty::SaveBonus {
            property_id: 26,
            subtype_id: 2,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(prop.subtype_label(&mut tables).as_deref(), Some("Cold"));
    }

    #[test]
    fn save_throw_family_subtype_labels_resolve_via_their_2das() {
        // SaveBonus / SavePenalty use `iprp_saveelement.2da` (the
        // universal element table); SaveBonusSpecific /
        // SavePenaltySpecific use `iprp_savingthrow.2da` (the
        // per-throw table). Verify each variant resolves through
        // the correct table.
        let propdef = itempropdef_with_subtypes(&[
            (26, "ImprovedSavingThrows", "iprp_saveelement"),
            (27, "ImprovedSavingThrowsSpecific", "iprp_savingthrow"),
            (33, "ReducedSavingThrows", "iprp_saveelement"),
            (34, "ReducedSpecificSavingThrow", "iprp_savingthrow"),
        ]);
        let saveelement = subtype_2da(&[(0, "Universal"), (1, "Acid"), (2, "Cold")]);
        let savingthrow = subtype_2da(&[(0, "Fortitude"), (1, "Reflex"), (2, "Will")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_saveelement", &saveelement);
        add_2da_entry(&mut tables, "iprp_savingthrow", &savingthrow);

        let specific_bonus = DecodedProperty::SaveBonusSpecific {
            property_id: 27,
            subtype_id: 2,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            specific_bonus.subtype_label(&mut tables).as_deref(),
            Some("Will")
        );

        let universal_penalty = DecodedProperty::SavePenalty {
            property_id: 33,
            subtype_id: 1,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            universal_penalty.subtype_label(&mut tables).as_deref(),
            Some("Acid")
        );

        let specific_penalty = DecodedProperty::SavePenaltySpecific {
            property_id: 34,
            subtype_id: 0,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            specific_penalty.subtype_label(&mut tables).as_deref(),
            Some("Fortitude")
        );
    }

    #[test]
    fn damage_bonus_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 11 carries the label `Damage`. The
        // decoder routes that property to the typed DamageBonus
        // variant rather than Unknown.
        let table = itempropdef_with_labels(&[(11, "Damage")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(11, 5);
        shaped.cost_table = 4;
        shaped.cost_value = 2;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::DamageBonus {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
        } = &view.properties()[0]
        else {
            panic!("expected DamageBonus variant for `Damage` label");
        };
        assert_eq!(*property_id, 11);
        assert_eq!(*subtype_id, 5);
        assert_eq!(*cost_table, 4);
        assert_eq!(*cost_value, 2);
    }

    #[test]
    fn damage_bonus_does_not_match_vulnerability_or_unrelated_kinds() {
        // Vanilla row 18 (`Damage_Vulnerability`) sits adjacent to
        // `Damage` in itempropdef and shares the prefix. It must not
        // route to DamageBonus; the decoder leaves it in Unknown
        // until it gets its own typed variant. The conditional
        // siblings DamageAlignmentGroup (row 12) and DamageRacialGroup
        // (row 13) now have their own typed variants and are covered
        // elsewhere; this test focuses on the prefix-trap case.
        let table = itempropdef_with_labels(&[(18, "Damage_Vulnerability")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(18, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for `Damage_Vulnerability`");
        };
        assert_eq!(property_label.as_deref(), Some("Damage_Vulnerability"));
    }

    #[test]
    fn damage_immunity_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(14, "DamageImmunity")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(14, 7)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::DamageImmunity {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected DamageImmunity variant for `DamageImmunity` label");
        };
        assert_eq!(*property_id, 14);
        assert_eq!(*subtype_id, 7);
    }

    #[test]
    fn damage_resistance_label_routes_to_typed_variant() {
        // Vanilla label is `DamageResist` (no `-ance` suffix), and
        // that's what the decoder must match.
        let table = itempropdef_with_labels(&[(17, "DamageResist")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(17, 3)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::DamageResistance {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected DamageResistance variant for `DamageResist` label");
        };
        assert_eq!(*property_id, 17);
        assert_eq!(*subtype_id, 3);
    }

    #[test]
    fn damage_resistance_does_not_match_damage_reduced() {
        // Vanilla row 16 is `DamageReduced`, backed by
        // iprp_protection.2da rather than iprp_damagetype.2da. The
        // DamageResistance arm must not absorb it; the decoder routes
        // it to Unknown until it gets its own typed variant.
        let table = itempropdef_with_labels(&[(16, "DamageReduced")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(16, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for `DamageReduced`");
        };
        assert_eq!(property_label.as_deref(), Some("DamageReduced"));
    }

    #[test]
    fn damage_family_subtype_labels_resolve_via_iprp_damagetype() {
        // All three damage-family variants share the iprp_damagetype
        // subtype 2DA. Verify the subtype_label helper resolves each
        // through that table.
        let propdef = itempropdef_with_subtypes(&[
            (11, "Damage", "iprp_damagetype"),
            (14, "DamageImmunity", "iprp_damagetype"),
            (17, "DamageResist", "iprp_damagetype"),
        ]);
        let damagetype = subtype_2da(&[
            (0, "Bludgeoning"),
            (1, "Slashing"),
            (2, "Piercing"),
            (5, "Acid"),
            (6, "Cold"),
        ]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_damagetype", &damagetype);

        let bonus = DecodedProperty::DamageBonus {
            property_id: 11,
            subtype_id: 5,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(bonus.subtype_label(&mut tables).as_deref(), Some("Acid"));

        let immunity = DecodedProperty::DamageImmunity {
            property_id: 14,
            subtype_id: 6,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(immunity.subtype_label(&mut tables).as_deref(), Some("Cold"));

        let resistance = DecodedProperty::DamageResistance {
            property_id: 17,
            subtype_id: 1,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            resistance.subtype_label(&mut tables).as_deref(),
            Some("Slashing")
        );
    }

    #[test]
    fn ac_bonus_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 1 carries the label `Armor`. The
        // decoder routes it to AcBonus. The property has no subtype
        // dimension; subtype_id is preserved for round-trip fidelity
        // even though the engine ignores it.
        let table = itempropdef_with_labels(&[(1, "Armor")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(1, 0);
        shaped.cost_table = 2;
        shaped.cost_value = 5;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::AcBonus {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
        } = &view.properties()[0]
        else {
            panic!("expected AcBonus variant for `Armor` label");
        };
        assert_eq!(*property_id, 1);
        assert_eq!(*subtype_id, 0);
        assert_eq!(*cost_table, 2);
        assert_eq!(*cost_value, 5);
    }

    #[test]
    fn ac_bonus_does_not_match_armor_conditional_kinds() {
        // Vanilla rows 2 / 3 / 4 (`ArmorAlignmentGroup`,
        // `ArmorDamageType`, `ArmorRacialGroup`) sit adjacent to
        // `Armor` and start with the same prefix. None belong in
        // AcBonus; all must fall through to Unknown.
        let table = itempropdef_with_labels(&[
            (2, "ArmorAlignmentGroup"),
            (3, "ArmorDamageType"),
            (4, "ArmorRacialGroup"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(2, 0), property(3, 0), property(4, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        for prop in view.properties() {
            assert!(
                matches!(prop, DecodedProperty::Unknown { .. }),
                "expected Unknown for non-Armor label, got {prop:?}"
            );
        }
    }

    #[test]
    fn enhancement_bonus_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(5, "Enhancement")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(5, 0);
        shaped.cost_table = 2;
        shaped.cost_value = 3;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::EnhancementBonus {
            property_id,
            cost_table,
            cost_value,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected EnhancementBonus variant for `Enhancement` label");
        };
        assert_eq!(*property_id, 5);
        assert_eq!(*cost_table, 2);
        assert_eq!(*cost_value, 3);
    }

    #[test]
    fn enhancement_bonus_does_not_match_its_conditional_siblings() {
        // Rows 6 (`EnhancementAlignmentGroup`) and 7
        // (`EnhancementRacialGroup`) share the `Enhancement` prefix
        // but are distinct typed variants. The EnhancementBonus arm
        // must not absorb either; each routes to its own typed kind.
        let table = itempropdef_with_labels(&[
            (6, "EnhancementAlignmentGroup"),
            (7, "EnhancementRacialGroup"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(6, 0), property(7, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(matches!(
            view.properties()[0],
            DecodedProperty::EnhancementAlignmentGroup { .. }
        ));
        assert!(matches!(
            view.properties()[1],
            DecodedProperty::EnhancementRacialGroup { .. }
        ));
    }

    #[test]
    fn on_hit_label_routes_to_typed_variant_with_param_fields() {
        // Vanilla itempropdef row 32 carries the label `OnHit`. The
        // decoder routes it to OnHit and preserves the param fields
        // (which the engine consumes via iprp_paramtable.2da to convey
        // the effect's magnitude / DC / duration).
        let table = itempropdef_with_labels(&[(32, "OnHit")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(32, 4);
        shaped.cost_table = 25;
        shaped.cost_value = 1;
        shaped.param1 = 1;
        shaped.param1_value = 7;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::OnHit {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
            param1,
            param1_value,
        } = &view.properties()[0]
        else {
            panic!("expected OnHit variant for `OnHit` label");
        };
        assert_eq!(*property_id, 32);
        assert_eq!(*subtype_id, 4);
        assert_eq!(*cost_table, 25);
        assert_eq!(*cost_value, 1);
        assert_eq!(*param1, 1);
        assert_eq!(*param1_value, 7);
    }

    #[test]
    fn on_hit_does_not_match_on_monster_hit() {
        // Vanilla row 48 is `OnMonsterHit`, a related but distinct
        // kind that the OnHit arm must not absorb.
        let table = itempropdef_with_labels(&[(48, "OnMonsterHit")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(48, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for `OnMonsterHit`");
        };
        assert_eq!(property_label.as_deref(), Some("OnMonsterHit"));
    }

    #[test]
    fn on_hit_subtype_label_resolves_via_iprp_onhit() {
        let propdef = itempropdef_with_subtypes(&[(32, "OnHit", "iprp_onhit")]);
        let onhit = subtype_2da(&[(0, "Sleep"), (1, "Daze"), (4, "Stun")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_onhit", &onhit);

        let prop = DecodedProperty::OnHit {
            property_id: 32,
            subtype_id: 4,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert_eq!(prop.subtype_label(&mut tables).as_deref(), Some("Stun"));
    }

    #[test]
    fn ac_bonus_subtype_label_returns_none_for_subtypeless_property() {
        // `Armor` carries no SubTypeResRef in vanilla. The helper must
        // short-circuit to None rather than treating subtype_id=0 as a
        // valid row index against some unrelated table.
        let propdef = itempropdef_with_subtypes(&[(1, "Armor", "")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let prop = DecodedProperty::AcBonus {
            property_id: 1,
            subtype_id: 0,
            cost_table: 2,
            cost_value: 5,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    fn active_property(property_name: u16, subtype: u16) -> UtiProperty {
        // Variant of `property` for active-property tests: starts with
        // every active-loop field at "GFF omitted" so each test can opt
        // into explicit values where it matters.
        let mut p = property(property_name, subtype);
        p.useable = None;
        p.uses_per_day = None;
        p
    }

    #[test]
    fn cast_spell_label_routes_to_typed_variant_with_active_defaults() {
        // Vanilla itempropdef row 10 carries the label `CastSpell`.
        // The decoder routes it to CastSpell. With Useable and
        // UsesPerDay omitted in the GFF, the active-property
        // defaults apply: useable = true, uses_per_day = None.
        let table = itempropdef_with_labels(&[(10, "CastSpell")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = active_property(10, 42);
        shaped.cost_table = 3;
        shaped.cost_value = 7;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::CastSpell {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
            useable,
            uses_per_day,
        } = &view.properties()[0]
        else {
            panic!("expected CastSpell variant for `CastSpell` label");
        };
        assert_eq!(*property_id, 10);
        assert_eq!(*subtype_id, 42);
        assert_eq!(*cost_table, 3);
        assert_eq!(*cost_value, 7);
        assert!(*useable);
        assert!(uses_per_day.is_none());
    }

    #[test]
    fn cast_spell_preserves_explicit_useable_false() {
        // The active-loop default only applies when the GFF omits
        // Useable. An explicit `Useable=false` must pass through; the
        // engine treats the item as inactive in that case.
        let table = itempropdef_with_labels(&[(10, "CastSpell")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = active_property(10, 0);
        shaped.useable = Some(false);
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::CastSpell { useable, .. } = &view.properties()[0] else {
            panic!("expected CastSpell variant");
        };
        assert!(!*useable);
    }

    #[test]
    fn cast_spell_coalesces_uses_per_day_sentinel_into_none() {
        // The engine's `0xFF` sentinel means "not set"; both an
        // omitted UsesPerDay and an explicit `0xFF` decode to None.
        // A non-sentinel cap passes through as Some(N).
        let table = itempropdef_with_labels(&[(10, "CastSpell")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut sentinel = active_property(10, 0);
        sentinel.uses_per_day = Some(0xFF);
        let mut explicit = active_property(10, 0);
        explicit.uses_per_day = Some(3);
        let uti = Uti {
            properties: vec![sentinel, explicit],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::CastSpell { uses_per_day, .. } = &view.properties()[0] else {
            panic!("expected CastSpell variant for sentinel");
        };
        assert!(uses_per_day.is_none());

        let DecodedProperty::CastSpell { uses_per_day, .. } = &view.properties()[1] else {
            panic!("expected CastSpell variant for explicit cap");
        };
        assert_eq!(*uses_per_day, Some(3));
    }

    #[test]
    fn cast_spell_subtype_label_resolves_via_spells_2da() {
        let propdef = itempropdef_with_subtypes(&[(10, "CastSpell", "spells")]);
        let spells = subtype_2da(&[(0, "Cure_Wounds"), (5, "Force_Push")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "spells", &spells);

        let prop = DecodedProperty::CastSpell {
            property_id: 10,
            subtype_id: 5,
            cost_table: 0,
            cost_value: 0,
            useable: true,
            uses_per_day: None,
        };
        assert_eq!(
            prop.subtype_label(&mut tables).as_deref(),
            Some("Force_Push")
        );
    }

    #[test]
    fn trap_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(46, "Trap")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = active_property(46, 2);
        shaped.uses_per_day = Some(1);
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Trap {
            property_id,
            subtype_id,
            useable,
            uses_per_day,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected Trap variant for `Trap` label");
        };
        assert_eq!(*property_id, 46);
        assert_eq!(*subtype_id, 2);
        assert!(*useable);
        assert_eq!(*uses_per_day, Some(1));
    }

    #[test]
    fn trap_subtype_label_resolves_via_traps_2da() {
        let propdef = itempropdef_with_subtypes(&[(46, "Trap", "traps")]);
        let traps = subtype_2da(&[(0, "Minor_Frag"), (3, "Deadly_Plasma")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "traps", &traps);

        let prop = DecodedProperty::Trap {
            property_id: 46,
            subtype_id: 3,
            cost_table: 0,
            cost_value: 0,
            useable: true,
            uses_per_day: Some(1),
        };
        assert_eq!(
            prop.subtype_label(&mut tables).as_deref(),
            Some("Deadly_Plasma")
        );
    }

    #[test]
    fn thieves_tools_label_routes_to_typed_variant_with_active_defaults() {
        // Vanilla itempropdef row 37 carries the label `ThievesTools`.
        // The decoder routes it to ThievesTools and applies the
        // active-property defaults (useable = true when GFF omits
        // Useable, uses_per_day = None for the 0xFF sentinel).
        let table = itempropdef_with_labels(&[(37, "ThievesTools")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = active_property(37, 0);
        shaped.cost_table = 1;
        shaped.cost_value = 4;
        shaped.uses_per_day = Some(0xFF);
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::ThievesTools {
            property_id,
            cost_table,
            cost_value,
            useable,
            uses_per_day,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected ThievesTools variant for `ThievesTools` label");
        };
        assert_eq!(*property_id, 37);
        assert_eq!(*cost_table, 1);
        assert_eq!(*cost_value, 4);
        assert!(*useable);
        assert!(uses_per_day.is_none());
    }

    #[test]
    fn thieves_tools_subtype_label_returns_none_for_subtypeless_property() {
        // ThievesTools carries no SubTypeResRef in vanilla. The
        // helper must short-circuit to None rather than dispatching
        // against an unrelated table.
        let propdef = itempropdef_with_subtypes(&[(37, "ThievesTools", "")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let prop = DecodedProperty::ThievesTools {
            property_id: 37,
            subtype_id: 0,
            cost_table: 1,
            cost_value: 4,
            useable: true,
            uses_per_day: None,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn computer_spike_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 53 carries the label
        // `Computer_Spike` (with underscore). The decoder routes it
        // to ComputerSpike. Note the Rust variant drops the
        // underscore per Rust naming conventions, but the dispatch
        // matches the verbatim vanilla label.
        let table = itempropdef_with_labels(&[(53, "Computer_Spike")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = active_property(53, 0);
        shaped.cost_table = 1;
        shaped.cost_value = 5;
        shaped.useable = Some(true);
        shaped.uses_per_day = Some(2);
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::ComputerSpike {
            property_id,
            cost_table,
            cost_value,
            useable,
            uses_per_day,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected ComputerSpike variant for `Computer_Spike` label");
        };
        assert_eq!(*property_id, 53);
        assert_eq!(*cost_table, 1);
        assert_eq!(*cost_value, 5);
        assert!(*useable);
        assert_eq!(*uses_per_day, Some(2));
    }

    #[test]
    fn computer_spike_subtype_label_returns_none_for_subtypeless_property() {
        let propdef = itempropdef_with_subtypes(&[(53, "Computer_Spike", "")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let prop = DecodedProperty::ComputerSpike {
            property_id: 53,
            subtype_id: 0,
            cost_table: 1,
            cost_value: 5,
            useable: true,
            uses_per_day: Some(2),
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn attack_bonus_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 38 carries the label `AttackBonus`.
        // The decoder routes that property to AttackBonus.
        let table = itempropdef_with_labels(&[(38, "AttackBonus")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(38, 0);
        shaped.cost_table = 2;
        shaped.cost_value = 3;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::AttackBonus {
            property_id,
            cost_table,
            cost_value,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected AttackBonus variant for `AttackBonus` label");
        };
        assert_eq!(*property_id, 38);
        assert_eq!(*cost_table, 2);
        assert_eq!(*cost_value, 3);
    }

    #[test]
    fn attack_bonus_does_not_match_its_conditional_siblings() {
        // Vanilla row 39 (`AttackBonusAlignmentGroup`) has corpus
        // usage and is now a typed variant; row 40
        // (`AttackBonusRacialGroup`) has zero corpus usage and stays
        // in Unknown. The plain `AttackBonus` arm must not absorb
        // either: row 39 routes to its own typed kind, row 40 to
        // Unknown.
        let table = itempropdef_with_labels(&[
            (39, "AttackBonusAlignmentGroup"),
            (40, "AttackBonusRacialGroup"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(39, 0), property(40, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(matches!(
            view.properties()[0],
            DecodedProperty::AttackBonusAlignmentGroup { .. }
        ));
        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[1] else {
            panic!("expected Unknown for `AttackBonusRacialGroup`");
        };
        assert_eq!(property_label.as_deref(), Some("AttackBonusRacialGroup"));
    }

    #[test]
    fn keen_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(28, "Keen")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(28, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Keen { property_id, .. } = &view.properties()[0] else {
            panic!("expected Keen variant for `Keen` label");
        };
        assert_eq!(*property_id, 28);
    }

    #[test]
    fn massive_criticals_label_routes_to_typed_variant() {
        // Vanilla label has an underscore (`Massive_Criticals`); the
        // Rust variant drops it per naming convention but the
        // dispatch matches the underscored form verbatim.
        let table = itempropdef_with_labels(&[(49, "Massive_Criticals")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(49, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::MassiveCriticals { property_id, .. } = &view.properties()[0] else {
            panic!("expected MassiveCriticals variant for `Massive_Criticals` label");
        };
        assert_eq!(*property_id, 49);
    }

    #[test]
    fn blaster_bolt_deflect_increase_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(55, "Blaster_Bolt_Deflect_Increase")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(55, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::BlasterBoltDeflectIncrease { property_id, .. } = &view.properties()[0]
        else {
            panic!("expected BlasterBoltDeflectIncrease variant for the vanilla label");
        };
        assert_eq!(*property_id, 55);
    }

    #[test]
    fn blaster_bolt_deflect_does_not_absorb_vanilla_typo_sibling() {
        // Vanilla row 56 is `Blaster_Bolt_Defect_Decrease` (note the
        // typo: `Defect` rather than `Deflect`). It has near-zero
        // corpus usage and stays in Unknown by design. The
        // BlasterBoltDeflectIncrease arm must not absorb it; the
        // dispatch matches the exact vanilla spellings, not
        // normalized forms.
        let table = itempropdef_with_labels(&[(56, "Blaster_Bolt_Defect_Decrease")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(56, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown for the vanilla-typo sibling");
        };
        assert_eq!(
            property_label.as_deref(),
            Some("Blaster_Bolt_Defect_Decrease")
        );
    }

    #[test]
    fn monster_damage_label_routes_to_typed_variant() {
        // Vanilla label uses lowercase `d` (`Monster_damage`); the
        // dispatch matches that exact spelling.
        let table = itempropdef_with_labels(&[(51, "Monster_damage")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(51, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::MonsterDamage { property_id, .. } = &view.properties()[0] else {
            panic!("expected MonsterDamage variant for `Monster_damage` label");
        };
        assert_eq!(*property_id, 51);
    }

    #[test]
    fn subtypeless_single_magnitude_variants_short_circuit_subtype_label() {
        // None of the new subtypeless variants carry a SubTypeResRef
        // in vanilla, so the helper must short-circuit to None
        // rather than dispatching against an unrelated table.
        let propdef = itempropdef_with_subtypes(&[
            (28, "Keen", ""),
            (38, "AttackBonus", ""),
            (49, "Massive_Criticals", ""),
            (51, "Monster_damage", ""),
            (55, "Blaster_Bolt_Deflect_Increase", ""),
        ]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        for prop in [
            DecodedProperty::Keen {
                property_id: 28,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::AttackBonus {
                property_id: 38,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::MassiveCriticals {
                property_id: 49,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::MonsterDamage {
                property_id: 51,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::BlasterBoltDeflectIncrease {
                property_id: 55,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
        ] {
            assert!(
                prop.subtype_label(&mut tables).is_none(),
                "expected None subtype_label for subtypeless variant, got {prop:?}"
            );
        }
    }

    #[test]
    fn bonus_feats_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(9, "BonusFeats")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(9, 12)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::BonusFeats {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected BonusFeats variant for `BonusFeats` label");
        };
        assert_eq!(*property_id, 9);
        assert_eq!(*subtype_id, 12);
    }

    #[test]
    fn immunity_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(24, "Immunity")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(24, 5)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Immunity {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected Immunity variant for `Immunity` label");
        };
        assert_eq!(*property_id, 24);
        assert_eq!(*subtype_id, 5);
    }

    #[test]
    fn skill_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(36, "Skill")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(36, 2)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Skill {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected Skill variant for `Skill` label");
        };
        assert_eq!(*property_id, 36);
        assert_eq!(*subtype_id, 2);
    }

    #[test]
    fn skill_does_not_match_decreased_skill_sibling() {
        // Vanilla row 21 is `DecreasedSkill`, also backed by
        // `skills.2da`. It has zero corpus usage in vanilla items
        // and stays in Unknown until a consumer asks; the Skill arm
        // must not absorb it.
        let table = itempropdef_with_labels(&[(21, "DecreasedSkill")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(21, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown for `DecreasedSkill`");
        };
        assert_eq!(property_label.as_deref(), Some("DecreasedSkill"));
    }

    #[test]
    fn misc_2da_backed_singleton_subtype_labels_resolve_via_their_2das() {
        // BonusFeats -> feat.2da, Immunity -> iprp_immunity.2da,
        // Skill -> skills.2da. Verify each resolves through the
        // correct table.
        let propdef = itempropdef_with_subtypes(&[
            (9, "BonusFeats", "feat"),
            (24, "Immunity", "iprp_immunity"),
            (36, "Skill", "skills"),
        ]);
        let feats = subtype_2da(&[(0, "Toughness"), (12, "Force_Sensitive")]);
        let immunities = subtype_2da(&[(0, "Mind_Affecting"), (5, "Paralysis")]);
        let skills = subtype_2da(&[(0, "Computer_Use"), (2, "Persuade")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "feat", &feats);
        add_2da_entry(&mut tables, "iprp_immunity", &immunities);
        add_2da_entry(&mut tables, "skills", &skills);

        let feat = DecodedProperty::BonusFeats {
            property_id: 9,
            subtype_id: 12,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            feat.subtype_label(&mut tables).as_deref(),
            Some("Force_Sensitive")
        );

        let immunity = DecodedProperty::Immunity {
            property_id: 24,
            subtype_id: 5,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            immunity.subtype_label(&mut tables).as_deref(),
            Some("Paralysis")
        );

        let skill = DecodedProperty::Skill {
            property_id: 36,
            subtype_id: 2,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            skill.subtype_label(&mut tables).as_deref(),
            Some("Persuade")
        );
    }

    #[test]
    fn use_limitation_feat_label_routes_to_typed_variant() {
        // Vanilla itempropdef row 57 carries the label
        // `Use_Limitation_Feat` (with underscores). The decoder
        // routes that property to UseLimitationFeat with the raw
        // feat row as subtype.
        let table = itempropdef_with_labels(&[(57, "Use_Limitation_Feat")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(57, 42)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::UseLimitationFeat {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected UseLimitationFeat variant for `Use_Limitation_Feat` label");
        };
        assert_eq!(*property_id, 57);
        assert_eq!(*subtype_id, 42);
    }

    #[test]
    fn use_limitation_racial_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(45, "UseLimitationRacial")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(45, 3)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::UseLimitationRacial {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected UseLimitationRacial variant for `UseLimitationRacial` label");
        };
        assert_eq!(*property_id, 45);
        assert_eq!(*subtype_id, 3);
    }

    #[test]
    fn use_limitation_alignment_group_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(43, "UseLimitationAlignmentGroup")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(43, 2)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::UseLimitationAlignmentGroup {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!(
                "expected UseLimitationAlignmentGroup variant for \
                 `UseLimitationAlignmentGroup` label"
            );
        };
        assert_eq!(*property_id, 43);
        assert_eq!(*subtype_id, 2);
    }

    #[test]
    fn use_limitation_does_not_match_unused_class_sibling() {
        // Vanilla row 44 is `UseLimitationClass`, the fourth member
        // of the family. It has zero corpus usage and is intentionally
        // left in Unknown until a consumer asks. The other
        // use-limitation arms must not absorb it.
        let table = itempropdef_with_labels(&[(44, "UseLimitationClass")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(44, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::Unknown { property_label, .. } = &view.properties()[0] else {
            panic!("expected Unknown variant for `UseLimitationClass`");
        };
        assert_eq!(property_label.as_deref(), Some("UseLimitationClass"));
    }

    #[test]
    fn damage_racial_group_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(13, "DamageRacialGroup")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut shaped = property(13, 3);
        shaped.cost_table = 4;
        shaped.cost_value = 2;
        let uti = Uti {
            properties: vec![shaped],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::DamageRacialGroup {
            property_id,
            subtype_id,
            cost_table,
            cost_value,
        } = &view.properties()[0]
        else {
            panic!("expected DamageRacialGroup variant for `DamageRacialGroup` label");
        };
        assert_eq!(*property_id, 13);
        assert_eq!(*subtype_id, 3);
        assert_eq!(*cost_table, 4);
        assert_eq!(*cost_value, 2);
    }

    #[test]
    fn damage_alignment_group_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(12, "DamageAlignmentGroup")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(12, 4)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::DamageAlignmentGroup {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected DamageAlignmentGroup variant for `DamageAlignmentGroup` label");
        };
        assert_eq!(*property_id, 12);
        assert_eq!(*subtype_id, 4);
    }

    #[test]
    fn enhancement_racial_group_label_routes_to_typed_variant() {
        let table = itempropdef_with_labels(&[(7, "EnhancementRacialGroup")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(7, 3)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::EnhancementRacialGroup {
            property_id,
            subtype_id,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected EnhancementRacialGroup variant for `EnhancementRacialGroup` label");
        };
        assert_eq!(*property_id, 7);
        assert_eq!(*subtype_id, 3);
    }

    #[test]
    fn conditional_bonus_family_subtype_labels_resolve_via_their_2das() {
        // DamageRacialGroup and EnhancementRacialGroup share
        // `racialtypes.2da`; DamageAlignmentGroup uses
        // `iprp_aligngrp.2da`. Verify each resolves through the
        // correct table.
        let propdef = itempropdef_with_subtypes(&[
            (7, "EnhancementRacialGroup", "racialtypes"),
            (12, "DamageAlignmentGroup", "iprp_aligngrp"),
            (13, "DamageRacialGroup", "racialtypes"),
        ]);
        let racial = subtype_2da(&[(0, "Human"), (3, "Wookiee")]);
        let aligngrp = subtype_2da(&[(0, "Lawful_Good"), (4, "Chaotic_Evil")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "racialtypes", &racial);
        add_2da_entry(&mut tables, "iprp_aligngrp", &aligngrp);

        let damage_racial = DecodedProperty::DamageRacialGroup {
            property_id: 13,
            subtype_id: 3,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            damage_racial.subtype_label(&mut tables).as_deref(),
            Some("Wookiee")
        );

        let damage_alignment = DecodedProperty::DamageAlignmentGroup {
            property_id: 12,
            subtype_id: 4,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            damage_alignment.subtype_label(&mut tables).as_deref(),
            Some("Chaotic_Evil")
        );

        let enhancement_racial = DecodedProperty::EnhancementRacialGroup {
            property_id: 7,
            subtype_id: 3,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            enhancement_racial.subtype_label(&mut tables).as_deref(),
            Some("Wookiee")
        );
    }

    #[test]
    fn use_limitation_family_subtype_labels_resolve_via_their_2das() {
        // All three use-limitation variants back onto different
        // subtype tables. Verify the helper resolves each through
        // the correct 2DA.
        let propdef = itempropdef_with_subtypes(&[
            (43, "UseLimitationAlignmentGroup", "iprp_aligngrp"),
            (45, "UseLimitationRacial", "racialtypes"),
            (57, "Use_Limitation_Feat", "feat"),
        ]);
        let aligngrp = subtype_2da(&[(0, "Lawful_Good"), (4, "Chaotic_Evil")]);
        let racial = subtype_2da(&[(0, "Human"), (3, "Wookiee")]);
        let feats = subtype_2da(&[(0, "Toughness"), (42, "Force_Sensitive")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_aligngrp", &aligngrp);
        add_2da_entry(&mut tables, "racialtypes", &racial);
        add_2da_entry(&mut tables, "feat", &feats);

        let alignment = DecodedProperty::UseLimitationAlignmentGroup {
            property_id: 43,
            subtype_id: 4,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            alignment.subtype_label(&mut tables).as_deref(),
            Some("Chaotic_Evil")
        );

        let racial = DecodedProperty::UseLimitationRacial {
            property_id: 45,
            subtype_id: 3,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            racial.subtype_label(&mut tables).as_deref(),
            Some("Wookiee")
        );

        let feat = DecodedProperty::UseLimitationFeat {
            property_id: 57,
            subtype_id: 42,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            feat.subtype_label(&mut tables).as_deref(),
            Some("Force_Sensitive")
        );
    }

    #[test]
    fn low_volume_catchall_variants_route_to_typed_variants() {
        // Seven low-volume vanilla rows get their own typed variants
        // in this batch: AttackPenalty (4 items), DamagePenalty (1),
        // ImprovedMagicResist (4), DamageNone (3), Regeneration (6),
        // Regeneration_Force_Points (4), and Disguise (2). This test
        // pins the routing for all seven at once.
        let table = itempropdef_with_labels(&[
            (8, "AttackPenalty"),
            (15, "DamagePenalty"),
            (25, "ImprovedMagicResist"),
            (31, "DamageNone"),
            (35, "Regeneration"),
            (54, "Regeneration_Force_Points"),
            (59, "Disguise"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![
                property(8, 0),
                property(15, 0),
                property(25, 0),
                property(31, 0),
                property(35, 0),
                property(54, 0),
                property(59, 7),
            ],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(matches!(
            view.properties()[0],
            DecodedProperty::AttackPenalty { .. }
        ));
        assert!(matches!(
            view.properties()[1],
            DecodedProperty::DamagePenalty { .. }
        ));
        assert!(matches!(
            view.properties()[2],
            DecodedProperty::MagicResistBonus { .. }
        ));
        assert!(matches!(
            view.properties()[3],
            DecodedProperty::DamageNone { .. }
        ));
        assert!(matches!(
            view.properties()[4],
            DecodedProperty::Regeneration { .. }
        ));
        assert!(matches!(
            view.properties()[5],
            DecodedProperty::RegenerationForcePoints { .. }
        ));
        let DecodedProperty::Disguise { subtype_id, .. } = &view.properties()[6] else {
            panic!("expected Disguise variant for `Disguise` label");
        };
        assert_eq!(*subtype_id, 7);
    }

    #[test]
    fn low_volume_subtypeless_variants_short_circuit_subtype_label() {
        // Six of the seven low-volume variants have no SubTypeResRef
        // in vanilla. The helper must short-circuit to None for each.
        let propdef = itempropdef_with_subtypes(&[
            (8, "AttackPenalty", ""),
            (15, "DamagePenalty", ""),
            (25, "ImprovedMagicResist", ""),
            (31, "DamageNone", ""),
            (35, "Regeneration", ""),
            (54, "Regeneration_Force_Points", ""),
        ]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        for prop in [
            DecodedProperty::AttackPenalty {
                property_id: 8,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::DamagePenalty {
                property_id: 15,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::MagicResistBonus {
                property_id: 25,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::DamageNone {
                property_id: 31,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::Regeneration {
                property_id: 35,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
            DecodedProperty::RegenerationForcePoints {
                property_id: 54,
                subtype_id: 0,
                cost_table: 0,
                cost_value: 0,
            },
        ] {
            assert!(
                prop.subtype_label(&mut tables).is_none(),
                "expected None subtype_label for subtypeless variant, got {prop:?}"
            );
        }
    }

    #[test]
    fn disguise_subtype_label_resolves_via_appearance_2da() {
        let propdef = itempropdef_with_subtypes(&[(59, "Disguise", "appearance")]);
        let appearance = subtype_2da(&[(0, "Human"), (7, "Tusken_Raider")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "appearance", &appearance);

        let prop = DecodedProperty::Disguise {
            property_id: 59,
            subtype_id: 7,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            prop.subtype_label(&mut tables).as_deref(),
            Some("Tusken_Raider")
        );
    }

    #[test]
    fn newly_visible_alignment_and_special_variants_route_to_typed() {
        // After the GFF reader's cycle-detection bound was widened
        // to allow flat one-entry property lists, four more rows
        // surfaced in the corpus survey and got typed variants:
        // EnhancementAlignmentGroup (row 6, 5 items),
        // AttackBonusAlignmentGroup (row 39, 1 item), Light (row 29,
        // 3 items, with param fields), and TrueSeeing (row 47,
        // 1 item). Pins routing for all four.
        let table = itempropdef_with_labels(&[
            (6, "EnhancementAlignmentGroup"),
            (29, "Light"),
            (39, "AttackBonusAlignmentGroup"),
            (47, "True_Seeing"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let mut light_prop = property(29, 0);
        light_prop.param1 = 9;
        light_prop.param1_value = 4;
        let uti = Uti {
            properties: vec![property(6, 2), light_prop, property(39, 3), property(47, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        let DecodedProperty::EnhancementAlignmentGroup {
            subtype_id: ealignment_subtype,
            ..
        } = &view.properties()[0]
        else {
            panic!("expected EnhancementAlignmentGroup for row 6");
        };
        assert_eq!(*ealignment_subtype, 2);

        let DecodedProperty::Light {
            param1,
            param1_value,
            ..
        } = &view.properties()[1]
        else {
            panic!("expected Light for row 29");
        };
        assert_eq!(*param1, 9);
        assert_eq!(*param1_value, 4);

        let DecodedProperty::AttackBonusAlignmentGroup {
            subtype_id: ab_alignment_subtype,
            ..
        } = &view.properties()[2]
        else {
            panic!("expected AttackBonusAlignmentGroup for row 39");
        };
        assert_eq!(*ab_alignment_subtype, 3);

        assert!(matches!(
            view.properties()[3],
            DecodedProperty::TrueSeeing { .. }
        ));
    }

    #[test]
    fn alignment_group_variants_subtype_labels_resolve_via_iprp_aligngrp() {
        // EnhancementAlignmentGroup (row 6) and
        // AttackBonusAlignmentGroup (row 39) both back onto
        // iprp_aligngrp.2da, the same table as the existing
        // UseLimitationAlignmentGroup and DamageAlignmentGroup
        // variants. Verify both new variants resolve through it.
        let propdef = itempropdef_with_subtypes(&[
            (6, "EnhancementAlignmentGroup", "iprp_aligngrp"),
            (39, "AttackBonusAlignmentGroup", "iprp_aligngrp"),
        ]);
        let aligngrp = subtype_2da(&[(0, "Lawful_Good"), (2, "Neutral"), (4, "Chaotic_Evil")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_aligngrp", &aligngrp);

        let enhancement = DecodedProperty::EnhancementAlignmentGroup {
            property_id: 6,
            subtype_id: 4,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            enhancement.subtype_label(&mut tables).as_deref(),
            Some("Chaotic_Evil")
        );

        let attack = DecodedProperty::AttackBonusAlignmentGroup {
            property_id: 39,
            subtype_id: 0,
            cost_table: 0,
            cost_value: 0,
        };
        assert_eq!(
            attack.subtype_label(&mut tables).as_deref(),
            Some("Lawful_Good")
        );
    }

    #[test]
    fn light_and_true_seeing_short_circuit_subtype_label() {
        // Light (row 29) and TrueSeeing (row 47) carry no
        // SubTypeResRef in vanilla; the helper must return None.
        let propdef = itempropdef_with_subtypes(&[(29, "Light", ""), (47, "True_Seeing", "")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let light = DecodedProperty::Light {
            property_id: 29,
            subtype_id: 0,
            cost_table: 0,
            cost_value: 0,
            param1: 9,
            param1_value: 4,
        };
        assert!(light.subtype_label(&mut tables).is_none());

        let true_seeing = DecodedProperty::TrueSeeing {
            property_id: 47,
            subtype_id: 0,
            cost_table: 0,
            cost_value: 0,
        };
        assert!(true_seeing.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn deferred_zero_use_rows_stay_in_unknown_by_design() {
        // The decoder intentionally leaves the vanilla itempropdef
        // rows with no .uti corpus references in Unknown. This test
        // pins a representative subset across the families listed in
        // the deferral comment at the `_ => Unknown` arm in
        // `decode_property`. If a future batch types any of these,
        // remove the corresponding entry here and update the
        // deferral comment.
        let table = itempropdef_with_labels(&[
            (2, "ArmorAlignmentGroup"),
            (16, "DamageReduced"),
            (19, "DecreaseAbilityScore"),
            (22, "DamageMelee"),
            (40, "AttackBonusRacialGroup"),
            (44, "UseLimitationClass"),
            (48, "OnMonsterHit"),
            (56, "Blaster_Bolt_Defect_Decrease"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![
                property(2, 0),
                property(16, 0),
                property(19, 0),
                property(22, 0),
                property(40, 0),
                property(44, 0),
                property(48, 0),
                property(56, 0),
            ],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        for prop in view.properties() {
            assert!(
                matches!(prop, DecodedProperty::Unknown { .. }),
                "expected Unknown for deferred row, got {prop:?}"
            );
        }
    }

    #[test]
    fn properties_accessor_preserves_source_order() {
        let uti = Uti {
            properties: vec![property(7, 0), property(0, 0), property(45, 0)],
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        let ids: Vec<u16> = view
            .properties()
            .iter()
            .map(|prop| match prop {
                DecodedProperty::AbilityBonus { property_id, .. }
                | DecodedProperty::SaveBonus { property_id, .. }
                | DecodedProperty::SaveBonusSpecific { property_id, .. }
                | DecodedProperty::SavePenalty { property_id, .. }
                | DecodedProperty::SavePenaltySpecific { property_id, .. }
                | DecodedProperty::DamageBonus { property_id, .. }
                | DecodedProperty::DamageImmunity { property_id, .. }
                | DecodedProperty::DamageResistance { property_id, .. }
                | DecodedProperty::AcBonus { property_id, .. }
                | DecodedProperty::EnhancementBonus { property_id, .. }
                | DecodedProperty::OnHit { property_id, .. }
                | DecodedProperty::CastSpell { property_id, .. }
                | DecodedProperty::Trap { property_id, .. }
                | DecodedProperty::ThievesTools { property_id, .. }
                | DecodedProperty::ComputerSpike { property_id, .. }
                | DecodedProperty::UseLimitationFeat { property_id, .. }
                | DecodedProperty::UseLimitationRacial { property_id, .. }
                | DecodedProperty::UseLimitationAlignmentGroup { property_id, .. }
                | DecodedProperty::DamageRacialGroup { property_id, .. }
                | DecodedProperty::DamageAlignmentGroup { property_id, .. }
                | DecodedProperty::EnhancementRacialGroup { property_id, .. }
                | DecodedProperty::EnhancementAlignmentGroup { property_id, .. }
                | DecodedProperty::AttackBonusAlignmentGroup { property_id, .. }
                | DecodedProperty::TrueSeeing { property_id, .. }
                | DecodedProperty::Light { property_id, .. }
                | DecodedProperty::AttackBonus { property_id, .. }
                | DecodedProperty::Keen { property_id, .. }
                | DecodedProperty::MassiveCriticals { property_id, .. }
                | DecodedProperty::BlasterBoltDeflectIncrease { property_id, .. }
                | DecodedProperty::MonsterDamage { property_id, .. }
                | DecodedProperty::BonusFeats { property_id, .. }
                | DecodedProperty::Immunity { property_id, .. }
                | DecodedProperty::Skill { property_id, .. }
                | DecodedProperty::AttackPenalty { property_id, .. }
                | DecodedProperty::DamagePenalty { property_id, .. }
                | DecodedProperty::MagicResistBonus { property_id, .. }
                | DecodedProperty::DamageNone { property_id, .. }
                | DecodedProperty::Regeneration { property_id, .. }
                | DecodedProperty::RegenerationForcePoints { property_id, .. }
                | DecodedProperty::Disguise { property_id, .. }
                | DecodedProperty::Unknown { property_id, .. } => *property_id,
            })
            .collect();
        assert_eq!(ids, vec![7, 0, 45]);
    }

    #[test]
    fn is_armor_delegates_to_source_uti_for_armor_base_item() {
        // Base item 35 is in the armor block per `is_armor_base_item`.
        let uti = Uti {
            base_item: 35,
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        assert!(view.is_armor());
        // Sanity: matches the source's own pure check.
        assert_eq!(view.is_armor(), uti.is_armor());
    }

    #[test]
    fn is_armor_returns_false_for_non_armor_base_item() {
        // Base item 0 (typically a melee weapon slot) is not armor.
        let uti = Uti {
            base_item: 0,
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        assert!(!view.is_armor());
    }

    /// Builds a `baseitems.2da` fixture with the columns the combat /
    /// equip queries read. Each `(row_index, weaponwield, stacking,
    /// equipableslots, modeltype)` tuple populates one row; intermediate
    /// rows get blank cells.
    fn baseitems_with_rows(rows: &[(usize, &str, &str, &str, &str)]) -> TwoDa {
        let max_row = rows.iter().map(|(idx, ..)| *idx).max().unwrap_or(0);
        let mut table_rows = Vec::with_capacity(max_row + 1);
        for row_index in 0..=max_row {
            let cells = rows
                .iter()
                .find(|(idx, ..)| *idx == row_index)
                .map(|(_, ww, st, eq, mt)| {
                    vec![
                        (*ww).to_string(),
                        (*st).to_string(),
                        (*eq).to_string(),
                        (*mt).to_string(),
                    ]
                })
                .unwrap_or_else(|| vec![String::new(); 4]);
            table_rows.push(TwoDaRow {
                label: row_index.to_string(),
                cells,
            });
        }
        TwoDa {
            headers: vec![
                "weaponwield".to_string(),
                "stacking".to_string(),
                "equipableslots".to_string(),
                "modeltype".to_string(),
            ],
            rows: table_rows,
        }
    }

    #[test]
    fn combat_equip_queries_default_to_safe_values_without_baseitems() {
        // No `baseitems.2da` in any source: queries return their
        // documented "we don't know" defaults rather than panicking.
        let uti = Uti {
            base_item: 2,
            ..Uti::default()
        };
        let mut tables = TestTables::new();

        let view = uti.resolve(&mut tables);
        assert!(!view.is_weapon());
        assert!(!view.is_consumable());
        assert!(view.equip_slot_mask().is_none());
        assert!(view.model_type().is_none());
    }

    #[test]
    fn combat_equip_queries_default_when_base_item_row_is_absent() {
        // `baseitems.2da` is loaded but does not contain row 99.
        // Queries should behave as if the table were missing.
        let table = baseitems_with_rows(&[(2, "2", "1", "0x00030", "0")]);
        let mut tables = TestTables::with("baseitems", &table);

        let uti = Uti {
            base_item: 99,
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);
        assert!(!view.is_weapon());
        assert!(!view.is_consumable());
        assert!(view.equip_slot_mask().is_none());
        assert!(view.model_type().is_none());
    }

    #[test]
    fn is_weapon_reads_weaponwield_column() {
        // Row 2 in vanilla baseitems is Long_Sword with weaponwield=2.
        // Row 35 is an armor row with weaponwield blank (-> 0).
        let table =
            baseitems_with_rows(&[(2, "2", "1", "0x00030", "0"), (35, "", "1", "0x00018", "0")]);
        let mut tables = TestTables::with("baseitems", &table);

        let weapon = Uti {
            base_item: 2,
            ..Uti::default()
        };
        assert!(weapon.resolve(&mut tables).is_weapon());

        let armor = Uti {
            base_item: 35,
            ..Uti::default()
        };
        assert!(!armor.resolve(&mut tables).is_weapon());
    }

    #[test]
    fn is_consumable_reads_stacking_column() {
        // Vanilla consumables like stim packs / grenades / med kits
        // have stacking > 1 (typically 99). Equipment has stacking
        // exactly 1. The threshold is `> 1`.
        let table = baseitems_with_rows(&[
            (60, "0", "99", "0x40000", "0"),
            (35, "0", "1", "0x00018", "0"),
        ]);
        let mut tables = TestTables::with("baseitems", &table);

        let stim = Uti {
            base_item: 60,
            ..Uti::default()
        };
        assert!(stim.resolve(&mut tables).is_consumable());

        let armor = Uti {
            base_item: 35,
            ..Uti::default()
        };
        assert!(!armor.resolve(&mut tables).is_consumable());
    }

    #[test]
    fn equip_slot_mask_parses_hex_string_with_or_without_prefix() {
        // The vanilla cell stores hex with `0x` prefix
        // (e.g. `0x00030`). Tolerate uppercase prefix and a bare
        // hex string too, in case mod tables omit the prefix.
        let table = baseitems_with_rows(&[
            (2, "2", "1", "0x00030", "0"),
            (3, "2", "1", "0X00030", "0"),
            (4, "2", "1", "00030", "0"),
        ]);
        let mut tables = TestTables::with("baseitems", &table);

        for base in [2, 3, 4] {
            let uti = Uti {
                base_item: base,
                ..Uti::default()
            };
            assert_eq!(uti.resolve(&mut tables).equip_slot_mask(), Some(0x0030));
        }
    }

    #[test]
    fn model_type_reads_numeric_column() {
        let table = baseitems_with_rows(&[
            (2, "2", "1", "0x00030", "0"),
            (38, "0", "1", "0x00018", "1"),
            (75, "0", "1", "0x00400", "2"),
        ]);
        let mut tables = TestTables::with("baseitems", &table);

        for (base, expected) in [(2, 0_u8), (38, 1), (75, 2)] {
            let uti = Uti {
                base_item: base,
                ..Uti::default()
            };
            assert_eq!(uti.resolve(&mut tables).model_type(), Some(expected));
        }
    }

    #[test]
    fn has_property_kind_matches_each_family() {
        // Build a Uti carrying one property from each family the
        // filter enum covers, then confirm each filter matches.
        let table = itempropdef_with_labels(&[
            (0, "Ability"),
            (10, "CastSpell"),
            (11, "Damage"),
            (26, "ImprovedSavingThrows"),
            (38, "AttackBonus"),
            (5, "Enhancement"),
            (57, "Use_Limitation_Feat"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![
                property(0, 0),
                property(10, 0),
                property(11, 0),
                property(26, 0),
                property(38, 0),
                property(5, 0),
                property(57, 0),
            ],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(view.has_property_kind(PropertyKindFilter::Ability));
        assert!(view.has_property_kind(PropertyKindFilter::Active));
        assert!(view.has_property_kind(PropertyKindFilter::Damage));
        assert!(view.has_property_kind(PropertyKindFilter::Save));
        assert!(view.has_property_kind(PropertyKindFilter::Attack));
        assert!(view.has_property_kind(PropertyKindFilter::Enhancement));
        assert!(view.has_property_kind(PropertyKindFilter::UseLimitation));
    }

    #[test]
    fn has_property_kind_returns_false_for_unrepresented_families() {
        // Item with only an AbilityBonus should match Ability but
        // none of the other filters.
        let table = itempropdef_with_labels(&[(0, "Ability")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(0, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        assert!(view.has_property_kind(PropertyKindFilter::Ability));
        for filter in [
            PropertyKindFilter::Damage,
            PropertyKindFilter::Save,
            PropertyKindFilter::Attack,
            PropertyKindFilter::Enhancement,
            PropertyKindFilter::UseLimitation,
            PropertyKindFilter::Active,
        ] {
            assert!(
                !view.has_property_kind(filter),
                "unexpected match for {filter:?}"
            );
        }
    }

    #[test]
    fn has_property_kind_damage_covers_full_damage_family() {
        // The Damage filter is the broadest: it should match
        // DamageBonus, DamageImmunity, DamageResistance,
        // DamageRacialGroup, DamageAlignmentGroup, and DamagePenalty.
        // (DamageNone is intentionally excluded from the filter set.)
        let table = itempropdef_with_labels(&[
            (11, "Damage"),
            (12, "DamageAlignmentGroup"),
            (13, "DamageRacialGroup"),
            (14, "DamageImmunity"),
            (15, "DamagePenalty"),
            (17, "DamageResist"),
        ]);
        let mut tables = TestTables::with("itempropdef", &table);

        for row in [11_u16, 12, 13, 14, 15, 17] {
            let uti = Uti {
                properties: vec![property(row, 0)],
                ..Uti::default()
            };
            let view = uti.resolve(&mut tables);
            assert!(
                view.has_property_kind(PropertyKindFilter::Damage),
                "expected Damage filter to match row {row}"
            );
        }
    }

    #[test]
    fn has_property_kind_does_not_match_unknown_variants() {
        // A property whose label has no typed dispatch arm becomes
        // Unknown; no filter family includes Unknown.
        let table = itempropdef_with_labels(&[(200, "FakeMod_GrantsCookies")]);
        let mut tables = TestTables::with("itempropdef", &table);

        let uti = Uti {
            properties: vec![property(200, 0)],
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);

        for filter in [
            PropertyKindFilter::Damage,
            PropertyKindFilter::Ability,
            PropertyKindFilter::Save,
            PropertyKindFilter::Attack,
            PropertyKindFilter::Enhancement,
            PropertyKindFilter::UseLimitation,
            PropertyKindFilter::Active,
        ] {
            assert!(
                !view.has_property_kind(filter),
                "Unknown variant should not match {filter:?}"
            );
        }
    }

    #[test]
    fn has_property_kind_returns_false_for_empty_property_list() {
        let uti = Uti::default();
        let mut tables = TestTables::new();
        let view = uti.resolve(&mut tables);

        for filter in [
            PropertyKindFilter::Damage,
            PropertyKindFilter::Ability,
            PropertyKindFilter::Save,
            PropertyKindFilter::Attack,
            PropertyKindFilter::Enhancement,
            PropertyKindFilter::UseLimitation,
            PropertyKindFilter::Active,
        ] {
            assert!(!view.has_property_kind(filter));
        }
    }

    #[test]
    fn combat_equip_queries_return_field_defaults_for_unparseable_cells() {
        // A row exists but cells are unparseable (non-numeric). Each
        // query falls back to its documented safe default rather than
        // crashing or surfacing garbage.
        let table = baseitems_with_rows(&[(2, "junk", "stuff", "not-hex", "wat")]);
        let mut tables = TestTables::with("baseitems", &table);

        let uti = Uti {
            base_item: 2,
            ..Uti::default()
        };
        let view = uti.resolve(&mut tables);
        assert!(!view.is_weapon());
        assert!(!view.is_consumable());
        assert!(view.equip_slot_mask().is_none());
        assert!(view.model_type().is_none());
    }

    /// Builds an `itempropdef.2da` fixture with both the `label` and
    /// `SubTypeResRef` columns populated per row. Empty `subtype_resref`
    /// matches a property that has no subtype dimension (engine
    /// short-circuits the dispatch).
    fn itempropdef_with_subtypes(rows: &[(usize, &str, &str)]) -> TwoDa {
        let max_row = rows.iter().map(|(idx, _, _)| *idx).max().unwrap_or(0);
        let mut table_rows = Vec::with_capacity(max_row + 1);
        for row_index in 0..=max_row {
            let (label, subtype_resref) = rows
                .iter()
                .find(|(idx, _, _)| *idx == row_index)
                .map(|(_, label, sr)| ((*label).to_string(), (*sr).to_string()))
                .unwrap_or_default();
            table_rows.push(TwoDaRow {
                label: row_index.to_string(),
                cells: vec![label, subtype_resref],
            });
        }
        TwoDa {
            headers: vec!["label".to_string(), "SubTypeResRef".to_string()],
            rows: table_rows,
        }
    }

    /// Builds a per-property subtype 2DA (e.g. `iprp_damagecost.2da`)
    /// with just the `label` column populated.
    fn subtype_2da(labels: &[(usize, &str)]) -> TwoDa {
        // The actual game tables carry a Name (StrRef) column too, but
        // the helper only consumes `label`, so we keep the fixture
        // minimal.
        itempropdef_with_labels(labels)
    }

    fn add_2da_entry(tables: &mut TestTables, name: &str, table: &TwoDa) {
        tables.insert(name, table);
    }

    #[test]
    fn subtype_label_resolves_full_chain_for_known_property() {
        // PropertyName 7 -> "Damage" -> iprp_damagecost.2da
        // Subtype 5 -> "Acid"
        let propdef = itempropdef_with_subtypes(&[
            (0, "Ability", "iprp_abilities"),
            (7, "Damage", "iprp_damagecost"),
        ]);
        let damagecost = subtype_2da(&[(0, "Bludgeoning"), (5, "Acid")]);

        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_damagecost", &damagecost);

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: Some("Damage".to_string()),
            subtype: 5,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert_eq!(prop.subtype_label(&mut tables).as_deref(), Some("Acid"));
    }

    #[test]
    fn subtype_label_returns_none_for_property_with_empty_subtype_resref() {
        // Property 7 exists but has no subtype dimension (empty
        // SubTypeResRef cell). Engine short-circuits; helper does too.
        let propdef = itempropdef_with_subtypes(&[(7, "Light", "")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: Some("Light".to_string()),
            subtype: 0,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn subtype_label_returns_none_when_subtype_table_resref_is_missing() {
        // Property 99 isn't in itempropdef at all (row absent). No
        // dispatch chain to walk.
        let propdef = itempropdef_with_subtypes(&[(0, "Ability", "iprp_abilities")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);

        let prop = DecodedProperty::Unknown {
            property_id: 99,
            property_label: None,
            subtype: 0,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn subtype_label_returns_none_when_subtype_table_cannot_be_loaded() {
        // itempropdef points at iprp_damagecost but no source provides
        // that 2DA. Helper must not panic.
        let propdef = itempropdef_with_subtypes(&[(7, "Damage", "iprp_damagecost")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: Some("Damage".to_string()),
            subtype: 0,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn subtype_label_returns_none_when_subtype_row_is_out_of_bounds() {
        // Subtype 99 is past the loaded subtype table's row count.
        let propdef = itempropdef_with_subtypes(&[(7, "Damage", "iprp_damagecost")]);
        let damagecost = subtype_2da(&[(0, "Bludgeoning"), (1, "Slashing")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_damagecost", &damagecost);

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: Some("Damage".to_string()),
            subtype: 99,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn subtype_label_returns_none_when_itempropdef_is_missing() {
        // No 2DAs at all. Helper must not panic.
        let mut tables = TestTables::new();

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: None,
            subtype: 5,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert!(prop.subtype_label(&mut tables).is_none());
    }

    #[test]
    fn subtype_label_resolves_mod_extended_subtype_row() {
        // Vanilla iprp_damagecost typically stops short of row 200; a
        // mod adds row 200 carrying a custom label. The helper must
        // surface that label without downgrading to None.
        let propdef = itempropdef_with_subtypes(&[(7, "Damage", "iprp_damagecost")]);
        let damagecost = subtype_2da(&[(200, "FakeMod_PsionicBurn")]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_damagecost", &damagecost);

        let prop = DecodedProperty::Unknown {
            property_id: 7,
            property_label: Some("Damage".to_string()),
            subtype: 200,
            cost_table: 0,
            cost_value: 0,
            param1: 0,
            param1_value: 0,
        };
        assert_eq!(
            prop.subtype_label(&mut tables).as_deref(),
            Some("FakeMod_PsionicBurn")
        );
    }

    // -- Projection / resolve two-stage path --

    #[test]
    fn project_with_itempropdef_dispatches_typed_variants() {
        // Property name 0 (`Ability`) routes to AbilityBonus when the
        // projection has the itempropdef table to dispatch from.
        let uti = Uti {
            properties: vec![property(0, 2)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(0, "Ability")]);

        let projection = uti.project(Some(&propdef));
        assert!(matches!(
            projection.properties()[0],
            DecodedProperty::AbilityBonus { subtype_id: 2, .. }
        ));
    }

    #[test]
    fn project_without_itempropdef_falls_back_to_unknown_no_label() {
        // Passing None for itempropdef must not panic and must
        // gracefully degrade every property to Unknown with no label.
        // Equivalent to the engine's tolerance of a missing
        // itempropdef.2da at load time.
        let uti = Uti {
            properties: vec![property(0, 2), property(11, 4)],
            ..Uti::default()
        };

        let projection = uti.project(None);
        let labels: Vec<Option<&str>> = projection
            .properties()
            .iter()
            .map(|prop| match prop {
                DecodedProperty::Unknown { property_label, .. } => property_label.as_deref(),
                _ => panic!("expected every property to land in Unknown without itempropdef"),
            })
            .collect();
        assert_eq!(labels, vec![None, None]);
    }

    #[test]
    fn projection_resolve_loads_baseitems_for_queries() {
        // Build a projection with no itempropdef (irrelevant for the
        // baseitems-backed query under test), then resolve it through
        // a cache that exposes a weapon row at the UTI's base_item id.
        let uti = Uti {
            base_item: 0,
            ..Uti::default()
        };
        let baseitems = baseitems_with_rows(&[(0, "5", "0", "0x0010", "3")]);
        let mut tables = TestTables::with("baseitems", &baseitems);

        let projection = uti.project(None);
        let resolved = projection.resolve(&mut tables);

        assert!(resolved.is_weapon());
        assert_eq!(resolved.equip_slot_mask(), Some(0x0010));
        assert_eq!(resolved.model_type(), Some(3));
    }

    #[test]
    fn one_projection_feeds_independent_resolutions_per_scope() {
        // Mod conflict scenario: same UTI bytes, two scopes whose
        // baseitems.2da rows disagree on whether base_item 0 is a
        // weapon. The projection's typed dispatch is shared (no
        // re-projection); each resolution reports the value under
        // its own context.
        let uti = Uti {
            base_item: 0,
            ..Uti::default()
        };

        let vanilla_baseitems = baseitems_with_rows(&[(0, "5", "0", "0x0010", "3")]);
        let mut vanilla_tables = TestTables::with("baseitems", &vanilla_baseitems);

        // Mod rebalances the row so the same base_item id is no
        // longer wielded as a weapon (weaponwield = 0).
        let mod_baseitems = baseitems_with_rows(&[(0, "0", "10", "0x0000", "0")]);
        let mut mod_tables = TestTables::with("baseitems", &mod_baseitems);

        let projection = uti.project(None);
        let vanilla = projection.resolve(&mut vanilla_tables);
        let modded = projection.resolve(&mut mod_tables);

        assert!(vanilla.is_weapon());
        assert!(!modded.is_weapon());
        assert!(modded.is_consumable(), "mod row marks the item stackable");
        assert!(!vanilla.is_consumable());
    }

    #[test]
    fn resolve_sugar_matches_project_then_resolve() {
        // `Uti::resolve(&mut tables)` is defined as sugar for
        // `project(propdef_from_cache).resolve(cache)`. Both paths
        // must produce identical resolutions on every query they
        // expose.
        let uti = Uti {
            base_item: 0,
            properties: vec![property(0, 2)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(0, "Ability")]);
        let baseitems = baseitems_with_rows(&[(0, "5", "0", "0x0010", "3")]);
        let mut sugar_tables = TestTables::new();
        add_2da_entry(&mut sugar_tables, "itempropdef", &propdef);
        add_2da_entry(&mut sugar_tables, "baseitems", &baseitems);
        let mut explicit_tables = TestTables::new();
        add_2da_entry(&mut explicit_tables, "itempropdef", &propdef);
        add_2da_entry(&mut explicit_tables, "baseitems", &baseitems);

        let sugar = uti.resolve(&mut sugar_tables);

        let projection = {
            let propdef_ref = explicit_tables.twoda(tables::ITEMPROPDEF);
            uti.project(propdef_ref)
        };
        let explicit = projection.resolve(&mut explicit_tables);

        assert_eq!(sugar.properties(), explicit.properties());
        assert_eq!(sugar.is_weapon(), explicit.is_weapon());
        assert_eq!(sugar.is_consumable(), explicit.is_consumable());
        assert_eq!(sugar.equip_slot_mask(), explicit.equip_slot_mask());
        assert_eq!(sugar.model_type(), explicit.model_type());
    }

    // -- Property-bundle iterators (magnitude resolution) --

    /// Builds an `iprp_costtable.2da` fixture with a `Name` column
    /// holding the per-cost 2DA resref for each declared row.
    /// Intermediate rows get an empty `Name`.
    fn iprp_costtable_with_entries(rows: &[(usize, &str)]) -> TwoDa {
        let max_row = rows.iter().map(|(idx, _)| *idx).max().unwrap_or(0);
        let mut table_rows = Vec::with_capacity(max_row + 1);
        for row_index in 0..=max_row {
            let name = rows
                .iter()
                .find(|(idx, _)| *idx == row_index)
                .map(|(_, name)| (*name).to_string())
                .unwrap_or_default();
            table_rows.push(TwoDaRow {
                label: row_index.to_string(),
                cells: vec![name],
            });
        }
        TwoDa {
            headers: vec!["Name".to_string()],
            rows: table_rows,
        }
    }

    /// Builds a generic per-cost 2DA (`iprp_bonuscost`,
    /// `iprp_immuncost`, etc.) with a `Value` column holding the
    /// magnitude for each declared row. Intermediate rows get an
    /// empty cell.
    fn cost_value_2da(rows: &[(usize, i32)]) -> TwoDa {
        let max_row = rows.iter().map(|(idx, _)| *idx).max().unwrap_or(0);
        let mut table_rows = Vec::with_capacity(max_row + 1);
        for row_index in 0..=max_row {
            let value = rows
                .iter()
                .find(|(idx, _)| *idx == row_index)
                .map(|(_, value)| value.to_string())
                .unwrap_or_default();
            table_rows.push(TwoDaRow {
                label: row_index.to_string(),
                cells: vec![value],
            });
        }
        TwoDa {
            headers: vec!["Value".to_string()],
            rows: table_rows,
        }
    }

    /// Builds a UTI carrying one property with explicit cost-table
    /// addressing. The decoder cares only about `property_name`,
    /// `subtype`, `cost_table`, and `cost_value` for the kinds the
    /// iterators yield; other fields take their default sentinels.
    fn property_with_cost(
        property_name: u16,
        subtype: u16,
        cost_table: u8,
        cost_value: u16,
    ) -> UtiProperty {
        UtiProperty {
            cost_table,
            cost_value,
            param1: 0xFF,
            param1_value: 0,
            property_name,
            subtype,
            chance_appear: 100,
            useable: None,
            uses_per_day: None,
            upgrade_type: None,
        }
    }

    #[test]
    fn damage_bonuses_yields_cost_value_as_magnitude() {
        // ApplyDamageBonus is a bypass handler: CostValue is the
        // damage amount directly. No per-cost 2DA needs to be in
        // the resolver, only itempropdef for typed dispatch.
        let uti = Uti {
            properties: vec![
                property_with_cost(11, 3, 4, 7),
                property_with_cost(11, 5, 4, 12),
            ],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(11, "Damage")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let resolved = uti.resolve(&mut tables);
        let yielded: Vec<(u16, i32)> = resolved.damage_bonuses().collect();
        assert_eq!(yielded, vec![(3, 7), (5, 12)]);
    }

    #[test]
    fn ability_bonuses_resolve_magnitude_from_iprp_bonuscost_value() {
        // ApplyAbilityBonus reads iprp_bonuscost row at CostValue,
        // column Value, with the cost-table index hardcoded by the
        // handler. The property's cost_table field is irrelevant
        // and should not influence resolution.
        let uti = Uti {
            properties: vec![
                property_with_cost(0, 2, 99, 4), // STR, cost_value 4 -> 2
                property_with_cost(0, 4, 99, 7), // WIS, cost_value 7 -> 5
            ],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(0, "Ability")]);
        let bonuscost = cost_value_2da(&[(4, 2), (7, 5)]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_bonuscost", &bonuscost);

        let resolved = uti.resolve(&mut tables);
        let yielded: Vec<(u16, i32)> = resolved.ability_bonuses().collect();
        assert_eq!(yielded, vec![(2, 2), (4, 5)]);
    }

    #[test]
    fn ability_bonuses_yield_nothing_when_iprp_bonuscost_missing() {
        // The source has itempropdef so the AbilityBonus variant
        // dispatches, but iprp_bonuscost is absent. The iterator
        // silently skips properties whose magnitude could not be
        // resolved rather than panicking or yielding a sentinel.
        let uti = Uti {
            properties: vec![property_with_cost(0, 2, 1, 4)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(0, "Ability")]);
        let mut tables = TestTables::with("itempropdef", &propdef);

        let resolved = uti.resolve(&mut tables);
        assert_eq!(resolved.ability_bonuses().count(), 0);
    }

    #[test]
    fn damage_immunities_walk_dynamic_cost_table_dispatch() {
        // ApplyDamageImmunity reads the cost-table index from each
        // property's cost_table field. The vanilla path uses index
        // 5 -> iprp_immuncost. Verify the dispatch follows the
        // iprp_costtable.Name resref and looks up the magnitude.
        let uti = Uti {
            properties: vec![property_with_cost(14, 8, 5, 3)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(14, "DamageImmunity")]);
        // Index 5 -> "iprp_immuncost", matching vanilla's layout.
        let costtable = iprp_costtable_with_entries(&[(5, "IPRP_IMMUNCOST")]);
        let immuncost = cost_value_2da(&[(3, 50)]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_costtable", &costtable);
        add_2da_entry(&mut tables, "iprp_immuncost", &immuncost);

        let resolved = uti.resolve(&mut tables);
        let yielded: Vec<(u16, i32)> = resolved.damage_immunities().collect();
        assert_eq!(yielded, vec![(8, 50)]);
    }

    #[test]
    fn damage_immunities_follow_mod_extended_cost_table_index() {
        // Mod-extended cost-table scenario: iprp_costtable carries a
        // row past vanilla's range pointing at a new cost 2DA. The
        // iterator must follow the dispatch via the property's own
        // cost_table field rather than hardcoding the vanilla index.
        let uti = Uti {
            properties: vec![property_with_cost(14, 8, 26, 1)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(14, "DamageImmunity")]);
        let costtable = iprp_costtable_with_entries(&[(26, "mod_immuncost")]);
        let modded_cost = cost_value_2da(&[(1, 75)]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_costtable", &costtable);
        add_2da_entry(&mut tables, "mod_immuncost", &modded_cost);

        let resolved = uti.resolve(&mut tables);
        let yielded: Vec<(u16, i32)> = resolved.damage_immunities().collect();
        assert_eq!(yielded, vec![(8, 75)]);
    }

    #[test]
    fn iterators_only_yield_matching_kind() {
        // An item carries one of each magnitude-resolvable kind.
        // Each iterator must yield only its own kind.
        let uti = Uti {
            properties: vec![
                property_with_cost(0, 2, 1, 4),  // AbilityBonus
                property_with_cost(11, 3, 4, 7), // DamageBonus
                property_with_cost(14, 8, 5, 3), // DamageImmunity
            ],
            ..Uti::default()
        };
        let propdef =
            itempropdef_with_labels(&[(0, "Ability"), (11, "Damage"), (14, "DamageImmunity")]);
        let bonuscost = cost_value_2da(&[(4, 2)]);
        let costtable = iprp_costtable_with_entries(&[(5, "iprp_immuncost")]);
        let immuncost = cost_value_2da(&[(3, 50)]);
        let mut tables = TestTables::new();
        add_2da_entry(&mut tables, "itempropdef", &propdef);
        add_2da_entry(&mut tables, "iprp_bonuscost", &bonuscost);
        add_2da_entry(&mut tables, "iprp_costtable", &costtable);
        add_2da_entry(&mut tables, "iprp_immuncost", &immuncost);

        let resolved = uti.resolve(&mut tables);
        assert_eq!(resolved.ability_bonuses().collect::<Vec<_>>(), vec![(2, 2)]);
        assert_eq!(resolved.damage_bonuses().collect::<Vec<_>>(), vec![(3, 7)]);
        assert_eq!(
            resolved.damage_immunities().collect::<Vec<_>>(),
            vec![(8, 50)]
        );
    }

    #[test]
    fn one_projection_yields_diverging_magnitudes_per_scope() {
        // Mod conflict scenario for magnitude resolution: same UTI
        // bytes, two scopes whose iprp_bonuscost rebalances the
        // ability bonus magnitude. The shared projection survives;
        // each per-scope resolution reports its own value.
        let uti = Uti {
            properties: vec![property_with_cost(0, 2, 1, 4)],
            ..Uti::default()
        };
        let propdef = itempropdef_with_labels(&[(0, "Ability")]);

        let vanilla_bonus = cost_value_2da(&[(4, 2)]);
        let mut vanilla_tables = TestTables::new();
        add_2da_entry(&mut vanilla_tables, "itempropdef", &propdef);
        add_2da_entry(&mut vanilla_tables, "iprp_bonuscost", &vanilla_bonus);

        let mod_bonus = cost_value_2da(&[(4, 6)]); // Mod rebalances row 4 from +2 to +6.
        let mut mod_tables = TestTables::new();
        add_2da_entry(&mut mod_tables, "itempropdef", &propdef);
        add_2da_entry(&mut mod_tables, "iprp_bonuscost", &mod_bonus);

        let projection = {
            let propdef_ref = vanilla_tables.twoda(tables::ITEMPROPDEF);
            uti.project(propdef_ref)
        };
        let vanilla = projection.resolve(&mut vanilla_tables);
        let modded = projection.resolve(&mut mod_tables);

        assert_eq!(vanilla.ability_bonuses().collect::<Vec<_>>(), vec![(2, 2)]);
        assert_eq!(modded.ability_bonuses().collect::<Vec<_>>(), vec![(2, 6)]);
    }
}