azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/spells/breakableStunCc.ts

@@ -0,0 +1,166 @@
+// MOD_STUN to the Phonecraft CC surface. CMaNGOS uses aura 12 for hard stuns AND for sleep, shackle,
+// sap and banish, so the Mechanic and AuraInterruptFlags decide the real behaviour.
+
+import type { ControlKind, Mechanic, School, SpellDef, SpellEffect } from '../../data/schema.ts';
+import { CREATURE_TYPE } from '../../data/schema.ts';
+
+/** SharedDefines.h Mechanics (1-based). */
+export const MECHANIC_SLEEP = 10;
+export const MECHANIC_STUN = 12;
+export const MECHANIC_FREEZE = 13;
+export const MECHANIC_KNOCKOUT = 14;
+export const MECHANIC_BANISH = 18;
+export const MECHANIC_SHACKLE = 20;
+export const MECHANIC_SAPPED = 30;
+
+// Resolve the spell-level mechanic id for a MOD_STUN slot: the raw mechanic wins, with the DBC name
+// and tooltip as the fallback for extracts that lost the column.
+export function resolveModStunMechanicId(
+  spell: Pick<SpellDef, 'name' | 'description'>,
+  rawMechanic: number,
+): number {
+  const fromRaw = rawMechanic | 0;
+  if (fromRaw > 0) return fromRaw;
+
+  const name = (spell.name || '').toLowerCase();
+  // Exact DBC English names (Sleep ranks, Hibernate ranks, Shackle Undead ranks).
+  if (name === 'sleep' || name === 'hibernate' || name.startsWith('zzoldsleep')) {
+    return MECHANIC_SLEEP;
+  }
+  if (name === 'shackle undead') return MECHANIC_SHACKLE;
+
+  // Creature-cast sleeps sometimes use unique names; tooltip still says awaken.
+  const desc = (spell.description || '').toLowerCase();
+  if (desc.includes('awaken') && (desc.includes('to sleep') || desc.includes('puts') && desc.includes('sleep'))) {
+    return MECHANIC_SLEEP;
+  }
+  if (desc.includes('shackle') && desc.includes('undead')) return MECHANIC_SHACKLE;
+
+  return 0;
+}
+
+export interface ModStunCcShape {
+  control: ControlKind;
+  mechanic: Mechanic;
+  breakOnDamage?: boolean;
+  onlyTypes?: number[];
+}
+
+// Map a mechanic id to the engine CC shape for MOD_STUN. A hard stun stays control plus mechanic with
+// no break-on-damage. Sap and Gouge share knockout with bombs, so the name separates them.
+export function modStunCcShape(mechanicId: number, spellName?: string): ModStunCcShape {
+  const name = (spellName || '').toLowerCase();
+  // Sap / Gouge: classic stores MECHANIC_KNOCKOUT (14); play surface is incap+sap.
+  // Cite: SpellMgr.h MECHANIC_KNOCKOUT Includes Sap, Gouge; enrich-stealth.mjs.
+  if (name === 'sap' || name === 'gouge') {
+    return { control: 'incapacitate', mechanic: 'sap', breakOnDamage: true };
+  }
+
+  switch (mechanicId | 0) {
+    case MECHANIC_SLEEP:
+      // Sleep / Hibernate: break-on-damage incapacitate. DR track = sleep.
+      // Cite: SpellMgr.h MECHANIC_SLEEP; tooltip "Any damage caused will awaken".
+      return { control: 'incapacitate', mechanic: 'sleep', breakOnDamage: true };
+    case MECHANIC_SHACKLE:
+      // Shackle Undead: break-on-damage incap, undead only. The mechanic is SHACKLE, not sleep, so
+      // Will of the Forsaken must not purge it. Cite: SharedDefines MECHANIC_SHACKLE=20.
+      return {
+        control: 'incapacitate',
+        mechanic: 'shackle',
+        breakOnDamage: true,
+        onlyTypes: [CREATURE_TYPE.UNDEAD],
+      };
+    case MECHANIC_SAPPED:
+      return { control: 'incapacitate', mechanic: 'sap', breakOnDamage: true };
+    case MECHANIC_KNOCKOUT:
+      // Bombs, Gouge and Sap share knockout. Without a Sap or Gouge name above, keep break-on-damage
+      // with the real mechanic id rather than collapsing it to a stun.
+      return { control: 'stun', mechanic: 'knockout', breakOnDamage: true };
+    case MECHANIC_BANISH:
+      // Banish isolation rides mechanic banish; control stays stun-like lockout.
+      // Cite: SpellAuras.cpp ~3025 MECHANIC_BANISH → UNIT_STAT_ISOLATED.
+      return { control: 'stun', mechanic: 'banish' };
+    case MECHANIC_FREEZE:
+      // Freezing Trap Effect: MOD_STUN + damage break. Cite: spell_template 3355 AIF=2.
+      return { control: 'stun', mechanic: 'freeze', breakOnDamage: true };
+    default:
+      // MECHANIC_STUN (12) or 0 / unknown → hard stun.
+      return { control: 'stun', mechanic: 'stun' };
+  }
+}
+
+// AURA_INTERRUPT_FLAG_DAMAGE — any damage removes the aura. The dump has 0 on every row, so the live
+// source is Spell.dbc field 18. Cite: SpellDefines.h:362–386; Unit.cpp DealDamage.
+export const AURA_INTERRUPT_FLAG_DAMAGE = 0x2;
+
+/** Build a cc SpellEffect for a MOD_STUN slot. */
+export function buildModStunCcEffect(
+  mechanicId: number,
+  durationMs: number,
+  school: School,
+  spellName?: string,
+  /** Spell.dbc AuraInterruptFlags (or 0). When DAMAGE is set, stamp breakOnDamage. */
+  auraInterruptFlags = 0,
+): SpellEffect {
+  const shape = modStunCcShape(mechanicId, spellName);
+  const eff: SpellEffect = {
+    kind: 'cc',
+    control: shape.control,
+    mechanic: shape.mechanic,
+    durationMs,
+    school,
+  };
+  // Mechanic-driven break (sleep/knockout/freeze) OR DBC AIF_DAMAGE (Tidal Charm, bombs, Encage).
+  // Hammer of Justice has AIF=0 so stays hard. Cite: Spell.dbc field 18; census dimension I.
+  if (shape.breakOnDamage || ((auraInterruptFlags | 0) & AURA_INTERRUPT_FLAG_DAMAGE) !== 0) {
+    (eff as { breakOnDamage?: boolean }).breakOnDamage = true;
+  }
+  if (shape.onlyTypes) (eff as { onlyTypes?: number[] }).onlyTypes = shape.onlyTypes;
+  return eff;
+}
+
+/** SPELL_AURA_MOD_CONFUSE — SetConfused, never SetStunned. Cite: SpellAuras.cpp:2354–2366. */
+const SPELL_AURA_MOD_CONFUSE = 5;
+
+// In-place retag of a MOD_CONFUSE disorient the bake surfaced as a hard stun: Blind and Scatter Shot
+// read as stuns that no damage ended. Gated on an actual aura-5 slot, so a real stun cannot be caught.
+export function retagDisorientOnSpell(spell: SpellDef): boolean {
+  if (!spell.effects?.length) return false;
+  if (!spell.rawEffects?.some((r) => (r.auraName | 0) === SPELL_AURA_MOD_CONFUSE)) return false;
+  let changed = false;
+  for (const e of spell.effects) {
+    if (e.kind !== 'cc' || e.mechanic !== 'disoriented') continue;
+    if (e.control === 'incapacitate' && e.breakOnDamage === true) continue;
+    (e as { control: ControlKind }).control = 'incapacitate';
+    (e as { breakOnDamage?: boolean }).breakOnDamage = true;
+    changed = true;
+  }
+  return changed;
+}
+
+// In-place retag of bake-surface hard-stun CC that is really sleep, shackle or hibernate, for repros
+// and kits that read bake effects before resolve. Real stuns are untouched.
+export function retagBreakableStunOnSpell(spell: SpellDef): boolean {
+  if (!spell.effects?.length) return false;
+  const mechId = resolveModStunMechanicId(spell, 0);
+  if (!mechId || mechId === MECHANIC_STUN) return false;
+  // Only retag when the slot still looks like generic MOD_STUN hard stun.
+  let changed = false;
+  for (let i = 0; i < spell.effects.length; i++) {
+    const e = spell.effects[i]!;
+    if (e.kind !== 'cc') continue;
+    if (e.control !== 'stun' || e.mechanic !== 'stun') continue;
+    const next = buildModStunCcEffect(mechId, e.durationMs, e.school, spell.name);
+    spell.effects[i] = next;
+    changed = true;
+  }
+  // Also stamp raw.mechanic so later SI paths see the sourced id without name fallback.
+  if (changed && spell.rawEffects) {
+    for (const raw of spell.rawEffects) {
+      if ((raw.auraName | 0) === 12 && (raw.mechanic | 0) === 0) {
+        raw.mechanic = mechId;
+      }
+    }
+  }
+  return changed;
+}

