azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/items/relic.ts

@@ -0,0 +1,105 @@
+// Relic class gate. AllowableClass is 32767 on all 19 classic relics; lock is subclass × class.
+// Cite: Player.cpp ViableEquipSlots 8039–8083 (6 idol / 7 libram / 6 totem).
+
+import { CLASS } from '../../data/schema.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { EquipGateResult } from './itemRestrictions.ts';
+
+/** INVTYPE_RELIC — equips into EQUIPMENT_SLOT_RANGED. */
+export const INVTYPE_RELIC = 28;
+/** ITEM_SUBCLASS_ARMOR_LIBRAM */
+export const ITEM_SUBCLASS_ARMOR_LIBRAM = 7;
+/** ITEM_SUBCLASS_ARMOR_IDOL */
+export const ITEM_SUBCLASS_ARMOR_IDOL = 8;
+/** ITEM_SUBCLASS_ARMOR_TOTEM */
+export const ITEM_SUBCLASS_ARMOR_TOTEM = 9;
+/** ITEM_SUBCLASS_ARMOR_MISC (ViableEquipSlots warlock branch) */
+export const ITEM_SUBCLASS_ARMOR_MISC = 0;
+
+export type RelicKind = 'libram' | 'idol' | 'totem' | 'misc';
+
+// Armor subclass for relic gates. Prefer armorSubclass — a bare itemSubclass is shared across ALL
+// item classes (tradegoods Herb 9 is the totem enum), so use it only for armor or a fixture.
+function armorSubclassOf(item: ItemDef): number | undefined {
+  if (item.armorSubclass != null) return item.armorSubclass;
+  if (item.itemClass === 4) return item.itemSubclass;
+  if (item.itemClass == null && (item.inventoryType === INVTYPE_RELIC || item.typeName != null)) {
+    return item.itemSubclass;
+  }
+  return undefined;
+}
+
+/** True when the item is a relic (libram / idol / totem / invtype 28). */
+export function isRelicItem(item: ItemDef | undefined): boolean {
+  if (!item) return false;
+  if (item.inventoryType === INVTYPE_RELIC) return true;
+  const sub = armorSubclassOf(item);
+  if (sub === ITEM_SUBCLASS_ARMOR_LIBRAM
+    || sub === ITEM_SUBCLASS_ARMOR_IDOL
+    || sub === ITEM_SUBCLASS_ARMOR_TOTEM) {
+    return true;
+  }
+  const tn = (item.typeName ?? '').toLowerCase();
+  return tn === 'libram' || tn === 'idol' || tn === 'totem' || tn === 'relic';
+}
+
+export function relicKindOf(item: ItemDef): RelicKind | undefined {
+  const sub = armorSubclassOf(item);
+  const tn = (item.typeName ?? '').toLowerCase();
+  if (sub === ITEM_SUBCLASS_ARMOR_LIBRAM || tn === 'libram') return 'libram';
+  if (sub === ITEM_SUBCLASS_ARMOR_IDOL || tn === 'idol') return 'idol';
+  if (sub === ITEM_SUBCLASS_ARMOR_TOTEM || tn === 'totem') return 'totem';
+  if (sub === ITEM_SUBCLASS_ARMOR_MISC && item.inventoryType === INVTYPE_RELIC) return 'misc';
+  return undefined;
+}
+
+/** Class ids ViableEquipSlots accepts for this relic, or undefined if not a relic. */
+export function relicRequiredClasses(item: ItemDef | undefined): number[] | undefined {
+  if (!item || !isRelicItem(item)) return undefined;
+  const kind = relicKindOf(item);
+  if (kind === 'libram') return [CLASS.PALADIN];
+  if (kind === 'idol') return [CLASS.DRUID];
+  if (kind === 'totem') return [CLASS.SHAMAN];
+  if (kind === 'misc') return [CLASS.WARLOCK];
+  if (item.allowClass?.length) return item.allowClass;
+  return undefined;
+}
+
+// Class gate for INVTYPE_RELIC into the ranged paperdoll slot. Non-relics return ok (no-op). Wrong class →
+// refuse.
+export function canEquipRelic(
+  char: { cls: number },
+  item: ItemDef | undefined,
+): EquipGateResult {
+  if (!item || !isRelicItem(item)) return { ok: true };
+
+  if (item.allowClass && !item.allowClass.includes(char.cls)) {
+    return { ok: false, reason: 'Your class cannot use that relic' };
+  }
+
+  const kind = relicKindOf(item);
+  if (kind == null) {
+    if (item.allowClass?.length) return { ok: true };
+    return { ok: false, reason: 'Your class cannot use that relic' };
+  }
+
+  switch (kind) {
+    case 'libram':
+      if (char.cls === CLASS.PALADIN) return { ok: true };
+      return { ok: false, reason: 'Only paladins can equip librams' };
+    case 'idol':
+      if (char.cls === CLASS.DRUID) return { ok: true };
+      return { ok: false, reason: 'Only druids can equip idols' };
+    case 'totem':
+      if (char.cls === CLASS.SHAMAN) return { ok: true };
+      return { ok: false, reason: 'Only shamans can equip totems' };
+    case 'misc':
+      if (char.cls === CLASS.WARLOCK) return { ok: true };
+      return { ok: false, reason: 'Your class cannot use that relic' };
+  }
+}
+
+/** Paladin / Druid / Shaman use Relic.blp and hide ammo. Cite: Player.cpp:8046-8065; PaperDollFrame.lua UnitHasRelicSlot. */
+export function classHasRelicSlot(cls: number): boolean {
+  return cls === CLASS.PALADIN || cls === CLASS.DRUID || cls === CLASS.SHAMAN;
+}

