azeroth-shell 0.0.0-stage → 0.1.0

package/src/domain/items/bank.ts

@@ -0,0 +1,162 @@
+// A personal bank: storage separate from the backpack. Pure — every op transfers between two
+// Inventory values. Bank bag slots must be PURCHASED one at a time before a bag can go in.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { Inventory } from './inventory.ts';
+import { addItem, addInstance, removeItem, takeStack, transferItem, canFit, canFitInstance, countItem, usedSlots, BACKPACK_SLOTS } from './inventory.ts';
+import { copyInstance } from './itemInstance.ts';
+
+// WoW's default bank window size, the base grid before any bank bags. CMaNGOS BANK_SLOT_ITEM_START
+// 39..63 is 24; we keep 28 for the existing Phonecraft grid, which is not DBC-driven.
+export const BANK_SLOTS = 28;
+
+// How many bank bag slots can ever be bought. Player.h comments BankBagSlots as 7 and purchase is
+// sequential via CMSG_BUY_BANK_SLOT; we keep 7 to match BANK_BAG_SLOT_COSTS.
+export const MAX_BANK_BAG_SLOTS = 7;
+
+// Copper price to unlock the Nth bank bag slot, indexed by how many you already own, in the
+// CMaNGOS purchase order. Values are BankBagSlotPrices.dbc-dependent — do not invent.
+export const BANK_BAG_SLOT_COSTS: readonly number[] = [
+  10_00, 1_00_00, 10_00_00, 25_00_00, 25_00_00, 25_00_00, 25_00_00,
+];
+
+// A bank's purchased bag slots: one entry per bought slot, holding the bag's item entry or null.
+// Its length IS the number owned. Plain data, so it serializes straight into the save.
+export type BankBags = (number | null)[];
+
+// Total bank capacity: the base BANK_SLOTS grid plus the bagSlots of every bag in a purchased
+// slot. Data-driven from the item's own bagSlots, never hardcoded.
+export function bankCapacity(bankBags: BankBags, ds: DataStore): number {
+  let cap = BANK_SLOTS;
+  for (const entry of bankBags) {
+    const it = entry != null ? ds.item(entry) : undefined;
+    if (it?.slot === 'bag') cap += it.bagSlots ?? 0;
+  }
+  return cap;
+}
+
+/** The cost to buy the next bank bag slot, or null if all slots are already owned. */
+export function nextBankBagSlotCost(bankBags: BankBags): number | null {
+  if (bankBags.length >= MAX_BANK_BAG_SLOTS) return null;
+  return BANK_BAG_SLOT_COSTS[bankBags.length] ?? BANK_BAG_SLOT_COSTS[BANK_BAG_SLOT_COSTS.length - 1];
+}
+
+export interface TransferResult {
+  ok: boolean;
+  reason?: string;
+  inventory: Inventory;
+  bank: Inventory;
+  moved: number;
+}
+
+const fail = (reason: string, inventory: Inventory, bank: Inventory): TransferResult =>
+  ({ ok: false, reason, inventory, bank, moved: 0 });
+
+/** Move up to `qty` of an item from the backpack into the bank (bank space permitting). */
+export function deposit(inv: Inventory, bank: Inventory, item: number, qty: number, maxStack: number, bankCap: number = BANK_SLOTS): TransferResult {
+  if (qty < 1) return fail('Invalid quantity', inv, bank);
+  const n = Math.min(qty, countItem(inv, item));
+  if (n <= 0) return fail("You don't have that", inv, bank);
+  if (!canFit(bank, item, n, maxStack, bankCap)) return fail('Your bank is full', inv, bank);
+  const moved = transferItem(inv, bank, item, n, maxStack, bankCap);
+  if (moved.moved !== n) return fail('Could not move that', inv, bank);
+  return { ok: true, inventory: moved.from, bank: moved.to, moved: moved.moved };
+}
+
+/** Move up to `qty` of an item from the bank into the backpack (bag space permitting). */
+export function withdraw(inv: Inventory, bank: Inventory, item: number, qty: number, maxStack: number, cap: number = BACKPACK_SLOTS): TransferResult {
+  if (qty < 1) return fail('Invalid quantity', inv, bank);
+  const n = Math.min(qty, countItem(bank, item));
+  if (n <= 0) return fail("It's not in your bank", inv, bank);
+  if (!canFit(inv, item, n, maxStack, cap)) return fail('Your bags are full', inv, bank);
+  const moved = transferItem(bank, inv, item, n, maxStack, cap);
+  if (moved.moved !== n) return fail('Could not move that', inv, bank);
+  return { ok: true, inventory: moved.to, bank: moved.from, moved: moved.moved };
+}
+
+/** Move up to `qty` from the *specific stack* at `slotIndex` in the backpack into the bank
+ *  (Wave Q P1: the moved instance keeps its full identity). */
+export function depositStack(inv: Inventory, bank: Inventory, slotIndex: number, qty: number, maxStack: number, bankCap: number = BANK_SLOTS): TransferResult {
+  if (qty < 1) return fail('Invalid quantity', inv, bank);
+  if (slotIndex < 0 || slotIndex >= inv.stacks.length) return fail('Invalid slot', inv, bank);
+  const src = inv.stacks[slotIndex];
+  const item = src.item;
+  const n = Math.min(qty, src.count);
+  if (n <= 0) return fail("You don't have that", inv, bank);
+  if (!canFitInstance(bank, copyInstance(src, n), maxStack, bankCap)) return fail('Your bank is full', inv, bank);
+  const [inventory, taken] = takeStack(inv, slotIndex, n);
+  return { ok: true, inventory, bank: taken ? addInstance(bank, taken, maxStack) : bank, moved: taken ? taken.count : 0 };
+}
+
+/** Move up to `qty` from the *specific stack* at `slotIndex` in the bank into the backpack
+ *  (Wave Q P1: the moved instance keeps its full identity). */
+export function withdrawStack(inv: Inventory, bank: Inventory, slotIndex: number, qty: number, maxStack: number, cap: number = BACKPACK_SLOTS): TransferResult {
+  if (qty < 1) return fail('Invalid quantity', inv, bank);
+  if (slotIndex < 0 || slotIndex >= bank.stacks.length) return fail('Invalid slot', inv, bank);
+  const src = bank.stacks[slotIndex];
+  const item = src.item;
+  const n = Math.min(qty, src.count);
+  if (n <= 0) return fail("It's not in your bank", inv, bank);
+  if (!canFitInstance(inv, copyInstance(src, n), maxStack, cap)) return fail('Your bags are full', inv, bank);
+  const [nextBank, taken] = takeStack(bank, slotIndex, n);
+  return { ok: true, inventory: taken ? addInstance(inv, taken, maxStack) : inv, bank: nextBank, moved: taken ? taken.count : 0 };
+}
+
+export interface BuySlotResult {
+  ok: boolean;
+  reason?: string;
+  bankBags: BankBags;
+  cost: number;
+}
+
+/** Purchase the next bank bag slot (an empty slot appended). Gold is deducted by the caller. */
+export function buyBankBagSlot(bankBags: BankBags, gold: number): BuySlotResult {
+  const cost = nextBankBagSlotCost(bankBags);
+  if (cost == null) return { ok: false, reason: 'All bank bag slots are bought', bankBags, cost: 0 };
+  if (gold < cost) return { ok: false, reason: 'Not enough money', bankBags, cost };
+  return { ok: true, bankBags: [...bankBags, null], cost };
+}
+
+export interface BagSlotResult {
+  ok: boolean;
+  reason?: string;
+  inventory: Inventory;
+  bankBags: BankBags;
+}
+
+const stack = (ds: DataStore, entry: number): number => ds.item(entry)?.stackable ?? 1;
+
+// Slot a bag from the backpack into purchased bank bag slot `slotIndex`, swapping any bag already
+// there back. Rejects a non-bag, an unpurchased slot, or a shrink that would overflow the bank.
+export function equipBankBag(inv: Inventory, bank: Inventory, bankBags: BankBags, ds: DataStore, entry: number, slotIndex: number): BagSlotResult {
+  const reject = (reason: string): BagSlotResult => ({ ok: false, reason, inventory: inv, bankBags });
+  if (slotIndex < 0 || slotIndex >= bankBags.length) return reject('That bank bag slot is locked');
+  const it = ds.item(entry);
+  if (it?.slot !== 'bag') return reject('That is not a bag');
+  if (countItem(inv, entry) <= 0) return reject("You don't have that bag");
+
+  let inventory = removeItem(inv, entry, 1)[0];
+  const bags = [...bankBags];
+  const displaced = bags[slotIndex];
+  if (displaced != null) inventory = addItem(inventory, displaced, 1, stack(ds, displaced));
+  bags[slotIndex] = entry;
+
+  // Swapping in a smaller bag shrinks capacity; block it if the bank would overflow.
+  if (usedSlots(bank) > bankCapacity(bags, ds)) return reject('Not enough room - that bag is too small for what the bank holds');
+  return { ok: true, inventory, bankBags: bags };
+}
+
+// Remove the bag in purchased bank bag slot `slotIndex`, returning it to the backpack. Rejects if the bags
+// have no room for it, or if losing its slots would overflow the bank.
+export function unequipBankBag(inv: Inventory, bank: Inventory, bankBags: BankBags, ds: DataStore, slotIndex: number, invCap: number = BACKPACK_SLOTS): BagSlotResult {
+  const reject = (reason: string): BagSlotResult => ({ ok: false, reason, inventory: inv, bankBags });
+  if (slotIndex < 0 || slotIndex >= bankBags.length) return reject('That bank bag slot is locked');
+  const entry = bankBags[slotIndex];
+  if (entry == null) return reject('That slot is empty');
+  if (!canFit(inv, entry, 1, stack(ds, entry), invCap)) return reject('Your bags are full');
+
+  const bags = [...bankBags];
+  bags[slotIndex] = null;
+  if (usedSlots(bank) > bankCapacity(bags, ds)) return reject('That bag is holding too much - free up bank space first');
+  return { ok: true, inventory: addItem(inv, entry, 1, stack(ds, entry)), bankBags: bags };
+}

