azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/rotation/classes/druid.ts

@@ -0,0 +1,58 @@
+// Druid rotation post-pass and kit policy. Pure. The form button selects that form's kit via formId
+// gates. Recovery holds NO form rows: a recast toggle there read as "jump into form when low".
+
+import type { SpellDef } from '../../../data/schema.ts';
+import { inferRole } from '../../../engine/combat.ts';
+import type { ClassRotationHooks } from './hooks.ts';
+import {
+  gateSupportDamageOnTopped,
+  gateSupportDamageRows,
+  hoistSupportHealsIntoCombat,
+} from './supportSpec.ts';
+
+function isFeralSpecName(spec: string): boolean {
+  const s = spec.toLowerCase();
+  return s === 'feral' || s === 'feral combat' || s.startsWith('feral')
+    || s === 'feral tank' || s === 'feraltank' || s === 'guardian' || s === 'bear';
+}
+
+// Form-kit vs caster-kit filter for role-bucket FALLBACK damage roles. Authored pack rules still win; this
+// only filters the unlisted tail.
+function allowDruidFallbackSpell(spell: SpellDef, spec: string): boolean {
+  const role = spell.role ?? inferRole(spell);
+
+  if (isFeralSpecName(spec)) {
+    // Cat/Bear kit: energy/rage spenders, physical strikes, named feral tools.
+    if (spell.powerType === 'energy' || spell.powerType === 'rage') return true;
+    if (spell.school === 'physical') return true;
+    if (/feral|faerie fire \(feral\)/i.test(spell.name)) return true;
+    // Skip mana caster nukes/DoTs (Moonfire/Starfire/Wrath/Insect Swarm/…) as ALWAYS fillers.
+    return false;
+  }
+  // Balance / Restoration: mana caster kit — no cat/bear energy-rage mash.
+  if (spell.powerType === 'energy' || spell.powerType === 'rage') return false;
+  const school = spell.school;
+  if (school === 'physical' && (role === 'strike' || role === 'instant_nuke')) return false;
+  // Druid caster schools (Wrath/Moonfire nature; Starfire arcane) + nature control (roots/hibernate).
+  // Cite: Spell.dbc School; nature/arcane are the Balance kit.
+  if (school === 'nature' || school === 'arcane') return true;
+  // Unknown schools drop (holy/fire/frost/shadow/physical non-strikes).
+  return false;
+}
+
+export const druidHooks: ClassRotationHooks = {
+  allowFormFallback(spec) {
+    // Form enter: only on form-using specs (Feral druids).
+    return isFeralSpecName(spec);
+  },
+  allowFallbackSpell(spell, spec) {
+    return allowDruidFallbackSpell(spell, spec);
+  },
+  afterFallback(ctx) {
+    if (/^restoration$/i.test(ctx.spec)) {
+      hoistSupportHealsIntoCombat(ctx);
+      gateSupportDamageOnTopped(ctx);
+      gateSupportDamageRows(ctx);
+    }
+  },
+};

package/src/domain/rotation/classes/hooks.ts

