azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/items/junkCategories.ts

@@ -0,0 +1,174 @@
+// Whole categories the junk filter refuses to sell or destroy. Every test reads item_template
+// CLASS, never the consumable SUBCLASS, which the 1.12 tier renumbers against the header enum.
+
+import type { ItemDef, RecipeDef } from '../../data/schema.ts';
+import { ITEM_CLASS_TRADE_GOODS } from '../bots/sendTradeGoods.ts';
+import { itemTeachIntent, type TeachLookup } from './itemTeaches.ts';
+import { isFishingPole, isMiningPick, isSkinningKnife } from '../professions/professions.ts';
+import { SPELL_EFFECT_SUMMON_CRITTER } from '../../engine/spells/interpreter/opcodes.ts';
+
+/** Cite: ItemPrototype.h:144-159. Only the classes a category asks about. */
+const ITEM_CLASS_CONSUMABLE = 0;
+const ITEM_CLASS_CONTAINER = 1;
+const ITEM_CLASS_REAGENT = 5;
+const ITEM_CLASS_PROJECTILE = 6;
+const ITEM_CLASS_RECIPE = 9;
+const ITEM_CLASS_QUIVER = 11;
+const ITEM_CLASS_QUEST = 12;
+const ITEM_CLASS_KEY = 13;
+
+/** INVTYPE_AMMO. Cite: ItemPrototype.h InventoryType; Item.cpp ItemCanGoIntoBag. */
+const INVTYPE_AMMO = 24;
+/** item_template.BagFamily ARROWS / BULLETS. Cite: Item.cpp ItemCanGoIntoBag. */
+const BAG_FAMILY_ARROWS = 1;
+const BAG_FAMILY_BULLETS = 2;
+
+export type JunkProtectCategory =
+  | 'ammo'
+  | 'quiver'
+  | 'foodDrink'
+  | 'consumable'
+  | 'reagent'
+  | 'tradeGoods'
+  | 'container'
+  | 'teaches'
+  | 'key'
+  | 'quest'
+  | 'mountPet'
+  | 'tool';
+
+export interface JunkProtectCategoryDef {
+  id: JunkProtectCategory;
+  /** Checkbox label, in the player's own words. */
+  label: string;
+  /** One line of why, for the settings row and the skipped-row reason. */
+  hint: string;
+}
+
+// Display order is "most likely to be in a bag" first. Every one is on by default: the point of the list is
+// that a fresh player can press Sell All without reading it.
+export const JUNK_PROTECT_CATEGORIES: readonly JunkProtectCategoryDef[] = [
+  { id: 'ammo', label: 'Arrows and bullets', hint: 'Ammunition your bow or gun still needs' },
+  { id: 'quiver', label: 'Quivers and ammo pouches', hint: 'The bag your ammo lives in' },
+  { id: 'foodDrink', label: 'Food and drink', hint: 'What the party eats and drinks between pulls' },
+  { id: 'consumable', label: 'Potions, scrolls and bandages', hint: 'Every other consumable' },
+  { id: 'reagent', label: 'Spell reagents', hint: 'Powders, ankhs, symbols a spell consumes' },
+  { id: 'tradeGoods', label: 'Crafting materials', hint: 'Cloth, ore, herbs, leather, essences' },
+  { id: 'container', label: 'Bags and containers', hint: 'Spare bags, not the ones you wear' },
+  { id: 'teaches', label: 'Recipes, formulas and books', hint: 'Anything somebody can still read' },
+  { id: 'key', label: 'Keys and lockpicks', hint: 'Dungeon keys and skeleton keys' },
+  { id: 'quest', label: 'Quest items', hint: 'Quest drops and items that start a quest' },
+  { id: 'mountPet', label: 'Mounts and pets', hint: 'Reins, whistles, pet carriers' },
+  { id: 'tool', label: 'Profession tools', hint: 'Hammer, spanner, rods, pick, knife, pole' },
+];
+
+const CATEGORY_IDS = new Set<string>(JUNK_PROTECT_CATEGORIES.map((c) => c.id));
+
+export const DEFAULT_PROTECT_CATEGORIES: readonly JunkProtectCategory[] =
+  JUNK_PROTECT_CATEGORIES.map((c) => c.id);
+
+export function junkProtectCategoryLabel(id: JunkProtectCategory): string {
+  return JUNK_PROTECT_CATEGORIES.find((c) => c.id === id)?.label ?? id;
+}
+
+// Coerce a stored list. An ABSENT list means "never configured" and takes the defaults — an EMPTY array is
+// a player who unchecked every box and must stay empty.
+export function normalizeProtectCategories(raw: unknown): JunkProtectCategory[] {
+  if (!Array.isArray(raw)) return [...DEFAULT_PROTECT_CATEGORIES];
+  const out: JunkProtectCategory[] = [];
+  for (const x of raw) {
+    if (typeof x === 'string' && CATEGORY_IDS.has(x) && !out.includes(x as JunkProtectCategory)) {
+      out.push(x as JunkProtectCategory);
+    }
+  }
+  return out;
+}
+
+// Item entries held, never spent, by some recipe — hammers, spanners, enchanting rods. Nine in the
+// bake, all white with a real sell price, so "sell all common" ate the crafting kit.
+export function craftToolEntries(recipes: readonly RecipeDef[]): Set<number> {
+  const out = new Set<number>();
+  for (const r of recipes) {
+    for (const t of r.requiredTools ?? []) if (t > 0) out.add(t);
+  }
+  return out;
+}
+
+export interface ProtectLookup extends TeachLookup {
+  /** From craftToolEntries(ds.recipes()). Empty set = tools fall through to their item class. */
+  craftTools: ReadonlySet<number>;
+}
+
+/** DataStore slice protectLookupFor needs. */
+export type ProtectSource = TeachLookup & { recipes(): RecipeDef[] };
+
+const toolsByStore = new WeakMap<object, Set<number>>();
+
+// One craft-tool set per DataStore. dispositionForEntry runs per bag entry and ds.recipes() materializes
+// 1,135 rows, so this must never be rebuilt inside the loop.
+export function protectLookupFor(ds: ProtectSource): ProtectLookup {
+  let tools = toolsByStore.get(ds);
+  if (!tools) {
+    tools = craftToolEntries(ds.recipes());
+    toolsByStore.set(ds, tools);
+  }
+  return { spell: ds.spell, recipe: ds.recipe, enchant: ds.enchant, craftTools: tools };
+}
+
+// A mount or a mini-pet. mountSpell is the baked aura-78 marker; a critter has none, so its on-use
+// spell is read for SPELL_EFFECT_SUMMON_CRITTER — a Cat Carrier is class 15 like any trinket.
+function isMountOrPet(it: ItemDef, look: ProtectLookup): boolean {
+  if (it.mountSpell != null) return true;
+  if (it.useSpell == null) return false;
+  const sp = look.spell(it.useSpell);
+  return !!sp?.rawEffects?.some((e) => e.effect === SPELL_EFFECT_SUMMON_CRITTER);
+}
+
+// Which protected category this item falls in, or null when nothing claims it. First match wins,
+// since the earlier tests are the ones whose reason a player would recognise.
+export function itemProtectCategory(
+  it: ItemDef | undefined | null,
+  look: ProtectLookup,
+): JunkProtectCategory | null {
+  if (!it) return null;
+  const cls = it.itemClass;
+
+  if (it.questItem || (it.startQuest ?? 0) > 0 || cls === ITEM_CLASS_QUEST) return 'quest';
+  // Tools before their item class: the enchanting rods are class 7, the pick a class-2 weapon.
+  if (look.craftTools.has(it.entry) || isFishingPole(it) || isMiningPick(it) || isSkinningKnife(it)) {
+    return 'tool';
+  }
+  if (cls === ITEM_CLASS_PROJECTILE
+    || it.inventoryType === INVTYPE_AMMO
+    || it.bagFamily === BAG_FAMILY_ARROWS
+    || it.bagFamily === BAG_FAMILY_BULLETS) {
+    return 'ammo';
+  }
+  if (cls === ITEM_CLASS_QUIVER) return 'quiver';
+  if (cls === ITEM_CLASS_CONSUMABLE) {
+    // The bake only stamps `consumable` on the food/drink rows it could derive (Skin of Dwarven
+    // Stout has none), so the split is cosmetic — both halves are class 0 and both are protected.
+    return it.consumable != null || it.foodType != null ? 'foodDrink' : 'consumable';
+  }
+  if (cls === ITEM_CLASS_REAGENT) return 'reagent';
+  if (cls === ITEM_CLASS_CONTAINER || it.slot === 'bag') return 'container';
+  if (cls === ITEM_CLASS_KEY) return 'key';
+  // itemTeachIntent, not the baked teach fields: 855 of the 1,672 teaching rows carry no field.
+  if (cls === ITEM_CLASS_RECIPE || itemTeachIntent(it, look) != null) return 'teaches';
+  if (isMountOrPet(it, look)) return 'mountPet';
+  if (cls === ITEM_CLASS_TRADE_GOODS) return 'tradeGoods';
+  return null;
+}
+
+/** The category blocking this item under `active`, or null when it is free to sell. */
+export function protectedCategoryFor(
+  it: ItemDef | undefined | null,
+  active: Iterable<JunkProtectCategory>,
+  look: ProtectLookup,
+): JunkProtectCategory | null {
+  const cat = itemProtectCategory(it, look);
+  if (cat == null) return null;
+  // Iterable, not array-or-Set: 12 ids at most, so a membership walk beats a cast either way.
+  for (const on of active) if (on === cat) return cat;
+  return null;
+}