package/src/domain/items/rocketBoots.ts

@@ -0,0 +1,36 @@
+// Goblin Rocket Boots (7189) — the on-use +70% run buff that can blow up on you.
+// Cite: Spell.dbc 8892 description "They are prone to explode however, so use with caution.";
+// aura text "Increases run speed.  Explosive malfunction is possible."
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { SpellDef } from '../../data/schema.ts';
+
+export const GOBLIN_ROCKET_BOOTS = 7189;
+/** src_spell_template 8893 EffectItemType3 — what a malfunction leaves in your bags. */
+export const SCORCHED_ROCKET_BOOTS = 7190;
+/** 8893 "Rocket Boots Malfunction": 2 s stun + 57-93 fire to self + conjure 7190. */
+export const ROCKET_BOOTS_MALFUNCTION_SPELL = 8893;
+
+// UNSOURCED RATE. The malfunction payload and its player-facing warning are tier-2/tier-3 data, but
+// no tier carries the odds: src_spell_template 8892 has one effect and no trigger, 8893 has no
+// caster, a full sweep of every src_* table for 8892/8893 returns nothing, and CMaNGOS never casts
+// 8893 (grep over src/, 2026-08-30). This number is the operator's to set.
+export const ROCKET_BOOTS_MALFUNCTION_PCT = 5;
+
+/** The malfunction rider `combatItems` hangs on the boots, or undefined for every other item. */
+export function rocketBootsMalfunction(
+  entry: number,
+  ds: DataStore,
+  resolve: (raw: SpellDef) => SpellDef,
+): { chancePct: number; spell: SpellDef; destroysInto: number } | undefined {
+  if (entry !== GOBLIN_ROCKET_BOOTS) return undefined;
+  const raw = ds.spell(ROCKET_BOOTS_MALFUNCTION_SPELL);
+  if (!raw) return undefined;
+  // 8893's fire damage is EffectImplicitTargetA 1 (TARGET_UNIT_CASTER) — it burns the WEARER, and
+  // effects-core.ts stamps that as hostile:false so applySpell routes it to the caster.
+  return {
+    chancePct: ROCKET_BOOTS_MALFUNCTION_PCT,
+    spell: resolve(raw),
+    destroysInto: SCORCHED_ROCKET_BOOTS,
+  };
+}

package/src/domain/items/sortContainer.ts