package/src/domain/spells/cancelAura.ts

@@ -0,0 +1,80 @@
+// CMSG_CANCEL_AURA — right-clicking a buff drops the aura. A port of HandleCancelAuraOpcode. Word 0
+// and word 1 attributes are both baked, so every bit this gate needs is readable.
+
+import type { SpellDef } from '../../data/schema/spell.ts';
+import { SPELL_ATTR } from '../../engine/spells/spellAttributes.ts';
+import { isPartyAreaAura } from './areaAuraMembership.ts';
+
+/** SPELL_ATTR_AURA_IS_DEBUFF. Cite: SpellDefines.h:56 (word 0 bit 26). */
+export const SPELL_ATTR_AURA_IS_DEBUFF = 0x04000000;
+/** SPELL_ATTR_EX_NO_AURA_ICON. Cite: SpellDefines.h:94 (word 1 bit 28). */
+export const SPELL_ATTR_EX_NO_AURA_ICON = 0x10000000;
+
+/** Why a right-click did nothing, or null when the aura may be cancelled. */
+export type AuraCancelRefusal =
+  | 'unknown-spell'
+  | 'passive'
+  | 'debuff'
+  | 'no-aura-cancel'
+  | 'no-aura-icon'
+  | 'channeled'
+  | 'possessed'
+  | 'foreign-area-aura';
+
+// The two gate inputs that are state rather than spell data, both straight off the opcode: is the
+// player possessed or charmed, and is the holder's caster the player.
+export interface AuraCancelState {
+  /** True while something else drives the player. Refuses every cancel. */
+  possessed?: boolean;
+  // True when the player is the holder's caster. Only consulted for an area aura, and `undefined` counts as
+  // NOT own — an unknown caster must not open a cancel the core refuses.
+  ownAura?: boolean;
+}
+
+// HandleCancelAuraOpcode in the core's own order, so the reason reported is the gate the client would
+// have hit. Only the holder lookup is left to the caller, which already holds the aura.
+export function auraCancelRefusal(
+  sp: SpellDef | null | undefined,
+  st: AuraCancelState = {},
+): AuraCancelRefusal | null {
+  if (!sp) return 'unknown-spell';
+  const attr = (sp.attributes ?? 0) >>> 0;
+  // :431 SPELL_ATTR_NO_AURA_CANCEL.
+  if (attr & SPELL_ATTR.NO_AURA_CANCEL) return 'no-aura-cancel';
+  // :434 SPELL_ATTR_EX_NO_AURA_ICON. Word 1 is baked; 933 rows carry the bit.
+  if (((sp.attributesEx ?? 0) >>> 0) & SPELL_ATTR_EX_NO_AURA_ICON) return 'no-aura-icon';
+  // :437 IsPassiveSpell (SpellMgr.h:340); `passive` is the baked word-0 bit 6, exact on every row.
+  if (sp.passive) return 'passive';
+  // :446 "cant remove any auras while possessed" — UNIT_FLAG_POSSESSED || HasCharmer().
+  if (st.possessed) return 'possessed';
+  // :450 !holder->IsPositive() (SpellAuras.cpp:5846). The engine's own buffs/debuffs split covers
+  // the hostile-caster case; this is the attribute half (IsPositiveAuraEffect, SpellMgr.h:1214).
+  if (attr & SPELL_ATTR_AURA_IS_DEBUFF) return 'debuff';
+  // :475 IsChanneledSpell (SpellMgr.h:1373) — the core interrupts the channel, not the holder.
+  if (sp.channelMs) return 'channeled';
+  // "Not own area auras can't be cancelled". isPartyAreaAura is this tree's predicate for
+  // effect 35 and also catches the bake rows carrying only that — the auras you hold but did not cast.
+  if (!st.ownAura && isPartyAreaAura(sp)) return 'foreign-area-aura';
+  return null;
+}
+
+// Reason text for a refused cancel. The real client draws no cancelable flag on these and a
+// right-click does nothing, so a caller should prefer silence; these exist for the dev log.
+export const CANCEL_AURA_REFUSAL_TEXT: Record<AuraCancelRefusal, string> = {
+  'unknown-spell': 'Unknown spell',
+  passive: 'That is a passive effect',
+  debuff: 'You cannot remove a debuff',
+  'no-aura-cancel': 'That effect cannot be cancelled',
+  'no-aura-icon': 'That effect cannot be cancelled',
+  channeled: 'Stop the channel instead',
+  possessed: 'You are not in control of yourself',
+  'foreign-area-aura': 'Only the caster can cancel that aura',
+};
+
+/** True when a buff chip for `sp` should respond to a right-click. */
+export function canCancelAura(
+  sp: SpellDef | null | undefined,
+  st: AuraCancelState = {},
+): boolean {
+  return auraCancelRefusal(sp, st) === null;
+}

