azeroth-shell 0.0.0-stage → 0.1.1

package/src/domain/professions/characterEnchants.ts

@@ -0,0 +1,176 @@
+// Temp weapon enchant (TEMP_ENCHANTMENT_SLOT) selectors + mutations.
+// Extracted from character.ts (Wave 1 S3 barrel split). Pure move — no behavior change.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Character, TempEnchantHand, TempEnchantState, TempEnchantMap, EquippedMap } from '../character/character.ts';
+import { equippedInstance, hasIdentity } from '../items/itemInstance.ts';
+import { withTempEnchant } from './enchantApply.ts';
+import { pruneExpiredAuras, getActiveBuffIds } from '../character/characterStats.ts';
+
+// True when a spell applies a temporary weapon enchant (imbue or poison). Thin bake rows ship
+// effects:[] with rawEffects 54 only, and without that check a prior imbue is never dropped.
+export function isWeaponImbueSpell(spell: {
+  effects?: readonly { kind: string }[];
+  rawEffects?: readonly { effect?: number }[];
+} | null | undefined): boolean {
+  if (!spell) return false;
+  if (spell.effects?.some((e) => e.kind === 'weapon_imbue')) return true;
+  // SPELL_EFFECT_ENCHANT_ITEM_TEMPORARY = 54
+  return !!spell.rawEffects?.some((e) => (e.effect ?? 0) === 54);
+}
+
+// Hunter Aspects — spell_group 10, rule UNIQUE_PER_CASTER. The bake's exclusionGroup and
+// spellGroupId are preferred; the name prefix is last-resort for fixtures missing both.
+export function isHunterAspectSpell(
+  spell: { name?: string; exclusionGroup?: number; spellGroupId?: number } | null | undefined,
+): boolean {
+  if (!spell) return false;
+  if (spell.exclusionGroup === 10 || spell.spellGroupId === 10) return true;
+  // Fallback when bake fields absent (legacy fixtures).
+  const n = spell.name;
+  return typeof n === 'string' && n.startsWith('Aspect of the ');
+}
+
+// Mutual-exclusion group id for UNIQUE_PER_CASTER / EXCLUSIVE spell groups (Aspects = 10, Mage Armors = 13,
+// …). Prefers exclusionGroup, then spellGroupId.
+export function spellExclusionGroup(
+  spell: { exclusionGroup?: number; spellGroupId?: number } | null | undefined,
+): number | null {
+  if (!spell) return null;
+  if (spell.exclusionGroup != null && spell.exclusionGroup > 0) return spell.exclusionGroup;
+  if (spell.spellGroupId != null && spell.spellGroupId > 0) return spell.spellGroupId;
+  return null;
+}
+
+// spell_group Rule 2 (UNIQUE_PER_CASTER): only the SAME caster's row is replaced, so two paladins
+// leave two Blessings on one body. Rule 1 (UNIQUE) replaces whoever cast it. Cite: SpellStacking.h:31
+// SpellGroupRule; Unit.cpp:4973 personal = rule == UNIQUE_PER_CASTER, :5021 RemoveAurasByCasterSpell.
+// Ids off src_spell_group Rule=2: 6 Judgement, 7 Blessing, 8 Aura, 9 Sting, 10 Aspect, 12 Curse,
+// 21 Alcohol. The bake collapses Rule>=1 to one flag, so the rule itself is read here.
+const PER_CASTER_EXCLUSION_GROUPS: ReadonlySet<number> = new Set([6, 7, 8, 9, 10, 12, 21]);
+
+/** True when this spell's exclusion group only replaces the same caster's own aura. */
+export function exclusionIsPerCaster(
+  spell: { exclusionGroup?: number; spellGroupId?: number } | null | undefined,
+): boolean {
+  const g = spellExclusionGroup(spell);
+  return g != null && PER_CASTER_EXCLUSION_GROUPS.has(g);
+}
+
+// Apply a temporary weapon enchant to one hand, replacing any prior temp enchant on THAT HAND
+// only. Also writes ItemInstance.tempEnchant so identity travels with the item on unequip.
+export function applyTempEnchant(
+  char: Character,
+  hand: TempEnchantHand,
+  state: TempEnchantState,
+  now: number = Date.now(),
+  ds?: DataStore,
+): Character {
+  const prev = char.tempEnchants?.[hand];
+  const otherHand: TempEnchantHand = hand === 'mainhand' ? 'offhand' : 'mainhand';
+  const other = char.tempEnchants?.[otherHand];
+  const tempEnchants: TempEnchantMap = { ...(char.tempEnchants ?? {}) };
+  tempEnchants[hand] = state;
+
+  // Mirror as an aura for buffPresent and the UI, stripping only this hand's prior apply and equip
+  // auras — never every imbue, which lied "one imbue" while both hands stayed coated.
+  let auras = pruneExpiredAuras(char.activeAuras, now).slice();
+  auras = auras.filter((a) => {
+    if (prev && a.spellId === prev.spellId) {
+      // Other hand still carries the same apply spell → keep one chip.
+      if (other?.spellId === prev.spellId) return true;
+      return false;
+    }
+    if (prev?.equipSpellId != null && a.spellId === prev.equipSpellId) {
+      if (other?.equipSpellId === prev.equipSpellId) return true;
+      return false;
+    }
+    // Drop then re-push so expiresAt refreshes; other hand with same id still gets one chip.
+    if (a.spellId === state.spellId) return false;
+    if (state.equipSpellId != null && a.spellId === state.equipSpellId) return false;
+    return true;
+  });
+  const expiresAt = state.expiresAt;
+  auras.push({ spellId: state.spellId, expiresAt });
+  // Oil / Rockbiter equip passive while TEMP is live (duration = temp expiresAt).
+  // durationMs 0 on the equip spell means "while enchanted", not permanent character-wide.
+  if (state.equipSpellId != null && state.equipSpellId > 0) {
+    auras.push({ spellId: state.equipSpellId, expiresAt });
+  }
+
+  // LOCK 2: dual-write identity onto the equipped instance (one-release migration with slot map).
+  const equipped: EquippedMap = { ...char.equipped };
+  const cur = equippedInstance(equipped[hand]);
+  if (cur != null) {
+    const te: { id: number; expiresAt?: number } = { id: state.enchantId };
+    if (state.expiresAt != null) te.expiresAt = state.expiresAt;
+    const next = withTempEnchant(cur, te);
+    equipped[hand] = hasIdentity(next) ? next : next.item;
+  }
+
+  return {
+    ...char,
+    equipped,
+    tempEnchants,
+    activeAuras: auras,
+    activeBuffs: getActiveBuffIds({ ...char, activeAuras: auras }, now, ds),
+  };
+}
+
+// Drop TEMP_ENCHANTMENT_SLOT combat authority + equip-spell auras for a hand. Used by equip/unequip so a
+// poison/oil does not follow a weapon swap (W5 D1).
+export function clearTempEnchantHand(
+  char: Character,
+  hand: TempEnchantHand,
+  now: number = Date.now(),
+  ds?: DataStore,
+): Character {
+  const te = char.tempEnchants?.[hand];
+  if (!te) return char;
+  const otherHand: TempEnchantHand = hand === 'mainhand' ? 'offhand' : 'mainhand';
+  const other = char.tempEnchants?.[otherHand];
+  const tempEnchants: TempEnchantMap = { ...(char.tempEnchants ?? {}) };
+  delete tempEnchants[hand];
+  const nextMap = (tempEnchants.mainhand || tempEnchants.offhand) ? tempEnchants : undefined;
+  let auras = pruneExpiredAuras(char.activeAuras, now).slice();
+  // Keep apply/equip aura when the other hand still uses the same spell ids.
+  auras = auras.filter((a) => {
+    if (a.spellId === te.spellId) return other?.spellId === te.spellId;
+    if (te.equipSpellId != null && a.spellId === te.equipSpellId) {
+      return other?.equipSpellId === te.equipSpellId;
+    }
+    return true;
+  });
+  return {
+    ...char,
+    tempEnchants: nextMap,
+    activeAuras: auras,
+    activeBuffs: getActiveBuffIds({ ...char, activeAuras: auras }, now, ds),
+  };
+}
+
+// Living, non-expired temp enchant on a hand, or undefined. Combat authority is char.tempEnchants;
+// the instance field is identity transport only, and no id→spell rehydrate happens here.
+export function getTempEnchant(
+  char: Character,
+  hand: TempEnchantHand,
+  now: number = Date.now(),
+): TempEnchantState | undefined {
+  const te = char.tempEnchants?.[hand];
+  if (!te) return undefined;
+  if (te.expiresAt != null && te.expiresAt <= now) return undefined;
+  return te;
+}
+
+// Flat AP from temp enchants that cache attackPower without an equip-spell aura. Rockbiter stamps
+// both, and AP must come from the aura alone or sheet and combat read 2× tooltip (KI-1039).
+export function tempEnchantAttackPower(char: Character, now: number = Date.now()): number {
+  let ap = 0;
+  for (const hand of ['mainhand', 'offhand'] as const) {
+    const te = getTempEnchant(char, hand, now);
+    if (!te?.attackPower) continue;
+    if (te.equipSpellId != null && te.equipSpellId > 0) continue;
+    ap += te.attackPower;
+  }
+  return ap;
+}