@@ -0,0 +1,139 @@
+// One sort order for every container in the game — your bags, your bank, a companion's bags and
+// their bank. Ported from the SortBags addon's `Item()` tier list (addons/SortBags/SortBags.lua:398-461)
+// with this tree's own predicates standing in for its hardcoded id sets: `mountSpell` for MOUNTS,
+// isKeyItem for KEYS, itemProtectCategory for TOOLS, and the disenchant table for ENCHANTING_MATERIALS.
+// Pure: every function returns a new value.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { Inventory, ItemStack } from './inventory.ts';
+import { addInstance, emptyInventory } from './inventory.ts';
+import { isKeyItem } from './keyring.ts';
+import {
+  itemProtectCategory,
+  protectLookupFor,
+  type ProtectLookup,
+  type ProtectSource,
+} from './junkCategories.ts';
+
+/** Hearthstone — first tile in the addon's order. Cite: SortBags.lua:411. */
+export const HEARTHSTONE_ITEM = 6948;
+
+/** Soul Shard — bucketed with junk so a warlock's shards never split the gear block. Cite: SortBags.lua:423. */
+export const SOUL_SHARD_ITEM = 6265;
+
+/** item_template.class TRADE_GOODS / subclass HERB. Cite: ItemPrototype.h; item-data.json Peacebloom (7/9). */
+const ITEM_CLASS_TRADE_GOODS = 7;
+const ITEM_SUBCLASS_HERB = 9;
+
+/** The DataStore slice a sort needs: junkCategories' lookup plus the disenchant table. */
+export type SortSource = ProtectSource & Pick<DataStore, 'disenchantRules' | 'item'>;
+
+export interface SortLookup extends ProtectLookup {
+  /** Every dust / essence / shard / crystal the disenchant table yields (24 rows). */
+  enchantMats: ReadonlySet<number>;
+  item: (entry: number) => ItemDef | undefined;
+}
+
+const matsByStore = new WeakMap<object, Set<number>>();
+
+// Enchanting materials, derived instead of listed: disenchantRules' yield IS the addon's
+// ENCHANTING_MATERIALS set, and both come to 24 entries.
+export function enchantMaterialEntries(ds: SortSource): ReadonlySet<number> {
+  let mats = matsByStore.get(ds);
+  if (!mats) {
+    mats = new Set<number>();
+    for (const rule of ds.disenchantRules()) {
+      for (const y of rule.yield ?? []) if (y.item > 0) mats.add(y.item);
+    }
+    matsByStore.set(ds, mats);
+  }
+  return mats;
+}
+
+/** One lookup per DataStore — protectLookupFor materializes 1,135 recipe rows. */
+export function sortLookupFor(ds: SortSource): SortLookup {
+  return { ...protectLookupFor(ds), enchantMats: enchantMaterialEntries(ds), item: ds.item };
+}
+
+// The addon's tier number, in the addon's own evaluation order (SortBags.lua:410-460). Lower sorts
+// first. 3 is unused: its SPECIAL set is six unexplained ids, so those items take their own tier.
+export function itemSortTier(
+  stack: ItemStack,
+  it: ItemDef | undefined,
+  look: SortLookup,
+): number {
+  if (!it) return 16;
+  const cat = itemProtectCategory(it, look);
+  if (it.entry === HEARTHSTONE_ITEM) return 1;
+  if (it.mountSpell != null || cat === 'mountPet') return 2;
+  if (cat === 'key' || isKeyItem(it)) return 4;
+  if (cat === 'tool') return 5;
+  if (it.entry === SOUL_SHARD_ITEM) return 14;
+  if (it.conjured) return 15;
+  if (stack.bound) return 6;
+  if (cat === 'reagent') return 7;
+  if (cat === 'quest') return 9;
+  if (cat === 'foodDrink' || cat === 'consumable') return 8;
+  if (look.enchantMats.has(it.entry)) return 11;
+  if (it.itemClass === ITEM_CLASS_TRADE_GOODS && it.itemSubclass === ITEM_SUBCLASS_HERB) return 12;
+  if (it.quality > 1) return 10;
+  if (it.quality === 0) return 14;
+  return 13;
+}
+
+// Tier, then the addon's own tie-breakers. Entry rather than name groups an item's ranks
+// (Minor → Lesser → Healing Potion) the way SortBags.lua:452-460 does.
+export function itemSortKey(
+  stack: ItemStack,
+  it: ItemDef | undefined,
+  look: SortLookup,
+): number[] {
+  return [
+    itemSortTier(stack, it, look),
+    it?.itemClass ?? 99,
+    it?.inventoryType ?? 0,
+    it?.itemSubclass ?? 0,
+    -(it?.quality ?? 0),
+    it?.entry ?? 0,
+    -(stack.charges ?? 0),
+    stack.randomPropertyId ?? 0,
+    stack.permEnchantId ?? 0,
+  ];
+}
+
+/** Element-wise compare; equal-length keys, so a shorter vector never appears. */
+export function compareSortKeys(a: readonly number[], b: readonly number[]): number {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const d = (a[i] ?? 0) - (b[i] ?? 0);
+    if (d !== 0) return d;
+  }
+  return 0;
+}
+
+export interface SortContainerResult {
+  inventory: Inventory;
+  /** Slots the restack handed back (used before − used after). Never negative. */
+  freed: number;
+  /** True when the stack order or count actually changed. */
+  changed: boolean;
+}
+
+// The addon's two halves (Stack() then Sort()) in one pass. addInstance merges only what
+// instancesStackable allows, so a suffix, an enchant or a bound flag keeps its own slot.
+export function sortInventory(inv: Inventory, ds: SortSource): SortContainerResult {
+  const look = sortLookupFor(ds);
+  let packed = emptyInventory();
+  for (const s of inv.stacks) {
+    packed = addInstance(packed, s, ds.item(s.item)?.stackable ?? 1);
+  }
+  const keyed = packed.stacks.map((s) => ({ s, k: itemSortKey(s, ds.item(s.item), look) }));
+  keyed.sort((a, b) => compareSortKeys(a.k, b.k));
+  const stacks = keyed.map((x) => x.s);
+  const freed = Math.max(0, inv.stacks.length - stacks.length);
+  const changed = freed > 0 || stacks.some((s, i) => {
+    const was = inv.stacks[i];
+    return !was || was.item !== s.item || was.count !== s.count;
+  });
+  return { inventory: { stacks }, freed, changed };
+}