package/src/domain/spells/diminishing.ts

@@ -0,0 +1,167 @@
+// Pure CC diminishing returns. Cite: Unit.cpp ApplyDiminishingToDuration ~8851; Unit.h
+// DiminishingLevels; SpellMgr.cpp GetDiminishingReturnsGroupForSpell ~2636. No DOM, no I/O.
+
+/** DiminishingLevels (Unit.h). */
+export const DIMINISHING_LEVEL = {
+  LEVEL_1: 0,
+  LEVEL_2: 1,
+  LEVEL_3: 2,
+  IMMUNE: 3,
+} as const;
+
+/** Duration multiplier by level (Unit.cpp ApplyDiminishingToDuration). */
+export function diminishingDurationMod(level: number): number {
+  switch (level) {
+    case DIMINISHING_LEVEL.LEVEL_1: return 1.0;
+    case DIMINISHING_LEVEL.LEVEL_2: return 0.5;
+    case DIMINISHING_LEVEL.LEVEL_3: return 0.25;
+    case DIMINISHING_LEVEL.IMMUNE: return 0.0;
+    default: return 1.0;
+  }
+}
+
+/** Apply DR to duration ms. Permanent (-1) and NONE group skip. Cite: Unit.cpp ~8851–8878. */
+export function applyDiminishingToDuration(durationMs: number, level: number): number {
+  if (durationMs < 0) return durationMs; // permanent
+  const mod = diminishingDurationMod(level);
+  return Math.floor(durationMs * mod);
+}
+
+/** 15s DR hit window (Unit.h DiminishingReturn hitTime comment). */
+export const DR_HIT_WINDOW_MS = 15_000;
+
+export interface DrState {
+  /** group id → { level, hitTimeMs } */
+  groups: Record<string, { level: number; hitTimeMs: number }>;
+}
+
+export function emptyDrState(): DrState {
+  return { groups: {} };
+}
+
+/** Get current level for a group, resetting to L1 if >15s since last hit. */
+export function getDiminishingLevel(state: DrState, group: string, nowMs: number): number {
+  const g = state.groups[group];
+  if (!g) return DIMINISHING_LEVEL.LEVEL_1;
+  if (nowMs - g.hitTimeMs > DR_HIT_WINDOW_MS) return DIMINISHING_LEVEL.LEVEL_1;
+  return g.level;
+}
+
+/** After a CC lands: bump level (L1→L2→L3→IMMUNE) and refresh hitTime. Returns new state (immutable). */
+export function bumpDiminishing(state: DrState, group: string, nowMs: number): DrState {
+  const cur = getDiminishingLevel(state, group, nowMs);
+  const nextLevel = Math.min(DIMINISHING_LEVEL.IMMUNE, cur + 1);
+  return {
+    groups: {
+      ...state.groups,
+      [group]: { level: nextLevel, hitTimeMs: nowMs },
+    },
+  };
+}
+
+/** Map mechanic string → DR group key (simplified SpellMgr grouping). */
+export function diminishingGroupForMechanic(mechanic: string, triggered = false): string {
+  switch (mechanic) {
+    case 'stun':
+      return triggered ? 'trigger_stun' : 'control_stun';
+    // MECHANIC_FREEZE has its OWN group and it is player-only, not the all-targets stun track, so
+    // Freezing Trap diminishes against players alone. Cite: SpellMgr.cpp:2700-2701.
+    case 'freeze':
+      return 'freeze';
+    case 'root':
+    case 'snare':
+    case 'daze':
+      return triggered ? 'trigger_root' : 'control_root';
+    case 'fear':
+    case 'turn':
+      return 'fear';
+    case 'horror': return 'deathcoil';
+    case 'polymorph':
+    case 'disoriented':
+      return 'polymorph';
+    case 'sleep':
+    case 'shackle':
+      return 'sleep';
+    case 'sap':
+    case 'knockout': return 'knockout';
+    case 'charm': return 'charm';
+    case 'silence':
+    case 'interrupt':
+      return 'silence';
+    case 'disarm': return 'disarm';
+    case 'banish': return 'banish';
+    default: return 'none';
+  }
+}
+
+// DiminishingReturnsType: 'all' applies even against creatures, 'player' only when the target is
+// player-controlled, and 'none' is not subject to level DR at all.
+export type DiminishingReturnsType = 'all' | 'player' | 'none';
+
+// The groups a rotation may ASK ABOUT, in a stable order, so drLevel's ref is an index the editor can
+// name. APPEND-ONLY: inserting or removing would change what a shipped row means.
+export const DIMINISHING_GROUP_ORDER: readonly string[] = [
+  'control_stun', 'trigger_stun', 'control_root', 'trigger_root', 'fear',
+  'polymorph', 'sleep', 'knockout', 'charm', 'silence',
+  'disarm', 'banish', 'freeze', 'deathcoil',
+] as const;
+
+/** Cite: SpellMgr.cpp GetDiminishingReturnsGroupType ~2748 (CHARM → DRTYPE_ALL @2756). */
+export function getDiminishingReturnsGroupType(group: string): DiminishingReturnsType {
+  switch (group) {
+    case 'control_stun':
+    case 'trigger_stun':
+    case 'kidneyshot':
+    case 'blind':
+    case 'charm':
+    // combat.ts simplified keys that map to the same DRTYPE_ALL groups:
+    case 'stun':
+      return 'all';
+    case 'sleep':
+    case 'control_root':
+    case 'trigger_root':
+    case 'fear':
+    case 'polymorph':
+    case 'deathcoil':
+    case 'freeze':
+    case 'banish':
+    case 'warlock_fear':
+    case 'knockout':
+    // combat.ts simplified shared tracks:
+    case 'incapacitate':
+    case 'root':
+      return 'player';
+    // 'silence' and 'disarm' fall through to 'none' ON PURPOSE, a departure from the source tier:
+    // both groups are marked "From 2.3.0", and 1.12 the game had no DR on either.
+    default:
+      return 'none';
+  }
+}
+
+// Whether duration is scaled by DR level for this group. Charm is special: duration diminish only in PvP.
+// Cite: SpellMgr.cpp IsDiminishingReturnsGroupDurationDiminished ~2737 (CHARM → pvp @2741).
+export function isDiminishingReturnsGroupDurationDiminished(group: string, pvp: boolean): boolean {
+  if (group === 'charm') return pvp;
+  return true;
+}
+
+// Whether DR levels apply (step advances / immune tracking). Cite: SpellMgr.cpp
+// IsSubjectToDiminishingLevels ~2778. true if (type == DRTYPE_PLAYER && pvp) || type == DRTYPE_ALL
+export function isSubjectToDiminishingLevels(group: string, pvp: boolean): boolean {
+  const type = getDiminishingReturnsGroupType(group);
+  return type === 'all' || (type === 'player' && pvp);
+}
+
+// Apply duration DR for a group, honoring charm's PvP-only duration diminish. Levels may still
+// advance in PvE while the duration stays full. Cite: Unit.cpp ApplyDiminishingToDuration ~8851.
+export function applyDiminishingToDurationForGroup(
+  durationMs: number,
+  level: number,
+  group: string,
+  pvp: boolean,
+): number {
+  if (durationMs < 0) return durationMs; // permanent
+  if (!isSubjectToDiminishingLevels(group, pvp)) return durationMs;
+  if (!isDiminishingReturnsGroupDurationDiminished(group, pvp)) return durationMs;
+  return applyDiminishingToDuration(durationMs, level);
+}