@@ -0,0 +1,59 @@
+// PURE: no DOM/RNG/Date. Per-class rotation hook contract.
+
+import type { DataStore } from '../../../data/dataStore.ts';
+import type { SpellDef } from '../../../data/schema.ts';
+import type { Character } from '../../character/character.ts';
+import type { Inventory } from '../../items/inventory.ts';
+import type { SpellBook } from '../../character/spellbook.ts';
+import type { SuggestionClassKey } from '../rotationSuggestions.ts';
+import type { RotationPhase, RotationRule } from '../types.ts';
+
+/** Mutable build state passed to class post-passes. */
+export interface FinalizeContext {
+  char: Character;
+  ds: DataStore;
+  sb: SpellBook;
+  inventory?: Inventory;
+  /** primarySpec result for this build. */
+  spec: string;
+  classKey: SuggestionClassKey;
+  known: readonly SpellDef[];
+  knownById: Map<number, SpellDef>;
+  phases: Record<RotationPhase, RotationRule[]>;
+  usedSpellsByPhase: Record<RotationPhase, Set<number>>;
+  usedItemsByPhase: Record<RotationPhase, Set<number>>;
+  /** Next fallback rule id (`f0`, `f1`, …). */
+  nextFallbackId: () => string;
+  /** Which fight this list is for. A post-pass that injects PvE utility must not fire on `pvp`. */
+  mode?: 'pvp';
+}
+
+// Optional per-class hooks. Shared pipeline calls these; missing methods are no-ops / allow-all.
+// Class-scoped rotation fixes should land in `classes/<class>.ts`, not build.ts.
+export interface ClassRotationHooks {
+  // Role-bucket FALLBACK filter for damage-role spells (cross-kit guard). Called only after shared utility
+  // allow-list (interrupts, heals, …) passes. Default: allow.
+  allowFallbackSpell?(spell: SpellDef, spec: string): boolean;
+
+  // Whether a `role === 'form'` spell may appear in the fallback for this spec. Default: allow (warriors
+  // any stance tree). Druid: Feral only.
+  allowFormFallback?(spec: string): boolean;
+
+  // After authored suggestion rows materialize, before role-bucket tail. Paladin: seal collapse + Judgement
+  // gate (first pass).
+  afterSuggestion?(ctx: FinalizeContext): void;
+
+  // After role-bucket tail + shared interrupt hoist. Hunter Auto Shot primary, mage PoM, paladin
+  // re-finalize, etc.
+  afterFallback?(ctx: FinalizeContext): void;
+}
+
+/** Rebuild used-id sets for one phase after a finalizer drops/rewrites rules. */
+export function rebuildPhaseUsed(ctx: FinalizeContext, phase: RotationPhase): void {
+  ctx.usedSpellsByPhase[phase].clear();
+  ctx.usedItemsByPhase[phase].clear();
+  for (const r of ctx.phases[phase]) {
+    if (r.action.kind === 'spell') ctx.usedSpellsByPhase[phase].add(r.action.spellId);
+    else if (r.action.kind === 'item') ctx.usedItemsByPhase[phase].add(r.action.itemEntry);
+  }
+}

package/src/domain/rotation/classes/hunter.ts