package/src/domain/items/spareContainers.ts

@@ -0,0 +1,71 @@
+// Spare bags and quivers Multi sell may offer. The "Bags and containers" / "Quivers and ammo
+// pouches" boxes exist for the bag you are about to wear; a 6-slot pack sitting behind four 16s is
+// not that bag, it is 50 copper.
+//
+// "Not an upgrade" is findUpgrades' own answer (equipmentHelper.ts:185-190 scores a bag by bagSlots
+// and replaces the SMALLEST worn one), taken for the player AND every companion via
+// partyUpgradeEntries. That alone is not enough for a class-11 quiver: quiverPouchValue returns 0
+// for a wrong ranged family, so an unarmed hunter's only spare quiver reads "not an upgrade". Both
+// families therefore also have to be beaten by something the body is ALREADY WEARING.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { EquippedMap } from '../character/character.ts';
+import { isQuiverOrPouch } from './ammo.ts';
+import { BAG_SLOTS } from './equipment.ts';
+import { equippedEntry } from './itemInstance.ts';
+import type { Inventory } from './inventory.ts';
+
+/** item_template.class 1 CONTAINER / 11 QUIVER. Cite: ItemPrototype.h:144-159. */
+const ITEM_CLASS_CONTAINER = 1;
+const ITEM_CLASS_QUIVER = 11;
+
+type ContainerFamily = 'bag' | 'quiver';
+
+/** Which of the two never-sell boxes owns this row, or null when it is not a container at all. */
+export function containerFamily(it: ItemDef | undefined): ContainerFamily | null {
+  if (!it) return null;
+  if (isQuiverOrPouch(it) || it.itemClass === ITEM_CLASS_QUIVER) return 'quiver';
+  if (it.itemClass === ITEM_CLASS_CONTAINER || it.slot === 'bag') return 'bag';
+  return null;
+}
+
+/** Biggest worn container of each family. A body wearing nothing keeps every spare it carries. */
+function wornSlotsByFamily(equipped: EquippedMap, ds: DataStore): Map<ContainerFamily, number> {
+  const out = new Map<ContainerFamily, number>();
+  for (const slot of BAG_SLOTS) {
+    const entry = equippedEntry(equipped[slot]);
+    const it = entry != null ? ds.item(entry) : undefined;
+    const fam = containerFamily(it);
+    if (!fam || !it) continue;
+    out.set(fam, Math.max(out.get(fam) ?? 0, it.bagSlots ?? 0));
+  }
+  return out;
+}
+
+/**
+ * Bag entries that are a container nobody would wear: not an upgrade for the party, and no bigger
+ * than what this body already has on in the same family.
+ */
+export function spareContainerEntries(
+  inv: Inventory,
+  ds: DataStore,
+  equipped: EquippedMap,
+  upgradeEntries: ReadonlySet<number> | undefined,
+): Set<number> {
+  const worn = wornSlotsByFamily(equipped, ds);
+  const out = new Set<number>();
+  const seen = new Set<number>();
+  for (const stk of inv.stacks) {
+    if (seen.has(stk.item)) continue;
+    seen.add(stk.item);
+    if (upgradeEntries?.has(stk.item)) continue;
+    const it = ds.item(stk.item);
+    const fam = containerFamily(it);
+    if (!it || !fam) continue;
+    const wornSlots = worn.get(fam);
+    if (wornSlots == null || wornSlots < (it.bagSlots ?? 0)) continue;
+    out.add(it.entry);
+  }
+  return out;
+}