package/src/domain/spells/dispel.ts

@@ -0,0 +1,149 @@
+// Dispel type masks plus a pure ProcessDispelList selection. Pure, with an injected rng for the
+// selection; the miss chance is 0 until a spellmod says otherwise. Cite: SpellEffects.cpp ~2521.
+
+/** SPELL_EFFECT_DISPEL — SpellEffectDefines.h. */
+export const SPELL_EFFECT_DISPEL = 38;
+
+export const DISPEL_TYPE = {
+  NONE: 0,
+  MAGIC: 1,
+  CURSE: 2,
+  DISEASE: 3,
+  POISON: 4,
+  STEALTH: 5,
+  INVISIBILITY: 6,
+  ALL: 7,
+  SPE_NPC_ONLY: 8,
+  ENRAGE: 9,
+  ZG_TICKET: 10,
+} as const;
+
+/** DISPEL_ALL_MASK = MAGIC|CURSE|DISEASE|POISON */
+export const DISPEL_ALL_MASK =
+  (1 << DISPEL_TYPE.MAGIC) |
+  (1 << DISPEL_TYPE.CURSE) |
+  (1 << DISPEL_TYPE.DISEASE) |
+  (1 << DISPEL_TYPE.POISON);
+
+/** GetDispellMask(DispelType) — bit for type, or ALL mask. */
+export function getDispelMask(dispelType: number): number {
+  if (dispelType === DISPEL_TYPE.ALL) return DISPEL_ALL_MASK;
+  if (dispelType <= 0) return 0;
+  return 1 << dispelType;
+}
+
+export interface DispellableAura {
+  spellId: number;
+  /** Aura Dispel field from SpellEntry. */
+  dispelType: number;
+  stacks: number;
+}
+
+export function isDispellableByMask(aura: DispellableAura, mask: number): boolean {
+  if (!mask) return false;
+  if (aura.dispelType === DISPEL_TYPE.NONE) return false;
+  return (getDispelMask(aura.dispelType) & mask) !== 0;
+}
+
+export interface DispelRng {
+  /** [0,1) uniform */
+  next(): number;
+  /** inclusive int */
+  int(min: number, max: number): number;
+}
+
+// ProcessDispelList: pick up to `count` auras, 0 meaning 1, uniformly among those remaining, each
+// pick reducing the stack by one. The miss chance is SPELLMOD_RESIST_DISPEL_CHANCE, base 0.
+export function processDispelList(
+  candidates: DispellableAura[],
+  count: number,
+  rng: DispelRng,
+  missChance = 0,
+): { success: Array<{ spellId: number }>; fail: number[] } {
+  const need = count > 0 ? count : 1;
+  // Work on stack counts
+  const pool = candidates.map((a) => ({ ...a }));
+  const success: Array<{ spellId: number }> = [];
+  const fail: number[] = [];
+
+  for (let i = 0; i < need && pool.length > 0; i++) {
+    const idx = rng.int(0, pool.length - 1);
+    const aura = pool[idx]!;
+    // resist roll: roll_chance_i(miss_chance)
+    if (missChance > 0 && rng.next() * 100 < missChance) {
+      fail.push(aura.spellId);
+    } else {
+      success.push({ spellId: aura.spellId });
+    }
+    aura.stacks -= 1;
+    if (aura.stacks <= 0) pool.splice(idx, 1);
+  }
+  return { success, fail };
+}
+
+export function collectDispellable(
+  auras: readonly DispellableAura[],
+  mask: number,
+): DispellableAura[] {
+  return auras.filter((a) => isDispellableByMask(a, mask));
+}
+
+// The Classic CheckCast pure-dispel shape: effect 0 is DISPEL and the others are NONE. Those fail
+// with nothing-to-dispel on an empty target, while a multi-effect spell keeps casting.
+export function isPureDispelSpell(spell: {
+  effects: ReadonlyArray<{ kind: string }>;
+  rawEffects?: ReadonlyArray<{ effect: number }> | null;
+}): boolean {
+  const raw = spell.rawEffects;
+  if (raw && raw.length > 0) {
+    const e0 = raw[0];
+    if (!e0 || (e0.effect | 0) !== SPELL_EFFECT_DISPEL) return false;
+    for (let i = 1; i < 3; i++) {
+      const e = raw[i];
+      if (e && (e.effect | 0) !== 0) return false;
+    }
+    return true;
+  }
+  return spell.effects.length === 1 && spell.effects[0]!.kind === 'dispel';
+}
+
+/** First resolved `dispel` effect on the spell, if any. */
+export function firstDispelEffect(
+  spell: { effects: ReadonlyArray<{ kind: string; dispelType?: number; count?: number }> },
+): { kind: 'dispel'; dispelType: number; count: number } | null {
+  for (const e of spell.effects) {
+    if (e.kind === 'dispel' && typeof e.dispelType === 'number') {
+      return { kind: 'dispel', dispelType: e.dispelType, count: e.count ?? 1 };
+    }
+  }
+  return null;
+}
+
+/** Party claim map key. Cite: AUTOPILOT-PLAN §4 row 21 (copy of interruptClaim). */
+export function dispelClaimKey(targetId: string, cat: number): string {
+  return `${targetId}:${cat}`;
+}
+
+// Drop stale party dispel claims: claimer/target dead, category gone, or the claimer is no longer mid-cast
+// (kick / move-cancel / fizzle). Instant Tranq/Purge also release in applySpell.
+export function pruneDispelClaims(
+  claim: Map<string, string>,
+  isAlive: (id: string) => boolean,
+  hasCat: (targetId: string, cat: number) => boolean,
+  isCasting?: (id: string) => boolean,
+): void {
+  for (const [key, claimerId] of [...claim.entries()]) {
+    const sep = key.lastIndexOf(':');
+    if (sep <= 0) {
+      claim.delete(key);
+      continue;
+    }
+    const targetId = key.slice(0, sep);
+    const cat = Number(key.slice(sep + 1));
+    if (!Number.isFinite(cat) || !isAlive(claimerId) || !isAlive(targetId) || !hasCat(targetId, cat)) {
+      claim.delete(key);
+      continue;
+    }
+    if (isCasting && !isCasting(claimerId)) claim.delete(key);
+  }
+}

