azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/bots/paladinPrePull.ts

@@ -0,0 +1,231 @@
+// PURE: turn a party roster into the Blessing and Aura chips each body carries into a pull.
+// The decision lives in rotation/paladinBuffs.ts (ported from PlayerbotPaladinAI); this file is
+// only the seating — who is in whose subgroup, and which pet rides which owner.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ActiveAura } from '../character/character.ts';
+import { CLASS } from '../../data/schema/constants.ts';
+import type { Rotation } from '../rotation/rotation.ts';
+import type { RotationRule } from '../rotation/types.ts';
+import {
+  blessingFamilyOf,
+  paladinAuraOf,
+  type PaladinAssignments,
+  planPaladinAuras,
+  planPaladinBlessings,
+  type BlessingTarget,
+  type PaladinAura,
+  type PaladinProvider,
+  type PlannedBlessing,
+  type PlannedReagent,
+} from '../rotation/paladinBuffs.ts';
+
+/** One seated body: the player or a companion, with its pet. */
+export interface PaladinPartyMember {
+  /** 'player' or the companion id — the caster identity for per-caster stacking. */
+  key: string;
+  name: string;
+  cls: number;
+  level: number;
+  known: readonly number[];
+  role?: 'tank' | 'healer' | 'dps';
+  /** Playerbot spec name, when resolved. Decides a paladin's own aura (CheckAuras). */
+  spec?: string | null;
+  /** Talent id → spent rank. Auto sort gives an improved Blessing to the paladin that took it. */
+  talents?: Readonly<Record<number, number>>;
+  /** Raid subgroup index. Auras radiate to the holder's subgroup only. */
+  subgroup?: number;
+  pet?: { key: string; usesMana: boolean };
+  /** How many of `item` this body carries — the Greater Blessing reagent. Absent ⇒ unlimited. */
+  reagentCount?: (item: number) => number;
+}
+
+export interface PaladinPartyBuffs {
+  /** Body key → the aura chips that body carries. Empty when the party has no paladin. */
+  byKey: Map<string, ActiveAura[]>;
+  blessings: PlannedBlessing[];
+  auras: { from: string; spellId: number; aura: PaladinAura }[];
+  /** Symbols of Kings the Greater Blessings in this plan cost, per paladin. */
+  reagents: PlannedReagent[];
+}
+
+const EMPTY: PaladinPartyBuffs = { byKey: new Map(), blessings: [], auras: [], reagents: [] };
+
+/** The roster split into who can bless and what gets blessed. The plan and the board's Auto sort
+ *  read the same one, so they cannot disagree about levels, spellbooks, talents or reagents. */
+export function paladinPartySeating(members: readonly PaladinPartyMember[]): {
+  providers: PaladinProvider[];
+  targets: BlessingTarget[];
+} {
+  const providers: PaladinProvider[] = members
+    .filter((m) => m.cls === CLASS.PALADIN)
+    .map((m) => ({
+      key: m.key,
+      name: m.name,
+      level: m.level,
+      known: m.known,
+      ...(m.spec != null ? { spec: m.spec } : {}),
+      ...(m.role ? { role: m.role } : {}),
+      ...(m.talents ? { talents: m.talents } : {}),
+      ...(m.reagentCount ? { reagentCount: m.reagentCount } : {}),
+    }));
+  const targets: BlessingTarget[] = [];
+  for (const m of members) {
+    targets.push({ key: m.key, cls: m.cls, ...(m.role ? { role: m.role } : {}) });
+    if (m.pet) targets.push({ key: m.pet.key, cls: 0, isPet: true, usesMana: m.pet.usesMana });
+  }
+  return { providers, targets };
+}
+
+/**
+ * Every Blessing and Aura the party's paladins hand out, as ready-to-carry aura chips.
+ *
+ * Blessings reach anyone (single-target, and a Greater fans by class raid-wide), so subgroup does
+ * not gate them. An Aura is SPELL_EFFECT_APPLY_AREA_AURA_PARTY and reaches the holder's subgroup
+ * only. Cite: applySpell.ts:1824; healTargets.ts:100 TARGET_UNIT_RAID_AND_CLASS.
+ */
+export function planPartyPaladinBuffs(
+  members: readonly PaladinPartyMember[],
+  ds: DataStore,
+  now: number,
+  /** The operator's PallyPower board. An absent cell is auto. */
+  assignments?: PaladinAssignments,
+): PaladinPartyBuffs {
+  const { providers, targets } = paladinPartySeating(members);
+  if (!providers.length) return EMPTY;
+
+  const board = assignments ? { assignments } : {};
+  const { blessings, reagents } = planPaladinBlessings(providers, targets, ds, board);
+  const auras = planPaladinAuras(providers, ds, {
+    tankInGroup: members.some((m) => m.role === 'tank'),
+    ...board,
+  });
+
+  const byKey = new Map<string, ActiveAura[]>();
+  // A body's OWN cast carries no caster key: that is what every other self keep-up on the sheet
+  // records, and stamping one here would let a paladin hold two of its own Blessings.
+  const push = (key: string, from: string, row: Omit<ActiveAura, 'fromCaster'>): void => {
+    const full: ActiveAura = from === key ? { ...row } : { ...row, fromCaster: from };
+    const list = byKey.get(key);
+    if (list) list.push(full);
+    else byKey.set(key, [full]);
+  };
+  for (const b of blessings) {
+    push(b.on, b.from, {
+      spellId: b.spellId,
+      ...(b.durationMs > 0 ? { expiresAt: now + b.durationMs } : {}),
+    });
+  }
+  const subgroupOf = new Map(members.map((m) => [m.key, m.subgroup ?? 0]));
+  for (const a of auras) {
+    const holderGroup = subgroupOf.get(a.from) ?? 0;
+    for (const m of members) {
+      if ((m.subgroup ?? 0) !== holderGroup) continue;
+      push(m.key, a.from, { spellId: a.spellId });
+      if (m.pet) push(m.pet.key, a.from, { spellId: a.spellId });
+    }
+  }
+  return { byKey, blessings, auras, reagents };
+}
+
+/**
+ * Merge planned chips into a body's carried list: a chip from the SAME paladin in the same
+ * exclusive group replaces its own, a chip from a different one is added beside it.
+ */
+export function mergePaladinChips(
+  carried: readonly ActiveAura[] | undefined,
+  add: readonly ActiveAura[] | undefined,
+  ds: DataStore,
+): ActiveAura[] {
+  if (!add?.length) return carried ? [...carried] : [];
+  const groupOf = (id: number): number | null => {
+    const sp = ds.spell(id);
+    const g = sp?.exclusionGroup ?? sp?.spellGroupId ?? 0;
+    return g > 0 ? g : null;
+  };
+  const out = (carried ?? []).filter((a) => {
+    const g = groupOf(a.spellId);
+    if (g == null) return true;
+    return !add.some((n) => groupOf(n.spellId) === g && (n.fromCaster ?? null) === (a.fromCaster ?? null));
+  });
+  return [...out, ...add.map((a) => ({ ...a }))];
+}
+
+/**
+ * Author one paladin's buffs phase from the PARTY plan: its assigned aura, a self rule for the
+ * family it keeps on itself, and one `{ allyMissingAura }` rule per (family, board COLUMN).
+ *
+ * The board WINS over a hand-edited list (operator ruling): only blessing and aura rows are
+ * rewritten. A class-BLIND ally rule was the spam — the Might row took the mage the board had put
+ * on Wisdom, and the two traded that body every GCD (group 7 is unique-per-caster).
+ */
+export function restampPaladinRotation(
+  rot: Rotation,
+  plan: PaladinPartyBuffs,
+  providerKey: string,
+  ds: DataStore,
+): Rotation {
+  const aura = plan.auras.find((a) => a.from === providerKey);
+  const mine = plan.blessings.filter((b) => b.from === providerKey);
+  if (!aura && !mine.length) return rot;
+
+  // One entry per family: the spell, whether it lands on this paladin, and the board columns it
+  // is handed to. A column is a target class id, or 'pet'.
+  const fams = new Map<string, { spellId: number; onSelf: boolean; cols: Set<string> }>();
+  for (const b of mine) {
+    const cur = fams.get(b.family) ?? { spellId: b.spellId, onSelf: false, cols: new Set<string>() };
+    cur.spellId = b.spellId;
+    if (b.on === providerKey) cur.onSelf = true;
+    else cur.cols.add(b.col);
+    fams.set(b.family, cur);
+  }
+
+  const selfRule = (id: string, spellId: number): RotationRule => ({
+    id,
+    action: { kind: 'spell', spellId },
+    conditions: [{ subject: 'self', metric: 'buffPresent', op: '==', value: 0, ref: spellId }],
+    enabled: true,
+  });
+  // No condition: the row is unusable while nobody in `among` is missing it, and it aims at the
+  // body that gate read. A pet has no player class, so the 'pet' column is `classId: 0`.
+  const allyRule = (id: string, spellId: number, col: string): RotationRule => ({
+    id,
+    action: {
+      kind: 'spell',
+      spellId,
+      target: { allyMissingAura: spellId, among: { classId: col === 'pet' ? 0 : Number(col) | 0 } },
+    },
+    conditions: [],
+    enabled: true,
+  });
+
+  // Every blessing and aura row goes; what the plan says replaces it. Anything else the band
+  // authored (Righteous Fury, a seal, a scroll) is kept exactly where it was.
+  const kept = rot.phases.buffs.filter((r) => {
+    if (r.action.kind !== 'spell') return true;
+    const sp = ds.spell(r.action.spellId);
+    return blessingFamilyOf(sp) == null && paladinAuraOf(sp) == null;
+  });
+  const authored: RotationRule[] = [];
+  if (aura) authored.push(selfRule('pally-aura', aura.spellId));
+  for (const [family, e] of fams) {
+    if (e.onSelf) authored.push(selfRule(`pally-${family}`, e.spellId));
+    for (const col of [...e.cols].sort()) {
+      authored.push(allyRule(`pally-ally-${family}-${col}`, e.spellId, col));
+    }
+  }
+  const buffs = [...kept, ...authored];
+  const same = buffs.length === rot.phases.buffs.length
+    && buffs.every((r, i) => {
+      const was = rot.phases.buffs[i];
+      if (!was || was.action.kind !== 'spell' || r.action.kind !== 'spell') return was === r;
+      const wt = was.action.target;
+      const rt = r.action.target;
+      const aimOf = (t: typeof wt): string => (t && typeof t === 'object' && 'allyMissingAura' in t
+        ? `${t.allyMissingAura}|${t.among?.classId ?? ''}` : '');
+      return was.action.spellId === r.action.spellId
+        && aimOf(wt) === aimOf(rt)
+        && (was.conditions[0]?.ref ?? null) === (r.conditions[0]?.ref ?? null);
+    });
+  return same ? rot : { ...rot, phases: { ...rot.phases, buffs } };
+}