package/src/domain/items/junkFilter.ts

@@ -0,0 +1,368 @@
+// Junk filter: Dejunk-style disposition over a character layer then a global one. Never sells a
+// quest item or an upgrade; whole categories are guarded by junkCategories.ts.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Character } from '../character/character.ts';
+import type { Inventory } from './inventory.ts';
+import type { Companion } from '../bots/squad.ts';
+import type { EquipOpts } from './equipment.ts';
+import {
+  type AutoDisenchantConfig,
+  canAutoDisenchantEntry,
+  isUpgradeForParty,
+  type PartyEnchanter,
+} from '../professions/autoDisenchant.ts';
+import {
+  DEFAULT_PROTECT_CATEGORIES,
+  junkProtectCategoryLabel,
+  normalizeProtectCategories,
+  protectLookupFor,
+  protectedCategoryFor,
+  type JunkProtectCategory,
+} from './junkCategories.ts';
+
+/** Classic quality tiers used by sell/destroy include checkboxes (poor .. epic). */
+export type JunkQuality = 0 | 1 | 2 | 3 | 4;
+
+export type JunkDisposition = 'keep' | 'sell' | 'destroy';
+
+/** One layer of junk rules (global or character). */
+export interface JunkFilterConfig {
+  /** Auto-vendor matching sellable junk. Default true. */
+  autoSell: boolean;
+  /** Auto-discard matching destroy junk. Default false. */
+  autoDestroy: boolean;
+  /** Include-by-quality for sell. Default: only poor (0). */
+  sellQuality: Record<JunkQuality, boolean>;
+  /** Include-by-quality for destroy. Default: all false. */
+  destroyQuality: Record<JunkQuality, boolean>;
+  /** Never junk (exclusions). */
+  keepEntries: number[];
+  /** Always sell when sellable. */
+  sellEntries: number[];
+  /** Always destroy. */
+  destroyEntries: number[];
+  // Whole item categories never sold or destroyed however the quality boxes are set — arrows, food,
+  // reagents, mats, bags, recipes, keys, quest items, mounts, pets, tools. Default: all of them.
+  protectCategories: JunkProtectCategory[];
+  // The vendor's Sell All picker remembers its own tier boxes here, separate from `sellQuality`: a manual
+  // "sell my greens once" must never arm the automatic pass. Default: poor only.
+  sellAllQuality: Record<JunkQuality, boolean>;
+}
+
+// Per-character layer. When `characterSpecific` is false, quality/auto flags come from global; character
+// lists still apply (Dejunk: lists are always both scopes).
+export interface CharacterJunkFilterConfig extends JunkFilterConfig {
+  characterSpecific: boolean;
+}
+
+export type JunkListScope = 'global' | 'character';
+
+const QUALITIES: JunkQuality[] = [0, 1, 2, 3, 4];
+
+export const DEFAULT_JUNK_FILTER_CONFIG: JunkFilterConfig = {
+  autoSell: true,
+  autoDestroy: false,
+  sellQuality: { 0: true, 1: false, 2: false, 3: false, 4: false },
+  destroyQuality: { 0: false, 1: false, 2: false, 3: false, 4: false },
+  keepEntries: [],
+  sellEntries: [],
+  destroyEntries: [],
+  protectCategories: [...DEFAULT_PROTECT_CATEGORIES],
+  sellAllQuality: { 0: true, 1: false, 2: false, 3: false, 4: false },
+};
+
+export const DEFAULT_CHARACTER_JUNK_FILTER_CONFIG: CharacterJunkFilterConfig = {
+  ...DEFAULT_JUNK_FILTER_CONFIG,
+  characterSpecific: false,
+  // Protection is a UNION of both layers, so a character copy of the defaults would make the global
+  // boxes un-unpickable. The character layer only ever ADDS.
+  protectCategories: [],
+};
+
+function qualityMap(
+  raw: unknown,
+  fallback: Record<JunkQuality, boolean>,
+): Record<JunkQuality, boolean> {
+  const r = (raw && typeof raw === 'object' ? raw : {}) as Partial<Record<JunkQuality | string, unknown>>;
+  const out = { ...fallback };
+  for (const q of QUALITIES) {
+    const v = r[q] ?? r[String(q)];
+    if (typeof v === 'boolean') out[q] = v;
+  }
+  return out;
+}
+
+function entryList(raw: unknown): number[] {
+  if (!Array.isArray(raw)) return [];
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (const x of raw) {
+    const n = typeof x === 'number' ? x : Number(x);
+    if (!Number.isInteger(n) || n <= 0 || seen.has(n)) continue;
+    seen.add(n);
+    out.push(n);
+  }
+  return out;
+}
+
+// dispositionForEntry re-normalizes ctx.global/ctx.character per bag entry and both are already
+// canonical: mark outputs so the second pass returns the same object instead of 5 allocations.
+const canonical = new WeakSet<object>();
+const canonicalCharacter = new WeakSet<object>();
+
+/** Coerce stored value; missing/partial → defaults (auto-sell greys only). */
+export function normalizeJunkFilterConfig(raw: unknown): JunkFilterConfig {
+  if (raw && typeof raw === 'object' && canonical.has(raw)) return raw as JunkFilterConfig;
+  const r = (raw && typeof raw === 'object' ? raw : {}) as Partial<JunkFilterConfig>;
+  const out: JunkFilterConfig = {
+    autoSell: typeof r.autoSell === 'boolean' ? r.autoSell : DEFAULT_JUNK_FILTER_CONFIG.autoSell,
+    autoDestroy: typeof r.autoDestroy === 'boolean' ? r.autoDestroy : DEFAULT_JUNK_FILTER_CONFIG.autoDestroy,
+    sellQuality: qualityMap(r.sellQuality, DEFAULT_JUNK_FILTER_CONFIG.sellQuality),
+    destroyQuality: qualityMap(r.destroyQuality, DEFAULT_JUNK_FILTER_CONFIG.destroyQuality),
+    keepEntries: entryList(r.keepEntries),
+    sellEntries: entryList(r.sellEntries),
+    destroyEntries: entryList(r.destroyEntries),
+    protectCategories: normalizeProtectCategories(r.protectCategories),
+    sellAllQuality: qualityMap(r.sellAllQuality, DEFAULT_JUNK_FILTER_CONFIG.sellAllQuality),
+  };
+  canonical.add(out);
+  return out;
+}
+
+export function normalizeCharacterJunkFilterConfig(raw: unknown): CharacterJunkFilterConfig {
+  if (raw && typeof raw === 'object' && canonicalCharacter.has(raw)) {
+    return raw as CharacterJunkFilterConfig;
+  }
+  const base = normalizeJunkFilterConfig(raw);
+  const r = (raw && typeof raw === 'object' ? raw : {}) as Partial<CharacterJunkFilterConfig>;
+  const out: CharacterJunkFilterConfig = {
+    ...base,
+    characterSpecific: typeof r.characterSpecific === 'boolean' ? r.characterSpecific : false,
+    // Absent means "adds nothing" here, not "take the defaults" (see the constant above).
+    protectCategories: Array.isArray(r.protectCategories)
+      ? normalizeProtectCategories(r.protectCategories)
+      : [],
+  };
+  canonical.add(out);
+  canonicalCharacter.add(out);
+  return out;
+}
+
+/** Build default config, optionally migrating legacy autopilot.autoSellGrays. */
+export function junkFilterFromLegacy(autoSellGrays: boolean | undefined): JunkFilterConfig {
+  return normalizeJunkFilterConfig({
+    ...DEFAULT_JUNK_FILTER_CONFIG,
+    autoSell: typeof autoSellGrays === 'boolean' ? autoSellGrays : DEFAULT_JUNK_FILTER_CONFIG.autoSell,
+  });
+}
+
+export type JunkListKind = 'keep' | 'sell' | 'destroy';
+
+/** Assign entry to one list (mutually exclusive within that layer). Pass null to remove. */
+export function setJunkListMembership(
+  cfg: JunkFilterConfig,
+  entry: number,
+  list: JunkListKind | null,
+): JunkFilterConfig {
+  const n = normalizeJunkFilterConfig(cfg);
+  const strip = (arr: number[]) => arr.filter((e) => e !== entry);
+  const keepEntries = strip(n.keepEntries);
+  const sellEntries = strip(n.sellEntries);
+  const destroyEntries = strip(n.destroyEntries);
+  if (list === 'keep') keepEntries.push(entry);
+  else if (list === 'sell') sellEntries.push(entry);
+  else if (list === 'destroy') destroyEntries.push(entry);
+  return { ...n, keepEntries, sellEntries, destroyEntries };
+}
+
+export function junkListKindFor(
+  cfg: JunkFilterConfig,
+  entry: number,
+): JunkListKind | null {
+  const n = normalizeJunkFilterConfig(cfg);
+  if (n.keepEntries.includes(entry)) return 'keep';
+  if (n.sellEntries.includes(entry)) return 'sell';
+  if (n.destroyEntries.includes(entry)) return 'destroy';
+  return null;
+}
+
+export function clearJunkList(cfg: JunkFilterConfig, list: JunkListKind): JunkFilterConfig {
+  const n = normalizeJunkFilterConfig(cfg);
+  if (list === 'keep') return { ...n, keepEntries: [] };
+  if (list === 'sell') return { ...n, sellEntries: [] };
+  return { ...n, destroyEntries: [] };
+}
+
+const mergedRules = new WeakMap<object, WeakMap<object, JunkFilterConfig>>();
+
+// Combined quality/auto from both layers (OR). Lists stay separate in disposition order. characterSpecific
+// is ignored — both Global and Character tabs always fully apply.
+export function effectiveJunkRules(
+  global: JunkFilterConfig,
+  character: CharacterJunkFilterConfig | JunkFilterConfig,
+): JunkFilterConfig {
+  const g = normalizeJunkFilterConfig(global);
+  const c = normalizeJunkFilterConfig(character);
+  let byCharacter = mergedRules.get(g);
+  const hit = byCharacter?.get(c);
+  if (hit) return hit;
+  const sellQuality = { ...g.sellQuality };
+  const destroyQuality = { ...g.destroyQuality };
+  const sellAllQuality = { ...g.sellAllQuality };
+  for (const q of QUALITIES) {
+    sellQuality[q] = !!(g.sellQuality[q] || c.sellQuality[q]);
+    destroyQuality[q] = !!(g.destroyQuality[q] || c.destroyQuality[q]);
+  }
+  // Protection is additive, like a keep list: a category either layer guards stays guarded.
+  const protectCategories = [...new Set([...g.protectCategories, ...c.protectCategories])];
+  const out: JunkFilterConfig = {
+    autoSell: !!(g.autoSell || c.autoSell),
+    autoDestroy: !!(g.autoDestroy || c.autoDestroy),
+    sellQuality,
+    destroyQuality,
+    keepEntries: c.keepEntries,
+    sellEntries: c.sellEntries,
+    destroyEntries: c.destroyEntries,
+    protectCategories,
+    // NOT merged: the vendor's Sell All picker writes the global layer and reads it back, so a
+    // stale character copy must never keep a tier ticked that the player just unticked.
+    sellAllQuality,
+  };
+  canonical.add(out);
+  if (!byCharacter) { byCharacter = new WeakMap(); mergedRules.set(g, byCharacter); }
+  byCharacter.set(c, out);
+  return out;
+}
+
+export interface JunkEvalContext {
+  global: JunkFilterConfig;
+  character: CharacterJunkFilterConfig;
+  deCfg: AutoDisenchantConfig;
+  player: Character;
+  playerInv: Inventory;
+  playerEquipOpts: EquipOpts;
+  companions: readonly Companion[];
+  enchanters: readonly PartyEnchanter[];
+  ds: DataStore;
+  questProtected: ReadonlySet<number>;
+  /** One findUpgrades pass per body. Absent → isUpgradeForParty per item (the old cost). */
+  upgradeEntries?: ReadonlySet<number>;
+}
+
+// Disposition for a bag item (Dejunk priority): quest → char keep → char force destroy/sell → global keep →
+// global force → upgrades → auto-DE claim → quality rules (char if characterSpecific else global).
+export function dispositionForEntry(
+  entry: number,
+  ctx: JunkEvalContext,
+): { disposition: JunkDisposition; reason: string } {
+  const global = normalizeJunkFilterConfig(ctx.global);
+  const character = normalizeCharacterJunkFilterConfig(ctx.character);
+  const item = ctx.ds.item(entry);
+  if (!item) return { disposition: 'keep', reason: 'Unknown item' };
+
+  if (ctx.questProtected.has(entry)) {
+    return { disposition: 'keep', reason: 'Needed for a quest' };
+  }
+
+  // Character lists (highest list priority).
+  if (character.keepEntries.includes(entry)) {
+    return { disposition: 'keep', reason: 'Character keep list' };
+  }
+  if (character.destroyEntries.includes(entry)) {
+    return { disposition: 'destroy', reason: 'Character destroy list' };
+  }
+  if (character.sellEntries.includes(entry)) {
+    if ((item.sellPrice ?? 0) > 0) return { disposition: 'sell', reason: 'Character sell list' };
+    return { disposition: 'destroy', reason: 'Character sell list (no vendor value)' };
+  }
+
+  // Global lists.
+  if (global.keepEntries.includes(entry)) {
+    return { disposition: 'keep', reason: 'Global keep list' };
+  }
+  if (global.destroyEntries.includes(entry)) {
+    return { disposition: 'destroy', reason: 'Global destroy list' };
+  }
+  if (global.sellEntries.includes(entry)) {
+    if ((item.sellPrice ?? 0) > 0) return { disposition: 'sell', reason: 'Global sell list' };
+    return { disposition: 'destroy', reason: 'Global sell list (no vendor value)' };
+  }
+
+  // Quality auto-sell/destroy must not eat the arrows, the food, the mats or the profession tool
+  // the next pull needs. The category list is the one gate the vendor's Sell All shares.
+  {
+    const cat = protectedCategoryFor(
+      item,
+      effectiveJunkRules(global, character).protectCategories,
+      protectLookupFor(ctx.ds),
+    );
+    if (cat) return { disposition: 'keep', reason: junkProtectCategoryLabel(cat) };
+  }
+
+  // Auto-DE owns disenchantable non-upgrades when that feature would accept them.
+  const q = (item.quality ?? 0) as number;
+  const isUpgrade = item.slot != null && q >= 1 && (
+    ctx.upgradeEntries
+      ? ctx.upgradeEntries.has(entry)
+      : isUpgradeForParty(
+        entry,
+        ctx.player,
+        ctx.playerInv,
+        ctx.playerEquipOpts,
+        ctx.companions,
+        ctx.ds,
+      )
+  );
+  if (isUpgrade) {
+    return {
+      disposition: 'keep',
+      reason: ctx.companions.length > 0 ? 'Upgrade for you or a companion' : 'Upgrade for you',
+    };
+  }
+
+  // Gate before the call: reading ctx.enchanters builds a companionCharacter per raid member
+  // (16.6 ms at 39), and canAutoDisenchantEntry returns on !cfg.enabled as its first line.
+  if (ctx.deCfg.enabled) {
+    const de = canAutoDisenchantEntry(
+      entry,
+      ctx.deCfg,
+      ctx.player,
+      ctx.playerInv,
+      ctx.playerEquipOpts,
+      ctx.companions,
+      ctx.enchanters,
+      ctx.ds,
+      ctx.questProtected,
+      ctx.upgradeEntries,
+    );
+    if (de.ok) return { disposition: 'keep', reason: 'Auto-disenchant claims' };
+  }
+
+  const rules = effectiveJunkRules(global, character);
+  const qKey: JunkQuality = q >= 0 && q <= 4 ? (q as JunkQuality) : 4;
+  if (rules.sellQuality[qKey] && (item.sellPrice ?? 0) > 0) {
+    return { disposition: 'sell', reason: 'Sell by quality' };
+  }
+  if (rules.destroyQuality[qKey]) {
+    return { disposition: 'destroy', reason: 'Destroy by quality' };
+  }
+
+  return { disposition: 'keep', reason: 'No filter matched' };
+}
+
+/** Unique bag entries matching a disposition. */
+export function bagEntriesWithDisposition(
+  inv: Inventory,
+  ctx: JunkEvalContext,
+  want: JunkDisposition,
+): number[] {
+  const seen = new Set<number>();
+  const out: number[] = [];
+  for (const stk of inv.stacks) {
+    if (seen.has(stk.item)) continue;
+    seen.add(stk.item);
+    if (dispositionForEntry(stk.item, ctx).disposition === want) out.push(stk.item);
+  }
+  return out;
+}