package/src/domain/items/spellReagentIndex.ts

@@ -0,0 +1,131 @@
+// What a spell reagent is FOR: the non-craft spells that spend it, the classes that cast those, and
+// the book that teaches one. Party-independent, so a shaman reagent reads as one with no shaman here.
+// Cite: spell_template.Reagent1..8; SkillLineAbility.classMask (Player.cpp:18369
+// IsSpellFitByClassAndRace); SpellEffects.cpp:2445 EffectLearnSpell.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef, SpellDef } from '../../data/schema.ts';
+import { itemTeachIntent } from './itemTeaches.ts';
+
+/** SPELL_EFFECT_CREATE_ITEM / ENCHANT_ITEM / ENCHANT_ITEM_TEMPORARY. Cite: SharedDefines.h:24/53/54. */
+const EFFECT_CREATE_ITEM = 24;
+const EFFECT_ENCHANT_ITEM = 53;
+const EFFECT_ENCHANT_ITEM_TEMPORARY = 54;
+
+/** Highest classic class id, so a classMask walk stops at Druid. Cite: SharedDefines.h CLASS_DRUID 11. */
+const MAX_CLASS_ID = 11;
+
+// A craft spends reagents to mint or enchant an item and buys vendor rows itself (258922bf5).
+// Enchanting is effect 53, not 24 — those dusts are trade goods, never a spell reagent.
+export function isCraftSpell(sp: SpellDef): boolean {
+  if (!(sp.reagents ?? []).some((r) => r.item > 0)) return false;
+  const raw = sp.rawEffects ?? [];
+  if (raw.length) {
+    return raw.some((e) =>
+      e.effect === EFFECT_CREATE_ITEM
+      || e.effect === EFFECT_ENCHANT_ITEM
+      || e.effect === EFFECT_ENCHANT_ITEM_TEMPORARY);
+  }
+  return (sp.effects ?? []).some((e) =>
+    e.kind === 'conjure' || e.kind === 'enchant_item_perm' || e.kind === 'enchant_held_item');
+}
+
+export interface ReagentSpender {
+  spell: number;
+  /** Classes this spell's SLA classMask lets cast it. Empty = no mask restricts it. */
+  classes: readonly number[];
+}
+
+export interface ReagentDemand {
+  /** Non-craft spells that list this item, lowest spell level first. */
+  spenders: readonly ReagentSpender[];
+  /** Union of the spenders' classes, so a wrong-class seat can be named and refused. */
+  classes: readonly number[];
+}
+
+const DEMAND = new WeakMap<DataStore, Map<number, ReagentDemand>>();
+const SPENDERS = new WeakMap<DataStore, ReadonlySet<number>>();
+
+function demandIndex(ds: DataStore): Map<number, ReagentDemand> {
+  const hit = DEMAND.get(ds);
+  if (hit) return hit;
+  const meta = ds.combatSkillMeta?.();
+  const spellsOf = new Map<number, SpellDef[]>();
+  for (const sp of ds.allSpells()) {
+    if (isCraftSpell(sp)) continue;
+    for (const r of sp.reagents ?? []) {
+      if (!(r.item > 0)) continue;
+      const arr = spellsOf.get(r.item);
+      if (arr) arr.push(sp);
+      else spellsOf.set(r.item, [sp]);
+    }
+  }
+  const classesOf = (spellId: number): number[] => {
+    let mask = 0;
+    for (const ab of meta?.spellAbilities?.[spellId] ?? []) mask |= ab.classMask | 0;
+    const out: number[] = [];
+    for (let cls = 1; cls <= MAX_CLASS_ID; cls++) if (mask & (1 << (cls - 1))) out.push(cls);
+    return out;
+  };
+  const out = new Map<number, ReagentDemand>();
+  for (const [item, sps] of spellsOf) {
+    sps.sort((a, b) => (a.spellLevel ?? 0) - (b.spellLevel ?? 0) || a.id - b.id);
+    const spenders = sps.map((sp) => ({ spell: sp.id, classes: classesOf(sp.id) }));
+    const classes = [...new Set(spenders.flatMap((sp) => sp.classes))].sort((a, b) => a - b);
+    // No classMask anywhere is a world spell, not a class reagent: Linen Cloth is spent by
+    // Defias Disguise (5169) and belongs in nobody's spellbook kit.
+    if (!classes.length) continue;
+    out.set(item, { spenders, classes });
+  }
+  DEMAND.set(ds, out);
+  return out;
+}
+
+/** Whether any non-craft spell spends this item. One map lookup — called per item per seat. */
+export function spendsAsReagent(ds: DataStore, entry: number): boolean {
+  return demandIndex(ds).has(entry);
+}
+
+/** Every item a non-craft spell spends. */
+export function reagentSpenders(ds: DataStore): ReadonlySet<number> {
+  let set = SPENDERS.get(ds);
+  if (!set) SPENDERS.set(ds, (set = new Set(demandIndex(ds).keys())));
+  return set;
+}
+
+/** What spends this item, or undefined when no class spell does. */
+export function reagentDemand(ds: DataStore, entry: number): ReagentDemand | undefined {
+  return demandIndex(ds).get(entry);
+}
+
+/** The lowest-rank spell of `cls` that spends this item — the one a blocked row should name. */
+export function reagentSpellFor(ds: DataStore, entry: number, cls: number): number | undefined {
+  const spenders = demandIndex(ds).get(entry)?.spenders ?? [];
+  return spenders.find((sp) => sp.classes.includes(cls))?.spell;
+}
+
+type BookIndex = { catalogSize: number; bySpell: Map<number, number> };
+const BOOKS = new WeakMap<DataStore, BookIndex>();
+
+// Keyed on the catalogue size, because attachItems merges the lazy chunk in after boot and a memo
+// built off the keep set alone would answer "no book" forever. Cite: playerbotEquipCache.ts:44.
+function bookIndex(ds: DataStore): Map<number, number> {
+  const catalogSize = ds.items().length;
+  const hit = BOOKS.get(ds);
+  if (hit && hit.catalogSize === catalogSize) return hit.bySpell;
+  const bySpell = new Map<number, number>();
+  for (const it of ds.items()) {
+    if (it.useSpell == null) continue;
+    const teach = itemTeachIntent(it, ds);
+    if (teach?.kind !== 'spell' || bySpell.has(teach.id)) continue;
+    bySpell.set(teach.id, it.entry);
+  }
+  BOOKS.set(ds, { catalogSize, bySpell });
+  return bySpell;
+}
+
+/** The book whose on-use teaches `spellId`, when the catalogue holds one. */
+export function spellTeachBook(ds: DataStore, spellId: number): ItemDef | undefined {
+  const entry = bookIndex(ds).get(spellId | 0);
+  return entry != null ? ds.item(entry) : undefined;
+}