package/src/domain/bots/partyRole.ts

@@ -0,0 +1,40 @@
+// One party role model for every unit in the group, the player included — before this the human
+// had no `groupRole`, so every role-gated party behaviour silently skipped them.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Character } from '../character/character.ts';
+import { roleSpecOverride } from './companionRotation.ts';
+import { primarySpec } from '../rotation/spec.ts';
+
+/** Engine-side role name. `SquadRole`'s 'dps' is spelled 'damage' on a Fighter spec. */
+export type PartyRole = 'tank' | 'healer' | 'damage';
+
+const FORM_BEAR = 5;
+const FORM_DIREBEAR = 8;
+
+// The role this character plays in a party. `explicit` is the user's own pick (`state.squadRole`) and
+// always wins; otherwise it comes off their talents.
+export function partyRoleOf(
+  char: Character,
+  ds: DataStore,
+  explicit?: 'tank' | 'healer' | 'dps',
+): PartyRole {
+  if (explicit === 'tank' || explicit === 'healer') return explicit;
+  if (explicit === 'dps') return 'damage';
+  // A druid in bear is tanking by definition, whatever the tree says (Feral is one tree for
+  // both cat and bear, so the spec name cannot answer this).
+  const form = char.form ?? 0;
+  if (char.cls === 11 && (form === FORM_BEAR || form === FORM_DIREBEAR)) return 'tank';
+  let spec: string;
+  try {
+    spec = primarySpec(char, ds);
+  } catch {
+    return 'damage'; // sparse fixture datastore with no talent trees
+  }
+  if (spec && spec === roleSpecOverride(char.cls, 'tank')) return 'tank';
+  if (spec && spec === roleSpecOverride(char.cls, 'healer')) return 'healer';
+  // Discipline priest heals too; the companion band table only names Holy because that is the
+  // build a hired healer is stamped with, not because Disc is a damage spec.
+  if (char.cls === 5 && spec === 'Discipline') return 'healer';
+  return 'damage';
+}