package/src/domain/professions/craftCooldown.ts

@@ -0,0 +1,52 @@
+// One reader for a recipe's craft cooldown, the shape itemUseCooldown.ts already holds: a personal
+// recovery keyed on the create-spell id plus a shared category. Cite: Player.cpp:20117 AddCooldown.
+
+import type { RecipeDef } from '../../data/schema.ts';
+
+export interface CraftCooldownMaps {
+  spellCooldowns?: Record<number, number> | null;
+  categoryCooldowns?: Record<number, number> | null;
+}
+
+/** Ms until this recipe may be crafted again; 0 is ready. */
+export function recipeCooldownRemainingMs(
+  recipe: RecipeDef,
+  cds: CraftCooldownMaps | null | undefined,
+  now: number,
+): number {
+  if (!cds) return 0;
+  let rem = (cds.spellCooldowns?.[recipe.id] ?? 0) - now;
+  const cat = recipe.cooldownCategory ?? 0;
+  if (cat > 0) rem = Math.max(rem, (cds.categoryCooldowns?.[cat] ?? 0) - now);
+  return Math.max(0, rem);
+}
+
+// Stamp both clocks after a craft lands. recTime and categoryRecTime are stored separately and the
+// longer one wins the wait: Player::AddCooldown keeps the pair rather than collapsing them.
+export function stampRecipeCooldown(
+  recipe: RecipeDef,
+  cds: { spellCooldowns: Record<number, number>; categoryCooldowns: Record<number, number> },
+  now: number,
+): void {
+  const rec = recipe.cooldownMs ?? 0;
+  if (rec > 0) cds.spellCooldowns[recipe.id] = Math.max(cds.spellCooldowns[recipe.id] ?? 0, now + rec);
+  const cat = recipe.cooldownCategory ?? 0;
+  const catRec = recipe.categoryCooldownMs ?? 0;
+  if (cat > 0 && catRec > 0) {
+    cds.categoryCooldowns[cat] = Math.max(cds.categoryCooldowns[cat] ?? 0, now + catRec);
+  }
+}
+
+// Countdown label for a craft cooldown. format.ts `duration` stops at hours, which renders a
+// 2-day transmute as "48 hr"; a cooldown this long reads in days.
+export function craftCooldownLabel(ms: number): string {
+  const sec = Math.max(0, Math.ceil(ms / 1000));
+  if (sec < 60) return `${sec} sec`;
+  const min = Math.ceil(sec / 60);
+  if (min < 60) return `${min} min`;
+  const hr = Math.ceil(min / 60);
+  if (hr < 24) return `${hr} hr`;
+  const day = Math.floor(hr / 24);
+  const rem = hr % 24;
+  return rem ? `${day} day ${rem} hr` : `${day} day${day > 1 ? 's' : ''}`;
+}