package/src/domain/items/staleConsumables.ts

@@ -0,0 +1,66 @@
+// Food and drink the bags have OUTGROWN. Multi sell's "Food and drink" box exists so a fresh player
+// never vendors the stack the next pull needs — but at 60 that box also guards the Tough Jerky and
+// the Refreshing Spring Water nobody has eaten since Westfall.
+//
+// Rank comes off the RequiredLevel gate the ladder is built on (item_template.RequiredLevel, mirrored
+// into the bake as consumable.reqLevel). Measured over the 17,603-row catalog, the gates are
+// food 1/5/(10,12)/15/(20)/25/(26)/35/(40)/45/(53)/55 and drink 1/(4)/5/15/25/35/(40)/45/(54)/55, so
+// a decade bucket puts each real gate on its own rank and folds the strays onto the gate they sit
+// beside — no table to keep in step with a re-bake.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { Inventory } from './inventory.ts';
+
+/** How far below the best rank in the bags a stack has to fall before it is vendor stock. */
+export const FOOD_TIER_MARGIN = 1;
+
+/** Rank of a food/drink gate. Cite: item_template.RequiredLevel; the gate histogram above. */
+export function foodDrinkTier(reqLevel: number): number {
+  return Math.floor(Math.max(0, reqLevel | 0) / 10);
+}
+
+/** The gate this stack is actually held behind — the bake's own stamp first, then the item row. */
+export function foodDrinkReqLevel(it: ItemDef): number {
+  return Math.max(it.consumable?.reqLevel ?? 0, it.requiredLevel | 0);
+}
+
+// Only a REAL food/drink row ranks. Raw meat and fish carry item_template.FoodType with no
+// consumable block — that is pet food, and Feed Pet reads the same rows, so it never ranks here.
+// A stat food (useBuff) is kept whatever its gate: it is worn for the buff, not the bite.
+function rankedEffect(it: ItemDef | undefined): 'food' | 'drink' | null {
+  if (!it || it.useBuff != null) return null;
+  return it.consumable?.effect ?? null;
+}
+
+/**
+ * Bag entries at least `margin` ranks below the best rank of the SAME kind the bags already hold and
+ * the body can eat. Reading the bags, not the catalog, is the whole safety property: the only stack
+ * you carry is always the best one you carry, so it can never be the thing that gets sold.
+ */
+export function outdatedFoodDrinkEntries(
+  inv: Inventory,
+  ds: DataStore,
+  level: number,
+  margin: number = FOOD_TIER_MARGIN,
+): Set<number> {
+  const ranked = new Map<number, { effect: 'food' | 'drink'; tier: number }>();
+  const best = new Map<'food' | 'drink', number>();
+  for (const stk of inv.stacks) {
+    if (ranked.has(stk.item)) continue;
+    const it = ds.item(stk.item);
+    const effect = rankedEffect(it);
+    if (!it || !effect) continue;
+    const req = foodDrinkReqLevel(it);
+    // Held for later, not outgrown: a gate above the body's level never sets or loses the bar.
+    if (req > level) continue;
+    const tier = foodDrinkTier(req);
+    ranked.set(it.entry, { effect, tier });
+    best.set(effect, Math.max(best.get(effect) ?? 0, tier));
+  }
+  const out = new Set<number>();
+  for (const [entry, { effect, tier }] of ranked) {
+    if ((best.get(effect) ?? 0) - tier >= margin) out.add(entry);
+  }
+  return out;
+}