package/src/domain/bots/playerbotEquipCache.ts

@@ -0,0 +1,412 @@
+// Offline port of the playerbots RandomItemMgr equip cache and the InitEquipment candidate walk.
+// The membership rules are rebuilt in-process, then ranked by GetStatWeight + Quality×ItemLevel.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { EquipSlot, ItemDef } from '../../data/schema.ts';
+import { CLASS } from '../../data/schema.ts';
+import { playerbotFactoryItemEligible } from './playerbotItemEligibility.ts';
+import { canEquipRelic } from '../items/relic.ts';
+import {
+  calculateStatWeight,
+  playerbotEquipScore,
+  playerbotWeightScale,
+} from './playerbotStatWeight.ts';
+
+// BuildEquipCache: abs(minLevel − botLevel) ≤ 20 keeps the item in the cache list. Cite: RandomItemMgr.cpp
+// BuildEquipCache ~3460.
+export const EQUIP_CACHE_LEVEL_WINDOW = 20;
+
+// AiPlayerbot.RandomGearMaxDiff (conf default 9): when equipping, reject items whose required level is more
+// than this many levels below the bot. Cite: PlayerbotFactory InitEquipment ~3368.
+export const EQUIP_GEAR_MAX_DIFF = 9;
+
+// ---- min level / quality index ---------------------------------------------
+
+/** Required level used by the factory (proto RequiredLevel or min-level cache). */
+export function itemMinLevel(it: ItemDef): number {
+  if (it.requiredLevel > 0) return it.requiredLevel;
+  return it.itemLevel ?? 0;
+}
+
+type CatalogIndex = {
+  catalogSize: number;
+  /** Eligible factory items grouped by quality. */
+  byQuality: Map<number, ItemDef[]>;
+  /** Items of one quality that fit one paperdoll slot, filled on first ask. */
+  slotPools: Map<string, ItemDef[]>;
+  /** BuildEquipCache result per level|cls|spec|slot|quality — dropped with the catalog it read. */
+  queries: Map<string, readonly ItemDef[]>;
+};
+
+const CATALOG = new WeakMap<DataStore, CatalogIndex>();
+
+function catalog(ds: DataStore): CatalogIndex {
+  const catalogSize = ds.items().length;
+  const cached = CATALOG.get(ds);
+  if (cached && cached.catalogSize === catalogSize) return cached;
+  const byQuality = new Map<number, ItemDef[]>();
+  for (const it of ds.items()) {
+    if (!playerbotFactoryItemEligible(it)) continue;
+    if (it.notObtainable) continue;
+    // BuildEquipCache only stores weapon/armor/container/projectile — we skip bags.
+    if (it.slot === 'bag' || it.slot === 'shirt') continue;
+    const q = it.quality ?? 0;
+    let arr = byQuality.get(q);
+    if (!arr) byQuality.set(q, (arr = []));
+    arr.push(it);
+  }
+  const idx: CatalogIndex = { catalogSize, byQuality, slotPools: new Map(), queries: new Map() };
+  CATALOG.set(ds, idx);
+  return idx;
+}
+
+// viableSlots is a property of the item alone, so bucket by it once instead of re-testing every
+// item of a quality on every query. Cite: RandomItemMgr ctor, which builds viableSlots up front.
+function slotPool(idx: CatalogIndex, quality: number, slot: EquipSlot): ItemDef[] {
+  const key = `${quality}|${slot}`;
+  let pool = idx.slotPools.get(key);
+  if (!pool) {
+    pool = (idx.byQuality.get(quality) ?? []).filter((it) => itemFitsEquipSlot(slot, it));
+    idx.slotPools.set(key, pool);
+  }
+  return pool;
+}
+
+// ---- viableSlots / CanEquipItem slot membership ----------------------------
+
+/** True when `it` may fill this paperdoll slot (viableSlots map). Cite: RandomItemMgr ctor viableSlots. */
+export function itemFitsEquipSlot(slot: EquipSlot, it: ItemDef): boolean {
+  const s = it.slot;
+  if (!s || s === 'bag') return false;
+  switch (slot) {
+    case 'head': return s === 'head';
+    case 'neck': return s === 'neck';
+    case 'shoulder': return s === 'shoulder';
+    case 'back': return s === 'back';
+    case 'chest': return s === 'chest';
+    case 'shirt': return s === 'shirt';
+    case 'wrist': return s === 'wrist';
+    case 'hands': return s === 'hands';
+    case 'waist': return s === 'waist';
+    case 'legs': return s === 'legs';
+    case 'feet': return s === 'feet';
+    case 'finger1':
+    case 'finger2':
+      return s === 'finger';
+    case 'trinket1':
+    case 'trinket2':
+      return s === 'trinket';
+    case 'mainhand':
+      // INVTYPE_WEAPON | 2HWEAPON | WEAPONMAINHAND
+      return s === 'mainhand' || s === 'twohand';
+    case 'offhand':
+      // Classic off-hand: SHIELD | WEAPONOFFHAND | HOLDABLE | INVTYPE_WEAPON via canOffhand.
+      // NOT WEAPONMAINHAND-only and NOT 2H — Titan's Grip is WotLK.
+      if (s === 'offhand') return true;
+      // INVTYPE_WEAPON (13) only — mainhand-only 1H must never land in OH (two "main hands").
+      if (s === 'mainhand') return it.canOffhand === true;
+      return false;
+    case 'ranged':
+      return s === 'ranged';
+    default:
+      return false;
+  }
+}
+
+export const BODY_ARMOR_SLOTS = new Set<EquipSlot>([
+  'head', 'shoulder', 'chest', 'waist', 'legs', 'feet', 'wrist', 'hands',
+]);
+
+// CanEquipArmor — the classic progressive armor tier by class, spec and level. Cloth casters are
+// NOT hard-filtered here, because the weightscales already zero the wrong armor.
+export function canEquipArmor(
+  cls: number,
+  specId: number,
+  level: number,
+  it: ItemDef,
+): boolean {
+  if (it.slot === 'back') return true;
+  const sub = it.armorSubclass;
+
+  // Shield always ok for Warr/Pally/Shaman (before tier checks)
+  if (sub === 6 || it.typeName === 'Shield') {
+    return cls === CLASS.WARRIOR || cls === CLASS.PALADIN || cls === CLASS.SHAMAN;
+  }
+
+  // Holy paladin = weightscale id 4 — exempt from plate force
+  const isHolyPally = cls === CLASS.PALADIN && specId === 4;
+  // C++: (shaman && spec != 21) for mail@40 — enhance 21 skips mail force
+  const isEnhanceShaman = cls === CLASS.SHAMAN && specId === 21;
+  // C++: druid && !(spec == 29 || 31) → leather force (resto 29 / balance 31 exempt)
+  const isCasterDruid = cls === CLASS.DRUID && (specId === 29 || specId === 31);
+
+  if ((cls === CLASS.WARRIOR || (cls === CLASS.PALADIN && !isHolyPally)) && level >= 40) {
+    if (sub != null && sub !== 4) return false; // plate
+  }
+
+  if (
+    ((cls === CLASS.WARRIOR || (cls === CLASS.PALADIN && !isHolyPally)) && level < 40)
+    || ((cls === CLASS.HUNTER || (cls === CLASS.SHAMAN && !isEnhanceShaman)) && level >= 40)
+  ) {
+    if (sub != null && sub !== 3) return false; // mail
+  }
+
+  if (
+    ((cls === CLASS.HUNTER || cls === CLASS.SHAMAN) && level < 40)
+    || ((cls === CLASS.DRUID && !isCasterDruid) || cls === CLASS.ROGUE)
+  ) {
+    if (sub != null && sub !== 2) return false; // leather
+  }
+
+  // Quality ≤ normal early-out in C++ is always true after the above; keep same.
+  return true;
+}
+
+/** Weight memo: specId|entry|hasSpellResolver → GetStatWeight (0 if unusable). */
+const WEIGHT_MEMO = new Map<string, number>();
+
+// `ds` is what lets CalculateStatWeight price an on-use or proc payload; a call without one scores
+// baked stats alone, so it memoises under its own key rather than answering for both.
+function statWeight(cls: number, specId: number, it: ItemDef, ds?: DataStore): number {
+  const key = `${cls}|${specId}|${it.entry}|${ds ? 1 : 0}`;
+  const hit = WEIGHT_MEMO.get(key);
+  if (hit !== undefined) return hit;
+  const w = calculateStatWeight(cls, specId, it, ds ? { spell: (id) => ds.spell(id) } : undefined);
+  WEIGHT_MEMO.set(key, w);
+  // Bound memo growth in long test runs
+  if (WEIGHT_MEMO.size > 200_000) WEIGHT_MEMO.clear();
+  return w;
+}
+
+// BuildEquipCache membership for one (level, class, spec, slot, quality) key, memoised on it like
+// the C++ cache. Unsorted — caller ranks. Cite: RandomItemMgr::BuildEquipCache inner loop.
+export function queryEquipCache(
+  ds: DataStore,
+  level: number,
+  cls: number,
+  specId: number,
+  slot: EquipSlot,
+  quality: number,
+): readonly ItemDef[] {
+  const scale = playerbotWeightScale(specId);
+  if (!scale || scale.classId !== cls) return [];
+
+  const idx = catalog(ds);
+  const key = `${level}|${cls}|${specId}|${slot}|${quality}`;
+  const hit = idx.queries.get(key);
+  if (hit) return hit;
+
+  const out: ItemDef[] = [];
+  for (const it of slotPool(idx, quality, slot)) {
+    const w = statWeight(cls, specId, it, ds);
+    if (w <= 0) continue;
+    // only accept "useless" weight==1 if bot level ≤ 30
+    if (w === 1 && level > 30) continue;
+
+    const minLvl = itemMinLevel(it);
+    if (minLvl > level) continue;
+    if (Math.abs(minLvl - level) > EQUIP_CACHE_LEVEL_WINDOW) continue;
+
+    if (BODY_ARMOR_SLOTS.has(slot) && !canEquipArmor(cls, specId, level, it)) continue;
+    if (!canEquipRelic({ cls }, it).ok) continue;
+
+    // Rogue OH must be a weapon
+    if (slot === 'offhand' && cls === CLASS.ROGUE && !it.weapon) continue;
+
+    out.push(it);
+  }
+  if (idx.queries.size > 50_000) idx.queries.clear();
+  idx.queries.set(key, out);
+  return out;
+}
+
+// InitEquipment sort for non-progressive gear: best GetStatWeight first, then Quality×ItemLevel,
+// returned descending as a new array. Cite: PlayerbotFactory.cpp sort + reverse.
+export function rankEquipCandidates(
+  cls: number,
+  specId: number,
+  items: ItemDef[],
+  ds?: DataStore,
+): ItemDef[] {
+  return [...items].sort((a, b) => {
+    const wa = statWeight(cls, specId, a, ds);
+    const wb = statWeight(cls, specId, b, ds);
+    if (wa !== wb) return wb - wa;
+    const ta = (a.quality ?? 0) * (a.itemLevel ?? 0);
+    const tb = (b.quality ?? 0) * (b.itemLevel ?? 0);
+    if (ta !== tb) return tb - ta;
+    return a.entry - b.entry;
+  });
+}
+
+// Live InitEquipment gates applied while walking the ranked list (after Query). Does not re-check cache
+// membership. Cite: PlayerbotFactory::InitEquipment filters after Query (~3330–3450).
+export function initEquipmentLiveOk(
+  it: ItemDef,
+  slot: EquipSlot,
+  cls: number,
+  specId: number,
+  botLevel: number,
+  worn: ReadonlySet<number>,
+  ds?: DataStore,
+): boolean {
+  if (worn.has(it.entry)) return false;
+
+  // randomGearMaxDiff
+  const req = itemMinLevel(it);
+  if (req > 0 && (it.quality ?? 0) < 5) {
+    if (Math.abs(botLevel - req) > EQUIP_GEAR_MAX_DIFF) return false;
+  }
+
+  // Tank OH = shield only (prot warrior 3, prot paladin 5)
+  if (slot === 'offhand' && (specId === 3 || specId === 5)) {
+    if (!(it.armorSubclass === 6 || it.typeName === 'Shield')) return false;
+  }
+  // Tank MH = weapon, not shield/holdable
+  if (slot === 'mainhand' && (specId === 3 || specId === 5)) {
+    if (it.armorSubclass === 6 || it.typeName === 'Shield') return false;
+    if (!it.weapon && it.slot !== 'mainhand' && it.slot !== 'twohand') return false;
+    if (it.slot === 'offhand' && !it.weapon) return false; // holdable
+  }
+  if (slot === 'mainhand' && it.slot === 'offhand' && !it.weapon) return false; // holdable MH
+
+  // Fury (spec 2): slow MH ≥ 2.0s
+  if (slot === 'mainhand' && specId === 2 && it.weapon) {
+    if ((it.weapon.delayMs || 0) < 2000) return false;
+  }
+
+  // Classic enhance (21) / retri (6) at 60+: 2H ≥ 3.0s
+  if (
+    slot === 'mainhand'
+    && (specId === 6 || specId === 21)
+    && botLevel >= 60
+    && it.slot === 'twohand'
+    && it.weapon
+    && (it.weapon.delayMs || 0) < 3000
+  ) {
+    return false;
+  }
+
+  // Positive live weight
+  if (statWeight(cls, specId, it, ds) <= 0) return false;
+
+  return true;
+}
+
+// Query and rank for one slot and quality at bot level, then apply the live maxDiff filter,
+// best first. Also merges the extra MH sources InitEquipment uses for tanks and casters.
+export function rankedSlotCandidates(
+  ds: DataStore,
+  botLevel: number,
+  cls: number,
+  specId: number,
+  slot: EquipSlot,
+  quality: number,
+  worn: ReadonlySet<number>,
+  opts?: { searchLevel?: number; accept?: (it: ItemDef) => boolean },
+): ItemDef[] {
+  const searchLevel = opts?.searchLevel ?? botLevel;
+  const seen = new Set<number>();
+  const raw: ItemDef[] = [];
+
+  const pushAll = (list: readonly ItemDef[]) => {
+    for (const it of list) {
+      if (seen.has(it.entry)) continue;
+      seen.add(it.entry);
+      raw.push(it);
+    }
+  };
+
+  pushAll(queryEquipCache(ds, searchLevel, cls, specId, slot, quality));
+
+  // InitEquipment: tank MH also pulls OH-query one-handers
+  if (slot === 'mainhand' && (specId === 3 || specId === 5)) {
+    pushAll(queryEquipCache(ds, searchLevel, cls, specId, 'offhand', quality));
+  }
+  // Dual wield: rogue or fury (spec 2) MH also pulls OH weapons
+  if (slot === 'mainhand' && (cls === CLASS.ROGUE || specId === 2)) {
+    pushAll(queryEquipCache(ds, searchLevel, cls, specId, 'offhand', quality));
+  }
+  // Casters: holy pally (4), druids, priest, mage, warlock — MH pulls OH (holdables)
+  if (
+    slot === 'mainhand'
+    && (
+      specId === 4
+      || cls === CLASS.DRUID
+      || cls === CLASS.PRIEST
+      || cls === CLASS.MAGE
+      || cls === CLASS.WARLOCK
+      || specId === 20
+      || specId === 22
+    )
+  ) {
+    pushAll(queryEquipCache(ds, searchLevel, cls, specId, 'offhand', quality));
+  }
+
+  const ranked = rankEquipCandidates(cls, specId, raw, ds);
+  const live = ranked.filter(
+    (it) => initEquipmentLiveOk(it, slot, cls, specId, botLevel, worn, ds),
+  );
+  // `accept` narrows WITHOUT changing the ranking, and is STRICT on purpose: a per-call fallback
+  // would answer at the first searchLevel and never look further for an in-band item.
+  return opts?.accept ? live.filter(opts.accept) : live;
+}
+
+// Top-weight item for one slot (best first that passes live gates), walking quality try-order and
+// searchLevel downward like InitEquipment. Returns undefined when the cache has nothing equippable.
+export function topWeightForSlot(
+  ds: DataStore,
+  botLevel: number,
+  cls: number,
+  specId: number,
+  slot: EquipSlot,
+  qualityTryOrder: readonly number[],
+  worn: ReadonlySet<number>,
+  opts?: { accept?: (it: ItemDef) => boolean },
+): ItemDef | undefined {
+  for (const quality of qualityTryOrder) {
+    let searchLevel = botLevel;
+    while (searchLevel > 0) {
+      const cands = rankedSlotCandidates(ds, botLevel, cls, specId, slot, quality, worn, {
+        searchLevel,
+        ...(opts?.accept ? { accept: opts.accept } : {}),
+      });
+      if (cands.length > 0) return cands[0];
+      // Lower search level when cache empty at this quality (InitEquipment currSearchLevel--)
+      searchLevel--;
+      // Don't walk forever — cache window is 20; going more than botLevel is enough
+      if (botLevel - searchLevel > EQUIP_CACHE_LEVEL_WINDOW + 5) break;
+    }
+  }
+  return undefined;
+}
+
+/** Debug / audit: best-in-slot map for a class/spec/level (paperdoll keys → item). */
+export function dumpTopWeightLoadout(
+  ds: DataStore,
+  botLevel: number,
+  cls: number,
+  specId: number,
+  qualityBand: { min: number; max: number },
+  slots: readonly EquipSlot[],
+): Partial<Record<EquipSlot, ItemDef>> {
+  const worn = new Set<number>();
+  const out: Partial<Record<EquipSlot, ItemDef>> = {};
+  const tryOrder: number[] = [];
+  for (let q = qualityBand.max; q >= qualityBand.min; q--) tryOrder.push(q);
+  for (let q = qualityBand.min - 1; q >= 0; q--) tryOrder.push(q);
+
+  for (const slot of slots) {
+    if (slot === 'offhand' && out.mainhand?.slot === 'twohand') continue;
+    const it = topWeightForSlot(ds, botLevel, cls, specId, slot, tryOrder, worn);
+    if (!it) continue;
+    out[slot] = it;
+    worn.add(it.entry);
+  }
+  return out;
+}
+
+/** Export score helper for tests (weight + Q×ilvl). */
+export function cacheEquipScore(cls: number, specId: number, it: ItemDef): number {
+  return playerbotEquipScore(cls, specId, it);
+}