package/src/domain/items/consumableFamily.ts

@@ -0,0 +1,205 @@
+// Consumable RANK LADDERS — "healing potion", not "Minor Healing Potion", so a rotation row binds
+// a FAMILY resolved against the bags at use time. The key is derived by stripping rank adjectives.
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { ItemDef } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import type { Inventory } from './inventory.ts';
+import { countItem } from './inventory.ts';
+import { isWeaponImbueItem } from '../professions/weaponImbueHand.ts';
+
+/** SPELL_EFFECT_ENERGIZE. Cite: SharedDefines.h SpellEffects; SpellEffects.cpp EffectEnergize. */
+const SPELL_EFFECT_ENERGIZE = 30;
+
+// Which Powers index a restore_power consumable actually fills: the bake's own stamp first, else the
+// use-spell — its energize effect, then the raw miscValue for a thin row. Thistle Tea is energy, and
+// reading it as mana pays a rogue nothing (or, before the pool gate, paid them the wrong bar).
+export function restoredPowerTypeIndex(it: ItemDef, ds: DataStore): number | null {
+  if (it.useInCombat?.powerType != null) return it.useInCombat.powerType | 0;
+  const spellId = it.useSpell ?? it.useInCombat?.spellId;
+  if (spellId == null) return null;
+  const sp = ds.spell(spellId);
+  if (!sp) return null;
+  for (const e of sp.effects ?? []) {
+    if (e.kind === 'energize') return e.powerType | 0;
+    if (e.kind === 'restore_power' && e.powerType != null) return e.powerType | 0;
+  }
+  for (const r of sp.rawEffects ?? []) {
+    if ((r.effect | 0) === SPELL_EFFECT_ENERGIZE) return r.miscValue | 0;
+  }
+  return null;
+}
+
+/** What a consumable DOES. Two items only share a ladder when they share this. */
+export type ConsumableRole = 'restore_health' | 'restore_power' | 'apply_buff' | 'weapon_imbue';
+
+// Rank adjectives Classic uses on consumable ladders, read off the item names themselves: Minor to
+// Major, Rough to Dense, Weak/Strong, the level-60 one-offs, and Combat / Discolored.
+const RANK_WORDS = [
+  'minor', 'lesser', 'greater', 'superior', 'major', 'mighty', 'strong', 'weak',
+  'rough', 'coarse', 'heavy', 'solid', 'dense',
+  'elemental', 'consecrated', 'brilliant', 'blessed', 'discolored', 'combat',
+  'small', 'large', 'giant',
+];
+const RANK_RE = new RegExp(`\\b(${RANK_WORDS.join('|')})\\b`, 'g');
+
+// The other rank marker Classic uses: a trailing numeral ("Instant Poison VI", "Scroll of Agility
+// IV"). 34 of the 238 consumables carry one, and every one of them is a rank of the name before it.
+const RANK_NUMERAL_RE = /\s+(?:i{1,3}|iv|vi{0,3}|ix|xi{0,2}|x)$/;
+
+/** Rank-free remainder of an item name, lowercased ("Elixir of Greater Agility" → "elixir of agility"). */
+export function rankFreeItemName(name: string): string {
+  return name.toLowerCase()
+    .replace(RANK_RE, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(RANK_NUMERAL_RE, '');
+}
+
+/** What this consumable does, or null when it is not a usable consumable at all. */
+export function consumableRoleOf(it: ItemDef | undefined, ds: DataStore): ConsumableRole | null {
+  if (!it) return null;
+  // Equippable on-use gear only works while worn — that is combatItems' job, not a ladder.
+  if (it.slot != null) return null;
+  if (isWeaponImbueItem(it, ds)) return 'weapon_imbue';
+  const eff = it.useInCombat?.effect;
+  if (eff === 'restore_health' || eff === 'restore_power') return eff;
+  if (it.useBuff) return 'apply_buff';
+  return null;
+}
+
+// Ladder key for one item, or null when it has no consumable role. Two items in the same family are the
+// same consumable at different ranks.
+export function consumableFamilyKey(it: ItemDef | undefined, ds: DataStore): string | null {
+  const role = consumableRoleOf(it, ds);
+  if (!role || !it) return null;
+  const base = rankFreeItemName(it.name);
+  if (!base) return null;
+  return `${it.itemClass ?? -1}/${it.itemSubclass ?? -1}/${role}/${base}`;
+}
+
+/** Display label for a family key — the ladder's own name, title-cased ("Healing Potion"). */
+export function consumableFamilyLabel(family: string): string {
+  const base = family.split('/').slice(3).join('/');
+  const small = new Set(['of', 'the', 'and']);
+  return base
+    .split(' ')
+    .map((w, i) => (i > 0 && small.has(w) ? w : w.charAt(0).toUpperCase() + w.slice(1)))
+    .join(' ');
+}
+
+interface FamilyIndex {
+  /** Item count the index was built at — the lazy catalog attach invalidates it. */
+  n: number;
+  byFamily: Map<string, ItemDef[]>;
+}
+
+const indexCache = new WeakMap<DataStore, FamilyIndex>();
+
+/** Every catalog member of each family, lowest itemLevel first. Cached per DataStore. */
+function familyIndex(ds: DataStore): Map<string, ItemDef[]> {
+  const all = ds.items();
+  const hit = indexCache.get(ds);
+  if (hit && hit.n === all.length) return hit.byFamily;
+  const byFamily = new Map<string, ItemDef[]>();
+  for (const it of all) {
+    if (it.notObtainable) continue;
+    const key = consumableFamilyKey(it, ds);
+    if (!key) continue;
+    const list = byFamily.get(key);
+    if (list) list.push(it);
+    else byFamily.set(key, [it]);
+  }
+  for (const list of byFamily.values()) {
+    // Ascending, so the last usable member is the best rank. itemLevel is the ladder, with quality
+    // then requiredLevel breaking real ties (Blessed Wizard Oil beats Brilliant at itemLevel 55).
+    list.sort((a, b) =>
+      (a.itemLevel ?? 0) - (b.itemLevel ?? 0)
+      || (a.quality ?? 0) - (b.quality ?? 0)
+      || (a.requiredLevel | 0) - (b.requiredLevel | 0)
+      // Fully tied ranks: the LOWER entry is the canonical one, so it sorts last and wins
+      // (Superior Healing Potion 3928 over the identical PvP-reward Combat Healing Potion 18839).
+      || b.entry - a.entry);
+  }
+  indexCache.set(ds, { n: all.length, byFamily });
+  return byFamily;
+}
+
+/** Catalog members of a family, lowest rank first. Empty for an unknown key. */
+export function consumableFamilyMembers(family: string, ds: DataStore): readonly ItemDef[] {
+  return familyIndex(ds).get(family) ?? [];
+}
+
+/** The family this entry belongs to, or null. */
+export function consumableFamilyOfEntry(entry: number, ds: DataStore): string | null {
+  return consumableFamilyKey(ds.item(entry), ds);
+}
+
+export interface BestFamilyOpts {
+  /** Owner of the item — gates requiredLevel and the engineering-device skill check. */
+  char: Character;
+  /** Bags to prefer. Omitted (or empty of this family) falls back to the catalog. */
+  inventory?: Inventory;
+}
+
+// Level-legal for this character. requiredLevel is the only gate — useInCombat.reqLevel is the
+// spell's own level and gating on it locked a level 20 out of the potion Classic sells at 12.
+function usableBy(it: ItemDef, char: Character): boolean {
+  return (it.requiredLevel | 0) <= char.level;
+}
+
+// Best rank of `family` for this character: the highest-itemLevel member they can use, out of the BAGS when
+// they carry any, else out of the catalog so the row is still visible (and inert) while they carry none.
+export function bestFamilyItem(
+  family: string,
+  ds: DataStore,
+  opts: BestFamilyOpts,
+): ItemDef | null {
+  const members = consumableFamilyMembers(family, ds);
+  if (!members.length) return null;
+  let carried: ItemDef | null = null;
+  let catalog: ItemDef | null = null;
+  // members is ascending by itemLevel, so the last match in each bucket is the best.
+  for (const it of members) {
+    if (!usableBy(it, opts.char)) continue;
+    catalog = it;
+    if (opts.inventory && countItem(opts.inventory, it.entry) > 0) carried = it;
+  }
+  return carried ?? catalog;
+}
+
+// Best rank of `family` the character actually CARRIES, or null. This is the use-time resolve — a rotation
+// row fires on what is in the bag, not on what it was built with.
+export function bestCarriedFamilyItem(
+  family: string,
+  ds: DataStore,
+  char: Character,
+  inventory: Inventory | undefined,
+): ItemDef | null {
+  if (!inventory) return null;
+  let best: ItemDef | null = null;
+  for (const it of consumableFamilyMembers(family, ds)) {
+    if (!usableBy(it, char)) continue;
+    if (countItem(inventory, it.entry) <= 0) continue;
+    best = it;
+  }
+  return best;
+}
+
+// Best rank of `family` out of a list of CARRIED entries — the live-session form, where the kit is
+// `session.items()` / `unitItems(side)` rather than an Inventory object.
+export function bestCarriedFamilyEntry(
+  family: string,
+  carried: readonly number[],
+  char: Character,
+  ds: DataStore,
+): number | null {
+  if (!carried.length) return null;
+  const have = new Set(carried);
+  let best: number | null = null;
+  for (const it of consumableFamilyMembers(family, ds)) {
+    if (!have.has(it.entry) || !usableBy(it, char)) continue;
+    best = it.entry;
+  }
+  return best;
+}

package/src/domain/items/craftUpgrades.ts

@@ -0,0 +1,83 @@
+// Who in the roster would wear a craft's product. One findUpgrades pass PER (body, product): a bag
+// holding every product flags 88 of 99, per item 99 (src/dev/probe-craft-upgrade-cost.mjs).
+
+import type { DataStore } from '../../data/dataStore.ts';
+import type { EquipSlot, ItemDef } from '../../data/schema.ts';
+import type { Character } from '../character/character.ts';
+import type { EquipOpts } from './equipment.ts';
+import { findUpgrades, type CompareScale } from './equipmentHelper.ts';
+import { canEquipItem } from './itemRestrictions.ts';
+
+/** A body a crafted piece could land on: you, a squad bot, a bench bot, a raid seat. */
+export interface UpgradeBody {
+  /** null = the player. */
+  id: string | null;
+  name: string;
+  cls: number;
+  char: Character;
+  opts?: EquipOpts;
+}
+
+/** One wearer of one product, with the slot it lands in and how far it beats what they wear. */
+export interface CraftWearer {
+  id: string | null;
+  name: string;
+  cls: number;
+  slot: EquipSlot;
+  /** Entry currently in that slot, absent when the slot is empty. */
+  currentEntry?: number;
+  /** Score over what they wear now: weightscale points, or the quality/ilvl fallback. */
+  delta: number;
+  scale: CompareScale;
+}
+
+/** Every roster body each product upgrades, best delta first. Unknown or unequippable ids skip. */
+export function craftUpgradeWearers(
+  products: Iterable<number>,
+  bodies: readonly UpgradeBody[],
+  ds: DataStore,
+): Map<number, CraftWearer[]> {
+  const defs: ItemDef[] = [];
+  for (const entry of new Set(products)) {
+    let it: ItemDef | undefined;
+    try {
+      it = ds.item(entry);
+    } catch {
+      continue;
+    }
+    if (it?.slot) defs.push(it);
+  }
+  const out = new Map<number, CraftWearer[]>();
+  for (const b of bodies) {
+    for (const it of defs) {
+      // Level / class / proficiency gate first: most (body, product) pairs never reach the scorer.
+      if (!canEquipItem(b.char, it, ds)) continue;
+      let ups: ReturnType<typeof findUpgrades>;
+      try {
+        ups = findUpgrades(b.char, { stacks: [{ item: it.entry, count: 1 }] }, ds, b.opts);
+      } catch {
+        continue;
+      }
+      for (const u of ups) {
+        // bestHandLoadout may also move a WORN piece between sockets; only the probe entry is news.
+        if (u.entry !== it.entry) continue;
+        const row: CraftWearer = {
+          id: b.id,
+          name: b.name,
+          cls: b.cls,
+          slot: u.targetSlot,
+          ...(u.currentEntry != null ? { currentEntry: u.currentEntry } : {}),
+          delta: u.valueDelta,
+          scale: u.scale ?? 'spec',
+        };
+        const hit = out.get(it.entry);
+        if (hit) hit.push(row);
+        else out.set(it.entry, [row]);
+      }
+    }
+  }
+  for (const list of out.values()) {
+    list.sort((a, b) => b.delta - a.delta || a.name.localeCompare(b.name));
+  }
+  return out;
+}

package/src/domain/items/createItem.ts

@@ -0,0 +1,93 @@
+// Create-time random property roll. Pure, injected Rng only. Clone, mail and trade pass
+// opts.preserve so a rolled suffix never re-rolls. Cite: Item.cpp:639 / :958.
+
+import type { ItemDef, RandomPropertyDef } from '../../data/schema.ts';
+import type { Rng } from '../../engine/core/rng.ts';
+import type { ItemInstance } from './itemInstance.ts';
+import { copyInstance } from './itemInstance.ts';
+import {
+  generateItemRandomPropertyId,
+  type RandomEnchRow,
+} from './itemRandomProps.ts';
+import { stampUniqueFromDef } from './itemRestrictions.ts';
+
+/** Minimal data surface for create-time minting. `DataStore` satisfies this. */
+export interface CreateItemData {
+  item(entry: number): ItemDef | undefined;
+  itemEnchantmentTemplate(entry: number): readonly RandomEnchRow[] | undefined;
+  itemRandomProperty?(id: number): RandomPropertyDef | undefined;
+}
+
+export interface CreateItemOpts {
+  // Force a property id (tests / GM). Skips the weighted pool roll. 0 (or missing from the property table
+  // when `lookupProp` is set) → no suffix.
+  forcedPropId?: number;
+  // Clone path (mail / trade / AH delivery): copy identity fields; never re-roll. `item` / `count` on the
+  // partial are ignored in favour of the call arguments.
+  preserve?: Partial<ItemInstance>;
+  // Validate a rolled/forced id against baked `ItemRandomProperties`. Missing id → store 0 / omit (CMaNGOS
+  // lookup fail → 0). Prefer this over casting the data bundle when DataStore has no accessor yet.
+  lookupProp?: (id: number) => RandomPropertyDef | undefined;
+}
+
+/** 0 / absent when no property; drops ids the property table does not know. */
+function sanitizePropId(
+  id: number,
+  lookupProp?: (id: number) => RandomPropertyDef | undefined,
+): number {
+  if (id <= 0) return 0;
+  if (lookupProp && lookupProp(id) == null) return 0;
+  return id;
+}
+
+// Mint a new item instance at economy entry — loot, vendor, craft, quest, AHbot. preserve copies
+// identity, forcedPropId wins over the pool roll, and plain mats stay { item, count }.
+export function createItemInstance(
+  entry: number,
+  count: number,
+  ds: CreateItemData,
+  rng: Rng,
+  opts?: CreateItemOpts,
+): ItemInstance {
+  const n = count > 0 ? count : 0;
+  const def = ds.item(entry);
+  const lookupProp = opts?.lookupProp ?? (ds.itemRandomProperty
+    ? (id) => ds.itemRandomProperty!(id)
+    : undefined);
+
+  // Clone / mail / trade: preserve existing identity fields; do not re-roll.
+  // Still stamp unique from def when signals exist (idempotent if already set).
+  if (opts?.preserve) {
+    return stampUniqueFromDef(
+      copyInstance({ item: entry, count: n, ...opts.preserve }, n),
+      def,
+    );
+  }
+
+  // Forced id (tests / GM override) — still validate against the property table.
+  if (opts?.forcedPropId != null) {
+    const id = sanitizePropId(opts.forcedPropId, lookupProp);
+    const out: ItemInstance = { item: entry, count: n };
+    if (id > 0) out.randomPropertyId = id;
+    return stampUniqueFromDef(out, def);
+  }
+
+  let randomPropertyId: number | undefined;
+
+  const poolKey = def?.randomProperty;
+  if (poolKey != null && poolKey > 0) {
+    const raw = ds.itemEnchantmentTemplate(poolKey);
+    const rows = Array.isArray(raw) ? raw : [];
+    const rolled = generateItemRandomPropertyId(rows, rng);
+    const id = sanitizePropId(rolled, lookupProp);
+    if (id > 0) randomPropertyId = id;
+  }
+
+  const out: ItemInstance = { item: entry, count: n };
+  if (randomPropertyId != null && randomPropertyId > 0) {
+    out.randomPropertyId = randomPropertyId;
+  }
+  // Callers decide instance-vs-stack via identityCapable / hasIdentity; minting always returns the LOCK-1
+  // shape (plain mats = entry+count only). FI: stamp unique when def signals unique / uniqueEquipped.
+  return stampUniqueFromDef(out, def);
+}