package/src/domain/items/weaponSpender.ts

@@ -0,0 +1,110 @@
+// The weapon-damage ability a rotation holds down, and the DPS a weapon reaches through it: the
+// scale prices listed DPS, the engine rolls the weapon at its real speed (weapon.ts:770). Pure.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef, SpellDef } from '../../data/schema.ts';
+import type { SpellBook } from '../character/spellbook.ts';
+import { SHAPESHIFT_FORM } from '../../data/schema/constants.ts';
+import { TUNING, calculateMinMaxDamage } from '../../engine/combat/formulas.ts';
+
+/** A resource spender that lands as a weapon hit (Sinister Strike, Cleave, Mortal Strike). */
+export interface WeaponSpender {
+  spellId: number;
+  /** SpellDef.cost — energy per cast. */
+  cost: number;
+  /** weapon_percent_damage pct; 100 for a plain weapon hit (SS r8 = roll + strikeBonus 68). */
+  pct: number;
+  /** SpellDef.rank, the tie-break when several ranks are known. */
+  rank: number;
+}
+
+// A spell whose damage IS the weapon roll: strikeBonus is the DBC basePoints on
+// SPELL_EFFECT_WEAPON_DAMAGE* and weapon_percent_damage multiplies that roll (weapon.ts:775-779).
+function weaponHitPct(sp: SpellDef): number | null {
+  const pctEff = (sp.effects ?? []).find((e) => e.kind === 'weapon_percent_damage');
+  if (pctEff) {
+    const pct = (pctEff as { pct?: number }).pct ?? 0;
+    return pct > 0 ? pct : null;
+  }
+  return sp.strikeBonus != null ? 100 : null;
+}
+
+// Held-down means castable from the front, out of stealth, off cooldown: the schema gates that rule
+// out Backstab and Ambush (requiresBehind / requiresStealth) and Riposte (cooldownMs).
+function isSpammable(sp: SpellDef): boolean {
+  if (sp.requiresBehind || sp.requiresStealth) return false;
+  return (sp.cooldownMs || 0) === 0;
+}
+
+// SpellEntry.Stances bit for the forms that replace weapon damage with a level×speed band
+// (forms.ts:79 isAttackSpeedOverriddenShapeShift): cat, bear, dire bear.
+const FORM_OVERRIDES_WEAPON_MASK =
+  (1 << (SHAPESHIFT_FORM.CAT - 1))
+  | (1 << (SHAPESHIFT_FORM.BEAR - 1))
+  | (1 << (SHAPESHIFT_FORM.DIREBEAR - 1));
+
+// A spender castable ONLY inside such a form (a druid's Claw) rolls that band and never this
+// weapon, so its weapon keeps the listed-DPS ranking.
+function rollsTheEquippedWeapon(sp: SpellDef): boolean {
+  const stances = sp.stances ?? 0;
+  if (stances === 0) return true;
+  return (stances & ~FORM_OVERRIDES_WEAPON_MASK) !== 0;
+}
+
+const SPENDER_MEMO = new WeakMap<SpellBook, WeaponSpender | null>();
+
+// The spender to price a weapon against. Energy only: TUNING.energyPerSec is a constant regen
+// (Player.cpp POWER_ENERGY), while rage income has no sustainable rate to read here.
+export function resolveWeaponSpender(
+  spellbook: SpellBook | undefined | null,
+  ds: Pick<DataStore, 'spell'>,
+): WeaponSpender | null {
+  if (!spellbook) return null;
+  const hit = SPENDER_MEMO.get(spellbook);
+  if (hit !== undefined) return hit;
+  let best: WeaponSpender | null = null;
+  for (const id of spellbook.known) {
+    let sp: SpellDef | undefined;
+    try {
+      sp = ds.spell(id);
+    } catch {
+      continue;
+    }
+    if (!sp || sp.powerType !== 'energy' || !(sp.cost > 0)) continue;
+    if (!isSpammable(sp) || !rollsTheEquippedWeapon(sp)) continue;
+    const pct = weaponHitPct(sp);
+    if (pct == null) continue;
+    const cand: WeaponSpender = { spellId: sp.id, cost: sp.cost, pct, rank: sp.rank ?? 0 };
+    if (!best || pct > best.pct || (pct === best.pct && cand.rank > best.rank)) best = cand;
+  }
+  SPENDER_MEMO.set(spellbook, best);
+  return best;
+}
+
+/** Listed weapon DPS — what the weightscale prices today (playerbotStatWeight mledps). */
+export function listedWeaponDps(it: ItemDef): number {
+  const w = it.weapon;
+  if (!w) return 0;
+  const speedSec = (w.delayMs || 2000) / 1000;
+  return (w.dmgMin + w.dmgMax) / 2 / speedSec;
+}
+
+// DPS the spender adds, in the unit the scale prices: the engine's own ability roll at the weapon's
+// real speed, at the rate the resource allows. The flat strikeBonus is weapon-independent, so it is out.
+export function spenderWeaponDps(
+  it: ItemDef,
+  attackPower: number,
+  spender: WeaponSpender | null | undefined,
+): number {
+  const w = it.weapon;
+  if (!w || !spender || !(spender.cost > 0)) return 0;
+  const castsPerSec = TUNING.energyPerSec / spender.cost;
+  const range = calculateMinMaxDamage({
+    weaponMin: w.dmgMin,
+    weaponMax: w.dmgMax,
+    attackPower,
+    speedMs: w.delayMs || 2000,
+  });
+  const perCast = ((range.min + range.max) / 2) * (spender.pct / 100);
+  return castsPerSec * perCast;
+}