@@ -0,0 +1,156 @@
+// PURE: no DOM/RNG/Date. Hunter rotation post-pass + kit policy.
+
+import type { DataStore } from '../../../data/dataStore.ts';
+import type { SpellDef } from '../../../data/schema.ts';
+import { inferRole } from '../../../engine/combat.ts';
+import { cond, isFeignDeathSpell } from '../classify.ts';
+import type { RotationRule } from '../types.ts';
+import { rebuildPhaseUsed, type ClassRotationHooks, type FinalizeContext } from './hooks.ts';
+
+function isAutoShotOrShootSpell(def: SpellDef | undefined): boolean {
+  if (!def) return false;
+  if (/^auto shot$/i.test(def.name)) return true;
+  if (/^shoot$/i.test(def.name)) return true;
+  // Paid shoot-role shots (Multi/Aimed) are abilities, not the auto-repeat toggle.
+  // Cite: predicates.isRangedAutoRepeatToggle; KI-745.
+  if ((def.cost ?? 0) > 0 || (def.castTimeMs ?? 0) > 0 || (def.gcdMs ?? 0) > 0) return false;
+  const role = def.role ?? inferRole(def);
+  return role === 'shoot';
+}
+
+/** Melee next-swing / short-range strike that should not outrank Auto Shot when unguarded. */
+function isUnconditionalHunterMeleeStrike(def: SpellDef | undefined, rule: RotationRule): boolean {
+  if (!def) return false;
+  // A melee strike gated only on `inMelee` range still sorts after Auto Shot as a
+  // situational next-swing — the inMelee gate is not a "special" trigger.
+  const nonMeleeGates = rule.conditions.filter((c) => c.metric !== 'inMelee');
+  if (nonMeleeGates.length > 0) return false;
+  if (def.onNextSwing) return true;
+  const role = def.role ?? inferRole(def);
+  // Raptor Strike and similar: strike role, melee range band.
+  return role === 'strike' && (def.rangeMax ?? 0) > 0 && (def.rangeMax ?? 0) <= 5;
+}
+
+// Hunter combat must keep Auto Shot as the ranged primary, never leaving unconditional next-swing
+// Raptor Strike as the sole filler. Order: conditioned specials, then shoot, then melee.
+export function finalizeHunterRangedPrimary(
+  combat: RotationRule[],
+  known: readonly SpellDef[],
+  knownById: Map<number, SpellDef>,
+  ds: DataStore,
+): RotationRule[] {
+  const autoDef =
+    known.find((s) => /^auto shot$/i.test(s.name))
+    ?? known.find((s) => isAutoShotOrShootSpell(s));
+
+  let rules = combat.slice();
+  const hasShoot = rules.some(
+    (r) => r.action.kind === 'spell' && isAutoShotOrShootSpell(
+      knownById.get(r.action.spellId) ?? ds.spell(r.action.spellId),
+    ),
+  );
+  if (autoDef && !hasShoot) {
+    rules.push({
+      id: 'auto-shot',
+      action: { kind: 'spell', spellId: autoDef.id },
+      conditions: [],
+      enabled: true,
+    });
+  }
+
+  const specials: RotationRule[] = [];
+  const instantShots: RotationRule[] = [];
+  const castTimeShots: RotationRule[] = [];
+  const shoots: RotationRule[] = [];
+  const nextSwings: RotationRule[] = [];
+  for (const r of rules) {
+    if (r.action.kind === 'spell') {
+      const def = knownById.get(r.action.spellId) ?? ds.spell(r.action.spellId);
+      if (isAutoShotOrShootSpell(def)) {
+        shoots.push(r);
+        continue;
+      }
+      if (isUnconditionalHunterMeleeStrike(def, r)) {
+        nextSwings.push(r);
+        continue;
+      }
+      // Aimed Shot is a 3.5 s stand-still; ahead of Arcane Shot it roots the hunter while the boss
+      // walks into the dead zone. C++ fires Arcane first. Cite: PlayerbotHunterAI.cpp:286, :306.
+      const nm = (def?.name ?? '').toLowerCase();
+      if (nm === 'aimed shot' || ((def?.castTimeMs ?? 0) > 0 && /shot$/.test(nm) && nm !== 'auto shot')) {
+        castTimeShots.push(r);
+        continue;
+      }
+      if (nm === 'arcane shot' || nm === 'multi-shot' || nm === 'multishot') {
+        instantShots.push(r);
+        continue;
+      }
+    }
+    specials.push(r);
+  }
+  // Dedupe shoot ids (band + fallback can both list Auto Shot after per-phase merge).
+  const seenShoot = new Set<number>();
+  const uniqueShoots: RotationRule[] = [];
+  for (const r of shoots) {
+    if (r.action.kind !== 'spell') continue;
+    if (seenShoot.has(r.action.spellId)) continue;
+    seenShoot.add(r.action.spellId);
+    uniqueShoots.push(r);
+  }
+  return [...specials, ...instantShots, ...castTimeShots, ...uniqueShoots, ...nextSwings];
+}
+
+/** Call Pet before Revive Pet — `pet.alive==0` is true for a missing pet, so Revive first
+ * is picked, the cast fails, and Aspect of the Hawk never fires. */
+export function orderHunterPetBuffs(ctx: FinalizeContext): void {
+  const call: RotationRule[] = [];
+  const revive: RotationRule[] = [];
+  const rest: RotationRule[] = [];
+  for (const r of ctx.phases.buffs) {
+    if (r.action.kind !== 'spell') { rest.push(r); continue; }
+    const def = ctx.knownById.get(r.action.spellId) ?? ctx.ds.spell(r.action.spellId);
+    const n = (def?.name ?? '').toLowerCase();
+    if (n === 'call pet') call.push(r);
+    else if (n === 'revive pet') revive.push(r);
+    else rest.push(r);
+  }
+  if (!call.length && !revive.length) return;
+  ctx.phases.buffs = [...call, ...revive, ...rest];
+  rebuildPhaseUsed(ctx, 'buffs');
+}
+
+// Combat-head Feign Death: any enemy on the hunter. Idempotent. No pet term — see the same gate in
+// rotation/build.ts (PlayerbotHunterAI.cpp:246).
+export function ensureHunterFeignDeath(ctx: FinalizeContext): void {
+  const fd = ctx.known.find((s) => isFeignDeathSpell(s));
+  if (!fd) return;
+  if (ctx.phases.combat.some((r) => r.action.kind === 'spell' && r.action.spellId === fd.id)) return;
+  ctx.phases.combat.unshift({
+    id: ctx.nextFallbackId(),
+    action: { kind: 'spell', spellId: fd.id },
+    conditions: [
+      cond('self', 'hasAggro', '==', 1),
+    ],
+    enabled: true,
+  });
+  rebuildPhaseUsed(ctx, 'combat');
+}
+
+export const hunterHooks: ClassRotationHooks = {
+  afterSuggestion(ctx) {
+    orderHunterPetBuffs(ctx);
+    ensureHunterFeignDeath(ctx);
+  },
+  afterFallback(ctx) {
+    orderHunterPetBuffs(ctx);
+    ensureHunterFeignDeath(ctx);
+    // Hunter: Auto Shot is the ranged primary; unconditional on-next-swing Raptor must not
+    // sit alone ahead of it (KI-389 starter Raptor-only combat).
+    ctx.phases.combat = finalizeHunterRangedPrimary(
+      ctx.phases.combat,
+      ctx.known,
+      ctx.knownById,
+      ctx.ds,
+    );
+  },
+};