package/src/domain/items/keyring.ts

@@ -0,0 +1,131 @@
+// Keyring — a separate unbounded container for BagFamily KEYS items, so keys never flood backpack
+// slots. The classic client grows 4→8→12 by level; we keep it unbounded. Cite: Player.cpp ~8613.
+
+import type { ItemDef } from '../../data/schema.ts';
+import type { Inventory, ItemStack } from './inventory.ts';
+import {
+  addInstance,
+  addItem,
+  countItem,
+  emptyInventory,
+  removeItem,
+  takeStack,
+} from './inventory.ts';
+import type { ItemInstance } from './itemInstance.ts';
+import { hasIdentity } from './itemInstance.ts';
+
+/** ItemPrototype.h BagFamily KEYS. */
+export const BAG_FAMILY_KEYS = 9;
+
+/** ItemPrototype.h ITEM_CLASS_KEY (many keys; not exclusive — see isKeyItem). */
+export const ITEM_CLASS_KEY = 13;
+
+// True when the item belongs on the keyring, by BagFamily KEYS only. Class 13 alone is wrong —
+// Defias Gunpowder and Soft-shelled Clam share that class.
+export function isKeyItem(item: ItemDef | null | undefined): boolean {
+  if (!item) return false;
+  return item.bagFamily === BAG_FAMILY_KEYS;
+}
+
+/** Count of a given entry across keyring stacks. */
+export function countKeyring(keyring: Inventory, entry: number): number {
+  return countItem(keyring, entry);
+}
+
+// Pull every key stack out of a bag inventory into the keyring. Non-keys stay in bags. Used on save migrate
+// and after bulk adds. Pure. Preserves instance identity via addInstance when present.
+export function migrateKeysToKeyring(
+  bags: Inventory,
+  keyring: Inventory,
+  itemDef: (entry: number) => ItemDef | undefined,
+): { bags: Inventory; keyring: Inventory; moved: number } {
+  let nextBags = bags;
+  let nextKey = keyring;
+  let moved = 0;
+  // Walk a snapshot of indices so removals stay stable.
+  const snapshot = nextBags.stacks.map((s, i) => ({ s, i }));
+  // Remove from the end so earlier indices stay valid when we re-scan… easier:
+  // rebuild bags without keys.
+  const keep: ItemStack[] = [];
+  for (const s of nextBags.stacks) {
+    const def = itemDef(s.item);
+    if (isKeyItem(def)) {
+      const maxStack = Math.max(1, def?.stackable ?? 1);
+      if (hasIdentity(s)) nextKey = addInstance(nextKey, s, maxStack);
+      else nextKey = addItem(nextKey, s.item, s.count, maxStack);
+      moved += s.count;
+    } else {
+      keep.push({ ...s });
+    }
+  }
+  nextBags = { stacks: keep };
+  return { bags: nextBags, keyring: nextKey, moved };
+}
+
+// Add a key quantity into the keyring (always succeeds — unbounded). Non-keys are rejected (caller should
+// use bags). Pure.
+export function addToKeyring(
+  keyring: Inventory,
+  entry: number,
+  count: number,
+  def: ItemDef | undefined,
+  instance?: ItemInstance,
+): Inventory {
+  if (count <= 0) return keyring;
+  const maxStack = Math.max(1, def?.stackable ?? 1);
+  if (instance && hasIdentity(instance)) {
+    return addInstance(keyring, { ...instance, item: entry, count }, maxStack);
+  }
+  return addItem(keyring, entry, count, maxStack);
+}
+
+/** Remove up to `count` of `entry` from the keyring. Pure. Returns [newKeyring, removedCount]. */
+export function removeFromKeyring(
+  keyring: Inventory,
+  entry: number,
+  count: number,
+): [Inventory, number] {
+  return removeItem(keyring, entry, count);
+}
+
+/** Take the stack at index (for destroy / move). Pure. */
+export function takeKeyringStack(
+  keyring: Inventory,
+  index: number,
+  count: number,
+): [Inventory, ItemInstance | null] {
+  return takeStack(keyring, index, count);
+}
+
+export function emptyKeyring(): Inventory {
+  return emptyInventory();
+}
+
+// Read-only union of bags, keyring and mailbox overflow, for "do I own this?" questions: the
+// keyring broke every gate that asked countItem(inventory, key). Counting only, never written to.
+export function ownedInventory(
+  bags: Inventory,
+  keyring: Inventory | undefined,
+  overflow?: Inventory,
+): Inventory {
+  const extra: ItemStack[] = [];
+  if (keyring && keyring.stacks.length > 0) extra.push(...keyring.stacks);
+  if (overflow && overflow.stacks.length > 0) extra.push(...overflow.stacks);
+  if (extra.length === 0) return bags;
+  return { ...bags, stacks: [...bags.stacks, ...extra] };
+}
+
+// Spend `count` of `entry` from the bags first, then the keyring, returning how many were actually
+// removed. A door key that had migrated to the keyring was being consumed from the bags, i.e. not.
+export function spendOwned(
+  bags: Inventory,
+  keyring: Inventory | undefined,
+  entry: number,
+  count: number,
+): { bags: Inventory; keyring: Inventory; removed: number } {
+  const keys = keyring ?? emptyInventory();
+  const [nextBags, fromBags] = removeItem(bags, entry, count);
+  if (fromBags >= count) return { bags: nextBags, keyring: keys, removed: fromBags };
+  const [nextKeys, fromKeys] = removeItem(keys, entry, count - fromBags);
+  return { bags: nextBags, keyring: nextKeys, removed: fromBags + fromKeys };
+}