package/src/domain/spells/dispelMechanic.ts

@@ -0,0 +1,105 @@
+// SPELL_EFFECT_DISPEL_MECHANIC holder match + ProcessDispelList peel. Cite: SpellEffects.cpp:2499–2519;
+// SpellAuras.cpp:5788–5796 HasMechanic.
+
+import type { Mechanic } from '../../data/schema.ts';
+import { MECHANIC_ID } from '../creature/creatureAiConstants.ts';
+import {
+  processDispelList,
+  type DispelRng,
+  type DispellableAura,
+} from './dispel.ts';
+
+/** SharedDefines.h:374 MECHANIC_MOUNT. */
+export const MECHANIC_MOUNT = 21;
+
+export type MechanicSpellView = {
+  mechanic?: string | number | null;
+  rawEffects?: ReadonlyArray<{ mechanic?: number }> | null;
+  // SpellEffect.mechanic is a Mechanic string on cc/root/speed and a raw id on dispel_mechanic.
+  effects?: ReadonlyArray<{ kind: string; mechanic?: string | number | null }> | null;
+};
+
+export function mechanicIdOf(mechanic: string | number | null | undefined): number {
+  if (mechanic == null) return 0;
+  if (typeof mechanic === 'number') return Number.isFinite(mechanic) ? mechanic | 0 : 0;
+  const id = MECHANIC_ID[mechanic as Mechanic];
+  return id ?? 0;
+}
+
+/** SpellAuraHolder::HasMechanic — proto Mechanic / EffectMechanic; skip dispel_mechanic misc. Cite: SpellAuras.cpp:5788–5796. */
+export function holderHasMechanic(
+  spell: MechanicSpellView | null | undefined,
+  mechanic: number,
+): boolean {
+  if (!mechanic || !spell) return false;
+  if (mechanicIdOf(spell.mechanic) === mechanic) return true;
+  for (const raw of spell.rawEffects ?? []) {
+    if (((raw.mechanic ?? 0) | 0) === mechanic) return true;
+  }
+  for (const effect of spell.effects ?? []) {
+    if (effect.kind === 'dispel_mechanic') continue;
+    if (effect.mechanic && mechanicIdOf(effect.mechanic) === mechanic) return true;
+  }
+  return false;
+}
+
+// Live-row fallback for when the holder's SpellDef is on no kit: a stamped mechanic wins, a root maps
+// to MECHANIC_ROOT and a hostile speed effect to MECHANIC_SNARE.
+export function liveEffectHasMechanic(
+  e: { kind?: string; mechanic?: string | number; hostile?: boolean },
+  mechanic: number,
+): boolean {
+  if (mechanic <= 0) return false;
+  if (e.mechanic != null && mechanicIdOf(e.mechanic) === mechanic) return true;
+  if (e.kind === 'root' && mechanic === MECHANIC_ID.root) return true;
+  if (e.kind === 'speed' && e.hostile === true && mechanic === MECHANIC_ID.snare) return true;
+  return false;
+}
+
+export type MechanicLiveView = {
+  spellId: number;
+  stacks?: number;
+  mechanic?: string | number;
+  kind?: string;
+  hostile?: boolean;
+};
+
+export function collectMechanicHolders(
+  auras: ReadonlyArray<MechanicLiveView>,
+  mechanic: number,
+  lookup: (spellId: number) => MechanicSpellView | null | undefined,
+): DispellableAura[] {
+  const out: DispellableAura[] = [];
+  for (const aura of auras) {
+    if (liveEffectHasMechanic(aura, mechanic) || holderHasMechanic(lookup(aura.spellId), mechanic)) {
+      out.push({ spellId: aura.spellId, dispelType: 0, stacks: aura.stacks ?? 1 });
+    }
+  }
+  return out;
+}
+
+export function peelMechanicAuras<T extends { spellId: number }>(
+  auras: readonly T[],
+  mechanic: number,
+  count: number,
+  lookup: (spellId: number) => MechanicSpellView | null | undefined,
+  rng: DispelRng,
+): { kept: T[]; removed: T[] } {
+  const candidates = collectMechanicHolders(auras, mechanic, lookup);
+  if (!candidates.length) return { kept: auras.slice(), removed: [] };
+  const { success } = processDispelList(candidates, count, rng);
+  const left = new Map<number, number>();
+  for (const row of success) left.set(row.spellId, (left.get(row.spellId) ?? 0) + 1);
+  const kept: T[] = [];
+  const removed: T[] = [];
+  for (const aura of auras) {
+    const n = left.get(aura.spellId) ?? 0;
+    if (n > 0) {
+      left.set(aura.spellId, n - 1);
+      removed.push(aura);
+    } else {
+      kept.push(aura);
+    }
+  }
+  return { kept, removed };
+}