package/src/domain/rotation/classes/index.ts

@@ -0,0 +1,104 @@
+// PURE: no DOM/RNG/Date. Per-class rotation hooks registry + public kit filters.
+
+import type { SpellDef } from '../../../data/schema.ts';
+import { inferRole } from '../../../engine/combat.ts';
+import type { SuggestionClassKey } from '../rotationSuggestions.ts';
+import { isDispelSpell, isInterruptSpell } from '../classify.ts';
+import type { ClassRotationHooks, FinalizeContext } from './hooks.ts';
+import { druidHooks } from './druid.ts';
+import { hunterHooks } from './hunter.ts';
+import { mageHooks } from './mage.ts';
+import { paladinHooks } from './paladin.ts';
+import { priestHooks } from './priest.ts';
+import { rogueHooks } from './rogue.ts';
+import { shamanHooks } from './shaman.ts';
+import { warlockHooks } from './warlock.ts';
+import { reconcilePullStanceWithCombat, warriorHooks } from './warrior.ts';
+import { ensureCastTimePullOpener, orderPullByTimeToLand } from './pullOpener.ts';
+
+export type { ClassRotationHooks, FinalizeContext } from './hooks.ts';
+export { rebuildPhaseUsed } from './hooks.ts';
+export { finalizePaladinSealJudge } from './paladin.ts';
+export { finalizeHunterRangedPrimary } from './hunter.ts';
+export { reconcilePullStanceWithCombat } from './warrior.ts';
+
+/** Static registry — one hooks object per suggestion class key. */
+export const CLASS_HOOKS: Record<SuggestionClassKey, ClassRotationHooks> = {
+  warrior: warriorHooks,
+  paladin: paladinHooks,
+  hunter: hunterHooks,
+  rogue: rogueHooks,
+  priest: priestHooks,
+  shaman: shamanHooks,
+  mage: mageHooks,
+  warlock: warlockHooks,
+  druid: druidHooks,
+};
+
+export function getClassHooks(classKey: SuggestionClassKey): ClassRotationHooks {
+  return CLASS_HOOKS[classKey];
+}
+
+// Whether a known spell may appear in the role-bucket FALLBACK for this class and spec. Interrupts,
+// dispels, seals, pet tools and heals stay open; combat damage is restricted to the spec's kit.
+export function spellAllowedInRoleBucketFallback(
+  spell: SpellDef,
+  classKey: SuggestionClassKey,
+  spec: string,
+): boolean {
+  const role = spell.role ?? inferRole(spell);
+  const hooks = CLASS_HOOKS[classKey];
+
+  // Always-safe utility categories (not cross-kit DPS mash).
+  if (isInterruptSpell(spell) || isDispelSpell(spell)) return true;
+  if (role === 'shoot' || role === 'pet_summon' || role === 'pet_heal' || role === 'pet_tame') return true;
+  if (role === 'totem_summon' || role === 'conjure' || role === 'seal' || role === 'judgement') return true;
+  if (role === 'charge') return true;
+
+  // Form enter: only on form-using specs (Feral druids; warriors any stance tree).
+  if (role === 'form') {
+    return hooks.allowFormFallback?.(spec) ?? true;
+  }
+
+  // Heals / self keep-ups are not the cross-kit problem (recovery + buffs).
+  if (role === 'buff') {
+    // Misclassified ranged channels already corrected in inferRole; any remaining buff
+    // with only proc_trigger + range is still blocked below if reclassified as damage.
+    return true;
+  }
+
+  const isDamageRole =
+    role === 'nuke' ||
+    role === 'instant_nuke' ||
+    role === 'strike' ||
+    role === 'dot' ||
+    role === 'control';
+
+  if (!isDamageRole) return true;
+
+  // Class/spec kit filter (school tables, feral vs caster, …).
+  return hooks.allowFallbackSpell?.(spell, spec) ?? true;
+}
+
+/** After authored suggestion rows — class post-pass (e.g. paladin seals). */
+export function applyClassAfterSuggestion(ctx: FinalizeContext): void {
+  CLASS_HOOKS[ctx.classKey].afterSuggestion?.(ctx);
+}
+
+// After role-bucket tail + interrupt hoist. Always runs stance reconcile (historical global; body in
+// warrior.ts), then class hooks.
+export function applyClassAfterFallback(ctx: FinalizeContext): void {
+  // Fury thrash: combat wants Berserker Stance while pull still lists Battle Stance and Charge.
+  // Align the pull form with combat's and swap Charge for Intercept when berserking.
+  ctx.phases.pull = reconcilePullStanceWithCombat(
+    ctx.phases.pull,
+    ctx.phases.combat,
+    ctx.knownById,
+    ctx.ds,
+    ctx.known,
+  );
+  CLASS_HOOKS[ctx.classKey].afterFallback?.(ctx);
+  ensureCastTimePullOpener(ctx);
+  // Slowest-landing cast first so a multi-cast opener lands together (Shadow Bolt -> Immolate).
+  orderPullByTimeToLand(ctx);
+}