package/src/domain/professions/enchantApply.ts

@@ -0,0 +1,62 @@
+// Pure apply and clear helpers for enchant identity on ItemInstance, so perm and temp enchants
+// survive unequip and trade. Callers inject expiresAt and now; no I/O, no DataStore.
+
+import type { ItemInstance, InstanceTempEnchant } from '../items/itemInstance.ts';
+import { copyInstance, equippedInstance, hasIdentity } from '../items/itemInstance.ts';
+import type { EquippedMap } from '../character/character.ts';
+import type { EquipSlot } from '../../data/schema.ts';
+
+// Set or clear PERM_ENCHANTMENT_SLOT on an instance (profession enchant id). `undefined` clears the field
+// (absent = no perm enchant).
+export function withPermEnchant(
+  inst: ItemInstance,
+  enchantId: number | undefined,
+): ItemInstance {
+  const out = copyInstance(inst, inst.count);
+  if (enchantId == null) {
+    delete out.permEnchantId;
+  } else {
+    out.permEnchantId = enchantId;
+  }
+  return out;
+}
+
+/** Clear PERM_ENCHANTMENT_SLOT identity. */
+export function clearPermEnchant(inst: ItemInstance): ItemInstance {
+  return withPermEnchant(inst, undefined);
+}
+
+// Set or clear TEMP_ENCHANTMENT_SLOT on an instance (oil / poison / imbue). `undefined` clears the field.
+// `expiresAt` is caller-supplied epoch ms (injected clock).
+export function withTempEnchant(
+  inst: ItemInstance,
+  te: InstanceTempEnchant | undefined,
+): ItemInstance {
+  const out = copyInstance(inst, inst.count);
+  if (te == null) {
+    delete out.tempEnchant;
+  } else {
+    const next: InstanceTempEnchant = { id: te.id };
+    if (te.expiresAt != null) next.expiresAt = te.expiresAt;
+    out.tempEnchant = next;
+  }
+  return out;
+}
+
+/** Clear TEMP_ENCHANTMENT_SLOT identity. */
+export function clearTempEnchant(inst: ItemInstance): ItemInstance {
+  return withTempEnchant(inst, undefined);
+}
+
+// Write a permanent enchant onto `slot` of an EquippedMap, returning a NEW map. Promotes a bare
+// entry to a real ItemInstance first — an enchant has nowhere to live on a number.
+export function applyPermEnchantToSlot(
+  equipped: EquippedMap,
+  slot: EquipSlot,
+  enchantId: number,
+): EquippedMap {
+  const cur = equippedInstance(equipped[slot]);
+  if (cur == null) return equipped;
+  const next = withPermEnchant(cur, enchantId);
+  return { ...equipped, [slot]: hasIdentity(next) ? next : next.item };
+}

