azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/rotation/condMetricPicker.ts

@@ -0,0 +1,379 @@
+// Rotation "if" catalog, split into Common and Situational so the metric list stays scannable.
+// Common is everyday gates; Situational is PvP, CC subtypes, class reacts and companion knobs.
+import { SHAPESHIFT_FORM } from '../../data/schema.ts';
+import type { CondMetric, CondOp, CondSubject } from './types.ts';
+
+/** Sensible starting comparison when the player switches a condition to this metric. */
+export const COND_METRIC_DEFAULTS: Record<CondMetric, { op: CondOp; value: number; subject?: CondSubject; ref?: number }> = {
+  healthPct: { op: '<', value: 50 },
+  powerPct: { op: '<', value: 20 },
+  manaPct: { op: '<', value: 20 },
+  level: { op: '>=', value: 1 },
+  alive: { op: '==', value: 1 },
+  buffPresent: { op: '==', value: 0 },
+  debuffPresent: { op: '==', value: 0, subject: 'target' },
+  buffStacks: { op: '<', value: 5 },
+  debuffStacks: { op: '<', value: 5, subject: 'target' },
+  // 3 s is the refresh window a HoT wants: absent reads 0 and so satisfies the same row.
+  buffRemainingMs: { op: '<', value: 3000 },
+  debuffRemainingMs: { op: '<', value: 3000, subject: 'target' },
+  canAfford: { op: '==', value: 0 },
+  castingPresent: { op: '==', value: 1, subject: 'target' },
+  // ref 5 is 'polymorph' in DIMINISHING_GROUP_ORDER; step 0 is full duration, so the seeded
+  // row reads "the target's sheep track is fresh" - the question a CC row actually asks.
+  drLevel: { op: '==', value: 0, subject: 'target', ref: 5 },
+  castingSchool: { op: '==', value: 2, subject: 'target' },
+  castingSpellId: { op: '==', value: 0, subject: 'target' },
+  castingIsHeal: { op: '==', value: 1, subject: 'target' },
+  dodgedRecently: { op: '==', value: 1, subject: 'target' },
+  defenseReactRecently: { op: '==', value: 1, subject: 'self' },
+  hunterParryRecently: { op: '==', value: 1, subject: 'self' },
+  controlled: { op: '==', value: 1, subject: 'self' },
+  rooted: { op: '==', value: 1, subject: 'self' },
+  feared: { op: '==', value: 0, subject: 'target' },
+  stunned: { op: '==', value: 1, subject: 'self' },
+  snared: { op: '==', value: 1, subject: 'self' },
+  silenced: { op: '==', value: 1, subject: 'self' },
+  hasFlag: { op: '==', value: 1, subject: 'self' },
+  allyHasFlag: { op: '==', value: 1 },
+  enemyHasFlag: { op: '==', value: 1 },
+  isFlagCarrier: { op: '==', value: 1, subject: 'target' },
+  isHealer: { op: '==', value: 1, subject: 'target' },
+  isCaster: { op: '==', value: 1, subject: 'target' },
+  isHunter: { op: '==', value: 1, subject: 'self' },
+  classId: { op: '==', value: 8, subject: 'target' },
+  enemiesWithinYd: { op: '>=', value: 3, ref: 10 },
+  alliesWithinYd: { op: '>=', value: 2, ref: 10 },
+  healersWithinYd: { op: '==', value: 0, ref: 30 },
+  enemyHealersWithinYd: { op: '>=', value: 1, ref: 30 },
+  enemyCastingOnAlly: { op: '==', value: 1 },
+  enemyCastingOnSelf: { op: '==', value: 1 },
+  objectiveContested: { op: '==', value: 1 },
+  objectiveOwnedByUs: { op: '==', value: 1 },
+  objectiveDistanceYd: { op: '<', value: 20 },
+  inMelee: { op: '==', value: 1, subject: 'target' },
+  charmed: { op: '==', value: 1, subject: 'target' },
+  charmedHostileCount: { op: '>=', value: 1 },
+  itemCount: { op: '<', value: 5 },
+  itemEquipped: { op: '==', value: 1 },
+  petHappiness: { op: '<', value: 60, subject: 'pet' },
+  combatTimeMs: { op: '>', value: 5000 }, inCombat: { op: '==', value: 0 },
+  timeToDieMs: { op: '<', value: 6000, subject: 'target' },
+  comboPoints: { op: '>=', value: 4 },
+  enemyCount: { op: '>=', value: 2 },
+  allyLowestHpPct: { op: '<', value: 75 },
+  allyLowestBuffPresent: { op: '==', value: 0 },
+  alliesBelowHpCount: { op: '>=', value: 2, ref: 80 },
+  nearbyAlliesBelowHpCount: { op: '>=', value: 2, ref: 15 },
+  meleeAllyCount: { op: '>=', value: 2 },
+  deadAllyCount: { op: '>=', value: 1 },
+  hasAggro: { op: '==', value: 1 },
+  allyHasAggro: { op: '==', value: 1 },
+  aggroHolderDebuffPresent: { op: '==', value: 1, subject: 'target' },
+  aggroHolderDebuffStacks: { op: '>=', value: 3, subject: 'target' },
+  allyAuraPresent: { op: '==', value: 1 },
+  allyAuraStacks: { op: '>=', value: 1 },
+  targetAttackingMe: { op: '==', value: 0 },
+  aoeMode: { op: '!=', value: 2 },
+  offHealAllowed: { op: '==', value: 1 },
+  healerPowerPct: { op: '<', value: 5 },
+  partySeats: { op: '<=', value: 1 },
+  formId: { op: '!=', value: SHAPESHIFT_FORM.CAT },
+  totemPresent: { op: '==', value: 0, ref: 0 },
+  weaponImbuePresent: { op: '==', value: 0, ref: 2 },
+  creatureTypeMask: { op: '==', value: 1, subject: 'target', ref: 32 },
+  dispellablePresent: { op: '==', value: 1, subject: 'self', ref: 1 },
+  hazardProximityYd: { op: '<=', value: 0 },
+  targetDistanceYd: { op: '<=', value: 20 },
+  creatureDistanceYd: { op: '<=', value: 20, ref: 0 },
+  allyWithoutAuraNearYd: { op: '<=', value: 13 },
+  inTargetCone: { op: '==', value: 1 },
+  isMainTank: { op: '==', value: 1 },
+  isOffTank: { op: '==', value: 1 },
+  myJob: { op: '==', value: 3 },
+  myCamp: { op: '==', value: 1 },
+  assignedHealSubgroup: { op: '==', value: 0 },
+};
+
+export type CondMetricBucket = 'common' | 'situational';
+export type CondMetricFilter = CondMetricBucket | 'all';
+
+export const COND_METRIC_BUCKET_ORDER: readonly CondMetricBucket[] = ['common', 'situational'];
+
+export const COND_METRIC_BUCKET_LABEL: Record<CondMetricBucket, string> = {
+  common: 'Common',
+  situational: 'Situational',
+};
+
+export const COND_METRIC_FILTER_LABEL: Record<CondMetricFilter, string> = {
+  common: 'Common',
+  situational: 'Situational',
+  all: 'All',
+};
+
+/** Dropdown / picker name for each if. Exhaustive on CondMetric. */
+export const COND_METRIC_LABEL: Record<CondMetric, string> = {
+  healthPct: 'health %', powerPct: 'mana / power %', level: 'level', alive: 'alive',
+  manaPct: 'mana % (never rage / energy)',
+  buffPresent: 'has buff', debuffPresent: 'has debuff', itemCount: 'items in bags',
+  itemEquipped: 'item equipped',
+  buffStacks: 'buff stacks', debuffStacks: 'debuff stacks',
+  buffRemainingMs: 'buff time left (ms)', debuffRemainingMs: 'debuff time left (ms)',
+  canAfford: 'can pay for spell',
+  castingPresent: 'is casting', castingSchool: 'cast school', castingIsHeal: 'cast is a heal',
+  drLevel: 'diminishing step',
+  castingSpellId: 'casting spell id',
+  dodgedRecently: 'dodged recently',
+  defenseReactRecently: 'defense react (dodge/parry/block)',
+  hunterParryRecently: 'parried recently',
+  inMelee: 'in melee',
+  charmed: 'charmed / possessed',
+  petHappiness: 'pet happiness %', combatTimeMs: 'fight time (ms)', inCombat: 'in combat (this unit)',
+  controlled: 'under crowd control', rooted: 'rooted', feared: 'feared',
+  stunned: 'stunned', snared: 'snared', silenced: 'silenced',
+  hasFlag: 'carrying the flag', allyHasFlag: 'our team has the flag',
+  enemyHasFlag: 'they have our flag', isFlagCarrier: 'is the flag carrier',
+  isHealer: 'is a healer', isCaster: 'is a caster', isHunter: 'is a hunter',
+  classId: 'class',
+  enemiesWithinYd: 'enemies within N yards (self=at me, target=at focus)', alliesWithinYd: 'allies within N yards',
+  healersWithinYd: 'our healers within N yards', enemyHealersWithinYd: 'their healers within N yards',
+  enemyCastingOnAlly: 'an enemy is casting at an ally',
+  enemyCastingOnSelf: 'an enemy is casting at you',
+  objectiveContested: 'objective contested', objectiveOwnedByUs: 'objective is ours',
+  objectiveDistanceYd: 'yards to objective',
+  comboPoints: 'combo points', enemyCount: 'living enemies', formId: 'form / stance',
+  timeToDieMs: "time until it dies (this fight's rate)",
+  allyLowestHpPct: 'most-hurt ally health %',
+  allyLowestBuffPresent: 'most-hurt ally has buff',
+  alliesBelowHpCount: 'hurt allies (count)',
+  nearbyAlliesBelowHpCount: 'hurt allies in range (count)',
+  meleeAllyCount: 'melee allies (count)',
+  deadAllyCount: 'dead allies (count)',
+  hasAggro: 'has aggro (any enemy)',
+  allyHasAggro: 'an ally has aggro (any enemy)',
+  aggroHolderDebuffPresent: 'tank has debuff',
+  aggroHolderDebuffStacks: 'tank debuff stacks',
+  allyAuraPresent: 'anyone has aura',
+  allyAuraStacks: 'anyone aura stacks',
+  targetAttackingMe: 'target attacking me',
+  charmedHostileCount: 'charmed hostiles (possessed allies)',
+  aoeMode: 'AoE mode',
+  offHealAllowed: 'off-heal allowed',
+  healerPowerPct: "party healer's mana %",
+  partySeats: 'party size (1 = solo)',
+  totemPresent: 'totem slot',
+  weaponImbuePresent: 'weapon imbue',
+  creatureTypeMask: 'creature type (Undead/Demon…)',
+  dispellablePresent: 'dispellable aura present',
+  hazardProximityYd: 'yards to nearest ground hazard',
+  targetDistanceYd: 'yards to current target',
+  creatureDistanceYd: 'yards to creature entry',
+  allyWithoutAuraNearYd: 'yards to nearest ally without this aura',
+  inTargetCone: "in the target's frontal cone",
+  isMainTank: 'is main tank',
+  isOffTank: 'is off-tank',
+  myJob: 'raid job (0 dps / 1 heal / 2 OT / 3 MT)',
+  myCamp: 'raid camp (0 none / 1 a / 2 b)',
+  assignedHealSubgroup: 'assigned heal subgroup',
+};
+
+export const COND_METRIC_BUCKET: Record<CondMetric, CondMetricBucket> = {
+  healthPct: 'common',
+  powerPct: 'common',
+  manaPct: 'common',
+  buffPresent: 'common',
+  debuffPresent: 'common',
+  buffStacks: 'common',
+  debuffStacks: 'common',
+  buffRemainingMs: 'common',
+  debuffRemainingMs: 'common',
+  canAfford: 'common',
+  castingPresent: 'common',
+  drLevel: 'situational',
+  comboPoints: 'common',
+  timeToDieMs: 'common',
+  enemyCount: 'common',
+  formId: 'common',
+  inMelee: 'common',
+  hasAggro: 'common',
+  allyHasAggro: 'situational',
+  aggroHolderDebuffPresent: 'situational',
+  aggroHolderDebuffStacks: 'situational',
+  allyAuraPresent: 'situational',
+  allyAuraStacks: 'situational',
+  targetAttackingMe: 'common',
+  allyLowestHpPct: 'common',
+  allyLowestBuffPresent: 'common',
+  alliesBelowHpCount: 'common',
+  nearbyAlliesBelowHpCount: 'common',
+  dispellablePresent: 'common',
+  inCombat: 'common',
+  itemCount: 'common',
+  itemEquipped: 'common',
+  castingSchool: 'situational',
+  castingSpellId: 'situational',
+  castingIsHeal: 'situational',
+  dodgedRecently: 'situational',
+  defenseReactRecently: 'situational',
+  charmed: 'situational',
+  charmedHostileCount: 'situational',
+  totemPresent: 'situational',
+  weaponImbuePresent: 'situational',
+  petHappiness: 'situational',
+  creatureTypeMask: 'situational',
+  aoeMode: 'situational',
+  offHealAllowed: 'situational',
+  healerPowerPct: 'situational',
+  partySeats: 'situational',
+  meleeAllyCount: 'situational',
+  deadAllyCount: 'situational',
+  controlled: 'situational',
+  rooted: 'situational',
+  feared: 'situational',
+  stunned: 'situational',
+  snared: 'situational',
+  silenced: 'situational',
+  hasFlag: 'situational',
+  allyHasFlag: 'situational',
+  enemyHasFlag: 'situational',
+  isFlagCarrier: 'situational',
+  isHealer: 'situational',
+  isCaster: 'situational',
+  isHunter: 'situational',
+  classId: 'situational',
+  enemiesWithinYd: 'situational',
+  alliesWithinYd: 'situational',
+  healersWithinYd: 'situational',
+  enemyHealersWithinYd: 'situational',
+  enemyCastingOnAlly: 'situational',
+  enemyCastingOnSelf: 'situational',
+  objectiveContested: 'situational',
+  objectiveOwnedByUs: 'situational',
+  objectiveDistanceYd: 'situational',
+  hazardProximityYd: 'situational',
+  targetDistanceYd: 'situational',
+  creatureDistanceYd: 'situational',
+  allyWithoutAuraNearYd: 'situational',
+  inTargetCone: 'situational',
+  hunterParryRecently: 'situational',
+  alive: 'situational',
+  level: 'situational',
+  combatTimeMs: 'situational',
+  isMainTank: 'situational',
+  isOffTank: 'situational',
+  myJob: 'situational',
+  myCamp: 'situational',
+  assignedHealSubgroup: 'situational',
+};
+
+// Scan order inside a bucket (and for All: Common first, then Situational). `as const` + Missing check so a
+// new CondMetric cannot ship unlisted.
+const COND_METRIC_ORDER = [
+  'healthPct', 'powerPct', 'manaPct', 'buffPresent', 'debuffPresent', 'buffStacks', 'debuffStacks',
+  'buffRemainingMs', 'debuffRemainingMs', 'canAfford',
+  'castingPresent', 'comboPoints', 'drLevel', 'enemyCount', 'formId', 'inMelee',
+  'hasAggro', 'allyHasAggro', 'targetAttackingMe', 'aggroHolderDebuffPresent', 'aggroHolderDebuffStacks',
+  'allyAuraPresent', 'allyAuraStacks',
+  'allyLowestHpPct', 'allyLowestBuffPresent', 'alliesBelowHpCount', 'nearbyAlliesBelowHpCount',
+  'dispellablePresent', 'inCombat', 'itemCount', 'itemEquipped',
+  'castingSchool', 'castingSpellId', 'castingIsHeal', 'dodgedRecently', 'defenseReactRecently',
+  'hunterParryRecently',
+  'controlled', 'rooted', 'feared', 'stunned', 'snared', 'silenced',
+  'totemPresent', 'weaponImbuePresent', 'petHappiness', 'creatureTypeMask',
+  'aoeMode', 'offHealAllowed', 'healerPowerPct', 'partySeats', 'meleeAllyCount', 'deadAllyCount',
+  'charmed', 'charmedHostileCount',
+  'hasFlag', 'allyHasFlag', 'enemyHasFlag', 'isFlagCarrier',
+  'isHealer', 'isCaster', 'isHunter', 'classId',
+  'enemiesWithinYd', 'alliesWithinYd', 'healersWithinYd', 'enemyHealersWithinYd',
+  'enemyCastingOnAlly',
+  'enemyCastingOnSelf',
+  'objectiveContested', 'objectiveOwnedByUs', 'objectiveDistanceYd',
+  'hazardProximityYd',
+  'targetDistanceYd',
+  'creatureDistanceYd',
+  'allyWithoutAuraNearYd',
+  'inTargetCone',
+  'isMainTank', 'isOffTank', 'myJob', 'myCamp', 'assignedHealSubgroup',
+  'alive', 'level', 'combatTimeMs',
+] as const satisfies readonly CondMetric[];
+
+type MissingCondMetric = Exclude<CondMetric, (typeof COND_METRIC_ORDER)[number]>;
+const _allMetricsListed: MissingCondMetric extends never ? true : { missing: MissingCondMetric } = true;
+void _allMetricsListed;
+
+export const ALL_COND_METRICS: CondMetric[] = [...COND_METRIC_ORDER];
+
+export function condMetricBucket(metric: CondMetric): CondMetricBucket {
+  return COND_METRIC_BUCKET[metric];
+}
+
+export function metricsInBucket(bucket: CondMetricBucket): CondMetric[] {
+  return ALL_COND_METRICS.filter((m) => COND_METRIC_BUCKET[m] === bucket);
+}
+
+// Words the search accepts that the LABEL does not carry: "team" / "friendly" / "party" matched
+// nothing, and a plain subject metric can now be asked about an ally, which no label says.
+const COND_METRIC_ALIAS: Partial<Record<CondMetric, string>> = {
+  healthPct: 'ally team friendly party raid mate',
+  powerPct: 'ally team friendly party mate',
+  manaPct: 'ally team friendly party mate',
+  buffPresent: 'ally team friendly party mate aura',
+  debuffPresent: 'ally team friendly party mate aura',
+  buffRemainingMs: 'ally team friendly party mate',
+  debuffRemainingMs: 'ally team friendly party mate',
+  timeToDieMs: 'ally team friendly party mate dying',
+  isHealer: 'ally team friendly party role',
+  classId: 'ally team friendly party mage priest warrior',
+  alive: 'ally team friendly party dead',
+  allyLowestHpPct: 'team friendly party raid mate hurt triage',
+  allyLowestBuffPresent: 'team friendly party raid mate hot triage',
+  alliesBelowHpCount: 'team friendly party raid mates',
+  nearbyAlliesBelowHpCount: 'team friendly party raid mates',
+  meleeAllyCount: 'team friendly party raid mates',
+  deadAllyCount: 'team friendly party raid mates rez',
+  alliesWithinYd: 'team friendly party raid mates',
+  healersWithinYd: 'team friendly party raid mates',
+  allyAuraPresent: 'ally team friendly party raid mates',
+  allyAuraStacks: 'ally team friendly party raid mates',
+  allyWithoutAuraNearYd: 'team friendly party raid mates',
+  allyHasFlag: 'team friendly party mates',
+  enemyCastingOnAlly: 'team friendly party mate peel',
+  enemyCastingOnSelf: 'self peel grounding totem incoming cast',
+  healerPowerPct: 'team friendly party mana',
+  partySeats: 'team friendly raid solo group size',
+  aggroHolderDebuffPresent: 'tank team friendly party swap',
+  aggroHolderDebuffStacks: 'tank team friendly party swap',
+};
+
+/** Everything a query may match on one metric: its label plus the words above. */
+function metricSearchText(m: CondMetric): string {
+  const alias = COND_METRIC_ALIAS[m];
+  return alias ? `${COND_METRIC_LABEL[m].toLowerCase()} ${alias}` : COND_METRIC_LABEL[m].toLowerCase();
+}
+
+// Metrics to show for a filter chip. `current` stays in the list so a switch to the other bucket cannot
+// blank the open condition's select.
+export function metricsForFilter(
+  filter: CondMetricFilter,
+  current?: CondMetric,
+  query = '',
+): CondMetric[] {
+  const q = query.trim().toLowerCase();
+  // A TYPED query searches the whole catalog: a search that only reaches the open chip's half is
+  // how "ally" on the Common chip returned "No matches" while six ally rows sat in Situational.
+  const pool = filter === 'all' || q ? ALL_COND_METRICS : metricsInBucket(filter);
+  const out = pool.filter((m) => !q || metricSearchText(m).includes(q));
+  if (current != null && !out.includes(current)) out.unshift(current);
+  return out;
+}
+
+export function metricOptgroups(
+  metrics: readonly CondMetric[],
+): { bucket: CondMetricBucket; label: string; metrics: CondMetric[] }[] {
+  const groups: { bucket: CondMetricBucket; label: string; metrics: CondMetric[] }[] = [];
+  for (const bucket of COND_METRIC_BUCKET_ORDER) {
+    const list = metrics.filter((m) => COND_METRIC_BUCKET[m] === bucket);
+    if (list.length) groups.push({ bucket, label: COND_METRIC_BUCKET_LABEL[bucket], metrics: list });
+  }
+  return groups;
+}