package/src/domain/rotation/classes/mage.ts

@@ -0,0 +1,99 @@
+// PURE: no DOM/RNG/Date. Mage rotation post-pass + kit policy.
+
+import type { SpellDef } from '../../../data/schema.ts';
+import { normalizeSpellName } from '../rotationSuggestions.ts';
+import {
+  isMultiTargetCombatSpell,
+  isNovaKiteSpell,
+  novaKiteConditions,
+  NOVA_KITE_STEP_BACK_YD,
+} from '../classify.ts';
+import type { ClassRotationHooks } from './hooks.ts';
+
+/** Canonical tree → combat damage schools allowed in role-bucket fallback. */
+const MAGE_FALLBACK_SCHOOLS: Readonly<Record<string, ReadonlySet<string>>> = {
+  Frost: new Set(['frost']),
+  Fire: new Set(['fire']),
+  Arcane: new Set(['arcane']),
+};
+
+function schoolAllowed(spell: SpellDef, spec: string): boolean {
+  const allowed = MAGE_FALLBACK_SCHOOLS[spec];
+  if (!allowed) return true;
+  // Multi-target / channeled AoE is available cross-spec and self-gates on enemyCount>=2.
+  if (isMultiTargetCombatSpell(spell)) return true;
+  const school = (spell.school ?? '').toLowerCase();
+  if (allowed.has(school)) return true;
+  return false;
+}
+
+export const mageHooks: ClassRotationHooks = {
+  allowFallbackSpell(spell, spec) {
+    return schoolAllowed(spell, spec);
+  },
+  afterFallback(ctx) {
+    let nova: (typeof ctx.known)[number] | undefined;
+    for (let i = ctx.known.length - 1; i >= 0; i--) {
+      if (isNovaKiteSpell(ctx.known[i]!)) { nova = ctx.known[i]; break; }
+    }
+    if (nova && !ctx.phases.combat.some((r) => r.action.kind === 'spell' && r.action.spellId === nova.id)) {
+      ctx.phases.combat.unshift({
+        id: ctx.nextFallbackId(),
+        action: { kind: 'spell', spellId: nova.id },
+        conditions: novaKiteConditions(nova),
+        enabled: true,
+        after: { stepBackYd: NOVA_KITE_STEP_BACK_YD },
+      });
+    }
+    // Presence of Mind is a one-shot next-cast talent, never a buffPresent keep-up. When an
+    // authored pull blocked injection, still expose it as a bare when-ready pull tool.
+    const pom = ctx.known.find((s) => normalizeSpellName(s.name) === 'presence of mind');
+    if (pom && !ctx.phases.pull.some((r) => r.action.kind === 'spell' && r.action.spellId === pom.id)) {
+      ctx.phases.pull.push({
+        id: ctx.nextFallbackId(),
+        action: { kind: 'spell', spellId: pom.id },
+        conditions: [], // CD-gated at session; not buffPresent (never clears)
+        enabled: true,
+      });
+    }
+
+    // Frost: the school nuke before cross-school instant fillers, since role buckets put
+    // instant_nuke first and starve Frostbolt. Only the two fillers swap — gated rows stay put.
+    if (ctx.spec === 'Frost') {
+      type Rule = (typeof ctx.phases.combat)[number];
+      const spellIdOf = (r: Rule): number | null =>
+        r.action.kind === 'spell' ? r.action.spellId : null;
+      const schoolOf = (id: number) => (ctx.knownById.get(id)?.school ?? '').toLowerCase();
+      const isFrostCombat = (r: Rule) => {
+        const id = spellIdOf(r);
+        return id != null && schoolOf(id) === 'frost';
+      };
+      const isFireInstantFiller = (r: Rule) => {
+        const id = spellIdOf(r);
+        if (id == null) return false;
+        const s = ctx.knownById.get(id);
+        if (!s) return false;
+        const name = normalizeSpellName(s.name);
+        const castMs = s.castTimeMs ?? 0;
+        return (s.school ?? '').toLowerCase() === 'fire' && (name === 'fire blast' || castMs === 0);
+      };
+      const ungated = (r: Rule) => r.enabled !== false && r.conditions.length === 0;
+      // The primary cast: the first ungated frost rule that actually has a cast time. The
+      // instants (Ice Block / Frost Nova / Ice Barrier) are frost too and are not the nuke.
+      const combat = ctx.phases.combat;
+      const nukeIdx = combat.findIndex((r) => {
+        if (!ungated(r) || !isFrostCombat(r)) return false;
+        const id = spellIdOf(r);
+        return id != null && (ctx.knownById.get(id)?.castTimeMs ?? 0) > 0;
+      });
+      if (nukeIdx > 0) {
+        const above = combat.slice(0, nukeIdx).filter((r) => ungated(r) && isFireInstantFiller(r));
+        if (above.length) {
+          const kept = combat.filter((r) => !above.includes(r));
+          const at = kept.indexOf(combat[nukeIdx]!) + 1;
+          ctx.phases.combat = [...kept.slice(0, at), ...above, ...kept.slice(at)];
+        }
+      }
+    }
+  },
+};