package/src/domain/professions/enchantTargets.ts

@@ -0,0 +1,114 @@
+// Which equipped slots an enchant apply spell may legally target, as ONE answer for the picker and
+// the validator. The rule is Item::IsFitToSpellRequirements, ANDing the three equipped-item masks.
+
+import type { EnchantApplicatorDef, EquipSlot, ItemDef, ItemEnchantDef } from '../../data/schema.ts';
+import type { EquippedMap } from '../character/character.ts';
+import { equippedEntry, equippedInstance } from '../items/itemInstance.ts';
+
+export interface EnchantTargetDs {
+  item(entry: number): ItemDef | undefined;
+  itemEnchant(id: number): ItemEnchantDef | undefined;
+}
+
+/** Why a slot cannot take this enchant — surfaced verbatim so the refusal is never mysterious. */
+export interface SlotRejection {
+  slot: EquipSlot;
+  reason: string;
+}
+
+export interface EnchantTargetScan {
+  /** Slots that would accept it right now. */
+  eligible: EquipSlot[];
+  /** Slots that hold an item but were refused, with the reason. */
+  rejected: SlotRejection[];
+}
+
+/** EquipSlot → the InventoryType bits an item in that slot can have. Cite: ItemPrototype.h. */
+const SLOT_INVTYPES: Readonly<Record<string, number[]>> = {
+  head: [1], neck: [2], shoulder: [3], shirt: [4], chest: [5, 20], waist: [6],
+  legs: [7], feet: [8], wrist: [9], hands: [10],
+  finger1: [11], finger2: [11], trinket1: [12], trinket2: [12],
+  mainhand: [13, 17, 21], offhand: [13, 22, 23, 14], back: [16],
+  ranged: [15, 25, 26, 28],
+  bag1: [18], bag2: [18], bag3: [18], bag4: [18],
+};
+
+/** item_template.class for the two classes an enchant can target. */
+const ITEM_CLASS_WEAPON = 2;
+const ITEM_CLASS_ARMOR = 4;
+
+// Can `app` be applied to `item` sitting in `slot`? Returns null when it can, else the reason.
+// `mainhandOnly` comes from the ENCHANT (DBC flag 0x04), not the applicator.
+export function rejectionFor(
+  app: EnchantApplicatorDef,
+  item: ItemDef,
+  slot: EquipSlot,
+  enchant?: ItemEnchantDef,
+): string | null {
+  // --- item class -----------------------------------------------------------
+  if (app.target.itemClass === ITEM_CLASS_WEAPON && !item.weapon) {
+    return 'That only goes on a weapon';
+  }
+  if (app.target.itemClass === ITEM_CLASS_ARMOR && item.weapon) {
+    return 'That only goes on armor';
+  }
+
+  // --- inventory type -------------------------------------------------------
+  const mask = app.target.inventoryTypeMask;
+  if (mask) {
+    // Prefer the item's real InventoryType; fall back to what the slot implies for bakes that
+    // omit the column (never guess a MATCH from absence — an unknown type must fail closed).
+    const bits = item.inventoryType != null ? [item.inventoryType] : (SLOT_INVTYPES[slot] ?? []);
+    if (!bits.some((b) => (mask & (1 << b)) !== 0)) return "That can't go on that slot";
+  }
+
+  // --- subclass -------------------------------------------------------------
+  const sub = item.weapon ? item.weaponSubclass : item.armorSubclass;
+  if (app.target.subClassMask && sub != null) {
+    if ((app.target.subClassMask & (1 << sub)) === 0) return "That can't go on that kind of item";
+  }
+
+  // --- item level floor (permanent enchants only) ---------------------------
+  // Temp imbues use baseLevel as the rank gate, not weapon ilvl. Cite: Spell.cpp:6672 vs :6689.
+  if (
+    app.permanent &&
+    app.target.minItemLevel > 0 &&
+    (item.itemLevel ?? 0) < app.target.minItemLevel
+  ) {
+    return `Requires an item of level ${app.target.minItemLevel} or higher`;
+  }
+
+  // --- main-hand-only enchants ---------------------------------------------
+  if (enchant?.mainhandOnly && slot !== 'mainhand') return 'That can only go on your main hand';
+
+  return null;
+}
+
+// Scan a wearer's equipped gear for slots this applicator accepts. Empty slots are skipped entirely — there
+// is nothing there to enchant.
+export function scanEnchantTargets(
+  equipped: EquippedMap,
+  app: EnchantApplicatorDef,
+  ds: EnchantTargetDs,
+): EnchantTargetScan {
+  const enchant = ds.itemEnchant(app.enchantId);
+  const eligible: EquipSlot[] = [];
+  const rejected: SlotRejection[] = [];
+
+  for (const [slot, v] of Object.entries(equipped) as [EquipSlot, unknown][]) {
+    const entry = equippedEntry(v as never);
+    if (entry == null) continue;
+    const item = ds.item(entry);
+    if (!item) continue;
+    const why = rejectionFor(app, item, slot, enchant);
+    if (why) rejected.push({ slot, reason: why });
+    else eligible.push(slot);
+  }
+  eligible.sort();
+  return { eligible, rejected };
+}
+
+/** True when `slot` already carries a permanent enchant (re-enchanting REPLACES, as in WoW). */
+export function slotHasPermEnchant(equipped: EquippedMap, slot: EquipSlot): boolean {
+  return equippedInstance(equipped[slot])?.permEnchantId != null;
+}

