MosswartOverlord/docs/superpowers/specs/2026-07-15-weapon-od-rating-design.md

# Weapon OD rating — compute, store, filter

**Date:** 2026-07-15
**Status:** Approved

## Problem

The inventory search has weak weapon/wand support. Mag-Tools (and UtilityBelt's
port of it, the "retail comparison" / OD feature) classifies weapons by **OD
("over damage")** — how much better a weapon's optimally-tinked output is than
the best possible *retail* loot weapon of its class and wield tier. Users want
to filter weapons by OD.

## Authoritative algorithm (researched 2026-07-15)

Source: `UtilityBelt/UtilityBelt/Tools/ItemInfo.cs` (sections titled "Slightly
modified MagTools item description classes", OD display at lines ~631-647) +
`UtilityBelt/UtilityBelt/Lib/ItemInfoHelper/{MiscCalcs,WeaponMods,Dictionaries}.cs`
in this workspace. WeaponMods.cs holds the **best-values table**: rows keyed by
`(Skill, Mastery, MultiStrike, WieldReq)` with columns
`MaxDmg, MaxVar, MaxDmgMod, MaxElementalDmgBonus, MaxElementalDmgVsMonsters`
(sourced from acpedia; ~330 rows covering heavy/light/finesse/two-handed melee
subtypes, bow/xbow/thrown, war/void casters).

Raw item keys (verified present in our `item_raw_data`):
- IntValues: `159` EquipSkill, `353` Mastery/WeaponType, `160` WieldReqValue,
  `218103842` MaxDamage, `204` ElementalDmgBonus, `171` Tinks, `179` Imbued
  (bitmask, nonzero = imbued), `131` Material.
- `original_json->DoubleValues`: `167772171` Variance, `167772174` DamageBonus
  (missile dmg modifier, e.g. 2.73 = 173%), `152` ElementalDmgVsMonsters
  (wands), `167772169` SalvageWorkmanship.
- `original_json->Spells` / `ActiveSpells`: innate and active spell id arrays.

**Buffed values** (GetBuffedIntValueKey / GetBuffedDoubleValueKey semantics):
value + Σ bonus(innate Spells) − Σ change(ActiveSpells), using the spell-effect
subset from UB `Dictionaries.cs`: MaxDamage — Blood Drinker VI 1616:+20,
Infected Caress 2096:+22, Incant. BD 5183/4395:+24, Minor/Major/Epic/Legendary
Blood Thirst 2598:+2/2586:+4/4661:+7/6089:+10, Prodigal BD 3688:+300 (bonus =
change for all these); ElemVsMonsters (double) — Spirit Drinker VI 3258:+.06,
Infected Spirit Caress 3259:+.07, Incant. SD 5182/4414:+.08, Minor/Major/Epic/
Legendary Spirit Thirst 3251:+.01/3250:+.03/4670:+.05/6098:+.07.

**MultiStrike** weapons: WeaponType (key 47 in UB code = our int key 47? no —
UB reads LongValueKey 47 = WeaponType master id; the multistrike check is:
`IntValues[47] ∈ {160,166,486}` or (`47==4` and mastery `353==11`)). Verify key
47 exists in our data during implementation; if absent, derive from mastery
subtype comments in the table (msdagger/mssword/cleaver rows are the
MultiStrike=1 rows).

Formulas (OD, higher = better; retail max = 0):
- **Melee** (object_class 1):
  `varianceTinks = round(log(MaxVar_t / variance) / log(0.8), 2)`;
  `OD = buffedMaxDmg − varianceTinks − MaxDmg_t`.
- **Missile** (object_class 9):
  `dmgMod = buffedDmgBonus·100 − 100`; `arrowMax` by mastery: bow(8)=40,
  xbow(9)=53, thrown(10)=42; `remainingTinks`: 10 − tinks, −1 more if not
  imbued, floor 0 (loot-gen only, see gate below; UB nuance: if tinks==0,
  remainingTinks=9);
  `buffedDmg = buffedMaxDmg; if ≤10 then +24`;
  `maxMod = (MaxDmgMod_t + 100 + 36)/100`;
  `OD = (1 + (dmgMod + 4·remainingTinks)/100) · (buffedElemBonus + buffedDmg + arrowMax) / maxMod − (MaxElemBonus_t + 24 + arrowMax)`.
- **Wand** (object_class 31, skill 34 war / 43 void):
  `OD = (buffedElemVsMonsters − MaxElemVsMonsters_t) · 100` (percentage points;
  e.g. live Frost Baton: (1.40 − 1.18)·100 = +22).
- **Gate**: OD only for loot-gen items (`SalvageWorkmanship > 0`); otherwise
  NULL. Table lookup miss (unknown skill/mastery/wieldreq combo) → NULL.
  Round stored OD to 2 decimals.

## Decisions (user-approved)

1. **Raw OD number** with a `min OD ≥` filter (not a bucketed 0-10 scale).
2. **All classes**: melee, missile, wands.
3. **Computed at ingest**, stored on `items.od_rating DOUBLE PRECISION NULL`,
   with a one-off backfill for existing rows.

## Backend (inventory-go)

- New `od.go`: best-values table ported from UB `WeaponMods.cs` (verify row
  count and spot-check values against the source file), buffed-value helpers,
  `computeOD(raw map[string]any) (float64, bool)`. TDD with golden values
  (incl. the live Frost Baton +22 case).
- `processItem` sets `items["od_rating"]` (or omits when NULL) — the dynamic
  insert in ingest.go picks it up automatically.
- `schema.go`: add `od_rating DOUBLE PRECISION` to the items DDL (fresh
  installs). Live DB gets a manual
  `ALTER TABLE items ADD COLUMN IF NOT EXISTS od_rating double precision`
  (prod runs SKIP_SCHEMA_INIT=true).
- Search: `i.od_rating` added to the CTE; `min_od` (>=) and `max_od` (<=)
  params; sort key `od`. NULL od never matches the filters (SQL NULL
  semantics) and sorts NULLS LAST/FIRST as usual.
- Backfill: `POST /admin/backfill-od` — iterates items of object_class 1/9/31
  joined to item_raw_data, recomputes, UPDATEs `od_rating`; returns counts.
  Service is internal-only (127.0.0.1:8772 / compose network).

## Frontend

- `RATING_DEFS` gains `{param:'min_od', label:'Weapon OD', common:true}` —
  flows through the existing ratings record, sidebar inputs, chips, and URL
  state with no new plumbing.
- `COLUMNS` gains `{key:'od_rating', label:'OD', sortKey:'od', defaultVisible:false}`;
  cell renders signed 2-decimal (`+3.25` / `-1.29`), `—` for null.
- `InvItem.od_rating?: number | null`; DetailPanel row "OD" for weapons.

## Verification

- Go unit tests (golden formula values + table spot checks) gate the image
  build as usual.
- Live: backfill count > 0; `min_od=20` returns the Frost Baton; melee/missile
  spot checks against UB in-game values if available; sort by OD desc.

## Out of scope

- Bucketed OD tiers (can be derived later).
- The old suitbuilder page.
- Recomputing OD when spell/enchant state changes intra-session (ingest
  updates overwrite it naturally via the debounced item updates).