package/src/domain/rotation/consumables.ts

@@ -0,0 +1,242 @@
+// In-combat consumable rows for the default rotation. The row is emitted from the CATALOG, gated on
+// itemCount, so buying a potion needs no rebuild: RotationAutoSig has no inventory term.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef, PowerType, SpellDef } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import { meetsItemSkillGate } from '../character/buildCombatant.ts';
+import { classPowerType } from '../core/ids.ts';
+import { powerTypeName } from '../../engine/spells/effects.ts';
+import { consumableFamilyOfEntry, restoredPowerTypeIndex } from '../items/consumableFamily.ts';
+import { hasHostilePayload } from '../items/onUsePayload.ts';
+import { resolveCombatSpell } from '../../engine/spells/interpreter/index.ts';
+import { ccBreakGateConditions, cond } from './classify.ts';
+import { DEFAULT_THRESHOLDS, type CondMetric, type Condition, type RotationPhase } from './types.ts';
+
+// ITEM_CLASS_CONSUMABLE — the gate separating a potion from an Engineering device with the same
+// restore_health shape. Mechanical Repair Kit is class 7 at requiredLevel 0 and was offered first.
+const ITEM_CLASS_CONSUMABLE = 0;
+
+// ITEM_SUBCLASS_POTION. Ranking by raw restore amount alone reaches past the potion ladder: at 20
+// the best class-0 heal is Lily Root, not a Healing Potion. Healthstones are subclass 6.
+const ITEM_SUBCLASS_POTION = 3;
+
+export interface CombatConsumable {
+  entry: number;
+  name: string;
+  /** Rank ladder this row rides (domain/items/consumableFamily.ts). Absent ⇒ a lone entry. */
+  family?: string;
+  /** 'health' fills HP; otherwise the power this item restores. */
+  kind: 'health' | PowerType;
+  /** Best rolled amount, used only to rank candidates. */
+  amount: number;
+}
+
+/** Which power a restore_power consumable fills. Cite: consumableFamily.restoredPowerTypeIndex. */
+function restoredPowerType(it: ItemDef, ds: DataStore): PowerType | null {
+  const idx = restoredPowerTypeIndex(it, ds);
+  return idx == null ? null : powerTypeName(idx);
+}
+
+// The best level-legal in-combat health potion and power potion for this character, straight off the
+// catalog. One of each — a list of every rank would bury the rest of the rotation.
+export function bestCombatConsumables(char: Character, ds: DataStore): CombatConsumable[] {
+  const want = classPowerType(char.cls);
+  let bestHealth: CombatConsumable | null = null;
+  let bestPower: CombatConsumable | null = null;
+
+  for (const it of ds.items()) {
+    const u = it.useInCombat;
+    if (!u) continue;
+    if (u.effect !== 'restore_health' && u.effect !== 'restore_power') continue;
+    if (it.notObtainable) continue;
+    if ((it.itemClass ?? -1) !== ITEM_CLASS_CONSUMABLE) continue;
+    if ((it.itemSubclass ?? -1) !== ITEM_SUBCLASS_POTION) continue;
+    // Engineering devices are the only use-gated rows; a potion is 0/0 and stays ungated.
+    // Cite: Player.cpp CanUseItem ~9756; buildCombatant.meetsItemSkillGate.
+    if (!meetsItemSkillGate(char, it)) continue;
+    // Permanent on-use gear is only usable while equipped — not a carried consumable.
+    if (it.slot != null) continue;
+    // ItemTemplate.RequiredLevel is the combat-kit floor (same one combatItems uses).
+    // Cite: Player.cpp:9797 CanUseItem.
+    if ((it.requiredLevel | 0) > char.level) continue;
+    const amount = Math.max(u.min ?? 0, u.max ?? 0);
+    if (amount <= 0) continue;
+
+    if (u.effect === 'restore_health') {
+      if (!bestHealth || amount > bestHealth.amount) {
+        bestHealth = { entry: it.entry, name: it.name, kind: 'health', amount };
+      }
+      continue;
+    }
+    if (restoredPowerType(it, ds) !== want) continue;
+    if (!bestPower || amount > bestPower.amount) {
+      bestPower = { entry: it.entry, name: it.name, kind: want, amount };
+    }
+  }
+
+  // Stamp the ladder so the row is "Healing Potion", not the one rung this level happens to
+  // top out at — the evaluator then drinks whatever rung is in the bag.
+  const withFamily = (c: CombatConsumable): CombatConsumable => {
+    const family = consumableFamilyOfEntry(c.entry, ds);
+    return family ? { ...c, family } : c;
+  };
+  const out: CombatConsumable[] = [];
+  if (bestHealth) out.push(withFamily(bestHealth));
+  if (bestPower) out.push(withFamily(bestPower));
+  return out;
+}
+
+// Gate for a carried consumable: you have one, and you need it. itemCount is what makes the row
+// inert rather than wrong while the bag is empty.
+export function combatConsumableConditions(c: CombatConsumable, hpBand?: number): Condition[] {
+  // A family row needs no itemCount gate and must not carry one: the gate names ONE entry, so a
+  // Major Healing Potion row was dead for a player carrying Greater. The ladder resolve covers it.
+  const need = c.family ? null : cond('self', 'itemCount', '>=', 1, c.entry);
+  if (c.kind === 'health') {
+    const low = cond('self', 'healthPct', '<', hpBand ?? DEFAULT_THRESHOLDS.potionLowPct);
+    return need ? [need, low] : [low];
+  }
+  // `manaPct`, never `powerPct`: a druid in Cat Form reads ENERGY on powerPct, so a mana potion row
+  // gated there drank on an empty energy bar — which is every third GCD — and never on empty mana.
+  // Rage and energy restores keep powerPct, since that IS the bar they fill.
+  const bar: CondMetric = c.kind === 'mana' ? 'manaPct' : 'powerPct';
+  const low = cond('self', bar, '<', DEFAULT_THRESHOLDS.manaRestoreLowPct);
+  // Potions share item category 4 (itemUseCooldown.ts), so a mana potion locks the health potion out
+  // for the whole category cooldown. Never spend that lock while the health band is live.
+  const safe = cond('self', 'healthPct', '>', DEFAULT_THRESHOLDS.manaRestoreSafeHpPct);
+  return need ? [need, low, safe] : [low, safe];
+}
+
+// buildCombatant.ts:379/473 files a cure, a summon, a shield, a sprint, a CC break and a damage
+// coat under one `friendly_cast` kind, and all six were gated `self.controlled == 1`.
+
+/** A speed aura this long is a carried buff (Swiftness of Zanza 2h), not a sprint (15s). */
+const SPEED_KEEP_UP_MIN_MS = 600_000;
+/** An immunity this short is a panic button, not something you hold up. Invulnerability is 6s. */
+const PANIC_IMMUNITY_MAX_MS = 15_000;
+/** enemiesWithinYd falls back to this when the trigger's radius is not baked. Cite: types.ts. */
+const DEFAULT_PBAOE_YD = 10;
+/** SharedDefines.h DispelType: MAGIC 1, CURSE 2, DISEASE 3, POISON 4, ALL 7. */
+const DISPEL_ALL = 7;
+const CURABLE_DISPEL_TYPES = [1, 2, 3, 4] as const;
+
+export interface ItemGate {
+  conditions: Condition[];
+  phase: RotationPhase;
+  /** Seed the row switched OFF: it spends the stack for movement, a body, or a flee. */
+  autoOff?: boolean;
+  /** Seed OFF even when worn and reusable: the payload HARMS the user (Skull of Impending Doom 5024). */
+  neverAuto?: boolean;
+}
+
+/** Every damaging spell an on-use aura triggers, so a PBAoE coat can be gated on bodies in range. */
+function triggeredDamageRadiusYd(sp: SpellDef, ds: DataStore | undefined): number | null {
+  if (!ds) return null;
+  for (const e of sp.effects) {
+    const id = e.kind === 'proc_trigger_spell' ? Number(e.triggerSpellId) || 0
+      : e.kind === 'trigger_spell' ? Number(e.spellId) || 0 : 0;
+    if (!id) continue;
+    const trig = ds.spell(id);
+    if (!trig) continue;
+    const te = trig.effects?.length ? trig.effects : resolveCombatSpell(trig).effects;
+    const dmg = (te ?? []).some((t) => t.kind === 'direct_damage' || t.kind === 'dot');
+    if (!dmg) continue;
+    if ((trig.rangeMax ?? 0) > 0) continue; // aimed at a target, not a shield around us
+    return trig.radiusYd ?? DEFAULT_PBAOE_YD;
+  }
+  return null;
+}
+
+// What a `friendly_cast` item is FOR, read off the spell it casts. Each branch cites the shape it
+// matches; the fallback is the keep-up gate an elixir already gets (build.ts apply_buff).
+export function friendlyCastItemGate(
+  sp: SpellDef,
+  spellId: number,
+  ds?: DataStore,
+): ItemGate {
+  const upAlready = cond('self', 'buffPresent', '==', 0, spellId);
+  const fighting = cond('self', 'inCombat', '==', 1);
+
+  // 1. Free Action / Living Action Potion: a pure mechanic_immunity payload, the one shape the old
+  // catch-all was written for. Cite: classify.ts:848 ccBreakGateConditions.
+  if (ccBreakGateConditions(sp).length > 0) {
+    return { conditions: [cond('self', 'controlled', '==', 1)], phase: 'combat' };
+  }
+  // 2. Cowardly Flight Potion 6614 fears the DRINKER. Never a row that fires on its own.
+  if (sp.effects.some((e) => e.kind === 'cc')) {
+    return {
+      conditions: [cond('self', 'healthPct', '<', DEFAULT_THRESHOLDS.emergencyDefensivePct)],
+      phase: 'recovery',
+      autoOff: true,
+    };
+  }
+  // 3. A cure in a bottle: the cure SPELL's gate, always on self, one OR group per category it
+  // clears (Purification Potion answers four). Cite: classify.ts:626 dispelGateConditions.
+  const cures = new Set<number>();
+  for (const e of sp.effects) {
+    if (e.kind !== 'dispel') continue;
+    // DISPEL_ALL 7 clears any of the four, and no debuff is ever filed under 7 itself.
+    if (e.dispelType === DISPEL_ALL) for (const c of CURABLE_DISPEL_TYPES) cures.add(c);
+    else cures.add(e.dispelType);
+  }
+  if (cures.size && !sp.effects.some((e) => e.kind === 'direct_damage')) {
+    const conditions = [...cures].sort((a, b) => a - b).map((cat, i) => ({
+      ...cond('self', 'dispellablePresent', '==', 1, cat),
+      ...(i > 0 ? { join: 'or' as const } : {}),
+    }));
+    return { conditions, phase: 'combat' };
+  }
+  // 4. A device that drops a body (Target Dummy, Explosive Sheep, Dog Whistle). It spends the
+  // stack, so it seeds off for the same reason a grenade does (companionRotation.ts:330).
+  if (sp.effects.some((e) => e.kind === 'summon_guardian')) {
+    return { conditions: [fighting], phase: 'combat', autoOff: true };
+  }
+  // 5. Limited Invulnerability Potion (6s) / Light of Elune (10s): a panic button, on the same
+  // health band every self-defensive cooldown uses. Cite: build.ts isSelfDefensiveSpell inject.
+  const shortImmunity = sp.effects.some((e) =>
+    (e.kind === 'school_immunity' || e.kind === 'damage_immunity')
+    && (e.durationMs ?? 0) > 0 && (e.durationMs ?? 0) <= PANIC_IMMUNITY_MAX_MS);
+  if (shortImmunity) {
+    return {
+      conditions: [cond('self', 'healthPct', '<', DEFAULT_THRESHOLDS.emergencyDefensivePct)],
+      phase: 'recovery',
+    };
+  }
+  // 6. Protection potions and the engineering deflectors: a school shield held like an elixir.
+  // Phase combat is what keeps it off the OOC path (evaluate.ts:1088 reads buffs and pets only).
+  if (sp.effects.some((e) => e.kind === 'school_absorb')) {
+    return { conditions: [upAlready], phase: 'combat' };
+  }
+  // 7. Resistance potions, elixirs and Flask of Chromatic Resistance: a plain keep-up.
+  if (sp.effects.some((e) => e.kind === 'resist' || e.kind === 'reflect')) {
+    return { conditions: [upAlready], phase: 'buffs' };
+  }
+  // 8. Speed. A 2h Zanza buff is a keep-up; a 15s Swiftness Potion answers a snare and is seeded
+  // off, since no PvE rotation should spend one (bgConsumes.ts drives the BG use).
+  const speed = sp.effects.find((e) => e.kind === 'speed');
+  if (speed) {
+    if ((speed.durationMs ?? 0) >= SPEED_KEEP_UP_MIN_MS) {
+      return { conditions: [upAlready], phase: 'buffs' };
+    }
+    // Flee 5024 rides a self dot and a mana drain beside its +60%: a row that fires on its own
+    // bleeds the user every 2 s. Off, worn or not; an author gates it by hand (operator, 2026-09-10).
+    const harmsTheUser = hasHostilePayload(sp.effects);
+    return {
+      conditions: [cond('self', 'snared', '==', 1)], phase: 'combat', autoOff: true,
+      ...(harmsTheUser ? { neverAuto: true } : {}),
+    };
+  }
+  // 9. Oil of Immolation 11350 ticks 11351 into a 5 yd disc, and Dragonbreath Chili into 10. The
+  // coat pays nothing with an empty disc, so the bodies in range are the gate.
+  const yd = triggeredDamageRadiusYd(sp, ds);
+  if (yd != null) {
+    return {
+      conditions: [upAlready, cond('self', 'enemiesWithinYd', '>=', 1, yd)],
+      phase: 'combat',
+    };
+  }
+  // 10. Everything else riding a whole SpellDef: Restorative Potion's periodic cleanse, Glowing
+  // Wax Stick, a festival brew. The keep-up gate an elixir already gets.
+  return { conditions: [upAlready], phase: 'combat' };
+}