package/src/domain/professions/enchanting.ts

@@ -0,0 +1,236 @@
+// Enchanting: apply a permanent bonus to equipped gear, and disenchant uncommon+ gear into dust.
+// Pure and deterministic — the roll comes from an injected Rng. Neither action fits RecipeDef.
+
+import type { Character, EnchantMap, EquippedMap } from '../character/character.ts';
+import { equippedEntry, equippedInstance, hasIdentity } from '../items/itemInstance.ts';
+import { withPermEnchant } from './enchantApply.ts';
+import type { Inventory } from '../items/inventory.ts';
+import { addItem, removeItem, removeStack, countItem, canFit } from '../items/inventory.ts';
+import type { LootDrop } from '../items/loot.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+import type { DataStore } from '../../data/dataStore.ts';
+import type { EquipSlot, ItemDef, EnchantDef, DisenchantRuleDef, SkillCurve } from '../../data/schema.ts';
+import type { Check } from './professions.ts';
+import { gainSkill } from './professions.ts';
+import { isBroken } from '../items/durability.ts';
+
+export interface EnchantResult extends Check {
+  char: Character;
+  inventory: Inventory;
+  skillUp?: number;    // new enchanting skill if a point was gained
+}
+export interface DisenchantResult extends Check {
+  char: Character;
+  inventory: Inventory;
+  yielded: LootDrop[]; // materials rolled (empty on an unlucky roll - the item is still destroyed)
+  skillUp?: number;
+}
+/** Learn a formula (pays its cost). Mirrors professions.learnRecipe, but for `knownEnchants`. */
+export interface LearnResult extends Check {
+  char: Character;
+}
+
+// ---- Rods (the tool) ------------------------------------------------------
+
+// Highest rod tier reachable (0 = none); a higher rod satisfies every lower one. `shared` is the
+// party's held-tool pool (partyHeldTools), so one rod anywhere in the party covers every enchanter.
+export function bestRodTier(inv: Inventory, ds: DataStore, shared?: ReadonlySet<number>): number {
+  let best = 0;
+  const bump = (entry: number): void => {
+    const tier = ds.enchantRodTier(entry);
+    if (tier && tier > best) best = tier;
+  };
+  for (const stk of inv.stacks) bump(stk.item);
+  if (shared) for (const entry of shared) bump(entry);
+  return best;
+}
+
+/** The rod a minRodTier asks for: the lowest rod that satisfies it. */
+export function rodForTier(tier: number, ds: DataStore): ItemDef | undefined {
+  let pick: { entry: number; tier: number } | undefined;
+  for (const rod of ds.enchantRods()) {
+    if (rod.tier >= tier && (!pick || rod.tier < pick.tier)) pick = rod;
+  }
+  return pick ? ds.item(pick.entry) : undefined;
+}
+
+// The rod's own name, the way canCraft names a hammer. Falls back to the tier with no rod row.
+export function rodNameForTier(tier: number, ds: DataStore): string {
+  return rodForTier(tier, ds)?.name ?? `a tier-${tier} runed rod`;
+}
+
+// ---- Applying an enchant --------------------------------------------------
+
+/** Whether `enchant` can be applied to the item currently in `slot`, right now. */
+export function canEnchant(
+  char: Character, inv: Inventory, ds: DataStore, enchant: EnchantDef, slot: EquipSlot,
+  /** Held tools the party can reach outside `inv` (partyHeldTools). The rod is shared. */
+  sharedTools?: ReadonlySet<number>,
+): Check {
+  if (!(char.knownEnchants ?? []).includes(enchant.id)) return { ok: false, reason: 'Enchant not known' };
+  const skill = char.skills.enchanting;
+  if (!skill) return { ok: false, reason: 'Requires Enchanting' };
+  if (skill.current < enchant.orange) return { ok: false, reason: `Requires Enchanting skill ${enchant.orange}` };
+  const entry = equippedEntry(char.equipped[slot]);
+  const item = entry != null ? ds.item(entry) : undefined;
+  if (!item || !item.slot) return { ok: false, reason: 'Nothing equipped there' };
+  if (!enchant.slots.includes(item.slot)) return { ok: false, reason: `This enchant can't go on that item` };
+  if (isBroken(char, slot, item)) return { ok: false, reason: 'Item is broken - repair it first' };
+  if (bestRodTier(inv, ds, sharedTools) < enchant.minRodTier) {
+    return { ok: false, reason: `Requires ${rodNameForTier(enchant.minRodTier, ds)}` };
+  }
+  for (const rg of enchant.reagents) {
+    if (countItem(inv, rg.item) < rg.count) return { ok: false, reason: 'Missing reagents' };
+  }
+  return { ok: true };
+}
+
+// Apply `enchant` to `slot`: consume the reagents, never the rod, record it, and roll a skill-up.
+// A prior enchant on that slot is overwritten. Also writes ItemInstance.permEnchantId.
+export function applyEnchant(
+  char: Character, inv: Inventory, ds: DataStore, enchant: EnchantDef, slot: EquipSlot, rng: Rng,
+  sharedTools?: ReadonlySet<number>,
+): EnchantResult {
+  const chk = canEnchant(char, inv, ds, enchant, slot, sharedTools);
+  if (!chk.ok) return { ok: false, reason: chk.reason, char, inventory: inv };
+  let working = inv;
+  for (const rg of enchant.reagents) working = removeItem(working, rg.item, rg.count)[0];
+  const enchants: EnchantMap = { ...char.enchants, [slot]: enchant.id };
+  // LOCK 2: identity on the equipped instance so unequip/trade keep the enchant.
+  const equipped: EquippedMap = { ...char.equipped };
+  const cur = equippedInstance(equipped[slot]);
+  if (cur != null) {
+    const next = withPermEnchant(cur, enchant.id);
+    equipped[slot] = hasIdentity(next) ? next : next.item;
+  }
+  const gain = gainSkill({ ...char, enchants, equipped }, 'enchanting', enchant, rng);
+  return { ok: true, char: gain.char, inventory: working, skillUp: gain.up };
+}
+
+// ---- Disenchanting (the material source) ----------------------------------
+
+// True if the item is weapons, armor or jewelry an enchanter can break down, never bags or
+// consumables. Jewelry bakes as class 4 with armor 0, so an `armor > 0` check blocked every ring.
+export function isDisenchantable(item: ItemDef): boolean {
+  // Authoritative bake: DB item class.
+  if (item.itemClass === 2 || item.itemClass === 4) return true;
+  // Weapon payload (fixtures / pre-class bake).
+  if (item.weapon) return true;
+  // Body armor / shields / cloaks (armor field, even if itemClass omitted).
+  if ((item.armor ?? 0) > 0) return true;
+  // Jewelry: armor class, armor 0 — never require armor points.
+  const s = item.slot;
+  if (s === 'finger' || s === 'neck' || s === 'trinket') return true;
+  return false;
+}
+
+/** The disenchant rule that matches an item (its quality + itemLevel band), or undefined. */
+export function disenchantRuleFor(item: ItemDef, ds: DataStore): DisenchantRuleDef | undefined {
+  const ilvl = item.itemLevel ?? 0;
+  return ds.disenchantRules().find(
+    (r) => r.quality === item.quality && ilvl >= r.minItemLevel && ilvl <= r.maxItemLevel,
+  );
+}
+
+/** Whether `entry` (an item held in the bags) can be disenchanted right now. */
+export function canDisenchant(char: Character, inv: Inventory, ds: DataStore, entry: number): Check {
+  const skill = char.skills.enchanting;
+  if (!skill) return { ok: false, reason: 'Requires Enchanting' };
+  if (countItem(inv, entry) <= 0) return { ok: false, reason: "You don't have that" };
+  const item = ds.item(entry);
+  if (!item) return { ok: false, reason: 'Unknown item' };
+  if (!isDisenchantable(item)) return { ok: false, reason: 'Only weapons and armor can be disenchanted' };
+  if (item.quality < 2) return { ok: false, reason: 'Only uncommon or better gear can be disenchanted' };
+  const rule = disenchantRuleFor(item, ds);
+  if (!rule) return { ok: false, reason: 'That yields no enchanting materials' };
+  if (skill.current < rule.reqSkill) return { ok: false, reason: `Requires Enchanting skill ${rule.reqSkill}` };
+  return { ok: true };
+}
+
+// The skill-up window for a disenchant, derived from the band's DE requirement, so DE stays a
+// viable way to level. CMaNGOS grants the point on cast; we roll after destroying — one roll.
+function disenchantCurve(reqSkill: number): SkillCurve {
+  return { orange: reqSkill, yellow: reqSkill + 25, green: reqSkill + 50, gray: reqSkill + 100 };
+}
+
+export interface DisenchantSplitResult extends Check {
+  char: Character;
+  /** The container the gear came out of. */
+  from: Inventory;
+  /** Where the mats landed — the same object as `from` when one container does both jobs. */
+  into: Inventory;
+  yielded: LootDrop[];
+  skillUp?: number;
+}
+
+// The one disenchant body, across two containers: the gear leaves `from`, the mats land in `into`.
+// Pass the same inventory for both when one bag does the whole job. Materials carry no bind, so a
+// soulbound green in a companion's bags breaks down where it lies and the dust is the player's.
+// An empty yield still destroys. Mats that cannot fit refuse the whole act (KI-808).
+export function disenchantInto(
+  char: Character, from: Inventory, into: Inventory, ds: DataStore, entry: number, rng: Rng,
+  opts?: { slot?: number; intoCap?: number },
+): DisenchantSplitResult {
+  const slot = opts?.slot;
+  const fail = (reason: string): DisenchantSplitResult =>
+    ({ ok: false, reason, char, from, into, yielded: [] });
+  const chk = canDisenchant(char, from, ds, entry);
+  if (!chk.ok) return fail(chk.reason ?? 'Cannot disenchant');
+  // `slot` names ONE stack. Without it removeItem takes the first stack of `entry`, which is the
+  // wrong "Archer's Jerkin" when you hold two with different rolled suffixes.
+  if (slot != null && from.stacks[slot]?.item !== entry) return fail("You don't have that");
+  const item = ds.item(entry)!;
+  const rule = disenchantRuleFor(item, ds)!;
+  const yielded: LootDrop[] = [];
+  for (const y of rule.yield) {
+    if (y.chance > 0 && rng.chance(y.chance / 100)) yielded.push({ item: y.item, count: rng.int(y.minCount, y.maxCount) });
+  }
+  // Probe on a copy: free the DE slot first, then require every rolled mat to fit (craft-style).
+  const shed = slot != null ? removeStack(from, slot, 1)[0] : removeItem(from, entry, 1)[0];
+  const oneBag = from === into;
+  let mats = oneBag ? shed : into;
+  for (const drop of yielded) {
+    const stackMax = ds.item(drop.item)?.stackable ?? 1;
+    if (!canFit(mats, drop.item, drop.count, stackMax, opts?.intoCap)) {
+      return fail('Not enough bag space');
+    }
+    mats = addItem(mats, drop.item, drop.count, stackMax);
+  }
+  // Craft skill-up (UpdateCraftSkill); enchanting is not a gather line - uses color curve only.
+  const gain = gainSkill(char, 'enchanting', disenchantCurve(rule.reqSkill), rng);
+  return { ok: true, char: gain.char, from: oneBag ? mats : shed, into: mats, yielded, skillUp: gain.up };
+}
+
+/** Disenchant one `entry` out of the bags, mats back into those same bags. */
+export function disenchant(
+  char: Character, inv: Inventory, ds: DataStore, entry: number, rng: Rng, cap?: number,
+  slot?: number,
+): DisenchantResult {
+  const res = disenchantInto(char, inv, inv, ds, entry, rng, {
+    ...(slot != null ? { slot } : {}), ...(cap != null ? { intoCap: cap } : {}),
+  });
+  if (!res.ok) return { ok: false, reason: res.reason, char, inventory: inv, yielded: [] };
+  return { ok: true, char: res.char, inventory: res.into, yielded: res.yielded, skillUp: res.skillUp };
+}
+
+// ---- Learning formulas ----------------------------------------------------
+
+// Learn an enchant formula, paying the cost. The trainer path also needs skill ≥ orange; reading
+// a Formula: item does not, since applyEnchant still gates on orange, rod and reagents.
+export function learnEnchant(
+  char: Character,
+  enchant: EnchantDef,
+  opts?: { fromItem?: boolean; discountMod?: number },
+): LearnResult {
+  const known = char.knownEnchants ?? [];
+  if (known.includes(enchant.id)) return { ok: false, reason: 'Already learned', char };
+  const skill = char.skills.enchanting;
+  if (!skill) return { ok: false, reason: 'Requires Enchanting', char };
+  // Classic trainer gate only — not applied when learning from a Formula: item.
+  if (!opts?.fromItem && skill.current < enchant.orange) {
+    return { ok: false, reason: `Requires Enchanting skill ${enchant.orange}`, char };
+  }
+  const cost = Math.floor((enchant.cost ?? 0) * (opts?.discountMod ?? 1.0));
+  if (char.gold < cost) return { ok: false, reason: 'Not enough money', char };
+  return { ok: true, char: { ...char, gold: char.gold - cost, knownEnchants: [...known, enchant.id] } };
+}